feishu-assistant

Feishu アシスタント

作者：43 COLLEGE 凯寓 (KAIYU) 制作 バージョン：v2.0

Feishu Open API を通じて、メッセージ、ドキュメント、ナレッジベース、カレンダー、グループチャット、多次元テーブル、メールなどの操作を実現します。 2 つの実行モードをサポートしています：lark-cli がある場合は自動プロキシ（設定不要）、app_secret がある場合は API に直接接続（より高速）。

初回設定

コマンド実行時に config.json が見つからない、または app_id が空であるというエラーが発生した場合は、このディレクトリ内の SETUP.md を読み、その手順に従ってユーザーの設定を完了させてください。

クイックスタート

同僚にメッセージを送信する

1. scripts/config.json の team_members フィールド（名前 → open_id のマッピング）を読み取ります
2. 対象の同僚の open_id を探します
3. send-message コマンドを実行します

python3 scripts/feishu_client.py send-message --type text --content "消息内容" --receive_id "ou_xxx" --receive_id_type open_id

グループにメッセージを送信する

1. scripts/config.json の default_chat_id を読み取ります
2. receive_id_type を chat_id に変更します

python3 scripts/feishu_client.py send-message --type text --content "消息内容" --receive_id "oc_xxx" --receive_id_type chat_id

重要：メッセージを送信する前に、config.json の team_members から対象の同僚の open_id を検索してください。

プラットフォームの説明（クロスプラットフォーム互換）

Python コマンド：macOS/Linux では python3、Windows では python を使用します。呼び出す前にどちらが利用可能かを検出してください。

パスの形式：

• macOS/Linux：~/.claude/skills/feishu-assistant/
• Windows：%USERPROFILE%\.claude\skills\feishu-assistant\

すべてのコマンドは python3 scripts/feishu_client.py <command>（macOS/Linux）または python scripts\feishu_client.py <command>（Windows）で呼び出します。 実行前に必ずこの skill のルートディレクトリに cd してください。

主要コマンド

メッセージ

# 发送文本消息（支持 text/post/interactive/image）
python3 scripts/feishu_client.py send-message --type text --content "内容" --receive_id "ou_xxx" --receive_id_type open_id

# 向群组发消息
python3 scripts/feishu_client.py send-message --type text --content "内容" --receive_id "oc_xxx" --receive_id_type chat_id

# 读取群消息
python3 scripts/feishu_client.py get-chat-messages --chat_id "oc_xxx" --page_size 20

グループチャット管理

# 创建群聊并拉入成员（members 为逗号分隔的 open_id）
python3 scripts/feishu_client.py create-chat --name "项目群" --members "ou_xxx,ou_yyy" --description "项目讨论群"

# 向已有群添加成员
python3 scripts/feishu_client.py add-chat-members --chat_id "oc_xxx" --members "ou_xxx,ou_yyy"

# 从群中移除成员
python3 scripts/feishu_client.py remove-chat-members --chat_id "oc_xxx" --members "ou_xxx"

# 获取群聊信息
python3 scripts/feishu_client.py get-chat-info --chat_id "oc_xxx"

# 修改群聊信息
python3 scripts/feishu_client.py update-chat --chat_id "oc_xxx" --name "新群名" --description "新描述"

# 列出群聊成员
python3 scripts/feishu_client.py list-chat-members --chat_id "oc_xxx"

# 解散群聊（不可恢复）
python3 scripts/feishu_client.py dissolve-chat --chat_id "oc_xxx"

ドキュメント

# 创建文档
python3 scripts/feishu_client.py create-doc --title "标题" --content "内容"

# 更新文档
python3 scripts/feishu_client.py update-doc --doc_token "doxcxxx" --content "新内容"

ナレッジベース

# 列出所有知识库空间
python3 scripts/feishu_client.py list-wiki-spaces

# 列出空间下的文章
python3 scripts/feishu_client.py list-wiki-nodes --space_id "xxx" --page_size 50

# 读取文章纯文本内容
python3 scripts/feishu_client.py read-wiki-node --node_token "xxx"

連絡先と組織

# 显示团队通讯录（从缓存读取）
python3 scripts/feishu_client.py show-contacts

# 刷新通讯录缓存
python3 scripts/feishu_client.py refresh-contacts

# 显示知识库列表
python3 scripts/feishu_client.py show-spaces

# 刷新知识库缓存
python3 scripts/feishu_client.py refresh-spaces

# 显示组织信息
python3 scripts/feishu_client.py show-org

# 通过邮箱查用户
python3 scripts/feishu_client.py get-user --email "[email protected]"

ファイルアップロード

python3 scripts/feishu_client.py upload-file --file_path "path/to/file.pdf" --parent_node "fldxxx"

カレンダー

# 查看我的日历列表
python3 scripts/feishu_client.py list-calendars

# 查看指定时间范围内的日程
python3 scripts/feishu_client.py list-events --calendar_id primary --start_time "2026-03-02 00:00" --end_time "2026-03-08 23:59"

# 创建日程
python3 scripts/feishu_client.py create-event --summary "周会" --start_time "2026-03-05 14:00" --end_time "2026-03-05 15:00" --description "每周例会" --attendees "ou_xxx,ou_yyy"

# 查看日程详情
python3 scripts/feishu_client.py get-event --calendar_id primary --event_id "xxx"

# 修改日程
python3 scripts/feishu_client.py update-event --calendar_id primary --event_id "xxx" --summary "新标题"

# 删除日程
python3 scripts/feishu_client.py delete-event --calendar_id primary --event_id "xxx"

# 查询忙闲信息（查自己）
python3 scripts/feishu_client.py query-freebusy --start_time "2026-03-29" --end_time "2026-03-30"

# 查询指定同事的忙闲信息
python3 scripts/feishu_client.py query-freebusy --start_time "2026-03-29 09:00" --end_time "2026-03-29 18:00" --user_id "ou_xxx"

# 推荐多人共同空闲时段（自动查询所有参会人的忙闲，计算交集）
python3 scripts/feishu_client.py suggest-meeting-time --start_time "2026-03-31 09:00" --end_time "2026-03-31 18:00" --attendees "ou_xxx,ou_yyy" --duration 30

空き時間照会 vs 空き時間提案：

• query-freebusy：1 人のビジー時間帯リスト（RSVP ステータスを含む）を照会し、時間のみを返して予定の詳細は返しません
• suggest-meeting-time：複数人を照会し、共通の空き時間を自動計算し、最大 5 件の推奨時間帯を返します

タスク管理

# 创建任务
python3 scripts/feishu_client.py create-task --summary "完成周报" --due "2026-03-31 18:00" --description "整理本周工作内容"

# 创建无截止时间的简单任务
python3 scripts/feishu_client.py create-task --summary "回复客户邮件"

# 查看我的任务列表
python3 scripts/feishu_client.py list-tasks --page_size 20

# 获取任务详情
python3 scripts/feishu_client.py get-task --task_id "xxx"

# 更新任务标题或描述
python3 scripts/feishu_client.py update-task --task_id "xxx" --summary "新标题" --description "新描述"

# 标记任务为已完成
python3 scripts/feishu_client.py complete-task --task_id "xxx"

# 或通过 update-task 标记完成
python3 scripts/feishu_client.py update-task --task_id "xxx" --completed

説明：タスク管理は Feishu Task v2 API を使用し、ユーザー認証（user_token）が必要です。complete-task は update-task --completed のショートカットです。

スプレッドシート（Sheets）

# 创建电子表格
python3 scripts/feishu_client.py create-sheet --title "销售数据"

# 读取表格数据（token 从表格 URL 提取）
python3 scripts/feishu_client.py read-sheet --token "shtcnXXX" --range "Sheet1!A1:C10"

# 写入数据（二维数组 JSON）
python3 scripts/feishu_client.py write-sheet --token "shtcnXXX" --range "Sheet1!A1" --values '[["姓名","分数"],["张三","95"]]'

# 追加数据到表格末尾
python3 scripts/feishu_client.py append-sheet --token "shtcnXXX" --range "Sheet1" --values '[["李四","88"]]'

token の取得方法：スプレッドシートの URL から抽出します。形式は https://xxx.feishu.cn/sheets/{token} です

多次元テーブルとの違い：スプレッドシート（Sheets）は従来の行列表形式で、シンプルなデータ入力や計算に適しています。多次元テーブル（Base）は構造化データベースで、フィールドタイプ、ビュー、リレーションなどの高度な機能をサポートします。

多次元テーブル（Base）

# 列出数据表
python3 scripts/feishu_client.py list-base-tables --app_token "bascnXXX"

# 列出字段
python3 scripts/feishu_client.py list-base-fields --app_token "bascnXXX" --table_id "tblXXX"

# 列出记录
python3 scripts/feishu_client.py list-base-records --app_token "bascnXXX" --table_id "tblXXX" --page_size 50

# 获取单条记录
python3 scripts/feishu_client.py get-base-record --app_token "bascnXXX" --table_id "tblXXX" --record_id "recXXX"

# 创建记录（fields 为 JSON）
python3 scripts/feishu_client.py create-base-record --app_token "bascnXXX" --table_id "tblXXX" --fields '{"名称":"测试","状态":"进行中"}'

# 批量创建记录
python3 scripts/feishu_client.py batch-create-base-records --app_token "bascnXXX" --table_id "tblXXX" --records '[{"名称":"A"},{"名称":"B"}]'

# 更新记录
python3 scripts/feishu_client.py update-base-record --app_token "bascnXXX" --table_id "tblXXX" --record_id "recXXX" --fields '{"状态":"已完成"}'

# 删除记录
python3 scripts/feishu_client.py delete-base-record --app_token "bascnXXX" --table_id "tblXXX" --record_id "recXXX"

# 创建数据表
python3 scripts/feishu_client.py create-base-table --app_token "bascnXXX" --name "新表"

# 创建字段（field_type: 1=文本, 2=数字, 3=单选, 4=多选, 5=日期, 7=复选框, 11=人员, 15=超链接, 17=附件）
python3 scripts/feishu_client.py create-base-field --app_token "bascnXXX" --table_id "tblXXX" --field_name "优先级" --field_type 3

app_token の取得方法：多次元テーブルの URL から抽出します。形式は https://xxx.feishu.cn/base/{app_token} です

メール（Mail）

# 获取当前用户邮箱地址
python3 scripts/feishu_client.py mail-profile

# 查看收件箱
python3 scripts/feishu_client.py list-mail --folder INBOX --page_size 20

# 查看已发送
python3 scripts/feishu_client.py list-mail --folder SENT

# 读取邮件
python3 scripts/feishu_client.py read-mail --message_id "xxx"

# 搜索邮件
python3 scripts/feishu_client.py search-mail --query "关键词"

# 发送邮件（默认 HTML 格式）
python3 scripts/feishu_client.py send-mail --to "[email protected]" --subject "标题" --body "<p>正文</p>"

# 发送纯文本 / 多收件人 / 带抄送
python3 scripts/feishu_client.py send-mail --to "[email protected],[email protected]" --cc "[email protected]" --subject "标题" --body "正文" --plain_text

# 创建草稿（不发送）
python3 scripts/feishu_client.py draft-mail --to "[email protected]" --subject "标题" --body "正文"

重要：メールを送信する前に、必ず宛先と内容を確認してください。

初期化

「初回設定」の章および SETUP.md を参照してください。

キャッシュの説明

• 連絡先：scripts/cache/contacts.json、形式 [{"name": "张三", "open_id": "ou_xxx", ...}]
• ナレッジベース一覧：scripts/cache/wiki_spaces.json、形式 [{"name": "空间名", "space_id": "xxx", ...}]
• デフォルトのグループチャット ID：scripts/config.json の default_chat_id
• team_members：scripts/config.json の team_members（名前 → open_id のマッピング）

キャッシュが存在しない場合は、refresh-contacts または refresh-spaces を実行して生成してください。

デュアルモードアーキテクチャ

feishu_client.py は 2 つの実行モードをサポートし、自動的に選択します：

モード	条件	特徴
直連モード	config.json に app_secret + cache/user_token.json がある	Feishu API を直接呼び出し、最速
lark-cli プロキシモード	app_secret または user_token がなく、lark-cli がある	lark-cli api を通じてリクエストをプロキシ、設定不要

既存の設定（app_secret + OAuth token）を持つ既存ユーザーは引き続き直連モードを使用し、影響は一切ありません。 新規ユーザーは lark-cli を通じて設定すると、すべてのリクエストが自動的に lark-cli プロキシを経由し、token を手動で管理する必要はありません。

トラブルシューティング

エラー	原因	修復
config.json が存在しない	インストールガイドを実行していない	python3 scripts/setup.py を実行
lark-cli がインストールされていない	lark-cli も app_secret もない	npm install -g @larksuite/cli && lark-cli config init --new && lark-cli auth login --domain all
lark-cli の呼び出しに失敗	token の期限切れ	lark-cli auth login --domain all で再認証
連絡先/ナレッジベースのキャッシュが空	キャッシュを更新していない	refresh-contacts または refresh-spaces を実行
Bot has NO availability	ボットの利用可能範囲に対象ユーザーが含まれていない	Feishu 開放プラットフォームでアプリの利用可能範囲を「すべての従業員」に設定し、再公開
権限不足	必要な scope が不足	lark-cli auth login --domain all で権限を補充

Feishu 開放プラットフォーム管理画面：https://open.feishu.cn/app