base-in-reality

base-in-reality

仅当本技能中的 MUST、MUST NOT、SHOULD、SHOULD NOT 和 MAY 以全大写形式出现时，才应按照 BCP 14（RFC 2119、RFC 8174）中的定义解释这些关键词。

一项只读、以研究为依据的代码仓库审计。它会针对仓库中每项重要设计决策回答一个问题：是否有可证实的证据表明它违反了既定规范、标准、算法或最佳实践，且依据是真实来源？

核心规则：不得捏造权威依据。 每项发现 MUST 关联到 Agent 在本次会话中实际获取的来源。缺乏依据的主张 MUST 报告为 UNCONFIRMED，且 MUST NOT 报告为违规，因为没有获取来源却声称存在违规，就是捏造权威依据。

适用场景

当你想依据当前最佳实践和领域标准，对代码库、架构或业务逻辑进行合理性检查时使用——例如：“我们的 APR 计算是否符合贷款规范？”“我们的加密是否遵循 NIST 标准？”“这种共识方法是否可靠？”“我们的 ML 评估是否避开了已知的数据泄漏陷阱？”适用于任何代码仓库；会适配其所属领域。

不可违反的约束

1. MUST NOT 修改代码，因为这是只读审计，所有修复都由用户决定。--annotate 只会插入注释标记，不会修改逻辑。此技能在默认路径下创建的唯一文件，是位于 docs/base-in-reality/ 下的审计报告；写入前 MUST 告知用户文件名，如果用户希望代码树保持原样，则 MUST 改为在对话中提供报告。
2. 不得捏造引用。 MUST 只引用本次会话中获取的 URL/DOI，并 MUST 证明这一点：设置 BIR_EVIDENCE_LOG 后获取来源，再使用 --evidence 运行 lint。fetched: true 是 Agent 对自身行为的声明——证据日志使其可供核验。缺乏依据 ⇒ UNCONFIRMED。参见 references/verdict-rubric.md。
3. 对抗性审核关卡。 VIOLATION/DEVIATION MUST NOT 在未经反驳审核的情况下报告，以便在报告发布前发现初审者过度解读的情况。
4. 不得静默截断。 如果 --max-claims 限制了提取内容，MUST 在报告的 Dropped-claims log 中列出被丢弃的内容。

标志

• --annotate — 还会在发现所在位置插入 # BASE-IN-REALITY[<sev>]: <one-line> — see <report> 标记（唯一会修改代码的模式）。默认关闭。
• --layer algo|arch|biz — 限定为单个层。默认审计全部三个层。
• --domain <x> — 覆盖自动检测的领域。默认自动检测。
• --since <ref> — 仅审计与 <ref> 相比的差异。默认审计整个代码仓库。
• --max-claims N — 限制每次运行的主张数量。默认值：40。

流程

Python 解释器。 此技能及其参考资料中的大多数命令都使用 python3 编写。首次运行这些命令之前，先找到解释器。如果设置了 $SKILL_PYTHON，则使用它。否则，在 macOS 上，如果 command -v python3 输出 /usr/bin/python3，且 xcode-select -p 执行失败，那么这个 python3 是安装占位程序：不要运行它，直接跳过。使用第一个未被跳过且满足以下条件的 python3、python 或 py -3：执行 <interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' 后退出码为 0。找到解释器后，在每条命令中用它替换 python3，并在建议的任何 Bash(...) 权限规则中使用它。以 uv run 或 {python} 开头的命令保持原样。在通过 Bash(...) 允许列表恢复的会话中，跳过此查找，使用允许列表中指定的解释器。如果没有任何解释器符合条件，则按照本技能提供的无 Python 运行替代方案执行；如果没有提供，则停止并告知用户此技能需要 Python 3.10 或更高版本。

按顺序运行以下六个阶段。按指示分派子 Agent（并行扩展）。在 Claude Code 中，也可以将 assets/workflow.mjs 提供给 Workflow 工具，作为确定性加速方案——它会并行执行第 2、4、5 阶段；以下步骤则是可移植方案。 定位源码辅助脚本（首先执行）。 随附的 fetch_sources.py 通过相对于此技能目录的路径引用，但验证子 Agent（阶段 4）从目标仓库运行，而非从此处运行——像 assets/fetch_sources.py 这样的路径对它们无效。分派任何子 Agent 之前，先解析一次该辅助脚本的绝对路径，并将其传入每个子 Agent 的提示词：

• 使用此技能的基础目录（技能加载时，运行环境会提供该目录），并设置 FETCH="$SKILL_DIR/assets/fetch_sources.py"。
• 如果你没有基础目录，请查找： FETCH=$(find ~/.claude ~/.config ~/.agents -path '*base-in-reality*/assets/fetch_sources.py' 2>/dev/null | head -1)
• 验证路径有效：python3 "$FETCH" --source openalex --query test --limit 1 应输出 JSON。（uv run "$FETCH" 效果相同；该脚本声明 dependencies = []，且只导入标准库，因此任何主机都能运行 python3，无需将 uv 设为先决条件。）
• 必须将 $FETCH 的绝对路径原样传给子 Agent，因为带有相对 assets/ 前缀的路径无法在目标仓库中解析。
• 开始获取资料前，先打开证据日志，并将其导出，以便所有子 Agent 都能继承： export BIR_EVIDENCE_LOG="$(mktemp -t bir-evidence-XXXXXX.jsonl)"。每次检索都会将实际返回的 URL/DOI 追加到日志中，阶段 6 会据此核对报告。否则，fetched: true 只是 Agent 自己的说法，代码检查器也会指出这一点。

1. 范围与领域检测。 调查语言、依赖清单、目录布局、README/文档、数据库架构/迁移文件和配置。根据 references/domains.md 中的检测信号对领域分类；修正规范覆盖面。遵循 --domain 和 --since。生成领域映射。

2. 提取声明（分发）。 将子 Agent 分派到仓库的不同区域。每个子 Agent 都应返回独立、可证伪的声明，并标注 {layer (algo|arch|biz), location (file:line), confidence, domain-tag}。声明必须是关于代码行为、可核查的断言（例如：“使用 MD5 进行密码哈希”“请求路径上同步扇出至 12 个服务”“APR 按单利计算”）。合并并去重。执行 --max-claims 限制；将超出的声明记录到已丢弃声明日志。

3. 来源路由。 对每项声明，根据 references/source-routing.md 选择按优先级排序的来源计划（算法→arxiv/Semantic Scholar；安全→NIST/RFC/OWASP；医疗→PubMed；金融科技→监管机构+标准；通用→Scholar/JSTOR/OpenAlex）。

4. 验证（分发，有依据）。 针对每项声明，分派一个子 Agent：先通过上文解析出的绝对 $FETCH 路径，使用随附的来源辅助脚本查询无需密钥的 API（python3 "$FETCH" --source <s> --query "<q>" --limit <n>——将绝对路径原样传给子 Agent；相对于技能目录、带有 assets/ 前缀的路径无法在目标仓库中解析），然后使用 WebSearch/WebFetch 查询标准和付费墙后的来源。提出任何高于 UNCONFIRMED 的结论之前，必须至少掌握 1 条已获取的来源。输出符合 assets/findings.schema.json 的发现：verdict ∈ {VIOLATION,DEVIATION,OUTDATED,UNCONFIRMED}、severity ∈ {critical,high,medium,low}、citations[]（每项均包含已获取来源的 URL/DOI 和支持性引文；若只能获取摘要，则标记 abstract_only）、recommended_fix。

5. 反驳（分发，对抗性审查）。 针对每项候选 VIOLATION/DEVIATION，依据 references/verdict-rubric.md，从不同视角（正确性、引用适用性、严重性）分派独立的反驳者。每位反驳者默认持怀疑态度。如果 ≥2 位反驳者反驳一项严重性为 medium/low 的发现，或任一反驳者反驳其他任何严重性的发现（critical、high 或缺失/未知），则将其降级为 UNCONFIRMED。没有返回内容的反驳者也计为反驳。无论发现是否保留，都要将投票记录在该发现的 refutation 字段中。

6. 综合。 填写报告前，使用随附的契约检查器检查合并后的发现数组：将发现写入临时 JSON 文件，然后运行 python3 "$SKILL_DIR/assets/report_lint.py" <findings.json> --evidence "$BIR_EVIDENCE_LOG"。 它会确定性地检查架构枚举值和依据不变量（没有已获取引文的 VIOLATION/DEVIATION 会被拒绝——应将其降级为 UNCONFIRMED， 而不是纳入报告），并且在指定 --evidence 时，会逐一检查每条 fetched: true 引文是否 对应检索实际返回的 URL。因此，看似合理但从未获取过的 DOI 会被拒绝，不会被呈现为有依据的引文。它还会检查反驳情况：仍保留的 VIOLATION/DEVIATION 若没有记录 refutation，或其投票结果按第 5 阶段的要求应降级，都会被拒绝。检查通过表示记录的投票与判定一致，并不表示投票诚实。你必须使用 --evidence 运行检查器：结果行会说明运行模式；不带此参数检查的报告只经过格式检查。 修复每一行 ERROR:，然后填写 assets/report-skeleton.md。将报告写入 docs/base-in-reality/<YYYY-MM-DD>-audit.md 是此技能在 --annotate 之外唯一预期的写入操作；创建文件前，你必须说明这一点。如果用户希望保持其工作区不变，则应改为在对话中输出报告。报告包含：执行摘要、领域图、发现（按严重程度再按层级排序）、来源附录和已舍弃主张记录。如果使用 --annotate，请在每条发现所在位置插入注释标记。

输出风格。 面向用户撰写报告和说明时，约 80% 使用 ASD-STE100 简明技术英语。使用短句、常见词、主动语态，并且每个步骤只包含一项操作。

参考资料

• references/source-routing.md — 主张类别与来源类别对照表、API 用法和礼仪。
• references/verdict-rubric.md — 判定分类、严重程度、依据规则和反驳。
• references/domains.md — 领域检测信号和各领域规范概览。

资源

• assets/fetch_sources.py — 无需密钥的学术来源查询辅助工具（标准库；uv run）。
• assets/findings.schema.json — 子 Agent 生成的发现所用的架构验证文件。
• assets/report_lint.py — 标准库检查器，用于根据架构、依据不变量和反驳规则检查发现（第 6 阶段）。
• assets/report-skeleton.md — 第 6 阶段填写的报告模板。
• assets/workflow.mjs — 可选的 Claude Code Workflow 加速工具。

边缘情况

• 来源覆盖不均。 arxiv/PubMed 覆盖较好；JSTOR/ISO 只能访问摘要——将这些引文标记为 abstract_only，以表明证据深度。
• 领域误判。 在报告开头列出领域图；可使用 --domain 覆盖检测结果。
• 大型代码仓库。 深度模式会针对每条主张执行两次分发（验证 + 反驳），消耗大量 Token。使用 --layer、--since 或较低的 --max-claims 缩小范围。
• “最佳实践”存在争议。 对有理据的偏离，优先使用 DEVIATION 而非 VIOLATION；设置反驳环节，就是为了防止此技能宣称只有一种正确做法。