lark-doc

# Genre Contract: Business Analysis / 商业分析 (`report.business_analysis`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 结论前置、具体、条件化；模型只用于改变比较或暴露约束，不用管理黑话代替判断 |
| 内容逻辑 | 围绕一个具体决策，比较现状 / 不行动与真实替代项；用统一目标和口径评价价值、全周期成本、风险、约束与可实施性，给出推荐、暂缓或验证门及翻转条件 |
| 事实 / 边界 | 事实、估算、假设、未知和外部依赖分开；数字标来源、时点、单位、口径和置信范围；利益相关方、不可货币化影响和权限边界显著；分析建议不等于批准或承诺 |
| 错误 | 为预选方案找论据；无现状基准或真实替代项；口径不一却排名；单一 ROI / BCR / 评分替代平衡判断；套 SWOT；估算冒充事实；忽略全周期成本、依赖或分配影响；未获批写成已承诺；建议不回链证据 |

## 适用与消歧

比较投资、资源、市场、产品、经营或供应选项并支持判断，但正文不要求具名决策者作出选择 / 批准，也不形成授权、资源拨付或执行承诺入口。`商业`、`市场分析`、`SWOT`单独只用于召回；回答研究问题走 [`research-report.md`](research-report.md)，纯指标解读走 [`data-report.md`](data-report.md)，命中上述 ask / 授权入口时走 Workplace Proposal，接口、不变量和实现取舍为主走 Technical RFC。

## 子类型

投资 / 资源配置；build-buy-partner 或 vendor；市场进入 / 扩张；产品 / 组合优先级；经营模式 / 流程；定价 / 商业模式；高不确定性的试点或阶段门。分析深度随金额、复杂度、不可逆性、影响范围和风险提高。

## 证据与方法

- 定义问题、目标、成功标准、范围、约束、决策 owner / 时点和现状 / 不行动基准；记录选项生成与排除理由。
- 对每个可行选项用相同维度比较收益、全生命周期成本、时间、能力 / 依赖、风险、受影响方、不可货币化影响和可逆性。
- 现状数据与预测分开；按需说明币种、价格时点、折现和估算方法。不得从官网标价推断销量、收入或份额。
- 对可能翻转结论的假设做范围、情景或敏感性分析，并给 switching value、决策门或验证信号；评分模型须解释权重和证据，不能只报总分。
- 缺目标、成功标准、基准或可行选项时只产出 decision frame / options discovery；关键估算用 `[成本区间待核]` 和验证计划，可能翻转结论且无法界定时标记 `blocked`。

## 结构与高质量写法

推荐与条件 → case for change / 目标 / 现状基准 → 选项生成、排除理由与同口径比较 → 关键假设、风险、情景与翻转条件 → 建议为何优于替代 → 阶段门、监测 / 学习计划与未决条件。把现状当真实选项，用区间和场景替代伪精确单点，显著说明谁获益、谁承担成本，以及什么新证据会改变建议。

# Genre Contract: Data Report / 数据报告 (`report.data_report`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 准确、可复算、少形容词；标题表达发现、对象和时点，并保留不确定性 |
| 内容逻辑 | 先建立指标契约和可比基线，再回答发生了什么、为何重要、还不能断言什么；观测、解释假设与行动条件分开，限制紧邻相关结论 |
| 事实 / 边界 | 核心指标标定义、单位、分子分母、总体 / 分群、时间窗、来源 / 版本、更新时间和修订状态；比较须同口径，估计须披露可得不确定性，敏感小群体须汇总、抑制或限制访问；数据图须标轴、单位、分母、时点和来源，并提供文字等价信息 |
| 错误 | 只列数字；隐藏分母或口径变化；不可比数据排名；选择性窗口 / 分群；相关性当因果；图轴、单位或来源缺失；统计显著冒充效应大小或业务胜出；伪精确；限制藏在附录 |

## 适用与消歧

解读已定义指标、趋势、分布、漏斗、监控、估计或实验观察值。`有数据`、`有数字`、`分析一下`单独不决定路由；研究问题、抽样和可推广性为主走 [`research-report.md`](research-report.md)，比较商业选项走 [`business-analysis.md`](business-analysis.md)，组织状态、偏差和下一步走 Workplace 周期报告。

## 子类型

- KPI / 经营表现与趋势；分群、cohort 与分布；漏斗 / 路径与监控异常。
- A/B 或实验 readout；设计和推断不足时只能报告观察值，不宣布因果胜出。
- 预测、估计、修订或统计简报；须标模型 / 假设、适用期和修订状态。

## 证据与方法

- 保留可复算的基数、过滤、聚合、估计区间和质量说明；比较前核对定义、总体、时间窗、分母和处理方法。
- 按误解风险同时给绝对值、绝对变化、相对变化和长期基线；不用多余小数位制造精确感。
- 覆盖、缺失、偏差、口径变化和修订若会改变解释，须与对应发现同处，并说明可能方向、规模和影响。
- 描述性差异不得写成因果；解释标为待验证假设。统计显著性不等于效应大小、实际重要性或完整决策依据。
- 缺定义、分母、时间或来源时使用 `[指标定义待核]`、`[分母待核]`，对应值不得进入结论；不可比数据分开展示。核心决策依赖的质量缺口无法关闭时标记 `blocked`。

## 结构与高质量写法

关键发现与决策限制 → 指标契约 / 数据质量 → 总览与基线 → 必要分维、分布和反例 → 可支持的解释与待验证假设 → 条件式行动 / 验证门 → 方法、修订和来源。每段按“观测 → 基线 / 背景 → 限制 → 含义”推进；复杂图同时给出文字结论和必要精确值，任何视觉不得成为唯一证据。

# Genre Contract: Email / 邮件 (`platform.email`)

## 核心定位（硬约束）

- 交付物是可复制到邮件客户端的邮件成稿，不代表已发送，也不执行收件人查询、邮件发送、草稿箱或邮箱管理；实际邮件操作切到 `lark-mail`。
- 视觉策略默认使用 `formal`；仅在用户要求且不违反组织规范或所选 content contract 时调整。全文禁止 emoji、高亮块和装饰性组件。
- 默认只使用短段落、列表和普通链接等基础结构。只有已由用户说明、平台文档或可信配置确认目标平台完整支持飞书富文本时，才允许使用 `rich` 或 rich block；不得根据“邮件”“HTML 邮件”、飞书文档承载或平台名称自行推断支持。
- 一封邮件只承担一个主要沟通任务；主题、首段、正文和行动请求围绕同一目的。不得编造发件人身份、收件人关系、事实、权限、承诺、截止时间、附件或已完成动作；缺失但必需的信息使用清楚的占位符。
- 不使用封面或目录。即使已确认平台能力，表格、图片、`callout`、画板及其他 rich block 也只能在信息确有需要时使用，并确保复制、投递和接收后的语义完整。

## 适用与消歧

用户明确要“写邮件、邮件成稿、邮件草稿、邮件措辞、email、e-mail”，或要求起草回复、跟进、通知、邀约、外联邮件时使用，内容保存在哪里不影响本合同生效。

查看、搜索、发送、回复或管理邮箱中的真实邮件属于 `lark-mail` 操作；邮件系统说明、邮件数据分析、营销方案或把邮件作为信息来源时不触发本合同。若任务既要成稿又要实际发送，先按本合同形成并确认内容，再切到 `lark-mail` 执行发送。

## 邮件主任务

| 主任务 | 内容脊柱 |
|-|-|
| 请求 / 决策 | 目的或结论 → 必要背景 → 明确请求 / 选项 → 期望时间或下一步 |
| 通知 / 同步 | 关键变化 → 影响范围 → 接收方需知 / 需做 → 时间点与联系入口 |
| 回复 / 跟进 | 对应的前情 → 新信息或直接答复 → 未决事项 → 下一步 |
| 邀约 / 外联 | 联系缘由 → 与收件人的相关性 → 具体提议 → 低成本回应方式 |
| 致歉 / 问题沟通 | 承认影响 → 已确认事实 → 补救动作 → 后续安排与边界 |

## 成稿要求

- 成稿先给主题，再给正文；只有用户要求或材料明确时才列出收件人、抄送人等信封字段。主题准确表达对象、事项或所需行动，不使用标题党、空泛寒暄或无信息量的“重要通知”。
- 称呼依据已知关系和语境选择；关系不明时使用稳妥中性的称呼或显式占位符，不擅自套用亲密、职级或性别称谓。
- 首段尽快说明来意、结论或与既有线程的关系。背景只保留收件人理解、判断或行动所需的信息，不把完整报告、会议纪要或思考过程原样搬入邮件。
- 行动请求写清需要谁在何时以何种方式完成什么；材料没有给出负责人或时间时，不自行补造。多个并列事项使用列表，优先让收件人能直接逐项回应。
- 提及链接、附件或引用材料时说明其用途；未实际提供或上传的材料写成待补占位符，不声称“见附件”。回复和跟进邮件只补充新信息，不机械复述整个线程。
- 结尾与邮件目的匹配：请求类明确回应方式，通知类说明无需动作或下一节点，外联类保留易于拒绝或调整的空间。署名仅使用已知身份；身份不明时使用占位符，不虚构姓名、团队或联系方式。

## 交付前检查

确认收件人能从主题和首段判断“为什么收到、需要知道或做什么”，事实、责任人、时间和附件状态均有依据，正文没有无关铺垫或重复，语气符合关系与风险，全文无 emoji；若使用 rich block，已有目标平台支持飞书富文本的确认依据；复制到邮件客户端后仍清晰可读，且未把“成稿”误写成“已发送”。

# Genre Contract: Execution Plan / 执行计划 (`workplace.execution_plan`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 以交付和判断为单位，具体、紧凑、可推进；计划可信度来自依赖、产能和验收闭环，不来自章节数量或精确到没有依据的日期 |
| 内容逻辑 | 从已批准结果、成功标准、范围和约束出发，按“交付物 / 工作流 → 依赖与关键路径 → 带退出条件的里程碑 → owner / 接口 / 资源 → 风险触发与备选 → 治理、变更与验收”推进 |
| 事实 / 边界 | 区分已确认承诺、估算、假设和待定项；时间、owner、预算、产能、权限、依赖与验收方须可追溯且算术相容；未批准方向不得写成承诺，关键资源或安全前提未知时收窄计划或 `blocked` |
| 错误 | 任务清单冒充计划、活动无交付物 / 完成定义、里程碑只是日期、排期不服从依赖与产能、所有事项同优先级、接口或验收方缺失、风险无预警信号 / 动作 / owner、变更后不更新基线，任一出现即失败 |

## 适用与消歧

用于方向和目标已定后，组织一次性项目、迁移、发布、活动战役、专项治理或跨团队变更。主要任务仍是选择方向、申请预算 / 资源或授权时走 `proposal.md`；比较策略选项且不形成批准入口走 `business-analysis.md`；发布已授权规则 / 通知走 `formal-doc.md`；重复确定路径走 `sop-tutorial.md`；报当前状态走 `weekly-report.md`。

“项目计划、执行方案、实施计划、营销策划”只作召回词。营销策划若仍在决定打法或预算，按上述 Proposal / Business Analysis 消歧；只有已定打法的协同落地走本合同。

## 可执行性与证据

- 先写可验收结果、范围 / 非范围、约束和最迟决策点；再按交付物而非部门名称拆工作包。每个关键工作包说明 owner、输入 / 输出、依赖、完成定义和验收方。
- 标出关键路径、可并行项、阶段入口 / 退出条件与资源瓶颈；日期由依赖、产能和必要审批 / 制作 / 校准时间推导。无法推导时用相对时间、区间或具体占位，不补造精确排期。
- 风险写预警信号、影响、预防 / 响应动作、决策 owner 和备选路径；备选必须说明何时切换及切换后的安全或业务终态，不写“加强沟通”。
- 治理只保留会产生判断的节奏：接口、升级条件、决策权、范围 / 基线变更和重新验收。密集对应关系可用一张排期、依赖或责任表，但表格不能替代关键路径和取舍说明。

## 高质量写法

让每个目标能一路回链到交付物、里程碑和工作包，让每个日期能回链依赖与产能，让每个风险能回链触发后的动作。资源不足时缩范围、分阶段或设决策门，不用“全渠道、全覆盖、同步推进”制造伪可行性。

# Genre Contract: Formal Document / 内部正式材料 (`workplace.formal_doc`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 庄重、准确、简洁、直接；正式性来自真实权威、事实、边界、责任和生命周期，不来自套话或机械层级 |
| 视觉策略 | 固定 `formal`；格式中立的内容稿完成后再应用，禁止高亮块、emoji 和装饰性组件 |
| 允许 block | `title`（完整文稿最多 1 个）、`p`、`h1`、`h2`、`h3`、`h4`；标题层级连续且不超过四级 |
| 限用 block | `ul`、`ol`容器及`li`子块仅承载真实并列或顺序；`table`容器及`thead`、`tbody`、`tfoot`、`tr`子块仅承载多对象同字段信息；`img`、`figure`仅承载有必要证据作用、来源说明和文字等价信息的材料 |
| 禁止 block | 禁止未列入允许 / 限用清单的类型，包括`callout`、`checkbox`、`grid`容器及`column`子块、`whiteboard`、`blockquote`、`pre`、根级`code`和`hr`；禁止装饰色、贴纸、伪红头、伪印章和无证据作用的配图 |
| 内容逻辑 | 先按读者任务选择规则 / 制度、已批准通知 / 安排、检查整改 / 台账或已核定正式说明之一；只写完成该任务所需的对象、依据、要求 / 发现、责任、核验和生命周期，不混写子类型 |
| 事实 / 边界 | 只把已确认的授权、要求、事实和立场写成定论；来源陈述、原始记录、已复核事实和推断分开；外发前确认保密、商业秘密、个人信息、素材权利和发布权限；关键缺口未关闭时不得创建 |
| 错误 | 因“正式”误判公文，把本 leaf 当方案 / 总结 / 简报兜底，伪造批准 / 生效，用通知偷渡未获授权的新规则，网络素材冒充本单位事实，检查线索写成责任结论，或措施与发现不对应，任一出现即失败 |

## 适用与收口

用于把已授权的非公文组织规则或安排、可复核的检查整改记录，或已核定的组织立场写成正式载体，使读者能够判断适用范围、应采取的行动、记录状态或核心立场。

待批准方向走 `proposal.md`；复杂一次性执行走 `execution-plan.md`；重复操作步骤走 `sop-tutorial.md`；党政机关公文走 `official-redhead.md`；高层简报走 `memo-brief.md`；周期状态走 `weekly-report.md`；学习总结走 Retrospective / Report。`正式、制度、通知、方案、计划、总结、简报、讲话稿`等词单独不触发本体裁，本体裁也不是不确定请求的 fallback。

## 按读者任务选择唯一内容路径

| 读者任务 | 内容主线 |
|-|-|
| 判断持续规则 | 目的与权威 → 适用 / 不适用范围 → 必要定义 → 规范要求 → 责任、例外与升级 → 生效、维护、复审和替代 |
| 执行已批准通知 | 发布主体与批准状态 → 受影响对象及范围 → 已确认事项与生效时间 → 动作、责任与期限 → 例外、反馈和联系人 |
| 复核检查整改 | 对象、范围、方法与证据状态 → 每项可观察发现、标准、影响和已支持原因 → 对应措施、责任与期限 → 核验、关闭证据和变更痕迹 |
| 理解已核定立场 | 讲者或发布主体、场合、受众与时长 → 核心立场 → 必要事实和理由 → 期望理解或行动；不混入制度效力 |

## 证据与高质量写法

- 规则类按需写维护责任、版本、批准、生效、复审和替代状态；稳定描述做什么、谁负责、何时生效，易变操作方法链接到受控 SOP。规范词优先沿用组织现有定义，强度不明时标`[规范强度待确认]`。
- 检查整改区分用户陈述、原始记录、已复核事实和待补证线索；关键日期、数量或结论证据不足时就近标`[证据待补：补证动作]`，不得推断原因或责任；归档补正保留原记录。
- 检查措施必须对应具体发现并可核验；已批准通知只传达授权范围内的事项；正式讲话只使用已核定立场，并按真实语速朗读校验。
- 使用主动句、明确主体和一致术语，一句只表达一个事实、判断、要求或许可；清单严守用户指定数量与字段，不机械补背景或文控字段。
- 批准者、依据、权限、适用范围、生效状态或发布条件不明时使用具体占位并保持草案；不得以版式、标题或署名暗示已经批准、签发或生效。

# Genre Contract: Meeting Minutes / 会议纪要 (`workplace.meeting_minutes`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 中性、精确、按议题和决定组织，用稳定标签区分决定、建议、未决和待确认，不重放发言顺序 |
| 内容逻辑 | 先说明会议身份和记录状态，再按议题写实际材料 / 必要讨论摘要 → 决定及理由 / 异议 → 未决项 → 行动 → 审阅材料；深度与治理风险相称 |
| 事实 / 边界 | 出席、法定人数、冲突、动议、表决、决定、owner、期限和批准状态均须来自会议材料或确认；只保留治理所需个人信息，草稿不得冒充批准版；历史状态固定为文字快照，不得由`checkbox`、`task`等可变交互块改写 |
| 错误 | 摘要冒充逐字稿、讨论流水账、建议写成决定、行动不可跟踪、法定人数不明却宣称决定有效、草稿冒充批准、静默改历史或泄露无关个人信息，任一出现即失败 |

## 适用与消歧

用于某次已发生会议的可引用治理记录，使缺席者、执行者和审核者确认决定、未决与行动。逐字 / 逐发言人 / 可回放内容只是 transcript 源材料；会前准备走 `memo-brief.md`；非会议状态走 `weekly-report.md`；党政机关法定“纪要”走 `official-redhead.md`。

## 子类型与治理证据

普通工作会可精简为会议身份、决定、未决和行动；项目决策会补必要理由与审阅材料；董事会、委员会、表决或法定会议按章程 / 适用规则记录出席、法定人数、利益冲突、动议、票决、精确决议及认证。

证据可来自 agenda、出席记录、实际审阅材料、动议 / 投票和录音 / 逐字稿，但正文只链接关键来源，不复制附件淹没决定。来源冲突并列保留并交主持人 / 参会者确认。

## 结构与高质量写法

标明名称 / 类型、日期时间、地点 / 方式、主持 / 记录和草稿 / 已批准状态；每个议题围绕结果而非发言顺序。行动项写交付物 / 动作、责任人 / 单位、时间要求和状态。缺失信息用`[决议原文待确认]`、`[owner 待确认]`等具体占位；法定人数或批准不明时不得宣称有效，保持草稿并进入确认流程。

# Genre Contract: Memo / Brief (`workplace.memo_brief`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 直接、克制、按具名读者控制信息密度，首屏给结论、状态或 ask，不设固定篇幅 |
| 内容逻辑 | 先选信息、决策或会前三种模式之一，再按“核心事项 / ask → 必要事实 → 影响 / 取舍 → 风险 / 未知 → 动作”推进；只有真实选择才写选项 |
| 事实 / 边界 | 事实、数字、立场、审批状态和时点均须可核验；未知与假设就近标记；Memo 只可作完整 Proposal 的决策封面，不替代其论证 |
| 错误 | 首屏无结论或 ask、把完整 Proposal 压成摘要、编造审批 / 立场、用固定篇幅删证据、细节不解释影响，任一出现即失败 |

## 适用与消歧

用于让具名内部读者快速知悉、判断或完成会前准备。请求批准完整方向、预算、资源或执行承诺走 `proposal.md`；按周期判断相对目标的位置走 `weekly-report.md`；“摘要 / 简报”单词本身不触发本体裁。

## 子类型与证据

- 信息 Brief：变化 → 影响 → 当前状态 / 风险 → 下一步；无须行动时明确“仅供知悉”。
- 决策 Memo：决定事项 / 时点 → 现状 → 真实选项及同口径影响 → 推荐与证据 → 明确决策入口。
- 会前 Brief：会议目标 → 已核验的参与方立场 / 利益 → 要点与禁区 → 期望结果；未知立场不得补造。
- 按需标读者、作者 / 责任团队、日期和信息截至时间。持续更新时说明相对上版的变化及下次更新点。

## 结构与高质量写法

按重要性而非材料顺序组织，一个段落一个观点；关键判断不藏在附件。建议写清谁做什么、为什么以及怎样判断完成，并呈现足以改变判断的风险、反例和不确定性。缺关键事实时用`[关键结论待确认]`、`[数据口径待核]`等具体占位，或收窄为待核问题清单；仍要求据此批准时必须 `blocked`。

# Genre Contract: Official Document / 公文内容稿 (`workplace.official_redhead`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 庄重、准确、简洁、直接；禁网感、营销话术、情绪化评价、空话和机械编号 |
| 视觉策略 | 固定 `formal`；禁止高亮块、emoji 和装饰性组件 |
| 允许 block | `title`（完整文稿最多 1 个）、`p`、`h1`、`h2`、`h3`、`h4`；标题层级连续且不超过四级 |
| 少用 block | `ul`、`ol`容器及`li`子块仅用于真实并列项，不替代公文层级序号；`table`容器及`thead`、`tbody`、`tfoot`、`tr`子块仅用于非表格难以清楚表达的多对象同字段信息 |
| 禁止 block | 禁止未列入允许 / 少用清单的类型，包括`callout`、`grid`容器及`column`子块、`checkbox`、`whiteboard`、`blockquote`、`pre`、根级`code`、`hr`、`img`、`figure`；禁装饰色、伪红头和伪印章 |
| 内容逻辑 | 按行文目的、机关关系和受众确定唯一文种，再按“必要依据 / 缘由 → 核心事项 / 决定 → 可执行要求 → 必要结语”推进 |
| 事实 / 边界 | 只写已给定或已核验的事实、依据、权限和决定；未知项具体占位，关键缺口未关闭时不得创建；飞书只交付内容审校稿，不宣称已签发或生效 |
| 错误 | 禁止文种或行文关系错误、报告夹请示、请示一文多事 / 多头主送、批复无对应请示、引用 / 文号 / 序号 / 附件不规范，以及编造事实、依据、权限或制发要素 |

## 适用

仅在明确要求公文、红头 / 套红、正式发文，或法定文种与机关行文关系、发文字号、签发人、主送机关等制发要素共同出现时使用。“红头文件”是制发信号，不是文种；普通公司通知、制度、检查 / 整改材料走 `formal-doc.md`，普通会议记录走 `meeting-minutes.md`。

## 文种选择

按“行文目的 → 发文与受文机关关系 → 受众范围”判断，不按单个关键词判断。

| 文种 | 适用意图 |
|-|-|
| 决议 | 会议讨论通过重大决策 |
| 决定 | 对重要事项作出决策部署、奖惩或变更 / 撤销决定 |
| 命令（令） | 公布法规规章、施行重大强制措施、授予衔级或嘉奖 |
| 公报 | 权威公布重要决定或重大事项 |
| 公告 | 向国内外宣布重要或法定事项 |
| 通告 | 在一定范围公布应遵守或周知的事项 |
| 意见 | 对重要问题提出见解和处理办法 |
| 通知 | 要求下级 / 有关单位执行或周知，批转、转发公文 |
| 通报 | 表彰、批评、传达重要精神或告知重要情况 |
| 报告 | 向上级汇报工作、反映情况或答复询问，不请求决定 |
| 请示 | 向上级请求指示或批准；一文一事，原则上只主送一个上级机关 |
| 批复 | 答复下级机关请示，必须有对应来文 |
| 议案 | 政府依法向同级人大或其常委会提请审议 |
| 函 | 不相隶属机关间商洽、询答、请求批准或答复审批 |
| 纪要 | 记载正式会议主要情况和议定事项，不写逐字过程 |

优先消歧：汇报且不求决定用报告，求上级决定用请示，不相隶属机关商洽用函；面向明确单位执行用通知，面向一定范围不特定对象遵守用通告，向国内外宣布重要 / 法定事项用公告，传达情况或评价用通报。

## 行文与事实

- 按隶属关系、职权和授权行文；一般不越级，特殊越级时同时抄送被越过机关。
- 上行文原则上主送一个上级机关，不抄送下级；报告不得夹带请示。除直接交办外，不主送上级负责人个人。
- 一份主文保持一个行文方向和授权状态；同一事项若既需向上请求批准又需向下要求执行，应拆分文稿或待批准后另行制发，附件不得偷渡尚未授权的执行要求。
- 下行要求不得超出发文机关权限；涉及其他地区 / 部门职权时先协商。联合行文仅限必要且主体关系适当的情形。
- 只把已确认的决定写成指令。措施按需写明主体、动作、对象、期限、标准和反馈去向；对不相隶属机关使用`商请`、`请予`、`函复`等匹配关系的措辞。
- 缺少授权、关键依据、核心事实、适用范围或审批决定时不得发布；不得猜测文号、签发人、密级或紧急程度。

## 内容结构

- 标题一般使用“发文机关 + 事由 + 文种”，内含法规、规章或被印发文件名称时使用书名号。
- 主送机关使用全称、规范简称或同类机关统称。附件说明与附件顺序、名称逐字一致；多个附件用阿拉伯数字编号，名称末尾不加标点。

| 文种 | 常用结构 |
|-|-|
| 通知 | 缘由 / 依据 → 事项 → 对象 / 时间 → 已确认要求 |
| 请示 | 缘由 / 依据 → 单一请示事项与倾向意见 → `妥否，请批示` |
| 批复 | 准确引用来文 → 明确意见 → 执行要求 → `此复` |
| 函 | 事项 / 依据 → 商请或答复 → `请予函复` / `特此函复` |
| 报告 | 情况 → 事实 / 成效 → 问题 → 后续安排 → `特此报告` |
| 纪要 | 会议基本信息 → 主要情况 → 议定事项 / 责任 / 时限 |

## 文号、引用与序号

- 普通发文字号采用“机关代字 + 完整年份 + 顺序号”，如 `×政发〔2026〕8号`；年份用六角括号，顺序号不加“第”、不编虚位。命令（令）的令号可用 `第×号`。
- 首次引用其他公文时写完整标题和文号：`《××机关关于印发〈××办法〉的通知》（×发〔2026〕8号）`。不只写文号，不用论文式参考文献编号。
- 文件、法律法规名称使用书名号；直接引文使用中文双引号，内层用单引号。引文须核对原文、效力、制定机关和适用范围；无法核实则标记 `[引文待核]`。
- 正文层级依次使用 `一、`、`（一）`、`1.`、`（1）`，不得写成 `1、`、`（一）、`，不得跳级；超过四级时重组内容。
- 成文日期写为 `2026年7月13日`，月日不补零。标点和数字按 GB/T 15834、GB/T 15835 使用；全称及规范简称前后一致。

# Genre Contract: PRD / 产品需求 (`workplace.prd`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 具体、行为化、术语和状态一致；不用固定大模板制造完整感 |
| 视觉约束 | 在有明确内容作用时用场景、状态流、表格、图示等组件降低理解与验收成本，但不得替代需求、证据或验收 |
| 内容逻辑 | 方向已定后按“用户问题 / 证据 → 目标 / 结果 → 范围 / 非目标 → 场景 → 行为需求 / 验收 → 异常 / 边界 → 适用质量约束 → 依赖 / 开放问题”推进 |
| 事实 / 边界 | 用户需要、指标、研究、阈值、可行性、owner、状态和排期须可追溯；需求描述可观察结果，acceptance criteria 验结果；安全、隐私、无障碍等仅按实际风险和标准纳入 |
| 错误 | 功能清单无用户问题、Proposal 论证吞没需求、范围 / 非目标缺失、需求暗藏实现、验收不可测、正常路径无异常、伪造研究 / 阈值 / 批准或机械填质量模板，任一出现即失败 |

## 适用与消歧

用于方向与投入原则已定后，让产品、设计、研发和测试就用户问题、范围、可观察行为与完成标准形成共识。是否立项 / 选择方向 / 批资源走 `proposal.md`；架构、接口和实现取舍走 `technical-doc.md`；已批准重复操作走 `sop-tutorial.md`。“需求 / 功能”单词本身不触发。

## 证据与需求写法

- 明确目标用户、任务情境、问题及研究 / 行为 / 支持证据；内部偏好和预设功能不冒充用户需要。
- 产品目标连接可观测结果，指标标口径、来源和时间窗。未知目标值用`[目标值待产品 / 数据确认]`并给确认 owner / 时点，不编使用量或阈值。
- 关键需求写成 actor + trigger / precondition + observable outcome + failure / edge；术语和状态一致。用户故事格式只是工具，不是章节配额。
- 每个质量约束给可验证门槛或明确待确认项；不适用时不填模板。需求、验收 / 测试和来源保持追踪。

## 结构与高质量写法

先定范围、非目标、优先级、依赖、假设和开放问题，防止 scope creep；再按关键场景写正常、异常和边界行为。把大而不可测的需求拆到可验收粒度，不用“体验更好 / 性能高”等形容词。没有用户证据时收窄为假设和研究计划；关键合规 / 安全门缺失时 `blocked`，开放问题不得藏在脚注。

# Genre Contract: Proposal / 方案提案 (`workplace.proposal`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 结论前置、具体、可审议，主动呈现代价、反例与不确定性，不用宏大背景或伪精确制造可批准感 |
| 内容逻辑 | 明确 decision / 决策者 / 时点，再按“改变理由与不行动基准 → 目标 → 真实选项同口径比较 → 推荐 → 资源 / 交付 → 风险 / 未知 → 决策入口”推进 |
| 事实 / 边界 | 区分事实、估算、假设和未知；收益、成本、资源、用户证据、审批和排期须可追溯；进入执行决策才写治理 / 退出条件，未批准不得写成既有承诺 |
| 错误 | 无决策者 / ask、无不行动基准、预设单一答案、选项口径不同、成本风险后置、未批先承诺、编造收益 / 审批或与 PRD 混写，任一出现即失败 |

## 适用与消歧

用于请求具名决策者批准、驳回或选择方向、预算、资源、试点或执行承诺。方向已定并定义产品行为 / 验收走 `prd.md`；短决策封面走 `memo-brief.md`；已批准安排的发布走 `formal-doc.md`。“方案”单词本身不触发本体裁。

## 子类型与证据

可用于概念 / 方向、投资 / 预算、资源申请、变更、试点 / 实验和执行承诺提案；深度随阶段、金额、风险和不可逆性裁剪。必须给 case for change、目标 / 成功标准、不行动或最小变化基准，以及足以判断的成本、收益、依赖、风险和敏感因素。

存在真实选择时纳入可行替代并以相同范围、时间和评价标准比较；没有真实替代时说明约束如何收敛，不能造假选项。不可量化影响可定性，但须说明原因及其决策影响。

## 结构与高质量写法

先把选择题写对，再论证推荐；显式记录被放弃选项和推荐代价。数字不足时使用范围、依据和验证计划，不补精确点估。进入执行决策时按需补 owner、里程碑、治理、衡量、退出 / 复盘；缺决策权、关键成本或安全合规依据时收窄为探索稿，仍要求批准则 `blocked`。

# Genre Contract: Research Report / 调研报告 (`report.research_report`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 证据驱动、校准、术语一致；摘要独立可读，语气强度不得超过证据强度 |
| 内容逻辑 | 先确定研究问题与研究类型，再交付当前答案、证据强度和可推广边界；按问题或主题组织发现，解释、建议和验证计划必须回链发现 |
| 事实 / 边界 | 区分原始事实或参与者陈述、分析推断、假设和建议；方法披露足以评估偏差；适用时确认委托、利益、同意、匿名或保密、敏感数据用途；研究材料须确认使用权、去标识、来源与说明，复杂视觉附文字等价信息；未知不补造 |
| 错误 | 无明确问题；方法黑箱；资料摘要冒充发现；样本外推；醒目个案冒充模式；事实、解释和建议混写；相关写成因果；合规状态、授权或行业共识靠猜 |

## 适用与消歧

以明确研究问题、研究设计或材料、发现和限制为主要交付。`调研`、`研究过`、`访谈`、`问卷`单独只用于召回；只解读既定指标走 [`data-report.md`](data-report.md)，比较特定战略或资源选项走 [`business-analysis.md`](business-analysis.md)，方法并非判断重点的问题框架综合走 [`white-paper.md`](white-paper.md)。

## 子类型

- **定量 / 定性 / 混合研究**：根据问题选择总体、抽样或招募、工具、采集和分析方法；不用一种方法的规范冒充全部研究标准。
- **用户研究 / 项目或政策评估**：说明场景、参与者、干预或对象、成功标准、观察窗口和用途。
- **证据综合**：只有检索范围、纳排和综合方法明确时才作为研究发现；普通资料汇总不得升级为系统结论。

## 证据与方法

- 明确对象、用途、非目标和适用情境；按需披露委托 / 执行方、总体与纳排、抽样 / 招募、样本量、工具 / 题项、采集方式 / 语言 / 时点、响应 / 脱落、加权、编码 / 分析和质量控制。
- 写明偏差、缺失、反例、负结果、替代解释及其可能方向；透明报告不等于设计无偏，也不证明结论可复现。
- 人员或敏感研究在适用规则下确认知情同意、撤回与伤害风险、匿名 / 保密、访问和数据用途；未获授权不公开可识别材料、原始数据或代码。
- 引文只说明有出处的体验或机制，不把单个引文写成频率；结论只推广到设计和样本支持的人群、时间与环境。
- 无原始材料只能产出研究范围或计划，不能生成 findings；方法或样本缺失时用 `[抽样方法待核]`、`[采集时点待核]` 并收窄为探索性观察。关键伦理、授权或方法缺口会改变结论时标记 `blocked`。

## 结构与高质量写法

独立答案、证据强度与关键限制 → 问题 / 范围 / 既有知识 → 方法 / 样本 → 按问题或主题组织的发现 → 解释、反例与替代解释 → 有边界的建议 / 验证 → 局限、来源与必要附录。摘要覆盖目的、方法、发现、含义和限制；正文以“主张 → 证据 → 限定”推进，不按作业时间线罗列过程，不用组件数量代替研究质量。

# Genre Contract: Retrospective / 复盘 (`workplace.retrospective`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 坦诚、无责备、因果克制，围绕证据和下一轮改变，不用“加强沟通 / 持续关注”代替可验证实验 |
| 内容逻辑 | 界定已结束周期 / 事件，再按“目标 / 证据 → 预期与实际 → 聚类观察 → 洞见 / 待验证因果 → 保留项 → 少量改进实验 → 复查”推进 |
| 事实 / 边界 | 事实 / 观察、解释 / 假设、洞见和行动分层；结论回链事件、指标或交付物；根因仅在证据充分时声明，否则写可证伪假设；保护必要隐私 |
| 错误 | 周报换标题、成绩陈列 / 情绪宣泄、个人归罪、单一根因臆测、行动无 owner / 验证 / 跟踪、不回看上轮或把模板便签当结论，任一出现即失败 |

## 适用与消歧

用于回看明确迭代、阶段、项目或事件，形成可复用学习并改变下一轮做法。当前状态与升级需求走 `weekly-report.md`；仍在未知中止损、取证、恢复或调查生产事故走 `technical-doc.md`。生产事故可由 Technical 主文承载影响 / 时间线 / 根因 / 恢复，再附本体裁的团队学习层。

## 证据与因果

- 开头界定范围、时间、目标 / 原计划、参与视角和已知证据；不得补造指标、时间线、共识、原因或行动。
- 同时识别应保留与应改变的条件，按影响聚类；以系统、流程、工具、接口和当时条件为对象，不把惩罚叙事冒充根因。
- 个人工作心得 / 成长反思以一个真实事件或转折为证据，呈现“当时判断 → 反证 / 后果 → 新认识 → 下一次可观察行为”；不代写材料没有提供的情绪、动机、心路或成长。
- 证据不足时写“促成条件 / 假设 + 验证方式”，不能用确定语气。缺基线用`[基线待补]`，涉及安全 / 法务而证据不足时转 Technical 并 `blocked`。

## 结构与高质量写法

便签、4Ls、Start / Stop / Continue 只是收集手段，成稿须综合为主题和判断。改进实验写动作、owner、目标时间、验证条件和跟踪位置，优先改变系统而不是要求人“更小心”；按需补上轮行动效果和下轮复查点。项目收尾可增加成本、范围、相关方和知识移交，但不机械扩章。

# Genre Contract: Consumer / 消费决策内容 (`router.consumer`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 具体、可信、可亲近，体验感服务于选择，不用热情语气替代测试、价格和适用条件 |
| 内容逻辑 | 围绕具体消费场景，用“需求 / 使用条件 → 评价标准 → 体验或测试证据 → 权衡 → 适合谁 / 不适合谁”推进；合集和比较须共享标准，不按品牌逐段堆卖点 |
| 事实 / 边界 | 只声称真实体验或有方法支撑的测试；披露赠品、佣金、赞助和其他重要关系；标明版本、时间、价格口径及限制；用户 / 专家引语、图片和前后对比须有授权、来源、语境与真实性依据，非文字证据须有文字等价信息；遵守目标法域和平台当期消费者、广告与高风险品类规则，关键利益关系、核心功效、安全条件或报价条款缺失时 blocked |
| 错误 | 编造使用经历、未披露商业关系、无方法的评分 / 排名、把主观偏好写成客观最佳、隐藏不适用人群或总成本、用极端个案概括功效、过期信息仍当现状，任一出现即失败 |

## 适用与消歧

用于帮助读者购买、比较、避坑或判断某种生活方式是否适合自己。仅出现小红书、微信等平台名不触发；明确要求最终交付小红书笔记或微信公众号文章时走 `route_platform`，再选择对应 leaf，消费选择任务作为该 leaf contract 的硬约束，不再并读 Consumer。以公共事件核实为主走 Media，以价值判断为主走 Opinion，以品牌拥有的转化内容走 Marketing。

“测评”必须继续区分独立比较、真实个人体验和品牌演示：前两者可走本合同，品牌控制结论或行动入口时走 Marketing，并保留显著披露。

## 子类型

| 子类型 | 读者任务与推进 |
|-|-|
| 单品体验 / 好物分享 | 判断某物在真实场景是否值得；使用背景 → 观察 → 优缺点 → 适用人群 |
| 对比测评 / 排名 | 在同一任务下选择；方法与样本 → 共同标准 → 结果 → 权衡与不确定性 |
| 合集 / 清单 | 快速缩小候选范围；选择门槛 → 分组理由 → 各项差异 → 最终选择路径 |
| 探店 / 服务体验 | 判断是否到访或购买服务；时间地点 → 实际流程 / 价格 → 体验证据 → 限制 |
| 生活方式内容 | 判断实践成本与可复制性；目标 → 做法 → 真实投入 / 结果 → 适用边界 |

## 证据、披露与合规

- 第一人称体验交代使用时长、频率、版本和条件；未亲测就明确资料来源，不伪装成亲历。比较结论说明样本、标准、测量方法及未覆盖变量。
- 把“真实 / 有效”“适合当前读者”“值得当前价格”分开判断。强参数品只保留会改变选择的指标，并解释版本口径和决策影响；使用评分 / 排名时公开标准、权重、主观边界和反转条件，安全或资格等一票否决项不得被平均分稀释。
- 商业关系和激励在读者接触推荐时清楚出现，不能藏在模糊标签或文末。披露、重大限制和安全警示须就近可见，不能只藏在链接或视觉装饰中。
- 健康、安全、金融、未成年人等高风险内容只写证据支持且适用法域允许的范围；不能核实的功效或个体化建议删除。规则冲突时按交付地区、渠道和发布时间核验，不把单一国家指南写成全球义务。

## 结构与高质量写法

先告诉读者评判基准，再给结论，才能让“推荐”可复核。优点与代价写在同一决策语境内，价格同时说明时间、地区、规格和附加成本。结尾给条件化选择，而不是人人适用的口号；关键参数待补时用具体占位并暂停对应结论，不能靠语气填空。

# Genre Contract: Creative / 叙事创作 (`router.creative`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 语言、节奏和视角服务指定叙事体验，表达自由不替代人物动机、因果和场景可读性 |
| 内容逻辑 | 本合同只覆盖叙事创作；先确认体验、篇幅、视角和约束，用“人物欲望 → 阻力 → 选择 → 代价 → 变化”形成场景因果；剧本和互动叙事分别服从可演行动与有后果分支 |
| 事实 / 边界 | 用户授权的虚构可创造，但真实背景、引用、既有作品正史和人物身份不得伪造；图片、题记、原作片段和创作参考须遵守来源与使用权限，非文字参考及互动分支图须附文字等价的关系、路径和状态说明；区分明确设定、合理创作补白和待确认约束；核心世界观 / 权利边界冲突且无法安全收窄时 blocked |
| 错误 | 只堆设定不发生选择、人物为推进情节突然失去动机、冲突靠偶然或外力无代价解决、视角 / 时态无意漂移、剧本写成解释性小说、互动分支无状态差异、把诗歌静默纳入交付，任一出现即失败 |

## 适用与消歧

仅用于网文、短篇故事、同人叙事、互动小说、剧本和故事大纲等以事件、人物选择和变化为核心的创作。诗歌、歌词、纯抒情散文不在本合同范围；收到这类请求时先确认目标或使用相应专用规则，不因“Creative”一级名称而静默扩写。

以论点和证据表达判断走 Opinion；以真实个人经历建立专业信誉走 Personal Brand。世界观说明若目标只是知识解释，不因带角色名就成为故事。

## 子类型

| 子类型 | 读者任务与推进 |
|-|-|
| 短篇 / 网文 | 获得连续叙事体验；触发变化 → 升级阻力 → 关键选择 → 后果 / 回响 |
| 同人叙事 | 在约定正史与角色核心上体验新情境；明确时间点 / 偏离点 → 角色选择 → 新后果 |
| 剧本 / 短剧 / 叙事短视频 | 看见可拍、可演的行动与冲突；媒介 / 时长 / 制作约束 → 场景目标 → 视觉、行动、声音 / 对话 → 转折 → 场景状态变化 |
| 互动小说 | 作出有信息依据且有后果的选择；状态 → 选择 → 反馈 → 状态改变 → 后续分支 |
| 故事大纲 | 判断故事能否成立并继续创作；前提 → 人物弧 → 节点因果 → 高潮选择 → 结局变化 |

## 设定与真实性

- 先锁定用户给定的人物、关系、禁区、正史时间点和期望体验；未指定的创作空间可以补白，但不得覆盖明确约束。关键歧义有多个会显著改变成品的方向时先询问。
- 使用真实地点、历史、科学或文化材料时核验会影响情节的事实；有意架空应让读者能辨认其虚构约定。同人创作不把自设冒充正史，也不虚构原作引语。
- 真实人物、未公开经历、受保护素材和委托作品按授权边界处理；不能确认可用性时改为原创替代或保持 blocked。

## 结构与高质量写法

每个场景都让人物为目标采取行动，并在离场时改变信息、关系、资源或风险。细节同时承担感官、人物或伏笔功能，背景通过当前冲突释放，不集中讲解。对话要改变局面而非重复旁白；剧本动作、声音和调度须在声明的演员、场地、道具与媒介条件下可实现，不用固定“前三秒 / 每分钟一反转”公式代替因果。结局兑现前文建立的选择与代价。大纲可显式呈现结构，成稿则把结构转化为可体验的场景。

# Genre Contract: Knowledge / 知识与教程 (`router.knowledge`)

## 体裁规则表（硬约束）

| 规则项 | 规则                                                                                                                                  |
|-|--|
| 写作风格 | 具体、可操作、按读者水平解释；科普可生动、有好奇心，但不得牺牲准确性或编造戏剧性                                                                                     |
| 内容逻辑 | 先选择唯一主模式和读者起点，再承诺一个理解、学习、一次操作、检索或选择结果；第一屏给适用对象、目标和关键前置，概念、步骤、练习 / 验证、反馈与例外按需渐进展开                                                    |
| 事实 / 边界 | 事实、版本、命令、UI 路径和链接须核验；示例与规则分开；截图 / 案例不得泄露敏感信息；已知自助路径可写，组织受控重复作业走 SOP，设计、精确技术契约或未知诊断走 Technical                                       |
| 错误 | 不声明读者起点；教程变理论课；学习计划无基线 / 完成标准 / 调整规则；只有原则无步骤 / 例子；步骤无结果或验证；版本、权限、环境缺失；编造命令、UI 或链接；FAQ 脱离真实问题；资源合集无标准 / 注释 / 维护；视觉成为唯一信息；把未知排障写成确定答案 |

## 适用与消歧

适用自主理解、学习 / 备考规划、一次已知任务或检索复用。`科普`、`教程`、`指南`、`攻略`、`学习计划`、`FAQ`、`知识库`、`资源合集`只用于召回；“知识库”是容器或渠道，不决定文章体裁。组织要求多人按批准版本重复执行并留痕走 [`sop-tutorial.md`](sop-tutorial.md)；未来设计、API 精确契约、生产状态变更或未知根因走 [`technical-doc.md`](technical-doc.md)；研究或数据形成新洞察走 Report。

## 主模式

| 模式 / 读者任务 | 结构推进 |
|-|-|
| Explanation / 科普：建立正确心智模型 | 现象 / 误区 → 概念模型 → 机制与证据 → 例子 → 争议、限制与适用边界 |
| Tutorial：通过受引导练习获得技能 | 学习目标 → 起点 / 环境 → 安全练习 → checkpoint → 复盘与下一步 |
| Learning plan：在现实约束下持续提高 | 基线诊断 → 可观察的阶段目标 → 练习 / 资料 / 时间 → 完成标准与反馈 → 调整规则 |
| How-to：完成一个已知目标 | 目标 → 前置 → 最短有效步骤与可观察结果 → 变体 / 已知错误 → 完成验证 |
| FAQ / known troubleshooting：快速找到已验证答案 | 按真实问题或症状分组 → 直接答案 → 必要条件 / 操作 → 相关内容；需要新假设或根因调查时转 Technical |
| Resource guide：按标准选择资源 | 使用场景 / 筛选标准 → 分类 → 每项适配、代价与访问条件 → 维护信息 |
| Reference / KB article：检索并复用事实或解法 | 上下文 / 适用版本 → 事实或 issue-resolution → 限制 / 相关项 → 时效性强时标 owner / last verified |

## 事实、步骤与维护

- 明确受众的已有知识、范围 / 非范围、版本、环境、权限与风险；术语在首次需要时解释，不先灌输完整理论。
- 学习计划按阶段 / 能力、可用时间、既有任务和可得资料控制强度；目标拆成可观察表现，每阶段合写练习、完成标准、反馈和调整条件。会显著改变安排的缺口先问或条件化，不补造基础 / 时间。
- 顺序任务一项写一个清楚动作，紧邻给可观察结果；命令、输入、输出和成功验证须能在声明环境中复现，危险或不可逆警告必须在动作前。
- FAQ 只收真实用户问题或检索需求；否则按用户任务重组。资源指南先写选择标准，再给有描述的精选链接，不用外链代替核心上下文。
- 时效性内容标适用版本 / 时间并说明维护边界；复杂视觉须有可传达同等信息的正文，图片、案例和代码不得成为无解释的唯一依据。
- 版本或权限不明时用 `[适用版本待核]`、`[所需权限待确认]` 并只写不受影响部分；未验证命令或链接不进入发布稿。缺口可能造成损失、安全风险或关键分叉时标记 `blocked`。

## 高质量写法

第一屏让读者知道能理解、学会、完成或找到什么；用读者语言、具体动词和可验证结果推进，每节只增加必要的新理解或动作。先给最短可行路径，再在需要处补原理、变体和进一步阅读；示例只服务迁移，不扩张为用户未要求的全套内容，也不用丰富组件掩盖解释不足。

# Genre Contract: Marketing / 营销与公关 (`router.marketing`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 清楚、有吸引力且可行动，表达强度不得超过承诺、证据和授权，紧迫感不得制造误导 |
| 内容逻辑 | 先锁定受众、漏斗阶段和唯一主要读者结果；转化内容用“场景 / 问题 → 有边界的价值主张 → 证据 → 关键条件 / 异议 → 一个 CTA”推进，公关稿按已授权事实、相关方影响、组织回应和后续更新推进 |
| 事实 / 边界 | 所有客观、比较、功效和稀缺性主张发布前有相称证据；价格、资格、期限和限制就近可见；广告身份与商业关系按目标法域 / 平台规则披露；评价、案例、引语、图片和活动素材须真实、可核且获授权，非文字证据须有文字等价信息；核心主张证据、适用法域、发布授权、关键交易条件或任务要求的行动入口缺失时 blocked |
| 错误 | 无证据的“最佳 / 保证 / 第一”、隐藏限制或自动续费、伪造倒计时 / 库存 / 评价、把广告伪装成独立报道、未经授权承诺赔付或责任、转化内容多个 CTA 争抢、用复杂 block 掩盖价值缺口，任一出现即失败 |

## 适用与消歧

用于组织拥有或授权、目标是认知、转化、留存或公共关系管理的内容。由新闻机构独立选题、核实和报道的内容走 Media；组织自有新闻稿、媒体通稿、品牌声明和回应口径走 Marketing，即使采用新闻结构也不变成独立报道。

个人真实体验用于帮助消费选择时走 Consumer；明确要求最终交付小红书笔记或微信公众号文章时走 `route_platform`，再选择对应 leaf，营销目标、商业关系和交易条件作为该 leaf contract 的硬约束，不再并读 Marketing。出现“新闻稿、软文、活动文案”只作召回信号，仍须确认发布主体、受众、行动和商业关系。

内部营销策划、增长方案或活动执行计划不因“营销”进入本合同：比较打法走 Business Analysis，请求预算 / 资源 / 战役批准走 Proposal，已定打法的协同落地走 Execution Plan；只有最终面向受众的传播、招募或转化成稿走 Marketing。

## 子类型

| 子类型 | 读者任务与推进 |
|-|-|
| 广告 / 短文案 | 迅速判断是否值得行动；受众场景 → 单一利益 → 可信理由 → 条件 → CTA |
| 详情页 / 落地页 | 完成比较与转化；价值主张 → 关键能力 → 证据 → 方案 / 条款 → 异议 → CTA |
| 活动 / 私域话术 | 判断是否参与并知道下一步；对象 → 收益 → 时间地点 / 门槛 → 风险限制 → 行动 |
| 新闻稿 / 媒体通稿 | 获取组织已授权消息；可发布事实 → 为什么重要 → 引语 / 背景 → 联系与更新安排 |
| 声明 / 危机回应 | 理解已知事实和组织行动；事件范围 → 已确认影响 → 当前措施 → 未知项 → 下次更新时间 |

## 证据、授权与合规

- 建立“主张—证据”对应：定量效果说明口径、样本和时间，比较主张保证对象与标准可比；图片、引语、评价和案例保留来源、必要语境及授权记录。
- 披露和限制应让普通受众在作决定前看见并理解，不能由链接、模糊缩写或弱提示代替。规则随法域、媒介、品类和时间变化，交付前核验当期法律、监管与平台要求。
- 公关内容只写已获授权的事实和承诺；事故原因、责任、补偿、调查结论未核定时明确 unknown。关键批准或法律审阅未完成，不生成可直接外发版本。

## 结构与高质量写法

价值主张具体到受众、场景和结果，证据紧跟对应主张。文案须锚定品牌独有资产、产品细节或品类语境；换成竞品名仍成立就返工。多版本应改变受众状态、主张、证据或场景并说明选择条件，不做同义改写。

删除不改变理解或行动的品牌空话，不把真实痛点升级为羞耻、身份不足或恐惧操控。有转化目标时，次级入口均服务同一主要行动；优惠资格和截止时间采用可比较字段，待补价格、库存或链接用语义化占位，并让受影响结论保持 blocked。

# Genre Contract: Media / 资讯媒体 (`router.media`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 准确、中立、紧凑，信息密度服从读者快速理解，不用戏剧化措辞替代事实强度 |
| 内容逻辑 | 先确定快讯 / 报道、解释、人物特写或访谈的读者任务；关键信息优先，随后给证据、必要背景、相关方视角和仍未知事项，段落按重要性、因果或时间关系推进 |
| 事实 / 边界 | 区分已核事实、来源说法、推断和 unknown；准确优先于抢发，关键主张可追溯，负面涉及方获得合理回应机会；引语须忠实可核，图片和原始材料须有使用权限、来源、语境说明及文字等价信息，更正、披露和关键缺口须直接可见；核心事实、来源真实性、发布权限缺失，或严重负面指控尚未提供回应机会时保持草稿并 blocked |
| 错误 | 把组织自有通稿伪装成独立报道、标题超出证据、单一匿名来源承载重大指控、引语失真、事实与评论混写、遗漏重大反方或不确定性、图片无权利 / 来源 / 文字等价信息，任一出现即失败 |

## 适用与消歧

本合同用于以独立采集、核实和公共理解为职责的新闻内容。请求出现“新闻稿、媒体稿、报道”只作召回信号：编辑方能独立核实、选择角度并承担报道判断时走 Media；由组织拥有、批准并面向媒体或公众发布的新闻稿、品牌声明和公关口径走 Marketing。

以立场说服为主走 Opinion；以购买决策和亲身体验为主走 Consumer；内部事实简报不因写得像新闻而改变读者任务。渠道名、标题风格或“像媒体一样写”均不能单独触发；明确要求最终交付小红书笔记或微信公众号文章时走 `route_platform`，再选择对应 leaf，资讯核实边界作为该 leaf contract 的硬约束。

## 子类型

| 子类型 | 读者任务与推进 |
|-|-|
| 快讯 / 硬新闻 | 尽快知道发生了什么及其可信程度；核心事实 → 来源与范围 → 必要背景 → 下一确认点 |
| 解释报道 | 理解为什么发生、如何运作及争议在哪里；问题 → 机制 / 时间线 → 多方证据 → 已知边界 |
| 人物 / 特写 | 通过可核场景和经历理解人物或议题；场景 → 关键变化 → 证据与他者视角 → 公共意义 |
| 访谈 / 问答 | 准确获取受访者观点及上下文；交代身份与场景，忠实编辑问答，不补造连接语或立场 |

## 证据与真实性

- 为可能引发争议的事实保留可追溯材料，记录来源身份、接近事实的方式、核实状态和使用限制；匿名只在有公共价值且无法安全具名时采用，并说明读者判断所需的来源范围。
- 引语逐字可核；压缩、翻译和转述不得改变含义。无法确认的数字、时间、身份或因果就近标明 unknown，不用“据悉”“有消息称”遮蔽来源质量。
- 开盒、网暴、羞辱、未成年人或其他可能放大伤害的事件只保留理解事实、责任和传播机制所需的最少信息；不为证明热点而复刻身份线索、攻击性内容或未核传言。
- 更正要说明改了什么；新证据改变核心判断时更新标题和结论。发布前无法核实的核心主张不得靠占位符放行。

## 结构与高质量写法

标题和导语只承诺正文已证明的内容。每段承担一个信息动作，并在首次出现时交代人物、机构、时间和口径；背景只保留改变理解的部分。多方说法按证据权重而非形式上的各打一板排列，不把可验证事实写成“双方观点”，也不把尚无结论写成确定因果。

# Genre Contract: Opinion / 观点评论 (`router.opinion`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 立场鲜明但措辞精确、公平，论证密度高于情绪密度，锋利不等于侮辱或夸张 |
| 内容逻辑 | 明确可争辩的中心判断及其重要性，用理由和证据推进；对有实质争议的主张呈现最强相关反论并回应，结论说明判断边界或行动含义 |
| 事实 / 边界 | 区分事实、推断、价值判断、预测和个人经验；事实可追溯，证据强度匹配主张强度，不把相关性写成因果或把个案外推为普遍规律；引语、图片和作品片段须有可核来源、必要语境与使用权限，非文字证据须有文字等价信息，重要利益关系须显著披露；关键事实缺失时收窄主张，无法成立则 blocked |
| 错误 | 只有态度没有论点、稻草人反驳、选择性证据、人格攻击、标题先定罪、把经验冒充统计、隐藏重大反例或利益关系、结论超出论证，任一出现即失败 |

## 适用与消歧

用于帮助读者评估一个判断、立场或解释框架。事件复述和独立核实走 Media；围绕购买选择的测评走 Consumer；组织为行动或转化发声走 Marketing。出现“评论、专栏、观点”只是召回词，正文必须有可辨认的判断和论证任务。

文化评论关注作品、现象的意义和判断；若主要提供剧情复述或故事体验，不走本合同。个人经历可以作为观察入口，但若目标是展示经历与能力，走 Personal Brand。

## 子类型

| 子类型 | 读者任务与推进 |
|-|-|
| 时评 / 公共议题评论 | 判断事件意味着什么；争点 → 判断 → 证据与机制 → 反论 → 后果 / 建议 |
| 商业 / 行业评论 | 评估策略、趋势或制度；基线 → 驱动因素 → 证据 → 替代解释 → 适用条件 |
| 文化评论 | 理解作品或现象的价值；分析对象 → 解释框架 → 细读证据 → 限度 → 判断 |
| 专栏 / 随笔 | 从观察或经验形成可迁移洞见；具体场景 → 反思 → 关联 → 有边界的结论 |

## 证据与论证

- 开头尽早写出“我主张什么”和“为什么现在值得讨论”，避免用大段背景延迟论点。每个理由回答一个潜在质疑，并由事实、例子、机制或可靠来源支持。
- 反论选择真正能动摇中心判断的版本，不挑最弱说法；回应可以承认条件、修改范围或解释为何仍不改变结论。观点平衡不是机械分配篇幅。
- 公共争议先拆清事实真伪、规则 / 权利、价值取舍、责任归属和 unknown，再分别判断；行动建议须对应具体主体、权限 / 义务、可用杠杆与代价，不用“多方协同”抹平责任边界。
- 预测写明前提和时间范围；价值判断说明采用的标准。涉及他人动机、违法或伤害的判断不得凭语气升级为事实。

## 结构与高质量写法

段落之间形成“主张 → 理由 → 证据 → 推论”的可追链条，过渡词只标真实关系。文化评论选择一个能统摄正文的主分析轴，把情节、语言、镜头、声音、表演或结构写成“形式选择 → 产生效果 → 支持何种解释 / 评价”的证据链；比较或综述可有多个对象，但不能退化成剧情复述或维度清单，也不把效果直接冒充创作者意图。

结尾不复述全文，而是给出经反论校准后的判断、仍然未知的部分，或读者下一步应重新考虑什么。随笔可弱化显式论证标记，但不能牺牲观察与结论之间的可理解联系。

# Genre Contract: Personal Brand / 个人品牌 (`router.personal_brand`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 可信、具体、有辨识度，声音服从目标读者和真实经历，不用自我评价替代成果证据 |
| 内容逻辑 | 从目标读者和目标机会出发，用“身份 / 价值定位 → 相关经历 → 可验证贡献 → 做事方式 → 下一步意图”组织；每项经历说明情境、本人动作、结果及与目标的关系 |
| 事实 / 边界 | 职位、时间、职责、学历、技能、作品和指标须真实可核，个人贡献与团队成果分开；尊重保密、个人信息、雇主和作品权利，作品、图片和推荐语须确认归属、使用权限与必要语境，非文字证据须有文字等价信息；关键身份、时间、归属或公开权限缺失时用具体占位，无法安全表述则 blocked |
| 错误 | 夸大头衔 / 技能 / 指标、把团队成果全归个人、关键词堆砌、伪造推荐语或客户、泄露敏感信息、作品无归属 / 权限、同一经历前后矛盾、渠道语气改变事实，任一出现即失败 |

## 适用与消歧

用于让招聘方、合作方、客户或专业社群判断“这个人是谁、做过什么、能带来什么”。仅出现平台名称不触发；明确要求最终交付 Email、小红书笔记或微信公众号文章时走 `route_platform`，再选择对应 leaf，个人身份、经历和信誉目标作为该 leaf contract 的硬约束，不再并读 Personal Brand。

以项目经验得失来改进下一轮走 Retrospective；以购买体验帮助他人选择走 Consumer；以组织身份转化客户走 Marketing。出现“介绍、主页、复盘”不能单独触发，须确认目标是个人能力和信誉呈现。

## 子类型

| 子类型 | 读者任务与推进 |
|-|-|
| 简历 / CV | 快速判断岗位匹配；摘要 → 相关经历与成果 → 技能 / 教育 → 必要补充 |
| 求职信 / 自我介绍 / 简介 | 理解动机与差异化价值；目标 → 相关证据 → 工作方式 → 明确下一步 |
| 个人主页 | 建立清晰定位并找到入口；一句定位 → 代表证据 → 领域 / 服务 → 联系或作品 |
| 作品集 / 案例集 | 判断能力如何形成结果；问题 → 约束与本人角色 → 过程决策 → 结果与反思 |
| 个人成长回顾 | 理解身份与能力变化；起点 → 关键选择 → 证据 → 学到什么 → 下一方向 |

## 证据与真实性

- 成果优先写可核结果及其口径，不能量化时写可观察变化、交付物或他人采用情况，不编造数字。明确“负责、协作、支持、批准”等角色差异。
- 时间线、组织名、客户名、作品链接和推荐语在公开前确认准确与授权；需匿名时保留问题、本人动作和结果的判断价值，不留下可反推的敏感细节。
- 技能由近期作品、职责范围或实际使用场景支撑；自我定位可以有主张，但不能使用未获认可的资质、奖项或身份。

## 结构与高质量写法

先筛选与目标读者最相关的经历，不把完整人生经历当作专业证明。经历条目以动作和影响开头，背景只写理解贡献所需的约束；案例说明权衡和本人判断，比工具清单更能证明能力。CTA 具体到希望发生的下一步，并只提供获授权的联系方式。

# Genre Router: Platform / 平台发布稿 (`route_platform`)

仅当最终交付物是小红书笔记、微信公众号文章或邮件成稿时进入本 router；按目标平台选择且只读取一个 leaf。仅把平台作为研究对象、信息来源或业务渠道时不触发；多平台成稿分别路由和生成。

| 关键词             | Leaf                               |
|-----------------|------------------------------------|
| XHS、小红书         | [`xiaohongshu.md`](xiaohongshu.md) |
| 微信、wechat       | [`wechat.md`](wechat.md)           |
| 邮件、email、e-mail | [`email.md`](email.md)             |

# Genre Router: Report (`router.report`)

用数据、样本或研究形成洞察走本类；按读者任务选择且只读一个 leaf，关键词仅用于召回，`报告 / 分析 / 研究 / 数据 / 白皮书`单独不决定路由。组织执行 / 批准走 Workplace，自主学习走 Knowledge。

| 读者任务 / 关键词、强信号与排除 | Leaf |
|-|-|
| 回答明确研究问题，方法、样本和可推广边界决定可信度；调研报告、访谈 / 问卷 / 用户研究。仅解读既定指标时排除 | [`research-report.md`](research-report.md) |
| 解读已定义指标、趋势、分布、漏斗或实验观察值；数据报告、经营数据、指标复盘。需重新设计样本回答问题时排除 | [`data-report.md`](data-report.md) |
| 让专业读者系统理解并评估问题、框架或方案；白皮书、行业框架、技术 / 政策议题。获客、产品卖点或 CTA 为主时排除 | [`white-paper.md`](white-paper.md) |
| 比较战略、投资、市场、产品或资源选项及成本、收益、风险；商业分析、可行性、进入 / 自建或采购判断。正文要求具名决策者选择 / 批准，或形成授权、资源拨付、执行承诺入口时排除 | [`business-analysis.md`](business-analysis.md) |

# Genre Router: Workplace (`router.workplace`)

组织内决策、执行、留档走本类；先按读者任务与生命周期选择且只读一个 leaf，关键词仅用于召回，排除信号优先于同名词。

| 读者任务 / 关键词、强信号与排除 | Leaf |
|-|-|
| 快速知悉、短判断或会前准备；备忘录、决策摘要、会前材料。完整批准论证走 Proposal，周期状态走 Weekly | [`memo-brief.md`](memo-brief.md) |
| 按周期判断相对承诺的状态、偏差、风险和下一步；周报、日报、月报、项目状态。原因学习走 Retrospective，完整分析走 Report | [`weekly-report.md`](weekly-report.md) |
| 请具名决策者批准方向、预算、资源或执行承诺；提案、立项、资源申请。已定产品行为走 PRD | [`proposal.md`](proposal.md) |
| 将方向已定的一次性项目、变更、专项行动或营销战役转成可协同推进的交付、依赖、里程碑与验收；项目计划、执行方案、实施计划。仍在比较方向或请求批准走 Proposal / Report，重复稳定路径走 SOP | [`execution-plan.md`](execution-plan.md) |
| 将已授权的内部规则 / 安排、可复核的检查整改记录或已核定组织立场写成正式载体；制度、公司通知、整改记录、讲话底稿。待批准方向走 Proposal，复杂执行走 Execution Plan，法定公文走 Official；`正式`单独不触发 | [`formal-doc.md`](formal-doc.md) |
| 党政机关法定公文拟制、审校或制发；明确要求公文 / 红头 / 套红 / 正式发文，或法定文种与机关行文关系、文号、主送等制发要素共同出现。`通知 / 报告 / 公告 / 纪要 / 正式 / 官方`单独不触发 | [`official-redhead.md`](official-redhead.md) |
| 记录已发生会议的决定、异议、行动和批准状态；会议记录、行动项。逐字稿不走本 leaf，法定公文纪要走 Official | [`meeting-minutes.md`](meeting-minutes.md) |
| 从已结束周期 / 事件提炼证据化学习并改变下一轮；复盘、回顾、经验教训。当前状态走 Weekly，活跃未知事故走 Technical | [`retrospective.md`](retrospective.md) |
| 方向已定，定义用户问题、范围、产品行为与验收；PRD、用户故事、验收标准。是否投入走 Proposal，实现取舍走 Technical | [`prd.md`](prd.md) |
| 评审未来技术设计、查询精确契约或调查未知故障；RFC、API、架构、事故调查。产品行为走 PRD，已定重复路径走 SOP | [`technical-doc.md`](technical-doc.md) |
| 按已批准、可验证路径重复达到终态，或为已知事件类别预置响应路径；SOP、runbook、值班 / 操作手册、BCP / 处置预案。应急预案若主要发布权威职责走 Formal，法定制发走 Official，活跃未知事故走 Technical，一次学习教程走 Knowledge | [`sop-tutorial.md`](sop-tutorial.md) |

# Genre Contract: SOP / Runbook (`workplace.sop_tutorial`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 命令式、具体、顺序稳定，一步一动作并紧邻可观察判据，不写无条件的“适当 / 必要时” |
| 内容逻辑 | 先定 routine / controlled / high-risk，并识别是否为响应预案，再按“版本 → 触发 / 范围 / 终态 → 角色 / 前置 → 动作 / 判据 / 证据 → 异常 / 停止 / 恢复 → 完成记录 / 复审”推进 |
| 事实 / 边界 | owner、版本、环境、资格、权限、工具、命令、阈值、预期结果和恢复路径均须已验证；警告在动作前；命令成功不等于业务终态；流程图 / 示意不能替代可执行步骤、判据与异常路径，须有文字等价；关键未知使可发布稿 `blocked` |
| 错误 | 教程冒充 SOP、未分风险、缺 owner / 版本 / 前置、一条多动作、编造入口 / 阈值 / 权限 / 命令、停止后状态未知、只写“必要时回滚”或未验证终态；响应预案无分级触发、替补指挥、降级路径或解除条件，任一出现即失败 |

## 适用与风险分类

用于组织规定的重复作业、沿已批准路线取得确定终态的 runbook，或针对已知事件类别预置并授权的响应 / 业务连续性路径。一次性自助 how-to / 学习走 Knowledge；未来设计取舍、活跃未知故障或临场根因调查走 `technical-doc.md`；只建立组织权威、职责或发布要求而不提供现场步骤走 `formal-doc.md`。“教程 / 操作 / 手册 / 应急预案”单词本身不触发。

| 分类 | 增量证明义务 |
|-|-|
| `routine` | 阶段或终态验证、常见异常和升级 |
| `controlled` | 再含审批、接受 / 拒绝、偏差记录、变更复审和代表性试跑 |
| `high-risk` | 再含 precheck、hold point、go / no-go、停止条件，以及可执行 rollback / fallback / roll-forward 和恢复验证 |

## 响应预案增量

- 涉及人身安全或法定直报时，其优先级高于业务与财产；按已核风险设置进入、升级、降级和解除条件，明确指挥 / 决策权限、替补角色、首轮动作、信息报送与对外口径边界。联络序列、等待时长和重试次数须预先批准；未知时保留占位，仅放行无需等待授权的安全动作。
- 预设负责人失联、断网断电、主资源不可用等降级场景及可达的安全终态；恢复须验证真实业务终态。发布前按风险做桌面推演或代表性演练，高风险场景包含故障注入并记录缺口、owner 和复验。

## 文控与证据

写明触发、目标终态、范围、owner / 资格、当前版本 / 环境、前置、权限、工具和输入。命令、参数、阈值、预期输出、备份 / 恢复资产和试跑结果须来自真实环境；流程变更后更新、复审并标 superseded 状态。

关键缺口就近使用`[待环境 owner 验证]`等具体占位。命令、权限、阈值、停止或恢复判据未知时只保留安全只读 precheck，不得创建可执行稿。

## 步骤、异常与恢复

- 每个关键步骤只写一个动作，紧邻可观察结果、阈值与证据；验证需要操作时另列一步。未知偏差停止于已知安全状态，记录证据并升级。
- high-risk 在不可逆动作前设置 hold point：列 go / no-go 信号、决策人和信号缺失时的安全终态。rollback 写触发条件、适用范围、步骤、阈值、停止点和恢复后业务验证，不能只写命令回执。
- 有状态迁移另列不可逆点、写入归属、checkpoint / 幂等，以及完整、无重复、有序或等价验证；关闭 fallback 前必须证明新终态稳定。

## 高质量写法

让具备规定基础资格但不熟流程的人可独立复现；选择条件写在动作前，稳定原理链接出去，不混入原理课或临场诊断。按风险裁剪篇幅但不删证明义务；按适用治理要求由代表性执行者试跑，未经任何实际验证不得发布。

# Genre Contract: Technical Document / 技术文档 (`workplace.technical_doc`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 精确、可证伪、术语与版本稳定；规范词仅用于明确采用的互操作、安全或验收语义 |
| 视觉约束 | 在有明确内容作用时用代码、表格、架构 / 状态 / 时序图等组件降低实现与诊断成本，但不得替代契约、证据或操作说明 |
| 内容逻辑 | 必须且只能选 design_rfc、api_reference、incident_diagnostic 一种主模式；分别按“证据 → 取舍 / 设计 → 验收”“契约 → 错误 / 兼容”“影响 → 假设 / 检查 → 验证 / 升级”推进 |
| 事实 / 边界 | 标对象、环境、版本、时间、范围和证据窗；事实、推断、决定、未知分开；示例 / 图不替代契约；任何改状态动作须有授权、影响、停止、还原和恢复验证，关键缺口按 reader impact 处理 |
| 错误 | 按关键词路由、三模式混写、设计无取舍 / 验收、reference 漏权限 / 错误 / 生命周期 / 兼容、未知故障直接定根因、改状态无授权 / 停止 / 还原或图作唯一证据，任一出现即失败 |

## 先选唯一主模式

| 主模式 | 读者任务 | 排除 |
|-|-|-|
| `design_rfc` | 评审者能批准并实现未来技术状态，理解替代、后果和验收 | 产品可观察行为走 PRD；既定路径走 SOP |
| `api_reference` | 调用者无需猜版本、权限、输入、行为、副作用、错误与生命周期 | 仍在讨论接口取舍时走 design_rfc |
| `incident_diagnostic` | 响应者以安全、有区分度的动作缩小未知、止损、恢复或升级 | 单纯团队学习走 Retrospective；已知重复处置走 SOP |

## 共同证据边界

标明对象、环境、版本、时间、范围 / 前置和证据位置 / 窗口；结论回链仓库、IDL / schema、日志、metrics、traces、变更记录或验证实验。缺口就近使用具体占位、收窄或 `blocked`；数据分级、访问、保留、重放、owner、时限和升级只在适用时形成门禁。

代码与命令示例须实际验证并标环境 / 版本；架构、状态或时序图必须附文字等价，不能成为唯一证据或唯一操作说明。

## Design RFC

按问题证据 → 目标 / 非目标 → 约束 / 不变量 → 真实备选与同口径取舍 → 接口 / 数据 / 状态设计 → 失败、安全、兼容与迁移 → 上线 / rollback → 可观测性、测试 / 验收 → 未决决定推进。每项关键决定写 why、被否方案及后果；不得隐藏低置信度或版本偏差。

## API Reference

写清版本 / 环境 / 权限 / 签名、输入约束、行为 / 副作用 / 幂等、输出、已知错误及可操作恢复、限流 / 分页 / 重试、兼容 / 弃用。事件、异步、CLI、SDK、流式按需补 channel / message、交付 / 顺序、生命周期 / 耗尽、I/O、取消与背压；未知语义明确 unspecified，不从示例推断承诺。

## Incident Diagnostic

按影响与 expected / actual → 当前状态与证据链 → 可证伪假设 → 信息增益高且副作用低的检查 → 止损 / 恢复验证 → 升级与后续 RCA 推进。每项检查写预期观察及其支持 / 排除的假设。

修改状态前必须确认授权、目标范围、潜在副作用、停止条件、还原路径和恢复判据；分开止损、根因与永久修复。缺证据、授权、owner、还原或升级路径时只给安全只读检查并 `blocked`；涉及安全 / 法务时先保全证据和升级。

# Genre Contract: WeChat Official Account / 微信公众号文章 (`platform.wechat`)

## 核心定位（硬约束）

- 交付物是飞书文档中的“微信公众号风格”内容稿，不代表实际发布，也不执行微信平台审核、流量、商业或发布规则。
- 视觉策略默认使用 `rich`，主动寻找图文结合的表达机会，但每个组件必须服务主线。
- 写作风格可信、有观点、有叙事或论证推进，在专业感与亲近感之间保持平衡。公众号不是加长版小红书，也不是公文或报告换皮。
- 一篇只服务一个读者任务和一个可兑现承诺；标题、封面、摘要、导语、正文与结尾围绕同一主线。不编造亲历、身份、数据、引语、案例或效果；无来源时不用“多数、普遍、研究表明”等统计口吻，材料不足时明确收窄表达。
- 飞书源稿禁止使用 `callout`；生成后通过 Draft Profile Check 的 `profile.blocks` 检查，其他 block 按真实信息关系选择。

## 适用与消歧

用户明确要“微信公众号文章、公众号推文、微信长文、微信爆文、公众号风格”时使用，内容保存在哪里不影响本合同生效。

普通微信聊天消息、群公告、朋友圈文案、视频号口播、小程序页面和服务通知不走本合同。仅把微信作为研究对象、信息来源或业务渠道时也不触发；若同时要公众号稿和正式体裁，分别生成，不混写。

## 内容模式

| 模式 | 内容脊柱 |
|-|-|
| 知识 / 方法 | 读者处境 → 核心原理 / 结论 → 方法与验证 → 成本、例外和适用边界 → 可执行认识 |
| 观点 / 解释 | 现象或争点 → 中心判断 → 理由、证据与机制 → 相关反论 / 边界 → 校准后的结论 |
| 资讯 / 热点 | 已确认事实 → 为什么重要 → 必要背景与多方信息 → 争议 / 未知 → 当前结论或更新点 |
| 案例 / 故事 | 具体场景 → 选择与行动 → 可观察结果 → 代价 / 失误 → 可迁移洞见 |
| 品牌 / 行动 | 读者场景 → 有边界的价值 → 证据 / 体验 → 条件与取舍 → 清楚结论 |

## 成稿要求

- 先钉住具体读者、核心问题与中心判断；内部比较信息清晰型、问题 / 冲突型、观点浓缩型标题，成稿只输出既有张力又不透支正文的一个。
- 标题负责建立准确预期；摘要按需补充关键背景、判断或阅读收益，不复述标题。摘要、导语和首节必须各有信息增量。封面只保留一个视觉中心，图片文案不制造第二个主题。
- 导语在首屏内用具体场景、问题、变化或判断说明“为什么值得读”，随后尽快进入主线，不用宏大背景、客套话或悬念拖延核心信息。
- 正文沿一条逻辑线展开，小标题概括本节增量。段落各有一个主要意思，但长短随内容变化：重点句可独立成段，证据、故事和推理要保留完整上下文，避免短句过多造成逻辑断裂。
- 使用自然、可交流的书面语；用具体细节、例子、转折和取舍形成作者声音，不靠网络热词、排比口号或统一句式制造“爆文感”，避免连续复用同一反转句式。
- 完整稿至少给出一个封面或正文视觉方案；已有图片时就近用于提供证据、解释信息、建立场景或调节长文节奏。图片不设固定数量，也不为“图文并茂”强塞装饰图，正文仍须独立可读。
- 结尾回扣开头问题或中心判断，留下结论、影响或自然的下一步；互动句、emoji 和话题标签均按需使用，不要求固定收尾动作。

## 交付前检查

确认标题没有透支正文，摘要与导语没有重复，文章主线连续，每节都在推进事实、故事、论证或方法，手机上容易扫读但不过度碎片化，图片确实帮助理解，且没有空洞口号、标题党、模板腔或虚构事实。

# Genre Contract: Weekly / Status Report (`workplace.weekly_report`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 具体、短、面向判断，稳定使用最小字段与状态语义，不用“持续推进”代替产出 |
| 内容逻辑 | 围绕报告对象和周期，按“总体状态 / 最大变化 → 对照基线的产出 → 偏差 / 风险 / 依赖 → 下一里程碑 → ask”推进，只写影响判断的变化 |
| 事实 / 边界 | 状态须回链范围、时间、质量、成本、资源或阻塞证据；事实、当前状态和下期计划分开；无基线或数据不足时写 unknown，不猜完成率、原因、owner 或日期 |
| 错误 | 活动流水账、无周期 / 基线、健康色无判据、风险被埋、猜测根因冒充事实、下一步无里程碑、ask 不可执行或自动汇总不可追，任一出现即失败 |

## 适用与消歧

用于按固定或约定周期判断当前相对目标 / 计划 / 承诺的位置。解释已结束周期为何如此并改变下一轮走 `retrospective.md`；完整指标洞察走数据报告；一次性高层知会走 `memo-brief.md`。“报告 / 进展”单词本身不触发本体裁。

## 状态与证据

- 标明报告对象、周期 / 截至时间；进展使用已验收产出、里程碑或有口径指标，会议数、沟通和投入时长本身不等于进展。
- On track / 红黄绿等状态须有预先定义或就近说明的判据。无基线时明确“无法判断是否按计划”，而不是默认绿色。
- 风险、问题、依赖和阻塞按已知程度写影响、当前缓解、责任方与升级需求；冲突数据并列保留并标`[口径待核]`。

## 结构与高质量写法

个人短更新可收缩，项目群 / 月报可按需增加趋势、成本或预算，但不复制无用栏目。优先写相对上期和相对承诺的 delta；稳定低风险项可链接原记录。ask 写明对象、事项和需要时间，关键数据延迟时说明最近可用时间点及其判断影响。

# Genre Contract: White Paper / 白皮书 (`report.white_paper`)

## 体裁规则表（硬约束）

| 规则项 | 规则 |
|-|-|
| 写作风格 | 系统、清楚、克制；权威来自真实主体、证据与归属，不来自篇幅、正式腔或视觉复杂度 |
| 内容逻辑 | 先确认白皮书类型、发布主体、专业读者和期望判断，再用证据建立问题、评价标准或框架、论证、反例及应用边界；框架必须实际解释或比较 |
| 事实 / 边界 | 客观主张连接真实来源、时点、范围和限制；事实、解释、价值判断、提议与品牌立场可区分；政策身份、发布状态、利益、资助和案例选择不得虚构或隐匿；证据图与材料须确认使用权、来源和说明，复杂视觉附文字等价信息 |
| 错误 | 政策与品牌身份混写；标题或版式伪造权威；宏大背景填篇幅；自创框架仅作装饰；来源不可追；单一案例冒充共识；忽略反证 / 利益冲突；CTA 吞没证据；复杂组件代替论证 |

## 适用与消歧

让专业读者系统理解并评估问题、框架或解决路径。先区分有权主体的政府政策白皮书与专业、技术或品牌资助白皮书；`白皮书`、`正式`、`权威`单独不产生政府或标准身份。明确研究问题和方法为核心走 [`research-report.md`](research-report.md)，特定组织选项决策走 [`business-analysis.md`](business-analysis.md)，设计 / RFC / 接口契约走 Technical，产品卖点、获客或 CTA 为主走 Marketing。

## 子类型

- **政府政策白皮书**：只有真实有权主体可使用；准确标政策、咨询、立法与发布状态，不模拟批准或法律效力。
- **政策 / 专业问题白皮书**：围绕问题、证据、评价标准、方案和影响形成可审查论证。
- **技术 / 行业 landscape 白皮书**：解释技术、标准或系统框架；一旦主要任务是批准实现设计或查询精确契约，改走 Technical。
- **品牌资助白皮书**：证据评估仍须是主体任务；披露资助、产品利益和案例选择，转化内容与论证分层。

## 证据与边界

- 开头明确作者 / 发布主体、读者、使用场景、范围、文档状态、核心立场和期望判断。
- 主张强度匹配证据层级；有限测试、相关观察、厂商数据或单一案例不得扩写成绝对承诺或行业共识。
- 框架的每一层都须增加解释、比较或选择价值；问题原因、评价标准与方案逻辑相连，并处理重要反证、替代解释和可行性限制。
- 主体或授权不明时用 `[发布主体待确认]`，不得写成政府、官方或标准；核心证据不足时收窄为 concept note / outline。利益关系或关键政策状态无法确认的发布稿标记 `blocked`。

## 结构与高质量写法

独立摘要（主体、论点、证据边界） → 问题与现有证据 → 评价标准或核心框架 → 逐层论证、方案与反例 → 应用 / 政策含义及条件 → 限制、利益关系与来源。摘要让忙碌读者复述主张和保留条件；长篇才增加目录或附录，不以背景、封面、缩写或组件制造权威感。

# Genre Contract: Xiaohongshu Note / 小红书笔记 (`platform.xiaohongshu`)

## 核心定位（硬约束）

- 交付物是飞书文档中的“小红书风格”内容稿，不代表实际发布，也不执行小红书平台审核、禁词、流量或商业规则。
- 视觉策略默认使用 `rich`，偏爱图文并茂和清晰轻松的阅读体验，但装饰不能代替内容。
- 写作风格鲜活、有节奏、有画面感，可使用符合语境的 emoji。
- 一篇只解决一个主要问题；标题、封面、首屏和正文围绕同一获得感并真正兑现。不编造亲历、身份、数字、效果或用户反馈，材料不足时用第二人称、场景化讲解或中性叙述。
- 飞书源稿禁止使用 `callout`；生成后通过 Draft Profile Check 的 `profile.blocks` 检查，其他 block 按真实信息关系选择。

## 适用与消歧

用户明确要“小红书笔记、小红书写法、小红书 style、红书感、XHS 风格”时使用，内容保存在哪里不影响本合同生效。

仅把小红书作为研究对象、数据源或业务渠道时不触发：小红书运营方案走 Workplace，平台数据或竞品分析走 Report，规则说明走 Knowledge。若同时要小红书风格稿和正式体裁，分别生成，不混写。

## 笔记主任务

| 主任务 | 内容脊柱 |
|-|-|
| 教程 / 攻略 / 知识 | 痛点场景 → 核心判断 → 分步做法 → 易错点 / 限制 → 马上可做的一步 |
| 体验 / 测评 / 探店 | 使用场景 → 具体观察 → 亮点与槽点 → 适合谁 / 不适合谁 → 选择建议 |
| 观点 / 热点 | 争议或反差 → 核心判断 → 理由与例子 → 另一面 / 边界 → 留给读者的问题 |
| 个人经历 / 成长 | 真实困扰 → 转折瞬间 → 做过什么 → 可观察变化 → 可迁移认识 |
| 推荐 / 种草 / 活动 | 目标人群与场景 → 核心价值 → 具体理由 / 体验 → 使用条件与取舍 |

## 成稿要求

- 先钉住具体读者、场景与获得感；内部比较搜索清晰型、痛点共鸣型、反差好奇型 3 个标题，成稿只输出正文能兑现的最强一个。
- 首屏用 1—3 个短段落完成“具体场景 / 冲突 → 核心判断 → 内容预告”，不从宏大背景或自我介绍讲起。
- 正文用短段落和有意义的小标题按信息增量推进；每节新增动作、观察、例子、判断或限制。“活人感”来自具体细节、选择和取舍，不靠强塞网感词。
- emoji 可比正式体裁用得更积极，用于导航、语气和停顿，但不连续堆叠。围绕一个视觉中心设计封面，图片 / 截图 / 示意图就近服务对应内容；无可用图片时给出简短配图建议，正文仍须独立可读。
- 核心主题词自然出现在标题或首屏，相关表达按需进入小标题和正文；话题标签少而相关，不为覆盖关键词而复读。
- 结尾用一句记忆点收束；互动问题可选且至多一个，不要求固定收尾动作。

## 交付前检查

确认读者能一眼判断“这和我有关”，标题承诺已兑现，每节都有实质信息，手机上容易扫读，emoji 与图片确实帮助理解。出现公文腔、长铺垫、文字墙、题文错配、空情绪或虚构事实时返工。

# 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`。
- 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。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` 字段包含 cwd、workspace、draft_path，后续 CLI 在 `data.cwd` 下执行；将 `data.workspace` 记为 `work_dir`、`data.draft_path` 记为 `draft_path`（已含工作区前缀）。
- CLI 会创建独占的 `work_dir` 并保存 `.presentation-decision.json` 作为固定基线，**但不会创建 `draft_path` 指向的 XML**。`draft_path` 是当前任务可直接写入的新文件路径；

### 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="@./downloads/image.png"/>`；画板使用 `<whiteboard type="svg" path="@./<work_dir>/diagram.svg"/>` 并遵循[`画板工作流`](lark-doc-whiteboard.md)；HTML 使用 `<html5-block path="@./<work_dir>/widget.html"/>` 并遵循[`拓展标签`](lark-doc-xml-extended-blocks.md)。
2. 直接在 `<data.cwd>/<draft_path>` 创建并写入完整 release candidate。新建资源建议放 `<data.cwd>/<work_dir>`，已有资源可原地复用；CWD 内优先用相对路径，其他位置用允许访问的绝对路径。XML 内相对资源先查 CWD，仅文件不存在时回退到 XML 所在目录。
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. `passed` 只覆盖已启用的检查；先对照用户要求确认应声明的约束已完整填写，再按 [`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` 及其中的创作草稿。最终只交付用户需要的结果，并说明必要来源、未关闭缺口、异常、失败或阻塞原因，以及文档 URL 或 token。

# docs +create（创建飞书云文档）

从 XML（默认）或 Markdown 内容创建一个新的飞书云文档；语义创作默认使用 XML，只有 Authoring 明确判定为 Markdown 例外时才使用 Markdown。

写入前必须按 `--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
# 简单内容优先使用 `--content -`，文件导入如下：
lark-cli docs +create --doc-format xml --content "@<XML 文件相对路径>"
lark-cli docs +create --doc-format markdown --content "@./draft.md"
```

## 返回值

```json
{
  "ok": true,
  "identity": "user",
  "data": {
    "document": {
      "document_id": "docx_token",
      "revision_id": 1,
      "url": "https://xxx.feishu.cn/docx/docx_token",
      "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 继续操作。
- **`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>`；多个标题仅保留第一个|
|`--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-cli docs +fetch --doc "<document_id 或文档 URL>" --detail with-ids` 回查，若需要更多信息可查看 [`+fetch`](lark-doc-fetch.md)。

# docs +fetch（读取飞书云文档）

读取整篇文档，或按目录、章节、区间和关键词获取局部内容。

## 常用示例

```bash
# 读取整篇文档，并附带当前用户可见的未解决评论；
lark-cli docs +fetch --doc "文档URL或token"

# 按 URL 中的 #share 锚点局部读取
lark-cli docs +fetch --doc '文档URL#share-anchor'

# 按关键词定位
lark-cli docs +fetch --doc Z1Fj...tnAc --scope keyword --keyword "部署|发布|上线"

# 先查看目录，再读取指定章节
lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
```

## 参数

|参数|必填|说明|
|-|-|-|
|`--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`，不限）|

## 选择详细度：`--detail`

|目的|取值|返回内容|
|-|-|-|
|浏览、总结|`simple`（默认）|简洁 XML/Markdown，不含 block ID、样式和引用元数据|
|定位、跳转|`with-ids`|包含 block ID，可用于 `+update --block-id`，也可拼成 `文档URL#block_id` 直达链接|
|编辑文档|`full`|包含 block ID、样式和引用元数据，保留完整结构信息|

需要修改文档时使用 `full`；只读场景通常不必获取额外元数据。

## 选择读取范围：`--scope`

`--scope` 与 `--detail` 可以组合。优先读取满足任务所需的最小范围；只有确需全文时才省略 `--scope`。

|模式|适用场景|关键参数|返回行为|
|-|-|-|-|
|`outline`|结构未知，先查看目录|`--max-depth`|扁平列出标题；返回的标题 ID 可作为 `section` 或 `range` 的端点|
|`section`|读取某个标题对应的整节|`--start-block-id`（必填）|顶层标题展开到下一个同级或更高级标题之前；容器内节点（含内嵌标题）按最小包容单元返回容器或表格切片|
|`range`|已知精确起止位置|`--start-block-id`、`--end-block-id` 至少一个|同一顶层序列按区间切片；同一容器返回整个容器；同一表格返回瘦身切片；跨顶层时完整返回端点所在的顶层块|
|`keyword`|只有关键词或模糊线索|`--keyword`（必填）|按最小包容单元返回命中；同一容器的多处命中自动去重，同一表格的多行命中合并为切片|

`keyword` 会依次尝试子串、归一化、分词形变和 RE2 正则匹配。多关键词使用 `|` 表示 OR，例如 `部署|发布|上线`；任一分支命中即返回。

范围参数的共同规则：

- `--max-depth`：`outline` 中 `3` 表示列出 h1～h3；其它模式中 `0` 表示仅返回块自身，`-1` 表示不限深度。
- `--context-before` / `--context-after`：仅对完整的顶层块生效。命中位于容器或表格内时会被忽略；如需更大范围，改用 `section` 或 `range`。

推荐选择顺序：

|已知信息|首选方式|后续动作|
|-|-|-|
|具体术语、错误码或标识|`keyword`|上下文不足时，用返回的 `top-block-id` 再执行 `section` 或 `range`|
|章节或标题|`outline --max-depth 3`|获取标题 ID 后执行 `section`|
|精确起止位置|`range`|按需调整端点或深度|
|没有关键词，也不了解结构|`outline`|根据目录转入 `section` 或 `range`|
|确实需要整篇|省略 `--scope`|—|

## 返回值

```json
{
  "ok": true,
  "identity": "user",
  "data": {
    "document": {
      "document_id": "docToken",
      "revision_id": 12,
      "content": "<title>标题</title><p>文档内容...</p>",
      "reference_map": {
        "<block_type>": {
          "<ref>": {
            "<real-attr-key>": "<real-attr-value>"
          }
        },
        "comments": {
          "c1": {
            "data": "<comment comment-id=\"xx\" block-id=\"xx\"><quote>引用内容</quote><msg>评论内容</msg></comment>"
          }
        }
      },
      "tips": "<safe replay or degradation guidance>"
    }
  }
}
```
- `content` 的格式由 `--doc-format` 决定。`reference_map` 是结构化 sidecar，一级键表示引用组：普通资源组通常以 `block_type` 命名，二级键 `ref` 对应正文中的临时引用，其值由真实属性组成；保留组 `comments` 使用 `<ref>.data` 保存评论。XML、Markdown 和 IM Markdown 在存在可见评论时都会返回该组；Markdown 正文没有与评论 key 对应的内联引用，这是有意的协议设计。没有提取数据时，`reference_map` 可能为空。`comments.tips.data` 表示评论因数量上限被截断，文档顶层 `tips` 则给出安全回放或依赖降级提示。`content` 和 `reference_map` 属于同一份响应，应保留完整 JSON 响应；`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见下文“局部读取的输出结构”。
- 评论内容不保证全部返回，需要详细信息时使用  `drive +list-comments` 获取完整评论。

### 理解局部读取结果

## 参数

设置 `--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>` 时，不要假设已经获取了整个顶层块。

表格默认瘦身：即使 `<table>` 本身是顶层块，也只返回表头和命中的行。读取整张表时，使用 `range --start-block-id <table-id> --end-block-id <table-id>`。如果切片覆盖全部数据行，SDK 会自动返回完整表格，不再包裹 `<excerpt>`。

## 处理文档内嵌资源

|返回内容|处理方式|
|-|-|
|`<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-meeting`](../../lark-meeting/SKILL.md) 的 `note +detail`|
|`<synced_reference>`|提取 `src-token` 和 `src-block-id`，读取源文档并定位 block|

## 参考

- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材或画板缩略图

# docs history（历史版本与回滚）

用于查看 Docx 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。

`entries[].edit_time` 是 RFC3339 时间字符串（例如 `2026-06-22T12:24:45Z`）。按时间匹配时先将其解析为时间值，再比较先后关系或时间差。

## 安全约束

- `overwrite` 会重建正文和 block ID，且无法保证保留评论等非正文对象。用户要求保留这些对象时，应先说明限制并确认。
- `overwrite` 返回 warning 或 `partial_success` 时，先核验最新内容。核验失败或发生 revision conflict 时停止，不要再次覆盖。
- 权限、网络或临时系统错误应保留原错误分类，不得解释为目标版本不存在。

## 按 revision_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. 目标版本明确不可读时停止并报告。

候选确认时使用类似格式：

```text
同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
```

## 命令

```bash
# 列出历史版本
lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20

# 翻页
lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"

# 回滚到指定 history_version_id（默认等待 30000ms）
lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42

# 只发起任务，不等待
lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42 --wait-timeout-ms 0

# 查询回滚任务状态
lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<task_id>"
```

## 参数

| 命令 | 参数 | 必填 | 说明 |
|-|-|-|-|
| `+history-list` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
| `+history-revert` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
| `+history-revert` | `--history-version-id` | 是 | `+history-list` 返回的 `history_version_id`，必须大于 0 |
| `+history-revert` | `--wait-timeout-ms` | 否 | 等待回滚完成的毫秒数，范围 `0-30000`，默认 `30000` |
| `+history-revert-status` | `--doc` | 是 | 同一个文档 |
| `+history-revert-status` | `--task-id` | 是 | `+history-revert` 返回的 `task_id` |

## 返回值要点

`+history-list` 返回：

```json
{
  "entries": [
    {
      "revision_id": 42,
      "history_version_id": "11",
      "edit_time": "2026-06-22T12:24:45Z",
      "type": 1,
      "name": "版本名",
      "description": "版本说明",
      "editor_ids": ["ou_xxx"]
    }
  ],
  "has_more": true,
  "page_token": "page_token"
}
```

`+history-revert` 返回：

```json
{
  "task_id": "task_xxx",
  "status": "running",
  "history_version_id": "11",
  "poll_after_ms": 10000
}
```

`+history-revert-status` 返回：

```json
{
  "status": "partial_failed",
  "history_version_id": "11",
  "failed_block_tokens": ["blk_xxx"]
}
```

`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或 `failed` 时，优先检查 `failed_block_tokens`。

# Markdown 格式参考

`docs +fetch` / `docs +create` / `docs +update` 使用 `--doc-format markdown` 时适用；fetch 的 `--doc-format im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用，不作为 create/update 写入格式。

## 转义规则

> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。

### 无条件转义（行内生效，任何位置都要转义）

| 符号 | Markdown 语法用途 | 转义写法 | 示例 |
|------|-------------------|----------|------|
| `\` | 转义符本身 | `\\` | `C:\\Users` → C:\Users |
| `` ` `` | 行内代码 | `` \` `` | `` 用 \` 包裹 `` |
| `*` | 斜体 / 加粗 | `\*` | `3 \* 5 = 15` → 3 \* 5 = 15 |
| `_` | 斜体 / 加粗 | `\_` | `foo\_bar\_baz` → foo\_bar\_baz |
| `[` `]` | 链接文本 | `\[` `\]` | `\[非链接\]` |
| `$` | 数学公式定界 | `\$` | `价格 \$100` |
| `~` | 删除线（GFM `~~text~~`） | `\~` | `a\~\~b\~\~c` → a~~b~~c |
| `<` | XML 标签起始（`<b>`、`<img>` 等会被当作标签解析并生效） | `\<` | 字面量 `<b>` 须写为 `\<b>`；`a < b` 建议写为 `a \< b` |

### 位置敏感转义（仅在特定位置才需要转义）

| 符号 | Markdown 语法用途 | 转义条件 | 示例 |
|------|-------------------|----------|------|
| `#` | 标题 | **仅行首**（去除前导空白后）| 行首 `\# 这不是标题`；行内 `A # B` 无需转义 |
| `+` | 无序列表 | **仅行首**（去除前导空白后）| 行首 `\+ item`；行内 `1 + 2` 无需转义 |
| `-` | 无序列表 / 分隔线 | **仅行首**（去除前导空白后）| 行首 `\- item`；行内 `A - B` 无需转义 |
| `>` | 引用块 | **仅行首**（去除前导空白后）| 行首 `\> 不是引用`；行内 `a > b` 无需转义 |
| `\|` | 表格 cell 分隔 | **仅在 GFM 表格 cell 内** | cell 内 `A \| B`；行内普通文本 `a \| b` 无需转义 |

**不需要转义的场景：**
- 在 `` ` `` 行内代码或 ` ``` ` 代码块内，所有符号均为字面量，无需转义
- `$...$` 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响

**导出已转义，不要反转义：**
`docs +fetch --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**

**写入时必须转义：**
使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。

**导出 → 更新 工作流示例：**

1. `docs +fetch` 导出得到 `C:\\Users\\test\[1\]`
2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
3. `--content` 中的替换内容也要保持转义：`C:\\Users\\prod\[2\]`

自行构造 Markdown 内容写入时同理：如字面文本 `a]b` 应写为 `a\]b`，`C:\Users` 应写为 `C:\\Users`。

## Shell 传参
- **首选文件传参**：`--content` 支持 `@./path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）
- **⚠️ `@file` 路径限制**：`@file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下（如 `./_content.md`），用完自行清理。
- **默认用单引号 `'...'`**：完全字面量，`$`、`` ` ``、`\`、`>`、`\<b>` 等全部原样保留
- **双引号 `"..."`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\` 仍参与转义，易踩坑
- **`$'...'` ANSI-C 引号**：按 C 转义解析，`\n`=换行、`\\`=单个 `\`；**zsh 下未知转义（如 `\<`）的 `\` 会被吞**，要保留字面 `\` 必须写 `\\`。只在确实需要 `\n`/`\t` 时用
- **多行内容**：用 `<<'EOF'` heredoc，EOF 必须带引号，否则仍展开 `$`
- **`\n` 在 `'...'` 和 `"..."` 里都是字面量**，不是换行；要真换行用 `$'...\n...'` 或 heredoc

## 图片语法

Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：
```markdown
![alt text](https://example.com/photo.png)
```
- `alt text` 为图片描述（可选，可留空）
- 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)。
> **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`<b>`、`<u>`、`<img>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `<tag>`），必须转义左尖括号：`\<b>`、`\<img>`。

## 参考

- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范

# docs +media-download（下载文档素材/画板缩略图）

> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

下载文档中的图片/文件素材（`file_token`），或下载画板缩略图（`whiteboard_id`）。当 `--output` 不带扩展名时，会根据响应的 `Content-Type` 自动补全扩展名。

## 选择规则

- 用户明确说“下载素材”时，使用 `docs +media-download`
- 用户只是想查看、预览图片或文件素材时，优先使用 [`docs +media-preview`](lark-doc-media-preview.md)
- 如果目标明确是画板 / whiteboard / 画板缩略图，继续使用 `docs +media-download --type whiteboard`；`+media-preview` 不支持画板

## 命令

```bash
# 下载图片/文件素材（默认 type=media）
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset

# 指定输出文件名（带扩展名则不会自动补全）
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset.png

# 下载画板缩略图（whiteboard token）
lark-cli docs +media-download --type whiteboard --token "wbcnxxxxxxxx" --output ./whiteboard
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--token <token>` | 是 | 资源 token：素材为 `file_token`，画板为 `whiteboard_id` |
| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
| `--type <type>` | 否 | `media`（默认）或 `whiteboard` |

## token 从哪里来

- 若你是从文档内容里提取：`lark-doc-fetch` 返回的内容里可能包含：
  - 图片：`<img token="..." .../>`
  - 文件：`<source token="..." name="..."/>`
  - 画板：`<whiteboard token="..."/>`

## 排障

- 如果返回 `permission_denied`，或最终下载返回 `HTTP 403`，按错误 `hint` 改用 [`docs +media-preview`](lark-doc-media-preview.md) 预览内容。
- 如果返回限流错误，停止立即重试，稍后按指数退避重试。

## 参考

- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

# docs +media-insert（文档末尾插入图片/文件）

> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在**文档末尾**插入本地图片或文件。

## 来源选择（Agent 必读）

> **最高优先级：用户明确指定了来源，就严格按用户的来。** 下面的启发式只在用户没表态时生效。
>
> - 用户说"把这张截图插进去"、"用剪切板里的图"、"我刚复制的" → 无条件走 `--from-clipboard`。
> - 用户说"用 `~/Downloads/foo.png`"、"插本地这个文件"、给了具体路径 → 无条件走 `--file`。
> - 用户两者都没说清 → 按下表的启发式推断。
>
> 即使推断看起来更"优"（比如用户说了路径但你觉得走剪切板更省事），也**不要自作主张**换来源。要换，先问。

按下列顺序判断，**不要反向做**：

| 用户的图片来源 | 命令 | 禁止做法 |
|----------------|------|----------|
| 图片已经在剪切板里（截图快捷键、从飞书/浏览器复制、从设计稿复制） | `--from-clipboard` | ❌ 不要先把剪切板存到本地文件再用 `--file`。多一步文件 I/O，还得清理临时文件。 |
| 图片是磁盘上的真实文件 | `--file <path>` | — |
| 图片是 URL | 先下载到本地 → `--file`；或用 `drive` 相关命令 | — |

`--from-clipboard` 走进程内存直传，不产生临时文件；macOS / Windows 内置支持，Linux 需要 `xclip` 或 `wl-paste` 或 `xsel` 任一。

### 剪切板为空时的 fallback

`--from-clipboard` 失败（剪切板里不是图片 / 没有图片 / Linux 上三个工具都没装）时，命令会返回 `clipboard contains no image data`（或类似的平台错误）。**这不是错误退出理由，而是 fallback 信号。**

**Agent 的标准处置顺序**（每一步失败再进下一步，不要并行）：

1. 先用 `--from-clipboard` 试一次。
2. 如果返回"no image data"类错误，**向用户明确说明剪切板里没有可识别的图片**，请用户提供本地文件路径或重新复制一张图。
3. 拿到本地路径后，用 `--file <path>` 重试**同一条插入命令**（其他参数如 `--doc` / `--align` / `--caption` 保持不变）。

**禁止做法**：
- ❌ 不要悄悄把空剪切板当"成功但没插入"处理。必须提示用户。
- ❌ 不要在剪切板失败后自行瞎猜某个本地文件路径（比如最近修改的 png）。必须让用户给路径。
- ❌ 不要用"先让用户保存剪切板到磁盘再 `--file`"的建议绕过 `--from-clipboard`，当且仅当剪切板确实没图片时才退回本地路径。

## 命令

```bash
# 🟢 推荐：从剪切板直接插入（无需先存盘）
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard

# 从本地文件插入
# 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地：
lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
  --block-id "目标 block_id" \
  --content '<img href="https://example.com/photo.png"/>'

# 插入图片（默认）
lark-cli docs +media-insert --doc doxcnXXX --file ./image.png

# doc 支持直接传 docx URL（自动提取 document_id）
lark-cli docs +media-insert --doc "https://xxx.feishu.cn/docx/doxcnXXX" --from-clipboard

# 如果上一步是 create-doc，优先传返回值里的 doc_id
# 不要把 /wiki/... 形式的 doc_url 直接传给 docs +media-insert
lark-cli docs +media-insert --doc doxcnReturnedByCreateDoc --file ./image.png

# 插入文件（非图片）
lark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file

# 图片对齐与描述（caption）
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --caption "架构图"

# Insert image with explicit display width (height auto-computed from aspect ratio)
lark-cli docs +media-insert --doc doxcnXXX --file ./banner.png --width 800 --align center

# Insert image with explicit width and height
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height 447 --caption "architecture diagram"
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--doc <id>` | 是 | 文档 ID 或 docx URL（仅支持 `/docx/<document_id>` 形式自动提取；**不支持 `/wiki/...` URL 自动提取**） |
| `--from-clipboard` | 二选一 | 从系统剪切板读取图片（与 `--file` 互斥）。macOS/Windows 内置支持，Linux 需要 `xclip` / `wl-paste` / `xsel` 之一。 |
| `--file <path>` | 二选一 | 本地文件路径（文件大于 20MB 时自动切换分片上传） |
| `--type <type>` | 否 | `image`（默认）或 `file`。`--from-clipboard` 目前只产出 image。 |
| `--align <align>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |
| `--caption <text>` | 否 | 仅图片：图片描述 |
| `--width <px>` | 否 | Image display width in pixels (only for `--type=image`). If `--height` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
| `--height <px>` | 否 | Image display height in pixels (only for `--type=image`). If `--width` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |

> [!IMPORTANT]
> 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。

## 平台注意（仅 `--from-clipboard`）

| 平台 | 依赖 | 典型错误 |
|------|------|---------|
| macOS | osascript（内置） | 剪切板为空 / 不是图片 → "clipboard contains no image data" |
| Windows | PowerShell + System.Windows.Forms（内置） | 同上 |
| Linux | `xclip` 或 `wl-paste` 或 `xsel` 任一 | 都没安装 → 报错会提示用发行版包管理器安装 |

命令不支持读取 TIFF 等非 PNG/JPEG/GIF/WebP/BMP 的冷门格式；遇到这类剪切板会返回 "contains no image data"，此时才考虑先用系统工具转成文件再 `--file`。

## 输出

命令成功后会输出 JSON，包含：`document_id`、`block_id`、`file_token`、`file_name`（剪切板路径下为 `clipboard.png`）、`type`。

> [!CAUTION]
> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。

## 参考

- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

# docs +media-preview（预览文档素材）

> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。

## 选择规则

- 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview`
- 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md)
- 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard`

## 命令

```bash
# 预览图片/文件素材
lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset

# 指定输出文件名（带扩展名则不会自动补全）
lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset.png
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--token <token>` | 是 | 素材 token，即 `file_token` |
| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |

## token 从哪里来

- 若你是从文档内容里提取：`lark-doc-fetch` 返回的内容里可能包含：
  - 图片：`<img token="..." .../>`
  - 文件：`<source token="..." name="..."/>`

## 参考

- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
- [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

# 飞书思维笔记（Mindnote）

> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 和 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和路由规则。

当用户要操作思维笔记时，入口属于 `lark-doc`，但实际执行命令使用 `lark-cli mindnotes nodes list/create`，不是 `docs +...`。

> [!IMPORTANT]
> 当前这条链路只支持**读取已有思维笔记**，以及在**已有思维笔记**里读取节点、创建子节点。
> `mindnotes nodes create` 是新增/更新节点命令，**不是**新建一个新的思维笔记。
> 如果用户要**新建思维笔记**，不要走本链路，改走 [lark-doc-whiteboard](lark-doc-whiteboard.md)。

## 获取 `mindnote_id`

`--mindnote-id` 传 **Mindnote 文档 token**，不是节点 ID。`lark-cli mindnotes` 只负责读取和写入思维笔记内部节点。

```bash
# 用户给了 Mindnote URL，或给了可能包着 Mindnote 的 Wiki URL
lark-cli drive +inspect --url "<mindnote_or_wiki_url>"
```

处理规则：

- 普通 Mindnote URL：`drive +inspect` 返回的 Mindnote token 可作为 `--mindnote-id`。
- Wiki URL：不要把 `/wiki/` 路径里的 wiki token 当作 `--mindnote-id`；必须先 `drive +inspect` 解包，确认底层类型是 `mindnote` 后再使用返回的真实 token。直接把 wiki token 传给 `mindnotes nodes list` 通常会返回 `3410003 resource not found`。

## 命令

```bash
# 先看命令帮助
lark-cli mindnotes nodes list --help
lark-cli mindnotes nodes create --help

# 读取节点列表
lark-cli mindnotes nodes list --mindnote-id "<mindnote_token>"

# 创建子节点
lark-cli mindnotes nodes create \
  --mindnote-id "<mindnote_token>" \
  --data '{"client_token":"<client_token>","nodes":[{"parent_id":"node_parent123","texts":[{"element_type":"text","text":{"content":"子节点内容"}}],"highlight":"yellow","finish":false}]}'

# 更新已有节点
lark-cli mindnotes nodes create \
  --mindnote-id "<mindnote_token>" \
  --data '{"client_token":"<client_token>","nodes":[{"node_id":"node_existing123","texts":[{"element_type":"text","text":{"content":"更新后的节点内容"}}],"highlight":"blue","finish":true}]}'
```

## 参数

### `mindnotes nodes list`

| 参数 | 必填 | 说明 |
|------|------|------|
| `--mindnote-id` | 是 | 思维笔记 token / 唯一标识 |

返回重点：`data.nodes` 中常见字段有 `node_id`、`parent_id`、`texts`、`notes`、`images`、`finish`、`highlight`。

### `mindnotes nodes create`

命令参数：

| 参数 | 必填 | 说明 |
|------|------|------|
| `--mindnote-id` | 是 | 思维笔记 token / 唯一标识 |
| `--data` | 是 | JSON 请求体 |

请求体字段：

| 字段 | 必填 | 说明 |
|------|------|------|
| `client_token` | 否 | 幂等 token，建议写操作传入；推荐使用时间戳或 UUID |
| `nodes` | 是 | 待创建或更新的节点数组 |
| `nodes[].node_id` | 否 | 节点 ID；传入已有 `node_id` 时表示更新对应节点 |
| `nodes[].parent_id` | 否 | 父节点 ID；创建子节点时传入 |
| `nodes[].texts` | 否 | 节点正文富文本数组 |
| `nodes[].notes` | 否 | 节点备注富文本数组 |
| `nodes[].images` | 否 | 节点图片列表 |
| `nodes[].highlight` | 否 | `red` / `yellow` / `pink` / `blue` / `cyan` / `olive` / `grey` |
| `nodes[].finish` | 否 | 节点完成状态 |

富文本字段 `texts` / `notes` 是元素数组。最常见的是：

```json
[{"element_type":"text","text":{"content":"节点内容"}}]
```

### 节点图片（`nodes[].images`）

`nodes[].images` 接收的是**图片 token**，不是本地文件路径，也不是 URL。

```bash
# 先上传图片，拿到 token
lark-cli docs +media-upload --file ./image.png --parent-type mindnote_image --parent-node <mindnote_token>

# 再把 token 写进节点
lark-cli mindnotes nodes create \
  --mindnote-id "<mindnote_token>" \
  --data '{"client_token":"<client_token>","nodes":[{"node_id":"node_existing123","images":[{"token":"canonical_token"}]}]}'
```

参数说明：

| 参数 | 必填 | 说明 |
|------|------|------|
| `--file` | 是 | 本地图片路径 |
| `--parent-type` | 是 | 上传目标类型；图片使用 `mindnote_image` |
| `--parent-node` | 是 | 传 Mindnote 的 token |
| `nodes[].images[].token` | 是 | 上传后返回的图片 token |

## 推荐工作流

1. 先判断用户目标是不是“新建一个思维笔记”。
2. 如果是新建思维笔记，切到 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
3. 如果是操作已有思维笔记，先按上方「获取 `mindnote_id`」确认已拿到 Mindnote 文档 token。
4. 确认目标类型是 **Mindnote** 后，把真实 Mindnote token 作为 `--mindnote-id`。
5. 先执行 `mindnotes nodes list`，确认目标 `parent_id`。
6. 新增子节点时，在 `nodes[]` 里传 `parent_id`；更新已有节点时，在 `nodes[]` 里传已有 `node_id`。
7. 再执行 `mindnotes nodes create`。
8. 写操作优先带 `client_token`，推荐使用时间戳或 UUID，避免重试时重复创建或重复更新。

> [!CAUTION]
> `mindnotes nodes create` 是写操作。创建时确认插入位置，更新时确认 `node_id` 指向的就是目标节点。

## 参考

- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容
- [lark-doc-whiteboard](lark-doc-whiteboard.md) — 新建思维笔记走画板链路
- [lark-drive](../../lark-drive/SKILL.md) — 解析 Mindnote / Wiki 等云空间资源
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

# docs +resource-*（Docx 封面图资源）

> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

Docx 封面图不是正文里的 `<img token="...">` 素材块。读取、更新、删除文档封面图时，使用 `docs +resource-download/+resource-update/+resource-delete --type cover`，不要使用 `+media-insert` 或 `+media-download --token <cover.token>` 让用户手动拼步骤。

## 选择规则

- 用户要下载文档封面图：`docs +resource-download --type cover`
- 用户要设置/替换文档封面图：`docs +resource-update --type cover`
- 用户要删除文档封面图：`docs +resource-delete --type cover`
- 用户要下载正文图片、附件、画板缩略图：继续使用 [`docs +media-download`](lark-doc-media-download.md)

## 命令

```bash
# 下载封面图。CLI 会先读取 document.cover.token，再下载图片内容并保存到本地。
lark-cli docs +resource-download --doc doxcnXXX --type cover --output ./cover

# 使用本地文件更新封面图。
lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png

# 使用剪切板图片更新封面图。
lark-cli docs +resource-update --doc doxcnXXX --type cover --from-clipboard

# 使用 HTTPS URL 更新封面图。CLI 会先下载 URL 内容，再上传并写入 cover.token。
lark-cli docs +resource-update --doc doxcnXXX --type cover --url "https://example.com/cover.png"

# 可选：设置封面图裁切偏移。
lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png --offset-ratio-x 0.2 --offset-ratio-y 0.8

# 删除封面图；当文档本来没有封面图时也成功返回。
lark-cli docs +resource-delete --doc doxcnXXX --type cover
```

## 参数

| 命令 | 参数 | 必填 | 说明 |
|------|------|------|------|
| all | `--doc <id>` | 是 | 文档 ID、docx URL，或可解析为 docx 的 wiki URL |
| all | `--type cover` | 否 | 当前只支持 `cover`；默认值也是 `cover` |
| download | `--output <path>` | 是 | 本地保存路径；不带扩展名会根据响应类型自动补全 |
| download | `--overwrite` | 否 | 覆盖已存在的输出文件 |
| update | `--file <path>` | 三选一 | 磁盘上的真实图片文件；大于 20MiB 自动使用分片上传 |
| update | `--from-clipboard` | 三选一 | 从系统剪切板读取图片 |
| update | `--url <https-url>` | 三选一 | 从 HTTPS URL 下载图片后上传 |
| update | `--offset-ratio-x <number>` | 否 | 视图相对原图中心的横向偏移比例：水平偏移 px / 原图宽度 px；0 为居中，正数向右，负数向左 |
| update | `--offset-ratio-y <number>` | 否 | 视图相对原图中心的纵向偏移比例：垂直偏移 px / 原图高度 px；0 为居中，正数向上，负数向下 |

## 输出契约

- `+resource-download` 成功时 stdout JSON 的 `data` 包含 `document_id`、`type`、`saved_path`、`size_bytes`、`content_type`、`cover.token`。如果文档没有封面图，命令失败退出，错误包含 `document has no cover` 和脱敏 `document_id`，不会创建输出文件。
- `+resource-update` 成功时 stdout JSON 的 `data` 包含完整 `file_token` 和 `cover.token`；stderr 只打印脱敏 token。
- `+resource-delete` 成功时 stdout JSON 的 `data.deleted` 表示本次是否真的发起删除，`data.already_empty` 表示删除前是否没有封面图。空封面图是幂等成功，不报错。

## URL 来源安全边界

`+resource-update --url` 只用于下载公开 HTTPS 图片：

- 只允许 `https://`，拒绝 HTTP、空 host 和 URL userinfo。
- 拒绝解析到 private、loopback、link-local、multicast、unspecified 地址的 host。
- 最多跟随 3 次跳转，每次跳转都重新校验 URL。
- 响应 `Content-Type` 只允许 `image/png`、`image/jpeg`、`image/gif`、`image/webp`。
- 响应体最大 20MiB。

## 参考

- [lark-doc-media-download](lark-doc-media-download.md) — 下载正文素材或画板缩略图
- [lark-doc-media-insert](lark-doc-media-insert.md) — 在正文插入图片/文件
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

# `docs +script`

## 脚本列表

| `--command` | 用途 |
|-|-|
| `init-draft` | 创建带 Presentation Decision 基线的独占工作区，并预留尚不存在的 XML 路径。 |
| `parse` | 解析本地或在线文档，返回画像并检查决策与资源。 |

每个脚本只使用其小节列出的专用参数；所有脚本均可使用文末的通用参数。

## `init-draft`

### 参数

| 参数 | 必填 | 用法 |
|-|-|-|
| `--command init-draft` | 是 | 选择本脚本。 |
| `--presentation-decision` | 是 | 决策 JSON；接受内联 JSON、`@相对或绝对路径` 或 `-`（stdin）。 |

```bash
lark-cli docs +script --command init-draft \
  --presentation-decision '{}' \
  --format json
```

路径返回值与用法见 [创建工作流 Step 4](lark-doc-create-workflow.md)。

- 在生成正文前执行；不要自行创建工作目录或决策文件。CLI 固定生成 `draft_<8位十六进制字符>_folder/draft.xml`，以返回的实际路径为准。
- 决策是单个 JSON 对象；无可量化约束时传 `{}`。`audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode`、`visual_plan.reason` 和每个 block 的 `purpose` 是可选描述信息，可省略、为空字符串或 `null`；不参与通过/失败判定。
- `visual_plan`、`visual_plan.blocks`、每项的 `type` 和 `min_count` 都可省略或为 `null`，表示未设置。`blocks` 写 `[]` 也表示无数量约束；条目缺少 `type` 或 `min_count` 时，不启用该条数量校验。
- 显式填写的字段仍须合法：`visual_plan` 为对象，`blocks` 为数组，`type` 为支持的块类型，`min_count` 为正整数。空字符串类型、未知块类型、零/负数或非整数数量会报错，即使另一字段缺失也一样。仅 `type` 与 `min_count` 都有效的条目参与数量检查；启用的条目不能重复声明同一类型。兼容的 `list` 约束按 `<ul>` 与 `<ol>` 的合计数量检查。
- `word_count` 仅在需要字数校验时填写 `{min,max}`；未指定的一侧写 `null`，至少一侧为正整数，且 `min <= max`。没有字数要求时省略整个字段。
- 返回 `data.cwd`（本次文件操作的绝对工作目录）、`data.workspace`（相对工作区）、`data.draft_path`（相对 XML 路径）和操作提示 `data.tip`。工作区及其中的 `.presentation-decision.json` 已存在，XML 尚不存在；直接写入 `<cwd>/<draft_path>`，首次写入前不要读取该路径。后续 CLI 使用返回的 `cwd`；资源路径规则见 [lark-doc](../SKILL.md)。
- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；保留 `workspace` 及其中的创作草稿。

## `parse`

### 参数

| 参数 | 必填 | 用法 |
|-|-|-|
| `--command parse` | 是 | 选择本脚本。 |
| `--content` | 二选一 | 本地 XML 的字面内容、`@相对或绝对路径` 或 `-`（stdin）。 |
| `--doc` | 二选一 | 在线 Docx/Wiki URL 或 token；与 `--content` 互斥。 |
| `--presentation-decision` | 否 | 用于检查当前输入的决策 JSON；支持内联、`@相对或绝对路径` 或 `-`。 |

```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。
- 决策格式同 `init-draft`：缺失的约束不检查，显式填写但非法的值报错，合法且完整的约束参与检查。`passed` 只表示本次启用的检查通过，不代表未声明的要求已满足。
- 使用 `--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` | 查看帮助。 |

# docs +update（更新飞书云文档）

使用文本或 block 指令精确更新飞书云文档。默认使用 XML；仅在用户明确要求或必须保真 Markdown 时使用 Markdown。

写入前必须按 `--doc-format` 读取对应格式参考：`xml` 读取 [`lark-doc-xml.md`](lark-doc-xml.md)，`markdown` 读取 [`lark-doc-md.md`](lark-doc-md.md)；

## 常用示例

```bash
# 先定位内容并获取最新 block ID
lark-cli docs +fetch --doc "文档URL或token" --scope keyword --keyword "key1|key2" --detail with-ids

# 替换文本；--content "" 可删除文本
lark-cli docs +update --doc "xx" --command str_replace --pattern "旧内容" --content "新内容"

# 替换单个 block，或同父连续范围内的 block
lark-cli docs +update --doc "xx" --command block_replace --block-id blkTarget --content '<p>新段落</p>'
lark-cli docs +update --doc "xx" --command block_replace --start-block-id blkFirst --end-block-id blkLast --content '<p></p>'

lark-cli docs +update --doc "xx" --command block_insert_after --block-id blkAnchor --content '<h2>新章节</h2><p>章节内容</p>'

# 删除单个 block 或范围内的 block
lark-cli docs +update --doc "xx" --command block_delete --block-id blkA
lark-cli docs +update --doc "xx" --command block_delete --start-block-id blkFirst --end-block-id blkLast
```

## 推荐流程

1. **Observe（读取现状）**：先 `docs +fetch` 读取当前文档状态，并按意图选择最小范围。
   - 改某一节或大文档：先 `--scope outline --max-depth 2` 找章节，再 `--scope section --start-block-id <标题id> --detail with-ids`
   - 精确跨节区间：用 `--scope range --start-block-id xxx --end-block-id yyy`
   - 只有模糊关键词：用 `--scope keyword --keyword "key1|key2" --context-before 1 --context-after 1 --detail with-ids`
   - 明确整篇重构才读 `--detail with-ids` 全文；只读摘要或确认事实时用更轻的 fetch
2. **Diagnose（诊断问题）**：判断用户目标、当前结构、语气、重复、断流、事实口径和需要保留的资源；识别哪些 block 必须原样保留。
3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内文本替换用 `str_replace`，但它不支持资源替换；单个 block 用一个 `--block-id`，同一直接父节点下的连续 block 用 `--start-block-id`/`--end-block-id`。连续范围适用于 `block_replace` 和 `block_delete`。整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
4. **Patch（精确修改）**：按 block / section 执行局部命令。替换内容必须符合目标父容器的结构；例如替换列表项范围时使用 `<li>...</li>`。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
5. **Verify（fetch 验证）**：每轮写操作后按影响范围重新 fetch，检查用户要求、结构、语气、事实、资源块和 block ID 是否符合预期；不满足就基于最新 fetch 结果继续 Diagnose / Patch，不要沿用上一轮 block ID。

除非用户明确要求完全重建，或原文已无保留价值，否则不要使用 `overwrite`；它可能丢失评论和暂不支持的资源。

## 生成 block 直达链接

用户需要某个 block 的直达链接时，只定位 block，不执行文档写操作：

1. 使用局部 `docs +fetch --detail with-ids` 获取目标 `block_id`。
2. 返回 `文档基础 URL#block_id`；没有 `block_id` 时不得猜测。

## 参数

|参数|必填|说明|
|-|-|-|
|`--doc`|是|文档 URL 或 token|
|`--command`|是|更新指令，见下表|
|`--doc-format`|否|`xml`（默认）或 `markdown`|
|`--content`|视指令|写入内容；`str_replace` 传空字符串可删除文本|
|`--pattern`|视指令|`str_replace` 的简单行内匹配文本；不要用于多行、整段或多个 block|
|`--block-id`|视指令|目标 block ID；`-1` 表示文档末尾，`0` 表示文档开头（仅适用于支持这些锚点的指令）|
|`--start-block-id` / `--end-block-id`|视指令|`block_replace` / `block_delete` 的同父连续闭区间，必须成对使用，且不能与 `--block-id` 混用；`--start-block-id` 用 `0` 表示从文档开头开始，`--end-block-id` 用 `-1` 表示到文档末尾结束|
|`--src-block-ids`|视指令|要复制或移动的源 block ID，多个 ID 用逗号分隔|
|`--reference-map`|否|保留或回放既有 `reference_map`，需与 `--content` 配合；支持 JSON、任务目录内的相对 `@file` 或 stdin `-`|
|`--revision-id`|否|基准版本号，默认 `-1`（最新版本）|

## 指令速查

|指令|用途与限制|必需参数|
|-|-|-|
|`str_replace`|全文查找替换；支持富文本内的文本替换，但不支持资源替换；涉及多个 block 时建议用 `block_replace`；空 `--content` 表示删除|`--pattern`、`--content`|
|`block_insert_after`|在指定 block 后插入内容；逐章填充时指定对应标题的 block ID|`--block-id`、`--content`|
|`block_copy_insert_after`|按 ID 顺序复制源 block，源 block 不变；基础标签均支持，资源块仅支持 `img`、`source`、`whiteboard`、`sheet`、`chat_card`、`sub-page-list`，不支持 `task`、`bitable`、`base_ref`、`synced_reference`、`synced_source`、`okr`|`--block-id`、`--src-block-ids`|
|`block_replace`|替换单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--content`，以及 `--block-id` 或 `--start-block-id`+`--end-block-id`|
|`block_delete`|删除单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--block-id` 或 `--start-block-id`+`--end-block-id`|
|`block_move_after`|移动已有 block，支持所有块类型；|`--block-id`、`--src-block-ids`|
|`append`|仅在文末追加，等价于 `block_insert_after --block-id -1`|`--content`|
|`overwrite`|清空后重写全文，丢失图片、评论等内容，非必要不使用|`--content`|

## 通用安全规则

- 每次写操作后都按 block ID 已变化处理。新插入或复制的内容一定使用新 ID；替换、删除和覆盖会使旧 ID 失效；移动会改变章节与 range 语义。
- 同一 block 有多处修改时，应合并为一次 `block_replace`，避免连续使用旧 ID。

## 返回值

```json
{
  "ok": true,
  "identity": "user",
  "data": {
    "document": {
      "revision_id": 2,
      "new_blocks": [
        { "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
      ]
    },
    "result": "success",
    "updated_blocks_count": 1,
    "warnings": [],
    "tips": ""
  }
}
```

|字段|说明|
|-|-|
|`result`|`success` \| `partial_success` \| `failed`|
|`updated_blocks_count`|实际更新的 block 数量|
|`warnings`|服务端返回的警告列表；即使 `result=success` 也要检查是否存在降级或未完全处理的内容|
|`tips`|服务端返回的后续处理建议；为空表示没有额外建议，非空本身不表示更新失败|
|`document.new_blocks`|新增 block；`block_id` 用于后续编辑，资源块的 `block_token` 可交给对应 skill 继续处理|

## 需要查文档

可查看 [`+fetch`](lark-doc-fetch.md)。

# lark-doc 画板处理指南

## 两个 Skill 的职责边界

| Skill             | 核心职责                                                      | 约束                              |
|-------------------|-----------------------------------------------------------|---------------------------------|
| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单图表或复杂空白画板 | 简单图可由主 Agent 直接写入；复杂图再隔离到 SubAgent |
| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |

## 画板适用规则

写文档时，核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，如果图示能明显降低理解成本，可以规划为画板；结构简单或文字更清楚的内容不必强行画板化。

同一篇文档可以有多个画板。确有多个独立图示点时，可拆成多个聚焦画板，而不是把所有信息塞进一张大图。

## 文档与画板协同流程

### 步骤 1：识别画板机会

| 场景                      | 入口                                                        |
|-------------------------|-----------------------------------------------------------|
| 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表                                     |
| 文档中需要插入其他图表/自定义图形       | 步骤 2B: 使用 SVG 插入图表                                        |
| 已有画板需要更新内容              | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3B |
| 只查看 / 下载已有画板            | 切换至 `lark-whiteboard`，不走本流程                               |

> [!IMPORTANT]
> ⚠️ **分别对每个图表进行决策**

如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B。思维导图、时序图、类图、饼图、甘特图可插入 mermaid 块；其他类型图表使用 SVG，简单图由主 Agent 直接写入，复杂图再启动 SubAgent。

简单 Mermaid / SVG 图可由主 Agent 直接写入本地 XML；需要专门视觉设计、信息密度较高或容易布局翻车的 SVG，再启动 SubAgent 产出完整片段。

### 步骤 2A: 使用 mermaid 插入图表

```xml

<whiteboard type="mermaid">
    mermaid 代码...
</whiteboard>
```

如果 Mermaid 已在本地文件中，可写成 `<whiteboard type="mermaid" path="@./diagram.mmd"></whiteboard>`；CLI 会在写入前读取文件并展开为内联内容。

### 步骤 2B: SubAgent 使用 SVG 插入图表

主 Agent 启动 SubAgent，让它用 `docs +create` / `docs +update` 插入：

```xml

<whiteboard type="svg">
    <svg...>...
    </svg>
</whiteboard>
```

如果 SVG 已在本地文件中，可写成 `<whiteboard type="svg" path="@./diagram.svg"></whiteboard>`；PlantUML 文件同理使用 `<whiteboard type="plantuml" path="@./sequence.puml"></whiteboard>`。

Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：

- doc token、插入位置（标题 / block_id / command）
- 图表目标、受众、源段落或数据
- 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`
- SVG 必须完整自包含：包含 `<svg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源

#### 画板 SVG 设计指南

使用 SVG 插入画板时，最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
**核心心智纠正 (重要)**：

- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, *
  *这将被视为不及格！**
- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀,
  大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！

##### SVG 设计 Workflow

###### 1. 想清楚要画什么

- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构

###### 2. 写 SVG

> [!IMPORTANT]
> 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
> 操作边界约束：

- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲

###### 画板怎么处理 SVG

画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但非阴影用途的
`<filter>` / `<pattern>` / `<clipPath>` / `<mask>` 等装饰特性画板不支持（见下方⚠️）
**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**

**可识别的元素**

- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
- 阴影：`<filter>` 里放 `<feDropShadow>` 或标准 drop/inner primitive 链 (`<feGaussianBlur in="SourceAlpha">` + `<feOffset>` + `<feFlood>` + `<feComposite>` + `<feMerge>`), 会被识别成节点阴影, drop 至多 1 个, inner 至多 1 个; 其余 filter 效果不识别
- 渐变：`<linearGradient>` / `<radialGradient>` 在 `<defs>` 中定义, 通过 `fill="url(#id)"` 引用 (载体限 `<rect>` / `<circle>` / `<ellipse>` / `<polygon>` / `<path>`), 需要至少 2 个 `<stop>`, `gradientUnits` 只支持默认的 `objectBoundingBox` (不写即可)

> [!IMPORTANT]
> ⚠️ **不支持的装饰特性**

- `<pattern>` / `<clipPath>` / `<mask>` / 非阴影用途的 `<filter>` (blur / hue-rotate / 复合合成 / `flood-color=url(...)` / 多个 `<feDropShadow>` 等) → 画板不支持，**请避免使用，否则会导致画板渲染问题**
- 渐变边界：`gradientUnits="userSpaceOnUse"` / `spreadMethod="reflect|repeat"` / stops 少于 2 个 / 复杂 `gradientTransform` 会变成不可编辑图片, 视觉正确但失去可编辑性, 若无必要请沿用默认 `objectBoundingBox`

###### 3.插入后审查

插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png
图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 [
`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。

```bash
lark-cli whiteboard +export \
  --whiteboard-token "wbcnxxxxxxxx" \
  --output-type preview \
  --output ./preview.png
```

### 步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent

复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。

复杂图 SubAgent 的最小上下文：

- board_token
- 图表目标、推荐画板类型、受众
- 与图表直接相关的源段落或数据
- 要求读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，按其完整流程写入该 board_token

多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。

### 步骤 4：完成校验

- Mermaid: 确认插入的是 `<whiteboard type="mermaid">`，且内容 mermaid 语法完整
- SVG: 确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
- 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成

---

---

## 关联参考

- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)

# XML 扩展块补充说明

本文件用于补充说明 block XML 扩展能力。常用标签和通用规则见 [`lark-doc-xml.md`](lark-doc-xml.md)；后续新增其他 block 说明时可继续追加到本文件。

## 拓展标签
- `<bookmark name="示例站点" href="https://example.com"></bookmark>`
- `<button action="OpenLink" src="https://example.com">操作按钮</button>`：`action` 可为 `OpenLink`、`DuplicatePage` 或 `FollowPage`；可选 `background-color`、`src`。
- `<time expire-time="1775916000000" notify-time="1775912400000" should-notify="false">提醒</time>`：使用毫秒时间戳。
- `<sheet type="blank"/>`：创建空白表格；`<sheet sheet-id="SHEET_ID" token="SPREADSHEET_TOKEN"/>`：复制已有表格。
- `<task task-id="TASK_GUID"/>`：挂载任务，`task-id` 为任务 GUID。
- `<chat_card chat-id="CHAT_ID"/>`：挂载聊天卡片。
- `<sub-page-list/>`：子页面列表块，仅 wiki 文档可插入。


## HTML5 block

1. 写入 HTML 内容块时，把完整单文件 HTML 存为本地 `.html` 文件，XML 写 `<html5-block path="@./widget.html"/>`；已有 `data-ref` 时配合 `--reference-map @./reference-map.json`。读取时 `<html5-block data-ref="html5_1"></html5-block>` 只是占位，必须从 `document.reference_map["html5-block"]["html5_1"].data` 读取 HTML；若 entry 是 `path`，读取对应 `@./doc-fetch-resources/...html` 文件。
2. 格式如下：

```html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="use-iframe" content="true">
  <meta name="html-box-height-mode" content="auto">
  <meta name="description" content="内容摘要，会导出为 html5-block 的 alt 属性，帮助模型理解该 HTML 块的用途">
  <title></title>
</head>
<body>
  ...
</body>
</html>
```

### 布局与高度

只使用 `auto` 或 `viewport`：正文需要在文档中完整展开时使用 `auto`；内容需要在 HTML Block 内滚动或单屏呈现时使用 `viewport`。`lark-cli` 会将 HTML 原样写入 `reference_map`，不会校验该字段，因此创建或更新前必须在 `<head>` 中显式声明。

- `auto`：使用普通文档流，不给根容器设置固定高度或 `overflow: hidden`。需要固定操作区时，在业务容器上设置 CSS `height` 和 `overflow: auto`，不要把像素值写入 meta。
- `viewport`：使用 `100vh` 和内部滚动、切页或缩放，适用于游戏、幻灯片、Dashboard、canvas 编辑器。
- 页面加载后的内容追加或展开不会由 `lark-cli` 刷新高度，不要臆造相关 CLI flag。
- 文档常见可用宽度约 `820px`；根容器使用 `width: 100%`、`max-width: 100%`、`box-sizing: border-box`。

### 内容限制

- HTML 总长度上限为 500KB。不要内联大图片、Base64、字体、长 JSON/CSV 或大量 mock 数据。

## OKR block
`<okr cycle-id="CYCLE_ID"></okr>`：创建时仅支持 root-only。

OKR block 可用 XML 格式完整表达。创建前先参考 [`lark-okr`](../../lark-okr/SKILL.md) 确认可用周期；创建时只写 root-only `<okr cycle-id="..."/>` 挂载已有 OKR，不构造 Objective/KR/Progress 子树。

获取时，XML 结构示例如下：

```xml
<okr cycle-id="" cycle-name="CYCLE_NAME" user-name="USER_NAME">
  <okr-objective objective-id="OBJECTIVE_ID" status="normal" percent="80" score="75">
    <p>O 描述</p>
    <okr-progress>
      <p>O 进展</p>
      <checkbox done="true">事项</checkbox>
      <ul><li>列表项内可包含 <a href="https://example.com">链接</a></li></ul>
    </okr-progress>
    <okr-key-result key-result-id="KEY_RESULT_ID" status="risk" percent="60" score="80">
      <p>KR 描述</p>
      <okr-progress>
        <p>KR 进展</p>
      </okr-progress>
    </okr-key-result>
  </okr-objective>
</okr>
```

- `cycle-id` 仅用于创建时挂载已有当前周期 OKR；`cycle-name`、`user-name` 只读。
- `objective-id`、`key-result-id` 为只读业务 ID，更新已有 OKR 时保持不变。
- `okr-objective` / `okr-key-result`
  - 可更新 `status`、`percent`、`score`；`percent` / `score` 取值 0-100，`status` 取值 `unset`/`normal`/`risk`/`extended`。
  - 不可更新 objective 和 key-result 内容描述。
- `okr-progress` 承载进展内容，支持更新。直接子节点支持 `<p>`、`<checkbox>`、`<grid>`、`<img>`、`<source>`、`<ol>`、`<ul>`、`<h1>` 到 `<h9>`。

# 飞书 XML 语法

**语法采用类 HTML 标签，渲染采用纵向块级文档流：顶层 Block 按文档顺序纵向排列，块内支持富文本和子块嵌套。默认宽度约 820 px，宽版模式约 1020 px**

以下为 XML 语法示例，使用时需替换其中的示例值。属性必须写成 `name="value"`，禁止省略引号。

## 常用标签

- `p, h1-h9, blockquote, hr, img, b, em, u, del, br, span` 语义不变。普通文档建议只使用 `h1-h6`，`h7-h9` 仅在确需更深层级时使用。
- `<a type="url-preview" href="URL">链接标题</a>`
- `<latex>E = mc^2</latex>`：适用行内公式，也适用于上标、下标写法。
- `<ol><li>第一项<ul><li>子项</li></ul></li><li>第二项</li></ol>`：子列表放在 `<li>` 内；新增列表项必须放在 `<ul>` 或 `<ol>` 内。
- `<pre lang="go" caption="示例"><code>fmt.Println(&quot;hello&quot;)</code></pre>`：代码必须放在 `<code>` 内，禁止直接放在 `<pre>` 下；`caption` 可省略。
- `<img path="@./photo.png"/>`：上传当前工作目录内的本地图片。也可用 `<img href="URL"/>` 上传公开 HTTP(S) 网络图片，或用 `<img src="token"/>` 复制原始图片；三者任选一个，可选 `width`、`height`、`caption`、`name`。使用 `href` 时，CLI 会将远程图片转为本地资源并完成上传；响应须为 PNG、JPEG、GIF 或 WebP，单图不超过 20MiB。内部网络图片须先下载到本地再使用 `path`。
- `<source path="@./report.pdf" name="报告.pdf"/>`：上传本地附件；也可使用 `<source token="token" name="xx"/>` 复制已有附件。可独立使用、放入 `<p>` 作为行内附件，或写成 `<figure view-type="Card|Preview"><source/></figure>`；
- `<checkbox done="true|false">todo</checkbox>`
- `p, h1-h9, li, checkbox, title` 支持可选属性 `align`，可选值为 `left`、`center`、`right`，例如 `<p align="center">居中正文</p>`。

## 标题与列表编号

- 完整文档以唯一的 `<title>` 开头；正文标题使用 `<h1>` 至 `<h9>`，层级须连续，不跳级，例如 `<h1>` 后不能直接使用 `<h3>`，应先出现 `<h2>`。需要自动编号时设置 `seq="auto"`，系统会按标题层级生成并递增阿拉伯数字编号，例如一级标题为 `1`，二级标题为 `1.1`。
- 有序列表：默认属性 `seq="auto"`，需从指定数字开始时设置对应值，如 `seq="3"`。

## 表格

- `<table><thead><tr><th><p>表头</p></th></tr></thead><tbody><tr><td><p>内容</p></td></tr></tbody></table>`
- `<colgroup><col /></colgroup>` 紧跟 `<table>` 定义列宽；`width` 表示列宽，可选 `span` 表示连续作用的列数。
- `<th>` / `<td>` 支持 `background-color`、`vertical-align`、`colspan`、`rowspan`；`vertical-align`：`top | middle | bottom`；`background-color` 支持基础色相、`light-{色相}`、`medium-gray`，表头优先使用 `light-gray` 或 `medium-gray`，彩色单元格仅用于表达状态或分类。被合并的单元格不再写入。

## 扩展标签

- `<cite type="user" user-id="ou_xxx"/>`：@人，会渲染为用户头像；必须显式传入用户 `open_id`，不得用纯文本名字冒充 @人。
- `<cite type="doc" doc-id="DOC_TOKEN"/>`：@文档，会渲染为文档标题。
- `<cite type="citation"><a href="URL" url-type="N"></a></cite>`：参考文献容器，仅含多个 `<a>`。`url-type` 标识链接类型：`5`（WebURL）须在`<a></a>`中填写渲染标题；`1`（Docx）、`6`（Minutes）、`12`（Base）、`13`（Sheet）可留空。
- `<whiteboard></whiteboard>`：`type | src` 二选一。`type=blank` 为新建；`type=mermaid|plantuml|svg` 时，支持 `path=@./file` 导入，也支持在标签内直接写入内容；`src=token` 表示复制已有画板。复杂图需读取 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)；
- `<grid><column width-ratio="0.5"><p>左栏</p></column><column width-ratio="0.5"><p>右栏</p></column></grid>`：各列 `width-ratio` 之和为 1。
- `<callout emoji="💡" background-color="light-*" border-color="*"><p>高亮块内容</p></callout>`：子块仅支持 `p`、`ol`、`ul`、`checkbox`、行内标签；禁止 `<table>`、`<img>`、`<pre>`、`<hr>`、`<grid>`、`<whiteboard>`、等其他块级标签或资源块。可选 `text-color`。
- 其他扩展标签 `html5-block`、`bookmark`、`button`、`time`、`sheet`、`task`、`chat_card`、`sub-page-list`、`okr` 见 [`lark-doc-xml-extended-blocks.md`](lark-doc-xml-extended-blocks.md)。

## 颜色

颜色用于表达语义，并在全文保持一致；默认保持中性色排版，避免仅为装饰而着色。

- **合法值**：色相为 `red, orange, yellow, green, blue, purple, gray`；`text-color`、`border-color` 使用基础色相；`<span>`、`<th>`、`<td>`、`<button>` 背景支持基础色相、`light-{色相}`、`medium-gray`；高亮块背景支持 `gray`、`light-{色相}`、`medium-{色相}`。
- **高亮块**：默认使用 `light-*` 背景和默认文字色；强提醒才使用 `medium-*`，彩色文字只强调短语。
- **表格**：表头优先使用 `light-gray` 或 `medium-gray`；彩色单元格只表达状态或分类，避免整表铺色。

## 转义规则

禁止转义标签本身；只转义标签内部的文本内容。

- 文本转义：`<` → `&lt;`，`>` → `&gt;`，`&` → `&amp;`，换行符 `\n` → `<br/>`。
- 错误：`&lt;p&gt;内容&lt;/p&gt;`
- 正确：`<p>A &amp; B 的对比：1 &lt; 2</p>`

---
name: lark-doc
description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；`/page/<token>` 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。"
metadata:
  requires:
    bins: ["lark-cli"]
    skills: ["lark-shared"]
  cliHelp: "lark-cli docs --help;lark-cli mindnotes --help"
---

# docs

## 场景与 Shortcut 路由

**CRITICAL：先判断场景，再读取该场景的参考文件；不要在任务开始时一次性读取全部参考文件。每个文件只在首次进入对应阶段时读取一次。**

**身份：文档操作推荐显式指定 `--as user`。**

**本地文件引用统一遵循文件访问权限：CWD 内优先使用 `@./相对路径`，其他目录使用 `@绝对路径`。XML 内的相对资源路径先查 CWD；仅文件不存在时再查源 XML 文件所在目录，同名文件以 CWD 为准。内联内容、stdin、在线文档没有源文件目录，不执行回退。**

### 文档内容

- **读取 / 摘要 — [`+fetch`](references/lark-doc-fetch.md)**：先读参考再获取文档。
- **从零创作 — [`创建工作流`](references/lark-doc-create-workflow.md)**：先完整执行创建工作流，**简单任务不是跳过的理由**；
- **导入 / 空文档 — [`+create`](references/lark-doc-create.md)**：仅创建空文档或原样导入用户提供的完整内容时，跳过创建工作流。
- **编辑 / block 直达链接 — [`+update`](references/lark-doc-update.md)**：语义改写、润色、重组、补写或排版均按 update 参考完成。

### 辅助能力

- **草稿初始化、解析与统计 — [`+script`](references/lark-doc-script.md)**：支持解析文档 URL / token 与本地 XML，统计字数并返回字符诊断；不支持 Markdown 输入。
- **历史版本 — [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md)**：查询、回滚文档历史版本或检查回滚任务状态。

### 资源、画板与思维笔记

- **插入本地素材 — [`+media-insert`](references/lark-doc-media-insert.md)**：在文末插入本地图片或文件。
- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档或评论中的图片、附件或素材。
- **下载素材 — [`+media-download`](references/lark-doc-media-download.md)**：下载文档中的图片、附件、素材或画板缩略图。
- **Docx 封面 — [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md)**：下载、更新或删除 Docx 封面。
- **画板 — [`画板工作流`](references/lark-doc-whiteboard.md)**：创建或更新画板时先读取工作流；更新已有画板必须复用现有 token，禁止新建空白画板；使用 [`whiteboard +update`](../lark-whiteboard/references/lark-whiteboard-update.md) 写入。
- **思维笔记 — `mindnotes`**：已有思维笔记走 [`思维笔记链路`](references/lark-doc-mindnote.md)；新建思维笔记走 [`lark-doc-whiteboard`](references/lark-doc-whiteboard.md)。

### 认证与 Scope

执行 Shortcut 时，不预读 [`lark-shared`](../lark-shared/SKILL.md) 或预跑 `auth status --verify`；仅遇到未认证、token / 身份或 scope 错误时读取该 Skill，修复后重试。认证、身份或 scope 管理请求则直接使用该 Skill。

## 不在本 Skill 范围

- **Drive 文件级操作**：找文档、导入导出、云空间文件上传 / 下载 / 权限管理 → [`lark-drive`](../lark-drive/SKILL.md)。复制文档、创建副本或另存为副本时，按其指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文。
- **独立评论操作**：添加、分页查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)；只需紧凑评论上下文时，直接使用默认 JSON 响应的 `docs +fetch`。