飞泰
英语 | 韩语
> 管理AI代理的知识——解析、存储、查询和协作。
KGN是一个开发人员友好的CLI+MCP服务器,适用于使用AI代理构建的团队。
在简单的YAML+Markdown文件中编写知识节点(.kgn),定义关系
他们之间(.kge),并让KGN处理存储、相似性搜索、冲突
检测和多代理任务切换——所有这些都由PostgreSQL+pgvector支持。
混合架构: PostgreSQL是本地工作引擎;GitHub是
长期的真理来源。导出、提交和推入一个命令。
目录
- 建筑
- 为什么选择KGN?
- 快速开始
- MCP服务器(克劳德集成)
- 多代理编排
- CLI命令
- 文件格式
- 发展
- 技术栈
建筑
要深入了解KGN的内部设计——层结构、模块依赖关系、数据库模式、数据流等——请参阅完整 架构指南 16张交互式美人鱼图。```mermaid
graph LR
A[".kgn / .kge"] --> B["Parser"]
B --> C["IngestService"]
C --> D[("PostgreSQL
+ pgvector")]
D --> E["CLI · MCP · LSP · Web"]
E --> F["Git / GitHub Sync"]
______________________________________________________________________
## 为什么选择KGN?
人工智能代理功能强大,但它们在会话之间会忘记一切——当多个代理协作时,它们可能会发生冲突、重复工作或失去对决策的跟踪。
KGN给你的特工一个 **共享、可查询内存**:
|问题|KGN解决方案|
|---|---|
|代理忘记过去的决定| PostgreSQL中的持久知识图|
|跨代理的重复工作|冲突检测+相似性搜索|
|无任务协调|内置具有租约管理的任务队列|
|难以审核代理操作|每个代理的结构化活动日志|
|上下文窗口溢出|子图提取——只提取相关内容|
|IDE摩擦 `.kgn` 文件|支持LSP的VS代码扩展名|
______________________________________________________________________
## 快速开始
> **📖 刚到KGN?** 按照以下步骤操作 **入门指南** ( 韩语 )--不需要以前的经验。
### 安装```bash
pip install kgn-mcp
启动数据库```bash
git clone https://github.com/baobab00/kgn.git && cd kgn
docker compose -f docker/docker-compose.yml up -d postgres
### 首次运行```bash
kgn init --project my-project
kgn ingest examples/ --project my-project --recursive
kgn status --project my-project
Embedding Provider Setup
若要使用嵌入功能,请在 .env 文件:```bash
.env
KGN_OPENAI_API_KEY=sk-your-api-key-here
KGN_OPENAI_EMBED_MODEL=text-embedding-3-small # default
如果未设置API密钥,则摄取工作正常,嵌入将被静默跳过(优雅的降级)。```bash
# Test provider connection
kgn embed provider test
Docker All-in-One
将PostgreSQL+kgn CLI与Docker一起运行:```bash
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能够直接读取、写入和管理知识图中的任务。```bash
# 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:```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```bash
# 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```bash
pip install kgn-mcp[web]
kgn web serve --project my-project --port 8080
打开http://localhost:8080--图形视图、任务板、运行状况仪表板、搜索和筛选。
VS Code Extension```bash
code --install-extension baobab00.vscode-kgn
pip install kgn-mcp[lsp] # for LSP features
语法高亮显示、诊断、自动补全、悬停、转到定义、CodeLens、子图预览。
Error Code System
所有MCP错误响应均以结构化JSON返回:```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` |目标→ 任务(索引)→ 任务(回顾)|知识获取管道|
```bash
kgn agent list --project my-project
kgn agent role --project my-project --agent-id --role worker
kgn agent stats --project my-project --agent-id
kgn agent timeline --project my-project --agent-id
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```yaml
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```yaml
---
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 文件示例。
发展```bash
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%+覆盖率) |
许可证
麻省理工学院
