# Klear-AgentForge 论文复现条件与项目差距审计

> 审计日期：2026-08-15  
> 状态：更新至2026-08-30。审计基线、公开Agent配置、64K服务探针及统一64K P0均已完成。P0中SFT与parent step20在test38均为6/38、Verified27按全部attempt均为9/27，配对检验无差异；项目据此停止追加PPO训练并阶段性归档。完整500题榜单复现和论文未公开参数仍未完成；腾讯云运行面已释放，不再安排上下文或单题恢复复测。  
> 目标：区分论文明确值、官方公开实现、模型默认值、当前项目值、建议值和未知项，避免把近似实验描述为论文复现。

## 1. 复现目标与边界

本项目涉及三个不同目标，必须分别报告：

1. **SFT 训练复现**：从 Qwen3-8B 和公开轨迹重新训练
   Klear-AgentForge-8B-SFT。
2. **公开 checkpoint 评测复现**：使用
   `Kwai-Klear/Klear-AgentForge-8B-SFT` 在 SWE-bench Verified 上复现论文结果。
3. **当前项目实验**：在经过双 Oracle 验证的 500 个合成 SWE-Smith 任务上执行
   Canary、GRPO smoke 和后续训练。

论文表 4 报告 Klear-AgentForge-8B-SFT 在 SWE-bench Verified 上为 38.2%；论文表 3
的 39.4% 属于经过 SFT、RL 和最终模型合并的 Klear-AgentForge-8B，不是纯SFT checkpoint
的结果。当前项目已分别评测两个checkpoint，不能混用其结果。官方 66K 数据卡另写 39.0%，
与论文存在口径差异。因此，除非使用同一
checkpoint revision、SWE-bench Verified 版本、Agent 配置和统计口径，否则不得把当前
500 个 SWE-Smith 任务的结果与 38.2%、39.0% 或 39.4% 直接比较。

## 2. 证据等级

本文使用以下标签：

| 标签 | 含义 |
| --- | --- |
| 论文明确值 | 论文正文明确写出，优先级最高 |
| 官方公开实现 | Kwai-Klear 官方仓库或数据集在固定 revision 下的实现 |
| 模型文件默认值 | Hugging Face checkpoint 自带配置；不等同于论文评测覆盖值 |
| 当前项目值 | 当前仓库代码、配置和已记录运行事实 |
| 建议复现值 | 后续基于证据制定的项目配置，不能冒充论文原值 |
| 未公开 | 当前一手资料不足，禁止猜测 |

对齐状态定义：

- **可精确对齐**：公开了确定值和实现，项目可以采用相同值。
- **可近似对齐**：目标明确，但底层版本、镜像或环境无法证明完全相同。
- **当前未对齐**：公开值存在，但项目当前值不同。
- **无法确认**：论文和公开实现没有足够信息。
- **无法精确复现**：缺少关键数据、代码或运行资产。
- **不适用**：属于不同模型阶段或不同实验口径。

## 3. 官方证据基线

主要一手资料：

- [Klear-AgentForge 论文](https://arxiv.org/html/2511.05951)
- [Klear-AgentForge-8B-SFT 模型](https://huggingface.co/Kwai-Klear/Klear-AgentForge-8B-SFT)
- [mini-swe-agent-plus 固定 revision](https://github.com/Kwai-Klear/mini-swe-agent-plus/tree/3dfa5e26831306978ff3cfa2da15b49113ded0e6)
- [官方 SWE-bench Agent 配置](https://raw.githubusercontent.com/Kwai-Klear/mini-swe-agent-plus/3dfa5e26831306978ff3cfa2da15b49113ded0e6/src/minisweagent/config/extra/swebench_add_edit_tool.yaml)
- [公开 66K SWE-Smith 轨迹](https://huggingface.co/datasets/Kwai-Klear/SWE-smith-mini_swe_agent_plus-trajectories-66k)
- [Qwen3 长上下文说明](https://qwen.readthedocs.io/en/stable/inference/transformers.html#enabling-long-context)
- [vLLM 模型长度校验](https://docs.vllm.ai/en/stable/api/vllm/config/model/)

论文明确说明：

- SWE-bench Verified 是 500 个真实 GitHub issue 的人工验证子集。
- SWE-bench Verified 评测使用 mini-swe-agent-plus，每个任务最多 200 steps，context
  length 为 64K。
- SWE 数据来自 SWE-Smith：先筛出约 12,000 个带合成问题描述的任务，再用
  mini-swe-agent-plus 蒸馏轨迹，最终约 66,000 条 SFT 样本。
- 官方删除与测试集仓库重叠的训练数据。
- RL 使用 revised GRPO：去除 KL、使用 DAPO 非对称裁剪、截断重要性采样，并对达到
  最大上下文、最大步数或超时的轨迹执行 oversampling 和 masking。
- RL 同时包含结果级二元奖励和一部分确定性工具任务的逐轮 exact-match 奖励。
- 系统采用 rollout/train 分离、异步奖励和每任务独立 sandbox。

## 4. 参数对齐矩阵

### 4.1 模型与评测

| 项目 | 官方证据 | 当前项目 | 状态 | 结论 |
| --- | --- | --- | --- | --- |
| SFT checkpoint | `Kwai-Klear/Klear-AgentForge-8B-SFT` | AutoDL 已下载并完成统一32K固定57题评测 | 可近似对齐 | 仍需记录模型文件digest、tokenizer和chat template digest |
| 模型阶段 | SFT 模型表 4 为38.2% | SFT与最终模型分开运行并记录 | 可对齐 | 不混用两个checkpoint结果 |
| 最终模型 | SFT + RL + merge 后为39.4% | 已完成统一32K固定57题评测 | 部分对齐 | 当前57题结果与SFT相同；不是完整500题或论文64K复现 |
| Agent | mini-swe-agent-plus | 已集成 Plus | 可精确对齐 | 需同时对齐配置，只有 Agent 名称相同不够 |
| Agent revision | 论文未写 commit；公开仓库可固定 | 固定 `3dfa5e26831306978ff3cfa2da15b49113ded0e6` | 可近似对齐 | 能对齐公开实现，不能证明就是论文内部 commit |
| 编辑工具 | 唯一匹配的多行字符串替换 | 已安装 `edit_via_str_replace` | 可精确对齐 | 需继续保持命令及错误语义一致 |
| SWE 上下文 | 64K | vLLM按65,536启动；8K、40K、64.5K探针与Canary前40K live gate均通过 | 可近似对齐 | 服务窗口与论文值一致；是否与论文内部RoPE/YaRN细节完全相同仍无法证明 |
| SWE step limit | 200 | `official-public-repro` 为200 | 可对齐 | 当前Verified Canary使用该profile |
| SWE 每轮 max tokens | 未写；公开 YAML 未设置 | official profile不额外注入，启动摘要为`max_tokens=unset` | 可对齐公开配置 | 仍不能声称已知论文内部值 |
| SWE temperature | 论文未单独写；公开 YAML 为 1.0 | YAML 未设置；GRPO train 1.0，val 0.7 | 无法确认论文值 | 可对齐公开 YAML，但不能称为论文明确值 |
| SWE top_p/top_k | 论文与公开 YAML 未写 | GRPO train top_p 1.0，val 0.8 | 无法确认 | BFCL/Aider 参数不得挪用 |
| 评测集 | SWE-bench Verified 500 | 固定27题诊断子集；由30题分层/仓库限额清单中镜像可用项派生 | 部分对齐 | 题目来自Verified，但样本不是500题无偏随机抽样 |
| 评测指标 | SFT 38.2%；数据卡 39.0% | 27题恢复口径10/27 = 37.04% | 小样本数值一致 | 与38.2%相差1.16个百分点；不得代替完整500题结论 |
| 容器与 harness revision | 未披露 digest | Harbor/ACK/TCR 自有环境 | 无法精确复现 | 可做功能等价验证，不能证明环境同一 |

### 4.2 Prompt 与 Agent 行为

| 项目 | 官方公开配置 | 当前项目 | 状态 |
| --- | --- | --- | --- |
| system prompt | Helpful assistant；每轮一个 Bash block；要求 THOUGHT | 自定义软件工程 Agent prompt | 当前未对齐 |
| instance prompt | `<pr_description>` 包装；明确只改非测试源文件 | `Solve the following issue...` 简化模板 | 当前未对齐 |
| 推荐流程 | 分析、创建复现脚本、编辑、重跑、测试边界 | grep/nl、最小修改、diff 检查等项目约束 | 当前未对齐 |
| 提交命令 | `echo MINI_SWE_AGENT_FINAL_OUTPUT && git add -A && git diff --cached` | `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` | 当前未对齐 |
| observation | return code + 输出；长输出头尾裁剪 | 未复用官方 observation 模板 | 当前未对齐 |
| 格式错误反馈 | 官方详细模板，再次提醒一个 Bash block | 使用 Plus 默认或项目简化模板 | 当前未对齐 |
| shell 状态 | 每个 action 在新 subshell 执行 | ACK sandbox 同类语义 | 可近似对齐 |
| 单工具、线性轨迹 | Bash action + 线性消息历史 | Plus 基础循环相同 | 基本可对齐 |

当前 Prompt 比官方公开 Prompt 增加了禁止重复相同 observation、限定 `grep`/`nl` 查看方式、
禁止备份和辅助脚本、编辑后强制 diff 检查等约束。这些可能提高工程稳定性，但会改变模型的
动作分布、轨迹长度和成功率，因此不能用于严格复现论文结果。

## 5. 每轮消息和环境反馈处理

固定 revision 的 Plus 默认循环如下：

1. 初始化一条 `system` 消息。
2. 加入包含任务描述的 `user` 消息。
3. 将当前完整 `messages` 交给 LiteLLM。
4. 将模型回复完整追加为 `assistant` 消息。
5. 从回复中解析唯一 Bash fenced block。
6. 在环境中执行命令。
7. 将执行结果渲染为 `user` observation。
8. 下一轮再次发送整条线性历史。

官方源码没有自动摘要、滑动窗口、删除旧轮次或仅保留最近 N 轮。模型回复和工具 observation
都会进入下一轮输入。论文也将 mini-swe-agent 描述为 single tool、linear trajectory。

官方 `swebench_add_edit_tool.yaml` 的 observation 规则：

- 输出少于 10,000 字符：回填 return code 和完整输出。
- 输出达到 10,000 字符：保留前 5,000 和后 5,000 字符，并报告中间省略字符数。
- 格式错误：作为 `user` 消息反馈，模型可继续纠正。
- 命令超时：作为 `user` 消息反馈，模型可继续纠正。
- 正常提交、step limit 和 cost limit：终止轨迹，不再调用模型。

当前本地 runtime schema v3 草案增加了基于上一轮 token usage 的请求前 context guard。这是项目
稳定性扩展，不是官方 Plus 行为；在决定是否启用前，应先确认 64K 服务策略以及 RL 对超长轨迹
的 masking 语义。

## 6. Prompt 对齐的可行性

官方 Prompt 和 observation 模板已在固定 revision 中公开，因此可建立独立的“论文公开配置
模式”。但仍只能称为对齐公开仓库，因为论文没有声明：

- 实验实际使用的 commit；
- 公开 YAML 是否在运行时被额外覆盖；
- LiteLLM、vLLM、Transformers 和镜像版本；
- SWE-bench 专用的单轮 token 与 sampling 覆盖值。

后续不应直接覆盖当前工程 Prompt。推荐保留两套明确命名的配置：

- `official-public-repro`：最大限度复用官方公开 YAML；
- `project-hardened`：保留当前防重复、最小修改、diff 检查和上下文保护。

上述双配置设计已于 2026-08-13 实施，详见第 10 节；它仍不代表已经完成论文复现。

## 7. 数据与训练差异

### 7.1 官方公开 SFT 数据

官方数据卡记录：

- split：仅 `train`；
- 数量：65,994；
- 字段：`instance_id`、`messages`；
- 未压缩数据约 4.64 GB，下载约 1.58 GB；
- 每条是 mini-swe-agent-plus 的端到端消息轨迹。

论文进一步说明，GitHub SWE 数据从 SWE-Smith 筛出约 12,000 个带合成问题描述的任务，
再通过 Plus 蒸馏多条轨迹。轨迹过滤会移除不能形成 submit-ready patch 的样本，并删除与
SWE-bench Verified 测试仓库重叠的数据。

#### 7.1.1 轨迹生成模型的证据边界

论文对不同数据域的披露程度不同：通用工具使用数据明确来自多种强模型，代码竞赛数据明确
混合目标 Qwen3-8B 与更强模型并验证输出；但 SWE 段落只说明每个问题通过
mini-swe-agent-plus 蒸馏新轨迹，没有公开该 66K SWE 轨迹所用模型的名称、占比或生成配置。
因此，不能据此断言公开的 65,994 条 SWE SFT 轨迹全部由强模型生成。

论文在 RL 数据筛选中另行说明：对 SWE SFT 样本使用一个未具名的强教师模型进行求解尝试，
只保留教师至少成功一次的任务。该描述属于 RL 任务筛选条件，不是公开 66K SFT 轨迹的生成
来源说明；论文也未公开相应 RL 任务 ID、任务数量、教师身份或筛选 rollout。

#### 7.1.2 公开轨迹不能直接判定 verifier 成功

[固定 revision](https://huggingface.co/datasets/Kwai-Klear/SWE-smith-mini_swe_agent_plus-trajectories-66k/tree/750b2c11239fd5e32f97e6cfb9bf80fb9a9a2983)
包含 65,994 行，公开 schema 只有 `instance_id` 和 `messages`，没有 `model`、`reward`、
`resolved`、`verifier_result`，也没有独立的最终 patch 字段。`messages` 中可以观察到提交命令、
模型自建测试或 shell return code，但这些只支持 `submit_ready` 或 `self_test_passed` 一类弱判断，
不能等价为官方 verifier 的 `reward=1`。

对公开 viewer 首行 `oauthlib__oauthlib.1fd52536.combine_file__otc4vogi` 的检查也符合这一边界：
轨迹包含 59 条消息，并以 `MINI_SWE_AGENT_FINAL_OUTPUT`、暂存和 diff 命令结束；前文虽出现模型
自建测试成功，但数据行没有提交命令执行后的 observation、官方 verifier 结果或 reward。
论文所述“过滤不能形成 submit-ready patch 的轨迹”也不等价于“每条公开轨迹均通过官方
测试”；论文提及曾考察执行测试进行过滤，但没有给出逐行成功标签或证明公开集全量通过。
因此，只有在对应任务环境中独立执行权威 verifier，才能把某条轨迹标记为成功。

### 7.2 当前项目数据

当前冻结集是 500 个可在线执行的合成任务：

- train / validation / test = 350 / 75 / 75；
- 覆盖 77 个仓库；
- 来自第三方 filtered SWE-Smith 候选；
- 经过静态检查、NOP 基线、Oracle 修复和 verifier 双向验证；
- 主要资产是问题、代码环境、容器镜像和 verifier，而非固定的 SFT `messages`。

两者用途不同：官方 66K 是离线 SFT 轨迹，当前 500 是在线 Agent RL/评测环境。不能把当前
500 简单描述为官方 66K 的小规模子集，也不能用其 Canary 通过率复现 SWE-bench Verified
指标。

### 7.3 训练实现差距

| 项目 | 论文 | 当前项目 | 状态 |
| --- | --- | --- | --- |
| SFT | 总 agentic 数据约 2.4B tokens；SWE 部分约 66K | 无完整 Klear SFT 重训管线 | 无法精确复现 |
| 公开 SWE SFT 轨迹生成模型 | SWE 段落未披露模型身份或混合比例 | 只能记录为未知 | 无法确认 |
| 公开 SWE SFT 成功标签 | 数据仅有 `instance_id`、`messages`，无 reward/resolved/verifier | 不能把提交标记或自测通过当作 reward 1 | 无法直接判定 |
| RL objective | revised GRPO、无 KL、DAPO 非对称裁剪、截断 IS | 明确配置为 GRPO；未证明其余三项一致 | 当前未对齐 |
| outcome reward | 格式正确且任务完成为 1，否则 0 | SWE verifier 最终 0/1 | 基本可近似对齐 |
| turn-level reward | 确定性工具任务逐步 exact-match | 当前 SWE 路线没有同类 ground truth | 当前未对齐 |
| 超长/超步/超时 | oversampling + masking | compact filtering、异常继续 verifier、context guard | 当前未对齐 |
| 系统架构 | rollout/train 分离、异步 reward | 每任务 sandbox 已有；默认训练配置并非论文同构 | 部分对齐 |
| 模型更新 | 论文未披露 LoRA/全参细节 | 默认 LoRA rank 32 | 无法确认 |
| 学习率 | 未披露 | `2e-5` | 无法确认 |
| group size | 未披露 | 默认 8 | 无法确认 |
| train sampling | 未完整披露 | temperature/top_p = 1.0/1.0 | 无法确认 |
| context | RL 轨迹涉及最大上下文 masking；具体训练长度未完整披露 | 32,768 | 无法精确对齐 |

## 8. 目前无法精确对齐的项目

除非作者补充配置、代码或不可变运行资产，以下项目必须标记为“未知”或“无法精确复现”：

- SWE-bench 每轮 `max_tokens`。
- SWE-bench 专用 temperature、top_p、top_k，以及模型默认参数是否被覆盖。
- 论文实际使用的 Plus commit 和 Python 依赖 lock。
- vLLM、Transformers、LiteLLM 的精确版本。
- 64K 使用的具体 YaRN/RoPE 参数和启动命令。
- SFT optimizer、学习率、batch、epoch、scheduler、packing 和完整数据混合比例。
- 公开 SWE SFT 轨迹的生成模型列表、各模型占比、sampling 和失败重试配置。
- SWE RL 筛选所用强教师模型的身份、候选任务 ID、保留数量和筛选 rollout。
- 公开 66K 是否逐条执行过官方 verifier，以及对应结果。
- submit-ready patch 过滤器和测试过滤器的完整实现。
- RL group size、batch size、学习率、clip 上下界和截断 IS 阈值。
- 超长、超步和超时轨迹的 oversampling 倍率与 mask 粒度。
- turn-level reward 子集及其 ground truth 构造代码。
- 论文评测容器 digest、SWE-bench harness revision、失败任务统计细节。
- SFT 38.2% 与公开数据卡 39.0% 差异的具体来源。

## 9. 64K 上下文的准确表述

64K 是论文对 SWE-bench Verified 的明确评测值，但不能只把 vLLM 的
`--max-model-len` 从 32768 改成 65536。Klear checkpoint 基于 Qwen3；Qwen3 原生预训练
上下文为 32,768，Qwen 官方建议使用 YaRN 扩展，典型 65,536 场景采用 factor 2.0。
vLLM 也会根据模型配置校验最大长度；无正确 RoPE 扩展而强制突破模型声明长度可能导致
数值错误或质量下降。

由于论文未披露具体 RoPE 配置，后续项目可实现“Qwen 官方推荐的 64K 近似复现”，但应与
“论文明确披露值”分开记录。

## 10. 已实施的公开资料对齐（2026-08-13）

### 10.1 修改范围

本轮只实现已公开且能够在本项目中明确验证的部分，没有操作 AutoDL，也没有修改正在运行的
vLLM、Canary 或训练任务。

| 修改项 | 修改前 | 修改后 | 对齐依据与状态 |
| --- | --- | --- | --- |
| Prompt 配置 | 只有项目强化 Prompt | 新增 `configs/agents/mini-swe-agent-plus-official-public-repro.yaml`，保留原 `project-hardened` 配置 | 固定 Plus revision 的 `swebench_add_edit_tool.yaml`；可对齐官方公开实现，不能证明是论文内部运行配置 |
| Profile 选择 | 无显式模式区分 | `MINI_SWE_AGENT_PLUS_PROFILE` 支持 `project-hardened`（默认）和 `official-public-repro` | 防止历史结果与公开复现结果混用 |
| Prompt 与 observation | 项目自定义模板 | official profile 对齐公开 system、PR wrapper、单 Bash action、长输出前后各 5,000 字符、格式错误反馈和提交命令 | 可精确对齐固定 revision 的公开 YAML |
| Agent 限制 | steps 100、cost 0、单轮 `max_tokens=896` | official profile 固定 steps 200、cost 3，不注入 `max_tokens` | 200/3 来自公开 YAML；每轮 max tokens 未公开，因此不猜测 |
| Sampling | 项目配置未显式复刻官方 YAML | official YAML 只声明 `temperature=1.0`、`drop_params=true`，未增加 top_p/top_k | 对齐公开 YAML；不得称为论文明确值 |
| 上下文 guard | 固定按 32,768、896 输出和 256 reserve 保护 | 参数化为 context/enable/reserve；official profile 为 65,536、guard 关闭、reserve 0；hardened 保持原值 | 64K/200 steps 为论文明确值；guard 是项目扩展，官方模式禁用 |
| 上下文一致性 | Agent、vLLM 声明可能静默不一致 | Canary/eval 要求 `CANARY_MODEL_CONTEXT_WINDOW` 与 profile 一致；训练要求 `TRAIN_MAX_MODEL_LEN` 一致 | 只完成启动前声明校验，未实现或验证 YaRN |
| 运行审计 | 日志不能完整区分模式 | Canary/eval/train 输出 Agent、profile、配置、context、steps、max tokens、sampling 来源和 dataset/split | 可追溯性增强，不改变论文算法 |
| Harbor/rLLM 透传 | Harbor 侧 context guard 为硬编码，训练必须有 max tokens | Harbor 参数化 context/guard/reserve；训练允许 official profile 不设置 max tokens | 支持两种配置语义；补丁已同步到 `patches/harbor-mini-swe-agent-plus.patch` |

official profile 配置文件 SHA-256 为
`681736ee9aaaa1a68d3dfe80fd437663236abebc1f6a2d69f6b5db2204109b22`。该摘要用于识别
本项目保存的公开配置副本，不是论文运行资产的摘要。

后续在 AutoDL 进入 official profile 前，`.env` 至少需要显式声明以下一致性契约；本轮没有
执行这些操作：

```bash
MINI_SWE_AGENT_PLUS_PROFILE=official-public-repro
CANARY_MODEL_CONTEXT_WINDOW=65536
```

这两行只允许脚本检查“服务声明值与 Agent 值一致”。必须先另行完成并验证 vLLM 65,536、
Qwen3 长上下文方案和长上下文探针，才能运行 official-profile Canary；不能用该声明绕过模型
真实能力验证。

### 10.2 涉及文件

- `configs/agents/mini-swe-agent-plus-official-public-repro.yaml`：官方公开复现 Prompt。
- `.env.example`：双 profile、上下文声明与 guard 参数示例。
- `scripts/lib.sh`：profile 解析及 Canary 模型上下文一致性校验。
- `scripts/40_canary.sh`、`scripts/55_eval_curated.sh`：profile 参数透传与运行审计。
- `scripts/50_train_grpo.sh`：训练上下文一致性校验、official smoke 长度和审计字段。
- `src/harbor_qwen_grpo_experiment/train_harbor_ack.py`：可选 max tokens 与 context 参数透传。
- `docker/minisweagent_context_guard.py`：支持显式关闭项目 guard。
- `upstream/harbor/src/harbor/agents/installed/mini_swe_agent.py` 与
  `patches/harbor-mini-swe-agent-plus.patch`：Harbor 参数化及可重建补丁。
- `tests/test_mini_swe_agent_plus_config.py` 与 Harbor 对应单元测试：配置、profile、校验和
  不注入 max tokens 的回归测试。

### 10.3 验证证据

- Shell 静态检查：`scripts/lib.sh`、Canary、训练和评测脚本均通过 `bash -n`。
- Python 静态检查：训练入口和 context guard 通过 `py_compile`。
- 项目测试：103项全部通过；包含Plus配置/运行时和offline-v3 verifier转换回归测试。
- Harbor 持久化补丁：对当前 Harbor 工作树执行 reverse apply check 通过，说明补丁包含当前改动。
- 本机没有安装 `pytest`，所以未在本机执行 Harbor 上游 pytest；新增 Harbor 测试已写入补丁，仍需在 AutoDL/标准 Harbor 开发环境运行。

### 10.4 历史结果影响

默认 profile 仍是 `project-hardened`，继续使用 32,768 context、896 max tokens、100 steps、
cost 0 和项目 guard。因此此前 Canary 与训练结果不会被重新解释或自动改写。只有显式选择
`official-public-repro` 的新任务，才属于“基于官方公开配置的近似复现”。两类结果必须分开统计。

### 10.5 尚未实施与不能声称已对齐的部分

- vLLM已按65,536启动并通过三档上下文探针；但论文内部的精确RoPE/YaRN细节未公开，仍只能标记为近似对齐。
- 尚未固定模型 revision、权重/tokenizer/chat template digest 和完整软件版本。
- 已引入固定Verified 27题诊断子集；完整500任务及论文对应harness/container digest仍未引入。
- 尚未复现官方 65,994 条 SFT messages 或论文的完整数据混合。
- 尚未实现 revised GRPO 的全部 DAPO clip、truncated IS、oversampling/masking 和 turn reward。
- 论文未公开的 max tokens、专用 sampling 覆盖、依赖锁和训练超参数仍保持未知。

因此当前完成状态是：**公开Agent配置、64K模型服务和固定27题Verified能力诊断已验证；
完整500题与论文级端到端复现尚未完成。**

## 11. 模型身份与 64K 启动前置审计（2026-08-13）

本阶段继续遵守“不擅自操作 AutoDL”：只在项目中增加可移植工具、校验和命令入口，没有连接
AutoDL、没有修改模型目录、没有启动或停止 vLLM。

### 11.1 已实现内容

| 能力 | 实现 | 输出或约束 |
| --- | --- | --- |
| 模型 provenance | `make model-audit` | 对 config、tokenizer、chat template、权重索引和全部 safetensors 分片计算 SHA-256；记录 repo、声明/本地检测 revision、模型结构、RoPE、Python/Torch/CUDA/GPU 和核心包版本 |
| 权重完整性 | 解析 `model.safetensors.index.json` | 任一索引分片缺失即失败；无权重文件也失败 |
| revision 审计 | 参数、HF snapshot 路径、下载 metadata 或 `REVISION` | 没有证据时明确写 `unknown`，不从模型名称猜 commit |
| 64K 计划 | `make klear-64k-plan` | 只生成 JSON 计划和不含 API key 的 vLLM 命令，不启动服务 |
| 64K 策略 | checkpoint context ≥ 65,536 时保持 checkpoint 原生配置；不足时才生成 YaRN fallback | 原生路径标记 `checkpoint-native-declared`；fallback 标记为 Qwen 官方建议近似而非论文参数 |
| vLLM 兼容 gate | 检查本机 `vllm serve --help=all` | 所有路径要求 `--max-model-len`；只有 fallback 才要求新版 `--hf-overrides`；不再要求已移除的 `--rope-scaling` |
| 三方 context gate | Profile、Canary 声明、64K target；训练另校验 `TRAIN_MAX_MODEL_LEN` | official profile 必须对应 65,536，避免只改一处 |
| 上下文探针 | `make klear-context-probe` | 对默认约 8K、40K、64.5K prompt 发请求；先实测重复单元的真实 token 增量，再在 context 硬上限内有界搜索；每档在本地 tokenization 前即原子记录 `running` 状态 |

新增文件为：

- `src/harbor_qwen_grpo_experiment/model_repro.py`
- `scripts/42_model_repro_audit.sh`
- `scripts/43_plan_klear_64k.sh`
- `scripts/44_probe_klear_context.sh`
- `tests/test_model_repro.py`

同时更新 `.env.example` 和 `Makefile`。审计产物默认写入 `state/model-repro/`，不会进入源码
目录，也不会保存 API key。

### 11.2 当前 checkpoint 的 64K 判定

AutoDL 只读审计已经确认：

- HF revision：`0da97e45dbbd44278bd55b878170ec369d2934fb`；
- vLLM：`0.22.1`；Transformers：`5.5.4`；
- `model_type=qwen3`、`dtype=bfloat16`；
- checkpoint 自身声明 `max_position_embeddings=65536`；
- `rope_scaling=None`。

因此当前 Klear checkpoint 的首选策略是 `checkpoint-native-declared`：只传
`--max-model-len 65536`，不注入 `--rope-scaling` 或 `--hf-overrides`。checkpoint 发布方已经
声明目标窗口时再强制添加 YaRN，会改变发布方配置，不能视为更接近论文。

单请求探针阶段曾固定`--max-num-seqs 1`，用于隔离KV cache并发压力；三档探针及1-task闭环通过后，
并发Canary配置提升为`--max-num-seqs 4`、`--max-num-batched-tokens 32768`、
`--enable-chunked-prefill`和`--gpu-memory-utilization 0.90`。32K scheduler batch限制同一调度批的
prefill token量，不降低每条请求的65,536上下文上限。文档中的128并发是未经容量测量的旧示例，
不再使用；若vLLM启动日志报告64K最大并发低于4，则将vLLM与Canary同步降为2。

这仍然只是“checkpoint 声明支持 64K”，不是质量验证，也不能证明论文采用相同 RoPE 服务配置。
短、长、边界探针仍是进入 Canary 前的必要 gate。

### 11.3 YaRN 回退方案

只有其他 Qwen3 checkpoint 的声明窗口低于 target 时，planner 才使用回退扩展。Qwen3 官方文档
说明预训练上下文为 32,768，并建议典型 65,536 场景使用 static YaRN factor 2.0。vLLM
0.22.1 已移除旧 `--rope-scaling`，新版接口是：

```json
{
  "rope_parameters": {
    "rope_type": "yarn",
    "factor": 2.0,
    "original_max_position_embeddings": 32768,
    "rope_theta": "从checkpoint读取"
  },
  "max_model_len": 65536
}
```

该 JSON 通过 `--hf-overrides` 传递；planner 禁止猜测 `rope_theta`，checkpoint 没有数值时直接
失败。这仍不是 Klear-AgentForge 论文披露参数，而且不适用于当前已声明 65,536 的 checkpoint。

### 11.4 后续 AutoDL 验收顺序（仅命令说明，本轮未执行）

1. 更新源码但不覆盖 `.env` 与 `state`。
2. 在 `.env` 填写真实 `KLEAR_HF_REVISION`；若暂时无法确定，则让 audit 输出 `unknown`，不得假填。
3. 运行 `make model-audit`，保存 provenance JSON。
4. 显式设置 official profile、`CANARY_MODEL_CONTEXT_WINDOW=65536`，运行
   `make klear-64k-plan`；人工检查版本警告和生成命令。
5. 经用户确认后单独启动 vLLM；该动作不包含在本项目的 plan target 中。
6. 服务健康后运行 `make klear-context-probe`；要求短、长、边界三档均无上下文拒绝或 OOM。
7. 再运行 1-task Canary，然后 10-task Canary；短上下文基线与 64K 近似结果分开报告。

### 11.5 验证状态

- model-repro 单元测试覆盖摘要、revision、缺失分片、checkpoint-native、YaRN fallback、
  `--hf-overrides`、context gate、64.5K 有界搜索、增量原子结果和无密钥单序列启动命令。
- 三个 Shell 入口通过 `bash -n`。
- 本地完整项目测试为83项全部通过，其中model-repro测试17项。
- 真实 16 GB 模型摘要、vLLM help gate、GPU 长上下文与 KV cache 容量只能在 AutoDL 执行，
  当前仍为待验收。

### 11.6 64K 探针停滞修复

首次 AutoDL 64K 探针没有生成 JSON，进程停在本地 prompt 构造，并出现
`196617 > 131072` 的 tokenizer 长度警告。根因不是 vLLM 的 `--max-num-seqs 1`，而是旧探针
把 `context_probe_token ` 的重复次数近似当作 token 数；该字符串在当前 tokenizer 中约产生
3 个 token，指数扩张因此构造出远超目标的本地候选。

探针现已改为：

- 先对空 chat、单个重复单元和 64 个重复单元做真实 tokenizer 测量；
- 根据实测增量估算重复次数，并用 `context_window - output_tokens` 计算保守上限；
- 只在估算点附近做有界搜索，不再从 1 开始指数翻倍；
- tokenizer 发出 sequence-length warning 时转为结构化失败；
- 每档在 tokenization、预算校验、HTTP 请求和完成阶段原子写入状态，进程中断后也可定位停点；
- probe schema 升级为 `klear-context-probe-v2`，记录估算诊断、实际 prompt token 数和剩余预算；
- 新增每单元 3-token 的回归测试，并断言所有候选不超过 65,504-token prompt 上限。

该修复只改变探针构造与审计，不改变模型、vLLM 服务参数、Agent、Canary 或训练配置。

### 11.7 Transformers 5 `BatchEncoding` 兼容修复

第二次AutoDL探针已生成结构化JSON，但8K、40K和64.5K三档均在
`local-tokenization` 阶段失败，错误为
`ValueError: probe unit did not increase tokenizer length`。该结果没有向vLLM发送HTTP请求，
不能解释为模型不支持长上下文。

根因是当前AutoDL使用Transformers 5.5.4。Transformers 5将
`apply_chat_template()` 的tokenized返回值统一为 `BatchEncoding`；旧探针直接执行
`list(result)`，实际得到 `input_ids`、`attention_mask` 等字典键，因而空prompt与重复prompt
都呈现相同的伪长度。

修复后的探针：

- 对Transformers 5的mapping返回值显式提取 `input_ids`；
- 同时接受旧版裸token列表和单样本批次形状，保持版本兼容；
- 拒绝多样本批次、缺失 `input_ids` 或非整数token，避免再次静默误计长度；
- 新增Transformers 5 mapping及单样本批次回归测试。

本地完整项目测试为83项全部通过。该阶段结论仅为探针工具已修复；实际服务结果见后续
11.8节。

### 11.8 8K/40K/64.5K服务探针全部通过

Transformers 5兼容修复部署后，AutoDL得到以下实测结果：

| 目标 | 本地prompt | 服务端prompt | HTTP | 结果 |
| ---: | ---: | ---: | ---: | --- |
| 8,192 | 8,193 | 8,193 | 200 | 通过 |
| 40,000 | 39,999 | 39,999 | 200 | 通过 |
| 64,512 | 64,512 | 64,512 | 200 | 通过；completion 32，总token 64,544 |

三档均为`stage=complete`、`status=passed`，本地chat template计数与vLLM服务端计数完全
一致。边界档延迟6.636秒，声明窗口剩余992 tokens；没有上下文拒绝或OOM。

实测空chat为8 tokens，单个重复单元后为12 tokens，但64个重复单元后为201 tokens：首个
单元增量为4，而进入长串后的边际增量为3。旧算法用首个增量4作为每次重复的硬上界，只允许
16,374次重复，候选停在49,131 tokens，因而错误报告目标不可达。

搜索上界现改为使用第1次到第64次之间的实测长串斜率，并以第64次样本为估算锚点；实际候选
仍逐次tokenize校验，不允许最终prompt超过65,504。新增回归场景精确模拟8/12/201的实测值，
可构造64,512-token prompt，且测试观察到的所有候选均未超过65,504。

本地完整项目测试现为85项全部通过，其中model-repro测试18项。AutoDL复测已证明当前
checkpoint与vLLM启动配置能够实际服务接近64K的单请求；这不单独证明长上下文任务质量，
也不证明论文使用了完全相同的RoPE服务参数。

### 11.9 64K Canary放行配置

探针通过后，Canary固定使用以下可审计组合：

```bash
HARBOR_AGENT=mini-swe-agent-plus
MINI_SWE_AGENT_PLUS_RUNTIME_SCHEMA=v3
MINI_SWE_AGENT_PLUS_PROFILE=official-public-repro
MINI_SWE_AGENT_PLUS_OFFICIAL_CONFIG_FILE=configs/agents/mini-swe-agent-plus-official-public-repro.yaml
CANARY_MODEL_CONTEXT_WINDOW=65536
MODEL_NAME=Klear-AgentForge-8B-SFT
```

`official-public-repro` profile固定200 steps、cost limit 3、64K context，不注入论文未公开的
单轮`max_tokens`，并关闭项目自定义context guard。runtime v3仍负责Plus Python与任务Python
隔离及运行时schema一致性。因此验收应记录`context_guard=false`，并要求vLLM无上下文400；
不能把项目guard触发视为该profile的通过条件。

执行顺序为1-task（concurrency 1、retry 0），通过后再运行10-task（concurrency 4、retry 0）。
每轮必须保留`RUN_PROFILE`行、job级与trial级`result.json`、ATIF trajectory、agent日志、verifier
reward以及对应vLLM日志区间。reward允许为0，但异常、缺失轨迹、缺失reward或上下文400不允许。
Canary入口同时强制校验runtime镜像必须精确等于当前Registry前缀、固定Plus revision和schema
组成的tag，并在`RUN_PROFILE`中输出schema、镜像、guard及reserve，防止只修改变量但仍注入旧镜像。

### 11.10 首次1-task空轨迹假成功与硬校验

首次runtime v3 + `official-public-repro` 1-task运行在64秒内结束，Harbor摘要显示Trials 1、
Exceptions 0、reward 0，但不能据此放行：trial的ATIF只有一个system step，`n_input_tokens`、
`n_output_tokens`和`n_cache_tokens`均为0，对应vLLM日志区间也没有模型请求记录。reward 0只是
verifier对未修改仓库的结果，不代表Agent完成过rollout。

Harbor公共执行层已经统一为命令前置`set -o pipefail`，因此本次不能归因于`tee`吞掉CLI非零
退出码。当前可确认的是Plus CLI以成功状态结束并留下system-only原始轨迹；具体提前退出原因仍
需结合保留job中的`agent/mini-swe-agent.txt`判断。

为禁止该状态再次被统计为成功，Plus运行命令现于CLI退出后使用注入的隔离Python读取原始
`mini-swe-agent.trajectory.json`，要求`messages`至少包含一个`role=assistant`或Responses API
的`object=response`模型轮次。文件缺失、JSON无效或没有模型轮次都会令agent命令非零退出，
进而写入trial异常；普通mini-swe-agent路径和已有预期step/context limit处理不变。

守卫后的第二次1-task已正确显示Exceptions 1与`NonZeroAgentExitCodeError`。原始CLI日志和轨迹确认
Plus 1.14.4在首次模型调用前因`'working_dir' is undefined`退出，`api_calls=0`，vLLM区间没有请求；
因此硬校验有效，reward 0仍不构成Canary通过。

固定提交的公开YAML使用顶层`environment`，但注入镜像内的1.14.4 CLI实际只消费旧顶层`env`，
运行时解析结果因而回落为`cwd: ""`、`timeout: 30`。为同时保持公开配置可审计和固定CLI可运行，
Harbor仅在Plus执行适配层把`environment`转换为`env`；若配置同时含两者则立即拒绝，避免静默覆盖。
普通mini-swe-agent不受影响，也不修改公开Prompt、sampling、step/cost/context契约。

带字段映射的第二次1-task表明运行时配置已正确解析`cwd: /testbed`和`timeout: 60`，但仍报告
`working_dir`未定义。这说明字段映射只修复了LocalEnvironment执行目录，没有补齐模板作用域：固定
Plus通用`mini`入口调用`agent.run(task)`，而公开配置面向的官方SWE-bench runner会额外传入
`working_dir`。Harbor现从已校验为非空绝对路径的`env.cwd`，在临时运行配置的
`instance_template`开头定义同值Jinja变量；源YAML保持不变，且空值或相对cwd会在运行前失败。

最终1-task已通过：Exceptions=0、`exit_status=Submitted`、`api_calls=37`、assistant与Shell
observation各37轮、输入/输出token为332761/4814、reward字段完整，且对应vLLM日志无上下文400
或OOM。累计输入token来自多轮请求，不表示单次请求超过65,536。现已放行10-task并发Canary。

### 11.4 Verified 27题Canary结果（2026-08-14）

固定27题子集使用 `Klear-AgentForge-8B-SFT`、`mini-swe-agent-plus`、
`official-public-repro`、runtime schema v3、65,536 context、200 steps和retry 0。原offline-v2
作业 `2026-08-14__14-03-48` 中25题正常评分，得到10个reward 1和15个reward 0；
`pallets__flask-5014` 因3000秒verifier超时异常，`sphinx-doc__sphinx-8621` 因
verifier目录下载失败异常。Harbor在27个请求上报告Mean 0.370。

offline-v3将parser改为只使用本地 `config.json` 的最小评分字段，不再调用会
触发GitHub访问的 `make_test_spec(datum)`，并增加60秒硬超时。两个异常任务分别在
`2026-08-14__15-38-50` 和 `2026-08-14__15-40-10` 复测为 `Exceptions=0, reward=0`。
因此恢复口径为10成功、17失败，即10/27 = 37.04%。

论文SFT点值为38.2%，两者相差1.16个百分点。该结果支持“当前checkpoint与评测链路
在固定27题小样本上表现与论文数值一致”，但不支持“已复现Verified 500榜单分数”。
同时，37.04%是一个原批次与两个异常恢复作业的合并统计，并非单一
`27 Trials / 0 Exceptions` 作业。

### 11.5 SFT与最终RL模型的统一32K比较（2026-08-15）

为比较可用于当前GRPO实验的基模，项目另行固定统一32K、mini-swe-agent-plus、runtime v3、
200 steps和retry 0口径，对SFT checkpoint和最终SFT→RL→merge checkpoint分别运行相同的
SWE-Smith30与SWE-bench Verified27：

| 模型 | SWE-Smith30 | Verified27 | 合计 | 异常 |
| --- | ---: | ---: | ---: | ---: |
| `Klear-AgentForge-8B-SFT` | 5/30 | 8/27 | 13/57 | 0 |
| `Klear-AgentForge-8B` | 5/30 | 8/27 | 13/57 | 0 |

因此，在这57个固定任务上没有观察到最终RL模型相对SFT模型的通过率增益。该结果只说明当前
样本和Agent口径下的点估计相同，不能推出两个模型逐题行为、生成分布或完整500题能力相同，
也不能与论文的64K、完整Verified结果直接互换。后续基模选择继续等待其他候选模型的同口径结果。

## 12. 后续实施建议与验收顺序

本文档确认后，后续修改应另行列清单并再次确认。建议顺序：

1. **已完成**：建立 `official-public-repro` 与 `project-hardened` 两套 Prompt 配置，禁止混用结果。
2. **已完成**：对齐公开 Prompt、observation 模板、提交命令、200 steps 和 cost limit。
3. **工具已完成、AutoDL 待完整归档**：固定模型 revision、模型文件 digest、tokenizer/chat-template digest和软件版本。
4. **已完成**：当前Klear checkpoint以原生65,536启动，三档探针和40K live gate通过；
   YaRN仅为其他短context checkpoint的回退方案。
5. 将单轮 max tokens、SWE sampling 等未知项作为实验变量，不标记成论文值。
6. **已完成小样本验证**：1-task、10-task和固定27-task Canary已运行；如需单一归档证据，在offline-v3下重跑27题并要求 `27 Trials / 0 Exceptions`。
7. 如要声称复现38.2%榜单结果，必须单独建立SWE-bench Verified 500-task评测流程。
8. 如要复现 SFT，单独下载并审计 65,994 条公开 `messages`，建立离线 SFT 管线。
9. 当前 500-task GRPO 继续作为独立项目实验，报告自身 split、reward 和训练配置。

## 13. 报告规范

后续每份结果至少记录：

- checkpoint/revision/digest；
- Agent commit、配置文件 digest 和 runtime image digest；
- dataset 名称、revision、split 和任务数；
- Prompt 模式；
- context、RoPE、max tokens、steps、sampling；
- vLLM/LiteLLM/Transformers/Harbor/rLLM/verl 版本；
- 并发、重试、超时和随机种子；
- exceptions、有效 trials、reward、通过率和统计口径；
- 该结果属于论文复现、公开实现近似复现，还是项目内部实验。

只要任一关键未知项仍未解决，结果应写成“基于公开资料的近似复现”，不得写成“完全复现
Klear-AgentForge 论文”。

## 14. 267题freeze上的64K Canary与PPO边界（2026-08-17）

项目已将`Klear-AgentForge-8B-SFT`用于`swesmith-curated-grpo-267-v1` validation的确定性30题抽样。使用`mini-swe-agent-plus`、`official-public-repro`、runtime schema v3、65,536 context、并发8和retry 0，作业`state/harbor-jobs/2026-08-17__16-14-11`得到12/30、Mean 0.400、Exceptions 0，耗时32m46s。

该30题来自新freeze validation，不是第11.5节统一32K SWE-Smith30，也不是完整SWE-bench Verified；只能证明当前模型、新数据、TCR、ACK runtime和64K服务链路可用。后续计划的critic+GAE PPO使用该SFT checkpoint作为初始化，但属于项目内部独立对照实验。Klear公开训练方案是revised GRPO，因此任何PPO结果都不得写成论文训练方法复现。

## 15. 项目PPO能力评测与上下文缺口（2026-08-22）

项目PPO已完成两轮20步，但三模型单次正式结果未显示随训练步数稳定提升：SFT/parent/current在test38分别为4/38、6/38、4/38，在Verified27按全部attempt分别为4/27、6/27、6/27。test38使用40K与256-token guard；Verified27的Agent profile实际为32K，即使共享的vLLM以40K启动也不能写成40K评测。

同一固定Verified27的历史约64K SFT恢复口径为10/27，当前offline-v3完整单作业32K SFT为4/27。该-6题观察差提示长上下文可能重要，但历史值由offline-v2主批次和2个offline-v3异常恢复任务拼接，不能视为严格context A/B。后续只在当前完整配置上把Agent和服务端context同时提高到65536并逐题配对；在结果产生前，不把差值全部归因于上下文，也不把项目PPO结果写成Klear论文RL复现。