@andyqiu/codeforge 0.3.5 → 0.3.7

package/commands/refactor.md

@@ -0,0 +1,79 @@
+---
+description: 安全重构工作流，先补特征测试再重构，保证行为不变
+agent: planner
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: refactor
+  version: 1.0.0
+  trigger_workflow: refactor
+  requires_human_approval: true
+  allowed_tools: smart_search, save_chat_insight, pending-changes, repo-map, nav-find, nav-goto, bash
+  说明：workflow-engine 看到 trigger_workflow=refactor 拦截 /refactor 触发对应 YAML
+-->
+
+
+# /refactor — 安全重构工作流
+
+触发 `workflows/refactor.yaml`。核心原则：**先补 characterization test 锁定现状行为，再重构**（参考 Working Effectively with Legacy Code）。
+
+## 输入
+
+用户需求：$ARGUMENTS
+
+## 当前仓库改动概览（自动注入）
+
+```
+!`git diff --stat`
+```
+
+## 用法
+
+```
+/refactor lib/foo.ts 里的 doBar 函数
+/refactor 把 user-service 缓存层抽出来
+/refactor #234 提到的 N+1 query
+```
+
+## 流程（7 步，由 refactor.yaml 编排）
+
+| 步骤 | Agent | 动作 | 是否需审批 |
+|------|------|------|-----------|
+| 1. 规划 | planner | 出重构方案 + smart_search 历史经验 | 否 |
+| 2. 补特征测试 | coder | 先写 characterization tests（锁定现状） | 否，auto_feedback 自纠 |
+| 3. 确认覆盖 | reviewer | 确认测试覆盖待重构代码路径 | 否 |
+| 4. 重构 | coder | 实施重构，每步保证测试仍绿 | 否，auto_feedback 自纠 |
+| 5. 审阅 | reviewer | 确认行为不变 + 代码更清晰 | 否 |
+| 6. 落地 | coder | `pending-changes apply_all` | **必审批**（YAML 写死） |
+| 7. 沉淀 | reviewer | `save_chat_insight` 把经验回写 KH | 否（写失败 skip） |
+
+## 与 /tdd 的区别
+
+| 维度 | /refactor | /tdd |
+|---|---|---|
+| 起点 | 已有可工作代码（可能很烂） | 新功能从零开始 |
+| 测试角色 | 锁定现状（characterization test） | 驱动设计（先红再绿） |
+| 终极目标 | 行为不变 + 代码更清晰 | 实现新功能 + 测试覆盖 |
+
+## 自主度（AGENTS.md C18）
+
+`/refactor` 默认 `semi`：风险动作（apply / bash）弹审批，但 `auto_feedback` 在测试反复失败时**自动 escalate 给 reviewer**（避免 coder 死循环）。
+
+## 失败处理
+
+| 失败位置 | 行为 |
+|---------|------|
+| step 1 (规划)        | abort |
+| step 2 (补测试)      | auto_feedback 3 轮重试，仍败 escalate reviewer |
+| step 3 (覆盖不足)    | REQUEST_CHANGES → 回 step 2 重补，max_loops=3 兜底 |
+| step 4 (重构)        | auto_feedback 5 轮重试，仍败 escalate reviewer |
+| step 5 (审阅 REQUEST_CHANGES) | 回 step 4 重做 |
+| step 6 (apply)       | hash 漂移则拒（防脏覆盖） |
+| step 7 (沉淀)        | skip |
+
+## 元数据
+
+- `agent`: `planner` —— 起手让 planner 出方案
+- `trigger_workflow`: `refactor`
+- `requires_human_approval`: `true` —— 高影响命令，CLI/UI 额外确认

package/commands/review.md

@@ -0,0 +1,66 @@
+---
+description: 审阅 PR / diff / 本地未提交改动，输出 APPROVE/REQUEST_CHANGES/BLOCK
+agent: reviewer
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: review
+  version: 1.0.0
+  trigger_workflow: code-review
+  allowed_tools: smart_search, save_chat_insight, pending-changes, bash, repo-map, nav-find
+  说明：workflow-engine 看到 trigger_workflow=code-review 拦截 /review 触发对应 YAML
+-->
+
+
+# /review — 代码审阅工作流
+
+触发 `workflows/code-review.yaml`。**只读流程**：不 stage 任何改动，不 apply 任何 pending。
+
+## 输入
+
+用户需求：$ARGUMENTS
+
+## 当前仓库改动概览（自动注入）
+
+```
+!`git diff --stat`
+```
+
+## 用法
+
+```
+/review                    # 审本地未提交改动（默认）
+/review <PR URL>           # 审指定 PR
+/review --base main        # 审当前分支与 main 的 diff
+```
+
+## 流程（4 步，由 code-review.yaml 编排）
+
+| 步骤 | Agent | 动作 | 是否需审批 |
+|------|------|------|-----------|
+| 1. 准备 diff | reviewer | 取 diff 上下文 + smart_search 历史经验 | 否 |
+| 2. 出审阅维度 | planner | 列出本次必查维度（安全/性能/可维护性/测试/风格） | 否 |
+| 3. 审阅 | reviewer | 按维度逐项审 + 跑测试 + 给 APPROVE/REQUEST_CHANGES/BLOCK | 否 |
+| 4. 沉淀 | reviewer | 把发现的 gotcha 沉淀回 KH | 否（写失败 skip） |
+
+## 与 /plan / /ship 的关系
+
+- `/plan` = 规划（不写代码）
+- `/ship` = 全套（规划 → coder → review → apply → 沉淀）
+- `/review` = **只审，不动手**：用于 PR review、code review 例会、入职新人代码巡检
+
+## 失败处理
+
+| 失败位置 | 行为 |
+|---------|------|
+| step 1 (准备 diff) | abort：取不到 diff 后续无意义 |
+| step 2 (出维度)   | abort：planner 出不来维度则无可执行清单 |
+| step 3 (审阅 BLOCK) | abort：严重问题，用户决定是否继续 |
+| step 4 (沉淀)     | skip：KH 写失败不能让审阅结果"看起来失败" |
+
+## 元数据
+
+- `agent`: `reviewer` —— 起手就切到 reviewer
+- `trigger_workflow`: `code-review`
+- 不像 `/ship`，本命令**不需要 human_approval**（因为只读，无副作用）

package/commands/tdd.md

@@ -0,0 +1,91 @@
+---
+description: TDD 严格流程 RED → GREEN → REFACTOR，测试驱动新功能
+agent: planner
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: tdd
+  version: 1.0.0
+  trigger_workflow: tdd
+  requires_human_approval: true
+  allowed_tools: smart_search, save_chat_insight, pending-changes, repo-map, nav-find, nav-goto, bash
+  说明：workflow-engine 看到 trigger_workflow=tdd 拦截 /tdd 触发对应 YAML
+-->
+
+
+# /tdd — Test-Driven Development 工作流
+
+触发 `workflows/tdd.yaml`。严格 **RED → GREEN → REFACTOR** 三步循环，避免"先写实现再补测试"反 TDD。
+
+## 输入
+
+用户需求：$ARGUMENTS
+
+## 当前仓库改动概览（自动注入）
+
+```
+!`git diff --stat`
+```
+
+## 用法
+
+```
+/tdd 给 lib/utils 加一个 deepMerge 函数
+/tdd 实现 #345：用户登录 24h 内失败 5 次自动锁定
+/tdd 给 Channel 加 LarkChannel 子类型
+```
+
+## 流程（7 步，由 tdd.yaml 编排，max_loops=5）
+
+| 步骤 | Agent | 动作 | 是否需审批 |
+|------|------|------|-----------|
+| 1. 拆需求 | planner | 把需求拆成可测的小步骤清单 | 否 |
+| 2. 写测试-RED | coder | 先写测试（不写实现） | 否 |
+| 3. 验证 RED | reviewer | 跑 npm test 确认测试**确实红了**（绿则 BLOCK） | 否 |
+| 4. 最小实现-GREEN | coder | 写最小实现让测试变绿（不超出需要） | 否，auto_feedback 自纠 |
+| 5. 重构-REFACTOR | coder | 可选 refactor，测试必须仍绿 | 否，可 skip |
+| 6. 审阅 | reviewer | 确认三步全做 + 测试覆盖核心 | 否 |
+| 7. 落地 | coder | `pending-changes apply_all` | **必审批**（YAML 写死） |
+
+## TDD 三色循环
+
+```
+┌─────────────────────────────────────────────────────┐
+│  RED    →  写一个失败的测试（描述期望行为）            │
+│  GREEN  →  写最简实现让测试通过（不超出测试需要）       │
+│  REFACT →  在测试保护下重构（可选；测试仍绿才能进下一轮） │
+└─────────────────────────────────────────────────────┘
+```
+
+`max_loops=5` 表示 reviewer REQUEST_CHANGES 时最多回到 step 2 重做 5 轮，防止死循环。
+
+## 与 /ship / /refactor 的区别
+
+| 维度 | /ship | /refactor | /tdd |
+|---|---|---|---|
+| 起点 | 任何需求 | 已有代码（改善结构） | 新功能（从零） |
+| 测试态度 | 写完后测 | 改前先锁定 | **先红再绿** |
+| 适用 | 大部分日常 | 技术债清理 | 新功能 + 高质量要求 |
+
+## 自主度
+
+`/tdd` 默认 `semi`：apply 必审批；其余步骤 auto_feedback 自纠。
+
+## 失败处理
+
+| 失败位置 | 行为 |
+|---------|------|
+| step 1 (拆需求) | abort |
+| step 2 (写测试) | retry 1 次 |
+| step 3 (验证 RED 失败，测试是绿的) | BLOCK：测试无效，必须重写 |
+| step 4 (最小实现) | auto_feedback 5 轮 |
+| step 5 (REFACTOR 失败) | skip：refactor 是可选 |
+| step 6 (审阅 REQUEST_CHANGES) | 回 step 2，max_loops=5 |
+| step 7 (apply) | hash 漂移则拒 |
+
+## 元数据
+
+- `agent`: `planner` —— 起手让 planner 拆需求
+- `trigger_workflow`: `tdd`
+- `requires_human_approval`: `true`

package/dist/index.js

@@ -8965,6 +8965,7 @@ import { promises as fs2 } from "node:fs";
 import * as path4 from "node:path";
 
 // lib/channels.ts
+import { createHmac } from "node:crypto";
 var TEMPLATE_RE = /\$\{([a-zA-Z_][a-zA-Z0-9_.]*)(?:\|([^}]*))?\}/g;
 function renderChannelTemplate(template, ev) {
   const missing = new Set;
@@ -9078,6 +9079,10 @@ async function sendOne(ev, ch, deps) {
       return await sendKh(ev, ch, deps);
     case "mcp":
       return await sendMcp(ev, ch, deps);
+    case "slack":
+      return await sendSlack(ev, ch, deps);
+    case "lark":
+      return await sendLark(ev, ch, deps);
   }
 }
 async function sendWebhook(ev, ch, deps) {
@@ -9217,6 +9222,224 @@ async function sendMcp(ev, ch, deps) {
     error: r.ok ? undefined : r.error ?? "mcp 调用失败"
   };
 }
+function transformSlackToWebhook(ch, ev) {
+  const missing = new Set;
+  const titleTpl = ch.title_template ?? "${title|}";
+  const msgTpl = ch.message_template ?? "${message|}";
+  const title = renderChannelTemplate(titleTpl, ev);
+  const message = renderChannelTemplate(msgTpl, ev);
+  title.missing.forEach((k) => missing.add(k));
+  message.missing.forEach((k) => missing.add(k));
+  const titleText = title.rendered.trim() ? title.rendered : ev.event;
+  const mentionText = (ch.mentions ?? []).map((id) => id.startsWith("@") || id.startsWith("<") ? id : `<@${id}>`).join(" ");
+  const color = severityToSlackColor(ev.severity);
+  const blocks = [
+    {
+      type: "header",
+      text: { type: "plain_text", text: titleText.slice(0, 150), emoji: true }
+    }
+  ];
+  if (message.rendered.trim()) {
+    blocks.push({
+      type: "section",
+      text: { type: "mrkdwn", text: message.rendered.slice(0, 3000) }
+    });
+  }
+  if (mentionText) {
+    blocks.push({
+      type: "context",
+      elements: [{ type: "mrkdwn", text: mentionText }]
+    });
+  }
+  const footerParts = [`event=\`${ev.event}\``];
+  if (ev.session_id)
+    footerParts.push(`session=\`${ev.session_id.slice(0, 8)}\``);
+  footerParts.push(`ts=<!date^${Math.floor(ev.timestamp / 1000)}^{date_short_pretty} {time}|${new Date(ev.timestamp).toISOString()}>`);
+  blocks.push({
+    type: "context",
+    elements: [{ type: "mrkdwn", text: footerParts.join(" · ") }]
+  });
+  const payload = {
+    attachments: [{ color, blocks }]
+  };
+  if (ch.channel)
+    payload.channel = ch.channel;
+  if (ch.username)
+    payload.username = ch.username;
+  if (ch.icon_emoji)
+    payload.icon_emoji = ch.icon_emoji;
+  return { body: JSON.stringify(payload), missing: [...missing] };
+}
+function severityToSlackColor(sev) {
+  if (sev === undefined)
+    return "#cccccc";
+  if (sev >= 40)
+    return "#d50000";
+  if (sev >= 30)
+    return "#e91e63";
+  if (sev >= 20)
+    return "#ff9800";
+  if (sev >= 10)
+    return "#36a64f";
+  return "#cccccc";
+}
+async function sendSlack(ev, ch, deps) {
+  if (!deps.fetch) {
+    return { name: ch.name, type: "slack", status: "error", error: "deps.fetch 未注入" };
+  }
+  const { body } = transformSlackToWebhook(ch, ev);
+  try {
+    const resp = await deps.fetch(ch.webhook_url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+    const ok = resp.status >= 200 && resp.status < 300;
+    if (ok) {
+      return {
+        name: ch.name,
+        type: "slack",
+        status: "sent",
+        http_status: resp.status,
+        rendered: body
+      };
+    }
+    return {
+      name: ch.name,
+      type: "slack",
+      status: "error",
+      http_status: resp.status,
+      error: `slack returned ${resp.status}: ${resp.body?.slice(0, 200) ?? ""}`,
+      rendered: body
+    };
+  } catch (err) {
+    return {
+      name: ch.name,
+      type: "slack",
+      status: "error",
+      error: describe2(err),
+      rendered: body
+    };
+  }
+}
+function transformLarkToWebhook(ch, ev) {
+  const missing = new Set;
+  const titleTpl = ch.title_template ?? "${title|}";
+  const msgTpl = ch.message_template ?? "${message|}";
+  const titleR = renderChannelTemplate(titleTpl, ev);
+  const msgR = renderChannelTemplate(msgTpl, ev);
+  titleR.missing.forEach((k) => missing.add(k));
+  msgR.missing.forEach((k) => missing.add(k));
+  const titleText = titleR.rendered.trim() || ev.event;
+  const messageText = msgR.rendered.trim();
+  const mentionMarkdown = (ch.mentions ?? []).map((id) => {
+    if (id === "@all" || id === "all")
+      return '<at user_id="all"></at>';
+    if (id.startsWith("<at"))
+      return id;
+    return `<at user_id="${id}"></at>`;
+  }).join(" ");
+  const headerTemplate = severityToLarkHeader(ev.severity);
+  const elements = [];
+  if (messageText || mentionMarkdown) {
+    const fullMsg = [messageText, mentionMarkdown].filter(Boolean).join(`
+
+`);
+    elements.push({
+      tag: "div",
+      text: { tag: "lark_md", content: fullMsg.slice(0, 3000) }
+    });
+  }
+  const footer = [
+    `**event**: \`${ev.event}\``,
+    ev.session_id ? `**session**: \`${ev.session_id.slice(0, 8)}\`` : null,
+    `**ts**: ${new Date(ev.timestamp).toISOString()}`
+  ].filter(Boolean).join(" · ");
+  elements.push({
+    tag: "note",
+    elements: [{ tag: "lark_md", content: footer }]
+  });
+  const payload = {
+    msg_type: "interactive",
+    card: {
+      config: { wide_screen_mode: true },
+      header: {
+        template: headerTemplate,
+        title: { tag: "plain_text", content: titleText.slice(0, 150) }
+      },
+      elements
+    }
+  };
+  return { body: JSON.stringify(payload), missing: [...missing] };
+}
+function severityToLarkHeader(sev) {
+  if (sev === undefined)
+    return "grey";
+  if (sev >= 40)
+    return "carmine";
+  if (sev >= 30)
+    return "red";
+  if (sev >= 20)
+    return "orange";
+  if (sev >= 10)
+    return "blue";
+  return "grey";
+}
+function computeLarkSign(secret, timestampSec) {
+  const stringToSign = `${timestampSec}
+${secret}`;
+  const hmac = createHmac("sha256", stringToSign);
+  hmac.update("");
+  return hmac.digest("base64");
+}
+async function sendLark(ev, ch, deps) {
+  if (!deps.fetch) {
+    return { name: ch.name, type: "lark", status: "error", error: "deps.fetch 未注入" };
+  }
+  const { body: cardBody } = transformLarkToWebhook(ch, ev);
+  let body = cardBody;
+  if (ch.secret) {
+    const tsSec = Math.floor((deps.now ? deps.now() : Date.now()) / 1000);
+    const sign = computeLarkSign(ch.secret, tsSec);
+    const parsed = JSON.parse(cardBody);
+    parsed.timestamp = String(tsSec);
+    parsed.sign = sign;
+    body = JSON.stringify(parsed);
+  }
+  try {
+    const resp = await deps.fetch(ch.webhook_url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+    const ok = resp.status >= 200 && resp.status < 300;
+    if (ok) {
+      return {
+        name: ch.name,
+        type: "lark",
+        status: "sent",
+        http_status: resp.status,
+        rendered: body
+      };
+    }
+    return {
+      name: ch.name,
+      type: "lark",
+      status: "error",
+      http_status: resp.status,
+      error: `lark returned ${resp.status}: ${resp.body?.slice(0, 200) ?? ""}`,
+      rendered: body
+    };
+  } catch (err) {
+    return {
+      name: ch.name,
+      type: "lark",
+      status: "error",
+      error: describe2(err),
+      rendered: body
+    };
+  }
+}
 function dedupeTags(defaults, evTags) {
   const set = new Set;
   if (defaults) {
@@ -11141,6 +11364,51 @@ function applyFocus(ranked, focus) {
   const rest = others.filter((n) => !isAdj(n.rel));
   return [center, ...adj, ...rest];
 }
+function renderMermaid(map, opts = {}) {
+  const top = opts.top ?? 20;
+  const dir = opts.direction ?? "LR";
+  const focus = opts.focus ? toPosix(opts.focus.replace(/^\.\//, "")) : undefined;
+  const sorted = [...map.ranked].sort((a, b) => b.score - a.score).slice(0, top);
+  const idMap = new Map;
+  for (const f of sorted) {
+    idMap.set(f.rel, "n" + sha1Short(f.rel));
+  }
+  const lines = [];
+  lines.push(`flowchart ${dir}`);
+  for (const f of sorted) {
+    const id = idMap.get(f.rel);
+    const basename = f.rel.split(/[\\/]/).pop() ?? f.rel;
+    const label = `${escapeLabel(basename)}<br/><small>${f.score.toFixed(2)}</small>`;
+    lines.push(`  ${id}["${label}"]`);
+  }
+  const topSet = new Set(sorted.map((f) => f.rel));
+  for (const f of sorted) {
+    const from = idMap.get(f.rel);
+    for (const dep of f.deps ?? []) {
+      if (topSet.has(dep)) {
+        const to = idMap.get(dep);
+        lines.push(`  ${from} --> ${to}`);
+      }
+    }
+  }
+  if (focus && idMap.has(focus)) {
+    lines.push(`  classDef focus fill:#ff9800,stroke:#e65100,color:#fff`);
+    lines.push(`  ${idMap.get(focus)}:::focus`);
+  }
+  return lines.join(`
+`);
+}
+function sha1Short(s) {
+  let h = 2166136261 >>> 0;
+  for (let i = 0;i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+function escapeLabel(s) {
+  return s.replace(/["`]/g, "'");
+}
 
 // tools/repo-map.ts
 var description17 = [
@@ -11149,6 +11417,7 @@ var description17 = [
   "- planner agent 接到新需求 → 先 smart_search → 再 repo-map 找代码入口",
   "- 用户问「这个项目怎么组织的 / 入口在哪 / 哪些是核心模块」",
   "- 跨多个文件的重构前，先用 focus= 看清依赖关系",
+  '- 想要可视化依赖图时传 format="mermaid"（Markdown 渲染器会自动出图）',
   "**何时不需要**：",
   "- 用户已指明确切文件，且只在该文件内改动",
   "- 项目地图本会话已生成且未发生大改"
@@ -11159,6 +11428,7 @@ var ArgsSchema17 = z18.object({
   top: z18.number().int().min(1).max(100).optional().describe("展示 top N 文件，默认 20；想要全图可传 100"),
   focus: z18.string().optional().describe("聚焦文件（仓内 POSIX 相对路径）：把它和它的直接依赖 / 反向依赖排在前面"),
   max_files: z18.number().int().min(10).max(5000).optional().describe("扫描文件数上限，默认 500；超过自动截断"),
+  format: z18.enum(["markdown", "mermaid", "both"]).optional().describe("输出格式：markdown(默认，文字 + 星级评分)/mermaid(flowchart 流程图，可贴 mermaid.live 渲染)/both(两者，方便对照)"),
   _raw: z18.boolean().optional()
 });
 async function execute17(input) {
@@ -11171,19 +11441,32 @@ async function execute17(input) {
     };
   }
   const args = parsed.data;
+  const format = args.format ?? "markdown";
   try {
     const map = await buildRepoMap({
       root: args.root,
       maxFiles: args.max_files
     });
-    const md = renderMarkdown(map, {
-      top: args.top,
-      focus: args.focus
-    });
+    let body;
+    if (format === "markdown") {
+      body = renderMarkdown(map, { top: args.top, focus: args.focus });
+    } else if (format === "mermaid") {
+      const mmd = renderMermaid(map, { top: args.top, focus: args.focus });
+      body = "```mermaid\n" + mmd + "\n```";
+    } else {
+      const md = renderMarkdown(map, { top: args.top, focus: args.focus });
+      const mmd = renderMermaid(map, { top: args.top, focus: args.focus });
+      body = md + `
+
+## Dependency Graph
+
+\`\`\`mermaid
+` + mmd + "\n```";
+    }
     const truncated = args.max_files ? map.totalFiles >= args.max_files : map.totalFiles >= 500;
     return {
       ok: true,
-      markdown: md,
+      markdown: body,
       raw: args._raw ? map : undefined,
       stats: {
         totalFiles: map.totalFiles,
@@ -16600,7 +16883,7 @@ import * as zlib from "node:zlib";
 // lib/version-injected.ts
 function getInjectedVersion() {
   try {
-    const v = "0.3.5";
+    const v = "0.3.7";
     if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) {
       return v;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andyqiu/codeforge",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "CodeForge — opencode 的零侵入扩展包",
   "type": "module",
   "private": false,
@@ -38,6 +38,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "bench": "node --experimental-strip-types --no-warnings ./scripts/bench-repo-map.mjs",
+    "bench:json": "node --experimental-strip-types --no-warnings ./scripts/bench-repo-map.mjs --json",
     "lint": "tsc --noEmit",
     "check:bun": "node ./scripts/check-bun.mjs",
     "install:local": "bash ./install.sh",
@@ -79,6 +82,7 @@
     "@opencode-ai/plugin": "^1.15.0",
     "@opencode-ai/sdk": "^1.15.0",
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
     "husky": "^9.1.7",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/workflows/code-review.yaml

@@ -0,0 +1,66 @@
+# ──────────────────────────────────────────────────────────────
+# code-review.yaml — 审阅别人的 PR / diff（最常用 workflow）
+# trigger: /review
+# 流程：取 diff → planner 出审阅维度 → reviewer 多维度审 → 沉淀
+# 注意：本流程只读，不 stage / apply 任何改动
+# ──────────────────────────────────────────────────────────────
+
+name: code-review
+max_loops: 1
+version: 1.0.0
+description: |
+  审阅 PR / diff / 本地未提交改动的工作流：
+    1. 取 diff（默认 git diff，支持指定 base 分支或 PR URL）
+    2. planner 看 diff 内容，列出审阅维度（安全 / 性能 / 可维护性 / 测试 / 风格）
+    3. reviewer 按维度逐项审，跑测试，输出 APPROVE / REQUEST_CHANGES / BLOCK
+    4. 沉淀关键发现到 KH（gotcha / convention 类）
+
+trigger: /review
+
+steps:
+  - name: 准备 diff
+    agent: reviewer
+    description: 取 diff 上下文（git diff / PR）
+    actions:
+      - tool: smart_search
+        args:
+          query: "code review checklist ${user_request}"
+          limit: 5
+        on_error: skip
+    on_error: abort
+
+  - name: 出审阅维度
+    agent: planner
+    description: 基于 diff 内容 + 项目特点，列出本次审阅必查的维度清单
+    inject_context:
+      role_hint: 你只列审阅维度，不评审具体代码
+    on_error: abort
+
+  - name: 审阅
+    agent: reviewer
+    description: 按维度清单逐项审，跑测试，输出 APPROVE/REQUEST_CHANGES/BLOCK
+    actions:
+      - tool: pending-changes
+        args:
+          action: list
+          status: pending
+        on_error: skip
+    on_decision:
+      APPROVE: continue
+      REQUEST_CHANGES: continue   # 仍 continue 进入沉淀，REQUEST_CHANGES 是给提交者看的
+      BLOCK: abort
+    on_error: abort
+
+  - name: 沉淀
+    agent: reviewer
+    description: 把发现的 gotcha / convention 沉淀到 KH
+    actions:
+      - tool: save_chat_insight
+        args:
+          insight: "${session_summary}"
+          category: gotcha
+          tags:
+            - "trigger:/review"
+            - "workflow:code-review"
+        on_error: skip
+    on_error: skip

package/workflows/refactor.yaml

@@ -0,0 +1,106 @@
+# ──────────────────────────────────────────────────────────────
+# refactor.yaml — 安全重构工作流
+# trigger: /refactor
+# 流程：planner → 补 characterization test → 重构 → 测试仍绿 → apply
+# 参考：Working Effectively with Legacy Code（Michael Feathers）
+# ──────────────────────────────────────────────────────────────
+
+name: refactor
+max_loops: 3
+version: 1.0.0
+description: |
+  安全重构流程（参考 Working Effectively with Legacy Code）：
+    1. planner 分析现状、列出重构方案
+    2. coder A 阶段：先补 characterization test（描述现状行为，可能很难看）
+    3. reviewer 确认 test 覆盖待重构代码的现有行为
+    4. coder B 阶段：开始重构，每步必须保证 test 仍绿
+    5. reviewer 最终确认：行为不变 + 代码更清晰
+    6. apply 落地
+
+trigger: /refactor
+
+steps:
+  - name: 规划
+    agent: planner
+    description: 列出重构目标 / 涉及文件 / 拆步计划
+    actions:
+      - tool: smart_search
+        args:
+          query: "${user_request} refactor"
+          limit: 5
+        on_error: skip
+    on_error: abort
+
+  - name: 补特征测试
+    agent: coder
+    description: 先写 characterization tests，覆盖现状行为（不为重构，只为锁定行为）
+    auto_feedback:
+      test_cmd: "npm test"
+      max_retries: 3
+      error_excerpt_lines: 5
+      escalate_to: reviewer
+    on_error: retry
+    max_retries: 1
+
+  - name: 确认覆盖
+    agent: reviewer
+    description: 确认 characterization tests 覆盖了所有待重构代码路径
+    on_decision:
+      APPROVE: continue
+      REQUEST_CHANGES:
+        action: goto
+        target: 补特征测试
+      BLOCK: abort
+    on_error: abort
+
+  - name: 重构
+    agent: coder
+    description: 实施重构，每步必须保证已写的 tests 全绿
+    auto_feedback:
+      test_cmd: "npm test"
+      max_retries: 5
+      error_excerpt_lines: 5
+      escalate_to: reviewer
+    on_error: retry
+    max_retries: 1
+
+  - name: 审阅
+    agent: reviewer
+    description: 确认行为不变（tests 绿）+ 代码更清晰
+    actions:
+      - tool: pending-changes
+        args:
+          action: list
+          status: pending
+    on_decision:
+      APPROVE: continue
+      REQUEST_CHANGES:
+        action: goto
+        target: 重构
+      BLOCK: abort
+    on_error: abort
+
+  - name: 落地
+    agent: coder
+    description: 用户审批通过后 apply 全部 pending
+    requires_human_approval: true
+    actions:
+      - tool: pending-changes
+        args:
+          action: apply_all
+        on_error: abort
+    on_error: abort
+
+  - name: 沉淀
+    agent: reviewer
+    description: 把这次重构的经验沉淀回 KH
+    actions:
+      - tool: save_chat_insight
+        args:
+          insight: "${session_summary}"
+          category: workflow
+          tags:
+            - "trigger:/refactor"
+            - "workflow:refactor"
+        on_error: skip
+    on_error: skip

package/workflows/tdd.yaml

@@ -0,0 +1,99 @@
+# ──────────────────────────────────────────────────────────────
+# tdd.yaml — Test-Driven Development 严格流程
+# trigger: /tdd
+# 流程：拆需求 → RED 测试 → 验证红 → GREEN 实现 → REFACTOR → 审阅 → apply
+# ──────────────────────────────────────────────────────────────
+
+name: tdd
+max_loops: 5
+version: 1.0.0
+description: |
+  Test-Driven Development 严格流程：
+    1. planner 拆需求成可测的小步骤
+    2. 循环 N 次（每个小步骤）：
+       a. coder 写 RED 测试（必须先红，否则 BLOCK）
+       b. coder 写最小实现（必须变绿）
+       c. coder refactor（仍绿）
+       d. reviewer APPROVE 进下一循环
+    3. 全部完成后 apply
+
+trigger: /tdd
+
+steps:
+  - name: 拆需求
+    agent: planner
+    description: 把需求拆成可测的小步骤清单
+    actions:
+      - tool: smart_search
+        args:
+          query: "${user_request} tdd"
+          limit: 5
+        on_error: skip
+    on_error: abort
+
+  - name: 写测试-RED
+    agent: coder
+    description: 先写测试。必须先跑红（无实现→失败），否则 BLOCK
+    inject_context:
+      role_hint: 你只写测试，不写实现。测试必须先失败再继续
+    on_error: retry
+    max_retries: 1
+
+  - name: 验证 RED
+    agent: reviewer
+    description: 跑 npm test，确认新测试是红的（如果绿了说明测试无效）
+    on_decision:
+      APPROVE: continue   # APPROVE 意味着"测试确实红了"
+      REQUEST_CHANGES:
+        action: goto
+        target: 写测试-RED
+      BLOCK: abort
+    on_error: abort
+
+  - name: 最小实现-GREEN
+    agent: coder
+    description: 写最小实现，让测试变绿。不要超出测试需要
+    auto_feedback:
+      test_cmd: "npm test"
+      max_retries: 5
+      error_excerpt_lines: 5
+      escalate_to: reviewer
+    on_error: retry
+    max_retries: 1
+
+  - name: 重构-REFACTOR
+    agent: coder
+    description: 测试绿了之后可选 refactor；任何时刻测试必须仍绿
+    auto_feedback:
+      test_cmd: "npm test"
+      max_retries: 3
+      error_excerpt_lines: 5
+      escalate_to: reviewer
+    on_error: skip   # refactor 是可选步骤，跳过也行
+
+  - name: 审阅
+    agent: reviewer
+    description: 确认 RED→GREEN→REFACTOR 三步全做，测试覆盖核心
+    actions:
+      - tool: pending-changes
+        args:
+          action: list
+          status: pending
+    on_decision:
+      APPROVE: continue
+      REQUEST_CHANGES:
+        action: goto
+        target: 写测试-RED
+      BLOCK: abort
+    on_error: abort
+
+  - name: 落地
+    agent: coder
+    description: 用户审批通过后 apply 全部 pending
+    requires_human_approval: true
+    actions:
+      - tool: pending-changes
+        args:
+          action: apply_all
+        on_error: abort
+    on_error: abort