Forsion Clip 2.2.0 / 浏览器剪藏

A Manifest V3 extension for Chrome and Microsoft Edge, connected to Forsion accounts, cloud vaults and Forsion Desktop. This independent repository lives at Forsion/Forsion-Clip, alongside Forsion-Genesis. The older reverse-engineering reference is archived locally under apps/Archived/Forsion-Clip-reference and is not part of this repository.

基于已确认的 Genesis 风格 Demo 实现。真正的 Chrome sidePanel、service worker、页面脚本、官方设备登录、云笔记接口和桌面 Unit 配对；没有把 Demo 的模拟状态带入安装包。

What's new in 2.2.0 / 2.2.0 更新

• Connecting to Forsion just works. No welcome page and no address to type: Clip finds Forsion on this computer by itself, and the first time you open the side panel it asks Forsion to connect — click Allow in Forsion and you're done (Tangu browser control comes along in the same step). Installed and dev builds running side by side are both listed; you pick one. Needs a Forsion version with the fixed Clip entrance (Changan-Su/Forsion#473); with an older Forsion whose connection port has moved, add that address under Settings › Connection › Advanced.

• Saves land where Forsion is. Clips go to the vault Forsion has open. If Forsion switched vaults since you looked, Clip stops and tells you once instead of writing somewhere you didn't see.

• A calmer side panel. One paper card for the page, a Chat Box–style composer at the bottom (↵ asks Tangu, ⌘↵ saves), a destination pill with the less common places under "Other places", and errors shown once, inline, with a next-step button.

• Settings laid out like Forsion's. Connection, destinations, templates, reading and the rest in one full-page window; the version number sits at the bottom left.

• Looks like Forsion. Theme colour, background, light/dark and language follow the connected Forsion and stay as they were while disconnected.

• 连 Forsion 不用设置:不开欢迎页、不填地址,Clip 自己在本机找 Forsion;第一次打开侧栏就向它发起连接,在 Forsion 里点「允许」即连上,Tangu 浏览器控制一起开通。安装版和开发版都开着时两个都列出,由你选。需要带 Clip 固定入口的 Forsion(Changan-Su/Forsion#473);旧版 Forsion 的互联口漂走时,到 设置 › 连接 › 高级 手填那个地址。

• 存到 Forsion 正打开的智库;Forsion 刚换过库时这次不写,提示一次再存。

• 侧栏更安静:一张纸卡放网页,底部 Chat Box 式输入卡(↵ 问 Tangu,⌘↵ 保存),保存位置药丸,少用的去处收在「其他位置」;报错只出一处,带下一步按钮。

• 设置照 Forsion 设置窗排,版本号在左下。外观和语言跟着连上的 Forsion,断开后保持原样。

Load in Chrome or Edge / 加载

1. Build with npm ci && npm run build, or unpack the supplied Chrome ZIP.

2. Open chrome://extensions (Edge: edge://extensions), enable Developer mode (Edge: the switch at the bottom of the left sidebar), choose Load unpacked, and select .output/chrome-mv3 (the directory containing manifest.json). Dragging that folder onto the extensions page also works while Developer mode is on.

3. Open a normal HTTP(S) page and click Forsion Clip. The browser's protected pages (chrome://, edge://) and the extension stores cannot be clipped.

4. Connecting to Forsion needs no setup: on install Clip quietly looks for Forsion on this computer, and the first time you open the side panel the connection popover opens by itself. If exactly one Forsion is running, Clip asks it to connect — click Allow in Forsion and you are done (Tangu browser control is enabled in the same step). With an installed and a dev build running side by side, both are listed (installed first) and you choose one. Settings live in Settings › Connection (⋯ › Settings); manual addresses are under Advanced. Language and appearance follow the connected Forsion (the last look is kept while disconnected) unless you choose them in Settings › General.

   连接 Forsion 不用设置:装好后 Clip 在本机找 Forsion;第一次打开侧栏时连接浮层自动弹出,只找到一台就直接发起连接,在 Forsion 里点「允许」即连上(Tangu 浏览器控制一并开通)。安装版和开发版同时开着时两个都列出、安装版在前,由你选。更新后的 Forsion 在本机固定口(安装版 8791 / 8793,开发版 8792 / 8794)留了入口,互联口漂到别的端口也找得到。

Edge loads the same build unchanged: the extension ID comes from manifest.key, and Edge still reports the chrome-extension:// origin, so Desktop pairing and Tangu browser control work as in Chrome. Forsion Desktop's Settings › Browser offers the folder and an "Open extensions" button for each installed browser. On Windows, browsers refuse to open their extensions page from another app, so the button opens a new browser window and copies the address to paste. / Edge 直接装同一份构建（同一扩展 ID，Origin 同为 chrome-extension://），桌面配对与 Tangu 浏览器控制照常可用。

构建命令会从相邻的 Forsion-Genesis 仓库复用 @lcl/components ChatBox、SettingsRow/SettingsSwitch 以及真实主题 token。可用 FORSION_GENESIS_ROOT 指定源码根目录。安装后的扩展不依赖源码仓、开发服务器或 CDN。

Forsion account / 账号

Settings → Forsion account → Sign in opens Forsion's official device authorization page. Complete sign-in there, approve the shown code, then the extension checks identity and stores its own session locally. The extension never asks for an account password.

登录后在剪藏底部选择 Forsion cloud vault，刷新并选择有写权限的智库及文件夹。默认仅新建笔记，不覆盖已有内容；云端成功回执和桌面本地保存是两个独立结果。登出会请求撤销当前会话并清除本地凭据。更换服务地址会清除旧会话，旧令牌不会带到新域名。

Desktop / 桌面联动

1. Clip probes Forsion's fixed loopback entrances (installed build 127.0.0.1:8791 / 8793, dev build 8792 / 8794), any manual addresses, and the addresses of Forsions it paired with before. Instances are told apart by instanceId and build.
2. Opening the side panel the first time shows the connection popover; with exactly one Forsion running it requests pairing right away. Compare the six-digit code and click Allow in Forsion. Pairing grants the existing Unit vault capability; revoke it in Forsion to remove access. Each Forsion is paired separately; Settings › Connection lists them.
3. Saves go to the vault Forsion has open. A save that finds Forsion switched vaults since the panel last looked stops with a notice instead of writing to the other vault.
4. After a confirmed save, Add reading task creates a separate dated Markdown task linked to the note. Continue in Chat starts a real Chat session/run using a Desktop model; enable Desktop remote sessions and approve this device if requested. A started run is not a completed model answer.

桌面保存走现有 Unit RPC，并对同一客户端的库操作串行化。原协议不支持原子的 expectedRoot 写入参数；桌面进程在“校验库 → 写文件”的极小间隔内重启并换库仍是现有协议边界。不会修改 Calendar.db，不会用只负责导航的 forsion:// 链接假装上传。

Tangu browser control / Tangu 浏览器控制

Since 2.1.0 this extension also carries Tangu browser control (formerly the separate Tangu for Chrome extension). Approving Clip in Forsion also hands over the connect code; to connect manually, copy it from Forsion → Settings → Browser and paste it under Settings › Connection › Advanced. Tangu can then list your tabs, read and act in background tabs, and open its own pages in an orange "Tangu" tab group. The bridge is src/lib/tanguBridge.ts; the protocol (loopback WebSocket, two-way HMAC handshake, the token never goes over the wire) is unchanged.

2.1.0 起本扩展并入了原 Tangu for Chrome。扩展 ID 固定为 gpajikakdmhjebadgcbmhidkkajclfoi（manifest.key），Tangu 引擎只认这个来源；上架商店时把对应私钥作为 key.pem 放进 zip 根目录才能保住同一 ID。

Forsion Desktop bundles the build from the npm package @forsion/clip (built extension only, source stays private); npm publish runs prepack, which builds and copies .output/chrome-mv3 to chrome-mv3/.

Capture and reading / 剪藏与阅读

• Article, selection, multiple regions and link-only capture; full Markdown editing, source properties, tags and per-page drafts.
• Defuddle 0.19.5 site adapters, Bilibili part/CID/subtitles, WeChat image fallback, tables, formulas, code, footnotes and sub/sup preservation. Only content accessible to the page is captured; missing subtitles are disclosed.
• Five-color text and image highlights, notes, context-based restoration, global search/management and JSON/Markdown backup.
• In 2.0.1, selecting text or clicking a saved highlight opens the page toolbar: copy, highlight, save, translate, explain, grammar, mnemonic and vocabulary. Google/Bing/current AI translation supports 12 target languages, a separate result window, retry/stop, copying and saving. Settings → Selection toolbar controls order, visibility, colors, site exclusions and prompts. Automatic vocabulary is limited to words/phrases of 200 characters. / 2.0.1 补齐划词与已有划线菜单、独立翻译结果窗和选区设置；200 字符以上段落仍可翻译与保存，但不会自动加入生词本。
• Forsion AI and configured OpenAI-compatible, Anthropic, Gemini or Ollama providers. Summaries, full translation, explanations, grammar, questions and reading cards stream into the shared Genesis ChatBox. Source and question are sent only when you press send. Full translations are segmented; incomplete streams/output limits are reported and partial text is preserved. Sources over 350,000 characters require selecting a smaller region.
• Vocabulary meanings, context, search, review cards, speech and Markdown export.
• Persistent batches from URLs, selected tabs and selected bookmarks; daily and explicit auto-clip domains. Page concurrency (1–5) and destination concurrency (1–6) are configurable. Safe transient failures retry with persisted exponential deadlines (default 1/2/4 seconds); cancellation wins over pending retries. Requests with uncertain delivery or an already-created partial object require explicit retry. A request already sent may complete and its acknowledgement is retained. Interrupted jobs require explicit retry. Confirmed targets are skipped, and retries reuse the captured document.

2.0.2 parity additions / 本轮补齐

• A draggable page-edge launcher: quick capture, preview, AI reading, vocabulary cards, selection-menu toggle, region capture and highlight export. Actions can be reordered/hidden; position and site exclusions persist. Opening AI reading does not send a model request.
• Preview typography (Latin/Chinese font family, size, width and spacing) and a clickable outline derived from the actual rendered headings. / 预览支持字体、字号、宽度、行距和正文标题提纲。
• Standalone long PNG and Print / Save PDF from the current edited document, including selected front matter/highlights. Session-only one-time snapshot; image-load failures are visible. PNG over 32,760 px or 64 MP fails explicitly and offers PDF; no silent truncation.
• Cross-node whitespace-tolerant highlight restoration; WeChat lazy-image recovery; complete formula/table/footnote and video-part metadata preservation.

Focused regression tests: node --import tsx --test tests/background.test.ts tests/queuePolicy.test.ts tests/floatingLauncher.test.ts tests/exportParity.test.ts tests/extractionParity.test.ts tests/paritySettingsUI.test.ts tests/documentExport.test.ts tests/core.test.ts tests/security.test.ts tests/imageBodyCancellation.test.ts tests/obsidianClipboard.test.ts.

Reproducible real-component UI instruments: node scripts/ui-fixture.mjs, node scripts/floating-ui-fixture.mjs (8777), node scripts/document-export-fixture.mjs (8776). These use synthetic local state and do not access the installed extension's credentials. Live public extraction: node --import tsx scripts/public-extraction-acceptance.mts; its report separates public-page results from installed Chrome and authenticated-service acceptance.

Destinations / 保存目标

18 compatible targets: Markdown download, clipboard, Obsidian, Notion, GitHub, flomo, SiYuan, Logseq, Joplin, Feishu, Yuque, Memos, Wolai, FlowUs, GetBiji, S3, OSS and COS. Forsion cloud and Desktop are additional native targets. Configure credentials in Settings → Save & sync; enabled additional targets receive each manual save. Each destination has its own result.

Image hosting supports S3, OSS, COS and Cloudinary. Failed uploads retain original image links and return a warning. External destination implementations use their documented APIs; API availability and account permissions still need real-account validation. Notion/Wolai/FlowUs support typed property mappings; GitHub/SiYuan/Joplin/Memos support opt-in native image attachments, and Joplin can synchronize tags. Image fetch/upload failures keep original links and warnings; a partially created remote document retains its ID and is never automatically duplicated. Protocol references and explicit format limits: export adapter notes.

Markdown download can also produce an offline ZIP (Save & sync → Markdown → Attachments). It preserves the complete document and bundles public HTTP(S) Markdown and HTML images into a configurable asset directory; failed images keep their original link and are listed in the archive report. Limits: 20 MiB per image, 100 MiB total, 200 images. HTML images, picture/srcset and relative image URLs are resolved against the source page; data/blob URLs are preserved with a report. / Markdown 下载支持离线图片 ZIP，失败保留原链并附报告；上述格式与大小边界会明确提示。

Obsidian/Logseq return handed off, not a confirmed saved file. A manual Obsidian save above 30,000 encoded URI characters writes the complete document to the clipboard, then opens the official clipboard=true URI after that write succeeds. Large Obsidian queue jobs and oversized Logseq URIs fail explicitly without truncation; queue workers cannot overwrite each other's clipboard handoffs. Chrome downloads return a download ID; completion is visible in Chrome's downloads page. Wolai unsupported rich constructs preserve the source as text with a warning.

MCP

The bridge is opt-in. It listens on loopback only and requires a random token of at least 24 characters. The extension and MCP process must use the same token. No browser debugging port or native host installation is required.

Example MCP client configuration (replace paths and token locally; never commit real tokens):

{
  "mcpServers": {
    "forsion-clip": {
      "command": "node",
      "args": ["/absolute/path/forsion-clip/scripts/mcp-server.mjs"],
      "env": {
        "FORSION_CLIP_BRIDGE_TOKEN": "replace-with-a-long-random-token",
        "FORSION_CLIP_BRIDGE_PORT": "18365"
      }
    }
  }
}

Install this project's dependencies before starting the server. In extension settings, use ws://127.0.0.1:18365, paste the matching token and enable the connection. Exposed tools: browser_tabs, clip_extract, clip_save. Enabling the bridge authorizes the connected local AI client to use those capabilities. Keep it disabled if unused.

The delivery also includes a minimal forsion-clip-2.0.0-mcp.zip companion. Unpack it and run npm ci --omit=dev; use its mcp-server.mjs path in the same configuration. / 也可使用交付中的独立 MCP 包，无需安装整个源码项目的开发依赖。

Permissions and privacy / 权限

Page scripts cannot access extension local storage. Token-bearing calls are confined to trusted extension contexts; page data crosses a narrow, source-validated message interface. Synthetic webpage clicks cannot trigger privileged toolbar saves. Credentials stay out of normal configuration exports; re-enter destination/image credentials after importing. No SmartClip private account service, telemetry, remote executable code, or browser history API is used. Chrome labels the tabs permission broadly as browsing access.

Verification / 验证

npm run check
npm test
npm run build
npm run package
npm audit --omit=dev

Tests include actual Defuddle DOM extraction, source fidelity, malicious synthetic clicks, account/Unit contract fixtures, cloud origin race, idempotency, queue cancellation/restart, streaming, 18 adapters and image signatures, UI vocabulary/annotation interactions, and the actual Node MCP stdio ↔ authenticated loopback WebSocket transport. Synthetic fixtures are not live account or third-party acceptance. The delivery report records real Chrome/desktop/account checks separately.

New tests never load a browser profile or perform real account writes. tests/fixtures/article.html is a synthetic, non-private article for explicit live acceptance.

For isolated selection UI verification, run node scripts/selection-ui-fixture.mjs and open its loopback URL. It uses real production toolbar/result modules with synthetic storage and deliveries. Optional live Google/Bing mode accepts only the fixture article text; it does not connect to an account or AI provider. / 隔离划词验收脚本使用正式组件与合成存储；可验证真实 Google/Bing 翻译，但不能据此声称已完成安装版端到端验收。

2.0.2 parity continuation (unreleased)

• Vocabulary now imports original-compatible CSV atomically with duplicate skipping, edits source sentences, filters by time/source and exports the current selection safely for spreadsheets.
• Document properties support enabled/visible fields, renamed keys, custom typed fields and date formatting. New captures snapshot the definitions; old drafts keep their original field names.
• Reading presets support create/edit/reorder/disable/reset. Long translations retain custom instructions in every source segment. Selected messages or a complete reading conversation can be saved without altering the source draft.
• Illustrated cards now have a real plan/review/generate/download workflow through Forsion account image models or a configured OpenAI-compatible image provider. Calls are serial, failures do not auto-retry, and completed images survive cancellation and panel navigation within the current page session. Download before closing/reloading the extension page.
• YouTube captions survive Defuddle sanitization, with chapter and timestamp links. Public production-module acceptance retained 129 caption segments and 12 chapters.
• Markdown filenames support {date}, {time}, {slug}, {title}, {site}; asset folders support {fileName}. Images can be preserved, zipped, or downloaded separately. All relative downloads stay below the browser download directory.

Evidence boundaries: production-module tests and HTTP component fixtures are distinct from installed Chrome. The browser tool rejects extension management/internal pages, so this revision has not been automatically reloaded into the user's Chrome. Cloud account image generation, third-party account writes and MV3 lifetime under actual slow image generation are not claimed as verified. See the current HTML acceptance report for exact evidence.