Teams — 团队包结构、编排与构建规范

English · ← 回到分类

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 安装后注入每个成员的上下文
WorkflowYAML 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)同此规则。

  1. file_write 写 team.json(manifest,见 §4)。
  2. 逐个 file_write README / ANNOUNCEMENT / NORMS / 每个成员 ROLE.md 等(见 §5)。
  3. 可选:写 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-squadFrontend 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. 接下来