command-add-remove

命令增删改

触发条件

• 增加新的 bl xxx 命令
• 删除已有命令
• 重命名命令(包括从单级 bl x 改成 bl x y 或反向)
• 调整某个 shared command 在 bl / kscli 等产品入口里的暴露路径

命令实现与产品路径的关系

命令实现住在 packages/commands,产品路径由入口包决定。实现文件路径按能力组织,但不再等同于最终命令路径。

实现文件:
  packages/commands/src/commands/knowledge/retrieve.ts
    ↓ packages/commands/src/index.ts export { default as knowledgeRetrieve }
产品入口:
  packages/cli/src/commands.ts  "knowledge retrieve": knowledgeRetrieve  ↔ bl knowledge retrieve
  packages/kscli/src/main.ts    "retrieve": knowledgeRetrieve             ↔ kscli retrieve

常见路径形态:

单级命令:  packages/commands/src/commands/update.ts              ↔ bl update
两级命令:  packages/commands/src/commands/text/chat.ts           ↔ bl text chat
子组命令:  packages/commands/src/commands/memory/profile-get.ts  ↔ bl memory profile get

子组要慎用:只有子组下有 ≥2 个 action 时才合理,否则优先拍平到两级。

CLI 命令注册架构(必读)

packages/commands 是命令库,只导出单个 command;不内置 path presets,不关心 bl / kscli。每个产品入口传入自己的 command map,runtime 负责解析、help、鉴权、遥测、执行。

packages/commands/src/commands/<...>.ts
  defineCommand({ auth, flags, usageArgs, exampleArgs, validate, run })
        ↓
packages/commands/src/index.ts
  export { default as xxxCommand } from "./commands/...ts"
        ↓
┌──────────────────────────────┬──────────────────────────────┐
│ packages/cli/src/commands.ts │ packages/kscli/src/main.ts   │
│ { "text chat": textChat }    │ { "retrieve": knowledge... } │
└──────────────┬───────────────┴──────────────┬───────────────┘
               ↓                              ↓
        createCli(commands, identity)  →  runtime registry/help/middleware
               ↓
        tools/generate-reference.ts reads packages/cli/src/commands.ts

• packages/commands/src/commands/<...>.ts:命令实现;usageArgs / exampleArgs 只写参数片段,不写 bl / kscli 前缀
• packages/commands/src/index.ts:导出命令实现;新增命令必须在这里 re-export
• packages/cli/src/commands.ts:bl 产品命令 map;新增/删除/重命名 bl 命令必须改这里
• packages/kscli/src/main.ts:kscli 产品命令 map;只有该入口需要暴露/变更时才改
• packages/runtime/src/registry.ts:通用 registry,从传入 map 建树;不要在这里登记业务命令
• tools/generate-reference.ts:pre-commit / pnpm run sync:skill-assets 时读 packages/cli/src/commands.ts,按 GROUP_OWNER_SKILL 归属表分流写到各 skills/<skill>/reference/index.md + <一级命令>.md。未显式归属的一级组默认进 bailian-cli。各目录纳入 git,勿手改。新增一级命令组若应归领域 skill,记得改归属表。