dsh-xrxs-lingting 0.4.0-dev.47

package/README.md

@@ -0,0 +1,97 @@
+# dsh-xrxs-lingting
+
+灵听 DSH 插件：数据列表在主页面（业务插槽），实时转写在右侧面板，在聊天旁边使用。已对接真实后端（aim 表单接口 + cinlyn JSON/SSE + 转写 WebSocket），麦克风与系统声音混合采集 16kHz PCM，记录保存在服务端。
+
+## 运行与打包
+
+需要 Node.js 22.12+。
+
+```sh
+npm ci
+npm test
+npm run build
+npm run build:plugin                 # Host bundle + 前端 + 原生 helper，产物与环境无关
+npm pack                             # 出 DSH 插件包（prepack 先跑 build:plugin）
+```
+
+`.tgz` 为 DSH 插件包，`dist/` 为独立网页预览。**环境与凭据由「薪人薪事授权」插件决定**
+（面板里改地址即换环境），灵听产物本身与环境无关；详见 [连接与环境说明](docs/env-switch.md)。
+
+`npm run dev` 打开组合预览（主页面 + 侧栏，含模拟宿主布局），仅用于 UI 样式与交互开发——
+业务数据需在 DSH 宿主内使用。
+
+DSH 中的实际体验和安装见 [Desktop Dev 说明](docs/desktop-dev.md)；环境名表、两种运行形态与排错见 [环境切换指南](docs/env-switch.md)。
+
+## 会议声音采集
+
+线上会议默认使用「麦克风 + 系统声音」，也可在开始面板选择「仅麦克风」用于线下交流。
+需要同时更新 **灵听插件和 DSH Desktop 宿主**：只有插件升级，旧宿主仍无法提供系统音频。
+录音侧栏分别显示两路音量；系统音轨缺失时不会悄悄退化为仅录麦克风，原生采集中断会暂停录音。
+平台条件、权限、测试边界和验收步骤见 [跨平台会议录音说明](docs/system-audio.md)。
+
+## 传输与授权
+
+业务请求统一经同源 Host 路由发送。Host 从 `ctx.xrxsAuth` 现取凭据，按部署绑定访问业务网关；浏览器不持有 Cookie、CSRF 或 access token。独立预览用于 UI 开发，真实业务需在 DSH 中验收。
+
+授权适配以 `xrxs-dsh-auth@0.2.6` 消费契约为基线，按能力判断，不根据版本号猜测接口。
+本机核对的 0.2.3 包也已有 `authorize()`，可以使用显式入口；只有缺少该方法的 provider 才需要去授权插件面板操作。
+
+未授权时，灵听显示「开始授权」；点击后 Host 在后台发起设备码流程，授权插件打开浏览器。
+等待期间按钮禁用，状态每次读取完成后约 3 秒再刷新；确认并建立业务上下文后自动进入列表。
+取消、验证码过期或网络失败会显示原因并恢复重试入口，正常状态恢复为约 20 秒轮询。
+
+**部署前提**：支持按需授权的授权插件应设置 `grant.authorizeOnDemand: false`。
+预检能拦住已知未授权状态，但无法消除预检之后凭据失效、续期被拒所触发的隐式交互；关闭该配置才能保证后台不弹窗、不等待人确认。
+显式 `authorize()` 不受此开关限制，配置位置见 [环境说明](docs/env-switch.md#4-显式授权与部署前提)。
+
+业务未就绪时仍显示具体原因（插件缺失、未配置、未授权、授权中、身份未知或目的地未确认）。
+实现、差异与验收项见 [按需授权优化实施文档](docs/plans/2026-09-16-授权按需授权优化实施文档.md)；
+早期凭据联调记录见 [对接说明](docs/薪人薪事授权-对接说明.md)。
+
+### P0 探针（只读诊断）
+
+设 `LINGTING_XIN_PROBE=1` 启动时，插件在 Host 内跑一次只读矩阵（11 种凭据形态 × 3 个头档位 × 2 个业务前缀），把报告写进 harness 日志，
+同时注册 `POST /api/lingting/xin.probe`；**未设置该变量时这条路由不存在**。报告只含形状（长度/有无/命中），不含 `sessionId` / `csrf` / token 的值。
+
+```bash
+LINGTING_XIN_PROBE=1 nohup "/path/to/DSH Desktop Dev.app/Contents/MacOS/DSH Desktop Dev" >/dev/null 2>&1 &
+```
+
+## 能力
+
+- 主页面数据列表：搜索、状态筛选、分页、详情、AI 纪要重新生成、重命名、删除。
+- 480px 右侧实时转写面板：折叠控制栏、展开阅读、收起后浮动状态入口（录音继续）。
+- 真实录音链路：getUserMedia + 原生系统音频（macOS Core Audio Tap / Windows WASAPI / Linux PulseAudio monitor） → 双路混音 → AudioWorklet 降采样 → 1600 采样 PCM 分块 → WS 上传；在线增量/离线定稿合并、发言人、时间戳。
+- 暂停/继续复用同一 recordId 重连；结束失败保留 finish-error 可重试；异常掉线标记断连。
+- 逐段追问建议与 SSE 流式速答；复制转写、TXT 导出。
+- 开始录音自动弹出侧栏；主页面与侧栏共享同一服务实例。
+- AI 纪要分享：企业内可见（按部门/员工授权，服务端登录后校验范围）或互联网公开，复制服务端生成的分享链接；回显上次设置。
+- 会议自动提醒（P1，默认关闭）：插件自带 macOS 原生 helper 采样音频活动，识别钉钉 / 腾讯会议等候选会话后由 Host 仲裁并提醒，确认后一键开始转录；检测能力不可用时如实报告，不影响手动录音。
+
+尚未实现：双方采音（会议声音混入、原生采集分片，P2）、拖拽和跨窗口录音协调。
+
+## 工程入口
+
+| 路径 | 内容 |
+| --- | --- |
+| `src/plugin/client.tsx` | DSH 插件入口，desktop.business.page / shell.overlay / sidebar.footer.action 三插槽 |
+| `src/plugin/host.ts` | Host 半边入口（Harness Node 进程）：helper 监督、提醒策略与 `connection.fetch` 路由 |
+| `src/plugin/native/` | helper 产物定位、私有协议（NDJSON）与 supervisor（握手、水位、心跳、重启） |
+| `src/plugin/meeting/` | 提醒策略、配置持久化、前端在场聚合与路由 |
+| `native/macos/lingting-helper.swift` | 原生 helper：音频活动采样、应用适配、每应用会话状态机、`--probe` 标定模式 |
+| `src/services/xin-service.ts` | `XinLingtingService`：真实后端编排（生命周期、转写、问答、目录） |
+| `src/integrations/xin-ui/` | 后端契约层：protocol（请求/wire/转写/SSE）、http、ws、config、units |
+| `src/audio/` | 麦克风与系统声音：双路音量、混音、AudioWorklet 降采样、PCM 分块 |
+| `src/sidebar/LingtingSidebar.tsx` | 右侧实时转写面板 |
+| `src/App.tsx` / `src/pages` | 主页面数据列表与记录详情 |
+| `src/sidebar/controller.ts` | 面板显示状态，与录音服务独立 |
+| `src/domain/types.ts` | 服务接口与数据模型 |
+| `scripts/install-desktop-dev.mjs` | 使用本机 Dev 的版本注册表更新插件 |
+
+原 Web 代码位置、接口字段、生命周期、宿主契约及剩余待办见 [侧栏与后端接入说明](docs/xin-ui-sidebar-integration.md)；原文见 [源码摘录](docs/reference/xin-ui-excerpts.md)；测试见 [验证记录](docs/verification.md)。
+
+## 数据说明
+
+记录保存在公司服务端（aim/cinlyn），插件不落本地数据文件。业务 origin、平台身份与 moduleId 等上下文由宿主或 `VITE_*` 环境变量注入，见 `src/integrations/xin-ui/config.ts`。
+
+凭据由 Host 经 `ctx.xrxsAuth` 现取，浏览器不持有，也不在授权失败时回退到直连或本机 Cookie 注入。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# 插入本插件的运行实例（Host 半边）。
+#
+# name 使用相对路径（相对本文件所在目录）：@deepseek-ai/dsh-app-boot 的
+# anchorInsertedPluginNames 会把 "./" 开头的 name 解析成本文件所在目录下的文件 URL，
+# 不依赖宿主对裸包名的模块解析锚点（profile / app 的 node_modules 差异）。
+- insert:
+    - id: dsh-xrxs-lingting
+      name: ./plugin-dist/index.js

package/docs/DSH/347/201/265/345/220/254/351/233/206/346/210/220/346/223/215/344/275/234/346/211/213/345/206/214.md

@@ -0,0 +1,497 @@
+# DSH 灵听集成操作手册
+
+> 2026-09-11 更新：DSH 插件已改为右侧面板，本文件保留早期主区域方案供追溯。当前安装与接口接入以 [灵听侧边栏与 Web 后端接入说明](xin-ui-sidebar-integration.md) 为准；旧 business 插槽补丁不再是侧栏插件的前置要求。
+
+
+版本：1.0 · 日期：2026-09-10  
+适用对象：公司 DSH 桌面端、前端、插件及后端开发人员
+
+## 1. 先看结论
+
+本次集成包含两部分：**灵听插件包 + DSH 主程序的业务页面接入能力**。用户从左侧「灵听」进入主内容区域；切回聊天时，模拟录音继续，聊天区域底部显示控制条。
+
+仅把网页 `dist/` 复制进 DSH，或者仅安装插件 `.tgz`，都不能自动得到上述效果。公司版需要提供本文第 5 节的宿主接口，或把灵听适配到公司已有的页面、导航和插件接口。
+
+当前交付是 **Mock 页面与交互集成**：音源、波形、转写均为模拟。增加的本地 Host 接口用于保存演示记录，不是公司业务后端，也没有接入真实录音、账号或语音识别服务。
+
+本机操作和测试结果已验证；公司自研 DSH 的源码、版本及发布链路尚未核对，因此公司部分是实施步骤与适配要求，不代表已在公司产品验证通过。
+
+## 2. 本次本机集成做了什么
+
+### 2.1 实际操作记录
+
+| 操作 | 修改内容 | 目的 |
+|---|---|---|
+| 建立开发分支 | 灵听：`codex/desktop-plugin`；DSH：`codex/lingting-desktop-dev` | 保存本次集成改动 |
+| 安装桌面项目依赖 | 在 DSH 源码目录执行 `npm ci`，应用仓库原有补丁 | 启动可修改的本地宿主 |
+| 将页面封装为插件 | 新增插件清单、Host 入口、浏览器入口和打包脚本 | 让 Harness 加载灵听 |
+| 对齐宿主 React | 插件构建使用 React 18；React 与 React DOM 由宿主提供 | 避免加载两份 React |
+| 隔离页面样式 | 样式限定在 `.lingting-root`，动画名称加前缀，增加嵌入布局 | 避免改变聊天页样式 |
+| 分离导航 | 独立网页继续使用 hash；插件使用内存导航 | 避免修改 DSH 自己的 URL 状态 |
+| 扩展 DSH 布局 | 增加业务页面导航及两个根级插槽 | 在主内容区展示灵听，并放置全局录音条 |
+| 接入侧栏与会话导航 | 「灵听」挂到已有侧栏插槽；新建/打开会话路径关闭业务页 | 在聊天和业务页面之间切换 |
+| 统一录音状态 | 页面和全局录音条共用一个 Mock 服务实例 | 切换页面后仍可控制同一场录音 |
+| 增加本地持久化 | Host 读写 `DSH_HOME/lingting-demo/records.json` | 重启后保留历史记录 |
+| 安装到 Dev profile | 安装 `.tgz`，在 profile 的 bundles 中启用；宿主随后迁移到受管插件版本目录 | 让实际 Desktop 加载插件 |
+| 验证与打包 | 自动化测试、真实 Electron 窗口验证，生成并启动 Dev `.app` | 交付可直接打开的本机测试版 |
+
+**本次使用独立的 DSH Desktop Dev 数据目录，没有覆盖 `/Applications/DSH Desktop.app`，也没有发布公司安装包。**
+
+### 2.2 当前版本和文件位置
+
+| 项目 | 本机位置或版本 |
+|---|---|
+| 灵听仓库 | `/Users/quwei/work/xrxs/code/dsh-xrxs-lingting` |
+| 灵听 Git 地址 | `http://code.qijiayoudao.net/ai/dsh/dsh-xrxs-lingting.git` |
+| 灵听集成代码提交 | `60ca730` |
+| Desktop 仓库 | `/Users/quwei/work/xrxs/code/dsh-desktop` |
+| Desktop 集成代码提交 | `3879672` |
+| 已验证 Harness 版本 | `0.1.2-rc.1` |
+| 已验证插件版本 | `0.2.0-dev.2` |
+| 已验证平台 | macOS Apple Silicon / arm64 |
+| 插件构建 Node 要求 | `>=22.12.0` |
+| 插件包 | Desktop 仓库下 `packages/lingting-bundles/dsh-xrxs-lingting-0.2.0-dev.2.tgz` |
+| 可运行应用 | Desktop 仓库下 `dist-dev/mac-arm64/DSH Desktop Dev.app` |
+
+上述两个集成提交目前保存在本机开发分支。编写本文时，灵听远端仅看到 `origin/main`，不能假定同事直接克隆 main 就能获得本次集成代码。交接时应先将相应开发分支同步到公司代码平台，或提供 Git 补丁。
+
+### 2.3 代码改动定位
+
+灵听仓库：
+
+| 文件 | 作用 |
+|---|---|
+| `package.json`、`cordis.patch.yml` | 插件标识、导出、依赖声明与启动条目 |
+| `scripts/build-plugin.mjs` | 生成 Harness 浏览器模块、处理样式隔离、输出 Host 文件 |
+| `src/plugin/client.tsx` | 注册侧栏、业务页面、全局录音条；管理共享服务生命周期 |
+| `src/plugin/contracts.ts` | 灵听依赖的宿主接口 |
+| `src/plugin/host.mjs` | 本机 Mock 记录读写接口 |
+| `src/plugin/persistence.ts` | 前端保存队列、延迟合并、失败提示及重试数据保留 |
+| `src/plugin/embedded.css` | 嵌入主区域后的高度、滚动、底部控制条样式 |
+| `src/domain/navigation.ts`、`page-scroll.ts` | 网页和嵌入模式的导航、滚动适配 |
+| `src/App.tsx`、`src/pages/*` | 返回聊天、可见状态、嵌入模式文案及页面交互 |
+| `src/services/mock-service.ts` | 模拟录音、转写与卸载后的中断处理 |
+| `src/domain/types.ts` | 后续真实服务需实现的 `LingtingService` 接口 |
+
+Desktop 仓库：
+
+| 文件 | 本次新增能力 |
+|---|---|
+| `patches/@deepseek-ai+dsh-client-ui-layout+0.1.2-rc.1.patch` | `ctx.layout.business`、主区域容器、业务页和全局状态插槽、类型声明 |
+| `patches/@deepseek-ai+dsh-client-ui-sidebar+0.1.2-rc.1.patch` | 从侧栏新建会话时返回聊天 |
+| `patches/@deepseek-ai+dsh-client-ui-workspace+0.1.2-rc.1.patch` | 打开会话时返回聊天 |
+| `package.json`、`package-lock.json`、`packages/lingting-bundles/` | 收录本地插件包 |
+| `scripts/install-lingting-dev.mjs` | 本机 Dev 首次安装和同版本检查 |
+| `test/lingting-business-navigation.test.ts` | 未注册页面、重复注册、卸载回退等导航测试 |
+
+三个 `.patch` 文件还包含 Desktop 原来已有的改动。移植时应查看提交 `3879672` 的差异，保留公司已有修改；不要把整个补丁文件当作全部由灵听新增，也不要直接覆盖公司补丁。
+
+## 3. 在本机继续使用
+
+### 3.1 直接打开已打包应用
+
+在访达中打开：
+
+```text
+/Users/quwei/work/xrxs/code/dsh-desktop/dist-dev/mac-arm64/DSH Desktop Dev.app
+```
+
+1. 若出现模型接入引导，选择「稍后配置」。Mock 测试不需要模型 API Key。
+2. 点击左侧「灵听」，进入主区域。
+3. 点击「开始灵听」并确认，即可测试模拟录音。
+4. 点击「返回聊天」，通过底部控制条继续操作。
+
+### 3.2 使用源码启动
+
+先退出打包版 Dev，再执行：
+
+```bash
+cd /Users/quwei/work/xrxs/code/dsh-desktop
+npm run dev
+```
+
+源码运行时应用名可能显示 Electron。源码版和打包版 Dev 使用同一套 Dev 数据，避免同时启动；正式版 DSH 使用另一套数据。
+
+### 3.3 本机数据目录
+
+```text
+Dev profile：
+~/Library/Application Support/dsh-desktop-dev/harness/profiles/web/
+
+灵听记录：
+~/Library/Application Support/dsh-desktop-dev/harness/lingting-demo/records.json
+
+Host 日志：
+~/Library/Logs/DSH Desktop Dev/harness.log
+```
+
+## 4. 从代码重新构建本机测试版
+
+以下命令对应已验证的两个本地仓库。换机器时替换仓库目录，先取得第 2 节的集成代码。对已有工作区先检查 Git 状态，保留未提交改动。
+
+### 4.1 构建灵听插件
+
+在灵听集成分支执行：
+
+```bash
+cd /Users/quwei/work/xrxs/code/dsh-xrxs-lingting
+npm ci
+npm test
+npm run build
+npm pack --pack-destination /tmp
+```
+
+两种产物的用途：
+
+| 产物 | 用途 |
+|---|---|
+| `dist/` | 独立网页预览 |
+| `plugin-dist/` | 插件 Host 与浏览器入口 |
+| `/tmp/dsh-xrxs-lingting-0.2.0-dev.2.tgz` | 供 DSH 安装的 npm 插件包 |
+
+`npm pack` 会执行 `prepack`，自动运行 `npm run build:plugin`。后续有代码变更应增加版本号，再打包；不要用同一版本反复替换包内容，避免包缓存与受管版本目录混淆。
+
+### 4.2 将包收录到 Desktop
+
+若使用本次 Desktop 分支中的原包，可直接跳到下一步。若替换为新构建包，先执行：
+
+```bash
+cd /Users/quwei/work/xrxs/code/dsh-desktop
+mkdir -p packages/lingting-bundles
+cp /tmp/dsh-xrxs-lingting-0.2.0-dev.2.tgz packages/lingting-bundles/
+npm install --save ./packages/lingting-bundles/dsh-xrxs-lingting-0.2.0-dev.2.tgz
+```
+
+版本升级时同时替换上述两处文件名。将插件包、`package.json`、`package-lock.json` 一起纳入版本管理。
+
+### 4.3 应用宿主改动并初始化 Dev
+
+在包含本次宿主改动的 Desktop 分支执行：
+
+```bash
+npm ci
+npm test
+npm run typecheck
+npm run build
+npm run dev
+```
+
+`npm ci` 的 `postinstall` 会运行 `patch-package`，从仓库补丁恢复宿主接入能力。因此不应只手工修改 `node_modules` 而不保存补丁。
+
+首次进入 Dev 主窗口后退出，完成 profile 初始化，然后执行：
+
+```bash
+node scripts/install-lingting-dev.mjs
+npm run dev
+```
+
+安装脚本只针对 **macOS 默认 Dev profile**：
+
+- 读取 Desktop 根依赖确定插件包路径。
+- 初次安装前备份 profile 的 `package.json`。
+- 使用 Desktop 自带的 pnpm 安装包，并把插件名合并到 `dsh.profile.bundles`。
+- 已由宿主管理插件版本且检测到同版本时直接返回。
+- 已由宿主管理版本、但需要安装其他版本时会停止，防止覆盖版本注册表；应走该宿主的插件安装/更新机制。
+
+**根项目依赖负责把包带入应用；profile/bundle 注册负责实际启用。两个步骤都需要。**
+
+### 4.4 打包可直接运行的 Dev 应用
+
+退出正在运行的 Dev，在 macOS arm64 的 Desktop 仓库执行：
+
+```bash
+CSC_IDENTITY_AUTO_DISCOVERY=false npm run package:dev:dir
+```
+
+本次最终使用此命令生成本地测试 `.app`，未做正式分发签名或公证。产物位于 `dist-dev/mac-arm64/DSH Desktop Dev.app`。
+
+公司正式分发应使用公司的应用标识、签名、公证、安装包和更新流程。不要把这条本地测试命令当作正式发布命令；Windows 和其他架构的构建、安装尚未在本轮验证。
+
+## 5. 公司自研 DSH 的接入要求
+
+### 5.1 先判断属于哪种情况
+
+| 公司版情况 | 实施方式 |
+|---|---|
+| 基于相同 Desktop 基线、Harness `0.1.2-rc.1` | 合并宿主提交的相关差异，构建并安装插件 |
+| 使用 Harness，但版本或 UI 布局已经改变 | 在公司源代码实现等价接口；按该版本的插件规范调整入口，重新验证 |
+| 已有自己的主区域路由、业务页容器和全局状态区 | 把灵听接入已有容器，编写导航及插槽适配，不必重复引入一套布局 |
+| 仅名称为 DSH，未使用 Harness/Cordis | 复用 React 页面、组件和服务接口；重写宿主桥接，当前 `.tgz` 不能直接安装 |
+
+第一步由公司 Desktop 开发确认：Harness 版本、React 版本、插件加载协议、主区域入口、全局状态区、数据目录、插件版本管理方式以及目标平台。
+
+### 5.2 必须提供的导航接口
+
+当前插件在 `src/plugin/contracts.ts` 声明了如下依赖，宿主通过 `ctx.layout.business` 提供：
+
+```ts
+interface BusinessController {
+  register(id: string): () => void;
+  open(id: string): void;
+  close(): void;
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): { activeId: string | null };
+}
+```
+
+行为要求：
+
+- `register()` 注册业务页并返回注销函数；重复 ID 应报错。
+- `open()` 激活已注册页面；未注册 ID 应报错。
+- `close()` 返回聊天，`activeId` 变为 `null`。
+- `subscribe()` 支持退订；`getSnapshot()` 在状态未改变时返回稳定引用，满足 React `useSyncExternalStore` 的要求。
+- 注销当前业务页时回到聊天，避免留下空白主区域。
+- 新建会话、打开已有会话等公司导航路径应调用关闭业务页的逻辑；按公司实际入口逐项覆盖。
+
+### 5.3 必须提供的页面位置
+
+| 插槽 | 类型/作用域 | 传给组件的属性 | 显示内容 |
+|---|---|---|---|
+| `sidebar.footer.action` | list / root，现有侧栏扩展位 | `{ wide: boolean }` | 灵听侧栏按钮 |
+| `desktop.business.page` | list / root，本次新增 | `{ activeId: string \| null }` | 灵听主页面 |
+| `desktop.business.status` | list / root，本次新增 | `{ activeId: string \| null }` | 聊天页底部录音条 |
+
+本次插件注册形式如下，list 插槽必须传 `id`：
+
+```ts
+ctx.slots.inject('desktop.business.page', () =>
+  ctx.slots.register(
+    { name: 'desktop.business.page', id: 'dsh-xrxs-lingting' },
+    Page,
+  ),
+);
+```
+
+公司有自己的路由/插槽时，可以改写 `src/plugin/client.tsx`，将这三个位置映射到现有界面。最终效果应是“侧栏入口 → 主区域页面”，而不是把整个页面塞到窄侧栏。
+
+当前布局只验证了灵听这一个业务插件。公司同时接多个业务插件时，应按 `activeId` 分别控制每个页面容器的显隐，并测试状态保存；不能直接让所有 list 插槽组件同时显示。
+
+### 5.4 页面和录音生命周期
+
+本次布局保留聊天组件挂载，通过显隐切换页面；在灵听打开时暂时收起右侧详情的显示宽度。全局录音条占用主区域底部空间，避免覆盖聊天输入框。
+
+公司移植时应保持以下关系：
+
+```text
+DSH 插件运行实例
+  ├─ 一份 LingtingService：拥有当前录音、计时和转写状态
+  ├─ 灵听主页面：订阅同一份服务
+  └─ 全局录音条：订阅同一份服务
+
+切换到聊天 → 保留服务 → 继续计时/转写
+结束录音 → 等待保存 → 清除当前录音 → 保留历史
+退出/卸载 → 停止服务 → 重启后将未结束记录标记为中断
+```
+
+不要在路由每次进入时重新创建录音服务，也不要让主页面和底部控制条各自创建服务。公司如果采用卸载页面的路由方式，服务仍须放到路由之外，列表筛选等页面状态也需按需求保存。
+
+### 5.5 插件清单与构建协议
+
+插件包的核心声明为：
+
+```json
+{
+  "name": "dsh-xrxs-lingting",
+  "main": "./plugin-dist/index.js",
+  "exports": {
+    ".": "./plugin-dist/index.js",
+    "./client": "./plugin-dist/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  }
+}
+```
+
+`cordis.patch.yml`：
+
+```yaml
+- insert:
+    - id: dsh-xrxs-lingting
+      name: dsh-xrxs-lingting
+```
+
+浏览器入口按 Harness `window.__ModuleLoader__.load({ id, factory })` 协议输出。当前包不携带运行时 npm 依赖，React 由宿主模块系统提供，其他页面代码已打入插件。
+
+公司如果修改过模块系统、React 主版本、插件包名或布局模块名称，需要同时检查清单、构建脚本、入口中的 `ID` 和注册条目。不能只改 npm 包名。
+
+### 5.6 本地 Host 接口
+
+保持 Mock 阶段时，公司宿主还需支持：
+
+| 项目 | 当前要求 |
+|---|---|
+| Host 依赖 | `ctx.connection.fetch.register()` |
+| 数据根目录 | 环境变量 `DSH_HOME` 指向可写且与测试/正式环境隔离的目录 |
+| 读取 | `GET /api/lingting.demo-state`，返回记录数组；文件不存在时返回 `null` |
+| 保存 | `PUT /api/lingting.demo-state`，JSON 记录数组；成功返回 `{ "saved": true }` |
+| 访问方式 | 相对路径、同源 fetch，通过 Harness 的认证访问 |
+| 文件 | `DSH_HOME/lingting-demo/records.json` |
+
+这是最小演示存储协议，不作为生产业务 API。公司若已有桌面本地存储服务，可以替换 `host.mjs` 与 `persistence.ts`，保持页面的服务接口不变。
+
+当前前端约一秒合并保存一次，Host 串行写入并通过临时文件替换。正常结束会等待保存完成；强制终止可能丢失最后尚未落盘的内容。当前不支持多个窗口或设备并发编辑同一份录音状态。
+
+## 6. 公司团队按这个顺序实施
+
+### 第一步：取得并核对代码
+
+取得灵听提交 `60ca730` 和 Desktop 提交 `3879672`，分别建立公司开发分支。若无法直接共享 Git 分支，可由本机导出：
+
+```bash
+git -C /Users/quwei/work/xrxs/code/dsh-xrxs-lingting format-patch -1 60ca730 --stdout > /tmp/lingting-plugin.patch
+git -C /Users/quwei/work/xrxs/code/dsh-desktop format-patch -1 3879672 --stdout > /tmp/lingting-desktop.patch
+```
+
+上述补丁基于各自父提交。公司仓库基线不同，应人工移植相关逻辑并处理冲突，不能默认直接 `git am` 成功。同步完整公司分支是更便于后续维护的交接方式。
+
+### 第二步：先实现宿主接入能力
+
+由 Desktop 开发按第 5 节接通导航、页面区、状态区、侧栏和本地存储。
+
+同版本且结构一致时可沿用 `patch-package`；公司直接维护 Harness 源码时，建议把能力写入对应布局/导航源文件并重新构建，避免长期直接维护编译产物补丁。
+
+### 第三步：构建和注册插件
+
+由插件开发执行第 4.1 节构建，Desktop 开发将 `.tgz` 纳入公司应用构建。
+
+在兼容 Harness 的 profile 中，启用后的配置应包含以下片段（示例只展示灵听，保留公司原有项）：
+
+```json
+{
+  "dsh": {
+    "profile": {
+      "bundles": ["dsh-xrxs-lingting"]
+    }
+  }
+}
+```
+
+同时确保 profile 的插件解析路径能找到对应包。公司若使用受管插件版本目录，应通过其安装器完成安装、注册和版本切换；不要手改投影目录或套用本机固定 macOS 路径的安装脚本。
+
+选择 profile bundle 或公司统一启动配置作为唯一注册来源，避免重复插入相同插件 ID。
+
+### 第四步：验证 Mock 集成
+
+先运行自动化测试，再执行第 8 节桌面验收。Mock 流程通过后形成一个可演示版本，供产品确认入口、交互及状态表现。
+
+### 第五步：接入真实业务服务
+
+按第 7 节替换服务实现，完成账号、权限、采集与转写联调，再进入公司发布流程。
+
+### 第六步：通过公司流水线打包
+
+在目标平台构建，使用公司的应用名称、应用 ID、数据目录、签名及更新服务。构建流水线应固定依赖和插件版本，执行测试，并在产物内检查插件入口、宿主接口和启动注册是否齐全。
+
+本机 Dev `.app` 依赖已安装的本机 Dev profile。若分发给其他员工，必须设计首次安装/启用插件的流程；仅复制这个 `.app` 到一台全新机器，不能假定会自动出现灵听入口。
+
+## 7. 后续接真实前后端，需要改哪里
+
+页面已经依赖 `LingtingService`，接口定义在 `src/domain/types.ts`。建议新增公司真实实现，例如 `CompanyLingtingService`，然后在插件入口替换 `MockLingtingService`。
+
+| 接口 | 真实实现负责的工作 |
+|---|---|
+| `list(query)` | 从业务后端查询列表、搜索、状态筛选、分页 |
+| `detail(id)` | 查询记录详情与转写 |
+| `start()` | 校验身份与权限，创建录音任务，启动采集/上传 |
+| `pause()` / `resume()` | 协调录音设备和后端任务状态 |
+| `finish()` | 停止采集、提交剩余数据、确认后端保存状态 |
+| `subscribe()` / `getSnapshot()` | 将服务端与设备状态同步给页面及全局录音条 |
+| `dispose()` | 释放麦克风、音频流、连接与监听器 |
+
+还需明确的业务约定：
+
+1. 使用公司统一登录态，不在前端写死密钥或员工身份。
+2. 确定录音来源：麦克风、系统声音或其他输入；当前没有实现真实设备采集。
+3. 确定转写协议和任务 ID，增量文本按片段 ID 更新，避免重复追加。
+4. 明确断线、暂停、结束失败的状态语义，以及重连和幂等规则。
+5. 明确记录归属、访问权限、保存位置和保留周期。
+6. 正式模式移除 Mock 场景入口及模拟文案。
+7. 多窗口需求下，把录音控制权放到一个明确的共享进程/服务，避免重复采集。
+
+真实服务接入还需调整 `client.tsx` 中“结束后写入 Mock 文件”的包装逻辑，以及 `persistence.ts` / `host.mjs` 的演示存储，不能只把某一个 URL 改成公司域名。
+
+## 8. 验收清单与当前验证边界
+
+### 8.1 公司版交付前逐项验收
+
+| 场景 | 预期结果 |
+|---|---|
+| 首次安装到全新测试 profile | 启动成功，出现一个灵听入口 |
+| 点击灵听 | 主区域打开，侧栏/设置仍可使用 |
+| 新建或打开聊天会话 | 返回聊天，原有聊天功能正常 |
+| 搜索、筛选、分页、历史详情 | 数据与页面状态正确 |
+| 开始录音后反复切换页面 | 只有一场当前录音，时长和转写持续更新 |
+| 聊天页暂停/继续 | 控制同一场录音，暂停时停止增长 |
+| 结束并确认 | 控制条消失，记录可回看 |
+| 保存失败、断线、结束失败 | 有明确提示，可恢复或重试，不误报成功 |
+| 退出并重启 | 历史保留，未结束的 Mock 记录为已中断 |
+| 停用并重启 | 入口消失，聊天可用；重新启用后历史保留 |
+| 侧栏收起、窄窗口、公司主题 | 布局可用，样式不污染其他页面 |
+| 插件更新/回滚 | 版本正确，既有数据与其他插件保留 |
+| 各目标系统的正式安装包 | 首次安装、重启、更新与权限流程通过 |
+
+### 8.2 本次已完成的验证
+
+- 灵听 17 项自动化测试通过，包括 Mock 录音状态、本地保存队列、失败重试及 Host 文件持久化。
+- Desktop 90 个测试文件、752 项测试通过，类型检查与构建通过。
+- 三个宿主补丁重新应用到原始 vendored 包后，与实际测试安装内容一致。
+- 实际 Electron 窗口验证主区域打开、聊天切换、底部暂停/继续/结束、历史详情。
+- 最终打包的 Dev `.app` 已启动，看到重启保留的已结束记录与已中断记录。
+
+未在本轮验证：公司 DSH、真实语音和业务后端、真实模型请求、多窗口并发、其他操作系统，以及面向员工分发的正式安装/升级链路。自动化测试数量不等于上述场景全部通过。
+
+## 9. 停用、回滚和故障排查
+
+### 9.1 停用与重新启用
+
+先结束当前录音，退出 Dev，备份 profile 配置。在 Dev profile 的 `cordis.patch.yml` 合并：
+
+```yaml
+- id: dsh-xrxs-lingting
+  disabled: true
+```
+
+重启后停用。恢复时移除此覆盖或改为 `false`，再重启。不要覆盖该文件中的其他配置，也不要为停用插件删除整个 profile。
+
+当前 Harness 在线停用时可能先移除 Host 接口，而打开的前端仍存在，并出现本地保存失败。本次操作规程因此要求先结束录音、退出、停用并重启。
+
+### 9.2 回滚
+
+1. 先结束录音并退出应用，备份 profile 和灵听记录文件。
+2. 通过公司插件版本管理切回上一版兼容插件；宿主接口有变化时一并回滚对应宿主版本。
+3. 本次新增 Host 接口没有修改原聊天数据；停用灵听不需要恢复整个 DSH 数据目录。
+4. 后续若修改记录结构，需要配套数据版本与迁移方案，再决定是否能直接回滚。
+
+### 9.3 常见问题
+
+| 现象 | 检查与处理 |
+|---|---|
+| 主程序没有灵听入口 | 确认运行的是 Dev；确认插件包可解析、bundle 已注册、未被 disabled 覆盖；查看 Host/前端插件错误 |
+| 提示“需要包含业务页面接入能力” | 检查 `ctx.layout.business` 是否存在、布局补丁是否生效；仅安装 `.tgz` 不够 |
+| `list slot ... requires options.id` | list 插槽注册使用 `id`，不要使用 `key` 代替 |
+| React Hook 错误或插件版本迁移失败 | 检查重复 React、错误 peer 解析及宿主 React 版本；沿用当前外置 React 的插件构建方式 |
+| 本地记录无法读取/保存 | 检查 Host 路由、同源认证、`DSH_HOME`、写权限及是否刚在线停用了 Host；先保留现场和日志 |
+| 切回聊天后录音停止 | 检查服务是否在路由卸载时被销毁，是否误创建多个实例 |
+| 新版插件仍显示旧页面 | 检查版本号、包缓存和受管插件目录；通过宿主安装器更新并重启 |
+| 已安装 npm 包但没有启用 | 检查 profile 的 bundle/启动条目，安装与启用是两个步骤 |
+| `patch-package` 失败 | 对照 Harness 精确版本和已有公司补丁，移植到新基线后重新生成；不要忽略失败继续发布 |
+| 新员工机器打开 `.app` 无入口 | 检查首次启用流程；本机 profile 不会自动跟随 `.app` 分发 |
+
+## 10. 交接给公司团队的材料
+
+- 本操作手册。
+- 灵听集成源码分支、版本号和 `.tgz`。
+- Desktop 宿主改动或公司等价实现，包括补丁、依赖锁文件、测试及安装脚本。
+- 已验证版本矩阵和第 8 节验收记录。
+- 公司自己的测试 profile、数据目录、首次安装、更新及回滚方案。
+
+推荐实施顺序：**先让公司 DSH 提供主区域接入能力，再装 Mock 插件验收交互，最后接真实服务并走公司发布流程。**