feat(manage-teams): expose complete team repository operations (#210)

团队仓库能力补齐后，manage-teams 的原有说明仍要求用户在 UI 配置远程，并缺少安装、升级与发布重试入口。同步中英文动作和流程、修正 set_member_source 自动解析语义，将技能增版为 1.4.0；最低客户端 10.0.178，旧客户端不应加载新增动作。 Updates the bilingual manage-teams contract for all team repository actions, remote destination configuration, exact release tags and same-version retries, complete archiving and protected member updates. Bumps the Skill to 1.4.0 with a 10.0.178 client floor so older tool ABIs cannot load the new actions. Validation: i18n/schema/catalog checks passed with 105 pre-existing governance/provenance warnings; reviewed human translations and refreshed their source hash. New content uses generic roles and examples. No customer, tenant, credential or runtime fixture data is introduced. Related: desirecore/desirecore#1490. Client implementation: https://github.com/desirecore/desirecore/pull/4362. Do not infer release availability from this Skill PR. The authorized alternative pre-publication check passed: full working tree including hidden files, changed paths, branch and commit metadata, and this PR text were scanned for credential shapes and manually reviewed for customer-neutral content. No private token list was supplied or recorded.
2026-10-21 06:24:08 +08:00 · 2026-10-06 09:44:51 -07:00
parent 362f800bd2
commit 8f6aa67c96
3 changed files with 48 additions and 18 deletions
--- a/skills/manage-teams/SKILL.md
+++ b/skills/manage-teams/SKILL.md
@@ -2,7 +2,7 @@
 license: "MIT"
 name: manage-teams
 description: 创建和管理 Agent 团队，组织多 Agent 协作。Use when 需要多个 Agent 持续协作、建立组织架构，或发布、安装和同步团队仓库时。
-version: 1.3.0
+version: 1.4.0
 type: procedural
 risk_level: medium
 status: enabled
@@ -13,7 +13,7 @@ tags:
  - organization
 metadata:
  author: desirecore
-  updated_at: '2026-08-25'
+  updated_at: '2026-10-06'
  i18n:
    default_locale: en-US
    source_locale: zh-CN
@@ -26,7 +26,7 @@ metadata:
      description: >-
        创建和管理 Agent 团队，组织多 Agent 协作。Use when 需要多个 Agent 持续协作、建立组织架构，或发布、安装和同步团队仓库时。
      body: ./SKILL.zh-CN.md
-      source_hash: sha256:f6d361c54642cb4d
+      source_hash: sha256:778c6fb42f550a02
      translated_by: human
    en-US:
      name: Team Management
@@ -34,7 +34,7 @@ metadata:
      description: >-
        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:f6d361c54642cb4d
+      source_hash: sha256:778c6fb42f550a02
      translated_by: human
 market:
  icon: >-
@@ -55,7 +55,7 @@ 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
+  required_client_version: 10.0.178
 ---

 # manage-teams Skill
@@ -104,10 +104,15 @@ A team defines organization, shared directories, and governance. Actual work is
 | `set_member_source` | Declare where a member Agent comes from | `teamId`, `agentId`, `memberSource`; `git` needs `url` (https, will be cloned) and `ref` (defaults to `main`), `registry` needs `id`+`version`, `core`/`local` need nothing else |
 | `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 |
+| `disband` | Disband a team | `teamId`; enters approval; preserves a full archive, requiring workdir binding and content review on restore |
 | `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 |
+| `add_remote` | Configure or replace a publishing destination | `teamId`, `url`; optional `connectionId`, `branch`, `isPrivate`; does not create a repository |
+| `remove_remote` | Remove remote configuration and the local connection binding | `teamId`; leaves the remote repository intact |
+| `install_members` | Install or repair members from the existing lock | `teamId`; optional `forceUpdate`, default false |
+| `upgrade_members` | Resolve a new lock and attempt safe updates | `teamId`; optional `forceUpdate`, default true; preserves local edits and commits |
+| `release` | Create a local version or publish one exact version | `teamId`; `push` defaults to false, optional `changelogEntry`, `expectedCommit`; retry with `releaseTag` |

 ### 3. Create a Team

@@ -159,7 +164,7 @@ Example:

 - Prefer batch member actions to avoid observable intermediate states.
 - `set_supervisor` uses `agentId`; first verify that the Agent does not already supervise another team.
- `set_member_source` declares provenance, it does not move files. A team whose roster still contains a `local` member is **not distributable** — `members.lock.json` cannot pin an ID that exists only on this machine, so a fork elsewhere would silently come up short a member. Switch each member to `git` or `registry` before publishing, then `resolve` to write the lock. It cannot change a member's `role`; use `set_supervisor` for that.
+- `set_member_source` declares provenance, it does not move files. A team whose roster still contains a `local` member is **not distributable** — `members.lock.json` cannot pin an ID that exists only on this machine, so a fork elsewhere would silently come up short a member. Switch each member to `git` or `registry` before publishing. The action resolves and writes the lock automatically; inspect its receipt. It cannot change a member's `role`; use `set_supervisor` for that.
 - `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.
@@ -182,7 +187,7 @@ For an image avatar, use `avatarImage.source` with `dc-media://<mediaId>`, a bar

 - 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.
+- `disband` archives the complete team directory and ends its local workdir binding, even without Git initialization. Archive failure preserves the original data and reports failure. The action enters approval; the caller's approval mode determines whether a human card appears. To restore, first check that the team ID is free, then bind the workdir and approve its content again.

 ### 6. Team Repository and Remote Synchronization

@@ -196,11 +201,21 @@ For local Git work:

 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.

- `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.
+- `push/pull` require a remote configuration. Use `add_remote` to configure the destination and an existing connection when needed. Client team settings are also available; the Agent chooses the configuration path.
 - 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.

+Release and member versions:
+
+- `release` defaults to a local version. Set `push=true` for publication; approval identifies the target and version. Only the branch and this exact release tag are pushed, never all tags or private backup/archive refs.
+- Inspect the team with `get`; constrain a new release HEAD with `expectedCommit`. Inspect `tag/version/commitHash` and `branchPushed/tagPushed/pushed` separately.
+- After network failure or an unknown remote outcome, inspect the remote and retry with the returned `releaseTag`; do not create another version. Omit `changelogEntry` on retries.
+- `install_members` follows the exact existing lock. `upgrade_members` resolves declarations and attempts safe updates to new pins. Both preserve local edits and commits, avoid downgrades, and do not approve installed content.
+- `complete=false` or `outdated/diverged/failed/unreachable` means members remain unaligned. Neither `success=true`, skipped counts nor zero failures proves all members were upgraded. Inspect each receipt before choosing repairs.
+- Conflicting pins for an Agent shared by multiple teams do not authorize overwriting a local fork; preserve data and report the conflict.
+- Remote actions, remote-source declarations and destination configuration enter approval. `ask-external` retains approval for them; `allow-all` respects the user's full trust in the acting Agent.
+
 ### 7. Dispatch and Finish

 After team creation, dispatch work to the supervisor or members with `Delegate`:
@@ -216,6 +231,6 @@ Report the team name and ID, type, supervisor and members, workdir mode, organiz
 - `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.
+- `Remote not configured`: use `add_remote` to configure the destination, or use 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
@@ -46,10 +46,15 @@
 | `set_member_source` | 声明成员 Agent 的来源 | `teamId`、`agentId`、`memberSource`；`git` 必填 `url`（https，将被 clone）与 `ref`（默认 `main`），`registry` 必填 `id`+`version`，`core`/`local` 无附加字段 |
 | `update` | 部分更新团队配置 | `teamId`；可更新 `name/type/isolation/parentTeamId/description/avatar/avatarImage` |
 | `promote` | 临时团队升级为持久团队 | `teamId`；单向操作，不得隐式执行 |
-| `disband` | 解散团队 | `teamId`；若用户未明确要求，先说明影响并确认 |
+| `disband` | 解散团队 | `teamId`；提交审批；完整归档，恢复需重新绑定目录和核准内容 |
 | `fork_team` | 从远程仓库安装团队 | `url`；`name?`、`installMembers?`；进入审批闸门 |
 | `push` | 把本地团队仓库推送到已连接的远程 | `teamId`；进入审批闸门 |
 | `pull` | 从已连接的远程拉取并校验团队 | `teamId`；进入审批闸门 |
+| `add_remote` | 配置或更换发布目标 | `teamId`、`url`；`connectionId?`、`branch?`、`isPrivate?`；不创建远程仓库 |
+| `remove_remote` | 移除远程配置与本机连接绑定 | `teamId`；不删除远程仓库 |
+| `install_members` | 按现有 lock 补齐成员 | `teamId`；`forceUpdate?`，默认 false |
+| `upgrade_members` | 解析新 lock 并尝试安全升级 | `teamId`；`forceUpdate?`，默认 true；保留本机修改和提交 |
+| `release` | 创建本地版本或发布精确版本 | `teamId`；`push?` 默认 false、`changelogEntry?`、`expectedCommit?`；重试已有版本用 `releaseTag` |

 ### 3. 创建团队

@@ -101,7 +106,7 @@

 - 成员增删优先使用批量 action，避免多次调用产生中间状态。
 - `set_supervisor` 使用 `agentId` 指定新组长；先确认其未担任其他团队组长。
- `set_member_source` 声明来源，不搬运文件。名册里只要还留着 `local` 成员，团队就**不可分发**——`members.lock.json` 无法锁定一个只存在于本机的 ID，别处 fork 出来会静默缺员。发布前把每个成员改为 `git` 或 `registry`，再 `resolve` 写锁。它改不了成员的 `role`，换组长用 `set_supervisor`。
+- `set_member_source` 声明来源，不搬运文件。名册里只要还留着 `local` 成员，团队就**不可分发**——`members.lock.json` 无法锁定一个只存在于本机的 ID，别处 fork 出来会静默缺员。发布前把每个成员改为 `git` 或 `registry`；该动作会自动解析并写 lock，核对解析回执即可。它改不了成员的 `role`，换组长用 `set_supervisor`。
 - `update` 是部分更新：未传字段保持原值。
 - `parentTeamId: null` 表示摘除父团队成为顶层团队；空字符串非法。
 - `type` 只允许 `ephemeral → persistent`。原值幂等更新可以接受；明确升级优先使用 `promote`。
@@ -124,7 +129,7 @@

 - 临时团队完成一次项目后应解散，避免组织结构长期堆积。
 - 只有明确存在长期协作需求时才 `promote`；这是单向升级。
- `disband` 会移除团队组织与仓库。用户已明确要求时可直接执行；否则先用 `get` 展示目标并确认，避免解散错团队。
+- `disband` 完整归档团队目录并结束本机工作目录绑定；不依赖 Git 初始化。归档失败保留原数据并报告失败。该动作提交审批，是否显示真人卡片由调用方的审批模式决定。恢复时先确认 teamId 未被占用，再绑定工作目录、重新核准内容。

 ### 6. 团队仓库与远程同步

@@ -138,11 +143,21 @@

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

- `push/pull` 要求团队已在客户端连接远程仓库；未连接时请让用户在团队设置中完成连接或发布。
+- `push/pull` 要求已有远程配置；未连接时使用 `add_remote` 配置目标和已有连接。客户端团队设置也是可选入口。Agent 可以自主选择配置方式。
 - `create` 和 `fork_team` 得到的本地团队默认都不继承可直接推送的远程配置。
 - `fork_team` 默认 `installMembers=true`；本机已偏离锁定版本的同名 Agent 会被跳过保护，不会覆盖。
 - `pull` 可能覆盖本地团队配置；先查看本地状态并说明审批卡中的目标远程。

+发布与成员版本：
+
+- `release` 默认只创建本地版本；明确要对外发布时传 `push=true`。审批摘要显示实际目标和版本，只推分支及本次正式 tag，不推 `backup/`、`archive/` 或其他 tag。
+- 先用 `get` 核对团队；新版本可传 `expectedCommit` 约束 HEAD。返回 `tag/version/commitHash` 与 `branchPushed/tagPushed/pushed`，本地成功和远端发布分别核验。
+- 网络失败或远端结果未知时，先检查远端；用返回的 `releaseTag` 重试同一版本，不再次运行无 tag 的 release。重试时不得传 `changelogEntry`。
+- `install_members` 按精确 lock 安装；`upgrade_members` 先解析当前声明，再按新 pin 尝试安全更新。它们不覆盖用户修改、本机提交，不自动回退，也不自动核准内容。
+- `complete=false` 或成员 `outdated/diverged/failed/unreachable` 表示未对齐；不要把 `success=true`、`skippedCount` 或 `failedCount=0` 当成全员升级完成。读取逐成员回执，确认后选择修复方法。
+- 同一 Agent 在多个团队有不同 pin 时，不自动覆盖现有分叉；保留数据并报告冲突。
+- 远程动作、远程来源声明和远程目标配置提交审批；`ask-external` 对这些动作保留审批，`allow-all` 保留用户对执行主体的全量信任。
+
 ### 7. 分派与收尾

 创建团队后，用 `Delegate` 向组长或成员分派任务：
@@ -158,6 +173,6 @@
 - `Agent 不存在`：核对 ID；先创建或安装 Agent，再重试团队操作。
 - `核心智能体不能担任组长`：显式指定普通 Agent 为 `supervisor`。
 - `组长已管理其他团队`：先为原团队执行 `set_supervisor`，再重试。
- `未配置远程`：让用户在客户端团队设置中连接远程，不要猜测隐藏 API。
+- `未配置远程`：调用 `add_remote` 配置目标，或使用客户端团队设置；不要猜测隐藏 API。
 - `本地内容已变化/存在冲突`：先用 `get` 获取目录并检查 Git 状态，保留用户改动后再决定提交、拉取或重试。
 - Skill 缺失或禁用时，仍可根据 `ManageTeam` 的 action、参数 Schema 和错误提示执行最小操作，不要因此绕过工具直接修改 AgentFS。
--- a/skills/manage-teams/catalog-metadata.v1.json
+++ b/skills/manage-teams/catalog-metadata.v1.json
@@ -28,13 +28,13 @@
  },
  "release": {
    "state": "known",
-    "version": "1.3.0",
+    "version": "1.4.0",
    "versionScheme": "semver"
  },
  "timestamps": {
    "catalogUpdatedAt": {
      "state": "known",
-      "value": "2026-08-25T10:32:03Z",
+      "value": "2026-10-06T13:00:00Z",
      "precision": "second"
    },
    "releasePublishedAt": {
@@ -65,7 +65,7 @@
    "platforms": {
      "state": "unknown"
    },
-    "requiredClientVersion": "10.0.108"
+    "requiredClientVersion": "10.0.178"
  },
  "spec": {
    "kind": "skill",