JohnXu22786/docgen

English

docgen — 文档工坊技能包

一组纯提示词（Agent Skills）形态的文档生成技能，为 dsh 等插件化 agent harness 提供四项能力：README 生成、PR 描述生成、changelog 生成、代码审查。所有技能遵循 Agent Skills 开放标准（SKILL.md + YAML frontmatter），自包含、无第三方依赖、离线可用。

包含的技能

技能	做什么	何时用
readme-forge	从代码库生成/重写 README.md，只写有证据的内容	「给这个项目写个 README」
pr-dossier	从 diff 与提交历史生成完整 PR 描述（变更档案）	「为这次改动写 PR 描述」
changelog-curator	从 git 历史分类、合并、改写生成 CHANGELOG	「更新 changelog，准备发版」
diff-verdict	输出结构化审查意见：结论 + 分级问题清单 + 亮点	「审查一下这个 PR」

每个技能都是自包含的单个 SKILL.md：正文包含输入收集指引、工作流程、输出模板与模板变量表、语言风格选项、输出质量检查清单、「不要做」清单与边界情况处理。

目录结构

docgen/
├── README.md                     # 本文档：安装、使用、接口说明
├── package.json                  # npm 清单：name（dsh-docgen）+ dsh.bundle
├── cordis.patch.yml              # `dsh plugin` 安装时消费的 bundle 补丁
├── index.js                      # 技能挂载适配（把 skills/ 注册到 ctx.skills）
├── manifest.json                 # 插件清单（自描述元数据）
├── SKILLS.md                     # 入口索引文件
├── LICENSE                       # MIT 许可
├── skills/                       # 技能根目录（接入时指向这里或拷贝其中条目）
│   ├── readme-forge/SKILL.md
│   ├── pr-dossier/SKILL.md
│   ├── changelog-curator/SKILL.md
│   └── diff-verdict/SKILL.md
├── examples/
│   ├── prompts.md                # 每个技能的示例调用提示词
│   └── dsh-patch-enable-skills.yml  # dsh 接入补丁示例（web profile 启用技能 + 登记目录）
├── scripts/
│   └── validate_skills.py        # 技能包校验脚本（Python 标准库，无依赖）
└── tests/
    ├── test_validate_skills.py   # 校验脚本的回归测试
    └── index.test.mjs            # 技能挂载适配的 node 冒烟测试

在 DSH 中安装

docgen 随包携带 dsh.bundle 清单，用插件加载器一条命令安装并启用：

dsh plugin --profile demo add github:JohnXu22786/docgen

bundle 会把插件行（id: docgen、name: dsh-docgen）插入 profile，解析本包入口 （index.js）；其 apply(ctx) 扫描 skills/ 目录并把每个 SKILL.md 运行时注册到 ctx.skills——无需拷贝、无需额外配置。文件式接入方式仍然可用，适用于未加载 skills 服务或技能组件的 profile。

安装与接入 dsh

dsh 通过 skill-filesystem 提供方按技能根目录发现技能（一层深度：目录束 <root>/<name>/SKILL.md 或平铺文件 <root>/<name>.md）。接入本插件任选一种方式：

方式零：插件加载器（dsh.bundle，推荐）

dsh plugin --profile demo add github:JohnXu22786/docgen

bundle 入口（index.js）在加载时把 skills/ 下四个目录束注册到 ctx.skills。 这是单步接入；下述方式适用于手工或文件式集成。

方式一：项目级（零配置，不用插件加载器）

把 skills/ 下的四个技能目录（或整个 skills/）放进项目的技能根目录：

# 项目根目录（包含 .git 的最近祖先）任选其一：
#   <project>/.dsh/skills/   或   <project>/.agents/skills/
cp -r skills/* <project>/.dsh/skills/

方式二：用户级（所有项目可用）

# $DSH_HOME 默认 ~/.dsh；$DSH_AGENTS_HOME 默认 ~/.agents
cp -r skills/* ~/.dsh/skills/

方式三：自定义目录（插件原地接入，不拷贝）

通过配置给 skill-filesystem 提供方登记 customSkillDirs，例如用补丁文件（见 examples/dsh-patch-enable-skills.yml）：

npx @deepseek-ai/dsh web --patch ./examples/dsh-patch-enable-skills.yml

注意：dsh 的 web profile 默认关闭技能相关组件（skill-filesystem / tool-skill），需要补丁或 preset 启用；headless profile 默认开启。具体配置键路径以你所装版本的 dsh --dump-config 与官方文档为准。

验证安装

python scripts/validate_skills.py            # 校验本包技能格式（全部通过则退出码 0）
python scripts/validate_skills.py --strict   # 追加正文行数上限检查
python -m unittest discover -s tests -t .    # 运行校验脚本自身的回归测试
npm test                                     # 运行技能挂载适配的 node 冒烟测试

接入后在会话中直接以自然语言发起请求即可，模型会通过 skill 工具加载对应技能：

给这个项目写一个 README
为刚才的改动生成 PR 描述
根据 git 历史更新 changelog，准备发 1.2.0
帮我审查这个 PR

使用说明

• 触发：在提问中自然描述需求（见技能表「何时用」列），无需记住技能名；harness 依据 description / whenToUse 自动路由。
• 风格选项：每个技能支持三种可覆盖维度——语言（默认跟随提问语言）、篇幅（精简/标准/详尽或完整）、语气/深度。以自然语言追加即可：篇幅=精简、关注=安全、language=en。
• 输出形态：技能直接产出 markdown 文本；README/changelog 类技能会给出可直接保存为文件的完整内容，PR/审查类技能给出结构化描述或意见清单。
• 示例提示词：见 examples/prompts.md。

接口说明

技能接口（dsh 原生契约）

每个技能是一个目录束，SKILL.md 的 frontmatter 是 harness 读取的唯一契约：

字段	必填	约束	本包用法
name	是	kebab-case（小写字母/数字/连字符），≤64 字符，与所在目录名一致	见各技能
description	是	非空，≤1024 字符，说明做什么 + 何时用 + 触发关键词	中文描述 + 英文关键词
whenToUse	否	字符串，补充路由提示（社区确立的驼峰扩展字段）	各技能均已提供
metadata	否	字符串键值映射	author / version / family
license	否	字符串	MIT
compatibility	否	字符串，环境要求	纯提示词，无需网络
allowed-tools	否	字符串，预先批准的工具清单（实验性）	未使用

dsh 额外识别（本包不写、按默认处理）：disable-model-invocation 与 user-invocable（缺省均开放）。注意：字段名必须按上表拼写——allowed-tools 含连字符、whenToUse 为既定驼峰拼写，拼写不一致（如写成 allowed_tools 或 when-to-use）会导致该字段不被识别；其中调用策略字段拼写或类型错误时，dsh 会丢弃整个技能（fail-closed）。

插件清单与入口

• package.json + cordis.patch.yml：dsh plugin add 消费的 dsh.bundle 清单。安装时 dsh 读取 cordis.patch.yml 插入 docgen 插件行并加载 index.js——其 apply(ctx) 把技能注册到 ctx.skills（name / description / whenToUse / content / metadata / source: bundled），返回的组合 disposer 在卸载时逆序注销全部注册。
• manifest.json：插件的自描述元数据（id / version / kind / entry / interface / skills / scripts）。dsh 的技能发现不读取它，它服务于人工查阅、发布流程与支持「入口文件」型加载器的 harness；interface 字段声明了技能发现契约。
• SKILLS.md：入口索引，列出加载契约摘要与技能清单。

dsh 加载原理（摘要）

dsh 的技能能力由 skill（注册表）、skill-filesystem（本地发现）、tool-skill（模型目录与 skill 工具）三个插件协作提供：启动时按根目录扫描 frontmatter 生成目录（模型只看到 name + description）；模型决定调用某技能时按名读取最新正文；正文中的相对引用以技能目录为基准。本包四个技能均为单文件自包含，不依赖相对资源。

开发与扩展

• 新增技能：在 skills/ 下新建目录 + SKILL.md（frontmatter 见上表），运行 python scripts/validate_skills.py 通过校验，并同步更新 manifest.json 与 SKILLS.md。
• 修改技能：只编辑对应 SKILL.md，harness 下次加载即读到新内容（正文修改无需重启目录缓存）。
• 校验脚本：scripts/validate_skills.py 仅用 Python 标准库，可独立用于任何技能包；支持传任意目录/文件。解析范围是扁平 YAML 子集（顶层键值 + metadata 缩进映射 + 引号/列表字面量），不含锚点、注释等完整 YAML 特性。

依赖与隐私

• 零第三方依赖：纯提示词 + Python 标准库脚本；
• 不发起网络请求，不收集任何数据；需要的能力仅为读取代码库文件与 git 历史（由 harness 提供）；
• 许可证：MIT，见 LICENSE。

许可

MIT — 见 LICENSE。

常见问题

• web 界面看不到技能？ dsh web profile 默认关闭技能组件，用方式三的补丁启用（或使用 CLI/headless profile）。
• 改了 SKILL.md 没生效？ 技能正文按次读取，重发一次请求即可；若改的是 frontmatter 的 name/description，目录会随文件系统监听刷新。
• 技能与已有技能重名？ dsh 按根目录优先级与层（layer）就近覆盖同名技能；本包技能名均为原创命名，冲突时优先检查是否已安装同名技能。