@amaster.ai/pi-lark 0.1.7 → 0.1.8

package/skills/lark-doc/references/lark-doc-create-workflow.md

@@ -0,0 +1,121 @@
+# Lark Doc Authoring
+
+## Philosophy
+
+以下原则是每个内容、结构和视觉决策的判定依据；写作和复查时逐条套用，冲突时按「约束栈」排序。
+
+- **读者本位**：落地前先回答：读者是谁、为什么要读、带着什么任务来。按读者的任务组织内容，不按功能或作者视角罗列。
+- **结构先行**：结论先行，先整体后局部；按逻辑分组与递进，依据关系选择列表、步骤或表格，使内容便于扫读。（特殊体裁除外）
+- **视觉服从语义**：先确定全篇主线和每节的中心任务或命题，再让视觉层级复现内容优先级。文档脱离讲解仍须完整、连续、可独立阅读。
+- **最低理解成本**：选择最能降低读者理解、执行和出错成本的表达形式，而不是机械选择字符最少或制作成本最低的形式；删冗余，用短句、动词和数据，并按真实信息关系使用图、表格或交互组件。
+- **克制且连贯**：每个视觉元素必须承担导航、比较、解释、证据、行动，或体裁所需的氛围与品牌功能；相关文字与视觉相邻，同类关系复用同类组件和样式。去掉后不影响读者任务或预期语气的装饰应删除。
+- **约束栈**：事实 > 用户硬约束 > 读者任务 > 内容 > 组件样式；后项不得牺牲或放宽前项，格式与组件不得反向改变内容判断。
+- **表达一致**：同一对象、动作和状态全文同名；标题层级与编号采用统一体系，如下；用户提供样例时，在不违反更高优先级规则的前提下延续其有效结构、语气、术语和编号。
+  - **自动编号模式**：每一个正文标题都写 `seq="auto"`，标题文本不手写任何前置序号。
+  - **中文手写模式**：适用于公文或正式场景，在标题文本中手写 `一、→（一）→ 1.→（1）`；最忌中文层级配阿拉伯小数，绝不出现 `一、` 下接 `1.1`。
+
+## Step Plan
+
+**CRITICAL：从零创作文档时按下述步骤依次执行，不可跳步。**
+
+### Step 1：理解读者任务、文档格式要求、硬约束和禁区。
+
+### Step 2：选择 genre content contract。
+
+下表文件均位于当前 Skill 的 `references/genres/` 目录。
+
+- 路由表仅用于选择候选，不代替 contract。高置信命中后必须读取对应 Profile / Adapter，并按其中的路由与消歧规则复核；未读取不得确定该值或进入 Step 3。确认后记录固定短名，最多各读取一个；未命中时，`genre_contract` 和 `adapter` 均可使用 `"none"` 或 `null`。
+- contract 决定内容任务、证据和体裁边界；adapter 只调整与所选 contract 兼容的平台结构、写作风格和组件约束。
+
+   | Content Profile | 独特专业任务 |
+   |-|-|
+   | [`route-workplace.md`](genres/route-workplace.md) | 组织决策、执行、留档 |
+   | [`route-report.md`](genres/route-report.md) | 数据、研究和证据形成洞察 |
+   | [`route-knowledge.md`](genres/route-knowledge.md) | 理解、自学、一次已知操作或检索 |
+   | [`route-media.md`](genres/route-media.md) | 独立采集、核实和公共理解 |
+   | [`route-opinion.md`](genres/route-opinion.md) | 形成并论证判断 |
+   | [`route-consumer.md`](genres/route-consumer.md) | 以真实体验或测试辅助消费选择 |
+   | [`route-marketing.md`](genres/route-marketing.md) | 组织授权的认知、转化或公关内容 |
+   | [`route-personal-brand.md`](genres/route-personal-brand.md) | 本人经历、能力和作品的可信呈现 |
+   | [`route-creative.md`](genres/route-creative.md) | 角色、冲突、情节与分支叙事 |
+
+   | Adapter | 渠道 |
+   |-|-|
+   | [`route-platform.md`](genres/route-platform.md) | Email、微信公众号、小红书 |
+
+### Step 3：收集资料并扫描表达机会。
+
+1. 强制扫描事实、数据、案例、引用和图片等资源缺口；内容需要而现有材料不足时必须检索或生成，判断需要图片且用户未提供素材时必须搜索图片。
+2. 根据用户要求、contract / adapter 限制和内容需要确定 `presentation_mode`，再识别真实信息关系并选择候选表达；不因命中关系就机械使用组件。
+
+   | 信息关系 | 候选表达 |
+   |-|-|
+   | 同组字段的精确比较或映射 | `table` |
+   | 流程、依赖、分支、时序、层级、因果、空间或拓扑关系 | `whiteboard` |
+   | 对象、场景、界面、外观、氛围、示例或视觉证据 | `img` |
+   | 复杂交互、动态状态、可探索数据或应用式布局 | `html5-block` |
+   | 两组简短、等权且适合横向阅读的信息 | `grid` |
+   | 单个关键提醒或限制 | `callout` |
+   | 简单并列、步骤或连续论述 | 列表或段落 |
+
+3. 按全篇、章节、block 三个尺度构图：相关内容相邻，同类关系保持相同顺序与对齐；正文可以是主表达，不要求每节都有 presentation block。
+4. 在写正文前确定计划使用的 block 和具体 `purpose`。Presentation Decision 的 `visual_plan.blocks` 只记录确需最低数量约束的 `whiteboard`、`img`、`html5-block`。三类均无硬性数量要求时写 `"blocks": []`。
+
+`presentation_mode` 只表示模型采用的视觉策略；只有用户要求、contract / adapter 限制互相冲突时才询问用户：
+
+- `formal`：视觉正式、克制；不使用高亮块、emoji 或装饰性组件，只保留正式体裁确有必要的结构。
+- `normal`：按内容需要使用组件；只有能降低理解、执行或出错成本时才扩展视觉表达。
+- `rich`：主动利用图片、画板、HTML 和其他飞书组件；每个组件须有明确目的，不设全局数量配额。
+
+### Step 4：提交 Presentation Decision，并初始化草稿。
+
+生成完整 JSON；字段值必须来自 Step 1–3，不得照抄示例。`word_count` 仅在用户明确提出字数要求时加入，使用 `min` / `max`；单边无限制写 `null`，“约 N 字”按 ±10%，无要求时省略整个字段：
+
+```json
+{
+  "audience": "项目负责人",
+  "reader_task": "判断偏差并决定下一轮动作",
+  "genre_contract": null,
+  "adapter": null,
+  "presentation_mode": "rich",
+  "visual_plan": {
+    "reason": "需要用因果图解释偏差来源与后续行动依赖",
+    "blocks": [
+      {"type": "whiteboard", "min_count": 1, "purpose": "展示偏差成因与行动依赖"}
+    ]
+  }
+}
+```
+
+不预建临时目录、草稿或决策文件。将上述 JSON 原样替换命令中的占位符并实际执行：
+
+```bash
+lark-cli docs +script --command init-draft --presentation-decision '<上方完整 JSON>' --format json
+```
+
+成功后：
+
+- 保持当前工作目录不变；将 `data.workspace` 原样记为 `work_dir`，将 `data.draft_path` 原样记为 `draft_path`；遵循 `data.tip`，后续始终使用 `@./<draft_path>`。
+- CLI 会创建独占的 `work_dir` 并保存 `.presentation-decision.json` 作为固定基线，**但不会创建 `draft_path` 指向的 XML**。`draft_path` 是当前任务可直接写入的新文件路径；要求、资料或 contract 实质变化时，提交新决策并重新初始化，不得直接改基线。
+
+### Step 5：生成 release candidate。
+
+读取 [`lark-doc-xml.md`](lark-doc-xml.md)，并结合 Presentation Decision、适用 contract 和 Philosophy 生成完整 XML。使用扩展标签时按需读取 [`拓展标签`](lark-doc-xml-extended-blocks.md)。
+
+1. 公开网络图片使用 `<img href="URL"/>`；已有本地图片使用 `<img path="@./relative/path"/>`；画板使用 `<whiteboard path="@./relative/path"/>` 并遵循[`画板工作流`](lark-doc-whiteboard.md)；HTML 使用 `<html5-block path="@./file.html"/>` 并遵循[`拓展标签`](lark-doc-xml-extended-blocks.md)。
+2. 直接在 Step 4 返回的 `draft_path` 创建并写入完整 release candidate。
+3. 首次写入后，发现 XML 语法问题时只修复最小范围，不无故重写正确内容。
+
+### Step 6：执行 Draft Profile Check。
+
+1. 执行 `lark-cli docs +script --command parse --content "@./<draft_path>" --format json`。顶层 `ok` 仅表示命令执行成功，是否通过看 `data.assessment.status`。失败时按 `data.diagnostics[]` 局部修复；只有草稿为空、截断或结构无效时才全文重建。`parse` 不替代 XML 规则或服务端校验。
+2. Profile Check 通过后，按 [`lark-doc-xml.md`](lark-doc-xml.md) 复查标签、属性和值，并依据 Philosophy 检查事实与来源、用户硬约束、适用 contract / adapter 以及 `visual_plan`。最终 XML 能否写入以 `docs +create` 的服务端结果为准。
+
+### Step 7：创建文档并处理局部失败。
+
+1. 只有最新 release candidate 完成 Draft Profile Check 和 XML 规则复查后，才读取 [`lark-doc-create.md`](lark-doc-create.md)，使用同一个 `draft_path` 创建文档。
+2. 创建结果存在 warning、局部资源失败或回查发现局部问题时，不得再次新建文档；读取 [`lark-doc-update.md`](lark-doc-update.md)，对已创建文档做最小范围修复，并按 update 流程 fetch 验证。
+
+### Step 8：清理并交付。
+
+无论创建成功、失败或被阻塞，只要 Step 4 已返回 `work_dir`，就先离开该目录，再使用当前运行时的文件删除能力精确删除整个 `work_dir`；不要使用通配符，也不要删除目录外的用户原始文件。最终只交付用户需要的结果，并说明必要来源、未关闭缺口、异常、失败或阻塞原因，以及文档 URL 或 token。

package/skills/lark-doc/references/lark-doc-create.md

@@ -1,24 +1,15 @@
 # docs +create（创建飞书云文档）
 
-> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
-> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
-> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
->
-> **未读完以上文件就生成内容会导致格式错误。**
+从 XML（默认）或 Markdown 内容创建一个新的飞书云文档；语义创作默认使用 XML，只有 Authoring 明确判定为 Markdown 例外时才使用 Markdown。
 
-从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
-
-> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
+写入前必须按 `--doc-format` 读取对应格式参考：`xml` 读取 [`lark-doc-xml.md`](lark-doc-xml.md)，`markdown` 读取 [`lark-doc-md.md`](lark-doc-md.md)；Markdown 中使用 XML 扩展标签时还须读取 `lark-doc-xml.md`。
 
 ## 命令
 
 ```bash
-# 创建 XML 文档（默认格式，推荐）
-lark-cli docs +create --content '<title>项目计划</title><h1>目标</h1><p>记录本周重点。</p>'
-
-# 仅当用户明确要求导入 Markdown 时才使用；文档标题用 --title，正文标题按内容自然组织
-lark-cli docs +create --doc-format markdown --title "项目计划" --content $'## 目标\n\n- 明确重点\n- 记录待办'
+# 简单内容优先使用 `--content -`，文件导入如下：
+lark-cli docs +create --doc-format xml --content "@<XML 文件相对路径>"
+lark-cli docs +create --doc-format markdown --content "@./draft.md"
 ```
 
 ## 返回值
@@ -35,46 +26,29 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
       "new_blocks": [
         { "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
       ]
-    }
+    },
+    "warnings": [],
+    "tips": ""
   }
 }
 ```
 
-- **`document.new_blocks`**：本次操作新增的 block 列表（如画板）。`block_id` 可用于 `docs +update` 的 `--block-id` 做精确编辑；`block_token` 是资源块（如画板）的 token，可交给 `lark-whiteboard` 等 skill 继续操作
-
-> \[!IMPORTANT]
-> 如果文档是**以应用身份（bot）创建**的，如 `lark-cli docs +create --as bot` 在文档创建成功后，CLI 会**尝试为当前 CLI 用户自动授予该文档的 `full_access`（可管理权限）**。
->
-> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
-> - `status = granted`：当前 CLI 用户已获得该文档的可管理权限
-> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
-> - `status = failed`：文档已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
->
-> `permission_grant.perm = full_access` 表示该资源已授予”可管理权限”。
->
-> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+- **`document.new_blocks`**：本次操作新增的 block 列表（如画板）。`block_id` 可用于 `docs +update` 的 `--block-id` 做精确编辑；`block_token` 是资源块（如画板）的 token，可交给 `lark-whiteboard` 等 skill 继续操作。
+- **`warnings`**：服务端返回的警告列表；`ok=true` 时也要检查，按提示确认是否存在降级或未完全处理的内容。
+- **`tips`**：服务端返回的后续处理建议；为空表示没有额外建议，非空本身不表示创建失败。
+- **`permission_grant`**：仅以 bot 身份创建时返回。CLI 会尝试为当前 CLI 用户授予新文档的 `full_access`；`status` 为 `granted` 表示授权成功，`skipped` 表示没有可用的当前用户 `open_id`，`failed` 表示文档已创建但授权失败。`perm` 固定为 `full_access`，失败或跳过时按 `message` / `hint` 处理。**自动授权不等于 owner 转移；用户要求转移 owner 时必须单独确认。**
 
 ## 参数
 
-| 参数                  | 必填 | 说明                                          |
-| ------------------- | -- |---------------------------------------------|
-| `--title`           | 否  | 文档标题，Markdown 导入时使用；XML 创建推荐在 `--content` 开头写 `<title>...</title>`；多个标题仅保留第一个并在 `warnings` / `degrade_details` 提示 |
-| `--content`         | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title` |
-| `--reference-map` | 否 | 结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。 |
-| `--doc-format`      | 否  | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
-| `--parent-token`    | 否  | 父文件夹或知识库节点 token（与 `--parent-position` 互斥）  |
-| `--parent-position` | 否  | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |
-
-## 最佳实践
-
-- **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容
-- **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
+|参数|必填|说明|
+|-|-|-|
+|`--title`|否|文档标题，Markdown 导入时使用；XML 创建推荐在 `--content` 开头写 `<title>...</title>`；多个标题仅保留第一个|
+|`--content`|视情况|文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title`|
+|`--reference-map`|否|结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、任务独占目录内的相对 `@file`，或 `-` 从 stdin 读取。|
+|`--doc-format`|否|CLI 与语义创作均默认 `xml`，并建议显式传入；仅用户明确要求 Markdown 或保真导入 Markdown 时使用 `markdown`。不要混用完整的 XML 与 Markdown 文档格式；Markdown 中允许使用文档已定义的 XML 扩展标签。|
+|`--parent-token`|否|父文件夹或知识库节点 token（与 `--parent-position` 互斥）|
+|`--parent-position`|否|父节点位置，如 `my_library`（与 `--parent-token` 互斥）|
 
-## 参考
+## 需要回查文档
 
-- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
-- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
-- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
-- [`lark-doc-update.md`](lark-doc-update.md) — 更新文档
-- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
+用 `lark-cli docs +fetch --doc "<document_id 或文档 URL>" --detail with-ids` 回查，若需要更多信息可查看 [`+fetch`](lark-doc-fetch.md)。

package/skills/lark-doc/references/lark-doc-fetch.md

@@ -1,81 +1,78 @@
+# docs +fetch（读取飞书云文档）
 
-# docs +fetch（获取飞书云文档）
+读取整篇文档，或按目录、章节、区间和关键词获取局部内容。
 
-## 命令
+## 常用示例
 
 ```bash
-# 获取文档（默认 XML，simple）
-lark-cli docs +fetch --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
+# 读取整篇文档
+lark-cli docs +fetch --doc "文档URL或token"
 
-# Markdown 格式
-lark-cli docs +fetch --doc Z1Fj...tnAc --doc-format markdown
+# 按 URL 中的 #share 锚点局部读取
+lark-cli docs +fetch --doc '文档URL#share-anchor'
 
-# 带 block ID（用于后续 block 级更新）
-lark-cli docs +fetch --doc Z1Fj...tnAc --detail with-ids
+# 按关键词定位
+lark-cli docs +fetch --doc Z1Fj...tnAc --scope keyword --keyword "部署|发布|上线"
 
-# 只拿目录
+# 先查看目录，再读取指定章节
 lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
-
-# 按 block id 区间精读
-lark-cli docs +fetch --doc Z1Fj...tnAc --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
-
-# URL 带 #share 选区锚点时自动局部读取
-lark-cli docs +fetch --doc 'docURL#share-anchor'
-
-# 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
-lark-cli docs +fetch --doc Z1Fj...tnAc \
-  --scope section --start-block-id <标题id> --detail with-ids
-
-# 按关键词定位（多关键词用 | 分隔，任一命中即返回）
-lark-cli docs +fetch --doc Z1Fj...tnAc \
-  --scope keyword --keyword "部署|发布|上线"
+lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
 ```
 
-## 选 `--detail`（每块详细度）
-
-| 意图 | `--detail` | 说明 |
-|------|-----------|------|
-| **只读**：浏览或总结文档内容 | `simple`（默认） | 简洁 XML/Markdown，不含 block ID、样式属性、引用元数据 |
-| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `<p id="blkcnXXXX">`），可用于 `+update` 的 `--block-id`，也可用于拼接 `文档URL#block_id` 形式的直达链接 |
-| **编辑**：任何修改文档内容的需求 | `full` | 包含 block ID + 样式属性 + 引用元数据，提供完整文档结构信息 |
+## 参数
 
-## 选 `--scope`（读取范围）
+|参数|必填|说明|
+|-|-|-|
+|`--doc`|是|文档 URL 或 token，支持 `/docx/`、`/wiki/` 和带 `#share-...` 的选区链接|
+|`--doc-format`|否|`xml`（默认）\| `markdown` \| `im-markdown`（供后续 `lark-im` 场景使用）|
+|`--detail`|否|`simple`（默认）\| `with-ids` \| `full`|
+|`--revision-id`|否|文档版本号；`-1` 表示最新版本（默认）|
+|`--scope`|否|`outline` \| `range` \| `keyword` \| `section`；省略则读取整篇|
+|`--start-block-id`|否|`range` 的起点，或 `section` 的锚点（`section` 必填）|
+|`--end-block-id`|否|`range` 的终点；`-1` 表示读到末尾|
+|`--keyword`|否|`keyword` 模式的关键词；支持多级自动匹配和多分支 OR|
+|`--context-before`|否|返回命中项之前的顶层兄弟块数量（默认 `0`）|
+|`--context-after`|否|返回命中项之后的顶层兄弟块数量（默认 `0`）|
+|`--max-depth`|否|`outline` 表示标题层级上限；其它模式表示子树深度（默认 `-1`，不限）|
+|`--format`|否|`json`（默认）\| `pretty`|
 
-`--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。**
+## 选择详细度：`--detail`
 
-| 模式 | 何时用 | 关键参数 | 行为要点 |
-|-|-|-|-|
-| `outline` | 不知道结构，先看目录 | `--max-depth`（标题层级上限） | 扁平列出所有标题，**包括嵌在容器里的内嵌标题**（如 callout 里的 h3）；这些 id 可直接作后续 `section` / `range` 端点 |
-| `section` | 读某个标题对应的整节 | `--start-block-id`（必填） | 顶层标题 → 展开到下一同级/更高级标题前；容器内节点（含内嵌标题） → 按"最小包容单元"返回容器/表格切片，不做 heading 扩展；顶层非标题块 → 仅该块 |
-| `range` | 已知精确起止 | `--start-block-id` / `--end-block-id` 至少一个；`-1` = 读到末尾 | 两端同顶层 → 顶层序列切片；两端同一容器 → 容器整体；两端同一表格 → 瘦身切片；**跨顶层 → 端点所在顶层块整块输出，不做瘦身** |
-| `keyword` | 只有模糊关键词 | `--keyword`（**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\|` 分隔多分支 OR） | 每处命中按"最小包容单元"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |
+|目的|取值|返回内容|
+|-|-|-|
+|浏览、总结|`simple`（默认）|简洁 XML/Markdown，不含 block ID、样式和引用元数据|
+|定位、跳转|`with-ids`|包含 block ID，可用于 `+update --block-id`，也可拼成 `文档URL#block_id` 直达链接|
+|编辑文档|`full`|包含 block ID、样式和引用元数据，保留完整结构信息|
 
-> 💡 **多关键词用 `\|` 拼接（OR 语义，任一命中即返回）**：例 `"部署\|发布\|上线"`，三词任一命中都进结果，适合**同义词/别名/多业务术语**一次召回（如 `bug\|缺陷\|故障`）。
+需要修改文档时使用 `full`；只读场景通常不必获取额外元数据。
 
-**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`。
+## 选择读取范围：`--scope`
 
-- `--max-depth`：`outline` = 标题层级上限（3 = h1~h3）；其它模式 = 被选块的子树遍历深度（`-1` 不限，`0` 仅块自身）。
-- `--context-before/--context-after`：**只对整块顶层单元生效**；命中落在容器/表格内（返回容器或切片）时 before/after 被忽略，需要更大范围改用 `section` / `range` 显式指定。
+`--scope` 与 `--detail` 可以组合。优先读取满足任务所需的最小范围；只有确需全文时才省略 `--scope`。
 
-**决策顺序**（核心原则：**局部获取优于全量获取**，根据需求形态选起点，必要时多步组合收敛范围）：
-1. 需求**直接给出待查的具体术语/错误码/标识** → 直接走 `keyword` 粗匹配（多级 fallback 自动覆盖形变），需要更大上下文时用返回的 `top-block-id` 走 `section` / `range`
-2. 需求**指向某个章节/标题**（"修改 XX 章"、"总结第 3 节"、"关于 xx 的内容"）→ 先 `outline --max-depth 3` 拿目录 → `section --start-block-id <标题id>` 精读
-3. 已知**精确起止 / 跨节连续区间** → `range`
-4. **结构未知且无明确关键词/章节线索** → `outline` 探测，再回到 2/3
-5. **兜底**：仅在确需整篇时才省略 `--scope`；不要为省事直接读整篇
+|模式|适用场景|关键参数|返回行为|
+|-|-|-|-|
+|`outline`|结构未知，先查看目录|`--max-depth`|扁平列出标题；返回的标题 ID 可作为 `section` 或 `range` 的端点|
+|`section`|读取某个标题对应的整节|`--start-block-id`（必填）|顶层标题展开到下一个同级或更高级标题之前；容器内节点（含内嵌标题）按最小包容单元返回容器或表格切片|
+|`range`|已知精确起止位置|`--start-block-id`、`--end-block-id` 至少一个|同一顶层序列按区间切片；同一容器返回整个容器；同一表格返回瘦身切片；跨顶层时完整返回端点所在的顶层块|
+|`keyword`|只有关键词或模糊线索|`--keyword`（必填）|按最小包容单元返回命中；同一容器的多处命中自动去重，同一表格的多行命中合并为切片|
 
-## 局部读取的输出结构：`<fragment>` 与 `<excerpt>`
+`keyword` 会依次尝试子串、归一化、分词形变和 RE2 正则匹配。多关键词使用 `|` 表示 OR，例如 `部署|发布|上线`；任一分支命中即返回。
 
-设置 `--scope` 时返回的 `content` 被一个 `<fragment>` 节点包裹，属性包含 `mode` / `requested-start` / `requested-end` / `keyword`（按需）。子节点只有两种形态：
+范围参数的共同规则：
 
-- **顶层块**：完整块直接作为 `<fragment>` 的子节点，无额外包裹。
-- **`<excerpt top-block-id="..." parent-block-path="...">`**：非顶层节选（容器整体 / 表格瘦身切片）。
-  - `top-block-id`：所在顶层块 id，想看该块全貌时作 `section` / `range` 锚点再拉一次。
-  - `parent-block-path`：从顶层块到 excerpt 内容直接父节点的 id 路径，`/` 分隔（表格切片时即表格自身 id）。
+- `--max-depth`：`outline` 中 `3` 表示列出 h1～h3；其它模式中 `0` 表示仅返回块自身，`-1` 表示不限深度。
+- `--context-before` / `--context-after`：仅对完整的顶层块生效。命中位于容器或表格内时会被忽略；如需更大范围，改用 `section` 或 `range`。
 
-**看到 `<excerpt>` 即意味着这是节选**，不能假设看到了该顶层块的全貌。
+推荐选择顺序：
 
-**表格默认瘦身**：即便 `<table>` 本身是顶层块也只返回 thead + 命中 tr。想拿整张表 → `range --start-block-id <table-id> --end-block-id <table-id>`；切片范围恰好覆盖全部 tr 时 SDK 自动升级为整块、不包 `<excerpt>`。
+|已知信息|首选方式|后续动作|
+|-|-|-|
+|具体术语、错误码或标识|`keyword`|上下文不足时，用返回的 `top-block-id` 再执行 `section` 或 `range`|
+|章节或标题|`outline --max-depth 3`|获取标题 ID 后执行 `section`|
+|精确起止位置|`range`|按需调整端点或深度|
+|没有关键词，也不了解结构|`outline`|根据目录转入 `section` 或 `range`|
+|确实需要整篇|省略 `--scope`|—|
 
 ## 返回值
 
@@ -85,7 +82,7 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \
   "identity": "user",
   "data": {
     "document": {
-      "document_id": "doxcnXXXX",
+      "document_id": "docToken",
       "revision_id": 12,
       "content": "<title>标题</title><p>文档内容...</p>",
       "reference_map": {
@@ -100,49 +97,35 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \
   }
 }
 ```
-
 `content` 的格式由 `--doc-format` 决定。`reference_map` 是正文引用数据的结构化 sidecar：一级键 `block_type` 表示引用所在的块类型，二级键 `ref` 对应正文中的临时引用；每个引用的值是由 `real-attr-key` 和 `real-attr-value` 组成的真实属性映射，具体属性由块类型决定。没有提取数据时，`reference_map` 可能为空。`content` 和 `reference_map` 属于同一份响应，保留或回放内容时应配套处理。`tips` 给出安全回放或降级提示。`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见上文"局部读取的输出结构"。
 
+### 理解局部读取结果
+
 ## 参数
 
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
-| `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `im-markdown`（仅用于获取内容后在 `lark-im` 场景下使用） |
-| `--detail` | 否 | `simple`（默认）\| `with-ids` \| `full` |
-| `--revision-id` | 否 | 文档版本号，`-1` = 最新（默认） |
-| `--scope` | 否 | `outline` \| `range` \| `keyword` \| `section`（省略 = 读整篇） |
-| `--start-block-id` | 否 | `range`/`section` 起始/锚点 id（`section` 必填） |
-| `--end-block-id` | 否 | `range` 结束 id；`-1` 表示读到末尾 |
-| `--keyword` | 否 | `keyword` 模式关键词，**4 层自动 fallback**（子串 → 归一化 → 分词形变 → RE2 正则）；`\|` 分隔多分支 OR |
-| `--context-before` | 否 | 命中前拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
-| `--context-after` | 否 | 命中后拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
-| `--max-depth` | 否 | `outline` = 标题层级上限；其它 = 子树深度（`-1` 不限，默认） |
-| `--format` | 否 | `json`（默认）\| `pretty` |
-
-## 图片、文件、画板的处理
-
-**文档中的素材以 XML 标签形式出现：**
-
-```xml
-<img token="..." url="https://..." width="..." height="..."/>
-<source token="..." url="https://..." name="skills.zip"/>
-<whiteboard token="..."/>
-```
+设置 `--scope` 后，`content` 外层是 `<fragment>`，并按需携带 `mode`、`requested-start`、`requested-end` 或 `keyword` 属性。其子节点有两种形式：
+
+- **顶层块**：直接作为 `<fragment>` 的子节点，表示返回了完整块。
+- **`<excerpt top-block-id="..." parent-block-path="...">`**：表示只返回了容器或表格中的节选。
+  - `top-block-id` 是节选所在的顶层块 ID。需要查看完整块时，可将它作为 `section` 或 `range` 的锚点重新读取。
+  - `parent-block-path` 是从顶层块到节选内容直接父节点的 ID 路径，以 `/` 分隔；表格切片中即表格自身 ID。
+
+看到 `<excerpt>` 时，不要假设已经获取了整个顶层块。
 
-- `<img>` / `<source>` 带 `url` 时，直接用该 URL 下载即可（普通 HTTP GET），无需走 shortcut。
-- 没有 `url`、或只想预览 → `docs +media-preview --token <token> --output ./preview_media`
-- 明确下载，或目标是 `<whiteboard>`（画板只能走 shortcut） → `docs +media-download --token <token> --output ./downloaded_media`
-- 文档封面图不是正文素材；下载/更新/删除封面图 → `docs +resource-download/+resource-update/+resource-delete --type cover`
+表格默认瘦身：即使 `<table>` 本身是顶层块，也只返回表头和命中的行。读取整张表时，使用 `range --start-block-id <table-id> --end-block-id <table-id>`。如果切片覆盖全部数据行，SDK 会自动返回完整表格，不再包裹 `<excerpt>`。
 
-## 嵌入电子表格 / 多维表格
+## 处理文档内嵌资源
 
-返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
+|返回内容|处理方式|
+|-|-|
+|`<img>`、`<source>`|有 `url` 时仅下载可信的公开 HTTPS URL：拒绝 userinfo 及解析到 private、loopback、link-local、multicast、unspecified 地址的 host，并逐次校验重定向；不满足时禁止请求。无 `url` 时提取 `token`，预览用 `docs +media-preview`，下载用 `docs +media-download`|
+|`<whiteboard>`|提取 `token`，使用 `docs +media-download`|
+|`<sheet>`、`<cite file-type="sheets">`|提取 `token` 和 `sheet-id`，转到 [`lark-sheets`](../../lark-sheets/SKILL.md)|
+|`<bitable>`、`<cite file-type="bitable">`|提取 `token` 和 `table-id`，转到 [`lark-base`](../../lark-base/SKILL.md)|
+|`<vc-transcribe-tab>`|提取 `vc-node-id`，使用 [`lark-note`](../../lark-note/SKILL.md) 的 `note +detail`|
+|`<synced_reference>`|提取 `src-token` 和 `src-block-id`，读取源文档并定位 block|
 
 ## 参考
 
-- [lark-doc-create](lark-doc-create.md) — 创建文档
-- [lark-doc-update](lark-doc-update.md) — 更新文档
 - [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
-- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图
-- [lark-doc-resource-cover](lark-doc-resource-cover.md) — 读取、更新、删除文档封面图
+- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材或画板缩略图

package/skills/lark-doc/references/lark-doc-history.md

@@ -2,24 +2,25 @@
 
 用于查看 Docx 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
 
-## 安全流程
+`entries[].edit_time` 是 RFC3339 时间字符串（例如 `2026-06-22T12:24:45Z`）。按时间匹配时先将其解析为时间值，再比较先后关系或时间差。
 
-1. 先用分页接口 `+history-list` 找到目标版本的 `history_version_id`。
-2. 如果用户指定的是 `revision_id`，不要假设它唯一，也不要把 `revision_id` 直接传给 `+history-revert`。先拉一页并在 `entries[]` 中筛选 `revision_id` 相同的候选；如果未匹配到且 `has_more=true`，继续用 `page_token` 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 `edit_time` 的接近程度选择最合适的一条，取同一条的 `history_version_id`；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（`history_version_id`、`revision_id`、`edit_time`、`name/description`）并确认后回滚。
-3. 如果用户指定的是某一时刻但没有指定 `revision_id`，按 `entries[].edit_time` 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
-4. 再用 `+history-revert --history-version-id <history_version_id>` 发起回滚。默认最多等待 30 秒；如果返回 `status: running`，记录 `task_id`。
-5. 用 `+history-revert-status` 轮询 `task_id`，直到状态不再是 `running`。
-6. 回滚完成后，用 `docs +fetch` 读取文档确认内容。
+## 安全约束
 
-## 按 revision_id 或时间点回滚
+- `overwrite` 会重建正文和 block ID，且无法保证保留评论等非正文对象。用户要求保留这些对象时，应先说明限制并确认。
+- `overwrite` 返回 warning 或 `partial_success` 时，先核验最新内容。核验失败或发生 revision conflict 时停止，不要再次覆盖。
+- 权限、网络或临时系统错误应保留原错误分类，不得解释为目标版本不存在。
 
-当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：
+## 按 revision_id 或时间点回滚
 
-1. 执行 `docs +history-list --doc <doc>` 获取第一页历史记录；`+history-list` 是分页接口，只有 `has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
-2. 如果用户给出 `revision_id`：先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。如果未命中且 `has_more=true`，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 `revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间，在候选里选择 `edit_time` 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
-3. 如果用户只给出时间：用 `entries[].edit_time` 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
-4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`，这是回滚接口需要的 ID。
-5. 执行 `docs +history-revert --doc <doc> --history-version-id <history_version_id>`。
+1. 使用 `+history-list` 定位目标记录。需要更多候选时，根据 `has_more` 和 `page_token` 翻页。
+   - 用户指定 `revision_id`：逐页筛选相同 `revision_id` 的记录。未命中时必须继续翻页至 `has_more=false` 才可进入 fallback；命中位于页尾时，继续读取下一页以收集相邻的同 `revision_id` 候选。多条记录时结合 `edit_time` 选择；无法区分时请用户确认。
+   - 用户指定时间：选择不晚于目标时间的最近一条记录；用户明确要求“最接近”时，选择时间差最小的记录。
+2. 找到目标记录后，使用该记录的 `history_version_id` 调用 `+history-revert`。不要将 `revision_id` 传给回滚接口。返回 `running` 时使用 `+history-revert-status` 查询；只有 `done` 表示成功，其他终态均停止并报告。
+3. 没有目标记录但用户指定了 `revision_id` 时，可读取目标版本并恢复正文：
+   - 使用 `docs +fetch --doc "<doc>" --revision-id <revision_id> --scope full --detail full --format json` 读取目标版本。确认文档一致、返回的 `revision_id` 与目标一致，且 `content` 不是 `<fragment>`。
+   - 使用 `docs +fetch --doc "<doc>" --scope full --detail full --format json` 读取当前完整文档，其 `content` 同样不得是 `<fragment>`。目标与当前响应的 `revision_id` 相同时直接结束，不执行 `overwrite`。否则移除目标 `content` 中旧的 block ID，将正文写入任务目录下的相对路径，然后仅执行一次 `docs +update --doc "<doc>" --command overwrite --revision-id <current_revision_id> --content @target.xml`，其中 `current_revision_id` 来自当前文档响应。目标响应包含非空 JSON object 形式的 `reference_map` 时，将其写入相对路径并追加 `--reference-map @target-reference-map.json`；否则省略该参数。`+update` 不支持 `--yes`。
+   - 使用 `docs +fetch --doc "<doc>" --scope full --detail full --format json` 读取最新完整文档并核验。忽略重新生成的 block ID，正文结构、文本、链接和引用资源应与目标版本一致。
+4. 目标版本明确不可读时停止并报告。
 
 候选确认时使用类似格式：
 
@@ -71,7 +72,7 @@ lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<tas
     {
       "revision_id": 42,
       "history_version_id": "11",
-      "edit_time": "1780000000",
+      "edit_time": "2026-06-22T12:24:45Z",
       "type": 1,
       "name": "版本名",
       "description": "版本说明",

package/skills/lark-doc/references/lark-doc-md.md

@@ -48,7 +48,7 @@
 自行构造 Markdown 内容写入时同理：如字面文本 `a]b` 应写为 `a\]b`，`C:\Users` 应写为 `C:\\Users`。
 
 ## Shell 传参
-- **首选文件传参**：`--content` 支持 `@path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）
+- **首选文件传参**：`--content` 支持 `@./path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）
 - **⚠️ `@file` 路径限制**：`@file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下（如 `./_content.md`），用完自行清理。
 - **默认用单引号 `'...'`**：完全字面量，`$`、`` ` ``、`\`、`>`、`\<b>` 等全部原样保留
 - **双引号 `"..."`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\` 仍参与转义，易踩坑
@@ -66,6 +66,10 @@ Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下
 - URL 支持 `http://` 和 `https://` 协议
 - 对应的 XML 格式为：`<img href="https://example.com/photo.png"/>`
 
+本地图片使用 `![alt](@./images/photo.png)`（路径含空格时写作 `![alt](<@./images/product shot.png>)`）；路径必须位于当前工作目录内，`alt` 会作为 caption。附件使用 `<source path="@./files/report.pdf"/>`
+
+目前不支持将 Base64 Data URI（如 `data:image/png;base64,...`）直接作为 Markdown 图片地址传入；如仅有 Base64 数据，请先解码为本地图片文件，再使用上述 `@./...` 路径上传。
+
 ## Markdown 不支持的 Block 类型
 
 非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。

package/skills/lark-doc/references/lark-doc-media-download.md

@@ -41,7 +41,8 @@ lark-cli docs +media-download --type whiteboard --token "wbcnxxxxxxxx" --output
 
 ## 排障
 
-- 如果报错返回的信息包含 `HTTP 403`，且目标是图片/文件素材，可以改成调用 [`docs +media-preview`](lark-doc-media-preview.md) 看是否能先预览内容
+- 如果返回 `permission_denied`，或最终下载返回 `HTTP 403`，按错误 `hint` 改用 [`docs +media-preview`](lark-doc-media-preview.md) 预览内容。
+- 如果返回限流错误，停止立即重试，稍后按指数退避重试。
 
 ## 参考
 

package/skills/lark-doc/references/lark-doc-script.md

@@ -0,0 +1,76 @@
+# `docs +script`
+
+## 脚本列表
+
+| `--command` | 用途 |
+|-|-|
+| `init-draft` | 创建带 Presentation Decision 基线的独占工作区，并预留尚不存在的 XML 路径。 |
+| `parse` | 解析本地或在线文档，返回画像并检查决策与资源。 |
+
+每个脚本只使用其小节列出的专用参数；所有脚本均可使用文末的通用参数。
+
+## `init-draft`
+
+### 参数
+
+| 参数 | 必填 | 用法 |
+|-|-|-|
+| `--command init-draft` | 是 | 选择本脚本。 |
+| `--presentation-decision` | 是 | 完整决策 JSON；接受内联 JSON、`@./decision.json` 形式的 CWD 下相对路径或 `-`（stdin）。 |
+
+```bash
+lark-cli docs +script --command init-draft \
+  --presentation-decision '<完整 Presentation Decision JSON>' \
+  --format json
+```
+
+`data` 的结构如下；实际随机段为 8 位十六进制字符：
+
+```json
+{
+  "workspace": "draft_a1b2c3d4_folder",
+  "draft_path": "draft_a1b2c3d4_folder/draft.xml",
+  "tip": "The workspace directory has been created successfully. draft_path points to a new XML file that does not exist yet. Create and write the file directly without reading it first."
+}
+```
+
+- 在生成正文前执行；不要自行创建工作目录或决策文件。CLI 固定生成 `draft_<8位十六进制字符>_folder/draft.xml`，以返回的实际路径为准。
+- 决策必须是单个 JSON 对象，包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`。`presentation_mode` 取 `formal|normal|rich`；`genre_contract`、`adapter` 使用固定短名、`"none"` 或 `null`。
+- `visual_plan` 包含非空 `reason` 和 `blocks` 数组；每项为 `{type,min_count,purpose}`，`type` 不重复，`min_count` 为正整数。按本 Skill 创建文档时，`blocks` 只对 `whiteboard`、`img`、`html5-block` 设置最低数量，其他表达按内容需要使用但不设数量约束；三类均无需约束时写 `[]`。CLI 为外部决策兼容 `type: "list"`，检查时将 `<ul>` 与 `<ol>` 的数量相加。仅有字数要求时添加 `word_count: {min,max}`；未指定的一侧写 `null`，至少一侧为正整数，且 `min <= max`。
+- 返回 `data.workspace`（已创建的随机工作区）、`data.draft_path`（可直接写入的 XML 路径）和英文操作提示 `data.tip`。工作区及其中的 `.presentation-decision.json` 已存在，但 XML 尚不存在；遵循提示直接使用文件创建/写入能力在 `draft_path` 写入完整 XML，首次写入前不要读取该路径。
+- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；使用完后精确删除 `workspace`。
+
+## `parse`
+
+### 参数
+
+| 参数 | 必填 | 用法 |
+|-|-|-|
+| `--command parse` | 是 | 选择本脚本。 |
+| `--content` | 二选一 | 本地 XML 的字面内容、`@./document.xml` 形式的 CWD 下相对路径或 `-`（stdin）。 |
+| `--doc` | 二选一 | 在线 Docx/Wiki URL 或 token；与 `--content` 互斥。 |
+| `--presentation-decision` | 否 | 用于检查当前输入的完整决策 JSON；支持内联、`@./decision.json` 形式的 CWD 下相对路径或 `-`。 |
+
+```bash
+lark-cli docs +script --command parse --content "@./document.xml" --format json
+lark-cli docs +script --command parse --doc "<Docx/Wiki URL 或 token>" --format json
+lark-cli docs +script --command parse --content "@./document.xml" --presentation-decision '<JSON>' --format json
+```
+
+- `--content` 与 `--presentation-decision` 同时使用时，最多一个参数读取 stdin。
+- 决策必须包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`；`presentation_mode` 取 `formal|normal|rich`。`visual_plan` 包含非空 `reason` 和不重复的 `{type,min_count,purpose}` 数组；兼容的 `list` 约束按 `<ul>` 与 `<ol>` 的合计数量检查。仅有字数要求时添加合法的 `word_count: {min,max}`。
+- 使用 `--content "@./<init-draft 返回的 data.draft_path>"` 时自动加载保存的决策；显式 `--presentation-decision` 优先。
+- `--doc` 需要 `docx:document:readonly`；`--content` 不调用 OpenAPI。
+- 返回 `data.assessment.status`、`data.profile` 和按需出现的 `data.diagnostics[]`；profile 包含 `word_count`、`char_count`、`block_count` 和 `blocks[]`。顶层 `ok` 只表示命令是否成功执行。画像、决策或资源预检未通过时，命令仍以 `ok:true` 和退出码 0 返回，但 `assessment.status` 为 `failed`；每条 diagnostic 提供 `severity`、稳定 `code`、`msg`、可选 `expected` / `actual` 和 `suggested`。同一原因失败的远程图片合并为一条 diagnostic，并在 `image_indices[]` 中列出图片序号，避免重复提示。修复后重新解析，直到 `assessment.status` 为 `passed`。
+- `parse` 不是 XML/SDK schema validator。成功且无 warning 也不保证服务端接受；写入前仍须按 XML 规则复查。
+
+## 所有脚本通用参数
+
+| 参数 | 用法 |
+|-|-|
+| `--as user|bot` | 选择身份。 |
+| `--dry-run` | 只返回执行计划，不联网、解析或写文件。 |
+| `--format` | 输出格式：`json|pretty|table|ndjson|csv`；模型使用默认的 `json`。 |
+| `--json` | `--format json` 的别名。 |
+| `--jq` / `-q` | 裁剪 JSON；不得与非 JSON 格式同时使用。 |
+| `-h` / `--help` | 查看帮助。 |