# https://github.com/Abhinav1234abhinav/neurostack 项目说明书 生成时间：2026-06-29 11:31:12 UTC ## 目录 - [Overview and System Architecture](#page-1) - [Tool Registry and Retrieval Engine](#page-2) - [Data Layer, Schema and Knowledge Graph](#page-3) - [Deployment, Cloud Sync and Extensibility](#page-4) ## Overview and System Architecture ### 相关页面 相关主题：[Tool Registry and Retrieval Engine](#page-2), [Data Layer, Schema and Knowledge Graph](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/README.md) - [npm/README.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/npm/README.md) - [npm/package.json](https://github.com/Abhinav1234abhinav/neurostack/blob/main/npm/package.json) - [src/neurostack/__init__.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/__init__.py) - [src/neurostack/tools/registry.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/registry.py) - [src/neurostack/tools/rest_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/rest_adapter.py) - [src/neurostack/tools/openai_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/openai_adapter.py) - [src/neurostack/tools/mcp_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/mcp_adapter.py) - [src/neurostack/tools/search_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/search_tools.py) - [src/neurostack/tools/insight_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/insight_tools.py) - [src/neurostack/tools/memory_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/memory_tools.py) - [src/neurostack/ask.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/ask.py) - [src/neurostack/api.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/api.py) - [src/neurostack/cloud/manifest.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cloud/manifest.py) - [src/neurostack/skills/vault-search.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-search.md) - [src/neurostack/skills/vault-audit.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-audit.md)
# Overview and System Architecture ## 项目定位与设计目标 NeuroStack 是一个本地优先（local-first）、AI 提供方无关的知识管理与检索工具，当前版本为 `0.10.1`。资料来源：[src/neurostack/__init__.py:1-9]() 中将其明确定义为 "AI-provider-agnostic, neuroscience-grounded knowledge management"。项目的核心目标是让用户在本地构建一个可被智能检索、相互链接的第二大脑，并通过统一协议与外部 LLM 协作,而非将数据上传到云端。 依据资料来源：[README.md:1-40]()，项目跨平台支持 Windows / Linux / macOS，最低仅需 4 GB 内存与约 100 MB 磁盘空间；AI 功能是可选增强项而非必备依赖。资料来源：[npm/README.md:1-15]() 进一步说明其同时提供 Python 与 npm 两套分发形态。 ## 系统架构总览 NeuroStack 采用 **"工具定义 + 协议适配"** 的分层架构。业务功能以 Python 函数形式通过统一注册中心暴露，再由若干 Adapter 分别翻译为 REST、OpenAI Function Calling、MCP 等不同协议，从而被命令行、HTTP 客户端或 AI Agent 进程调用。 ```mermaid flowchart TB subgraph 协议适配层[Protocol Adapters] REST["REST Adapter
POST /v1/tools/{name}
GET /v1/tools"] OAI["OpenAI Adapter
function calling schema"] MCP["MCP Adapter
FastMCP / stdio"] end REG["ToolRegistry
@registry.tool 装饰器"] subgraph 业务工具集[Business Tools] SRCH["search_tools
vault_search / vault_ask"] MEM["memory_tools
vault_memories / vault_capture"] INS["insight_tools
session_brief / vault_context"] end subgraph 存储与同步[Storage & Sync] DB[("SQLite + FTS5")] VAULT["Markdown Vault"] CLOUD["Content-Hash Manifest
SHA-256"] end AI["LLM / Embedding
OpenAI-compatible endpoint"] REST --> REG OAI --> REG MCP --> REG REG --> SRCH REG --> MEM REG --> INS SRCH --> DB SRCH --> VAULT SRCH --> AI MEM --> DB INS --> DB VAULT <--> CLOUD ``` ## 核心模块剖析 ### 工具注册与协议适配层 所有功能均通过单例 `ToolRegistry` 注册。资料来源：[src/neurostack/tools/registry.py:50-90]() 指出，开发者使用 `@registry.tool(tags=[...])` 装饰器即可声明一个工具；参数 schema 通过 `inspect.signature` 自动抽取，docstring 首段被 `_extract_description` 抽取为描述。注册后的工具再由三类 Adapter 暴露： | 适配器 | 暴露形态 | 关键能力 | 来源 | |--------|----------|----------|------| | REST Adapter | FastAPI 路由 `POST /v1/tools/{name}`、`GET /v1/tools` | 通用 HTTP 调用，OpenAPI-ready | [src/neurostack/tools/rest_adapter.py:25-50]() | | OpenAI Adapter | `tools=` 字段的 function 定义 | 兼容 OpenAI / Ollama 的 function calling | [src/neurostack/tools/openai_adapter.py:60-100]() | | MCP Adapter | FastMCP `mcp.tool()` 包装 | 为 Claude / Agent 进程提供 stdio 工具 | [src/neurostack/tools/mcp_adapter.py:15-40]() | OpenAI Adapter 额外截断 docstring 至 1024 字符以满足 OpenAI 描述字段上限；REST Adapter 通过 `_param_to_json_schema` 将 Python 类型转换为 JSON Schema；MCP Adapter 则用 `functools.wraps` 保留签名与文档，避免协议层签名漂移。 ### 检索与上下文装配层 检索层采用"分层深度（depth）"策略以权衡 token 成本。资料来源：[src/neurostack/skills/vault-search.md:1-25]() 列出了 `triples / summaries / full / auto` 四种 `depth` 取值，分别对应 SPO 三元组、预生成摘要、全文片段与系统自动决策。`vault_ask` 在此基础上封装为标准 RAG 流程：调用 `hybrid_search` → 拼接 prompt → 经 `httpx` 调用 OpenAI 兼容端点（temperature=0.3、max_tokens=500） → 剥离 `` 标签 → 返回带 `[[note-title]]` 内联引用的答案。资料来源：[src/neurostack/ask.py:50-100]()。 上下文工具则面向"会话恢复"场景：`session_brief` 提供约 500 token 的时间锚定快照（最近变更、git commits、记忆、连接最密的笔记）；`vault_context` 按任务描述在默认 2000 token 预算内拉取记忆、三元组、摘要与历史。资料来源：[src/neurostack/tools/insight_tools.py:30-70]()。 ### 存储、记忆与同步层 底层采用 SQLite + FTS5 提供全文检索能力。`memory_tools` 提供 `vault_capture`（零摩擦快速捕获到 `inbox/`）、`vault_memories`（FTS5 + 语义相似度混合检索）等能力，记忆类型涵盖 `observation / decision / convention / learning / context / bug` 六类。资料来源：[src/neurostack/tools/memory_tools.py:60-100]()。 云同步通过 `Manifest` 扫描 vault 目录并计算 SHA-256 哈希，仅上传"新增"或"变更"文件。资料来源：[src/neurostack/cloud/manifest.py:15-45]() 中 `SyncDiff.has_changes` 与 `upload_files` 属性明确界定了这一增量同步语义，避免重复传输。 健康审计能力由独立 skill 提供。资料来源：[src/neurostack/skills/vault-audit.md:1-25]() 暴露了 `vault_stats` / `vault_prediction_errors` / `vault_record_usage` 等检查点，用于追踪嵌入覆盖率、检索质量与使用热度（hotness scoring）。 ## 运行模式与部署形态 项目同时支持 **full mode** 与 **lite mode** 两种安装形态。资料来源：[npm/README.md:20-35]() 与 [npm/package.json:1-25]() 显示 npm 包通过 `postinstall` 脚本自动安装 `uv`、克隆仓库并创建虚拟环境；设置 `NEUROSTACK_MODE=lite` 即可跳过 ML 依赖获得最小化安装。Full mode 默认依赖 Ollama 上的 `nomic-embed-text` 与 `qwen2.5:3b` 模型。 REST API 入口由 `create_app()` 构建并在 `run_server()` 中通过 uvicorn 启动，监听来自配置的 `api_host` / `api_port`。资料来源：[src/neurostack/api.py:80-110]()。该服务同时提供 OpenAI 兼容的 `/v1/embeddings` 端点，使 NeuroStack 可作为向量后端被其它应用复用。 ## See Also - 工具注册中心与协议适配器详解 - 检索策略（triples / summaries / full）与 RAG 流程 - 记忆系统与内容哈希增量同步 - 安装模式（full / lite）与 CLI / npm 部署 --- ## Tool Registry and Retrieval Engine ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Data Layer, Schema and Knowledge Graph](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/neurostack/tools/registry.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/registry.py) - [src/neurostack/tools/__init__.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/__init__.py) - [src/neurostack/tools/search_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/search_tools.py) - [src/neurostack/tools/insight_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/insight_tools.py) - [src/neurostack/tools/openai_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/openai_adapter.py) - [src/neurostack/tools/rest_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/rest_adapter.py) - [src/neurostack/ask.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/ask.py) - [src/neurostack/skills/vault-search.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-search.md) - [src/neurostack/skills/vault-audit.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-audit.md)
# Tool Registry and Retrieval Engine ## 架构概览 Tool Registry and Retrieval Engine 是 neurostack 的中枢模块，职责是把本地知识库（Markdown vault + SQLite + Embedding）的能力以"协议无关"的工具形式暴露给上层调用方（CLI、LLM、MCP/REST 客户端）。设计上坚持三点： 1. **单一注册中心**：所有工具以 Python 函数 + `@registry.tool(...)` 装饰器登记到同一份 `ToolRegistry` 单例。 2. **多协议适配**：同一份注册表被不同 adapter 渲染为 OpenAI function-calling、FastAPI REST、CLI/MCP 调用三种形态，调用方共享同一个工具名空间。 3. **按深度分级 + 按工作区隔离**：检索工具以 `depth ∈ {"triples","summaries","full","auto"}` 控制成本，以 `workspace` 子目录前缀限定作用域。 整体调用链是 `tool 函数 → ToolDef → registry → adapter → 客户端 → registry.call(...) → tool 函数 → dict 结果 → JSON`。 ## 注册表与适配器 `ToolRegistry` 是轻量内存字典，键为工具名，值为 `ToolDef`。装饰器 `@registry.tool(name=..., tags=[...])` 接收可选 `name` 与 `tags`（如 `["search", "retrieval"]`），并通过 `inspect.signature` 自动抽取参数类型生成 `ToolParam` 列表 [资料来源：[src/neurostack/tools/registry.py:60-110]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/registry.py)。被装饰函数必须返回 `dict`，序列化交给上层处理；首次访问时由 `ensure_registered()` 惰性导入 `insight_tools / memory_tools / search_tools / session_tools` 四组工具完成填充 [资料来源：[src/neurostack/tools/__init__.py:18-33]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/__init__.py)。 当前已落地的两条适配路径： - **OpenAI 适配器** 把工具渲染为标准 `{"type":"function","function":{...}}` schema，并将模型返回的 `name + arguments` 反序列化后调用 `registry.call(name, **arguments)`，结果以 JSON 字符串回填到 `tool_call.response` [资料来源：[src/neurostack/tools/openai_adapter.py:30-90]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/openai_adapter.py)。 - **REST 适配器** 通过 `create_tools_router(prefix="/v1/tools")` 创建 FastAPI `APIRouter`，暴露 `GET /v1/tools`（列出全部工具的 JSON Schema）与 `POST /v1/tools/{tool_name}`（按名调用，参数取自 JSON body），把每个 `ToolParam` 自动转为 JSON Schema [资料来源：[src/neurostack/tools/rest_adapter.py:25-110]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/rest_adapter.py)。 这种"单注册中心 + 多适配器"模式让新增协议（例如 MCP）只需新增一个 adapter，注册表本体无需改动。 ## 检索工具与分级深度 `search_tools.py` 是检索核心入口，提供 `vault_search / vault_triples / vault_ask / vault_summary / vault_communities / vault_stats` 等 [资料来源：[src/neurostack/tools/search_tools.py:35-200]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/search_tools.py)。下表按用途与成本对比常用工具： | 工具 | 适用场景 | Token 量级 | |------|---------|-----------| | `vault_search(depth="triples")` | 快速事实查询（SPO 三元组） | ~10-20/事实 | | `vault_search(depth="summaries")` | 主题概览（2-3 句摘要 + frontmatter） | ~50-100/笔记 | | `vault_search(depth="full")` | 需要真实内容/片段 | ~200-500/结果 | | `vault_triples(query)` | 仅 SPO 事实，最廉价 | 极低 | | `vault_communities(query, map_reduce=True)` | 全局/主题性问题（GraphRAG map-reduce） | 高（LLM） | | `vault_ask(question, top_k=8)` | RAG 问答并内联 `[[note-title]]` 引用 | 高（LLM） | | `vault_summary(path_or_query)` | 按路径或查询拿预存摘要 | ~100-200/笔记 | | `vault_stats()` | 索引健康度（笔记/chunk/embedding 覆盖、摘要陈旧度） | 极低 | `tiered_search` 与 `hybrid_search` 在底层按 `triples → summaries → full` 自动降级，`mode` 支持 `hybrid / semantic / keyword` 三种召回方式。`vault_ask` 走标准 RAG：先用 `hybrid_search` 召回 top_k 片段，再用 OpenAI 兼容 chat-completion 端点作答，prompt 强制要求输出 `[[note-title]]` 内联引用 [资料来源：[src/neurostack/ask.py:30-90]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/ask.py)。 ## 上下文、会话与审计 除检索外，`insight_tools.py` 与 `session_tools.py` 提供"上下文/会话/审计"能力： - `session_brief(workspace=None)`：约 500 token 的会话快照，包含最近 vault 变更、git commit、近期记忆、连接度最高的笔记及时间上下文，典型用途是新会话开场 [资料来源：[src/neurostack/tools/insight_tools.py:30-60]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/insight_tools.py)。 - `vault_context(task, token_budget=2000, include_memories=True, include_triples=True)`：以"任务"为锚（而非时间），在 token 预算内召回相关记忆、三元组、摘要与会话历史，用途是 `/clear` 或切换会话后快速恢复 [资料来源：[src/neurostack/tools/insight_tools.py:60-110]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/insight_tools.py)。 - `vault_stats()`：直接查 SQLite 输出笔记、chunk、embedding、摘要陈旧度、图边、三元组数量等健康指标。 - `vault_prediction_errors()` / `vault_record_usage(note_paths=[...])`：前者暴露检索质量差的笔记，后者把被真正使用过的笔记通过"热度"分数拉高，影响后续排序 [资料来源：[src/neurostack/skills/vault-audit.md:5-30]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-audit.md)。 ## 使用模式与选型决策树 skills 文档给出了一条清晰的检索选型路径 [资料来源：[src/neurostack/skills/vault-search.md:13-30]()](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-search.md)： 1. 需要具体事实 → `vault_triples` 或 `vault_search(depth="triples")` 2. 需要主题概览 → `vault_search(depth="summaries")` 3. 需要真实内容 → `vault_search(depth="full")` 4. 宽泛/主题性问题 → `vault_communities` 5. 需要带引用的答案 → `vault_ask` 6. 探索某条笔记的连接 → `vault_graph` 7. 寻找相似笔记 → `vault_related` 8. 检索 agent 写下的"记忆" → `vault_memories` 调用方只需先执行 `from neurostack.tools import ensure_registered; ensure_registered()`，随后即可通过任一适配器（OpenAI function-calling、REST `POST /v1/tools/{name}`、CLI）拿到同名同语义的工具，避免在每个入口重复定义。 ## See Also - [Configuration & Vault Root](#) - [Embedding & Index Pipeline](#) - [Skills and Prompt Library](#) --- ## Data Layer, Schema and Knowledge Graph ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Tool Registry and Retrieval Engine](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [src/neurostack/schema.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/schema.py) - [src/neurostack/embedder.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/embedder.py) - [src/neurostack/chunker.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/chunker.py) - [src/neurostack/attractor.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/attractor.py) - [src/neurostack/cooccurrence.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cooccurrence.py) - [src/neurostack/related.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/related.py) - [src/neurostack/ask.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/ask.py) - [src/neurostack/tools/search_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/search_tools.py) - [src/neurostack/tools/memory_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/memory_tools.py) - [src/neurostack/__init__.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/__init__.py)
# 数据层、Schema 与知识图谱 ## 概览 neurostack 的数据层承担着"第二大脑"的核心职责：把本地 Markdown 笔记、嵌入向量、知识三元组、记忆条目与社区结构统一持久化到 SQLite 中，供上层检索、RAG 问答与 AI 代理调用。整套系统在 [src/neurostack/__init__.py:5-6](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/__init__.py) 中被定位为"AI-provider-agnostic, neuroscience-grounded knowledge management"——一个与具体 AI 提供方解耦、以神经科学启发的记忆模型为底层隐喻的知识管理系统。 数据层的关键设计目标是**本地优先、可增量更新、兼容 Lite 模式**。在 [npm/README.md:21-26](https://github.com/Abhinav1234abhinav/neurostack/blob/main/npm/README.md) 中明确区分了两种安装模式： | 模式 | 包含能力 | 触发方式 | |------|---------|---------| | `full`（默认） | 语义搜索、AI 摘要、重排序、吸引子社区检测 | `npm install -g neurostack` | | `lite` | 不含 ML 依赖的最小化安装 | `NEUROSTACK_MODE=lite npm install -g neurostack` | Lite 模式下 `numpy` 等可选依赖不会被拉入，因此诸如 `attractor.py` 中的社区检测会显式抛出 `ImportError` 提示用户安装 `neurostack[full]`。资料来源：[src/neurostack/attractor.py:1-25]()。 ## 数据库 Schema 所有数据通过 SQLite 存储在由 [src/neurostack/schema.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/schema.py) 中 `DB_PATH` 指向的本地文件中，并在 [src/neurostack/tools/search_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/search_tools.py) 的 `vault_summary` / `vault_search` 等工具中通过 `get_db(DB_PATH)` 取得连接。主要表与职责如下： | 表名 | 主要字段 | 职责 | |------|---------|------| | `notes` | `path`、`title`、`frontmatter`、`pagerank`、`in_degree`、`out_degree` | 笔记元数据与图中心性 | | `chunks` | `note_path`、`text`、`embedding` (BLOB)、`heading_path` | 文本分块及对应的嵌入向量 | | `summaries` | `note_path`、`summary_text` | 预生成的 2-3 句摘要（来自 [src/neurostack/tools/search_tools.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/search_tools.py) 中 `vault_summary` 的 `LEFT JOIN` 查询）| | `triples` | `note_path`、`subject`、`predicate`、`object` | 知识图谱的 Subject-Predicate-Object 事实 | | `memories` | `memory_id`、`content`、`entity_type`、`tags`、`workspace` | 代理写入的长期记忆（[src/neurostack/tools/memory_tools.py:1-15]()）| | `community_members` / `communities` | 吸引子动力学结果 | 粗粒度（β=0.5）与细粒度（β=2.0）两套社区 | | `entity_cooccurrence` | 实体对权重 | 由 `persist_cooccurrence(conn)` 从 `triples` 派生（[src/neurostack/attractor.py:30-40]()）| 嵌入向量以 BLOB 形式落盘；读取时通过 `blob_to_embedding(r["embedding"])` 反序列化为 numpy 数组，支撑后续余弦相似度与 PageRank 计算。资料来源：[src/neurostack/attractor.py:42-55]()。 ## 嵌入与文本分块 笔记在入库前会经过 [src/neurostack/chunker.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/chunker.py) 的分块器按 `heading_path` 切片，再交由 [src/neurostack/embedder.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/embedder.py) 调用的嵌入服务向量化。结果既可直接用于 `hybrid_search` 的稠密检索，也会按 `note_path` 聚合为笔记级向量，以驱动 [src/neurostack/related.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/related.py) 中的 `find_related()`，发现未显式链接但语义相近的笔记。 RAG 问答流程在 [src/neurostack/ask.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/ask.py) 中串起整条管线：`hybrid_search` 取出前 `top_k` 个相关片段 → 构造 `[Title] (path): snippet` 形式的 source block → 拼接 `ASK_PROMPT` → 调用与 OpenAI 兼容的 `/v1/chat/completions`（`temperature=0.3`、`max_tokens=500`）→ 去除 `` 噪声后返回带 `[[note-title]]` 内联引用的答案。 ```mermaid flowchart LR A[Markdown 笔记] --> B[chunker.py
按 heading 切片] B --> C[embedder.py
向量化] C --> D[(chunks.embedding
BLOB)] A --> E[schema.py
notes / triples] D --> F[hybrid_search /
tiered_search] E --> G[attractor.py
吸引子动力学] F --> H[ask.py
RAG 问答] G --> H ``` ## 知识图谱与社区检测 知识图谱由三种边共同构成：**显式 Wiki 链接**（`in_degree` / `out_degree` 反映在 `notes` 表）、**从笔记中抽取的 SPO 三元组**（`triples` 表，被 `vault_triples` 以约 10-20 token/事实的紧凑形式返回，资料来源：[src/neurostack/tools/search_tools.py:1-20]()）、以及**实体共现权重**（`entity_cooccurrence` 表，由 [src/neurostack/cooccurrence.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cooccurrence.py) 从三元组派生）。 社区检测由 [src/neurostack/attractor.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/attractor.py) 实现：先融合嵌入相似度、共现权重与 Wiki 链接得到混合相似矩阵，再分别以 β=0.5（粗）与 β=2.0（细）两档温度参数运行吸引子动力学，**清除已有社区后做全量重建**，最终将收敛到的吸引子盆分配给各笔记。重建时若 `len(note_paths) < 3` 会跳过并打 warning。资料来源：[src/neurostack/attractor.py:1-55]()。 对外暴露的检索工具按成本由低到高形成清晰的选择阶梯，`vault_search(depth="triples"|"summaries"|"full"|"auto")` 决定读取深度，`vault_graph` 用于沿显式链接做邻居遍历并附带 `pagerank` 分数，`vault_related` 走嵌入相似度发现隐式连接，`vault_communities` 则面向全局主题性问题（GraphRAG，最贵）。这一决策树已沉淀在技能说明 [src/neurostack/skills/vault-search.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-search.md) 中，供 AI 代理按需选用。 ## 常见失败模式 - **Lite 模式运行社区检测**：会触发 `ImportError("Community detection requires numpy. Install with: pip install neurostack[full]")`（[src/neurostack/attractor.py:8-13]()）。 - **没有嵌入的块**：`attractor.py` 检测到 `chunk_rows` 为空时记 warning 并 `return 0, 0`，不会创建社区。 - **笔记过少**：少于 3 个已嵌入笔记时同样跳过社区检测。 - **RAG 无命中**：`ask.py` 在 `hybrid_search` 返回空时直接返回 `"No relevant notes found in the vault."` 而非调用 LLM，避免幻觉。资料来源：[src/neurostack/ask.py:1-25]()。 ## 参见 - [搜索与检索工具](搜索与检索工具.md) - [AI 代理集成（MCP / OpenAI / REST）](AI代理集成.md) - [配置与模式（full / lite）](配置与模式.md) --- ## Deployment, Cloud Sync and Extensibility ### 相关页面 相关主题：[Overview and System Architecture](#page-1), [Data Layer, Schema and Knowledge Graph](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/README.md) - [npm/README.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/npm/README.md) - [npm/package.json](https://github.com/Abhinav1234abhinav/neurostack/blob/main/npm/package.json) - [src/neurostack/__init__.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/__init__.py) - [src/neurostack/cloud/__init__.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cloud/__init__.py) - [src/neurostack/cloud/manifest.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cloud/manifest.py) - [src/neurostack/cloud/sync.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cloud/sync.py) - [src/neurostack/cloud/config.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/cloud/config.py) - [src/neurostack/tools/rest_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/rest_adapter.py) - [src/neurostack/tools/openai_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/openai_adapter.py) - [src/neurostack/tools/mcp_adapter.py](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/tools/mcp_adapter.py)
# 部署、云同步与可扩展性 NeuroStack 是一个本地优先的 AI 知识库工具，其部署、云同步与可扩展性三个维度共同构成了从单机使用到多端协作、从基础功能到多协议集成的完整链路。`__init__.py` 中将项目定位为「AI 提供商无关、神经科学启发的知识管理」工具，版本号 `0.10.1` 资料来源：[src/neurostack/__init__.py:5-9]()。 ## 1. 部署：双通道安装与模式选择 NeuroStack 提供两条主要部署通道：**Python 源码直接运行** 与 **npm 包装器**。`package.json` 中定义了 `bin` 字段，注册 `neurostack` 与 `ns` 两个命令，并通过 `postinstall` / `preuninstall` 钩子自动处理 Python 虚拟环境的创建与清理 资料来源：[npm/package.json:3-15]()。 npm 包装器要求环境为 **Linux 或 macOS**、**Python 3.11+**（需启用 SQLite FTS5）、`git` 与 `curl`，安装器会自动安装 `uv`、克隆代码库并建立 venv 资料来源：[npm/README.md:17-25]()`。项目同时支持两种运行模式： | 模式 | 启用方式 | 特性差异 | |------|----------|----------| | Full（默认） | `npm install -g neurostack` | 包含语义搜索、AI 摘要、重排序等 ML 依赖 | | Lite | `NEUROSTACK_MODE=lite npm install -g neurostack` | 最小化安装，不含 ML 依赖 | 若启用 Full 模式的 Ollama 后端，还需手动拉取嵌入模型 `nomic-embed-text` 与生成模型 `qwen2.5:3b` 资料来源：[npm/README.md:27-33]()。这意味着用户可以按算力与隐私需求灵活裁剪部署范围。 ## 2. 云同步：基于内容哈希的增量同步 云同步功能位于 `src/neurostack/cloud/` 子包，对应 CLI 的 `neurostack cloud push/pull/query` 命令；服务端基础设施独立于 `neurostack-cloud` 包 资料来源：[src/neurostack/cloud/__init__.py:1-9]()。 ### 2.1 清单与差异计算 `Manifest` 类通过扫描 vault 根目录为每个 `.md` 文件计算 **SHA-256 哈希**，生成 `相对路径 → 哈希值` 的映射表，并提供 `scan_vault()` 与 `SyncDiff` 工具来识别新增、变更与删除的文件 资料来源：[src/neurostack/cloud/manifest.py:23-58]()。`SyncDiff.upload_files` 属性返回需要上传的文件集合，避免重复传输未变更内容。 ### 2.2 同步引擎与配置 `VaultSyncEngine` 使用 `httpx` 进行 multipart 上传、状态轮询与流式下载，所有 HTTP 调用均带 Bearer 认证头 资料来源：[src/neurostack/cloud/sync.py:17-48]()。其构造参数 `poll_interval`（默认 5.0 秒）与 `poll_timeout`（默认 3600.0 秒）控制索引轮询行为。配置加载遵循 **默认值 → `config.toml` `[cloud]` 节 → 环境变量** 的三层优先级，其中 `NEUROSTACK_CLOUD_API_URL` 与 `NEUROSTACK_CLOUD_API_KEY` 可作为最高优先级覆盖 资料来源：[src/neurostack/cloud/config.py:42-71]()。 ```mermaid flowchart LR A[本地 Vault
.md 文件] --> B[Manifest.scan_vault
SHA-256 哈希] B --> C{SyncDiff
差异计算} C -->|added/changed| D[VaultSyncEngine
multipart 上传] C -->|removed| E[记录删除] D --> F[云端索引器] F --> G[轮询状态
poll_interval=5s] G --> H[下载索引 DB] H --> I[远程查询] ``` ## 3. 可扩展性：统一注册表与多协议适配器 NeuroStack 的核心可扩展性来源于 **工具注册表**（`registry`）与三类适配器，它们把同一套内部函数暴露给不同协议消费方： - **REST 适配器**：`create_tools_router(prefix="/v1/tools")` 创建 FastAPI 路由，自动生成 `GET /v1/tools`（列出所有工具及参数 schema）与 `POST /v1/tools/{tool_name}`（调用工具）端点 资料来源：[src/neurostack/tools/rest_adapter.py:9-37]()。 - **OpenAI 适配器**：`get_openai_tools()` 把注册表中的工具转换为 OpenAI function calling 格式（截断 docstring 至 1024 字符），`execute_tool_call()` 反向解析 function call 并执行 资料来源：[src/neurostack/tools/openai_adapter.py:31-65]()。 - **MCP 适配器**：`create_mcp_server(name="neurostack")` 通过 `FastMCP` 自动包装所有工具函数，保留原函数签名与 docstring，可通过 `mcp.run(transport="stdio")` 启动 资料来源：[src/neurostack/tools/mcp_adapter.py:17-34]()。 三类适配器共享同一注册表（`ensure_registered()`），新增工具只需通过 `@registry.tool(tags=[...])` 装饰器声明，即可在 REST、OpenAI、MCP 三种协议下同时可用——这是项目支持任意 AI 提供商的关键机制。 ## 4. 常见失败模式 - **Windows 原生安装受限**：`package.json` 的 `os` 字段仅声明 `["linux", "darwin"]`，Windows 用户需通过 WSL 或 Python 源码方式部署 资料来源：[npm/package.json:34-36]()。 - **同步清单路径错位**：若 vault 根目录包含被忽略的子目录，`scan_vault()` 需正确处理 `relative_path` 的统一分隔符，否则哈希会因路径表示差异而失配。 - **云端凭据残留**：`clear_cloud_credentials()` 仅清空 `cloud_api_key` 而保留 `cloud_api_url`，切换账户时需注意 URL 是否仍指向原租户 资料来源：[src/neurostack/cloud/config.py:23-31]()。 ## See Also - [README.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/README.md) — 项目总体说明 - [src/neurostack/skills/vault-search.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/vault-search.md) — 检索策略与工具选择 - [src/neurostack/skills/memory-management.md](https://github.com/Abhinav1234abhinav/neurostack/blob/main/src/neurostack/skills/memory-management.md) — 记忆管理 API --- --- ## Doramagic 踩坑日志 项目：Abhinav1234abhinav/neurostack 摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。 ## 1. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Abhinav1234abhinav/neurostack | README/documentation is current enough for a first validation pass. ## 2. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Abhinav1234abhinav/neurostack | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Abhinav1234abhinav/neurostack | no_demo; severity=medium ## 4. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Abhinav1234abhinav/neurostack | no_demo; severity=medium ## 5. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Abhinav1234abhinav/neurostack | issue_or_pr_quality=unknown ## 6. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Abhinav1234abhinav/neurostack | release_recency=unknown