GitNexus evidence-provenance Schema 2 深度解析为 AI 生成计划建立可验证的证据指纹与安全写入契约【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus导读本文讲解 GitNexus 中gitnexus-plan/gitnexus-work双技能共用的证据溯源evidence provenanceSchema 2规范及其配套可执行脚本。它解决一个真实工程问题——AI 规划器产出的变更计划文档如何携带可审计的仓库证据谁被引用、HEAD/index/工作区分别是什么内容、整棵树脏状态的总摘要以及这些计划文件如何被原子、防竞态、防符号链接攻击地写入与读取。读完本文你将掌握read-plan/snapshot/write-plan三个子命令的完整用法、路径与字节级契约、Linux 与 macOS 两套差异化的目录描述符锚定机制以及 canonical bytes 的精确帧格式。一、什么是 evidence provenance Schema 2在 GitNexus 的规划技能体系中gitnexus-plan负责把一项工程任务加工成可直接实施的计划文档而gitnexus-work负责按 §7 实施序列逐条落地。两者之间传递的不仅是自然语言章节还有一份机器可读的§11 Implementation Context 包其中evidence_provenance字段是强制项——它是证明这份计划针对的是哪一棵确切的仓库状态的唯一依据。.claude/skills/gitnexus-plan/references/evidence-provenance.md 是这份规范文档normative byte contract它声明相邻的 scripts/evidence-provenance.mjs 是规范的可执行定义共 2366 行gitnexus-plan与gitnexus-work各自携带字节完全一致的副本.mjs 与 .md 均经 md5sum 校验一致任一技能都能独立产出相同快照无需依赖另一技能是否安装该 helper 是生成计划唯一受支持的写入边界——严禁用临时 shell 管道自行重算摘要或直接写计划目标路径。四个字节级副本位于仓库中互为镜像副本位置内容.claude/skills/gitnexus-plan/references/evidence-provenance.md规范文档.claude/skills/gitnexus-plan/scripts/evidence-provenance.mjs可执行定义.claude/skills/gitnexus-work/references/evidence-provenance.md规范文档与上同 md5.claude/skills/gitnexus-work/scripts/evidence-provenance.mjs可执行定义与上同 md5gitnexus/skills/gitnexus-plan/{references,scripts}/…打包进发行技能的副本gitnexus/skills/gitnexus-work/{references,scripts}/…打包进发行技能的副本核心原则在 SKILL.md 中重复强调Pin working-tree evidence, not only HEAD每个计划形态都携带带版本号的 global dirty digest 与按路径排序的 cited-path manifestWrite the plan only through the helper先在仓库外 scratchpad 组合完整 UTF-8 文档再通过 stdin 交给write-planRead an existing plan only through the helperDeepen 必须调用read-plan且只用回执中解码出的精确字节。Schema 1 被有意废弃。执行器一旦遇到 schema 1 计划必须保守地将其重新锚定到 schema 2 之下evidence-provenance.mjs 中snapshot命令对非 2 的--schema-version直接抛错Unsupported evidence provenance schema 1; schema 1 is legacy and must be conservatively re-anchored。二、三个子命令的 CLI 契约在目标仓库根目录运行当前技能目录下的 helpernode skill-dir/scripts/evidence-provenance.mjs read-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.mdskill-dir在本仓库中对应.claude/skills/gitnexus-plan或gitnexus-work、gitnexus/skills/...下的镜像副本取决于当前激活的技能。parseCli源码 evidence-provenance.mjs对每个子命令严格白名单校验允许的选项子命令允许选项输出read-plan--repo,--generated-planJSON 回执generated_plan_path、bytes_read、plan_digest、plan_bytes_base64snapshot--repo,--generated-plan,--cited可多次,--schema-version完整evidence_provenanceJSON 值write-plan--repo,--generated-plan,--replace,--expected-plan-path,--expected-plan-digestJSON 回执generated_plan_path、bytes_writtenDeepen 时附加prior_plan_backup_git_path解析器会拒绝未知选项、重复选项--cited除外、缺失值、多余的位置参数--repo与--generated-plan为必填。2.1 read-plan唯一受支持的计划读取方式node skill-dir/scripts/evidence-provenance.mjs read-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md它是 Deepen强化已有计划或执行计划时加载既有计划的唯一途径。回执携带规范的generated_plan_path、bytes_read、精确的plan_bytes_base64与plan_digest格式sha256:hex{ generated_plan_path: docs/plans/2026-07-11-gitnexus-plan-ingestion-retry.md, bytes_read: 18273, plan_digest: sha256:2c…64 位小写十六进制, plan_bytes_base64: … }调用方必须解码并消费这些精确字节绝不重新打开词法路径并需在整个 Deepen 会话期间把规范路径与摘要绑定保留——一份路径的回执永远不能授权另一份路径即使两者字节完全相同。2.2 snapshot生成 evidence_provenance 值node skill-dir/scripts/evidence-provenance.mjs snapshot \ --repo $PWD \ --schema-version 2 \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --cited src/one.ts \ --cited test/one.test.ts每一个被引用的路径都要传一个--cited参数脚本输出完整的evidence_provenanceJSON 值调用方需原样拷贝、绝不改写字段gitnexus-work在重锚定时会传入计划的schema_version、generated_plan_path以及cited_path_manifest中的每个路径。产出值结构源码 evidence-provenance.mjs{ schema_version: 2, head_commit: HEAD 完整 SHA, generated_plan_path: docs/plans/…, global_dirty_digest: { algorithm: sha256, canonicalization: gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records, value: 64 位小写 hex无 sha256: 前缀 }, cited_path_manifest: [] }gitnexus-work的 SKILLSKILL.md要求执行前做双层漂移检查two-layer drift check即使当前 HEAD 与计划 pin 相同也要同时重算全局 dirty digest 与 cited-path manifestSchema 1 无法无歧义重算必须保守重锚。2.3 write-plan唯一受支持的计划写入方式计划文档完全组合好之后通过 helper 发布其精确 UTF-8 字节node skill-dir/scripts/evidence-provenance.mjs write-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ /path/to/outside-repo-scratch-plan.md标准输入必须是合法 UTF-8且至多 16 MiB常量MAX_PLAN_BYTES 16 * 1024 * 1024见 evidence-provenance.mjsreadStdinBounded在超过时直接抛错成功的写入会打印含规范化generated_plan_path与bytes_written的 JSON 回执helper 会安全地创建缺失的父目录初始规划绝不传--replace——目标已存在即为错误写入采用 no-replace 原语write-plan命令拒绝了所有与其所选命令不匹配的选项直接 API 同样要求字面量布尔值与精确摘要字符串而非真值强制转换requireBoolean/normalizeSha256Digest于 evidence-provenance.mjs。2.4 write-plan --replace仅 Deepen 模式可用node skill-dir/scripts/evidence-provenance.mjs write-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --replace \ --expected-plan-path docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --expected-plan-digest sha256:digest-from-read-plan \ /path/to/outside-repo-scratch-plan.mdDeepen 流程的语义链是先用read-plan取得规范路径与摘要原地重写同一路径时附加--replace、--expected-plan-path generated_plan_path-from-read-plan、--expected-plan-digest plan_digest-from-that-same-receipt成功写入会额外返回prior_plan_backup_git_path——一个指向被顶替旧计划的、位于 Git 管理目录下的持久备份路径。校验约束源码 evidence-provenance.mjs--replace必须同时携带--expected-plan-path与--expected-plan-digest二者缺一即错未传--replace却携带这两个 expected 参数同样报错期望路径必须与写入目标逐字节相等——一个计划的相同字节不能授权另一个计划期望路径只能指向已存在的普通文件不接受符号链接或其他类型。三、路径契约谁可以被读写所有 Git 路径与 CLI 路径必须满足normalizeRepoPathevidence-provenance.mjs合法 UTF-8且已规范化为Unicode NFC非空的POSIX 仓库相对路径拒绝NUL、反斜杠、绝对路径 / 盘符/开头或/^[A-Za-z]:\//、空组件、.或..组件也拒绝无法往返编码的非法 Unicode 标量值。helper不做静默修复或别名化。以下情况一律 fail closed来自 Git 的非法 UTF-8、非 NFC 名称、索引未合并阶段unmerged stages、不支持的 Git 模式、socket/设备/FIFO、不可读对象、父路径组件中的符号链接穿越、快照期间观察到的仓库变更。generated-plan 路径的命名约束是双重的Schema 2 下计划路径永远是仓库相对路径快照排除与写入要求精确匹配docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-kebab-slug.md且必须是合法日历日期写入正则见源码GENERATED_PLAN_WRITE_PATTERN并做new Date(...)回环校验非法日期如2026-02-30会被拒绝/^docs\/plans\/(\d{4}-\d{2}-\d{2})-gitnexus-plan-[a-z0-9](?:-[a-z0-9]){2,4}\.md$/它们不能指向.git、源码、配置文件或任意仓库文件读取侧GENERATED_PLAN_READ_PATTERN为兼容文档化历史计划接受规范化的docs/plans/*gitnexus-plan*.md但保持同样的描述符锚定包含性检查该读取兼容性不会放宽写入器外部输出仓库外路径没有 Schema 2 表示——写入不允许 external 路径快照的排除是一次精确规范化路径比较源码 evidence-provenance.mjs.filter((record) record.path ! generatedPlan)——不允许 glob、目录、basename 或docs/plans/全目录排除若精确路径是重命名端点则仅排除该端点记录。四、安全的既有计划读取契约read-planread-plan采用fail-closed策略除非宿主机平台能基于持有的目录描述符解析名称否则拒绝读取Linux/proc/self/fd配合O_DIRECTORY与O_NOFOLLOWmacOSO_DIRECTORY/O_NOFOLLOW其它平台一律拒绝——未经验证的读取不是降级读取而是另一种带竞态的、不同的操作。读取流程对应 read-plan 实现 与规范 L99-L111解析出精确的 Git top-level以持有的 no-follow 目录描述符打开仓库根目录及每一级计划父目录拒绝缺失、符号链接、非目录与逃逸的父目录以O_NOFOLLOW打开叶子文件从持有的文件描述符读取至多 16 MiB要求合法 UTF-8对精确字节做哈希返回回执前证明父链与词法叶子仍指向同一批持有的对象。无论是 Deepen 还是 work 执行都不得解析此回执之前或之外获得的字节。规范原文对此的态度非常明确一份字节不匹配就换路径读取、或把 A 计划的摘要套到 B 计划上都是被禁止的。五、安全的 generated-plan 写入契约write-plan写入器的安全前提requireDescriptorAnchoringevidence-provenance.mjs宿主机必须提供O_DIRECTORY与O_NOFOLLOWLinux 还必须存在/proc/self/fd不 spawn 任何解释器、不加载任何原生代码发布原语是link(2)。5.1 link(2)原子、绝不替换规范与源码linkNoReplace/linkCreatedDespiteErrorevidence-provenance.mjs指出发布使用fs.linkSync其特性是原子目标名已被占用时返回EEXIST——无论占用者是普通文件、目录还是活/悬空符号链接都不跟随符号链接去覆盖其目标与renameat2(RENAME_NOREPLACE)、renameatx_np(RENAME_EXCL)提供相同的 no-replace 保证但在所有受支持平台均可通过fs.linkSync使用甚至在 v9fsWSL2 的 9p等renameat2不可用的文件系统上也能工作链接成功后临时名会被 unlink已发布文件与写入器创建并验证的是同一 inode因此下游所有身份检查构造性地成立链接成功但 unlink 失败时计划已被发布按成功报告——因为它确实成功了不支持硬链接的文件系统FAT、Coda、部分 SMB/FUSE/virtiofs会大声拒绝绝不降级为替换式 rename若系统报告错误但链接实际已建NFS 场景用源文件 nlink 是否达到 2 判定。计划父目录与仓库的 Git 管理目录必须位于同一文件系统。5.2 写入时序与 fsync 保障写入器流程规范 L134-L147 源码解析目标仓库精确 Git top-level以持有的 no-follow 目录描述符打开根与每个目标父目录相对这些描述符创建缺失父目录在写入边界证明描述符链与词法链仍标识同一批目录符号链接或非目录父目录、逃逸解析路径、符号链接/非常规最终目标、父目录被替换均为错误在持有的最终父描述符旁创建随机互斥临时文件保持其 no-follow 描述符打开写入并 flush 字节把临时名绑定到已打开的 inode在发布前对打开中的文件做哈希发布前一刻重新验证父目录与临时路径的 inode、大小、摘要发布相对持有的目录描述符把临时名 link 到目标——目标被占用时失败而非替换。因此初始模式即使出现先检查后目标出现也无法覆盖随后 flush 目录以O_NOFOLLOW重新打开已提交路径分别对原始临时 fd 与路径绑定 fd 做哈希再做一次描述符锚定的路径身份检查发现任何变更或替换即中止绝不接受混合时代的输出。每个新建的计划或 vault 目录先自身 fsync再 fsync 进其所在目录每次跨目录的保留性移动在报告成功或恢复路径前都会 fsync 源与目标目录。六、Linux 锚定 vs macOS 验证两条不同的证明路径这是本设计中一个刻意保留的真实差异而非被抹平的实现细节Linux上每个名字都经由/proc/self/fd/fd/child解析——这是内核基于描述符已持有的 inode解析的 magic link。其上的名字永远不会被重新遍历因此攻击者即使在检查与使用之间重命名了父目录也无法重定向操作——竞态是不可能的不只是被检测到。macOS没有这样的路径。/dev/fd/fd是 devfs 节点而非 magic link可以被 open但无法经由它解析任何子项open(/dev/fd/fd/child)返回ENOENT对它的realpath返回/dev/fd/fd而非目录路径规范注明这是在 macOS 26 上实测的非推断。Node 不暴露openat、dir_fd参数或 FFI因此 macOS 写入器的做法是在每个组件上以O_NOFOLLOW做词法解析在整个操作期间对链上每个目录持有打开的描述符在每一步之前与之后证明链仍恰好指向其持有的 inode。持有描述符正是让记录的 inode 号可信的原因一个打开的描述符 pin 住它的 inode被释放的编号无法在遍历下方被回收复用源码verifyPinnedDescriptorsevidence-provenance.mjs。两种平台共享同一个结论只是强度不同macOS 买到的是检测而非预防——检查与使用之间窗口内被调包的父目录会被紧随其后的检查捕获操作在未写入任何内容时中止但在 Linux 上它根本不可能发生。无论哪种平台没有任何已发布字节能逃过验证。实现注释还记录了一个值得注意的历史坑macOS 上曾为目录 open 追加O_NOFOLLOW_ANY但 XNU 在配合O_DIRECTORY时会直接以EINVAL拒绝导致 Darwin 上所有目录打开失败该标志已被移除且不会以探测或降级方式回归——逐组件O_NOFOLLOW遍历才是保证本身。七、Canonical bytes全局脏摘要的精确帧格式global_dirty_digest.value是对下列字节流计算出的小写 SHA-256不带sha256:前缀所有文本值均为其精确 UTF-8 字节下文的NUL指一个0x00字节。规范化字面量被定义为gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records帧结构与源码serializeDirtyRecords/canonicalRecord/serializeFields一致evidence-provenance.mjs前缀字段每个后跟 NUL再跟一个额外 NULgitnexus-evidence-provenance、schema_version、2零或多条记录按规范化路径 UTF-8 字节的**无符号字典序unsigned lexicographic comparison**排序——禁止 locale 序与文件系统序源码用compareUtf8做二进制字节比较并对重复规范化路径抛错每条记录为record NUL随后是按固定顺序的field-name NUL field-value NUL 对序列最后再加一个额外 NUL。固定字段RECORD_FIELDS为path、state、head_kind、index_kind、worktree_kind、untracked_kind、rename_from、rename_to、head_digest、index_digest、worktree_digest、untracked_digest字面量absent表示所有不可用的重命名端点、对象 kind 与层摘要——它永远不会是空字符串。固定字段数 前缀/记录后的额外 NUL 使帧边界无歧义值内不允许出现 NUL重复规范化路径被拒绝。八、记录、重命名与状态语义原始脏集合dirty set取自 Git porcelain v2源码 readDirtySnapshot读取时强制参数为git -c diff.renameLimit0 -c status.renameLimit0 status \ --porcelainv2 -z --untracked-filesall --find-renames50% --ignore-submodulesnone-zNUL 终止包含所有未跟踪文件子模块检查开启固定 50% 重命名阈值diff.renameLimit0与status.renameLimit0同时设置仓库配置无法限制重命名候选数量。共享同一路径的多个原始 porcelain 事实被合并为一条规范记录。一次重命名贡献两个端点事实旧端点pathold、rename_fromabsent、rename_tonew新端点pathnew、rename_fromold、rename_toabsent。两者通常都是renamed状态记录排序而非新旧角色决定先后顺序。工作区脏的重命名目标、或同时带另一事实的端点状态为mixed并保留重命名元数据。任一端点被引用时引用清单会自动扩为包含两端。普通XY状态映射源码classifyXYevidence-provenance.mjs条件状态索引列与工作区列都脏mixed删除任一列为 Ddeleted仅索引变更staged仅工作区变更unstaged?untracked同路径多个不同事实mixed阶段化删除后又重建文件保留 HEAD/index 事实文件系统对象记入 untracked 层? child/Git 内嵌目录标记去掉尾部斜杠后规范化child物化为一个有界目录对象引用路径不在脏集合内clean仅存在于 Git 层之外为untracked任何层都不存在为absent未合并路径u记录 /U列直接抛错无法规范化——先解决索引九、对象与摘要规则每个存在的层摘要格式为sha256:小写十六进制源码sha256()函数HEAD 层普通文件/符号链接Git blob 精确字节的 SHA-256目录精确原始 Git tree 字节的 SHA-256gitlinktree 中存储的 ASCII 对象 ID 的 SHA-256。索引层普通文件/符号链接stage-0 Git blob 字节的 SHA-256gitlink其 ASCII 对象 ID 的 SHA-256索引没有目录层任何非 stage-0 条目都会被拒绝。已跟踪工作区层普通文件原始文件字节以不跟随符号链接的方式打开读取源码hashFile全程O_NOFOLLOW 前后fstat身份一致性断言符号链接原始链接目标字节gitlink仅在rev-parse --show-toplevel证明该目录自身是嵌套仓库根、HEAD在其中可解析、且 porcelain v2 未报告该嵌套目录的任何 staged/unstaged/untracked/ignored 变更后才取检出嵌套 HEAD 的 ASCII 对象 ID同一 root/HEAD/clean 证明会被 mutation guard 重复一次脏、空、未初始化或父目录穿透的 gitlink 一律 fail closed目录下述 v1 目录流。层归属HEAD 与索引中都不存在的路径文件系统对象记入untracked层、worktree标记为 absentGit 托管的路径记入worktree、untracked标记为 absent缺失层对 kind 与 digest 都用字面量absent空文件是零字节的 SHA-256——绝不能用不存在冒充空文件。目录对象 v1 流前缀字段gitnexus-evidence-directory、schema_version、1同样的 NUL 帧递归条目按无符号 UTF-8 相对路径字节排序每条目固定字段path、kind、digest一次自底向上的文件系统遍历访问每个节点一次返回每个子摘要及展平子树以保留规范字节绝不跟随链接当目录被证明是精确的嵌套 Git top-level 时仅排除其管理性.git条目其余工作文件、嵌套目录仍是证据。目录边界DIRECTORY_LIMITSevidence-provenance.mjs每次遍历至多 10,000 个条目、深度 256、普通文件内容至多 256 MiB超过任一上限即 fail closed且各界限独立适用于每条记录物化的每个顶层目录对象。竞态防护源码末尾verifyGuards 快照前后双重比对HEAD 对象只从快照开始时捕获的完整对象 ID 读取符号名HEAD绝不针对各层重新解析索引层从一次捕获的 stage-0 列表解析helper 守护对应的 HEAD/ref/reflog 控制文件与原始索引文件结束时比对捕获列表拒绝普通的 A→B→A 变更而非接受混合时代层普通文件经O_NOFOLLOW描述符读取并做前后身份检查符号链接用 lstat/readlink/lstat目录在盘点前后记录身份开始与结束时比对 porcelain-v2 status 与 HEAD并重查文件系统守卫被引用的缺失路径持有最近存在父目录的 no-follow 描述符记录首个缺失组件/叶子该锚定缺失在最终 Git status pass 前后各查一次使新建的 ignored 路径无法逃避 porcelain观察到任何竞态都拒绝整个快照绝不输出混合时代的证据。十、在 gitnexus-plan / gitnexus-work 全流程中的落位理解了契约后再看它在两个技能中何时、为何被调用会更有价值gitnexus-plan规划永不改动生产代码——SKILL.mdPhase 4定向源码验证结束前立即按本文档要求重算evidence_provenance快照重读规划期间发生变化的任何引用且只排除 generated-plan 路径Phase 5 组合计划时把该 schema-2 JSON 原样拷入 §11 包的强制evidence_provenance字段见 plan-template.md 与 context-pack.md 中此为该字段唯一规范 schema的声明再整体交给write-plan初始模式不带--replaceDeepen 模式则先read-plan→ 全量重跑 Phase 1 → 重锚再重 pin → 以write-plan --replace --expected-plan-path --expected-plan-digest原地重写同一规范文件并保留回执中的prior_plan_backup_git_path。gitnexus-work执行会改动代码——SKILL.md输入三态计划路径、最新docs/plans/*gitnexus-plan*.md、或小任务直通模式解析 §11 包并要求回执规范路径与evidence_provenance.generated_plan_path逐字节相等缺失 provenance 或 schema 1 一律视为 legacy 计划绝非干净树执行前做两层漂移检查与保守重锚重锚结果留在会话状态、永不改写计划正文用git rev-parse --git-path解析备份路径gitnexus-plan-backups/random-name而绝不可把它当作仓库相对工作树路径——该约定在计划父目录发布后被重命名时依然有效。十一、总结它为什么值得作为 byte contract 存在从工程本质看这份文档把AI 写了什么、依据了哪棵确切的仓库状态从不可审计的自然语言压缩成了可复算、可字节级比对的证据流。它的设计取舍非常清晰只信描述符不信词法路径——读取与写入都锚定在 held directory descriptor 上Linux 让竞态不可能macOS 让竞态必然被发现只信精确字节不信语义巧合——同一路径、同一摘要、同一 inode 是强绑定的三位一体同一字节的拷贝也不能授权另一路径只信 no-replace 原语不信先查后写——link(2)让覆盖别人的文件在结构上不可行写入前自证、写入后再证——fsync、inode、digest 多重验证绝不允许混合时代的输出逃逸。后续代码阅读推荐按此顺序先读规范文档 references/evidence-provenance.md再对照 scripts/evidence-provenance.mjs 的normalizeRepoPath、readDirtySnapshot、canonicalRecord、serializeDirtyRecords、linkNoReplace、parseCli、main等关键函数随后结合两个 SKILL 看调用时序最后在.claude/skills/gitnexus-plan/references/context-pack.md中确认evidence_provenance在实施上下文包中的字段语义。这套契约同时服务 AI 规划器的防伪与执行器的防错是让多代理、多会话、跨平台协作下仍能保持仓库证据可信的底层保障。【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考