优化清单 · 方案 · 优先级 · 严格区分【已实现/具备基础/建议补齐】
📑 返回索引：项目文档索引
优化总览表
| 序号 | 优化方向 | 当前状态 | 证据强度 | 文档价值 | 系统适配方向 | 推荐优先级 |
|---|---|---|---|---|---|---|
| 1 | Session 运行态持久化 | 具备基础条件 | 高（源码 TODO 明确） | 高 | 可靠性优先 | S |
| 2 | Provider 重试与重复工具调用上界 | 具备基础条件 | 高（源码 TODO 明确） | 高 | 稳定性 | S |
| 3 | Session Drain 集群化（多节点 ownership） | 建议补齐 | 高（源码 TODO 明确） | 高 | 平台化 | A |
| 4 | 事件流断线自动重连 | 具备基础条件 | 中（设计决策明确拒绝自动重连） | 中 | 可用性 | A |
| 5 | Cache Policy 协议覆盖扩展 | 具备基础条件 | 中 | 中 | 成本优化 | A |
| 6 | Managed Tool Output 保留策略治理 | 已实现 | 高（truncate.ts） | 中 | 工程治理 | B |
| 7 | 旧版 SDK 迁移收尾 | 具备基础条件 | 高（sdk-next 注释） | 中 | 工程治理 | A |
| 8 | 会话列表大页查询与索引优化 | 建议补齐 | 低（未发现专项优化） | 中 | 性能优化 | B |
| 9 | Provider 兼容性测试扩展 | 具备基础条件 | 中（仅部分协议有测试） | 高 | 生态中立 | S |
| 10 | 嵌入式 Host 多实例支持 | 建议补齐 | 中（CONTEXT.md 开放问题） | 中 | 平台化 | B |
单条优化文档
优化点 1：Session 运行态持久化
- 优化分类：稳定性优化 ｜ 当前状态：【具备基础条件】 ｜ 优先级：S
- 原始问题：进程崩溃后无法区分”中断的 drain”与”正常空闲”，恢复时只能依赖 admitted/promoted seq 推断，busy/retrying/interrupted 等运行态丢失。
- 现有源码情况：
packages/core/src/session/runner/llm.ts注释明确列出未落地项：”Mark busy, retrying, idle, interrupted, or terminal-failure status durably”；SessionExecution的 drain 无持久身份。 - 完整优化方案：为 Session 增加 durable 运行态字段（status + 上次活动 seq），在 Drain 生命周期关键点（启动/完成/中断/失败）原子更新；恢复流程读取运行态决定续接或空闲。
- 方案取舍：以每次状态写入代价换取崩溃恢复准确性；可用”状态变更事件 + 投影”方式减少直写。
- 文档标准描述：可表述为”建议将运行态纳入持久化，以支撑更精确的崩溃恢复语义”。不可声称”已支持多节点故障转移”。
- 局限与风险：需同步演进 SessionExecution 接口与投影逻辑，改动面较大。
优化点 2：Provider 重试与重复工具调用上界
- 优化分类：稳定性优化 ｜ 当前状态：【具备基础条件】 ｜ 优先级：S
- 原始问题：同一 Provider 轮次无限重试、重复相同工具调用可能造成失控循环（费用/时间爆炸）。
- 现有源码情况：
packages/core/src/session/runner/llm.tsTODO：”Bound provider retries and repeated identical tool calls”；SessionRetry.policy（opencode 包）已有基础策略。 - 完整优化方案：为 Provider 调用引入指数退避 + 最大重试次数（可配置）；为相同工具签名调用引入会话级去重计数与上限，超限提示用户或切换策略。
- 方案取舍：重试上限过低影响弱网可用性，过高放大故障；需按 Provider 与工具类型差异化配置。
- 局限与风险：识别”等价工具调用”本身有成本（参数比较），需权衡。
优化点 3：Session Drain 集群化（多节点 ownership）
- 优化分类：平台化 ｜ 当前状态：【建议补齐】 ｜ 优先级：A
- 原始问题：Drain 为进程本地协调，多节点部署无法接管彼此 Session，无法支撑分布式场景。
- 现有源码情况：
packages/core/src/session/runner/llm.tsTODO：”Replace local ownership with durable multi-node ownership when clustered”；SessionRunCoordinator明确”process-local”。 - 完整优化方案：引入 durable lease/ownership 表 + 心跳续约；Drain 前获取 ownership，失败者见 lease 过期接管；事件系统天然支撑（durable event + replay）。
- 方案取舍：以基础设施复杂度换取横向扩展能力；当前单机产品形态下价值有限。
- 文档标准描述：标注为【可扩展设计】，不可作为已实现能力写入。
优化点 4：事件流断线自动重连
- 优化分类：可用性优化 ｜ 当前状态：【具备基础条件】 ｜ 优先级：A
- 原始问题：
events.subscribe()断线显式失败，不自动重连；sessions.events()亦要求调用方自己组合续接。 - 现有源码情况：CONTEXT.md 明确”does not automatically reconnect after transport loss”；sessions.events 支持 after 续接（保留 last durable sequence 即可）。
- 完整优化方案：在 UI 层（tui/app/desktop）封装”可恢复订阅”组件：记录 last seq → 断线 → 刷新权威状态 → 以 after 重新订阅。
- 方案取舍：协议层保持无状态（显式失败），由消费方组合重连策略——这是当前设计的刻意取舍，优化点应在消费侧。
优化点 5：Cache Policy 协议覆盖扩展
- 优化分类：成本优化 ｜ 当前状态：【具备基础条件】 ｜ 优先级：A
- 原始问题：缓存策略仅对声明 RESPECTS_INLINE_HINTS 的协议生效（anthropic-messages、bedrock-converse），其余协议缓存提示被忽略。
- 现有源码情况：
packages/llm/src/cache-policy.ts：applyCachePolicy 编译期注入 CacheHint，默认 auto=tools+system+最新 user message。 - 完整优化方案：对 openai-chat 等协议通过 provider 侧显式 cache_control 字段或系统提示标记尝试；建立各协议缓存兼容性矩阵。
- 方案取舍：部分协议不支持显式提示词缓存标记，硬编码注入可能改变行为；需逐协议验证。
优化点 6：Managed Tool Output 保留策略治理
- 优化分类：工程治理 ｜ 当前状态：【已实现】 ｜ 优先级：B
- 原始问题：截断文件落盘有 7 天保留 + 每小时清理，但清理失败时无可见告警。
- 现有源码情况：
packages/opencode/src/tool/truncate.ts：MAX_LINES=2000、MAX_BYTES=50KB，config.tool_output 可覆盖。 - 完整优化方案：清理任务失败时发布可观测事件；提供手动清理命令；截断文件路径可配置目录（当前为共享平铺目录）。
优化点 7：旧版 SDK 迁移收尾
- 优化分类：工程治理 ｜ 当前状态：【具备基础条件】 ｜ 优先级：A
- 原始问题：
@opencode-ai/sdk-next待接管@opencode-ai/sdk名称，旧消费者（packages/sdk/js 生成的 openapi client）尚未迁移。 - 现有源码情况：
packages/sdk-next注释明确”sdk-next will assume the existing sdk name after legacy consumers migrate”；sdk/js 含 v2/ 子目录。 - 完整优化方案：以 v2 子目录先内测 → 生态迁移 → 包名接管 → 删除旧生成物；保持 Page 投影等稳定 API 先行落地。
优化点 8：会话列表大页查询与索引优化
- 优化分类：性能优化 ｜ 当前状态：【建议补齐】 ｜ 优先级：B
- 原始问题：会话与事件表随使用增长，当前索引策略未见专项优化（未发现相关索引设计文档）。
- 现有源码情况：
session/sql.ts、event/sql.ts；迁移引擎支持增量演进。 - 完整优化方案：为 session_input.promoted_seq、event.aggregate_id+seq 等高频查询路径补充索引；大库启用分页基准测试。
- 证据强度说明：此条目基于查询模式推断，未发现明确性能瓶颈证据，标注为【可扩展设计】。
优化点 9：Provider 兼容性测试扩展
- 优化分类：工程治理 ｜ 当前状态：【具备基础条件】 ｜ 优先级：S
- 原始问题：8 个协议适配器仅 anthropic-messages、bedrock-converse 有明确测试支撑，其余协议兼容性证据不足。
- 现有源码情况：
packages/llm/src/protocols/；CONTEXT.md 提到”recorded provider tests establish compatibility”作为 Native Continuation 拓宽的前置条件。 - 完整优化方案：用 http-recorder 为各协议录制真实流量 cassettes 作为回归基线；建立协议兼容性矩阵文档。
- 文档标准描述：当前不可声称”全协议兼容”，应以测试覆盖范围为准。
优化点 10：嵌入式 Host 多实例支持
- 优化分类：平台化 ｜ 当前状态：【建议补齐】 ｜ 优先级：B
- 原始问题：CONTEXT.md 开放问题：”Should a future operation expose the complete provider request context”；多宿主共享单数据库时执行协调未定义。
- 现有源码情况：CONTEXT.md：”Define embedded-host placement before supporting multiple hosts over one database”。
- 完整优化方案：先定义 Host 放置语义（每个 Host 独立存储 or 共享存储 + 协调协议），再开放多实例。
由 opencode-project-analyzer skill 生成