skills/modelstudioai__cli
1
0
Fork 0
mirror of https://github.com/modelstudioai/cli.git synced 2026-09-14 19:49:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: align agent and skill docs with kscli split

Browse Source 
- replace stale rag/package references with kscli/knowledge-studio-cli
- update release docs for core/runtime/commands/cli plus kscli publishing
- refresh skill setup notes and generated reference output defaults
This commit is contained in:
若麒
2026-07-09 17:31:49 +08:00
parent 7ce018cc53
commit 749549aa28
11 changed files with 92 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+7 -7
View File
@@ -10,14 +10,14 @@ monorepo 现在按"纯逻辑 → 运行时框架 → 命令库 → 产品入口"
- `packages/runtime` — `bailian-cli-runtime`,通用 CLI 运行时:`createCli`、参数解析、registry/help、middleware、error handler、输出、pipeline
- `packages/commands` — `bailian-cli-commands`,可复用命令实现库,只导出 command,不决定产品路径
- `packages/cli` — `bailian-cli`,完整 `bl` 产品入口;`src/commands.ts` 组装 `bl` 暴露的命令路径
- `packages/rag` — `bailian-cli-rag`,知识库向入口;`src/main.ts` 复用 commands 并重映射为 `rag` 路径
- `packages/kscli` — `knowledge-studio-cli`,Knowledge Studio 专用入口;`src/main.ts` 复用 commands 并重映射为 `kscli` 路径
### 关键文件
```
packages/cli/src/main.ts # bl 入口,注入 binName/version/clientName/npmPackage
packages/cli/src/commands.ts # bl 产品命令 map,tools/generate-reference.ts 也读它
packages/rag/src/main.ts # rag 入口和命令 map
packages/kscli/src/main.ts # kscli 入口和命令 map
packages/commands/src/index.ts # re-export 单个命令实现
packages/commands/src/commands/ # defineCommand({ auth, flags, usageArgs, exampleArgs, run })
@@ -38,9 +38,9 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
约定:
- 命令实现文件路径仍按能力放置:`packages/commands/src/commands/text/chat.ts`
- 产品命令路径由入口 map 决定:同一个实现可暴露为 `bl knowledge retrieve` 或 `rag retrieve`
- 产品命令路径由入口 map 决定:同一个实现可暴露为 `bl knowledge retrieve` 或 `kscli retrieve`
- `defineCommand` 只写命令元数据与逻辑: `auth`、`flags`、`usageArgs`、`exampleArgs`、`validate`、`run`
- `usageArgs` / `exampleArgs` 不写 `bl` 或 `rag` 前缀;runtime / reference 生成器按产品路径补前缀
- `usageArgs` / `exampleArgs` 不写 `bl` 或 `kscli` 前缀;runtime / reference 生成器按产品路径补前缀
- 不再使用 `catalog.ts` 作为登记处;新增/重命名命令必须同时看命令库导出和产品入口 map
非代码资产:
@@ -75,14 +75,14 @@ Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/
### 1. 发布包版本号同步
源码包的 `version` 当前保持一致: `packages/core`、`packages/runtime`、`packages/commands`、`packages/cli`、`packages/rag`。做版本 bump 时一动多动。release 工具当前强校验 / 发布范围以 `tools/release/lib/packages.mjs` 为准;把新包纳入发布前必须同步该清单和 [publish.md](docs/agents/publish.md)。
源码包的 `version` 当前保持一致: `packages/core`、`packages/runtime`、`packages/commands`、`packages/cli`、`packages/kscli`。做版本 bump 时一动多动。release 工具当前强校验 / 发布范围以 `tools/release/lib/packages.mjs` 为准;把新包纳入发布前必须同步该清单和 [publish.md](docs/agents/publish.md)。
### 2. 分层边界
- `core` 是纯库:不依赖 `runtime` / `commands` / 产品入口;不调 `process.exit`;新增/改动时不硬编码 `bl` / `rag` 命令名、控制台 URL 或渠道追踪参数。当前遗留项见 [error-hint-change.md](docs/agents/error-hint-change.md) 与 [url-change.md](docs/agents/url-change.md),触碰相关代码时顺手收敛
- `core` 是纯库:不依赖 `runtime` / `commands` / 产品入口;不调 `process.exit`;新增/改动时不硬编码 `bl` / `kscli` 命令名、控制台 URL 或渠道追踪参数。当前遗留项见 [error-hint-change.md](docs/agents/error-hint-change.md) 与 [url-change.md](docs/agents/url-change.md),触碰相关代码时顺手收敛
- `runtime` 是通用 CLI 框架:可以处理 TTY、help、错误输出、middleware,但不写具体业务命令逻辑
- `commands` 是命令实现库:不决定产品路径;不在 `usageArgs` / `exampleArgs` / hint 里硬编码产品 bin 前缀
- `cli` / `rag` 是产品层:负责命令路径 map、产品 identity、README、技能 reference、发版入口
- `cli` / `kscli` 是产品层:负责命令路径 map、产品 identity、README、技能 reference、发版入口
- URL 集中在 `packages/runtime/src/urls.ts`(用户面控制台)和 `packages/core/src/config/schema.ts` / client 层(API)
### 3. 错误处理边界:CLI 不翻译服务端错误
docs/agents/auth-change.md
+3 -3
View File
@@ -62,7 +62,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
- 新增 credential 类型 / source / scope 字段
- [ ] `packages/core/src/auth/resolver.ts`:
- 新增或调整 resolver,保持优先级注释清晰
- 新增/调整 resolver hint 时保持产品无关,不要新增 `bl` / `rag` 硬编码;当前遗留的 `bl auth login` hint 如被触碰,迁到 runtime `enhanceHint`
- 新增/调整 resolver hint 时保持产品无关,不要新增 `bl` / `kscli` 硬编码;当前遗留的 `bl auth login` hint 如被触碰,迁到 runtime `enhanceHint`
- [ ] `packages/core/src/auth/store.ts`:
- 如果新方式需要持久化,扩展 `AuthStore` / `AuthPersistPatch`
- [ ] `packages/core/src/config/schema.ts`:
@@ -113,7 +113,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
```sh
# 各种凭证组合
unset DASHSCOPE_API_KEY DASHSCOPE_ACCESS_TOKEN
unset DASHSCOPE_API_KEY ALIBABA_CLOUD_ACCESS_KEY_ID ALIBABA_CLOUD_ACCESS_KEY_SECRET
HOME=/tmp/empty node packages/cli/src/main.ts auth status
# flag 注入(凭证域 flag 只在对应业务命令可见,auth status 不接收)
@@ -140,4 +140,4 @@ node packages/cli/src/main.ts usage stats --dry-run --output json
- ✗ `auth login` 写成功但 `auth status` 不识别(两边走的 storage path 不一致)
- ✗ token mask 显示完整 token,日志泄漏
- ✗ `auth: "console"` 命令误用 `apiKey` 域,config 只有 API key 时会把 `sk-...` 发到网关
- ✗ 新增 core resolver hint 时写死产品命令,导致 `rag` 等入口提示错误
- ✗ 新增 core resolver hint 时写死产品命令,导致 `kscli` 等入口提示错误
docs/agents/branch-merge-review.md
+9 -9
View File
@@ -50,7 +50,7 @@ git diff --name-only <base>...<head>
- [ ] **`package.json` 没破坏发布元数据**:`bin` / `exports` / `files` / `inlinedDependencies` 字段任何删除或改名都要单独评估
- [ ] **公共依赖没被悄悄升级**:catalog / 根 lockfile 改动要列出来
- [ ] **`package.json` version 没倒退**:目标分支已经更高时(如 main 1.0.3 vs head 1.0.0-beta.1),手动对齐版本号,不要被 head 覆盖
- [ ] **全局表没冲突**:`packages/cli/src/commands.ts` / `packages/rag/src/main.ts` command map、`defineCommand({ auth })`、`GLOBAL_FLAGS` / `MODEL_AUTH_FLAGS` / `CONSOLE_AUTH_FLAGS`、`ExitCode` 新增项不和现有项冲突
- [ ] **全局表没冲突**:`packages/cli/src/commands.ts` / `packages/kscli/src/main.ts` command map、`defineCommand({ auth })`、`GLOBAL_FLAGS` / `MODEL_AUTH_FLAGS` / `CONSOLE_AUTH_FLAGS` / `OPENAPI_AUTH_FLAGS`、`ExitCode` 新增项不和现有项冲突
## 清单 B:用户透出(用户可见的新东西必看)
@@ -94,11 +94,11 @@ git diff --name-only <base>...<head>
## 常见漏点(基于历史踩坑)
| 漏点 | 后果 |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `pnpm-workspace.yaml` 把 `packages/*` 收窄成显式列表 | 合并后目标分支的新子包不再被 workspace 识别,`pnpm install` 看似正常但子包失联 |
| 源分支 version 比目标分支低,直接 merge 覆盖 | npm 上版本号回退,latest tag 错乱 |
| `packages/cli/src/commands.ts` 注册新命令但忘了 [README](README.md) / [README.zh](README.zh.md) | 用户完全感知不到新功能 |
| 共享 util 重构(抽公共函数)只改了一处调用方 | 其它调用方静默走旧分支,行为分裂 |
| 命令 `auth` 域设错（如 Console Gateway 用了 `apiKey`） | 凭证域 flag/help/credential 注入都错,运行期才暴露 |
| `packages/cli/src/commands.ts` / `packages/rag/src/main.ts` 这类 map 两边都加项,解冲突时被合掉一侧 | 某个新命令注册丢失,编译能过、回归不易察觉 |
| 漏点 | 后果 |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `pnpm-workspace.yaml` 把 `packages/*` 收窄成显式列表 | 合并后目标分支的新子包不再被 workspace 识别,`pnpm install` 看似正常但子包失联 |
| 源分支 version 比目标分支低,直接 merge 覆盖 | npm 上版本号回退,latest tag 错乱 |
| `packages/cli/src/commands.ts` 注册新命令但忘了 [README](README.md) / [README.zh](README.zh.md) | 用户完全感知不到新功能 |
| 共享 util 重构(抽公共函数)只改了一处调用方 | 其它调用方静默走旧分支,行为分裂 |
| 命令 `auth` 域设错（如 Console Gateway 用了 `apiKey`） | 凭证域 flag/help/credential 注入都错,运行期才暴露 |
| `packages/cli/src/commands.ts` / `packages/kscli/src/main.ts` 这类 map 两边都加项,解冲突时被合掉一侧 | 某个新命令注册丢失,编译能过、回归不易察觉 |
docs/agents/command-add-remove.md
+13 -13
View File
@@ -5,7 +5,7 @@
- 增加新的 `bl xxx` 命令
- 删除已有命令
- 重命名命令(包括从单级 `bl x` 改成 `bl x y` 或反向)
- 调整某个 shared command 在 `bl` / `rag` 等产品入口里的暴露路径
- 调整某个 shared command 在 `bl` / `kscli` 等产品入口里的暴露路径
## 命令实现与产品路径的关系
@@ -17,7 +17,7 @@
↓ packages/commands/src/index.ts export { default as knowledgeRetrieve }
产品入口:
packages/cli/src/commands.ts "knowledge retrieve": knowledgeRetrieve ↔ bl knowledge retrieve
packages/rag/src/main.ts "retrieve": knowledgeRetrieve ↔ rag retrieve
packages/kscli/src/main.ts "retrieve": knowledgeRetrieve ↔ kscli retrieve
```
常见路径形态:
@@ -32,7 +32,7 @@
## CLI 命令注册架构(必读)
`packages/commands` 是命令库,只导出单个 command;不内置 path presets,不关心 `bl` / `rag`。每个产品入口传入自己的 command map,`runtime` 负责解析、help、鉴权、遥测、执行。
`packages/commands` 是命令库,只导出单个 command;不内置 path presets,不关心 `bl` / `kscli`。每个产品入口传入自己的 command map,`runtime` 负责解析、help、鉴权、遥测、执行。
```
packages/commands/src/commands/<...>.ts
@@ -42,7 +42,7 @@ packages/commands/src/index.ts
export { default as xxxCommand } from "./commands/...ts"
↓
┌──────────────────────────────┬──────────────────────────────┐
│ packages/cli/src/commands.ts │ packages/rag/src/main.ts │
│ packages/cli/src/commands.ts │ packages/kscli/src/main.ts │
│ { "text chat": textChat } │ { "retrieve": knowledge... } │
└──────────────┬───────────────┴──────────────┬───────────────┘
↓ ↓
@@ -51,10 +51,10 @@ packages/commands/src/index.ts
tools/generate-reference.ts reads packages/cli/src/commands.ts
```
- **`packages/commands/src/commands/<...>.ts`**:命令实现;`usageArgs` / `exampleArgs` 只写参数片段,不写 `bl` / `rag` 前缀
- **`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/rag/src/main.ts`**:`rag` 产品命令 map;只有该入口需要暴露/变更时才改
- **`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`,写 `skills/bailian-cli/reference/index.md` + `<一级命令>.md`。该目录**纳入 git**,勿手改
@@ -66,7 +66,7 @@ packages/commands/src/index.ts
- [ ] 新建/删除/移动对应的 `packages/commands/src/commands/<...>.ts`
- [ ] `defineCommand` 字段使用当前 schema:
- `auth: "apiKey" | "console" | "none"`
- `auth: "apiKey" | "console" | "openapi" | "none"`
- `flags`(camelCase key,由 runtime 渲染为 kebab-case)
- `usageArgs`(不含 bin/path 前缀)
- `exampleArgs`(不含 bin/path 前缀)
@@ -81,7 +81,7 @@ packages/commands/src/index.ts
- [ ] `packages/cli/src/commands.ts`:按需增删 `import` 与 `commands` map key
- [ ] 新 map key 就是 `bl` 下的命令路径;重命名时全仓 grep 旧路径字符串
- [ ] 如果 `rag` 入口也要暴露/移除该能力,同步 `packages/rag/src/main.ts`
- [ ] 如果 `kscli` 入口也要暴露/移除该能力,同步 `packages/kscli/src/main.ts`
- [ ] 不要在 `packages/runtime/src/registry.ts` 或 `create-cli.ts` 里写业务命令表
### C. 文档层
@@ -94,13 +94,13 @@ packages/commands/src/index.ts
- [ ] 按 [cli-e2e-tests.md](cli-e2e-tests.md) 新建或更新 `packages/cli/tests/e2e/<topic>.e2e.test.ts`
- [ ] 删除命令时一并删对应 e2e / README 示例 / reference 生成结果
- [ ] 如果 shared command 在不同入口路径下复用,至少确保 `bl` 入口 e2e 覆盖;`rag` 入口改动需补对应入口测试或手工 smoke
- [ ] 如果 shared command 在不同入口路径下复用,至少确保 `bl` 入口 e2e 覆盖;`kscli` 入口改动需补对应入口测试或手工 smoke
### E. 重命名特殊处理
- [ ] 全仓 grep **旧命令名字符串**,确保以下位置全部更新:
- `packages/cli/src/commands.ts` map key
- `packages/rag/src/main.ts` map key(如适用)
- `packages/kscli/src/main.ts` map key(如适用)
- 用户可见 hint / README / tests
- `skills/bailian-cli/reference/`(重建后检查并提交)
- [ ] 检查 `usageArgs` / `exampleArgs` 没有硬编码旧的 `bl <path>` 前缀
@@ -114,10 +114,10 @@ node packages/cli/src/main.ts
vp test packages/cli/tests/e2e/<topic>.e2e.test.ts
```
如改了 `rag` 入口:
如改了 `kscli` 入口:
```sh
node packages/rag/src/main.ts <command> --help
node packages/kscli/src/main.ts <command> --help
```
## 常见漏点
@@ -125,6 +125,6 @@ node packages/rag/src/main.ts <command> --help
- ✗ 只新增 `packages/commands/src/commands/...` 文件,忘了在 `packages/commands/src/index.ts` 导出
- ✗ 只导出了命令实现,忘了在 `packages/cli/src/commands.ts` 暴露路径 → `bl --help` 看不到
- ✗ 手改 `skills/bailian-cli/reference/*.md` → 下次 generate 被覆盖;应改 command metadata 后重新 generate 并提交
- ✗ 在 `usageArgs` / `exampleArgs` 写死 `bl text chat` → `rag` 等入口复用时 help 错
- ✗ 在 `usageArgs` / `exampleArgs` 写死 `bl text chat` → `kscli` 等入口复用时 help 错
- ✗ Console Gateway 命令忘设 `auth: "console"` → console flags / credential 注入都不生效
- ✗ 单 action 的子组是反模式,新增时优先拍平为两级
docs/agents/error-hint-change.md
+3 -3
View File
@@ -67,7 +67,7 @@ process.exit(err.exitCode)
### 3. core 的 hint 必须不含 cli 关切
- ❌ 新增/改动时不写 `bl xxx` 命令名
- ❌ 新增/改动时不写 `rag xxx` 等产品入口命令名
- ❌ 新增/改动时不写 `kscli xxx` 等产品入口命令名
- ❌ 新增/改动时不写控制台 URL 或 region
- ❌ 新增/改动时不写渠道追踪参数(`source_channel=xxx`)
- ✅ 只描述抽象做法(如 `"Set DASHSCOPE_API_KEY environment variable, or pass --api-key."`)
@@ -75,9 +75,9 @@ process.exit(err.exitCode)
### 4. runtime / 产品层可以使用入口名 + URL
- `packages/runtime/src/error-handler.ts` 通过 `binName` 渲染 `bl` / `rag` 等入口名,不要硬编码
- `packages/runtime/src/error-handler.ts` 通过 `binName` 渲染 `bl` / `kscli` 等入口名,不要硬编码
- 产品入口 / README / E2E 可以写具体入口命令
- shared command 实现不写 `bl` / `rag` 前缀;`usageArgs` / `exampleArgs` 只写参数片段
- shared command 实现不写 `bl` / `kscli` 前缀;`usageArgs` / `exampleArgs` 只写参数片段
- URL 必须从 `packages/runtime/src/urls.ts` import,不能硬编码
## 必查清单
docs/agents/lint-toolchain.md
+5 -5
View File
@@ -14,7 +14,7 @@
- [ ] `package.json` 的 `engines.node` 与 README 的 Node.js 徽章一致
- [ ] `pnpm-lock.yaml` 同步生成(运行 `pnpm install`)
- [ ] 各源码包 `tsconfig.json`(根 + core + runtime + commands + cli + rag)的 target / module 设置一致
- [ ] 各源码包 `tsconfig.json`(根 + core + runtime + commands + cli + kscli)的 target / module 设置一致
### B. lint / format 规则改动
@@ -28,9 +28,9 @@
- [ ] `packages/*/vite.config.ts` 的 entry / dts / exports 设置符合包类型:
- library 包(core/runtime/commands):导出 `dist/index.mjs` + dts + `@bailian-cli/source` dev export
- binary 包(cli/rag):entry 指向 `src/main.ts`,有 shebang,`exports: true`
- [ ] cli / rag 的 bundle 必须把 workspace 包(`bailian-cli-core` / `bailian-cli-runtime` / `bailian-cli-commands`)当 **external**(不内联),确认 dist 中仍是 package import
- [ ] cli / rag 的 binary bundle 第一行必须有 `#!/usr/bin/env node` shebang
- binary 包(cli/kscli):entry 指向 `src/main.ts`,有 shebang,`exports: true`
- [ ] cli / kscli 的 bundle 必须把 workspace 包(`bailian-cli-core` / `bailian-cli-runtime` / `bailian-cli-commands`)当 **external**(不内联),确认 dist 中仍是 package import
- [ ] cli / kscli 的 binary bundle 第一行必须有 `#!/usr/bin/env node` shebang
### D. 依赖升级
@@ -63,6 +63,6 @@ node tools/release/check.mjs
- ✗ 升级 Node engines 但忘了 README 徽章
- ✗ 改 lint 规则后没全仓 `--fix`,新人 PR 报红一片
- ✗ 改 cli/rag 的 vite config 把 core/runtime/commands 不小心打成 inline,bundle 体积暴涨
- ✗ 改 cli/kscli 的 vite config 把 core/runtime/commands 不小心打成 inline,bundle 体积暴涨
- ✗ Oxlint 配置改了但 IDE 缓存还是旧的(IDE 可能要重启 ts server)
- ✗ 升级依赖一并升 lockfile,改动量大但没拆 commit
docs/agents/publish.md
+34 -31
View File
@@ -20,14 +20,14 @@
### channel 发布
1. 在 GitHub 触发 Publish workflow，mode 选 `channel`，channel 填 dist-tag 名（如 `mcp`）
2. CI 自动：生成 `0.0.0-beta-<sha7>-<date>` 版本号 → 自检 → 构建 → 发布到指定 dist-tag
1. 在 GitHub 触发 Publish workflow，package 选 `bailian-cli` 或 `knowledge-studio-cli`，mode 选 `channel`，channel 填 dist-tag 名（如 `mcp`）
2. CI 自动：生成 `0.0.0-beta-<sha7>-<date>` 版本号 → 临时 bump 对应包集合 → 自检 → 构建 → 发布到指定 dist-tag
3. 对应脚本：`tools/release/publish-channel.mjs`
### stable 发布
1. 确保当前 release tooling 覆盖的包(`tools/release/lib/packages.mjs`,现为 `packages/core` / `packages/cli`)已升到目标版本且一致;同时人工检查源码包版本(`runtime` / `commands` / `rag`)是否需要跟随
2. 在 GitHub 触发 Publish workflow，mode 选 `stable`
1. 确保当前 release tooling 覆盖的包(`tools/release/lib/packages.mjs`)已升到目标版本且一致;当前基础集合为 `packages/core` / `packages/runtime` / `packages/commands` / `packages/cli`，`knowledge-studio-cli` 发布会额外包含 `packages/kscli`
2. 在 GitHub 触发 Publish workflow，package 选目标包集合，mode 选 `stable`
3. 需要 production environment 审批人批准
4. CI 自动：自检 → 构建 → 发布到 latest → 打 git tag
5. 对应脚本：`tools/release/publish-stable.mjs`
@@ -36,21 +36,23 @@
两种模式都会先跑 `check.mjs`，覆盖以下检查：
| 检查项 | 说明 |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `pnpm install --frozen-lockfile` | lockfile 一致性 |
| README 同步 | `packages/cli/README.md` 与根 README 一致 |
| 版本号一致 | `tools/release/lib/packages.mjs` 中列出的包 version 相同（当前为 core + cli） |
| `workspace:*` 替换 | 发布包间 workspace 依赖解析为真实版本号 |
| 构建 | 当前 check 会构建 core + cli |
| pnpm pack | 打 tarball |
| publint | 包元数据校验 |
| gitleaks | 敏感信息扫描 |
| 检查项 | 说明 |
| -------------------------------- | ------------------------------------------------------------------------------------------------ |
| `pnpm install --frozen-lockfile` | lockfile 一致性 |
| README 同步 | `packages/cli/README.md` 与根 README 一致 |
| 版本号一致 | `tools/release/lib/packages.mjs` 中待发布包集合 version 相同 |
| `workspace:*` 替换 | 发布包间 workspace 依赖解析为真实版本号 |
| 构建 | 基础发布构建 core/runtime/commands 依赖和 cli;`--knowledge` 额外构建 `knowledge-studio-cli` |
| 生成资产 | 重建 `skills/bailian-cli/reference/`;非 channel 模式还同步 `skills/bailian-cli/SKILL.md` version |
| pnpm pack | 打 tarball |
| publint | 包元数据校验 |
| gitleaks | 敏感信息扫描 |
本地可以 dry-run 验证：
```sh
node tools/release/publish-channel.mjs --channel test --dry-run
node tools/release/publish-channel.mjs --channel test --knowledge --dry-run
```
## CI 基础设施
@@ -58,15 +60,15 @@ node tools/release/publish-channel.mjs --channel test --dry-run
- **认证**：npm OIDC Trusted Publishing（无 token），需要 `id-token: write` 权限
- **Node 版本**：24（npm 11.5+ 才支持 OIDC token 交换）
- **Actions 版本**：checkout/setup-node/pnpm-action 均为 v6（Node 24 兼容）
- **npm 配置**：当前 release tooling 发布的包(core + cli)的 Trusted Publisher 指向 `modelstudioai/cli` 的 `publish.yml`，environment 留空;新增发布包时同步 npm Trusted Publisher
- **npm 配置**：当前 release tooling 发布的包(`bailian-cli-core` / `bailian-cli-runtime` / `bailian-cli-commands` / `bailian-cli` / `knowledge-studio-cli`)的 Trusted Publisher 指向 `modelstudioai/cli` 的 `publish.yml`;新增发布包时同步 npm Trusted Publisher
## `check.mjs` 不覆盖的（手动确认）
### 版本号目标（仅 stable）
- [ ] `tools/release/lib/packages.mjs` 覆盖的包已升到目标版本且一致
- [ ] 源码包 `packages/runtime/package.json`、`packages/commands/package.json`、`packages/rag/package.json` 是否需要同步升版已人工确认;当前仓库通常保持五包版本一致
- [ ] `tools/release/lib/packages.mjs` 的 `PACKAGES` 覆盖所有本次实际要发布的包;如果新增发布包,同步 `publish-stable.mjs` / `publish-channel.mjs` 的 bump、publish、idempotency 逻辑
- [ ] `tools/release/lib/packages.mjs` 覆盖的目标包集合已升到目标版本且一致
- [ ] 源码包 `packages/core/package.json`、`packages/runtime/package.json`、`packages/commands/package.json`、`packages/cli/package.json`、`packages/kscli/package.json` 是否需要同步升版已人工确认;当前仓库通常保持五包版本一致
- [ ] `tools/release/lib/packages.mjs` 的 `PACKAGES` 覆盖基础发布包;`KSCLI_PACKAGE` / `ALL_PACKAGES` 覆盖 `knowledge-studio-cli` 发布路径;如果新增发布包,同步 `publish-stable.mjs` / `publish-channel.mjs` 的 bump、publish、idempotency 逻辑和 `.github/workflows/publish.yml` 的 package 选项
- [ ] pre-release 格式正确（`1.0.0-beta.0` / `1.0.0-rc.1`，**不要直接用 `1.0.0` 当 beta**）
### CHANGELOG（仅 stable）
@@ -80,23 +82,24 @@ node tools/release/publish-channel.mjs --channel test --dry-run
- [ ] `README.md` / `README.zh.md` 的 Quick Start 命令仍能跑通
- [ ] README 的 Node.js 徽章版本与 `cli/package.json.engines.node` 一致
- [ ] README 宣传的 bin 名称在 `cli/package.json.bin` 都真的注册
- [ ] `packages/kscli/README.md` / `README.zh.md` 与 `knowledge-studio-cli` 的 bin、控制台 URL、认证方式一致
- [ ] `LICENSE` 文件存在（根 + 当前实际发布包;新增发布包时补该包 LICENSE）
## 完成后
- [ ] 验证 npm 上能装：`npm view bailian-cli@<tag> version`
- [ ] 试装一次：`npm i -g bailian-cli@<tag> && bl --version`
- [ ] 验证 npm 上能装：`npm view bailian-cli@<tag> version`;如发布 `knowledge-studio-cli`，同时 `npm view knowledge-studio-cli@<tag> version`
- [ ] 试装一次：`npm i -g bailian-cli@<tag> && bl --version`;如发布 `knowledge-studio-cli`，同时 `npm i -g knowledge-studio-cli@<tag> && kscli --version`
## 常见漏点（基于历史踩坑）
| 漏点 | 后果 |
| -------------------------------------------------------- | --------------------------------------------------------- |
| 只升 cli/core,漏升 runtime/commands/rag | 当前 check.mjs 不一定拦下,但 workspace 发布会出现版本漂移 |
| 新增发布包但没加 `tools/release/lib/packages.mjs` | CI 不会 bump/publish/校验该包 |
| cli 升版号但 core 没升 | check.mjs 会拦下 |
| 发版漏更 CHANGELOG，或分类写成规范外的 `优化`/`Improved` | 用户看不到本次变更，分类与历史不一致 |
| `1.0.0` 当 beta 直接发 | 占了 `latest` tag，所有用户被强升，撤回成本极高 |
| README 写的 bin 名实际 `package.json.bin` 没注册 | 用户复制命令报 `command not found` |
| Node 徽章 `>=18`、engines `>=22.12` 不一致 | 用户在 Node 18 上 `npm i` 被 engine 警告或直接失败 |
| npm Trusted Publisher 的 workflow filename 改了没同步 | OIDC 匹配不上，publish 报 404 |
| CI 用 Node 22（npm 10）跑 publish | npm 10 不支持 OIDC token 交换，publish 报 404 |
| 漏点 | 后果 |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 只升部分包,漏升 runtime/commands/kscli | 当前 check.mjs 按所选发布集合校验,但未选择 `knowledge-studio-cli` 时不会覆盖 kscli |
| 新增发布包但没加 `tools/release/lib/packages.mjs` | CI 不会 bump/publish/校验该包 |
| cli 升版号但 core 没升 | check.mjs 会拦下 |
| 发版漏更 CHANGELOG，或分类写成规范外的 `优化`/`Improved` | 用户看不到本次变更，分类与历史不一致 |
| `1.0.0` 当 beta 直接发 | 占了 `latest` tag，所有用户被强升，撤回成本极高 |
| README 写的 bin 名实际 `package.json.bin` 没注册 | 用户复制命令报 `command not found` |
| Node 徽章 `>=18`、engines `>=22.12` 不一致 | 用户在 Node 18 上 `npm i` 被 engine 警告或直接失败 |
| npm Trusted Publisher 的 workflow filename 改了没同步 | OIDC 匹配不上，publish 报 404 |
| CI 用 Node 22（npm 10）跑 publish | npm 10 不支持 OIDC token 交换，publish 报 404 |
skills/bailian-cli/SKILL.md
+6 -7
View File
@@ -29,7 +29,7 @@ description: >-
Auto-generated from the CLI source at build time. Before running an unfamiliar command:
1. Open `reference/index.md` → **Quick index** (or **By group**) to locate the command.
2. Open the matching `reference/<group>.md` for **Usage**, **Options**, and **Examples**.
2. Open the matching `reference/<group>.md` for **Usage**, **Flags**, and **Examples**.
3. Run `bl <command> --help` for the same information in the terminal.
Do not guess flags — use the reference files or `--help`.
@@ -64,7 +64,7 @@ NO_COLOR=1 bl config show --output text
| Bailian agent / workflow | `bl app call` | Needs `--app-id` |
| Find app by name | `bl app list` then `bl app call` | Console auth |
| Memory CRUD / profile | `bl memory *` | [`reference/memory.md`](reference/memory.md) |
| Knowledge RAG | `bl knowledge retrieve` | API key + index ID |
| Knowledge RAG | `bl knowledge search` / `chat` | API key + agent/workspace IDs |
| Upload file to temp OSS | `bl file upload` | When you need `oss://` URL explicitly |
| Model selection / recommendation | `bl advisor recommend` | Intent → candidate recall → LLM ranking |
| MCP tool discovery / call | `bl mcp list` / `tools` / `call` | Bailian MCP marketplace |
@@ -180,12 +180,11 @@ bl text chat --message "Write a poem about spring" # quick smoke test
2. Pick `code` (app ID); handle `user_prompt_params` via `--biz-params '{"key":"value"}'`
3. `bl app call --app-id <code> --prompt "..."`
### Tool schemas for agents
### Command metadata for agents
```bash
bl config export-schema
bl config export-schema --command "image generate"
```
Use [`reference/index.md`](reference/index.md), the matching `reference/<group>.md`,
and `bl <command> --help` as the command schema surface. Do not call removed
schema-export commands.
---
skills/bailian-cli/assets/setup.md
+10 -13
View File
@@ -1,6 +1,6 @@
# Setup, authentication & configuration
> Hand-maintained. Lives in `assets/` (not auto-generated from `catalog.ts`).
> Hand-maintained. Lives in `assets/` (not auto-generated from command metadata).
> Entry point: [SKILL.md → Setup & auth](../SKILL.md#setup--auth).
Read this only when you need to install `bl`, change credentials/endpoint, or
@@ -21,15 +21,17 @@ Verify: `bl --version` (prints `bl X.Y.Z`).
## Authentication
| Auth | How | Used by |
| ------------- | ------------------------------------------------------------------------ | ---------------------------------------- |
| API key | `export DASHSCOPE_API_KEY=sk-...` or `bl auth login --api-key sk-...` | Most DashScope API commands |
| Console token | `bl auth login --console --console-site domestic` or `... international` | `app list`, `usage free`, `console call` |
| Auth | How | Used by |
| ---------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| API key | `export DASHSCOPE_API_KEY=sk-...` or `bl auth login --api-key sk-...` | Most DashScope API commands |
| Console | `bl auth login --console --console-site domestic` or `... international` | `app list`, `usage free`, `console call` |
| OpenAPI AK | `bl auth login --open-api --access-key-id <id> --access-key-secret <secret>` or Alibaba env vars | `token-plan *` |
```bash
bl auth status # check current auth
bl auth logout # clear credentials
bl auth logout --console # clear console token only
bl auth logout --open-api # clear OpenAPI AK/SK only
```
Get an API key: https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key
@@ -88,7 +90,7 @@ Default: `https://dashscope.aliyuncs.com` (China). Override with any of:
## Configuration
- **Config file:** `~/.bailian/config.json`
- **Env:** `DASHSCOPE_API_KEY`, `DASHSCOPE_BASE_URL`, `DASHSCOPE_OUTPUT`
- **Env:** `DASHSCOPE_API_KEY`, `DASHSCOPE_BASE_URL`, `DASHSCOPE_OUTPUT`, `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`, `BAILIAN_WORKSPACE_ID`
```bash
bl config show
@@ -96,10 +98,5 @@ bl config set --key default-text-model --value qwen3.7-max
bl config set --key output_dir --value ~/bailian-output
```
Valid config keys and the export-schema for agent tool definitions:
see [`reference/config.md`](../reference/config.md).
```bash
bl config export-schema # all commands as JSON tool schemas
bl config export-schema --command "image generate"
```
Valid config keys are listed in [`reference/config.md`](../reference/config.md)
and `bl config set --help`.
skills/bailian-cli/reference/index.md
+1 -1
View File
@@ -162,4 +162,4 @@ Available on OpenAPI-domain commands (AK/SK auth); also listed per command below
- Console commands (`app list`, `usage free`, `console call`) require `bl auth login --console`.
- Most API commands use `DASHSCOPE_API_KEY` or `bl auth login --api-key`.
- Token Plan commands use OpenAPI AK/SK via `bl auth login --open-api` or `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.
- Default output: **text** in TTY; **json** when piped.
- Default output: **text** unless explicitly set to `json` with `--output`, `DASHSCOPE_OUTPUT`, or config.
tools/generate-reference.ts
+1 -1
View File
@@ -215,7 +215,7 @@ function buildIndex(
"- Console commands (`app list`, `usage free`, `console call`) require `bl auth login --console`.",
"- Most API commands use `DASHSCOPE_API_KEY` or `bl auth login --api-key`.",
"- Token Plan commands use OpenAPI AK/SK via `bl auth login --open-api` or `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.",
"- Default output: **text** in TTY; **json** when piped.",
"- Default output: **text** unless explicitly set to `json` with `--output`, `DASHSCOPE_OUTPUT`, or config.",
"",
);