@coreyuan/vector-mind 1.0.48 → 1.0.52

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 (117) hide show
  1. package/README.md +146 -394
  2. package/dist/activity-log.d.ts +19 -0
  3. package/dist/activity-log.js +106 -0
  4. package/dist/activity-log.js.map +1 -0
  5. package/dist/builtin-conventions.d.ts +2 -1
  6. package/dist/builtin-conventions.js +7 -2
  7. package/dist/builtin-conventions.js.map +1 -1
  8. package/dist/builtin-instructions.d.ts +1 -1
  9. package/dist/builtin-instructions.js +1 -1
  10. package/dist/builtin-instructions.js.map +1 -1
  11. package/dist/config.d.ts +28 -0
  12. package/dist/config.js +189 -0
  13. package/dist/config.js.map +1 -0
  14. package/dist/database-runtime.d.ts +54 -0
  15. package/dist/database-runtime.js +512 -0
  16. package/dist/database-runtime.js.map +1 -0
  17. package/dist/development-warnings.d.ts +93 -0
  18. package/dist/development-warnings.js +589 -0
  19. package/dist/development-warnings.js.map +1 -0
  20. package/dist/file-indexing.d.ts +22 -0
  21. package/dist/file-indexing.js +243 -0
  22. package/dist/file-indexing.js.map +1 -0
  23. package/dist/grep.d.ts +64 -0
  24. package/dist/grep.js +475 -0
  25. package/dist/grep.js.map +1 -0
  26. package/dist/index.js +167 -6884
  27. package/dist/index.js.map +1 -1
  28. package/dist/large-file-split.d.ts +29 -0
  29. package/dist/large-file-split.js +146 -0
  30. package/dist/large-file-split.js.map +1 -0
  31. package/dist/memory-maintenance.d.ts +80 -0
  32. package/dist/memory-maintenance.js +537 -0
  33. package/dist/memory-maintenance.js.map +1 -0
  34. package/dist/memory-mutations.d.ts +23 -0
  35. package/dist/memory-mutations.js +83 -0
  36. package/dist/memory-mutations.js.map +1 -0
  37. package/dist/memory-recall.d.ts +93 -0
  38. package/dist/memory-recall.js +796 -0
  39. package/dist/memory-recall.js.map +1 -0
  40. package/dist/path-filters.d.ts +1 -0
  41. package/dist/path-filters.js +27 -0
  42. package/dist/path-filters.js.map +1 -0
  43. package/dist/path-rules.d.ts +12 -0
  44. package/dist/path-rules.js +208 -0
  45. package/dist/path-rules.js.map +1 -0
  46. package/dist/pending-changes.d.ts +22 -0
  47. package/dist/pending-changes.js +166 -0
  48. package/dist/pending-changes.js.map +1 -0
  49. package/dist/project-files.d.ts +66 -0
  50. package/dist/project-files.js +215 -0
  51. package/dist/project-files.js.map +1 -0
  52. package/dist/root.d.ts +15 -0
  53. package/dist/root.js +191 -0
  54. package/dist/root.js.map +1 -0
  55. package/dist/rtk-tools.d.ts +20 -0
  56. package/dist/rtk-tools.js +318 -0
  57. package/dist/rtk-tools.js.map +1 -0
  58. package/dist/server-instructions.d.ts +1 -0
  59. package/dist/server-instructions.js +88 -0
  60. package/dist/server-instructions.js.map +1 -0
  61. package/dist/symbols.d.ts +2 -0
  62. package/dist/symbols.js +159 -0
  63. package/dist/symbols.js.map +1 -0
  64. package/dist/token-savings.d.ts +40 -0
  65. package/dist/token-savings.js +50 -0
  66. package/dist/token-savings.js.map +1 -0
  67. package/dist/tool-catalog.d.ts +18 -0
  68. package/dist/tool-catalog.js +243 -0
  69. package/dist/tool-catalog.js.map +1 -0
  70. package/dist/tool-handlers/context-recovery.d.ts +6 -0
  71. package/dist/tool-handlers/context-recovery.js +319 -0
  72. package/dist/tool-handlers/context-recovery.js.map +1 -0
  73. package/dist/tool-handlers/context.d.ts +34 -0
  74. package/dist/tool-handlers/context.js +2 -0
  75. package/dist/tool-handlers/context.js.map +1 -0
  76. package/dist/tool-handlers/diagnostics.d.ts +8 -0
  77. package/dist/tool-handlers/diagnostics.js +114 -0
  78. package/dist/tool-handlers/diagnostics.js.map +1 -0
  79. package/dist/tool-handlers/files.d.ts +8 -0
  80. package/dist/tool-handlers/files.js +493 -0
  81. package/dist/tool-handlers/files.js.map +1 -0
  82. package/dist/tool-handlers/large-files.d.ts +4 -0
  83. package/dist/tool-handlers/large-files.js +139 -0
  84. package/dist/tool-handlers/large-files.js.map +1 -0
  85. package/dist/tool-handlers/maintenance.d.ts +4 -0
  86. package/dist/tool-handlers/maintenance.js +160 -0
  87. package/dist/tool-handlers/maintenance.js.map +1 -0
  88. package/dist/tool-handlers/memory-diagnostics.d.ts +5 -0
  89. package/dist/tool-handlers/memory-diagnostics.js +509 -0
  90. package/dist/tool-handlers/memory-diagnostics.js.map +1 -0
  91. package/dist/tool-handlers/memory.d.ts +6 -0
  92. package/dist/tool-handlers/memory.js +334 -0
  93. package/dist/tool-handlers/memory.js.map +1 -0
  94. package/dist/tool-handlers/notes-decisions.d.ts +7 -0
  95. package/dist/tool-handlers/notes-decisions.js +169 -0
  96. package/dist/tool-handlers/notes-decisions.js.map +1 -0
  97. package/dist/tool-handlers/requirements.d.ts +7 -0
  98. package/dist/tool-handlers/requirements.js +357 -0
  99. package/dist/tool-handlers/requirements.js.map +1 -0
  100. package/dist/tool-handlers.d.ts +4 -0
  101. package/dist/tool-handlers.js +105 -0
  102. package/dist/tool-handlers.js.map +1 -0
  103. package/dist/tool-output.d.ts +213 -0
  104. package/dist/tool-output.js +278 -0
  105. package/dist/tool-output.js.map +1 -0
  106. package/dist/tool-schemas.d.ts +434 -0
  107. package/dist/tool-schemas.js +328 -0
  108. package/dist/tool-schemas.js.map +1 -0
  109. package/dist/types.d.ts +61 -0
  110. package/dist/types.js +2 -0
  111. package/dist/types.js.map +1 -0
  112. package/docs/capability-matrix.md +43 -0
  113. package/package.json +11 -10
  114. package/skills/vector-mind-autopilot/SKILL.md +149 -0
  115. package/skills/vector-mind-autopilot/references/claude-desktop-mcp-config.json +9 -0
  116. package/skills/vector-mind-autopilot/references/claude-project-instructions.md +47 -0
  117. package/skills/vector-mind-autopilot/references/universal-system-prompt.md +78 -0
package/README.md CHANGED
@@ -1,394 +1,146 @@
1
- # VectorMind MCP
2
-
3
- VectorMind 是一个给 AI 编程助手使用的本地项目记忆 MCP。
4
-
5
- 它不只是“记笔记”,而是把需求、决策、代码改动、文件变化、项目约定、代码定位、上下文恢复都串起来,让 AI 在长期开发中更稳定地理解项目。
6
-
7
- 适合这些场景:
8
-
9
- - 一个项目要连续开发很多天。
10
- - 需求经常变更,旧逻辑容易被误用。
11
- - AI 经常忘记前面为什么这样改。
12
- - 换新会话后,希望 AI 能接着上次上下文继续做。
13
- - 想让 AI 少猜路径、少乱翻文件、少输出大量无用日志。
14
-
15
- 当前版本:
16
-
17
- ```text
18
- 1.0.48
19
- ```
20
-
21
- ---
22
-
23
- ## 它能做什么
24
-
25
- ### 1. 项目上下文恢复
26
-
27
- 新会话开始时,VectorMind 可以把项目最近的状态恢复给 AI:
28
-
29
- - 当前项目总结
30
- - 最新决策
31
- - 当前近期上下文
32
- - 最近需求
33
- - 最近改动原因
34
- - 待同步文件变化
35
- - 和当前任务相关的历史记录
36
- - 当前改动是否过大、是否在继续堆大文件
37
-
38
- 这样 AI 不需要只靠当前聊天窗口猜项目背景。
39
-
40
- ---
41
-
42
- ### 2. 需求驱动开发
43
-
44
- 每个开发任务都可以先记录成一个需求。
45
-
46
- AI 在改代码前知道:
47
-
48
- - 这次要做什么
49
- - 为什么要做
50
- - 当前任务是否已经完成
51
- - 后续改动应该归属到哪个需求
52
-
53
- 这能避免“改了很多文件,但没人知道当时为什么改”的问题。
54
-
55
- ---
56
-
57
- ### 3. 改动意图记录
58
-
59
- 每次改完代码后,VectorMind 可以记录这次改动的原因。
60
-
61
- 比如:
62
-
63
- ```text
64
- 将任务申请流程改为提交后直接通过,并移除上级审核分支。
65
- ```
66
-
67
- 以后 AI 再看到这些文件时,不只是知道“代码变了”,还能知道“为什么这么变”。
68
-
69
- ---
70
-
71
- ### 4. 最新决策优先
72
-
73
- 这是 VectorMind 很重要的一类能力。
74
-
75
- 例如:
76
-
77
- > 一开始任务申请需要上级审核,后来改成申请直接通过。
78
-
79
- 后续 AI 再修改审核相关功能时,应该优先相信最新决策,而不是旧需求。
80
-
81
- VectorMind 支持把新决策写成“当前权威决定”,并把旧需求或旧记录标记为过时。这样可以减少 AI 把功能改回老版本的问题。
82
-
83
- ---
84
-
85
- ### 5. 项目总结、笔记和约定
86
-
87
- VectorMind 可以长期保存项目级信息,例如:
88
-
89
- - 项目整体说明
90
- - 架构说明
91
- - 业务规则
92
- - 命名规范
93
- - 构建命令
94
- - 不要再改回去的产品决策
95
- - 后续 TODO
96
-
97
- 这些内容会在后续会话中自动参与上下文恢复。
98
-
99
- ---
100
-
101
- ### 6. 代码库定位
102
-
103
- VectorMind 会维护项目文件和代码符号索引,让 AI 更容易回答:
104
-
105
- - 这个函数在哪?
106
- - 这个类在哪定义?
107
- - 哪些文件提到了这个功能?
108
- - 某个配置在哪里?
109
-
110
- 它提供比“让 AI 猜路径”更稳定的代码定位方式。
111
-
112
- ---
113
-
114
- ### 7. 项目文件阅读与搜索
115
-
116
- VectorMind 提供适合 AI 使用的文件工具:
117
-
118
- - 列出项目文件
119
- - 读取指定文件片段
120
- - 按行读取代码
121
- - 搜索项目文本
122
- - 读取 Codex skill / prompt / rule 文件
123
-
124
- 这些工具都有输出限制,避免一次性把大量文件内容塞进上下文。
125
-
126
- ---
127
-
128
- ### 8. 本地语义检索
129
-
130
- VectorMind 可以从本地记忆中搜索相关内容,包括:
131
-
132
- - 需求
133
- - 改动意图
134
- - 决策
135
- - 笔记
136
- - 项目总结
137
- - 代码片段
138
- - 文档片段
139
-
140
- 默认即可本地检索,并会优先保留明确文字匹配和最新决策;如果需要,也可以开启 embeddings 增强语义召回。
141
-
142
- ---
143
-
144
- ### 9. Pending Changes 跟踪
145
-
146
- VectorMind 会记录“文件已经变化,但还没有同步改动意图”的状态。
147
-
148
- 这样 AI 可以在改完文件后检查:
149
-
150
- - 哪些文件还没记录原因
151
- - 哪些改动还没归到当前需求
152
- - 是否漏同步了某些文件
153
-
154
- 同时也会结合 Git 工作区状态作为补充,降低文件监听漏掉变化的风险。
155
-
156
- ---
157
-
158
- ### 10. 开发边界提醒
159
-
160
- VectorMind 会提醒 AI 避免几类常见问题:
161
-
162
- - 把新功能一直堆到一个大文件里
163
- - 一次需求改太多无关文件
164
- - 顺手改已完成的其他功能
165
- - 自己加用户没说的新需求
166
-
167
- 如果检测到文件过大、改动范围过散、读取/搜索跨出了当前项目,或计划改动超出了当前需求的通用范围约定,工具会返回 `development_warnings`。现在可以在改代码前用 `preflight_change_scope` 先检查目标文件;如果返回 `safe_to_edit=false`,AI 应该先停下来收窄范围,不等到改完后才发现问题。
168
-
169
- ---
170
-
171
- ### 11. 自动维护记忆和索引
172
-
173
- VectorMind 会定期做轻量维护:
174
-
175
- - 把很久以前、已经完成的需求和改动记录压缩成摘要
176
- - 保留最新决策、项目约定和项目总结
177
- - 清理已经不存在、已忽略或明显无用的旧索引
178
- - 降低大项目长期使用后的检索压力
179
-
180
- 如果感觉项目越用越慢,可以让 AI 先检查维护计划,再执行清理。
181
-
182
- ---
183
-
184
- ### 12. 低 token 输出
185
-
186
- VectorMind 的常用工具默认返回 compact 输出,而不是大段 JSON。
187
-
188
- 好处:
189
-
190
- - 新会话恢复更轻
191
- - 搜索结果更短
192
- - 文件读取更可控
193
- - 不容易把上下文撑爆
194
-
195
- 需要完整结构化数据时,也可以显式要求 JSON。
196
-
197
- ---
198
-
199
- ### 13. RTK 集成
200
-
201
- VectorMind 包里带了一个 `rtk` 命令入口。
202
-
203
- 它可以帮助压缩 shell 命令输出,减少命令日志对 AI 上下文的占用。
204
-
205
- 常见用法:
206
-
207
- ```bash
208
- rtk git status
209
- rtk npm run build
210
- rtk rg "keyword" src
211
- ```
212
-
213
- ---
214
-
215
- ### 14. 内置开发规范
216
-
217
- VectorMind MCP 会提供一些有用的开发规范,例如:
218
-
219
- - 轻量计划
220
- - 架构和代码组织
221
- - UI 输出不要泄露提示词
222
- - git 提交说明要包含改动总结
223
- - 长线程和大输出要尽量克制
224
- - 破坏性操作要有风险意识
225
- - 不要把新功能持续堆到一个大文件
226
- - 不要乱改当前需求以外的已完成功能
227
- - 不要自行叠加用户没提出的新需求
228
-
229
- 这些内容只用于统一项目协作、代码组织、交付质量和长期记忆。
230
-
231
- ---
232
-
233
- ## 安装
234
-
235
- 推荐直接通过 npx 使用:
236
-
237
- ```bash
238
- npx -y @coreyuan/vector-mind
239
- ```
240
-
241
- 也可以全局安装:
242
-
243
- ```bash
244
- npm install -g @coreyuan/vector-mind
245
- ```
246
-
247
- 全局安装后会提供:
248
-
249
- ```text
250
- vector-mind
251
- rtk
252
- ```
253
-
254
- ---
255
-
256
- ## Codex 配置示例
257
-
258
- 在 `~/.codex/config.toml` 中添加:
259
-
260
- ```toml
261
- [mcp_servers.vector-mind]
262
- type = "stdio"
263
- command = "npx"
264
- args = ["-y", "@coreyuan/vector-mind"]
265
- ```
266
-
267
- 配置后重启 Codex。
268
-
269
- ---
270
-
271
- ## Claude Desktop 配置示例
272
-
273
- ```json
274
- {
275
- "mcpServers": {
276
- "vector-mind": {
277
- "command": "npx",
278
- "args": ["-y", "@coreyuan/vector-mind"]
279
- }
280
- }
281
- }
282
- ```
283
-
284
- ---
285
-
286
- ## 推荐使用方式
287
-
288
- ### 新会话开始
289
-
290
- 可以这样对 AI 说:
291
-
292
- ```text
293
- 先用 VectorMind 恢复这个项目的上下文,再继续做。
294
- ```
295
-
296
- ### 开始新需求
297
-
298
- ```text
299
- 先记录这个需求:任务申请提交后直接通过,不需要上级审核。
300
- ```
301
-
302
- ### 改完代码后
303
-
304
- ```text
305
- 把这次改动原因同步到 VectorMind。
306
- ```
307
-
308
- ### 需求变更时
309
-
310
- ```text
311
- 这是最新决定:任务申请不再需要上级审核,申请后直接通过。请写入 VectorMind,并标记旧审核需求已过时。
312
- ```
313
-
314
- 这类“最新决定”非常重要。它能帮助 AI 后续优先使用新规则,而不是旧记录。
315
-
316
- ---
317
-
318
- ## 主要工具能力
319
-
320
- 你平时不需要记工具名,让 AI 自己调用即可。下面是 VectorMind 暴露的主要能力:
321
-
322
- | 能力 | 工具 |
323
- | --- | --- |
324
- | 恢复上下文 | `bootstrap_context`, `get_brain_dump` |
325
- | 记录需求 | `start_requirement`, `complete_requirement` |
326
- | 记录改动原因 | `sync_change_intent`, `get_pending_changes` |
327
- | 检查开发边界 | `preflight_change_scope`, `read_file_lines`, `grep`, `query_codebase`, `get_pending_changes`, `sync_change_intent` 返回的 `development_warnings` |
328
- | 保存最新决策 | `upsert_decision`, `supersede_memory` |
329
- | 保存长期信息 | `upsert_project_summary`, `add_note`, `upsert_convention` |
330
- | 搜历史上下文 | `semantic_search`, `read_memory_item` |
331
- | 自动维护记忆和索引 | `maintain_memory`, `prune_index` |
332
- | 找代码位置 | `query_codebase`, `grep` |
333
- | 读项目文件 | `list_project_files`, `read_file_lines`, `read_file_text` |
334
- | 读 Codex 配置/技能文件 | `read_codex_text_file` |
335
- | 减少命令输出 token | `detect_rtk`, `install_rtk`, `get_token_savings` |
336
- | 调试 | `get_activity_summary`, `get_activity_log`, `clear_activity_log` |
337
-
338
- ---
339
-
340
- ## 多项目使用
341
-
342
- 如果你同时在多个项目中使用 VectorMind,建议告诉 AI 当前项目路径:
343
-
344
- ```text
345
- 这个任务的项目路径是 H:\2025\YourProject,请 VectorMind 使用这个 project_root。
346
- ```
347
-
348
- 这样每个项目都会有自己的本地记忆,避免混在一起。
349
-
350
- 默认数据位置:
351
-
352
- ```text
353
- <project>/.vectormind/
354
- ```
355
-
356
- ---
357
-
358
- ## 隐私说明
359
-
360
- VectorMind 默认把数据保存在项目本地。
361
-
362
- 不开启 embeddings 时,记忆检索主要在本地完成,不需要上传代码。即使开启 embeddings,也可以通过环境配置控制模型和缓存位置。
363
-
364
- ---
365
-
366
- ## 更新后不生效怎么办
367
-
368
- 如果刚升级或发布了新版本,但客户端里看起来没变化:
369
-
370
- 1. 重启 Codex / VS Code / Claude 等客户端。
371
- 2. 开一个新会话。
372
- 3. 确认 MCP 配置仍然指向:
373
-
374
- ```bash
375
- npx -y @coreyuan/vector-mind
376
- ```
377
-
378
- ---
379
-
380
- ## 开发与发布
381
-
382
- ```bash
383
- npm install
384
- npm run build
385
- npm run smoke -- --roots=off --use-tool-project-root
386
- npm publish --access public
387
- ```
388
-
389
- ---
390
-
391
- ## 一句话总结
392
-
393
- VectorMind MCP 是一个面向 AI 编程助手的本地项目记忆系统。
394
- 它让 AI 记住需求、决策、改动原因和项目约定,在长期开发中少丢上下文、少猜代码、少把旧功能改回来。
1
+ # VectorMind MCP
2
+
3
+ VectorMind 是给 AI 编程助手用的本地项目记忆 MCP。
4
+
5
+ 它会把“当前在做什么、为什么这样改、哪些决策已经更新、哪些文件不能乱动”保存到项目本地,帮助 AI 在长期开发里少丢上下文、少猜路径、少把旧功能改回来。
6
+
7
+ 当前版本:`1.0.52`
8
+
9
+ ## 它能做什么
10
+
11
+ - **恢复上下文**:新会话可以找回项目摘要、最近需求、最近改动、决策、约定和待同步文件。
12
+ - **守住需求边界**:修改前先确认当前需求和计划文件,减少乱改无关模块。
13
+ - **记录改动原因**:改完后保存“改了什么、为什么改”,后续会话能接上。
14
+ - **让新决策覆盖旧记忆**:需求反转或规则更新后,可以标记旧记忆过时,避免 AI 按旧规则回退功能。
15
+ - **查看上下文时间线**:按需求、文件、记忆或关键词查看前后发生了什么,帮助判断新旧关系。
16
+ - **保存会话检查点**:长会话或交接前保存 waypoint,后续只读恢复上下文,不改变模型判断。
17
+ - **诊断记忆质量**:检查记忆冲突、重复记忆和 checkpoint 差异,只给证据,不自动修改。
18
+ - **沉淀项目知识**:保存架构说明、构建命令、命名规则、注意事项和 TODO。
19
+ - **定位代码和搜索文本**:帮 AI 找函数、类、配置、关键逻辑,不靠猜。
20
+ - **安全读取文件**:按目录、按行、按大小读取,避免一次塞入过多上下文。
21
+ - **治理巨量文件**:遇到几千行实现文件,会要求先做真实模块拆分,不继续往大文件里堆代码。
22
+ - **维护长期记忆**:压缩过时记忆、清理无效索引,减轻大项目越用越慢的问题。
23
+ - **减少输出占用**:默认返回简洁结果,并可配合 `rtk` 降低命令输出负担。
24
+
25
+ 更完整的能力表见:`docs/capability-matrix.md`
26
+
27
+ ## 推荐工作流
28
+
29
+ 开发任务建议让 AI 按这个顺序使用:
30
+
31
+ 1. 恢复上下文:`bootstrap_context`
32
+ 2. 记录当前需求:`start_requirement`
33
+ 3. 修改前检查范围:`preflight_change_scope`
34
+ 4. 修改文件
35
+ 5. 查看未同步改动:`get_pending_changes`
36
+ 6. 同步改动原因:`sync_change_intent`
37
+ 7. 需求规则变化时:`upsert_decision` / `supersede_memory`
38
+ 8. 完成后:`upsert_project_summary` / `complete_requirement`
39
+
40
+ ## 巨量文件规则
41
+
42
+ 当实现文件达到巨量阈值时,VectorMind 会提示:
43
+
44
+ - 不要继续往这个文件里加新功能。
45
+ - 先做机械搬迁式模块化拆分。
46
+ - 使用真实模块名和清晰目录。
47
+ - 禁止 `*.generated.*`、`.parts`、`*.rs.parts`、`part1/part2` 这类假拆分。
48
+ - 拆分计划和结果会被记录,后续会话知道这个文件正在或已经被治理。
49
+
50
+ ## 它不做什么
51
+
52
+ VectorMind 只定义开发规范、记忆和质量约束。
53
+
54
+ 它的输出只是上下文证据和质量信号,不替模型做决定,不削弱模型自己的推理、判断、创造和实现能力。
55
+
56
+ 它不接管 Codex、Claude 或其他客户端的运行控制,也不处理客户端自己的确认弹窗、执行策略或访问设置。
57
+
58
+ ## 安装
59
+
60
+ ```bash
61
+ npx -y @coreyuan/vector-mind
62
+ ```
63
+
64
+ 或全局安装:
65
+
66
+ ```bash
67
+ npm install -g @coreyuan/vector-mind
68
+ ```
69
+
70
+ 全局安装后可用:
71
+
72
+ ```text
73
+ vector-mind
74
+ rtk
75
+ ```
76
+
77
+ ## Codex 配置
78
+
79
+ `~/.codex/config.toml` 添加:
80
+
81
+ ```toml
82
+ [mcp_servers.vector-mind]
83
+ type = "stdio"
84
+ command = "npx"
85
+ args = ["-y", "@coreyuan/vector-mind"]
86
+ ```
87
+
88
+ 配置后重启 Codex,并开启新会话。
89
+
90
+ ## Claude Desktop 配置
91
+
92
+ ```json
93
+ {
94
+ "mcpServers": {
95
+ "vector-mind": {
96
+ "command": "npx",
97
+ "args": ["-y", "@coreyuan/vector-mind"]
98
+ }
99
+ }
100
+ }
101
+ ```
102
+
103
+ ## 多项目使用
104
+
105
+ 建议明确告诉 AI 当前项目路径:
106
+
107
+ ```text
108
+ 这个任务的项目路径是 H:\2025\YourProject,请 VectorMind 使用这个 project_root。
109
+ ```
110
+
111
+ 每个项目的数据默认保存在:
112
+
113
+ ```text
114
+ <project>/.vectormind/
115
+ ```
116
+
117
+ ## 常用工具
118
+
119
+ | 能力 | 工具 |
120
+ | --- | --- |
121
+ | 恢复上下文 | `bootstrap_context`, `get_brain_dump` |
122
+ | 需求管理 | `start_requirement`, `preflight_change_scope`, `complete_requirement` |
123
+ | 改动记录 | `sync_change_intent`, `get_pending_changes` |
124
+ | 决策更新 | `upsert_decision`, `supersede_memory` |
125
+ | 项目知识 | `upsert_project_summary`, `add_note`, `upsert_convention` |
126
+ | 时间线/检查点 | `memory_timeline`, `create_checkpoint`, `list_checkpoints`, `restore_checkpoint_context` |
127
+ | 记忆诊断 | `analyze_memory_conflicts`, `memory_quality_report`, `compare_checkpoint_context` |
128
+ | 代码定位 | `query_codebase`, `grep` |
129
+ | 读项目文件 | `list_project_files`, `read_file_lines`, `read_file_text` |
130
+ | 读 Codex 文本 | `read_codex_text_file` |
131
+ | 巨量文件拆分 | `plan_large_file_split`, `record_large_file_split` |
132
+ | 记忆维护 | `maintain_memory`, `prune_index` |
133
+ | 调试/降噪 | `get_activity_summary`, `get_activity_log`, `get_token_savings`, `detect_rtk` |
134
+
135
+ ## 开发与发布
136
+
137
+ ```bash
138
+ npm install
139
+ npm run build
140
+ npm run smoke -- --roots=off --use-tool-project-root
141
+ npm publish --access public
142
+ ```
143
+
144
+ ## 一句话
145
+
146
+ VectorMind 让 AI 记住需求、决策、改动原因和项目边界,在长期开发中少丢上下文、少乱改、少回退到旧逻辑。
@@ -0,0 +1,19 @@
1
+ export declare function configureActivityLogProjectRoot(fn: () => string): void;
2
+ type ActivityEvent = {
3
+ id: number;
4
+ ts: string;
5
+ type: string;
6
+ project_root: string;
7
+ data: Record<string, unknown>;
8
+ };
9
+ export declare function logActivity(type: string, data: Record<string, unknown>): void;
10
+ export declare function snapshotActivityLog(opts: {
11
+ sinceId: number;
12
+ limit: number;
13
+ }): {
14
+ events: ActivityEvent[];
15
+ last_id: number;
16
+ };
17
+ export declare function clearActivityLog(): void;
18
+ export declare function summarizeActivityEvent(e: ActivityEvent): string;
19
+ export {};
@@ -0,0 +1,106 @@
1
+ import { debugLogEnabled, debugLogMaxEntries } from "./config.js";
2
+ let getProjectRoot = () => "";
3
+ export function configureActivityLogProjectRoot(fn) {
4
+ getProjectRoot = fn;
5
+ }
6
+ let activitySeq = 0;
7
+ const activityLog = [];
8
+ function sanitizeForLog(value, depth = 0) {
9
+ if (depth > 4)
10
+ return "[max-depth]";
11
+ if (value === null || value === undefined)
12
+ return value;
13
+ if (typeof value === "string") {
14
+ return value.length > 500 ? `${value.slice(0, 500)}...` : value;
15
+ }
16
+ if (typeof value === "number" || typeof value === "boolean")
17
+ return value;
18
+ if (Array.isArray(value)) {
19
+ const sliced = value.slice(0, 20).map((v) => sanitizeForLog(v, depth + 1));
20
+ return value.length > 20 ? [...sliced, `[+${value.length - 20} more]`] : sliced;
21
+ }
22
+ if (typeof value === "object") {
23
+ const obj = value;
24
+ const keys = Object.keys(obj).slice(0, 40);
25
+ const out = {};
26
+ for (const k of keys)
27
+ out[k] = sanitizeForLog(obj[k], depth + 1);
28
+ if (Object.keys(obj).length > 40)
29
+ out["__more_keys__"] = Object.keys(obj).length - 40;
30
+ return out;
31
+ }
32
+ try {
33
+ return String(value);
34
+ }
35
+ catch {
36
+ return "[unserializable]";
37
+ }
38
+ }
39
+ export function logActivity(type, data) {
40
+ if (!debugLogEnabled)
41
+ return;
42
+ activityLog.push({
43
+ id: ++activitySeq,
44
+ ts: new Date().toISOString(),
45
+ type,
46
+ project_root: getProjectRoot() || "",
47
+ data: sanitizeForLog(data),
48
+ });
49
+ while (activityLog.length > debugLogMaxEntries)
50
+ activityLog.shift();
51
+ }
52
+ export function snapshotActivityLog(opts) {
53
+ const sinceId = Math.max(0, opts.sinceId);
54
+ const limit = Math.max(1, Math.min(500, opts.limit));
55
+ const lastId = activitySeq;
56
+ const events = activityLog.filter((e) => e.id > sinceId).slice(0, limit);
57
+ return { events, last_id: lastId };
58
+ }
59
+ export function clearActivityLog() {
60
+ activityLog.length = 0;
61
+ activitySeq = 0;
62
+ }
63
+ export function summarizeActivityEvent(e) {
64
+ const d = e.data ?? {};
65
+ switch (e.type) {
66
+ case "index_file":
67
+ return `index ${String(d.file_path ?? "")} reason=${String(d.reason ?? "")} symbols=${String(d.symbols ?? "")} chunks=${String(d.chunks ?? "")}`;
68
+ case "remove_file":
69
+ return `remove ${String(d.file_path ?? "")}`;
70
+ case "pending_flush":
71
+ return `pending_flush entries=${String(d.entries ?? "")}`;
72
+ case "pending_prune":
73
+ return `pending_prune ${String(d.before ?? "")}->${String(d.after ?? "")}`;
74
+ case "bootstrap_context":
75
+ return `bootstrap q=${String(d.query ?? "")} pending=${String(d.pending_returned ?? "")}/${String(d.pending_total ?? "")} reqs=${String(d.requirements_returned ?? "")} semantic=${String(d.semantic_mode ?? "")}+${String(d.semantic_matches ?? "")}`;
76
+ case "get_brain_dump":
77
+ return `brain_dump pending=${String(d.pending_returned ?? "")}/${String(d.pending_total ?? "")} reqs=${String(d.requirements_returned ?? "")} notes=${String(d.notes_returned ?? "")}`;
78
+ case "get_pending_changes":
79
+ return `pending_list returned=${String(d.returned ?? "")} total=${String(d.total ?? "")}`;
80
+ case "semantic_search":
81
+ return `semantic_search mode=${String(d.mode ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
82
+ case "grep":
83
+ return `grep backend=${String(d.backend ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
84
+ case "query_codebase":
85
+ return `query_codebase q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
86
+ case "read_file_lines":
87
+ return `read_file_lines file=${String(d.file_path ?? "")} returned=${String(d.returned ?? "")} truncated=${String(d.truncated ?? "")}`;
88
+ case "read_file_text":
89
+ return `read_file_text file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
90
+ case "list_project_files":
91
+ return `list_project_files path=${String(d.path ?? "")} returned=${String(d.returned ?? "")} scanned=${String(d.scanned ?? "")} truncated=${String(d.truncated ?? "")}`;
92
+ case "read_codex_text_file":
93
+ return `read_codex_text_file file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
94
+ case "start_requirement":
95
+ return `start_requirement #${String(d.req_id ?? "")} ${String(d.title ?? "")}`;
96
+ case "sync_change_intent":
97
+ return `sync_change_intent #${String(d.req_id ?? "")} files=${String(d.files_total ?? "")}`;
98
+ case "complete_requirement":
99
+ return `complete_requirement ${String(d.all_active ? "all_active" : d.req_id ?? "")}`;
100
+ case "memory_maintenance":
101
+ return `memory_maintenance trigger=${String(d.trigger ?? "")} compacted=${String(d.compacted ?? "")} stale=${String(d.stale_files ?? "")} chunks_deleted=${String(d.chunks_deleted ?? "")}`;
102
+ default:
103
+ return e.type;
104
+ }
105
+ }
106
+ //# sourceMappingURL=activity-log.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"activity-log.js","sourceRoot":"","sources":["../src/activity-log.ts"],"names":[],"mappings":"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"}