GitNexus 技能深度解析gitnexus-work 如何把 gitnexus-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/GitNexusGitNexus 在.claude/skills/gitnexus-work/目录下提供了一套名为gitnexus-work的 Agent 技能规范它是规划技能gitnexus-plan的执行侧对偶executor counterpart读取计划文档第 11 节的implementation_context上下文包以GitNexus 纪律——每次符号编辑前先做impact、每次提交前先做detect_changes、按计划场景补测试、提交前做两层漂移检查——把计划逐步落地为一串已验证的原子提交verified atomic commits。阅读本文后你将掌握该技能的调用与安装方式、它与计划文档之间的证据契约、图新鲜度门禁Build-current/index-current、四阶段执行流程以及底层evidence-provenance.mjs工具链的设计原理。本文的骨架文档是 .claude/skills/gitnexus-work/README.md并以其完整执行规范 .claude/skills/gitnexus-work/SKILL.md 与字节契约文档 .claude/skills/gitnexus-work/references/evidence-provenance.md 作为深度来源。一、技能定位一份会写代码的施工规范gitnexus-plan是纯规划技能产出 13 节的工程计划文档而gitnexus-work是会修改代码的执行技能。它的核心约定是输入是计划文档的第 11 节implementation_context机器可读的上下文包章节正文prose只作为理由说明每个符号symbol编辑之前必须运行 GitNexus 的impact上游分析确认改动半径每次提交之前必须运行detect_changes门禁只允许预期内的符号与流被改动测试必须来自计划tests[]场景input → action → expected outcome两层漂移检查会在提交与脏工作区证据真正被依赖前重新锚定re-anchorHEAD 与工作区状态。在仓库的角色划分中见 AGENTS.md 的 Engineering planning execution 一节/gitnexus-plan、/gitnexus-work、/gitnexus-review、/gitnexus-lfg构成完整的规划 → 执行 → 评审闭环其中 gitnexus-work 承担唯一会改动源代码的执行环节。在 AGENTS.md 的变更日志中可以看到该技能于 2026-07-11 的 1.10.0 版本加入随后随 npm 包、Claude Code 插件与gitnexus setup一并分发gitnexus/test/unit/shipped-skills-sync.test.ts 专门守护这些副本的同步一致性。二、调用方式与安装README 中给出的调用入口如下表CLI如何调用Claude Code/gitnexus-work [plan path]留空则使用当前仓库最新的docs/plans/*gitnexus-plan*.mdCodex CLI直接说 run gitnexus-work on Codex 会读取AGENTS.md或按下方用户级安装技能Codex 用户级安装cp -r .claude/skills/gitnexus-work ~/.agents/skills/gitnexus-work如果需要显式的斜杠命令可创建~/.codex/prompts/gitnexus-work.md--- description: Execute a gitnexus-plan as verified atomic commits (impact-checked, detect_changes-gated) argument-hint: plan path, or blank for the newest plan --- Use the gitnexus-work skill for: $ARGUMENTS Read ~/.agents/skills/gitnexus-work/SKILL.md (prefer the repo copy at .claude/skills/gitnexus-work/SKILL.md when present) and follow its phases in order. This skill edits code; honor its impact-before-edit and detect_changes-before-commit rules without exception.三种调用形式来自 SKILL.md 的输入分诊.claude/skills/gitnexus-work/SKILL.md 规定输入分为三类计划路径或留空 → 当前仓库根下最新的docs/plans/*gitnexus-plan*.md正常模式进入 Phase 1。Schema-2 计划带有规范化仓库相对路径generated_plan_path裸任务文本仅当任务琐碎且有界1–2 个文件、无架构决策时可直接以同样纪律实现impact先行、最小改动、行为变化必须补测试、验证命令取自仓库自身脚本package.json / CI、提交前detect_changes、图相关分析与最终验证前跑 Build-current/index-current任务更大则应建议先走/gitnexus-plan若最新计划的 §7 每一步都已在 HEAD 上完成pre-completed check应停下询问用户而不是重复执行。三、与 gitnexus-plan 的契约只读最权威的字节gitnexus-work 与规划技能之间的契约可以浓缩为几句话计划绝不因执行而被改写The plan is never mutated一切偏差都记录在提交信息与最终报告中。具体体现为只通过字节契约加载计划gitnexus-work 只用与gitnexus-plan逐字节相同byte-identical的辅助脚本scripts/evidence-provenance.mjs的read-plan命令加载计划消费收据receipt中的精确 base64 字节绝不直接重开词法路径evidence_provenance是强制字段compact 与 full 计划都必须携带。即使当前 HEAD 与计划钉住pin的 HEAD 一致执行器仍要重新计算全局脏摘要global dirty digest与按路径排序的引用清单sorted cited-path manifestgenerated_plan_path强校验schema-2 计划中该字段必须是规范化的仓库相对路径docs/plans/date-gitnexus-plan-slug.md外部、越界或作用域不同的取值非法且必须与read-plan收据给出的 canonical 路径逐字节相等缺失或 schema-1 的证据按 schema 2 保守重新锚定legacy不等于干净树被引用路径变更后会重读新增的未被引用脏路径要接受作用域评估不可读的证据会阻塞依赖它的工作Deepen深化模式只保留给漂移使作用域、需求、关键技术决策KTD或计划接缝失效的情形。§11 上下文包的字段骨架.claude/skills/gitnexus-plan/references/context-pack.md 给出第 11 节的规范 YAML 骨架gitnexus-work 逐字段消费implementation_context: task_summary: acceptance_criteria: [] evidence_provenance: schema_version: 2 head_commit: # 引用证据所钉住的完整 commit SHA generated_plan_path: # docs/plans/date-gitnexus-plan-slug.md global_dirty_digest: algorithm: sha256 canonicalization: gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records value: # 只放摘要不内嵌整份脏路径清单 cited_path_manifest: # 按规范化仓库相对路径排序 - path: object_kind: { head: , index: , worktree: , untracked: } state: clean | staged | unstaged | untracked | deleted | renamed | mixed | absent rename_from: null rename_to: null head_digest: sha256:hex | absent index_digest: sha256:hex | absent worktree_digest: sha256:hex | absent untracked_digest: sha256:hex | absent primary_symbols: [] # symbol / file / lines / role related_symbols: [] # CALLS / IMPORTS / EXTENDS / test-of ... execution_path: [] pdg_constraints: [] # 由 PDG 切片而来无 PDG 层则空并注明 architectural_patterns: [] # pattern example_location usage_guidance files_to_modify: [] # file symbols intended_change tests: [] # file scenarios(input→action→outcome) verification_commands: [] # 必须是确实存在且可运行的真实命令 risks: [] assumptions: [] # 每项都写明 WHAT to check / HOW open_questions: [] avoid: []关键语义也是稳定性契约compact 计划只发 mini-packtask_summary、evidence_provenance、files_to_modify、tests、verification_commands、仅当切片真的跑过才有的pdg_constraints、assumptions、open_questions、avoidfull 计划发全部字段两者语义一致evidence_provenance都强制存在。执行器把assumptions当作要廉价复核的事实把avoid当作硬约束。真实计划样本仓库中存放着一份完整的 schema-2 计划可作为对照阅读docs/plans/2026-08-04-gitnexus-plan-python-dotted-namespace-receiver.md。其头部明示Evidence provenance schema 2; global dirty digest 0912a3ee…; cited-path manifest 13 sorted entries; exact generated plan path excluded.——这正是 gitnexus-work 在 Phase 1 要逐项校验的证据头。计划第 2 节对每一段代码分析都标注了[verified]源码级验证或[graph]图查询证据这正是gitnexus-work编辑前引用重读、未引用脏路径评估所依赖的引用精度。四、两层漂移检查即使 HEAD 没动也要重算README 强调契约中最容易被轻视的一点是即使当前 HEAD 就是计划钉住的 HEAD也必须执行两层漂移检查第一层commit drift重新计算规范的全局脏摘要global_dirty_digest第二层working-tree drift重新计算排序后的引用路径清单cited_path_manifest且必须带上对象类型 HEAD/index/worktree/untracked 各层的摘要并将证据分类为staged、unstaged、untracked、deleted、renamed、mixed、absent。在 .claude/skills/gitnexus-work/references/evidence-provenance.md 中定义了规范字节流全局脏摘要 value 是对固定字节流前缀字段与记录的 NUL 分帧 UTF-8 字节路径按无符号字典序排序做的小写 SHA-256absent是字面量而非空字符串。Renames 用rename_from/rename_to双端点记录?是untracked同时命中多种状态的路径归并为mixed。重新锚定re-anchor规则对引用清单中每一项做 diff无论 staged-only、unstaged-only、deleted、双端 rename、mixed stagedunstaged 还是消失的 untracked 路径其被引用的行范围都要在依赖前重读拿当前全树脏集合与钉住的全局摘要对比新增的未引用脏路径要做作用域评估判断是否与计划、需求、测试或关键技术决策重叠——不能因为没被引用就默默忽略不可读或无法分类的引用证据会阻塞所有依赖步骤直到恢复、读到或用它与用户确认。禁止伪造摘要也禁止把缺失当作空文件重新锚定的结果保存在会话状态中计划正文绝不改动。若对账使作用域、需求、KTD 或计划接缝失效才调用 Deepen普通的字节漂移在本地重新验证即可。Phase 1 还有几道廉价校验逐条复核assumptions失败即该步骤 stop-and-replan 的信号留意open_questions若某一步被它卡住且答案会实质改变工作应在该步之前问用户而非之后做pre-completed check分支上若已有该计划的提交——如部分运行或 Deepen 回环——先确认哪些 §7 步骤已在 HEAD 落地落地者跳过并报告为 pre-completed执行从第一个未落地步骤继续。五、图新鲜度门禁Build-current / index-current 过程这是 gitnexus-work 唯一拥有的图新鲜度过程fail-closed每个依赖图的impact查询之前必须跑一次最终图验证之前必须再跑一次。它绝不在陈旧 runnerstale runner上回退执行。过程要点来自 .claude/skills/gitnexus-work/SKILL.md 第 2 阶段捕获 HEAD 与工作区来源读取gitnexus://repo/name/context用其类型化的index.commit与index.runner_identity收据绝不从 prose、时间戳或路径单独推断 analyzer 身份。当前收据必须是schemaVersion: 4其依赖运行时规范化名恰为gitnexus-analyzer-dependency-runtime-v4依赖运行时摘要覆盖已解析的包元数据与完整可加载的包载荷JavaScript、JSON、native、Wasm、parser 产物schema 1/2/3 均视为 legacy/stale。关系影响的已提交与未提交编辑会使新鲜度失效包括 staged、unstaged、untracked、deleted、renamed 的 analyzer/source/config 改动。即使 HEAD 未移动步骤间的这类编辑也要求在下次图查询前做 inter-step 刷新。陈旧则用已验证的包脚本构建当前本地源码本仓库为cd gitnexus npm run build对应 gitnexus/package.json 中build: node scripts/build.js产物 bin 指向dist/cli/index.js随后用该精确产物的status --json抓当前收据。源码/构建时间戳只是保守的触发信号不是产物是最新的证据。用该精确产物从目标仓库根运行带 PDG 层的索引本仓库为node gitnexus/dist/cli/index.js analyze --index-only --pdg持久化收据缺失/损坏/版本不同/不相等时加--force以免 already-up-to-date 快速路径留下 legacy/stale 来源。通常的node .gitnexus/run.cjs analyze仅在能证明其 runner 身份解析到同一刚构建产物时才可用禁止回退到旧项目 runner、全局安装或包下载。刷新后复核重读 index context、重跑status --json证明index.commit等于当前 HEAD、MCPindex.incomplete_reasons为空、持久化runner_identity与 status 的index.runnerIdentity语义一致runnerIdentityStatus: current、incompleteReasons为空、顶层status: up-to-date。invokedArtifact是诊断性入口被刻意排除在语义比较之外。任何构建/刷新/元数据读取/身份验证失败都阻塞图相关的 impact 与完成报告失败命令与证据绝不基于旧图继续。六、执行实现序列Phase 3六道工序一步一提交对计划 §7 的每一步按序执行如下六道工序编辑前先做新鲜 impact紧接在每次依赖图的impact {target, direction: upstream}查询前先跑 Build-current/index-current 过程然后对每一个直接d1依赖者负责。HIGH 或 CRITICAL 风险必须先带着爆炸半径呈报用户这是 AGENTS.md 中 GitNexus 规则的仓库级强制要求详见其 Always Do 一节impact不可被 grep 替代risk: UNKNOWN视为未解决而非低风险。遵守约束pdg_constraints声明了改动必须保持的次序与依赖事实avoid是硬性禁止architectural_patterns指明要镜像的形状先读示例位置再创造。最小化实现以完成该步所需的最小改动、遵循周边代码约定。按计划场景测试每个tests[]场景input → action → expected outcome在指定文件中变成真实测试行为需要时可补充计划遗漏的覆盖绝不删除或削弱断言来让步骤通过。当失败模式微妙时先在修复前的树上跑一次新回归测试并观察其失败先写测试再写修复或 stash 修复——两边都通过的测试什么都没钉住。验证运行步骤相关的verification_commands按原样使用它们自带构建前置。凡改动涉及构建产物执行路径worker 入口、dist 分发的 CLI、打包资源每次验证前先重新构建——对着过期产物通过或失败都是噪音修复不生效多半是修复根本没被加载。原子提交每次提交前跑detect_changes {scope: staged}确认只有预期符号与流受影响仓库强制然后按约定一个步骤一个 conventional commit。stage →detect_changes→ commit 必须作为从仓库根开始的不间断序列因为中间穿插其他工作正是门禁被跳过的途径。结果带partial图查询失败或truncated符号列表被截断都会同样阻塞提交——门禁没看全所有改动符号就应重跑而非当作干净。任何关系影响的实现编辑或提交都会使先前的过程证明失效下一步必须在 impact 查询前做 inter-step 刷新最后一次编辑后、最终验证前再刷一次。步骤彼此独立可行动每一步提交后树都是自洽的。若某步暴露计划有误停止该步、在 HEAD 上重新验证受影响断言然后要么就地小范围适配在提交信息与最终总结里记录偏差要么路由回gitnexus-plan的 Deepen 模式结构性遗漏——选项不明显时用一句话问用户。七、收尾Phase 4对照 DoD验证最终图谱即使每一步都单独通过最后也要整体跑一遍完整verification_commands逐条对照计划 §13Definition of Done与上下文包的acceptance_criteria——未满足项要么现在完成、要么明确报告为 unmet绝不静默丢弃验证最终知识图谱最后一次编辑后即使没有提交、HEAD 仍等于原始 pin再跑一遍 Build-current/index-current然后以该 proven-current 索引运行detect_changes {scope: all}或仓库等价的最终图检查对每一个意外符号或流负责过程失败即阻塞完成报告完成的步骤、产出的提交、相对计划的偏差含原因、复核失败的 assumptions、DoD 状态、最终索引 commit 与 runner 身份、任何延后事项。测试失败要连输出一起报告不粉饰。八、红线Never与技能反馈回路SKILL.md 明确列出不可逾越的红线跳过 Phase 3 门禁没有impact不做符号编辑没有detect_changes不提交扩大计划范围§12 延后的 follow-ups 保持延后改写计划正文Phase 2 原样提交该文件不算改写、削弱失败的测试、把未验证的工作说成已验证。反馈回路方面仅限 GitNexus 仓库本身若本次运行暴露了技能自身说明的摩擦点指引错误/缺失、工具预算浪费、阶段误路由且仓库带有eval/workflow_bench/则向eval/workflow_bench/learnings.jsonl追加一行 JSON{skill: gitnexus-work, date: ..., task: ..., friction: ..., suggestion: ...}但绝不在现场任务中直接修改技能文件本身——改进必须走离线候选回路参见 eval/workflow_bench/README.md 的 prompt/skill 演化循环候选需在配对基准上胜过在位者才由人工合入。九、底层支撑evidence-provenance.mjs 的读写安全设计gitnexus-work 与 gitnexus-plan 各自携带逐字节相同的 scripts/evidence-provenance.mjs其规范文档是 references/evidence-provenance.md。它同时是唯一受支持的现有计划读取器与安全计划写入器且是生成计划的唯一写边界——禁止用临时 shell 管道重算摘要或直接写计划目标路径。三个子命令均从目标仓库根运行# 1) 读计划唯一受支持的加载方式输出含 canonical path / bytes_read / # plan_bytes_base64 / plan_digest(sha256:hex) 的 JSON 收据 node skill-dir/scripts/evidence-provenance.mjs read-plan \ --repo $PWD \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md # 2) 生成证据快照每个被引用路径传一个 --cited输出完整 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 # 3) 写入计划发布精确 UTF-8 字节Deepen 模式追加 --replace 及期望路径/摘要 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其安全设计的几个关键点失败一律 fail-closed描述符锚定读safe readLinux 上通过/proc/self/fdO_DIRECTORYO_NOFOLLOWmacOS 上用O_DIRECTORY/O_NOFOLLOW不满足平台即整体拒绝——未验证的读不是降级读而是另一种竞态操作。最多读 16 MiB要求合法 UTF-8返回前还要证明父链与词法叶子仍指向同一持有对象描述符锚定写safe write发布用link(2)——原子、目标名被占时返回EEXIST、不跟随符号链接等价于renameat2(RENAME_NOREPLACE)/renameatx_np(RENAME_EXCL)且对每个支持平台都可通过fs.linkSync获得。写入者是随机独占临时文件 持有 no-follow 描述符 发布前复核 inode/size/digest--replace只对 Deepen 开放且必须匹配同一会话read-plan收据的 canonical 路径与摘要Linux 锚定 / macOS 验证的差异被如实写明Linux 上所有名字都经/proc/self/fd/fd/child魔链按已持有 inode 解析竞态不可能发生而非被检测到macOS 没有等价路径/dev/fd只是 devfs 节点因此改用持描述符钉 inode 每步前后重证链身份的方式换来的是检测而非预防——两平台都没有任何已发布字节能逃过验证路径契约一切 Git/CLI 路径必须是合法 UTF-8、已 NFC 规范化、非空 POSIX 仓库相对路径拒绝 NUL、反斜杠、绝对/盘符路径、空组件、./..组件。快照排除只做一条精确规范化路径的比较禁止 glob、目录或docs/plans/级通配排除恢复路径失败发布后保留的旧/被替换/未发布/目标计划存放在 Git-admin 目录的gitnexus-plan-backups/必须以git rev-parse --git-path gitnexus-plan-backups/random-name解析绝不能当作工作树相对路径解读。十、给执行者的实践清单把本文浓缩为可直接照做的检查单加载计划只走read-plan消费收据 base64 字节校验generated_plan_path与收据 canonical 路径逐字节相等同 HEAD 也要重算全局脏摘要与排序引用清单缺失/legacyschema-1证据一律保守按 schema-2 重锚每次图相关impact前、最终验证前跑 Build-current/index-current陈旧即cd gitnexus npm run build后用产物跑analyze --index-only --pdg必要时--force绝不回退陈旧 runner编辑前impact上游、覆盖每个 d1 依赖者HIGH/CRITICAL 先上报用户编辑后从仓库根不间断地执行 stage →detect_changes {scope: staged}→ 原子提交测试来自计划场景且必须能区分修复前后改动跑构建产物前先重建收尾整体跑验证套件、逐条核对 §13 DoD 与acceptance_criteria、刷新后做detect_changes {scope: all}终验并在报告中交代偏差与未满足项。通过这一整套规划时留痕、执行时验签、提交时过门禁的机制gitnexus-work 让 Agent 编写代码的过程从凭直觉改动升级为围绕可复现证据的受控工程执行——这正是 GitNexus 知识图谱能力在 Agent 工作流中的典型落地形态。【免费下载链接】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），仅供参考