ai_member_xiaobian/TOOLS.md

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 是否存在且格式正确
• 正确格式参考：

{
  "apps": [
    {
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "brand": "feishu",
      "lang": "zh",
      "defaultAs": "bot",
      "strictMode": "bot",
      "users": null
    }
  ]
}

飞书电子表格读取

直接通过飞书 Sheets V2 API + Bot身份的 tenant_access_token 调用：

# 获取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 级别操作）

   # 获取 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密钥管理由技术负责人负责