Strong Relation

---
name: strong-relation
description: 识别并判定跨文件的强关联关系（契约 / 业务耦合）：本 skill 只负责识别与判定方向，写 ki 下沉 ki-memory-write，查询走 ki-memory-lookup。触发："记录强关联"、"模块间强耦合"、"改A要连带改B"，或 expert-team 产出专家资产后自动调用。
---

# 强关联关系记录

## 概述

**目的**：把"浏览完整代码才能发现的跨文件强耦合"显性化、可检索化——解决 code review 或修改代码时，改了 A 却不知道必须连带改 B 的风险。

**功能**：识别跨模块/跨文件的强关联（契约耦合 + 业务耦合），沿契约/结构线与语义/行为线分别判定方向与强度，按功能模块分组写入 ki-search，供后续检索感知。

**使用场景**：
- expert-team 创建专家资产完成后，自动调用本 skill 记录该模块与外部的强关联
- 手动指定模块/范围，记录其强关联
- **查询**既有强关联记录（排查/重构/review 前了解模块间耦合），调用 `use_skill("ki-memory-lookup")`（本 skill 只识别+判定，写 ki 下沉到 ki-memory-write，查询走 ki-memory-lookup）

## 定位

```
expert-team 落盘模块专家 → strong-relation（本 skill）→ 识别强关联 → 按模块分组写 ki-search
                                                                            ↓
                        后续 code review / 修改时，ki-search 检索即可感知"改A必改B"
```

- **输入**：目标模块（默认 expert-team 刚完成的模块；手动时指定模块路径/范围）+ 可选操作意图
- **输出**：强关联原子记录（写入 ki-search，按功能模块分组）
- **边界**：本 skill **记录"模块间"的强耦合关系**，不深挖单模块内部知识（那是 expert-team 的事）；不画 ER 图/数据流图（那是 data-flow-model 的事）；不分析某次具体改动的影响（那是 code-change-impact 的事）

## 强关联的定义（识别什么）

强关联 = **改了 A 必须连带改 B（或强烈建议连带改）** 的耦合。用三个维度刻画：

1. **契约耦合**（最主要）：数据源→消费端、接口签名变更牵动所有调用方、消息格式契约、DTO/字段结构共享、数据库表结构共享
2. **业务耦合**：业务规则依赖、调用顺序要求、状态一致性、事务边界
3. **粒度**：够用即可——**类名、文件位置、关键接口名**，不追求接口签名级逐字段细节

**关键区分（方向性/不对称）**：

方向判定沿**两条正交的依赖线**分别走一遍，两条线可能相反且同时存在：

| 依赖线 | 问什么 | 谁是"源" | 方向结论 |
|--------|--------|---------|---------|
| **契约/结构线** | 谁消费谁的**数据结构/参数/消息/接口签名**？ | 结构的生产者（如 Builder 生成参数结构、数据模型定义方） | 改源的结构/契约 → 消费端必改 |
| **语义/行为线** | 谁的**行为语义/规则**被对方去适配？ | 语义的定义者（如底层引擎定义 instant 行为，上层做对齐补偿） | 改源的语义 → 适配方必改 |

> 两条线可能给出**相反方向**：A 可以是 B 的结构之源（B 消费 A 生成的数据），同时又是 B 的语义依赖方（A 去适配 B 定义的行为）。此时两条都是强关联，**不得**只记一条、把另一条归结为"不用管"。

> **业务耦合其余子类归入语义/行为线**：「调用顺序要求」「事务边界」「状态一致性」等业务耦合，归入语义/行为线判定——谁定义了顺序/边界/状态约束，谁就是"源"；改源，依赖该约束的另一端必改。

**方向结论必须绑定"改动的性质"**：
- 改 B 的**内部实现**（对外契约/输出不变）→ 依赖方 A 不用管
- 改 B 的**对外契约/数据结构/参数/消息**（输出变了）→ 依赖方 A 必改
- 改 B 的**行为语义**（对外签名/结构不变，但结果/行为变了，如算法从"四舍五入"改为"向下取整"）→ 视同改语义之源，需检查语义/行为线的适配方 A 是否必改

> 因此禁止出现笼统的"改 B，A 不用管"——必须写清是"改内部实现不用管"还是"改对外契约/行为语义必改"。

## 核心原则

1. **先查后记**：写入前先查该模块是否已有强关联记录（查 `ki-memory-lookup`），避免重复
2. **GitNexus 辅助 + 源码确认**：用 GitNexus 查调用/依赖关系定位候选，再读关键源码/数据结构确认真实耦合强度，不凭图谱臆断
3. **方向性必标**：每条关联必须标明方向与强度（必改/建议改/可选）；方向沿「契约/结构线」与「语义/行为线」分别判定，两条线相反时都要记录，不得漏记反方向
4. **够用即止**：粒度到类名/文件/关键接口，不深挖签名级细节
5. **写 ki 下沉**：所有 ki 写入动作（分组/tags/格式）统一下沉到 `ki-memory-write` 强关联策略，本 skill 只负责识别+判定方向，不重复声明写入细节
6. **可分次写入**：关联多时一次写不完，可分多次原子写入同一 group，保持分组一致
7. **ki 不可用降级**：ki 不可用时告知用户并给出关联清单（对话内），不阻塞流程

## 工作流

```
Step 0 环境检测 → Step 1 定位模块 → Step 2 识别关联 → Step 3 判定方向强度 → Step 4 写 ki（下沉 ki-memory-write）→ Step 5 校验
```

### Step 0：环境检测

1. 确认 ki 可用（`ki_manage_index_list` / `ki_search` 可调用）
2. 确认 GitNexus 是否可用（`context`/`impact`/`query`）——可用则辅助识别，不可用则纯读源码（不阻塞）

### Step 1：定位目标模块

- **自动模式**（expert-team 完成后）：目标 = 刚创建的专家/专题。从 `.module-experts/{专家名}/` 读 `agent.md` 获取模块根路径与职责
- **手动模式**：用户指定模块路径/范围，或从上下文推断

### Step 2：识别强关联（GitNexus + 源码确认）

1. **GitNexus 定位候选**：用 `impact`/`query`/`context` 查目标模块的关键符号（类/方法）的调用方、依赖方，列出候选关联对象
2. **源码确认**：读关键源码（数据结构定义、接口签名、消息格式、消费方处理逻辑），判断是否为强耦合
3. **甄别强弱**：区分
   - **强关联**（记录）：改 A 必须/强烈建议连带改 B——数据结构共享、接口契约、消息格式、业务规则强依赖
   - **弱关联**（不记录）：普通调用、读操作、可选依赖，改了不一定会坏

> 识别重点（沿两条依赖线都扫一遍）：**契约线**——数据源→消费端、接口定义→实现/调用方、DTO/结构体→所有使用方、消息发送→消息消费、共享表结构→多写方；**语义线**——业务规则/行为语义强依赖（如上层补偿逻辑适配底层引擎行为）。避免只沿契约线找、漏掉语义线。

> **无强关联时**：扫描后未发现任何强关联（纯独立模块），明确告知用户"该模块无跨文件强关联"，正常结束，不写入 ki。

### Step 3：判定方向与强度

对每条关联，**沿两条依赖线分别判定方向**（见「强关联的定义」），再输出三元组：

1. **契约/结构线**：谁消费谁的数据结构/参数/消息/接口签名？改结构之源 → 消费端必改
2. **语义/行为线**：谁的行为语义被对方适配？改语义之源 → 适配方必改
3. **两条线方向相反时**：分别输出两条三元组（或一条内分两条「影响线」），不得合并成单向、不得漏记反方向

每条（或每向）三元组：

```
{源} → {目标} | 方向 | 强度 | 原因（含改动性质限定）
```

| 字段 | 取值 | 说明 |
|------|------|------|
| 源/目标 | 关键类名/接口名（可多个） | 参与关联的两端，每端可含多个类/文件 |
| 方向 | `A→B` 或 `B→A` 或 `A↔B` | **影响方向**：`A→B` 表示"改 A 连带改 B"（左端=改动源，右端=被影响方）。注意与"依赖方向"相反（A 依赖 B = 改 B 影响 A），本 skill 箭头一律用影响方向。两条线相反时，`A↔B` 须分列两条影响线，各自带原因与强度 |
| 强度 | `必改` / `建议改` / `可选` | 改源时，目标必须跟着改的程度 |
| 原因 | 一句话 | 为什么是强关联，并**标注改动性质限定**：是"改内部实现不用管"还是"改对外契约必改" |

> Step 3 是判定阶段的内部整理格式，用于 AI 归纳后再写入 Step 4 的 `module_info`。`→` 在此为概念表达，写入 ki 时 `relation` 名称用 `-` 连接（不含特殊字符）。

### Step 4：写 ki（下沉到 ki-memory-write）

识别与判定完成后，写 ki 的动作**统一下沉到 `ki-memory-write`**：

调用 `use_skill("ki-memory-write")` 的**强关联策略**，传入 Step 3 判定的三元组（或双向影响线）。ki 写入细节（`ki_sync_relation` API、分组约定「关联关系/{功能模块名}」、relation 命名、tags=`relation`、module_info 模板、格式硬约束）一律以 `ki-memory-write` 的 `reference-strong-relation.md` 为准，本 step 不重复声明。

> 本 skill 只负责"识别关联 + 判定方向强度"（Step 1~3 的核心价值），"写 ki"这个公共动作由 `ki-memory-write` 承载，避免与专题记忆等其它 ki 写入重复维护格式硬约束与 API 细节。

### Step 5：校验

写入后，用 `ki_query_group`（group = `关联关系/{功能模块名}`，**`mode="full"`**）确认关联原子已归入正确子分组，抽查 1-2 条确认已可检索。

> ⚠️ **校验必须显式 `mode="full"`**：默认 `mode="hot"` 只返回最热 5 条，新写入的关联若不在其中会被误判为"写入失败"。

> 校验是**写入侧**的自我验证（确认数据落盘），与对外**查询**（`use_skill("ki-memory-lookup")`）不同；写入校验直接查 ki 结果，不需要走 ki-memory-lookup。

校验不通过 → 回到 Step 4 修正；ki 校验异常时降级为对话内输出清单。

## 查询强关联（调用 ki-memory-lookup）

强关联的**查询**由 `ki-memory-lookup` skill 提供（只查不写，SSOT）。本 skill 需要查询存量记录时（如 Step 5 校验、Step 2 先查后记），调用 `use_skill("ki-memory-lookup")`，ki 查询参数细节以 ki-memory-lookup 为准，本 skill 不重复。

## 更多资源

- **查询**强关联记录，调用 `use_skill("ki-memory-lookup")`
- **写入**强关联记录（写 ki 动作），调用 `use_skill("ki-memory-write")`
- 强关联识别细则（高概率/低概率模式），参见 [reference.md](reference.md)
- 模块专家资产与专题记忆，参见 `use_skill("expert-team")`
- 查找复用专家资产，参见 `use_skill("expert-lookup")`