duyanta123/arch-doc

English | 简体中文

DSH 技能插件：输入代码库路径，自动生成架构文档（模块职责、依赖关系、入口点、运行方式）。

npm 包名为 dsh-arch-doc（原名 arch-doc 因 npm 防抢注拦截不可用，2026-09-02 改名）；GitHub 仓库名与插件 id 保持 arch-doc，两者指向同一项目。

定位

arch-doc 是架构文档生成插件：扫描器只提取硬事实（语言、目录、依赖、入口点等确定性信息），语义总结由 LLM 按固定模板补充并标注推断。

它回答：

• 这是什么类型的项目（语言 / 框架 / 构建系统 / 仓库类型）？
• 模块怎么划分，各自负责什么？
• 内部 / 外部依赖是什么关系？
• 入口点在哪（CLI / Web / Worker / Scheduler / Library）？
• 怎么安装、开发、构建、测试、运行、部署？

边界：扫描过程只读，不执行目标仓库代码；扫描器零依赖、无子进程、无网络。

安装

作为 DSH 插件（推荐）：

dsh plugin --profile web add "github:duyanta123/arch-doc#v0.1.4"

或从 npm 安装：

npm install dsh-arch-doc

兼容性分层：独立脚本 scripts/arch-profile.mjs 可运行在 Node.js >= 18（无 Node 环境时 runbook 自动降级为 shell 手工探测，结论质量略降但流程完整）；作为 DSH 0.1.5-rc.2 插件验证统一使用 Node.js >= 22.19。运行 npm run test:compat 可执行隔离 profile 的 add、dump-config 和启动 smoke test。

本地开发：profile 的 package.json 加 "arch-doc": "file:<本地路径>/arch-doc"，bundles 数组加 "arch-doc"，然后重启 profile。

快速开始

1. 作为 DSH 技能使用

安装后重启 profile，对 Agent 说：

用 arch-doc 分析 /path/to/repo

技能按 runbook 执行：先跑扫描脚本取事实，再按模板生成文档，写入目标仓库的 docs/ 下（见「输出」）。

2. 作为独立 CLI 使用

node scripts/arch-profile.mjs <repo_path> --probe
node scripts/arch-profile.mjs <repo_path> --scan --max-depth 3
node scripts/arch-profile.mjs <repo_path> --deps
node scripts/arch-profile.mjs <repo_path> --entry
node scripts/arch-profile.mjs <repo_path> --all

CLI 参数

参数	默认	说明
--probe	-	识别项目类型 / 语言 / 构建系统，输出摘要
--scan	-	目录扫描与模块划分（模块职责事实）
--deps	-	内部 / 外部依赖提取
--entry	-	入口点识别（CLI / Web / Worker / Scheduler / Library）
--all	-	依次执行全部阶段，输出完整结果 JSON
--max-depth <N>	3	目录扫描深度（1–10）
--include-dirs <a,b>	-	只分析这些目录（相对 repo_path，逗号分隔）
--exclude-dirs <a,b>	-	额外排除目录（与内置排除目录合并，内置覆盖 node_modules、.venv 等构建产物）
--language <L>	自动	语言提示：python / javascript / typescript / go / java / generic

输出

对目标仓库生成三件套：

文件	用途
docs/ARCHITECTURE.md	结构化架构文档（按 9+1 章固定骨架：概览 / 技术栈 / 目录 / 模块职责 / 依赖关系 / 入口点 / 运行方式 / 关键流程 / 风险点 / 附录）
docs/architecture.json	机器可读的结构化结果
docs/diagrams/module-dependencies.mmd	Mermaid 模块依赖图

完整样例见 examples/sample-output.md：

## 1. 项目概览
- 项目名称：my-app
- 一句话描述：示例项目（Python FastAPI 服务）
- 架构风格：分层
- 仓库类型：monolith

## 2. 技术栈
- 语言：python
- 框架：fastapi、uvicorn
- 构建/运行：docker

安全边界

• 只读扫描：扫描阶段不写入、不修改目标仓库源码，不执行目标仓库代码。
• 零依赖运行：扫描器为单文件 Node 脚本，无第三方依赖、无子进程、无网络访问。
• 产物限定：仅写入 docs/ 下的三个文档产物文件。
• 降级安全：无 Node 环境时 runbook 自动降级为 shell 手工探测，不引入新依赖。

排障

生成的 ARCHITECTURE.md 里 Mermaid 图不渲染？ file:// 协议下浏览器直接打开时，CDN 加载的 mermaid.js 受同源策略限制无法自动渲染；用 Typora 等本地渲染编辑器打开，或把 diagrams/module-dependencies.mmd 内容粘到 mermaid.live 查看。.mmd 源文件语法本身独立有效。

大仓库扫描太慢 / 输出太长？ --max-depth 3 起步，必要时降到 2；确认 --exclude-dirs 覆盖了 node_modules、.venv、构建产物等大目录。

识别不到入口点？ 先跑 --probe 确认项目类型识别正确；混合技术栈仓库以主语言构建文件为准（如 Go+Node 混合，以 go.mod 优先）。

升级 DSH 宿主到 0.1.5 系后旧会话打不开？ Session format V3 迁移不可逆，属宿主行为；升级宿主前请先备份会话日志（见 CHANGELOG.md 0.1.4 条目）。

文档

• docs/architecture-template.md — 输出文档的 9+1 章固定骨架
• docs/scanning-rules.md — 扫描器的确定性规则（语言探测、仓库类型、模块划分、依赖提取、入口点判定、运行方式提取）
• examples/ — 输入与完整输出样例
• CHANGELOG.md — 版本变更记录
• PLUGIN-MAINTENANCE.md — 本仓维护规则

License

MIT