Claude、GitHub Copilot、Cline、Cursor、Windsurf、Aider、Continue、Antigravity和Gemini的通用AI上下文工程,采用OpenRouter驱动的智能分析。
](https://www.npmjs.com/package/k0ntext) ](https://www.npmjs.com/package/k0ntext)   ](https://nodejs.org) 
______________________________________________________________________
目录
______________________________________________________________________
快速开始
# Install globally
npm install -g k0ntext
# Initialize your project with intelligent analysis
k0ntext init
# Generate context files for all AI tools
k0ntext generate
# Start the MCP server for AI tools
k0ntext mcp______________________________________________________________________
从零到英雄的工作流程
New Project Setup
# 1. Initialize with intelligent analysis
k0ntext init --intelligent
# 2. Index your codebase
k0ntext index
# 3. Generate context files
k0ntext generate
# 4. Start MCP server (auto-configured)
k0ntext mcpExisting Project Setup
# 1. Check existing context
k0ntext stats
# 2. Index codebase if needed
k0ntext index --docs --code
# 3. Generate missing tool configs
k0ntext generate --force
# 4. Validate everything
k0ntext validate --strict______________________________________________________________________
Windows支持
K0ntext使用原生SQLite扩展进行高性能向量搜索。
对于Windows用户:
- 推荐: 使用带有预构建二进制文件的Node.js LTS(v18、v20、v22)
- 即时安装: 这些版本的安装不需要额外的工具
- 非LTS版本(v23/v24): 可能需要 Visual Studio 生成工具 编译数据库驱动程序
______________________________________________________________________
🚀 Features Overview
交互式REPL外壳
- 自动启动:跑步
k0ntext无参数启动交互式shell - 会话持续:跨会话保存的命令历史记录和统计信息
- 内置命令:帮助、统计、索引、搜索、配置、漂移、初始化、更新、退出
- 橙色渐变主题 具有Unicode/ASCII回退和终端功能检测
- 更新检查器 启动时自动发出版本通知
增强型TUI面板
- 高级搜索面板 --筛选、可排序的搜索
--type,--sort,--limit标志和内容预览 - 配置UI --交互式编辑器,分为4类(项目、AI工具、功能、显示)
- 索引进度 --使用ora微调器进行实时多阶段进度可视化
- 漂移检测 --具有严重性编码报告的三轴分析(文件日期、结构、git diff)
智能分析
- OpenRouter驱动的嵌入代码库分析
- 技术栈检测和记录
- 工作流发现和分类
- 自动生成上下文
- 集中式模型配置——所有人工智能操作的单一真实来源
语义搜索
- 用于智能代码检索的矢量数据库(sqlite-vec)
- 混合搜索(文本+语义)
- 内容类型过滤(工作流、代理、命令、代码、文档等)
- 手表模式下的实时索引
跨工具同步
- 支持9种AI工具: 克劳德,副驾驶,克莱恩,反重力,风浪,助手,继续,光标,双子座
- 工具配置之间的自动同步
- 使用SHA256哈希进行更改检测
- 同步状态监控
- 智能交叉同步——人工智能驱动的跨工具变化传播
Git钩子自动化
- 预提交工作流程 --自动上下文维护
- 对每次提交进行漂移检测
- 检测到漂移时自动交叉同步
- 已更新的上下文文件已自动添加到提交中
漂移检测
- 基于人工智能的语义分析 --检测文档何时偏离代码
- 用智能理解取代基于哈希的检查
- 基于严重性的报告(高/中/低)
- 自动修复建议
事实核查
- 根据代码库验证文档的准确性
- 识别过时的API、错误的文件路径、缺少依赖项
- 每项索赔的信心评分
基于地图的上下文
- 简洁、结构化的上下文文件
- 通过精确的参考减少幻觉
- 冗长文档格式的替代方案
版本检测
- 自动版本检查 --检测过时的上下文文件
- 语义版本解析 --支持5种版本标记格式
- 更新类型指示器 --主要/次要/带有表情符号的补丁
- 数据库跟踪 --存储版本历史记录并检查时间戳
用户修改处理
- SHA-256哈希检测 --检测用户何时编辑生成的文件
- 自动创建备份 --在覆盖已修改的文件之前创建备份
- 双重备份策略 --使用git stash回退的文件复制
- 交互式提示 --在覆盖自定义更改之前询问用户
模板引擎
- 手柄杆集成 --基于丰富模板的内容生成
- 15名定制助手 --join、first、truncate、slugify、formatDate、eq、ne和、or、defaults、json、键、值、长度
- 丰富的项目数据 --生成的文件包括实际的项目元数据
模板同步系统
- 自动
.claude/同步 --从包同步命令/、代理/、模式/、标准/、工具/、自动化/ - 基于哈希的变化检测 --SHA-256与数据库客户端保持一致
- 文件状态分类 --相同、安全更新、冲突、新建、已删除、仅限用户
- 交互式冲突解决 --显示差异、保持本地、覆盖或跳过选项
- 覆盖前备份 --自动备份到
.k0ntext/backups/
数据库快照
- 创建/恢复/差异快照 --使用gzip压缩进行完整数据库保存/还原
- 快照比较 --比较两个快照,看看发生了什么变化
- 持久待办事项列表 --通过markdown文件保存上下文压缩
MCP服务器
- 自动配置 --MCP服务器在中自动配置
.claude/settings.json在init上 - 10工具: search_context、get_item、add_knowledge、analyze、get_tool_config、query_graph、get_status
- 6提示: 上下文工程师、核心架构师、api开发人员、数据库运维、集成中心、部署运维
- AI助手的实时上下文访问
- 知识图遍历
完整的CLI
init--通过智能分析进行初始化(自动配置MCP)generate--为所有工具生成上下文文件mcp--启动MCP服务器sync--跨AI工具同步cleanup--清理冲突的工具文件夹validate--验证上下文文件export--导出数据库import--从出口进口performance--显示性能指标watch--自动索引文件更改index--索引代码库search--搜索索引内容stats--查看数据库统计信息check--检查上下文文件是否已过时restore--从备份中还原AI工具配置文件sync-templates--同步.claude/来自包的模板template-status--显示模板同步状态drift-detect--人工智能驱动的文档漂移检测cross-sync--跨所有AI工具的智能同步hooks--Git挂钩管理(安装/卸载/状态)fact-check--验证文档的准确性generate --map--生成简洁的基于地图的上下文文件snapshot--创建/还原/列出/差异/删除数据库快照migrate--管理数据库迁移shell--启动交互式REPL shell
智能代理
- 清洁剂 --删除冲突的AI工具文件夹(.cursor、.widsurf、.cline等)
- 性能监视器代理 --跟踪数据库性能并提出优化建议
- DriftAgent 的 --人工智能驱动的文档漂移检测
- FactCheckAgent --根据代码库验证文档的准确性
SQLite存储
- 具有SHA256更改检测的持久数据库
- 语义搜索的嵌入支持
- 知识图关系
- 自动架构迁移
______________________________________________________________________
📦 Releases
v3.8.0版本发布 - 2026-02-11
📦 新功能
- 数据库快照 --使用gzip压缩创建、还原、区分和删除数据库快照
- 持久待办事项列表 --TodoListManager服务,带有在上下文压缩中幸存的markdown文件
- 人工智能驱动的清理 --CleanupAgent支持OpenRouter分析,用于智能文件夹清理
- 时间戳跟踪 --Timestamp Tracker服务,用于精确的文件同步跟踪
- 数据库架构v1.6.0 --用于todo会话、任务、文件时间戳和生成文件的新表
🐛 漏洞修补
- 修复了中的类型保护错误
TimestampTracker和TodoListManager服务 - 固定的导入路径
SnapshotManager在CLI命令中键入 - 添加缺失
description财产SnapshotListEntry接口 - 修复了映射回调的快照命令类型注释
看 更改日志.md 完整的发布历史。
v3.8.1发布 - 2026-02-12
📚 文档更新
- 创建全面
packages.md记录所有包含的组件 - 宣布
MIT License显式地在package.json中 - 在README标题中添加了项目横幅图像
______________________________________________________________________
⚙️ Complete CLI Reference
核心命令
k0ntext init [project-name]
使用智能分析初始化项目的AI上下文。
# Initialize current directory
k0ntext init
# Initialize specific project
k0ntext init my-project
# Skip intelligent analysis (faster)
k0ntext init --no-intelligent选项:
--no-intelligent--跳过OpenRouter供电分析--no-version-check--跳过过时上下文文件的版本检查--no-template-sync--跳过模板同步-v, --verbose--显示详细输出
k0ntext generate
为所有AI工具生成上下文文件。
# Generate for all tools
k0ntext generate
# Generate for specific tools
k0ntext generate -ai claude,copilot,cursor
# Force regenerate all files
k0ntext generate --force
# Verbose output
k0ntext generate -v选项:
-ai, --ai--特定工具(逗号分隔)--force--强制重新生成所有文件--map--使用简洁的基于地图的格式-v, --verbose--显示详细输出
k0ntext mcp
启动模型上下文协议服务器。
# Start with default database
k0ntext mcp
# Specify database path
k0ntext mcp --db .my-context.db选项:
- `--db
` --数据库文件路径
k0ntext sync
跨AI工具同步上下文。
# Sync all tools
k0ntext sync
# Check sync status only
k0ntext sync --check
# Sync from specific tool
k0ntext sync --from claude
# Sync to specific tool
k0ntext sync --to copilot
# Force sync
k0ntext sync --force选项:
--check--仅检查同步状态--from--从特定工具同步--to--同步到特定工具--force--强制同步,即使是最新的
k0ntext cleanup
从其他AI工具中清理上下文文件夹。
# Dry run to see what would be removed
k0ntext cleanup --dry-run
# Keep specific folders
k0ntext cleanup --keep .github,.vscode
# Verbose output
k0ntext cleanup -v选项:
--dry-run--显示要删除的内容--keep--要保留的文件夹(逗号分隔)--ai--使用AI智能分析哪些文件夹可以安全删除-v, --verbose--显示详细输出
k0ntext validate
验证上下文文件和AI工具配置。
# Basic validation
k0ntext validate
# Auto-fix errors
k0ntext validate --fix
# Treat warnings as errors
k0ntext validate --strict选项:
--fix--自动修复验证错误--strict--将警告视为错误
k0ntext export
将上下文数据库导出到文件。
# Export as JSON
k0ntext export context.json
# Export as markdown
k0ntext export docs.md --format markdown
# Export specific type
k0ntext export workflows.json --type workflow选项:
--format--导出格式(json、markdown)--type--按上下文类型筛选
k0ntext import
从导出的文件中导入上下文数据。
# Import JSON export
k0ntext import context.json
# Import and merge with existing data
k0ntext import context.json --merge选项:
--format--导入格式(json、markdown)--merge--与现有数据合并(默认:替换)
k0ntext performance
显示性能指标和优化建议。
# Human-readable report
k0ntext performance
# JSON output
k0ntext performance --json选项:
--json--输出为JSON
k0ntext watch
注意文件更改和自动更新索引。
# Start watching with 1s delay
k0ntext watch
# Custom debounce delay
k0ntext watch -d 2000选项:
-d, --delay--去抖动延迟(毫秒)
k0ntext index
将代码库内容索引到数据库中。
# Index everything
k0ntext index
# Index documentation only
k0ntext index --docs
# Index source code only
k0ntext index --code
# Index AI tool configs only
k0ntext index --tools
# Verbose output
k0ntext index -v选项:
--docs--仅索引文档文件--code--仅索引源代码--tools--仅索引AI工具配置--all--索引所有内容(默认)-v, --verbose--显示详细输出
k0ntext search
在索引内容中搜索。
# Basic search
k0ntext search "authentication"
# Search specific type
k0ntext search "user login" -t workflow
# Text-only search
k0ntext search "API endpoint" -m text
# Semantic search (requires OPENROUTER_API_KEY)
k0ntext search "data persistence" -m semantic
# Limit results
k0ntext search "database" -l 5选项:
-t, --type--按类型筛选-l, --limit--最大结果(默认值:10)-m, --mode--搜索模式:文本、语义、混合
k0ntext stats
显示数据库和索引统计信息。
# View all statistics
k0ntext stats上下文管理命令
k0ntext check
检查上下文文件是否已过时。
# Check all context files
k0ntext check
# Check with detailed output
k0ntext check -v
# Prompt to update outdated files
k0ntext check --update
# Force update without prompts
k0ntext check --update --force选项:
--update--提示更新过时的文件--force--无提示更新-v, --verbose--显示详细输出
k0ntext restore
从备份中还原AI工具配置文件。
# List available backups
k0ntext restore --list
# Interactive restore mode
k0ntext restore
# Restore from specific backup
k0ntext restore --backup "AI_CONTEXT.md.2026-02-09T14.30.45.123Z.bak"
# Restore for specific tool
k0ntext restore --tool claude --list选项:
--list--列出可用备份- `--backup
` --从特定备份路径还原
--tool--按工具名称筛选--force--无需确认即可恢复
k0ntext sync-templates
同步 .claude/ 来自包的模板 templates/base/.
# Sync all templates
k0ntext sync-templates
# Dry run to see what would change
k0ntext sync-templates --dry-run
# Sync specific subdirectories
k0ntext sync-templates --subdirs commands,agents
# Force overwrite all conflicts
k0ntext sync-templates --force选项:
--dry-run--显示更改而不应用--force--自动覆盖冲突而不提示--subdirs--要同步的逗号分隔的子目录-v, --verbose--显示包括差异在内的详细输出--no-archive--跳过存档已删除的文件
k0ntext template-status
显示模板同步状态。
# Check sync status
k0ntext template-status
# Detailed status with file listings
k0ntext template-status --verbosek0ntext snapshot
管理数据库快照。
# Create a snapshot
k0ntext snapshot
# Restore from snapshot
k0ntext snapshot restore
# List all snapshots
k0ntext snapshots
# Diff two snapshots
k0ntext snap-diffAI分析命令
k0ntext drift-detect
使用语义分析进行AI驱动的文档漂移检测。
# Detect drift in all context files
k0ntext drift-detect
# Detect drift in specific paths
k0ntext drift-detect -p CLAUDE.md,.cursorrules
# Strict mode (fails on any drift)
k0ntext drift-detect --strict选项:
--fix--自动修复检测到的漂移(实验)--strict--检测到任何漂移失败- `-p, --paths
` --要检查的逗号分隔路径
--max-files--要检查的最大文件数(默认值:50)-v, --verbose--显示详细输出
k0ntext cross-sync
漂移检测后,在所有AI工具之间智能同步上下文。
# Sync all affected files
k0ntext cross-sync
# Dry run to see what would be synced
k0ntext cross-sync --dry-run
# Sync to specific tools only
k0ntext cross-sync --to claude,cursor选项:
--dry-run--显示在不进行更改的情况下将同步的内容--from--仅从特定工具同步--to--仅同步到特定工具(逗号分隔)--affected--受影响文件的逗号分隔列表-v, --verbose--显示详细的同步输出
k0ntext hooks
管理git挂钩以实现自动上下文同步。
# Install git hooks
k0ntext hooks install
# Uninstall git hooks
k0ntext hooks uninstall
# Check hooks status
k0ntext hooks status子命令:
install--安装预提交钩子以实现自动工作流uninstall--移除已安装的挂钩status--显示挂钩安装状态
k0ntext fact-check [files...]
使用AI分析验证文档的准确性。
# Check all documentation files
k0ntext fact-check
# Check specific files
k0ntext fact-check CLAUDE.md .cursorrules选项:
--fix--自动修复检测到的问题(实验性)-v, --verbose--显示详细输出--min-confidence--报告的最小置信度(0-1,默认值:0.5)
Git挂钩工作流
当你安装钩子时 k0ntext hooks install,预提交钩子自动执行:
- 自动同步 --从真相来源同步上下文
- 验证 --检查上下文错误
- 漂移检测 --AI驱动的漂移检测
- 交叉同步 --如果发现偏差,更新所有AI工具上下文
- 自动添加 --在提交中包含更新的上下文文件
暂时跳过挂钩:
K0NTEXT_SKIP_HOOKS=1 git commit -m "message"
# or
git commit --no-verify -m "message"______________________________________________________________________
🔌 MCP Server Usage
自动配置
当你奔跑时 k0ntext init,MCP服务器是 自动配置 在 .claude/settings.json:
{
"mcpServers": {
"k0ntext": {
"command": "npx",
"args": ["k0ntext", "mcp"],
"env": {
"K0NTEXT_PROJECT_ROOT": "${projectFolder}"
}
}
}
}不再需要手动设置! MCP服务器在初始化后立即工作。
启动服务器
# Start MCP server (auto-configured)
k0ntext mcp可用的MCP工具
- 搜索文本 --跨所有索引内容的语义搜索
- 获取项目 --通过ID或路径获取特定上下文项
- 添加知识 --存储新的见解或事实
- 分析 --在代码库上运行智能分析
- get_tool_config --获取AI工具配置
- 查询图 --遍历知识图
- get_stats --获取数据库统计信息
可用提示
- 上下文工程师 --初始化和配置AI上下文系统
- 核心架构师 --设计系统架构
- api开发人员 --开发API端点
- 数据库操作 --数据库操作
- 集成中心 --外部集成
- 部署操作 --CI/CD和部署
MCP工具使用示例
// Search for authentication workflows
const results = await search_context({
query: "user authentication flow",
type: "workflow",
limit: 5
});
// Get a specific item
const item = await get_item({
id: "workflow:user-auth"
});
// Add new knowledge
await add_knowledge({
name: "API Rate Limiting",
content: "Our API uses token bucket algorithm with 1000 req/min",
relatedTo: ["api:main-endpoint"]
});______________________________________________________________________
支持的AI工具
全力支持
- 克劳德 --AI_CONEXT.md
- GitHub Copilot --.github/copilot-instructions.md
- 光标 -- .cursorrules
- 帆板运动 --风帆/规则.md
- 克莱恩 --.微规则
- 帮助 --.aider.conf.yml
- 继续 --.scontinue/config.json
- 反重力 --.agent/README.md
- 双子座 --.ggemini/config.md
RPI工作流程技能
- @上下文工程师 --设置和配置
- @核心架构师 --系统设计
- @api开发人员 --API开发
- @数据库操作 --数据库操作
- @集成中心 --外部集成
- @部署操作 --CI/CD和部署
______________________________________________________________________
配置
环境变量
| 变量 | 描述 | 必填 |
|---|---|---|
OPENROUTER_API_KEY | 通过OpenRouter进行智能分析的API密钥 | 用于 --intelligent 旗帜 |
K0NTEXT_PROJECT_ROOT | 覆盖项目根路径 | 可选 |
K0NTEXT_DB_PATH | 覆盖数据库文件路径 | 可选 |
数据库位置
默认情况下,k0ntext将其SQLite数据库存储在 .k0ntext.db 在项目根中。此文件会自动添加到 .gitignore.
工具配置路径
每个AI工具都有自己的配置文件路径:
- 克劳德:
AI_CONTEXT.md - 副驾驶:
.github/copilot-instructions.md - 光标:
.cursorrules - 风浪:
.windsurf/rules.md - 克莱恩:
.clinerules - 助手:
.aider.conf.yml - 继续:
.continue/config.json - 反重力:
.agent/README.md - 双子座:
.gemini/config.md
______________________________________________________________________
🏗️ Architecture
系统组件
k0ntext/
├── src/ # TypeScript source
│ ├── agent-system/ # TodoListManager, TimestampTracker
│ ├── agents/ # Smart agents (Cleanup, Performance, Drift, FactCheck)
│ ├── analyzer/ # Intelligent codebase analysis
│ ├── cli/ # CLI commands, REPL shell, utilities
│ │ ├── version/ # Version detection system
│ │ ├── commands/ # Command implementations
│ │ └── utils/ # File detector, backup manager
│ ├── config/ # Centralized model configuration
│ ├── db/ # SQLite database client + migrations
│ ├── embeddings/ # OpenRouter integration
│ ├── services/ # SnapshotManager and services
│ ├── template-engine/ # Handlebars template system
│ ├── template-sync/ # Template synchronization
│ ├── utils/ # Utilities (chunking, encoding)
│ └── mcp.ts # MCP server implementation
├── agents/ # Agent definitions
├── skills/ # RPI workflow skills
├── templates/ # Output templates
│ ├── base/ # Templates synced to user .claude/ directories
│ └── map/ # Map-based context templates
└── .k0ntext.db # SQLite database (auto-created)数据流
- 初始化 --
k0ntext init发现并分析代码库 - 索引 --
k0ntext index使用嵌入将内容存储在SQLite中 - 生成 --
k0ntext generate创建特定于工具的上下文文件 - 同步 --
k0ntext sync保持所有AI工具同步 - MCP服务器 --
k0ntext mcp为AI助手提供实时上下文
数据库模式
SQLite数据库包含:
- 上下文项目 --工作流、代理、命令、代码、文档
- 嵌入 --语义搜索的向量嵌入
- 关系 --知识图连接
- 同步状态 --更改同步跟踪(带版本跟踪)
- 工具配置 --AI工具配置
- 生成的文件 --使用哈希和备份进行文件跟踪
- Todo会话/任务 --持续任务管理
- 文件时间戳 --同步跟踪时间戳
- 快照 --数据库快照元数据
______________________________________________________________________
💻 Development
构建和测试
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Run tests once (no watch)
npm run test:run
# Lint code
npm run lint出版
# Dry run
npm run publish:dry
# Publish to npm
npm run publish:public贡献
- 克隆该仓库
- 创建要素分支
- 进行更改
- 运行测试和梳理
- 提交拉取请求
看 贡献.md 详细指南。
项目结构
src/cli/--命令实现src/db/--数据库操作src/analyzer/--代码分析逻辑src/agents/--智能代理templates/--上下文模板.claude/--Claude代码开发环境
______________________________________________________________________
性能监控
PerformanceMonitorAgent提供以下见解:
- 查询执行次数
- 数据库大小和增长
- 查询检测速度慢
- 优化建议
# View performance report
k0ntext performance
# Get JSON metrics
k0ntext performance --json______________________________________________________________________
🔧 Troubleshooting
常见问题
- SQLite原生扩展问题(Windows)
# Use Node.js LTS version
node --version- 找不到OpenRouter API密钥
# Set the environment variable
export OPENROUTER_API_KEY=your_api_key_here- 数据库锁
# Close other instances of k0ntext
# Or wait a few seconds- 权限错误
# Check file permissions
ls -la .k0ntext.db调试模式
# Verbose output for most commands
k0ntext init -v
k0ntext index -v
k0ntext generate -v看 docs/TROUBLESHOOTING.md 获取完整的故障排除指南。
______________________________________________________________________
文档
______________________________________________________________________
社区
______________________________________________________________________
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
存储库: https://github.com/SireJeff/k0ntext npm包: https://www.npmjs.com/package/k0ntext 问题: https://github.com/SireJeff/k0ntext/issues MCP协议: https://modelcontextprotocol.io
精心制作 杰夫爵士
