@spzxg/cli-ui 0.0.0-stage → 0.1.0

package/src/core/types.ts

@@ -0,0 +1,278 @@
+/**
+ * 两套数据形状：
+ *   · center 服务（cli-task-center）对话任务接口的返回（snake_case，原样保留，便于对照 API 文档）；
+ *   · Operator 节点转录的消息与事件（center 的实时流原样转发，界面按 Operator 的规则渲染）。
+ */
+
+// ── center：对话任务 ────────────────────────────────────────────────
+
+export type JobStatus = "queued" | "bound" | "idle" | "running" | "paused" | "succeeded" | "failed" | "cancelled" | string;
+export type TurnStatus = "queued" | "dispatching" | "running" | "succeeded" | "failed" | "cancelled" | "merged" | string;
+
+export interface CenterTurn {
+  turn_id: string;
+  job_id: string;
+  task_id: string;
+  seq: number;
+  business_id: string | null;
+  status: TurnStatus;
+  input: string;
+  /** 合并了后面排队的消息时，实际发给 Agent 的全文；否则为 null（= input）。 */
+  sent_input: string | null;
+  merged_into_turn_id: string | null;
+  reply: string | null;
+  /** true = 这一轮以 Agent 提问结束：reply 是问题，下一条消息就是回答。 */
+  asked: boolean;
+  last_error: string | null;
+  attempt: number;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  /** true = 节点上的会话重建了，这一轮起之前的对话没带过去（工作区文件还在）。 */
+  context_reset: boolean;
+  /** 这一轮的改动是否已合并回项目基线。 */
+  merged?: boolean;
+  merge_error?: string | null;
+  created_at: string;
+  started_at: string | null;
+  ended_at: string | null;
+  queue_position?: number | null;
+}
+
+export interface CenterTask {
+  id: string;
+  job_id: string;
+  title: string;
+  status: string;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  browser?: boolean;
+  last_error: string | null;
+}
+
+export interface ConversationSummary {
+  turns: number;
+  queued_turns: number;
+  running_turn: boolean;
+  last_turn: CenterTurn | null;
+  last_activity_at: string | null;
+  expires_at: string | null;
+  closed_reason: string | null;
+  continued_from_job_id: string | null;
+  continued_by_job_id: string | null;
+}
+
+/** GET /api/jobs/:id */
+export interface CenterJob {
+  id: string;
+  title: string;
+  status: JobStatus;
+  mode?: "conversation" | string;
+  conversation?: ConversationSummary;
+  tasks: CenterTask[];
+}
+
+/** POST /api/jobs/:id/messages */
+export interface SendResult {
+  job_id: string;
+  status: JobStatus;
+  duplicate: boolean;
+  /** true = 原对话已结束，这条消息开了一个新对话（job_id 是新的）。 */
+  new_conversation: boolean;
+  previous_job_id: string | null;
+  queue_position: number | null;
+  turn: CenterTurn;
+}
+
+/** 新建对话时可带的参数（POST /api/jobs，mode=conversation）。 */
+export interface NewConversationOptions {
+  title?: string;
+  /** 业务自己的 ID（tasks[0].business_id）：第一轮的回调里原样带回，用来和业务数据对应。 */
+  businessId?: string;
+  workspace?: { name?: string; context?: string; branch?: string };
+  callback?: { url: string; code: string };
+  agent?: string;
+  timeoutSeconds?: number;
+  browser?: boolean;
+}
+
+// ── Operator：节点转录 ─────────────────────────────────────────────
+
+export type MsgRole = "user" | "assistant" | "tool" | "system" | "session_break";
+
+export interface Message {
+  id: string;
+  task_id?: string;
+  generation: number;
+  role: MsgRole;
+  content: string;
+  created_at: number;
+}
+
+export interface PendingMessage {
+  id: string;
+  generation: number;
+  content: string;
+  created_at: number;
+}
+
+export interface Msg {
+  id: string;
+  /** queued：中枢里还在排队、没送到节点的消息（界面上是可撤回的「排队中」气泡）。 */
+  role: MsgRole | "queued";
+  content: string;
+  generation: number;
+  toolId?: string;
+  ts?: number;
+  /** queued 气泡对应的中枢轮次，撤回时用。 */
+  turnId?: string;
+  /** queued 气泡：中枢给出的等待原因（节点连不上、没有可用节点……），正常排队时为空。 */
+  note?: string;
+}
+
+export interface AskOption { label: string; description?: string }
+export interface AskQuestion { question: string; header: string; multiSelect?: boolean; options: AskOption[] }
+export type AskAnswers = string[][];
+
+export interface InputField { label: string; secret?: boolean; options?: string[]; placeholder?: string }
+export interface InputRequest {
+  id: string;
+  message: string;
+  fields: InputField[];
+  status: "pending" | "answered" | "cancelled";
+  values?: string[];
+}
+
+export type DiffLine = { sign: "+" | "-" | " "; text: string };
+
+export type ToolPeek =
+  | { kind: "count"; text: string }
+  | { kind: "diff"; added: number; removed: number; label?: string; lines: DiffLine[]; truncated?: number }
+  | { kind: "lines"; label?: string; lines: string[]; truncated?: number }
+  | { kind: "todos"; items: { text: string; status: string }[] };
+
+export interface ToolData {
+  title: string;
+  detail?: string;
+  result?: string;
+  isError?: boolean;
+  peek?: ToolPeek;
+  diff?: DiffLine[];
+  ask?: { id: string; questions: AskQuestion[]; answers?: AskAnswers };
+  input?: InputRequest;
+}
+
+export interface TurnUsage {
+  cost_usd: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+}
+
+/** 节点回合事件（center 流里 `{type:"node", event}` 的 event）。 */
+export type NodeEvent =
+  | { type: "user"; content: string; msgId: string; generation: number; ts?: number }
+  | { type: "queued"; msgId: string; content: string; generation: number; ts?: number }
+  | { type: "dequeued"; msgId: string }
+  | { type: "model"; model: string }
+  | { type: "assistant"; content: string; msgId?: string; generation?: number; ts?: number }
+  | { type: "tool"; id: string; title: string; detail: string; peek?: ToolPeek; diff?: DiffLine[]; msgId?: string; generation?: number }
+  | { type: "tool_result"; id: string; content: string; isError: boolean; peek?: ToolPeek; msgId?: string }
+  | { type: "ask"; id: string; questions: AskQuestion[]; msgId?: string; generation?: number }
+  | { type: "ask_answered"; id: string; answers: AskAnswers; msgId?: string }
+  | { type: "input"; input: InputRequest; msgId?: string; generation?: number }
+  | { type: "usage"; usage: TurnUsage }
+  | { type: "notice"; content: string; msgId?: string; generation?: number }
+  | { type: "error"; content: string; msgId?: string; generation?: number }
+  | { type: "turn_end" }
+  | { type: string; [key: string]: unknown };
+
+/** center 实时流 chunk.events 里的一项。 */
+export type StreamItem =
+  | { type: "transcript"; messages: Message[] | null; pending: PendingMessage[] | null; running: boolean | null }
+  | { type: "node"; event: NodeEvent }
+  | { type: "turn"; turn: CenterTurn }
+  | { type: "job"; job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null } };
+
+export interface StreamSnapshot {
+  job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null; mode: string; title: string; conversation: ConversationSummary };
+  turns: CenterTurn[];
+}
+
+export interface StreamEnd {
+  reason: string;
+  continued_by_job_id?: string | null;
+}
+
+// ── center 回调体（与中枢 conversation.ts turnCallbackPayload / job-callback.ts 的字段一一对应） ──
+//
+// 组件在前端发出的 conversation_turn / conversation_closed 事件，载荷与中枢投递给 callback.url 的请求体同名同义，
+// 业务方可以用同一套代码处理「后端回调」和「前端事件」。前端拿不到的字段（event_id、callback_seq、cumulative、
+// carried）不出现；以后端回调为准落库，前端事件只用来刷新界面。
+
+/** 每轮一次：type = "conversation_turn"。 */
+export interface ConversationTurnCallback {
+  type: "conversation_turn";
+  /** 投递顺序号（= seq）。同一对话里按它从小到大处理；结束事件是最后一轮 + 1。 */
+  callback_seq: number;
+  job_id: string;
+  task_id: string;
+  turn_id: string;
+  seq: number;
+  business_id: string | null;
+  /** succeeded / failed / cancelled（被合并的消息不单独回调，见 messages）。 */
+  status: TurnStatus;
+  occurred_at: string;
+  /** 实际发给 Agent 的正文（合并了排队消息时是拼起来的全文）。 */
+  input: string;
+  /** 这一轮包含的全部消息，按发送顺序（排队的消息会合并进来）。 */
+  messages: Array<{ turn_id: string; seq: number; business_id: string | null; input: string }>;
+  reply: string | null;
+  /** true = 这一轮以 Agent 提问结束（reply 是问题），status 仍是 succeeded；下一条消息就是回答。 */
+  asked: boolean;
+  /** 失败 / 取消原因（中枢原文）。 */
+  message: string | null;
+  continued_from_job_id: string | null;
+  context_reset: boolean;
+  merged: boolean;
+  merge_error: string | null;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  started_at: string | null;
+  ended_at: string | null;
+}
+
+/** 对话结束一次：type = "conversation_closed"。 */
+export interface ConversationClosedCallback {
+  type: "conversation_closed";
+  mode: "conversation";
+  /** 投递顺序号：最后一轮的 seq + 1，永远排在这个对话所有 conversation_turn 之后。 */
+  callback_seq: number;
+  job_id: string;
+  /** succeeded（关闭 / 过期 / 换线）/ cancelled / failed。 */
+  status: JobStatus;
+  /** closed / cancelled / expired / node_reassigned / node_lost。 */
+  closed_reason: string | null;
+  /** 一共几轮（= 最大的 seq，被合并的消息也算）。 */
+  turns: number;
+  /** 接续出来的新对话（过期、换线、节点丢失后再发消息时才有）。 */
+  continued_by_job_id: string | null;
+  occurred_at: string;
+}
+
+export type ConversationCallback = ConversationTurnCallback | ConversationClosedCallback;

package/src/elements.tsx

@@ -0,0 +1,122 @@
+/**
+ * Web Component 版：任何页面（不用 React）都能直接放 <cli-msglist> / <cli-chat>。
+ *
+ *   import "@spzxg/cli-ui/styles.css";
+ *   import { defineCliElements } from "@spzxg/cli-ui/elements";
+ *   defineCliElements();
+ *
+ *   <cli-msglist group="a" base-url="/api/center" title="战略"></cli-msglist>
+ *   <cli-chat group="a"></cli-chat>
+ *
+ * 同一个 group 的元素共享一个仓库：列表点哪个，对话就显示哪个；不写 group 各自独立。
+ * 属性：base-url、token、line、namespace、group、job-id、title、color、theme、context、read-only、
+ *       config（界面配置 JSON）、new-conversation（新建对话参数 JSON：title / businessId / workspace / callback / agent …）。
+ * 界面配置也可以直接赋对象：document.querySelector("cli-chat").config = { header: { export: false } }。
+ * 事件：cli-event（detail 是 CliEvent：select / conversation_turn / conversation_closed / job_change / error）；
+ *       cli-callback（detail 与 center 回调 conversation_turn / conversation_closed 的请求体同名同义）。
+ * 渲染在 light DOM 里（不用 Shadow DOM），样式靠页面引入 styles.css，作用域都在 .cli-ui 内。
+ */
+import { createRoot, type Root } from "react-dom/client";
+import { CliMsgList } from "./msglist/CliMsgList.js";
+import { CliChat } from "./chat/CliChat.js";
+import { createCliStore, type CliStore } from "./core/store.js";
+
+const groups = new Map<string, CliStore>();
+
+function storeFor(el: HTMLElement): CliStore | undefined {
+  const group = el.getAttribute("group");
+  if (!group) return undefined;
+  const baseUrl = el.getAttribute("base-url") ?? undefined;
+  const key = `${group}|${baseUrl ?? ""}`;
+  let store = groups.get(key);
+  if (!store) {
+    store = createCliStore(storeOptions(el));
+    groups.set(key, store);
+  }
+  return store;
+}
+
+const ATTRS = ["base-url", "token", "line", "namespace", "group", "job-id", "title", "color", "theme", "context", "read-only", "config", "new-conversation"];
+
+function jsonAttr(el: HTMLElement, name: string): object | undefined {
+  const raw = el.getAttribute(name);
+  if (!raw) return undefined;
+  try { return JSON.parse(raw) as object; } catch { console.warn(`<${el.localName}> 的 ${name} 不是合法 JSON，已忽略`); return undefined; }
+}
+
+function storeOptions(el: HTMLElement) {
+  return {
+    baseUrl: el.getAttribute("base-url") ?? undefined,
+    token: el.getAttribute("token") ?? undefined,
+    line: el.getAttribute("line") ?? undefined,
+    namespace: el.getAttribute("namespace") ?? el.getAttribute("group") ?? undefined,
+    newConversation: jsonAttr(el, "new-conversation"),
+  };
+}
+
+abstract class CliElement extends HTMLElement {
+  static observedAttributes = ATTRS;
+  private root: Root | null = null;
+  private ownStore: CliStore | undefined;
+  private configValue: object | undefined;
+
+  /** 界面配置（对象）。优先于 config 属性里的 JSON。 */
+  get config(): object | undefined {
+    return this.configValue ?? jsonAttr(this, "config");
+  }
+  set config(value: object | undefined) {
+    this.configValue = value;
+    if (this.root) this.render();
+  }
+
+  connectedCallback() {
+    // 缺省撑满父容器；组件自己内部滚动（宿主给定高度即可）。
+    this.style.display ||= "block";
+    this.style.height ||= "100%";
+    this.style.minHeight ||= "0";
+    this.root ??= createRoot(this);
+    this.render();
+  }
+  disconnectedCallback() {
+    // 移动节点时会先断开再连上：推到下一轮再卸载。
+    queueMicrotask(() => { if (!this.isConnected) { this.root?.unmount(); this.root = null; } });
+  }
+  attributeChangedCallback() { if (this.root) this.render(); }
+
+  protected common() {
+    const store = storeFor(this) ?? (this.ownStore ??= createCliStore(storeOptions(this)));
+    return {
+      store,
+      title: this.getAttribute("title") ?? undefined,
+      color: this.getAttribute("color") ?? undefined,
+      theme: (this.getAttribute("theme") as "light" | "dark" | null) ?? undefined,
+      onEvent: (event: unknown) => this.dispatchEvent(new CustomEvent("cli-event", { detail: event, bubbles: true })),
+      onCallback: (payload: unknown) => this.dispatchEvent(new CustomEvent("cli-callback", { detail: payload, bubbles: true })),
+      style: { height: "100%" },
+      config: this.config as never,
+    };
+  }
+  protected abstract element(): React.ReactNode;
+  private render() { this.root?.render(this.element()); }
+}
+
+class CliMsgListElement extends CliElement {
+  protected element() {
+    const context = this.getAttribute("context");
+    // 回调类事件只由 <cli-chat> 发：同一个 group 里列表和对话共用一个仓库，两边都发的话 document 上会收到两遍。
+    const { onCallback: _chatOnly, ...common } = this.common();
+    return <CliMsgList {...common} {...(context !== null ? { context } : {})} />;
+  }
+}
+
+class CliChatElement extends CliElement {
+  protected element() {
+    const jobId = this.getAttribute("job-id");
+    return <CliChat {...this.common()} {...(jobId !== null ? { jobId: jobId || null } : {})} readOnly={this.hasAttribute("read-only")} />;
+  }
+}
+
+export function defineCliElements() {
+  if (!customElements.get("cli-msglist")) customElements.define("cli-msglist", CliMsgListElement);
+  if (!customElements.get("cli-chat")) customElements.define("cli-chat", CliChatElement);
+}

package/src/embed.ts

@@ -0,0 +1,47 @@
+/**
+ * 给第三方页面用的一体化入口：引入一个 JS 和一个 CSS 就能用，不需要 React、打包工具或 TypeScript。
+ *
+ *   <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>
+ *
+ * 引入后自动注册 <cli-chat> / <cli-msglist>；想用 JS 控制（传回调函数、随时改参数）就用 window.CliUI.mountChat / mountMsgList。
+ * 产物由 `npm run build:embed -w @spzxg/cli-ui` 生成在 dist/。
+ */
+import "./styles.css";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { defineCliElements } from "./elements.js";
+import { CliChat, type CliChatProps } from "./chat/CliChat.js";
+import { CliMsgList, type CliMsgListProps } from "./msglist/CliMsgList.js";
+import { CliCenterProvider } from "./core/provider.js";
+import { createCliStore } from "./core/store.js";
+import { createCenterClient } from "./core/client.js";
+
+export interface Mounted<P> {
+  /** 合并更新参数（只传要改的）。 */
+  update(next: Partial<P>): void;
+  unmount(): void;
+}
+
+function mount<P extends object>(Component: (props: P) => unknown, el: Element, props: P): Mounted<P> {
+  const root = createRoot(el);
+  let current = props;
+  const render = () => root.render(createElement(Component as never, { style: { height: "100%" }, ...current }));
+  render();
+  return {
+    update(next) { current = { ...current, ...next }; render(); },
+    unmount() { root.unmount(); },
+  };
+}
+
+/** 在一个元素里挂对话组件。参数与 React 的 <CliChat> 相同（jobId、newConversation、onCallback、config……）。 */
+export const mountChat = (el: Element, props: CliChatProps = {}) => mount(CliChat, el, props);
+/** 在一个元素里挂列表组件。参数与 React 的 <CliMsgList> 相同。 */
+export const mountMsgList = (el: Element, props: CliMsgListProps = {}) => mount(CliMsgList, el, props);
+
+export { defineCliElements, CliChat, CliMsgList, CliCenterProvider, createCliStore, createCenterClient };
+
+defineCliElements();
+const api = { mountChat, mountMsgList, createCliStore, createCenterClient, defineCliElements };
+(globalThis as { CliUI?: typeof api }).CliUI = api;

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @spzxg/cli-ui —— 任务中心（cli-task-center）对话任务的前端积木，数据全部来自 center 服务。
+ *
+ *   cli-msglist  消息对话列表（CliMsgList）
+ *   cli-chat     对话（CliChat）
+ *   cli-board    右侧看板 —— 规划中，见 PLAN.md
+ *
+ * 单独用：
+ *   <CliChat baseUrl="/api/center" jobId="job_xxx" />
+ * 组合用（同一个 Provider 里共享选中和实时流）：
+ *   <CliCenterProvider baseUrl="/api/center" namespace="strategy">
+ *     <CliMsgList title="战略" />
+ *     <CliChat />
+ *   </CliCenterProvider>
+ *
+ *   import "@spzxg/cli-ui/styles.css";
+ * 非 React 页面用 Web Component：import { defineCliElements } from "@spzxg/cli-ui/elements"。
+ */
+export { CliMsgList, type CliMsgListProps } from "./msglist/CliMsgList.js";
+export { CliChat, type CliChatProps } from "./chat/CliChat.js";
+export { CliCenterProvider, useCliStore, useCliState, type CliCenterProviderProps } from "./core/provider.js";
+
+export {
+  resolveChatConfig, resolveMsgListConfig, DEFAULT_CHAT_CONFIG, DEFAULT_MSGLIST_CONFIG,
+  type CliChatConfig, type CliMsgListConfig, type ResolvedChatConfig, type ResolvedMsgListConfig,
+} from "./core/config.js";
+export { createCliStore, type CliStore, type CliStoreOptions, type CliState, type CliEvent, type JobEntry } from "./core/store.js";
+export { createCenterClient, CenterError, type CenterClient, type CenterClientOptions, type StreamHandlers } from "./core/client.js";
+export { viewMessages, isRunning, runningTurn, type ConvState } from "./core/conversation.js";
+export {
+  composeMessage, splitMessage, serializeBlock, readFileText, isLongText, ACCEPTED_EXTENSIONS, MAX_MESSAGE_CHARS,
+  type TextBlock, type MessagePart,
+} from "./core/blocks.js";
+export type * from "./core/types.js";