@spzxg/cli-ui 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @spzxg/cli-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+任务中心（cli-task-center）对话任务（`mode=conversation`）的前端组件，界面与执行节点（Operator）的对话界面一致。数据全部来自中枢。
+
+| 组件 | 作用 |
+| --- | --- |
+| `<CliChat>` / `<cli-chat>` | 对话：实时显示执行过程，发消息、排队、停止、回答提问、结束对话 |
+| `<CliMsgList>` / `<cli-msglist>` | 对话列表，按「需要你处理 / 进行中 / 已结束」分组 |
+| cli-board | 右侧看板（文件、预览、下载）：规划中，见 [PLAN.md](PLAN.md) |
+
+两个组件**相互独立**：传入参数就能单独运行，之后由组件接管。完整说明见中枢 API 文档的「前端组件」页签（`/api-docs#fe-start`）。
+
+## 快速开始
+
+```tsx
+import { CliChat, CliMsgList } from "@spzxg/cli-ui";
+import "@spzxg/cli-ui/styles.css";
+
+<CliChat jobId="job_xxx" />                                               // 打开已有对话
+<CliChat jobId={null} newConversation={{ title: "周报", businessId: "biz-1" }} />  // 新对话
+<CliMsgList jobIds={["job_xxx"]} onSelect={setJobId} />                   // 列表
+```
+
+组件请求同源的 `/api/center`（可以用 `baseUrl` 改），由代理转到中枢并注入令牌：
+
+```nginx
+location /api/center/ {
+  proxy_pass https://cli.xgjktech.com.cn/;
+  proxy_set_header Authorization "Bearer <产品线令牌>";
+  proxy_buffering off;
+  proxy_read_timeout 1h;
+}
+```
+
+### 第三方页面（无需 React、无需构建）
+
+`npm run build:embed` 生成的 `dist/` 放到静态目录：
+
+```html
+<link rel="stylesheet" href="/static/cli-ui/cli-ui.css">
+<script type="module" src="/static/cli-ui/cli-ui.js"></script>
+<cli-chat base-url="/api/center" job-id="job_xxx"></cli-chat>
+<!-- 或者 JS 挂载：CliUI.mountChat(el, { jobId, newConversation, onCallback }) → { update, unmount } -->
+```
+
+示例见 `demo/embed.html`：先 `npm run build:embed`，再 `npm run demo`，然后打开 http://127.0.0.1:12791/embed.html。
+
+## 数据怎么流转
+
+- **组件 ⇄ 中枢**：显示对话、发消息。页面打开时才连接。
+- **中枢 → 业务后端 `callback.url`**：每轮一次 `conversation_turn`，结束时一次 `conversation_closed`。**落库以它为准。**
+- **组件 → 页面 `onCallback`**：内容与中枢回调体字段相同，只用来即时刷新页面。
+
+推荐由业务后端建对话（`POST /api/jobs`，带 `mode: "conversation"`、`business_id`、`callback`），把 `job_id` 存进业务库，前端只传 `jobId`。
+
+## 和列表一起用
+
+```tsx
+// a. 页面自己串：两个组件互不依赖
+<CliMsgList selectedId={jobId} onSelect={setJobId} onNew={() => setJobId(null)} />
+<CliChat jobId={jobId} onEvent={(e) => e.type === "job_change" && setJobId(e.jobId)} />
+
+// b. 放进同一个 Provider：自动联动
+<CliCenterProvider><CliMsgList /><CliChat /></CliCenterProvider>
+```
+
+## 界面配置
+
+```tsx
+<CliChat config={{
+  header: { export: false, close: false },        // header: false 隐藏整个顶部栏
+  composer: { placeholder: "给 {agent} 发消息…" },  // composer: false 只读
+  transcript: { tools: false },
+}} />
+```
+
+所有配置项和缺省值都在 [`src/core/config.ts`](src/core/config.ts) 里，每一项都有注释。Web Component 上用 `config='{"header":{"export":false}}'`。
+
+## 事件
+
+- `onCallback(payload)`：`payload.type` 为 `conversation_turn` / `conversation_closed`，字段与中枢回调体相同。
+- `onEvent(event)`：另外还有 `job_change`（新建了对话，或接续出了新 job_id，要存起来）、`select`、`error`。
+- Web Component 上监听 `cli-callback` / `cli-event` 事件。
+
+## 顺序与容错
+
+- 同一对话的消息按发出顺序送到 center（一条一条发）；新建对话只发一次（center 建对话不去重）。
+- 回调带 `callback_seq`，`conversation_closed` 总在最后一个 `conversation_turn` 之后，与 center 回调一致。
+- 发送失败时内容留在输入框；撤回、停止、回答、结束失败时在顶部提示；排队卡住时气泡下写明原因。
+- 实时流 45 秒没数据就重连，网络恢复或切回页面时立即重连；404 / 401 停止重连，并给出提示。
+
+## 开发
+
+```bash
+npm run demo -w @spzxg/cli-ui      # 假中枢 + 演示页 http://localhost:12790（?mode=chat / ?mode=wired / elements.html）
+npm test -w @spzxg/cli-ui
+npm run lint -w @spzxg/cli-ui
+npm run css:sync -w @spzxg/cli-ui  # Operator 改了样式后重新同步
+npm run build:embed -w @spzxg/cli-ui # 第三方一体化产物 dist/cli-ui.js + cli-ui.css
+```
+
+演示用的是 `demo/mock-center.mjs` 里的内存数据，不要把演示页指向生产中枢。