@kira905/dsh-diagnostics-extra 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,33 @@
 # dsh-diagnostics-extra · DSH 诊断与对账小工具
 
+> **本仓是命令行工具，不挂宿主界面，不需要 `dsh.bundle`、不需要写 `cordis.patch.yml`。** 装它 = `npm i -g @kira905/dsh-diagnostics-extra`（或 `npx -p @kira905/dsh-diagnostics-extra dsh-why`）。装进 profile 也对，但那条 `declares no dsh.bundle` 警告是**正常现象**，不是故障。
+
+## 装完自检（三条只读验法）
+
+`<profile>` 换成你实际用的 profile（默认 `web`），`<数据根>` 换成你的 DSH 数据根（默认 `~/.dsh`）。
+
+```powershell
+# ① 组合树里有没有它（只读、约 0.6 秒、不启服务）
+dsh --profile <profile> --dump-config | Select-String "dsh-diagnostics-extra"
+# 期望：bundle 层出现一行 "# == <登记名>"、insert 层出现 "- id: <entry>"（问的都是「它挂上没」）；
+#       本仓包名 @kira905/dsh-diagnostics-extra —— 带 scope 装的写带 scope 名、老工装 / 手写的可能是裸名，两种都搜一遍
+#       ⚠️ 若该包会 insert 一行，还要数一遍"同一个 id 出现了几次"，必须 == 1
+
+# ② 组合列表里有没有它（只读）
+Get-Content <数据根>/profiles/<profile>/package.json | Select-String "@kira905/dsh-diagnostics-extra"
+# 期望：dependencies 与 dsh.profile.bundles 两处都有（CLI 类只需要 dependencies；bundles 里也可能写裸名 dsh-diagnostics-extra）
+
+# ③ 命令在不在 —— 【只查存在，不执行】
+Test-Path <数据根>/profiles/<profile>/node_modules/.bin/dsh-why.CMD   # 装进 profile 的
+Test-Path "$env:APPDATA\npm\dsh-why.CMD"                           # npm i -g 装的
+# 期望：True。两条路径按你实际用的装法挑一条
+```
+
+> 探针只做存在性检查（只看命令文件在不在，不执行任何命令）。
+> 要不要用 `--help` 验，见本仓当前说明与该命令的参数表。
+
+---
+
 > DeepSeek Harness（DSH）生态里**出问题时真正会去跑**的几件只读诊断工具：
 > **图片附件对账 / 取回**（从别的机器同步来的含图会话为什么一续聊就报 TRANSPORT）、
 > **一条命令答清「现在哪台机在跑、dsh 与守护鱼何时起、3080 端口连了谁」**、
@@ -11,13 +39,13 @@
 
 ## ⚠️ 先读这段（比任何用法都重要）
 
-1. **四件里有一件的未知参数会被静默忽略、然后直接执行真动作** ——
-   `owner-todo-scan.mjs`：它用「参数是否出现」判断开关，**没有** `--help`。
-   敲一个不认识的参数不会被拦，加 `--write` 时**会直接重写 `docs\待你操作-<设备>.md`**。
-   ⇒ 对这件**先读脚本头部注释（前 25 行）**，或者照本文件的逐件表抄参数。
-2. **另外三件是安全的**：`attachments-audit.mjs` / `attachments-fetch.mjs` / `dsh-why.mjs`
-   都实现了 `-h` 与帮助输出，**未知参数会报错并停在用法提示**（不会执行真动作）。
-   但本文件仍不在代码块里给帮助示例 —— 四件的参数写法差异大，照抄逐件表最稳。
+1. **`owner-todo-scan.mjs` 自 2026-10-30 起已支持 `--help`（打印用法、退出码 0）与未知参数拒收
+   （退出码 2，绝不继续执行）** —— 敲错参数会被拦下，不会带着 `--write` 去重写清单。
+   用法文本里写明了它唯一的写动作：`--write` 会**整体重写 `docs\待你操作-<设备>.md`**。
+   ⇒ 拿不准就先 `--help`，或先读脚本头部注释。
+2. **另外三件**：`attachments-audit.mjs` / `attachments-fetch.mjs` / `dsh-why.mjs`
+   也都实现了 `-h` 与帮助输出，**未知参数会报错并停在用法提示**（不会执行真动作）。
+   本文件仍不在代码块里给帮助示例 —— 四件的参数写法差异大，照抄逐件表最稳。
 3. **写动作只有两处**：`attachments-fetch.mjs` 的取回落盘（可 `--dry-run` 预演、`--report` 留报告、`--rollback` 回退）
    与 `owner-todo-scan.mjs --write` 的清单刷新（整体重写）。其余全部只读。
 4. 本仓工具**不做任何网络请求、不读凭据文件**。它们只读本机 DSH 数据根与 docs 树。

package/lib/cli-args.mjs

@@ -0,0 +1,183 @@
+// cli-args.mjs —— 用户 CLI 公共参数件（零依赖）
+//
+// 三条纪律（本仓所有 bin 共用）：
+//   1. `-h` / `--help` ⇒ 打印用法、退出码 0，**绝不执行动作**；
+//   2. 出现不认识的参数 ⇒ 打印错误、退出码 2，**绝不继续执行**；
+//   3. 用法文本必须写清「这个命令会写什么」，用户得知道有没有副作用。
+//
+// 接入方式（bin 顶部）：
+//   import { cliGuard } from '../lib/cli-args.mjs';
+//   const argv = cliGuard(spec);            // 默认取 process.argv.slice(2)
+//
+// spec 字段（都可选，但 summary / usage / writes / exits 建议必填）：
+//   cmd, summary, usage,
+//   commands: [{ name, desc }],
+//   flags:    [{ name, alias: ['-x'], arg: 'N', desc }],
+//   positional: [{ name, desc }],
+//   env:      [{ name, desc }],
+//   writes, dryRun, exits, examples: [], notes: []
+
+import fs from 'node:fs';
+
+export const EXIT_USAGE = 2;
+
+// 同步写 fd：`process.stdout` 在管道下是异步流，若随后同步 process.exit() 会把内容截断；
+// 而 `--help` 必须「打印完立刻退出、后面一行都不许跑」⇒ 一律用 writeSync 写原始字节。
+function writeSyncFd(fd, text) {
+  try { fs.writeSync(fd, text); } catch { (fd === 1 ? process.stdout : process.stderr).write(text); }
+}
+
+/** 取 token 的「参数名」部分：`--hours=6` → `--hours`；非 `-` 开头返回 null */
+function tokenName(a) {
+  if (typeof a !== 'string' || !a.startsWith('-')) return null;
+  const eq = a.indexOf('=');
+  return eq > 0 ? a.slice(0, eq) : a;
+}
+
+const dashless = (n) => n.replace(/^-+/, '');
+
+function knownSet(spec) {
+  const s = new Set(['-h', '--help']);
+  for (const f of spec.flags ?? []) {
+    if (f.name) s.add(f.name);
+    for (const a of f.alias ?? []) s.add(a);
+  }
+  return s;
+}
+
+function valueSet(spec) {
+  const s = new Set();
+  for (const f of spec.flags ?? []) {
+    if (!f.arg) continue;
+    if (f.name) s.add(f.name);
+    for (const a of f.alias ?? []) s.add(a);
+  }
+  return s;
+}
+
+/** 识别帮助：`hasFlag(argv, '-h', '--help')` */
+export function hasFlag(argv, ...names) {
+  for (const a of argv ?? []) {
+    const n = tokenName(a);
+    if (n !== null && names.includes(n)) return true;
+  }
+  return false;
+}
+
+/** 渲染用法文本（纯函数，便于测试） */
+export function renderHelp(spec = {}) {
+  const L = [];
+  L.push('用法');
+  L.push(`  ${spec.usage ?? spec.cmd ?? '<命令>'}`);
+
+  if (spec.summary) L.push('', spec.summary);
+
+  if (spec.commands?.length) {
+    L.push('', '子命令');
+    for (const c of spec.commands) L.push(`  ${c.name}    ${c.desc}`);
+  }
+
+  L.push('', '选项');
+  for (const f of spec.flags ?? []) {
+    const head = [f.name, ...(f.alias ?? [])].join(', ') + (f.arg ? ` <${f.arg}>` : '');
+    L.push(`  ${head}`);
+    if (f.desc) L.push(`      ${f.desc}`);
+  }
+  L.push('  -h, --help');
+  L.push('      打印本用法并退出（退出码 0），不执行任何动作');
+
+  if (spec.positional?.length) {
+    L.push('', '位置参数');
+    for (const p of spec.positional) L.push(`  ${p.name}`);
+    for (const p of spec.positional) if (p.desc) L.push(`      ${p.name}    ${p.desc}`);
+  }
+
+  if (spec.writes) L.push('', '写什么', `  ${spec.writes}`);
+  if (spec.dryRun) L.push('', '干跑', `  ${spec.dryRun}`);
+  if (spec.env?.length) {
+    L.push('', '环境变量');
+    for (const e of spec.env) L.push(`  ${e.name}    ${e.desc ?? ''}`);
+  }
+  if (spec.exits) L.push('', '退出码', `  ${spec.exits}`);
+  if (spec.examples?.length) {
+    L.push('', '示例');
+    for (const e of spec.examples) L.push(`  ${e}`);
+  }
+  if (spec.notes?.length) {
+    L.push('', '注意');
+    for (const n of spec.notes) L.push(`  ${n}`);
+  }
+  return L.join('\n') + '\n';
+}
+
+/** 打印用法并按需以指定码退出（默认 rc=0）：同步写 + 同步退出，保证后续代码一行都不跑 */
+export function printHelp(spec = {}, { exit = true, exitCode = 0 } = {}) {
+  const text = renderHelp(spec);
+  if (!exit) { process.stdout.write(text); return text; }
+  writeSyncFd(1, text);
+  process.exit(exitCode);
+  return text;
+}
+
+/** 未知参数：打印错误并 rc=2 退出（同步写 + 同步退出，绝不继续执行） */
+export function usageError(spec = {}, arg) {
+  const cmd = spec.cmd ? `${spec.cmd} --help` : '--help';
+  writeSyncFd(2, `错误：不认识的参数 ${arg}\n（运行 \`${cmd}\` 看用法）\n`);
+  process.exit(EXIT_USAGE);
+}
+
+/** 列出 argv 里不认识的参数（不含数值形如 -1 的取值、不含 `--` 之后的内容） */
+export function findUnknown(argv = [], spec = {}) {
+  const known = knownSet(spec);
+  const out = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--') break;
+    if (/^-\d/.test(a)) continue; // 负数取值，不是参数名
+    const n = tokenName(a);
+    if (n === null) continue;
+    if (!known.has(n)) out.push(a);
+  }
+  return out;
+}
+
+/**
+ * 解析参数。遇到不认识的参数 ⇒ 打印错误 + rc=2 退出（绝不继续执行）。
+ * 返回 `{ flags, positional }`；`--x=1` 与 `--x 1` 都归一成 `flags.x`。
+ */
+export function parseArgs(argv = [], spec = {}) {
+  const known = knownSet(spec);
+  const valued = valueSet(spec);
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--') { positional.push(...argv.slice(i + 1)); break; }
+    if (/^-\d/.test(a)) { positional.push(a); continue; }
+    const n = tokenName(a);
+    if (n === null) { positional.push(a); continue; }
+    if (!known.has(n)) usageError(spec, a);
+    const key = dashless(n);
+    const eq = a.indexOf('=');
+    if (eq > 0) { flags[key] = a.slice(eq + 1); continue; }
+    const next = argv[i + 1];
+    if (valued.has(n) && next !== undefined && tokenName(next) === null) {
+      flags[key] = next;
+      i += 1;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return { flags, positional };
+}
+
+/**
+ * 一道闸：先认 `-h/--help`，再拦未知参数，通过则把 argv 原样交回。
+ * 用法（改动最小的接法）：`const argv = cliGuard(SPEC, process.argv.slice(2));`
+ */
+export function cliGuard(spec = {}, argv = process.argv.slice(2)) {
+  if (hasFlag(argv, '-h', '--help')) printHelp(spec);
+  const unknown = findUnknown(argv, spec);
+  if (unknown.length) usageError(spec, unknown[0]);
+  return argv;
+}

package/owner-todo-scan.mjs

@@ -30,6 +30,7 @@ import process from "node:process";
 import { pathToFileURL } from "node:url";
 import { resolveDshHome, resolveDshWorkspace } from "./lib/dsh-home.mjs";
 import { firstH1Index, insertAtFor, stampDocMark } from "./lib/generated-docs.mjs"; // §2.2 权威源（档级标记）
+import { cliGuard } from "./lib/cli-args.mjs";
 // 升级锁现场（③ 包 C-6 段①②的第三处视图）：判据唯一源 = lib/upgrade-lock.mjs 的 status()
 // —— **绝不在此复制判定逻辑**（锁的心跳/pid 判据改一处就够）。
 // ⚠️ 该模块是**可选依赖**：它属于 DSH 生态内核（私有工具树），本仓不下发 ⇒ 改为动态加载 + 降级（见下方「可选内核」段）。
@@ -46,6 +47,21 @@ const HOME = resolveDshHome();
 // 这三个判据的真实实现长在 DSH 私有工具树（dsh-butler/lib）里，本仓不下发：
 //   · 目录存在 ⇒ 行为与私有树逐字一致；
 //   · 目录不存在 ⇒ 升级锁本节显式打印「不可探测」并继续；另两节静默跳过（它们是噪音源，不是"有你的事"）。
+const SPEC = {
+  cmd: 'dsh-owner-todo-scan',
+  summary: '把「等你操作 / 待拍板」的悬项从四处登记里合成一张清单（现场锁 / 看板卡 / 交接档 / 对端执行单）。',
+  usage: 'dsh-owner-todo-scan [--all] [--json] [--write]',
+  flags: [
+    { name: '--all', desc: '连已 done 卡里的历史段也扫（噪声多，兜底用）' },
+    { name: '--json', desc: '机器可读输出（含每条的档位判定）' },
+    { name: '--write', desc: '把清单整体重写成 docs 下的「待你操作-<设备>.md」' },
+  ],
+  writes: '默认只打印。--write 会整体重写一份 docs 下的清单文件（覆盖式刷新）。',
+  exits: '0 成功 · 1 采集异常 · 2 参数错误',
+  examples: ['dsh-owner-todo-scan', 'dsh-owner-todo-scan --json'],
+};
+cliGuard(SPEC);
+
 const TOOLS_DIR = process.env.DSH_TOOLS_DIR || path.join(resolveDshWorkspace(), "tools");
 const BUTLER_LIB = process.env.DSH_BUTLER_LIB || path.join(TOOLS_DIR, "dsh-butler", "lib");
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kira905/dsh-diagnostics-extra",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "DeepSeek Harness (DSH) diagnostics & reconciliation utilities: image-attachment audit/fetch (TRANSPORT root cause), one-command health check (host / dsh & guard start times / port connections), and an owner-action scanner. Zero third-party runtime dependencies.",
   "license": "AGPL-3.0-only",
   "private": false,