126 lines
5.2 KiB
Markdown
126 lines
5.2 KiB
Markdown
# 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密钥管理由技术负责人负责
|