用户体验优化路线
本路线跟踪 Issue #829。目标是让使用者更容易配置一个实用功能，理解它在哪里生效，并在执行失败后自行定位原因。框架仍面向生活与工作场景中的多通道 IM 助手，不扩展为独立产研工作流产品。
本文是实施与验收计划。已有基础、正在实现和后续计划分别标注；列入路线不代表功能已经交付。既有安装改进详见插件体验计划。
实施状态与顺序
| 批次 | 优先级 | 范围 | 状态 | 依赖 |
|---|---|---|---|---|
| A | P0 | 单条入站消息的有界诊断、可读文本降级；Console 展示与排错入口 | Host 与 Console 已合入各自主分支；真实平台验收未执行 | 当前消息链与当前 generation 快照 |
| B | P0 | 按用途配置的首条任务路径 | 管理员提醒与 RSS 用途已合入；欢迎连续导航与人工核验见开放的 Console #25；关键词仍为真实群命令指南 | 复用安装、配置、应用与业务验证；复用 A 的故障解释 |
| C | P0 | 精确生效范围选择、查看与权限解释 | 欢迎精确入站范围与 builtin 权限解释已随 #837 合入，对应 Console 页面已合入；其他能力按契约逐项扩展 | 完整会话身份；明确各能力的入站或投递边界 |
| D | P1 | 任务中心、自然时间与补问 | 管理员提醒、个人提醒补问与管理员 RSS 首条路径已合入；其他任务来源待接入 | 明确任务 ownership、持久化与 C 的目标选择 |
| E | P1 | 通用准入、配置解释、通知节制 | 指令准入 #840 已合入；配置 Host #841/#846 已合入，Console #22/#24 开放；RSS 静默摘要 #842 开放 | A 的结果分类；C 的隔离身份；D 的任务状态 |
| F | P1 | 场景试验台、文档与运行时入口连通 | 真实导出回归与指南 #843、诊断文档入口 #838 已合入；场景 UI Console #23 开放 | 前述稳定契约与可复现验收场景 |
每批做成可独立评审的纵切片，先交付一条真实用户路径，再扩展用途与适配器覆盖。所有批次使用 Issue 分支与 PR；文档或本地测试通过不能代替前端、完整 CI 或平台实机验收。
跨平台的共同边界
精确身份
会话和范围必须保留 ConversationRef 的全部身份字段：
endpoint.adapter + endpoint.id
kind + id
parent.kind + parent.id（如有）
threadId（如有）endpoint.id 是完整的 Endpoint capability id，不能用显示名或局部账号名代替。展示名只用于帮助识别。结构化编码必须区分字段缺省与具体值，不用裸会话 ID 或冒号拼接字符串作为唯一隔离键。
选择一个会话，默认只匹配这个精确会话。是否包含子话题、整个父容器或同类全部会话，必须是显式选项，不能通过忽略 parent 或 threadId 获得。多账号相同会话 ID、不同父容器相同频道 ID、同会话不同话题均须有隔离回归。
已有 group(id)、channel(id) 等权限 DSL 的语义不能未经评审就改成上述精确范围。当前权限投影没有完整携带父容器和话题，后续应明确补充契约与准入位置，不把现有快捷字段直接当作精确目标。
按目标解析能力
下表是设计与验收矩阵，不是任何平台的固定支持清单。每次操作应根据选定 Endpoint、目标会话、当前 generation 及可用渲染资源解析能力；未声明、未实现或未确认的能力不能显示为已支持。
| 目标具备的能力 | 期望表现 | 不满足时的路径 | 必验边界 |
|---|---|---|---|
| 仅文本 | 有层次的标题、摘要、编号、可执行的文本指令和可读链接 | 保留核心信息，不暴露 HTML 或内部 Segment 对象 | 长文、特殊字符、无预览链接仍可理解 |
| 原生 Markdown | 使用目标实际支持的语法组织信息 | 不支持的结构转可读文本 | 不把通用 Markdown 支持等同于所有扩展语法支持 |
| 可发送图片，且 HTML renderer 可用 | 对适合的内容生成图片，并保留必要操作说明 | 渲染失败或 renderer 不可用时走可读文本 | renderer 可用不等于目标可收图片；目标可收图片不等于 renderer 存在 |
| 原生按钮或其他交互 | 在已支持的动作协议与生命周期内提供操作入口 | 提供等价文本命令或明确操作路径 | 当前会话、generation、权限、分页边界和禁用状态 |
| 只有图片、没有原生交互 | 图片展示信息，操作放在可读文本中 | 不绘制会让用户误以为可点击的有效控件 | 图片外的指令足以继续操作 |
| 平台缺少目录、角色或状态查询 | 明确显示未知或需确认，允许按规范输入精确目标 | 不伪造列表、权限和在线结论 | 无查询能力与查询失败分别解释 |
所有发送复用统一消息链。目标能力的判定、内容降级与平台投递不能形成独立的第二条发送路径。纯预览不发送消息、不执行按钮动作，也不证明真实投递成功。结果为 unknown 时不得自动重发；先核实原会话与平台结果，再由使用者选择后续操作。
1. P0：从一条消息解释没有回复的原因
已有基础： 入站与出站链、Command 准入、Endpoint 状态、日志、Console 会话视图与插件诊断已经存在。当前Console 排错路径仍需要使用者在多个入口间关联线索。
本批实现： 在单条入站消息执行期间记录有界诊断结果，连接 Console 的单消息与当前会话入口；同步改善降级为文本时的可读链接、列表和表格。文本按钮的禁用项不分配操作编号。具体阶段以实现实际记录的范围为准，不将未覆盖的 AI 子步骤、平台回执或自定义中间件行为显示为已观测。
本地已验证 Core 与 Host 回归、独立 Console 测试/类型/构建，并用真实 Runtime 生成的脱敏诊断夹具进行桌面与窄屏浏览器验收。该浏览器验收的 API 使用本地夹具，证明前端展示和交互，不证明真实平台消息投递或已部署版本。
诊断只记录必要的身份、阶段、结果码与经过控制的摘要，不记录消息正文、提示词、完整工具参数、密钥或任意异常对象。记录须有数量与大小上限；首版不默认持久化成完整消息审计库。普通聊天不因为未匹配指令而收到额外错误消息。Console 鉴权与诊断可见性应保持一致。
端到端验收： 发送一条正常消息、一条权限拒绝消息、一条执行失败消息以及一条触发渲染降级的消息；授权使用者能找到各自诊断，看到实际观测到的阶段和可操作的下一步。无权限请求不能读取记录，正文与秘密不进入诊断，超出上限后记录有界清理。未命中命令仍按普通聊天链处理。
2. P0：按用途配置功能
已有基础： CLI 与 Console 已共享安装权威，具备安装计划、精确包版本、配置校验、应用、当前 generation 状态与显式业务验证。它们是复用对象，不再重建安装事务。脚手架与 zhin setup 已共享 scaffold-wizard。
已合入： zhin use-cases 与 Console 读取同一份用途目录。提醒区分管理员任务入口与个人聊天指令指南；管理员 RSS 已随 #839 接入现有任务端口。欢迎通过精确范围配置选择账号与群；省略范围保留所有符合事件条件的群，空列表表示全部关闭。管理员任务保存在插件独立持久池，不伪造聊天用户；多实例与精确投递目标必须明确选择。
开放实现： Console #25 将群欢迎串成选择实例、市场计划、原配置表单、详情应用和人工核验的连续导航。它仍在评审，不能当作已合入或已部署功能。人工记录不伪造入群事件、不自动归因或执行平台检查，环境引用不能从原始文件推断为可用；具体路径见群欢迎指南。
待扩展： 关键词等用途尚未完成连续流程，仍由真实群成员使用现有聊天命令。用途描述只引用现有插件与配置契约；包、插件实例和业务任务仍由各自现有 authority 管理。继续区分已安装、已配置、已应用和已验证，不把配置指南本身登记为功能交付。
插件实例声明已随 PR #828 合入 main，按 configVersion: 2 配置。用途入口仍选择明确实例；包对应多个实例时要求选择，不能推断别名。
端到端验收： 在没有该用途配置的项目中，从用途入口完成一项功能，查看精确变更，保存并应用，再在选定会话显式验证。中途断线后先读取真实状态核对，不重复安装或投递；配置冲突时保留草稿。平台缺少目录查询时能理解限制并选择明确目标。验证前不能显示业务成功。
3. P0：可视化生效范围与权限解释
已有基础： 统一 PermissionHost、builtin permit DSL、真实命令准入与 canonical 会话契约存在；部分插件已经使用完整 DeliveryTarget 隔离持久状态。
已合入的首条入站范围： #837 的群欢迎使用 welcomeConversations 精确白名单，完整比较 Endpoint、会话、父容器和话题；缺省、空列表与具体列表分别表示全部、关闭和精确匹配。Console 通过已有配置表单、Host 校验、保存和应用管理它，删除最后一项保持关闭，恢复全部需要再次确认扩大范围。页面显示的是草稿范围，不冒充当前生效状态。欢迎仍发送到实际事件的原会话，其他插件能力不受该字段控制。
已实现的权限解释： Console 从当前运行代读取命令目录，静态查看声明，或填写完整目标、发送者和角色作假设检查。解释复用真实命令的 builtin 匹配与主体投影，保留缺少依据及未评估状态；不调用命令、参数默认函数、平台或自定义 checker。group(id) 等现有规则仍只约束类型和 ID，页面保留完整目标不表示这些规则约束了 Endpoint、parent 或 thread。身份和角色由使用者假设，结果不是授权。
待实现： 将精确入站范围逐步扩展到其他有明确契约的能力。入站触发、出站投递与单条任务目标分别表达。配置归现有 Host 配置 authority，任务目标和业务数据归相应插件；不新增一份与事实脱离的 Console 范围数据库。
权限解释必须说明依据。自定义及平台 permission checker 可以执行任意异步代码，当前没有只读、幂等或无副作用保证，不能为“试算”无条件运行。首版可解释 builtin 规则，将未执行的平台或自定义规则标记为“未评估”；手动填写身份与角色的结果仅是模拟，不得成为正式授权。本文不要求改变现有默认权限语义。
端到端验收： 配置账号 A 的一个精确会话，A 的目标消息生效，账号 B 的同名同 ID 会话不生效；parent 或 thread 改变后不自动扩大范围。保存后重新打开能看到一致规则，真实准入与解释无矛盾。未知角色或未评估 checker 不显示为通过，打开试算不会执行自定义 checker。
4. P1：统一查看提醒、订阅与定时推送
已有基础： 持久提醒、订阅和调度能力已有各自的数据与执行机制，提醒已有失败与投递不确定处理。任务中心不代替这些插件存储。
已合入的提醒路径： PluginTaskProvider 在当前运行代发布管理员任务事实，由插件持有 CAS 版本与操作回执。Console 支持提醒创建、暂停、编辑、恢复、取消和未知命令对账；聊天个人任务保持原归属。真实 SQLite、实际 ReminderService 与 HTTP 集成覆盖长正文、幂等重放、过期恢复、未知投递与鉴权。两池共用现有 worker 和批次上限，跨扫描轮转避免管理员任务饥饿。个人提醒的自然时间见下一节，管理员时间字段仍要求显式 ISO offset。
已合入的订阅路径： #839 将管理员 RSS 接入同一任务投影与通用 Console 表单，保留完整目标、真实状态和动态操作。首次抓取与恢复只建立基线，不补发；按轮询事实显示结果，不伪造下次执行时间。投递 unknown 不自动重试或提供恢复，详见订阅指南。
待扩展： 其他任务来源逐项接入标准投影，按实际能力显示来源、所有者、精确目标、时区、下次执行时间、状态和最近结果；不为未知能力生成可执行按钮。任务事实仍由原插件持有，权限由服务端核验。
端到端验收： 创建任务、重启服务后查看一致状态，修改或取消能反映到真实任务；不同账号与会话任务不混淆，其他使用者不能越权取消。unknown 明确提示先核实，不自动重发或伪装失败后重试。
5. P1：自然时间与补问
已有基础： 提醒有明确时间格式、延迟和周期指令，Agent 提醒工具与对话交互基础存在。不能把新增便捷入口描述成此前完全没有自然语言或交互能力。
补问前置修复： 共享问答在提示发送前登记等待，早到回答先暂存，只有发送确认后才交给业务；发送失败、取消、超时、作者退役或运行代切换都会撤销等待。每题按钮使用独立短 callback token，旧按钮和其他能力的回调不能回答当前问题；纯文本仍可输入。Slack 回调保留真实话题身份。不把协议回归当作真实平台发送证明。
已实现的个人提醒路径： remind create 无需 AI，按实例 IANA 时区解析“十分钟后”“明天九点”等有限中文表达与含 offset 的 ISO 时间；缺少时间或正文时逐项补问。纯文字预览保留完整正文、绝对日期、时区与原会话，明确回复“确认”才保存。取消、过期、超时、代切换与投递不确定不会自动创建或重试。固定一天按 24 小时，日历周期未纳入；裸时钟、过去的今天和夏令时重复／不存在时刻不猜测或顺延。入口见提醒指南和 zhin use-cases personal-reminder。
端到端验收： 不启用 AI 也能完成受支持表达；缺时间时只补问必要字段，超时、取消和多会话并发不串话。跨时区日期、无效时间和歧义表达结果可解释；不支持的表达回退到明确格式。补问按钮不可用的平台能用文本继续同一流程。
6. P1：统一冷却、并发与重复触发准入
已合入的指令路径： #840 支持按指令显式声明 execution.cooldownMs、maxConcurrent 与 progressAfterMs，未声明的指令保持原行为。额度按真实指令 capability、发送者与完整会话隔离，别名和快捷方式共享；占用持续到业务、渲染和最终发送实际结束。处理中提示经统一回复链投递，不确定时不重发。见指令执行策略。
Console 已接入 limited 及冷却、忙碌、容量或身份缺失等实际原因。冷却时间只表示记录产生时的剩余时间；忙碌没有确定 ETA，不能伪造倒计时，也不视为权限拒绝或平台发送失败。
待扩展： 指令之外的能力及更灵活的准入维度仍需按实际契约评审，不给所有能力静默增加默认限制。冷却不是业务幂等，取消也只有在能终止相应操作时才提供。
端到端验收： 同一目标连续触发昂贵操作遵循配置限制，不同 Endpoint 或 thread 不误限流；拒绝时给出可理解原因，仅在有依据时展示等待时间。抛错、取消、HMR 与 generation 退役后，按执行实际结束释放占用；退役信号不提前释放仍在运行的任务。幂等键和不确定结果不能被普通冷却机制代替。
7. P1：配置解释与生效状态
已有基础： 配置 Schema、表单、源码编辑回退、revision 检查、应用状态与保留草稿已存在。复杂 Schema 目前采用保守回退，不能为了表单覆盖而丢字段。
已合入的 Host 证据： #841 提供同一文件版本、插件版本与当前运行代的应用证据；#846 提供已保存字段的候选来源与读取时一致性元数据。字段来源区分文件、Schema 默认、未设置与未知；不显示最终配置值或环境展开值。旧运行代字段来源没有记录时始终未知，值一致不能证明来源一致；敏感或环境引用字段未比较也不等于通过。复杂 Schema、自定义解析和漂移无法证明时明确回退，不给部分猜测结果。
开放前端： Console #22 接入保存与应用证据、未知结果冻结和只读核对；Console #24 接入字段来源与读取时一致性。两者尚未合入，不能因 Host 已合入或指南已有说明就宣称页面已发布。草稿与已保存版本分别绑定，切换连接、实例或 revision 时丢弃旧解释，不执行应用或业务验证。
待扩展： 复杂 Schema 表单覆盖继续逐项增加；无法完整保留结构时明确回退源码编辑。本项不包含展示“脱敏最终配置”的产品入口。
端到端验收： 保存后展示的是实际文件 revision，应用后展示的是当前 generation；失败不假称生效，冲突不覆盖别人的修改。复杂对象经编辑往返保留未知字段，敏感值不进入默认值解释、诊断或截图。
8. P1：通知节制与可管理性
已有基础： 现有插件可以产生通知与任务结果，但不等于已有统一静默和摘要策略。
开放实现： #842 为管理员 RSS 订阅提供显式 IANA 时区静默时段与持久有界摘要，沿用原轮询；暂停、编辑或取消清空待发摘要，恢复只建基线、不补发，投递未知不自动重试。该 PR 仍开放并在最新 main 上核验，尚未合入；聊天订阅和定时提醒不因此获得静默策略。
待扩展： 其他通知来源、重复失败合并及紧急例外尚待按契约设计。继续保留任务暂停或退订入口；不能通过摘要改变任务事实或掩盖失败。
端到端验收： 同一任务的重复失败不会持续刷屏，恢复时能理解恢复了什么；静默期间的通知遵循明确的延后或丢弃策略。静默与摘要按精确目标隔离；不支持交互的平台提供可执行的文本操作。投递 unknown 不自动补发整份摘要。
9. P1：带场景的插件试验台
已有基础： 插件测试工具支持实际发现、命令、权限和发送链测试；输出预览已有不发送的边界。
已合入的验收与指南： #843 使用 Console 实际导出产物运行可信独立项目中的真实 PluginTestKit 回归，并以故意错误的预期证明断言会失败。入口及项目配置见消息场景指南；这些测试不表示已验收任意用户插件。
开放前端： Console #23 提供 /scenario-lab 纯消息预览与导出，尚未合入。preview 是作者预期外观，最终派发和投递断言由作者独立填写，不能从预览推断执行成功。页面不执行插件、不调用 Host 渲染、不发送或注册交互；HTML 显示源码，Markdown 仅呈现安全子集，媒体占位。来源到合成 Endpoint 的完整映射、可信测试项目或明确断言未配置时，只能导出场景 JSON，不能导出空断言或跳过的“可运行回归”；显式投递断言 [] 表示预期没有投递，不是缺少断言。
执行边界： 首版仅在独立测试项目显式运行导出的回归，不内置远程 runner。PluginTestKit 不是安全沙箱；测试配置、数据与合成 Endpoint 必须独立，不导入生产适配器或凭据。更多渲染与平台能力验证仍属后续分层验收，不把浏览器预览当作真实派发。
端到端验收： 一个具备明确映射与断言的场景能导出并在独立测试项目复现，错误预期确实失败；切换合成能力配置不冒充平台支持。纯预览不发送、不触发交互、不调用业务工具；真实渲染和实机投递分别验证。模拟结果、浏览器结果、可信 fixture 执行与实机证据分别标注。
10. P1：让运行时问题直达文档答案
已有基础： 排错目录、配置文档、命令文档与 Console 路径存在。
已合入首条路径： #838 与对应 Console 诊断帮助入口，将未匹配、参数、权限、Agent 进行中及投递问题连接到固定排错章节。链接不携带消息正文或凭据，成功中间件不被解释为失败；该入口不自动重放消息。
待扩展： 其他稳定结果码与用途继续补齐短路径。最小示例需有预期结果、适用边界与失败后的检查方式；指南与代码契约保持一致，不能以新增文章代替功能或平台验收。
端到端验收： 从真实错误或拒绝状态进入正确章节，链接无需携带正文、凭据或完整内部异常；示例可在推荐的最小项目执行。文本平台能读到并打开链接，Markdown 和图片路径不会丢失必要操作说明。文档链接检查通过不代替示例执行验证。
验证与交付记录
Zhin Host 与独立 Console 是两个仓库。协议、后端权限与测试在 Zhin 仓库验证；页面状态、请求适配、交互与实际浏览器表现须在 Console 仓库分别验证。后端测试通过不说明前端已接入，Console 构建通过也不说明消息已投递。
Host 消息诊断与文本降级已随 #830 合入 main；管理员提醒任务端口由 #831 交付。独立 Console 的诊断界面 #14与任务中心 #16 也已合入主分支。#834 已将交互可靠性与个人提醒自然时间一并合入 Zhin main。
随后已合入 Zhin main 的切片为精确范围与权限解释 #837、诊断文档入口 #838、管理员 RSS #839、指令准入 #840、配置应用证据 #841、导出场景回归 #843 及配置字段解释 #846。对应能力的真实平台验收未因此自动完成。
仍开放的切片为 Zhin 通知节制 #842，以及 Console 的应用证据 #22、场景试验台 #23、字段解释 #24和群欢迎流程 #25。开放 PR、本地验收和使用指南不等于已合入、部署或平台验证。切换 PR 基准或新增提交后，完整 CI 必须按实际 head 重新核验，已有预览检查不能代替未触发的主矩阵。
每个纵切片的 PR 应记录：实际改动、未覆盖能力、回归范围、能力矩阵覆盖、是否做过浏览器或实机验证。验证可分为纯函数与本地测试、Host 集成、Console 浏览器、完整 CI、真实平台五层；没有执行的层次标记未验证。
A 批的消息诊断与可读降级闭环已进入后续用途扩展。B/C 继续按具体插件边界推进；任务、准入、配置、通知和场景各自区分已合入基础与开放前端。设计、审计材料或指南不能登记为对应功能交付，未覆盖的来源和平台仍按各自验收逐项推进。