---

作品简介

UCAgent-Assisted NutShell Cache Verification 面向 UCAgent 赛题中的 NutShell Cache 验证方向，交付一套本地可运行、结果可验证、证据可追踪的 Cache 验证工程。

仓库以 UCAgent/Agent 生成的验证起点为输入，记录了 CRV、Cache corner case、Scoreboard 观察点和故障注入等 refinements，并形成从 AI 起点 -> refinement -> 验证执行 -> 报告归档 -> 作者归属审查 的证据链。作者归属审查已于 2026-08-10 完成：NS-HITL-007 clean-line 5-step 变更经重审后纳入当前树，author_attribution_review_complete=True、claimable_human_attribution=True，当前树 8/8 recorded refinement cases 作者归属已接受。

项目重点不是单纯整理文档，而是把 Cache 关键路径转换为可运行场景、可检查指标和可追溯证据。除 Python-model 故障注入闭环外，仓库已完成 Cache_1 Picker export，并在真实 Toffee Agent + Env + Model + CovGroup 中跑通 15 个 RTL-native case、20/20 feature bins、21/21 legal cross bins 和 8 个 mixed CRV seed；定向场景覆盖 MMIO 延迟握手、四路全脏替换、组合/寄存两类 Stage2 forwarding，以及操作/命中结果/行边界、store mask、probe line state、cacheable/MMIO path 的合法交叉。同次 Verilator 数据量化出核心 RTL 96.91% line / 90.15% branch code coverage；一条隔离的 CacheStage3_1.sv byte-merge 受控 mutation 通过 Picker 重编译，并在配对的 clean/mutant 场景中产生预期区分与可复算的 Scoreboard failure signature。

在此基础上，新增的 deterministic bounded RTL timing-CRV 直接驱动同一 Cache_1 pins：dram_bursty、cpu_response_backpressure、mixed_io_jitter 3 个 profile 与 8 个固定 seed 组成完整笛卡尔积，24/24 runs 通过，7/7 时序机制和 12/12 profile-operation bins 命中，共观测 1688 个有界 stall cycles、960 个 refill beats、192 个 writeback beats；事务级 Scoreboard、stalled-payload stability 与最终 quiescence 均为 24/24。计划 SHA256 为 ec0f632f1a4757db982a3b26336ece165fe599f4cd07acecaf7d1f23ba5aeabb，结果索引 SHA256 为 2d34b25124ddc1f102b1988c6e6e578b9c2a85fb9d340b9932bb277cc4aa0116。该新增证据是 non-exhaustive bounded campaign，not a discovered NutShell bug，not independent HM approval，not UCAgent/DeepSeek stage completion，且不在既有 hm_review.log 的审查范围内。

Direct-RTL refinement technical ablation 对同一 canonical Picker/Toffee campaign 做 fail-closed 映射复核：UCAgent-style seed 为 3/3，recorded-refinement executable mappings 为 6/6，另外 2/2 个 DCache flush 目标因架构不兼容被明确拒绝而没有伪造成 RTL pass。这里的 20/20 feature bins 与 21/21 legal cross bins 只属于完整 15-case campaign，不归因给任一 ablation 子集。该结果只是 bounded、non-exhaustive technical mapping，不是发现 NutShell Bug，不构成独立 HM 审批或完整 UCAgent/DeepSeek/MCP/HM 闭环；当前树 8/8 作者归属已接受（含 NS-HITL-007 clean-line 5-step 重审）。

快速演示入口

当前可复现演示以最新代码、真实 RTL 证据和冻结包为准：

• 30 秒评审入口：docs/submission/JUDGE_QUICK_START.md
• 现场演示脚本：docs/submission/demo_script.md
• 精确提交包身份：最终 ZIP 同级的 .sha256、.replay.*、.form_pack.* 与 .final_audit.* sidecar

旧录屏包含已被真实 Cache_1 RTL 审查纠正的 prototype 语义与过时测试计数，因此不再作为当前交付证据。

仓库中已有的冻结 ZIP 和 sidecar 属于上一冻结基线，不包含当前未提交的 Stage 22/checker 与回归更新。代码冻结后必须重新生成 ZIP、SHA256、replay、form-pack 和 final-audit sidecar，才能与当前交付绑定。

赛题对应

赛题要求	本仓库交付物	位置
基于 UCAgent 完成 NutShell Cache 验证	UCAgent/Agent seed、refinement 记录、验证脚本、作者归属门禁和报告闭环	ucagent_prompt_pack/ / data/agent_artifacts/
Cache 验证组件	Generator、Driver、Monitor、Scoreboard、CoverageCollector、FaultCampaign	src/nutshell_cache_verify/
激励发生器 Generator	11 个 Cache 验证场景，包含 3 个 Agent seed 和 8 个 recorded refinement cases；当前树作者归属 8/8 已接受（含 NS-HITL-007 clean-line 5-step 重审）	src/nutshell_cache_verify/scenarios.py
计分板 Scoreboard	32 个检查观察点，覆盖数据一致性、写回、失效和替换行为	src/nutshell_cache_verify/toffee_env.py
UCAgent Stage 22 模板准备	15 个 non-API CK 模板均按预期以 Not implemented 失败；API 4 项 deselected，unmarked/unassociated 均为 0	docs/toolchain/UCAGENT_STAGE22_TEMPLATE_CHECKER_COMPATIBILITY.md
CRV 与复杂路径	16 个 seed、1024 个随机事务的压力验证	docs/evidence/CRV_STRESS_CAMPAIGN.md
Picker/Toffee 真实 RTL	Cache_1 export、15-case、20/20 feature bins、21/21 legal cross bins、8 mixed seeds	docs/toolchain/WSL_NUTSHELL_CACHE_PICKER_TOFFEE_RTL.md
Direct-RTL refinement ablation	UCAgent-style seed 3/3、recorded-refinement executable mappings 6/6；2/2 个 DCache flush 架构不兼容目标被拒绝	docs/evidence/RTL_REFINEMENT_ABLATION.md
RTL 时序 CRV	3 profiles × 8 seeds 的 deterministic bounded campaign；24/24 runs、7/7 mechanisms、12/12 profile-operation bins	docs/toolchain/WSL_NUTSHELL_CACHE_RTL_TIMING_CRV.md
RTL 引脚边界负向验证	4/4 clean controls、4/4 isolated mutations、4 个 distinct signatures；故障位于 testbench boundary，不冒充 DUT Bug	docs/toolchain/WSL_NUTSHELL_CACHE_RTL_PIN_MUTATION_AUDIT.md
RTL 源码受控负向验证	clean control 1/1、specific source mutant killed 1/1；Picker 隔离重编译、原源码未改；tool-assisted、非发现 Bug、非穷尽覆盖；独立审查已接受该有界结论	docs/toolchain/WSL_NUTSHELL_CACHE_RTL_SOURCE_MUTATION_AUDIT.md
RTL code coverage	Verilator LCOV：core line 96.91%、branch 90.15%；16/16 uncovered lines 有处置分类	docs/toolchain/WSL_NUTSHELL_CACHE_RTL_CODE_COVERAGE.md
故障注入	5 类建模故障，5/5 可检出并定位到场景	docs/evidence/MUTATION_DETECTION_AUDIT.md
验证报告	测试计划、覆盖率、Bug 追踪、评分映射和最终报告	docs/submission/final_report.md
工程规范与可复现性	demo、unittest、文本一致性检查和结构合规检查	scripts/ / tests/

交付要求导航

验证实操闭环

交付要求	本仓库证据
可运行 demo	scripts/run_nutshell_cache_demo.py
自动化测试	tests/
仓库结构说明	项目结构
文本一致性检查	scripts/check_submission_text_consistency.py

AI 协同、refinement 记录与作者归属审查

交付要求	本仓库证据
Agent 任务分解	data/agent_artifacts/task_decomposition.md
Agent seed 与 recorded refinement 对照	data/agent_artifacts/nutshell_ai_human_correction_matrix.md
AI 缺陷与 recorded refinement 收益	data/agent_artifacts/ai_defect_human_fix_score_table.md
AI/HITL 可追踪审计	docs/evidence/AI_HITL_TRACEABILITY_AUDIT.md
Refinement 技术增益量化	docs/evidence/AI_HUMAN_DELTA_AUDIT.md
作者归属审查门禁	docs/evidence/AUTHOR_ATTRIBUTION_AUDIT.md
一票否决结构与归属分离审计	docs/evidence/BASELINE_COMPLIANCE_AUDIT.md
UCAgent 工作区证据桥接审计	docs/evidence/UCAGENT_WORKSPACE_BRIDGE_AUDIT.md（自动替换占位内容，但不代表 UCAgent 阶段完成、人工审批或作者归属）

Cache 验证深度

验证主题	本仓库证据
dirty eviction / write-back	docs/evidence/FAULT_FAILURE_SIGNATURE_AUDIT.md
partial store / byte mask	docs/evidence/SCOREBOARD_INVARIANT_AUDIT.md
probe invalidate / reload（Python fault model）	docs/evidence/MUTATION_DETECTION_AUDIT.md
same-set pressure / LRU refresh（Python fault model）	docs/evidence/CRV_STRESS_CAMPAIGN.md
probe release / LFSR replacement（Cache_1 RTL）	docs/toolchain/WSL_NUTSHELL_CACHE_PICKER_TOFFEE_RTL.md
覆盖项到 NutShell 源码映射	docs/evidence/SOURCE_COVERAGE_TRACEABILITY_AUDIT.md

核心交付

模块	内容	价值
Cache 验证模型	Python-adapter Cache model 与 fault model	本地快速复现 Cache 关键路径和故障签名
Generator	Agent seed + recorded CRV refinement cases	展示 AI 起点与领域补强的技术差异；当前树 8/8 作者归属已接受（含 NS-HITL-007 clean-line 5-step 重审）
Scoreboard	32 个观察点和一致性检查	把场景执行结果转化为可判定证据
Fault Campaign	5 类建模故障注入	验证环境具备缺陷暴露能力
Picker/Toffee RTL Campaign	15/15 RTL-native cases、20/20 feature bins、21/21 legal cross bins	真实 rtl_pins 功能证据与语义映射
RTL Timing-CRV Campaign	3 profiles × 8 seeds；24/24 runs，1688 bounded stalls，Scoreboard/stability/quiescence 24/24	用可回放独立随机通道检验 DRAM、CPU response 与 MMIO 握手时序
RTL Pin Mutation Campaign	4/4 clean controls、4/4 isolated mutations、4 个 distinct signatures	证明 testbench/Scoreboard 检错敏感性，并保持非 DUT Bug 边界
RTL Source Mutation Campaign	1/1 clean control、1/1 controlled mutant killed	证明特定 masked-write 源码故障可检出，并保留 tool-assisted、非 Bug、非 exhaustive 边界；独立复核已接受
RTL Code Coverage	4 个核心模块 line/branch 计数	将 coverage data 转为可审计缺口
Evidence Reports	覆盖率、AI/HITL、CRV、Scoreboard、Bug 追踪	用数据支撑项目说明

工作流概览

UCAgent / Agent seed
        |
        v
Recorded CRV、Cache corner case、Scoreboard 观察点 refinement（当前树作者归属 8/8 已接受）
        |
        v
Generator -> Driver -> Monitor -> Scoreboard -> CoverageCollector
        |
        +-- Python model: flush / probe invalidate / LRU fault injection
        +-- Cache_1 RTL: probe release / LFSR replacement / partial-write CRV
        +-- RTL pin boundary: paired clean/mutant refill / writeback / MMIO probes
        +-- RTL source mutation: isolated Picker rebuild + paired masked-write oracle
        +-- failure signature / bug tracking / portable evidence revalidation
        |
        v
验证报告、量化指标、文本一致性和结构合规检查
        |
        v
README / final report / evidence index / automated checks

快速运行

python -m pip install -e ".[test]"
python scripts\run_nutshell_cache_demo.py
python -m pytest -q tests
python scripts\analyze_nutshell_rtl_coverage.py
python scripts\check_submission_text_consistency.py

测试 extra 将官方 pytoffee / toffee-test 分别固定到已审计提交 f57dd6ffc295b9b8bad3e3b3ce040b8a849f5c91 与 64f183a5caf4645fa0ec3d0e8600c94d445ed7ea，避免依赖未声明或版本不兼容的本机插件。

验证结果

指标	结果
Cache 验证场景	11
Agent seed 场景	3
Recorded refinement cases	8（当前树作者归属 8/8 已接受；NS-HITL-007 clean-line 5-step 变更已接受）
功能覆盖项	33/33
Recorded refinement 覆盖增量	24
Scoreboard 观察点	32
故障注入检出	5/5
CRV stress seeds	16
CRV 随机事务	1024
固定参考模型失败数	0
当前工作树全仓回归	最新主 pytest 204 passed + 114/114 参数化 subtests；unittest discover 203/203 OK；另有 active-interpreter/guard 24/24、adapter 5/5、stage-artifact 3/3 聚焦回归
UCAgent 聚焦回归	原 guard + template 集合 32/32 通过；扩大 guard/template/random/VerifyPDB/testops 集合 64 passed + 1 runtime-capability skip（非 pass）；Python adapter smoke 5/5 通过
Stage 22 临时原生模板报告	15/15 模板均为 expected-fail (Not implemented)；4 个 API tests deselected；15 CK；unmarked=0；unassociated=0；只证明模板/checker 准备，不代表 Stage 22 完成
11 场景功能结果来源	Python reference model（非 RTL pins）
Cache_1 Picker-backed Toffee	15/15 RTL-native cases，20/20 feature bins，21/21 legal cross bins，481 hooks，8 mixed seeds，0 timeout
Direct-RTL refinement technical ablation	UCAgent-style seed 3/3；recorded-refinement executable mappings 6/6；DCache flush incompatibilities 2/2 rejected；完整 campaign 的 20/20 + 21/21 不归因给子集
RTL long-CRV	128 seeds × A/B 两次独立重复，256/256 RTL long-CRV seed-runs 通过，128/128 result signatures 一致，128/128 set indices，16/16 word offsets，11,776 Toffee hooks，0 timeout
RTL timing-CRV	3 profiles × 8 seeds，24/24 runs；7/7 timing mechanisms；12/12 profile-operation bins；1688 bounded stalls；960 refill beats；192 writeback beats；Scoreboard/stability/quiescence 24/24
RTL pin-boundary mutation	4/4 clean controls，4/4 isolated mutations detected，4 个 distinct signatures，0 timeout
RTL controlled source mutation	1/1 clean control，1/1 mutant killed，clean/mutant 各 9 Toffee hooks，0 timeout；非发现 Bug、非 exhaustive；已纳入独立 HM 有界证据审查
核心 RTL code coverage	502/518 lines（96.91%），9294/10310 branches（90.15%）
真实工具链可宣称状态	上一冻结证据集为 True（六份机器证据与独立 hm_review.log 已跟踪并通过语义校验；7/7 claim-valid）；该结论不自动绑定当前未提交工作树
当前工作树作者归属状态	Complete：author_attribution_review_complete=True、claimable_human_attribution=True；当前树 8/8 已接受（含 NS-HITL-007 clean-line 5-step 2026-08-10 重审）
仓库结构检查	通过
文本一致性检查	通过

核心 demo 输出应包含：

combined_cases=11
coverage=33/33 (100.0%)
faults_detected=5/5
fixed_reference_failures=0

项目结构

路径	说明
src/nutshell_cache_verify/	Cache 模型、Generator、Scoreboard、Adapter、故障注入
tests/	单元测试和回归测试
scripts/	demo、审计、文本检查和结构检查脚本
data/agent_artifacts/	Agent seed、refinement、作者归属状态、缺陷追踪和协同记录
docs/submission/	最终报告、提交清单、快速入口和测试说明
docs/evidence/	AI/HITL、覆盖率、CRV、Scoreboard、故障证据
docs/topic/	赛题文本、评分点和实现对齐
docs/toolchain/	UCAgent、Toffee、Picker、NutShell 工具链接入材料
reports/	当前指标、覆盖率、缺陷追踪和证据汇总
agent_skills/	Agent Skills 风格的领域知识注入包
ucagent_prompt_pack/	可交给 UCAgent/Agent 的提示词和人工复核记录
real_toolchain/	UCAgent/Toffee/NutShell 工具链接入材料

交付材料

材料	文件
30 秒快速入口	docs/submission/JUDGE_QUICK_START.md
最终报告	docs/submission/final_report.md
技术方案	docs/submission/technical_solution.md
测试说明	docs/submission/testing.md
使用说明	docs/submission/usage.md
提交清单	docs/submission/submission_checklist.md
赛题对齐	docs/topic/SUPPLIED_TOPIC_RUBRIC_ALIGNMENT.md
评分证据索引	docs/evidence/RUBRIC_SCORE_BOOST_AUDIT.md
RTL 引脚边界故障注入	docs/toolchain/WSL_NUTSHELL_CACHE_RTL_PIN_MUTATION_AUDIT.md
Direct-RTL refinement technical ablation	docs/evidence/RTL_REFINEMENT_ABLATION.md
RTL 时序 CRV	docs/toolchain/WSL_NUTSHELL_CACHE_RTL_TIMING_CRV.md
AI 缺陷与 refinement 表	data/agent_artifacts/ai_defect_human_fix_score_table.md
作者归属审查	docs/evidence/AUTHOR_ATTRIBUTION_AUDIT.md
基础合规与 no-pure-AI 诚实门禁	docs/evidence/BASELINE_COMPLIANCE_AUDIT.md
证据汇总	reports/submission_manifest.md

当前验证范围

本仓库保留多个不可混淆的证据层。11 场景、33/33 覆盖和 5/5 故障检出来自 Python reference model；8 个 recorded refinement cases 的 24 项覆盖增量和 5 类故障定位是可复算技术 delta。当前树作者归属 8/8 已接受（author_attribution_review_complete=True、claimable_human_attribution=True）；NS-HITL-007 clean-line 5-step 变更已于 2026-08-10 重审并接受。

Cache_1 的 8-case pin smoke、15-case、20/20 feature bins、21/21 legal cross bins、128-seed A/B 重复的 256/256 RTL long-CRV（128/128 set indices、16/16 word offsets）和 96.91%/90.15% core line/branch code coverage来自真实 rtl_pins/Verilator。4/4 clean controls 与 4/4 isolated testbench-boundary mutations detected 用于证明对 DRAM refill、dirty writeback 和 MMIO 协议边界破坏的敏感性；另有一条 tool-assisted controlled DUT-source mutation，以配对 clean control 1/1、mutant kill 1/1 证明对特定 masked-write corruption 的检出能力。后两层都不是“发现 NutShell RTL Bug”，也不是 exhaustive mutation coverage。source review 已确认 DCache 不支持 flush traversal、probe 不 invalidate、替换为 LFSR 而非 LRU。评审范围内的功能计划已经闭合，但全 set/offset sweep、bounded feature/cross bins 和结构 code coverage仍不等于穷尽所有时序、状态与输入序列。

独立新增的 timing-CRV 进一步提供 24/24 deterministic bounded 时序运行证据，但仍是 non-exhaustive：它不证明全部时序交错或状态空间，不是发现 NutShell Bug，不是独立 HM 审批，也不代表 UCAgent/DeepSeek 阶段完成。其机器报告与哈希可复算，但该证据生成晚于既有 HM 审查，因此不属于旧 hm_review.log scope。

Direct-RTL ablation 只证明 3/3 UCAgent-style seed、6/6 executable recorded-refinement mappings 和 2/2 DCache flush architecture rejections 的有界技术分类。完整 RTL campaign 的 20/20 feature bins 与 21/21 legal cross bins 不分摊给 ablation 子集；该审计不是穷尽 Cache 正确性证明、不是 NutShell Bug 发现、不是独立 HM，也不补全 DeepSeek/MCP/HM transcript。当前树 8/8 作者归属已接受（含 NS-HITL-007），但不等同于 UCAgent-stage HM 完成或完整 DeepSeek/MCP/HM transcript。

上一冻结七产物证据集为 claimable=True、missing=0、7/7，有界独立审批已完成。不可变 DeepSeek 胶囊记录的是捕获时 14/30（映射到当前 31-stage schema 为 14/31、index 21）；随后仅由 Code Agent 编排 UCAgent 官方 controller/checker 工具推进。当前持久化状态已真实达到 completed=22/31、skipped=9/31、resolved=31/31、remaining=0/31、stage index=31、all_completed=true。这证明原生 stage graph 已闭合，但不补写 DeepSeek 对话，也不主张完整 DeepSeek/MCP/HM transcript；UCAgent-stage HM pass 仍为 0。

License

Project-original work is licensed under Apache License 2.0; see LICENSE. The single reviewed NutShell generated-RTL snapshot at data/nutshell_cache/rtl_source_snapshots/ is a third-party exception distributed under Mulan PSL v2 with adjacent license and provenance files. It is not relicensed under Apache-2.0.