Gan-lang/dsh-project-handbook

dsh-project-handbook

面向 DeepSeek Harness 的公司级项目交接 / 入职手册生成器 —— 项目交接与新人熟悉文档。

一对命令即可将真实代码仓库转化为一份 Markdown 交接包，新工程师可在第一周直接据此开展工作：

.handover/
├── PROJECT-HANDBOOK.md        # 15 节交接手册（公司项目级）
├── ONBOARDING-CHECKLIST.md    # 第一天 / 第一周检查清单，含签核
├── GLOSSARY.md                # 领域术语 + 内部行话（全面档案）
├── RUNBOOK.md                 # 故障卡片、发布、数据修复（全面）
├── inventory.json / .md       # 所有论断据此核验的事实基础
└── check-report.md            # 质量门禁发现的问题

它与“让模型写个 README”有何不同

- 证据或 待确认。 每条论断都附带 path、path:line 或能证明它的确切命令。仓库无法回答的内容（部署目标、值班轮换、业务规则、某项决策的原因）会写成明确的待解决问题，而非听起来合理的空话。
- 先做确定性扫描。 project-inventory.mjs 遍历仓库并报告语言、清单文件、框架信号、CI 任务及其命令、部署产物、环境变量名、迁移、入口点、测试布局、git 历史与主要作者、技术债标记、已提交的凭据形态文件 —— 外加一份预先计算好的 verifyFirst 缺口清单。
- 真正的质量门禁。 check-handbook.mjs 会拦截缺失章节、占位内容、未填写的占位符、推测性措辞、无引用的 ✅ 标记、引用了不存在的路径、无法解析的链接与锚点、没有任何 package.json 定义的包脚本、粘贴进文档的密钥，以及与清单相矛盾的论断。
- 技术栈感知的侦察。 针对 Java/Spring、Go、Python、Node/TypeScript、前端、数据/AI 及遗留运维项目的侦察手册，会明确告诉 agent 该打开哪些文件、提取哪些事实。
- 构造上即安全。 只读侦察；凭据绝不被打开或引用；生成文档期间不执行构建、迁移、部署或提交。

安装

从 GitHub 安装（当前即可用，无需发布到 npm）：

dsh plugin --profile web add github:Gan-lang/dsh-project-handbook

从 npm 安装 —— 待该包发布到 npm 后：

dsh plugin --profile web add dsh-project-handbook

从本地检出安装：

dsh plugin --profile web add /absolute/path/to/dsh-project-handbook

无论使用哪种来源，最后都要把该 bundle 加入 $DSH_HOME/profiles/web/package.json 中 profile 的有序 bundle 列表：

{
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-project-handbook"]
}
}
}

重启 dsh web。该插件只挂载随包提供的 skill（无宿主服务，无
客户端代码）：cordis.patch.yml 注册了一个 @deepseek-ai/dsh-skill-filesystem
提供程序，其 bundledSkillDir 从已安装的包标识解析而来，
因此该技能会以 project-handbook 出现在会话目录中。

使用

在任意会话中提问：

生成这个项目的交接文档，要公司项目级、新人能直接上手的那种

该技能会：

1. 运行 scripts/project-inventory.mjs（--root . --out .handover/inventory.json）；
2. 读取匹配的技术栈手册以及承载项目故事的代码；
3. 填充 assets/ 中的模板（配置文件 compact / standard / comprehensive）；
4. 运行 scripts/check-handbook.mjs 直到通过，然后完成
references/quality-gate.md 中的人工验收清单；
5. 报告文件、所检查的提交，以及项目负责人必须回答的简短问题列表。

这些脚本是纯 ESM，也可以独立运行：

node skills/project-handbook/scripts/project-inventory.mjs --root . --help
node skills/project-handbook/scripts/check-handbook.mjs .handover/PROJECT-HANDBOOK.md \
--root . --facts .handover/inventory.json --profile standard --report .handover/check-report.md

布局

dsh-project-handbook/
├── cordis.patch.yml                     # 挂载捆绑的技能提供程序
├── lib/index.js                         # 包标识 + 技能根目录解析器
└── skills/project-handbook/
├── SKILL.md                         # 智能体遵循的工作流
├── scripts/project-inventory.mjs    # 仓库侦察 → JSON + Markdown
├── scripts/check-handbook.mjs       # 文档质量门禁
├── references/                      # 证据规则、内容标准、技术栈手册、
│                                    # 凭据规则、质量门禁
└── assets/                          # 待填写的文档模板

要求

Node.js ^22.19.0 || >=24.0.0（无运行时依赖），以及一个
附带 @deepseek-ai/dsh-skill-filesystem 的 DSH 主机。

许可证

MIT