feat(web): REQ-304 扩展资产/契约文档/收件服务面板

Author: Aparencia

app/extension-web-clipper/background.js

@@ -0,0 +1,4 @@
+// 服务 worker：剪藏动作由 popup 发起（本文件保持最小——消息中继与安装日志）。
+chrome.runtime.onInstalled.addListener(() => {
+  console.log("熵减 Web 剪藏已安装（开发期加载）——先到熵减设置页开启本地收件服务");
+});

app/extension-web-clipper/content.js

@@ -0,0 +1,68 @@
+// content script：已登录 DOM → Markdown + 元数据 + 图 data URI（零依赖轻量规则；
+// 无 readability/turndown 依赖——规则只做常见文章结构，精确度不承诺，登录墙
+// 优势=读已渲染 DOM）。
+
+function collectMeta() {
+  const pick = (sel) => document.querySelector(sel)?.content?.trim() || null;
+  return {
+    title: document.title || pick("meta[property='og:title']"),
+    url: location.href,
+    site: pick("meta[property='og:site_name']") || location.hostname,
+    author: pick("meta[name='author']") || pick("meta[property='article:author']"),
+  };
+}
+
+function mdText(node) {
+  let out = "";
+  for (const child of node.childNodes) {
+    if (child.nodeType === Node.TEXT_NODE) out += child.textContent;
+    else if (child.nodeType === Node.ELEMENT_NODE) out += mdText(child);
+  }
+  return out;
+}
+
+function nodeToMd(node, depth) {
+  if (!node || depth > 8) return "";
+  const tag = node.tagName ? node.tagName.toLowerCase() : "";
+  if (["script", "style", "noscript", "svg", "iframe", "template", "nav", "aside"].includes(tag)) return "";
+  if (tag === "img") {
+    const src = node.currentSrc || node.src || "";
+    if (src.startsWith("data:")) {
+      const alt = node.alt || "";
+      return alt ? `![${alt}](${src})\n` : "";
+    }
+    // 远程图：扩展无跨域读字节权限（fetch 被 CORS 拦）——跳过并保留 alt 文本
+    return node.alt ? `${node.alt}\n` : "";
+  }
+  if (tag === "h1" || tag === "h2" || tag === "h3" || tag === "h4") {
+    const t = mdText(node).trim();
+    return t ? `${"#".repeat(Number(tag[1]))} ${t}\n` : "";
+  }
+  if (tag === "li") {
+    const t = mdText(node).trim();
+    return t ? `- ${t}\n` : "";
+  }
+  if (tag === "p" || tag === "blockquote" || tag === "pre") {
+    const t = mdText(node).trim();
+    return t ? `${t}\n\n` : "";
+  }
+  let inner = "";
+  for (const child of node.children || []) inner += nodeToMd(child, depth + 1);
+  if (tag === "article" || tag === "section" || tag === "main") inner += "\n";
+  return inner;
+}
+
+function extract() {
+  const main =
+    document.querySelector("article") ||
+    document.querySelector("main") ||
+    document.querySelector(".article-content") ||
+    document.querySelector("#js_content") ||
+    document.body;
+  const markdown = nodeToMd(main, 0).replace(/\n{3,}/g, "\n\n").trim();
+  return { ...collectMeta(), markdown: markdown || "" };
+}
+
+chrome.runtime.onMessage.addListener((req, _sender, sendResponse) => {
+  if (req && req.type === "entropy-extract") sendResponse(extract());
+});

app/extension-web-clipper/manifest.json

@@ -0,0 +1,22 @@
+{
+  "manifest_version": 3,
+  "name": "熵减 Web 剪藏（本地收件）",
+  "version": "0.20.4",
+  "description": "登录态 DOM 抽取 → 熵减本地收件服务（127.0.0.1 + token 单向投递）。仅开发期加载：Edge/Chrome 扩展管理页开启开发者模式后“加载已解压的扩展程序”。",
+  "permissions": ["activeTab", "scripting", "storage"],
+  "host_permissions": ["http://127.0.0.1/*"],
+  "action": {
+    "default_title": "剪藏到熵减",
+    "default_popup": "popup.html"
+  },
+  "background": {
+    "service_worker": "background.js"
+  },
+  "content_scripts": [
+    {
+      "matches": ["http://*/*", "https://*/*"],
+      "js": ["content.js"],
+      "run_at": "document_idle"
+    }
+  ]
+}

app/extension-web-clipper/popup.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <title>熵减 Web 剪藏</title>
+  <style>
+    body { font-family: system-ui, sans-serif; width: 280px; margin: 0; padding: 12px; font-size: 13px; }
+    h1 { font-size: 14px; margin: 0 0 8px; }
+    label { display: block; margin: 6px 0 2px; font-size: 12px; color: #444; }
+    input { width: 100%; box-sizing: border-box; padding: 3px 6px; font-size: 12px; }
+    button { margin-top: 10px; width: 100%; padding: 6px; border: none; border-radius: 6px;
+             background: #0d9488; color: #fff; cursor: pointer; }
+    #result { margin-top: 8px; font-size: 12px; color: #0f766e; white-space: pre-wrap; }
+    #result.err { color: #dc2626; }
+    .hint { font-size: 11px; color: #999; margin-top: 4px; }
+  </style>
+</head>
+<body>
+  <h1>熵减 Web 剪藏</h1>
+  <label>收件端口（设置页 web 采集 显示）</label>
+  <input id="port" type="text" placeholder="如 38921" />
+  <label>Token</label>
+  <input id="token" type="password" placeholder="粘贴设置页 token" />
+  <button id="clip">✂ 剪藏当前页到熵减</button>
+  <div id="result"></div>
+  <div class="hint">登录态页面（公众号/知乎/付费墙）在已登录 DOM 内直取正文——不经第三方。</div>
+  <script src="popup.js"></script>
+</body>
+</html>

app/extension-web-clipper/popup.js

@@ -0,0 +1,55 @@
+// popup 逻辑：保存收件参数 → 抽取当前页 DOM → 投递本地服务。
+
+const $ = (id) => document.getElementById(id);
+
+function result(text, err) {
+  const el = $("result");
+  el.textContent = text;
+  el.className = err ? "err" : "";
+}
+
+$("clip").addEventListener("click", async () => {
+  const port = $("port").value.trim();
+  const token = $("token").value.trim();
+  if (!port || !token) {
+    result("请先填写端口与 token（设置页 web 采集→本地收件）", true);
+    return;
+  }
+  await chrome.storage.local.set({ port, token });
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  if (tab?.id == null) {
+    result("未找到活动页", true);
+    return;
+  }
+  result("抽取当前页正文…");
+  let payload;
+  try {
+    payload = await chrome.tabs.sendMessage(tab.id, { type: "entropy-extract" });
+  } catch (e) {
+    result(`抽取失败：请刷新页面后重试（${e.message ?? e}）`, true);
+    return;
+  }
+  if (!payload || !payload.markdown || payload.markdown.trim().length < 10) {
+    result("页面无正文可剪藏（框架隔离站点请刷新重试）", true);
+    return;
+  }
+  result("投递本地收件服务…");
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/ingest`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: JSON.stringify(payload),
+    });
+    const body = await resp.json().catch(() => ({}));
+    if (resp.ok) result(`✓ 已投递 kind=web 会话（#${body.sessionId}）`);
+    else result(`投递失败 ${resp.status}：${body.error ?? "未知"}`, true);
+  } catch (e) {
+    result(`连接失败：熵减未开启收件服务？(${e.message ?? e})`, true);
+  }
+});
+
+document.addEventListener("DOMContentLoaded", async () => {
+  const { port, token } = await chrome.storage.local.get(["port", "token"]);
+  if (port) $("port").value = port;
+  if (token) $("token").value = token;
+});

app/src/components/WebInboxPanel.tsx

@@ -0,0 +1,100 @@
+/**
+ * WebInboxPanel — web 扩展收件服务（v0.20.4 / REQ-304）。
+ *
+ * @ai-context: 只绑 127.0.0.1 随机端口 + 随机 token（首启生成持久化）；扩展在
+ *              已登录 DOM 抽取（公众号/知乎正解）→ POST /ingest 单向投递；
+ *              本面板=启动/停止/参数展示（端口+token 复制给扩展安装配置）。
+ */
+import { useCallback, useEffect, useState } from "react";
+import { invoke } from "@tauri-apps/api/core";
+
+interface InboxView {
+  running: boolean;
+  port: number | null;
+  token: string | null;
+  inbox_url: string | null;
+}
+
+const btn: React.CSSProperties = { padding: "5px 10px", cursor: "pointer", fontSize: 12, borderRadius: 6 };
+const okBtn: React.CSSProperties = { ...btn, background: "#0d9488", color: "#fff", border: "none" };
+const ghostBtn: React.CSSProperties = { ...btn, background: "#fff", border: "1px solid #e5e7eb", color: "#374151" };
+
+export function WebInboxPanel() {
+  const [view, setView] = useState<InboxView | null>(null);
+  const [msg, setMsg] = useState("");
+  const [err, setErr] = useState("");
+
+  const reload = useCallback(async () => {
+    try {
+      setErr("");
+      setView(await invoke<InboxView>("web_inbox_status"));
+    } catch (e) {
+      setErr(String(e));
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  const start = async () => {
+    try {
+      setView(await invoke<InboxView>("web_inbox_start"));
+      setMsg("✓ 收件服务已启动——仅本机回环可达（随机端口 + token 鉴权）");
+    } catch (e) {
+      setErr(String(e));
+    }
+  };
+
+  const stop = async () => {
+    try {
+      await invoke("web_inbox_stop");
+      setMsg("已停止（token 保留——下次启动同 token，扩展零重配）");
+      await reload();
+    } catch (e) {
+      setErr(String(e));
+    }
+  };
+
+  const copy = async () => {
+    if (!view?.token) return;
+    try {
+      await navigator.clipboard.writeText(
+        `端口：${view.port}\nToken：${view.token}`,
+      );
+      setMsg("已复制端口与 token——粘贴到浏览器扩展弹窗（app/extension-web-clipper 手动加载）");
+    } catch (e) {
+      setErr(`复制失败: ${e}`);
+    }
+  };
+
+  return (
+    <div>
+      <div style={{ fontSize: 12, color: "#374151", marginBottom: 6 }}>
+        <b>🛬 本地收件（浏览器扩展投递）</b>{" "}
+        <span style={{ fontSize: 11, color: "#9ca3af" }}>
+          登录墙正解：扩展读已登录 DOM → 本服务（127.0.0.1 + token 单向投递）→ kind=web 会话
+        </span>
+      </div>
+      {msg && <div style={{ fontSize: 11, color: "#047857", marginBottom: 4 }}>{msg}</div>}
+      {err && <div style={{ fontSize: 11, color: "#dc2626", marginBottom: 4 }}>{err}</div>}
+      <div style={{ display: "flex", gap: 6, alignItems: "center", flexWrap: "wrap" }}>
+        {!view?.running ? (
+          <button style={okBtn} onClick={() => void start()}>▶ 启动收件服务</button>
+        ) : (
+          <>
+            <span style={{ fontSize: 12 }}>端口 <b>{view.port}</b></span>
+            <code style={{ fontSize: 11, background: "#f9fafb", padding: "2px 6px", borderRadius: 4 }}>{view.token}</code>
+            <button style={ghostBtn} onClick={() => void copy()}>复制参数</button>
+            <button style={{ ...ghostBtn, color: "#dc2626" }} onClick={() => void stop()}>⏹ 停止</button>
+          </>
+        )}
+      </div>
+      <div style={{ fontSize: 11, color: "#9ca3af", marginTop: 4 }}>
+        安装扩展：Edge/Chrome 扩展管理页开启开发者模式 → 「加载已解压的扩展程序」→ 选 app/extension-web-clipper（投递契约见 docs/Foresight/web-capture-extension-protocol.md）
+      </div>
+    </div>
+  );
+}
+
+export default WebInboxPanel;

app/src/pages/SettingsPage.tsx

@@ -31,6 +31,8 @@ import SealToggle from "../components/SealToggle";
 import AsrConfusionPanel from "../components/AsrConfusionPanel";
 // v0.20.2（REQ-270）：可选 LLM 文本校对开关（默认关双闸门之二）
 import ProofreadToggle from "../components/ProofreadToggle";
+// v0.20.4（REQ-304）：web 扩展收件服务面板
+import WebInboxPanel from "../components/WebInboxPanel";
 
 const panel: React.CSSProperties = { border: "1px solid #e5e7eb", borderRadius: 8, padding: 12 };
 const groupTitle: React.CSSProperties = {
@@ -123,6 +125,12 @@ export default function SettingsPage({ active = true }: Props) {
         <div style={{ ...panel, marginBottom: 4 }}>
           <AsrConfusionPanel />
         </div>
+
+        {/* v0.20.4（REQ-304）：web 采集（URL 采集在课堂助手动线；本组=扩展收件） */}
+        <GroupTitle>web 采集</GroupTitle>
+        <div style={{ ...panel, marginBottom: 4 }}>
+          <WebInboxPanel />
+        </div>
 
         {/* ── 功能预览（默认关的新能力开关，v4 §11.3）── */}
         <GroupTitle>功能预览</GroupTitle>

docs/Foresight/web-capture-extension-protocol.md

@@ -0,0 +1,48 @@
+# Web 采集：扩展投递契约（v0.20.4 / REQ-304 阶段 2 薄壳）
+
+> 状态：落地文档（2026-09-06，与服务 `web_inbox_start/status/stop` 及扩展骨架 `app/extension-web-clipper/` 同批）
+> 背景：[web-capture-ingestion-path.md](./web-capture-ingestion-path.md)（三件套机制定案）· REQ-303~305
+
+## 一、安全边界（与 AGENTS.md 红线对齐）
+
+- 服务只绑 `127.0.0.1` 随机端口（应用启动期由用户显式开启）；
+- 首启生成随机 token（24 位字母数字，`data_dir/web_inbox.json` 持久化——重启同 token，扩展零重配）；
+- 单向投递：服务只收不发；`GET /ping` 仅返回 `{"ok":true}`（Joplin 端口探测范式）；
+- 鉴权：`Authorization: Bearer <token>`，恒定时间比较；缺失/错误 → 401；
+- CORS：仅需预检放行（`Authorization`/`content-type` 头 + POST/OPTIONS）；扩展服务上下文非同源页面，浏览器 CORS 强制下正常投递；
+- 校验：正文 ≤2MB、URL 仅 http(s) 且 ≤2048、图 ≤50 张且单张 ≤8MB、data URI 必须 `data:image/`、文件名禁路径字符（`../` 等穿越拒绝）；
+- 体量护栏：请求头+体总量 8MB 上限（慢速/超大直断）。
+
+## 二、投递契约（POST /ingest）
+
+```json
+{
+  "title": "文章标题",
+  "url": "https://mp.weixin.qq.com/s/xxx",
+  "site": "公众号名",
+  "author": "作者",
+  "markdown": "# 标题\n正文段落…\n![图1](data:image/png;base64,…)",
+  "images": [{ "name": "图1", "data_base64": "data:image/png;base64,…" }]
+}
+```
+
+响应：`200 {"ok":true,"sessionId":7}`（已建 kind=web 会话 + 页面）；`422 {"error":"…"}` 校验失败；`500` 落库失败；`401` 未授权。
+
+落库语义：图 base64 解码落 `notes-images/web-{sessionId}-{hash}.{ext}`，md 内 `![name](data:…)` 改写为相对引用（编辑器同解析基座）；标题/URL/站点/作者入会话与页面元数据；投递成功广播 `data:sessions`。
+
+## 三、扩展骨架（app/extension-web-clipper/）
+
+- `manifest.json`：MV3、content script（读已登录 DOM）、popup（端口/token 配置 + 投递按钮）；
+- `content.js`：零依赖轻量 DOM→MD（article/main/公众号 `#js_content` 等选区；标题层级/列表/段落；图：data URI 直带，远程图保留 alt 文本——跨域字节不可读，截图/快照路径补）；
+- `popup.js/html`：参数存 `chrome.storage.local`，点击 → sendMessage 抽取 → fetch `http://127.0.0.1:{port}/ingest`（Bearer token）。
+- 发布：开发期手动加载（扩展管理页→开发者模式→加载已解压）。商店发布（Edge/Chrome/Firefox）周期与审核不确定性登记开放项（v0.20.md 风险 1）。
+
+## 四、与阶段 1/3 的关系
+
+- 阶段 1（URL 静态直取）覆盖无登录墙静态站；本契约同一 `kind=web` 收口（扩展投递与 URL 采集产物同构——会话列表无感同列，Foresight 决策 4）；
+- 阶段 3（整页快照）的渲染型 DOM 内联为独立命令（REQ-305），投递失败不阻断剪藏主路径。
+
+## 五、测试与回归
+
+- 纯逻辑层（web_inbox.rs 5 测：头解析/token 恒定比较/载荷白名单/base64 摘要）+ 收口函数（commands_web_inbox_tests 1 测：会话+图落盘改写）；
+- 网络面人工冒烟：启动服务 → curl -H "Authorization: Bearer x" -d '{"markdown":"正文"}' http://127.0.0.1:{port}/ingest。