nx-sk 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-09-26
+
+### Added
+
+- **多行值的可靠通道**：`key set <名> -`（stdin）与 `key set <名> --data @文件.json`
+  （也接受 `-` 与 JSON 字面量）。对象含 `value` 键时取它，只含一个键时取那个键，
+  多键且无 `value` 直接报错而不是猜。
+
+### Fixed
+
+- **Git Bash 下多行参数不再被静默截断**（原始事故）：转发器里 `exec node` 走的是
+  PATH 上的 node，而它可能是 Volta 之类的中转 shim，那一跳会把 `$'l1\nl2\nl3'`
+  截成 `l1` 且**不报错**——一次性凭据就这么丢掉大半。改为直连本进程的
+  `process.execPath`，并带路径失效回退（node 升级换目录时退回 PATH，重跑
+  `link:local` 即恢复）。
+- **恢复被删的 `references/40-extend.md`**：它与 SKILL.md 路由表里的条目被**同时**
+  删掉，于是「路由表 ↔ 目录双向对账」两边一起变空、照样通过——这个 ref 就这样被
+  删了两次。新增断言钉住「ref 体系整体不被削掉」（必存 ref 下限 + 编号升序唯一），
+  已做反向验证（删文件时确实变红）。
+
+### Notes
+
+- **`.cmd` 那条路修不了**：实测直连真实 `node.exe` 与走 shim 结果**完全相同**
+  （多行都截断、尖括号都失败），瓶颈是 cmd.exe 解析 `.cmd` 内容时的 `%*` 展开。
+  cmd / PowerShell 下多行值必须走 `-` 或 `@文件`。
+- 原计划要在 CLI 里做「检测到含换行就拒绝」，实测后**放弃**：损坏后 CR 是被删掉而非
+  保留（`$'a\rb'` 实际落盘 `"ab"`），零真阳性；而 `@文件` 读入的合法 CRLF 多行值含
+  CR，会被自己的检测拦住（高假阳性）。LF 截断后与合法单行值不可区分——可靠信号不存在。
+
 ## [0.3.3] - 2026-09-26
 
 ### Fixed

package/assets/nx-sk/SKILL.md

@@ -73,7 +73,7 @@ nx-sk key remove OPENAI_KEY               # 删除，写前自动留快照
 | `10-sections-entries` | **动手填/改信息时必读**——栏目与条目的完整命令、AI 补全个人信息的推荐流程、字段字典怎么扩、读命令与写命令的参数陷阱 |
 | `20-secrets` | 存/读大模型 key、密文机制、密钥来源（环境变量 vs 本机密钥文件）、什么时候会解不开 |
 | `30-export-backup` | 整体导出、只导出某个栏目、快照与回滚、明文密钥的取舍 |
-| `40-extend` | 要**改这个项目本身**（加一个栏目模板、加一个功能域）时——闭环落点表与静默失效点 |
+| `40-extend` | 要**改这个项目本身**时读——加栏目模板、加功能域（含 12 项闭环表与「哪些地方漏了没有断言会发现」）、四条硬纪律、验证闸门、几个刻意不该改的地方 |
 
 取 ref 全文（外部 agent 用这条，不必进终端翻文件）：
 

package/assets/nx-sk/references/20-secrets.md

@@ -91,6 +91,43 @@ nx-sk section list                           # 列表里 KV 栏目带 [KV 表]
 - **重复写同一个值不会重写密文**：返回 `{ status: 'skipped', unchanged: true }`。
   每次加密都用新 IV，无脑重写只会产生一堆无意义的新密文和新快照。
 
+### 多行值：走 stdin 或 `@文件`（真实事故）
+
+Windows 上命令经启动器转发时，**命令行参数里的换行会被截断**，而命令**照样报成功**——
+一次性凭据（多行私钥、恢复码、证书）就这么静默丢掉后半截。同一条通道还会让含 `<` `>`
+的参数整串失败（被当成重定向符，报「系统找不到指定的路径」）。
+
+值的可靠通道有两条，任选：
+
+```bash
+printf '%s' "$KEY" | nx-sk key set OPENAI_KEY -        # stdin：值的位置参数写 -
+nx-sk key set OPENAI_KEY --data @C:/Users/me/值.json    # 文件：--data @路径（含 value 键）
+```
+
+`--data` 也接受 `-`（从 stdin 读 JSON）与直接给 JSON 字面量；对象含 `value` 键时取它，
+只含一个键时取那个键，多键且无 `value` 直接报错（不猜）。
+
+**路径必须用 Windows 形式**（`C:/Users/...`）：Git Bash 的 `/tmp` 在 node 侧看不到
+（实测 ENOENT），node 侧拿到的会是 `D:\tmp\...` 这种对不上的路径。
+
+#### 哪些情况下命令行参数本身是安全的
+
+实测（Windows 11 · Volta · Git Bash）分两种情况，**别当成一回事**：
+
+| 你在哪敲 | 命令行多行参数 | 说明 |
+| --- | --- | --- |
+| **Git Bash / WSL 终端** | ✅ **安全** | 0.3.4 起转发器直连真实 `node.exe`，绕开了会截断参数的那一跳 |
+| **cmd.exe / PowerShell** | ❌ **损坏** | 瓶颈是 cmd 解析 `.cmd` 文件内容（`%*` 展开），换 node 也治不了 |
+
+所以：**cmd / PowerShell 下多行值一律走 `-` 或 `@文件`**，这是硬要求；
+Git Bash 下裸参数已经能用，但脚本里要可移植的话，仍然推荐上面两条通道。
+
+> 没有「检测到损坏就报错」这回事——**做不到**。损坏后的值里 CR 是被**删掉**而非保留
+> （`$'a\rb'` 实际落盘 `"ab"`），所以「含 CR 即损坏」既抓不到真实损坏（零真阳性）、
+> 又会拦住用 `@文件` 写入的**合法 CRLF 多行值**（高假阳性）。而 LF 截断后与一个合法的
+> 单行值完全不可区分。可靠信号不存在，因此只能「提供可靠通道 + 修好通道本身」，
+> 不能靠事后检测兜底。
+
 ## 三、密文机制
 
 - 算法 **AES-256-GCM**（`core/crypto.js`）。每个值独立 IV，带认证标签。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-sk",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "nx-sk · 本机个人资源管理器（server-cli-web 骨架）：栏目化存储个人信息与大模型密钥，CLI 与 Web 同源，敏感字段密文落盘。",
   "type": "module",
   "bin": {

package/src/core/argsafe.js

@@ -0,0 +1,53 @@
+// CLI 参数安全：把「命令行传不了的东西」换成可传的形式。
+//
+// 为什么不放 runtime/spec.js：那里的 coerce() 是 CLI 与 HTTP **共用**的纯净解码器，
+// 而 HTTP 没有「命令行通道」这回事。CLI 专属的通道问题集中在 CLI 适配层解决。
+//
+// 背景（真实事故，见 ref 20-secrets）：Windows 上值经命令行参数传递时，启动器 shim
+// （Volta shim / npm 生成的 .cmd）会把换行当命令分隔符截断、把 < > 当重定向符，
+// 而命令**报成功**——一次性凭据就这么静默丢掉大半。文件与管道是可靠通道。
+//
+// 为什么不在这里做「检测损坏就报错」：实测做不到（详见 cli.js 的 expandSafeArgs）。
+// 损坏后的值里 CR 是被**删掉**而非保留，所以「含 CR」既抓不到损坏（零真阳性）、
+// 又会拦住用 --data 写入的合法 CRLF 多行值（高假阳性）；LF 截断后则与合法单行值
+// 完全不可区分。可靠的信号不存在，因此只能提供可靠通道 + 修好通道本身。
+import { readFileSync } from 'node:fs';
+import { badInput } from './errors.js';
+
+/**
+ * `--data` 的值：JSON 字面量 / `@文件路径` / `-`（stdin）。
+ *
+ * takeStdin 由调用方注入——CLI 传 readFileSync(0)，测试能换桩。
+ * 「读 stdin」因此不是一个无法测试的隐式依赖，也让本模块保持纯函数（不自己碰 fd 0）。
+ */
+export function parseDataArg(raw, takeStdin) {
+  const s = String(raw ?? '').trim();
+  if (!s) throw badInput('--data 需要一个 JSON 字面量、@文件路径，或 -（从 stdin 读）');
+  if (s === '-' || s === '@-') return parseJson(takeStdin(), '-');
+  if (s.startsWith('@')) return parseJson(readText(s.slice(1)), s.slice(1));
+  return parseJson(s, '--data'); // 直接给的字面 JSON
+}
+
+/** 值本身走 stdin 的入口（`key set NAME -`）。true 表示「这个值来自 stdin」。 */
+export function parseStdinValue(raw) {
+  return String(raw ?? '').trim() === '-';
+}
+
+function parseJson(text, src) {
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw badInput(`--data 不是合法 JSON（${src}）: ${e.message}`);
+  }
+}
+
+function readText(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch (e) {
+    // 路径写法是最常见的坑：Git Bash 的 /tmp 在 node 侧看不到（真实事故 ENOENT），
+    // 所以错误里直接把 Windows 路径形式写出来，省掉一轮排查。
+    throw badInput(`读取文件失败: ${p}（${e.message}）—— Windows 上请用 C:/Users/... 形式的路径`);
+  }
+}
+

package/src/modules/entries/index.js

@@ -129,6 +129,9 @@ export default {
       args: ['name', 'value'],
       flags: {
         value: { type: 'string', hint: '值的另一种给法（值以 - 开头时用 --value=<值>）' },
+        // 多行值经命令行会被 Windows 启动器 shim 截断成首行且不报错（见 ref 20-secrets），
+        // 文件与 stdin 是可靠通道。取 value 键；没有则取对象里唯一那个键。
+        data: { type: 'string', hint: '@文件.json（含 value 键），或 -（从 stdin 读原文）' },
         section: { type: 'string' },
         'dry-run': { type: 'boolean' },
       },

package/src/runtime/cli.js

@@ -1,8 +1,10 @@
 // 通用 CLI 运行器：解析 → 匹配 → 校验 → 渲染 → help。
 // 命令表由 action 声明派生，所以「Web 上能做的 CLI 都能做」是结构保证，不靠人记。
+import { readFileSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { APP_NAME, DEFAULT_PORT, ENV_STORE, VERSION } from '../core/paths.js';
 import { badInput, external, toErrorShape } from '../core/errors.js';
+import { parseDataArg, parseStdinValue } from '../core/argsafe.js';
 import { ACTIONS, MODULES, MODULE_TITLES, commandEntry } from './registry.js';
 import { applySpec, argSpecsOf, cliPathsOf, flagSpecsOf, usageOf } from './spec.js';
 
@@ -198,7 +200,60 @@ function parseArgs(action, tokens) {
   for (let i = 0; i < positional.length; i++) raw[argSpecs[i].name] = positional[i];
   // 显式 flag 覆盖位置参数：`key set K --value=<值>` 与 `key set K <值>` 必须等价，
   // 而后者在值以 `-` 开头时会被当成 flag（那时只能走前者）。
-  return { ...raw, ...flags };
+  // 位置参数与 flag 一起交给展开函数：`key set K -` 的 `-` 是位置参数，
+  // 不能因为它「看起来像 flag」就漏掉。
+  return expandSafeArgs({ ...raw, ...flags });
+}
+
+/**
+ * 安全通道展开 —— CLI 独有的「通道知识」全部集中在这一个函数里。
+ *
+ * Windows 上值经命令行参数进来时，启动器 shim（Volta / npm 的 .cmd）会把换行
+ * 当命令分隔符截断，而命令**报成功**——一次性凭据就这么静默丢掉大半（真实事故）。
+ * 文件与 stdin 不受影响，所以这里把 `--data @文件` / `-` 在进 applySpec 之前
+ * 换成真正的值。放这里而不是 spec.js：那边的 coerce() 是 CLI 与 HTTP 共用的
+ * 纯净解码器，而 HTTP 没有「命令行通道」这回事。
+ */
+function expandSafeArgs(raw) {
+  const out = { ...raw };
+  let stdinUsed = false;
+  // stdin 只能被消费一次：两个参数都写 `-` 的话第二个读到的是空，
+  // 静默读空比报错危险，所以显式拒绝。
+  const takeStdin = () => {
+    if (stdinUsed) throw badInput('stdin 只能被一个参数使用（已经有一个参数用 - 读过了）');
+    stdinUsed = true;
+    return readFileSync(0, 'utf8');
+  };
+
+  // --data 统一在这里解析成对象：spec.coerce 的 json 分支对「已是对象」的值直接返回，
+  // 所以两处不会各解析一遍，`-`（stdin）这条新通道也自然被 coerce 认作合法输入。
+  //
+  // 注意顺序：**先**解析 --data，再处理 `-`。反过来的话 `--data -` 会在 data 还没读 stdin
+  // 时就被判定成「value 也是 stdin」，把两次消费搅在一起（真实踩到的顺序 bug）。
+  if (typeof out.data === 'string') out.data = parseDataArg(out.data, takeStdin);
+
+  // `--data` 是位置参数 value 的替代给法（KV 表格只有一个值字段，语义确定），
+  // 所以给了 data 就不该再因为缺 value 而报用法错。
+  // 取 value 键；没有 value 键时取对象里唯一那个键。
+  //
+  // 位置参数 `-` 要**先于**这里的提取被认出来，否则 `key set K -` 的 `-` 会被
+  // 当成字面值 `-`。所以 stdin 判定放在 data 提取之后、用「value 是否还等于 -」判断。
+  if (out.value === undefined && out.data && typeof out.data === 'object' && !Array.isArray(out.data)) {
+    const keys = Object.keys(out.data);
+    if (out.data.value !== undefined) out.value = out.data.value;
+    else if (keys.length === 1) out.value = out.data[keys[0]];
+    else throw badInput(`--data 需要含 value 键，或只含一个键（收到 ${keys.length} 个: ${keys.join(', ')}）`);
+  }
+
+  if (typeof out.value === 'string' && parseStdinValue(out.value)) out.value = takeStdin();
+
+  // 注意：这里**没有**「值含换行就报错」的检测，因为做不到。
+  // 实测（Windows 11 / Volta）：损坏后的值里 CR 是被**删掉**而不是保留，
+  // 所以「含 CR」既抓不到损坏（零真阳性），又会拦住用 --data 写入的合法
+  // CRLF 多行值（高假阳性）。而 LF 截断后与合法单行值完全不可区分。
+  // 能做的只有：① 给出可靠通道（--data / stdin，本函数）；② 让通道本身不再损坏
+  // （scripts/link-local.mjs 的转发器直连 node.exe）。
+  return out;
 }
 
 const STATUS_NOTE = {