nx-sk 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+本文件格式参考 [Keep a Changelog](https://keepachangelog.com/)，中文正文。
+
+## [Unreleased]
+
+## [0.3.0] - 2026-09-25
+
+### Added
+
+- **字段填写策略 `fill`：`normal` / `optional` / `avoid`** —— 有些格子填了反而减分
+  （应届生的「上一家公司」、政治面貌为「群众」时的「入党时间」），这次把这种判断做成**数据**。
+  - `optional`（不必填）与 `avoid`（不填）**既不计入完整度的分子、也不计入分母**。
+    完整度这个数字是用来导航「还该补什么」的，被一批主动跳过的字段长期压着就失效了。
+  - 它们不会被藏起来：`serializeEntry` 新增顶层 `excluded[]`，与 `missing[]` **并列**
+    （「主动跳过」和「还没填」是两件事）；`completeness` 新增 `excluded`（个数）与
+    `excludedFilled`（标了不填却仍然填了的个数，非 0 就说明策略该更新了）。
+    CLI 的 `entry get` / `entry list` 把两者分开报，面板在字段标签上打中性标签。
+  - 新增 `section update --fill <字段>=normal|optional|avoid`（可重复，label 或 key 都认；
+    改回照常填传 `normal`）。`entry fields` / `section dump` 的字段字典输出带上
+    `fill` 与 `fillLabel`。
+  - `validateFieldDef` 放行 `fill` —— 该函数是**白名单**，漏了会静默丢弃新属性，
+    后果是「用户设了不填、完整度照旧算它」，很难查。非法策略报错而非忽略；`normal` 是缺省、不落盘。
+  - **非破坏性**：没有任何字段带 `fill` 时，行为与之前完全一致，旧 store 无需迁移。
+
+### Fixed
+
+- **「面板无 emoji / 不使用原生弹窗」这条守卫覆盖不全**：它只 `readdir` 了
+  `src/web/frontend/` 的**直接子文件**，于是 `frontend/components/`（`fieldEditor.jsx`、`ui.jsx`）、
+  `App.jsx`、`main.jsx`、`api/` 全都没被扫到 —— 等于**面板规则不覆盖面板**；
+  `src/core/`、`bin/`、`scripts/` 同样漏了。改为递归收集并补齐这几处，
+  顺手清掉 `core/render.js`、`core/store.js` 里两处漏网的 emoji。
+  已按项目「改完规则必须反向测试」的要求验证：往原先扫不到的 `components/fieldEditor.jsx`
+  注入 emoji，测试如期变红，还原后恢复全绿。
+
+## [0.2.0] - 2026-09-24
+
+### Changed
+
+- **【破坏性】密文字段默认原文显示**，打码改成显式选项：
+  `--reveal` 全部换成 `--mask`（`key get/list`、`entry get`、`section dump`、`GET /api/keys?mask=1`）；
+  导出默认也含明文（`settings.includeSecretsInExport` 默认 `true`，要打码加 `--no-secrets`）。
+  理由：本机单人工具，数据是给自己看的，默认打码等于每次先拦自己一道。
+  **落盘仍然是 AES-256-GCM 密文**——「store.json 泄露」不等于「凭据泄露」这一点没变。
+  面板里的勾选框从「显示密文字段明文」翻成「打码显示（投屏/截图时用）」，默认不勾。
+- **【破坏性】skill 不再出现在 Web 面板**：删掉 Skill tab 与它的视图；`skill install` / `skill get`
+  仍完整保留在 CLI（用户明确要求，偏离了骨架 ref「三条最高优先级命令要有 Web 入口」的建议）。
+- **【破坏性】密钥栏目从 8 字段缩成极简 KV**：只保留「名称（条目名）→ 值」。
+  删掉了服务商 / 接口地址 / 模型 / 用途 / 有效期 / 额度 / 备注 ——
+  存一个 key 不该先填一张表；「这个 key 干什么用」写进键名里就够了。
+  - **自动迁移**：`store.json` 版本升到 `2`。首次读盘时把旧 `keyValue` 的值搬到 `value`，
+    并**先留一份迁移前的原始文件快照**到 `~/nx-sk/backup/…-migrate-v1-to-v2.json`；
+    其余旧值**不删除**（不再显示 ≠ 删掉），`bootstrap --json` 的 `migration` 字段会报告迁移结果。
+  - 迁移幂等：`version` 落盘后不再触发。
+
+### Added
+
+- **README 补「安装」节**：`npm link` 做成全局垫片（全局 node_modules 是指向项目的软链，
+  改代码即刻生效）、skill 的**软链垫片**做法、以及 `npm unlink -g nx-sk` 的回退方式。
+- **skill 在本机改成软链**：`~/.claude/skills/nx-sk` 与 `~/.workbuddy/skills/nx-sk`
+  现在都软链到项目 `assets/nx-sk`（与 `server-cli-web-scaffold` 同一种做法）。
+  `skill install` 装的是**副本**，只在分发/跨机器时用；日常用软链才不会让 agent 拿到旧版手册。
+- **【破坏性】KV 栏目在面板里就是一张表**：`secret` 标了 `kv: true`，面板渲染成
+  「名称 / 值」两列表格（改值即改、加行即加键、行内重命名、一键复制），
+  **不再有**条目列表、字段表单、完整度百分比 —— 那些只对「一族同构条目」的栏目（求职）有意义。
+  CLI 侧 `key *` 缺省作用在标了 `kv` 的栏目上，并新增 `--section`；
+  `settings.kvSection` 这个间接层**删掉**（哪个栏目是 KV，由栏目自己说了算）。
+- **KV 栏目拒绝加字段**：往里塞字段会让「值在哪一列」变得不确定，所以直接报错并指出
+  该用 `key set`。这条是真实事故换来的：早先面板那行「KV 直填」把 `3123312=xxx`
+  登记成了字段，用户看到的是一堆无意义的「模板建议」。
+  配套 v2 → v3 迁移：把误当字段用的值搬进值列，字段收成一个，旧键一律不删，迁移前留原始快照。
+- **`entry update` 改名时挡住重名**（同栏目已有同名条目报 `CONFLICT`）——
+  重名会让「按名字取」变成二义。
+- **字段台账不再拦写入**：`--set 任意键=值` 一律能存，没见过的键自动登记
+  （键名就是字段名，**中文也可以**；类型按值推断：`是/否` → bool、数组 → tags、其余 → text）。
+  `--allow-new-field` 随之取消（它现在是默认行为）。
+  **刻意不推 number**：18 位身份证号这类长数字超过 2^53，推成数字会静默丢精度。
+- **面板加「KV 直填」行**：敲 `字段=值` 回车即写入，不再必须先在分组表单里找到那一格；
+  「未填 N 项」也从告警口吻改成中性的「模板建议里还有 N 项没填（不影响使用）」。
+- `assertFieldKey` 放宽到允许中文（仍挡空白 / 路径分隔符 / `..`），
+  这样 `--set 微信号=xxx` 存下去就是 `微信号`，不必再记一个英文别名。
+- **`key` 系列命令（KV 直通）**：`key set <名称> <值>` / `key get <名称> [--reveal]` /
+  `key list [--reveal]` / `key remove <名称>`，对应接口
+  `PUT /api/keys/:name` / `GET /api/keys/:name` / `GET /api/keys` / `DELETE /api/keys/:name`。
+  - `key *` 是 `entry *` 的**语法糖**，与 `entry` 同模块、共用同一批 service 函数
+    （加解密 / 打码 / 快照 / `--dry-run` 只有一份实现），有一致性测试钉住「不许另起一套」。
+  - `key set` 是 **SET 语义**（同名覆盖，返回值带 `created`）。这是它与 `entry add`
+    （同名报 `CONFLICT`）唯一刻意的差别。
+  - 重复写同一个值 → `{ status: 'skipped', unchanged: true }`，不重写密文、不留快照。
+  - 作用栏目由新设置项 `settings.kvSection` 决定（默认 `secret`）。
+- CLI 位置参数与 flag 的优先级明确为**显式 flag 覆盖位置参数**，
+  于是 `key set K <值>` 与 `key set K --value=<值>` 等价 ——
+  后者是值以 `-` 开头时唯一可用的写法。
+
+### Fixed
+
+- `cli.js` 的 `parseArgs` 原本让位置参数覆盖同名的显式 flag，导致 `--value=` 被静默忽略。
+- `key set` 的「值没变」判定原本只比明文，面板原样回传打码值时会被误判成覆盖
+  （多写一次密文 + 多留一份快照）。现在明文相同与掩码相同都算「未改动」。
+
+## [0.1.0] - 2026-09-24
+
+首个版本：本机个人资源管理器（server-cli-web 骨架的完整实现）。
+
+### Added
+
+- **栏目化数据模型**：栏目 = 一组同构条目 + 一份字段字典（字典是数据，不是代码分支）。
+  内置两个模板：`job`（求职 / 个人信息，9 分组 75 字段）、`secret`（密钥，8 字段）。
+- **CLI**（26 条命令）：`serve` / `help` / `version` 三个平台命令，
+  以及 `bootstrap` / `health` / `routes` / `section.*` / `entry.*` / `export.*` / `setting.*` / `skill.*`。
+- **HTTP API**：由 action 声明同源编译，路由按「字面量段优先」排序（`/api/sections/templates`
+  不会被 `/api/sections/:ref` 遮蔽）。写操作校验 `Origin`。
+- **Web 面板**：栏目动态 tab、按分组渲染的字段表单、PATCH 语义保存（只发改动过的字段）、
+  密文字段一键揭示、完整度与未填清单、派生式 CLI 提示、页内 toast / dialog / 错误边界。
+- **密文存储**：敏感字段 AES-256-GCM 落盘，密钥来源支持 `NX_SK_PASSPHRASE`（scrypt + 盐）
+  或本机 `~/.vaultkey`；密文带密钥指纹 `kid`，换来源时给明确的 `BLOCKED` 而不是乱码。
+  打码值原样回传会被识别为「不修改」，直接写入打码占位会被拒绝。
+- **整体导出**：JSON + Markdown，支持按栏目、指定目录、`--dry-run`；凭据默认打码，
+  `--with-secrets` 才出明文并在导出文件里标记 `withSecrets`。
+- **快照与回滚**：每次破坏性写入前整库快照到 `~/nx-sk/backup/`（最多 20 份）。
+- **损坏保护**：`store.json` 解析失败先改名为 `.corrupt-<时间戳>.json`，不静默覆盖。
+- **内置 skill**：`skill install` 装到 `~/.claude/skills`（三态，不静默覆盖），
+  `skill get` 输出「prefix → 文档 → install 状态」三段，`--json` 为四元契约。
+- **测试**：40 项单测（含一致性断言：模块目录 ↔ 注册表 ↔ 前端视图表 ↔ 视图里的 `/api` 字面量、
+  CRUD 五操作与路由形状、CLI 路径可解析回自身、eslint 互依禁列覆盖、文档漂移防护、
+  装载期自检的负向反证）+ 56 项端到端冒烟断言。
+
+### Notes
+
+- 数据默认落在 `~/nx-sk/`（骨架 ref 的默认是 `~/.<主题名>/`，本实现按项目要求改成可见目录）。
+- 存储路径支持 `NX_SK_HOME` / `NX_SK_STORE` 覆盖 —— **不是可选项**：没有它测试会写脏真实数据。
+- eslint 的模块互依禁列是**逐模块枚举**的：新增模块必须补一行，漏补是静默的
+  （已由 `tests/unit/consistency.test.mjs` 兜住）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nx-sk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# nx-sk · 本机个人资源管理器
+
+把你的信息按**栏目**存起来。CLI 与 Web 面板是同一条业务链，敏感字段密文落盘，
+数据全在你自己机器上 —— 默认 `~/nx-sk/`。
+
+```
+nx-sk serve          # 打开面板（http://127.0.0.1:7866）
+```
+
+![结构](https://img.shields.io/badge/node-%3E%3D18.17-informational) ![license](https://img.shields.io/badge/license-MIT-informational)
+
+## 安装
+
+命令名就是包名。**推荐做成全局垫片**（全局 node_modules 里是指向本项目的软链，
+改代码立刻生效，不用重新安装）：
+
+```bash
+cd <本项目>
+pnpm install          # 只为构建面板；CLI 侧零依赖
+pnpm run build        # 产出 src/web/public，serve 才有面板可服务
+npm link              # → 全局多了 nx-sk / nx-sk.cmd / nx-sk.ps1
+nx-sk version         # 从任何目录都能跑
+nx-sk serve           # 打开面板
+```
+
+取消：`npm unlink -g nx-sk`（只删全局垫片，不动项目）。
+
+> **npm 的全局 prefix 不在你的 PATH 里怎么办**（用 Volta / nvm 管理 node 时很常见）：
+> `npm link` 会把垫片放进 npm 的 prefix 目录，而那个目录可能不在终端的 PATH 上，
+> 于是你敲 `nx-sk` 会 command not found —— 但某些 shell（比如被别的工具注入过 PATH 的）却能跑。
+> 这种情况自己做一个垫片，放进**你自己的 bin 目录**（确认它在 PATH 里）：
+>
+> ```sh
+> # ~/.local/bin/nx-sk（Git Bash / sh）
+> #!/bin/sh
+> MSYS_NO_PATHCONV=1; export MSYS_NO_PATHCONV   # 不开这个，MSYS 会把 /d/... 按当前盘符改写成 d:\d\...
+> exec node "<项目绝对路径>/bin/nx-sk.mjs" "$@"
+> ```
+>
+> ```bat
+> :: ~/.local/bin/nx-sk.cmd（cmd.exe / PowerShell）
+> @echo off
+> node "D:\a_js\js_proj\nx-sk\bin\nx-sk.mjs" %*
+> ```
+>
+> 别忘了 `chmod +x ~/.local/bin/nx-sk`。验证：`cd / && nx-sk version`。
+
+> 不想污染全局也行：`node bin/nx-sk.mjs <子命令>` 等价，或 `npx --no-install . <子命令>`。
+
+### skill：用**软链垫片**（推荐）
+
+`skill install` 装出去的是**副本**，不会跟着源码走 —— 改了 `assets/nx-sk/` 就变旧版手册。
+日常开发应该用**软链**指向项目里的源，改完立刻生效、永远不会漂移：
+
+```bash
+# Windows（cmd / 终端里，目录软链）
+mklink /D "%USERPROFILE%\.claude\skills\nx-sk"      "D:\a_js\js_proj\nx-sk\assets\nx-sk"
+mklink /D "%USERPROFILE%\.workbuddy\skills\nx-sk"   "D:\a_js\js_proj\nx-sk\assets\nx-sk"
+# Windows（Git Bash，需要原生软链）
+MSYS=winsymlinks:nativestrict ln -s "D:/a_js/js_proj/nx-sk/assets/nx-sk" "$HOME/.claude/skills/nx-sk"
+
+# macOS / Linux
+ln -s "$(pwd)/assets/nx-sk" "$HOME/.claude/skills/nx-sk"
+ln -s "$(pwd)/assets/nx-sk" "$HOME/.workbuddy/skills/nx-sk"
+```
+
+建好之后 `nx-sk skill install` 会变成 no-op（内容一致 → 跳过），因为目标就是源本身。
+
+> 软链建不出来？退回到复制式安装（适合分发给别人 / 跨机器，但**改完记得重装**）：
+>
+> ```bash
+> nx-sk skill install                           # → ~/.claude/skills/nx-sk（三态：安装/跳过/冲突）
+> nx-sk skill install --to ~/.workbuddy/skills  # WorkBuddy 侧的 agent 也读得到
+> nx-sk skill install --force                   # 改了 assets/nx-sk/ 之后必须重装，否则是旧版
+> nx-sk skill get nx-sk --json                  # 外部 agent 一键拿全上下文（四元：skillName/ref/content/contentBytes/install）
+
+## 它是什么
+
+一个「本机工具类」项目的标准骨架实现（server-cli-web）：**serve 驱动 CLI 与 Web，
+CLI 与 API 同源，skill 驱动 agent**。落到具体功能上：
+
+| 栏目 | id | 内容 |
+| --- | --- | --- |
+| 求职 | `job` | 求职用的个人信息档案：9 个分组 / 75 个字段（姓名、学历、联系方式、求职意向、紧急联系人…）。模板只是**建议清单**，`--set 任意键=值` 直接写 |
+| 密钥 | `secret` | **一张 KV 表**（`kv: true`）：面板上就是两列表格（名称 / 值），一行一个键。落盘是 **AES-256-GCM** 密文，读出来默认是原文（`--mask` 才打码） |
+
+栏目不是写死的：字段字典是**数据**，加字段、加栏目都不用改代码。
+
+## 三条核心不变量
+
+1. **一条 action 同时声明 CLI 与 HTTP。** 面板上能做的，CLI 都能做；参数名与错误码两端一致。
+2. **依赖只能向下**：`core ← modules ← runtime ← bin`，模块之间不许互相 import（lint 强制）。
+3. **失败抛异常（退出码 1），业务结果返回 `{ status }`（退出码 0）。**
+   `conflict` / `blocked` / `skipped` 都是正常返回 —— agent 看 `status`，不看退出码。
+
+## 命令总表
+
+平台命令（`runtime/cli.js` 的 BUILTINS）：
+
+| 命令 | 作用 |
+| --- | --- |
+| `nx-sk serve [--port N] [--no-open]` | 起 Web 面板（唯一常驻命令；默认只绑 `127.0.0.1`） |
+| `nx-sk help [主题]` | 命令表（由 action 声明生成，不是手写） |
+| `nx-sk version` | 裸输出版本号 |
+
+模块命令（`src/modules/*/index.js` 声明，`nx-sk routes` 可双向查）：
+
+| 命令 | 作用 |
+| --- | --- |
+| `nx-sk bootstrap [--json]` | 一次拿齐上下文：版本 / 存储路径 / 栏目 / 设置 / 命令表 |
+| `nx-sk health` | 存活与存储可达性检查 |
+| `nx-sk routes [--module M] [--http "POST /api/entries"]` | 命令 ↔ 路由双向对照 |
+| `nx-sk section list \| get \| add \| update \| remove` | 栏目 CRUD |
+| `nx-sk section dump <id> [--mask]` | **一个栏目的全部信息**：字段台账 + 全部条目 + 每个条目的未填清单 |
+| `nx-sk section templates` | 内置模板（job / secret） |
+| `nx-sk entry list \| get \| add \| update \| remove` | 条目 CRUD（PATCH 语义） |
+| `nx-sk entry fields [--section job]` | 字段字典 —— 填之前先看这个，别猜字段名 |
+| `nx-sk export run [--format json\|md\|both] [--section id] [--with-secrets] [--out DIR] [--dry-run]` | 整体导出 |
+| `nx-sk export list` | 历次导出与目录内文件 |
+| `nx-sk setting get \| set` | 全局设置 |
+| `nx-sk skill list \| install \| get` | 把内置 skill 装给 agent / 给外部 agent 取上下文 |
+
+所有写命令都有 `--dry-run`；所有命令都支持 `--json`（标准输出**单个** JSON 值）。
+
+## 快速上手
+
+```bash
+pnpm install
+pnpm start                     # 构建前端 + 起面板
+# 或开发模式（vite :5180 + serve :7866，一个 Ctrl-C 关两个）
+pnpm run dev
+```
+
+用 CLI 填一份档案：
+
+```bash
+nx-sk entry fields --section job --json          # ① 看字段字典
+nx-sk entry add --section job --set 姓名=张三 --set 电话=13800000000 --json
+nx-sk entry update 张三 --data @补全.json --dry-run   # ② 批量补，先试运行
+nx-sk entry update 张三 --data @补全.json
+nx-sk section dump job --json                    # ③ 复核：完整度 + 未填清单
+```
+
+存一个大模型 key —— 密钥栏目就是**极简 KV：名称 → 值**（**值不会以明文进 store.json**）：
+
+```bash
+nx-sk key set OPENAI_KEY sk-xxxxxxxx     # 写入：不存在则新建，存在则覆盖
+nx-sk key get OPENAI_KEY                 # 取值：默认就是原文
+nx-sk key get OPENAI_KEY --mask           # 投屏/截图时才打码：sk-x******xxxx
+nx-sk key list                            # 所有键（默认原文）
+nx-sk key remove OPENAI_KEY               # 删除，写前自动留快照
+```
+
+状态与栏目一样：`key *` 只是 `entry *` 的语法糖（同模块、同一批 service 函数），
+作用在 `settings.kvSection` 指向的单字段栏目上（默认 `secret`）。
+
+整体导出（凭据默认**含明文**——本机自己用；要分享给别人时加 `--no-secrets` 打码）：
+
+```bash
+nx-sk export run --format both --out D:/备份/nx-sk
+nx-sk export list
+```
+
+## 数据与安全
+
+| 项 | 位置 / 做法 |
+| --- | --- |
+| 数据目录 | `~/nx-sk/`，可用 `NX_SK_HOME` 覆盖 |
+| 状态文件 | `~/nx-sk/store.json`，可用 `NX_SK_STORE` 覆盖；**原子写**（临时文件 + rename） |
+| 密文密钥 | 环境变量 `NX_SK_PASSPHRASE`（scrypt 派生 + 盐）优先，否则 `~/nx-sk/.vaultkey`（32 字节随机，0600） |
+| 快照 | 每次破坏性写入前整库备份到 `~/nx-sk/backup/`（最多 20 份），拷回即回滚 |
+| 导出 | `~/nx-sk/export/`，默认不含凭据明文 |
+| 服务绑定 | 默认 `127.0.0.1`，不暴露到局域网；写操作校验 `Origin` |
+| 数据损坏 | `store.json` 解析失败会先被改名为 `.corrupt-<时间戳>.json`，不会静默覆盖 |
+
+换成口令模式更安全（口令不落盘）：
+
+```bash
+export NX_SK_PASSPHRASE='你的长口令'      # 之后所有密文都用它派生
+```
+
+注意：**换口令或删掉密钥文件后，旧密文解不开**（这是设计，密文指纹 `kid` 会明确报错）。
+
+## 给 agent 用
+
+```bash
+nx-sk skill install                 # 装到 ~/.claude/skills/nx-sk（三态，不静默覆盖）
+nx-sk skill get nx-sk --json        # {skillName, ref, content, contentBytes, install}
+nx-sk skill get nx-sk 10-sections-entries   # 裸名 → references/10-sections-entries.md
+```
+
+内置 skill 的 ref 路由表：
+
+| ref | 何时读 |
+| --- | --- |
+| `00-design` | 为什么这么分层、错误码与 `{status}` 的分工 |
+| `10-sections-entries` | 填/改信息的完整命令与 AI 补全流程 |
+| `20-secrets` | 密文机制、密钥来源、排查「解不开」 |
+| `30-export-backup` | 导出、快照与回滚 |
+| `40-extend` | 改这个项目本身：闭环落点表与静默失效点 |
+
+## 开发
+
+```bash
+pnpm test        # = lint + build + 冒烟（56 项断言） + 单测（40 项）
+```
+
+| 目录 | 职责 |
+| --- | --- |
+| `bin/nx-sk.mjs` | 唯一入口，只转发 argv + 兜异常 |
+| `src/core/` | 零业务语义：paths / errors / store / fsx / crypto / vault / fields / render / ids / open |
+| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务) + `view.jsx`(面板) |
+| `src/runtime/` | registry / spec / cli / api / server —— 装配层，不写业务 |
+| `src/web/frontend/` | React 壳 + 组件 + 视图注册表 |
+| `assets/nx-sk/` | 随包分发的 skill（SKILL.md + references/） |
+| `tests/unit/` · `tests/smoke.mjs` | 一致性断言 + 端到端冒烟 |
+
+**加一个功能域要碰的 12 处**（其中 3 处没有任何断言会替你发现）见 `assets/nx-sk/references/40-extend.md`。
+
+## License
+
+MIT

package/assets/nx-sk/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: nx-sk
+description: 本机个人资源管理器——栏目化存储个人信息（求职档案等）与大模型 API Key，CLI 与 Web 面板同源，敏感字段密文落盘。当用户要"记录/更新我的个人信息"、"填一份求职档案"、"存一个大模型 key"、"管理我的密钥"、"导出我的资料"、"起一个个人资料面板"，或需要在填表单/网申时批量取用个人字段、用 CLI 快速设置某个栏目内容时使用。触发词：nx-sk、个人资源管理器、个人信息、求职档案、栏目、条目、密钥、API key、密文、导出、面板、serve。不适用：纯问答、不需要落盘的临时讨论；也不适用于把密钥同步/上传到远程服务的场景——nx-sk 只在本机落盘，不做任何上传。
+---
+
+# nx-sk · 本机个人资源管理器
+
+一句话：**把「你的信息」按栏目存起来，CLI 与 Web 面板是同一套业务，敏感字段密文落盘。**
+
+数据落在 `~/nx-sk/`（可用环境变量 `NX_SK_HOME` / `NX_SK_STORE` 覆盖）。默认两个栏目：
+
+| 栏目 | id | 内容 |
+| --- | --- | --- |
+| 求职 | `job` | 求职用的个人信息档案（姓名/学历/求职意向…约 70 个字段） |
+| 密钥 | `secret` | **一张 KV 表**（`kv: true`）：一行一个键值对。面板渲染成表格，值以 AES-256-GCM 密文落盘 |
+
+## 核心不变量
+
+1. **栏目 = 一组同构条目 + 一份字段台账。台账是数据，不是代码。**
+   字典随栏目存在 store 里，所以 agent 与面板看到的字段永远一致。
+   **它不拦写入**：`--set 任意键=值` 一律能存，没见过的键会自动登记（键名就是它本身，
+   中文也可以）。台账的用处是「模板建议 + 你实际写过什么」，不是门禁。
+   *违反会怎样*：如果把它做成门禁，用户每换一个表单就要先改一次 schema ——
+   而那正是「只想存个 kv」时最不想付的成本。
+
+2. **一条 action 同时声明 CLI 与 HTTP。** 面板上能做的，CLI 都能做；两边参数名、错误码一致。
+   *违反会怎样*：只能靠字符串匹配猜错误，无法可靠分支。
+
+3. **失败抛异常（退出码 1），业务结果返回 `{ status }`（退出码 0）。**
+   `conflict` / `blocked` / `skipped` 都是**正常返回**，agent 要看 `status` 字段而不是退出码。
+   *违反会怎样*：把一个「等用户决策」的冲突当成失败去重试。
+
+## 命令面（先跑这一条）
+
+```bash
+nx-sk bootstrap --json        # 版本 / 存储路径 / 栏目 / 设置 / 命令表，一次拿齐
+```
+
+零知识时的主力命令：
+
+```bash
+nx-sk entry fields --section job --json              # ① 看台账：模板建议字段 + 你写过什么
+nx-sk entry update <条目id或条目名> --set 字段=值     # ② 直接写：字典里没有的键会自动登记
+nx-sk section dump job --json                        # ③ 一个栏目的全部信息 + 每个条目的未填清单
+```
+
+**键就是键**：`--set 微信=xxx` 存下去就是 `微信`，不需要先翻译成英文 key。
+
+`--set` 的键**可以用 key 也可以用中文标签**（`--set 电话=138…` 与 `--set phone=138…` 等价）。
+一次写很多字段用 `--data @file.json`（`--data` 也接受内联 JSON）。
+
+存/取密钥（KV）走这四条，别用 `entry --set value=` 绕一圈：
+
+```bash
+nx-sk key set OPENAI_KEY sk-xxxxxxxx     # 写入（存在即覆盖，返回 created 告诉你是哪种）
+nx-sk key get OPENAI_KEY                 # 取值：默认就是原文
+nx-sk key get OPENAI_KEY --mask           # 投屏/截图时才打码
+nx-sk key list                            # 所有键（默认原文）
+nx-sk key remove OPENAI_KEY               # 删除，写前自动留快照
+```
+
+`key *` 是 `entry *` 的**语法糖**（同模块、同一批 service 函数），缺省作用在标了 `kv` 的栏目上
+（`--section` 可指定）。区别只有一个：`key set` 遇到同名是**覆盖**，`entry add` 是报 `CONFLICT`。
+
+**KV 栏目不许加字段**：它的形状就是一行一个键值对。想加东西就用 `key set <名称> <值>`
+（在 KV 栏目里 `entry update --set 新键=值` 会被拒绝并告诉你该用哪条命令）。
+
+## ref 路由表（按需加载）
+
+| ref | 何时读取 |
+| --- | --- |
+| `00-design` | 想搞清楚「为什么这么设计」、分层与依赖方向、错误码与 `{status}` 的分工时 |
+| `10-sections-entries` | **动手填/改信息时必读**——栏目与条目的完整命令、AI 补全个人信息的推荐流程、字段字典怎么扩、读命令与写命令的参数陷阱 |
+| `20-secrets` | 存/读大模型 key、密文机制、密钥来源（环境变量 vs 本机密钥文件）、什么时候会解不开 |
+| `30-export-backup` | 整体导出、只导出某个栏目、快照与回滚、明文密钥的取舍 |
+| `40-extend` | 要**改这个项目本身**（加一个栏目模板、加一个功能域）时——闭环落点表与静默失效点 |
+
+取 ref 全文（外部 agent 用这条，不必进终端翻文件）：
+
+```bash
+nx-sk skill get nx-sk                          # SKILL.md 全文
+nx-sk skill get nx-sk 10-sections-entries      # 裸名 → references/10-sections-entries.md
+nx-sk skill get nx-sk references/20-secrets.md # 也可写完整路径
+nx-sk skill get nx-sk --json                   # 四元 JSON：{skillName, ref, content, contentBytes, install}
+```
+
+## 什么时候不用
+
+- 用户只是随口问一句、不需要落盘 —— 别动数据。
+- 想找「面板上的 skill 页」—— 没有：**skill 只走 CLI**（`nx-sk skill install` / `nx-sk skill get`），
+  面板里不呈现它。
+- 用户要把密钥**同步到云端/团队** —— nx-sk 只做本机落盘与本地导出，不做上传。
+- 只是要看一眼面板 —— 提示 `nx-sk serve`，别用 CLI 重放一遍。
+
+## 硬约束（动手前先记住）
+
+- 所有写命令都有 `--dry-run`，先试运行再落盘；删除类命令**自动留快照**在 `~/nx-sk/backup/`。
+- 密文字段**落盘是密文，读出来默认是原文** —— 本机单人工具，自己看的东西不先拦一道。
+  要打码形态（投屏 / 截图）显式加 `--mask`。
+- 把打码后的值（含 `******`）当新值写回去会被拒绝 —— 那通常意味着「不修改」，什么都不传即可。
+- 导出默认**含明文**；要分享出去时加 `--no-secrets`。
+- **绝不把密钥明文打进日志、提交进 git、或写进给第三方的输出里。**

package/assets/nx-sk/references/00-design.md

@@ -0,0 +1,116 @@
+# 00 · 设计思想
+
+> 骨架级文档：回答「为什么这么设计」。**不放场景级 SOP** —— 怎么调命令看 `10-sections-entries` / `20-secrets` / `30-export-backup`。
+
+## 一、驱动关系
+
+```
+        ┌──────────────────────────────────────────┐
+        │  serve（唯一常驻入口，默认 127.0.0.1:7866）  │
+        └───────────────┬──────────────────────────┘
+                        │ 静态面板 + /api
+        ┌───────────────┴──────────────┬────────────┐
+        ▼                              ▼            │
+   Web 面板                        HTTP API         │
+        └──────────────┬───────────────┘            │
+                       ▼                            │
+              action 声明（唯一真相源）               │
+                       ▼                            ▼
+                service 层（业务）              CLI（同一条链）
+                       ▼                            │
+         core（存储 / 密文 / 字段字典 / 渲染）          │
+                                                    ▼
+                          skill install ──► ~/.claude/skills ──► agent
+```
+
+三条驱动链，一条比一条向上一级：serve 驱动 CLI 与 Web；CLI/Web 驱动 skill；skill 驱动 agent。
+
+**第 3 条是这个骨架跟普通 CLI 工具的分水岭**：nx-sk 不只是给人用的，也是给 agent 用的。
+一旦承认这点，`--json` 的稳定性、错误码、幂等性就从「锦上添花」变成硬契约。
+
+## 二、分层与依赖方向
+
+```
+core/       零业务语义：paths / errors / store / fsx / crypto / vault / fields / render / ids / open
+modules/    功能域，每个自包含：index.js(声明) + service.js(业务) + view.jsx(面板)
+runtime/    装配层：registry / spec / cli / api / server —— 不写业务
+web/frontend/  React 壳，只 import 各模块的 view.jsx
+```
+
+| 允许 | 禁止 |
+| --- | --- |
+| `core` ← `modules` ← `runtime` ← `bin` | 反向依赖（core 不许 import 上层） |
+| `web/frontend/*` 与 `view.jsx` import 组件、api 客户端、store | 前端 import `core/`、`runtime/`、`node:*`、任何 `service.js` |
+| 任意模块 → `../settings/service.js`（单向只读，基础模块） | 其它模块之间互相 import |
+| `view.jsx` → `../../web/frontend/components/*` | `core` / `runtime` / `service.js` → 任何 `.jsx` |
+
+**例外只有一处**：`settings` 是基础模块，允许被单向只读依赖。它的落地方式是——
+eslint 的模块互依禁列**逐模块枚举**，"例外"就等于**不把它列进去**。
+
+**模块要 runtime 的数据怎么办**（如 `system` 需要命令表）：用**函数体内的动态 import** 破环。
+静态 import 会成环，动态 import 不会——这是全项目唯一需要用到它的地方。
+
+## 三、关键不变量
+
+### 1. 字段字典是数据，不是代码分支
+
+栏目自己带一份 `fields[]`（key / label / type / group / options / sensitive），
+条目按它存取。所以：
+
+- CLI 与面板的字段集合不可能分叉——它们读的是同一份；
+- 写入**不受字典限制**：没见过的键自动登记（键名即字段名），agent 与用户都不必先改 schema；
+- `--set` 的键同时接受 `key` 与中文 `label`，人机都顺手。
+
+*违反会怎样*：如果字段写死在代码里，面板加一个字段就要改前端 + 后端 + 文档三处，
+而漏改任何一处都不会报错——只是「面板上有、CLI 里没有」。
+反过来，如果把它做成写入门禁，用户每见一个新表单就得先扩一次字典——那是把成本推给了用户。
+
+### 2. 一条 action 同时声明 cli 与 http
+
+```js
+{ id: 'entry.update', cli: ['entry','update'], http: ['PATCH','/api/entries/:ref'], run, render }
+```
+
+CLI 命令表、HTTP 路由表、`help` 文本全部由此派生。
+**方向刻意不对称**：`cli` 必填，`http` 可为 `null`（纯 CLI 命令）。
+这样「Web 上能做的 CLI 都能做」是结构保证，而不要求反向。
+
+*违反会怎样*：两份清单必然分叉 —— 面板上有按钮、CLI 里没命令，且没人发现。
+
+### 3. 失败抛异常，业务结果返回 `{ status }`
+
+判据是**「调用方要不要处理它」**：
+
+| 情形 | 表达 | 例子 |
+| --- | --- | --- |
+| 调用方无从处理，只能中断上报 | `throw` | 字段名打错、条目不存在、密钥解不开 |
+| 调用方要拿它做决策 | `return { status }` | 栏目非空需 `--force`（`blocked`）、技能安装冲突（`conflict`）、已是期望状态（`skipped`） |
+
+**冲突不是错误。** 面板要拿它弹窗让用户决策，所以不能抛。
+CLI 侧这四个取值分别渲染成不同的可读提示，退出码只有「抛异常」才是 1。
+
+## 四、错误契约
+
+| code | 判据 | HTTP |
+| --- | --- | --- |
+| `INVALID_INPUT` | 输入本身不合法 | 400 |
+| `NOT_FOUND` | 指定的目标不存在 | 404 |
+| `CONFLICT` | 目标存在且与期望状态冲突，需要用户选一侧 | 409 |
+| `BLOCKED` | 操作合法但被前置条件挡住（或密钥不一致） | 409 |
+| `EXTERNAL` | 外部命令/端口失败 | 502 |
+| `INTERNAL` | 兜底 | 500 |
+
+映射**只写一处**（`core/errors.js`）。`--json` 的错误对象向后兼容：`error` 保持字符串，`code` 是新增字段。
+
+## 五、错误案例表（都实测踩过）
+
+| 错误操作 | 实际后果 | 正确做法 |
+| --- | --- | --- |
+| 把「读命令的过滤 flag」照抄写命令的 `default` | 参数层无条件注入默认值 → 「不传 = 全部」的分支**永远走不到**，不报错、不崩，只是永远返回半个结果 | 写命令的 flag 可带 `default`；读命令的过滤 flag 一律不带 |
+| 路由只按声明顺序匹配 | `GET /api/sections/templates` 被 `GET /api/sections/:ref` 遮蔽，命中哪条取决于 actions 数组顺序 | 路由按「字面量段优先」排序，让声明顺序无关（`runtime/spec.js` 的 `compareRoutes`） |
+| 把打码值当成新值写回去 | 密钥字段被写成 `sk-1****cdef` 这串掩码，**原凭据永久丢失** | 写入前比对掩码：相等就当成「未改动」保留原密文；含 `******` 的值直接拒绝 |
+| 删条目/栏目不留快照 | 误删即不可逆；这是用户的**唯一一份**个人信息 | 所有破坏性写操作先 `snapshotStore()` 到 `~/nx-sk/backup/` |
+| store.json 解析失败就当空库继续 | 下一次写入把用户数据永久覆盖 | 先把损坏文件改名为 `store.json.corrupt-<时间>.json`，再降级返回空结构 |
+| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 同时覆盖 `view.jsx`，禁掉 `node:*` / `core` / `runtime` / `service.js` |
+| 新增模块忘了往 eslint 互依禁列里补一行 | **静默**：新模块变成「谁都可以依赖」，且规则随模块数增加持续衰减 | 把「加模块必补禁列」写进 `40-extend` 的闭环表，并在禁列旁留注释说明漏补是静默的 |
+| 代理前缀 `/api` 与前端源码目录 `api/` 撞车 | 只在 dev 模式整页白屏，报错却是 404 / ECONNREFUSED，离根因很远 | vite 代理加 `bypass`，按「是不是前端资源」分流；并用测试钉住 `shouldServeLocally` |