Skip to main content
Glama
deenesjakoruzh
nasyx-rakeeb

knownpath

by nasyx-rakeeb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

KnownPath

KnownPath 是一个面向 AI 编程代理的开源共享知识网络。其长期目标是让代理不再反复重新发现相同的技术解决方案，而是通过代理原生的接口提供经过验证、可复用的工程经验。

[!IMPORTANT] KnownPath 正在积极进行分阶段开发。Phase 13 添加了可移植的安装器 CLI 以及五个编程代理的安全适配器。贡献/成果工具、仪表板、公开注册和公开匿名访问尚未实现。安装器以 knownpath 发布。

先决条件

  • Node.js 24 LTS（.nvmrc 跟踪所支持的主版本；package.json 执行已验证的版本范围）

  • Corepack（随受支持的 Node.js 发行版提供）

  • Docker Desktop 或其他支持 Compose 的 Docker Engine，用于本地 MongoDB

Related MCP server: Cortex

安装

corepack enable
pnpm install
cp .env.example .env

按照 .env.example 中的说明生成独立的 BETTER_AUTH_SECRET 和 API_KEY_PEPPER 值。已提交的示例不包含任何默认凭据。

启动当前的开发环境

启动 MongoDB：

pnpm dev:infra

创建或同步当前的集合、验证器和索引：

pnpm db:init

可选的持久化检查和仓库层往返验证：

pnpm db:inspect
pnpm db:verify

通过掩码 CLI 创建第一个本地用户或管理员（注册已关闭）：

pnpm auth:user:create

可选，在 .env 中设置 GITHUB_TOKEN 以获得常规的 5,000 次请求认证 REST API 限制以及 GitHub Discussions 访问权限。然后预览或运行一次有界的采集：

pnpm ingest:github --source expo-core --types issues --limit 5 --dry-run
pnpm ingest:github --source expo-core --types issues --limit 5

在运行回填之前，请参阅 GitHub 摄取指南。

在不写入源记录的情况下发现当前经过整理的官方文档集，然后同步一个有界的源或一个已索引页面。

pnpm ingest:sources discover --source expo-documentation --limit 20
pnpm ingest:sources sync --source expo-documentation --limit 5 --dry-run
pnpm ingest:sources sync --source expo-documentation \
  --page https://docs.expo.dev/workflow/upgrading-expo-sdk-walkthrough --limit 1

在更改整理策略或请求有界的完整目录运行之前，请参阅 官方源摄取指南。

在被忽略的 .env 中使用 Gemini 开发密钥处理或检查一个有界的公共源候选：

pnpm extract one --source-item <uuid>
pnpm extract pending --limit 5
pnpm extract inspect --attempt <uuid>
pnpm extract inspect --candidate <uuid>

未付费的 Gemini 路径会在任何提供商调用之前直接拒绝私有/团队源记录。在配置该密钥或扩展批处理之前，请阅读 AI 提取指南。

在不调用 AI 提供商的情况下对提取的候选进行评分，然后检查完整的评分明细/历史：

pnpm score one --candidate <uuid>
pnpm score pending --limit 10
pnpm score inspect --assessment <uuid>
pnpm score history --candidate <uuid>

评分是可解释的排序信号，不是真理概率。在更改版本化策略之前，请阅读 评分指南。

构建不可变的相似性画像，发现被阻止的候选对，检查评审记录，并仅应用确定性安全的规范化合并：

pnpm canonicalize profile --limit 10
pnpm canonicalize discover --limit 10
pnpm canonicalize review --limit 20
pnpm canonicalize auto-merge --limit 10       # dry-run
pnpm canonicalize auto-merge --limit 10 --apply
pnpm canonicalize history --known-path <uuid>

Gemini embeddings 仅在所有候选及相关源都经过验证为公开后才生成。它们只是为可能被阻止的比较提供替换，而绝不会决定自动合并。在应用合并或手动操作之前，请阅读 规范化指南。

构建当前规范的搜索投影，并在本地查询它们。除非明确请求，否则评审状态记录会被排除在外：

pnpm run search project --pending --limit 10
pnpm run search query --text "EAS build cannot find an imported file" \
  --error "None of these files exist" --ecosystem expo --include-review
pnpm run search indexes print

本地 MongoDB 使用精确/容错和加权文本检索，并明确报告语义检索不可用。Atlas 降级搜索/向量搜索是可选的配置。未付费的 Gemini 提供商会直接拒绝私有/团队文档和查询文本。在启用 Atlas 或更改排名/模型配置之前，请阅读 检索指南。

启动所有应用程序和包开发进程：

pnpm dev

当前 Web 前端位于 http://127.0.0.1:3000。API 的存活状态和就绪状态可在 http://127.0.0.1:3001/health/live 和 http://127.0.0.1:3001/health/ready 获取。OpenAPI JSON 位于 http://127.0.0.1:3001/api/v1/openapi.json；Swagger UI 开发版位于 http://127.0.0.1:3001/docs/。

经过认证的知识搜索、规范化详情交互、备选方案、评审访问规则以及安全的 curl 示例，均记录在 Knowledge HTTP API 指南 中。普通客户端只能获得公开的已发布记录；评审访问是显式、仅管理员密钥、并可审计的。

完成构建后，可以将 MCP 客户端直接连接到 http://127.0.0.1:3001/mcp，或者使用 KNOWNPATH_API_URL 和 KNOWNPATH_API_KEY 运行轻量级 stdio 桥接器：

pnpm mcp:stdio
pnpm mcp:inspect --transport stdio

工具合约、认证、安全行为以及当前 Codex / Claude Code / Cursor / Gemini CLI 的配置均已记录在 MCP 指南 中。

可移植的 Agent Skill 会引导受支持的编程代理在何时以及如何查看这些 MCP 工具，而不是盲目应用检索到的修复。手动开发安装以及当前的行为合约均已记录在 Agent Skill 指南 中。

在启动每个代理的环境中配置 API 来源和 API 密钥，然后检查或应用 Phase 13 安装器计划：

export KNOWNPATH_API_URL='https://your-knownpath-origin.example'
read -rsp 'KnownPath API key: ' KNOWNPATH_API_KEY && export KNOWNPATH_API_KEY && printf '\n'
pnpm knownpath -- install --dry-run --agent all
pnpm knownpath -- install --agent all
pnpm knownpath -- doctor --agent all

CLI 仅存储对这些变量名称的引用，并且不会在 URL 配置缺失时进行回退。它支持全局或项目作用域下的 Codex CLI、Claude Code、Cursor、Gemini CLI 以及 OpenCode。系统支持运行 npx knownpath install；仓库开发环境可以使用 pnpm knownpath --。具体的更改行为、Windows 设置、备份、冲突处理、更新和卸载行为均记录在 安装器指南 中。

部署 API

根目录中的 render.yaml 为 Fastify 和 MongoDB Atlas 的 API 定义了 Render 云实例。它声明了如何在不复制数据或损坏的情况下部署数据，但不会部署 worker 或管理后台。在配置之前，请轮换任何之前泄露的密钥，然后按照 Render 部署指南 进行 Blueprint 构建、Atlas 网络访问、健康检查和部署后的 API 密钥流程。

停止 MongoDB 且不删除其有名称的开发卷：

pnpm dev:infra:down

仓库命令

Command

Purpose

pnpm install

安装带锁定的工作区依赖

pnpm dev

运行工作区开发任务

pnpm build

构建所有可编译的应用程序和包

pnpm typecheck

在整个工作区运行严格的 TypeScript 验证

pnpm lint

对整个工作区运行 ESLint flat 配置

pnpm format

用 Prettier 格式化受支持的文件

pnpm format:check

验证格式化而不修改文件

pnpm dev:infra

添加所需的本地 MongoDB 容器

pnpm dev:infra:down

停止本地容器并保留其数据卷

pnpm db:init

以幂等方式创建/或同步 MongoDB 集合、验证器和索引

pnpm db:inspect

输出当前集合的验证器和索引

pnpm db:verify

运行并清理仓库层持久化往返测试

pnpm auth:user:create

通过使用时隐藏的密码提示安全地创建用户/管理员

pnpm ingest:github

通过官方 API 收集一个有界的 GitHub 配置源

pnpm ingest:sources

发现或同步配置好的官方文档和发布 feed

pnpm extract

提取或检查有界的公共源码候选经验

pnpm score

验证证据并创建/或检查不可变的候选评估

pnpm canonicalize

对候选进行画像、比较、合并、拆分、重新分配或重建

pnpm run search

投影、嵌入、索引、检查或查询规范化的 KnownPaths

pnpm mcp:stdio

使用 stdio 运行本地 MCP-over-HTTP 桥接器

pnpm mcp:inspect

使用官方 SDK 客户端列出或调用 MCP 工具

pnpm knownpath -- …

从当前源码目录运行多代理安装 CLI

结构

apps/
  api/             Fastify HTTP process
  cli/             Publishable installer CLI and stdio bridge entry point
  mcp-server/      Thin stdio MCP bridge to the authenticated HTTP API
  web/             Next.js application shell
  worker/          Source ingestion and future background processing runtime
packages/
  agent-adapters/  Safe detection/configuration adapters and ownership state
  ai/              Gemini provider, privacy gate, prompts, validation, and extraction lifecycle
  auth/            Sessions, API keys, principals, authorization, and audit
  config/          Typed environment parsing
  database/        MongoDB lifecycle, repositories, validators, and indexes
  domain/          Versioned domain schemas and canonicalization helpers
  canonicalization/ Deterministic blocking, optional embeddings, and canonical projections
  github-ingestion/ GitHub API collection and source normalization
  source-ingestion/ Official documentation/feed discovery and normalization
  verification/    Deterministic evidence verification and immutable seed scoring
  search/          Embeddings, search projections, hybrid retrieval, and explainable ranking
  mcp/             Shared MCP tool contracts, projections, server factory, and HTTP gateway
  typescript-config/ Shared strict compiler configurations
skills/
  knownpath/        Portable Agent Skill instructions and on-demand examples

有关当前边界和交付状态，请参阅 架构指南、数据模型、检索指南、Knowledge API 指南、MCP 指南、Agent Skill 指南、安装器指南、部署指南、决策记录 以及 阶段进度。

License

KnownPath 以 Apache License 2.0 许可证发布。

This server cannot be deployed

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers