一个面向低延迟交易系统研发的 coding agent：不仅能改代码，还能自己写 benchmark、跑 perf、做 A/B 交替测量、用统计显著性判定自己的改动是否真的有效。
量化性能优化是极少数具备客观 reward signal 的 agent 任务（p99 延迟是硬数字，不是模型自评）。因此本项目能回答绝大多数 AI 应用项目回答不了的问题：你怎么知道它真的有用？
主线身份是低延迟 C++ 工程师，agent 是「把自己的优化方法论工程化」的载体。设计文档见 PLAN.md。
quant-coding-agent/
├─ kernel/ # Agent 执行内核（来自 Claude-Code-reproduce，改包名）
│ ├─ application/ # 主循环 / 五层上下文治理 / 工具装配 / 子代理
│ ├─ domain/ # todo / task / message bus / skills / approvals
│ └─ infra/ # 统一 LLM 网关 / shell / workspace / token 计费
├─ knowledge/ # 代码知识层（来自 agentic-rag-plus，重定向到代码检索）
│ ├─ index/ # tree-sitter AST 切片 + 符号索引(BM25) + 向量索引(Qdrant)
│ ├─ retrieve/ # 混合检索(RRF) + find_refs
│ └─ corpus/ # 演示语料（订单簿/SPSC/撮合/工具）
├─ quant/ # ★ 量化性能优化闭环（差异化核心）
│ ├─ host/ # 机器就绪自检（不达标拒绝出数字）
│ ├─ bench/ # 基准脚手架（绑核/预热/rdtscp/百分位）
│ ├─ perf/ # perf stat/record/c2c 采集 + 结构化解析
│ ├─ ab/ # A/B 交替 + 块自举 + Mann-Whitney U
│ ├─ loop/ # ★ 闭环状态机：把上面这些串成带硬门禁的一条流水
│ ├─ backtest/ # 沙箱 + 指标 + 置换检验反过拟合
│ └─ review/ # 热路径规则引擎 + LLM 去误报
├─ skills/ # 10 个 quant-* playbook（SKILL.md，被 SkillLoader 加载）
├─ eval/ # 24 题评测集 + 判定 + 跑分 + 消融
├─ server/ # FastAPI 最小服务（/task /ab /health）
├─ web/ # Vue 单页（执行轨迹 + 延迟分布对比）
├─ mcp_server/ # quant 工具以 MCP 协议暴露
├─ deploy/ # docker-compose: qdrant + backend + frontend
└─ tests/ # 60 项单元测试
- 两套 LLM 封装合一 ——
kernel/infra/llm.py（chat + tool-binding）与services/llm_factory.py（chat + embedding）合并为单一 gateway，加入 token 计费统计（kernel/infra/usage.py）。 - 两套多代理机制合一 —— 保留内核 subagent / teammate 真实机制。
- RAG 从文档检索改为代码检索 —— tree-sitter 切片 + 符号 BM25 + 向量混合，强制
file:line锚点。
# 1. 依赖
python -m venv .venv
.venv\Scripts\activate # Windows
pip install -r requirements.txt
pip install -r requirements-dev.txt # 含 pytest
# 2. 配置模型（.env）
# MODEL_ID="deepseek-chat" / DEEPSEEK_API_KEY=...
# 或 qwen 系列 / openai 系列
# 3. 测试
pytest tests
# 4. REPL
python -m kernel.runtime
# 5. 代码语料摄入（P1）
python -m knowledge.ingest knowledge/corpus --no-vector
# 6. 评测跑分 / 消融（P3）
python -m eval.ablationREPL 内置命令：/compact /tasks /team /inbox /approvals /approve <id> /reject <id>。
| 目录 | 来源 | 职责 |
|---|---|---|
kernel/ |
Claude-Code-reproduce | 主 Agent Loop、工具运行时（只读缓存 + 写失效）、多代理协作、五层上下文治理、统一 LLM 网关 |
knowledge/ |
agentic-rag-plus | tree-sitter AST 切片 + 符号 BM25 + Qdrant 向量 + 混合检索（grep_symbol/search_code/find_refs） |
quant/ |
★ 全新 | 机器自检 / bench / perf / A-B 显著性 / 优化闭环状态机 / 回测 / 热路径评审 |
skills/ |
quant-* playbook | 可被 load_skill 加载的领域知识 |
eval/ |
★ 全新 | 24 题评测集 + 判定器 + 跑分 + 消融表 |
server/ web/ |
agentic-rag-plus | 精简 FastAPI + 单页前端 |
mcp_server/ |
★ 全新 | quant 工具以 MCP 协议暴露 |
- 五层上下文治理：工具结果裁剪 → microcompact → session-memory-first compact → context collapse → legacy fallback（
kernel/application/compression.py+session_memory.py）。 - 代码检索防幻觉：所有命中强制携带
file:line锚点；符号名走 BM25 精确匹配，语义意图走向量，RRF 融合。 - 性能闭环防自欺：四道硬门禁串成状态机（
quant/loop/），见下节。 - 热路径评审：规则引擎保召回与确定性，LLM 保准确率。
项目的心脏。host/ bench/ perf/ ab/ 是四个叶子能力，它们之间原本没有任何
约束关系——host_check 出一份报告但没人拦着你无视它，ab_test 吃两个现成数组
因而默认路径恰好是「改前跑一次、改后跑一次」。loop/ 把它们串成一条状态机，
并在转移上装了四道绕不过去的门：
┌──────────────────────────────────────────┐
opt_start │ ① 就绪门 机器不达标 → 拒绝出数字 │
↓ │ 旁路需显式声明，此后全程 unreliable │
[baselined] └──────────────────────────────────────────┘
↓ 编译基线二进制 + 绑核测量 + perf 归因证据
opt_propose ┌──────────────────────────────────────────┐
↓ │ ② 归因门 必须声明 TMA 象限 / perf 证据 / │
[proposed] │ 预期指标，且预期指标不得等于裁决指标 │
↓ └──────────────────────────────────────────┘
〔改一处代码〕 同时对目标文件打内容快照
↓ ┌──────────────────────────────────────────┐
opt_verify │ ③ 单点门 diff 超过 1 个 hunk → 拒绝验证 │
↓ │ ④ 自欺门 显著改善但预期指标没动 → 挂起 │
↓ └──────────────────────────────────────────┘
┌───┴────┬─────────────┐
落盘 回滚 挂起
新基线 记「此路不通」 opt_accept（写明理由）/ opt_abandon
| 门 | 挡住什么 | 实现 |
|---|---|---|
| 就绪门 | 在没调好的机器上产出「看起来很精确」的垃圾数字 | host_check 的 fail 项阻断状态转移；旁路后每个数字与每条日志都带 unreliable |
| 归因门 | 凭直觉改代码，事后再编一个理由 | 改动之前登记 TMA 象限 + perf 证据 + 预期指标；预期指标必须是闭环能独立测出来的量 |
| 单点门 | 一轮改三处，收益归因不到任何一处 | 快照 → 当前内容的 unified diff 数 hunk（相邻几行算一处），超限拒绝验证且不销毁改动 |
| 自欺门 | 运气改对，却把错误经验沉淀进 session memory | 预期指标未朝预期方向动 ≥2% 时判「原因不明」，挂起不落盘，要么给书面理由要么回滚 |
ABAB 交替，不是「改前一次、改后一次」。 基线二进制在改动前就编译好并留存， 验证时两个二进制交替执行，机器漂移因此成为共模噪声被差分抵消。
块自举，不是对原始样本做 iid bootstrap。 延迟样本存在强序列相关（热漂移、
缓存与分支预测器状态、邻核干扰）。直接对几十万条原始样本重采样会得到宽度趋近于 0
的置信区间，于是任何微小差异都被判成 improved——防自欺机制反而成了自欺工具。
闭环先把样本按连续时间块归约（每块内样本量足够撑起目标分位数，见
effective_batches），再对块统计量重采样，顺带把 bootstrap 的计算量从
O(n_boot × n) 降到 O(n_boot × 块数)。
判定与效应量分开报告：ab 给出置信区间与 p 值，回答「是不是真的变快了」；
effect 由两侧合并摘要算出全局分位数变化，回答「快了多少」。块统计量的绝对值
系统性高于全局 p99，混用会明显高估改善幅度。
opt_start(target_file="orderbook.hpp", hot_func="bench_sink += book.top_n(5);")
opt_propose(change_summary="把红黑树换成扁平数组存首 N 档",
tma_quadrant="backend-bound",
evidence="perf stat: LLC-load-misses 占指令数 1.8%，IPC 仅 0.6",
expected_metric="llc_miss_rate")
# …改一处代码…
opt_verify() # 通过则落盘成为新基线，否则自动回滚并记「此路不通」
opt_status(report=True)opt_status 会带出历史上所有走不通的路径，下一轮提案前先看它，避免反复否定
同一个想法。
pytest tests # 115 项：内核 / 知识层 / 性能闭环 / 评测体系
python -m quant.loop.smoke # 端到端冒烟：真编译 + 真绑核测量 + 真回滚（需 Linux）覆盖：运行时行为、工具全覆盖、session memory、token 计费、AST 切片、BM25、混合检索、机器自检、bench 生成、perf 解析、A-B 统计与块自举、四道闭环门禁、快照与回滚、优化日志、热路径评审、回测指标、评测判定与打分。
闭环的状态机逻辑用注入的假执行器完整单测，不依赖真机；quant.loop.smoke 则在
Linux 上跑真实的 g++ 编译与绑核测量，验证执行器本身。