CCF UCAgent · NutShell Cache 自动化验证

本仓库面向 CCF 开源创新大赛 UCAgent 赛题，围绕 NutShell Cache 构建可复现的自动化验证工程。项目包含事务级参考模型、定向与受约束随机激励、Scoreboard、覆盖率收集、故障注入、RTL 规格追踪，以及 WSL2 真 RTL/UCAgent MCP 证据链。

当前结论

本地主线：参考模型、Generator、Scoreboard、Coverage、属性测试、故障注入和提交门禁均可一键复现。
真 RTL 证据：WSL2 Cache_1 DUT harness 已归档 L1 定向 158/158 与 L2 全量 358/358 通过日志，均无 mismatch，并包含 DUT 文件 size/SHA256 与全 set/way 覆盖摘要。
UCAgent 证据：MCP server 日志、Code Agent transcript、session artifact、截图和 FIRST_PRIZE_EVIDENCE_SHA256SUMS 已归档并通过审计。
E-13 诊断：x-initial 对照和 72-trial 直接复现矩阵均未复现 stuck-request；仓库按 no-issue 处置保留诊断链，不宣称上游 RTL bug 已闭环。

目录结构

workspace/
  src/                 # ref_model / generator / scoreboard / coverage / harness / dut_adapter
  tests/               # 协议对齐、覆盖率、属性、Scoreboard、UCAgent 证据门禁
  third_party/         # UCAgent、picker、NutShell 固定版本源码
docs/                  # 报告、证据索引、测试计划、RTL 追踪和演示走查
logs/                  # 本地主线与 WSL2 真 RTL/UCAgent 证据日志
dist/                  # 提交归档、证据包、SHA256 清单和 release notes

快速复现

提交归档

生成正式提交包：

PYTHON=workspace/.venv311/bin/python ./package_submission.sh

生成 WSL2/MCP 证据包：

PYTHON=workspace/.venv311/bin/python ./prepare_wsl_evidence_kit.sh

写出归档哈希：

PYTHON=workspace/.venv311/bin/python ./write_artifact_manifest.sh
PYTHON=workspace/.venv311/bin/python ./write_release_notes.sh

封版审计：

cd workspace
.venv311/bin/python check_submission_readiness.py --first-prize

核心证据入口

docs/judge_quick_review.md：评审速览、评分点映射和诚实边界。
docs/final_evidence_index.md：结论到命令、日志和归档的最终索引。
docs/submission_evidence_matrix.md：官方要求到仓库证据的映射。
docs/test_plan.md：参数、接口、状态机、覆盖矩阵和 Scoreboard 策略。
docs/report.md：完整验证报告、覆盖率、Bug 追踪和复现步骤。
docs/rtl_traceability.md：RTL 源码锚点到验证组件和测试的追踪矩阵。
docs/bug_finding_forwardmeta.md：E-13 诊断、x-initial 对照、复现矩阵和 no-issue 处置。
docs/ucagent_usage_evidence.md、docs/ai_collaboration.md、docs/prompt_strategy.md：UCAgent/AI 协同、人工复核和 Prompt 策略记录。
docs/demo_walkthrough.md：3 到 5 分钟现场演示走查脚本。

WSL2 真 RTL 复验

真 RTL 复验需要 Linux/WSL2、ASCII 路径、Verilator、swig、cmake、picker、UCAgent 和 NutShell RTL 输出。可先把证据包解到 WSL2：

tar -xzf dist/ucagent-wsl-mcp-evidence-kit.tar.gz
cd ucagent-wsl-mcp-evidence-kit/workspace

阶段一：真 RTL 与 MCP 证据：

NUTSHELL_RTL_DIR=/home/cjm/ucagent-ws/NutShell/build/rtl \
CACHE_DEFAULT_OUT_ROOT=/home/cjm/ucagent-ws/cache-dut-xunique \
CACHE_X0_OUT_ROOT=/home/cjm/ucagent-ws/cache-dut-x0 \
HARNESS_DUT_RUN_L2_FULL=1 \
HARNESS_DUT_RUN_L3_FAULT=1 \
./run_first_prize_wsl_battle1.sh

./run_first_prize_wsl_battle1.sh --postcheck

阶段二：UCAgent session 证据：

UCAGENT_DUT_PATH=/home/cjm/ucagent-ws/cache-dut-x0/Cache_1 \
UCAGENT_DUT_NAME=Cache_1 \
./prepare_ucagent_session_workspace.sh

UCAGENT_DUT_PATH=/home/cjm/ucagent-ws/cache-dut-x0/Cache_1 \
UCAGENT_DUT_NAME=Cache_1 \
./run_ucagent_session_server.sh

完成交互式 session、保存 transcript 和截图后：

UCAGENT_SESSION_WORKDIR=/home/cjm/ucagent-ws/cache-dut-x0/Cache_1 \
./run_first_prize_wsl_battle2.sh --postcheck

诚实边界

本地主线不依赖 RTL 工具链，证明的是验证框架、覆盖率、Scoreboard、故障注入和 UCAgent 参数链路。
WSL2 真 RTL 证据证明 Cache_1 在当前 picker 导出与 Python memory/MMIO/coherence 代理下的事务级闭环。
E-13 是未复现的诊断链与 hardening 建议，不写成上游缺陷闭环。
workspace/test_*.py 顶层历史脚本主要是 WSL2/RTL 诊断资产；本机一键主线以 workspace/run_main_checks.sh 和 workspace/tests/ 为准。

开源合规

仓库根目录使用 Apache-2.0 许可证。第三方源码版本与许可证见 docs/third_party_manifest.md；正式提交包会排除虚拟环境、picker 本地安装目录、构建产物、动态库、波形文件和嵌套 Git 元数据。