1. 项目定位与核心目标

create-vkm-kit 自 v4.0.0 起更名为 vkm-kit，前身为 @vkmikc/create-obsidian-memory。它是一个面向 Claude Code 的"即插即用"效率套件，将原本分散的能力整合到统一安装器下，对外暴露两个二进制命令 create-vkm-kit 与 vkm，用户通过一条命令即可完成整个本地知识库的搭建 资料来源：README.md:1-30。

套件围绕四个支柱构建，v4.0.0 发布说明明确指出："one plug-and-play efficiency suite for Claude Code — persistent vault memory + token-saver + local usage doctor + spec-builder" 资料来源：v4.0.0 release notes。

• 持久化 Vault 记忆：基于 Obsidian / Markdown 的笔记仓库，跨会话保留项目知识。
• Token 节省器：通过最小化规则块减少每会话 token 消耗（v3.12.0 缩减约 18%）。
• 本地用量诊断：在本地运行 usage doctor，统计 token、缓存命中率等指标。
• 规范构建器（spec-builder）：根据项目目标自动生成结构化规范文档。

旧包名 @vkmikc/create-obsidian-memory 作为转发包保留，确保历史用户的 npx 命令仍可解析 资料来源：v4.0.0 release notes。

2. 系统架构总览

整体架构围绕一个本地 MCP（Model Context Protocol）服务器 obsidian-memory-hybrid 展开，安装器负责把 MCP 配置写入三个宿主（Cursor、Claude Code、Codex），并把 vault 目录初始化到项目根目录下。

flowchart TB
    User[开发者] -->|npx create-vkm-kit| Installer[create-vkm-kit 安装器]
    Installer -->|写入 mcp.json| Cursor[Cursor MCP 配置]
    Installer -->|claude mcp add| Claude[Claude Code MCP]
    Installer -->|codex mcp add| Codex[Codex MCP]
    Installer -->|初始化目录| Vault[(Vault / Obsidian 库)]
    Claude <-->|stdio| MCPServer[obsidian-memory-hybrid MCP 服务器]
    MCPServer <-->|读写| Vault
    MCPServer <-->|按需启动| SearXNG[本地 SearXNG]
    MCPServer -->|后台任务| Research[obscura_research 长任务]

v3.14.0 起，安装器默认注入 OBSIDIAN_MEMORY_PIN_FAILURES=1 与 OBSIDIAN_MEMORY_USAGE_BOOST=1 两个检索杠杆（ADR-0038），原因与 sqlite-vec 相同：纯排序杠杆优于遥测型杠杆 资料来源：v3.14.0 release notes。

3. 核心子系统

3.1 Vault 与规则契约

vault 脚手架在初始化时创建 RULES/TEMPLATE.md（es/en 双语）以及托管规则块。v3.15.0 引入的 RULES 契约要求每条项目规则都带有日期、来源与推理（ADR-0039） 资料来源：v3.15.0 release notes。多写入者安全由 v3.13.0 的乐观并发保证：vault_read_file 返回内容 etag + mtime，vault_write_file / vault_edit_file 接受 ifMatch 形参，写入冲突时返回可重试的 precondition failed（ADR-0037） 资料来源：v3.13.0 release notes。

3.2 强制执行钩子

v3.11.0 的 ADR-0030 引入确定性钩子，对任意模型都生效。其核心组件 guard-native-memory-write.mjs 在 PreToolUse 阶段拒绝针对 Claude Code 原生记忆路径的 Write / Edit / MultiEdit / NotebookEdit 调用，确保 ADR-0029 原则不被模型理解能力差异影响 资料来源：v3.11.0 release notes。

3.3 检索与搜索

obscura_search 在 v4.2.0 引入本地 SearXNG 结构化后端（ADR-0052），ensureSearxng() 在需要时按需启动，闲置窗口后自动停止，绕过反爬墙同时保持高速高量 资料来源：v4.2.0 release notes。v4.4.0 的 obscura_research 则在 MCP 服务器进程内启动最长 30 分钟的后台深度研究任务，逐轮复用 deepResearch，并产出每轮报告（ADR-0060） 资料来源：v4.4.0 release notes。

4. 包结构与部署

仓库为 monorepo 结构，根 package.json 协调多个子包，核心安装器位于 packages/create-vkm-kit/ 下 资料来源：package.json:1-40。入口 packages/create-vkm-kit/src/index.js 负责：解析 CLI 参数、检测宿主类型、写入对应 MCP 配置、生成 vault 模板，并输出回填指引 资料来源：packages/create-vkm-kit/src/index.js:1-120。

Agent 协作规约见 AGENTS.md，约定 vault 的目录结构、规则保存契约与多写入者协议 资料来源：AGENTS.md:1-40；架构细节图与多写入者序列、检索栈、记忆报告等示意图见 ARCHITECTURE.md 资料来源：ARCHITECTURE.md:1-40。双语文档 README.md（中文）与 README.en.md（英文）同步维护，v3.13.1 集中补齐了 how-it-works / como-funciona 中的多写入者安全与演进式记忆章节 资料来源：v3.13.1 release notes。

值得注意的演进决策：v4.3.0 移除了 token-saver 中的 permissions.deny 自动规则（ADR-0043 修正），因为日常使用中发现 Read(**/*.lock) 等硬阻断与手动拒绝无法区分，影响依赖解析等场景 资料来源：v4.3.0 release notes。

vkm-kit 的核心价值是把 Claude Code / Cursor / Codex 等多个 agent 的会话记忆沉淀到一份本地 Vault（仓库化的 Markdown 笔记库），并通过一个混合检索 MCP（Model Context Protocol）服务器在每次会话开始时按需回灌。围绕这条主线，仓库同时引入了三套机制：持久化的 Vault 文件系统、基于 sqlite-vec 与图谱的混合检索、基于 etag/ifMatch 的多写者乐观并发。这三者共同回答了三个问题：记忆落在哪里、如何被找到、以及多个 agent 同时改写时如何不丢更新。

Vault 持久化层

Vault 是一个普通的本地目录（默认位于 .obsidian-memory/），由 MCP 服务器作为唯一写入入口管理。vault-fs.mjs 负责把笔记的增删改查映射为原子文件操作，并提供 etag（基于内容哈希与 mtime）用于后续并发判断；vault-lock.mjs 则在更细粒度上对单条笔记加锁，避免读-改-写循环中出现撕裂。记忆按 RULES 合约（ADR-0039）拆分为"项目规则 / 一次性事实 / 演变型经验"三类，写入时通过 vault_write_file / vault_edit_file 两个工具落地，工具签名接受可选的 ifMatch 参数。

hybrid-mcp.mjs 是上述能力的对外门面：它把 vault_* 工具与一组 obscura_* / memory_* 检索工具一起注册到 MCP，让任何已接入的 IDE 都能直接调用，无需关心 Vault 的物理布局。

资料来源：packages/obsidian-memory-mcp/src/hybrid-mcp.mjs:1-120，packages/obsidian-memory-mcp/src/vault-fs.mjs:1-80，packages/obsidian-memory-mcp/src/vault-lock.mjs:1-60。

混合检索栈

检索不是单一的向量相似度，而是"BM25 关键词 + sqlite-vec 向量 + 知识图谱邻接"三层叠加，由 context-assemble.mjs 汇总打分后返回。

• 关键词层：使用 FTS5 风格的 BM25 抓取显式命中（函数名、错误码、专有名词）。
• 向量层：通过 rag-client.mjs 调到本地 obsidian-memory-rag 服务（Python 侧），底层是 sqlite-vec 存储，提供 ANN 检索。
• 图谱层：knowledge_graph.py 维护笔记之间的显式链接（[[wikilink]]、标签共现），用于补充向量检索难以触达的"一跳之外"的相关性。

排序之外还有两个可调杠杆（ADR-0038，自 v3.14.0 起默认开启）：

两个杠杆都是"排序级"而非"遥测级"，关闭后向量库原样保留，因此用户可以零成本回退。reflect: true 还会触发一次"反思回合"，把本次会话里被命中的笔记再次入榜，强化长期记忆回路。

资料来源：packages/obsidian-memory-mcp/src/context-assemble.mjs:1-140，packages/obsidian-memory-mcp/src/rag-client.mjs:1-90，packages/obsidian-memory-rag/src/obsidian_memory_rag/knowledge_graph.py:1-100。

多写者安全（乐观并发）

当 Vault 同时被多个 agent（甚至多台机器上的 IDE）写入时，最朴素的做法是"读完再写"，但这会复现经典的 *lost-update* 问题：Agent A 读到版本 1、改完要写回时，Agent B 已经把版本推到 2，A 的写入会无声覆盖 B 的更新。ADR-0037 引入了一个轻量的 HTTP 风格条件写入协议：

sequenceDiagram
    participant A as Agent A
    participant V as vault-fs
    participant B as Agent B
    A->>V: vault_read_file(note)
    V-->>A: {content, etag: e1, mtime: t1}
    B->>V: vault_write_file(note, ..., ifMatch=e1)
    V-->>B: 200 OK (etag: e2)
    A->>V: vault_write_file(note, ..., ifMatch=e1)
    V-->>A: 412 precondition failed (retryable)
    A->>V: vault_read_file(note)
    V-->>A: {content, etag: e2, mtime: t2}
    A->>V: vault_write_file(note, ..., ifMatch=e2)
    V-->>A: 200 OK (etag: e3)

关键设计点：

• etag 在不可信信封之外返回——vault_read_file 的返回结构里把 etag 与 mtime 提到与 content 同级，而不是埋在可信元数据里，方便客户端在每次重试时直接复用。
• ifMatch 是可选的——旧调用方不传时仍按"最后写入获胜"工作，因此这次升级对存量用户透明。
• 失败是可重试的 412 precondition failed——客户端拿到后只需重新 read → merge → write，无需人工介入。
• 配合 vault-lock.mjs 的细粒度锁——对短事务提供跨进程的互斥，覆盖乐观并发之外的"读-改-写"同进程竞争。

效果上，这套机制把"多 agent 共写一个 Vault"从高风险变成了受控事件；同时它也支撑了 v3.15.0 引入的 RULES 合约：每条规则都带日期与来源，写入时自然要走 ifMatch，避免在并发刷新中规则版本被回退。

资料来源：packages/obsidian-memory-mcp/src/vault-fs.mjs:40-160，packages/obsidian-memory-mcp/src/vault-lock.mjs:20-90，packages/obsidian-memory-mcp/src/hybrid-mcp.mjs:120-220。

小结

• 持久化：vault-fs.mjs + vault-lock.mjs 把 Markdown 笔记落到本地目录，所有写入经 MCP 工具，受 RULES 合约约束。
• 混合检索：context-assemble.mjs 汇总 BM25 / sqlite-vec / 知识图谱三层结果，并通过 pin_failures 与 usage_boost 两个零成本杠杆调节长期记忆的优先级。
• 多写者安全：ADR-0037 的 etag + ifMatch 协议让任何写入都可条件化，配合 412 precondition failed 的可重试语义，关闭了 lost-update 窗口。

三件事合在一起，使 Vault 成为多个 agent 都能安全共享的"项目长期记忆"，而不是一个随时被覆盖的临时缓存。

Token 节约：响应裁剪与权限精简

token-saver.mjs 是入口模块，负责生成 permissions.deny 列表与基于文件大小阈值的工具策略。早期版本会硬性 Read(**/*.lock)，但 v4.3.0（ADR-0043 修订）撤销了该自动 deny：Flutter 会话中需要读取 pubspec.lock 解决依赖约束时，自动 deny 与用户手动 deny 在 UI 上无法区分，触发了"无提示硬阻断"的体验事故。安装器现在主动清理遗留的 token-saver deny 规则，只保留白名单式 opt-in 规则 资料来源：packages/create-vkm-kit/src/token-saver.mjs:1-180。

真正承担上下文裁剪的是两条 PostToolUse 钩子：

• compact-tool-output.mjs 在 Bash / Read / Grep / Glob 输出进入模型前执行，按可读性优先的策略（保留头尾、折叠重复行、剥离 ANSI）将超出阈值的载荷压缩到目标字节数以内。
• compact-mcp-output.mjs 专门处理 MCP 服务器响应（如 obsidian-memory-hybrid 的 vault_* 与 obscura_search），结构化 JSON 按字段重要性分层裁剪，文本响应复用相同的头尾保留算法 资料来源：packages/create-vkm-kit/src/hooks/compact-tool-output.mjs:1-120、资料来源：packages/create-vkm-kit/src/hooks/compact-mcp-output.mjs:1-140。

本地诊断：OTel 汇与用量医生

诊断层不把遥测外发，而是写入本地 OTel sink。ensure-otel-sink.mjs 会在安装阶段检测 OTEL_EXPORTER_OTLP_ENDPOINT 等环境变量；当未配置外部 collector 时，按需启动一个本地 OTLP/HTTP 接收器（仅监听 127.0.0.1），把 span 与 metric 落到 .vkm/otel/ 目录下的滚动日志中，供 vkm doctor 子命令汇总 资料来源：packages/create-vkm-kit/src/hooks/ensure-otel-sink.mjs:1-90。

这一设计支撑了 v4.0.0 引入的"local usage doctor"：每次会话结束，doctor 汇总每个项目的 token 占用、压缩比、guard 触发次数，与 sqlite-vec 的 pin_failures / usage_boost（ADR-0038）等检索杠杆的表现叠加显示。遥测保持本地化的核心动机是：优化决策不能依赖外发到厂商的统计数据。

CI 守护：确定性执行钩子

最后一道防线是两条 PreToolUse 钩子，对应 ADR-0030 的"对任何模型都生效"的执行原则：

• guard-native-memory-write.mjs 拒绝指向 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md 等"原生记忆"路径的 Write / Edit / MultiEdit / NotebookEdit，把所有跨会话的状态写入收敛到 vkm 的 vault，而不是散落在原生记忆文件里。这条规则与 Claude Code 的 native-memory override 标志位联动，关闭 override 即同时关闭该 guard 资料来源：packages/create-vkm-kit/src/hooks/guard-native-memory-write.mjs:1-110。
• guard-effort-gate.mjs 在模型声明高推理 effort 之前校验前置条件（如必需的研究产物、必读的 RULES 条目），未满足时直接 deny 并提示补齐步骤，避免"高 effort 但证据不足"的浪费 资料来源：packages/create-vkm-kit/src/hooks/guard-effort-gate.mjs:1-95。

三层协作流程

flowchart LR
    A[工具/MCP 调用] --> B[PreToolUse 守卫]
    B -- 放行 --> C[工具执行]
    B -- deny --> X[阻断并提示]
    C --> D[PostToolUse 压缩]
    D --> E[OTel 本地汇]
    D --> F[模型上下文]
    E --> G[vkm doctor 报告]

裁剪只作用于已通过守卫生成的结果，守护只校验即将发生的调用，OTel 旁观整条链路，三者通过 ~/.vkm/state.json 中的会话 ID 关联，确保一次会话的 token 成本、guard 拦截、压缩收益能在同一份报告中交叉对照 资料来源：packages/create-vkm-kit/src/token-saver.mjs:200-260。

1. 技能体系的安装与契约

vkm-kit 把"可复用的工作流"打包成一组 SKILL.md，每一个 skill 是一个独立的目录，里面只放一段 Markdown 契约，对 Claude Code 暴露何时使用、如何调用与产出什么。安装器通过 skills-install.mjs 把 templates/skills/ 下登记的 skill 镜像同步到目标项目的 .claude/skills/ 或同等目录，确保每次 create-vkm-kit / vkm 执行后 skill 集合保持一致。

skill 之间有清晰的边界：

SKILL.md 顶部通常声明触发关键词与受管工具（如 obscura_search / obscura_research_start），并要求 skill 自身只消费这些受管工具，避免 skill 越权调用任意 Write / Bash。资料来源：packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md:1-40

2. Spec 规格化与构建工作流

vkm-spec 的核心是把"我说要做 X"翻译成"我会怎样验证 X 已经做好"。它读取 vault 中的 RULES 与历史决策笔记，按以下顺序推进：

1. 澄清阶段：把含糊表达拆成问题清单，逐条向用户确认或从 vault 检索。
2. 规格阶段：产出一份带验收标准的 Markdown，落到 RULES/ 之外的明示目录下。
3. 移交阶段：把规格转交给 vkm-implementer 代理执行，实现完成后回写"实现差异"段。

vkm-implementer 是模板中唯一的代理（agent），其指令文件位于 templates/agents/vkm-implementer.md，它的契约是：只能消费 spec 的输出，不能脱离 spec 自己新增范围。这避免了"边写代码边加需求"的常见漂移。资料来源：packages/create-vkm-kit/templates/skills/vkm-spec/SKILL.md:1-60、packages/create-vkm-kit/templates/agents/vkm-implementer.md:1-50

设计阶段由 vkm-design 承担，它要求先产出一张对比表或一段 ASCII 流程，再决定是否动 vkm-spec。这样做的目的是让"为什么这样切分"留下可回放的记录。资料来源：packages/create-vkm-kit/templates/skills/vkm-design/SKILL.md:1-40

3. 外部工具与代理联动

flowchart LR
  U[用户] -->|触发 skill| SK[SKILL.md]
  SK -->|调用受管工具| MCP[obsidian-memory-hybrid MCP]
  SK -->|需要外部数据| OBS[obscura_search / obscura_research]
  OBS -->|按需启动| SX[SearXNG 本地后端]
  OBS -->|多轮爬取| DR[deepResearch]
  MCP -->|读写 vault| V[(Obsidian Vault)]
  SK -->|移交 spec| AG[vkm-implementer]
  AG -->|回写实现笔记| V

vkm-research 把外部集成固定下来：任何联网动作都必须通过 MCP 提供的 obscura_search 与 obscura_research_start，禁止 skill 直接调用 WebFetch / 浏览器工具（ADR-0043 修正后，连 permissions.deny 这种隐式屏蔽也不被依赖）。obscura_search 在 v4.2.0 引入按需启动的 SearXNG（ADR-0052），ensureSearxng() 会在第一次调用时拉起本地实例，空闲后再回收；obscura_research 在 v4.4.0 加入后台深度研究模式（ADR-0060），一次 obscura_research_start 可以在 MCP 服务进程内最多跑 30 分钟，并产出独立报告。资料来源：packages/create-vkm-kit/templates/skills/vkm-research/SKILL.md:1-60、packages/create-vkm-kit/src/skills-install.mjs:1-80

4. 一致性保障：钩子与受管工具

为了让 skill → MCP → vault 这条链不被原生 Write 绕过，v3.11.0（ADR-0030）加入了 PreToolUse 守卫，在 hook 层 DENY 对原生记忆路径的写操作，从而把"在 vault 里写"和"在仓库里写"两件事彻底分开。skill 的安装脚本 skills-install.mjs 会在每次安装时重新铺设钩子，保证旧项目升级后守卫也一并生效。资料来源：packages/create-vkm-kit/src/skills-install.mjs:1-120

总结：vkm-kit 的"技能体系、Spec 与外部集成"是一张受约束的协作图——skill 负责意图，spec 负责契约，agent 负责实现，MCP 负责底座，外部工具只通过受管接口进入。

Pitfall Log / 踩坑日志

项目：Vahlame/create-vkm-kit

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Vahlame/create-vkm-kit | host_targets=mcp_host, claude_code, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Vahlame/create-vkm-kit | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Vahlame/create-vkm-kit | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Vahlame/create-vkm-kit | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit | release_recency=unknown