cgraphx 1.4.1 → 2.0.0

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

@@ -1,91 +1,41 @@
 ---
 name: clarify-requirements
-description: 用户给一段话描述(模糊想法/领导式指令/产品想法/业务变更/bug 报告/重构请求/对接请求/数据任务/UI 改动/技术提案)时,在写 PRD/spec/plan/代码之前先澄清。扮演顶级程序员 + 业务专家,像员工接领导任务那样——先了解项目上下文、确认意图、识别任务类型、针对性提问、必要时挑战假设、有用时头脑风暴有限选项,在用户确认业务边界和技术方案边界后停止。不写 PRD/spec/plan/代码,后续动作由用户自决。触发词:想做、想法、需求、新功能、做一下、加一个、帮我想、实现一下、有个想法、帮我做、调整、改一下。
+description: 用户给一段话描述(模糊想法/领导式指令/产品想法/业务变更/bug 报告/重构请求/对接请求/数据任务/UI 改动/技术提案)时,在写 PRD/spec/plan/代码之前先澄清。扮演顶级程序员 + 业务专家,像员工接领导任务那样——先了解项目上下文、确认意图、识别任务类型、针对性提问、必要时挑战假设、有用时头脑风暴有限选项,在用户确认业务边界和技术约束后停止;也可对已有想法/决策/方案做**拷问式**单问澄清。实现手段的选型不在本阶段拍板(归 plan)。不写 PRD/spec/plan/代码,后续动作由用户自决。触发词:想做、想法、需求、新功能、做一下、加一个、帮我想、实现一下、有个想法、帮我做、调整、改一下、拷问、压力测试、grill、这方案靠谱吗。
 ---
 
 # 澄清需求 (Clarify Requirements)
 
 ## 定位
 
-这是一个**事前理解与决策锁定协议**。把用户模糊或不完整的请求,变成确认的意图、业务边界、技术方案边界和下游 PRD/spec/plan 可直接消费的决策输入。
-
-**角色:顶级程序员 + 业务专家。** 像员工接到领导的任务安排——在做之前先搞清楚领导到底要做什么,哪些要做,哪些不要做;同时主动提出更优方案、挑战不稳假设,但所有关键业务和技术方向必须由用户确认后才能进入下游。
+- **事前理解 + 决策锁定**:把模糊请求变成锁定的意图、业务边界、技术约束——spec 的输入。像员工接领导任务:先搞清到底要做什么、哪些不做,主动挑战不稳假设,但拍板权永远在用户。
+- **读无界,决策有界**:代码、数据模型、知识库尽管读(不读暴露不了真问题:维度可不可得模型说了算,读了代码才知道"系统已按周统计",定义题变确认题);但只锁定**业务决策和用户声明的技术约束**。实现手段选型(同步/异步、缓存、定时任务、选型、表设计)不在此拍板,归 plan 结合代码规划。
+- **容忍度是业务边界,不是手段**:问"能容忍多久延迟、数据能容忍多旧",不问"用同步还是异步"。不问清容忍度,plan 选手段就只能猜。
+- **判别标准**:业务拍板人能回答 → 这里问;需要代码现实才能回答 → 留给 plan。
 
 <HARD-GATE>
-在用户确认业务边界和技术方案边界之前,不要写 PRD、不要写详细 spec、不要写实现计划、不要写代码、不要搭建项目脚手架、不要采取任何实现动作。这适用于每一个任务,无论它看起来有多简单。
-不要妄下断言。不要掩饰困惑。坦诚地权衡利弊。
+用户确认业务边界之前:不写 PRD/spec/plan/代码,不搭脚手架,不采取任何实现动作。无论任务看起来多简单。
+**只有用户能锁定决策**——推荐不是确认,拍板才算。
+不妄下断言,不掩饰困惑,坦诚权衡。
 </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` — 查 历史决策、业务概念、项目经验时必须使用
-     - `db-query skill` — 查数据库、查 DDL 时必须使用
-     - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` 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. **知识库召回** —— 会话中没用过 `knowledge-recall` 则提示先聊相关概念;命中的实体主条目 = 第 2 步代码阅读的入口。
+2. **探索上下文(读无界)** —— 按需读项目结构/文档/代码/测试/schema/模型/API;`db-query`(查库/DDL 必须用)、grep/Read(调用关系必须用),调用前告知用户,收集完简要陈述。**路径:从实体主条目的代码入口 + 相关表指针进代码,不盲目全局搜。产物是问题和事实,不是方案**——冒出的手段念头记入"留给 plan",不在此展开。
+3. **分类任务** —— 选一个主类型(脚手架,见下)。
+4. **确认初步理解** —— 结构化复述(意图/怀疑的目标/受影响区域/初步范围)+ "**这是你的意思吗?有什么要补充或纠正?**" 用户没明确说"没补充"之前,不进锁定。
+5. **澄清业务边界** —— 目标/参与者/场景/包含与排除/数据归属/权限/异常/成功标准;**口径**(统计维度/时间范围/过滤/去重)与**容忍度**(延迟/新鲜度/一致性预期/中间状态感知)必须锁定;需领导拍板的规则标记"业务决策"。
+6. **识别技术约束与影响(不选手段)** —— 只收三类:① 用户声明的技术约束(如实记录,不代展开);② 兼容性边界(旧 API/旧数据/旧调用方哪些不动);③ 影响半径与风险(blast radius/直接调用方/风险等级,HIGH/CRITICAL 先警告再定)。业务方案可给 2-3 选项 + 推荐,推荐不是锁定;手段选项不在此辩论,记入总结。
+7. **总结并停止** —— 输出澄清总结(见「决策分层」),下一步交用户选,不自动继续;总结指向实现时按规模推荐 `/implementation`(简单)或 `/subagent-implement`(复杂)。
 
 ## 任务类型路由
 
-任务类型是**默认脚手架,不是封闭枚举**。用它辅助推理——但当项目有更贴切的分类时,优先用项目的。
-
-**三条规则:**
-
-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`
-
-**默认任务类型(脚手架):**
+脚手架,不是封闭枚举:项目有领域特定分类(电商 pricing/inventory、金融 compliance/audit 等)优先用项目的;无匹配时创建临时分类并说明理由。
 
 | 类型 | 含义 |
-|------|------|
+|---|---|
 | `feature` | 新能力或业务功能 |
 | `change` | 修改现有行为 |
 | `bugfix` | 错误行为或生产问题 |
@@ -93,344 +43,86 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 | `permission` | 角色、访问控制、可见性、审批权、数据范围 |
 | `integration` | 第三方或跨系统对接 |
 | `data-change` | 数据订正、迁移、初始化、导入导出、回填 |
-| `performance` | 速度、异步、扩展性、稳定性、超时、可靠性提升 |
-| `refactor` | 内部代码重构、架构清理、降依赖、可测试性提升 |
-| `ui-ux` | 页面、交互、展示、表单、空/加载/错误状态、体验改动 |
+| `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`
+启发式,不是清单;上下文已答的跳过,项目特定的主动加。
 
-关注:行为是否可能改变、重构目标、稳定的公开契约、高风险模块、测试预期、是否应分期。
+- **feature**:用户、入口、业务目标、输入输出、创建或变更的数据、与现有流程的连接、排除项、成功标准。
+- **change**:当前行为、期望行为、需保留行为、兼容性、受影响调用方、迁移/灰度约束。
+- **bugfix**:观察到的行为、期望行为、复现路径、影响范围、脏数据、验证方法、是否预防。
+- **workflow**:触发事件、状态、流转、参与者、审批、可逆性、通知、异常、非目标。
+- **permission**:角色、动作、可见性、数据隔离、默认权限、存量用户、审计、拒绝行为。
+- **integration**:外部系统、真相源、数据方向、失败/重试/时效的业务容忍度(对接手段归 plan)、认证归属、回调可见性。
+- **data-change**:目标/源数据、转换规则、dry-run、回滚、在线影响、审计、验证。
+- **performance**:当前瓶颈、目标指标、用户体感、一致性容忍度(异步与否归 plan)、进度可见性、运维风险。
+- **refactor**:行为是否可能变、目标、稳定公开契约、高风险模块、测试预期、是否分期。
+- **ui-ux**:目标用户、受影响界面、痛点、期望交互、展示字段、校验、空/加载/错误状态、权限、数据范围。
 
-### `ui-ux`
+## 澄清策略(按需)
 
-关注:目标用户、受影响的界面、当前痛点、期望交互、展示字段、校验、空/加载/错误状态、权限、数据范围。
+- **苏格拉底单问(默认节奏)**:沿决策树一个分支一个分支走,**一次只问一个决策**,**每问先给推荐答案**,用户确认或纠正后再进下一问。**事实自己查、只问决策**(同定位「读无界,决策有界」);简单任务的琐碎确认可一并问,实质决策逐一单问。典型追问:为什么是现在?要解决什么问题?必需还是只是一条路径?不做会怎样?想优化哪个权衡?
+- **确认式(锁定)**:一个分支问完后用"我理解是…… / 包含…… / 不包含…… / 对吗?"收口。
+- **头脑风暴**(目标清楚但**业务方案**不清):2-3 选项 + 权衡 + 推荐,选定后回确认式锁定。手段方案不适用——归 plan。
 
-## 业务边界检查清单
+## 问题池
 
-结束前,确保总结能回答:
+按需取用,不是必问清单;上下文已回答的跳过。
 
-- 确认的意图
-- 业务目标
-- 用户或角色
-- 触发场景
-- 包含范围
-- 排除范围
-- 输入输出
-- 数据和状态变更
-- 权限和可见性边界
-- 重要的边界情况
-- 成功标准
-- 需要领导/业务方拍板的业务决策是否已明确
+- **意图与范围**:解决什么问题?为什么是现在?谁受影响?包含/排除哪些场景?哪些现有行为不许变?最低成功标准?
+- **术语与对象**:关键名词对应系统里哪个既有对象/状态/流程(有实体主条目以它为准)?易混同名?本次新增/变更/只读引用?
+- **规则与口径**:哪些规则要领导拍板?优先级/冲突/例外?口径:维度/过滤/时间范围(按周/按月/当前月/滚动 N 天)/去重/数据来源?临时策略 vs 长期机制?
+- **行为与容忍度**:前置条件与触发(周期多少是业务定,用不用定时任务是 plan 定)?成功后各方看到什么?失败行为(报错/重试/回滚/待处理,哪些可接受是业务定)?结果可接受延迟多久?数据可接受多旧?重复请求允许重复结果吗?用户需要中间状态吗?外部失败可接受挂起重试吗?
+- **权限与审计**:哪些角色能看/操作/审批/导出?隔离维度?无权限返回什么?审计/脱敏?
+- **边界与兼容**:影响哪些页面/接口/任务/外部系统?新增/改旧/兼容后扩展?旧调用方/旧用户/旧数据兼容?真相源在哪?回填/灰度/回滚?
+- **数据与状态**:读写/迁移哪些数据?状态枚举与流转?存量/脏数据处理?
+- **验收**:怎么判断"做好了"?必验收场景?明确不测什么?
+- **Plan 约束**:哪些文件/模块/接口/表/口径不能动?哪些方案已排除?
 
-## 技术边界检查清单
+## 决策分层(即总结结构)
 
-结束前,确保总结能回答(相关时):
+结束时只输出一份澄清总结,按下列分层——**这份总结是 spec 的输入,不是契约:决策只有写进 spec 才成为义务**。输出后停止,不自动调任何下游。
 
-- 受影响的前端、后端、数据库、job、队列、缓存、外部系统、基础设施
-- 是否预期新模型、表、字段、API、路由、任务、UI
-- 同步还是异步
-- 与既有数据、API、用户、工作流的兼容性
-- 迁移或回填预期
-- 日志、审计、安全、权限的影响
-- 性能、可靠性、一致性、运维约束
-- 应该或不应该引入的依赖
-- 哪些技术方向已锁定,哪些仍需后续探索
-- 哪些决策不能留到实现阶段
+- **确认的意图**
+- **已锁定业务决策**(目标/范围/角色/规则/口径/权限/异常/验收)
+- **业务边界与容忍度**(延迟/新鲜度/一致性预期)
+- **明确的非目标**
+- **已锁定技术约束**(用户声明 + 兼容性边界;无则写"无特别约束")
+- **影响半径与风险**(相关时;LOW/MEDIUM/HIGH/CRITICAL)
+- **留给 plan 的手段决策**(识别到但不在此拍板;纯工程手段 plan 自主定,有业务可观察后果的 plan 会回跳 spec 业务拍板)
+- **必须在 spec 前解决的问题** / **后续阶段的决策**
+- **下游就绪判断**:Spec 可写否 / Plan 可写否 / 是否需先探索
+- **用户控制的下一步**:`/write-spec` · `/write-plan` · 开始实现(`/implementation` 简单 / `/subagent-implement` 复杂) · `/write-prd`(发布后按需) · `/write-api-doc`(接口开发完毕后,可选) · `/write-design-doc`(发布后按需)
 
-## 决策分层
-
-澄清总结必须把决策分层,方便 PRD/spec/plan 直接消费:
-
-- **已锁定业务决策**:业务目标、范围、角色、规则、口径、权限、异常、验收等已由用户确认的内容。
-- **已锁定技术方向**:影响 spec/plan 正确性的系统边界、同步/异步、兼容、迁移、外部系统、风险处理等已确认方向。
-- **已排除方案 / 非目标**:明确不做的业务范围和技术路线。
-- **必须在 PRD/spec/plan 前解决的问题**:不解决会导致后续文档或计划不可靠的问题。
-- **后续阶段可处理的细节**:不影响业务决策、规格正确性和计划正确性的局部细节。
-
-不要把 agent 推荐但用户未确认的方案写进"已锁定"。
+不要把 agent 推荐但用户未确认的写进"已锁定"。
 
 ## 终止条件
 
-**只在以下条件全满足时结束:**
-
-- 用户意图已确认
-- 业务边界已确认
-- 技术方案边界已确认
-- 主要非目标已确认
-- 决策账本已分层,且剩余 open 项不阻塞后续 PRD/spec/plan/实现
-- 已判断下一步是否可直接写 PRD/spec/plan,或是否需要先做探索
-- 用户明确说没补充、没纠正、或理解对了
+意图 ✓ 业务边界(含口径、容忍度)✓ 技术约束已识别 ✓ 主要非目标 ✓ 账本分层且剩余 open 项不阻塞 spec ✓ 用户明确说没补充/理解对了。全满足才结束。
 
 ## 下游实现 skill 选择
 
-澄清总结指向"开始实现"时,根据任务规模推荐对应的实现 skill:
-
-| 维度 | `/implementation`(主会话顺序) | `/subagent-implement`(派子 agent) |
+| 维度 | `/implementation` | `/subagent-implement` |
 |---|---|---|
 | 任务量 | 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 是否存在 + 任务独立性判断。
-
-**事后沉淀环节(可选,不在实现前)**:无论选 `/implementation` 还是 `/subagent-implement`,实现推进过程中可按需触发两个事后文档 skill:
-
-| skill | 触发时机 | 产物 | 主题 |
-|---|---|---|---|
-| `/write-api-doc` | 接口开发完毕(不必等所有自测) | `<文件前缀>-接口文档.html` | 仅本次 feature 新增的接口;从 spec 接口章节 + 代码反向提取 |
-| `/code-impact-docgen` | 自测通过后 | `<文件前缀>-设计文档.md` | 整个 feature 的设计(架构/模块/决策);从 knowledge + spec + plan 合成 |
-
-两者互不替代:同一 feature 可以同时产出接口文档和设计文档,各自服务不同读者。默认输出路径都在 `docs/features/<feature-id>/`。
-
-## 最终输出
-
-结束时,只输出一份澄清总结:
-
-```markdown
-**澄清总结**
-
-**确认的意图**
-...
-
-**已锁定业务决策**
-...
-
-**业务边界**
-...
-
-**明确的非目标**
-...
-
-**已锁定技术方向**
-...
-
-**技术方案边界**
-...
-
-**已排除方案**
-...
-
-**必须在 PRD/spec/plan 前解决的问题**
-...
-
-**后续阶段的决策**
-...
-
-**下游就绪判断**
-- PRD: 可写 / 需补充 ...
-- Spec: 可写 / 需补充 ...
-- Plan: 可写 / 需补充 ...
-- 是否需要先做代码/数据/接口探索: ...
-
-**用户控制的下一步**
-接下来你可以选择:
-- 写 PRD(`/write-prd`)—— 产物 `<文件前缀>-需求文档.md`
-- 起草 spec(`/write-spec`)—— 产物 `<文件前缀>-spec.md`
-- 创建实现计划(`/write-plan`)—— 产物 `plan/<文件前缀>-index.md` 等
-- 开始实现 —— 根据任务规模选(`/implementation` 简单 / `/subagent-implement` 复杂,详见「下游实现 skill 选择」)
-- 接口开发完毕后 —— 用 `/write-api-doc` 生成 `<文件前缀>-接口文档.html`(只覆盖新增接口,可选)
-- 自测通过后 —— 用 `/code-impact-docgen` 生成 `<文件前缀>-设计文档.md` 沉淀到 feature 目录(可选)
-```
+| 文件域 | 单文件/单模块 | 跨 schema/backend/frontend/test 多域 |
+| 有 plan | 不必,可基于 spec/上下文直接做 | 需要 |
+| 上下文压力 | 不会挤爆主 agent | 会挤爆,需隔离 |
+| 审查 | 主 agent 自审 | 按风险派 spec-reviewer + 最终 quality-reviewer |
 
-**输出这份总结后,不再继续。** 不自动调用任何下游 skill,不写代码,不写文档。
+默认:简单(单点/1-3 文件)→ `/implementation`;复杂(多任务/跨域)→ `/subagent-implement`;边界情况看 plan 是否存在 + 任务独立性。事后文档(发布后按需):`/write-prd`(业务方审阅)· `/write-api-doc`(接口开发完毕,仅新增接口)· `/write-design-doc`(设计文档)。
 
-## 核心原则
+## 红线(绝对不能做)
 
-- **先理解再行动** —— 整个 skill 的核心价值
-- **循环式复述不能省** —— 第 3 步的循环是理解偏差的防线,用户没明确确认"没补充"不进下一步
-- **问题尽量前置** —— 会影响 PRD/spec/plan 正确性的业务规则、技术方向、数据口径、权限、异常和验收问题,不要拖到后续阶段才问
-- **发挥在前,执行在后** —— agent 的方案判断、权衡和挑战应在澄清/spec/plan 前释放;用户确认后进入下游,实现阶段不再重新设计
-- **任务类型是脚手架不是束缚** —— 默认类型只辅助推理;项目特定分类能更准确澄清请求时,优先用项目的分类替换或补充
-- **一次一轮,3-5 个高价值问题** —— 不淹没用户,不做清单审讯
-- **只问影响边界的问题** —— 只影响后续阶段细节的,记录为后续阶段决策,不问
-- **不编造** —— 用户无法明确的,标注【待确认】或列为后续阶段决策
-- **无情 YAGNI** —— 主动砍不必要的功能
-- **允许回跳** —— 后面阶段发现前面没搞清,退回去重新澄清
-- **简单任务轻量过** —— 不是每个任务都要死磕每一步,简单任务各阶段快速过
+1. ❌ **不在此拍板实现手段** —— 同步/异步、缓存、定时任务、选型、表设计归 plan;本阶段只收用户声明的约束。
+2. ❌ **不跳过复述锁定** —— 用户没明确说"没补充/理解对了",不进决策锁定。
+3. ❌ **不编造** —— 无法明确的标【待确认】或列为后续阶段决策。
+4. ❌ **不把未确认推荐写进"已锁定"**。
+5. ❌ **不自动继续下游** —— 输出总结即停;写什么、做不做,归用户。
+6. ❌ **不放行不必要功能** —— YAGNI,主动砍。

package/dist/.claude-template/skills/developer-timeline/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: developer-timeline
+disable-model-invocation: true
 description: 基于 Developer Timeline 事件流生成日报、周报、月报、阶段总结、工作复盘、交付汇报和使用习惯分析。Use when 日报/周报/月报/工作总结/最近做了什么/上周做了什么/这个月干了啥/开发历史/会话历史/使用习惯分析/效率分析/工具使用统计/工作节奏/修改过什么/最近改过/上次什么时候改/git 提交历史/开发统计。当用户问"我/你最近做了什么"或要求报告时优先用本 skill。
 ---
 
@@ -286,14 +287,14 @@ cgraphx timeline show <id>
 | 想知道 | 用 |
 |---|---|
 | 代码结构、调用关系 | `cgraphx` skill |
-| 业务决策、概念定义 | `code-impact-api` skill |
+| 业务决策、概念定义 | `knowledge-api` skill |
 | 数据库数据 | `db-query` skill |
 | 开发活动历史、报告、习惯分析 | 本 skill |
 | 只要 commit 列表 | `git log` 更轻量 |
 
 ## 前置条件和失败处理
 
-- 项目必须 `cgraphx init`。
+- 项目必须已 `cgraphx install`(会建 `.cgraphx/`)。
 - Timeline hooks 必须安装(`cgraphx timeline install` 或 `cgraphx install`)。
 - Kill-switch:`CGRAPHX_NO_TIMELINE=1` 时 hooks 静默不记录。
 - 如果 timeline 无数据,说明原因并建议检查 hooks;可以退化到 `git log` + 当前工作区状态,但必须标明覆盖不足。

package/dist/.claude-template/skills/export-table-ddl/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: export-table-ddl
+disable-model-invocation: true
 description: 导出项目用到的全部数据库表的 DDL 到可检索目录(按工程分目录,每工程一个 INDEX.md 列表名+注释,details 目录放完整建表语句)。Use when 导出表结构/导出DDL/导出建表语句/拉表结构/批量查DDL/项目表清单/数据库表导出/dump schema/导出全部表.
 ---
 
@@ -133,13 +134,13 @@ node <skill-dir>/scripts/export-ddl.mjs \
 
 ## 闭环:和 db-query skill 配合
 
-本 skill 建**基线**(DDL + 列注释 + 表注释 + 索引,来自 DB),`db-query` skill 在日常查数据时**补充**探索发现:
+**全量保鲜的分工**:日常开发改模型 → 开发流程**写透**(全量 `ddl/<表名>.sql` 直接改到最终态,增量流水记在需求目录 `sql/`,见项目 `docs/guides/data-standards.md`「Schema 变更约定」节);本 skill 建**基线**并做**周期校准**(初始化、全量重导、漂移复核,DDL + 列注释 + 表注释 + 索引来自 DB);`db-query` 在日常查数据时**补充**探索发现:
 
 ```
 export-table-ddl  →  docs/schema-knowledge/<project>/ddl/<table>.sql  (基线 DDL)
        ↑                          ↑ 重 dump 保留
        │                          │
-       └──── schema 变了重跑 ────┘
+       └── 周期校准 / 漂移重跑 ──┘
                                   │
 db-query 探索踩坑 → append DISCOVERED 块(隐式关系/字段含义/陷阱/流程)
 ```

package/dist/.claude-template/skills/handdrawn-deck/.cgraphx/timeline-current-turn.json

@@ -0,0 +1 @@
+{"turn_id":"ce0a807e-1b19-4522-81e4-343c054f94ed","session_id":"0255b490-e883-4864-b8dd-c202719fe42f","ts":"2026-08-01T05:10:37.301Z"}