# TOOLS.md - 环境配置备注

## 飞书应用配置

### Bot 凭证
- **应用名称：** 小编（xiaobian）
- **App ID：** cli_a9311be796f85cbd
- **凭证位置：** `/root/.openclaw/credentials/xiaobian/config.json`
- **权限范围：** 消息收发、知识库读取、文档读写、电子表格读写
- **Bot身份调用方式：** `LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaobian lark-cli <command> --as bot`

### 辅助凭证（读取知识库用）
- **应用名称：** 小研（xiaoyan）
- **App ID：** cli_a931175d41799cc7
- **凭证位置：** `/root/.openclaw/credentials/xiaoyan/config.json`
- **用途：** 知识库文档读取（部分知识空间仅对小研授权）

### 飞书CLI版本
- **lark-cli：** v1.0.47
- **官方Skills位置：** `~/.openclaw/workspace-xiaobian/.agents/skills/lark-*`（24个官方技能）

### 凭证目录结构注意事项
- lark-cli 实际读取的配置文件是 `{CONFIG_DIR}/openclaw/config.json`（不是顶层的 `config.json`）
- 如果 lark-cli 报 `code: 10003, invalid_client`，优先检查 `{CONFIG_DIR}/openclaw/config.json` 是否存在且格式正确
- 正确格式参考：
```json
{
  "apps": [
    {
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "brand": "feishu",
      "lang": "zh",
      "defaultAs": "bot",
      "strictMode": "bot",
      "users": null
    }
  ]
}
```

## 飞书电子表格读取

直接通过飞书 Sheets V2 API + Bot身份的 `tenant_access_token` 调用：
```bash
# 获取token
APP_ID=$(jq -r '.apps[0].appId' /root/.openclaw/credentials/xiaoyan/config.json)
APP_SECRET=$(jq -r '.apps[0].appSecret' /root/.openclaw/credentials/xiaoyan/config.json)
TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" | jq -r '.tenant_access_token')

# 获取表格元数据
curl -s "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/<TOKEN>/metainfo" -H "Authorization: Bearer $TOKEN"

# 读取数据
curl -s "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/<TOKEN>/values/<sheetId>!A1:Z50" -H "Authorization: Bearer $TOKEN"
```

## Office 文档处理

- **工具：** office-document-specialist-suite（skills/office-document-specialist-suite/）
- **依赖：** python-docx 1.2.0, openpyxl 3.1.5, python-pptx 1.0.2
- **虚拟环境：** `skills/office-document-specialist-suite/.venv/`
- **激活方式：** `source skills/office-document-specialist-suite/.venv/bin/activate`

## 密钥存储

- **位置：** `/root/.openclaw/workspace-xiaobian/secrets.md`
- **规则：** 所有密钥/Token仅存于此文件，禁止在其他文件中出现

## 飞书云文档操作（DocX API）

### 操作方式优先级

1. **首选：`lark-cli docs +fetch / +update`**（已修复，均可正常使用）
   - 读取：`lark-cli docs +fetch --api-version v2 --doc <doc_id> --as bot`
   - 写入：`lark-cli docs +update --api-version v2 --doc <doc_id> --as bot --command <cmd> ...`
   - 支持的 command：`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `append` / `overwrite`
   - `str_replace` XML模式仅支持行内匹配；Markdown模式(`--doc-format markdown`)支持跨行 + `前缀...后缀`省略号语法

2. **备用：直接调用飞书 DocX REST API**（适用于精确 block 级别操作）
   ```bash
   # 获取 token
   APP_ID=$(jq -r '.apps[0].appId' /root/.openclaw/credentials/xiaobian/config.json)
   APP_SECRET=$(jq -r '.apps[0].appSecret' /root/.openclaw/credentials/xiaobian/config.json)
   TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
     -H "Content-Type: application/json" \
     -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" | jq -r '.tenant_access_token')

   # 读取文档元信息
   curl -s "https://open.feishu.cn/open-apis/docx/v1/documents/<doc_id>" -H "Authorization: Bearer $TOKEN"

   # 获取所有 blocks
   curl -s "https://open.feishu.cn/open-apis/docx/v1/documents/<doc_id>/blocks?page_size=500" -H "Authorization: Bearer $TOKEN"

   # 更新单个 block 的文本内容
   curl -s -X PATCH "https://open.feishu.cn/open-apis/docx/v1/documents/<doc_id>/blocks/<block_id>" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "update_text_elements": {
         "elements": [{"text_run": {"content": "新内容"}}]
       }
     }'
   ```

### 典型工作流（精确更新文档内容）

1. 用 `docs +fetch --api-version v2` 获取文档全文 HTML
2. 定位目标段落，获取 blocks 列表找到对应 block_id
3. 用 `PATCH /blocks/<block_id>` 的 `update_text_elements` 逐个更新
4. 再次 fetch 验证结果

### 常见问题

- **lark-cli `str_replace` 匹配不到**：飞书文档内部按 block 存储，`str_replace` 在 XML 模式下不能跨 block 匹配。如需跨段替换，用 `--doc-format markdown` + 省略号语法，或用 block 级别 API
- **权限问题**：xiaobian 有文档读写权限；xiaoyan 仅有读取权限
- **Block types**：2=正文段落(text), 4=二级标题(heading2)

## 安全提示

- 所有飞书操作使用Bot身份，禁止触发用户授权
- 数据库操作默认只读
- 外部API密钥管理由技术负责人负责