# Bot Agent 自主组建团队

分支：`feat/bot-agent-teams`。配套 iOS 使用同名分支；该功能没有修改基础 Hermes Profile。

## 使用

在 Bot 模式创建或编辑 Agent，打开「允许组建团队」并保存。例如给它发送：

> 帮我完成项目调研，需要哪些成员就先查看已有 Agent，缺少时再创建。组建团队、启动任务，并告诉我到哪个团队查看结果。

Agent 可以查看可用基础 Agent、复用已有成员、创建持久成员和团队、启动独立团队任务、读取进展和结果。新团队自动加入发起者并将其设为管理员，随后使用已有的 @分派和管理员复核机制。成员、团队和任务写入当前账号的 `workspace.sqlite3`，发布既有变更事件供 Web/iOS 同步。

启动任务返回「已启动，尚未完成」。工作在新团队的任务内继续，结果在那里显示；发起者可使用查询工具读取结果。并未新增回到原单聊的自动回传机制，也不会把队列完成当成用户目标已经达成。

## 运行条件

- Web 服务和发起者的 Hermes 必须在同一机器/网络命名空间，以回环地址连接。远程节点和远端引用 Agent 可作为成员，不能开启发起组队权限。
- 发起者的基础 Profile 需安装并启用既有 `yaoyao-bot-bridge` 工具桥，能力响应必须包含 `version: 1`、`ready: true`、`in_process: true`、`native_tools: true`。插件由 Hermes Bot 提供；按其安装流程部署并重新加载，Named Profile 需要各自安装、启用。
- 服务端在首次授予权限及每轮执行前检查条件。不满足时返回具体错误，普通 Agent 对话仍不查询工具桥。
- 先部署 Web 分支，再使用配套 iOS 分支。现有记录缺少 `canManageTeam` 时按关闭处理；新建成员默认关闭。

## 工具与权限

| 工具 | 作用 |
| --- | --- |
| `workspace_list_sources` | 当前账号获准的基础 Profile |
| `workspace_list_agents` | 当前账号可使用的已有成员 |
| `workspace_list_teams` | 发起者担任管理员的团队 |
| `workspace_create_agent` | 创建成员，禁止授予组队权限 |
| `workspace_create_team` | 创建管理员协作模式的团队 |
| `workspace_start_team_task` | 在发起者管理的团队启动任务 |
| `workspace_get_team_task` | 读取状态、最近 20 条消息和待处理问题 |

所有变更工具要求 `requestId`（UUID）；重试同一操作必须复用它。服务端持久保存回执；相同编号用于不同参数返回冲突，重复请求不会重复创建。原生工具调用 ID 也在本轮去重。

账号和调用 Agent 从正在运行的服务端轮次取得，模型参数不能指定 owner、token 或调用身份。创建成员只能引用当前账号获准的基础 Profile；子账号的分配规则保持有效。只有团队管理员可以启动或读取该团队的任务，禁止从当前团队任务递归启动自身任务。

每轮使用独立随机凭据、独立原生工具 ID 和回环监听端口，凭据仅传给经过认证的工具桥绑定接口。权限、账号、Profile、成员归属、归档和停止状态在每次调用时校验，异步操作在写入前再次校验。绑定保留 Agent 的配置版本；关闭后重新开启权限也不能使旧轮次重新生效。完成、取消、连接结束或服务关闭时销毁监听器并解绑；最长 30 分钟，运行时每 5 分钟续租。断线恢复只核对原执行，不重新提交已有工具副作用；下一轮重新授权。

自动组队的范围：每队 2–8 人，最多管理 20 个有效团队，账号最多保留 100 个有效 Agent，默认协作 6 轮、可设置 1–12 轮，每轮最多 128 次团队工具调用。运行并发沿用现有调度器。手工编辑团队仍走原有界面和接口。

## 验证

```sh
npm run typecheck
npm test
npm run test:e2e:team-tools
```

`tests/server/workspaceTeamTools.test.ts` 验证创建、持久去重、账号隔离、Profile 撤销、配置版本失效、停止、回环认证、不同轮次的工具 ID/凭据隔离、过期和取消绑定竞态。

真实 Hermes 协议验收使用隔离测试实例（不调用付费模型、不访问用户会话）：

1. 使用 Hermes 的 Python，运行 Hermes Bot 仓库内 `integrations/hermes-bots-bridge/tests/hermes_wire_fixture.py /path/to/hermes-agent`。
2. 将它打印的回环 URL 设为 `HERMES_TEAM_WIRE_URL`，运行 `npm test -- tests/live/workspaceTeamTools.live.test.ts`。

此测试必须校验实例的专用 fixture 标记，实际经过 HTTP 登录、WebSocket 会话、插件原生工具注册、回环工具调用、持久成员/团队/任务和权限撤销。未设置 URL 时跳过该项；模型决策使用确定脚本，因此不代表真实模型在任意任务下的自主组队质量。

### 2026-09-08 分支验收

- 类型检查及生产构建通过。
- 完整 Vitest：98 个文件、649 项通过；上述需显式指定实例的用例默认跳过，并已单独执行通过。
- 真实 Hermes 隔离实例通过创建、重试去重、团队任务、撤销和两个发起者同时调用的验证，实际注册的原生函数名称互不冲突。
- Playwright：新开关保存/重载/撤销 1 项、原有成员/团队及子账号权限回归 2 项通过。检查了桌面浅色与 375px 手机宽度深色截图。
- iOS：24 项 WorkspaceChatTests 通过；开关保存往返在普通显示与深色大字体下均通过模拟器验收。
- 首次全量并发运行有 1 项既有语音配置用例失败；聚焦重跑及最终全量运行均通过，未修改语音功能。

所有结果来自分支代码和隔离数据。没有部署正式 Web、调用付费模型、安装实体手机或合并主分支。