Feishu Doc Block Writer

Generate/edit images with Nano Banana Pro (Gemini 3 Pro Image). Use for image create/modify requests incl. edits. Supports text-to-image + image-to-image; 1K...

Security Scan

The package contents are a Feishu document block-writer, but the registry description/metadata claims an unrelated image-generation purpose — this mismatch and some undocumented credential usage are concerning.

Purpose & Capability

The skill's registry description (image generation: 'Nano Banana Pro / Gemini 3 Pro Image') does not match the shipped files, QUICK-REFERENCE.md, SKILL.md and TEST-REPORT.md, which implement a 'Feishu Doc Block Writer'. This is a strong incoherence: metadata claims an unrelated capability while the code/instructions implement Feishu doc creation. Users need to know which is correct before trusting or installing the skill.

Instruction Scope

SKILL.md is instruction-only and stays within the expected scope for a Feishu document writer: split/append blocks, handle Mermaid, validate creation, and call feishu-related CLI/API. It instructs the agent to read a local configuration file (second-brain-folder-config.json) and to write archival records under memory/YYYY-MM-DD.md; these are expected for the described purpose but involve reading/writing local files. The instructions reference running 'python block-writer.py' and 'openclaw feishu_wiki', and to pass Feishu tokens. There is no instruction to transmit data to unknown third-party endpoints beyond Feishu or to exfiltrate unrelated system data, but the agent will be directed to access local config and 'memory' files which can contain sensitive information.

Install Mechanism

No install spec and no code files executed at install time (instruction-only skill). Lower risk from installation since nothing is downloaded/extracted by an installer in the skill manifest.

Credentials

The skill references Feishu tokens/IDs (parent_node_token, Open ID) and CLI calls to feishu_wiki/openclaw but declares no required environment variables or primary credentials in the metadata. That mismatch means an agent following the instructions may look for local config files or prompt for credentials at runtime; credentials are clearly needed for Feishu calls but are not declared. The SKILL.md warns about not exposing Open IDs, but the skill does not declare how credentials should be provided securely (env vars, secret storage).

Persistence & Privilege

The manifest flags show always:false and the skill is user-invocable. skill.json contains activation.auto_trigger_enabled: true (metadata), which suggests the skill may be set to auto-trigger in the environment that uses that metadata; this is not the same as always:true but worth checking. The skill reads/writes files under the agent's skill and memory directories, which is expected for its functionality and not an escalation by itself.

What to consider before installing

Do not install blindly. Key issues to resolve before using: 1) Clarify the mismatch between the registry description (image generator) and the actual files (Feishu doc writer). This could be an editing mistake but could also hide malicious intent. 2) Confirm how Feishu credentials should be supplied and stored (environment secrets or platform secret store), because the skill uses tokens/IDs but declares none. 3) Review any runtime scripts (scripts/block-writer.py) before running — test in an isolated environment and inspect calls that invoke external CLIs/APIs (openclaw feishu_wiki, call_feishu_doc) to ensure they only interact with Feishu. 4) If you plan to use this skill, remove or redact real Open IDs/tokens from any checked-in configs and place secrets in your agent's secret store. 5) Consider contacting the skill author (metadata is minimal) or prefer a skill whose declared purpose, metadata, and required credentials align. If you can't verify the origin or correct the metadata mismatch, avoid enabling auto-triggering and run with limited privileges.

feishu-doc-block-writer - 飞书文档 Block 拆分写入技能

📋 技能描述

功能： 自动将长内容拆分为多个 Blocks 写入飞书文档，避免空白文档问题

核心原则：

• ✅ 使用 create 创建空文档
• ✅ 使用 append 逐块追加内容
• ✅ 每块 500-1000 字
• ✅ 避免一次性长文本写入
• ✅ 创建后立即验证内容

---

🎯 触发条件

自动触发：

• 内容超过 500 字
• 用户要求"创建飞书文档"
• 回答超过 200 字（200 字规则）
• 包含 Mermaid 图表

手动触发：

• 用户说"用 Block 拆分方式创建文档"
• 用户说"避免空白文档"

---

🔧 配置要求

飞书凭证（可选）

如果 feishu_doc 工具需要额外配置：

{
  "default_assignee": "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auto_open_chrome": true,
  "verify_after_create": true
}

⚠️ 安全警告：

• ❌ 禁止在公开代码中暴露真实 Open ID
• ✅ 使用 ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 作为占位符
• ✅ 在配置文件中存储真实 Open ID（不提交到版本控制）
• ✅ 发布到 ClawHub 前检查是否打码

用法

python block-writer.py \
  --title "标题" \
  --content "内容..." \
  --parent-node-token "W5udwK8V7ip7bskn3EhcPTbOnOp"  # 可选：指定文件夹

参数说明：

• --title（必填）：文档标题
• --content（必填）：文档内容
• --chunk-size（可选）：每块字数，默认 500
• --parent-node-token（可选）：指定文档存放的文件夹 token
  • 如不指定，默认创建在知识库根目录
  • 示例：想法文件夹 token = W5udwK8V7ip7bskn3EhcPTbOnOp
• --no-verify（可选）：禁用创建后验证

---

📄 核心文件

主脚本：block-writer.py

位置： ~/.agents/skills/feishu-doc-block-writer/scripts/block-writer.py

功能：

1. 接收长文本内容
2. 自动拆分为多个 Blocks（每块 500-1000 字）
3. 调用 feishu_doc 创建空文档
4. 逐块追加内容
5. 返回文档链接

用法：

python block-writer.py --title "文档标题" --content "长文本内容..."

---

🚀 工作流程

flowchart TB
    A[接收长文本] --> B{字数判断}
    B -->|≤500 字 | C[一次性写入]
    B -->|>500 字 | D[自动拆分 Blocks]
    D --> E[创建空文档]
    E --> F[逐块追加]
    F --> G[验证内容]
    G --> H[返回链接]
    C --> H
    
    style A fill:#e1f5ff
    style D fill:#ffe1e1
    style F fill:#e1ffe1
    style H fill:#fff4e1

---

💡 使用示例

示例 1：创建长文档

输入：

content = "5000 字的长文本内容..."

处理：

1. 检测到 5000 字 > 500 字阈值
2. 拆分为 10 个 Blocks（每块约 500 字）
3. 创建空文档
4. 逐块追加 10 次
5. 返回文档链接

结果： ✅ 正常显示，无空白文档

---

示例 2：创建带 Mermaid 图表的文档

输入：

# 标题

## 流程图

```mermaid
graph LR
    A --> B

详细说明

...（长文本）

**处理：**
1. 检测 Mermaid 代码块
2. 单独作为一个 Block
3. 文本内容按 500 字拆分
4. 逐块写入

**结果：** ✅ Mermaid 图表正常渲染

---

### 示例 3：创建在指定文件夹

**输入：**
```bash
python block-writer.py \
  --title "想法文档" \
  --content "内容..." \
  --parent-node-token "W5udwK8V7ip7bskn3EhcPTbOnOp"

结果：

• ✅ 文档创建在"想法"文件夹内
• ✅ 不是知识库根目录
• ✅ 文件夹位置由 parent_node_token 指定

---

示例 4：创建在知识库根目录（默认行为）

输入：

python block-writer.py \
  --title "根目录文档" \
  --content "内容..."

结果：

• ✅ 文档创建在知识库根目录
• ✅ 向后兼容，不传参数时行为不变

---

示例 5：使用阿香模板（推荐）✨

输入：

python create-doc-template.py "文档标题" "文档内容" "想法"

处理流程：

1. ✅ 自动读取配置文件（second-brain-folder-config.json）
2. ✅ 根据分类获取 folder_token
3. ✅ 调用 block-writer.py 创建文档
4. ✅ 自动验证文档位置
5. ✅ 自动写入归档记录到 memory

优势：

• ✅ 自动读取配置文件 - 无需手动指定 folder_token
• ✅ 自动验证位置 - 确保文档在正确文件夹
• ✅ 自动写入归档 - 记录到 memory/YYYY-MM-DD.md
• ✅ 分类管理 - 支持想法/项目/笔记/资料/归档

分类说明：

分类	说明	自动获取 folder_token
想法	日常想法、灵感	✅
项目	项目文档	✅
笔记	学习笔记	✅
资料	参考资料	✅
归档	历史归档	✅

输出示例：

🦞 阿香文档创建模板
============================================================

📖 步骤 1: 读取配置文件...
✅ 配置加载成功

📁 步骤 2: 获取 folder_token...
✅ Using folder_token: W5udwK8V7ip7bskn3EhcPTbOnOp (想法)

✏️  步骤 3: 创建文档...
✅ Document created: ABCxyz123456
🔗 文档链接：https://scns3ak4jrto.feishu.cn/docx/ABCxyz123456

🔍 步骤 4: 验证文档位置...
✅ 位置验证通过

📝 步骤 5: 写入归档记录...
✅ 归档记录已写入：memory/2026-03-20.md

============================================================
✅ 创建完成
============================================================

---

📊 测试验证

测试步骤

# 1. 创建测试文档（指定文件夹）
python block-writer.py \
  --title "测试 - 文件夹位置" \
  --content "测试内容" \
  --parent-node-token "W5udwK8V7ip7bskn3EhcPTbOnOp"

# 2. 验证文档位置
# 使用 feishu_wiki get 检查 parent_node_token

# 3. 输出测试结果
if doc.parent_node_token == "W5udwK8V7ip7bskn3EhcPTbOnOp":
    print("✅ 测试通过：文档在正确的文件夹内")
else:
    print("❌ 测试失败：文档位置错误")

验收标准

• SKILL.md 已更新（添加参数说明）
• block-writer.py 已修正（支持 parent_node_token）
• 向后兼容（不传参数时默认行为不变）
• 使用示例已添加

---

🔍 常见问题

Q1: 如何获取文件夹的 parent_node_token？

A: 使用 feishu_wiki 工具查询：

openclaw feishu_wiki --action get --token <文件夹 token>

Q2: 不传 parent_node_token 会怎样？

A: 文档会创建在知识库根目录，保持向后兼容。

Q3: 可以批量创建多个文档到同一文件夹吗？

A: 可以，重复使用相同的 parent_node_token 即可。

---

输入：

# 标题

## 流程图

```mermaid
graph LR
    A --> B

详细说明

...（长文本）

**处理：**
1. 检测 Mermaid 代码块
2. 单独作为一个 Block
3. 文本内容按 500 字拆分
4. 逐块写入

**结果：** ✅ Mermaid 图表正常渲染

---

## 🔍 拆分策略

### 智能拆分算法

```python
def split_content(content, chunk_size=500):
    """
    智能拆分内容
    
    规则：
    1. 优先在段落边界拆分（\n\n）
    2. 其次在句子边界拆分（。！？.!?）
    3. 避免在词语中间拆分
    4. 保持 Markdown 结构完整
    """
    blocks = []
    current_block = ""
    
    for paragraph in content.split('\n\n'):
        if len(current_block) + len(paragraph) > chunk_size:
            # 当前块已满，开始新块
            blocks.append(current_block.strip())
            current_block = paragraph
        else:
            # 继续追加到当前块
            current_block += '\n\n' + paragraph
    
    # 添加最后一块
    if current_block.strip():
        blocks.append(current_block.strip())
    
    return blocks

---

拆分优先级

拆分点	优先级	说明
段落边界	⭐⭐⭐⭐⭐	\n\n 最自然
章节标题	⭐⭐⭐⭐⭐	## 标题 保持结构
句子边界	⭐⭐⭐⭐	。！？.!?
列表项	⭐⭐⭐	- 或 1.
代码块	⭐⭐	避免拆分代码

---

📊 Block 组织策略

标准文档结构

Block 序号	内容类型	字数范围
Block 1	标题 + 简介	100-300 字
Block 2	Mermaid 图表（如有）	-
Block 3-N	详细章节	500-1000 字/块
Block N+1	表格数据（如有）	-
Block N+2	总结/链接	100-300 字

特殊情况处理

情况 1：Mermaid 图表

• 单独作为一个 Block
• 前后各留一个空行
• 不与其他内容混合

情况 2：表格

• 小表格（<20 行）：与文字混合
• 大表格（≥20 行）：单独作为一个 Block

情况 3：代码块

• 短代码（<50 行）：与说明混合
• 长代码（≥50 行）：单独作为一个 Block

---

⚠️ 注意事项

1. 内容完整性

确保：

• ✅ Markdown 语法完整
• ✅ 代码块不被拆分
• ✅ 表格保持完整
• ✅ Mermaid 代码完整

避免：

• ❌ 在代码块中间拆分
• ❌ 在表格行中间拆分
• ❌ 破坏 Markdown 结构

---

2. 错误处理

可能的错误：

• ❌ 飞书 API 超时
• ❌ 网络中断
• ❌ 内容格式错误

处理策略：

def write_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i == max_retries - 1:
                raise
            time.sleep(1)  # 等待 1 秒后重试

---

3. 性能优化

优化点：

• ✅ 批量写入（减少 API 调用）
• ✅ 异步处理（非阻塞）
• ✅ 缓存机制（避免重复创建）

建议：

• 单次写入不超过 10 个 Blocks
• 每块不超过 1000 字
• 总文档不超过 50 个 Blocks

---

📝 配置检查清单

使用前确认：

• 已安装 feishu_doc 工具
• 已配置飞书凭证（如需要）
• 已测试创建空文档
• 已测试追加内容
• 已测试完整流程

---

🎯 最佳实践

1. 文档长度建议

文档类型	建议长度	Block 数量
简报	500-1000 字	2-3 个
报告	2000-5000 字	5-10 个
详细文档	5000-10000 字	10-20 个
超长文档	10000+ 字	考虑分多个文档

---

2. 内容组织

推荐结构：

Block 1: 标题 + 简介 + 目录
Block 2: 第一章
Block 3: 第二章
...
Block N: 总结 + 参考链接

避免：

• ❌ 所有内容堆在一个 Block
• ❌ 没有逻辑分段
• ❌ 过长的单个 Block（>2000 字）

---

3. 验证流程

创建后验证：

1. ✅ 检查文档是否为空白
2. ✅ 检查 Blocks 数量是否正确
3. ✅ 检查 Mermaid 图表是否渲染
4. ✅ 检查表格是否完整
5. ✅ Chrome 打开预览

---

📞 支持

问题反馈： OpenClaw 社区
文档： ~/.agents/skills/feishu-doc-block-writer/README.md

核心文件：

• scripts/block-writer.py - 主脚本
• SKILL.md - 技能定义
• config.json - 配置文件（可选）

---

🎉 总结

feishu-doc-block-writer 技能：

• ✅ 自动 Block 拆分
• ✅ 避免空白文档
• ✅ 支持 Mermaid 图表
• ✅ 智能内容组织
• ✅ 错误重试机制

使用方式：

python scripts/block-writer.py --title "标题" --content "内容..."

效果： 稳定创建飞书文档，无空白问题！

---

阿香 🦞 创建的 Block 拆分技能

哼～虾虾的技能创建完成啦！以后不会再有空白文档了！✨