claude-code/docs/features/stub-recovery-design-1-4.md

Stub 恢复设计 1-4

日期：2026-04-12 目标：基于当前代码边界，为下一阶段 4 个 stub/半 stub 命令面给出可实施的设计方案。 排序原则：按建议实施顺序排序，不按问题严重性排序。

设计原则

• 先做能独立闭环、收益明确、改动边界清晰的项。
• 大项拆成 MVP 和 Phase 2+，避免一次性掉进大范围恢复。
• 优先复用已有状态、传输层、日志与配置能力，不重造协议。
• 设计以当前仓库实际代码为准，不以旧文档的理想状态为准。

1. claude daemon status / claude daemon stop

现状

• start 路径已有完整 supervisor + worker 生命周期： src/daemon/main.ts src/daemon/workerRegistry.ts
• status / stop 目前只是占位输出： src/daemon/main.ts
• /remote-control-server 有自己的命令内 UI 状态，但只维护当前进程内的 daemonProcess，并不适合作为跨进程 CLI 管理基础： src/commands/remoteControlServer/remoteControlServer.tsx

目标

• 让 claude daemon status 和 claude daemon stop 在另一个 CLI 进程中也能正确工作。
• 不依赖 TUI 内存态，不要求当前命令进程就是启动 daemon 的那个进程。

MVP 方案

• 新增 daemon 状态文件，例如： ~/.claude/daemon/remote-control.json
• start 时写入：
  • supervisor pid
  • cwd
  • startedAt
  • worker kinds
  • 最近状态
• status：
  • 读取状态文件
  • 用现有进程探测能力验证 pid 是否存活
  • 输出 running / stopped / stale
  • stale 时自动清理状态文件
• stop：
  • 读取 pid
  • 发送 SIGTERM
  • 等待退出
  • 超时后 SIGKILL
  • 清理状态文件

代码范围

• 新增 src/daemon/state.ts
• 修改 src/daemon/main.ts
• 轻量修改 src/commands/remoteControlServer/remoteControlServer.tsx，让 UI 尽量读取同一份状态文件

验证

1. claude daemon start
2. 新开终端执行 claude daemon status
3. 执行 claude daemon stop
4. 再次执行 claude daemon status，确认返回 stopped 或清晰的 stale cleaned

风险

• Windows 信号模型和 Unix 不同，stop 需要超时兜底。
• 当前设计默认单 supervisor，不处理多实例并发。

工作量判断

• 小
• 适合作为下一步的首选实现项

2. BG_SESSIONS

现状

• fast-path 已接好： src/entrypoints/cli.tsx
• session registry 已有真实实现： src/utils/concurrentSessions.ts
• exit 在 bg session 内已会 tmux detach-client： src/commands/exit/exit.tsx
• 但 CLI handler 仍全空： src/cli/bg.ts
• task summary 仍然是 stub： src/utils/taskSummary.ts

目标

• 先把 ps / logs / kill 做成真正有用的 session 管理命令。
• 不在第一阶段就强行补完 attach / --bg。

Phase 2A：MVP

• 实现 ps
  • 从 registry 读取 live sessions
  • 展示 pid、kind、sessionId、cwd、name、startedAt、bridgeSessionId
  • 如果有 activity/status，则一并展示
• 实现 logs
  • 支持按 sessionId / pid / name 查找
  • 优先复用本地 transcript/log 读取能力
  • 如果 registry 里存在 logPath，支持 tail 文件
• 实现 kill
  • 解析目标 session
  • 发退出信号
  • 清理 stale registry

Phase 2B：后续

• 实现 attach
• 实现 --bg
• 实现 taskSummary 的中途状态更新

为什么要拆

• 现有 registry 记录了 pid / sessionId / name / logPath
• 但没有可靠的 tmux attach target
• 所以 attach 和 --bg 不是简单补 handler，而是需要补启动/附着元数据设计

代码范围

• 修改 src/cli/bg.ts
• 修改 src/utils/concurrentSessions.ts 以便后续 attach/--bg 扩展
• 修改 src/utils/taskSummary.ts
• 复用： src/utils/sessionStorage.ts src/utils/udsClient.ts

验证

1. ps 能列出 live sessions
2. logs <sessionId|pid|name> 能输出对应日志
3. kill <sessionId|pid|name> 能结束目标 session

风险

• attach / --bg 第二阶段需要 tmux 元数据设计
• Windows 下 tmux 路径需要明确降级策略

工作量判断

• ps/logs/kill 中等
• attach/--bg 明显更大，应分阶段

3. TEMPLATES

现状

• 命令入口只有 fast-path： src/entrypoints/cli.tsx
• handler 是空的： src/cli/handlers/templateJobs.ts
• markdownConfigLoader 已把 templates 纳入配置目录： src/utils/markdownConfigLoader.ts
• query / stopHooks 已预留 job classifier 链路： src/query/stopHooks.ts
• jobs/classifier.ts 仍是 stub： src/jobs/classifier.ts

目标

• 把 new / list / reply 做成可用的模板任务系统。
• 第一阶段不碰复杂的自动分类与自动执行。

MVP 方案

• 模板来源： .claude/templates/*.md
• 模板格式： 复用现有 markdown + frontmatter 解析，不另外设计 DSL
• list
  • 列出所有模板
  • 显示模板名、description、路径
• new <template> [args...]
  • 解析模板
  • 在 ~/.claude/jobs/<job-id>/ 下创建 job 目录
  • 写入 template.md、input.txt、state.json
  • 返回 job id 与目录
• reply <job-id> <text>
  • 将回复写入 replies.jsonl 或 input.txt
  • 更新 state.json

Phase 2

• 恢复 src/jobs/classifier.ts
• 让带 CLAUDE_JOB_DIR 的 job session 在 turn 完成后自动更新 state.json
• 再决定是否补自动 job runner

为什么要拆

• 当前证据表明这是“template job commands”，不是单纯模板列表
• 但自动 job 运行链路没有足够现成实现，先做文件系统 job lifecycle 更稳

代码范围

• 修改 src/cli/handlers/templateJobs.ts
• 新增 src/jobs/state.ts
• 新增 src/jobs/templates.ts
• Phase 2 再改 src/jobs/classifier.ts

验证

1. list 能列出 .claude/templates
2. new 能创建 job 目录和状态文件
3. reply 能更新 job 内容和状态
4. Phase 2 再验证 classifier 写状态

风险

• frontmatter schema 需要先定义最小字段集
• 一旦扩展到“自动运行 job”，范围会明显膨胀

工作量判断

• MVP 中等
• 完整 job 系统偏大

4. assistant [sessionId]

现状

• attach 主流程其实已经存在： src/main.tsx
• 远端 viewer 所需基础模块已存在： src/remote/RemoteSessionManager.ts src/hooks/useAssistantHistory.ts src/assistant/sessionHistory.ts
• 真正 stub 的主要是： src/assistant/sessionDiscovery.ts src/assistant/AssistantSessionChooser.ts src/commands/assistant/assistant.ts src/assistant/index.ts

目标

• 不一次性恢复整个 KAIROS 助手系统。
• 先做“明确 sessionId 的 viewer attach 可用”，再逐步补 discovery / chooser / install。

Phase 4A：MVP

• 只支持 claude assistant <sessionId>
• 对 claude assistant 无参数模式，先返回明确提示：
  • 当前版本需要显式 sessionId
  • discovery 尚未启用
• 这样可以直接复用现有 attach 分支，不必先恢复 chooser/install wizard

Phase 4B

• 恢复 discoverAssistantSessions()
• 数据来源优先复用现有 sessions / bridge / teleport API，而不是新协议
• 让 claude assistant 无参数时能拿到候选 session 列表

Phase 4C

• 恢复 AssistantSessionChooser
• 多 session 时可交互选择

Phase 4D

• 最后考虑 install wizard 辅助函数
• 这部分属于“没有 session 时如何引导”，不是 attach 核心路径

为什么要拆

• attach 渲染层与远端消息通道大部分已经在
• 真正缺的是“如何发现目标 session”和“如何交互选择”
• 如果把 src/assistant/index.ts 的整套 KAIROS 正常模式也一起拉进来，范围会失控

代码范围

• Phase 4A：
  • src/main.tsx
  • src/commands/assistant/index.ts
• Phase 4B：
  • src/assistant/sessionDiscovery.ts
• Phase 4C：
  • src/assistant/AssistantSessionChooser.ts
• Phase 4D：
  • src/commands/assistant/assistant.ts

验证

1. claude assistant <sessionId> 能进入 remote viewer
2. 历史懒加载工作正常
3. 无参数模式先给出明确提示
4. 后续阶段再分别验证 discovery / chooser / install

风险

• 这是四项里范围最大的
• 一旦把 KAIROS 正常模式整体拉入，会从“viewer attach”膨胀成“完整 assistant mode 恢复”

工作量判断

• Phase 4A 中等
• 4A-4D 全做完很大

建议执行顺序

1. claude daemon status / claude daemon stop
2. BG_SESSIONS 先做 ps/logs/kill
3. TEMPLATES 先做 job 文件系统 MVP
4. assistant [sessionId] 先做显式 sessionId attach，再补 discovery/chooser/install

简短结论

这四项里，最适合立刻实现的是 daemon status/stop。BG_SESSIONS 和 TEMPLATES 适合按 MVP 先补 handler 与文件系统闭环。assistant [sessionId] 不能整块硬上，应该按“attach → discovery → chooser → install”拆开恢复。