C/C++ 协议·平台代码的漏洞发现规范化为可重现的证明，并在隔离副本中验证候选补丁的 MVP。code-shield 是已被确认存在名称冲突风险的工作名称，因此在公开包和 CLI 中使用了中立的内部名称。
当前实现的核心不是补丁生成模型，而是以下验证闭环。
sanitizer 또는 SARIF
-> Finding + EvidenceBundle
-> source context
-> manual/external-agent patch
-> 원본 재현
-> build
-> patched reproducer
-> tests
-> static rescan
-> bounded refuzz
-> protocol oracle
-> verified report
Finding、EvidenceBundle、PatchProposal、VerificationReport JSON 模型detected → reproducible → contextualized → proposed → plausible → verified 状态转移无运行时 Python 依赖。
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v
如果要直接运行而不安装：
PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v
动态端到端套件是 examples 中的 C/C++ fixture 矩阵。使用 Clang ASan/UBSan 实际重现 CWE-121、CWE-190、CWE-416、CWE-787、CWE-476，然后针对每个修复不变量的补丁运行所有六个网关。每个 fixture 的输入和验证范围已在 examples/README.md 中整理。
如果要在没有单元测试框架的情况下仅运行实际矩阵：
PYTHONPATH=src python3 examples/run_fixture_matrix.py
如果要自动生成并运行更多 C/C++ 变体示例：
PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50
该 runner 不使用 unittest，而是将生成的每个项目传递给相同的 VerificationPipeline。结果摘要默认保存在 artifacts/generated-corpus-summary.json。
使用 Vite + React + TypeScript 构建的前端 frontend，可以以操作仪表盘的形式查看当前实现状态。该控制台将 fixture 矩阵、生成语料库、Hermes API 服务器连接面、验证网关和证据安全性不变量整合在一个屏幕上。
cd frontend
npm install
npm run dev
默认开发服务器是 http://127.0.0.1:5173。使用以下命令检查生产构建：
cd frontend
npm run build
protocol-remediator ingest-sanitizer \
--log asan.log \
--reproducer crash.input \
--target-name parser \
--revision 0123456789abcdef \
--variant asan-x86_64 \
--output intake/parser-crash
输出：
intake/parser-crash/finding.json
intake/parser-crash/evidence.json
protocol-remediator ingest-sarif \
--sarif results.sarif \
--output intake/sarif
protocol-remediator export-sarif \
--finding intake/parser-crash/finding.json \
--finding intake/another/finding.json \
--output artifacts/findings.sarif
protocol-remediator context \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--target-root /path/to/target \
--output intake/parser-crash/context.json
protocol-remediator verify \
--config /path/to/target/target.toml \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--patch candidate.patch \
--artifacts artifacts
退出码：若已验证则为 0，验证失败则为 1，配置或输入错误则为 2。
启动 Hermes API 服务器后，remediate 可以通过 HTTP API 请求补丁，而不是使用本地命令。默认端点是 POST /v1/patches，接收发现/证据/上下文和目标工作区归档，并返回 unified diff。
示例服务器执行：
PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
--host 127.0.0.1 \
--port 8765
安装后也可以使用 console script：
hermes-agent-server --host 127.0.0.1 --port 8765
附加生产 backend 命令时，按参数重复 --backend-command。支持 {context}、{workspace}、{patch_output} 占位符。
hermes-agent-server \
--backend-command my-patch-agent \
--backend-command --context \
--backend-command {context} \
--backend-command --workspace \
--backend-command {workspace} \
--backend-command --output \
--backend-command {patch_output}
在 target.toml 中按如下方式指定 Hermes 模式：
[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30
然后直接使用现有的 remediate 命令：
protocol-remediator remediate \
--config examples/length-prefixed-parser/target.hermes.toml \
--finding artifacts/hermes-cli-input/finding.json \
--evidence artifacts/hermes-cli-input/evidence.json \
--artifacts artifacts/hermes-cli
开发用的端到端验证通过以下 runner 执行。该 runner 会启动临时 Hermes 服务器，通过 API 客户端接收补丁，然后完整运行验证闭环：
PYTHONPATH=src python3 examples/run_hermes_demo.py
如果不使用 Hermes 而直接调用本地命令，则在 target.toml 中将 agent 命令指定为字符串数组：
[agent]
mode = "command"
command = [
"my-patch-agent",
"--context",
"{context}",
"--workspace",
"{workspace}",
"--output",
"{patch_output}",
]
timeout_seconds = 900
然后执行以下命令：
protocol-remediator remediate \
--config /path/to/target/target.toml \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--artifacts artifacts
核心不直接调用特定 LLM API。约定是 Hermes 后端或外部命令读取上下文并生成 unified diff。agent 的工作在临时副本中执行，而非原始目标。
完整示例请参考 target.toml：
[project]
name = "my-protocol"
language = "c++"
root = "."
[executor]
mode = "docker"
image = "my-frozen-toolchain@sha256:..."
timeout_seconds = 300
network = false
[reproduction]
failure_regex = "AddressSanitizer|heap-buffer-overflow"
[verification]
required_gates = [
"build",
"reproducer",
"tests",
"rescan",
"refuzz",
"protocol",
]
[gates]
build = [["cmake", "-S", ".", "-B", "build"], ["cmake", "--build", "build"]]
reproducer = [["./build/fuzz_target", "{reproducer}"]]
tests = [["ctest", "--test-dir", "build", "--output-on-failure"]]
rescan = [["./tools/run-sast", "--fail-on-new"]]
refuzz = [["./tools/refuzz", "--seconds", "60"]]
protocol = [["./tools/protocol-oracle"]]
每个命令是参数数组，而非 shell 字符串。支持的占位符：
{workspace}：执行器中可见的临时目标路径{reproducer}：校验和验证后复制到临时目标的重现器路径build 和 reproducer 始终必需。默认策略下，六个网关都是必选的。如果由于目标特性某些网关不可用，则必须在 required_gates 中显式调整，且结果仍会保留在报告中。
每次验证运行保留以下内容：
artifacts/run_<id>/
candidate.patch
context.json
evidence.input.json
finding.input.json
finding.final.json
patch-proposal.json
patch-stats.json
verification-report.json
verification-report.json 包含基线和补丁命令的输出。由于 PoC 或日志可能包含机密信息，因此应对产物仓库应用单独的访问和保留策略。
network=false。allow_local=true，且不应用于不可信目标。plausible 是仅通过构建和原始重现器的状态。verified 也不是程序等价性的证明，不能替代人工审批。调查依据与设计决策已在 docs/research 中整理。