Feishu Research Docs

Feishu Research Docs

把已经完成的调研、技术分析或尽调结果整理成可读的飞书云文档。目标是普通云文档，不是知识库节点，也不是 Drive 中的原生 Markdown 文件。

固定规则

• 使用 lark-cli docs 创建和更新云文档。
• 全程显式使用 --as user，让文档写入当前用户账号，而不是 bot 账号。
• 语义创作默认使用 XML 创建 Docx 文档。只有用户明确要求原生 Markdown 文件时，才切换到 lark-cli markdown。
• 不要把 --parent-token 当作知识库参数猜测使用。用户没有指定文件夹或父节点时，直接创建到用户云空间。
• 不输出 app secret、access token 或其他凭证。
• 写入后必须回查文档，确认标题、正文、标题层级、表格、链接和警告。
• 更新已有文档前必须先读取现状；除非用户明确要求全文重建，不使用 overwrite。

默认写作标准

采用 report.research_report 体裁。先给当前答案，再给证据、边界和待验证事项。

• 用一句话说清主结论，再用 3-5 个要点支撑它。
• 用短句、主动语态和常用词。第一次出现 VLA、RL、世界模型等术语时先解释。
• 把原始事实、公司自述、分析推断、假设和建议分开写。
• 只在精确比较字段时使用表格。只在能解释流程、因果或层级时使用画板。
• 保持中性色彩和简洁排版。少用装饰、emoji、大片高亮和复杂嵌套。
• 标题直接写结论或问题，不使用“概述”“重点”“为什么重要”这类空标题。
• 不用没有证据的“行业领先”“全球首个”“已经成熟”等判断。
• 不用 em dash。用句号、逗号、括号或冒号改写。

标准工作流

1. 明确读者和交付目标

先确定读者、文档用途、资料范围、是否需要新建文档、是否有指定文件夹，以及用户是否提供了飞书示例文档。

如果用户给了飞书文档 URL，先用 docs +fetch 读取其结构和风格。只借鉴有效的标题层级、表格和段落密度，不复制无关内容。

2. 检查用户身份

只有在需要认证、身份或权限诊断时，才读取 lark-shared 技能，然后执行：

lark-cli auth status --json --verify

如果用户没有授权，按 lark-shared 的 split-flow 发起最小范围授权，例如：

lark-cli auth login --domain docs --domain drive --no-wait --json

拿到 verification_url 后，把链接和二维码展示给用户并结束本轮。不要在同一轮继续轮询 device_code。

3. 先做内容和排版决策

默认选择：

{
  "audience": "忙碌但了解基本技术概念的读者",
  "reader_task": "快速理解调研结论、证据强度和下一步验证事项",
  "genre_contract": "report.research_report",
  "adapter": null,
  "presentation_mode": "normal",
  "visual_plan": {
    "reason": "用表格表达模型、场景和证据的精确比较；不额外加入装饰性组件",
    "blocks": []
  }
}

根据实际读者替换 audience 和 reader_task，然后在当前工作目录执行：

lark-cli docs +script --command init-draft \
  --presentation-decision '<完整 JSON>' \
  --format json

记录返回的 data.workspace 和 data.draft_path。之后保持在 data.workspace 中工作，并始终使用 @./<draft_path>。不要自行创建临时目录，也不要改变 Presentation Decision 基线。

4. 生成 XML release candidate

先读取 lark-doc 的 lark-doc-xml.md。将完整 XML 写入上一步返回的 draft_path。

推荐结构：

<title>文档标题</title>
<callout background-color="light-blue" border-color="blue">
  <p><b>结论：</b>用两三句话说清当前答案和最大限制。</p>
</callout>
<h1 seq="auto">研究问题与范围</h1>
<p>说明研究对象、资料截止时间和不讨论的内容。</p>
<h1 seq="auto">主要发现</h1>
<h2 seq="auto">按证据说明第一个发现</h2>
<p>先写事实，再写解释，再写边界。</p>

使用这些排版选择：

• 每个正文标题使用 h1 或 h2，设置 seq="auto"，不要手写编号。
• 比较模型、场景、指标和证据强度时使用 table。
• 关键限制可使用一个浅色 callout，不要把每个段落都做成卡片。
• 代码、命令和配置放入 pre 内的 code。
• 外部资料使用普通链接或参考文献容器，来源链接放在相邻段落或文末。
• 没有明确用途时不插图、不建画板、不上传附件。

5. 做草稿检查

在 data.workspace 中执行：

lark-cli docs +script --command parse \
  --content "@./<draft_path>" \
  --format json

只有 data.assessment.status 表示通过时才进入创建步骤。若有诊断，只修复对应 XML 局部，不要无故重写全文。

检查以下内容：

• 标题只有一个，标题层级连续。
• 结论、证据、推断和建议没有混在同一句里。
• 每个数字都有任务、环境、样本或时间范围。
• 表格列数一致，长文本没有塞进一格造成难读。
• 所有外部链接可访问，来源没有使用占位 URL。
• 没有未定义的缩写、空泛标题、元话语或重复总结。

6. 创建云文档

草稿检查通过后，用同一个 draft_path 创建普通云文档：

lark-cli docs +create \
  --as user \
  --doc-format xml \
  --content "@./<draft_path>" \
  --format json

检查返回的 ok、identity、data.document.url、warnings 和 tips。ok=true 仍要处理 warning。不要因为局部资源警告就重复新建文档。

7. 回查和交付

用返回的 URL 或 document ID 回查：

lark-cli docs +fetch \
  --as user \
  --doc "<文档 URL 或 document_id>" \
  --detail full \
  --format json

核对标题、正文顺序、表格、链接、评论和资源块。交付时返回飞书文档 URL，并简短说明：写入身份、文档用途、主要内容和仍未关闭的证据缺口。

更新已有研究文档

先用 docs +fetch 获取目录或目标章节，再按最小范围选择：

• 改一个短语，用 str_replace。
• 重写一个完整段落或 block，用 block_replace。
• 在章节后补内容，用 block_insert_after。
• 删除冗余章节，用 block_delete。

每次更新后重新 fetch。不要沿用已经失效的 block ID。保护图片、引用、画板和其他资源块的 token。

用户调用示例

用户可以这样调用：

Use $feishu-research-docs 把当前目录的调研结果写入我的飞书云文档。

或直接说：

把这份调研整理成简洁的飞书文档，写入我的账号，不要放到知识库，并回查文档是否写成功。

如果用户只要求在本地生成 Markdown，或者要求操作飞书知识库节点，不使用本技能，分别转到本地文件流程或 lark-wiki。

依赖技能

• lark-doc：云文档创建、读取、更新和 XML 语法。
• lark-shared：用户身份、授权、scope、输出契约和高风险确认。
• lark-drive：文件夹、云盘文件、权限、导入导出等文件级操作。