- MCP 工具名 mcp__<server>__<tool> 各段净化为 ^[a-zA-Z0-9_-]+: 合法名零改写(既有 --allow/持久化权限规则不受影响);非法字符连段折叠为 单下划线并追加原名 FNV 短哈希(不同原名不撞名、跨会话稳定);展示层仍用 原始名。修复中文命名的 MCP server 导致整个请求被网关 502 拒绝 - UI 输入框 Enter 发送加 isComposing 守卫:输入法选字/确认候选不再误发送 (对话 composer 与新建会话输入框)
mc-agent — MonkeyCode 本地 Agent 内核
自研编码 agent 内核(M1 headless CLI + M2 localhost WS 宿主)。直接在本机工作区执行编码任务:自主读代码、改文件、跑命令、验证结果,全程流式输出,支持会话恢复。
设计文档:docs/superpowers/specs/2026-07-12-local-agent-design.md
安装
需要 Go 1.25+(仅构建时;产物为零依赖单二进制):
cd agent
make install # 构建并安装到 ~/.local/bin/mc-agent
或手动构建:make build(产物在 bin/mc-agent),交叉编译六平台:make cross。
配置
三种方式,优先级 flag > 环境变量 > 配置文件:
# 写入配置文件(~/.config/mc-agent/config.json,权限 0600)
mc-agent config set \
--provider anthropic \
--base-url https://<你的网关>/api/anthropic \
--api-key sk-xxx \
--model <模型或路由别名>
mc-agent config get # 查看(key 打码)
环境变量:MC_AGENT_PROVIDER / MC_AGENT_BASE_URL / MC_AGENT_API_KEY / MC_AGENT_MODEL,数据目录 MC_AGENT_DATA_DIR(默认 ~/.local/share/mc-agent)。
provider 支持 anthropic(Anthropic Messages 协议)和 openai(Chat Completions 协议,兼容多数国产模型网关)。
使用
# 单任务(在当前目录作为工作区)
mc-agent run -p "修复 calc 包的测试失败"
# 指定工作区
mc-agent run --dir ~/dev/myrepo -p "给 HTTP handler 加上超时中间件"
# 交互式对话
mc-agent chat
# 会话管理
mc-agent sessions # 列出历史会话
mc-agent chat --resume <会话ID> # 恢复会话继续对话
# worktree 隔离模式(工作区须为 git 仓库)
mc-agent run --worktree -p "..." # 改动发生在独立 git worktree,原仓库不动
mc-agent worktree list # 列出隔离工作区
mc-agent worktree diff <会话ID> # 审查改动
mc-agent worktree apply <会话ID> # 应用回原仓库(不产生提交)
mc-agent worktree drop <会话ID> # 丢弃全部改动
权限模型
本地没有沙箱兜底,默认策略:
- 只读操作(读文件/搜索/git 查询)自动放行;
- 写文件、编辑、未知 bash 命令 → 终端询问(y/n/a 始终允许/d 始终拒绝);
- 危险命令(
sudo、rm -rf /等)直接拒绝; --allow write_file --allow edit_file预授权指定工具;--yolo全部放行(仅限受信环境/eval);- 审批时选「此项目永久」会把规则写入
<项目>/.mc-agent/permissions.json,后续会话直接生效(可手动编辑该文件的allow/deny列表)。
文件类操作强制限制在工作区目录内(含 bash 的 cd 越界拉回)。
MCP(扩展工具)
配置 MCP server(格式与 Claude Code/opencode 同构),其工具会自动注入 agent:
// ~/.config/mc-agent/mcp.json(全局)或 <项目>/.mc-agent/mcp.json(项目级,覆盖全局)
{
"mcpServers": {
"context7": { "url": "https://mcp.context7.com/mcp", "headers": {"Authorization": "Bearer xxx"} },
"playwright": { "command": "npx", "args": ["@playwright/mcp"], "env": {} }
}
}
mc-agent mcp list # 连接并列出各 server 的工具与连接状态
- 工具名命名空间化为
mcp__<server>__<tool>,避免冲突; - 传输支持 stdio(
command)与 Streamable HTTP(url); - 权限:MCP 工具默认走审批,仅 server 声明
readOnlyHint的工具自动放行;--allow mcp__<server>__<tool>可预授权; - 单个 server 连接失败只告警跳过,不阻塞启动;连接随会话建立与关闭。
技能(Skills)
技能 = 一个含 SKILL.md 的目录,注入系统提示作为按需知识索引(agent 相关任务时自行 read_file 文档),来源三级、同名按 项目 > 全局 > 平台 覆盖:
<项目>/.mc-agent/skills/<name>/SKILL.md # 项目技能(随仓库走)
~/.config/mc-agent/skills/<name>/SKILL.md # 全局技能(个人积累)
# 平台技能:mc-agent login 后由 MonkeyCode 平台下发,缓存于 ~/.cache/mc-agent/platform/
SKILL.md 支持可选 frontmatter,缺省取目录名与正文首段:
---
name: deploy
description: 部署到测试环境的完整流程
---
# 正文:步骤、脚本用法、注意事项……
mc-agent skills # 列出当前可用技能与来源
全局/平台技能目录对 read_file 只读放行(写与编辑仍严格限定工作区)。
子代理(task 工具)
主 agent 可把开放式的探索/检索任务(如"找出鉴权逻辑在哪、怎么工作")委托给只读子代理:子代理在独立上下文里用 read_file/grep/glob/git 探索,只把结论返回主上下文——翻阅的大量文件内容不挤占主任务上下文。子代理无 bash/写/编辑能力、不可再派子代理,故整体只读、自动放行无需审批;用量计入会话累计。
子代理过程全程可观测,两层结构:
- 进度通道:子代理每一步工具调用实时外显,挂在 task 调用卡片下(CLI 缩进
↳ ✓ 读取 auth.go,UI 嵌套渲染);这是通用原语——bash 长命令的最新输出行也经同一通道外显; - 子会话:子代理完整帧流落盘为真实子会话(
mc-agent sessions --all可见,列表默认隐藏),可独立回放;serve 模式下 UI 点 task 卡片的"查看子会话"即可实时跟看或事后复盘。
serve 模式(WS 宿主 + 浏览器界面)
mc-agent serve # 默认 127.0.0.1:7439,每次启动随机 token
mc-agent serve --token xxx # 固定 token(桌面壳托管时用)
多模型:宿主(桌面壳)可经 MC_AGENT_MODELS=<清单.json> 下发模型列表([{name, provider, base_url, api_key, model, default}]),内核只消费不管理。每个会话创建时可选模型,会话中可随时切换(session_set_model,轮次间生效;消息历史为归一化格式,跨 provider 续聊安全)。无清单时退回单配置。
启动后终端会打印界面地址(形如 http://127.0.0.1:7439/#<token>),浏览器打开即可:创建会话(选工作区,可选 worktree 隔离)→ 对话(Markdown 渲染)→ 流式输出/工具过程/计划 → 写操作在页面上弹审批卡片(允许/本会话始终/此项目永久/拒绝)。
页面顶部「改动」标签页展示本轮修改的文件(A/M/D),点击查看着色的 unified diff。
界面是 ui/ 下的 React 工程(Vite 单文件构建,产物 cmd/mc-agent/uidist/index.html 入库,go build 不依赖 node);改 UI 后:
cd ui && npm install && npm run build # 重新生成 uidist,再编译内核生效
协议(桌面客户端/IDE 插件对接同一套):
GET /healthz;GET/POST /api/sessions(Bearer token);WS /ws?session=<id>&token=<t>:下行为帧序列(先回放历史再实时);上行user-input/user-cancel/permission-resp;call/call-response(只读同步查询,不进事件日志):repo_file_list/repo_read_file/repo_file_changes/repo_file_diff,供 UI 文件浏览与 diff;- 安全:仅绑 loopback、随机 token、WS 同源 Origin 校验、慢消费者断开重连回放。
评测(eval)
mc-agent eval --tasks eval/tasks --report report.json
任务定义:eval/tasks/<名称>/task.json(prompt + check 判分命令 + files/ 工作区夹具),在隔离临时目录执行,退出码 0 视为通过。输出通过率、步数、token 用量。
架构位置
本内核是本地版桌面产品的执行核心。对外协议为流式帧
{type, kind, data(base64), timestamp, seq},与云端任务流一致(ACP 风格
session update),会话事件日志(events.jsonl)即帧序列——M2 的
mc-agent serve(localhost WS 宿主)与桌面 UI 直接消费同一协议。
cmd/mc-agent CLI(run/chat/sessions/config/eval/serve)
internal/loop 主循环:LLM ↔ 工具,中断/恢复/步数上限,上下文压缩(阈值/溢出触发)
internal/provider anthropic + openai 客户端,SSE 流式,tool-call 归一化与修复,退避重试
internal/tools read/write/edit/bash/grep/glob/git/todo,工作区边界强制
internal/mcp MCP 客户端:stdio/HTTP 传输,工具适配为内核工具(命名空间化)
internal/workspace git worktree 隔离(create/diff/apply/drop)
internal/repo 只读文件浏览与 diff 查询(call/call-response 后端)
internal/policy 权限规则引擎(工具×路径×命令,allow/deny/ask)
internal/contextmgr 系统提示装配(项目规则 AGENTS.md/CLAUDE.md、仓库树摘要)
internal/session JSONL 事件日志 + 消息快照,resume
internal/frame 流式帧协议(与云端对齐)