Teams — 团队包结构、编排与构建规范
Team(团队) 是多个专精 Agent 的组合:定义一组各司其职的 AI 工作者 + 共享规范(ANNOUNCEMENT / NORMS)+ 协作编排结构,并可选附带可运行的工作流(workflow)模板。本页一体讲清团队包如何构建:成员结构、编排配置、仓库布局与发布规范。单 Agent 详见 Agents。
1. 概念速览与核心哲学
| 概念 | 说明 |
|---|---|
| Team 包 | 自包含、可发布 Hub 的目录工件,定义一组 Agent + 共享规范 + 编排 |
| Manifest(team.json) | team.members[] 成员结构、team.workflow 编排、team.workflows 工作流文件 |
| 成员(Member) | members/{slug}/ 目录下的 Agent 定义,含 ROLE.md 等 |
| 规范注入 | ANNOUNCEMENT.md + NORMS.md 安装后注入每个成员的上下文 |
| Workflow | YAML DAG 模板,可作任务序列自动跑 |
核心哲学:团队里每个 Agent 必须专精。别拿通用模板改个名就完事——每个成员要有独一无二的身份、专长与详细的角色文档;安全约束写在各自
POLICIES.md,不是用裁撤工具来限制。
2. 仓库结构(Artifact Directory)
~/.markus/builder-artifacts/teams/{team-name}/ ← {name} 必须是合法 slug
├── team.json # 主配置(manifest)
├── README.md # 对外介绍(Hub/Builder 展示,REQUIRED)
├── ANNOUNCEMENT.md # 团队公告
├── NORMS.md # 工作规范
├── images/
│ └── icon.png # 团队图标(安装后作头像)
├── workflows/ # 工作流模板(optional)
│ └── {workflow-name}.yaml # YAML 工作流 DAG
└── members/
├── {manager-slug}/
│ ├── ROLE.md # 身份与系统提示词(REQUIRED)
│ ├── HEARTBEAT.md # 定期巡检(RECOMMENDED)
│ ├── POLICIES.md # 约束护栏(optional)
│ ├── CONTEXT.md # 领域上下文(optional)
│ └── images/ # 成员头像
└── {worker-slug}/ #(结构同上)
只认 ~/.markus/builder-artifacts/teams/,被 package_list / package_install 识别。不要写到 ~/.markus/shared/、workspace 或其他位置。
安装落点
| 包内文件 | 部署到 | 作用 |
|---|---|---|
ANNOUNCEMENT.md | ~/.markus/teams/{teamId}/ANNOUNCEMENT.md | 注入每个成员上下文 |
NORMS.md | ~/.markus/teams/{teamId}/NORMS.md | 注入每个成员上下文 |
members/{name}/ROLE.md | ~/.markus/agents/{agentId}/role/ROLE.md | 成员身份/系统提示 |
members/{name}/HEARTBEAT.md | ~/.markus/agents/{agentId}/role/HEARTBEAT.md | 每约 30 分钟巡检 |
members/{name}/POLICIES.md | ~/.markus/agents/{agentId}/role/POLICIES.md | 附加约束 |
members/{name}/CONTEXT.md | ~/.markus/agents/{agentId}/role/CONTEXT.md | 领域上下文 |
members/{name}/images/ | ~/.markus/agents/{agentId}/role/images/ | 成员头像 |
workflows/*.yaml | ~/.markus/teams/{teamId}/workflows/*.yaml | 可运行工作流模板 |
3. 三步工作流
先 manifest,再内容文件,再可选工作流 YAML。绝不把文件内容内联到 JSON。 所有模式(chat / task / A2A)同此规则。
file_write写team.json(manifest,见 §4)。- 逐个
file_writeREADME / ANNOUNCEMENT / NORMS / 每个成员 ROLE.md 等(见 §5)。 - 可选:写
workflows/*.yaml工作流模板。
4. Manifest(team.json)核心字段
{
"type": "team",
"name": "dev-squad", // slug,kebab-case,规则同 agent
"displayName": "Development Squad", // 人类可读(可中文)
"version": "2.0.0",
"description": "Team purpose and goals",
"author": "",
"icon": "images/icon.png",
"category": "development", // development | devops | management | productivity | general
"tags": ["development", "sprint"],
"i18n": { "zh-CN": { "displayName": "开发小队", "description": "…", "members": { "Tech Lead": "技术负责人" } } },
"team": {
"members": [
{ "name": "Tech Lead", "slug": "tech-lead", "roleName": "Tech Lead",
"role": "manager", "count": 1, "skills": ["team-building"] },
{ "name": "Backend Developer", "role": "worker", "roleName": "backend-developer",
"skills": ["coding-tools"] }
],
"workflow": {
"phases": ["plan", "implement", "review", "validate"],
"parallelImplementation": true,
"worktreeIsolation": true,
"requireReviewBeforeComplete": true
},
"workflows": ["workflows/content-publishing.yaml"]
}
}
包名(Slug)— 硬规则
name 即包 slug(目录名、Hub URL 段、分享/发布 ID)。规则同 Agent:仅英文 kebab-case(小写字母/数字/连字符)、2–64 字符、字母开头;不允许中文/空格/下划线/大写/emoji;人读名放 displayName。members/ 下的成员目录 slug 也必须是英文 kebab-case。用户只给中文名时,发明英文 kebab slug、displayName 用原名。
| 用户语言 | name(slug) | displayName |
|---|---|---|
| 中文「智库研究团队」 | think-tank-research | 智库研究团队 |
| 英文 “Frontend Squad” | frontend-squad | Frontend Squad |
成员字段(team.members[])——REQUIRED
| 字段 | 说明 |
|---|---|
name | 显示名——可中文(如「技术负责人」) |
slug (推荐) | kebab-case slug,匹配 members/{slug}/ 目录名。当 name 含非 ASCII 时必备——中文自动 kebab 会丢 Unicode,导致目录错位、头像失效 |
roleName (推荐) | 英文显示名,作为目录匹配兜底 |
role | 只能 "manager" 或 "worker"——UI 用它着色与管理 |
count | 实例数(通常 1),必填 |
skills | 技能 ID(从动态上下文取)——主动分配,别留空 |
⚠️ 硬规则:
members必须嵌在team下(不在根层);role只能 manager/worker;count必须有;category只能在枚举里;根层不要放members/skills;每个团队恰好 1 个 manager + ≥1 worker。
编排(team.workflow)与 Workflow 模板
phases:团队工作阶段数组(如["plan","implement","review","validate"])。parallelImplementation:实现期是否多成员并行;worktreeIsolation:编码团队建议true(git worktree 隔离);requireReviewBeforeComplete:任务是否必须先过审查才能完成。workflows/*.yaml:带依赖的步骤 DAG(steps[].id/name/type/role/prompt/depends_on/inputs)。安装后拷到~/.markus/teams/{teamId}/workflows/,即可通过 Workflows UI 或workflow_run运行。完整 YAML 格式见 workflow-building 技能。
5. 内容文件规范
- README.md(REQUIRED):Hub/Builder 展示的公开介绍——团队做什么、解决什么、成员构成、关键能力、部署场景(2–4 段)。
- ANNOUNCEMENT.md:团队使命、成员介绍、协作方式、关键能力(至少 3 段)。
- NORMS.md:按
team.workflow.phases写阶段化流程——每阶段谁负责、用哪些平台能力、并行开发的文件/模块归属、通信协议(何时agent_send_message/agent_broadcast_status)、引用spawn_subagent/background_exec/shell_execute/ worktree /deliverable_create。这对团队效力至关重要。 - 每个成员 ROLE.md:逐个写,至少 5 个实质段落(参考既有 base role 模板),体例同 Agents / ROLE.md。
- HEARTBEAT.md(RECOMMENDED)、POLICIES.md(optional)、CONTEXT.md(optional)。
视觉资产
- 团队图标
images/icon.png:抽象 logo/徽章风格(盾牌/齿轮/节点/星星),不用人像。 - 成员头像
members/{slug}/images/avatar.jpg:真实数字肖像,规则同 Agent 头像。
6. 创建 ≠ 安装(红线)
创建工件 ≠ 安装/部署。只有用户明确说 “install”/“deploy”/“hire” 才用 package_install / hub_install。装进组织后团队中每个成员会成为真实 Agent、可被指派任务、共同协作。
7. 接下来
- 单 Agent 结构与构建 → Agents。
- 给成员配可复用能力 → Skills 技能。
- 把团队包发布到社区 → Markus Hub 市场。