37chengshan/agent-mcp

Agent MCP

让 Agent 跑在最适配的底座上 · 打破 Agent 之间的隔离
任务特征 → 最适配 CLI × 模型 · 跨 Runtime 编排 / 消息互通 / 统一治理

版本 v4.0.0a1 · 单一来源 agent_mcp/__init__.py
· CHANGELOG
· v4 路线图
· DSH 接入

核心思想

不是：所有 Agent 挤在同一个 CLI 里
而是：每个 Agent 跑在最适配它的底座上，彼此可通信、可协作、可统一治理

| 主张 | 含义 |
|---|---|
| 最适配底座 | 按任务特征选择 CLI × 模型（重构 → Claude Code，长上下文 → Codex，低延迟 → omp…），执行留在原生 Runtime |
| 打破隔离 | 跨 Agent 消息（mailbox）、共识投票、子任务互派、跨会话续接，不再各干各的 |
| 统一控制面 | 派发 / 监控 / 续接 / 终止 / 预算 / 审计在同一个 Control Plane，与底座无关 |

三层架构（详见 architecture.md · ADR-0001）：

Skill   是否委派 · 怎么拆 · 选最适配 CLI×模型 · 怎么验收     ← 编排控制面
↓
MCP     稳定工具面 · 会话隔离 · daemon 拉起                  ← 能力面（薄、无状态）
↓
Daemon  队列 · 进程 · Run/Goal/Schedule · 策略 · 协作         ← 执行面
↓
Native Runtime   claude / codex / omp / prime / custom        ← 真正执行（最适配底座）

边界：模型推理与工具执行留在原生 CLI；agent-mcp 只做编排、调度、托管、协作、观测与治理。

flowchart LR
Host["Host Agent + Skill"] -->|MCP stdio| MCP["mcp_server.py"]
Web["Web 控制台"] -->|SSE| CP["Control Plane daemon"]
MCP --> CP
CP --> Store["store_v4 · journal"]
CP --> EM["Execution Manager · Run"]
EM --> Ad["Backend Adapters"]
Ad --> RT["Native CLIs"]

快速开始

1. 安装

交互：指定 host（推荐显式；all = 全部 21 个 host，会改多套配置）
git clone git@github.com:37chengshan/agent-mcp.git && cd agent-mcp
python3 install.py --install --host claude
python3 start_agent_mcp.py --open

非交互管道必须写 AGENT_MCP_HOST，否则只下载、不注册
AGENT_MCP_HOST=codex,claude \
curl -fsSL https://raw.githubusercontent.com/37chengshan/agent-mcp/main/install.sh | bash

| 模式 | 行为 |
|---|---|
| --host claude | 只写 Claude 配置（MCP + Skill） |
| --host all | 全部 21 host（六主载体 + 15 扩展），改写多套用户配置 |
| --dry-run | 只预览不写盘 |
| --rollback | 从备份恢复 |
主载体（MCP+Skill）：codex claude omp opencode kimi zcode
扩展 host（多只注册 MCP）：grok cursor gemini pi copilot cline qwen devin windsurf amazon-q atomcode kiro goose hermes crush

安装结束只打印仓库首页链接，不自动开浏览器 / 不调用 gh star。
诊断：python3 start_agent_mcp.py --doctor
DeepSeek Harness：dsh plugin --profile web add dsh-plugin-agentmcp（见 packages/dsh-plugin · dsh-integration.md）

2. 打开控制台

python3 start_agent_mcp.py --open
→ http://127.0.0.1:8765（token 经 0600 bootstrap 文件交付，不经 argv）

| 会话文件夹 | 对话树 | 仪表盘 |
|:---:|:---:|:---:|
| 左栏分类筛选 | 流动边 · 节点可拖 · 画布缩放 | Run/Goal·Token·策略·工作区 |

仪表盘

能力一览

| | |
|---|---|
| 派发 | spawn_agent · orchestrate_task（DAG）· 复杂度分级门 S/M/L |
| 续接 | steer_agent · followup_task · resume · 任务级超时 |
| 观测 | wait_agent · get_agent_activity · get_token_usage · Web SSE |
| 治理 | 策略链（预算/审批/限权）· 验证回投 · 会话隔离 · 审计 |
| v4 控制面 | Run 唯一执行单位 · Goal/Schedule · /api/v4 journal 幂等 |
| 知识 | Harness revision/rollback · 三段式 refine · 记忆银行 |
| 协作 | mailbox P2P · consensus_vote |

完整工具目录以 mcp_server.py 的 tools/list（当前 34）与 capability-matrix.md 为准。

诚实标注
- 沙箱 SANDBOX_MAP 未接执行链（生效的是适配器 PERMISSION_FLAGS）；容器沙箱 AGENT_MCP_SANDBOX_IMAGE 实验开关
- verify_command 默认拒绝，须配置 AGENT_MCP_VERIFY_ALLOW_PREFIXES
- Prime Agent 适配器已接入，能力默认 DEGRADED，真实冒烟 ⏳

安全加固（2026-09）

| 面 | 措施 |
|---|---|
| 凭据 | daemon.json / env 文件 O_CREAT\|0600；state_dir 0700；token 不进进程 argv |
| 鉴权 | X-Auth-Token + hmac.compare_digest；?token= 仅 SSE；CSP script-src 'self' |
| 会话隔离 | 变更类操作强制非空 session_id；mailbox 所有权校验 |
| 命令面 | verify_command allowlist 默认 deny；custom-cli 拒绝绝对路径/覆盖内置 |
| 幂等 | journal created 标志防双执行；孤儿 recorded → uncertain 可恢复；服务端重算 request_hash |
| 子进程 | worker env 走 0600 文件并剥离 LD_PRELOAD/PYTHON* 等危险键 |

项目结构

mcp_server.py            # MCP 薄层（能力面）
start_agent_mcp.py       # 启动 · --open · --doctor
install.py / install.sh  # host 注册 · 备份回滚
agent_mcp/               # daemon · execution · store_v4 · adapters · policies
packages/dsh-plugin/     # DSH bundle 插件（dsh-plugin-agentmcp）
web/                     # v4 控制台 + 仪表盘面板（含动效）
skill/                   # 编排 Skill（控制面）+ 内置 Agent
docs/                    # 架构 · ADR · 能力矩阵 · DSH/安装指南 · 品牌资产
tests/                   # 600+ 单测

文档

| 文档 | 用途 |
|---|---|
| install-guide.md | AI 可读安装说明 |
| dsh-integration.md | DeepSeek Harness 接入 |
| architecture.md · runtime.md | 三层职责 / 运行时边界 |
| capability-matrix.md | 适配器能力（✅/⏳） |
| custom-cli.md | 自定义 CLI 接入 |
| skill/SKILL.md | 编排 Skill 全文 |
| CHANGELOG.md | 变更记录 |

开发

python3 -m pytest -m "not integration" -q   # 单测（默认跳过真实 CLI 冒烟）
python3 start_agent_mcp.py --doctor         # 健康体检 JSON

许可证 MIT