GitNexus 工程计划技能实战基于知识图谱与语句级 PDG 的 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/GitNexus导读gitnexus-plan是 GitNexus 随 Claude Code 插件gitnexus-claude-plugin分发的工程规划技能其任务不是回答代码问题而是把一次代码变更加工成实现者无需重新调研即可动手的工程计划文档与机器可读上下文包。本文以该技能主文件 SKILL.md 为核心骨架完整拆解其 Phase 0–5 工作流、任务分类矩阵、新鲜度门控、PDG 切片方法与证据溯源契约并结合仓库内 5 份 references 参考文档与evidence-provenance.mjs脚本源码说明其底层原理。读完你将掌握 GitNexus 图谱导航、语句级 PDG 约束与定向源码验证三层协作的规划方法论以及如何用它输出可直接交给gitnexus-work执行的高质量计划。一、技能定位从会提问到可交付、可执行的规划层在 GitNexus 的技能生态中gitnexus-plan与 gitnexus-work、gitnexus-review、gitnexus-lfg一起构成规划 → 执行/加深 → 评审的闭环仓库根 AGENTS.md 的Engineering planning execution一节对这套管线有系统登记。其中gitnexus-plan只规划、永不实现。运行期间不得修改生产代码、测试或配置唯一允许写入仓库的文件是计划文档本身唯一允许的其它状态变更是通过analyze --index-only刷新.gitnexus索引存储它输出两类东西一份计划文档compact 或 full 两种形态外加计划内嵌的第 11 节——implementation context pack实现上下文包这是给后续实现代理gitnexus-work或任何执行器消费的机器可读契约使其无需重复调研。技能主文件 frontmatter 中给出的典型触发语句展示了其两种用法/gitnexus-plan Add retry support to the ingestion pipeline /gitnexus-plan deepen docs/plans/plan.md /gitnexus-plan impact_depth:3 depth:deep task description # knob 覆盖见 Configuration第二条是 Deepen 模式就地加深既有计划第三条说明任务文本前可以携带key:value形式的配置旋钮。三层信息架构导航、约束、验证技能将 GitNexus 的能力与代理自身能力组织为严格有序的三层这也是全文方法论的核心骨架GitNexus 图谱负责导航where to look通过query→context→impact/trace→最后手段cypher的调用阶梯回答看哪里、什么和什么相连——执行流、调用者/被调者、爆炸半径、相关测试。这一层的每次调用都必须回答一个有名字的规划问题禁止无目的的海量探索。语句级 PDG 负责约束what gates and feeds the behavior对变更所聚焦的少数函数用pdg_querycontrols/flows、impact {mode:pdg}、explain污点抽取有界切片回答哪些语句门控或喂给了目标行为。代理自身的定向源码读取负责验证what is actually true right now当前源码是权威图谱结论在验证前只是导航提示。图谱与源码冲突时信任源码、记录差异并建议重建索引。这套分层设计详见 README.md决定了 token 效率来自上下文账本每次查询与读取都记录它回答的问题除非源码确实变化、出现矛盾或命中账本允许的升级场景否则绝不重复拉取。二、硬性规则先有纪律后有深度技能开篇即给出 10 条硬性规则是理解后续所有阶段设计的钥匙Ledger first账本优先每次 GitNexus 调用、每次仓库文件读取前都必须检查上下文账本context-ledger.md禁止重复回答过同一问题的查询或重复读取未变化的区间。每个图谱查询回答一个有名字的规划问题把问题与结论记入账本不做探索式撒网。Source beats graph源码胜过图谱图谱负责导航当前源码才是权威断言前必须验证注释是最弱的证据。No fabrication禁止编造绝不虚构符号、文件名、测试名、工具结果或 PDG 边未知项一律放入Assumptions and Open Questions。No scope creep禁止蔓延任务未要求的相邻重构归入计划 §12作为显式推迟的后续项。Pin working-tree evidence钉住工作树证据而不只钉 HEAD每种计划形态都要携带版本化的全局 dirty digest 与排序的被引用路径清单且只能通过 evidence-provenance.mjs 生成禁止自行重算 digest。只通过 helper 写计划生成的计划路径必须规范化为仓库相对的docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-slug.md先在仓库外草稿完整合成文档再通过 stdin 管道给 helper 的write-plan命令绝不允许直接写目标文件或退化为外部输出路径。只通过 helper 读已有计划Deepen 必须调用read-plan解码其 descriptor 锚定的plan_bytes_base64把 receipt 里的规范generated_plan_path与plan_digest作为同一绑定保留。够了就停Stop when you have enough足够证据即终止探索计划不会随 token 消耗单调变好。附带约定账本中标记为discarded的符号与查询允许被忽略这正是防止本会话回头重走死胡同的机制见 context-ledger.md。三、Phase 0——任务解析与分类先定姿势再谈深度计划质量在很大程度上取决于开头 30 秒的正确分类。Phase 0 的第一步是读取账本参考文档并用任务打开账本记录原始请求、解释后的目标、验收标准三项。任务分类矩阵类别姿势表类别姿势深度 · 计划形态 · 工具调用预算 · 新鲜度Bug 修复局部窄1–2 个主符号impact_depth1 · compact · 约 15 · accept功能特性默认旋钮 · compact · 约 30 · accept重构 / 共享 API 变更必须做 impactimpact_depth3 · full · 约 45 · strict性能默认 性能 PDG 模式见 pdg-slice.md· full · 约 45 · strict安全默认 安全 PDG 模式 explain污点发现 · full · 约 45 · strict依赖升级 / 迁移impact 兼容性聚焦通常不需要 PDG · compact · 约 20 · accept并发 / 事务性控制流 状态变更 PDG 聚焦 · full · 约 45 · strict测试改进 / 文档最窄通常不做 impact 或 PDG 轮 · compact · 约 10 · accept架构变更 / spike最宽先看 clusters processes · full · 无上限 · strict该分类姿势覆盖Configuration 基线调用文本中的显式key:value旋钮又覆盖两者。一个任务命中多行时取最宽的深度、并集各专注领域。播种证据Seeded evidence当已有完成度足够高的调研成果时——例如一份已结束的 review、一份带path:line锚点和命名失败场景的分诊文档——账本直接从它打开把来源文档作为开篇账目引用直接据此规划而不在已覆盖的地面上重跑图谱阶梯。Phase 4 仍会对 Proposed Changes 引用的内容做源码验证钉在锁定提交上也就是说播种替代的是探索绝不替代验证。深度是用户的一次性决定在交互会话中若调用没有携带任何显式深度信号无depth:、form:、freshness:旋钮且非 Deepen 模式进入 Phase 1 前应阻塞性地问一次规划要多深Quick——depth:narrow form:compact freshness:accept1–2 个主符号、最少图谱工作、只写核心小节Standard—— 按上表分类姿势原样执行除非分类另有理由否则推荐Deep——depth:deep form:full freshness:strict写全 13 节、impact_depth3、读 clusters/processes、给中心函数做 PDG 切片。答案被设定得如同用户在调用中键入了这些旋钮显式旋钮优先并跳过提问。无头headless运行永不提问直接套用分类姿势。这个设计取代了完成后建议再加深的做法——Deepen 模式保留给后续会话、review 发现或执行器回灌等真正的加深场景。轮次经济Turn economy本身就是交付物计划质量以每 token 的决策质量来评判而非论证充分性表演。技能文档特别点名了一个被量化的反例GitNexus 仓库的 eval/workflow_bench/ 中曾出现为一行两行的改动花了 63 轮规划。当预算耗尽而问题仍未闭合时把它们记入 §12 而不是继续深挖——执行器反正还要做廉价重验证。四、Phase 1——锚定与新鲜度一切行号引用都要钉在锁定提交上解析目标仓库不确定时list_repos否则用覆盖工作目录的已索引仓库多仓库索引时每次调用都显式传repo。在账本中记录仓库当前HEAD commit——计划中每个行号引用都钉在它上面。解析并记录 analyzer runner本技能所有analyze命令都经它执行项目有 runner此前 analyze 把.gitnexus/run.cjs放在索引旁时用node .gitnexus/run.cjs analyze …否则用已安装 CLIgitnexus analyze …npm install -g gitnexus再否则npx gitnexus analyze …。记录其路径/版本与可用的源码/构建标识禁止用时间戳臆造来源。读取gitnexus://repo/{name}/context代码库总览 过期检查进入新鲜度门控compact 类目默认freshness: accept直接在现有图谱上规划、加权源码验证——这类计划的图谱引用本就稀少。仅当某个图谱声明变成承重墙如 Proposed Changes 依赖某个 d1 依赖列表时才中途升级刷新。full 类目默认freshness: strict其下先做analyzer 来源检查把解析出的 runner 身份与索引元数据以及在 analyzer 源码检出中与当前 analyzer 源码比对。身份过期或未知时不得产出输出也不得让图谱承重在index_refresh、计划头部和 §12 记录过期 analyzer 来源——source-weighted limitation改靠定向源码读取或转手给拥有构建当前门禁的gitnexus-work手工执行。索引过期 → 经解析 runner 执行analyze --index-only任务类别将进入 Phase 3 时追加--pdg且仅当 runner 来源已知为当前版本时才重读 context 资源。刷新有预算上限Phase 1 最多一次--index-only刷新外加 Phase 3 最多一次--pdg升级仅当 Phase 1 刷新未带--pdg每个规划会话如此一次 Deepen 是独立会话。analyze --index-only只写.gitnexus索引存储绝不触碰仓库文件。刷新失败/不可行无索引写权限、仓库过大或传入accept→ 在过期图谱上推进、更高地加权源码验证并在计划头部与 Assumptions 中声明过期与跳过的刷新资源不可读但工具可用 → 单靠工具推进新鲜度按未知处理。GitNexus 完全不可用 → 切换Fallback 模式见下文第九节。仅架构级任务额外读取gitnexus://repo/{name}/clusters与.../processes。五、Phase 2——图谱导航阶梯永远用能回答当前账本问题的最小操作调用顺序如下且全局有活跃预算账本中活跃主符号最多max_primary_symbols默认 5个、相关符号最多max_related_symbols默认 20个。query {search_query, task_context}—— 定位任务相关的概念、执行流、模块与测试context {name}—— 每个候选主符号的 360° 视图调用者、被调者、分类引用、进程据此提升为主符号或丢弃返回ambiguous时用kind/file_path/ uid 收窄重试一次这是被允许的重复impact {target, direction}—— 共享或高连通符号的上游/下游爆炸半径maxDepthimpact_depth枢纽符号先summaryOnly:true再下钻——同样是被允许的重复。记录 d1 项直接、深度为 1 的依赖者——计划必须逐一为它们负责trace {from, to}—— 当任务核心是A 如何到达 B时一次调用代替多次 context 跳转语句级 PDG —— 进入 Phase 3针对变更聚焦的函数cypher—— 最后手段仅用于上述工具无法表达的精确图谱问题先读gitnexus://repo/{name}/schema每个查询都要锚定并LIMITdetect_changes {scope}—— 仅当要规划的是既有未提交或分支工作。不要默认跑全所有工具一个局部测试修复可能在第二步就结束阶梯。这些图谱工具query、context、impact、trace、cypher、pdg_query、explain、detect_changes的落点在仓库源码 tools.ts 中实现pdg-slice.md 亦注明其工具均对照该文件验证。六、Phase 3——语句级 PDG 切片给 1–3 个核心函数建立有界证据对变更最核心的 1–3 个函数构建有界 PDG context slice目标是一份规划 LLM 能装进上下文的紧凑切片绝不是图谱倾倒。构建前先读 pdg-slice.md它独占定义工具调用、入选标准、深度界、切片 schema、安全/性能模式与无 PDG 层回退。PDG 工具速查表问题调用X 在什么条件下运行有什么门卫pdg_query {mode: controls, target}函数内变量 Y 流向哪里pdg_query {mode: flows, target, variable}第 N 行语句依赖什么 / 被什么依赖impact {mode: pdg, target, direction, line: N}源到汇的污点路径安全模式explain {target}解读切片时必须遵守的契约细节impact在所有模式下都要求direction含mode: pdg——upstream指什么依赖此语句downstream指它依赖什么省略会直接 schema 校验失败CDG 分支语义编码在结果的label字段中为T/F门卫的语义取决于其谓词if (!ok) return;走T绝不按固定 label 过滤门卫提前返回/抛错边带guard: truepdg_query是过程内且始终锚定的跨函数流转属于污点域explain或impact {mode:pdg}的过程间可达范围每个switch分支臂都是T没有--pdg层时工具返回no PDG layer提示而非报错——该提示是仓库级的探测一次即定不要逐函数重探。入选标准满足任意一条才进切片与任务直接匹配的语句、数据流前驱/后继限pdg_data_depth默认 2、控制依赖限pdg_control_depth默认 2、影响目标行为的状态变更、执行路径上的外部调用、错误处理/回退分支、被影响的返回值组成部分、解释测试断言所必需的语句。其余一律切除若每函数超过约 15 条语句收紧相关性而不是调大深度。切片在工作内存中保存、账本中压缩为一行pdg_slices条目、计划 §5 中蒸馏呈现。其中的behavioural_observations是已确认事实planning_implications是推断二者必须区分。安全模式与性能模式安全类目额外识别并记录不可信输入、校验点、净化点、认证/授权检查、特权边界、敏感数据、持久化操作、网络调用、危险 sink、绕过校验的错误路径。运行explain {target}取持久化的 source→sink 污点路径。注意没有污点发现不等于安全——闭包/回调流、属性/字段流与隐式流未被建模需在必要时明说。性能类目额外扫描循环、重复调用、阻塞操作、网络/数据库调用、分配密集路径、缓存边界、并发、扇出、重复数据转换并以推断形式陈述热路径含义没有 benchmark 证据就不得声称测得加速。七、Phase 4——定向源码验证图谱说看哪里源码说现在实际是什么用普通文件读取精确行区间非不得已不整文件确认图谱指出的位置读取计划将引用的每个源码区间签名、分支条件、状态变更、错误路径、会改变行为的邻近注释compact 计划引用更少——验证所引用的即可读取 GitNexus 关联到主符号的测试未定位到测试就绝不声称某测试存在验证计划将点名的构建/测试命令真实存在package.json scripts / CI workflows且优先采用自带前置依赖pre-hooks的脚本形式而非直接调用底层二进制检查会约束变更的仓库约定AGENTS.md、GUARDRAILS.md、lint/构建配置——只看变更触及的部分每个账本符号随手标记source_verified: true出现在 Proposed Changes 中的符号必须经过源码验证图谱与源码冲突时信任源码、把差异记入账本与计划、建议重建索引绝不让过期图谱数据冒充事实。源码验证的证据层级由强到弱为当前源码与配置 → 当前测试与可执行行为 → 编译/构建/lint 输出 → GitNexus 图谱与 PDG → 文档与注释。八、Phase 5——组合计划两种形态、四类声明标签、一条发布通道先读模板、按类目取形态组合前先读 plan-template.mdcompact 形态同样的证据头只保留承重小节但小节号必须保留以便gitnexus-work的 § 引用仍可解析。硬上限除 §11 包外 80 行超限而仍重要的一切压成 §12 的一行——compact 计划长到爆表是任务被错误分类的信号应重新分类为 full 而非溢写。full 形态写满全部 13 节——1. Objective、2. Current Behaviour、3. Relevant Architecture、4. GitNexus Findings、5. Statement-Level PDG Findings、6. Proposed Changes、7. Implementation Sequence、8. Test Strategy、9. Risk and Impact Analysis、10. Files Expected to Change、11. Reusable Implementation Context、12. Assumptions and Open Questions、13. Definition of Done。某节对该任务确实为空例如无 PDG 层索引时保留标题并一句话说明原因绝不悄悄删节。四类声明标签每一条承重声明都打证据类别标签[verified]在锁定提交上读过源码、[graph]GitNexus/PDG 输出未经源码确认、[inferred]有证据支撑的推理、[assumed]未验证——必须同时在 §12 出现。未打标签的散文是叙述不是证据。模板的组稿细则还包括§2/§5 引源码节选最多max_snippet_lines30行且只在节选承载论证时引用§4 每条发现都要点名来源工具调用工具 关键参数并在计划依赖该结果时附一行原文引用使工具声明事后可审计§7 步骤按依赖排序且各自独立可执行——执行器可在任一步骤停下而树仍自洽§8 必须点名真实定位到的测试文件新测试要有具体场景清单输入 → 动作 → 预期输出§9 必须为 impact 轮报告的每个直接depth-1依赖负责。Evidence provenance组合前必须重算的版本化快照组合前一刻必须严格按 evidence-provenance.md 调用 evidence-provenance.mjs 重算快照对所有脏路径不只被引用路径做版本化的global_dirty_digestSHA-256gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records规范化以及按规范化仓库相对路径排序的cited_path_manifest含每层对象种类与 HEAD/index/worktree/untracked 层 digest。只排除本次生成的计划路径本身docs/plans/其余内容不得排除。规划期间变化过的任何引用都要重读。核心命令形态从目标仓库根执行helper 属于当前激活技能目录# 快照为每个被引用路径传一个 --cited node gitnexus-claude-plugin/skills/gitnexus-plan/scripts/evidence-provenance.mjs snapshot \ --repo $PWD \ --schema-version 2 \ --generated-plan docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ --cited src/one.ts \ --cited test/one.test.ts只通过 helper 发布安全的计划写入通道# 写新计划完整 UTF-8 文档经 stdin 传入绝不直接写目标 node gitnexus-claude-plugin/skills/gitnexus-plan/scripts/evidence-provenance.mjs write-plan \ --repo $PWD \ --generated-plan docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ /path/to/outside-repo-scratch-plan.md发布受多重保护生成路径必须精确匹配docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-kebab-slug.md含有效日历日期3–5 词 slug写入用原子link(2)目标已存在则报EEXIST绝不覆盖拒绝符号链接目标快照排除、读取与写入共用同一个严格校验器。初始规划绝不传--replacesafe-write 失败即阻断发布报告之不得直接写、改投外部目标或弱化仓库相对来源契约。stdin 须为合法 UTF-8 且 ≤ 16 MiB。机器可读的实现上下文包§11按 context-pack.md 构建 §11它是后续代理消费的稳定契约compact 计划发 mini-pack仅含task_summary、evidence_provenance、files_to_modify、tests、verification_commands、pdg_constraints仅在确实跑过切片时、assumptions、open_questions、avoidfull 计划发全部字段在 mini-pack 基础上增加acceptance_criteria、primary_symbols、related_symbols、execution_path、architectural_patterns、risks等。包的稳定性契约字段名是gitnexus-work消费的接口可以自由增字段但不得改名或挪用既有字段assumptions与avoid是承重字段——执行器把前者当作依赖前要廉价复验的对象把后者当作硬约束。evidence_provenance字段同样承重其版本、全局 digest 与排序的引用清单让执行器能区分提交漂移与staged/unstaged/untracked/deleted/renamed/mixed/absent 工作树证据。缺失该字段或 schema 1 的旧包须保守地做 schema-2 重锚定不得当作干净树解释。九、Deepen 模式就地加深既有计划/gitnexus-plan deepen plan-path不是创建新计划而是在原地强化已有计划解析目标仓库与规范化的仓库相对计划候选再用read-plan装载read-plan是 Deepen 或执行装载已有计划的唯一受支持方式拒绝缺失、外部、越界、符号链接或作用域不符的路径只解码 receipt 中精确的plan_bytes_base64在整个 Deepen 会话中保留其规范generated_plan_path与plan_digest不变完整重跑 Phase 1analyzer 来源检查 新鲜度门控Deepen 是独立会话拥有自己的刷新预算先重新锚定再重钉重算全局 dirty digest 与引用清单并与旧 HEAD 钉比较。被改动/改名/删除/混合/新缺失的引用路径必须在钉与来源快照移动前重读区间或降级声明——只移动 commit 钉等于把脏的或过期的声明悄悄洗成 verified除非调用显式覆盖旋钮否则升级到depth: deepimpact_depth 3读 clusters/processes从计划 §11 包为账本播种然后复验每个[graph]/[inferred]声明定向补强为[verified]每个[assumed]被解决或带原因保留d1 直接依赖核算对刷新后的图谱复检有 PDG 层时为中央函数新建或扩展切片对账执行状态若gitnexus-work已为该计划落过提交执行中途回灌把 HEAD 上已存在的 §7 步骤标记为完成并重排剩余序列——重写后的计划必须能从开头执行且不重做已落地的步骤补强浅处测试场景、风险、完成定义并把声明标签升级贯穿全文通过write-plan --replace --expected-plan-path 保留的读路径 --expected-plan-digest 保留的读 digest重写同一个规范文件两个期望值必须来自同一次 read-plan receipt任何 digest/路径不匹配都阻断发布成功的 receipt 里prior_plan_backup_git_path指向被替换旧计划的、经 Git 验证的备份。对应的 Deepen 写入命令形态node gitnexus-claude-plugin/skills/gitnexus-plan/scripts/evidence-provenance.mjs write-plan \ --repo $PWD \ --generated-plan docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ --replace \ --expected-plan-path docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ --expected-plan-digest sha256:digest-from-read-plan \ /path/to/outside-repo-scratch-plan.md十、Configuration全部旋钮与默认值默认基线如下——Phase 0 的类别姿势覆盖它任务文本前的内联key:value旋钮覆盖两者该技能无 skill-config 文件机制调用参数即机制旋钮默认值含义depth视类别而定narrowimpact_depth1仅当明显只有一个中心函数时才做 PDGdefault 本表deepimpact_depth3 读 clusters/processesform视类别而定compact核心小节 mini-pack除 pack 外 ≤80 行——见 plan-template或full全部 13 节impact_depth2impact的maxDepthpdg_data_depth2PDG 切片中的数据依赖跳数pdg_control_depth2PDG 切片中的控制依赖跳数max_primary_symbols5账本预算活跃符号计数丢弃的不计max_related_symbols20账本预算活跃符号计数丢弃的不计max_snippet_lines30计划中引用的最长源码节选freshness视类别而定strictfull 类目 依赖图谱前先刷新过期索引及补齐缺失 PDG 层用analyze --index-only [--pdg]acceptcompact 类目 在现有图谱上规划源码加权并加标注仅当图谱声明承重时才刷新十一、Fallback 模式GitNexus 或 PDG 不可用时怎么办首先在聊天中和计划里明说用定向仓库探索grep/glob/reads近似调用者、依赖、执行流、状态变更与相关测试把每条此类发现标记为source-derived——绝不冒充图谱派生的结果也绝不编造语句级边当会实质性提升置信度时建议经解析 runnernode .gitnexus/run.cjs、已装gitnexus或npx gitnexus执行analyze --index-only需要 PDG 层时加--pdg。十二、账本与配套支持文件让方法与实现可追溯技能目录下五份 references 与一份脚本共同构成可追溯的实现基础主文件与文件总览见 README.md文件作用SKILL.md技能本体Phase 0–5、硬性规则、配置、回退pdg-slice.mdPDG 切片构造工具、入选标准、schema、安全/性能模式context-ledger.md账本 schema 反重复读取规则plan-template.md13 节计划文档模板context-pack.md实现上下文包 schema 稳定性契约evidence-provenance.md脏树证据的版本化字节契约evidence-provenance.mjs快照序列化器 descriptor 锚定的计划读/写器从脚本源码可见其实现严谨度该文件共 2366 行零 npm 依赖仅用 Node 内置crypto/fs/path/child_processschema 常量EVIDENCE_PROVENANCE_SCHEMA_VERSION 2规范化字面量gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records写入路径由GENERATED_PLAN_WRITE_PATTERN校验目录对象受 10,000 条记录、深度 256、256 MiB 内容字节三重限制超界即 fail-closed。账本 schema 速览context-ledger.md 给出账本的 YAML schema涵盖任务三元组原始请求/解释后目标/分类/验收标准、verified_at_commitPhase 1 记录一次的 HEAD、evidence_provenance快照、index_refresh每次analyze --index-only的命令与结果或跳过原因、established_facts、符号表每个带name/kind/file/relevance(primary|related|discarded)/source_verified、files_read精确区间 目的、gitnexus_queries工具参数 / 回答的规划问题 / 一行结论、pdg_slices、未决问题、假设、决策。其重读规则界定被允许的重复summaryOnly:true→ 对同一 impact 目标下钻ambiguous结果用 kind/file_path/uid 收窄重试一次同一工具换参数回答新规划问题。账本里塞满近似重复查询是失败信号——停下来用已有结论规划。十三、跨插件安装与执行端协作该技能在仓库内以多份副本分发以适配不同宿主Claude Code 经.claude/skills/gitnexus-plan/SKILL.md即本仓库的gitnexus-claude-plugin/skills/gitnexus-plan/Codex CLI 经用户级~/.agents/skills/任何 AGENTS.md-aware 代理可要求它读取该 SKILL.md 并遵循之。MCP 服务接线见同目录 mcp.jsongitnexusserver 由npx -y gitnexus1.6.9 mcp启动为技能提供知识图谱工具面。在整条管线里规划不是终点执行端 gitnexus-work 以计划 §11 的implementation_context包为主要机器可读输入其 prose 各节是依据它以每次符号编辑前跑 GitNexus impact 检查、按计划场景跑测试、每个提交前用detect_changes门禁的方式把计划落成一系列已验证的原子提交。两端共享字节一致的evidence-provenance.mjs因此规划者与执行者对同一证据树计算出的 hash 完全相同。十四、限制与优雅降级边界即诚实技能的可运行前提与边界README 的Requirements and graceful degradation与Limitations两节需要 GitNexus 索引语句级小节额外需要--pdg层pdg_query是过程内的跨函数流转来自explain污点或impact {mode:pdg}的过程间可达按类别定价的新鲜度是门禁而非装饰full 类目默认strict且只在 runner 来源已知为当前时刷新--index-only只触碰.gitnexus存储过期 analyzer 来源是如实披露的 source-weighted limitation——规划不会重建 analyzer 输出也不让该图谱承载承重声明刷新后 PDG 层仍不可用 → 计划如实说明并跳过语句级声明绝不手工伪造边完全没有 GitNexus → fallback 模式source-derived 标签 建议建索引计划读写强制平台契约需O_DIRECTORY与O_NOFOLLOWLinux 还需/proc/self/fd其它平台直接拒绝不派生解释器、不加载原生代码发布即link(2)原子且占位则失败。Linux 把每个名字都对着已持有的描述符解析中途换父目录不可能重定向操作macOS 无等价路径改为钉住整条目录链的打开描述符并在每一步前后重证——换来的是检测出现即中止而非预防发布还要求目标仓库可写且计划目录与 Git 管理备份目录在同一文件系统这些保证缺失时写入 fail-closed绝不把计划改道别处技能按契约只做规划唯一写入仓库的文件是计划文档唯一允许触碰的其它状态是.gitnexus索引新鲜度刷新。它不得构建 analyzerdist/产物不得改动源码、测试、配置、benchmark 或评测数据对技能指令的改进反馈只在聊天中给出不落进评测或技能文件。这套图谱导航、PDG 约束、源码验证三层分工配合账本驱动的反重复纪律与版本化证据溯源正是 GitNexus 想把工程计划从调研型聊天推向可移交、可审计、可执行的核心工程实践——规划者可以放心停手执行者可以放心开工。【免费下载链接】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 工程计划技能实战：基于知识图谱与语句级 PDG 的 gitnexus-plan 完整工作流
GitNexus 工程计划技能实战基于知识图谱与语句级 PDG 的 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/GitNexus导读gitnexus-plan是 GitNexus 随 Claude Code 插件gitnexus-claude-plugin分发的工程规划技能其任务不是回答代码问题而是把一次代码变更加工成实现者无需重新调研即可动手的工程计划文档与机器可读上下文包。本文以该技能主文件 SKILL.md 为核心骨架完整拆解其 Phase 0–5 工作流、任务分类矩阵、新鲜度门控、PDG 切片方法与证据溯源契约并结合仓库内 5 份 references 参考文档与evidence-provenance.mjs脚本源码说明其底层原理。读完你将掌握 GitNexus 图谱导航、语句级 PDG 约束与定向源码验证三层协作的规划方法论以及如何用它输出可直接交给gitnexus-work执行的高质量计划。一、技能定位从会提问到可交付、可执行的规划层在 GitNexus 的技能生态中gitnexus-plan与 gitnexus-work、gitnexus-review、gitnexus-lfg一起构成规划 → 执行/加深 → 评审的闭环仓库根 AGENTS.md 的Engineering planning execution一节对这套管线有系统登记。其中gitnexus-plan只规划、永不实现。运行期间不得修改生产代码、测试或配置唯一允许写入仓库的文件是计划文档本身唯一允许的其它状态变更是通过analyze --index-only刷新.gitnexus索引存储它输出两类东西一份计划文档compact 或 full 两种形态外加计划内嵌的第 11 节——implementation context pack实现上下文包这是给后续实现代理gitnexus-work或任何执行器消费的机器可读契约使其无需重复调研。技能主文件 frontmatter 中给出的典型触发语句展示了其两种用法/gitnexus-plan Add retry support to the ingestion pipeline /gitnexus-plan deepen docs/plans/plan.md /gitnexus-plan impact_depth:3 depth:deep task description # knob 覆盖见 Configuration第二条是 Deepen 模式就地加深既有计划第三条说明任务文本前可以携带key:value形式的配置旋钮。三层信息架构导航、约束、验证技能将 GitNexus 的能力与代理自身能力组织为严格有序的三层这也是全文方法论的核心骨架GitNexus 图谱负责导航where to look通过query→context→impact/trace→最后手段cypher的调用阶梯回答看哪里、什么和什么相连——执行流、调用者/被调者、爆炸半径、相关测试。这一层的每次调用都必须回答一个有名字的规划问题禁止无目的的海量探索。语句级 PDG 负责约束what gates and feeds the behavior对变更所聚焦的少数函数用pdg_querycontrols/flows、impact {mode:pdg}、explain污点抽取有界切片回答哪些语句门控或喂给了目标行为。代理自身的定向源码读取负责验证what is actually true right now当前源码是权威图谱结论在验证前只是导航提示。图谱与源码冲突时信任源码、记录差异并建议重建索引。这套分层设计详见 README.md决定了 token 效率来自上下文账本每次查询与读取都记录它回答的问题除非源码确实变化、出现矛盾或命中账本允许的升级场景否则绝不重复拉取。二、硬性规则先有纪律后有深度技能开篇即给出 10 条硬性规则是理解后续所有阶段设计的钥匙Ledger first账本优先每次 GitNexus 调用、每次仓库文件读取前都必须检查上下文账本context-ledger.md禁止重复回答过同一问题的查询或重复读取未变化的区间。每个图谱查询回答一个有名字的规划问题把问题与结论记入账本不做探索式撒网。Source beats graph源码胜过图谱图谱负责导航当前源码才是权威断言前必须验证注释是最弱的证据。No fabrication禁止编造绝不虚构符号、文件名、测试名、工具结果或 PDG 边未知项一律放入Assumptions and Open Questions。No scope creep禁止蔓延任务未要求的相邻重构归入计划 §12作为显式推迟的后续项。Pin working-tree evidence钉住工作树证据而不只钉 HEAD每种计划形态都要携带版本化的全局 dirty digest 与排序的被引用路径清单且只能通过 evidence-provenance.mjs 生成禁止自行重算 digest。只通过 helper 写计划生成的计划路径必须规范化为仓库相对的docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-slug.md先在仓库外草稿完整合成文档再通过 stdin 管道给 helper 的write-plan命令绝不允许直接写目标文件或退化为外部输出路径。只通过 helper 读已有计划Deepen 必须调用read-plan解码其 descriptor 锚定的plan_bytes_base64把 receipt 里的规范generated_plan_path与plan_digest作为同一绑定保留。够了就停Stop when you have enough足够证据即终止探索计划不会随 token 消耗单调变好。附带约定账本中标记为discarded的符号与查询允许被忽略这正是防止本会话回头重走死胡同的机制见 context-ledger.md。三、Phase 0——任务解析与分类先定姿势再谈深度计划质量在很大程度上取决于开头 30 秒的正确分类。Phase 0 的第一步是读取账本参考文档并用任务打开账本记录原始请求、解释后的目标、验收标准三项。任务分类矩阵类别姿势表类别姿势深度 · 计划形态 · 工具调用预算 · 新鲜度Bug 修复局部窄1–2 个主符号impact_depth1 · compact · 约 15 · accept功能特性默认旋钮 · compact · 约 30 · accept重构 / 共享 API 变更必须做 impactimpact_depth3 · full · 约 45 · strict性能默认 性能 PDG 模式见 pdg-slice.md· full · 约 45 · strict安全默认 安全 PDG 模式 explain污点发现 · full · 约 45 · strict依赖升级 / 迁移impact 兼容性聚焦通常不需要 PDG · compact · 约 20 · accept并发 / 事务性控制流 状态变更 PDG 聚焦 · full · 约 45 · strict测试改进 / 文档最窄通常不做 impact 或 PDG 轮 · compact · 约 10 · accept架构变更 / spike最宽先看 clusters processes · full · 无上限 · strict该分类姿势覆盖Configuration 基线调用文本中的显式key:value旋钮又覆盖两者。一个任务命中多行时取最宽的深度、并集各专注领域。播种证据Seeded evidence当已有完成度足够高的调研成果时——例如一份已结束的 review、一份带path:line锚点和命名失败场景的分诊文档——账本直接从它打开把来源文档作为开篇账目引用直接据此规划而不在已覆盖的地面上重跑图谱阶梯。Phase 4 仍会对 Proposed Changes 引用的内容做源码验证钉在锁定提交上也就是说播种替代的是探索绝不替代验证。深度是用户的一次性决定在交互会话中若调用没有携带任何显式深度信号无depth:、form:、freshness:旋钮且非 Deepen 模式进入 Phase 1 前应阻塞性地问一次规划要多深Quick——depth:narrow form:compact freshness:accept1–2 个主符号、最少图谱工作、只写核心小节Standard—— 按上表分类姿势原样执行除非分类另有理由否则推荐Deep——depth:deep form:full freshness:strict写全 13 节、impact_depth3、读 clusters/processes、给中心函数做 PDG 切片。答案被设定得如同用户在调用中键入了这些旋钮显式旋钮优先并跳过提问。无头headless运行永不提问直接套用分类姿势。这个设计取代了完成后建议再加深的做法——Deepen 模式保留给后续会话、review 发现或执行器回灌等真正的加深场景。轮次经济Turn economy本身就是交付物计划质量以每 token 的决策质量来评判而非论证充分性表演。技能文档特别点名了一个被量化的反例GitNexus 仓库的 eval/workflow_bench/ 中曾出现为一行两行的改动花了 63 轮规划。当预算耗尽而问题仍未闭合时把它们记入 §12 而不是继续深挖——执行器反正还要做廉价重验证。四、Phase 1——锚定与新鲜度一切行号引用都要钉在锁定提交上解析目标仓库不确定时list_repos否则用覆盖工作目录的已索引仓库多仓库索引时每次调用都显式传repo。在账本中记录仓库当前HEAD commit——计划中每个行号引用都钉在它上面。解析并记录 analyzer runner本技能所有analyze命令都经它执行项目有 runner此前 analyze 把.gitnexus/run.cjs放在索引旁时用node .gitnexus/run.cjs analyze …否则用已安装 CLIgitnexus analyze …npm install -g gitnexus再否则npx gitnexus analyze …。记录其路径/版本与可用的源码/构建标识禁止用时间戳臆造来源。读取gitnexus://repo/{name}/context代码库总览 过期检查进入新鲜度门控compact 类目默认freshness: accept直接在现有图谱上规划、加权源码验证——这类计划的图谱引用本就稀少。仅当某个图谱声明变成承重墙如 Proposed Changes 依赖某个 d1 依赖列表时才中途升级刷新。full 类目默认freshness: strict其下先做analyzer 来源检查把解析出的 runner 身份与索引元数据以及在 analyzer 源码检出中与当前 analyzer 源码比对。身份过期或未知时不得产出输出也不得让图谱承重在index_refresh、计划头部和 §12 记录过期 analyzer 来源——source-weighted limitation改靠定向源码读取或转手给拥有构建当前门禁的gitnexus-work手工执行。索引过期 → 经解析 runner 执行analyze --index-only任务类别将进入 Phase 3 时追加--pdg且仅当 runner 来源已知为当前版本时才重读 context 资源。刷新有预算上限Phase 1 最多一次--index-only刷新外加 Phase 3 最多一次--pdg升级仅当 Phase 1 刷新未带--pdg每个规划会话如此一次 Deepen 是独立会话。analyze --index-only只写.gitnexus索引存储绝不触碰仓库文件。刷新失败/不可行无索引写权限、仓库过大或传入accept→ 在过期图谱上推进、更高地加权源码验证并在计划头部与 Assumptions 中声明过期与跳过的刷新资源不可读但工具可用 → 单靠工具推进新鲜度按未知处理。GitNexus 完全不可用 → 切换Fallback 模式见下文第九节。仅架构级任务额外读取gitnexus://repo/{name}/clusters与.../processes。五、Phase 2——图谱导航阶梯永远用能回答当前账本问题的最小操作调用顺序如下且全局有活跃预算账本中活跃主符号最多max_primary_symbols默认 5个、相关符号最多max_related_symbols默认 20个。query {search_query, task_context}—— 定位任务相关的概念、执行流、模块与测试context {name}—— 每个候选主符号的 360° 视图调用者、被调者、分类引用、进程据此提升为主符号或丢弃返回ambiguous时用kind/file_path/ uid 收窄重试一次这是被允许的重复impact {target, direction}—— 共享或高连通符号的上游/下游爆炸半径maxDepthimpact_depth枢纽符号先summaryOnly:true再下钻——同样是被允许的重复。记录 d1 项直接、深度为 1 的依赖者——计划必须逐一为它们负责trace {from, to}—— 当任务核心是A 如何到达 B时一次调用代替多次 context 跳转语句级 PDG —— 进入 Phase 3针对变更聚焦的函数cypher—— 最后手段仅用于上述工具无法表达的精确图谱问题先读gitnexus://repo/{name}/schema每个查询都要锚定并LIMITdetect_changes {scope}—— 仅当要规划的是既有未提交或分支工作。不要默认跑全所有工具一个局部测试修复可能在第二步就结束阶梯。这些图谱工具query、context、impact、trace、cypher、pdg_query、explain、detect_changes的落点在仓库源码 tools.ts 中实现pdg-slice.md 亦注明其工具均对照该文件验证。六、Phase 3——语句级 PDG 切片给 1–3 个核心函数建立有界证据对变更最核心的 1–3 个函数构建有界 PDG context slice目标是一份规划 LLM 能装进上下文的紧凑切片绝不是图谱倾倒。构建前先读 pdg-slice.md它独占定义工具调用、入选标准、深度界、切片 schema、安全/性能模式与无 PDG 层回退。PDG 工具速查表问题调用X 在什么条件下运行有什么门卫pdg_query {mode: controls, target}函数内变量 Y 流向哪里pdg_query {mode: flows, target, variable}第 N 行语句依赖什么 / 被什么依赖impact {mode: pdg, target, direction, line: N}源到汇的污点路径安全模式explain {target}解读切片时必须遵守的契约细节impact在所有模式下都要求direction含mode: pdg——upstream指什么依赖此语句downstream指它依赖什么省略会直接 schema 校验失败CDG 分支语义编码在结果的label字段中为T/F门卫的语义取决于其谓词if (!ok) return;走T绝不按固定 label 过滤门卫提前返回/抛错边带guard: truepdg_query是过程内且始终锚定的跨函数流转属于污点域explain或impact {mode:pdg}的过程间可达范围每个switch分支臂都是T没有--pdg层时工具返回no PDG layer提示而非报错——该提示是仓库级的探测一次即定不要逐函数重探。入选标准满足任意一条才进切片与任务直接匹配的语句、数据流前驱/后继限pdg_data_depth默认 2、控制依赖限pdg_control_depth默认 2、影响目标行为的状态变更、执行路径上的外部调用、错误处理/回退分支、被影响的返回值组成部分、解释测试断言所必需的语句。其余一律切除若每函数超过约 15 条语句收紧相关性而不是调大深度。切片在工作内存中保存、账本中压缩为一行pdg_slices条目、计划 §5 中蒸馏呈现。其中的behavioural_observations是已确认事实planning_implications是推断二者必须区分。安全模式与性能模式安全类目额外识别并记录不可信输入、校验点、净化点、认证/授权检查、特权边界、敏感数据、持久化操作、网络调用、危险 sink、绕过校验的错误路径。运行explain {target}取持久化的 source→sink 污点路径。注意没有污点发现不等于安全——闭包/回调流、属性/字段流与隐式流未被建模需在必要时明说。性能类目额外扫描循环、重复调用、阻塞操作、网络/数据库调用、分配密集路径、缓存边界、并发、扇出、重复数据转换并以推断形式陈述热路径含义没有 benchmark 证据就不得声称测得加速。七、Phase 4——定向源码验证图谱说看哪里源码说现在实际是什么用普通文件读取精确行区间非不得已不整文件确认图谱指出的位置读取计划将引用的每个源码区间签名、分支条件、状态变更、错误路径、会改变行为的邻近注释compact 计划引用更少——验证所引用的即可读取 GitNexus 关联到主符号的测试未定位到测试就绝不声称某测试存在验证计划将点名的构建/测试命令真实存在package.json scripts / CI workflows且优先采用自带前置依赖pre-hooks的脚本形式而非直接调用底层二进制检查会约束变更的仓库约定AGENTS.md、GUARDRAILS.md、lint/构建配置——只看变更触及的部分每个账本符号随手标记source_verified: true出现在 Proposed Changes 中的符号必须经过源码验证图谱与源码冲突时信任源码、把差异记入账本与计划、建议重建索引绝不让过期图谱数据冒充事实。源码验证的证据层级由强到弱为当前源码与配置 → 当前测试与可执行行为 → 编译/构建/lint 输出 → GitNexus 图谱与 PDG → 文档与注释。八、Phase 5——组合计划两种形态、四类声明标签、一条发布通道先读模板、按类目取形态组合前先读 plan-template.mdcompact 形态同样的证据头只保留承重小节但小节号必须保留以便gitnexus-work的 § 引用仍可解析。硬上限除 §11 包外 80 行超限而仍重要的一切压成 §12 的一行——compact 计划长到爆表是任务被错误分类的信号应重新分类为 full 而非溢写。full 形态写满全部 13 节——1. Objective、2. Current Behaviour、3. Relevant Architecture、4. GitNexus Findings、5. Statement-Level PDG Findings、6. Proposed Changes、7. Implementation Sequence、8. Test Strategy、9. Risk and Impact Analysis、10. Files Expected to Change、11. Reusable Implementation Context、12. Assumptions and Open Questions、13. Definition of Done。某节对该任务确实为空例如无 PDG 层索引时保留标题并一句话说明原因绝不悄悄删节。四类声明标签每一条承重声明都打证据类别标签[verified]在锁定提交上读过源码、[graph]GitNexus/PDG 输出未经源码确认、[inferred]有证据支撑的推理、[assumed]未验证——必须同时在 §12 出现。未打标签的散文是叙述不是证据。模板的组稿细则还包括§2/§5 引源码节选最多max_snippet_lines30行且只在节选承载论证时引用§4 每条发现都要点名来源工具调用工具 关键参数并在计划依赖该结果时附一行原文引用使工具声明事后可审计§7 步骤按依赖排序且各自独立可执行——执行器可在任一步骤停下而树仍自洽§8 必须点名真实定位到的测试文件新测试要有具体场景清单输入 → 动作 → 预期输出§9 必须为 impact 轮报告的每个直接depth-1依赖负责。Evidence provenance组合前必须重算的版本化快照组合前一刻必须严格按 evidence-provenance.md 调用 evidence-provenance.mjs 重算快照对所有脏路径不只被引用路径做版本化的global_dirty_digestSHA-256gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records规范化以及按规范化仓库相对路径排序的cited_path_manifest含每层对象种类与 HEAD/index/worktree/untracked 层 digest。只排除本次生成的计划路径本身docs/plans/其余内容不得排除。规划期间变化过的任何引用都要重读。核心命令形态从目标仓库根执行helper 属于当前激活技能目录# 快照为每个被引用路径传一个 --cited node gitnexus-claude-plugin/skills/gitnexus-plan/scripts/evidence-provenance.mjs snapshot \ --repo $PWD \ --schema-version 2 \ --generated-plan docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ --cited src/one.ts \ --cited test/one.test.ts只通过 helper 发布安全的计划写入通道# 写新计划完整 UTF-8 文档经 stdin 传入绝不直接写目标 node gitnexus-claude-plugin/skills/gitnexus-plan/scripts/evidence-provenance.mjs write-plan \ --repo $PWD \ --generated-plan docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ /path/to/outside-repo-scratch-plan.md发布受多重保护生成路径必须精确匹配docs/plans/YYYY-MM-DD-gitnexus-plan-3-5-word-kebab-slug.md含有效日历日期3–5 词 slug写入用原子link(2)目标已存在则报EEXIST绝不覆盖拒绝符号链接目标快照排除、读取与写入共用同一个严格校验器。初始规划绝不传--replacesafe-write 失败即阻断发布报告之不得直接写、改投外部目标或弱化仓库相对来源契约。stdin 须为合法 UTF-8 且 ≤ 16 MiB。机器可读的实现上下文包§11按 context-pack.md 构建 §11它是后续代理消费的稳定契约compact 计划发 mini-pack仅含task_summary、evidence_provenance、files_to_modify、tests、verification_commands、pdg_constraints仅在确实跑过切片时、assumptions、open_questions、avoidfull 计划发全部字段在 mini-pack 基础上增加acceptance_criteria、primary_symbols、related_symbols、execution_path、architectural_patterns、risks等。包的稳定性契约字段名是gitnexus-work消费的接口可以自由增字段但不得改名或挪用既有字段assumptions与avoid是承重字段——执行器把前者当作依赖前要廉价复验的对象把后者当作硬约束。evidence_provenance字段同样承重其版本、全局 digest 与排序的引用清单让执行器能区分提交漂移与staged/unstaged/untracked/deleted/renamed/mixed/absent 工作树证据。缺失该字段或 schema 1 的旧包须保守地做 schema-2 重锚定不得当作干净树解释。九、Deepen 模式就地加深既有计划/gitnexus-plan deepen plan-path不是创建新计划而是在原地强化已有计划解析目标仓库与规范化的仓库相对计划候选再用read-plan装载read-plan是 Deepen 或执行装载已有计划的唯一受支持方式拒绝缺失、外部、越界、符号链接或作用域不符的路径只解码 receipt 中精确的plan_bytes_base64在整个 Deepen 会话中保留其规范generated_plan_path与plan_digest不变完整重跑 Phase 1analyzer 来源检查 新鲜度门控Deepen 是独立会话拥有自己的刷新预算先重新锚定再重钉重算全局 dirty digest 与引用清单并与旧 HEAD 钉比较。被改动/改名/删除/混合/新缺失的引用路径必须在钉与来源快照移动前重读区间或降级声明——只移动 commit 钉等于把脏的或过期的声明悄悄洗成 verified除非调用显式覆盖旋钮否则升级到depth: deepimpact_depth 3读 clusters/processes从计划 §11 包为账本播种然后复验每个[graph]/[inferred]声明定向补强为[verified]每个[assumed]被解决或带原因保留d1 直接依赖核算对刷新后的图谱复检有 PDG 层时为中央函数新建或扩展切片对账执行状态若gitnexus-work已为该计划落过提交执行中途回灌把 HEAD 上已存在的 §7 步骤标记为完成并重排剩余序列——重写后的计划必须能从开头执行且不重做已落地的步骤补强浅处测试场景、风险、完成定义并把声明标签升级贯穿全文通过write-plan --replace --expected-plan-path 保留的读路径 --expected-plan-digest 保留的读 digest重写同一个规范文件两个期望值必须来自同一次 read-plan receipt任何 digest/路径不匹配都阻断发布成功的 receipt 里prior_plan_backup_git_path指向被替换旧计划的、经 Git 验证的备份。对应的 Deepen 写入命令形态node gitnexus-claude-plugin/skills/gitnexus-plan/scripts/evidence-provenance.mjs write-plan \ --repo $PWD \ --generated-plan docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ --replace \ --expected-plan-path docs/plans/2026-09-08-gitnexus-plan-example-change-plan.md \ --expected-plan-digest sha256:digest-from-read-plan \ /path/to/outside-repo-scratch-plan.md十、Configuration全部旋钮与默认值默认基线如下——Phase 0 的类别姿势覆盖它任务文本前的内联key:value旋钮覆盖两者该技能无 skill-config 文件机制调用参数即机制旋钮默认值含义depth视类别而定narrowimpact_depth1仅当明显只有一个中心函数时才做 PDGdefault 本表deepimpact_depth3 读 clusters/processesform视类别而定compact核心小节 mini-pack除 pack 外 ≤80 行——见 plan-template或full全部 13 节impact_depth2impact的maxDepthpdg_data_depth2PDG 切片中的数据依赖跳数pdg_control_depth2PDG 切片中的控制依赖跳数max_primary_symbols5账本预算活跃符号计数丢弃的不计max_related_symbols20账本预算活跃符号计数丢弃的不计max_snippet_lines30计划中引用的最长源码节选freshness视类别而定strictfull 类目 依赖图谱前先刷新过期索引及补齐缺失 PDG 层用analyze --index-only [--pdg]acceptcompact 类目 在现有图谱上规划源码加权并加标注仅当图谱声明承重时才刷新十一、Fallback 模式GitNexus 或 PDG 不可用时怎么办首先在聊天中和计划里明说用定向仓库探索grep/glob/reads近似调用者、依赖、执行流、状态变更与相关测试把每条此类发现标记为source-derived——绝不冒充图谱派生的结果也绝不编造语句级边当会实质性提升置信度时建议经解析 runnernode .gitnexus/run.cjs、已装gitnexus或npx gitnexus执行analyze --index-only需要 PDG 层时加--pdg。十二、账本与配套支持文件让方法与实现可追溯技能目录下五份 references 与一份脚本共同构成可追溯的实现基础主文件与文件总览见 README.md文件作用SKILL.md技能本体Phase 0–5、硬性规则、配置、回退pdg-slice.mdPDG 切片构造工具、入选标准、schema、安全/性能模式context-ledger.md账本 schema 反重复读取规则plan-template.md13 节计划文档模板context-pack.md实现上下文包 schema 稳定性契约evidence-provenance.md脏树证据的版本化字节契约evidence-provenance.mjs快照序列化器 descriptor 锚定的计划读/写器从脚本源码可见其实现严谨度该文件共 2366 行零 npm 依赖仅用 Node 内置crypto/fs/path/child_processschema 常量EVIDENCE_PROVENANCE_SCHEMA_VERSION 2规范化字面量gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records写入路径由GENERATED_PLAN_WRITE_PATTERN校验目录对象受 10,000 条记录、深度 256、256 MiB 内容字节三重限制超界即 fail-closed。账本 schema 速览context-ledger.md 给出账本的 YAML schema涵盖任务三元组原始请求/解释后目标/分类/验收标准、verified_at_commitPhase 1 记录一次的 HEAD、evidence_provenance快照、index_refresh每次analyze --index-only的命令与结果或跳过原因、established_facts、符号表每个带name/kind/file/relevance(primary|related|discarded)/source_verified、files_read精确区间 目的、gitnexus_queries工具参数 / 回答的规划问题 / 一行结论、pdg_slices、未决问题、假设、决策。其重读规则界定被允许的重复summaryOnly:true→ 对同一 impact 目标下钻ambiguous结果用 kind/file_path/uid 收窄重试一次同一工具换参数回答新规划问题。账本里塞满近似重复查询是失败信号——停下来用已有结论规划。十三、跨插件安装与执行端协作该技能在仓库内以多份副本分发以适配不同宿主Claude Code 经.claude/skills/gitnexus-plan/SKILL.md即本仓库的gitnexus-claude-plugin/skills/gitnexus-plan/Codex CLI 经用户级~/.agents/skills/任何 AGENTS.md-aware 代理可要求它读取该 SKILL.md 并遵循之。MCP 服务接线见同目录 mcp.jsongitnexusserver 由npx -y gitnexus1.6.9 mcp启动为技能提供知识图谱工具面。在整条管线里规划不是终点执行端 gitnexus-work 以计划 §11 的implementation_context包为主要机器可读输入其 prose 各节是依据它以每次符号编辑前跑 GitNexus impact 检查、按计划场景跑测试、每个提交前用detect_changes门禁的方式把计划落成一系列已验证的原子提交。两端共享字节一致的evidence-provenance.mjs因此规划者与执行者对同一证据树计算出的 hash 完全相同。十四、限制与优雅降级边界即诚实技能的可运行前提与边界README 的Requirements and graceful degradation与Limitations两节需要 GitNexus 索引语句级小节额外需要--pdg层pdg_query是过程内的跨函数流转来自explain污点或impact {mode:pdg}的过程间可达按类别定价的新鲜度是门禁而非装饰full 类目默认strict且只在 runner 来源已知为当前时刷新--index-only只触碰.gitnexus存储过期 analyzer 来源是如实披露的 source-weighted limitation——规划不会重建 analyzer 输出也不让该图谱承载承重声明刷新后 PDG 层仍不可用 → 计划如实说明并跳过语句级声明绝不手工伪造边完全没有 GitNexus → fallback 模式source-derived 标签 建议建索引计划读写强制平台契约需O_DIRECTORY与O_NOFOLLOWLinux 还需/proc/self/fd其它平台直接拒绝不派生解释器、不加载原生代码发布即link(2)原子且占位则失败。Linux 把每个名字都对着已持有的描述符解析中途换父目录不可能重定向操作macOS 无等价路径改为钉住整条目录链的打开描述符并在每一步前后重证——换来的是检测出现即中止而非预防发布还要求目标仓库可写且计划目录与 Git 管理备份目录在同一文件系统这些保证缺失时写入 fail-closed绝不把计划改道别处技能按契约只做规划唯一写入仓库的文件是计划文档唯一允许触碰的其它状态是.gitnexus索引新鲜度刷新。它不得构建 analyzerdist/产物不得改动源码、测试、配置、benchmark 或评测数据对技能指令的改进反馈只在聊天中给出不落进评测或技能文件。这套图谱导航、PDG 约束、源码验证三层分工配合账本驱动的反重复纪律与版本化证据溯源正是 GitNexus 想把工程计划从调研型聊天推向可移交、可审计、可执行的核心工程实践——规划者可以放心停手执行者可以放心开工。【免费下载链接】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），仅供参考
