dsh-plugin-maoxuan-pet 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 0.2.3 — 2026-11-01
+
+首次安装修复：模型配置自动从宿主 profile 桥接进 headless 子进程，新装机基本零配置。
+
+### 修复
+- **新装机必踩的 `MISSING_CREDENTIAL`**：插件每小时调用 `dsh --profile headless` 生成气泡，而随包 `headless` profile 是一个没有任何模型配置的空壳——官方 DeepSeek、中转线路的用户第一次安装都会生成失败，只能看到「离线摘录 + 报错」。
+- 现在**每次生成前自动把宿主 profile patch 里的 llm 条目**（`agent-default-model`、`dsh-llm-pi-ai`、`dsh-llm-deepseek-api-key`）**原样搬到** `$DSH_HOME/storages/dsh-maoxuan-pet.headless-overlay.yml`，并以 `dsh --profile headless --patch <overlay>` 启动子进程：宿主 GUI 能用什么模型（官方 / wocheng 之类任意中转），气泡子进程就能用什么，官方与中转线路零配置可用。
+- 待机行为：宿主 patch 没有 llm 条目（如机器确实没配过模型）时不写 overlay，`MISSING_CREDENTIAL` 报错会转成一句可操作的中文指引（保留原始错误摘要）写入 `state.lastError`；`dsh` 找不到（ENOENT）同样给出指引，其他报错原样透传。
+- overlay 内容变化才落盘（tmp + rename 原子写）；文件可随时手动删除，插件每次生成都会重写。子进程 llm 桥接失败不影响正常降级。
+
+### 升级行为
+- `profile` 配置默认仍是 `headless`。显式改 `profile` / `dshBin` 的老配置完全不受影响（此时不做桥接桥外干扰，`--patch` 只在 overlay 存在时追加）。
+- 新增并导出纯函数 `headlessOverlayPath` / `hostPatchPath` / `extractLlmPatchEntries` / `syncHeadlessOverlay` / `friendlyHeadlessError`；`verify/contract.mjs` 增加 llm 抽取与友好报错用例（40 断言全绿）。
+
 ## 0.2.2 — 2026-11-01
 
 展示层维护版：README 从技术说明改成安装页，npm 页面的介绍随之更新。

package/README.en.md

@@ -55,7 +55,8 @@ fan-made character; not affiliated with DeepSeek.
     maxBubbles: 40
     headless: true          # false = only local excerpts, zero model calls
     dshBin: dsh
-    profile: headless
+    profile: headless       # since v0.2.3 the host GUI's model config is
+                            # bridged in automatically (official/relay, no setup)
     timeoutMs: 180000
     businessContext: "40, indie developer, small-tool SaaS"
 ```

package/README.md

@@ -51,7 +51,8 @@ dsh plugin --profile web add dsh-plugin-maoxuan-pet
     maxBubbles: 40
     headless: true          # false = 只用本地摘录，不花模型调用
     dshBin: dsh
-    profile: headless
+    profile: headless       # v0.2.3 起会自动把宿主 GUI 的模型配置桥接进来
+                            # （官方/中转线路通用，无需手动配置）
     timeoutMs: 180000
     businessContext: |-
       用户是一位正在创业的独立开发者……

package/cordis.patch.yml

@@ -16,7 +16,8 @@
         quietHours: [2, 8]
         maxBubbles: 40
         headless: true
-        profile: headless
+        # 不写死 profile：插件默认跟随宿主的 DSH_PROFILE（宿主能用什么模型，
+        # 子进程就能用什么模型）。想强制某个 profile 再显式写 profile: xxx。
         timeoutMs: 180000
         businessContext: |-
           用户是一位正在创业的独立开发者/小团队创始人，关心客户获取、现金流、

package/docs/RELEASE.md

@@ -8,7 +8,7 @@
 | 项 | 现状（2026-11-01 核对） |
 |---|---|
 | 包名 | `dsh-plugin-maoxuan-pet`（unscoped，npm 上未占用） |
-| 版本 | `0.2.2` |
+| 版本 | `0.2.3` |
 | 代码许可 | MIT（`LICENSE`）；语料与立绘的非 MIT 声明见 `NOTICE` |
 | 打包清单 | `npm pack --dry-run` → 59 files / 1.26 MB（含 33 篇语料；0.2.1 起立绘降到 256×539，包体从 4.2 MB 降下来） |
 | GitHub 账号 | `gh auth status` → `yuna78`（scopes 含 `repo`） |
@@ -93,7 +93,7 @@ cd .. && node build-registry.mjs --write    # 重算 registry.json / README 表
 node -e "const r=require('./registry.json');console.log(r.plugins.find(p=>p.name==='dsh-plugin-maoxuan-pet'))"
 ```
 
-期望字段：`openSource: true`、`npm: "0.2.2"`、`market: { title: "yuna78/dsh-maoxuan-pet", version: "0.2.2" }`。
+期望字段：`openSource: true`、`npm: "0.2.3"`、`market: { title: "yuna78/dsh-maoxuan-pet", version: "0.2.3" }`。
 
 ## 5. 版本号规则
 

package/index.js

@@ -16,6 +16,7 @@
  * node_modules without resolving any DSH-internal module.
  */
 import { readFile, writeFile, rename, mkdir, stat } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -79,6 +80,11 @@ export function normaliseConfig(config) {
     dailyLimit: int(raw.dailyLimit, 24, 0, 500),
     headless: raw.headless !== false,
     dshBin: typeof raw.dshBin === 'string' && raw.dshBin.trim() ? raw.dshBin.trim() : 'dsh',
+    // The child keeps the dedicated one-shot `headless` profile (its app is the
+    // only one that accepts `--json`); the *model* config is bridged from the
+    // host profile at spawn time via a `--patch` overlay, so anything the GUI
+    // can use — DeepSeek official, a relay, any provider — works with zero
+    // per-machine setup. See syncHeadlessOverlay / extractLlmPatchEntries.
     profile: typeof raw.profile === 'string' && raw.profile.trim() ? raw.profile.trim() : 'headless',
     timeoutMs: int(raw.timeoutMs, 180000, 10000, 900000),
     businessContext: typeof raw.businessContext === 'string' ? raw.businessContext.trim() : '',
@@ -86,6 +92,144 @@ export function normaliseConfig(config) {
   };
 }
 
+/** Translate a raw child-process failure into something a user can act on. */
+export function friendlyHeadlessError(message) {
+  if (/MISSING_CREDENTIAL/i.test(message)) {
+    return `${clip(message, 160)}——修复：打开 Web 界面的 Models 页保存一个可用模型的 API Key（插件默认跟随宿主 profile，宿主能用它就能用）；或在插件配置里显式指定 profile / dshBin。`;
+  }
+  if (/无法启动 headless|ENOENT/.test(message)) {
+    return `${clip(message, 160)}——多数是 PATH 里没有 dsh 命令，可在插件配置里把 dshBin 指到 dsh 的绝对路径。`;
+  }
+  return message;
+}
+
+// --- host-profile → headless child: llm config bridge (v0.2.3) ---------------
+// The hourly child runs `dsh --profile headless`, whose bundled patch carries no
+// llm provider — so on a fresh install it always died with MISSING_CREDENTIAL
+// unless the user happened to export a global DEEPSEEK_API_KEY. The host
+// process *does* have a working model stack (that is what the GUI renders with):
+// its profile patch declares `agent-default-model` and the provider plugins.
+// These two files are plain YAML; bridging is a verbatim copy of the llm
+// entries into a `--patch` overlay handed to the child at spawn time.
+
+/** The overlay file handed to every headless child (idempotent, human-inspectable). */
+export function headlessOverlayPath(env = process.env) {
+  return join(resolveDshHome(env), 'storages', 'dsh-maoxuan-pet.headless-overlay.yml');
+}
+
+/** Where the host profile's own patch layer lives, or null if unknown. */
+export function hostPatchPath(env = process.env) {
+  const dir = env.DSH_PROFILE_DIR?.trim();
+  if (dir) return join(dir, 'cordis.patch.yml');
+  const home = resolveDshHome(env);
+  const profile = env.DSH_PROFILE?.trim();
+  if (profile) return join(home, 'profiles', profile, 'cordis.patch.yml');
+  return null;
+}
+
+/**
+ * Copy the llm-related top-level entries out of a profile patch, verbatim.
+ * Only Node builtins are allowed in this package, so "parsing" is slicing the
+ * top-level `- ` blocks by column-0 boundary lines; profile patches are
+ * machine-written simple YAML, and the output is applied by dsh itself, exactly
+ * like the original layer. Anything not matching is left out untouched.
+ */
+export function extractLlmPatchEntries(patchText) {
+  const lines = String(patchText ?? '').split('\n');
+  const starts = [];
+  lines.forEach((line, index) => {
+    if (/^- /.test(line)) starts.push(index);
+  });
+  return starts
+    .map((start, i) => lines.slice(start, starts[i + 1] ?? lines.length).join('\n').replace(/\s+$/, ''))
+    .filter((block) => /- id: agent-default-model\b/.test(block)
+      || /^\s*name:\s+["']?@deepseek-ai\/dsh-llm-pi-ai["']?\s*$/m.test(block)
+      || /^\s*name:\s+["']?@deepseek-ai\/dsh-llm-deepseek-api-key["']?\s*$/m.test(block));
+}
+
+/**
+ * Write the overlay if its content changed; return the path, or '' when the
+ * host patch had no llm entries (then an existing overlay is kept — a stale
+ * bridge still beats a child with no model config at all).
+ */
+export async function syncHeadlessOverlay(env = process.env) {
+  const target = headlessOverlayPath(env);
+  let text = '';
+  const source = hostPatchPath(env);
+  if (source) {
+    try {
+      const entries = extractLlmPatchEntries(await readFile(source, 'utf8'));
+      if (entries.length) {
+        text = [
+          '# Auto-generated by dsh-plugin-maoxuan-pet (v0.2.3).',
+          '# The host profile\'s llm entries, bridged verbatim so the hourly',
+          '# headless child uses the same model stack as the GUI. Safe to delete:',
+          '# the plugin rewrites it on every generation attempt.',
+          ...entries,
+          '',
+        ].join('\n');
+      }
+    } catch { /* unreadable host patch → no bridge this run */ }
+  }
+  let existing = '';
+  try { existing = await readFile(target, 'utf8'); } catch { /* absent */ }
+  if (existing === text) return text ? target : '';
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp`;
+  await writeFile(tmp, text, 'utf8');
+  await rename(tmp, target);
+  return text ? target : '';
+}
+
+/**
+ * Read the machine-local credential refs file the web Models page writes
+ * (`$DSH_HOME/.credentials.yaml`, only the top-level `refs:` block; the file
+ * belongs to the user and is remounted by the harness anyway). Returns a map
+ * name → value, {} when absent/unreadable — callers treat any error as
+ * "no bridge" and fall back to the honest offline excerpt.
+ */
+export function readCredentialRefs(env = process.env) {
+  try {
+    const file = join(resolveDshHome(env), '.credentials.yaml');
+    const text = readFileSync(file, 'utf8');
+    const refs = {};
+    let inRefs = false;
+    for (const line of text.split('\n')) {
+      if (/^refs:/.test(line)) { inRefs = true; continue; }
+      if (inRefs && /^[A-Za-z0-9_]+:/.test(line)) break; // next top-level block
+      const match = inRefs && /^  ([A-Za-z0-9_]+): (.+)$/.exec(line);
+      if (match) refs[match[1]] = match[2].trim();
+    }
+    return refs;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The child env for one generation: the host env plus every `apiKeyEnv` the
+ * bridged overlay names but the child env does not have, sourced from the
+ * credential refs (the same store the GUI reads). Injecting only missing names
+ * keeps explicit user-provided env values authoritative; anything unknown is
+ * simply not injected, so the child fails with the honest MISSING_CREDENTIAL.
+ */
+export function childHeadlessEnv(overlayText, childEnv = process.env) {
+  const env = { ...childEnv, DSH_MAOXUAN_PET_CHILD: '1' };
+  const names = new Set(
+    (String(overlayText ?? '').match(/^\s*apiKeyEnv:\s*([A-Za-z0-9_]+)\s*$/gm) ?? [])
+      .map((line) => /^ apiKeyEnv:/.test(line) ? line.trim().replace(/^apiKeyEnv:\s*/, '') : line.replace(/^\s*apiKeyEnv:\s*/, '').trim())
+      .map((name) => name.trim()),
+  );
+  if (!names.size) return env;
+  const refs = readCredentialRefs(childEnv);
+  for (const name of names) {
+    if (env[name]) continue;
+    const value = refs[name];
+    if (value) env[name] = value;
+  }
+  return env;
+}
+
 /** Resolve DSH home the same way the harness does. */
 export function resolveDshHome(env = process.env) {
   if (env.DSH_HOME && env.DSH_HOME.trim()) return env.DSH_HOME.trim();
@@ -668,13 +812,24 @@ export function apply(ctx, config) {
   };
 
   /** Run one headless dsh conversation and return the final text, or throw. */
-  const runHeadless = (prompt) => new Promise((resolvePromise, reject) => {
-    const args = ['--profile', cfg.profile, '--json', prompt];
+  const runHeadless = (prompt) => new Promise(async (resolvePromise, reject) => {
+    // Bridge the host profile's llm config into the one-shot child (idempotent;
+    // '' when nothing to bridge — see syncHeadlessOverlay). Must not kill the
+    // generation if it fails for any reason: worst case the child errors with
+    // the old MISSING_CREDENTIAL and the usual offline fallback kicks in.
+    await syncHeadlessOverlay().catch(() => '');
+    let overlayText = '';
+    try {
+      overlayText = await readFile(headlessOverlayPath(), 'utf8');
+    } catch { /* no overlay available this run */ }
+    const args = ['--profile', cfg.profile];
+    if (overlayText.trim()) args.push('--patch', headlessOverlayPath());
+    args.push('--json', prompt);
     let proc;
     try {
       proc = spawn(cfg.dshBin, args, {
         cwd: homedir(),
-        env: { ...process.env, DSH_MAOXUAN_PET_CHILD: '1' },
+        env: childHeadlessEnv(overlayText),
         stdio: ['ignore', 'pipe', 'pipe'],
       });
     } catch (error) {
@@ -810,7 +965,7 @@ export function apply(ctx, config) {
           if (generated) produced = { mode: 'headless', ...generated };
           else failure = `模型输出无法解析为约定 JSON（${clip(answer, 120)}）`;
         } catch (error) {
-          failure = String(error?.message ?? error);
+          failure = friendlyHeadlessError(String(error?.message ?? error));
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-maoxuan-pet",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "DSH 悬浮宠物「鲸鱼娘·小毛」：每小时读一篇毛选，给创业中的你说一句能动手的督促；内置毛选公开语料与 maoxuan-pet preset。",
   "keywords": [
     "dsh",