feishu-integration

# Feishu Integration

> CLI: `./feishu <module> <command> [options]`
> Parameter details: `references/cli_reference.md`

## Auth

Check: `./feishu auth status`. Token **auto-refreshes** on any API call — no manual refresh needed.

If no credentials exist, guide user through first-use setup:
1. Create app at [飞书开放平台](https://open.feishu.cn/app) → 自建应用
2. 全选开通用户权限; add redirect `http://localhost:9876/callback`; publish
3. `export FEISHU_APP_ID="<id>" FEISHU_APP_SECRET="<secret>"` → `./feishu auth login`

## Intent → Command

### Task

| Intent | Command |
|---|---|
| 查任务 / 未完成 | `task list [--completed false]` |
| 建任务 | `task create --summary "..." [--due ISO8601] [--members "Name1,Name2"]` |
| 完成任务 | `task list --keyword "..." → task complete --task-id ID` |
| 改截止 / 去掉截止 | `task update --task-id ID --due ISO8601` / `--clear-due` |
| 建清单/Sprint | `task tasklist-create --name "..."`, then `task batch-create` |
| 评论 | `task comment --task-id ID --content "..."` |

`task list` defaults to **Markdown table** (状态/标题/截止/负责人). Use `--format json` for raw data.

### Document

| Intent | Command |
|---|---|
| 浏览文件 | `doc list` or `doc tree` |
| 搜索+读取 | `doc read-raw --name "keyword"` |
| **全文搜索** | `doc search-content --query "退款"` |
| **搜索+自动读取** | `doc search-content --query "库存" --read` |
| **按类型过滤搜索** | `doc search-content --query "数据" --type docx,wiki` |
| 从 MD 创建 | `doc create-from-markdown --file path.md` |
| 追加内容 | `doc append-markdown --document-id ID --file content.md` |
| 清理 | `doc list` → `doc trash --token TOKEN` |
| 共享 | `doc shared-add --url "..."` (user provides URL) |
| **导出为 Markdown** | `doc export --document-id TOKEN --output path.md` |
| **导出含图片** | `doc export --document-id TOKEN --images` |
| **按名称导出** | `doc export --name "方案"` |

#### Batch Upload with Cross-Document Linking

When uploading a directory where an index (e.g., README.md) has relative `.md` links:
1. Create target folder in Drive
2. Upload child docs first via `doc create-from-markdown` → capture `{filename: feishu_url}` map
3. Replace relative links in index with Feishu URLs
4. Upload processed index

#### Markdown → Feishu Notes

Auto-handled by `create-from-markdown`:
- CJK table columns: 2x width for proportional sizing
- Relative links `[text](file.md)` → plain text (Feishu only supports HTTP links)
- Code blocks, headings, lists, quotes, dividers, todos: fully supported

### Wiki

| Intent | Command |
|---|---|
| 看知识库 | `wiki space-list` → `wiki tree --space-id ID` |
| 读页面 | `wiki node-read --token TOKEN` |
| 发方案到 wiki | `wiki create-from-markdown --space-id ID --file path.md` |
| **搜索知识库** | `wiki search --query "关键词"` |
| **搜索+读取** | `wiki search --query "退款" --read` |
| **搜索指定空间** | `wiki search --query "退款" --space-id ID` |
| **导出 Wiki(含图片)** | `wiki export --url "https://xxx.feishu.cn/wiki/TOKEN"` |
| **导出(仅文本)** | `wiki export --token TOKEN --no-images` |

### Message

| Intent | Command |
|---|---|
| 发消息到群 | `msg send --chat-id oc_xxx --text "消息内容"` |
| 发消息给个人 | `msg send --user "张三" --text "消息内容"` |
| 发卡片消息 | `msg send --chat-id oc_xxx --card card.json` |
| 查看群列表 | `msg chats` |
| 按名称找群 | `msg chats --name "产品"` |
| 查看群详情 | `msg chat-info --chat-id oc_xxx` |
| 查看消息记录 | `msg history --chat-id oc_xxx [--count 20]` |
| **发富文本消息** | `msg send --chat-id oc_xxx --post "内容" --title "标题"` |

### Approval (审批)

| Intent | Command |
|---|---|
| 查看审批模板 | `approval list-definitions` |
| 查看模板详情 | `approval get-definition --code CODE` |
| 创建审批 | `approval create --code CODE --form '{...}'` |
| 查看审批详情 | `approval get --instance-id ID` |
| 列出审批实例 | `approval list --code CODE [--status PENDING]` |
| 同意审批 | `approval approve --instance-id ID --task-id TID` |
| 拒绝审批 | `approval reject --instance-id ID --task-id TID --comment "理由"` |
| 撤销审批 | `approval cancel --instance-id ID` |

### Bitable

| Intent | Command |
|---|---|
| 看表格数据 | `bitable list-tables` → `bitable list-records --json` |
| **按条件筛选** | `bitable list-records --filter 'CurrentValue.[status]="active"'` |
| 导出 | `bitable export --format csv --output path.csv` |
| 写入/更新 | `bitable create-record` / `bitable update-record` |
| 批量 | `bitable batch-create --file records.json` (auto-chunks at 500) |

### Member

| Intent | Command |
|---|---|
| 找人 | `member find --name "keyword"` (substring match) |
| 我是谁 | `member whoami` |

## Output Formatting

`task list` defaults to table output. All other commands output JSON.

Agent should transform JSON for user when applicable:
- **Doc list** → numbered list with name, type, date
- **Bitable records** → Markdown table matching field names
- **Member lookup** → inline: "张三 → ou_xxxxx"

Include `url` field as clickable link when present.

## Error Recovery

| Code | Meaning | Action |
|---|---|---|
| 99991663 | Token expired | Auto-handled by engine. If persists: `auth refresh` |
| 99991679 | Scope missing | Auto-handled by incremental auth. If persists: `auth relogin` |
| 100003 | Permission denied | User enables scope in console → `auth relogin` |
| 1470400 | Invalid param | Check format (URLs need `http://`/`https://`) |
| Member not found | — | `member scan` to refresh cache, retry shorter keyword |

## Key Behaviors

- **Member resolution**: Names auto-resolve to `open_id` via local cache (`~/.agents/data/feishu/members.json`, 7d TTL). Substring match on name/en_name.
- **Auto-assign**: `task create` assigns current user unless `--no-assign`
- **Agent badge**: Created tasks show "🤖 Agent" origin in Feishu UI
- **Date clearing**: Use `--clear-due`/`--clear-start` (not timestamp=0)
- **Shared folders**: API can't discover — user must provide URL via `doc shared-add`
- **Retry**: Built-in 429/5xx auto-retry (max 3, exponential backoff)

## Structure

```
feishu-integration/
├── feishu                ← CLI entry (bash)
├── SKILL.md              ← This file
├── scripts/
│   ├── feishu_api.py     ← Core (auth + HTTP + retry + pagination + media download)
│   ├── auth.py           ← OAuth2 (login/refresh/relogin/incremental)
│   ├── task.py           ← Task v2 (table + JSON output)
│   ├── docx.py           ← Document & Drive (+ full-text search + export with images)
│   ├── wiki.py           ← Knowledge base (+ wiki export)
│   ├── bitable.py        ← Bitable (多维表格)
│   ├── msg.py            ← Messaging (send/chats/history + rich-text post)
│   ├── approval.py       ← Approval (审批: create/get/list/approve/reject)
│   └── members.py        ← Member directory (scan/cache/resolve/reverse-resolve)
├── evals/
│   └── evals.json        ← Test cases
└── references/
    └── cli_reference.md  ← Full parameter reference
```