lark-authorize

name	lark-authorize
version	1.0.0
description	Friday 飞书授权引导：检查连接状态，按需配置应用凭证、登录授权并验证。当用户需要初始化飞书连接、修复未登录状态、配置 lark-cli、执行 /login 或确认飞书连接可用时使用。
metadata	{"requires":{"bins":["lark-cli"]}}

Lark Authorize

前置条件： 先阅读 ../lark-shared/SKILL.md。

本 Skill 用于引导用户完成 lark-cli 与飞书的连接。不要直接假设需要重新配置或重新登录；必须先检查当前状态，再根据返回结果决定下一步。

输出展示规则

• 内部判断用命令默认使用 showOutputInTui: false，由 Agent 读取返回内容后总结。
• 需要用户打开链接、扫码、输入验证码或等待授权完成的命令使用 showOutputInTui: true。
• 如果某一步需要把命令结果直接展示给用户，使用 showOutputInTui: true 时必须选择合适的输出格式：--format pretty 适合说明性结果，--format table 适合列表，--format json 仅在用户需要原始 JSON 时使用。

流程

Step 1: 检查当前状态

先执行：

lark-cli auth status

调用 run_lark_cli 时设置 showOutputInTui: false。

根据输出判断：

• 如果状态显示已登录、身份可用或已有有效授权：说明连接已可用，直接进入 Step 4 再验证一次并总结当前状态。
• 如果状态显示未登录、缺少授权、token 失效或需要登录：进入 Step 3。
• 如果状态显示应用凭证未配置、找不到 appId/appSecret、缺少配置文件或要求先 config init：进入 Step 2。
• 如果命令不存在或 lark-cli 未安装：提示用户先安装 @larksuite/cli 和 lark skills，不要继续执行后续步骤。
• 如果输出不明确：简短说明无法判断当前状态，并建议先按 Step 2 重新配置或请用户提供完整错误输出。

Step 2: 配置应用凭证

仅当 Step 1 表明应用凭证未配置或配置无效时执行。

在后台运行此命令。命令会输出一个授权链接；提取该链接并发送给用户。用户在浏览器中完成配置后，命令会自动退出。

lark-cli config init --new

调用 run_lark_cli 时设置 showOutputInTui: true。

执行要求：

• 将输出中的授权链接清楚发给用户。
• 等待命令结束后再继续。
• 如果命令失败，只基于 stdout/stderr 说明失败原因，不要编造配置结果。
• 配置完成后进入 Step 3。

Step 3: 登录授权

当 Step 1 表明未登录、授权缺失或 Step 2 刚完成配置后执行。

用户入口统一是 /login。本步骤是 Friday 在 /login 流程内部执行的授权动作；不要建议用户手动运行底层 lark-cli 登录命令。

在后台运行授权命令。命令会输出一个授权链接；提取该链接并发送给用户。用户在浏览器中完成登录授权后，命令会自动退出。

调用 run_lark_cli，参数为 ["auth", "login", "--recommend"]，并设置 showOutputInTui: true。

执行要求：

• 将输出中的授权链接清楚发给用户。
• 等待命令结束后再继续。
• 如果命令失败，只基于 stdout/stderr 说明失败原因。
• 登录完成后进入 Step 4。

Step 4: 验证连接

最后执行：

lark-cli auth status

调用 run_lark_cli 时设置 showOutputInTui: false。

根据输出给出简短结论：

• 已连接：说明当前身份、授权状态和可用信息，然后进入 Step 5。
• 未连接：说明缺少配置还是缺少登录，并给出下一步建议。
• 权限不足：说明需要重新通过 /login 完成授权，不要建议用户手动执行底层授权命令。

Step 5: Project Knowledge Warmup

仅当 Step 4 验证连接可用后执行。目标是在当前项目的 .gitx/memory.json 中形成或更新 project_context_index，供后续 commit message、排障、review 协作、需求状态和开发记录场景复用。

输入 context 可能包含 projectHints：

• repositoryName
• cwdName
• gitRoot
• branch
• remoteUrl
• webUrl

根据 projectHints 先定位项目对应知识库，不要求用户手动指定文档。优先使用 repositoryName，其次使用 cwdName。建议用少量关键词只做知识库定位：

• <项目名>
• <项目名> 知识库
• <项目名> 项目
• <项目名> 文档

开始预热前先调用 read_project_context_index 读取本地索引摘要和 fingerprint。随后只用少量飞书只读命令定位并遍历线上知识库目录，生成线上目录摘要，再调用 compare_project_context_index 比对本地与线上目录 fingerprint：

• 如果目录 fingerprint 一致，不要立刻重复读取文档 outline。先对本地索引中的 documents 和 nonDocResources 调用 drive metas batch_query 批量读取元数据，基于 doc_type、doc_token、title、latest_modify_time、latest_modify_user 形成 metadataFingerprint。
• 如果目录 fingerprint 和 metadataFingerprint 都一致，复用本地 project_context_index，不要调用 docs +fetch，并在最终回答中说明“本地索引已是最新”。
• 如果目录 fingerprint 一致但 metadataFingerprint 不一致，只对 latest_modify_time 或元数据变化的 docx/doc 文档重新执行 docs +fetch --scope outline；未变化文档复用本地 outline。
• 如果本地索引缺失、项目匹配变化或目录 fingerprint 不一致，重新更新目录索引；再通过 drive metas batch_query 找出新增或变化节点，只对必要 docx/doc 文档读取 outline，最后调用 save_project_context_index 保存。
• 比对用的线上目录摘要只包含稳定节点字段：title、path、obj_type、obj_token、node_token、space_id，不要为了算 fingerprint 读取全文。
• drive metas batch_query 一次最多 200 个 request_docs；文档很多时按批次查询。wiki 节点必须使用 node.obj_token 作为 doc_token，使用 node.obj_type 作为 doc_type，不要把 wiki token 当成 doc token。

只允许执行以下只读命令，内部判断统一使用 showOutputInTui: false：

lark-cli docs +search --query "<关键词>" --format json
lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --format json
lark-cli wiki nodes list --params '{"space_id":"<space_id>","parent_node_token":"<node_token>"}' --format json
lark-cli drive metas batch_query --data '{"request_docs":[{"doc_token":"<obj_token>","doc_type":"<obj_type>"}],"with_url":true}' --format json
lark-cli docs +fetch --api-version v2 --doc "<文档URL或token>" --scope outline --max-depth 3 --format json
lark-cli docs +fetch --api-version v2 --doc "<文档URL或token>" --scope section --start-block-id "<标题block id>" --detail simple --format json
lark-cli docs +fetch --api-version v2 --doc "<文档URL或token>" --scope keyword --keyword "<关键词>" --detail simple --format json

权限补齐规则：

• 如果 docs +search 返回未登录、token 失效、Permission denied、缺少 scope 或明确缺少 search:docs:read，不要立刻保存 missing 或空 project_context_index。
• 先调用 load_skill 加载 lark-shared，按其规则在当前 TUI 内部发起最小 scope 授权：调用 run_lark_cli，参数使用 ["auth", "login", "--scope", "search:docs:read"]，showOutputInTui: true，等待用户完成授权。
• 授权命令结束后，重试原来的 docs +search 一次；只有这次重试仍然失败，才说明缺少权限并保存 missing 状态。
• 如果 wiki、drive metas batch_query 或 docs +fetch 返回缺少其它 user scope，也按 lark-cli 输出里的 scope 加载 lark-shared，用 ["auth", "login", "--scope", "<缺失scope>"] 补授权，并重试原命令一次。
• 保存 missing 或空索引前，必须已经尝试过上述 lark-shared 授权补齐和一次原命令重试；不要把“重新执行 /login”作为第一反应。
• 如果错误是 bot 后台 scope 或应用后台权限，不要发起用户授权；只基于 lark-cli 返回内容说明需要后台开通。

读取策略：

• docs +search 只用于定位项目对应知识库或项目文档入口；不要把它当成最终资料集合。
• 如果命中 Wiki URL、Wiki token、知识库空间或知识库节点，先用 wiki spaces get_node 解析节点；不要把 wiki token 直接当成 doc token。
• wiki spaces get_node 返回中读取 node.obj_type、node.obj_token、node.title、node.space_id 和节点 token。确定 space_id 后，用 wiki nodes list 从项目知识库根节点或命中的目录节点开始遍历。
• 遍历项目对应知识库中的所有可读子节点，递归或逐层继续 wiki nodes list，直到覆盖该项目知识库中能访问到的文档节点；不要只按固定主题筛选。
• 对每个可读节点记录标题、路径、node token、obj_type、obj_token、space_id。形成全量目录索引后，先用 drive metas batch_query 做快速元数据比对，再决定哪些 docx/doc 文档需要轻量读取。
• 对 obj_type 为 docx 或 doc 且本地没有 outline、属于新增节点或元数据已变化的节点，读取 docs +fetch --scope outline 获取目录；只在目录过薄或标题不足以判断内容时，用 keyword 或少量 section 补充摘要。
• 对元数据未变化的 docx/doc 节点，复用本地 outline，不要重复 fetch。
• 对 obj_type 是 sheet 或 bitable 的节点，只记录标题、路径、token 和用途推断，不要用 docs fetch 强读内部表格数据。
• 如果项目知识库文档很多，可以分批处理，但最终 project_context_index 应说明已遍历范围、已索引数量、跳过数量和原因。
• 不要只按固定主题预热；主题是开放的，索引应服务后续任意 Git/Lark Agent 查询。
• 如果搜索或读取权限不足，先按上面的权限补齐规则处理；重试后仍失败时，只基于 lark-cli 返回内容说明原因，不要猜测文档内容。
• 如果无搜索结果，保留一个 missing 状态的 project_context_index，说明没有命中项目资料。

禁止执行：

• docs +create
• docs +update
• docs +media-insert
• docs +media-download
• wiki +node-create
• wiki +move
• 任何写入、删除、移动、上传、评论或发消息命令

预热完成后，在最终回答中简短列出：

• 扫描过的关键词
• 定位到的项目知识库或入口节点
• 已遍历节点数、已读取 outline 的文档数、跳过项数量和原因
• metadataFingerprint 是否一致，以及本次实际刷新了哪些文档
• 已缓存的全量目录索引摘要
• 本地索引是否已是最新，或本次是否已保存新的 fingerprint
• 未完成项或权限问题

保存到 save_project_context_index 的 project_context_index 结构包括：

• project：项目名或仓库名
• knowledgeBase：知识库名称、space_id、入口 node token 或 URL
• documents：所有可读文档节点的标题、路径、obj_type、obj_token 或 node token
• outlines：docx/doc 文档的轻量目录或章节摘要
• nonDocResources：sheet、bitable 等非文档节点的标题、路径和定位信息
• metadata：通过 drive metas batch_query 获取的 create_time、latest_modify_time、latest_modify_user、url 等轻量元数据
• metadataFingerprint：基于 doc_type、doc_token、title、latest_modify_time、latest_modify_user 计算的内容变更指纹
• coverage：已遍历范围、已索引数量、跳过数量和权限问题
• retrievalHints：后续查询时可按标题、路径、目录关键词、文档类型或用户意图快速定位

安全规则

• 禁止输出 appSecret、accessToken、refreshToken 等密钥。
• 不要声称已完成配置或登录，除非对应命令返回成功且 Step 4 验证通过。
• 不要引导用户手动执行底层授权命令；bot 权限问题应引导用户到飞书开发者后台开通 scope。
• 写入或删除飞书资源不属于本 Skill 范围；Step 5 也只能读取文档。

输出要求

• 回答简短、明确、适合终端阅读。
• 如果需要用户打开链接，只输出必要说明和链接。
• 每一步结论必须基于命令返回内容。