|
| 1 | +# 讨论：完全移除 Supervisor 功能 |
| 2 | + |
| 3 | +> 日期：2026-05-19 |
| 4 | +> 状态：讨论中 |
| 5 | +
|
| 6 | +## 背景 |
| 7 | + |
| 8 | +用户认为 supervisor 功能已完全被 Claude Code 自身的 goal 和 loop 功能取代，不再需要 ccc 项目中的 supervisor 功能。需要全面清理。 |
| 9 | + |
| 10 | +## 需求理解 |
| 11 | + |
| 12 | +**目标**：完全移除 supervisor 相关的所有代码、配置、测试、文档和依赖。 |
| 13 | + |
| 14 | +**保留**：Provider 切换功能（这是 ccc 的另一核心价值，独立于 supervisor）。 |
| 15 | + |
| 16 | +## 探索发现 |
| 17 | + |
| 18 | +### 项目双核心功能 |
| 19 | + |
| 20 | +ccc 有两个核心功能： |
| 21 | +1. **Supervisor Mode** -- Agent 停止时自动审查工作质量（要移除） |
| 22 | +2. **Provider Switching** -- 多 API 供应商之间切换（保留） |
| 23 | + |
| 24 | +### Supervisor 功能涉及的范围 |
| 25 | + |
| 26 | +#### 1. 需要整个删除的包/目录 |
| 27 | + |
| 28 | +| 路径 | 原因 | |
| 29 | +|------|------| |
| 30 | +| `internal/supervisor/` (state.go, logger.go, output.go + 测试) | supervisor 核心运行时 | |
| 31 | +| `internal/llmparser/` (parser.go + 测试) | 仅 supervisor hook 使用的容错 JSON 解析 | |
| 32 | +| `cmd/test-sdk/` | SDK 诊断工具 | |
| 33 | +| `cmd/test-sdk-auto-compact/` | SDK compact 测试 | |
| 34 | +| `cmd/test-sdk-structured/` | SDK structured output 测试 | |
| 35 | + |
| 36 | +#### 2. 需要删除的单个文件 |
| 37 | + |
| 38 | +| 路径 | 原因 | |
| 39 | +|------|------| |
| 40 | +| `internal/cli/hook.go` | supervisor hook 核心逻辑 | |
| 41 | +| `internal/cli/supervisor_prompt_default.md` | 嵌入的默认审查 prompt | |
| 42 | +| `internal/cli/supervisor_mode_test.go` | supervisor mode 测试 | |
| 43 | +| `internal/cli/hook_test.go` | hook 测试 | |
| 44 | +| `internal/config/supervisor.go` | SupervisorConfig 定义 | |
| 45 | +| `internal/config/supervisor_test.go` | supervisor 配置测试 | |
| 46 | +| `internal/config/supervisor_integration_test.go` | supervisor 集成测试 | |
| 47 | + |
| 48 | +#### 3. 需要删除的文档 |
| 49 | + |
| 50 | +| 路径 | 原因 | |
| 51 | +|------|------| |
| 52 | +| `docs/supervisor-mode-improvement-proposal.md` | supervisor 改进方案 | |
| 53 | +| `docs/supervisor-planning-integration.md` | supervisor 规划集成 | |
| 54 | +| `docs/LLM_JSON_PARSER_IMPLEMENTATION_PLAN.md` | LLM 解析器实现计划 | |
| 55 | +| `docs/STRUCTURED_OUTPUTS_IMPLEMENTATION_PLAN.md` | 结构化输出实现计划 | |
| 56 | +| `docs/WORKING_STATE_PATTERN.md` | 工作状态模式 | |
| 57 | +| `docs/working-state-discuss.md` | 工作状态讨论 | |
| 58 | + |
| 59 | +#### 4. 需要修改的文件 |
| 60 | + |
| 61 | +| 路径 | 修改内容 | |
| 62 | +|------|----------| |
| 63 | +| `internal/cli/cli.go` | 移除 supervisor-hook、supervisor-mode 子命令；移除 --debug 标志（仅用于 supervisor 日志）；简化 help 文本 | |
| 64 | +| `internal/cli/exec.go` | 移除 supervisor ID 生成（UUID）、日志文件打开、supervisor 相关环境变量 | |
| 65 | +| `internal/config/config.go` | 移除 `EnsureStopHook()` 函数；从 Config 结构体移除 `Supervisor` 字段 | |
| 66 | +| `internal/provider/provider.go` | 移除 Stop Hook 注入、移除 slash command 文件创建（supervisor.md、supervisoroff.md） | |
| 67 | +| `go.mod` / `go.sum` | 移除 claude-agent-sdk-go、uuid、jsonrepair、gojsonschema 依赖 | |
| 68 | +| `README.md` / `README-CN.md` | 移除 supervisor 相关文档 | |
| 69 | +| `CHANGELOG.md` | 移除 supervisor 相关条目 | |
| 70 | +| `CLAUDE.md` | 更新项目描述 | |
| 71 | +| `check.sh` | 检查是否需要更新 | |
| 72 | +| `.github/workflows/*` | 检查是否需要更新 | |
| 73 | + |
| 74 | +#### 5. 可移除的 Go 依赖 |
| 75 | + |
| 76 | +| 依赖 | 原因 | |
| 77 | +|------|------| |
| 78 | +| `github.com/schlunsen/claude-agent-sdk-go` | 仅 supervisor hook 使用 SDK | |
| 79 | +| `github.com/google/uuid` | 仅生成 supervisor session ID | |
| 80 | +| `github.com/kaptinlin/jsonrepair` | 仅 llmparser 使用 | |
| 81 | +| `github.com/xeipuuv/gojsonschema` | 仅 llmparser 使用 | |
| 82 | +| `github.com/twpayne/go-expect` | PTY 交互测试（需确认是否有非 supervisor 用途） | |
| 83 | + |
| 84 | +#### 6. 需要更新的 CLI 命令 |
| 85 | + |
| 86 | +移除后的命令结构： |
| 87 | +``` |
| 88 | +ccc [--version] [-v] |
| 89 | +ccc [--help] [-h] |
| 90 | +ccc <provider> [claude_args...] # 切换 provider 并启动 claude |
| 91 | +ccc # 使用当前 provider 启动 claude |
| 92 | +ccc validate [--all] [provider] # 验证配置 |
| 93 | +ccc patch [--reset] # 替换/恢复 claude 命令 |
| 94 | +``` |
| 95 | + |
| 96 | +移除的命令： |
| 97 | +- `ccc supervisor-mode [on|off]` -- 已移除 |
| 98 | +- `ccc supervisor-hook [--session-id ID]` -- 已移除 |
| 99 | +- `ccc [--debug]` -- debug 标志仅用于显示 supervisor 日志路径 |
| 100 | + |
| 101 | +#### 7. 需要移除的环境变量 |
| 102 | + |
| 103 | +- `CCC_SUPERVISOR_ID` -- supervisor 会话 ID |
| 104 | +- `CCC_SUPERVISOR_HOOK` -- 防递归标记 |
| 105 | + |
| 106 | +#### 8. 需要移除的文件系统路径 |
| 107 | + |
| 108 | +- `~/.claude/ccc/supervisor-{id}.json` -- 状态文件 |
| 109 | +- `~/.claude/ccc/supervisor-{id}.log` -- 日志文件 |
| 110 | +- `~/.claude/commands/supervisor.md` -- slash command |
| 111 | +- `~/.claude/commands/supervisoroff.md` -- slash command |
| 112 | +- `~/.claude/SUPERVISOR.md` -- 自定义 prompt |
| 113 | + |
| 114 | +### 保留的功能（独立于 supervisor） |
| 115 | + |
| 116 | +1. **Provider 切换** -- 核心功能 |
| 117 | +2. **配置管理** -- ccc.json/settings.json 读写 |
| 118 | +3. **迁移** -- 旧格式迁移 |
| 119 | +4. **验证** -- Provider 配置验证 |
| 120 | +5. **Pretty JSON** -- JSON 美化 |
| 121 | +6. **Patch** -- claude 命令替换 |
| 122 | + |
| 123 | +### 模块依赖变化 |
| 124 | + |
| 125 | +移除后的依赖图： |
| 126 | +``` |
| 127 | +main.go |
| 128 | + └── cli |
| 129 | + ├── config (配置加载/保存) |
| 130 | + ├── migration (从旧格式迁移) |
| 131 | + ├── provider (provider 切换) |
| 132 | + │ └── config (provider 依赖 config) |
| 133 | + ├── validate (配置验证) |
| 134 | + └── prettyjson (美化 JSON) |
| 135 | +``` |
| 136 | + |
| 137 | +## 讨论与决策 |
| 138 | + |
| 139 | +### Q1: settings.json 中残留的 Stop Hook 配置如何处理？ |
| 140 | +**决策**：将 `EnsureStopHook` 改为清理逻辑，在 SwitchWithHook 中主动清除 settings.json 中的 ccc Stop Hook 配置。 |
| 141 | + |
| 142 | +具体实现： |
| 143 | +- `EnsureStopHook` 改名为 `RemoveStopHook`，功能从"注入 hook"变为"移除 hook" |
| 144 | +- 清理 settings.json 中 `hooks.Stop` 里 command 包含 `ccc supervisor-hook` 的条目 |
| 145 | +- 如果清理后 hooks 为空 map，移除整个 hooks 字段 |
| 146 | +- 清理 `disableAllHooks` 和 `allowManagedHooksOnly` 字段（这两个是 supervisor 专用） |
| 147 | + |
| 148 | +### Q2: slash command 文件（supervisor.md、supervisoroff.md）是否清理？ |
| 149 | +**决策**：清理。在 SwitchWithHook 中主动删除 `~/.claude/commands/supervisor.md` 和 `~/.claude/commands/supervisoroff.md`。 |
| 150 | + |
| 151 | +### Q3: cmd/ 目录下的 SDK 测试工具是否全部删除？ |
| 152 | +**决策**：全部删除。它们都是为 supervisor SDK 功能服务的。 |
| 153 | + |
| 154 | +### Q4: --debug 标志如何处理？ |
| 155 | +**决策**：移除。之前只通过环境变量控制 debug，不需要 CLI 参数。移除 Command.Debug 字段、Parse() 中的 --debug 扫描逻辑、exec.go 中的相关判断。 |
| 156 | + |
| 157 | +### Q5: docs/ 下的 supervisor 相关文档如何处理？ |
| 158 | +**决策**：封存不动，保留在仓库中作为历史记录。 |
| 159 | + |
| 160 | +### Q6: ccc.json 中的 supervisor 配置字段如何处理？ |
| 161 | +**决策**：从 Config 结构体中移除 Supervisor 字段。Go JSON 解析自动忽略多余字段，旧的 ccc.json 中的 supervisor 配置不影响。Save 时也不会再写入。 |
| 162 | + |
| 163 | +## 最终方案 |
| 164 | + |
| 165 | +### 删除文件清单（共 ~20 个） |
| 166 | + |
| 167 | +**整个删除的目录：** |
| 168 | +- `internal/supervisor/` -- 6 个文件（state.go, logger.go, output.go + 3 个测试） |
| 169 | +- `internal/llmparser/` -- 2 个文件（parser.go + parser_test.go） |
| 170 | +- `cmd/test-sdk/` -- 1 个文件 |
| 171 | +- `cmd/test-sdk-auto-compact/` -- 2 个文件 |
| 172 | +- `cmd/test-sdk-structured/` -- 1 个文件 |
| 173 | + |
| 174 | +**删除的单个文件：** |
| 175 | +- `internal/cli/hook.go` -- supervisor hook 逻辑 |
| 176 | +- `internal/cli/supervisor_prompt_default.md` -- 嵌入 prompt |
| 177 | +- `internal/cli/supervisor_mode_test.go` -- mode 测试 |
| 178 | +- `internal/cli/hook_test.go` -- hook 测试 |
| 179 | +- `internal/config/supervisor.go` -- SupervisorConfig |
| 180 | +- `internal/config/supervisor_test.go` -- 配置测试 |
| 181 | +- `internal/config/supervisor_integration_test.go` -- 集成测试 |
| 182 | + |
| 183 | +### 修改文件清单（共 ~8 个） |
| 184 | + |
| 185 | +**`internal/cli/cli.go`：** |
| 186 | +- 移除 `supervisor` 包导入 |
| 187 | +- 移除 Command 结构体中的 Debug、SupervisorHook、SupervisorHookOpts、SupervisorMode、SupervisorModeOpts 字段 |
| 188 | +- 移除 SupervisorHookCommand、SupervisorModeCommand 类型定义 |
| 189 | +- 移除 parseSupervisorHookArgs、parseSupervisorModeArgs 函数 |
| 190 | +- 移除 RunSupervisorMode 函数 |
| 191 | +- 移除 Parse() 中的 --debug 扫描、supervisor-hook 和 supervisor-mode 分支 |
| 192 | +- 移除 Run() 中的 supervisor-mode 和 supervisor-hook 分发 |
| 193 | +- 更新 ShowHelp() 移除 Supervisor Mode 部分 |
| 194 | +- 更新项目描述文案 |
| 195 | + |
| 196 | +**`internal/cli/exec.go`：** |
| 197 | +- 移除 `uuid`、`time` 和 `supervisor` 包导入 |
| 198 | +- 移除 supervisorID 生成逻辑（UUID + CCC_SUPERVISOR_ID 环境变量） |
| 199 | +- 移除日志文件打开和写入逻辑 |
| 200 | +- 移除所有 cmd.Debug 相关逻辑 |
| 201 | +- 保留 checkSettingsEnvConflict（这是 provider 功能） |
| 202 | +- 保留 determineProvider（这是 provider 功能） |
| 203 | + |
| 204 | +**`internal/config/config.go`：** |
| 205 | +- 移除 `stopHookTimeout` 常量 |
| 206 | +- 从 Config 结构体移除 `Supervisor *SupervisorConfig` 字段 |
| 207 | +- 将 `EnsureStopHook()` 改为 `RemoveStopHook()`：清除 settings 中的 ccc Stop hook |
| 208 | + - 移除 hooks.Stop 中 command 包含 `ccc supervisor-hook` 的条目 |
| 209 | + - 如果 hooks.Stop 为空则删除 Stop 字段 |
| 210 | + - 如果整个 hooks 为空则删除 hooks 字段 |
| 211 | + - 删除 `disableAllHooks` 和 `allowManagedHooksOnly` 字段 |
| 212 | + |
| 213 | +**`internal/provider/provider.go`：** |
| 214 | +- 移除 `EnsureStopHook` 调用，改为调用 `RemoveStopHook` |
| 215 | +- 移除 `createSupervisorCommandFiles` 函数 |
| 216 | +- 改为调用清理 slash command 文件的逻辑：删除 `~/.claude/commands/supervisor.md` 和 `supervisoroff.md` |
| 217 | +- 更新 SwitchWithHook 函数注释 |
| 218 | + |
| 219 | +**`go.mod`：** |
| 220 | +- 移除 `github.com/schlunsen/claude-agent-sdk-go` 直接依赖和 replace 指令 |
| 221 | +- 移除 `github.com/google/uuid` 直接依赖 |
| 222 | +- 移除 `github.com/kaptinlin/jsonrepair` 直接依赖 |
| 223 | +- 移除 `github.com/xeipuuv/gojsonschema` 直接依赖 |
| 224 | +- 移除 `github.com/twpayne/go-expect` 直接依赖（用于 PTY 交互测试） |
| 225 | +- 运行 `go mod tidy` 清理间接依赖 |
| 226 | + |
| 227 | +**`README.md` / `README-CN.md`：** |
| 228 | +- 移除 supervisor 相关的所有描述 |
| 229 | +- 更新项目定位为 "Claude Code Configuration Switcher" |
| 230 | +- 更新功能列表、使用说明、配置说明 |
| 231 | + |
| 232 | +**`CHANGELOG.md`：** |
| 233 | +- 添加移除 supervisor 功能的 changelog 条目 |
| 234 | + |
| 235 | +**`CLAUDE.md`：** |
| 236 | +- 更新项目描述 |
| 237 | + |
| 238 | +### 移除后的命令结构 |
| 239 | + |
| 240 | +``` |
| 241 | +ccc [--version] [-v] |
| 242 | +ccc [--help] [-h] |
| 243 | +ccc <provider> [claude_args...] # 切换 provider 并启动 claude |
| 244 | +ccc # 使用当前 provider 启动 claude |
| 245 | +ccc validate [--all] [provider] # 验证配置 |
| 246 | +ccc patch [--reset] # 替换/恢复 claude 命令 |
| 247 | +``` |
| 248 | + |
| 249 | +### 移除后的依赖图 |
| 250 | + |
| 251 | +``` |
| 252 | +main.go |
| 253 | + └── cli |
| 254 | + ├── config (配置加载/保存) |
| 255 | + ├── migration (从旧格式迁移) |
| 256 | + ├── provider (provider 切换) |
| 257 | + │ └── config |
| 258 | + ├── validate (配置验证) |
| 259 | + └── prettyjson (美化 JSON) |
| 260 | +``` |
| 261 | + |
| 262 | +### 移除后的 go.mod 直接依赖 |
| 263 | + |
| 264 | +仅保留： |
| 265 | +- `github.com/stretchr/testify` -- 测试框架 |
0 commit comments