GitNexus gitnexus-plan 技能实战：以知识图谱 + 语句级 PDG + 源码核验生成可直接落地的工程计划

导读

gitnexus-plan 是 GitNexus 仓库内置的一项规划型 Agent 技能，其产物不是泛泛的设计文档，而是可以直接交给实现 Agent（如 gitnexus-work）开工、无需重复勘探仓库的 implementation-ready 工程计划：以 .gitnexus 知识图谱回答"往哪看"，以语句级程序依赖图（PDG）回答"什么在约束与喂养这段行为"，再以 Agent 自身的定向源码阅读回答"当下真实状态是什么"。读完本文，你将掌握该技能的调用方式、Phase 0–5 工作流、13 段计划模板、上下文台账（context ledger）、实现上下文包（context pack）与带版本化证据溯源的原子化安全写入机制，能够为 Bug 修复、重构、安全审计、性能优化等任务产出可被后续 Agent 直接消费的高信噪比计划。

---

一、技能定位：三层严格排序的人机协同勘探

技能的全量定义位于 gitnexus/skills/gitnexus-plan/SKILL.md，其核心思想是三层严格排序、各自回答一类问题：

1. GitNexus 导航层（导航性）——通过 query → context → impact/trace → cypher 的阶梯调用，让图谱回答 where to look / what is connected：执行流、调用者/被调用者、爆炸半径、关联测试。每一次调用都必须对应一个具名的规划问题，禁止漫无目的的探索式挖掘。
2. PDG 约束层（语句级）——通过 pdg_query（controls/flows）、impact {mode:"pdg", ...}（语句切片）与 explain（污点分析）回答 what gates and feeds the behavior：哪些守卫条件、数据依赖、状态变更在约束变更点所涉及的核心函数。结果被过滤为有界切片（见 references/pdg-slice.md），绝不整段倾倒。
3. Agent 核验层（事实性）——通过精确行区间的源码阅读确认"当前到底是什么"。当前源码是权威，图谱结果在核验前只算导航提示；二者冲突时信任源码、记录分歧、建议重建索引。

一句话概括其证据层级（强到弱）：当前源码与配置 → 当前测试与可执行行为 → 编译/构建/lint 输出 → GitNexus 图谱与 PDG → 文档与注释。注释是最弱的证据，永远不强于可执行代码。

二、调用方式与产物形态

技能在三种环境中均可调用，适配表见 README.md：

环境	调用方式	适配载体
Claude Code	/gitnexus-plan <task>	.claude/skills/gitnexus-plan/SKILL.md
Codex CLI	"run gitnexus-plan for "（读取根目录 AGENTS.md）	AGENTS.md § Engineering planning & execution
任何 AGENTS.md-aware Agent	让其读取 .claude/skills/gitnexus-plan/SKILL.md 并遵循执行	同上

典型调用示例（技能自文档即带）：

/gitnexus-plan Add retry support to the ingestion pipeline
/gitnexus-plan Fix the stale warm-cache invalidation bug in exportedTypeMap
/gitnexus-plan depth:deep impact_depth:3 Migrate the emit phase to streaming COPY

Codex 需要用户级安装：把技能目录复制到 ~/.agents/skills/（与其它 gitnexus-* 技能同一路径）即全会话可自动发现；若要显式 /gitnexus-plan 斜杠命令，可再创建 ~/.codex/prompts/gitnexus-plan.md。注意 SKILL.md 中明确声明：该技能只做规划、绝不实现——运行期间不得修改生产代码、测试或配置，唯一允许写入仓库的文件是计划文档本身，唯一允许触碰的其它状态是用于新鲜度刷新的 .gitnexus 索引。

产物形态：一份写入 docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5字kebab-slug>.md 的计划文档（13 节全量版或核心节压缩版，其第 11 节是机器可读的实现上下文包），外加聊天里的一句话摘要（目标、变更摘要、实施顺序、主要风险、开放问题与计划路径，不整篇粘贴到聊天）。

计划文档的两种形式（references/plan-template.md）

• Compact 压缩版：保留同样的证据头，只含承重章节，且保留 § 编号使 gitnexus-work 的章节引用可解析；不含 §11 包时硬上限 80 行。超出上限说明任务被误分类，应重分类为 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]（在固定 commit 上读过源码）、[graph]（GitNexus/PDG 输出、未经源码确认）、[inferred]（有证据支撑的推理）、[assumed]（未核验，必须同时出现在 §12）。§6 的变更只能点名台账中标记 source_verified: true 的符号。

三、五阶段工作流（Phase 0–5）

Phase 0 —— 解析与分类

先读台账并开盘：原始请求、解读后的目标、验收标准。再按任务类别决定姿态——类别姿态覆盖基线默认值，行内 key:value 旋钮再覆盖两者：

类别	姿态（深度 · 形式 · 工具预算 · 新鲜度）
Bug 修复（局部）	窄 · 1–2 个主符号 · impact_depth 1 · compact · ~15 · accept
功能特性	默认旋钮 · compact · ~30 · accept
重构 / 共享 API 变更	impact 强制、impact_depth 3 · full · ~45 · strict
性能	默认 + 性能 PDG 模式 · full · ~45 · strict
安全	默认 + 安全 PDG 模式 + explain 污点发现 · full · ~45 · strict
依赖升级 / 迁移	impact + 兼容性关注，PDG 少见 · compact · ~20 · accept
并发 / 事务	控制流 + 状态变更 PDG 侧重 · full · ~45 · strict
测试改进 / 文档	最窄：通常无 impact/PDG 趟 · compact · ~10 · accept
架构变更 / spike	最宽：先簇与进程 · full · 无上限 · strict

种子证据（Seeded evidence）：若已有完成的调查（评审结论、带 path:line 锚点与具名失败场景的分诊单），可直接以其开盘台账并据此规划，而不必重跑整个图谱阶梯。种子只替代勘探、永不替代核验——Phase 4 仍会在固定 commit 上核验 Proposed Changes 引用的内容。

深度是用户决定：交互会话中若无任何显式深度信号（无 depth:/form:/freshness: 旋钮、非 Deepen），在 Phase 1 前问一个阻塞性问题——Quick（depth:narrow form:compact freshness:accept）、Standard（类别姿态）、Deep（depth:deep form:full freshness:strict，全 13 节、impact_depth 3、读簇/进程、为核心函数做 PDG 切片）。Headless 运行不提问，直接按类别姿态。

Phase 1 —— 锚定与新鲜度

1. 解析目标仓库（list_repos），每张调用显式传 repo；
2. 台账记录当前 HEAD commit——计划中每一处行号引用都锚定到该 commit；
3. 解析并记录 analyzer 运行器：项目带 runner 用 node .gitnexus/run.cjs analyze …，否则已装 CLI 用 gitnexus analyze …（npm install -g gitnexus），再否则 npx gitnexus analyze …；
4. 读 gitnexus://repo/{name}/context 获得代码概览 + 陈旧度检查，随后执行新鲜度闸门（见下节）；仅架构级任务额外读 .../clusters 与 .../processes。

新鲜度闸门按类别定价：compact 类默认 freshness: accept（以源码核验加权、把图谱声明标为 load-bearing 时才刷新）；full 类默认 freshness: strict，且刷新前先做 analyzer provenance 检查——runner 身份与索引元数据不一致视为"stale analyzer provenance — source-weighted limitation"，记入 index_refresh、计划头与 §12，依靠定向源码阅读并把"构建当前版本"的闸门移交 gitnexus-work。刷新命令为 analyze --index-only（Phase 3 需要 PDG 层时追加 --pdg），每个规划会话最多一次 Phase 1 刷新 + 最多一次 Phase 3 的 --pdg 升级。--index-only 只写 .gitnexus 存储、绝不触碰仓库文件。

Phase 2 —— 图谱导航阶梯

使用能回答当前台账问题的最窄操作，按序：query（定位概念/执行流/相关测试）→ context（对候选主符号的 360° 视图，ambiguous 结果用 kind/file_path/uid 重试一次）→ impact（上下游爆炸半径，中心符号先 summaryOnly:true 再下钻；记录全部 d=1 直接依赖）→ trace（回答 A 如何到达 B）→ 语句级 PDG（Phase 3）→ cypher（兜底，先读 schema，每查询锚定并 LIMIT）→ detect_changes（仅对现有未提交/分支工作规划时）。主符号与相关符号在台账中分别受 5 / 20 的活跃预算约束。不是每个工具都要跑——局部测试修复可能在步骤 2 就结束。

Phase 3 —— 语句级 PDG 切片

对变更最核心的 1–3 个函数构建有界 PDG 上下文切片（详见下文第六节）。切片超额（每函数约 >15 条语句）时应收紧相关性而非提高深度。

Phase 4 —— 定向源码核验

• 读取计划将引用的每个源码区间：签名、分支条件、状态变更、错误路径、影响行为的注释；
• 读取图谱关联到主符号的测试，未定位到就不声称测试存在；
• 核验计划命名的构建/测试命令真实存在，优先用带前置（pre-hooks）的 npm/CI 脚本形式；
• 检查约束变更的仓库约定（AGENTS.md、GUARDRAILS.md、lint/build 配置）中与变更相关的部分；
• 随核验把台账符号标为 source_verified: true；构图谱/源码分歧时信任源码、记录分歧、建议重索引。

Phase 5 —— 组装计划

读模板、按类别形式填充（compact 或 full），打四类证据标签，开放问题路由到 §12；按 context-pack 规范构建第 11 节实现上下文包；随后把完整 UTF-8 文档通过 evidence-provenance.mjs write-plan 发布（见下文第八节），聊天中只给摘要。

四、上下文台账（Context Ledger）：让"重复调查"在纪律层面不可能

台账（schema 见 references/context-ledger.md）是技能的工作记忆，核心规则是每次 GitNexus 调用与每次仓库读取前先查台账。结构字段包括 task（原请求/目标/验收标准）、verified_at_commit、evidence_provenance、index_refresh、established_facts、symbols（每个带 source_verified 标志与 primary/related/discarded 相关性）、files_read（含精确行区间）、gitnexus_queries（含回答的规划问题与一行结论）、pdg_slices、unresolved_questions、assumptions、decisions。

防重读规则（Reread rules）：不重复查询/读取，除非(a)上次结果不足以回答当前问题、(b)已知源码变化、(c)核验暴露图谱与源码矛盾。允许的重试是刻意的升级而非违规：summaryOnly:true → 同一 target 全量下钻；ambiguous 结果用 kind/file_path/uid 收窄重试一次；同一工具改参数回答新问题（如同一函数 pdg_query 先 controls 再 flows）。无关符号/查询保留在台账中标记 discarded 并附一行原因——这正是避免后续死胡同重走的机制。

台账还强制符号预算（默认 5 主 / 20 相关，仅统计活跃项，丢弃项免费）与工作树证据钉扎（不仅钉 HEAD）：计划的每种形态都携带版本化的全局脏摘要与排序引文清单。

五、新鲜度、降级与回退模式

技能的健壮性边界（见 README.md § Requirements and graceful degradation）可以归纳为一句话：每个档位都诚实标注证据来源，绝不伪造图谱或语句级边。

• 需要 GitNexus 索引；语句级章节额外需要 --pdg 层。
• PDG 层刷新后仍不可用 → 计划如实说明并跳过语句级声明（绝不从源码手搓伪边）。
• 完全没有 GitNexus → 进入 Fallback mode：用定向 grep/glob/读取近似调用者与依赖，每一条发现标记为 source-derived，并向用户建议 analyze --index-only [--pdg]。
• 读取或发布计划要求宿主机提供 O_DIRECTORY + O_NOFOLLOW（Linux 还要求 /proc/self/fd），其它平台一律拒绝；写入依赖一个可写的目标仓库，以及计划与 Git 管理保险柜共享文件系统；这些保证不可用时写入者 fail closed，绝不把计划重定向到别处。

六、PDG 上下文切片：把语句级证据压缩成 LLM 装得下的形态

references/pdg-slice.md 给出了工具对照表，对应 MCP 层实现可回溯到 gitnexus/src/mcp/tools.ts 中声明的 impact/pdg_query/explain：

规划问题	调用
X 在什么条件下运行？守卫是什么？	pdg_query {mode: "controls", target}
函数内变量 Y 流向哪里？	pdg_query {mode: "flows", target, variable}
第 N 行语句依赖什么 / 什么依赖第 N 行？	impact {mode: "pdg", target, direction, line: N}
源码到汇点（sink）的污点路径（安全模式）	explain {target}

几则影响解读方式的契约细节：impact 所有模式都强制 direction（upstream = 什么依赖该语句，downstream = 它依赖什么，缺省会过不了 schema 校验）；CDG 分支语义存于结果的 label 字段为 'T'/'F'，且守卫语义取决于其谓词（if (!ok) return; 走 'T'），永远不要按固定标签过滤守卫，早退/抛错边携带 guard: true；pdg_query 是过程内且始终锚定的，跨函数流属 taint 或 impact {mode:"pdg"} 的跨过程领域；每个 switch 分支臂都标 'T'。

无 --pdg 层时工具返回的是"no PDG layer"提示而非错误，且该提示是仓库级的——探测一次即可定性，不要逐函数重探。freshness: strict 下先跑 analyze --index-only --pdg（即 Phase 1 预算允许的唯一 --pdg 升级）再重探；失败/不可行或 accept 时，在台账记录 "PDG unavailable"、跳过切片、在计划 §5 说明并推荐命令。

包含准则：一条语句只有在满足下列至少一项时才进入切片——直接匹配任务；相关语句的数据流前驱/后继（pdg_data_depth 默认 2 内）；相关语句的控制依赖（pdg_control_depth 默认 2 内）；影响目标行为的状态变更；执行路径上的外部调用；错误处理/回退分支；受影响返回值的一部分；解释某条测试断言所必需。其余一律裁掉，每函数超过约 15 条语句就收紧相关性而非提高深度。

切片表示以 YAML 呈现，字段如 pdg_context.entry_symbol、relevant_statements[].{type, code, relevance, defines, uses, control_dependencies, data_dependencies}、execution_flow、critical_dependencies、behavioural_observations（确认事实）与 planning_implications（推断，二者必须区分开）。安全模式额外要求识别不可信输入、校验/净化点、认证授权边界、敏感数据、危险汇点等，并跑 explain 收集持久化 TAINTED/TAINT_PATH 跳路径；无污点发现不等于安全（闭包/回调流、属性/字段流、隐式流未被建模，守卫式净化器可能漏报）。性能模式则额外扫描循环、重复调用、阻塞/网络/数据库操作、分配密集路径、缓存边界与扇出，热点推论必须标为推断——没有基准证据就不许声称测量到的提升。

七、实现上下文包：执行 Agent 无需重勘探的机器契约

references/context-pack.md 定义计划第 11 节的机器可读契约，让后续实现 Agent（gitnexus-work 或任何执行器）在不重复调查的前提下开工。Compact 计划只发迷你包：task_summary、evidence_provenance、files_to_modify、tests、verification_commands、pdg_constraints（仅当确实跑了切片）、assumptions、open_questions、avoid；Full 计划则输出全部字段，字段语义两者一致，evidence_provenance 两种形态都强制携带。gitnexus-work 把缺席的可选字段当作空值而非错误。

包内 implementation_context.evidence_provenance 字段是规范 schema：schema_version: 2、head_commit（完整 SHA）、generated_plan_path（归一化仓库相对路径，且精确排除出全局脏摘要）、global_dirty_digest（sha256，canonicalization 字面量为 gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records）、cited_path_manifest（按归一化路径排序，每项含各层 object_kind、state、rename_from/to、HEAD/index/worktree/untracked 的 SHA-256 摘要）。不得包含：完整文件、仓库级原始脏路径清单（只存其规范全局摘要）、未过滤的 PDG 转储、重复代码摘录（用 file:line 引用而非重引）与伪装的推测细节。

稳定性契约：字段名是 gitnexus-work 消费的接口，可自由加字段但不得改名或挪作他用。assumptions 与 avoid 是承重的——执行器把 assumptions 视为"需廉价重验后可信"、把 avoid 视为硬约束。generated_plan_path 永远归一化、相对目标仓库且限定 docs/plans/ 下的生成计划文件名形态；schema 2 没有外部输出表示，执行器必须用 helper 的 read-plan 命令加载计划并要求该字段与回执中的规范路径逐字节相等。schema 1 属遗留并被刻意拒绝，执行器须保守地按 schema 2 重锚定。

八、证据溯源序列化器与安全计划写入：字节级确定性

references/evidence-provenance.md 是 evidence_provenance schema 2 的规范字节契约，其可执行定义即同目录 scripts/evidence-provenance.mjs（共 2366 行，自述"gitnexus-plan 与 gitnexus-work 各携带逐字节一致的一份副本"，因此 planner 与 executor 哈希出相同字节）。该 helper 还是生成的计划的唯一受支持读取器与写入器——绝不用临时 shell 管道重建摘要，绝不直接写计划目标路径。

从目标仓库根运行（<skill-dir> 即本技能目录）：

# 1) 读取既有计划（Deepen 或执行的唯一受支持加载方式）
node gitnexus/skills/gitnexus-plan/scripts/evidence-provenance.mjs read-plan \
  --repo "$PWD" \
  --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md

# 2) 生成证据快照（每个被引路径传一个 --cited）
node gitnexus/skills/gitnexus-plan/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 计划（初始规划绝不传 --replace）
node gitnexus/skills/gitnexus-plan/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

实现要点：read-plan 发出 JSON 回执，含规范 generated_plan_path、bytes_read、精确的 plan_bytes_base64 与 plan_digest（sha256:<hex>）——解码并只消费这些精确字节，不重开词法路径；某个路径的回执永远不授权另一路径，即便字节相同。写入端有严格路径校验：只接受 docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5字kebab-slug>.md（含合法日历日期，helper 内 GENERATED_PLAN_WRITE_PATTERN 正则即此形状），拒绝 .git、源码、配置或任意仓库文件；read 端为兼容历史计划放宽为 docs/plans/*gitnexus-plan*.md 但保留同样的描述符锚定包含检查。

安全写入的底层机制（源码中有专门注释与实现段，值得读懂安全性质）：不 spawn 解释器、不加载原生代码，发布用 link(2)——原子、目标名已存在时报 EEXIST、拒绝跟随符号链接，等价于 renameat2(RENAME_NOREPLACE)/renameatx_np(RENAME_EXCL) 的 no-replace 语义。流程上先在持有的最终父描述符相对位置创建随机独占临时文件，写后 flush、绑定临时名到已开 inode、发布前哈希；发布前重新校验父目录与临时路径的 inode/size/digest，发布后再以 O_NOFOLLOW 打开提交路径做二次描述符锚定校验。检测到任何变异即中止，绝不接受混合时代的输出。

Linux 锚定 vs macOS 校验是一条值得明说的平台差异：Linux 上每个名字经 /proc/self/fd/<fd>/<child> 这条 magic link 解析，内核基于描述符已持有的 inode 解析、其上层的名字永不被重走——父目录在检查与使用之间被换名也无法重定向操作，竞争在结构上不可能；macOS 无此路径（Node 不暴露 openat/dir_fd/FFI），Darwin 后端对每个组件做 O_NOFOLLOW 词法解析并全程持有链上每个目录的开放描述符、每步前后证明链仍精确命名所持 inode——这买到的是检测而非预防（窗口内换父会被紧随其后的检查抓住并中止、什么都没写）。两端共同保证：任何平台都不让未经验证的字节流出。

--replace 仅 Deepen 专用且只接受既有常规文件，还必须传同一会话 read-plan 回执中的精确规范路径与摘要；预期路径必须与写目标完全相等，杜绝"字节相同的另一计划授权本计划"。替换前对仍持有的旧计划 fd 做哈希并拒绝任何 digest/inode/path 失配，然后以同一原子 no-replace 原语把当前目标移动到 Git 管理目录下随机命名的 gitnexus-plan-backups/ 文件（用 git rev-parse --git-path gitnexus-plan-backups/<random-name> 解析，绝不当作工作树相对路径），只有成功后才发布新计划。

九、配置旋钮总表

SKILL.md § Configuration 明确了基线默认值——类别姿态覆盖基线、行内 key:value 再覆盖（仓库没有技能配置文件机制，调用参数本身就是配置机制）：

旋钮	默认	含义
depth	按类别	narrow = impact_depth 1、仅当单函数明显核心时做 PDG；default = 本表；deep = impact_depth 3 + 读 clusters/processes
form	按类别	compact（核心节 + 迷你包，不含包 ≤80 行）或 full（全 13 节）
impact_depth	2	impact 的 maxDepth
pdg_data_depth	2	PDG 切片中数据依赖跳数
pdg_control_depth	2	PDG 切片中控制依赖跳数
max_primary_symbols	5	台账预算（活跃符号；丢弃不计数）
max_related_symbols	20	台账预算（活跃符号；丢弃不计数）
max_snippet_lines	30	计划中引用的最长源码摘录行数
freshness	按类别	strict（full 类）= 用 analyze --index-only [--pdg] 刷新陈旧索引后再依赖图谱；accept（compact 类）= 在当前图谱上规划、以源码加权并标注，仅当图谱声明变得承重时才刷新

同一任务命中多行类别时取并集姿态：取最宽的深度、合并关注面。

十、Deepen 模式：就地加强既有计划

/gitnexus-plan deepen <plan-path> 不新建计划而是就地强化既有计划（README 与 SKILL.md 均定义了完整契约），流程要点：

1. 解析目标仓库与归一化的候选路径，只能经 read-plan --repo <root> --generated-plan <candidate> 加载，拒绝缺失/越界/逃逸/符号链接/作用域不符的路径；只解码并解析回执中的 plan_bytes_base64，整个 Deepen 会话保持回执的规范 generated_plan_path 与 plan_digest 不变；
2. 完整重跑 Phase 1（analyzer provenance 检查 + 新鲜度闸门，Deepen 自带刷新预算、独立成会话）；
3. 先重锚定再重钉：重算计划全局脏摘要与引文清单、比对新旧 HEAD 钉——变更/重命名/删除/混合/新消失的被引路径须先重读或降级其声明，只挪 commit 钉会悄悄把脏或过时声明洗成"已核验"；
4. 除非显式旋钮覆盖，升级到 depth: deep（impact_depth 3、读 clusters/processes）；
5. 从计划 §11 包播种台账并重验：每个 [graph]/[inferred] 声明定向推进到 [verified]；每个 [assumed] 被解决或保留原因；对照刷新后的图谱复查 d=1 直接依赖账目；PDG 层在场时为核心函数建/扩切片；
6. 对账执行状态：若 gitnexus-work 已落地该计划的部分 commit（中途回程），把 §7 中已在 HEAD 的步骤标为完成并重排剩余序列，保证重写后的计划无需重做已落地步骤即可从头执行；
7. 强化薄弱环节（测试场景、风险、DoD），将声明标签升级贯穿全文；
8. 通过 write-plan --replace --expected-plan-path <...> --expected-plan-digest <...> 重写同一规范文件（两值必须出自同一 read-plan 回执，任何失配即阻断发布），保留成功回执的 prior_plan_backup_git_path 并在聊天中汇总差异（升级/核验失败的声明、变更章节、备份路径）。

十一、基线工作流与已知局限

技能文档明确列出的限制（如实引用，避免读者踩坑）：

• pdg_query 是过程内的；跨函数流来自 explain（污点）或 impact {mode:"pdg"} 的跨过程可达。
• 按契约该技能只做规划：唯一写入的仓库文件是计划文档，唯一可触碰的其它状态是用于新鲜度刷新的 .gitnexus 索引；不得构建 analyzer dist/ 输出，不得改动源码、测试、配置、基准或评测文件，指令反馈仅限聊天内（不得在规划任务期间改动本技能自身）。
• 该技能不维护运行器/分析器版本构建，陈旧 analyzer provenance 只会被披露为 source-weighted 局限而不会被规划运行修复。
• 产出物的可执行性由"工具预算 + 停止准则"保证：技能把 turn economy 当作交付物——计划以每 token 的决策质量论成败而非"充分性表演"（仓库自测中提到一份两行改动跑了 63 轮的失败案例），预算耗尽仍未决的问题进 §12 留给执行器廉价重验。gitnexus-work 的运行时环境与计划消费语义见 gitnexus/skills/gitnexus-work（SKILL.md 及 references 中的计划执行/路由约定），评测框架侧的工作流与演进逻辑见 eval/workflow_bench。

结语

gitnexus-plan 的价值不在于让 LLM"看更多代码"，而在于用三件事把勘探压缩到决策质量所需的最小值：知识图谱回答连通性、PDG 回答语句级因果、源码核验回答当下事实——再通过上下文台账杜绝重复查询、通过实现上下文包把结论以字节确定性的证据溯源（全局脏摘要 + 排序引文清单）无损耗地移交给执行 Agent。若你正在为自己仓库构建"规划→实施"的 Agent 流水线，本技能在 gitnexus/skills/gitnexus-plan/ 下的整套文件（SKILL、五份 references、一个 2366 行的序列化 helper）本身就是一个高完成度的可移植参考实现；直接以 /gitnexus-plan <task> 调用即为最快上手路径。