ki 记忆查询（SSOT）

概述

目的：把"查 ki-search 记忆"这个公共动作收敛为一处，统一承载专题记忆（模块内部路标）、接口信息（对外 API）、数据流（数据实体流向）、强关联（跨模块耦合）、决策记忆（为什么这么定）、错误库（报错→解法）、待生效变更（待合入的资产变更台账）七类记忆的查询，消除查询逻辑散落、SSOT 不清晰的问题。

功能：统一的 ki 查询公共动作层，按记忆类型分发到不同策略（各策略独立一个 reference），引用方只调用本 skill，不再内嵌 ki 查询细节。

使用场景：

强关联查询（供 code review / debug / 设计 / 测试 / 修改前刹车检查等 skill 引用）：检索"改了某模块要连带改哪里"
专题记忆查询（供 expert-lookup 等检索）：知晓"有此专家 + 关键入口"
接口信息查询：检索"某接口在哪定义 / 怎么调 / 谁提供"
数据流查询：检索"某表/字段/消息谁写的 / 谁读的 / 干什么用"
决策记忆查询：检索"当初为什么这么定 / 砍掉的备选是什么 / 该不该重新评估"
错误库查询：贴整段报错堆栈检索"这个报错怎么解"（.solutions/ 关键词匹配命中率低时的语义补位）
待生效变更查询（供 code-review 阶段 2.3）：检索"有没有已合入、该结账的变更登记"
项目记忆查询（"遇事不决 ki-search"，调用 use_skill("ki-search-first")）

定位

查询请求 → ki-memory-lookup（本 skill，只查询）→ ki_search / ki_query_group 检索
                                                    ↓
          返回命中的记忆（专题记忆路标 / 接口信息 / 数据流 / 决策记录 / 错误解法 / 强关联牵动清单 / 待生效变更条目）

输入：目标模块/代码的关键符号（类名、方法名、接口名等）、自然语言问题、或报错原文/堆栈片段（错误库场景）
输出：命中的记忆（专题记忆路标 / 接口信息 / 数据流 / 决策记录 / 错误解法 / 强关联牵动清单 / 待生效变更条目）
边界：本 skill 只查询 ki 记忆，不写入（写入是 ki-memory-write 的事）

核心原则

只查不写：本 skill 查询既有记忆，不负责识别/判定/写入（那是 ki-memory-write 及其调用方的事）
SSOT：ki 查询参数细节只在本 skill 定义，引用方 skill 只写明调用时机，不重复写 ki 查询细节
目录优先于语义（决策记忆、强关联、待生效变更）：这三类数量有限（一个模块通常几条到十几条）且 relation 名本身可读，先用 ki_query_group 确定性列举全部条目、按 relation 名判断、再取内容——比 ki_search 更完整、更可控，不存在语义召回遗漏。待生效变更是强制目录优先——它 vector=false 不进向量，ki_search 根本查不到
- 两级导航：① ki_query_group(subtree="{根分组}") 列出所有模块子分组 → ② ki_query_group(groups="{根分组}/{模块名}", mode="full") 列出该模块全部条目。不要凭代码目录名猜模块名（代码模块名与 ki 功能模块名常不一致，如 order-service vs 订单服务）
- ⚠️ groups 必须显式 mode="full"：默认 mode="hot" + hot_count=5，只返回最热 5 条，比语义检索漏得更多，且不报错（auto_fallback 静默兜底）。subtree 不受此限制（返回的是结构而非条目），也无需 mode="full"
- ⚠️ subtree 不支持逗号分隔多值：传多值会被当整体模糊匹配，可能静默匹配到不相关 group；且近似匹配会跑偏，须核对返回头部的 💡 提示行确认实际解析出的路径
- 拿到清单后：清单信息已够判断就不必取原文，要取就用 ki_get_module_info（relation / relations 均为精确匹配，名称从清单复制）
- ✅ 取多条一律用 relations 数组，一次提交（与 relation 二选一）：同 group 下 ≤10 条一次调用返回，逐条出 results，部分失败不影响其他条。无论"全取"还是"筛出候选后取"，都用 relations 一次提交，不该拆成 N 次单条调用
  - ⚠️ 必须同 group：relations 不接受跨 group，跨模块拉取按 group 分多次调用（每次一个 group）
  - ⚠️ ≤10 条是硬上限，超限报错：超过就按每批 10 条切分调用，不要为省调用数丢条目
  - ⚠️ 逐条核对 results：某条名称写错时只该项失败、不整体报错（批量是"部分失败不影响其他"），须确认每条都返回了内容，失败的补单条重试——否则会误以为"全取到了"
  - ⚠️ 批量会放大 group 解析错误：group 走模糊匹配，解析错了整批结果全错却看似正常——批量前用第 2 级返回的 group 路径原样复制，不手打
- 取多少条，取决于有没有「变更上下文」（双路并行 vs 全取，强关联 / 决策记忆适用）：
  - 有变更上下文（code-review / code-change-impact——手上有完整 diff；只有片段按"无"处理）→ 双路并行：A 筛候选（目标 ≤5 条）+ B 同时 ki_search 语义检索 → 取并集核对
  - 无变更上下文（改前评估 / 点查 / 设计阶段——只知模块名，不知改哪）→ 全取：全量取后按方向/强度逐条核对（数量有限，成本可接受）
  - A 路的筛子按优先级取（不是"看着像就挑"）：① 另一端模块是否落在本次改动涉及的模块集合内 → ② 另一端模块名 / 功能域是否出现在 diff 触及的文件 / 符号 / 调用链里 → ③ relation 名与改动主题的字面 / 语义重合度
    - ⚠️ "是否涉及被改模块"不是筛子：group 本身就是 关联关系/{被改模块}，组内每条都已涉及该模块，拿它筛一条都筛不掉。要筛的是另一端
  - ⚠️ 筛不动就全取，别硬截到 5 条：单模块改动、耦合方全在外部时，三条筛子可能全部失效——此时"挑 5 条"= 随机挑 5 条，漏审风险高于省下的开销。≤5 是筛得动时的目标，不是硬配额
  - ⚠️ B 路是并行补位，不是兜底：与目录路同时发起；B 路命中的条目即使不在 A 的候选里也纳入核对
  - ⚠️ "0 命中才退回全取"不够——任一路为"空"都要警惕：B 路返回空通常不是"没有相关"而是 query 没写好 → 改写 query 重试一次，仍空则退回全取；A 空但 B 有 → 用 B 的结果，并回看 A 的筛选条件是否写歪
  - ⚠️ 省不得的场景直接全取：改动涉及对外契约 / 公共 API / 数据 schema / 权限 / 资金 / 持久化时，漏一条的代价远高于多取几条 → 跳过筛选
  - ⚠️ 判据是"手上有无完整 diff"，不是 skill 名：request-guard 常常只有一句口头提议（无 diff）、code-change-impact 在「只有 Bug 描述、还没修复代码」时也无 diff → 走全取
  - ⚠️ 决策记忆的 A 路筛选力弱于强关联：relation 名不含代码符号，且决策约束的是方案选择而非具体符号；决策记忆里两路权重接近，B 路不能当配角
  - 多模块改动时 A 路按 group 分组调用（relations 不接受跨 group），各组独立筛后合并取并集
  - 待生效变更不在此列：需逐条判定结账且 vector=false 无语义路，永远全取
符号提准：走 ki_search 时，query 中带上关键代码符号（类名/方法名/接口名等），显著提高检索准确度
降级不阻塞：ki 不可用 / 无可用记录 / 未命中 → 静默跳过，不阻塞调用方主流程
记录以代码为准：记忆是辅助参考，与代码实际不符时以代码为准

执行流程

Step 0：确定记忆类型与策略

根据查询目标选择对应 reference 策略：

记忆类型	典型场景	策略 reference	检索 API
强关联	改代码前感知牵动、code review、排错、设计	reference-strong-relation.md	首选 `ki_query_group` 两级导航（`subtree` 找模块 → `groups`+`mode=full` 列条目；按场景取：无变更上下文→全取 / 有→双路并行）/ 辅助 `ki_search`（tags=relation；有变更上下文时与目录路并行发起）
专题记忆	知晓有此专家 + 关键入口	reference-topic-memory.md	`ki_search`（无 tags）
接口信息	查接口在哪定义/怎么调/谁提供	reference-api.md	`ki_search`（tags=api）/ `ki_query_group`
数据流	查某表/字段/消息谁写谁读	reference-data-flow.md	`ki_search`（tags=data）/ `ki_query_group`
决策记忆	当初为什么这么定、砍了什么备选、该不该重新评估	reference-decision.md	首选 `ki_query_group` 两级导航（`subtree` 找模块 → `groups`+`mode=full` 列条目；按场景取：无变更上下文→全看 / 有→双路并行）/ 辅助 `ki_search`（tags=decision；决策记忆里两路权重接近，非配角）
错误库	贴报错堆栈查"这个报错怎么解"	reference-error.md	`ki_search`（tags=error，语义优先）/ `ki_query_group`
待生效变更	有没有已合入、该结账的变更登记	reference-pending-change.md	只能 `ki_query_group` 两级导航（`vector=false` 不进向量，`ki_search` 无效）

为何只有强关联、决策记忆、待生效变更走"目录优先"：强关联与决策记忆数量有限、relation 名可读，精确列举能穷举；待生效变更则是因为它 vector=false，ki_search 完全查不到，目录直查是唯一路径。其余四类中，接口信息/数据流数量中等、专题记忆用自然语言检索更自然、错误库可能成百上千条必须语义优先——一刀切反而更差。

Step 1：按路径准备定位信息

两条路径需要的信息不同，不要一律去猜模块名：

路径	需要准备
目录优先（强关联 / 决策记忆 / 待生效变更）	只需根分组名——由记忆类型决定，固定为 `关联关系` / `决策记录` / `待生效变更`。模块名不需预提取：由第 1 级 `subtree` 列出子分组后从中挑选，避免代码模块名与 ki 功能模块名不一致导致猜错
语义检索（其余四类 + 目录路径的兜底 / 并行补位）	提取功能模块名 + 关键代码符号（2-3 个）。代码符号按实际情况选取最能标识目标的一端——类名、方法名、接口名、函数名、枚举/常量名等；核心是选"写入记忆时会出现的、能唯一定位的符号"，带上能显著提高检索准确度。并行补位模式下还要带上本次改动的关键符号

Step 2：按策略检索

加载对应策略 reference，按其检索方式执行。强关联、决策记忆、待生效变更先走「目录优先」两级导航（① subtree 列出模块子分组 → ② groups+mode="full" 列举该模块全部条目 → 按 relation 名判断 → ki_get_module_info 取内容，取多条用 relations 一次批量）。

ki_search 在其中的角色按有无变更上下文分两种（详见核心原则 3）：

无变更上下文 → 兜底：仅在两级导航都取不到时补位
有变更上下文（手上有 diff）→ 并行补位：与目录路同时发起，与按名筛选的候选取并集
待生效变更 → 无此角色（vector=false 无语义路，目录查不到就是没有）

Step 3：利用结果

强关联命中 → 记录牵动清单（{被改模块} 与 {其他模块} 强关联：方向/强度/原因；双向记录按两条影响线分别列出），作为跨模块一致性检查的重点
专题记忆命中 → 知晓"有此专家 + 关键入口"，跳转前校验专家路径存在
接口信息命中 → 得接口定位（子功能 + 接口列表：API 路径 / 后端接口名 / 文件位置 / 职责），直接据此定位代码
数据流命中 → 得数据流向（实体类型 / 结构 / 生产方 / 消费方 / 业务用途），直接据此定位代码
决策记忆命中 → 得决策成因（决策 / 背景约束 / 被否决方案及理由 / 重新评估触发条件）；避免重复讨论已否决方案，触发条件满足时提示重新评估
错误库命中 → 得报错解法（根因 / 解法 / 验证方式 / 关联方案）；执行后必须按「验证方式」确认，失效则更新条目而非新建
待生效变更命中 → 得待结账清单（触发来源 / 影响资产坐标 / 变更类型 / 合并后应为）；逐条判断对应变更是否已合入，已合入的执行结账（按资产类型落地正式变更：ki 记忆走写入流程 / 专家资产·wiki·项目文档直接改文件 → 删台账条目 → 删 AGENTS.md 指针行），未合入的保持不动，已废弃的删除
未命中 / ki 不可用 → 静默跳过，不阻塞主流程

ki-memory-lookup

SKILL.mdskills/ki-memory-lookup/SKILL.md

ki 记忆查询（SSOT）

概述

定位

核心原则

执行流程

Step 0：确定记忆类型与策略

Step 1：按路径准备定位信息

Step 2：按策略检索

Step 3：利用结果

更多资源

Похожие навыки: development

update-docs-vercel-next-js

docstring-pytorch-pytorch

at-dispatch-v2