# You Should Know：设计规格

You Should Know 在用户的任务会话中观察重要事实、方案取舍和必要知识。当用户可能遗漏一个会影响当前决策的事项时，插件在输入框上方展示简短提醒，用户可以展开解释、表示已了解，或把事项带回主会话讨论。

本文记录首版行为规格。实现、确定性行为测试和运行入口检查已完成；真实界面交互与模型质量须按下文验收标准分别验证。

## 默认行为与可选设置

| 设置 | 默认值 | 菜单中的可选项 |
| --- | --- | --- |
| 自动观察 | 开启 | 开启、关闭 |
| 观察模型 | 跟随主会话的提供方和模型 | 独立选择已配置的提供方和模型 |
| 语言 | 跟随系统 | 跟随系统、中文、English |
| 观察步长 | 6 个模型步骤 | 6、12、18 或自定义正整数 |
| 每轮检查次数上限 | 不限（0） | 不限、1、3、5 或自定义非负整数 |
| 观察上下文 | 主会话的完整请求上下文 | 首版固定使用完整上下文 |

设置使用 Harness 的原生配置能力保存。独立选择观察模型不会修改主会话模型；切回跟随模式后，下一次观察使用主会话当时的模型。设置改变时取消或丢弃使用旧配置的在途结果。

跟随系统使用 Harness 当前界面语言，中文界面使用简体中文，其余语言使用英文；手动选择覆盖系统语言。界面文案和后续观察、解释请求使用同一语言。已经展示的内容保留原文。多客户端打开同一会话时，自动语言优先采用最早仍在线客户端的语言，避免心跳交替导致任务反复取消；该客户端离开或租期到期后才切换。

首版使用完整上下文，不增加裁剪或模型摘要步骤。跟随主模型时保留请求前缀，以便提供方尝试复用缓存；实际命中及费用取决于提供方和请求内容。

## 检查时机

每轮使用从 0 开始的步骤索引；仅当索引大于 0 且能被观察步长整除时获得检查机会。默认步长 6，对应索引 6、12、18 等。Harness 的步骤从 1 开始，因此对应步骤 7、13、19；开始新轮时重新计数，不跨轮累计。一个模型步骤可能包含多个工具调用，工具调用本身不单独计步。

以下情况跳过检查：子 Agent 会话、没有可展示提醒的界面、该会话正在检查、当前已有提醒或解释视图、当前轮已经成功展示提醒，以及忽略退避尚未结束。

每轮检查次数上限按会话和用户任务轮次独立计数，默认 0 表示不限。满足检查条件且实际发起的自动观察计为一次，失败、取消或没有提醒仍计入；检查机会被跳过以及用户展开解释不计入。一次观察内部的工具拒绝后重试仍属于同一次检查，因此上限不是模型生成次数或 token 用量上限。计数在请求发起前持久化，插件重载、同轮追加输入和修改设置不会清零；新轮使用新的计数。

检查在后台启动，主任务继续执行。没有发现值得提醒的事项时保持安静。默认不会因一轮结束而增加额外检查，也不提供自动纠偏。

## 观察请求

默认观察使用主会话当前的提供方、模型、系统提示和会话信息。观察者不读取新文件、不搜索、不执行命令，也不运行主 Agent 的工具；请求不进入主会话记录。一次观察最多进行两次模型生成。

观察在主会话完整模型请求的公开扩展点取得快照。该快照是 Harness 请求层的内容；模型适配器仍可能投影图片、文件和工具声明。插件不承诺逐字复制提供方最终收到的请求，也不承诺缓存命中或特定缓存费用。

提醒判断遵循以下规则：优先不提醒；一次只选择一个重要主题；考虑用户已经展示的理解，专业提问不必然代表前提正确；关注成本、时间、返工、结果和当前决策；跳过已讨论事项、主回答的中心内容、正在准备解释的内容、琐事、无关知识和缺乏证据的推测。主 Agent 在长回答或工具序列中提及过的重要事项，仍可能因用户未注意到而值得提醒。

两种语言的提示词独立表述同一组规则，要求避免复述密钥、令牌、凭证、环境变量值和个人数据，并保留事实的不确定性。此要求作用于生成内容，观察请求仍包含完整会话上下文。

提醒分为“值得了解”和“注意事项”：前者解释重要的系统或设计知识，后者提示当前任务的取舍或即时后果。观察提示词由本项目独立编写。

## 提醒和解释

提醒以输入框上方的悬浮面板显示，最大宽度 560px，窄屏保留边距。正文区域限制高度并允许滚动，展开解释不增加布局高度。用户可收起为提示按钮并重新打开，也可在面板内按 Escape 收起；此操作仅改变当前界面显示，不提交反馈或记录忽略。

模型输出支持无提醒，以及简短提醒、分类和可选解释。只要提醒可解析，缺省分类或解释不会自动拒绝它。无效输出不展示提醒；提醒正文最多 240 个 JavaScript 字符，缺少句末标点时补全。

简短提醒提供“展开解释”“已经知道”“关闭”。展开解释时优先复用首次观察已生成的同语言解释；缺少可用解释时再请求模型。升级前保存的解释没有语言标记，仍保留原文。解释请求失败时显示失败状态，不展示不完整回答。

展开后提供“已了解”“带回主会话”“关闭”。解释展示保留段落与示意代码；最多四个解释块，每个示意代码块最多十二行，每行最多一百二十个字符，段落和说明各有四千字符上限。

选择带回主会话时，输入框为空才填入提醒及解释，仍由用户发送。已有草稿时提示用户先发送或清空，不覆盖草稿，也不自动给主 Agent 发消息。首版支持 Web 与桌面共用的输入区；没有该输入区的 profile 不自动发起观察。

## 反馈、去重和退避

成功展示的提醒进入“已展示”记录；“已经知道”“已了解”“有帮助”和成功带回主会话将相关主题加入“已了解”记录。两类记录均为插件级、跨会话使用，各保留最近 50 条。

展示前同时检查两类记录，按忽略大小写及末尾句点的精确匹配去重。不同措辞的同一主题还需由观察模型结合记录判断，不宣称保证语义去重。

设置菜单分别列出两类主题，按最近记录优先显示；读取不依赖当前会话，关闭自动观察后仍可管理。清空需要用户确认，仅移除所选列表，保留另一类记录、当前提醒、每轮检查计数和忽略退避状态。清空成功后撤回使用旧记录的在途观察，迟到响应不写回；已打开提醒的解释请求继续执行。另一类列表仍参与去重，因此清空一类并不保证再次展示相同主题。

关闭提醒立即重置连续忽略和退避计数，并进入短暂反馈视图，提供与当前视图对应的“有帮助”“不相关”“未理解”等反馈；20 秒没有反馈则由计时器收起，开始新轮时也会收起。主动反馈同样重置计数；超时收起不再改变计数。

未展开的提醒在累计两次有效用户输入后收起，并计为一次连续忽略。已经展开的解释继续保留。退避规则如下，每遇到其余条件满足的检查机会，跳过计数减一。

| 连续忽略次数 | 跳过后续检查机会 |
| --- | --- |
| 1–2 | 0 |
| 3 | 1 |
| 4 | 2 |
| 5 | 4 |
| 6 | 8 |
| 7 及以上 | 16 |

## 状态与生命周期

会话记录最多保存 32 条，更新过的记录移到前端。超出容量时优先淘汰较早且没有近期开放提醒的记录；三天内的开放提醒优先保留。三天用于容量裁剪，不是所有记录的统一有效期。

每轮观察计数独立于提醒视图列表保存，每个会话保留当前轮次一条计数；超过 32 个会话也不会重置既有上限。会话销毁时清理其计数，插件卸载和重载保留计数。升级时兼容读取原先随会话视图保存的计数。

状态由 Harness 的存储域保存，路径和后端由宿主管理。持久状态只包含提醒、解释、主题和必要交互字段；主请求快照留在内存，不额外持久化整份会话或凭证。

界面离开、会话结束、设置变化和插件卸载需使旧任务失效。卸载清理订阅、计时器、在途请求和存储句柄；会话结束收起开放视图，保留必要的去重和已了解记录。取消请求不能保证远端停止计费。

开始新轮保留尚未完成的观察或解释。观察请求未被后续检查替换时，结果仍可展示；只有实际发起新检查才更新检查所属轮次。

## Harness 接入与开源交付

最低支持及开发基线为 DeepSeek Harness `0.2.0-rc.2`，兼容声明为 `>=0.2.0-rc.2 <0.3.0-0`，并对 `0.2.1-alpha.1` 进行回归。开发依赖固定版本保证验证可复现，安装兼容声明允许 0.2 系列升级。服务端使用 `llm/stream` 公开扩展点、`session/event` 和 `storageDomain`；客户端使用 `conversation.input.dock`、原生输入操作和 `settings.section`。不修改 Harness 主循环或已安装应用。

链接安装时宿主与插件可能加载不同的 SDK 副本，模块内的主请求标记不共享。插件同时核对宿主发起者、冻结请求及完整会话消息身份；旁路调用使用 `withoutInitiator` 清除发起者归属，避免把自身请求当作主循环。有效用户输入按 `user/message` 事件计数，步骤开始本身不计为用户输入。

插件通过 Harness 已配置的模型服务调用模型，不另建持有 API Key 的客户端。客户端请求使用宿主认证传输；反馈操作校验会话、当前提醒身份和状态，过期操作不改变新提醒。项目不新增遥测、外部反馈上传或服务端账号门禁。

项目采用 MIT，代码与提示词独立编写。交付包含明确的安装方式、配置说明、兼容版本、贡献方式和问题反馈入口；引用第三方代码时保留其许可证要求的声明。

## 验收标准

验证必须覆盖步骤索引映射、检查并发、同轮展示上限、检查次数上限及重载恢复、主题分别清空和迟到响应、输出解析、已有解释复用、工具禁止、草稿保护、反馈超时、忽略退避、跨会话去重、状态容量、语言和模型配置切换、旧轮询竞态和卸载清理。

类型检查、行为测试、构建及安装包检查通过后，还需在真实 Harness 中验证加载、提醒展示、菜单保存、输入交互和状态恢复。模型提醒质量、中文效果与实际用量单独验收，不以 Mock、静态源码分析或浏览器组件检查代替。