尧图网页设计 
GitNexus 证据溯源与安全写入evidence-provenanceSchema 2 规范与原子化 Plan 发布机制【免费下载链接】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 中AI Agent 生成的实施计划generated plan不是普通文件——它必须携带它到底依据了哪个工作树状态、哪些被引用源码的确切字节的可验证溯源信息。本文以 gitnexus-claude-plugin/skills/gitnexus-plan/references/evidence-provenance.md 这份规范文档为主体围绕evidence_provenanceschema 2 的规范字节契约与配套安全读写器 gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs 展开你将掌握read-plan/snapshot/write-plan三条命令的完整用法、generated-plan 路径约束、基于目录描述符directory descriptor锚定的竞态安全读写契约、link(2)原子 no-replace 发布原理以及脏工作树 被引用路径逐层 SHA-256 摘要的字节级序列化格式从而能安全地生成、读取与深化一份 GitNexus 计划文档。一、这份文档在 GitNexus 技能体系中的地位GitNexus 将制定计划gitnexus-plan与执行计划gitnexus-work拆成两个技能前者只规划、绝不改代码后者按计划的 §11 implementation context pack 逐条落地并提交。这两个技能之间存在一条必须被双方信任的交接边界——计划文档本身。evidence-provenance规范文档就是这条边界的规范性字节契约normative byte contract用于约束evidence_provenanceschema 2 这个机器可读快照字段的编码方式。关键设计约束包括可执行定义与规范分离紧邻的scripts/evidence-provenance.mjs是该契约的可执行定义executable definition文档本身才是应当如何编码的权威文字。字节级一致的副本gitnexus-plan与gitnexus-work各自携带逐字节相同的规范与 helper任一技能都能在只依赖自身安装的前提下产出相同的快照。仓库内可验证的三处对照为 gitnexus/skills/gitnexus-plan/references/evidence-provenance.md、gitnexus/skills/gitnexus-work/references/evidence-provenance.md 与其脚本副本 gitnexus/skills/gitnexus-work/scripts/evidence-provenance.mjs。唯一的写入边界它是生成计划的唯一受支持的写入边界。规范明文要求绝不要用临时的 shell 管道重算摘要也绝不直接写计划目标路径。gitnexus-plan的 SKILL.md 硬规则Pin working-tree evidence, not only HEAD与Write the plan only through the helper均指向同一结论摘要与发布都必须经由该 helper 完成。schema 1 是遗留格式且被刻意拒绝一旦遇到执行方必须在 schema 2 下保守地重新锚定re-anchor而不是继续使用旧格式。二、三个 CLI 命令read-plan / snapshot / write-plan在目标仓库根目录下运行当前活动技能自带的 helper。命令形态如下skill-dir可替换为仓库内实际路径例如gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs1. read-plan —— 加载既有计划Deepen 或执行的前置node skill-dir/scripts/evidence-provenance.mjs read-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.mdread-plan是加载既有计划进行 Deepen深化或执行的唯一受支持方式。它输出一份 JSON receipt包含规范化的generated_plan_path、bytes_read、精确的plan_bytes_base64以及plan_digest形如sha256:hex。使用时须遵守解码并消费 receipt 中的精确字节不要重新按词法路径lexical path打开文件将规范化路径与摘要绑定保留整个 Deepen 会话一份路径的 receipt 绝不授权另一份路径——即便它们的字节完全相同。在实现中对应 readPlanSafely它对每个读取路径先打开持有式 no-follow 目录描述符并验证父链对叶子用O_NOFOLLOW打开最多读取 16 MiB强制要求合法 UTF-8对精确字节做哈希最后在返回 receipt 前证明父链与词法叶子仍指向同一批持有对象。2. snapshot —— 生成 evidence_provenance JSON 值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参数helper 输出完整的evidence_provenanceJSON 值使用方应整体复制且不重写任何字段gitnexus-work执行时会传入计划中的schema_version、generated_plan_path与cited_path_manifest里每个路径schema 1 会被拒绝见 parseCli 中对 schema-version 的校验。snapshot 的实现见 snapshotEvidence返回结构包含schema_version、head_commit、generated_plan_path、global_dirty_digest含 algorithm/canonicalization/value以及排序后的cited_path_manifest。3. write-plan —— 发布计划的唯一写入路径在快照进入完整文档后把文档的精确 UTF-8 字节通过同一 helper 发布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仅 Deepen 模式使用--replacenode 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.md写入规则总结规则说明初始计划绝不传--replace目标已存在即为错误no-replace 语义Deepen 的--replace三件套--replace--expected-plan-path须等于 read-plan receipt 的generated_plan_path--expected-plan-digest须等于同一 receipt 的plan_digest标准输入约束必须是合法 UTF-8最大 16 MiB成功输出JSON receipt含规范化generated_plan_path与bytes_writtenDeepen 成功额外输出prior_plan_backup_git_path——被替换计划在 Git 管理目录Git-admin中的持久化备份路径CLI 参数严格性拒绝任何不适用于当前命令的选项直接 API 亦要求字面量布尔值与精确摘要字符串不做 truthy 强转上述严格性在源码中都有对应实现参数白名单在 parseClisnapshot/read-plan/write-plan各自的 allowed 集合requireBoolean/normalizeSha256Digest强制字面量布尔与sha256:64位小写hex精确格式主流程 main 仅在作为脚本被直接调用时执行。三、路径契约Path contract所有 Git 路径与 CLI 路径必须满足 normalizeRepoPath 的校验合法 UTF-8且已是 Unicode NFC 规范化形式非空的 POSIX 仓库相对路径拒绝NUL 字节、反斜杠、绝对路径/盘符路径、空组件、.与..组件helper不静默修复或别名化这些非法输入。显式 fail-closed检出即失败的情形还包括来自 Git 的非法 UTF-8、非 NFC 名称、未合并的 index 阶段、不支持的 Git 模式、socket/设备/FIFO、不可读对象、父路径组件中的符号链接穿越以及在快照期间观察到的仓库变更。generated-plan 路径在 schema 2 下恒为仓库相对路径。快照排除与写入都要求严格匹配docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-kebab-slug.md即必须包含合法日历日期且 slug 为 35 个词的 kebab-case。写入器不得指向.git、源码、配置文件或任意仓库文件。源码中的模式定义在 GENERATED_PLAN_READ_PATTERN 与 GENERATED_PLAN_WRITE_PATTERN且 normalizeGeneratedPlanWritePath 会用Date解析进一步验证日历日期真实存在拒绝2026-02-30之类。读宽写窄read-widening为兼容文档化与遗留计划read-plan接受匹配docs/plans/*gitnexus-plan*.md的规范化文件同时保留同样的基于描述符的包含性检查但读取兼容性不会放宽写入器。外部输出没有 schema-2 表示。快照排除是一次精确的规范化路径比较不允许glob、目录、basename 或整个docs/plans/范围的排除若该精确路径恰是重命名端点仅排除该端点记录。四、安全读取契约read-plan 的 fail-closed 语义read-plan只有在宿主平台能针对持有的目录描述符解析名称时才可用Linux/proc/self/fdO_DIRECTORY/O_NOFOLLOWmacOSO_DIRECTORY/O_NOFOLLOW其他任何平台直接被拒绝——未被验证的读取不是降级的读取而是另一种存在竞态的操作。requireDescriptorAnchoring 正是这条平台门槛的实现。读取流程为解析精确的 Git top-level → 把仓库根与每个计划父目录作为持有式 no-follow 目录描述符打开 → 拒绝缺失、符号链接、非目录与逃逸的父目录 → 用O_NOFOLLOW打开叶子 → 从该持有描述符读取最多 16 MiB → 要求合法 UTF-8 → 对精确字节做哈希 → 返回 receipt 前证明父链与词法叶子仍命名同一批持有对象。Deepen 与 work 都不得解析 receipt 之外获取的字节。五、安全写入契约write-plan 的原子 no-replace 发布这是全文档技术含量最高的部分核心诉求是发布动作本身在任何竞态下都不允许覆盖他人写入、不允许跟随符号链接、不允许留下混合时代的产物。5.1 平台前提与发布原语写入器 fail-closed除非平台提供O_DIRECTORY与O_NOFOLLOWLinux 还需/proc/self/fd。它不启动任何解释器、不加载任何原生代码发布原语是link(2)——原子、目标名被占用时返回EEXIST、且不跟随符号链接。这与renameat2(RENAME_NOREPLACE)、renameatx_np(RENAME_EXCL)提供相同的 no-replace 保证并通过fs.linkSync在所有受支持平台可用。实现见 linkNoReplace / linkCreatedDespiteError其中对link 返回错误但实际已创建NFS 场景通过检查源文件 nlink 是否达到 2 来兜底对不支持硬链接的文件系统EPERM/ENOTSUP/EMLINK则大声拒绝绝不回退到会覆盖的 rename。5.2 写前写后的完整校验链写入器执行解析目标仓库精确 Git top-level打开根与每个目标父目录为持有式 no-follow 描述符按描述符创建缺失父目录并在写入边界证明描述符链与词法链仍指向同一目录在持有的最终父描述符旁创建随机排他临时文件并保持其 no-follow 描述符打开写入、刷新字节绑定临时名到已打开 inode发布前对打开文件做哈希发布前一刻重新校验父目录与临时路径的 inode、大小、摘要——初发模式下即使目标在缺失检查之后才出现也无法被覆盖link 对已占用名返回 EEXIST发布后刷新目录用O_NOFOLLOW重新打开已提交路径对原始临时 fd 与路径绑定 fd 分别哈希再做第二次描述符锚定的路径身份校验。检测到任何变更或替换都会中止而不是接受混合时代的输出。校验链实现在 writePlanSafely 与 validateCommittedPlan。5.3 Linux 锚定 vs macOS 验证两个平台殊途同归但证明路径不同Linux 锚定anchors每个名字都经/proc/self/fd/fd/child解析。这是内核直接针对描述符已持有的 inode 解析的 magic link其上方的名字永远不会被重新遍历——攻击者在检查与使用之间重命名父目录也无法重定向操作。竞态不是被检测而是不可能发生。macOS 验证verifies/dev/fd/fd是 devfs 节点而非 magic link文档注明在 macOS 26 上实测open(/dev/fd/fd/child)返回ENOENTrealpath返回/dev/fd/fd而非目录路径Node 不暴露openat、dir_fd参数或 FFI。因此 macOS 端在每一组件上以O_NOFOLLOW词法解析、在整个操作期间持有链上每个目录的打开描述符并在每一步前后证明链仍精确命名其持有的 inode。持有描述符正是让已记录 inode 号可信的原因打开描述符钉住了 inode被释放的 inode 号无法在遍历下方被回收复用。实际效果差异macOS 买到的是检测——检查与使用之间窗口内的父目录交换会被其后的检查抓住并中止此时尚未写出任何字节而 Linux 上这类竞态根本不可能发生。无论哪个平台已发布的字节都无法逃过验证。两个后端的实现在 LINUX_ANCHORING 与 DARWIN_ANCHORING 中清晰对照其余所有操作经由统一的anchoredChild收口为单个普通路径组件含对尾随斜杠会破坏O_NOFOLLOW的注释警示见 anchoredChild。5.4 --replace 与 Git-admin 备份 vault--replace只接受已存在的常规文件且专用于 Deepen不带它时意外覆盖会被拒绝。它额外要求同一会话read-planreceipt 中的精确规范化generated_plan_path与plan_digest且期望路径必须与写入目标完全相等——一份计划的相同字节不能授权另一份计划。Deepen 替换的时序是先对仍持有的旧计划 fd 做哈希拒绝任何摘要/inode/路径不匹配包括同 inode 编辑、读写之间的变更将当前目标无替换地原子移动到Git 管理目录Git-admin下随机命名的gitnexus-plan-backups/文件vault 打开逻辑见 openBackupVault并针对该持有 fd 验证被移动的 inode 与摘要只有以上全部通过才用同一原子 no-replace 原语发布新计划。任一边界重新出现的目标都会保持原样不动。每个新建计划/vault 目录都会先 fsync 自身、再 fsync 进其所在目录每次跨目录的保留性移动在报告成功或恢复路径前都会 fsync 源与目标两个目录。故障恢复语义一旦临时字节已存在失败发布或失败验证会把所有可得的 prior / displaced / unpublished / intended 计划先保留进该 Git-admin vault再报告失败。每个被报告的恢复对象都会从新解析的 Git 根重新打开并验证然后才在错误信息中以git-path:gitnexus-plan-backups/random-name命名。消费方必须用git rev-parse --git-path gitnexus-plan-backups/random-name解析该值绝不可将其解释为仓库相对工作树路径。这一保证在持有计划父目录被重命名后依然成立写入器也绝不经陈旧的词法父目录报告恢复绝不执行先身份检查再 unlink式的回滚那可能删除竞态者的替换文件。只读或不支持的 checkout 会产生阻塞性错误调用方不得绕过 helper、重定向到外部路径或削弱这些检查。六、规范字节Canonical bytes全局脏摘要怎么算global_dirty_digest.value是覆盖如下字节流的小写 SHA-256不带sha256:前缀。所有文本值取其精确 UTF-8 字节下文NUL指一个0x00字节前缀字段各随一个 NUL随后再一个额外 NULgitnexus-evidence-provenance、schema_version、2零或多条记录按规范化路径 UTF-8 字节的无符号字典序排序locale 与文件系统顺序一律禁止每条记录为record NUL随后固定顺序的field-name NUL field-value NUL 对序列末尾再一个额外 NUL。字段顺序恰为源码 RECORD_FIELDS 所声明的 12 个path、state、head_kind、index_kind、worktree_kind、untracked_kind、rename_from、rename_to、head_digest、index_digest、worktree_digest、untracked_digest字面量absent代表所有不可得的重命名端点、对象种类与层摘要——它绝不是空字符串。序列化实现在 serializeFields 与 serializeDirtyRecords后者额外做重复规范化路径拒绝。schema 的规范化字面量canonicalization literal精确为gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records固定字段数加上前缀/记录后的额外 NUL 使成帧无歧义——值内部不能含 NUL。这一 literal 作为global_dirty_digest.canonicalization随 JSON 输出。七、记录、重命名与状态Records, renames, and states原始脏集合由 Git porcelain v2 获取见 readDirtySnapshotgit status --porcelainv2 -z --untracked-filesall \ --find-renames50% --ignore-submodulesnone并且强制diff.renameLimit0与status.renameLimit0使仓库配置无法截断重命名候选。共享同一路径的原始 porcelain 事实会被合并为一条规范化记录。状态映射规则普通XY状态索引列与工作树列同时脏 →mixed删除 →deleted仅索引变更 →staged仅工作树变更 →unstaged。映射逻辑见 classifyXY?→untracked同一路径的多个不同事实 →mixed因此已暂存删除 重建文件仍保留 HEAD/index 事实而文件系统对象记入 untracked 层? child/是 Git 的内嵌目录标记规范化前去掉尾随斜杠child作为一个有界目录对象被实体化若实际并非目录则报错见 materializeRecord未合并unmerged阶段U或u记录直接拒绝先解决 index 再规范化引用路径位于脏集合之外时为clean仅存在于 Git 层之外时为untracked任何层都不存在时为absent。重命名是双端点一次重命名贡献两条事实——旧端点rename_fromabsent, rename_tonew新端点rename_fromold, rename_toabsent两者常态下状态均为renamed顺序由记录排序决定与新旧角色无关。工作树脏的重命名目标或同时带其他事实的端点为mixed并保留重命名元数据。任一端点被引用时引用清单会展开为同时包含两端见 snapshotEvidence 中引用集合的展开。八、对象与摘要规则Object and digest rules每个存在层的摘要均为sha256:小写hexHEAD 常规文件/符号链接精确 Git blob 字节的 SHA-256HEAD 目录精确原始 Git tree 字节的 SHA-256HEAD gitlinktree 存储的 ASCII 对象 ID 的 SHA-256Index 常规文件/符号链接stage-0 Git blob 字节的 SHA-256Index gitlink其 ASCII 对象 ID 的 SHA-256index 没有目录层任何非 stage-0 条目都被拒绝被跟踪的工作树常规文件不跟随符号链接打开的原始文件字节符号链接原始链接目标字节gitlink检出嵌套 HEAD 处的 ASCII 对象 ID——但必须先经rev-parse --show-toplevel证明该目录自身是嵌套仓库根、HEAD可在该处解析且 porcelain v2 报告无任何 staged/unstaged/untracked/ignored 嵌套变更脏、空、未初始化或父目录穿透的 gitlink fail-closed见 readOwnGitlinkHead目录下文 v1 目录流同时缺席于 HEAD 与 index 的路径把文件系统对象放入untracked层并将worktree标记 absentGit 托管的路径放入worktree并把untracked标记 absent缺失层对 kind 与 digest 均用字面量absent空文件是零字节的 SHA-256绝不与 absent 混为一谈。目录对象v1 目录流文件系统目录字节使用前缀字段gitnexus-evidence-directory、schema_version、1、同样的 NUL 成帧以及按无符号 UTF-8 相对路径字节排序的递归条目每条目固定字段为path、kind、digest。一次自底向上的文件系统遍历访问每个节点一次返回每个子摘要及为保留规范字节所需的扁平化子树链接从不被跟随。当目录被证明是精确的嵌套 Git top-level 时仅排除其管理性.git条目——其余每个子项含工作文件与嵌套目录都保留为证据。每个目录对象有界10,000 个访问条目、深度 256、256 MiB 常规文件内容超界 fail-closed且这些界独立作用于每条记录实体化的每个顶层目录对象。实现与常量见 digestDirectory 与 DIRECTORY_LIMITS。分层一致性HEAD 对象只从快照开始时捕获的完整对象 ID 读取符号HEAD名称绝不为各层重新解析index 层从一次捕获的 stage-0 清单解析helper 守护对应的 HEAD/ref/reflog 控制文件与原始 index 文件结束时比对捕获清单拒绝普通的 A→B→A 变更绝不接受混合时代的层。九、全程竞态防护变更守卫mutation guards快照期间的每一次读取都被守卫包裹任何观测到的竞态都会拒绝快照而不是输出混合时代证据常规文件通过O_NOFOLLOW描述符读取并做前/后身份校验见 hashFile符号链接使用 lstat/readlink/lstat目录在盘点前后记录身份helper 同时比较快照开始与结束时的原始 porcelain-v2 状态与 HEAD再复检文件系统守卫snapshotEvidence 的verifyGuards与终末比较见 gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs#L2175-L2228absent 引用路径会为最近的现存父目录持有 no-follow 描述符并记录第一个缺失组件/叶子该锚定缺席在最终 Git 状态传递前后都被检查使新建的 ignored 路径无法规避 porcelain。缺席锚定按仓库相对前缀去重并钉住描述符防止 inode 号复用实现见 recordAnchoredAbsence。十、落点验证helper 在仓库与评测体系中的使用gitnexus-plan生命周期Phase 4 末尾、组合计划前按规范重新计算evidence_provenance快照全局脏摘要 排序引用清单仅排除本次 generated-plan 路径Phase 5 以 stdin 通过write-plan发布Deepen 以read-plan→ 深度重验 →write-plan --replace重写同一规范化文件。规范细节见 gitnexus/skills/gitnexus-plan/SKILL.md 与 gitnexus/skills/gitnexus-plan/references/context-ledger.mdevidence_provenance是 ledger 中必填的不可变工作快照。gitnexus-work的双层漂移检查执行器即使在同一 HEAD 也总重新计算全局脏摘要与引用清单路径或摘要不匹配即触发保守 re-anchor重新读取已变更引用、评估新增未引用脏路径缺失或 schema-1 证据一律在 schema 2 下重锚。见 gitnexus/skills/gitnexus-work/SKILL.md 与其 README.md。评测沙箱eval/workflow_bench/proposer_sandbox.py 中实现了一个受信任、自我拥有的 Python 3 启动器专门用于调用evidence-provenance.mjs的原子移动器见其文件内 L447-L452 一带验证沙箱环境不信任 PATH 扫描到的任意可执行文件。这从评测侧佐证了 helper 作为唯一受信任写入边界的定位。十一、快速查阅索引关注点仓库路径规范正文本文主体来源gitnexus-claude-plugin/skills/gitnexus-plan/references/evidence-provenance.md规范的可执行定义gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjswork 技能字节一致副本gitnexus/skills/gitnexus-work/scripts/evidence-provenance.mjs规划技能规则与 Deepen 流程gitnexus/skills/gitnexus-plan/SKILL.md工作台账字段语义gitnexus/skills/gitnexus-plan/references/context-ledger.md小结GitNexus 把AI 生成的计划当做一个需要密码学强度溯源的决策工件来对待。evidence-provenanceschema 2 定义了可跨技能复现的字节级快照格式而配套 helper 用目录描述符锚定、原子link(2)no-replace 发布与 Git-admin 备份 vault把读取旧计划、生成快照、写入新计划收敛为三条纪律严明的命令。理解这套契约你就能在 GitNexus或其他采用该技能的仓库中安全地生成、交接并深化带完整证据链的实施计划而不会把计划可信度寄托在脆弱的词法路径与 shell 管道之上。【免费下载链接】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），仅供参考 GitNexus 证据溯源与安全写入：`evidence-provenance` Schema 2 规范与原子化 Plan 发布机制
GitNexus 证据溯源与安全写入evidence-provenanceSchema 2 规范与原子化 Plan 发布机制【免费下载链接】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 中AI Agent 生成的实施计划generated plan不是普通文件——它必须携带它到底依据了哪个工作树状态、哪些被引用源码的确切字节的可验证溯源信息。本文以 gitnexus-claude-plugin/skills/gitnexus-plan/references/evidence-provenance.md 这份规范文档为主体围绕evidence_provenanceschema 2 的规范字节契约与配套安全读写器 gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs 展开你将掌握read-plan/snapshot/write-plan三条命令的完整用法、generated-plan 路径约束、基于目录描述符directory descriptor锚定的竞态安全读写契约、link(2)原子 no-replace 发布原理以及脏工作树 被引用路径逐层 SHA-256 摘要的字节级序列化格式从而能安全地生成、读取与深化一份 GitNexus 计划文档。一、这份文档在 GitNexus 技能体系中的地位GitNexus 将制定计划gitnexus-plan与执行计划gitnexus-work拆成两个技能前者只规划、绝不改代码后者按计划的 §11 implementation context pack 逐条落地并提交。这两个技能之间存在一条必须被双方信任的交接边界——计划文档本身。evidence-provenance规范文档就是这条边界的规范性字节契约normative byte contract用于约束evidence_provenanceschema 2 这个机器可读快照字段的编码方式。关键设计约束包括可执行定义与规范分离紧邻的scripts/evidence-provenance.mjs是该契约的可执行定义executable definition文档本身才是应当如何编码的权威文字。字节级一致的副本gitnexus-plan与gitnexus-work各自携带逐字节相同的规范与 helper任一技能都能在只依赖自身安装的前提下产出相同的快照。仓库内可验证的三处对照为 gitnexus/skills/gitnexus-plan/references/evidence-provenance.md、gitnexus/skills/gitnexus-work/references/evidence-provenance.md 与其脚本副本 gitnexus/skills/gitnexus-work/scripts/evidence-provenance.mjs。唯一的写入边界它是生成计划的唯一受支持的写入边界。规范明文要求绝不要用临时的 shell 管道重算摘要也绝不直接写计划目标路径。gitnexus-plan的 SKILL.md 硬规则Pin working-tree evidence, not only HEAD与Write the plan only through the helper均指向同一结论摘要与发布都必须经由该 helper 完成。schema 1 是遗留格式且被刻意拒绝一旦遇到执行方必须在 schema 2 下保守地重新锚定re-anchor而不是继续使用旧格式。二、三个 CLI 命令read-plan / snapshot / write-plan在目标仓库根目录下运行当前活动技能自带的 helper。命令形态如下skill-dir可替换为仓库内实际路径例如gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs1. read-plan —— 加载既有计划Deepen 或执行的前置node skill-dir/scripts/evidence-provenance.mjs read-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.mdread-plan是加载既有计划进行 Deepen深化或执行的唯一受支持方式。它输出一份 JSON receipt包含规范化的generated_plan_path、bytes_read、精确的plan_bytes_base64以及plan_digest形如sha256:hex。使用时须遵守解码并消费 receipt 中的精确字节不要重新按词法路径lexical path打开文件将规范化路径与摘要绑定保留整个 Deepen 会话一份路径的 receipt 绝不授权另一份路径——即便它们的字节完全相同。在实现中对应 readPlanSafely它对每个读取路径先打开持有式 no-follow 目录描述符并验证父链对叶子用O_NOFOLLOW打开最多读取 16 MiB强制要求合法 UTF-8对精确字节做哈希最后在返回 receipt 前证明父链与词法叶子仍指向同一批持有对象。2. snapshot —— 生成 evidence_provenance JSON 值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参数helper 输出完整的evidence_provenanceJSON 值使用方应整体复制且不重写任何字段gitnexus-work执行时会传入计划中的schema_version、generated_plan_path与cited_path_manifest里每个路径schema 1 会被拒绝见 parseCli 中对 schema-version 的校验。snapshot 的实现见 snapshotEvidence返回结构包含schema_version、head_commit、generated_plan_path、global_dirty_digest含 algorithm/canonicalization/value以及排序后的cited_path_manifest。3. write-plan —— 发布计划的唯一写入路径在快照进入完整文档后把文档的精确 UTF-8 字节通过同一 helper 发布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仅 Deepen 模式使用--replacenode 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.md写入规则总结规则说明初始计划绝不传--replace目标已存在即为错误no-replace 语义Deepen 的--replace三件套--replace--expected-plan-path须等于 read-plan receipt 的generated_plan_path--expected-plan-digest须等于同一 receipt 的plan_digest标准输入约束必须是合法 UTF-8最大 16 MiB成功输出JSON receipt含规范化generated_plan_path与bytes_writtenDeepen 成功额外输出prior_plan_backup_git_path——被替换计划在 Git 管理目录Git-admin中的持久化备份路径CLI 参数严格性拒绝任何不适用于当前命令的选项直接 API 亦要求字面量布尔值与精确摘要字符串不做 truthy 强转上述严格性在源码中都有对应实现参数白名单在 parseClisnapshot/read-plan/write-plan各自的 allowed 集合requireBoolean/normalizeSha256Digest强制字面量布尔与sha256:64位小写hex精确格式主流程 main 仅在作为脚本被直接调用时执行。三、路径契约Path contract所有 Git 路径与 CLI 路径必须满足 normalizeRepoPath 的校验合法 UTF-8且已是 Unicode NFC 规范化形式非空的 POSIX 仓库相对路径拒绝NUL 字节、反斜杠、绝对路径/盘符路径、空组件、.与..组件helper不静默修复或别名化这些非法输入。显式 fail-closed检出即失败的情形还包括来自 Git 的非法 UTF-8、非 NFC 名称、未合并的 index 阶段、不支持的 Git 模式、socket/设备/FIFO、不可读对象、父路径组件中的符号链接穿越以及在快照期间观察到的仓库变更。generated-plan 路径在 schema 2 下恒为仓库相对路径。快照排除与写入都要求严格匹配docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-kebab-slug.md即必须包含合法日历日期且 slug 为 35 个词的 kebab-case。写入器不得指向.git、源码、配置文件或任意仓库文件。源码中的模式定义在 GENERATED_PLAN_READ_PATTERN 与 GENERATED_PLAN_WRITE_PATTERN且 normalizeGeneratedPlanWritePath 会用Date解析进一步验证日历日期真实存在拒绝2026-02-30之类。读宽写窄read-widening为兼容文档化与遗留计划read-plan接受匹配docs/plans/*gitnexus-plan*.md的规范化文件同时保留同样的基于描述符的包含性检查但读取兼容性不会放宽写入器。外部输出没有 schema-2 表示。快照排除是一次精确的规范化路径比较不允许glob、目录、basename 或整个docs/plans/范围的排除若该精确路径恰是重命名端点仅排除该端点记录。四、安全读取契约read-plan 的 fail-closed 语义read-plan只有在宿主平台能针对持有的目录描述符解析名称时才可用Linux/proc/self/fdO_DIRECTORY/O_NOFOLLOWmacOSO_DIRECTORY/O_NOFOLLOW其他任何平台直接被拒绝——未被验证的读取不是降级的读取而是另一种存在竞态的操作。requireDescriptorAnchoring 正是这条平台门槛的实现。读取流程为解析精确的 Git top-level → 把仓库根与每个计划父目录作为持有式 no-follow 目录描述符打开 → 拒绝缺失、符号链接、非目录与逃逸的父目录 → 用O_NOFOLLOW打开叶子 → 从该持有描述符读取最多 16 MiB → 要求合法 UTF-8 → 对精确字节做哈希 → 返回 receipt 前证明父链与词法叶子仍命名同一批持有对象。Deepen 与 work 都不得解析 receipt 之外获取的字节。五、安全写入契约write-plan 的原子 no-replace 发布这是全文档技术含量最高的部分核心诉求是发布动作本身在任何竞态下都不允许覆盖他人写入、不允许跟随符号链接、不允许留下混合时代的产物。5.1 平台前提与发布原语写入器 fail-closed除非平台提供O_DIRECTORY与O_NOFOLLOWLinux 还需/proc/self/fd。它不启动任何解释器、不加载任何原生代码发布原语是link(2)——原子、目标名被占用时返回EEXIST、且不跟随符号链接。这与renameat2(RENAME_NOREPLACE)、renameatx_np(RENAME_EXCL)提供相同的 no-replace 保证并通过fs.linkSync在所有受支持平台可用。实现见 linkNoReplace / linkCreatedDespiteError其中对link 返回错误但实际已创建NFS 场景通过检查源文件 nlink 是否达到 2 来兜底对不支持硬链接的文件系统EPERM/ENOTSUP/EMLINK则大声拒绝绝不回退到会覆盖的 rename。5.2 写前写后的完整校验链写入器执行解析目标仓库精确 Git top-level打开根与每个目标父目录为持有式 no-follow 描述符按描述符创建缺失父目录并在写入边界证明描述符链与词法链仍指向同一目录在持有的最终父描述符旁创建随机排他临时文件并保持其 no-follow 描述符打开写入、刷新字节绑定临时名到已打开 inode发布前对打开文件做哈希发布前一刻重新校验父目录与临时路径的 inode、大小、摘要——初发模式下即使目标在缺失检查之后才出现也无法被覆盖link 对已占用名返回 EEXIST发布后刷新目录用O_NOFOLLOW重新打开已提交路径对原始临时 fd 与路径绑定 fd 分别哈希再做第二次描述符锚定的路径身份校验。检测到任何变更或替换都会中止而不是接受混合时代的输出。校验链实现在 writePlanSafely 与 validateCommittedPlan。5.3 Linux 锚定 vs macOS 验证两个平台殊途同归但证明路径不同Linux 锚定anchors每个名字都经/proc/self/fd/fd/child解析。这是内核直接针对描述符已持有的 inode 解析的 magic link其上方的名字永远不会被重新遍历——攻击者在检查与使用之间重命名父目录也无法重定向操作。竞态不是被检测而是不可能发生。macOS 验证verifies/dev/fd/fd是 devfs 节点而非 magic link文档注明在 macOS 26 上实测open(/dev/fd/fd/child)返回ENOENTrealpath返回/dev/fd/fd而非目录路径Node 不暴露openat、dir_fd参数或 FFI。因此 macOS 端在每一组件上以O_NOFOLLOW词法解析、在整个操作期间持有链上每个目录的打开描述符并在每一步前后证明链仍精确命名其持有的 inode。持有描述符正是让已记录 inode 号可信的原因打开描述符钉住了 inode被释放的 inode 号无法在遍历下方被回收复用。实际效果差异macOS 买到的是检测——检查与使用之间窗口内的父目录交换会被其后的检查抓住并中止此时尚未写出任何字节而 Linux 上这类竞态根本不可能发生。无论哪个平台已发布的字节都无法逃过验证。两个后端的实现在 LINUX_ANCHORING 与 DARWIN_ANCHORING 中清晰对照其余所有操作经由统一的anchoredChild收口为单个普通路径组件含对尾随斜杠会破坏O_NOFOLLOW的注释警示见 anchoredChild。5.4 --replace 与 Git-admin 备份 vault--replace只接受已存在的常规文件且专用于 Deepen不带它时意外覆盖会被拒绝。它额外要求同一会话read-planreceipt 中的精确规范化generated_plan_path与plan_digest且期望路径必须与写入目标完全相等——一份计划的相同字节不能授权另一份计划。Deepen 替换的时序是先对仍持有的旧计划 fd 做哈希拒绝任何摘要/inode/路径不匹配包括同 inode 编辑、读写之间的变更将当前目标无替换地原子移动到Git 管理目录Git-admin下随机命名的gitnexus-plan-backups/文件vault 打开逻辑见 openBackupVault并针对该持有 fd 验证被移动的 inode 与摘要只有以上全部通过才用同一原子 no-replace 原语发布新计划。任一边界重新出现的目标都会保持原样不动。每个新建计划/vault 目录都会先 fsync 自身、再 fsync 进其所在目录每次跨目录的保留性移动在报告成功或恢复路径前都会 fsync 源与目标两个目录。故障恢复语义一旦临时字节已存在失败发布或失败验证会把所有可得的 prior / displaced / unpublished / intended 计划先保留进该 Git-admin vault再报告失败。每个被报告的恢复对象都会从新解析的 Git 根重新打开并验证然后才在错误信息中以git-path:gitnexus-plan-backups/random-name命名。消费方必须用git rev-parse --git-path gitnexus-plan-backups/random-name解析该值绝不可将其解释为仓库相对工作树路径。这一保证在持有计划父目录被重命名后依然成立写入器也绝不经陈旧的词法父目录报告恢复绝不执行先身份检查再 unlink式的回滚那可能删除竞态者的替换文件。只读或不支持的 checkout 会产生阻塞性错误调用方不得绕过 helper、重定向到外部路径或削弱这些检查。六、规范字节Canonical bytes全局脏摘要怎么算global_dirty_digest.value是覆盖如下字节流的小写 SHA-256不带sha256:前缀。所有文本值取其精确 UTF-8 字节下文NUL指一个0x00字节前缀字段各随一个 NUL随后再一个额外 NULgitnexus-evidence-provenance、schema_version、2零或多条记录按规范化路径 UTF-8 字节的无符号字典序排序locale 与文件系统顺序一律禁止每条记录为record NUL随后固定顺序的field-name NUL field-value NUL 对序列末尾再一个额外 NUL。字段顺序恰为源码 RECORD_FIELDS 所声明的 12 个path、state、head_kind、index_kind、worktree_kind、untracked_kind、rename_from、rename_to、head_digest、index_digest、worktree_digest、untracked_digest字面量absent代表所有不可得的重命名端点、对象种类与层摘要——它绝不是空字符串。序列化实现在 serializeFields 与 serializeDirtyRecords后者额外做重复规范化路径拒绝。schema 的规范化字面量canonicalization literal精确为gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records固定字段数加上前缀/记录后的额外 NUL 使成帧无歧义——值内部不能含 NUL。这一 literal 作为global_dirty_digest.canonicalization随 JSON 输出。七、记录、重命名与状态Records, renames, and states原始脏集合由 Git porcelain v2 获取见 readDirtySnapshotgit status --porcelainv2 -z --untracked-filesall \ --find-renames50% --ignore-submodulesnone并且强制diff.renameLimit0与status.renameLimit0使仓库配置无法截断重命名候选。共享同一路径的原始 porcelain 事实会被合并为一条规范化记录。状态映射规则普通XY状态索引列与工作树列同时脏 →mixed删除 →deleted仅索引变更 →staged仅工作树变更 →unstaged。映射逻辑见 classifyXY?→untracked同一路径的多个不同事实 →mixed因此已暂存删除 重建文件仍保留 HEAD/index 事实而文件系统对象记入 untracked 层? child/是 Git 的内嵌目录标记规范化前去掉尾随斜杠child作为一个有界目录对象被实体化若实际并非目录则报错见 materializeRecord未合并unmerged阶段U或u记录直接拒绝先解决 index 再规范化引用路径位于脏集合之外时为clean仅存在于 Git 层之外时为untracked任何层都不存在时为absent。重命名是双端点一次重命名贡献两条事实——旧端点rename_fromabsent, rename_tonew新端点rename_fromold, rename_toabsent两者常态下状态均为renamed顺序由记录排序决定与新旧角色无关。工作树脏的重命名目标或同时带其他事实的端点为mixed并保留重命名元数据。任一端点被引用时引用清单会展开为同时包含两端见 snapshotEvidence 中引用集合的展开。八、对象与摘要规则Object and digest rules每个存在层的摘要均为sha256:小写hexHEAD 常规文件/符号链接精确 Git blob 字节的 SHA-256HEAD 目录精确原始 Git tree 字节的 SHA-256HEAD gitlinktree 存储的 ASCII 对象 ID 的 SHA-256Index 常规文件/符号链接stage-0 Git blob 字节的 SHA-256Index gitlink其 ASCII 对象 ID 的 SHA-256index 没有目录层任何非 stage-0 条目都被拒绝被跟踪的工作树常规文件不跟随符号链接打开的原始文件字节符号链接原始链接目标字节gitlink检出嵌套 HEAD 处的 ASCII 对象 ID——但必须先经rev-parse --show-toplevel证明该目录自身是嵌套仓库根、HEAD可在该处解析且 porcelain v2 报告无任何 staged/unstaged/untracked/ignored 嵌套变更脏、空、未初始化或父目录穿透的 gitlink fail-closed见 readOwnGitlinkHead目录下文 v1 目录流同时缺席于 HEAD 与 index 的路径把文件系统对象放入untracked层并将worktree标记 absentGit 托管的路径放入worktree并把untracked标记 absent缺失层对 kind 与 digest 均用字面量absent空文件是零字节的 SHA-256绝不与 absent 混为一谈。目录对象v1 目录流文件系统目录字节使用前缀字段gitnexus-evidence-directory、schema_version、1、同样的 NUL 成帧以及按无符号 UTF-8 相对路径字节排序的递归条目每条目固定字段为path、kind、digest。一次自底向上的文件系统遍历访问每个节点一次返回每个子摘要及为保留规范字节所需的扁平化子树链接从不被跟随。当目录被证明是精确的嵌套 Git top-level 时仅排除其管理性.git条目——其余每个子项含工作文件与嵌套目录都保留为证据。每个目录对象有界10,000 个访问条目、深度 256、256 MiB 常规文件内容超界 fail-closed且这些界独立作用于每条记录实体化的每个顶层目录对象。实现与常量见 digestDirectory 与 DIRECTORY_LIMITS。分层一致性HEAD 对象只从快照开始时捕获的完整对象 ID 读取符号HEAD名称绝不为各层重新解析index 层从一次捕获的 stage-0 清单解析helper 守护对应的 HEAD/ref/reflog 控制文件与原始 index 文件结束时比对捕获清单拒绝普通的 A→B→A 变更绝不接受混合时代的层。九、全程竞态防护变更守卫mutation guards快照期间的每一次读取都被守卫包裹任何观测到的竞态都会拒绝快照而不是输出混合时代证据常规文件通过O_NOFOLLOW描述符读取并做前/后身份校验见 hashFile符号链接使用 lstat/readlink/lstat目录在盘点前后记录身份helper 同时比较快照开始与结束时的原始 porcelain-v2 状态与 HEAD再复检文件系统守卫snapshotEvidence 的verifyGuards与终末比较见 gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs#L2175-L2228absent 引用路径会为最近的现存父目录持有 no-follow 描述符并记录第一个缺失组件/叶子该锚定缺席在最终 Git 状态传递前后都被检查使新建的 ignored 路径无法规避 porcelain。缺席锚定按仓库相对前缀去重并钉住描述符防止 inode 号复用实现见 recordAnchoredAbsence。十、落点验证helper 在仓库与评测体系中的使用gitnexus-plan生命周期Phase 4 末尾、组合计划前按规范重新计算evidence_provenance快照全局脏摘要 排序引用清单仅排除本次 generated-plan 路径Phase 5 以 stdin 通过write-plan发布Deepen 以read-plan→ 深度重验 →write-plan --replace重写同一规范化文件。规范细节见 gitnexus/skills/gitnexus-plan/SKILL.md 与 gitnexus/skills/gitnexus-plan/references/context-ledger.mdevidence_provenance是 ledger 中必填的不可变工作快照。gitnexus-work的双层漂移检查执行器即使在同一 HEAD 也总重新计算全局脏摘要与引用清单路径或摘要不匹配即触发保守 re-anchor重新读取已变更引用、评估新增未引用脏路径缺失或 schema-1 证据一律在 schema 2 下重锚。见 gitnexus/skills/gitnexus-work/SKILL.md 与其 README.md。评测沙箱eval/workflow_bench/proposer_sandbox.py 中实现了一个受信任、自我拥有的 Python 3 启动器专门用于调用evidence-provenance.mjs的原子移动器见其文件内 L447-L452 一带验证沙箱环境不信任 PATH 扫描到的任意可执行文件。这从评测侧佐证了 helper 作为唯一受信任写入边界的定位。十一、快速查阅索引关注点仓库路径规范正文本文主体来源gitnexus-claude-plugin/skills/gitnexus-plan/references/evidence-provenance.md规范的可执行定义gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjswork 技能字节一致副本gitnexus/skills/gitnexus-work/scripts/evidence-provenance.mjs规划技能规则与 Deepen 流程gitnexus/skills/gitnexus-plan/SKILL.md工作台账字段语义gitnexus/skills/gitnexus-plan/references/context-ledger.md小结GitNexus 把AI 生成的计划当做一个需要密码学强度溯源的决策工件来对待。evidence-provenanceschema 2 定义了可跨技能复现的字节级快照格式而配套 helper 用目录描述符锚定、原子link(2)no-replace 发布与 Git-admin 备份 vault把读取旧计划、生成快照、写入新计划收敛为三条纪律严明的命令。理解这套契约你就能在 GitNexus或其他采用该技能的仓库中安全地生成、交接并深化带完整证据链的实施计划而不会把计划可信度寄托在脆弱的词法路径与 shell 管道之上。【免费下载链接】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），仅供参考