NutShell Cache 验证项目

项目仓库：

GitHub：https://github.com/cyp-pyc/nutshell-cache-verification
GitLink：https://www.gitlink.org.cn/cyppyc/nutshell-cache-verification

项目简介

本仓库面向 NutShell Cache 模块搭建了一套基于 Python、pytest、Toffee 和 Picker 的验证环境。

最终提交版本以人工重构和人工审查后的 Toffee 验证环境为准，UCAgent/Codex 的输出主要作为原型生成、思路探索和对比审查材料。项目中保留了 AI 协作记录、UCAgent 输出审查、覆盖率分析和 bug injection 实验记录。

评审快速入口

推荐运行：

make reproduce

等价脚本入口：

bash scripts/reproduce.sh

该命令会在需要时生成 Picker DUT，运行主回归，并生成 Toffee report。

环境依赖

Picker
Verilator
Python 3.10
pytest
toffee-test

与 EDA1 验证环境一致的 Python 依赖版本记录在 requirements.txt 中：

python3 -m pip install -r requirements.txt

Picker 和 Verilator 仍需单独安装。请将仓库放在只包含 ASCII 字符的路径下运行，因为 Picker 生成的 CMake 文件无法稳定处理部分非 ASCII 路径转义。

常用命令

make gen_dut      # 使用 Picker 生成 Python DUT
make test         # 运行主回归
make report       # 运行主回归并生成 Toffee report
make reproduce    # 评审用一键复现入口
make random       # seed 可控的随机 smoke，可通过 RANDOM_SEED/RANDOM_ITERS 配置
make mutant_demo  # 可选：运行 RTL mutant demo，默认 MUTANT=dirty_writeback
make check_submission
make clean        # 删除 report、波形和仿真数据输出

目录结构

rtl/        被验证的 Cache RTL
src/env/    Toffee 环境、agent、coverage、memory model、timeline
src/ref/    Cache 参考模型和后端行为检查
test/       定向、随机、MMIO、blocking、flush 和 bug 场景测试
reports/    已保存的参考 Toffee 和代码覆盖率报告
generated_reports/  本地复现生成的报告（运行时创建，不提交）
docs/       英文版 AI 协作、生成代码快照、覆盖率分析、提交检查文档
docs_zh/    中文版文档索引和审查说明
scripts/    复现和辅助脚本
tools/      外部 UCAgent DUT 证据 Checker、策略测试和实验结果
presentation_materials/  主回归和 RTL mutant 演示动画

test/test_case.py 是报告中 24 项测试的主回归入口。 test/base_test.py 保存开发阶段的补充 smoke 测试，不计入报告中的 24 项主回归结果。

当前结果

24/24 testcases passed
Functional coverage: 100.0%
Coverage: 7/7 groups, 24/24 points, 72/72 bins
Line coverage: 94.26%

正式验证报告：

CACHE_VERIFICATION_REPORT.pdf

决赛答辩稿：

问题不大队-NutShell Cache Verification-UCAgent开源项目贡献赛道.pptx

已保存的 Toffee/line coverage 报告：

reports/report-20260603094655/report-20260603094655.html

脚本入口

bash scripts/run_regression.sh    # 运行主 pytest 回归
bash scripts/collect_report.sh    # 运行主回归并将 Toffee report 写入 generated_reports/
bash scripts/reproduce.sh         # 评审用一键复现入口
bash scripts/run_random_regression.sh
bash scripts/run_bug_injection_demo.sh dirty_writeback
bash scripts/run_bug_injection_demo.sh wmask
bash scripts/final_demo.sh clean
bash scripts/final_demo.sh mutant dirty_writeback
bash scripts/check_submission.sh
bash scripts/clean_generated.sh   # 删除生成的 DUT、缓存、波形和数据文件

scripts/final_demo.sh 是面向答辩展示的一键入口。clean 模式运行维护版主回归并生成 Toffee report；mutant 模式还会注入指定 RTL 故障、确认目标 testcase 能检出故障、恢复干净 RTL，并重新生成干净 DUT。

答辩与演示材料

问题不大队-NutShell Cache Verification-UCAgent开源项目贡献赛道.pptx：决赛答辩稿。
presentation_materials/make test.gif：主回归运行演示。
presentation_materials/make mutant_demo.gif：RTL mutant 检出和恢复过程演示。

GIF 用作答辩展示和快速视觉参考；可复现的技术证据仍以脚本、测试源码和保存报告为准。

文档索引

docs_zh/REVIEWER_GUIDE.md：评审快速导航，包含运行命令、预期结果和推荐阅读顺序。
docs_zh/VERIFICATION_PLAN.md：功能点到 testcase、checker、coverage 的映射和最终验证范围。
docs_zh/GAP_ANALYSIS.md：验证边界说明和未纳入结论范围的 rationale。
docs_zh/AI_COLLABORATION.md：AI 协作过程记录，说明 UCAgent/Codex 输出如何被人工审查、修正或舍弃。
docs_zh/AI_REVIEW_MATRIX.md：表格化记录 AI 生成了什么、人工发现了什么问题、如何发现、如何修正以及最终证据。
docs_zh/UCAGENT_OUTPUT_REVIEW.md：UCAgent 输出审查记录，包含 model bypass、mock、手写 trace 等风险点。
tools/ucagent_dut_evidence/：可复用的 UCAgent AST checker 补丁、聚焦单元测试、四版本对比脚本和机器可读证据，用于量化 prompt 调优与人工重构对 DUT 交互可信度的影响。
tools/ucagent_dut_evidence/results/FRESH_CONTROLLED_REPRODUCTION_zh.md：全新 UCAgent/Codex 受控重跑，说明为什么阶段完成和静态分析之后仍必须独立运行真实 DUT 回归。
tools/ucagent_dut_evidence/results/GATE_AB_COMPARISON_zh.md：对同一份冻结输出进行 A/B/C 对照；工作流/静态检查接收，严格 V1 拒绝，根因分类 V2 将 8 passed, 33 failed 明确判为验证环境失败并拒绝。
tools/ucagent_dut_evidence/results/fresh_controlled_failure_assessment.json：以机器可读形式将 33 个失败 testcase ID 完整归入人工审查的 reset/bring-up 根因。
docs_zh/ai_collaboration_records/：UCAgent/Codex 生成代码快照的中文说明。实际快照位于 docs/ai_collaboration_records/generated_code_snapshots/，只作为过程证据，最终可运行代码仍以 src/、test/、scripts/ 为准。
docs_zh/CRV_STRATEGY.md：受约束随机策略，包含 seed、迭代次数、合法地址约束和 checker 边界。
docs_zh/COVERAGE_ANALYSIS.md：功能覆盖率和代码覆盖率分析。
docs_zh/BUG_TRACKING.md：高风险 bug 场景、checker 覆盖情况和 AI 输出风险记录。
docs_zh/BUG_INJECTION_RESULT.md：RTL mutant 实验记录，说明验证环境可以抓到字节掩码和 dirty writeback 地址错位类 RTL bug。
docs_zh/SUBMISSION_CHECKLIST.md：对齐比赛评审维度的提交检查清单。

自定义 DUT 交互证据 Checker 的完整集成源码保存在 tools/ucagent_dut_evidence/ucagent_dut_interaction_evidence.patch 中。该补丁包含 Checker 实现、专项测试和开发者文档，针对记录的 UCAgent 基线使用；它是本项目的外部扩展，不宣称已经被 UCAgent 官方接收。

英文版同名文档位于 docs/ 目录。

可选 bug injection 复现入口：

make mutant_demo MUTANT=dirty_writeback
make mutant_demo MUTANT=wmask

说明

波形文件和仿真数据文件没有放入提交仓库，可以通过回归重新生成。

最终验证结论来自人工重构后的 Toffee 环境、主回归结果、保存的 Toffee report 和已记录的 bug injection 实验，不直接采用未经审查的 UCAgent 自动生成代码作为最终验证依据。

License

本项目使用 Apache License 2.0，详见 LICENSE。