feat: 整合功能恢复与技能学习闭环(含 ECC v2.1 parity + Opus 4.7 接入 + prompt 工程优化)

主要变更: - Skill Learning 闭环系统 (9/9 AC) - Opus 4.7 模型层接入 + adaptive thinking - Prompt 工程优化 (64 审计测试) - Agent Teams 简化门控 (默认启用) - Windows Terminal 后端修复 (EncodedCommand/WT_SESSION) - TF-IDF 技能搜索精准化 (字段加权/CJK 优化) - Autonomy 系统 (/autonomy 命令) - ACP 协议完整实现 - mock.module 泄漏修复 (CI 全绿) - 152+ lint/type 修复
2026-06-21 15:55:50 +00:00 · 2026-04-22 16:07:42 +08:00
parent 711927f01b
commit 95fece4b51
316 changed files with 39611 additions and 14298 deletions
--- a/docs/features/stub-recovery-priority.md
+++ b/docs/features/stub-recovery-priority.md
@@ -0,0 +1,398 @@
+# 剩余 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 专项清理