yuque-cookie-plugin 0.1.0

package/dist/lake-diff.js

@@ -0,0 +1,113 @@
+import { parseLake } from "./lake-parser.js";
+export function diffLakeSnapshots(before, after) {
+    const beforeEdit = before.edit || {};
+    const afterEdit = after.edit || {};
+    const beforeLake = beforeEdit.body_asl || before.lake?.sourcecode || '';
+    const afterLake = afterEdit.body_asl || after.lake?.sourcecode || '';
+    const beforeHeadings = extractLakeHeadings(beforeLake);
+    const afterHeadings = extractLakeHeadings(afterLake);
+    const beforeParsed = parseLake(beforeLake);
+    const afterParsed = parseLake(afterLake);
+    return {
+        before: {
+            doc: before.doc,
+            heading_count: beforeHeadings.length
+        },
+        after: {
+            doc: after.doc,
+            heading_count: afterHeadings.length
+        },
+        headings: diffHeadings(beforeHeadings, afterHeadings),
+        stats: {
+            body_asl_length_before: beforeLake.length,
+            body_asl_length_after: afterLake.length,
+            body_asl_changed: beforeLake !== afterLake
+        },
+        structure: {
+            before: summarizeStructure(beforeParsed),
+            after: summarizeStructure(afterParsed),
+            changed: summarizeStructure(beforeParsed).join('|') !== summarizeStructure(afterParsed).join('|')
+        },
+        cards: diffNamedCounts(countByName(beforeParsed.cards), countByName(afterParsed.cards)),
+        lists: {
+            before: beforeParsed.lists.map((list) => ({ ordered: list.ordered, item_count: list.item_count })),
+            after: afterParsed.lists.map((list) => ({ ordered: list.ordered, item_count: list.item_count }))
+        },
+        tables: {
+            before: beforeParsed.tables.map((table) => ({ row_count: table.row_count })),
+            after: afterParsed.tables.map((table) => ({ row_count: table.row_count }))
+        }
+    };
+}
+export function extractLakeHeadings(lake) {
+    const result = [];
+    const headingRegex = /<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/g;
+    let match;
+    while ((match = headingRegex.exec(lake))) {
+        const block = match[0];
+        result.push({
+            type: 'heading',
+            level: Number(match[1]),
+            attrs: {},
+            text: decodeEntities(block.replace(/<[^>]+>/g, '')),
+            block
+        });
+    }
+    return result;
+}
+function diffHeadings(before, after) {
+    const count = Math.max(before.length, after.length);
+    const changes = [];
+    for (let i = 0; i < count; i += 1) {
+        const b = before[i];
+        const a = after[i];
+        if (!b || !a || b.level !== a.level || b.text !== a.text || b.block !== a.block) {
+            changes.push({
+                index: i,
+                before: b && summarizeHeading(b),
+                after: a && summarizeHeading(a)
+            });
+        }
+    }
+    return changes;
+}
+function summarizeHeading(heading) {
+    return {
+        level: heading.level,
+        text: heading.text,
+        attrs: heading.attrs,
+        block_preview: heading.block.slice(0, 500)
+    };
+}
+function decodeEntities(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&#39;/g, "'");
+}
+function summarizeStructure(parsed) {
+    return [
+        `headings:${parsed.headings.length}`,
+        `cards:${parsed.cards.length}`,
+        `lists:${parsed.lists.length}`,
+        `tables:${parsed.tables.length}`,
+        `paragraphs:${parsed.stats.paragraph_count}`,
+        `length:${parsed.stats.length}`
+    ];
+}
+function countByName(items) {
+    const counts = {};
+    for (const item of items)
+        counts[item.name] = (counts[item.name] || 0) + 1;
+    return counts;
+}
+function diffNamedCounts(before, after) {
+    const names = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...names].sort().map((name) => ({
+        name,
+        before: before[name] || 0,
+        after: after[name] || 0
+    })).filter((item) => item.before !== item.after);
+}

package/dist/lake-heading-numbering.js

@@ -0,0 +1,29 @@
+import { parse } from 'node-html-parser';
+export function enableLakeHeadingNumbering(lake) {
+    if (!lake.trim())
+        return lake;
+    const root = parse(lake, {
+        lowerCaseTagName: true,
+        comment: false,
+        blockTextElements: {
+            script: true,
+            noscript: true,
+            style: true,
+            pre: true
+        }
+    });
+    for (const heading of root.querySelectorAll('h1,h2,h3,h4,h5,h6')) {
+        heading.setAttribute('data-lake-index-type', '2');
+        stripTextualHeadingNumber(heading);
+    }
+    return root.toString();
+}
+function stripTextualHeadingNumber(heading) {
+    const firstSpan = heading.querySelector('span');
+    if (!firstSpan)
+        return;
+    const current = firstSpan.text;
+    const next = current.replace(/^\s*\d+(?:\.\d+)*\.?\s+/, '');
+    if (next !== current)
+        firstSpan.set_content(next);
+}

package/dist/lake-insert.js

@@ -0,0 +1,34 @@
+export function extractFirstImageParagraph(lake) {
+    const paragraphMatch = /<p\b[^>]*>\s*<card\b[^>]*\bname="image"[^>]*><\/card>\s*<\/p>/i.exec(lake);
+    if (paragraphMatch?.[0])
+        return paragraphMatch[0];
+    const cardMatch = /<card\b[^>]*\bname="image"[^>]*><\/card>/i.exec(lake);
+    if (cardMatch?.[0])
+        return `<p>${cardMatch[0]}</p>`;
+    throw new Error('Serialized Lake did not contain an image card.');
+}
+export function insertLakeBlock(lake, block, afterText) {
+    if (!lake.trim())
+        throw new Error('Current Lake document is empty.');
+    if (!block.trim())
+        throw new Error('Inserted Lake block is empty.');
+    if (afterText?.trim()) {
+        const inserted = insertAfterTextBlock(lake, block, afterText.trim());
+        if (inserted)
+            return inserted;
+        throw new Error(`Could not find a Lake block containing --after-text: ${afterText}`);
+    }
+    return `${lake}${block}`;
+}
+function insertAfterTextBlock(lake, block, text) {
+    const escapedText = escapeRegExp(text);
+    const blockPattern = new RegExp(`<(p|h[1-6]|blockquote|li)\\b[^>]*>[\\s\\S]*?${escapedText}[\\s\\S]*?<\\/\\1>`);
+    const match = blockPattern.exec(lake);
+    if (!match?.[0] || match.index === undefined)
+        return undefined;
+    const insertAt = match.index + match[0].length;
+    return `${lake.slice(0, insertAt)}${block}${lake.slice(insertAt)}`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/lake-markdown.js

@@ -0,0 +1,54 @@
+import { parseLake, stripTags } from "./lake-parser.js";
+export function snapshotToMarkdown(snapshot) {
+    const lake = snapshot.edit?.body_asl || snapshot.lake?.sourcecode || snapshot.edit?.body_draft_asl || '';
+    return lakeToMarkdown(lake, snapshot);
+}
+export function lakeToMarkdown(lake = '', snapshot) {
+    const parsed = parseLake(lake);
+    const title = snapshot?.doc?.title || 'Yuque Document';
+    const lines = [`# ${title}`, ''];
+    lines.push(`> Source: ${snapshot?.url || 'snapshot'}`);
+    lines.push(`> Headings: ${parsed.headings.length}; Cards: ${parsed.cards.length}; Lists: ${parsed.lists.length}; Tables: ${parsed.tables.length}`);
+    lines.push('');
+    const body = lake
+        .replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/g, (_match, level, content) => `${'#'.repeat(Number(level))} ${stripTags(content)}\n`)
+        .replace(/<p\b[^>]*>([\s\S]*?)<\/p>/g, (_match, content) => `${inlineToMarkdown(content)}\n`)
+        .replace(/<blockquote\b[^>]*>([\s\S]*?)<\/blockquote>/g, (_match, content) => `> ${inlineToMarkdown(content)}\n`)
+        .replace(/<card\b([^>]*)>(?:<\/card>)?/g, (block) => cardToMarkdown(block))
+        .replace(/<li\b[^>]*>([\s\S]*?)<\/li>/g, (_match, content) => `- ${inlineToMarkdown(content)}\n`)
+        .replace(/<[^>]+>/g, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    if (body)
+        lines.push(body, '');
+    return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`;
+}
+function inlineToMarkdown(value = '') {
+    return stripTags(value
+        .replace(/<strong\b[^>]*>([\s\S]*?)<\/strong>/g, '**$1**')
+        .replace(/<em\b[^>]*>([\s\S]*?)<\/em>/g, '*$1*')
+        .replace(/<code\b[^>]*>([\s\S]*?)<\/code>/g, '`$1`')
+        .replace(/<a\b[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/g, '[$2]($1)'));
+}
+function cardToMarkdown(block) {
+    const name = (block.match(/\bname="([^"]+)"/) || [])[1] || 'unknown';
+    const value = (block.match(/\bvalue="([^"]+)"/) || [])[1] || '';
+    const data = decodeCardValue(value);
+    if (name === 'codeblock')
+        return `\n\`\`\`${data.mode || 'plain'}\n${data.code || ''}\n\`\`\`\n`;
+    if (name === 'image')
+        return `\n![${data.name || 'image'}](${data.src || ''})\n`;
+    if (name === 'hr')
+        return '\n---\n';
+    return `\n[Unsupported Yuque card: ${name}]\n`;
+}
+function decodeCardValue(value) {
+    if (!value.startsWith('data:'))
+        return {};
+    try {
+        return JSON.parse(decodeURIComponent(value.slice(5)));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/lake-parser.js

@@ -0,0 +1,79 @@
+import { parse } from 'node-html-parser';
+export function parseLake(lake = '') {
+    const root = parse(lake, {
+        lowerCaseTagName: true,
+        comment: false,
+        blockTextElements: {
+            script: true,
+            noscript: true,
+            style: true,
+            pre: true
+        }
+    });
+    const headings = root.querySelectorAll('h1,h2,h3,h4,h5,h6').map((node) => ({
+        type: 'heading',
+        level: Number(node.tagName.slice(1)),
+        attrs: attrsFromNode(node),
+        text: decodeEntities(node.text.trim().replace(/\s+/g, ' ')),
+        block: node.toString()
+    }));
+    const cards = root.querySelectorAll('card').map((node) => {
+        const attrs = attrsFromNode(node);
+        return {
+            type: 'card',
+            attrs,
+            name: attrs.name || '',
+            block: node.toString()
+        };
+    });
+    const lists = root.querySelectorAll('ul,ol').map((node) => ({
+        type: 'list',
+        ordered: node.tagName === 'ol',
+        attrs: attrsFromNode(node),
+        item_count: node.querySelectorAll('li').length,
+        block: node.toString()
+    }));
+    const tables = root.querySelectorAll('table').map((node) => ({
+        type: 'table',
+        attrs: attrsFromNode(node),
+        row_count: node.querySelectorAll('tr').length,
+        block: node.toString()
+    }));
+    return {
+        headings,
+        cards,
+        lists,
+        tables,
+        stats: {
+            length: lake.length,
+            paragraph_count: root.querySelectorAll('p').length
+        }
+    };
+}
+export function parseAttrs(value = '') {
+    const attrs = {};
+    const attrRegex = /([:\w-]+)(?:="([^"]*)")?/g;
+    let match;
+    while ((match = attrRegex.exec(value))) {
+        attrs[match[1]] = decodeEntities(match[2] || '');
+    }
+    return attrs;
+}
+export function stripTags(value = '') {
+    return decodeEntities(value.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim());
+}
+function attrsFromNode(node) {
+    const attrs = {};
+    for (const [key, value] of Object.entries(node.attributes)) {
+        attrs[key] = decodeEntities(String(value));
+    }
+    return attrs;
+}
+function decodeEntities(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&#39;/g, "'");
+}

package/dist/lake-transform.js

@@ -0,0 +1,12 @@
+// Focused Lake transforms live here. Keep these small and tested against
+// snapshot before/after pairs captured from the Yuque web editor.
+export function removeTextualHeadingNumbers(lake) {
+    return lake.replace(/<h([1-6])\b[^>]*>[\s\S]*?<\/h\1>/g, (block) => {
+        return block.replace(/(<span\b[^>]*>)([\s\S]*?)(<\/span>)/, (_match, open, text, close) => {
+            return `${open}${stripNumber(text)}${close}`;
+        });
+    });
+}
+function stripNumber(text) {
+    return text.replace(/^\s*\d+(?:\.\d+)*[.．、]?\s+/, '');
+}

package/dist/reports.js

@@ -0,0 +1,10 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { timestampForFile } from "./fs-utils.js";
+export async function writeReport(prefix, data) {
+    const dir = path.resolve('reports');
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${prefix}-${timestampForFile()}.json`);
+    await writeFile(file, `${JSON.stringify(data, null, 2)}\n`);
+    return file;
+}

package/dist/serve-book.js

@@ -0,0 +1,134 @@
+import { access, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function serveBook(root, options = {}) {
+    const rootPath = path.resolve(root);
+    await access(rootPath);
+    const vitepressPath = path.join(rootPath, '.vitepress');
+    let generated = false;
+    if (options.force) {
+        await createVitePressConfigForTest(rootPath);
+        generated = true;
+    }
+    else {
+        try {
+            await access(vitepressPath);
+        }
+        catch {
+            await createVitePressConfigForTest(rootPath);
+            generated = true;
+        }
+    }
+    const configPath = path.join(vitepressPath, 'config.mjs');
+    if (options.configOnly) {
+        return {
+            root: rootPath,
+            config: configPath,
+            generated
+        };
+    }
+    const createVitePressServer = options.createServer || await loadVitePressCreateServer();
+    const server = await createVitePressServer(rootPath, {
+        host: options.host || 'localhost',
+        port: Number(options.port || 5173)
+    });
+    await server.listen();
+    server.printUrls();
+    return server;
+}
+async function loadVitePressCreateServer() {
+    try {
+        const mod = await import('vitepress');
+        return mod.createServer;
+    }
+    catch (error) {
+        throw new Error(`VitePress is required for "serve-book" without --config-only. Install it in your current project or use "serve-book <book-path> --config-only". Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function createVitePressConfigForTest(root) {
+    const vitepressPath = path.join(root, '.vitepress');
+    await mkdir(vitepressPath, { recursive: true });
+    const progress = await readProgress(root);
+    const sidebar = await createSidebar(root, root, progress);
+    const config = `export default {
+  title: ${JSON.stringify(path.basename(root))},
+  themeConfig: {
+    search: { provider: 'local' },
+    sidebar: ${JSON.stringify(sidebar, null, 2)}
+  },
+  markdown: {
+    html: true,
+    breaks: true
+  }
+}
+`;
+    await writeFile(path.join(vitepressPath, 'config.mjs'), config);
+}
+async function createSidebar(root, current, progress) {
+    const ignore = new Set(['.vitepress', 'img', 'attachments', 'progress.json']);
+    const entries = sortEntriesByProgress(root, (await readdir(current)).filter((entry) => !ignore.has(entry)), current, progress);
+    const items = [];
+    for (const entry of entries) {
+        const full = path.join(current, entry);
+        const info = await stat(full);
+        const rel = path.relative(root, full).split(path.sep).join('/');
+        if (info.isDirectory()) {
+            const children = await createSidebar(root, full, progress);
+            if (!children.length)
+                continue;
+            const item = {
+                text: entry,
+                collapsed: true,
+                items: children
+            };
+            try {
+                await access(path.join(full, 'index.md'));
+                item.link = `/${rel}/`;
+            }
+            catch {
+                // no index
+            }
+            items.push(item);
+        }
+        else if (/\.md$/i.test(entry)) {
+            items.push({
+                text: entry.replace(/\.md$/i, ''),
+                link: `/${rel.replace(/\.md$/i, '')}`
+            });
+        }
+    }
+    return items;
+}
+function sortEntriesByProgress(root, entries, current, progress) {
+    if (!progress.length)
+        return entries.sort();
+    const order = new Map();
+    progress.forEach((item, index) => {
+        const normalized = item.path.split(path.sep).join('/');
+        order.set(normalized, index);
+        const firstPart = normalized.split('/')[0];
+        if (firstPart && !order.has(firstPart))
+            order.set(firstPart, index);
+        const dirname = path.dirname(normalized);
+        if (dirname && dirname !== '.' && !order.has(dirname))
+            order.set(dirname, index);
+    });
+    const currentRel = path.relative(root, current).split(path.sep).join('/');
+    return [...entries].sort((a, b) => {
+        const aKey = currentRel ? `${currentRel}/${a}` : a;
+        const bKey = currentRel ? `${currentRel}/${b}` : b;
+        const aOrder = order.get(aKey.replace(/\.md$/i, '')) ?? order.get(aKey) ?? Number.MAX_SAFE_INTEGER;
+        const bOrder = order.get(bKey.replace(/\.md$/i, '')) ?? order.get(bKey) ?? Number.MAX_SAFE_INTEGER;
+        if (aOrder !== bOrder)
+            return aOrder - bOrder;
+        return a.localeCompare(b, 'zh-CN');
+    });
+}
+async function readProgress(root) {
+    try {
+        const data = await readFile(path.join(root, 'progress.json'), 'utf8');
+        return JSON.parse(data);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/docker-quickstart.md

@@ -0,0 +1,96 @@
+# Docker 隔离试用
+
+本文档用于在不影响宿主机 Node/npm/Python 环境的情况下，使用 Docker 试用 `yuque-cookie-plugin`。
+
+## 一行启动并安装
+
+复制下面命令时保持为完整一行，不要在 `npm install -g` 后换行：
+
+```bash
+docker run --rm -it -p 34567:34567 node:22-bookworm bash -lc 'python3 --version && git --version && npm install -g yuque-cookie-plugin && yuque-local --help && bash'
+```
+
+进入容器后运行登录：
+
+```bash
+yuque-local auth login --manual
+```
+
+如果你想使用网页填写模式，也可以运行：
+
+```bash
+yuque-local auth login --port 34567
+```
+
+然后在宿主机浏览器打开：
+
+```text
+http://127.0.0.1:34567/
+```
+
+## 备用方式：进入容器后逐条执行
+
+如果终端复制长命令时容易自动换行，推荐先进入容器：
+
+```bash
+docker run --rm -it -p 34567:34567 node:22-bookworm bash
+```
+
+然后在容器里逐条执行：
+
+```bash
+python3 --version
+git --version
+npm install -g yuque-cookie-plugin
+yuque-local --help
+yuque-local auth login --manual
+```
+
+网页填写模式可以改用：
+
+```bash
+yuque-local auth login --port 34567
+```
+
+宿主机浏览器同样打开：
+
+```text
+http://127.0.0.1:34567/
+```
+
+## 常见错误
+
+错误示例：
+
+```bash
+npm install -g
+yuque-cookie-plugin
+```
+
+这会导致 npm 没收到安装地址，然后报错：
+
+```text
+Could not read package.json
+```
+
+另一个错误示例：
+
+```bash
+bash -lc 'python3 --version && git --version
+  && npm install -g yuque-cookie-plugin'
+```
+
+这会导致第二行以 `&&` 开头，bash 报：
+
+```text
+syntax error near unexpected token `&&'
+```
+
+结论：要么使用完整单行命令，要么进入容器后逐条执行。
+
+## 说明
+
+- `node:22-bookworm` 镜像内已经包含 Node、npm、Python 3 和 git。
+- 登录凭据会保存到容器内的 `~/.config/yuque-cookie-plugin/config.json`。
+- 使用 `--rm` 启动的容器退出后会删除，登录凭据也会丢失。
+- 如果需要保留配置，可以后续增加 Docker volume 映射。

package/docs/native-lake-capability.md

@@ -0,0 +1,101 @@
+# 语雀原生 Lake 写入能力矩阵
+
+## 目标
+
+本项目允许 AI 输入 Markdown、HTML 或本地文件，但写入语雀后的最终形态应尽可能是语雀编辑器原生 Lake 结构，而不是把 Markdown 文本硬塞进文档。
+
+核心判断标准：
+
+- 最终文档 `format` 应为 `lake`。
+- `body_asl` / `body_draft_asl` 应包含语雀 Lake 节点、`data-lake-id`、卡片元数据等结构。
+- 对复杂结构必须先通过真实语雀文档 snapshot before/after 验证，再固化自动化逻辑。
+- 不使用纯文本伪装编辑器功能。例如标题编号不能写成标题文本里的 `1. 标题`。
+
+## 当前已真实验证
+
+| 能力 | 当前状态 | 原生证据 | 说明 |
+| --- | --- | --- | --- |
+| 文档创建 | 已验证 | `create-doc` 真实创建并加入 TOC | 不传 `--slug` 时由语雀自动生成文档 slug |
+| 最终 Lake 化 | 已验证 | 创建后读取 `body_asl` 并通过 `/api/docs/:id/content` 写回 `format: lake` | `create-doc` 默认执行，除非显式传 `--no-native-lake` |
+| 标题 | 已验证 | `<h1 data-lake-id="..." id="...">` | 由语雀 Markdown 导入生成，再 Lake 写回 |
+| 段落 | 已验证 | `<p data-lake-id="..." id="...">` | 普通正文是 Lake 原生段落 |
+| 行内代码 | 已验证 | `<code data-lake-id="...">` | 快照中已出现 |
+| 无序列表 | 已验证 | `<ul list="..."><li data-lake-id="...">` | 语雀会生成 list id 和连续 start |
+| 有序列表 | 已验证 | `<ol list="...">`、`start="2"` | 真实快照显示语雀会拆成连续 Lake 列表节点 |
+| 嵌套列表 | 已验证 | `data-lake-indent="1"` | 真实快照显示二级列表使用缩进属性 |
+| 引用块 | 已验证 | `<blockquote data-lake-id="...">` | 由 Markdown `>` 导入生成 |
+| 分隔线 | 已验证 | `<card type="block" name="hr" value="data:...">` | 语雀使用 hr card |
+| 加粗/斜体/删除线 | 已验证 | `<strong>`、`<em>`、`<del>` | 行内结构保留为 Lake 原生节点 |
+| 普通链接 | 已验证 | `<a href="..." target="_blank" data-lake-id="...">` | 普通外链可原生写入 |
+| 表格 | 已验证 | `<table class="lake-table">`、`<colgroup>`、`td/p/span` | 当前真实快照已经是 Lake 表格 |
+| 代码块 | 已验证 | `<card type="inline" name="codeblock" value="data:...">` | 语雀使用 codeblock card，而不是普通 `<pre>` |
+| 标题章节编号 | 已验证 | 标题节点 `data-lake-index-type="2"` | 这是编辑器原生编号；渲染层的 `lake-read-ignore` 编号 span 不应写入正文 |
+
+## 当前待真实验证
+
+| 能力 | 当前判断 | 下一步验证方式 |
+| --- | --- | --- |
+| 下划线 | 未单独验收 | 创建含 HTML `<u>` 的样例并 snapshot |
+| bookmark 链接卡片 | 未验收 | 验证普通链接何时升级为 bookmark card |
+| 图片 | 已验证 | `POST /api/upload/attach` + `<card type="inline" name="image" value="data:...">` | 已真实上传本地 PNG，写入 Lake，下载回本地资源无 warning |
+| 附件/PDF | 已验证 | `POST /api/upload/attach` + `<card type="inline" name="file" value="data:...">` | file card 必须包含 `src` 和 `name`；`src` 使用 `/office/...pdf?from=...` 预览 URL，否则阅读页点击会变成 `about:blank` |
+| 音视频 | 下载侧已有部分兼容；写入侧未支持 | 需要真实文档 before/after，确认 card name/value 结构 |
+| 思维导图 | 未支持写入 | 需要手动创建一篇含思维导图的文档，snapshot 分析 card/resource 结构 |
+| 画板 | 未支持写入 | 需要手动创建一篇含画板的文档，snapshot 分析 board/card/resource 结构 |
+| 语雀表格/数据表等复杂卡片 | 未支持写入 | 先只保留、解析、diff，不主动生成 |
+
+## 当前写入策略
+
+`create-doc` 的默认策略是：
+
+1. 使用 Web Session 创建 Markdown 文档，让语雀服务器先做一次 Markdown 到编辑器内容的转换。
+2. 立即 snapshot 新文档，读取语雀生成的 `body_asl`。
+3. 必要时只做经过真实验证的 Lake 变换，例如标题编号 `data-lake-index-type="2"`。
+4. 通过安全 Lake 写入链路写回，生成备份和报告。
+
+这样做的原因是：语雀自己的 Markdown 导入器比手写 Lake 更接近编辑器原生结构，尤其是表格、代码块、列表等结构。
+
+## 禁止策略
+
+- 禁止直接把章节编号写进标题文本。
+- 禁止在未做 snapshot diff 前手写复杂 card。
+- 禁止用 Markdown 覆盖已有 Lake 文档来做批量排版。
+- 禁止静默丢弃图片、附件、思维导图、画板等资源。
+
+## 图片和附件探索路线
+
+图片、附件要达到原生写入，需要补齐上传链路：
+
+1. 用真实测试文档手动插入一张图片和一个附件。
+2. 分别 snapshot before/after，记录 `body_asl` card 结构。
+3. 探索 Web Session 接口，重点参考已调研到的 `/api/upload/attach`。
+4. 实现并真实验证 `upload-attach <doc-url> --file <file>`，只上传并输出返回 JSON，不先写入正文。
+5. `insert-image` 已支持 dry-run 和真实写入。`insert-attachment` 已支持 PDF 附件真实写入，并保留 `downloadUrl/download_url` 供本地下载器使用。
+6. 单篇真实文档 apply 后人工检查。
+
+## 思维导图和画板探索路线
+
+思维导图、画板属于复杂资源，不应直接猜结构。
+
+1. 用户或 AI 在测试知识库中创建包含思维导图/画板的真实文档。
+2. 使用 `snapshot` 保存原始 Lake。
+3. 使用 `diff-lake` 和人工阅读 `body_asl` 分析 card name、value、resource id。
+4. 先实现“识别和保留”，再考虑“创建和更新”。
+5. 如果资源本体不在 `body_asl` 中，需要继续探索资源接口，不能只写 card 壳。
+
+## 真实验收记录
+
+- `reports/real-ai-use-numbered/snapshot-default-native-lake.json`
+  - 验证标题、段落、列表、表格、代码块为 Lake 原生结构。
+- `reports/real-ai-use-numbered/snapshot-lake-native-heading-number.json`
+  - 验证标题编号原生写法为 `data-lake-index-type="2"`。
+- `reports/real-ai-use-native-rich/snapshot-native-rich.json`
+  - 验证有序列表、嵌套列表、引用、分隔线、加粗、斜体、删除线、普通链接均为 Lake 原生结构。
+- `reports/real-ai-use-native-image/snapshot-after-image.json`
+  - 验证本地 PNG 可通过 `/api/upload/attach` 上传，并以原生 image card 写入 Lake。
+- `reports/real-ai-use-native-attachment/snapshot-after-a99-src-attachment.json`
+  - 验证本地 PDF 可通过 `/api/upload/attach` 上传，并以 file card 写入 Lake。
+  - 关键结论：语雀阅读页 file card 渲染读取 `src + name`，不是 `url/previewUrl`。`src` 必须是 `https://www.yuque.com/office/<filekey>?from=<doc-url>` 形式，才能打开语雀内置 PDF 预览。
+  - `downloadUrl/download_url` 仍保留为附件下载地址，供 `download-doc` 资源落盘使用。
+
+后续每补齐一种复杂内容，都必须在本文件追加真实验收记录。