前言¶
在 DSH 插件场景里，架构说明、流程说明、时序说明常常需要从代码仓库里整理出来，再交给团队查看和分享。dsh-archify 提供的是一个 agent 技能：用 JSON 规格生成架构图、流程图、时序图、数据流图与生命周期图，并输出独立 HTML。
它的做法是先形成规格文件，再执行校验和交付。下面介绍它的功能、安装方式、典型用法和注意事项。
该插件由 GongYuanCaiJi 维护，许可证为 MIT。它移植自 tt-a1i/archify v2.14.0；官方 DSH 包 @tt-a1i/archify-dsh@0.1.0 与它同源同版本。技能本体 archify/ 与 examples/ 逐字保留，只适配了 dsh 的打包与命名。
定位¶
- 输入：JSON 规格，一个 JSON 规格对应一种图型。
- 输出：独立 HTML，也支持 PNG、SVG、WebM，以及 1200×630 分享卡片。
- 验收：提交前跑
validate，确定性校验给出 9 项验收（showcase）或基础验收（standard）。 - 主题：支持深浅主题；视觉预设包括
classic（默认）、signal-flow、blueprint、editorial。
核心功能¶
五种图型：
architecture
workflow
sequence
dataflow
lifecycle
每个 JSON 规格对应其中一种图型。
可验证交付：
validate
showcase: 9 项验收
standard: 基础验收
提交前跑 validate，用确定性校验给出验收结果。
多格式导出：
HTML
PNG
SVG
WebM
1200×630 分享卡片
Mermaid 输入：
flowchart
sequenceDiagram
stateDiagram
粘贴 Mermaid 内容后，可转为 Archify JSON，再进行美化。
架构对比：
compare
Before / Delta / After
compare 两份快照，输出 Before / Delta / After 三态 HTML。
安装与启用¶
先确认环境要求：
Node.js: ^22.19.0 || >=24.0.0
dsh: 0.1.0-rc.6
确认环境后，从 GitHub 安装：
dsh plugin --profile <你的 profile> add github:GongYuanCaiJi/dsh-archify
安装时会通过 prepare 脚本把 archify/ 暂存为 skills/。如果 pnpm 拦下构建步骤，在 profile 的 pnpm-workspace.yaml 里把本包加进 allowBuilds，再重跑一次：
pnpm-workspace.yaml -> allowBuilds 中加入 dsh-archify
从本地目录安装时，先克隆并安装依赖，再交给 dsh 添加：
git clone https://github.com/GongYuanCaiJi/dsh-archify.git
cd dsh-archify && npm install
dsh plugin --profile <你的 profile> add ../dsh-archify
这里的 npm install 用于触发 prepare 脚本，把技能文件暂存到 skills/。
典型用法¶
让 agent 按名字加载技能：
Use the archify skill to map this repository's runtime architecture.
如果希望得到更完整的交付要求，可以给出这段提示：
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.
After delivery, return the exact workspace paths of the specification JSON and the HTML artifact.
一个示例流程是先写 runtime.architecture.json，再执行校验和交付：
node bin/archify.mjs validate architecture runtime.architecture.json --quality showcase
node bin/archify.mjs deliver architecture runtime.architecture.json runtime.html --quality showcase
经过上面的步骤后，交付 runtime.html。
产物打开注意¶
shell 命令生成的文件不会自动出现在 Web 端的 Produced Files 栏。
需要让 agent 返回规格 JSON 与 HTML 工件的精确工作区路径，再从工作区打开。上游官方 DSH 包同样如此。
安全与许可¶
安全姿态：
- 无遥测
- 无网络客户端
- 无凭据处理
- 无后台服务
- 没有
install/postinstall/preinstall生命周期钩子，仅prepare用于暂存技能文件
许可证为 MIT。
上游 tt-a1i/archify 的版权为：
Copyright (c) 2026 tt-a1i (Archify)
Copyright (c) 2025 Cocoon AI
本移植的版权为：
Copyright (c) 2026 GongYuanCaiJi (dsh port)
插件以当前 dsh 进程权限运行。安装前应检查源码与许可证。
包信息与测试限制¶
包信息如下：
version: 0.1.0
type: module
main: ./lib/index.js
engines.node: ^22.19.0 || >=24.0.0
dsh.bundle.patch: ./cordis.patch.yml
测试限制：scripts/run-skill-tests.mjs 会跳过 19 个无法在移植仓库运行的技能测试，包括：
- 18 个绑定上游仓库根目录网站/发布文件的测试
- 1 个依赖
ajvdevDependency 的generate-validators.test.mjs
卸载¶
卸载命令：
dsh plugin --profile <你的 profile> remove dsh-archify
链接¶
GitHub 仓库：
https://github.com/GongYuanCaiJi/dsh-archify
如需从目录页查找，请在当前使用的 DSH 插件目录中搜索：
dsh-archify
