GitNexus 实施级工程计划文档模板解析：compact/full 双形态、证据标签与 13 节结构规范-开发者社区

GitNexus 实施级工程计划文档模板解析：compact/full 双形态、证据标签与 13 节结构规范

【免费下载链接】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 仓库中 gitnexus-plan 技能的规范核心——plan-template.md——系统讲解"GitNexus Engineering Plan"文档的标准结构：它如何用 compact/full 两种形态承载不同深度的工作、如何在每个论断上打上[verified]等证据标签、又如何通过 §11 的机器可读上下文包把一次调查结果无损传递给后续实施 Agent。读完本文，你将掌握该模板的逐节语义、80 行硬上限的取舍逻辑、evidence provenance（证据溯源）schema 2 的生成与校验方式，以及编写/发布计划文档的全部硬性约束。

模板在工作流中的定位：一份"可直接开工"的交付物

在 GitNexus 的 Agent 体系中，gitnexus-plan是一个"只做计划、绝不实现"的深度规划技能，其产物是一份计划文档 + 一个机器可读的 implementation context pack。规范规定产物必须写入仓库内形如docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md的路径。这份模板定义了计划文档本身的结构契约：

计划文档告诉人类或实施 Agent：任务是什么、当前行为与架构如何、图与语句级 PDG 发现了什么、改哪里、按什么顺序改、怎么测、何时算完成；
§11 的上下文包（见 context-pack.md）则让跟随实施方（如gitnexus-work或任意执行器）无需重做调查即可开始工作。

在仓库中该技能存在多份字节一致或同步的副本：.claude/skills/gitnexus-plan/（Claude Code 使用）、随 CLI 分发的 gitnexus/skills/gitnexus-plan/，以及插件版 gitnexus-claude-plugin/skills/gitnexus-plan/；其中 scripts/evidence-provenance.mjs 由gitnexus-plan与gitnexus-work携带字节完全一致的副本，保证规划方与执行方对同一棵工作树计算出相同的哈希。

模板开篇即明确两条总则：

由Phase 0 的任务类别决定使用compact（窄/默认工作）还是full（深度工作）形态，调用中的form参数可以覆盖类别默认值；
无论哪种形态，所有仓库产物一律使用 repo 相对路径（即相对于目标仓库根目录的路径，而非文档自身所在目录）。

形态入口：任务类别先于篇幅决定深度

SKILL.md 的 Phase 0 依据任务类别给出"姿态"（深度 · 形态 · 工具预算 · 新鲜度策略），可大致归纳为：

任务类别	默认形态	特点
Bug fix（局部）	compact	1~2 个主符号，`impact_depth`1，约 15 次调用
Feature	compact	默认参数，约 30 次调用
Refactor / 共享 API 变更	full	强制 impact，`impact_depth`3，约 45 次调用
Performance / Security	full	附带性能/安全 PDG 模式
依赖升级 / 迁移	compact	以 impact + 兼容性为主
并发 / 事务类	full	控制流 + 状态变更 PDG 焦点
测试改进 / 文档	compact	通常无需 impact 或 PDG 通道
架构变更 / spike	full	最宽泛，无调用次数上限

depth:narrow|default|deep、form:compact|full、freshness:strict|accept、impact_depth、pdg_data_depth、pdg_control_depth等均以key:value形式写在调用中（如/gitnexus-plan depth:deep impact_depth:3 ...），显式参数优先于类别姿态。当交互会话未带深度信号时，会向上提问一次（Quick / Standard / Deep），Headless 运行则直接套用类别姿态。

Compact 形态：只保留承重章节的最小骨架

Compact 模板以相同的 evidence header 开头，随后只保留承重小节，且要求在标题中保留 § 编号——这是为了让gitnexus-work的 § 引用可以稳定解析。

# GitNexus Engineering Plan > Task: <one line> > Evidence verified at commit <sha>; GitNexus index <...>. > Evidence provenance schema 2; 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)

Compact 形态的核心约束：

80 行硬上限（不含 §11 包）。一旦超限，不是去注水正文，而是说明任务被误分类了——重新归类为 full 而非溢出；
§2–3 合并描述当前行为，控制在 10 行以内，架构信息折叠其中；
§4–5 只保留承重发现，每条都要打标签并注明来源工具；
被裁掉但仍重要的事实，在 §12 以一行记录，绝不写成填充式散文。

Full 形态：全部 13 节，一节都不能静默缺席

Full 形态用于深度工作（重构、安全、性能、并发、架构类）。它要求填满每一个小节：若某节对当前任务确实为空（例如仓库没有索引 PDG 层），保留标题并在一行内说明原因，绝不静默删除。

论断标签（Claim tagging）：让"证据"可审计

Full 形态要求给每个承重论断打上证据类别标签；未打标签的文字只是叙述（narrative），不是证据：

[verified]——在固定 commit 上读过源码确认；
[graph]——来自 GitNexus/PDG 输出，未经源码确认；
[inferred]——有证据支撑的推理；
[assumed]——未经证实，必须同时出现在 §12。

模板全文如下：

# 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. ## 1. Objective A concise description of the requested outcome. ## 2. Current Behaviour Describe the current implementation and execution path. Include the most relevant symbols, files, and statement-level observations. ## 3. Relevant Architecture Explain the involved modules, boundaries, dependencies, and established patterns. ## 4. GitNexus Findings Summarise: - primary symbols; - callers and callees; - impact radius; - related implementations; - related tests; - important cross-module relationships. ## 5. Statement-Level PDG Findings For each critical symbol, explain: - relevant statements; - control dependencies; - data dependencies; - state mutations; - error branches; - side effects; - ordering constraints; - planning implications. Do not paste an unfiltered graph dump. ## 6. Proposed Changes For every proposed change include: - file; - symbol; - exact responsibility; - intended behavioural change; - dependencies; - constraints; - implementation notes. ## 7. Implementation Sequence Provide an ordered sequence of implementation steps. Each step must be independently actionable. ## 8. Test Strategy Describe: - tests to add; - tests to update; - edge cases; - failure paths; - regression coverage; - integration boundaries; - relevant verification commands. ## 9. Risk and Impact Analysis Include: - high-risk symbols; - downstream consumers; - compatibility concerns; - performance concerns; - concurrency or transaction risks; - migration risks; - observability requirements. ## 10. Files Expected to Change | File | Symbols | Reason | | ---- | ------- | ------ | ## 11. Reusable Implementation Context The machine-readable context pack — see `context-pack.md`. Its mandatory `evidence_provenance` field carries the full pinned commit, canonical repository-wide dirty digest, and sorted cited-path manifest. ## 12. Assumptions and Open Questions Clearly separate assumptions from confirmed facts. Explicitly-deferred follow-up suggestions (adjacent work the task didn't ask for) land here too. ## 13. Definition of Done Concrete, testable completion criteria.

逐节职责可归纳如下：§1 是一句话目标；§2/§3 描述现状与架构（含最相关符号、文件与语句级观察）；§4 汇总 GitNexus 图调查（主符号、调用者/被调者、影响半径、相关实现与测试、跨模块关系）；§5 是核心函数的语句级 PDG 切片（控制依赖、数据依赖、状态变更、错误分支、副作用、顺序约束、规划影响），但严禁倾倒未经筛选的图谱转储；§6 对每个改动给出文件、符号、精确职责、预期行为变化、依赖、约束与实现注记；§7 是按依赖排序、每步可独立执行的实现序列；§8 列出新增/更新的测试、边界与失败路径、回归覆盖、集成边界与可运行的验证命令；§9 做风险与影响分析（高风险符号、下游消费者、兼容性、性能、并发/事务、迁移、可观测性）；§10 用表格列出预计变更文件；§11 内嵌机器可读上下文包；§12 区分假设与确认事实并收纳被显式推迟的后续建议；§13 给出可测试的完成标准。

13 节从何而来：与技能阶段一一对应

模板的章节并非随意拼凑，而是与 SKILL.md 的调查阶段严格对应：

模板章节	对应阶段
header 的 commit / freshness 字段	Phase 1 锚定与新鲜度门控
§4 GitNexus Findings	Phase 2 图导航阶梯（query → context → impact/trace → cypher）
§5 PDG Findings	Phase 3 语句级 PDG 切片（见 pdg-slice.md）
§2/§3/§6 的"verify before assert"	Phase 4 定向源码验证
§11 上下文包 + header 溯源	Phase 5 组合前的 evidence_provenance 快照

调查过程中的一切中间信息先记入上下文账本（context-ledger.md）：每次 GitNexus 调用和源码读取都要登记"回答了什么规划问题"，账本同时强制符号预算（默认 5 主符号 / 20 相关符号）并钉住 HEAD 与脏工作树证据。账本本身绝不原样发布，计划和上下文包由它蒸馏而成。

贯穿两形态的证据溯源契约：evidence provenance schema 2

计划能否被"信任地执行"，取决于执行方能否区分"commit 漂移"与"工作树脏状态"。因此两种形态的 header 都要求携带 schema 2 的证据溯源信息，其规范性字节契约定义在 evidence-provenance.md，可执行实现是 scripts/evidence-provenance.mjs（约 2366 行，零 npm 依赖）。它的职责被严格限定为三个子命令：

命令	参数	作用
`snapshot`	`--repo`、`--generated-plan`、`--schema-version 2`、可重复的`--cited <path>`	输出完整的`evidence_provenance`JSON（含全局脏摘要 + 排序的引用路径清单），需原样拷贝进文档，禁止在正文或 shell 中重建
`read-plan`	`--repo`、`--generated-plan`	读取既有计划的唯一受支持方式；返回带规范`generated_plan_path`、`bytes_read`、精确`plan_bytes_base64`与`plan_digest`（`sha256:<hex>`）的 JSON receipt
`write-plan`	`--repo`、`--generated-plan`、`--replace`、`--expected-plan-path`、`--expected-plan-digest`	从 stdin 接收完整 UTF-8 计划（最大 16 MiB）原子发布；初始计划绝不传`--replace`，Deepen 才允许

典型调用（在目标仓库根目录）：

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

文件名与路径白名单

生成计划的路径必须是docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-kebab-slug>.md（含合法日历日期）；snapshot 排除与写入不能指向.git、源码、配置或任意 repo 文件。为兼容历史文档，read-plan额外接受匹配docs/plans/*gitnexus-plan*.md的规范化文件，但该读取兼容性不会放宽写入器的白名单。路径必须为 NFC 规范化的 POSIX repo 相对路径，拒绝 NUL、反斜杠、绝对路径、空组件与./..；任何非法 UTF-8、非 NFC 名称、未合并索引阶段、符号链接父目录穿越等都会 fail closed。

原子无覆盖写盘与平台差异

发布机制刻意不 spawn 解释器、不加载原生代码：用link(2)原子发布，目标名已被占用时返回EEXIST，且不跟随符号链接目标——这与renameat2(RENAME_NOREPLACE)/renameatx_np(RENAME_EXCL)等价，经fs.linkSync在所有受支持平台可用。写前在持握的目录描述符旁创建随机独占临时文件，写后先哈希再发布，发布后再次以O_NOFOLLOW复验路径绑定 inode 与摘要。

平台差异也被明确承认而非掩盖：Linux 上每个名字都经由/proc/self/fd/<fd>/<child>这类 magic link 解析，父目录在检查与使用之间被重命名也无法劫持操作——竞态不可能发生；macOS 没有等价机制，改为对链上每个目录持握打开的描述符并在每一步前后反复证明链仍指向同一组 inode，因此是检测而非预防——父目录在窗口内被替换会被紧随其后的检查发现并中止，且未写入任何字节。两种平台都没有"发布字节逃逸校验"的路径。Deepen 的--replace仅接受已存在的普通文件，并强制--expected-plan-path与--expected-plan-digest必须来自同一次read-planreceipt；旧计划会先被原子移动到 Git 管理目录下随机命名的gitnexus-plan-backups/备份文件（经git rev-parse --git-path gitnexus-plan-backups/<name>解析），随后新计划才以同样的无覆盖原语发布。

§11 机器可读上下文包：执行方免重调查的接口

§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均为强制字段。gitnexus-work把缺失的可选字段视为空而非错误。

implementation_context: task_summary: '' acceptance_criteria: [] evidence_provenance: schema_version: 2 head_commit: '' # full commit SHA that source citations pin to generated_plan_path: '' global_dirty_digest: algorithm: 'sha256' canonicalization: 'gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records' value: '' # digest only; do not embed the whole dirty-path manifest cited_path_manifest: # sorted by normalized repo-relative path - path: '' object_kind: # per layer: regular | symlink | gitlink | directory | absent 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: [] related_symbols: [] # relationship: CALLS / IMPORTS / EXTENDS / test-of / ... execution_path: [] # ordered prose steps, from §2/§5 pdg_constraints: [] # from the PDG slice; empty + note if no layer architectural_patterns: [] files_to_modify: [] tests: [] # existing file to update, or new path to create verification_commands: [] risks: [] assumptions: [] open_questions: [] avoid: - 'Do not repeat full repository discovery' - 'Do not replace established patterns without evidence'

该包明确不得包含：完整文件、仓库级原始脏路径清单、大段 GitNexus 原始响应、未过滤的 PDG 转储、重复的代码摘录（应引用file:line而非重贴）、以及被包装成事实的臆测实现细节。

稳定性契约同样严格：字段名是gitnexus-work消费的接口——可以自由新增字段，但不得重命名或改变既有字段用途。assumptions与avoid是承重字段：执行方把 assumptions 当作"执行前需低成本复验"的事项，把 avoid 当作硬约束。evidence_provenance也是承重字段：其版本、全局摘要与排序的引用路径清单，使执行方能区分 commit 漂移与 staged/unstaged/untracked/deleted/renamed/mixed/absent 等各类工作树证据；缺少它或使用 schema 1 的 legacy 包一律要求保守地按 schema 2 重新锚定，绝不被解释为干净工作树。执行方必须经 helper 的read-plan读取计划，并要求包内generated_plan_path与 receipt 的规范路径逐字节相等。

Composition notes：成文前的硬性纪律

模板末尾的"组合注记"是该文档最容易被忽略、却决定计划可信度的一节，逐条解读如下：

组合前先发快照：立刻输出evidence_provenance.schema_version、完整 HEAD commit、规范global_dirty_digest与按规范化 repo 相对路径排序的cited_path_manifest（含对象类型、重命名端点与各层摘要），只从全局摘要中排除生成的计划路径；
只经 helper 生成溯源记录：按 evidence-provenance.md 调用 scripts/evidence-provenance.mjs 并原样拷贝 schema-2 JSON，禁止在散文或 shell 中重建规范记录；
只经write-plan发布：先在仓库外/内存中完成 UTF-8 文档，再以 stdin 传给 helper。初次计划不得覆盖既有文件；Deepen 通过write-plan --replace --expected-plan-path <path-from-read-plan> --expected-plan-digest <digest-from-read-plan>重写同一相对路径，旧计划在 receipt 的prior_plan_backup_git_path中留档。两个期望值必须来自同一份receipt，Deepen 必须先用read-plan加载并绑定该规范路径与原始字节；
§2/§5 引用上限：源码摘录每处最多max_snippet_lines（默认 30）行，且仅当该摘录真正承载论证时才引用；
§4 每条发现都注明工具调用（tool + 关键参数）并在计划倚重时附一行结果原文——这是工具论断事后可审计的关键；过期索引或 fallback 模式的发现必须显式标注；
§6 只能引用 ledger 标记为source_verified的符号——出现在 Proposed Changes 中的符号必须经过源码验证；
§7 按依赖排序且每步独立可行：执行者可以在任一步后停下而树仍自洽。凡是会改动 fingerprint、golden、recorded baseline 的步骤，只在序列最后一步一次性再生成——CI 只裁决 tip，每步刷新会搅乱中间提交并在后续步骤落地时再次漂移；
§8 必须点名真实存在的测试文件，新增测试给出具体场景清单（input → action → expected outcome）；验证命令必须真实存在且可运行，优先采用自带前置钩子/构建的 npm/CI 脚本形式，而非直接调用底层二进制；
§9 必须覆盖 impact pass 报告的每一个直接（depth-1）依赖者。

与其余规划工具链的关系

这份模板处于一套自洽文档体系的末端，全链路文件如下：

文件	作用
.claude/skills/gitnexus-plan/SKILL.md	技能主流程：Phase 0~5、硬规则、配置旋钮、Deepen 模式与 Fallback 模式
references/plan-template.md	本文所述的 13 节计划文档模板
references/context-pack.md	§11 上下文包 schema 与稳定性契约
references/context-ledger.md	调查账本 schema 与反重复读取规则
references/evidence-provenance.md	证据溯源 schema 2 的规范性字节契约
references/pdg-slice.md	语句级 PDG 切片的工具、收录标准与安全/性能模式
scripts/evidence-provenance.mjs	snapshot 序列化器 + 描述符锚定的计划读写器

模板同样决定了Deepen 模式的演进路径：/gitnexus-plan deepen <plan-path>先经read-plan读取并绑定既有计划的规范路径与摘要，随后重跑完整 Phase 1（含 freshness 门控）并在推进 pin 之前重新锚定——变更、改名、删除或新消失的引用路径都要先重读或降级论断，再逐条把[graph]/[inferred]提升为[verified]，补齐 §7 中已由gitnexus-work落地的步骤，最后用write-plan --replace重写同一规范文件。

何时该用哪种形态：一个判断范式

模板给出了一条清晰的升级判据：compact 计划若超过 80 行（不含 §11 包），说明任务被误分类，应重新归类为 full 而非任其溢出。反过来，深度工作若仍用 compact，就意味着承重章节被压缩到不可执行。此外，"turn economy"本身就是可交付物——SKILL.md 以仓库 eval/workflow_bench 中一次"两行改动用了 63 轮"的实测为反面案例，强调按类别调用预算执行、预算耗尽就把未决问题写进 §12 而非继续深挖，因为执行方本就廉价复验。换言之：模板的意义不在于把计划写厚，而在于让每个论断可溯源、每步可执行、每处空白被显式声明——这正是 GitNexus Engineering Plan 文档模板最核心的设计哲学。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考