---

一、任务执行协议

这是可公开复用的工程工作协议，不是模型隐藏思维链。协议注入每个会话；无论选择哪个人设（包括「不使用人设」），都始终生效。

层	防范目标	规则
上下文管理	上下文衰减	保留目标、约束、已完成事项、关键决策、错误与已排除假设
任务分解	复杂任务失控	拆成可验证步骤，优先处理阻塞项和高风险项
自适应投入	简单问题过度分析或复杂问题草率处理	低风险问题快速收敛；复杂、高风险或不确定问题增加调研、比较与验证
信息路由	在无关内容上浪费上下文	优先定位高影响入口和数据流；无依赖的只读检查可并行
阶段门控	未调研即动手	先理解和只读检查，再执行写入
变更保护	覆盖用户状态	修改前完整读取，最小范围变更，保护用户已有改动和数据
验证闭环	修改后不确认	测试、类型检查、构建或最小复现；失败先归因再重试
振荡预防	修改—回滚循环	连续失败后更换方案，不重复已排除假设，不制造假成功
结果复核	把部分完成说成完成	对照需求、边界、兼容性和数据保留，明确已实现与仍有限制

意图路由与长会话护栏

协议会先把当前请求归类为五种行为模式，而不是默认把所有消息当成执行命令：

• 问答：直接回答，不擅自改文件或调用写入工具
• 查找：先核对来源、已知和未知，不未经授权改变外部状态
• 讨论：比较方案、取舍和风险，不把探讨中的方案提前当成决定
• 诊断：先给现象、证据、根因和验证办法，不越权修复
• 执行：确认目标和完成标准，完成后验证真实效果并检查副作用

会话达到第 6 轮后，插件才启用短版长会话护栏和“当前目标锚点”：以当前消息和最新状态为准，把旧计划、旧时间、旧事实和助手过去的自述视为候选信息；每次动作都要检查是否生效、是否留下副作用。这样不会给短聊增加固定成本，也能缓解长对话中上下文变长后“越来越笨”的问题。

协议不要求输出隐藏的逐步思考过程；对外只输出与任务复杂度匹配的结论、计划、变更和验证结果。简单问题保持简洁，复杂问题增加必要依据和边界说明。人设只影响自然语言表达，不影响代码、工具调用、结构化输出或安全判断。

协议自适应与闭环

任务协议不是一段每轮机械重复的说明，而是会根据会话状态和模型能力动态调整：

• 会话内自愈 —— 当同一用户请求连续两轮出现明确的失败、报错、超时或权限错误信号时，临时追加“先定位根因、记录已排除假设、选择不同方案”的纠偏条款；下一轮成功后自动解除。为避免误判，普通的重复提问不会单独触发该机制。
• 即时对齐纠偏 —— 用户说“不是这个意思”“你理解错了”或重复提出相近请求时，本轮立即要求先复述目标、检查上一轮是否答非所问，不沿用旧假设，也不原样重复上一轮。
• 反思回环 —— 会话结束后的协议复盘会保存在本地。最近多个会话中某一项持续低分时，下一会话只注入一条针对性提醒；表现恢复后自动淡出。反思摘要不会把完整历史日志带入上下文。
• 模型感知 —— 普通闲聊使用短版协议；复杂任务按模型能力选择协议长度。已确认具备推理能力的模型保留变更保护、验证、失败归因和结果复核，减少重复的计划说明；无法确认模型类型时使用完整协议作为安全回退。

这三层共同形成“常规协议 → 检测问题 → 临时强化 → 成功解除 → 跨会话复盘”的闭环，在需要深度处理时增加约束，在简单问题上控制 Token 消耗。

文档能力感知（与文档工具插件协作）

DSH 本身不带 Office / PDF 读写能力：附件只接受图片，工具名册里没有任何文档工具。模型面对 .docx、.xlsx 这类二进制容器时，只能在“当文本读”“现场解压 zip”“手写解析脚本”之间瞎试——慢，而且几乎必然出错。

微光不重复造这套工具，而是做能力探测与约束：注入前查询宿主的工具注册表，按工具名的能力族前缀（word_* / excel_* / ppt_* / pdf_* 等）判断当前环境具备哪些文档能力，再据此分叉——有工具时要求走工具而不是自己解析、先读后写、交付前回读验证；没有工具时要求第一轮就如实说明边界、不要静默硬解二进制，并给出替代交付方式。用户明确说「就用脚本自己试」时仍然照做，但要先说明代价。

两条都只在文档任务轮注入：闲聊、代码、排查类请求零成本，只有请求里出现文件后缀、Word / Excel / PPT / PDF 等格式名，或“写一份报告”这类产物请求时才生效；中文里“查一下官方文档”这种泛称不会被误判成文档任务。判据取自冻结的意图文本，因此在一轮之内稳定，不会像工具结果那样在轮中作废前缀缓存。探测按能力族前缀而非插件名，因此不绑定任何第三方实现——dsh-office-tools、dsh-excel-chat、dsh-ppt 装了哪个都能识别，一个都不装就退化为边界声明模式。

优化清单

• 问答、查找、讨论、诊断、执行五类请求路由
• 诊断不越权修复，讨论不提前替用户拍板
• 用户纠正和重复提问的即时对齐纠偏
• 相同请求连续失败后的归因纠偏与换方案提醒
• 第 6 轮起的长会话护栏与当前目标锚点
• 执行任务的“已完成 / 已验证 / 未验证 / 副作用”交付清单
• 上一轮执行回复缺少验证证据时的后续复核提醒
• 任务阶段状态机：回答 / 查找 / 讨论 / 归因 / 执行 / 验证 / 交付
• 真实工具证据：区分工具成功、失败和结果未知，不把工具调用本身当作目标完成
• 证据时效：引用日志/历史/旧报错前核对时间戳与因果，不用旧错误填空
• 记忆生命周期：相对时间记忆标记为临时记忆，30 天后自动失效；旧记忆无感兼容
• 反思日志跨会话反馈、旧字段迁移和模型感知协议
• 上下文压缩感知：识别宿主压缩检查点，压缩后重锚状态并提醒“摘要不是完整历史”
• 文档能力感知：探测文档工具并按需注入——有工具要求先读后写与回读验证，没工具要求如实说明边界、不硬解二进制
• 系统提示词轮内稳定：意图冻结（只认真实用户消息）+ 会变的内容走 runtime-context 通道，一轮只产生一份系统提示词
• 注入分层：system 段在会话内逐字节恒定（协议/契约/身份/纪律），记忆、语料、播报与任务指令全部走对话尾部快照——每一步都吃住前缀缓存
• 任务载具：任务契约（数量先估后回填、交付按原始判据对账）+ 改动台账 + 假设台账（含已排除项）+ 跨会话项目知识
• 行为触发器：按轨迹纠偏——撒网不收敛 / 连写不验 / 死路重撞（环境类给验证降级阶梯）/ 契约对账 / 项目知识采集
• 方法层：文档编辑方法（结构 → 最小编辑 → 一致性 → 回读）、改动影响面清单、结构定位提示
• 反思日志第五维「诊断深度与假设管理」：跨会话提醒能指向思维方式而非只有纪律
• 角色卡算法自动升级且保留记忆、风格和认可语料

为什么不接管宿主的历史压缩

压缩服务由 DSH 的 agent preset 在自己的隔离域里挂载（isolate: { compaction: true }），profile 层的插件注册的同名服务不会被 /compact 或自动压缩使用——第三方插件在标准 preset 下无法替换压缩后端，这属于宿主的架构边界，不是接口开放与否的问题。

Lume 因此选择「观察 + 重锚」：压缩发生时记录规模，在随后一轮注入提示，提醒模型摘要只保留要点、依赖早期细节时先确认；压缩产生的摘要消息带固定来源标记，Lume 用它把摘要与真实用户消息区分开，避免摘要污染当前目标与协议路由。人设契约、长期记忆与协议本身注入在 system prompt 段，不参与对话历史压缩，因此不受影响。

二、人设系统：「人设即人」

微光的人设是具名的独立个体，而非一段静态的性格描述：

• 记忆以人设为主键，跨会话、跨项目持久 —— 在绘画项目中告诉晚晴「以后叫你阿晴」，她在任何项目、任何新会话中都保持这一身份。记忆存放于 DSH 官方 storageDomain（storages/lume_persona_identity.json），完全本地
• 性格随对话演进 —— 内置风格契约是基础盘；对话中提出的语气要求（「少用 emoji」「自称改为 XX」）会固化为该人设的「习得的风格约定」，跨会话生效，与基础盘冲突时以习得层为准
• 切换带接班播报与持续纠偏 —— 切换人设时，新任人设在回复开头明确接替；此后逐轮检测回复是否残留旧人设的口头禅与称呼（零 token 的词法检测），检出即重新注入升级版纠偏播报——长对话中切换同样可靠
• 双通道记忆写入 —— 主通道为模型主动调用工具（lume_remember / lume_update_style / lume_create_persona），随对话发生、零额外调用；安全网为被动提取，经三道门（关键词正则 → 相似去重 → 冷却）过滤后仅对触发轮调用模型，绝大多数轮次零消耗
• 对话创建 —— 对当前人设说明「想建一个新的人设」，模型将通过访谈收集设定（名字、性格、说话方式、称呼）后保存，新的人设立即出现在菜单中

切换时机提醒：在新开的会话里切换人设，新任人设即刻生效；但在已经聊了一阵的会话里，仅仅点一下菜单切换往往不够——大模型有思维惯性，会沿旧人设的口吻继续说话，不会立刻「换皮」。此时要在对话里明确告诉大模型「切换到 XX 人设」（如：「现在用福尔摩斯的口吻回复」），让它在下一轮真正进入新角色。插件自带的接班播报与持续纠偏能加速这个过程，但无法替代你的一句明确指令。

菜单固定在输入栏左侧：「不使用人设」置顶，可随时回到默认风格；内置角色卡随后；底部为蒸馏与管理入口。列表异步加载完成后自动重新钳制视口，输入栏置底时菜单保持完整可见、可滚动。

内置卡与自定义卡在同一菜单中平铺：内置的噜噜（元气管家娘，口头禅「好哒哥哥～」）、晚晴（低频高载的姐姐，口头禅「……交给我」）、沈砚（儒雅管家，口头禅「这就去办，主人」）、江野（嘴硬心软的傲娇，口头禅「……切」「才不是特意帮你」）受保护不可删除；自定义的 Jade、坂田银时、福尔摩斯 等由蒸馏或对话创建，可随时编辑、删除。

三、蒸馏工具：从素材到角色卡

菜单中的「＋ Distill a character card…」提供批量生产角色卡的路径：粘贴（或导入 .txt/.md）一段小说、剧本或人物设定文档，由宿主侧管线将其蒸馏为一张与内置卡同构的角色卡。

管线分三步：

1. 对话挖掘（零 token）：抽取台词、统计说话人、保留双边情境窗口、时间间隔和可观测风格统计；归属不足时标记 mixed，由 LLM 甄别目标角色
2. 证据约束的契约合成：每条稳定特征都要求原话/情境证据、触发场景和频率，避免把单一场景脑补成固定人格
3. 语料合成：聊天记录优先使用全时段真实对话对；小说、剧本和设定文档也按“场景→行为→原声”组织示例，优先复用原句，禁止中和为通用回复

蒸馏算法与角色卡自动升级

角色卡保存蒸馏算法版本、目标角色和本地原始素材升级源。插件升级后会在后台检查旧版本角色：有升级源时自动重新蒸馏，只替换基础契约和基础语料；记忆、习得风格、用户改名和对话中沉淀的认可语料保留不动。升级失败时继续使用旧卡，不阻塞对话。

原始素材只保存在本地身份域，不注入普通对话上下文，也不会上传。旧版本且没有原始素材的卡片只能做兼容迁移，无法恢复旧算法已经丢弃的证据。

从聊天记录蒸馏一个人

粘贴微信 / QQ 导出或复制的聊天记录，蒸馏工具会自动识别时间戳锚点切分说话人（剔除 [语音] / [图片] / [表情] 等占位符），并在弹窗中列出检测到的说话人供点选——点选要蒸馏的人，对方的每一句话成为语气样本，你发出的每一句话归为用户侧，真实对话对直接作为语料，无需 LLM 改写，原汁原味保留本人的说话方式。对话量建议 50 条以上，蒸馏出的角色才足够立体。

• 预览中所有字段可编辑，保存后立即出现在人设菜单
• 素材经 RPC 以任务制交由宿主后台蒸馏（约 10~90 秒），不进入对话上下文，不影响当前会话；蒸馏过程中弹窗不可误关，关闭需二次确认并会中止任务
• 素材上限 20,000 字；素材按不可信文本处理，其中出现的任何指令不会被执行
• 蒸馏路由可通过 distillProvider / distillModel 指定专用模型档，默认跟随主对话模型

非聊天素材的统一蒸馏原则

小说、剧本和人物设定不再简单当作性格简介：按角色、场景、连续对白建立“谁在什么情境下说了什么”的证据链；分别观察平淡、冲突、亲密、拒绝等场景。设定文档只作为低置信度身份与边界线索，没有原话支持的内容不会伪装成口吻特征。所有素材最终统一为原声证据、情境行为、表达风格、身份边界和置信度。

四、管理自定义人设

「管理自定义人设…」列出全部条目：内置卡的编辑与删除按钮置灰（受保护），自定义卡支持：

• 导入人设卡 —— 从 JSON 卡片文件导入一张完整人设（含契约、语料、风格约定与记忆），同名覆盖需二次确认
• 导出 —— 任一人设（含内置）可导出为自包含 JSON 卡片文件，可选是否附带记忆，跨设备可还原
• 删除 —— 行内二次确认；删除同时清除该人设的记忆、习得风格与身份档案，不可恢复
• 记忆 —— 打开该人设的记忆星图（见下节）
• 编辑 —— 显示名、简介与风格契约全文可修改（英文键名为存储主键，创建后不可变更；语料只读展示，语气随对话继续演进）

自定义人设与内置人设能力完全一致：对话改名、记忆积累、风格演进全部支持，区别仅在于自定义人设可以删除。

五、记忆星图

管理弹窗中每个人设行内都有「记忆」按钮，点击后以力导向星空图的形式可视化该角色的全部长期记忆。

• Canvas 力导向布局 —— 记忆卡片（260×72）在 960px 宽幅遮罩层中自动排布，核心记忆紫色带 ★、普通记忆青色，语义相关者连线，背景缓慢漂移
• 日期筛选 —— 顶部支持 全部 / 最近 7 天 / 30 天 / 90 天 过滤
• 行内编辑与删除 —— 点击卡片展开详情面板，可即时修改记忆文本或删除整条记忆，经 updateMemory / deleteMemory 持久化写入存储

六、反思日志

会话结束时，插件在空闲时间跑一次小模型调用，对整段对话的任务执行协议执行情况进行复盘：上下文管理、计划与门控、验证与失败处理、结果复核，各打 0-2 分并附一句中文备注，写入 lume_reflection 域。

升级到 0.4.0 时，旧版反思日志会在域打开后自动从旧字段迁移到新字段；迁移幂等，不影响角色卡、记忆或会话。

• 零用户感知 —— 不进入对话上下文，不消耗正常请求的 token 配额
• 定性分析 —— 积攒数周后读取存储文件即可复盘对话质量，无需猜测
• 可关闭 —— 配置项 reflectionEnabled 默认 true，置为 false 即停用

七、人设卡片导出/导入

在管理弹窗中，任意人设（内置或自定义）均可导出为独立的 JSON 卡片文件，并在其他设备或他人环境中导入还原。

• 导出格式 —— 自包含 JSON（lume-persona-card v1），含契约、语料、风格约定、声音签名，可选含记忆
• 导入校验 —— 解析时校验格式、版本、键名合法性，内置人设名受保护，不可覆盖
• 跨设备迁移 —— 一张卡片即可还原人设的完整身份（记忆、风格、档案名），无需额外配置

任务载具：把量化与台账变成可检查的产出

纪律（协议正文）教的是「不越权、要验证、要复核」；方法教的是「怎么把一个任务收敛成可核对的产物」。后者需要载体——模型通常不是不知道要量化，而是没有地方放量化结果。四个载具都由模型自己写（工具调用、零额外 LLM 调用），每轮按状态回显到对话尾部：

载具	工具	内容	生命周期
任务契约	lume_contract	目标 / 范围 / 数量（先估后回填） / 完成判据 / 非目标 / 待确认	会话内；交付轮自动切成对账口径——对照的是开工时写下的原始判据，防「判据漂移」
改动台账	lume_change	文件·符号·章节 → 改什么 → 为什么 → 怎么验 → 状态	会话内；文档任务用章节名当 target，形成分节记账
假设台账	lume_hypothesis	假设 + 证据 + 状态（含已排除）	会话内；已排除项照常回显，避免重复验证同一个假设
项目知识	lume_project_note	构建/测试命令、模块链路、仓库约定、死路记录	跨会话，按工作目录归属

项目知识为什么单独存放：代码路径与仓库约定是工作事实，换人设不该失忆，也不该随人设卡被导出分享。环境性死路会被自动记入（例如「本机 Maven 离线仓库为空」），下次会话不必重踩。

行为触发器：把「元决策」从用户手里接过来

一次真实会话的轨迹复盘（2 轮 / 58 步 / 106 次工具调用）显示：不是不知道该收敛，而是在压力下没有执行——34 次广度探查不收敛、25 次改动里 18 次连击无验证、17 次命令全在撞同一个不可用的构建环境、交付前靠用户发话才自审。协议正文管不了这种，因为文本是静态的，而症状是轨迹的。所以只在行为模式成立时注入一句带具体数字的提醒：

触发器	触发条件	注入
收敛提醒	连续 ≥12 次只读探查且尚未写契约	停止撒网，先复述「入口 → 数据流 → 影响面」并写台账
增量验证	连续 ≥6 次改动没有任何验证动作	改一处验一处，先验证前一批
死路重撞	同一验证连续失败 ≥3 次	环境类占多数 → 验证降级阶梯（编译器 → 语法检查 → 静态交叉引用 → 手工走读 + 风险清单）；否则要求先归因并写假设台账
假设维护	诊断模式下验证失败但假设未更新	更新假设状态，标出已排除项
契约对账	有契约且每 3 轮 / 压缩后	用原始判据逐项对账，标注已验证 / 未验证 / 偏离
项目知识采集	无契约且步数 ≥20（每会话一次）	提醒把稳定项目事实记下来

每类触发器每轮最多一次且有轮级冷却（提示一多就变噪音）；工具按行为类别（inspect / mutate / verify / plan）归类而非按名字，宿主或扩展换名不失效。

方法层：按任务形态注入

• 文档任务：先取结构（标题层级 / 表格清单 / 编号体系）→ 最小编辑保留格式与编号 → 术语与称谓全文一致 → 交付前回读改动区域并列出「改了什么 / 没动什么 / 未核对什么」
• 执行轮：改动影响面清单（谁调用它、被谁实现、配置与 SQL 映射、前端引用）+ 每处改动的验证方式
• 有结构分析工具时：建议用符号级定位替代通篇 read

分层注入与 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 秒，所以这不是缓存过期。分层后恒定段一次构建全程命中，易变段落在尾部、改它不作废前缀。

注入段	层	无优化	优化后	使用的算法
任务执行协议	恒定	~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	六类行为模式 + 轮级冷却

• 恒定段（协议 + 契约 + 身份）约 900 tok，在一个会话里建一次、之后每步都是缓存命中
• 易变段稳态约 700~1,200 tok/步，全部落在对话尾部：改它只花自己那点 token，不动前面的任何前缀
• 静态内容前置于易变内容，叠加 DeepSeek 前缀缓存后，有效成本可再降约一个数量级

怎么确认分层还成立：$DSH_HOME/lume-compaction.log 里每个会话应只有 1-2 行「系统段指纹」（首次 + 人设切换）。若长会话里反复出现新指纹，说明又有内容混进了 system 段——test/injection-layering.test.ts 就是在锁这条不变量。

旧宿主降级：宿主不支持 systemPrompt.context（0.1.5 之前的版本）时，易变段并回 system 段——丢前缀缓存但不丢记忆与播报注入，启动日志会写一条 warn。配置 layeredInjection: false 可手动退回旧行为做对照。

配置项

配置项	默认值	说明
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
• 全部数据保存在本地，不上传任何远端

宿主兼容性

• 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 即可安装：

dsh plugin add lume-dsh-plugin

从 GitHub 安装（备选）

若网络无法访问 npm，也可直接从仓库安装：

dsh plugin add github:cayan0x/Lume#v0.7.0

安装后需**完全重启 DSH（包含托盘进程）**方可加载；启动日志中出现 lume: 已加载（builtins=loli,senpai,butler,tsundere,none） 即表示加载成功。构建产物随仓库发布，两种路径都不需要本地构建。

从旧版本升级（已装过微光的电脑）

重新执行一次安装命令即可升到指定版本，随后完全重启 DSH（含托盘）：

dsh plugin add lume-dsh-plugin   # npm（推荐）
# 或
dsh plugin add github:cayan0x/Lume#v0.7.0   # GitHub（备选）

人设选择、记忆与风格数据存放在 storages/ 目录，升级不会丢失。

若当初是以本地源码目录方式安装的（dsh plugin add <路径>，依赖表现为 link: 指向源码目录）：更新方式为在源码目录执行 git pull && npm install --legacy-peer-deps && npm run build，然后完全重启 DSH 即可，无需重跑安装命令。

指定其他版本

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 任意历史标签

标签与版本的对应关系见 CHANGELOG，建议始终使用最新标签。

开发

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 增量构建

目录结构：

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