项目定位与设计目标

lark-cli 是面向 Lark/Feishu 开放平台的命令行与 AI Agent 工具，定位为"代理原生（Agent-Native）"的入口。其设计目标是在三分钟内完成"安装 → 登录 → 首次 API 调用"，并同时被人类与 AI Agent 高效调用。仓库内置 24 个结构化 Skills，覆盖 18 个业务域、200+ 精选命令、26 个 AI Agent 技能包，以 MIT 协议开源，零门槛使用 README.md:1-50。

项目的核心价值在于三层架构的取舍：把"人类/AI 友好"的快捷命令、平台同步生成的 API 命令、覆盖全量的原始 API 视为同一命令空间内的不同粒度，使用者可以根据需要选择合适的层级。这种分层设计既保证了常用场景的简洁，也保留了底层 API 的完整访问能力。

三层命令架构

lark-cli 的命令体系被设计成三层金字塔，最上层是"快捷命令（Shortcuts）"，面向人机共用的高频场景；中间层是"API 命令（API Commands）"，由平台规范自动同步生成；最底层是"原始 API（Raw API）"，通过统一 lark-cli api METHOD /path 直接调用任意开放接口 README.md:1-30。

命令实现机制

在 cmd/api/api.go 中，APIOptions 结构体承载方法、路径、参数、身份（As）、输出格式、分页等所有输入，并提供 --dry-run、--page-all、--page-size、--page-delay 等通用开关 cmd/api/api.go:1-30。api 命令的运行时流程包含身份严格模式校验（CheckStrictMode）、互斥参数检查（如 --output 与 --page-all）、请求构建、dry-run 预览、调用 NewAPIClientWithConfig 发送请求，最后以 JSON 信封形式输出 cmd/api/api.go:120-180。

分页与错误包装

分页逻辑被抽到 internal/client/pagination.go 的 PaginationOptions 与 mergePagedResults 中，遵循"默认 10 页、200ms 间隔、合并数组字段"的策略，使上层命令无需重复实现 internal/client/pagination.go:1-50。错误处理通过 WrapDoAPIError 将 SDK 边界失败转换为类型化 errs.* 错误：JSON 解码失败归为 SubtypeInvalidResponse，网络错误细分为 timeout/tls/dns/server_error/transport 等子类，并附上 rawAPIJSONHint 提示用户重试时加上 --output internal/client/api_errors.go:1-40。

flowchart TB
    User[人类 / AI Agent] --> Shortcuts[Shortcuts 快捷命令<br/>lark-im / lark-doc / ...]
    Shortcuts --> API[API Commands 平台命令<br/>cmd/api 与各域命令]
    API --> Raw[Raw API<br/>lark-cli api METHOD /path]
    Raw --> SDK[oapi-sdk-go]
    SDK --> Lark[(Lark/Feishu Open Platform)]
    Plugins[Plugin SDK] -.Observer/Wrap/Restrict.-> Shortcuts
    Plugins -.Observer/Wrap/Restrict.-> API
    QualityGate[Quality Gate<br/>deterministic + semantic] -.CI 拦截.-> API
    QualityGate -.CI 拦截.-> Raw

插件 SDK 与安全契约

为了让企业或团队在不影响核心代码的前提下注入审计、只读、限权等横切关注点，lark-cli 提供了 extension/platform 中的 Plugin SDK。它在 On(Startup) 后，会在每次命令分发时按注册顺序触发 Observer Before → Wrap (around RunE) → Observer After 钩子链；Restrict() 返回 command_denied 时会绕过 Wrap 链，但 Observer 仍会触发以保证审计可见 extension/platform/README.md:1-60。

Plugin SDK 强制规定：调用 Restrict() 的插件必须声明 FailClosed；同一二进制只允许一个插件贡献规则（避免"独立插件越权放宽另一插件限制"）；每个 Restrict 规则按 OR 组合、按轴（allow/deny/max_risk/identities）AND 收敛 extension/platform/README.md:60-120。仓库自带两个示例插件：audit-observer（最简 Observer）和 readonly-policy（结合 MaxRisk=read 与 FailClosed 演示拒绝写操作），它们在 CI 中由 make examples-build 强制构建以防止示例静默漂移 extension/platform/examples/README.md:1-15。

质量门禁与社区关切

lark-cli 通过 internal/qualitygate/config/README.md 描述的"质量门禁"保护机器可读的 CLI 契约：覆盖命令/旗标命名、Skills 引用、--dry-run 示例、默认输出事实以及命令边界错误契约 internal/qualitygate/config/README.md:1-30。语义层审查默认观察（comment-only），当仓库变量 SEMANTIC_REVIEW_BLOCK=true 启用时才会真正阻断 PR；首批阻断类别为 error_hint 和 skill_quality internal/qualitygate/config/README.md:30-80。该门禁同时定义了按行号/路径精确定位的豁免（waiver）机制，防止历史兼容项被一刀切掉。

PR 标签同步脚本 scripts/pr-labels/index.js 进一步把"修改文件的有效行数"映射为 size/S|M|L|XL 标签，并把改动域识别为 domain/im|vc|ccm|base|...，为评审者提供即时的影响范围信号 scripts/pr-labels/README.md:1-20。

社区的关切（参见 issue #234、#204、#1385、#501）反映出当前架构的真实痛点：用户希望 CLI 支持"非企业应用身份"、多用户按 open_id 的授权、以及解决 Skills 全量本地安装导致的上下文膨胀（19 个 skill ≈ 212 文件 / 22k 行）。这些问题直接驱动着 Plugin SDK 的 Restrict 规则、Schema 内省、以及按需加载方向的下一步迭代 README.md:1-50。

See Also

• API Command Reference
• Plugin SDK Guide
• Quality Gate & CI Contracts
• Skills & Agent Integration

lark-cli 在多种执行场景下都需要清晰的“身份”概念：既要区分 user（终端用户） 与 bot（应用机器人） 两种调用主体，又要在本地安全地保存 access_token / refresh_token，还要为 AI Agent、多用户协作等场景提供受控的代理注入。本页梳理认证、身份与凭据管理三大主题，覆盖 lark-cli auth login 命令体系、运行时身份切换、凭据存储以及 Sidecar 认证代理扩展点。

一、认证架构总览

lark-cli 的认证体系可以划分为四层：配置层（app_id / app_secret）、凭据层（OS Keychain 中的 refresh_token 与内存中的 TAT）、命令层（auth login / auth logout / auth status）以及执行层（每个业务命令通过 --as user|bot 选择身份）。这种分层使同一份 app 配置既可以驱动机器人自动化（TAT），又可以代表用户操作（user access_token），二者走完全不同的解析路径。README.md 中明确指出，工具默认依赖 OS-native keychain 进行凭据持久化，并提供输入注入防护与终端输出清洗等多层安全保护。

flowchart LR
    A[config init<br/>app_id + app_secret] --> B[auth login<br/>--domain/--scope]
    B --> C[Keychain<br/>refresh_token]
    C --> D{Runtime}
    D -->|--as user| E[user access_token]
    D -->|--as bot| F[TAT<br/>app_id+app_secret]
    E --> G[Lark OpenAPI]
    F --> G
    G --> H[WrapDoAPIError<br/>typed errs.*]

二、`auth login` 命令体系

auth login 是用户与平台建立委托关系的入口，位于 cmd/auth/login.go 中。命令核心支持以下几种模式（参见 README.md 的鉴权章节）：

交互式提示、会话消息文案与结果渲染分别被拆到 login_interactive.go、login_messages.go、login_result.go 三个独立文件中，便于在不同终端环境（TTY、CI、Agent）下复用同一套登录状态机。login_scope_cache.go 负责 scope 缓存，避免每次登录都重新计算推荐的最小 scope 集合。

三、身份（Identity）模型与运行时切换

lark-cli 定义了 core.Identity 类型来统一表征调用主体，并通过 --as 标志在每条业务命令上做选择。从 cmd/api/api.go 的 APIOptions.As 字段可以看出，user / bot 是两个一等公民。

lark-cli calendar +agenda --as user
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"

二者的凭据来源截然不同：

• bot 身份：TAT（tenant access token）由 app_id + app_secret 在 internal/auth 包中即时换取，无需本地用户凭据，适合后台批处理与 webhook 接收。
• user 身份：依赖 auth login 后写入 Keychain 的 refresh_token，每次调用前由 credential.TokenSpec / credential.TokenResult 抽象（见 internal/client/client_test.go 中的 staticTokenResolver）完成解析与刷新。

社区曾在 #89 中反映“无法以用户的名义发送消息，只能以 bot 名义”，该问题正是 --as user 前置条件之一 —— 必须先完成 auth login 并把 refresh_token 落盘。另一条 #204 “CLI 的多用户授权支持需求” 也在讨论按 openid 区分不同 user 凭据，这是当前 auth login 尚未原生覆盖的能力，通常通过 Sidecar 模式解决。

四、凭据存储、错误包装与 Sidecar 扩展

4.1 本地凭据存储

lark-cli 不把 token 写入纯文本配置文件，而是委托操作系统 Keychain（macOS Keychain、Linux Secret Service、Windows Credential Manager）。config init --new 仅写入 app_id / app_secret，auth login 则把 user 模式下的 refresh_token 推入 Keychain，读取时由 internal/credential 包负责抽象，调用方只看到 ResolveToken(ctx, TokenSpec) (*TokenResult, error)。

4.2 错误契约

任何来自 SDK 边界的失败都会经过 internal/client/api_errors.go 的 WrapDoAPIError：

• 已类型化的 errs.Problem 透传；
• JSON 解码失败 → InternalError{SubtypeInvalidResponse}，并附带 rawAPIJSONHint（典型场景：文件下载端点忘记加 --output）；
• 其它错误依据 errors.As 与消息子串归类为 NetworkError，子类型覆盖 timeout / tls / dns / server_error / transport-fallback。internal/client/api_errors_test.go 用 x509.UnknownAuthorityError、net.DNSError 等典型样本对归类做了锁定测试。

4.3 Sidecar 认证代理

在 Agent 多用户、CI 沙箱等场景下，本地 Keychain 不可用，lark-cli 提供了 Sidecar 注入模式，详见 sidecar/server-demo/README.md：

• 通过 LARKSUITE_CLI_AUTH_PROXY 指向一个本地 HTTP 端点，CLI 在需要 token 时改为向代理申请；
• 代理以 HMAC 签名（LARKSUITE_CLI_PROXY_KEY）应答，server 进程不继承 LARKSUITE_CLI_AUTH_PROXY 避免循环；
• 启动期校验：URL 必须是 http:// 且 host 属于 loopback 或同机别名（host.docker.internal 等），跨机器部署不在支持范围内（应改用独立的 auth broker / STS）；
• 严格模式可设置 LARKSUITE_CLI_STRICT_MODE=user 把沙箱锁定在单一身份。

See Also

• README.md —— 整体三分钟上手、Three-Layer Command System 与安全警告
• sidecar/server-demo/README.md —— 沙箱化部署与 Sidecar 凭据注入
• internal/qualitygate/config/README.md —— 涉及命令边界错误契约的 CI 规则（与认证错误包装相关）
• extension/platform/README.md —— 插件 SDK 中的 Restrict() 限制，可用于为高风险身份切换加策略

命令系统、快捷指令与领域覆盖

1. 概述与设计目标

lark-cli 的命令系统采用 三层架构（Three-Layer Architecture），按抽象层级从高到低依次为：快捷指令（Shortcuts）→ 平台同步生成的 API 命令（API Commands）→ 直接透传开放平台的原始 API（Raw API）。这一架构的目标是同时服务两类用户：人类开发者（关注简洁与可读）以及 AI Agent（关注结构化、确定性、可校验的契约）。资料来源：README.md:27-30。

2. 命令分发与生命周期

命令派发由 Cobra 框架驱动，每次调用会经过宿主进程预注册的插件钩子链。Plugin SDK 在 Install(Registrar) 阶段注入四类能力：Observe（记录入参出参）、Wrap（包裹 RunE）、Restrict（按规则放行/拒绝）、On(Startup,Shutdown)（进程级回调）。资料来源：extension/platform/README.md:1-30。

sequenceDiagram
    participant U as 用户/Agent
    participant H as Host(Cobra)
    participant S as SDK
    participant P as Plugin
    U->>H: 发起命令
    H->>S: 进入 hook 链
    S->>P: Observer.Before
    alt Restrict 通过
        S->>P: Wrap(around RunE)
        H->>H: 执行 RunE
        S->>P: Observer.After
    else command_denied
        S-->>U: 返回结构化拒绝信封
        S->>P: 仍触发 Observer(供审计)
    end
    Note over S,P: 退出时 Emit(Shutdown)

当插件调用 Restrict() 时，Builder 会自动设置 FailClosed，未声明 FailClosed 的限制插件会被 restricts_mismatch 错误拒绝，从而防止“看似启用实则不拦截”的安全错觉。资料来源：extension/platform/README.md:31-58。

3. 原始 API 命令的参数与输出

cmd/api/api.go 暴露的 APIOptions 结构集中了 Raw API 层所有公共 Flag：Method/Path（位置参数）、Params、Data、As（身份）、Output、PageAll、PageSize、PageLimit、PageDelay、Format、JqExpr、DryRun、File。路径解析会自动剥离域名前缀与查询片段，统一归一化为 /open-apis/...。资料来源：cmd/api/api.go:18-58。

常用输出格式与分页约定如下：

• 输出格式：json（默认，含完整信封）、pretty、table、ndjson（便于管道）、csv。资料来源：README.md:101-114。
• 分页：--page-all 自动遍历；--page-limit 控制最大页数；--page-delay 毫秒级间隔以避免限流。资料来源：README.md:108-113。
• Dry Run：副作用命令需先以 --dry-run 预览请求，cmdutil.PrintDryRunWithFile 还会渲染表单字段。资料来源：cmd/api/api.go:104-120。
• 校验冲突：--output 与 --page-all 互斥，违反时返回 errs.NewValidationError(SubtypeInvalidArgument, ...) 并附带 WithHint 与具体 InvalidParam 列表。资料来源：cmd/api/api.go:85-95。
• Schema 自省：lark-cli schema [command_path] 输出参数、请求体、响应、身份与作用域，便于 Agent 动态发现能力。资料来源：README.md:120-128。

4. 领域覆盖与插件生态

lark-cli 在 18 个业务域内置 200+ 精选快捷指令与 24 个 AI Agent Skills，覆盖日历、即时消息、文档、表格、演示、白板、任务、邮件、知识库、视频会议、审批等场景。资料来源：README.md:35-44 与 README.md:1-25 中的 Skills 列表。每个 lark-* 技能对应一个独立 SKILL.md + references/` 目录，可由宿主 Agent 按需加载。

插件与策略通过 extension/platform/examples/ 下的可运行示例引导：

• audit-observer：最简 Observer，演示如何记录所有命令至 stderr。
• readonly-policy：策略插件，调用 Restrict(&Rule{MaxRisk: platform.RiskRead, Allow: []string{"docs/","im/"}})，构建器自动开启 FailClosed + Restricts=true；越权命令将返回 command_denied 信封。资料来源：extension/platform/examples/readonly-policy/README.md:9-32。

Sandbox 侧车（sidecar）通过环境变量 LARKSUITE_CLI_AUTH_PROXY 提供凭据代理与身份注入；--strict-mode 强制将沙箱锁定到单一身份。资料来源：sidecar/server-demo/README.md:25-50。

5. 契约治理与社区关注点

internal/qualitygate/ 通过静态分析守护 CLI 机器可读契约：命令/Flag 命名、Skills 引用、--dry-run 示例、默认输出事实与命令边界错误约定。REJECT 失败阻断 CI；LABEL 与 WARNING 给出提示。legacy-commands.txt 与 legacy-flags.txt 列出暂不更名的历史命令/Flag，新增条目需匹配 CODEOWNERS 审批。资料来源：internal/qualitygate/config/README.md:1-50。lint/ 子模块按领域组织规则（errscontract/、flagnaming/），顶层 main.go 统一退出码：0 干净、1 含 REJECT、2 域扫描失败。资料来源：lint/README.md:1-40。

社区集中反馈的三类与命令系统相关的问题：

1. 多用户授权（#204）：当前 --as 面向个人助理；企业 Agent 需要按 open_id 分发不同凭据与权限。资料来源：README.md:55-70。
2. Skill 全量安装（#501、#1385、#1497）：默认安装会注入 20+ lark-* 技能，导致 Agent 上下文膨胀并污染技能列表；建议支持按需加载与子目录分类安装。资料来源：issue #1497 与 issue #501。
3. 个人身份调用（#234、#89）：用户希望在不创建应用的情况下以个人身份发消息或写表格。api 命令的 --as 已经支持 user/bot，但需要预先完成用户 OAuth 登录流程。资料来源：cmd/api/api.go:60-80。

See Also

• 安全与风险警告
• 插件 SDK 与策略契约
• 质量门禁
• 原始 API 命令实现

总览

lark-cli 在底层 API 之上,为 AI Agent 提供三个相互独立又相互协作的扩展面:

1. Skills —— 面向 Agent 的领域知识包,遵循 SKILL.md + references/ 的标准化目录结构,通过 lark-cli skill install 等命令注入到 Agent 上下文。README.md 指出项目出厂自带 24-26 个 Skill,覆盖 18 个业务域。
2. Events —— 基于 lark-event 技能提供的 WebSocket 实时事件订阅能力,支持正则路由与 Agent 友好的输出格式。
3. Extensibility(插件 SDK) —— 位于 extension/platform 目录的 Go 语言插件框架,允许外部二进制在命令分发前后插入 Observer、Wrap、Restrict 钩子,实现审计、限流、只读策略等横切关注点。

三个面向共享同一份 lark-cli 二进制,但生命周期不同:Skill 是用户态内容、Event 是网络层能力、Plugin 是进程内扩展点。下面的章节将分别展开。

Skills 系统

Skill 的结构与分发

README.md 描述了 Skill 的产品定位——"Agent-Native Design",出厂 24+ 个结构化 Skill,兼容主流 AI 工具,Agent 零配置即可操作 Lark。Skill 采用 Markdown 作为唯一承载形式,典型的目录结构是 skills/<skill-name>/SKILL.md,以及可选的 references/ 子目录用于补充长篇资料。

社区反馈显示,这种"全量本地安装"模式随着 Skill 数量增长暴露了上下文膨胀和触发歧义两个问题(参见 issue #501)。另有用户提出应将 lark 官方 Skill 隔离到独立子目录,以避免污染第三方 Skill 列表(issue #1497、#1385)。

格式校验流水线

为保证每个 SKILL.md 都符合发布规范,仓库在 scripts/skill-format-check/ 下提供独立校验脚本,核心规则如下:

校验模板定义在 skill-template/skill-template.md,lark-shared 被显式排除在检查之外。该脚本在 PR 与 push 阶段由 GitHub Actions .github/workflows/skill-format-check.yml 自动执行,资料来源:scripts/skill-format-check/README.md:1-20。本地复跑命令为 node scripts/skill-format-check/index.js [path]。

与质量门禁的耦合

internal/qualitygate/config/README.md 明确指出:Skill 内容是机器可读的 CLI 契约的一部分,质量门禁会针对 skills/lark-wiki/SKILL.md 等文件进行行级语义审查,违规项通过 waivers.txt 进行带 owner 和到期时间的临时豁免。这意味着修改 Skill 文案不仅是文案工作,也会触发质量门禁,资料来源:internal/qualitygate/config/README.md:1-30。

事件订阅(lark-event)

lark-event 技能提供实时事件订阅能力,基于 WebSocket 长连接,支持:

• 正则路由 —— 将事件 payload 匹配到具体业务处理函数;
• Agent 友好输出 —— 事件结果以结构化 Markdown 落盘,便于 Agent 直接消费;
• 运行时身份 —— 与命令层一样,支持 as=bot / as=user 的身份选择。

事件订阅本身复用 internal/client/ 中的分页与错误处理逻辑:当驱动侧 SDK 报 JSON 解析错误时,会被 WrapDoAPIError 包装为 InternalError{SubtypeInvalidResponse} 并附带"是否漏写 --output"的提示,资料来源:internal/client/api_errors.go:1-30。这意味着事件型调用同样受 --dry-run 与 --output 规则保护。

插件扩展(Plugin SDK)

钩子与生命周期

extension/platform/README.md 定义的 SDK 在命令分发链路上暴露四类钩子:Observer、Wrap、Restrict 以及进程级 On(Startup) / On(Shutdown)。运行时的典型交互如下:

sequenceDiagram
    participant Host as lark-cli Host
    participant SDK as Plugin SDK
    participant Plugin as 外部插件

    Note over Host,Plugin: 启动阶段
    Host->>SDK: Install(Registrar)
    SDK->>Plugin: Observe / Wrap / Restrict / On(Startup,Shutdown)
    SDK->>Plugin: On(Startup) fire

    Note over Host,Plugin: 每次命令分发
    Host->>SDK: hook chain (按注册顺序)
    SDK->>Plugin: Observer Before
    SDK->>Plugin: Wrap (包裹 RunE)
    SDK->>Plugin: Observer After

    Note over Host,Plugin: 进程退出
    Host->>SDK: Emit(Shutdown)
    SDK->>Plugin: On(Shutdown) fire

安全契约

SDK 强制以下不变量(资料来源:extension/platform/README.md:1-50):

• 调用 Restrict() 的插件必须声明 FailClosed,Builder 会自动校正;底层 Plugin 接口会以 restricts_mismatch 拒绝违规配对;
• 同一二进制中只允许一个插件贡献 Restrict 规则,第二方独立插件再调用会触发 multiple_restrict_plugins,避免任意外部插件扩大授权面;
• command_denied 决定会绕过 Wrap 链,但 Observer 仍会触发,确保审计型插件能观察到被拒绝的派发。

仓库自带两个示例:extension/platform/examples/audit-observer 与 readonly-policy,均通过 make examples-build 参与 CI,防止与 SDK 漂移,资料来源:extension/platform/examples/README.md:1-10。

与命令 API 的桥接

cmd/api/api.go 暴露的 --as、--dry-run、--output、--page-all 等通用旗标在插件 Wrap 钩子看来是透明的,钩子拿到的是 *cobra.Command 与已构造的 APIOptions。这种设计让审计插件可在 Observer Before 中读取即将发出的身份(opts.As)与 --dry-run 状态,从而区分"真实调用"与"预演",资料来源:cmd/api/api.go:1-50。

已知问题与社区反馈

• Skill 全量安装导致上下文膨胀 —— issue #501 实测本地 19 个 lark Skill 占用 22,343 行、212 个文件,推动后续"按需加载"方案;
• Skill 目录污染 —— issue #1497 与 #1385 建议将官方 Skill 隔离到 lark/ 子目录,避免与其他用户 Skill 混排;
• 多用户身份管理 —— issue #204 期望插件 SDK 能按 openid 区分授权,这恰好是 Restrict 钩子未来可承载的能力;
• PR 自动化 —— scripts/pr-labels/ 通过 domain/* 标签标记 PR 触及的业务域,当前覆盖 im、vc、ccm、base、mail、calendar、task、contact,以便审查者快速评估 Skill 与插件改动的影响面,资料来源:scripts/pr-labels/README.md:1-30。

See Also

• README.md — 项目主入口与 Skill 全景列表
• extension/platform/README.md — 插件 SDK 完整契约
• internal/qualitygate/config/README.md — Skill 与命令的语义门禁策略
• scripts/skill-format-check/README.md — Skill 格式校验脚本
• issue #501 — Skill 按需加载讨论

Pitfall Log / 踩坑日志

项目：larksuite/cli

摘要：发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Feature request: Install skills into a dedicated subdirectory/category instead of root skills directory。

1. 安装坑 · 来源证据：Feature request: Install skills into a dedicated subdirectory/category instead of root skills directory

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: Install skills into a dedicated subdirectory/category instead of root skills directory
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/larksuite/cli/issues/1497 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 失败模式：installation: Feature request: Install skills into a dedicated subdirectory/category instead of root skills...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Feature request: Install skills into a dedicated subdirectory/category instead of root skills directory
• 对用户的影响：Developers may fail before the first successful local run: Feature request: Install skills into a dedicated subdirectory/category instead of root skills directory
• 证据：failure_mode_cluster:github_issue | https://github.com/larksuite/cli/issues/1497 | Feature request: Install skills into a dedicated subdirectory/category instead of root skills directory

3. 安装坑 · 失败模式：installation: v1.0.52

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.0.52
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.52
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.52 | v1.0.52

4. 配置坑 · 失败模式：configuration: v1.0.47

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.0.47
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.47
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.47 | v1.0.47

5. 配置坑 · 失败模式：configuration: v1.0.51

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.0.51
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.51
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.51 | v1.0.51

6. 配置坑 · 失败模式：configuration: v1.0.53

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.0.53
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.53
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.53 | v1.0.53

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://www.npmjs.com/package/@larksuite/cli | README/documentation is current enough for a first validation pass.

8. 运行坑 · 失败模式：runtime: v1.0.50

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v1.0.50
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.50
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.50 | v1.0.50

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@larksuite/cli | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://www.npmjs.com/package/@larksuite/cli | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://www.npmjs.com/package/@larksuite/cli | no_demo; severity=medium

12. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@larksuite/cli | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@larksuite/cli | release_recency=unknown

14. 维护坑 · 失败模式：maintenance: v1.0.46

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.46
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.46
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.46 | v1.0.46

15. 维护坑 · 失败模式：maintenance: v1.0.48

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.48
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.48
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.48 | v1.0.48

16. 维护坑 · 失败模式：maintenance: v1.0.49

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.49
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.49
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.49 | v1.0.49

17. 维护坑 · 失败模式：maintenance: v1.0.54

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.54
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.54
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.54 | v1.0.54

18. 维护坑 · 失败模式：maintenance: v1.0.55

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.55
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.55
• 证据：failure_mode_cluster:github_release | https://github.com/larksuite/cli/releases/tag/v1.0.55 | v1.0.55