From 727b2900ca650d3cdaa52ba970dc42b18e691e50 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sun, 21 Dec 2025 03:45:20 +0800 Subject: [PATCH] feat: add ddd doc steward skill --- AGENTS.md | 2 +- .../04-开发工具/ddd-doc-steward/SKILL.md | 109 ++++++++++++++++++ .../ddd-doc-steward/references/api.md | 62 ++++++++++ .../ddd-doc-steward/references/examples.md | 51 ++++++++ .../ddd-doc-steward/references/getting_started.md | 31 +++++ .../ddd-doc-steward/references/index.md | 17 +++ .../ddd-doc-steward/references/troubleshooting.md | 26 +++++ i18n/zh/skills/README.md | 4 +- 8 files changed, 300 insertions(+), 2 deletions(-) create mode 100644 i18n/zh/skills/04-开发工具/ddd-doc-steward/SKILL.md create mode 100644 i18n/zh/skills/04-开发工具/ddd-doc-steward/references/api.md create mode 100644 i18n/zh/skills/04-开发工具/ddd-doc-steward/references/examples.md create mode 100644 i18n/zh/skills/04-开发工具/ddd-doc-steward/references/getting_started.md create mode 100644 i18n/zh/skills/04-开发工具/ddd-doc-steward/references/index.md create mode 100644 i18n/zh/skills/04-开发工具/ddd-doc-steward/references/troubleshooting.md diff --git a/AGENTS.md b/AGENTS.md index a5b2797..42653d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ - 多语言 i18n：`i18n//` 统一三层结构（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/` 存档目录。 diff --git a/i18n/zh/skills/04-开发工具/ddd-doc-steward/SKILL.md b/i18n/zh/skills/04-开发工具/ddd-doc-steward/SKILL.md new file mode 100644 index 0000000..9687255 --- /dev/null +++ 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-.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. 安全：不输出密钥明文，敏感值使用占位符。 diff --git a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/api.md b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/api.md new file mode 100644 index 0000000..bfdf160 --- /dev/null +++ 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-.md` +- PRD：`docs/features/prd-.md` +- Spec：`docs/features/spec-.md` +- Integration：`docs/integrations/.md` +- Guide：`docs/guides/.md` +- Incident：`docs/incidents/incident-YYYYMMDD-.md` +- Archive：`docs/archive/YYYY/.md`（原处留指向） + +## 每个文档必备结构 + +- Purpose（目的） +- Scope（适用范围） +- Status（Active/Draft/Deprecated） +- Evidence（代码/配置/命令路径） +- Related（交叉链接或路径） +- Changelog（含最后更新时间 + 变更摘要） + +## 质量门禁速查 + +- 五段交付结构齐全，顺序正确。 +- 所有关键事实附证据路径；缺失用【待确认】+验证指引。 +- guides / integrations 优先生成，且 integrations 含可验证步骤（curl/脚本）。 +- 超限文档拆分；无权限时使用 patch/full_files 仍可落地。 diff --git a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/examples.md b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/examples.md new file mode 100644 index 0000000..8485175 --- /dev/null +++ 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. 检查清单提示下一步需用户提供证据。 +- 预期：完整可落盘模板，不含任何凭空事实。 diff --git a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/getting_started.md b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/getting_started.md new file mode 100644 index 0000000..5c8fcc4 --- /dev/null +++ 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 `）生成参考素材，再按本技能流程落盘。 + +## 交付物检查 + +- 五段结构齐全；每文含 Purpose/Scope/Status/Evidence/Related/Changelog；所有事实有证据或【待确认】。 diff --git a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/index.md b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/index.md new file mode 100644 index 0000000..8ab0734 --- /dev/null +++ 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 的真实项目素材请分批引用，避免上下文爆炸。 +- 所有证据链（文件/命令）务必写在文档正文而非这里。 diff --git a/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/troubleshooting.md b/i18n/zh/skills/04-开发工具/ddd-doc-steward/references/troubleshooting.md new file mode 100644 index 0000000..cd8a81e --- /dev/null +++ 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`；必要时缩小范围或增加重试间隔。 diff --git a/i18n/zh/skills/README.md b/i18n/zh/skills/README.md index a2f0fe1..aaeca53 100644 --- 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 快照与测试 |