强关联关系记录

概述

目的：把"浏览完整代码才能发现的跨文件强耦合"显性化、可检索化——解决 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
• 模块专家资产与专题记忆，参见 use_skill("expert-team")
• 查找复用专家资产，参见 use_skill("expert-lookup")