[chore] 参考外部 issue #132 汇总本仓协议层与服务层值得继续演进的点 #264
Description
背景
参考外部仓库 issue：
基于同一类评估视角，检查本仓在当前主干快照下，是否仍存在值得继续推进的协议层 / 服务层进化点，并将值得做的点汇总成母单，便于后续拆分。
本次评估明确 不考虑低定价比 的事项，只保留对当前仓库后续演进有明确价值的方向。
当前仓库快照：
- HEAD snapshot:
aa021e02bb7ef03eade18122be132f9617fdebb1
评估参考实现与文档：
src/opencode_a2a_server/server/application.pysrc/opencode_a2a_server/server/agent_card.pysrc/opencode_a2a_server/jsonrpc/application.pysrc/opencode_a2a_server/contracts/extensions.pysrc/opencode_a2a_server/profile/runtime.pydocs/guide.md
相关现有 issue：
#166单租户实例内认证与授权模型#167多单租户实例的接入与编排模型#110终态 subscribe replay / cancel 幂等契约（已关闭，说明行为本身已落地）
当前判断
已经做得较好的部分
- 本仓已经形成较强的 contract honesty 表达：
docs/guide.md对 transport、auth、streaming、cancel、subscribe 行为有明确说明；contracts/extensions.py已显式区分 core A2A、shared extension、vendor-private extension；- Agent Card / OpenAPI / machine-readable compatibility profile 之间的一致性意识较强。
- 单租户、共享工作区的部署语义已经清晰外显，而不是隐藏假设：
profile/runtime.pyserver/agent_card.pydocs/guide.md
tasks/cancel幂等与 terminalsubscribereplay-once 已有明确实现与测试覆盖：server/application.pytests/server/test_cancel_contract.py
仍值得继续进化的点
1. task durability 仍偏弱，适合评估持久化 task store
当前 create_app() 里仍直接构造：
InMemoryTaskStore()
这意味着以下行为主要只在单进程生命周期内可靠：
tasks/gettasks/canceltasks/resubscribe
对当前单实例开发场景这并非 bug，但如果后续希望提升：
- 重启后的任务可见性
- 断连后的重订阅稳定性
- 跨进程 / 多副本的一致任务视图
则应评估引入可插拔持久化 task store 的最小方案，并明确迁移前后的 compatibility promise。
2. REST / JSON-RPC 协议入口仍存在较多手工拼装层，适合评估进一步收敛到 SDK 官方扩展点
当前仓库不是简单包一层 SDK app，而是自己维护了多块协议拼装逻辑：
OpencodeSessionQueryJSONRPCApplication(A2AFastAPIApplication)KeepaliveRESTAdapter- 自行追加
/v1/message:stream - 自行追加
/v1/tasks/{id}:subscribe create_app()中把 JSON-RPC app 与 REST routes 拼装到同一个 FastAPI app
这样做当前是可控的，也换来了较强的 contract 可见性；但它也意味着：
- 升级
a2a-sdk时的回归面更大； - route / stream / method 支持矩阵需要持续人工对齐；
- SDK 官方能力若演化，当前仓更容易积累自定义胶水层。
因此值得单独评估：
- 哪些自定义层是必要的产品差异；
- 哪些入口可以回收至 SDK 官方 app / adapter 扩展点。
3. terminal subscribe replay-once / cancel idempotency 已有文档化，但仍可继续补足 machine-readable service contract 表达
当前这两项行为已经：
- 在实现中落地；
- 在测试中固化；
- 在
docs/guide.md中明确说明。
但它们目前更多还是“文档 + 测试 + 代码注释级”契约，尚未像 core / extension taxonomy 那样，成为更明确的 machine-readable service-level contract 声明。
如果后续希望继续强化“外部消费者可自动推断”的能力，可以评估：
- 是否在 compatibility / wire contract 中补充 service behavior 段；
- 是否显式区分 core baseline 与 service-level semantic enhancement；
- 是否需要为 terminal replay-once 建立更稳定的声明字段，而不是只留在 guide 文本里。
这不是最高优先级，但属于值得做的收口项。
4. 若未来支持多入口 / 多 persona / 多公开面，需要 route-level card / auth / capability 模型
当前仓的真实模型仍然是：
- 全局 bearer token 认证
- 单 runtime profile
- 单 AgentCard 主体
- 单租户、共享工作区语义
这与当前产品定位一致，但如果未来出现以下目标：
- 多 reception persona
- 多公开入口
- 不同 route 暴露不同 contract / auth / capability
则现有模型会不够细。这个方向本仓已经有相关 open issue，可作为母单下的既有关联：
#166#167
因此这里不需要重复开散单，但需要在母单里明确：这是值得继续进化的方向，且应被视为 route/auth/card 模型演进，而不是简单配置项扩展。
5. 若进入持久化 task store 路径，需要提前定义 final-state protection 与 stale-connection resilience
一旦任务状态进入持久化与重订阅增强，本仓就不应只讨论“把 store 换成数据库”，还应提前定义：
- 哪些 terminal update 是 authoritative final state；
- 如何屏蔽迟到或非权威的终态覆盖；
- stale connection / upstream reconnect / store I/O 异常时的保护边界；
- 是否需要连接预检、I/O shield、最小健康探针与失败降级策略。
这类问题在当前 InMemoryTaskStore 模型下不突出，但在 durability 演进时会立即成为主问题，因此值得作为母单中的独立演进项记录。
建议后续拆分方向
- 评估可插拔持久化 task store 的最小引入方案，并明确对
tasks/get/tasks/cancel/tasks/resubscribe的影响边界。 - 评估哪些协议入口应继续保持自定义实现，哪些可以回收到 SDK 官方 app / adapter 扩展点。
- 为 cancel idempotency 与 terminal subscribe replay-once 补一层 machine-readable service contract 设计说明。
- 结合
#166与#167，抽象 route-level AgentCard / auth / capability 模型，而不是继续维持全局单主体假设。 - 为未来持久化任务流补一份 final-state protection / stale-connection resilience 设计说明。
验收标准
- 本 issue 作为本仓协议层 / 服务层后续进化的汇总母单保留；
- 后续拆分的子 issue 能明确标注：
- 是 durability 演进，还是 SDK integration 收敛；
- 是 machine-readable contract 收口，还是多入口 route/auth/card 能力演进；
- 是否影响当前对外 compatibility promises；
#166、#167与后续新拆 issue 之间的边界清晰，不重复造轮子。
备注
- 本次评估刻意不纳入“低定价比”的候选项。
- 当前仓库在 compatibility docs、extension taxonomy、contract honesty 上已经处于较强状态；本 issue 的重点是记录下一阶段仍值得做的“结构性演进点”，不是否定现状。