@qilin-agent/cli
v3.1.12
Published
qilin CLI: profile launch, plugin management, and configuration inspection
Readme
@qilin-agent/cli
English | 中文
qilin 是唯一受支持的 Node 应用启动器;profile 由多个插件组合包 patch 层按顺序叠加而成,其上再应用用户自己的覆盖配置。SDK 与 ACP(Agent Client Protocol)都是 profile,而不是独立的公开可执行命令。Python 运行时 wheel 包中也包含同一个命令;SDK 默认使用 sdk,极简示例选择 sdk-minimal。src/args.ts 负责命令语法,src/bin.ts 只加载选中的运行器。无效命令、来自其他模式的选项,以及致命的配置或启动错误都会以非零状态退出。
入口模式
| 命令 | 用途 |
|---|---|
| qilin <name> / qilin --profile <name> | 启动位于 $QILIN_HOME/profiles/<name> 的指定 profile。 |
| qilin --profile <name> --from-default-profile <template> | 从随附模板创建新的自定义 profile,然后启动它。 |
| qilin --profile acp | 通过 ACP stdio 为自动化客户端提供服务,直至断开连接。 |
| qilin --profile headless "job" | 运行一个全新的持久化会话,打印最终答案并退出。 |
| qilin --profile sdk | 通过 JSON-RPC stdio 为 SDK 客户端提供服务,直至关闭或断开连接。 |
| qilin --profile sdk-minimal | 以独立极简 agent(智能体)配置树为 SDK 客户端提供服务。 |
| qilin、qilin web | 在一个地址上服务整套部署:每个账户一个隔离的 Web 运行时,各自服务应用自己的落地页与登录表单。你原本就在启动的那个 profile 就是整套部署。 |
| qilin tenants accounts | 列出本 harness home 的账户,以及每个账户拥有的租户目录。 |
| qilin tenants add <用户名> | 创建一个账户,交互式输入密码,或读取 --password-stdin。 |
| qilin tenants passwd <用户名> | 替换某个账户的密码,并使其已签发的会话失效。 |
| qilin tenants remove <用户名> | 注销某个账户,默认保留其租户目录,除非给出 --purge-data。 |
| qilin plugin --profile <name> <pnpm args> | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
| qilin plugin list | 按激活顺序列出某个 profile 的 bundle 层;省略 --profile 时使用产品 profile。 |
| qilin plugin doctor <包名\|目录> | 报告某个插件包的 DSH 时代兼容性,不安装也不运行任何东西。 |
会服务浏览器的 profile——产品面 qilin 与 qilin web——就是整套部署:一条命令,一个地址,没有第二个入口。入口自己不作画:它按需在 $QILIN_HOME/tenants/<账户 id>/ 下为每个账户启动一个 Web 运行时,并把浏览器发出的每个请求——应用文档、/api 通道、mux 升级与带 Range 的媒体读取——转发到它的路由 cookie 所命中的那个运行时,同时把运行时自己的 authority 顶替掉入口的,从而让它的会话 cookie 始终绑定在签发它的那个运行时上。运行时的 harness home 归它自己:会话、任务、工作区、附件、插件、模型设置、凭据、技能与预设都在其中解析,只有 $QILIN_HOME/auth/accounts.json 这份名册是共享的。凭据由被指名账户自己的运行时校验:入口把登录提交转发到那里,并中继它签发的会话 cookie;运行时只接纳自己的账户,因此伪造的路由 cookie 只会到达一个不认可调用者的运行时。--idle-ms 会回收在该时长内没有服务过任何流量的运行时,0 表示不回收;--max-tenants 限定同时存活多少个运行时,超出上限时回收最久未使用的那个;--restart-backoff-ms 设定启动失败的运行时第一次重试前的等待,每次连续失败翻倍。--patch 让每个运行时都多叠一层 overlay;--tls-cert 与 --tls-key 让入口地址以 HTTPS 服务,并在 loopback 运行时之前终止 TLS,因此两者必须成对给出,且与 --per-account-ports 互斥。入口只读自己拥有的 flag:其余参数一律交给每个运行时自己的命令行,而 --host 拒绝通配地址。同一个浏览器一次只服务一个账户。落地页、登录表单与注册都归运行时内部的应用所有。名册里有账户时,裸地址会重定向到第一个账户的路径 /t/<账户>/,其余账户各自在自己的路径上可达。名册为空时,每个路径都交给首启运行时,它那一层的接纳判据就是名册里有什么就接纳什么,于是由产品自己的表单创建第一个账户,入口从不说明该输入什么。--registration open|closed 决定产品自己的表单能否创建账户:loopback 地址上默认为 open,其他地址上默认为 closed,因此别的机器能到达的地址只在运维明说时才创建账户(用 qilin tenants add);名册里没有的名字、指向一个名册已不再持有的账户的路由 cookie,以及其余任何没有指名账户的请求,都由同一个运行时回答,因此入口从不替应用说话。/healthz 与 /status 仍归入口自己读取。
roster 子命令维护该共享文件中的账户。租户运行时只接纳自己服务的那个账户且关闭注册,因此它自己的 Web 界面无法创建第二个账户;首启运行时承载的则是部署自己的策略,接受新账户的部署由此通过产品自己的表单扩充账户。add 无需浏览器即可创建账户,passwd 为一个账户重新设置密码并使其已签发的会话失效,remove 注销一个账户,默认把它的 Session 留在磁盘上,除非给出 --purge-data。为已注销账户启动的运行时会明确失败,因为它的覆盖层接纳的是一个文件里已不存在的账户。
运行命令时所在的目录将作为默认 workspace 根目录。web、headless、sdk、sdk-minimal 和 acp profile 在首次使用时会从随附模板自动初始化。使用 --from-default-profile 可以基于这些模板之一,在尚未使用的非内置名称处创建其他 profile;通过 qilin plugin 则可以初始化一个以 base 为基础的 profile。desktop 名称保留给 Electron 持有的 profile,因此 CLI(命令行界面)会拒绝针对它的启动、配置 dump 和插件管理请求。包操作成功后命令会协调 profile 的 bundle 列表;若 profile 的已安装依赖中出现上游 DSH 时代的引擎包,命令会拒绝:诊断会指明每个冲突包、它映射到的 QiLin 包,以及清除它的 remove 命令,命令以退出码 1 结束且不改变 bundle 列表。
list 与 doctor 只读取 profile,既不初始化它也不运行 pnpm。doctor 接受已安装的包名或包目录,检查插件要在此加载必须满足的四条规则:包是否自己拼出 DSH 时代的主目录而不是读取 DSH_HOME/QILIN_HOME、是否安装了 harness 已提供的引擎包、是否导入了未声明为 peer 的引擎名、以及是否注入了兼容层无法映射的客户端模块名。它每行输出一条发现,仅当某条发现会阻断激活时才以退出码 1 结束。
list 把随附模板层标为 (shipped):它随运行中的安装实例走,无法从 profile 移除。列表里其余每层都归 profile 所有——例如通过 qilin plugin add 安装的组合包——可原地升级或移除,无需等待 QiLin 发版。
命令本身从已发布的包安装(npm install -g @qilin-agent/cli)即可把 qilin 放到 PATH;manifest 把 lib/bin.js 声明为 qilin bin,并且只随包发布该 bundle。
应用参数
启动器只解析自身的 flag,并将其后的所有内容交给已启动的 profile;注入该 profile 的任意应用插件都可以解析这份共享的不可变快照(qilin-cmdline)。启动器无法识别的第一个 token 标志着应用参数的开始:
qilin --profile web --port 8080 # --port is the deployment's address
qilin --profile tui --resume <id> # example, assuming the tui profile is installed; --resume belongs to the terminal app
qilin --profile headless "run the tests"
qilin --profile web --patch ./extra.cordis.yml # the overlay every account's runtime composes with
qilin --profile web --help # the deployment's flags, then the app's
qilin --help # the launcher's own helpProfile
profile 目录包含一个 package.json,其中记录树外插件依赖,以及 profile manifest(元数据清单)qilin.profile、其中按顺序排列的 bundles 列表;还包含一个 cordis.patch.yml,其中保存用户自己的 patch 层。在 YAML 中启用的 qilin-hmr 监视 profile manifest、profile 与 home 级 patch 文件,再通过统一串行重载重新组合所有层。未启用 HMR 时,更改在重启后生效。监听器注册期间发生的编辑与后续编辑使用相同的非致命重载错误报告。插件管理器 与 qilin plugin 共享包操作和 profile 写锁;更新依赖会保留已停用的组合包选择。CLI 包操作继承认证环境和终端描述符,支持交互式构建批准;service 调用保留清理后的环境并捕获诊断。
安装与 profile 启动会用 qilin --version 打印的同一个运行时版本校验已声明的 qilin peer 范围。不兼容的插件必须显式确认精确版本豁免,qilin plugin allow-version、revoke-version 与 version-exemptions 按 profile 管理这些豁免。插件管理器兼容性参考记录了命令、持久化方式与风险。
配置树以空根为起点,依次叠加以下配置层:
qilin.profile.bundles中各组合包的 patch- profile 自身的
cordis.patch.yml,然后是 home 级的$QILIN_HOME/cordis.patch.yml --patch指定的覆盖层
qilin.profile.bundles 中列出的组合包先从 qilin 安装目录解析(@qilin-agent/base、@qilin-agent/web-app、@qilin-agent/headless、@qilin-agent/sdk-app、@qilin-agent/sdk-minimal、@qilin-agent/acp-app),再从 profile 自身的 node_modules 解析;pnpm 会将树外插件安装到该目录。
使用 --dump-default-config 和 --dump-config 可在不启动的情况下检查组合后的配置树。
层的确切优先级、flag、关闭行为、部署默认值和源码执行方式,以 CLI 行为参考为准。启动与重载失败表对比 optional、required 插件启动失败与配置 HMR 的行为。
可选覆盖层
config/examples/ 交付 GitHub 评审 webhook、会话内 Schedule、记忆 MCP 服务器与运行时 Kylin 工具的可选覆盖层。它们绝不属于默认 profile;设置与安全说明由用户指南和开发实战指南负责。
开发
生产运行需要已构建的包与前端产物。请在仓库根目录单独运行 pnpm run build,然后使用 pnpm qilin <args...> 运行 TypeScript 入口并转发所有参数;模块解析约定以源码执行参考为准。
@qilin-agent/cli/profile-boot 导出向 Desktop Host 提供共享 profile 生命周期。已解析的应用 profile 为运行时包解析指定自己的安装锚点,同时沿用 Harness home patch、代理环境、遥测开关、patch 热重载和有界关闭。
Web 失败矩阵在 test:expected 中通过构建后的 CLI 验证启动失败与启用 awaitWriteFinish 的原生配置 HMR。它不调用模型 API,而是检查经过认证的 HTTP 响应、诊断、恢复、进程退出与 dispose;启动验收测试还覆盖随附 Web 的必需依赖与端口冲突。
