shaomang/mtnode-aio/ai-facts

AI 事实库（mtnode_facts）

AI 事实库是每张画布一份的极简条例库：给 AI 读的紧凑索引，不是人类文档。它与「团队事实库」（人读的 md 文档）并存、互不干扰，也与 mtnode_db（数据库副本的权威事实）分工不同。工具对所有会话 / 专家 / 节点默认可用，不需要接线，也没有许可开关。

一、什么时候必须查

• 要索引项目内容时先查这里：需要知道「这个项目有哪些模块 / 关键文件在哪 / 定了哪些约定 / 工作流的端口与数据流怎么走 / 命令入口是什么 / 踩过哪些坑」时，先 query（拿不准关键词就 list 全量看标题），再决定要不要去读现文件。
• 拿到条目后仍要回到现文件核对（条目是索引，不是原文）；条目只是帮你少读几个文件、快速定位。
• 一轮任务里同一个问题不要反复 query：查一次拿全，答案不够再换关键词查第二次。

二、什么时候必须写（沉淀纪律）

创建项目架构、搭建 / 改工作流、定下约定与路径之后，把关键结论沉淀成极简条例写进本库。典型场景：

• 建完 / 分析完项目架构、细化完模块：每个功能块一行——模块职责 + 关键文件与相对路径。
• 搭完 / 改完工作流：节点链与端口口径、数据（或文件）流向、一键重跑的 control 入口。
• 定下约定：目录约定、命名约定、保护路径（不要修改的目录 / 文件）、以及约定的来源（哪份 AGENTS.md / 哪次用户确认）。
• 命令入口：构建 / 启动 / 测试 / 发布怎么跑。
• 已知坑：这次踩到的、下次不该再踩的（含报错特征与规避办法）。

写作口径（极简条例，软纪律，靠本技能约束）：

• 一条一件事：把混在一起的信息拆成多条，别写成一整篇。
• 标题可辨：标题写检索时你会用的词（模块名、文件路径、命令名、坑的关键词）。
• 正文只求信息传达：一行到几行、≤120 字，能压缩就压缩；不写过程、不写聊天记录、不写「我做了 A 又做了 B」、不写客套与总结套话。
• 不要重复已有内容：先按第三节查过再写。
• 命中计数说明一切：条目被 query / get 命中才会加计数，常被索引的会留下，低分且未保护的会被淘汰——所以别为了保命反复刷查询，那只是噪声；写废话同样会被淘汰。

三、先 query 再 write（避免重复）

1. 写之前先 query（关键词取标题里最可能的词，或 list 看全部标题）。
2. 同标题即更新同一条：write 传 record: {title, text}（或 records: [...]）时，标题相同就更新那条，等于修订；省略 id 且标题是新的才新增。
3. 要改的是同一条内容就别新建条目——先 get 取回原文，改后按同标题写回。
4. 过时 / 被取代的条目用 delete（ids:[…]）清掉，别让库留下自相矛盾的两条。
5. 确实重要、不该被淘汰的条目用 pin（ids:[…], on:true）保护；只在真的关键时用，不要满库 pinned。

四、冲突口径（权威性）

• 与现文件冲突 → 以现文件为准；与数据库记录冲突 → 以数据库为准（mtnode_db 的记录是权威事实）。AI 事实库只是紧凑索引，可能滞后。
• 发现分歧时：按权威来源回答，并在回答里说明分歧（例如「AI 事实库写的是 X，但 renderer/app.js 现在是 Y，按文件为准」），随后把那条条目更新成与权威来源一致。
• 不确认的条目不要当成事实引用；引用时说明它来自 AI 事实库（索引）而不是现文件。

五、库不可用（无绑定画布）

• 工具返回「当前没有绑定画布」= 本轮没有绑定画布，库不可用：如实告诉用户「AI 事实库本轮不可用（没有绑定画布）」，并拒绝凭记忆回答项目事实。
• 库不可用或查不到时不得编造：不要说「我记得 / 一般来说」来填充内容；该读现文件就读现文件。

六、命中计数与淘汰（行为纪律）

• 命中计数（query / get 命中 +1）与淘汰（默认上限 100 条，超出自动淘汰低分、pinned 不动）都由宿主实现，工具只透传——你不需要算分，也不要试图操纵分数。
• 你的行为纪律只有两条：写真正有用的极简条例；不要为了保命反复刷查询（刷出来的命中只会污染排序，帮不了内容质量）。
• 条例被淘汰不是灾难：真正需要的事实仍可从现文件 / 数据库重新取得。

七、与「团队事实库」和 mtnode_db 的分工

一句话：AI 事实库用来「快速知道去哪看」，权威事实仍以现文件与数据库为准；三者的完整规范分别在本技能、团队事实库文档与技能 mtnode-db-facts。