refactor: simplify command context capabilities

XXPermanentXX · XXPermanentXX · commit 63edde35888b · 2026-07-13T15:47:57.000+08:00
- replace lazy store and manager accessors with direct properties
- enforce command capability boundaries through lint rules
diff --git a/packages/commands/src/commands/auth/login.ts b/packages/commands/src/commands/auth/login.ts
@@ -87,7 +87,7 @@ export default defineCommand({
   },
   async run(ctx) {
     const { identity, settings, flags } = ctx;
-    const store = ctx.authStore();
+    const store = ctx.authStore;
     const deps = { identity, settings, authStore: store };
     const key = flags.apiKey;
     const baseUrl = flags.baseUrl || undefined;
diff --git a/packages/commands/src/commands/auth/logout.ts b/packages/commands/src/commands/auth/logout.ts
@@ -20,7 +20,7 @@ export default defineCommand({
     f.console && f.openApi ? "Use only one scope: --console or --open-api" : undefined,
   async run(ctx) {
     const { settings, flags } = ctx;
-    const store = ctx.authStore();
+    const store = ctx.authStore;
     const stored = store.stored();
 
     if (flags.console) {
diff --git a/packages/commands/src/commands/auth/status.ts b/packages/commands/src/commands/auth/status.ts
@@ -9,7 +9,7 @@ export default defineCommand({
   async run(ctx) {
     const { identity, settings } = ctx;
     const format = detectOutputFormat(settings.output);
-    const auth = ctx.authStore().describe();
+    const auth = ctx.authStore.describe();
 
     const apiKey = auth.apiKey
       ? {
diff --git a/packages/commands/src/commands/config/set.ts b/packages/commands/src/commands/config/set.ts
@@ -106,7 +106,7 @@ export default defineCommand({
     }
 
     const coerced = resolvedKey === "timeout" ? Number(value) : value;
-    await ctx.configStore().write({ [resolvedKey]: coerced } as Partial<ConfigFile>);
+    await ctx.configStore.write({ [resolvedKey]: coerced } as Partial<ConfigFile>);
 
     if (!settings.quiet) {
       const shown = SECRET_KEYS.has(resolvedKey) ? maskToken(String(coerced)) : coerced;
diff --git a/packages/commands/src/commands/config/show.ts b/packages/commands/src/commands/config/show.ts
@@ -7,7 +7,7 @@ export default defineCommand({
   exampleArgs: ["", "--output json"],
   async run(ctx) {
     const { settings, client } = ctx;
-    const store = ctx.configStore();
+    const store = ctx.configStore;
     const file = store.read();
     const format = detectOutputFormat(settings.output);
 
diff --git a/packages/commands/src/commands/plugin/install.ts b/packages/commands/src/commands/plugin/install.ts
@@ -15,7 +15,7 @@ export default defineCommand({
   },
   exampleArgs: ["--package @ali/bailian-plugin-agent", "--package @ali/bailian-plugin-agent@beta"],
   async run(ctx) {
-    const installed = await ctx.commandPacks().install(ctx.flags.package);
+    const installed = await ctx.commandPacks.install(ctx.flags.package);
     emitResult({ installed }, detectOutputFormat(ctx.settings.output));
   },
 });
diff --git a/packages/commands/src/commands/plugin/link.ts b/packages/commands/src/commands/plugin/link.ts
@@ -15,7 +15,7 @@ export default defineCommand({
   },
   exampleArgs: ["--path ../bailian-plugin-agent"],
   async run(ctx) {
-    const linked = await ctx.commandPacks().link(ctx.flags.path);
+    const linked = await ctx.commandPacks.link(ctx.flags.path);
     emitResult({ linked }, detectOutputFormat(ctx.settings.output));
   },
 });
diff --git a/packages/commands/src/commands/plugin/list.ts b/packages/commands/src/commands/plugin/list.ts
@@ -6,7 +6,7 @@ export default defineCommand({
   auth: "none",
   exampleArgs: ["", "--output json"],
   async run(ctx) {
-    const reports = await ctx.commandPacks().list();
+    const reports = await ctx.commandPacks.list();
     const format = detectOutputFormat(ctx.settings.output);
     if (format === "json") {
       emitResult({ command_packs: reports }, format);
diff --git a/packages/commands/src/commands/plugin/remove.ts b/packages/commands/src/commands/plugin/remove.ts
@@ -15,7 +15,7 @@ export default defineCommand({
   },
   exampleArgs: ["--name @ali/bailian-plugin-agent"],
   async run(ctx) {
-    await ctx.commandPacks().remove(ctx.flags.name);
+    await ctx.commandPacks.remove(ctx.flags.name);
     emitResult({ removed: ctx.flags.name }, detectOutputFormat(ctx.settings.output));
   },
 });
diff --git a/packages/commands/tests/boundaries.test.ts b/packages/commands/tests/boundaries.test.ts
diff --git a/packages/core/src/types/command.ts b/packages/core/src/types/command.ts
@@ -165,12 +165,12 @@ export interface CommandContext<F extends FlagsDef = FlagsDef> {
   flags: ParsedFlags<F>;
   /** Network surface; the credential for the command's `auth` is pre-injected. */
   client: Client;
-  /** 惰性访问器,lint 限定 commands/config/** 使用。 */
-  configStore(): ConfigStore;
-  /** 惰性访问器,lint 限定 commands/auth/** 使用。 */
-  authStore(): AuthStore;
-  /** 绑定当前产品的 Command Pack 管理器；仅限 commands/plugin/** 使用。 */
-  commandPacks(): CommandPackManager;
+  /** 配置持久化能力；lint 限定 commands/config/** 使用。 */
+  configStore: ConfigStore;
+  /** 鉴权持久化能力；lint 限定 commands/auth/** 使用。 */
+  authStore: AuthStore;
+  /** Command Pack 管理能力；lint 限定 commands/plugin/** 使用。 */
+  commandPacks: CommandPackManager;
 }
 
 // ── Command ──────────────────────────────────────────────────────────────────
diff --git a/packages/runtime/src/command-packs/validate.ts b/packages/runtime/src/command-packs/validate.ts
@@ -152,7 +152,7 @@ function adaptCommandPack(
                     ExitCode.GENERAL,
                   );
                 }
-                const credential = ctx.authStore().describe().apiKey;
+                const credential = ctx.authStore.describe().apiKey;
                 if (!credential) {
                   throw new BailianError(
                     "No API key available to the Command Pack.",
diff --git a/packages/runtime/src/create-cli.ts b/packages/runtime/src/create-cli.ts
@@ -183,9 +183,9 @@ export function createCli(commands: Record<string, AnyCommand>, opts: CliOptions
             flags: ownFlags,
             settings,
             sources,
-            configStore: () => makeConfigStore(),
-            authStore: () => makeAuthStore(sources),
-            commandPacks: () => commandPackManager,
+            configStore: makeConfigStore(),
+            authStore: makeAuthStore(sources),
+            commandPacks: commandPackManager,
             client: new Client({ identity, settings, baseUrl: resolveModelBaseUrl(sources) }),
           };
           await runMiddleware(ctx);
diff --git a/packages/runtime/src/middleware.ts b/packages/runtime/src/middleware.ts
@@ -46,12 +46,12 @@ export interface RunContext {
   settings: Settings;
   /** 解析源:provider/访问器用;业务命令不可见(窄视图类型不含此字段)。 */
   sources: ResolutionSources;
-  /** 惰性访问器,lint 限定 commands/config/** 使用。 */
-  configStore(): ConfigStore;
-  /** 惰性访问器,lint 限定 commands/auth/** 使用。 */
-  authStore(): AuthStore;
-  /** 绑定当前产品的 Command Pack 管理器；仅限 commands/plugin/** 使用。 */
-  commandPacks(): CommandPackManager;
+  /** 配置持久化能力；lint 限定 commands/config/** 使用。 */
+  configStore: ConfigStore;
+  /** 鉴权持久化能力；lint 限定 commands/auth/** 使用。 */
+  authStore: AuthStore;
+  /** Command Pack 管理能力；lint 限定 commands/plugin/** 使用。 */
+  commandPacks: CommandPackManager;
   /** Network surface with the credential baked in — set by {@link authStage}. */
   client: Client;
 }
diff --git a/vite.config.ts b/vite.config.ts
@@ -1,5 +1,29 @@
 import { defineConfig } from "vite-plus";
 
+const commandCapabilityRestrictions = [
+  {
+    property: "configStore",
+    message: "configStore is only available to commands/config/**.",
+  },
+  {
+    property: "authStore",
+    message: "authStore is only available to commands/auth/**.",
+  },
+  {
+    property: "commandPacks",
+    message: "commandPacks is only available to commands/plugin/**.",
+  },
+] as const;
+
+type CommandCapabilityRestriction = (typeof commandCapabilityRestrictions)[number];
+type CommandCapability = CommandCapabilityRestriction["property"];
+
+function restrictCommandCapabilities(
+  allowed?: CommandCapability,
+): ["error", ...CommandCapabilityRestriction[]] {
+  return ["error", ...commandCapabilityRestrictions.filter(({ property }) => property !== allowed)];
+}
+
 export default defineConfig({
   test: {
     globalSetup: "./packages/e2e/src/global-setup.ts",
@@ -25,6 +49,23 @@ export default defineConfig({
         files: ["packages/commands/src/commands/finetune/watch.ts"],
         rules: { "unicorn/no-process-exit": "off" },
       },
+      {
+        // 普通业务命令只依赖 settings/flags/client；持久化和管理能力按命令族开放。
+        files: ["packages/commands/src/commands/**/*.ts"],
+        rules: { "no-restricted-properties": restrictCommandCapabilities() },
+      },
+      {
+        files: ["packages/commands/src/commands/config/**/*.ts"],
+        rules: { "no-restricted-properties": restrictCommandCapabilities("configStore") },
+      },
+      {
+        files: ["packages/commands/src/commands/auth/**/*.ts"],
+        rules: { "no-restricted-properties": restrictCommandCapabilities("authStore") },
+      },
+      {
+        files: ["packages/commands/src/commands/plugin/**/*.ts"],
+        rules: { "no-restricted-properties": restrictCommandCapabilities("commandPacks") },
+      },
     ],
   },
   run: {

Original file line number	Diff line number	Diff line change
`@@ -106,7 +106,7 @@ export default defineCommand({`
`106`	`106`	`}`
`107`	`107`
`108`	`108`	`const coerced = resolvedKey === "timeout" ? Number(value) : value;`
`109`		`- await ctx.configStore().write({ [resolvedKey]: coerced } as Partial<ConfigFile>);`
	`109`	`+ await ctx.configStore.write({ [resolvedKey]: coerced } as Partial<ConfigFile>);`
`110`	`110`
`111`	`111`	`if (!settings.quiet) {`
`112`	`112`	`const shown = SECRET_KEYS.has(resolvedKey) ? maskToken(String(coerced)) : coerced;`