synaptic

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/synaptic-logo.png"> <img src="assets/synaptic-logo-light.png" alt="Synaptic" width="520"> </picture> </p> # Synaptic **你的 Obsidian 仓库，编译成一个思考网络。** Synaptic 是一个本地优先的智能层，位于你的 [Obsidian](https://obsidian.md) 仓库和 Claude（或任何 LLM）之间。它摄取你的原始捕获，编译成链接的永久笔记，为它们添加证据支持的置信度评分，揭示非显而易见的联系，并回答问题，而所有这些都基于你曾经写过的内容，且不会离开你的机器。 这里的关键区别：**这不是 RAG。** RAG（检索增强生成）在每次查询时都会从原始片段中重新推导出答案，并且不会积累任何内容。Synaptic 只需编译一次源内容，生成结构化、链接的页面，然后从这个构建成果中回答问题。编译的知识会不断增长；检索的知识只是被重新发现。 13 种仓库技能 · 7 种 MCP 工具 · 0 次所需的云调用。 > **新来者或不熟悉技术？** 从[逐步入门指南](GETTING-STARTED.md)开始。它会带你从零开始，用简单的语言解释一切，不需要任何预先的知识。本 README 是完整的参考资料，供你需要了解详细信息时使用。 --- ## 目录 - [什么是 Synaptic](#what-synaptic-is) - [核心概念](#core-concepts) - [工作原理](#how-it-works) - [安装](#installation) - [快速入门：三个命令即可体验](#quick-start-three-commands-to-a-felt-result) - [示例：一个笔记从头到尾](#a-worked-example-one-note-end-to-end) - [日常使用](#everyday-use) - [运行本地模型（Ollama）](#running-a-local-model-ollama) - [从 Claude Code 或 Codex 使用 Synaptic](#using-synaptic-from-claude-code-or-codex) - [配置](#configuration) - [个人与共享仓库](#personal-vs-shared-vaults) - [仓库结构（PARA）](#vault-structure-para) - [智能文件：CLAUDE.md](#the-intelligence-file-claudemd) - [技能](#skills) - [CLI 参考](#cli-reference) - [可选集成](#optional-integrations) - [项目布局与开发](#project-layout--development) - [路线图](#roadmap) --- ## 什么是 Synaptic 大多数笔记系统都在同一个地方失败。捕获很容易，归档感觉很有成效，但笔记很快就会沉到底部，你再也不会查看。 你最终成为了搜索引擎：唯一遍历整个仓库的过程是你手动执行的，只有在你偶然记得某个笔记存在的那一天。仓库每周都在增长，但其价值却停滞不前。 Synaptic 颠覆了这种状况。你的笔记不再只是你能读懂的东西，它们变成了代理可以读取、编写、链接和按需调用的内容。你策划来源并提出问题；系统负责记账：总结、交叉引用、归档到正确的信息下，并在新内容到达时更新邻近的笔记。 Synaptic 有三个关键属性： - **本地优先。** 默认模型是 [Ollama](https://ollama.com)，在你的硬件上运行，并且默认启用 `local_only: true`。你的半成品想法、私人策略和敏感捕获都保留在机器上，直到你明确选择导出。如果 Ollama 未安装，Synaptic 会退回到确定性的启发式引擎，因此每个命令仍然有效；只是当有模型可用时，它变得更智能。 - **证据优于臆想。** 每个 AI 建议的标签都带有置信度评分、来源、引用的证据和隐私安全标志。没有任何内容成为权威的，除非你批准。 - **你拥有的纯文本。** 仓库是普通的 Markdown 文件，存放在普通的目录中。没有专有数据库，没有锁定。你可以将不同的模型指向同一个目录，它仍然有效，因为你拥有这个大脑，而不是工具。 Synaptic 默认情况下适用于一个人的第二大脑，可以设置为共享的团队大脑（参见 [个人与共享仓库](#personal-vs-shared-vaults)）。它与 Claude Code 或 Codex 等代理天然配对，通过 [MCP 服务器](#using-synaptic-from-claude-code-or-codex)，因此代理可以直接查询你的仓库，而不是复制粘贴笔记内容。 ## 核心概念 术语表。这些术语在文档和技能中反复出现。 | 术语 | 含义 | |------|---------| | **PARA** | 目录分类法：**P** 项目，**A** 领域，**R** 资源，**A** 存档，另外还有一个Inbox和一个System文件夹。组织用于*检索*（你查找笔记时知道的内容），而不是*存储*（内容来自哪里）。 | | **捕获** | 放入`00 - INBOX/`的原始、未处理的想法或高亮。还不是真正的笔记。 | | **源笔记** | 用自己的话重写的捕获并存放在`01 - NOTES/`（每天、会议、书籍、课程）。一旦归档，就是原始记录。 | | **永久 / 常绿笔记** | 一个原子级、属于自己的、*链接*的笔记，表达一个想法，存放在`04 - RESOURCES/topics/`。这是编译后的产物，仓库会从中获取答案。每个笔记都有一个**关键张力**：一个明确的陈述，说明这个想法为何非显而易见。 | | **MOC（内容地图）** | 一个索引笔记，链接到某个主题的所有笔记。让代理（和你）可以通过一次跳转导航到主题集群。位于`06 - SYSTEM/MOCs/`。 | | **实体** | 笔记在 Synaptic 的本地数据库中扫描后的样子，包含其类型、前端、内容和解析出的维基链接。 | | **主题笔记** | 一个特殊的笔记（`type: topic`），用纯英语*定义一个标签*，并附有匹配规则。标签引擎根据主题笔记对其他笔记进行评分。 | | **证据支持的标签** | 一个标签建议，带有置信度评分、来源引用、引用的证据和隐私安全标志。它位于待审批队列中，直到你批准。 | | **贡献** | 记录一个笔记对实际输出（文章、决定、简报）的贡献。重要的指标不是你有多少笔记，而是笔记*贡献*的次数。 | | **三层结构** | `01 - NOTES/`（原始、不可变、属于你自己的），然后是`04 - RESOURCES/topics/`（维基、编译、模型维护），最后是`06 - SYSTEM/CLAUDE.md`（模式和规则，共享）。保持它们分开是使系统值得信赖的原因。 | ## 工作原理 ### 流程 笔记通过一个固定的流程。每个 CLI 命令都是一个阶段： ``` 捕获 扫描 嵌入 建议标签 -> 审查 -> 编写标签 （将笔记放入 -> 将仓库解析到 -> 计算向量 -> 每个笔记针对每个主题笔记进行评分； -> 审查并批准 00-INBOX） 本地 SQLite 语义搜索 队列证据支持的建议；你批准；批准的 数据库为实体 标记写入前端 | | | +------------------------+-------------------------+ v 查询 / 简报 / 查找联系 （回答问题，生成简报，显示链接， 所有这些都基于编译的、标记的仓库） ``` - **`扫描`** 读取每个 Markdown 文件，将前端与正文分离，提取维基链接和章节，并将每个笔记作为*实体*更新到本地 SQLite 数据库（`.synaptic/synaptic.db`）。没有任何内容被发送到任何地方。 - **`嵌入`** 使用本地嵌入模型（通过 Ollama 的 `nomic-embed-text`）将每个笔记转换为向量并存储。这支持语义搜索（“查找 *含义* 相似的笔记”）。如果没有嵌入，Synaptic 恢复到关键词搜索。 - **`建议标签`、`审查`、`编写标签`** 是标签循环的一部分，下面会详细介绍。 - **`查询`、`简报`、`查找联系`** 是读取侧；它们使用编译的、标记的仓库。 **文件监视器**（`synaptic watch`）可以在文件更改时自动重新运行扫描，这样数据库就可以在你编写时保持最新。 ### 问题如何得到回答 `synaptic query "…"`（和 `query_vault` MCP 工具）通过设计用于廉价地找到正确的笔记，然后再进行更广泛的搜索： 1. **MOC优先。** 如果 Map of Content 的文件名是问题的一个*强*主题匹配（两个或多个共享有意义的单词，或一个单词主题 MOC，其单词包含在问题中），Synaptic 会从该 MOC 和它链接的笔记中回答。这是“通过索引导航，不要对整个语料库进行强力搜索”的路径。通用索引名称和偶然的单词重叠故意不会触发它。 2. **前端缩小语义搜索。** 否则，Synaptic 通过将问题中有意义的单词与每个笔记的标签/类型/项目进行匹配来缩小候选范围，将数百个笔记减少到少数，然后根据嵌入式相似性（余弦，高于相关性阈值）对该集合进行排序。 3. **关键词备用。** 如果嵌入式不可用或返回为空，它将对相同的候选集合运行词频关键词搜索（标题匹配增强）。 4. **全仓库重试。** 如果缩小范围找不到任何结果，它将对整个仓库重新运行搜索，因此过于激进的缩小范围永远不会隐藏答案。 5. **合成。** 收集的笔记成为 LLM 的上下文，LLM 使用这些笔记*回答问题，并引用它们的标题*。如果没有 LLM，它会返回最相关的笔记标题列表。 ### 标签如何工作 Synaptic 中的标签是*赚取的*，而不是凭空捏造的。你通过编写一个**主题笔记**（`type: topic`）来定义一个标签，该笔记用纯英语描述标签并附有可选的匹配规则。然后： 1. **`建议标签`** 对每个笔记与每个主题笔记进行评分。如果路由到`tagging`任务的实际模型使用它进行细致入微的判断；否则，确定性关键词匹配器运行，因此该功能始终有效。每个匹配项成为一个建议，带有**置信度评分**、**引用的证据**和**隐私安全标志**。低于置信度阈值（默认为`0.55`）的建议被丢弃。 2. **`审查`** 逐一检查待处理的建议，显示证据，以便您可以批准或拒绝每个建议。它还会显示*拒绝模式*：如果您一直拒绝相同的标签，它会建议将其添加到`CLAUDE.md`的“无用”部分，以便您的仓库从您的纠正中改进，而不是要求您提前编写规则。 3. **`编写标签`** 仅将批准的标签注入每个笔记的前端。 没有任何内容未经人工批准就成为权威。整个循环都是围绕证据和同意构建的。 ### 隐私保护 每个笔记都有一个`privacy`级别（在前端设置或自动分类）。隐私分类器会标记可能敏感的内容，并在生成任何内容之前进行编辑。级别决定了哪些内容可以出现在简报和建议中： | 级别 | 是否出现在简报/建议中？ | |-------|--------------------------------------| | `public` | 是的，在任何地方 | | `professional` | 是的 | | `personal_sensitive` | 仅在明确允许的情况下 | | `nsfw` | 永远不会 | | `excluded` | 永远不会被索引或使用 | 与`local_only: true`相结合，这意味着敏感的思考不仅保留在您的机器上，还保留在生成的任何输出中，除非您故意允许。 ### 本地优先、提供者无关的路由 Synaptic 工作任务路由。根据任务的不同，默认情况下，每个任务（标签、嵌入、简报、战略查询）都发送到本地 Ollama，并且`privacy_filter`任务始终在本地运行，无论其他设置如何。您可以通过在`.env`中添加密钥并设置`local_only: false`，将个别任务指向托管提供商（OpenAI、Anthropic、xAI/Grok、DeepSeek、OpenRouter 或任何 OpenAI 兼容的端点）。例如，本地标记但使用更强的付费模型合成简报。Synaptic 在每个会话中仅发出一次警告，然后再进行外部调用。 ## 安装 ```bash # 克隆，然后从项目根目录： python -m venv .venv . .venv/Scripts/activate # Windows # source .venv/bin/activate # macOS / Linux pip install -e . # 核心 pip install -e ".[mcp]" # + Claude Code MCP 服务器 pip install -e ".[dev,mcp]" # + 测试/开发工具 ``` 要求：Python 3.10+。Ollama 是可选的，但推荐；如果没有 Ollama，Synaptic 使用启发式备用。 ## 快速入门：三个命令即可体验 不要先阅读架构。随便丢一个笔记进去，问它一个问题，看看效果。其他功能都在这里，不需要你先学习。 ```bash synaptic init # 创建 PARA 文件夹、CLAUDE.md、config.yaml # 将一个真实的笔记（一个想法、一个高亮、任何内容）放入 00 - INBOX/ synaptic scan # 将仓库解析到本地数据库 synaptic query "我的仓库里有什么？" # 问它 ``` 这是循环：**捕获、扫描、询问。** 它适用于零 Ollama 设置，因为一切都回退到确定性启发式引擎，因此循环永远不会因基础设施而阻塞。一旦运行模型后，它会变得更智能，但永远不需要模型来启动。 `init` 会提出一个分支问题：**个人大脑还是共享团队大脑？** 个人是默认的。参见 [个人与共享仓库](#personal-vs-shared-vaults)。 如果您更喜欢在不创建任何内容的情况下进行探索，请使用捆绑的示例仓库而不是 `init`: ```bash cp config/config.example.yaml config/config.yaml # 已经指向 examples/vault synaptic scan && synaptic query "我知道关于刻意练习什么？" ``` 一旦循环感觉真实，完整的循环： ```bash synaptic doctor # 检查 Ollama / 模型 / 配置 synaptic health # inbox 大小、未链接的笔记、缺少的前端 synaptic embed # 计算语义嵌入（需要 nomic-embed-text） synaptic suggest-tags # 生成待处理、证据支持的标签建议 synaptic review # 批准 / 拒绝，并显示 CLAUDE.md 的拒绝模式 synaptic write-tags # 将批准的标签注入笔记前端 synaptic brief "Jane Doe" # 隐私安全的联系简报 synaptic contributed "Note Title" --context "used in Q2 article" # 记录贡献 synaptic contribution-report # 哪些笔记赚取了他们的保留 vs. 未使用 synaptic mcp # 启动 Claude 的 MCP 服务器 ``` ## 示例：一个笔记从头到尾 假设您刚刚读了 *Peak* 的一章，并记下了一个粗略的想法。 1. **捕获。** 您将一个片段放入 `00 - INBOX/`： ``` IDEA: 练习只有在你能获得反馈你的错误时才有帮助 CONNECTS TO: 10,000 小时想法，但它缺少一些东西 ``` 2. **处理成永久笔记。** 使用 `capture-processor` 和 `permanent-note` 技能（或手动），片段变成原子级、属于自己的笔记，存放在 `04 - RESOURCES/topics/`： ```markdown --- type: resource status: draft date: 2026-05-14 description: 刻意练习需要对错误提供即时反馈，而不是重复。 tags: [学习、专业知识] source: Peak (Ericsson & Pool) --- # 刻意练习需要对错误提供即时反馈 改进需要不仅是重复，而是重复并对错误提供即时反馈。没有反馈的练习优化的是流畅度，而不是准确度…… ## 关键张力 这与流行的“10,000 小时”框架相矛盾。小时数不会产生专业知识；反馈结构会…… ## 联系 - [[复合需要一致性大于幅度]]：两个都是关于输入循环的质量，而不是数量 ``` 原始片段保留在`01 - NOTES/`或存档中作为不可变的源；永久笔记是编译后的产物。 3. **扫描和嵌入。** `synaptic scan` 将笔记加载为实体；`synaptic embed` 为其赋予向量。 4. **标签。** `synaptic suggest-tags` 根据主题笔记对它进行评分，并建议例如 `#deliberate-practice`，置信度为 0.88，并引用句子作为证据。`synaptic review` 显示给你；你批准；`synaptic write-tags` 将其写入前端。 5. **复合。** 几个月后，您询问 `synaptic query "练习量真的很重要吗"`。Synaptic 缩小到学习和专业知识笔记，按含义排序，并*从您自己的笔记中*回答，引用它，并显示您编写的关键张力。当这个答案用于文章时，您运行 `synaptic contributed "Deliberate Practice Requires Immediate Feedback on Errors" --context "Q2 essay on skill-building"`，笔记升级为`status: reference`。 这就是全部内容。笔记不仅被存储，还被*使用*，并且在相关时会被再次显示。 ## 日常使用 **日常（几分钟）。** 自由地将内容捕获到 `00 - INBOX/` 中，不需要立即进行分类。每天处理一次 inbox：将每条信息重写成自己的语言，链接到至少一个现有的笔记，然后归档。这需要 `capture-processor` 技能。黄金法则是 *绝不直接归档原始捕获内容，绝不留下零链接的笔记*。 **消化来源（一次一个）。** 当你阅读值得吸收的内容时，使用 `karpathy-ingest` 技能：不可变地归档来源笔记，然后运行 **邻居更新**，该更新会找到新来源确认、矛盾或扩展的每个现有永久笔记，并更新这些笔记。一次处理一个来源，充分集成后再处理下一个。批量导入会产生一堆笔记；一次消化一个来源会产生一个知识库。 **每周（约 45 分钟）。** 运行 `weekly-ritual`：清空 inbox，揭示本周笔记之间的新连接，审计孤立笔记（`synaptic health` 显示零链接笔记），并撰写简短的回顾。你可以安排机械部分自动运行（参见 cron 和 Task Scheduler 的技能配方），但仅授予计划任务存档访问权限，切勿删除。 **检查知识库的健康状况。** `synaptic health` 报告 inbox 大小、未链接和孤立笔记、缺失的前置信息。`synaptic contribution-report` 显示哪些笔记已经发挥作用，哪些笔记一直未被使用。未使用的笔记是归档的候选。 ## 运行本地模型（Ollama） `synaptic doctor` 检测 Ollama 是否可以在 `http://localhost:11434` 访问以及存在哪些模型。 ```bash # 原生安装：https://ollama.com/download （或 `winget install Ollama.Ollama` ） # ... 或通过 Docker： docker compose up -d ollama ollama pull llama3.2:3b # 快速，适合 8 GB RAM ollama pull llama3.1:8b # 更智能，需要 16 GB RAM ollama pull nomic-embed-text # 嵌入（用于语义搜索） ``` 按任务选择模型： - **日常知识库工作 / 捕获处理：** `llama3.2:3b` （8 GB）或 `llama3.1:8b` （16 GB） - **长文档分析，笔记综合：** `gemma2:9b` （24 GB） - **创意写作，想法开发：** `mistral:7b` - **硬件资源有限：** `llama3.2:1b` 或 `phi3:mini` 如果您更喜欢为某些任务使用托管模型？请在 `.env` 中添加密钥，设置 `local_only: false`，并将相关的 `routing:` 条目指向该提供商。 ## 从 Claude Code 或 Codex 使用 Synaptic Synaptic 是与代理无关的。你可以通过三种方式从 Claude Code、Codex 或任何编码代理驱动它，并且它们可以组合使用： 1. **作为 CLI。** `synaptic scan`、`synaptic query "…""` 等是普通的 shell 命令。任何具有终端的代理（Claude Code 的 Bash 工具，Codex 的 shell）都可以直接运行它们。这里没有任何特定于 Claude 的内容。 2. **作为 MCP 服务器。** `synaptic mcp` 启动一个标准的 stdio [MCP](https://modelcontextprotocol.io) 服务器，暴露以下 7 种工具，代理可以像使用原生工具一样查询知识库，无需复制粘贴。需要 `pip install "synaptic[mcp]"`。 3. **作为技能。** `skills/` 文件夹是普通的 Markdown 攻略手册，代理可以读取并遵循；捆绑的 `kepano/obsidian-skills` 针对开放的 Agent Skills 规范，该规范在 Claude、Codex 等上运行。 **Claude Code** 从 `.claude/settings.json` 读取 MCP 服务器。注册一次： ```json { "mcpServers": { "synaptic": { "command": "synaptic", "args": ["mcp"], "cwd": "/path/to/your/vault-project" } } } ``` **Codex** 从 `~/.codex/config.toml` 读取 MCP 服务器。服务器命令相同；仅客户端的配置文件和格式不同： ```toml [mcp_servers.synaptic] command = "synaptic" args = ["mcp"] # 在知识库项目中运行服务器，以便它找到 config.yaml： cwd = "/path/to/your/vault-project" ``` 无论哪种方式，服务器都暴露相同的 **7 种工具**： | 工具 | 代理可以用它做什么 | |------|-------------------------------| | `get_active_context` | 读取知识库的 `CLAUDE.md` （关于你是谁，什么是活跃的） | | `search_vault` | 语义 + 关键词搜索，返回带有摘录的笔记 | | `get_note` | 通过标题获取完整笔记 | | `query_vault` | 提问；从知识库中回答，并附上引文（上面的级联） | | `find_connections` | 查找与给定笔记最相关的笔记 | | `vault_health` | 收件箱大小，存档计数，总笔记数 | | `list_notes` | 按类型/状态筛选笔记，每个笔记都有一个单行 `description` | 两件值得注意的事情： - **Synaptic 自己的模型独立于驱动它的代理。** 其 LLM 路由器默认为本地 Ollama，可以指向 OpenAI、Anthropic 或其他提供商。无论 Claude Code 还是 Codex 调用，Synaptic 的标签、嵌入和查询合成都通过 *您* 配置的提供商（默认为本地）。 - **`CLAUDE.md` 是一个 Synaptic 读取的文件名，而不是对 Claude 的依赖。** `get_active_context` 工具加载 `06 - SYSTEM/CLAUDE.md` 并将该上下文提供给调用它的任何代理，包括 Codex。Codex 不会自动加载该文件作为其自己的指令，就像它对待 `AGENTS.md` 一样，但它不需要这样做：上下文通过 MCP 工具调用到达它。 ## 配置 - `config/config.yaml` 包含知识库路径、存储位置、隐私规则、LLM 提供商和任务路由。 从 `config/config.example.yaml` 复制它。 - `.env` 仅包含 API 密钥。 永远不要提交；永远不要写入笔记。 关键设置：`privacy.local_only` （严格的本地模式），`privacy.default_level` 和 `privacy.brief_allowed_levels` （隐私分级），`routing.<task>` （哪个提供商处理每个任务），以及 `tagging.min_confidence` （建议的阈值）。 ## 个人 vs. 共享知识库 `synaptic init` 会询问：个人大脑还是共享团队大脑？两种路径都使用相同的 PARA 结构、技能和 CLI。只有 `CLAUDE.md` 和隐私默认值不同。 | | 个人 | 共享 | |---|---|---| | CLAUDE.md 格式 | 一个人的项目、决策、声音 | 团队章程：目的、指定负责人、贡献者、升级路径 | | 笔记归属 | 不需要 | `contributor:` 前置字段在每个模板上 | | 默认隐私 | `professional` （默认情况下在简介中显示） | `personal_sensitive` + `brief_allowed_levels: [public]` （除非明确标记，否则没有任何内容到达简介） | | 访问控制 | 不适用 | **无。** 任何可以打开文件夹的人都可以读取和写入所有内容 | 诚实面对最后一行：**共享模式是一套适用于受信任、已同步的团队文件夹的约定，而不是权限系统。** 指定的负责人更重要，而不是工具。一个有授权的负责人（可以添加来源并修复错误而无需每次都征求许可）的共享知识库是有效的。一个需要每次变更都获得批准的知识库会因信号不足而难以变得有用。参见 `skills/claude-md.md` 以了解完整的推理。 ## 知识库结构（PARA） Synaptic 在 `examples/vault/` 中提供了一个预先构建的 PARA 知识库： ``` vault/ ├── 00 - INBOX/ # 捕获队列，每天处理 ├── 01 - NOTES/ # 时间戳记源笔记（每天、会议、书籍、课程）；不可变 ├── 02 - PROJECTS/ # 具有明确结果和截止日期的活跃项目 ├── 03 - AREAS/ # 持续的责任，没有截止日期 ├── 04 - RESOURCES/ # 参考资料（主题、人物、地点、工具）；编译的 wiki ├── 05 - ARCHIVE/ # 已完成和不活跃的笔记 └── 06 - SYSTEM/ # CLAUDE.md、模板、MOCs ├── CLAUDE.md # 智能激活文件，每个工作流程都会读取 ├── templates/ # 每种笔记类型的笔记模板 └── MOCs/ # 内容地图（主题索引笔记） ``` 您归档笔记的文件夹编码了 *您正在使用它的目的*，而不是它来自哪里，因此您可以根据您对它的了解稍后找到它。参见 `skills/vault-structure.md` 以获取完整的检索优先哲学和放置逻辑。 ## 智能文件：CLAUDE.md `06 - SYSTEM/CLAUDE.md` 是每个工作流程告诉你什么是有用的 *对你来说具体* 的文件。没有它，Synaptic 可以组织笔记，但无法判断笔记是否值得保留、连接或显示。它记录了你的活跃项目、当前决策、写作主题、什么使笔记有用（什么没用）、你的声音和输出目标。`synaptic init` 通过采访你来生成它；每个技能和 `get_active_context` MCP 工具都会先读取它。保持它最新，整个系统就会根据你当前真正关心的事物进行调整。参见 `skills/claude-md.md`。 ## 技能 `skills/` 目录包含生产质量的 Obsidian 智能技能：可重用、详细的攻略手册，代理（或您）可以遵循。 | 技能 | 目的 | |-------|---------| | `vault-structure` | 检索优先的 PARA 架构、命名、前置信息、标签、三层模型 | | `capture-processor` | 每日收件箱处理、晨间捕获通道、学习加速器、摄入原则 | | `karpathy-ingest` | 单源摄入：归档到 `01-NOTES/`，然后通过邻居更新编译成永久笔记 | | `permanent-note` | 原子、链接、自己的文字笔记，带有关键紧张，用于 `04 - RESOURCES/topics/` | | `intelligence-layer` | 决策馈送器、写作激活器、写作解除粘滞剂、输出生成器 | | `connection-finder` | 每周连接表面、跨领域链接发现 | | `map-of-content` | MOC 创建和维护，用于 10+ 笔记主题集群 | | `claude-md` | 生成和应用知识库的智能激活文件（个人或共享） | | `retrieval-organization` | 搜索策略、收件箱处理、每周审计、季度审查 | | `weekly-ritual` | ~45 分钟的每周会话：收件箱 + 连接 + 孤立审计 + 回顾，带有调度配方 | | `project-completion` | 存档已完成的项目并提取学习成果 | | `local-llm-setup` | 安装 Ollama 或 LM Studio、选择模型、连接 Obsidian 社区插件 | | `vault-prompts` | 每个提示的快速参考备忘录，用于复制、粘贴和运行 | 来自 [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) 的上游基础技能已预加载到 `skills/obsidian-markdown/`、 `skills/obsidian-bases/`、 `skills/obsidian-cli/`、 `skills/json-canvas/` 和 `skills/defuddle/`。您无需单独安装它们。 ## CLI 参考 | 命令 | 它做什么 | |---------|--------------| | `synaptic init` | 交互式地创建一个新的 PARA 知识库（文件夹 + CLAUDE.md + 配置），个人或共享。 | | `synaptic doctor` | 检查配置、Ollama 可达性、模型和每个任务的活动提供商。 | | `synaptic scan` | 解析知识库并将实体加载到 SQLite。 | | `synaptic health` | 知识库健康状况：收件箱大小、未链接和孤立的笔记、缺失的前置信息。 | | `synaptic embed [--force]` | 通过 `nomic-embed-text` 计算语义嵌入。 | | `synaptic query "<question>"` | 提问；从知识库中用引用的来源回答。 `--save` 将答案写回。 | | `synaptic watch` | 当知识库更改时重新扫描受影响的笔记（文件监视器）。 | | `synaptic suggest-tags` | 生成带有置信度 + 证据的待处理标签建议。 | | `synaptic review [--min-rejections N] [--auto-approve-above F]` | 批准或拒绝待处理建议；将 N+ 次拒绝的标签显示为建议的 CLAUDE.md 编辑。 | | `synaptic write-tags [--dry-run]` | 将批准的标签写回每个笔记的前置信息中。 | | `synaptic brief "<name>"` | 生成隐私安全的联系简介。 | | `synaptic tags` | 列出已定义的主题笔记及其定义。 | | `synaptic contributed "<title>"` | 记录笔记对特定输出的贡献。 | | `synaptic contribution-report` | 显示哪些笔记已贡献 vs. 未使用。 | | `synaptic mcp` | 为 Claude Code 集成启动 MCP stdio 服务器。 | 每个命令都接受 `--root <path>` 以定位除当前目录之外的项目目录。 ## 可选集成 **PixelRAG / pixelbrowse（视觉网页阅读）。** [PixelRAG](https://github.com/StarTrail-org/PixelRAG) 给 Claude 配备了眼睛：它将任何 URL 或 PDF 截图成拼贴图像，以便图表、表格和布局可读，而不是在文本提取中丢失。使用它与 Synaptic 结合使用，这样 Synaptic 处理文本笔记，而 pixelbrowse 处理视觉文档内容。将它克隆到您存放工具的任何位置，然后使用活动插件启动 Claude Code： ```bash claude --plugin-dir /path/to/PixelRAG/plugin ``` 它完全在本地运行，除了 Chromium 之外（通过 Playwright）。 **LM Studio（替代本地运行程序）。** [LM Studio](https://lmstudio.ai) 提供可视化模型浏览器，并提供与 OpenAI 兼容的 API，位于 `http://localhost:1234/v1`。取消注释 `config.yaml` 中的 `lm_studio` 提供商块即可使用它代替 Ollama。它适用于发现和测试模型；Ollama 对于日常后台操作更轻量级。 ## 项目布局与开发 ``` synaptic/ config.py # 加载配置 + .env，提供者解析，本地强制执行 obsidian/ # Markdown + YAML 前置信息解析器，知识库加载器，文件监视器 db/ # SQLite 存储：实体、证据、标签建议、贡献、审计 llm/ # 提供者抽象（ollama / openai / anthropic / 兼容）+ 路由 + 启发式回退 privacy/ # 隐私分类 + 删减通道 tagging/ # 语义标签引擎（建议 + 证据 + 批准） briefs/ # 隐私安全简介生成器 search.py # 语义（余弦）+ 关键词（TF）搜索，共享分词器 templates/ # 规范的知识库笔记模板（单一真实来源） mcp/ # FastMCP stdio 服务器（7 种工具） cli.py # 入口 config/ # config.example.yaml examples/vault/ # 准备好运行的示例 Obsidian 知识库（PARA 结构） skills/ # Obsidian 智能技能 tests/ # pytest：存储查询、初始化分支、模板一致性、MCP 检索 ``` ```bash pip install -e ".[dev,mcp]" pytest tests/ ``` ## 路线图 1. ✅ 搭建、配置、示例知识库（PARA 结构）。 2. ✅ Obsidian 解析器 + 前置信息 + 文件监视器。 3. ✅ 本地数据库 + 语义嵌入（nomic-embed-text via Ollama，余弦相似度）。 4. ✅ LLM 提供者抽象 + Ollama + LM Studio + 路由 + 启发式回退。 5. ✅ 隐私分类 + 删减。 6. ✅ 标签引擎，置信度/证据 + 批准队列 + 前置信息写入。 7. ✅ 知识库健康命令。 8. ✅ 自然语言查询、贡献跟踪、MCP 服务器。 9. ✅ 交互式知识库初始化，个人/共享分支。 10. 🔶 测试覆盖率：存储、初始化、模板、MCP 检索。尚未全面：标签引擎、隐私分类器和 LLM 路由未覆盖。 11. ☐ 向量 ANN 索引（sqlite-vec / LanceDB）用于大型知识库（>5k 笔记）。 12. ☐ 知识库迁移工具：分类现有笔记，然后建议 PARA 放置。 ## 许可证 MIT。