basemouse-core

BaseMouse 是一个 AI 原生的文档/笔记仓库，面向工作区和 AI 智能体，定位为本地优先的知识库，能够导出结构化、带版本、智能体可直接使用的上下文包（context pack）。本仓库 basemouse-core 是其开源核心，是一个零依赖的 Node.js 应用。

用途 BaseMouse 旨在为智能体提供共享、带版本的记忆：智能体可以搜索知识库、获取带引用和校验和的上下文包，并通过写入接口持久化决策和会话上下文。它适合需要让多个智能体或工作区共享同一份可追溯知识源的场景。

主要能力

• 仓库内置种子数据（data/seed/*.json），提供 /api/repository 端点返回文档计数和规范化文档。
• 搜索端点 /api/search?q=... 返回带评分和匹配词的搜索结果。
• 上下文包端点 /api/context-pack?q=...&limit=... 导出智能体就绪的 basemouse.context_pack.v1 格式。
• 两个端点均支持分面过滤：type 和 tag 参数（大小写不敏感，空参数视为无过滤，超过 256 字符返回 400 错误），并回显应用的过滤器。
• 检索模式：lexical（默认，完全向后兼容）和 hybrid。hybrid 混合三种信号——词法词项重叠、沿文档链接的一跳图扩展、本地向量相似度——并为每个结果标注各信号检索块，解释其出现原因。向量信号使用 Node 内置的本地离线哈希特征嵌入（无外部向量数据库、无付费嵌入 API、无网络），本质是稠密空间中的词项重叠，而非语义模型；可通过 BASEMOUSE_VECTOR_RETRIEVAL=off 禁用（图+词法混合仍可用）。
• 上下文包包含引用、来源、文档版本、校验和、相关度、截断信息和智能体指令。
• 图感知关系：每个条目携带出站链接和解析后的相关列表，以及包级关系边列表，便于智能体追踪文档连接。
• 更安全的静态文件服务：路径包含、nosniff 头、畸形 URL 处理、API 验证和限制。
• Web UI 支持搜索、上下文包生成、原始 JSON 检查、复制和下载。
• 公开的 Agent Governance Demo 页面（/agent-governance-demo.html），展示合成治理语料、示例审计/操作查询，以及词法与混合检索质量基线。
• 公开的 Design Partner Intake 页面（/design-partner.html），征集小型真实语料、真实问题和具体智能体工作流以进行基准测试。
• 公开的替代方案/对比页面（/compare.html），涵盖人们替代 BaseMouse 的五种方式以及 BaseMouse 不适合的场景。
• 首页包含 JSON-LD 结构化数据（Organization、WebSite、SoftwareApplication、FAQPage），并通过测试固定到 src/billing.js 和可见 FAQ，防止标记漂移。
• clients/ 目录提供轻量级 JavaScript 和 Python API 客户端（见 docs/client-libraries.md）。
• integrations/slack/ 提供 Slack Socket Mode 连接器，用于本地 LLM + BaseMouse 接地。
• deployment/compose/ 提供 Dockerfile 和自托管 Docker Compose 示例（见 docs/self-hosted.md）。
• 检索质量评估工具（npm run eval:retrieval），黄金查询位于 data/retrieval-eval/。
• GitHub Actions 工作流用于 main 分支的测试/构建/推送。

使用方式 本地开发：运行零依赖 Node.js 应用，使用上述 API 端点。

写入 API 与持久化：设置 DATABASE_URL（托管 Postgres — Supabase）后，BaseMouse 运行持久存储：API 密钥限定私有工作区，写入为仅追加修订，公共演示语料在数据库故障时降级到仓库内种子（X-BaseMouse-Degraded: true）。未设置 DATABASE_URL 时，应用运行内存种子存储。当提供商服务器证书链到私有 CA 时，需提供 DATABASE_CA_CERT（PEM）；TLS 验证从不禁用。

MCP 连接：BaseMouse 在 POST /mcp 提供 Model Context Protocol（无状态 Streamable HTTP，JSON-RPC）。工具包括 search、get_context_pack 和 upsert_document（写入入口——智能体可通过稳定 id 幂等地持久化决策和会话上下文；内容未变则不写入），与 REST 使用相同的认证、作用域和配额计量。Claude Code 配置示例见官方文档。未认证的 POST /mcp 返回 401 并带 WWW-Authenticate，以便 Cursor 市场 Connect 启动 OAuth。可在同意页面粘贴现有 bm_ 密钥，或继续使用公共演示。配置文件客户端仍发送 Authorization: Bearer bm_...。REST 匿名演示不变。端点与工具无关：node integrations/cli/basemouse.mjs register 可打印适用于 Claude Code、Cursor、Windsurf、Codex CLI、Gemini CLI、Grok CLI、AWS Kiro 和 Google Antigravity 的即用 MCP 配置，以及通过 mcp-remote 桥接的仅 SSE 客户端（如 IBM Bob）。

同步工作区：integrations/cli/basemouse.mjs 是一个零依赖 Node CLI，可将 projects 工作区同步为 project:<slug> 标记的带版本文档。仅需 Node，无 bash/curl/jq，跨 Windows、macOS、Linux 行为一致。同步幂等且低成本：每个文档一次 PUT ?mode=upsert，服务器在自身规范化旁决定创建/未变/更新，标签增量合并，未变保存不写入。单文档失败警告并继续（空存根文件跳过而非失败）。需要 Node 20+ 和支持 upsert 的服务器（basemouse.com 或 D9 版本及以后的自托管）。可通过 BASEMOUSE_BASE_URL 覆盖自托管地址，--base-dir / BASE_DIR 覆盖工作区根目录。

通过 git push 同步（GitHub Action）：添加仓库密钥 BASEMOUSE_API_KEY，然后在 .github/workflows/basemouse-sync.yml 中配置。该 action 同步仓库的 CLAUDE.md / PROGRESS.md，标记为 project:<repo-name>（可用 slug 输入覆盖；base-url 指向自托管实例）。

计费/Stripe 设置：BaseMouse 从 /api/billing/config 渲染付费 Starter、Team 和 Enterprise 计划。POST /api/checkout 在配置 Stripe 时为自助层级创建 Stripe Checkout Session。若环境变量缺失，UI 和 API 降级为清晰的联系销售状态；本地不存储支付或客户数据。需在 Stripe 创建带月度循环价格的产品，为每个价格打上 tier 元数据（starter 或 team）；创建指向 /api/stripe/webhook 的 webhook 端点并复制签名密钥到 STRIPE_WEBHOOK_SECRET；设置环境变量并启用 CHECKOUT_ENABLED=true。推荐使用受限密钥（rk_…），最小作用域为 Checkout Sessions 和 Billing Portal Sessions 的写权限，以及 Checkout Sessions 的读权限用于声明验证路径。

种子文档：每个文档由 src/store.js 规范化，获得确定性来源元数据，并从规范化内容生成稳定的 16 字符 SHA-256 校验和。

托管服务运行在 Kubernetes 上，从 main 持续部署。自托管者可用 deployment/compose/ 中的 Docker Compose 示例部署相同镜像。

若在 apex 和 www 主机名上提供同一站点，可设置 CANONICAL_HOST 为裸域名（如 example.com），则到达 www.<CANONICAL_HOST> 的 GET 和 HEAD 请求会 308 重定向到裸主机，使爬虫只索引一个源。仅 GET 和 HEAD 重定向，POST 流量（API、MCP、webhook）不受影响。不设置则禁用重定向（默认）。

文档：docs/getting-started.md（首次调用 API 和 MCP 端点）、docs/agent-integration.md（将 BaseMouse 接入智能体和 MCP 客户端）、docs/client-libraries.md（JavaScript 和 Python API 客户端）、docs/retrieval-eval.md（黄金查询检索质量工具）、docs/demo-corpus-agent-governance.md（公共 Agent Governance Demo 语料、页面和评估基线）、docs/self-hosted.md（在公司网络内运行 BaseMouse + 本地 LLM + Slack）。

适用场景

• 需要为 AI 智能体提供共享、带版本、可追溯记忆的工作区。
• 需要智能体引用来源、校验和和文档版本的场景。
• 需要本地优先/自托管隐私、仅追加历史和审计追踪的团队。
• 需要将编码工作区（CLAUDE.md / PROGRESS.md）同步到知识库并通过 MCP 供智能体使用的开发者。

限制

• 当前向量检索为本地离线哈希特征嵌入，是稠密空间中的共享词汇重叠，并非学习到的语义模型。
• 混合检索中的图扩展仅为一跳，非完整 GraphRAG。
• 路线图（尚未实现，仅方向）：真实语料检索评估套件、语义向量检索、完整 GraphRAG、记忆胶囊、内置智能体沙箱、精确画布 UX、MeshAI 集成（OpenTelemetry）。
• MeshAI 集成默认禁用，配置前为空操作；仅发送检索证据（查询、计数、文档 id），不发送文档正文。
• 付费计划存在，但具体价格和功能细节暂未提供。
• 托管服务状态为 live（付费计划），版本 v0.3。