cgraphx 1.1.0

package/dist/.claude-template/skills/db-query/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: db-query
+description: 数据库探索方法论 — 通过 cgraphx db CLI 查数据(MySQL + PostgreSQL),沉淀业务知识到 docs/schema-knowledge/。Use when 查数据库/查数据/SQL查询/查表/表结构/DDL/查表结构/验证数据/获取测试数据。
+---
+
+## 工具(由 cgraphx 提供,通过 CLI 调用)
+
+```bash
+cgraphx db <subcommand> [options]
+```
+
+| 操作 | 命令 | 关键参数 |
+|---|---|---|
+| 列已配置 profiles | `cgraphx db profiles` | — |
+| 跑 SELECT | `cgraphx db query` | `--sql "SELECT ..."` `--profile <name>?` `--limit <n>?`(自动 LIMIT,默认 100,上限 1000) |
+| 查表结构 | `cgraphx db schema` | `--mode ddl --table <name> [--profile <name>]` |
+| 列所有表 | `cgraphx db schema` | `--mode tables [--profile <name>]` |
+| 查索引 | `cgraphx db schema` | `--mode indexes --table <name>` |
+| 查表注释 | `cgraphx db schema` | `--mode table-comment --table <name>` |
+
+输出格式:所有命令支持 `--format json|table|csv`(schema 命令固定 json)。
+
+**`ddl` 模式输出字段**:每字段一行,含 `field_name` / `data_type` / `nullable` / `default_value` / `key_type`(PRI/UNI/MUL) / `comment`(字段业务注释) / `fk_table`+`fk_column`(外键关联,如有)。**这是判断表关系的首选信息源** —— 数据库本身定义的外键 + 业务专家写的注释都在这。
+
+## 配置位置
+
+- 项目级:`.cgraphx/db-profiles.json`(优先)
+- 用户级:`~/.cgraphx/db-profiles.json`
+- 禁用整个子系统:`CGRAPHX_DB_QUERY_DISABLED=1` 或 profiles 文件里 `"enabled": false`(禁用时所有命令输出 "数据库无法连接,请以代码中查询为准" 到 stderr,exit code 4,不实际连库)
+- 退出码:0 成功 / 2 配置错误 / 3 安全拦截(写操作) / 4 连接/超时/禁用 / 5 参数错误
+
+profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数、可选 `description`。**密码永不输出**。
+
+## 使用原则
+
+1. **必须先确定目标库避免连错** — 先 `cgraphx db profiles` 列出,确认目标 profile
+2. **所有查询只读**(铁律,不可破) — 子系统内置禁止 DELETE/UPDATE/INSERT/DROP/ALTER,只读永不改变数据库
+3. **必须带 LIMIT** — `cgraphx db query` 自动 LIMIT,但自定义 SQL 仍建议显式 `LIMIT N`
+4. **先看表结构再写 SQL** — 用 `schema --mode ddl` 看字段、注释、外键,避免字段名拼写错误或类型不匹配
+5. **陌生 schema 探索"先问后试"** — 不确定表关系或字段含义时,**先问业务专家**,不要埋头反复试错(试错既浪费 token,也可能拿错数据误导后续判断)
+6. **复用 DAO 时验证参数** — 修改 Mapper XML 中的查询条件前,先用真实数据确认字段值分布
+
+## 典型查询流程(已知 schema)
+
+```
+0. cgraphx db profiles                                  → 确认连接哪个库哪个 profile
+1. cgraphx db schema --mode ddl --table work_order      → 看字段、注释、外键
+2. cgraphx db query --sql "SELECT * FROM ... LIMIT 5"   → 用 LIMIT 查样本数据
+3. 确认字段值分布                                          → 编写/修改代码
+```
+
+## 陌生 schema 探索流程(不知道表关系时)
+
+按以下优先级链尝试,**每步失败才进入下一步**:
+
+```
+1. cgraphx db schema --mode ddl --table A
+   cgraphx db schema --mode ddl --table B
+   → 看 fk_table/fk_column(数据库外键)+ comment(业务注释)
+   → 大多数情况能直接看出关联
+
+2. Read docs/schema-knowledge/<profile>.md
+   → 团队沉淀的表关系 + 字段含义 + 已知陷阱
+   → 含待执行的 COMMENT SQL(用户执行后从这里删除)
+
+3. 都没有 → 问用户(不要试错)
+   → "这两个表你想通过哪个字段关联?"
+   → "你期望这条 SQL 返回什么样的业务实体?"
+   → 用户也不知道时,**每一步试错都报告用户**,让用户决定继续还是换思路
+
+4. 探索完成(用户告知或谨慎试错得到结论)后:
+   a. append 关系/含义到 docs/schema-knowledge/<profile>.md
+   b. 生成 COMMENT SQL(按 profile 的 db type 选语法)append 到 schema-knowledge 的"待执行 COMMENT SQL"段
+   c. 提示用户:执行后从文件删除(DB 注释已固化,不需要文件重复)
+```
+
+**长期目标**:DB 注释逐渐健全(用户/DBA 执行了 COMMENT SQL)后,`schema --mode ddl` 直接返回业务含义,**schema-knowledge 退役**。DB 自带注释是单一事实源,任何工具/任何人查 DDL 都受益。
+
+## 何时派子 agent(让上下文更干净)
+
+主 agent **直接调 cgraphx db 工具时,大段原文(DDL 字段列表、SELECT 输出、表关系推断过程)会进自己的上下文**,挤占决策与待办的空间。本 skill 工具适合精确查询,但**模糊意图的重探索型任务**适合派子 agent 在隔离上下文里跑。
+
+### 判断规则(R4:目标精度)
+
+主 agent **已知精确目标**(具体表名 / 字段名 / SQL)→ **不派**,直接调上面工具;主 agent **只有模糊意图**(系统理解 / 梳理 / 调研型)→ **派**。
+
+具体例子:
+
+| 场景 | 不派(直接调工具) | 派(派子 agent) |
+|---|---|---|
+| 看表结构 | "work_order 表结构" → `cgraphx db schema --mode ddl --table work_order` | "梳理这个库的所有表关系" |
+| 看索引 | "users 表的索引" → `cgraphx db schema --mode indexes --table users` | "系统理解 X 业务的数据模型" |
+| 查数据 | "查 work_order 里 status=1 的前 5 条" → `cgraphx db query --sql "SELECT ... LIMIT 5"` | "调研 work_order / payment / users 这套流程涉及的表关系" |
+
+### 派的方法(决定派时执行)
+
+1. **Read** 本 skill 目录下的 `./agent-prompt.md`
+2. **Agent tool 调用**:
+   ```
+   Agent({
+     subagent_type: "general-purpose",
+     prompt: <agent-prompt.md 文件内容> + "\n\n当前任务: " + <用户原话或你的转述>
+   })
+   ```
+3. **直接采纳**子 agent 返回的提炼结论 —— 不要再自己调 `cgraphx db schema/query` 重新查(那是浪费)
+4. 结论不够 → 再派一次(换 prompt 重点,如"重点看 X 表的关联")或回头自己调工具补
+5. 子 agent 在返回里明确说"这些表关系不明,建议问用户"→ 主 agent 决定是否问,**不要让子 agent 自己问用户**(主 agent 才是用户对话入口)
+
+### 代价
+
+- **不派的代价**:大段 DDL / SELECT 输出进主上下文,后续决策可用 budget 变小
+- **派的代价**:子 agent 本身耗 token,简单查询派反而更贵
+- **R4 是平衡点**:只在"模糊意图 + 主 agent 无法精确判断目标"时派
+
+## schema-knowledge 文件结构
+
+每个 profile 一个 markdown 文件:`docs/schema-knowledge/<profile>.md`(项目业务数据目录,跨工具版本保留,不会被 cgraphx 升级覆盖)
+
+```markdown
+# <profile> schema knowledge
+
+## 表关系(DB 未定义 FK 的隐式关联)
+- `work_order.assignee_id` → `users.staff_code`(处理人)
+- `payment.order_id` → `work_order.id`(订单的支付记录)
+
+## 关键字段业务含义(DB 注释未覆盖的)
+- `work_order.status`: 0=待派单 1=处理中 2=已完成 3=已取消
+- `users.tenant_id`: 租户隔离字段,所有查询必须带这个过滤
+
+## 待执行的 COMMENT SQL(用户执行后从此处删除)
+ALTER TABLE work_order MODIFY COLUMN assignee_id VARCHAR(64) COMMENT '处理人工号,关联 users.staff_code';
+COMMENT ON COLUMN work_order.status IS '0=待派单 1=处理中 2=已完成 3=已取消';  -- PG
+ALTER TABLE work_order MODIFY COLUMN status TINYINT NOT NULL COMMENT '0=待派单 1=处理中 2=已完成 3=已取消';  -- MySQL
+
+## 已知陷阱
+- `users.email` 不是唯一(同 email 多账号)—— 用 `users.phone` 关联更稳
+- 跨 schema 查询时 schema 前缀必须显式(如 `tenant.users`)
+```
+
+**用户工作流**:
+- 看 schema-knowledge 找现成知识 → 直接用
+- 找不到 → AI 探索(按上面优先级链)→ 写入
+- 看"待执行的 COMMENT SQL" → 复制执行到 DB → 删除已执行的部分(因为 DB 已固化)
+
+## 期望错误(CLI 退出码语义)
+
+| 退出码 | 含义 | 处理 |
+|---|---|---|
+| 0 | 成功 | — |
+| 2 | 配置错误(profiles 文件缺失/无效) | 创建 `.cgraphx/db-profiles.json` |
+| 3 | 安全拦截(SQL 含写操作) | 只读 SELECT,改 SQL |
+| 4 | 连接失败/查询超时/子系统禁用 | 检查 profile 连接参数,或 `CGRAPHX_DB_QUERY_DISABLED` 是否设置 |
+| 5 | 参数错误(缺 --sql / 缺 --table) | 补全必填参数 |
+
+stderr 文本能直接读,无需额外解析。
+
+## 探索结果收口(给 clarify/spec/plan)
+
+只有当本 skill 用于需求澄清、spec 或 plan 前置探索时,才做简短收口。简单精确查询(如"看某表 DDL")可以直接回答,不套模板。
+
+按需使用以下 4 项,无内容可省略:
+
+- **查到的关键事实**:表、字段、注释、索引、外键/隐式关联、样本分布、状态枚举或异常数据。
+- **对决策的影响**:哪些统计口径、过滤条件、兼容策略、迁移/回填策略需要确认或锁定。
+- **应进入 PRD/spec/plan 的内容**:数据口径、状态含义、权限隔离字段、迁移任务、验证 SQL、索引风险等。
+- **仍不确定/需确认**:需要业务方、DBA、代码探索或 schema 注释补充的点。

package/dist/.claude-template/skills/db-query/agent-prompt.md

@@ -0,0 +1,55 @@
+# db-query 探索子 agent prompt(数据库 schema 探索)
+
+> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接 `\n\n当前任务: <用户原话>`。
+
+## 你的角色
+
+你是数据库 schema 探索子 agent。你在**隔离上下文**里跑,主 agent **看不到你的中间过程**(工具调用、DDL 原文、SELECT 输出),**只拿到你的最终返回**。
+
+主 agent 派你来是因为它收到一个**模糊意图的重探索型任务**(如"梳理这个库的所有表关系 / 系统理解 X 业务的数据模型 / 调研 X 流程涉及的表"),需要逐表查 schema 才能给结论。你的产出会被主 agent **直接采纳**,不需要它再回头查。
+
+## 可用工具
+
+| 工具 | 用途 |
+|---|---|
+| `cgraphx db profiles` | 列已配置 profiles,确认连哪个库 |
+| `cgraphx db schema --mode tables [--profile <name>]` | 列所有表 |
+| `cgraphx db schema --mode ddl --table <name> [--profile <name>]` | 看字段、注释、外键(判断表关系的首选信息源) |
+| `cgraphx db schema --mode indexes --table <name>` | 看索引 |
+| `cgraphx db schema --mode table-comment --table <name>` | 看表注释 |
+| `cgraphx db query --sql "SELECT ... LIMIT N" [--profile <name>]` | 查样本数据(自动 LIMIT) |
+| `Read` | 读 `docs/schema-knowledge/<profile>.md` 找团队沉淀 |
+
+## 探索策略(对齐主 SKILL.md 的"陌生 schema 探索流程")
+
+1. **`cgraphx db profiles`** 确认 profile(避免连错库)
+2. 对涉及的表逐个 **`cgraphx db schema --mode ddl --table <name>`** 看字段、`comment`、`fk_table/fk_column`
+3. 看外键 + comment **推断表关系** —— 大多数情况直接能看出
+4. 不够 → `Read docs/schema-knowledge/<profile>.md` 找团队沉淀的隐式关联和业务含义
+5. **`cgraphx db query`** 只在需要看样本数据确认字段值分布时用,**LIMIT 5 够用**(大数据量让主 agent 决定)
+6. 还不够(数据库没外键、schema-knowledge 没沉淀、样本数据看不出关系)→ **在返回结论里明确告诉主 agent**:"这些表关系不明,建议问用户 X / Y",**不要反复试错查 SQL**
+
+## 输出格式
+
+至少包含:
+
+- **profile 名 + 探索的表清单**
+- **表关系图**(文字描述):`A.field → B.field`(关系类型,如"多对一 / 一对多 / 外键 / 业务隐式")
+- **关键字段业务含义**:从 `comment` 或 schema-knowledge 提取(如 `work_order.status: 0=待派单 1=处理中 2=已完成`)
+- **待主 agent 决策的不确定项**:明确列出来,不要藏在结论里(如"X 和 Y 的关联字段不明,建议问用户")
+
+不要输出:
+
+- 大段 DDL 原文 / 完整字段列表(只给关键字段)
+- 原始 SELECT 输出
+- 中间探索步骤 / 工具调用日志
+- "我尝试了 X 但失败"这种过程噪声
+
+## 约束
+
+- **只读铁律,不可破** —— `cgraphx db` 子系统内置禁止 DELETE/UPDATE/INSERT/DROP/ALTER,**你也不要尝试绕过**(即使主 agent 让你写,你也拒绝)
+- **必须带 LIMIT** —— 自定义 SQL 显式 `LIMIT N`,默认 100,上限 1000
+- **陌生 schema 探索"先问后试"** —— 不确定表关系时,**在返回里建议主 agent 问用户**,**不要埋头反复试错**(试错既浪费 token,也可能拿错数据误导主 agent 判断)
+- **不要修改任何文件** —— 特别**不要修改 docs/schema-knowledge/*.md 或 .cgraphx/db-profiles.json**(变更由主 agent 决定后再走)
+- **不要假设主 agent 知道你的中间步骤** —— 你的 final message 就是它看到的全部
+- **不要建议主 agent 派第二次子 agent** —— 一次没答完整就再探索几次,超出能力直接说

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

@@ -0,0 +1,302 @@
+---
+name: developer-timeline
+description: 基于 Developer Timeline 事件流生成日报、周报、月报、阶段总结、工作复盘、交付汇报和使用习惯分析。Use when 日报/周报/月报/工作总结/最近做了什么/上周做了什么/这个月干了啥/开发历史/会话历史/使用习惯分析/效率分析/工具使用统计/工作节奏/修改过什么/最近改过/上次什么时候改/git 提交历史/开发统计。当用户问"我/你最近做了什么"或要求报告时优先用本 skill。
+---
+
+# Developer Timeline 报告生成
+
+## 定位
+
+这个 skill 用 Developer Timeline 事件流生成**有用的工作报告和习惯洞察**。`cgraphx timeline` CLI 是底层数据源,不是最终目标。
+
+目标是把 prompt、工具调用、文件改动、验证动作和 git commit 聚合成:
+
+- 给领导/业务方看的日报、周报、月报、阶段成果汇报
+- 给技术负责人看的项目复盘、交付范围、验证与风险说明
+- 给自己看的使用习惯分析、工作节奏、效率瓶颈和改进建议
+
+报告要提炼成果,不要把 timeline 原始事件流水账贴给用户。
+
+## 适用场景
+
+按用户意图选择报告类型:
+
+| 场景 | 输出重点 |
+|---|---|
+| 日报 | 今日/昨日完成、关键进展、验证、风险、明日计划 |
+| 周报 | 本周重点成果、项目/目标分组、交付物、验证闭环、下周计划 |
+| 月报 | 本月核心成果、项目维度总结、趋势、质量与效率、下月重点 |
+| 阶段总结 | 某个 feature / 时间窗口 / 会话范围内的目标、过程、产出、遗留 |
+| 使用习惯分析 | 活跃时段、工具分布、读写比、验证习惯、上下文切换、改进建议 |
+| 交付汇报 | 面向领导/团队的价值、结果、风险和下一步 |
+| 历史查询 | 某文件/commit/会话最近发生了什么,可直接回答或轻量总结 |
+
+如果用户没有指定报告类型,根据措辞判断:
+
+- "今天/昨天" → 日报
+- "本周/上周/最近 7 天" → 周报
+- "本月/上月/最近 30 天" → 月报
+- "使用习惯/效率/分析一下我怎么用" → 使用习惯分析
+- "最近做了什么" → 默认最近 7 天工作总结,除非上下文明显指向今天或本月
+
+## 输出模式
+
+支持三种输出:
+
+| 模式 | 适用 |
+|---|---|
+| `chat-summary` | 聊天内快速总结,默认最轻量 |
+| `markdown-report` | 可复制到周报/月报/文档 |
+| `single-page-html` | 正式汇报、归档、浏览器查看、打印或截图 |
+
+生成单文件 HTML:
+
+- 内联 CSS,无外部资源,无脚本依赖。
+- 默认路径:`docs/reports/timeline/`
+- 建议命名:
+  - 日报:`YYYY-MM-DD-daily.html`
+  - 周报:`YYYY-Www-weekly.html`
+  - 月报:`YYYY-MM-monthly.html`
+  - 习惯分析:`YYYY-MM-DD-habits.html`
+- 如果项目没有 `docs/reports/timeline/`,可以创建。
+- 页面布局和风格参考本 skill 目录下 `demo-single-page-report.html`, 内容可以适当调整
+
+## 报告生成流程
+
+### 1. 确认必须明确的维度
+
+报告生成前必须把以下维度敲定。核心原则:**用户已经明确给出的不重复问,未给出的必须主动问,不可推断**。
+
+| 维度 | 已明确 → 直接用,不问 | 未明确 → 必须问 |
+|---|---|---|
+| 时间范围 | "昨天/今天/上周/本月/最近 N 天"等措辞清楚 | 必须问,不推断 |
+| 输出格式 | 用户指定 chat 摘要 / Markdown / HTML | 必须问,不推断 |
+| 受众 | 用户指明给领导/自己/团队/业务方 | 必须问,不推断 |
+| 报告类型 | "日报/周报/月报/阶段总结/习惯分析"措辞清楚 | 从措辞推断,不强制问 |
+
+举例:
+
+- "总结昨天的日报" → 时间已明确、报告类型已明确,只问输出格式和受众
+- "总结最近工作" → 时间、格式、受众都未明确,一次问完
+- "做一份本月 HTML 月报发给领导" → 全部明确,直接做,不问
+
+询问规则:
+
+- 用 `AskUserQuestion` 一次性把所有缺失维度问完,不逐条追问。
+- 询问优先级:输出格式 > 时间范围 > 受众。
+- 报告类型不强制问,从措辞合理推断。
+- 用户已经明确说出的维度,**绝不重复问**(说"昨天"就不要再问"什么时候")。
+
+### 2. 采集 timeline 数据
+
+优先用 table 格式,减少 token:
+
+```bash
+cgraphx timeline query --since=<date-or-range> --until=<date-or-now> --format=table
+```
+
+按需补充统计:
+
+```bash
+cgraphx timeline stats --since=<date-or-range> --until=<date-or-now>
+```
+
+按需钻取单条详情:
+
+```bash
+cgraphx timeline show <id>
+```
+
+常用时间范围:
+
+- 日报:今天 00:00 到现在;昨日用昨日 00:00 到今日 00:00
+- 周报:本周一 00:00 到现在;上周用上周一到本周一
+- 月报:本月 1 日 00:00 到现在;上月用上月 1 日到本月 1 日
+- 最近 N 天:用 `--since=Nd`
+
+### 3. 聚合事件,不要流水账
+
+把事件归并成"目标 / 成果 / 证据 / 验证 / 风险":
+
+- 按用户 prompt 和会话边界识别工作目标。
+- 按文件路径、模块、feature-id、commit message 聚类。
+- 把 Read/Edit/Bash 等工具调用转译成工程动作,不要当作成果本身。
+- commit 是交付证据之一,不是唯一成果。
+- 探索、调试、验证、未提交改动也要识别,但要说明状态。
+- 将未验证、未提交、被中断、失败命令、反复修改集中列为风险或遗留。
+
+### 4. 选择叙述方式
+
+按受众调整语言:
+
+- 给领导/业务方:强调业务价值、交付结果、风险闭环、下一步计划;少讲工具细节。
+- 给技术负责人:强调模块、文件范围、接口/测试/验证、质量风险。
+- 给团队:强调协作影响、变更范围、阻塞项、需要 review 的地方。
+- 给自己:强调工作节奏、工具使用、上下文切换、验证习惯和改进建议。
+
+### 5. 生成报告
+
+默认先给高层结论,再给证据。不要先贴原始表格。
+
+如果生成 HTML:
+
+1. 先组织报告内容。
+2. 使用 `demo-single-page-report.html` 的布局风格作为参考。
+3. 根据报告类型裁剪章节。
+4. 写入目标 HTML 文件。
+5. 检查是否单文件、无外链、无脚本、可打印。
+
+## 报告模板
+
+模板是结构参考,不是死板填表。无内容的章节可以省略。
+
+### 日报
+
+```markdown
+## 今日完成
+## 关键进展
+## 验证与交付
+## 风险/阻塞
+## 明日计划
+```
+
+### 周报
+
+```markdown
+## 本周摘要
+## 重点成果
+## 项目/模块进展
+## 验证与交付证据
+## 风险与遗留
+## 下周计划
+```
+
+### 月报
+
+```markdown
+## 本月核心成果
+## 项目/模块维度总结
+## 质量与效率指标
+## 关键风险处理
+## 经验沉淀
+## 下月重点
+```
+
+### 使用习惯分析
+
+```markdown
+## 工作节奏
+## 工具使用分布
+## 读写与验证习惯
+## 上下文切换与中断
+## 交付闭环
+## 改进建议
+```
+
+### 单页面 HTML
+
+推荐章节:
+
+- 标题区:报告名称、时间范围、项目、生成时间
+- 一页摘要:3-5 个核心结论或关键数字
+- 重点成果:按目标/项目聚合,不按工具流水账
+- 证据与交付物:commit、文件、验证命令、产物
+- 使用习惯分析:工具分布、读写比、验证习惯、工作节奏
+- 风险与遗留:未验证、未提交、阻塞、敏感项
+- 下一步计划:建议转化成可执行事项
+
+页面风格:
+
+- 工作报告风,信息密度高,适合领导和技术负责人快速扫描。
+- 不做营销页、不做装饰性 hero、不放无意义图形。
+- 使用表格、指标块、短列表、标签和时间线组织信息。
+- 内容优先,视觉只服务可读性。
+
+## 使用习惯分析指标
+
+按数据可得性取用,不要为了凑指标编造:
+
+- 活跃时间段:上午/下午/晚上、连续工作时长、长会话/短会话比例
+- 工具使用:Read/Edit/Bash/搜索/测试/提交分布
+- 读写比:读取上下文与实际编辑的比例
+- 验证习惯:测试、lint、build、diff check、手工验证频率
+- 上下文切换:涉及项目/模块/文件数量,是否频繁中断
+- 交付闭环:commit 数、未提交改动、失败命令、未验证改动
+- 工作类型:探索、实现、修复、文档、评审、调试、汇报
+- 风险模式:改多测少、探索多沉淀少、频繁返工、长时间无验证
+
+## 内容质量规则
+
+- 不要逐条复述 raw timeline 事件。
+- 不要把 "Read/Edit/Bash" 当作工作成果;要翻译成目标和结果。
+- 不夸大:没有 commit 不等于没成果,但没有验证也不能说已交付。
+- 明确区分完成、进行中、探索、未验证、未提交、阻塞。
+- 对失败命令、回滚、重复尝试要总结原因和影响,不要隐藏。
+- 敏感信息默认摘要化;不要直接暴露完整 prompt、命令参数、token、密钥、客户数据或长日志。
+- 用户要求给领导时,语言要结果导向;用户要求自我分析时,可以更直接指出习惯问题。
+- 如果 timeline 数据不足,说明覆盖范围和不确定性,不要编造缺失事件。
+
+## CLI 数据源参考
+
+Developer Timeline 记录项目本地事件流:
+
+- `user_prompt`:用户提出的任务
+- `pre_tool_use` / `post_tool_use`:工具调用、文件、命令
+- `stop`:会话结束
+- `git_commit`:提交记录
+
+数据存在项目本地 `.cgraphx/cgraphx.db`,per-project 隔离。
+
+### 命令
+
+```bash
+cgraphx timeline recent --limit=20 --format=table
+cgraphx timeline query --since=7d --format=table
+cgraphx timeline query --since=2026-06-01 --until=2026-07-01 --format=table
+cgraphx timeline query --file=src/auth/login.ts --since=30d --format=table
+cgraphx timeline query --type=git_commit --since=7d --format=table
+cgraphx timeline stats --since=7d
+cgraphx timeline show <id>
+```
+
+### 时间格式
+
+`--since` / `--until` 接受:
+
+- ISO 8601:`2026-06-01` / `2026-06-01T00:00:00Z`
+- 相对:`7d` / `12h` / `30m` / `now`
+
+### 输出选择
+
+- `table`:推荐给 agent 读,密度高。
+- `json`:需要完整字段或程序处理时使用。
+- `show <id>`:单条钻取。
+
+## 跟其他工具的边界
+
+| 想知道 | 用 |
+|---|---|
+| 代码结构、调用关系 | `cgraphx` skill |
+| 业务决策、概念定义 | `code-impact-api` skill |
+| 数据库数据 | `db-query` skill |
+| 开发活动历史、报告、习惯分析 | 本 skill |
+| 只要 commit 列表 | `git log` 更轻量 |
+
+## 前置条件和失败处理
+
+- 项目必须 `cgraphx init`。
+- Timeline hooks 必须安装(`cgraphx timeline install` 或 `cgraphx install`)。
+- Kill-switch:`CGRAPHX_NO_TIMELINE=1` 时 hooks 静默不记录。
+- 如果 timeline 无数据,说明原因并建议检查 hooks;可以退化到 `git log` + 当前工作区状态,但必须标明覆盖不足。
+- Timeline 全量记录 prompt、命令和文件路径,不脱敏;报告时默认摘要化敏感内容。
+
+## 探索结果收口(给 clarify/spec/plan)
+
+只有当本 skill 用于恢复上下文、承接未完成工作或进入 clarify/spec/plan 前置探索时,才做简短收口。普通日报、周报、月报、历史查询和习惯分析直接按用户要求生成报告,不套这个模板。
+
+按需使用以下 4 项,无内容可省略:
+
+- **查到的关键事实**:最近目标、读过/改过的文件、跑过的命令、commit 或未提交改动。
+- **对决策的影响**:哪些上下文可复用,哪些必须重新问用户确认。
+- **应进入 PRD/spec/plan 的内容**:已完成任务、剩余任务、验证缺口、需要保护的用户改动。
+- **仍不确定/需确认**:只是探索未确认、尚未验证、未提交或需要用户重新拍板的点。