soia-cwork-feishu-cli

使用飞书官方 lark-cli 连接用户明确授权的飞书应用，按“知识库/Wiki”和“云盘/Drive”分开执行只读盘点、搜索和文档分析。默认使用应用身份 bot；只有用户明确要求访问个人云盘、个人知识库或私有资源时，才走用户 OAuth。默认不修改飞书远端内容；写入、移动、删除、权限变更、发送消息和导出个人数据都必须单独确认。

场景分流：知识库与云盘不能混用

不要把 Wiki 的空间/节点接口当作云盘目录，也不要把 bot 的空搜索结果解释为用户个人云盘为空。

两种权限类型：是否需要同时申请

飞书对同一个 API 能力按调用身份分别管理权限：

• 应用身份权限：tenantaccesstoken，运行时是 bot。在“应用身份权限”页签申请；还要配置应用数据权限、可用范围或把应用加入目标知识库/文件夹。
• 用户身份权限：useraccesstoken，运行时是 user。在“用户身份权限”页签申请；再由用户执行 lark-cli auth login 完成 OAuth，访问范围跟随登录用户。

如果目标是“Bot 读取企业知识库 + 用户 OAuth 读取个人云盘”，需要在两个页签分别申请对应的最小只读 scope。只使用其中一种身份时，不要重复申请另一种权限。具体清单以 [permissions.yml](references/permissions.yml) 的 identity_modes 为准。

客户可读说明

这个技能可以做什么

客户如何使用

可以直接说：

• “用飞书 CLI 盘点我可见的知识库层级和云盘文档类型。”
• “读取这个飞书 Wiki 页面，判断它更适合迁移到哪个开源本地部署产品。”
• “检查飞书应用当前能看到哪些知识空间和文档，不要修改任何内容。”

执行前解析 source、target、scope、as 和 output。对本技能的调研任务，默认 as=bot、readonly=true、dryrun=true（涉及写操作时）；不要因为 bot 看不到用户个人资源就静默改用用户 OAuth。

依赖与安装

安装本技能：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-cwork-office@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-cwork-office-skills -g -a '*' -s soia-cwork-feishu-cli -y

安装后先运行：

lark-cli doctor
lark-cli profile list
lark-cli auth status --json --verify
lark-cli whoami

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

权限开通与应用发布

在首次调研前，或 CLI 返回错误时，先读取[机器可读权限目录](references/permissions.yml)和[错误目录](references/errors.yml)，再按[权限开通指南](references/permissions.md)向客户解释申请流程。先判断目标是知识库还是云盘，再判断使用 bot 还是 user OAuth；不要把 user OAuth scope 当成 bot 权限，也不要为了读取而申请写入、删除、上传或成员管理权限。

开放平台入口按私有配置中的 LARKAPPID 拼接：

https://open.feishu.cn/app/<APP_ID>/auth

必须完成完整闭环：在“开发配置 → 权限管理”按目标 API 的权限要求开通并保存 → 检查 tenant 应用数据权限和资源可见范围 → 对需审核权限创建版本并提交线上发布 → 等企业管理员审核通过 → 重新运行 setupappcredentials.py --use、auth status --json --verify 和代表性只读命令。免审权限可直接测试；“审核中”不视为权限已正式生效。

每次向客户回执权限时，分成“必需”“可选”“不要默认开通”三类，并列出缺失 scope、官方控制台入口和发布步骤；不要把客户的真实 App ID 写进公共技能文件。

应用凭证登录（bot 模式）

应用凭证是本技能的默认登录方式，不调用 lark-cli auth login 作为默认流程。应用凭证只获得 bot 身份：它只能读取应用可见、被授予应用访问权或租户策略允许访问的资源；它不能自动代表用户读取个人知识库、个人云盘或私有文档。

推荐把凭证放在技能专属私有配置，不提交仓库、不写入 vault：

~/.config/soia-skills/soia-cwork-feishu-cli/config.yml
SOIA_CWORK_FEISHU_CONFIG_FILE=<custom-config-path>

配置示例见 [assets/config.example.yml](assets/config.example.yml)。配置只允许出现占位符或用户自己的本地值：

version: 1
env:
  LARK_APP_ID: "<YOUR_APP_ID>"
  LARK_APP_SECRET: "<YOUR_APP_SECRET>"
  LARK_PROFILE: "feishu-reader"
  LARK_BRAND: "feishu"

使用配置初始化应用 profile 时，脚本通过 stdin 传递 Secret，不把 Secret 放进进程参数或日志：

python3 <skill-path>/scripts/setup_app_credentials.py

首次初始化或本机 profile 不存在时，使用 --use 让它成为当前 profile：

python3 <skill-path>/scripts/setup_app_credentials.py --use

刷新已有 profile 的 App Secret、App ID 或 brand 时，必须由用户明确发起，再使用：

python3 <skill-path>/scripts/setup_app_credentials.py --replace --use

由于 lark-cli 不允许同一个 App ID 同时存在于两个 profile，刷新会先删除旧 profile，再写入新 profile；因此只有在私有配置已确认无误、且用户明确要求刷新时才执行。若写入失败，需要检查私有配置后重新运行初始化。完成后验证：

lark-cli profile list
lark-cli auth status --json --verify
lark-cli whoami
lark-cli doctor

若出现 invalid_client、错误码 20140 或 “The auth method is not supported.”，这属于 profile/应用凭证认证失败，不是缺少 scope；先按 [errors.yml](references/errors.yml) 修复 profile，再检查权限。

如需将新 profile 切换为默认 profile，必须显式使用：

python3 <skill-path>/scripts/setup_app_credentials.py --use

等价的手工方式是：

printf '%s' '<YOUR_APP_SECRET>' | lark-cli profile add \
  --name feishu-reader \
  --app-id '<YOUR_APP_ID>' \
  --app-secret-stdin \
  --brand feishu

不要把 LARKAPPSECRET 放进 shell 历史、命令行参数、日志、提交记录或飞书文档。auth login 是用户 OAuth 授权，只能在用户明确要求个人资源或明确指定 --as user 时使用。

用户 OAuth 登录（仅个人资源）

用户明确要求个人云盘、个人知识库或私有资源时，先读取对应的 [wiki-workflow.md](references/wiki-workflow.md) 或 [drive-workflow.md](references/drive-workflow.md)，确认用户身份 scope，再使用 split-flow：

mkdir -p "${TMPDIR:-/tmp}/soia-cwork-feishu-cli"
lark-cli auth login --scope "<minimal-user-scopes>" --no-wait --json
lark-cli auth qrcode '<verification_url>' --output "${TMPDIR:-/tmp}/soia-cwork-feishu-cli/feishu-user-oauth.png"

把授权链接和二维码交给用户后结束本轮；用户确认完成后，由 agent 执行 lark-cli auth login --device-code <device_code>，再检查 auth status --json --verify 是否为 user: ready。不要把用户 OAuth 当成 bot 修复手段，也不要在用户未明确要求时静默切换身份。

认证链路必须区分：

• lark-cli auth login：官方 CLI 的用户身份 OAuth/device flow，完成后才会出现 user: ready。
• https://accounts.feishu.cn/oauth/v1/device/verify?...：CLI device flow 的验证入口。若它跳转到 open.feishu.cn/page/scope-authorization 并显示“已提交申请，正在审核中”，表示应用的用户身份 scope 或应用版本尚未生效；这不是用户已经完成登录。
• https://open.feishu.cn/open-apis/authen/v1/userinfo：登录完成后的“获取用户信息” API，需要已有 useraccess_token，不能当作登录入口。
• 自建网页应用若自行实现 OAuth，使用官方授权码接口 /open-apis/authen/v1/authorize，配置 redirecturi 后交换 useraccess_token；不要为了 CLI 任务手工拼接该 URL，CLI 已经用 device flow 封装。

同一个 App ID 既可以产生 Bot 的 tenantaccesstoken，也可以作为 OAuth 客户端产生用户的 useraccesstoken；页面显示应用名称相同不能证明当前是 Bot 或 User。以 auth status --json --verify 的 identities.bot / identities.user 和命令的 --as 为准。

只读调研工作流

1. 检查身份和范围：先读取[机器可读权限目录](references/permissions.yml)，必要时读取[错误目录](references/errors.yml)和[权限开通指南](references/permissions.md)；运行 lark-cli auth status --json --verify、lark-cli whoami；记录 identity、profile、token 状态和非敏感 scope，不输出密钥。
2. 读取匹配的官方嵌入技能：运行 lark-cli skills read lark-shared；知识库任务读取 lark-wiki，云盘任务读取 lark-drive，正文任务再读取 lark-doc。不要凭 --help 猜参数。
3. 盘点知识库/Wiki：按 [wiki-workflow.md](references/wiki-workflow.md) 选择身份；bot 运行 wiki +space-list / wiki +node-list，user 仅在用户明确授权后运行对应的 --as user 命令。个人库 my_library 只能用 user 身份。
4. 盘点云盘/Drive：按 [drive-workflow.md](references/drive-workflow.md) 选择身份；bot 运行 Drive 搜索只能覆盖应用可见资源，个人云盘必须明确 OAuth 后运行 --as user。
5. 读取文档：先用对应身份运行 lark-cli drive +inspect --as <bot|user> --url '<URL>' --format json 解析真实类型和 token；再按 lark-doc 说明使用对应身份的 docs +fetch。
6. 分析迁移需求：只基于已读到的结构、类型、附件、权限和协作痕迹判断目标产品；把“看到的”“推断的”“未验证的”分开写。
7. 验证：对关键数量重新分页核对；抽取代表性文档；检查 bot 不可见的个人资源并单列为缺口；若 API 要求应用数据权限，单独核对其数据范围。不要把一次搜索结果当成全量清单。

详细命令和产品边界见 [references/cli-workflows.md](references/cli-workflows.md)。

写操作与风险边界

• 默认只读：搜索、列空间、列节点、读取正文、查看元数据、查看评论和权限。
• 创建、编辑、评论、上传、移动、复制、导出、下载、公开分享、成员管理、删除、回滚和发送消息都属于写入或敏感数据动作；先展示目标、范围、命令和影响，等待用户明确确认。
• 遇到 CLI 返回 confirmation_required，不要静默追加 --yes；把高风险动作交给用户确认。
• 遇到 invalid_client / 20140，不要把它归类为缺 scope，也不要先申请权限；先修复应用凭证 profile。
• 遇到缺 scope，优先按错误中的 console_url 和缺失 scope 处理；不要静默切换用户 OAuth，只有用户明确要求个人资源或明确指定 --as user 时才启动 OAuth。
• 不读取浏览器 Cookie、密码、浏览器 profile、keychain 原始内容或未由用户提供的 token 存储。

日志与完成回执

每次运行至少报告：

• started：CLI 版本、profile 名称、bot/user 身份、非敏感 scope 和调研范围；不打印 Secret。
• processed：空间、节点、文件或文档数量，以及分页是否完整。
• created/updated：默认写“未改动远端”；若有用户确认的写入，列出实际对象和结果。
• skipped/failed：权限不足、bot 不可见、分页上限、解析失败和原因。
• verification：运行过的 status、schema、分页、抽样读取和备份/导出检查。

推荐回执：

完成：<一句话说明本次飞书调研或配置结果>。

日志摘要：
- started: <profile / identity / 非敏感范围>
- processed: <空间、节点、文档或文件数量>
- created/updated: 未改动远端 / <已确认的写入结果>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的 CLI 检查、分页核对、抽样读取>

问题与下一步：
- <缺 scope、bot 不可见资源、需要用户授权或无>

资源

• 配置示例：[assets/config.example.yml](assets/config.example.yml)
• CLI 工作流：[references/cli-workflows.md](references/cli-workflows.md)
• Provider 选择和凭证边界：[references/providers.md](references/providers.md)
• 权限事实源：[references/permissions.yml](references/permissions.yml)
• 知识库/Wiki 工作流：[references/wiki-workflow.md](references/wiki-workflow.md)
• 云盘/Drive 工作流：[references/drive-workflow.md](references/drive-workflow.md)
• 常见错误事实源：[references/errors.yml](references/errors.yml)
• 权限申请流程：[references/permissions.md](references/permissions.md)
• 应用凭证初始化脚本：scripts/setupappcredentials.py

验证

python3 <skill-path>/scripts/setup_app_credentials.py --help
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-path>

仓库级验证由本仓 AGENTS.md 规定，至少运行单元测试、技能目录生成检查、技能审计和 git diff --check。

前向测试

复杂调研或权限变更前，先用脱敏 fixture 或客户明确授权的代表性只读对象执行一次前向测试：核对权限提示、bot 身份、数量分页、失败分类和最终回执；不得把命令成功退出当成内容完整性的证据。