zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
81833de6efa5420926e8626efbe2a10d37b420e7
ProjectAGiPrompt/1-AgentSkills/doc-sync-skill/SKILL.md
zeaslity e7c301023c 超大量更新
2026-04-29 09:46:36 +08:00

9.1 KiB
Raw Blame History

name, description, version, author, argument-hint, allowed-tools
name description version author argument-hint allowed-tools
doc-sync-skill 当 PRD 文档版本更新时，自动分析两版 PRD 差异并生成 Change Intent，驱动 DDS 与 AgentSkill 的增量同步更新，最终归档版本矩阵。 Automatically analyzes PRD version diffs, generates structured Change Intent, drives incremental DDS and AgentSkill updates, and archives version matrix. 触发场景 Trigger: 当用户提供了新旧两版 PRD 文档并需要同步更新 DDS 和 Skill / 需要执行文档级联变更 / 需要生成版本归档矩阵。 关键词 Keywords: PRD, DDS, diff, 增量更新, incremental update, change intent, version matrix, skill sync, 文档同步, doc sync, 版本管理。 1.0.0 wdd --old <old-prd-path> --new <new-prd-path> [--dds <current-dds-path>] [--skills-dir <skills-directory>]
Read
Write
Edit
Glob
Grep
Bash

Doc-Sync-Skill：PRD 增量变更驱动的文档级联同步

本 Skill 用于在软件开发流程中，当 PRD（产品需求文档）从旧版本更新到新版本时，自动完成以下四个阶段的级联同步：

  1. Phase 1 — PRD Diff 分析：对比新旧 PRD，生成结构化 Change Intent
  2. Phase 2 — DDS 增量更新：基于 Change Intent 驱动 DDS 只改受影响章节
  3. Phase 3 — AgentSkill 增量更新：基于 DDS 变更同步更新相关 SKILL.md
  4. Phase 4 — 版本归档：生成 VERSION_MATRIX.md 追踪所有文档版本关系

核心原则：

  • 最小变更原则 — 只修改受 PRD 变更影响的章节，未提及部分绝对不动
  • 溯源可追踪 — 每一处变更都能追溯到具体的 PRD 变更条目
  • 幂等安全 — 相同输入多次执行应产生相同结果

前置条件

执行前必须确认以下文件存在：

文件 必需 用途
旧版 PRD（--old） ✅ PRD diff 基准
新版 PRD（--new） ✅ PRD diff 目标
当前 DDS（--dds） ⚠️ Phase 2 必需 DDS 增量更新的基础
Skills 目录（--skills-dir） ⚠️ Phase 3 必需 Skill 增量更新的目标目录

文件不存在时的降级策略

  • 旧版 PRD 不存在：终止执行，提示用户提供旧版 PRD 路径
  • 新版 PRD 不存在：终止执行，提示用户提供新版 PRD 路径
  • DDS 不存在：跳过 Phase 2，在 Phase 4 记录"DDS 待创建"
  • Skills 目录不存在：跳过 Phase 3，在 Phase 4 记录"Skills 待创建"

Phase 1：PRD Diff 分析 → 生成 Change Intent

1.1 执行 PRD 差异对比脚本

使用 scripts/diff_prd.py 对新旧两版 PRD 进行章节级对比：

# 运行 PRD 差异对比
python3 "$(dirname "$0")/scripts/diff_prd.py" --old "$OLD_PRD_PATH" --new "$NEW_PRD_PATH"

该脚本输出结构化 JSON，包含：

  • added_sections：新增章节列表
  • modified_sections：修改章节列表（含 old/new 对比）
  • removed_sections：删除章节列表
  • summary：变更摘要

1.2 生成 Change Intent 文档

基于脚本输出的 JSON，填充 references/CHANGE_INTENT_TEMPLATE.md 模板：

  1. 读取模板：references/CHANGE_INTENT_TEMPLATE.md
  2. 根据 JSON 结果填充所有字段
  3. 输出完成的 Change Intent 文档到工作目录

填充规则：

  • 变更版本：从新版 PRD 的文档头提取版本号
  • 变更日期：使用当前日期
  • 新增需求列表：对应 added_sections
  • 修改需求列表：对应 modified_sections
  • 废弃需求列表：对应 removed_sections
  • 影响模块列表：从变更章节中提取涉及的模块/组件名称
  • 变更摘要：使用 JSON 中的 summary 字段，必要时补充人工判断

1.3 Change Intent 质量门禁

生成的 Change Intent 必须通过以下检查：

  • 所有字段非空（或显式标注"无"）
  • 影响模块列表至少 1 项（纯文案修改除外）
  • 变更摘要不超过 500 字
  • 新增/修改/废弃列表与 diff 脚本输出一致

Phase 2：DDS 增量更新

2.1 准备 DDS 更新 Prompt

将 Change Intent 和当前 DDS 内容注入 references/DDS_UPDATE_PROMPT.md：

  1. 读取当前 DDS 全文
  2. 读取 Phase 1 生成的 Change Intent
  3. 将两者填入 references/DDS_UPDATE_PROMPT.md 的对应占位符

变量替换：

  • {{CHANGE_INTENT}} → 完整的 Change Intent 文档内容
  • {{CURRENT_DDS}} → 当前 DDS 全文

2.2 执行 DDS 更新

将准备好的 Prompt 发送给大模型，获得 DDS 增量更新内容。

输出格式要求（在 Prompt 中已约束）：

  • [NEW] 标注新增章节
  • [MODIFIED] 标注修改章节，含 diff 对比
  • [DEPRECATED] 标注废弃章节
  • 未提及的章节绝对不修改

2.3 应用 DDS 变更

将大模型返回的增量更新逐章节应用到 DDS 文件：

  1. 对 [NEW] 章节：插入到 DDS 合适位置
  2. 对 [MODIFIED] 章节：替换对应章节内容
  3. 对 [DEPRECATED] 章节：标注废弃标记（保留原文，添加删除线或注释）
  4. 更新 DDS 文档头的版本号（按 Prompt 建议）

2.4 DDS 变更验证

  • 只有 Change Intent 中涉及的章节被修改
  • 未涉及章节内容与原文完全一致
  • 文档版本号已更新
  • 无语法错误（Markdown lint 通过）

Phase 3：AgentSkill 增量更新

3.1 一致性检查

运行 scripts/sync_check.py 检查 DDS 与 Skills 的对应关系：

python3 "$(dirname "$0")/scripts/sync_check.py" --dds "$DDS_PATH" --skills-dir "$SKILLS_DIR"

该脚本输出不一致报告：

  • DDS 中有定义但无对应 Skill 的模块
  • Skills 目录中有 Skill 但无对应 DDS 章节的模块

3.2 确定需要更新的 Skill 列表

基于 Phase 2 的 DDS 变更内容，确定受影响的 Skill 列表：

  1. 提取 DDS 中 [NEW]/[MODIFIED]/[DEPRECATED] 章节涉及的模块名
  2. 在 Skills 目录中查找对应的 SKILL.md 文件
  3. 对于 DDS 新增模块但无 Skill 的情况，标记为"需新建 Skill"

3.3 执行 Skill 增量更新

对每个受影响的 Skill，使用 references/SKILL_UPDATE_PROMPT.md 驱动更新：

变量替换：

  • {{DDS_DIFF}} → 该模块涉及的 DDS 变更内容（[NEW]/[MODIFIED]/[DEPRECATED] 片段）
  • {{SKILL_NAME}} → 当前 Skill 的 name 值
  • {{CURRENT_SKILL_MD}} → 当前 SKILL.md 全文

更新规则：

  • 只更新受 DDS 变更影响的部分
  • version 字段 patch 版本 +1
  • 输出完整的新 SKILL.md 内容（直接覆盖写入）

3.4 Skill 更新验证

对每个更新后的 Skill 执行以下检查：

  • SKILL.md 的 YAML frontmatter 格式正确
  • version 字段已递增
  • name 字段未被修改
  • description 保持单行且 < 1024 字符
  • 未受影响的章节内容未被修改

Phase 4：版本归档

4.1 生成 VERSION_MATRIX.md

基于 assets/VERSION_MATRIX_TEMPLATE.md 模板，追加一行新的版本记录：

字段 取值来源
迭代日期 当前执行日期
PRD版本 新版 PRD 中提取的版本号
DDS版本 更新后 DDS 的版本号
受影响Skill Phase 3 中更新的 Skill 名称列表
变更摘要 Change Intent 中的变更摘要
Git Commit 预留占位（手动填写或自动获取）

4.2 归档文件存放位置

VERSION_MATRIX.md 存放在项目根目录或用户指定目录，采用追加模式：

  • 如果文件已存在，在表格末尾追加新行
  • 如果文件不存在，从模板创建并填入第一条记录

异常处理规则

异常场景 处理策略
旧版/新版 PRD 文件不存在 终止执行，输出错误信息
diff_prd.py 脚本执行失败 输出错误日志，提示用户手动对比
DDS 文件不存在 跳过 Phase 2/3，仅执行 Phase 1/4
Skills 目录不存在 跳过 Phase 3，仅执行 Phase 1/2/4
DDS 更新 Prompt 返回格式异常 要求重新生成，最多重试 2 次
Skill 更新后 frontmatter 格式错误 回滚该 Skill 更新，标记为需人工修复
sync_check.py 发现不一致模块 在 VERSION_MATRIX 中记录，不阻断流程

输出清单

每次执行完成后，必须输出以下产物清单：

📋 Doc-Sync 执行报告
├── [Phase 1] CHANGE_INTENT.md        — PRD 变更意图文档
├── [Phase 2] DDS 更新文件            — 增量更新后的 DDS（如适用）
├── [Phase 3] 更新的 SKILL.md 列表    — 增量更新后的 Skills（如适用）
├── [Phase 4] VERSION_MATRIX.md       — 追加后的版本矩阵
└── [报告]    执行摘要                 — 各 Phase 执行状态汇总

Quick Reference

需要了解... 查阅...
Change Intent 的结构模板 references/CHANGE_INTENT_TEMPLATE.md
DDS 增量更新 Prompt references/DDS_UPDATE_PROMPT.md
Skill 增量更新 Prompt references/SKILL_UPDATE_PROMPT.md
PRD 差异对比脚本 scripts/diff_prd.py
DDS-Skill 一致性检查脚本 scripts/sync_check.py
版本矩阵归档模板 assets/VERSION_MATRIX_TEMPLATE.md