From 6388fd11e2780a48b2f20edeea168f7030828e0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=8B=A5=E9=BA=92?= Date: Mon, 13 Jul 2026 16:05:08 +0800 Subject: [PATCH] docs: sync command context capability usage --- docs/agents/auth-change.md | 4 ++-- docs/agents/command-add-remove.md | 4 ++-- docs/agents/command-pack.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/agents/auth-change.md b/docs/agents/auth-change.md index d5ec52f..fde6101 100644 --- a/docs/agents/auth-change.md +++ b/docs/agents/auth-change.md @@ -48,7 +48,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx - `resolveOpenApi()` — `auth: "openapi"` 命令;优先级 `--access-key-id/--access-key-secret` > `ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET` > config `access_key_*`。兼容读取旧字段 `openapi_access_key_*`,新写入只写短字段 - `describeAuthState()` — `auth status` / banner / telemetry 使用的只读快照 -命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore()` / `ctx.configStore()` 的窄接口操作落盘。 +命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore` / `ctx.configStore` 的窄接口操作落盘。 ## 必查清单 @@ -87,7 +87,7 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx - [ ] `packages/commands/src/commands/auth/login.ts`: - 新增/调整登录 flag 与流程 - - 持久化只走 `ctx.authStore().login(...)` + - 持久化只走 `ctx.authStore.login(...)` - [ ] `packages/commands/src/commands/auth/status.ts`: - 分别显示 model / console / openapi 鉴权状态,并 mask token - [ ] `packages/commands/src/commands/auth/logout.ts`: diff --git a/docs/agents/command-add-remove.md b/docs/agents/command-add-remove.md index 69aea09..471b140 100644 --- a/docs/agents/command-add-remove.md +++ b/docs/agents/command-add-remove.md @@ -72,8 +72,8 @@ packages/commands/src/index.ts - `exampleArgs`(不含 bin/path 前缀) - `validate`(跨 flag 校验) - 普通业务命令的 `run(ctx)` 只读 `ctx.flags` / `ctx.settings` / `ctx.client` - - `commands/auth/**` 可用 `ctx.authStore()`,`commands/config/**` 可用 `ctx.configStore()`;不要把这些 store accessor 扩散到普通业务命令 - - `commands/plugin/**` 可用 `ctx.commandPacks()`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口 + - `commands/auth/**` 可用 `ctx.authStore`,`commands/config/**` 可用 `ctx.configStore`;不要把这些持久化能力扩散到普通业务命令 + - `commands/plugin/**` 可用 `ctx.commandPacks`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口 - [ ] `packages/commands/src/index.ts`:新增或移除对应 export - [ ] 如果命令调用 Console Gateway,设置 `auth: "console"`;不要重复声明 console 凭证域 flags - [ ] 如果命令不需要网络或自己管理配置/登录,设置 `auth: "none"`;不要绕过 runtime auth stage diff --git a/docs/agents/command-pack.md b/docs/agents/command-pack.md index 373f7a7..1bec108 100644 --- a/docs/agents/command-pack.md +++ b/docs/agents/command-pack.md @@ -11,8 +11,8 @@ - `packages/core/src/types/command-pack.ts`：稳定的协议元数据和导出类型，不知道具体产品或白名单。 - `packages/runtime/src/command-packs/`：所有 CLI 共用的加载、校验、API 适配、产品隔离安装目录和 manager 实现。 -- `packages/runtime/src/create-cli.ts`：始终接收静态 command map，按 `CliOptions.commandPacks` 统一合并 pack，并把已绑定产品 identity/policy 的 manager 注入 `ctx.commandPacks()`。 -- `packages/commands/src/commands/plugin/`：普通共享管理命令，只依赖 `ctx.commandPacks()`，不 import 任何产品 policy。 +- `packages/runtime/src/create-cli.ts`：始终接收静态 command map，按 `CliOptions.commandPacks` 统一合并 pack，并把已绑定产品 identity/policy 的 manager 注入 `ctx.commandPacks`。 +- `packages/commands/src/commands/plugin/`：普通共享管理命令，只依赖 `ctx.commandPacks`，不 import 任何产品 policy。 - `packages/cli/src/command-pack-policy.ts`：`bl` 支持的包、命令前缀和凭据授权。 - `kscli` 当前不传 `commandPacks`，使用 runtime 的默认空 policy。 - 当前只有 `bl` 从 `bailian-cli-commands` 导入并登记 `plugin *`；使用默认空 policy 的产品不提前暴露管理命令。 @@ -33,7 +33,7 @@ - [ ] 普通网络请求走 `ctx.client`；基础 Context 提供 `identity/settings/flags/client/output/errors`，不提供原始凭据。 - [ ] `ctx.credentials.apiKey()` 仅限 policy 显式声明 `credentialAccess: ["apiKey"]`，且命令自身为 `auth: "apiKey"`。 - [ ] 不向 Command Pack 暴露原始 Console Token、OpenAPI AK/SK、`authStore` 或 `configStore`。 -- [ ] 不向 Command Pack 暴露宿主的 `commandPacks()` manager，避免 pack 安装或删除其他 pack。 +- [ ] 不向 Command Pack 暴露宿主的 `commandPacks` manager，避免 pack 安装或删除其他 pack。 - [ ] 单包失败必须 fail-open：保留内置命令和其他合法 pack。 - [ ] 破坏协议前优先在适配层兼容；确实无法兼容时才提升 `apiVersion`。