KnownPath

KnownPath — это открытая общая сеть знаний для ИИ-агентов, пишущих код. Её долгосрочная цель — избавить агентов от необходимости многократно заново открывать одни и те же технические решения, предоставляя проверенный и переиспользуемый инженерный опыт через интерфейсы, ориентированные на агентов.

[!IMPORTANT] KnownPath находится в активной поэтапной разработке. Фаза 13 добавляет портативный CLI-установщик и безопасные адаптеры для пяти агентов кодирования. Инструменты для вклада и результатов, дашборды, публичная регистрация и публичный анонимный доступ ещё не реализованы. Установщик опубликован как knownpath.

Предварительные требования

• Node.js 24 LTS (.nvmrc отслеживает поддерживаемую мажорную версию; package.json закрепляет протестированный диапазон)

• Corepack, включённый в поддерживаемый дистрибутив Node.js

• Docker Desktop или другой Docker Engine с поддержкой Compose для локальной MongoDB

Related MCP server: CodeGraph

Установка

corepack enable
pnpm install
cp .env.example .env

Сгенерируйте независимые значения BETTER_AUTH_SECRET и API_KEY_PEPPER так, как описано в .env.example. Зафиксированный в репозитории пример не содержит учётных данных по умолчанию.

Запуск текущей среды разработки

Запустите MongoDB:

pnpm dev:infra

Создайте или приведите в соответствие текущие коллекции, валидаторы и индексы:

pnpm db:init

Необязательная проверка постоянного хранения и сквозная проверка репозитория:

pnpm db:inspect
pnpm db:verify

Создайте первого локального пользователя или администратора через CLI с маскированием пароля (регистрация закрыта):

pnpm auth:user:create

При желании установите GITHUB_TOKEN в .env для обычного аутентифицированного лимита REST в 5 000 запросов и доступа к 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

Перед изменением курирования или запросом ограниченного прогона полного каталога см. руководство по загрузке официальных источников.

С ключом Gemini для разработки в игнорируемом .env обработайте или проверьте ограниченного кандидата из публичного источника:

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

Бесплатный путь Gemini жёстко отклоняет записи источников private/team до любого вызова провайдера. Прочтите руководство по извлечению с помощью ИИ перед настройкой ключа или расширением пакета.

Проверьте извлечённых кандидатов без вызова ИИ-провайдера, затем просмотрите полную разбивку/историю:

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 создаются только после того, как и кандидаты, и все связанные источники проверены как публичные. Они поддерживают правдоподобные сравнения заблокированных пар, но никогда не принимают решение об автоматическом слиянии. Прочтите руководство по канонизации перед применением слияний или ручных операций.

Сформируйте текущие канонические проекции для поиска и выполняйте локальные запросы. Записи в состоянии ревью исключаются, если явно не запрошены:

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 Search/Vector Search — необязательная конфигурация. Бесплатный Gemini-провайдер жёстко отклоняет документы и текст запросов private/team. Прочтите руководство по поиску перед включением Atlas или изменением конфигурации ранжирования/моделей.

Запустите все процессы разработки приложений и пакетов:

pnpm dev

Текущая веб-оболочка доступна по адресу http://127.0.0.1:3000. Liveness и readiness эндпоинты 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. Обычные клиенты получают только публичные опубликованные записи; доступ к ревью является явным, только по admin-ключу и аудируется.

После сборки подключите MCP-клиент напрямую к http://127.0.0.1:3001/mcp или запустите тонкий stdio-мост с KNOWNPATH_API_URL и KNOWNPATH_API_KEY:

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

Контракты инструментов, аутентификация, поведение в области безопасности и текущие конфигурации Codex/Claude Code/Cursor/Gemini CLI описаны в руководстве по MCP.

Портативный Agent Skill учит поддерживаемых агентов, когда и как обращаться к MCP-инструментам, не применяя слепо найденные исправления. Ручная установка для разработки и текущий контракт поведения описаны в руководстве по Agent Skill.

Настройте origin API и ключ API в среде, которая запускает каждого агента, затем проверьте или примените план установщика Фазы 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 определяет один веб-сервис Render для Fastify API и использует MongoDB Atlas в качестве базы данных. Он намеренно не развёртывает worker, дашборд или другое хранилище данных. Перед настройкой смените ранее раскрытые учётные данные, затем следуйте руководству по развёртыванию Render для Blueprint, сетевого доступа Atlas, проверки состояния и потока API-ключей после развёртывания.

Остановите MongoDB, не удаляя его именованный том для разработки:

pnpm dev:infra:down

Команды репозитория

Структура

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

О текущих границах и статусе поставки см. руководство по архитектуре, модель данных, руководство по поиску, руководство по HTTP API для знаний, руководство по MCP, руководство по Agent Skill, руководство по установщику, руководство по развёртыванию, журнал решений и прогресс по фазам.

Лицензия

KnownPath распространяется под лицензией Apache License 2.0.