nx-sk 0.23.1 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,153 @@
 
 本文件格式参考 [Keep a Changelog](https://keepachangelog.com/)，中文正文。
 
+## 0.28.0 (2026-11-10)
+
+**全量 TypeScript 化：后端与前端源码统一为 `.ts/.tsx`；字段与模块改为注册表驱动。对外行为不变。**
+
+### Changed
+
+- **源码全量 TypeScript**：`src/**` 不再有 `.js/.jsx`；`pnpm build` 先用 `tsc -p tsconfig.build.json`
+  产出 `dist/**/*.js`（`.ts` 导入后缀在 emit 时改写），再把面板构建到 `dist/web/public`。
+- **字段收敛为穷举注册表**：服务端 `FIELD_BEHAVIOR` / `FIELD_SEAL`、前端 `FIELD_CONTROLS`
+  都是 `Record<FieldType, …>`；`FIELD_TYPES` 加一项而漏实现/漏控件，会直接编译失败。
+- **模块「目录即声明」**：`src/modules/<id>/index.ts` 自动装载，新增模块不再需要改注册表与 eslint 清单。
+- **前端只消费 `shared`**：类型与零依赖纯函数从 `src/shared/**` 引入，eslint 边界规则覆盖 `.ts/.tsx`，
+  继续拦住 `import '../../core/**'` 与 `import '../../modules/**'`。
+
+### Fixed
+
+- **导出 ZIP 时表格的敏感列按列定义解密**：此前 `plainValues` 只处理 `entrylist`，含敏感列的表格会带密文出包，
+  换机器后永久不可解（独立提交 `fc4b9e2`）。
+
+### 说明
+
+- 命令、HTTP 响应形状、面板文案与交互、`store.json` 格式均未变化；`engines.node` 仍是 `>=18.17`。
+- 贡献者：单测直接执行 `.ts` 需要 Node `>=22.18`；改了后端源码要重新 `pnpm build`。
+
+## 0.27.0 (2026-11-08)
+
+**表格字段重做：列头 ⋮ 属性菜单、行列都有抓手、去掉了那一整块「列设置」表单。**
+
+原来的表格能用，但长得像后台配置页：表格下面铺着一整块「列设置」，一列一行、七八个输入框
+（key / 名称 / 类型 / 汇总 / 单位 / 默认值 / 密文 / ←→×），而行与列的操作散在两端。
+这一版按 Notion 数据库的手感重排：**表头就是属性入口，操作都收在 hover 里，静止时这页只有数据**。
+
+### Changed
+
+- **列头 ⋮ 打开属性菜单**：列名 / 类型（含「计算列（JS）」）/ key / 单位 / 默认值 / 表尾统计 / 密文 /
+  下拉选项 / 公式，以及左移右移、左右插入、复制属性、删除属性。弹层按锚点定位，空间不够自动翻到上方。
+- **表头末尾 `＋`**：加列的入口长在列该长的位置；原来底栏那个「＋ 添加列」只在空表时出现。
+- **行抓手挪到左侧沟槽**：静止显示行号，hover 变成 `⋮`（在上/下方插入、复制、删除）+ `⠿`（拖动排序）。
+  原来行操作挤在行尾 78px 的操作列里,现在表格右侧干净了。
+- **表尾「新建一行」**：加行不用回工具栏；回车在最后一格仍然能续行。
+- **质感**：格子不再是「描边输入框」——无边框、无底色，只有 1px 网格线；hover 整行浮起，
+  focus 才在格子里显一圈极淡边界。表头小字灰色、计算列浅底、统计行加粗、数字等宽右对齐。
+- 删掉了整块「列设置」面板（`.tf-cols` / `.tf-colrow`），列定义现在只在列头弹层里改。
+
+### Fixed
+
+- **勾选列被撑成一整格黑块**：复选框套了给文本框用的 `.tf-input`（width/height 100%），
+  现在单独用 `.tf-check`（15px）。
+- **弹层跑到屏幕左上角**：行/列的 `⋮` 原本用 `display:none` 藏在 hover 里，键盘或脚本点开时
+  `getBoundingClientRect()` 全是 0。改成「常驻布局 + opacity 切换」，行号绝对定位叠在同一格上。
+
+## 0.26.0 (2026-11-08)
+
+**原始资料（`source`）改成真正的侧边栏；块头 / 面板标题整行都能拖。**
+
+它本来就有 master-detail 的骨架（左清单 / 右正文），但外面套的是「全屏遮罩 + 模态 dialog」：
+打开时整页被压暗、还被块的 `overflow: hidden` 裁掉一角——整理素材时看不见原文，
+而「整理」恰恰要求两边对着看。
+
+### Changed
+
+- `SourceDrawer` 用 `createPortal` 挂到 `document.body`，定位改为**窗口右侧通栏**
+  （`position: fixed`，宽 `min(720px, 46vw)`，窄屏 94vw），带一条柔和投影与轻微的滑入动画。
+- **去掉遮罩与 `aria-modal`**：改成 `role="complementary"`，左边条目仍然可读、可滚；
+  关闭走「关闭」按钮 / `Esc`（焦点仍然归还折叠条）。
+- 层级排好：侧边栏 45 < 弹窗 50，toast 提到 70（不会被侧边栏盖住）。
+- **块头、面板标题行整条都是抓手**（不再只靠那个 10px 的 `⠿`）：hover 给浅底、`⠿` 平时淡显
+  hover 变实、光标 `cursor: grab`——三件事一起说「这行能拖」。块体（输入区）仍然不能拖，
+  否则选词会变成搬块；面板行内按钮也不会触发拖动。
+
+### Fixed
+
+- **拖块不再「卡手」：改成插入式排序**（用户反馈「只能显示在可以显示的位置」）。
+  网格里全宽块只有 `x=0` 一个落点、半宽块只有两个，用引擎的自由拖拽时块只能在「合法格」
+  之间跳，还会被纵向压实实时吸回去——拖到哪儿都不对。现在：
+  - 拖动只表达**顺序**：拖到某块的上/下半，出现一条 2px 插入线（与表格搬行同一套语义），
+    松手按新顺序重新铺格（`repackBlocks`，**保留每块原来的宽度**）。
+  - 宽度仍是独立自由度：拖块的左右边缘改宽，所以「单列变多列」照旧成立。
+  - 拖动过程中不再有实时重排（引擎的 drag 已关掉），落点所见即所得。
+- **「拖拽有点难触发」的真因**：上一版把 `Block` 组件直接当成网格的子元素，而
+  `react-grid-layout` 靠 `cloneElement` + `ref` 给子元素注入定位与拖拽手柄——函数组件接不住
+  ref，按下时抛 `<DraggableCore> not mounted on DragStart`，拖动因此在 mousedown 就断了。
+  现在子元素回到原生 `div`（`.blk-cell`），块放在里面。
+
+## 0.25.0 (2026-11-08)
+
+**正文改成「按内容长」的文档：md 有多长就多高，界面去掉边框，读的内容回到第一眼。**
+
+上一版把正文块化了，但块高是固定的：md 正文被塞进一个 220px 的框里滚动——那还是「面板」的思路，
+不是「读文档」的思路。这一版把高度的决定权还给内容，并顺手把视觉收干净。
+
+### Changed
+
+- **块高由内容决定**：行高压到 8px 一档，用 `ResizeObserver` 量块里的内容（md 正文、附件列表、
+  清单/表格、自动增高的 textarea），显示高度 = max(存储的最小高, 内容高度)。内容删掉就缩回最小高。
+  - 存的 `h` 因此变成**最小高**：版式 JSON 描述「这个栏目怎么排」，不是「这一条内容有多高」——
+    后者每条记录都不一样，不该落盘（视图期算出来的高度会在回写时剥掉）。
+  - **只保留左右缩放手柄**：高度既然跟内容走，再叠一个手动高度只会互相打架（拖宽 → 内容重排 → 高度自己跟）。
+- **md 正文不再限高滚动**：`.md-preview` 去掉 `max-height: 340px / 560px`，阅读态连灰底也去掉，
+  正文直接落在页面上；工具行（字数 / 图片数 / 编辑）退到 hover 才出现。
+- **无边框**：新增 `--line`（rgba 8.5%）代替原来的实色分隔线；块与面板去掉边框与底色，
+  靠留白与字号分层；把手、字段 key、面板操作平时不出现，hover / 聚焦才浮出。
+- **现代控件**：输入框改成「无边框 + 浅底，focus 才显边界」；按钮/标签去掉浮雕投影，改为平色块 + hover 加深；
+  顶部 tab 扁平化（选中只加深底色）；浮层统一一层柔和投影。
+- **阅读优先的排版**：条目名抬到标题级（16px / 600，仍是就地可改的输入）；
+  「＋ 直接加字段」收成折叠项，不再常驻一行；块内正文字号 13px（工具条仍是 12px）。
+
+### Notes
+
+- 版式 JSON 的 `h` 语义变了（最小高 / 8px 一档），但**结构与读写口径不变**：
+  `section get --json` / `section update --layout` 照旧；老版式读进来会被夹到最小高，
+  视觉上相当于「内容多长就多长」，不需要迁移脚本。
+- 全局样式改动波及所有页面（条目 / 栏目 / 附件 / 导出 / 设置），逐页截图确认过没有退化。
+
+## 0.24.0 (2026-11-08)
+
+**条目正文块逻辑化：一个分组 = 一块面板，一个字段 = 面板里的一个块——能拖、能并排、窄屏自动折列。**
+
+过去正文是「分组小标题 + 自动填充的字段矩阵」：顺序由字段字典决定，想把「岗位」挪到「公司名称」
+右边、想让两块并排、想让长文独占一整行，都只能去改字段字典。现在**版式是独立的一份 JSON**
+（`section.layout`），拖动即改、自动落盘，与「字段值」是两条保存链——拖一下版式不会把没填完的值一起提交。
+
+### Added
+
+- **块面板**：每组一块面板，面板里每个字段一个块（块头 = 标签 + 密文/填写策略标签 + 字段 key）。
+  底层用 `react-grid-layout`（MIT）做网格引擎：拖块头 `⠿` 搬块、拖右下角改宽高、单列变多列、
+  窄屏按断点自动折成一列。碰撞 / 回弹 / 折行都交给引擎，**不自己实现面板引擎**——
+  这一层最容易出错，也最没有复用价值。
+- **版式单独存**（`section.layout`）：
+  `{v, mode, panels[], groups{分组:{collapsed, layouts{断点:[{i,x,y,w,h}]}}}}`。面板顺序、折叠态、
+  每个块的位置/宽度/高度都在里面，`i` 就是字段 key；坐标是列单位（lg 12 / md 10 / sm 6 / xs 4 / xxs 2）。
+- **结构变了版式自愈**（幂等，读写两条路都过一遍）：删字段 → 对应块消失且不留空位；加字段 →
+  接到该组最底部（不插队打散已排好的版式）；删分组整块移除、新分组接末尾。
+  没存过版式 = 按默认编排铺一遍（窄字段半列、宽字段整行、窄屏单列）。
+- **CLI 对等**：`section get --json` 带出**已按当前字段对齐**的 `layout`；
+  `section update --layout @layout.json` 整体写版式、`--clear-layout` 回到默认编排。
+  端到端冒烟把「面板走的那条 HTTP PATCH」与 CLI 两头都钉住了。
+- **落位吸附**：半宽的块从「缝上」（x=3 这种）吸附到 0 / 6 这类档位，两块并排才齐；
+  用户特意拉的自由宽度（除不尽列数，如 5 列）保持原样，不被「自动摆正」。
+- **表单视图**：一键切回单列流式（长文 `md` / 表格字段多时更好读），版式保留、切回来即恢复。
+
+### Notes
+
+- 新增依赖 `react-grid-layout@^2.3.0`（含 `react-draggable` / `react-resizable`）；构建产物 +约 105KB gzip
+  在条目视图的懒加载分片里，首屏不受影响。
+- 版式**不影响**条目值、完整度与 CLI 读写口径；老 store 没有 `layout` 也能直接用（读一次就按默认编排渲染）。
+
 ## 0.23.1 (2026-11-05)
 
 ### Added

package/README.md

@@ -11,13 +11,26 @@ nx-sk serve          # 打开面板（http://127.0.0.1:7866）
 
 ## 安装
 
+**要求 Node.js >= 18.17。** 包内是构建好的 `dist/`（纯 JS），运行时不需要 TypeScript。
+
+```bash
+npm i -g nx-sk        # 命令名就是包名
+nx-sk version
+nx-sk serve           # 打开面板
+```
+
+## 开发
+
+**开发/测试需要 Node >= 22.18**（单测用 `node --test` 直接跑 `.ts`，依赖 Node 原生类型剥离）；
+运行 CLI 与面板仍只需 >= 18.17。改了后端要重新构建——`dist/` 是运行时唯一入口。
+
 命令名就是包名。**推荐做成全局垫片**（全局 node_modules 里是指向本项目的软链，
 改代码立刻生效，不用重新安装）：
 
 ```bash
 cd <本项目>
 pnpm install          # 只为构建面板；CLI 侧零依赖
-pnpm run build        # 产出 src/web/public，serve 才有面板可服务
+pnpm run build        # tsc → dist/**/*.js，vite → dist/web/public
 npm link              # → 全局多了 nx-sk / nx-sk.cmd / nx-sk.ps1
 nx-sk version         # 从任何目录都能跑
 nx-sk serve           # 打开面板
@@ -45,7 +58,7 @@ nx-sk serve           # 打开面板
 >
 > 别忘了 `chmod +x ~/.local/bin/nx-sk`。验证：`cd / && nx-sk version`。
 
-> 不想污染全局也行：`node bin/nx-sk.mjs <子命令>` 等价，或 `npx --no-install . <子命令>`。
+> 不想污染全局也行：先 `pnpm build`，再 `node bin/nx-sk.mjs <子命令>`，或 `npx --no-install . <子命令>`。
 
 ### skill：用**软链垫片**（推荐）
 
@@ -516,9 +529,9 @@ pnpm test        # = lint + build + 冒烟 + 单测
 | --- | --- |
 | `bin/nx-sk.mjs` | 唯一入口，只转发 argv + 兜异常 |
 | `src/core/` | 零业务语义：paths / errors / store / fsx / crypto / vault / fields / attachments / render / ids / open |
-| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务) + `view.jsx`(面板) |
+| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务)。**不声明视图** |
 | `src/runtime/` | registry / spec / cli / api / server —— 装配层，不写业务 |
-| `src/web/frontend/` | React 壳 + 组件 + 视图注册表 |
+| `src/web/frontend/` | React 壳 + 组件 + `modules/<域>/view.jsx` + 视图注册表（视图只住这里） |
 | `assets/nx-sk/` | 随包分发的 skill（SKILL.md + references/） |
 | `tests/unit/` · `tests/smoke.mjs` | 一致性断言 + 端到端冒烟 |
 
@@ -553,7 +566,7 @@ agent 手册** —— 它写在创建本项目的脚手架 skill `server-cli-web
 | 把打码值当成新值写回去 | 密钥字段被写成 `sk-1****cdef` 这串掩码，**原凭据永久丢失** | 写入前比对掩码：相等就当成「未改动」保留原密文；含 `******` 的值直接拒绝 |
 | 删条目/栏目没有留退路 | 误删即不可逆；这是用户的**唯一一份**个人信息 | 破坏性写操作一律先 `transfer export` 导出，导出的包就是唯一回退手段 —— 不另设本地备份模块 |
 | store.json 解析失败就当空库继续 | 下一次写入把用户数据永久覆盖 | 先把损坏文件改名为 `store.json.corrupt-<时间>.json`，再降级返回空结构 |
-| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 同时覆盖 `view.jsx`，禁掉 `node:*` / `core` / `runtime` / `service.js` |
+| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 覆盖整个 `src/web/frontend/**`（视图都在这里），禁掉 `node:*` / `core` / `runtime` / `service.js` |
 | 新增模块忘了往 eslint 互依禁列里补一行 | **静默**：新模块变成「谁都可以依赖」，且规则随模块数增加持续衰减 | 在禁列旁留注释说明它是**逐模块枚举**的、漏补是静默的；加模块前先读 `eslint.config.js` |
 | 代理前缀 `/api` 与前端源码目录 `api/` 撞车 | 只在 dev 模式整页白屏，报错却是 404 / ECONNREFUSED，离根因很远 | vite 代理加 `bypass`，按「是不是前端资源」分流；并用测试钉住 `shouldServeLocally` |
 | 把「上传 / 选择」放到附件中心，再让条目去引用 | 条目里看不到上传入口，用户不知道该在哪儿加文件；附件中心还被迫预定义分类与槽位，跟栏目脱节 | **上传 / 选择发生在栏目条目里**（`file` 字段的值 = 附件 id）；附件中心由栏目驱动、只做统一展示与库存管理，**不预定义分类、不做指派** |

package/assets/nx-sk/SKILL.md

@@ -193,6 +193,11 @@ nx-sk file open f_xxxx                          # 系统默认程序打开原件
 - 附件中心：**「清理未引用（N）」**一键删掉所有没人引用的附件（判据与「未引用」筛选片同一套）；
 - 条目表单：**保存按钮固定在右上角**，有改动时顶栏出现「N 处改动未保存 · 保存」，
   长栏目滚到一半也看得见（底部也还有一个）。
+- **正文是块面板**：一个分组一块面板、一个字段一块，拖块头整行换顺序、拖左右边缘改宽（可并排成多列）；
+  高度**跟内容走**（md 正文/附件/清单有多长就多高，不在块内滚）；版式（`section.layout`）自动保存，
+  与字段值两条保存链。想用命令改版式：
+  `nx-sk section get <栏目> --json`（读，已按当前字段对齐）/ `section update <栏目> --layout @layout.json`
+  / `section update <栏目> --clear-layout`（回默认编排）。形状与自愈规则见 [[10-sections-entries]] 第六节。
 
 求职条目里的「简历附件 / 头像图片 / 成绩单 / 证书扫描件」是 `file` 字段，
 它的值是**附件 id 的列表**——一个字段可以挂**多个**附件（简历多版本、头像多张）
@@ -278,7 +283,7 @@ nx-sk source update <条目> --id <itemId> --mapped 字段key   # 标注「这
 nx-sk source ensure                    # 给老栏目补上这个字段（模板是后加的，老栏目没有）
 ```
 
-面板上：条目表单底部一条**折叠条**「原始资料 · N 条」，点开是右侧抽屉（左清单、中正文），
+面板上：条目表单底部一条**折叠条**「原始资料 · N 条」，点开是右侧**侧边栏**（左清单、中正文；不遮不挡，左边条目还能读），
 文件可拖进去（也给了「选择文件」按钮与粘贴框——拖拽不能是唯一入口，WCAG 2.2 AA）。
 三条纪律：**原文不改写**、**不确定就留空**、**敏感内容不进袋**（袋是明文的；
 密码走场景栏目的密文字段，不进袋）。

package/assets/nx-sk/references/10-sections-entries.md

@@ -7,7 +7,7 @@
 ```
 store.json（~/nx-sk/store.json 或 $NX_SK_STORE）
 ├─ settings                 全局配置（可读 JSON/Markdown 导出见 60-transfer）
-├─ sections[]               栏目：id / title / order / template / titleField / groups[] / fields[]
+├─ sections[]               栏目：id / title / order / template / titleField / groups[] / fields[] / layout
 └─ entries[]                条目：id(e_xxx) / section / title / tags[] / values{字段key: 值} / 时间戳
 ```
 
@@ -171,7 +171,8 @@ nx-sk section update job --fields @fields.json
 > 还能有**计算列**（JS 表达式）与**表尾统计**。最根本的差别是**结构归数据**：列定义、行、公式、
 > 统计配置全部存在**条目值里**（`{v, columns, rows, totals?, summary?}`），字段定义里的 `columns`
 > 只是「新建时的初始列」。所以「这一条想多一列」不必改 schema，也不影响同栏目其它条目。
-> 面板上**行与列都能拖**：拖表头搬列、拖行尾的 ⠿ 搬行（松手前有插入线）。
+> 面板上**列头有 ⋮ 属性菜单**（改名 / 换类型 / 单位 / 汇总 / 默认值 / 密文 / 选项 / 公式 + 左右插入 / 复制 / 删除），
+> 表头末尾有 `＋` 加列；**行与列都能拖**（拖表头搬列、拖行左缘的 ⠿ 搬行，松手前有插入线）。
 >
 > ```bash
 > nx-sk section update mysec --add-field '{"key":"tasks","label":"任务表","type":"table"}'
@@ -187,7 +188,7 @@ nx-sk section update job --fields @fields.json
 > 杂乱资料（邮件、截图、PDF 摘录、手抄的表）先**原样**丢进袋里，之后由 agent 或人
 > 按字段字典整理进上面的字段——「先乱入、后整理」因此成立：没有这个袋子，用户只有
 > 把乱数据硬塞进结构化字段（把结构搞脏）或干脆不存（信息丢了）两个坏选择。
-> - 面板上：条目表单底部一条**折叠条**「原始资料 · N 条」，点开是右侧抽屉——
+> - 面板上：条目表单底部一条**折叠条**「原始资料 · N 条」，点开是右侧**侧边栏**（不遮不挡，左边条目还能读）——
 >   左清单、中间正文，文件可拖进去（也给了「选择文件」按钮与粘贴框：拖拽不能是唯一入口）。
 > - CLI：`nx-sk source list / get / add / update / remove / ensure`（细节见 `sk-source` skill）。
 > - 三条纪律：**原文不改写**（整理结果写进字段或新的一条）、**不确定就留空**、
@@ -272,11 +273,52 @@ nx-sk entry get 张三
 
 `nx-sk serve` → 每个栏目一个 tab，共用同一个条目视图：
 
-- 左侧条目列表（带完整度），右侧按分组渲染的字段表单；
+- 左侧条目列表（带完整度），右侧**按分组渲染的块面板**：一个分组 = 一块面板，一个字段 = 面板里的一个块；
+- **块布局（默认）**：拖**块头整行**（不用对准 ⠿）**换顺序**——拖到某块的上/下半就插到它前面/后面；
+  拖块的**左右边缘**改宽度（单列可变多列）；拖**面板标题行**换面板顺序。
+  块可以并排，窄屏自动折成一列（响应式由网格引擎按断点算，不是手写媒体查询）。
+  **高度跟内容走**：`md` 正文、附件列表、清单表格有多长就多高，不在块内滚（阅读优先）；删掉内容再缩回最小高。
+  **版式改动自动保存**，与字段值的「保存」互不影响——拖一下版式不会把没填完的值一起提交；
+- **表单视图**：同一份数据按字段顺序单列铺开（长文 `md`、`table` 字段多时更好读）；切回块布局版式原样恢复；
 - **「栏目」页的「编辑」弹窗能改整个结构**：分组可新增 / 改名（含换 id）/ 上下挪 / 删（空的才让删），
   字段可改标签、类型、分组、提示、必填策略、组内上下挪、删除 —— 一次改动一次落盘；
 - 密文字段默认显示原文；「打码显示（投屏/截图时用）」勾选等价于 `--mask`（选择持久化在 localStorage）；
 - 保存是 **PATCH**：只有被你改动过的字段才会发出去（面板会显示「N 处改动」）；
 - 每个页面底部会派生显示该模块的 CLI 等价命令（可点击复制）。
 
+### 版式（`section.layout`）：**显示关系单独存**
+
+「有哪些字段」（字段字典）与「这些块怎么摆」（版式）是两件事，所以版式是栏目上**另一份 JSON**：
+
+```json
+{
+  "v": 1,
+  "mode": "grid",                       // grid = 面板块 · flow = 单列表单
+  "panels": ["basic", "contact"],       // 面板（分组）顺序
+  "groups": {
+    "basic": {
+      "collapsed": false,
+      "layouts": {                      // 按断点各一份，坐标是**列单位**
+        "lg": [{ "i": "name", "x": 0, "y": 0, "w": 6, "h": 2 }]
+      }
+    }
+  }
+}
+```
+
+- `i` = 字段 key；`x / y / w / h` 是列单位（`lg` 12 列、`md` 10、`sm` 6、`xs` 4、`xxs` 2）。
+  `h` 是**最小高**（一档 8px + 10px 间距）：实际显示高度 = max(最小高, 内容量到的高度)，
+  所以同一份版式套在不同内容上都能读。底层是 `react-grid-layout` 的网格形状，面板只管喂 JSON；
+  碰撞、回弹、折列都由引擎算。
+- **结构变了版式自愈**（幂等，读写两条路都过一遍）：删字段 → 对应块消失且不留空位；
+  加字段 → 接到该组最底部（不插队打散已排好的版式）；删分组 → 整块移除；新分组 → 面板接在末尾。
+- 没存过版式 = 按默认编排铺一遍（窄字段半列、宽字段整行，窄屏单列），**不是**没有版式。
+- 版式不参与完整度、不影响条目值；`flow` 模式下版式仍保留。
+
+```bash
+nx-sk section get job --json                       # 含 layout（已按当前字段对齐）
+nx-sk section update job --layout @layout.json     # 整体写版式（面板拖完回写的就是这条）
+nx-sk section update job --clear-layout            # 回到默认编排（不是删成 null）
+```
+
 面板上没有 CLI 做不到的事——两边共享同一套 action 声明。

package/assets/nx-sk/references/15-special-fields.md

@@ -13,11 +13,11 @@
 
 | type | 值形状 | 结构（列）归谁 | 面板怎么编 | 读它 |
 | --- | --- | --- | --- | --- |
-| `table` | `{v, columns, rows, totals?, summary?}` | **数据自己**（字段定义只给初始列） | 表格控件 + 「列设置」；**拖表头搬列、拖行尾 ⠿ 搬行** | `entry table` / `entry get` |
+| `table` | `{v, columns, rows, totals?, summary?}` | **数据自己**（字段定义只给初始列） | 表格控件：**列头 ⋮ 属性菜单**、表头 ＋ 加列；拖表头搬列、拖行左缘 ⠿ 搬行 | `entry table` / `entry get` |
 | `entrylist` | `[{列key: 值}, …]` | 字段字典的 `fields` | 密集迷你表（直接增删行，**拖 ⠿ 调行序**） | `entry get` |
 | `md` | 一段 markdown 字符串 | — | 图文编辑器（Ctrl+V 贴图） | `entry get`（图片还原成路径） |
 | `file` | `[附件id, …]` | 字段字典的 `kind` / `maxItems` | 附件选择器（上传 / 从库里选） | `entry get`（附件名 + 物理路径） |
-| `source` | `[{id, kind, name, text\|fileId\|url, addedAt, …}]` | 内置（每个栏目自带一个） | 底部折叠条 → 右侧抽屉 | `source get` |
+| `source` | `[{id, kind, name, text\|fileId\|url, addedAt, …}]` | 内置（每个栏目自带一个） | 底部折叠条 → 右侧侧边栏 | `source get` |
 | `secret` | 一个字符串（落盘是密文） | — | 输入框 | `key get` / `entry get` |
 
 共同点：**写入即校验**（不合法就整条拒绝，不会存半条）、**空值有明确语义**、
@@ -120,20 +120,33 @@
 默认值只在**新增行**时用（面板「添加行」按列的 `default` 预填），不会回头改已有行；
 字段级的默认是：初始列 + 表尾自动统计（数字 sum / 勾选 countTrue）+ 列类型默认 text。
 
-### 面板上怎么调顺序（拖）
+### 面板上怎么改结构、怎么调顺序
 
-排序是表格最常见的编辑动作之一，所以**行与列都能拖**，不用去点箭头：
+**列管理在列头上**：鼠标移到表头 → 右侧出现 `⋮` → 打开这一列的属性菜单：
 
-- **搬列**：直接拖**表头**（表头里没有输入框，不会跟选词打架）；「列设置」里每列前面的 ⠿
-  也能拖，效果一样。
-- **搬行**：拖行尾的 ⠿。整行 `draggable` 不这么做——那会跟单元格里选文本冲突
-  （想选一段字结果把行拖走了），所以把手是唯一的拖拽入口。
-- 松手前会有一条**插入线**落在上/下半（行）或左/右半（列）的位置：线在哪就插到哪。
-  只高亮「这一行」是做不到这件事的。
-- ↑↓ / ←→ 保留（鼠标悬停在行上才浮出来），键盘与「就挪一格」的场景仍然走得通；
-  行内操作键统一是 16px 的小图标键——密集表里的按钮不该抢内容的注意力。
+| 菜单里能做什么 | 说明 |
+| --- | --- |
+| 列名 / 类型 | 就地改；改成「计算列（JS）」后填公式 |
+| key / 单位 / 默认值 | key 是公式里引用的名字（改 key 会连值一起搬） |
+| 统计 | 表尾这一格怎么算（求和 / 平均 / 计数 / 不统计…） |
+| 密文 | 这一列的值以 AES-256-GCM 密文落盘 |
+| 选项 | `select` 类型的候选项，逗号分隔 |
+| 左移 / 右移 | 挪一格 |
+| 向左 / 向右插入列 | 在它旁边插一列空列 |
+| 复制属性 | 连**值**一起复制出一列（`xxxCopy`） |
+| 删除属性 | 连值一起删（只删定义会留下「没有列的数据」） |
+
+表头**末尾有一个 `＋`**：加列就在列该长的位置，不用回头去工具栏找。
+
+排序：行与列都能拖，拖到哪儿有一条**插入线**告诉你会插在哪：
+
+- **搬列**：直接拖**表头**（表头里没有输入框，不会跟选词打架）。
+- **搬行**：拖行**左侧沟槽**的 ⠿（hover 时行号会变成 `⋮`（行菜单：上下插入 / 复制 / 删除）+ `⠿`）。
+  整行 `draggable` 不这么做——那会跟单元格里选文本冲突（想选一段字结果把行拖走了）。
+- 表尾有一整行「**新建一行**」：加行不用回工具栏；回车在最后一格也能直接续一行。
+- 行内操作统一是小图标，hover 才出现——密集表里的按钮不该抢内容的注意力。
 
-`entrylist` 的行同理（拖 ⠿），删除键也从「一颗正常大小的按钮」换成了小图标键。
+`entrylist` 的行同理（拖 ⠿），删除键也是小图标键。
 
 ### 常见错 → 改法
 
@@ -173,7 +186,7 @@
 - 每个非 KV 栏目自带一个：杂乱资料先**原样**入袋（不改写），之后按字段字典整理。
 - **`text` 的底层是 markdown**——聊天记录图文混排，图和文不能分开存：
   正文里直接写 `![说明](f_xxx)`（附件库的图）或 `![说明](https://…)`（外链图）；
-  面板抽屉里图片 Ctrl+V / 拖进编辑器就自动上传并插入引用。
+  面板侧边栏里图片 Ctrl+V / 拖进编辑器就自动上传并插入引用。
   普通文字本来就是合法 markdown，老数据不用迁移。
 - 不计完整度（`fill: optional`）；袋里是明文，**敏感内容不要进袋**。
 

package/assets/sk-source/SKILL.md

@@ -94,7 +94,7 @@ nx-sk source add <条目> --url "https://qcloud.sicau.edu.cn/login"
 ```
 
 - `--file` **默认复制不搬走**原件（这是「加一条资料」，不是 `file add` 的搬运语义）。
-- 一次要收很多份：面板里在「原始资料」抽屉中**多选文件**拖进去，或用 `--file` 重复调用。
+- 一次要收很多份：面板里在「原始资料」侧边栏中**多选文件**拖进去，或用 `--file` 重复调用。
 - 文件分发细则（PDF 怎么拆、截图怎么批量进、表格怎么变成清单行）见 [[20-intake]]。
 
 ### 第 2 步：读袋子
@@ -160,7 +160,7 @@ nx-sk section dump <栏目> --json         # 完整度与未填清单（袋子
 ## 面板里怎么用
 
 条目表单底部有一条**折叠条**「原始资料 · N 条」（暂存区不该在日常填表时占地方）。
-点开是右侧抽屉：左边清单、中间正文。
+点开是右侧侧边栏：左边清单、中间正文（不遮挡条目）。
 
 - 拖文件进左栏 → 自动上传并入袋
 - 「＋ 选择文件」按钮 → 同样的事（**拖拽不是唯一入口**：WCAG 2.2 AA 要求键盘/单指针也能完成）

package/assets/sk-source/references/20-intake.md

@@ -43,7 +43,7 @@ nx-sk source add <条目> --file "D:\资料\用户指南.pdf" --name "平台用
 
 ## 批量进一批文件
 
-面板最快：条目表单底部「原始资料」折叠条 → 抽屉 → 「＋ 选择文件」（可多选）
+面板最快：条目表单底部「原始资料」折叠条 → 右侧侧边栏 → 「＋ 选择文件」（可多选）
 或直接把一批文件拖进左栏。
 
 CLI 逐个加（每条一次调用）：

package/bin/nx-sk.mjs

@@ -1,7 +1,25 @@
 #!/usr/bin/env node
-// nx-sk 的唯一可执行入口：只做两件事——转发 argv、兜住未捕获的异常。
-// 所有命令分发都在 src/runtime/cli.js（那里才是命令表）。
-import { runCli } from '../src/runtime/cli.js';
+// nx-sk 的唯一可执行入口：转发 argv、兜住未捕获的异常。
+// 所有命令分发都在 dist/runtime/cli.js（那里才是命令表）——只跑构建产物，
+// 不在运行时做 TypeScript 类型剥离（Node 对 node_modules 下的 .ts 直接拒绝）。
+//
+// 首次从源码仓库直接跑、或改了后端还没构建时，dist 不存在：给一句能照做的提示，
+// 而不是把 ERR_MODULE_NOT_FOUND 的栈甩给用户。
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const cliUrl = new URL('../dist/runtime/cli.js', import.meta.url);
+
+if (!existsSync(fileURLToPath(cliUrl))) {
+  process.stderr.write(
+    'nx-sk: 找不到构建产物 dist/runtime/cli.js。\n'
+      + '源码仓库需要先构建：pnpm build（npm run build）——它会先 tsc 产出 dist，再构建面板。\n'
+      + '如果你是用 npm 全局安装的，这说明包不完整，请重装：npm i -g nx-sk。\n',
+  );
+  process.exit(1);
+}
+
+const { runCli } = await import(cliUrl.href);
 
 runCli(process.argv.slice(2)).catch((err) => {
   const message = err && err.message ? err.message : String(err);

package/{src → dist}/core/argsafe.js

@@ -12,8 +12,7 @@
 // 又会拦住用 --data 写入的合法 CRLF 多行值（高假阳性）；LF 截断后则与合法单行值
 // 完全不可区分。可靠的信号不存在，因此只能提供可靠通道 + 修好通道本身。
 import { readFileSync } from 'node:fs';
-import { badInput } from './errors.js';
-
+import { badInput } from "./errors.js";
 /**
  * `--data` 的值：JSON 字面量 / `@文件路径` / `-`（stdin）。
  *
@@ -21,33 +20,34 @@ import { badInput } from './errors.js';
  * 「读 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
+    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() === '-';
+    return String(raw ?? '').trim() === '-';
 }
-
 function parseJson(text, src) {
-  try {
-    return JSON.parse(text);
-  } catch (e) {
-    throw badInput(`--data 不是合法 JSON（${src}）: ${e.message}`);
-  }
+    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/... 形式的路径`);
-  }
+    try {
+        return readFileSync(p, 'utf8');
+    }
+    catch (e) {
+        // 路径写法是最常见的坑：Git Bash 的 /tmp 在 node 侧看不到（真实事故 ENOENT），
+        // 所以错误里直接把 Windows 路径形式写出来，省掉一轮排查。
+        throw badInput(`读取文件失败: ${p}（${e.message}）—— Windows 上请用 C:/Users/... 形式的路径`);
+    }
 }
-