nx-sk 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +85 -0
  2. package/README.md +85 -5
  3. package/assets/nx-sk/SKILL.md +65 -15
  4. package/assets/nx-sk/references/00-design.md +3 -3
  5. package/assets/nx-sk/references/10-sections-entries.md +18 -3
  6. package/assets/nx-sk/references/15-special-fields.md +178 -0
  7. package/assets/nx-sk/references/40-files.md +44 -8
  8. package/assets/sk-needdo/SKILL.md +2 -0
  9. package/assets/sk-source/SKILL.md +11 -1
  10. package/assets/sk-source/references/20-intake.md +3 -0
  11. package/package.json +1 -1
  12. package/src/core/attachments.js +17 -4
  13. package/src/core/fields.js +138 -13
  14. package/src/core/render.js +58 -4
  15. package/src/core/store.js +5 -3
  16. package/src/core/vault.js +17 -8
  17. package/src/modules/entries/index.js +27 -0
  18. package/src/modules/entries/service.js +340 -21
  19. package/src/modules/sections/index.js +22 -0
  20. package/src/modules/sections/service.js +161 -4
  21. package/src/modules/sections/view.jsx +441 -56
  22. package/src/modules/transfer/service.js +13 -0
  23. package/src/shared/table.js +884 -0
  24. package/src/web/frontend/components/fieldEditor.jsx +8 -1
  25. package/src/web/frontend/components/tableField.jsx +451 -0
  26. package/src/web/frontend/styles.css +134 -0
  27. package/src/web/public/assets/{files--aIy09Sp.js → files-vbBBJ5q_.js} +1 -1
  28. package/src/web/public/assets/{index-CEIiV0jA.css → index-CYX-3oPr.css} +1 -1
  29. package/src/web/public/assets/{index-BWIrglCf.js → index-Czcw5Khj.js} +2 -2
  30. package/src/web/public/assets/{view-Bt8MZAtu.js → view-B3IpBaPq.js} +1 -1
  31. package/src/web/public/assets/{view-Bt7O8gS_.js → view-C2PCebaC.js} +1 -1
  32. package/src/web/public/assets/view-Dlnt7qN2.js +40 -0
  33. package/src/web/public/assets/{view-0jlrnuBr.js → view-DzlhjD91.js} +1 -1
  34. package/src/web/public/assets/view-PNU16Ybm.js +3 -0
  35. package/src/web/public/index.html +2 -2
  36. package/src/web/public/assets/view-1SYBZ3dg.js +0 -1
  37. package/src/web/public/assets/view-CjX_ywS7.js +0 -36
@@ -37,7 +37,43 @@
37
37
  - 所有写命令都支持 `--dry-run`;`file remove` 连物理原件一起删**不可撤销**——
38
38
  只想「拿出原件、库里留着」应该用 `file restore --copy`。
39
39
 
40
- ## 三、一键清理未引用的附件(孤儿附件)
40
+ ## 三、三种「正式引用」(cleanup 与「未引用」判同一套)
41
+
42
+ 附件算不算「已引用」,**判据只有一套**,附件中心的「未引用」筛选与 `file cleanup`
43
+ 都用它(`fileReferences` 为空 = 未引用)。三种引用方式都算数:
44
+
45
+ | 引用方式 | 在哪 | 典型场景 |
46
+ | --- | --- | --- |
47
+ | `file` 字段值里有它的 id | 条目的 `values.<file字段>` | 简历 / 头像 / 成绩单挂条目上 |
48
+ | `md` 正文里写了 `![说明](f_xxx)` | 图文字段正文 | SOP 截图、图文笔记 |
49
+ | `source` 袋里有 kind=`file` 的 item 指着它 | 条目的原始资料袋 | **溯源**:字段值是从这份原件整理出来的 |
50
+
51
+ 第三种是溯源的锚点:字段值会过时,「它是从哪份原件来的」必须永远能反查——
52
+ 所以袋里的原件**受保护**:cleanup 不删、`transfer export` 随包带走、
53
+ `file get` 能反查到「条目 / 原始资料」。
54
+ 反过来,一条附件三种引用都没有,就是真孤儿——`file cleanup` 会连物理原件一起删(不可撤销)。
55
+
56
+ ### 「保存这个文件里的 xx」:先挂原件,再写字段
57
+
58
+ 信息来自一份文件(图片 / PDF / Word…)时,**第一步是把原件收进库、挂到条目上**,
59
+ 第二步才是把内容抄进字段。顺序反了,原件随手一放(桌面、下载目录、对话里),
60
+ 被移动或清理之后字段就成了无源之水。
61
+
62
+ ```bash
63
+ # ① 原件进库 + 挂条目(两种落点,判据见上表)
64
+ nx-sk source add <条目> --file "D:\扫描\成绩单.pdf" --name "教务处成绩单" # 不好区分 / 先乱入:进袋
65
+ nx-sk file add --path "D:\扫描\成绩单.pdf" && nx-sk entry update 张三 --set 成绩单=f_xxx # 有贴切 file 字段:直接挂
66
+ # ② 抄内容进字段(照字段台账的 key/label 写,别编字段名)
67
+ nx-sk entry update 张三 --data '{"绩点":"3.6/4.0"}' --dry-run # 先试运行
68
+ # ③ 留痕:这条袋资料已整理到哪个字段(下次同步不重复)
69
+ nx-sk source update 张三 --id s_xxx --mapped gpa
70
+ ```
71
+
72
+ - 扫描件先 OCR 再抄(见主文档「什么时候不用」);OCR 拿不准的值**留空**,
73
+ 在袋里那条的 `--note` 里写明疑点——原件挂上了,随时能回看。
74
+ - 第 ③ 步的 `--mapped` 与双向同步见 `sk-source` skill。
75
+
76
+ ## 四、一键清理未引用的附件(孤儿附件)
41
77
 
42
78
  附件库是「导入即进库」:批量导入 SOP 截图、临时传一份再删,都会留下**没人引用的原件**——
43
79
  既占空间,又在附件中心混在真资料里。逐个删是折磨。
@@ -47,13 +83,13 @@ nx-sk file cleanup --dry-run # 先看会删哪些(名字 / 体积 / 物理
47
83
  nx-sk file cleanup # 真删:物理原件一并删除,不可撤销
48
84
  ```
49
85
 
50
- - 判据与「未引用」筛选片**完全同一套**:没有任何条目的 `file` 字段引用它、正文里也没有引用它的图。
51
- 两套判据会出现「筛选片里看不到、清理却删了」这种吓人的不一致。
86
+ - 判据与「未引用」筛选片**完全同一套**:没有任何条目的 `file` 字段引用它、正文里没有引用它的图、
87
+ 资料袋里也没有指着它的 item。两套判据会出现「筛选片里看不到、清理却删了」这种吓人的不一致。
52
88
  - 被引用的附件**一律不动**;同一个原件可以被多条条目共享,所以「已被引用」不是删除理由。
53
89
  - 不可撤销:要留底就先 `nx-sk transfer export`。
54
90
  - 面板上:附件中心工具条有「清理未引用(N)」,点了弹确认,报清数量。
55
91
 
56
- ## 四、导入:默认移动,`--copy` 才复制
92
+ ## 五、导入:默认移动,`--copy` 才复制
57
93
 
58
94
  ```bash
59
95
  nx-sk file add --path "D:\简历\张三-简历.pdf" # 默认把原件**移动**进库(原件不再留在原地)
@@ -66,7 +102,7 @@ nx-sk file add --path C:\扫描\成绩单.pdf --tags 成绩单 --note "教务处
66
102
  - 同 sha256 的文件直接复用已有记录(返回 `duplicated`),不会重复占空间。
67
103
  - `file add --dry-run` 只计算落点与校验,不移动、不写台账。
68
104
 
69
- ## 五、链接:`file` 字段值 = 附件 id 的**列表**(可挂多个)
105
+ ## 六、链接:`file` 字段值 = 附件 id 的**列表**(可挂多个)
70
106
 
71
107
  条目**不复制文件**,只存附件 id。把 id 写进栏目里 `file` 类型的字段,链接就建立了;
72
108
  **一个字段可以挂多个附件**(简历多个版本、头像多张、证书多份),值是 id 的数组:
@@ -90,7 +126,7 @@ nx-sk file get f_bbb
90
126
  - 老数据里存的**单个 id 字符串**原样兼容:读、反查、搜索、面板编辑都按「单元素列表」处理,
91
127
  不需要迁移;下一次在面板里编辑该字段保存后,会统一成数组。
92
128
 
93
- ## 六、还原(可逆)
129
+ ## 七、还原(可逆)
94
130
 
95
131
  ```bash
96
132
  nx-sk file restore f_xxxx # 移回**原始位置**并撤销台账(默认)
@@ -106,7 +142,7 @@ nx-sk file restore f_xxxx --to "D:\资料" # Web 上传件没有原始
106
142
  - Web 上传进来的附件没有「原始位置」,还原时必须给 `--to`。
107
143
  - 还原/删除都不留本地备份;删之前先 `transfer export` 导一份——见 `60-transfer`。
108
144
 
109
- ## 七、Web 面板
145
+ ## 八、Web 面板
110
146
 
111
147
  `nx-sk serve` → 顶部「附件」页:
112
148
 
@@ -133,7 +169,7 @@ nx-sk file restore f_xxxx --to "D:\资料" # Web 上传件没有原始
133
169
  > 附件 id 是**全局唯一**的:同一个原件被两个条目挂上,两边指的是同一条记录。
134
170
  > 「已被 N 处引用」说的就是这件事,不是「不能选」。
135
171
 
136
- ## 八、看不到 `file` 上传字段 / 条目里解析不到附件
172
+ ## 九、看不到 `file` 上传字段 / 条目里解析不到附件
137
173
 
138
174
  1. **栏目里没有这类字段** —— 栏目字段台账是**持久化数据**:栏目实例化时深拷贝模板字段,
139
175
  此后独立演化,模板**后来**新增的字段不会自动回溯到已建栏目。用
@@ -20,6 +20,8 @@ description: 把用户随手丢来的混乱数据(一段话、聊天记录、
20
20
  3. **原文不丢。** 杂乱的原件先丢进栏目自带的「原始资料」袋(`source` 字段),
21
21
  文件进附件库、长文进 `md` 字段、链接原样留在链接字段。
22
22
  摘要可以重写,原文不能只剩摘要 —— 收件箱的第一承诺是「收进来」,不是「总结掉」。
23
+ 袋里的文件**算已引用**:`file cleanup` 不会删它、导出随包走——先入袋没有代价,
24
+ 不入袋的原件躺在库外,丢了没有任何机制能拦。
23
25
 
24
26
  ## ⚠️ 每个栏目都自带「原始资料」袋(source 字段,先乱入后整理)
25
27
 
@@ -21,6 +21,15 @@ description: 在 nx-sk 的栏目里做「原始资料 ↔ 结构化字段」的
21
21
  3. **敏感内容不进袋。** 袋是**明文**的(不加密),密码/token 走「密钥」栏目或 `sensitive` 字段。
22
22
  往袋里贴明文密码 = 把凭据从密文降级成明文,这是不可逆的降级。
23
23
 
24
+ ## 铁律第 0 条:文件先入袋,再谈整理
25
+
26
+ **用户丢来一个文件(截图 / PDF / Word)说「保存里面的 xx」——第一步不是抄内容,
27
+ 是 `source add --file` 把原件收进袋。** 袋里的 file item 是溯源的锚点:
28
+ 字段值「从哪份原件来」靠它反查,而且它**受三重保护**——cleanup 不删(袋里的文件算已引用)、
29
+ 导出随包走、`file get` 能反查到本条目。先抄内容、原件随手一放,这三重保护都不存在,
30
+ 原件一丢字段就成了无源之水。先挂原件还有个实际好处:**随时能回看**——
31
+ OCR 抄错了、字段整理漏了,点开原件就行,不用求用户再发一遍。
32
+
24
33
  ## 冲突:以新的为准,旧的留痕
25
34
 
26
35
  同一件事有了新版本(又来一封邮件、密码改了)——**不要覆盖、不要删**:
@@ -75,7 +84,8 @@ nx-sk entry list --section <栏目> # 找目标条目(同名用 id)
75
84
 
76
85
  ### 第 1 步:原样收下(先别整理)
77
86
 
78
- 一份资料一条 item。文字、文件、网址各是一个 kind:
87
+ 一份资料一条 item。文字、文件、网址各是一个 kind。
88
+ **文件类资料永远先 `--file` 入袋**(铁律第 0 条)——哪怕你马上就要整理它:
79
89
 
80
90
  ```bash
81
91
  nx-sk source add <条目> --text "邮件原文照抄……" --name "李晶老师的分配邮件"
@@ -14,6 +14,9 @@ nx-sk source add <条目> --file "D:\资料\用户指南.pdf" --name "平台用
14
14
  - 想要「原件搬进库里」那是 `nx-sk file add` 的语义(它默认移动)——两者别混。
15
15
  - 袋里的 `file` item 只存 `fileId`;读的时候用 `nx-sk file get <fileId>` 或
16
16
  `source get --json` 里的 `files[fileId].path` 找物理路径。
17
+ - **袋里的文件算「已引用」**:`file cleanup` 不删它、`transfer export` 随包带走——
18
+ 袋是溯源的锚点,整理错了随时能点开原件回看。所以文件先入袋没有代价;
19
+ 不入袋的原件躺在库外,清理、移动、丢失都没有任何机制能拦。
17
20
 
18
21
  ## 各类资料的进法
19
22
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nx-sk",
3
- "version": "0.18.0",
3
+ "version": "0.20.0",
4
4
  "description": "nx-sk · 本机个人资源管理器(server-cli-web 骨架):栏目化存储个人信息与大模型密钥,CLI 与 Web 同源,敏感字段密文落盘。",
5
5
  "type": "module",
6
6
  "bin": {
@@ -165,11 +165,14 @@ export function findFileRecord(store, ref) {
165
165
  /**
166
166
  * 反向链接:哪些条目的**哪些字段**引用了这个附件。
167
167
  *
168
- * 两种引用方式都要认,否则附件中心会把「只在正文里贴过」的图片判成未引用:
168
+ * 三种引用方式都要认,否则附件中心会把「只在正文里贴过」的图片、
169
+ * 或「躺在原始资料袋里」的原始文件判成未引用,然后被 cleanup 删掉:
169
170
  * 1. `file` 字段 —— 值是附件 id(或唯一文件名),一个字段可挂多个,
170
171
  * 按 `fileIdsOf` 逐个成员判断,**任一** id 命中即算。
171
172
  * 2. `md` 字段 —— 正文里的 `![说明](f_xxx)`(见 mdimages.mdImageIds)。
172
173
  * 图片是**内嵌在 markdown 里**的,和 file 字段一样是正式引用。
174
+ * 3. `source` 字段 —— 原始资料袋里 kind='file' 的 item(袋是溯源的锚点:
175
+ * 字段值是从这份原件整理出来的,原件被删,溯源就成了空话)。
173
176
  * 同一个(条目, 字段)只出一条。附件中心据此显示「被哪些栏目 / 条目 / 字段用到」。
174
177
  */
175
178
  export function fileReferences(store, rec) {
@@ -193,7 +196,8 @@ export function fileReferences(store, rec) {
193
196
  if (!entries.length) continue;
194
197
  const fileFields = (sec.fields || []).filter((f) => f.type === 'file');
195
198
  const mdFields = (sec.fields || []).filter((f) => f.type === 'md');
196
- if (!fileFields.length && !mdFields.length) continue;
199
+ const sourceFields = (sec.fields || []).filter((f) => f.type === 'source');
200
+ if (!fileFields.length && !mdFields.length && !sourceFields.length) continue;
197
201
 
198
202
  for (const e of entries) {
199
203
  const push = (f) => out.push({
@@ -209,6 +213,14 @@ export function fileReferences(store, rec) {
209
213
  const ids = mdImageIds(e.values?.[f.key]);
210
214
  if (ids.length && hits(ids)) push(f);
211
215
  }
216
+ for (const f of sourceFields) {
217
+ // 袋值应是 item 数组(normalizeSourceItems 的产物);形状不对就当没有,别炸引用扫描
218
+ const bag = Array.isArray(e.values?.[f.key]) ? e.values[f.key] : [];
219
+ const ids = bag
220
+ .filter((x) => x && typeof x === 'object' && x.kind === 'file' && x.fileId)
221
+ .map((x) => x.fileId);
222
+ if (ids.length && hits(ids)) push(f);
223
+ }
212
224
  }
213
225
  }
214
226
  return out;
@@ -217,11 +229,12 @@ export function fileReferences(store, rec) {
217
229
  /**
218
230
  * 附件中心的分组素材:哪些栏目**可能**引用附件。
219
231
  * 中心据此按栏目筛选 / 分组 —— 组织方式**完全由栏目驱动,不预定义任何分类或槽位**。
220
- * 带 `file` 或 `md` 字段的栏目都算数:md 字段正文里贴的图也是正式引用。
232
+ * 带 `file` / `md` 字段的栏目都算数:md 字段正文里贴的图也是正式引用;
233
+ * `source` 袋也算——袋里的原始文件是溯源的锚点,同样要能按栏目筛出来。
221
234
  */
222
235
  export function collectFileSections(store) {
223
236
  return (store.sections || [])
224
- .filter((s) => (s.fields || []).some((f) => f.type === 'file' || f.type === 'md'))
237
+ .filter((s) => (s.fields || []).some((f) => ['file', 'md', 'source'].includes(f.type)))
225
238
  .map((s) => ({ id: s.id, title: s.title }));
226
239
  }
227
240
 
@@ -1,9 +1,11 @@
1
1
  // 字段字典:栏目的字段模板是**数据**,不是代码分支。
2
2
  // agent 与面板都从同一份声明渲染,所以「CLI 能填的字段」与「面板能填的字段」不可能分叉。
3
3
  //
4
- // type 取值:text | textarea | number | date | month | bool | select | tags | secret | file
4
+ // type 取值:text | textarea | number | date | month | bool | select | tags | entrylist | table | source | secret | file | md
5
5
 
6
- export const FIELD_TYPES = ['text', 'textarea', 'number', 'date', 'month', 'bool', 'select', 'tags', 'entrylist', 'source', 'secret', 'file', 'md'];
6
+ import { newId } from './ids.js';
7
+
8
+ export const FIELD_TYPES = ['text', 'textarea', 'number', 'date', 'month', 'bool', 'select', 'tags', 'entrylist', 'table', 'source', 'secret', 'file', 'md'];
7
9
 
8
10
  /**
9
11
  * 类型的人读标签 —— 只用于**面板下拉框**。
@@ -21,6 +23,7 @@ export const FIELD_TYPE_LABELS = {
21
23
  select: '单选',
22
24
  tags: '多值标签',
23
25
  entrylist: '结构清单(变长行)',
26
+ table: '表格(勾选/下拉/计算)',
24
27
  source: '原始资料(乱入后整理)',
25
28
  secret: '密文',
26
29
  file: '附件',
@@ -373,7 +376,78 @@ const PLATFORM_GROUPS = [
373
376
  { id: 'extra', title: '其他' },
374
377
  ];
375
378
 
379
+ // —— 字段样例(demo):播种用的**唯一**栏目 ——
380
+ //
381
+ // 为什么单独做一个:新用户第一个问题不是「帮我建一个求职栏目」,而是
382
+ // 「这个工具到底能存什么、能算到哪」。把答案直接摆出来——每种字段类型一格、
383
+ // 连示例数据一起给——比让他们先建栏目再自己填一遍快得多。
384
+ // 其它模板(job / secret / projects…)仍是模板,`section add --template` 随取随用,
385
+ // 只是**不再播种**:第一屏是说明书,不是别人的表格。
386
+ const DEMO_TABLE_COLUMNS = [
387
+ { key: 'item', label: '事项', type: 'text' },
388
+ { key: 'state', label: '状态', type: 'select', options: ['未开始', '进行中', '已完成'], default: '未开始' },
389
+ { key: 'done', label: '已办', type: 'bool' },
390
+ { key: 'hours', label: '工时', type: 'number' },
391
+ { key: 'rate', label: '单价', type: 'number', total: 'avg' },
392
+ { key: 'cost', label: '费用', formula: 'hours * rate', unit: '元' },
393
+ ];
394
+
395
+ const DEMO_FIELDS = [
396
+ // —— 基本字段(每个都是标量)——
397
+ f('name', '名称', 'text', 'basic', { hint: '单行文本:所有字段的地基。这个字段被设为「条目名」,列表里显示的就是它' }),
398
+ f('desc', '描述', 'textarea', 'basic', { hint: '多行文本:换行原样保留' }),
399
+ f('count', '数量', 'number', 'basic', { hint: '数字。写「1,200」这种带千分位的也认' }),
400
+ f('ok', '完成', 'bool', 'basic', { hint: '是 / 否 勾选框' }),
401
+ f('state', '状态', 'select', 'basic', { options: ['未开始', '进行中', '已完成'], hint: '下拉框:值必须在候选里,写错会被拦下而不是悄悄存进去' }),
402
+ f('day', '日期', 'date', 'basic', { hint: '日期,形如 2026-10-30' }),
403
+ f('month', '月份', 'month', 'basic', { hint: '月份,形如 2026-10' }),
404
+ f('tags', '标签', 'tags', 'basic', { hint: '多值标签:顿号或逗号分隔' }),
405
+
406
+ // —— 组合字段(值有自己的形状)——
407
+ f('accounts', '凭据清单', 'entrylist', 'combo', {
408
+ hint: '结构清单:变长的行,一列一列填。密码列与顶层敏感字段同一条边界(密文落盘、--mask 打码)。示例行只是形状,密码自己填',
409
+ fields: [
410
+ { key: 'name', label: '名称' },
411
+ { key: 'user', label: '账号' },
412
+ { key: 'pass', label: '密码', sensitive: true },
413
+ ],
414
+ }),
415
+ f('sheet', '样例表格', 'table', 'combo', {
416
+ hint: '表格:列定义就在**这条数据里**(不在栏目字典),面板「列设置」可以直接加列。'
417
+ + '「费用」是计算列(公式 hours * rate,不落盘、读时现算);表尾自动合计——数字求和、勾选计是',
418
+ columns: DEMO_TABLE_COLUMNS,
419
+ totals: [
420
+ { label: '合计', agg: { hours: 'sum', cost: 'sum', done: 'countTrue' } },
421
+ { label: '完成率', expr: 'pct(countTrue(col("done")), n)', unit: '%' },
422
+ ],
423
+ }),
424
+
425
+ // —— 富内容 ——
426
+ f('note', '图文笔记', 'md', 'rich', { hint: 'markdown 正文:标题 / 列表 / 代码块都能渲染;直接 Ctrl+V 贴截图(自动进附件库);待办勾选就是改正文本身' }),
427
+ f('docs', '附件', 'file', 'rich', { kind: 'doc', hint: '附件字段:值是附件 id 的列表(不是路径)。在这里直接上传,或从附件库选' }),
428
+ f('apikey', '密钥', 'secret', 'rich', { hint: '密文字段:值以 AES-256-GCM 落盘,读出来默认原文,--mask 才打码' }),
429
+ ];
430
+
431
+ const DEMO_GROUPS = [
432
+ { id: 'basic', title: '基本字段(标量)' },
433
+ { id: 'combo', title: '组合字段(值有形状)' },
434
+ { id: 'rich', title: '富内容' },
435
+ ];
436
+
437
+ const DEMO_TPL = {
438
+ id: 'demo',
439
+ label: '字段样例 / 能力边界',
440
+ description:
441
+ '每种字段类型各来一份,连示例数据一起给:单行文本到表格、公式与统计。'
442
+ + '看完(或直接改)就知道 nx-sk 能存什么、算到哪一步。看完可以整栏删掉。',
443
+ titleField: 'name',
444
+ titleLabel: '条目名',
445
+ groups: DEMO_GROUPS,
446
+ fields: DEMO_FIELDS,
447
+ };
448
+
376
449
  const TEMPLATES = {
450
+ demo: DEMO_TPL,
377
451
  job: {
378
452
  id: 'job',
379
453
  label: '求职 / 个人信息',
@@ -558,16 +632,58 @@ export function instantiateTemplate(templateId, overrides = {}) {
558
632
  };
559
633
  }
560
634
 
561
- /** 首次运行(store 文件不存在)时的默认栏目——第一个就是「求职」。 */
562
- export function seedSections(stamp) {
563
- return [
564
- { ...instantiateTemplate('job', { id: 'job', title: '求职', order: 10 }), createdAt: stamp, updatedAt: stamp },
565
- { ...instantiateTemplate('projects', { id: 'projects', title: '项目经历', order: 11 }), createdAt: stamp, updatedAt: stamp },
566
- { ...instantiateTemplate('internships', { id: 'internships', title: '实习/工作经历', order: 12 }), createdAt: stamp, updatedAt: stamp },
567
- { ...instantiateTemplate('campus', { id: 'campus', title: '校内职务/实践', order: 13 }), createdAt: stamp, updatedAt: stamp },
568
- { ...instantiateTemplate('secret', { id: 'secret', title: '密钥', order: 20 }), createdAt: stamp, updatedAt: stamp },
569
- { ...instantiateTemplate('deploy', { id: 'deploy', title: '部署配置', order: 30 }), createdAt: stamp, updatedAt: stamp },
570
- ];
635
+ /**
636
+ * 首次运行(store 文件不存在)时播种的东西:**只有一个**「字段样例」栏目。
637
+ *
638
+ * 为什么不再播种求职 / 密钥 / 项目那一堆:那些是「某个具体场景」的栏目,
639
+ * 用户的第一栏多半不是它们;而「这个工具能存什么」是每个新用户都要问的问题。
640
+ * 把答案直接摆出来(每种字段一格、连示例数据一起),比让他们先建栏目再填一遍快得多。
641
+ * 其它模板仍是模板——`section templates` 看得到,`section add --template` 随取随用。
642
+ */
643
+ export function seedSections(at) {
644
+ return [{ ...instantiateTemplate(DEMO_TPL.id, { id: DEMO_TPL.id, title: '字段样例', order: 10 }), createdAt: at, updatedAt: at }];
645
+ }
646
+
647
+ /**
648
+ * 播种的那条**示例条目**:每种字段都有内容可看(附件与密文除外——
649
+ * 附件要有真实文件、密文要有密钥,这两样播种时给不了,留空并在 hint 里说明)。
650
+ *
651
+ * 注意:播种直接写 store,不走写入校验——所以这里的形状必须与
652
+ * `normalizeSpec` / `serializeEntry` 认的一致(表格给行数组,列取字段定义里的)。
653
+ */
654
+ export function seedEntries(at) {
655
+ const values = {
656
+ name: '示例条目',
657
+ desc: '这是一条示例条目:左(或上)边选中的就是它。直接改任何一格,保存后就成了你自己的数据。',
658
+ count: 3,
659
+ ok: true,
660
+ state: '进行中',
661
+ day: String(at).slice(0, 10),
662
+ month: String(at).slice(0, 7),
663
+ tags: ['样例', '能力边界'],
664
+ accounts: [{ name: '示例:主控台', user: 'ops@example.com' }],
665
+ sheet: [
666
+ { item: '设计', state: '已完成', done: true, hours: 2, rate: 200 },
667
+ { item: '开发', state: '进行中', done: false, hours: 5, rate: 200 },
668
+ ],
669
+ note: [
670
+ '# 图文字段',
671
+ '',
672
+ '- 支持 **markdown**:标题、列表、`行内代码`、表格都能渲染',
673
+ '- 裸网址会变成可点链接:https://github.com/ZHLX2005/nx-sk',
674
+ '- [ ] 截图直接 Ctrl+V 粘进来(自动进附件库,正文里插入引用)',
675
+ '- [ ] 勾选待办就是改正文本身,没有第二份勾选状态',
676
+ ].join('\n'),
677
+ };
678
+ return [{
679
+ id: newId('e'),
680
+ section: DEMO_TPL.id,
681
+ title: values.name,
682
+ tags: ['样例'],
683
+ values,
684
+ createdAt: at,
685
+ updatedAt: at,
686
+ }];
571
687
  }
572
688
 
573
689
  /** 由「字段定义 + 值」推导栏目的分组结构,供 render/面板用。 */
@@ -610,7 +726,8 @@ export function syncSectionGroups(groups, fields) {
610
726
  */
611
727
  // entrylist 的子字段也要参与漂移对比:清单列是结构的一部分,模板把「密码」列标了
612
728
  // sensitive 而栏目里没有,这种差异必须报出来——否则密文边界在两份定义间悄悄分叉。
613
- const FIELD_CMP_KEYS = ['label', 'type', 'group', 'hint', 'options', 'maxItems', 'sensitive', 'fill', 'fields'];
729
+ // table 的列与统计行同理:列类型(勾选/下拉/数字)和公式改了,值的样子就变了。
730
+ const FIELD_CMP_KEYS = ['label', 'type', 'group', 'hint', 'options', 'maxItems', 'sensitive', 'fill', 'fields', 'columns', 'totals'];
614
731
 
615
732
  function normalizedFieldDef(f) {
616
733
  return {
@@ -626,6 +743,14 @@ function normalizedFieldDef(f) {
626
743
  fields: Array.isArray(f?.fields)
627
744
  ? f.fields.map((s) => ({ key: String(s?.key || ''), label: String(s?.label || s?.key || ''), sensitive: s?.sensitive === true }))
628
745
  : null,
746
+ // 表格列:类型与公式决定「这一格怎么算」,改了一定要报
747
+ columns: Array.isArray(f?.columns)
748
+ ? f.columns.map((s) => ({
749
+ key: String(s?.key || ''), label: String(s?.label || s?.key || ''),
750
+ type: String(s?.type || 'text'), sensitive: s?.sensitive === true, formula: String(s?.formula || ''),
751
+ }))
752
+ : null,
753
+ totals: Array.isArray(f?.totals) ? f.totals : null,
629
754
  };
630
755
  }
631
756
 
@@ -6,16 +6,46 @@
6
6
  // 这样 render 保持纯函数,而「什么时候允许看明文」仍然只有一个决策点。
7
7
  import { isCipherBlob, maskValue } from './crypto.js';
8
8
  import { FILL_LABELS, fillPolicy, isExcludedField, isSensitiveField } from './fields.js';
9
+ // 表格的「字段定义 + 数据」怎么合成一份自描述文档,只有一份实现(见 shared/table.js)。
10
+ import { columnToDef, normalizeSpec } from '../shared/table.js';
9
11
 
10
12
  export function isBlank(v) {
11
13
  if (v === null || v === undefined) return true;
12
14
  if (Array.isArray(v)) return v.length === 0;
15
+ // 表格文档:一行都没有就算没填(有列没数据不算填了内容)。
16
+ // 密文对象没有 rows,不受这条影响。
17
+ if (typeof v === 'object' && Array.isArray(v.rows)) return v.rows.length === 0;
18
+ return String(v).trim() === '';
19
+ }
20
+
21
+ /**
22
+ * 「这个字段真的没有东西可带出去」—— 与 isBlank 的区别只在表格:
23
+ *
24
+ * - `isBlank` 决定**完整度**:有列没行的表算「没填」(不然一张空表就把进度撑满了)。
25
+ * - `isStoredEmpty` 决定**值要不要输出**:还有列就说明结构在,要带出去 ——
26
+ * 否则面板拿不到列,用户搭好的骨架(列 + 默认值)一保存就"消失"了。
27
+ */
28
+ export function isStoredEmpty(v) {
29
+ if (v === null || v === undefined) return true;
30
+ if (Array.isArray(v)) return v.length === 0;
31
+ if (typeof v === 'object' && Array.isArray(v.rows)) {
32
+ return !v.rows.length && !(Array.isArray(v.columns) && v.columns.length);
33
+ }
13
34
  return String(v).trim() === '';
14
35
  }
15
36
 
16
37
  /** 值 → 人读字符串(bool / tags / 数组 / 标量 / entrylist 行)。 */
17
38
  export function formatValue(value) {
18
39
  if (isBlank(value)) return '';
40
+ // 表格文档:按「列名=值 · 列名=值;下一行」压成一行(section dump 的表格放不下多行版)
41
+ if (typeof value === 'object' && Array.isArray(value.rows)) {
42
+ const cols = Array.isArray(value.columns) ? value.columns : [];
43
+ const labelOf = (k) => cols.find((c) => c.key === k)?.label || k;
44
+ return value.rows.map((row) => Object.entries(row || {})
45
+ .filter(([, v]) => !isBlank(v))
46
+ .map(([k, v]) => `${labelOf(k)}=${typeof v === 'boolean' ? (v ? '是' : '否') : (Array.isArray(v) ? v.join('、') : v)}`)
47
+ .join(' · ')).filter(Boolean).join(';');
48
+ }
19
49
  if (Array.isArray(value)) {
20
50
  // 结构清单的行:`k=v · k=v;k=v` 压成一行——section dump 的表格里放不下多行版
21
51
  if (value.length && value.every((x) => isPlainRow(x))) {
@@ -35,12 +65,17 @@ function isPlainRow(x) {
35
65
  }
36
66
 
37
67
  /**
38
- * entrylist 的一行:敏感子值走与顶层敏感字段同一条 displaySensitive 边界
68
+ * 清单类字段(entrylist / table)的一行:敏感子值走与顶层敏感字段同一条 displaySensitive 边界
39
69
  * (默认原文 / mask 打码 / 有 decrypt 才解密)。非对象行(坏数据)原样放过。
70
+ *
71
+ * 两种字段的差别只在「列」叫什么:entrylist 用 fields,table 用 columns。
72
+ * 密文边界是同一条,所以这里只认「哪些子字段是 sensitive」,不关心是哪种清单。
40
73
  */
41
- function displayRow(def, row, opts) {
74
+ function subFieldsOf(def) {
75
+ return def?.type === 'table' ? (def.columns || []) : (def.fields || []);
76
+ }function displayRow(def, row, opts) {
42
77
  if (!isPlainRow(row)) return row;
43
- const subs = (def.fields || []).filter((s) => s.sensitive);
78
+ const subs = subFieldsOf(def).filter((s) => s.sensitive);
44
79
  if (!subs.length) return row;
45
80
  const out = { ...row };
46
81
  for (const s of subs) {
@@ -82,11 +117,25 @@ export function serializeEntry(section, entry, { mask = false, decrypt } = {}) {
82
117
  const values = {};
83
118
  for (const def of section.fields) {
84
119
  const raw = entry.values?.[def.key];
85
- if (isBlank(raw)) { values[def.key] = null; continue; }
120
+ // 这里用 isStoredEmpty 而不是 isBlank:空表(有列没行)要带出去,否则骨架丢失
121
+ if (isStoredEmpty(raw)) { values[def.key] = null; continue; }
86
122
  if (def.type === 'entrylist' && Array.isArray(raw)) {
87
123
  values[def.key] = raw.map((row) => displayRow(def, row, { mask, decrypt }));
88
124
  continue;
89
125
  }
126
+ // 表格读出去永远是**自描述的完整文档**:columns / rows / 可选 totals。
127
+ // 列存在数据里,所以读的人(面板、agent、导出)不必再去查栏目字典才知道有哪些列。
128
+ if (def.type === 'table') {
129
+ const spec = normalizeSpec(def, raw);
130
+ values[def.key] = {
131
+ v: spec.v,
132
+ columns: spec.columns.map((c) => columnToDef(c)),
133
+ rows: spec.rows.map((row) => displayRow({ type: 'table', columns: spec.columns }, row, { mask, decrypt })),
134
+ ...(Array.isArray(spec.totals) ? { totals: spec.totals } : {}),
135
+ ...(spec.summary === false ? { summary: false } : {}),
136
+ };
137
+ continue;
138
+ }
90
139
  values[def.key] = isSensitiveField(section, def.key)
91
140
  ? displaySensitive(raw, { mask, decrypt })
92
141
  : raw;
@@ -167,6 +216,11 @@ export function dumpSection(section, entries, { mask = false, decrypt } = {}) {
167
216
  options: x.options || null,
168
217
  // 结构清单的列(子字段)必须跟着字典出去,否则面板渲染不出列、agent 不知道行里该有什么键
169
218
  fields: x.fields || null,
219
+ // 表格的列(带类型/公式)与统计行同理:不知道列定义,agent 只能瞎猜行里能写什么
220
+ columns: x.columns || null,
221
+ totals: x.totals || null,
222
+ summary: x.summary === false ? false : undefined,
223
+ maxRows: x.maxRows || null,
170
224
  kind: x.kind || '',
171
225
  sensitive: isSensitiveField(section, x.key),
172
226
  // 填写策略要跟着字段字典出去,否则面板与 agent 不知道哪个格子「不用填」
package/src/core/store.js CHANGED
@@ -4,7 +4,7 @@ import fsp from 'node:fs/promises';
4
4
  import { join } from 'node:path';
5
5
  import { displayPath, migrationDir, storeFile } from './paths.js';
6
6
  import { ensureDir, pathExists, writeAtomic } from './fsx.js';
7
- import { ensureSourceBuiltin, instantiateTemplate, seedSections, syncSectionGroups } from './fields.js';
7
+ import { ensureSourceBuiltin, instantiateTemplate, seedEntries, seedSections, syncSectionGroups } from './fields.js';
8
8
  import { normalizeFileRecord } from './attachments.js';
9
9
  import { nowIso, stamp } from './ids.js';
10
10
 
@@ -15,7 +15,7 @@ export const STORE_VERSION = 3;
15
15
 
16
16
  export function defaultSettings() {
17
17
  return {
18
- defaultSection: 'job',
18
+ defaultSection: 'demo',
19
19
  // 头部导航分组:[{ title, sections: [栏目 id…] }],数组顺序 = 显示顺序。
20
20
  // 缺省空数组 = 全部栏目平铺(保持老行为);栏目建得多了再在设置页收拢。
21
21
  navGroups: [],
@@ -30,7 +30,9 @@ function emptyStore(seed) {
30
30
  // 只有「store 文件压根不存在」才播种。文件在、但 sections 为空
31
31
  // 说明用户自己删光了栏目——这时候再播种会把它变回来,等于删不掉。
32
32
  sections: seed ? seedSections(at) : [],
33
- entries: [],
33
+ // 示例条目跟着「字段样例」栏目一起播种:没有它,那些字段就只是空格子,
34
+ // 「感受能力边界」就少了最有说服力的那部分。
35
+ entries: seed ? seedEntries(at) : [],
34
36
  files: [],
35
37
  };
36
38
  }
package/src/core/vault.js CHANGED
@@ -100,16 +100,25 @@ export async function currentKeyId() {
100
100
  */
101
101
  export async function sensitiveViewer(section, entries = []) {
102
102
  const sensitive = (section?.fields || []).filter((f) => f.sensitive || f.type === 'secret');
103
- // 结构清单(entrylist)的敏感子值也是密文落盘:不探行内的话,清单里真有密文时
104
- // viewer 不会被创建,读出来全变成「需要密钥才能解密」。
105
- const entryLists = (section?.fields || []).filter((f) => f.type === 'entrylist');
106
- if (!sensitive.length && !entryLists.length) return undefined;
103
+ // 清单类(结构清单 entrylist / 表格 table)的敏感**子值**也是密文落盘:
104
+ // 不探行内的话,清单里真有密文时 viewer 不会被创建,读出来全变成「需要密钥才能解密」。
105
+ const lists = (section?.fields || []).filter((f) => f.type === 'entrylist' || f.type === 'table');
106
+ if (!sensitive.length && !lists.length) return undefined;
107
107
  const keys = sensitive.map((f) => f.key);
108
- const subKeysOf = (f) => (f.fields || []).filter((s) => s.sensitive).map((s) => s.key);
108
+ // 两种清单的「列」字段名不同(fields / columns),但密文边界的判据是同一个
109
+ const subKeysOf = (f) => (f.type === 'table' ? (f.columns || []) : (f.fields || []))
110
+ .filter((s) => s.sensitive).map((s) => s.key);
111
+ // 表格的值既可能是行数组,也可能是自描述文档 `{columns, rows}`
112
+ const rowsOf = (v) => (Array.isArray(v) ? v : (v && Array.isArray(v.rows) ? v.rows : []));
113
+ const rowHasBlob = (row, f) => {
114
+ if (!row || typeof row !== 'object') return false;
115
+ const subKeys = subKeysOf(f);
116
+ if (subKeys.length) return subKeys.some((k) => isCipherBlob(row[k]));
117
+ // 列存在数据里、字段定义没给列时:任何一格是密文都算(否则会锁死在不认识的结构上)
118
+ return Object.values(row).some((v) => isCipherBlob(v));
119
+ };
109
120
  const hasBlob = entries.some((e) => keys.some((k) => isCipherBlob(e?.values?.[k]))
110
- || entryLists.some((f) => Array.isArray(e?.values?.[f.key]) && e.values[f.key].some((row) => (
111
- !!row && typeof row === 'object' && subKeysOf(f).some((k) => isCipherBlob(row[k]))
112
- ))));
121
+ || lists.some((f) => rowsOf(e?.values?.[f.key]).some((row) => rowHasBlob(row, f))));
113
122
  if (!hasBlob) return undefined;
114
123
  const { key } = await resolveVaultKey();
115
124
  return (blob) => decryptValue(key, blob);
@@ -92,6 +92,33 @@ export default {
92
92
  run: (ctx) => service.updateEntry(ctx.ref, ctx),
93
93
  render: (d) => service.renderEntryChange(d),
94
94
  },
95
+ {
96
+ id: 'entry.table',
97
+ cli: ['entry', 'table'],
98
+ http: ['GET', '/api/tables/:ref'],
99
+ summary: '看一个表格字段的现值:表头、数据、计算列与统计行(合计/平均/计数)。只读,公式现算',
100
+ args: ['ref'],
101
+ flags: {
102
+ field: { type: 'string', hint: '表格字段(key 或中文标签);栏目里只有一个表格时可不填' },
103
+ mask: { type: 'boolean', hint: '密文列打码显示' },
104
+ section: { type: 'string', hint: '限定栏目,解决同名歧义' },
105
+ },
106
+ run: (ctx) => service.getTable(ctx.ref, ctx),
107
+ render: (d) => service.renderTable(d),
108
+ },
109
+ {
110
+ id: 'entry.remove-many',
111
+ cli: ['entry', 'remove-many'],
112
+ http: ['POST', '/api/entries/remove-many'],
113
+ summary: '批量删条目(ids 用逗号分隔)。找不到的跳过并报告;一个都找不到才报 NOT_FOUND',
114
+ args: ['ids'],
115
+ flags: {
116
+ section: { type: 'string', hint: '限定栏目,解决同名歧义' },
117
+ 'dry-run': { type: 'boolean' },
118
+ },
119
+ run: (ctx) => service.removeMany(ctx.ids, ctx),
120
+ render: (d) => service.renderEntryRemoveMany(d),
121
+ },
95
122
  {
96
123
  id: 'entry.remove',
97
124
  cli: ['entry', 'remove'],