From bae76c8b9a55bd31beb0ac90ee6e26a3e82ff0d4 Mon Sep 17 00:00:00 2001
From: yi-ge <a@wyr.me>
Date: Sun, 17 May 2026 17:19:28 +0800
Subject: [PATCH 1/2] docs: add Team Version Management chapter (zh + en)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New chapter explains how a whole team can be versioned, pushed to
GitHub/Gitee, released to the community, and one-click installed from
someone else's link — written in the same mentor-style, customer-facing
voice as the existing single-Agent Version Control chapter.

Changes:
- New docs/02-user-guide/06-agents/09-team-version-management.md (zh-Hans, main source)
- New i18n/en/.../09-team-version-management.md (English mirror)
- 08-version-control.md "Next steps" links to the new chapter (zh + en)
- Glossary adds 3 entries: Team Version Management / Team Member Lock / Team Release (zh + en)

Covers, in plain-language customer voice:
- Why a team needs versioning
- Two-layer model (team-level vs member-level)
- 4 member sources (local / git / marketplace / built-in core)
- Connecting a remote repo (GitHub/Gitee)
- Viewing history, push/pull, upgrading members, releasing a new version
- Installing from someone's link (forking)
- Disband-as-archive (recoverable)
- 5 common scenarios

Build verified: pnpm build passes for both zh-Hans and en locales,
no broken links. Related to desirecore PR #656.
---
 .../06-agents/08-version-control.md           |   1 +
 .../06-agents/09-team-version-management.md   | 235 ++++++++++++++++++
 docs/05-more/03-glossary.md                   |   9 +
 .../06-agents/08-version-control.md           |   1 +
 .../06-agents/09-team-version-management.md   | 235 ++++++++++++++++++
 .../current/05-more/03-glossary.md            |   9 +
 6 files changed, 490 insertions(+)
 create mode 100644 docs/02-user-guide/06-agents/09-team-version-management.md
 create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md

diff --git a/docs/02-user-guide/06-agents/08-version-control.md b/docs/02-user-guide/06-agents/08-version-control.md
index e7586ce..4d4142f 100644
--- a/docs/02-user-guide/06-agents/08-version-control.md
+++ b/docs/02-user-guide/06-agents/08-version-control.md
@@ -113,5 +113,6 @@ DesireCore 中的每个智能体都是一个 Git 仓库。你对智能体的每
 
 ## 下一步
 
+- [团队版本管理](./09-team-version-management.md) — 把整支智能体团队当作一个整体进行版本管理
 - [智能体类型](./01-agent-types.md) — 回顾智能体的类型和定位
 - [创建自定义智能体](./03-create-agent.md) — 创建你自己的智能体
diff --git a/docs/02-user-guide/06-agents/09-team-version-management.md b/docs/02-user-guide/06-agents/09-team-version-management.md
new file mode 100644
index 0000000..b8835b2
--- /dev/null
+++ b/docs/02-user-guide/06-agents/09-team-version-management.md
@@ -0,0 +1,235 @@
+---
+title: 团队版本管理
+description: 把整支智能体团队当作一个整体进行版本管理——记录组织变化、同步到 GitHub/Gitee、发布到社区或从他人的链接一键安装。
+keywords: [团队版本管理, 团队协作, 团队发布, 团队安装, 跨设备同步, 团队 Git]
+---
+
+# 团队版本管理
+
+如果说每个智能体是一位单独的同事,那么一支团队就是一个有自己阵型、规则和共同记忆的小组。当你花了很多时间把这个小组调教好——选好队长、搭好成员、写好共享规则——你会希望把整个小组当作"一份完整的成果"保存下来:能换台电脑接着用、能让朋友一键复刻、能在迭代过程中知道每次改了谁。
+
+这就是团队版本管理要解决的事:**让团队也像智能体一样,具备完整的版本历史、远程同步和分享能力**。
+
+## 团队为什么需要版本管理?
+
+| 你遇到的情况 | 团队版本管理怎么帮你 |
+|---|---|
+| 在笔记本上搭好的团队,想在桌面机继续用 | 推送到 GitHub/Gitee 后,在另一台机器一键拉取,组织架构和共享资源一起到位 |
+| 公司里两个人都在调一支客服团队 | 各自修改后通过推送/拉取合并,谁加了谁、谁换了队长一目了然 |
+| 想把精心搭建的销售团队分享给社区 | 发布一次,任何人贴上链接就能完整安装,包括所有成员智能体 |
+| 不小心把一位关键队长换掉了 | 在版本历史里找到那次更换,回到之前的组织架构 |
+| 看到别人发布的运维团队很不错 | 输入链接,一键 Fork 到自己机器,自由修改不影响原作者 |
+
+## 团队和成员的两层版本管理
+
+DesireCore 用两层结构来管理团队:
+
+| 层级 | 追踪什么 | 谁来维护 |
+|---|---|---|
+| **团队本身** | 谁是队长、谁是成员、共享技能/记忆/规则、团队远程仓库地址 | 团队版本管理(本章) |
+| **每个成员智能体** | 自己的人格、原则、记忆、技能、对话学习 | 每个智能体自己的版本管理(参考[上一章](./08-version-control.md)) |
+
+这意味着团队仓库里**不会嵌入成员智能体的副本**,只保留一份"成员清单"——指向每个成员各自的位置(本地、某个 git 仓库、或市场的某个版本)。这样既能整体打包分享,又不会让一个智能体被两份记录互相覆盖。
+
+:::info 一个比喻
+团队仓库像是乐队的"演出曲目单",列出谁来弹什么、用哪个版本的编曲。每位乐手依然有自己的练习本(成员智能体仓库),曲目单只是引用他们。
+:::
+
+## 团队的四种成员来源
+
+当你把一个智能体加入团队时,系统会记下它"来自哪里"。共有四种来源:
+
+| 来源 | 什么时候用 |
+|---|---|
+| **本机** | 这个智能体只在你自己电脑上,没有上传到 git,也没发布到市场。适合个人练手,但**团队若包含本机成员则不可分发** |
+| **Git 仓库** | 这个智能体已经推送到 GitHub/Gitee 等,有公开或私有的远程地址。最常见的协作和分享形式 |
+| **市场** | 从 DesireCore 市场安装的智能体,带具体版本号 |
+| **内置核心** | DesireCore 自带的核心智能体(`desirecore`),所有人都有,无需上传 |
+
+:::tip 团队要可分享,所有成员都得有"远程出处"
+如果你计划把一支团队发布给他人,先确认每个成员都已经发布或推送到 git。完全本机的智能体别人是装不到的。
+:::
+
+## 配置团队远程仓库
+
+要让团队跨设备同步、或分享给别人,需要先连接一个远程仓库(GitHub、Gitee、Gitea 等)。
+
+1. 进入团队设置,或在队长视角点击右上角"更多"菜单
+2. 选择"连接远程仓库"
+3. 选择已连接的 OAuth 账号(没有的话先在设置中添加 GitHub/Gitee 等账号)
+4. 填写仓库地址和分支名(默认 `main`)
+5. 标注是否为私有仓库
+6. 保存
+
+保存后,系统会自动把团队的当前状态作为一次发布,等你下次推送时同步到远端。
+
+:::tip 没远程也能用版本管理
+即使不连接远程,团队的本地版本历史也照常记录。远程仓库只是给跨设备同步和对外分享加一道"云端备份",不是必需的。
+:::
+
+## 查看团队的修改历史
+
+每次有人加入团队、被移除、被设为队长,或者远程被推送/拉取,系统都会自动留下一条记录。
+
+1. 进入团队设置面板,展开"版本历史"区块;或在队长更多菜单点击"团队版本历史"
+2. 顶部状态卡片显示团队当前同步情况:
+   - **已同步** — 本地和远端一致
+   - **领先 N 个** — 本地有新变化,可以推送
+   - **落后 N 个** — 远端有新变化,需要拉取
+   - **本地与远程分叉** — 双方都改了,需要合并
+3. 下方按时间倒序列出所有修改记录,每条显示:
+   - 做了什么(例如:加入成员 alice、换帅 alice → bob)
+   - 谁做的、什么时候做的
+   - 当时影响了哪些团队文件
+
+每个"自动留下记录"的动作大致是:
+
+| 你的动作 | 记录示例 |
+|---|---|
+| 创建新团队 | 初始化团队仓库 |
+| 添加成员 | 新增成员: alice |
+| 移除成员 | 移除成员: bob |
+| 更换队长 | 修改组织架构: 换帅 alice → bob |
+| 批量添加/移除 | 新增成员批量(N 人) |
+| 配置 / 移除远程 | 修改远程配置 |
+| 升级成员版本 | 升级成员版本 |
+| 发布新版本 | 发布 vX.Y.Z |
+| 解散归档 | 团队归档 |
+
+## 推送和拉取团队
+
+跟单个智能体一样,团队也通过"推送"和"拉取"和远端同步。
+
+- **推送** — 把你这边的变化(加成员、换队长、共享技能更新等)发送到远端
+- **拉取** — 把远端的变化拉到本地
+
+在团队版本历史面板顶部,有"推送"和"拉取"按钮(连了远程仓库后才显示)。
+
+### 遇到冲突怎么办?
+
+如果你这边和别人都改了同一个团队的同一处,拉取时会出现冲突。DesireCore 会优先尝试"以远端为准"自动合并;如果还是合不上,会列出具体冲突的文件,提示手动处理。
+
+:::info 团队冲突通常很轻
+因为团队仓库只记录"清单和共享资源",不包含成员智能体的内容,绝大部分冲突都集中在"成员列表"上——比如两个人各加了一位新成员。系统会取并集自动合并。
+:::
+
+## 升级团队成员到最新版本
+
+当一支团队的某位成员智能体在它自己的仓库里发布了新版本,团队默认还指向旧版本——这是有意为之,**保证团队的可复现性**:你今天发布的团队,半年后别人安装时,装到的还是发布时锁定的那些成员版本,不会因为成员各自升级而变样。
+
+需要把团队同步到成员的最新版本时:
+
+1. 在团队版本历史顶部点击"升级成员"
+2. 系统重新查询每个成员的最新版本
+3. 把团队的"成员清单"更新到新版本,记录一条升级记录
+4. 自动把本机相应的成员智能体也拉到新版本
+
+:::warning 本地已偏离的成员不会被覆盖
+如果你在本机修改过某个成员智能体,系统会标记为"已偏离",升级时**不会自动覆盖你的修改**,只是提醒你存在差异。是否同步由你决定。
+:::
+
+## 发布团队新版本
+
+当团队达到一个稳定状态、可以对外分享或固化里程碑时,可以"发布"一次:
+
+1. 在队长更多菜单点击"发布团队新版本"
+2. 系统自动算出下一个版本号(例如 0.1.0 → 0.1.1)
+3. 系统根据自上次发布以来的修改自动起草一份说明,你可以修改
+4. 勾选"发布后推送到远程"(推荐),让远端也能看到这次发布
+5. 点击"发布 vX.Y.Z" 完成
+
+发布会在团队版本历史里留下一条带版本号的记录,并打一个对应的"版本标签",方便日后回溯到这次发布时的完整状态。
+
+:::tip 发布失败不会让团队进入半成品状态
+如果发布过程中出错(例如打版本标签失败、远端推送失败),系统会自动把团队回滚到发布前的状态,确保版本号和变更日志始终一致。
+:::
+
+## 从其他人的链接安装团队
+
+如果别人发布了一支不错的团队、给你一个 git 链接,你可以一键把它复刻到自己机器:
+
+1. 在团队列表点击"添加团队"→ "从链接安装"
+2. 粘贴对方的团队 git 仓库地址
+3. 可选:给这支团队起个新名字(留空就用原名)
+4. 勾选"同时安装成员智能体"(推荐),系统会自动把团队需要的成员一并拉到本机
+5. 确认 → 等待安装完成
+
+:::tip 安装来的团队是独立副本
+DesireCore 会自动断开和原始作者远程的连接、清空仓库地址。你可以自由修改、自己连接到你自己的远程,完全不影响原作者。这等同于 GitHub 上的 "fork"。
+:::
+
+安装过程中,系统会逐个处理每位成员:
+
+| 状态 | 含义 |
+|---|---|
+| **已安装** | 成员智能体之前不存在,刚从远端下载完成 |
+| **已存在(版本一致)** | 本机已有这个智能体,版本和团队需要的一致,跳过 |
+| **本地版本较旧** | 本机有这个智能体,但版本低于团队需要,**不会覆盖你的本地版本**,只标记提示 |
+| **本地已偏离** | 本机有同 ID 的智能体但内容被你改过,**不会覆盖** |
+| **跳过(核心智能体)** | 是 DesireCore 自带的核心智能体,所有人都有,无需下载 |
+| **无法安装** | 团队需要这个成员,但它没有远程地址(纯本机),你需要联系作者 |
+
+## 解散团队是可恢复的
+
+不想用某支团队时,可以"解散":
+
+1. 在团队设置面板点击"解散团队"
+2. 确认后,系统会:
+   - 在团队版本历史里留下一条解散记录
+   - 打一个"归档标签"
+   - 把整个团队目录移动到归档区(**不是真正删除**)
+
+如果将来后悔了,可以从归档区手动恢复——所有版本历史、共享资源、成员清单都完整保留。
+
+:::info 归档不占主列表
+解散后的团队不会出现在团队列表里,但磁盘上还在。如需彻底清理,需手动删除归档目录。
+:::
+
+## 常见场景
+
+### 场景一:笔记本和桌面机两边都用同一支团队
+
+1. 在笔记本上把团队连到一个 GitHub 私有仓库
+2. 完成搭建后推送一次
+3. 在桌面机上"添加团队 → 从链接安装",粘贴同一个 GitHub 地址
+4. 之后任一台机器修改后,推送/拉取就能保持两边一致
+
+### 场景二:朋友给我一个团队链接,如何安装
+
+1. 拿到链接(形如 `https://github.com/xxx/team-xxx.git`)
+2. "添加团队 → 从链接安装",粘贴链接
+3. 勾选"同时安装成员智能体"
+4. 确认 → 等待完成,所有成员到位,可以立刻开始用
+
+### 场景三:发布一支团队让社区使用
+
+1. 确认所有成员都已经发布到市场或推送到 git(不能含本机来源的成员)
+2. 配置好团队远程仓库
+3. 点击"发布团队新版本",填好版本说明
+4. 把团队的 git 地址分享出去
+
+### 场景四:两个人同时改了团队,如何合并
+
+A 加了 carol,B 加了 dave,各自推送时第二个会被告知"远端先动了"。
+此时第二位:
+
+1. 先拉取——系统会自动合并(并集:含 carol 和 dave)
+2. 再推送
+
+不需要任何手动 git 操作。
+
+### 场景五:发布的新版本有问题,要回到上一版
+
+团队的版本历史里每一次"发布"都打了版本标签。如需回到上一版本:
+
+1. 在版本历史里找到上一个发布标签
+2. 点击"恢复到此版本"
+3. 系统创建一条"回滚"记录,并把团队配置回到那时的状态
+
+成员版本会按那个时间点的清单重新指向,你也可以选择是否同时回滚本机成员智能体。
+
+## 下一步
+
+- [版本管理](./08-version-control.md) — 单个智能体的版本管理
+- [跨智能体协作](../04-delegation/06-cross-agent.md) — 多智能体协作执行
+- [智能任务编排](../../04-concepts/10-task-orchestration.md) — 团队模式 vs 蜂群模式的概念解析
diff --git a/docs/05-more/03-glossary.md b/docs/05-more/03-glossary.md
index 3c5c0ad..1cceb1a 100644
--- a/docs/05-more/03-glossary.md
+++ b/docs/05-more/03-glossary.md
@@ -140,6 +140,15 @@ DesireCore 的协作写作功能。基于 Markdown 编辑器，支持 AI 辅助
 ### Teach（教）
 六原语之一。用户告诉智能体怎么做、为什么这么做、什么情况例外。教学内容会被持久化为行为规范。
 
+### Team Version Management（团队版本管理）
+把整支智能体团队当作一个整体进行版本管理的能力,包括组织变化(加成员/换队长/解散)的自动记录、推送到 GitHub/Gitee 远程仓库、发布团队新版本、从他人链接一键 Fork 安装等。与单个智能体的版本管理是两层独立体系。
+
+### Team Member Lock(团队成员锁定)
+团队对每位成员智能体的精确版本指向。即使成员智能体在自己的仓库里继续迭代,团队默认仍指向锁定的版本,保证别人下次安装时能装到一模一样的组合。需要同步到成员最新版本时,使用"升级成员"操作。
+
+### Team Release(团队发布)
+为团队打一个完整的版本号(例如 v0.1.1)、生成变更日志、并同步到远程。发布后这个版本可以被分享、回退、或作为参考点。
+
 ### Tool（工具）
 智能体可以调用的外部能力。包括内置工具（文件读写、搜索等）、MCP 工具和自定义工具。通过 Tool Registry 统一注册和管理。
 
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md
index f07f2a9..1def910 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/08-version-control.md
@@ -113,5 +113,6 @@ During export, you can select content by category, such as Agents, skills, memor
 
 ## Next Steps
 
+- [Team Version Management](./09-team-version-management.md) - Manage an entire Agent team as a single versioned unit
 - [Agent Types](./01-agent-types.md) - Review Agent types and positioning
 - [Create Custom Agent](./03-create-agent.md) - Create your own Agent
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md
new file mode 100644
index 0000000..1c7758c
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md
@@ -0,0 +1,235 @@
+---
+title: Team Version Management
+description: Manage an entire Agent team as a single versioned unit — track organizational changes, sync to GitHub/Gitee, publish to the community, or install from someone else's link in one click.
+keywords: [Team Version Management, Team Collaboration, Team Publishing, Team Install, Cross-Device Sync, Team Git]
+---
+
+# Team Version Management
+
+If every Agent is a single colleague, a team is a small group with its own formation, rules, and shared memory. Once you've spent time getting that group right — choosing a leader, building out the roster, writing shared principles — you'll want to preserve the whole group as "a finished result": carry it to another machine, let a friend clone it in one click, and know exactly who changed what along the way.
+
+That's what team version management is for: **giving teams the same version history, remote sync, and sharing capabilities that individual Agents already have**.
+
+## Why Teams Need Version Management
+
+| Your situation | How team version management helps |
+|---|---|
+| You built a team on a laptop and want to keep using it on your desktop | Push it to GitHub/Gitee, then pull it on the other machine — organization and shared resources arrive intact |
+| Two people are tuning a customer-support team at work | Each side pushes/pulls to merge — who added whom, who changed the leader, all visible |
+| You want to share a carefully built sales team with the community | Publish once; anyone with the link can install the complete team, including all member Agents |
+| You accidentally replaced a key leader | Find that change in the version history and return to the prior organization |
+| You see someone published a great ops team | Paste their link, fork it to your machine, modify freely without affecting the original author |
+
+## Two Layers: Team and Member
+
+DesireCore manages teams in two layers:
+
+| Layer | What it tracks | Who maintains it |
+|---|---|---|
+| **The team itself** | Who's the leader, who's a member, shared skills/memory/rules, the team's remote repo address | Team version management (this chapter) |
+| **Each member Agent** | Its own persona, principles, memory, skills, learned conversation knowledge | Each Agent's own version management ([previous chapter](./08-version-control.md)) |
+
+This means the team repository **does not embed copies of member Agents**. It only keeps a "roster" pointing to where each member lives (locally, in a git repo, or at a specific marketplace version). This way you can package and share a team as a whole without any Agent ending up duplicated and out of sync.
+
+:::info An analogy
+A team repository is like a band's "setlist" — it lists who plays what and which arrangement to use. Each musician still has their own practice book (the member's Agent repo); the setlist just references them.
+:::
+
+## Four Member Sources
+
+When you add an Agent to a team, the system records where it comes from. Four options:
+
+| Source | When to use |
+|---|---|
+| **Local** | The Agent only exists on your machine — not in a git repo, not in the marketplace. Fine for personal use, but **a team containing local members cannot be shared** |
+| **Git Repo** | The Agent is already pushed to GitHub/Gitee/etc., with a public or private address. The most common collaboration and sharing format |
+| **Marketplace** | An Agent installed from the DesireCore marketplace, with a specific version |
+| **Built-in Core** | DesireCore's built-in core Agent (`desirecore`) — everyone has it, no upload needed |
+
+:::tip For a team to be shareable, every member needs a "remote source"
+If you plan to share a team with others, make sure every member is published or pushed to git first. Purely local Agents can't be installed by anyone else.
+:::
+
+## Connecting a Team Remote Repository
+
+To sync a team across devices or share it with others, first connect a remote repository (GitHub, Gitee, Gitea, etc.).
+
+1. Open team settings, or click "More" in the leader's top-right menu
+2. Choose "Connect Remote Repository"
+3. Pick a connected OAuth account (add GitHub/Gitee accounts in settings first if you don't have one)
+4. Fill in the repository URL and branch name (defaults to `main`)
+5. Mark whether it's a private repository
+6. Save
+
+Once saved, the system commits the team's current state as a snapshot, ready to sync the next time you push.
+
+:::tip You can version-manage without a remote
+Even without a remote, local version history is recorded as usual. A remote just adds cloud backup for cross-device sync and external sharing — it's not required.
+:::
+
+## Viewing Team Modification History
+
+Every time someone joins the team, gets removed, gets promoted to leader, or the team is pushed/pulled, the system automatically leaves a record.
+
+1. Open the team settings panel and expand the "Version History" section; or click "Team Version History" in the leader's More menu
+2. The status card at the top shows the current sync state:
+   - **Synced** — local and remote are identical
+   - **N ahead** — local has new changes, ready to push
+   - **N behind** — remote has new changes, ready to pull
+   - **Diverged** — both sides changed, needs merging
+3. Below is a reverse-chronological list of all modifications, each showing:
+   - What was done (e.g., "added member alice", "changed leader: alice → bob")
+   - Who did it, when
+   - Which team files were affected at the time
+
+Actions that automatically leave a record:
+
+| Your action | Record example |
+|---|---|
+| Create a new team | Initialize team repository |
+| Add member | Add member: alice |
+| Remove member | Remove member: bob |
+| Change leader | Change organization: leader alice → bob |
+| Bulk add/remove | Add members in bulk (N people) |
+| Configure / remove remote | Modify remote configuration |
+| Upgrade member versions | Upgrade member versions |
+| Publish a new version | Release vX.Y.Z |
+| Disband and archive | Archive team |
+
+## Push and Pull a Team
+
+Just like individual Agents, teams sync with the remote via "push" and "pull".
+
+- **Push** — send your local changes (added members, leader changes, shared skill updates, etc.) to the remote
+- **Pull** — bring remote changes down to your local
+
+The "Push" and "Pull" buttons are at the top of the team version history panel (visible only after connecting a remote).
+
+### When conflicts happen
+
+If both you and someone else changed the same part of the same team, pulling will produce a conflict. DesireCore first tries to merge automatically with "prefer remote" strategy; if that still fails, it lists the conflicting files for manual resolution.
+
+:::info Team conflicts are usually mild
+Because the team repository only records "the roster and shared resources" — not the contents of member Agents — most conflicts are around the member list (e.g., two people each added a different member). The system takes the union and merges automatically.
+:::
+
+## Upgrading Team Members to Their Latest Version
+
+When a member Agent in a team gets a new version published in its own repo, the team still points at the old version by default — this is intentional, and **guarantees reproducibility**: the team you publish today will still install the same member versions for someone six months from now, instead of drifting whenever individual members update.
+
+When you want to bring the team in sync with members' latest versions:
+
+1. Click "Upgrade Members" at the top of the team version history
+2. The system re-checks each member's latest version
+3. The team's "roster" updates to the new versions and a record is added
+4. The corresponding member Agents on your machine are also updated
+
+:::warning Locally diverged members are not overwritten
+If you've modified a member Agent on your machine, the system marks it as "diverged" and **won't automatically overwrite your changes** during upgrade. It just flags the difference; whether to sync is up to you.
+:::
+
+## Publishing a New Team Version
+
+When a team reaches a stable state and is ready to share externally or freeze as a milestone, "publish" it:
+
+1. Click "Release New Team Version" in the leader's More menu
+2. The system calculates the next version number automatically (e.g., 0.1.0 → 0.1.1)
+3. The system drafts a changelog based on modifications since the last release; you can edit it
+4. Check "Push to remote after release" (recommended) so the release reaches the remote too
+5. Click "Release vX.Y.Z" to finish
+
+The release leaves a record in the team version history with the version number, and creates a corresponding "version tag" so you can revisit the exact state at release time later.
+
+:::tip A failed release won't leave the team in a half-state
+If something goes wrong during release (e.g., tagging fails or the remote push fails), the system automatically rolls the team back to its pre-release state, keeping the version number and changelog consistent.
+:::
+
+## Installing a Team From Someone Else's Link
+
+If someone published a great team and gave you a git link, you can clone it to your machine in one click:
+
+1. In the team list, click "Add Team" → "Install From Link"
+2. Paste the team's git repository URL
+3. Optional: give the team a new name (leave blank to use the original)
+4. Check "Also install member Agents" (recommended) — the system pulls the team's required members to your machine
+5. Confirm → wait for installation
+
+:::tip Installed teams are independent copies
+DesireCore automatically disconnects the original author's remote and clears the repository address. You can modify freely, connect your own remote, and nothing affects the original author. This is the same idea as a "fork" on GitHub.
+:::
+
+During installation, each member is handled individually:
+
+| Status | Meaning |
+|---|---|
+| **Installed** | The member Agent didn't exist before — just downloaded from the remote |
+| **Already present (matching version)** | The Agent already exists locally at the version the team needs — skipped |
+| **Local version is older** | You have this Agent locally but at a lower version than the team needs. **Your local version is not overwritten**, just flagged |
+| **Locally diverged** | You have the same Agent ID locally but modified its content. **Not overwritten** |
+| **Skipped (core Agent)** | DesireCore's built-in core Agent — everyone has it, no download needed |
+| **Cannot install** | The team needs this member, but it has no remote address (purely local). You'll need to contact the author |
+
+## Disbanding a Team Is Reversible
+
+When you no longer need a team, "disband" it:
+
+1. Click "Disband Team" in the team settings panel
+2. After confirmation, the system:
+   - Leaves a disband record in the team version history
+   - Creates an "archive tag"
+   - Moves the entire team folder to the archive area (**not actually deleted**)
+
+If you change your mind later, you can manually restore it from the archive — all version history, shared resources, and member roster are preserved intact.
+
+:::info Archived teams don't clutter the main list
+A disbanded team disappears from the team list but stays on disk. To permanently clean up, delete the archive folder manually.
+:::
+
+## Common Scenarios
+
+### Scenario 1: Same team on laptop and desktop
+
+1. Connect the team to a private GitHub repo on the laptop
+2. Push once after finishing the setup
+3. On the desktop, "Add Team → Install From Link" with the same GitHub URL
+4. After that, any change on either machine syncs via push/pull
+
+### Scenario 2: A friend sent me a team link — how do I install it?
+
+1. Get the link (something like `https://github.com/xxx/team-xxx.git`)
+2. "Add Team → Install From Link", paste the URL
+3. Check "Also install member Agents"
+4. Confirm → wait — all members arrive, ready to use immediately
+
+### Scenario 3: Publish a team for the community
+
+1. Confirm every member is already published to the marketplace or pushed to git (no local-source members)
+2. Configure the team's remote repository
+3. Click "Release New Team Version", fill in the version notes
+4. Share the team's git URL
+
+### Scenario 4: Two people changed the team at the same time — how to merge?
+
+A added carol, B added dave. When the second person tries to push, they're told "the remote moved first".
+
+The second person:
+
+1. Pull first — the system auto-merges (union: includes both carol and dave)
+2. Push again
+
+No manual git operations required.
+
+### Scenario 5: The new release has a bug — how do I revert?
+
+Every "release" in the team version history has a version tag. To return to the previous version:
+
+1. Find the previous release tag in the version history
+2. Click "Revert to this version"
+3. The system creates a "rollback" record and restores the team configuration to that state
+
+Member versions revert to the roster from that point in time. You can choose whether to roll back the local member Agents too.
+
+## Next Steps
+
+- [Version Control](./08-version-control.md) — Version management for an individual Agent
+- [Cross-Agent Collaboration](../04-delegation/06-cross-agent.md) — How multiple Agents work together
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md
index 4a5f2e2..072e960 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md
@@ -140,6 +140,15 @@ DesireCore's collaborative writing feature. Based on a Markdown editor, supporti
 ### Teach
 One of the Six Primitives. Users tell agents how to do something, why to do it, and what exceptions apply. Teaching content is persisted as behavioral norms.
 
+### Team Version Management
+The ability to manage an entire Agent team as a single versioned unit — automatic recording of organizational changes (add member / change leader / disband), pushing to GitHub/Gitee remotes, releasing new team versions, one-click forking from someone else's link, and more. Independent from individual Agent version management.
+
+### Team Member Lock
+The team's precise version pointer to each member Agent. Even as a member Agent keeps iterating in its own repository, the team continues to point at the locked version by default — guaranteeing that anyone installing the team later gets the exact same combination. Use "Upgrade Members" to sync to members' latest versions.
+
+### Team Release
+Stamping a complete version number (e.g., v0.1.1) on the team, generating a changelog, and syncing to the remote. Once released, the version can be shared, reverted to, or used as a reference point.
+
 ### Tool
 External capabilities that agents can invoke. Includes built-in tools (file read/write, search, etc.), MCP tools, and custom tools. Unified registration and management through the Tool Registry.
 

From bd17ea08693988cb39a2a6d1a82a054c7cca8c12 Mon Sep 17 00:00:00 2001
From: yi-ge <a@wyr.me>
Date: Sun, 17 May 2026 18:46:14 +0800
Subject: [PATCH 2/2] docs: address Copilot review on PR #12
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. 09-team-version-management.md line 64: replace "as a release"
   wording with "as a commit" — the remote-config step records a
   snapshot, the actual release flow is documented separately later.

2. Glossary: change ASCII parentheses to full-width parentheses on
   the two new Team entries, matching the rest of the zh-Hans
   glossary format (Teach（教）, Tool（工具）...).

3. Glossary (zh + en): reorder the three new Team entries
   alphabetically — Team Member Lock → Team Release → Team Version
   Management — so the T section stays navigable.

4. English 09 Next Steps: re-add the link to Intelligent Task
   Orchestration now that PR #14 has merged the English translation
   of that concept page.
---
 .../06-agents/09-team-version-management.md            |  2 +-
 docs/05-more/03-glossary.md                            | 10 +++++-----
 .../06-agents/09-team-version-management.md            |  1 +
 .../current/05-more/03-glossary.md                     |  6 +++---
 4 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/02-user-guide/06-agents/09-team-version-management.md b/docs/02-user-guide/06-agents/09-team-version-management.md
index b8835b2..386b855 100644
--- a/docs/02-user-guide/06-agents/09-team-version-management.md
+++ b/docs/02-user-guide/06-agents/09-team-version-management.md
@@ -61,7 +61,7 @@ DesireCore 用两层结构来管理团队:
 5. 标注是否为私有仓库
 6. 保存
 
-保存后,系统会自动把团队的当前状态作为一次发布,等你下次推送时同步到远端。
+保存后,系统会自动把这次远程配置记录为一次提交,等你下次推送时同步到远端。
 
 :::tip 没远程也能用版本管理
 即使不连接远程,团队的本地版本历史也照常记录。远程仓库只是给跨设备同步和对外分享加一道"云端备份",不是必需的。
diff --git a/docs/05-more/03-glossary.md b/docs/05-more/03-glossary.md
index 1cceb1a..beaa4cb 100644
--- a/docs/05-more/03-glossary.md
+++ b/docs/05-more/03-glossary.md
@@ -140,15 +140,15 @@ DesireCore 的协作写作功能。基于 Markdown 编辑器，支持 AI 辅助
 ### Teach（教）
 六原语之一。用户告诉智能体怎么做、为什么这么做、什么情况例外。教学内容会被持久化为行为规范。
 
-### Team Version Management（团队版本管理）
-把整支智能体团队当作一个整体进行版本管理的能力,包括组织变化(加成员/换队长/解散)的自动记录、推送到 GitHub/Gitee 远程仓库、发布团队新版本、从他人链接一键 Fork 安装等。与单个智能体的版本管理是两层独立体系。
-
-### Team Member Lock(团队成员锁定)
+### Team Member Lock（团队成员锁定）
 团队对每位成员智能体的精确版本指向。即使成员智能体在自己的仓库里继续迭代,团队默认仍指向锁定的版本,保证别人下次安装时能装到一模一样的组合。需要同步到成员最新版本时,使用"升级成员"操作。
 
-### Team Release(团队发布)
+### Team Release（团队发布）
 为团队打一个完整的版本号(例如 v0.1.1)、生成变更日志、并同步到远程。发布后这个版本可以被分享、回退、或作为参考点。
 
+### Team Version Management（团队版本管理）
+把整支智能体团队当作一个整体进行版本管理的能力,包括组织变化(加成员/换队长/解散)的自动记录、推送到 GitHub/Gitee 远程仓库、发布团队新版本、从他人链接一键 Fork 安装等。与单个智能体的版本管理是两层独立体系。
+
 ### Tool（工具）
 智能体可以调用的外部能力。包括内置工具（文件读写、搜索等）、MCP 工具和自定义工具。通过 Tool Registry 统一注册和管理。
 
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md
index 1c7758c..60fcb36 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-team-version-management.md
@@ -233,3 +233,4 @@ Member versions revert to the roster from that point in time. You can choose whe
 
 - [Version Control](./08-version-control.md) — Version management for an individual Agent
 - [Cross-Agent Collaboration](../04-delegation/06-cross-agent.md) — How multiple Agents work together
+- [Intelligent Task Orchestration](../../04-concepts/10-task-orchestration.md) — Team mode vs. swarm mode explained
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md
index 072e960..5a53127 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md
@@ -140,15 +140,15 @@ DesireCore's collaborative writing feature. Based on a Markdown editor, supporti
 ### Teach
 One of the Six Primitives. Users tell agents how to do something, why to do it, and what exceptions apply. Teaching content is persisted as behavioral norms.
 
-### Team Version Management
-The ability to manage an entire Agent team as a single versioned unit — automatic recording of organizational changes (add member / change leader / disband), pushing to GitHub/Gitee remotes, releasing new team versions, one-click forking from someone else's link, and more. Independent from individual Agent version management.
-
 ### Team Member Lock
 The team's precise version pointer to each member Agent. Even as a member Agent keeps iterating in its own repository, the team continues to point at the locked version by default — guaranteeing that anyone installing the team later gets the exact same combination. Use "Upgrade Members" to sync to members' latest versions.
 
 ### Team Release
 Stamping a complete version number (e.g., v0.1.1) on the team, generating a changelog, and syncing to the remote. Once released, the version can be shared, reverted to, or used as a reference point.
 
+### Team Version Management
+The ability to manage an entire Agent team as a single versioned unit — automatic recording of organizational changes (add member / change leader / disband), pushing to GitHub/Gitee remotes, releasing new team versions, one-click forking from someone else's link, and more. Independent from individual Agent version management.
+
 ### Tool
 External capabilities that agents can invoke. Includes built-in tools (file read/write, search, etc.), MCP tools, and custom tools. Unified registration and management through the Tool Registry.