Mini-Kode
一个约 14K 行的教学型 AI 编码 Agent CLI,帮你看懂并改造现代编码智能体架构。
- Star 数
- ★ 305
- 最近更新
- 18 天前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 43/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API
- 费用
- 软件免费,模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 想学习编码 Agent 内部机制、希望有一份可通读并改造的 TypeScript 代码库的开发者
- 不适合
- 需要稳定生产级编码助手的团队,本项目定位是教学示例
- 需要图像输入或子代理等尚未实现功能的用户
- 维护状态
- 近 30 天有提交最近提交 2026-11-03
这个 Agent 能做什么,适合哪些场景?
Mini-Kode 是一个以教学为目的的开源 AI 编码助手命令行工具,用 TypeScript 编写,代码量约 14K 行,填补了大型开源项目与玩具示例之间的空白。它基于 OpenAI SDK 实现完整的 Agent 循环,支持流式响应与人在回路(human-in-the-loop)的权限审批,并通过 React/Ink 构建终端界面。工具系统提供文件操作、搜索与命令执行的统一接口,并可连接外部 MCP 服务器扩展能力。模型层兼容 OpenAI API,已验证的支持包括 DeepSeek、GLM(智谱AI)和 MiniMax。项目会自动读取项目根目录的 AGENTS.md 作为持久化项目记忆。它面向希望理解并动手修改编码智能体内部机制的开发者,而非追求生产级稳定性的团队。
运行 mini-kode 后,CLI 通过 Commander 解析参数,在交互模式下启动 Ink/React 终端 UI,在非交互模式下直接执行单条指令。核心 agent 模块组织 LLM 调用循环:将系统提示、AGENTS.md 中的项目上下文和对话历史发给 OpenAI 兼容接口,以流式方式接收回复;当模型请求调用工具时,由 src/tools 中的工具(文件读写、搜索、命令执行)执行,并通过 src/permissions 的两层权限系统请求用户批准后才会落地。LLM 客户端位于 src/llm,配置由 src/config 管理,会话由 src/sessions 维护。项目还可接入外部 MCP 服务器以调用额外工具,最终结果与操作过程都呈现在终端界面中。
- 想学习编码 Agent 内部机制、希望有一份可通读并改造的 TypeScript 代码库的开发者
- 在课程、工作坊或内部分享中需要一个结构清晰、带注释的 Agent 教学示例的技术讲师
- 希望用 DeepSeek、GLM 或 MiniMax 等国内可访问模型的 API 密钥,在终端里完成改 bug、搜索代码等日常编码任务的个人开发者
- 需要把 Agent 接入自有 OpenAI 兼容网关、并自行控制 base URL 与模型名的团队
- 希望通过 MCP 服务器为编码助手补充外部工具能力的工程师
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
npm install -g mini-kode
- 环境变量
DEEPSEEK_API_KEYGLM_API_KEYMINIMAX_API_KEYMINIMAX_REGIONMINIMAX_MODELMINIKODE_API_KEY
如何安装或部署这个 Agent?
通过 npm 全局安装:
npm install -g mini-kode然后设置至少一个模型提供方的 API 密钥,例如 DeepSeek 或 GLM:
export DEEPSEEK_API_KEY="your-deepseek-api-key"export GLM_API_KEY="your-glm-api-key"也可使用 MiniMax:
export MINIMAX_API_KEY="your-minimax-api-key"
export MINIMAX_REGION="cn"
export MINIMAX_MODEL="MiniMax-M3"或任意 OpenAI 兼容服务:
export MINIKODE_API_KEY="your-api-key"
export MINIKODE_BASE_URL="https://your-api-provider.com/v1"
export MINIKODE_MODEL="your-model-name"如何使用这个 Agent?
在项目根目录启动交互式界面:
mini-kode或以非交互模式直接下达一条指令:
mini-kode "help me fix the bug in auth.ts"如需让助手了解项目背景,在项目根目录维护一个 AGENTS.md;如需从源码开发,需先安装 Bun 与 pnpm:
pnpm install
pnpm run dev这个 Agent 有哪些优点和局限?
- 代码量约 14K 行,规模适中,适合完整通读并二次改造,官方还提供了 DeepWiki 深度分析
- 内置统一工具接口,覆盖文件操作、搜索与命令执行,并可通过 MCP 服务器扩展
- 模型层基于 OpenAI SDK,已验证 DeepSeek、GLM、MiniMax,并支持自定义 base URL 与模型名,避免单一厂商锁定
- 提供人在回路的两层权限系统,工具执行前可人工审批
- 采用 React/Ink 构建现代终端界面并支持主题,同时支持交互与非交互两种使用方式
- 自我定位为教学项目,未声明生产级稳定性或安全审计证据
- 路线图中会话持久化、图像输入、子代理、推理模型支持、上下文缓存等能力尚未实现
- 开发流程依赖 Bun 与 pnpm 两套工具链,与普通 Node 项目不同
- 需要自备第三方模型 API 密钥并按量付费,无法开箱即用
- README 未说明支持的操作系统范围,非交互模式与 MCP 集成的具体配置细节也未展开
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Mini-Kode 当前 | 43 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 305 | 18 天前 | TypeScript | OpenAI API |
| smelt | 50 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 73 | 2 天前 | Rust | ChatGPT · Claude Code · OpenAI API · Claude API |
| rpi:Rust 编码代理运行时 | 71 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 287 | 今天 | Rust | OpenAI API · Claude API |
| Aster | 70 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 139 | 20 天前 | Rust | OpenAI API |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
docs/permission.md 描述了多层审批模型(default/autoEdit/yolo)、路径绝对化与 path.resolve 归一化、bash 黑名单(curl/wget/nc 等)与反引号禁用,属于最小权限与用户确认的实质设计,故 least_privilege 与 user_confirmation 给 2。但 yolo 模式可一键自动批准全部 FS 与 bash 操作,且文档未说明该模式的显著风险提示,扣分。data_flow_transparency 仅说明 API key 不入配置文件、用环境变量,未说明对话/文件内容会发送给第三方 LLM 端点,故仅 1。sensitive_data_handling 有环境变量与 ${ENV_VAR} 解析机制,但 MCP 配置示例直接 npx -y 拉取 latest 包,未做完整性校验,给 2。dependency_security 依赖全部为 ^ 浮动版本、无 lockfile 证据、无审计脚本,仅 1。external_effects 涉及 bash 执行与 MCP 外部服务器,但无沙箱/网络出口限制说明,仅 1。rollback 完全缺失:无撤销、无 diff 回滚、无会话恢复(README 将 session persistence 列为未来计划),给 0。source_attribution 在 README References 中明确列出灵感来源与参考项目,给 2。
self_consistency 存在明显矛盾:docs/permission.md 称项目策略存于 .mini-kode/config.json,docs/config.md 称存于 .mini-kode/permissions.json,且 grants 字段一处用 path/command、一处用 pattern;README 称两层权限而 permission.md 称三层,故仅 1。dependency_availability 依赖版本均为 caret 范围且无锁文件证据,构建依赖 Bun 而运行要求 Node>=20,工具链混用增加可得性风险,给 1。failure_messages 文档提到被禁命令有清晰错误信息,但 MCP 初始化失败仅 console.error 后标记已初始化并静默继续,错误处理偏弱,给 1。
audience_and_scenarios 明确面向教育/学习现代 coding agent 架构,场景清晰,给 2。capability_boundaries 通过工具系统、权限类型、banned commands 与未来计划列表界定了能力边界,给 2。trigger_precision 对何时触发审批有流程描述,但 bash 采用黑名单而非白名单,前缀匹配 npm:* 等易被参数绕过,触发精度不足,给 1。environment_fit 要求 Node>=20 且开发需 Bun+pnpm,多 LLM 端点与区域切换有一定适配,但无 Windows/平台说明,给 1。
information_architecture 有 README、docs 目录(permission/config 等)、AGENTS.md/CLAUDE.md 开发指南,结构清晰,给 2。install_notes 提供 npm 全局安装、API key 环境变量、开发前置条件与命令,较完整,给 2。naming_stability 处于 0.2.x 早期版本,配置路径与字段在文档间不一致,命名稳定性不足,给 1。examples_and_faq 有安装与配置示例,但无 FAQ、无故障排查,给 1。known_limitations 仅以 Future Plans 间接暗示缺失功能,未系统列出已知限制与风险,给 1。license 有完整 MIT LICENSE 且 package.json 一致,给 3。versioning_changelog 有版本号但无 CHANGELOG,发布流程为手动改版本,给 1。maintenance_responsibility 发布者为未验证身份,仅有个人邮箱与仓库链接,无治理/维护承诺说明,给 1。
output_usability 有交互与非交互两种模式、流式输出与 Ink UI,但缺少输出格式/结果示例,给 1。marginal_value 定位为教育项目,与成熟 coding agent 相比增量价值主要在可读架构,实际生产力价值有限,给 1。cost_benefit 无 token 成本控制、上下文缓存列为未来计划,成本收益证据不足,给 1。
claim_traceability README 声称 14K 行生产代码、DeepSeek/GLM 已测试验证,但包内无对应证据支撑,给 1。cross_source_corroboration README、AGENTS.md、CLAUDE.md 与 docs 在权限层数与配置路径上互相矛盾,交叉印证不足,给 1。fact_inference_separation 文档混合事实与愿景(Future Plans 与现状并列),未清晰区分已实现与计划,给 1。
- 源码中未见:回滚或恢复路径运行前先备份,或在 git 分支、快照上操作,确保改动可以撤销。
- yolo 模式会无提示地自动批准全部文件写入与 bash 命令,使用前务必确认风险并避免在敏感目录启用。
- bash 权限采用黑名单而非白名单,npm:* 等前缀授权可能被参数绕过,命令校验并非强隔离。
- 文档在权限层数(两层/三层)与项目权限文件路径(config.json vs permissions.json)上自相矛盾,配置行为需以源码为准。
- MCP 示例使用 npx -y 拉取 @latest 包,存在供应链与版本漂移风险,建议固定版本并审阅服务器来源。
- 缺少回滚/撤销与会话恢复能力,破坏性操作后难以恢复。
- 发布者身份未经 FollowAgents 验证,维护责任与更新路径不明确。
常见问题
使用 Mini-Kode 需要付费吗?
工具执行前会不会自动修改我的文件?
我可以用自己的模型网关吗?
它能记住我的项目背景吗?
它支持哪些平台或客户端?
Mini-Kode 开源吗?
Mini-Kode 安全吗?
Mini-Kode 还在维护吗?
Mini-Kode 是谁开发的?
谢谢反馈,我们会据此改进页面。