Skip to content

[docs] 更新 README:首页补充架构图并推荐 a2a-client-hub 作为消费端 #168

@liujuanjuan1984

Description

@liujuanjuan1984

[docs] 更新 README:首页补充架构图并推荐 a2a-client-hub 作为消费端

背景

当前 opencode-a2a-serve 的根 README 已经具备愿景、核心价值、能力概述和文档导航,但从开源项目首页视角看,仍有两个明显缺口:

  1. 缺少首页级架构图,首次进入仓库的读者仍需要依赖文字理解服务角色、边界与上下游关系。
  2. 缺少客户端侧消费建议,README 没有明确告诉读者“如果要在客户端侧消费这个服务,应优先使用什么项目/层次”。

这会让 README 在“项目定位清晰度”上仍有提升空间,尤其是对第一次接触仓库的技术读者。

问题

  • 没有架构图时,读者难以快速建立 A2A client -> opencode-a2a-serve -> OpenCode runtime 的心智模型。
  • 缺少客户端侧推荐时,服务端仓库容易被误当作同时承载客户端接入职责。
  • README 虽然已有价值说明,但首页入口还可以更明确地区分“服务端适配层”和“客户端消费层”。

建议方案

  1. 在根 README.md 增加首页级架构图
    • 目标是帮助首次阅读者快速理解系统组成与职责边界
    • 图建议突出:A2A client / Hub / App、opencode-a2a-serve、共享契约/运维边界、OpenCode runtime 之间的关系
    • 可采用 Mermaid,保持和仓库当前文档风格一致
  2. 在根 README.md 增加客户端侧推荐说明
    • 明确推荐 https://github.com/liujuanjuan1984/a2a-client-hub 作为消费 opencode-a2a-serve 的客户端侧集成层
    • 说明 opencode-a2a-serve 聚焦服务端/运行时边界,而 a2a-client-hub 更适合承载客户端消费、上游适配归一化和应用侧集成职责
  3. 如需避免首页重复,可同步梳理架构文档分层
    • README 保留“适合首次阅读”的图和高层说明
    • 更细的边界、请求流和模块说明下沉到专门文档

验收标准

  • README.md 包含一张首页级架构图
  • README 明确推荐 a2a-client-hub 作为客户端侧消费当前服务的优先入口
  • 首页能更清楚地区分服务端适配层与客户端消费层职责
  • 如果涉及文档分层调整,不引入新的 README / docs 重复

参考

  • 可参考 codex-a2a-serve 近期对 README 与架构文档的整理思路
  • 当前快照:2f471cb3bbc951bfb3f7356b49452db65fab280b

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions