@spzxg/cli-ui 0.6.2 → 0.6.5

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.6.5 — 2026-11-05
+
+- 文件预览按后端、任务和路径隔离，切换不沿用旧正文、选区或短期链接。
+- 文件下载及图片、PDF、HTML、Word 的内存读取校验实际字节数，及时响应取消；ZIP 取消／失败后停止剩余读取，不保存迟到结果。
+- ZIP 失败报告避让用户同名文件；`FolderResult.failedListName` 可选返回真实报告路径。
+- 原生文件事件新增可选 `FileEntry.changeToken`，用于断线恢复时发现同大小、同 mtime 的改写；不是内容版本锁。
+- 看板状态和自动背景原子更新后通知业务；回调内导航保持顺序，新增业务监听可恢复已停止的连接，清理期间重新订阅不进入失效记录。
+- 来源任务文件的选中文字引用明确包含工作区身份，关闭自动背景也保留来源。
+- 浏览器复制引用保留复制时页面来源；远端弹窗错误可重试，输入坐标使用实际显示帧，取消拖动或切换控制权清除旧按压。
+- 首帧未就绪不发送鼠标输入；节点浏览器状态流显示认证、接口和临时断线错误，保留共享连接的降级恢复；自定义 browserEvents 可选提供 onError 通知。
+
+
+## 0.6.4 — 2026-11-05
+
+- 统一 `CliMsgList`、`CliChat`、`CliBoard` 与完整 Operator 工作区；React、Web Component、embed 使用同一源码，宿主保留协议适配和服务端能力。
+- 文件／浏览器／改动模块可独立关闭和重新打开，改动默认关闭；聊天文件链接可唤起看板，来源任务身份随引用与文件页签保留。
+- 聊天默认附带当前文件、打开页签、最近访问与看板显示状态的元信息背景；支持取消本次附带，手动引用与任务派生保持独立。
+- 新增工作区 `watch/stat/context` 及文件／监听／浏览状态业务回调；原生节点提供文件事件，旧中枢明确降级为可见文件轮询。相同尺寸和 mtime 的原生改写仍触发预览重读。
+- 修复多看板抢占当前文件、迟到恢复覆盖正在使用的看板及历史丢失；重新点击已选文件可重新激活上下文。
+- 修复浏览器重连、接管交还和任务切换时旧输入／动作污染新画面；网页确认弹窗等待远端确认后关闭。
+- 文件监听区分永久错误、认证／限流和暂时断线；保留 WebSocket → SSE 降级，资源恰好释放一次，限制客户端跟踪元数据并准确报告不完整覆盖。
+- 自定义后端文件读取增加最终大小校验和及时取消；业务订阅的文件、看板元信息彼此隔离。
+
+文件预览仍为只读，文件改写由 AI／服务端执行。文件事件是当前状态通知，非持久审计日志或不可变内容版本。旧中枢轮询与扫描上限见 README。此版本为本地构建包；npm 发布需 registry 登录。

package/README.md

@@ -1,6 +1,6 @@
 # @spzxg/cli-ui
 
-任务中心（cli-task-center）对话任务（`mode=conversation`）的前端组件，界面与执行节点（Operator）的对话界面一致。数据全部来自中枢。
+相互联动的三个组件，支持中枢对话和完整 Operator 节点工作区。缺省参数使用中枢协议；`operator` 参数承接节点的完整任务与 Git 工作流。两种后端的能力不同，不显示后端不支持的执行控制。
 
 | 组件 | 作用 |
 | --- | --- |
@@ -91,12 +91,14 @@ location /api/center/ {
 
 - Provider 里的组件不要再传 `jobId` / `taskId`（列表不传 `selectedId`）：传了的组件只看自己那个，不跟着切。
 - Web Component：同一个 `group`，不写 `job-id`；从外面打开某个对话给任意一个元素写 `selected-id="job_x"`，改它就一起切。
-- 不用 Provider 也行：页面自己串，每个组件传 `jobId` / `selectedId`，在 `onSelect`、`job_change` 里同步：
+- 不用 Provider 时，完整联动仍需传同一个稳定的 `store`；仅同步 `jobId` / `selectedId` 不会共享文件打开和引用事件。页面可在 `onSelect`、`job_change` 中同步受控选择：
 
 ```tsx
-<CliMsgList selectedId={key} onSelect={setKey} onNew={() => setKey(null)} />
-<CliChat jobId={key} onEvent={(e) => e.type === "job_change" && setKey(e.key)} />
-<CliBoard jobId={key} />
+// React 组件内；账号变化时重建 store，并取消旧账号的业务订阅。
+const store = useMemo(() => createCliStore({ baseUrl: "/api/center", namespace: accountId }), [accountId]);
+<CliMsgList store={store} jobIds={ids} selectedId={key} onSelect={setKey} onNew={() => setKey(null)} />
+<CliChat store={store} jobId={key} onEvent={(e) => e.type === "job_change" && setKey(e.key)} />
+<CliBoard store={store} jobId={key} />
 ```
 
 ## 右侧看板
@@ -126,7 +128,7 @@ location /api/center/ {
 </CliCenterProvider>
 ```
 
-- 页签：文件（目录、预览、下载）、改动（diff，只读）、浏览器（实时画面，接管后可直接操作）。`tabs={["files","changes"]}` 选页签。
+- 页签：默认文件（目录、预览、下载）和受支持的浏览器；改动（diff，只读）默认关闭，可手动添加。`tabs={["files","changes"]}` 只设置初始打开的模块和顺序；用户仍可从「管理看板模块」打开浏览器。`availableTabs` 才限制允许使用的模块。所有模块都能单独关闭、重新打开，`tabs={[]}` 表示初始全部关闭。
 - 预览：Markdown、代码、文本、CSV、图片、PDF、HTML（沙箱 iframe）、Word（.docx，mammoth 转 HTML 放进无脚本沙箱）。其他类型下载。
 - 自动同步：实时流有进展就刷新（节流 1.5 秒），运行中每 15 秒（`pollMs`）兜底再刷一次；改过的文件标「有更新」，打开着的文件改了自动重读。
 - 没有看板时，对话自己弹窗预览（`<CliChat fileOpen="auto|board|modal|link">`）。宿主也可以 `store.openInBoard(jobId, { kind: "file", path })`。
@@ -136,7 +138,7 @@ location /api/center/ {
 - 引用到对话：文件预览、浏览器的「引用到对话」把它带进下一条消息（`store.addRef`），对话输入框上方显示、可去掉；发出时合成「看板上下文」附件。自定义页签（`extraTabs`）的 `quote` 同理——终端之类的交互以后都走这条路进对话。
 - 多个文件页签：点开的文件各占一个页签（最多 8 个，再开关掉最早的），可关闭（× 或鼠标中键），按对话记在 sessionStorage，刷新后还在。
 - 选中引用：在预览里选中文字浮出「引用到对话」（Markdown / 代码 / 文本 / 表格 / HTML / Word 及其源文件；HTML、Word 在沙箱 iframe 里，预览用 srcdoc 插一段选区小脚本报给宿主，页面自己的脚本仍不执行）；在浏览器网页里复制（⌘C / Ctrl+C）后提示里也有「引用到对话」。
-- 正在看：打开着的文件 / 浏览器页面缺省随下一条消息带给智能体（换了再带；`autoQuoteOpenFile={false}` 关掉），单独一块「看板正在看」，缺省在输入框上方和对话里都不显示。cli-chat 的 `config.refs` 按种类控制显示：`{ viewing: true }` 显示「正在看」虚线卡片（× 这次不带），`{ selection: false }` 不显示选中引用，`true` / `false` 全部。状态在 `store.getState().viewing`。
+- 被动浏览背景：每条消息自动附带当前文件、仍打开的页签和最近40个实际访问文件的元信息；手机回聊天／收起看板后仍保留，并标记收起状态。输入框可查看摘要、取消本次附带；成功发送后恢复默认。不会自动读取文件正文，也不替换手动引用。`CliChat passiveContext={false}`／`CliBoard autoQuoteOpenFile={false}` 关闭；节点 `board={{autoContext:false}}`。`workspace.context()` 读取完整浏览快照，`config.refs` 继续控制旧式引用的显示。
 - 浏览器弱网：操作没送达时提示（不自动重发，免得点两次）；接管时发了操作 8 秒画面没变化提示并给「重连画面」；按住鼠标切走窗口自动补发松开；地址栏自动补 `https://`。
 - 数据都经中枢：`/api/jobs/:id/board`、`/files`、`/files/raw/<路径>`、`/diff`、`/browser`（+ `events` / `frames` / `input`）。
 - 链路、交互、故障与重试的设计见 [BOARD-DESIGN.md](BOARD-DESIGN.md)。
@@ -236,11 +238,11 @@ Agent 回复里指向本地文件的链接（`report.md`、`src/a.ts:12`、`file
 
 | 工程 | 放什么 | 和组件的关系 |
 | --- | --- | --- |
-| `operator-oss` | 执行节点（Operator）+ **组件源码** `packages/cli-ui` | 改组件都在这里改；组件的样式从同仓库的 `app/globals.css` 同步（`css:sync`） |
+| `operator-oss` | 执行节点（Operator）+ **组件源码** `packages/cli-ui` | 改组件都在这里改；界面、交互和共享样式均在组件包维护；当前工程通过本地包依赖使用组件 |
 | `clawbizx` | 业务协同工程，统一发布 `@spzxg/*` 包 | `packages/cli-ui` 是指向 `../../operator-oss/packages/cli-ui` 的链接，`scripts/publish-shared-packages.sh` 从这里发布到 npm |
 | `cli-task-center` | 中枢（组件的数据都来自它） | 组件的使用文档在中枢 API 文档的「前端组件」页签（`backend/public/api.html`） |
 
-两个仓库要并排放在同一个目录下（`~/operator-oss`、`~/clawbizx`），链接才有效。组件有自己的依赖，不和 Operator 共用：
+两个仓库要并排放在同一个目录下（`~/operator-oss`、`~/clawbizx`），链接才有效。组件可独立安装；Operator 使用本地 `file:packages/cli-ui` 依赖，React 使用宿主的 peer dependency：
 
 ```bash
 cd operator-oss/packages/cli-ui
@@ -248,7 +250,7 @@ npm install                          # 第一次
 npm test                             # 测试
 npm run lint                         # 类型检查
 npm run demo                         # 假中枢 + 演示页 http://localhost:12790（?mode=chat / ?mode=wired / elements.html；看板用 e2e-local.sh 的 ?mode=board，单独集成看 blocks.html?job=…，先 build:embed）
-npm run css:sync                     # Operator 改了样式后重新同步
+npm run css:sync                     # 从 src/operator.base.css 生成作用域样式
 npm run build:embed                  # 第三方一体化产物 dist/cli-ui.js + cli-ui.css
 bash demo/e2e-local.sh               # 连真实 center 联调：本地 center + 假节点 + 一次性本地库，演示页代理过去
 bash demo/e2e-local.sh stop
@@ -259,4 +261,128 @@ bash demo/e2e-real.sh stop
 cd clawbizx && bash scripts/publish-shared-packages.sh
 ```
 
-演示用的是 `demo/mock-center.mjs` 里的内存数据，不要把演示页指向生产中枢。Operator 的 `tsconfig.json`、`.dockerignore` 排除了 `packages/`，组件不进 Operator 的构建和镜像。
+演示使用 `demo/mock-center.mjs` 的内存数据。Operator 的 Next 构建和 Docker 镜像现已包含组件包；不要恢复旧的 packages 全目录排除规则。
+
+
+## 完整 Operator 工程与唯一维护位置
+
+```tsx
+"use client";
+import { OperatorWorkspace } from "@spzxg/cli-ui/operator";
+import "@spzxg/cli-ui/operator.css";
+import "@spzxg/cli-ui/styles.css";
+export default function App() { return <OperatorWorkspace />; }
+```
+
+`OperatorWorkspace` 使用 `CliMsgList`、`CliChat`、`CliBoard` 的 `operator` 参数组合，三者由同一个 `useOrchestrator` 控制项目、选中任务、运行状态、配置、分支和事件连接。宿主只保留路由、服务端和以上入口。节点的完整客户端实现位于 `src/operator/node`；根工程原有 `app/orchestrator/*`、Markdown、图标、终端和 Git 面板路径均为兼容导出，不再维护另一份界面。
+
+直接使用 `operator` 参数时，宿主负责传入同一个项目／任务控制器及回调，并把三个组件放入 `.cli-ui` 容器，加载上述样式。完整工作区需要 Operator 的 `/api/*`、`/live` 和 PTY 服务；它不是脱离节点服务器的离线演示。
+
+| 能力 | 中枢默认模式 | Operator 模式 |
+| --- | --- | --- |
+| 列表、对话、文件／浏览器看板联动 | 同一 `CliCenterProvider`／store | 同一工作区控制器和多路复用实时连接 |
+| 附件、长文本、引用 | 文档转文字与看板／消息引用 | 图片／文本上传、消息引用、草稿与来源恢复 |
+| 模型、推理、权限／规划 | 不伪造中枢没有提供的配置接口 | 能力列表驱动，等待真实 PATCH 成功再允许发送 |
+| `@` 多来源分支 | 中枢协议目前未提供独立 Git 派生接口 | 同项目已完成任务，每个来源一个独立 worktree／分支，固定源提交 |
+| 源对话结尾 → 分支选择 → 子对话 | 不虚构分支数据 | 支持横向切换和递归派生，来源历史只读 |
+| Git 同步、合并、PR、冲突修复 | 只读改动看板 | 保留原完整工作流 |
+| 看板／列表、依赖、自动启动、建议、回顾、设置、认证、用量、终端和服务 | 由宿主业务提供 | 保留在完整工作区中 |
+
+`src/operator.base.css` 是共享样式源，`src/operator.css` 是 `css:sync` 的生成结果；根工程 `app/globals.css` 只导入包的样式。迁移与备份清单见仓库的 `docs/CLI_UI_MERGE.md`。
+
+当前 npm 的 `0.6.2` 已发布，不能覆盖重发。本地此次版本为 `0.6.5`，需要通过组件测试、嵌入构建、真实工程构建和浏览器回归，再发布新的补丁版本；不要运行会连带发布其他共享包的批量脚本。
+
+
+### 文件、对话与浏览器看板联动
+
+```tsx
+// 只设置初始可见状态；用户仍能手动打开文件、改动等模块。
+<OperatorWorkspace board={{ tabs: ["browser"], defaultTab: "browser" }} />
+// 中枢组件用相同规则；三个组件放在同一个 Provider 中。
+<CliBoard tabs={["browser"]} defaultTab="browser" />
+// 只有明确限制能力时才设置 availableTabs。
+<CliBoard tabs={["browser"]} availableTabs={["browser", "files"]} />
+```
+
+Web Component 对应 `tabs="browser"`、`available-tabs="browser,files"`；`tabs=""` 表示初始全部关闭。默认配置与用户手动开关分开，模块偏好按任务／配置保存在会话存储中。
+
+对话里的本地文件链接及文件形态的行内代码会打开右侧文件预览；看板收起或在手机上时自动展开／切换。Ctrl／⌘ 点击仍可独立打开。来源历史文件使用来源任务的文件接口，不切换当前任务或分支。文件、选区、网页和网页复制文字可引用回同一个草稿，保留原有输入；手机引用后返回对话。
+
+浏览器关闭页签只隐藏模块和断开画面连接，不结束浏览器任务；重新打开后连接当前状态。「关闭浏览器」才调用实际关闭接口。新浏览器交接能唤起隐藏的模块；旧历史交接、已经消费的打开请求和其他任务的事件不会反复唤起。浏览器模块与独立窗口共用画面／输入实现，保留触摸、键盘／输入法、网页弹窗、剪贴板、重连、接管交还，并保留节点登录配置、弹出窗口和在节点屏幕显示操作。
+
+### v0.6.3 历史验收（当前版本见 CHANGELOG）
+
+组件 308 项测试、lint、嵌入构建，以及宿主生产构建已通过；宿主 873 项测试、24 项常规真实页面回归和 1 项真实 ego lite 看板完整流程通过。宿主默认跳过的 17 项底层浏览器／playbook 环境测试，本轮未重跑；此前单独执行的记录保留在验收包中。未使用付费模型账号测试，不把模拟驱动配置测试等同于所有真实 CLI 环境验证。
+
+该版本已在本地准备，当前执行账户未登录 npm，尚未发布。旧 UI 已归档，47 个兼容入口由宿主 `npm run check:components` 检查；今后 UI 改动只在组件包中维护。
+
+
+### 维护前提：组件为唯一标准
+
+开发、修复和发布均以三个公开组件为单位。React／Web Component／embed 统一调用 `src/components.tsx`；文件预览和浏览器独立窗口同样在本包维护。旧界面只留备份和转发，不再改旧工程实现。
+
+宿主普通 `dev`、`build`、`test` 会先执行来源审计：错误转发、新增包外 UI／样式、组件反向引用宿主／备份、分发入口绕过组件都会失败。审计自身有 7 项回退回归；本包的具体维护规则见仓库内 `packages/cli-ui/AGENTS.md`。
+
+
+### 高可用接入与恢复
+
+配置保存锁、上传中断恢复和结束确认均绑定任务／会话身份，切走再回来不会提前发送或误操作其他会话。看板正常断流自动重连，主动关闭停连；卸载最后实时消费者会释放连接，卸载文件模块取消 ZIP 下载。宿主事件回调异常记录在控制台，不能阻断组件终态更新或其他通知。
+
+Web Component 组内唯一配置源的 URL、token、line、namespace 和新会话配置会完整继承，包括晚挂载或配置旋转；明确不同凭据各用独立 store。继承配置出现歧义时显示错误，调用方需要补齐连接属性，不能依赖“第一个组件”的身份。
+
+标准连接按身份指纹隔离草稿、文件页签及当前 UI，不把原始 token 写入存储键。同配置刷新可恢复，换凭据后旧内容不会自动附到新身份。Cookie 鉴权宿主应提供按账号区分的 namespace，并在账号切换后重建 Provider／client。自定义 client 对象应保持稳定；不同对象保守隔离，不能只凭 URL 推断其隐藏的认证身份。历史没有身份标签的草稿保留在原分区，不自动搬入新增的认证分区。
+
+完整问题与验证边界见仓库 `docs/CLI_UI_RELIABILITY.md`。本轮未进行生产长期浸泡、持续并发容量或付费模型账号验收；部署可用率需结合实际环境监测。
+
+
+### 文件通知 → 云端读取 → 业务交付
+
+```tsx
+<CliCenterProvider store={store}
+  onFilesChange={event => handleChanges(store.workspace(event.jobId), event)}
+  onFilesWatch={status => showWatchStatus(status)}>
+  <CliMsgList /><CliChat /><CliBoard />
+</CliCenterProvider>
+```
+
+也可只在 `CliBoard` 上监听 `onFilesChange`；或无 UI 地订阅：
+
+```ts
+const ws = store.workspace("job_x#task_y");
+const stop = ws.watch(async event => {
+  for (const change of event.changes) {
+    if (change.kind === "deleted") { removeBusinessFile(change.path); continue; }
+    const info = await ws.stat(change.path);
+    const blob = await ws.readFile(change.path); // 也可 readText()
+    receiveBusinessFile(info, blob);
+  }
+}, { onStatus: status => showWatchStatus(status) });
+// 业务生命周期结束时 stop()。
+const view = ws.context(); // current / opened / history / visible / sourceId
+```
+
+上述业务函数由集成方实现，组件不会自动上传到外部服务。通知是当前状态变化，读取可能遇到后续改写／删除，应处理错误与密集通知；不能将 revision 当成不可变内容版本锁。
+
+节点使用 `createOperatorWorkspace(taskId)`（从 `@spzxg/cli-ui/operator` 导入），或 `<OperatorWorkspace board={{onFilesChange, onFilesWatch}} />`。接口包含 watch/stat/readText/readFile/context/open。`onBoardContextChange` 提供浏览状态；它与文件内容变化分开。
+
+Web Component 发出 `cli-files-change`、`cli-files-watch`、`cli-board-context`，detail 与 React 事件一致；也可 `el.workspace(id).watch(...)`。通用 `cli-event` 会包含同类事件，不要重复处理两个入口。`watch-files="false"` 关闭自动订阅，`passive-context="false"` 关闭聊天自动背景。
+
+事件含 `jobId`、`changes[{kind,path,file?,previous?}]`、`revision?`、`mode`、`coverage`、`complete`；创建/修改/删除分别为 created/modified/deleted，初始快照不冒充全部新建。多个组件与业务监听共享连接，最后取消时释放；关闭模块不会关闭会话持有的订阅。
+
+节点支持实际工作区文件事件（含隐藏业务文件，排除Git/Operator内部状态与symlink），经 `/live` 复用。旧中枢尚无文件事件代理，明确降级为约15秒目录快照比对：`mode=poll, coverage=listed-files, complete=false`，不保证隐藏项／瞬时变化／同metadata改写；完整推送需后端实现可选 `BoardBackend.watchFiles`。原生清单默认上限100000项，不完整／异常会明确报告resync；精准路径事件不受初始清单截断遮蔽。完整协议与业务接入见仓库 `docs/CLI_UI_BOARD_FLOW.md`。
+
+### v0.6.4 接入加固
+
+多个看板按最近实际操作选择当前文件，历史／远程 metadata 同步不抢占活动看板。文件和浏览状态的业务事件使用独立副本；监听可区分永久错误、认证／限流和暂时断线，保留 WebSocket → SSE 恢复。客户端文件元信息跟踪上限为 100000；超限明确 `complete=false`，完整且未超限快照才恢复。
+
+`workspace.readFile()` 对自定义后端也校验实际字节数并及时响应取消，后端仍应正确实现 AbortSignal 以释放内部资源。浏览器重连、接管交还和切换任务不等待或重放旧会话输入。当前看板为只读预览，文件编辑由 AI／服务端执行，再通过事件刷新和交付给业务方。
+
+本地版本 `0.6.5`，更新记录见随包 `CHANGELOG.md`。发布验收记录见仓库 `docs/CLI_UI_RELEASE_0.6.5.md`；本地打包不等于 npm 已发布。
+
+### v0.6.5 文件和业务交付加固
+
+文件预览按 backend／任务／路径隔离；下载和预览读取检查实际字节数，取消 ZIP 不保存迟到结果。部分失败时 `zip()`／`downloadFolder()` 的可选 `failedListName` 返回实际报告名，避让同名用户文件。
+
+原生文件通知的可选 `FileEntry.changeToken` 用于重连对账，可识别同大小并恢复 mtime 的改写；需同步部署支持该字段的节点服务端。它不是不可变内容版本或审计日志。
+
+看板与自动背景一起更新后通知业务，回调内继续导航保持顺序；显式选区引用携带来源任务身份。浏览器复制引用固定复制时页面，取消拖动、控制权切换、弹窗错误和异步帧解码均保持正确状态。