Skip to content

Commit f117a23

Browse files
DeliciousBudingclaude
DeliciousBuding
and
claude
committed
chore(docs): 仓库治理——文档去重、README 产品化、分支清理
- 删除 docs/ 根级 3 个重复文件（权威版在 docs/governance/） - README.md/README_EN.md 产品化重写：移除开发态内容、验证命令、内部引用 - 收件箱/过期 review 文件归档至 docs/archive/ - PLAN.md 归档、dev-start 脚本修正 agenthub-hub→server-hub - fork 远端 7 个过期分支删除 - .gitignore 新增 .tmp/ Co-Authored-By: Claude <noreply@anthropic.com>
1 parent fccd428 commit f117a23

18 files changed

Lines changed: 44 additions & 214 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ hub-server/deployments/.env
8484
hub-server/deployments/backups/
8585
backups/
8686

87+
# Local temp files
88+
.tmp/
89+
8790
# Local machine and agent state
8891
.worktrees/
8992
docs/review/

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -368,7 +368,7 @@ python -c "import yaml, pathlib; yaml.safe_load(pathlib.Path('api/openapi.yaml')
368368
git status --short --branch
369369
```
370370

371-
运行命令以真实入口为准：Edge 是 `edge-server/cmd/agenthub-edge`，Hub 是 `hub-server/cmd/server-hub`。`scripts/dev-start.ps1` / `scripts/dev-start.sh` 仍引用旧 Hub 命令，`scripts/client-smoke.ps1` 仍包含已删除 `runner/` 的历史检查；修复脚本前不要把这些脚本作为验收依据。
371+
运行命令以真实入口为准：Edge 是 `edge-server/cmd/agenthub-edge`，Hub 是 `hub-server/cmd/server-hub`。`scripts/dev-start.ps1` / `scripts/dev-start.sh` 已修复 Hub 入口路径。`scripts/client-smoke.ps1` 仍包含已删除 `runner/` 的历史检查；修复脚本前不要把这些脚本作为验收依据。
372372

373373
有 Go 代码后追加：
374374

‎README.md‎

Lines changed: 16 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
[English](README_EN.md) &nbsp;·&nbsp; [产品需求](docs/architecture/product-requirements.md) &nbsp;·&nbsp; [系统架构](docs/architecture/system-architecture.md) &nbsp;·&nbsp; [API 契约](api/) &nbsp;·&nbsp; [官网](https://hub.vectorcontrol.tech)
1010

11-
<img src="https://img.shields.io/badge/状态-P0--M7_完成-blue?style=flat-square" alt="status">
11+
<img src="https://img.shields.io/badge/状态-P0_完成-blue?style=flat-square" alt="status">
1212
<img src="https://img.shields.io/badge/go-1.25+-00ADD8?style=flat-square&logo=go" alt="go">
1313
<img src="https://img.shields.io/badge/react-19-61DAFB?style=flat-square&logo=react" alt="react">
1414
<img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?style=flat-square" alt="license">
@@ -19,13 +19,13 @@
1919

2020
## 这是什么
2121

22-
AgentHub 把 AI 编程 Agent 变成 IM 联系人。你可以像在群聊里 @同事一样 @ClaudeCode 写代码、@Codex 做审查、@Reviewer 提建议，所有计划、执行、Diff、审批和预览都在同一个聊天线程中流转。
22+
AgentHub 把 AI 编程 Agent 变成 IM 联系人。你可以像在群聊里 @同事一样 @ClaudeCode 写代码、@Codex 做审查、@Reviewer 提建议，所有计划、执行、Diff、审批和预览都在同一个聊天线程中流转，不需要在工具之间来回切换。
2323

24-
**与现有工具的区别**：多数 Claude Code GUI 是单人聊天壳。AgentHub 的核心是多 Agent 协作和多端控制：Desktop 提供本地执行工作台，Edge Server 连接真实 Agent CLI，Hub Server 提供账号、IM、多端同步和远程中继。
24+
与现有工具的区别：多数 Claude Code GUI 是单人聊天壳。AgentHub 的核心是多 Agent 协作和多端控制：Desktop 提供本地执行工作台，Edge Server 连接真实 Agent CLI，Hub Server 提供账号、IM、多端同步和远程中继。
2525

26-
当前已完成：Edge Server 三大 Agent Runtime 适配（Claude Code、Codex、OpenCode）、Desktop IM 工作台（React 19 + Tauri + TanStack Query + Zustand）、Hub Server 三层架构（Gin/GORM/Redis/PostgreSQL，17 组迁移）和 Edge-Hub 部署链路。当前状态以 [docs/handoff/STATE.md](docs/handoff/STATE.md) 和 [docs/roadmap.md](docs/roadmap.md) 为准。
26+
你可以拉一个群，把 Builder、Reviewer、Tester 三个 Agent Profile 加进去——Builder 写代码，Reviewer 自动审查 Diff，Tester 跑测试，所有输出和决策都在群聊里透明可见。审批卡片、进度播报、Artifact 预览都是 IM 原生协作体验的一部分。
2727

28-
跨产品治理请同步阅读工作区根文档：统一第三方登录见 `../docs/unified-login.md`，AgentHub 飞书/Lark 应用规划见 `../docs/feishu-agenthub-integration.md`，设计 token 收敛见 `../docs/design-token-convergence.md`，产品包装/SEO/i18n 见 `../docs/agent-seo-i18n-packaging.md`。
28+
AgentHub 支持 Claude Code、Codex、OpenCode 三种 Agent Runtime。Agent Profile 可自由组合 Runtime、模型、Skill、MCP 和审批策略，配置一次，在多台设备上同步使用。
2929

3030
<br>
3131

@@ -49,18 +49,16 @@ Desktop UI -> Local Edge Server -> Agent Runtime Adapter -> Claude Code / Codex
4949
| **Shared App** | `app/shared/` | 前端共享类型、API/event client、树/Diff 工具和 `@shared/ui` 组件 |
5050
| **API Contract** | `api/` | REST JSON API 与 WebSocket typed events 契约 |
5151

52-
早期设计中曾有独立 `runner/` 目录；当前执行生命周期已经合并到 Edge Server 的 `internal/lifecycle/`，Runtime 协议适配位于 `internal/adapters/`。文档和 UI 应使用 **Agent Runtime**、**Agent Profile**、**Agent Configuration**、**Execution Target** 四个术语，避免把 Runtime 直接称为用户配置好的 Agent。
53-
5452
<br>
5553

5654
## 核心概念
5755

5856
| 概念 | 含义 | 例子 |
5957
|---|---|---|
60-
| **Agent Runtime** | 能启动并解析某类 Agent CLI/SDK 的适配器。它回答“用什么运行”。 | Claude Code、Codex、OpenCode |
61-
| **Agent Profile** | 用户选择和管理的 Agent 实体。它回答“谁来做事”。 | `Reviewer on Codex/gpt-5.4-high`、`Builder on Claude Code/sonnet` |
62-
| **Agent Configuration** | Profile 的可编辑规则集合。它回答“按什么规则做事”。 | `AGENTS.md`、memory、上下文、聊天记录、工作目录、Skill、MCP、模型参数、审批策略 |
63-
| **Execution Target** | 某次 Run 实际执行的位置。它回答“在哪里执行”。 | Local Edge、Remote Edge over SSH/Tailscale、Cloud Edge、Hub Relay target |
58+
| **Agent Runtime** | 能启动并解析某类 Agent CLI/SDK 的适配器。它回答"用什么运行"。 | Claude Code、Codex、OpenCode |
59+
| **Agent Profile** | 用户选择和管理的 Agent 实体。它回答"谁来做事"。 | `Reviewer on Codex/gpt-5.4-high`、`Builder on Claude Code/sonnet` |
60+
| **Agent Configuration** | Profile 的可编辑规则集合。它回答"按什么规则做事"。 | `AGENTS.md`、memory、上下文、聊天记录、工作目录、Skill、MCP、模型参数、审批策略 |
61+
| **Execution Target** | 某次 Run 实际执行的位置。它回答"在哪里执行"。 | Local Edge、Remote Edge over SSH/Tailscale、Cloud Edge、Hub Relay target |
6462

6563
本地执行不依赖 Hub：Desktop 可以只连接 `127.0.0.1:3210` 的 Local Edge 完成项目、Thread、Run 和 Runtime adapter 调度。Hub 只在账号、团队 IM、多端同步、远程查看/审批、设备路由和中继场景进入链路。
6664

@@ -104,11 +102,7 @@ macOS/Linux:
104102
./scripts/setup.sh
105103
```
106104

107-
### 推荐本地链路
108-
109-
当前真实可用的本地执行链路是手动启动 Edge 和 Desktop。`scripts/dev-start.ps1` / `scripts/dev-start.sh` 仍引用旧 Hub 命令，修复前不要把它当作推荐入口。
110-
111-
终端 1：Edge Server。
105+
### 启动 Edge Server
112106

113107
```powershell
114108
cd edge-server
@@ -123,7 +117,7 @@ go run ./cmd/agenthub-edge --agent-default codex
123117
go run ./cmd/agenthub-edge --agent-default opencode
124118
```
125119

126-
终端 2：Desktop Web UI。
120+
### 启动 Desktop
127121

128122
```powershell
129123
cd app/desktop
@@ -144,68 +138,15 @@ go run ./cmd/server-hub
144138

145139
默认配置来自 `hub-server/configs/config.yaml`：Hub HTTP `localhost:8080`，admin/pprof/metrics `localhost:6060`，Redis 默认 `localhost:6380`。
146140

147-
### Desktop 应用构建和实测
141+
### Desktop 应用构建
148142

149143
```powershell
150144
cd app/desktop
151145
pnpm build
152146
pnpm tauri dev
153147
```
154148

155-
`pnpm build` 只构建前端，不需要 Rust 工具链；`pnpm tauri dev` 需要 Rust 和 Tauri 系统依赖。Playwright 桌面 Web 预览使用 `http://localhost:5199`：
156-
157-
```powershell
158-
cd app/desktop
159-
pnpm test:e2e
160-
```
161-
162-
`scripts/client-smoke.ps1` 已对齐当前 Edge Runtime 架构，不再构建已删除的独立 `runner/` 目录；它使用 Edge 内置 `agenthub-runner-mock` 兼容 profile，并支持 `-EdgeAddr` 在隔离端口运行。
163-
164-
### 当前验证命令
165-
166-
文档改动至少运行：
167-
168-
```powershell
169-
git diff --check
170-
python -c "import yaml, pathlib; yaml.safe_load(pathlib.Path('api/openapi.yaml').read_text(encoding='utf-8')); print('yaml ok')"
171-
```
172-
173-
Runtime / AgentAdapter / Edge API / Settings 展示边界改动还应运行：
174-
175-
```powershell
176-
.\scripts\verify-runtime-readiness.ps1
177-
```
178-
179-
Web Hub/Local Edge 边界改动还应运行：
180-
181-
```powershell
182-
.\scripts\verify-web-hub-boundary.ps1
183-
```
184-
185-
后端改动：
186-
187-
```powershell
188-
cd edge-server
189-
go test ./... -short -count=1
190-
191-
cd ..\hub-server
192-
go test ./... -short -count=1
193-
```
194-
195-
前端改动：
196-
197-
```powershell
198-
cd app/desktop
199-
pnpm test
200-
pnpm build
201-
pnpm typecheck
202-
203-
cd ..\web
204-
pnpm typecheck
205-
pnpm build
206-
```
207-
208-
已知限制：`app/shared/src/ui` 的 React 类型解析和跨包虚拟存储会影响部分 shared-ui 测试/typecheck；提交前需要在变更说明中区分“新引入错误”和既有跨包限制。
149+
`pnpm build` 只构建前端，不需要 Rust 工具链；`pnpm tauri dev` 需要 Rust 和 Tauri 系统依赖。
209150

210151
<br>
211152

@@ -231,8 +172,6 @@ AgentHub/
231172
└── scripts/ # 本地 setup、git hooks、联调脚本
232173
```
233174

234-
Docker 和部署文件跟随所属模块放置。根级 compose 只用于跨模块本地联调。
235-
236175
<br>
237176

238177
## 文档导航
@@ -247,37 +186,19 @@ Docker 和部署文件跟随所属模块放置。根级 compose 只用于跨模
247186
| [调研索引](docs/reference/) | 跨仓库调研和工程规格 |
248187
| [调研与历史归档](docs/archive/) | 旧版架构、协议、memory、workspace 等历史材料 |
249188

250-
在 `D:\Code\TokenDance` workspace 内做跨系统治理时，先看根级 `../AGENTS.md` 和 `../docs/`。其中 `../docs/architecture/system-architecture.md`、`../docs/identity-auth.md`、`../docs/design-system.md` 定义 TokenDance 级别的架构、身份鉴权和设计系统边界；本仓库 `docs/` 只负责 AgentHub 实现细节。
251-
252189
<br>
253190

254-
## TokenDance ID 鉴权边界
255-
256-
TokenDance ID 是跨产品身份入口；Hub session 是 AgentHub 自己的产品会话。Hub Server 已提供 TokenDance ID relying-party 登录交换：`POST /client/auth/oidc/authorize` 生成 PKCE 授权 URL 和一次性 state，`POST /client/auth/oidc/callback` 完成 code exchange、验证 ID token 的 issuer/audience/JWKS、把 `tokendance_sub` 映射到 Hub user，再签发 Hub 本地 access/refresh session。
257-
258-
| 项 | 当前边界 |
259-
|---|---|
260-
| TokenDance ID | 统一第三方登录和账号主体；产品不直接集成 GitHub/Google/飞书 |
261-
| Hub Server | 拥有 Hub OIDC authorize/callback exchange、Hub user 映射、Hub access/refresh session 和 UUID device proof |
262-
| Desktop/Web | 打开系统浏览器或 Web 登录入口，保存 Hub session；不保存第三方 provider token |
263-
| 兼容 bearer 路径 | `hub-server/internal/middleware/auth.go` 可验证 TokenDance ID RS256/JWKS bearer token，但验证结果只标记为 `tokendance_bearer`，不能替代 Hub session，也不能满足 Edge `desktop` 设备门禁；`/client/ws` 只接受 Hub-issued HS256 access token，TokenDance bearer 会在 WebSocket upgrade 或首帧 auth 中被拒绝 |
264-
| 本地执行 | Local Edge + Desktop 执行不依赖 Hub 登录；需要云端 IM、同步、远控或中继时才需要 Hub session |
265-
266-
OIDC 结构检查：
267-
268-
```powershell
269-
.\scripts\verify-oidc-readiness.ps1
270-
```
191+
## 鉴权
271192

272-
该检查只证明公开仓库里的 Hub OIDC 端点、示例配置、Desktop/Web Hub session 存储策略、Hub WebSocket upgrade 鉴权和根治理矩阵对齐；它不连接生产 TokenDance ID，不需要真实 `client_secret`，也不替代部署态 login/callback/logout/reconnect 证据。
193+
AgentHub 使用 TokenDance ID 统一登录。Hub Server 管理自身会话层。本地执行无需登录；需要云端 IM、多端同步或远程控制时才需要连接 Hub。
273194

274195
<br>
275196

276197
## 参考项目
277198

278199
- [Claude Code Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview)
279200
- [OpenAI Codex CLI](https://github.com/openai/codex)
280-
- [OpenCode](https://github.com/anomalyco/opencode)
201+
- [OpenCode](https://github.com/sst/opencode)
281202
- [Multica](https://github.com/multica-ai/multica)
282203
- [LibreChat](https://github.com/danny-avila/LibreChat)
283204
- [Kanna](https://github.com/jakemor/kanna)

0 commit comments

Comments
 (0)