lume-dsh-plugin 0.7.4 → 0.8.0

package/README.md

@@ -1,384 +1,354 @@
-<div align="center">
+# Lume · 微光
 
-# Lume（微光）
+**不替模型思考，只让它手边的事实到位。**
 
-**DSH Desktop 增强插件。给会话装上两样东西：靠谱的任务执行纪律，和一段真实的关系。**
+给 DSH Desktop 加四样东西——三层能力，加一块仪表盘：
 
-### 能力一：任务执行纪律（自适应协议）
+| 层         | 管什么         | 一句话                                                             |
+| ---------- | -------------- | ------------------------------------------------------------------ |
+| **纪律层** | 这一轮该怎么干 | 判断请求类型、划清"能不能动手"的边界、交付前对账                   |
+| **方法层** | 干活的产出物   | 契约 / 改动台账 / 假设台账 / 设计决策 / 项目知识——可检查、可跨会话 |
+| **仪表盘** | 到底有没有用   | 路由判定、触发器命中、外部结果信号落盘，`lume_metrics` 随时可查    |
+| **人设层** | 用什么风格说话 | 从真实素材蒸馏具名角色，长期记忆与风格随对话演进                   |
 
-约束「如何正确完成任务」，始终生效、不依赖人设：
-
-- **自适应协议分层**——闲聊走短版、任务走完整版、推理型模型走精简版，按请求类型与模型能力分流，不为闲聊支付完整工作协议的 token
-- **意图路由**——问答 / 查找 / 讨论 / 诊断 / 执行五类先行分流：诊断不越权修复，讨论不提前收敛，只有执行才改动状态
-- **证据时效**——引用日志、历史、旧报错前先核对时间戳与因果：历史里存在的错误不等于当前问题的原因
-- **真实工具结果验证**——监听工具成败与结果未知；失败或未知不允许报完成，交付时区分「已验证 / 未验证 / 推测有效」
-- **会话内自愈与复盘回环**——相同请求连续失败自动注入归因纠偏；跨会话聚合反思评分，对持续低分的维度定向提醒
-- **上下文压缩感知**——压缩发生后重锚状态，提醒模型摘要不是完整历史，细节依赖先确认
-- **文档能力感知**——按当前环境探测文档工具：有就要求先读后写、交付前回读验证；没有就如实说明边界，不用文本读取或脚本硬解二进制办公文件
-
-### 能力二：人设系统（人设即人）
-
-塑造「以何种风格表达」：具名角色、长期记忆、随对话演进：
-
-- **素材蒸馏**——从聊天记录、小说、剧本、人物设定文档蒸馏角色卡，语气、口头禅与回复篇幅锚定真实素材统计
-- **长期记忆与生命周期**——事件记忆 + 故事记忆；相对时间的临时记忆自动过期，长期事实不受影响
-- **双向反馈闭环**——负面反馈自动转成风格约定，被认可的回复摘录为语料，语气随使用收敛
-- **记忆星图与角色卡导入导出**——可视化记忆、行内编辑，卡片可分享迁移
-
-人设只影响自然语言表达，不介入任务执行，也不影响代码、命令与工具调用的结果。
-
-[![CI](https://github.com/cayan0x/Lume/actions/workflows/ci.yml/badge.svg)](https://github.com/cayan0x/Lume/actions/workflows/ci.yml)
-[![Version](https://img.shields.io/badge/version-0.7.0-blue)](./CHANGELOG.md)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-
-*人设系统：内置角色卡、蒸馏与管理入口，以及记忆星图*
-
-</div>
+约束**按需注入**：闲聊轮不会背上整份工作协议的成本。人设只影响自然语言表达，不介入代码、命令与工具调用的结果——你选"不使用人设"时，纪律层照样生效。
 
 ---
 
-## 一、任务执行协议
-
-这是可公开复用的工程工作协议，不是模型隐藏思维链。协议注入每个会话；无论选择哪个人设（包括「不使用人设」），都始终生效。
-
-| 层 | 防范目标 | 规则 |
-|---|---|---|
-| **上下文管理** | 上下文衰减 | 保留目标、约束、已完成事项、关键决策、错误与已排除假设 |
-| **任务分解** | 复杂任务失控 | 拆成可验证步骤，优先处理阻塞项和高风险项 |
-| **自适应投入** | 简单问题过度分析或复杂问题草率处理 | 低风险问题快速收敛；复杂、高风险或不确定问题增加调研、比较与验证 |
-| **信息路由** | 在无关内容上浪费上下文 | 优先定位高影响入口和数据流；无依赖的只读检查可并行 |
-| **阶段门控** | 未调研即动手 | 先理解和只读检查，再执行写入 |
-| **变更保护** | 覆盖用户状态 | 修改前完整读取，最小范围变更，保护用户已有改动和数据 |
-| **验证闭环** | 修改后不确认 | 测试、类型检查、构建或最小复现；失败先归因再重试 |
-| **振荡预防** | 修改—回滚循环 | 连续失败后更换方案，不重复已排除假设，不制造假成功 |
-| **结果复核** | 把部分完成说成完成 | 对照需求、边界、兼容性和数据保留，明确已实现与仍有限制 |
-
-### 意图路由与长会话护栏
+## 摘要
 
-协议会先把当前请求归类为五种行为模式，而不是默认把所有消息当成执行命令：
+**在会话里补上"事实到位"这一步。** 它不替模型思考，只让模型手边的事实到位；约束按需注入，闲聊轮不额外加 token。（这一段与[插件市场简介](docs/hub-registration.md)同源。）
 
-- **问答**：直接回答，不擅自改文件或调用写入工具
-- **查找**：先核对来源、已知和未知，不未经授权改变外部状态
-- **讨论**：比较方案、取舍和风险，不把探讨中的方案提前当成决定
-- **诊断**：先给现象、证据、根因和验证办法，不越权修复
-- **执行**：确认目标和完成标准，完成后验证真实效果并检查副作用
+- **纪律层**：按这一句话加最近几轮轨迹判定请求类型（问答 / 查找 / 讨论 / 诊断 / 执行）并划清边界——问答轮不改文件、诊断轮不越权修复；引用本次没打开过的代码行、对没见过的符号下否定断言、需求条目与交付物对不上、把「我没查」包装成「待你定」，都会被当场点出；上下文占用到 75% / 90% 预警并导出结构化会话记忆（目标 / 已拍板 / 未决 / 关键定位），新会话开局注入，续接一句「继续」即可；历史会话（含已撑满聊不动的）启动时自动补蒸馏出跨会话知识，幂等不重复。
+- **方法层（可检查的产出）**：任务契约（目标 / 范围 / 数量先估后回填 / 完成判据 / 非目标）、改动台账（每处改动自动入账并记下验证方式，未验证的条目在交付时点出）、假设台账（含已排除项；下结论必须带证据、裁决方式与反例检查）、设计决策（决策点 / 选择 / 放弃理由 / 影响面）、按工作目录跨会话累积的项目知识（带编号、可点名删除，只收句子并拦截密钥）。
+- **行为触发器（按轨迹纠偏，不看措辞）**：撒网不收敛、连写不验、死路重撞、契约缺失、设计缺失、假设过期、判据漂移、知识未记、未读就改——每条带具体数字，同类两轮内不重复。
+- **仪表盘**：路由判定、触发器命中、块装配与外部结果信号写本机 `lume-metrics.jsonl`，`lume_metrics` 可查触发器效能（口径为命中后 3 轮内出现真验证命令或载具从无到有，明确标注观察性；无机械口径的标未判定且不计入分母）。
+- **人设层**：从聊天记录、小说、剧本、人物设定文档蒸馏具名角色（语气、口头禅、回复篇幅锚定真实素材统计）；以人设为键的长期记忆，以及 30 天后自动过期的临时记忆；纠正自动转风格约定、认可的回复摘录为语料；切换人设后按签名词做词法泄漏检测；记忆星图可视化与角色卡导出导入。
 
-会话达到第 6 轮后，插件才启用短版长会话护栏和“当前目标锚点”：以当前消息和最新状态为准，把旧计划、旧时间、旧事实和助手过去的自述视为候选信息；每次动作都要检查是否生效、是否留下副作用。这样不会给短聊增加固定成本，也能缓解长对话中上下文变长后“越来越笨”的问题。
+---
 
-协议不要求输出隐藏的逐步思考过程；对外只输出与任务复杂度匹配的结论、计划、变更和验证结果。简单问题保持简洁，复杂问题增加必要依据和边界说明。人设只影响自然语言表达，不影响代码、工具调用、结构化输出或安全判断。
+## 它解决什么问题
 
-### 协议自适应与闭环
+_（下面用一个跟你业务无关的小例子：一个自己写着玩的跑步记录 App——单页前端加一个本地 SQLite。）_
 
-任务协议不是一段每轮机械重复的说明，而是会根据会话状态和模型能力动态调整：
+同一个需求：「给跑步记录加个『配速』列，历史数据也要补算」。
 
-- **会话内自愈** —— 当同一用户请求连续两轮出现明确的失败、报错、超时或权限错误信号时，临时追加“先定位根因、记录已排除假设、选择不同方案”的纠偏条款；下一轮成功后自动解除。为避免误判，普通的重复提问不会单独触发该机制。
-- **即时对齐纠偏** —— 用户说“不是这个意思”“你理解错了”或重复提出相近请求时，本轮立即要求先复述目标、检查上一轮是否答非所问，不沿用旧假设，也不原样重复上一轮。
-- **反思回环** —— 会话结束后的协议复盘会保存在本地。最近多个会话中某一项持续低分时，下一会话只注入一条针对性提醒；表现恢复后自动淡出。反思摘要不会把完整历史日志带入上下文。
-- **模型感知** —— 普通闲聊使用短版协议；复杂任务按模型能力选择协议长度。已确认具备推理能力的模型保留变更保护、验证、失败归因和结果复核，减少重复的计划说明；无法确认模型类型时使用完整协议作为安全回退。
+**没有 Lume**：它直接改了列表页那个表格。你问"迁移脚本写了吗"，它说"已处理"——但它从没打开过建表那一份。你出门跑了半小时步，回来换个窗口继续，它又问你"这个项目怎么启动"。上下文撑满以后，进度就留在那个窗口里了。
 
-这三层共同形成“常规协议 → 检测问题 → 临时强化 → 成功解除 → 跨会话复盘”的闭环，在需要深度处理时增加约束，在简单问题上控制 Token 消耗。
+**有 Lume**：
 
-### 文档能力感知（与文档工具插件协作）
+- 开工前把你的原话**逐字**记下来，并落一份契约：目标、范围、**数量先估**（探索后回填实际值）、完成判据、非目标；
+- 每处改动**自动**进台账（不用它自觉调用工具），交付时把**还没验证的条目**列出来，而不是说一句"已完成"；
+- 它引用了没打开过的代码行、对没见过的符号断言"不存在"、把两个需求数成三个、把"我没查"包装成"待你定"——都会被当场点出来；
+- 下结论（confirmed / excluded）要过闸：证据、裁决方式、反例检查三项缺一不可；
+- 换个窗口说一句"继续"，它带上目标、已拍板、未决、关键定位接着干；
+- 觉得"好像没起作用"时，有数据可看：`lume_metrics` 会告诉你这一路的判定、命中与纠正率。
 
-DSH 本身不带 Office / PDF 读写能力：附件只接受图片，工具名册里没有任何文档工具。模型面对 `.docx`、`.xlsx` 这类二进制容器时，只能在“当文本读”“现场解压 zip”“手写解析脚本”之间瞎试——慢，而且几乎必然出错。
+**它不做的事**：
 
-微光不重复造这套工具，而是**做能力探测与约束**：注入前查询宿主的工具注册表，按工具名的能力族前缀（`word_*` / `excel_*` / `ppt_*` / `pdf_*` 等）判断当前环境具备哪些文档能力，再据此分叉——**有工具**时要求走工具而不是自己解析、先读后写、交付前回读验证；**没有工具**时要求第一轮就如实说明边界、不要静默硬解二进制，并给出替代交付方式。用户明确说「就用脚本自己试」时仍然照做，但要先说明代价。
+- 不偷偷改文件——问答轮不改文件，诊断轮不越权修复，只有执行轮才动状态；
+- 不发起网络请求——除了调用你自己配置的模型档做记忆提取、反思与人设蒸馏；
+- 不给闲聊加固定开销——协议与台账是按需注入的；
+- 不替你下结论——机械判据只保证"有没有证据"，判断对错仍在模型自己。
 
-两条都只在**文档任务轮注入**：闲聊、代码、排查类请求零成本，只有请求里出现文件后缀、Word / Excel / PPT / PDF 等格式名，或“写一份报告”这类产物请求时才生效；中文里“查一下官方文档”这种泛称不会被误判成文档任务。判据取自冻结的意图文本，因此在一轮之内稳定，不会像工具结果那样在轮中作废前缀缓存。探测按能力族前缀而非插件名，因此不绑定任何第三方实现——`dsh-office-tools`、`dsh-excel-chat`、`dsh-ppt` 装了哪个都能识别，一个都不装就退化为边界声明模式。
+---
 
-### 优化清单
+## 安装与升级
 
-- [x] 问答、查找、讨论、诊断、执行五类请求路由
-- [x] 诊断不越权修复，讨论不提前替用户拍板
-- [x] 用户纠正和重复提问的即时对齐纠偏
-- [x] 相同请求连续失败后的归因纠偏与换方案提醒
-- [x] 第 6 轮起的长会话护栏与当前目标锚点
-- [x] 执行任务的“已完成 / 已验证 / 未验证 / 副作用”交付清单
-- [x] 上一轮执行回复缺少验证证据时的后续复核提醒
-- [x] 任务阶段状态机：回答 / 查找 / 讨论 / 归因 / 执行 / 验证 / 交付
-- [x] 真实工具证据：区分工具成功、失败和结果未知，不把工具调用本身当作目标完成
-- [x] 证据时效：引用日志/历史/旧报错前核对时间戳与因果，不用旧错误填空
-- [x] 记忆生命周期：相对时间记忆标记为临时记忆，30 天后自动失效；旧记忆无感兼容
-- [x] 反思日志跨会话反馈、旧字段迁移和模型感知协议
-- [x] 上下文压缩感知：识别宿主压缩检查点，压缩后重锚状态并提醒“摘要不是完整历史”
-- [x] 文档能力感知：探测文档工具并按需注入——有工具要求先读后写与回读验证，没工具要求如实说明边界、不硬解二进制
-- [x] 系统提示词轮内稳定：意图冻结（只认真实用户消息）+ 会变的内容走 runtime-context 通道，一轮只产生一份系统提示词
-- [x] 注入分层：system 段在会话内逐字节恒定（协议/契约/身份/纪律），记忆、语料、播报与任务指令全部走对话尾部快照——每一步都吃住前缀缓存
-- [x] 任务载具：任务契约（数量先估后回填、交付按原始判据对账）+ 改动台账 + 假设台账（含已排除项）+ 跨会话项目知识
-- [x] 行为触发器：按轨迹纠偏——撒网不收敛 / 连写不验 / 死路重撞（环境类给验证降级阶梯）/ 契约对账 / 项目知识采集
-- [x] 方法层：文档编辑方法（结构 → 最小编辑 → 一致性 → 回读）、改动影响面清单、结构定位提示
-- [x] 反思日志第五维「诊断深度与假设管理」：跨会话提醒能指向思维方式而非只有纪律
-- [x] 角色卡算法自动升级且保留记忆、风格和认可语料
+前置：已安装 DSH Desktop。
 
-### 为什么不接管宿主的历史压缩
+```bash
+# npm（推荐）
+dsh plugin add lume-dsh-plugin
 
-压缩服务由 DSH 的 agent preset 在自己的隔离域里挂载（`isolate: { compaction: true }`），profile 层的插件注册的同名服务不会被 `/compact` 或自动压缩使用——**第三方插件在标准 preset 下无法替换压缩后端**，这属于宿主的架构边界，不是接口开放与否的问题。
+# GitHub（备选）
+dsh plugin add github:cayan0x/Lume#v0.8.0
 
-Lume 因此选择「观察 + 重锚」：压缩发生时记录规模，在随后一轮注入提示，提醒模型摘要只保留要点、依赖早期细节时先确认；压缩产生的摘要消息带固定来源标记，Lume 用它把摘要与真实用户消息区分开，避免摘要污染当前目标与协议路由。人设契约、长期记忆与协议本身注入在 system prompt 段，不参与对话历史压缩，因此不受影响。
+# 指定版本 / 最新
+dsh plugin add lume-dsh-plugin@0.8.0
+dsh plugin add lume-dsh-plugin@latest
+```
 
-## 二、人设系统：「人设即人」
+**升级**：重复执行同一条命令即可。若当初是用**本地源码目录**装的（依赖里是 `link:`），在源码目录执行：
 
-微光的人设是**具名的独立个体**，而非一段静态的性格描述：
+```bash
+git pull && npm install --legacy-peer-deps && npm run build
+```
 
-- **记忆以人设为主键，跨会话、跨项目持久** —— 在绘画项目中告诉晚晴「以后叫你阿晴」，她在任何项目、任何新会话中都保持这一身份。记忆存放于 DSH 官方 storageDomain（`storages/lume_persona_identity.json`），完全本地
-- **性格随对话演进** —— 内置风格契约是基础盘；对话中提出的语气要求（「少用 emoji」「自称改为 XX」）会固化为该人设的「习得的风格约定」，跨会话生效，与基础盘冲突时以习得层为准
-- **切换带接班播报与持续纠偏** —— 切换人设时，新任人设在回复开头明确接替；此后逐轮检测回复是否残留旧人设的口头禅与称呼（零 token 的词法检测），检出即重新注入升级版纠偏播报——长对话中切换同样可靠
-- **双通道记忆写入** —— 主通道为模型主动调用工具（`lume_remember` / `lume_update_style` / `lume_create_persona`），随对话发生、零额外调用；安全网为被动提取，经三道门（关键词正则 → 相似去重 → 冷却）过滤后仅对触发轮调用模型，绝大多数轮次零消耗
-- **对话创建** —— 对当前人设说明「想建一个新的人设」，模型将通过访谈收集设定（名字、性格、说话方式、称呼）后保存，新的人设立即出现在菜单中
+**装完必须完全重启 DSH（含托盘进程）**——插件在宿主启动时加载，DSH 没有热重载。
 
-> **切换时机提醒**：在**新开的会话**里切换人设，新任人设即刻生效；但在**已经聊了一阵的会话**里，仅仅点一下菜单切换往往不够——大模型有思维惯性，会沿旧人设的口吻继续说话，不会立刻「换皮」。此时要在对话里**明确告诉大模型「切换到 XX 人设」**（如：「现在用福尔摩斯的口吻回复」），让它在下一轮真正进入新角色。插件自带的接班播报与持续纠偏能加速这个过程，但无法替代你的一句明确指令。
+![菜单入口](docs/screenshots/menu.png)
 
-菜单固定在输入栏左侧：「不使用人设」置顶，可随时回到默认风格；内置角色卡随后；底部为蒸馏与管理入口。列表异步加载完成后自动重新钳制视口，输入栏置底时菜单保持完整可见、可滚动。
+---
 
-<p align="center"><img src="docs/screenshots/persona-list.png" width="720" alt="人设菜单：不使用人设置顶，内置卡与自定义卡，底部为蒸馏与管理入口"></p>
+## 一、纪律层：这一轮该怎么干
 
-内置卡与自定义卡在同一菜单中平铺：内置的**噜噜**（元气管家娘，口头禅「好哒哥哥～」）、**晚晴**（低频高载的姐姐，口头禅「……交给我」）、**沈砚**（儒雅管家，口头禅「这就去办，主人」）、**江野**（嘴硬心软的傲娇，口头禅「……切」「才不是特意帮你」）受保护不可删除；自定义的 **Jade**、**坂田银时**、**福尔摩斯** 等由蒸馏或对话创建，可随时编辑、删除。
+### 1.1 先判类型，再划边界
 
-## 三、蒸馏工具：从素材到角色卡
+每一轮先用**这一句话 + 最近几轮轨迹**判定请求类型，判定结果与命中的判据都写进注入块（也进度量）：
 
-菜单中的「＋ Distill a character card…」提供批量生产角色卡的路径：粘贴（或导入 .txt/.md）一段小说、剧本或人物设定文档，由宿主侧管线将其蒸馏为一张与内置卡同构的角色卡。
+| 模式     | 允许做什么                                                                      |
+| -------- | ------------------------------------------------------------------------------- |
+| **问答** | 直接回答；只读核实该做就做，不改文件、不替你做决定                              |
+| **查找** | 收集并区分已知 / 未知 / 推断；未经授权不改外部状态                              |
+| **讨论** | 比较选项、取舍与风险；不把探讨中的方案当成已定方案                              |
+| **诊断** | 说明现象、证据、根因与验证办法；除非你明确要求修复，不越权动手                  |
+| **执行** | 确认目标与完成标准，做最小变更；交付时列清已完成 / 已验证 / 未验证 / 残留副作用 |
 
-<p align="center"><img src="docs/screenshots/distill-input.png" width="720" alt="蒸馏弹窗：粘贴素材，上限 20000 字"></p>
+轨迹只在**证据足够**时补判：纠正后按被纠正前那句话重算、在途任务对承接式追问有粘性、连问两句不算任务；带了疑问特征的句子一律不抬档。证据不足时回落到单句判定，绝不猜。
 
-管线分三步：
+进入执行后还有阶段推进（answer → research → discuss → diagnose → execute → verify → deliver），阶段决定这一轮是"先给方案"还是"可以动手"。
 
-1. **对话挖掘**（零 token）：抽取台词、统计说话人、保留双边情境窗口、时间间隔和可观测风格统计；归属不足时标记 mixed，由 LLM 甄别目标角色
-2. **证据约束的契约合成**：每条稳定特征都要求原话/情境证据、触发场景和频率，避免把单一场景脑补成固定人格
-3. **语料合成**：聊天记录优先使用全时段真实对话对；小说、剧本和设定文档也按“场景→行为→原声”组织示例，优先复用原句，禁止中和为通用回复
+### 1.2 证据核对：该拿事实说话的地方
 
-### 蒸馏算法与角色卡自动升级
+| 核对           | 什么时候响                                             | 每会话上限 |
+| -------------- | ------------------------------------------------------ | ---------- |
+| **引用核对**   | 回答里写了 `文件:行`，但这段本次没打开过               | 3          |
+| **断言核对**   | 对没见过的符号下"没映射 / 不存在 / 不支持"这类否定断言 | 2          |
+| **需求漂移**   | 有契约在手，进展却偏离了契约的判据（含压缩之后）       | 2          |
+| **覆盖核对**   | 写出文档产物之后：把需求原句与交付物里的句子并列对账   | 2          |
+| **提问核对**   | 一轮抛出超过 2 条「待你定」，或问题带着"我没查 / 我猜" | 2          |
+| **载具缺口**   | 已经动了代码，但契约与设计都还空着                     | 2          |
+| **上下文预警** | 上下文占用到 75% / 90%                                 | 3          |
+| **度量自校**   | 本会话路由被反复纠正（≥2 次）                          | 2          |
 
-角色卡保存蒸馏算法版本、目标角色和本地原始素材升级源。插件升级后会在后台检查旧版本角色：有升级源时自动重新蒸馏，只替换基础契约和基础语料；记忆、习得风格、用户改名和对话中沉淀的认可语料保留不动。升级失败时继续使用旧卡，不阻塞对话。
+上限不是"省着用"，是**防噪音**：同一个提醒反复顶，模型会开始躲词而不是解决问题。所以每个槽有自己的用量上限与冷却，多数槽还有"清空条件"——你补上了它就不再提。
 
-原始素材只保存在本地身份域，不注入普通对话上下文，也不会上传。旧版本且没有原始素材的卡片只能做兼容迁移，无法恢复旧算法已经丢弃的证据。
+### 1.3 行为触发器：不看你怎么说，看轨迹
 
-### 从聊天记录蒸馏一个人
+协议文本管不了"在压力下不执行"——实测症状是连续几十次广度探查不收敛、连续十几次改动不验证、在同一个坏环境上撞十几次。这类症状是**轨迹**的，所以判据也在轨迹上：
 
-粘贴微信 / QQ 导出或复制的聊天记录，蒸馏工具会**自动识别时间戳锚点切分说话人**（剔除 [语音] / [图片] / [表情] 等占位符），并在弹窗中列出检测到的说话人供点选——**点选要蒸馏的人，对方的每一句话成为语气样本，你发出的每一句话归为用户侧，真实对话对直接作为语料**，无需 LLM 改写，原汁原味保留本人的说话方式。对话量建议 50 条以上，蒸馏出的角色才足够立体。
+| 触发器              | 判据（可配阈值）                          | 命中后给什么                                       |
+| ------------------- | ----------------------------------------- | -------------------------------------------------- |
+| `converge`          | 连续只读探查 ≥ 12 步仍无产出              | 停止撒网，先复述链路并落台账                       |
+| `verify-as-you-go`  | 连续改动 ≥ 4 步（或台账未验证项 ≥ 4）     | 先跑一次最小验证，再把台账推进到 verified          |
+| `dead-path`         | 同一验证连续失败 ≥ 3 次                   | 环境类给"验证降级阶梯"，其余要求先归因写假设台账   |
+| `hypothesis-stale`  | 诊断轮出现验证失败，但假设台账没更新      | 把失败归因落成假设，标出下一步验哪条               |
+| `contract-missing`  | 已经动手，但还没写契约                    | 补一份契约（目标 / 范围 / 数量 / 判据 / 非目标）   |
+| `design-missing`    | 设计型任务摸了 ≥ 6 处代码仍无设计记录     | 写`lume_design`：决策点 / 选择 / 放弃理由 / 影响面 |
+| `criteria-drift`    | 有契约，且距上次对账 ≥ 3 轮（或刚压缩过） | 拿契约逐条对账，防止判据随进展漂移                 |
+| `knowledge-capture` | 工具步数 ≥ 20 且本会话还没提醒过          | 若有稳定事实（命令 / 链路 / 约定 / 死路）就记下来  |
+| `unfounded-change`  | 改的是**已存在但本会话没读过**的文件      | 二选一：先做最便宜的核实，或落成带验证方式的假设   |
 
-- 预览中所有字段可编辑，保存后立即出现在人设菜单
-- 素材经 RPC 以任务制交由宿主后台蒸馏（约 10~90 秒），不进入对话上下文，不影响当前会话；蒸馏过程中弹窗不可误关，关闭需二次确认并会中止任务
-- 素材上限 20,000 字；素材按不可信文本处理，其中出现的任何指令不会被执行
-- 蒸馏路由可通过 `distillProvider` / `distillModel` 指定专用模型档，默认跟随主对话模型
+规矩：一次只顶**一条**（按紧急度排序，同时堆三条会互相稀释）、每类每轮最多一次、同类两轮内不重复、文本里带**具体数字**（"已连续 14 次只读探查"）——让提醒可被核对，而不是空洞训话。
 
-### 非聊天素材的统一蒸馏原则
+---
 
-小说、剧本和人物设定不再简单当作性格简介：按角色、场景、连续对白建立“谁在什么情境下说了什么”的证据链；分别观察平淡、冲突、亲密、拒绝等场景。设定文档只作为低置信度身份与边界线索，没有原话支持的内容不会伪装成口吻特征。所有素材最终统一为原声证据、情境行为、表达风格、身份边界和置信度。
+## 二、方法层：把量化落成能检查的产出
 
-## 四、管理自定义人设
+### 2.1 十个工具
 
-「管理自定义人设…」列出全部条目：**内置卡的编辑与删除按钮置灰**（受保护），自定义卡支持：
+模型丢的通常不是"不知道要量化"，而是**没有一个地方放量化结果**。任务侧七个：
 
-- **导入人设卡** —— 从 JSON 卡片文件导入一张完整人设（含契约、语料、风格约定与记忆），同名覆盖需二次确认
-- **导出** —— 任一人设（含内置）可导出为自包含 JSON 卡片文件，可选是否附带记忆，跨设备可还原
-- **删除** —— 行内二次确认；删除同时清除该人设的记忆、习得风格与身份档案，不可恢复
-- **记忆** —— 打开该人设的记忆星图（见下节）
-- **编辑** —— 显示名、简介与风格契约全文可修改（英文键名为存储主键，创建后不可变更；语料只读展示，语气随对话继续演进）
+| 工具                  | 做什么                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `lume_contract`       | 任务契约：目标 / 范围 / 数量（先估后回填）/ 完成判据 / 非目标 / 待确认                |
+| `lume_change`         | 改动台账：改什么 → 为什么 → **怎么验证的** → 状态；只推进状态时可只传 target + status |
+| `lume_hypothesis`     | 假设台账：open / testing / confirmed / excluded；含被推翻的已排除项                   |
+| `lume_design`         | 设计决策：决策点 → 选择 → 被放弃的方案与理由 → 影响面                                 |
+| `lume_project_note`   | 记一条稳定的项目事实（按工作目录跨会话累积）                                          |
+| `lume_project_forget` | 按编号删掉一条过时或记错的项目知识                                                    |
+| `lume_metrics`        | 读运行时度量：路由判定 / 外部结果信号 / 块装配 / 触发器效能                           |
 
-<p align="center"><img src="docs/screenshots/manage.png" width="720" alt="管理弹窗：导入入口 + 完整列表（导出/记忆/编辑/删除）"></p>
-<p align="center">
-  <img src="docs/screenshots/manage-edit.png" width="560" alt="编辑契约：显示名、键名只读、简介、风格契约与只读示例对话">
-</p>
+人设侧三个：`lume_remember`（一条持久事实）· `lume_update_style`（一条风格约定）· `lume_create_persona`（访谈后新建人设）。
 
-自定义人设与内置人设能力完全一致：对话改名、记忆积累、风格演进全部支持，区别仅在于自定义人设可以删除。
+### 2.2 契约长这样
 
-## 五、记忆星图
+```
+lume_contract({
+  goal: "跑步记录新增「配速」列：列表展示 + 历史记录补算 + 导出可用",
+  scope: "run_record 表与迁移脚本、列表页组件、CSV 导出",
+  expectCount: 6,            // 先估：6 个改动点，探索后回填实际值
+  criteria: ["新记录能自动算出配速", "历史记录已补算", "导出的 CSV 里含配速列"],
+  nonGoals: ["不改 CSV 既有的列顺序", "不动手机端的同步逻辑"],
+  open: []                   // 默认 0 个待确认——能自己核实的不许抛回来
+})
+```
 
-管理弹窗中每个人设行内都有「记忆」按钮，点击后以力导向星空图的形式可视化该角色的全部长期记忆。
+### 2.3 核心机制不靠模型自觉
 
-- **Canvas 力导向布局** —— 记忆卡片（260×72）在 960px 宽幅遮罩层中自动排布，核心记忆紫色带 ★、普通记忆青色，语义相关者连线，背景缓慢漂移
-- **日期筛选** —— 顶部支持 全部 / 最近 7 天 / 30 天 / 90 天 过滤
-- **行内编辑与删除** —— 点击卡片展开详情面板，可即时修改记忆文本或删除整条记忆，经 `updateMemory` / `deleteMemory` 持久化写入存储
+这是刻意的取舍：只靠提醒的机制会退化成"提醒了很多次，一次都没落地"。所以这些是插件**机械完成**的，模型调用工具只是为了补充细节：
 
-<p align="center"><img src="docs/screenshots/memory-map.png" width="720" alt="记忆星图：顶部日期筛选，记忆卡片可点击编辑删除"></p>
+- **改动台账自动入账**：`mutate` 类工具一被调用，就从入参里记一条（标注"（自动）"）；
+- **需求锚点**：用户原话逐字留存，供覆盖核对与漂移检查；
+- **项目知识自动沉淀**：不依赖模型调 `lume_project_note`（实测它三次全部落空）；
+- **覆盖核对、引用核对、断言核对**：纯词法 + 本会话证据索引，零额外模型调用。
 
-## 六、反思日志
+### 2.4 下结论要过闸
 
-会话结束时，插件在空闲时间跑一次小模型调用，对整段对话的任务执行协议执行情况进行复盘：上下文管理、计划与门控、验证与失败处理、结果复核，各打 0-2 分并附一句中文备注，写入 `lume_reflection` 域。
+假设台账的 `confirmed` / `excluded` 是**裁决**，不是备注：证据（≥8 字，写清观察）、裁决方式（用哪条命令 / 工具、看什么结果）、反例检查（找过哪些反例）三项缺一即拒。证据里出现的路径引用必须**本会话真的打开过**，否则点名报错。
 
-升级到 0.4.0 时，旧版反思日志会在域打开后自动从旧字段迁移到新字段；迁移幂等，不影响角色卡、记忆或会话。
+理由很直白：真机里这两个状态曾经只带一句"已验证 / 无"——无法复核的结论，等于把猜测固化成跨轮次的事实。
 
-- **零用户感知** —— 不进入对话上下文，不消耗正常请求的 token 配额
-- **定性分析** —— 积攒数周后读取存储文件即可复盘对话质量，无需猜测
-- **可关闭** —— 配置项 `reflectionEnabled` 默认 `true`，置为 `false` 即停用
+### 2.5 项目知识：越用越强的那部分
 
-## 七、人设卡片导出/导入
+- **按工作目录归属**跨会话累积；需求特有的结论带"（本需求）"标记，只在同一需求内可见，换项目不会串；
+- **带编号**，可以在对话里点名删除（`lume_project_forget`）；
+- **有形状闸**：只收句子，不收测试输出行、代码片段、表格行、复制粘贴的命令行；宁窄勿宽——宁可漏记，也不要把仓库开发过程的产物灌进知识库；
+- **有敏感拦截**：带值的密钥、连接串、私钥一律不入库（项目知识是明文跨会话存储）；
+- **历史补蒸馏**：启动时扫最近 7 天的会话（**包括已经撑满、聊不动的那些**）补出跨会话知识，分片执行、幂等不重复。
 
-在管理弹窗中，任意人设（内置或自定义）均可导出为独立的 JSON 卡片文件，并在其他设备或他人环境中导入还原。
+---
 
-- **导出格式** —— 自包含 JSON（`lume-persona-card` v1），含契约、语料、风格约定、声音签名，可选含记忆
-- **导入校验** —— 解析时校验格式、版本、键名合法性，内置人设名受保护，不可覆盖
-- **跨设备迁移** —— 一张卡片即可还原人设的完整身份（记忆、风格、档案名），无需额外配置
+## 三、仪表盘：它到底有没有起作用
 
-## 任务载具：把量化与台账变成可检查的产出
+装了约束和提醒之后，最该回答的问题不是"机制在不在"，而是"命中之后行为真的变了吗"。所以 v0.8 起先装仪表盘：
 
-纪律（协议正文）教的是「不越权、要验证、要复核」；**方法**教的是「怎么把一个任务收敛成可核对的产物」。后者需要载体——模型通常不是不知道要量化，而是**没有地方放量化结果**。四个载具都由模型自己写（工具调用、零额外 LLM 调用），每轮按状态回显到对话尾部：
+- **记什么**：路由判定（模式 + 命中判据 + 证据来源）、触发器命中（带命中当时的计数器快照）、块装配（留下 / 丢弃 / 字符数 + 本轮加权了哪几条条款）、每轮状态快照（契约 / 设计 / 台账 / 假设）、外部结果信号（用户纠正 / 重复请求 / 问答轮改动 / 执行轮零动作 / 出现真验证命令）；
+- **落在哪**：`<DSH_HOME>/harness/lume-metrics.jsonl`，一行一条 JSON，可以直接看、直接删；
+- **怎么看**：对话里调 `lume_metrics`，或在 DSH 的插件配置里关闭 `metrics`（关掉只是不记录，不影响任何行为）；
+- **效能口径**：命中后 **3 轮**内是否出现**机械可判**的预期变化——真验证命令、或对应载具（契约 / 设计 / 台账 / 假设）从无到有；没有机械口径的机制直接标"未判定"，**不计入分母**。
 
-| 载具 | 工具 | 内容 | 生命周期 |
-|---|---|---|---|
-| **任务契约** | `lume_contract` | 目标 / 范围 / **数量（先估后回填）** / 完成判据 / 非目标 / 待确认 | 会话内；交付轮自动切成**对账口径**——对照的是开工时写下的原始判据，防「判据漂移」 |
-| **改动台账** | `lume_change` | 文件·符号·章节 → 改什么 → 为什么 → 怎么验 → 状态 | 会话内；文档任务用章节名当 target，形成分节记账 |
-| **假设台账** | `lume_hypothesis` | 假设 + 证据 + 状态（含**已排除**） | 会话内；已排除项照常回显，避免重复验证同一个假设 |
-| **项目知识** | `lume_project_note` | 构建/测试命令、模块链路、仓库约定、死路记录 | **跨会话**，按工作目录归属 |
+两条诚实声明写在这里，也写在报表里：效能是**观察性**的，不是因果；纠正率是代理指标（用户纠正次数 / 判定次数），不是真值。样本不够时，`0/1` 可能只是"没被触发过"，不代表机制无效——它代表**还没有证据**。
 
-项目知识为什么单独存放：代码路径与仓库约定是**工作事实**，换人设不该失忆，也不该随人设卡被导出分享。环境性死路会被自动记入（例如「本机 Maven 离线仓库为空」），下次会话不必重踩。
+---
 
-## 行为触发器：把「元决策」从用户手里接过来
+## 四、长会话：上下文不是记忆的载体
 
-一次真实会话的轨迹复盘（2 轮 / 58 步 / 106 次工具调用）显示：**不是不知道该收敛，而是在压力下没有执行**——34 次广度探查不收敛、25 次改动里 18 次连击无验证、17 次命令全在撞同一个不可用的构建环境、交付前靠用户发话才自审。协议正文管不了这种，因为文本是静态的，而症状是**轨迹**的。所以只在行为模式成立时注入一句带具体数字的提醒：
+- **压力预警**：上下文占用到 75% / 90% 时提醒收尾并开新会话，**先把会话记忆落盘**；
+- **会话记忆**：每轮机械导出（目标 / 已拍板 / 未决 / 关键定位 / 改动与验证状态），新会话开局注入，说一句"继续"即可续接；
+- **不要指望旧窗口还能继续**：宿主压缩失败时它会彻底聊不动，而会话记忆已经把该带的带走了。
 
-| 触发器 | 触发条件 | 注入 |
-|---|---|---|
-| 收敛提醒 | 连续 ≥12 次只读探查且尚未写契约 | 停止撒网，先复述「入口 → 数据流 → 影响面」并写台账 |
-| 增量验证 | 连续 ≥6 次改动没有任何验证动作 | 改一处验一处，先验证前一批 |
-| 死路重撞 | 同一验证连续失败 ≥3 次 | 环境类占多数 → **验证降级阶梯**（编译器 → 语法检查 → 静态交叉引用 → 手工走读 + 风险清单）；否则要求先归因并写假设台账 |
-| 假设维护 | 诊断模式下验证失败但假设未更新 | 更新假设状态，标出已排除项 |
-| 契约对账 | 有契约且每 3 轮 / 压缩后 | 用原始判据逐项对账，标注已验证 / 未验证 / 偏离 |
-| 项目知识采集 | 无契约且步数 ≥20（每会话一次） | 提醒把稳定项目事实记下来 |
+### token 与缓存
 
-每类触发器每轮最多一次且有轮级冷却（提示一多就变噪音）；工具按**行为类别**（inspect / mutate / verify / plan）归类而非按名字，宿主或扩展换名不失效。
+Lume 每轮都往对话里加东西（模式、需求原话、台账、提醒），这些内容按"变不变"分两处放：
 
-## 方法层：按任务形态注入
+- **系统段**只放会话内逐字节不变的内容（人设契约、身份名、纪律）；
+- **易变段**（记忆 top-k、语料示例、切换播报、本轮重点条款、提醒）交给宿主的 runtime-context 通道，渲染成对话尾部快照。
 
-- **文档任务**：先取结构（标题层级 / 表格清单 / 编号体系）→ 最小编辑保留格式与编号 → 术语与称谓全文一致 → 交付前回读改动区域并列出「改了什么 / 没动什么 / 未核对什么」
-- **执行轮**：改动影响面清单（谁调用它、被谁实现、配置与 SQL 映射、前端引用）+ 每处改动的验证方式
-- **有结构分析工具时**：建议用符号级定位替代通篇 read
+这样只有**重启、且插件本身变了**时才需要重算一次上下文；平时长对话的前缀缓存不会被每一步作废。宿主不支持 `systemPrompt.context` 时自动退回旧行为（全部挤在 system 段）——丢前缀缓存，不丢功能，启动日志会写 warn。
 
-## 分层注入与 Token 预算
+---
 
-注入分两层。这不是洁癖，是**前缀缓存的前提**：
+## 五、人设系统
 
-| 层 | 通道 | 内容 | 变化频率 |
-|---|---|---|---|
-| **恒定段** | system prompt（`lume:thinking` order 1 / `lume:persona` order 10000） | 任务协议正文、人设契约、身份、行为纪律 | 会话内**逐字节不变**（只有人设切换时 +1 份） |
-| **易变段** | runtime-context（`lume:runtime` / `lume:persona-runtime` / `lume:boundary`，渲染成对话尾部的一条快照消息） | 路由、任务阶段、长会话护栏、目标锚点、即时对齐、交付复核、压缩重锚、文档能力指引、记忆 top-k、风格约定、语料示例、切换播报 | 每步可变，但只花自己那几百 token |
+人设不是"换个语气"，是换一段关系。
 
-为什么必须这样分：**system 串排在消息序列最前面**，而前缀缓存只认「从第一个不同的字节起，之后全部失效」。system 段只要每步改写一次，它后面的工具定义、结构化输出和**整段对话历史**就全部按全价重算。旧实现正是如此——`taskPhase` 随 `tool/call`·`tool/result` 在**轮内推进**、长会话护栏还内嵌轮次号，于是每一步都改写系统提示词。实测（`deepseek-v4-flash`，2026-09-11 某会话 282 个请求）：`cacheReadTokens` 恒定 **384**、命中率中位数 **0.2%**，未命中输入从 1.3 万涨到 55.9 万；请求间隔中位数仅 22 秒，所以这不是缓存过期。分层后恒定段一次构建全程命中，易变段落在尾部、改它不作废前缀。
+- **内建人设**：萝莉 `loli`（噜噜）/ 御姐 `senpai`（晚晴）/ 管家 `butler`（沈砚）/ 毒舌傲娇 `tsundere`（江野）/ 不使用人设 `none`；
+- **人设蒸馏**：从聊天记录、小说、剧本、人物设定文档里提炼具名角色——语气、口头禅、回复篇幅都**锚定真实素材的统计**，而不是凭想象编；
+- **语气泄漏纠偏**：内置卡带"签名词"（自称 / 称呼 / 口头禅），切换后逐轮做**纯词法**检测；检出泄漏就重开纠偏窗口，一轮干净就自动解除；
+- **长期记忆**：以人设为主键，跨会话、跨项目持久；身份称呼类记忆（core）恒注入，其余按与当前消息的相关度取 top-k；
+- **风格收敛**：你的纠正自动转成风格约定，你认可的回复摘录为语料，语气随使用收敛；
+- **记忆星图**：把记忆与关联可视化，可筛选、可编辑、可删除；
+- **角色卡导出 / 导入**：一张卡带走完整身份（记忆 + 风格 + 档案名）。
 
-| 注入段 | 层 | 无优化 | 优化后 | 使用的算法 |
-|---|---|---|---|---|
-| 任务执行协议 | 恒定 | ~500 | 会话内恒定（吃缓存）；闲聊轮尾部另加约 40 | 协议按模型能力冻结；「闲聊不背任务条款」由尾部一行声明 |
-| 人设契约 | 恒定 | ~350 | ~250 | 契约精简 |
-| 身份 | 恒定 | ~80 | ~80 | 恒注入 |
-| 工具定义 ×3 | 恒定 | ~600 | ~450 | description 精简 |
-| 语料示例 | 易变 | 6 条 ~600 | 稳态 2 条 ~200 | 少样本衰减 `max(2, 6−轮数)` |
-| 记忆 | 易变 | 15 条 ~350 | core + top5 ~120 | 相关性检索（本地分词 + mini-IDF，零成本） |
-| 风格层 | 易变 | 10 条 ~250 | top5 ~120 | 同上 |
-| 任务指令（路由/阶段/护栏/锚点） | 易变 | ~600 | 按需 | 6 轮前不注入护栏与锚点，闲聊不注入任务条款 |
-| 文档能力指引 | 易变 | 常驻 ~120 | 文档任务轮 ~120，其余 0 | 工具能力探测 + 按轮触发 |
-| 任务载具（契约 / 台账 / 假设 / 项目知识） | 易变 | 0 | 任务轮 ~150-400，**只在内容变化时付费** | 模型主动写入；尾部快照按内容差异提交 |
-| 方法块（文档方法 / 影响面 / 结构提示） | 易变 | 常驻 ~400 | 按形态 80-200 | 文档轮 / 执行轮 / 有分析工具时才注入 |
-| 触发器提醒 | 易变 | 0 | 触发时 80-120 | 六类行为模式 + 轮级冷却 |
+![人设列表](docs/screenshots/persona-list.png)
+![人设管理](docs/screenshots/manage.png)
+![人设编辑](docs/screenshots/manage-edit.png)
+![人设蒸馏](docs/screenshots/distill-input.png)
+![记忆星图](docs/screenshots/memory-map.png)
 
-- 恒定段（协议 + 契约 + 身份）约 **900 tok**，在一个会话里建一次、之后每步都是缓存命中
-- 易变段稳态约 **700~1,200 tok/步**，全部落在对话尾部：改它只花自己那点 token，不动前面的任何前缀
-- 静态内容前置于易变内容，叠加 DeepSeek 前缀缓存后，有效成本可再降约一个数量级
+### 记忆的两类与生命周期
 
-**怎么确认分层还成立**：`$DSH_HOME/lume-compaction.log` 里每个会话应只有 1-2 行「系统段指纹」（首次 + 人设切换）。若长会话里反复出现新指纹，说明又有内容混进了 system 段——`test/injection-layering.test.ts` 就是在锁这条不变量。
+- **叙述与真实事件**：故事、背景、共同经历、对方身份事实、约定分别归类；叙述有 **1600 字上限**，避免人设卡被闲聊撑爆；
+- **临时记忆 30 天过期**：带过期时间的记忆到点自动不再注入——"我下周出差"这类会被自然清掉，不需要你手动删；
+- **同主题去重**：同一主题算同一条，相似度判重后合并，避免"换句话就多一条"；
+- **蒸馏带算法版本**：角色卡记录蒸馏算法版本，升级后旧卡按新算法重蒸（启动时后台做，失败留痕）。
 
-**旧宿主降级**：宿主不支持 `systemPrompt.context`（0.1.5 之前的版本）时，易变段并回 system 段——丢前缀缓存但不丢记忆与播报注入，启动日志会写一条 warn。配置 `layeredInjection: false` 可手动退回旧行为做对照。
+---
 
-## 配置项
+## 六、配置
+
+在 DSH 的插件配置里改（键名与 `src/host/config.ts` 一致）：
+
+| 配置                                           | 默认             | 说明                                                       |
+| ---------------------------------------------- | ---------------- | ---------------------------------------------------------- |
+| `layeredInjection`                             | `true`           | 分层注入；关掉则易变内容回到 system 段（丢缓存，不丢功能） |
+| `projectMemory`                                | `true`           | 跨会话项目知识与载具台账                                   |
+| `behaviorTriggers`                             | `true`           | 行为触发器（按轨迹纠偏）                                   |
+| `metrics`                                      | `true`           | 运行时度量落盘与 `lume_metrics`                            |
+| `reflectionEnabled`                            | `true`           | 会话结束反思：四项能力各打 0-2 分并留痕                    |
+| `extractionEnabled` / `extractionCooldownMs`   | `true` / 10 分钟 | 自动记忆提取开关与冷却                                     |
+| `extractionProvider` / `extractionModel`       | 回落主对话       | 记忆提取专用模型档（可只配其一）                           |
+| `distillProvider` / `distillModel`             | 回落主对话       | 人设蒸馏专用模型档（可只配其一）                           |
+| `triggerInspectStreak` / `triggerChangeStreak` | `12` / `4`       | 收敛提醒 / 增量验证提醒的步数阈值                          |
+| `triggerDeadPathFails`                         | `3`              | 同一验证连续失败多少次判定死路                             |
+| `sampleCount` / `sampleMin`                    | `6` / `2`        | 语料少样本注入条数与下限                                   |
+| `memoryInject` / `styleInject`                 | `12` / `5`       | 记忆与风格约定的注入条数上限                               |
+| `injectionStrategy`                            | `"topk"`         | 检索策略（`topk` / `full`）                                |
+| `switchBoundaryTurns`                          | 内置常量         | 切换人设后的播报窗口轮数                                   |
+| `personaOrder`                                 | 内置顺序         | 人设菜单排序                                               |
 
-| 配置项 | 默认值 | 说明 |
-|---|---|---|
-| `sampleCount` / `sampleMin` | 6 / 2 | 语料少样本基数与保底值（随轮数衰减） |
-| `memoryInject` / `styleInject` | 12 / 5 | 记忆与风格注入条数（top-k） |
-| `injectionStrategy` | `"topk"` | `"topk"` 相关性检索 / `"full"` 全量注入 |
-| `personaOrder` | 10000 | 人设契约段（恒定段）在 system prompt 中的排序：贴着对话历史的注意力最强位 |
-| `layeredInjection` | `true` | 分层注入：system 段只留会话恒定文本，易变内容走 runtime-context（对话尾部快照）。置 `false` 退回旧行为做对照；宿主不支持该通道时自动降级 |
-| `projectMemory` | `true` | 项目知识（构建/测试命令、模块链路、约定、死路）按工作目录跨会话累积；与人格记忆分开存放 |
-| `behaviorTriggers` | `true` | 行为触发器：撒网不收敛 / 连写不验 / 死路重撞 / 判据漂移的按轨迹提醒 |
-| `triggerInspectStreak` / `triggerChangeStreak` / `triggerDeadPathFails` | 12 / 6 / 3 | 三类触发器的阈值（只读探查连击 / 改动连击 / 验证失败连击） |
-| `switchBoundaryTurns` | 2 | 切换播报边界窗口（按用户轮计） |
-| `extractionEnabled` | `true` | 被动提取开关 |
-| `extractionCooldownMs` | 600000 | 被动提取冷却（毫秒） |
-| `extractionProvider` / `extractionModel` | 回落主对话 | 提取专用模型档（可仅配置其一） |
-| `distillProvider` / `distillModel` | 回落主对话 | 蒸馏专用模型档（可仅配置其一） |
-| `reflectionEnabled` | `true` | 会话结束时运行任务执行协议反思评估，写入 `lume_reflection` 域 |
+---
 
-## 存储
+## 七、数据与隐私
 
-- 会话选择：`storages/lume_persona_state.json`（LRU 淘汰，200 会话上限）
-- 身份、记忆、风格与自定义人设：`storages/lume_persona_identity.json`（记忆上限 30 条、风格上限 20 条、语料上限 12 条）
-- 自定义蒸馏卡额外保存 `distillVersion`、`distillHint` 与本地 `distillSource`，供插件升级时后台重蒸馏；升级只替换基础契约/语料，不覆盖身份域中的记忆、风格和认可语料
-- v0.1.0 旧版 `persona-state.json` 会在首次启动时自动导入并改名为 `.migrated`
-- 全部数据保存在本地，不上传任何远端
+- 数据全部在**本机**：人设与记忆、项目知识、反思、会话选择各走宿主的存储域（明文 JSON，DSH 数据目录下，可直接查看 / 备份 / 删除）；会话原文由 DSH 自己管理；
+- 度量单独一条线：`<DSH_HOME>/harness/lume-metrics.jsonl`，一行一条事实；
+- 插件自身**不发起网络请求**（除调用你配置的模型档做提取 / 反思 / 蒸馏）；
+- 自动沉淀有**敏感内容拦截**：带值的密钥、连接串、私钥、加密串一律不入库；
+- 想彻底清空：停用插件后删除上述存储域文件与 `lume-metrics.jsonl` 即可。
 
-## 宿主兼容性
+---
 
-- **RPC 通道必须注册在注入了 `webServer` 的作用域里，且不能包 `effect`**：宿主的 `connection.rpc.handle` 内部以**调用方 ctx** 执行 `webServer.register(route)`（`register(owner, ...)` 里是 `owner.effect(() => owner.webServer.register(route))`）。而 cordis 的 `effect` 会另起一个 **fiber**，**注入授权不随子 fiber 继承**——所以 `webCtx.effect(() => webCtx.connection.rpc.handle(...))` 仍然越权抛错（0.7.1 就栽在这），必须像宿主自带的 `dsh-ppt` 那样**直接在 inject 回调里调用**。该注册还被挪到 `apply` 末尾并加独立 try/catch：它只服务客户端菜单，失败绝不该影响人设注入与工具。0.6.2 / 0.7.0 / 0.7.1 在 DSH Desktop 0.9.1 上的故障（DSH 起不来、或界面人设菜单空白）都源于此，请升级到 ≥0.7.2。
-- **插件不会拖垮宿主**：`apply()` 外层有兜底 try/catch，插件内部的任何异常都降级为「部分功能不可用 + `logger.error`」，不再阻断 DSH 启动。
-- **peer 声明只留宿主运行时保证提供的包**：`@deepseek-ai/dsh-client-ui-primitives` 这类前端包由宿主模块图在运行时提供，**不声明为 peer**——新版桌面安装器做严格 peer 闭包校验，声明它会连带检查它自己的 peer（`dsh-client-runtime`），导致安装/更新被拒绝（desktop 会写进 `.generations-deferred.json` 并冻结整个 profile 迁移）。它仍在 `devDependencies`（tsc 类型与 tsdown external 需要）。
+## 八、常见问题
 
-## 安装与更新
+**这轮它怎么没按纪律来？**
+先看这一轮被归成了哪类：问答轮不会硬塞任务方法块（否则就是自相矛盾）。想让它按执行纪律走，把话说明确（"开始改"）。
 
-前置条件：已安装 DSH Desktop。
+**为什么工具没被调用？**
+因为核心机制**不需要**它调用：改动台账、需求锚点、知识沉淀、覆盖核对都是插件自己机械完成的。模型主动调用只是补充细节。
 
-### 从 npm 安装（推荐）
+**知识为什么没落盘？**
+四种可能，日志里都能看见：① 工作目录还没拿到（新会话第一轮偶发，第二轮补上）；② 候选没通过判据（要求有证据锚点：路径 / 文件名 / 表名字段 / 命令）；③ 形状闸把它当成了代码 / 测试输出 / 表格行 / 命令行；④ 命中了敏感内容拦截。
+日志关键词：`自动沉淀候选` / `项目知识补落盘` / `工作目录已解析`。
 
-微光已发布到公共 npm 仓库（`lume-dsh-plugin`），无需访问 GitHub 即可安装：
+**提醒怎么变少了？**
+设计如此：每个提示槽有用量上限，触发器有轮级冷却，一次只顶最紧急的一条。提醒变噪音就没人读了。
 
-```bash
-dsh plugin add lume-dsh-plugin
-```
+**度量里为什么是 0 和"未判定"？**
+0 往往意味着**没被触发过**，不是机制失效；"未判定"是明确排除在比例外的机制（没有机械口径）。看效能要同时看命中次数——命中 0 次的比例没有意义。
 
-### 从 GitHub 安装（备选）
+**上下文快满时怎么办？**
+按提醒收尾当前这一步，然后**开新会话**——会话记忆已经存好，新会话开局会带上"目标 / 已拍板 / 未决 / 关键定位"。
 
-若网络无法访问 npm，也可直接从仓库安装：
+**换项目 / 换工作目录，知识会串吗？**
+不会。项目知识按**工作目录**归属；需求特有的结论还会带"（本需求）"标记。
 
-```bash
-dsh plugin add github:cayan0x/Lume#v0.7.0
-```
+---
 
-安装后需**完全重启 DSH（包含托盘进程）**方可加载；启动日志中出现 `lume: 已加载（builtins=loli,senpai,butler,tsundere,none）` 即表示加载成功。构建产物随仓库发布，两种路径都不需要本地构建。
+## 九、已知局限
 
-### 从旧版本升级（已装过微光的电脑）
+**局限（不藏）**：
 
-重新执行一次安装命令即可升到指定版本，随后**完全重启 DSH（含托盘）**：
+1. **有一部分只能真机验证**：宿主 RPC 注册、注入作用域、事件形状、装配时序——单测抓不到，所以提供了 `npm run verify:live` 把真机清单做成一条命令；门禁里的产物断言也只能保证"已知的坑不再犯"。
+2. **机械判据只管"有没有证据"，管不了"判断对不对"**：语义层的对错仍在模型自己。
+3. **效能是观察性的**：3 轮窗口内的共现不等于因果；样本少时读不出结论，别把 0/1 当判决。
+4. **宿主侧与客户端侧同一个包**：任一侧坏了都可能让 Harness 起不来，所以门禁里有产物解析断言。
+5. **旧宿主降级**：不支持 `systemPrompt.context` 的宿主会把易变段并回 system 段——丢前缀缓存，不丢功能，启动日志会写 warn。
 
-```bash
-dsh plugin add lume-dsh-plugin   # npm（推荐）
-# 或
-dsh plugin add github:cayan0x/Lume#v0.7.0   # GitHub（备选）
-```
+**兼容性**：
 
-人设选择、记忆与风格数据存放在 `storages/` 目录，升级不会丢失。
+| 项       | 说明                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| 宿主     | DSH Desktop；插件以 `dsh.bundle.patch` 声明入口，`dependencies` 为空，只声明官方包的 `peerDependencies` |
+| RPC 通道 | 优先走 `connection.rpc.handle`，失败则自注册 webServer 路由（两条路径都有诊断日志）                     |
+| 打包内容 | `lib/`、`cordis.patch.yml`、`assets/`、`CHANGELOG.md`（构建产物不入库，`release:check` 会先 build）     |
 
-> 若当初是以**本地源码目录**方式安装的（`dsh plugin add <路径>`，依赖表现为 `link:` 指向源码目录）：更新方式为在源码目录执行 `git pull && npm install --legacy-peer-deps && npm run build`，然后完全重启 DSH 即可，无需重跑安装命令。
+---
 
-### 指定其他版本
+## 十、开发与验证
 
 ```bash
-dsh plugin add lume-dsh-plugin@0.7.0          # npm 指定版本
-dsh plugin add lume-dsh-plugin@latest         # npm 最新
-dsh plugin add github:cayan0x/Lume            # GitHub 最新 main
-dsh plugin add github:cayan0x/Lume#v0.6.0     # GitHub 任意历史标签
+npm install --legacy-peer-deps   # DSH 生态包与若干 rc 存在 peer 冲突，需要这个开关
+npm test                         # 跑全量用例（条数以当场输出为准）
+npm run lint                     # 架构规则 + 类型检查 + 机制覆盖 + 格式检查
+npm run build                    # 产出 lib/（构建产物不入库）
+npm run release:check            # 发布门禁：对着产物断言，每条绑一个历史事故
+npm run verify:live              # 真机清单（重启后跑：加载行 / 能力行 / RPC / 补蒸馏 / 知识 / 注入块）
+npm run format                   # 全仓格式化
 ```
 
-标签与版本的对应关系见 [CHANGELOG](./CHANGELOG.md)，建议始终使用最新标签。
-
-## 开发
+**三层护栏**：
 
-```bash
-npm install --legacy-peer-deps   # DSH 生态包发布在公共 npm
-npm test                         # vitest：单元测试 + 真实存储栈集成测试
-npm run build                    # tsc（宿主 lib/index.js）+ tsdown（客户端 lib/client.js）
-npm run watch                    # 客户端 bundle 增量构建
-```
+- **架构规则**：分层（core 不得依赖 host / client）· ESM 扩展名 · 禁 `console.*` · 静默失败必须写理由 · 抑制必须写理由 · 类型边界（裸 `any` 只允许在装配点）· 禁 `as any` · 依赖必须真的被使用 · 文档引用必须存在；
+- **机制覆盖**：从代码里枚举出全部机制（提示槽 / 触发器 / 工具 / 注入块），每一个都必须有"能跑出行为"的测试；
+- **发布门禁**：对**构建产物**断言，含"客户端产物可解析""无重复顶层声明"这类一旦退化就会让 Harness 起不来的检查。
 
-目录结构：
+工程约定与分层原因见 [ARCHITECTURE.md](ARCHITECTURE.md)；发布流程见 [RELEASING.md](RELEASING.md)；市场登记块见 [docs/hub-registration.md](docs/hub-registration.md)；版本变更见 [CHANGELOG.md](CHANGELOG.md)。
 
-```
-src/index.ts            宿主入口：注入 + RPC + 工具 + 事件接线
-src/core/               纯逻辑：种子采样、检索打分、衰减、对话挖掘、manifest 解析、文本组装
-src/host/               存储（选择/身份/项目）、蒸馏管线、提取器、工具、协议与文档能力、任务载具、行为触发器、RPC、注册表
-src/client/             前端：人设菜单、蒸馏弹窗、管理弹窗（插槽 conversation.input.left）
-lib/                    构建产物（随仓库提交，GitHub 安装路径依赖它）
-test/                   vitest 单元测试 + storage 栈集成测试（含带数据重开域回归）
-docs/screenshots/       README 截图
-```
+---
 
 ## License
 
-[MIT](./LICENSE)
+MIT © cayan0x