feat(skills): 补全团队管理操作规范 (#92)

## 中文 ### 变更 - 将 manage-teams 升级到 1.3.0，并设置最低客户端版本 10.0.108 - 补齐 ManageTeam 全部 14 个 action 的用途、参数与风险边界 - 增加创建前检查、工作目录选择、Smart 成员路由、组织更新、头像、团队仓库、远程同步与失败恢复流程 - 明确远程操作必须经过 ManageTeam 的原因是供应链校验与审批，而不是假设 Agent 永远拿不到凭据 - 保持 disable-model-invocation: true，只在需要管理团队时按需加载 ### 测试 - uv run --quiet scripts/i18n/test_validate_i18n.py - uv run --quiet scripts/i18n/validate-i18n.py - uv run --quiet scripts/i18n/translate.py --check - git diff --check ## English ### Changes - Upgrade manage-teams to 1.3.0 and require client 10.0.108 - Cover all 14 ManageTeam actions with their parameters and risk boundaries - Add preflight checks, workdir selection, Smart member routing, organization updates, avatars, team repositories, remote synchronization, and failure recovery - Clarify that remote operations must use ManageTeam for supply-chain validation and approval, not because Agents can never access credentials - Keep disable-model-invocation: true so the Skill is loaded only when team management is needed ### Tests - uv run --quiet scripts/i18n/test_validate_i18n.py - uv run --quiet scripts/i18n/validate-i18n.py - uv run --quiet scripts/i18n/translate.py --check - git diff --check
2026-09-05 21:43:46 +08:00 · 2026-08-25 18:32:03 +08:00
parent bdaaa44ce1
commit 2891f9dc06
2 changed files with 247 additions and 199 deletions
--- a/skills/manage-teams/SKILL.zh-CN.md
+++ b/skills/manage-teams/SKILL.zh-CN.md
@@ -4,134 +4,158 @@

 ## L0：一句话摘要

-创建和管理 Agent 团队，组织多 Agent 围绕共同任务协作。
+通过 `ManageTeam` 查询、创建和治理 Agent 团队，并在组织变更或远程同步前完成必要检查。

-## L1：概述与使用场景
+## L1：何时使用

-### 能力描述
+以下情况使用团队：

-manage-teams 是一个**流程型技能（Procedural Skill）**，赋予 DesireCore 创建和管理 Agent 团队的能力。团队是多个 Agent 围绕共同任务协作的组织单元，每个团队有一个组长（supervisor）负责接收需求、拆解任务、分派给成员、汇总结果。
+- 多个 Agent 需要围绕同一任务持续协作并共享团队工作目录；
+- 需要稳定的组长、成员关系或父子团队组织结构；
+- 需要发布、安装或同步一个团队仓库。

-### 使用场景
+以下情况不要创建团队：

- 需要多个 Agent 围绕同一任务持续协作（如项目组）
- 需要建立组织架构（部门/团队层级）
- 需要组长统一调度、拆解和分派任务
- 简单一次性委派不够，需要共享上下文的长期协作
+- 一次性向一个专家求助：直接 `Delegate(mode="sync" | "async")`；
+- 多个专家只需各自给出一次意见：直接 `Delegate(mode="fan-out")`；
+- 只是临时文件探索：使用 Worker，不要制造长期组织关系。

-### 核心价值
+团队只定义组织、共享目录和治理关系。实际给成员分派工作仍使用 `Delegate`。

- **组织化协作**：从单点委派升级为团队协作模式
- **灵活管理**：支持临时团队和持久团队两种模式
- **动态调整**：运行时可添加/移除成员、更换组长
+## L2：执行规范

-## L2：详细规范
+### 1. 先查再改

-## 核心概念
+- 不知道 `teamId` 时先执行 `ManageTeam(action="list")`。
+- 修改、解散或远程同步前执行 `ManageTeam(action="get", teamId=...)`，核对名称、类型、组长、成员、本地仓库目录和远程状态。
+- 不要猜测 `~/.desirecore` 下的路径；本地仓库绝对路径只使用 `get` 返回值。
+- `list` 可传 `parentTeamId` 过滤；`tree=true` 返回组织树，此时 `teamId` 表示子树根，`parentTeamId` 不生效。

-### 团队 vs 单点委派
+### 2. Action 对照表

-| 场景 | 推荐方式 | 理由 |
-|------|---------|------|
-| 一次性简单问题 | `Delegate(target, mode='sync')` | 无需组织开销 |
-| 需要一个专家处理 | `Delegate(target, mode='sync/async')` | 一对一足够 |
-| 需要多专家各出意见 | `Delegate(targets, mode='fan-out')` | 并行分派无需创建团队 |
-| 持续协作 + 共享上下文 | **创建团队** | 团队提供共享 workdir 和组织架构 |
-| 组织架构管理 | **创建嵌套团队** | 部门/团队层级关系 |
+| action | 用途 | 关键参数与注意事项 |
+|---|---|---|
+| `list` | 列出团队或组织树 | `parentTeamId?`、`tree?`、`teamId?` |
+| `get` | 查看单个团队详情和仓库路径 | `teamId` |
+| `create` | 创建临时团队 | `name` 或 `task`；`supervisor?`、`members?`、`memberRouting?`、`parentTeamId?`、`workdirMode?` |
+| `add_member` | 添加一个成员 | `teamId`、`agentId` |
+| `add_members` | 批量添加成员 | `teamId`、`members` |
+| `remove_member` | 移除一个成员 | `teamId`、`agentId` |
+| `remove_members` | 批量移除成员 | `teamId`、`members` |
+| `set_supervisor` | 更换组长 | `teamId`、`agentId` |
+| `update` | 部分更新团队配置 | `teamId`；可更新 `name/type/isolation/parentTeamId/description/avatar/avatarImage` |
+| `promote` | 临时团队升级为持久团队 | `teamId`；单向操作，不得隐式执行 |
+| `disband` | 解散团队 | `teamId`；若用户未明确要求，先说明影响并确认 |
+| `fork_team` | 从远程仓库安装团队 | `url`；`name?`、`installMembers?`；进入审批闸门 |
+| `push` | 把本地团队仓库推送到已连接的远程 | `teamId`；进入审批闸门 |
+| `pull` | 从已连接的远程拉取并校验团队 | `teamId`；进入审批闸门 |

-### 团队类型
+### 3. 创建团队

- **临时团队（ephemeral）**：任务驱动，完成后可解散。适合项目制协作。
- **持久团队（persistent）**：长期存在，适合部门/团队。临时团队可升级为持久团队。
+创建前必须满足：

-### 组长唯一性约束
+1. `supervisor` 和 `members` 中的 Agent 均已存在。缺少时先用 `ManageAgent(action="list" | "get")` 核对，确需新增时再按对应 Agent Skill 创建。
+2. DesireCore 核心智能体 `desirecore` 不能担任组长。由核心智能体发起创建时必须显式指定普通 Agent 为 `supervisor`。
+3. 通常不要把 `desirecore` 加入成员；需要核心能力时通过 `Delegate` 调用。
+4. 一个 Agent 只能担任一个团队的组长；目标组长已有团队时，先为原团队指定接替者。

-**一个 Agent 只能担任一个团队的组长（TL）。** 这是组织架构的硬性约束：
+工作目录选择：

- 创建团队时，如果调用者已是其他团队的组长，应先卸任原团队组长（`set_supervisor` 指定接替者）再创建新团队
- 不要将已担任组长的 Agent 设为另一个团队的组长
- 一个 Agent 可以同时是某团队的组长和另一个团队的普通成员，但不能同时担任两个团队的组长
+- `merged`（默认）：团队共享目录优先，同时保留成员和全局工作目录；
+- `team_only`：只暴露团队共享目录，适合所有成员必须围绕同一项目目录工作的高可靠任务；不会删除成员原有目录配置。

-### 组长职责
+智能路由通过 `memberRouting` 表达意图，不写死 Provider 或模型：

-1. 接收用户需求，分析任务复杂度
-2. 拆解子任务，决定需要哪些成员参与
-3. 使用 `Delegate` 工具分派任务（单点或 fan-out）
-4. 汇总各成员结果，给出综合回答
-5. 根据需要动态调整成员（添加/移除）
-
-## 操作指南
-
-### 创建团队
-
-```
-ManageTeam({
-  action: 'create',
-  name: '房产评估项目组',
-  members: ['legal-advisor', 'finance-advisor', 'real-estate'],
-  task: '综合评估目标房产'
-})
+```json
+{
+  "supervisor-agent": {
+    "tier": "flagship",
+    "requiredCapabilities": ["reasoning"],
+    "reasoning": "high"
+  },
+  "member-agent": {
+    "tier": "balanced"
+  }
+}
 ```

-组长默认为调用者（你自己）。创建后你就是这个团队的 supervisor。
+- 键必须属于本次 `supervisor` 或 `members`；
+- 使用 fixed 模型的成员不能出现在 `memberRouting`；
+- 未填写的 Smart 成员保留现有路由档案；具体 Provider/模型在成员实际执行任务前解析。

-### 向团队成员分派任务
+示例：

-**单点委派**（一个成员处理）：
-```
-Delegate({
-  target: 'legal-advisor',
-  task: '检查该房产的产权状况和法律风险',
-  mode: 'sync'
-})
+```json
+{
+  "action": "create",
+  "name": "合同审查项目组",
+  "supervisor": "legal-lead",
+  "members": ["contract-reviewer", "risk-analyst"],
+  "task": "持续审查合同并汇总风险",
+  "workdirMode": "team_only"
+}
 ```

-**扇出委派**（多个成员并行）：
-```
-Delegate({
-  targets: ['legal-advisor', 'finance-advisor', 'real-estate'],
-  task: '从各自专业角度评估这套房产',
-  mode: 'fan-out',
-  strategy: 'parallel'
-})
+### 4. 修改组织与配置
+
+- 成员增删优先使用批量 action，避免多次调用产生中间状态。
+- `set_supervisor` 使用 `agentId` 指定新组长；先确认其未担任其他团队组长。
+- `update` 是部分更新：未传字段保持原值。
+- `parentTeamId: null` 表示摘除父团队成为顶层团队；空字符串非法。
+- `type` 只允许 `ephemeral → persistent`。原值幂等更新可以接受；明确升级优先使用 `promote`。
+- `isolation`：`soft` 共享会话隔离，`hard` 使用独立 Agent 副本。
+- `description` 是团队市场简介，不等同于 `create` 的 `task`。
+
+声明头像使用：
+
+```json
+{
+  "action": "update",
+  "teamId": "team-id",
+  "avatar": { "char": "审", "color": "purple" }
+}
 ```

-### 管理成员
+图片头像使用 `avatarImage.source`，可传 `dc-media://<mediaId>`、裸 `mediaId` 或工作目录内图片路径。支持 PNG/JPEG/WebP；不传 HTTP(S) URL 或 base64。移除图片使用 `{ "remove": true }`，不得与 `source` 同时出现。

-```
-// 添加成员
-ManageTeam({ action: 'add_member', teamId: '...', agentId: 'new-agent' })
+### 5. 团队生命周期

-// 批量添加成员
-ManageTeam({ action: 'add_members', teamId: '...', members: ['agent-a', 'agent-b'] })
+- 临时团队完成一次项目后应解散，避免组织结构长期堆积。
+- 只有明确存在长期协作需求时才 `promote`；这是单向升级。
+- `disband` 会移除团队组织与仓库。用户已明确要求时可直接执行；否则先用 `get` 展示目标并确认，避免解散错团队。

-// 移除成员
-ManageTeam({ action: 'remove_member', teamId: '...', agentId: 'old-agent' })
+### 6. 团队仓库与远程同步

-// 批量移除成员
-ManageTeam({ action: 'remove_members', teamId: '...', members: ['agent-a', 'agent-b'] })
+团队目录是 Git 仓库，包含 `team.json`、成员锁和 `shared/rules.md` 等治理文件。

-// 更换组长
-ManageTeam({ action: 'set_supervisor', teamId: '...', agentId: 'new-leader' })
-```
+本地 Git 操作：

-### 团队生命周期
+1. 用 `get` 取得仓库绝对路径；
+2. 用 Bash 在该目录执行 `status/log/diff/add/commit/tag`；
+3. 本地提交完成后，再调用 `ManageTeam(action="push")`。

-```
-// 任务完成，解散临时团队
-ManageTeam({ action: 'disband', teamId: '...' })
+远程 `fork_team/push/pull` 必须走 `ManageTeam`，原因是工具会执行团队 Schema、名册一致性、核心智能体组长禁令、工作区类型和越界符号链接校验，并进入审批闸门。不要用裸 `git push/pull` 绕过这些治理步骤；这条规则不是基于“Agent 一定拿不到凭据”的假设。

-// 或升级为持久团队（长期使用）
-ManageTeam({ action: 'promote', teamId: '...' })
-```
+- `push/pull` 要求团队已在客户端连接远程仓库；未连接时请让用户在团队设置中完成连接或发布。
+- `create` 和 `fork_team` 得到的本地团队默认都不继承可直接推送的远程配置。
+- `fork_team` 默认 `installMembers=true`；本机已偏离锁定版本的同名 Agent 会被跳过保护，不会覆盖。
+- `pull` 可能覆盖本地团队配置；先查看本地状态并说明审批卡中的目标远程。

-## 最佳实践
+### 7. 分派与收尾

-1. **先评估再创建团队**：简单任务直接 Delegate，不要过度组织
-2. **成员精简**：只拉入真正需要的专家，避免信息过载
-3. **优先团队内成员**：在团队中优先委派给团队内成员。如需团队外专家的一次性意见，可临时 Delegate 咨询而无需加入团队；若反复需要，则用 add_member 正式拉入
-4. **明确任务描述**：分派时给出清晰的任务描述和背景信息
-5. **及时汇总**：收到成员结果后及时汇总，不要让用户等待
-6. **动态调整**：发现缺少某领域专家时，用 add_member 补充
-7. **用完即散**：临时团队任务完成后及时解散，保持组织整洁
-8. **组长唯一**：一个 Agent 只担任一个团队的组长，避免职责分散导致管理混乱
+创建团队后，用 `Delegate` 向组长或成员分派任务：
+
+- 单成员：`Delegate(target=..., mode="sync" | "async", teamId=...)`；
+- 多成员：`Delegate(targets=[...], mode="fan-out", teamId=...)`；
+- 需要持续协作时优先团队内成员，一次性外部意见无需先入队。
+
+完成后向用户报告：团队名称与 ID、类型、组长和成员、工作目录模式、发生的组织变更，以及远程动作是否完成。不要暴露凭据或带 token 的远程 URL。
+
+### 8. 失败恢复
+
+- `Agent 不存在`：核对 ID；先创建或安装 Agent，再重试团队操作。
+- `核心智能体不能担任组长`：显式指定普通 Agent 为 `supervisor`。
+- `组长已管理其他团队`：先为原团队执行 `set_supervisor`，再重试。
+- `未配置远程`：让用户在客户端团队设置中连接远程，不要猜测隐藏 API。
+- `本地内容已变化/存在冲突`：先用 `get` 获取目录并检查 Git 状态，保留用户改动后再决定提交、拉取或重试。
+- Skill 缺失或禁用时，仍可根据 `ManageTeam` 的 action、参数 Schema 和错误提示执行最小操作，不要因此绕过工具直接修改 AgentFS。