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 18:43:51 +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.md
+++ b/skills/manage-teams/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: manage-teams
-description: 创建和管理 Agent 团队，组织多 Agent 协作。Use when 需要多个 Agent 围绕同一任务协作、需要建立组织架构、或需要组长统一调度分派任务时。
-version: 1.2.3
+description: 创建和管理 Agent 团队，组织多 Agent 协作。Use when 需要多个 Agent 持续协作、建立组织架构，或发布、安装和同步团队仓库时。
+version: 1.3.0
 type: procedural
 risk_level: medium
 status: enabled
@@ -12,7 +12,7 @@ tags:
  - organization
 metadata:
  author: desirecore
-  updated_at: '2026-05-04'
+  updated_at: '2026-08-25'
  i18n:
    default_locale: en-US
    source_locale: zh-CN
@@ -23,19 +23,18 @@ metadata:
      name: 团队管理
      short_desc: 创建团队、管理成员、组织多 Agent 协作
      description: >-
-        创建和管理 Agent 团队，组织多 Agent 协作。Use when 需要多个 Agent 围绕同一任务协作、需要建立组织架构、或需要组长统一调度分派任务时。
+        创建和管理 Agent 团队，组织多 Agent 协作。Use when 需要多个 Agent 持续协作、建立组织架构，或发布、安装和同步团队仓库时。
      body: ./SKILL.zh-CN.md
-      source_hash: sha256:2aad4d237ca4bc7a
+      source_hash: sha256:d781d4d2d18667aa
      translated_by: human
    en-US:
      name: Team Management
      short_desc: Create teams, manage members, and organize multi-Agent collaboration
      description: >-
-        Create and manage Agent teams to organize multi-Agent collaboration. Use when multiple Agents need to collaborate on the same task, when organizational structure is required, or when a team leader needs to orchestrate and dispatch tasks.
+        Create and govern Agent teams. Use when multiple Agents need sustained collaboration, an organizational hierarchy, or a team repository must be published, installed, or synchronized.
      body: ./SKILL.md
-      source_hash: sha256:2aad4d237ca4bc7a
-      translated_by: ai:claude-opus-4-7
-      translated_at: '2026-05-03'
+      source_hash: sha256:d781d4d2d18667aa
+      translated_by: human
 market:
  icon: >-
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
@@ -55,140 +54,165 @@ market:
    fill-opacity="0.7"/><circle cx="21.5" cy="4" r="0.9" fill="#34C759"
    fill-opacity="0.7"/></svg>
  category: productivity
+  required_client_version: 10.0.108
 ---

 # manage-teams Skill

 ## L0: One-line Summary

-Create and manage Agent teams to organize multiple Agents collaborating around a shared task.
+Use `ManageTeam` to inspect, create, and govern Agent teams, with the required checks before organizational changes or remote synchronization.

-## L1: Overview and Use Cases
+## L1: When to Use

-### Capability Description
+Use a team when:

-manage-teams is a **Procedural Skill** that gives DesireCore the ability to create and manage Agent teams. A team is an organizational unit in which multiple Agents collaborate around a shared task; each team has a supervisor responsible for receiving requirements, decomposing tasks, dispatching work to members, and consolidating results.
+- multiple Agents need sustained collaboration around one task and a shared team workdir;
+- a stable supervisor, membership, or parent-child organizational structure is required;
+- a team repository must be published, installed, or synchronized.

-### Use Cases
+Do not create a team when:

- Multiple Agents need to collaborate continuously on the same task (e.g., a project group)
- An organizational hierarchy is required (departments / team levels)
- A supervisor is needed to centrally orchestrate, decompose, and dispatch tasks
- Simple one-off delegation is insufficient and long-term collaboration with shared context is required
+- one expert is needed once: use `Delegate(mode="sync" | "async")`;
+- several experts only need to provide one-off opinions: use `Delegate(mode="fan-out")`;
+- the work is temporary file exploration: use a Worker instead of creating a lasting organization.

-### Core Value
+A team defines organization, shared directories, and governance. Actual work is still dispatched to members with `Delegate`.

- **Organized collaboration**: upgrade from point-to-point delegation to a team collaboration model
- **Flexible management**: supports both ephemeral and persistent team modes
- **Dynamic adjustment**: members can be added/removed and supervisors swapped at runtime
+## L2: Execution Specification

-## L2: Detailed Specification
+### 1. Inspect Before Mutating

-## Core Concepts
+- If `teamId` is unknown, call `ManageTeam(action="list")` first.
+- Before modifying, disbanding, or synchronizing a team, call `ManageTeam(action="get", teamId=...)` and verify its name, type, supervisor, members, local repository directory, and remote state.
+- Never guess a path under `~/.desirecore`; use only the absolute repository path returned by `get`.
+- `list` can filter by `parentTeamId`. With `tree=true`, `teamId` selects the subtree root and `parentTeamId` is ignored.

-### Teams vs. Single-point Delegation
+### 2. Action Reference

-| Scenario | Recommended Approach | Rationale |
-|------|---------|------|
-| One-off simple problem | `Delegate(target, mode='sync')` | No need for organizational overhead |
-| Need a single expert to handle | `Delegate(target, mode='sync/async')` | One-to-one is sufficient |
-| Need multiple experts to weigh in | `Delegate(targets, mode='fan-out')` | Parallel dispatch without creating a team |
-| Continuous collaboration + shared context | **Create a team** | Teams provide a shared workdir and structure |
-| Organizational hierarchy management | **Create nested teams** | Department / team hierarchy relationships |
+| action | Purpose | Key parameters and notes |
+|---|---|---|
+| `list` | List teams or an organization tree | `parentTeamId?`, `tree?`, `teamId?` |
+| `get` | Inspect one team and its repository path | `teamId` |
+| `create` | Create an ephemeral team | `name` or `task`; `supervisor?`, `members?`, `memberRouting?`, `parentTeamId?`, `workdirMode?` |
+| `add_member` | Add one member | `teamId`, `agentId` |
+| `add_members` | Add members in a batch | `teamId`, `members` |
+| `remove_member` | Remove one member | `teamId`, `agentId` |
+| `remove_members` | Remove members in a batch | `teamId`, `members` |
+| `set_supervisor` | Replace the supervisor | `teamId`, `agentId` |
+| `update` | Partially update team configuration | `teamId`; supports `name/type/isolation/parentTeamId/description/avatar/avatarImage` |
+| `promote` | Promote an ephemeral team to persistent | `teamId`; one-way and never implicit |
+| `disband` | Disband a team | `teamId`; explain impact and confirm unless explicitly requested |
+| `fork_team` | Install a team from a remote repository | `url`; `name?`, `installMembers?`; enters approval |
+| `push` | Push a local team to its connected remote | `teamId`; enters approval |
+| `pull` | Pull and validate a team from its connected remote | `teamId`; enters approval |

-### Team Types
+### 3. Create a Team

- **Ephemeral team**: task-driven, can be disbanded after completion. Suitable for project-based collaboration.
- **Persistent team**: long-lived, suitable for departments / teams. Ephemeral teams can be promoted to persistent.
+Before creation:

-### Supervisor Uniqueness Constraint
+1. Every Agent in `supervisor` and `members` must already exist. Verify IDs with `ManageAgent(action="list" | "get")`; create or install a missing Agent through its corresponding Agent Skill before creating the team.
+2. The DesireCore core Agent, `desirecore`, cannot be a supervisor. When the core Agent initiates creation, it must explicitly choose a regular Agent as `supervisor`.
+3. Normally do not add `desirecore` as a member. Reach core capabilities through `Delegate` instead.
+4. One Agent may supervise only one team. If the intended supervisor already leads another team, assign a successor there first.

-**An Agent can only serve as the supervisor (TL) of a single team.** This is a hard constraint of the organizational structure:
+Choose the workdir mode deliberately:

- When creating a team, if the caller is already a supervisor of another team, they must first step down from the original team (use `set_supervisor` to designate a successor) before creating the new team
- Do not assign an Agent who already serves as supervisor to be the supervisor of another team
- An Agent can simultaneously be the supervisor of one team and a regular member of another, but cannot be supervisor of two teams at once
+- `merged` (default): the shared team directory is primary while member and global workdirs remain available;
+- `team_only`: exposes only the shared team directory, for high-reliability work where every member must operate on the same project. It does not delete member workdir configuration.

-### Supervisor Responsibilities
+Use `memberRouting` to express routing intent without pinning a Provider or model:

-1. Receive user requirements and analyze task complexity
-2. Decompose subtasks and decide which members are needed
-3. Use the `Delegate` tool to dispatch tasks (single-point or fan-out)
-4. Consolidate results from members and produce an integrated answer
-5. Dynamically adjust members (add/remove) as needed
-
-## Operations Guide
-
-### Create a Team
-
-```
-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"
+  }
+}
 ```

-The supervisor defaults to the caller (you). After creation, you are the supervisor of this team.
+- keys must belong to the selected `supervisor` or `members`;
+- Agents using a fixed model must not appear in `memberRouting`;
+- omitted Smart members retain their current routing profile; the concrete Provider/model is resolved when that member executes work.

-### Dispatch Tasks to Team Members
+Example:

-**Single-point delegation** (one member handles it):
-```
-Delegate({
-  target: 'legal-advisor',
-  task: '检查该房产的产权状况和法律风险',
-  mode: 'sync'
-})
+```json
+{
+  "action": "create",
+  "name": "Contract Review Project",
+  "supervisor": "legal-lead",
+  "members": ["contract-reviewer", "risk-analyst"],
+  "task": "Review contracts continuously and consolidate risks",
+  "workdirMode": "team_only"
+}
 ```

-**Fan-out delegation** (multiple members in parallel):
-```
-Delegate({
-  targets: ['legal-advisor', 'finance-advisor', 'real-estate'],
-  task: '从各自专业角度评估这套房产',
-  mode: 'fan-out',
-  strategy: 'parallel'
-})
+### 4. Change Organization and Configuration
+
+- Prefer batch member actions to avoid observable intermediate states.
+- `set_supervisor` uses `agentId`; first verify that the Agent does not already supervise another team.
+- `update` is a patch: omitted fields remain unchanged.
+- `parentTeamId: null` detaches the team and makes it top-level; an empty string is invalid.
+- `type` only allows `ephemeral → persistent`. Repeating the current value is idempotent; use `promote` for an explicit upgrade.
+- `isolation`: `soft` uses shared session isolation; `hard` uses independent Agent copies.
+- `description` is the marketplace-facing team description, not the `task` supplied at creation.
+
+Use a declared avatar with:
+
+```json
+{
+  "action": "update",
+  "teamId": "team-id",
+  "avatar": { "char": "CR", "color": "purple" }
+}
 ```

-### Manage Members
+For an image avatar, use `avatarImage.source` with `dc-media://<mediaId>`, a bare `mediaId`, or an image path inside the workdir. PNG/JPEG/WebP are supported. Do not pass an HTTP(S) URL or base64. Remove the image with `{ "remove": true }`; `remove` and `source` are mutually exclusive.

-```
-// 添加成员
-ManageTeam({ action: 'add_member', teamId: '...', agentId: 'new-agent' })
+### 5. Team Lifecycle

-// 批量添加成员
-ManageTeam({ action: 'add_members', teamId: '...', members: ['agent-a', 'agent-b'] })
+- Disband an ephemeral team after its project is complete so the organization does not accumulate stale teams.
+- Use `promote` only for an explicit long-term collaboration requirement; promotion is one-way.
+- `disband` removes the team organization and repository. Execute directly when the user explicitly requested it; otherwise show the `get` result and confirm the intended target first.

-// 移除成员
-ManageTeam({ action: 'remove_member', teamId: '...', agentId: 'old-agent' })
+### 6. Team Repository and Remote Synchronization

-// 批量移除成员
-ManageTeam({ action: 'remove_members', teamId: '...', members: ['agent-a', 'agent-b'] })
+The team directory is a Git repository containing governance data such as `team.json`, member locks, and `shared/rules.md`.

-// 更换组长
-ManageTeam({ action: 'set_supervisor', teamId: '...', agentId: 'new-leader' })
-```
+For local Git work:

-### Team Lifecycle
+1. obtain the absolute repository path with `get`;
+2. run `status/log/diff/add/commit/tag` with Bash in that directory;
+3. after the local commit is complete, call `ManageTeam(action="push")`.

-```
-// 任务完成，解散临时团队
-ManageTeam({ action: 'disband', teamId: '...' })
+Remote `fork_team/push/pull` must go through `ManageTeam` because it enforces team Schema validation, roster consistency, the core-Agent supervisor prohibition, workspace types, out-of-bounds symlink checks, and approval. Do not bypass those controls with raw `git push/pull`. This rule is not based on an assumption that Agents can never access credentials.

-// 或升级为持久团队（长期使用）
-ManageTeam({ action: 'promote', teamId: '...' })
-```
+- `push/pull` require a remote connected through the client. If none is configured, ask the user to connect or publish the team in team settings.
+- Locally created and forked teams do not inherit a directly pushable remote configuration by default.
+- `fork_team` defaults to `installMembers=true`; a same-ID local Agent that has diverged from its lock is protected and skipped rather than overwritten.
+- `pull` may replace local team configuration. Inspect local state first and identify the target remote in the approval card.

-## Best Practices
+### 7. Dispatch and Finish

-1. **Evaluate before creating a team**: simple tasks should be delegated directly without over-organizing
-2. **Keep membership lean**: only bring in the experts truly needed to avoid information overload
-3. **Prefer in-team members**: within a team, prefer delegating to its members. For one-off opinions from outside experts, ad-hoc `Delegate` consultation is fine without joining the team; if needed repeatedly, formally bring them in via `add_member`
-4. **Clear task descriptions**: provide a clear task description and background information when dispatching
-5. **Consolidate promptly**: synthesize member results promptly — do not keep the user waiting
-6. **Adjust dynamically**: when missing a domain expert, supplement with `add_member`
-7. **Disband after use**: disband ephemeral teams promptly when their task is done to keep the organization tidy
-8. **One supervisor per Agent**: an Agent should only serve as supervisor of one team to avoid management chaos from divided responsibilities
+After team creation, dispatch work to the supervisor or members with `Delegate`:
+
+- one member: `Delegate(target=..., mode="sync" | "async", teamId=...)`;
+- several members: `Delegate(targets=[...], mode="fan-out", teamId=...)`;
+- prefer team members for sustained collaboration; a one-off outside opinion does not require membership.
+
+Report the team name and ID, type, supervisor and members, workdir mode, organizational changes, and whether remote operations completed. Never expose credentials or a remote URL containing a token.
+
+### 8. Failure Recovery
+
+- `Agent does not exist`: verify the ID; create or install the Agent, then retry.
+- `Core Agent cannot supervise`: explicitly choose a regular Agent as `supervisor`.
+- `Supervisor already leads another team`: run `set_supervisor` on the existing team before retrying.
+- `Remote not configured`: ask the user to connect a remote in client team settings; do not guess a hidden API.
+- Local content changed or conflicts exist: obtain the directory with `get`, inspect Git state, preserve user changes, and only then decide whether to commit, pull, or retry.
+- If this Skill is missing or disabled, the minimal operation may still be executed from the `ManageTeam` action/parameter Schema and tool error messages. Never bypass the tool by editing AgentFS directly.
--- 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。