vcp.nvim 🚀

VCP.nvim 是 VCP (Variable & Command Protocol) 生态的 Neovim 专用接入端。它将高性能 Agent 的认知能力直接注入编辑器，实现代码感知、智能重构、结构化任务执行与多话题协同。

"No Electron. No BS. Just Lua."

---

🛠️ 环境准备

在安装插件前，请确保已配置好 VCP 核心后端：

1. VCPToolBox: 核心工具箱，提供分布式工具调用支持。

   git clone https://github.com/lioensky/VCPToolBox.git

2. VCPChat: 桌面端 GUI 与数据管理中心。

   git clone https://github.com/lioensky/VCPChat.git

   请确保 VCPChat 已启动，并记下其 AppData 所在路径。

---

📦 安装 (Lazy.nvim)

创建 ~/.config/nvim/lua/plugins/vcp.lua：

return {
  {
    "vcp.nvim",
    -- 本地开发调试时指向项目目录
    -- dir = "~/projects/vcp.nvim",
    dependencies = {
      "nvim-lua/plenary.nvim",
      "nvim-telescope/telescope.nvim",
    },
    config = function()
      require("vcp").setup({
        -- 也可以在这里传入配置覆盖 config.env
        -- data_root = "/path/to/your/VCPChat"
      })
    end,
  },
}

---

⚙️ 配置文件 (config.env)

在插件根目录下创建 config.env：

VCP_API_URL=http://127.0.0.1:6005
VCP_KEY=your_vcp_key
VCP_DATA_ROOT=/home/user/path/to/VCPChat

每个 Agent 可在其 nvim-config.json 中独立配置上下文深度：

{
  "systemPrompt": "你是一个高性能的 Neovim 编程助手...",
  "contextDepth": 20
}

contextDepth：发送给模型的最大对话轮数（1 轮 = 1 user + 1 assistant）。本地历史文件始终保留完整记录，截断只影响发给模型的内容。省略则全量发送。

注意：真正的 token 级上下文折叠（如 [nvim-view] 的按需展开）依赖后端实现。 相关 issue 已提交给 VCP 后端开发者，前端目前仅做视觉折叠。

---

🎮 使用指南

1. 载入 Agent 与话题

执行 :VCPAgent 唤起 Telescope 选择器：

位置	按键	功能
话题列表	n	创建新话题
话题列表	x	删除选中话题
话题列表	Enter	进入对话工作区

---

2. 对话工作区快捷键

按键	功能
Enter（输入框）	发送消息
F5	截停当前流式输出，末尾追加 [reroll]
Enter（光标在 [reroll] 行）	重试：移除最后一条 assistant 回复，重新发送
a	应用代码块 / 执行 task-line 勾选的子任务
Space / Enter	切换 task-line 子任务复选框
Tab	折叠 / 展开当前语义块
C-b / Esc	返回话题列表

---

3. 代码联动与智能应用

VCP 自动感知当前编辑器打开的文件，通过 [nvim-view] 协议标记将文件内容折叠注入上下文，Agent 知晓文件存在但默认不展开（视觉折叠）。

• 全量替换：光标移至 [nvim-code:AgentName] 折叠块，按 a，选择 1. Replace entire file。
• 光标处插入：先在编辑器中定位目标行，切回聊天窗口按 a，选择 2. Insert at cursor。

---

4. 流式截停与重试（F5 / reroll）

正在流式输出中...
  ↓ 按 F5
输出立即截停，末尾追加 [reroll]

[reroll]          ← 光标移到这一行，按 Enter
  ↓
移除最后一条 assistant 回复，用相同的 user 消息重新请求

每次 assistant 回复自然结束时，也会自动追加 [reroll]，方便随时重试。

---

5. task-line 结构化任务系统

Agent 可以输出结构化的多步骤任务块，用户选择性执行：

[nvim-task-line:AgentName]
[nvim-subtask:set:AgentName]     [path] /project/src/foo.js  [set] // 新组件...
[nvim-subtask:ci:AgentName]      [docker] node:20-alpine [path] /project [steps] npm install | npm test
[nvim-subtask:migrate:AgentName] [steps] nvm use 20 | fnm install 20 [rollback] nvm use default
[nvim-task-line-end:AgentName]

渲染后显示为带复选框的列表：

[task-line:AgentName]
  [ ] :set     /project/src/foo.js
  [ ] :ci      /project
  [ ] :migrate nvm use 20 | fnm install 20
[task-line-end:AgentName]

操作流程：

1. Space 或 Enter 勾选 / 取消勾选子任务
2. 光标在 task-line 块内，按 a 执行所有已勾选的子任务
3. 执行结果通过 vim.notify 汇报

内置子任务类型

类型	字段	说明
:set	[path] [set]	将内容写入指定文件（自动创建目录）
:ci	[docker] [path] [steps] [cmd] [env]	Docker 容器隔离 CI，返回压缩日志
:migrate	[steps] [cmd] [rollback]	原子化步骤执行，失败自动回滚，支持断点续跑

占位符：:current / :self

Agent 无需硬编码自身名称，插件渲染时自动替换：

[nvim-task-line:current]
[nvim-subtask:set:current] [path] /foo.js [set] content
[nvim-task-line-end:current]

扩展新子任务类型（依赖倒置）

-- vcp-plugins/my_type.lua
local M = {}
function M.setup()
    require("vcp.protocol").register("my_type", function(subtask, ctx)
        -- subtask.path / .cmd / .steps / .env ...
        return "✓ 执行完成"
    end)
end
return M

在 init.lua 的 setup() 中加一行 require("vcp.vcp-plugins.my_type").setup() 即可，无需修改引擎。

---

6. [nvim-read] 按需文件注入

Agent 在回复中可以请求读取指定文件，插件自动将文件内容注入下一轮上下文：

[nvim-read:AgentName] [path] /project/src/config.json

插件检测到该标记后，将文件内容以 [nvim-view] 块格式附加到当次请求的末尾，并通过 vim.notify 提示注入成功。文件不存在或不可读时给出警告。

---

7. [nvim-log] 执行日志捕获

通过 M.capture_log(cmd, callback) API 捕获外部命令输出，自动压缩并注入对话上下文：

-- 在自定义 subtask handler 或快捷键中调用
require("vcp").capture_log("cargo test 2>&1", function(log)
    require("vcp").inject_log_and_send(log)
end)

捕获结果以 [nvim-log:AgentName] 块包裹注入，Agent 可据此分析错误并提出修复方案。

日志压缩规则：过滤空行与进度条，只保留含 error/warning/FAIL/PASS/assert 等关键词的行（最多 15 行），并附上退出码状态。

---

8. VCP 协议标记参考

自然上下文标记（无需 Agent 标识，插件自动注入）

标记	说明
[nvim-path:/abs/path]	当前编辑器打开的文件路径
[nvim-view]...[nvim-view-end]	当前文件内容（视觉折叠，Agent 按需展开）

交互 / 任务标记（必需 Agent 标识）

标记	说明
[nvim-task-line:Agent]	task-line 块开始
[nvim-task-line-end:Agent]	task-line 块结束
[nvim-subtask:TYPE:Agent] ...	单条子任务
[nvim-code:Agent]	代码块（a 键应用到编辑器）
[nvim-read:Agent] [path] /abs/path	请求读取文件并注入上下文
[nvim-log:Agent]...[nvim-log-end:Agent]	执行日志块

---

🔌 分布式节点模式

vcp.nvim 可作为 VCP 分布式工具节点运行，接收主服务器下发的工具调用：

# config.env
VCP_WS_URL=ws://127.0.0.1:6007
SERVER_NAME=my-nvim-node

内置支持 WriteFile、ReadFile、ShellExec、GetCurrentFile 等工具调用，可通过 vcp-plugins/ 扩展。

---

📁 项目结构

lua/vcp/
├── init.lua          # 入口：Agent/话题选择、消息发送、nvim-read/log 处理
├── config.lua        # 配置加载（config.env + setup() 参数）
├── topics.lua        # 话题/历史管理、contextDepth 窗口截断
├── ui.lua            # TUI 渲染：折叠、流式、复选框、F5/reroll
├── protocol.lua      # 纯文本协议解析引擎（依赖倒置核心）
├── websocket.lua     # WebSocket 客户端（分布式节点连接）
├── utils/            # JSON 读写、工具函数
└── vcp-plugins/      # 可插拔工具 handler
    ├── file_ops.lua  # :set subtask + WriteFile/ReadFile WebSocket handler
    ├── ci.lua        # :ci subtask（Docker 隔离 CI）
    ├── migrate.lua   # :migrate subtask（原子化迁移 + 断点续跑）
    └── shell_exec.lua# ShellExec WebSocket handler

---

🗺️ 路线图

• Agent / 话题选择（Telescope）
• SSE 流式对话
• [nvim-view] 文件内容折叠注入（视觉折叠）
• [nvim-code] 代码块应用（替换 / 插入）
• F5 截停 + [reroll] 重试
• [nvim-task-line] / [nvim-subtask] 结构化任务系统（依赖倒置）
• :set 文件写入子任务
• :ci Docker 隔离 CI 子任务
• :migrate 原子化迁移子任务（断点续跑 + 自动回滚）
• :current / :self 占位符替换
• WebSocket 分布式节点（RFC 6455，心跳 + 重连）
• [nvim-read] 按需文件注入
• [nvim-log] 执行日志捕获与压缩注入
• contextDepth 上下文轮次截断（本地历史完整保留）
• 后端协议级上下文折叠（[nvim-view] token 级按需展开，需后端支持）
• Vim help 格式文档
• 演示录屏