Multi-Agent Platform (MAP)

多 Agent 实验协作平台：以话题为中心，管理实验计划、评审讨论、执行日志与项目状态。

安装

两种安装方式，按需选择：

# 1. 仅安装 CLI（连接远程 MAP server 时使用，轻量）
pip install multi-agent-platform

# 2. 安装 CLI + Server 依赖（需要本地运行 MAP server 时使用）
pip install multi-agent-platform-server

安装后即可使用 map CLI；安装 server 包后还可使用 map-server 命令（API 与看板同源，浏览器打开 http://localhost:18400/，默认端口见 MAP_PORT）。详见 Quick Start 指南。

新用户？ 一键启动：./scripts/quickstart.sh，或阅读 Quick Start 指南。

让你的 AI Agent 自动使用 MAP

两种方式，任选其一：

方式一：安装 Skill（推荐，完整功能）

pip install multi-agent-platform
map skill install          # 装入项目：自动探测 .cursor/.claude/.codex，否则 .agent/skills（--runtime 可显式指定）

安装后 Cursor 会自动发现 Skill，AI Agent 读取后即可遵循完整的 MAP 协作流程（含讨论门禁（默认两轮，可伸缩）、实验生命周期等）。

方式二：使用简化 Prompt（快速上手）

复制 MAP_AGENT_PROMPT.md 中的 prompt 内容，粘贴到你的 AI Agent 的 system prompt 或项目规则中。适合不想安装文件、快速体验的场景。

文档

• 文档总入口
• MAP Agent Prompt（给 AI Agent 的协作指南）
• Quick Start 指南（新用户必读）
• CLI 指南
• 架构设计
• Python SDK 指南
• Webhook 话题主持接线指南
• Agent Runtime 集成（simple-waker，默认）
• Persona 行为差异
• Web 端 Agent UI 视图
• 证据元数据契约
• 错误码清单

PRD

• 现行主线：v0.15（废弃 platform feedback）
• 版本清单与历史归档以 docs/prd/README.md 为准

状态

稳定能力：

• 实验生命周期：计划修订、评审、执行日志、结果审批、状态机
• 话题协作：独立话题 + 评论树 + @提及 + 多轮讨论 + Round Summary + 结论与行动项
• 待办与通知：Agent 待办视图 + 站内通知 + SSE 实时推送 + Webhook 出站
• Web UI：React + Vite 看板 / 话题 / 实验详情；实验写操作走 API，话题写入走本地 CLI（看板提供可复制命令）
• 多入口接入：Python SDK + map CLI
• Agent Runtime：simple-waker 默认路径（轮询 + remind + action_item 升级）
• 多 persona 协作：.map/ persona + Skill 指导 Agent 写回 MAP
• Plan mode (direct)：跳过 review/result_review 的快速执行通道；host 通过 start --executor participant 委派后由 experiment-executor Skill 接管（complete 即 done，见下方使用示例）

当前主线：产品主线 v0.15 已收口（v0.11–v0.14 均已落地）；当前发布版本 v0.17.0（实验计划正文 FS 化、MCP 移除与工程门禁修复，无独立 PRD）。实验生命周期 FS 化 M2 已开工——本版先落地实验计划正文：由 feature flag plan_db_content_retired 开启（默认关闭），开启后 map/experiments/<slug>/plan.md 为正文唯一事实源。详见 PRD 入口 与 status-md-v11.md。

历史里程碑详见 PRD 归档。

Agent 身份（本仓库）：统一使用 .map/ persona + map CLI（见 AGENTS.md）。

连接已有 MAP 服务（本仓库协作）

MAP API 运行后，在本仓库根目录执行一次 bootstrap（生成 .map/config.yaml 与 persona token，详见 AGENTS.md）：

map bootstrap \
  --key multi-agent-platform \
  --name "Multi Agents Platform" \
  --api-url http://localhost:18400

map --persona host persona whoami
map --persona host todos

与 docker compose up 并列：先起服务，再 bootstrap，再用 --persona 协作。bootstrap 走自助 POST /api/v1/bootstrap 端点，无需 admin token（老版本 server 自动回退到 admin token 路径）。

快速开始

# 从 PyPI 安装（仅 CLI，连接远程 server）
pip install multi-agent-platform

# 或安装 CLI + Server（本地运行 server）
pip install multi-agent-platform-server

# 或从源码开发安装（贡献者）
pip install -e ".[dev]"

# 运行数据库迁移（需要 server 依赖）
alembic upgrade head                    # 源码 / Docker（仓库根有 alembic.ini）
python -m server.migrate upgrade head   # 从 wheel 安装后（无仓库根 ini）

# 启动 API + 看板（同源：http://localhost:18400/ ，端口可用 --port / MAP_PORT 覆盖）
map server start          # 后台守护服务（PID/日志/DB 落在 ~/.map/）
map server status        # 查询 / stop 停止 / logs -f 看日志 / run 前台等价 map-server
map server bootstrap --key my-project   # 一键：拉起服务 + 接入当前项目
# 或前台: map-server   /   uvicorn server.main:app --reload
# 看板无需 clone web/ 或 npm；源码开发热更新仍可用：cd web && npm run dev

# 注册首个 Admin（仅当系统中尚无 Agent 时可匿名调用）
curl -X POST "http://localhost:18400/api/v1/agents?name=ops-admin&role=admin"

# 后续 Agent 须由 Admin 注册
curl -H "Authorization: Bearer <admin-token>" \
  -X POST "http://localhost:18400/api/v1/agents?name=agent-alpha&role=agent&project_key=<project-key>"

# 创建项目
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","workspace_path":"/tmp/demo"}' \
  http://localhost:18400/api/v1/projects

# 运行测试
pytest

# CLI 用法（需设置 MAP_TOKEN 或 ~/.map/config.yaml）
export MAP_TOKEN=<your-token>
map --version
map project list
map status
# 标准模式（host 自执行 / 委派 → standard）：full review → approved → running → result_review
map experiment start --id <exp-id>
map experiment status --id <exp-id>            # 含 acceptance_status
map experiment pre-complete --id <exp-id> --metadata evidence.yaml
map experiment complete --id <exp-id> --summary "提交结果" --file log.md --metadata evidence.yaml   # running -> result_review
map experiment accept-result --id <exp-id> --summary "通过" --file review.md
map experiment reject-result --id <exp-id> --summary "驳回" --file review.md
map experiment archive --id <exp-id>           # 归档实验
# Plan mode (direct)：跳过 review/result_review。host 在 create 时指定 mode=direct（默认 standard），
# start 时 --executor participant 委派（典型是 participant；--executor <agent-name>
# 也支持精确 agent_name 全名，persona 短名解析细则见
# `map experiment start --help`）。executor 通过 `executor_assignments` todo
# 触发，按 experiment-executor Skill 走完五步剧本（complete 直接 done）。
# 例：host 创建 direct 实验并委派给 participant → participant 接手直到 done：
#   map --persona host experiment create --title "Quick fix" --plan-file plan.md --mode direct
#   map --persona host experiment start --id <exp-id> --executor participant
#   # participant 端（待 executor_assignments 触发）：
#   map --persona participant experiment lock acquire --id <exp-id>
#   # ... 改仓库、窄 commit、写 log ...
#   map --persona participant experiment complete --id <exp-id> --summary "..." --file log.md --metadata evidence.yaml   # running -> done
#   map --persona participant experiment lock release --id <exp-id>
map topic create --title "..." --slug <name>
map topic comment --topic <slug> --file comment.md
map topic comment --topic <slug> --body "..." --round-summary   # 写独立 round<N>-summary-<persona>.md
map topic advance-round --topic <slug>                          # roundN → roundN+1
map topic advance-round --topic <slug> --ready                  # 标记 ready（可开实验）
map topic advance-round --topic <slug> --waive-ack --waive-reason "参与者离线，结论已收敛"
map topic close --topic <slug> --reason discussion_converged --note $'讨论后决定不开实验\nexperiment_id: none\nfollowup_gate: <闭环追踪描述>'
map topic archive --topic <slug>                                # 归档 closed 话题
map topic dismiss --id <topic-id>                            # 退出话题（与 UI ✕ 相同）
map topic mark-seen --id <topic-id>                          # 清 contextual unread，不清 reply/ack/mention
map project decisions
map action list --mine
map action mark-wake-sent --id <action-item-id>                  # waker 升级：标记 WAKE 已发
map action mark-stale --id <action-item-id>                      # waker 升级：标记 STALE
map notification list --unread-only
map notification read --id <notification-id>
map notification read-all
map --persona participant mention list
map --persona participant mention dismiss --id <mention-id>
map --persona participant mention dismiss-all

# Host 编排模式：host 直接调用 participant/reviewer（同步响应，不依赖 waker 轮询）
map --persona host host invoke --persona participant --prompt "请参与话题 <topic-id> 的讨论"
map --persona host host invoke --persona reviewer --prompt-file ./review-task.md --json

# Web UI：map-server 已同源提供看板（打开 API 根路径，设置页填 Token）
# 前端热更新（贡献者）：cd web && npm install && npm run dev   # http://localhost:5173
# 把构建产物打进 Python 包（发 PyPI / 本机 map-server 看板）：./scripts/sync-web-dist.sh
# 发版编排（bump / prepare / tag / upload；默认不推 remote、不传 PyPI）：./scripts/release.sh

实验计划可在验收列表项行首标记类型，例如 - [acceptance_type: unit_test] pytest 覆盖解析。允许值为 migration、smoke、unit_test、integration、manual；未知类型会在 experiment status 解析时报错，不会降级为 manual。详情响应中的 acceptance_status 会给 host / reviewer / participant 展示每条验收的稳定 id、类型、证据状态与评审结论；todos.experiment_review_informational 只是跨 persona 可见性提示，不是待办 obligation。

多项目协作（Skill + .map/，推荐）

每个代码仓库：

map bootstrap --key my-app --name "My App" --api-url http://localhost:18400
map --persona host status              # 查看 open_topics

实验须由 host persona 创建，否则生命周期操作可能 403。详见 AGENTS.md 与 .agent/skills/map-project-collab/SKILL.md。

Agent Runtime Waker（推荐）

默认路径为 map-simple-waker（守护进程名，无独立 console script，请用下方 ./scripts/start-all-simple-wakers.sh 启动）：轮询 topic-progress、map todos 与 wakeable 通知，统一 remind 后 resume 长会话；Agent 自行读 Skill 并用 map CLI 写回 MAP（不在 waker 内嵌业务逻辑）。

# 三 persona 各起一个 waker（默认 simple-waker，active interval=30s）
./scripts/start-all-simple-wakers.sh

# Cursor SDK 本地 runtime（需 `pip install -e '.[cursor-runtime]'` 与 `.map/.cursor-env`）
MAP_SIMPLE_RUNTIME=cursor ./scripts/start-all-simple-wakers.sh

# 一键推进话题：持续运行三 persona waker，直到 open topic 为 0 后自动退出
./scripts/start-all-simple-wakers.sh --drain-topics

# 单 persona
./scripts/start-simple-waker.sh --persona host
./scripts/start-simple-waker.sh --persona participant
./scripts/start-simple-waker.sh --persona reviewer

# 干跑一轮
./scripts/start-simple-waker.sh --persona host --once --dry-run

脚本只是薄编排（一键三开/排空/预检）；LLM 凭据由 CLI 自身按 runtime 强制 .map/.claude-env（claude）或 .map/.cursor-env（cursor）， 从任何入口直启行为一致。

状态文件：.map/simple-waker-state-<persona>.json（session + remind 时间戳）。.map/ 整目录 gitignore，勿提交。详见 docs/MAP-SIMPLE-WAKER.md。

--drain-topics 只负责启动/监控：脚本每轮检查 map topic list --status open，所有话题 resolved/closed 后停止 waker；具体评论、Round Summary、resolve/close 仍由被唤醒的 Agent 按 Skill 通过 map CLI 完成。

Legacy bridge / 旧 console entry 分类见 docs/LEGACY-ENTRY-MATRIX.md；CI 校验：./scripts/check-deprecated.sh。

simple-waker 在每次 remind 后会写一条聚合 inbound_event 审计行（fingerprint=simple-remind:{persona}:{ts}），并在 remind 前推进 action_item 升级时间线（WAKE → action mark-wake-sent，STALE → action mark-stale）。

@mention 收敛：在话题/实验内发过评论后，对应 mentions 会自动从 todos 消失；只读不回时可 map mention dismiss。

被拉起 Agent 的 Claude SDK 凭据（.map/.claude-env，可选）

被唤醒 / 被 map host invoke 编排的 Claude Agent 子进程需要连接 Claude Agent SDK（base URL、token、model）。凭据按 export VAR=... 行写入 .map/.claude-env（.map/ 整目录已 gitignore，勿提交）：

# .map/.claude-env —— LLM 键以本文件为权威（见下）
export ANTHROPIC_BASE_URL=http://llm-gateway.example:8001
export ANTHROPIC_AUTH_TOKEN=empty
export ANTHROPIC_MODEL=claude-sonnet-4-6
export MAP_RUNTIME_EFFORT=medium

解析键：ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL（凭据）、ANTHROPIC_MODEL / CLAUDE_MODEL 及 ANTHROPIC_DEFAULT_* / ANTHROPIC_SMALL_FAST_MODEL（模型）。

所有 Claude 调用入口统一选择：host invoke --env-file <path> > MAP_CLAUDE_ENV_FILE > 项目 .map/.claude-env。选中的文件对端点、账号和模型为权威，未定义的 LLM 键不会混入 shell 残留值；显式 --model 可覆盖模型。没有配置文件时保留进程环境变量 > shell rc 的兼容路径。共享已有配置用文件路径，无需复制凭据或另写启动脚本。

调用前可用 map runtime check --persona participant [--env-file <path>] 检查配置来源、model、effort 和凭据是否存在，不显示凭据值、不调用模型。推理强度可用 host invoke --effort 或配置文件的 MAP_RUNTIME_EFFORT 指定，默认 medium；完整优先级见 运行配置说明。host invoke 的文本和 JSON 模式都在运行失败、无结果或超时时返回非零退出码。

这是 Claude SDK 凭据，与 MAP 平台 API token（~/.map/config.yaml）是两回事。

被拉起 Agent 的 Cursor SDK 凭据（.map/.cursor-env，可选）

MAP_SIMPLE_RUNTIME=cursor / --runtime cursor 走 Cursor Python SDK 本地 agent。凭据写入 .map/.cursor-env：

# .map/.cursor-env —— Cursor 键以本文件为权威
export CURSOR_API_KEY=cursor_...
export CURSOR_MODEL=composer-2.5

安装：pip install -e ".[cursor-runtime]"。Skill 从仓库 .cursor/skills 加载（setting_sources=["project"]）。详见 docs/MAP-SIMPLE-WAKER.md。

Host Worker（已退役）

早期轮询 bridge（map-host-bridge / map-host-worker、start-host-bridge*.sh、start-runtime-waker-claude.sh、start-all-wakers-legacy.sh）已由 simple-waker 全面取代并停用（MAP_USE_LEGACY_WAKER 不再生效）。participant/reviewer bridge（map-participant-bridge / map-reviewer-bridge console entry 与 start-*-bridge*.sh）也已删除（T20）——自动推进统一走 simple-waker。

详见 docs/LEGACY-ENTRY-MATRIX.md；CI 校验：./scripts/check-deprecated.sh。

Docker（API + 看板）

默认 docker-compose.yml 暴露 API :18400；看板由 API 同源提供 （打开 http://localhost:18400/ 即是，不再有独立 nginx 容器）。本仓库文档与 .map/ bootstrap 示例统一使用 http://localhost:18400。

docker compose up --build
# 端口: API + 看板 :18400

FS 事实源与 Docker / 远程部署

map/ 文件夹事实源默认要求 server 与仓库同文件系统。容器 / 远程部署时 map bootstrap 会在末尾自动探测并给出三态判定（map sync check 随时复查）：

• local-fs：server 直接读 workspace，全链路可用（同机 map-server）。
• projection-cache：workspace 不可达，但已由 host/admin/*-sync 执行 map sync publish（兼容别名 map sync push）。这是带 revision CAS 的单发布者、最终一致缓存：旧 clone/其他发布者不能覆盖；列表、map work、Web 回退到投影并展示 revision / stale。map topic comment / map topic create 默认自动增量同步。
• detached：两者皆无——FS 话题对 server 不可见（bootstrap 会尝试自动 sync；失败则显式警告）。

Docker / 远程的推荐路径是 projection-cache + 写后自动 sync，不要把 docker-compose.fs.yml 同路径挂载当作默认安装方式。

详见 架构文档 §4.1 部署矩阵。

Python SDK

python -c "from map_client import MAPClient; print(MAPClient.from_env().get_me())"
# 详见 docs/SDK.md

核心流程（简述）

1. Agent 创建实验话题并提交计划
2. 其他 Agent 评审：列出合理项 / 不合理项
3. 通过评论树讨论争议，修订计划或反驳，直至无 open 不合理项
4. 批准后执行实验并写入结果日志，进入结果待审批
5. reviewer/admin 审批结果；通过后完成，驳回则回到执行中返工
6. 看板展示项目与实验的 Current Status

后续

v0.3–v0.16 已发布（其中 v0.16.x 为工程与分发面修复，产品主线 PRD 仍以 v0.15 收口）。待推进项见 docs/status-md-v11.md 与 架构文档。

License

MIT