cortico-world-surfing 0.3.0 → 0.3.2

package/AGENTS.md

@@ -2,11 +2,11 @@
 
 Before changing this world extension, read [Cortico extension contracts](https://github.com/Pal-AI-Lab/Cortico/blob/main/docs/extensions.md).
 
-- Use a Cortico checkout at tag `v0.2.1` for framework checks; the sibling deployment checkout may run an older version. Match `cortico.api` to the printed contract version.
-- After changing tools, events or environment prompt templates, run `pnpm describe:extension <dir>` from the v0.2.1 checkout. Commit the generated file and ship it through `cortico.describe` and `files`.
+- Use a Cortico checkout at tag `v0.2.10` for framework checks; the sibling deployment checkout may run an older version. Match `cortico.api` to the printed contract version.
+- After changing tools, events or environment prompt templates, run `pnpm describe:extension <dir>` from the v0.2.10 checkout. Commit the generated file and ship it through `cortico.describe` and `files`.
 - Before publishing, select applicable tags from [TAGS.md](https://github.com/Pal-AI-Lab/cortico-extensions/blob/main/TAGS.md), including notice and warning tags. Maintainer tags take precedence; withdrawing a published warning requires a maintainer request.
 - Add a `## <version>` section to CHANGELOG.md and include it in the package. Declare npm `os` only for supported platform restrictions.
-- Run the package tests, TypeScript checks and engine build, then `pnpm check:extension <dir>` from the v0.2.1 checkout. Check the packed file list for the entry, engine bundle, self-description and changelog.
+- Run the package tests, TypeScript checks and engine build, then `pnpm check:extension <dir>` from the v0.2.10 checkout. Check the packed file list for the entry, engine bundle, self-description and changelog.
 - Build the engine bundle in an isolated copy while a deployed bot uses this checkout. Use fake deployments and scripted models for verification.
 - Stage explicit paths and make local Conventional Commits. Push, publish and submit maintainer requests only when the user asks.
 - For tag changes, certification, superseding packages or appeals, follow the [index request format](https://github.com/Pal-AI-Lab/cortico-extensions#readme). Certification requires a maintainer review.

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.2 - 2026-11-03
+
+- Use Microlink to render pages when local Chromium is unavailable, with an optional API key and keyless requests.
+- Merge reading limits and Microlink settings into one WebUI config panel, with key file actions, key status and step-by-step API key instructions.
+
+## 0.3.1 - 2026-10-30
+
+- Align development and CI validation with Cortico 0.2.10.
+
 ## 0.3.0 - 2026-10-21
 
 - Add anonymous video description and comment readers, including hot/latest ordering, pinned comments, thread replies and cursor continuation.

package/README.md

@@ -1,4 +1,4 @@
-<!-- Owner: package.json, src/definition.ts, src/world.ts, src/ENV_PROMPT.md, src/network.ts, src/bili.ts -->
+<!-- Owner: package.json, src/definition.ts, src/world.ts, src/ENV_PROMPT.md, src/network.ts, src/bili.ts, src/microlink.ts, src/webui/client.ts -->
 # 网上冲浪
 
 让 Cortico 阅读公开网页、B站视频简介、字幕和评论，搜索视频，并根据读到的内容回答问题。发送链接或BV号即可使用，B站读取均使用匿名请求。
@@ -18,12 +18,34 @@
 
 1. 在 Cortico 扩展管理页输入 `cortico-world-surfing` 安装 npm 包；使用本地源码时选择本项目目录。
 2. 重启 Cortico 进程，启用“网上冲浪”。
-3. 如需读取依赖脚本加载正文的网页，在扩展目录执行一次：
+3. 读取依赖脚本加载正文的网页时，优先使用本机 Chromium。可在扩展目录安装：
 
    ```powershell
    corepack pnpm install:browser
    ```
 
+本机 Chromium 不可用时，扩展将目标网页 URL 发送给 Microlink，由其渲染后返回 HTML；正文、编号链接和章节锚点仍由本扩展提取。静态读取、Chromium 和 Microlink 共用单次读取超时及下载上限。Chromium 已启动后的网页错误、超时或取消不触发 Microlink。
+
+## Microlink（可选）
+
+无需 API Key 即可使用 Microlink 后备。配置 Key 后使用认证接口及该 Key 的额度；Key 仅发送给 Microlink，不进入模型回执。
+
+在网上冲浪的「配置」页找到「Microlink 远程渲染」，点击「打开密钥文件」，编辑部署目录的 `.env`：
+
+```dotenv
+CORTICO_SURFING_MICROLINK_API_KEY=
+```
+
+取得免费 Key 的步骤：
+
+1. 打开 [Microlink 注册页](https://dashboard.microlink.io/signup)，注册账号并登录，无需购买付费套餐。
+2. 在控制台左侧选择「Overview」，点击「Usage」标签。
+3. 点击「Development」标签右上角的「…」，复制 API Key。
+4. 将 Key 填在上面的等号后，不加引号，保存文件。
+5. 点击「刷新密钥状态」，状态变为「API Key 已配置」。下次远程读取使用新 Key；清空值并保存可恢复免 Key 调用。
+
+免 Key 和免费 Key 的额度不同，当前限制见 [Microlink 额度说明](https://microlink.io/docs/api/basics/rate-limit)。额度耗尽或访问失败时，回执说明原因；已有短静态正文仍返回，并标明未取得完整渲染内容。
+
 ## World 兼容性
 
 按 [Cortico World 兼容等级](https://github.com/Pal-AI-Lab/Cortico/blob/main/docs/world-compatibility.md)，本 World 的最低等级为 **L1**，完整等级为 **L3**。

package/dist/webui.js

@@ -0,0 +1,216 @@
+// src/config.ts
+var SURFING_MICROLINK_SECRET = "CORTICO_SURFING_MICROLINK_API_KEY";
+var SURFING_DEFAULTS = {
+  enabled: false,
+  reading: { maxResponseEstimatedTokens: 3e3, maxSourceChars: 3e5 },
+  bili: { subtitleGroupSec: 30, maxSubtitleRetries: 2, subtitleRetryDelayMs: 1e3 },
+  network: { maxDownloadBytes: 8 * 1024 * 1024, requestTimeoutMs: 2e4 },
+  cache: { ttlMs: 9e5, maxBytes: 32 * 1024 * 1024 }
+};
+var SURFING_CONFIG_GROUP = {
+  id: "world:surfing",
+  owner: "world:surfing",
+  schema: { type: "object", title: "\u9605\u8BFB\u4E0E\u5B57\u5E55", properties: {
+    "worlds.surfing.reading.maxResponseEstimatedTokens": {
+      type: "integer",
+      title: "\u5355\u6B21\u8FD4\u56DE\u4E0A\u9650",
+      minimum: 1024,
+      maximum: 32768,
+      "x-suffix": "\u4F30\u7B97 token",
+      "x-hot": true,
+      description: "\u5305\u542B\u6B63\u6587\u548C\u7EED\u8BFB\u4FE1\u606F\uFF1B\u4E0B\u6B21\u8C03\u7528\u751F\u6548\u3002\u8FDE\u7EED\u7EED\u8BFB\u4F1A\u7D2F\u79EF\u4E0A\u4E0B\u6587\u3002"
+    },
+    "worlds.surfing.bili.subtitleGroupSec": {
+      type: "integer",
+      title: "\u5B57\u5E55\u65F6\u95F4\u5206\u7EC4",
+      minimum: 1,
+      maximum: 120,
+      "x-suffix": "\u79D2",
+      "x-hot": true,
+      description: "\u5408\u5E76\u663E\u793A\u65F6\u95F4\u6233\uFF0C\u4FDD\u7559\u539F\u53E5\uFF1B\u65B0\u8BFB\u53D6\u751F\u6548\u3002"
+    },
+    "worlds.surfing.bili.maxSubtitleRetries": {
+      type: "integer",
+      title: "\u7A7A\u5B57\u5E55\u91CD\u8BD5\u6B21\u6570",
+      minimum: 0,
+      maximum: 5,
+      "x-suffix": "\u6B21",
+      "x-hot": true,
+      description: "\u9996\u6B21\u4E3A\u7A7A\u540E\u989D\u5916\u91CD\u8BD5\uFF1B0 \u8868\u793A\u5173\u95ED\u3002\u65B0\u8BFB\u53D6\u751F\u6548\u3002"
+    },
+    "worlds.surfing.bili.subtitleRetryDelayMs": {
+      type: "integer",
+      title: "\u9996\u6B21\u91CD\u8BD5\u7B49\u5F85",
+      minimum: 100,
+      maximum: 1e4,
+      "x-scale": 1e3,
+      "x-suffix": "\u79D2",
+      "x-hot": true,
+      description: "\u540E\u7EED\u6BCF\u6B21\u7B49\u5F85\u7FFB\u500D\uFF0C\u91CD\u8BD5\u5171\u7528\u5355\u6B21\u8BFB\u53D6\u8D85\u65F6\u3002\u65B0\u8BFB\u53D6\u751F\u6548\u3002"
+    }
+  } }
+};
+var SURFING_LIMITS_CONFIG_GROUP = {
+  id: "world:surfing:limits",
+  owner: "world:surfing",
+  schema: { type: "object", title: "\u83B7\u53D6\u4E0E\u7F13\u5B58\u9650\u5236", properties: {
+    "worlds.surfing.reading.maxSourceChars": {
+      type: "integer",
+      title: "\u5355\u4EFD\u6750\u6599\u4FDD\u7559\u4E0A\u9650",
+      minimum: 1e4,
+      maximum: 2e6,
+      "x-suffix": "\u5B57\u7B26",
+      description: "\u6B63\u6587\u3001\u94FE\u63A5\u5730\u5740\u548C\u641C\u7D22\u7ED3\u679C\u5408\u8BA1\uFF1B\u89E6\u9650\u65F6\u6807\u660E\u6750\u6599\u4E0D\u5B8C\u6574\u3002\u65B0\u8BFB\u53D6\u751F\u6548\u3002"
+    },
+    "worlds.surfing.network.maxDownloadBytes": {
+      type: "integer",
+      title: "\u5355\u6B21\u8BFB\u53D6\u4E0B\u8F7D\u4E0A\u9650",
+      minimum: 1048576,
+      maximum: 67108864,
+      "x-scale": 1048576,
+      "x-suffix": "MiB",
+      description: "\u6309\u89E3\u538B\u540E\u6570\u636E\u7D2F\u8BA1\uFF0C\u5305\u542B\u91CD\u5B9A\u5411\u53CA\u6E32\u67D3\u8BF7\u6C42\u3002"
+    },
+    "worlds.surfing.network.requestTimeoutMs": {
+      type: "integer",
+      title: "\u5355\u6B21\u8BFB\u53D6\u8D85\u65F6",
+      minimum: 3e3,
+      maximum: 12e4,
+      "x-scale": 1e3,
+      "x-suffix": "\u79D2",
+      description: "\u6574\u6B21\u8BFB\u53D6\u5171\u7528\u65F6\u9650\uFF1B\u4E0B\u6B21\u8C03\u7528\u751F\u6548\u3002"
+    },
+    "worlds.surfing.cache.ttlMs": {
+      type: "integer",
+      title: "\u7EED\u8BFB\u4FDD\u7559\u65F6\u95F4",
+      minimum: 6e4,
+      maximum: 72e5,
+      "x-scale": 6e4,
+      "x-suffix": "\u5206\u949F",
+      description: "\u5230\u671F\u9700\u91CD\u65B0\u8BFB\u53D6\uFF1B\u65B0\u5FEB\u7167\u751F\u6548\u3002"
+    },
+    "worlds.surfing.cache.maxBytes": {
+      type: "integer",
+      title: "\u6587\u672C\u7F13\u5B58\u4E0A\u9650",
+      minimum: 8388608,
+      maximum: 268435456,
+      "x-scale": 1048576,
+      "x-suffix": "MiB",
+      description: "\u6309\u4FDD\u5B58\u7684\u6570\u636E\u5927\u5C0F\u6838\u7B97\uFF0C\u8D85\u9650\u6DD8\u6C70\u6700\u4E45\u672A\u8BFB\u7684\u6750\u6599\u3002"
+    }
+  } }
+};
+var SURFING_CONFIG_GROUPS = [SURFING_CONFIG_GROUP, SURFING_LIMITS_CONFIG_GROUP];
+
+// src/webui/client.ts
+var errorText = (error) => error instanceof Error ? error.message : "\u64CD\u4F5C\u5931\u8D25";
+async function mount(ctx) {
+  const { ui } = ctx;
+  const state = await ctx.invoke("state");
+  const layout = ui.h("div");
+  layout.style.cssText = "display:grid;gap:20px;max-width:960px;margin:auto";
+  let saves = Promise.resolve();
+  for (const group of SURFING_CONFIG_GROUPS) {
+    const sheet = group === SURFING_LIMITS_CONFIG_GROUP ? ui.foldSheet("surfing-limits", { title: group.schema.title, defaultOpen: false }) : ui.sheet({ title: group.schema.title });
+    const grid = ui.h("div");
+    grid.style.cssText = "display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,320px),1fr));gap:16px 24px";
+    const saved = ui.msgline("");
+    for (const [path, property] of Object.entries(group.schema.properties)) {
+      const scale = property["x-scale"] ?? 1;
+      const input = ui.input({ type: "number", value: String(state.values[path] / scale), onChange: (value) => {
+        saves = saves.then(async () => {
+          const next = await ctx.invoke("save", [path, Number(value) * scale]);
+          if (input.value === value) input.value = String(next.values[path] / scale);
+          saved.textContent = `\u5DF2\u4FDD\u5B58\uFF1A${property.title}`;
+          saved.classList.remove("bad");
+          void ctx.refresh().catch(() => void 0);
+        }).catch((error) => {
+          saved.textContent = errorText(error);
+          saved.classList.add("bad");
+        });
+      } });
+      input.min = String(property.minimum / scale);
+      input.max = String(property.maximum / scale);
+      const field = ui.field(`${property.title}\uFF08${property["x-suffix"]}\uFF09`, input);
+      const note = ui.h("small", "muted", property.description);
+      note.id = path;
+      input.setAttribute("aria-describedby", note.id);
+      const row = ui.h("div");
+      row.append(field, note);
+      grid.append(row);
+    }
+    sheet.body.append(grid, saved);
+    layout.append(sheet.el);
+  }
+  const anchor = (text, href) => {
+    const link = ui.h("a", null, text);
+    link.href = href;
+    link.target = "_blank";
+    link.rel = "noopener noreferrer";
+    return link;
+  };
+  const keyStatus = ui.msgline("");
+  let keyPill = ui.pill("", "off");
+  const showKey = (keySet) => {
+    const next = ui.pill(keySet ? "API Key \u5DF2\u914D\u7F6E" : "\u514D Key", keySet ? "on" : "off");
+    keyPill.replaceWith(next);
+    keyPill = next;
+  };
+  async function keyAction(run) {
+    try {
+      keyStatus.textContent = await run();
+      keyStatus.classList.remove("bad");
+    } catch (error) {
+      keyStatus.textContent = errorText(error);
+      keyStatus.classList.add("bad");
+    }
+  }
+  const keyBar = ui.rowbar();
+  keyBar.append(
+    keyPill,
+    ui.button("\u6253\u5F00\u5BC6\u94A5\u6587\u4EF6", { onClick: () => {
+      void keyAction(async () => {
+        await ctx.invoke("openKeyFile");
+        return "\u5DF2\u6253\u5F00\u5BC6\u94A5\u6587\u4EF6";
+      });
+    } }),
+    ui.button("\u5237\u65B0\u5BC6\u94A5\u72B6\u6001", { onClick: () => {
+      void keyAction(async () => {
+        showKey((await ctx.invoke("state")).keySet);
+        void ctx.refresh().catch(() => void 0);
+        return "\u5DF2\u5237\u65B0\u5BC6\u94A5\u72B6\u6001";
+      });
+    } }),
+    keyStatus
+  );
+  showKey(state.keySet);
+  const steps = ui.h("ol");
+  steps.style.cssText = "list-style:decimal;padding-left:24px;margin:6px 0;line-height:1.8";
+  const secret = ui.h("code", "mono", `${SURFING_MICROLINK_SECRET}=`);
+  for (const parts of [
+    ["\u6253\u5F00", anchor("Microlink \u6CE8\u518C\u9875", "https://dashboard.microlink.io/signup"), "\uFF0C\u6CE8\u518C\u8D26\u53F7\u5E76\u767B\u5F55\uFF0C\u65E0\u9700\u8D2D\u4E70\u4ED8\u8D39\u5957\u9910\u3002"],
+    ["\u5728\u63A7\u5236\u53F0\u5DE6\u4FA7\u9009\u62E9\u300COverview\u300D\uFF0C\u70B9\u51FB\u300CUsage\u300D\u6807\u7B7E\u3002"],
+    ["\u70B9\u51FB\u300CDevelopment\u300D\u6807\u7B7E\u53F3\u4E0A\u89D2\u7684\u300C\u2026\u300D\uFF0C\u590D\u5236 API Key\u3002"],
+    ["\u70B9\u51FB\u300C\u6253\u5F00\u5BC6\u94A5\u6587\u4EF6\u300D\uFF0C\u5C06 Key \u586B\u5728 ", secret, " \u540E\u9762\uFF0C\u4E0D\u52A0\u5F15\u53F7\uFF0C\u4FDD\u5B58\u6587\u4EF6\u3002"],
+    ["\u4FDD\u5B58\u540E\uFF0C\u4E0B\u6B21\u8FDC\u7A0B\u8BFB\u53D6\u4F7F\u7528\u8BE5 Key \u7684\u989D\u5EA6\u3002\u70B9\u51FB\u300C\u5237\u65B0\u5BC6\u94A5\u72B6\u6001\u300D\u53EF\u67E5\u770B\u914D\u7F6E\u72B6\u6001\u3002\u6E05\u7A7A Key \u7684\u503C\u5E76\u4FDD\u5B58\u53EF\u6062\u590D\u514D Key \u8C03\u7528\u3002"]
+  ]) {
+    const step = ui.h("li");
+    step.append(...parts);
+    steps.append(step);
+  }
+  const limits = ui.h("p", "muted");
+  limits.append("\u514D Key \u548C\u514D\u8D39 Key \u7684\u989D\u5EA6\u4E0D\u540C\uFF0C\u5F53\u524D\u9650\u5236\u89C1", anchor("Microlink \u989D\u5EA6\u8BF4\u660E", "https://microlink.io/docs/api/basics/rate-limit"), "\u3002");
+  const microlink = ui.sheet({
+    title: "Microlink \u8FDC\u7A0B\u6E32\u67D3",
+    desc: "\u672C\u673A Chromium \u4E0D\u53EF\u7528\u65F6\uFF0C\u5C06\u7F51\u9875 URL \u4EA4\u7ED9 Microlink \u6E32\u67D3\u3002API Key \u53EF\u9009\uFF0C\u7559\u7A7A\u4F7F\u7528\u514D Key \u989D\u5EA6\u3002"
+  });
+  const help = ui.foldSheet("surfing-microlink-key", { title: "\u5982\u4F55\u53D6\u5F97 API Key", defaultOpen: false });
+  help.body.append(steps, limits);
+  microlink.body.append(keyBar, help.el);
+  layout.append(microlink.el);
+  ctx.root.replaceChildren(layout);
+}
+var client_default = { panels: { config: { mount } } };
+export {
+  client_default as default
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-surfing",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "读取公开网页正文和 B站视频简介、字幕、评论，支持视频搜索、分段续读和可调返回量。",
   "author": "DTMosken",
@@ -27,7 +27,8 @@
       "browser",
       "video"
     ],
-    "describe": "describe.json"
+    "describe": "describe.json",
+    "webUiClient": "dist/webui.js"
   },
   "files": [
     "src",
@@ -43,6 +44,8 @@
   "scripts": {
     "test": "node scripts/build-engine.mjs && vitest run",
     "build:engine": "node scripts/build-engine.mjs",
+    "build:web": "esbuild src/webui/client.ts --bundle --format=esm --outfile=dist/webui.js",
+    "typecheck:web": "tsc -p tsconfig.web.json --noEmit",
     "typecheck": "tsc --noEmit",
     "install:browser": "node scripts/install-browser.mjs"
   },
@@ -55,7 +58,7 @@
   "devDependencies": {
     "@types/jsdom": "^27.0.0",
     "@types/node": "^22.10.0",
-    "cortico": "^0.2.1",
+    "cortico": "0.2.10",
     "esbuild": "0.28.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"

package/src/config.ts

@@ -1,5 +1,7 @@
 import type { ConfigGroup } from 'cortico/core/types.ts';
 
+export const SURFING_MICROLINK_SECRET = 'CORTICO_SURFING_MICROLINK_API_KEY';
+
 export interface SurfingConfigSection {
   enabled: boolean;
   reading: { maxResponseEstimatedTokens: number; maxSourceChars: number };
@@ -18,7 +20,7 @@ export const SURFING_DEFAULTS: SurfingConfigSection = {
 
 export const SURFING_CONFIG_GROUP: ConfigGroup = {
   id: 'world:surfing', owner: 'world:surfing',
-  schema: { type: 'object', title: '阅读返回量', properties: {
+  schema: { type: 'object', title: '阅读与字幕', properties: {
     'worlds.surfing.reading.maxResponseEstimatedTokens': {
       type: 'integer', title: '单次返回上限', minimum: 1024, maximum: 32768,
       'x-suffix': '估算 token', 'x-hot': true,
@@ -66,6 +68,12 @@ export const SURFING_LIMITS_CONFIG_GROUP: ConfigGroup = {
   } },
 };
 
+export const SURFING_CONFIG_GROUPS = [SURFING_CONFIG_GROUP, SURFING_LIMITS_CONFIG_GROUP];
+
+export function configValue(config: SurfingConfigSection, path: string): unknown {
+  return path.split('.').slice(2).reduce<unknown>((part, key) => (part as Record<string, unknown>)?.[key], config);
+}
+
 export function applyBiliDefaults(config: SurfingConfigSection): void {
   if (config.bili.maxSubtitleRetries === undefined) config.bili.maxSubtitleRetries = SURFING_DEFAULTS.bili.maxSubtitleRetries;
   if (config.bili.subtitleRetryDelayMs === undefined) config.bili.subtitleRetryDelayMs = SURFING_DEFAULTS.bili.subtitleRetryDelayMs;
@@ -73,9 +81,9 @@ export function applyBiliDefaults(config: SurfingConfigSection): void {
 
 export function validateConfig(config: SurfingConfigSection): void {
   applyBiliDefaults(config);
-  for (const group of [SURFING_CONFIG_GROUP, SURFING_LIMITS_CONFIG_GROUP]) {
+  for (const group of SURFING_CONFIG_GROUPS) {
     for (const [path, schema] of Object.entries(group.schema.properties)) {
-      const value = path.split('.').slice(2).reduce<unknown>((part, key) => (part as Record<string, unknown>)?.[key], config);
+      const value = configValue(config, path);
       if (typeof value !== 'number' || !Number.isInteger(value) || value < schema.minimum! || value > schema.maximum!)
         throw new Error(`${schema.title}超出配置范围。`);
     }

package/src/microlink.ts

@@ -0,0 +1,35 @@
+import { ReadError, validatePublicUrl, type ReadOperation } from './network.ts';
+
+export class MicrolinkRenderer {
+  constructor(private readonly apiKey: () => string = () => '') {}
+
+  async render(input: string, operation: ReadOperation, maxBytes: number): Promise<{ html: string; url: string }> {
+    const target = validatePublicUrl(input);
+    const key = this.apiKey().trim();
+    const endpoint = new URL(key ? 'https://pro.microlink.io/' : 'https://api.microlink.io/');
+    endpoint.search = new URLSearchParams({ url: target.href, 'data.html.attr': 'html', meta: 'false', prerender: 'true' }).toString();
+    const response = await operation.get(endpoint.href, {
+      headers: key ? { 'x-api-key': key } : undefined,
+      allowHost: hostname => hostname === endpoint.hostname,
+    });
+    if (response.status === 429) throw new ReadError('access_denied', 'Microlink 请求额度已用完或请求过于频繁，请等待额度重置或检查套餐。');
+    if (response.status === 401 || response.status === 403)
+      throw new ReadError('access_denied', 'Microlink 未允许本次读取，请检查可选 API Key 和访问权限。');
+    if (response.status !== 200) throw new ReadError('network_error', `Microlink 读取失败（HTTP ${response.status}）。`);
+    let result: { status?: string; code?: string; statusCode?: number; data?: { html?: string; url?: string } };
+    try { result = JSON.parse(response.body.toString('utf8')); }
+    catch { throw new ReadError('protocol_error', 'Microlink 未返回有效 JSON。'); }
+    if (result?.status !== 'success') {
+      if (result?.code === 'EPROXYNEEDED') throw new ReadError('access_denied', '该网页需要 Microlink 代理，请配置 API Key 后重试。');
+      throw new ReadError('content_unavailable', 'Microlink 未取得渲染后的网页。');
+    }
+    if (result.statusCode !== 200)
+      throw new ReadError(result.statusCode === 404 ? 'not_found' : 'access_denied', '网页未允许本次 Microlink 公开读取。');
+    if (typeof result.data?.html !== 'string' || typeof result.data.url !== 'string')
+      throw new ReadError('protocol_error', 'Microlink 响应缺少 HTML 或最终网页地址。');
+    if (Buffer.byteLength(result.data.html) > maxBytes) throw new ReadError('source_limit', '渲染后的 HTML 超出单次读取上限。');
+    const url = validatePublicUrl(result.data.url);
+    if (!url.hash) url.hash = target.hash;
+    return { html: result.data.html, url: url.href };
+  }
+}

package/src/network.ts

@@ -76,7 +76,7 @@ export function requestHeaders(options: GetOptions): Record<string, string> {
     'accept-encoding': 'gzip, deflate, br', accept: '*/*', 'accept-language': '*',
   };
   for (const [key, value] of Object.entries(options.headers ?? {})) {
-    if (['accept', 'accept-language', 'referer', 'user-agent'].includes(key.toLowerCase())) headers[key.toLowerCase()] = value;
+    if (['accept', 'accept-language', 'referer', 'user-agent', 'x-api-key'].includes(key.toLowerCase())) headers[key.toLowerCase()] = value;
   }
   return headers;
 }

package/src/page-reader.ts

@@ -3,6 +3,7 @@ import { ReadError, asReadError, validatePublicUrl, waitWithSignal, type Failure
 import { createServer, type Server } from 'node:net';
 import { chromium, type Browser } from 'playwright';
 import type { Material } from './snapshots.ts';
+import { MicrolinkRenderer } from './microlink.ts';
 
 const ENGINE = new URL('../dist/page-engine.mjs', import.meta.url);
 export function pageKey(input: string): string { return 'page:' + validatePublicUrl(input).href; }
@@ -27,7 +28,7 @@ function extract(html: string, url: string, signal: AbortSignal): Promise<Materi
 }
 
 export class PageReader {
-  constructor(private readonly renderer = new Renderer()) {}
+  constructor(private readonly renderer = new Renderer(), private readonly microlink = new MicrolinkRenderer()) {}
 
   async read(input: string, operation: ReadOperation, maxBytes: number): Promise<Material> {
     const original = validatePublicUrl(input);
@@ -65,10 +66,19 @@ export class PageReader {
     catch (error) {
       if (!(error instanceof ReadError) || error.kind !== 'content_unavailable') throw error;
       try {
-        const rendered = await this.renderer.render(target.href, operation, maxBytes,response);
+        let rendered: { html: string; url: string };
+        let provider = 'chromium';
+        try { rendered = await this.renderer.render(target.href, operation, maxBytes, response); }
+        catch (error) {
+          if (operation.signal.aborted || !(error instanceof ReadError) || error.kind !== 'browser_unavailable') throw error;
+          rendered = await this.microlink.render(target.href, operation, maxBytes);
+          provider = 'microlink';
+        }
+        this.rejectVideo(validatePublicUrl(rendered.url));
         material = await extract(rendered.html, rendered.url, operation.signal);
         delete material.scope.mayNeedRendering;
         material.scope.extraction = 'rendered-html';
+        material.scope.renderingProvider = provider;
       } catch (renderError) {
         if (!staticMaterial || operation.signal.aborted) throw renderError;
         const failure = asReadError(renderError);

package/src/secret-file.ts

@@ -0,0 +1,24 @@
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SURFING_MICROLINK_SECRET } from './config.ts';
+
+export function prepareKeyFile(botDir: string): string {
+  const file = join(botDir, '.env');
+  const contents = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (!new RegExp(`^${SURFING_MICROLINK_SECRET}=`, 'm').test(contents)) {
+    const line = `${contents && !contents.endsWith('\n') ? '\n' : ''}${SURFING_MICROLINK_SECRET}=\n`;
+    if (existsSync(file)) appendFileSync(file, line);
+    else writeFileSync(file, line, { mode: 0o600 });
+  }
+  return file;
+}
+
+export function openSecretFile(file: string): Promise<void> {
+  const command = process.platform === 'win32' ? 'notepad.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [file], { detached: true, stdio: 'ignore' });
+    child.once('error', () => reject(new Error('无法打开密钥文件。')));
+    child.once('spawn', () => { child.unref(); resolve(); });
+  });
+}

package/src/webui/client.ts

@@ -0,0 +1,97 @@
+import type { WebUiClientBundle, WebUiPanelContext } from 'cortico/web/shared/client-panel.ts';
+import { SURFING_CONFIG_GROUPS, SURFING_LIMITS_CONFIG_GROUP, SURFING_MICROLINK_SECRET } from '../config.ts';
+
+interface ConfigState { values: Record<string, number>; keySet: boolean }
+
+const errorText = (error: unknown): string => error instanceof Error ? error.message : '操作失败';
+
+async function mount(ctx: WebUiPanelContext): Promise<void> {
+  const { ui } = ctx;
+  const state = await ctx.invoke<ConfigState>('state');
+  const layout = ui.h('div');
+  layout.style.cssText = 'display:grid;gap:20px;max-width:960px;margin:auto';
+  let saves: Promise<void> = Promise.resolve();
+  for (const group of SURFING_CONFIG_GROUPS) {
+    const sheet = group === SURFING_LIMITS_CONFIG_GROUP
+      ? ui.foldSheet('surfing-limits', { title: group.schema.title, defaultOpen: false })
+      : ui.sheet({ title: group.schema.title });
+    const grid = ui.h('div');
+    grid.style.cssText = 'display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,320px),1fr));gap:16px 24px';
+    const saved = ui.msgline('');
+    for (const [path, property] of Object.entries(group.schema.properties)) {
+      const scale = property['x-scale'] ?? 1;
+      const input = ui.input({ type: 'number', value: String(state.values[path]! / scale), onChange: value => {
+        saves = saves.then(async () => {
+          const next = await ctx.invoke<ConfigState>('save', [path, Number(value) * scale]);
+          if (input.value === value) input.value = String(next.values[path]! / scale);
+          saved.textContent = `已保存：${property.title}`; saved.classList.remove('bad');
+          void ctx.refresh().catch(() => undefined);
+        }).catch(error => { saved.textContent = errorText(error); saved.classList.add('bad'); });
+      } });
+      input.min = String(property.minimum! / scale);
+      input.max = String(property.maximum! / scale);
+      const field = ui.field(`${property.title}（${property['x-suffix']}）`, input);
+      const note = ui.h('small', 'muted', property.description);
+      note.id = path;
+      input.setAttribute('aria-describedby', note.id);
+      const row = ui.h('div');
+      row.append(field, note);
+      grid.append(row);
+    }
+    sheet.body.append(grid, saved);
+    layout.append(sheet.el);
+  }
+
+  const anchor = (text: string, href: string): HTMLAnchorElement => {
+    const link = ui.h('a', null, text);
+    link.href = href; link.target = '_blank'; link.rel = 'noopener noreferrer';
+    return link;
+  };
+  const keyStatus = ui.msgline('');
+  let keyPill = ui.pill('', 'off');
+  const showKey = (keySet: boolean): void => {
+    const next = ui.pill(keySet ? 'API Key 已配置' : '免 Key', keySet ? 'on' : 'off');
+    keyPill.replaceWith(next); keyPill = next;
+  };
+  async function keyAction(run: () => Promise<string>): Promise<void> {
+    try { keyStatus.textContent = await run(); keyStatus.classList.remove('bad'); }
+    catch (error) { keyStatus.textContent = errorText(error); keyStatus.classList.add('bad'); }
+  }
+  const keyBar = ui.rowbar();
+  keyBar.append(keyPill,
+    ui.button('打开密钥文件', { onClick: () => { void keyAction(async () => { await ctx.invoke('openKeyFile'); return '已打开密钥文件'; }); } }),
+    ui.button('刷新密钥状态', { onClick: () => { void keyAction(async () => {
+      showKey((await ctx.invoke<ConfigState>('state')).keySet);
+      void ctx.refresh().catch(() => undefined);
+      return '已刷新密钥状态';
+    }); } }), keyStatus);
+  showKey(state.keySet);
+
+  const steps = ui.h('ol');
+  steps.style.cssText = 'list-style:decimal;padding-left:24px;margin:6px 0;line-height:1.8';
+  const secret = ui.h('code', 'mono', `${SURFING_MICROLINK_SECRET}=`);
+  for (const parts of [
+    ['打开', anchor('Microlink 注册页', 'https://dashboard.microlink.io/signup'), '，注册账号并登录，无需购买付费套餐。'],
+    ['在控制台左侧选择「Overview」，点击「Usage」标签。'],
+    ['点击「Development」标签右上角的「…」，复制 API Key。'],
+    ['点击「打开密钥文件」，将 Key 填在 ', secret, ' 后面，不加引号，保存文件。'],
+    ['保存后，下次远程读取使用该 Key 的额度。点击「刷新密钥状态」可查看配置状态。清空 Key 的值并保存可恢复免 Key 调用。'],
+  ]) {
+    const step = ui.h('li');
+    step.append(...parts);
+    steps.append(step);
+  }
+  const limits = ui.h('p', 'muted');
+  limits.append('免 Key 和免费 Key 的额度不同，当前限制见', anchor('Microlink 额度说明', 'https://microlink.io/docs/api/basics/rate-limit'), '。');
+  const microlink = ui.sheet({
+    title: 'Microlink 远程渲染',
+    desc: '本机 Chromium 不可用时，将网页 URL 交给 Microlink 渲染。API Key 可选，留空使用免 Key 额度。',
+  });
+  const help = ui.foldSheet('surfing-microlink-key', { title: '如何取得 API Key', defaultOpen: false });
+  help.body.append(steps, limits);
+  microlink.body.append(keyBar, help.el);
+  layout.append(microlink.el);
+  ctx.root.replaceChildren(layout);
+}
+
+export default { panels: { config: { mount } } } satisfies WebUiClientBundle;

package/src/world.ts

@@ -1,13 +1,16 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { coerceGroupValues } from 'cortico/core/config-schema.ts';
 import type { ToolDef, ToolSpec, ToolOutcome, ToolCallContext, World, WorldWebUiDecl, WorldHost } from 'cortico/core/types.ts';
 import type { WorldContext } from 'cortico/world.ts';
-import { SURFING_DEFAULTS, SURFING_CONFIG_GROUP, SURFING_LIMITS_CONFIG_GROUP, applyBiliDefaults, validateConfig, type SurfingConfigSection } from './config.ts';
+import { SURFING_CONFIG_GROUPS, SURFING_MICROLINK_SECRET, applyBiliDefaults, configValue, validateConfig, type SurfingConfigSection } from './config.ts';
 import { BiliClient, biliKey, biliCommentsKey, type BiliInput, type BiliCommentsInput } from './bili.ts';
 import { ReadError, asReadError, PublicClient, waitWithSignal, type ReadOperation } from './network.ts';
 import { PageReader, pageKey } from './page-reader.ts';
 import { SnapshotCache, estimateTokens, type Material } from './snapshots.ts';
+import { MicrolinkRenderer } from './microlink.ts';
+import { prepareKeyFile, openSecretFile } from './secret-file.ts';
 
 const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
 
@@ -68,14 +71,16 @@ export class SurfingWorld implements World {
   readonly id = 'surfing';
   private readonly cache = new SnapshotCache();
   private readonly bili = new BiliClient();
-  private readonly pages = new PageReader();
+  private readonly pages: PageReader;
   private readonly pendingBatches = new Map<string,{promise:Promise<string>;signal:AbortSignal}>();
   private lifecycle = new AbortController();
   private stopped = false;
   private last?: { status: string; failed: boolean; estimatedTokens: number; sourceTruncated: boolean };
 
-  constructor(private readonly ctx: WorldContext<SurfingConfigSection>, private readonly client = new PublicClient()) {
+  constructor(private readonly ctx: WorldContext<SurfingConfigSection>, private readonly client = new PublicClient(),
+    private readonly openFile = openSecretFile) {
     applyBiliDefaults(ctx.cfg);
+    this.pages = new PageReader(undefined, new MicrolinkRenderer(() => ctx.secret(SURFING_MICROLINK_SECRET)));
   }
 
   envPromptVars(): Record<string, string> {
@@ -184,6 +189,22 @@ export class SurfingWorld implements World {
     }
   }
 
+  private configState(): { values: Record<string, unknown>; keySet: boolean } {
+    const paths = SURFING_CONFIG_GROUPS.flatMap(group => Object.keys(group.schema.properties));
+    return { values: Object.fromEntries(paths.map(path => [path, configValue(this.ctx.cfg, path)])),
+      keySet: !!this.ctx.secret(SURFING_MICROLINK_SECRET).trim() };
+  }
+
+  private saveConfig(path: unknown, value: unknown): void {
+    const group = SURFING_CONFIG_GROUPS.find(candidate => typeof path === 'string' && Object.hasOwn(candidate.schema.properties, path));
+    if (!group) throw new Error('未知配置项。');
+    const key = path as string;
+    const result = coerceGroupValues(group, { [key]: value });
+    if ('error' in result) throw new Error(result.error);
+    const [section, field] = key.split('.').slice(2);
+    this.ctx.persist({ [section]: { [field]: result.values[key] } });
+  }
+
   webUi(): WorldWebUiDecl {
     const override = join(this.ctx.botDir, 'prompts', 'worlds', 'surfing', 'ENV_PROMPT.md');
     return {
@@ -196,7 +217,17 @@ export class SurfingWorld implements World {
         { label: '源材料', value: this.last ? (this.last.sourceTruncated ? '触及保留上限' : '未触及保留上限') : '尚未读取' },
         { label: '文本缓存', value: Math.ceil(this.cache.sizeBytes / 1024) + ' KiB' },
       ],
-      config: [SURFING_CONFIG_GROUP, SURFING_LIMITS_CONFIG_GROUP],
+      panels: [{ id: 'config', title: '配置' }],
+      invoke: async (panel, method, args) => {
+        if (panel !== 'config') throw new Error('未知面板。');
+        if (method === 'state') return this.configState();
+        if (method === 'save') { this.saveConfig(args[0], args[1]); return this.configState(); }
+        if (method === 'openKeyFile') {
+          const file = prepareKeyFile(this.ctx.botDir);
+          await this.openFile(file); return { file };
+        }
+        throw new Error('未知操作。');
+      },
       promptDocs: [{ key: 'worlds.surfing.envPrompt', title: '网上冲浪环境提示词', description: '网页、视频与学习工具的使用指导。',
         path: existsSync(override) ? override : ENV_PROMPT_FILE, deploymentPath: override, role: 'envPrompt',
         vars: [