pdlc-relate · diff
git:20260606.4b10e8d to git:20260911.c7dfbe7
40 added, 6 removed. Audit A to A.
---
name: pdlc-relate
description: 管理 feature 关系链（set/query/impact/orphans/rebuild/validate）
argument-hint: <set|query|impact|orphans|rebuild|validate> [args]
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 3
stage: ops
produces:
- docs/.pdlc-state/_relations.json
- docs/.pdlc-state/_graph.md
requires: []
next_step: null
terminal_state: null
---
# Feature 关系链管理
<!-- @include templates/prompts/iron-law.md -->
管理 PDLC feature 之间的关系链。维护反向索引 `docs/.pdlc-state/_relations.json` 和全局图 `docs/.pdlc-state/_graph.md`。
<!-- @include templates/prompts/relations.md -->
+ <!-- @include templates/prompts/state-read.md -->
+
## 段一：执行子命令
- 从 `$ARGUMENTS` 解析子命令：
+ 从 `$ARGUMENTS` 解析子命令。子命令分两类，**只读类绝不写任何文件**：
+ | 类别 | 子命令 | 写什么 |
+ |---|---|---|
+ | 写入类 | `set` / `rebuild` | `<fid>.json` 的 `relations` 块（仅 `set`）、`_relations.json`、`_graph.md` |
+ | 只读类 | `query` / `impact` / `orphans` / `validate` | 不写 |
+
+ 只读类遇到 `_relations.json` **缺失或比任一状态文件旧**时：从各状态文件的 `relations` 块当场现算（只在内存里），
+ 并在输出里注明「索引缺失 / 已过期，本次现算、未落盘；要持久化请跑 `/pdlc-relate rebuild`」。
+ **不要替用户顺手 rebuild**——查询命令悄悄改仓库，用户会在 `git status` 里看到两个来路不明的文件。
+
### `set <fid> <type> <target-fid> [target-fid...]`
为 feature `<fid>` 添加 `<type>` 关系，指向一或多个目标。
1. 读 `docs/.pdlc-state/<fid>.json`；**若无 `relations` 块**（旧状态文件 / Phase 1 关系块可选），先初始化六类空块（`extends`/`depends_on`/`supersedes`/`resolves`/`conflicts_with`/`relates_to`），再在 `relations.<type>` 数组追加目标（去重）
+ - **`relations` 存在但不是六键对象**（体检报 `relations-not-object`，如数组形态）→ **停下，不写**。
+ 把现有条目原样列出，请人确认迁移方式后再动。直接初始化六类空块会把原有条目连同其中的说明文字
+ 一起覆盖掉——这是静默的数据丢失，比关系写不进去更坏
2. 若 `<type>` 是对称类型（conflicts_with / relates_to）→ 同时在每个目标的 `<fid>.json` 镜像写入
3. 写回后调用本命令 `rebuild` 流程刷新 `_relations.json` + `_graph.md`
### `query <fid>`
显示 `<fid>` 的全部关系（出边 + 从 `_relations.json` 读入边）。
### `impact <fid>` ⭐ 杀手锏
- 分析改动 `<fid>` 的影响半径。读 `_relations.json`：
- - 🔴 **直接影响**（depth 1 入边）：直接 extends / depends_on 本 feature 的，必须协调
- - 🟡 **间接影响**（depth ≥2 传递入边）：通过中间 feature 传递依赖的，应 review
- - 🟢 **历史**（指向 terminal-state feature 的边 / resolves 的缺陷）：仅审计
+ 分析改动 `<fid>` 的影响半径。读 `_relations.json`（缺失或过期时按上文现算，不落盘）：
+ - 🔴 **直接影响**（depth 1 入边）：**只有** extends / depends_on 本 feature 的，必须协调
+ - 🟡 **间接影响**（depth ≥2 传递入边）：沿 extends / depends_on 传递的，应 review
+ - 🟢 **历史**（指向**已抵达终态**——`current_stage` 以 `_done` 结尾——的 feature 的边 / resolves 的缺陷）：仅审计
+ - `relates_to` / `conflicts_with` 是弱关系与互斥，**不进 🔴 / 🟡**，单列「相关 / 冲突」
+ - 体检中不入图的关系（数组形态、表外类型、散文目标）**不要解读成 feature 依赖**——原样列在体检块里，交给人判断
输出树状结构 + 建议（先 review 哪些 PRD / 是否该新建 supersedes feature 而非就地改）。
### `orphans`
列出 `_relations.json` 中 inbound + outbound 均为空的 feature（可能是孤立 / 死代码候选）。
### `rebuild`
扫描所有 `docs/.pdlc-state/<id>.json` 的 `relations` 块 + 文档追溯头的 `关系:` 行，重建：
- `_relations.json`：nodes（id→name/stage/terminal）+ edges（flat 有向列表）+ index（每节点预计算 inbound/outbound）
+ - `terminal` = `current_stage` 以 `_done` 结尾（见上方「判终态的唯一依据」）。**不读 `terminal_state`**——
+ 它是目标不是事实，拿它算会把「停在 review、目标写着 review_done」的 feature 标成已完成
+ - 只收**六键对象形态**、目标为合法 feature ID 的关系；体检报 `relations-not-object` / `relations-unknown-type` /
+ `relations-target-not-id` 的不入图，列进输出的体检块
+ - 目标 ID 没有状态文件（`relations-dangling`）的不入 edges，交给 `validate` 报告——不要为了过自检去造占位节点
- `_graph.md`：mermaid 图，边样式按类型区分（supersedes 虚线 / conflicts_with 粗线 / 其余实线），顶部加 `<!-- AUTO-GENERATED by /pdlc-relate · do not edit by hand -->`
### `validate`
按 `relations.md` 的校验规则检查：悬空引用 / 自引用 / extends·depends_on 成环 / 矛盾对 / 对称一致性。报告问题清单。
## 段二：自检（强制）
<!-- @include templates/prompts/self-audit.md -->
### 关系链自检清单
- [ ] `_relations.json` 是合法 JSON（`jq . ` 通过）
- [ ] 所有 edge 的 from/to ID 在 nodes 中存在（无悬空）
- [ ] 对称类型（conflicts_with / relates_to）两端互含
- [ ] extends / depends_on 无环
- [ ] `_graph.md` 含 `AUTO-GENERATED` 头且 mermaid 语法成对闭合
- [ ] set 操作的目标 ID 格式合法（F/B 开头）
+ - [ ] 只读类子命令（query / impact / orphans / validate）没有写任何文件
+ - [ ] nodes 的 `terminal` 全部按 `current_stage` 后缀算，没有读 `terminal_state`
## 段三：修复（单次，不递归）
<!-- @include templates/prompts/loop-prevention.md -->
- 可自动修复（对称缺失补镜像 / index 不一致 → 重跑 rebuild）→ 直接修
- 无法自动修复（真实的循环依赖 / 用户意图矛盾）→ 记录到报告，提示人工介入
## 段四：交接
> **状态机豁免**：本命令非 feature-scoped（不推进单个 feature 的阶段），不更新 `<feature-id>.json` 的 history，只维护关系索引文件。同 `/pdlc-changelog`。
<!-- @include templates/prompts/handoff.md -->
- **本命令的 handoff 输出：**
+ **本命令的 handoff 输出**（按子命令类别二选一）：
+ 写入类（`set` / `rebuild`）：
+
```
✅ 关系操作完成：<子命令> <参数>
📦 已更新：docs/.pdlc-state/_relations.json + _graph.md
👉 下一步：/pdlc-relate impact <fid> 查影响 | /pdlc-status 看全景
```
+
+ 只读类（`query` / `impact` / `orphans` / `validate`）：
+
+ ```
+ ✅ 关系查询完成：<子命令> <参数>（只读，未写任何文件）
+ 👉 下一步：/pdlc-relate rebuild 持久化索引（若本次为现算） | /pdlc-status 看全景
+ ```
+
+ 体检有偏差时，两种都在最前面加一行 `⚠️ 输入契约体检：<M> 处偏差（见开头）`。
---
**关系操作**: $ARGUMENTS