Maki配置入门:init.lua核心设置与AGENTS.md项目教学完整指南

原创2026-10-14 13:04:191,325 阅读

Maki配置入门:init.lua核心设置与AGENTS.md项目教学完整指南

Maki 是一款高效的 AI 编程助手(AI coding agent),支持用类 neovim 的 Lua 插件扩展。它的配置体系有两个核心入口:init.lua 配置文件(控制主题、模型、工具行为)与 AGENTS.md 项目教学文件(告诉 AI 你代码库的规矩)。本文带你 10 分钟完成 Maki 配置入门,写出属于自己的第一份 init.lua 和 AGENTS.md。

Maki AI编程助手官方横幅:一只趴在寿司上的小猫,标语 the efficient coder

🔧 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 只写了几件事:

  1. 代码规范:命名、错误处理、依赖约定
  2. 测试方法:just check → just lint → just test,从快到慢
  3. 架构概览:每个核心 crate 一句话说明

全是简短的规则式陈述,没有长篇大论——这就是 AGENTS.md 的正确写法:放编码约定、构建命令、禁改区域,保持短小。

还有三个配套文件,各司其职:

文件 位置 用途
AGENTS.local.md 项目同目录 个人偏好,加入 gitignore
~/.config/maki/AGENTS.md 全局 跨所有项目生效的偏好
子目录 AGENTS.md 代码旁 惰性加载:agent 首次触碰该目录才载入,monorepo 神器

冲突时目录越近优先级越高。

Maki AI编程助手在终端中运行:左侧是工具调用与命令输出,右侧展示正在生成的复古游戏画面

🧠 该放哪:四种知识载体的选择

AGENTS.md 不是唯一放知识的地方,Maki 提供四档,成本各不相同:

方式 加载时机 平时成本 适合
AGENTS.md 每个会话 每次请求 短规则:约定、构建命令、禁区
Skills agent 选用时 一行描述 长流程手册:发版、插件开发
Memory agent 回忆时 一行标签名 干活中学到的坑
Commands 输入 /name 时 零成本 反复输入的提示词

黄金法则:当 AGENTS.md 超过一屏,新内容多半该进 Skills——AGENTS.md 是每次请求都要交的“税”,Skills 只在需要时付费。

⚠️ 配置避坑三则

  1. 重复调用 maki.setup()——一个 init.lua 里只能调一次,分节写而不是分次调
  2. 字段名拼错——Maki 会当场校验并指出字段名,按报错修正即可,不会静默忽略
  3. AGENTS.md 写成文档——每次请求都计费,长内容拆成 Skills 或 Memory

延伸阅读

登录后查看全文
maki