# https://github.com/Vahlame/create-vkm-kit 项目说明书
生成时间：2026-07-21 16:56:06 UTC
## 目录
- [项目概述与系统架构](#page-overview)
- [持久化记忆、混合检索与多写者安全](#page-memory)
- [Token 节约、本地诊断与 CI 守护](#page-token)
- [技能体系、Spec 与外部集成](#page-skills)
## 项目概述与系统架构
### 相关页面
相关主题：[持久化记忆、混合检索与多写者安全](#page-memory), [Token 节约、本地诊断与 CI 守护](#page-token), [技能体系、Spec 与外部集成](#page-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Vahlame/create-vkm-kit/blob/main/README.md)
- [README.en.md](https://github.com/Vahlame/create-vkm-kit/blob/main/README.en.md)
- [ARCHITECTURE.md](https://github.com/Vahlame/create-vkm-kit/blob/main/ARCHITECTURE.md)
- [AGENTS.md](https://github.com/Vahlame/create-vkm-kit/blob/main/AGENTS.md)
- [package.json](https://github.com/Vahlame/create-vkm-kit/blob/main/package.json)
- [packages/create-vkm-kit/src/index.js](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/index.js)
# 项目概述与系统架构
## 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 目录初始化到项目根目录下。
```mermaid
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]()。
---
## 持久化记忆、混合检索与多写者安全
### 相关页面
相关主题：[项目概述与系统架构](#page-overview), [Token 节约、本地诊断与 CI 守护](#page-token)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/obsidian-memory-mcp/src/hybrid-mcp.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/hybrid-mcp.mjs)
- [packages/obsidian-memory-mcp/src/vault-fs.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/vault-fs.mjs)
- [packages/obsidian-memory-mcp/src/vault-lock.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/vault-lock.mjs)
- [packages/obsidian-memory-mcp/src/context-assemble.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/context-assemble.mjs)
- [packages/obsidian-memory-mcp/src/rag-client.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/rag-client.mjs)
- [packages/obsidian-memory-rag/src/obsidian_memory_rag/knowledge_graph.py](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-rag/src/obsidian_memory_rag/knowledge_graph.py)
# 持久化记忆、混合检索与多写者安全
`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 起默认开启）：
| 环境变量 | 作用 |
|---|---|
| `OBSIDIAN_MEMORY_PIN_FAILURES=1` | 把历史上导致失败/返工的笔记权重钉死在前列 |
| `OBSIDIAN_MEMORY_USAGE_BOOST=1` | 根据真实召回频次对笔记做使用加权 |
两个杠杆都是"排序级"而非"遥测级"，关闭后向量库原样保留，因此用户可以零成本回退。`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 风格条件写入协议：
```mermaid
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 节约、本地诊断与 CI 守护
### 相关页面
相关主题：[项目概述与系统架构](#page-overview), [持久化记忆、混合检索与多写者安全](#page-memory)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/create-vkm-kit/src/token-saver.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/token-saver.mjs)
- [packages/create-vkm-kit/src/hooks/compact-tool-output.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/hooks/compact-tool-output.mjs)
- [packages/create-vkm-kit/src/hooks/compact-mcp-output.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/hooks/compact-mcp-output.mjs)
- [packages/create-vkm-kit/src/hooks/ensure-otel-sink.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/hooks/ensure-otel-sink.mjs)
- [packages/create-vkm-kit/src/hooks/guard-native-memory-write.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/hooks/guard-native-memory-write.mjs)
- [packages/create-vkm-kit/src/hooks/guard-effort-gate.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/hooks/guard-effort-gate.mjs)
# Token 节约、本地诊断与 CI 守护
`vkm-kit` 的效率套件由三组相互衔接的子系统组成：在写入到模型上下文前压缩工具 / MCP 响应、在本地采集遥测用于诊断，以及在 PreToolUse 阶段硬性阻断违反契约的写入。这三组机制共享同一份 `permissions/hooks` 注册表，由 `create-vkm-kit` 安装器在 Claude Code、Cursor 与 Codex 三端统一接线，默认全部启用。
## 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]()。
## 三层协作流程
```mermaid
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]()。
---
## 技能体系、Spec 与外部集成
### 相关页面
相关主题：[项目概述与系统架构](#page-overview), [Token 节约、本地诊断与 CI 守护](#page-token)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/create-vkm-kit/src/skills-install.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/skills-install.mjs)
- [packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md)
- [packages/create-vkm-kit/templates/skills/vkm-spec/SKILL.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/templates/skills/vkm-spec/SKILL.md)
- [packages/create-vkm-kit/templates/skills/vkm-design/SKILL.md](https://github.com/Vahlame/create-vkm-kit/templates/skills/vkm-design/SKILL.md)
- [packages/create-vkm-kit/templates/skills/vkm-research/SKILL.md](https://github.com/Vahlame/create-vkm-kit/templates/skills/vkm-research/SKILL.md)
- [packages/create-vkm-kit/templates/agents/vkm-implementer.md](https://github.com/Vahlame/create-vkm-kit/templates/agents/vkm-implementer.md)
# 技能体系、Spec 与外部集成
## 1. 技能体系的安装与契约
`vkm-kit` 把"可复用的工作流"打包成一组 `SKILL.md`，每一个 skill 是一个独立的目录，里面只放一段 Markdown 契约，对 Claude Code 暴露何时使用、如何调用与产出什么。安装器通过 `skills-install.mjs` 把 `templates/skills/` 下登记的 skill 镜像同步到目标项目的 `.claude/skills/` 或同等目录，确保每次 `create-vkm-kit` / `vkm` 执行后 skill 集合保持一致。
skill 之间有清晰的边界：
| Skill | 角色 | 触发场景 |
|---|---|---|
| `vkm-discipline` | 纪律守护 | 用户行为偏离已写定的 RULES 契约时介入 |
| `vkm-spec` | 规格生成 | 把模糊需求拆成可验证的规格 |
| `vkm-design` | 设计裁决 | 在实现前对架构、模块边界给出意见 |
| `vkm-research` | 调研 | 联网搜索、本地 SearXNG 与 deepResearch 复用 |
`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. 外部工具与代理联动
```mermaid
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 负责底座，外部工具只通过受管接口进入。
---
---
## Doramagic 踩坑日志
项目：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