使用说明

飞泰

英语 | 韩语

管理AI代理的知识——解析、存储、查询和协作。

KGN是一个开发人员友好的CLI+MCP服务器，适用于使用AI代理构建的团队。在简单的YAML+Markdown文件中编写知识节点(.kgn)，定义关系他们之间(.kge)，并让KGN处理存储、相似性搜索、冲突检测和多代理任务切换——所有这些都由PostgreSQL+pgvector支持。

混合架构： PostgreSQL是本地工作引擎；GitHub是长期的真理来源。导出、提交和推入一个命令。

建筑

要深入了解KGN的内部设计——层结构、模块依赖关系、数据库模式、数据流等——请参阅完整 架构指南 16张交互式美人鱼图。

graph LR
    A[".kgn / .kge"] --> B["Parser"]
    B --> C["IngestService"]
    C --> D[("PostgreSQL<br/>+ pgvector")]
    D --> E["CLI · MCP · LSP · Web"]
    E --> F["Git / GitHub Sync"]

为什么选择KGN？

人工智能代理功能强大，但它们在会话之间会忘记一切——当多个代理协作时，它们可能会发生冲突、重复工作或失去对决策的跟踪。

KGN给你的特工一个 共享、可查询内存:

问题	KGN解决方案
代理忘记过去的决定	PostgreSQL中的持久知识图
跨代理的重复工作	冲突检测+相似性搜索
无任务协调	内置具有租约管理的任务队列
难以审核代理操作	每个代理的结构化活动日志
上下文窗口溢出	子图提取——只提取相关内容
IDE摩擦 `.kgn` 文件	支持LSP的VS代码扩展名

快速开始

📖 刚到KGN？ 按照以下步骤操作 入门指南 ( 韩语 )--不需要以前的经验。

安装

pip install kgn-mcp

启动数据库

git clone https://github.com/baobab00/kgn.git && cd kgn
docker compose -f docker/docker-compose.yml up -d postgres

首次运行

kgn init --project my-project
kgn ingest examples/ --project my-project --recursive
kgn status --project my-project

Embedding Provider Setup

若要使用嵌入功能，请在 .env 文件：

# .env
KGN_OPENAI_API_KEY=sk-your-api-key-here
KGN_OPENAI_EMBED_MODEL=text-embedding-3-small    # default

如果未设置API密钥，则摄取工作正常，嵌入将被静默跳过（优雅的降级）。

# Test provider connection
kgn embed provider test

Docker All-in-One

将PostgreSQL+kgn CLI与Docker一起运行：

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml exec kgn kgn init --project my-project
docker compose -f docker/docker-compose.yml exec kgn kgn --help

地方 .kgn/.kge 文件位于 docker/workspace/ 目录。

MCP服务器（克劳德集成）

MCP（模型上下文协议）服务器使Claude能够直接读取、写入和管理知识图中的任务。

# stdio mode (Claude Desktop / Claude Code default)
kgn mcp serve --project my-project

# HTTP SSE mode
KGN_MCP_TRANSPORT=sse KGN_MCP_PORT=8000 kgn mcp serve --project my-project

# streamable-http mode
KGN_MCP_TRANSPORT=streamable-http kgn mcp serve --project my-project

Claude桌面集成 --添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "kgn": {
      "command": "uv",
      "args": ["run", "kgn", "mcp", "serve", "--project", "my-project"]
    }
  }
}

MCP Tools (12 tools)

工具	类别	描述
`get_node`	读取	按ID获取节点
`query_nodes`	读取	搜索项目中的节点（类型/状态筛选器）
`get_subgraph`	读取	从节点提取BFS子图
`query_similar`	读取	向量相似度Top-K搜索
`task_checkout`	任务	查看优先级最高的任务（具有自动租约恢复功能）
`task_complete`	任务	将任务标记为已完成（自动解除阻止相关任务）
`task_fail`	任务	将任务标记为失败
`workflow_list`	工作流	列出已注册的工作流模板
`workflow_run`	工作流	执行工作流模板（创建子任务DAG）
`ingest_node`	从.kgn字符串中写入	摄取节点
`ingest_edge`	写	从.kge字符串中摄入边缘
`enqueue_task`	写入	Enqueue TASK节点

Git/GitHub Sync

# Export DB → filesystem (+ auto-generate Mermaid README)
kgn sync export --project my-project --target ./sync

# Import filesystem → DB
kgn sync import --project my-project --source ./sync

# Push/pull to GitHub
kgn sync push --project my-project --target ./sync
kgn sync pull --project my-project --target ./sync

# Mermaid visualization
kgn graph mermaid --project my-project
kgn graph readme --project my-project --target ./sync

# Branch/PR management
kgn git branch list --target ./sync
kgn git pr create --project my-project --target ./sync --title "PR title"

Web Dashboard

pip install kgn-mcp[web]
kgn web serve --project my-project --port 8080

打开http://localhost:8080--图形视图、任务板、运行状况仪表板、搜索和筛选。

VS Code Extension

code --install-extension baobab00.vscode-kgn
pip install kgn-mcp[lsp]    # for LSP features

语法高亮显示、诊断、自动补全、悬停、转到定义、CodeLens、子图预览。

Error Code System

所有MCP错误响应均以结构化JSON返回：

{
  "error": "Error message",
  "code": "KGN-300",
  "detail": "Detailed description",
  "recoverable": false
}

代码	类别	描述	可重试
`KGN-100`	基础结构	数据库连接失败	✅
`KGN-101`	基础架构	嵌入提供程序不可用	✅
`KGN-200`	摄取	YAML前体解析错误	❌
`KGN-201`	摄入	必填字段缺失	❌
`KGN-202`	摄取	字段值无效	❌
`KGN-300`	查询	找不到节点	❌
`KGN-301`	查询	UUID格式无效	❌
`KGN-302`	查询	超过子图深度限制	❌
`KGN-400`	任务	没有可用的就绪任务	❌
`KGN-401`	任务	任务未处于预期状态	❌
`KGN-402`	任务	租约已到期	✅
`KGN-999`	内部	意外的服务器错误	✅

多代理编排

KGN支持多代理协作工作流，其中多个AI代理在基于角色的访问控制、任务切换和冲突解决的知识图上协同工作。

5代理角色 --具有基于角色的访问控制的genesis、worker、reviewer、indexer、admin
3个工作流模板 --面向内建、问题解决、知识索引的设计
任务交接 --工作流步骤之间的自动上下文传播
咨询锁定 --防止对同一节点进行并发修改
冲突解决 --检测冲突并自动创建审阅任务
可观测性 --代理活动时间线、任务流统计数据、瓶颈检测

Agent Roles & Workflow Details

角色	创建	签出	描述
起源	目标、规格、架构、约束、假设	--	项目引导
工人	规格、拱形、逻辑、任务、摘要	✅ （角色筛选）	实施工作
审稿人	决定、问题、总结	✅ （角色筛选）	代码审查和决策
索引器	摘要	--	知识索引
管理员	所有类型	✅ （所有任务）	完全访问权限

模板	步骤	说明
`design-to-impl`	目标→ SPEC → ARCH → 任务（示例）→ 任务（审查）	从设计到实施的完整流程
`issue-resolution`	问题→ 任务（修复）→ 任务（验证）	Bug修复工作流程
`knowledge-indexing`	目标→ 任务（索引）→ 任务（回顾）	知识获取管道

kgn agent list --project my-project
kgn agent role --project my-project --agent-id <uuid> --role worker
kgn agent stats --project my-project --agent-id <uuid>
kgn agent timeline --project my-project --agent-id <uuid>

CLI命令

跑 kgn --help 查看完整的命令列表。

关键命令摘要：

组	示例	描述
核心	`kgn init`, `kgn ingest`, `kgn status`, `kgn health`	初始化、摄取、状态、健康
查询	`kgn query nodes`, `kgn query subgraph`, `kgn query similar`	搜索、子图、相似性
任务	`kgn task enqueue/checkout/complete/fail/list/log`	任务编排
嵌入	`kgn embed`, `kgn embed provider test`	嵌入管理
冲突	`kgn conflict scan/approve/dismiss`	冲突检测/管理
同步	`kgn sync export/import/status/push/pull`	DB↔ 文件↔ GitHub同步
Git	`kgn git init/status/diff/log/branch/pr`	Git/GitHub管理
图	`kgn graph mermaid/readme`	美人鱼可视化
主控程序	`kgn mcp serve`	MCP服务器（stdio/sse/可流式传输http）
代理	`kgn agent list/role/stats/timeline`	多代理编排
网络	`kgn web serve`	Web可视化仪表板
语言服务器协议	`kgn lsp serve`	语言服务器（VS代码集成）

Expired Task Recovery

当已签出的任务超过其 lease_expires_at，它被认为 过期的. requeue_expired 重置已过期 IN_PROGRESS 任务到 READY 和增量 attempts.

MCP： checkout 自动呼叫 requeue_expired 事先
CLI： 需要手动调用或cron计划
当 max_attempts 超过（默认值3），任务将转换为 FAILED

文件格式

.kgn — Knowledge Graph Node

---
kgn_version: "0.1"
id: "new:my-node"        # UUID or new:slug
type: SPEC               # GOAL, ARCH, SPEC, LOGIC, DECISION, ISSUE, TASK, CONSTRAINT, ASSUMPTION, SUMMARY
title: "Node title"
status: ACTIVE            # ACTIVE, DEPRECATED, SUPERSEDED, ARCHIVED
project_id: "my-project"
agent_id: "my-agent"
tags: ["tag1", "tag2"]
confidence: 0.9
---

## Context
...
## Content
...

.kge — Edge Definition

---
kgn_version: "0.1"
project_id: "my-project"
agent_id: "my-agent"
edges:
  - from: "new:node-a"
    to:   "new:node-b"
    type: DEPENDS_ON      # DEPENDS_ON, IMPLEMENTS, RESOLVES, SUPERSEDES, DERIVED_FROM, CONTRADICTS, CONSTRAINED_BY
    note: "Edge description"
---

看 examples/ 实用指南 .kgn 和 .kge 文件示例。

发展

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Test
uv run pytest --tb=short -q

# Coverage
uv run pytest --cov=kgn --cov-report=term-missing

技术栈

层	技术
语言	Python 3.12+
命令行界面	类型 + 富有的
数据库	PostgreSQL 16+ pg向量
ORM/SQL	psycopg3 （本机异步就绪）
验证	Pydantic v2
AI协议	MCP 1.26.0 通过FastMCP
嵌入	OpenAI `text-embedding-3-small` （可选）
Git/GitHub	双向同步（DB\u2194 GitHub）
日志记录	结构日志（JSON/控制台）
网络	FastAPI+Uvicorn+Jinja2+Cytoscape.js（可选额外）
集成开发环境	VS代码扩展+pygls LSP（可选额外）
基础设施	Docker编写+GitHub操作CI
质量	颈毛 +pytest（2081+个测试，93%+覆盖率）

许可证

麻省理工学院

使用说明

飞泰

目录

建筑

为什么选择KGN？

快速开始

安装

启动数据库

首次运行

MCP服务器（克劳德集成）

多代理编排

CLI命令

文件格式

发展

技术栈

许可证

相关 MCP

知识图谱记忆服务器

AI持久记忆服务器

网页抓取与搜索MCP服务器

知识图谱存储服务

百度优选

自主代理操作系统