DingCard

按主题读一份使用指南：文档怎么写、每个动作怎么发、content / outline / 海报内容怎么填、HTML 怎么写、模板字段和检查项是什么意思、渲染导出有哪些方式。工具说明里只写了做什么；要动手写参数之前，先来这里读对应主题的完整写法。section 给主题 id（不给就列出全部主题 id 和标题）：document-model 文档模型、actions 动作清单、deck-content 套图内容、outline Markdown 大纲、poster-content 海报内容、html-import 网页转文档、templates 模板清单、check 检查项、render-export 渲染与导出。

列出叮卡内置模板，按内容和尺寸挑模板、拿 templateId。默认每个模板一张简卡：id、标题、描述、kind、format（尺寸 id）、uses（用途）、styles（风格）。kind 是 deck（一整套，用 create_document_from_content / create_document_from_outline 生成）或 poster（单页，用 create_poster_from_content 生成）。kind / format / q 只取子集（如 kind: "poster"、format: "xhs"、q: "菜单"）。挑出两三个候选后用 ids 取详情：每页能放多少要点（capacity）、海报有哪些位置（posterCapacity）、颜色、标签和像素尺寸，字段含义见 get_guide("templates")。不同页可以用不同模板：create_document_from_content 的每页可以写自己的 templateId，add_template_pages 把任何模板的某几页加进已有文档。

按模板 id 实例化一份完整的可编辑文档：自由画布模板保存在服务端，返回 documentId（之后传给 inspect_document / apply_actions / check_document / render_document 等）和各页 id、名称；Markdown 模板返回 { source, platformId, themeId, fontFamily, radius, profile, images? } 信封（可用 render_markdown 无头渲染）。

把模板的页面加进一份自由画布文档，和编辑器模板面板里点一页一样：套图模板可以只加某几页（再来一张内页、换个结尾页），单页海报加进来就是新的一页。页面保留模板自己的尺寸和示例文字，之后用 inspect_document 找到图层、apply_actions 改字，check_document 会把没改的示例文字报出来。要直接按内容填好：套图的页用 create_document_from_content 每页的 templateId，海报用 create_poster_from_content 的 documentId。返回加进来的页（slideId、名称、在文档里是第几页），默认附上这些页的缩略图。

把你写的 HTML/CSS 网页转成在叮卡里能逐个修改的自由画布文档（v44）。适合模板排不出来的版式：直接用网页写法排版，叮卡在浏览器里排好后，把每个色块、文字、图片和 SVG 图形读成形状、文字框、图片和图形节点，位置、字号、颜色、圆角、阴影、渐变等全部照网页来，层叠顺序按 CSS（含 z-index）。返回 documentId、每页 id 和尺寸、notes（哪里没转过来），默认附缩略图。之后 check_document 检查、apply_actions 修改、render_document 出图、open_in_editor 交给人。HTML 怎么写（section 分页、内置字体、图片、svg、表格、data-name）见 get_guide("html-import")。

按结构化内容生成一整套自由画布卡片（v44）：封面 + 每个 page 一页 + 可选结尾页，风格沿用所选模板。适合已经整理好标题、正文、要点的内容；每页还能配一种数据元素（chart / table / timeline / progress）。content 的完整写法（页面字段、版式选择、数据元素、生成规则）见 get_guide("deck-content")。生成后建议先 check_document，再 render_document 看缩略图。

按内容生成一张海报（单页模板：小红书封面、菜单、价目表、证书、九宫格、课程表、各种海报、请柬、贺卡、封面、宣传单、数据盘点、对比表、成长记录等），尺寸跟模板走。模板里的示例文字全部换成内容，没给的连同它的底板、按钮一起删掉。不同模板吃不同的字段（菜单的 details、课程表的 table、数据盘点的 chart、证书的 recipient），content 每个字段的写法和放不下时怎么排见 get_guide("poster-content")；summary.moved / unplaced / shrunk 说明文字放到了哪里、缩了多少。给 documentId 时海报加成那份文档的一页。

按 Markdown 大纲生成一整套自由画布卡片（v44）：封面 + 每个 "## 小节" 一页 + 可选结尾页，风格沿用所选模板；小节里的 Markdown 表格也变成这一页的表格元素。大纲的完整语法（小节、要点、引文、表格、结尾页）见 get_guide("outline")。生成后建议先 check_document，再 render_document 看缩略图。

查内置素材与样式清单，kind 选一类：icons 内置图标（query 中文或英文搜、ids 按 id 取；example 是可直接 node/insert-children 的完整 path 节点）、decorations 装饰素材（手绘线条、贴纸、标签；category 只看一类，用 add_decorations 放置）、styles 配色与字体组合（document/restyle 一键套用）、text_styles 现成花字（patch 直接作为 node/update-style 的补丁）、collages 拼图版式（example 是完整的拼图组节点，格子换图片填充）、filter_presets 照片滤镜预设（patch 同样给 node/update-style）。不给 kind 返回每类的条数和用法。

把装饰素材放到一页上（一次可放多个，按顺序叠放；list_assets 的 decorations 查 id）：每项给 decoration、x、y（盒子左上角的页面坐标）、width（不给按页面短边的默认比例），高度按装饰的宽高比算。color（#RRGGBB）换掉装饰本来的主色（手绘线条和贴纸换整体颜色，标签换底色，字色自动取黑或白）；text 换标签上的字；rotation 旋转（度）；below 填同页一个顶层节点的 id 或图层名，装饰就放在它下面一层（荧光笔、胶带、色块垫在文字下面时用），不给则放在最上层。用 documentId 时就地更新这份文档，返回每个装饰的 nodeId、path 和盒子；之后可以用 apply_actions 改，用 check_document 检查有没有压住文字。

校验文档是否为合法的自由画布 v44 文档（v1–43 自动迁移，src 是本机路径的图片读进来嵌入）；合法时保存在服务端并返回 documentId（已有 documentId 的照旧），非法时返回原因：第几页、哪个节点、多了或缺了哪个键，或者该写哪个 documentVersion。 文档速写：{ documentVersion: 44, slides: [{ id, name, width(128–4096), height(128–4096), background, nodes, guides? }], activeSlideId }；节点 11 选一（text / image / shape / line / path / qrcode / chart / table / timeline / progress / group），公共必填键 id, name, locked, hidden, type, x, y, rotation, scale，其余键按节点类型精确匹配（不多不少），全文档节点 id 唯一。每种节点的完整键表见 dingcard://schema/freeform 资源或 get_guide("document-model")，写之前先读；拿不准就先写个大概来校验，按返回的原因改。

检查文档结构：页面摘要（尺寸/背景/节点数）与递归节点树（id、name、type、几何、文本摘要；内置图标标出 icon id，装饰素材标出 decoration id，组成装饰的组也标在组上），以及整套卡片的 style：用到的颜色（按占的面积排序，附 share 和用在 background/fill/text/line/shadow 哪些地方）、字体（texts 用了几段文字、largest 最大字号）和正文字号 bodySize。改文档前先 inspect，拿到节点 id / 路径再发动作。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。

对文档应用一串编辑动作（与编辑器 UI 同一归约器，语义完全一致），返回每个动作是否生效（changes）和没生效的原因（reasons，与 changes 一一对应：没改动时是 null，被拒时写清哪个键、哪条规则）。用 documentId 时就地更新这份文档（version 加一），传 document / documentPath 时另存为一份新文档并返回它的 documentId；动作里图片 src 写成本机文件路径的会读进来嵌入。常用：node/insert-children（插入节点）、node/update-content（改字/改数据元素内容）、node/update-style（改样式）、node/update-geometry（改位置尺寸）、slide/*（页的增删换序）、document/find-replace（整套查找替换）、document/restyle（整套换配色字体）。每个动作的完整写法见 get_guide("actions")。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。

检查自由画布文档排出来的样子：在与导出相同的页面里排版后，逐页列出读者会注意到的问题——文字放不下、叠住、被挡住或跑出页面，对比度太低，还留着示例文字，图片没加载出来，图形、二维码、表格、图表画坏了，对齐差几 px，标题和正文拉不开层级，页面上一大片空白，该放图片的色块空着。每条带 kind、page、slideId、node（图层名）、path（apply_actions 用的节点路径）和改法，每种 kind 是什么意思见 get_guide("check")。fix: true 时把放不下的文字缩到能放下的字号、把差几 px 的对齐吸齐，并保存（用 documentId 时就地更新，返回 documentId 和 version），附改了哪些（fixed 是缩过的字号，snapped 是挪过的位置）和剩下的问题。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。

把自由画布 v44 文档（v1–43 输入自动迁移）无头渲染为图片或 PDF（与编辑器导出同一管线：网页字体按字符子集嵌入、图片就绪等待、逐页导出），默认逐页 PNG 到 outputDir，另附每页小缩略图供你直接查看效果。长图、九宫格、PDF、JPEG、倍率等输出方式见 get_guide("render-export")。仅支持自由画布文档；文档中的图片 src 必须是浏览器可加载的 URL 或 data URL。文档怎么写见 dingcard://schema/freeform 资源或 get_guide("document-model")。

取回一份文档的完整 JSON：给 path 时写成 JSON 文件（目录不存在会创建）并返回路径，不给时直接返回文档。写成文件的文档可以拖进叮卡「我的项目」，或之后用 documentPath 传回来。

在叮卡编辑器里打开这份自由画布文档，方便人接着手改：服务端把文档放在本机地址上，在浏览器里打开编辑器的导入链接，编辑器读进来存成一个新项目（不登录也行，存在这台设备的浏览器里）。默认打开服务端自带的编辑器 http://127.0.0.1:5390（DINGCARD_APP_PORT 可改端口，被占用时换一个空闲端口）；设了环境变量 DINGCARD_APP_URL 或传 appUrl，就在那个叮卡里打开。open: false 只返回链接（url）不打开浏览器。

把文档渲染成图片、上传到部署的叮卡服务端，生成一个不用登录就能打开的分享链接：手机扫码或点链接就能看整套卡片、长按存图——「电脑做图、手机发图」的最后一公里。自由画布文档（documentId 或 v44 文档）和 Markdown 卡片信封（source、platformId、themeId 等，与 render_markdown 的 document 相同）都可以。返回 { ok, share: { id, url, expiresAt, imageCount } } 并附上二维码图片，给用户扫即可。expiresInHours 是有效期（小时，1–720，默认 24，最长一个月），过期后链接打不开、图片仍留在账号里。action 另选 list（列出账号已有的分享）、revoke（按 id 撤销：链接立刻打不开、图片等回收清理）。需要环境变量 DINGCARD_SERVER_URL（部署的服务端地址）和账号或令牌环境变量。

管部署的叮卡服务端账号里存的作品（人在编辑器里存的，AI 接着做）：action 选操作——list 列出作品（id、标题、类型 mode、更新时间，query 按标题过滤，这是接着做已有作品的第一步）、open 按 id 载入（自由画布作品返回 documentId，之后 inspect_document / apply_actions / render_document / share_document 都能用；Markdown 作品返回 markdownDocument 信封，交给 render_markdown）、save 把一份文档存回账号（不给 projectId 存成新作品，给 open 返回的 projectId 时覆盖那一份）。需要环境变量 DINGCARD_SERVER_URL 加 DINGCARD_SERVER_TOKEN（带 drafts 权限的 API 令牌）或账号环境变量。

搜索在线图库的照片，给卡片配图：返回缩略图和能直接使用的图片地址，把它们填进图片字段（create_poster_from_content 的 image、图片节点的 src、页面的图片背景都接受 http(s) 地址）。配置了 DINGCARD_SERVER_URL（和账号）时走部署服务端的图库代理（Pixabay / Unsplash / Pexels / Openverse，密钥留在服务端），选中的图用 import_stock_image 转存成账号里的稳定地址；没配置时直连 Openverse（免密钥、只搜 CC0 可商用图），结果里的 url 可以直接用、无需转存。搜索词用中英文内容词都行，如 "咖啡馆 内景"、"city night skyline"。

把 search_images 选中的一张照片通过部署的服务端转存到账号的图片库里，得到稳定的原图地址（比缩略图清晰，也不会因为图库改链接而失效）。返回的 url 直接填进图片字段。需要 DINGCARD_SERVER_URL（和账号）；没配置时不用转存，直接用 search_images 结果里的 url。

把 Markdown 文档信封无头渲染为一套卡片 PNG（与 Markdown 工作台导出同一管线：DOM 实测分页、平台头部与主题、网页字体按字符子集嵌入、逐页 pixelRatio 3 导出）。输出 <baseName>-01.png、<baseName>-02.png… 到 outputDir；页数由分页决定。 document 为 Markdown 文档信封：{ source: Markdown 文本（--- 为手动分页）, platformId: 'rednote'|'weibo'|'twitter', themeId: 主题 id（如 'light'）, fontFamily, radius: 数字圆角, profile: { nickname, handle, location, avatarColor, avatarImage: dataURL 或 null, verified, headerFirstPageOnly }, images?: { "img:<id>": dataURL } }。