# Companion 源码分析：本次验证记录

日期：2026-09-08（Asia/Shanghai）。

正文：`companion-source-analysis.md`。
离线复核脚本：`companion-verification.py`。

## 源码身份

- 本地上游：`/home/lingdu/workspace/agent/M-agent`。
- 本次 HEAD：`48a011e2f950287735bce1c12eca50b1cdaad4e7`。
- Python：上游现有 `.venv`，`Python 3.13.13`。
- 文章的 69 个固定源码/测试/ADR 引用均使用完整 SHA。
- 已以本地 `git show <SHA>:<path>` 验证文件存在、行号有效，且引用文件的本地
  内容与 Git 对象逐字一致。此项不是每条 GitHub URL 的 HTTP 可达性认证。
- 未使用未跟踪的 Durable Run 文章作为固定源码事实的替代；它仅为写作顺序参照。

## 本次测试

以下命令均在上游目录执行。使用现有环境，不安装依赖、不调用真实供应商模型、
不访问凭据。没有将 pytest 从源码运行冒充 wheel 安装验收。

### 1. Session

```bash
.venv/bin/pytest -q \
  tests/test_m_agent_session.py \
  tests/test_m_agent_sqlite_session.py \
  tests/test_m_agent_session_scenario.py
```

结果：`118 passed, 38 subtests passed in 9.00s`。

覆盖共享 InMemory/SQLite Session 行为、跨 Scope、历史冻结、Claim/CAS、提交
pending/conflict、Session scenario。Scenario 的证据等级按自身声明读取，
不因内部使用子进程或 SQLite 就升级为完整 HOST/PROVIDER/FIELD 验收。

### 2. Context、Routing、Eval

```bash
.venv/bin/pytest -q \
  tests/test_m_agent_context.py \
  tests/test_m_agent_context_plan.py \
  tests/test_m_agent_compression.py \
  tests/test_m_agent_routing_contracts.py \
  tests/test_m_agent_routing_integration.py \
  tests/test_m_agent_routing_store.py \
  tests/test_m_agent_routing_fallback.py \
  tests/test_m_agent_routing_publish.py \
  tests/test_m_agent_eval_execute.py \
  tests/test_m_agent_eval_observe.py \
  tests/test_m_agent_eval_projection_evaluator.py \
  tests/test_m_agent_eval_judge.py \
  tests/test_m_agent_eval_recovery.py \
  tests/test_m_agent_eval_baseline.py \
  tests/test_m_agent_eval_recommendation.py
```

结果：`287 passed, 25 subtests passed in 2.28s`。

### 3. Store、Report 与快照

```bash
.venv/bin/pytest -q \
  tests/test_m_agent_eval_store.py \
  tests/test_m_agent_eval_store_contract.py \
  tests/test_m_agent_eval_report_metrics.py \
  tests/test_m_agent_routing_snapshots.py \
  tests/test_m_agent_routing_cost.py
```

结果：`70 passed in 1.20s`。

以上三批文件互不重叠，共 475 个测试项通过，另有 63 项 subtests 通过。
这不是全仓回归数量，也不是历史 release 的测试数量。

### 4. 公共 API smoke 与负向复现

```bash
env PYTHONPATH=src .venv/bin/python \
  /home/lingdu/workspace/agent/per-web/.scratch/m-agent-content-rebuild/articles/companion-verification.py
```

本次标准输出：

```json
{
  "two_turn_smoke": "PASS",
  "snapshot_version": 2,
  "second_run_history_messages": 2,
  "create_ack_loss": {
    "reproduced": true,
    "first_run_status": "CREATED",
    "claim_released_after_error": true,
    "followup_admitted": true,
    "model_calls_before_followup": 0
  },
  "evidence_scope": "offline public API; injected Store acknowledgement loss"
}
```

脚本第一部分使用公开 API 和确定性 Adapter，验证两轮提交、第二 Run 的冻结
History、Session version 与 Claim 清除。

第二部分用 InMemoryRunStore 子类包装公开 `create_run`，在父实现完成写入后
抛一次异常，模拟已提交但确认丢失。SessionRunner 释放 Claim，第一 Run 保持
CREATED，后续 submit 获准并完成。这个结果是实现缺口的复现，不是修复后
回归通过，不声称内置 SQLite 发生了同样的自然故障。

该脚本刻意断言当前缺口存在；上游修复后它应失败并要求重新分析文章，而不是
为了保持绿色把缺口描述继续保留下去。

## 静态与编辑检查

- 正文 3 个 Python fenced snippets 均通过 AST 语法检查。
- 在上游环境加载了这 3 个代码片段，公开 imports 与函数定义通过；没有以未初始化
  的真实应用参数执行函数体。真实运行范围仅为上面的配套 smoke。
- 固定引用定义均可解析，正文使用的引用 ID 均已定义。
- 文章选择保持单篇，明确区分设计决策、实现事实、作者推断、本次结果。
- Session 的创建异常缺口通过故障注入复现；Context Stage、Sizer 和 Frame
  持久化差异依据当前实际控制流记录，不以枚举值或注释宣称能力交付。
- Routing/Eval 第 5–7 节经过独立只读事实抽查，未发现明确的事实或公开 API
  签名错误；主代理另行完成引用、代码片段和本次测试结果的最终核对。

## 未执行与非目标

未修改上游源码，未修复发现的实现缺口；未把本票扩展为新功能开发。
未修改正式网站页面，未运行网站构建或浏览器测试，未提交、推送或部署。
未使用真实模型、生产业务数据或外部通知系统；未作生产容量、供应商质量、
操作系统沙箱、跨库事务、全局并发调度或自动模型推荐采纳的保证。