@winspan/claude-forge 8.50.6 → 8.51.0

package/src/claudemd/claudemd-generator.ts

@@ -3,13 +3,40 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { ClaudeProvider } from '../core/ai/provider.js';
 import { TechDetector, type TechStack } from './tech-detector.js';
 
 const AUTO_START = '<!-- forge:claudemd-auto -->';
 const AUTO_END = '<!-- forge:end-claudemd-auto -->';
 
+/**
+ * Swarm Protocol — fixed CLAUDE.md preface injected into every project.
+ *
+ * Loaded from `templates/swarm-protocol.md` (same directory as this module's
+ * compiled output). `fileURLToPath(import.meta.url)` resolves to either
+ * `src/claudemd/` (dev via tsx) or `dist/claudemd/` (npm install) — both
+ * have a sibling `templates/` directory after build (see package.json `build`
+ * script which copies *.md into dist/claudemd/templates/).
+ *
+ * Cached at module level: the file is read at most once per process.
+ */
+let _swarmProtocolCache: string | null = null;
+function getSwarmProtocol(): string {
+  if (_swarmProtocolCache !== null) return _swarmProtocolCache;
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const p = join(thisDir, 'templates', 'swarm-protocol.md');
+  if (!existsSync(p)) {
+    throw new Error(
+      `[ClaudeMdGenerator] swarm-protocol.md not found at ${p}. ` +
+        `This indicates a broken build/install. Run \`npm run build\` or reinstall the package.`,
+    );
+  }
+  _swarmProtocolCache = readFileSync(p, 'utf-8');
+  return _swarmProtocolCache;
+}
+
 export class ClaudeMdGenerator {
   readonly detector: TechDetector;
 
@@ -56,7 +83,7 @@ export class ClaudeMdGenerator {
     }
 
     // 3. Swarm 协议 + 项目内容
-    const full = SWARM_PROTOCOL + '\n\n' + projectContent;
+    const full = getSwarmProtocol() + '\n\n' + projectContent;
     return this.merge(full, userContent);
   }
 
@@ -539,239 +566,3 @@ export class ClaudeMdGenerator {
     return [generated.trim(), '', '---', '', userContent.trim()].join('\n');
   }
 }
-
-/**
- * Ruflo-style Swarm Protocol — injected into every project's CLAUDE.md
- * so Claude autonomously invokes multi-agent pipelines for complex tasks.
- */
-/**
- * Core behavioral rules — injected into every project's CLAUDE.md.
- * Simplified to ~140 lines for clarity and reduced instruction drift.
- */
-/**
- * Core behavioral rules — injected into every project's CLAUDE.md.
- * Simplified to ~140 lines for clarity and reduced instruction drift.
- */
-const SWARM_PROTOCOL = `# claude-forge 工作区规范
-
-## 自检（每次响应前必读）
-
-**在开始任何操作前，先问自己**：
-
-1. 我是否要修改 ≥2 个文件？
-2. 我是否要修改 ≥10 行代码？
-3. 这是否是新功能/重构/Bug 修复？
-4. 我修改的代码所在模块**测试覆盖率 < 50%** 吗？
-
-**如果 1-3 任一答案是"是"，且我没有 spawn Agent**：
-- ❌ 停下来 → 重新评估例外 → 否则立即 spawn Agent
-
-**如果 4 答案是"是"**（改老代码 + 测试薄弱）：
-- ❌ 不要 spawn 普通 \`coder\` / \`planner\`
-- ✅ 必须走 **Harness 或 Hybrid 工作流**（详见下方「工作流升级判定」）
-
-**违规示例**：
-- "修复 daemon handler bug（改老代码 + 0 测试）" → 应走 \`harness-hotfix\`，不是 \`coder\`
-- "重构 738 行字面量为 .md 文件" → 应走 \`refactor-safe\`，不是 \`coder\`
-- "新功能加在 hook 脚本" → 应走 \`hybrid-feature-with-safety\`，不是 \`planner+coder\`
-
----
-
-## 核心行为规则
-
-- Do what has been asked; nothing more, nothing less
-- NEVER create files unless absolutely necessary
-- ALWAYS prefer editing existing files to creating new ones
-- ALWAYS read a file before editing it
-- Never continuously check status after spawning agents — wait for results
-
----
-
-## Two-Phase Workflow (BMAD 默认路径)
-
-**适用范围**：≥3 文件改动 / 新功能 / 重构 / 架构调整
-**前提**：通过「工作流升级判定」确认为 BMAD 路径（测试覆盖充分 / 全新模块）
-**如果改老代码 + 测试薄弱** → 改走 Harness/Hybrid 三阶段（见下方）
-
-### Phase 1: Generate Spec
-
-1. Spawn planner/researcher agent with \`run_in_background: true\`
-2. Agent 输出 \`docs/design/[task]-spec-YYYYMMDD-HHMM.md\`，包含：
-   - 目标、改动文件清单、关键设计决策、风险点、测试策略
-   - **禁止写任何代码**
-3. 主线程告诉用户"已 spawn planner，等待 spec 生成"，**然后结束响应**
-
-### Phase 1.5: User Review (Critical Gate)
-
-Agent 完成后，**主线程必须停止并等待用户确认**：
-
-\`\`\`
-设计方案已生成：docs/design/xxx-spec.md
-
-请 review 后回复：
-- "批准" / "approve" → 我会 spawn coder 实现
-- "修改 [意见]" → 我会调整 spec
-- "取消" → 停止任务
-\`\`\`
-
-**绝对禁止**：
-- ❌ 主线程自行判断 spec 质量并进入 Phase 2
-- ❌ 主线程直接 spawn coder 而不等用户确认
-
-### Phase 2: Implement per Spec
-
-收到用户"批准"后：
-1. Spawn coder agent with \`run_in_background: true\`
-2. 严格按 spec 执行，完成后写 \`docs/implementation/[task]-changelog-YYYYMMDD-HHMM.md\`
-
-### 例外
-
-可跳过两阶段：
-- 单文件 1-2 行修改
-- 用户明确说"不需要 spec"
-- 纯查询/调研任务
-
----
-
-## Agent 委托规则
-
-### 默认行为：spawn Agent
-
-接到任务时，**第一反应是 spawn Agent**。主线程只做协调。
-
-### 不 spawn 的例外（仅 4 条）
-
-1. **单行 typo**：1 文件 1 行拼写错误
-2. **协调与汇总**：整合 Agent 结果
-3. **元任务（极小改动）**：git commit/push、daemon 启停、单行规则调整
-4. **即时问答**：不涉及代码/文件的纯对话
-
-**注意**：
-- 例外 #3 不包括"重构 CLAUDE.md"、"修改多个配置文件"等大改动
-- 如果改动 ≥2 文件或 ≥10 行，必须 spawn Agent
-
-### 强制 spawn 的场景
-
-以下必须 spawn Agent：
-- 查/找/看/列出 → Explore agent
-- 函数分析/代码阅读 → doc-reviewer
-- 单文件 2+ 行修改 → coder
-- 实现/修复/重构/优化 → 对应 agent
-
-### 强制理由声明
-
-每次不 spawn 时，必须在响应开头说明：
-
-> 不 spawn 理由：例外 #N [具体原因]
-
----
-
-## 工作流升级判定（spawn agent 前必查）
-
-**默认是 BMAD（planner+coder）**，但满足下表条件**必须升级到 Harness/Hybrid**。
-
-### 判定表
-
-| 任务特征 | 推荐 agent | 工作流序列 |
-|---------|-----------|----------|
-| **改老代码 + 模块测试覆盖 < 50%** | \`refactor-safe\` | safety-net → design → implement → test → review |
-| **已知原因的 Bug 修复**（紧急/明确）| \`harness-hotfix\` | safety-net → fix → verify |
-| **未知/偶发 Bug**（需先定位）| \`harness-debug-full\` | reproduce → safety-net → root-cause → fix → verify |
-| **新功能改老代码 + 测试薄弱** | \`hybrid-feature-with-safety\` | safety-net → analyze → design → implement → test → review |
-| **先修 bug 再加功能** | \`hybrid-fix-then-feature\` | reproduce → fix → verify → design → implement → review |
-| **全新模块 / 测试充分**（覆盖 ≥50%）| \`planner\` + \`coder\` | BMAD analyze → design → implement |
-| **纯调研 / 单行 typo / 元任务** | 不 spawn 或 \`Explore\` | — |
-
-### 测试覆盖快速判定
-
-修改 \`src/<module>/\` 前必查：
-
-\`\`\`bash
-SRC=$(find src/<module> -name "*.ts" -not -name "*.test.ts" 2>/dev/null | wc -l)
-TST=$(find tests/unit/<module> src/tests -name "*.test.ts" 2>/dev/null | wc -l)
-echo "ratio: $TST / $SRC"
-\`\`\`
-
-\`TST/SRC < 50%\` → **触发 Harness safety-net 阶段**（不要直接改代码）
-
-### 项目模块覆盖现状（提醒）
-
-| 模块 | 覆盖判定 | 默认走 |
-|------|---------|--------|
-| \`src/daemon/handlers/\` | 部分（≥50%）| BMAD，但 hotfix 类 bug 走 \`harness-hotfix\` |
-| \`src/daemon/services/\` | **零测试** | **Harness/Hybrid 强制** |
-| \`src/core/storage/\` | 高（≥80%）| BMAD |
-| \`src/core/queue/\` | 高（新写时已加）| BMAD |
-| \`src/skills/\` | 中（~40%）| 大改走 \`refactor-safe\` |
-| \`src/web/routes/\` | 中 | BMAD |
-| \`src/hooks/*.sh\` | 0（无 sh 测试）| 改 hook 必走 Hybrid |
-| \`src/claudemd/\` | 低 | \`refactor-safe\` |
-
-### 违规自查
-
-过去 5 次任务全踩坑，请引以为戒：
-
-- ❌ "修复 daemon schema 收紧拒收 bug"（改 events.ts + 5 个 hook）→ 走了 \`coder\`，应走 \`harness-hotfix\`
-- ❌ "Official Skills 数据分离"（重构 738 行老代码）→ 走了 \`planner+coder\`，应走 \`refactor-safe\`
-- ❌ "Hook 失败缓冲队列"（新功能 + 改 4 个老 hook）→ 走了 \`planner+coder\`，应走 \`hybrid-feature-with-safety\`
-
-**判定时机**：在「自检」之后、「Two-Phase Workflow」之前。判定结果若是 Harness/Hybrid，跳过 Two-Phase，直接 spawn 对应 agent。
-
----
-
-## 并发规则
-
-- All operations MUST be concurrent/parallel in ONE message
-- ALWAYS batch ALL agents in ONE message with \`run_in_background: true\`
-- ALWAYS batch ALL file reads/writes/edits in ONE message
-- ALWAYS batch ALL terminal operations in ONE Bash message
-
----
-
-## 项目特定信息
-
-### 技术栈
-
-- **语言**: TypeScript (Node.js 24+)
-- **数据库**: SQLite (better-sqlite3)
-- **前端**: 原生 HTML + Vanilla JS（单文件 SPA），无打包
-- **测试**: Vitest
-
-### 架构要点
-
-**分层**：
-- \`src/cli/\` — CLI 命令
-- \`src/daemon/\` — 后台守护进程（事件处理）
-- \`src/web/\` — Web 仪表盘
-- \`src/core/\` — 共享核心（storage/config/types）
-- \`src/claudemd/\` — CLAUDE.md 生成器
-- \`src/skills/\` — Skill 匹配与注入
-
-**存储**：
-- 主库：\`~/.claude-forge/data.db\`
-- 表：sessions, events, tasks, routing_events, skill_invocations, token_usage
-
-### 开发规范
-
-**构建与测试**：
-\`\`\`bash
-npm run build        # 构建前后端
-npm test             # 运行测试
-./scripts/dev-daemon.sh restart  # 重启 daemon
-\`\`\`
-
-**守护进程事件推送**：
-- PreToolUse / PostToolUse / UserPromptSubmit / Stop / Notification
-- 通过 Unix socket 推送到 daemon
-
-**注意**：
-- daemon 和 CLI 都用系统 node（v26）
-- better-sqlite3 12.10.0 支持 v26
-- 修改 schema 需要手动迁移（无自动 migration）
-
----
-
-## 上次工作续接
-
-（由 daemon 自动更新，记录最近任务上下文）
-`;

package/src/claudemd/resume-manager.ts

@@ -115,7 +115,7 @@ export class ResumeManager {
       }
 
       if (e.tool_name && ['Edit', 'Write'].includes(e.tool_name)) {
-        const fp = e.tool_input?.file_path as string | undefined;
+        const fp = typeof e.tool_input?.file_path === 'string' ? e.tool_input.file_path : undefined;
         if (fp) editedFiles.add(fp);
       }
 

package/src/claudemd/templates/swarm-protocol.md

@@ -0,0 +1,222 @@
+# claude-forge 工作区规范
+
+## 自检（每次响应前必读）
+
+**在开始任何操作前，先问自己**：
+
+1. 我是否要修改 ≥2 个文件？
+2. 我是否要修改 ≥10 行代码？
+3. 这是否是新功能/重构/Bug 修复？
+4. 我修改的代码所在模块**测试覆盖率 < 50%** 吗？
+
+**如果 1-3 任一答案是"是"，且我没有 spawn Agent**：
+- ❌ 停下来 → 重新评估例外 → 否则立即 spawn Agent
+
+**如果 4 答案是"是"**（改老代码 + 测试薄弱）：
+- ❌ 不要 spawn 普通 `coder` / `planner`
+- ✅ 必须走 **Harness 或 Hybrid 工作流**（详见下方「工作流升级判定」）
+
+**违规示例**：
+- "修复 daemon handler bug（改老代码 + 0 测试）" → 应走 `harness-hotfix`，不是 `coder`
+- "重构 738 行字面量为 .md 文件" → 应走 `refactor-safe`，不是 `coder`
+- "新功能加在 hook 脚本" → 应走 `hybrid-feature-with-safety`，不是 `planner+coder`
+
+---
+
+## 核心行为规则
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless absolutely necessary
+- ALWAYS prefer editing existing files to creating new ones
+- ALWAYS read a file before editing it
+- Never continuously check status after spawning agents — wait for results
+
+---
+
+## Two-Phase Workflow (BMAD 默认路径)
+
+**适用范围**：≥3 文件改动 / 新功能 / 重构 / 架构调整
+**前提**：通过「工作流升级判定」确认为 BMAD 路径（测试覆盖充分 / 全新模块）
+**如果改老代码 + 测试薄弱** → 改走 Harness/Hybrid 三阶段（见下方）
+
+### Phase 1: Generate Spec
+
+1. Spawn planner/researcher agent with `run_in_background: true`
+2. Agent 输出 `docs/design/[task]-spec-YYYYMMDD-HHMM.md`，包含：
+   - 目标、改动文件清单、关键设计决策、风险点、测试策略
+   - **禁止写任何代码**
+3. 主线程告诉用户"已 spawn planner，等待 spec 生成"，**然后结束响应**
+
+### Phase 1.5: User Review (Critical Gate)
+
+Agent 完成后，**主线程必须停止并等待用户确认**：
+
+```
+设计方案已生成：docs/design/xxx-spec.md
+
+请 review 后回复：
+- "批准" / "approve" → 我会 spawn coder 实现
+- "修改 [意见]" → 我会调整 spec
+- "取消" → 停止任务
+```
+
+**绝对禁止**：
+- ❌ 主线程自行判断 spec 质量并进入 Phase 2
+- ❌ 主线程直接 spawn coder 而不等用户确认
+
+### Phase 2: Implement per Spec
+
+收到用户"批准"后：
+1. Spawn coder agent with `run_in_background: true`
+2. 严格按 spec 执行，完成后写 `docs/implementation/[task]-changelog-YYYYMMDD-HHMM.md`
+
+### 例外
+
+可跳过两阶段：
+- 单文件 1-2 行修改
+- 用户明确说"不需要 spec"
+- 纯查询/调研任务
+
+---
+
+## Agent 委托规则
+
+### 默认行为：spawn Agent
+
+接到任务时，**第一反应是 spawn Agent**。主线程只做协调。
+
+### 不 spawn 的例外（仅 4 条）
+
+1. **单行 typo**：1 文件 1 行拼写错误
+2. **协调与汇总**：整合 Agent 结果
+3. **元任务（极小改动）**：git commit/push、daemon 启停、单行规则调整
+4. **即时问答**：不涉及代码/文件的纯对话
+
+**注意**：
+- 例外 #3 不包括"重构 CLAUDE.md"、"修改多个配置文件"等大改动
+- 如果改动 ≥2 文件或 ≥10 行，必须 spawn Agent
+
+### 强制 spawn 的场景
+
+以下必须 spawn Agent：
+- 查/找/看/列出 → Explore agent
+- 函数分析/代码阅读 → doc-reviewer
+- 单文件 2+ 行修改 → coder
+- 实现/修复/重构/优化 → 对应 agent
+
+### 强制理由声明
+
+每次不 spawn 时，必须在响应开头说明：
+
+> 不 spawn 理由：例外 #N [具体原因]
+
+---
+
+## 工作流升级判定（spawn agent 前必查）
+
+**默认是 BMAD（planner+coder）**，但满足下表条件**必须升级到 Harness/Hybrid**。
+
+### 判定表
+
+| 任务特征 | 推荐 agent | 工作流序列 |
+|---------|-----------|----------|
+| **改老代码 + 模块测试覆盖 < 50%** | `refactor-safe` | safety-net → design → implement → test → review |
+| **已知原因的 Bug 修复**（紧急/明确）| `harness-hotfix` | safety-net → fix → verify |
+| **未知/偶发 Bug**（需先定位）| `harness-debug-full` | reproduce → safety-net → root-cause → fix → verify |
+| **新功能改老代码 + 测试薄弱** | `hybrid-feature-with-safety` | safety-net → analyze → design → implement → test → review |
+| **先修 bug 再加功能** | `hybrid-fix-then-feature` | reproduce → fix → verify → design → implement → review |
+| **全新模块 / 测试充分**（覆盖 ≥50%）| `planner` + `coder` | BMAD analyze → design → implement |
+| **纯调研 / 单行 typo / 元任务** | 不 spawn 或 `Explore` | — |
+
+### 测试覆盖快速判定
+
+修改 `src/<module>/` 前必查：
+
+```bash
+SRC=$(find src/<module> -name "*.ts" -not -name "*.test.ts" 2>/dev/null | wc -l)
+TST=$(find tests/unit/<module> src/tests -name "*.test.ts" 2>/dev/null | wc -l)
+echo "ratio: $TST / $SRC"
+```
+
+`TST/SRC < 50%` → **触发 Harness safety-net 阶段**（不要直接改代码）
+
+### 项目模块覆盖现状（提醒）
+
+| 模块 | 覆盖判定 | 默认走 |
+|------|---------|--------|
+| `src/daemon/handlers/` | 部分（≥50%）| BMAD，但 hotfix 类 bug 走 `harness-hotfix` |
+| `src/daemon/services/` | **零测试** | **Harness/Hybrid 强制** |
+| `src/core/storage/` | 高（≥80%）| BMAD |
+| `src/core/queue/` | 高（新写时已加）| BMAD |
+| `src/skills/` | 中（~40%）| 大改走 `refactor-safe` |
+| `src/web/routes/` | 中 | BMAD |
+| `src/hooks/*.sh` | 0（无 sh 测试）| 改 hook 必走 Hybrid |
+| `src/claudemd/` | 低 | `refactor-safe` |
+
+### 违规自查
+
+过去 5 次任务全踩坑，请引以为戒：
+
+- ❌ "修复 daemon schema 收紧拒收 bug"（改 events.ts + 5 个 hook）→ 走了 `coder`，应走 `harness-hotfix`
+- ❌ "Official Skills 数据分离"（重构 738 行老代码）→ 走了 `planner+coder`，应走 `refactor-safe`
+- ❌ "Hook 失败缓冲队列"（新功能 + 改 4 个老 hook）→ 走了 `planner+coder`，应走 `hybrid-feature-with-safety`
+
+**判定时机**：在「自检」之后、「Two-Phase Workflow」之前。判定结果若是 Harness/Hybrid，跳过 Two-Phase，直接 spawn 对应 agent。
+
+---
+
+## 并发规则
+
+- All operations MUST be concurrent/parallel in ONE message
+- ALWAYS batch ALL agents in ONE message with `run_in_background: true`
+- ALWAYS batch ALL file reads/writes/edits in ONE message
+- ALWAYS batch ALL terminal operations in ONE Bash message
+
+---
+
+## 项目特定信息
+
+### 技术栈
+
+- **语言**: TypeScript (Node.js 24+)
+- **数据库**: SQLite (better-sqlite3)
+- **前端**: React 18 + Vite + Tailwind + react-router-dom + react-query + Recharts（`web/` 目录，build 后被 cp 到 dist/web/static/）
+- **测试**: Vitest
+
+### 架构要点
+
+**分层**：
+- `src/cli/` — CLI 命令
+- `src/daemon/` — 后台守护进程（事件处理）
+- `src/web/` — Web 仪表盘
+- `src/core/` — 共享核心（storage/config/types）
+- `src/claudemd/` — CLAUDE.md 生成器
+- `src/skills/` — Skill 匹配与注入
+
+**存储**：
+- 主库：`~/.claude-forge/data.db`
+- 表：sessions, events, tasks, routing_events, skill_invocations, token_usage
+
+### 开发规范
+
+**构建与测试**：
+```bash
+npm run build        # 构建前后端
+npm test             # 运行测试
+./scripts/dev-daemon.sh restart  # 重启 daemon
+```
+
+**守护进程事件推送**：
+- PreToolUse / PostToolUse / UserPromptSubmit / Stop / Notification
+- 通过 Unix socket 推送到 daemon
+
+**注意**：
+- daemon 和 CLI 都用系统 node（v26）
+- better-sqlite3 12.10.0 支持 v26
+- 修改 schema 需要手动迁移（无自动 migration）
+
+---
+
+## 上次工作续接
+
+（由 daemon 自动更新，记录最近任务上下文）

package/src/cli/commands/daemon.ts

@@ -31,7 +31,7 @@ import fs from 'fs';
 import path from 'path';
 import { spawn, execSync } from 'child_process';
 import type { Command } from 'commander';
-import { FORGE_HOME } from '../../core/constants.js';
+import { FORGE_PATHS, DEFAULTS } from '../../core/constants.js';
 import { fileURLToPath } from 'url';
 import {
   install as installLaunchAgent,
@@ -42,10 +42,10 @@ import {
 } from '../../daemon/launchd-installer.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PID_FILE = path.join(FORGE_HOME, 'daemon.pid');
-const DEFAULT_PORT = 3721;
-const STDOUT_LOG = path.join(FORGE_HOME, 'daemon-stdout.log');
-const STDERR_LOG = path.join(FORGE_HOME, 'daemon-stderr.log');
+const PID_FILE = FORGE_PATHS.daemonPid();
+const DEFAULT_PORT = DEFAULTS.WEB_PORT;
+const STDOUT_LOG = FORGE_PATHS.daemonStdout();
+const STDERR_LOG = FORGE_PATHS.daemonStderr();
 
 function readPid(): number | null {
   if (!fs.existsSync(PID_FILE)) return null;
@@ -112,7 +112,7 @@ export function register(program: Command): void {
 
       // Background mode: spawn detached child process
       const daemonScript = path.resolve(__dirname, '../../daemon/index.js');
-      const logFile = path.join(FORGE_HOME, 'daemon.log');
+      const logFile = FORGE_PATHS.daemonLog();
       const out = fs.openSync(logFile, 'a');
 
       const env: Record<string, string> = {

package/src/cli/commands/executions.ts

@@ -2,6 +2,7 @@ import type { Command } from 'commander';
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
+import { resolveGitRoot } from '../../core/utils/git.js';
 
 export function registerExecutionsCommand(program: Command): void {
   const cmd = program.command('executions').description('管理 Agent/Skill 执行文档');
@@ -13,7 +14,7 @@ export function registerExecutionsCommand(program: Command): void {
     .option('--limit <n>', '限制数量', '20')
     .option('--date <date>', '按日期筛选（YYYY-MM-DD）')
     .action(async (opts) => {
-      const baseDir = path.join(process.cwd(), '.claude-forge', 'executions', 'by-route');
+      const baseDir = path.join(resolveGitRoot(), '.claude-forge', 'executions', 'by-route');
       if (!fs.existsSync(baseDir)) {
         console.log('暂无执行文档。请先触发 Agent/Skill 执行。');
         return;
@@ -50,7 +51,7 @@ export function registerExecutionsCommand(program: Command): void {
     .command('open <route_id>')
     .description('打开指定执行的 overview 文档')
     .action((routeId: string) => {
-      const baseDir = path.join(process.cwd(), '.claude-forge', 'executions', 'by-route');
+      const baseDir = path.join(resolveGitRoot(), '.claude-forge', 'executions', 'by-route');
       if (!fs.existsSync(baseDir)) {
         console.error('执行文档目录不存在。');
         process.exit(1);
@@ -82,7 +83,7 @@ export function registerExecutionsCommand(program: Command): void {
     .option('--before <days>', '清理 N 天前的文档', '30')
     .option('--dry-run', '只显示将删除的文件，不实际删除')
     .action(async (opts) => {
-      const baseDir = path.join(process.cwd(), '.claude-forge', 'executions', 'by-route');
+      const baseDir = path.join(resolveGitRoot(), '.claude-forge', 'executions', 'by-route');
       if (!fs.existsSync(baseDir)) {
         console.log('执行文档目录不存在，无需清理。');
         return;

package/src/cli/commands/init.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
 import type { Command } from 'commander';
-import { FORGE_HOME, FORGE_PATHS } from '../../core/constants.js';
+import { FORGE_HOME, FORGE_PATHS, DEFAULTS } from '../../core/constants.js';
 import { copyHookScripts, backupSettings, injectHooks } from '../init/hook-manager.js';
 import chalk from 'chalk';
 
@@ -104,7 +104,7 @@ export function register(program: Command): void {
       // 2. Interactive configuration
       let apiKey = process.env.ANTHROPIC_API_KEY || '';
       let baseUrl = 'https://api.anthropic.com';
-      let webPort = 3721;
+      let webPort: number = DEFAULTS.WEB_PORT;
 
       if (!skipPrompts) {
         console.log(chalk.yellow('\n📝 配置选项（直接回车使用默认值）\n'));

package/src/cli/commands/logs.ts

@@ -40,7 +40,7 @@ function formatEventGrouped(e: ForgeEvent): string {
 function extractDetail(e: ForgeEvent): string {
   if (e.user_prompt) return e.user_prompt.slice(0, 80);
   if (!e.tool_input) return '';
-  const input = e.tool_input as Record<string, unknown>;
+  const input = e.tool_input;
   if (input.command) return String(input.command).slice(0, 80);
   if (input.file_path) return String(input.file_path);
   return JSON.stringify(input).slice(0, 80);

package/src/cli/commands/mcp.ts

@@ -17,11 +17,9 @@
 import { Command } from 'commander';
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import chalk from 'chalk';
 import { ConfigManager } from '../../core/config.js';
-import { DEFAULTS } from '../../core/constants.js';
+import { DEFAULTS, FORGE_PATHS } from '../../core/constants.js';
 
 const SERVER_NAME = 'claude-forge';
 const SCOPE = 'user'; // user scope: 全局可用
@@ -42,7 +40,7 @@ export function isClaudeCodeInstalled(): boolean {
  * 读取 daemon token（如果存在）
  */
 function readDaemonToken(): string | null {
-  const tokenPath = join(homedir(), '.claude-forge', 'daemon.token');
+  const tokenPath = FORGE_PATHS.daemonToken();
   if (!existsSync(tokenPath)) return null;
   try {
     return readFileSync(tokenPath, 'utf-8').trim() || null;
@@ -83,7 +81,7 @@ export function getMcpServerUrl(): string {
  * 是否处于 daemon 运行中（通过 pid 文件存在性判断，松散探测）
  */
 function isDaemonRunning(): boolean {
-  return existsSync(join(homedir(), '.claude-forge', 'daemon.pid'));
+  return existsSync(FORGE_PATHS.daemonPid());
 }
 
 /**

package/src/cli/commands/menu.ts

@@ -2,6 +2,7 @@ import readline from 'readline';
 import { spawn } from 'child_process';
 import { createRequire } from 'module';
 import type { Command } from 'commander';
+import { DEFAULTS } from '../../core/constants.js';
 
 const require = createRequire(import.meta.url);
 const { version } = require('../../../package.json') as { version: string };
@@ -124,9 +125,9 @@ function runCommand(cmd: string, args: string[]): Promise<void> {
 
 function openDashboard(): void {
   console.log('\x1b[32m正在打开 Web Dashboard...\x1b[0m');
-  console.log('访问: \x1b[36mhttp://localhost:3721\x1b[0m\n');
+  console.log(`访问: \x1b[36mhttp://localhost:${DEFAULTS.WEB_PORT}\x1b[0m\n`);
   const open = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-  spawn(open, ['http://localhost:3721'], { detached: true, stdio: 'ignore' }).unref();
+  spawn(open, [`http://localhost:${DEFAULTS.WEB_PORT}`], { detached: true, stdio: 'ignore' }).unref();
 }
 
 function prompt(question: string): Promise<string> {
@@ -241,7 +242,7 @@ async function selectModel(): Promise<void> {
   try {
     console.log('\n\x1b[36m正在获取模型列表...\x1b[0m');
 
-    const response = await fetch('http://localhost:3721/api/ai/models');
+    const response = await fetch(`http://localhost:${DEFAULTS.WEB_PORT}/api/ai/models`);
     if (!response.ok) {
       const text = await response.text();
       console.log(`\x1b[31m获取模型列表失败: ${text}\x1b[0m`);