Files
agenthub/docs/UPGRADE_SPLIT.md

62 lines
3.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 升级方案:拆分为 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 协议。