cgraphx 1.4.1 → 2.0.0

package/dist/.claude-template/skills/cgraphx-guide/how-to-use.html

@@ -15,7 +15,6 @@
   --color-bg: #FFFFFF;
   --color-bg-subtle: #F7FAFC;
   --color-bg-code: #EDF2F7;
-  --color-bg-accent: #FFFAF0;
   --color-cgraphx: #2B6CB0;
   --radius: 6px;
 }
@@ -110,7 +109,7 @@ code {
 }
 .tag-cgraphx { background: #EBF8FF; color: #2C5282; }
 
-/* Pipeline (单卡片,沿用左侧 code-workflow 卡片样式) */
+/* Pipeline (numbered steps) */
 .pipeline {
   border: 1px solid var(--color-border);
   border-top: 4px solid var(--color-cgraphx);
@@ -118,43 +117,40 @@ code {
   padding: 24px 28px;
   background: var(--color-bg);
   margin: 0 0 24px;
+  counter-reset: step;
 }
-.pipeline h4 {
-  margin: 0 0 20px;
-  font-size: 16px;
-  font-weight: 600;
-}
-.phase {
-  margin-bottom: 18px;
-  padding-bottom: 18px;
+.step {
+  position: relative;
+  padding-left: 40px;
+  margin-bottom: 20px;
+  padding-bottom: 20px;
   border-bottom: 1px dashed var(--color-border);
+  counter-increment: step;
 }
-.phase:last-child {
-  margin-bottom: 0;
-  padding-bottom: 0;
-  border-bottom: none;
+.step:last-child { margin-bottom: 0; padding-bottom: 0; border-bottom: none; }
+.step::before {
+  content: counter(step);
+  position: absolute;
+  left: 0;
+  top: 2px;
+  width: 26px;
+  height: 26px;
+  border-radius: 50%;
+  background: var(--color-cgraphx);
+  color: #fff;
+  font-size: 13px;
+  font-weight: 700;
+  display: flex;
+  align-items: center;
+  justify-content: center;
 }
-.phase-label {
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
-  color: var(--color-text-tertiary);
+.step h4 {
+  margin: 0 0 6px;
+  font-size: 15.5px;
   font-weight: 600;
-  margin-bottom: 10px;
-}
-.phase-list {
-  padding-left: 20px;
-  margin: 0;
-  font-size: 14px;
-  line-height: 1.75;
-}
-.phase-list li { margin-bottom: 6px; }
-.phase-list code { font-size: 12.5px; }
-.phase-list em {
-  color: var(--color-text-tertiary);
-  font-size: 13px;
-  font-style: normal;
 }
+.step h4 code { font-size: 13px; }
+.step p { margin: 0; font-size: 14.5px; color: var(--color-text-secondary); }
 
 /* Highlight box */
 .highlight {
@@ -163,16 +159,69 @@ code {
   border-left: 4px solid var(--color-cgraphx);
   border-radius: var(--radius);
   padding: 20px 24px;
-  margin: 0 0 16px;
+  margin: 16px 0 16px;
 }
 .highlight p:last-child { margin-bottom: 0; }
 
+/* Tabs */
+.tabs-bar {
+  display: flex;
+  gap: 0;
+  border-bottom: 2px solid var(--color-border);
+  margin-bottom: 20px;
+  flex-wrap: wrap;
+}
+.tab-btn {
+  padding: 10px 18px;
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--color-text-tertiary);
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -2px;
+  cursor: pointer;
+  transition: color 0.15s, border-color 0.15s;
+  font-family: inherit;
+}
+.tab-btn:hover { color: var(--color-primary); }
+.tab-btn.active {
+  color: var(--color-primary);
+  border-bottom-color: var(--color-primary);
+  font-weight: 600;
+}
+.tab-panel { display: none; }
+.tab-panel.active { display: block; }
+.tab-panel .phase-list code { font-size: 12.5px; }
+.tab-panel .phase-list em {
+  color: var(--color-text-tertiary);
+  font-size: 13px;
+  font-style: normal;
+}
+
+/* Workflow overview diagram */
+.flow-diagram {
+  background: var(--color-bg-code);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: 18px 22px;
+  font-family: "SF Mono", "Menlo", monospace;
+  font-size: 12.5px;
+  line-height: 1.7;
+  overflow-x: auto;
+  margin: 12px 0 0;
+  white-space: pre;
+  color: var(--color-text-secondary);
+}
+
 /* Lists */
 ul, ol {
   padding-left: 24px;
   margin: 0 0 16px;
 }
 li { margin-bottom: 6px; }
+.phase-list { padding-left: 20px; font-size: 14.5px; line-height: 1.75; }
+.phase-list li { margin-bottom: 8px; }
 
 /* Footer */
 footer {
@@ -200,25 +249,12 @@ footer p { margin: 0; }
   margin: 0 0 16px;
   white-space: pre;
 }
-.docs-tree b {
-  font-weight: 600;
-  color: var(--color-primary-dark);
-}
-.docs-tree .skill {
-  color: var(--color-primary);
-  font-weight: 600;
-}
-.docs-tree .ann {
-  color: var(--color-text-tertiary);
-}
-.docs-tree .must {
-  color: #2e7d32;
-  font-weight: 600;
-}
-.docs-tree .opt {
-  color: #e65100;
-  font-weight: 600;
-}
+.docs-tree b { font-weight: 600; color: var(--color-primary-dark); }
+.docs-tree .skill { color: var(--color-primary); font-weight: 600; }
+.docs-tree .ann { color: var(--color-text-tertiary); }
+.docs-tree .must { color: #2e7d32; font-weight: 600; }
+.docs-tree .opt { color: #e65100; font-weight: 600; }
+.docs-tree .post { color: #6a1b9a; font-weight: 600; }
 .docs-legend {
   display: flex;
   gap: 20px;
@@ -227,11 +263,7 @@ footer p { margin: 0; }
   color: var(--color-text-secondary);
   margin: 0 0 20px;
 }
-.docs-legend span {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-}
+.docs-legend span { display: inline-flex; align-items: center; gap: 6px; }
 .docs-legend .dot {
   display: inline-block;
   width: 8px;
@@ -240,7 +272,80 @@ footer p { margin: 0; }
 }
 .docs-legend .dot.must { background: #2e7d32; }
 .docs-legend .dot.opt { background: #e65100; }
-.docs-legend .dot.local { background: var(--color-cgraphx); }
+.docs-legend .dot.post { background: #6a1b9a; }
+
+/* Terminal-style install flow */
+.terminal {
+  background: #282c34;
+  border-radius: 8px;
+  overflow: hidden;
+  box-shadow: 0 10px 30px rgba(0,0,0,0.12), 0 2px 6px rgba(0,0,0,0.06);
+  margin: 0 0 24px;
+  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+}
+.terminal-titlebar {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 11px 14px;
+  background: #21252b;
+  border-bottom: 1px solid #181a1f;
+}
+.terminal-titlebar .dot {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  display: inline-block;
+}
+.terminal-titlebar .dot.red { background: #ff5f56; }
+.terminal-titlebar .dot.yellow { background: #ffbd2e; }
+.terminal-titlebar .dot.green { background: #27c93f; }
+.terminal-titlebar .terminal-title {
+  color: #9da5b4;
+  font-size: 12.5px;
+  margin-left: 8px;
+}
+.terminal-body {
+  padding: 20px 22px;
+  font-size: 13.5px;
+  line-height: 1.7;
+  color: #abb2bf;
+  overflow-x: auto;
+}
+.t-line { white-space: pre-wrap; }
+.t-prompt { color: #98c379; font-weight: 600; }
+.t-path { color: #61afef; }
+.t-cmd { color: #e5c07b; }
+.t-flag { color: #c678dd; }
+.t-comment { color: #5c6370; }
+.t-sep {
+  color: #4b5263;
+  margin: 16px 0 2px;
+  font-size: 12.5px;
+  letter-spacing: 0.03em;
+}
+.t-note {
+  color: #56b6c2;
+  font-size: 12.5px;
+  padding-left: 18px;
+  margin: 2px 0 0;
+}
+.t-cursor {
+  display: inline-block;
+  width: 8px;
+  height: 15px;
+  background: #abb2bf;
+  vertical-align: text-bottom;
+  margin-left: 3px;
+  animation: t-blink 1.1s steps(2, start) infinite;
+}
+@keyframes t-blink { 50% { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) {
+  .t-cursor { animation: none; }
+}
+@media (max-width: 768px) {
+  .terminal-body { padding: 16px; font-size: 12.5px; }
+}
 
 /* Responsive */
 @media (max-width: 768px) {
@@ -261,162 +366,242 @@ footer p { margin: 0; }
 <header>
   <div class="eyebrow">cgraphx 安装与使用</div>
   <h1>cgraphx 怎么用</h1>
-  <p class="subtitle">本地优先的代码智能 · 给 AI agent 用的代码图谱</p>
-  <p class="meta">最后更新:2026-07-13</p>
+  <p class="subtitle">本地优先的 AI agent 研发系统 · skill 流程 + 知识库 / 数据库 / 时间线</p>
+  <p class="meta">最后更新:2026-07-30</p>
 </header>
 
 <section>
-  <h2>安装流程</h2>
+  <h2>安装</h2>
+
+  <div class="terminal">
+    <div class="terminal-titlebar">
+      <span class="dot red"></span>
+      <span class="dot yellow"></span>
+      <span class="dot green"></span>
+      <span class="terminal-title">bash — 安装 cgraphx</span>
+    </div>
+    <div class="terminal-body">
+      <div class="t-line"><span class="t-prompt">$</span> npm install <span class="t-flag">-g</span> cgraphx <span class="t-comment"># Node.js ≥22.5 &lt;27(内置 node:sqlite,无原生依赖)</span></div>
 
-  <div class="pipeline">
-    <h4><span class="tag tag-cgraphx">cgraphx</span> &nbsp;一次接入 · 三层就绪</h4>
+      <div class="t-sep"># ── 项目级 · 每项目一次 ──────────────────────</div>
+      <div class="t-line"><span class="t-path">~/my-project</span> <span class="t-prompt">$</span> cgraphx install</div>
+      <div class="t-note"># 建 .cgraphx/ + 部署 skills 到 .claude/ + 接入 hooks/statusLine + 写工作方式</div>
+      <div class="t-note"># 重启 Claude Code 即可</div>
 
-    <div class="phase">
-      <div class="phase-label">机器级 · 每机器一次</div>
-      <ul class="phase-list">
-        <li><code>npm install -g cgraphx</code> 装 CLI<em>（Node ≥ 20 且 &lt; 25）</em></li>
-      </ul>
-    </div>
+      <div class="t-sep"># ── 升级 ────────────────────────────────────</div>
+      <div class="t-line"><span class="t-prompt">$</span> cgraphx upgrade <span class="t-comment"># npm 自更新(纯换包,不动项目)</span></div>
+      <div class="t-line"><span class="t-path">~/my-project</span> <span class="t-prompt">$</span> cgraphx install <span class="t-comment"># 各项目重跑,刷新 skill(自动清理旧 skill)</span></div>
 
-    <div class="phase">
-      <div class="phase-label">项目级 · 每项目一次</div>
-      <ul class="phase-list">
-        <li><code>cd /your/project &amp;&amp; cgraphx init</code> 建 <code>.cgraphx/</code> 代码图谱索引、开 watcher 自动增量同步</li>
-        <li><code>cgraphx install</code> 写 MCP 配置 + 部署 skills 模板到项目 <code>.claude/</code><em>（默认 local;想影响所有项目才用 <code>--location=global</code>）</em></li>
-        <li><code>/code-impact-init</code> 接手陌生项目时按需跑<em>（派子 agent 自动探索、建 <code>docs/knowledge/</code> 业务知识库）</em></li>
-      </ul>
+      <div class="t-sep"># ── 卸载 · 可选 ──────────────────────────────</div>
+      <div class="t-line"><span class="t-path">~/my-project</span> <span class="t-prompt">$</span> cgraphx uninstall <span class="t-comment"># 清 .claude/ skills/配置 + 删 .cgraphx/</span></div>
+      <div class="t-line"><span class="t-prompt">$</span> npm uninstall <span class="t-flag">-g</span> cgraphx<span class="t-cursor"></span></div>
     </div>
+  </div>
+</section>
+
+<section>
+  <h2>最佳起步实践</h2>
+  <p>接入只是第一步。推荐这个顺序——<strong>先立规范、再聊业务、然后做需求</strong>:</p>
 
-    <div class="phase">
-      <div class="phase-label">卸载 · 可选</div>
-      <ul class="phase-list">
-        <li><code>npm uninstall -g cgraphx</code><em>（preuninstall 钩子自动清所有 agent 的 MCP 配置）</em></li>
-        <li>删项目目录下 <code>.cgraphx/</code> 清索引数据</li>
-      </ul>
+  <div class="pipeline">
+    <div class="step">
+      <h4>立规范 · <code>/init-project-guides</code></h4>
+      <p>生成 <code>docs/guides/</code> 五份规范(编码/接口/数据/测试/Git)。规范 = 项目对默认做法的<strong>有意偏离</strong>——「SQL 禁止 ORDER BY」「金额一律 decimal(12,2)」这类最容易偏离又没有工具兜底的约定。这些 guide 是后续任务的<strong>强制读点</strong>:编码/接口/数据三份会被 <code>/write-plan</code> 结晶成契约(测试规范不走 plan,由测试流程 <code>write-unit-test-code</code>/<code>run-api-test</code> 自读;Git 结晶进 plan 提交规范节)。</p>
+    </div>
+    <div class="step">
+      <h4>聊业务 · 和 Claude Code 聊项目</h4>
+      <p>做需求前先聊业务。agent 会自动从知识库召回已沉淀的概念、对齐术语;边聊边用 <code>/knowledge-write</code> 把业务实体沉淀下来。接手陌生项目可以跑 <code>/knowledge-init</code> 批量探索建档。知识库越用越厚,重复解释和重复踩坑越少。</p>
+    </div>
+    <div class="step">
+      <h4>做需求 · <code>/clarify-requirements</code> 起步</h4>
+      <p>进入主工作流:澄清 → 规格(<code>/write-spec</code>)→ 实现 → 测试。有了前两步,澄清才有共同语境,而不是从零问起。</p>
     </div>
   </div>
 
   <div class="highlight">
-    <p><strong>装一次,自动维护</strong>——全局装 CLI,每个项目跑 <code>init</code> + <code>install</code> 就接入完成;之后 watcher 自动同步代码图谱、MCP 配置自动注入,你不需要主动跑命令。卸载也是一条命令。</p>
+    <p>先有规范(agent 懂「规矩」),再对齐业务(agent 懂「黑话」),然后做需求才事半功倍。</p>
   </div>
 </section>
 
 <section>
-  <h2>使用流程</h2>
+  <h2>工作流全景</h2>
+
+  <div class="flow-diagram">knowledge-recall(自动召回)
+        │
+        ▼
+/clarify-requirements ──→ /write-spec ──→ /write-plan(可选)
+     澄清                  唯一契约          执行计划
+        │                                        │
+        │            ┌───────────────────────────┘
+        ▼            ▼
+  /implementation(简单) 或 /subagent-implement(复杂)
+        │
+   ┌────┴─────────────────────────────┐
+   ▼              ▼                   ▼
+/write-api    /write-unit-test-spec  交付收尾:
+→ /run-api-test → /write-unit-test-code  /knowledge-write 沉淀
+  接口测试       单元测试              commit 门禁
+
+── 发布后 · 按需(不在主链,不参与门禁)──────────────────
+/write-prd(业务方审阅)  /write-design-doc(设计文档)  /write-api-doc(接口文档)</div>
 
-  <div class="pipeline">
-    <h4><span class="tag tag-cgraphx">cgraphx</span> &nbsp;极简内核 · 按需扩展</h4>
-
-    <div class="phase">
-      <div class="phase-label">日常做需求 · 必经 2 步</div>
-      <ul class="phase-list">
-        <li><code>/clarify-requirements</code> 澄清意图、业务边界、技术边界</li>
-        <li><code>/implementation</code> 实现<em>（简单任务,主会话顺序做）</em>或 <code>/subagent-implement</code><em>（复杂多任务,派子 agent）</em></li>
-      </ul>
-    </div>
+  <div class="highlight">
+    <p>日常默认两步:<strong>澄清 + 实现</strong>。复杂需求按需补规格/计划/测试。timeline 自动记录开发事件,你不需要主动跑命令。</p>
+  </div>
+</section>
 
-    <div class="phase">
-      <div class="phase-label">日常做需求 · 复杂按需</div>
-      <ul class="phase-list">
-        <li><code>/write-prd</code> 写业务文档<em>（给业务方 / 领导确认）</em></li>
-        <li><code>/write-spec</code> 写技术规格<em>（归档业务行为 / 规则 / 接口 / 数据,作为 plan 的稳定输入）</em></li>
-        <li><code>/write-plan</code> 拆执行计划<em>（给 agent 执行）</em></li>
-        <li><code>/code-impact-markdown</code> 沉淀业务决策 / 概念到 <code>docs/knowledge/</code></li>
-      </ul>
+<section>
+  <h2>各流程详解</h2>
+
+  <div class="tabs-bar">
+    <button class="tab-btn active" onclick="switchTab(this, 'tab-dev')">开发流程</button>
+    <button class="tab-btn" onclick="switchTab(this, 'tab-api-test')">接口测试</button>
+    <button class="tab-btn" onclick="switchTab(this, 'tab-unit-test')">单元测试</button>
+    <button class="tab-btn" onclick="switchTab(this, 'tab-knowledge')">知识管理</button>
+    <button class="tab-btn" onclick="switchTab(this, 'tab-postdoc')">事后文档</button>
+    <button class="tab-btn" onclick="switchTab(this, 'tab-review')">工作回顾</button>
+  </div>
+
+  <div id="tab-dev" class="tab-panel active">
+    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;">做需求的主线。</p>
+    <ul class="phase-list">
+      <li><strong style="color:var(--color-primary);">必经</strong> <code>/clarify-requirements</code> 澄清意图、业务边界、技术约束<em>(不拍板实现手段)</em></li>
+      <li><strong style="color:var(--color-primary);">核心</strong> <code>/write-spec</code> 写技术规格——唯一契约<em>(归档业务行为/规则/接口/数据/权限/异常/验收)</em></li>
+      <li><span class="opt">可选</span> <code>/write-plan</code> 拆执行计划<em>(大需求/跨模块;手段选型在这一步结合代码定——纯工程手段 plan 自主,有业务可观察后果的回跳 spec 业务拍板)</em></li>
+      <li><strong style="color:var(--color-primary);">必经</strong> <code>/implementation</code><em>(简单:1-3 文件/单模块)</em>或 <code>/subagent-implement</code><em>(复杂:≥3 任务跨域,派子 agent 隔离上下文)</em></li>
+    </ul>
+    <div class="highlight">
+      <p>日常默认 2 步:澄清 + 实现。spec 是唯一契约——「没有任何业务义务存在于 spec 之外」,变更时只改 spec 一处,下游重新派生。</p>
     </div>
+  </div>
 
-    <div class="phase">
-      <div class="phase-label">编码完成后 · 按需</div>
-      <ul class="phase-list">
-        <li><code>/write-api</code> 自动生成 bruno 测试接口<em>（识别新增接口 → 生成测试规格 + .bru + 多环境配置 + bruno.json,只造弹药不跑测试）</em></li>
-        <li><code>/run-api-test</code> 跑接口测试 + 核实写接口 DB 副作用 + 出报告<em>（指定需求或接口触发；写接口必须查 DB 验数据,HTTP 200 ≠ 通过；失败只报告不修不重跑）</em></li>
-        <li><code>/write-api-doc</code> 生成静态 HTML 接口文档<em>（与 write-api / run-api-test 独立并列）</em></li>
-        <li><code>/code-impact-docgen</code> 自测通过后合成 feature 设计文档</li>
-      </ul>
+  <div id="tab-api-test" class="tab-panel">
+    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;"><strong>需求开发完成后</strong>,从 spec 到测试报告的全自动闭环。</p>
+    <ul class="phase-list">
+      <li><code>/write-api</code> 基于 spec 接口章节自动生成 bruno 测试接口<em>(.bru + 内嵌断言 + 真实参数 + 多环境配置)</em></li>
+      <li><code>/run-api-test</code> 跑测试 + 核实写接口 DB 副作用 + 出报告 <em>—— <strong>写接口必须查 DB 验数据,HTTP 200 ≠ 通过</strong></em></li>
+    </ul>
+    <div class="highlight">
+      <p>产物落在 <code>docs/bruno/</code>(接口定义,bruno app 可直接打开)+ <code>docs/features/&lt;前缀&gt;/</code>(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。失败只报告不修代码不重跑,交用户决定。</p>
     </div>
+  </div>
 
-    <div class="phase">
-      <div class="phase-label">工作回顾 · 按需</div>
-      <ul class="phase-list">
-        <li><code>/developer-timeline</code> 生成日报 / 周报 / 月报 / 阶段总结 / 交付汇报</li>
-        <li>直接问「我上周做了什么」「这个月干了啥」「X 是哪天做的」也能答</li>
-        <li><code>/code-impact-docgen</code> 从知识库合成面向人类阅读的业务 / 技术文档<em>（HTML 或 Markdown）</em></li>
-      </ul>
+  <div id="tab-unit-test" class="tab-panel">
+    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;"><strong>需求开发完成后</strong>的独立流程,共享 spec 作为输入(与接口测试同节奏)。</p>
+    <ul class="phase-list">
+      <li><code>/write-unit-test-spec</code> 基于 spec 产出测试规格文档<em>(零代码依赖——该测哪些路径/边界/异常)</em></li>
+      <li><code>/write-unit-test-code</code> 基于测试规格 + 已有实现,填实测试代码 + 跑测试 + 出报告 <em>—— 找不到测试规格则退出要求先跑 write-unit-test-spec</em></li>
+    </ul>
+    <div class="highlight">
+      <p>产物落在 <code>docs/features/&lt;前缀&gt;/</code>(测试规格 + 报告)+ 项目测试目录。</p>
     </div>
+  </div>
 
-    <div class="phase">
-      <div class="phase-label">背后 · agent 自动</div>
-      <ul class="phase-list">
-        <li>agent 经 <code>codegraph_explore</code> 自动查代码结构、调用链、影响半径<em>（你不用主动跑）</em></li>
-        <li>文件改动 → watcher 自动增量同步,无需手动 reindex</li>
-        <li><code>status</code> / <code>sync</code> / <code>explore</code> / <code>docs</code> / <code>db</code> / <code>timeline</code> 等子命令由 agent / skill 调用,人类日常不主动跑</li>
-      </ul>
+  <div id="tab-knowledge" class="tab-panel">
+    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;">两个知识积累闭环,用得越多越值钱。</p>
+
+    <p style="font-weight:600;font-size:14.5px;margin:0 0 8px;">业务知识(沉淀 → 召回)</p>
+    <ul class="phase-list">
+      <li><code>/knowledge-write</code> 把有价值的知识沉淀到 <code>docs/knowledge/</code><em>(开发收尾自动提示,也可随时手动触发)</em></li>
+      <li><code>knowledge-recall</code> 做需求前自动召回相关概念、对齐术语 <em>—— agent 自动触发</em></li>
+      <li><code>knowledge-api</code> 已知概念名时精确查知识库 <em>—— agent 自动触发</em></li>
+      <li><code>/knowledge-init</code> 接手陌生项目时批量探索建档 <em>—— 可选,只跑一次</em></li>
+    </ul>
+
+    <p style="font-weight:600;font-size:14.5px;margin:16px 0 8px;">数据模型(导出 → 探索 → 回写)</p>
+    <ul class="phase-list">
+      <li><code>/export-table-ddl</code> 按工程批量导出 DDL 基线(一表一文件)<em>—— 项目接入时跑一次,schema 变了重跑</em></li>
+      <li><code>db-query</code> 查数据时<strong>首选读本地 DDL</strong>(便宜),只在知识库没有或要实际数据时才连库(贵,兜底);探索发现回写 DISCOVERED 块 <em>—— agent 自动触发</em></li>
+    </ul>
+    <div class="highlight">
+      <p>业务知识落在 <code>docs/knowledge/*.md</code>(写前必过 <code>cgraphx docs validate</code>);数据模型落在 <code>docs/schema-knowledge/&lt;工程&gt;/</code>。重 dump 时 DISCOVERED 块<strong>自动保留</strong>,积累不丢。</p>
     </div>
+  </div>
 
-    <div class="phase">
-      <div class="phase-label">项目上下文 · agent 自动</div>
-      <ul class="phase-list">
-        <li><code>code-impact-api</code> agent 自动查 <code>docs/knowledge/</code> 业务决策 / 概念 / 历史教训</li>
-        <li><code>db-query</code> agent 自动查 MySQL / PostgreSQL 验证数据假设,沉淀 schema 知识到 <code>docs/schema-knowledge/</code></li>
-      </ul>
+  <div id="tab-postdoc" class="tab-panel">
+    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;"><strong>发布后 · 按需</strong>——不在开发主链上,不参与流程门禁。</p>
+    <ul class="phase-list">
+      <li><span class="post">发布后</span> <code>/write-prd</code> 业务需求文档<em>(给领导/客户/业务方审阅)</em></li>
+      <li><span class="post">自测通过后</span> <code>/write-design-doc</code> 设计文档<em>(面向研发/技术负责人/维护者)</em></li>
+      <li><span class="post">接口开发完毕后</span> <code>/write-api-doc</code> 接口文档<em>(仅本次新增接口)</em></li>
+    </ul>
+    <div class="highlight">
+      <p>设计原则:前期文档越少,变更回归成本越低;发布后写的是<strong>实际交付的行为</strong>,不存在文档与系统漂移的问题。</p>
     </div>
   </div>
 
-  <div class="highlight">
-    <p><strong>日常默认 2 步</strong>——澄清 + 实现;复杂需求按需补 <code>prd</code> / <code>spec</code> / <code>plan</code> / 沉淀。<strong>cgraphx 在背后自动同步代码图谱、agent 自动查</strong>,你不需要主动跑命令。</p>
+  <div id="tab-review" class="tab-panel">
+    <ul class="phase-list">
+      <li><code>/developer-timeline</code> 从自动记录的开发事件流生成日报/周报/月报/阶段总结/使用习惯分析</li>
+      <li><code>/write-workload</code> 产出需求工作量汇报<em>(内部对账/甲方结款依据)</em></li>
+    </ul>
+    <div class="highlight">
+      <p>timeline 通过隐藏 hook 自动记录(每次约 5ms,不阻塞工作流),数据一直在 <code>.cgraphx/cgraphx.db</code>——不用回忆,不用拼凑。</p>
+    </div>
   </div>
+
+  <script>
+  function switchTab(btn, panelId) {
+    document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+    document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
+    btn.classList.add('active');
+    document.getElementById(panelId).classList.add('active');
+  }
+  </script>
 </section>
 
 <section>
   <h2>docs/ 目录速查</h2>
-  <p>翻文档时知道去哪儿找 —— 哪个目录由哪个 skill 自动维护。</p>
+  <p>翻文档时知道去哪儿找——哪个目录由哪个 skill 维护。</p>
 
   <div class="docs-legend">
     <span><span class="dot must"></span>必有</span>
     <span><span class="dot opt"></span>可选(按需)</span>
-    <span><span class="dot local"></span>本地测试相关</span>
+    <span><span class="dot post"></span>发布后按需</span>
   </div>
 
-  <pre class="docs-tree"><b>docs/</b>                                              <span class="ann"># 必有</span>
-├── <b>bruno/</b>                                          <span class="ann"># 本地,write-api + run-api-test 维护</span>
-│   ├── bruno.json                                  <span class="ann"># bruno app 识别整个 collection</span>
-│   ├── <b>environments/</b>
-│   │   ├── local.bru                               <span class="ann"># write-api 生成骨架,用户填 secret</span>
-│   │   ├── staging.bru
-│   │   └── production.bru
-│   ├── <b>common/</b>                                   <span class="ann"># 通用接口(登录 / 健康检查等),不绑需求</span>
-│   │   └── &lt;接口名&gt;/&lt;场景&gt;.bru
-│   └── <b>&lt;服务名&gt;/</b>                                <span class="ann"># 如 a-service / b-service</span>
-│       └── <b>&lt;需求前缀&gt;/</b>                            <span class="ann"># 按需求隔离,跨需求不覆盖</span>
-│           └── <b>&lt;接口名&gt;/</b>                          <span class="ann"># 接口目录,本需求内累积场景</span>
-│               ├── &lt;场景1&gt;.bru                    <span class="ann"># 如 正常.bru</span>
-│               └── &lt;场景2&gt;.bru                    <span class="ann"># 如 缺prodInstId.bru</span>
+  <pre class="docs-tree"><b>docs/</b>
+├── <b>features/</b>   需求目录(单次需求工作目录,spec 必有)
+│   └── <b>&lt;日期&gt;-&lt;编号&gt;-&lt;前缀&gt;/</b>
+│       ├── &lt;前缀&gt;-spec.md            <span class="skill">/write-spec</span>           <span class="must">必有</span>  <span class="ann">唯一契约</span>
+│       ├── <b>plan/</b>                     <span class="skill">/write-plan</span>           <span class="opt">可选</span>  <span class="ann">大需求</span>
+│       ├── &lt;前缀&gt;-需求文档.md         <span class="skill">/write-prd</span>            <span class="post">发布后</span>  <span class="ann">按需</span>
+│       ├── &lt;前缀&gt;-api-spec.md        <span class="skill">/write-api</span>            <span class="opt">可选</span>  <span class="ann">开发完成后</span>
+│       ├── &lt;前缀&gt;-测试报告.md         <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">write-api 后</span>
+│       ├── &lt;前缀&gt;-测试验证.jsonl      <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">自动产出</span>
+│       ├── &lt;前缀&gt;-单元测试-spec.md    <span class="skill">/write-unit-test-spec</span> <span class="opt">可选</span>  <span class="ann">开发完成后</span>
+│       ├── &lt;前缀&gt;-单元测试报告.md     <span class="skill">/write-unit-test-code</span> <span class="opt">可选</span>  <span class="ann">开发完成后</span>
+│       └── &lt;前缀&gt;-设计文档.md         <span class="skill">/write-design-doc</span>     <span class="post">发布后</span>  <span class="ann">按需</span>
+│
+├── <b>knowledge/</b>   业务知识库(跨需求共享)
+│   └── *.md                          <span class="skill">/knowledge-write</span> <span class="ann">沉淀</span>  <span class="skill">/knowledge-init</span> <span class="ann">批量建档</span>
 │
-├── <b>features/</b>                                       <span class="ann"># 必有,全流程 skills 维护</span>
-│   └── <b>&lt;前缀&gt;/</b>                                   <span class="ann"># 前缀 = 需求/bug编号 + 名称,如 CRM-req19230-号百商品详情查询接口</span>
-│       ├── &lt;前缀&gt;-需求文档.md                       <span class="skill">/write-prd</span>
-│       ├── &lt;前缀&gt;-spec.md                           <span class="must">必有</span>  <span class="skill">/write-spec</span>
-│       ├── <b>plan/</b>                                <span class="opt">可选</span>  <span class="ann">(按复杂度)</span>  <span class="skill">/write-plan</span>
-│       ├── &lt;前缀&gt;-api-spec.md                      <span class="skill">/write-api</span>
-│       ├── &lt;前缀&gt;-测试报告.md                        <span class="skill">/run-api-test</span>
-│       ├── &lt;前缀&gt;-测试验证.jsonl                    <span class="skill">/run-api-test</span>
-│       └── &lt;前缀&gt;-设计文档.md                        <span class="skill">/code-impact-docgen</span>
+├── <b>bruno/</b>   接口测试(bruno app 可直接打开)
+│   ├── bruno.json
+│   ├── <b>environments/</b>                 <span class="ann">local / staging / production</span>
+│   └── <b>&lt;服务&gt;/&lt;需求前缀&gt;/&lt;接口&gt;/</b>&lt;场景&gt;.bru
 │
-├── <b>knowledge/</b>                                     <span class="ann"># 公共必选,业务知识库</span>
-│                                                      <span class="skill">/code-impact-init</span> <span class="ann">批量写</span>
-│                                                      <span class="skill">/code-impact-markdown</span> <span class="ann">按需写</span>
+├── <b>schema-knowledge/</b>   数据模型知识库
+│   └── <b>&lt;工程&gt;/</b>
+│       ├── INDEX.md                  <span class="ann">表清单 + 注释(agent 入口)</span>
+│       ├── pending-comments.sql      <span class="ann">DBA 待执行 COMMENT(action 队列)</span>
+│       └── ddl/&lt;table&gt;.sql           <span class="ann">DDL + DISCOVERED 块(探索积累)</span>
 │
-└── <b>schema-knowledge/</b>                             <span class="opt">可选</span>  <span class="ann">DB schema 知识</span>
-                                                       <span class="skill">/db-query</span> <span class="ann">自动写</span>
+└── <b>guides/</b>   项目规范(<span class="skill">/init-project-guides</span> <span class="ann">生成</span>)
+    ├── coding-standards.md
+    ├── interface-standards.md
+    ├── data-standards.md
+    ├── testing-standards.md
+    └── git-standards.md              <span class="ann">commit 门禁指向此文件</span>
   </pre>
 
   <div class="highlight">
-    <p><strong>两个核心目录</strong>——<code>docs/features/</code> 是单次需求工作目录(必须有 spec.md),<code>docs/knowledge/</code> 是跨需求共享的业务知识库。<strong>bruno/ 和 schema-knowledge/ 按需出现</strong>,只在跑接口测试 / 查 DB 时产生。</p>
+    <p><strong>两个核心目录</strong>——<code>docs/features/</code> 是单次需求工作目录(必须有 spec),<code>docs/knowledge/</code> 是跨需求共享的业务知识库。bruno/、schema-knowledge/、guides/ 按需出现。</p>
   </div>
 </section>
 
 <footer>
-  <p>cgraphx 使用说明 · 2026-07-13</p>
+  <p>cgraphx 使用说明 · 2026-07-30</p>
 </footer>
 
 </div>