GitNexus Engineering Plan

2026-09-08 17:46:56作者：宣海椒Queenly

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

Task: Evidence verified at commit ; GitNexus index <...>. Evidence provenance schema 2; global dirty digest ; cited-path manifest 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 包）**。任何被裁掉但仍要紧的内容，浓缩成 §12 里的一句话，**绝不允许用填充性散文（padded prose）去凑行数**。原文对超限的处理给出明确诊断："一份超过上限的 compact 计划，说明任务被错误分类了——应当重新归类为 full，而不是任其溢出。"这本质上是把"模板溢出"当作分类错误的信号灯。
- **章节缺失是有意的**：compact 只覆盖 §1、§2–3、§4–5、§6、§7、§8、§11（mini-pack）、§12、§13，即§9（风险与影响）与 §10（预期变更文件表）默认缺席——它们属于 full 形态的深度任务专属章节。

注意 compact 的标题写法刻意把章节区间折叠进了小节标题（如 `Current Behaviour (§2–3)`、`Findings (§4–5)`），其作用就是保持 § 编号语义对 `gitnexus-work` 可解析，同时又压缩了文档层级。

## Full 表单：13 节一个都不能少

full 表单面向重构、性能、安全、并发、架构级任务，规则是：**填充每一个小节；若某节对当前任务确实为空（例如没有索引 PDG 层），也要保留标题并在一行内说明原因，绝不静默丢弃。** 这就保证了消费方永远能按固定章节号定位信息。

### 证据标签：全文统一的论断审计语言

full 表单（compact 同样适用）要求给**每一条承重论断**打上证据类别标签：

| 标签 | 含义 |
| --- | --- |
| `[verified]` | 已在钉住的 commit 上做了源码阅读确认 |
| `[graph]` | 来自 GitNexus / PDG 输出，未经源码确认 |
| `[inferred]` | 有证据支撑的推理 |
| `[assumed]` | 未经验证——**且必须同时出现在 §12 假设清单中** |

模板原话给出了一个容易被忽略的强制规则："**未打标签的散文只是叙述（narrative），不是证据（evidence）。**"这意味着凡是承载论证的句子都要能归入四类之一；任何 `[assumed]` 若没有同步登记到 §12，就属于格式违规。

### 完整骨架

```markdown
# 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.

§2/§5：语句级证据的呈现纪律

这两节是计划里最容易被写成"源码糊墙"的地方，模板给出双重约束：

引用配额：§2/§5 引用源码摘录时，每次最长 max_snippet_lines（默认 30）行，并且只有在摘录真正承担论证时才允许引用（"only when the excerpt carries the argument"）；
禁止裸转储：§5 明确写"不要粘贴未经过滤的图转储（Do not paste an unfiltered graph dump）"——PDG 的证据要按语句的八类属性（相关语句、控制依赖、数据依赖、状态变更、错误分支、副作用、顺序约束、规划影响）逐条提炼，而非把 PDG 输出整体倒进文档。

§4：让每条图谱论断"可回放"

§4 的每条发现必须写出它来自哪一次工具调用（工具名 + 关键参数），当计划依赖该结果时还要附一行结果原话引用——这正是"工具论断事后可审计（auditable）"的机制。此外，基于过期索引或回退模式得出的发现必须显式标注（stale-index or fallback-mode findings are labelled as such），防止把旧图当新事实。

§6：只允许写"源码验证过"的符号

§6（拟议变更）只能提名台账（ledger）中标记为 source_verified 的符号。这条规则与 SKILL.md Phase 4 相互咬合："一个出现在 Proposed Changes 里的符号，必须已经过源码验证。"而验证动作本身是定向的行区间阅读（只读将被引用的签名、分支条件、状态变更、错误路径），不是整文件通读。

§7：按依赖排序、可随时停下的步骤序列

§7 的实现步骤要求每一步都可独立执行（independently actionable）——执行器可以在任一步之后停下，代码树依然自洽。对受指纹（fingerprints）、golden 文件或基准基线保护的输出，模板施加了著名的"只再生一次"规则：

改变此类输出的步骤，其产物重生成必须发生在序列的最后一个步骤——CI 只看最终顶点（tip），而每步都刷新会让中间每个 commit 都抖动，并在后续步骤落地后再次漂移。

§8：可运行的真实命令，具体的测试场景

§8 要点名真实存在且已定位的测试文件；新增测试要给出具体场景清单（输入 → 动作 → 期望结果）。验证命令"必须存在且可运行"，并且优先选择携带前置依赖（pre-hooks、构建）的 npm/CI 脚本形态，而不是直接调用底层二进制——这保证了后续执行器照抄命令就能通过。

§9：d=1 直接依赖的全量清点

§9 的风险分析必须覆盖 impact pass 报告的每一个直接（depth-1）下游依赖者。这呼应了 SKILL.md 的 Phase 2 阶梯：对共享或高连接度符号先做 impact {target, direction}，把 d=1 的 direct dependents 全部记录在案——计划要么处理它们、要么在 §9 中逐一说明。

§11 实现上下文包：机器可读的执行契约

§11 不是普通小节，而是整份计划的"机器接口"。完整 schema 见 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 消费的接口——可以自由新增字段，但禁止重命名或改义现有字段。assumptions 与 avoid 是承重字段：执行器把 assumptions 当作"使用前需廉价重验证"的清单、把 avoid 当作硬约束；evidence_provenance 让执行器能区分 commit 漂移与工作区 staged/unstaged/untracked/deleted/renamed/mixed/absent 各类脏证据。
包内禁止出现：完整文件内容、仓库级原始脏路径清单（只存其规范全局摘要 global_dirty_digest）、大段 GitNexus 原始响应、未过滤的 PDG 转储、重复的代码摘录（应引用 file:line 而非重新引用）、把推测当作事实的细节。

证据溯源机与"唯一写入边界"

模板的组成注记（Composition notes）规定了整条链路的唯一合法通道，任何绕过都构成违规。这部分的完整字节契约在 evidence-provenance.md，可执行实现是同目录 scripts/evidence-provenance.mjs（该 Node 助手无 npm 依赖、带版本号，gitnexus-plan 与 gitnexus-work 各持字节级一致的副本）。

撰写前：发射 provenance 快照

在正式成文之前，立即发射 evidence_provenance.schema_version、完整 HEAD commit、规范的 global_dirty_digest，以及按规范化仓库相对路径排序的 cited_path_manifest（含对象种类、重命名端点、HEAD/index/worktree/untracked 四层摘要）。命令形态：

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

每引用一个路径就传一个 --cited。助手输出完整的 evidence_provenance JSON 值——照抄该值，绝不用散文或 shell 重新创作规范记录（never recreate canonical records in prose or shell）。

发布：write-plan 是唯一写入边界

完整文档必须在仓库外（内存或 scratchpad）合成后，通过同一助手的 write-plan 命令从 stdin 管道写入：

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

几个值得深挖的安全语义（源自 evidence-provenance.md 的实现契约）：

初次规划永不传 --replace：目标已存在即报错；发布原语是 link(2)（原子化、目标名被占即 EEXIST 失败、拒绝跟随符号链接），等价于 renameat2(RENAME_NOREPLACE) 的无覆盖保证。也就是说，write-plan 面对"写入瞬间目标才出现"的竞态也只能失败、不能覆盖。
平台差异是"防"与"检"的区别：Linux 上每个名字都经 /proc/self/fd/<fd>/<child> 魔法链接解析，父目录在检查与使用之间被改名也无法重定向操作——竞态"不可能发生"而非"被发现"；macOS 没有等效路径（实测 /dev/fd/<fd> 是 devfs 节点而非魔法链接），改为对链上每个目录持有 O_NOFOLLOW 打开描述符并在每步前后重证链身份，能"检测并中止"任何已发生的父级换入。两种平台下没有任何一个已发布的字节能逃过验证。
深度模式（Deepen）重写同一路径时追加 --replace --expected-plan-path <read-plan 返回的路径> --expected-plan-digest <同一份 receipt 返回的摘要>：两个期望值必须出自同一份 read-plan receipt，摘要/路径任一不匹配即阻断发布；被顶替的旧计划先被原子移动到 Git-admin 目录下的 gitnexus-plan-backups/ 随机文件（receipt 返回 prior_plan_backup_git_path，须用 git rev-parse --git-path 解析），然后才无覆盖地发布新计划。
路径契约：schema 2 下生成的计划路径必须是 docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-kebab-slug>.md（含合法日历日期），排除 .git、源码、配置或任意仓库文件；外部输出在 schema 2 中没有表示（no external-output fallback）。快照的排除是一次精确的规范化路径比较，不允许 glob、目录、basename 或 docs/plans/ 级宽排除。

read-plan：读取既有计划的唯一通道

无论是 Deepen 还是后续执行，读取已有计划只能走 read-plan：

node <skill-dir>/scripts/evidence-provenance.mjs read-plan \
  --repo "$PWD" \
  --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md

GitNexus

项目地址：https://gitcode.com/GitHub_Trending/gi/GitNexus

登录后查看全文