nx-sk 0.18.0 → 0.23.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.
- package/CHANGELOG.md +250 -0
- package/README.md +101 -5
- package/assets/nx-sk/SKILL.md +68 -16
- package/assets/nx-sk/references/00-design.md +3 -3
- package/assets/nx-sk/references/10-sections-entries.md +128 -12
- package/assets/nx-sk/references/15-special-fields.md +197 -0
- package/assets/nx-sk/references/40-files.md +44 -8
- package/assets/nx-sk/references/60-transfer.md +10 -4
- package/assets/sk-needdo/SKILL.md +2 -0
- package/assets/sk-source/SKILL.md +11 -1
- package/assets/sk-source/references/20-intake.md +3 -0
- package/package.json +15 -4
- package/src/core/attachments.js +51 -5
- package/src/core/fields.js +138 -13
- package/src/core/paths.js +11 -0
- package/src/core/render.js +71 -4
- package/src/core/source.js +47 -7
- package/src/core/store.js +56 -6
- package/src/core/vault.js +33 -8
- package/src/modules/entries/aiPending.js +303 -0
- package/src/modules/entries/blockPanel.jsx +239 -0
- package/src/modules/entries/boardView.jsx +136 -0
- package/src/modules/entries/entriesTable.jsx +119 -0
- package/src/modules/entries/index.js +174 -0
- package/src/modules/entries/service.js +875 -27
- package/src/modules/entries/view.jsx +136 -6
- package/src/modules/sections/index.js +94 -1
- package/src/modules/sections/service.js +643 -11
- package/src/modules/sections/view.jsx +770 -79
- package/src/modules/settings/service.js +90 -7
- package/src/modules/system/service.js +19 -3
- package/src/modules/transfer/service.js +165 -4
- package/src/shared/blocks.js +400 -0
- package/src/shared/navTree.js +252 -0
- package/src/shared/table.js +884 -0
- package/src/shared/views.js +221 -0
- package/src/web/frontend/App.jsx +200 -234
- package/src/web/frontend/activeView.js +56 -0
- package/src/web/frontend/blocks/registry.jsx +304 -0
- package/src/web/frontend/components/aiBar.jsx +192 -0
- package/src/web/frontend/components/blockDnd.jsx +69 -0
- package/src/web/frontend/components/fieldEditor.jsx +24 -4
- package/src/web/frontend/components/listDrag.jsx +82 -0
- package/src/web/frontend/components/sidebar.jsx +354 -0
- package/src/web/frontend/components/sourcePanel.jsx +179 -22
- package/src/web/frontend/components/tableField.jsx +477 -0
- package/src/web/frontend/components/viewChips.jsx +43 -0
- package/src/web/frontend/listSort.js +18 -0
- package/src/web/frontend/main.jsx +4 -0
- package/src/web/frontend/panels.jsx +75 -0
- package/src/web/frontend/store.jsx +4 -1
- package/src/web/frontend/styles.css +536 -0
- package/src/web/frontend/workspace.js +253 -0
- package/src/web/public/assets/{files--aIy09Sp.js → files-BoJqTGyZ.js} +1 -1
- package/src/web/public/assets/index-DDcA8xZc.js +64 -0
- package/src/web/public/assets/index-FDvbnX_f.css +1 -0
- package/src/web/public/assets/{view-0jlrnuBr.js → view-B04bzsph.js} +1 -1
- package/src/web/public/assets/view-CvJr_elT.js +42 -0
- package/src/web/public/assets/{view-Bt7O8gS_.js → view-DNT9of0L.js} +1 -1
- package/src/web/public/assets/view-tNIpJ3PQ.js +1 -0
- package/src/web/public/assets/view-xwEy1P7C.js +3 -0
- package/src/web/public/index.html +2 -2
- package/src/web/public/assets/index-BWIrglCf.js +0 -41
- package/src/web/public/assets/index-CEIiV0jA.css +0 -1
- package/src/web/public/assets/view-1SYBZ3dg.js +0 -1
- package/src/web/public/assets/view-Bt8MZAtu.js +0 -1
- package/src/web/public/assets/view-CjX_ywS7.js +0 -36
|
@@ -47,8 +47,9 @@ store.json(~/nx-sk/store.json 或 $NX_SK_STORE)
|
|
|
47
47
|
|
|
48
48
|
内置模板 8 个:`job`(求职 / 个人信息,约 80 字段 / 10 分组——含「附件资料」组:简历附件 / 头像图片 / 成绩单 / 证书扫描件)、`projects`(项目经历)、`internships`(实习/工作经历)、`campus`(校内职务/实践)、`secret`(密钥,**单字段 KV**——细节见 `20-secrets`)、`deploy`(部署配置:Dockerfile / compose / k8s 清单,**一份文件一个条目**,自带「凭据清单」——细节见 `50-deploy`)、`platform`(容器平台:控制台链接 / 账号 / 密码 / 镜像,一个平台一个条目)、`thesis`(毕业论文规范字段化)。三类经历栏目(projects / internships / campus)**一个项目 / 一段经历 = 一个条目**,角色、时间、技术栈都是独立字段——不要往 job 栏目里塞经历。
|
|
49
49
|
|
|
50
|
-
首次运行只**播种
|
|
51
|
-
|
|
50
|
+
首次运行只**播种 1 个**:`demo`(字段样例 / 能力边界——每种字段一格、连示例条目一起,见 `15-special-fields`)。
|
|
51
|
+
其余模板(job / projects / internships / campus / secret / deploy / platform / thesis)需要时用
|
|
52
|
+
`section add <id> --template <模板id>` 建;没有 KV 栏目时第一次 `key set` 也会自动补建 `secret`。
|
|
52
53
|
|
|
53
54
|
## 三、条目命令
|
|
54
55
|
|
|
@@ -104,7 +105,64 @@ nx-sk entry get 张三 --json
|
|
|
104
105
|
- 身份证号、手机号、紧急联系人电话这类字段,写之前跟用户确认一次来源。
|
|
105
106
|
- 每次批量写之前先 `--dry-run`。
|
|
106
107
|
|
|
107
|
-
##
|
|
108
|
+
## 五、块正文与 AI 提议(entry.body / entry ai)
|
|
109
|
+
|
|
110
|
+
条目除了结构化字段还有**块正文**(`entry.body`,可选键):段落 / 标题 / 图文 / 表格 / 清单 /
|
|
111
|
+
附件 / 密钥七种叶块,加内嵌栏目(`section`)与分栏(`column`)两种容器块。
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# 建块 / 看块
|
|
115
|
+
nx-sk entry block add <ref> --type paragraph --data '{"text":"第一段"}'
|
|
116
|
+
nx-sk entry block list <ref> # secret 块默认原文,--mask 打码
|
|
117
|
+
nx-sk entry block update <ref> <块id> --data @块.json
|
|
118
|
+
nx-sk entry block move <ref> <块id> --to 0
|
|
119
|
+
|
|
120
|
+
# AI 提议:**AI 永不直接改数据**
|
|
121
|
+
# ① 你(agent / 外部模型)产出提议正文 = 该条目的最终块数组
|
|
122
|
+
# ② suggest 只落一条 pending(~/nx-sk/pending/,运行态,不进 store / 导出包)
|
|
123
|
+
# ③ 人或你在面板/CLI 上 apply(才写 store)或 reject(只删文件)
|
|
124
|
+
nx-sk entry ai suggest <ref> --prompt "把自我介绍改短" --from @proposal.json
|
|
125
|
+
nx-sk entry ai list <ref>
|
|
126
|
+
nx-sk entry ai apply <pendingId> # 块被改过 → CONFLICT,--force 才覆盖
|
|
127
|
+
nx-sk entry ai reject <pendingId>
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
**纪律**:
|
|
131
|
+
|
|
132
|
+
- proposal.json 是 `{"blocks":[…]}` 或直接块数组;给**最终正文**,不是补丁。
|
|
133
|
+
- 建议先 `nx-sk entry block list <ref> --json` 拿现正文再改,块 id 保持不变
|
|
134
|
+
(同 id 不同内容 = 一次「修改」,出现新 id = 「新增」,缺了的 id = 「删除」)。
|
|
135
|
+
- 密钥块在提议里是明文——pending 落在本机运行态目录(0600),这是有意设计;
|
|
136
|
+
但**不要**把 pending 文件内容贴进对话或日志。
|
|
137
|
+
- 应用前想留底就先 `transfer export`(apply 写 store,与手改同一条边界)。
|
|
138
|
+
|
|
139
|
+
## 六、数据库视图(section.views / section view)
|
|
140
|
+
|
|
141
|
+
视图是**同一批条目的多种投影**:表格(列 = 字段投影)、精简(两列)、看板(按 select 字段分列)、
|
|
142
|
+
KV 栏目的键值面。配置存在 `section.views` / `section.defaultView`(可选键)。
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
nx-sk section view list <id> # 没配过时给缺省推断(provisional: true,不落盘)
|
|
146
|
+
nx-sk section view add <id> --type board --title 按状态 --groupby status
|
|
147
|
+
nx-sk section view update <id> <viewId> --set col.状态.width=180 --sort 状态:desc
|
|
148
|
+
nx-sk section view set-default <id> <viewId>
|
|
149
|
+
nx-sk section view remove <id> <viewId>
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
**语义**:
|
|
153
|
+
|
|
154
|
+
- **缺省视图是推断的、不落盘**:非 KV 栏目给「表格 / 精简 / 看板」,KV 栏目给「KV」。
|
|
155
|
+
第一次改视图才固化(把当时生效的那套推断视图一起写进去——只写用户新建的那条,
|
|
156
|
+
其余 chips 会凭空消失)。`views: []` 与「没配过」行为一致,都走推断。
|
|
157
|
+
- 投影只存 `key / width / hidden`;标签与类型回查字段字典。引用的字段被删 → 列还在,
|
|
158
|
+
表头写「已删字段」、单元格「—」(不炸、也不静默消失)。
|
|
159
|
+
- **看板的拖卡 = 写操作**:等于 `entry update --set <groupby字段>=<列值>`;
|
|
160
|
+
空值与候选外的值落「未分组」列——展示可以,**不是拖拽落点**(拖进去等于写一个不存在的值)。
|
|
161
|
+
- **没有筛选 DSL**(`--filter` 明确不做):存一个不生效的配置比没有更糟。
|
|
162
|
+
- 视图随导出包往返;导入只在「新建栏目」或「目标没配过视图」时应用——
|
|
163
|
+
目标已有视图说明用户自己配过,不静默覆盖(预览里给警告)。
|
|
164
|
+
|
|
165
|
+
## 七、扩字段字典(不写代码)
|
|
108
166
|
|
|
109
167
|
**最省事的做法:直接写。** 字典里没有的键会自动登记(键名就是它本身),类型按值推断
|
|
110
168
|
(`是/否` → bool,数组 → tags,其余 → text)。
|
|
@@ -133,7 +191,7 @@ nx-sk section update job --remove-field blog
|
|
|
133
191
|
nx-sk section update job --fields @fields.json
|
|
134
192
|
```
|
|
135
193
|
|
|
136
|
-
字段定义支持:`key`(字母开头)、`label`、`type`(`text|textarea|number|date|month|bool|select|tags|entrylist|source|secret|file|md`)、
|
|
194
|
+
字段定义支持:`key`(字母开头)、`label`、`type`(`text|textarea|number|date|month|bool|select|tags|entrylist|table|source|secret|file|md`)、
|
|
137
195
|
`group`、`hint`、`options`(候选项)、`sensitive`(true 则密文落盘)、`maxItems`(tags / file 上限)、
|
|
138
196
|
`fill`(填写策略,见下)。
|
|
139
197
|
|
|
@@ -150,7 +208,8 @@ nx-sk section update job --fields @fields.json
|
|
|
150
208
|
> `type: 'entrylist'` 是**结构清单字段**:值 = 行对象的**数组**,行数不限(变长);列(子字段)
|
|
151
209
|
> 在字段定义的 `fields` 里声明。适合「一个条目挂多组 链接/账号/密码」这类密集结构——
|
|
152
210
|
> tags 存不了结构,拆成多个字段又不知道会有几组。声明 `sensitive: true` 的列与顶层敏感字段
|
|
153
|
-
> 同一条边界:密文落盘、默认原文、`--mask`
|
|
211
|
+
> 同一条边界:密文落盘、默认原文、`--mask` 打码。面板渲染成密集迷你表,直接增删行,
|
|
212
|
+
> **拖行尾的 ⠿ 调行序**(行内操作键是小图标键,不抢内容的注意力)。
|
|
154
213
|
>
|
|
155
214
|
> ```bash
|
|
156
215
|
> # 建字段(面板「新增字段」选「结构清单」会预填 名称/链接/账号/密码(密文) 四列)
|
|
@@ -165,6 +224,21 @@ nx-sk section update job --fields @fields.json
|
|
|
165
224
|
> 没登记过的键直接写行数组会**自动登记**成 entrylist 并从行推断列。`entry get` 里清单一行一条:
|
|
166
225
|
> `名称=主控台 · 链接=https://… · 账号=ops · 密码=…`(--mask 时密码列打码)。
|
|
167
226
|
|
|
227
|
+
> `type: 'table'` 是**表格字段**:`entrylist` 的进阶版 —— 每格有类型(勾选 / 下拉 / 数字 / 日期),
|
|
228
|
+
> 还能有**计算列**(JS 表达式)与**表尾统计**。最根本的差别是**结构归数据**:列定义、行、公式、
|
|
229
|
+
> 统计配置全部存在**条目值里**(`{v, columns, rows, totals?, summary?}`),字段定义里的 `columns`
|
|
230
|
+
> 只是「新建时的初始列」。所以「这一条想多一列」不必改 schema,也不影响同栏目其它条目。
|
|
231
|
+
> 面板上**行与列都能拖**:拖表头搬列、拖行尾的 ⠿ 搬行(松手前有插入线)。
|
|
232
|
+
>
|
|
233
|
+
> ```bash
|
|
234
|
+
> nx-sk section update mysec --add-field '{"key":"tasks","label":"任务表","type":"table"}'
|
|
235
|
+
> nx-sk entry update 周报 --data '{"任务表":{"columns":[…],"rows":[…]}}'
|
|
236
|
+
> nx-sk entry table 周报 --field 任务表 # 只看这张表:数据 + 合计 + 公式报错
|
|
237
|
+
> ```
|
|
238
|
+
>
|
|
239
|
+
> 形状、公式作用域与内建、统计两个轴、**写入即体检**(语法 / 列名 / 单值不通过就不保存)、
|
|
240
|
+
> 空值与默认值、常见错对照表 —— 全在 [[15-special-fields]],这里不重复一份(两份必然漂移)。
|
|
241
|
+
|
|
168
242
|
> `type: 'source'` 是**原始资料袋**:每个栏目都自带一个的「乱入区」。值 = 一组资料条目
|
|
169
243
|
> (`{id, kind, name, text|fileId|url, addedAt, note, mapped}`,kind = text/file/url)。
|
|
170
244
|
> 杂乱资料(邮件、截图、PDF 摘录、手抄的表)先**原样**丢进袋里,之后由 agent 或人
|
|
@@ -183,6 +257,37 @@ nx-sk section update job --fields @fields.json
|
|
|
183
257
|
|
|
184
258
|
> `select` 的 `options` 是**候选项不是白名单**:真实值(如某个少数民族)不在候选里也允许写入。
|
|
185
259
|
|
|
260
|
+
### 栏目结构:分组也是数据,面板里就能改
|
|
261
|
+
|
|
262
|
+
栏目 = 分组(`section.groups`)+ 字段字典(`section.fields`),两样都只是**数据**:
|
|
263
|
+
分组是条目表单里的小标题,**顺序就是它们出现的先后**。面板「编辑栏目」里能直接增删改序,
|
|
264
|
+
CLI 用同一批 action —— 不存在「哪一边功能少一点」。
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
nx-sk section update job --add-group '{"id":"contact","title":"联系信息"}'
|
|
268
|
+
nx-sk section update job --rename-group '{"id":"contact","title":"联系方式"}'
|
|
269
|
+
nx-sk section update job --rename-group '{"id":"contact","title":"联系方式","newId":"reach"}' # 换 id:组里字段的 group 跟着改
|
|
270
|
+
nx-sk section update job --move-group '{"id":"reach","dir":"up"}'
|
|
271
|
+
nx-sk section update job --remove-group reach # 空组才能删
|
|
272
|
+
nx-sk section update job --set-field '{"key":"phone","label":"手机号","group":"reach"}'
|
|
273
|
+
nx-sk section update job --move-field '{"key":"phone","dir":"up"}' # 在自己的分组内换位置
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
每次改动都会把**新旧值**打进输出(`字段 phone:分组 contact → reach`)——
|
|
277
|
+
「已更新栏目 job:fields」这种输出等于没说,改错了没法回溯。
|
|
278
|
+
|
|
279
|
+
三条规矩,全是**拦下来**而不是悄悄做:
|
|
280
|
+
|
|
281
|
+
| 规矩 | 为什么 |
|
|
282
|
+
| --- | --- |
|
|
283
|
+
| 分组 id 唯一 | 重复报 CONFLICT,绝不覆盖同名分组(改名用 `--rename-group`) |
|
|
284
|
+
| 非空分组不给删 | 字段上挂着每个条目的值;先把字段挪走(改它的「分组」)或删掉 |
|
|
285
|
+
| 字段 key 不可改 | 值按 key 存在条目里,改 key = 已有值读不出来。要换就新增字段再搬值 |
|
|
286
|
+
|
|
287
|
+
另外两条边界:内置的「原始资料」分组与字段**删不掉**(每个栏目自带,删了下回读又补回来);
|
|
288
|
+
清单类字段(`entrylist` / `table`)的列是字段自己的结构,所以**不提供就地换类型**——
|
|
289
|
+
要建就在「新增字段」里连列一起建。
|
|
290
|
+
|
|
186
291
|
### 填写策略 `fill`:有些格子填了反而减分
|
|
187
292
|
|
|
188
293
|
不是每个格子都值得填。应届生的「上一家公司」、政治面貌为「群众」时的「入党时间」——
|
|
@@ -220,13 +325,24 @@ nx-sk entry get 张三
|
|
|
220
325
|
> ② 两者都**不要**出现在「还缺什么」的清单里;③ 用户说「这个不用填」时,
|
|
221
326
|
> 用 `--fill <字段>=avoid` 记下来,而不是靠下一轮上下文记住。
|
|
222
327
|
|
|
223
|
-
##
|
|
224
|
-
|
|
225
|
-
`nx-sk serve`
|
|
226
|
-
|
|
227
|
-
-
|
|
228
|
-
|
|
328
|
+
## 八、Web 面板
|
|
329
|
+
|
|
330
|
+
`nx-sk serve` 打开的是**可停靠的工作区**(Notion 式壳),不是一栏一页:
|
|
331
|
+
|
|
332
|
+
- **目录树**(左侧面板):栏目 + 分组 + 条目子节点。拖拽重排与嵌套——第一次拖动会把
|
|
333
|
+
「从旧导航配置推断出的树」固化成显式 `settings.navTree`(`settings get` 里
|
|
334
|
+
`navTreeSource: explicit`,之前始终 `inferred` 只读不写回);隐藏的栏目收在树底,一键恢复。
|
|
335
|
+
- **布局 = FlexLayout 模型**:数据库 / 资料 / 文件 / 导出 / 设置都是面板,可拖到任意一边拆分、
|
|
336
|
+
弹出成浮窗;布局存 localStorage(`nx-sk-ui.workspace`),跨会话恢复,顶栏可撤销/重做。
|
|
337
|
+
- **两段深链**:`#/栏目` 开该栏目的数据库面板,`#/栏目/条目` 再定位到条目;
|
|
338
|
+
栏目 / 条目缺失时明确提示是哪一级没了。
|
|
339
|
+
- 栏目页(数据库面板)顶部是**视图 chips**(表格 / 精简 / 看板 / KV,见 §六);
|
|
340
|
+
左侧条目列表带完整度,右侧按分组渲染的字段表单。
|
|
341
|
+
- 密文字段默认显示原文;顶栏「打码」等价于 `--mask`(选择持久化在 localStorage);
|
|
342
|
+
- **栏目结构自己能搭**:栏目面板里点某个栏目的「编辑」,弹窗里分组可新增 / 改名(含换 id)/
|
|
343
|
+
上下挪 / 删(空的才让删),字段可改标签 / 类型 / 分组 / 提示 / 必填策略、组内上下挪、删除
|
|
344
|
+
—— 一次改动一次落盘,与 CLI 的 `--add-group` 等是同一批 action(见 §七「栏目结构」)。
|
|
229
345
|
- 保存是 **PATCH**:只有被你改动过的字段才会发出去(面板会显示「N 处改动」);
|
|
230
|
-
-
|
|
346
|
+
- 详细页下半部分是**块面板**(见 §五),AI 提议是评审条:渲染 diff + 应用 / 拒绝。
|
|
231
347
|
|
|
232
348
|
面板上没有 CLI 做不到的事——两边共享同一套 action 声明。
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# 特殊字段:值不是标量的那几种
|
|
2
|
+
|
|
3
|
+
大多数字段的值是标量(一行字、一个数字、一个日期)。这一篇只讲**值不是标量**的字段,
|
|
4
|
+
以及它们各自的规则、写入时的体检、空值与默认值怎么处理:
|
|
5
|
+
|
|
6
|
+
`table`(表格)· `entrylist`(结构清单)· `md`(图文)· `file`(附件)· `source`(原始资料袋)· `secret`(密文)
|
|
7
|
+
|
|
8
|
+
> 为什么要单独一篇:这些字段的**值形状**决定了怎么读、怎么写、怎么在面板上编。
|
|
9
|
+
> 把它们当普通字符串塞进去,最常见的后果不是报错,而是「存进去了但面板看不见」——
|
|
10
|
+
> 那比报错难查得多。
|
|
11
|
+
|
|
12
|
+
## 速查
|
|
13
|
+
|
|
14
|
+
| type | 值形状 | 结构(列)归谁 | 面板怎么编 | 读它 |
|
|
15
|
+
| --- | --- | --- | --- | --- |
|
|
16
|
+
| `table` | `{v, columns, rows, totals?, summary?}` | **数据自己**(字段定义只给初始列) | 表格控件 + 「列设置」;**拖表头搬列、拖行尾 ⠿ 搬行** | `entry table` / `entry get` |
|
|
17
|
+
| `entrylist` | `[{列key: 值}, …]` | 字段字典的 `fields` | 密集迷你表(直接增删行,**拖 ⠿ 调行序**) | `entry get` |
|
|
18
|
+
| `md` | 一段 markdown 字符串 | — | 图文编辑器(Ctrl+V 贴图) | `entry get`(图片还原成路径) |
|
|
19
|
+
| `file` | `[附件id, …]` | 字段字典的 `kind` / `maxItems` | 附件选择器(上传 / 从库里选) | `entry get`(附件名 + 物理路径) |
|
|
20
|
+
| `source` | `[{id, kind, name, text\|fileId\|url, addedAt, …}]` | 内置(每个栏目自带一个) | 底部折叠条 → 右侧抽屉 | `source get` |
|
|
21
|
+
| `secret` | 一个字符串(落盘是密文) | — | 输入框 | `key get` / `entry get` |
|
|
22
|
+
|
|
23
|
+
共同点:**写入即校验**(不合法就整条拒绝,不会存半条)、**空值有明确语义**、
|
|
24
|
+
字段值只在这一处定义(面板与 CLI 不会各理解一套)。
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## `table` 表格
|
|
29
|
+
|
|
30
|
+
### 结构归数据,不归栏目
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"columns": [
|
|
35
|
+
{"key":"task","label":"任务","type":"text"},
|
|
36
|
+
{"key":"state","label":"状态","type":"select","options":["未开始","进行中","已完成"]},
|
|
37
|
+
{"key":"done","label":"已办","type":"bool"},
|
|
38
|
+
{"key":"hours","label":"工时","type":"number"},
|
|
39
|
+
{"key":"rate","label":"单价","type":"number","total":"avg"},
|
|
40
|
+
{"key":"cost","label":"费用","formula":"hours * rate","unit":"元"}
|
|
41
|
+
],
|
|
42
|
+
"rows": [{"task":"写文档","state":"已完成","done":true,"hours":2,"rate":100}],
|
|
43
|
+
"totals": [{"label":"完成率","expr":"pct(countTrue(col(\"done\")), n)","unit":"%"}]
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- **列定义、行、公式、统计配置全在值里**。字段字典里的 `columns` 只是**初始列**
|
|
48
|
+
(新建条目时表格长什么样),条目一旦有了自己的 `columns` 就以数据为准。
|
|
49
|
+
所以「这一条想多一列」不必改 schema,也不会影响同栏目其它条目。
|
|
50
|
+
- 值可以整体是 `{v:1, columns, rows}`,也可以是**行数组**(列取初始列或从行推断)。
|
|
51
|
+
- 必填的只有「能自洽」:有行就必须有列;没列没行 = 空(见下面「空与默认」)。
|
|
52
|
+
|
|
53
|
+
### 列(column)的每个键
|
|
54
|
+
|
|
55
|
+
| 键 | 说明 |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| `key` | 列标识,也是公式里的变量名。中文可以,但不能有空白 / `/` `\` / `..` |
|
|
58
|
+
| `label` | 表头显示名。**中文列名也能直接当公式变量**(`工时 * 单价`) |
|
|
59
|
+
| `type` | `text` \| `textarea` \| `number` \| `bool` \| `select` \| `date` \| `month` \| `tags` |
|
|
60
|
+
| `formula` | 给了就是**计算列**(不落盘、不可编辑、读时按顺序现算) |
|
|
61
|
+
| `options` | 仅 `select`:候选项数组,**必须给**;写入时值必须在列表里 |
|
|
62
|
+
| `total` | 表尾这一格怎么算:`sum` `avg` `min` `max` `count` `countTrue` `countFalse` `distinct` `median` `first` `last` `none` |
|
|
63
|
+
| `sensitive` | `true` = 密文落盘(与顶层敏感字段同一条边界);计算列不能是密文列 |
|
|
64
|
+
| `width` / `align` / `precision` / `unit` / `hint` | 显示用:列宽(px) / 对齐 / 小数位(0-8) / 单位 / 悬停提示 |
|
|
65
|
+
| `default` | **新增行时的初值**(按类型强转;`0` / `false` 都合法;不写进已有行) |
|
|
66
|
+
|
|
67
|
+
未声明 `total` 时的默认:数字列 `sum`、勾选列 `countTrue`、其它不统计。
|
|
68
|
+
|
|
69
|
+
### 公式:JS 表达式,不是自造语法
|
|
70
|
+
|
|
71
|
+
公式只被包成 `return ( … )` 求值,所以**语句写不进来**(`for` / `var` 在这里=语法错)。
|
|
72
|
+
|
|
73
|
+
- 变量:列 `key`、中文 `label`、`row` / `行`(原值,空格子是 `null`)、`rows` / `表`(整张表)、
|
|
74
|
+
`i`(行号)、`n`(行数);`col("单价")` 取一整列。
|
|
75
|
+
- 内建:`sum avg min max count countTrue countFalse distinct uniq median first last join`
|
|
76
|
+
/ `round floor ceil abs pct ratio clamp` / `toNum isBlank ifEmpty fixed`
|
|
77
|
+
/ `Math Number String Boolean Array Object JSON Date`。
|
|
78
|
+
- **顺序**:计算列按声明顺序算,只能引用排在它**前面**的列(引用自己或后面的列 = 成环,直接拒绝)。
|
|
79
|
+
- **空格子**在短变量里当 `0` / `false` / `''`(`hours * rate` 不会因为空格子变 NaN);
|
|
80
|
+
要判「到底填没填」用 `isBlank(row.hours)` 或 `row.hours === null`。
|
|
81
|
+
- 取不到全局:`window` / `document` / `process` / `fetch` / `require` 一律报「不存在的名字」。
|
|
82
|
+
这不是安全沙箱(公式是数据所有者自己写的),而是把写错的边界前移。
|
|
83
|
+
|
|
84
|
+
### 统计:两个轴
|
|
85
|
+
|
|
86
|
+
1. **列上的 `total`** → 表尾那一格。多种统计方式会自动分组成多行
|
|
87
|
+
(`sum` 与 `countTrue` 都是「合计」,`avg` / `max` / `median` 各成一行)。
|
|
88
|
+
2. **值里的 `totals`** → 整表表达式行,如
|
|
89
|
+
`{"label":"完成率","expr":"pct(countTrue(col(\"done\")), n)","unit":"%"}`,
|
|
90
|
+
也可写 `{"label":"合计","agg":{"工时":"sum","费用":"sum"}}`(写了 `agg` 就接管整块表尾)。
|
|
91
|
+
|
|
92
|
+
`summary: false` 关掉整块表尾;`totals: []` 同样表示「不要表尾」。
|
|
93
|
+
统计**不落盘**,每次读现算——不会出现「存下来的合计和现在的数据对不上」。
|
|
94
|
+
|
|
95
|
+
### 写入即体检(不通过就不保存)
|
|
96
|
+
|
|
97
|
+
写入路径(`section update --add-field`、`entry add/update`)会对**每一条公式**做一次
|
|
98
|
+
静态体检:拿一行空值当探针跑一遍,只拦**与数据无关**的错:
|
|
99
|
+
|
|
100
|
+
| 拦(定义/数据写错了) | 放行(这条数据不巧,渲染时逐格报) |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| 语法错:`hours *` | 除以 0 → `#错误:结果不是有限数字` |
|
|
103
|
+
| 名字解析不到:`qty` 打错、引用自己或后面的计算列、`col("不存在的列")` | 对空格子做类型操作抛的错(换个数据就没事) |
|
|
104
|
+
| 结果不是单值:返回数组 / 对象(该用 `join`) | |
|
|
105
|
+
|
|
106
|
+
列、行、默认值、下拉候选、`total`、`totals` 全部在这条路径上校验;
|
|
107
|
+
**面板与 CLI 走同一个函数**,不可能出现「面板能存的列,CLI 存不进去」。
|
|
108
|
+
|
|
109
|
+
### 空与默认
|
|
110
|
+
|
|
111
|
+
「清空」= 清掉**行**。列还留不留,看你有没有在字段定义里给初始列:
|
|
112
|
+
|
|
113
|
+
| 写入 | 结果 |
|
|
114
|
+
| --- | --- |
|
|
115
|
+
| `--set 表=` / `[]` / `{}` / `{"columns":[],"rows":[]}` | 清掉所有行。**没有初始列**时值 = `null`(字段真空了);**有初始列**时留下骨架(列在、行空) |
|
|
116
|
+
| `{"columns":[…],"rows":[]}` | 骨架:列齐、没有行,下一步直接填 |
|
|
117
|
+
| `{"columns":[],"rows":[{…}]}` | **报错**:有数据没列,没法强转 |
|
|
118
|
+
| 全空行 | 写入时剔除(不占位) |
|
|
119
|
+
|
|
120
|
+
默认值只在**新增行**时用(面板「添加行」按列的 `default` 预填),不会回头改已有行;
|
|
121
|
+
字段级的默认是:初始列 + 表尾自动统计(数字 sum / 勾选 countTrue)+ 列类型默认 text。
|
|
122
|
+
|
|
123
|
+
### 面板上怎么调顺序(拖)
|
|
124
|
+
|
|
125
|
+
排序是表格最常见的编辑动作之一,所以**行与列都能拖**,不用去点箭头:
|
|
126
|
+
|
|
127
|
+
- **搬列**:直接拖**表头**(表头里没有输入框,不会跟选词打架);「列设置」里每列前面的 ⠿
|
|
128
|
+
也能拖,效果一样。
|
|
129
|
+
- **搬行**:拖行尾的 ⠿。整行 `draggable` 不这么做——那会跟单元格里选文本冲突
|
|
130
|
+
(想选一段字结果把行拖走了),所以把手是唯一的拖拽入口。
|
|
131
|
+
- 松手前会有一条**插入线**落在上/下半(行)或左/右半(列)的位置:线在哪就插到哪。
|
|
132
|
+
只高亮「这一行」是做不到这件事的。
|
|
133
|
+
- ↑↓ / ←→ 保留(鼠标悬停在行上才浮出来),键盘与「就挪一格」的场景仍然走得通;
|
|
134
|
+
行内操作键统一是 16px 的小图标键——密集表里的按钮不该抢内容的注意力。
|
|
135
|
+
|
|
136
|
+
`entrylist` 的行同理(拖 ⠿),删除键也从「一颗正常大小的按钮」换成了小图标键。
|
|
137
|
+
|
|
138
|
+
### 常见错 → 改法
|
|
139
|
+
|
|
140
|
+
| 报错 | 改法 |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `公式里用了不存在的名字「qty」…可用的名字:a、b` | 列名打错,或那列还没加 |
|
|
143
|
+
| `「x」是计算列…只能引用排在它前面的列` | 把被引用的计算列往前挪 |
|
|
144
|
+
| `列「密码」既是密文列又是计算列` | 计算列不落盘,加密没意义;二选一 |
|
|
145
|
+
| `列「状态」是下拉框(select),必须给 options` | 补 `options`,或把类型改回 `text` |
|
|
146
|
+
| `不在候选里(可选:…)` | 写入的下拉值不在 `options` 里 |
|
|
147
|
+
| `需要数字,收到「两小时」` | 数字列只能写数字(`1,200` 这种千分位也认) |
|
|
148
|
+
| `有 N 行数据却没有任何列` | 把 `columns` 一起写进值里 |
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## `entrylist` 结构清单
|
|
153
|
+
|
|
154
|
+
- 值 = **行对象的数组**,列在字段字典的 `fields` 里(`{key, label, sensitive, hint}`)。
|
|
155
|
+
- 适合「一个条目挂多组 链接/账号/密码」这类**列固定、行变长**的密集结构。
|
|
156
|
+
- 列名用 key 或中文标签都认;全空行剔除;`sensitive: true` 的列密文落盘。
|
|
157
|
+
- 与 `table` 的分界线:**列会不会每条都不一样 / 需不需要类型和计算**。会 → `table`;不会 → `entrylist`。
|
|
158
|
+
|
|
159
|
+
## `md` 图文
|
|
160
|
+
|
|
161
|
+
- 值 = 一段 markdown 正文;图片用 `` 引用附件库里的图(外链也直接显示)。
|
|
162
|
+
- 正文即真相:预览里勾选待办就是改正文那一行的 `[x]`,没有第二份「勾选状态」。
|
|
163
|
+
- `entry get` 会把本地图片引用还原成「[图片: 说明] 本地路径」,方便 agent 直接读文件。
|
|
164
|
+
|
|
165
|
+
## `file` 附件
|
|
166
|
+
|
|
167
|
+
- 值 = **附件 id 的列表**(不是路径),一个字段可挂多个;id 全局唯一,原件的物理路径由附件库管。
|
|
168
|
+
- `sensitive` 不适用(附件本身不是密文);`maxItems` 限个数。
|
|
169
|
+
- 上传 / 选择发生在**字段里**;`nx-sk file get <id>` 可反查被谁引用。
|
|
170
|
+
|
|
171
|
+
## `source` 原始资料袋
|
|
172
|
+
|
|
173
|
+
- 每个非 KV 栏目自带一个:杂乱资料先**原样**入袋(不改写),之后按字段字典整理。
|
|
174
|
+
- **`text` 的底层是 markdown**——聊天记录图文混排,图和文不能分开存:
|
|
175
|
+
正文里直接写 ``(附件库的图)或 ``(外链图);
|
|
176
|
+
面板抽屉里图片 Ctrl+V / 拖进编辑器就自动上传并插入引用。
|
|
177
|
+
普通文字本来就是合法 markdown,老数据不用迁移。
|
|
178
|
+
- 不计完整度(`fill: optional`);袋里是明文,**敏感内容不要进袋**。
|
|
179
|
+
|
|
180
|
+
## `secret` 密文
|
|
181
|
+
|
|
182
|
+
- 值是一个字符串,落盘 AES-256-GCM 密文;读出来默认原文,`--mask` 打码。
|
|
183
|
+
- 键名像凭据(密码 / token / key / 账号…)时**自动**建成这种字段,不必先声明 schema。
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## 共同规矩
|
|
188
|
+
|
|
189
|
+
1. **密文边界只有一条**:`sensitive` 字段 / `entrylist` 与 `table` 的 `sensitive` 列,
|
|
190
|
+
都是密文落盘、默认原文、`--mask` 打码。面板把打码值原样回传时保留原密文(不把掩码存成新值)。
|
|
191
|
+
*已知限制*:打码状态下若两格打码值一模一样(短密码全是星)又拖动了行,无法判断谁是谁——打码时别调行序。
|
|
192
|
+
2. **空只有两种落盘形态**:`null`(结构 + 数据都空)或「只含 `columns` 的骨架」(结构在、行空)。
|
|
193
|
+
写入什么形态进去(`''` / `[]` / `{}`)都会被归一,读出来不会出现半吊子形状 ——
|
|
194
|
+
所以「值是不是空」判 `null` 就够,不必再猜 `[]` 还是 `''`。
|
|
195
|
+
3. **完整度只看「有没有数据」**:有列没行的表算**没填**(不会把进度撑满),但它的骨架会照常带出去。
|
|
196
|
+
4. **写入即校验**:类型、候选值、公式、默认值全部在写入路径上验;错就整条拒绝并给出**能照着改**的话。
|
|
197
|
+
5. **面板与 CLI 是同一套业务**:这里写的每条规则对两边都成立,没有「面板能存、CLI 存不进去」的列。
|
|
@@ -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` 正文里写了 `` | 图文字段正文 | 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
|
-
##
|
|
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
|
-
##
|
|
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
|
-
##
|
|
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
|
-
##
|
|
172
|
+
## 九、看不到 `file` 上传字段 / 条目里解析不到附件
|
|
137
173
|
|
|
138
174
|
1. **栏目里没有这类字段** —— 栏目字段台账是**持久化数据**:栏目实例化时深拷贝模板字段,
|
|
139
175
|
此后独立演化,模板**后来**新增的字段不会自动回溯到已建栏目。用
|
|
@@ -74,9 +74,14 @@ bundle.json 包清单:包含哪些栏目、整体口令说明
|
|
|
74
74
|
sections/<id>.zip 每个栏目一个上面的单栏目包(逐栏目复用同一套逻辑)
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
- 只打包**条目实际引用**的附件:`file` 字段的 id + `md` 正文里的 `
|
|
77
|
+
- 只打包**条目实际引用**的附件:`file` 字段的 id + `md` 正文里的 `` + `file` **块**里的 id。
|
|
78
78
|
- 导入时附件按 **sha256 去重**:本机已有同一份文件就复用,不会存两份。
|
|
79
|
-
- 条目里的旧 file id 会**自动重映射**到新 id(`file`
|
|
79
|
+
- 条目里的旧 file id 会**自动重映射**到新 id(`file` 字段数组、`file` 块与 md 图片引用都改)。
|
|
80
|
+
- 包版本(`manifest.formatVersion`):**2** 起,包里多 `entries[].body`(块正文)与
|
|
81
|
+
`section.views`(视图配置)。老版本读到 2 号包会明确报「版本过新」,
|
|
82
|
+
不会把这两个键静默丢掉;manifest 里**没有这个键**(0.20 及更早的包)视为 1 号包——
|
|
83
|
+
无正文/无视图,照常导入。
|
|
84
|
+
- 导入时视图配置只在「新建栏目」或「目标没配过视图」时应用——目标已有自己的视图就不覆盖(预览里会提示)。
|
|
80
85
|
- `import-new` 会看包结构自动判断是单栏目包还是整库包,不用手动挑命令。
|
|
81
86
|
|
|
82
87
|
## 口令加密(transfer 层)
|
|
@@ -102,8 +107,9 @@ sections/<id>.zip 每个栏目一个上面的单栏目包(逐栏目复
|
|
|
102
107
|
包里**恒为明文**,保护只靠口令 —— 没有「打码 / 明文」二选(0.11.0 之前的 `--no-secrets` 已移除)。
|
|
103
108
|
要发给别人的包就设口令;不设口令的包自己收好,别当分享件用。
|
|
104
109
|
|
|
105
|
-
读取侧仍兼容旧打码包:遇到 `******`
|
|
106
|
-
|
|
110
|
+
读取侧仍兼容旧打码包:遇到 `******` 会跳过该字段并计数,不会把打码串当新密码存进去;
|
|
111
|
+
**密钥块**同一条口径——打码的密钥块保留、值清空待重填(预览会统计「密钥块打码 N 个」)。
|
|
112
|
+
导入后敏感字段与密钥块用**本机 vaultKey** 重新加密落盘,与手填的没有区别。
|
|
107
113
|
|
|
108
114
|
## 限制与坑
|
|
109
115
|
|
|
@@ -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.
|
|
3
|
+
"version": "0.23.0",
|
|
4
4
|
"description": "nx-sk · 本机个人资源管理器(server-cli-web 骨架):栏目化存储个人信息与大模型密钥,CLI 与 Web 同源,敏感字段密文落盘。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -18,11 +18,11 @@
|
|
|
18
18
|
},
|
|
19
19
|
"repository": {
|
|
20
20
|
"type": "git",
|
|
21
|
-
"url": "https://github.com/
|
|
21
|
+
"url": "https://github.com/On-DevPlan/nx-sk.git"
|
|
22
22
|
},
|
|
23
|
-
"homepage": "https://github.com/
|
|
23
|
+
"homepage": "https://github.com/On-DevPlan/nx-sk#readme",
|
|
24
24
|
"bugs": {
|
|
25
|
-
"url": "https://github.com/
|
|
25
|
+
"url": "https://github.com/On-DevPlan/nx-sk/issues"
|
|
26
26
|
},
|
|
27
27
|
"packageManager": "pnpm@9.12.0",
|
|
28
28
|
"nxSk": {
|
|
@@ -37,12 +37,23 @@
|
|
|
37
37
|
"dev:serve": "node bin/nx-sk.mjs serve --no-open",
|
|
38
38
|
"build": "vite build && node scripts/link-local.mjs --auto",
|
|
39
39
|
"start": "pnpm run build && node bin/nx-sk.mjs serve",
|
|
40
|
+
"proto:dev": "vite --config plan/block-refactor/prototype/vite.config.js",
|
|
41
|
+
"proto:build": "vite build --config plan/block-refactor/prototype/vite.config.js",
|
|
42
|
+
"loop:on": "node scripts/rp-loop.mjs on",
|
|
43
|
+
"loop:off": "node scripts/rp-loop.mjs off",
|
|
44
|
+
"loop:status": "node scripts/rp-loop.mjs status",
|
|
45
|
+
"loop:log": "node scripts/rp-loop.mjs log",
|
|
46
|
+
"loop:cancel": "node scripts/rp-loop.mjs cancel",
|
|
40
47
|
"lint": "eslint .",
|
|
41
48
|
"test:unit": "node --test",
|
|
42
49
|
"test:smoke": "node tests/smoke.mjs",
|
|
43
50
|
"test": "pnpm run lint && pnpm run build && pnpm run test:smoke && pnpm run test:unit"
|
|
44
51
|
},
|
|
45
52
|
"dependencies": {
|
|
53
|
+
"@dnd-kit/core": "^6.3.1",
|
|
54
|
+
"@dnd-kit/sortable": "^10.0.0",
|
|
55
|
+
"@dnd-kit/utilities": "^3.2.2",
|
|
56
|
+
"flexlayout-react": "0.11.1",
|
|
46
57
|
"react": "^18.3.1",
|
|
47
58
|
"react-dom": "^18.3.1",
|
|
48
59
|
"react-markdown": "^10.1.0",
|