@oversk7/pi-web-dsh-style 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 采用 DeepSeek Harness（DSH）视觉风格、面向 Windows 的非官方 Pi Coding Agent 本地浏览器界面扩展。后端使用 Pi 的公开 RPC 模式，每个会话对应独立的 RPC 进程；历史会话可直接从 Pi 会话文件恢复和渲染。
 
-> 当前正式版本为 1.0.0，仅承诺 Windows 10/11。服务只监听 `127.0.0.1`，不应通过端口转发或反向代理暴露到局域网或公网。
+> 仅承诺 Windows 10/11。首次启动只监听 `127.0.0.1`；电脑网页的“设置 → 手机访问”可配置仅本机、局域网和服务器中转。之后 `pi --web` 使用已保存的模式。
 
 ## 安装
 
@@ -34,9 +34,54 @@ pi --web
 /web
 /web --no-open
 /web --port 18789
+/web --lan
+/web --relay
+/web --local
 /web --stop
 ```
 
+### 网页会话中的斜杠命令
+
+输入 `/` 可查看当前可用命令。Web 内置命令包括 `/settings`、`/model`、`/thinking`、`/export`、`/copy`、`/name`、`/session`、`/new`、`/resume`、`/rewind`、`/tree`、`/compact` 和 `/reload`。
+
+- `/model provider/model` 精确匹配时切换模型；未唯一匹配时打开带搜索词的模型选择器。`/thinking high` 切换当前模型支持的思考强度，两者不带参数时打开选择器。
+- `/compact 压缩要求` 会将要求传给 Pi；`/name 名称` 修改会话名称，不带参数时显示当前名称。
+- `/resume` 打开侧栏会话搜索；`/export` 下载 HTML 到浏览器下载目录，暂不接受导出路径或 JSONL 格式参数。
+- 网页会话中的 `/reload` 只重载当前会话的扩展与配置。要重载整个 Web 服务，请使用设置中的“重新加载”或在宿主 Pi 终端执行 `/reload`。
+
+扩展命令、提示词模板和 `/skill:名称` 由当前会话的 Pi RPC 进程执行。未知命令会报错并保留草稿，不会作为普通消息发送给模型；普通消息需要避免以 `/` 开头。
+
+`/scoped-models`、`/import`、`/share`、`/fork`、`/clone`、`/trust`、`/changelog`、`/hotkeys`、`/login`、`/logout` 和 `/quit` 尚未提供对应的 Web 操作，输入时会显示说明。需要这些 Pi 功能时请使用终端。
+
+### 手机通过局域网访问
+
+电脑和手机连接同一 Wi-Fi，在电脑本机网页“设置 → 手机访问”中选择“局域网”并保存。也可以执行 `/web --lan`，或直接以 `pi --web-lan` 启动。首次使用时，在同一设置中设置固定密码；之后手机打开显示的地址，输入该密码即可登录。界面只显示一个手机访问地址，优先使用 Wi-Fi，并过滤 WSL、Hyper-V 等虚拟网卡。
+
+手机登录状态保留 30 天。密码在服务重启后继续有效，可在电脑本机网页中修改；修改密码后，已登录的手机需要重新登录。
+
+手机与电脑共用工作区和会话，可各自切换、发送消息、停止生成及回答扩展提问。手机上点击左上角按钮展开会话列表；输入框回车换行，点击发送按钮提交；图片按钮选择手机图片。手机切回前台或网络重连时会刷新会话内容。
+
+设置面板及 `/web --lan`、`/web --relay`、`/web --local` 会保存模式并切换正在运行的服务，保留后台会话进程。切换时浏览器实时连接会重新连接。执行 `/reload` 会保留端口和访问模式；重载或重启服务会保留密码和未过期的登录状态。
+
+首次开启时，如 Windows 弹出防火墙提示，请允许 Node.js 在当前可信网络上接收连接。若手机仍无法打开，检查防火墙是否允许该端口，以及 Wi-Fi 是否启用了客户端隔离。电脑需要保持运行且未休眠。
+
+局域网直连使用 HTTP，请只在可信局域网内使用。
+
+### 通过服务器中转
+
+电脑运行扩展和原生 `frpc`，服务器运行 `frps`、作为 STCP 访问端的 `frpc` 以及 Nginx。手机通过服务器的 HTTPS 域名访问，适用于校园网客户端隔离等无法直连的网络。电脑上的 `frpc` 由扩展启动和关闭，中转请求直接进入扩展的 Web 服务。
+
+1. 从 [frp 官方 Releases](https://github.com/fatedier/frp/releases) 下载电脑对应架构的 Windows 版本，将 `frpc.exe` 解压到固定位置。客户端和服务器建议使用相同版本（已验证 0.70.1）。
+2. 在电脑网页“设置 → 手机访问”选择“服务器中转”，填写服务器域名或 IPv4、frps 端口（默认 `7000`）、frps 认证密钥、手机 HTTPS 入口（如 `https://web.example.com`），以及 `frpc.exe` 路径。路径留空时从 PATH 查找 `frpc`；相对路径以状态目录为基准。认证密钥留空会保留已保存的值。
+3. 保存后，下载设置中生成的 `frps.toml`、`visitor.toml` 和 `nginx.conf`。隧道名称和私有密钥自动生成；隧道名称及服务器内部端口可在高级配置中调整。将域名 DNS 指向服务器，并为该域名准备有效的 HTTPS 证书。
+4. 服务器安装原生 frp 和 Nginx。新服务器使用 `frps -c frps.toml`，访问端使用 `frpc -c visitor.toml`，并用 systemd 等服务管理器保持运行。已有 frps 时复用现有端口和认证密钥，保留其配置。把生成的 Nginx 配置中的证书路径替换成实际证书路径，再安装到 Nginx 的站点配置目录，执行 `nginx -t` 验证并重载。
+
+手机打开显示的 HTTPS 地址，输入原有固定密码即可使用。设置会显示 frpc 的连接或错误状态；服务器暂时不可达时 frpc 自动重连，本机网页仍可使用。后续执行 `pi --web` 会自动恢复保存的中转模式；也可以用 `pi --web-relay` 或 `/web --relay` 明确启用已配置的中转。
+
+服务器需开放 HTTPS 端口和 frps 控制端口；生成的 STCP 访问端仅监听服务器 `127.0.0.1`，无须开放其内部端口。Nginx 配置保留域名 Host、附加代理密钥、限制登录请求速率，并关闭缓冲以支持实时消息。公网访问由扩展直接验证来源和固定密码，登录 Cookie 带有 `Secure` 标记。中转模式下，电脑 Web 服务仅监听本机回环地址。
+
+网络配置和服务器配置下载仅对电脑本机网页开放。更换服务器域名、隧道名称、认证密钥或服务器内部端口后，需要同步部署重新下载的服务器配置。电脑上的 Pi Web 需要保持运行且未休眠。
+
 ## 功能
 
 - 多工作区、多会话和后台会话并行运行。
@@ -45,14 +90,14 @@ pi --web
 - 模型、思考等级、中断、压缩和扩展交互对话框。
 - 运行中逐条显示待处理消息，可单条撤回并重新编辑；`Alt+Q` 可将全部队列消息恢复到输入框。
 - 会话历史保留完整分支与检查点，支持回溯后返回切换前的位置，以及 `pi-rewind` 文件恢复。
-- Windows 系统剪贴板图片和文本粘贴。
+- Windows 系统剪贴板图片和文本粘贴；手机支持选择或粘贴本机图片。
 - 会话中的本地文件链接可在右侧分栏预览，支持语法高亮、行定位和拖拽调整宽度。
 - 设置面板内更新扩展并热重载 Pi 运行时，无需退出 Web UI。
 - 会话 HTML 导出。
 
 ## 进程生命周期
 
-`/web --stop`、宿主 Pi 退出或运行时重载会关闭 Web 会话进程及其后代，包括 detached 后台进程；即使宿主被强制结束，Windows 托管进程也会检测到宿主退出并清理整棵进程树。不会扫描或结束工作区外独立启动的进程，也不会结束其他 Pi 实例。
+`/web --stop`、宿主 Pi 退出或运行时重载会关闭扩展托管的 frpc 和 Web 会话进程及其后代，包括 detached 后台进程；即使宿主被强制结束，Windows 托管进程也会检测到宿主退出并清理整棵进程树。不会扫描或结束工作区外独立启动的进程，也不会结束其他 Pi 实例。
 
 单个 RPC 进程退出、异常终止或被空闲进程回收时，它启动的后台进程也会一起结束。需要独立于会话长期运行的服务，应从 Web 会话之外的终端启动。通过系统服务管理器、计划任务等外部机制启动的进程不属于此进程树。
 
@@ -66,6 +111,10 @@ pi --web
 ~/.pi/agent/pi-web/state.json
 ```
 
+访问密码的加盐哈希和登录签名密钥保存在同一目录的 `auth.json` 中，不保存明文密码。
+
+访问模式及中转配置保存在同一目录的 `network.json` 中。中转所需的 frps 认证密钥、STCP 私有密钥和代理密钥保存在此文件；普通设置响应不返回这些密钥，服务器配置下载会包含部署所需的密钥。配置文件不属于发布包。运行时的 frpc 配置写入状态目录下的 `runtime/`，正常停止时清理。
+
 从旧版目录安装首次升级时，如果新位置尚无状态文件，扩展会从扩展目录中的旧 `state.json` 原样复制并继续使用。旧文件不会被删除或改写，可作为迁移备份。
 
 可用环境变量：

package/THIRD_PARTY_NOTICES.md

@@ -3,6 +3,10 @@
 This package contains adapted web UI styles and bundled font assets from the
 projects below. Their licenses are reproduced here as required.
 
+The browser Markdown renderer also bundles markdown-it and highlight.js with
+their dependencies. Their license texts are included in
+`web/assets/markdown.LICENSE.txt`, next to the bundled renderer.
+
 ## DeepSeek Harness
 
 Source: https://github.com/deepseek-ai/deepseek-harness

package/attachment-parser.ts

@@ -0,0 +1,210 @@
+import { extname, posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import { unzipSync } from "fflate";
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+
+const MAX_TEXT = 200_000;
+const MAX_XML_BYTES = 32 * 1024 * 1024;
+const OFFICE_MIME: Record<string, string> = {
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+
+type XmlNode = { [key: string]: XmlNode[] | Record<string, string> | string };
+const parser = new XMLParser({ preserveOrder: true, ignoreAttributes: false, attributeNamePrefix: "", parseTagValue: false, parseAttributeValue: false, trimValues: false });
+
+function tag(node: XmlNode): string {
+  return Object.keys(node).find((key) => key !== ":@") ?? "";
+}
+function children(node: XmlNode): XmlNode[] {
+  const value = node[tag(node)];
+  return Array.isArray(value) ? value : [];
+}
+function attr(node: XmlNode, name: string): string {
+  return (node[":@"] as Record<string, string> | undefined)?.[name] ?? "";
+}
+function find(nodes: XmlNode[], name: string): XmlNode[] {
+  const found: XmlNode[] = [];
+  for (const node of nodes) {
+    if (tag(node).split(":").at(-1) === name) found.push(node);
+    else found.push(...find(children(node), name));
+  }
+  return found;
+}
+function value(nodes: XmlNode[]): string {
+  return nodes.map((node) => tag(node) === "#text" ? String(node["#text"]) : value(children(node))).join("");
+}
+function runs(nodes: XmlNode[]): string {
+  return nodes.map((node) => {
+    const name = tag(node).split(":").at(-1);
+    if (name === "t") return value(children(node));
+    if (name === "tab") return "\t";
+    if (name === "br" || name === "cr") return "\n";
+    return runs(children(node));
+  }).join("");
+}
+function checked(text: string): string {
+  if (text.length > MAX_TEXT) throw new Error("解析文本超过 200000 字符，请拆分文件后上传");
+  return text;
+}
+function decode(bytes: Uint8Array): string {
+  const encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? "utf-16le"
+    : bytes[0] === 0xfe && bytes[1] === 0xff ? "utf-16be" : "utf-8";
+  try {
+    return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error("文件编码无效，仅支持 UTF-8 或带 BOM 的 UTF-16 文本");
+  }
+}
+
+function officeFiles(bytes: Uint8Array): Record<string, Uint8Array> {
+  let total = 0;
+  try {
+    const files = unzipSync(bytes, { filter(entry) {
+      if (!/\.(xml|rels)$/i.test(entry.name)) return false;
+      total += entry.originalSize;
+      if (total > MAX_XML_BYTES) throw new Error("Office XML 解压总量超过 32MB");
+      return true;
+    } });
+    if (Object.values(files).reduce((sum, file) => sum + file.length, 0) > MAX_XML_BYTES) throw new Error("Office XML 解压总量超过 32MB");
+    return files;
+  } catch (error) {
+    throw new Error(`无法解析 Office 压缩包：${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function xml(files: Record<string, Uint8Array>, path: string): XmlNode[] {
+  if (!files[path]) throw new Error(`Office 文件缺少 ${path}`);
+  const text = decode(files[path]);
+  if (/<!\s*(DOCTYPE|ENTITY)\b/i.test(text)) throw new Error("不支持含 DTD 或实体声明的 Office XML");
+  if (XMLValidator.validate(text) !== true) throw new Error(`Office XML 格式无效：${path}`);
+  return parser.parse(text) as XmlNode[];
+}
+function relationships(files: Record<string, Uint8Array>, source: string): Map<string, { path: string; type: string }> {
+  const relPath = posix.join(posix.dirname(source), "_rels", `${posix.basename(source)}.rels`);
+  const result = new Map<string, { path: string; type: string }>();
+  if (!files[relPath]) return result;
+  for (const rel of find(xml(files, relPath), "Relationship")) {
+    if (attr(rel, "TargetMode") === "External") continue;
+    const target = attr(rel, "Target");
+    const path = posix.normalize(target.startsWith("/") ? target.slice(1) : posix.join(posix.dirname(source), target));
+    if (path.startsWith("../") || path.includes("\\")) throw new Error("Office 关系路径无效");
+    result.set(attr(rel, "Id"), { path, type: attr(rel, "Type") });
+  }
+  return result;
+}
+function related(rels: ReturnType<typeof relationships>, id: string): string {
+  const rel = rels.get(id);
+  if (!rel) throw new Error(`Office 文件缺少内部关系：${id}`);
+  return rel.path;
+}
+function word(nodes: XmlNode[]): string {
+  return nodes.map((node) => {
+    const name = tag(node).split(":").at(-1);
+    if (name === "p") return `${runs(children(node))}\n`;
+    if (name === "tr") return `${find(children(node), "tc").map((cell) => word(children(cell)).trimEnd()).join("\t")}\n`;
+    return word(children(node));
+  }).join("");
+}
+function excel(files: Record<string, Uint8Array>): string {
+  const source = "xl/workbook.xml";
+  const rels = relationships(files, source);
+  const sharedPath = [...rels.values()].find((rel) => rel.type.endsWith("/sharedStrings"))?.path;
+  const shared = sharedPath ? find(xml(files, sharedPath), "si").map((node) => runs(children(node))) : [];
+  let text = "";
+  for (const sheet of find(xml(files, source), "sheet")) {
+    text = checked(`${text}工作表：${attr(sheet, "name")}\n`);
+    const root = xml(files, related(rels, attr(sheet, "r:id")));
+    for (const cell of find(root, "c")) {
+      const address = attr(cell, "r");
+      if (!/^[A-Z]+[1-9]\d*$/.test(address)) throw new Error("工作表单元格缺少有效坐标");
+      const type = attr(cell, "t");
+      let content = value(find(children(cell), "v"));
+      if (type === "s") {
+        if (!/^\d+$/.test(content) || shared[Number(content)] === undefined) throw new Error("工作表共享字符串索引无效");
+        content = shared[Number(content)];
+      } else if (type === "inlineStr") content = runs(children(cell));
+      else if (type === "b" && content) content = content === "1" ? "TRUE" : "FALSE";
+      text = checked(`${text}${address}: ${content}\n`);
+    }
+    text = checked(`${text}\n`);
+  }
+  return text.trimEnd();
+}
+function powerpoint(files: Record<string, Uint8Array>): string {
+  const source = "ppt/presentation.xml";
+  const rels = relationships(files, source);
+  let text = "";
+  let index = 0;
+  for (const slide of find(xml(files, source), "sldId")) {
+    const path = related(rels, attr(slide, "r:id"));
+    const content = find(xml(files, path), "p").map((node) => runs(children(node))).join("\n");
+    text = checked(`${text}幻灯片 ${++index}\n${content}\n`);
+    for (const rel of relationships(files, path).values()) {
+      if (rel.type.endsWith("/notesSlide")) {
+        const notes = find(xml(files, rel.path), "p").map((node) => runs(children(node))).join("\n");
+        text = checked(`${text}备注：\n${notes}\n`);
+      }
+    }
+    text = checked(`${text}\n`);
+  }
+  return text.trimEnd();
+}
+async function pdf(bytes: Uint8Array): Promise<string> {
+  const { getDocument } = await import("pdfjs-dist/legacy/build/pdf.mjs");
+  const packageUrl = import.meta.resolve("pdfjs-dist/package.json");
+  const task = getDocument({
+    data: Uint8Array.from(bytes),
+    useSystemFonts: true,
+    cMapUrl: fileURLToPath(new URL("./cmaps/", packageUrl)).replace(/\\/g, "/"),
+    cMapPacked: true,
+    standardFontDataUrl: fileURLToPath(new URL("./standard_fonts/", packageUrl)).replace(/\\/g, "/"),
+  });
+  try {
+    const document = await task.promise;
+    let text = "";
+    for (let index = 1; index <= document.numPages; index++) {
+      const page = await document.getPage(index);
+      try {
+        const content = await page.getTextContent();
+        for (const item of content.items) {
+          if ("str" in item) text = checked(text + item.str + (item.hasEOL ? "\n" : " "));
+        }
+        text = checked(`${text}\n`);
+      } finally {
+        page.cleanup();
+      }
+    }
+    if (!text.trim()) throw new Error("PDF 无可提取文本，可能是扫描件；当前不支持 OCR");
+    return text.trim();
+  } catch (error) {
+    if (error instanceof Error && error.name === "PasswordException") throw new Error("PDF 受密码保护，无法提取文本");
+    throw error;
+  } finally {
+    await task.destroy();
+  }
+}
+
+export async function parseDocument(bytes: Uint8Array, filename: string): Promise<{ text: string; mimeType: string }> {
+  const extension = extname(filename).toLowerCase();
+  if (/^\.(doc|xls|ppt|zip|rar|7z|gz|tar|mp3|mp4|wav|ogg|flac|aac|m4a|m4v|mov|avi|webm|mkv|wma|wmv|exe|dll|png|jpg|jpeg|gif|webp)$/.test(extension)) {
+    throw new Error("不支持此文件类型，请上传文本、PDF、DOCX、XLSX 或 PPTX");
+  }
+  if (Buffer.from(bytes.subarray(0, 8)).equals(Buffer.from([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]))) {
+    throw new Error("不支持旧版二进制 Office 或加密 Office 文件");
+  }
+  if (extension === ".pdf" || Buffer.from(bytes.subarray(0, 5)).toString("ascii") === "%PDF-") {
+    return { text: checked(await pdf(bytes)), mimeType: "application/pdf" };
+  }
+  if (OFFICE_MIME[extension]) {
+    const files = officeFiles(bytes);
+    const text = extension === ".docx" ? word(xml(files, "word/document.xml")).trimEnd()
+      : extension === ".xlsx" ? excel(files) : powerpoint(files);
+    return { text: checked(text), mimeType: OFFICE_MIME[extension] };
+  }
+  if (bytes[0] === 0x50 && bytes[1] === 0x4b) throw new Error("不支持 ZIP 压缩文件，请上传 DOCX、XLSX 或 PPTX");
+  const text = decode(bytes);
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(text)) throw new Error("文件包含二进制控制符，无法作为文本解析");
+  const mimeType = ({ ".json": "application/json", ".csv": "text/csv", ".md": "text/markdown", ".markdown": "text/markdown" } as Record<string, string>)[extension] ?? "text/plain";
+  return { text: checked(text), mimeType };
+}

package/attachment-store.ts

@@ -2,17 +2,22 @@ import { randomUUID } from "node:crypto";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { parseDocument } from "./attachment-parser.ts";
 
-export interface ImageAttachmentMeta {
+export interface AttachmentMeta {
   id: string;
+  kind: "image" | "document";
+  name: string;
+  textLength?: number;
   mimeType: string;
   size: number;
   createdAt: number;
   expiresAt: number;
 }
 
-interface StoredImageAttachment extends ImageAttachmentMeta {
+interface StoredAttachment extends AttachmentMeta {
   path: string;
+  text?: string;
   timer: ReturnType<typeof setTimeout>;
 }
 
@@ -43,53 +48,62 @@ function fallbackImageMimeType(bytes: Uint8Array): string | null {
   return null;
 }
 
-async function detectImageMimeType(path: string, bytes: Uint8Array): Promise<string | null> {
+export async function detectImageMimeType(path: string, bytes: Uint8Array): Promise<string | null> {
   const detector = await resolvePublicMimeDetector();
   return detector ? detector(path) : fallbackImageMimeType(bytes);
 }
 
-export interface ImageAttachmentStoreOptions {
+export interface AttachmentStoreOptions {
   directory?: string;
   ttlMs?: number;
   maxBytes?: number;
   maxPromptImages?: number;
+  maxPromptAttachments?: number;
 }
 
-export class ImageAttachmentStore {
+export class AttachmentStore {
   readonly maxPromptImages: number;
+  readonly maxPromptAttachments: number;
   private readonly directory: string;
   private readonly ttlMs: number;
   private readonly maxBytes: number;
-  private readonly entries = new Map<string, StoredImageAttachment>();
+  private readonly entries = new Map<string, StoredAttachment>();
 
-  constructor(options: ImageAttachmentStoreOptions = {}) {
+  constructor(options: AttachmentStoreOptions = {}) {
     this.directory = options.directory ?? tmpdir();
     this.ttlMs = options.ttlMs ?? 24 * 60 * 60 * 1000;
     this.maxBytes = options.maxBytes ?? 15 * 1024 * 1024;
     this.maxPromptImages = options.maxPromptImages ?? 4;
+    this.maxPromptAttachments = options.maxPromptAttachments ?? 8;
   }
 
-  async create(bytes: Uint8Array): Promise<ImageAttachmentMeta> {
-    if (bytes.byteLength === 0) throw new Error("图片内容为空");
+  async create(bytes: Uint8Array, filename?: string): Promise<AttachmentMeta> {
+    if (bytes.byteLength === 0) throw new Error("文件内容为空");
     if (bytes.byteLength > this.maxBytes) {
-      throw new Error(`图片不能超过 ${Math.floor(this.maxBytes / 1024 / 1024)} MB`);
+      throw new Error(`文件不能超过 ${Math.floor(this.maxBytes / 1024 / 1024)} MB`);
     }
 
     const id = randomUUID();
-    const path = join(this.directory, `pi-web-attachment-${id}.img`);
+    const path = join(this.directory, `pi-web-attachment-${id}.upload`);
+    const name = filename?.split(/[\\/]/).pop()?.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 255) || "";
     await writeFile(path, bytes);
     try {
-      const mimeType = await detectImageMimeType(path, bytes);
-      if (!mimeType) throw new Error("不支持的图片格式");
+      const imageMimeType = await detectImageMimeType(path, bytes);
+      if (!imageMimeType && !name) throw new Error("不支持的图片格式");
+      const document = imageMimeType ? undefined : await parseDocument(bytes, name);
+      const mimeType = imageMimeType || document!.mimeType;
       const createdAt = Date.now();
       const expiresAt = createdAt + this.ttlMs;
       const timer = setTimeout(() => {
         void this.remove(id);
       }, this.ttlMs);
       timer.unref();
-      const stored: StoredImageAttachment = {
+      const stored: StoredAttachment = {
         id,
         path,
+        kind: imageMimeType ? "image" : "document",
+        name: name || `图片.${mimeType.split("/")[1]}`,
+        ...(document ? { text: document.text, textLength: document.text.length } : {}),
         mimeType,
         size: bytes.byteLength,
         createdAt,
@@ -104,7 +118,7 @@ export class ImageAttachmentStore {
     }
   }
 
-  get(id: string): ImageAttachmentMeta | undefined {
+  get(id: string): AttachmentMeta | undefined {
     const stored = this.entries.get(id);
     if (!stored) return undefined;
     if (stored.expiresAt <= Date.now()) {
@@ -114,26 +128,52 @@ export class ImageAttachmentStore {
     return this.meta(stored);
   }
 
-  async read(id: string): Promise<{ meta: ImageAttachmentMeta; bytes: Buffer }> {
+  async read(id: string): Promise<{ meta: AttachmentMeta; bytes: Buffer }> {
     const stored = this.entries.get(id);
     if (!stored || stored.expiresAt <= Date.now()) {
       if (stored) await this.remove(id);
-      throw new Error("图片附件不存在或已过期");
+      throw new Error("附件不存在或已过期");
     }
     return { meta: this.meta(stored), bytes: await readFile(stored.path) };
   }
 
-  async imagesForRpc(ids: string[]): Promise<Array<{ type: "image"; data: string; mimeType: string }>> {
+  async promptForRpc(ids: string[], message: string): Promise<{
+    message: string;
+    images: Array<{ type: "image"; data: string; mimeType: string }>;
+  }> {
     const uniqueIds = [...new Set(ids)];
-    if (uniqueIds.length > this.maxPromptImages) {
+    if (uniqueIds.length > this.maxPromptAttachments) {
+      throw new Error(`每条消息最多附加 ${this.maxPromptAttachments} 个文件`);
+    }
+    const attachments = uniqueIds.map((id) => {
+      const stored = this.entries.get(id);
+      if (!stored || !this.get(id)) throw new Error("附件不存在或已过期，请重新上传");
+      return stored;
+    });
+    if (attachments.filter((entry) => entry.kind === "image").length > this.maxPromptImages) {
       throw new Error(`每条消息最多附加 ${this.maxPromptImages} 张图片`);
     }
+    if (attachments.reduce((length, entry) => length + (entry.textLength || 0), 0) > 200_000) {
+      throw new Error("附件文本总量不能超过 200000 字符，请拆分发送");
+    }
     const images = [];
-    for (const id of uniqueIds) {
-      const { meta, bytes } = await this.read(id);
-      images.push({ type: "image" as const, data: bytes.toString("base64"), mimeType: meta.mimeType });
+    const documents = [];
+    for (const attachment of attachments) {
+      if (attachment.kind === "image") {
+        const { meta, bytes } = await this.read(attachment.id);
+        images.push({ type: "image" as const, data: bytes.toString("base64"), mimeType: meta.mimeType });
+      } else {
+        const text = attachment.text!;
+        let fenceLength = 3;
+        for (const match of text.matchAll(/`+/g)) fenceLength = Math.max(fenceLength, match[0].length + 1);
+        const fence = "`".repeat(fenceLength);
+        documents.push(`附件：${JSON.stringify(attachment.name)}\n${fence}text\n${text}\n${fence}`);
+      }
     }
-    return images;
+    return {
+      message: [message.trim() || (documents.length ? "请分析附加文件。" : "请分析附加图片。"), ...documents].join("\n\n"),
+      images,
+    };
   }
 
   async remove(id: string): Promise<boolean> {
@@ -149,9 +189,12 @@ export class ImageAttachmentStore {
     await Promise.all([...this.entries.keys()].map((id) => this.remove(id)));
   }
 
-  private meta(stored: StoredImageAttachment): ImageAttachmentMeta {
+  private meta(stored: StoredAttachment): AttachmentMeta {
     return {
       id: stored.id,
+      kind: stored.kind,
+      name: stored.name,
+      ...(stored.textLength !== undefined ? { textLength: stored.textLength } : {}),
       mimeType: stored.mimeType,
       size: stored.size,
       createdAt: stored.createdAt,

package/background-jobs.ts

@@ -0,0 +1,52 @@
+import { open } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { stripAnsi, type RenderedMessage } from "./transcript.ts";
+
+export interface BackgroundJob {
+  id: string;
+  jobId: string;
+  name?: string;
+  command: string;
+  logPath: string;
+}
+
+export function collectBackgroundJobs(messages: RenderedMessage[]): BackgroundJob[] {
+  const jobs = new Map<string, BackgroundJob>();
+  for (const message of messages) {
+    for (const block of message.blocks ?? []) {
+      if (block.type !== "toolCall" || block.name !== "pwsh" || !block.id || block.result?.isError) continue;
+      const text = block.result?.content ?? "";
+      const started = /^Started background job (bg-\d+)\b/.exec(text);
+      const logPath = /Full log: ([^\r\n]+)$/.exec(text)?.[1].trim();
+      if (!started || !logPath || basename(logPath) !== `${started[1]}.log` || !basename(dirname(logPath)).startsWith("pi-pwsh-notify-")) continue;
+      const args = block.arguments && typeof block.arguments === "object" ? block.arguments as Record<string, unknown> : {};
+      // Job numbers restart with each extension instance; tool call IDs remain session-scoped.
+      jobs.set(block.id, {
+        id: block.id,
+        jobId: started[1],
+        name: typeof args.name === "string" ? args.name : undefined,
+        command: typeof args.command === "string" ? args.command : block.argumentsText ?? "",
+        logPath,
+      });
+    }
+  }
+  return [...jobs.values()].reverse();
+}
+
+export async function readBackgroundJobLog(logPath: string): Promise<{ output: string; truncated: boolean }> {
+  const file = await open(logPath, "r");
+  try {
+    const { size } = await file.stat();
+    const start = Math.max(0, size - 128 * 1024);
+    const buffer = Buffer.alloc(Math.min(size, 128 * 1024));
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, start);
+    let offset = 0;
+    if (start > 0) while (offset < bytesRead && (buffer[offset] & 0xc0) === 0x80) offset++;
+    const text = new StringDecoder("utf8").write(buffer.subarray(offset, bytesRead));
+    const lines = text.split("\n");
+    return { output: stripAnsi(lines.slice(-1000).join("\n")), truncated: start > 0 || lines.length > 1000 };
+  } finally {
+    await file.close();
+  }
+}

package/extension-settings.ts

@@ -0,0 +1,50 @@
+import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+type PackageEntry = ReturnType<SettingsManager["getPackages"]>[number];
+type ManagedPackage = Exclude<PackageEntry, string> & { piWebExtensionFilter?: string[] };
+
+export function togglePackage(entry: PackageEntry, enabled: boolean): PackageEntry {
+  const next: ManagedPackage = typeof entry === "string" ? { source: entry } : { ...entry };
+  const disabled = Array.isArray(next.extensions) && next.extensions.length === 0;
+  if (enabled === !disabled) return entry;
+  if (enabled) {
+    if (next.piWebExtensionFilter) next.extensions = next.piWebExtensionFilter;
+    else delete next.extensions;
+    delete next.piWebExtensionFilter;
+  } else {
+    if (next.extensions) next.piWebExtensionFilter = next.extensions;
+    next.extensions = [];
+  }
+  return next;
+}
+
+export async function extensionSettings(cwd: string, change?: { scope: "global" | "project"; source: string; enabled: boolean }, agentDir = getAgentDir()) {
+  const manager = SettingsManager.create(cwd, agentDir, { projectTrusted: true });
+  const checkErrors = () => {
+    const errors = manager.drainErrors();
+    if (errors.length) throw new Error(errors.map((item) => item.error.message).join("\n"));
+  };
+  checkErrors();
+  if (change) {
+    const settings = change.scope === "global" ? manager.getGlobalSettings() : manager.getProjectSettings();
+    const packages = settings.packages ?? [];
+    if (!packages.some((entry) => (typeof entry === "string" ? entry : entry.source) === change.source)) throw new Error("扩展包配置已变化，请刷新列表");
+    const next = packages.map((entry) => (typeof entry === "string" ? entry : entry.source) === change.source ? togglePackage(entry, change.enabled) : entry);
+    if (change.scope === "global") manager.setPackages(next);
+    else manager.setProjectPackages(next);
+    await manager.flush();
+    checkErrors();
+  }
+  return {
+    cwd,
+    packages: (["global", "project"] as const).flatMap((scope) => {
+      const settings = scope === "global" ? manager.getGlobalSettings() : manager.getProjectSettings();
+      return (settings.packages ?? []).map((entry) => ({
+        scope,
+        source: typeof entry === "string" ? entry : entry.source,
+        enabled: typeof entry === "string" || entry.extensions?.length !== 0,
+        filtered: typeof entry !== "string" && Boolean(entry.extensions?.length),
+      }));
+    }),
+  };
+}

package/file-preview.ts

@@ -55,6 +55,8 @@ export interface FilePreviewData {
   path: string;
   name: string;
   language: string;
+  kind: "code" | "markdown" | "html";
+  content?: string;
   highlighted: boolean;
   highlightedHtml: string;
   lineCount: number;
@@ -68,7 +70,9 @@ function escapeHtml(value: string): string {
 export function buildFilePreview(filePath: string, data: Buffer): FilePreviewData {
   const name = basename(filePath);
   const text = data.toString("utf8").replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
-  const language = LANGUAGES_BY_FILENAME[name.toLowerCase()] ?? LANGUAGES_BY_EXTENSION[extname(name).toLowerCase()] ?? "plaintext";
+  const extension = extname(name).toLowerCase();
+  const language = LANGUAGES_BY_FILENAME[name.toLowerCase()] ?? LANGUAGES_BY_EXTENSION[extension] ?? "plaintext";
+  const kind = language === "markdown" ? "markdown" : [".html", ".htm"].includes(extension) ? "html" : "code";
   const canHighlight = data.byteLength <= MAX_HIGHLIGHT_BYTES && Boolean(hljs.getLanguage(language));
   let highlightedHtml = escapeHtml(text);
   let highlighted = false;
@@ -86,6 +90,8 @@ export function buildFilePreview(filePath: string, data: Buffer): FilePreviewDat
     path: filePath,
     name,
     language,
+    kind,
+    ...(kind !== "code" ? { content: text } : {}),
     highlighted,
     highlightedHtml,
     lineCount: text.split("\n").length,