62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
# 升级方案:拆分为 agenthub-gateway / acpclient 两个包
|
||
|
||
## 目标
|
||
|
||
把现有单体 `agenthub` 升级为两个独立发布的 Python 包:
|
||
|
||
1. **acpclient**(新独立包,零 gateway 依赖)
|
||
- 迁入:`framing.py`(ndjson / lsp-frame 分帧)+ `acp_client.py`(ACPClient、
|
||
ACPError、ACPProcessDead、handler 协议)
|
||
- 新增(M-w1 需要的远程传输):`RemoteACPClient`——与 ACPClient 同一接口
|
||
(request/notify/register_*/initialize/session_*),transport 不是子进程
|
||
stdin/stdout,而是 HTTP POST(指令)+ WS(事件回流),帧仍是 ACP JSON-RPC 原样。
|
||
- 传输层抽象:`start()/close()/is_alive()/_send()/读循环` 收敛为 Transport 协议,
|
||
StdioTransport(现有逻辑原样)与 RemoteTransport(新)两个实现。上层
|
||
(session.py 的 pending/permission/relay 逻辑)完全不感知差别。
|
||
- 发布名:`acpclient`(PyPI 空闲已确认过 agenthub 被占但 acpclient 待查),
|
||
单独 repo `vxquant/acpclient`,CI 同 agenthub(Gitea 先行→GitHub)。
|
||
|
||
2. **agenthub-gateway**(原 agenthub 改名重发布)
|
||
- 目录 `src/agenthub/` 不动(import 名保留 `agenthub`,避免大改 140 个测试与
|
||
三台部署脚本),只改发行元数据:
|
||
- `name = "agenthub-gateway"`,`[project.scripts] agenthub-gateway = "agenthub.__main__:main"`
|
||
- 依赖加 `acpclient`(本地 path/内网 PyPI),删除内部 framing/acp_client 模块,
|
||
`from acpclient import ...` 兼容 shim:`agenthub/acp_client.py` 留 3 行 re-export,
|
||
老测试/老 import 不破坏。
|
||
- gateway 侧后续新增(本升级不实现,仅留口):`worker:<name>` agent 类型
|
||
(cmd 字段换 url 字段)、deepagents orchestrator 段。
|
||
|
||
## 为什么保留 import 名 `agenthub`
|
||
|
||
- 140 tests + 三台部署(zd git pull、api rsync、proxy git)+ supervisor unit 文件
|
||
都引用 `agenthub` 包与 `agenthub` 命令;改名 import 是纯机械风险零收益。
|
||
- 发行名与 import 名不一致是 Python 常态(`pip install agent-client-protocol`
|
||
→ `import acp`)。
|
||
|
||
## 实施清单(一次升级,向后兼容)
|
||
|
||
| # | 事项 | 验证 |
|
||
|---|---|---|
|
||
| 1 | 新 repo `vxquant/acpclient`:src/acpclient/{framing,client,transports}.py(代码从 agenthub 平移) | uv run pytest(迁过去的老测试 + RemoteTransport 单测 mock HTTP/WS) |
|
||
| 2 | acpclient pyproject:独立版本 0.1.0,零依赖(stdlib only,WS 用 websockets optional extra) | uv build + 安装冒烟 |
|
||
| 3 | agenthub pyproject:rename `agenthub-gateway`,deps + acpclient,scripts 改名,旧脚本 `agenthub` 保留别名 | 全量 140 tests 过(import 不变) |
|
||
| 4 | agenthub/acp_client.py 与 agenthub/framing.py 变 re-export shim | 老测试不动全绿 |
|
||
| 5 | Gitea 建 vxquant/acpclient、推送;agenthub-gateway 版本 bump 0.2.0 | push 成功 |
|
||
| 6 | 三台部署:zd/proxy git pull(requirements 解析 acpclient 需内网可装——Gitea 直装 `agenthub-gateway @ gitea+https` 或 vendor);api rsync | 目标机 pytest + 重启 + status |
|
||
| 7 | CHANGELOG + DESIGN_GATEWAY_WORKER.md 更新实施状态 | — |
|
||
|
||
## RemoteACPClient 接口草案
|
||
|
||
```python
|
||
class RemoteACPClient:
|
||
"""ACPClient 兼容接口,帧走 HTTP/WS 到 worker-agentd。"""
|
||
def __init__(self, base_url: str, worker_token: str | None = None): ...
|
||
# 与 ACPClient 相同:request/notify/register_notification_handler/
|
||
# register_request_handler/initialize/session_new/session_prompt/session_cancel
|
||
# start() = 打开 WS 事件流 + POST initialize;close() = POST /close
|
||
# is_alive() = WS 连接健康 + 心跳未超时
|
||
```
|
||
|
||
worker-agentd(后续 M-w1 实现,不在本升级)作为 acpclient 的姊妹服务,
|
||
复用 acpclient 的 framing/handler 协议。
|