minimal-agent 0.8.2 → 0.10.0

package/skills/web-crawler/scripts/crawl.test.mjs

@@ -0,0 +1,204 @@
+/**
+ * crawl.test.mjs —— web-crawler 引擎单测（DI 假 fetch/写盘，不连真网）。
+ * 用 bun test 跑：bun test skills/web-crawler/scripts/crawl.test.mjs
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  canonicalizeUrl,
+  crawl,
+  decodeEntities,
+  extractJsonLd,
+  extractLinks,
+  extractMainImage,
+  extractOpenGraph,
+  extractTitle,
+  fallbackHtmlToMarkdown,
+  isAllowedByRobots,
+  looksJsRendered,
+  parseRobots,
+  shouldFollow,
+} from './crawl.mjs';
+
+describe('抽取纯函数', () => {
+  test('extractTitle 去标签解实体', () => {
+    expect(extractTitle('<title>Hello &amp; World</title>')).toBe('Hello & World');
+    expect(extractTitle('<p>no title</p>')).toBe('');
+  });
+
+  test('extractOpenGraph property/content 任意顺序', () => {
+    const html =
+      '<meta content="T" property="og:title"><meta property="og:image" content="/i.png">';
+    expect(extractOpenGraph(html)).toEqual({ 'og:title': 'T', 'og:image': '/i.png' });
+  });
+
+  test('extractJsonLd 解析、坏块跳过', () => {
+    const html =
+      '<script type="application/ld+json">{"@type":"Article","h":1}</script>' +
+      '<script type="application/ld+json">{bad</script>';
+    expect(extractJsonLd(html)).toEqual([{ '@type': 'Article', h: 1 }]);
+  });
+
+  test('extractLinks 相对地址按 base 解析 + 去重 + 过滤 mailto/#', () => {
+    const html =
+      '<a href="/a">A</a><a href="b">B</a><a href="/a">dup</a>' +
+      '<a href="#x">hash</a><a href="mailto:x@y">m</a><a href="https://o.test/z">O</a>';
+    expect(extractLinks(html, 'https://s.test/dir/').sort()).toEqual(
+      ['https://o.test/z', 'https://s.test/a', 'https://s.test/dir/b'].sort(),
+    );
+  });
+
+  test('extractMainImage 优先 og:image', () => {
+    expect(
+      extractMainImage('<img src="/x.png">', { 'og:image': 'https://s.test/og.png' }, 'https://s.test/'),
+    ).toBe('https://s.test/og.png');
+    expect(extractMainImage('<img src="/x.png">', {}, 'https://s.test/')).toBe('https://s.test/x.png');
+  });
+
+  test('decodeEntities + fallbackHtmlToMarkdown', () => {
+    expect(decodeEntities('a&amp;b&#39;c')).toBe("a&b'c");
+    const md = fallbackHtmlToMarkdown(
+      '<head><title>x</title></head><h1>Title</h1><p>Hello <a href="/u">link</a></p><script>junk()</script>',
+    );
+    expect(md).toContain('# Title');
+    expect(md).toContain('[link](/u)');
+    expect(md).not.toContain('junk');
+  });
+});
+
+describe('URL 规范化 / 域名 / robots', () => {
+  test('canonicalizeUrl 去 hash/tracking、host 小写、去末尾斜杠', () => {
+    expect(canonicalizeUrl('HTTPS://Site.TEST/a/?utm_source=x&q=1#frag')).toBe(
+      'https://site.test/a?q=1',
+    );
+    expect(canonicalizeUrl('https://site.test/')).toBe('https://site.test/'); // 根保留斜杠
+  });
+
+  test('canonicalizeUrl 去重等价：带不带 tracking/hash 归一', () => {
+    expect(canonicalizeUrl('https://s.test/p?utm_medium=ad')).toBe(
+      canonicalizeUrl('https://s.test/p#top'),
+    );
+  });
+
+  test('shouldFollow sameOrigin / allowDomains', () => {
+    expect(shouldFollow('https://s.test/x', { origin: 'https://s.test', sameOrigin: true })).toBe(true);
+    expect(shouldFollow('https://o.test/x', { origin: 'https://s.test', sameOrigin: true })).toBe(false);
+    expect(shouldFollow('https://sub.s.test/x', { allowDomains: ['s.test'] })).toBe(true);
+    expect(shouldFollow('https://o.test/x', { allowDomains: ['s.test'] })).toBe(false);
+  });
+
+  test('parseRobots + isAllowedByRobots', () => {
+    const rb = parseRobots('User-agent: *\nDisallow: /private\nCrawl-delay: 2\n# c\nDisallow: /tmp');
+    expect(rb.disallow).toEqual(['/private', '/tmp']);
+    expect(rb.crawlDelay).toBe(2);
+    expect(isAllowedByRobots('https://s.test/ok', rb)).toBe(true);
+    expect(isAllowedByRobots('https://s.test/private/x', rb)).toBe(false);
+  });
+
+  test('looksJsRendered：空壳 + app root → true；有正文 → false', () => {
+    expect(looksJsRendered('<div id="root"></div><script src="app.js"></script>')).toBe(true);
+    expect(
+      looksJsRendered(`<body><article>${'实质正文内容。'.repeat(40)}</article></body>`),
+    ).toBe(false);
+  });
+});
+
+// DI 假依赖：内存抓取 + 内存写盘
+function memDeps(pages) {
+  const writes = new Map();
+  return {
+    writes,
+    deps: {
+      renderImpl: async () => ({ ok: false, html: '' }),
+      mkdirImpl: async () => {},
+      writeFileImpl: async (p, c) => {
+        writes.set(p.replace(/\\/g, '/'), c);
+      },
+      fetchImpl: async (url) => {
+        const body = pages[url] ?? pages[url.replace(/\/$/, '')] ?? null;
+        if (body == null) return { ok: false, status: 404, body: '', url };
+        return { ok: true, status: 200, contentType: 'text/html', body, url };
+      },
+    },
+  };
+}
+
+describe('crawl 引擎（DI，不连真网）', () => {
+  test('single 模式：1 页、产 manifest + markdown', async () => {
+    const { writes, deps } = memDeps({
+      'https://s.test/': '<title>Home</title><h1>Home</h1><p>hi</p><a href="/a">A</a>',
+    });
+    const m = await crawl({ url: 'https://s.test/', mode: 'single', out: '/o', render: 'off' }, deps);
+    expect(m.mode).toBe('single');
+    expect(m.generated_pages).toBe(1);
+    expect(m.pages[0].title).toBe('Home');
+    expect([...writes.keys()]).toContain('/o/crawl.json');
+    expect([...writes.keys()].some((k) => /page_001\.md$/.test(k))).toBe(true);
+  });
+
+  test('site 模式：BFS + 去重 + 同域过滤 + depth/maxPages', async () => {
+    const { deps } = memDeps({
+      'https://s.test/':
+        '<title>Home</title><a href="/a">A</a><a href="/b">B</a><a href="https://o.test/x">ext</a>',
+      'https://s.test/a': '<title>A</title><a href="/b">B-dup</a><a href="/c">C</a>',
+      'https://s.test/b': '<title>B</title><p>leaf</p>',
+      'https://s.test/c': '<title>C</title><p>leaf</p>',
+      'https://s.test/robots.txt': 'User-agent: *\nDisallow: /private',
+    });
+    const m = await crawl(
+      {
+        url: 'https://s.test/',
+        mode: 'site',
+        out: '/o',
+        depth: 2,
+        maxPages: 20,
+        sameOrigin: true,
+        render: 'off',
+        delay: 0,
+      },
+      deps,
+    );
+    const urls = m.pages.filter((p) => p.file).map((p) => p.url).sort();
+    expect(urls).toEqual([
+      'https://s.test/',
+      'https://s.test/a',
+      'https://s.test/b',
+      'https://s.test/c',
+    ]);
+    // 外域不爬、/b 去重（只出现一次）
+    expect(urls.filter((u) => u === 'https://s.test/b').length).toBe(1);
+    expect(urls).not.toContain('https://o.test/x');
+  });
+
+  test('site 模式：maxPages 截断', async () => {
+    const { deps } = memDeps({
+      'https://s.test/': '<a href="/a">A</a><a href="/b">B</a><a href="/c">C</a>',
+      'https://s.test/a': '<p>a</p>',
+      'https://s.test/b': '<p>b</p>',
+      'https://s.test/c': '<p>c</p>',
+      'https://s.test/robots.txt': '',
+    });
+    const m = await crawl(
+      { url: 'https://s.test/', mode: 'site', out: '/o', depth: 2, maxPages: 2, sameOrigin: true, render: 'off', delay: 0 },
+      deps,
+    );
+    expect(m.generated_pages).toBe(2);
+  });
+
+  test('site 模式：robots Disallow 跳过', async () => {
+    const { deps } = memDeps({
+      'https://s.test/': '<a href="/private/secret">P</a><a href="/ok">OK</a>',
+      'https://s.test/ok': '<p>ok</p>',
+      'https://s.test/private/secret': '<p>secret</p>',
+      'https://s.test/robots.txt': 'User-agent: *\nDisallow: /private',
+    });
+    const m = await crawl(
+      { url: 'https://s.test/', mode: 'site', out: '/o', depth: 2, maxPages: 20, sameOrigin: true, render: 'off', delay: 0 },
+      deps,
+    );
+    const skipped = m.pages.find((p) => p.skipped === 'robots');
+    expect(skipped?.url).toBe('https://s.test/private/secret');
+    expect(m.pages.filter((p) => p.file).map((p) => p.url)).toContain('https://s.test/ok');
+  });
+});

package/skills/xlsx/SKILL.md

@@ -73,6 +73,10 @@ A user may ask you to create, edit, or analyze the contents of an .xlsx file. Yo
 
 **LibreOffice Required for Formula Recalculation**: You can assume LibreOffice is installed for recalculating formula values using the `scripts/recalc.py` script. The script automatically configures LibreOffice on first run, including in sandboxed environments where Unix sockets are restricted (handled by `scripts/office/soffice.py`)
 
+**OPC 合规是交付硬门槛**：.xlsx 本质是 OPC zip 包，Excel 打开时做严格 OPC 校验。交付前用
+`scripts/opc_check.py`（仅依赖 Python 标准库）做忠实合规校验（见 Common Workflow 第 7 步）——
+**不要**只用「openpyxl 能否重新打开」判断通过，那类库太宽容会放过损坏包。
+
 ## Reading and analyzing data
 
 ### Data analysis with pandas
@@ -147,6 +151,14 @@ This applies to ALL calculations - totals, percentages, ratios, differences, etc
      - `#DIV/0!`: Division by zero
      - `#VALUE!`: Wrong data type in formula
      - `#NAME?`: Unrecognized formula name
+7. **OPC 合规校验（硬门槛）**: 确认产物是干净的 OPC 包，Excel 能干净打开
+   ```bash
+   python scripts/opc_check.py output.xlsx
+   ```
+   openpyxl 从零创建通常产出合规包，但 recalc（经 LibreOffice）或第三方/Bun 工具链改写过的
+   文件可能引入不合规。**「某个库能 load/import ≠ Excel 能干净打开」**——openpyxl/pandas 很宽容，
+   会忽略 zip 目录条目等问题照样加载成功，**绝不要**拿「openpyxl 能否重新 load」当验证通过的判据。
+   退出码非 0 即不合规，按提示一步修回：`python scripts/opc_check.py output.xlsx --repack output.fixed.xlsx`。
 
 ### Creating new Excel files
 

package/skills/xlsx/scripts/opc_check.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+opc_check.py —— OOXML（pptx/docx/xlsx 本质都是 OPC zip 包）的「忠实合规校验 + 重打包」工具。
+
+为什么需要这个脚本？
+====================
+pptx/docx/xlsx 文件本质是一个遵循 OPC（Open Packaging Conventions, ECMA-376 第 2 部分）
+规范的 zip 包。PowerPoint / Word / Excel 打开文件时会做**严格的 OPC 校验**，任何一处不合规
+都可能被判「需要修复」、修复后内容丢失。
+
+但是——「某个库能 load/import ≠ 目标程序（PowerPoint/Word/Excel）能干净打开」。
+python-pptx / python-docx / openpyxl 这类库非常宽容：它们会忽略 zip 里的目录条目、不在乎
+[Content_Types].xml 是不是第一个条目，照样 load 成功。于是「用 python-pptx 重新打开来验证」
+会**误报通过**，让损坏的包溜过验收闸门（这正是本仓库踩过的坑：PptxGenJS 在 Bun 下用 JSZip
+产出含 19 个目录条目 + STORE 无压缩的非合规包，python-pptx 照常加载，PowerPoint 却判损坏）。
+
+因此本脚本**绝不依赖任何宽容的高层库**，只用标准库（zipfile / xml.etree / posixpath / re），
+直接从 zip 字节层面 + OPC 规范层面做校验，忠实于最终消费者（Office）。
+
+校验项（任一不合规 → 非零退出码 + 打印具体问题）
+================================================
+1. zip 里没有目录条目（条目名以 "/" 结尾的应为 0 个）。
+   —— Office 严格 OPC 校验不接受目录条目；JSZip/Bun 常错误地写入它们。
+2. [Content_Types].xml 是 zip 的第一个条目。
+   —— OPC 规范虽未强制顺序，但 Office 的快速解析依赖它在前；不在首位常触发「需要修复」。
+3. 所有 .rels 里的内部 Target（TargetMode != External）都能解析到真实存在的部件。
+   —— 悬空关系（指向不存在的部件）是最常见的「文件损坏」根因。
+4. 没有 0 字节的媒体文件（ppt/media/、word/media/、xl/media/ 下）。
+   —— 空图片 = 渲染失败 / 修复时被丢弃。
+5. 所有 .xml / .rels 都是良构（well-formed）XML。
+   —— 坏 XML 直接导致 Office 拒绝加载该部件。
+
+用法
+====
+    python opc_check.py <file>                 # 校验，合规退出 0，不合规退出 1
+    python opc_check.py <file> --verbose       # 同上，额外打印每项 PASSED 明细
+    python opc_check.py --repack <in> <out>    # OPC 重打包：把不合规包修回合规
+
+重打包（--repack）做了什么？
+===========================
+读入源包里所有**非目录**条目，按「[Content_Types].xml 第一、_rels/.rels 第二、其余其后」的
+顺序，用 DEFLATE 压缩重写一个干净 zip。这样即便生成器（如 Bun 下的 PptxGenJS）产出不合规包，
+也能一步修回合规——重打包后再跑一次校验即应全绿。
+"""
+
+import argparse
+import posixpath
+import re
+import sys
+import zipfile
+import xml.etree.ElementTree as ET
+
+# OPC 关系命名空间：.rels 文件里 <Relationship> 元素所在的命名空间，固定不变。
+RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+# 三大 OOXML 家族放媒体（图片等）的目录前缀，用于「0 字节媒体」检查。
+MEDIA_DIRS = ("ppt/media/", "word/media/", "xl/media/")
+
+CONTENT_TYPES = "[Content_Types].xml"
+
+
+def _normalize_part_target(rels_name: str, target: str) -> str:
+    """
+    把一条关系里的 Target 解析成「包内绝对部件名」（不带前导 /）。
+
+    OPC 里 .rels 的 Target 是相对于「该 .rels 所描述部件所在目录」的相对路径：
+    - 根关系 _rels/.rels 描述的是包根 → 基准目录是包根 ""。
+    - 部件关系 <dir>/_rels/<part>.xml.rels 描述的是 <dir>/<part>.xml → 基准目录是 <dir>。
+    Target 也可能以 "/" 开头表示「相对包根的绝对路径」。
+    返回归一化后的 posix 路径（用 posixpath，因为 zip 内部一律用正斜杠）。
+    """
+    if target.startswith("/"):
+        # 绝对路径：直接去掉前导斜杠即为部件名。
+        return target.lstrip("/")
+
+    # 求 .rels 的基准目录。rels_name 形如 "_rels/.rels" 或 "ppt/_rels/presentation.xml.rels"。
+    # 基准目录 = .rels 所在目录的父目录（因为 _rels 子目录描述的是其上一级里的部件）。
+    rels_dir = posixpath.dirname(rels_name)          # 如 "ppt/_rels"
+    base_dir = posixpath.dirname(rels_dir)           # 如 "ppt"（根关系时为 ""）
+    joined = posixpath.join(base_dir, target) if base_dir else target
+    # posixpath.normpath 处理 "../" 等相对段，得到干净的部件名。
+    return posixpath.normpath(joined)
+
+
+def check_compliance(path: str, verbose: bool = False) -> list:
+    """
+    对 OOXML 文件做忠实 OPC 合规校验，返回「问题列表」（空列表 = 合规）。
+    每个问题是一段人话描述的字符串，方便直接打印给用户/喂回 LLM 排障。
+    """
+    problems = []
+
+    # 先确认它确实是个 zip（OOXML 包损坏到连 zip 都不是时，这里就拦下）。
+    if not zipfile.is_zipfile(path):
+        return [f"不是合法的 zip 包（OOXML 文件本质必须是 zip）：{path}"]
+
+    with zipfile.ZipFile(path, "r") as zf:
+        infos = zf.infolist()
+        # namelist 保持 zip 物理顺序，用于「第一个条目」判定。
+        names = [i.filename for i in infos]
+
+        # 现存的所有「真实部件」名集合（排除目录条目），供关系 Target 解析时核对存在性。
+        present_parts = {i.filename for i in infos if not i.filename.endswith("/")}
+
+        # ---- 校验项 1：没有目录条目 ----
+        dir_entries = [n for n in names if n.endswith("/")]
+        if dir_entries:
+            problems.append(
+                "zip 含目录条目（OPC 不允许，Office 会判损坏）："
+                + ", ".join(dir_entries)
+            )
+        elif verbose:
+            print("PASSED [1] 无目录条目")
+
+        # ---- 校验项 2：[Content_Types].xml 是第一个条目 ----
+        if CONTENT_TYPES not in present_parts:
+            problems.append(f"缺少 {CONTENT_TYPES}（OPC 必备部件）")
+        elif names and names[0] != CONTENT_TYPES:
+            problems.append(
+                f"{CONTENT_TYPES} 不是 zip 的第一个条目（首位是 '{names[0]}'）；"
+                "Office 严格解析依赖它在最前，可用 --repack 修复"
+            )
+        elif verbose:
+            print(f"PASSED [2] {CONTENT_TYPES} 位于首位")
+
+        # ---- 校验项 5（先做，因为 3 要解析 .rels XML）：所有 .xml/.rels 良构 ----
+        # 把良构检查提前，能在解析 .rels 之前就把坏 XML 的部件挑出来，避免下面重复报错。
+        malformed = set()
+        for info in infos:
+            n = info.filename
+            if n.endswith("/"):
+                continue
+            if n.lower().endswith(".xml") or n.lower().endswith(".rels"):
+                try:
+                    ET.fromstring(zf.read(n))
+                except ET.ParseError as e:
+                    malformed.add(n)
+                    problems.append(f"XML 不良构（Office 无法加载该部件）：{n} —— {e}")
+        if verbose and not malformed:
+            print("PASSED [5] 所有 .xml/.rels 均为良构 XML")
+
+        # ---- 校验项 3：所有 .rels 内部 Target 都能解析到真实部件 ----
+        dangling = []
+        for info in infos:
+            n = info.filename
+            if not n.lower().endswith(".rels") or n in malformed:
+                continue
+            try:
+                root = ET.fromstring(zf.read(n))
+            except ET.ParseError:
+                continue  # 已在校验项 5 报过
+            for rel in root.iter("{%s}Relationship" % RELATIONSHIPS_NS):
+                # 外部关系（TargetMode="External"，如 URL/超链接）不要求包内存在，跳过。
+                if rel.get("TargetMode") == "External":
+                    continue
+                target = rel.get("Target")
+                if not target:
+                    continue
+                part = _normalize_part_target(n, target)
+                if part not in present_parts:
+                    dangling.append(f"{n} → Target '{target}'（解析为部件 '{part}'，不存在）")
+        if dangling:
+            problems.append(
+                "存在悬空关系（.rels 指向不存在的部件，Office 会判损坏）：\n  "
+                + "\n  ".join(dangling)
+            )
+        elif verbose:
+            print("PASSED [3] 所有内部关系 Target 均指向存在的部件")
+
+        # ---- 校验项 4：没有 0 字节媒体文件 ----
+        empty_media = [
+            i.filename
+            for i in infos
+            if (not i.filename.endswith("/"))
+            and i.file_size == 0
+            and any(i.filename.startswith(d) for d in MEDIA_DIRS)
+        ]
+        if empty_media:
+            problems.append(
+                "存在 0 字节媒体文件（空图片，渲染/修复时会被丢弃）："
+                + ", ".join(empty_media)
+            )
+        elif verbose:
+            print("PASSED [4] 媒体文件均非空")
+
+    return problems
+
+
+def repack(src: str, dst: str) -> None:
+    """
+    OPC 重打包：读入源包所有非目录条目，按 OPC 友好顺序用 DEFLATE 重写干净 zip。
+    顺序约定：[Content_Types].xml 第一 → _rels/.rels 第二 → 其余其后（保持源相对顺序）。
+    """
+    with zipfile.ZipFile(src, "r") as zin:
+        # 只取真实部件，丢弃所有目录条目（这正是修复非合规包的关键一步）。
+        parts = [(i.filename, zin.read(i.filename)) for i in zin.infolist()
+                 if not i.filename.endswith("/")]
+
+    def sort_key(item):
+        name = item[0]
+        if name == CONTENT_TYPES:
+            return (0, name)        # Content_Types 永远第一
+        if name == "_rels/.rels":
+            return (1, name)        # 根关系第二
+        return (2, name)            # 其余按名次序其后
+
+    parts.sort(key=sort_key)
+
+    with zipfile.ZipFile(dst, "w", compression=zipfile.ZIP_DEFLATED) as zout:
+        for name, data in parts:
+            # 显式指定 DEFLATE，杜绝源包里 STORE（无压缩）残留——Office 对 STORE 的兼容性更差。
+            zout.writestr(name, data, compress_type=zipfile.ZIP_DEFLATED)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="OOXML（pptx/docx/xlsx）忠实 OPC 合规校验 + 重打包工具（仅依赖标准库）"
+    )
+    parser.add_argument("file", help="要校验的 OOXML 文件（或 --repack 模式下的输入文件）")
+    parser.add_argument(
+        "--repack",
+        metavar="OUT",
+        help="重打包模式：把 file 修回合规并写到 OUT（例：--repack fixed.pptx）",
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="打印每项 PASSED 明细")
+    args = parser.parse_args()
+
+    if args.repack:
+        repack(args.file, args.repack)
+        # 重打包后立刻自检，确保产物确实合规，否则别假装成功。
+        problems = check_compliance(args.repack, verbose=args.verbose)
+        if problems:
+            print(f"重打包到 {args.repack} 后仍存在 {len(problems)} 个问题：")
+            for p in problems:
+                print("  - " + p)
+            return 1
+        print(f"重打包完成且合规：{args.repack}")
+        return 0
+
+    problems = check_compliance(args.file, verbose=args.verbose)
+    if problems:
+        print(f"OPC 合规校验 FAILED —— {args.file} 存在 {len(problems)} 类问题：")
+        for p in problems:
+            print("  - " + p)
+        print("提示：可用 `python opc_check.py <in> --repack <out>` 一步修回合规。")
+        return 1
+
+    print(f"OPC 合规校验 PASSED —— {args.file} 是干净的 OPC 包，可被 Office 安全打开。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/advisorState.js

@@ -0,0 +1,22 @@
+/**
+ * ============================================================
+ *  src/advisorState.ts —— 顾问模型（Advisor 工具）开关状态
+ * ------------------------------------------------------------
+ *  模块级单例，镜像 askBridge.ts::setAskHandler 的简单风格——这不是按请求
+ *  隔离的状态（不需要 AsyncLocalStorage），TUI 单进程单会话场景下一个
+ *  进程内全局开关就够用。
+ *
+ *  默认 true：用户配置了 5 个 ADVISOR_AGENT_* 环境变量本身就是"我要用"的
+ *  信号，/advisor off 是需要时的临时关闭手段。
+ *
+ *  纯内存，不落盘——进程重启即重置为默认值（与 sessionState.ts 的
+ *  "运行时态、不持久化"定位一致）。
+ * ============================================================
+ */
+let enabled = true;
+export function isAdvisorEnabled() {
+    return enabled;
+}
+export function setAdvisorEnabled(value) {
+    enabled = value;
+}

package/src/askBridge.js

@@ -21,7 +21,10 @@
  *      绝不挂起（保 `-p` 单行 JSON 契约 + 子进程不卡死）。
  * ============================================================
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 let handler = null;
+const askHandlerScope = new AsyncLocalStorage();
+const askSourceScope = new AsyncLocalStorage();
 /**
  * 注册 / 注销 UI 处理器。
  * TUI 的 useChat 在 mount 时注册、unmount 时传 null 注销。
@@ -30,9 +33,79 @@ let handler = null;
 export function setAskHandler(h) {
     handler = h;
 }
+/** 在某个异步调用链里临时覆盖 Ask handler（Web/Gateway 多 turn 并发宿主用）。 */
+export function withAskHandler(h, fn) {
+    return askHandlerScope.run(h, fn);
+}
+/** 给嵌套 Agent 的提问附上来源，并允许执行器暂停/恢复自身超时预算。 */
+export function withAskSource(source, lifecycle, fn) {
+    return askSourceScope.run({ source, ...lifecycle }, fn);
+}
+/**
+ * 把任意宿主 handler 包装为单活跃 FIFO 队列。队列实例必须按顶层回合创建，
+ * 不能做模块级单例，否则不同用户/Session 会互相阻塞。
+ */
+export function createAskCoordinator(base, onStatus) {
+    const queue = [];
+    let active = false;
+    const refreshQueuedPositions = () => {
+        queue.forEach((entry, index) => onStatus?.({
+            source: entry.source,
+            state: 'queued',
+            queuePosition: index + 1,
+            queuedCount: queue.length,
+        }));
+    };
+    const pump = () => {
+        if (active)
+            return;
+        const entry = queue.shift();
+        if (!entry)
+            return;
+        active = true;
+        entry.abort?.();
+        onStatus?.({ source: entry.source, state: 'waiting', queuedCount: queue.length });
+        refreshQueuedPositions();
+        void base(entry.questions, entry.signal, entry.source, entry.control).then((answers) => {
+            onStatus?.({ source: entry.source, state: 'answered', queuedCount: queue.length });
+            entry.resolve(answers);
+        }, (error) => {
+            onStatus?.({ source: entry.source, state: 'cancelled', queuedCount: queue.length });
+            entry.reject(error instanceof Error ? error : new Error(String(error)));
+        }).finally(() => {
+            active = false;
+            pump();
+        });
+    };
+    return (questions, signal, source = { kind: 'main' }, control) => new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException('aborted', 'AbortError'));
+            return;
+        }
+        const entry = { questions, signal, source, control, resolve, reject };
+        const onAbort = () => {
+            const index = queue.indexOf(entry);
+            if (index < 0)
+                return; // active entry is cancelled by the base handler's signal
+            queue.splice(index, 1);
+            onStatus?.({ source, state: 'cancelled', queuedCount: queue.length });
+            reject(new DOMException('aborted', 'AbortError'));
+            refreshQueuedPositions();
+        };
+        if (signal) {
+            signal.addEventListener('abort', onAbort, { once: true });
+            entry.abort = () => signal.removeEventListener('abort', onAbort);
+        }
+        queue.push(entry);
+        if (active) {
+            onStatus?.({ source, state: 'queued', queuePosition: queue.length, queuedCount: queue.length });
+        }
+        pump();
+    });
+}
 /** 是否有交互 UI 在场（测试 / 诊断用）。 */
 export function hasAskHandler() {
-    return handler !== null;
+    return askHandlerScope.getStore() !== undefined || handler !== null;
 }
 /**
  * 向用户提问，返回答案。
@@ -41,11 +114,32 @@ export function hasAskHandler() {
  * - 无 handler（非交互宿主）→ 自动选每题首项（约定=推荐），stderr 注记，不挂起。
  */
 export async function requestUserChoice(questions, signal) {
-    if (handler)
-        return handler(questions, signal);
+    const scope = askSourceScope.getStore();
+    const scoped = askHandlerScope.getStore();
+    if (scoped || handler) {
+        scope?.onWaitStart?.();
+        try {
+            return await (scoped ?? handler)(questions, signal, scope?.source, {
+                cancelSource: () => scope?.onCancel?.(),
+            });
+        }
+        finally {
+            scope?.onWaitEnd?.();
+        }
+    }
     // 非交互兜底
     return questions.map((q) => {
         const pick = q.options[0]?.label ?? '';
+        // 约定校验：askBridge.ts:25 JSDoc 说"把推荐项放在第一个，并在 label 末尾标「(推荐)」。
+        // 若首项 label 不含 "(推荐)"，stderr 注记一下——上游作者违反约定
+        // （用户被自动套上非推荐路径是糟糕的体验）
+        const firstOpt = q.options[0];
+        if (firstOpt && !firstOpt.label.includes('(推荐)')) {
+            try {
+                process.stderr.write(`[AskUserQuestion·非交互] "${q.header}" 首项 label "${firstOpt.label}" 不含「(推荐)」标记——非交互宿主会按首项兜底，违反 promptAssembly 里的提问克制约定\n`);
+            }
+            catch { /* ignore */ }
+        }
         try {
             process.stderr.write(`[AskUserQuestion·非交互] "${q.header}" 无 UI，自动选推荐项："${pick}"\n`);
         }

package/src/bootstrap/workingDir.js

@@ -11,8 +11,10 @@
  *    - 环境变量覆盖 MINIMAL_AGENT_CWD：测试 / docker / 显式 cd 场景
  * ============================================================
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { resolve } from 'node:path';
 let _workingDir = null;
+const workingDirScope = new AsyncLocalStorage();
 /** 首次调用锁定 cwd（解析 MINIMAL_AGENT_CWD），重复调用幂等。 */
 export function initWorkingDir() {
     if (_workingDir !== null)
@@ -23,7 +25,16 @@ export function initWorkingDir() {
 }
 /** 读取已锁定的工作目录；尚未 init 时退到 lazy init（主要给测试）。 */
 export function getWorkingDir() {
-    return _workingDir ?? initWorkingDir();
+    return workingDirScope.getStore() ?? _workingDir ?? initWorkingDir();
+}
+/** TUI idle-only workspace switch. Callers must reject switching during a turn. */
+export function setWorkingDir(cwd) {
+    _workingDir = resolve(cwd);
+    return _workingDir;
+}
+/** 在同一进程的某个异步调用链里临时覆盖工作目录（HTTP/Gateway 多工作区宿主用）。 */
+export function withWorkingDir(cwd, fn) {
+    return workingDirScope.run(resolve(cwd), fn);
 }
 /** 仅供测试：重置 module-level state */
 export function _resetWorkingDir() {