dsh-project-handbook
Company-grade project handover / onboarding handbook generator for
DeepSeek Harness — 项目交接与新人熟悉文档.
One command pair turns a real repository into a Markdown handover pack a new
engineer can act on in their first week:
.handover/
├── PROJECT-HANDBOOK.md # 15-section handover manual (公司项目级)
├── ONBOARDING-CHECKLIST.md # day-one / week-one checklist with sign-off
├── GLOSSARY.md # domain + internal jargon (comprehensive profile)
├── RUNBOOK.md # failure cards, rollout, data repair (comprehensive)
├── inventory.json / .md # the fact base every claim is checked against
└── check-report.md # what the quality gate found
Why it is different from "ask the model to write a README"
- Evidence or
待确认. Every claim carries a path, path:line or the exact
command that proves it. Anything the repository cannot answer (deploy target,
on-call rotation, business rules, why a decision was made) is written as an
explicit open question instead of plausible-sounding prose.
- A deterministic scan first.
project-inventory.mjs walks the repository and
reports languages, manifests, framework signals, CI jobs and their commands,
deployment artifacts, env-var names, migrations, entry points, test layout, git
history and top authors, technical-debt markers, committed credential-shaped
files — plus a pre-computed verifyFirst list of the gaps.
- A real quality gate.
check-handbook.mjs blocks missing sections, stubs,
unfilled placeholders, speculation wording, ✅ badges with no citation, cited
paths that do not exist, links and anchors that do not resolve, package scripts
that no package.json defines, secrets pasted into the document, and claims
that contradict the inventory.
- Stack-aware reconnaissance. Recon playbooks for Java/Spring, Go, Python,
Node/TypeScript, frontend, data/AI and legacy-ops projects tell the agent exactly
which files to open and which facts to extract.
- Safe by construction. Read-only reconnaissance; credentials are never
opened or quoted; no builds, migrations, deploys or commits happen while
producing the document.
Install
From GitHub (works today, no npm publish needed):
dsh plugin --profile web add github:Gan-lang/dsh-project-handbook
From npm — once the package is published there:
dsh plugin --profile web add dsh-project-handbook
From a local checkout:
dsh plugin --profile web add /absolute/path/to/dsh-project-handbook
Whichever source you use, finish by adding the bundle to the profile's ordered
bundle list in $DSH_HOME/profiles/web/package.json:
{
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-project-handbook"]
}
}
}
Restart dsh web. The plugin mounts only the bundled skill (no host services, no
client code): cordis.patch.yml registers a @deepseek-ai/dsh-skill-filesystem
provider whose bundledSkillDir is resolved from the installed package identity,
so the skill appears in the session catalog as project-handbook.
Use
Ask in any session:
生成这个项目的交接文档，要公司项目级、新人能直接上手的那种
The skill:
- runs
scripts/project-inventory.mjs (--root . --out .handover/inventory.json);
- reads the matching stack playbook(s) and the code that carries the project story;
- fills the templates in
assets/ (profile compact / standard / comprehensive);
- runs
scripts/check-handbook.mjs until it passes, then completes the manual
acceptance list in references/quality-gate.md;
- reports the files, the inspected commit, and the short list of questions the
project owner must answer.
The scripts are plain ESM and also run standalone:
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
Layout
dsh-project-handbook/
├── cordis.patch.yml # mounts the bundled skill provider
├── lib/index.js # package identity + skill-root resolver
└── skills/project-handbook/
├── SKILL.md # the workflow the agent follows
├── scripts/project-inventory.mjs # repository reconnaissance → JSON + Markdown
├── scripts/check-handbook.mjs # documentation quality gate
├── references/ # evidence rules, content standard, stack playbooks,
│ # credential rules, quality gate
└── assets/ # fill-in document templates
Requirements
Node.js ^22.19.0 || >=24.0.0 (no runtime dependencies) and a DSH host that
ships @deepseek-ai/dsh-skill-filesystem.
License
MIT
