dsh-macro-memory 0.0.0-stage → 0.3.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 (130) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +457 -2
  3. package/cordis.patch.yml +6 -0
  4. package/lib/client.js +3623 -0
  5. package/lib/index.js +469 -0
  6. package/lib/macro/brand.js +82 -0
  7. package/lib/macro/bridge.js +158 -0
  8. package/lib/macro/chain.js +206 -0
  9. package/lib/macro/contract.js +471 -0
  10. package/lib/macro/cost.js +164 -0
  11. package/lib/macro/defs/admin.js +439 -0
  12. package/lib/macro/defs/dream.js +24 -0
  13. package/lib/macro/defs/link.js +257 -0
  14. package/lib/macro/defs/project.js +25 -0
  15. package/lib/macro/defs/read.js +145 -0
  16. package/lib/macro/defs/remember.js +213 -0
  17. package/lib/macro/defs/search.js +661 -0
  18. package/lib/macro/defs/update.js +161 -0
  19. package/lib/macro/dreamledger.js +1398 -0
  20. package/lib/macro/facade.js +135 -0
  21. package/lib/macro/fusion.js +182 -0
  22. package/lib/macro/linkflow.js +391 -0
  23. package/lib/macro/links.js +448 -0
  24. package/lib/macro/neighbor.js +209 -0
  25. package/lib/macro/panel.js +96 -0
  26. package/lib/macro/prompt.js +139 -0
  27. package/lib/macro/provenance.js +148 -0
  28. package/lib/macro/render.js +35 -0
  29. package/lib/macro/revisions.js +253 -0
  30. package/lib/macro/shared.js +113 -0
  31. package/lib/macro/store.js +103 -0
  32. package/lib/macro/tokencost.js +90 -0
  33. package/lib/macro/tools.js +67 -0
  34. package/package.json +54 -4
  35. package/vendor/VENDOR.json +23 -0
  36. package/vendor/dsh-memory-nebula/CONTRIBUTING.md +48 -0
  37. package/vendor/dsh-memory-nebula/LICENSE +21 -0
  38. package/vendor/dsh-memory-nebula/README.en.md +203 -0
  39. package/vendor/dsh-memory-nebula/README.md +253 -0
  40. package/vendor/dsh-memory-nebula/SECURITY.md +43 -0
  41. package/vendor/dsh-memory-nebula/SUPPORT.md +33 -0
  42. package/vendor/dsh-memory-nebula/cordis.patch.yml +4 -0
  43. package/vendor/dsh-memory-nebula/lib/client.js +105 -0
  44. package/vendor/dsh-memory-nebula/lib/host/adapters/index.js +279 -0
  45. package/vendor/dsh-memory-nebula/lib/host/adapters/ingest.js +230 -0
  46. package/vendor/dsh-memory-nebula/lib/host/adapters/meow.js +317 -0
  47. package/vendor/dsh-memory-nebula/lib/host/adapters/notes.js +305 -0
  48. package/vendor/dsh-memory-nebula/lib/host/adapters/sqlite.js +287 -0
  49. package/vendor/dsh-memory-nebula/lib/host/adapters/util.js +231 -0
  50. package/vendor/dsh-memory-nebula/lib/host/bridge.js +351 -0
  51. package/vendor/dsh-memory-nebula/lib/host/compress.js +97 -0
  52. package/vendor/dsh-memory-nebula/lib/host/demo.js +357 -0
  53. package/vendor/dsh-memory-nebula/lib/host/diagnostics.js +125 -0
  54. package/vendor/dsh-memory-nebula/lib/host/doctor.js +270 -0
  55. package/vendor/dsh-memory-nebula/lib/host/graph.js +1663 -0
  56. package/vendor/dsh-memory-nebula/lib/host/graphcache.js +282 -0
  57. package/vendor/dsh-memory-nebula/lib/host/http.js +993 -0
  58. package/vendor/dsh-memory-nebula/lib/host/injectcfg.js +95 -0
  59. package/vendor/dsh-memory-nebula/lib/host/ledger.js +175 -0
  60. package/vendor/dsh-memory-nebula/lib/host/live.js +204 -0
  61. package/vendor/dsh-memory-nebula/lib/host/nebula.js +2105 -0
  62. package/vendor/dsh-memory-nebula/lib/host/page.js +75 -0
  63. package/vendor/dsh-memory-nebula/lib/host/path.js +83 -0
  64. package/vendor/dsh-memory-nebula/lib/host/recall.js +451 -0
  65. package/vendor/dsh-memory-nebula/lib/host/share.js +633 -0
  66. package/vendor/dsh-memory-nebula/lib/host/sources.js +266 -0
  67. package/vendor/dsh-memory-nebula/lib/host/store.js +333 -0
  68. package/vendor/dsh-memory-nebula/lib/host/text.js +410 -0
  69. package/vendor/dsh-memory-nebula/lib/host/transcripts.js +396 -0
  70. package/vendor/dsh-memory-nebula/lib/index.js +759 -0
  71. package/vendor/dsh-memory-nebula/lib/standalone.mjs +315 -0
  72. package/vendor/dsh-memory-nebula/lib/web/api.js +426 -0
  73. package/vendor/dsh-memory-nebula/lib/web/app.js +4159 -0
  74. package/vendor/dsh-memory-nebula/lib/web/i18n.js +580 -0
  75. package/vendor/dsh-memory-nebula/lib/web/index.html +174 -0
  76. package/vendor/dsh-memory-nebula/lib/web/nav.js +132 -0
  77. package/vendor/dsh-memory-nebula/lib/web/render.js +1890 -0
  78. package/vendor/dsh-memory-nebula/lib/web/space3d.js +1883 -0
  79. package/vendor/dsh-memory-nebula/lib/web/style.css +1402 -0
  80. package/vendor/dsh-memory-nebula/locale/en.json +7 -0
  81. package/vendor/dsh-memory-nebula/locale/zh.json +7 -0
  82. package/vendor/dsh-memory-nebula/market/assets/icon-180.png +0 -0
  83. package/vendor/dsh-memory-nebula/market/assets/icon.svg +40 -0
  84. package/vendor/dsh-memory-nebula/market/index.json +101 -0
  85. package/vendor/dsh-memory-nebula/package.json +87 -0
  86. package/vendor/dsh-memory-nebula/sidecar.ps1 +119 -0
  87. package/vendor/meow-memory/LICENSE +21 -0
  88. package/vendor/meow-memory/README.en.md +192 -0
  89. package/vendor/meow-memory/README.md +174 -0
  90. package/vendor/meow-memory/README.pt-br.md +180 -0
  91. package/vendor/meow-memory/cordis.patch.yml +7 -0
  92. package/vendor/meow-memory/lib/client.js +3344 -0
  93. package/vendor/meow-memory/lib/client.js.map +7 -0
  94. package/vendor/meow-memory/lib/index.js +9567 -0
  95. package/vendor/meow-memory/lib/index.js.map +7 -0
  96. package/vendor/meow-memory/lib/prompts/README.md +65 -0
  97. package/vendor/meow-memory/lib/prompts/en/dream-atomic.md +36 -0
  98. package/vendor/meow-memory/lib/prompts/en/dream-header.md +9 -0
  99. package/vendor/meow-memory/lib/prompts/en/dream-project-summary.md +12 -0
  100. package/vendor/meow-memory/lib/prompts/en/dream-topic.md +27 -0
  101. package/vendor/meow-memory/lib/prompts/en/external-memory-notice.md +8 -0
  102. package/vendor/meow-memory/lib/prompts/en/first-create-notice.md +8 -0
  103. package/vendor/meow-memory/lib/prompts/en/labels.md +98 -0
  104. package/vendor/meow-memory/lib/prompts/en/reflect.md +31 -0
  105. package/vendor/meow-memory/lib/prompts/en/system-guide.md +121 -0
  106. package/vendor/meow-memory/lib/prompts/en/tools.md +83 -0
  107. package/vendor/meow-memory/lib/prompts/en/welcome-guide.md +12 -0
  108. package/vendor/meow-memory/lib/prompts/pt-br/dream-atomic.md +36 -0
  109. package/vendor/meow-memory/lib/prompts/pt-br/dream-header.md +9 -0
  110. package/vendor/meow-memory/lib/prompts/pt-br/dream-project-summary.md +12 -0
  111. package/vendor/meow-memory/lib/prompts/pt-br/dream-topic.md +27 -0
  112. package/vendor/meow-memory/lib/prompts/pt-br/external-memory-notice.md +8 -0
  113. package/vendor/meow-memory/lib/prompts/pt-br/first-create-notice.md +8 -0
  114. package/vendor/meow-memory/lib/prompts/pt-br/labels.md +98 -0
  115. package/vendor/meow-memory/lib/prompts/pt-br/reflect.md +31 -0
  116. package/vendor/meow-memory/lib/prompts/pt-br/system-guide.md +121 -0
  117. package/vendor/meow-memory/lib/prompts/pt-br/tools.md +83 -0
  118. package/vendor/meow-memory/lib/prompts/pt-br/welcome-guide.md +12 -0
  119. package/vendor/meow-memory/lib/prompts/zh/dream-atomic.md +36 -0
  120. package/vendor/meow-memory/lib/prompts/zh/dream-header.md +9 -0
  121. package/vendor/meow-memory/lib/prompts/zh/dream-project-summary.md +19 -0
  122. package/vendor/meow-memory/lib/prompts/zh/dream-topic.md +27 -0
  123. package/vendor/meow-memory/lib/prompts/zh/external-memory-notice.md +8 -0
  124. package/vendor/meow-memory/lib/prompts/zh/first-create-notice.md +8 -0
  125. package/vendor/meow-memory/lib/prompts/zh/labels.md +98 -0
  126. package/vendor/meow-memory/lib/prompts/zh/reflect.md +30 -0
  127. package/vendor/meow-memory/lib/prompts/zh/system-guide.md +119 -0
  128. package/vendor/meow-memory/lib/prompts/zh/tools.md +83 -0
  129. package/vendor/meow-memory/lib/prompts/zh/welcome-guide.md +12 -0
  130. package/vendor/meow-memory/package.json +64 -0
@@ -0,0 +1,287 @@
1
+ /**
2
+ * 适配器:sqlite —— 任意 SQLite 记忆库(列映射驱动)
3
+ *
4
+ * 现实里「记忆插件」的存储五花八门,但一大半最后都是 SQLite。
5
+ * 这个适配器不猜语义,只按配置把「表 → 层」「列 → 字段」对上:
6
+ *
7
+ * 多表模式: { "tables": { "fact": "facts", "lesson": "lessons" } }
8
+ * 单表模式: { "table": "memories", "levelField": "kind" }
9
+ *
10
+ * 没给 columns 时按常见列名自动猜(id / title / content / keywords …),
11
+ * 猜不到就跳过这一列,不会把库读炸。
12
+ *
13
+ * 只读:`new DatabaseSync(path, { readOnly: true })`。
14
+ */
15
+ import { existsSync, statSync } from 'node:fs'
16
+ import { DatabaseSync } from 'node:sqlite'
17
+ import { hashShort, slugKey, toKeywordList, toMs } from './util.js'
18
+
19
+ /** 列名候选:按优先级,命中第一个就用。 */
20
+ const COLUMN_HINTS = {
21
+ id: ['id', 'uid', 'key', 'uuid', 'memory_id', 'rowid'],
22
+ title: ['title', 'name', 'heading', 'subject', 'label'],
23
+ content: ['content', 'text', 'body', 'memory', 'detail', 'value', 'summary', 'description'],
24
+ keywords: ['keywords', 'tags', 'labels', 'keyword', 'tag'],
25
+ importance: ['importance', 'weight', 'priority', 'score', 'salience'],
26
+ project: ['project', 'project_name', 'scope', 'workspace'],
27
+ status: ['status', 'state', 'active', 'archived'],
28
+ created: ['created_at', 'createdAt', 'created', 'ctime', 'timestamp', 'ts', 'time'],
29
+ updated: ['updated_at', 'updatedAt', 'updated', 'mtime', 'modified'],
30
+ accessed: ['last_accessed_at', 'accessed_at', 'lastAccess', 'accessed'],
31
+ session: ['source_session', 'session_id', 'sessionId', 'session'],
32
+ hits: ['hit_count', 'hits', 'access_count', 'used_count', 'read_count'],
33
+ subcategory: ['subcategory', 'sub_category', 'subtype'],
34
+ goal: ['goal', 'objective', 'intent'],
35
+ level: ['level', 'kind', 'layer', 'category', 'type', 'mem_type'],
36
+ }
37
+
38
+ export const meta = {
39
+ id: 'sqlite',
40
+ name: 'SQLite 记忆库',
41
+ kind: 'sqlite',
42
+ description:
43
+ '把任意 SQLite 记忆库接进星图:配置表与列的对应关系即可。适合自己写的记忆插件、或换皮的同构实现。',
44
+ config: {
45
+ path: '必填。.db 文件绝对路径(支持 ~ 开头)。',
46
+ title: '展示名;默认取文件名。',
47
+ tables: '多表模式:{ 层名: 表名 },例如 {"fact":"facts","lesson":"lessons"}。',
48
+ table: '单表模式:表名;配合 levelField 使用。',
49
+ levelField: '单表模式下从哪列读层名,默认 level。',
50
+ defaultLevel: '读不到层名时用哪个,默认 note。',
51
+ columns: '列映射 { id, title, content, keywords, importance, project, status, created, updated, accessed, session, hits, subcategory, goal },缺省自动猜。',
52
+ where: '附加 SQL 过滤条件(只接受简单比较,不要写 UPDATE/DELETE)。',
53
+ },
54
+ }
55
+
56
+ function expandHome(p) {
57
+ const raw = String(p || '').trim()
58
+ if (!raw) return ''
59
+ if (raw === '~') return process.env.USERPROFILE || process.env.HOME || raw
60
+ if (raw.startsWith('~/') || raw.startsWith('~\\')) {
61
+ const home = process.env.USERPROFILE || process.env.HOME || ''
62
+ return home ? home + raw.slice(1) : raw
63
+ }
64
+ return raw
65
+ }
66
+
67
+ /** 拒绝任何会改写数据的 where(适配器是只读的,这里多一道闸)。 */
68
+ function safeWhere(where) {
69
+ const text = String(where || '').trim()
70
+ if (!text) return ''
71
+ if (/\b(insert|update|delete|drop|alter|attach|pragma|create|replace)\b/i.test(text)) return ''
72
+ return text
73
+ }
74
+
75
+ /** 列名自动猜:只在表的实际列里找。 */
76
+ function guessColumns(actualCols, given = {}) {
77
+ const out = {}
78
+ for (const [key, hints] of Object.entries(COLUMN_HINTS)) {
79
+ if (given[key]) {
80
+ out[key] = given[key]
81
+ continue
82
+ }
83
+ const lower = new Map([...actualCols].map((c) => [c.toLowerCase(), c]))
84
+ for (const hint of hints) {
85
+ const hit = lower.get(hint.toLowerCase())
86
+ if (hit) {
87
+ out[key] = hit
88
+ break
89
+ }
90
+ }
91
+ }
92
+ return out
93
+ }
94
+
95
+ function tableCols(db, table) {
96
+ try {
97
+ return db.prepare(`PRAGMA table_info(${quoteIdent(table)})`).all().map((c) => String(c.name))
98
+ } catch {
99
+ return []
100
+ }
101
+ }
102
+
103
+ function quoteIdent(name) {
104
+ return '"' + String(name).replace(/"/g, '""') + '"'
105
+ }
106
+
107
+ /** 在**已经打开**的库上列表(tableMap 手上有 handle,不必再开一次)。 */
108
+ function tablesOf(db) {
109
+ try {
110
+ return db
111
+ .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
112
+ .all()
113
+ .map((r) => String(r.name))
114
+ } catch {
115
+ return []
116
+ }
117
+ }
118
+
119
+ /** 列出库里所有普通表(探测/给 nebula_sources 用)。 */
120
+ export function listTables(dbPath) {
121
+ let db = null
122
+ try {
123
+ db = new DatabaseSync(dbPath, { readOnly: true })
124
+ return tablesOf(db)
125
+ } catch {
126
+ return []
127
+ } finally {
128
+ try {
129
+ db?.close()
130
+ } catch {
131
+ /* ignore */
132
+ }
133
+ }
134
+ }
135
+
136
+ /** 表 → 层的映射(多表 / 单表 / 兜底「表名就是层名」)。 */
137
+ function tableMap(db, config) {
138
+ const declared = config.tables && typeof config.tables === 'object' ? config.tables : null
139
+ if (declared && Object.keys(declared).length > 0) {
140
+ return Object.entries(declared).map(([level, table]) => ({ level, table: String(table) }))
141
+ }
142
+ if (config.table) {
143
+ return [{ level: null, table: String(config.table) }]
144
+ }
145
+ const KNOWN = ['soul', 'user', 'project', 'fact', 'lesson', 'topic', 'rules', 'note', 'notes', 'memory']
146
+ const all = tablesOf(db)
147
+ // 表名多是复数:facts → fact、memories → memory。认不出来才交给 defaultLevel。
148
+ const baseOf = (name) => {
149
+ const low = name.toLowerCase()
150
+ if (KNOWN.includes(low)) return low
151
+ if (low.endsWith('ies')) return low.slice(0, -3) + 'y'
152
+ if (low.endsWith('s')) return low.slice(0, -1)
153
+ return low
154
+ }
155
+ const known = all.filter((t) => KNOWN.includes(baseOf(t))).map((t) => ({ level: baseOf(t), table: t }))
156
+ if (known.length > 0) return known
157
+ return all.slice(0, 8).map((t) => ({ level: null, table: t }))
158
+ }
159
+
160
+ /** 探测:给了 path 且是真 sqlite 就产出一个 store。 */
161
+ export function detect(config = {}) {
162
+ const path = expandHome(config.path)
163
+ if (!path || !existsSync(path)) return []
164
+ let size = 0
165
+ let mtimeMs = 0
166
+ try {
167
+ const st = statSync(path)
168
+ if (!st.isFile()) return []
169
+ size = st.size
170
+ mtimeMs = st.mtimeMs
171
+ } catch {
172
+ return []
173
+ }
174
+ const tables = listTables(path)
175
+ if (tables.length === 0) return []
176
+ const title = String(config.title || '').trim() || path.split(/[\\/]/).pop().replace(/\.(db|sqlite3?|db3)$/i, '')
177
+ return [
178
+ {
179
+ id: 'sqlite:' + (config.id || slugKey(title)),
180
+ provider: String(config.provider || config.id || 'sqlite'),
181
+ adapter: 'sqlite',
182
+ title,
183
+ path,
184
+ key: slugKey(title, 'sqlite'),
185
+ dbPath: path,
186
+ size,
187
+ mtimeMs,
188
+ tables,
189
+ config,
190
+ },
191
+ ]
192
+ }
193
+
194
+ /** 扫描一个 sqlite store(生成器版:每 512 行让一次路)。 */
195
+ export function* scanSteps(store) {
196
+ const config = store.config || {}
197
+ const nodes = []
198
+ let db = null
199
+ try {
200
+ db = new DatabaseSync(store.dbPath, { readOnly: true })
201
+ } catch {
202
+ return { nodes, ledgers: [], error: '打不开 ' + store.dbPath }
203
+ }
204
+ try {
205
+ for (const { level, table } of tableMap(db, config)) {
206
+ const cols = tableCols(db, table)
207
+ if (cols.length === 0) continue
208
+ const map = guessColumns(cols, config.columns || {})
209
+ if (!map.content && !map.title) continue
210
+ const where = safeWhere(config.where)
211
+ let rows
212
+ try {
213
+ // iterate() 而不是 all():让取行跟着消费节奏走,中间能停。
214
+ rows = db.prepare(`SELECT * FROM ${quoteIdent(table)}${where ? ' WHERE ' + where : ''}`).iterate()
215
+ } catch {
216
+ continue
217
+ }
218
+ let batch = 0
219
+ for (const row of rows) {
220
+ if ((++batch & 511) === 0) yield 'rows'
221
+ const content = String(row[map.content] ?? '').trim()
222
+ const title = String(row[map.title] ?? '').trim()
223
+ if (!content && !title) continue
224
+ const rawId = String(row[map.id] ?? '').trim() || hashShort(title + '\u0000' + content)
225
+ const levelName = String(level || (map.level ? row[map.level] : '') || config.defaultLevel || 'note')
226
+ .trim()
227
+ .toLowerCase()
228
+ const uid = rawId
229
+ nodes.push({
230
+ id: `${store.key}:${levelName}:${uid}`.replace(/^/, 'sqlite:'),
231
+ uid,
232
+ provider: store.provider,
233
+ adapter: 'sqlite',
234
+ storeId: store.id,
235
+ ws: store.key,
236
+ wsTitle: store.title,
237
+ wsPath: store.path,
238
+ level: levelName || 'note',
239
+ title,
240
+ label: (title || content).length > 42 ? (title || content).slice(0, 42) + '…' : title || content,
241
+ content,
242
+ importance: Math.max(0, Math.min(4, Number(map.importance ? row[map.importance] : 0) || 0)),
243
+ status: String(map.status ? row[map.status] : 'active') || 'active',
244
+ project: String(map.project ? row[map.project] : '').trim(),
245
+ subcategory: String(map.subcategory ? row[map.subcategory] : '').trim(),
246
+ goal: String(map.goal ? row[map.goal] : ''),
247
+ corrected: false,
248
+ keywords: toKeywordList(map.keywords ? row[map.keywords] : ''),
249
+ sessionId: String(map.session ? row[map.session] : ''),
250
+ hits: Number(map.hits ? row[map.hits] : 0) || 0,
251
+ createdAt: toMs(map.created ? row[map.created] : 0),
252
+ updatedAt: toMs(map.updated ? row[map.updated] : 0) || toMs(map.created ? row[map.created] : 0),
253
+ accessedAt: toMs(map.accessed ? row[map.accessed] : 0),
254
+ table,
255
+ })
256
+ }
257
+ }
258
+ } finally {
259
+ try {
260
+ db.close()
261
+ } catch {
262
+ /* ignore */
263
+ }
264
+ }
265
+ return { nodes, ledgers: [] }
266
+ }
267
+
268
+ /** 同步壳:跑完 scanSteps 拿到结果(单测、脚本、MCP 工具走这条)。 */
269
+ export function scan(store) {
270
+ const it = scanSteps(store)
271
+ let step = it.next()
272
+ while (!step.done) step = it.next()
273
+ return step.value
274
+ }
275
+
276
+ export function probe(config = {}) {
277
+ const stores = detect(config)
278
+ if (stores.length === 0) {
279
+ return { ok: false, note: '不是可读的 SQLite 文件,或路径为空:' + (config.path || '(未配置 path)') }
280
+ }
281
+ const st = stores[0]
282
+ return {
283
+ ok: true,
284
+ stores: stores.map((s) => ({ id: s.id, title: s.title, db: s.dbPath, tables: s.tables })),
285
+ note: `${st.tables.length} 张表:${st.tables.slice(0, 8).join(', ')}`,
286
+ }
287
+ }
@@ -0,0 +1,231 @@
1
+ /**
2
+ * 适配器公用工具:所有适配器都从这里拿「读文件 / 走目录 / 抠 frontmatter / 造 id」。
3
+ *
4
+ * 这里只做纯函数与只读 IO。任何失败都吞掉并返回空,星图不能因为某个来源坏掉而整体挂。
5
+ */
6
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
7
+ import { basename, extname, join, relative } from 'node:path'
8
+ import { homedir } from 'node:os'
9
+ import { createHash } from 'node:crypto'
10
+
11
+ /** DSH 家目录。 */
12
+ export function dshHome() {
13
+ return process.env.DSH_HOME || join(homedir(), '.dsh')
14
+ }
15
+
16
+ /** 星图自己的数据目录(唯一我们写的地方)。 */
17
+ export function nebulaHome() {
18
+ return join(dshHome(), 'memory-nebula')
19
+ }
20
+
21
+ /** 安全读 JSON(Windows 上这些文件常带 BOM)。 */
22
+ export function readJsonSafe(file, fallback = null) {
23
+ try {
24
+ if (!existsSync(file)) return fallback
25
+ const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '')
26
+ if (!text.trim()) return fallback
27
+ return JSON.parse(text)
28
+ } catch {
29
+ return fallback
30
+ }
31
+ }
32
+
33
+ /** 安全读文本。 */
34
+ export function readTextSafe(file, limit = 0) {
35
+ try {
36
+ if (!existsSync(file)) return ''
37
+ const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '')
38
+ return limit > 0 ? text.slice(0, limit) : text
39
+ } catch {
40
+ return ''
41
+ }
42
+ }
43
+
44
+ /** 工作区短键:给人看、给 UI 上色、当 node id 的一段。 */
45
+ export function slugKey(text, fallback = 'ws') {
46
+ const raw = String(text || '').trim()
47
+ if (!raw) return fallback
48
+ const cleaned = raw.replace(/[\\/:*?"<>|\s]+/g, '').slice(0, 24)
49
+ return cleaned || fallback
50
+ }
51
+
52
+ /** 8 位短 hash(内容定位用,避免路径里的冒号/斜杠污染 id)。 */
53
+ export function hashShort(text) {
54
+ return createHash('sha1').update(String(text)).digest('hex').slice(0, 8)
55
+ }
56
+
57
+ /** 取首行/首句,当标题用。 */
58
+ export function firstLine(text, max = 46) {
59
+ const line = String(text || '')
60
+ .replace(/\r/g, '')
61
+ .split('\n')
62
+ .map((x) => x.trim())
63
+ .find((x) => x.length > 0)
64
+ const s = (line || '').replace(/^#+\s*/, '')
65
+ return s.length > max ? s.slice(0, max) + '…' : s
66
+ }
67
+
68
+ /**
69
+ * 极简 frontmatter 解析:只认 key: value 与 key: [a, b] / - 列表。
70
+ * 够读 SKILL.md、Obsidian 笔记、hindsight 知识页的头部;不引第三方 YAML。
71
+ */
72
+ export function parseFrontmatter(text) {
73
+ const src = String(text || '').replace(/^\uFEFF/, '')
74
+ const m = src.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
75
+ if (!m) return { data: {}, body: src }
76
+ const data = {}
77
+ let lastKey = ''
78
+ for (const line of m[1].split(/\r?\n/)) {
79
+ if (!line.trim() || line.trim().startsWith('#')) continue
80
+ const kv = line.match(/^([A-Za-z0-9_.-]+)\s*:\s*(.*)$/)
81
+ if (kv) {
82
+ lastKey = kv[1]
83
+ let value = kv[2].trim()
84
+ if (value.startsWith('[') && value.endsWith(']')) {
85
+ value = value
86
+ .slice(1, -1)
87
+ .split(',')
88
+ .map((x) => x.trim().replace(/^["']|["']$/g, ''))
89
+ .filter(Boolean)
90
+ } else {
91
+ value = value.replace(/^["']|["']$/g, '')
92
+ }
93
+ data[lastKey] = value
94
+ continue
95
+ }
96
+ const li = line.match(/^\s*-\s+(.*)$/)
97
+ if (li && lastKey) {
98
+ const cur = data[lastKey]
99
+ const value = li[1].trim().replace(/^["']|["']$/g, '')
100
+ if (Array.isArray(cur)) cur.push(value)
101
+ else data[lastKey] = [value]
102
+ }
103
+ }
104
+ return { data, body: src.slice(m[0].length) }
105
+ }
106
+
107
+ /**
108
+ * 递归列文件(受控:限制深度、数量、单文件大小)。
109
+ * @param {string} dir
110
+ * @param {{exts?:string[], maxDepth?:number, maxFiles?:number, skipDirs?:Set<string>}} opts
111
+ * @returns {{file:string, rel:string, size:number, mtimeMs:number}[]}
112
+ */
113
+ export function walkFiles(dir, opts = {}) {
114
+ const exts = (opts.exts || []).map((e) => e.toLowerCase())
115
+ const maxDepth = opts.maxDepth ?? 4
116
+ const maxFiles = opts.maxFiles ?? 4000
117
+ const skip = opts.skipDirs || new Set(['node_modules', '.git', 'dist', 'build', '.cache', '__pycache__'])
118
+ const out = []
119
+ const seen = new Set()
120
+
121
+ const visit = (current, depth) => {
122
+ if (out.length >= maxFiles) return
123
+ let names
124
+ try {
125
+ names = readdirSync(current, { withFileTypes: true })
126
+ } catch {
127
+ return
128
+ }
129
+ for (const ent of names) {
130
+ if (out.length >= maxFiles) return
131
+ const p = join(current, ent.name)
132
+ if (ent.isDirectory()) {
133
+ if (skip.has(ent.name) || ent.name.startsWith('.')) continue
134
+ if (depth >= maxDepth) continue
135
+ visit(p, depth + 1)
136
+ continue
137
+ }
138
+ if (!ent.isFile()) continue
139
+ const ext = extname(ent.name).toLowerCase()
140
+ if (exts.length > 0 && !exts.includes(ext)) continue
141
+ let st
142
+ try {
143
+ st = statSync(p)
144
+ } catch {
145
+ continue
146
+ }
147
+ if (seen.has(p)) continue
148
+ seen.add(p)
149
+ out.push({ file: p, rel: relative(dir, p).replace(/\\/g, '/'), size: st.size, mtimeMs: st.mtimeMs })
150
+ }
151
+ }
152
+ visit(dir, 0)
153
+ // 被 maxFiles 截断时调用方必须知道:少读的文件不会进图,也不会出现在签名里,
154
+ // 静默截断会让用户以为「我的笔记都在图里」(1.11.40)。
155
+ if (opts.stats) {
156
+ opts.stats.scanned = out.length
157
+ opts.stats.truncated = out.length >= maxFiles
158
+ }
159
+ return out
160
+ }
161
+
162
+ /** 目录里最新的 mtime(用来算变化指纹)。 */
163
+ export function newestMtime(dir, exts = []) {
164
+ const files = walkFiles(dir, { exts, maxDepth: 3, maxFiles: 800 })
165
+ let max = 0
166
+ for (const f of files) max = Math.max(max, Math.round(f.mtimeMs))
167
+ return { count: files.length, mtime: max }
168
+ }
169
+
170
+ /** 把任意值拍平成字符串关键词数组。 */
171
+ export function toKeywordList(value) {
172
+ if (!value) return []
173
+ if (Array.isArray(value)) return value.map((x) => String(x).trim()).filter(Boolean)
174
+ if (typeof value === 'string') {
175
+ return value
176
+ .split(/[,;,;、\s]+/)
177
+ .map((x) => x.trim())
178
+ .filter(Boolean)
179
+ }
180
+ return []
181
+ }
182
+
183
+ /** 字符数(中文按 1 算,够用)。 */
184
+ export function charLen(text) {
185
+ return String(text || '').length
186
+ }
187
+
188
+ /** 安全取字段(列名可能在配置里换过)。 */
189
+ export function pick(row, columns, key, fallback = '') {
190
+ const col = columns?.[key]
191
+ if (!col) return fallback
192
+ const value = row?.[col]
193
+ return value === null || value === undefined ? fallback : value
194
+ }
195
+
196
+ /** 常见时间列:秒 / 毫秒 / ISO 字符串都认。 */
197
+ export function toMs(value) {
198
+ if (value === null || value === undefined || value === '') return 0
199
+ if (typeof value === 'number') {
200
+ if (!Number.isFinite(value) || value <= 0) return 0
201
+ return value < 1e12 ? Math.round(value * 1000) : Math.round(value)
202
+ }
203
+ const num = Number(value)
204
+ if (Number.isFinite(num) && num > 0) return num < 1e12 ? Math.round(num * 1000) : Math.round(num)
205
+ const t = Date.parse(String(value))
206
+ return Number.isFinite(t) ? t : 0
207
+ }
208
+
209
+ /** 目录是否存在(不抛)。 */
210
+ export function dirExists(dir) {
211
+ try {
212
+ return !!dir && existsSync(dir) && statSync(dir).isDirectory()
213
+ } catch {
214
+ return false
215
+ }
216
+ }
217
+
218
+ /** 文件名去扩展名。 */
219
+ export function stem(name) {
220
+ return basename(String(name || '')).replace(/\.[^.]+$/, '')
221
+ }
222
+
223
+ /** 展开 ~ / ~/xx 为真实路径(Windows 用 USERPROFILE)。 */
224
+ export function expandHome(p) {
225
+ const raw = String(p || '').trim()
226
+ if (!raw) return ''
227
+ const home = process.env.USERPROFILE || process.env.HOME || ''
228
+ if (raw === '~') return home || raw
229
+ if (raw.startsWith('~/') || raw.startsWith('~\\')) return home ? home + raw.slice(1) : raw
230
+ return raw
231
+ }