---
name: lark_docx_update_as_bot
version: 1.0.0
description: "飞书文档正文Bot身份写入技能，使用 lark-cli docs +update --api-version v2 --as bot 更新文档正文内容，补齐「读文档→读内嵌Sheet→回填文档正文」全链路Bot身份闭环"
metadata:
  requires:
    permissions: ["docx:document", "docx:document:write_only"]
---

# lark_docx_update_as_bot 技能规范

## 核心规则（强制执行）
1. **身份限制**：所有文档正文更新操作**永远使用Bot身份**执行（`--as bot`），绝对不触发任何用户身份授权弹窗
2. **文档范围限制**：支持知识库文档（`/wiki/`）和个人文档（`/doc/`），前提是Bot有对应文档的编辑权限
3. **权限告知规则**：
   - Bot无权限编辑目标文档：回复「当前Bot无编辑该文档权限，请将Bot应用（App ID: `cli_a931175d41799cc7`）添加为文档协作者并授予编辑权限后重试」
   - 权限不足时提示需要开通的权限：`docx:document` 或 `docx:document:write_only`

## 适用场景
- 将润色后的台词/文本回填到文档正文段落
- 更新文档中的配置说明、备注等文本内容
- 批量替换文档中的特定文本
- 在文档中追加新章节/段落
- 所有需要Bot身份修改文档正文的操作

## 前置条件
- Bot应用已在飞书开发者后台开通 `docx:document` 权限
- Bot已被添加为目标文档的协作者（至少「可编辑」权限）

## 完整执行链路

### 步骤1：获取文档内容和 block 结构
先用 `lark_wiki_operate_as_bot` 或 `lark-cli docs +fetch --api-version v2 --as bot` 获取文档内容，定位需要修改的文本/block。

```bash
# 读取文档（获取 block_id 用于精确编辑）
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +fetch --api-version v2 --doc "<doc_token>" --as bot
```

### 步骤2：执行更新

#### 方式A：str_replace — 全文文本查找替换（推荐，无需 block_id）

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +update --api-version v2 --doc "<doc_token>" --as bot \
  --command str_replace \
  --pattern "要替换的原文" \
  --content "替换后的新文本"
```

**Markdown 模式（支持跨行匹配 + 省略号语法）：**

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +update --api-version v2 --doc "<doc_token>" --as bot \
  --command str_replace \
  --doc-format markdown \
  --pattern "开头文本...结尾文本" \
  --content "替换后的完整内容"
```

#### 方式B：block_replace — 替换指定 block（需先获取 block_id）

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +update --api-version v2 --doc "<doc_token>" --as bot \
  --command block_replace \
  --block-id "blkcnXXXX" \
  --content '<p>替换后的段落内容</p>'
```

#### 方式C：append — 在文档末尾追加

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +update --api-version v2 --doc "<doc_token>" --as bot \
  --command append \
  --content '<h2>新章节</h2><p>追加的内容</p>'
```

#### 方式D：block_insert_after — 在指定 block 后插入

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +update --api-version v2 --doc "<doc_token>" --as bot \
  --command block_insert_after \
  --block-id "blkcnXXXX" \
  --content '<p>插入的内容</p>'
```

### 步骤3：验证更新结果

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaoyan \
  lark-cli docs +fetch --api-version v2 --doc "<doc_token>" --as bot
```

## 指令速查表

| 指令 | 说明 | 必需参数 | 适用场景 |
|------|------|----------|----------|
| `str_replace` | 全文文本查找替换 | `--pattern` `--content` | 回填润色文本、修正错别字 |
| `block_replace` | 替换指定 block | `--block-id` `--content` | 替换整段内容 |
| `block_insert_after` | 在指定 block 后插入 | `--block-id` `--content` | 插入新段落 |
| `append` | 文档末尾追加 | `--content` | 追加新章节 |
| `block_delete` | 删除指定 block | `--block-id` | 删除废弃内容 |
| `overwrite` | ⚠️ 全文覆盖 | `--content` | 完全重建文档（慎用） |

## 最佳实践

1. **优先 str_replace**：回填润色文本等场景，直接用 str_replace 匹配原文替换，无需获取 block_id
2. **Markdown 模式跨行匹配**：需要替换大段内容时，用 `--doc-format markdown` + `前缀...后缀` 省略号语法
3. **精确操作优于全文覆盖**：避免使用 `overwrite`，会丢失图片、评论等
4. **保护不可重建内容**：替换时避开包含图片、画板、电子表格 token 的 block
5. **写入后必须验证**：每次更新后回读确认内容正确

## 与其他技能的配合

| 场景 | 技能链路 |
|------|----------|
| 读文档 → 读内嵌Sheet → 回填正文 | `lark_wiki_operate_as_bot` → `feishu-embedded-sheet` → **本技能** |
| 读文档 → 修改正文 | `lark_wiki_operate_as_bot` → **本技能** |
| 读文档 → 读内嵌Sheet → 写Sheet | `lark_wiki_operate_as_bot` → `feishu-embedded-sheet` |

## 异常处理

| 错误码 | 含义 | 处理方式 |
|--------|------|---------|
| `99991400` | 频率限制 | 等待后重试，使用指数退避 |
| `429` | 并发编辑限制 | 同一文档每秒最多3次编辑，排队重试 |
| `403` | 无权限 | Bot未被添加为文档协作者，需用户授权 |
| `400` | 参数错误 | 检查 doc_token、block_id、pattern 格式 |
| `404` | 文档/block不存在 | 检查 token 是否正确，block 是否已被删除 |
