DM-Code-Agent

<div align="center">

本地优先、可审计、有算法骨架的 Python Code Agent

中文 | English | Français

</div>

一句话：DM-Code-Agent 是一个把 ReAct + Planner + Replan + Trace 写在 ~1500 行可读 Python 里的代码维护 Agent；v2 已落地默认关闭的 Reflexion / Critic / Self-Consistency / Adaptive Replan 模块，并接入 SWE-bench Lite Tier-1 评测链路。

>

它不是要做又一个聊天黑盒，而是要做一个开发者能看懂、能复现、能扩展、能拿来对比研究的 Code Agent baseline。

Why this project

• 可审计 (Auditable)：每一步的计划、工具调用、观察结果都写入 JSONL trace，trace 自带 dry replay、显式 tool replay 和离线 diff，调试不靠"再问一次模型"。
• 可对标 (Benchmarked)：项目自带 coding 与 maintenance 两套 hidden-test benchmark，并已发布 SWE-bench Lite DeepSeek Tier-1 baseline：0.0% resolved / 72.0% patch-applied on the fixed 50-instance subset。这个 Tier-1 数字受 host verifier 环境噪声影响，不能和官方 leaderboard 直接比较；真实 ablation 仍在冻结，现有离线报告都附 raw JSON。
• 有算法 (Algorithmic, v2)：不是"调用 GPT-4 并写个 ReAct"。Reflexion、Critic、Self-Consistency、Adaptive Replanning 都是默认关闭的模块化能力，并有 keyless 测试与 research log。真实 SWE-bench ablation 等允许的 live run 后再补。
• 可扩展 (Extensible)：内置 Skill 系统 + MCP 集成，任务激活领域 prompt 与专用工具；4 家主流 LLM 适配（DeepSeek/OpenAI/Claude/Gemini），可加自定义 base_url。

v.s. 同类项目（当前公开口径）

表中的 SWE-bench Tier-1 baseline 已在 P1 落地；leaderboard-comparable 分数需要 Tier-2 Docker verifier。当前冻结真实 SWE-bench / Docker / cross-model 跑分，因此 v2 算法模块只声明代码、测试和离线报告能力，不声明真实分数提升。 进度见 docs/research-log/ 与 CHANGELOG.md。

Algorithm Highlights（v2 status）

Research Log

DM-Code-Agent 的每个非平凡设计决策都会留下 devlog：动机、实验、ablation、踩坑、下一步。 入口：docs/research-log/。已发布：

• 00 — Kickoff: Why a v2 algorithm-track upgrade?
• 01 — SWE-bench Lite baseline: harness, sampling, and the road to numbers
• 02 — Reflexion: episodic memory across trials
• 04 — Critic and self-consistency: peer review before acceptance
• 05 — Adaptive replanning and token economics
• 06 — Final write-up: v2 algorithm stack
• Distribution checklist
• Interview talking points

DM-Code-Agent 是一个面向真实代码维护任务的轻量 Code Agent。它在本地工作区中运行，能够调用文件、搜索、测试、lint、代码分析和 MCP 工具，并把每一步计划、工具调用、观测结果和最终报告记录为可审计 trace。

它的目标不是做一个黑盒聊天机器人，而是做一个开发者可以检查、复现、评测和扩展的代码维护助手。

适合做什么

• 修复小到中等规模的 bug，并运行测试验证。
• 补充回归测试，避免只修 visible case。
• 分析项目结构、函数签名、依赖和代码指标。
• 执行小型重构或文档一致性修复。
• 生成 trace 和 benchmark 报告，用于审计 agent 的行为质量。

核心能力

快速开始

git clone https://github.com/hwfengcs/DM-Code-Agent.git
cd DM-Code-Agent

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

copy .env.example .env
dm-agent --help

Linux/macOS:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
dm-agent --help

在 .env 中填入至少一个模型 API key 后运行：

dm-agent "分析当前项目结构，列出最适合优先测试的模块" --provider deepseek --show-steps

Trace 与 Replay

默认 trace 不保存完整 prompt 和 raw response，只记录可审计摘要、工具输入输出和执行结果：

dm-agent "修复 retry.py 的重试边界，并运行测试" \
  --provider deepseek \
  --trace traces/retry-fix.jsonl \
  --report reports/retry-fix.md

dm-agent-trace view traces/retry-fix.jsonl
dm-agent-trace analyze traces/retry-fix.jsonl
dm-agent-trace analyze-dir bench_reports/traces
dm-agent-trace replay traces/retry-fix.jsonl

analyze 会离线标记首个失败阶段、恢复链路、验证缺口和 trace health，不调用模型也不执行工具。

比较两次 run 的计划、工具调用和最终结果，不调用模型也不执行工具：

dm-agent-trace diff traces/baseline.jsonl traces/critic-enabled.jsonl

如果需要私有调试，可以显式记录完整 LLM I/O：

dm-agent "解释这个模块" --trace traces/debug.jsonl --trace-llm-io

--trace-llm-io 可能包含源码、路径、命令输出或模型上下文，只建议在本地私有环境使用。详见 docs/tracing.md。

Benchmark

查看 coding benchmark：

dm-agent-bench --list

查看更真实的 maintenance benchmark：

dm-agent-bench --suite maintenance --list

运行一次真实模型维护任务：

dm-agent-bench --suite maintenance \
  --provider deepseek \
  --task config_precedence \
  --output bench_reports/maintenance.json \
  --markdown bench_reports/maintenance.md \
  --trace-dir bench_reports/traces

报告会包含 hidden-test pass rate、95% 置信区间、agent completion rate、平均步骤、工具调用、token 估算、改动文件列表、文件约束违规、任务 manifest 指纹；启用 --trace-dir 时还会附带离线 trace analysis。详见 docs/benchmarks.md。

离线生成 token 经济学报告（不调用模型、不联网）：

dm-agent-economics bench_reports/swebench_lite_baseline.json \
  --label swebench-tier1-baseline \
  --cost-per-1k-tokens 0.00027 \
  --output-json bench_reports/economics.json \
  --output-md bench_reports/economics.md

--cost-per-1k-tokens 是显式输入的本地会计参数，不是实时价格查询。

默认关闭的算法模块也可以接入 coding / maintenance benchmark plumbing，用于本地 smoke 或后续真实实验：

dm-agent-bench --suite maintenance \
  --enable-critic \
  --self-consistency-runs 3 \
  --self-consistency-strategy test_pass

这些开关只在真实 benchmark run 时触发额外模型调用；CI 只验证 keyless 参数解析和 fake-result plumbing。SWE-bench Lite 的 self-consistency 在真实评测冻结期会明确拒绝运行，避免误报新分数。

Context Memory

长对话会使用本地 Mem0 风格策略压缩：旧消息被提取成 episodic / semantic / procedural 原子记忆，按当前任务检索为 <agent_memory>，同时保留最近轮次原文。

架构

DM-Code-Agent architecture

flowchart LR
    User[Developer CLI] --> Main[main.py]
    Main --> Agent[ReactAgent]
    Agent --> Planner[TaskPlanner]
    Agent --> Tools[Built-in Tools]
    Agent --> Skills[SkillManager]
    Agent --> Memory[Mem0-style ContextCompressor]
    Agent --> Trace[TraceWriter]
    Tools --> Workspace[Local Workspace]
    Tools --> MCP[MCPManager]
    Agent --> LLM[LLM Client Factory]
    LLM --> DeepSeek
    LLM --> OpenAI
    LLM --> Claude
    LLM --> Gemini

项目结构

DM-Code-Agent/
├── main.py
├── dm_agent/
│   ├── core/          # ReactAgent and TaskPlanner
│   ├── tools/         # file, execution, test, lint, AST tools
│   ├── tracing/       # JSONL trace writer and trace CLI
│   ├── benchmarks/    # coding and maintenance benchmark suites
│   ├── evals/         # deterministic and real-model eval runners
│   ├── mcp/           # MCP config/client/manager
│   ├── skills/        # built-in and custom skill system
│   └── memory/        # context compression
├── tests/
├── docs/
├── benchmarks/
├── evals/
└── pyproject.toml

本地验证

python -m compileall dm_agent main.py tests
python -m pytest
python -m dm_agent.evals.cli --variant full --task direct_finish
python -m dm_agent.benchmarks.cli --suite maintenance --list
python -m ruff check .
python -m black --check .

当前测试、确定性 eval 和 benchmark manifest 检查都不依赖真实 API key。

文档

• docs/research-log/：v2 算法升级的设计动机、实验、ablation 与踩坑记录
• docs/release-v2.0.0.md：v2 发布说明和 smoke checklist
• docs/product.md：产品定位和落地场景
• docs/tracing.md：trace schema、view、replay 和隐私边界
• docs/benchmarks.md：benchmark suite、评分和报告字段
• MCP_GUIDE.md：MCP 配置
• SKILL_GUIDE.md：内置和自定义 skill
• CHANGELOG.md：版本变更

Roadmap

v2 本地算法栈已经按 docs/research-log/00-kickoff.md 的路线图交付到 P6： SWE-bench Lite Tier-1 baseline → Reflexion → Critic + Self-Consistency → Adaptive Replanning + 离线 token economics → README/write-up 发布素材。

冻结项：Docker/Tier-2 SWE-bench、真实 cross-model 跑分、以及任何 v2 机制的真实分数提升声明，都会等允许的真实评测后再补。

短期持续在做的非算法方向：

• Trace completeness：把 trace analyzer 接入 benchmark report，标记缺失 trace、验证缺口和 replay 风险。
• Tool replay sandbox：为危险工具提供更明确的隔离执行策略。
• Maintenance benchmark 扩展：加入文档一致性、CI 配置修复、跨文件重构和多轮修复任务。
• Run report：自动生成改动摘要、验证命令和剩余风险。

发布记录见 CHANGELOG.md。

贡献

欢迎提交 Issue 和 PR。建议先阅读 CONTRIBUTING.md、SECURITY.md、AGENTS.md 与 CODE_OF_CONDUCT.md。

如果你的工作有算法决策或非平凡 ablation，请同步在 docs/research-log/ 留下一篇 devlog。

License

MIT License. See LICENSE.