CodeMason README

The project's README from github.com/mufengyuan6/CodeMason. As one markdown file: README.md.

编舟 · CodeMason

CodeMason 不保存任何状态——记忆是投影,回滚是重放,审计是回看。因为一切皆事件,所以敢让 AI 写更少:写错了回滚,写对了复用,每一步都有据可查。

CodeMason 是 Claude Code / Cline 同级的自主编码 Agent:理解需求 → 规划 → 改码 → 验证 → 交付,全链路自主完成。与市面上"把状态当真相"的工具相反,它以事件流为唯一真相(状态永不保存、只从事件推导),因此敢让 Agent 写得更少(YAGNI 独立确定性验证 Hook)——写错了可回滚,写对了可复用,每一步都完全透明可审计。

核心特性

核心特性

架构

headless 内核(Python 进程,--mode rpc / run)
    │  Event Queue(core→界面):TurnStarted / MessageDelta / ExecApprovalRequest / ItemCompleted
    │  Op Queue(界面→core):UserTurnStart / ApprovalResponse / UserTurnCancel / Compact
    ▼
协议层(Op/Event 双向契约,schema 版本化 + Op 幂等)
    ├── JSONL 持久化(append-only 事实源 + flock 写锁)
    ├── OTel 导出(prompt / 审批 / 工具 / 沙箱轨迹)
    └── WebSocket 广播(Web 驾驶舱,多标签页共享会话)
Web 驾驶舱(React 18 + Vite)← 唯一界面
Agent Loop(手写状态机 + 事件流)
  ├── Plan 模式:architect 强模型 → 规划 / 反思归因 / 只读
  ├── Act 模式:editor 快模型 → 10 内置工具(Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch/Monitor/AskUser)
  ├── 控制平面:PolicyEngine 策略判定 → LoopScheduler 调度 → LoopBudget 记账 → OpRouter 按 Op 分派
  ├── 变更控制:工具执行 → staging diff → Hook 验证(YAGNI/安全/权限)→ 落盘 → Git Checkpoint
  ├── 执行沙箱:SandboxProvider(默认 Firecracker microVM,L1-L4 可换)——沙箱内无凭据、网络白名单
  ├── 安全分类器:Tier3 动作 → 两阶段判决(allow/block/alternative/escalate)→ 拦截件进审批收件箱
  ├── 记忆:session / project / global 三层 + T1-T5 压缩
  └── 审计:全部事件落盘 + OTel 导出 + AI 贡献报告(Co-Authored-By trailer)

驾驶舱是任务工作台而非仪表盘集合——三区信息架构:

┌─────────────┬─────────────────────────────┬──────────────┐
│  左·会话栏   │   中·事件流主流程             │  右·监控抽屉  │
│ 列表/新建/恢复│ 审批内联可操作 · 交付横幅      │ 文件/成本/    │
│             │ 首次引导卡 · 任务输入          │ YAGNI/上下文/ │
│             │                             │ 健康信号/贡献  │
└─────────────┴─────────────────────────────┴──────────────┘

切换会话 = 换 JSONL 重放(事件溯源兑现),审批阻塞点始终在事件流内即时可见,监控一律抽屉化不稀释主流程。收件箱语义:人类只审被拦截/存疑的动作(分类器放行的照跑)。

技术栈

快速开始

# 1. 克隆
git clone https://github.com/mufengyuan666/CodeMason.git
cd CodeMason

# 2. 环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 3. 启动驾驶舱(默认 127.0.0.1:8765)
python -m src.web.server

# 4. headless 模式(自动化 / CI)
python -m src.cli.main run --task "修复 xxx"
python -m src.cli.main rpc --task "读取 README 并总结"   # 结构化事件输出

Docker 部署:

docker compose up --build
docker run -p 8765:8765 codemason

测试与评测

pytest tests/ -v        # 单元测试(Agent Loop / 协议 / 安全 / 工具 / 记忆 / 压缩 / 沙箱 / 分类器 / Team / 投影)
cd frontend && npx playwright test   # E2E(WebSocket 事件推送 / 审批交互 / 收件箱)

评测体系(自建任务集 + 同模型对照):

CodeMason (mufengyuan6/CodeMason)

Searching Database…

Что это?CodeMason (编舟) — автономный агент для кодинга в одном классе с Claude Code или Cline: он понимает требование, планирует, правит код, проверяет результат и сдаёт его, выполняя весь цикл самостоятельно. Он построен вокруг идеи, что состояние никогда не сохраняется — всё выводится из append-only журнала событий, поэтому любое изменение можно воспроизвести, откатить или проверить аудитом.
Это CLI-агент вроде Claude Code или что-то другое?Это самостоятельно размещаемое веб-приложение, а не единый CLI-бинарник: бэкенд на Python FastAPI + WebSocket управляет панелью-«кокпитом» на React 18 с областями для таймлайна событий, входящих подтверждений, доски YAGNI, обзора затрат/контекста и просмотрщика кода только для чтения.
Как его запустить?Quick Start в README указывает на развёртывание через Docker, так что вы поднимаете его с помощью Docker/Compose, а не устанавливаете вручную.
Нужен ли мой собственный API-ключ LLM?Да — по умолчанию CodeMason использует iFlytek (讯飞) в качестве поставщика модели, но подключаемая абстракция Provider позволяет заменить его на OpenAI или Ollama, с отдельными ролями модели «architect» (планирование) и «editor» (исполнение).
Насколько надёжен классификатор безопасности, блокирующий опасные действия?На собственном тестовом наборе из 100 команд он блокирует около 89% опасных команд и сообщает о 0% успешных prompt-инъекций на 720 сценариях при доле ложных срабатываний менее 1% — это не идеально, поэтому три блокировки подряд автоматически передают задачу человеку-согласующему.
Что именно проверяет движок YAGNI?После каждой генерации независимый хук статического анализа прогоняет подготовленный diff через семиуровневую лестницу решений (действительно ли это нужно, есть ли это в библиотеке, может ли stdlib это сделать и т.д.) и сообщает о сокращённых строках, избежанных зависимостях, дублирующих реализациях и оценке читаемости.
Какие бэкенды песочницы доступны для запуска кода?Абстракция SandboxProvider поддерживает четыре взаимозаменяемых бэкенда: microVM Firecracker (по умолчанию, изолированное ядро + KVM), укреплённый Docker-контейнер, gVisor (runsc) как промежуточный уровень или облачную песочницу E2B.
Как измеряется производительность CodeMason в сравнении с Cline?Та же модель запускается в Cline на идентичном бенчмарке из 30 задач (исправления багов, фичи, рефакторинги, тесты, адаптированные из SWE-bench и реальных issue), а результаты сравниваются по доле fail-to-pass и разбиению точности/полноты на уровне инструментов из TRAJEVAL, так что меняется только реализация агента.
Что такое самоэволюционирующий движок?Замкнутый цикл (Observe→Analyze→Improve→Verify→Persist), который со временем улучшает память, навыки, планирование, использование инструментов и сам harness, управляемый ограничивающим темп EvolutionPolicy с поэтапным развёртыванием shadow→canary→полное и автоматическим откатом.
Size
2.1 MB
Stars
176
Updated
CommitAug 21
Age
2mo
Commits · 90 Days