feishu-doc-reviewer

为智能体提供飞书文档读写能力：导出全文、读取评论与段落、写回修改并回复评论。

Security Scan

The skill's behavior (reads/writes Feishu documents and requires Feishu credentials) matches its description, but the package/registry metadata omits required environment variables and the skill runs code that can modify documents — this mismatch and the write capability warrant caution.

Purpose & Capability

The name/description (Feishu doc read/write, comment handling, delete/modify blocks) aligns with the included code (feishu_api, comment processors, MCP server). However, the registry metadata lists no required env vars or primary credential while the code clearly requires FEISHU_APP_ID and FEISHU_APP_SECRET to function. This is an incoherence between claimed requirements and actual needs.

Instruction Scope

SKILL.md and scripts consistently instruct the agent to fetch comments, read block content, update/delete text, reply and resolve comments via the Feishu API. The runtime instructions and code only reference Feishu APIs and local .env config; they do not attempt to read unrelated system paths or exfiltrate to third-party endpoints. The instructions do require running a local MCP server or CLI which will give the agent programmatic ability to perform write operations on documents.

Install Mechanism

There is no network download/install of arbitrary binaries. Dependencies are standard Python packages listed in requirements.txt (requests, python-dotenv, mcp). The skill is instruction+code only and instructs pip installing those dependencies — no high-risk install URLs or extracted archives detected.

Credentials

The skill needs Feishu credentials (FEISHU_APP_ID and FEISHU_APP_SECRET) and optionally FEISHU_BASE_URL in .env to obtain tenant_access_token and act on documents. The registry metadata incorrectly lists no required env vars or primary credential — this omission is misleading. The requested secrets are necessary for the described functionality, but the metadata mismatch and presence of a .env file in the repo are concerning from an operational/visibility standpoint.

Persistence & Privilege

always:false (good). The skill exposes autonomous-invocable tools (MCP) that can perform destructive write operations (update/delete block, delete selected text) when given credentials. Autonomous invocation is normal for skills, but because these tools modify user documents, the operator should ensure least-privilege credentials and explicit confirmation before the agent performs write actions.

What to consider before installing

This skill appears to do what it claims — read comments and modify Feishu docs — and includes the necessary code. However: (1) the package/registry metadata omits required environment variables; you must provide FEISHU_APP_ID and FEISHU_APP_SECRET (and optionally FEISHU_BASE_URL) in a .env or environment for it to work. (2) The skill will be able to modify and delete document content and post replies once given valid credentials — grant only a dedicated app with the minimum permissions needed, and add the app only to documents you trust. (3) Review the code yourself (feishu_api.py, process_comment.py, mcp_server.py) before running; running the MCP server gives the agent programmatic write access. (4) Prefer using an app with limited scope/tenant and test on non-production documents first. The metadata omission is an indicator of sloppy packaging (or incomplete registry data) rather than overt malice, but you should proceed cautiously.

飞书文档 AI 自动审阅与修改

本技能为 Claude Code / OpenClaw 等智能体提供飞书文档的读写工具，便于在对话中基于全文上下文与批注要求完成修改并写回。

核心能力

• 获取评论: 自动提取文档中未解决的评论，支持按关键词筛选。
• 读取原文: 获取评论对应段落内容，或导出全文 Markdown 供理解上下文。
• 写回修改: 直接通过 API 更新文档段落内容。
• 删除段落:
  • delete_block: 清空整个块内容
  • delete_text_from_block: 只删除选中的文本（保留块中其他内容）⭐
• 结果反馈: 在评论区回复修改结果，并标记为 [AI-DONE]。
• 智能识别: 自动从评论 quote 中识别对应的块 ID。

使用方法

MCP 协议 (Claude / OpenClaw)

在对话中，您可以直接下达指令，例如：

"请审阅文档 doxcnABC123，只处理包含'格式错误'的评论，并将修改后的语气调整为正式商务风格。"

推荐用法：让 Claude Code 自己推理（无需外部 LLM 配置）

在 Claude Code / OpenClaw 的对话过程中，通常希望由宿主模型完成"怎么改"的推理，本技能只负责"读/写飞书"。

可用的原子工具：

• get_comments(document_token): 获取评论列表
• get_block(document_id, block_id): 获取指定块的文本内容
• update_block(document_id, block_id, new_text): 更新块内容
• delete_block(document_id, block_id): 清空整个块内容
• delete_text_from_block(document_id, block_id, text_to_delete): 只删除块中选中的文本⭐
• reply_comment(file_token, comment_id, content): 回复评论
• resolve_comment(file_token, comment_id): 标记评论为已解决

CLI 工具

技能提供命令行工具，可直接处理评论：

cd /path/to/.openclaw/workspace/skills/feishu-doc-reviewer

# ⭐ 推荐：只删除批注选中的内容（保留块中其他内容）
python3 process_comment.py <document_token> <comment_id> --action delete_selected

# 删除整个段落（清空块）
python3 process_comment.py <document_token> <comment_id> --action delete

# 修改段落内容
python3 process_comment.py <document_token> <comment_id> --action modify --new-content "新内容"

# 仅回复评论（自定义处理）
python3 process_comment.py <document_token> <comment_id> --action custom

# 指定块 ID（不传则自动识别）
python3 process_comment.py <document_token> <comment_id> --block-id doxcnXXX

源代码结构

核心代码位于 src/ 目录下：

• src/feishu_api.py: 飞书接口层，封装了认证、获取评论、读取/更新/删除文档块等 API 调用。
• src/config.py: 配置管理，读取环境变量。
• process_comment.py: 评论处理工具，实现评论处理的完整流程（获取评论→处理块→回复→标记解决）。

配置要求

请确保项目根目录下的 .env 文件包含以下配置：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx

依赖安装

使用 pip 安装所需依赖：

pip install -r requirements.txt

API 说明

delete_block vs delete_text_from_block

方法	功能	使用场景
delete_block	清空整个块内容	整个段落都需要删除
delete_text_from_block	只删除块中选中的文本	只删除批注选中的部分，保留块中其他内容 ⭐

delete_text_from_block 实现说明：

1. 首先获取块的当前内容
2. 从评论的 quote 字段获取要删除的文本
3. 从块内容中移除该文本
4. 用 PATCH 更新块

# 只删除选中的文本
result = api.delete_text_from_block(document_id, block_id, text_to_delete)
if result.get("ok"):
    print(f"删除后内容：{result.get('new_content')}")

resolve_comment 注意事项

必须使用 PATCH 方法，使用 PUT 会返回 404。

# 正确 ✅
response = requests.patch(url, headers=headers, json={"is_solved": True})

# 错误 ❌
response = requests.put(url, headers=headers, json={"is_solved": True})  # 返回 404

常见问题

Q: 为什么删除块返回 403 或 404？

A: 可能的原因：

1. 应用缺少 docx:document:write 权限 → 在飞书开放平台添加权限
2. 使用了错误的 API 路径 → 使用 PATCH 而非 DELETE
3. Token 过期 → 重新获取 tenant_access_token

Q: 如何识别评论对应的块 ID？

A: process_comment.py 工具已实现自动识别逻辑：

1. 从评论的 quote 字段获取选中的文本
2. 遍历文档块，匹配内容
3. 返回匹配的块 ID

如果自动识别失败，可以手动指定 --block-id。

Q: delete_selected 和 delete 有什么区别？

A:

• delete_selected（推荐）：只删除批注选中的文本，保留块中其他内容
• delete：清空整个块内容

例如，如果一个块包含 A+B+C 三段内容，批注只选中了 B：

• delete_selected → 删除 B，保留 A+C
• delete → 删除 A+B+C（整个块清空）