chore: uv packaging + README refresh, prep for TestPyPI
- pyproject: metadata (license/classifiers/urls), cryptography runtime dep, optional [nats] extra, PEP 735 dependency-groups dev (pytest/pyright), hatch wheel target src/agenthub - regenerate uv.lock; uv sync/build verified (sdist+wheel, no node_modules) - README: real repo structure, channel matrix, uv workflows, TestPyPI flow - dist/ ignored
This commit is contained in:
1 parent
86642e07c9
commit
0e585c1d5a
3 files changed
+434
-32
No files matched your search
@@ -1,47 +1,112 @@
|
||||
# agenthub
|
||||
|
||||
IM/NATS ↔ 本地 ACP 桥:让总线上的编排方(Octop / botflow / 任意 worker)
|
||||
能够**发现并驱动**运行在本地机器上的 ACP 编码 agent
|
||||
(Claude Code、Codex、Gemini CLI、OpenCode …),并收回结构化事件流。
|
||||
IM/NATS ↔ 本地 ACP 桥:让 IM 用户(企业微信 / 微信)与总线上的编排方
|
||||
(Octop / botflow / 任意 worker)能够**发现并驱动**运行在本地机器上的
|
||||
ACP 编码 agent(Claude Code、Codex、Gemini CLI、OpenCode …),
|
||||
并收回结构化事件流。
|
||||
|
||||
```
|
||||
IM 用户 ── Octop ── NATS bus ── agenthub ── stdio JSON-RPC (ACP) ── coding agent
|
||||
IM 用户 ─┐
|
||||
├─ agenthub ── stdio JSON-RPC (ACP, ndjson) ── coding agent
|
||||
NATS bus ┘
|
||||
```
|
||||
|
||||
## 定位
|
||||
- IM 与 NATS 是**平级前端通道**:NATS 只负责消息如何来、怎么回;
|
||||
IM 通道把企业微信/微信消息归一化成同一套 op 语义。
|
||||
- agenthub 在 ACP 协议里是 **client**(agent 子进程是 server)。
|
||||
|
||||
- **ACP agent 侧代理(client 角色)**:agenthub 作为 ACP client 拉起/管理
|
||||
本地 agent 子进程,把 NATS 请求翻译成 ACP 会话。
|
||||
- **总线侧服务**:对外表现为 NATS 上的一个可发现服务(类似 A2A 的
|
||||
Agent Card 思路,但传输是 NATS)。
|
||||
详细设计见 [docs/DESIGN.md](docs/DESIGN.md),
|
||||
ACP 协议速查(方法/生命周期/实测坑)见 [docs/ACP_PRIMER.md](docs/ACP_PRIMER.md)。
|
||||
|
||||
详细设计见 [docs/DESIGN.md](docs/DESIGN.md)。
|
||||
## 安装(uv 管理)
|
||||
|
||||
```bash
|
||||
# 从源码
|
||||
git clone https://gitea.vxquant.com/vxquant/agenthub.git
|
||||
cd agenthub
|
||||
uv sync # 创建 .venv、装运行时依赖 + dev 组
|
||||
uv run pytest tests/ -q # 43 个测试应全绿
|
||||
|
||||
# 从 PyPI(测试源)
|
||||
uv pip install --index-url https://test.pypi.org/simple/ agenthub
|
||||
```
|
||||
|
||||
运行依赖刻意保持最小(当前仅 `cryptography`,供企微自建应用消息加解密)。
|
||||
NATS 通道的 `nats-py` 放在 extra:`uv pip install "agenthub[nats]"`。
|
||||
|
||||
## 配置
|
||||
|
||||
配置用 JSON(`config.json`,首次引导;运行期事实源是 sqlite DB):
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"claude-code": {
|
||||
"cmd": ["claude", "--acp"],
|
||||
"cwd_whitelist": ["~/projects/*"]
|
||||
}
|
||||
},
|
||||
"session": { "idle_ttl_s": 1800, "max_sessions": 8 },
|
||||
"orchestration": { "max_depth": 3 },
|
||||
"nats": { "url": "nats://127.0.0.1:4222",
|
||||
"inbox": "bots.agenthub.in", "events": "bots.agenthub.out" },
|
||||
"channels": {
|
||||
"wecom": { "bot_id": "...", "secret": "..." },
|
||||
"wecom-app": { "corp_id": "...", "agent_id": "...", "secret": "...",
|
||||
"token": "...", "encoding_aes_key": "..." },
|
||||
"weixin": { "token": "扫码登录后持久化的 token" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 通道
|
||||
|
||||
| 通道 | 目录 | 传输 | 流式 |
|
||||
|---|---|---|---|
|
||||
| `wecom` 企微 aibot | `src/agenthub/channels/wecom.py` | WebSocket 长连接(免公网回调) | ✅ 同气泡流式编辑,delta 0.8s 合并 |
|
||||
| `wecom-app` 企微自建应用 | `src/agenthub/channels/wecom_app.py` | HTTP 回调 + qyapi API;企微客户端与微信(微信插件)两端可用 | ❌ 无编辑 API,整段发送 |
|
||||
| `weixin` 微信智能机器人 | `src/agenthub/channels/weixin.py` | QR 扫码登录 + `getupdates` 长轮询 | ❌ 整段发送 |
|
||||
|
||||
事件语义(三通道与 NATS 通道一致):
|
||||
`delta / thinking / tool_start / tool_end / plan / permission / final`。
|
||||
|
||||
## 会话与 /switch
|
||||
|
||||
- 绑定表:`(channel, chat_id) → {agent, acp_session_id}`,sqlite 持久化。
|
||||
- `/switch <agent> [--continue]`:切换 IM 会话绑定的 agent;
|
||||
`--continue` 跨 agent 只迁移 hub 侧对话文本(tool state 不迁移)。
|
||||
- cwd 白名单按 agent 配置校验;`idle_ttl_s` 到期回收,`max_sessions` LRU 逐出。
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```
|
||||
agenthub/
|
||||
├── docs/DESIGN.md # 设计方案(总)
|
||||
├── docs/ACP_PRIMER.md # ACP 协议速查(方法/生命周期/坑)
|
||||
├── src/acp_bridge/
|
||||
│ ├── __init__.py
|
||||
│ ├── config.py # 配置加载
|
||||
│ ├── agent_registry.py # 本地 agent 进程池(拉起/复用/回收)
|
||||
│ ├── acp_client.py # ACP JSON-RPC over stdio 客户端(frame 层)
|
||||
│ ├── session.py # 会话状态机:nats 请求 <-> acp session 映射
|
||||
│ ├── events.py # ACP session/update -> NATS 事件主题 映射
|
||||
│ └── nats_service.py # NATS 订阅/发布、服务发现广播
|
||||
├── tests/
|
||||
└── pyproject.toml
|
||||
```
|
||||
|
||||
## 快速开始(规划中)
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
uv run agenthub --config config.json
|
||||
├── docs/DESIGN.md # 设计方案(总)
|
||||
├── docs/ACP_PRIMER.md # ACP 协议速查(ndjson 实测修正等)
|
||||
├── src/agenthub/
|
||||
│ ├── framing.py # ndjson / LSP-frame 双传输分帧
|
||||
│ ├── acp_client.py # ACP JSON-RPC over stdio 客户端(含反向请求)
|
||||
│ ├── session.py # 绑定表 + /switch + 事件中继 + idle reaper + sqlite
|
||||
│ ├── channels/ # IM 前端通道(wecom / wecom-app / weixin)
|
||||
│ ├── nats_service.py # NATS 订阅/发布(M1 后续)
|
||||
│ ├── agent_registry.py # agent 进程池(M2)
|
||||
│ └── config.py # 配置加载
|
||||
├── tests/ # 43 tests(mock agent 子进程 + mock 传输)
|
||||
├── scripts/probe_agent.py # ACP agent 探针
|
||||
└── config.json # 示例配置
|
||||
```
|
||||
|
||||
## 状态
|
||||
|
||||
设计阶段 → M0 骨架实现中。
|
||||
- **M0 ✅** ACP 客户端(ndjson 传输实测修正,真实 claude-code-acp 验证)
|
||||
- **M1 ✅** SessionManager(绑定表 / switch / reaper / sqlite)
|
||||
- **M1.5 ✅(代码+mock e2e)** 三 IM 通道;真机验收需真实凭据
|
||||
- **待做**:NATS 通道服务化、Web admin、supervisor + dashboard
|
||||
|
||||
## 发布
|
||||
|
||||
```bash
|
||||
uv build # 产 dist/*.tar.gz + *.whl
|
||||
uv publish --publish-url https://test.pypi.org/legacy/ # 测试源
|
||||
uv publish # 正式 PyPI(Gitea 测试通过后再发)
|
||||
```
|
||||
Reference in new issue
Block a user