Repo Context 用于在接触一个陌生仓库或归档之前先建立事实,而不是基于假设行动。
使用方式: 运行 python3 scripts/repo_context.py --cwd <directory>。脚本会输出一份 JSON 文档,仅执行只读的 git 查询,不执行仓库中配置的任何命令,不跟随任何路径组件上的符号链接,跳过依赖与构建目录,也从不运行它列出的命令。
结果字段:
- source:git(根、HEAD、分支、脏状态计数)或 archive-or-unversioned。
- scan:深度/目录预算、已访问目录数、因深度修剪和计数截断的情况。
- instructions:指令与规则文件及其大小和 SHA-256,不复制文件内容。
- ecosystems:各目录中的 Node、Python、Go 和 Makefile 声明。
- commandCandidates:argv + 依据 + executed: false;被阻止时 argv 为 null。
- ci:存在的 CI 文件;gates 始终为 null,因为不解释文件内容。
- unknowns:固定原因码,如 invalid-json、symlink-not-followed。
- executionStillNeeded:仍需运行或确认的内容。
行动前先核对: 阅读列出的每个指令文件。当指令与发现的事实不一致时,以指令为准;报告冲突,而不是默默选择。 将 defaultBranch: null、ci.gates: null 和 packageManager: null 视为未知项,需从指令或用户处确认,不要从锁文件、惯例或 localOriginHead 推断。 当出现 dirty: null 且原因为 dirty-state-uninspected-content-filters 时,表示某受跟踪路径经过配置的过滤器驱动;检查它会执行该驱动的命令,因此未检查,需以可信方式确认其状态。 每个候选命令在被运行之前都视为未验证;用 verified-handoff 技能记录运行,使结果有回执支持。 对于 archive-or-unversioned 来源,在原本会引用提交的地方明确描述来源(名称与摘要)。 在依赖受影响声明前,先解决 unknowns 中的每个条目;directory-scan-depth-limit 或 directory-scan-count-limit 意味着扫描树之外可能还有声明。
限制: 发现范围有界(深度 4、5000 个目录、单文件 1 MiB)。_test.go 计数仅覆盖已扫描的树。不检查子模块状态。 声明的事实不等于已安装的事实:工具链版本和依赖仍须在目标环境中确认。