larksuite / larksuite/cli

feat(skills): adopt agent-browser-style discovery stub — install a minimal stub, fetch full skill content at runtime via `lark-cli skills get`

Open
#1,696 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domain/core enhancement
Dominant language
Go
Stars
17.3k
Forks
1.4k
Avg merge
2d 4h
Merged PRs (30d)
105

Description

Feature Request

Summary: 采用 agent-browser 式的 discovery stub 设计——skills add 只装一个极简 stub SKILL.md,运行时通过 lark-cli skills get <domain> 动态拉取当前 CLI 版本对应的完整 skill 内容,从根上解决 #1465 / #1385 / #1392 的"27 个 lark-* skill 常驻上下文膨胀"问题。

参考实现:https://github.com/vercel-labs/agent-browser

Motivation

#1392 已经精确指出真正痛点:harness(Claude Code / Codex 等)在每次会话启动把所有已注册 skill 的 name + description 注入上下文,progressive disclosure 只对 SKILL.md 正文 + references 生效,对启动期的 description 列表不生效。所以 27 个 lark-* skill 的 description 全部常驻,这就是 #1465 / #1385 "skill 太多太乱、claude code 提醒描述超限"的根因。

现有的两条解法都有局限:

  • 精简 description(#1395 / #1452 走的路):能降 token,但 27 条 description 仍常驻,数量不降;且 description 太短会损害触发准确率(我在 #1465 实测:GLM-5.2 上削掉子层 description 会让重叠用例触发变差)。
  • single umbrella entry(#1432 试过的路):被关闭,关键拦路虎是 open.feishu.cn 主安装源 index-driven、root SKILL.md 短路在真实安装流不生效,且 skills add 只增不减导致新旧并存上下文反而变大。

agent-browser 的 discovery stub 正好绕开这些拦路虎:注册面(stub)和内容面(CLI 动态输出)解耦——stub 极简、占一条 description 的成本几乎为零;真实内容随用随取、永远匹配已安装 CLI 版本、不随 release 变陈旧。

Proposed Design

借鉴 agent-browser,lark-cli 已有(或计划有)skills read 子命令(#1432 引用过 lark-cli skills read <domain-skill>),在此基础上补齐 discovery stub 模式:

  1. 极简 stub 安装npx skills add larksuite/cli 只装一个根 stub(或每域一个 stub),其 SKILL.md 内容就是一个指针——"运行 lark-cli skills get <domain> 加载真实工作流"。stub 的 description 短到几乎不占启动期上下文。
  2. CLI 动态输出 skills 内容(复用/扩展现有 skills 子命令):
    • lark-cli skills list — 枚举可用 skill
    • lark-cli skills get <name> — 输出某 skill 当前版本完整内容
    • lark-cli skills get <name> --full — 含 references/templates
    • lark-cli skills get --all — 输出全部
    • lark-cli skills path [name] — 打印 skill 目录路径
    • 内容来自已安装 CLI 自带的 skill 数据目录(LARK_CLI_SKILLS_DIR 可覆盖),永远匹配当前 CLI 版本。
  3. 运行时流:agent 遇到 stub → 按 stub 指引跑 lark-cli skills get <domain> → CLI 输出当前版本完整指令 → agent 用取回的内容继续。注册与内容解耦。
  4. 配合 open.feishu.cn 真实安装流:把 #1432 关闭理由 2(index-driven 源下 root SKILL.md 短路不生效)作为本方案的前置验证项——stub 模式不依赖 root SKILL.md 短路目录扫描,而是依赖 CLI 自带内容输出,应能在 index-driven 安装流下生效。
  5. 避免新旧并存:配合 skills add 增删一致(解决 #1432 关闭理由 3),切到 stub 模式时移除旧的全量 domain skill 安装。
Why this resolves the related issues
  • #1392:stub 让启动期常驻的 description 从 27 条降到 1 条(或几条 stub),常驻 token 断崖式下降,且不靠"把 description 写短"——子 skill 完整 description 仍可通过 skills get 取回,触发准确率不受损(呼应 #1465 实测)。
  • #1465 / #1385:体感"太多太乱"消失,全局 skill 列表不再被 lark 污染(也顺带解 #1497 的"skill 装在根目录与用户自定义混在一起")。
  • #1432:绕开其三个关闭理由的工程拦路虎,把"opt-in umbrella"升级为更彻底的 stub+动态获取。
Prior art / references
  • agent-browser discovery stub:https://github.com/vercel-labs/agent-browser
    • stub 故意极简,指向 agent-browser skills get core 运行时加载
    • CLI skills list / get / get --full / get --all / path 子命令
    • 内容来自已安装包自带数据目录,AGENT_BROWSER_SKILLS_DIR 可覆盖
  • 本仓 #1432 已引用 lark-cli skills read <domain-skill>,基础设施部分就位
What I'd ask the maintainers to evaluate
  1. lark-cli skills 子命令现状(read 之外是否已有 get/list/path),能否直接承载 stub 模式。
  2. stub 模式在 open.feishu.cn index-driven 真实安装流下是否生效(#1432 关闭理由 2 的前置验证)。
  3. 是否接受把"opt-in umbrella"(#1392 方向)升级为 discovery stub,作为 #1465 / #1385 / #1392 的统一解。
Context

我在 #1465 做的 GLM-5.2 小样本实测结论是"router 对触发准确率无差别、削掉子层描述会更差"——这恰好说明靠精简/自隐 description 来降上下文是有代价的,而 discovery stub 是不牺牲准确率的降上下文路径,值得官方大范围评估。

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inspecting the existing lark-cli skills commands, especially skills read, the installed skill data directory, and the LARK_CLI_SKILLS_DIR override. Verify the proposed list, get, and path behavior against the index-driven open.feishu.cn installation flow; done means a minimal stub installs, runtime retrieval returns the matching skill content, and old full domain skills do not remain alongside it.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.