Feishu Power Skill

让 AI agent 像飞书重度用户一样操作飞书。不只是读写文档，而是跨文档工作流 + 多维表格自动化 + 智能报告生成 + 零售运营审计。

安装

# 自动安装（推荐）
bash install.sh

# 手动安装
pip install requests pyyaml
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx

模块

1. Bitable 自动化引擎 (bitable_engine.py)

多维表格的瑞士军刀：批量读写、跨表 JOIN、快照备份、统计分析。

# 批量创建记录
python3 scripts/bitable_engine.py batch-create --app \x3Capp_token> --table \x3Ctable_id> --data records.json

# 批量更新
python3 scripts/bitable_engine.py batch-update --app \x3Capp_token> --table \x3Ctable_id> --data updates.json

# 跨表 JOIN（两张表按字段关联）
python3 scripts/bitable_engine.py join --app \x3Capp_token> --left \x3Ctable1> --right \x3Ctable2> --on "字段名"

# 数据快照（备份当前状态）
python3 scripts/bitable_engine.py snapshot --app \x3Capp_token> --table \x3Ctable_id> --output snapshots/

# 统计摘要
python3 scripts/bitable_engine.py stats --app \x3Capp_token> --table \x3Ctable_id>

# CSV 导入
python3 scripts/bitable_engine.py import-csv --app \x3Capp_token> --table \x3Ctable_id> --file data.csv

2. 文档工作流引擎 (doc_workflow.py)

Bitable 数据 + 模板 → 飞书文档，一步到位。

# 从 Bitable 数据 + 模板 → 飞书文档
python3 scripts/doc_workflow.py generate \
  --app \x3Capp_token> --table \x3Ctable_id> \
  --template templates/data_summary.md \
  --title "周报标题" \
  --group-by "分类字段" \
  --local output.md

# 纯模板渲染（不创建飞书文档）
python3 scripts/doc_workflow.py render --template templates/weekly_report.md --context data.json

# 提取 Bitable 上下文（调试用）
python3 scripts/doc_workflow.py context --app \x3Capp_token> --table \x3Ctable_id>

模板语法：

• {{变量}} — 简单替换（支持中文字段名、点号路径如 {{门店.名称}}）
• {{#each 列表}}...{{/each}} — 循环
• {{#if 条件}}...{{/if}} — 条件
• 内置变量：{{TODAY}} {{YESTERDAY}} {{WEEK_START}} {{WEEK_END}} {{NOW}}

3. 零售运营审计引擎 (retail_audit.py)

YAML 配置化审计规则，门店健康评分，异常自动诊断。

# Demo 模式（50家模拟门店，快速体验）
python3 scripts/retail_audit.py demo --output report.md
python3 scripts/retail_audit.py demo --publish  # 直接发布到飞书

# 从 Bitable 真实数据审计
python3 scripts/retail_audit.py audit \
  --app \x3Capp_token> --sales-table \x3Ctable_id> \
  --config configs/retail_default.yaml \
  --publish

# 查看可用行业配置
python3 scripts/retail_audit.py list-configs

审计规则（YAML 配置化，可按行业切换）：

• 售罄率过高/过低
• 目标达成率不足
• 负库存 / 零销售
• 库存周转过慢
• 动销率过低

内置配置：configs/retail_default.yaml（服装）、configs/fmcg.yaml（快消）。复制一份改阈值即可适配其他行业。

4. 定时报告生成器 (report_generator.py)

调度引擎：支持日/周/月频率，YAML 配置任务列表，自动跟踪执行状态。

# 运行所有到期任务
python3 scripts/report_generator.py run --schedule configs/schedule.yaml

# 运行指定任务
python3 scripts/report_generator.py run --schedule configs/schedule.yaml --job daily_audit

# 强制运行（忽略调度时间）
python3 scripts/report_generator.py run --schedule configs/schedule.yaml --job daily_audit --force

# 列出所有任务及状态
python3 scripts/report_generator.py list --schedule configs/schedule.yaml

# 单次审计报告（不需要调度配置）
python3 scripts/report_generator.py audit --demo --output report.md

# 单次模板报告
python3 scripts/report_generator.py template --app \x3Ctoken> --table \x3Cid> --template \x3Cpath> --publish

调度配置示例（configs/schedule.yaml）：

jobs:
  - id: daily_audit
    name: 每日门店审计
    type: audit
    enabled: true
    schedule:
      frequency: daily    # daily / weekly / monthly
      time: "09:00"
    params:
      app_token: YOUR_APP_TOKEN
      sales_table: YOUR_TABLE_ID
      config: retail_default.yaml
      publish: true

支持的报告类型：audit（审计报告）、template（模板报告）。

5. API 封装层 (feishu_api.py)

Token 自动管理 + Bitable / Docx / Wiki / Drive 全覆盖。其他模块的底层依赖。

也可以在 Python 中直接 import：

import sys; sys.path.insert(0, "scripts")
import feishu_api as api
records = api.bitable_list_all_records(app_token, table_id)

项目结构

feishu-power-skill/
├── SKILL.md                 # OpenClaw 入口
├── CLAUDE.md                # Claude Code 入口
├── README.md                # GitHub README
├── install.sh               # 安装脚本
├── scripts/
│   ├── feishu_api.py        # 飞书 API 封装
│   ├── bitable_engine.py    # 多维表格引擎
│   ├── doc_workflow.py      # 文档工作流
│   ├── retail_audit.py      # 零售审计引擎
│   └── report_generator.py  # 定时报告生成器
├── templates/               # 文档模板
│   ├── weekly_report.md
│   └── data_summary.md
└── configs/                 # 配置文件
    ├── retail_default.yaml  # 服装行业审计规则
    ├── fmcg.yaml            # 快消行业审计规则
    └── schedule.yaml        # 报告调度配置

依赖

• Python 3.11+
• requests, pyyaml
• 飞书应用凭证（通过 FEISHU_APP_ID / FEISHU_APP_SECRET 环境变量）

测试 Bitable

J2ehbrIvwaM4XXsjoeQckftAnNe — 内置测试表，可用于验证功能。