之前在终端里跑 AI 编码助手时总是被几个问题反复折腾模型生成的代码无法直接信任、网页上下文抓取得不完整、审核修改又缺少直观界面导致“一键生成、手动返工”效率很低。最近看到 VT Code 这个项目方向比较有启发它把 terminal coding agent、WebMCP 和人工审核编辑器结合在了一起。本文就围绕这套思路拆解核心概念、设计流程并实现一个带人工审核环节的最小可运行示例帮助大家理解这类工具的原理和落地方式。1. 背景与核心概念1.1 从 IDE 插件到终端编码代理早期 AI 编程辅助主要依赖 IDE 插件比如在编辑器中选中代码、让模型补全或解释。后来逐渐出现了更“主动”的玩法直接在终端里运行一个编码代理coding agent让它读取项目文件、执行命令、修改代码甚至负责一次完整的重构。这种转变背后的原因并不复杂IDE 插件通常把 AI 能力限制在“代码编辑”这一层无法自由操作终端命令。实际开发中大量操作发生在 shell 里包括构建、测试、Git 操作、依赖安装。终端编码代理可以把“读取上下文 → 生成方案 → 执行命令 → 验证结果”变成闭环更像一个真正的辅助工程师。但也正因为它能直接操作文件系统和执行命令出错的代价也更高。一个未经审核的sed替换可能让整个目录面目全非。这也是 VT Code 把“人工审核编辑器”作为核心设计的原因。1.2 VT Code 是什么VT Code 可以理解为“运行在终端里的编码代理”同时配套一个由人工审核的 WebMCP 编辑器。这里的关键特征有两个终端是主场操作入口、日志输出、命令执行都在终端中完成。Web 端负责审核模型生成的修改计划会渲染成一个可视化页面由开发者确认后再执行。这种“终端执行 Web 审核”的拆分解决了一个很实际的矛盾终端适合高效输入命令但不太适合展示复杂的 diff 和修改原因浏览器则更适合展示结构化内容方便人做判断。1.3 为什么需要 WebMCP 和人工审核编辑MCPModel Context Protocol是一套让 AI 模型获取外部工具和上下文的标准协议可以理解为“模型的 USB 接口”。VT Code 提到的 WebMCP可以理解为面向 Web 场景的 MCP 适配把网页中的结构化内容、工具参数、审核表单等转换成模型和编辑器都能理解的标准上下文。但协议再完善也不能替代人的判断。人工审核编辑环节解决的是“信任边界”问题模型给出的修改计划是否合理涉及删除、覆盖、批量替换的操作是否有风险有没有超出当前任务范围的意外改动所以 VT Code 的工作流强调 human-reviewed让 AI 先生成计划再由人来批准最后才执行。这比“完全自动执行”稳妥也比“手工改完全部代码”高效。1.4 适合谁读、读完能做什么如果你属于下面任何一类这篇文章都值得往下看后端开发者想了解终端编码代理如何落地不再只停留在“让 AI 写个函数”的层面。全栈工程师想在自己项目中接入人工审核式 AI 工作流。AI 应用开发新手想理解 MCP、WebMCP、Agent 这些概念并能动手跑通一个最小示例。读完本文你会掌握终端编码代理的核心工作流程、WebMCP 的作用边界、人工审核编辑器如何与 Agent 配合以及一个可以复制运行的 Python 示例。2. 核心概念拆解2.1 Terminal Coding Agent 的工作方式Terminal coding agent 本质上是把大模型与终端能力连接起来的程序。它通常包含几个模块指令解析接收自然语言任务比如“把日志文件的输出格式改成 JSON”。上下文收集扫描项目目录、读取关键文件、查看 Git 状态。工具调用执行 shell 命令、读写文件、调用测试脚本。结果反馈把执行结果返回给模型继续下一步决策。与 IDE 插件不同终端编码代理不要求开发者开启某个编辑器窗口。它更像一个“数字同事”你在终端里给它下达任务它在工作区中操作然后把结果汇报给你。2.2 WebMCP把“网页上下文”变成模型可读的协议WebMCP 这个名字由 Web 和 MCP 组合而来。传统 MCP 解决的是“模型如何调用本机工具”WebMCP 则更多关注“模型如何与网页内容、Web 服务交互并让人参与审核”。举个例子当编码代理准备修改一个前端页面的按钮文案时它可能需要读取页面源码、理解页面结构并确定修改会影响哪些模块。WebMCP 的作用是定义网页上下文的描述格式让模型能读懂。提供工具接口让模型获取页面内容或 DOM 结构。把修改方案转成结构化数据供人工审核编辑器渲染。简单说 WebMCP 像一层“翻译器”让模型、网页、编辑器之间可以交换语义明确的数据。2.3 Human-reviewed Editor给 AI 修改加一道人工闸门“人工审核编辑器”听起来很高大上核心其实就是一个 Web 页面 审核接口。页面展示的内容包括用户原始诉求。模型计划调用的工具。工具参数比如文件路径、要覆盖的新内容。风险等级比如写入操作比读取操作风险高。审核接口则负责接收“同意/拒绝”的结果并把结果写回 Agent 的状态文件。只有被审核通过的修改才会进入执行阶段。这样做等于在 AI 决策链条中加了一个“人肉 if 判断”把高风险操作的通过率控制在人手里。3. VT Code 的整体设计思路3.1 两层架构Agent 层与审核层从架构上看VT Code 类工具可以拆成两层第一层是 Agent 核心负责理解任务、生成计划、调用工具。它运行在终端中不依赖浏览器。第二层是 WebMCP 审核层负责把计划可视化并收集人的审批结果。它通过本地 HTTP 服务与 Agent 核心通信。两层之间用文件或接口传递数据。比如 Agent 生成 plan.json审核层读取并渲染成 HTML 页面用户点击“同意”后写回 approved.jsonAgent 读取后再执行。这种解耦方式的好处是Agent 核心可以脱离 Web 独立测试。审核页面可以自由替换不影响 Agent 逻辑。风险操作必须先经过审核层执行记录也便于审计。3.2 一次任务的完整流程下面把一次典型任务拆成步骤用户在终端输入自然语言请求比如“把 docs/readme.md 中的版本号改为 v2.3.0”。Agent 解析意图识别出需要调用replace_text工具并生成修改计划。计划保存为 JSON同时启动 WebMCP 审核页面。用户在浏览器查看修改内容、文件范围、风险等级。用户点击同意或拒绝审核层把结果写回状态文件。Agent 根据审核结果决定是否调用工具执行修改。执行完成后Agent 在终端输出修改日志并更新审核页面状态。整个过程不需要用户离开终端去复制代码也不需要担心 AI 擅自改动文件因为改动前多了一道人工确认。3.3 配置文件的模样很多终端编码代理都支持配置文件用来声明模型、工具源、审核服务地址等。下面是一个概念性的配置示例[agent] name vt-code-demo model your-llm-model base_dir ./workspace [review] host 127.0.0.1 port 8765 language zh-CN [tools] sources [./config/tools.json]这里只是展示配置思路实际项目需要根据自己的目录结构、模型服务和审核端口调整。注意不要把模型名和端口写成固定值尤其是多人协作时最好让每个开发者使用独立配置。4. 环境准备与基础终端工作台4.1 操作系统与终端模拟器VT Code 这类工具对终端模拟器有较高依赖因为要展示日志、状态、diff 等文本信息。推荐使用WindowsWindows Terminal支持多标签页、主题定制也支持离线安装适合内网环境。macOS系统自带 Terminal或者 iTerm2。LinuxGNOME Terminal、Konsole或者直接在 VS Code 中打开终端。如果你的终端出现乱码、颜色丢失、tab 宽度异常先检查终端字符集是否为 UTF-8再检查是否启用了 TrueColor 支持。很多终端编码代理会输出 ANSI 颜色码终端关闭相关选项时日志会变得难以阅读。4.2 运行时环境本文示例使用 Python 3.10只依赖标准库不要求安装额外的第三方包。为了确保兼容建议先查看本机 Python 版本python --version如果你的系统同时存在 python 和 python3注意选择与项目虚拟环境一致的命令。下面的示例全部使用python你可以在自己的环境中替换为python3。4.3 目录结构规划先创建一个项目目录后面所有示例文件都放在这个目录下vt-code-demo/ ├── agent.py ├── config/ │ └── tools.json ├── review/ └── workspace/agent.py编码代理主程序负责计划生成、审核服务、执行审批通过的操作。config/tools.json声明工具元数据用于让代理知道有哪些可调用能力。review/保存计划、审核状态和审批结果。workspace/模拟的实际工作目录测试写入操作会落在这里。5. 实战实现一个带人工审核 WebMCP 编辑的最小编码代理为了讲清楚“终端编码代理 人工审核 WebMCP 编辑器”的核心机制我们来实现一个最小示例。它不做真实的 LLM 调用而是用规则解析来代替模型决策重点演示完整链路。5.1 定义工具元数据新建config/tools.json{ tools: [ { name: read_file, description: 读取指定文件的文本内容, parameters: { type: object, properties: { path: { type: string, description: 文件路径 } } }, risk: low }, { name: write_file, description: 将内容写入指定文件会覆盖已有内容, parameters: { type: object, properties: { path: { type: string, description: 文件路径 }, content: { type: string, description: 要写入的完整内容 } } }, risk: high } ] }这里把工具分成了只读和写入两类写入操作的风险等级标记为 high后面审核页面会据此提醒用户重点检查。5.2 编码代理主程序新建agent.py完整代码如下#!/usr/bin/env python3 VT Code Demo带人工审核的最小编码代理示例 import argparse import json import re from pathlib import Path from http.server import BaseHTTPRequestHandler, HTTPServer BASE_DIR Path(__file__).resolve().parent REVIEW_DIR BASE_DIR / review PLAN_FILE REVIEW_DIR / plan.json APPROVED_FILE REVIEW_DIR / approved.json STATE_FILE REVIEW_DIR / state.json PORT 8765 TOOL_REGISTRY { read_file: { name: read_file, description: 读取指定文件的文本内容, risk: low, }, write_file: { name: write_file, description: 将内容写入指定文件会覆盖已有内容, risk: high, }, } def ensure_dirs(): REVIEW_DIR.mkdir(exist_okTrue) (BASE_DIR / workspace).mkdir(exist_okTrue) def parse_user_request(text: str): 模拟模型决策从自然语言请求中解析出工具调用。 真实场景中这里应接入大模型由模型决定调用哪个工具、传入什么参数。 m re.search(r写入\s(\S)\s内容为\s*(.), text) if not m: return None path m.group(1) content m.group(2).strip() return { tool: write_file, arguments: { path: path, content: content, }, } def create_plan(request_text: str): ensure_dirs() action parse_user_request(request_text) if action is None: plan { id: plan-demo-001, status: needs_human_input, intent: request_text, reason: 未能识别为明确的写入任务请人工补充说明, action: None, tool: None, } else: tool_name action[tool] plan { id: plan-demo-001, status: pending_review, intent: request_text, action: action, tool: TOOL_REGISTRY.get(tool_name), } PLAN_FILE.write_text(json.dumps(plan, ensure_asciiFalse, indent2), encodingutf-8) if STATE_FILE.exists(): STATE_FILE.unlink() print(f计划已生成{PLAN_FILE}) print(下一步运行 python agent.py serve 打开人工审核页面) def render_review_page(plan): intent plan.get(intent, ) action plan.get(action) tool plan.get(tool) or {} action_text json.dumps(action, ensure_asciiFalse, indent2) if action else 暂无结构化计划 risk tool.get(risk, unknown) tool_name tool.get(name, unknown) return f!DOCTYPE html html langzh-CN head meta charsetutf-8 / titleWebMCP Review Editor/title style body {{ font-family: system-ui, sans-serif; max-width: 820px; margin: 40px auto; padding: 0 20px; }} pre {{ background: #f6f8fa; padding: 16px; border-radius: 8px; overflow-x: auto; }} button {{ padding: 8px 18px; font-size: 15px; margin-right: 12px; border: 0; border-radius: 6px; cursor: pointer; }} .approve {{ background: #1a7f37; color: #fff; }} .reject {{ background: #cf222e; color: #fff; }} .risk {{ display: inline-block; padding: 2px 10px; border-radius: 12px; background: #fff5b1; }} /style /head body h1WebMCP 人工审核编辑器/h1 pstrong用户请求/strong{intent}/p pstrong待调用工具/strong{tool_name}/p pstrong风险等级/strongspan classrisk{risk}/span/p pre{action_text}/pre button classapprove onclicksend(approved)同意执行/button button classreject onclicksend(rejected)拒绝/button script async function send(decision) {{ const res await fetch(/api/review, {{ method: POST, headers: {{Content-Type: application/json}}, body: JSON.stringify({{decision: decision}}) }}); const data await res.json(); alert(审核结果 data.state); }} /script /body /html class ReviewHandler(BaseHTTPRequestHandler): def do_GET(self): if self.path /review: if not PLAN_FILE.exists(): self.send_error(404, plan not found) return plan json.loads(PLAN_FILE.read_text(encodingutf-8)) html render_review_page(plan) self.send_response(200) self.send_header(Content-Type, text/html; charsetutf-8) self.end_headers() self.wfile.write(html.encode(utf-8)) else: self.send_error(404) def do_POST(self): if self.path ! /api/review: self.send_error(404) return length int(self.headers.get(Content-Length, 0)) body json.loads(self.rfile.read(length) or b{}) decision body.get(decision, rejected) state approved if decision approved else rejected if state approved: plan json.loads(PLAN_FILE.read_text(encodingutf-8)) APPROVED_FILE.write_text( json.dumps({decision: state, plan: plan}, ensure_asciiFalse, indent2), encodingutf-8, ) STATE_FILE.write_text( json.dumps({state: state}, ensure_asciiFalse, indent2), encodingutf-8, ) response json.dumps({ok: True, state: state}, ensure_asciiFalse) self.send_response(200) self.send_header(Content-Type, application/json; charsetutf-8) self.end_headers() self.wfile.write(response.encode(utf-8)) def log_message(self, *args): pass def apply_approved(): ensure_dirs() if not APPROVED_FILE.exists(): print(没有已审核通过的记录请先执行 plan 和 serve 完成审核。) return record json.loads(APPROVED_FILE.read_text(encodingutf-8)) plan record.get(plan, {}) action plan.get(action) if not action: print(计划中没有可执行的操作。) return tool_name action.get(tool) args action.get(arguments, {}) if tool_name write_file: path BASE_DIR / args[path] path.parent.mkdir(parentsTrue, exist_okTrue) path.write_text(args[content], encodingutf-8) print(f已执行写入{path}) else: print(f暂不支持执行工具{tool_name}) def main(): parser argparse.ArgumentParser(descriptionVT Code Demo Agent) sub parser.add_subparsers(destcommand, requiredTrue) p_plan sub.add_parser(plan, help生成修改计划) p_plan.add_argument(request, help自然语言请求) sub.add_parser(serve, help启动人工审核 WebMCP 编辑服务) sub.add_parser(apply, help执行通过审核的计划) args parser.parse_args() if args.command plan: create_plan(args.request) elif args.command serve: ensure_dirs() print(f人工审核页面http://127.0.0.1:{PORT}/review) HTTPServer((127.0.0.1, PORT), ReviewHandler).serve_forever() elif args.command apply: apply_approved() if __name__ __main__: main()这段代码虽然简略但完整覆盖了 Agent 的核心链路计划生成、Web 审核、审批执行。5.3 人工审核 WebMCP 编辑器的页面逻辑render_review_page函数生成了审核页面核心逻辑是展示用户原始请求方便确认“AI 是否理解对了需求”。展示待调用的工具名称和参数。用不同的按钮区分“同意执行”和“拒绝”点击后通过 fetch 发送 POST 请求。这里没有引入前端框架也没有使用构建工具而是用 Python 字符串模板直接生成 HTML。好处是零依赖读者可以很快跑通坏处是模板转义不够完善生产环境应该使用 Jinja2 之类的模板引擎并对特殊字符做 HTML 转义。5.4 运行与验证先进入项目目录生成计划python agent.py plan 写入 workspace/hello.txt 内容为 Hello VT Code如果命令解析成功控制台会输出计划已生成.../review/plan.json 下一步运行 python agent.py serve 打开人工审核页面打开另一个终端启动审核服务python agent.py serve浏览器访问http://127.0.0.1:8765/review页面会显示请求、工具名称、风险等级和待执行参数。点击“同意执行”后服务端会写入review/approved.json再执行 apply 命令python agent.py apply这时会看到输出“已执行写入.../workspace/hello.txt”。查看文件内容cat workspace/hello.txt结果为Hello VT Code。5.5 结果说明整个流程中真正的写操作发生在apply阶段而不是plan阶段。也就是说即使 Agent 生成了计划如果没有人在审核页面点击同意write_file永远不会执行。这就是人工审核的核心价值。再试一次拒绝流程python agent.py plan 写入 workspace/bye.txt 内容为 bye python agent.py serve在页面点击“拒绝”然后执行python agent.py apply因为review/approved.json不存在程序会提示“没有已审核通过的记录”写入操作不会发生。6. 常见问题与排查思路6.1 高频故障对照表问题现象常见原因解决思路点击审核按钮后提示跨域错误浏览器直接打开本地 HTMLfetch 到 127.0.0.1:8765 属于跨域统一通过 http://127.0.0.1:8765/review 访问页面端口 8765 被占用其他程序占用了端口修改代码中的 PORT 变量重新启动服务计划生成后页面显示 unknown工具名称未在 TOOL_REGISTRY 中注册检查 tools.json 中的工具名并在代码中补充注册表apply 不执行任何操作没有点击“同意”approved.json 不存在先访问审核页面并点击同意再执行 apply中文内容写入后乱码终端编码或文件编码不匹配统一使用 UTF-8代码中已指定 encodingutf-8正则无法解析复杂请求演示解析器只覆盖“写入 xxx 内容为 yyy”格式接入真实 LLM 决策层替换 parse_user_request 函数6.2 两个典型排错案例第一个案例服务能启动但浏览器打开 127.0.0.1:8765/review 返回 404。排查思路先确认 plan 是否已经生成。serve命令只负责渲染审核页面如果review/plan.json不存在服务端会返回 404。所以在启动服务前必须先执行plan命令。第二个案例点击同意后apply 仍然提示没有审核记录。排查思路检查review/approved.json是否生成。如果文件存在再看文件内容中的plan字段是否完整。这里有一个容易踩的坑审核服务记录的是“当前 plan.json 的快照”如果之后又执行了一次新的 plan旧审批记录仍然保留但 apply 可能会执行旧计划。生产环境应该为每条计划生成唯一 id并用 id 关联审批结果。7. 最佳实践与工程建议7.1 安全与权限终端编码代理因为能直接操作文件系统安全边界必须严格设计。最小权限原则Agent 使用的账号只应该具有当前项目目录的读写权限不要使用管理员身份运行。路径校验写入文件前检查目标路径是否在工作目录内防止../路径穿越。高危操作隔离凡是涉及删除、覆盖、批量替换的调用都应强制进入人工审核流程。沙箱环境复杂任务先在临时目录或容器中试运行再在真实项目执行。这些都是通用工程建议具体实现要根据实际项目调整。7.2 日志与审计人工审核机制的价值之一是可追溯。每次计划生成、审核决定、执行结果都应该有日志。建议记录生成时间、计划 ID、意图、工具名、参数。审核人身份、审核时间、审核结果。执行开始时间、执行耗时、退出状态码。实际修改文件前后的 diff。日志文件建议使用 JSON Lines 格式每行一个事件方便用 jq 或日志系统分析。7.3 人工审核机制的工程化设计不要把审核页面写成一个一次性 HTML。实际项目中可以考虑将计划保存为结构化数据审核页面与 Agent 通过协议读取而不是直接拼接字符串。引入 diff 展示让用户直观看到改动前后差异。设置“撤销按钮”执行后允许回滚。对低风险操作可以设置自动通过规则例如只读操作或纯格式化操作。对高风险操作强制要求二次确认比如输入项目名或标记高风险原因。审核不是一刀切好的设计应该根据操作风险动态决定是否需要人介入以及介入的深度。7.4 可维护性与后续扩展从演示代码走向生产环境还需要考虑接入真实 LLM用 OpenAI、Claude 或本地模型替换规则解析让模型根据任务动态选择工具。接入真实 MCP Server按 MCP 协议定义工具而不是硬编码 JSON 注册表。使用模板引擎免去手写 HTML 转义的麻烦减少 XSS 风险。增加事件持久化使用 SQLite 或消息队列保存任务状态避免进程重启导致状态丢失。增加测试对计划生成、审核接口、执行模块分别编写单元测试。推荐演进路径是先用规则解析跑通链路再接入 LLM 决策先本地审核再扩展到远端审核服务。每进一层都确保旧链路可以回退。8. 总结与学习路线8.1 核心要点本文围绕 VT Code 的设计方向梳理了终端编码代理、WebMCP、人工审核编辑器三者之间的关系并给出了一个可运行的最小示例。核心收获有三点终端编码代理的价值在于把 AI 决策与 shell 执行结合但必须约束风险。WebMCP 是模型与网页工具之间的语义桥梁让人工审核成为可能。人工审核不能只做一个“同意/不同意”的按钮它应该与计划、执行、日志闭环。8.2 下一步学习如果你对这类工具感兴趣建议按下面的路线继续深入学习 MCP 协议规范理解 client、server、tool、resource 这几个抽象概念。在本地搭建一个最小 MCP Server暴露读取文件、写入文件、执行命令三个工具。把本文示例中的 TOOL_REGISTRY 替换为 MCP Client让 Agent 动态发现工具。再实现一个基于 WebSocket 的审核接口让审核页面可以实时收到 Agent 状态更新。最后考虑接入身份认证让多人协作时能区分审核人与执行权限。8.3 动手验证代码已经完整直接复制到本地运行一遍比单纯阅读效果要好。哪怕只是跑通一次“写入 → 审核 → 执行”的闭环也能让你对终端编码代理的架构有更直观的感觉。如果本文对你有帮助可以收藏备用后续可以继续扩展成完整的 MCP 版本教程。有任何运行问题也欢迎对照第 6 节的排查表格逐步定位。