sidekick-chat 0.0.0-stage → 0.2.2

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,128 @@
-# 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
+```
+
+0.2.2 起，输入框上方 HUD 显示 OpenCode、Codex、Claude WSL 和 Claude Docker 的剩余额度，每分钟刷新。显示采样时间，刷新失败保留旧值并标注；无数据时显示未知。`/quota` 可立即刷新并查看本地日期时间标注的重置时间，纯文本交互也支持。额度沿用 App 的接口，凭据只用于访问同一服务器；不需要在 CLI 配置模型 API key。
+
+0.2.1 起，交互界面实时显示服务器的流式回复草稿，支持生成中的 Markdown；正式消息到达后替换草稿，不重复显示。切换会话、断线、清屏或服务端撤回会清除临时草稿。草稿不落盘，重连只补正式消息。`--plain`、管道、一次性 `ask` 和 `--json` 只输出正式消息。
+
+需要 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` | 名册:谁在线、谁在忙 |
+| `/quota` | 刷新额度，查看剩余比例、采样和重置时间 |
+| `/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.2",
+  "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,236 @@
+/**
+ * 和 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, { signal } = {}) {
+    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: signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+      } catch (err) {
+        if (signal?.aborted) throw signal.reason;
+        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 };