sidekick-chat 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,75 @@
+Required Notice: Copyright (c) 2026 Cznorth (https://github.com/Cznorth/sidekick)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# Sidekick 终端客户端
 
-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.
+在终端里和秘书说话。它只是 `chat` World 的又一个客户端,和手机 App、网页版共用同一批会话、未读和回复,
+不新增任何后端接口——所以手机上收到的、终端里发的,是同一份对话。
+
+```
+$ npx sidekick-chat
+Sidekick · 秘书 https://hkv4.cznorth.cn/chat
+会话:秘书 · /help 看命令,/conv 列会话,Ctrl-C 退出
+────────────────────────────
+[11-03 13:39] 秘书 codex/gpt-5.5
+  已经把 frp 备用入口补给执行器了。
+你 › 明天几点提醒我看牙
+[13:44] 我
+  明天几点提醒我看牙
+[13:44] 秘书 codex/gpt-5.5
+  记成明天 9:30,提前 10 分钟提醒。
+```
+
+## 安装
+
+```bash
+npx sidekick-chat          # 不装直接用
+npm i -g sidekick-chat     # 或者装到全局,命令就是 sidekick
+```
+
+仓库里直接用(还没发包时):
+
+```bash
+node cli/bin/sidekick.mjs
+```
+
+需要 Node 22.19 以上。交互界面使用与 Pi agent 相同的 `@earendil-works/pi-tui`，支持 Markdown、中文换行、多行粘贴、输入历史和窗口缩放。
+
+Enter 发送，Shift+Enter 换行（终端需支持；也可用 Ctrl+J），↑/↓ 翻输入历史。回复和忙碌状态更新时保留输入草稿与光标。
+
+老终端可用 `sidekick --plain`：不上色、不重画输入行。管道和 `TERM=dumb` 自动使用纯文本；`--no-color` / `NO_COLOR` 只关闭颜色。一次性 `ask` 和 `--json` 保持文本/JSON 输出。
+
+## 登录
+
+凭据存在 `~/.sidekick/config.json`(权限 600),两种方式任选:
+
+```bash
+sidekick login                                  # 问地址和网页密码,换一个登录 Cookie
+sidekick login --url http://47.96.64.66:18792 --token <设备令牌>   # 直连 chat World
+```
+
+- **网页密码**:就是网页版那个 `CORTICO_WEB_PASSWORD`。客户端拿它调站点的 `/api/auth/login`,
+  拿到 `cortico_session` Cookie 存起来,400 天不用重登。服务器地址默认 `https://hkv4.cznorth.cn/chat`。
+- **设备令牌**:部署 `.env` 里的 `SIDEKICK_DEVICE_TOKEN`,和手机 App 用的是同一个。
+  适合备用线路(杭州 `47.96.64.66:18792`)这种没有网页登录接口的直连地址。
+
+`sidekick logout` 清掉本机登录态。Cookie 失效时会提示重新 `sidekick login`。
+
+## 用法
+
+```bash
+sidekick                          # 进交互,一行一句
+sidekick "今天有什么安排"          # 问一句,回复打印完就退出(适合脚本/管道)
+sidekick ask --wait 20 "…"        # 同上,收到第一条后最多再等 20 秒后续消息
+sidekick --conv 收发室             # 指定会话:名字、id 或 /conv 里的序号
+sidekick --json "…"               # 每条消息输出一行 JSON
+sidekick --device 家里的电脑 "…"   # 换一个署名(默认「终端」)
+```
+
+交互里的命令:
+
+| 命令 | 作用 |
+|---|---|
+| `/conv` | 列出会话(带未读和最后一条摘要) |
+| `/to <序号\|名字>` | 切换会话 |
+| `/history [n]` | 重印最近 n 条,默认 20 |
+| `/who` | 名册:谁在线、谁在忙 |
+| `/clear` | 清屏 |
+| `/quit` | 退出(也可以 Ctrl-C) |
+
+其它会话来消息时只在终端里提一句,`/to` 切过去看。其它设备上聊的、手机上聊的,这里都能看到历史的最近 30 条。
+
+## 环境变量
+
+参数优先于环境变量,环境变量优先于配置文件:
+
+| 变量 | 作用 |
+|---|---|
+| `SIDEKICK_URL` | 服务器地址,如 `https://hkv4.cznorth.cn/chat` |
+| `SIDEKICK_TOKEN` | 设备令牌(Bearer) |
+| `SIDEKICK_PASSWORD` | 网页登录密码(只在 `sidekick login` 时用,不落盘) |
+| `SIDEKICK_COOKIE` | 直接给 `cortico_session` 的值 |
+| `SIDEKICK_DEVICE` | 这台机器的署名 |
+| `SIDEKICK_CONFIG` | 配置文件路径,默认 `~/.sidekick/config.json` |
+| `NO_COLOR` | 设了就不上色 |
+
+## 怎么实现的
+
+只用了 `chat` World 已经开给手机 App 和网页的那几个接口(`packages/world-chat/src/world.ts` 的 `startHub`):
+
+| 接口 | 用途 |
+|---|---|
+| `GET /v1/team/state` | 主 Bot、名册、会话列表 |
+| `GET /v1/team/history?conv=&limit=` | 一个会话的历史 |
+| `POST /v1/team/send` | 发一句 |
+| `POST /v1/team/read` | 标记已读 |
+| `GET /v1/team/stream?after=` | SSE 推流:消息、正在输入、连接状态 |
+
+```
+bin/sidekick.mjs   入口,把参数交给 src/main.mjs
+src/main.mjs       login / logout / ask / 交互三种流程
+src/api.mjs        接口调用与 SSE 解析,断线按 1s→30s 退避重连,重连时带 seq 补收
+src/config.mjs     ~/.sidekick/config.json 读写,参数 > 环境变量 > 配置文件的优先级
+src/format.mjs     纯文本消息排版(纯函数)
+src/tui.mjs        Pi TUI：Markdown、编辑器、忙碌状态和差分渲染
+src/prompt.mjs     提问与遮掉回显的密码输入
+test/              node:test,`npm test`;有一个假 World 顶替服务器,不需要联网
+```
+
+## 测试
+
+```bash
+cd cli && node --test
+```
+
+`test/fake-world.mjs` 起了个假的 chat World(实现上面五个接口),所以鉴权失败、发送、推流补收、
+`sidekick ask` 端到端这些都能脱网验证。

package/bin/sidekick.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * `npx sidekick-chat` / `npm i -g sidekick-chat` 之后的入口:只是把参数交给 src/main.mjs。
+ */
+import { run } from '../src/main.mjs';
+
+await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,38 @@
-{
-  "name": "sidekick-chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "sidekick-chat",
+  "version": "0.2.0",
+  "description": "Sidekick 终端客户端:在终端里和秘书对话",
+  "type": "module",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "bin": {
+    "sidekick": "bin/sidekick.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "sidekick",
+    "cli",
+    "chat",
+    "assistant"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cznorth/sidekick-chat.git"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "1.0.0"
+  },
+  "devDependencies": {
+    "@xterm/headless": "5.5.0"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,235 @@
+/**
+ * 和 chat World 的 HTTP 接口打交道:鉴权、状态、历史、发送、SSE 推流。
+ *
+ * 只认两条路:设备令牌(Bearer,和手机 App 同一个 `SIDEKICK_DEVICE_TOKEN`),或网页登录拿到的
+ * `cortico_session` Cookie(和网页版同一个 `CORTICO_WEB_PASSWORD`)。接口本身见
+ * packages/world-chat/src/world.ts 的 `startHub`。
+ */
+import { authOrigin } from './config.mjs';
+
+/** 鉴权没过:登录态失效或令牌不对,调用方据此提示重新登录。 */
+export class AuthError extends Error {}
+
+/** 连不上(没拿到响应):只有这种错才换备用线路,4xx / 5xx 不换。 */
+export class NetworkError extends Error {}
+
+const REQUEST_TIMEOUT_MS = 20_000;
+
+export class SidekickApi {
+  /** `alt` 是备用线路(如杭州 `http://47.96.64.66:18792`),只有主线路连不上才用。 */
+  constructor({ url, alt, token, cookie }) {
+    this.primary = stripSlashes(String(url || ''));
+    this.alt = stripSlashes(String(alt || ''));
+    /** 当前用着哪条:切到备用线路后就不再每次先撞一次主线路。 */
+    this.current = this.primary;
+    this.token = token || '';
+    this.cookie = cookie || '';
+  }
+
+  get base() {
+    return this.current;
+  }
+
+  get headers() {
+    const h = { 'content-type': 'application/json' };
+    if (this.token) h.authorization = `Bearer ${this.token}`;
+    if (this.cookie) h.cookie = `cortico_session=${this.cookie}`;
+    return h;
+  }
+
+  /** 先试当前线路,连不上再试备用线路(只有拿不到响应才算连不上)。 */
+  async attempt(run) {
+    const bases = [this.current === this.alt ? this.primary : this.current];
+    if (this.alt && this.alt !== bases[0]) bases.push(this.alt);
+    let last;
+    for (const base of bases) {
+      try {
+        const out = await run(base);
+        this.current = base;
+        return out;
+      } catch (err) {
+        if (!(err instanceof NetworkError)) {
+          // 备用线路上没有网页登录接口:提示改用令牌,别让人以为密码错了。
+          if (err instanceof AuthError && base === this.alt && this.cookie) {
+            throw new AuthError('备用线路不认网页登录,改成 sidekick login --token <设备令牌>');
+          }
+          throw err;
+        }
+        last = err;
+      }
+    }
+    throw last;
+  }
+
+  async request(method, path, body) {
+    return this.attempt(async (base) => {
+      const url = `${base}/${path.replace(/^\/+/, '')}`;
+      let res;
+      try {
+        res = await fetch(url, {
+          method,
+          headers: this.headers,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+      } catch (err) {
+        throw new NetworkError(networkHint(url, err));
+      }
+      const data = await res.json().catch(() => ({}));
+      if (res.status === 401) throw new AuthError(data.error || '登录态已失效');
+      if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+      return data;
+    });
+  }
+
+  /** 拿一次服务器全貌:主 Bot、名册、会话列表和全局最新的 seq。 */
+  state() {
+    return this.request('GET', 'v1/team/state');
+  }
+
+  history(conv, limit = 60) {
+    return this.request('GET', `v1/team/history?conv=${encodeURIComponent(conv)}&limit=${limit}`);
+  }
+
+  send({ conv, text, device }) {
+    return this.request('POST', 'v1/team/send', { conv, text, device });
+  }
+
+  read(conv, seq) {
+    return this.request('POST', 'v1/team/read', { conv, seq });
+  }
+
+  imageUrl(name) {
+    return `${this.base}/v1/team/image?name=${encodeURIComponent(name)}`;
+  }
+
+  /**
+   * 订阅推流,断了按退避重连,重连时带上最后的 seq 把漏掉的补齐。
+   * `onEvent(event, payload)` 收到 hello / state / message / draft / thinking / busy / read。
+   * 返回的 promise 只在 abort 时结束。
+   */
+  async stream({ after = 0, device, signal, onEvent, onStatus }) {
+    let seq = after;
+    let delay = 1000;
+    while (!signal.aborted) {
+      try {
+        await this.openStream({ after: seq, device, signal, onEvent: (event, payload) => {
+          if (event === 'message' && typeof payload?.seq === 'number') seq = Math.max(seq, payload.seq);
+          if (event === 'state' && typeof payload?.latest === 'number') seq = Math.max(seq, payload.latest);
+          onEvent(event, payload);
+        }, onStatus });
+        delay = 1000;
+        onStatus?.('closed');
+      } catch (err) {
+        if (signal.aborted) return;
+        if (err instanceof AuthError) throw err;
+        onStatus?.('error', err);
+      }
+      // 断线重连:1s、2s、4s…最多 30s。
+      await sleep(delay, signal);
+      delay = Math.min(30_000, delay * 2);
+    }
+  }
+
+  async openStream({ after, device, signal, onEvent, onStatus }) {
+    const res = await this.attempt(async (base) => {
+      const url = `${base}/v1/team/stream?after=${after}&device=${encodeURIComponent(device || '终端')}`;
+      const r = await fetch(url, {
+        headers: { ...this.headers, accept: 'text/event-stream' },
+        signal,
+      }).catch((err) => {
+        throw new NetworkError(networkHint(url, err));
+      });
+      // 4xx / 5xx 不是网络问题,不换线路重试。
+      if (r.status === 401) throw new AuthError('登录态已失效');
+      if (!r.ok) throw new Error(`推流 HTTP ${r.status}`);
+      return r;
+    });
+    if (!res.body) throw new Error('推流没有响应体');
+    onStatus?.('open');
+    const decoder = new TextDecoder();
+    const reader = res.body.getReader();
+    let buf = '';
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) return;
+        buf += decoder.decode(value, { stream: true });
+        let cut;
+        while ((cut = buf.indexOf('\n\n')) >= 0) {
+          const block = buf.slice(0, cut);
+          buf = buf.slice(cut + 2);
+          const frame = parseFrame(block);
+          if (frame) onEvent(frame.event, frame.data);
+        }
+      }
+    } finally {
+      reader.cancel().catch(() => {});
+    }
+  }
+}
+
+/** SSE 一块:`event: x` + 若干 `data:` 行;只有注释(心跳)或 `retry:` 时返回 null。 */
+export function parseFrame(block) {
+  let event = 'message';
+  let data = '';
+  for (const line of block.split('\n')) {
+    if (line.startsWith('event:')) event = line.slice(6).trim();
+    else if (line.startsWith('data:')) data += line.slice(5).trim();
+  }
+  if (!data) return null;
+  try {
+    return { event, data: JSON.parse(data) };
+  } catch {
+    return null;
+  }
+}
+
+/** 用网页登录密码换登录态 Cookie;WebUI 不在这个地址上时抛错说明改用令牌。 */
+export async function loginWithPassword(url, password) {
+  const endpoint = `${authOrigin(url)}/api/auth/login`;
+  let res;
+  try {
+    res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ password }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new Error(`连不上 ${endpoint}:${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (res.status === 401) throw new AuthError('密码不对');
+  if (res.status === 404) throw new Error(`${authOrigin(url)} 上没有网页登录接口,请改用 --token(设备令牌)`);
+  if (!res.ok) throw new Error(`登录失败:HTTP ${res.status}`);
+  const raw = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : [res.headers.get('set-cookie') ?? ''];
+  for (const line of raw) {
+    const m = /(?:^|;\s*)cortico_session=([^;]+)/.exec(line || '');
+    if (m) return decodeURIComponent(m[1]);
+  }
+  throw new Error('服务器没发登录 Cookie,请改用 --token(设备令牌)');
+}
+
+/** fetch 在网络层失败时只给一句 `fetch failed`,这里把地址和常见原因一起说出来。 */
+export function networkHint(url, err) {
+  if (err instanceof Error && err.name === 'TimeoutError') return `连不上 ${url}(超时)`;
+  const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : '';
+  return `连不上 ${url}${cause ? `(${cause})` : ''}`;
+}
+
+function stripSlashes(url) {
+  return url.replace(/\/+$/, '');
+}
+
+/** 等 ms 毫秒;signal 中止时提前返回。 */
+export function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', done);
+      resolve();
+    }
+    signal?.addEventListener?.('abort', done, { once: true });
+  });
+}

package/src/config.mjs

@@ -0,0 +1,84 @@
+/**
+ * 终端客户端的本地配置:`~/.sidekick/config.json`(权限 600)。
+ * 只存服务器地址、登录凭据(设备令牌或网页登录 Cookie)和上次用的会话,不存密码明文。
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const DEFAULT_URL = 'https://hkv4.cznorth.cn/chat';
+/** 主线路连不上时自动换的备用线路(杭州阿里云 frps 把 chat World 的 18792 开在公网)。 */
+export const DEFAULT_ALT = 'http://47.96.64.66:18792';
+
+export function configPath() {
+  return process.env.SIDEKICK_CONFIG || join(homedir(), '.sidekick', 'config.json');
+}
+
+export function readConfig() {
+  const file = configPath();
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8'));
+    return typeof raw === 'object' && raw ? raw : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(cfg) {
+  const file = configPath();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
+  // Windows 上 mode 只影响只读位,这里补一次尽力而为的收紧。
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* 某些文件系统不支持,忽略 */
+  }
+}
+
+export function clearConfig() {
+  const file = configPath();
+  if (existsSync(file)) writeFileSync(file, '{}\n', { mode: 0o600 });
+}
+
+/**
+ * 把命令行参数、环境变量和配置文件合成一份可用设置。优先级:参数 > 环境变量 > 配置文件。
+ * 设备令牌和 Cookie 二者取其一;都没有时返回的 `loggedIn` 为 false,由调用方引导登录。
+ */
+export function resolveSettings(flags = {}) {
+  const saved = readConfig();
+  const url = String(flags.url || process.env.SIDEKICK_URL || saved.url || DEFAULT_URL).trim();
+  const alt = String(flags.alt || process.env.SIDEKICK_ALT || saved.alt || defaultAltFor(url)).trim();
+  const token = String(flags.token || process.env.SIDEKICK_TOKEN || saved.token || '').trim();
+  const cookie = String(process.env.SIDEKICK_COOKIE || saved.cookie || '').trim();
+  const device = String(flags.device || process.env.SIDEKICK_DEVICE || saved.device || '终端').trim();
+  return {
+    url: stripTrailingSlash(url),
+    alt: stripTrailingSlash(alt),
+    token,
+    cookie,
+    device,
+    conv: flags.conv || saved.conv || '',
+    loggedIn: Boolean(token || cookie),
+    saved,
+  };
+}
+
+export function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, '');
+}
+
+/** 用默认的主线路时自动带上已知的备用线路;自己指定 `--url` 就只走那一条。 */
+export function defaultAltFor(url) {
+  return stripTrailingSlash(url) === DEFAULT_URL ? DEFAULT_ALT : '';
+}
+
+/** WebUI 的登录接口在站点根上,不在 `/chat/` 这类前缀下面。 */
+export function authOrigin(url) {
+  try {
+    const u = new URL(url);
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return stripTrailingSlash(url);
+  }
+}

package/src/format.mjs

@@ -0,0 +1,94 @@
+/**
+ * 把消息排版成终端里的一行行文字。纯函数,不碰网络和终端状态,好测。
+ */
+
+const ANSI = {
+  reset: '\u001b[0m',
+  dim: '\u001b[2m',
+  bold: '\u001b[1m',
+  cyan: '\u001b[36m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  red: '\u001b[31m',
+  gray: '\u001b[90m',
+};
+
+/** stdout 是终端、且没设 NO_COLOR 时才上色。 */
+export function colorsEnabled(stream = process.stdout) {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(stream?.isTTY);
+}
+
+export function paint(enabled, code, text) {
+  return enabled ? `${ANSI[code]}${text}${ANSI.reset}` : text;
+}
+
+const pad2 = (n) => String(n).padStart(2, '0');
+
+export function clockTime(ts) {
+  const d = new Date(ts);
+  return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+export function dayLabel(ts) {
+  const d = new Date(ts);
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+/** 消息的发送者显示名:`user` 是「我」,`system` 是「系统」,其余查名册,查不到就用 id。 */
+export function senderName(message, bots = []) {
+  if (message.from === 'user') return '我';
+  if (message.from === 'system') return '系统';
+  return bots.find((b) => b.id === message.from)?.name || message.from;
+}
+
+/**
+ * 一条消息排成多行:头一行是时间、名字和模型,正文缩进两格。
+ * `options.imageUrl` 给了就把图片链接也写出来。
+ */
+export function formatMessage(message, { bots = [], color = false, imageUrl } = {}) {
+  const who = senderName(message, bots);
+  const mine = message.from === 'user';
+  const model = message.model ? paint(color, 'gray', message.model) : '';
+  const head = [
+    paint(color, 'gray', `[${clockTime(message.ts)}]`),
+    paint(color, mine ? 'green' : 'cyan', who),
+    model,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  const lines = [head];
+  if (message.reply_to) {
+    const quote = `↳ 回复 ${message.reply_to.name || message.reply_to.from}:${message.reply_to.text}`;
+    lines.push(`  ${paint(color, 'gray', quote)}`);
+  }
+  const body = String(message.text ?? '');
+  for (const line of body.split('\n')) lines.push(`  ${line}`);
+  for (const name of message.images ?? []) {
+    const link = imageUrl ? ` ${imageUrl(name)}` : '';
+    lines.push(`  ${paint(color, 'gray', `[图片]${link}`)}`);
+  }
+  return lines.join('\n');
+}
+
+/** 会话列表里的一行:序号、未读数、标题、最后一条摘要。 */
+export function formatConversation(conv, index, { bots = [], current = '' } = {}) {
+  const mark = conv.id === current ? '*' : ' ';
+  const unread = conv.unread > 0 ? ` (${conv.unread})` : '';
+  const last = conv.last ? ` — ${senderName(conv.last, bots)}:${oneLine(conv.last.text, 40)}` : '';
+  return `${mark}${String(index).padStart(2)}. ${conv.title}${unread}${last}`;
+}
+
+/** 去掉换行、截断到 n 个字,给列表和引用用。 */
+export function oneLine(text, n = 60) {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > n ? `${flat.slice(0, n)}…` : flat;
+}
+
+/** 一条消息的纯文本版(一次性模式打印用,便于管道)。 */
+export function plainMessage(message, bots = []) {
+  return `${senderName(message, bots)}: ${String(message.text ?? '')}`.trimEnd();
+}
+
+export { ANSI };

package/src/main.mjs

@@ -0,0 +1,560 @@
+/**
+ * 终端客户端的主流程:`sidekick` 进交互对话,`sidekick login` 存凭据,`sidekick ask "…"` 一次性问一句。
+ *
+ * 它只是 chat World 的又一个客户端,和手机 App、网页版共用同一份会话和未读,
+ * 不新增任何后端接口(见 packages/world-chat/src/world.ts 的 `startHub`)。
+ */
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { AuthError, SidekickApi, loginWithPassword } from './api.mjs';
+import {
+  DEFAULT_ALT,
+  DEFAULT_URL,
+  clearConfig,
+  configPath,
+  readConfig,
+  resolveSettings,
+  stripTrailingSlash,
+  writeConfig,
+} from './config.mjs';
+import {
+  dayLabel,
+  formatConversation,
+  formatMessage,
+  colorsEnabled,
+  oneLine,
+  paint,
+  plainMessage,
+} from './format.mjs';
+import { ask, askPassword } from './prompt.mjs';
+
+const PACKAGE_VERSION = (() => {
+  try {
+    const file = fileURLToPath(new URL('../package.json', import.meta.url));
+    return JSON.parse(readFileSync(file, 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+const HELP = `Sidekick 终端客户端 ${PACKAGE_VERSION}
+
+用法:
+  sidekick                     和秘书对话(进去后输入一行回车发一条)
+  sidekick "今天有什么安排"      问一句,等回复打印完就退出
+  sidekick ask --wait 20 "…"   同上,收到第一条后最多再等 20 秒后续消息
+  sidekick login               登录(网页密码或设备令牌)
+  sidekick logout              删掉本机保存的登录态
+  sidekick help                这份说明
+
+参数:
+  --url <地址>      服务器地址,默认 ${DEFAULT_URL}
+  --alt <地址>      备用线路,主线路连不上时自动换,默认 ${DEFAULT_ALT}
+  --token <令牌>    设备令牌(部署 .env 的 SIDEKICK_DEVICE_TOKEN),跳过密码登录
+  --password <密码> 网页登录密码(不给就在终端里问)
+  --conv <会话>     指定会话:id、名字或 /conv 列表里的序号,默认和秘书的私聊
+  --device <名字>   这台机器的署名,默认「终端」
+  --wait <秒>       一次性模式:收到第一条后再等多久算说完,默认 6
+  --json            一次性模式:每条消息输出一行 JSON
+  --no-color        不上色
+  --plain           纯文本:不上色、不重画输入行(老终端/管道/日志里用)
+  -h, --help        这份说明
+  -v, --version     版本
+
+进交互后可用 /help 看命令,/conv 列会话,/to 切换,Ctrl-C 退出。
+
+环境变量(优先于配置文件):SIDEKICK_URL、SIDEKICK_ALT、SIDEKICK_TOKEN、SIDEKICK_PASSWORD、SIDEKICK_DEVICE、SIDEKICK_COOKIE。
+配置放在 ${configPath()}(权限 600)。`;
+
+/** 命令行参数解析:node 自带的 parseArgs,不引第三方依赖。 */
+function parseFlags(argv) {
+  const flags = { positional: [] };
+  const takesValue = new Set(['url', 'alt', 'token', 'password', 'conv', 'device', 'wait']);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') {
+      flags.positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg === '-h' || arg === '--help') {
+      flags.help = true;
+      continue;
+    }
+    if (arg === '-v' || arg === '--version') {
+      flags.version = true;
+      continue;
+    }
+    if (arg === '--json') {
+      flags.json = true;
+      continue;
+    }
+    if (arg === '--no-color') {
+      flags.noColor = true;
+      continue;
+    }
+    if (arg === '--plain') {
+      flags.plain = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      const name = eq >= 0 ? arg.slice(2, eq) : arg.slice(2);
+      if (!takesValue.has(name)) throw new Error(`不认识的参数:--${name}`);
+      const value = eq >= 0 ? arg.slice(eq + 1) : argv[++i];
+      if (value === undefined) throw new Error(`--${name} 缺一个值`);
+      flags[name] = value;
+      continue;
+    }
+    flags.positional.push(arg);
+  }
+  return flags;
+}
+
+const stdout = (text) => process.stdout.write(`${text}\n`);
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+/** 登录:有令牌就用令牌,否则拿网页密码换 Cookie,最后都用 `/v1/team/state` 验一次。 */
+async function loginCommand(flags) {
+  const current = resolveSettings(flags);
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  let url = stripTrailingSlash(String(flags.url || current.url || DEFAULT_URL));
+  if (interactive && !flags.url) {
+    url = stripTrailingSlash(await ask(`服务器地址 [${current.url}]:`, { fallback: current.url }));
+  }
+
+  let token = String(flags.token || '').trim();
+  let cookie = '';
+  if (!token) {
+    let password = String(flags.password || process.env.SIDEKICK_PASSWORD || '');
+    if (!password) {
+      if (!interactive) throw new Error('没有终端可问密码:请用 --password 或 --token');
+      password = await askPassword('网页登录密码(和网页版同一个 CORTICO_WEB_PASSWORD):');
+      if (!password) throw new Error('没输入密码');
+    }
+    cookie = await loginWithPassword(url, password);
+  }
+
+  const api = new SidekickApi({ url, alt: current.alt, token, cookie });
+  const state = await api.state();
+  const primary = state.bots.find((b) => b.primary);
+  const cfg = { ...readConfig(), url, alt: current.alt, device: current.device || '终端', savedAt: new Date().toISOString() };
+  if (token) {
+    cfg.token = token;
+    delete cfg.cookie;
+  } else {
+    cfg.cookie = cookie;
+    delete cfg.token;
+  }
+  writeConfig(cfg);
+  stdout(`登录成功:${url}`);
+  stdout(`主 Bot:${primary?.name || state.primary};会话 ${state.conversations.length} 个。凭据存在 ${configPath()}`);
+  return { url, token, cookie };
+}
+
+/** 一次性模式:发一句,把回复打印完就退出,方便脚本里用。 */
+async function askOnce(flags, text) {
+  const settings = resolveSettings(flags);
+  if (!settings.loggedIn) throw new AuthError('还没登录,先运行 sidekick login');
+  const api = new SidekickApi(settings);
+  const state = await api.state();
+  const conv = pickConv(state, settings.conv);
+  const idleMs = Math.max(1, Number(flags.wait || 6) || 6) * 1000;
+  const sent = await api.send({ conv, text, device: settings.device });
+
+  const ctl = new AbortController();
+  const got = [];
+  let idleTimer = null;
+  let guardTimer = null;
+  let finishing = false;
+  const done = new Promise((resolve) => {
+    const finish = () => {
+      if (finishing) return;
+      finishing = true;
+      clearTimeout(idleTimer);
+      clearTimeout(guardTimer);
+      ctl.abort();
+      resolve();
+    };
+    ctl.signal.addEventListener('abort', finish, { once: true });
+    // 一直没回复也别吊着:默认 5 分钟(按 idle 时间的两倍放宽)。
+    guardTimer = setTimeout(finish, Math.max(120_000, idleMs * 2));
+  });
+
+  api
+    .stream({
+      after: sent.seq,
+      device: settings.device,
+      signal: ctl.signal,
+      onEvent(event, payload) {
+        if (event === 'message') {
+          if (payload.conv !== conv || payload.from === 'user') return;
+          got.push(payload);
+          if (flags.json) stdout(JSON.stringify(payload));
+          else stdout(plainMessage(payload, state.bots));
+          clearTimeout(idleTimer);
+          idleTimer = setTimeout(() => ctl.abort(), idleMs);
+        } else if (event === 'busy' && conv.startsWith('dm:') && payload.busy === false && got.length > 0) {
+          // 私聊里这一轮结束了,不用再等 idle;群里别的成员还在忙,只认 idle。
+          ctl.abort();
+        }
+      },
+    })
+    .catch((err) => {
+      if (!ctl.signal.aborted) fail(`推流出错:${err instanceof Error ? err.message : String(err)}`);
+    });
+
+  await done;
+  if (got.length === 0) {
+    fail('没等到回复。检查服务器是否在跑,或者用 sidekick 进交互看看。');
+    return;
+  }
+}
+
+/** 按 id、名字或列表序号找一个会话;找不到返回 undefined。 */
+export function findConv(state, wanted) {
+  const ref = String(wanted || '').trim();
+  if (!ref) return undefined;
+  const byId = state.conversations.find((c) => c.id === ref);
+  if (byId) return byId;
+  const byTitle = state.conversations.find((c) => c.title === ref);
+  if (byTitle) return byTitle;
+  const index = Number(ref);
+  if (Number.isInteger(index) && index > 0 && index <= state.conversations.length) return state.conversations[index - 1];
+  return undefined;
+}
+
+/** 按 id、名字或列表序号挑会话;挑不到就退回和主 Bot 的私聊。 */
+export function pickConv(state, wanted) {
+  const primaryConv = `dm:${state.primary}`;
+  const found = findConv(state, wanted);
+  if (found) return found.id;
+  if (state.conversations.some((c) => c.id === primaryConv)) return primaryConv;
+  return state.conversations[0]?.id ?? primaryConv;
+}
+
+/** 交互模式。 */
+async function startChat(flags) {
+  let settings = resolveSettings(flags);
+  if (!settings.loggedIn) {
+    if (!process.stdin.isTTY) throw new AuthError('还没登录,先运行 sidekick login');
+    await loginCommand({ ...flags, url: flags.url || settings.url });
+    settings = resolveSettings(flags);
+  }
+
+  let api = new SidekickApi(settings);
+  let state;
+  try {
+    state = await api.state();
+  } catch (err) {
+    if (err instanceof AuthError) {
+      if (!process.stdin.isTTY) throw new AuthError('登录态已失效,重新运行 sidekick login');
+      await loginCommand({ ...flags, url: settings.url });
+      settings = resolveSettings(flags);
+      api = new SidekickApi(settings);
+      state = await api.state();
+    } else {
+      throw err;
+    }
+  }
+
+  // 老终端(不认 ANSI)和管道里别用转义序列:重画输入行会留下「[K」这类垃圾。
+  const vt = Boolean(process.stdout.isTTY && process.stdin.isTTY) && process.env.TERM !== 'dumb' && !flags.plain && process.env.SIDEKICK_PLAIN !== '1';
+  const color = flags.noColor || !vt ? false : colorsEnabled();
+  const convTitle = (id) => state.conversations.find((c) => c.id === id)?.title || id;
+  const convOf = (id) => state.conversations.find((c) => c.id === id);
+  let convId = pickConv(state, settings.conv);
+  let latest = state.latest || 0;
+  let everConnected = false;
+  const displayed = new Set();
+  const ctl = new AbortController();
+  let rl = null;
+  let closed = false;
+  let ui = null;
+  let streamTask = Promise.resolve();
+
+  const out = (text) => {
+    if (ui) ui.out(text);
+    else process.stdout.write(`${text}\n`);
+  };
+  const typing = (on) => ui?.typing(on);
+
+  const printMessage = (message) => {
+    const options = { bots: state.bots, color, imageUrl: (name) => api.imageUrl(name) };
+    if (ui) ui.message(message, options);
+    else out(formatMessage(message, options));
+  };
+  if (vt) {
+    const { createChatUI } = await import('./tui.mjs');
+    ui = createChatUI({ color, onSubmit: (text) => {
+      queue.push(() => text.startsWith('/') ? handleSlash(text) : sendText(text));
+      void drain();
+    }, onQuit: () => shutdown(0) });
+  }
+
+  async function printHistory(limit = 20) {
+    const body = await api.history(convId, limit);
+    let day = '';
+    for (const m of body.messages) {
+      const d = dayLabel(m.ts);
+      if (d !== day) {
+        out(paint(color, 'gray', `──── ${d} ────`));
+        day = d;
+      }
+      printMessage(m);
+    }
+    latest = Math.max(latest, body.latest || 0);
+    if (body.latest) api.read(convId, body.latest).catch(() => {});
+    if (body.messages.length === 0) out(paint(color, 'gray', '(这里还没有消息)'));
+  }
+
+  const primary = state.bots.find((b) => b.primary);
+  out(`${paint(color, 'bold', `Sidekick · ${primary?.name || state.primary}`)} ${paint(color, 'gray', settings.url)}`);
+  if (settings.conv && !findConv(state, settings.conv)) {
+    out(paint(color, 'yellow', `找不到会话「${settings.conv}」,先用「${convTitle(convId)}」;/conv 看全部`));
+  }
+  out(paint(color, 'gray', `会话:${convTitle(convId)} · /help 看命令,/conv 列会话,Ctrl-C 退出`));
+  await printHistory(30);
+
+  function applyState(next) {
+    if (!next) return;
+    state = next;
+    if (!convOf(convId)) convId = pickConv(state, '');
+  }
+
+  function onMessage(m) {
+    latest = Math.max(latest, m.seq || 0);
+    typing(false);
+    if (displayed.has(m.seq)) return;
+    displayed.add(m.seq);
+    if (displayed.size > 1000) displayed.delete(displayed.values().next().value);
+    if (m.conv !== convId) {
+      if (m.from !== 'user') {
+        out(paint(color, 'gray', `· ${convTitle(m.conv)} 有新消息(${oneLine(m.text, 40) || '图片'}),/to 切过去`));
+      }
+      return;
+    }
+    printMessage(m);
+    if (typeof m.seq === 'number') api.read(convId, m.seq).catch(() => {});
+  }
+
+  streamTask = api
+    .stream({
+      after: latest,
+      device: settings.device,
+      signal: ctl.signal,
+      onStatus: (kind) => {
+        // 只在「连着的时候断了」和「重新接上」各说一句,退避重试期间不刷屏。
+        if (kind === 'open') {
+          if (everConnected) out(paint(color, 'green', '已重新连上'));
+          everConnected = true;
+        } else if (kind === 'error' && everConnected) {
+          everConnected = false;
+          out(paint(color, 'red', '连接断了,正在重连…'));
+        }
+      },
+      onEvent(event, payload) {
+        if (event === 'hello' || event === 'state') applyState(payload.state ?? payload);
+        else if (event === 'message') onMessage(payload);
+        else if (event === 'busy') typing(Boolean(payload.busy));
+      },
+    })
+    .catch((err) => {
+      if (ctl.signal.aborted) return;
+      out(err instanceof AuthError ? '登录态已失效,重新运行 sidekick login' : `推流出错:${err.message}`);
+      shutdown(1);
+    });
+
+  function switchConv(next) {
+    convId = next;
+    const cfg = { ...readConfig(), url: settings.url, conv: convId, device: settings.device };
+    writeConfig(cfg);
+    out(paint(color, 'green', `→ ${convTitle(convId)}`));
+    return printHistory(30);
+  }
+
+  async function handleSlash(line) {
+    const [raw, ...rest] = line.slice(1).trim().split(/\s+/);
+    const cmd = (raw || '').toLowerCase();
+    const arg = rest.join(' ');
+    switch (cmd) {
+      case 'help':
+      case '?':
+        out([
+          '/conv            列出会话',
+          '/to <序号|名字>  切换会话',
+          '/history [n]     重印最近 n 条(默认 20)',
+          '/who             名册和连接状态',
+          '/clear           清屏',
+          '/quit            退出(也可以 Ctrl-C)',
+          '直接输入文字就是发给当前会话。',
+        ].join('\n'));
+        return;
+      case 'quit':
+      case 'exit':
+      case 'q':
+        shutdown(0);
+        return;
+      case 'conv':
+      case 'convs':
+      case 'ls':
+        out(
+          state.conversations
+            .map((c, i) => formatConversation(c, i + 1, { bots: state.bots, current: convId }))
+            .join('\n') || '(还没有会话)',
+        );
+        return;
+      case 'to':
+      case 'switch':
+        if (!arg) {
+          out('用法:/to <序号或名字>,先 /conv 看一眼');
+          return;
+        }
+        await switchConv(pickConv(state, arg));
+        return;
+      case 'history':
+      case 'h':
+        await printHistory(Math.max(1, Number(arg) || 20));
+        return;
+      case 'who':
+        out(
+          state.bots
+            .map((b) => `${b.primary ? '*' : ' '}${b.name}(${b.id}) ${b.status}${b.busy ? ' 正在忙' : ''} — ${b.role || '无专长'}`)
+            .join('\n'),
+        );
+        return;
+      case 'clear':
+        if (ui) ui.clear();
+        else out('(清屏已跳过:纯文本模式下不动终端)');
+        return;
+      default:
+        out(paint(color, 'red', `不认识的命令:/${cmd}(/help 看命令)`));
+    }
+  }
+
+  const queue = [];
+  let busy = false;
+  async function drain() {
+    if (busy) return;
+    const next = queue.shift();
+    if (next === undefined) return;
+    busy = true;
+    try {
+      await next();
+    } catch (err) {
+      out(paint(color, 'red', err instanceof Error ? err.message : String(err)));
+    } finally {
+      busy = false;
+      void drain();
+    }
+  }
+
+  async function sendText(text) {
+    const res = await api.send({ conv: convId, text, device: settings.device });
+    latest = Math.max(latest, res.seq);
+    if (displayed.has(res.seq)) return;
+    displayed.add(res.seq);
+    printMessage({ seq: res.seq, conv: convId, ts: Date.now(), from: 'user', text });
+  }
+
+  if (ui) {
+    ui.start();
+  } else {
+    rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    rl.on('line', (line) => {
+      const text = line.trim();
+      if (!text) return;
+      queue.push(() => (text.startsWith('/') ? handleSlash(text) : sendText(text)));
+      void drain();
+    });
+    rl.on('SIGINT', () => shutdown(0));
+    rl.on('close', () => {
+      if (!closed) shutdown(0);
+    });
+  }
+
+  function shutdown(code = 0) {
+    if (closed) return;
+    closed = true;
+    typing(false);
+    ui?.stop();
+    ctl.abort();
+    try {
+      rl?.close();
+    } catch {
+      /* 已经关了 */
+    }
+    process.exitCode = code;
+    void streamTask.catch(() => {});
+    // 让事件循环自己收尾:Windows 上在 TLS 句柄还没关完时就 process.exit(),
+    // 会让 libuv 报「!(handle->flags & UV_HANDLE_CLOSING)」直接崩掉。
+    // 万一有句柄赖着不放,1.5 秒后强退。
+    setTimeout(() => process.exit(code), 1500).unref();
+  }
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  let flags;
+  try {
+    flags = parseFlags(argv);
+  } catch (err) {
+    fail(`${err.message}\n\n${HELP}`);
+    return;
+  }
+  if (flags.help) {
+    stdout(HELP);
+    return;
+  }
+  if (flags.version) {
+    stdout(PACKAGE_VERSION);
+    return;
+  }
+  if (flags.noColor) process.env.NO_COLOR = '1';
+
+  const command = flags.positional[0];
+  const rest = flags.positional.slice(1);
+
+  process.on('unhandledRejection', (err) => {
+    fail(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+
+  try {
+    if (command === 'help') {
+      stdout(HELP);
+      return;
+    }
+    if (command === 'login') {
+      await loginCommand(flags);
+      return;
+    }
+    if (command === 'logout') {
+      clearConfig();
+      stdout(`已经删掉本机保存的登录态(${configPath()})`);
+      return;
+    }
+    if (command === 'ask') {
+      const text = rest.join(' ').trim();
+      if (!text) throw new Error('用法:sidekick ask "要说的话"');
+      await askOnce(flags, text);
+      return;
+    }
+    if (command) {
+      // 没有子命令就当成一句话发出去:sidekick "今天有什么安排"
+      await askOnce(flags, flags.positional.join(' ').trim());
+      return;
+    }
+    await startChat(flags);
+  } catch (err) {
+    if (err instanceof AuthError) {
+      fail(`${err.message}`);
+      process.exitCode = 2;
+      return;
+    }
+    fail(err instanceof Error ? err.message : String(err));
+  }
+}

package/src/prompt.mjs

@@ -0,0 +1,66 @@
+/**
+ * 终端里的交互输入:普通提问(带回车默认值)和遮掉回显的密码输入。
+ */
+import { createInterface } from 'node:readline';
+
+/** 问一句,拿一行答案;直接回车就用 `fallback`。 */
+export async function ask(question, { fallback = '', input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input, output, terminal: Boolean(input.isTTY) });
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(question, resolve);
+    });
+    const trimmed = answer.trim();
+    return trimmed || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+/** 读密码:终端里按 * 显示(不公开长度以外的信息),管道输入时直接读一行。 */
+export function askPassword(question, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) {
+    const rl = createInterface({ input, output, terminal: false });
+    return new Promise((resolve) => {
+      rl.once('line', (line) => {
+        rl.close();
+        resolve(line.replace(/\r$/, ''));
+      });
+    });
+  }
+  return new Promise((resolve) => {
+    output.write(question);
+    input.setRawMode(true);
+    input.resume();
+    let buf = '';
+    const finish = (value) => {
+      input.setRawMode(false);
+      input.pause();
+      input.off('data', onData);
+      output.write('\n');
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const ch of String(chunk)) {
+        if (ch === '\r' || ch === '\n') return finish(buf);
+        if (ch === '\u0003') {
+          // Ctrl-C:交还给外层,由它统一退出。
+          finish('');
+          process.kill(process.pid, 'SIGINT');
+          return;
+        }
+        if (ch === '\u007f' || ch === '\b') {
+          if (buf) {
+            buf = buf.slice(0, -1);
+            output.write('\b \b');
+          }
+          continue;
+        }
+        if (ch < ' ') continue;
+        buf += ch;
+        output.write('*');
+      }
+    };
+    input.on('data', onData);
+  });
+}

package/src/tui.mjs

@@ -0,0 +1,58 @@
+import { Container, Editor, Markdown, ProcessTerminal, Text, TuiMainScreen } from '@earendil-works/pi-tui';
+import { paint, formatMessage } from './format.mjs';
+
+export function markdownTheme(color) {
+  const style = (code) => (text) => paint(color, code, text);
+  return Object.fromEntries(Object.entries({
+    heading: 'bold', link: 'cyan', linkUrl: 'gray', code: 'yellow',
+    codeBlock: 'yellow', codeBlockBorder: 'gray', quote: 'gray', quoteBorder: 'gray',
+    hr: 'gray', listBullet: 'cyan', bold: 'bold', italic: 'dim',
+    strikethrough: 'dim', underline: 'cyan',
+  }).map(([name, code]) => [name, style(code)]));
+}
+
+/** Pi's renderer owns every screen write, including the editor and busy status. */
+export function createChatUI({ color, onSubmit, onQuit, terminal = new ProcessTerminal() }) {
+  const tui = new TuiMainScreen(terminal);
+  const transcript = new Container();
+  const status = new Text('', 1, 0);
+  const identity = (text) => text;
+  const editor = new Editor(tui, {
+    borderColor: (text) => paint(color, 'gray', text),
+    selectList: Object.fromEntries(['selectedPrefix', 'selectedText', 'description', 'scrollInfo', 'noMatch'].map((key) => [key, identity])),
+  });
+  tui.addChild(transcript);
+  tui.addChild(status);
+  tui.addChild(editor);
+  tui.addChild(new Text(paint(color, 'gray', 'Enter 发送 · Shift+Enter 换行 · ↑ 历史 · /help · Ctrl+C 退出'), 1, 0));
+  tui.setFocus(editor);
+  tui.addInputListener((data) => {
+    if (data === '\u0003' || data === '\u0004' && !editor.getText()) {
+      onQuit();
+      return { consume: true };
+    }
+  });
+  editor.onSubmit = (text) => {
+    if (!text.trim()) return;
+    editor.addToHistory(text);
+    editor.setText('');
+    onSubmit(text.trim());
+    tui.requestRender();
+  };
+  return {
+    start: () => tui.start(),
+    stop: () => tui.stop(),
+    out(text) { transcript.addChild(new Text(text, 1, 0)); tui.requestRender(); },
+    message(message, options) {
+      const header = formatMessage({ ...message, text: '', images: [] }, options).trimEnd();
+      transcript.addChild(new Text(`\n${header}`, 1, 0));
+      transcript.addChild(message.from === 'user'
+        ? new Text(String(message.text ?? ''), 2, 0)
+        : new Markdown(String(message.text ?? ''), 2, 0, markdownTheme(color)));
+      for (const name of message.images ?? []) transcript.addChild(new Text(`[图片] ${options.imageUrl?.(name) || name}`, 2, 0));
+      tui.requestRender();
+    },
+    typing(on) { status.setText(on ? paint(color, 'gray', '… 正在输入') : ''); tui.requestRender(); },
+    clear() { transcript.clear(); tui.requestRender(true); },
+  };
+}