docs: 接口文档

[pionxe]

文档在/docs/interfaces目录下。

• 主规范：runtime-interface-spec.md
  唯一事实源，包含 Gateway、Runtime、Context、Provider、Tools、Config、事件总线、错误语义、并发语义。
• 压缩专题：context-compact.md
  动态压缩、手动 compact、reactive compact、单次重试门禁、摘要协议。
• 迁移映射：interface-migration-map.md
  “旧协商名 -> 当前项目名 -> V2 定名”映射，标注 deprecated。
• 导航文档：README.md

[codecov]

Codecov Report

❌ Patch coverage is 78.70999% with 439 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/config/selection.go	42.10%	137 Missing and 28 partials ⚠️
internal/context/compact/summary_validator.go	78.01%	24 Missing and 18 partials ⚠️
internal/tui/update.go	75.92%	33 Missing and 6 partials ⚠️
internal/provider/openai/openai.go	74.50%	18 Missing and 8 partials ⚠️
internal/runtime/runtime.go	86.25%	15 Missing and 7 partials ⚠️
internal/provider/catalog/store.go	48.64%	12 Missing and 7 partials ⚠️
internal/context/compact/transcript_store.go	78.78%	7 Missing and 7 partials ⚠️
internal/provider/types.go	65.00%	7 Missing and 7 partials ⚠️
internal/context/source_rules.go	84.61%	6 Missing and 6 partials ⚠️
internal/tools/filesystem/result_filter.go	73.68%	5 Missing and 5 partials ⚠️
... and 18 more

📢 Thoughts on this report? Let us know!

[wynxing]

这批接口文档整体整理得很完整，尤其是把 Runtime / Context / Provider / Tools 的边界集中到 docs/interfaces 目录这件事本身是有价值的。不过我这边看下来，当前版本还有几个关键点把“未来目标态”写成了“当前事实”，这会直接影响 context/runtime 侧后续的接口判断，建议这一轮先收敛一下再合：

1. Gateway 目前还没有在仓库里形成稳定实现，但主规范和 README 导航把 TUI/CLI/Web -> Gateway -> Runtime 写成了当前固定入口模型，和现状不一致，也和迁移表里“Gateway 最后补”有冲突。
2. 审批流文档写成了 permission_request -> 用户确认/拒绝 -> permission_resolved，但当前 runtime 命中 ask 时会直接顺序发出这两个事件，并没有真实的人机确认闭环。这里如果不区分“现状”和“目标态”，客户端会被带偏。
3. proactive compact 现在还没有形成可落地的现有契约；当前 internal/context/compact 只有 manual/reactive，context.BuildInput 也还没有配套的预算字段和自动触发链路。对 context 模块来说，这一段很容易误导后续实现。
4. compact_start 在文档里被定义成结构化 payload，但当前 runtime 发的还是裸字符串；如果消费者按文档直接解码，会和现实现不兼容。

我的建议是：

• 把文档里的内容明确拆成“当前实现基线”和“V2 目标态 / proposed”。
• 对暂未落地的能力统一标注 proposed / future / not implemented yet，不要和 current baseline 混写。
• 对事件载荷、审批闭环、compact 触发模式这几个会直接影响联调的地方，优先以当前代码行为为准，或者显式写清楚这是待实现变更。

等这些语义收敛后，这套文档会更适合作为后续接口事实源。

[pionxe]

这批接口文档整体整理得很完整，尤其是把 Runtime / Context / Provider / Tools 的边界集中到 docs/interfaces 目录这件事本身是有价值的。不过我这边看下来，当前版本还有几个关键点把“未来目标态”写成了“当前事实”，这会直接影响 context/runtime 侧后续的接口判断，建议这一轮先收敛一下再合：

1. Gateway 目前还没有在仓库里形成稳定实现，但主规范和 README 导航把 TUI/CLI/Web -> Gateway -> Runtime 写成了当前固定入口模型，和现状不一致，也和迁移表里“Gateway 最后补”有冲突。
2. 审批流文档写成了 permission_request -> 用户确认/拒绝 -> permission_resolved，但当前 runtime 命中 ask 时会直接顺序发出这两个事件，并没有真实的人机确认闭环。这里如果不区分“现状”和“目标态”，客户端会被带偏。
3. proactive compact 现在还没有形成可落地的现有契约；当前 internal/context/compact 只有 manual/reactive，context.BuildInput 也还没有配套的预算字段和自动触发链路。对 context 模块来说，这一段很容易误导后续实现。
4. compact_start 在文档里被定义成结构化 payload，但当前 runtime 发的还是裸字符串；如果消费者按文档直接解码，会和现实现不兼容。

我的建议是：

• 把文档里的内容明确拆成“当前实现基线”和“V2 目标态 / proposed”。
• 对暂未落地的能力统一标注 proposed / future / not implemented yet，不要和 current baseline 混写。
• 对事件载荷、审批闭环、compact 触发模式这几个会直接影响联调的地方，优先以当前代码行为为准，或者显式写清楚这是待实现变更。

等这些语义收敛后，这套文档会更适合作为后续接口事实源。

现已对当前与未实现的进行了区分