CC ──fetch.mjs(一次性)──HTTP /command──▶ daemon ──WebSocket──▶ Chrome 扩展
                                          ▲ 127.0.0.1:19925     └ 后台开标签页跑导出
                                          └ 流式回传进度/产物 ──▶ 解包到 <输出目录>/<文档名>/

daemon

scripts/bridge/

fetch.mjs

<输出目录>/
└── 无监督数据修复/          ← Folder named after document title
    ├── 无监督数据修复.md
    └── images/              ← Images are referenced inline with relative paths
        └── xxx.png

• The extension is a WS client that actively connects out to the local daemon — no native messaging, no system-level installation.
• The daemon is automatically launched on demand by this skill and runs persistently (exits automatically after 30 minutes of idle time), bound only to

  127.0.0.1

  .
• fetch.mjs is one-time: Exits immediately after completion, does not run in the background.

node ~/.claude/skills/larksnap-fetch/scripts/fetch.mjs <Feishu link> <output directory> [--format md|pdf|html] [--profile <code>]

• <output directory>

  is the parent directory; the output will be saved to the subfolder

  <output directory>/<document name>/

  (each document is stored independently to avoid confusion).

• --format

  defaults to

  md

  . For

  md

  /

  html

  , images will be downloaded and referenced inline with relative paths in the

  images/

  subfolder of that directory;

  pdf

  availability depends on tenant capabilities.
• Progress is output to stderr, and the result path is output to stdout (the absolute path of the document's subfolder follows

  ✓ Exported to

  ).

• --profile <code>

  : When multiple browser profiles are connected to the daemon simultaneously, specify which one to use (the code can be found in the Profile section of the extension popup and copied via the Copy button). Not required when only one profile exists.

0

1

2

3

4

5

edit.mjs

node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> new-doc [<md file>] --name "<title>"
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs new-doc [<md file>] --name "<title>" [--host <authorized domain>]  # No link required
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs hosts [--profile <code>]   # Read-only list of authorized domains
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> append <md file>
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> insert-after "<title text>" <md file>
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> list-blocks
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> find-blocks "<keyword>" [--regex] [--type <type prefix>] [--limit N]
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> replace-block <block ID> <md file> --expect "<content summary>"
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> delete-block <block ID> --expect "<content summary>"
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> insert-after-block <block ID> <md file>
node ~/.claude/skills/larksnap-fetch/scripts/edit.mjs <link> replace-all <md file> --expect-first "<first block content summary>"

• Content to be written must first be saved to a local md file, then pass the file path to the command (do not use command line parameters to avoid escaping and length issues); maximum size is 2MB.

• new-doc

  Create new document: Creates a docx in the root directory of My Space. The

  <link>

  here is only used to locate "which tenant/domain to create under" — you can pass the tenant's drive homepage (

  /drive/me/

  ) or any document link.

  <md file>

  is optional: if provided, the content will be written automatically after creation (reusing append); if not provided, an empty document will be created.

  --name

  sets the title (defaults to "Untitled" if not provided). On success, outputs

  {ok:true, url}

  , where

  url

  is the address of the new document, which can be used for subsequent

  fetch

  or editing operations. Only docx is supported (works for both public and private clouds).

• new-doc

  can be used without a link: When

  <link>

  is omitted, it automatically uses the extension's "authorized domain list" to locate where to create the document — if there is only one authorized domain, it will be used directly; if there are multiple, you must specify it with

  --host <domain>

  (accepts the full base domain or a unique abbreviation; if ambiguous, it reports

  host_ambiguous

  ; if not in the list, it reports

  host_not_authorized

  , and the error message includes the full list of optional domains).

  --host

  only works with link-free new-doc; other operations (append/insert-after/…) still require a document link. Private domains are more stable than public clouds: When the user authorizes a private domain in the sidebar, the extension records the real tenant entry; public clouds (feishu.cn, etc.) have no authorization action to capture, and can only be located as a fallback when a

  *.feishu.cn

  tab is open. If

  need_landing_url

  is reported, follow the prompt: use the old method to provide a link under that domain this time, or ask the user to open a page under that domain in the browser (or re-authorize) before re-running. The personal version

  my.feishu.cn

  has different interfaces, and

  --host my.feishu.cn

  is not guaranteed to succeed on the first try; if it fails, follow the prompt to use the old method.

• hosts

  View authorized domain list (read-only): Outputs

  {ok:true, domains:[{host,kind,sampleUrl}]}

  —

  kind

  is builtin (public cloud built-in)/trusted (user-authorized private domain), and

  sampleUrl

  is non-empty indicating that the domain supports link-free document creation. Add

  --profile <code>

  when multiple browser profiles exist. If

  extension_outdated

  is reported, the extension in the browser is too old (bridge protocol <v4); ask the user to rebuild/update and reload the extension in chrome://extensions.
• Only supports docx / wiki documents; spreadsheets and multidimensional tables are not supported for editing.
• Block-level operations require locating first: If you know what content to find (especially in long documents), use

  find-blocks

  first, which only returns matching blocks; use

  list-blocks

  to output the full structure

  {blocks:[{id,parentId,type,depth,childCount,summary}]}

  only when you need to see the overall structure, where

  summary

  is the first 80 characters of the block content.

  replace-block

  /

  delete-block

  must include

  --expect "<summary>"

  (copy the

  summary

  of the target block from the list-blocks / find-blocks output exactly) — the extension compares the current content of the block before execution, and reports

  block_changed

  if it does not match, preventing incorrect modification/deletion of blocks after concurrent changes to the document. Deleting a container block (list/quote, etc.) will delete its child blocks together; use

  parentId

  /

  depth

  /

  childCount

  to confirm that you won't accidentally delete an entire section before proceeding.

• find-blocks

  Search blocks by content (read-only): Matches against the full plain text of the block (not limited by the 80-character summary), defaults to "whitespace-removed + case-insensitive" substring match;

  --regex

  matches using JS regular expressions (

  iu

  flag);

  --type <prefix>

  filters by block type (e.g.,

  --type heading

  only searches for headings);

  --limit N

  controls the maximum number of returned results (default 20). Outputs

  {total,shown,blocks:[{...,summary,snippet}]}

  : if

  total > shown

  , it means hits are truncated; use more specific keywords;

  summary

  is exactly the same as in list-blocks and can be directly used as

  --expect

  , while

  snippet

  is the context of 40 characters before and after the hit (the hit word is marked with 【】) only for confirming that the correct block is found, do not use it to fill in

  --expect

  . If no hits are found, returns

  total: 0

  with exit code 0, which is not considered an error. To search for content starting with

  --

  , use

  --regex

  with escaping. If "Unknown edit operation" is reported, the extension in the browser is too old; ask the user to reload/update the extension.

• insert-after

  matches exactly by title text: reports

  anchor_not_found

  if not found, and

  anchor_ambiguous

  if multiple matches are found (in this case, use

  insert-after-block

  to locate by block ID).

• replace-all

  is the most dangerous operation (replaces the entire body of the document, keeping the document title), and the process must be: ① First use

  fetch.mjs

  to export the original document to local for backup; ② Get the

  summary

  of the first block from the

  list-blocks

  output; ③ Pass it as

  --expect-first

  exactly. The extension compares the first block of the current document before execution, and reports

  block_changed

  if it does not match (indicating the document has been modified; repeat steps ①②). Do not execute replace-all without a backup.
• Image writing:

  ![](image)

  in md supports three sources — local path (relative path is based on the directory of the md file), external http(s) link (automatically downloaded and embedded), and data URI. Only png/jpg/jpeg/gif/webp/bmp formats are accepted (svg/ico will be silently discarded by Feishu, and the CLI will directly report

  image_unsupported

  ). If the overall size exceeds 2MB after image embedding,

  image_too_large

  is reported (compress the image or split the writing); if external link download fails,

  image_fetch_failed

  is reported; if the local file is missing,

  image_not_found

  is reported. Writing with images automatically switches to HTML paste mode (Feishu only recognizes data URI images in HTML paste), with the side effect: md tables in the same write operation will be pasted as embedded spreadsheets instead of native tables — try to write images and tables separately. For pure image writing (no text), the read-back verification is determined by the net increase in the number of image blocks.
• Success of writing is determined by read-back verification: After editing, the full text is re-exported to confirm that the new content has been saved before returning success. If

  save_unconfirmed

  is reported, the content may have been written to the document; do not blindly re-run (it may write twice), ask the user to open the document and confirm manually.
• If you want to perform block-level operations after successful editing, re-run

  list-blocks

  first. Feishu blocks are addressed by ID; the IDs of blocks that have not been modified remain valid after editing, but two types of references will definitely become invalid: ①

  replace-block

  will change the block ID (Feishu handles it as "delete old block + insert new block"), and the old ID will become invalid directly; ② You do not have the block ID of the newly written content. Using the old list will result in

  block_not_found

  /

  block_changed

  ; re-running

  list-blocks

  is the easiest solution.
• Edit-specific exit codes:

  6

  = Logged in but read-only for the document (

  need_edit_permission

  ), ask the user to confirm/apply for edit permissions in the browser before re-running;

  7

  = Extension lacks debugging permissions (

  need_edit_grant

  , usually an old version of the extension without editing functionality is installed), ask the user to update/reload the extension. Other exit codes are the same as fetch.mjs.
• Edit-specific error subtypes (exit code 1):

  anchor_not_found

  /

  anchor_ambiguous

  /

  block_not_found

  /

  block_changed

  (retry after re-running list-blocks) /

  save_unconfirmed

  (manual confirmation) /

  inject_failed

  .

• extension_outdated

  (exit code 5): The extension version is too old to support editing; ask the user to update/rebuild the extension.

• Only

  md

  is supported: Requesting

  --format pdf/html

  will directly report an error without opening a tab.
• The output is a single

  .md

  file, saved to

  <output directory>/<page title>/<page title>.md

  ; Images are kept as absolute external URLs (

  https://...

  ) and not downloaded locally (unlike Feishu documents, there is no

  images/

  directory; exception: Xiaohongshu images will be localized, see the next section).
• If the domain is not authorized, exit code

  4

  is returned, prompting the user to click "Authorize access to this domain" in the extension sidebar on that web page before re-running.
• Frontend-rendered pages (SPA) may capture incomplete body content due to page loading strategies, which is a known limitation; static article pages work best.

• The user must first log in to Xiaohongshu in Chrome (the note detail page must have a login state); if not logged in, exit code

  3

  is returned, with the prompt including

  xiaohongshu.com

  ;
• Authorization for the

  xiaohongshu.com

  domain is required (exit code

  4

  is returned for the first time, follow the prompt to authorize);
• Must use the full sharing link with

  xsec_token

  (links copied from the "Share" function in the app/web version come with it; bare

  /explore/<id>

  links are no longer accessible);

  xhslink.com

  short links can be used directly and will automatically redirect to the full link;
• The output Markdown includes title, author, publication time, interaction count, body, images, and tags; images will be downloaded to the local

  images/

  directory and rewritten with relative paths (Xiaohongshu CDN links have time-sensitive signatures and will expire if left as-is; if a single image fails to download, the external link will be retained without affecting the whole); videos are kept as external links and not downloaded, and the direct link signature may expire, so save them as soon as possible.

node ~/.claude/skills/larksnap-fetch/scripts/arxiv.mjs <arXiv link or ID> <output directory> [--pdf-only|--html-only]

• Fully compatible with links and IDs: bare ID (

  2601.18226

  ),

  arXiv:

  prefix, three types of

  arxiv.org

  links (abs/pdf/html, including

  .pdf

  suffix and

  v2

  version number), and old-style IDs (

  math.GT/0309136

  , slashes are replaced with underscores when used as directory names).
• The output is also saved to an independent folder named after the ID:

  <output directory>/2601.18226/2601.18226.pdf

  +

  .html

  +

  .md

  .

• <base>

  is injected into the HTML, so images/styles are resolved to absolute addresses on arxiv.org, and local opening will not break images (images themselves are not downloaded locally).
• Markdown is converted from HTML on-site with zero external dependencies (turndown is packaged in

  scripts/vendor/

  , no need for pandoc): formulas are restored to

  $...$

  /

  $$...$$

  using the alttext from LaTeXML, images/reference links are absolute addresses on arxiv.org; complex tables are retained as embedded HTML. Conversion failure only affects

  .md

  , while PDF/HTML are saved normally.
• It is normal for some papers to not have an HTML version (arXiv only provides HTML for papers with LaTeX sources that have been successfully converted, and old papers may also have been retroactively converted): in this case, only the PDF is saved, exit code is still 0, and there is an

  ℹ

  prompt in stderr — do not retry as a failure.
• Exit codes:

  0

  Success |

  1

  Failure |

  2

  Usage error; the error contract is the same as fetch.mjs (when exiting with non-0, the last line of stderr is a JSON object, follow the

  hint

  branch).

yt-dlp

~/Downloads/larksnap-video/

• This function has no CLI entry, and can only be triggered from the extension sidebar; the responsibility of this skill is to distribute the new version of the daemon.
• Additional dependencies on

  yt-dlp

  and

  ffmpeg

  (only used for video download, not required for capturing/editing Feishu documents): macOS:

  brew install yt-dlp ffmpeg

  ; Windows:

  winget install yt-dlp.yt-dlp Gyan.FFmpeg

  . If missing, the sidebar will receive a clear installation prompt, which does not affect other functions.
• When the daemon is an old version, the download button in the sidebar will prompt to update this skill; after updating the skill files, kill the old daemon (

  pkill -f bridge/daemon.mjs

  or wait for it to exit automatically when idle).

{"ok":false,"error":{"type":"authentication","subtype":"need_login","message":"需要登录：浏览器里没有该域名的飞书登录态。","hint":"让用户在 Chrome 中打开该文档域名并登录飞书，登录完成后重跑本命令。","retryable":false}}

• message

  = What went wrong (for human reading);

  hint

  = What to do next (imperative, follow it);

• retryable: true

  = No changes needed, re-running the command directly may succeed;

  false

  = Take action according to

  hint

  first (usually requires user operation), then re-run.

• type

  /

  subtype

  are closed enums, and exit codes are derived from subtypes:

bad_args

profile_not_found

profile_ambiguous

host_ambiguous

--profile

--host

need_landing_url

need_login

need_domain_auth

host_not_authorized

--host

daemon_missing

daemon_spawn_failed

daemon_timeout

bridge_request_failed

extension_not_connected

extension_outdated

extension_timeout

signature_invalid

export_failed

write_failed

no_result

unexpected

1. Run the command directly (user-provided link + user-specified local directory; if the user does not specify a directory, it defaults to the current working directory). The daemon will be automatically launched.
2. Non-0 exit → Parse the last line of JSON in stderr, follow the

   hint

   to execute, do not guess:

   • retryable: true

     → After completing the hint (e.g., click the extension icon to wake it up), re-run the same command directly; if the same error occurs twice in a row, stop and ask the user.

   • retryable: false

     → If the hint requires user operation (login/authorize domain), relay the hint to the user, wait for the user to confirm completion, then re-run.
3. Exit code 0 → Tell the user the written files listed in stdout (path format like

   <document name>/<document name>.md

   ). The output is in the subfolder

   <output directory>/<document name>/

   (md includes the

   images/

   subdirectory referenced with relative paths), and each document is stored independently.

1. Run

   npm run build

   in the root directory of the larksnap repository.
2. Go to

   chrome://extensions

   , enable "Developer mode" → "Load unpacked" and select the

   dist/

   folder.
3. Click the extension icon to wake up the background Service Worker — it will automatically connect to the local daemon (the daemon is launched by the first

   fetch.mjs

   run).

No need to bind the extension ID or write any system manifest. To switch machines, just repeat these three steps (and copy this skill directory to the new machine's

~/.claude/skills/

).

• Check

  ~/.larksnap/daemon.log

  to see if the daemon is listening, if the extension is connected, and if tasks are dispatched;

  ~/.larksnap/daemon.pid

  is the PID of the listening instance.
• Connection issues: Confirm Chrome is open and the extension is loaded; when the extension background is dormant, the first command may need to wait for it to reconnect via

  /ping

  (alarms ~24s), clicking the extension icon can wake it up immediately.
• Port conflict: The daemon defaults to

  127.0.0.1:19925

  , which can be changed with the environment variable

  LARKSNAP_PORT

  (must be consistent with the

  PORT

  in the extension's

  src/background/bridge.ts

  ).
• Missing images/failed export for a domain: Mostly due to not authorizing the domain with "base domain wildcard" (including the image drive-stream subdomain), re-authorize in the sidebar.
• Version drift: When fetch.mjs detects that the running daemon version is inconsistent with this skill, it will automatically restart to the version included with this skill (old skill copies installed in multiple projects will not break silently, but it is recommended to update old skill copies as well); the extension and daemon report protocol versions to each other during WS handshake, and the popup will prompt for an update if they are inconsistent.
• Security: The daemon only binds to the loopback interface, verifies the Origin (rejects non-

  chrome-extension://

  requests) and requires the

  X-Larksnap

  header to block web CSRF; requests from CLI→daemon have an additional HMAC-SHA256 signature (key is in

  ~/.larksnap/secret

  , 0600 permissions, automatically generated on first run; the signature covers timestamp/method/path/body digest, 60s anti-replay, no fallback) to block impersonation from other identities on the machine. The extension's WS cannot read the key file, so Origin verification is maintained (known limitation).