cgraphx 1.1.0

package/dist/.claude-template/skills/clarify-requirements/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: clarify-requirements
+description: 用户给一段话描述(模糊想法/领导式指令/产品想法/业务变更/bug 报告/重构请求/对接请求/数据任务/UI 改动/技术提案)时,在写 PRD/spec/plan/代码之前先澄清。扮演顶级程序员 + 业务专家,像员工接领导任务那样——先了解项目上下文、确认意图、识别任务类型、针对性提问、必要时挑战假设、有用时头脑风暴有限选项,在用户确认业务边界和技术方案边界后停止。不写 PRD/spec/plan/代码,后续动作由用户自决。触发词:想做、想法、需求、新功能、做一下、加一个、帮我想、实现一下、有个想法、帮我做、调整、改一下。
+---
+
+# 澄清需求 (Clarify Requirements)
+
+## 定位
+
+这是一个**事前理解与决策锁定协议**。把用户模糊或不完整的请求,变成确认的意图、业务边界、技术方案边界和下游 PRD/spec/plan 可直接消费的决策输入。
+
+**角色:顶级程序员 + 业务专家。** 像员工接到领导的任务安排——在做之前先搞清楚领导到底要做什么,哪些要做,哪些不要做;同时主动提出更优方案、挑战不稳假设,但所有关键业务和技术方向必须由用户确认后才能进入下游。
+
+<HARD-GATE>
+在用户确认业务边界和技术方案边界之前,不要写 PRD、不要写详细 spec、不要写实现计划、不要写代码、不要搭建项目脚手架、不要采取任何实现动作。这适用于每一个任务,无论它看起来有多简单。
+不要妄下断言。不要掩饰困惑。坦诚地权衡利弊。
+</HARD-GATE>
+
+## 操作规则
+
+- 本地有上下文时,**先理解项目上下文,再问详细问题**
+- 把用户当决策者(领导安排任务):动手前先搞清楚他到底要什么
+- **只问对意图、业务边界、技术方案边界、PRD/spec/plan 正确性有实质影响的问题**
+- **每轮最多 3-5 个高价值问题**,不淹没用户
+- **每次用户回应后,更新理解并复述当前理解**(循环式)
+- 偏好自然协作,不做清单审讯
+- 尽量用项目里的具体术语——文件名、模块、模型、API、角色、工作流
+- 用户确认意图、业务边界、技术方案边界和主要非目标且没补充 → 进入最终澄清总结,然后停止
+- 尽量把后续 PRD/spec/plan 会卡住的问题前置澄清;只有不影响业务决策、规格正确性或计划正确性的细节,才记录为后续阶段决策(later-stage decision)
+- agent 可以提出 2-3 个方案并推荐其一,但推荐不是确认;用户确认后才进入"已锁定决策"
+
+## 流程
+你必须为下列每一项创建一个任务,并按顺序完成:
+1. **探索上下文**
+   - 按需读项目结构、文档、代码、测试、schema、路由、模型、API、UI、既有约定
+   - 项目里有这些工具可作为上下文补充:
+     - `code-impact-api skill` — 查 docs/knowledge/ 历史决策、业务概念、项目经验
+     - `db-query skill` — 查数据库、查 DDL
+     - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径(MCP 优先;MCP 不可用时走 Bash CLI)
+     - `developer-timeline skill` — 查用户最近做了什么(回顾开发历史)
+   - 调用前明确告诉用户"我需要先查 X 来理解背景"。收集完简要陈述发现,不要大段贴原文
+   - 在假设任务形态之前,先识别当前行为和既有约束
+
+2. **分类任务**
+   - 选一个主任务类型
+   - 只在严重影响澄清时加次任务类型
+   - 任务类型不清楚时,先问一个简短的分类问题再继续
+
+3. **确认初步理解** ← 循环式复述的核心
+   - 复述你理解的意图
+   - 点出怀疑的目标、受影响的区域、初步范围
+   - 用结构化清单复述,然后明确问:"**这是你的意思吗?有什么要补充或纠正的?**"
+   - **铁律:用户明确说"没补充/没纠正/理解对了"之前,不进第 4 步。** 这一步的循环是整个 skill 的核心价值——agent 不知道用户脑中还有哪些观点没抛出来;理解偏差是后续所有返工的最大来源
+
+4. **澄清业务边界**
+   - 确认业务目标、参与者、场景、包含范围、排除范围、数据归属、权限、异常、成功标准
+   - 对需要领导/业务方拍板的规则、口径、优先级、例外、验收标准明确标记为"业务决策"
+
+5. **澄清技术方案边界**
+   - 确认受影响的层和主要技术选择,**不展开成完整设计 spec**
+   - **技术方案涉及既有代码改动时,做影响分析**——把 blast radius、直接调用方、受影响流程、风险等级(LOW/MEDIUM/HIGH/CRITICAL)报告给用户。HIGH/CRITICAL 风险必须先警告用户,再决定是否继续
+   - 当目标清楚但方案未定时,给 2-3 个可行方案 + 权衡 + 推荐方案;用户确认前不得把推荐方案写成已锁定技术方向
+   - 判断哪些技术决策必须在 spec/plan 前锁定,哪些可以留给后续实现做局部工程适配
+
+6. **总结并停止**
+   - 输出简洁的澄清总结(见「最终输出」)
+   - 提一句可能的下一步(写 PRD/spec/plan/实现),作为用户控制的选择,不自动继续
+   - 总结指向"实现"时,**根据任务规模推荐 `/implementation` 或 `/subagent-implement`**(见「下游实现 skill 选择」)
+
+## 任务类型路由
+
+任务类型是**默认脚手架,不是封闭枚举**。用它辅助推理——但当项目有更贴切的分类时,优先用项目的。
+
+**三条规则:**
+
+1. **默认类型不是封闭集合** —— 只是没有更具体项目分类时的基础路由
+2. **项目有领域特定分类时优先用项目的** —— 电商可能有 pricing/inventory/order-lifecycle,AI 产品可能有 model-behavior/evaluation/safety,金融可能有 compliance/audit/risk-control,基建可能有 observability/deployment/incident-response
+3. **请求不符合任何默认类型时,创建临时分类并说明理由**
+
+允许组合和重命名,例如:
+
+- primary: `subscription-billing-change`,secondary: `permission` + `workflow`
+- primary: `ai-evaluation-task`
+
+**默认任务类型(脚手架):**
+
+| 类型 | 含义 |
+|------|------|
+| `feature` | 新能力或业务功能 |
+| `change` | 修改现有行为 |
+| `bugfix` | 错误行为或生产问题 |
+| `workflow` | 业务流程或状态流转调整 |
+| `permission` | 角色、访问控制、可见性、审批权、数据范围 |
+| `integration` | 第三方或跨系统对接 |
+| `data-change` | 数据订正、迁移、初始化、导入导出、回填 |
+| `performance` | 速度、异步、扩展性、稳定性、超时、可靠性提升 |
+| `refactor` | 内部代码重构、架构清理、降依赖、可测试性提升 |
+| `ui-ux` | 页面、交互、展示、表单、空/加载/错误状态、体验改动 |
+| `unknown` | 信息不足以分类 |
+
+用主类型选主问题集。只在补充影响边界的问题时用次类型。
+
+**任务类型只为选问题服务,不是最终产出重点。** 用户关心的是意图、业务边界、技术边界,不关心分类本身。
+
+## 澄清策略
+
+按需使用这些策略。**不要每次都全跑一遍。**
+
+### 确认式澄清(默认)
+
+对齐事实和范围。
+
+问:
+
+- "我理解是..."
+- "这包含..."
+- "这不包含..."
+- "对吗?"
+
+### 苏格拉底式澄清
+
+当用户给了方案但没说目标、假设看起来有风险、请求可能在治标不治本、或表面方案可能比必要的更贵时使用。
+
+问:
+
+- 为什么现在需要这个变更
+- 提出的方案要解决什么问题
+- 这个方案是必需的还是只是一条可能的路径
+- 不做这个变更会怎样
+- 用户真正想优化哪个权衡
+
+### 头脑风暴式澄清
+
+当目标清楚但方案不清楚,或存在多个合理方案时使用。
+
+给 2-3 个选项 + 简短权衡,让用户选或调整。用户选定后,回到确认式澄清锁定边界。
+
+### 方案锁定式澄清
+
+当后续 plan 必须写死执行路径、但当前仍有多个业务/技术方案时使用。
+
+做法:
+
+- 先说明哪些决策不能留到实现期。
+- 给 2-3 个方案,每个方案说明业务影响、技术影响、风险和适用场景。
+- 可以明确推荐一个方案,但要说明推荐理由和放弃其他方案的原因。
+- 用户确认后,把结论写入"已锁定业务决策"或"已锁定技术方向"。
+- 用户未确认时,不得进入 spec/plan/implementation。
+
+## 通用问题池
+
+下面是**问题池,按需取用**,不是必问清单。跨任务类型,相关问题挑着用。
+
+- 我们在解决什么问题?
+- 为什么是现在?
+- 谁使用或受影响?
+- 包含哪些业务场景?
+- 明确排除哪些场景?
+- 哪些现有行为必须保持不变?
+- 创建、读取、更新、删除、导入、导出、迁移哪些数据?
+- 涉及哪些角色、权限、租户、组织、数据范围?
+- 重要的失败、空、重复、重试、回滚、边界情况有哪些?
+- 这个工作的最低成功标准是什么?
+- 必须尊重哪些约束?
+
+## Spec 就绪问题池
+
+下面的问题来自后续 spec 的必备信息。**不是必问清单**,但只要答案会影响 PRD/spec/plan 正确性,就应在澄清阶段前置解决,不要拖到写 spec 时才发现缺口。
+
+### 术语与业务对象
+
+- 需求中的关键名词在系统里对应哪个既有对象、状态、页面、接口或流程?
+- 是否存在容易混淆的同名概念?需要统一叫法吗?
+- 哪些业务对象是本次新增、变更或只读引用?
+
+### 业务规则与拍板项
+
+- 哪些规则必须由领导/业务方拍板?
+- 是否有优先级、冲突处理、例外规则或豁免场景?
+- 哪些规则是临时策略,哪些是长期机制?
+- 哪些业务口径不能留到实现期由 agent 判断?
+
+### 系统行为
+
+- 前置条件是什么?不满足时系统怎么表现?
+- 触发动作是什么?是用户动作、系统事件、接口调用还是定时任务?
+- 成功后用户、接口、下游系统分别看到什么结果?
+- 失败时是报错、忽略、重试、部分成功、回滚还是进入待处理状态?
+
+### 数据、状态与口径
+
+- 读取、创建、更新、删除、导入、导出、迁移或回填哪些数据?
+- 状态是否变化?状态枚举、状态含义和流转规则是什么?
+- 统计/计算口径是什么?维度、过滤条件、时间范围、去重规则、数据来源是什么?
+- 存量数据、历史状态、脏数据是否需要处理?
+
+### 权限、安全与审计
+
+- 哪些角色能看、能操作、能审批、能导出?
+- 数据范围按租户、组织、区域、账号、客户还是其他维度隔离?
+- 无权限时返回什么或展示什么?
+- 是否需要审计日志、操作记录、敏感数据脱敏或安全限制?
+
+### 接口、页面与系统边界
+
+- 影响哪些页面、接口、任务、队列、缓存、外部系统或报表?
+- 是新增能力、改旧能力,还是兼容旧能力后扩展?
+- 旧调用方、旧用户、旧数据是否必须保持兼容?
+- 真相源是当前系统、外部系统还是人工维护数据?
+
+### 异步、幂等、重试与一致性
+
+- 动作必须同步完成,还是允许异步处理?
+- 重复请求、重复点击、重复回调如何处理?
+- 外部系统失败时是否重试?重试次数、超时、人工兜底如何处理?
+- 是否允许最终一致?用户如何感知处理中、失败或部分成功状态?
+
+### 兼容性、迁移与灰度
+
+- 老数据、老接口、老流程是否保持不变?
+- 是否需要默认值、回填、迁移、dry-run、回滚或灰度?
+- 不兼容变更是否允许?需要谁确认?
+
+### 验收与测试关注点
+
+- 用户怎么判断"这件事做好了"?
+- 哪些主路径、边界、异常、权限、兼容性场景必须验收?
+- 哪些场景明确不测或不覆盖?为什么?
+
+### Plan 编写约束
+
+- 后续 plan 必须遵守哪些技术约束?
+- 哪些文件、模块、接口、表、状态、业务口径不能改?
+- 哪些方案已经被排除?
+- 哪些决策不能留到 implementation/subagent-implement 阶段?
+
+## 各类型关注点
+
+下面的关注点是**启发式提醒,不是必问清单**。用它们辅助判断,不要逐项审讯。
+
+**取用规则:**
+
+- 只问对理解意图/边界有实质影响的问题
+- 项目上下文或用户输入已经回答的,跳过
+- 代码库、领域、请求揭示的项目特定问题,主动加
+- 已经默认对齐的事实,不重复确认
+
+### `feature`
+
+关注:用户、入口、业务目标、输入输出、创建或变更的数据、与现有流程的连接、排除项、成功标准。
+
+### `change`
+
+关注:当前行为、期望行为、需保留的行为、兼容性、受影响的用户或调用方、迁移需求、灰度约束。
+
+### `bugfix`
+
+关注:观察到的行为、期望行为、复现路径、受影响范围、既有的脏数据、验证方法、是否需要预防。
+
+### `workflow`
+
+关注:触发事件、状态、流转、参与者、审批、可逆性、通知、异常处理、非目标。
+
+### `permission`
+
+关注:角色、允许的动作、可见性规则、数据隔离、默认权限、存量用户处理、审计需求、拒绝行为。
+
+### `integration`
+
+关注:外部系统、真相源、数据方向、同步 vs 异步、认证、重试、幂等、限流、回调、失败可见性。
+
+### `data-change`
+
+关注:目标数据、源数据、转换规则、dry-run 需求、回滚需求、在线影响、审计轨迹、验证。
+
+### `performance`
+
+关注:当前瓶颈、目标指标、用户体感、异步可行性、进度可见性、重试行为、一致性权衡、运维风险。
+
+### `refactor`
+
+关注:行为是否可能改变、重构目标、稳定的公开契约、高风险模块、测试预期、是否应分期。
+
+### `ui-ux`
+
+关注:目标用户、受影响的界面、当前痛点、期望交互、展示字段、校验、空/加载/错误状态、权限、数据范围。
+
+## 业务边界检查清单
+
+结束前,确保总结能回答:
+
+- 确认的意图
+- 业务目标
+- 用户或角色
+- 触发场景
+- 包含范围
+- 排除范围
+- 输入输出
+- 数据和状态变更
+- 权限和可见性边界
+- 重要的边界情况
+- 成功标准
+- 需要领导/业务方拍板的业务决策是否已明确
+
+## 技术边界检查清单
+
+结束前,确保总结能回答(相关时):
+
+- 受影响的前端、后端、数据库、job、队列、缓存、外部系统、基础设施
+- 是否预期新模型、表、字段、API、路由、任务、UI
+- 同步还是异步
+- 与既有数据、API、用户、工作流的兼容性
+- 迁移或回填预期
+- 日志、审计、安全、权限的影响
+- 性能、可靠性、一致性、运维约束
+- 应该或不应该引入的依赖
+- 哪些技术方向已锁定,哪些仍需后续探索
+- 哪些决策不能留到实现阶段
+
+## 决策分层
+
+澄清总结必须把决策分层,方便 PRD/spec/plan 直接消费:
+
+- **已锁定业务决策**:业务目标、范围、角色、规则、口径、权限、异常、验收等已由用户确认的内容。
+- **已锁定技术方向**:影响 spec/plan 正确性的系统边界、同步/异步、兼容、迁移、外部系统、风险处理等已确认方向。
+- **已排除方案 / 非目标**:明确不做的业务范围和技术路线。
+- **必须在 PRD/spec/plan 前解决的问题**:不解决会导致后续文档或计划不可靠的问题。
+- **后续阶段可处理的细节**:不影响业务决策、规格正确性和计划正确性的局部细节。
+
+不要把 agent 推荐但用户未确认的方案写进"已锁定"。
+
+## 终止条件
+
+**只在以下条件全满足时结束:**
+
+- 用户意图已确认
+- 业务边界已确认
+- 技术方案边界已确认
+- 主要非目标已确认
+- 决策账本已分层,且剩余 open 项不阻塞后续 PRD/spec/plan/实现
+- 已判断下一步是否可直接写 PRD/spec/plan,或是否需要先做探索
+- 用户明确说没补充、没纠正、或理解对了
+
+## 下游实现 skill 选择
+
+澄清总结指向"开始实现"时,根据任务规模推荐对应的实现 skill:
+
+| 维度 | `/implementation`(主会话顺序) | `/subagent-implement`(派子 agent) |
+|---|---|---|
+| 任务量 | 1-2 个简单任务 | ≥3 个任务 |
+| 文件域 | 单文件 / 单模块 | 跨 schema/backend/frontend/test 多域 |
+| 有 plan | 不一定需要,可基于 spec / 当前上下文直接做 | 需要(`docs/features/<feature-id>/plan/`) |
+| 上下文压力 | 实现过程不会挤爆主 agent 上下文 | 实现过程会挤爆主 agent 上下文,需要隔离 |
+| 审查模式 | 主 agent 自审 | 按风险派 spec-reviewer + quality-reviewer(最终) |
+| 隔离价值 | 任务太简单,派反而费 token | 任务复杂,隔离后主 agent 能聚焦协调 |
+
+**默认推荐**:
+- 简单任务(单点改动 / 1-3 文件 / 不需要多步审查)→ `/implementation`
+- 复杂 plan(多任务 / 跨域 / 需要双阶段审查)→ `/subagent-implement`
+
+边界情况(任务量 2-3 个、文件 3-5 个)由主 agent 根据 plan 是否存在 + 任务独立性判断。
+
+## 最终输出
+
+结束时,只输出一份澄清总结:
+
+```markdown
+**澄清总结**
+
+**确认的意图**
+...
+
+**已锁定业务决策**
+...
+
+**业务边界**
+...
+
+**明确的非目标**
+...
+
+**已锁定技术方向**
+...
+
+**技术方案边界**
+...
+
+**已排除方案**
+...
+
+**必须在 PRD/spec/plan 前解决的问题**
+...
+
+**后续阶段的决策**
+...
+
+**下游就绪判断**
+- PRD: 可写 / 需补充 ...
+- Spec: 可写 / 需补充 ...
+- Plan: 可写 / 需补充 ...
+- 是否需要先做代码/数据/接口探索: ...
+
+**用户控制的下一步**
+接下来你可以选择:
+- 写 PRD(`/write-prd`)
+- 起草 spec(`/write-spec`)
+- 创建实现计划(`/write-plan`)
+- 开始实现 —— 根据任务规模选(`/implementation` 简单 / `/subagent-implement` 复杂,详见「下游实现 skill 选择」)
+```
+
+**输出这份总结后,不再继续。** 不自动调用任何下游 skill,不写代码,不写文档。
+
+## 核心原则
+
+- **先理解再行动** —— 整个 skill 的核心价值
+- **循环式复述不能省** —— 第 3 步的循环是理解偏差的防线,用户没明确确认"没补充"不进下一步
+- **问题尽量前置** —— 会影响 PRD/spec/plan 正确性的业务规则、技术方向、数据口径、权限、异常和验收问题,不要拖到后续阶段才问
+- **发挥在前,执行在后** —— agent 的方案判断、权衡和挑战应在澄清/spec/plan 前释放;用户确认后进入下游,实现阶段不再重新设计
+- **任务类型是脚手架不是束缚** —— 默认类型只辅助推理;项目特定分类能更准确澄清请求时,优先用项目的分类替换或补充
+- **一次一轮,3-5 个高价值问题** —— 不淹没用户,不做清单审讯
+- **只问影响边界的问题** —— 只影响后续阶段细节的,记录为后续阶段决策,不问
+- **不编造** —— 用户无法明确的,标注【待确认】或列为后续阶段决策
+- **无情 YAGNI** —— 主动砍不必要的功能
+- **允许回跳** —— 后面阶段发现前面没搞清,退回去重新澄清
+- **简单任务轻量过** —— 不是每个任务都要死磕每一步,简单任务各阶段快速过

package/dist/.claude-template/skills/code-impact-api/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: code-impact-api
+description: 项目文档知识库查询入口 — 通过 cgraphx docs CLI 查询 docs/knowledge/ 下的业务决策、概念定义、历史教训。Use when 任务开始时 / 查业务概念 / 查历史决策 / 对齐术语 / 找相关文档 / 探索既有知识。
+---
+
+## 这个 skill 解决什么问题
+
+新任务开始时,**先查现有知识库**,在既有决策和概念基础上推进工作,而不是从零推断业务背景。
+
+典型场景:
+- "实现订单退订功能" → 先看是否已有退订决策文档,有则直接采纳
+- "对齐业务概念命名" → 看 concept 列表,用团队已有命名,避免造新词
+- "找相关文档" → 按 concept/domain/tag 过滤,定位最相关决策
+
+## 工具(由 cgraphx 提供,通过 CLI 调用)
+
+```bash
+cgraphx docs <subcommand> [options] [project-path]
+```
+
+| 操作 | 命令 |
+|---|---|
+| 全量扫描入库 | `cgraphx docs index [project-path]` |
+| 列出所有 concept | `cgraphx docs concepts [project-path]` |
+| 列出所有 domain | `cgraphx docs domains [project-path]` |
+| 列出所有 tag | `cgraphx docs tags [project-path]` |
+| 多维过滤查询 | `cgraphx docs find [project-path] --concept=X --domain=Y --tag=Z --status=active --type=decision --q=关键词 --limit=20` |
+| 文档引用关系 | `cgraphx docs refs <doc-id-or-path> [project-path]` |
+| 文档详情(摘要+元数据) | `cgraphx docs show <doc-id-or-path> [project-path]` |
+
+所有命令支持 `--json` 切换为机器可读格式。
+
+## 工作流(任务开始时)
+
+```
+1. cgraphx docs concepts
+   → 列出所有业务 concept(跨文档去重 + 关联文档数 + 所属 domain)
+   → 用语义匹配判断任务涉及的 concept 是否已存在
+
+2. 命中 concept 后:
+   cgraphx docs find --concept=<name>
+   → 返回该 concept 关联的所有文档,含:
+     - title / type / status / updated
+     - summary(Summary 章节内容,作为"是否需要读全文"的依据)
+     - path(项目根相对,用 Read 工具看全文)
+
+3. summary 够用 → 直接采纳,开始开发
+   summary 不够 → Read 返回的 path 原文,再判断
+```
+
+## 何时派子 agent(让上下文更干净)
+
+主 agent **直接调 cgraphx docs 工具时,大段原文(文档 Summary、find 返回的文档列表、docs/show 输出)会进自己的上下文**,挤占决策与待办的空间。本 skill 工具适合精确查询,但**模糊意图的重探索型任务**适合派子 agent 在隔离上下文里跑。
+
+### 判断规则(R4:目标精度)
+
+主 agent **已知精确目标**(具体 concept / 文档 id / 关键词)→ **不派**,直接调上面工具;主 agent **只有模糊意图**(系统理解 / 梳理 / 调研型)→ **派**。
+
+具体例子:
+
+| 场景 | 不派(直接调工具) | 派(派子 agent) |
+|---|---|---|
+| 找具体决策 | "订单退订的决策文档有没有" → `cgraphx docs find --q=退订` | "调研订单业务的全部决策" |
+| 看 concept | "X concept 在哪些文档里" → `cgraphx docs find --concept=X` | "梳理 X 业务的所有 concept 和它们的关系" |
+| 单文档详情 | "show 一下 decision-001.md" → `cgraphx docs show decision-001.md` | "系统理解这块业务为什么这么做,把所有相关决策串起来" |
+
+### 派的方法(决定派时执行)
+
+1. **Read** 本 skill 目录下的 `./agent-prompt.md`
+2. **Agent tool 调用**:
+   ```
+   Agent({
+     subagent_type: "general-purpose",
+     prompt: <agent-prompt.md 文件内容> + "\n\n当前任务: " + <用户原话或你的转述>
+   })
+   ```
+3. **直接采纳**子 agent 返回的提炼结论 —— 不要再自己调 `cgraphx docs find/show` 重新查(那是浪费)
+4. 结论不够 → 再派一次(换 prompt 重点,如"重点看 decision 之间的关系")或回头自己调工具补
+
+### 代价
+
+- **不派的代价**:大段 Summary / find 列表进主上下文,后续决策可用 budget 变小
+- **派的代价**:子 agent 本身耗 token,简单查询派反而更贵
+- **R4 是平衡点**:只在"模糊意图 + 主 agent 无法精确判断目标"时派
+
+## 工作流(查文档间引用)
+
+```
+cgraphx docs refs docs/knowledge/decision-001.md
+→ 输出双向引用:
+  Outgoing: 这份文档引用了哪些
+  Incoming: 哪些文档引用了这份
+```
+
+适合"这个决策被谁引用了"、"还有哪些相关文档"。
+
+## 索引管理
+
+文档变更后**必须重新触发扫描**(覆盖式重建,不走增量):
+
+```bash
+cgraphx docs index              # 全量扫 docs/knowledge/,事务性覆盖
+```
+
+什么时候跑:
+- 写了新 .md 到 docs/knowledge/
+- 修改了已有 .md 的 frontmatter 或 Summary
+- 删除了 .md
+- 重新 clone 仓库后
+
+不需要跑:
+- 改了 .md 的非 Summary 章节(那些不进索引,改完直接 Read 就行)
+
+## 文档规范要点(写新文档时遵守,详见 code-impact-markdown skill)
+
+frontmatter **7 必填**(缺一即被跳过):`title` / `document_type` / `domains` / `concepts` / `status` / `source_type` / `updated`
+
+**章节**:**只有 `## Summary`(或 `## 摘要`)进索引**,其他章节留文件里,AI 想看就 Read。
+
+详细 frontmatter 枚举值、稳定标题、命名规则、模板 → 见 `code-impact-markdown` skill。
+
+## 关键词搜索(中文友好)
+
+`cgraphx docs find --q=关键词` 走 **LIKE 子串匹配**(不用 FTS5,因为 SQLite 默认 tokenizer 对中文不友好)。任何中文/英文 substring 都能命中 title 或 Summary。
+
+## 排除范围(明确不做)
+
+- ❌ 不扫 `docs/knowledge/` 之外(README、CHANGELOG、第三方文档一律忽略)
+- ❌ 不存文档全文(只存 title + Summary + 元数据 + 关系;其他章节 AI 自己 Read)
+- ❌ 不修改文档(变更只能由人/AI 写文件后重新 `docs index`)
+- ❌ 不与代码索引打通(文档不会自动建立到代码符号的反向链接)
+- ❌ 不预计算 concept↔concept 关联(AI 从 find 返回的 concepts 列表自己推断)
+
+## 探索结果收口(给 clarify/spec/plan)
+
+只有当本 skill 用于需求澄清、spec 或 plan 前置探索时,才做简短收口。简单精确查询(如"有没有某个决策文档")可以直接回答,不套模板。
+
+按需使用以下 4 项,无内容可省略:
+
+- **查到的关键事实**:历史决策、状态、适用范围、关键规则、引用路径、团队已有术语。
+- **对决策的影响**:哪些规则应继承、排除、更新,哪些需要领导/业务方重新拍板。
+- **应进入 PRD/spec/plan 的内容**:已确认业务规则、非目标、兼容性要求、不可改动旧行为、必须复用机制等。
+- **仍不确定/需确认**:历史文档过期、状态非 active、概念冲突或需要用户确认的部分。

package/dist/.claude-template/skills/code-impact-api/agent-prompt.md

@@ -0,0 +1,51 @@
+# code-impact-api 探索子 agent prompt(docs/knowledge/ 业务知识探索)
+
+> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接 `\n\n当前任务: <用户原话>`。
+
+## 你的角色
+
+你是 docs/knowledge/ 业务知识探索子 agent。你在**隔离上下文**里跑,主 agent **看不到你的中间过程**(工具调用、文档 Summary 原文),**只拿到你的最终返回**。
+
+主 agent 派你来是因为它收到一个**模糊意图的重探索型任务**(如"调研订单业务的所有决策 / 梳理 X 业务的所有 concept / 系统理解这块业务为什么这么做"),需要遍历多篇文档才能给结论。你的产出会被主 agent **直接采纳**,不需要它再回头查。
+
+## 可用工具
+
+| 工具 | 用途 |
+|---|---|
+| `cgraphx docs concepts` | 列出所有业务 concept(跨文档去重 + 关联文档数 + 所属 domain) |
+| `cgraphx docs domains` | 列出所有 domain |
+| `cgraphx docs tags` | 列出所有 tag |
+| `cgraphx docs find --concept=X --domain=Y --tag=Z --q=关键词 --limit=20` | 多维过滤查询,返回 title / type / status / summary / path |
+| `cgraphx docs show <doc-id-or-path>` | 单文档详情(摘要 + 元数据) |
+| `cgraphx docs refs <doc-id-or-path>` | 文档双向引用(Outgoing + Incoming) |
+| `Read` | 读 docs/knowledge/*.md 全文(summary 不够时) |
+
+## 探索策略
+
+1. **先 `cgraphx docs concepts`** 看全局 concept 清单,语义匹配任务涉及的 concept
+2. 命中 concept → `cgraphx docs find --concept=X` 拿关联文档清单(含 Summary)
+3. **不要立即 Read 全文** —— 先看 find 返回的 Summary,够用就直接用
+4. Summary 不够 → `cgraphx docs show <id>` 或 `Read` 全文(只读你确定需要的)
+5. 跨文档关系 → `cgraphx docs refs <id>` 看引用图
+6. **不要遍历所有文档** —— 任务范围内够用就停
+
+## 输出格式
+
+至少包含:
+
+- **命中的 concept / domain 清单**:每个给 `名字 + 一句话定义(从关联文档 Summary 提炼)`
+- **相关决策文档清单**:每篇给 `title + 一句话核心结论 + path(主 agent 需要时自己读)`
+- **关键发现 / 团队既有约定**:主 agent 决策时需要遵守的(如"团队已决定用 X 方案,不要再造新轮子")
+
+不要输出:
+
+- 大段 Summary 原文 / 文档全文引用
+- 中间探索步骤 / 工具调用日志
+- "我尝试了 X 但失败"这种过程噪声 —— 失败的直接说"X 不存在 / 未找到"
+- 你不确定的内容(用"【不确定】X,建议主 agent 验证"标记)
+
+## 约束
+
+- **不要修改任何文件** —— 你是只读探索,Edit/Write 工具不要调;特别**不要修改 docs/knowledge/ 下任何 .md**(变更由人/主 agent 决定后再走 code-impact-markdown skill)
+- **不要假设主 agent 知道你的中间步骤** —— 你的 final message 就是它看到的全部
+- **不要建议主 agent 派第二次子 agent** —— 一次没答完整就再探索几次,超出能力直接说