data_query_skill/skills/feishu-data-publisher/references/configuration.md

配置与权限

环境变量

脚本读取当前进程环境变量，不会自动加载 .env。在项目根目录创建不进入 Git 的 .env，写入以下三个参数：

export FEISHU_APP_ID='飞书自建应用 App ID'
export FEISHU_APP_SECRET='飞书自建应用 App Secret'
export FEISHU_TARGET_CHAT_ID='oc_a63f05d3a773e8d4d4a57955a618b63b'

当前团队使用的机器人应用名称为“增长投放”。FEISHU_APP_ID 和 FEISHU_APP_SECRET 的真实值只放在环境变量或 Secret Manager，不写入 Markdown 和 Git。

每次新开终端后，在项目根目录执行：

source .env

可用下面的命令确认三个变量已加载，而不显示其值：

for name in FEISHU_APP_ID FEISHU_APP_SECRET FEISHU_TARGET_CHAT_ID; do
  if [ -n "$(printenv "$name")" ]; then echo "$name=set"; else echo "$name=unset"; fi
done

当前默认 chat_id 对应“前端组”。群 ID 不是应用密钥，但属于环境配置；通用 Skill 只记录配置方法，实际值放在使用者本机的 .env。

也可使用群名，由脚本在机器人可见群中精确解析：

export FEISHU_TARGET_CHAT_NAME='前端组'

群名可能重名，因此生产环境推荐保存 chat_id。群 ID 不是应用密钥，但属于环境配置，不应硬编码进通用 Skill。

可选配置：

export FEISHU_BASE_URL='https://open.feishu.cn/open-apis'

飞书应用准备

• 应用必须启用机器人能力，并已发布到当前企业。
• 机器人必须加入目标群，才能查到群并向群发送消息。
• 应用需具备获取 tenant access token、上传素材、创建与查询云文档导入任务、管理电子表格权限、获取群信息和发送消息所需的权限。
• 如果上传成功但权限设置失败，检查应用是否有“添加或管理云文档协作者/权限”和电子表格管理权限。
• 如果可以导入但不能发消息，检查机器人是否在目标群、应用是否已发布，以及消息发送权限。

API 流程

1. POST /auth/v3/tenant_access_token/internal
2. POST /drive/v1/medias/upload_all，使用 parent_type=ccm_import_open
3. POST /drive/v1/import_tasks
4. GET /drive/v1/import_tasks/{ticket} 轮询结果
5. PATCH /drive/v1/permissions/{token}/public?type=sheet
6. POST /im/v1/messages?receive_id_type=chat_id

脚本不会打印 tenant access token、App Secret 或临时素材 token。

常见错误

• 群名匹配多个群聊：改用 --chat-id 或 FEISHU_TARGET_CHAT_ID。
• 机器人看不到目标群：先把机器人加入群，再用 --list-chats 检查。
• 导入任务超时：稍后重试，并确认文件大小和扩展名符合飞书限制。
• 设置任何人可编辑失败：确认企业安全策略允许互联网链接分享，且应用具备文档权限管理能力。