# archify

> 为 DeepSeek Harness 注入 Archify 技术图 Skill：让 dsh 在对话里读仓库生成五种交互式系统地图（架构/工作流/时序/数据流/生命周期），产出可分享 HTML。

## 元数据

- 作者: [@tt-a1i](https://github.com/tt-a1i)
- 仓库: <https://github.com/tt-a1i/archify.git>
- GitHub: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Star: 13,801
- 主语言: HTML
- License: [MIT](https://spdx.org/licenses/MIT.html)
- 主页: <https://tt-a1i.github.io/archify/>
- Topics: `agent-skills`, `architecture-as-code`, `architecture-diagram`, `claude-skill`, `code-visualization`, `codex`, `coding-agents`, `data-flow-diagram`, `deepseek-harness`, `developer-tools`, `diagram-as-code`, `diagrams`, `diagrams-as-code`, `dsh-plugin`, `mermaid-alternative`, `opencode`, `sequence-diagram`, `software-architecture`, `system-design`, `text-to-diagram`
- Fork: 1,013
- Open Issues: 19
- 最后推送: 2026-08-17T15:47:26.000Z
- 加入目录: 2026-08-17T00:00:00.000Z

## 安装

```bash
dsh plugin --profile web add github:tt-a1i/archify
```

## 百科

## 一句话定位
把 Archify 技术图 Skill 挂到 DeepSeek Harness 上，让 dsh 在聊天里读取代码、产出五种带校验的交互式系统地图（架构/工作流/时序/数据流/生命周期），最终生成可分享的自包含 HTML 文件。

## 核心能力
- 在 dsh 对话里直接说一句话即可让 agent 加载 Archify Skill，按 typed JSON 描述生成并校验图
- 支持五种图类型：组件架构图、CI/CD 类工作流、API 调用时序、数据流与生命周期/状态机
- 生成单个自包含 HTML 文件，内置深浅主题切换、节点搜索、上下游可达路径探查、对比视图与有限动效
- 提供架构 Before/Delta/After 对比模式，可读出新增、删除、变化、移动与重路由等差异事实
- 校验流程在 schema、布局、HTML/SVG、连线、标签-路径间距等多层失败时返回结构化 JSON 修复提示，而不是直接抛错
- 无任何网络请求、无遥测、无原生模块依赖，适配器侧只做文件系统路径解析

## 技术实现
- **语言**: TypeScript-free，纯 ESM JavaScript（Node.js）
- **关键依赖**: `node:module`（createRequire 解析包路径）、`node:path`（拼接 Skill 目录）、`@deepseek-ai/dsh-skill-filesystem`（DSH 内置 Skill provider）
- **架构模式**: 通过 `cordis.patch.yml` 向宿主 DSH 注入 1 个名为 `archify-skill-filesystem` 的 Skill provider（`includeDefaultRoots: false`），由 `bundledSkillDir` JS 表达式把 Skill 根目录锚到当前已安装 npm 包内
- **入口文件**: `integrations/deepseek-harness/lib/index.js`（21 行，导出 `name`、`PACKAGE_NAME`、`resolveArchifySkillRoot`）；实际 Skill 入口是 `archify/bin/archify.mjs`

## 适用场景
DSH 用户在和 agent 对话描述「我想看看这个仓库长什么样」「把这条 CI/CD 流程画出来」「给我一个登录请求的时序图」时，agent 就能加载 Archify Skill 去读仓库、生成 typed JSON、跑校验、产出可直接分享的 HTML。它特别适合做架构评审、PR 前后对比、文档插图这类需要把口头描述固化成可视材料的场景。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6（开发者预览版） | 适配器明确仅在该 DSH 版本上验证，未承诺跨版本兼容 |
| Node.js | ^22.19.0 或 >=24.0.0 | `integrations/deepseek-harness/package.json#engines` 强制；Archify 主工具自身最低 Node 18 |
| 平台 | macOS / Windows / Linux | 跨平台；Windows 下 `lib/index.js` 不依赖 npm/cmd shim，但 Archify 主 CLI 在 Windows 上有专门的 launcher 兼容逻辑（`resolve-cli.mjs`） |
| 原生模块 | 无 | `adapter-security.test.mjs` 强制 lib 不含 `node:http/net/dgram/child_process` 等关键字；Archify 主工具零依赖运行 |

## 安装方式
```bash
dsh plugin --profile web add github:tt-a1i/archify
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `providerName` | 字符串 | 在 DSH 内显示的 Skill 提供者名称，agent 调用时看到的标识 | `archify-plugin`（写死在 `cordis.patch.yml`） |
| `includeDefaultRoots` | 布尔 | 是否同时启用 DSH 内置的默认 Skill 根目录 | `false`（仅加载本插件打包的 Archify Skill，避免污染） |
| `bundledSkillDir` | 路径表达式 | 指向已安装 npm 包内 `skills/` 子目录的绝对路径；通过 `createRequire(baseUrl).resolve('@tt-a1i/archify-dsh/package.json')` 反向解析 | 安装时由 JS 表达式自动计算 |

> 这三项均在 `integrations/deepseek-harness/cordis.patch.yml` 中固化，普通用户无需也不能修改；如需调整，只能 fork 适配器后重新打包。

## 常见问题

**Q: 这个插件是 DeepSeek 官方出品的吗？**

A: 不是。仓库和适配器 README 都明确标注「Community integration」「not an official DeepSeek product」，仅在开发者预览版 `@deepseek-ai/dsh@0.1.0-rc.6` 上验证可用，不代表跨版本稳定承诺。

**Q: 安装之后我怎么调用它？**

A: 在 dsh 对话里直接说「Use the archify skill to map this repository's runtime architecture」或其中文表述，agent 会加载 Skill、按校验流程生成图。Skill 内部调用 `node bin/archify.mjs validate/deliver/preview` 需要 dsh 赋予 shell 权限。

**Q: 生成的图为什么不出现在 dsh Web 的 Produced Files 列表里？**

A: 因为 Archify 通过 shell 写出 HTML/JSON 文件，不会自动进入 Produced Files 通道。需要让 agent 在交付完图后，把生成的 specification JSON 和 HTML 的「精确工作区绝对路径」返回给你，你从工作区里直接打开这些文件。

**Q: 这个适配器会在我电脑上偷偷开端口、上报数据或读我的 key 吗？**

A: 不会。`integrations/deepseek-harness/lib/index.js` 全文件只有 1 个导出函数 `resolveArchifySkillRoot`；仓库测试 `adapter-security.test.mjs` 强制断言该目录不含 `child_process`、`fetch`、`node:http/https/net/dgram`、`setInterval/setTimeout/Worker/cluster`、`telemetry/opentelemetry/otlp`、`process.env.*TOKEN`、`tools.register` 等关键词。没有 telemetry、没有网络请求、没有 `prepare/install/postinstall` 钩子。

**Q: 卸载命令是什么？**

A: 上游 README 写法为 `dsh plugin --profile web remove @tt-a1i/archify-dsh`（按 npm 包名移除）。该命令只会移除适配器和 Skill 注入，不会删掉你之前生成的 HTML/JSON 文件。

**Q: 升级 dsh 之后还能用吗？**

A: 适配器当前仅在开发者预览版 `@deepseek-ai/dsh@0.1.0-rc.6` 上验证，README 明确写「It is not a stable cross-version guarantee」。等 dsh 进入正式版本后需要看适配器是否同步发布新版。

**Q: Archify 适合做实时监控、PR 风险评估、生产部署状态展示吗？**

A: 不适合。Archify 强调「authored facts only」，所有连接、上下游可达范围、架构对比结果都来自用户写入的 typed JSON，不去探测运行时基础设施；生成的图明确不声明风险、爆炸半径、合并安全性或运行影响。

## 上手难度
入门 — 调用方式只是 dsh 对话里加一句「Use the archify skill ...」，用户不需要写 JSON 也不需要记 CLI；Archify Skill 内部会引导 agent 自己读取仓库、生成 typed JSON 并跑校验。

## 已知问题与限制
- 适配器处于 `v0.1.0`，仅在 `@deepseek-ai/dsh@0.1.0-rc.6`（开发者预览版）上验证，不是稳定的跨版本保证
- 生成的 HTML/JSON 不会自动出现在 dsh Web 的 Produced Files 列表里，必须由 agent 返回精确工作区路径后由用户手动打开
- 适配器上游 README 推荐的安装形式是 `dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0`（npm 精确版本），而非从 git 源安装；marketplace 的 `github:tt-a1i/archify` 形式是否可用取决于 dsh 自身的解析器，本仓库测试 `docs-contract.test.mjs` 主动禁止文档里出现 `github:tt-a1i/archify` 的写法
- Archify Skill 主工具本身为 `v2.14.0`，且仍在持续演进（CHANGELOG 显示频繁修复 wide desktop 排版、label 间距等），与适配器版本号是各自独立的两套号
- 适配器不注册原生 render/validate/deliver 工具、不暴露 Web 客户端、不接入 Web Produced Files 通道、不做网络请求或遥测，这意味着所有 Archify 能力必须经由 Skill + shell 调用

---

本文档由 [deepseek-plugin.org](https://deepseek-plugin.org) 自动生成，对应 HTML 页面: [archify](https://deepseek-plugin.org/plugins/tt-a1i/archify)
百度百科由 AI 生成 (模型: `MiniMax-M3`)