0028-skill-cli-device-login.md 2.4 KB
ADR-0028 技能推送工具：Node 命令行 + 设备码浏览器登录
- 状态：Accepted · 日期：2026-11-03 · 补充 ADR-0027 · 设计见 19-skill-cli
背景
技能发布平台（ADR-0027）需要一个推送工具。推送方是各个项目的开发机（常通过 SSH / VS Code Remote 在远程机器上开发）和 CI；手动复制、保管发布密钥不方便。
决策
- 只提供 Node 命令行工具：打包成不带依赖的单文件
@agent-server/skills-cli，不发布到 npm 官方仓库。开发机与 CI 普遍有 Node；不另做 Python / Shell 版本。 - 由平台自己的 npm 仓库分发（2026-11-04 修订）：服务在
/npm/提供只读的 npm 仓库协议（包信息 + 包文件，全部版本），用npx -y --registry $BASE/npm/ @agent-server/skills-cli@latest运行。最初用固定地址的 tgz（/sdk/agent-skills.tgz），实测 npx 按地址缓存安装目录，包更新后仍运行旧版本；@latest由 npx 向仓库确认最新版本，是 npm 的标准做法。SDK 的三个包一起迁移，/sdk/不再提供。全局安装或锁定版本时，工具每次执行前查询仓库，有新版本时改用新版本重新执行。 - 开发机用浏览器登录：采用 OAuth 设备码授权（RFC 8628）的流程与错误码。浏览器与终端可以不在同一台机器上；管理员核对验证码后批准，终端下一次询问时才签发普通的发布密钥（平台不保存明文），保存在用户目录（权限 600）。CI 继续使用后台创建、存为加密变量的密钥。
- 配置分层：命令行参数 > 环境变量 > 项目
.agent-skills.json（不含密钥，可提交）> 用户目录的登录信息，密钥不进入项目。 --wait默认关闭：等待审核适合本机开发；CI 中只推送。超时用单独的退出码 5（仍在待审核），与失败、拒绝（4）区分。
后果
- 本机推送不需要接触密钥明文；登录签发的密钥在后台可见、可停用，
logout会在服务器上停用它。 - 设备码授权存在"诱导管理员批准别人的申请"的风险：审批页显示来源 IP、机器名、系统用户并给出提示；签发的密钥只能产生待审核的提交，影响有限。
- 推送工具与服务端各自实现一份技能识别与预检规则，修改限额或规则时两边需要同步（测试覆盖了主要路径）。