dsh-tabbit 0.2.3 → 0.3.2

package/lib/update-check.js

@@ -0,0 +1,343 @@
+/*
+ * ============================================================================
+ * 文件职责：插件自身的「每日更新检查」——纯逻辑层
+ * ============================================================================
+ *
+ * 出处：自 github:Tabbit-Browser/dsh-tabbit（本包 npm 0.2.x 世代）的
+ * update-check.js 移植。0.2.x 起线上用户就带着这套机制：skill 每次加载时
+ * 顺带比对「已装版本 vs 发布仓库 CHANGELOG.md 的最新版本段」，有新版就在
+ * skill 正文顶部插一段更新通知，由模型转告用户并询问是否升级。
+ * 【0.3.0 起 CHANGELOG 的最新段落就是老用户看到的升级文案】——写它时开头
+ * 500 字符要能独立成文（见 truncateChangelog 的截断规则）。
+ *
+ * 设计约束（缓存/退避/拒绝记忆沿袭 0.2.x，保证升级用户行为连续）：
+ *  - 每天最多查一轮：成功结果缓存 24 小时；失败也静默退避 24 小时
+ *    （离线用户不该每次会话都白等超时）；
+ *  - 【更新源自 0.3.0 起改为 npm】
+ *  - 用户拒绝过的版本记下来不再重复announce（更新的版本出现才再提）；
+ *  - 缓存文件路径【必须与 0.2.x 相同】（XDG 缓存下 tabbit-dsh/），
+ *    这样 0.2.x → 0.3.x 升级后 dismissed 记录、退避状态原样继续生效。
+ *
+ * 本文件是纯逻辑（不依赖任何 dsh 包），两处接线在别的文件：
+ *  - core/index.ts 的 skill provider：get() 返回正文前调 prependUpdateNotice；
+ *  - installer/index.ts：注册 `tabbit_plugin_update` 工具（记录拒绝/强制重查）。
+ *
+ * 【浏览器托管形态的静默】：Tabbit Browser 预装（vendored）形态下插件版本
+ * 由浏览器随自身更新管理，若照通知里的 `dsh plugin add` 跑一遍，会把浏览器
+ * 托管的安装覆盖成 npm 版、脱离浏览器的版本管理。嵌入形态的权威信号是
+ * 浏览器启动 dsh 时注入的 TABBIT_PLAYWRIGHT_INSTANCE 环境变量——检测到它
+ * 就整套静默（不发请求、不插通知；用户手动设了该变量的极小众场景会被误伤，
+ * 代价可接受）。
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const DAY_MS = 24 * 60 * 60 * 1000;
+/* 单个网络请求限时 1.5 秒：更新检查是锦上添花，绝不能拖慢 skill 加载。
+ * 最坏路径是两个串行请求（有新版时才有第二个），每天最多一轮。 */
+const FETCH_TIMEOUT_MS = 1500;
+/* 通知里塞给模型的变更摘要上限（CHANGELOG 版本段压平空白后截断到此长度）。 */
+const CHANGELOG_MAX_CHARS = 500;
+/*
+ * 版本真相源：npm registry 的 latest 版本清单（标准公开端点，无需鉴权、
+ * 无 GitHub API 式的匿名配额问题）。可用环境变量 TABBIT_PLUGIN_UPDATE_URL
+ * 覆盖（测试/私有镜像用；覆盖的是这个 JSON 清单地址）。
+ * 注意：0.2.x 存量安装轮询的是旧仓库 Tabbit-Browser/dsh-tabbit main 的
+ * raw CHANGELOG.md——想通知到他们，旧仓库的 CHANGELOG.md 需要镜像新版本段
+ * （见 AGENTS.md 的发布流程）。
+ */
+const DEFAULT_MANIFEST_URL = 'https://registry.npmjs.org/dsh-tabbit/latest';
+/* 变更说明源：jsdelivr 按版本锚定的发布 tarball 内 CHANGELOG.md（锚定 URL
+ * 内容不可变、可永久缓存；解析新鲜度由上面的 registry 清单保证）。 */
+function defaultChangelogUrl(version) {
+    return `https://cdn.jsdelivr.net/npm/dsh-tabbit@${encodeURIComponent(version)}/CHANGELOG.md`;
+}
+/* 本包 package.json 的位置（编译后本文件在 lib/ 下，包根在上一级）。 */
+const PACKAGE_URL = new URL('../package.json', import.meta.url);
+/* 进程级缓存已读到的本包版本（null = 读过但失败，undefined = 还没读过）。 */
+let cachedLocalVersion;
+/* "1.9.2" / "v1.9" → [1,9,2]；解析不出（空/乱格式）→ undefined。 */
+function numericVersion(version) {
+    const match = String(version ?? '').trim().match(/^v?(\d+(?:\.\d+)*)/i);
+    return match?.[1] !== undefined ? match[1].split('.').map(Number) : undefined;
+}
+/*
+ * 数字段逐段比较两个版本号：1 = left 新，-1 = right 新，0 = 相等；
+ * 任一方解析不出 → undefined（调用方把 undefined 当"不可比、不提示"处理）。
+ */
+export function compareVersions(left, right) {
+    const leftParts = numericVersion(left);
+    const rightParts = numericVersion(right);
+    if (!leftParts || !rightParts)
+        return undefined;
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index += 1) {
+        const a = leftParts[index] ?? 0;
+        const b = rightParts[index] ?? 0;
+        if (a !== b)
+            return a > b ? 1 : -1;
+    }
+    return 0;
+}
+/* 压平所有空白（含换行）为单个空格——CHANGELOG 段落要塞进单行通知。 */
+export function flattenChangelog(text) {
+    return String(text ?? '').replace(/\s+/g, ' ').trim();
+}
+/* 压平后截断到 500 字符（尾部加省略号）。 */
+export function truncateChangelog(text) {
+    const value = flattenChangelog(text);
+    if (value.length <= CHANGELOG_MAX_CHARS)
+        return value;
+    return `${value.slice(0, CHANGELOG_MAX_CHARS - 1).trimEnd()}…`;
+}
+/*
+ * 从 CHANGELOG.md 全文里抠出【最新一个版本段】：
+ * 找第一个 `## <版本号>` 标题行，取它到下一个 `## ` 之间的内容作为变更摘要。
+ * 没有版本标题 = 文件坏了，抛错（调用方把抛错当"检查失败"静默处理）。
+ */
+export function parseLatestChangelog(markdown) {
+    const match = String(markdown ?? '').match(/^## +(v?\d+(?:\.\d+)+).*$/m);
+    if (!match || match.index === undefined)
+        throw new Error('Latest changelog has no version heading.');
+    const version = numericVersion(match[1])?.join('.');
+    if (version === undefined)
+        throw new Error('Latest changelog heading has no usable version.');
+    const sectionStart = match.index + match[0].length;
+    const rest = String(markdown).slice(sectionStart);
+    const nextSection = rest.search(/^## +/m);
+    const section = nextSection === -1 ? rest : rest.slice(0, nextSection);
+    return { version, changelog: truncateChangelog(section) };
+}
+/*
+ * 缓存文件的默认位置（【与 0.2.x 完全一致】，保证升级后状态连续）：
+ *   XDG_CACHE_HOME（设了就用）> Windows 的 LOCALAPPDATA > ~/.cache，
+ * 之下 tabbit-dsh/update-check.json。
+ */
+export function defaultCacheFile(env = process.env, platform = process.platform) {
+    const base = env.XDG_CACHE_HOME ||
+        (platform === 'win32' ? env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local') : undefined) ||
+        join(homedir(), '.cache');
+    return join(base, 'tabbit-dsh', 'update-check.json');
+}
+/* 读本包已安装版本（package.json 的 version；读不到 → undefined，检查报 unknown）。 */
+export async function readLocalVersion() {
+    if (cachedLocalVersion !== undefined)
+        return cachedLocalVersion ?? undefined;
+    try {
+        const parsed = JSON.parse(await readFile(PACKAGE_URL, 'utf8'));
+        cachedLocalVersion = typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        cachedLocalVersion = null;
+    }
+    return cachedLocalVersion ?? undefined;
+}
+export async function readCachedCheck(cacheFile) {
+    try {
+        const parsed = JSON.parse(await readFile(cacheFile, 'utf8'));
+        return parsed !== null && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function writeCachedCheck(cacheFile, state) {
+    await mkdir(dirname(cacheFile), { recursive: true });
+    await writeFile(cacheFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/* 限时取回一个 URL 的完整文本（含响应体读取都在超时保护内）。 */
+async function fetchTextWithTimeout(url, timeoutMs, fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, { signal: controller.signal });
+        if (!response.ok)
+            throw new Error(`Update check failed with HTTP ${response.status}.`);
+        return await response.text();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/*
+ * 从 CHANGELOG 全文抠出【指定版本】的段落（压平+截断后返回）。
+ * 与 parseLatestChangelog（取最新段）的分工：这里按 registry 报的版本精确
+ * 定位——锚定 tarball 里最新段理应就是该版本，但万一发布时忘了加条目、
+ * 或段落顺序有误，精确匹配能避免把别的版本的说明安到这个版本头上。
+ * 精确段缺失时退回"最新段"，且仅当最新段的版本号与目标一致才采用；
+ * 都不成立返回 undefined（通知降级为无摘要）。
+ */
+export function changelogSectionFor(markdown, version) {
+    const source = String(markdown ?? '');
+    const escaped = version.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    const heading = source.match(new RegExp(`^## +v?${escaped}(?!\\S).*$`, 'm'));
+    if (heading !== null && heading.index !== undefined) {
+        const rest = source.slice(heading.index + heading[0].length);
+        const next = rest.search(/^## +/m);
+        const section = truncateChangelog(next === -1 ? rest : rest.slice(0, next));
+        return section !== '' ? section : undefined;
+    }
+    try {
+        const latest = parseLatestChangelog(source);
+        if (compareVersions(latest.version, version) === 0 && latest.changelog !== '')
+            return latest.changelog;
+    }
+    catch {
+        // 整个文件没有版本标题：没有可用摘要。
+    }
+    return undefined;
+}
+/*
+ * 取最新发布：
+ *  1. 问 npm registry latest 清单拿版本号（版本真相，失败即整个检查失败、
+ *     进入 24h 退避）；
+ *  2. 只有确认比已装新，才去 jsdelivr 拉【该版本锚定】的 CHANGELOG.md 抠
+ *     对应段落——这步任何失败都只降级为"无摘要"，绝不挡升级提示（jsdelivr
+ *     在部分网络环境下可达性弱于 registry，不能让它拖垮主通道）。
+ */
+export async function fetchLatestRelease({ manifestUrl = process.env.TABBIT_PLUGIN_UPDATE_URL || DEFAULT_MANIFEST_URL, changelogUrlFor = defaultChangelogUrl, timeoutMs = FETCH_TIMEOUT_MS, fetchImpl = fetch, currentVersion, } = {}) {
+    const manifest = JSON.parse(await fetchTextWithTimeout(manifestUrl, timeoutMs, fetchImpl));
+    const version = typeof manifest.version === 'string' ? manifest.version.trim() : '';
+    if (numericVersion(version) === undefined)
+        throw new Error('npm manifest has no usable version.');
+    if (currentVersion !== undefined && compareVersions(version, currentVersion) !== 1)
+        return { version };
+    try {
+        const changelog = changelogSectionFor(await fetchTextWithTimeout(changelogUrlFor(version), timeoutMs, fetchImpl), version);
+        return changelog !== undefined ? { version, changelog } : { version };
+    }
+    catch {
+        return { version };
+    }
+}
+function isRecent(timestamp, now) {
+    return typeof timestamp === 'number' && now - timestamp < DAY_MS;
+}
+/*
+ * 把"已装版本 + 已知最新版本 + 拒绝记录"归纳成结论：
+ *  - 任一版本缺失/不可比 → unknown（静默，不打扰）；
+ *  - 最新 ≤ 已装，或最新恰是用户拒绝过的 → current；
+ *  - 否则 → update-available（带变更摘要）。
+ */
+export function summarizeUpdate({ currentVersion, latestVersion, changelog, dismissedVersion, }) {
+    if (currentVersion === undefined || latestVersion === undefined)
+        return { status: 'unknown', currentVersion };
+    if (compareVersions(latestVersion, currentVersion) !== 1 || latestVersion === dismissedVersion) {
+        return { status: 'current', currentVersion, latestVersion };
+    }
+    return { status: 'update-available', currentVersion, latestVersion, changelog };
+}
+function summaryFromCache(currentVersion, cached) {
+    return summarizeUpdate({
+        currentVersion,
+        latestVersion: cached.latestVersion,
+        changelog: cached.changelog,
+        dismissedVersion: cached.dismissedVersion,
+    });
+}
+async function fetchAndCacheRelease({ currentVersion, cached, cacheFile, now, fetchRelease, }) {
+    const state = { ...cached, lastAttemptAt: now };
+    try {
+        const release = await fetchRelease({ currentVersion });
+        state.checkedAt = now;
+        state.latestVersion = release.version;
+        // 有意整体覆盖（包括写入 undefined→序列化时丢弃）：旧版本的摘要绝不能
+        // 残留下来配错到新版本号头上。
+        state.changelog = release.changelog;
+    }
+    catch {
+        // 保留 lastAttemptAt：失败也静默退避一天再试（离线用户不被反复拖慢）。
+    }
+    try {
+        await writeCachedCheck(cacheFile, state);
+    }
+    catch {
+        // 缓存目录只读等写失败不影响本次结论（只是下次会重查）。
+    }
+    return summaryFromCache(currentVersion, state);
+}
+/*
+ * 检查主入口。非 force 时的省流顺序：
+ *  1. 24 小时内成功查过 → 直接用缓存归纳；
+ *  2. 24 小时内失败过 → unknown（退避中，不发请求）；
+ *  3. 否则才真正发请求并写缓存。
+ */
+export async function checkPluginUpdate({ now = Date.now(), cacheFile = defaultCacheFile(), fetchRelease = fetchLatestRelease, readVersion = readLocalVersion, force = false, } = {}) {
+    const currentVersion = await readVersion();
+    const cached = await readCachedCheck(cacheFile);
+    if (!force) {
+        if (isRecent(cached.checkedAt, now) && cached.latestVersion !== undefined) {
+            return summaryFromCache(currentVersion, cached);
+        }
+        if (isRecent(cached.lastAttemptAt, now)) {
+            return { status: 'unknown', currentVersion };
+        }
+    }
+    return fetchAndCacheRelease({ currentVersion, cached, cacheFile, now, fetchRelease });
+}
+/* 记录"用户拒绝了这个版本"（skill 从此不再announce它；更新的版本出现才再提）。 */
+export async function dismissUpdate(version, { cacheFile = defaultCacheFile() } = {}) {
+    const cached = await readCachedCheck(cacheFile);
+    const state = { ...cached, dismissedVersion: String(version ?? '').trim() };
+    await writeCachedCheck(cacheFile, state);
+    return state;
+}
+/*
+ * 浏览器托管形态判定（见文件头）：TABBIT_PLAYWRIGHT_INSTANCE 是浏览器启动
+ * 嵌入 dsh 时注入的权威通道，出现即认为插件版本归浏览器管、整套更新检查静默。
+ */
+export function isBrowserManagedInstall(env = process.env) {
+    const value = env.TABBIT_PLAYWRIGHT_INSTANCE;
+    return value !== undefined && value !== '';
+}
+/*
+ * 生成插到 skill 正文顶部的更新通知（Markdown 引用块）。
+ * 【只用本地模板拼接】：changelog 摘要来自我们自己仓库的 CHANGELOG，且以
+ * 数据形式呈现——通知里的行动指令（问用户、跑哪条命令、怎么 dismiss）全部
+ * 是这里硬编码的模板文字，摘要影响不了指令本身。
+ */
+export function formatUpdateNotice({ currentVersion, latestVersion, changelog, }) {
+    return [
+        `> **Plugin update available**: dsh-tabbit ${latestVersion} (installed ${currentVersion}).`,
+        changelog !== undefined && changelog !== '' ? `> New in ${latestVersion}: ${changelog}` : null,
+        '> Show the offered version and these changes to the user, then ask whether to update now.',
+        '> If they agree, tell them to rerun the install command below over the current install and restart the DSH session afterwards:',
+        '> ```bash',
+        '> dsh plugin --profile web add dsh-tabbit',
+        '> ```',
+        `> If they decline, call \`tabbit_plugin_update\` with \`dismiss: "${latestVersion}"\`, then continue the task.`,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/*
+ * 给 skill 正文加前缀通知（core 的 skill provider get() 调用）：
+ *  - 浏览器托管形态：原样返回（版本归浏览器管，见文件头）；
+ *  - 检查抛错/没有新版：原样返回；
+ *  - 有新版：通知 + 空行 + 原正文。
+ */
+export async function prependUpdateNotice(content, checkUpdate = checkPluginUpdate, env = process.env) {
+    if (isBrowserManagedInstall(env))
+        return content;
+    let update;
+    try {
+        update = await checkUpdate();
+    }
+    catch {
+        return content;
+    }
+    if (update.status !== 'update-available')
+        return content;
+    return `${formatUpdateNotice(update)}\n\n${content}`;
+}
+/* `tabbit_plugin_update` 工具的结果文案（installer/index.ts 注册处调用）。 */
+export function messageForUpdate(update) {
+    if (update.status === 'update-available') {
+        const changes = update.changelog !== undefined && update.changelog !== '' ? update.changelog : 'see the release notes';
+        return `dsh-tabbit ${update.latestVersion} is available (installed ${update.currentVersion}). New in this version: ${changes}. Ask the user whether to update now.`;
+    }
+    if (update.status === 'current') {
+        return `The dsh-tabbit plugin is up to date (${update.currentVersion}).`;
+    }
+    return 'Could not determine the latest dsh-tabbit plugin version. The check stays silent for a day before retrying.';
+}

package/lib/web-fetch/index.js

@@ -0,0 +1,219 @@
+/*
+ * ============================================================================
+ * 文件职责：浏览器代理的 `web_fetch` provider
+ * ============================================================================
+ *
+ * 为什么存在（背景知识）：dsh 内置了 `web_fetch` 工具（模型抓网页正文用），
+ * 并自 0.1.2-alpha.1 起自带一个匿名直连的 HTTP 抓取 provider
+ * （@deepseek-ai/dsh-web-fetch-http，id `http`）：先解析域名、要求答案全部
+ * 是公网单播才放行，再把连接钉在验证过的 IP 上直连。这套 SSRF 防护很严谨，
+ * 但对真实网页力不从心——无 JS 渲染、无登录态、不走系统代理；在 fake-ip
+ * 模式代理的机器上（国内常见），一切域名都解析进保留网段，它会把所有请求
+ * 判成"非公网 IP"拒绝（WEB_BLOCKED_URL）。dsh 的 `ctx.web` 服务开放了
+ * registerFetchProvider 扩展点：本文件注册一个更能打的替代者。
+ *
+ * 本文件的做法：
+ *  - 用【用户的真实 Tabbit 浏览器】取页（顺带白赚 JS 渲染和登录墙内容）；
+ *  - 安全性与 permissions 模块的双闸配对：pageAccess 总闸 + intranetFetch
+ *    内网附加闸（默认逐 origin 审批）——这是"敢启用 fetch"的全部底气；
+ *  - 请求前的内网判定在 permissions 里做；本文件负责【事后半段】：拿到
+ *    最终 URL（重定向后的落点）再查一次，公网请求跳到内网目标一律拒绝
+ *    返回内容（redirect containment，防"公网 URL 302 进内网"绕闸）。
+ *
+ * 执行模型：所有 fetch 共用一个固定只读任务（FETCH_TASK_NAME，在用户浏览器
+ * 里显示为 "DeepSeek Harness · Web Fetch" 标签组）；每个请求开一个新页
+ * （用户可见、不抢焦点），提取完 finally 关页——任务本身常驻复用。
+ *
+ * 选择机制：dsh 的 `ctx.web` 按【钉死的 provider id】选 provider——没有
+ * 优先级链，config 里钉的 id 还优先于环境变量 DSH_WEB_FETCH_PROVIDER。基座
+ * 把 fetchProvider 钉为内置的 `http`，本 bundle 的 cordis.patch.yml 把它改
+ * 钉为本 provider 的 id `tabbit-browser`——因此本文件注册后就是唯一会被使
+ * 用的抓取通道；浏览器不可用时 dsh 报 WEB_PROVIDER_CONFIGURED_UNAVAILABLE
+ * （工具仍可见，调用时才报错），不会回落到内置直连抓取器。工具开关
+ * tool-web.fetch 由 web 形态的标准 preset（alpha.1 起自带 true）和本 bundle
+ * 补丁（headless 形态）打开。
+ */
+import { existsSync } from 'node:fs';
+// WebError：dsh-web 定义的标准错误类型（带错误码），fetch 失败必须抛它，
+// dsh 才能把错误规整地渲染给模型。
+import { WebError } from '@deepseek-ai/dsh-web';
+import { FETCH_TASK_NAME } from '../core/index.js';
+import { TabbitCliError } from '../runtime/errors.js';
+import { hostnameLooksLocal, ipIsPrivate } from '../runtime/net.js';
+/* 提取正文的字符上限（在浏览器侧就截断，见 buildFetchCode）。 */
+const MAX_TEXT_CHARS = 180_000;
+/* 页面导航（goto）超时。 */
+const NAV_TIMEOUT_MS = 25_000;
+/* 整段求值超时（导航 + 稳定等待 + 提取，留了余量）。 */
+const EVAL_TIMEOUT_MS = 45_000;
+/* dsh WebFetchProvider 接口的实现（id 是 provider 的注册标识）。 */
+class TabbitFetchProvider {
+    tabbit;
+    id = 'tabbit-browser';
+    /* available() 的 5 秒结果缓存（该方法会被频繁调用，别每次都摸文件系统）。 */
+    availabilityCache;
+    constructor(tabbit) {
+        this.tabbit = tabbit;
+    }
+    /*
+     * dsh 用它判断"这个 provider 现在能不能用"。刻意只做【零副作用的本地文件
+     * 检查】：launcher 文件存在 + 实例注册表非空。不真连浏览器（那会把离线的
+     * 浏览器拉起来），也不管在不在线（fetch 真跑的时候 launcher 自会拉起浏览器）。
+     */
+    available() {
+        const now = Date.now();
+        if (this.availabilityCache !== undefined && now - this.availabilityCache.at < 5000) {
+            return this.availabilityCache.value;
+        }
+        const value = existsSync(this.tabbit.launcherPath()) && this.tabbit.instances().length > 0;
+        this.availabilityCache = { at: now, value };
+        return value;
+    }
+    /* 一次抓取。全流程：校验 URL → 浏览器里取页提取 → 重定向围堵 → 组装结果。 */
+    async fetch(request, signal) {
+        let url;
+        try {
+            url = new URL(request.url);
+        }
+        catch {
+            throw new WebError(`invalid URL: ${request.url}`, 'FETCH_INVALID_URL');
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new WebError(`unsupported URL scheme "${url.protocol}" (http/https only)`, 'FETCH_INVALID_URL');
+        }
+        // 记住请求【本来就是】内网目标的情况（此时用户已经通过 intranetFetch 闸
+        // 批准过了）——这种请求最终落在内网属正常，不该被下面的重定向围堵误杀。
+        const requestWasPrivate = hostIsObviouslyPrivate(url.hostname);
+        const client = this.tabbit.client();
+        let outcome;
+        try {
+            outcome = await client.evaluate({
+                task: FETCH_TASK_NAME,
+                readOnly: true, // 抓取声明为只读：中断不会把共享任务打进隔离状态
+                timeoutMs: EVAL_TIMEOUT_MS,
+                code: buildFetchCode(url.href),
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch (error) {
+            // CLI 层错误 → 翻译成 dsh 的 WebError（错误码映射见 webErrorCode）。
+            if (error instanceof TabbitCliError) {
+                throw new WebError(`Tabbit browser fetch failed: ${error.message}`, webErrorCode(error));
+            }
+            throw error;
+        }
+        // 登记共享任务实际用的实例（插件卸载时 releaseAll 要在对的实例上 finish 它）。
+        this.tabbit.markFetchTaskUsed(client.resolvedInstanceId());
+        if (outcome.status === 'failed') {
+            const message = outcome.errorMessage ?? 'navigation failed';
+            const code = /timeout/iu.test(message) ? 'FETCH_TIMEOUT' : 'FETCH_FAILED';
+            throw new WebError(`Tabbit browser fetch failed: ${message}`, code);
+        }
+        const value = (outcome.result?.value ?? {});
+        const finalUrl = typeof value.finalUrl === 'string' && value.finalUrl !== '' ? value.finalUrl : url.href;
+        // 【重定向围堵】：公网发起的请求，最终 URL 若落在私有目标上，拒绝返回
+        // 内容——否则攻击者可用一个公网短链 302 到 http://127.0.0.1:8080/admin
+        // 之类，绕过 intranetFetch 闸把内网内容送进模型上下文。
+        if (!requestWasPrivate) {
+            try {
+                const finalHost = new URL(finalUrl).hostname;
+                if (hostIsObviouslyPrivate(finalHost)) {
+                    throw new WebError(`fetch of ${url.href} redirected to a private target (${finalHost}); refusing to return its content`, 'FETCH_BLOCKED_REDIRECT');
+                }
+            }
+            catch (error) {
+                if (error instanceof WebError)
+                    throw error;
+                /* 最终 URL 解析不了：按原始 URL 继续（不因解析失败误杀） */
+            }
+        }
+        // 组装 dsh 期望的 WebFetchResult：标题拼成 Markdown 一级标题打头。
+        const title = typeof value.title === 'string' ? value.title : '';
+        const text = typeof value.text === 'string' ? value.text : '';
+        const content = title !== '' ? `# ${title}\n\n${text}` : text;
+        return {
+            url: finalUrl,
+            statusCode: typeof value.status === 'number' && value.status > 0 ? value.status : 200,
+            body: { kind: 'text', content },
+            truncated: value.truncated === true || outcome.result?.truncated === true,
+        };
+    }
+}
+/* "一眼可判"的私有主机检查（字面 IP 私有段 / 本地域名形态；不做 DNS——同步、够快）。 */
+function hostIsObviouslyPrivate(hostname) {
+    const bare = hostname.replace(/^\[|\]$/gu, '');
+    return ipIsPrivate(bare) || hostnameLooksLocal(bare);
+}
+/* TabbitCliError 类别 → dsh WebError 错误码的映射。 */
+function webErrorCode(error) {
+    switch (error.kind) {
+        case 'launcher-missing':
+        case 'instance-selection':
+        case 'browser-unavailable':
+            return 'TABBIT_UNAVAILABLE';
+        case 'busy':
+            return 'TABBIT_BUSY';
+        case 'timeout':
+            return 'FETCH_TIMEOUT';
+        default:
+            return 'FETCH_FAILED';
+    }
+}
+/*
+ * 生成在浏览器任务里执行的取页脚本（作为 evaluate 的 code 参数）。
+ * URL 经 JSON.stringify 嵌入——这是防注入的关键：URL 里的引号/反斜杠都会被
+ * 正确转义，不可能"逃出"字符串字面量变成代码。
+ *
+ * 脚本逻辑（在浏览器进程里跑，可用注入全局 context 等）：
+ *  1. context.newPage() 开新页（挂在共享 fetch 任务的标签组下）；
+ *  2. goto 导航，等到 domcontentloaded（DOM 就绪即可，不等全部资源）；
+ *  3. 再等 400ms 让常见的客户端渲染稳一稳；
+ *  4. p.evaluate(...) 进入【页面 JS 环境】提取：优先 article/main/[role=main]
+ *     语义正文容器，退化到 body；取 innerText（渲染后的可见文本，自动剔除
+ *     script/style/隐藏元素——比 innerHTML 干净得多）；
+ *  5. 超 18 万字符截断并标记；
+ *  6. 返回 {finalUrl（重定向后落点，围堵检查用）, status, title, text, truncated}；
+ *  7. finally 无论成败必关页——不留孤儿标签页。
+ *
+ * ⚠️ 模板字符串内是下发浏览器的代码原文，勿在其中加注释/改动。
+ */
+function buildFetchCode(url) {
+    return `const target = ${JSON.stringify(url)};
+const p = await context.newPage();
+try {
+  let resp = null;
+  try {
+    resp = await p.goto(target, { waitUntil: 'domcontentloaded', timeout: ${NAV_TIMEOUT_MS} });
+  } catch (error) {
+    throw new Error('navigation failed: ' + String((error && error.message) || error));
+  }
+  await p.waitForTimeout(400);
+  const data = await p.evaluate(() => {
+    const root = document.querySelector('article, main, [role="main"]') || document.body;
+    const title = document.title || '';
+    const text = root ? root.innerText || '' : '';
+    return { title, text };
+  });
+  let text = data.text || '';
+  let truncated = false;
+  if (text.length > ${MAX_TEXT_CHARS}) {
+    text = text.slice(0, ${MAX_TEXT_CHARS});
+    truncated = true;
+  }
+  return {
+    finalUrl: p.url(),
+    status: resp ? resp.status() : 0,
+    title: data.title,
+    text,
+    truncated,
+  };
+} finally {
+  try { await p.close(); } catch {}
+}`;
+}
+export const name = 'tabbit-web-fetch';
+export const inject = ['web', 'tabbit'];
+/* 插件入口：把 provider 注册进 dsh 的 web 服务（补丁层已把 fetchProvider 钉到它的 id 上）。 */
+export function apply(ctx) {
+    ctx.web.registerFetchProvider(new TabbitFetchProvider(ctx.tabbit));
+}

package/package.json

@@ -1,41 +1,80 @@
 {
   "name": "dsh-tabbit",
-  "version": "0.2.3",
-  "description": "DSH bundle that packages the Tabbit Browser skill and background installer",
+  "version": "0.3.2",
+  "description": "Tabbit Browser bundle for DeepSeek Harness: a code-first tabbit_browser tool, browser-backed web_fetch, @tab composer mentions, a dedicated page-access permission, an environment preflight with background installer download, and a daily plugin update check.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Tabbit-Browser/dsh-tabbit.git"
   },
   "type": "module",
-  "main": "./index.js",
+  "main": "./lib/core/index.js",
   "exports": {
-    ".": "./index.js"
+    ".": "./lib/core/index.js",
+    "./core": "./lib/core/index.js",
+    "./permissions": "./lib/permissions/index.js",
+    "./tool-browser": "./lib/tool-browser/index.js",
+    "./web-fetch": "./lib/web-fetch/index.js",
+    "./mentions": "./lib/mentions/index.js",
+    "./installer": "./lib/installer/index.js",
+    "./client": "./client/client.js",
+    "./runtime": "./lib/runtime/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
   },
   "files": [
-    "index.js",
-    "installer.js",
-    "update-check.js",
+    "lib",
+    "client",
+    "skills",
     "cordis.patch.yml",
-    "skills/**",
     "README.md",
-    "README.zh-CN.md"
+    "README.en.md",
+    "CHANGELOG.md"
   ],
-  "scripts": {
-    "test": "node --test"
-  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-input-trigger"
+      ]
     }
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test",
+    "link-harness": "node scripts/link-harness.mjs"
+  },
   "engines": {
-    "node": ">=20"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
-    "@deepseek-ai/dsh-jobs": ">=0.1.0-rc.5",
-    "@deepseek-ai/dsh-skill": ">=0.1.0-rc.5",
-    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.5"
+    "@deepseek-ai/dsh-agent": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-attachment": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-commands": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-jobs": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-skill": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-user-approval": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-util-values": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-web": ">=0.1.1-rc.2 || >=0.1.2-alpha.1",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "link:./.dsh-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-session": "link:./.dsh-harness/packages/core/session",
+    "@deepseek-ai/dsh-tools": "link:./.dsh-harness/packages/core/tools",
+    "@deepseek-ai/dsh-web": "link:./.dsh-harness/packages/web/web",
+    "@deepseek-ai/schemastery": "link:./.dsh-harness/vendor/schemastery",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0"
   },
   "license": "MIT"
 }