miaobo/wechat_ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
wechat_ai/docs/page-completion-audit.md

72 KiB
Raw Permalink Blame History

src/ 页面完成度审计与业务补全方案

审计日期：2026-07-20
审计范围：src/App.jsx、src/pages/、src/windows/、页面级公共组件、src/data/mockData.js、src/utils/navigation.js
口径：一个可独立进入的主 Tab 或 hash 路由计为一个页面级视图；同一路由的步骤、页签和弹层不重复计数。
限制：本报告以当前前端代码、Tauri/Rust/Go 接线和浏览器可运行行为作为现状证据，并在此基础上评审最小 MVP 功能闭环。Windows 微信窗口捕获、自动回复和 Go sidecar 未做生产环境端到端验收，因此只判断接线，不把规划项表述为已实现能力。

1. 执行摘要

当前 src/ 已经不是“占位页集合”。主界面、设置、日志工作台、知识库、Skill、员工和蒸馏相关的 13 个页面级视图都有完整布局，原先的 6 个二级占位页也已替换为可交互表单/详情页。

但“页面做完”“单项能力闭环”“最小 MVP 闭环”是三套不同口径。当前只有标注保存形成了局部技术闭环，引擎启停接入部分 Tauri 命令；知识、Skill、员工、蒸馏、设置和日志仍主要来自 mockData 或组件内存状态。更关键的是，方案尚未完成“界面观测 → 消息归并 → 知识检索与建议 → 人工确认/规则拦截 → 发送执行 → 界面执行证据 → 结果核对与处理水位”的核心业务链。因此当前是可走查原型，不是可实际使用的 MVP。

1.1 页面统计

共识别 13 个页面级视图：4 个主 Tab、1 个标注路由、8 个二级窗口路由。

完成层级 数量 占比 页面
L3：可恢复、可审计的生产闭环 0 0% 尚无页面通过真实 Windows 全链路与异常验收
L2：部分真实能力接入 2 15.4% 屏幕区域标注、微信分身/引擎控制台
L1：交互原型完成，业务未持久化 11 84.6% 其余列表、设置、工作台、创建/详情/蒸馏页
L0：纯占位页面 0 0% 当前路由已不再使用 PlaceholderWindow
合计 13 100% —

按布局覆盖口径：13/13 已有页面结构，但其中仍有死控件、错误路由和模拟成功反馈，不能表述为“交互完成”。
按可持久化、可恢复、可审计、可端到端完成用户目标的严格口径：0/13 达到生产 L3，2/13 部分接入，11/13 仍为原型。

1.2 最高优先级问题

  1. 核心链路未接通：现有页面尚未把“微信界面观测 → 消息识别 → 知识检索 → 建议回复 → 人工确认 → 发送 → 结果记录”串成真实闭环。
  2. 大量状态仍是 mock 或页面内存：知识、设置、日志和引擎状态在重开窗口后不能稳定恢复，也无法跨窗口保持一致。
  3. 发送结果语义不准确：RPA 只能证明执行了输入/点击或观察到本方气泡，不能声称服务端送达或对方已读。
  4. 标注契约漂移：启动检查、React 标注页和原生标注 overlay 使用的必需区域不一致。
  5. 引擎状态不可恢复：当前 React 页面以内存状态驱动，停止操作又会直接终止 Agent/视觉流；异常退出后的真实状态没有统一来源。
  6. 消息识别不能依赖文本哈希冒充渠道 id：相同文本可能重复出现，OCR 也可能抖动，必须保留观测证据并允许人工处理歧义。
  7. 发送前缺少必要校验：焦点、当前会话、输入框原草稿、待发全文和标注坐标任一变化都可能造成错发。
  8. 未知结果不能自动重试：点击后崩溃或证据不足时，自动重试可能重复发送，必须先由用户核对。
  9. 知识检索需要段落级引用：当前“整篇返回”不适合长文；MVP 只需复用页面已有的 SQLite FTS5/BM25 方向，不扩展为向量平台。
  10. 非核心页面会分散实现面：Skill、Employee、蒸馏和复杂知识向导已有原型，但不应阻塞首条人工确认回复闭环。
  11. 现有成功反馈不能作为完成证据：保存、测试、启停、导出等动作若未调用真实持久层或原生命令，必须明确显示演示状态。
  12. Windows 自动化仍未验收：旧 Go/Python 视觉路径明显偏 macOS，必须以真实 Tauri Windows 端到端记录作为最终证据。
  13. MVP 导航脱离现有信息架构：方案新增“待处理 / 运行”主页面并把设置提升为主 Tab，但当前只有“微信分身 / 知识库 / Skill / 员工蒸馏”四个主 Tab，设置和日志均是二级窗口。MVP 应扩展现有微信分身页承载当前会话与人工确认，不再创建新的一级业务页面。
  14. 现有提示词与托管设置被错误裁掉：当前设置已有自定义提示词、开启托管、发送前人工确认、异常自动暂停、异常阈值和消息等待时间；这些直接约束现有自动回复功能，MVP 必须持久化，而不是只保留模型、回复规则和知识。
  15. Outbox 缺少原子执行权：queued → executing 若只是先查后改，双窗口、重复回调或残留进程可能同时发送。MVP 需要 SQLite 条件更新一次性取得执行权，但不需要引入分布式租约或安全账本。
  16. 聚合状态与执行证据未闭合：ReplyRun、Approval、Outbox 和 SendAttempt 各有状态，但没有明确由谁同步终态；SendAttempt 只有证据 hash 又无法在“结果未知”页面展示证据。
  17. 现有名单规则在单会话 MVP 中语义不完整：黑名单可直接阻断当前会话；白名单原本服务主动联系/自动发送，本轮既不主动联系也不全自动发送，若继续展示会成为无效果配置，应从 MVP 设置隐藏。
  18. 缺少“已处理到哪里”的会话水位：基线只能阻止首次启动处理历史消息，不能证明哪些新消息已经发送、拒绝或转人工；重启后可能再次为同一批消息生成建议。
  19. 新消息使旧建议失效后没有替代任务：方案只规定 supersede 旧 ReplyRun，却没有规定如何把旧输入和新输入合并为新 Run，可能出现旧建议失效后再也不回复。
  20. 结果未知期间的新消息没有归宿：未知发送结果必须阻断后续发送，但新观测仍会到达；若不保留为未处理输入，对账结束后会漏消息。
  21. 知识版本与引用模型不一致：现有知识页已有版本和标签，方案却让 Passage 只引用可变 Knowledge；编辑正文后，历史建议的引用会指向新内容。
  22. 方案新增了当前产品不存在的“测试建议/dry-run”动作：现有页面只有模型连接测试和组合提示词预览。MVP 首次建议应由布防后的真实测试消息产生，不另建测试业务流程。
  23. 黑名单按手输显示名无法可靠匹配：同名联系人可能被误拦截。单会话 MVP 应只允许把当前已布防会话加入黑名单，并保存当时的会话头指纹。

2. 页面与导航结构

flowchart TD
  App[App.jsx hash 分发] --> Main[MainShell]
  App --> Annotate["/annotate（开发调试）"]
  App --> Secondary[/window/*]

  Main --> Clone[微信分身]
  Clone --> NativeOverlay[Windows 原生标注 overlay]
  Main --> Knowledge[知识库]
  Main --> Skills[Skill 市场]
  Main --> Distill[员工蒸馏]

  Secondary --> Settings[settings]
  Secondary --> Workbench[engine-logs]
  Secondary --> KnowledgeCreate[knowledge-create]
  Secondary --> KnowledgeDetail[knowledge-detail?id]
  Secondary --> SkillCreate[skill-create]
  Secondary --> SkillDetail[skill-detail?id]
  Secondary --> EmployeeDetail[employee-detail?id]
  Secondary --> DistillStart[distill-start?step]

2.1 路由与窗口机制

  • 没有 React Router。App.jsx 读取 window.location.hash，将路由分成主窗口、/annotate 和 /window/*。
  • 当前仍可直接进入 React /annotate，但生产方案应把它降为开发调试路由；用户唯一标注入口是 ClonePage 调用 enter_window_select_mode 打开的 Windows 原生 overlay。
  • 主 Tab 只存在 App 内存中，刷新后回到“微信分身”；设置二级分区状态提升到 App，但字段值不在 App 中。
  • 浏览器模式下，openWindow(route) 通过修改 hash 导航。
  • Tauri 模式下，openWindow(route) 调用 open_popup_window 创建独立窗口；失败时降级为当前窗口 hash 跳转。
  • 二级窗口由 SecondaryWindow 根据 route 映射到 8 个实现。未知 /window/* 会降级显示 PlaceholderWindow，应改为明确的 404/未知窗口状态，避免把路由错误伪装成正常占位页。
  • PlaceholderWindow.jsx 当前仅用于未知二级路由兜底，不属于 13 个已命名页面。

2.2 公共壳与全局交互

  • TitleBar：主窗口可打开设置、退出应用；二级窗口可关闭；支持 Tauri 窗口拖动。
  • ThemeSwitch：主题写入 localStorage.theme，通过 storage 事件在窗口间同步。
  • BottomTabs：切换 4 个主业务页面。
  • WindowUI：为二级窗口提供标题、页签、向导步骤、表单行、指标和底部动作栏。
  • DraggableFab：支持纵向拖动，设置移动阈值避免拖动后误触点击。
  • Terminal：自动滚动到最新日志，支持可选的查看全部与清理回调。

2.3 MVP 目标导航

MVP 不新建一级“待处理”或“运行”页面，沿用当前窗口结构并缩减生产导航：

  1. 微信分身：保留现有引擎状态、启动检查、暂停、停止、最近日志和标注入口；在同一页增加当前会话、待人工确认建议和未知结果核对区域。
  2. 知识库：复用现有列表与详情入口，只支持纯文本/UTF-8 TXT、编辑、发布/停用、删除和段落检索预览。
  3. 设置二级窗口：保留模型、提示词、回复规则、知识和托管配置中的 MVP 字段。
  4. 日志二级窗口：复用 /window/engine-logs 展示真实运行日志。

Skill 市场与创建/详情、员工蒸馏与详情不进入 MVP 生产导航；保留源码时标记为开发预览。原生 overlay 是唯一生产标注入口。这样只扩展已有页面，不新增一级业务路由。

3. 逐页完成度

# 页面/路由 已有交互 数据/副作用 严格状态 未完成项
1 微信分身 / 引擎启停、启动前检查、标注入口、状态球、日志清理/查看 Tauri command/event + 本地 state；浏览器使用演示分支 L2 部分接入 初始状态查询、真实模型健康、实时日志、重启、错误恢复和跨窗口同步
2 知识库主列表 搜索、类型/状态筛选、详情入口、新增 FAB 页面内 items 常量 L1 原型 查询/分页/加载/错误态、真实详情同步、解析任务状态
3 Skill 市场 搜索、分类筛选、卡片详情、启停、创建 FAB 页面内 initialSkills + 本地 state L1 原型 CRUD、测试、发布、授权、持久化启停、失败回滚
4 员工蒸馏 教程弹层、搜索/筛选、任务隐藏、详情/继续任务入口 mock 员工 + 固定 72% 任务 L1 原型 后台任务、恢复、取消/重试、评估、发布和实时进度
5 屏幕区域标注（生产：原生 overlay；调试：/annotate） 原生选窗/画框/保存；React Canvas 框选、编辑、删除和保存 Tauri 截图/区域命令；浏览器存储仅用于调试捕获结果 L2 部分接入 单一生产契约、完整保存校验、未保存离开确认、Windows DPI/多屏端到端验收
6 设置 /window/settings 7 个分区、输入/选择/开关、连接测试、保存/恢复、脏状态提示 组件本地 state + 延时模拟 L1 原型 get/save_config、安全密钥存储、真实连接测试、校验、错误反馈、跨窗口同步
7 引擎日志 /window/engine-logs 级别/模块/关键字筛选、暂停、自动滚动选项、清空、日志详情抽屉 mockData.logs × 3 + 派生字段 L1 原型 真实日志订阅；导出、复制按钮接线；容量、脱敏和结构化导出策略
8 新增知识 /window/knowledge-create 4 步向导、基本信息、来源/文件输入、全文预览、发布设置、草稿/发布反馈 本地 state + 固定解析结果 L1 原型 文件读取、OCR/ASR、SQLite 落库、任务恢复、校验、失败重试
9 知识详情 /window/knowledge-detail?id=… 5 页签、正文搜索/编辑、重新解析、创建版本、启停、删除 固定知识文案 + 本地 state L1 原型 读取路由 id、查询实体、引用保护、版本持久化、真实解析和删除
10 创建 Skill /window/skill-create 5 步向导、提示词/schema/工具/知识库选择、测试、草稿/发布 本地 state + 固定测试结果 L1 原型 schema 校验、真实沙箱、权限模型、版本化发布、持久化
11 Skill 详情 /window/skill-detail?id=… 5 页签、概览指标、启停、执行/权限/测试/版本列表 固定“客户意图识别”数据 + 本地 state L1 原型 读取 id、内置/自定义权限边界、真实编辑/测试/审计、列表同步
12 员工详情 /window/employee-detail?id=… 5 页签、画像/指标/授权/版本/调用展示、启停 固定“销售冠军 Aileen”数据 + 本地 state L1 原型 读取 id、真实评估/调用/版本数据、持久化启停/回滚、列表同步
13 开始蒸馏 /window/distill-start?step=… 5 步向导、来源、隐私、能力提取、评估、发布、草稿 本地 state + 固定进度/评估结果 L1 原型 读取 step/job id、后台任务、脱敏执行、评估计算、发布落库和恢复

MVP 范围说明：上述 13 项是现状审计口径，不是 MVP 必做清单。MVP 只交付扩展后的“微信分身”、精简知识页、精简设置二级窗口、真实日志二级窗口和原生标注；Skill/员工/蒸馏及对应复杂创建/详情窗口全部移出发布阻断范围并从生产导航隐藏。

3.1 局部闭环页面

屏幕区域标注已具备“读取输入 → 用户编辑 → 保存结果 → 通知/退出”的局部技术闭环，同时支持 Tauri 命令与浏览器演示路径；但必需类型契约尚未统一，且 Windows 原生窗口捕获、DPI 和多屏未完成验收，因此只能评为 L2，当前没有页面达到生产 L3。

3.2 已有视觉结构、未完成业务的页面

以下 11 个页面已不属于占位页：知识/Skill/蒸馏列表、设置、引擎工作台、知识创建/详情、Skill 创建/详情、员工详情、蒸馏向导。它们可以用于布局和流程走查；死控件、固定结果和未持久化状态必须明确标记为“演示”，不能作为交互可用、数据已保存或任务已执行的证据。

3.3 部分接入页面

微信分身已经调用 start_vision_stream、start_agent、stop_agent、stop_vision_stream，并监听 engine-state-changed 与 annotation-completion-changed。启动前会依次检查模型配置、标注和微信窗口；这是有效接线。但页面初始状态、日志和部分健康信息仍不是单一真实来源。

3.4 全局布局与内容规范

主窗口公共布局

  • 使用纵向三段式：顶部 TitleBar、中部可滚动内容区、底部四栏 BottomTabs。
  • 顶栏标题随当前 Tab 变化为“微信分身 / 知识库 / skill市场 / 员工蒸馏”；右侧依次为主题、设置、重启、退出。
  • 底部导航固定四等分；数据项格式为 { id, label, icon, badge }。当前 badge 数据存在“3”“新”，但 BottomTabs 未实际渲染徽标。
  • 主内容统一使用 20px 左右内边距；列表页采用垂直卡片流，主要卡片圆角 14px。

二级窗口公共布局

  • 使用顶部紧凑标题栏 + 单一内容画布；标题栏右侧为主题切换和“关闭”。
  • 创建类页面使用“顶部步骤条 + 居中最大宽度内容 + 底部 sticky 操作栏”。
  • 详情类页面使用“实体标题/版本/状态 + 横向页签 + 内容卡片”。
  • 通用展示格式：状态使用 StatusPill，统计使用 Metric，键值信息使用 InfoRow，表单标签使用 FormRow。

通用文案和数值格式

类型 当前格式 示例
版本 v<major>.<minor> 字符串 v2.4、v3.2
短日期 MM-DD 06-08
完整日期 YYYY-MM-DD 2026-06-05
日期时间 YYYY-MM-DD HH:mm 2026-06-08 18:20
日志时间 HH:mm:ss；详情补日期和毫秒 12:30:04、2026-07-20 12:30:04.238
百分比 数字加 % 72%、98.4%
评分 整数或 整数 / 100 96、92 / 100
数量 数字加中文单位 32 次、3 个、1,286 条会话
文件大小 整数加 KB 428 KB
字数 千位分隔或“万字” 8,600 字、2.6 万字
状态 中文显示文本 已生效、解析中、已启用、已关闭
实体路由 query string ?id=kb-refund、?step=3

3.5 每个页面的布局、文案与数据格式

1. 微信分身

  • 布局：上半部居中状态球 NodeSphere、状态标题/说明和主操作；下半部是自动滚动终端日志。运行后主操作变为两列“暂停/恢复自动发送”和“停止引擎”。
  • 核心文案：状态标题为“微信引擎未运行 / 微信引擎运行中 / 微信引擎运行异常”；说明分别描述等待运行、已处理消息和启动失败。未标注时显示“标注微信”，已标注时显示“启动引擎”，异常时显示“重新启动”。
  • 启动浮层：标题“正在检测引擎启动环境”，逐项展示“大模型连接情况 / 微信区域标注情况 / 微信窗口连接情况”和“检测中... / 成功 / 失败”，最终文案为“全部检查成功，正在启动引擎...”或“检查失败，启动流程已终止。”
  • 数据格式：
    • engineStatus: "idle" | "running" | "error"；
    • 日志 { level: "info" | "warning" | "error", message: string }；
    • 检查项 { id, label, detail, status, passed }，其中 status 为 waiting/checking/passed/failed；
    • 原生状态事件使用 payload.enabled: boolean。
  • 展示格式：日志 message 当前有 [HH:mm:ss] 文本 和无时间前缀文本两种格式，建议统一拆分 timestamp 字段。

2. 知识库主列表

  • 布局：类型分段器 → 搜索框 → 状态筛选与刷新按钮 → 汇总行 → 知识卡片列表 → 右下角新增 FAB。
  • 核心文案：类型为“全部 / 视频 / 图片 / 文件 / 案例 / 其他”；搜索占位“搜索标题、标签或完整正文”；状态为“全部状态 / 已生效 / 解析中 / 解析失败 / 待审核 / 已停用”；汇总为“共 6 项 · 生效 2 · 解析中 1 · 异常 1”。
  • 卡片内容：标题、类型标签、业务标签、状态、可选解析进度条、版本、更新时间、引用数、正文长度或错误原因；错误卡增加“查看原因 / 重试”。
  • 空态文案：“暂无匹配知识”“调整类型、状态或搜索关键词后重试。”“清除筛选”。
  • 数据格式：{ id, title, type, tags: string[], updated: "MM-DD", refs: number, version, status, detail, progress?: number, error?: boolean }。progress 范围按 0..100 百分比展示。

3. Skill 市场

  • 布局：类型分段器 → 名称/能力搜索 → 状态筛选与刷新 → Skill 卡片流 → 新增 FAB。
  • 核心文案：类型“全部 / 内置 / 自定义”；搜索占位“搜索 Skill 名称或能力”；状态“全部状态 / 已启用 / 已关闭”。
  • 卡片内容：名称、类型 · 版本、启用状态、三个能力标签、测试/绑定知识/最近调用摘要；右下提供“查看/编辑”和启停开关。
  • 空态文案：“暂无匹配 Skill”“调整筛选条件后重试。”
  • 数据格式：{ id, name, type: "内置" | "自定义", enabled: boolean, version, tags: string[], meta: string, tested: boolean }。当前 meta 把多个字段拼成展示字符串，正式数据应拆为 knowledgeCount/callCount/testStatus/updatedAt。

4. 员工蒸馏主列表

  • 布局：顶部产品说明与双 CTA → 当前任务进度卡 → 员工搜索/状态筛选 → 已发布员工卡片列表；教程使用居中模态框。
  • 核心文案：主标题“把优秀话术沉淀成员工能力”，说明“导入聊天记录、话术和案例，形成可评估、可授权的员工。”；CTA 为“查看教程 / 开始新的蒸馏”。
  • 任务卡：“销售冠军 Aileen 话术蒸馏”“能力提取 · 剩余约 3 分钟”“72%”“成功 248 · 失败 7”，操作为“查看 / 取消”。
  • 教程文案：依次说明授权导入、隐私脱敏、能力提取/失败样本、效果评估与授权发布。
  • 员工卡片：名称、领域、版本、启停状态、画像特征、评分、本周调用和“查看详情”。
  • 数据格式：
    • 员工 { name, version, enabled, traits, domain }；
    • 列表派生 score 和 weeklyCalls；
    • 当前任务应规范为 { id, name, stage, progress, successCount, failureCount, etaSeconds }，当前均为硬编码展示值。

5. 屏幕区域标注

  • 布局：全屏左右两栏。左侧固定 320px 配置栏，包含标题/状态、截图元信息、区域编辑表单、区域列表和取消/保存；右侧为自适应黑底 Canvas。
  • 核心文案：模块名“屏幕区域标注”，页面标题“微信 RPA 坐标配置”，操作提示“拖拽截图区域创建矩形框”。浏览器不可用时显示“浏览器预览模式无法截屏，请在 Tauri 应用中使用”。
  • 表单：区域名称；区域类型“联系人区域 / 聊天内容区域 / 输入框区域 / 发送按钮区域 / 自定义区域”；区域用途描述；“删除当前框 / 取消 / 保存”。
  • 元信息：截图像素、ScaleFactor、区域数量、来源（窗口/桌面）；选中区域展示 image: [x1, y1, x2, y2] 和 screen: [x1, y1, x2, y2]。
  • 数据格式：
    • 捕获 { screenshotPath, screenshotWidth, screenshotHeight, scaleFactor, source?, totalMs?, screenListMs?, captureMs?, saveMs? }；
    • 区域 { id: UUID, name, type, description, bbox_image: number[4], bbox_source: number[4], bbox_screen: number[4], scaleFactor }；
    • 保存文件 { app: "wechat", screenshotPath, screenshotWidth, screenshotHeight, scaleFactor, source, regions, createdAt, updatedAt }；
    • 坐标顺序统一为 [x1, y1, x2, y2]，最多保留两位小数；时间使用 ISO 8601。

6. 设置

  • 布局：左侧 180px 分区导航，右侧滚动配置内容，底部固定“保存状态 + 恢复/保存配置”。小屏改为顶部横向分区。
  • 分区：基础配置、提示词配置、回复规则、Skill 管理、员工管理、知识库管理、托管配置。
  • 基础配置：标题“大模型配置”；字段为模型厂家、请求地址、API Key 状态、模型名称、请求超时（毫秒）；按钮“更换 / 删除 / 测试连接”；结果“尚未测试当前配置”或“● 连接成功 · 324ms · doubao-pro-32k”。
  • 提示词配置：固定提示词只读；自定义提示词显示 {length} / 4000；操作“预览组合提示词”。
  • 回复规则：免打扰模式、自动加好友、主动联系客户、开启蒸馏；白名单/黑名单区支持名称搜索、添加、删除，示例数据“张三 / 客户测试群”。
  • Skill/员工管理：总开关 + 每项开关；摘要格式分别为类型 · 版本 · 测试状态和版本 · 评分 · 领域。
  • 知识库管理：固定算法“SQLite FTS5 / BM25”，最大返回数量，搜索字段“标题 / 标签 / 完整正文”，以及逐知识启停。
  • 托管配置：开启托管、本地消息服务、发送前人工确认、异常自动暂停、连续异常阈值、单日消息最长等待秒数。
  • 数据格式：当前没有统一配置对象，各分区由局部 state 和非受控 defaultValue/defaultChecked 混合组成。正式格式应采用报告 5.3 的 AppConfig，数值字段使用 number、开关使用 boolean、名单使用 { id, displayName }[]。
  • 保存状态文案：“所有修改已保存 / ● 有未保存修改 / 配置已保存”。

7. 分身引擎日志

  • 布局：顶部过滤工具栏 → 自动滚动和动作栏 → 深色等宽日志表 → 底部计数/接收状态；点击日志后从右侧打开 390px 详情抽屉。
  • 筛选文案：“全部级别 / info / warning / error”“全部模块”；搜索占位“搜索消息或 requestId”。
  • 操作文案：“暂停接收 / 继续接收”“导出”“清空视图”；空态“当前筛选下暂无日志”。
  • 表格列：时间、级别、模块、消息；详情补充 requestId、上下文和完整日期时间，并提供“复制完整日志 / 仅筛选此 requestId”。
  • 状态文案：“已显示 N / M 条 · 缓存上限 10,000”“最后更新 12:30:15”或“已暂停接收 · 新日志 3 条”。
  • 数据格式：{ id: number, time: "HH:mm:ss", level: "info" | "warning" | "error", module: "agent" | "vision" | "capture" | "retriever" | "model" | "policy" | "sender", message: string, requestId: string | "—" }。当前原始 message 内又包含时间，存在重复时间字段。

8. 新增知识库

  • 布局：四步向导“基本信息 / 来源导入 / 全文预览 / 发布设置”，内容最大宽度 5xl，底部操作为“上一步 / 保存草稿 / 下一步或发布知识”。
  • 第 1 步：知识标题、知识类型、标签、适用范围、说明；类型为“文件 / 图片 / 视频 / 案例 / 其他”。
  • 第 2 步：上传文件、粘贴文本、选择本地目录；拖拽区支持 PDF / DOCX / TXT / PNG / JPG / MP4；文件行展示名称、大小、解析状态和“移除”；附敏感信息脱敏选项。
  • 第 3 步：解析汇总、进度条、来源文件切换、完整文本预览；提示“SQLite 将对标题、标签和完整正文建立 FTS5 索引，并通过 BM25 排序。”
  • 第 4 步：发布摘要、发布方式、版本说明、敏感信息确认；发布方式为“立即生效 / 保存为待审核 / 仅保存草稿”。
  • 数据格式：页面状态 { title, type, tags: string[], files, content, publishMode }；文件 { name, size: "<n> KB", status }；正式提交应把 size 改为字节 number，显示层再格式化。

9. 知识库详情

  • 布局：实体标题/版本/状态和“更多” → 五页签“概览 / 全文内容 / 引用关系 5 / 版本历史 7 / 错误记录” → 页签内容。
  • 页头文案：“售后常见问题与退款边界”“v1.7”“已生效/已停用”“文件 · 售后 · 更新于 2026-06-05 · 引用 82 次”。
  • 概览：来源、解析方式、创建人、当前版本、生效时间、最近检索；内容摘要；本周命中、引用 Skill、绑定员工、正文字数；操作“重新解析 / 创建新版本 / 停用或重新启用 / 删除知识”。
  • 全文内容：搜索占位“在完整正文中搜索”，结果文案“找到 N 段包含‘关键词’的内容”，正文 textarea。
  • 其他页签：引用项使用“名称 · 类型”；版本使用“版本 · 说明 · 日期”；错误使用“日期：错误说明”。
  • 数据格式：当前数据散落为显示字符串。正式详情应包含 knowledge、references[]、versions[]、errors[]；计数页签由数组长度生成，不写死在标题中。

10. 新增 Skill

  • 布局：五步向导“基本信息 / 执行定义 / 权限授权 / 沙箱测试 / 发布设置”，底部为草稿和前后步骤/发布操作。
  • 基本信息：Skill 名称、类型、描述、能力标签。
  • 执行定义：系统提示词、输入 Schema、输出 Schema、可调用工具；工具包括查询商品信息、检索知识库、发送微信消息、创建工单。
  • 权限授权：可访问知识库；危险权限“允许直接发送消息 / 允许主动联系客户”，并显示人工确认、托管和白名单限制。
  • 沙箱测试：测试输入、运行测试；结果展示是否通过、耗时、tokens、结构化结果和工具轨迹。
  • 发布设置：版本、授权知识数、工具数、测试状态、发布说明、“发布后立即启用”；未测试时提示“发布前必须至少完成一次成功测试。”
  • 数据格式：当前输入/输出 Schema 是“字段名 → 类型字符串”的 JSON 示例；正式格式应采用合法 JSON Schema。测试结果建议 { status, durationMs, tokenUsage, output, toolTrace[] }。

11. Skill 详情

  • 布局：实体标题/版本/状态和启停按钮 → 五页签“概览 / 执行定义 / 权限授权 / 测试记录 / 版本历史”。
  • 页头文案：“客户意图识别”“v2.1”“已启用/已关闭”“内置 Skill · 更新于 2026-06-16 · 最近调用 16 次”。
  • 概览：能力说明、三个标签，以及最近调用、成功率、平均耗时、绑定知识四项指标。
  • 其他页签格式：
    • 执行定义：输入/输出/提示词：内容；
    • 权限：资源或动作 · 已授权/未授权；
    • 测试：日期 · 场景 · 结果 · 耗时；
    • 版本：版本 · 说明 · 当前状态。
  • 数据格式：当前各页签是字符串数组；正式数据应拆成 definition、permissions[]、testRuns[]、versions[]，状态和耗时保持机器可计算类型。

12. 员工详情

  • 布局：员工标题/版本/状态和启停按钮 → 五页签“概览 / 能力与授权 / 评估报告 / 版本历史 / 调用记录”。
  • 页头文案：“销售冠军 Aileen”“v3.2”“已启用/已关闭”“企微私域成交 · 更新于 2026-06-18”。
  • 概览：员工画像、适用/禁止边界、综合评分、本周调用、采纳率、异常；绑定能力和知识；操作“编辑画像 / 管理授权 / 管理知识 / 重新蒸馏 / 复制为新员工 / 更多操作”。
  • 其他页签格式：
    • 授权：名称 · 已授权/未授权/已绑定；
    • 评估：指标 数值；
    • 版本：版本 · 说明 · 当前；
    • 调用：HH:mm · 场景 · 结果。
  • 数据格式：当前概览与页签均为固定字符串。正式数据需要 { employee, profile, grants, evaluation, versions, calls }，其中评分和百分比使用 number，显示时再添加 % 或 / 100。

13. 开始蒸馏

  • 布局：五步向导“来源导入 / 隐私处理 / 能力提取 / 效果评估 / 发布员工”，内容最大宽度 5xl，底部为保存草稿和步骤/发布操作。
  • 来源导入：入口“导入微信聊天 / 上传文档 / 选择已有案例”；来源卡显示名称、条数和“格式有效”；另有数据日期范围和导入范围设置。
  • 隐私处理：扫描汇总“423 个联系人、86 个手机号、31 个订单号”；规则包括匿名编号、手机号后四位、订单号隐藏、地址保留省市；展示脱敏前后对照。
  • 能力提取：标题“正在提取能力”“任务可在后台继续运行”，进度 72%；阶段为数据清洗、场景聚类、策略提取、边界归纳、反例生成。
  • 效果评估：综合评分 92/100，状态“达到发布标准”；指标为场景命中、拒答准确、越权率、一致性；样例行展示场景、结果和通过状态。
  • 发布员工：员工名称、业务领域、授权能力、授权知识、初始启停状态；按钮“发布员工”。
  • 数据格式：
    • 来源建议 { id, name, kind, itemCount, status }；
    • 隐私扫描 { contactCount, phoneCount, orderCount, rules[] }；
    • 任务阶段 { name, current, total?, valueText, done }；
    • 评估 { score, sceneHitRate, refusalAccuracy, overreachRate, consistency, cases[] }；
    • 当前代码仅保存 { step, notice, name }，其余为静态 JSX 数据。

3.6 数据格式共性问题

  1. 展示文本与领域数据混合：meta、版本历史、测试记录、调用记录大量使用“字段 · 字段”字符串，无法可靠排序、筛选和国际化。
  2. 同一概念格式不统一：知识更新时间同时存在 06-08、2026-06-08、2026-06-08 18:20；日志时间既在 time 字段中，也嵌入 message。
  3. 计量值被字符串化：文件大小、字数、耗时、token、评分、百分比均应在数据层保存 number，并由显示层加单位。
  4. 中文状态被当作枚举：应使用稳定英文/代码枚举，中文只作为映射文案。
  5. 详情子数据是字符串数组：引用、版本、错误、权限、测试、调用都应改为带 id 和独立字段的对象数组。
  6. 路由参数与页面状态脱节：实体 id、任务 jobId、步骤 step 应有统一解析和校验函数。
  7. Schema 不是标准 JSON Schema：当前仅是字段到类型的示例对象，正式执行契约至少需要 type、properties、required。

4. 当前交互逻辑清单

4.1 有真实 Tauri 接线的交互

交互 当前调用链 结论
启动引擎 模型配置检查 → load_regions → find_wechat_window → start_vision_stream → start_agent 接线有效；Agent 启动失败会回滚视觉流
停止引擎 stop_agent → stop_vision_stream 接线有效；需增加部分失败后的真实状态重查
打开标注 enter_window_select_mode，并监听标注完成事件 接线有效；实际生产入口更接近原生 overlay 流程
React 标注保存 read_screenshot_bytes / load_regions / save_regions Tauri 模式具备原生读写；浏览器存储只承担截图结果传递，不能保存标注文件
弹出/关闭窗口 open_popup_window / close_current_window 通用窗口链路已接入
退出应用 exit_application 主窗口退出已接入

4.2 仅当前页面内有效的交互

  • 搜索、筛选、Tab/步骤切换、教程弹层和日志详情抽屉。
  • Skill 列表启停、知识详情启停、Skill 详情启停、员工详情启停。
  • 设置字段修改、模拟连接测试、脏状态和保存成功提示；“恢复”只清除脏状态，不恢复字段值。
  • 创建知识、创建 Skill、蒸馏向导的步骤推进、草稿/发布提示。
  • 引擎日志暂停显示状态、关键字筛选、requestId 筛选和清空视图。

共同特点：有效动作只更新当前 React state 或显示 notice；刷新、关闭二级窗口或从另一窗口查看时不会保留。页面中仍有大量带按钮外观但没有 handler 的控件，见 4.4。

4.3 纯模拟逻辑

  • 设置连接测试：固定延时后显示固定成功结果。
  • 知识创建页：文件解析数量、100% 进度、正文长度和影响范围均为固定演示。
  • Skill 创建页：测试按钮立即返回固定结果、1.8 秒、820 tokens 和固定工具轨迹。
  • 蒸馏页：72% 进度、脱敏统计、能力阶段和评估指标均为静态内容。
  • 引擎日志：将 mockData.logs 重复三次并派生时间、模块和 requestId。
  • 知识引用、版本记录、员工评分、最近调用和日志上下文均为静态内容。
  • 浏览器模式引擎启动会模拟成功，应始终标注为“演示模式”。

4.4 无效或存在契约错误的交互

位置 问题 用户风险
主标题栏“重启” 无 onClick 看似可用，点击无反馈
知识详情 URL 的 id 未读取 所有卡片展示同一知识
Skill 详情 URL 的 id 未读取 所有卡片展示同一 Skill
员工详情 URL 的 id 未读取 所有卡片展示同一员工
蒸馏当前任务 ?step=3 未读取 点击继续后仍回到第 1 步
设置保存/恢复 保存只切换 dirty/saved；恢复不还原字段 关闭窗口后配置丢失，恢复按钮也可能造成误解
日志导出/复制 按钮没有 handler 用户无法获得文件或复制结果
未知二级路由 自动显示 PlaceholderWindow 路由错误被伪装成正常占位页面

5. 数据、状态与契约审计

5.1 当前真实依赖

  • Tauri commands：引擎启停、视觉流、微信窗口查找、标注模式、截图读取、区域读写、窗口创建/关闭、应用退出。
  • Tauri events：engine-state-changed、annotation-completion-changed。
  • 浏览器存储：主题、React 标注页截图捕获结果、等待状态和错误传递。

5.2 当前 mock 或易失数据

  • skillItems、employeeItems、logs、设置分区和设置内知识条目来自 src/data/mockData.js；知识主列表和 Skill 主列表另有各自的页面内常量。
  • 创建向导、详情页、设置和启停动作存在各自页面 state 或静态 JSX 数据中。
  • 多窗口没有共享 store，也没有服务端/原生数据重新查询机制。

5.3 MVP 最小数据模型

只为现有功能闭环保存必要数据，避免为本轮非目标预建领域模型：

AppConfig
  revision, provider, endpoint, model, requestTimeoutMs, keyConfigured,
  customPrompt, quietHours, blockList: { displayName, headerFingerprint }[],
  knowledgeEnabled, knowledgeMaxResults, knowledgeSearchFields,
  activeKnowledgeIds, hostingEnabled, localMessageServiceEnabled,
  confirmBeforeSend: true, abnormalPauseEnabled,
  consecutiveErrorLimit, messageWaitSeconds, updatedAt

Knowledge
  id, title, tags, status, currentVersionId, updatedAt

KnowledgeVersion
  id, knowledgeId, version, contentHash, text, createdAt

KnowledgePassage
  id, knowledgeVersionId, ordinal, text, sourceLocator

AnnotationConfig
  windowFingerprint, regions, geometryHash, revision, updatedAt

EngineState
  lifecycle, agent, visionStream, wechatWindow,
  activeConversationId?, paused, consecutiveErrors,
  lastError, updatedAt

Conversation
  id, headerFingerprint, baselineObservationSeq,
  lastHandledObservationSeq, armedAt, active, manualTakeover,
  contextVersion, updatedAt

MessageObservation
  id, conversationId, seq, frameHash, normalizedContent,
  contentHash, direction, confidence, observedAt,
  state: pending | included | handled | manual

ReplyRun
  id, conversationId, inputObservationIds, contextVersion,
  configRevision, proposedContent,
  citations: { knowledgeVersionId, passageId, sourceLocator, excerpt }[],
  replyDeadlineAt, state, outcome?, createdAt, completedAt?, error?

Approval
  id, runId, revision, approvedContent, contentHash,
  state, decidedAt

OutboxMessage
  id, runId, conversationId, normalizedContent, contentHash,
  state, executionId?, expiresAt, startedAt?, createdAt, updatedAt

SendAttempt
  id, outboxId, executionId, state,
  beforeEvidence?, afterEvidence?, resolution?,
  startedAt, finishedAt?

LogEvent
  id, time, level, module, message, requestId?

SQLite 是本机唯一业务状态源；API Key 由系统密钥库保存。页面只显示后端状态，不自行制造成功结果。Approval.runId 与 OutboxMessage.runId 分别唯一；同一会话只允许一个非终态 ReplyRun。

Outbox 执行权使用一次原子条件更新取得：UPDATE outbox SET state='executing', execution_id=?, started_at=? WHERE id=? AND state='queued'。只有受影响行数为 1 的当前 Tauri 执行器可以输入和点击；应用启动时先把遗留 executing 标为 unknown_result，完成核对前不消费新 Outbox。该约束只解决本机重复执行，不引入分布式租约、跨设备协调或额外产品模块。

5.4 前端服务边界

页面与 Tauri invoke 之间只增加薄服务层，覆盖现有页面需要的真实动作：

configService:       get/test/save
knowledgeService:    list/get/upsertText/publish/disable/searchPassages
annotationService:   load/start/save/validate
engineService:       getState/start/stop/restart/pause/subscribeState/subscribeLogs
conversationService: armCurrent/disarm/getCurrent/subscribeObservations
replyService:        listPending/get/approve/reject/regenerate
outboxService:       list/get/cancelPending/reconcileUnknown

每个动作返回 { data, revision } 或结构化错误 { code, message, fieldErrors, retryable }。approve(runId, revision, contextVersion, configRevision, contentHash) 是唯一能创建 Outbox 的页面命令；仅当页面所见版本全部仍匹配时提交，重复同内容批准返回原结果，不同内容或旧版本返回冲突。页面不得直接 enqueue 或重试发送。getState/listPending/getCurrent 负责微信分身页首次加载，事件只通知重新查询。

5.5 产品主闭环与必要技术不变量

MVP 只实现现有功能能够组成的一条链：

flowchart LR
  A[标注并启动] --> B[观察当前会话]
  B --> C[识别新文本]
  C --> D[检索知识段落]
  D --> E[生成建议]
  E --> F[人工批准或拒绝]
  F -->|批准| G[持久 Outbox]
  G --> H[发送前复检]
  H --> I[输入并点击一次]
  I --> J{UI 证据}
  J -->|本方气泡| K[记录 observed_sent]
  J -->|证据不足| L[人工核对]

只保留完成该链必须满足的不变量：

  1. MVP 只观察操作者已打开并明确布防的一条当前一对一文本会话；不扫描联系人列表、不点击未读项、不自动切换会话。
  2. 首次布防、重新标注或重启后先建立基线；屏幕上已有内容不自动进入回复链。
  3. OCR 文本不是稳定渠道 id；相同文本、OCR 抖动或归属不明时保留观测并转人工，不能静默合并或重复建任务。
  4. 建议必须冻结当前输入、知识引用和会话版本；出现新消息、切换会话、修改标注或停用知识后，旧建议和未执行 Outbox 失效。
  5. 每条回复逐条人工确认；Outbox 只能由批准动作创建，拒绝或编辑后未重新确认不能发送。
  6. 发送前验证当前微信窗口、会话头、输入框为空、待发全文和标注区域；用户已有草稿不得清空或覆盖。
  7. 发送只执行一次完整文本输入和一次发送按钮点击；不静默截断、不自动拆分、不以回车作为未验证降级。
  8. 点击后只能记录“观察到本方气泡”或“结果未知”，不能显示服务端送达或已读。
  9. unknown_result 不自动重试；用户核对为未发送后，也必须重新生成或重新确认后创建新 Outbox。
  10. 应用停止或异常退出后不得自动重放正在执行或结果未知的发送；先恢复状态并核对。
  11. 生产键鼠副作用集中在 Tauri 侧固定发送流程；模型输出、Go Action 和 Python 实验脚本不能直接驱动生产键鼠。
  12. 运行状态、知识、设置、Outbox 和日志来自真实后端；浏览器演示必须明确标注演示模式。
  13. 应用只允许一个主实例；Outbox 仍必须通过 SQLite 条件更新取得执行权。每个 SendAttempt 使用唯一 executionId，迟到结果仅在 Outbox 仍为 executing 且 id 匹配时写入，否则只记录错误。
  14. “结果未知”界面必须能读取 SendAttempt 保存的发送前后结构化观测或聊天区域裁剪；只有 hash 不足以支持人工判断。
  15. MessageObservation 使用会话内单调递增 seq；Conversation 以 baselineObservationSeq/lastHandledObservationSeq 记录基线和处理水位，不能用无顺序语义的 UUID 比较先后。首次布防只建立基线，之后仅将水位后的稳定入站观测纳入 ReplyRun。
  16. 新消息到达且当前 Run 尚未点击发送时，旧 Run/Approval/未执行 Outbox 同时 supersede；稳定窗口结束后，用“旧 Run 尚未处理的输入 + 新观测”创建唯一替代 Run，不能只失效不补建。
  17. 当前存在 executing/unknown_result 时不创建新 Run，但继续把新观测保存为 pending；结果核对完成后，再从处理水位之后生成下一条 Run。
  18. observed_sent/reconciled_sent/rejected/manual_takeover/reconciled_unresolved/expired 均收口本次输入并推进处理水位；reconciled_not_sent 不推进水位，页面只提供“重新生成”或复用现有“拒绝/转人工”完成收口。
  19. 黑名单只能从当前已布防会话执行“加入黑名单”，保存显示名和 headerFingerprint；加入后立即停用该会话、收口当前输入并停止继续观察。再次布防时只按完整指纹精确阻断；指纹变化视为未知会话并要求操作者重新确认，不能仅凭同名放行或拦截。移出黑名单不会自动重新布防；MVP 隐藏自由输入添加和白名单。

5.6 MVP 最小价值闭环

本轮只交付一个可重复的本机价值链，不扩展为团队协作或通用运营平台：

阶段 用户目标 MVP 必须提供 闭环信号
首次配置 完成运行前提 模型连接、托管设置、单微信窗口、标注、启动检查 启动检查全部通过
首次建议 确认识别和建议正确 布防后的真实测试消息、观测归并、知识引用 生成可审阅且尚未批准的建议
首次发送 安全完成一次真实动作 人工确认、发送前复检、Outbox、UI 执行证据 观察到本方气泡或明确进入未知对账
异常恢复 不因崩溃重复发送 持久状态、未知结果、人工对账、急停 重开后不自动重放副作用

只有这四步在真实 Windows 测试账号上可重复完成，才称为 MVP 闭环；页面数量、资源 CRUD 和模拟成功不计入。

5.7 MVP 定位与范围

MVP 收窄为：一名本机操作者，在一台 Windows 电脑上使用单个已登录微信窗口，手工打开并明确布防一条一对一纯文本会话，为基线后的新入站咨询生成有引用的建议回复，并在逐条人工确认后发送。

  • 首要任务：在一条当前会话内缩短文本咨询等待时间，同时确保操作者可以审核、拒绝、切换和接管。
  • 非目标：联系人列表扫描、未读识别、自动切换联系人、多会话并行、群聊、语音、图片、视频、文件、小程序卡片、引用/撤回消息、主动营销、批量触达、自动加好友、多微信账号、白名单全自动发送、团队账号和远程同步。
  • 运行形态：本机单用户、单数据目录、单微信窗口、单条活动会话、用户自备模型密钥（BYOK）；不实现账号系统、Workspace、RBAC 或远程控制面。
  • 非支持消息或会话切换只生成“转人工/重新布防”提示，不进入自动决策；支持矩阵外环境直接阻断运行。
  • MVP 验收只看首次就绪、建议生成、人工确认、UI 执行证据、未知结果收口以及确认错发/重发是否为 0；不新增运营指标或数据看板。

5.8 核心状态与事务边界

页面不能直接修改业务状态：

ReplyRun
  deciding → awaiting_approval → queued → executing → completed
           ↘ rejected | failed | expired | superseded
  executing → unknown_result → completed
  completed.outcome:
    observed_sent | reconciled_sent | reconciled_not_sent | reconciled_unresolved

Approval
  pending → approved | rejected | expired | superseded

OutboxMessage
  queued → executing → observed_sent
  queued → cancelled | expired | superseded
  executing → unknown_result
  unknown_result → reconciled_sent | reconciled_not_sent | reconciled_unresolved

SendAttempt
  started → input_verified → action_performed → evidence_observed
  点击前失败 → failed
  点击后证据不足 → unknown_result
  • 批准、创建 Outbox 和把 ReplyRun 改为 queued 在同一 SQLite 事务内完成；重复批准只能返回原结果，不能产生第二条 Outbox。
  • 批准命令必须同时匹配 ReplyRun 的 state='awaiting_approval'、revision、contextVersion、configRevision 和待批内容 hash；双击相同请求返回原 Outbox，任一字段变化则冲突并重新加载，不能批准旧建议。
  • 消费者使用条件更新把 Outbox 与 ReplyRun 同时改为 executing，并创建同一 executionId 的 SendAttempt；受影响行数不是 1 时不得执行键鼠动作。
  • Outbox 或 SendAttempt 每次状态变化都在同一事务内更新 ReplyRun；进入 unknown_result 时 ReplyRun 同步进入待核对，终态时同步写入 outcome。微信分身页只查询 ReplyRun 聚合状态，不跨表猜测。
  • 新消息、会话头变化、手工发送、重新标注、提示词/回复规则/模型配置变化或引用知识停用时，旧 ReplyRun、待审批项和未执行 Outbox 同时 superseded。
  • replyDeadlineAt/expiresAt 由现有“单日消息最长等待”配置计算；超过时间后 ReplyRun、Approval 和未执行 Outbox 同时 expired。免打扰或暂停不会延长旧消息时效，恢复后需要按最新上下文重新生成。
  • 点击发送前失败时关闭本次尝试，不自动回到 queued；需要继续时基于最新上下文重新生成并再次批准。
  • 点击发送后证据不足时进入 unknown_result；只能由用户标记“确认已发 / 确认未发 / 无法判断并转人工”。
  • 应用启动时先把遗留 executing 转为 unknown_result；完成核对前不消费新 Outbox。迟到回调必须同时匹配 state='executing' 与 executionId，不能复活已收口记录。
  • 同一当前会话只允许一条非终态 ReplyRun；MessageObservation(conversationId, seq)、Approval.runId、OutboxMessage.runId 和 SendAttempt.executionId 分别唯一，观测 seq 在 SQLite 事务内按会话递增。
  • Run 进入 observed_sent/reconciled_sent/rejected/manual_takeover/reconciled_unresolved/expired 时，在同一事务内把 inputObservationIds 标为 handled/manual 并推进 Conversation 处理水位。reconciled_not_sent 保留输入为 pending，直到用户重新生成或明确拒绝/转人工。
  • 新消息使未执行 Run 失效时，原输入回到 pending；稳定窗口结束后与新消息合并生成替代 Run。存在 executing/unknown_result 时只积累 pending，不并行创建新 Run。

5.9 不可信输入与模型输出边界

客户消息、OCR 文本和知识正文均是不可信内容。该边界只保护现有建议回复功能，不增加工具系统：

  1. 固定系统提示、自定义提示词、回复规则、当前消息和知识引用分开组装；消息或知识中的“忽略规则”“调用工具”等文字只能作为内容。
  2. 模型输出只接受建议正文、引用和风险提示；出现 actions、tool_calls、坐标、按键或未知字段时整次结果失败并转人工。
  3. 模型不能直接调用鼠标、键盘、发送消息、访问网页或执行 Go/Python Action；批准后的固定 Tauri 发送流程是唯一副作用入口。
  4. 提示词、模型配置或启用知识变化后，旧待批准建议失效；组合提示词预览只展示最终文本，不调用模型、不创建 Approval 或 Outbox。
  5. 验收至少覆盖客户消息和知识正文中的提示词注入，确认它们不能绕过人工确认或产生键鼠动作。

6. MVP 业务闭环设计

6.1 微信分身与引擎工作台

目标：主页面与日志工作台读取同一个真实 EngineState。

  1. 页面打开时查询真实引擎状态，事件只做增量更新；操作失败后重新查询。
  2. 启动检查必须真实验证模型配置、标注完整性和微信窗口；任一失败都不启动 Agent。
  3. 启动 Agent 失败时停止已启动的视觉流，并显示真实错误。
  4. “暂停/恢复自动发送”改为“暂停/恢复已批准发送”；暂停不停止观测，也不能绕过逐条人工确认。
  5. 停止或重启时先停止接收新发送；正在执行或结果未知的项先进入核对，不能直接 kill 后显示安全停止。
  6. 工作台订阅真实日志，保留级别/模块/关键字筛选、暂停滚动、清空视图和详情复制。
  7. 浏览器降级明确显示“演示模式”，不用真实运行的成功文案。

验收：重开页面状态一致；启动检查失败会阻止启动；Agent 启动失败会回滚视觉流；主页面与工作台状态同步；停止/重启不会自动补发未确认结果；日志来自真实事件。

6.2 MVP 知识

目标：把现有知识页收敛为可持久化、可检索、可引用的文本知识，并保持版本引用不漂移。

  1. 只支持粘贴纯文本和 UTF-8 TXT；PDF、DOCX、图片、视频、OCR/ASR 和后台解析任务不进入本轮。
  2. Knowledge 保存标题、标签、状态和当前版本；每次正文编辑发布新的不可变 KnowledgeVersion，再按段落建立指向该版本的 FTS5/BM25 索引。
  3. 搜索字段沿用现有标题、标签和完整正文；列表保留搜索、新增、编辑、发布/停用和删除，不实现复杂解析向导。
  4. 建议引用冻结 knowledgeVersionId/passageId/sourceLocator/excerpt；知识更新后，历史引用仍指向原版本，待批准建议则失效并按新版本重新生成。
  5. 停用或删除后，新建议不能再引用该知识；待批准建议同时失效。已完成 ReplyRun 只读取自身保存的引用快照，不把可变 Knowledge 当作历史证据。

验收：粘贴文本、TXT 导入、标签、保存、检索、引用、版本、停用和删除均持久化；不同知识 id 返回不同内容；更新正文不会改变历史建议引用；长文只返回相关段落。

6.3 MVP 提示词与回复规则

目标：复用现有“提示词配置”和“回复规则”，只负责生成建议，不建设 Skill 或工具编排。

  1. 固定提示词只读，自定义提示词保留 4,000 字限制并持久化；“预览组合提示词”展示最终文本但不调用模型、不发送。
  2. 生成输入只包含固定/自定义提示词、当前会话文本、命中知识和现有回复规则。
  3. 免打扰和黑名单在生成前与发送前使用同一份已保存配置；把当前会话加入黑名单时立即停用布防、取消未执行发送并将当前输入转人工，移出后必须由操作者重新打开并布防。
  4. 自动加好友、主动联系客户、开启蒸馏和白名单在本轮隐藏，因为 MVP 不主动联系、不自动加好友、不蒸馏，也不存在白名单免人工确认。

验收：提示词和规则保存后重开不丢；组合预览不调用模型或发送；黑名单与免打扰能阻断发送；提示词、知识或规则变化会使旧待批准建议失效。

6.4 Skill、Employee 与蒸馏

本轮 不实现 Skill CRUD、工具沙箱、自定义 Employee、聊天蒸馏、评估发布和在线反馈训练。相关页面保留为开发预览或从生产构建隐藏，不能连接模拟成功，也不能成为 G0–G3 的依赖。

6.5 设置中心

目标：把现有设置中的 MVP 必需项接到真实持久层，不新增设置分区。

  1. 打开时调用 get_config；所有字段使用受控状态并维护 dirty/saving/error。“恢复”必须恢复最近一次已保存值，不能只清除 dirty。
  2. 基础配置保留厂家、请求地址、API Key、模型名称和请求超时；API Key 保存到系统密钥库，前端只接收 keyConfigured。
  3. “测试连接”使用当前表单值，返回鉴权失败、超时、模型不存在或网络不可达等真实结果。
  4. 提示词配置保留固定提示词、自定义提示词和组合预览；回复规则只保留免打扰，以及“将当前已布防会话加入/移出黑名单”，不保留自由输入名单。
  5. 知识库管理保留总开关、最大返回数、搜索字段和逐知识启停。
  6. 托管配置保留开启托管、本地消息服务、发送前人工确认、异常自动暂停、连续异常阈值和单日消息最长等待；MVP 中“发送前人工确认”固定开启且不可关闭，本地消息服务关闭时就绪检查失败且不能启动托管处理。
  7. Skill、员工、自动加好友、主动联系、开启蒸馏和白名单隐藏或明确标记为非 MVP，不保存为生效配置。
  8. 保存调用 save_config(config, revision)；并发冲突提示重新加载，保存失败保留表单内容且不覆盖旧配置。保存成功后主窗口重新查询模型与引擎就绪状态。

验收：重开配置不丢；恢复按钮恢复字段；密钥不回显；连接成功与各类失败都有真实反馈；托管或本地消息服务关闭时不能启动自动处理；人工确认始终开启；异常达到阈值后暂停新建议和发送；非 MVP 设置不会影响运行链。

6.6 屏幕区域标注

目标：以现有 Windows 原生透明 Tauri overlay 作为唯一生产入口，消除双实现和契约漂移。

  1. ClonePage 的“标注微信”只调用 enter_window_select_mode 进入原生 overlay；React /annotate 降为显式开发调试路由，不进入正式导航、不发送生产完成事件，也不维护第二套保存规则。
  2. 单会话 MVP 的生产必需区域统一为 conversation_header、chat_content、input_box、send_button；不依赖 contact_list/unread_message 扫描和点击。原生保存校验、ClonePage 启动检查、Go/Rust 消费端和文案共同引用同一份契约；custom 只能附加，不能替代必需类型。
  3. 保存前校验必需类型、区域非空、边界合法、同类型唯一性；返回字段级错误。发送执行器启动前必须再次确认 conversation_header 和 send_button，消息检测前必须确认当前会话头指纹。
  4. 有未保存修改时关闭应二次确认；截图变化、微信版本变化或窗口尺寸变化后，旧坐标必须标记失效并要求重验，不能静默尺寸映射后直接用于发送。
  5. Windows/Tauri 环境实测窗口选择、DPI 缩放、多显示器、截图读取、保存、重新加载和退出通知；原生 overlay 之外的旧 Go/Python macOS 捕获路径不得作为 Windows 验收证据。

验收：正式入口只有原生 overlay；启动检查、保存和消费端使用同一必需类型；高 DPI/多屏坐标可复现；未保存退出不会静默丢数据；缺少 conversation_header、chat_content、input_box 或 send_button 均不能布防。生产运行不会扫描联系人列表、点击未读项或自动切换会话。

6.7 会话、建议、确认与发送

目标：打通现有自动回复方向所需的最窄真实链路。

  1. 操作者在微信中手工打开目标一对一会话，再点击“布防当前会话”；系统记录会话头指纹并建立基线。
  2. 捕获只覆盖 conversation_header/chat_content/input_box/send_button；会话头变化、群聊或非文本消息直接转人工。
  3. 新文本稳定出现后，从 Conversation 处理水位之后取全部 pending 入站观测，检索当前启用知识版本的相关段落，并生成一条建议及不可变引用快照。
  4. 微信分身页的“当前会话与待确认”区域提供“批准并排队发送、编辑后重新确认、拒绝、转人工”；不新增一级待处理页，也不能使用模拟延时制造成功。
  5. 新消息在点击发送前到达时，旧建议和未执行发送失效；稳定后把旧输入与新消息合并生成替代建议。当前存在执行中或未知结果时只积累 pending 观测，对账结束后再生成。
  6. 发送前确认窗口、会话、输入框为空、待发全文和发送按钮；输入框已有草稿时保持原样并转人工。
  7. Tauri 发送流程只写入一条完整文本并点击一次 send_button；Go/Python 实验路径不作为生产发送入口。
  8. 点击后观察输入框变化和本方消息气泡；证据充分显示“已观察到本方气泡”，证据不足显示“结果未知”，不显示服务端送达或已读。
  9. 结果未知时不自动重试；用户完成“确认已发 / 确认未发 / 无法判断”后关闭原尝试，需要再发时重新展示并确认。
  10. 停止、重启或异常退出不得自动重放 executing/unknown 项；恢复后先展示待核对状态。
  11. Outbox 必须由当前唯一应用实例通过 SQLite 原子条件更新取得执行权；发送结果只接受同一 executionId，重复消费和迟到回调不能产生第二次发送或覆盖较新状态。
  12. 结果未知区域展示发送前后结构化观测或聊天区域裁剪以及三个核对动作；证据缺失时只能选择“无法判断并转人工”。
  13. 免打扰期间只保留新观测，不生成或执行回复；超过“单日消息最长等待”的观测和未执行 Outbox 转为 expired，结束免打扰后不能自动补发。
  14. 识别、检索、模型、预检或发送连续失败达到现有配置阈值时，EngineState 进入 paused 并停止新建议与发送；用户查看真实错误并手工恢复后计数清零。
  15. 观察到本方气泡、确认已发、拒绝、转人工、无法判断或消息过期时推进 Conversation 处理水位，保证重启后不重复生成；确认未发时不推进，用户必须选择重新生成或明确拒绝/转人工。
  16. “转人工”会设置 manualTakeover=true 并推进当前输入水位；人工模式下只保留界面状态，不生成新 Run。用户解除接管时重新确认当前会话并建立新基线，人工期间积压不自动回复。

验收：在真实 Tauri Windows、受支持微信版本和隔离测试账号中，从布防后的新文本到知识版本引用、建议、人工批准、一次发送和 UI 证据可重复完成；历史内容和已处理输入不重复生成；新消息会形成包含全部未处理输入的替代建议；未知结果期间的新消息不会丢失或并行发送；相同文本不被误吞；非空草稿不被覆盖；切换会话不会使用旧建议；点击后崩溃不会自动补发。

6.8 本地数据与密钥安全

目标：保护现有模型配置、知识、聊天观测和运行日志，不新增合规工单或备份产品。

  1. MVP 只有当前 Windows 会话下的一名本地操作者，不实现账号、Workspace 或多角色。
  2. API Key 保存到系统密钥库；前端只读取 keyConfigured，密钥不得进入 localStorage、日志或诊断内容。
  3. SQLite 只保存完成当前功能所需的配置、知识段落、消息观测、回复状态和日志；原始整窗截图默认不持久化。
  4. 捕获只限当前已布防会话区域；会话头变化后停止持久化和模型请求。
  5. 模型请求只发送生成当前建议所需的文本和命中知识，不发送其他窗口内容。
  6. 日志默认脱敏，禁止记录 API Key、完整系统提示、剪贴板内容和无关聊天原文。

验收：密钥不回显且不出现在日志；未布防会话内容不落盘、不进入模型；诊断信息不包含密钥和无关聊天原文。

6.9 首次运行就绪

目标：让用户通过现有页面顺序完成第一次真实运行，不新增独立引导向导。

微信分身页显示就绪清单和直达入口，顺序为：模型连接 → 选择并标注微信窗口 → 托管与人工确认配置 → 导入一条测试知识 → 操作者手工打开测试会话并布防 → 发送一条基线后的测试消息 → 查看建议与引用 → 人工批准 → 观察本方消息气泡或进入结果核对。

验收：全新本地数据目录可从现有微信分身、知识、设置和标注入口完成首条有引用、经批准且有 UI 执行证据的测试回复；中途失败不显示成功，不依赖新路由或手工编辑配置文件。

6.10 运行日志与诊断

目标：把现有日志工作台接到真实运行事件，而不是扩展分析或训练平台。

  1. 日志字段沿用页面现有结构：时间、级别、模块、消息、requestId。
  2. 支持级别/模块/关键字筛选、暂停滚动、清空当前视图和复制详情。
  3. 日志使用限长缓冲；前端重开后从后端读取最近记录。
  4. 每次建议、批准、发送尝试和未知结果使用同一 requestId 串联。

验收：启动、识别、检索、模型、批准、发送和错误均有真实日志；筛选与暂停不影响后台运行；日志不含 API Key 和无关聊天原文。

6.11 本地持久化与升级

目标：让现有配置、知识和运行状态重开不丢，不新增用户可见的备份/恢复业务。

  1. SQLite schema 采用版本化迁移；迁移在事务中执行，失败时保持旧库不变并阻止启动引擎。
  2. 配置、知识、标注、当前会话、非终态 ReplyRun、Outbox、SendAttempt 和最近日志均从后端读取，不以 React state 作为唯一来源。
  3. 应用升级或启动后重新检查微信窗口、标注和当前会话；遗留 executing 先转 unknown_result，核对完成前不消费新 Outbox。
  4. 数据库损坏或版本不兼容时显示明确错误和数据目录位置，不伪装为空数据或自动覆盖。

验收：重开应用后配置、知识、当前会话与微信分身页待确认状态一致；迁移失败不破坏原库；升级后旧执行中发送不会自动重放。

6.12 非目标、运行前提与发布边界

MVP 明确不做：群聊与非文本自动回复、多微信账号、白名单自动发送、后台无人值守、团队协作、主动营销、自动加好友、跨设备同步、在线自学习、Skill/Employee/蒸馏、向量数据库和多渠道客服。运行时要求 Windows 会话未锁定、目标微信窗口属于已标注实例且状态可识别；窗口关闭、账号切换、版本/DPI 不兼容、界面证据不足或系统休眠后，一律暂停并要求重新就绪检查。支持矩阵外环境显示“不受支持”，不能静默降级。

6.13 可靠性边界

发布前只验证主链必需的故障：断网、模型超时、微信窗口移动/关闭、会话切换、输入框已有草稿、sidecar 异常退出、应用强制退出和磁盘不可写。任何故障都必须停止新发送、保留可诊断错误，并且不得产生未批准发送、重复发送或跨会话发送。

6.14 故障处置

  1. 复用“停止引擎”作为全局急停，并保留取消尚未执行项、重新标注和查看真实日志入口，不新增独立风险中心。
  2. 发生错发、重复发送、跨会话串话或密钥泄漏时，立即停止发送能力，不自动恢复。
  3. 候选版本记录应用、sidecar、Windows、微信、DPI 和模型版本，便于复现。

验收：急停可阻断尚未执行的 Outbox；高风险故障后不自动恢复发送；日志足以关联到具体 ReplyRun 和 SendAttempt。

7. 实施顺序与发布闸门

实施顺序围绕一条现有功能链，不按页面数量推进。

G0：冻结最小契约

  1. 统一原生标注区域：conversation_header/chat_content/input_box/send_button。
  2. 冻结单 Windows 操作者、单微信窗口、单条手工布防的一对一纯文本会话、逐条人工确认和 UI 证据口径。
  3. 定义最小数据模型、状态迁移、原子 Outbox 执行权、executionId 回写条件和结构化错误；移除页面模拟成功。

出闸条件：前端、Rust 和 sidecar 使用同一标注及发送契约；不再声称服务端送达；Skill、Employee、蒸馏不阻塞主链。

G1：接通真实状态

  1. 建立 SQLite 持久层和薄服务层，接通现有设置、知识、引擎状态、日志和标注。
  2. 持久化提示词、免打扰、当前会话黑名单、知识启停、托管开关、人工确认、异常暂停阈值和消息最长等待；实现当前会话布防、基线、处理水位、消息观测、不可变知识版本、段落 FTS5 检索和建议生成。
  3. 扩展微信分身页展示当前会话、待确认建议和未知结果；实现新消息合并替代 Run、未知期间 pending 积累和已处理水位恢复；页面重开与多窗口读取同一后端状态。

出闸条件：重开后配置、知识版本、引擎、处理水位和微信分身页待确认状态一致；基线历史消息与已处理输入不创建建议；新消息不会只失效旧 Run 而漏建替代 Run；托管关闭、黑名单、免打扰、消息过期和连续异常阈值均能阻断相应处理；日志来自真实事件。

G2：交付人工确认回复闭环

  1. 接通建议展示、引用、批准/编辑后重新确认/拒绝、Outbox 和一次发送。
  2. 完成单实例、SQLite 原子执行权、executionId 条件回写、窗口/会话/输入框/全文复检、非空草稿保护和发送前后证据。
  3. 完成未知结果人工核对、聚合状态同步、停止/崩溃恢复和禁止自动重发。

出闸条件：真实 Tauri Windows 测试账号可重复完成首条回复；未批准、重复和跨会话发送均为 0；双开应用、重复消费、迟到回调和点击后崩溃均不会补发或覆盖较新状态。

G3：发布验证

  1. 验证微信分身、知识、设置、日志和标注五个 MVP 界面的正常和错误状态。
  2. 演练断网、模型超时、窗口变化、会话切换、非空草稿、sidecar 退出、应用退出和磁盘不可写。
  3. 隐藏或明确标记未接真实后端的预览页面。

出闸条件：主链验收记录完整；浏览器 mock 不计作证据；Windows 支持范围和已知限制写实。

8. 完成定义与验收矩阵

页面从原型升级为 MVP 必须满足：

  • 数据来自真实后端状态，不来自 mock 或固定延时。
  • 重开窗口后状态不丢，多窗口读取一致。
  • 具备 loading、empty、error、success 和 disabled 等必要状态。
  • 失败不显示成功，敏感字段不回显、不进入日志。
  • 关键路径在真实 Tauri Windows 环境验证。

最小验收矩阵：

领域 正常路径 必测异常路径
设置 加载、模型测试、保存 鉴权失败、超时、保存失败、重开
知识 粘贴文本/TXT、段落检索、引用、停用 空文档、编码错误、长文、停用后旧建议
标注 选择微信窗口、四区域保存、重载 缺失区域、窗口尺寸变化、DPI/多屏
引擎 启动检查、启动、暂停、停止、真实日志 Agent 启动失败、窗口关闭、sidecar 退出
当前会话 手工布防、建立基线、从处理水位识别新文本、新消息合并替代 Run 历史/已处理消息、未知期间新消息、相同文本、OCR 抖动、会话切换
建议与确认 冻结输入与知识版本引用、生成、编辑、批准、拒绝 配置/知识更新、新消息使旧建议失效、重复批准、旧 revision/contentHash
发送 空输入框、完整写入、单击、UI 证据 原草稿、焦点漂移、回读不一致、点击后崩溃
未知结果 确认已发、确认未发、无法判断 应用重启、禁止自动重试、原 Outbox 不复活
本地持久化 重开恢复、schema 迁移 迁移失败、磁盘不可写、数据库不兼容

只有上述主链全部通过，才能称为最小 MVP；其余页面完成度不影响本轮结论。

9. 最终结论

当前项目是“界面覆盖较完整、少量原生能力接线的桌面原型”，不是已经可用的 Windows 微信自动回复产品。

最小 MVP 只保留现有功能能够形成的链路：模型/提示词/托管设置 → 微信标注 → 引擎启动 → 手工布防当前会话 → 水位后的新文本识别 → 知识版本段落检索 → 建议回复 → 逐条人工确认 → 一次发送 → UI 证据或人工核对 → 推进处理水位 → 真实日志。待确认与结果核对并入现有微信分身页，不新增一级页面；Skill、Employee、蒸馏、团队账号、跨设备能力和自动联系人发现均不进入本轮。

必要技术闭环仅用于保证上述现有功能真实可用：SQLite 持久化、统一标注契约、当前会话基线与处理水位、不可变知识版本、输入合并替代 Run、Outbox 原子执行权、executionId 条件回写、发送前复检、用户草稿保护、聚合状态同步、未知期间 pending 积累、未知结果不自动重试、异常恢复不自动补发，以及 Tauri 侧固定键鼠流程。这些是现有自动回复功能的执行条件，不是新增业务模块。

本报告不声明 Windows 视觉自动化、微信 RPA 或自动发送已生产可用；旧 Go/Python 捕获链路仍包含明显的 macOS 实验路径，最终能力必须由真实 Tauri Windows 端到端记录证明。