从 cordis.yml 到运行中的树

142function composeProfile(143  name: string,144  patchFiles: readonly string[],145): ComposedProfile {146  const profile = prepareProfile(name)147  const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? []148  const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)))149  const bundlePatches = profile.layers.flatMap(layer => layer.patches)150  const rows = new Map<string, EntryOptions>()151  for (const row of composeEntries([bundlePatches, profile.patches, homePatches, overlays])) {152    if (typeof row.id === 'string') rows.set(row.id, row)153  }

105/** One profile's patch layers (application order) and the row index of its pre-flag composition. */106interface ComposedProfile {107  profile: Profile108  /** Bundle layers concatenated — the part below the user layers on a live reload. */109  bundlePatches: PatchOptions[]110  /** The home-level user layer (`$DSH_HOME/cordis.patch.yml`), applied after the profile's own. */111  homePatches: PatchOptions[]112  /** Layers above the user layers on a live reload: `--patch` overlays and the telemetry switch. */113  overlays: PatchOptions[]114  /**115   * id → row of the composed tree (bundles + user layers + overlays), for the116   * launcher's own row checks.117   */118  rows: ReadonlyMap<string, EntryOptions>119}120121/** The full patch stack of one composed profile, in application order. */122function allPatches(composed: ComposedProfile): PatchOptions[] {123  return [⋯    ...composed.bundlePatches,⋯    ...composed.profile.patches,⋯    ...composed.homePatches,⋯    ...composed.overlays,128  ]129}

371export function loadProfile(372  binName: string, name: string, installAnchor: string, home: string = resolveDshHome(),373  options: { userLayer?: boolean } = {},374): Profile {375  const dir = resolveProfileDir(name, home)376  if (!existsSync(join(dir, 'package.json'))) {377    const template = PROFILE_TEMPLATES[name]378    if (template === undefined) {379      throw new Error(380        `${binName}: profile ${JSON.stringify(name)} does not exist; create it with 'dsh plugin --profile ${name} add <package>'`,381      )382    }383    initProfile(dir, template)384  }385  const manifest = normalizeShippedProfile(name, dir, readProfileManifest(binName, dir))386  // A hand-written profile manifest may omit the dsh section entirely.387  const bundles = manifest.dsh?.profile?.bundles ?? []388  const layers = bundles.map((packageName): ProfileLayer => {389    const packageDir = resolveBundleDir(binName, packageName, installAnchor, dir)390    const bundleManifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')) as ProfileManifest391    const declared = bundleManifest.dsh?.bundle?.patch392    if (declared === undefined) {393      throw new Error(`${binName}: profile bundle ${JSON.stringify(packageName)} declares no dsh.bundle in its package.json`)394    }395    const patchPath = join(packageDir, declared)396    return { packageName, packageDir, patchPath, patches: loadOverlayPatches(binName, patchPath) }397  })398  const patchPath = join(dir, PROFILE_PATCH_FILENAME)399  const patches = options.userLayer !== false && existsSync(patchPath)400    ? loadOverlayPatches(binName, patchPath)401    : []402  return { name, dir, layers, patchPath, patches }403}

59/** The empty root entry list every profile tree patches over. */60const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tree is composed as patches:61# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any62# --patch overlays. Edit cordis.patch.yml, not this file.63[]64`

103    ctx.on('internal/update', async function (config, noSave, next) {104      if (!this.entry || noSave || this.parent.fiber?.entry === this.entry) return next()105      await next()106      const unparse = this.runtime?.Config?.['simplify']107      this.entry.options.config = unparse ? unparse(config) : config108      this.entry.parent.tree.write()109    }, { global: true, prepend: true })

413export function composeEntries(414  layers: readonly PatchOptions[][], warn: (message: string) => void = () => {},415): EntryOptions[] {416  return applyEntryPatches([], structuredClone(layers.flat()), (message: string, ...args: unknown[]) => {417    let index = 0418    warn(message.replace(/%C/g, () => JSON.stringify(args[index++])))419  })420}

58export function applyEntryPatches(59  data: EntryOptions[],60  patches: PatchOptions[] | undefined,61  warn: (message: string, ...args: any[]) => void,62): EntryOptions[] {63  data = structuredClone(data)64  if (!patches?.length) return data6566  const entryMap = new Map<string, EntryOptions>()67  const buildMap = (entries: EntryOptions[]) => {68    for (const entry of entries) {69      if (entry.id) entryMap.set(entry.id, entry)70      if (entry.group && Array.isArray(entry.config)) {71        buildMap(entry.config)72      }73    }74  }75  buildMap(data)7677  for (const patch of patches) {78    const { id, insert, name, ...overrides } = patch7980    if (insert) {81      if (id) {82        const target = entryMap.get(id)83        if (!target) {84          warn('patch insert: entry %C not found', id)85          continue86        }87        if (!target.group) {88          warn('patch insert: entry %C is not a group', id)89          continue90        }91        if (!Array.isArray(target.config)) target.config = []92        target.config.push(...insert)93      } else {94        data.push(...insert)95      }96      // Index what this patch added so a LATER patch in the same list can97      // target it. Patch lists compose one layer per source (each bundle98      // layer, then the user's, then `--patch` overlays), and a layer must be99      // able to configure or disable a row an earlier layer inserted; without100      // this, inserted rows were silently unpatchable.101      buildMap(insert)102      continue103    }104105    if (!id) {106      warn('patch: id is required for non-insert patches')107      continue108    }109110    const target = entryMap.get(id)111    if (!target) {112      warn('patch: entry %C not found', id)113      continue114    }115116    if (name && name !== target.name) {117      warn('patch: name mismatch for %C (expected %C, got %C), skipping', id, target.name, name)118      continue119    }120121    for (const [key, value] of Object.entries(overrides)) {122      if (key === 'id') continue123      target[key] = value124    }125  }126127  return data128}

144/** Runtime patch applied to entries loaded from an included config file. */145export interface PatchOptions {146  id?: string147  insert?: EntryOptions[]148  name?: string149  config?: any150  group?: boolean | null151  disabled?: boolean | null152  inject?: any153  intercept?: any154  isolate?: any155  [key: string]: any156}

267/**268 * Load an optional patch-list file: a top-level YAML array of loader patch269 * entries (`@deepseek-ai/cordis-plugin-include`'s `PatchOptions`): id-targeted config270 * overrides and `insert` lists, with `!!js` expressions allowed. A missing271 * file means "no layer"; an unreadable, unparsable, or non-array file throws —272 * a present patch file that cannot apply is a misconfiguration and must fail273 * loud at boot, never be silently skipped.274 * @param binName - the diagnostic prefix on the thrown error.275 * @param file - absolute path of the patch file.276 * @returns the parsed patches, or `undefined` when the file does not exist.277 */278export function loadOptionalPatches(binName: string, file: string): PatchOptions[] | undefined {279  let content: string280  try {281    content = readFileSync(file, 'utf8')282  } catch (error) {283    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return undefined284    throw new Error(`${binName}: failed to read patches ${file}: ${String(error)}`)285  }286  return parsePatchList(binName, file, content, 'patches')287}

289/**290 * Load a required overlay patch list: a bundle's `cordis.patch.yml` or a291 * `--patch <path>` overlay. Same file format as {@link loadOptionalPatches},292 * but a missing file throws, because the caller named this file — its absence293 * is a misconfiguration, not "no overlay".294 * @param binName - the diagnostic prefix on the thrown error.295 * @param file - absolute path of the overlay file.296 * @returns the parsed patch list.297 */298export function loadOverlayPatches(binName: string, file: string): PatchOptions[] {299  let content: string300  try {301    content = readFileSync(file, 'utf8')302  } catch (error) {303    throw new Error(`${binName}: failed to read overlay ${file}: ${String(error)}`)304  }305  return parsePatchList(binName, file, content, 'overlay')306}

320function parsePatchList(321  binName: string, file: string, content: string, label: string,322): PatchOptions[] {323  let parsed: unknown324  try {325    parsed = yaml.load(content, { schema: userPatchesSchema })326  } catch (error) {327    throw new Error(`${binName}: failed to parse ${label} ${file}: ${String(error)}`)328  }329  if (!Array.isArray(parsed)) {330    throw new Error(`${binName}: ${label} ${file} must be a top-level YAML array of loader patch entries`)331  }332  parsed.forEach((entry, index) => {333    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {334      throw new Error(`${binName}: ${label} entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)335    }336  })337  return parsed as PatchOptions[]338}

757export async function boot(758  binName: string,759  absoluteConfigPath: string,760  patches?: PatchOptions[],761  prepare?: (ctx: Context) => Promise<void> | void,762  bareModuleBaseUrl?: string,763): Promise<Context> {764  const ctx = new Context()765  // Two failure labels: `prepare` runs before any config-tree entry mounts,766  // so its failure is host setup, not the plugin tree.767  let stage = 'host preparation failed'768  try {769    ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'770    ctx.provide('dshHomePath', dshHomePath)771    await ctx.plugin(Loader)772    await prepare?.(ctx)773    stage = 'plugin tree failed to load'774    await mountRootInclude(ctx, absoluteConfigPath, patches, bareModuleBaseUrl)

59  async update(config: EntryOptions[]) {60    const oldConfig = this.data as EntryOptions[]61    const seen = new Set<string>()62    for (const options of config) {63      const id = this.tree.ensureId(options)64      if (seen.has(id)) throw new TypeError(`duplicate loader entry id: ${id}`)65      seen.add(id)66    }67    const oldMap = Object.fromEntries(oldConfig.map(options => [options.id, options]))68    const newMap = Object.fromEntries(config.map(options => [options.id, options]))6970    try {71      const outcomes = await Promise.allSettled(config.map(options => this.create(options)))72      // Disposal owns termination: sibling starts can still be settling after73      // the containing tree has gone away, but their failures no longer74      // describe a live update to roll back.75      if (this.ctx.fiber.uid === null) return76      const failures = outcomes77        .filter((outcome): outcome is PromiseRejectedResult => outcome.status === 'rejected')78        .map(outcome => outcome.reason)79      if (failures.length === 1) throw failures[0]80      if (failures.length > 1) throw new AggregateError(failures, 'loader entries failed to apply')81      for (const id of Object.keys(oldMap)) {82        if (!newMap[id]) await this.remove(id, true)83      }84      this.data = config85    } catch (error) {86      const rollbackErrors: unknown[] = []87      for (const id of Object.keys(newMap).reverse()) {88        if (oldMap[id]) continue89        try {90          await this.remove(id, true)91        } catch (rollbackError) {92          rollbackErrors.push(rollbackError)93        }94      }95      for (const options of oldConfig) {96        try {97          await this.create(options)98        } catch (rollbackError) {99          rollbackErrors.push(rollbackError)100        }101      }102      this.data = oldConfig103      if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], 'loader entry rollback failed')104      throw error105    }106  }

142  async update(options: Partial<EntryOptions>, create = false, force = false) {143    const previousOptions = this.options144    const legacy = { ...previousOptions }145    const candidate = create ? options as EntryOptions : { ...previousOptions }146    if (!create) {147      for (const [key, value] of Object.entries(options)) {148        if (isNullable(value)) {149          delete candidate[key as keyof EntryOptions]150        } else {151          candidate[key as keyof EntryOptions] = value as never152        }153      }154    }155    sortKeys(candidate)156157    const diff = Object158      .keys({ ...candidate, ...legacy })159      .filter(key => !deepEqual(candidate[key as keyof EntryOptions], legacy[key as keyof EntryOptions]))160    if (!diff.length && !force) return

194    const replace = diff.some(key => key === 'name' || key === 'inject' || key === 'group')195    if (!replace) {196      this.options = candidate197      try {198        await this._patchContext(diff)199      } catch (error) {200        this.options = previousOptions201        try {202          await this._patchContext(diff)203        } catch (rollbackError) {204          throw updateError('rollback', legacy, new AggregateError([error, rollbackError]))205        }206        this.context.emit('loader/partial-dispose', this, candidate, true)207        throw updateError('apply', candidate, error)208      }209      commit()210      this.context.emit('loader/partial-dispose', this, legacy, true)211      return212    }

277  private async _init() {278    let plugin: any279    try {280      plugin = this.loader.unwrapExports(await this.parent.tree.import(this.options.name, this.getOuterStack))281    } catch (error) {282      throw updateError('import', this.options, error)283    }284    try {285      await this._start(plugin)286    } catch (error) {287      throw updateError('apply', this.options, error)288    }289  }290291  private async _start(plugin: any) {292    let fiber: Fiber | undefined293    try {294      await this._patchContext([])295      this.loader.showLog(this, 'apply')296      fiber = this.fiber = this.ctx.registry.plugin(plugin, this.options.config, this.getOuterStack)297      await fiber.await()298    } catch (error) {299      await this._dispose(fiber)300      throw error301    }302  }303}

9const JsExpr = new yaml.Type('tag:yaml.org,2002:js', {10  kind: 'scalar',11  resolve: (data) => typeof data === 'string',12  construct: (data) => ({ __jsExpr: data }),13  predicate: isJsExpr,14  represent: (data) => data['__jsExpr'],15})1617/**18 * The entry-list YAML dialect: `!!js` scalars round-trip as expression nodes19 * the Loader evaluates at entry activation. Exported so config tooling20 * (`dsh --dump-config`) parses and prints exactly the dialect this include21 * mounts.22 */23export const entryListSchema = yaml.JSON_SCHEMA.extend(JsExpr)

92    ctx.on('internal/config', function (this: Fiber, _config, next) {93      const config = next()94      if (!this.entry || this.parent.fiber?.entry === this.entry) return config95      // Tree carriers (Group, Include) keep their configs literal: their96      // entry and patch lists hold other rows' configs, whose `!!js`97      // expressions belong to those rows' own fibers.98      const plugin = this.runtime?.callback as Record<PropertyKey, unknown> | undefined99      if (plugin?.[EntryGroup.key]) return config100      return interpolate(this.ctx, config)101    }, { global: true })

3// eslint-disable-next-line no-new-func4/** Evaluate a JavaScript expression against a loader context scope. */5export const evaluate = new Function('ctx', 'expr', `6  with (ctx) {7    return eval(expr)8  }9`) as ((ctx: object, expr: string) => any)1011/** Recursively replace YAML `!js` expression nodes with evaluated values. */12export function interpolate(ctx: object, value: any) {13  if (isJsExpr(value)) {14    return evaluate(ctx, value.__jsExpr)15  } else if (!value || typeof value !== 'object') {16    return value17  } else if (Array.isArray(value)) {18    return value.map(item => interpolate(ctx, item))19  } else {20    return valueMap(value, item => interpolate(ctx, item))21  }22}

100  /**101   * Effective disabled state: a `!!js` expression evaluates against the loader102   * context. The raw node stays in the options, so write-back keeps the form.103   */104  private disabledOf(options: EntryOptions): boolean {105    return isJsExpr(options.disabled)106      ? Boolean(this.evaluate(options.disabled.__jsExpr))107      : Boolean(options.disabled)108  }

97Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and root `.env`. cordis.yml allows `!!js` (never `!js`) under plugin `config` and entry `disabled`; other metadata stays literal, so conditional composition also uses overlays ([primer](docs/cordis-primer.md#loader-configuration)). Never commit credentials. CI e2e skips without a key; [testing.md](docs/testing.md) owns key policy.

178    - id: bash-sandbox179      name: '@deepseek-ai/dsh-bash-sandbox'180      disabled: !!js process.platform === 'win32'181      config:182        timeoutMs: 60000183184    - id: pwsh-sandbox185      name: '@deepseek-ai/dsh-pwsh-sandbox'186      disabled: !!js process.platform !== 'win32'

1# The dsh-base bundle patch: the shared core of every dsh profile, applied as2# ONE insert over the empty profile root. Later bundle patches and the user's3# profile cordis.patch.yml address these rows by id, with the last write4# winning per row.5#6# A patch replaces the targeted row's whole `config` rather than merging into7# it, so a row whose value differs by mode does NOT live here: it belongs to8# each mode bundle, keeping any single row down to one bundle layer plus the9# user's. Mode-specific rows appear below only with shared plugin identity and10# neutral defaults; each mode bundle restates its complete configuration.11#12# Row order carries no load semantics (activation is service-availability13# driven); the grouping is for readers.

17A running `dsh` is a plugin tree composed at boot from ordered layers.1819A **profile** is a named composition stored in the Harness home. It lists the bundles it stacks, holds any out-of-tree plugins it installs, and keeps the user's own `cordis.patch.yml`. `web` and `headless` ship as templates.2021A **bundle** is a distribution format for Cordis config rows and the code they mount, so whatever it inserts stays patchable by the layers above it.2223Each declares itself in its own `package.json` under a `dsh` field: `dsh.profile` lists a profile's bundles, and `dsh.bundle` points at a bundle's patch file.2425[`dsh-base`](../packages/bundle/base/README.md) is the first layer of every profile: model adapters, tools, persistence, sandbox and approval policy, settings, credentials, telemetry. [`dsh-web-app`](../packages/bundle/web-app/README.md) adds the browser application; [`dsh-headless`](../packages/bundle/headless/README.md) adds a one-shot runner with no server at all.2627Layers apply to an empty entry list in this order: each bundle in the profile's listed order, then the profile's `cordis.patch.yml`, then the home-level one, then any `--patch` overlay. A patch targets a row by id and replaces its whole config, or inserts new rows.

35Any row it prints can be replaced by a patch of your own.3637Composition mechanics are in [app-boot](../packages/boot/app-boot/README.md#profiles); config fields are in the generated [config catalog](config-catalog.md).

5The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, the shared [`agent-default-model`](../../core/agent-default-model/README.md) selection, tools, persistence, policy, settings/credentials, telemetry, and the core spawn/fork subagent providers — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. The optional Codex and Claude Code providers stay outside this package and its production dependency closure; a Profile installs either [product provider Bundle](../../subagent/README.md) only when needed. The default `@deepseek-ai/dsh` production closure therefore includes neither product provider, the Claude Agent SDK, nor the Codex wrapper and platform payloads. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.

21- **A patch replaces whole row configs** — profile overrides must restate every field a row keeps; there is no deep-merge layer.

1# The dsh-web-app bundle patch: the browser surface over the dsh-base layer.2# Applied after dsh-base's insert; rows here override base rows by id, with3# the profile's own cordis.patch.yml and any --patch overlays still to come.4#5# A patch replaces the targeted row's whole `config`, so each row below6# restates every key it owns.7#8# The web-startup plugin injects `cmdlineArgs` and provides `webStartup` as an9# ordinary Cordis service. Rows configured from flags inject that service, so10# Loader resolves their expressions only after it exists. The web runtime then11# provides bind-dependent `webRuntime` values to the trust fence.12# `dsh --profile web --help` provides neither service, so no server binds.1314# ── surface-specific values the base deliberately omits ─────────────────────1516- id: system-prompt17  config:18    persona: >-19      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.2021# TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.22- id: hmr23  disabled: true

200describe('composeEntries', () => {201  it('applies layers over an empty root and reports skipped patches', () => {202    const warnings: string[] = []203    const entries = composeEntries([204      [{ insert: [{ id: 'x', name: 'pkg-x', config: { a: 1 } }] }],205      [{ id: 'x', config: { a: 2 } }, { id: 'missing', config: {} }],206    ], message => warnings.push(message))207    expect(entries).toEqual([{ id: 'x', name: 'pkg-x', config: { a: 2 } }])208    expect(warnings.join('\n')).toContain('"missing"')209    // Default warn sink: skipped patches are silently dropped (boot repeats them).210    expect(composeEntries([[{ id: 'missing', config: {} }]])).toEqual([])211  })212})

348/**349 * Compose the effective entry list exactly as `boot()` would mount it: parse350 * the base config file with the include's entry-list dialect, apply every351 * layer's patches as ONE flattened list through the include's own patch352 * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so353 * even patch-visibility corner cases (a later layer targeting a group child a354 * plain config replacement introduced, which the single-pass id index never355 * sees) compose identically — then render the result as YAML in the same356 * dialect (`!!js` expressions print verbatim, unevaluated).

5These may be applied at any level of the [settings hierarchy](https://code.claude.com/docs/en/settings#settings-files), though certain properties only take effect if specified in enterprise settings (e.g. `strictKnownMarketplaces`, `allowManagedHooksOnly`, `allowManagedPermissionRulesOnly`).

26- Before deploying configuration files to your organization, test them locally by applying to `managed-settings.json`, `settings.json` or `settings.local.json`

24- Settings deployed this way sit at the top of the precedence order and cannot be overridden by users

304- Changed `sandbox.ripgrep` to be honored only from user, managed, and `--settings` settings; project settings can no longer override the sandbox's ripgrep binary

357- Fixed a settings-merge issue where a marketplace entry redefined in a higher-precedence settings tier could inherit another tier's custom headers; marketplace entries now merge as whole entries

1{2  "permissions": {3    "disableBypassPermissionsMode": "disable",4    "ask": [5      "Bash"6    ],7    "deny": [8      "WebSearch",9      "WebFetch"10    ]11  },12  "allowManagedPermissionRulesOnly": true,13  "allowManagedHooksOnly": true,14  "strictKnownMarketplaces": [],15  "sandbox": {16    "autoAllowBashIfSandboxed": false,17    "excludedCommands": [],18    "network": {19      "allowUnixSockets": [],20      "allowAllUnixSockets": false,21      "allowLocalBinding": false,22      "allowedDomains": [],23      "httpProxyPort": null,24      "socksProxyPort": null25    },26    "enableWeakerNestedSandbox": false27  }28}

26- id: sandbox27  name: '@deepseek-ai/dsh-sandbox-local'2829- id: sandbox-policy30  name: '@deepseek-ai/dsh-sandbox-policy'31  config:32    mode: !!js "process.env.DSH_PERMISSION_MODE ?? (process.env.DSH_SNAPSHOT === undefined ? 'workspace-write' : 'danger-full-access')"33    workspaceRoot: !!js process.cwd()