GitNexus Engineering Plan 模板完全指南：Compact 与 Full 双形态 13 段工程方案的撰写规范

2026-09-08 22:18:32作者：劳婵绚Shirley

GitNexus: 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 负责把一次代码变更任务转化为"可以直接交给实现代理开工、且无需重复调研"的工程方案文档，而方案正文必须遵循一个统一模板——plan-template.md。本文以该模板为核心，逐层拆解其双形态结构（compact / full）、§1–§13 段落的写作义务、四类证据标签（claim tagging）的用法，以及撰写阶段必须遵守的组合与安全发布规则，并结合 gitnexus-plan/SKILL.md、evidence-provenance.md、context-pack.md 与配套脚本 scripts/evidence-provenance.mjs 给出源码级佐证。读完后，你将能按规范写出结构与证据纪律都合格的 GitNexus Engineering Plan。

模板在 GitNexus 规划流水线中的定位

plan-template.md 是 gitnexus-plan 技能 Phase 5「Compose the plan」的第一步引用对象（SKILL.md Phase 5 step 1 明确要求先读模板再按分类填充）。整条流水线由三个严格分层的环节组成：

GitNexus 导航——用图查询回答"看哪里、谁连谁"；
PDG 约束——用语句级程序依赖图回答"什么在门控、什么在喂数据"；
代理源文件核验——用精确行范围的源码读取确认"当前事实"。

plan-template.md 正是把这三个环节的产出压缩成一份结构化文档的规范：正文之外，第 11 节是一个机器可读的 implementation context pack，供后续实现代理（gitnexus-work 或任意执行器）直接消费，无需重复调研。

模板的核心思想用文档开头的三句话可以概括（见 plan-template.md）：

存在两种形态：compact（紧凑） 用于窄范围/默认任务，full（完整） 用于深度工作；
形态选择由 Phase 0 的任务分类决定，form 调用旋钮（knob）可显式覆盖；
无论哪种形态，正文中所有仓库产物一律使用 repo 相对路径。

证据头：每份计划文档的"身份证"

两种形态共享同一个证据头（evidence header），写在标题下方，由三行引用块组成，模板原文（plan-template.md）：

# GitNexus Engineering Plan

> Task: <one line>
> Evidence verified at commit <HEAD sha>; GitNexus index <fresh | refreshed this session (--index-only [--pdg]) | N commits behind, refresh skipped: <reason> | not used>.
> Evidence provenance schema 2; global dirty digest <sha256>; cited-path manifest <count> sorted entries; exact generated plan path excluded.

逐字段拆解其语义：

字段	含义
`Task`	一行任务描述，全文的唯一锚点
`Evidence verified at commit`	全部行号引用钉死到的 HEAD 提交；这是计划"引用可复核"的基线
`GitNexus index <...>`	索引新鲜度状态，取值仅限四种：`fresh`（新鲜）、`refreshed this session (--index-only [--pdg])`（本会话刷新）、`N commits behind, refresh skipped: <reason>`（落后 N 个提交且已跳过刷新并说明原因）、`not used`（未使用图）。这个枚举与 SKILL.md 中按任务分类定价的 freshness 门控（strict/accept）一一对应
`Evidence provenance schema 2`	证据溯源结构版本，schema 1 是刻意拒绝的 legacy，必须保守地以 schema 2 重新锚定
`global dirty digest <sha256>`	覆盖工作区全部脏路径的规范化全局摘要，算法为小写 SHA-256，规范化格式为 `gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records`（见 evidence-provenance.md）
`cited-path manifest <count> sorted entries`	按规范化 repo 相对路径排序的被引用路径清单条目数
`exact generated plan path excluded`	生成出来的计划文档路径本身被从全局摘要中精确排除，避免"写完计划使自己证据失效"

从源码结构看，摘要必须调用唯一受支持的序列化器生成（见下文），严禁在正文或 shell 里徒手重建——这正是 SKILL.md 硬规则中 "Pin working-tree evidence, not only HEAD" 与 "Write the plan only through the helper" 两条规则的落地。

Compact form：为窄任务准备的"只留承重墙"版本

compact 形态的定位是"narrow/default 工作"——本地 bug 修复、测试改进、文档类任务等。它的取舍哲学在模板中写得很直接：保留同样的证据头，但只写承重（load-bearing）段落（plan-template.md）。

它有一个极易被忽略但至关重要的约束：标题中必须保留 § 编号，使得 gitnexus-work 对 § 的引用能够解析——例如执行器在 Phase 3 按 plan §7 step by step 推进、在收尾时按 plan §13 与 acceptance_criteria 校验（见 gitnexus-work/SKILL.md）。如果去掉编号，计划章节与实际执行环节的对应关系就会断裂。

compact 模板的骨架如下：

# GitNexus Engineering Plan

> Task: <one line>
> Evidence verified at commit <sha>; GitNexus index <...>.
> Evidence provenance schema 3; global dirty digest <sha256>; cited-path manifest <count> sorted entries; exact generated plan path excluded.

## Objective (§1)

## Current Behaviour (§2–3) — ≤10 lines, architecture folded in

## Findings (§4–5) — only load-bearing, each tagged + tool-named

## Proposed Changes (§6)

## Implementation Sequence (§7) — risks inline as step notes

## Test Strategy (§8)

## Implementation Context (§11) — the mini-pack (see context-pack.md)

## Assumptions and Open Questions (§12)

## Definition of Done (§13)

注意它与 full 的差异：

§2 与 §3 合并（当前行为一节收在 ≤10 行内，把架构折叠进去）；
§4 与 §5 合并（只保留承重发现，且每条必须带证据标签和来源工具名）；
删去了 §9 Risk、§10 Files Expected to Change（风险以"步注"形式内联在 §7 中）；
§11 退化为 mini-pack（详见后文）。

compact 还有一个硬性上限：除 §11 包之外，正文不得超过 80 行。任何被裁掉但仍然重要的内容，只能进 §12 变成一行——绝不靠注水散文把计划撑大。模板特别指出：一份 compact 计划如果超过 80 行上限，本身就是"任务被错误分类"的信号——此时应该把任务重新分类为 full，而不是任其溢出。这条规则把"行数"变成了分类质量的探针。

Full form：覆盖全部 13 节的深潜模板

full 形态用于 refactor、security、performance、concurrency、architecture 等深度任务。其纪律是：每个小节都要填；如果某节对本任务确实为空（例如没有建立 PDG 层），保留标题并用一行说明原因——绝不静默删除（plan-template.md）。

完整模板如下（plan-template.md）：

# GitNexus Engineering Plan

> Task: <one line>
> Evidence verified at commit <HEAD sha>; GitNexus index <...>.
> Evidence provenance schema 2; global dirty digest <sha256>; cited-path manifest <count> sorted entries; exact generated plan path excluded.

## 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

1. Objective

对期望产出结果的简洁描述，是评审与执行双方对齐的唯一共识。

2. Current Behaviour

描述当前实现与执行路径，并纳入最相关的符号、文件与语句级观察。它的素材来自 Phase 4 的定向源码阅读，而不是图结果的转述。

3. Relevant Architecture

解释涉及的模块、边界、依赖与既有模式——让实现代理在动手前就理解"代码生长在什么土壤里"。

4. GitNexus Findings

汇总图的发现：primary symbols、callers 与 callees、impact radius（影响半径）、相关实现、相关测试、重要的跨模块关系。模板的组合规则要求该节每条发现都点名它来自哪次工具调用（tool + 关键参数），并在计划依赖该结果时附上一行原始结果引用——这正是让"工具声称"日后可审计的手段（plan-template.md）。来自过期索引或降级模式（fallback）的发现必须显式标注为 stale/fallback。

5. Statement-Level PDG Findings

对每个关键符号展开语句级论证：相关语句、控制依赖、数据依赖、状态变更、错误分支、副作用、排序约束、对规划的影响。模板在此明确给出反面纪律：不要粘贴未过滤的图 dump。PDG 切片的构造规则（工具、包含标准、深度边界、schema、安全/性能模式、无 PDG 层的回退）在 pdg-slice.md 中有完整定义——它把一次切片控制在每函数约 15 条语句以内，超限时收紧相关性而不是加大深度。

6. Proposed Changes

每个拟议变更都必须包含：文件、符号、精确职责、预期的行为变化、依赖、约束、实现备注。模板的组合规则进一步收紧：本节只能点名上下文台账（ledger）标记为 source_verified: true 的符号——这是"禁止凭图声称、必须源码核验"在成文边界的强制检查点（plan-template.md）。

7. Implementation Sequence

给出按依赖排序的实施步骤序列，每一步都必须可以独立执行——执行代理可以在任意一步之后停下，而代码树仍然自洽。组合规则特别强调指纹/黄金文件/基线基准保护产物的再生成时机：会改变这类受保护输出的步骤，只允许在序列的最后一步统一再生成一次——CI 只看最终 commit 顶端，而每步都刷新会让中间提交反复漂移，等后续步骤落地时又再次漂移（plan-template.md）。

8. Test Strategy

描述要新增/更新的测试、边界情况、失败路径、回归覆盖、集成边界与相关验证命令。组合规则要求：点名的都是真实存在且已定位的测试文件；新测试必须给出具体的场景清单（input → action → expected outcome）。验证命令必须真实存在且可运行——优先使用携带前置条件的 npm/CI 脚本形式（pre-hooks、构建），而不是直接调用底层二进制。

9. Risk and Impact Analysis

覆盖：高风险符号、下游消费者、兼容性顾虑、性能顾虑、并发或事务风险、迁移风险、可观测性需求。组合规则的硬要求是——必须对 impact pass 报告的每一个直接（depth-1）依赖方给出交代（plan-template.md）。这条规则的依据在 SKILL.md Phase 2：对共享或高连通符号跑 impact 时，计划必须记录 d=1 的直接依赖方清单。

10. Files Expected to Change

一张三列表格，列为 File | Symbols | Reason，让评审者一眼看出改动范围与理由的对应关系。

11. Reusable Implementation Context

机器可读的 context pack（详见下文专节），其规范在 context-pack.md。它强制携带 evidence_provenance 字段：完整的被钉住提交、仓库范围的规范化脏摘要、排序后的被引用路径清单——这是实现代理判断"提交漂移 vs 脏工作区"的关键载荷。

12. Assumptions and Open Questions

严格区分假设与已确认事实。组合规则补充两点：任何 [assumed] 标签的声明必须同时出现在本节；任务未要求的相邻工作（显式延后的后续建议）也落在这里，而不是混进 §6 制造范围蔓延。

13. Definition of Done

给出具体、可测试的完成标准——它是 gitnexus-work 在收尾阶段逐条核对的清单（gitnexus-work/SKILL.md）。

Claim tagging：哪些话能写进计划，用什么语气

full 模板要求给每一条承重声明打上证据类别标签（plan-template.md）：

标签	含义	约束
`[verified]`	在被钉住的提交上做过源码阅读	证据最强
`[graph]`	来自 GitNexus/PDG 输出，未经源码确认	只能说明图说了什么
`[inferred]`	有证据支撑的推理	需标注推理依据
`[assumed]`	未经核验	必须同时出现在 §12

模板强调：未打标签的散文是叙述（narrative），不是证据（evidence）。换句话说，模板默认读者会把"没证据标签的句子"当作背景叙述而非事实声明来读——真正支撑结论的每一句都必须是可追踪的。

撰写前的组合规则（Composition notes）逐条拆解

模板在 full form 代码块之后用近 40 行集中给出了撰写纪律（plan-template.md）。它们是"怎么写才合规"的完整答案，逐条归纳如下：

先发证据快照，再写正文。落笔前依次输出 evidence_provenance.schema_version、完整 HEAD 提交、规范化 global_dirty_digest、按规范化路径排序的 cited_path_manifest；清单包含对象种类、改名端点、HEAD/index/worktree/untracked 各层摘要；只从全局摘要中排除生成的计划路径本身。
证据只能用专属助手生成。必须按 evidence-provenance.md 调用 scripts/evidence-provenance.mjs 并复制其 schema-2 JSON——绝不在散文或 shell 中重建规范记录。
发布只有一条路。完整组成的 UTF-8 计划只能用助手脚本的 write-plan 命令发布。首次规划不得覆盖已有文件；Deepen（加深）模式改写同一 repo 相对路径时必须带 --replace --expected-plan-path <read-plan 返回的路径> --expected-plan-digest <read-plan 返回的摘要>，被替换的前一版会保留在回执的 prior_plan_backup_git_path 中。两个期望值必须来自同一次 read-plan 回执，且 Deepen 必须先通过 read-plan 装载并绑定规范路径与原始字节，再谈改写。
引用长度封顶。§2/§5 引用源码摘录每处最多 max_snippet_lines（默认 30）行，且只有在该摘录承载论证时才允许引用。
§4 发现必须可审计（见前文）；stale-index 或 fallback 模式的发现要显式标注。
§6 只能点名 source_verified 符号。
§7 步骤按依赖排序、独立可执行；受保护产物只在序列末步再生成一次。
§8 写真实测试文件 + 具体场景清单；验证命令必须真实可运行。
§9 覆盖每个 d=1 直接依赖方。

§11 implementation context pack：机器可读的交接协议

plan 的 §11 由 context-pack.md 定义，是"后续代理无需重复调研即可开工"的协议层：

compact 计划输出 mini-pack，只含：task_summary、evidence_provenance、files_to_modify、tests、verification_commands、pdg_constraints（仅当切片真的跑过）、assumptions、open_questions、avoid；
full 计划输出全部字段；两种形态的字段语义完全一致，且 evidence_provenance 都是必填。

pack 的核心字段包括 primary_symbols、related_symbols、execution_path、pdg_constraints、architectural_patterns、files_to_modify、tests、verification_commands、risks、assumptions、open_questions 与 avoid。它同时给出"不得包含"清单：完整文件、仓库级原始脏路径清单、大段 GitNexus 原始响应、未过滤的 PDG dump、重复代码摘录（应当 file:line 引用而非复述）、以及被包装成事实的推测。

它还定义了稳定性契约：字段名是 gitnexus-work 消费的接口——可以自由增字段，但不得改名或改变既有字段语义。其中 assumptions 与 avoid 是承重字段：执行器把 assumptions 当作"依赖前要低成本复核"的事项，把 avoid 当作硬约束。evidence_provenance 同样是承重字段——缺少它或使用 schema 1 的 legacy pack 会被保守地要求做 schema-2 重锚定，绝不被解释为干净工作区。

支撑工具：evidence-provenance.mjs 的三个命令

evidence-provenance.md 是 schema 2 的规范字节契约，scripts/evidence-provenance.mjs 是其可执行定义。gitnexus-plan 与 gitnexus-work 携带字节级一致的副本——任何一方都能独立产出相同快照，且它是生成计划的唯一受支持写入边界。

从目标仓库根目录调用（以下 <skill-dir> 在本仓库即 gitnexus/skills/gitnexus-plan）：

# 1) 读取既有计划（Deepen / 执行的唯一合法装载方式）
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）
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) 发布计划（首次规划绝不带 --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

三个命令各自承担不同的信任义务：

read-plan：输出带描述符锚定的 JSON 回执（规范 generated_plan_path、bytes_read、精确 plan_bytes_base64、plan_digest 即 sha256:<hex>）。消费方必须解码并只使用这些精确字节，不得重新打开词法路径；一份路径的回执永不授权另一份路径，哪怕字节相同。
snapshot：对每个被引用路径生成层摘要。该命令应用与 writer 相同的严格生成计划文件名/日期校验器——计划路径必须精确匹配 docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-kebab-slug>.md，含合法日历日期，不能指向 .git、源码、配置或任意仓库文件。
write-plan：只接受仓库相对的计划目标，拒绝符号链接穿越与意外替换。发布原语是 link(2)（对 Linux 相当于 renameat2(RENAME_NOREPLACE)），目标名已被占用时失败（EEXIST）而非覆盖——首次规划因此无法覆盖中途出现的同名文件；Deepen 的 --replace 保留给既有常规文件，且必须先匹配 read-plan 回执中的精确路径与摘要。

安全发布还依赖平台证明：Linux 通过 /proc/self/fd/<fd>/<child> 的 magic link 按已持有的描述符解析每个名字，父目录在上层被换掉也无法重定向操作——竞态不可能发生；macOS 无此路径（/dev/fd 是 devfs 节点而非 magic link），改为在每一步前后用 O_NOFOLLOW 词法解析 + 持有全链目录描述符 + 重证 inode 链——换来的是检测而非预防。两份平台上的共同承诺是：任何已发布字节都逃不过校验。发布也需要可写的目标仓库、以及计划与 Git-admin 保管区共享同一文件系统；只读或不支持的检出产生阻塞性错误，没有"写去外部路径"或"绕过检查"的回退。

模板与整条 plan → work → eval 流水线的关系

从仓库的交叉引用可以看清模板的上下流契约：

上游是分类与证据预算。SKILL.md Phase 0 按 10 类任务（bug fix、feature、refactor、performance、security、dependency upgrade、concurrency、test/docs、architecture）给出"姿态"矩阵：每类的深度、plan 形态、工具调用预算、freshness 取值决定了写 compact 还是 full。例如本地 bug fix → compact + impact_depth 1 + ~15 次调用 + accept；refactor/shared API → full + impact_depth 3 + ~45 次调用 + strict。depth/form/impact_depth/pdg_data_depth/max_snippet_lines 等旋钮（默认值表见 SKILL.md）可以逐项覆盖分类默认值。
上游证据由台账聚合。context-ledger.md 是规划会话的工作内存：每次图查询与源码读取都记录"回答了哪个问题"，台账同时执行符号预算（默认 5 primary / 20 related）、把脏工作区证据与 HEAD 一起钉住、并定义重读规则。模板 §6"只点名 source_verified 符号"的判据，正是台账里每行符号的 source_verified 布尔位。
下游是执行器。gitnexus-work/SKILL.md 通过同一 read-plan 装载计划，解析 §11 pack 的 acceptance_criteria、tests、verification_commands、assumptions、avoid，逐 §7 步骤实施，逐 §8 场景测试，最后按 §13 收尾。
再下游是评估环。仓库的 eval/workflow_bench/README.md 明确把 gitnexus-plan → gitnexus-work 的完整工作流作为被测量对象：workflow 臂先跑 plan 再跑 work，direct 臂则跳过规划直接实现；技能自身的演进通过离线克隆 + 覆盖层候选评测，且生产技能绝不在真实任务中自我改写。模板中的 80 行上限、§12 假设纪律等约束，正是在这类评测中被反复验证过的"turn economy"设计——SKILL.md 甚至记录过一次两行变更却花 63 轮规划的反面案例。