FinAgent-RL：金融多跳证据 Agent 的可验证后训练工程

FinAgent-RL 的目标是将公开金融问答与自建 SEC 证据语料统一为可追溯数据，组合 BM25、BGE-M3、 证据图、RRF 和 CrossEncoder 检索，并以 Qwen3-4B LoRA SFT 与 verl Agentic GRPO 训练 search → open → calculate → answer 的多轮工具行为。

这个仓库的核心目标不是“跑过一次 RL”，而是让数据、检索、轨迹、奖励、训练和评测都可审计。 计划目标与真实结果严格分开；没有 run card、冻结预测和统计报告支持的数字，不会写进简历。

当前状态（2026-08-30）

模块	状态	已落盘证据
Python / GPU 环境	driver-v6 preflight 与 runtime-v2 vLLM 8K 主 Gate 已通过	reports/preflight_driver_v6.json 与 reports/smoke/vllm_gpu0_driver_v6_runtime_v2.json 为当前真实 PASS；reports/smoke/driver_binding.json 固定 570.144 的 CUDA/PTX-JIT/NVML 三库且 cold-PTX probe 通过；更早 smoke 只作历史
公开数据	已构建并通过当前自动审计	45,939 examples、372,323 chunks；Gold evidence 映射率 100%；见 reports/data_audit.json
公开数值程序	历史封存指标通过，当前代码重放 MEASURED_FAIL_GATE	r2 封存时 35,006 条 calculator programs 全部可执行且答案等价；当前 calculator hash/provenance 已漂移，必须用 fresh run-id 重封存，不能继续当 current Gate
FinRank	已隔离为 evaluation-only	1,185 questions；禁止训练和调参；见 data/eval/finrank/manifest.json
MultiHiertt	train/dev 已并入已审计主语料	保留 8,873 examples；固定 GitHub/Hugging Face revisions；见 docs/licenses/MULTIHIERTT.md
自建 SEC 数据与检索	自动 build 与 split-isolated Recall@30 已通过；人工 Gate 未发生	repaired corpus 为 700/150/150、563,549 chunks；Top-30 全量 Recall@30=0.947173；真正 human-review v2 仍缺失，owner waiver 不能替代
本地模型缓存	三个 manifest 已完整	现有 manifests 声明 Qwen3-4B 使用 environment-proxy policy、BGE-M3 与 reranker 使用镜像 direct policy；revision、文件大小与 SHA256 均落盘；缓存命中不证明本次发生网络传输
当前四源检索	历史 full-dev 数值保留，当前代码重放 MEASURED_FAIL_GATE	sealed-r2 的 5,047-dev 曾通过逐来源 Gate且 p95=220.36ms；现 runtime code closure 漂移，需 fresh 重跑后才能恢复 current Gate
Shadow frontier（非 formal）	已完成	从 38,289 条 train 中确定性选择 12,000 个候选，每题生成 4 条轨迹（48,000 条），经 combined-train reachability、Gold 命中与 0 < pass@4 < 1 筛出 1,317 条 GRPO train
不可变实验登记	IMPLEMENTED_UNVERIFIED / BLOCKED	固定 42-cell 主矩阵、条件消融、append-only hash-chain ledger 与只读 audit 已实现；最终 combined/formal artifacts 和 clean commit 未齐，因此尚无 executable registry 或已完成实验
Shadow combined / SFT（非 formal）	MEASURED_PASS_SHADOW_TRAINING_ONLY	r11b 使用 8,000 条轨迹完成 500/500 steps；matched 5,170-dev 与 2,951-test SFT baselines 已落盘。r5 失败仍保留为历史诊断
Full-shadow GRPO（非 formal）	MEASURED_PASS_SHADOW_GRPO_AND_DEV_DIAGNOSTIC_ONLY	双 RTX 5090 完成 Stage A 250 + Stage B 400；checkpoint-400、5,170-dev 和独立 held-out test comparison 均已封存
内部 held-out test	MEASURED_INTERNAL_HELD_OUT_TEST_DIAGNOSTIC_SINGLE_SEED	同一 2,951 个 test IDs/order、seed 42：Stage B 相对 SFT 综合评分 0.5504→0.6163（+6.59pp，paired bootstrap 95% CI +5.57～+7.62pp），terminal-valid 0.8512→0.9607
Formal Oracle / SFT / GRPO	functional smoke 有证据；main 链仍 BLOCKED	5-step GRPO smoke 仅证明 provisional 兼容；genuine review、formal combined、main Oracle/SFT/GRPO 与 frozen test 均未完成
Formal frozen test / Demo	骨架已实现，未完成最终验收	已执行一次内部 single-seed held-out test，但不是 formal/frozen；正式三 seed manifest、外测、录屏与发布包仍缺失
CPU mini reproduction	已验证	runs/reproduce-mini-v2 含恰好 100 条项目自有 synthetic 样例；真实 data→index→tools→reward→16 参数线性模型训练/保存/加载→留出评测→report，且二次隔离 artifact SHA 一致
代码质量	持续检查	发布前以 make quality 的当次结果为准，不在 README 固化会随测试增长而失效的用例总数

旧四源 document-scoped v1 和 2026-08-21 的 retrieval-v2 full-dev 结果均保留，不覆盖、不删除； 但当前报告会重新核对代码和输入 seal，发生漂移时按 fail-closed 降为当前 Gate 失败。SEC repaired 检索的自动 Gate 与 public retrieval Gate 分开记录，任何一个都不替代人工审核或 formal combined。 完整进度、数据用途和 formal blocker 见项目总进度，招聘者可引用的 统一指标与证据入口见 RESULTS.md。内部机器状态文件不进入公开发布 bundle。

最新内部实测结果

同一 Agent runtime、同一 2,951 条内部留出 test（FinQA 1,138、TAT-QA 1,663、SEC 150）上的 严格配对结果如下。它是 seed 42 的内部诊断，不是公开榜单、formal/frozen 或多 seed 结论。

指标	SFT r11b	Stage B checkpoint-400	Stage B - SFT
综合评分	0.550409	0.616296	+0.065887
answer	0.507164	0.563828	+0.056664
grounding	0.652773	0.766390	+0.113617
terminal-valid	0.851237	0.960691	+0.109454
tool-response errors / example	0.171128	0.062013	-0.109116

综合评分差值的 10,000 次 paired bootstrap 95% CI 为 [+0.055675, +0.076236]。公开展示层的统一 结果口径、逐来源拆分和证据入口见 RESULTS.md。

系统结构

FinQA / TAT-QA / ConvFinQA / MultiHiertt / SEC 10-K
                         │
                adapters + schema + hashes
                         │
          split isolation / dedup / evidence audit
                         │
     BM25 ─┬─ BGE dense ─┬─ BGE sparse ─┬─ graph BFS
           └────────────── RRF ───────────┘
                           │
                    CrossEncoder rerank
                           │
              search / open / calculate tools
                           │
              Oracle trajectories → LoRA SFT
                           │
          grounding-first → correctness-heavy GRPO
                           │
        internal held-out diagnostic / formal frozen evaluation

核心公共对象是 CanonicalExample、Chunk、Trajectory、RewardBreakdown 和 RunCard。 工具调用采用 Qwen3 Hermes <tool_call> JSON 语义；引用必须来自本轨迹实际打开的 chunk； calculator 使用 AST 白名单，绝不执行 Python eval。详细边界见 中文架构说明。

5 分钟 CPU Quickstart

当前公开版本支持从源码 checkout 后以 editable 模式运行；训练配置、脚本和 synthetic mini 样例属于仓库资源。构建出的 wheel 用于检查 Python 包完整性，暂不宣称是可脱离源码仓库运行的 PyPI/standalone CLI。

git clone <your-repository-url> finagent-rl
cd finagent-rl
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
make reproduce-mini MINI_OUTPUT=runs/reproduce-mini-quickstart

该命令只使用项目自带的 synthetic 数据，在 CPU 上跑通 data → retrieval → tools → reward → mini training → held-out evaluation → report，并验证重复运行的 artifact hash。它不下载 SEC、模型 权重或受限数据。

完整 GPU / 训练环境

在仓库根目录执行：

conda create -n finagent_rl python=3.11 -y
conda activate finagent_rl
python -m pip install -e '.[retrieval,training,rl,demo,dev]'
FINAGENT_PYTHON="$(command -v python)" bash scripts/bootstrap_verl.sh --install --direct
python -m pip check
finagent report env-lock
finagent preflight

RTX 5090 必须在训练前额外确认 sm_120、两卡 CUDA matmul、Qwen3-4B vLLM 8K 生成和目标合同的 功能 smoke。依赖已安装不等于 GPU Gate 通过。已完成的 full-shadow GRPO 使用双卡 FSDP2 actor 与 两个 TP1/internal-DP1 vLLM async replica（每卡一个）共置/分时运行，GRPO 继承 SFT adapter 的 LoRA r=32；不是静态地把 一张卡永久分给 actor、另一张卡永久分给 rollout。参见 资源可行性和 ADR-0001。

大文件下载：默认直连，可按源切换

公开数据和 Hugging Face 模型缓存命令默认使用 --direct：仅在该同步下载调用期间移除 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 及小写变量，并设置 NO_PROXY=*；调用结束后恢复 原环境。这适合模型权重、数据压缩包等大流量请求，不会永久修改 shell。

固定 verl 源码的 bootstrap 同样默认直连；它会把网络模式同时用于 git fetch、源码压缩包 curl 和可选的 pip 安装。源站必须经代理时显式运行 bash scripts/bootstrap_verl.sh --install --proxy。本地索引、训练、评测和回环工具请求不属于 外部大文件传输，不添加代理开关。

# 公开数据默认直连
finagent data download --sources finqa,tatqa,convfinqa,finrank,multihiertt --direct \
  --manifest-out data/manifests/public_downloads_20260820_r2.json

# LOFin 有独立的 test-only 下载链；不经过训练 loader
finagent data download-lofin --direct

# 当前三个模型缓存 manifest 所声明的 network policy
finagent model cache --component qwen --proxy
HF_ENDPOINT=https://hf-mirror.com finagent model cache --component embedding --direct
HF_ENDPOINT=https://hf-mirror.com finagent model cache --component reranker --direct

若需要使用 Hugging Face 镜像，可在命令前设置 HF_ENDPOINT；它决定访问端点， --direct/--proxy 决定是否继承代理环境，二者含义不同。每个成功模型缓存目录必须包含 manifest.json。若只有部分 .safetensors 分片而没有 manifest，视为未完成，不得用于训练。

截至 2026-08-20，三个缓存均已完成：

• .cache/models/qwen3_4b/manifest.json：Qwen/Qwen3-4B，固定 revision， network_mode=environment_proxy；
• .cache/models/bge_m3/manifest.json：BAAI/bge-m3，通过 https://hf-mirror.com 直连；
• .cache/models/bge_reranker_v2_m3/manifest.json：BAAI/bge-reranker-v2-m3，通过同一镜像直连。

“缓存完整”本身只表示本地文件与 manifest 可用；GPU、SFT smoke 和 GRPO smoke 的验证必须分别 引用 preflight、训练 audit 与 run card，不能从缓存状态推导。

数据流水线

全局参数必须放在子命令前，例如 finagent --dry-run data download。

# 下载固定 revision；FinRank 自动保持 evaluation-only
finagent data download --sources finqa,tatqa,convfinqa,finrank,multihiertt --direct \
  --manifest-out data/manifests/public_downloads_20260820_r2.json

# 构建当前已批准的公开训练语料
finagent data build-public --sources finqa,tatqa,convfinqa,multihiertt \
  --download-manifest data/manifests/public_downloads_20260820_r2.json \
  --examples-out data/processed/public_20260820_r2/examples.jsonl \
  --chunks-out data/processed/public_20260820_r2/chunks.jsonl \
  --manifest-out data/manifests/public_build_20260820_r2.json
finagent data build-finrank
finagent data download-lofin --direct
finagent data build-lofin
finagent data audit
finagent data audit-programs --output reports/program_audit.json

public_downloads.json 与 public_build.json 是已被既有语料/索引/运行绑定的只读历史 manifest， 其单一许可字段现标记为 HISTORICAL_LICENSE_METADATA_STALE，不会原地改写。每次刷新必须使用新的 run-id 路径；新 manifest 分别记录 code_license、data_license、官方证据 URL、配置 SHA256 与 上游输入 SHA256。新 build 通过审计并重建所有下游绑定前，不替换当前运行使用的 corpus。

自建 SEC 数据必须提供可联系的 SEC User-Agent，并遵守 fair-access：

export SEC_USER_AGENT='Your Name your.email@example.com'
finagent data sec-manifest
finagent data sec-download
finagent data sec-build
finagent data audit

在 SEC 合成集满足 issuer 隔离、目标数量、证据映射、程序执行和双重验证之前，不能把 “1,000 条 SEC 多跳 QA”写成已完成事实。FinRank、LOFin 永不进入训练；FinReflectKG 在许可 明确前不下载、不训练、不正式评测。数据治理细节见 数据与 RL 审计和 许可证清单。LOFin 的 pinned revision、ND 发布边界和“只有页 locator、 没有 PDF 页正文”的检索限制见 LOFin 外测手册。

SEC review queue 的 qualitative、4-hop 和低 fact-confidence 难例可先运行确定性的本地 query rewrite/qualitative draft。外部 reviewer 默认关闭且没有隐式 HTTP 实现；只有显式 enable、注入明确 provider/model 并提供环境变量凭据后才能调用。逐请求 ledger 记录 provider/model/prompt/request/ response/decision/cost，累计 ¥450 告警、¥500 前置硬停止。任何 teacher/API 结果都只是 UNVERIFIED 建议，不能替代程序、证据或人工 final Gate。详见 SEC 难例审核手册。

构建和评测检索

# 分别构建 train/dev BGE-M3 dense+sparse 索引；工具服务会按 split 路由
finagent index build \
  --split train \
  --output-dir data/processed/index/train_bge_m3 \
  --device cpu \
  --batch-size 8

finagent index build \
  --split dev \
  --output-dir data/processed/index/dev_bge_m3 \
  --device cpu \
  --batch-size 8

# 当前 formal Gate：默认绑定 sealed program-v2，先 dry-run，再用 fresh output 跑 full dev
finagent --dry-run --run-id retrieval-v2-preview index evaluate-v2 \
  --profile scoped_hybrid_v2_graph_free_c80_no_rerank_struct2 \
  --output-dir reports/retrieval_v2/primary_preview

finagent --run-id retrieval-v2-full-dev-r1 index evaluate-v2 \
  --profile scoped_hybrid_v2_graph_free_c80_no_rerank_struct2 \
  --output-dir reports/retrieval_v2/primary_full_dev_r1

budget 与 graph 消融使用独立 v2 profile；只有 graph promotion audit 证明 unique recovery>0、无 Gold displacement/chain regression 后，图 BFS 才能作为亮点。公开四源 sealed r2 指标只保留为历史测量； 当前代码闭包重放 Gate 为失败。formal combined 仍须以 fresh 输入重跑，不能直接迁用旧结果。

Oracle、SFT 与工具服务

finagent oracle build
finagent oracle audit

# 先 dry-run 检查输入数量和路径
finagent --config configs/sft/qwen3_4b_lora.yaml \
  --run-id sft_seed42 --seed 42 --dry-run sft train \
  --output-dir runs/sft_seed42

# GPU Gate 通过后才移除 --dry-run
finagent --config configs/sft/qwen3_4b_lora.yaml \
  --run-id sft_seed42 --seed 42 sft train \
  --output-dir runs/sft_seed42

# GRPO rollout 前只能从 sealed producer chain 启动 detached 私有快照服务
finagent tool launch-detached \
  --grpo-manifest data/processed/grpo_formal_v2_smoke_s42_r1/manifest.json \
  --public-program-manifest data/processed/public_program_v2/program_compiler_v2_20260820_r2/manifest.json \
  --chunks-path data/processed/public_program_v2/program_compiler_v2_20260820_r2/chunks.jsonl \
  --split train,dev \
  --bge-index data/processed/index/train_bge_m3 \
  --dev-bge-index data/processed/index/dev_bge_m3 \
  --include-graph \
  --session-ttl-seconds 1800 \
  --max-active-sessions 4096 \
  --host 127.0.0.1 --port 18080 \
  --launch-dir runs/.detached_services/tool_formal_v2_18080_s42_r1

SFT 默认 fail-closed：local_path=.cache/models/qwen3_4b、local_files_only=true、 offline=true、allow_remote_fallback=false。manifest、revision 或本地权重不完整时应直接失败， 不会在训练过程中临时联网补文件。GRPO 的 train/dev rollout 要求两个 split 各自的索引，不能让 dev 请求回退到 train 索引。 成功 answer 会立即释放服务端会话；未作答轨迹受 idle TTL 和最大活动会话数双重约束。 /health.session_store 提供 active/completed/evicted 计数，正式运行应记录这些诊断。

训练命令会写 run_card.json、heartbeat、资源采样和进程日志；SFT 默认 24 小时 hard timeout， GRPO 默认 72 小时 hard timeout。任何失败重跑都使用新的 run-id，禁止覆盖失败证据。

所有新 GPU 入口使用 runtime contract v6 的 driver_binding.json：固定 570.144 的 libcuda、libnvidia-ptxjitcompiler 与 NVML，并以唯一 CUDA:PTXJIT:NVML 顺序在进程启动时 预加载。冻结/launch preflight 还会运行 CUDA_CACHE_DISABLE=1 的冷 PTX Driver API 探针； 只通过 nvidia-smi、torch matmul 或带缓存的 Triton JIT 均不足以通过该 Gate。详情见 ADR-0008。

GRPO

内部 owner-waiver 路径已经真实执行：12,000 个候选问题产生 48,000 条 SFT-policy rollout，动态 筛出 1,317 条 frontier train；双卡完成 Stage A 250 steps 与 Stage B 400 steps。Stage B 从 Stage-A LoRA 初始化，但使用 fresh optimizer，不能描述成连续 650-step optimizer resume。最终 LoRA 和完整结果见 runs/grpo_shadow_full_stage_b_s42_r2/global_step_400/actor/lora_adapter/ 与 reports/shadow/grpo_results/grpo_shadow_full_s42_r2/。下列命令描述的是仍被阻塞的 formal/main 路径，不应理解为上述内部运行尚未完成。

先验证正式 main-SFT adapter，并对完整 train split 规划 4 条独立 rollout。以下 dry-run 只校验 本地文件、配置和 hash，不加载模型/检索器或 CUDA；移除 --dry-run 才会开始正式长任务：

finagent --run-id audit-main-sft-s42 sft audit-run \
  --run-dir runs/sft-main-s42

finagent --run-id sft-frontier-rollout-s42 --seed 42 --dry-run \
  sft frontier-shard \
  --examples data/processed/combined/examples.jsonl \
  --chunks data/processed/combined/chunks.jsonl \
  --candidate-manifest reports/sft_frontier_candidates.json \
  --candidate-batch-size 12000 \
  --sft-run-dir runs/sft-main-s42 \
  --bge-index data/processed/index/train_bge_m3 \
  --shard-id 0 \
  --output-dir runs/sft-frontier-rollout-s42/shard-0

对 --shard-id 1 重复 dry-run 并确认两个 input_contract_sha256 相同；正式运行时 shard 0/1 分别独占 GPU 0/1。中断只允许以相同合同加全局 --resume 续跑。两边完成后用 finagent sft frontier-merge 默认严格验证预注册 12,000 前缀的 48,000 个 identity，并生成 auditor 兼容的 trajectories.jsonl/trajectories.run.json；完整命令见下方专用 Runbook。

正式生成产物和独立检索可达性通过 finagent sft frontier-audit 后，再选择 RL 样本并生成 verl parquet：

finagent rl prepare \
  --examples data/processed/combined/examples.jsonl \
  --frontier-audit reports/sft_frontier.jsonl \
  --frontier-manifest reports/sft_frontier.manifest.json \
  --output-dir data/processed/grpo

frontier 不是手写三列布尔值：finagent sft frontier-audit 会对每题恰好四条已保存 SFT trajectory、可复算 seed、模型/adapter provenance、独立检索 reachability 和所有输入 SHA256 做 fail-closed 审计。格式与生成前置条件见 docs/SFT_FRONTIER_RUNBOOK_CN.md。

先 dry-run 查看固定上游命令，然后依次跑 compatibility smoke、阶段 A 和阶段 B：

finagent --config configs/grpo/stage_a.yaml --run-id grpo_smoke --seed 42 \
  --dry-run rl smoke \
  --train-path data/processed/grpo/train.parquet \
  --validation-path data/processed/grpo/dev.parquet \
  --base-model .cache/models/qwen3_4b \
  --adapter runs/sft_seed42 \
  --output-dir runs/grpo_smoke

finagent rl audit-run --run-dir runs/grpo_smoke

# 对 rollout_generations/ 与 validation_generations/ 做逐行 reward replay
# 输出必须是新文件；命令拒绝缺 phase、schema/replay 错误和输入覆盖
finagent rl audit-observability \
  --run-dir runs/grpo_smoke \
  --output runs/grpo_smoke/grpo_smoke_observability_audit.json

finagent --config configs/grpo/stage_a.yaml --run-id grpo_a_seed42 --seed 42 \
  rl train \
  --train-path data/processed/grpo/train.parquet \
  --validation-path data/processed/grpo/dev.parquet \
  --base-model .cache/models/qwen3_4b \
  --adapter runs/sft_seed42 \
  --compatibility runs/grpo_smoke/compatibility.json \
  --output-dir runs/grpo_a_seed42

finagent --config configs/grpo/stage_b.yaml --run-id grpo_b_seed42 --seed 42 \
  rl train \
  --train-path data/processed/grpo/train.parquet \
  --validation-path data/processed/grpo/dev.parquet \
  --base-model .cache/models/qwen3_4b \
  --adapter runs/grpo_a_seed42 \
  --compatibility runs/grpo_smoke/compatibility.json \
  --output-dir runs/grpo_b_seed42

rl audit-run 会从 run_card.json、compatibility.json、process log、heartbeat、完整 resource samples 和 checkpoint 文件重新计算审计 JSON，并把 audit/checkpoint manifest SHA256 绑定回 run card。compatibility.json.passed=true 不能单独授权 main GRPO；bounded smoke 仍要求 reward-functional 与 seed provenance 另行通过。

rl audit-observability 会自动按 phase 与数值 step 排序两类 generation JSONL，在 replay 之前固定每个文件的 SHA256，并再次核验哈希、严格 schema、reward 分解、terminal provenance 和组内 reward/component 方差。即使该 Gate 通过，报告也只会标记 MEASURED_PASS_FUNCTIONAL_SMOKE_ONLY；main_training、main_resume 和 performance_claim 永远为 false。

历史 grpo_seeded_terminal_smoke_100_driver_v6_s42 只证明迁移前 legacy-6call-8k-v1 双卡 GPU/verl/tool/FSDP 的 100-step bounded 功能与兼容性：step 平均/最大 153.36/197.31 秒， GPU0/GPU1 峰值 23.08/23.88 GiB；checkpoint、0/50/100 validation、3,224 条逐轨迹 generation、reward replay、terminal、显式 seed provenance，以及 driver-v6 artifact/hash 绑定均通过 审计。它在原合同下为 MEASURED_PASS_FUNCTIONAL_SMOKE_ONLY，但缺少当前 formal 8-call profile ID/hash，报告层只能归为 legacy historical evidence；main_training_eligible=false、 performance_claim=false。旧记录不覆盖当前合同；本轮 internal full-shadow Stage A/B 的真实容量 证据以上述 r2 RunCard、checkpoint 和 paired evaluation 为准，但它仍不解锁 formal/main。

上述 main 路径仍是运行约定，不表示 main checkpoint 已存在。正式训练前请严格执行 运行手册中的 Go/No-Go Gate。

GRPO runtime contract 将 actor/reference 固定为 SDPA、use_remove_padding=false、Ulysses SP1； 这是为了避开 pinned verl remove-padding 辅助路径对未安装 flash_attn 的独立依赖。vLLM rollout 仍固定使用 TRITON_ATTN。关闭 remove-padding 会增加 padded token 的计算与潜在显存开销，必须 以新的 smoke run 测量，不能沿用历史失败 run 的资源结论。 为防止 verl 按有效 token 动态合并多条未裁剪的 8K padded tensor，actor update、rollout log-prob 与 reference log-prob 均固定关闭 dynamic batching，三个 per-GPU micro-batch 均为 1。

正式 GRPO 另固定 seed/terminal runtime contract：项目 Manager 按 SHA256(project_seed, global_step, example_id, rollout_n) 为 n=4 的每条 trajectory 派生身份， ToolAgentLoop 再为每个 assistant turn 显式派生 vLLM sampling seed；answer 仅在服务返回 accepted=true、且其 tool response 已追加到 decoded output 后终止。parquet 必须使用 agent_name=finagent_seeded_tool_agent；旧 tool_agent 数据不能用于新的正式 run。每个新 run 冻结 seed_contract.json，并在 rollout_generations/、validation_generations/ 保存可关联 example_id、reward error/components、seed 与 terminal provenance 的逐轨迹 JSONL；legacy 100-step smoke 已验证旧合同的落盘与 replay 链路，但当前 formal 8-call profile 仍须独立重跑。

冻结评测、报告和 Demo

一次内部 single-seed held-out test 已完成且不再用于调参；它不能替代 formal frozen evaluation。 正式运行前仍须用不可变 registry 固定五主对照、三 seed、Stage A/B 与六项消融。当前正式输入尚未齐全， 以下首条命令只能得到零写 UNVERIFIED_DRY_RUN/BLOCKED 预览，不能当作已预注册：

finagent --dry-run experiment preregister --registry-dir reports/experiments/main
finagent experiment audit --registry-dir reports/experiments/main

终态登记、2pp 条件 seed、hash chain 与冻结测试屏障见 不可变实验登记手册。

正式 v2 manifest 绑定 checkpoint/adapter、combined corpus、test split、retrieval config/index、 prompt/decode 和 main SFT/GRPO audit；freeze 阶段只使用上游 test hash，不读取 test rows。完整 spec、 producer contract 和五基线三 seed 约定见 正式冻结评测手册：

finagent evaluate freeze --spec /absolute/path/to/freeze-spec.json
finagent --seed 42 evaluate frozen --manifest reports/frozen/manifest.json \
  --baseline two_stage --trajectories /absolute/path/to/trajectories.jsonl \
  --producer-contract /absolute/path/to/producer.json \
  --output-dir reports/frozen/runs/two_stage/seed42
finagent evaluate aggregate --manifest reports/frozen/manifest.json \
  --runs-spec /absolute/path/to/runs.json --output-dir reports/frozen/aggregate
finagent evaluate analyze-errors --manifest reports/frozen/manifest.json \
  --runs-spec /absolute/path/to/runs.json --output-dir reports/frozen/error_analysis

finagent report build
finagent report build-resume --output-dir reports/resume_final
finagent report build-technical --output-dir reports/technical_report
finagent demo serve --chunks-path data/processed/chunks.jsonl --split dev --port 7860

正式 aggregate 的 runs spec 只能引用 evaluate frozen 的完整 immutable run 目录或其中 per_example.jsonl。聚合前会验证 runner/producer manifest 与原始 trajectory hash，并从 frozen gold 重算逐例指标及精确 ID 覆盖；手写身份字段、子集挑选、symlink、不同 contract 的分片 resume/ merge 都 fail closed。no-tool 与 fixed-RAG 的 call/result、单轮和 document-scope policy 会在 producer 与 runner 两层重复校验。

build-resume 只从 hash-verified artifact 回填中文简历、机器可读 claims 和证据引用表。正式结果不 完整时只生成 infrastructure-only 草稿；完整但 GRPO 未显著提升时生成诚实的负结果模板。 analyze-errors 只生成可重算、脱敏且不授权 claim 的失败分类与案例证据；缺正式 artifact 时为 BLOCKED，不构造数量或案例。 build-technical 生成中文技术报告与逐文件 SHA256 evidence manifest；formal 链不完整时结果章节 保持 BLOCKED/UNVERIFIED，smoke 只作为工程功能验证，不进入性能叙述。详见 技术报告 Runbook。

测试与代码质量

make quality
make coverage-core
make reproduce-mini
make release-check

make reproduce-mini 在恰好 100 条项目自有 synthetic 样例上运行确定性 CPU 闭环：data audit → BM25+graph → Agent tools/Oracle → reward → 16 参数可解释 softmax 线性模型从零优化 200 step → checkpoint 保存/加载 → 20 条留出 operation eval → report。命令会在第二个隔离目录重跑并逐项比较 primary artifact SHA256；输出目录已存在或被另一 writer 占用时 fail-closed，不覆盖历史证据。该模型 不是 Qwen，不使用下载权重，结果不是 benchmark、SFT 或 GRPO 性能。完整产物合同与换目录重跑方法见 mini 复现手册。

make coverage-core 将 data（audit/registry）、reward（numeric/scorer）和 tool （calculator/environment）拆成三个独立 pytest-cov 进程，每组均以 --cov-fail-under=85 阻断； 缺少 pytest-cov 时应切换到已安装 dev 依赖的离线环境，禁止在发布验收中临时联网安装。

make release-check 是 CPU/offline 的最终公开发布 Gate：只枚举 Git tracked 或未忽略的新文件， 对源码、配置、脚本和文档检查 secret-shaped value、个人邮箱和非白名单绝对路径；检测结果只记录 规则名、文件和行号，不回显匹配值。它生成逐文件 allowlist/denylist，拒绝 test/SEC/FinRank/LOFin 数据、完整基座权重、大 checkpoint 和机器本地报告；FinRank 只可能保留经净化的 attribution manifest，不能捆绑 records。随后使用本地 Hatchling 构建 sdist/wheel，检查 archive members，执行 pip --no-index --no-deps 安装和 import probe。输出通过 exclusive lock、staging 与 atomic rename 一次发布；目标已存在时拒绝覆盖。LoRA 默认不包含，只有发布时能精确重算为正式 main-SFT PASS 的 adapter 才可显式加入，所有 smoke adapter 无条件拒绝。详见 发布手册。

最终 Stage-B LoRA 另有模型卡边界：main SFT、Stage-B GRPO、frozen 三 seed aggregate 与上述 release allowlist 未全部可重算通过时，只能生成不含 adapter 的 BLOCKED preview。正式本地候选 必须显式运行 finagent report build-model-card --publish-candidate ...；该命令从不上传或声称 公开，真实发布仍需用户之后决定。详见 LoRA 模型卡发布手册。

文档入口

• 完整文档导航
• 公开结果与证据入口
• GitHub 安全发布流程
• 项目总进度与边界
• 中文系统架构
• 架构、数据流与 Agent/工具时序图
• 八周执行与验收计划
• 运行、恢复与故障处理手册
• 正式冻结评测手册
• 不可变实验预注册与运行账本
• 简历与面试表述规则
• 双 RTX 5090 资源核算
• 数据与 RL 可行性审计
• 许可证与发布边界
• LoRA 模型卡与候选发布包
• 简历写法
• 面试学习路线
• 架构决策记录

结果披露规则

不得把预注册目标或他人项目的 27%/5%/3% 写成结果。当前允许引用的效果数字只有已绑定 artifact 的 内部同口径比较，并必须标明“内部留出 test、single seed、Stage B 相对 SFT”：综合评分 55.04%→61.63%（+6.59pp）、answer +5.67pp、terminal-valid +10.95pp。不能把综合评分称为准确率， 不能称公开 benchmark、SOTA、formal/frozen 或多 seed 稳健结果；完整正式结论仍等待 formal 主线。

许可

项目自身代码声明为 Apache-2.0。数据、模型和本地 bootstrap 的 verl 保留各自许可证；本仓库不会发布 原始受限数据或完整基座模型。详见 LICENSE、NOTICE 和 第三方许可证清单。