Work with the workspace via the Outline Wiki MCP—Search / Read(search / read)+ Write / Edit
(create / edit)+ Extended write operations(image attachments / @mention / comments / Collection management / move / delete / archive), with output following the repository's existing Markdown style fingerprint (* bullet /
==高亮== / first body block ```yaml metadata block, etc.), and controlling the upload format per OKF (Open Knowledge Format)—so that Outline documents can be read back and understood by the agent.
This skill is the only one in the outline-wiki familyoperations skill (search / read / write all in one); MCP server access and authentication are maintained in the agent configuration file (see §Access).
Input / Output
Input
At startup, the followingprerequisitesmust be in place (for MCP server access and authentication, see §Access):
- MCP is registered: the current session can call outline MCP tools (if not registered, configure per §Access and thenrestart the sessionand come back)
- Collection ID(required when writing documents; if the schema allows referencing by name, call it per the schema)
- User's natural language instructions: search keywords / document ID / create and edit instructions, target Collection
Output
- Search results: list of matching documents (including ID, title, summary / context excerpt)
- Document content: metadata (title / Collection / time / author, etc.) + Markdown body
- Create / edit results: new document ID + URL; or the updated version returned after patch
- Image attachment ID: returned after completing the 3 attachment steps
/api/attachments.redirect?id=<uuid> - Error messages: tool name mismatch / invalid document ID / attachment 0 bytes / Markdown newlines swallowed / connection refused, etc.
Access (when MCP is not registered)
The MCP server is read in once at agent startup,mid-session config changes will not be re-read—when not registered, you need to add the server in the agent configuration file and thenrestart the session. This skill does not perform configuration operations, and only provides minimal access information:
- endpoint:
https://<your-subdomain>.getoutline.com/mcpor self-hostedhttps://<your-domain>/mcp(path is fixed as/mcp) - Authentication:
Authorization: Bearer <API key>(generated in Settings → API) or OAuth - On-disk location(varies by agent):
- opencode:
~/.config/opencode/opencode.json#mcp.outline(type: remote+url+headers.Authorization) - Claude Code: project root
.mcp.json(project scope) or~/.claude.json#mcpServers.outline(user / local scope)
- opencode:
- Verification: after restarting, you can see the outline MCP tools (
tools/listcan fetch the list)
401 / 403:Authorization key in the header has expired / been revoked—regenerate the key and update the configuration (changes take effect after restarting the session).
Connection refused: confirm that the workspace's Settings → AI MCP toggle is enabled (self-hosted requires an administrator to enable it in the console); for intranet tunneling / reverse proxy environments, make sure to use https://——The HTTP port may be occupied by a
middlebox returning an empty 200, while the real MCP only passes through to the upstream on HTTPS 443.
Design decisions (write Markdown according to ProseMirror JSON's "projection")
What Outline persists is the ProseMirror node tree, while MCP only accepts Markdown strings—before writing each piece of Markdown,
first think about which node it will be parsed into; do not use syntax that the schema does not accept, and for things Markdown cannot express (such as colored
highlighting), use "Advanced". The complete principles, §1-§13 mapping table, image attachment upload process, and @mention syntax are all in
references/doc_style.md, and this file only lists a style quick reference + key anti-patterns.
OKF upload format (agent-readable baseline)
Why: documents pushed to Outline must be able to be read back and understoodby agents—the OKF (Open Knowledge Format, "markdown + frontmatter") metadata header + predictable body structure are prerequisites for readback / retrieval / chunking. For the complete definition, field table, type enum, carrier selection tests, and minimal skeleton example, see
references/doc_style.md→ OKF agent-readable baseline。
Outline-side carrier (SSOT in doc_style.md): the OKF standard uses ---...--- frontmatter,
but Outline's MCP round-trip testsdo not support(--- it ( --- is eaten, YAML leaks into visible body text),
so the carrier = the first body block ```yaml fence(stored as code_block and preserved verbatim), while title is carried by
Outline's native field and does not go into the block.The only hard threshold is type non-empty—all other fields are
uniformly tolerated by consumers, and should be filled in whenever possible (description / tags / created / updated);
okf_version(single document without a bundle) and title are not placed in this block;x-outline is an optional provenance block.
Body structure discipline: the yaml block is the first block of the body (nothing before it); headings start from ## ,
do not skip levels, and do not have duplicate names at the same level (agents use headings as chunking anchors); one topic per document; links use Outline
links / absolute URLs, and do not write bare local relative paths.
MCP tool discovery (important)
This skill does not hard-code any tool names—at the start of a session, you must first call MCP's
tools/listendpoint, verify the tool names, parameter schemas, and return structures actually exposed by the current MCP server, and then call accordingly. Convention: "search / read / create / edit / image attachment / comment / Collection management" etc. appearing below refer tocapabilitiesrather than specific tool names; before calling, firsttools/listto get the real tool names and then map them.
Different self-hosted deployments may have slightly different tool sets; extended capabilities (such as comments / image attachments)
also depend on what tools/list actually returns. Reference (current server tests):list_documents /
fetch / list_collection_documents / list_collections / create_document /
update_document / create_attachment / list_users / list_comments /
create_comment / update_comment / delete_comment / create_collection /
update_collection / delete_collection / move_document / delete_document /
restore_document / list_templates。
Capability list
divided into two groups by "tool source".Core capabilitiescorrespond to the 4 high-level operations explicitly listed in the official documentation (search / read / create / edit);Extended capabilitiescorrespond to tools not explicitly listed in the official documentation but currently available in server tests, and usually also exposed in different self-hosted deployments.
Core capabilities
1. Search
Perform a full-text search in the workspace by keyword, returning a list of matching documents (including metadata + context
Body excerpt snippet; for short documents it is close to the full text, for long documents it will be truncated—Do notuse this alone to judge the full text).
Typical parameters (specific values are subject to what tools/list actually returns):
query: search keyword (required)collection_id(optional): limit the Collection scopelimit/offset(optional): pagination
2. Read
Retrieve metadata by document ID (title / Collection / time / author, etc.) + Markdown body.
Outline MCP serverreturns 2 content blocks: block[0] = JSON metadata,
block[1] = complete markdown body. Most native MCP clients (such as opencode) can fully receive
both blocks and get the body directly;if the current client only presents the first block (such as Claude Code,
tested on 2026-07-01), get the body via the REST bypass POST /api/documents.info
(see §Troubleshooting item 1 for curl).
3. Create
Create a new document under the specified Collection; if you need a nested subpage, pass in the parent document ID.
Typical parameters:
title(required)content(required): Markdown source textcollection_id(required): target Collectionparent_document_id(optional): parent document ID (set when creating a subpage)
4. Edit
Modify the title or Markdown body of an existing document.
Typical parameters:
id(required): target document IDtitle(optional)content(optional)editMode(optional):replace(full replacement, default) /append/prepend/patch(precise partial replacement, used withfindText)
Note: the edit operation may require passing the complete body, or it may support partial replacement;the parameter schema actually returned by
tools/listis authoritative。
Extended capabilities
The following tools are not explicitly listed in the official MCP documentation, but are capabilities actually exposed by the current server (and most self-hosted deployments); this skill includes them and treats them as formal processes. Before use,
tools/listjust confirm.
5. Image / file attachments (create_attachment + fetch attachment)
MCP create_document / update_document only accepts Markdown strings,does not accept
file binaries. To embed an image or file into a document, you must first go through the attachment channel
(create_attachment → curl upload → reference the attachment URL in Markdown), 3-step
process + curl template; see the "Workflow / Steps / Image insertion / File attachment workflow" section below.
6. @mention a user (list_users)
list_users Look up workspace members by keyword (name / email); with Markdown syntax
@[Display Name](mention://user/<userId>) you can @ a specific user in the document, and the Outline
UI will render it as a clickable link.
7. Comments (create_comment / list_comments / update_comment / delete_comment)
Create / list / modify / delete comments under the specified document (or top-level / inline); supports nested replies
(parentCommentId)。update_comment can also resolve / unresolve top-level comments
(status: resolved / unresolved). For other people's documents, it is recommended to first list_comments look at the existing
discussion before deciding whether to create a new comment or reply.
8. Collection management
list_collections: list Collections visible in the workspacelist_collection_documents: return the complete document tree of the Collection (including nested subdocuments)create_collection/update_collection: Create / modify Collection (name / description / icon / color)delete_collection: Delete Collection; can setarchive=trueto archive
Note: deleting a Collection willcascade-deleteits non-archived documents under it; before batch moving, first use
list_collection_documentsto see the structure clearly.
9. Move / Delete documents
move_document: move a document under another Collection or parent document; can specifyindexto control same-level orderingdelete_document: delete a document (by default goes to trash, recoverable from trash within 30 days); can setarchive=trueto archive directly andnot go trash
Document style (repository fingerprint quick reference)
For the complete Markdown ↔ ProseMirror mapping, image attachment upload flow, colored highlights, and other features that Markdown
cannot express, see references/doc_style.md.
The last line of defense before writing a new document / major rewrite is
references/style_checklist.md 's 9 major categories of
checklist—checking through them in order avoids 90% of style drift.
Style baseline (quick reference table)
| Element | Repository convention | Description |
|---|---|---|
| OKF metadata block | First block of body ```yaml metadata block; hard gate type(requirements and fields see §OKF Upload Format) |
agent-readable baseline |
| OKF title | Use Outline's native title field,notin the yaml block | avoid duplication |
OKF okf_version |
Single documentdo not write(the standard is only declared at the bundle root index.md ) |
no bundle for a single document |
| top structure | first block of body = OKF yaml; if followed by a Reference section, follow ## Reference |
standard + OKF constraints |
| Heading levels | # / ## / ### express logical hierarchy; body starts from ## without skipping levels (title is passed separately, see §OKF Upload Format) |
standard + MCP constraints |
| Bullet marker | *(do not use - / +) |
repository unified |
| highlight | ==text== mark key terms / parameters / statuses |
repository fingerprint (default color) |
| code block language | required (bash / python / ...) |
habit |
| Shell prompt | $> followed by one space |
repository-specific convention |
| Images |  |
attachment reference, see doc_style.md §7 / §12 |
| @mention | @[Name](mention://user/<userId>) |
server extension syntax, see doc_style.md §13 |
| Mermaid identifier | ```mermaidjs(not mermaid) |
repository fingerprint |
| language | Chinese narrative + English terms mixed | habit |
| line width | follow .markdownlint.jsonc MD013 |
threshold see doc_style.md §3 |
Anti-patterns (look before writing)
Dual-written with the "Anti-patterns" section of doc_style.md: this table is a standing gate summary, the full version is in doc_style— new entries must be synced on both sides.
- the first block of body is not OKF ```yaml metadata block, or the block is missing a non-empty
type(the agent skips it on read-back; see §OKF upload format for hard-gate details) - Put OKF
titlewritten repeatedly into the yaml block (title is already carried by the Outline field) - Write in the yaml block
okf_version(the standard declares it only at the bundle rootindex.md; a single document should not have it) - Write bare
---...---frontmatter in the body text——the Outline round-trip will eat---, and the YAML leaks into visible body text (confirmed by actual testing) - Use
-or+to start bullets (breaks uniformity) - The body text starts with H1 (title is already passed separately; adding a body H1 duplicates the title)
- Expect
==text==to appear with colored highlighting (Markdown cannot express this; see doc_style.md §Advanced for details) - Invent syntax not supported by Outline (
!!!, HTML tags, etc.) - Introduce external private extensions (MathJax,
:::tip, etc.) - Large stretches of plain paragraphs without bullets (plain paragraphs are rarely used in the repository)
- Reference local image paths that have not been uploaded (they will only render as broken images; you must go through the attachment flow first)
Paper notes / design documents: key architecture diagrams / schematic diagrams are required by default
In the repository, documents such as 论文笔记 Collection、数据结构与算法 → 索引类 suchwhose core is to present system
/ algorithm design,key architecture diagrams
/ schematic diagrams are a default requirement——not optional. For the criteria and the complete operational flow, see
references/style_checklist.md §9。
Execution principles / boundaries
Core principles
- Search before writing (Read-First)
- Before creating a new document, you mustfirst search to check for duplicates, to confirm whether a similar but outdated document already exists
- If a similar document already exists, use edit to update it rather than create a duplicate
- Search results are displayed sorted by relevance; do not directly read using a cached ID (documents may be archived / renamed)
- Strict Markdown format
- Outline Wiki is a Markdown-first platform; all content must use valid, pure Markdown
- Use
#/##/###to reflect logical hierarchy and automatically generate a clear table of contents - Do not introduce non-standard private extension syntax not supported by Outline Wiki
- Verify tool names (Tools-First)
- Do not assume the spelling of tool names or whether they have prefixes (such as
outline_/mcp__outline__) - Before any operation, first
tools/listto get the real tool list
- Do not assume the spelling of tool names or whether they have prefixes (such as
- Capability boundaries are handled in two groups
- Core capabilities(search / read / create / edit): explicitly listed in the official documentation; call directly
- Extended capabilities(image attachments / @mention / comments / Collection management / move /
delete): actually exposed by the server but not listed in the official documentation; before calling,
tools/listconfirm whether it is exposed - When the user requests operations such as "share / export / permission adjustment", clearly inform them that these are not covered by this skill, and suggest using the Outline Wiki UI itself or calling the REST API directly
- Confirm destructive operations first
- Deleting / archiving others' documents, moving documents, changing Collections, etc.destructive operationsmust first be explicitly confirmed within the session
- for others' documents, it is recommended to use
create_commentto propose rather than directly overwrite
Boundaries
- Do nothandle knowledge bases other than Outline Wiki
- Do notattempt operations when MCP is not enabled (first configure according to §Access and restart the session)
- Do notgenerate / revoke API Keys on the server side (that is an operation performed by Outline Wiki users in Settings → API )
Workflow / Steps
Standard process
- Verify configuration and tools: at the start of the session——
- confirm that the outline-related MCP tools are registered in the current session; if not registered, configure the MCP server according to §Access andrestart the sessionthen come back
- call MCP
tools/listto get the actual tool list (the real tool names and parameter schemas corresponding to the core capabilities + extended capabilities respectively)
- Understand intent: map the user's natural language instructions to one of the capability lists (core or extended); see whether the user's intent includes a write action ("find it and change it" → go directly into the editing process; "find it and tell me the content" → read-only)
- Search first, then write: before involving "create / edit", first search to check for duplicates / locate the target document;
before involving "images", first confirm that the attachment channel (
create_attachment) is available - Execute the operation:
- call the corresponding tool
- Organize the body: when writing a new document / making major rewrites, the body'sfirst blockshould write OKF ```yaml metadata
block (requirements and fields are detailed in §OKF upload format), with the title starting from
##without skipping levels - for image scenarios, follow the 3 steps "create_attachment → curl upload → Markdown reference to attachment URL" (see "Image insertion / file attachment workflow" below for details)
- for comment scenarios, first
list_commentsto look at the existing discussion before deciding whether to create a new one or reply - when writing paper notes / design documents, key architecture diagrams should by default go through these 3 steps for embedding, do not write text placeholders (see the "Document style / paper notes" subsection above)
- Destructive operations(delete / move_document / delete_collection) require confirmation first
- Verify the result: check whether the return indicates success; on failure, locate it according to the troubleshooting process
- Report: tell the user what was done, what the result was, and whether follow-up actions are needed
Image insertion / file attachment workflow
This skill's image capability = upload + reference——it only solves "turning local files into images that can be rendered in outline."It does notmanage where images come from:
- Any local image such as screenshots / illustrations / logos: directly follow the 3 steps below
Complete 3-step process(each image goes through it independently):
-
Presigned upload URL: call
create_attachment(name, contentType, size)name: (如 figure-p1-f1.png) contentType: image/png(或 image/jpeg / image/webp) size: 文件字节数returns
uploadUrl(multipart receiving endpoint) + a set of form fields -
Upload binary: Use
curlto POST the local file touploadUrl(i.e., the/api/files.create)。attachments.createreturned byformfield mustverbatimbe sent back (Cache-Control/Content-Type/key/acl/maxUploadSize/_csrf), then attachfile=@<path>:$> KEY=$(jq -r '.data.form.key' <(curl -sS -X POST \ -H "Authorization: Bearer $OUTLINE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"figure-p1-f1.png","contentType":"image/png","size":12345}' \ "$OUTLINE_BASE/api/attachments.create")) $> curl -X POST "$OUTLINE_BASE/api/files.create" \ -F 'Cache-Control=max-age=31557600' \ -F 'Content-Type=image/png' \ -F "key=$KEY" \ -F 'acl=private' \ -F 'maxUploadSize=26214400' \ -F '_csrf=' \ -F "file=@<本地文件路径>" \ -H "Authorization: Bearer $OUTLINE_API_KEY"response
{"success":true, ...}counts as a successful upload (only metadata returned butsuccess=falsestill means the file was not written to disk; you must retry)⚠️ create_attachment only registers metadata; the binary must be curled yourself
the previous line
create_attachmentsucceeding ≠ the file was uploaded. The MCP tool only acceptsname / contentType / sizethree parameters,does notaccept binary content. Without the step 2 curl, the attachment record exists but the content is 0 bytes; after the document embeds it, the browser fails to load the image → blank / broken image。especially nasty: no error at the time; only afterward do you discover none of the images displayed.Authentication: use the API key from the outline MCP config (
<endpoint 域名>/mcpcorresponding toAuthorization: Bearer <key>header, see §Access for where it is stored). the agent can use it directly—same key as the MCP server; curl/api/attachments.createand/api/files.createboth work. No need for the user to manually grab cookies.A safe way to get the key: first check
tools/listto see whether the attachment tool works → that means the key is already in effect on the MCP side → use that same key directly for curl.Fallbacks when the API key is unavailable / curl 401(by priority):
- Check whether
headers.Authorizationin the MCP server config actually has the key filled in; an empty key is a silent failure - Regenerate the API key and update the MCP config (restart the session for changes to take effect)
- The user drags the image into the editor in the Outline UI (the editor has its own session auth)
- Check whether
-
Insert reference: write it in Markdown
attachment.urlin the form/api/attachments.redirect?id=<uuid>=宽x高to give the render size (repository-wide=WxHequal-width convention, see doc_style.md §7)- non-image attachments may omit
=WxH
-
Required verification: after writing the Markdown referenceyou mustverify that the attachment actually has content
fetch attachment id=<attachment.id> → 拿到 signedUrl → 用 WebFetch / 浏览器访问 signedUrl → 必须返回 200 + 实际图片字节;404 / 0 字节 / HTML 错误页都算失败if it fails,you must notwrite the document; fix the upload first, then continue
Write / replace method(choose by scenario):
-
When creating a new document: directly embed the
from step 3 into thecreate_documentoftextparameter -
Replace an image reference in an existing document: use
update_document+editMode: "patch"+findTextfor precise replacementfindText:  text: This preserves other content (comments / highlights / table widths) from being damaged
Full rewrite(replace mode + large document)Switch to the REST API(2026-06-21 experience):
-
Pitfall:
update_documentoftextfield in some scenarios willSwallows newline characters—— Measured: after a 3K-character markdown goes through a tool call,between the 3 rows of the first-line table, the\nare all lost, the three lines are squeezed into one line, and the table renders as a single-line inline element. In other places (list / section headings) newlines are normal, but the three lines of the first-line table area death sentence. patch mode is even worse:findTextshort matches willappendinstead of replace, causing the "3-sentence summary" list to become 5 items 1-2-3-4-5. -
Fallback: when rewriting the whole document,do notuse the mcp tool,switch to
POST /api/documents.updateusing curl + API key (the key is the same as the MCP server config), pass the payload via a file to avoid command-line escaping:python3 -c "import json; json.dump({'id': '<doc-id>', 'text': open('summary.md').read()}, open('payload.json', 'w'), ensure_ascii=False)" curl -sS -X POST https://<endpoint>/api/documents.update \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <api-key>" \ --data-binary @payload.jsonThe REST API correctly preserves all newlines; returns
{"data": {...}, "status": 200, "ok": true}。 -
Verification is a must: immediately after writing, fetch to see whether the returned markdown body is corrupted (first-line table / list / section headings); if found → resend. A tool returning success does not mean the save is OK
-
patch mode pitfalls:
findTextmust belong enough(at least contain 2-3 adjacent lines), otherwise it will be mistakenly appended; measured that when only 1 list item line is matched, the patch behavior is "append after that item" rather than "replace the entire section"
Anti-patterns(Don'tdo this):
- Referencing a local path that has not been uploaded (
or)—— the outline renders asa broken image, readers cannot see it - Uploading a screenshot of the entire PDF page / containing the header / the paragraph at the end of the section——must only capturethe image itself's bbox
- In
create_document/update_document'stextparameterdirectly pass image binary—— these two toolsdo notaccept files, only accept Markdown strings
Read uploaded attachments: call fetch(resource="attachment", id=<id 或完整 redirect URL>)
returns a short-lived signed URL, which can be downloaded directly.
Troubleshooting
Locate in the following order:
- fetch only returns metadata, cannot read the body — the client only presents the first content block (a client-side issue,
do not troubleshoot in the direction of empty document / wrong ID / authentication; for the mechanism and measurements see "Capability List · Read")——for the body, use the
REST bypass below; or
list_documents(query)'scontextto get a body excerpt (short documents are close to the full text, long documents will be truncated) - Authentication failure (401 / 403) — key expired / revoked: regenerate the API key and update the MCP config (§Access), restart the session after changing it for it to take effect
- MCP not enabled / connection refused — troubleshoot according to §Access (MCP toggle / endpoint protocol)
- Tool name mismatch — call
tools/listagain to get the current tool list; do not call from memory - Invalid document ID — use search to relocate and get a new ID; do not call with a cached ID (the document may have been archived / renamed)
- Image attachment 0 bytes / 404 — rerun the attachment 3 steps (create_attachment → curl upload → Markdown reference); verify that fetch returns signedUrl and can download the bytes with 200
- first-row table
\nlost — switch to REST APIPOST /api/documents.update(key same as MCP server config)
Read body REST bypass(fault item 1 expanded) — token / <base> same as MCP config
(same key as the MCP server, already written during setup):
# <base> = outline MCP url 去掉尾部 /mcp
curl -sS -X POST "<base>/api/documents.info" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"id":"<docId>"}' | jq -r '.data.text'
<token> For the location, see §Access the on-disk location (varies by agent:~/.config/opencode/opencode.json
#mcp.outline.headers.Authorization / .mcp.json / ~/.claude.json)。
Reference examples
Example 1: Search documents
User instruction: "Help me search Outline Wiki for documents related to 'CI deployment process'"
Execution:
1. 确认 outline MCP 工具已在 session 注册(否则按 §接入 配置后重启会话)
2. 调用 tools/list 拿到 search 工具的实际名称
3. 调用 search 工具,query="CI 部署流程",limit=10
4. 整理返回的文档列表,按相关度展示给用户
5. 若用户要打开某篇,再 fetch 拉取正文
Example 2: Read by document ID
User instruction: "Show me the original Markdown of the document doc_abc123"
Execution:
1. 调用 tools/list 拿到 read 工具的实际名称
2. fetch(resource=document, id="doc_abc123") → 标题 + 元数据 + 正文
(若当前客户端只返元数据,正文走 REST 旁路 POST /api/documents.info)
3. 把标题 + 元数据 + Markdown 正文一并展示
4. 若用户后续要"改这篇",直接进入编辑流程(本 skill 已覆盖)
Example 3: Create a new document
User instruction: "Create a new document named 'Cache Strategy' under the 'Backend' Collection"
Execution:
1. 先 search 查 '后端' Collection 下是否已有同名 / 相似文档(有 → 走编辑不新建)
2. 调 list_collections 拿 '后端' Collection ID(若 create schema 要求)
3. 撰写 Markdown 正文:正文首块写 OKF yaml 元数据块
(type: reference / tags / description / created / updated),
再按 doc_style.md 风格基线 + style_checklist.md(§0 OKF + §1-§9)组织正文
4. 调用 create_document 工具传 title / content / collection_id
(title 走 Outline 字段,不写进 yaml 块)
5. 验证返回成功,把新文档链接 / ID 告诉用户
Note: The Collection ID is notexplicitly statedin the official documentation as to how to obtain it; if in
tools/listthe schema of the create tool does not require collection_id (for example, it allows referencing by Collection name), then call it according to the actual schema.
Example 4: Push an image from an upstream generation tool to outline (using paper abstract output as an example)
User instruction: "Push the ~/out/<slug>/summary.md + figures/*.png
generated by the upstream paper abstract tool to the outline workspace"
Execution:
1. search 查目标 Collection + 是否已有同名文档
2. 正文首块写 OKF yaml 元数据块(type: paper-note / tags / description /
created / updated)——title 走 Outline 字段
3. 对每张 figures/*.png 走 attachment 3 步(详见上文"图片插入")
4. 用 read 拿当前 summary.md 中所有  引用
5. 用 update_document + editMode: "patch" + findText 精准替换每张图为

6. 验证 fetch 返回每张图 signedUrl 能 200 下载
7. (可选)删本地 figures/ 目录
Related references
references/doc_style.md— Markdown ↔ ProseMirror node mapping (§1-§13) + image attachment upload process (§12) + @mention (§13) + OKF agent readable baseline (upload format control) + advancedreferences/style_checklist.md— the style checklist that must be run before writing (§0 OKF metadata + §1-§9 style)