claude-code/docs/features/stub-recovery-priority.md

# 剩余 Stub 恢复优先级（按当前源码）

> 更新日期: 2026-04-15
> 结论口径: 以当前 `src/` + `packages/` 源码为准，不以历史设计文档为准。
> 目标: 将剩余 stub 按 `恢复收益 / 实现复杂度 / 是否挡主流程` 归类，给出实际可执行的恢复顺序。

## 一、判定口径

本文中的“主流程”特指外部版默认用户最容易直接碰到的执行链路：

1. `src/entrypoints/cli.tsx` 快速入口
2. `src/main.tsx` 命令注册与主 action
3. `src/screens/REPL.tsx` 与 `src/query.ts` 的常规对话循环
4. 默认或显式可见的工具与命令

以下内容不视为主流程阻塞：

- `process.env.USER_TYPE === 'ant'` 的内部路径
- 纯遥测 / 内部监控
- feature flag 关闭时根本不会暴露给普通用户的能力
- 已被显式隐藏的占位命令

## 二、先说结论

建议恢复顺序：

1. `SSH`
2. `Bash Classifier`
3. `WebBrowserTool`

并行的收口 / 验证项：

4. `WorkflowTool` 设计口径澄清
5. `DiscoverSkillsTool`
6. `Cached Microcompact`

原因：`WebBrowserTool` 仍然属于真正部分完成的能力面；`WorkflowTool` 按当前代码模型更像 prompt expansion surface，不应继续误判为“缺少执行引擎”；`DiscoverSkillsTool` 与 `Cached Microcompact` 已从“待恢复”转为“基本完成，需收口验证”。

## 三、优先级总表

| 优先级 | 模块 | 主要文件 | 恢复收益 | 实现复杂度 | 挡主流程 | 结论 |
|------|------|------|------|------|------|------|
| P0 | SSH 远程会话 | `src/ssh/createSSHSession.ts` | 高 | 中高 | 是 | 最优先 |
| P1 | Bash 语义分类器 | `src/utils/permissions/bashClassifier.ts` | 高 | 中 | 否 | 高 ROI |
| P2 | Workflow prompt surface | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | 中 | 低 | 否 | 基本完成，需澄清设计边界 |
| P2 | 显式技能搜索工具 | `packages/builtin-tools/src/tools/DiscoverSkillsTool/DiscoverSkillsTool.ts` | 中 | 低 | 否 | 基本完成，转入收口与测试 |
| P1 | 内嵌浏览器工具 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | 中 | 中高 | 否 | 部分完成，需补 runtime 或收口成 browser-lite |
| P2 | Cached microcompact | `src/services/compact/cachedMicrocompact.ts` | 高 | 中 | 否 | 基本完成，转入硬化与验证 |
| P2 | Agent snapshot 更新对话框 | `src/components/agents/SnapshotUpdateDialog.ts` | 中 | 低中 | 否 | 补齐一个已连通但无 UI 的链路 |
| P3 | 反馈受挫检测 | `src/components/FeedbackSurvey/useFrustrationDetection.ts` | 低中 | 低 | 否 | UX 补丁 |
| P3 | 平台辅助原生模块 | `packages/modifiers-napi/src/index.ts`, `packages/url-handler-napi/src/index.ts` | 低中 | 低中 | 否 | 平台能力补强 |
| P3 | `/reset-limits` | `src/commands/reset-limits/index.ts` | 低 | 低 | 否 | 仅补齐显式提示链路 |
| P4 | internal runner / telemetry | `src/environment-runner/main.ts`, `src/self-hosted-runner/main.ts`, `src/utils/sessionDataUploader.ts`, `src/utils/sdkHeapDumpMonitor.ts`, `src/hooks/notifs/useAntOrgWarningNotification.ts` | 低 | 中到高 | 否 | 长期后置 |

## 四、P0 - P2 详细说明

### P0: SSH 远程会话

**文件**

- `src/ssh/createSSHSession.ts`

**现状**

- `src/main.tsx` 已明确暴露 `claude ssh <host> [dir]`。
- `main.tsx` 在 `3775` 行附近直接动态导入 `createSSHSession()` / `createLocalSSHSession()`。
- 当前实现直接抛 `SSHSessionError('SSH sessions are not supported in this build')`。

**为什么排第一**

- 这是一个已经暴露给用户、但运行时被 stub 卡死的显式入口。
- 不是“未来功能”，而是“入口存在、帮助里可见、实际不能用”。
- 修复后能立刻把一个主命令从假可用变成真可用。

**复杂度来源**

- 需要处理 SSH 建链、错误回传、远端 cwd、auth proxy、stderr tail。
- 已有 `SSHSessionManager` 接口，说明调用方契约基本稳定，难点主要在 runtime 实现而不是接口设计。

**建议拆解**

1. 先恢复 `createLocalSSHSession()`，打通本地伪 SSH 流程。
2. 再补真实 SSH session 创建。
3. 最后补重连、端口转发和更好的错误分类。

### P1: Bash 语义分类器

**文件**

- `src/utils/permissions/bashClassifier.ts`

**现状**

- 权限 UI、`bashPermissions.ts`、`classifierDecision.ts` 都已接入。
- 当前实现明确写着 `Stub for external builds - classifier permissions feature is ANT-ONLY`。
- `isClassifierPermissionsEnabled()` 恒为 `false`，`classifyBashCommand()` 恒返回 disabled。

**为什么优先级高**

- 不挡主流程，但直接影响 Bash 工具体验和自动审批能力。
- 修复收益覆盖面广，因为 BashTool 是高频主工具。
- 不需要先重做整个权限框架，只需把分类后端从 no-op 变成可用实现。

**复杂度来源**

- 需要决定是本地规则引擎、轻量 AST、还是保守的模式匹配策略。
- 但外围编排基本都在，属于“后端一补，整条链路就活”。

**建议目标**

- 第一阶段先做保守匹配，支持 deny / ask / allow 的最小闭环。
- 不要一开始追求 Anthropic 内部同等能力。

### P2: Workflow prompt surface

**文件**

- `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts`

**现状**

- `WorkflowTool`、`createWorkflowCommand.ts`、`constants.ts`、`WorkflowPermissionRequest.tsx`、`src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` 已存在。
- `getWorkflowCommands()` 生成的是 `type: 'prompt'` 的命令，`kind: 'workflow'`。
- `WorkflowTool.call()` 会读取 workflow 内容并把它返回给模型。
- 这条链路和 `/commit`、skills、prompt command 的执行模式一致：命令/工具提供 prompt，模型再去调用普通工具执行。

**为什么不再列为主恢复项**

- 当前更准确的判断是：它按现有设计已经基本可用。
- 缺的不是“执行引擎”，而是文档口径和能力边界说明。
- `LocalWorkflowTask` / `WorkflowDetailDialog` 这类结构更像未来高级 background workflow 轨道，不是当前 WorkflowTool 主路径的必需部分。

**建议动作**

1. 把文档统一改成“workflow = prompt-backed command”
2. 统一 `/workflow-name` 与 `WorkflowTool.call()` 的输出语义
3. 再决定是否要把 background workflow 作为未来升级功能单独推进

### P1: DiscoverSkillsTool

**文件**

- `packages/builtin-tools/src/tools/DiscoverSkillsTool/prompt.ts`
- `packages/builtin-tools/src/tools/DiscoverSkillsTool/DiscoverSkillsTool.ts`

**现状**

- `src/constants/prompts.ts` 已经尝试读取 `DISCOVER_SKILLS_TOOL_NAME`。
- 本地 skill index、prefetch、remote loader、remote state 都已有实现。
- `DISCOVER_SKILLS_TOOL_NAME` 已补上，`DiscoverSkillsTool.call()` 已能调用本地 TF-IDF 搜索。

**为什么排 P1**

- 这项已经不再是主恢复缺口。
- 当前更准确的状态是“基本完成”，剩余工作集中在测试、上下文使用和文档同步。

**建议拆解**

1. 补测试，覆盖显式搜索结果与空结果路径。
2. 修正 `call()` 中对上下文 `cwd` 的获取。
3. 同步文档口径，移出“待恢复主项”。

### P2: WebBrowserTool

**文件**

- `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts`
- `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts`

**现状**

- `src/tools.ts` 已在 `feature('WEB_BROWSER_TOOL')` 下注册工具。
- `src/screens/REPL.tsx` 已给面板留了位置。
- 当前 `navigate` / `screenshot` 已有 HTTP fetch-lite 实现，但 `click` / `type` / `scroll` 仍需 full runtime，Panel 仍是 `null`。

**为什么是 P2，不是 P1**

- 功能面存在，但默认外部用户并不会直接依赖它完成主流程。
- 但它已经不是纯 placeholder，更准确的状态是“部分完成，待补完”。
- 真正的复杂度仍在 full browser runtime / Bun WebView。

**建议拆解**

1. 先决定产品方向：收口成 browser-lite，还是继续补 full runtime。
2. 若走 browser-lite，收紧文案并补简单 Panel。
3. 若走 full runtime，再补 `click / type / scroll`。

### P2: Cached Microcompact

**文件**

- `src/services/compact/cachedMicrocompact.ts`
- `src/services/compact/cachedMCConfig.ts`

**现状**

- `microCompact.ts`、`query.ts`、`services/api/claude.ts` 都已经接了调用点。
- `constants/prompts.ts` 也已经预留配置读取。
- `cachedMicrocompact.ts` 与 `cachedMCConfig.ts` 现在已有真实实现，`microCompact.ts` 也已经走 `cachedMicrocompactPath()`。

**为什么不是更高优先级**

- 它已经不再是“待恢复”主项。
- 更准确的状态是“基本完成，但需要硬化验证”。
- 当前主要风险是边界行为、模型兼容性和测试覆盖，而不是主路径完全缺失。

**建议拆解**

1. 补集成测试，覆盖阈值、去重、pin、baseline/delta 逻辑。
2. 补更明确的 debug logging 与失败回退。
3. 从“恢复主项”移到“验证/硬化项”。

### P2: Snapshot 更新对话框

**文件**

- `src/components/agents/SnapshotUpdateDialog.ts`

**现状**

- `main.tsx`、`dialogLaunchers.tsx` 都会走到这里。
- 当前组件直接 `return null`，`buildMergePrompt()` 也返回空字符串。

**为什么是 P2**

- 这不是大 feature，但它属于“调用点真实存在、UI 仍为空”的典型残缺项。
- 实现成本低于前几个，适合穿插修复。

## 五、P3 - P4 详细说明

### P3: 反馈与平台辅助项

**包含**

- `src/components/FeedbackSurvey/useFrustrationDetection.ts`
- `packages/modifiers-napi/src/index.ts`
- `packages/url-handler-napi/src/index.ts`
- `src/commands/reset-limits/index.ts`

**判断**

- `useFrustrationDetection.ts` 已被 `REPL.tsx` 使用，但只是 survey UX，不挡核心功能。
- `modifiers-napi` 在 macOS 下有部分实现，其他平台退化为 false，可接受。
- `url-handler-napi` 会影响 deep link URL launch，但不是日常主流程。
- `/reset-limits` 已在文案中出现，但仍是隐藏 stub，修复价值有限。

### P4: internal runner / telemetry

**包含**

- `src/environment-runner/main.ts`
- `src/self-hosted-runner/main.ts`
- `src/utils/sessionDataUploader.ts`
- `src/utils/sdkHeapDumpMonitor.ts`
- `src/hooks/notifs/useAntOrgWarningNotification.ts`

**判断**

- 这些模块不是没有价值，而是对当前外部版几乎不构成主线能力缺口。
- 多数要么是 feature-gated，要么是 `ant-only`，要么明显偏内部监控与基础设施。

## 六、建议的实际恢复批次

### 批次 A: 先修“显式暴露但跑不通”的入口

1. `src/ssh/createSSHSession.ts`
2. `src/utils/permissions/bashClassifier.ts`

### 批次 B: 修“骨架已齐、核心仍空”的 feature shell

1. `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` 的设计口径澄清与文档统一

### 批次 C: 修“已注册但 runtime 缺失”的增强能力

1. `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts`
2. `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts`

### 批次 D: 做“基本完成项”的收口与验证

1. `packages/builtin-tools/src/tools/DiscoverSkillsTool/DiscoverSkillsTool.ts`
2. `src/services/compact/cachedMicrocompact.ts`

### 批次 E: 修“可见但不挡主线”的 UI / 平台补丁

1. `src/components/agents/SnapshotUpdateDialog.ts`
2. `src/components/FeedbackSurvey/useFrustrationDetection.ts`
3. `packages/url-handler-napi/src/index.ts`
4. `packages/modifiers-napi/src/index.ts`

## 七、当前不建议优先投入的方向

### 关于 `summary` 的状态说明

仓库里现在有两种不同含义的 `summary`，需要明确区分：

1. **后台会话 task summary**

   - 文件: `src/utils/taskSummary.ts`
   - 状态: **已从纯 stub 变成基础实现**
   - 当前能力: 仅在 `BG_SESSIONS` + bg session 下生效，按最近一次 assistant/tool_use 更新 `status` 与 `waitingFor`
   - 结论: 不能算“完整”，但也不应继续归类为纯 stub

2. **隐藏的 `/summary` 命令**

   - 文件: `src/commands/summary/index.js`
   - 状态: **仍为隐藏 stub**
   - 当前能力: `isEnabled: () => false`
   - 结论: 如果讨论“summary 命令是否完成”，答案是否定的

因此，后续讨论 `summary` 时应统一使用下面的表述：

- `task summary`: 基础版已完成
- `/summary` 命令: 仍未完成

### 隐藏命令 stub

当前至少还有一批明确导出为 `name: 'stub'` 的隐藏命令，包括：

- `teleport`
- `summary`
- `ctx_viz`
- `share`
- `bughunter`
- `backfill-sessions`
- `autofix-pr`
- `break-cache`
- `ant-trace`
- `issue`
- `env`
- `debug-tool-call`
- `perf-issue`
- `good-claude`
- `onboarding`
- `oauth-refresh`
- `mock-limits`
- `reset-limits`

这些命令的共同特点是：

- 不是“看起来能用、但运行时报错”，而是已经明确被隐藏和禁用。
- 从产品角度，它们比 SSH、Workflow、Bash Classifier 更靠后。

### 大规模 type stub 清理

当前扫描中带 `Auto-generated type stub` 标记的文件仍有数百个量级。

这类工作重要，但不适合和功能恢复搅在一起做。更合理的顺序是：

1. 先恢复高价值运行时 stub。
2. 再单独开一个类型恢复专项。

## 八、哪些旧文档结论已经过期

以下模块在历史文档中曾被写成 stub，但当前源码已经不是本轮恢复重点：

- `src/services/compact/reactiveCompact.ts`
- `src/proactive/index.ts`
- `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts`
- `src/utils/taskSummary.ts`（现为基础实现，不再是纯 stub）
- `src/utils/eventLoopStallDetector.ts`
- `src/utils/ccshareResume.ts`
- `src/services/contextCollapse/index.ts`

后续如果需要继续维护 stub 清单，应优先更新本文档，而不是继续沿用这些旧设计稿中的状态判断。

## 九、执行建议

如果目标是尽快提升外部版可用性，建议严格按下面顺序推进：

1. `SSH`
2. `bashClassifier`
3. `WebBrowserTool`
4. `WorkflowTool` 设计口径澄清
5. `DiscoverSkillsTool` 收口
6. `cachedMicrocompact` 硬化

如果明确**先不处理** `SSH` 和 `bashClassifier`，后续完整顺序改为：

1. `WebBrowserTool`
2. `WorkflowTool` 设计口径澄清
3. `DiscoverSkillsTool` 收口
4. `cachedMicrocompact` 硬化
5. `SnapshotUpdateDialog`
6. `useFrustrationDetection`
7. `url-handler-napi`
8. `modifiers-napi`
9. `/summary`
10. 其他隐藏命令 stub
11. type stub 专项清理

如果目标是“减少仓库里看起来像半成品的地方”，则应在上面这条主线完成后，再处理：

1. `SnapshotUpdateDialog`
2. `useFrustrationDetection`
3. `url-handler-napi`
4. `modifiers-napi`
5. 隐藏命令 stub
6. type stub 专项清理