# Multica Assistant

> 将 SOP 梳理为 Multica 可 import 的 Agent、Squad 或 Autopilot 目录结构与 YAML/Instruction 模版；涵盖形态选型、小队协作体（含 *-copilot 本地高频 Skills 载体）、Skill/Instruction 分层、队长路由、import 同步与小队优化。适用于创建/优化 squad、agent、worker、队长路由，或编写 agent.yaml、squad.yaml、squad-instructions、autopilot.yaml 时。

- Skill: `zixun-github/multica-assistant` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add zixun-github/multica-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zixun-github/multica-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zixun-github (https://skillmd.com/u/zixun-github)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zixun-github/multica-assistant

---


# Multica Agent & Squad 脚手架

将协作 SOP 落成可 `multica import` 的物料。参考实现：`aidlc-multica/agents/task-build/`。

## 任务清单

执行时复制并勾选：

```
- [ ] 1. 选型（独立 Agent / 小队 / Autopilot）
- [ ] 2. 复制 assets 模版到 aidlc-multica/agents/ 或 squads/ 或 autopilots/
- [ ] 3. 填写 YAML + instructions（共性 → squad-instructions；角色边界 → agent-instructions）
- [ ] 3b. （选小队且需与 AI 高频互动）配套 agents/<scene>-copilot/：绑 Skills，不进 squad.yaml 路由
- [ ] 4. 判定 Skill vs Instruction，仅可复用方法论抽 Skill
- [ ] 5. （可选）生成头像 → references/avatar-generation.md
- [ ] 6. multica import 同步（--dry-run 预览；小队与配套 copilot 分别 import）
- [ ] 7. 新 issue 跑 happy path 验证（低频 assign Squad；高频 copilot 用 issue start / 本地对话）
```

**优化现有小队**：先读 [references/optimization-playbook.md](references/optimization-playbook.md)，再改文件 → import → 新 issue 验证。

## 形态选择

| 形态 | 目录 | 件数 | 何时用 |
|------|------|------|--------|
| 独立 Agent | `agents/<slug>/` | 2 件套 | 单环节，或 Agent 内部自管多模式 |
| 小队 | `squads/<name>/` | 3 件套 + 可选配套 copilot | 多阶段 SOP，需队长路由 / 人审门禁；若场景还需人与 AI 高频互动（脑暴、探索、改稿等），见下节「小队协作体」一并交付 `agents/<scene>-copilot/` |
| Autopilot | `autopilots/<name>/` | 1+ 件套 | 定时/Webhook 触发，绑定 Agent 执行 |

可复用 Agent 先在 `agents/` 定义；小队 `squad.yaml` 的 `agents[]` 按**同名**引用，`runtime` / `model` / `skills` 须一致。Autopilot `agents[]` 同理（`assignee_type: agent` 时内嵌 Agent 定义）。

**不要**把 `*-copilot` 当成与上表并列的第四种选型——它是**小队场景内**的高频配套 Agent（Skills 载体），跟小队一起设计、一起交付。

## 小队协作体与 *-copilot

选「小队」且该场景需要人与 AI **高频互动**（如脑暴、探索、反复改稿——不限于塑形）时，按协作体交付：**低频 Squad + 高频 `*-copilot`**。对齐实践文「协作体」，不是另起一套编排。

```text
协作体 = 人 + *-copilot（Skills 载体） + Squad（Leader + Workers）
高频：人驱动 copilot → 结论落盘 commit
低频：assign Squad → Leader 派 Worker
```

| | `*-copilot`（小队配套） | Leader / Worker |
|--|------------------------|-----------------|
| 本质 | **Agent**（仅为绑定 Skills 的载体） | Agent（路由专精 / 阶段专精） |
| 驱动方 | **人**（IDE + workdir 对话选用 Skill） | **Leader**（状态机派活） |
| 典型场景 | 脑暴、探索、澄清、改稿等需来回对话 | 判阶段、派活、执行、写 Comment |
| 落点 | `agents/<scene>-copilot/`；在小队文档标明配套 | `squad.yaml` roster |

**是什么 / 不是什么**：是小队场景里的特殊 Agent、Skills 载体；**不是**独立选型形态，**不是** Leader / Worker，**不是**又一个 Squad。勿用 daemon 派活驱动副驾。

**配套纪律**：

- 命名必须以 `-copilot` 结尾；典型 `runtime: cursor`；挂载该场景多 Skill
- 小队 README / `squad-instructions` 可写「本场景副驾 = `xxx-copilot`」；**不得**写入 `squad.yaml` → `agents[]` / `members`
- 交接：高频结论落盘并 commit 后 `multica issue assign --squad`

**起手**（注入绑定的 Skill 集合）：

```powershell
multica workdir issue start <issue-id> --agent "<scene>-copilot" --runtime cursor
multica workdir agent switch --agent "<另一套-copilot>" --runtime cursor
```

**Instruction 写法**：写清「人驱动、挂载哪些 Skill、产物落盘与 Evidence Gaps、关键判断过人」。**不要**套 Worker 模板（沉默退出 / 模式状态机 / @队长）——现有 `assets/agent-instruction-template.md` 偏 Worker，copilot 按上文自行精简。

**红线**：结论写入文件并 commit 再 assign；勿把副驾写进小队状态机；Worker 交付后沉默退出，避免与人互相 @ 成环。

## 平台前提（摘要）

- Squad 是路由对象，不执行任务；issue 分配、mention、autopilot 均落到 `leader_id`，不会 fan-out 全部成员。
- `squad-instructions.md` 注入 Leader 与**每个成员** prompt——全队共性写此处，角色边界写各 `agent-instructions/*.md`。
- Agent `description` 是目录摘要，不进运行时；`instructions` + 绑定 skills 才是行为契约。
- 分配、评论、mention、改状态、import 均有副作用；验证用新 issue，生产 issue 勿试错。

完整契约见 [references/multica-platform-context.md](references/multica-platform-context.md)；平台事实核对优先参考 `.cursor/skills/multica-squads`、`.cursor/skills/multica-creating-agents`、`.cursor/skills/multica-working-on-issues`。

## 目录结构

**独立 Agent**

```
agents/<slug>/
├── agent.yaml
├── avatar.png                     # 可选
└── agent-instructions/<slug>.md
```

**小队**（协作体场景可另建配套 `agents/<scene>-copilot/`，结构同独立 Agent，不进下方 roster）

```
squads/<name>/
├── squad.yaml
├── squad-instructions.md          # 全队共享：状态机、协作规范、共性上下文；可注明配套副驾名
├── avatar.png / avatars.yaml      # 可选
├── avatars/                       # 可选
└── agent-instructions/
    ├── leader-<slug>-router.md
    └── worker-<slug>.md

# 同场景配套（可选，不进 squad.yaml agents[]）
agents/<scene>-copilot/
├── agent.yaml
└── agent-instructions/<scene>-copilot.md
```

**Autopilot**

```
autopilots/<name>/
├── autopilot.yaml
├── agent-instructions/<slug>.md    # assignee_type=agent 时
└── skills/<skill-name>/SKILL.md
```

## Skill vs Instruction

| 放 Skill | 放 Instruction |
|----------|----------------|
| **可跨小队复用**的通用方法论 | 平台命令、metadata key、评论模板 |
| 产物结构与 DoD（与编组无关） | 状态机、路由规则、门禁实现 |
| 合格条件、步骤与判定逻辑 | 具体 Agent 名、小队专属 SOP |

**判定**：「换一个小队 / 平台还成立吗？」成立 → Skill；不成立 → Instruction。**不要**为单次工作项或本小队专属流程单独建 Skill。

Worker 基线引用 `aidlc-multica/shared/worker-loop-base.md`，不重复。小队配套 copilot 不引用该 Worker 基线。

## 模版文件

按需读取 [assets/](assets/) 并复制到目标目录：

| 文件 | 用途 |
|------|------|
| [agent-yaml-template.yaml](assets/agent-yaml-template.yaml) | 独立 Agent / 小队配套 `*-copilot` 声明 |
| [agent-instruction-template.md](assets/agent-instruction-template.md) | 独立 Agent / 多模式 Worker（copilot 勿照搬 Worker 结构） |
| [squad-yaml-template.yaml](assets/squad-yaml-template.yaml) | 小队编组声明 |
| [squad-instructions-template.md](assets/squad-instructions-template.md) | 全队共享指引 |
| [leader-router-template.md](assets/leader-router-template.md) | 队长路由 instruction |
| [worker-instruction-template.md](assets/worker-instruction-template.md) | 单阶段 Worker |
| [autopilot-yaml-template.yaml](assets/autopilot-yaml-template.yaml) | Autopilot（triggers + agent） |
| [avatars-manifest.example.yaml](assets/avatars-manifest.example.yaml) | 头像生成清单 |

Skill 目录规范：`aidlc-multica/skills/README.md`

## 编写顺序

```
独立 Agent：agent.yaml → agent-instructions → （可选）头像 → 确认 skills/ → import → 验证
小队：       squad.yaml → squad-instructions → agent-instructions
             →（需与 AI 高频互动）agents/<scene>-copilot/ → （可选）头像 → import 小队 + import 副驾 → 验证
Autopilot：  autopilot.yaml → agent-instructions → skills/ → import → 验证（手动触发一次）
```

## 同步命令

```powershell
multica agent import --dir <agent-dir>              # 独立 Agent 或小队配套 *-copilot
multica squad import --dir <squad-dir>              # 小队；删了本地 skill 时加 --prune-skills
multica autopilot import --dir <autopilot-dir>
# 均支持 --dry-run 预览、--force 跳过确认
multica squad export <name-or-id> --dir <dir>       # 备份/迁移
multica autopilot export <name-or-id> --dir <dir>
```

## 模型选型

写入 `squad.yaml` / `agent.yaml` 时：**先定 `runtime`，再按 `models.json` 的 `runtime_constraints` 过滤 `model`**。

| runtime | 可用 model 协议 |
|---------|----------------|
| `claude` | `anthropic` |
| `codex` / `daemon` 等执行型 | `openai` |
| `cursor` | 不支持指定网关 model（小队配套 `*-copilot` 常用） |

SSOT：[references/models.json](references/models.json)；决策树：[references/model-cost-matrix.md](references/model-cost-matrix.md)。

## 深入参考

| 主题 | 文件 |
|------|------|
| 平台协作契约 | [references/multica-platform-context.md](references/multica-platform-context.md) |
| 小队优化方法论 | [references/optimization-playbook.md](references/optimization-playbook.md) |
| 头像生成 | [references/avatar-generation.md](references/avatar-generation.md) |
| 模型定价与约束 | [references/models.json](references/models.json) |
| 人类使用说明与提示词示例 | [README.md](README.md) |