99

Neovim 应得的 AI 客户端，由那些依然热爱编码的人打造。

如果你是从 YouTube 视频 来的

很多事情都发生了变化。所以请务必小心！

警告 :: 当前 API 正在变化

API 可能会消失或被更改。抱歉，这是一款 BETA 产品。

项目方向

这个仓库旨在成为我探索将 AI 与传统编程结合使用的试验场。

我相信手工编码仍然非常重要，而当今我所知的最佳产品依然坚持这一点（参见 opencode 与 claude code）。

警告

1. 提示目前是临时的，未来可以大幅改进。
2. 正式处于 Beta 阶段，但 API 仍可能发生变化。不过现在不太可能了。

99

AI 的 Neovim 使用体验

_99

99 是一种代理式工作流，旨在将当前程序员的能力与大型语言模型的强大功能相结合。它并不是要取代程序员，而是用来增强程序员的工作。

目前，99 的发展方向是推进代理式编程和信息的呈现。最初以及最初的 YouTube 视频中提到的是用 AI 替换特定的代码片段。然而，随着我对 99 的使用越来越深入，我逐渐意识到它更好的用途在于“搜索”和“工作”。

基本设置

	{
		"ThePrimeagen/99",
		config = function()
			local _99 = require("99")

            -- 用于日志记录，如果希望追踪请求以报告 bug，建议不要依赖此方式，而是使用 99 内置的日志机制。此配置主要用于调试目的。
            local cwd = vim.uv.cwd()
            local basename = vim.fs.basename(cwd)
			_99.setup({
                -- provider = _99.Providers.ClaudeCodeProvider,  -- 默认：OpenCodeProvider
				logger = {
					level = _99.DEBUG,
					path = "/tmp/" .. basename .. ".99.debug",
					print_on_error = true,
				},
                -- 当设置为非当前工作目录的路径时，例如 claude code 或 opencode，可能会出现权限问题，导致生成失败。请参考相关工具的文档来解决：
                -- https://opencode.ai/docs/permissions/#external-directories
                -- https://code.claude.com/docs/en/permissions#read-and-edit
                tmp_dir = "./tmp",

                --- 补全功能：提示缓冲区中的 #rules 和 @files
                completion = {
                    -- 我暂时禁用这些功能，直到更好地理解问题所在。光标规则中还包含应用规则，这意味着需要以不同的方式应用它们。
                    -- cursor_rules = "<自定义光标规则路径>"

                    --- 包含您自己的 SKILL.md 文件的文件夹列表
                    --- 预期格式：
                    --- /path/to/dir/<skill_name>/SKILL.md
                    ---
                    --- 示例：
                    --- 输入路径：
                    --- "scratch/custom_rules/"
                    ---
                    --- 输出规则：
                    --- {path = "scratch/custom_rules/vim/SKILL.md", name = "vim"},
                    --- ... 该目录下的其他规则 ...
                    ---
                    custom_rules = {
                      "scratch/custom_rules/",
                    },

                    --- 配置 @file 补全（所有字段可选，有合理默认值）
                    files = {
                        -- enabled = true,
                        -- max_file_size = 102400,     -- 字节，跳过大于此大小的文件
                        -- max_files = 5000,            -- 总发现文件数上限
                        -- exclude = { ".env", ".env.*", "node_modules", ".git", ... },
                    },
                    --- 文件发现：
                    --- - 在 Git 仓库中：使用 `git ls-files`，自动尊重 .gitignore 文件。
                    --- - 非 Git 仓库：回退到文件系统扫描，并手动排除指定文件。
                    --- - 两种方法都会在 .gitignore 的基础上应用配置的 `exclude` 列表。

                    --- 使用哪种自动补全引擎。未指定时，默认使用原生（内置）引擎。
                    source = "native", -- "native"（默认）、"cmp" 或 "blink"
                },

                --- 警告：如果更改当前工作目录，此功能很可能失效
                --- 我可能会在后续更新中修复这个问题。
                ---
                --- md_files 是一个文件列表，系统会根据原始请求的位置自动查找并添加这些文件。也就是说，如果你位于 /foo/bar/baz.lua，
                --- 系统会自动查找：
                --- /foo/bar/AGENT.md
                --- /foo/AGENT.md
                --- 假设 /foo 是项目根目录（基于当前工作目录）。
				md_files = {
					"AGENT.md",
				},
			})

            -- 请注意，我在视觉模式下才进行操作
            -- 实际上，无论你上次选择的是什么内容，都会被使用
            -- 因此我将其设置为视觉模式，以免误用之前的视觉选择。
            --
            -- 未来可能会增加模式检查，并断言必须处于视觉模式
            -- 所以现在就做好准备吧。
			vim.keymap.set("v", "<leader>9v", function()
				_99.visual()
			end)

            --- 如果你有一个请求不想再继续，可以直接取消它。
			vim.keymap.set("n", "<leader>9x", function()
				_99.stop_all_requests()
			end)

			vim.keymap.set("n", "<leader>9s", function()
				_99.search()
			end)
		end,
	},

使用方法

我强烈推荐尝试 search 功能，因为这是该库的发展方向。

_99.search()

更多详情请参阅搜索部分。

描述

名称	类型	默认值
setup	fun(opts?: _99.Options): nil	-
search	fun(opts: _99.ops.SearchOpts): _99.TraceID	-
vibe	fun(opts?: _99.ops.Opts): _99.TraceID | nil	-
open	fun(): nil	-
visual	fun(opts: _99.ops.Opts): _99.TraceID	-
view_logs	fun(): nil	-
stop_all_requests	fun(): nil	-
clear_previous_requests	fun(): nil	-
Extensions	_99.Extensions	-

API

setup

设置 _99。必须调用此函数，库才能正常工作。通过它我们可以设置正在进行的请求加载动画、设定默认值，并使补全功能按你期望的方式运行。

search

根据你提供的提示，在你的项目中执行搜索，并返回一个包含注释的位置列表，这些位置将被添加到快速修复列表中。

vibe

无描述。

open

打开一个选择窗口，供你选择最近的一次交互进行打开，并以适合其类型的方式显示内容。对于 search 和 vibe，会打开 qfix 窗口；对于 tutorial，则会打开教程窗口。

visual

获取当前选中的内容并连同提供的提示一起发送，然后用结果替换当前的视觉选区。

view_logs

查看最近的日志，并配置机器以便查看更早和更新的日志。目前这部分还比较粗糙，未来会有较大改动。

stop_all_requests

停止所有正在进行的请求。这意味着底层进程（OpenCode）会被终止，任何已产生的结果都将被丢弃。

clear_previous_requests

清除所有之前的搜索和视觉操作记录。

扩展

请查看 Worker，它为 search 和 vibe 提供了很酷的抽象层。

_99.Extensions.Worker

一种持久化的工单跟踪方式。

这很可能是未来开发的重点方向。我希望将其扩展到工作树的范畴，从而能够非常流畅地在不同任务之间切换。

在此之前，它只是一个简单的工单系统：你可以提供任务描述，然后使用 search 来查找尚未完成的工作。

描述

名称	类型	默认值
set_work	fun(opts?: _99.WorkOpts): nil	-
search	fun(): nil	-

API

set_work

为项目设置工单。如果 opts 中提供了描述，则无需再次输入工单描述。

search

将使用 _99.search 来查找该工单中尚未完成的部分，直到工单被视为已完成。

_99.Options

无描述。

描述

名称	类型	默认值
logger	_99.Logger.Options | nil	-
model	string | nil	-
in_flight_options	_99.InFlight.Opts | nil	-
md_files	string[] | nil	-
provider	_99.Providers.BaseProvider | nil	-
display_errors	boolean | nil	-
auto_add_skills	boolean | nil	-
completion	_99.Completion | nil	-
tmp_dir	string | nil	-

API

logger

无描述。

model

无描述。

in_flight_options

无描述。

md_files

无描述。

provider

无描述。

display_errors

无描述。

auto_add_skills

无描述。

completion

无描述。

tmp_dir

无描述。

_99.ops.Opts

这些选项用于与 99 进行的所有交互，包括 search、visual 等操作。

描述

名称	类型	默认值
additional_prompt	string | nil	-
additional_rules	_99.Agents.Rule[] | nil	-

API

additional_prompt

通过提供 additional_prompt，你就不需要再单独提供提示。这样可以根据 remap 定义不同的操作。

remap("n", "<leader>9d", function()
  --- 这个函数可以用来自动调试你的项目
  _99.search({
    additional_prompt = [[
运行 `make test` 并调试测试失败的原因，然后向我提供一套完整的步骤，说明测试在哪里出错 ]]
  })
end)

这段代码会启动一个后台搜索任务，运行你的测试。一旦发现失败，就会进行诊断，并将结果转移到快速修复列表中。

additional_rules

可用于提供额外的参数。如果你有一个名为 “cloudflare” 的技能，就可以提供相应的规则，这些规则及其上下文将被注入到你的请求中。

_99.ops.SearchOpts

更多信息请参阅 _99.opts.Opts。

目前还没有具体属性。但我希望可以根据 opts 调整一些行为。

描述

名称	类型	默认值
-	-	-

API

无属性。

_99.WorkOpts

无描述。

描述

名称	类型	默认值
description	string | nil	-

API

description

无描述。

_99.Completion

无描述。

描述

名称	类型	默认值
source	"cmp" | "blink" | nil	-
custom_rules	string[]	-
files	_99.Files.Config?	-

API

source

无描述。

custom_rules

无描述。

files

无描述。

_99.InFlight.Opts

这是一个纯粹用于测试的类，有助于控制时间间隔。

描述

名称	类型	默认值
throbber_opts	_99.Throbber.Opts | nil	-
in_flight_interval	number | nil	-
enable	boolean | nil	-

API

throbber_opts

左上角加载动画的相关选项。

in_flight_interval

控制加载动画显示或隐藏的频率。

enable

默认为 true。

_99.Logger.Options

无描述。

描述

名称	类型	默认值
level	number?	-
type	"print" | "void" | "file" | nil	-
path	string?	-
print_on_error	boolean | nil	-
max_requests_cached	number | nil	-

API

level

无描述。

type

无描述。

path

无描述。

print_on_error

无描述。

max_requests_cached

无描述。

_99.Agents.Rule

无描述。

描述

名称	类型	默认值
name	string	-
path	string	-
absolute_path	string?	-

API

name

无描述。

path

无描述。

absolute_path

无描述。

补全功能

在输入提示时，你可以引用规则和文件来为你的请求增加上下文。

• # 引用规则 — 在提示中输入 # 可以从你配置的规则目录中自动补全规则文件。
• @ 引用文件 — 输入 @ 可以模糊搜索项目文件，但会排除 .gitignore 中列出的文件。

引用的内容会自动解析并注入到 AI 上下文中。默认情况下使用原生补全功能。如果使用 nvim-cmp 或 blink.cmp，则需设置 source = "cmp" 或 source = "blink"。

提供者

99 支持多种 AI CLI 后端。在你的配置中设置 provider 即可切换。如果你没有设置 model，则会使用提供者的默认模型。

提供者	CLI 工具	默认模型
OpenCodeProvider（默认）	opencode	opencode/claude-sonnet-4-5
ClaudeCodeProvider	claude	claude-sonnet-4-5
CursorAgentProvider	cursor-agent	sonnet-4.5
GeminiCLIProvider	gemini	auto

_99.setup({
    provider = _99.Providers.ClaudeCodeProvider,
    -- model 是可选的，会覆盖提供者的默认值
    model = "claude-sonnet-4-5",
})

扩展

Telescope 模型选择器

如果你安装了 telescope.nvim，可以通过 Telescope 选择器实时切换模型：

vim.keymap.set("n", "<leader>9m", function()
  require("99.extensions.telescope").select_model()
end)

所选模型将用于当前会话中的所有后续请求。

Telescope 提供者选择器

无需重启 Neovim 即可在 OpenCode、Claude、Cursor 和 Kiro 之间切换提供者。切换提供者时，模型也会重置为该提供者的默认值。

vim.keymap.set("n", "<leader>9p", function()
  require("99.extensions.telescope").select_provider()
end)

fzf-lua

如果你使用 fzf-lua 而不是 telescope，同样可以使用这些选择器：

vim.keymap.set("n", "<leader>9m", function()
  require("99.extensions.fzf_lua").select_model()
end)

vim.keymap.set("n", "<leader>9p", function()
  require("99.extensions.fzf_lua").select_provider()
end)

报告 bug

要报告 bug，请提供完整的运行调试日志。这可能需要多次沟通确认。

请勿提出功能需求。我们将在 Twitch 上公开讨论功能需求，这将比你单独提交大量请求后再被关闭要高效得多。如果你仍然提交功能请求，我将会立即关闭它。

日志

要查看上次运行的日志，请执行 :lua require("99").view_logs()。

请注意

如果日志中包含敏感信息或其他需要删除的内容，请务必删除 query 的打印部分。这部分内容很可能包含你不希望公开的信息。

99 Neovim AI 助手快速上手指南

99 是一款专为 Neovim 打造的 AI 客户端插件，旨在通过代理工作流（Agentic Workflow）增强开发者的编码能力，而非替代手写代码。它深度集成了搜索（Search）和视觉选择处理（Visual）功能，帮助开发者更高效地利用大语言模型。

注意：本项目目前处于 Beta 阶段，API 可能会发生变化。

环境准备

在开始之前，请确保满足以下要求：

• Neovim: 建议使用最新稳定版（v0.10+），需支持 vim.uv 和 vim.fs。
• AI 后端依赖: 99 本身是客户端，需要本地或远程运行支持的 AI 工具作为后端。目前主要支持：
  • OpenCode (默认)
  • Claude Code
  • 请根据官方文档安装并配置好相应的后端工具，确保其在终端中可正常运行。
• Git: 部分文件发现功能依赖 Git。

安装步骤

推荐使用 lazy.nvim 进行安装和管理。

1. 在你的 Neovim 插件配置文件中（例如 lua/plugins/99.lua），添加以下配置：

{
    "ThePrimeagen/99",
    config = function()
        local _99 = require("99")

        -- 获取当前项目目录名称用于日志命名
        local cwd = vim.uv.cwd()
        local basename = vim.fs.basename(cwd)

        _99.setup({
            -- 可选：指定 provider，默认为 OpenCodeProvider
            -- provider = _99.Providers.ClaudeCodeProvider,

            -- 日志配置（调试用）
            logger = {
                level = _99.DEBUG,
                path = "/tmp/" .. basename .. ".99.debug",
                print_on_error = true,
            },

            -- 临时目录配置
            -- 注意：如果设置为 CWD 外部目录，OpenCode/Claude Code 可能会有权限问题
            tmp_dir = "./tmp",

            -- 自动加载的上下文文件（如 AGENT.md）
            md_files = {
                "AGENT.md",
            },

            -- 补全功能配置
            completion = {
                -- 自定义技能规则路径 (SKILL.md)
                custom_rules = {
                  "scratch/custom_rules/",
                },
                -- 补全引擎来源: "native" (默认), "cmp", 或 "blink"
                source = "native",
                
                -- 文件补全配置
                files = {
                    enabled = true,
                    max_file_size = 102400, -- 跳过大于此字节数的文件
                    exclude = { ".env", ".env.*", "node_modules", ".git" },
                },
            },
        })

        -- 键位映射
        
        -- 可视模式下选中代码进行处理 (<leader>9v)
        vim.keymap.set("v", "<leader>9v", function()
            _99.visual()
        end)

        -- 普通模式下停止所有正在进行的请求 (<leader>9x)
        vim.keymap.set("n", "<leader>9x", function()
            _99.stop_all_requests()
        end)

        -- 普通模式下启动项目搜索 (<leader>9s) - 推荐核心功能
        vim.keymap.set("n", "<leader>9s", function()
            _99.search()
        end)
    end,
},

2. 保存配置并重启 Neovim，或执行 :Lazy sync 安装插件。
3. 确保你的项目中已正确安装并初始化了后端的 AI 工具（如 opencode 或 claude-code）。

基本使用

99 的核心设计理念是通过 搜索 (Search) 来驱动开发工作流。

1. 项目智能搜索 (search)

这是最推荐的使用方式。它会基于你的提示词在整个项目中进行搜索、分析，并将结果（包含文件位置和修改建议）输出到快速修复列表（Quickfix List）中。

• 操作: 在普通模式下按下 <leader>9s。
• 流程:
  1. 输入你的自然语言提示（例如：“查找所有未处理的错误”或“重构用户认证模块”）。
  2. 99 调用后端 AI 分析项目。
  3. 结果展示在 Quickfix 窗口，你可以直接跳转查看。

高级用法（预设提示词）: 你可以在按键映射中预设提示词，实现一键自动化任务：

vim.keymap.set("n", "<leader>9d", function()
  _99.search({
    additional_prompt = [[
run `make test` and debug the test failures and provide me a comprehensive set of steps where
the tests are breaking ]]
  })
end)

2. 可视区域代码处理 (visual)

对选中的代码块进行重构、解释或修改。

• 操作:
  1. 进入可视模式 (v, V, 或 Ctrl+v) 选中代码。
  2. 按下 <leader>9v。
  3. 输入指令（例如：“添加注释”或“优化性能”）。
  4. AI 生成的代码将直接替换选中的内容。

3. 查看历史与日志

• 打开最近交互: 使用 _99.open() 查看最近的搜索结果或教程窗口。
• 查看日志: 使用 _99.view_logs() 调试插件运行状态。
• 停止任务: 如果任务运行时间过长，按 <leader>9x 强制停止所有后台进程。

4. 工作流管理 (Worker)

99 提供了简单的任务追踪功能，可以设定一个工作目标，然后让 AI 搜索还需要完成哪些内容。

-- 设置当前工作任务描述
_99.Extensions.Worker.set_work({ description = "完成用户登录功能的 API 集成" })

-- 搜索该项目中还剩下什么没做
_99.Extensions.Worker.search()