打算给v2申请合并的特性

[SivanCola]

v2 子 PR 功能点说明

本文档整理当前 v2 子 PR 的功能点、价值、风险和合并注意事项，按建议优先级从高到低排列。

当前 v2 最新基线：a79f2a57

---

1. feat/schemas-sort：工具 Schema 稳定排序

将 Registry.Schemas() 的输出从注册顺序改为按工具名排序。

价值

这是高缓存系统的基础优化。工具 schema 是模型请求前缀的一部分，如果不同 session 中工具注册顺序不同，即使工具集合完全一致，也可能导致缓存前缀字节变化，从而降低 DeepSeek prefix cache 命中率。

风险

低。只是输出顺序稳定化，不改变工具语义。

合并状态

与当前 v2 无冲突。

建议

优先合并。

---

2. feat/bash-readonly：只读 Bash 命令跳过审批

识别常见只读命令，例如 ls、cat、grep、rg、git log、git status、git diff 等，在权限系统里自动按只读命令处理，减少不必要的审批弹窗。

价值

对交互体验提升明显。当前很多只读排查命令也会触发审批，容易打断模型连续工作。

风险

中低。核心风险在于白名单误判，把有副作用的命令当成只读。

注意事项

需要重点收紧白名单。比如 sed、tee、xargs 这类命令在某些参数下可能产生写入或副作用，建议不要直接全量视为只读。

合并状态

与当前 v2 无冲突。

---

3. feat/compact：结构化上下文压缩摘要

将压缩摘要改为固定五段结构：

• Goal
• Decisions
• Files
• Commands
• Pending

同时增加小区间跳过逻辑，避免在压缩收益很低时触发额外 summarization。

价值

对长任务很重要。结构化摘要比自由文本摘要更适合恢复任务状态，能减少压缩后模型丢失目标、文件上下文或下一步动作的问题。

风险

中。摘要 prompt 改动会影响长对话续航质量，需要观察摘要是否足够完整。

合并状态

与当前 v2 无冲突。

---

4. test/mock-provider：可复用 MockProvider

新增 agent 测试用的 MockProvider，支持脚本化模型响应、请求记录和错误注入。

价值

这是后续测试基础设施。缓存、压缩、工具调用、权限、goal 等功能都可以基于它做稳定单测，避免依赖真实模型或网络。

风险

低。纯测试代码，不影响生产路径。

合并状态

与当前 v2 无冲突。

---

5. feat/cache-diag：缓存前缀诊断

增加缓存前缀 hash、系统 prompt hash、工具 schema hash、rewrite version 等诊断信息，用于分析缓存 miss 的原因。

价值

对高缓存系统很有意义。它可以帮助判断缓存失效是因为 system prompt 变化、工具 schema 变化，还是日志被压缩/重写。

风险

中。需要和当前 v2 已有的 Usage / Session cache 统计结构对齐。

合并状态

与当前 v2 有冲突，主要在：

internal/event/event.go