Feishu Power Skill

  - requests
  - pyyaml
---

# Feishu Power Skill

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

## 安装

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

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

## 模块

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

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

```bash
# 批量创建记录
python3 scripts/bitable_engine.py batch-create --app <app_token> --table <table_id> --data records.json

# 批量更新
python3 scripts/bitable_engine.py batch-update --app <app_token> --table <table_id> --data updates.json

# 跨表 JOIN（两张表按字段关联）
python3 scripts/bitable_engine.py join --app <app_token> --left <table1> --right <table2> --on "字段名"

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

# 统计摘要
python3 scripts/bitable_engine.py stats --app <app_token> --table <table_id>

# CSV 导入
python3 scripts/bitable_engine.py import-csv --app <app_token> --table <table_id> --file data.csv
```

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

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

```bash
# 从 Bitable 数据 + 模板 → 飞书文档
python3 scripts/doc_workflow.py generate \
  --app <app_token> --table <table_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 <app_token> --table <table_id>
```

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

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

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

```bash
# 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 <app_token> --sales-table <table_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 配置任务列表，自动跟踪执行状态。

```bash
# 运行所有到期任务
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 <token> --table <id> --template <path> --publish
```

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

```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：

```python
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` — 内置测试表，可用于验证功能。