@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/design/m2-m3-tool-input-spec-20260518-1425.md

@@ -0,0 +1,131 @@
+# M2 + M3: event tool_input 类型契约 Spec
+
+## 目标
+为 `ForgeEvent.tool_input` 建立可选字段类型契约消除 `as any` 泛滥；同时让 `event_id` 在 parser 层尊重外部传入，为 hook 端端到端去重铺路。
+
+## 调研结果
+
+### M2 使用统计（30 处含 `as any` 与 `as Record<string,unknown>`）
+
+| 工具 | 字段 | 使用点 |
+|---|---|---|
+| Bash | `command` | `web/routes/sessions.ts:95,97,223,225`; `anti-pattern-detector.ts:256,363`; `cli/commands/logs.ts:44`; `history-exporter.ts:103` |
+| Edit/Write | `file_path` | `sessions.ts:90,91,232,233`; `tasks.ts:161,163`; `anti-pattern-detector.ts:140,356`; `resume-manager.ts:118`; `cli/commands/logs.ts:45`; `weekly-report.ts:274` |
+| UserPromptSubmit fallback | `user_prompt` | `sessions.ts:82,83,159,164`; `tasks.ts:168,171`; `daemon/index.ts:161`; `storage/base.ts:253,257` |
+| Agent/Task | `subagent_type`, `name`, `prompt` | `web/routes/tasks.ts:125–129`; `daemon/handlers/post-tool-use.ts:29` |
+| Notebook | `notebook_path` | `weekly-report.ts:274` |
+
+### 使用模式
+**几乎全部是防御访问**：`(e.tool_input as any)?.command || ''`、`?.file_path`、`?? input?.command`。零处做 strict assert。
+真正窄化的两处（`post-tool-use.ts:29`、`web/routes/tasks.ts:111-131`）也是 `?` 容忍。
+
+### M3 event_id 流向
+- **Hook 端**：`pre-tool-use.sh`、`post-tool-use.sh` 等当前**不产生** `event_id`；payload 里无该字段。
+- **Queue 层**：`core/queue/index.ts:83` 已经写了 `event.event_id ?? randomUUID()`，文件名也依赖之。
+- **Storage 层**：`core/storage/events.ts:21` schema 已 `event_id: z.string().uuid().optional()`，`writeEvent` 也是 `event.event_id || randomUUID()`。**唯一断点**：`daemon/event-parser.ts:23` 无条件 `randomUUID()`，先于 storage，外部传入永远被覆盖。
+
+## 方案选择
+
+### M2：方案 B（lenient bag）+ 辅助 getter
+理由：
+1. 30+ 处使用全是 undefined-friendly，方案 A 需要给每个站点加 type guard，改动大且收益低（hook event 名不等于 tool 名，`Edit`/`Write`/`Bash` 都来自 `event.tool_name`，不是 `hook_type` discriminator）。
+2. Claude Code 的 tool 集合是开放的（未来还可能新增），union 难以穷举；bag + index signature 兼容前向。
+3. 已有 `anti-pattern-detector.ts:354-365` 的 `extractFilePath`/`extractBashCommand` 范式，扩展即可。
+
+### M3：保留 `event_id` 可选透传
+`event-parser.ts` 改为 `event_id: validated.event_id ?? randomUUID()`，schema 加 `event_id: z.string().uuid().optional()`。**不强制 hook 端立即生成**。
+
+## 类型设计
+
+```ts
+// core/types.ts 追加
+export interface ToolInputFields {
+  // Bash
+  command?: string;
+  description?: string;
+  // Edit / Write / Read / NotebookEdit
+  file_path?: string;
+  notebook_path?: string;
+  old_string?: string;
+  new_string?: string;
+  content?: string;
+  // Agent / Task
+  subagent_type?: string;
+  name?: string;
+  prompt?: string;
+  // UserPromptSubmit fallback envelope
+  user_prompt?: string;
+  // 兼容未来未知字段
+  [key: string]: unknown;
+}
+
+export interface ForgeEvent {
+  // ...
+  tool_input?: ToolInputFields;
+  tool_output?: Record<string, unknown>;
+  event_id?: string;
+}
+
+// helpers（放 core/event-fields.ts）
+export function getCommand(e: ForgeEvent): string | undefined {
+  const c = e.tool_input?.command;
+  return typeof c === 'string' ? c : undefined;
+}
+export function getFilePath(e: ForgeEvent): string | undefined {
+  const fp = e.tool_input?.file_path ?? e.tool_input?.notebook_path;
+  return typeof fp === 'string' && fp.length > 0 ? fp : undefined;
+}
+export function getUserPrompt(e: ForgeEvent): string | undefined {
+  return e.user_prompt ?? (typeof e.tool_input?.user_prompt === 'string' ? e.tool_input.user_prompt : undefined);
+}
+export function getSubagentType(e: ForgeEvent): string | undefined {
+  const s = e.tool_input?.subagent_type;
+  return typeof s === 'string' ? s : undefined;
+}
+```
+
+## 改造范围
+
+| 文件 | 改动点 | 行数 |
+|---|---|---|
+| `src/core/types.ts` | 加 `ToolInputFields`；改 `ForgeEvent.tool_input` 类型 | +25 |
+| `src/core/event-fields.ts`（新建）| 4 个 getter | +30 |
+| `src/daemon/event-parser.ts` | schema 加 `event_id.optional()`；`event_id ?? randomUUID()`；`tool_input as ToolInputFields` | ~4 |
+| `src/daemon/index.ts:161` | 改 `getUserPrompt(event)` | 1 |
+| `src/web/routes/sessions.ts` | 8 处 `(tool_input as any)?.X` → getter | ~10 |
+| `src/web/routes/tasks.ts` | 5 处 | ~6 |
+| `src/cli/commands/logs.ts:42-46` | 直接用 `e.tool_input?.command` 等 | 4 |
+| `src/web/analytics/anti-pattern-detector.ts` | `extractFilePath/Command` 内联或调 getter | 2 |
+| `src/daemon/handlers/post-tool-use.ts:29` | `getSubagentType(event)` | 1 |
+| `src/daemon/handlers/history-exporter.ts:102-103` | 直接 `.file_path / .command` | 2 |
+| `src/claudemd/resume-manager.ts:118` | 已经接近规范，去 `as string` | 1 |
+| `src/core/storage/events.ts` | `tool_input` 反序列化 cast 调整 | 1 |
+| `src/core/storage/tasks.ts:233` | 同上 | 1 |
+| `src/core/storage/base.ts:253,257` | SQL 不变（已用 json_extract）；无代码改动 | 0 |
+
+## 测试策略
+- **新增** `src/tests/event-fields.test.ts`：4 个 getter × {undefined, wrong type, valid} 共约 12 case。
+- **新增** `src/tests/event-parser.test.ts`：
+  - 无 `event_id` → 自动生成 UUID
+  - 传入 `event_id` (合法 UUID) → 透传
+  - `tool_input` 含 `command/file_path` → 落到 `ToolInputFields`
+- **回归**：`src/tests/events.test.ts`（若存在）补一条 `writeEvent` + parser 端到端 event_id 透传 + 重放 UNIQUE 拒收。
+- **集成**：现有 `tests/integration/*` 跑完无回归。
+
+## 风险与回滚
+- **风险 1**：`ToolInputFields` 加 `[key:string]: unknown` 等于半放弃严格性 — 接受，因为目标是消 `as any` 与统一访问入口，而非全量窄化。
+- **风险 2**：M3 让外部 event_id 入库后，若 hook 端误用非 UUID 字符串，zod `.uuid()` 会抛 → 由 parser 抛错入 daemon error 路径，与现有 schema 失败同语义。回滚：parser 单行还原 `randomUUID()`。
+- **回滚成本**：M2 是纯类型 + getter 替换，git revert 即可；M3 仅 2 行。
+
+## 实施顺序
+1. 新增 `core/types.ts` 类型 + `core/event-fields.ts` getter，先跑 `tsc --noEmit`（此时旧 `as any` 仍有效，无破坏）。
+2. 改 `daemon/event-parser.ts`（M3 + tool_input cast）；加 parser 测试。
+3. 逐文件替换 `as any`：`daemon/index.ts` → `cli/logs.ts` → `daemon/handlers/*` → `web/routes/sessions.ts` → `web/routes/tasks.ts` → `web/analytics/*` → `claudemd/resume-manager.ts`。每改一个跑 `tsc --noEmit`。
+4. 跑 `npm test`，确认 0 回归。
+5. 抓 hook 端 event_id 预生成作为后续 follow-up（**本 spec 不实施**）。
+
+## 命名遵循
+- Getter 用 `get*` 前缀（符合「获取单个资源用 `get`」约定）。
+- 类型用 PascalCase：`ToolInputFields`。
+- 文件 kebab-case：`event-fields.ts`。
+- 字段名沿用 hook 原始命名 (`file_path` / `command` / `subagent_type`)，不改 snake_case。

package/docs/design/m7-routing-event-association-spec-20260518-1545.md

@@ -0,0 +1,103 @@
+# M7: post-tool-use routing_event 关联修复 Spec
+
+## 目标
+
+修复 `PostToolUseHandler` 将 Agent 调用错误关联到已完成（`obeyed` 已填）的 routing_event 的时序错配 bug：把"最近一条"语义收紧为"最近一条 pending（`obeyed IS NULL`）"。
+
+## 数据流分析
+
+### routing_event 生命周期
+
+| T | 触发 | 操作 | 状态 |
+|---|---|---|---|
+| T0 | user prompt P1 | `UserPromptHandler` 写 routing_event#1 | `obeyed=NULL` |
+| T1 | Agent 调用 | `PostToolUseHandler` 取 most-recent → #1，update | `#1.obeyed=1` |
+| T2 | 普通工具（Read/Bash）| 不写 routing_event | `#1.obeyed=1` |
+| T3 | user prompt P2 | 写 routing_event#2 | `#2.obeyed=NULL`，#1 仍 obeyed=1 |
+| T4 | Agent 调用 | 取 most-recent → #2 | 正常 |
+
+### 现有读写点（routing_events）
+
+| 调用方 | 操作 | 方法 |
+|---|---|---|
+| `user-prompt.ts:120` | 每次 prompt insert，`obeyed=null` | `writeRoutingEvent` |
+| `post-tool-use.ts:33` | 取最近一条 | `getRecentRoutingEvent(sessionId)` |
+| `post-tool-use.ts:35` | 更新 obeyed/routed_to_* | `updateRoutingEvent(id, patch)` |
+| daemon 恢复 | 拉 pending（项目级） | `queryPendingRoutingEvents(ageMs)` |
+| 统计/聚合 | 只读 | `queryRoutingEvents`、`aggregate*` |
+
+## Bug 复现路径
+
+**真实错配场景**：同一 user prompt 内连续 2+ 个 Agent 调用。
+
+```
+T0  prompt P1 → write #1 (obeyed=NULL)
+T1  Agent#a 完成 → PostToolUse → getRecent → #1 → update {obeyed=1, routed_to_name='a'}
+T2  Agent#b 完成 → PostToolUse → getRecent → 仍是 #1 → update {obeyed=1, routed_to_name='b'}
+```
+
+后果：#1 的 `routed_to_name`、`first_tool_ts` 被第二个 Agent **覆盖**；第二个 Agent 调用**没有自己的归属 routing_event**，统计层缺数。
+
+**第二种错配**：跨 prompt 但中间 prompt 未走 UserPromptHandler（如 hook 失败 / daemon 重启后 buffer 丢失），下一个 Agent 仍会误关联到旧的 obeyed=1 的事件并把它再次覆盖。
+
+> review 描述的"覆盖未来不相关"其实是"覆盖过去已完成"语义，效果一致——丢失上次填充结果且当前调用无新行。
+
+## 方案对比
+
+| 维度 | A: `obeyed IS NULL` 过滤 | B: sessionKey in-mem cache | C: A + B 组合 |
+|---|---|---|---|
+| 实现复杂度 | 低（1 个 SQL 改/加方法）| 中（cache + 失效）| 中高 |
+| 跨进程/重启鲁棒 | 强（DB 真源）| 弱（cache 丢）| 强 |
+| 同 prompt 多 Agent 行为 | 第 2 个 Agent 找不到 pending → 跳过更新（数据丢失）| 同上，cache 也指向同一 id | 同上 |
+| 时序正确性 | 强 | 强（cache 命中时）| 强 |
+| 风险 | 同 prompt 多 Agent 漏记需另案 | daemon crash 丢 cache | 复杂度高于必要 |
+
+**推荐：方案 A**。理由：
+1. DB 是单一真源，无 cache 一致性问题。
+2. 同 prompt 多 Agent 场景下，方案 A 与 B 行为一致（都只命中一次），不构成 B 的优势。
+3. "同 prompt 多 Agent 都要记录"是 M7 范围外的功能扩展（应该在 PostToolUse 里 **insert** 新 routing_event 而非 update），不在此次修复内。
+
+## 改造点
+
+| 文件 | 改动 |
+|---|---|
+| `src/core/storage/routing.ts` | `getRecentRoutingEvent(sessionId)` SQL 加 `AND obeyed IS NULL`；或保留旧方法 + 新增 `getRecentPendingRoutingEvent(sessionId)`（推荐后者，向后兼容） |
+| `src/daemon/handlers/post-tool-use.ts:33` | 调用新方法 `getRecentPendingRoutingEvent` |
+| `src/core/storage/sqlite.ts` | facade 透传新方法 |
+| `tests/unit/storage/routing.test.ts`（如缺则新建）| 单测：3 个时序 case |
+| `tests/unit/daemon/post-tool-use.test.ts`（如缺则新建）| handler 行为测试 |
+
+## 测试策略
+
+**Storage 单测**（routing.test.ts）：
+- `getRecentPendingRoutingEvent` 返回最近 `obeyed IS NULL` 的行
+- 已存在 obeyed=1 在前 + 新 pending 在后 → 返回新 pending
+- 全部 obeyed 已填 → 返回 null（不误返）
+- 不同 session 隔离
+
+**Handler 单测**（post-tool-use.test.ts，新增）：
+- 时序 case 1（同 prompt 第 2 个 Agent）：第 1 个 update 成功，第 2 个找不到 pending → silently skip（assert：原 routing_event 不被二次覆盖）
+- 时序 case 2（跨 prompt）：每个 prompt 的 Agent 关联到自己的 event
+- 时序 case 3（无 routing_event）：handler 不抛错
+
+不需要集成测试（daemon 端到端已被 daemon 集成测试覆盖）。
+
+## 风险与回滚
+
+- **风险 1**：同 prompt 多 Agent 漏记 → 文档化为已知限制（M7 范围外）；后续可改为 PostToolUse insert 新行。
+- **风险 2**：旧库残留 obeyed=NULL 的 stale 行可能被新 prompt 的 Agent 错关 → 因为 ORDER BY ts DESC 限制 + session_id 过滤，最多影响"在该 session 内有非常老的孤儿 pending"的极端情况；可接受。
+- **回滚**：单 commit revert；新方法可保留无害。
+
+## 实施顺序
+
+1. routing.ts 新增 `getRecentPendingRoutingEvent`（SQL 加 `AND obeyed IS NULL`）
+2. sqlite.ts facade 透传
+3. routing.test.ts 加单测
+4. post-tool-use.ts 切换调用
+5. post-tool-use.test.ts 加 handler 单测
+6. `npx tsc --noEmit` + 相关 vitest
+
+## 命名遵循
+
+- `getRecentPendingRoutingEvent`（get 前缀，单个资源；与现有 `getRecentRoutingEvent`、`getExperimentAssignment` 对齐）
+- 不用 `queryRecentPending*`（query 前缀留给返回行集合的方法）

package/docs/design/project-path-gitroot-spec-20260518-1715.md

@@ -0,0 +1,134 @@
+# project-path git root 修复 Spec
+
+## 目标
+让 5 个 hook 在 IDE 调用时把 `cwd`（可能是任意子目录）上溯为 git 仓库根目录后再发给 daemon，从根上阻止子目录被生成 `.claude-forge/`。
+
+## 调研结果
+
+| 位置 | 现状 | 改造需求 |
+|---|---|---|
+| `src/hooks/pre-tool-use.sh:15-16` | `PROJECT_PATH=$(jq -r '.cwd'); fallback $PWD` | 套上 `resolve_project_path` |
+| `src/hooks/post-tool-use.sh:17-18` | 同上 | 同上 |
+| `src/hooks/user-prompt-submit.sh:15-16` | 同上 | 同上 |
+| `src/hooks/stop.sh:11-12` | 同上 + 未引用 hook-lib.sh | 先 source hook-lib.sh 再用函数 |
+| `src/hooks/notification.sh:13-14` | 同上 | 同上 |
+| `src/hooks/hook-lib.sh` | 已有 `send_event_or_enqueue` 公共函数 | **新增 `resolve_project_path`** |
+| `src/daemon/handlers/history-exporter.ts:24` | `path.join(project_path,'.claude-forge','history')` | 不动（hook 端已传 git root） |
+| `src/cli/commands/executions.ts:16,53,85` | `process.cwd()` 拼 `.claude-forge` | 新增 `resolveGitRoot()` helper |
+| `src/templates/template-manager.ts:82,89` | `initProject(_, projectPath)` 由调用方传入 | 调用方传 git root 即可（init CLI 自身改） |
+
+观察：`hook-lib.sh` 已存在公共函数集，`stop.sh` 是唯一未 source 它的 hook（手写 nc + socket），改造时顺手补齐一致性。
+
+## 方案选择
+
+| | A. Hook 端解析 git root | B. Daemon 端解析 | C. 完全消除目录 | D. 混合 hash |
+|---|---|---|---|---|
+| 改动面 | 5 hook + lib + CLI | 1 处 | 涉及多模块迁移 | A+ 存储改造 |
+| 性能 | bash 上溯（O(深度)，无子进程）| 每次 spawn `git` | 同 A | 同 A |
+| 下游受益 | 全部 | 仅 history-exporter | 全部但破坏可见性 | 全部 |
+| 老数据 | 兼容（新数据用新值）| 兼容 | 需迁移 | 需迁移 |
+| 风险 | 0 测试 hook 改动 | 子进程开销 | discoverability 破坏 | 引入新维度 |
+
+**推荐 A**：根因解决 + 保留用户在项目根 `ls` 即可看到 history 的可见性 + 不引入子进程开销。bash `while` 上溯零依赖，daemon / CLI 自动受益。
+
+## 改造范围（约 70 行）
+
+| 文件 | 行数 | 说明 |
+|---|---|---|
+| `src/hooks/hook-lib.sh` | +25 | 新增 `resolve_project_path` |
+| `src/hooks/pre-tool-use.sh` | -2 +1 | 替换两行 |
+| `src/hooks/post-tool-use.sh` | -2 +1 | 同上 |
+| `src/hooks/user-prompt-submit.sh` | -2 +1 | 同上 |
+| `src/hooks/stop.sh` | -2 +2 | 先 source hook-lib.sh，再用函数 |
+| `src/hooks/notification.sh` | -2 +1 | 同上 |
+| `src/cli/commands/executions.ts` | +8 | 新增 `resolveGitRoot()` 替换 3 处 `process.cwd()` |
+| `src/cli/commands/init.ts`（调用 template-manager 处，需 grep 确认）| +2 | 把传给 `initProject` 的 `projectPath` 改成 git root |
+| 新增 `tests/unit/hooks/resolve-project-path.test.sh`（或 vitest 调 bash）| ~40 | safety-net |
+| 新增 `tests/integration/hook-gitroot.integration.test.ts` | ~50 | 端到端 |
+
+## hook-lib.sh 公共函数设计
+
+```bash
+# resolve_project_path <input_cwd>
+# 从 input_cwd 上溯查找最近的 .git 目录，输出 git root。
+# 非 git 项目 / 上溯到根 / 输入为空 → 回退到 input_cwd（再回退到 $PWD）。
+# 防御：最多上溯 64 层，避免符号链接环。
+resolve_project_path() {
+  local dir="${1:-$PWD}"
+  [ -z "$dir" ] && dir="$PWD"
+
+  # 规整为绝对路径（不依赖 realpath）
+  case "$dir" in
+    /*) ;;
+    *)  dir="$PWD/$dir" ;;
+  esac
+
+  local guard=0
+  while [ "$dir" != "/" ] && [ "$dir" != "." ] && [ $guard -lt 64 ]; do
+    if [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then  # 后者兼容 git worktree
+      printf '%s' "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+    guard=$((guard + 1))
+  done
+
+  # 未找到 → 回退到原 cwd
+  printf '%s' "${1:-$PWD}"
+}
+```
+
+调用方一行替换：
+```bash
+RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
+```
+
+## CLI / daemon 端兼容
+
+**daemon 端**：不改。`history-exporter.ts:24` 信任传入的 `event.project_path`（hook 端已是 git root）。
+
+**CLI 端 `executions.ts`**：新增 helper（放 `src/core/utils/git.ts`）：
+```typescript
+export function resolveGitRoot(start = process.cwd()): string {
+  try {
+    return execSync('git rev-parse --show-toplevel', { cwd: start, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString().trim() || start;
+  } catch { return start; }
+}
+```
+三处 `path.join(process.cwd(), '.claude-forge', ...)` → `path.join(resolveGitRoot(), '.claude-forge', ...)`。
+
+**template-manager.ts**：函数本身签名不变（接收 `projectPath`），改 init 命令调用侧。
+
+## 测试策略
+
+- **safety-net (单测 bash 函数)**：构造 fixture `/tmp/forge-test/repo/.git/`，对 `resolve_project_path /tmp/forge-test/repo/a/b/c` 断言返回 git root；非 git 目录断言回退；空输入断言回退到 `$PWD`。
+- **集成**：vitest 起一个 daemon，构造 `cwd=fixture/sub/dir` 的 INPUT，跑 `pre-tool-use.sh`，从 daemon storage queryEvents 断言 `project_path === fixture` 而非子目录。
+- **回归**：现有 daemon 集成测试不需要改（hook 端透明改造）。
+- **CLI 端**：单测 `resolveGitRoot()` 在 git 仓 / 非 git 仓两种 cwd 下的返回值。
+
+## 风险与回滚
+
+- **`.git` 是文件（worktree）场景**：`[ -f "$dir/.git" ]` 已兼容。
+- **非 git 项目**：fallback 原 cwd，行为不变。
+- **monorepo 子模块各自 .git**：返回最近的 git root，符合预期。
+- **历史数据**：旧 sessions.project_path 仍是子目录路径，不做迁移；可选清单：列出 sessions 表去重 project_path，提供 `cf admin remap-project-path` 工具（非本次范围）。
+- **bash on Linux/macOS 差异**：用 POSIX 内建（`dirname` / `case`），不依赖 `realpath`。
+- **回滚**：还原 6 个文件即可，无 schema 变更。
+
+## 实施顺序（refactor-safe）
+
+1. **safety-net 阶段**：先写 `tests/unit/hooks/resolve-project-path.test.sh`（或 vitest 用 `child_process.execSync('bash -c "source hook-lib.sh && resolve_project_path ..."')`）和 `tests/integration/hook-gitroot.integration.test.ts`（先红）
+2. **lib 阶段**：在 `hook-lib.sh` 新增 `resolve_project_path` → 单测转绿
+3. **hook 改造**：5 个 hook 替换两行；`stop.sh` 同时改为 `source hook-lib.sh`（顺手补一致性）→ 集成测试转绿
+4. **CLI 阶段**：新增 `src/core/utils/git.ts::resolveGitRoot`，改 `executions.ts` 3 处 + `init` 调用侧
+5. **验证**：`npx tsc --noEmit` + `npm test` + 手工到 fixture 子目录跑 `cf executions list` 确认走 git root
+6. **release**：bump patch 版本，changelog 注明"hooks 解析 git root，不再在子目录生成 .claude-forge"
+
+## 命名遵循
+
+- bash 函数：`resolve_project_path`（snake_case，与 hook-lib 现有 `send_event_or_enqueue` / `_enqueue_event_bg` 一致）
+- TS 工具函数：`resolveGitRoot`（camelCase，`get` 前缀不适用因为这是计算非查询）
+- 新文件：`src/core/utils/git.ts`（kebab 化已为单词，遵循现有 `time.ts` / `session.ts`）
+- 测试文件：`tests/unit/hooks/resolve-project-path.test.sh` 或 `.test.ts`、`tests/integration/hook-gitroot.integration.test.ts`