feat(agent): 鉴权分离线命令和在线命令，仅对bailian provider鉴权

Author: chenanran555

docs/agents/auth-change.md

@@ -53,18 +53,22 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore` / `ctx.configStore` 的窄接口操作落盘。
 
-### 例外:agent 命令的 SDK 凭证内存注入
+### 例外:agent 命令的分层鉴权与 SDK 凭证内存注入
 
-`bl managed-agent *` 的全部命令声明 `auth: "apiKey"`(含纯本地脚手架 `init` —— 统一登录门槛,无例外),bailian 凭证由 authStage 经 `resolveApiKey(sources)` 权威解析(flag > env > active profile config,缺失时抛统一 AUTH 错误)。
+`bl managed-agent *` 按调用链分两层，不再全命令硬门禁:
 
-凭证不再以真实值写入 `process.env`,而是经 `packages/commands/src/commands/managed-agent/_engine/` 的**内存注入管道**(`resolveAgentProjectConfig`)注入 SDK,管道四步:
+- **离线命令** — `init`、`validate`、`state list/show/rm`:`auth: "none"`，只读写本地文件，无需登录;引擎侧传 `credentials: "none"` 跳过凭证断言（`plan --no-refresh` 同样传 `"none"`）
+- **provider-aware 命令** — `plan`(默认)、`apply`、`destroy`、`state import`、`skill-list`、全部 `session *`:仍声明 `auth: "apiKey"` 但加 `authOptional: true` —— authStage 照常经 `resolveApiKey(sources)` 解析 bailian 凭证(flag > env > active profile config)并注入 `ctx.client`，但缺失不在 authStage 抛;真正的门禁在引擎层 `assertProviderCredentials`，只校验本次运行涉及的 provider（`CredentialScope`:`--provider` / state 地址里的 provider / 配置默认 provider 链）。配了四个 provider 只跑 claude 时，缺 bailian key 不阻塞。
 
-1. `prepareProviderEnv()` — 先 `bootstrapRuntimeCredentialsSync()`(SDK 把 `.env` / `~/.agents/config.json` 灌进 env,服务 claude/ark/qoder 等非 bailian provider),再把全部凭证类 env(`CREDENTIAL_ENV_KEYS`,含别名)中仍为 undefined 的占位为 `""`,使 agents.yaml 插值不因缺变量抛错
-2. `resolveProjectConfig` — 插值发生:bailian 插值拿到占位空串,claude/ark 拿到真实 env 值
-3. `injectProviderCredentials()` — 用 `ctx.client.exportApiCredential()`(lint 限定 `managed-agent/_engine/**` 可用)覆写内存 config 对象的 bailian 块:`api_key` 无条件覆写;`base_url`(拼 `/api/v1/agentstudio` 后缀)/`workspace_id`(取 `settings.workspaceId`)仅在引用且为空时填充
-4. `scrubCredentialEnv()` + `assertProviderCredentials()` — 从 `process.env` 删除全部凭证变量(真实凭证此后只存于 config 对象 → provider adapter 实例内存,不驻留 env / 不被子进程继承);任一已声明 provider 的 `api_key` 为空 → CLI 权威 `AUTH` 错误 + provider 专属 hint(取代 SDK 原始插值/zod 报错)
+凭证不以真实值写入 `process.env`，而是经 `packages/commands/src/commands/managed-agent/_engine/` 的**内存注入管道**(`resolveAgentProjectConfig`)注入 SDK，管道五步:
 
-`bl auth login` 仅管理 bailian(DashScope)凭证;claude/ark/qoder 的 key 从 env(shell / `.env` / `~/.agents/config.json`)经插值进入 config 对象,同样被清扫。禁止命令层直接 `readConfigFile` 裸读凭证;bailian 字段以 CLI 鉴权链为唯一信源。
+1. `prepareProviderEnv()` — 先 `bootstrapRuntimeCredentialsSync()`(SDK 把 `.env` / `~/.agents/config.json` 灌进 env，服务 claude/ark/qoder 等非 bailian provider)，再把全部凭证类 env(`CREDENTIAL_ENV_KEYS`，含别名)中仍为 undefined 的占位为 `""`，使 agents.yaml 插值不因缺变量抛错
+2. `resolveProjectConfig` — 插值发生:bailian 插值拿到占位空串，claude/ark 拿到真实 env 值;随后 `normalizeInterpolatedProviderBlocks()` 把插值为空导致的 YAML `null` 归一为 `""`(避免范围外 provider 在 SDK zod 层报 "received null")
+3. `injectProviderCredentials()` — 用 `ctx.client.exportApiCredential()`(lint 限定 `managed-agent/_engine/**` 可用)覆写内存 config 对象的 bailian 块:有凭证时 `api_key` 无条件覆写;`base_url`(拼 `/api/v1/agentstudio` 后缀，无凭证时用 client 默认域名补齐以满足 schema)/`workspace_id`(取 `settings.workspaceId`)仅在引用且为空时填充
+4. `scrubCredentialEnv()` — 从 `process.env` 删除全部凭证变量(真实凭证此后只存于 config 对象 → provider adapter 实例内存，不驻留 env / 不被子进程继承)
+5. `assertProviderCredentials(providers, required)` — 按 `CredentialScope` 算出的 `required` 范围校验:范围内 provider 的 `api_key` 为空 → CLI 权威 `AUTH` 错误 + provider 专属 hint(取代 SDK 原始插值/zod 报错);范围外 provider 允许空 key
+
+`bl auth login` 仅管理 bailian(DashScope)凭证;claude/ark/qoder 的 key 从 env(shell / `.env` / `~/.agents/config.json`)经插值进入 config 对象，同样被清扫。禁止命令层直接 `readConfigFile` 裸读凭证;bailian 字段以 CLI 鉴权链为唯一信源。
 
 ## 必查清单
 

packages/commands/src/commands/managed-agent/_engine/config-loader.ts

@@ -9,18 +9,32 @@ import {
   assertProviderCredentials,
   type CredentialHost,
   injectProviderCredentials,
+  normalizeInterpolatedProviderBlocks,
   prepareProviderEnv,
+  resolveTargetProviderNames,
   scrubCredentialEnv,
 } from "./credentials.ts";
 import { loadFileState } from "./file-state-manager.ts";
 import { type HostContext, installSdkTransport } from "./transport.ts";
 
-export { CREDENTIALS_NOTE } from "./credentials.ts";
+export { CREDENTIALS_NOTE, OFFLINE_NOTE } from "./credentials.ts";
+
+/**
+ * Which providers this run requires a non-empty key for:
+ *   - "targets" (default) — the run's target providers per the config's
+ *     default provider chain (mirrors the SDK's plan/apply targeting)
+ *   - "none" — offline command (local config/state only), skip the check
+ *   - "all" — every configured provider (`--provider all`)
+ *   - any other name — the run was narrowed to that provider
+ *     (`--provider <name>` / a provider-qualified state address)
+ */
+export type CredentialScope = "targets" | "none" | "all" | (string & {});
 
 interface AgentConfigOptions {
   resolveEnv?: boolean;
   projectName?: string;
   statePath?: string;
+  credentials?: CredentialScope;
 }
 
 /**
@@ -32,7 +46,8 @@ interface AgentConfigOptions {
  *   3. override the bailian block with the CLI auth chain's credential (in-memory)
  *   4. scrub all credential vars from process.env (real values now live only in
  *      the config object → provider adapters, never the environment)
- *   5. fail with a CLI-authoritative AUTH error if any provider's key is empty
+ *   5. fail with a CLI-authoritative AUTH error if a provider within this run's
+ *      {@link CredentialScope} has an empty key (offline commands pass "none")
  */
 export async function resolveAgentProjectConfig(
   host: CredentialHost,
@@ -41,9 +56,20 @@ export async function resolveAgentProjectConfig(
 ): Promise<LoadedProjectConfig> {
   prepareProviderEnv();
   const resolved = await resolveProjectConfig(filePath, options);
+  normalizeInterpolatedProviderBlocks(resolved.config.providers);
   injectProviderCredentials(resolved.config.providers, host);
   scrubCredentialEnv();
-  assertProviderCredentials(resolved.config.providers);
+  const scope = options.credentials ?? "targets";
+  if (scope !== "none") {
+    assertProviderCredentials(
+      resolved.config.providers,
+      scope === "targets"
+        ? resolveTargetProviderNames(resolved.config)
+        : scope === "all"
+          ? Object.keys(resolved.config.providers)
+          : [scope],
+    );
+  }
   return resolved;
 }
 

packages/commands/src/commands/managed-agent/_engine/credentials.ts

@@ -51,9 +51,18 @@ export interface CredentialHost {
 export const CREDENTIALS_NOTE = [
   "Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).",
   "Other providers read the env vars referenced in agents.yaml (e.g. ${ANTHROPIC_API_KEY}), including .env and ~/.agents/config.json.",
+  "Only the providers this run involves (--provider, or the config's default provider chain) need credentials; other configured providers are not checked.",
   "Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.",
 ];
 
+/**
+ * Shared `--help` note for commands that never talk to a provider: they load
+ * agents.yaml / local state only, so no login or provider key is required.
+ */
+export const OFFLINE_NOTE = [
+  "Runs fully offline against local files: no login or provider credentials required.",
+];
+
 /**
  * Load the SDK's env-based credential sources (`.env`, `~/.agents/config.json`)
  * for non-bailian providers, then placeholder every credential var that is still
@@ -72,15 +81,18 @@ export function prepareProviderEnv(): void {
 /**
  * Override the bailian provider block with bl's authStage-resolved credential, so
  * the bailian API key is authoritatively the CLI auth chain's — never a config
- * file bare-read or a stale env value. `api_key` is replaced unconditionally;
- * `base_url` / `workspace_id` are filled only when the block references them and
- * the interpolated value is empty (a literal in agents.yaml is respected).
+ * file bare-read or a stale env value. `api_key` is replaced unconditionally
+ * when a credential resolved; `base_url` / `workspace_id` are filled only when
+ * the block references them and the interpolated value is empty (a literal in
+ * agents.yaml is respected).
  *
  * `base_url` carries {@link AGENTSTUDIO_API_PATH} because the SDK appends resource
  * paths onto it verbatim; a value already ending in the suffix is left as-is.
- * With no credential (only under --dry-run: authStage hard-gates otherwise) the
- * bailian block is left untouched. Non-bailian blocks keep their interpolated
- * (env-sourced) values.
+ * It is filled even without a credential — `client.baseUrl` is readable
+ * credential-less (defaults to the CLI's model-domain base URL) — so offline /
+ * out-of-scope runs still satisfy the SDK's "workspace_id or base_url" schema.
+ * With no credential the `api_key` is left untouched: an in-scope empty key is
+ * rejected by {@link assertProviderCredentials}, out-of-scope ones may stay empty.
  */
 export function injectProviderCredentials(
   providers: Record<string, unknown>,
@@ -91,16 +103,14 @@ export function injectProviderCredentials(
   const block = bailian as Record<string, unknown>;
 
   const cred = host.client.exportApiCredential();
-  if (cred) {
-    block.api_key = cred.token;
-    if ("base_url" in block && !block.base_url) {
-      // Defensive normalization: the auth chain already normalizes base_url to
-      // an origin, but never let a trailing slash produce "//api/v1/agentstudio".
-      const origin = cred.baseUrl.replace(/\/+$/, "");
-      block.base_url = origin.endsWith(AGENTSTUDIO_API_PATH)
-        ? origin
-        : `${origin}${AGENTSTUDIO_API_PATH}`;
-    }
+  if (cred) block.api_key = cred.token;
+  if ("base_url" in block && !block.base_url) {
+    // Defensive normalization: the auth chain already normalizes base_url to
+    // an origin, but never let a trailing slash produce "//api/v1/agentstudio".
+    const origin = host.client.baseUrl.replace(/\/+$/, "");
+    block.base_url = origin.endsWith(AGENTSTUDIO_API_PATH)
+      ? origin
+      : `${origin}${AGENTSTUDIO_API_PATH}`;
   }
   if ("workspace_id" in block && !block.workspace_id && host.settings.workspaceId) {
     block.workspace_id = host.settings.workspaceId;
@@ -121,15 +131,55 @@ export function scrubCredentialEnv(): void {
 }
 
 /**
- * After injection, fail with a CLI-authoritative AUTH error if any configured
+ * The SDK interpolates `${VAR}` into the raw YAML text, so an empty env var
+ * leaves `api_key:` with nothing after it — YAML parses that as null. Normalize
+ * every null provider field back to "" so the pipeline stays uniform: an empty
+ * api_key is caught by {@link assertProviderCredentials} when the provider is
+ * in scope, and out-of-scope blocks still satisfy the SDK's string schemas
+ * instead of failing zod with "received null" before the run even starts.
+ */
+export function normalizeInterpolatedProviderBlocks(providers: Record<string, unknown>): void {
+  for (const raw of Object.values(providers)) {
+    if (!raw || typeof raw !== "object") continue;
+    const block = raw as Record<string, unknown>;
+    for (const [fieldName, value] of Object.entries(block)) {
+      if (value === null) block[fieldName] = "";
+    }
+  }
+}
+
+/**
+ * The providers a run targets when no explicit `--provider` narrows it: the
+ * config's default provider, or every configured provider when the default is
+ * absent or "all". Mirrors the SDK's config-based `resolveTargetProviders`
+ * (not exported from the SDK's public surface).
+ */
+export function resolveTargetProviderNames(config: {
+  providers: Record<string, unknown>;
+  defaults?: { provider?: string };
+}): string[] {
+  const defaultProvider = config.defaults?.provider;
+  if (!defaultProvider || defaultProvider === "all") return Object.keys(config.providers);
+  return [defaultProvider];
+}
+
+/**
+ * After injection, fail with a CLI-authoritative AUTH error if a required
  * provider's `api_key` resolved empty (missing env var, or no bl login for
  * bailian). Replaces the SDK's raw `Environment variable '...' is not set` /
- * zod config error with a clean message plus a provider-specific hint. Validates
- * every declared provider, so a project is only runnable once all its providers'
- * keys are available.
+ * zod config error with a clean message plus a provider-specific hint.
+ * `required` limits the check to the providers this run actually involves
+ * (← --provider / state address / config default chain); providers outside
+ * that scope may keep empty keys — a project stays runnable per provider.
+ * Names without a matching config block are skipped: "provider not
+ * configured" is the engine's error to raise, not a credential problem.
  */
-export function assertProviderCredentials(providers: Record<string, unknown>): void {
-  for (const [name, raw] of Object.entries(providers)) {
+export function assertProviderCredentials(
+  providers: Record<string, unknown>,
+  required?: readonly string[],
+): void {
+  for (const name of required ?? Object.keys(providers)) {
+    const raw = providers[name];
     if (!raw || typeof raw !== "object") continue;
     const block = raw as Record<string, unknown>;
     if (!("api_key" in block)) continue;

packages/commands/src/commands/managed-agent/apply.ts

@@ -46,6 +46,8 @@ const APPLY_FLAGS = {
 export default defineCommand({
   description: "Apply planned changes to create/update/delete agent resources",
   auth: "apiKey",
+  // Provider-aware gate: only the providers this apply targets need credentials.
+  authOptional: true,
   usageArgs: "[--file <path>] [--provider <name>] [--yes] [--concurrency <n>]",
   flags: APPLY_FLAGS,
   exampleArgs: ["--yes", "--provider bailian --yes"],
@@ -73,7 +75,9 @@ export default defineCommand({
 
     const planned = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(ctx, file);
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: flags.provider ?? "targets",
+        });
         assertProviderConfigured(runtime, flags.provider);
         return planProjectContext(runtime, {
           provider: flags.provider,

packages/commands/src/commands/managed-agent/destroy.ts

@@ -31,6 +31,8 @@ const DESTROY_FLAGS = {
 export default defineCommand({
   description: "Destroy all managed agent resources tracked in state",
   auth: "apiKey",
+  // Provider-aware gate: only the run's target providers need credentials.
+  authOptional: true,
   usageArgs: "[--file <path>] [--yes] [--cascade]",
   flags: DESTROY_FLAGS,
   exampleArgs: ["--yes", "--yes --cascade"],
@@ -54,7 +56,9 @@ export default defineCommand({
 
     const planned = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(ctx, file);
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: "targets",
+        });
         return planDestroyProjectContext(runtime);
       }),
     );

packages/commands/src/commands/managed-agent/init.ts

@@ -99,7 +99,7 @@ const INIT_FLAGS = {
 
 export default defineCommand({
   description: "Create a new agents.yaml template",
-  auth: "apiKey",
+  auth: "none",
   usageArgs: "[--provider <name>] [--agent-name <name>] [--file <path>] [--force]",
   flags: INIT_FLAGS,
   exampleArgs: ["", "--provider bailian --agent-name assistant", "--provider all"],

packages/commands/src/commands/managed-agent/plan.ts

@@ -41,6 +41,9 @@ const PLAN_FLAGS = {
 export default defineCommand({
   description: "Show what changes would be applied to agent infrastructure",
   auth: "apiKey",
+  // Provider-aware gate: --no-refresh plans fully offline; a refreshing run
+  // only needs credentials for the providers it targets (see CredentialScope).
+  authOptional: true,
   usageArgs: "[--file <path>] [--provider <name>] [--no-refresh] [--refresh-only]",
   flags: PLAN_FLAGS,
   exampleArgs: ["", "--provider bailian", "--no-refresh"],
@@ -52,7 +55,10 @@ export default defineCommand({
 
     const planned = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(ctx, file);
+        // --no-refresh never talks to a provider → no credentials required.
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: flags.noRefresh ? "none" : (flags.provider ?? "targets"),
+        });
         assertProviderConfigured(runtime, flags.provider);
         return planProjectContext(runtime, {
           provider: flags.provider,

packages/commands/src/commands/managed-agent/session-create.ts

@@ -43,6 +43,8 @@ const SESSION_CREATE_FLAGS = {
 export default defineCommand({
   description: "Create a new session for an agent",
   auth: "apiKey",
+  // Provider-aware gate: only the session's provider needs credentials.
+  authOptional: true,
   usageArgs: "[--agent <name>] [--environment <name>] [--title <title>] [--file <path>]",
   flags: SESSION_CREATE_FLAGS,
   exampleArgs: ["", "--agent assistant", "--agent assistant --title 'debug run'"],
@@ -72,7 +74,9 @@ export default defineCommand({
 
     const run = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(ctx, file);
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: flags.provider ?? "targets",
+        });
         return createSessionForAgent(runtime, {
           agent: flags.agent,
           provider: flags.provider,

packages/commands/src/commands/managed-agent/session-delete.ts

@@ -27,6 +27,8 @@ const SESSION_DELETE_FLAGS = {
 export default defineCommand({
   description: "Delete a session",
   auth: "apiKey",
+  // Provider-aware gate: only the session's provider needs credentials.
+  authOptional: true,
   usageArgs: "--session-id <id> [--provider <name>] [--file <path>]",
   flags: SESSION_DELETE_FLAGS,
   exampleArgs: ["--session-id sess_abc123"],
@@ -50,7 +52,9 @@ export default defineCommand({
 
     await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(ctx, file);
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: flags.provider ?? "targets",
+        });
         await deleteSession(runtime, flags.sessionId, flags.provider);
       }),
     );

packages/commands/src/commands/managed-agent/session-events.ts

@@ -38,6 +38,8 @@ const SESSION_EVENTS_FLAGS = {
 export default defineCommand({
   description: "List event history for a session",
   auth: "apiKey",
+  // Provider-aware gate: only the session's provider needs credentials.
+  authOptional: true,
   usageArgs: "--session-id <id> [--limit <n>] [--all] [--file <path>]",
   flags: SESSION_EVENTS_FLAGS,
   exampleArgs: ["--session-id sess_abc123", "--session-id sess_abc123 --all"],
@@ -49,7 +51,9 @@ export default defineCommand({
 
     const { items: events, hasMore } = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(ctx, file);
+        const runtime = await buildAgentRuntime(ctx, file, {
+          credentials: flags.provider ?? "targets",
+        });
         return fetchAllPages(async (page) => {
           const result = await listSessionEvents(runtime, flags.sessionId, {
             provider: flags.provider,