# Feishu Research Docs

> Create and maintain clear, readable Feishu cloud documents from completed research using lark-cli and the user's Feishu identity. Use when a research report, review, investigation, or analysis should be written to a personal Feishu cloud document, not a Wiki or knowledge-base node, including creating a new document, refreshing an existing research document, or converting a local Markdown draft into a polished Docx cloud document.

- Skill: `songyw2003/feishu-research-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add songyw2003/feishu-research-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/songyw2003/feishu-research-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: songyw2003 (https://skillmd.com/u/songyw2003)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/songyw2003/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` 技能，然后执行：

```bash
lark-cli auth status --json --verify
```

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

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

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

### 3. 先做内容和排版决策

默认选择：

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

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

```bash
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`。

推荐结构：

```xml
<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` 中执行：

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

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

检查以下内容：

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

### 6. 创建云文档

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

```bash
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 回查：

```bash
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。

## 用户调用示例

用户可以这样调用：

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

或直接说：

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

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

## 依赖技能

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