@menghuan1918/dsh-apollo 0.5.2 → 0.5.3

package/docs/DEVELOPMENT.md

@@ -2,7 +2,7 @@
 
 面向维护者、集成者和需要排查装配问题的用户。用户安装与配置请看 [README](../README.md)；本文保留 DSH 插件的实现细节、旧配置迁移、组合安装边界与验证方法。
 
-当前实现版本：`0.5.2`；npm 包名是 `@menghuan1918/dsh-apollo`。纯 ESM，无构建步骤；宿主浏览器半边是直接加载的闭包工厂。
+当前实现版本：`0.5.3`；npm 包名是 `@menghuan1918/dsh-apollo`。纯 ESM，无构建步骤；宿主浏览器半边是直接加载的闭包工厂。
 
 ## 目录
 
@@ -34,16 +34,15 @@
 | 依赖 | 版本 | 所有权 |
 |---|---|---|
 | `dsh-better-goal` | `0.2.0` | 目标域 |
-| `@menghuan1918/dsh-better-subagent` | `0.1.0` | 子代理 CLI/等待/child guard/分档/设置页 |
-| `dsh-better-compact` | `0.1.1` | 压缩 companion + engine + 设置页/诊断 |
+| `@menghuan1918/dsh-better-subagent` | `0.1.1` | 子代理 CLI/等待/child guard/分档/设置页 |
+| `dsh-better-compact` | `0.1.2` | 压缩 companion + engine + 设置页/诊断 |
 | `@deepseek-ai/schemastery` | `~3.18.4` | Apollo 行 Config |
 | `react` | peer | 宿主提供 |
 
-两个 0.1.0 版本在实现完成时尚未发布到 npm；验证使用本地 tarball：
+正式安装从 npm registry 获取上述精确版本，不需要本地 tarball 或 link：
 
 ```sh
 npm install
-npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/to/dsh-better-compact-0.1.0.tgz
 ```
 
 发布顺序必须是先两个子包、后 Apollo（见[发布](#实现入口打包与发布)）。
@@ -192,7 +191,7 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 1. 有 Loader 时等待装配完成（`loader.await()`，有界）；
 2. 等待 `legacyImport`（旧 eng.json）完成；
 3. 有界轮询 `settings.describe()`，直到 `dsh-better-subagent` 与 `dsh-better-compact` 两个命名空间都出现（默认 5s，50ms 间隔）；
-4. 子代理迁移 → 压缩迁移，各自写入后重读验证；
+4. 子代理迁移 → 恢复 Apollo job 开关 → 压缩迁移，各自写入后重读验证；
 5. 返回状态并记录日志（complete / pending / blocked / error）。
 
 若目标命名空间一直不可读/不可写（例如双显式 bundle 导致写入被拒），日志明确要求重载 profile，迁移保持幂等，下次启动会再试；不宣告成功。迁移不删除旧值，也不创建迁移 sidecar。
@@ -205,6 +204,8 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 
 **0.5.1 修复**：DSH 把 profile 覆盖行的 `name` 当 guard。旧 profile 若保留历史 `name: dsh-apollo`，Loader 会跳过该覆盖，`describe().value` 只剩默认值（例如用户显式 `subagents.eng: false` 会被看成默认 `true`）。迁移现在额外读取 `configEditor.configuration()` 中该行的 `override`，递归合并到有效配置之上：普通对象逐键合并，数组与所有标量（含 `false`/`0`/`""`/`[]`）整体覆盖。这样被跳过的显式值仍会迁移。`preset-eng` / `preset-eng-ptc` 的预设覆盖也按同样方式合并（`plugins` 数组整体替换），再读取原生 `compaction-basic`。
 
+历史 name guard 同样会让仍活跃的 Apollo job `exitGuard` 静默回退到默认 false。现在迁移还会只把这个开关经 `settings.update` 恢复到 Apollo，并重读验证；不会激活其他已弃用字段。宿主 `describe().user` 会投影被跳过的旧覆盖，因此优先检查活动 Apollo entry 的 raw config：它已声明 `exitGuard` 时（尤其当前 scoped 行显式 false），不覆盖。child 目标仍按自己的 `user.childExitGuard` 存在性判断，不让两个开关互相覆盖。旧 unscoped 行保留，重复执行不重写。仅在子代理迁移完成/无需写入后恢复 job 开关，避免新 scoped 行遮蔽尚未导入的旧来源；写入拒绝为 pending，重读不一致为 error，均纳入顶层状态。
+
 目标：`dsh-better-subagent` 的 `settings.describe()`：
 
 - `target.user` 的存在性表示显式值（含 false/0/""/[]）；
@@ -218,7 +219,7 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 | `tiers.fast` / `tiers.quality` | 同名 | 目标该档已有任一显式字段 → 整档不混写；否则来源档与目标默认不同才写 |
 | `subagents.eng` / `global` | 同名 | 目标缺字段且值不同才写；显式 false 是值 |
 | `subagents.codex/claude.*` | 同名 | 逐叶补齐：enabled、executable、profile（仅 codex）、permissionMode、defaultModel、models（含顺序/effort 元数据） |
-| `exitGuard` | `childExitGuard` | 只补目标缺失字段；Apollo 自己的 `exitGuard` 保留给 job 守卫 |
+| `exitGuard` | Apollo `exitGuard` + `childExitGuard` | 两份相同初值，随后独立配置；当前目标显式值（含 false）各自优先 |
 | `trustedHosts` | `trustedHosts` | 非 volatile；目标 raw config 未声明且来源非空时用 `configEditor.edit` 写 |
 
 写入：volatile 用 `settings.update(ns, patch, revision)`；非 volatile 用 target entry 的 `configEditor.edit`。`settings.update` 会触发 reconcile，可能替换目标 entry 对象，因此写 `trustedHosts` 前重新从 `entries()` 取目标 entry。写后重新 `describe()`/读 raw config 校验，任何字段不一致按 `error` 报告。
@@ -240,6 +241,10 @@ npm install --no-save /path/to/menghuan1918-dsh-better-subagent-0.1.0.tgz /path/
 
 原生默认值不会变成目标显式值：只有来源行里显式存在的键才会被携带。压缩配置是 volatile 保存、引擎载入时冻结快照；迁移后的设置需要重载 profile 才会被运行中引擎采用（inspect 的 `requiresReload` 可观察）。
 
+Apollo 在迁移挂载时先登记启动门禁：验证完成前，`agent/pre-step` 阻止任务步骤，`llm/stream` 同时阻止不经过 pre-step 的手动摘要调用。迁移 pending/blocked/error 不得按默认配置继续执行；应检查日志后修复来源或目标并重载。若本次迁移改变 compact 的载入快照，持久化验证完成后仍要求重载，重载后确认无差异才放行。普通后续设置保存不关闭已通过的启动门禁，仍按原有“当前快照继续、重载后应用新值”语义处理。
+
+宿主行明确 `disabled: true` 时，跳过该增强的迁移，不将其缺少 settings namespace 误判为全宿主故障；活动行缺失 namespace 仍报 pending。子代理增强被禁用时保留尚未迁出的旧来源，并暂缓会遮蔽该来源的旧 job 开关恢复，待重新启用后再迁移；已生效的 Apollo job 配置不变。停用 compact 增强时仍需按卸载说明启用原生 `compaction-basic`，以恢复 `/compact`；启动门禁不替用户改写禁用选择。
+
 ### 迁移测试
 
 - [tests/migrate.test.mjs](../tests/migrate.test.mjs)：纯函数与 fake host 编排。覆盖显式 false/空值、目标优先（分档整档、models 空列表、保留方式二选一）、缺失来源、ambiguity、trustedHosts、写入拒绝、幂等、重读验证、有界等待。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@menghuan1918/dsh-apollo",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "DSH plugin bundle: workflow skills, engineering presets, independent better-goal / better-subagent / better-compact integration, and a minimal job exit guard. Pure ESM, no build step.",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "~3.18.4",
-    "@menghuan1918/dsh-better-subagent": "0.1.0",
-    "dsh-better-compact": "0.1.1",
+    "@menghuan1918/dsh-better-subagent": "0.1.1",
+    "dsh-better-compact": "0.1.2",
     "dsh-better-goal": "0.2.0"
   },
   "peerDependencies": {

package/src/admission.js

@@ -0,0 +1,36 @@
+import { isDeepStrictEqual } from 'node:util'
+
+/** Do not run a turn or manual summary using pre-migration defaults. */
+export function mountMigrationAdmission(ctx) {
+  let report = { status: 'pending' }
+  let requiresReload = false
+  const assertReady = () => {
+    if (report.status !== 'complete') {
+      const detail = report.error ?? report.compact?.error ?? report.compact?.reason ?? report.subagent?.error
+      const error = new Error('Apollo 配置迁移尚未完成（' + report.status + '）。请检查迁移诊断，修复配置后重载 profile。' + (detail ? ' ' + detail : ''))
+      error.code = 'APOLLO_MIGRATION_PENDING'
+      throw error
+    }
+    if (requiresReload) {
+      const error = new Error('Apollo 已迁移压缩配置，但当前引擎仍使用旧快照。请重载 profile 后继续；刷新网页不会应用压缩配置。')
+      error.code = 'APOLLO_MIGRATION_RELOAD_REQUIRED'
+      throw error
+    }
+  }
+  ctx.on('agent/pre-step', (_payload, next) => {
+    assertReady()
+    return next()
+  }, { prepend: true })
+  // Manual /compact does not enter pre-step. Guard its provider boundary too,
+  // without replacing the compaction service or changing any request messages.
+  ctx.on('llm/stream', async function* (_options, next) {
+    assertReady()
+    yield* next()
+  }, { prepend: true })
+  return (result) => {
+    report = result
+    const compact = ctx.get?.('betterCompactConfig')
+    requiresReload = result.status === 'complete' && result.compact?.fields?.length > 0
+      && compact !== undefined && !isDeepStrictEqual(compact.snapshot(), compact.current())
+  }
+}

package/src/index.js

@@ -14,6 +14,7 @@ import { readFile, readdir } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { mountMigration } from './migrate.js'
+import { mountMigrationAdmission } from './admission.js'
 import { mountSettings } from './settings.js'
 export { Config } from './config.js'
 
@@ -33,8 +34,9 @@ export const inject = ['skills']
 export function apply(ctx, config) {
   ctx.skills.registerProvider(() => createProvider(ctx))
   if (typeof ctx.inject === 'function') {
+    const onResult = typeof ctx.on === 'function' ? mountMigrationAdmission(ctx) : undefined
     const settings = mountSettings(ctx, config)
-    mountMigration(ctx, config, { legacyImport: settings.legacyImport })
+    mountMigration(ctx, config, { legacyImport: settings.legacyImport, onResult })
   }
 }
 

package/src/migrate.js

@@ -7,8 +7,8 @@
  *
  *   - `apollo-skills` 的 `tiers.fast/quality`、`subagents.{eng,global}`、
  *     `subagents.{codex,claude}.*`、`trustedHosts` → `dsh-better-subagent`
- *     相同路径；`exitGuard` → `childExitGuard`。旧 `exitGuard` 仍留在 Apollo
- *     作为 job/通用守卫开关，不被删除。
+ *     相同路径；`exitGuard` → `childExitGuard`。旧 `exitGuard` 同时保留/恢复到
+ *     Apollo 作为 job 守卫开关；两边目标显式配置（含 false）各自优先。
  *   - 旧 `eng` / `eng-ptc` 预设里原生 `compaction-basic` 的显式配置 →
  *     `dsh-better-compact` 同名原生键；目标缺失的 `mode` 采用默认 `goal`。
  *
@@ -524,6 +524,28 @@ export async function migrateSubagent({ settings, configEditor, descriptors, sou
   return { status: 'complete', fields }
 }
 
+/** Restore only the job switch lost to a historical Apollo name guard. */
+async function migrateJobExitGuard({ settings, descriptors, source, rawSource }) {
+  const target = descriptors.find((row) => row?.ns === APOLLO_NS)
+  // user also projects skipped overrides, so the active raw config is the
+  // authority for an already configured job switch (including explicit false).
+  if (hasOwn(rawSource, 'exitGuard')
+    || (hasOwn(target?.user, 'exitGuard') && target.user.exitGuard !== source.exitGuard)
+    || target?.value?.exitGuard === source.exitGuard) {
+    return { status: 'no-change' }
+  }
+  if (target === undefined) return { status: 'pending', error: 'Apollo namespace is not readable' }
+  try {
+    await settings.update(APOLLO_NS, { exitGuard: source.exitGuard }, target.revision)
+  } catch (error) {
+    return { status: 'pending', error: errorMessage(error) }
+  }
+  const after = (await settings.describe()).find((row) => row?.ns === APOLLO_NS)
+  return after?.value?.exitGuard === source.exitGuard
+    ? { status: 'complete' }
+    : { status: 'error', error: 'unverified: exitGuard' }
+}
+
 /**
  * Apply the compaction migration.
  *
@@ -570,7 +592,8 @@ function errorMessage(error) {
  * Run the one-time (idempotent) migration.
  *
  * Order: Loader settlement → legacy `eng.json` import → bounded wait for both
- * target namespaces → subagent plan/write/verify → compact plan/write/verify.
+ * target namespaces → subagent plan/write/verify → job switch recovery →
+ * compact plan/write/verify.
  * A missing target namespace yields `pending`; errors are reported, never
  * silently claimed as success, and no source value is deleted.
  *
@@ -588,7 +611,12 @@ export async function runMigration(ctx, options = {}) {
   const loader = loaderOf(ctx)
   if (loader !== undefined) await bounded(Promise.resolve(loader.await()).catch(() => undefined), timeoutMs)
   if (options.legacyImport !== undefined) await bounded(options.legacyImport, timeoutMs)
-  const descriptors = await waitForDescriptors(settings, [SUBAGENT_NS, COMPACT_NS], {
+  const configEditor = options.configEditor ?? serviceOf(ctx, 'configEditor')
+  // A deliberately disabled row is not an unloaded/failed active plugin. Keep
+  // its legacy source intact for a later re-enable instead of blocking native work.
+  const disabled = new Set([SUBAGENT_NS, COMPACT_NS].filter((ns) => targetEntryOf(configEditor, ns)?.options?.disabled === true))
+  const targets = [SUBAGENT_NS, COMPACT_NS].filter((ns) => !disabled.has(ns))
+  const descriptors = await waitForDescriptors(settings, targets, {
     timeoutMs,
     intervalMs: options.intervalMs,
   })
@@ -599,7 +627,6 @@ export async function runMigration(ctx, options = {}) {
     return { status: 'pending', error: message }
   }
   const sourceDescriptor = descriptors.find((row) => row?.ns === APOLLO_NS)
-  const configEditor = options.configEditor ?? serviceOf(ctx, 'configEditor')
   const agentPresets = options.agentPresets ?? serviceOf(ctx, 'agentPresets')
   // describe().value only projects the *volatile* form, so read the Apollo
   // row's raw config for non-volatile fields (trustedHosts) and overlay the
@@ -617,23 +644,34 @@ export async function runMigration(ctx, options = {}) {
     effectiveSource,
     configurationOverrideOf(configEditor, APOLLO_NS),
   ))
-  const subagent = await migrateSubagent({ settings, configEditor, descriptors, source, log })
-  const compact = await migrateCompact({ settings, configEditor, descriptors, agentPresets, log })
-  const status = [subagent.status, compact.status].some((value) => value === 'error')
+  const subagent = disabled.has(SUBAGENT_NS)
+    ? { status: 'disabled', fields: [] }
+    : await migrateSubagent({ settings, configEditor, descriptors, source, log })
+  // A scoped job write would become the last override and hide the skipped
+  // source from configuration().override. Wait until its child fields are safe.
+  const job = subagent.status === 'disabled'
+    ? { status: 'deferred', reason: 'subagent is disabled; preserve the legacy source until it is re-enabled' }
+    : ['complete', 'no-change'].includes(subagent.status)
+      ? await migrateJobExitGuard({ settings, descriptors, source, rawSource })
+      : { status: 'pending', error: 'waiting for the subagent migration before restoring the job switch' }
+  const compact = disabled.has(COMPACT_NS)
+    ? { status: 'disabled', fields: [] }
+    : await migrateCompact({ settings, configEditor, descriptors, agentPresets, log })
+  const status = [job.status, subagent.status, compact.status].some((value) => value === 'error')
     ? 'error'
-    : [subagent.status, compact.status].some((value) => value === 'pending')
+    : [job.status, subagent.status, compact.status].some((value) => value === 'pending')
       ? 'pending'
       : ['ambiguous', 'invalid', 'source-missing'].includes(compact.status) ? 'blocked'
         : 'complete'
-  for (const [name, section] of [['subagent', subagent], ['compact', compact]]) {
+  for (const [name, section] of [['job', job], ['subagent', subagent], ['compact', compact]]) {
     if (section.error !== undefined) {
       log?.warn?.(`apollo-migration: ${name} is ${section.status}: ${section.error}`)
     }
   }
   log?.[status === 'complete' ? 'info' : 'warn']?.(
-    `apollo-migration: ${status} (subagent=${subagent.status}, compact=${compact.status})`,
+    `apollo-migration: ${status} (job=${job.status}, subagent=${subagent.status}, compact=${compact.status})`,
   )
-  return { status, source: sourceDescriptor === undefined ? 'apply-config' : 'settings', subagent, compact }
+  return { status, source: sourceDescriptor === undefined ? 'apply-config' : 'settings', job, subagent, compact }
 }
 
 /**
@@ -641,7 +679,8 @@ export async function runMigration(ctx, options = {}) {
  *
  * @param ctx - plugin context.
  * @param config - Apollo row config (fallback source when describe() is not ready).
- * @param options - `{ legacyImport, env, timeoutMs, intervalMs }`.
+ * @param options - `{ legacyImport, env, timeoutMs, intervalMs, onResult }`.
+ *   `onResult` receives the settled report without blocking the Loader callback.
  */
 export function mountMigration(ctx, config, options = {}) {
   let started = false
@@ -656,7 +695,8 @@ export function mountMigration(ctx, config, options = {}) {
       log: settingsCtx.logger ?? ctx.logger,
     }).catch((error) => {
       settingsCtx.logger?.warn?.(`apollo-migration: skipped: ${errorMessage(error)}`)
-    })
+      return { status: 'error', error: errorMessage(error) }
+    }).then((result) => options.onResult?.(result))
   }
   ctx.inject(['settings'], start)
 }