KnownPath

KnownPath ist ein quelloffenes gemeinsames Wissensnetzwerk für KI-Codierungsagenten. Sein langfristiger Zweck ist es, zu verhindern, dass Agenten wiederholt dieselben technischen Lösungen neu entdecken, indem verifizierte, wiederverwendbare Ingenieurerfahrungen über agenten-native Schnittstellen verfügbar gemacht werden.

[!IMPORTANT] KnownPath befindet sich in aktiver phasenweiser Entwicklung. Phase 13 ergänzt die portable Installer-CLI und sichere Adapter für fünf Coding-Agenten. Werkzeuge für Beiträge/Ergebnisse, Dashboards, öffentliche Registrierung und öffentlicher anonymer Zugriff sind noch nicht implementiert. Die Installer wird als knownpath veröffentlicht.

Voraussetzungen

• Node.js 24 LTS (.nvmrc verfolgt die unterstützte Hauptversion; package.json erzwingt den getesteten Bereich)

• Corepack, enthalten in der unterstützten Node.js-Distribution

• Images: Docker Desktop oder eine andere Docker Engine mit Compose-Unterstützung für lokales MongoDB

Related MCP server: CodeGraph

Installation

corepack enable
pnpm install
cp .env.example .env

Generieren Sie unabhängige Werte für BETTER_AUTH_SECRET und API_KEY_PEPPER wie in .env.example beschrieben. Das eingecheckte Beispiel enthält keine Standard-Anmeldedaten.

Aktuelle Entwicklungsumgebung starten

Start MongoDB:

pnpm dev:infra

Aktuelle Collections, Validatoren und Indizes erstellen beziehungsweise abgleichen:

pnpm db:init

Optionale Persistenzprüfung und Repository-Roundtrip-Validierung:

pnpm db:inspect
pnpm db:verify

Über die maskierte CLI (Registrierung ist geschlossen) den ersten lokalen Benutzer oder Administrator anlegen:

pnpm auth:user:create

Optional können Sie GITHUB_TOKEN in .env setzen, um das normale authentifizierte REST-Limit von 5.000 Anfrufen und den Zugriff auf GitHub Discussions zu erhalten. Danach können Sie eine begrenzte Sammlung vorab anzeigen oder ausführen:

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

Lesen Sie den GitHub-Erfassungsleitfaden, bevor Sie einen Backfill ausführen.

Das aktuelle kuratierte Set offizieller Dokumente entdecken, ohne Quelldatensätze zu schreiben, und anschließend eine begrenzte Quelle oder eine einzelne indizierte Seite synchronisieren:

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

Lesen Sie den Leitfaden zur Erfassung offizieller Quellen, bevor Sie die Kuratierung ändern oder einen begrenzten Gesamtkatalog-Lauf anfordern.

Mit einem Gemini-Entwicklungsschlüssel in der ignorierten .env einen begrenzten Kandidaten aus öffentlichen Quellen verarbeiten oder untersuchen:

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

Der nicht bezahlte Gemini-Pfad lehnt private/Team-Quelldatensätze ab, bevor irgendein Provider-Aufruf erfolgt. Lesen Sie den KI-Extraktionsleitfaden, bevor Sie den Schlüssel konfigurieren oder einen Batch erweitern.

Extrahierte Kandidaten bewerten, ohne einen KI-Anbieter aufzurufen, und im Anschluss die vollständige Aufschlüsselung/History prüfen:

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

Bewertungen sind erklärbare Ranking-Signale und keine Wahrheitswahrscheinlichkeiten. Lesen Sie den Bewertungsleitfaden, bevor Sie die versionierte Richtlinie ändern.

Non-mutable similarity profiles erstellen, blockierte Paare entdecken, Reviews ansehen und ausschließlich deterministisch sichere kanonische Merges anwenden:

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 werden nur erzeugt, nachdem sowohl die Kandidaten als auch alle referenzierten Quellen als öffentlich verifiziert wurden. Sie unterstützen plausible blockierte Vergleiche, entscheiden aber niemals über einen automatischen Merge. Lesen Sie den Kanonisierungsleitfaden, bevor Sie Merges oder manuelle Operationen anwenden.

Aktuelle kanonische Suchprojektionen erstellen und lokal abfragen. Einträge mit Review-Status sind ausgeschlossen, sofern nicht ausdrücklich angefordert:

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

Lokales MongoDB nutzt exakt/error- und gewichtetetes SucheRetrieval und meldet eindeutig, dass semantisches Retrieval nicht verfügbar ist. Atlas Search/Vector Search ist optionale Konfiguration. Der unbezahlte Gemini-Provider lehnt private/Team-Dokumente und Anfragen strikt ab. Lesen Sie den Retrieval-Leitfaden, bevor Sie Atlas aktivieren oder die Ranking-/Modellkonfiguration ändern.

Starten Sie alle Anwendungs- und Paketentwicklungsprozesse:

pnpm dev

Die aktuelle Web-Shell ist verfügbar unter http://127.0.0.1:3000. API-Liveness und -Readiness sind unter http://127.0.0.1:3001/health/live und http://127.0.0.1:3001/health/ready verfügbar. OpenAPI-JSON liegt unter http://127.0.0.1:3001/api/v1/openapi.json; die Entwickler-Swagger-UI ist unter http://127.0.0.1:3001/docs/ erreichbar.

Authentifizierte Wissenssuche, kanonische Details, Alternativen, Regeln für den Review-Zugriff und sichere curl-Beispiele finden Sie im Knowledge-HTTP-API-Leitfaden. Normale Clients erhalten nur veröffentlichte öffentliche Datensätze; der Review-Zugriff ist explizit, nur über Admin-Schlüssel und wird protokolliert.

Verbinden Sie nach dem Build direkt einen MCP-Client mit http://127.0.0.1:3001/mcp oder führen Sie die schlanke Stdio-Bridge mit KNOWNPATH_API_URL und KNOWNPATH_API_KEY aus:

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

Tool-Verträge, Authentifizierung, Sicherheitsverhalten und aktuelle Co-Code/Claude Code/Cursor/Gemini-CLI-Konfigurationen sind im MCP-Leitfaden dokumentiert.

Die portierbare Agent-Skill bringt unterstützenden Coding-Agenten bei, wann und wie sie die MCP erfern-Tools einsetzen, ohne heruntergeladene Fixes blind anzuwenden. Die manuelle Entwicklungsinstallation und der aktuellen Verhaltensvertrag sind im Agent-Skill-Leitfaden beschrieben.

Konfigurieren Sie die API-Origin und den API-Schlüssel in der Umgebung, die jeden Agenten starten, und prüfen Sie dann oder wenden Sie den Installationsplan für Phase 13 an:

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

Die CLI speichert nur Verweise auf diese Variablennamen und hat keinen URL-Fallback. Sie unterstützt Codex CLI, Claude Code, Cursor, Gemini CLI und OpenCode auf globaler oder Projektebene. Benutzer können npx knownpath install ausführen; die Repository-Entwicklung kann pnpm knownpath -- verwenden. Genaue Schritte, Windows-Einrichtung, Backups, Konflikte, Upgrades und Deinstallationsverhalten sind im Installer-Leitfaden eingeführt.

Bereitstellung der API

Das render.yaml im Wurzelverzeichnis definiert einen einzelnen Render-Webdienst für die Fastify-API-API und bleibenden MongoDB Atlas als Datenbank. Es deployed absichtlich weder den Worker, noch das Dashboard noch stesso einen anderen Datenspeicher. Drehen Sie zuvor aufgedeckshöhe Anmeldedaten vor dem Setup, und folgen Sie dann der Render-Bereitstellung leitfaden für das Blueprint, Netzwerkzugriffe für Atlas, Health-Verification und den Schritte zum API-Key nach der Bereitstellung.

Stoppen Sie MongoDB, ohne das benannte Entwicklungs-Volume löschen:

pnpm dev:infra:down

Repository-Befehle

| Befehl | Zweck | | ----------------------- | -------------------------------------------- --- | | pnpm install | Die festgelegten Workspace-Abhängigkeiten installieren | | pnpm dev | Workspace-Entwicklungsaufgaben ausführen | | pnpm build | Alle kompilierbaren Anwendungen und Pakete bauen | | pnpm typecheck | Strikte TypeScript-Pruefung über den Workspace ausführen | | pnpm lint | ESLint Flat-Konfiguration über den Workspace ausführen | | pnpm format | Unterstützte Dateien mit Prettier formatieren | | pnpm format:check | Format Validieren, ohne Dateien zu ändern | | pnpm dev:infra | Starten den erforderlichen lokalen MongoDB-Container | | pnpm dev:infra:down | Stoppen den lokalen Container und Datenvolume beibehalten | | pnpm db:init | Collections, Validatoren und Indizes in Mongo idempotent erstellen/abgleichen | | pnpm db:inspect | Aktuelle Collection-Validatoren und -Indizes auswählen | | pnpm db:verify | Ein PersistenzRoundtrip der Repsitory-Ebene ausführen und bereinigen | | pnpm auth:user:create | Benutzer/Admin sicher mit maskierter Passwortabfrage bereitstellen | | pnpm ingest:github | Eine begrenzte, konfigurierte GitHub-Quelle über offizielle APIs erfassen | | pnpm ingest:sources | Konfigurierte offizielle Dokumentation und ReleaseFeed discover/syncen | | pnpm extract | Kandidaten aus begrenzten öffentlichen Quellen extrahieren oder ansehen | | pnpm score | Proof of Evidence prüfen und unveränderliche Assessments erstellen/ansehen | | pnpm canonicalize | Kandidaten profileieren, vergleichen, Review, mergen, splitten, neu zuweisen oder rebuilden | | pnpm run search | Kanonische KnownPaths projizieren, einbetten, indexieren, "invalid" inspectieren oder quaest | | pnpm mcp:stdio | Schlanke lokale MCP-HTTP-Brücke über stdio ausführen | | pnpm mcp:inspect | MCP-Tools mit officiellen SDK-Client auflisten oder aufrufen | | pnpm knownpath -- … | Multi-Agent-Installer-CLI aus diesem Checkout ausführen |

Struktur

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

Siehe und die Architektur-Anleitung, Datenmodell, Retrieval-Anleitung, Knowledge-HTTP-API-Anleitung, MCP-Leitfaden, Agent-Skill-Anleitung, Installer-Anleitung, Deployment-Anleitung, Entscheidungsprotokoll und Fortschritt für die aktuellen Abgrenzungen und Bereitstellungn.

Lizenz

KnownPath ist unter der Apache License 2.0 lizenziert.