项目定位

Vault-for-LLM 是一个面向多 Agent 系统的本地优先记忆治理（Memory Governance）中间件，定位不是另一个 RAG 检索库，而是用于在多个 LLM Agent 之间共享、组织并治理长期记忆的"统一记忆底座"。项目以 Obsidian Vault 作为人类可读的存储形态，并提供 CLI、Gateway、GUI 与 MCP 等多种接入面，使 Agent 可以在结构化目录中沉淀记忆，而人类可以通过相同的目录进行审阅与干预。

资料来源：README.md:1-80

资料来源：docs/vision.md:10-45

资料来源：docs/strategy/positioning.md:20-60

• 面向多 Agent 协作：默认假设存在多个 Agent 同时读写记忆，需要解决冲突、归属与可见性问题
• 本地优先（Local-first）：所有记忆以纯文本 Markdown 形式保存在用户控制的 Vault 目录中，规避外部向量库锁定
• 人类在回路（Human-in-the-loop）：通过 Obsidian 笔记、每日报告卡与冲突清单，把关键决策交回给人类

核心价值主张

与"再做一个向量数据库 + RAG 检索"的常见思路不同，Vault-for-LLM 的核心价值集中在四个层面：

资料来源：docs/core-concepts.md:30-90

资料来源：docs/articles/agents-need-memory-governance-not-just-rag.md:25-70

资料来源：README.md:60-110

资料来源：docs/vision.md:50-100

1. 记忆治理而非单纯检索：除 vault search 检索外，还提供 vault compile 编译、vault init 初始化、冲突检测、归档与候选记忆晋升流程
2. 稳定面向 Agent 的契约：CLI JSON 输出从 v0.7.25 起统一为 ok / status 信封，vault search --json、vault init --json、vault compile --json 均保持向后兼容字段，便于 Agent 自动化解析
3. 统一人类审阅入口：GUI 的"每日审阅收件箱"将日报卡、候选记忆、同步冲突、定向 Task Ledger 交接合并为单一视图
4. 多层接入面：支持 CLI（脚本与 Agent）、Gateway HTTP（轻量 Agent / 桥接工具）、MCP（模型上下文协议）、GUI（人类审阅）四类入口共享同一份底层 Vault

系统形态与运行流程

Vault-for-LLM 在一次典型工作流中串联以下模块：CLI/Gateway 接收 Agent 请求 → 解析为记忆操作 → 在 00-Vault-Knowledge/ 等目录中读写 Markdown → 触发 vault compile 生成可检索索引与摘要 → 将需人类决策的项写入 _Inbox/ 或 Obsidian 笔记。

flowchart LR
  A[Agent / Script] --> B[CLI 或 Gateway]
  C[Human] --> D[Obsidian / GUI]
  B --> E[Vault 编译器]
  E --> F[(Markdown Vault)]
  F --> E
  E --> D
  D -->|审阅与晋升| F

资料来源：docs/cli/quickstart.md:1-40

资料来源：docs/articles/agents-need-memory-governance-not-just-rag.md:75-115

资料来源：README.md:90-140

• vault quickstart 为新用户提供 5 分钟入门路径，降低首次配置门槛
• vault gateway serve 提供单一 HTTP 入口，支持健康检查、搜索、记忆边界等接口
• setup-agent 可生成保守的 Obsidian 目录规则、导入笔记并安排持续同步

适用场景与边界

Vault-for-LLM 适合"多个 Agent 共享同一份长期记忆、需要人类定期审阅"的场景，例如个人 AI 助手集群、Agent 辅助开发团队、小型知识管理工作流。它不适合作为大规模云端 RAG 替代品，也不试图覆盖纯检索增强生成的轻量需求。项目通过 v0.7.20 至 v0.7.29 的迭代，逐步将"多 Agent 记忆治理"从实验能力沉淀为可安装的发布候选，并随 v0.7.28 上线三 Agent 记忆治理演示页与 GitHub Pages 部署站点 资料来源：docs/strategy/positioning.md:80-130。

资料来源：docs/vision.md:110-160

概述与范围

Vault-for-LLM 的安装、快速开始与代理辅助设置子系统是面向"代理辅助构建者（agent-assisted builder）"的入口层，目标是为新用户提供一条小而稳的首次运行路径，而不是直接抛出完整的 setup-agent 标志面。该子系统由安装脚本、CLI 引导命令以及代理设置编排模块三部分组成，分别覆盖了"怎么装进来"、"装完后第一步做什么"以及"代理如何接管设置"三个连续场景。

在 v0.7.29 版本中，该层被刻意简化：用户不再被要求一次性理解所有标志位，而是通过 vault quickstart 走完最小闭环，再通过 vault guide install 阅读 5 分钟快速指南与 FAQ，最后在需要扩展时才进入 setup-agent 的完整配置面。资料来源：vault/cli_quickstart.py:1-40

安装脚本：跨平台引导

安装层由两个并列的入口脚本组成，分别面向类 Unix 系统与 Windows：

• scripts/install.sh：在 Linux/macOS 上完成 Python 解释器校验、依赖安装以及 vault 可执行命令的注册。脚本设计为幂等，重复执行不会破坏现有 Vault 目录。资料来源：scripts/install.sh:1-60
• scripts/install.ps1：在 Windows PowerShell 环境下提供等价能力，路径与权限处理与 sh 版本保持一致语义，避免用户在不同平台上读到不一致的提示。资料来源：scripts/install.ps1:1-60

两个脚本均将后续 CLI 子命令的注册点暴露出来，使 vault 主命令可以分发到 vault quickstart、vault guide、vault setup-agent、vault gateway serve 等子入口。资料来源：scripts/install.sh:60-120

快速开始：vault quickstart 与 vault guide install

快速开始层承担"第一次跑通"的责任，对应两个互补的命令：

vault quickstart

vault quickstart 是一个轻量级引导命令，刻意避免暴露 setup-agent 的全部标志。它会：

1. 检查 Vault 根目录是否已初始化；
2. 若未初始化，调用 vault init --json 并把状态以机器可读的 envelope 形式写出，便于代理捕获结果；
3. 运行一次最小 vault compile，确保编译链路通畅；
4. 打印下一步建议（通常是 vault guide install）。

这条路径的核心设计意图是"先成功一次，再谈配置"。资料来源：vault/cli_quickstart.py:40-120

vault guide install

vault guide install 是面向人类读者的文档型命令，会打印 5 分钟快速指南与 FAQ，覆盖代理辅助设置中最常见的疑问（例如：Vault 与 Obsidian 的边界、Gateway 与 MCP 的关系、--json 输出契约等）。它本身不修改任何状态。资料来源：vault/cli_guide.py:1-80

下表总结了三个入门入口的职责差异：

代理辅助设置：setup-agent 编排

代理辅助设置由 vault/agent_setup.py 与 vault/agent_setup_consumer.py 共同编排。前者负责把代理传入的标志与意图映射成具体的子任务计划，后者负责消费计划并按顺序执行。

入口与标志面

setup-agent 的标志面被设计成"可选累加"：代理可以只传入最小子集完成保守设置，也可以传入完整集启用 Obsidian 导入、定时同步、规则生成等高级能力。资料来源：vault/agent_setup.py:1-80

Obsidian 集成路径

当代理选择启用 Obsidian 集成时，setup-agent 会：

1. 生成保守的 Obsidian 文件夹规则；
2. 按需执行增量导入（v0.7.20 起的语义：变更更新、未变更跳过、缺失不删除）；
3. 调度后续同步任务；
4. 将冲突与待审项导出到 00-Vault-Knowledge/_Inbox/，交由 GUI 或人类处理。

这一路径让 Obsidian 充当"人类审阅收件箱"，而 Vault 仍是事实上的记忆源。资料来源：vault/agent_setup.py:80-160

消费者契约

agent_setup_consumer.py 把上述计划当作流水线来执行：每一步消费前一步的 JSON 状态，并在失败时保留可重入的检查点，使代理能够在中断后继续而非回滚到起点。资料来源：vault/agent_setup_consumer.py:1-100

何时升级到完整 setup-agent

社区共识（来自 v0.7.23–v0.7.29 的发布说明）显示：用户在 vault quickstart 与 vault guide install 完成首次闭环后，应在以下场景进入 setup-agent 的完整标志面：

• 需要把 Obsidian 纳入审阅收件箱；
• 需要启动 vault gateway serve 以便多代理通过 HTTP 接入；
• 需要开启增量同步、冲突解决策略或 Remote Server 硬化材料生成；
• 需要让代理接管后续维护工作（此时 setup-agent 的输出会被代理持续消费）。

对于只需要本地 CLI + GUI 的轻量用户，停留在 vault quickstart 与 GUI 日常审阅收件箱即可，无需进入 setup-agent 的高级路径。资料来源：vault/cli_quickstart.py:120-160

记忆核心模型（Memory）

vault/memory.py 定义了记忆的最小语义单元 Memory，承载内容、来源、类型与时间戳等基础字段。记忆按类型（用户偏好、任务上下文、长期事实、临时草稿等）区分，便于上层在检索时按 memory_type 进行过滤。资料来源：vault/memory.py:1-80

记忆的创建、读取、序列化与去重逻辑集中在本模块，配合 vault/db_memory.py 完成 SQLite 持久化。Memory 对象在被写入前会先生成稳定哈希以支持幂等写入，避免多 Agent 重复提交造成的污染。资料来源：vault/db_memory.py:30-110

治理元数据（Governance Metadata）

vault/governance.py 提供了记忆之上的治理层，主要包含以下几类元数据：

治理层把"机器可读的状态"与"人类可审阅的状态"统一在同一份记录中，使 v0.7.27 引入的统一复核收件箱与 v0.7.28 的三 Agent 记忆治理演示页能够基于同一数据源渲染。资料来源：vault/governance.py:20-140

时间维度与生命周期

vault/temporal.py 负责记忆的时间语义处理。核心字段包括：

• created_at：写入时间，用于审计与排序。
• updated_at：最近一次被引用或重写的时间，影响重要性衰减。
• valid_from / valid_until：可选的生效窗口，用于表达"在某个时间段内有效"的事实。
• decay_factor：随时间自然衰减的可信度系数。

stateDiagram-v2
    [*] --> draft
    draft --> candidate: 自动候选
    candidate --> active: 人工/规则批准
    candidate --> rejected: 复核拒绝
    active --> active: 引用更新
    active --> archived: 超过 valid_until
    archived --> purged: 保留策略触发
    rejected --> [*]
    purged --> [*]

重要性评分与持久化

vault/importance.py 实现了重要性评分函数，综合考虑引用频率、最近命中时间、来源 Agent 权重与治理 confidence，输出 0-1 范围的归一化分数。该分数直接参与 vault/search 的排序权重，是 v0.7.26 稳定化 JSON 信封 ok/status/query/mode/count/results 中 results 数组的排序依据。资料来源：vault/importance.py:10-70

vault/db_schema.py 定义了底层 SQLite 表结构，关键列与上述模型一一对应：memories 表负责主数据，memory_governance 表负责治理元数据，memory_temporal 表负责时间索引与衰减快照，三表通过 memory_id 关联，使写入具备事务一致性。资料来源：vault/db_schema.py:25-180

端到端调用关系

记忆写入路径通常为：Agent 提交 → Memory 构造 → 治理元数据附加 → importance 打分 → db_memory.persist 事务写入三表 → temporal 注册衰减计划。检索路径则反向：db_memory.query 取出候选 → governance 过滤可见性 → temporal 过滤有效期 → importance 重排序 → 返回 vault search --json 结果。这一闭环正是 v0.7.20 起多 Agent 仪表盘与 v0.7.21 统一复核收件箱得以稳定工作的底层支撑。资料来源：vault/db_memory.py:120-200

一、CLI 命令面：从 `quickstart` 到 `daily-report`

主入口 vault/cli.py 把命令分发到若干 cli_*.py 模块，每个子模块负责一个主题域。v0.7.29 新增的 vault quickstart 为新用户提供首跑路径，避免一开始接触 setup-agent 的全部 flag 表面 资料来源：vault/cli.py:1-120、资料来源：vault/cli_quickstart.py:1-80。

主要子命令族如下：

这种"一个主题一个文件"的拆分让 CLI 既能保持单一可执行入口，又能按子系统独立演化。资料来源：vault/cli_core.py:1-60。

二、JSON 契约：`--json` 与统一 envelope

v0.7.25 起，vault init --json 与 vault compile --json 引入稳定 JSON 输出，搭配 --pretty 输出美化版；编译器的进度信息被收纳进 JSON payload，而不是混进 stdout，从而保证 agent stdout 始终可解析 资料来源：vault/cli_common.py:30-140、资料来源：vault/cli_core.py:120-260。

v0.7.26 进一步规范化 vault search --json，统一采用 ok/status 信封，并保留 query、mode、count、results 等兼容字段 资料来源：vault/cli_search.py:40-180。

flowchart LR
  A[vault subcommand] --> B{--json?}
  B -- no --> C[人类可读输出]
  B -- yes --> D[envelope: ok/status]
  D --> E[结果字段: query/mode/count/results]
  D --> F[--pretty: 美化 JSON]
  D --> G[错误归一: 退出码]

任何子命令走 --json 时都会经过 cli_common.py 里的统一包装器，保证：

• 成功：{"ok": true, "status": "ok", ...} 加上业务字段。
• 失败：{"ok": false, "status": "<error_code>", "error": "..."}，并对应非零退出码。
• 进度：编译/索引等长时间操作把进度消息塞进 JSON（如 progress 字段），stdout 不再被日志污染。

这套契约是 agent 自动化的"硬地板"：脚本只需 jq/JSON 解析即可决定下一步动作，不必正则匹配人类文案。

三、Daily Report：人类评审入口

vault daily-report 由 cli_daily_report.py 负责，产出当日需要人类审核的事项清单，落地在 00-Vault-Knowledge/_Inbox/ 与 GUI 的"统一日报收件箱"中 资料来源：vault/cli_daily_report.py:1-200。

日报内容来自四个池子（v0.7.21 起统一到一个 inbox）：

1. Daily Report Cards：摘要当天的记忆写入/更新。
2. 候选记忆（Candidate Memories）：尚未晋升的草稿。
3. 同步冲突（Sync Conflicts）：例如 Obsidian 双向同步时的内容/元数据冲突（v0.7.24 增强了镜像冲突检测）。
4. 定向 Task Ledger 交接：由 Agent 发给人类的任务条目。

GUI 与 CLI 共用同一份数据源，因此 GUI 中看到的人类评审项与 daily-report 生成的卡完全一致，避免双口径 资料来源：vault/cli_daily_report.py:60-160。

四、协同工作流：agent + 人类

完整闭环如下：

1. Agent 通过 vault init --json 初始化仓库，再调用 vault compile --json 构建索引。
2. 检索/记忆操作通过 vault search --json、vault memory add --json 完成，解析 ok/status 信封。
3. 一天结束后，vault daily-report 汇总待评审项，人类在 Obsidian 或 GUI inbox 中查看/批准/驳回。
4. setup-agent（v0.7.23+）可生成保守的 Obsidian 目录规则并把审核卡回流到 _Inbox/，形成 agent ↔ human 的可审计循环。

稳定 JSON 契约 + 统一日报收件箱，使得 Vault 既能被脚本/Hosted 工具桥（v0.7.22 的 vault gateway serve）消费，又能在关键节点保留人类把关，符合"agent-assisted 构建者"的协作模型。

Vault-for-LLM 通过 Model Context Protocol（MCP）把本地知识库能力以"工具"的形式暴露给 LLM 代理。MCP 工具集是面向代理（agent）的统一操作接口，而配置集（Profile）则用于按场景裁剪工具集合、安全策略与默认值，从而让同一个 Vault 实例可以被多类代理安全复用。配合 v0.7.22 引入的 vault gateway serve、v0.7.25/0.7.26 稳定的 JSON 契约以及 v0.7.27/v0.7.28 的人审界面，工具集 + Profile 已经构成 Vault-for-LLM 多 Agent 架构的对外契约层。

MCP 工具集模块划分

工具集并未集中在一个文件，而是按能力域拆分到多个模块，便于按需注册与裁剪：

• 入口与注册：vault/mcp.py 负责装配 MCP 服务器、加载 Profile，并对外输出统一的工具清单。
• 工具清单与定义：vault/mcp_tools.py 集中存放可被代理调用的工具名称、参数 schema 与描述，是 Profile 白名单的引用源。
• 读取能力：vault/mcp_read.py 提供按路径、标签或 ID 读取知识条目的工具。
• 检索能力：vault/mcp_search.py 提供语义、关键词与混合检索工具，对应 CLI 的 vault search 行为并沿用 v0.7.26 稳定的 ok / status 信封。
• 自动化能力：vault/mcp_automation.py 把 compile、init、sync、Obsidian 同步等长任务封装为可被代理调度的工具。

这种"入口 + 工具清单 + 能力域模块"的分层让新增工具只需新增一个领域模块并在 vault/mcp_tools.py 中登记即可，不会改动 vault/mcp.py 的装配逻辑。

工具能力一览

配置集（Profile）机制

Profile 是一组命名的 MCP 暴露配置，用于回答"这个代理应该看到哪些工具、能做哪些操作"的问题。其核心要素包括：

• 工具白名单：Profile 引用 vault/mcp_tools.py 中的工具，按只读 / 写入 / 危险等级归类，便于为不同 Agent 角色裁剪可见工具集。
• 默认参数：检索模式 mode、返回条目数 limit、是否允许提交记忆等默认值，由 vault/mcp.py 在装配阶段按 Profile 注入，使自动化脚本与代理拿到一致的默认行为（这也是 v0.7.25/0.7.26 强调的"代理可解析 stdout"基础）。
• 安全策略：是否需要 token、是否启用 Obsidian 双向同步、是否允许危险级工具等，由各能力域模块（如 vault/mcp_automation.py 中的同步/编译工具）在调用门禁处统一把关。
• 启动入口：每个 Profile 对应一种启动形态，例如 v0.7.22 引入的 vault gateway serve 本质上就是一个"轻量 / 只读 + 受控写入"的 Profile，把 MCP 工具映射为 HTTP 接口。

与 Gateway、CLI 的协作

MCP 工具集 + Profile 同时支撑三种调用入口，三者共享同一套能力域实现：

1. CLI：vault 子命令（如 vault search、vault init --json）复用与 vault/mcp_search.py、vault/mcp_automation.py 同源的内核，从而保证 CLI 与 MCP 在结果与 JSON 契约上完全一致。
2. MCP 服务器：直接对接支持 MCP 协议的本地代理，由 vault/mcp.py 装配并按 Profile 过滤工具，敏感能力（如记忆写入、Obsidian 冲突解决）可被裁剪掉，只留给人类在 GUI 中处理（v0.7.27 的人审界面）。
3. Gateway：vault gateway serve 把部分只读与轻写入工具映射为 HTTP 接口，便于脚本或托管式工具桥接；当 Gateway 与 MCP 共存时，Profile 决定两者暴露的工具集合与默认值是否一致，避免出现"CLI 是一种行为、MCP 是另一种行为"的分裂。

资料来源：vault/mcp.py:1-200、vault/mcp_tools.py:1-200、vault/mcp_memory.py:1-200、vault/mcp_read.py:1-200、vault/mcp_search.py:1-200、vault/mcp_automation.py:1-200。

概述与定位

Vault-for-LLM 的搜索子系统负责为 Agent、CLI 调用以及 vault gateway serve 暴露的 HTTP 入口提供统一的记忆检索能力。它通过把"查询构造 — 召回 — 重排 — 结果封装"拆为多个独立模块，使每一步都可以单独替换、基准化或被 Agent 通过 JSON 调用直接消费。vault search --json 命令自 v0.7.26 起被规范化为稳定的 ok / status 信封，同时保留 query、mode、count 和 results 等字段以兼容既有自动化脚本。资料来源：vault/search.py:1-40

模块结构

资料来源：vault/search.py:1-80、vault/search_query.py:1-60、vault/search_results.py:1-50

查询与召回流程

search_query.py 把外部输入的 query 字符串、过滤标签、Agent 上下文编译成内部查询计划，决定走哪条召回路径（关键词、语义或图谱）。随后 search.py 会并行调度：

1. search_semantic_methods.py 中的语义召回（基于向量表示的近邻检索）。
2. search_graph.py 中的图谱遍历（基于既有笔记间链接的上下文扩展）。
3. 关键词/标题字段的精确匹配通道（兜底路径）。

三路召回结果被 search_results.py 统一封装为内部 SearchHit 对象，包含来源路径、命中片段、得分与时间戳等元数据，避免不同策略之间字段不一致。资料来源：vault/search_query.py:40-120、vault/search_results.py:20-90、vault/search_semantic_methods.py:1-70

重排与质量基准

粗排阶段返回的候选集会进入 search_rerank.py，这里会基于以下信号做精排：

• 与原始查询的语义相似度二次打分；
• 图谱距离（同一文档子树或链接稠密区域优先）；
• 时间新鲜度（重排阶段可配置加权）；
• Agent 任务上下文（防止跨任务记忆污染）。

search_rerank.py 同时也是质量基准（quality benchmark）接入点：开发评审时可以在不同检索策略之间复用同一个重排模块，从而在同一指标下比较 keyword-only、semantic-only 与 hybrid 模式的 Recall@k、MRR 等指标，使搜索质量的演进可量化、可回归。资料来源：vault/search_rerank.py:1-100、vault/search.py:80-140

Agent 面向的 JSON 契约

对 Agent / Gateway 调用方而言，搜索结果通过 vault search --json 或 /search HTTP 端点暴露，统一遵循以下信封：

{
  "ok": true,
  "status": "ok",
  "query": "...",
  "mode": "semantic|graph|hybrid|keyword",
  "count": N,
  "results": [ ... SearchHit ... ]
}

当出现解析错误或索引缺失时，ok 字段会切换为 false，results 为空数组且错误信息放在 status 字段中，从而保证 Agent 自动化流程不会因非结构化输出而中断。资料来源：vault/search_results.py:60-140、vault/search.py:60-120、vault/search_query.py:80-150

概述与设计目标

Vault-for-LLM 的"自动化、候选评审与日常循环"子系统负责将 LLM 代理产生的记忆操作组织为可控、可审计、可恢复的日常工作流。它的核心目标不是让代理完全自主决定一切，而是为 agent-assisted builders 提供一套最小化但完整的"机器执行 + 人类复核"循环：候选生成 → 评审收件箱 → 决策落地 → 学习反馈。社区在 v0.7.21 与 v0.7.27 两个版本中重点强化了"统一日常评审收件箱"以及"GUI 评审面与 Daily Report 共享同一组人类复核项"，这正好对应本子系统的两个核心抽象：候选（candidate） 与 循环（cycle）。整个子系统因此被刻意拆成多个薄模块，以保持策略、评审、学习三件事可以独立演进 资料来源：vault/automation.py:1-80。

模块分解与职责

六个模块围绕同一个 AutomationContext 对象协作，但各司其职，避免任何单一文件成为"上帝模块"：

• automation.py：入口与调度门面，向 CLI（vault quickstart、vault run-cycle 等）和 GUI 提供 run_once / pause / resume / skip 等原子操作 资料来源：vault/automation.py:30-140。
• automation_policy.py：策略层，将原始事件打分并分桶为 auto-accept / review-required / block，是"机器执行 vs 人类复核"分界线的真正持有者 资料来源：vault/automation_policy.py:20-110。
• automation_cycle.py：循环引擎，按每日 / 每次会话粒度驱动 采集 → 评审 → 提交 → 回写 四阶段，并发执行但串行提交 资料来源：vault/automation_cycle.py:45-200。
• automation_review.py：评审收件箱层，把策略层产出的"待审项"结构化为 GUI、Daily Report、Task Ledger 三种人类可见形态，保证多入口的事实一致性 资料来源：vault/automation_review.py:25-180。
• automation_learning.py：学习反馈层，读取历史接受/拒绝决策作为样本，回写策略层内部的偏好模型 资料来源：vault/automation_learning.py:15-120。
• automation_lifecycle.py：生命周期管理，处理冷启动、暂停、人工覆盖、版本切换（如 v0.7.20 起作为多代理 RC 发布时的策略迁移） 资料来源：vault/automation_lifecycle.py:30-150。

候选评审流程

候选评审（candidate review）不是一个独立命令，而是日常循环中必经的人类参与节点。其数据流可概括为：代理产出 → policy 过滤 → review 收件箱 → 人类决策 → 回写 Vault。

候选可能来自：新候选记忆、Obsidian 同步冲突、Task Ledger 定向交接、Gateway/Remote 健康异常。v0.7.27 的发布说明强调，Obsidian 冲突现在与 Daily Report、Memory Control Center 共享同一组人类评审项，以保证代理作者在多个表面看到的"待办"是同一份事实，避免代理在不知情的情况下"双写"冲突两侧 资料来源：vault/automation_review.py:60-140。当用户通过 vault quickstart（v0.7.29）首次运行时，候选评审默认进入"保守模式"：任何被策略判定为高风险的变更都会被路由到评审层而非直接写回，这与 v0.7.24 引入的"双侧保留 + 仅记录元数据冲突"行为一致 资料来源：vault/automation_policy.py:80-160。

下表汇总了主要候选来源与对应的人工介入深度：

资料来源：vault/automation_review.py:90-170 vault/automation_lifecycle.py:60-130。

日常循环与学习闭环

日常循环（daily cycle）是该子系统最外层的执行单元，由 automation_cycle.run_once() 触发，支持时间或事件两种驱动模式。它的核心思想是：每次循环最多产生一组候选、至多要求人类批一次，避免大批量变更阻塞正常使用 资料来源：vault/automation_cycle.py:120-240。循环结束后，automation_learning 会读取评审层的人工决策作为样本，更新策略层的偏好模型；这意味着同一类候选在多次被人工接受或拒绝后，策略层会自动调整其分桶阈值，从而让"保守起步、逐步放手"成为可能 资料来源：vault/automation_learning.py:50-130。

生命周期的边界由 automation_lifecycle 守护：它负责在版本升级（如 v0.7.20 将多代理工作正式打包为可安装 RC）时安全迁移策略与候选队列，并在用户暂停自动化时确保已生成但未回写的候选不丢失 资料来源：vault/automation_lifecycle.py:80-160。对于初次接入 Vault 的代理，quickstart 子命令（在 v0.7.29 引入）会跳过完整的 setup-agent 标志面，直接给出一个最小可运行的循环配置，使用户在五分钟内就能看到候选评审收件箱的第一行数据 资料来源：vault/automation.py:100-180。

概览与目标

Vault-for-LLM 的「集成、网关与远程共享」子系统位于 CLI 与本地 Vault 存储之间，承担三项职责：

1. 为外部 Agent、脚本与托管工具桥提供统一的 HTTP 入口，避免每个调用方都直接对接完整 CLI 或 MCP 表面。
2. 在 Vault 与第三方知识库（尤其是 Obsidian）之间建立双向、可审计的同步通道，使人类审阅工作流可以在 Obsidian 中完成。
3. 通过 Remote Server 加固模板与 Token/TLS/备份清单，让用户把 Vault 内存以受控方式共享给远端 Agent。

该子系统围绕 v0.7.22 的 vault gateway serve、v0.7.23 的 Obsidian 集成、v0.7.24 的 Remote Server 加固材料，以及 v0.7.27/v0.7.29 的网关安全与仪表盘逐步成形。资料来源：vault/gateway_server.py:1-80。

CLI Gateway：`vault gateway serve`

vault gateway serve 提供一个轻量级 HTTP 端点，覆盖健康检查、检索（search）、边界（boundary）与受限的写入操作。CLI 端将 HTTP 调用包装成与本地 CLI 一致的命令语义，方便 Agent 调用方复用现有调用约定。资料来源：vault/gateway.py:1-120。

网关启动阶段会执行安全自检，并在 v0.7.29 中对接 startup checklist，确保在监听端口前完成 token、TLS、绑定地址的校验。资料来源：vault/gateway_security.py:30-160。

Obsidian 集成：人类审阅收件箱

Obsidian 被定位为 Vault 的人体侧审阅面。import_obsidian.py 负责将 Obsidian 中的笔记增量导入 Vault；export_obsidian.py 则把 Vault 中需要人类确认的卡片（候选记忆、同步冲突、定向 Task Ledger 交接）导出回 Obsidian 的约定目录（如 00-Vault-Knowledge/_Inbox/）。资料来源：vault/import_obsidian.py:40-200、资料来源：vault/export_obsidian.py:30-180。

冲突检测在 v0.7.24 中得到加强：当源笔记与 Vault 原始副本都发生变化时，Vault 会同时保留两侧内容，并在元数据中记录一条仅元数据冲突，供人类在 Daily Report 与 Memory Control Center 中统一审阅。资料来源：vault/import_obsidian.py:210-310。

安全、审计与远程共享

gateway_security.py 集中实现 token 校验、来源限制、CORS、速率限制等横切关注点；gateway_audit.py 把每一次网关调用、每一次 Obsidian 同步决策写入审计日志，供多 Agent 仪表盘聚合展示。资料来源：vault/gateway_security.py:160-300、资料来源：vault/gateway_audit.py:1-150。

Remote Server 部署侧由 vault guide remote 输出 env 模板与 token/TLS/备份清单，配合 Gateway 的本地自检，确保远端 Agent 接入时遵循最小权限与可审计原则。资料来源：vault/gateway_server.py:120-220。

下表给出各入口与其主要用途的速览：

多 Agent 仪表盘在 v0.7.27 起直接展示 Gateway/Remote 访问健康，包含阻塞与失败计数，使运维侧可以尽早介入。资料来源：vault/gateway_audit.py:150-260。

Pitfall Log / 踩坑日志

项目：zycaskevin/Vault-for-LLM

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

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

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

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

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

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/zycaskevin/Vault-for-LLM | no_demo; severity=medium

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

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

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

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

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

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