Maki配置入门:init.lua核心设置与AGENTS.md项目教学完整指南
Maki配置入门:init.lua核心设置与AGENTS.md项目教学完整指南
Maki 是一款高效的 AI 编程助手(AI coding agent),支持用类 neovim 的 Lua 插件扩展。它的配置体系有两个核心入口:init.lua 配置文件(控制主题、模型、工具行为)与 AGENTS.md 项目教学文件(告诉 AI 你代码库的规矩)。本文带你 10 分钟完成 Maki 配置入门,写出属于自己的第一份 init.lua 和 AGENTS.md。
🔧 init.lua 文件位置:两个配置入口一览
Maki 的配置全部写在一个调用 maki.setup() 的 Lua 脚本里,有两个可选位置:
| 层级 | 位置 | 作用范围 |
|---|---|---|
| 全局 | ~/.config/maki/init.lua |
所有项目 |
| 项目 | 仓库根目录 .maki/init.lua |
仅当前项目 |
两者同时存在时,项目配置覆盖全局配置;两个都不写,Maki 用全部默认值也能开箱即用。
⚠️ 项目的 .maki/init.lua 可以执行代码,因此 Maki 在首次加载前会做一次文件夹信任(Folder Trust)确认,详见文件夹信任文档。
🎯 maki.setup() 核心配置示例:一份直接能用
下面是一份覆盖最常用设置的示例,所有字段均可选:
maki.setup({
ui = {
theme = "tokyonight", -- 内置主题名
splash_animation = true,
mouse_scroll_lines = 5,
},
agent = {
max_output_lines = 3000, -- 模型可见的工具输出行数上限
},
provider = {
default_model = "anthropic/claude-sonnet-4-6",
allowed_models = { "anthropic/*" }, -- 模型白名单(glob)
},
storage = {
max_log_files = 5,
},
plugins = {
bash = { timeout_secs = 180 }, -- 按插件传选项
},
})
只需记住一条硬规则:maki.setup() 每个 init.lua 只能调用一次。
⚡ init.lua 常用配置项速查
界面与主题(ui)
theme:30+ 内置主题可选(tokyonight、gruvbox、catppuccin_mocha等);往配置目录的themes/放一个<name>.toml即可自定义inline_images:终端支持时内联渲染图片mouse_scroll_lines、max_input_lines:滚动与输入区体验微调
Agent 行为(agent)
| 字段 | 默认值 | 作用 |
|---|---|---|
max_output_lines |
2000 | 模型可见工具输出最大行数 |
max_output_bytes |
51200 | 工具输出最大字节数 |
compaction_buffer |
20% | 上下文窗口接近上限时预留的自动压缩空间 |
模型与网络(provider)
default_model:默认模型;不设置则沿用你上次使用的模型allowed_models/excluded_models:glob 白名单与黑名单,黑名单永远优先max_retries:限流重试上限,默认 5 次
插件开关(plugins)
内置插件默认全部开启,enabled = false 即关闭。例如 plugins.websearch = { enabled = false } 关闭联网搜索,plugins.task = { max_concurrent = 8 } 限制并发子代理数。
完整字段与默认值见 Configuration 完整参考。
📚 AGENTS.md 项目教学文件:怎么写
AGENTS.md 是 Maki 的“项目教学手册”:会话开始时从 git 根目录到工作目录自动加载,内容注入系统提示词。Maki 优先识别 AGENTS.md,也兼容 CLAUDE.md、.cursorrules 等流行格式,每个目录取第一个匹配的文件。
Maki 项目自己就是一份优秀范例,它的 AGENTS.md 只写了几件事:
- 代码规范:命名、错误处理、依赖约定
- 测试方法:
just check→just lint→just test,从快到慢 - 架构概览:每个核心 crate 一句话说明
全是简短的规则式陈述,没有长篇大论——这就是 AGENTS.md 的正确写法:放编码约定、构建命令、禁改区域,保持短小。
还有三个配套文件,各司其职:
| 文件 | 位置 | 用途 |
|---|---|---|
AGENTS.local.md |
项目同目录 | 个人偏好,加入 gitignore |
~/.config/maki/AGENTS.md |
全局 | 跨所有项目生效的偏好 |
子目录 AGENTS.md |
代码旁 | 惰性加载:agent 首次触碰该目录才载入,monorepo 神器 |
冲突时目录越近优先级越高。
🧠 该放哪:四种知识载体的选择
AGENTS.md 不是唯一放知识的地方,Maki 提供四档,成本各不相同:
| 方式 | 加载时机 | 平时成本 | 适合 |
|---|---|---|---|
AGENTS.md |
每个会话 | 每次请求 | 短规则:约定、构建命令、禁区 |
| Skills | agent 选用时 | 一行描述 | 长流程手册:发版、插件开发 |
| Memory | agent 回忆时 | 一行标签名 | 干活中学到的坑 |
| Commands | 输入 /name 时 |
零成本 | 反复输入的提示词 |
黄金法则:当 AGENTS.md 超过一屏,新内容多半该进 Skills——AGENTS.md 是每次请求都要交的“税”,Skills 只在需要时付费。
⚠️ 配置避坑三则
- 重复调用
maki.setup()——一个 init.lua 里只能调一次,分节写而不是分次调 - 字段名拼错——Maki 会当场校验并指出字段名,按报错修正即可,不会静默忽略
- AGENTS.md 写成文档——每次请求都计费,长内容拆成 Skills 或 Memory
延伸阅读
- Quick Start:安装、连接模型、跑通第一次会话
- Configuration 完整参考:所有 init.lua 字段、默认值与目录布局
- Context 指令文件加载规则:AGENTS.md 加载顺序与
@文件引用 - Writing maki plugins:用 Lua 写自己的插件与斜杠命令

