feishu-setup

feishu-setup：可选飞书连接器向导

目标：让本机 .agents/skills/worklog-ingest/connectors/feishu/ 在无人值守 ingest 中可用。Feishu 与 lark-cli 完全选配，默认和 worklog 在同一台电脑。未选择飞书时不安装、不认证、不生成任何配置。

Step 1：安装可选依赖

npm i -g @larksuite/cli
bash -lc 'lark-cli --version'

没有 npm 时先安装 Node。后续 lark-cli 都由连接器经登录 shell 启动，因为 node 的 PATH 可能只在 shell 初始化文件中存在。

安装与扫码授权属于交互式配置，按当前客户端逐条审阅并授权即可。不要把 Bash(lark-cli:*) 或 npm 全局安装通配永久追加到 .claude/settings.json。夜间 ingest 只调用仓内受检的 check.sh / fetch.sh，已有固定包装器权限足够。

Step 2：应用凭证与授权

1. 运行 lark-cli config init，按飞书开放平台说明配置自建应用与所需 scope。
2. 运行 lark-cli auth login 完成 Device Flow 扫码授权。
3. 运行 lark-cli auth status 与 lark-cli auth scopes 核对身份和权限。

企业租户不允许自建应用或不给 scope 时，停止配置飞书并说明“该租户暂不支持此可选连接器”。不要修改其他 sources，ingest 其余部分照常运行。

Step 3：macOS 无人值守适配

macOS 钥匙串在夜间非交互会话中可能不可用。只有用户理解并接受“凭证从钥匙串降级到 lark-cli 本地配置文件，保护强度降低”后才运行：

bash -lc 'lark-cli config keychain-downgrade'

凭证仍在 vault 之外，禁止复制 app secret、token 或 lark-cli 凭证到 worklog 配置。

Step 4：发现并确认采集范围

bash -lc 'lark-cli im +chat-search --query "<关键词>"'
bash -lc 'lark-cli im +chat-list --types=p2p,group'

先确认本人 open_id，优先使用 ou_ 开头的唯一值，姓名只作为旧格式兼容。再让用户逐项选择：

1. 少量已选会话，以及每个会话的 own / mentions / full。
2. 可选生效日期 active_from / active_until。
3. 是否额外扫描全部 p2p，默认 none。
4. 是否扫描未选群的本人发言与 @ 触点，默认 none。
5. 是否扫描相关文档，默认关闭。

mentions、full、全部 p2p 与文档扫描都会让他人的内容进入本机临时文件和当前 Agent 上下文。启用前复述 connectors/README.md 的 IM 数据使用须知并取得明确同意。不要用“负责人”“组长”等角色推断读取范围，公共配置只表达用户亲自选择的采集级别和日期。

Step 5：写本地作用域与非敏感 source

在 vault 根生成 worklog.feishu.local.json，格式完整遵循 connectors/README.md。该文件包含 open_id、chat_id 与用户选择，必须已被 .gitignore 排除。写后运行：

chmod 600 worklog.feishu.local.json
git check-ignore -q worklog.feishu.local.json

若权限或 ignore 检查失败，先修复，不要继续。然后只在受 Git 跟踪的 worklog.config.yaml 中写入不含身份和会话坐标的 source：

- {type: im, provider: feishu, via: lark-cli, scope_file: worklog.feishu.local.json, on_unreachable: note}

已有 v1 chats + me + record_others source 仍可使用。迁移时先生成本地作用域并试拉成功，再把 tracked config 改为 scope_file，不要在同一晚同时保留两条 Feishu source。