@spzxg/cli-ui 0.3.1 → 0.4.0

package/README.md

@@ -61,15 +61,28 @@ location /api/center/ {
 - **组件自己建**：`<CliChat jobId={null} newConversation={{ title, businessId }} />`，建好后通过 `job_change` 事件把 job_id 交给页面。
 - **业务后端建**（要带 callback 时）：后端调 `POST /api/jobs`，前端只传 `jobId`，这样 callback 的密钥留在服务端。
 
-## 和列表一起用
+## 组合使用（列表 + 对话 + 看板联动）
+
+放进同一个 `CliCenterProvider`（Web Component 写同一个 `group`），三个组件互相通信、切换时一起变：列表点哪个对话，对话和看板就切到哪个；对话里新建 / 接续出的新对话，列表跟着加上并选中、看板跟过去；对话里点文件在看板里打开。
 
 ```tsx
-// a. 页面自己串：两个组件互不依赖
-<CliMsgList selectedId={jobId} onSelect={setJobId} onNew={() => setJobId(null)} />
-<CliChat jobId={jobId} onEvent={(e) => e.type === "job_change" && setJobId(e.key)} />
+<CliCenterProvider baseUrl="/api/center"
+  selectedId={key}                                  // 打开 / 切换到哪个对话（"job_x" 或 "job_x#task_y"）；不传由列表点击决定
+  onEvent={(e) => { if (e.type === "select") setKey(e.jobId); if (e.type === "job_change") setKey(e.key); }}>
+  <CliMsgList jobIds={ids} />
+  <CliChat />
+  <CliBoard />
+</CliCenterProvider>
+```
 
-// b. 放进同一个 Provider：自动联动
-<CliCenterProvider><CliMsgList /><CliChat /></CliCenterProvider>
+- Provider 里的组件不要再传 `jobId` / `taskId`（列表不传 `selectedId`）：传了的组件只看自己那个，不跟着切。
+- Web Component：同一个 `group`，不写 `job-id`；从外面打开某个对话给任意一个元素写 `selected-id="job_x"`，改它就一起切。
+- 不用 Provider 也行：页面自己串，每个组件传 `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} />
 ```
 
 ## 右侧看板
@@ -111,13 +124,13 @@ location /api/center/ {
 
 ```tsx
 <CliChat config={{
-  header: { export: false, close: false },        // header: false 隐藏整个顶部栏
+  header: { title: true, status: true },          // 顶部栏缺省隐藏；header: true 全部显示
   composer: { placeholder: "给 {agent} 发消息…" },  // composer: false 只读
   transcript: { tools: false },
 }} />
 ```
 
-所有配置项和缺省值都在 [`src/core/config.ts`](src/core/config.ts) 里，每一项都有注释。Web Component 上用 `config='{"header":{"export":false}}'`。
+cli-chat 的顶部栏（面包屑、标题、智能体、用量、模型、状态、结束对话）缺省全部隐藏，需要哪项写哪项。各种状态（未开始、进行中、已完成……）缺省都不显示：要显示打开 chat 的 `header.status`、`transcript.status`，list 的 `card.status`（卡片状态）、`grouped`（按状态分组）。所有配置项和缺省值都在 [`src/core/config.ts`](src/core/config.ts) 里，每一项都有注释。Web Component 上用 `config='{"header":{"title":true}}'`。
 
 ## 事件
 
@@ -138,6 +151,8 @@ location /api/center/ {
 `<CliChat jobId taskId>` 两个参数，或者把对话键整个交给 `jobId` 都可以。cli-msglist 里开了几个对话的任务按对话展开，卡片上的「+」新开对话；`onSelect(id, { jobId, taskId })` 的 `id` 就是对话键，直接交给 CliChat 即可。指定了对话时，「结束对话」只关这一个（`POST /api/jobs/:id/conversations/:taskId/close`），没指定时结束整个对话任务。工具函数 `convKey` / `parseConvKey` 从包里导出。
 
 一次性任务（含续派，`mode` 不是 `conversation`）也能交给 CliChat：只读显示一个子任务的执行过程（没有输入框和「结束对话」，状态是子任务的状态）。`taskId` 指定看哪个子任务，不给看最近派发的那个（续派开出新的子任务后自动跟过去）。转录里中枢的派发标记行（`[CENTER-ATTEMPT…]`）去掉，完成核对（`[CENTER-CONFIRM]`）合成一行说明。需要 0.3.1 + 中枢实时流支持 `?task=`；0.3.0 打开这类任务会一直「正在重连」。
+
+例外是对话式续派的子任务（续派时 `mode: "conversation"`）：用 `taskId` 打开它就是一个能一直聊下去的对话——有输入框，不显示「子任务已完成」之类的状态；每发一条 = 续派一条 `continue_from` 这个子任务的子任务（接在同一个 Agent 会话里），对话键不变。需要 0.4.0 + 同版本中枢。
 - Web Component 上监听 `cli-turn-end` / `cli-conversation-end` / `cli-event` 事件。
 - 旧名字 `onCallback` / `cli-callback` 仍然可用，等同于前两个合在一起。