Mini-Kode

你是否好奇：像 GitHub Copilot 或 Cursor 这样的 AI 编程助手，底层是如何工作的？

现有的开源项目要么过于庞大（数万行、依赖复杂），要么过于简略（仅演示单点功能），难以作为学习范本。

Mini-Kode 是一个教育优先的 AI 编程助手实现，仅用 14,000 行生产级 TypeScript 代码，完整复现了现代编程智能体的核心架构，同时保持代码清晰、注释充分、易于调试。

为什么值得开发者关注？

教育导向的清晰架构

• 基于 OpenAI SDK 构建，接口设计规范
• 全面使用 TypeScript 类型系统 与 Zod 运行时校验，减少隐式错误
• 每个模块配有详细注释，适合逐行阅读与理解

完整的工具系统

• 提供统一的工具调用接口，支持：
  • 文件读写与编辑
  • 本地命令执行（如 git、npm）
  • 代码搜索与上下文提取
• 支持 MCP（Model Context Protocol），可连接外部工具服务器扩展能力

多模型兼容

• 原生支持 OpenAI API
• 已验证兼容 DeepSeek、GLM（智谱 AI）等主流国产/开源模型
• 通过环境变量灵活切换模型与 API 端点

真实的交互体验

• 智能体循环：完整实现 LLM 规划 → 工具调用 → 人工审批 → 执行 → 反馈
• 流式响应：支持实时输出，模拟真实 AI 助手体验
• 终端 UI：基于 React + Ink 构建，支持主题切换，无需浏览器即可交互

项目上下文感知

• 自动读取项目根目录下的 AGENTS.md 文件
• 你可在此文件中描述项目结构、技术栈或特殊约定
• AI 助手将基于此上下文提供更精准的建议，实现轻量级“项目记忆”

快速上手：5 分钟运行你的第一个 AI 助手

# 全局安装
npm install -g mini-kode

# 设置 API 密钥（以 DeepSeek 为例）
export DEEPSEEK_API_KEY="your-key"

# 启动交互式终端 UI
mini-kode

# 或直接执行命令
mini-kode "帮我修复 auth.ts 中的登录 bug"

无需复杂配置，即可体验一个可读、可改、可部署的 AI 编程助手。

开发者友好：从学习到贡献

• 技术栈现代：TypeScript + pnpm + Bun + Vitest
• 开发体验流畅：

  pnpm install      # 安装依赖
  pnpm run dev      # 启动开发模式（带热重载）
  pnpm run test     # 运行单元测试
  

• 文档齐全：
  • docs/README.md 提供完整架构图与设计说明
  • 专用 《Mini-Kode 深度分析》 文档详解代码组织与设计模式

未来方向：不止于教学

项目团队已规划多项增强功能：

• 会话持久化与恢复
• 子智能体委派（分层任务分解）
• 图像输入支持（多模态调试）
• 推理优化模型集成
• 工具调用流式输出

这些特性将使 Mini-Kode 从“教学模型”逐步演进为可实际集成的轻量级智能体框架。