From 2891f9dc063cc290c4dd244984c7e5ac501dc2e2 Mon Sep 17 00:00:00 2001 From: Yige Date: Tue, 25 Aug 2026 18:32:03 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E8=A1=A5=E5=85=A8=E5=9B=A2?= =?UTF-8?q?=E9=98=9F=E7=AE=A1=E7=90=86=E6=93=8D=E4=BD=9C=E8=A7=84=E8=8C=83?= =?UTF-8?q?=20(#92)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 中文 ### 变更 - 将 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 --- skills/manage-teams/SKILL.md | 232 ++++++++++++++++------------- skills/manage-teams/SKILL.zh-CN.md | 214 ++++++++++++++------------ 2 files changed, 247 insertions(+), 199 deletions(-) diff --git a/skills/manage-teams/SKILL.md b/skills/manage-teams/SKILL.md index 360c801..9efb4c1 100644 --- 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: >- 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://`, 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. diff --git a/skills/manage-teams/SKILL.zh-CN.md b/skills/manage-teams/SKILL.zh-CN.md index ed1681b..32da4a1 100644 --- 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` 或工作目录内图片路径。支持 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。