@personai/agent-ui-terminal 1.0.0-preview.1 → 1.0.0-preview.3

package/README.md

@@ -5,7 +5,7 @@
 ## 安装
 
 ```sh
-npm install @personai/agent-ui-terminal
+npm install --save-exact @personai/agent-ui-terminal@1.0.0-preview.3
 ```
 
 应用入口需导入 `@personai/agent-ui-terminal/styles.css`。包内 `npm run dev` 提供本地模拟宿主演示。
@@ -38,6 +38,26 @@ terminal.dispose();
 
 `createTerminalTransport` 使用 Socket.IO 连接远端 PTY。服务端负责安全地创建并管理 shell 进程；浏览器组件只发送终端输入、尺寸变化和信号。连接地址、认证、租户信息和进程启动策略均由宿主决定。
 
+## 实例控制
+
+`initTerminal()` 返回可直接调用的实例，无需获取内部 Terminal 类或 xterm 对象。以下三个方法从 `1.0.0-preview.3` 开始提供，`1.0.0-preview.2` 不包含它们。
+
+| 方法 | 返回值 | 行为 |
+| --- | --- | --- |
+| `clear()` | `void` | 调用 xterm 清屏，清除缓冲区并保留当前提示行；不向 shell 发送 clear 命令、不停止 PTY，也不删除宿主历史 |
+| `getSelection()` | `string` | 读取终端选中的文本；未选择时返回空字符串 |
+| `focus()` | `void` | 聚焦终端输入；不重建实例或连接 |
+
+```ts
+terminal.clear();
+const selectedText = terminal.getSelection();
+terminal.focus();
+```
+
+这些方法在实例存活期间使用；关闭后调用 `dispose()`，不要继续操作已销毁的实例。三个方法均保留当前主题和语言设置。
+
+主题初始化放在 `terminalOptions.themeTokens`；运行中通过 `setThemeTokens(tokens)` 更新，通过 `resetTheme()` 清除覆盖，通过 `refreshTheme()` 将当前 CSS 颜色同步到 xterm。`setLocale()` / `setMessages()` 更新文案。
+
 ## 自定义传输
 
 如果宿主的传输协议不同，实现并注入 `TerminalTransport` 即可。它负责连接、发送键盘输入/尺寸/信号，并通知组件输出、会话信息、退出和错误。需要 AI 能力时再实现 `AITransport` 的 `request` 与 `stream`；流式结果通过 `onChunk` 提供文本，通过 `onEvent` 提供结构化 Agent 活动。详见包导出的 TypeScript 接口。

package/dist/index.js

@@ -2552,8 +2552,8 @@ class Yi {
       }
   }
   getOrCreateSession(e) {
-    var I;
-    if (!((I = this.terminal) != null && I.element))
+    var C;
+    if (!((C = this.terminal) != null && C.element))
       return;
     const t = Zi(e.requestId, e.conversationId), i = this.sessions.get(t);
     if (i)
@@ -3964,8 +3964,8 @@ class Ds {
             let g;
             try {
               g = JSON.parse(u);
-            } catch (I) {
-              h(I);
+            } catch (C) {
+              h(C);
               return;
             }
             const w = $s(g);
@@ -4072,13 +4072,13 @@ function Qs(s) {
   let o, r = !1;
   const a = {}, l = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map(), h = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Set(), u = (d, m, E) => {
     var T;
-    const C = (T = a.current) == null ? void 0 : T.shellIntegrationAddon, $ = (C == null ? void 0 : C.sanitizeInput(d)) ?? d;
-    C == null || C.noteInput($), t.input($, m, E);
+    const I = (T = a.current) == null ? void 0 : T.shellIntegrationAddon, $ = (I == null ? void 0 : I.sanitizeInput(d)) ?? d;
+    I == null || I.noteInput($), t.input($, m, E);
   }, g = i ? async (d) => {
     var T, ie, Ue, He, ze, We;
     const m = ((ie = (T = globalThis.crypto) == null ? void 0 : T.randomUUID) == null ? void 0 : ie.call(T)) ?? `${Date.now()}-${Math.random()}`, E = new AbortController();
     h.set(m, E);
-    let C;
+    let I;
     const $ = async (Y) => {
       var D, fe;
       await i.stream(
@@ -4099,7 +4099,7 @@ function Qs(s) {
             if (r) return;
             const _ = Fs(R);
             if (_) {
-              C = _, (se = (k = a.current) == null ? void 0 : k.modelSessionAddon) == null || se.appendUserInputRequest({
+              I = _, (se = (k = a.current) == null ? void 0 : k.modelSessionAddon) == null || se.appendUserInputRequest({
                 conversationId: "default",
                 requestId: m,
                 request: _,
@@ -4122,9 +4122,9 @@ function Qs(s) {
         requestId: m
       }), await $();
     } finally {
-      h.delete(m), !r && !C && !p.has(m) && await (((We = (ze = a.current) == null ? void 0 : ze.modelSessionAddon) == null ? void 0 : We.complete(m)) ?? Promise.resolve());
+      h.delete(m), !r && !I && !p.has(m) && await (((We = (ze = a.current) == null ? void 0 : ze.modelSessionAddon) == null ? void 0 : We.complete(m)) ?? Promise.resolve());
     }
-    if (C && !r) {
+    if (I && !r) {
       let Y, D;
       const fe = new Promise((R, _) => {
         Y = R, D = _;
@@ -4135,7 +4135,7 @@ function Qs(s) {
       }), l.set(m, async (R, _) => {
         var se;
         const k = (se = a.current) == null ? void 0 : se.modelSessionAddon;
-        k == null || k.clearUserInputRequest(m, R, _), C = void 0;
+        k == null || k.clearUserInputRequest(m, R, _), I = void 0;
         try {
           await $([
             {
@@ -4143,11 +4143,11 @@ function Qs(s) {
               status: "resolved",
               payload: { answers: _ }
             }
-          ]), C || (await (k == null ? void 0 : k.complete(m)), Y());
+          ]), I || (await (k == null ? void 0 : k.complete(m)), Y());
         } catch (ne) {
           throw D(ne), ne;
         } finally {
-          k == null || k.setUserInputSubmitting(m, !1), C || (l.delete(m), c.delete(m));
+          k == null || k.setUserInputSubmitting(m, !1), I || (l.delete(m), c.delete(m));
         }
       }), await fe;
     }
@@ -4156,7 +4156,7 @@ function Qs(s) {
     signal: E
   }) => {
     var $, T;
-    let C = "";
+    let I = "";
     return await i.stream(
       ((T = ($ = s.prompts) == null ? void 0 : $.explain) == null ? void 0 : T.call($, d)) ?? `Command:
 ${d.command}
@@ -4165,18 +4165,18 @@ Output:
 ${d.output}`,
       {
         onChunk: ({ delta: ie }) => {
-          C += ie, m == null || m(ie);
+          I += ie, m == null || m(ie);
         },
         signal: E
       }
-    ), C;
+    ), I;
   } : void 0, f = i ? (d) => {
     var m, E;
     return i.request(((E = (m = s.prompts) == null ? void 0 : m.generate) == null ? void 0 : E.call(m, d)) ?? d);
   } : void 0, F = (d) => {
     const m = a.current;
     return m ? m.executeCommand(d) : Promise.reject(new Error("终端尚未完成初始化"));
-  }, I = new ks(s.el, {
+  }, C = new ks(s.el, {
     cursorBlink: !0,
     cursorStyle: "bar",
     cursorWidth: 2,
@@ -4234,14 +4234,14 @@ ${d.output}`,
         requestId: m,
         answers: E
       }) => {
-        const C = l.get(d);
-        C && await C(m, E);
+        const I = l.get(d);
+        I && await I(m, E);
       },
       onCancelSession: async ({ requestId: d }) => {
-        var E, C, $, T;
+        var E, I, $, T;
         p.add(d), l.delete(d), (E = c.get(d)) == null || E.resolve(), c.delete(d);
         const m = h.get(d);
-        m == null || m.abort(new DOMException("会话已终止", "AbortError")), await ((C = i == null ? void 0 : i.cancel) == null ? void 0 : C.call(
+        m == null || m.abort(new DOMException("会话已终止", "AbortError")), await ((I = i == null ? void 0 : i.cancel) == null ? void 0 : I.call(
           i,
           (m == null ? void 0 : m.signal) ?? new AbortController().signal
         )), await ((T = ($ = a.current) == null ? void 0 : $.modelSessionAddon) == null ? void 0 : T.complete(
@@ -4250,22 +4250,22 @@ ${d.output}`,
       }
     } : void 0
   });
-  a.current = I;
+  a.current = C;
   const v = t.onOutput((d) => {
-    I.terminal.write(d, () => {
+    C.terminal.write(d, () => {
       var m;
-      (m = I.shellIntegrationAddon) == null || m.noteOutput(d);
+      (m = C.shellIntegrationAddon) == null || m.noteOutput(d);
     });
   }), S = t.onSessionChange((d) => {
     var m, E;
-    o = d, (m = I.shellIntegrationAddon) == null || m.setCwd(d.currentDirectory), d.supportsBlocks || (E = s.onDegraded) == null || E.call(s, d);
+    o = d, (m = C.shellIntegrationAddon) == null || m.setCwd(d.currentDirectory), d.supportsBlocks || (E = s.onDegraded) == null || E.call(s, d);
   }), q = t.onExit((d) => {
     var m;
     (m = s.onExit) == null || m.call(s, d);
   }), K = t.onError((d) => {
     te(d);
-  }), _e = I.terminal.onResize((d) => {
-    I.shouldNotifyTransportResize() && t.resize(d);
+  }), _e = C.terminal.onResize((d) => {
+    C.shouldNotifyTransportResize() && t.resize(d);
   });
   t.connect().catch((d) => {
     te(qs(d));
@@ -4276,15 +4276,27 @@ ${d.output}`,
   return {
     dispose() {
       var d;
-      r = !0, v.dispose(), S.dispose(), q.dispose(), K.dispose(), _e.dispose(), t.dispose(), (d = i == null ? void 0 : i.dispose) == null || d.call(i), I.dispose();
+      r = !0, v.dispose(), S.dispose(), q.dispose(), K.dispose(), _e.dispose(), t.dispose(), (d = i == null ? void 0 : i.dispose) == null || d.call(i), C.dispose();
+    },
+    /** Clears xterm's buffer while keeping the current prompt line and PTY session. */
+    clear() {
+      C.terminal.clear();
+    },
+    /** Returns selected terminal text, or an empty string when nothing is selected. */
+    getSelection() {
+      return C.terminal.getSelection();
+    },
+    /** Focuses the terminal input without reconnecting its transport. */
+    focus() {
+      C.terminal.focus();
     },
     /** Runs a command through the real prompt, producing a normal block. */
     executeCommand(d) {
-      return I.executeCommand(d);
+      return C.executeCommand(d);
     },
     appendChatChunk(d, m) {
       var E;
-      (E = I.modelSessionAddon) == null || E.appendMessageChunk({
+      (E = C.modelSessionAddon) == null || E.appendMessageChunk({
         requestId: (m == null ? void 0 : m.requestId) ?? "default",
         conversationId: (m == null ? void 0 : m.conversationId) ?? "default",
         response: d
@@ -4292,22 +4304,22 @@ ${d.output}`,
     },
     completeChat(d = "default") {
       var m;
-      return ((m = I.modelSessionAddon) == null ? void 0 : m.complete(d)) ?? Promise.resolve();
+      return ((m = C.modelSessionAddon) == null ? void 0 : m.complete(d)) ?? Promise.resolve();
     },
     setThemeTokens(d) {
-      I.setThemeTokens(d);
+      C.setThemeTokens(d);
     },
     resetTheme() {
-      I.resetTheme();
+      C.resetTheme();
     },
     refreshTheme() {
-      I.refreshTheme();
+      C.refreshTheme();
     },
     setLocale(d, m) {
-      n.setLocale(d), m && n.setMessages(m), I.refreshLocale();
+      n.setLocale(d), m && n.setMessages(m), C.refreshLocale();
     },
     setMessages(d) {
-      n.setMessages(d), I.refreshLocale();
+      n.setMessages(d), C.refreshLocale();
     }
   };
 }

package/dist/src/index.d.ts

@@ -49,6 +49,12 @@ export interface ChatTerminalOptions {
 export type IOptions = ChatTerminalOptions;
 export declare function initTerminal(options: ChatTerminalOptions): {
     dispose(): void;
+    /** Clears xterm's buffer while keeping the current prompt line and PTY session. */
+    clear(): void;
+    /** Returns selected terminal text, or an empty string when nothing is selected. */
+    getSelection(): string;
+    /** Focuses the terminal input without reconnecting its transport. */
+    focus(): void;
     /** Runs a command through the real prompt, producing a normal block. */
     executeCommand(command: string): Promise<TerminalCommandBlock>;
     appendChatChunk(response: string, ids?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@personai/agent-ui-terminal",
-  "version": "1.0.0-preview.1",
+  "version": "1.0.0-preview.3",
   "type": "module",
   "files": [
     "dist",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@microsoft/fetch-event-source": "^2.0.1",
-    "@personai/agent-ui-chat-core": "1.0.0-preview.1",
+    "@personai/agent-ui-chat-core": "1.0.0-preview.3",
     "@preact/signals-core": "^1.14.4",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-web-links": "^0.11.0",