feat(agent): agent相关cli命令的client层功能，对齐cli client的基础能力

Author: chenanran555

docs/agents/auth-change.md

@@ -50,6 +50,10 @@ defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx
 
 命令不要直接解析 token、env 或 config。业务请求统一走 `ctx.client`;登录/配置命令通过 `ctx.authStore` / `ctx.configStore` 的窄接口操作落盘。
 
+### 例外:agent 命令的 SDK 凭证桥接
+
+`bl agent *` 命令声明 `auth: "none"`,凭证由 `@openagentpack/sdk` 自主从 env 解析(agents.yaml 的 `${DASHSCOPE_API_KEY}` / `${BAILIAN_WORKSPACE_ID}` 插值)。为让 bl 登录态复用,`packages/commands/src/commands/agent/_engine/credentials.ts` 的 `bridgeBailianCredentials()` 会**直接 `readConfigFile()`**,把 config 的 `api_key` / `workspace_id` 作为最低优先级兜底填入对应 env,仅填空值,不覆盖已有。这是唯一允许命令层直接读 config 的场景(SDK 只认 env,不走 `ctx.client`);优先级链:`~/.agents/config.json` > shell env > `.env` > `~/.bailian/config.json`。
+
 ## 必查清单
 
 ### A. core 层(类型 + 解析)

packages/cli/.gitignore

@@ -2,4 +2,7 @@ node_modules
 dist
 *.log
 .DS_Store
-outputs/
+outputs/
+# agents
+agents.state.json
+.env

packages/cli/agents.yaml

@@ -0,0 +1,26 @@
+version: "1"
+
+providers:
+  bailian:
+    api_key: ${DASHSCOPE_API_KEY}
+    workspace_id: ${BAILIAN_WORKSPACE_ID}
+
+defaults:
+  provider: bailian
+
+environments:
+  dev:
+    config:
+      type: cloud
+      networking:
+        type: unrestricted
+
+agents:
+  assistant:
+    description: "General-purpose assistant"
+    model: qwen3.7-max
+    instructions: |
+      You are a helpful assistant.
+    environment: dev
+    tools:
+      builtin: [bash, read, glob, grep]

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

@@ -6,16 +6,27 @@ import {
 } from "@openagentpack/sdk";
 import { ensureCredentials } from "./credentials.ts";
 import { loadFileState } from "./file-state-manager.ts";
+import { type HostContext, installSdkTransport } from "./transport.ts";
+
+export { CREDENTIALS_NOTE } from "./credentials.ts";
 
 /**
  * Build a full ProjectRuntimeContext from a config file path — the standard
  * entry point for agent commands that need the SDK engine. Mirrors OpenAgentPack
  * CLI's buildCliRuntime: resolve config → load local state → assemble runtime.
+ * Takes the host context first so every SDK-engine command wires the
+ * instrumented transport (UA / tracking headers / verbose) by construction.
  */
 export async function buildAgentRuntime(
+  host: HostContext,
   filePath: string,
-  options: { resolveEnv?: boolean; projectName?: string; statePath?: string } = {},
+  options: {
+    resolveEnv?: boolean;
+    projectName?: string;
+    statePath?: string;
+  } = {},
 ): Promise<ProjectRuntimeContext & { configPath: string }> {
+  installSdkTransport(host);
   ensureCredentials();
   const { config, configPath, projectName } = await resolveProjectConfig(filePath, options);
   const state = await loadFileState(configPath, options.statePath, projectName);

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

@@ -1,18 +1,59 @@
 import { bootstrapRuntimeCredentialsSync } from "@openagentpack/sdk";
+import { readConfigFile } from "bailian-cli-core";
 
 let bootstrapped = false;
 
+/**
+ * Shared `--help` note documenting where agent commands get provider
+ * credentials. Mirrors the credential-source hint bl's native commands surface
+ * (knowledge / usage / token-plan), adapted for the SDK's env-based resolution
+ * and the {@link bridgeBailianCredentials} fallback. Attach to every command
+ * that loads agents.yaml. `bl` prefix is safe: agent commands ship on `bl` only.
+ */
+export const CREDENTIALS_NOTE = [
+  "Credentials come from the env vars referenced in agents.yaml (e.g. ${DASHSCOPE_API_KEY}, ${BAILIAN_WORKSPACE_ID}).",
+  "For the bailian provider, bl fills these from your login as a fallback: `bl auth login` (API key) and `bl config set workspace_id <id>`.",
+];
+
+/**
+ * Bridge bl's own login state into the env vars the OpenAgentPack SDK reads for
+ * the bailian provider. bl persists `api_key` / `workspace_id` in
+ * `~/.bailian/config.json` (via `bl auth login` / `bl config set`); mirror them
+ * onto `DASHSCOPE_API_KEY` / `BAILIAN_WORKSPACE_ID` so users don't have to
+ * re-declare the same credentials for `bl agent *`.
+ *
+ * Lowest priority: only fills a var that is still unset, so anything already in
+ * the environment (shell export, `.env`, or `~/.agents/config.json` — which the
+ * SDK bootstrap has already applied) wins. Missing values are left alone; the
+ * SDK surfaces its own error when interpolation can't resolve, and non-bailian
+ * providers (claude/qoder/ark) don't need DashScope credentials at all.
+ */
+export function bridgeBailianCredentials(): void {
+  const file = readConfigFile();
+  if (!process.env.DASHSCOPE_API_KEY?.trim() && file.api_key) {
+    process.env.DASHSCOPE_API_KEY = file.api_key;
+  }
+  if (!process.env.BAILIAN_WORKSPACE_ID?.trim() && file.workspace_id) {
+    process.env.BAILIAN_WORKSPACE_ID = file.workspace_id;
+  }
+}
+
 /**
  * Lazily load `.env` and `~/.agents/config.json` into `process.env` so the
  * OpenAgentPack SDK can resolve provider credentials (e.g. DASHSCOPE_API_KEY,
- * BAILIAN_WORKSPACE_ID). Safe to call repeatedly — only the first call does I/O.
+ * BAILIAN_WORKSPACE_ID), then bridge bl's own config as a fallback. Safe to call
+ * repeatedly — only the first call does I/O.
+ *
+ * Effective precedence for bailian provider fields:
+ *   ~/.agents/config.json > shell env > .env > ~/.bailian/config.json
  *
  * NOTE: agent commands declare `auth: "none"` and let the SDK own credential
- * resolution. This is the documented tradeoff of the wholesale SDK integration;
- * bl's own `--api-key` / `bl auth login` flow is bridged separately as a follow-up.
+ * resolution. The bl-config bridge is a best-effort fallback; it never overrides
+ * a value the SDK bootstrap already resolved.
  */
 export function ensureCredentials(): void {
   if (bootstrapped) return;
   bootstrapped = true;
   bootstrapRuntimeCredentialsSync();
+  bridgeBailianCredentials();
 }

packages/commands/src/commands/agent/_engine/errors.ts

@@ -1,18 +1,56 @@
 import { UserError } from "@openagentpack/sdk";
-import { BailianError, ExitCode } from "bailian-cli-core";
+import { type ApiErrorBody, BailianError, ExitCode, mapApiError } from "bailian-cli-core";
+
+/**
+ * Structural shape of the SDK's `ApiError` (thrown by provider clients on HTTP
+ * 4xx/5xx). Matched on fields instead of `instanceof` because the installed SDK
+ * version does not export the class yet, and structural matching keeps this
+ * check stable across SDK versions either way.
+ */
+interface SdkApiErrorLike extends Error {
+  statusCode: number;
+  responseBody: string;
+}
+
+function isSdkApiError(error: Error): error is SdkApiErrorLike {
+  const candidate = error as Partial<SdkApiErrorLike>;
+  return typeof candidate.statusCode === "number" && typeof candidate.responseBody === "string";
+}
+
+/**
+ * The SDK embeds the raw response body in its error message; recover the
+ * structured fields (message / code / request_id) when the body is JSON so
+ * `mapApiError` surfaces a clean server message plus api metadata. Non-JSON
+ * bodies pass through verbatim as the message.
+ */
+function parseSdkResponseBody(raw: string): ApiErrorBody {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as ApiErrorBody;
+  } catch {
+    /* non-JSON body */
+  }
+  return { message: raw.trim() || undefined };
+}
 
 /**
  * Run an SDK-backed operation, translating SDK error types into BailianError so
  * bl's error handler produces the right exit code and hint formatting.
- * SDK `UserError` → USAGE/GENERAL; any other Error → GENERAL (message passed
- * through, per bl's "don't translate server errors" boundary).
+ * SDK `UserError` → USAGE; SDK `ApiError` (server HTTP error) → GENERAL via
+ * `mapApiError` (server message passed through verbatim, with
+ * httpStatus/apiCode/requestId metadata for --output json); any other Error →
+ * GENERAL (message passed through, per bl's "don't translate server errors"
+ * boundary).
  */
 export async function withAgentErrors<T>(fn: () => Promise<T>): Promise<T> {
   try {
     return await fn();
   } catch (error) {
     if (error instanceof BailianError) throw error;
     if (error instanceof UserError) throw new BailianError(error.message, ExitCode.USAGE);
+    if (error instanceof Error && isSdkApiError(error)) {
+      throw mapApiError(error.statusCode, parseSdkResponseBody(error.responseBody));
+    }
     if (error instanceof Error) throw new BailianError(error.message, ExitCode.GENERAL);
     throw error;
   }

packages/commands/src/commands/agent/_engine/transport.ts

@@ -0,0 +1,29 @@
+import * as sdk from "@openagentpack/sdk";
+import {
+  createInstrumentedFetch,
+  type FetchImplementation,
+  type Identity,
+  type Settings,
+} from "bailian-cli-core";
+
+/** The slice of CommandContext the transport wrapper needs (UA identity + verbose). */
+export interface HostContext {
+  identity: Identity;
+  settings: Settings;
+}
+
+let installed = false;
+
+/**
+ * Route the SDK's provider-client requests through the CLI's instrumented
+ * fetch (UA, host-gated tracking headers, --verbose logging). Feature-detected:
+ * `setDefaultFetch` landed after @openagentpack/sdk 0.1.0 — on older versions
+ * this is a silent no-op and the SDK keeps using the global fetch as before.
+ */
+export function installSdkTransport(host: HostContext): void {
+  if (installed) return;
+  const setDefaultFetch = (sdk as Record<string, unknown>).setDefaultFetch;
+  if (typeof setDefaultFetch !== "function") return;
+  (setDefaultFetch as (fetchImpl: FetchImplementation) => void)(createInstrumentedFetch(host));
+  installed = true;
+}

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

@@ -8,7 +8,11 @@ import {
 import { emitBare, emitResult } from "bailian-cli-runtime";
 import { executePlannedProject, planProjectContext } from "@openagentpack/sdk";
 import { formatResourceLabel } from "./_engine/address-utils.ts";
-import { assertProviderConfigured, buildAgentRuntime } from "./_engine/config-loader.ts";
+import {
+  assertProviderConfigured,
+  buildAgentRuntime,
+  CREDENTIALS_NOTE,
+} from "./_engine/config-loader.ts";
 import { withStdoutProtected } from "./_engine/console-capture.ts";
 import { withAgentErrors } from "./_engine/errors.ts";
 import { renderAgentFeedback } from "./_engine/feedback.ts";
@@ -45,14 +49,15 @@ export default defineCommand({
   usageArgs: "[--file <path>] [--provider <name>] [--yes] [--concurrency <n>]",
   flags: APPLY_FLAGS,
   exampleArgs: ["--yes", "--provider bailian --yes"],
+  notes: CREDENTIALS_NOTE,
   async run(ctx) {
     const { settings, flags } = ctx;
     const format = detectOutputFormat(settings.output);
     const file = flags.file ?? "agents.yaml";
 
     const planned = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(file);
+        const runtime = await buildAgentRuntime(ctx, file);
         assertProviderConfigured(runtime, flags.provider);
         return planProjectContext(runtime, {
           provider: flags.provider,

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

@@ -8,7 +8,7 @@ import {
 import { emitBare, emitResult } from "bailian-cli-runtime";
 import { destroyPlannedProjectResources, planDestroyProjectContext } from "@openagentpack/sdk";
 import { formatResourceLabel } from "./_engine/address-utils.ts";
-import { buildAgentRuntime } from "./_engine/config-loader.ts";
+import { buildAgentRuntime, CREDENTIALS_NOTE } from "./_engine/config-loader.ts";
 import { withStdoutProtected } from "./_engine/console-capture.ts";
 import { withAgentErrors } from "./_engine/errors.ts";
 
@@ -34,14 +34,15 @@ export default defineCommand({
   usageArgs: "[--file <path>] [--yes] [--cascade]",
   flags: DESTROY_FLAGS,
   exampleArgs: ["--yes", "--yes --cascade"],
+  notes: CREDENTIALS_NOTE,
   async run(ctx) {
     const { settings, flags } = ctx;
     const format = detectOutputFormat(settings.output);
     const file = flags.file ?? "agents.yaml";
 
     const planned = await withAgentErrors(() =>
       withStdoutProtected(async () => {
-        const runtime = await buildAgentRuntime(file);
+        const runtime = await buildAgentRuntime(ctx, file);
         return planDestroyProjectContext(runtime);
       }),
     );

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

@@ -18,7 +18,7 @@ agents.state.json
 const PROVIDERS = ["bailian", "claude", "qoder", "ark", "all"] as const;
 
 const PROVIDER_BLOCKS: Record<string, string> = {
-  bailian: `  bailian:\n    api_key: \${DASHSCOPE_API_KEY}\n    workspace_id: \${BAILIAN_WORKSPACE_ID}`,
+  bailian: `  bailian:\n    # bl auth login sets DASHSCOPE_API_KEY; bl config set workspace_id <id> sets BAILIAN_WORKSPACE_ID\n    api_key: \${DASHSCOPE_API_KEY}\n    workspace_id: \${BAILIAN_WORKSPACE_ID}`,
   claude: `  claude:\n    api_key: \${ANTHROPIC_API_KEY}`,
   qoder: `  qoder:\n    api_key: \${QODER_PAT}\n    gateway: "https://api.qoder.com/api/v1/cloud"`,
   ark: `  ark:\n    api_key: \${ARK_API_KEY}`,
@@ -135,6 +135,11 @@ export default defineCommand({
       emitResult({ created: file, provider, agent: agentName }, format);
     } else {
       emitBare(`Created ${file}`);
+      if (provider === "bailian" || provider === "all") {
+        emitBare(
+          "Credentials: run `bl auth login` and `bl config set workspace_id <id>`, or set DASHSCOPE_API_KEY / BAILIAN_WORKSPACE_ID.",
+        );
+      }
       emitBare("Next: edit agents.yaml, then run `bl agent plan`.");
     }
   },