feat: add ddd doc steward skill

2025-12-21 03:45:20 +08:00 · 2025-12-21 03:45:20 +08:00 · 727b2900ca
parent b70e41b461
commit 727b2900ca
8 changed files with 300 additions and 2 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -5,7 +5,7 @@
 - 多语言 i18n：`i18n/<lang>/` 统一三层结构（documents / prompts / skills）。现有语言：中文 `zh`、英文 `en`、希伯来语 `he`，以及 `es`、`hi`、`ar`、`pt`、`ru`、`fr`、`de`、`ja`、`ko`、`it`、`tr`、`nl`、`pl`、`id`、`vi`、`th`、`fa`、`uk`、`bn`、`ta`、`ur`、`ms`、`sw`、`ha`；新增语言遵循同样层级。
 - 文档库：`i18n/zh/documents/` 是默认中文方法论入口，含子目录：`方法论与原则/`、`模板与资源/`、`教程与指南/`、`外部资源聚合/`、`胶水编程/`、`从零开始vibecoding/` 等。
 - 提示词资产：`i18n/zh/prompts/` 按角色拆分（`system_prompts/`、`assistant_prompts/`、`coding_prompts/`、`user_prompts/`、`meta_prompts/`），`libs/external/prompts-library/` 提供 Excel ↔ Markdown 互转工具。
- 技能库：`i18n/zh/skills/` 包含模块化技能集，如 `ccxt/`、`postgresql/`、`telegram-dev/`、`claude-code-guide/`、`claude-skills/` 等 16+ 个技能目录。
+- 技能库：`i18n/zh/skills/` 包含模块化技能集，如 `ccxt/`、`postgresql/`、`telegram-dev/`、`claude-code-guide/`、`ddd-doc-steward/`、`claude-skills/` 等 17+ 个技能目录。
 - 代码与集成：`libs/` 预留核心实现骨架，`common/`（含 `models/`、`utils/`）、`database/`、`external/` 分别对应通用模型、存储适配与外部依赖。
 - 外部工具：`libs/external/` 含 `prompts-library/`、`l10n-tool/`、`my-nvim/`、`MCPlayerTransfer/`、`XHS-image-to-PDF-conversion/` 等。
 - 备份：`backups/` 内含 `一键备份.sh`、`快速备份.py` 和 `gz/` 存档目录。
--- a/i18n/zh/skills/04-开发工具/ddd-doc-steward/SKILL.md
+++ b/i18n/zh/skills/04-开发工具/ddd-doc-steward/SKILL.md
@ -0,0 +1,109 @@
+name: ddd-doc-steward
+description: "文档驱动开发（DDD）文档管家：以仓库真实证据为准，盘点 ~/project 与 docs 目录，生成/更新 SSOT 文档（计划→补丁/全文→摘要→一致性检查）。触发：需要让文档与代码/配置/运行方式同步、补齐 guides/integrations/features/architecture/incidents/archive、无法推导时标注【待确认】并给验证路径。"
+---
+
+# DDD 文档管家 Skill
+
+让 `~/project/docs` 成为单一可信来源（SSOT）：先盘点、后计划、再增量写文档，所有事实有证据来源，没有证据就【待确认】。
+
+## 何时使用
+
+- 需要为真实仓库建立/维护文档 SSOT，输出「盘点表 → 计划 → 文档补丁/全文 → 变更摘要 → 一致性检查」的固定交付物。
+- 新增/改动功能、集成或事故复盘，需要同步更新 docs 下对应目录。
+- 需要在 strict 模式下，避免任何臆测，所有关键事实必须给出代码/配置/命令的路径或说明验证方法。
+- 只能获取部分信息时，仍需生成最小可落地模板并标注【待确认】。
+
+## 不适用 / 边界
+
+- 与工程无关的纯创作文案。
+- 无法提供最小证据集（目录树、README/依赖/配置/路由位置）且不接受【待确认】输出时。
+- 涉及密钥明文输出；文档中仅可写占位符与获取方式。
+- 未提供 `project_root/docs_root/output_mode` 等输入时，先将自然语言归一到输入 JSON（参见快速参考）。
+
+## 快速参考
+
+1) 归一化输入（缺省值）
+```json
+{
+  "project_root": "~/project",
+  "docs_root": "~/project/docs",
+  "output_mode": "patch_diff",
+  "truthfulness_mode": "strict",
+  "change_type": "baseline",
+  "scope_hint": null,
+  "related_paths": [],
+  "prefer_priority": ["guides","integrations","features","architecture","incidents","archive"],
+  "enforce_docs_index": true,
+  "use_git_diff": true,
+  "max_doc_size_kb": 200,
+  "style": "standard"
+}
+```
+
+2) Phase A 扫描要点（证据链）
+- `tree -L 3` 或目录枚举；`rg` 聚焦 README、依赖、配置、路由/API 定义。
+- 记录证据路径清单（文件/命令），不写结论。
+
+3) Phase B 先输出计划
+- 《文档盘点表》：按六大目录标记「存在/缺失/疑似过期」，附证据路径。
+- 《生成/更新计划》：新增/更新/待确认清单；理由=证据。
+
+4) Phase C 生成文档（遵循 output_mode）
+- `patch_diff` 推荐；无写权限时用 `full_files`。
+- 每个文档必含 Purpose/Scope/Status/Evidence/Related/Changelog。
+- 命名规范：ADR `architecture/adr-YYYYMMDD-<kebab>.md`；PRD/Spec/Integration/Guide/Incident/Archive 详见 `references/api.md`。
+
+5) Phase D 收尾
+- 变更摘要：每文件 3-8 条关键变化。
+- 一致性检查：文档-代码验证点 + 未解的【待确认】与下一步。
+
+6) 关键规则
+- 真实性优先：无证据不写，写则附路径；敏感值用占位符。
+- 没有就创建，有就增量更新，禁止大面积重写无关内容。
+- 超过 `max_doc_size_kb` 拆分；缺少访问时生成模板并给证据采集命令。
+
+## 规则 & 约束
+
+- MUST：输出五段结构；严格遵守目录/命名规范；Changelog 每文必有；冲突以代码/配置为准。
+- SHOULD：优先用 git diff/related_paths 聚焦；guides 与 integrations 先行；为每个【待确认】提供验证路径。
+- NEVER：编造端口/环境变量/接口字段；输出密钥明文；跳过盘点直接写文档。
+
+## 示例
+
+### 示例 1：空仓库初始化
+- 输入：`change_type=baseline`，docs 为空。
+- 步骤：A 扫描→B 盘点表标记全部缺失→计划新增 docs/README.md、guides/getting-started.md 等→C 生成骨架补丁→D 摘要与检查。
+- 验收：输出 patch diff，所有命令标【待确认】或给寻找路径。
+
+### 示例 2：新增登录功能
+- 输入：`change_type=feature`，`scope_hint="auth 登录"`，`use_git_diff=true`。
+- 步骤：用 diff 找受影响路由；盘点 features/integrations；计划新增 PRD/Spec，更新 integrations/auth-api；标记 token 过期时间待确认。
+- 验收：变更摘要指出新增文档与更新字段；检查清单含鉴权/错误码/验证 curl。
+
+### 示例 3：无法读取仓库
+- 输入：仅自然语言“帮我做 SSOT 文档”。
+- 步骤：先归一化 JSON，声明“无法真实扫描”→生成六类文档模板，全量标【待确认】并列证据缺口与采集命令。
+- 验收：输出 full_files；每条待确认可直接行动补证。
+
+## FAQ
+
+- Q: 没有写权限怎么办？  
+  A: 将 `output_mode` 设为 `patch_diff` 或 `full_files`，给出可落盘内容。
+- Q: 目录过大处理不过来？  
+  A: 按 prefer_priority 分批；声明本次范围与剩余批次计划。
+
+## 维护
+
+- 来源：`i18n/zh/prompts/02-编程提示词/文档驱动开发/DDD 文档管家 Agent 工业级提示词.md`；元技能 `00-元技能/claude-skills/`；自动化辅助工具 `libs/external/Skill_Seekers-development`.
+- 最后更新：2025-12-20
+- 已知限制：依赖用户提供真实证据；大体量仓库需分批；不输出敏感值。
+
+## 质量门禁（出厂前自检）
+
+1. `name/description` 符合触发条件、目录名一致。
+2. 五段交付结构齐全；每段内容可直接给人/脚本消费。
+3. 每个文档含 Purpose/Scope/Status/Evidence/Related/Changelog。
+4. 所有事实有证据路径；无证据标【待确认】且给验证路径。
+5. Quick Reference ≤20 条且可直接执行；示例 ≥3。
+6. 长文本放 `references/`，`references/index.md` 可导航。
+7. 安全：不输出密钥明文，敏感值使用占位符。
--- a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/api.md
+++ b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/api.md
@ -0,0 +1,62 @@
+# 输入 / 输出 / 目录命名规范
+
+## 输入字段
+
+- **required**
+  - `project_root` (默认 `~/project`)
+  - `docs_root` (默认 `~/project/docs`)
+  - `output_mode` ∈ {`direct_write`,`patch_diff`,`full_files`}，默认 `patch_diff`
+  - `truthfulness_mode`，默认 `strict`
+- **optional**
+  - `scope_hint`：聚焦模块/目录提示
+  - `change_type` ∈ {`baseline`,`feature`,`bugfix`,`refactor`,`release`}
+  - `related_paths`：受影响路径列表
+  - `prefer_priority`：文档优先级顺序
+  - `enforce_docs_index`：是否强制维护 docs/README.md
+  - `use_git_diff`：true 时优先以 git diff 定位
+  - `max_doc_size_kb`：单文档体积上限（默认 200KB）
+  - `style` ∈ {`concise`,`standard`,`verbose`}
+
+## 输出固定顺序
+
+1) 文档盘点表  
+2) 生成/更新计划  
+3) 逐文件创建/更新内容（遵循 output_mode）  
+4) 变更摘要  
+5) 一致性检查清单
+
+## 目录与命名
+
+```
+docs/
+├── architecture/
+├── features/
+├── integrations/
+├── guides/
+├── incidents/
+└── archive/
+```
+
+- ADR：`docs/architecture/adr-YYYYMMDD-<kebab>.md`
+- PRD：`docs/features/prd-<kebab>.md`
+- Spec：`docs/features/spec-<kebab>.md`
+- Integration：`docs/integrations/<kebab-service>.md`
+- Guide：`docs/guides/<kebab-topic>.md`
+- Incident：`docs/incidents/incident-YYYYMMDD-<kebab>.md`
+- Archive：`docs/archive/YYYY/<orig-or-topic>.md`（原处留指向）
+
+## 每个文档必备结构
+
+- Purpose（目的）
+- Scope（适用范围）
+- Status（Active/Draft/Deprecated）
+- Evidence（代码/配置/命令路径）
+- Related（交叉链接或路径）
+- Changelog（含最后更新时间 + 变更摘要）
+
+## 质量门禁速查
+
+- 五段交付结构齐全，顺序正确。
+- 所有关键事实附证据路径；缺失用【待确认】+验证指引。
+- guides / integrations 优先生成，且 integrations 含可验证步骤（curl/脚本）。
+- 超限文档拆分；无权限时使用 patch/full_files 仍可落地。
--- a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/examples.md
+++ b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/examples.md
@ -0,0 +1,51 @@
+# 场景示例（可直接套用）
+
+## 示例 1：空仓库快速落地
+- 输入：
+```json
+{
+  "project_root": "~/project",
+  "docs_root": "~/project/docs",
+  "output_mode": "patch_diff",
+  "change_type": "baseline",
+  "scope_hint": "docs 为空",
+  "use_git_diff": false
+}
+```
+- 操作：
+  1. A：`tree -L 2 docs` 为空 → 记录证据。
+  2. B：盘点表全部标记“缺失”；计划新增 docs/README.md、guides/getting-started.md、development-workflow.md、integrations/<待确认>.md。
+  3. C：输出补丁，命令/端口/变量均标【待确认】，并说明从 `.env` / `docker-compose` / 配置目录查证。
+  4. D：摘要列出新增文件；检查清单提示需补全端口/env/API 证据。
+- 预期：可直接应用的 diff；无臆测字段；每文含 Changelog。
+
+## 示例 2：功能迭代—登录与刷新
+- 输入：
+```json
+{
+  "project_root": "~/project",
+  "docs_root": "~/project/docs",
+  "output_mode": "patch_diff",
+  "truthfulness_mode": "strict",
+  "change_type": "feature",
+  "scope_hint": "auth 登录 & token 刷新",
+  "related_paths": ["services/api/auth", "services/api/routes"],
+  "use_git_diff": true
+}
+```
+- 操作：
+  1. A：`git diff --name-only` 聚焦 auth 路由/控制器；提取请求/响应字段与错误码。
+  2. B：盘点表标识 features/prd-auth-login.md、spec-auth-login.md 缺失；integrations/auth-api.md 疑似过期（字段不一致）。
+  3. C：新增 PRD/Spec；更新 integrations 文档含鉴权方式、错误码、验证 curl；token TTL 等未证实字段标【待确认】并指向配置文件。
+  4. D：摘要列出新增/更新；检查清单包含“对照 auth/config 复核 TTL、错误码”。
+- 预期：diff 覆盖 3 个文件；所有事实有路径；待确认项附验证方法。
+
+## 示例 3：无法读取仓库的降级
+- 输入：自然语言 “帮我生成 SSOT 文档模板”。
+- 操作：
+  1. 归一化 JSON，声明“无法真实扫描，进入 strict 模板模式”。
+  2. 盘点表说明证据缺口（目录树/README/依赖/配置/API 位置缺失）。
+  3. 计划仅生成模板；待确认清单列出需用户补充的命令与文件。
+  4. 输出 full_files：六大目录的骨架文档，字段均标【待确认】+ 如何获取。
+  5. 检查清单提示下一步需用户提供证据。
+- 预期：完整可落盘模板，不含任何凭空事实。
--- a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/getting_started.md
+++ b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/getting_started.md
@ -0,0 +1,31 @@
+# 快速开始 & 术语表
+
+## 使命
+
+让 `~/project/docs` 成为单一可信来源（SSOT）：先盘点、先计划、增量更新，所有事实可追溯。
+
+## 最短落地路径
+
+1. **收集最小证据集**：`tree -L 3`、README、依赖清单、主要配置（.env*/yaml/toml/docker/k8s）、路由/API 定义位置、最近 git diff。
+2. **归一化输入**：把用户自然语言转成 JSON（见 `SKILL.md` 快速参考），缺省 `output_mode=patch_diff`、`truthfulness_mode=strict`。
+3. **执行 A→D 流程**：A 扫描→B 盘点与计划→C 生成文档（按 output_mode）→D 变更摘要与一致性检查。
+4. **落盘或回传**：有写权用 direct_write；否则输出 patch/full_files 供用户应用。
+
+## 核心术语
+
+- **SSOT**：Single Source of Truth，docs 与代码/配置/运行方式一致。
+- **output_mode**：`direct_write`（直接写）、`patch_diff`（推荐）、`full_files`（无法写入时）。
+- **truthfulness_mode=strict**：无证据不写；写则附路径或命令；敏感值用占位符。
+- **prefer_priority**：默认 `guides > integrations > features > architecture > incidents > archive`。
+- **enforce_docs_index**：true 时必须维护 `docs/README.md` 导航。
+- **Evidence**：文件路径、命令输出、日志位置；每个关键事实都需来源。
+- **【待确认】**：无法推导的字段，需附验证路径（文件/命令/负责人）。
+- **max_doc_size_kb**：单文档建议体积，超限应拆分。
+
+## 自动化采集（可选）
+
+- 需要批量抓取外部文档/代码仓库时，可用 `libs/external/Skill_Seekers-development` 的 CLI（如 `skill-seekers scrape --config <config.json>`）生成参考素材，再按本技能流程落盘。
+
+## 交付物检查
+
+- 五段结构齐全；每文含 Purpose/Scope/Status/Evidence/Related/Changelog；所有事实有证据或【待确认】。
--- a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/index.md
+++ b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/index.md
@ -0,0 +1,17 @@
+# ddd-doc-steward 参考索引
+
+长文与细节集中在这里，`SKILL.md` 保持轻量。
+
+## 快速导航
+
+- 入门与术语：`getting_started.md`
+- 输入/输出规范 & 目录命名：`api.md`
+- 场景示例（可直接套用）：`examples.md`
+- 降级与故障处理：`troubleshooting.md`
+- 质量门禁与评分要点：`api.md#质量门禁`
+
+## 使用提示
+
+- 优先阅读 `getting_started.md` 获取流程全貌，再按需跳转。
+- 大于 10KB 的真实项目素材请分批引用，避免上下文爆炸。
+- 所有证据链（文件/命令）务必写在文档正文而非这里。
--- a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/troubleshooting.md
+++ b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/troubleshooting.md
@ -0,0 +1,26 @@
+# 故障与降级处理
+
+## 无法访问仓库或文件
+- 症状：无法读取目录/文件；无 tree/README/依赖信息。
+- 诊断：权限不足或未提供素材。
+- 处理：声明 strict 降级；仅输出模板骨架，所有事实标【待确认】；列出证据采集命令（tree/README/依赖/配置/API）。
+
+## 文档与代码冲突
+- 症状：文档端口/字段/错误码与实现不一致。
+- 诊断：历史文档未同步。
+- 处理：以代码/配置为准更新；在 Changelog 记录冲突与修复原因；若行为变更建议补 ADR；无法确定时标【待确认】并给验证命令。
+
+## 仓库过大或范围不清
+- 症状：输出超长或扫描耗时。
+- 诊断：目录/模块过多，未限定范围。
+- 处理：按 `prefer_priority` 分批；声明本次覆盖范围；优先 guides/integrations；余量列入后续批次计划。
+
+## 敏感信息暴露风险
+- 症状：配置包含 token/password/key。
+- 诊断：直接读取 .env / 配置文件。
+- 处理：文档仅写变量名与获取方式，值用占位符；提示使用 vault/secret manager；必要时创建安全整改/incident 记录。
+
+## 自动化采集失败
+- 症状：使用 `skill-seekers` 抓取外部文档/仓库失败。
+- 诊断：配置不当或站点屏蔽。
+- 处理：检查 config/URL；改用本地 `git clone` + 手工 `rg`；必要时缩小范围或增加重试间隔。
--- a/i18n/zh/skills/README.md
+++ b/i18n/zh/skills/README.md
@ -1,6 +1,6 @@
 # 🎯 AI Skills 技能库

-`i18n/zh/skills/` 目录存放 AI 技能（Skills），这些是比提示词更高级的能力封装，可以让 AI 在特定领域表现出专家级水平。当前包含 **16 个**专业技能。
+`i18n/zh/skills/` 目录存放 AI 技能（Skills），这些是比提示词更高级的能力封装，可以让 AI 在特定领域表现出专家级水平。当前包含 **17 个**专业技能。

 ## 目录结构

@ -28,6 +28,7 @@ i18n/zh/skills/
 │   └── polymarket/          # 预测市场 API
 │
 └── 04-开发工具/             # 通用开发工具
+    ├── ddd-doc-steward/    # 文档驱动开发文档管家
    ├── telegram-dev/        # Telegram Bot 开发
    ├── twscrape/            # Twitter/X 数据抓取
    ├── snapdom/             # DOM 快照工具
@ -71,6 +72,7 @@ i18n/zh/skills/

 | 技能 | 说明 |
 |:---|:---|
+| [ddd-doc-steward](./04-开发工具/ddd-doc-steward/SKILL.md) | 文档驱动开发（DDD）文档管家，按证据链生成/更新 docs SSOT |
 | [telegram-dev](./04-开发工具/telegram-dev/SKILL.md) | Telegram Bot 开发 |
 | [twscrape](./04-开发工具/twscrape/SKILL.md) | Twitter/X 数据抓取 |
 | [snapdom](./04-开发工具/snapdom/SKILL.md) | DOM 快照与测试 |