arch-doc：DSH 插件与代码库架构文档生成器

前言¶

在使用 DeepSeek Harness（DSH）进行智能体开发或调试时，让模型快速理解一个陌生代码库的结构是一项基础需求。传统方式依赖阅读文件或手动整理，效率低且容易遗漏关键信息。DSH 生态中的 arch-doc 插件通过“扫描器提取事实 + 模板填充”的模式，自动生成包含模块职责、依赖关系和入口点的架构文档。

插件介绍¶

arch-doc 是由 duyanta123 维护的一个 DSH 技能插件。它的核心作用是分析代码库，并生成结构化的架构文档。该插件通过提取硬事实（如语言、目录、依赖、入口点），结合 LLM 的模板填充，输出一份包含项目类型、模块划分、依赖关系和运行方法的文档。

许可证：MIT
仓库地址：https://github.com/duyanta123/arch-doc
插件目录：https://www.skillhub.cn/plugins/duyanta123/arch-doc

核心功能¶

该插件主要完成以下工作：

硬事实提取：识别项目使用的语言、目录结构、内部与外部依赖以及入口点。
项目检测：判断项目类型（如 CLI/Web/Worker）、构建系统和仓库类型（单体/多模块）。
模块分析：确定模块的划分方式及每个模块的职责。
入口点识别：检测应用是作为 CLI、Web 服务、Worker、Scheduler 还是库运行的。
可视化输出：生成 Mermaid 格式的模块依赖图。
结构化数据：输出 JSON 格式的机器可读分析结果。

安装与启用¶

安装该插件需要使用官方提供的命令。注意，虽然 GitHub 仓库名为 arch-doc，但 npm 包名被反占库名规则修改为 dsh-arch-doc。

1. 作为 DSH 插件安装¶

推荐通过 DSH 的插件管理器安装指定版本：

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

2. 作为 npm 包安装¶

也可以直接通过 npm 安装：

npm install dsh-arch-doc

安装完成后，需要重启对应的 profile 以加载插件。

典型用法¶

安装完成后，可以在 DSH 中通过自然语言指令调用该技能，也可以直接运行独立脚本。

1. 作为 DSH 技能使用¶

在对话中下达指令，让智能体分析指定路径的代码库：

Use arch-doc to analyze /path/to/repo

智能体会执行扫描，提取事实，并生成文档。

2. 作为独立 CLI 运行¶

插件提供了独立的 Node.js 脚本，支持分步执行或全量扫描。

运行全量扫描：

node scripts/arch-profile.mjs <repo_path> --all

分步执行特定任务：

# 仅探测项目类型
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

常用参数：

--max-depth <N>：限制目录扫描深度（1-10），默认为 3。
--language <L>：指定语言提示（python/javascript/typescript/go/java/generic）。
--include-dirs / --exclude-dirs：指定分析或排除的目录。

适用场景与注意¶

适用场景¶

快速上手遗留系统：在接手新项目时，快速生成架构概览。
混合栈项目分析：识别不同语言模块之间的依赖关系。
文档自动化：维护项目文档，确保其与代码结构同步。

注意事项¶

安全边界：
- 扫描过程是只读的，不会执行目标仓库的代码，也不会写入源码。
- 扫描器本身零依赖，不调用子进程，不访问网络。
- 输出仅限于目标仓库下的 docs/ 目录，生成三个文件。
Mermaid 渲染限制：
生成的 Mermaid 图表文件（.mmd）在浏览器通过 file:// 协议打开时可能无法渲染。建议使用 Typora 等本地编辑器，或将源码粘贴到 mermaid.live 等在线工具查看。
混合栈项目：
对于同时包含多种语言的项目，插件会根据构建文件优先级判断主语言（例如 Go+Node 项目中 go.mod 优先级高于 JS 配置文件）。

短结尾¶

arch-doc 作为一个轻量级、零依赖的架构分析工具，通过将扫描逻辑与文档生成逻辑分离，为 DSH 智能体提供了可靠的代码库理解能力。它生成的结构化文档和依赖图，能显著降低代码库的阅读门槛。