refactor(cmdline): make command providers ordinary

2026-08-10 21:49:11 +08:00
parent 668bdb3d8e
commit 09e2d2ddc1
46 changed files with 400 additions and 742 deletions
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/headless/README.md
-README.md: 459d0f32788265d43e75922067da3c03d054f444
-README.zh.md: e3ca9d13512e3a13ac71c5cda650fca958609062
+README.md: 31a4894dbb191d2244371ca7272339e96e253053
+README.zh.md: 6e8d28f10071fbab175c4f14f1aaa9618b8f598a
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -2,9 +2,9 @@

 English | [中文](README.zh.md)

-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`, resolved from the injected startup service). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`, resolved from the injected `headlessStartup` provider). It mounts no Host, HTTP server, Web runtime, or browser plugin.

-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the `headless-startup` row ([`src/startup.ts`](src/startup.ts)) reads it as the positional argument of `dsh --profile headless "task"` from `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), prints the app's `--help`, and rejects an invocation with no task instead of letting the runner's schema fail.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the ordinary `headless-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), reads the positional argument of `dsh --profile headless "task"`, prints the app's `--help`, and provides `headlessStartup`; the runner injects that service and reads its task from lazy config. A missing or whitespace-only task is rejected before the runner activates.

 ## Model Experience

--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -2,9 +2,9 @@

 [English](README.md) | 中文

-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`，从注入的启动服务解析）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`，从注入的 `headlessStartup` 提供方解析）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。

-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。任务文本就是这个应用的命令行：`headless-startup` 行（[`src/startup.ts`](src/startup.ts)）从 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)）把它读作 `dsh --profile headless "task"` 的位置参数，打印应用自己的 `--help`，并拒绝没有任务的调用，而不是让 runner 的 schema 失败。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。任务文本就是这个应用的命令行：普通 `headless-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），读取 `dsh --profile headless "task"` 的位置参数、打印应用自己的 `--help`，并提供 `headlessStartup`；runner 注入该服务，再从惰性配置中读取任务。缺失或只有空白的任务会在 runner 激活前被拒绝。

 ## 模型体验

--- a/packages/bundle/headless/cordis.patch.yml
+++ b/packages/bundle/headless/cordis.patch.yml
@@ -1,8 +1,8 @@
 # The dsh-headless bundle patch: one-shot task mode directly over dsh-base.
-# It mounts no Host, HTTP server, Web runtime, or browser plugin. The startup
-# row injects `cmdlineArgs`, owns the task positional
-# (`dsh --profile headless "<task>"`) and this app's --help; the direct driver
-# creates an Agent through the core registry and prints its durable result.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. An ordinary
+# provider plugin injects `cmdlineArgs`, parses the task positional
+# (`dsh --profile headless "<task>"`) and this app's --help, then the direct
+# driver creates an Agent through the core registry and prints its durable result.

 - id: system-prompt
  config:
@@ -25,10 +25,8 @@

    - id: headless-startup
      name: '@deepseek-ai/dsh-headless/startup'
-      inject: [cmdlineArgs]

-    # Reads its task from the headlessStartup service after the startup row
-    # resolves this app's command line.
+    # Reads its task from the ordinary headlessStartup provider.
    - id: headless-runner
      name: '@deepseek-ai/dsh-headless'
      inject: [headlessStartup]
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -25,7 +25,7 @@ export const name = 'headless-runner'
 /** Core services required before the one-shot turn can start. */
 export const inject = ['agentDefaultModel', 'agents', 'sessions']

-/** Plugin config: the task resolved from this app's injected startup service. */
+/** Plugin config: the task resolved from this app's injected provider service. */
 export interface Config {
  /** The prompt text for the single run. */
  task: string
--- a/packages/bundle/headless/src/startup.ts
+++ b/packages/bundle/headless/src/startup.ts
@@ -1,16 +1,13 @@
 /**
- * The one-shot app's startup row: it owns the `dsh --profile headless` command
- * line — the task text is this command's positional argument — and its
- * `--help` text, then provides {@link HEADLESS_STARTUP_SERVICE} with the task
- * the user asked for. The runner waits for it, so a missing task is a usage
- * error printed by this command instead of a schema failure inside the runner.
+ * The one-shot app's command-line provider: it parses the task positional and
+ * `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
+ * ordinary consumer whose lazy config waits for that service.
 * @module @deepseek-ai/dsh-headless/startup
 */

 import { Command } from 'commander'
 import type { Context } from 'cordis'
-import type { EntryOptions } from '@cordisjs/plugin-loader'
-import { runStartup } from '@deepseek-ai/dsh-cmdline'
+import { parseCmdline } from '@deepseek-ai/dsh-cmdline'

 /** Stable Cordis plugin name. */
 export const name = 'headless-startup'
@@ -18,12 +15,9 @@ export const name = 'headless-startup'
 /** Services required before the task can be resolved. */
 export const inject = ['cmdlineArgs']

-/** The service this row provides and the one-shot runner row reads. */
+/** Service provided by this plugin and injected by the one-shot runner. */
 export const HEADLESS_STARTUP_SERVICE = 'headlessStartup'

-/** The row that runs the task, and the only reason this app has a command line. */
-const RUNNER_ROW_ID = 'headless-runner'
-
 /** What the runner row reads from {@link HEADLESS_STARTUP_SERVICE}. */
 export interface HeadlessStartupValues {
  /** The task text this invocation asked for. */
@@ -47,27 +41,22 @@ Examples:
 }

 /**
- * Turn the parsed command line into the runner row's task.
+ * Turn the parsed command line into the runner's task.
 * @param program - the parsed headless command.
- * @param rows - the rows waiting on this app's service, in tree order.
- * @returns the runner row's service value.
- * @throws when the composition has no runner row, which would otherwise accept
- * a task and silently run nothing.
+ * @returns the runner's service value.
 */
-function planHeadlessStartup(program: Command, rows: readonly EntryOptions[]): HeadlessStartupValues {
+function planHeadlessStartup(program: Command): HeadlessStartupValues {
  const task = program.args.join(' ')
-  if (task === '') program.error('error: a task is required, for example: dsh --profile headless "run the tests"')
-  if (!rows.some(row => row.id === RUNNER_ROW_ID)) {
-    throw new Error(`headless-startup: the composition has no waiting "${RUNNER_ROW_ID}" row to run the task`)
-  }
+  if (task.trim() === '') program.error('error: a task is required, for example: dsh --profile headless "run the tests"')
  return { task }
 }

 /**
- * Resolve the task for the runner waiting on `headlessStartup`.
- * @param ctx - plugin context carrying the command line and the Loader.
- * @returns nothing once the runner is started, or once `--help` or a missing task requested exit.
+ * Parse and provide the one-shot task as an ordinary Cordis service.
+ * @param ctx - plugin context carrying the command line.
+ * @returns nothing once the task is provided, or when the command requested exit.
 */
 export function apply(ctx: Context): void {
-  runStartup(ctx, HEADLESS_STARTUP_SERVICE, headlessCommand(), planHeadlessStartup)
+  const values = parseCmdline(ctx, headlessCommand(), planHeadlessStartup)
+  if (values !== undefined) ctx.provide(HEADLESS_STARTUP_SERVICE, values)
 }
--- a/packages/bundle/headless/tests/startup.spec.ts
+++ b/packages/bundle/headless/tests/startup.spec.ts
@@ -1,7 +1,7 @@
 /**
- * The one-shot app's startup row over a real Loader tree: the task positional
- * becomes the injected runner config, while help and usage errors leave the
- * runner pending.
+ * The one-shot app's ordinary command-line provider over a real Loader tree:
+ * the task becomes injected runner config, while help and usage errors leave
+ * the consumer pending.
 */

 import { mkdtempSync, writeFileSync } from 'node:fs'
@@ -31,15 +31,11 @@ afterEach(async () => {
 })

 /**
- * Mount the real startup row over a runner stand-in.
+ * Mount the real provider over a runner stand-in.
 * @param args - the invocation's inner arguments.
- * @param options - fixture knobs for invalid compositions.
- * @returns the resolved startup value and observed runner/process effects.
+ * @returns the resolved service value and observed runner/process effects.
 */
-async function bootStartup(
-  args: string[],
-  options: { withoutRunner?: boolean } = {},
-): Promise<{ task: HeadlessStartupValues | undefined; observed: Observed }> {
+async function bootStartup(args: string[]): Promise<{ task: HeadlessStartupValues | undefined; observed: Observed }> {
  const dir = mkdtempSync(join(tmpdir(), 'dsh-headless-startup-'))
  const observed: Observed = { exits: [], out: '' }
  writeFileSync(join(dir, 'row.mjs'), 'export function apply(_ctx, config) { globalThis.__headlessStartupObserved.runnerConfig = config }\n')
@@ -52,14 +48,13 @@ export const apply = ctx => globalThis.__headlessStartupApply(ctx)
 `)
  const rowUrl = pathToFileURL(join(dir, 'row.mjs')).href
  writeFileSync(join(dir, 'cordis.yml'), [
-    options.withoutRunner === true ? '- id: displaced-runner' : '- id: headless-runner',
+    '- id: headless-runner',
    `  name: ${rowUrl}`,
    `  inject: [${HEADLESS_STARTUP_SERVICE}]`,
    '  config:',
    '    task: !!js ctx.headlessStartup.task',
    '- id: headless-startup',
    `  name: ${pathToFileURL(join(dir, 'startup.mjs')).href}`,
-    '  inject: [cmdlineArgs]',
    '',
  ].join('\n'))
  const observing = { write: (chunk: string) => { observed.out += chunk; return true } }
@@ -85,7 +80,7 @@ export const apply = ctx => globalThis.__headlessStartupApply(ctx)
  }
 }

-describe('headless startup', () => {
+describe('headless command-line provider', () => {
  it('joins the task positional into the runner config', async () => {
    const { task, observed } = await bootStartup(['run', 'the', 'tests'])
    expect(task).toEqual({ task: 'run the tests' })
@@ -93,8 +88,8 @@ describe('headless startup', () => {
    expect(observed.exits).toEqual([])
  })

-  it('rejects an invocation with no task and leaves the runner pending', async () => {
-    const { task, observed } = await bootStartup([])
+  it.each([{ args: [] }, { args: ['   '] }])('rejects an invocation with no non-whitespace task ($args)', async ({ args }) => {
+    const { task, observed } = await bootStartup(args)
    expect(observed.out).toContain('a task is required')
    expect(task).toBeUndefined()
    expect(observed.runnerConfig).toBeUndefined()
@@ -108,9 +103,4 @@ describe('headless startup', () => {
    expect(observed.runnerConfig).toBeUndefined()
    expect(observed.exits).toEqual([0])
  })
-
-  it('fails when the composition has no runner row', async () => {
-    await expect(bootStartup(['task'], { withoutRunner: true }))
-      .rejects.toThrow('the composition has no waiting "headless-runner" row')
-  })
 })