CLI 插件

May 31, 2026 · View on GitHub

本期在 12.plugin_cli.md（CLI 插件首期）基础上做体验优化，并引入通用 Skills 系统 作为后续扩展能力的承载。本文只描述「需求」，不涉及技术实现。

实施时同时遵循 docs/dev/00.rules.md。

1. 目标与背景

  • 首期 CLI 插件已上线：用户可以从 npm 装 CLI、由 AI 调用、走交互式登录。
  • 实际使用中暴露两类问题：
    • 流程上：npm 安装是阻塞式的，弹窗必须等到结束，多个 CLI 串行装、用户被强制等待。
    • 入口上：让用户自己找 npm 包名门槛高；用户更习惯丢一个文档链接或文档正文，由 AI 完成接入。
  • 同时观察到「让 AI 按一份既定指引完成某类任务」是高频通用诉求（不止 CLI 安装），值得抽出成可复用的 Skills 系统。

本期的两个核心目标：

  1. 降低 CLI 接入门槛、消除等待感：删除冷门入口、改后台执行、新增「从官方文档安装」。
  2. 搭起 Skills 通用框架：以「从官方文档安装 CLI」为首个落地场景验证框架，后续 MCP 接入、自动登录、复杂工作流等都能在同一框架上扩展。

2. 与首期的关系

  • 沿用 data_models.ExtensionItem 数据模型与 kind: "cli" 分类。
  • 沿用「插件运行时（内置 Node.js / npm）」、{data_dir}/plugins/cli/{name}/ 安装目录、cli_data/{name}/ 数据目录、manifest 结构。
  • 沿用「插件与工具」设置页的列表 + 详情双列布局。
  • 沿用首期已有的 CLI 调用、登录、隔离 env、审批机制。
  • 本期不重做以上能力，只新增 / 调整后文所列需求。

3. 需求列表

3.1 简化 CLI 安装入口

  • 删除「添加 → CLI → 从本地目录导入」入口。
  • 「添加 → CLI」下保留并新增：
    • 从 npm 安装（已有）
    • 从官方文档安装（本期新增，见 3.3）

3.2 CLI 安装改为后台执行

  • 用户在「从 npm 安装」对话框输入包名、点击确认后：
    • 对话框立即关闭，不再阻塞用户。
    • 安装任务转入后台执行。
  • 后台执行期间：
    • 「插件与工具」列表中对应 CLI 项实时显示进度与当前阶段。
    • 用户可关闭设置页、切换到聊天页或其他页面，任务不中断。
    • 同时可发起多个不同 CLI 的安装任务，互不干扰。
  • 任务结束：
    • 成功：列表项变为「已启用」状态，可被 AI 调用。
    • 失败：列表项给出错误摘要与「重试」「查看详情」入口。
  • 中途若需用户介入（包名歧义、需要补充信息、需要二次确认等）：见 3.5 的统一规则。

实现层面允许（也鼓励）将本流程作为一个「隐藏会话」托管在 Agent / Skills 体系中——这是与首期相比的关键变化。

3.3 从官方文档安装 CLI

  • 「添加 → CLI → 从官方文档安装」打开一个对话框：
    • 单一文本输入框（多行，无格式约束）。
    • 用户可粘贴任意内容：文档 URL、文档正文（Markdown / 纯文本）、自然语言描述，或上述任意组合。
    • 不强制用户区分输入类型，应用提交后由 AI 自行理解与处理。
  • 提交后：
    • 当前设置页不跳转。
    • 安装任务进入后台执行，复用 3.2 的进度、并发、列表反馈规则。
    • AI 在后台完成以下事项（用户感知不到细节）：识别包名 / 抓取必要文档 / 触发 npm 安装管线 / 生成 manifest / 完成接入。
  • 失败兜底：
    • 输入无法解析或 AI 无法确定包名时，触发 3.5 的「需要介入」流程，向用户请求补充信息。

3.4 Skills 系统（通用框架）

引入 Skill 作为一等公民概念，表达「一段教 AI 如何完成某类任务的指引」。

3.4.1 单 skill 形态

  • 对齐当前事实标准（Claude Code / Codex / Cursor 等同源约定）：
    • 一个目录 = 一个 skill，目录名即 skill 名（kebab-case）。
    • 入口文件为 Markdown（SKILL.md）。
    • 顶部 YAML frontmatter，至少包含：
      • name：skill 标识。
      • description：触发线索，AI 据此判断"什么时候该用"。
    • 正文为给 AI 的自然语言指引，可包含步骤、注意事项、安全约束。
    • 可携带配套文件（references/、scripts/、assets/ 等），由正文按需引用。
  • 不引入 Lemontea 私有字段；后续若需要扩展，以 frontmatter 加字段的方式向后兼容。

3.4.2 存放位置

  • 所有 skill 收纳到 {data_dir}/skills/<skill-name>/。
  • 内置 skill 与用户 / AI 生成 skill 共用同一根目录，按来源做标识区分（不另开目录层级）。

3.4.3 来源（本期 MVP 三类）

  • 应用内置：随应用版本发布，包含"从官方文档安装 CLI"等官方 skill；用户不可删除或修改。
  • 用户手动创建：用户可在 Skills 设置页内从零新建一个 skill（编辑 frontmatter + 正文），也可以从本地文件或粘贴内容导入；创建 / 导入后均可查看、启用 / 禁用、编辑、删除。
  • AI 运行时生成：AI 在聊天中可主动产出一个新 skill 并落盘；落盘前必须经过用户二次确认（默认行为，不可绕过）。

远程市场 / 远程仓库分发本期不实现，仅在概念上预留扩展位（见 §5）。

3.4.4 触发方式

  • 聊天中 AI 自动选择：所有启用的 skill 的 name + description 对 AI 可见，AI 在合适时机自行套用。
  • 聊天中用户显式调起：用户输入 /<skill-name> 显式触发对应 skill。
  • 应用内入口静默触发：如 3.3「从官方文档安装 CLI」由设置页入口直接绑定到指定 skill，用户不感知 skill 概念。

3.4.5 管理 UI

  • 在「设置」侧栏新增一级页面 Skills，与「插件与工具」并列。
  • 页面承载：
    • skill 列表（按来源分类显示：内置 / 用户 / AI 生成）。
    • 启用 / 禁用 开关（内置 skill 也可被用户禁用，但不可删除）。
    • 查看详情（frontmatter + 正文 + 配套文件清单）。
    • 用户 skill：新建（在 UI 中直接编辑 frontmatter + 正文）、导入（本地文件 / 粘贴）、编辑、删除。
    • AI 生成 skill：编辑、删除。

3.5 隐藏会话与"需要介入"统一规则

3.2 / 3.3 的后台任务在实现上视为一个不出现在聊天列表中的 AI 会话。该会话可能在执行过程中发现自己缺信息、需要权限、或要做关键决定。统一规则：

  • 默认情况下用户感知不到这个会话的存在，只看到列表项进度。
  • 当会话明确需要用户介入时：
    • 全局通知（应用内的统一通知通道）提示用户有任务待处理。
    • 用户点击通知，弹出独立小窗承载该会话的对话内容，用户可回复、补充信息或同意 / 拒绝。
    • 用户处理完毕后小窗关闭，任务继续在后台执行。
  • 该规则适用于所有 3.2 / 3.3 触发的隐藏会话，未来其他 skill 走相同流程。

4. 用户故事

  • 想最快接入 CLI 的用户：复制官方文档 URL，粘到「从官方文档安装」输入框，提交后切回聊天页继续干别的；几十秒后看到列表里 CLI 已就绪，向 AI 提问即可使用。
  • 熟悉 npm 的用户：知道包名，直接「从 npm 安装」，提交后立刻回到工作流，不再被弹窗卡住。
  • 同时接两个 CLI 的用户：先发起 A 的安装，转头发起 B 的安装；两条进度条并行在列表里更新，互不阻塞。
  • AI 重度用户：在聊天里直接说「帮我装一个飞书 CLI，文档在 https://...」，AI 自动用上「从官方文档安装 CLI」skill，进入与 3.3 等价的流程。
  • 想沉淀重复工作流的用户：手动从本地文件导入一个自己写的 skill（比如「按公司规范生成季度报告」），后续在聊天里 AI 自动用上。
  • 被 AI 帮过一次的用户：聊天里完成一次复杂任务后让 AI 「把这套流程记下来」，AI 提示要新建 skill，确认后落盘，下次同类需求自动复用。

5. 不在本期范围

  • Skills 的远程市场 / Git 仓库 / HTTP URL 拉取。
  • Skills 的版本管理、依赖管理、更新通知。
  • Skills 的细粒度权限 / 沙箱模型；本期 skill 走 AI 现有工具权限边界，不另设权限层。
  • CLI 插件本身的版本升级 UI（沿用首期：重装即覆盖）。
  • CLI 插件 / Skill 的多语言文案系统级重构；新增 UI 文案沿用首期的简体中文 + 英文双语方案。

6. 验收要点

在干净环境下，按以下顺序应可全程走通：

  1. 「添加 → CLI」下拉中不再出现「从本地目录导入」入口，但出现「从官方文档安装」入口。
  2. 「从 npm 安装」提交后弹窗立即关闭；列表项可见进度；用户切到其他页或聊天页不中断安装；同时发起第二个 CLI 安装两者并行进行。
  3. 「从官方文档安装」：
    • 仅粘贴一个公开文档 URL，提交后能成功装好对应 CLI；
    • 仅粘贴文档正文（无 URL），同样能装好；
    • 粘贴一段自然语言描述（不含 URL，也不含完整文档），AI 无法决定时弹出「需要介入」通知 + 小窗，用户补充后任务继续完成。
  4. 隐藏会话中 AI 需要用户介入时，全局通知出现，点击后弹出小窗，回复后小窗关闭、任务继续。
  5. 在聊天里说「帮我装一个 XX cli：」，AI 自动调用「从官方文档安装 CLI」skill，效果与 3 一致。
  6. 「设置 → Skills」页存在，展示内置 skill（含「从官方文档安装 CLI」）、用户 skill、AI 生成 skill 三类；内置 skill 可禁用但不可删除；用户可从零新建 skill（在 UI 中直接编辑 frontmatter + 正文）、也可从本地文件 / 粘贴导入；用户 / AI skill 可编辑、删除。
  7. 在聊天里输入 /<skill-name> 能显式调起对应 skill。
  8. AI 在聊天里产出一个新 skill 时，用户必须二次确认才会落盘到 {data_dir}/skills/。