# Personal Understanding > 两档调用。①完整档：当用户谈及自己的经历、状态、感受、家人朋友、学校、决定、长期偏好，或要求记住、纠正关于他本人的信息，或问"我为什么会这样"，包括抒发、闲聊和活动足迹类（游戏攻略、宿舍安置、在读在看）轮次——先以不可变原话保存，再沿"时间主干 survey → 实体/情境 probe → 原话 deep"渐进检索；纯足迹类轮次遵守"足迹纪律"（恰好一条微型记录）。②跳过档：纯技术、吃什么、一次性购物决策等零增值轮次完全不碰档案。默认用中文工作。 - Skill: `caix84476-netizen/personal-understanding` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add caix84476-netizen/personal-understanding` - Raw SKILL.md: https://api.skillmd.com/api/skills/caix84476-netizen/personal-understanding/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: caix84476-netizen (https://skillmd.com/u/caix84476-netizen) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/caix84476-netizen/personal-understanding --- # 个人理解 v2.0 这是一个**本地、可追溯、原话优先、时间主干驱动的个人认知档案**。它用于保存经历、关系、状态和规则，并让模型在需要时能够： - 先从一件经历想起； - 再沿着时间、人物、地点、学校、物品、作品、游戏、概念和生活环境发散； - 回到用户当时的原话； - 区分事实、感受、用户解释、模型推测和未解决问题； - 检查待回访事项是否到期； - 发现矛盾时带着证据和上下文提问。 旧版 `memory/records/` 保留为兼容层。v2 的派生主干位于 `memory/v2/`，不可变会话原话位于 `sources/conversation/`。 ## 两档调用闸门：full / skip 调用本 Skill 前，先判断本轮属于哪一档。两档共用同一个档案库，不建第二层存储。 **第一档：完整档（full）——默认档。** 任务包含个人经历、状态、感受、关系、偏好、决定等实质个人材料，或用户明确要求记住/归档，或个人背景会实质改变建议、取舍、风险提示或行动顺序时，走完整流程：preflight receipt → capture 原话 → survey/probe/deep 检索 → 派生记录 → finalize → session_check。抒发、闲聊、自我陈述类轮次同样属于本档：档案的价值是提供背景和参考，不以"必须给建议"为前提。 **活动足迹轮次（并入完整档，2026-09-03 两档制改革）：** 游戏攻略、宿舍安置、在读在看、装备选型等"消息本身不含实质个人材料、但可沉淀一条活动足迹"的轮次（如"《只狼》怎么打弦一郎"→"2026-09 正在玩《只狼》"、"这本书好看吗"→"在读/考虑读某书"），与实质个人材料走**同一条流程**——capture、读取、闭环一项不可少，不存在免读取的快速建档。此类轮次额外遵守**足迹纪律**： 1. **写入前定向查重（不可跳过，2026-09-03"已入学"误记的制度根源就是缺了这一步）**：按足迹关键词做定向 probe/routing 查询，核对两点——(a) 档案里是否已有覆盖同一足迹的 current 记录：已有则不新建，需要刷新就沿既有记录做版本链更新；(b) 待写内容是否与既有事实或既有边界相矛盾：档案内任何"不得把 A 写成 B"类状态告诫（如"已录取"不得写成"已入学"）逐条核对； 2. **恰好一条微型记录**：通过查重后写 `tier=light`、`salience` 0–1 的微型派生记录（带 `capture_id` 回链），不拆多条、不生成假设或待回访、不把单次咨询升级成决定； 3. **零新增可体面收场**：查重确认既有记录已完全覆盖、无任何增量时，以 `no-derivation-needed` 收尾，reason 必须写明命中的具体记录——这是合法闭环，禁止为闭环制造噪声记录； 4. 查重翻出档案内部矛盾时留证不断言；发现待写内容实际包含多条独立事实或需纠正既有记录时，按完整档正常语义拆分处理（不再是"升级换档"，只是同一档位内的派生深度变化）。 **第二档：跳过档（skip）——完全不碰档案。** 明显无关、或记录后对未来对话质量增益为零的轮次：纯技术（代码、配置、排障、MCP、插件、仓库维护）、"今天吃什么"、"帮我看看买哪个"这类一次性购物决策、"这东西怎么样"这类无后效的评价请求。不做 survey，不捕获消息，不建派生记录，也不为了审计保存副本。判定标准与完整档的足迹轮次互补：一次纯咨询 FAQ 若查重后无增量，宁可 skip 或零新增收尾，不往档案里倒噪声。护栏：内容分类已经检出个人材料的轮次不得用 `tier=skip` 压制——那是完整档的轮次；压制行为会留痕在 receipt 的 `reasons_suppressed` 字段，事后审计可查。 **轻量补记档（light）已废除（2026-09-03）。** `preflight` 的 `tier=light` 枚举仅为兼容保留，收到时一律按 full 处理；不再声明 light。废除理由：其"免读取"省下的少量 token 远低于引入的复杂度与事故率（盲写误记、`light-tier-requires-derived-record` 查重死锁、回答无法利用档案背景），活动足迹轮次并入完整档并受足迹纪律约束。记录层的 `tier=light` 微型标记（salience 0–1）保留，仅表示记录形态，不再表示档位。 维护本 Skill 的边界规则本身不属于个人材料；应直接修改 Skill 规则，不要把维护对话归档。全局聊天语气、编程语言偏好、工具偏好和方案拷问行为属于宿主客户端的指令文件，不属于个人档案。不得把这些客户端配置决定捕获或派生成个人事实。 ## 最高优先级：原话保真 **只要用户在任何形式、任何场景补充个人理解 Skill 的内容，必须先把用户完整原话一字不改保存，再做任何摘要、事件拆分、人物提取、关系判断或因果解释。** 执行顺序固定为： ```text 用户原话 / 原始附件 ↓ 先保存，不可覆盖 verbatim fragment ↓ 事件、实体、情境卡、状态、待回访、假设 ↓ 检索与回答 ``` 必须遵守： 1. 文字输入保存完整用户消息，不只截取模型认为重要的句子； 2. 图片、音频、文件保留原始附件；OCR、转写、摘要都是派生内容； 3. 每份原话有 `utf8_sha256`、捕获时间、会话标识和来源路径； 4. 原话捕获一旦存在，不得静默覆盖；纠正只能新增捕获和关系； 5. 任何模型摘要都不能冒充用户原话；旧版只有摘要的记录必须标成 `summary_only`； 6. 原话捕获失败时，必须报告失败，不得假装“已经存好了”； 7. 先用 `scripts/preflight_context.py <完整消息> --turn-id ` 或 MCP `personal_preflight_turn` 创建同一轮的 receipt；再使用 `scripts/capture_user_update.py --turn-id ` 或 MCP `personal_capture_user_turn` 完成捕获。文字 capture 的 SHA256 必须与 receipt 的完整消息一致； 8. 使用 `personal_add_record` 写派生记录时，当前用户补充必须带 `capture_id` 或 `verbatim_refs`，禁止继续用裸 `current-conversation` 冒充原文。 ### 派生闭环：捕获成功不等于档案更新完成 `capture` 成功只代表原始材料没有丢失。它会在 `memory/derivation-ledger.json` 中进入 `pending`，仍然必须完成语义拆分、链接和关闭。 每次准备回答前，当前轮所有个人材料捕获必须满足以下一种状态： - 已创建全部必要的事件、实体、状态、偏好、规则、情境或候选解释记录，并用 `scripts/finalize_capture.py --disposition derived` 或 MCP 工具 `personal_finalize_capture` 关闭； - 经查重和语义检查后确实没有新增信息，用 `no-derivation-needed` 关闭，并写清具体原因。 硬性约束： 1. 禁止在仍有当前轮 `pending` 捕获时声称“已经录入”“已经融入”或结束答复； 2. `derived` 至少要有一条可验证的 capture→record 双向链接； 3. 一条原话包含多个独立事件、人物、时间纠正、偏好或状态时，必须逐项判断并拆分，不能只建一张笼统摘要卡应付； 4. 单独的确认、纠正和上下文补充可以与同一派生记录关联，但仍要逐条 finalize； 5. 图片、音频和文件与文字遵守同一闭环；附件用 `scripts/capture_attachment.py` 保留原件并登记哈希； 6. 精确重复附件可以复用已存原件，但本次 capture 仍需登记，并以具体查重理由关闭； 7. `scripts/validate_memory.py --require-closed-captures` 必须能阻止孤立捕获、未跟踪捕获和未完成派生混入完成态； 8. 历史材料的事件日期、材料写作日期、回忆日期和本次录入日期必须分开，禁止把录入当天冒充事件发生日。 ## 事实层级 所有内容按以下层级处理： 1. **用户原话事实**：用户第一人称明确说出的经历、状态、感受、偏好、纠正和规则； 2. **用户对材料的评价**：用户说某份分析不对、某人不是某账号、某个方案只是咨询等； 3. **用户自己的解释**：用户对原因、意义、关系和未来的解释；仍保留为用户观点，不自动变成客观事实； 4. **模型候选解释**：模型根据多条记录提出的模式或因果假设，必须单独放在假设层； 5. **无法确认的内容**：保留来源和缺口，不凭空补全。 用户刚刚说的内容优先于旧档案。旧事实不能被静默擦掉；新内容应建立 `supersedes`、`contradicts` 或纠正链。 ## 统一记忆权重：只有一条轴 事件性质和记忆权重不是一回事，但不能再搞两套“重要性”标准。 - `entry_kind`：事件、状态、决定、事实等，表示它是什么； - `salience`：它在未来理解用户时有多大依赖价值，唯一采用 0–3 轴： - `3 主轴`：改变长期理解、多个领域或人生方向； - `2 关键`：明显改变某条生活线、当前决定或关系过程； - `1 关联`：提供背景、连接或反例； - `0 提及`：只作为名字或细节出现。 `主轴/关键/关联/提及`是同一个尺度的显示标签，不再另设“核心事件/重要事件/背景事件”第二套分类。旧记录迁移时的权重只能标记为 `imported heuristic`，不能伪装成用户亲自评定。 ## 时间主干 时间主干是档案的第一条脊柱，但不是把人生强行写成一篇传记。 每条时间条目尽量保留： - `date_start`、`date_end`； - `date_precision`：日、月、年、约略、相对顺序、未知； - `date_basis`：发生时间、回忆时间、来源时间或模型推断； - `phase`：童年、初中、高中、大学过渡期等； - `salience`：唯一记忆权重； - `entity_refs`：人物、学校、地点、物品、作品、概念和环境； - `before_ids`、`after_ids`； - 原话片段和旧摘要片段的保真度。 禁止把记录创建日期当成事件发生日期。日期不确定就写不确定，不能为了让时间线好看而造日期。 ### 总览怎么概括 总览采用**事件优先、体验跟随、当前状态单独叠加**的结构： 1. **人生主干**：先展示改变生活线的主轴/关键事件，不用一段宏大叙事概括用户； 2. **事件展开**：每个事件可以展开“发生了什么、用户当时感受、用户如何解释、后来产生什么影响”； 3. **当前状态**：单独展示当前内核、现实处境、感受负荷、正在拉扯的决定和下一检查点； 4. **证据入口**：每个判断都能跳回实体、情境卡、事件和原话。 因此不是“侧重事例”或“侧重感受”二选一：时间主干以事例为骨架，感受和意义是事件的展开层，当前状态再单独提供一个短而有信息密度的快照。 ## 实体档案：人物不是孤岛 任何被用户明确指涉、并且在当前内容中承担一点作用的对象，都可以建立一个轻量实体档案；不因为它是路人就省略，也不因为资料少就编造长篇内容。 实体类型不限于人物： - `person`：人物、亲属、朋友、同学； - `group`：班级、球队、社群； - `school_or_organization`：学校、大学、机构； - `place`：城市、住处、球场、工作地点； - `object`：电脑、耳机、足球鞋、设备； - `book_or_work`：书、小说、作品、文章； - `game_or_media`：游戏、视频、音乐、账号内容； - `concept`：概念、价值、理想、制度； - `environment`：家庭环境、学校氛围、生活条件、制度环境。 ### 模糊代词怎么处理 “单纯的模糊代词”指： - 用户只说“他/她/那个人”； - 当前消息和可回读上下文都不能确定指向谁； - 也没有足够信息建立一个稳定的名字或角色。 这种情况下不创造一个假人物，也不写“未确认实体”这种模型看不懂的垃圾节点；把这段原话挂在事件的 `unresolved_referent` 上，保留原文，等用户之后明确指向再补进正式档案。 只要身份能从上下文确定，即使只有一句话，也创建一个短档案。路人档案可以只有几句话，这不构成浪费。 ### 档案内容和冗余 实体档案不手抄一份重复传记。采用： - **事实只保留一份**：原话和事件是 canonical source； - **实体页是投影**：展示所有相关故事和原话入口； - **实体正文不写可变状态**：拥有/未拥有、在读/毕业、已购/愿望单这类会变的断言一律放进挂靠的 `state` 记录，由 `update_state.py` 走版本链刷新；实体页靠投影自动反映最新状态，往实体正文写状态断言等于制造永不更新的僵尸信息； - **情境卡是交叉入口**：展示某个实体在特定关系/地点/阶段中的共同故事； - **交叉连接不删除**：人物档案必须保留与其他人物、学校、地点和环境的连接； - `identity_note`、时间跨度等只是检索元数据，默认不占据档案正文，除非它们本身影响理解。 一个人的档案可以谈他身边的人，因为社会关系本来就是这个人的一部分。连接保留，同一事实通过链接和情境卡回到同一个 canonical 片段。 ## 情境卡：解决“学校 × 足球”问题 实体档案之外增加 `facet` / `context card`。 例如： ```text 学校实体 足球实体 学校 × 足球情境卡 ``` 学校档案可以跳转到这张卡，足球档案也可以跳转到同一张卡。卡片里面放共同事件、共同人物、地点、物品和原话入口，不复制一份假的“学校足球故事”。 情境卡的边界按共同故事形成： - 同一事件中共同出现； - 有明确关系或空间连接； - 有共同的用户体验或决定； - 有助于解释当前问题。 如果只是偶然共现，不自动写成因果关系；但也不因为“跨领域”就删掉。相关性由事件、时间、实体和用户体验共同决定。 ## 当前状态 当前状态不写成一句空话，也不写成长篇传记。默认使用五块： 1. **个人内核**：当前仍在起作用的价值、边界和决策倾向； 2. **现实处境**：正在发生的生活事实和资源条件； 3. **体验负荷**：用户明确表达的情绪、能量、身体感受和压力； 4. **开放张力**：尚未解决的决定、冲突、反例和不确定性； 5. **下一检查点**：待回访、期限、需要新证据的地方。 每块先给 1–3 个高密度条目，附带可展开的重要事例和原话，不用只留内核，也不用把所有事例塞进首页。 ## 待办与主动回访 模型提出的问题、用户提到的“等几天看结果”、对方尚未回复、等待决定或待确认事项，必须进入 `memory/v2/followups.jsonl`，至少包含： - 原问题或待确认事项； - 具体上下文； - 创建日期； - `due_at` 或明确的 `due_rule`； - 当前状态； - 来源； - 上次检查时间； - 解决结果或后续记录。 每次运行个人理解 Skill 时，先检查已到期和临近到期（默认 3 天窗口）的待回访。到期后主动提问，但提问必须带上下文： ```text 你在某日提到：…… 当时约定/预期是：…… 现在已经到检查时间了。 这件事后来怎么样？ ``` 回访必须有正规关闭通道（2.5.0 §6.3），不要用"放着不管"代替关闭：用户回复了用 `answered`，用户明确不再跟进用 `declined`，方案被后续决定取代或本就过时用 `resolved`；三种都要 `note` 写具体依据。CLI 走 `followup_check.py --resolve --resolution --note "<理由>"`，MCP 走 `personal_resolve_followup`。当用户的回答本身就是一条新原话时，先 capture 再把该轮 `capture_id` 传给 resolve（可选参数，须已存在于 ledger），把用户原话直接绑在回访上；declined/resolved 通常没有新原话，不传即可。被取代或作废的回访若不关闭会持续污染对话入口和到期清单。 如果发现当前消息和档案存在矛盾，也要把冲突的两条事实、日期、来源和差异列出来，再询问用户；禁止没头没尾地突然追问。 ## 引导开场：用户不知道要讲什么时 有些用户面对一个空档案会僵住。当用户问"我该讲些什么"、表现得不知从何说起，或档案刚初始化时，运行 `python scripts/conversation_starters.py`（JSON 输出），挑**一条**开场建议——排序为：到期回访优先，其次最空的领域——用你自己的话温暖地问出来。 - 绝不把整张清单当审问一次抛出；一次只给一条提示，等用户回答，然后像任何一轮一样捕获原话； - 建议必须来自档案的真实空缺（空领域、开放回路、过期状态）——绝不编造心理学判断； - **"档案里没有 X"是一个需要证据的断言（2026-09-06 实测教训）**：无论场景是开场建议、回填清单、还是"这个内容档案查无、请你补原文"式点名，说出这句话之前必须先对 X 做定向 probe（用 X 的话题关键词，不是用户材料的标题原句——标题是别人起的，不代表档案的收录措辞），空手才许出口。实测反面案例：150 条标题清单靠脑补分诊，把忧郁小王子/硬盘故障/做饭难吃三条 probe 一发即中的既有记录判成"档案查无"，用户被迫人肉贴原文。档案的标题、目录、直觉印象都不算证据，probe 空手才算； - 用户回答后，回归正常流程：捕获 → 派生 → 回答。 ## 回答前硬闸门（不可跳过） 只要当前用户消息包含个人经历、状态、感受、自我评价、关系、决定、纠正、长期偏好，或要求解释“我为什么会这样”，必须先通过**内容优先**的 preflight 创建当前轮 receipt，再把**当前这条完整用户消息**作为一份新的 immutable capture 保存成功后，才能执行 survey、probe、deep、派生记录、因果分析或回答。不能用上一轮 capture、旧摘要、`current-conversation` 或模型记忆代替。 内容分类器是关键词启发式，两层触发（2.5.0 §8，2.6.1 §4d 修正）：第一人称+标记词（"我+任何经历/状态词"），以及**强情感词触发**——中文常态省略主语，"有点烦""挺焦虑的""心情很差"这类抒发/状态轮次没有"我"字也要召回；带"我"字的强情感句（"我堵得慌""我社死了""我诸事不顺"）同样召回（旧版把强情感词挂在"无主语"分支下，第一人称情感句两头落空，实测是"四连漏"的主因，已修）。技术语境否决保持：句中含 python/代码/配置/报错等词时强情感词不触发，"这个 bug 烦死了""写代码写得心累"仍是技术轮。此外开了一个形态槽兜住词表枚举不尽的框架：`X得慌`（闷得慌/憋得慌，身体需求饿/渴/撑除外）。诚实边界：纯枚举仍不可持续——"兵役登记搞完了"这种省略主语的生活事件陈述、"最近状态不太好"这种弱词组合，关键词表按定义抓不全，**兜底责任在模型**：判断为个人材料就在同一 turn-id 上重声明 `--tier full`（2.5.0 §8.1 后同 id 升级即时生效，不再返回假 receipt）。 **实测已知的漏型清单（2.6.1 三轮泛化测出，模型兜底时优先怀疑这些形态）**：以事件陈述包裹的情绪（"兵役登记搞完了"）、"状态/感觉"类弱词组合、以及情感词藏在第一人称之外的新口语形态（形态槽只覆盖 `X得慌`/`干啥啥不行`/`哪哪都不对`，其它靠补词或模型兜）。规则不变：**凡是"这句话里有人的温度"就按完整档走**，判错方向宁可多 capture（no-derivation 收场无成本）也不要漏 capture（用户原话永久丢失）。 执行顺序固定为： ```text 内容优先 preflight receipt → capture（绑定 receipt，回读校验） → survey/probe/deep → 派生记录/假设 → finalize → session_check --turn-id → 回答/声称已更新 ``` receipt 是可审计的事实，不是让模型参考一下的提示：`requires_personal_understanding=true` 时，capture、finalize 和 `session_check --turn-id` 缺一项即 fail closed。若捕获失败，停止个人理解相关分析，明确报告失败原因；不得继续回答后再补录。若捕获成功但尚未形成派生记录，回答中必须明确区分”已保存原话”和”尚未写入经历/状态卡”，不得把原话捕获说成档案已经完整更新。 这条闸门适用于直接提及个人档案、skill、记忆、原话或“记住”的消息，也同样适用于把个人经历、状态、感受、关系、偏好或决定包在改写、润色、翻译、总结、看图审阅任务里的消息。任务外形不能覆盖个人材料。纯技术、配置、排障、项目维护和本 Skill 规则维护属于跳过档，不创建 receipt、capture 或派生记录（见“三档调用闸门”）。 **历史 light receipt 的兼容处理（2026-09-03）**：两档制改革前遗留的 `tier=light` receipt 按完整档闸门处理——`light-tier-requires-derived-record` 门禁已从 `turn_receipts.py` 移除；遗留 light 轮次以 `no-derivation-needed` 收尾属合法闭环，但 reason 仍须写明查重命中的既有记录。凡回答涉及用户个人背景，引用的档案细节必须来自本轮实际检索；没读过的内容不进回答，凭校验输出等边角碎片臆断档案内容比不提更糟。 ### 低信号快速通道（完整档内部） 被内容判定为个人材料的低信息量消息（“有点迷茫”“说不上来”，见 `scripts/preflight_context.py` 的 low-information 判定）同时受两份契约约束：回答要自然（见低信号响应契约），闸门又要求先捕获。单独一个“唉”不会自动进入档案。为避免把聊天变成检索现场，低信号个人轮次按以下顺序执行： 1. **capture 立即执行，不可延迟**——原话保真没有例外； 2. **读取降级**：不跑完整 survey，直接用 preflight 输出里的到期回访 + 当前状态快照挑一个最可能的入口；确有必要才做一次小范围 probe； 3. **回答优先**：像熟人聊天一样直接开口（一两个细节，说完就停），工具调用控制在 capture + 至多一次轻读取； 4. **finalize 收尾**：回答之后的同一轮内完成派生或 `no-derivation-needed` 关闭，并运行 session_check；若用户连续追问转成实质内容，则升级为完整流程。 快速通道放宽的是读取和派生的时序，绝不放宽原话捕获和闭环本身。它服务于**已含个人材料的消息**（只是信息量低），仍按完整档做语义拆分；与之相对，**不含实质个人材料**的活动足迹轮次走完整档的足迹纪律路径（见两档调用闸门）。 ### 读取入口与 MCP 优先使用 MCP 工具（`personal_catalog`、`personal_retrieve`、`personal_session_check` 等）读写；它们带读取前捕获校验。**足迹/攻略类消息被 capture 闸门拦下时的只读降级（2.6.0）**：内容分类器把"只狼怎么打""书荒求推荐"这类足迹消息判为 non-personal 时，写入照旧被拦，但可以用 `personal_retrieve` / `personal_catalog` 的 `maintenance: true` 做只读读取（有 trace 审计；等价 CLI `--maintenance`），随后模型仍应按足迹纪律在同一 turn 上用 `tier=full` 重声明补 capture——只读通道解决的是"读不到档案"，不是"免捕获"。若当前会话工具列表里没有 `personal_*` 工具，说明本客户端尚未注册本地 MCP 服务：运行 `python scripts/install_mcp.py --auto`（幂等，可重复执行）完成注册后提示用户重启会话；注册前仍可用 CLI 脚本完成同样的工作——但 CLI 读取同样遵守"先捕获再读"（2.5.0 §6.5：`retrieve_v2.py`/`catalog_context.py` 需 `--capture-id`，与 MCP 一致），无对话轮次的维护/测试/审计读取显式声明 `--maintenance`。注意：如果本机存在多份 skill 树（备份、沙盒、粘贴副本），从副本运行 `--auto` 时若旧注册树仍在磁盘会被 §6.6 防劫持护栏拦下并拒绝改注册，确认要切换须显式 `--force`（这防止把用户真实注册静默重指向测试树）。 ## 检索流程：不是把所有东西读完 v2 的检索不是“先把整个档案库塞进模型”，也不是只搜关键词。它是三层发散： ### survey：看全局地图 只读紧凑目录，不读原话全文： - 时间主干； - 当前状态； - 实体目录； - 情境卡目录； - 待回访； - 因果假设目录； - 资料缺口和审查警告。 survey 是紧凑路由地图，不含旧记录全量列表；需要按领域展开旧目录时用 `catalog_context.py --view routing --query <消息>`，需要完整目录时用 `--view full`。 因果假设按需携带（2.5.0 起，检索层闸门）：survey 和 probe 里假设默认只显示 id/status/confidence 存根，只有当轮消息的内容词真实命中假设文本时才带出 claim/scope/mechanism。因此**当用户的问题是在求解释（"为什么我会…"）而存根 id 又看着可能相关时，主动用 `personal_catalog --view full` 或把用户的因果措辞原样放进 `--query` 读完整假设**；普通事实问题不要为凑数去翻假设。 ### probe：从入口发散 模型选择一个或多个入口： - 事件； - 实体； - 情境卡； - 当前状态； - 待回访； - 候选假设。 然后读取入口的派生卡片，并扩展： - 事件前后时间邻居； - 事件涉及的人、地点、学校、物品、作品、概念和环境； - 这些实体共同出现的情境卡； - 支持、反驳、替代和 supersede 关系。 这些扩展只读取必要范围，同时保证细枝末节有卡片可达，减少关键小人物漏召回。probe 输出的每条时间条目带 `evidence_fidelity` 保真计数（逐字/摘要债务各占多少）；用摘要债务支撑的说法要向用户说明"这一段来自旧摘要，不是原话"。每次检索的决策轨迹会追加到 `memory/v2/traces/`，漏召回和误归属时用它回放检索过程。 probe 与 routing 共用同一套加权排序（2.4.1 起，2.5.0 起为 weighted-idf-4-anchor，2.6.0 起加权词元经过档案词表净化）：IDF 稀有词加权（"只狼""猫学派"这类短专有名词权重高，烂大街单字权重接近零）+ 长度归一（超长记录不再靠字数霸榜）+ 实体别名路由（命中实体的时间条目获得反哺加权，如"哥哥 家里"→哥哥冲突）+ 单字实体别名豁免（"妈""她"这类档案别名不按噪音降权，口语查询可直接触达家族簇）+ 内容词入选门槛（只被非别名单字偶然命中的记录不占检索名额，杜绝"防/钱/状态"式捞偏）+ 锚定比值降权（记录得分乘以"它命中的最强词重 ÷ 查询最强词重"：只靠大路词上榜的长记录被按比例压下，命中查询稀有决定词的记录不受影响；查询本身没有稀有词时退化为原行为）+ 词元净化（2.6.0：查询切片先过 `resources/lexicon` 词典——vendored jieba 词典 + 档案自训练词表 `memory/v2/archive-lexicon.json`，档案里 DF≥2 的字段自动成词，冷门专名靠档案自训练；词典外切片权重 ×0.4 封顶——保留召回但不再当锚定，跨词假切片如"郎我"不再霸榜；"巫师3""晕3D"这类中英混写专名自动粘连成整词；ASCII 单字符（如"巫师3"拆出的"3"）不再具备内容词资格）。因此短词游戏名等查询的漏召回已修复，定向查重直接按足迹关键词 probe 即可；routing 仍是按领域浏览的全量地图，供查不到关键词时兜底。诚实边界：**probe 的契约输入是足迹关键词**——把整句原话直接当 query 时，锚定降权可缓解不可根除；模型侧先提关键词再 probe，routing 才吃整句。 ### associations：联想检索通道（2.6.0） probe 输出里有一个独立的 `associations` 段：个性化 PageRank 在档案图上扩散（种子 = 本轮查询实际命中的实体与概念卡），带出**词面零重叠**的候选——例如用户抱怨"打击感烂"时应想到"巫师3 骑马手感"记录（两个词面无交集，靠概念卡 `entity.concept.gameplay-feel` 中转）。使用契约： 1. **它是候选池，不是排序结果**：每条带 `via_entity` 图路径与 `spread_score`，模型必须自己判断联想是否成立再引用；经枢纽封顶（mention_count>30 的泛枢纽不做中转）与去重（不与 timeline/knowledge 重复）。 2. **绝不混入 timeline**：词面通道管精确回忆，联想通道管发散；两者分开呈现，审计时 via 路径可回放。 3. **概念卡是它的地基**：`entity.concept.*` 卡（操作手感/叙事体验/品味锚点/金钱自主/消费纪律/家庭边界/考公路径/身体限制等）的 aliases 覆盖口语入口词（"书荒""晕3D""考公""史低"）；新概念出现时按实体卡流程开卡挂链，不要让联想层退化为共现随机游走。 4. 宽泛兴趣问题（"书荒了""最近好无聊"）若实体零命中，associations 会经由概念卡 aliases 自动获得种子；仍无种子时按"冷回溯"阶梯与实体目录 routing 兜底，**禁止宣称"档案里没有"**。 ### 聚合读法：侦探拼图（2.6.1） 宽泛决策问题（"我该怎么办""我是个什么样的人""这条路值不值"）不是单入口 probe 能答的。像警察拼案情：**多条模糊线索摊在桌面上，拼出完整画像**。执行方式是对既有 probe 的编排，不新增机制： 1. **多入口并发**：按线索词拆 2-4 个 probe（情绪线、利益线、人物线各一发），每发用该线的足迹关键词； 2. **跨域收集**：允许每条线各取 timeline/knowledge 前排 + associations 的强候选（via 清晰者），**entities 段命中的概念/实体卡也算跨域信号**（卡是挂靠边的入口，P5 实测考研场景：决策卡 career-exam-route 经路线线 entities 首位可达，只看前三段会漏掉它），禁止单通道凑数； 3. **ids 精读**：把候选中直接相关的记录用 `ids` 参数精读（deep），核对原话； 4. **拼图输出**：回答里区分"档案事实""模式观察（多条记录的共同点）""模型推断"三层，推断层注明依据了哪几条记录——禁止把单次事件升格为人格定论。 ### 工具与模型的分工契约（懒惰悖论的答案，2.6.1） 词典、IDF、PPR 这些检索层机制的职责边界，回答了"工具这么强模型还用不用自己判断"的张力：**工具把召回的体力活做厚（候选捞全、切片净化、宁滥勿漏），判断与拍板永远在模型**。衡量标准不是"模型还用不用自己想"，而是**模型思考时的起点质量**——前排候选有多干净、被扣下的候选有多可解释。因此： - 模型**必须**自己提关键词再 probe（工具不给判断，只给候选）；整句直查只在 routing/时间窗场景合法； - 模型**不必**替工具干活：不要手工过滤 n-gram 假切片、不要人工重算 IDF——这些是检索层的责任，发现问题报给维护轮修机制，而不是在回答里绕过； - 前排有噪声时不静默吞下：按 trace 说明"为什么它会出现、为什么不采信"，让下一轮修复有据可查。 ### deep：回到原话核验 只有当回答需要精确事实、时间、归属、矛盾、人物关系、用户原意或因果解释时，才读取对应原话片段。旧摘要只能作为摘要债务，不能在 deep 阶段伪装成原文。 ### 冷回溯：想不起关键词时 用户说"我忘了""好像以前聊过类似的事"时，不要求他提供关键词，也不宣布"查不到"。按阶梯下降： 1. 从已提到的任何人物、地点、物品、时间线索做 probe，顺实体和 facet 发散； 2. 命中任意条目后，沿 `before_ids`/`after_ids` 时间邻居向前后走； 3. 仍无命中时，用 `retrieve_v2.py --window 2025-03`（或 `起:止` 区间）按时间窗浏览标题，像翻老相册一样扫过候选，让用户认领； 4. 时间也说不准就按 phase（童年/初中/高中/大学）逐段扫主轴。 降权到提及级的记录同样在实体、关键词和时间窗三条路径上可达；降权只把它移出常驻地图，不把它变成不可达。 ## 因果解释层 因果解释是独立的大工程，不在普通事实检索里自动乱跑。候选假设至少包含： - `claim`：解释什么； - `mechanism`：通过什么过程发生； - `supports`：支持证据； - `contradicts`：反例或限制； - `alternatives`：竞争解释； - `scope`：在哪些时间、场景和关系里成立； - `confidence`：置信度； - `status: candidate`：默认候选，不能当作事实。 触发条件： 1. 用户明确问“为什么我会这样”； 2. 多条独立经历跨时间重复出现同一条件—反应—适应链； 3. 深度回顾发现多个模型互相依赖； 4. 当前决定确实需要比较不同成因。 生成步骤： ```text 候选模式 → 机制草图 → 支持证据 → 反例/限制 → 竞争解释 → 用户确认/继续观察 ``` 单次事件不能直接生成稳定因果。因果假设只有在当前问题需要解释时才进入深读；普通事实问题不自动加载它。 ## 隐私边界 用户已明确允许本地 Skill 在相关时正常读取 private / highly-private 内容。敏感度不再作为隐藏、降级或归档理由。 但相关性过滤仍然保留： - 个人资料会改变答案时，敏感内容按相关性读取； - 无关问题不主动泄露无关私密材料； - 原话、档案和来源只在本地 Skill 目录处理； - 外部聊天、第三方分析、OCR 和模型分析仍不能自动当作用户事实。 放宽隐私读取，不等于取消边界；否则不是更懂用户，是把档案当垃圾桶倒进每个回答。 ## 深度审查和结构校验 结构校验不再只输出“通过”。`scripts/validate_memory.py` 有三种结果： - `clean`：没有错误或警告； - `warnings`：结构可用，但存在摘要债务、来源缺口、日期缺口、待回访或实体连接问题； - `failed`：存在哈希错误、重复 ID、孤立引用、关系环、损坏 JSONL 或不可接受的 schema 错误。 严格模式 `--strict` 会把警告也视为失败，适合迁移验收。 `review_v2.py --deep --json` 用于生成语义审查包，重点检查： - 原话与事件是否一致； - 人物/学校/地点/物品是否归属正确； - 共同故事是否被错误删掉； - 时间顺序和“后来回望”是否混淆； - 事实、感受、用户解释和模型假设是否混层； - 旧摘要是否被错误当成原话； - 因果假设是否有支持、反例和范围； - 待回访是否到期、是否已经解决。 深度审查可以输出警告和资料缺口，但不能凭空补写丢失的原话。结构干净不等于语义正确；审查必须有风险报告。 ## 维护入口 - `scripts/capture_user_update.py`：先保存完整用户原话（超长消息优先用 `--stdin` 或 `--file`，避开命令行长度限制）； - `scripts/preflight_context.py` 与 `scripts/turn_receipts.py`：创建、读取和审计不可变的 turn receipt； - `scripts/capture_attachment.py`：保存或按 SHA256 精确去重原始附件，并登记 pending； - `scripts/derivation_ledger.py`：维护 capture→records 状态和链接审计；`--repair` 可由 immutable capture metadata 和 record 引用重建投影； - `scripts/finalize_capture.py`：完成派生或记录“无需派生”的具体理由； - `scripts/catalog_context.py`：v2 全局 survey； - `scripts/retrieve_v2.py`：v2 probe/deep； - `scripts/followup_check.py`：待回访检查； - `scripts/review_v2.py --deep`：深度结构/保真/语义准备审查； - `scripts/validate_memory.py`：失败、警告、干净三态校验； - `scripts/session_check.py --turn-id `：回答或声称"档案已更新"前的硬闸门（receipt + 结构 + 派生闭环 + v2 完整性，失败退出码非 0）； - `scripts/salience_review.py`：季度记忆权重复盘，把长期未确认的导入权重降为提及级（见 `references/review-and-feedback-loops.md`）； - `scripts/record_feedback.py`：记录依赖个人记忆的回答效果（helpful/missed/corrected），`review_v2 --deep` 汇总常被纠正的记忆（见 `references/review-and-feedback-loops.md`）； - `scripts/rebuild_views.py`：重建旧版兼容视图、v2 派生视图与档案自训练词表（`memory/v2/archive-lexicon.json`，2.6.0 起每次重建自动刷新，供检索词元净化使用）； - `scripts/pipeline_view.py`：一轮对话的管线时间线（receipt → capture → 派生闭环 → 检索 trace 的一页只读回放，2.6.0；`--turn-id X` 或 `--latest N`，HTML 输出到 dashboard/，同时是审计与验收工具）； - `scripts/backup_archive.py`：生成带 SHA256 清单的本地备份，并自动镜像到 `memory/backup-config.json` 指定的第二位置（见 `references/maintenance-and-durability.md`；重要更新后、迁移前、至少每周一次）； - `scripts/init_archive.py`：全新安装时初始化档案骨架（目录 + 通用领域分支），首次使用前运行一次（幂等）； - `scripts/install_mcp.py`：检测本机各 AI 客户端并注册本地 MCP 服务（幂等；换机器、粘贴 skill 到新客户端后运行一次即可；若检测到多份 skill 树并存，改注册受 §6.6 防劫持护栏约束，须 `--force` 显式确认）； - `scripts/mcp_server.py`：本地 MCP 读写入口； - **弃用兼容层（勿作读取入口）**：`scripts/query_context.py`（旧 core/evidence 结构 + 英文触发词的 legacy proactive cues）、`scripts/retrieve_context.py`（2.0-compat 检索接口）。它们与 v2 不是同一套，只为回归调试保留，读取一律走 `catalog_context.py` + `retrieve_v2.py`；`references/proactive-cues.json` 是英文触发词且默认关闭，任何人要重新启用须先翻译成中文，否则匹配不了中文输入。一个发布周期确认无依赖后可整层删除。（注意：`review_context.py` 不是这一层——它是 review 系统 `review_skill` 的活依赖，别误删。） - `dashboard/`：v2 可视化面板。 ### 维护原则 - 先完成当前任务，再做非紧急维护； - 但用户纠正、原话捕获失败、人物归属错误、结构损坏、待回访到期和临近决策必须及时处理； - preflight / session_check 输出里的 `maintenance` 提醒是唯一需要看的维护状态：备份超期（`backup.due: true`）时，当前任务完成后先运行 `scripts/backup_archive.py` 再结束会话；依赖个人记忆的回答出现用户明确纠正/确认时，按 `references/review-and-feedback-loops.md` 记录反馈（写不出原话证据就不记录）； - 永久删除必须由用户明确指定； - 旧摘要不删除，标记为迁移债务； - 新档案不覆盖旧档案，使用版本链； - 所有 writer（CLI、MCP、ledger、重建）共享进程间锁，并以原子 replace 落盘；写入一律在锁内基于最新磁盘快照读取、合并、提交。禁止从旧 JSON/JSONL 快照覆盖其他 Agent/MCP 已写入的数据； - 不把用户一句自我评价直接升级成人格定论； - 不为了让图谱好看而制造因果边、合并人物或填补时间。 ## 可视化审计契约 面板的任务是让用户检查 Skill 是否按规则工作。首页只提供状态入口和数量入口；详细内容进入对应的时间、实体、情境、来源、待回访和诊断页面。 诊断页必须能看到： - `SKILL.md`、references、scripts、memory/v2 的真实文件入口； - 原话捕获、片段、时间条目、实体、情境卡和检索层级的实际数量； - `clean`、`warnings`、`failed` 的机器校验结果； - 旧摘要债务、日期缺口、实体归并、关系未解析和候选假设缺口； - 从事件跳到实体、情境、知识卡、前后条目和原话来源的完整链路。 任何列表点击都要使用自己的 ID。禁止把多个条目绑定到同一个默认目标。实体重定向要显示旧 ID、canonical ID 和归并来源。