![\"agent-mcp\"](\"docs/images/agentmcp-mark.png\")
\n\n \n
\n 让 Agent 跑在最适配的底座上 · 打破 Agent 之间的隔离
\n 任务特征 → 最适配 CLI × 模型 · 跨 Runtime 编排 / 消息互通 / 统一治理\n
\n ![\"version\"](\"https://img.shields.io/badge/version-4.0.0a1-C0503A\"){kind=icon}
![\"tools\"](\"https://img.shields.io/badge/tools-34%20%2F%20tools%2Flist-3E7A56\"){kind=icon}
![\"tests\"](\"https://img.shields.io/badge/tests-617%20passed-3E7A56\"){kind=icon}
![\"license\"](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
![\"mcp\"](\"https://img.shields.io/badge/MCP-2026--07--28-5A54A3\"){kind=icon}
![\"security\"](\"https://img.shields.io/badge/security-hardened-8B4513\"){kind=icon}
\n ![\"动态架构：匹配最适配底座并打破隔离\"](\"docs/images/architecture-match-bridge.gif\")
\n
\n ![\"控制台总览\"](\"docs/images/console-overview.jpg\")
\n ![\"对话树\"](\"docs/images/console-session-tree.jpg\")
\n
\n 版本 v4.0.0a1 · 单一来源 agent_mcp/__init__.py\n · CHANGELOG\n · v4 路线图\n · DSH 接入\n
\n\n---\n\n## 核心思想\n\n```text\n不是：所有 Agent 挤在同一个 CLI 里\n而是：每个 Agent 跑在最适配它的底座上，彼此可通信、可协作、可统一治理\n```\n\n| 主张 | 含义 |\n|---|---|\n| **最适配底座** | 按任务特征选择 CLI × 模型（重构 → Claude Code，长上下文 → Codex，低延迟 → omp…），执行留在原生 Runtime |\n| **打破隔离** | 跨 Agent 消息（mailbox）、共识投票、子任务互派、跨会话续接，不再各干各的 |\n| **统一控制面** | 派发 / 监控 / 续接 / 终止 / 预算 / 审计在同一个 Control Plane，与底座无关 |\n\n三层架构（详见 [architecture.md](docs/architecture.md) · [ADR-0001](docs/decisions/0001-skill-first-mcp-runtime.md)）：\n\n```text\nSkill 是否委派 · 怎么拆 · 选最适配 CLI×模型 · 怎么验收 ← 编排控制面\n ↓\nMCP 稳定工具面 · 会话隔离 · daemon 拉起 ← 能力面（薄、无状态）\n ↓\nDaemon 队列 · 进程 · Run/Goal/Schedule · 策略 · 协作 ← 执行面\n ↓\nNative Runtime claude / codex / omp / prime / custom ← 真正执行（最适配底座）\n```\n\n**边界**：模型推理与工具执行留在原生 CLI；agent-mcp 只做编排、调度、托管、协作、观测与治理。\n\n```mermaid\nflowchart LR\n Host[\"Host Agent + Skill\"] -->|MCP stdio| MCP[\"mcp_server.py\"]\n Web[\"Web 控制台\"] -->|SSE| CP[\"Control Plane daemon\"]\n MCP --> CP\n CP --> Store[\"store_v4 · journal\"]\n CP --> EM[\"Execution Manager · Run\"]\n EM --> Ad[\"Backend Adapters\"]\n Ad --> RT[\"Native CLIs\"]\n```\n\n---\n\n## 快速开始\n\n### 1. 安装\n\n```bash\n# 交互：指定 host（推荐显式；all = 全部 21 个 host，会改多套配置）\ngit clone git@github.com:37chengshan/agent-mcp.git && cd agent-mcp\npython3 install.py --install --host claude\npython3 start_agent_mcp.py --open\n```\n\n```bash\n# 非交互管道必须写 AGENT_MCP_HOST，否则只下载、不注册\nAGENT_MCP_HOST=codex,claude \\\n curl -fsSL https://raw.githubusercontent.com/37chengshan/agent-mcp/main/install.sh | bash\n```\n\n| 模式 | 行为 |\n|---|---|\n| `--host claude` | 只写 Claude 配置（MCP + Skill） |\n| `--host all` | **全部 21 host**（六主载体 + 15 扩展），改写多套用户配置 |\n| `--dry-run` | 只预览不写盘 |\n| `--rollback` | 从备份恢复 |\n\n主载体（MCP+Skill）：`codex` `claude` `omp` `opencode` `kimi` `zcode` \n扩展 host（多只注册 MCP）：`grok` `cursor` `gemini` `pi` `copilot` `cline` `qwen` `devin` `windsurf` `amazon-q` `atomcode` `kiro` `goose` `hermes` `crush`\n\n> 安装结束只打印仓库首页链接，**不自动开浏览器 / 不调用 gh star**。 \n> 诊断：`python3 start_agent_mcp.py --doctor` \n> DeepSeek Harness：`dsh plugin --profile web add dsh-plugin-agentmcp`（见 [packages/dsh-plugin](packages/dsh-plugin) · [dsh-integration.md](docs/dsh-integration.md)）\n\n### 2. 打开控制台\n\n```bash\npython3 start_agent_mcp.py --open\n# → http://127.0.0.1:8765（token 经 0600 bootstrap 文件交付，不经 argv）\n```\n\n| 会话文件夹 | 对话树 | 仪表盘 |\n|:---:|:---:|:---:|\n| 左栏分类筛选 | 流动边 · 节点可拖 · 画布缩放 | Run/Goal·Token·策略·工作区 |\n\n\n\n---\n\n## 能力一览\n\n| | |\n|---|---|\n| **派发** | `spawn_agent` · `orchestrate_task`（DAG）· 复杂度分级门 S/M/L |\n| **续接** | `steer_agent` · `followup_task` · `resume` · 任务级超时 |\n| **观测** | `wait_agent` · `get_agent_activity` · `get_token_usage` · Web SSE |\n| **治理** | 策略链（预算/审批/限权）· 验证回投 · 会话隔离 · 审计 |\n| **v4 控制面** | Run 唯一执行单位 · Goal/Schedule · `/api/v4` journal 幂等 |\n| **知识** | Harness revision/rollback · 三段式 refine · 记忆银行 |\n| **协作** | mailbox P2P · consensus_vote |\n\n> 完整工具目录以 **`mcp_server.py` 的 `tools/list`**（当前 34）与 [capability-matrix.md](docs/capability-matrix.md) 为准。\n\n**诚实标注**\n- 沙箱 `SANDBOX_MAP` **未接执行链**（生效的是适配器 `PERMISSION_FLAGS`）；容器沙箱 `AGENT_MCP_SANDBOX_IMAGE` 实验开关\n- `verify_command` **默认拒绝**，须配置 `AGENT_MCP_VERIFY_ALLOW_PREFIXES`\n- Prime Agent 适配器已接入，能力默认 **DEGRADED**，真实冒烟 ⏳\n\n---\n\n## 安全加固（2026-09）\n\n| 面 | 措施 |\n|---|---|\n| 凭据 | `daemon.json` / env 文件 `O_CREAT\\|0600`；`state_dir` 0700；token 不进进程 argv |\n| 鉴权 | `X-Auth-Token` + `hmac.compare_digest`；`?token=` 仅 SSE；CSP `script-src 'self'` |\n| 会话隔离 | 变更类操作强制非空 `session_id`；mailbox 所有权校验 |\n| 命令面 | `verify_command` allowlist 默认 deny；custom-cli 拒绝绝对路径/覆盖内置 |\n| 幂等 | journal `created` 标志防双执行；孤儿 `recorded` → `uncertain` 可恢复；服务端重算 `request_hash` |\n| 子进程 | worker `env` 走 0600 文件并剥离 `LD_PRELOAD`/`PYTHON*` 等危险键 |\n\n---\n\n## 项目结构\n\n```text\nmcp_server.py # MCP 薄层（能力面）\nstart_agent_mcp.py # 启动 · --open · --doctor\ninstall.py / install.sh # host 注册 · 备份回滚\nagent_mcp/ # daemon · execution · store_v4 · adapters · policies\npackages/dsh-plugin/ # DSH bundle 插件（dsh-plugin-agentmcp）\nweb/ # v4 控制台 + 仪表盘面板（含动效）\nskill/ # 编排 Skill（控制面）+ 内置 Agent\ndocs/ # 架构 · ADR · 能力矩阵 · DSH/安装指南 · 品牌资产\ntests/ # 600+ 单测\n```\n\n---\n\n## 文档\n\n| 文档 | 用途 |\n|---|---|\n| [install-guide.md](docs/install-guide.md) | AI 可读安装说明 |\n| [dsh-integration.md](docs/dsh-integration.md) | DeepSeek Harness 接入 |\n| [architecture.md](docs/architecture.md) · [runtime.md](docs/runtime.md) | 三层职责 / 运行时边界 |\n| [capability-matrix.md](docs/capability-matrix.md) | 适配器能力（✅/⏳） |\n| [custom-cli.md](docs/custom-cli.md) | 自定义 CLI 接入 |\n| [skill/SKILL.md](skill/SKILL.md) | 编排 Skill 全文 |\n| [CHANGELOG.md](CHANGELOG.md) | 变更记录 |\n\n---\n\n## 开发\n\n```bash\npython3 -m pytest -m \"not integration\" -q # 单测（默认跳过真实 CLI 冒烟）\npython3 start_agent_mcp.py --doctor # 健康体检 JSON\n```\n\nLicense [MIT](LICENSE)\n"}