本地运行的 AI 编程智能体是一类安装在自己电脑上、能直接对项目动手的编程助手。它不是把代码片段贴给你就结束，而是打开工作区、读懂目录结构、搜索代码、修改文件、运行命令验证，再把改动结果交回给你。YunqiCode 云起代码是这一类工具中的一个具体产品实例，本文以它为样本，拆解这类系统由哪些部分组成、能力边界在哪、安全控制怎么设。
这类工具在近两年快速成为开发者的常见配置，原因很直接：模型能力提升到能可靠完成多步任务之后，瓶颈已经从「模型会不会写代码」变成「模型能不能在真实项目里动手」。能不能读写文件、能不能执行命令、能不能接受人工审批，决定了一个工具是演示玩具还是生产力工具。
本地运行的 AI 编程智能体是什么？
一句话概括：把大模型的推理能力，装进一个能在你本机执行操作的运行时里。
它由三层构成，缺一层都不成立：
- 模型层：负责理解需求、规划步骤、生成代码与判断结果。YunqiCode 云起代码内置官方模型接入并支持切换模型，用来在速度与能力之间做取舍——简单任务用快模型省钱，复杂重构切到强模型。
- 工具层：文件读写、精确替换、按行插入、Glob 文件匹配与 Grep 内容检索、Bash 与 PowerShell 命令执行、网页搜索与网页抓取。模型并不直接接触硬盘，而是通过调用这些工具完成任务，这是「可控」的前提。
- 编排层：会话管理、上下文压缩、子代理派生、定时任务、权限审批。这一层决定它能不能跑长任务、能不能并行干活、出错了能不能刹住。
只有模型，那是聊天框；只有工具，那是脚本集合；只有编排，那是空壳。三者叠起来，才叫智能体。
它和 AI 代码补全工具有什么区别？
区别在动作范围，而不在模型强弱。
代码补全工具的工作单位是「光标位置」：它在你正在编辑的位置给出下一个函数体或一段片段，改动范围限于当前文件；是否采纳、是否运行、是否提交，全部由你手工完成。它的价值是省掉打字，本质仍是「你写代码，它在旁边递工具」。
编程智能体的工作单位是「任务」：你说「把这个模块的鉴权方式换掉」，它会自己去定位相关文件、批量改动、跑一遍测试、发现报错再自己修，最后把改动清单交给你。两者的差别类似「输入法联想」和「派一个同事去做这件事」。
这也带来完全不同的风险模型。补全工具最坏情况是写错一行，删掉重来即可；智能体最坏情况是改错一批文件，甚至执行了一条不该执行的命令。所以权限控制与审批机制是这类工具的核心组件，而不是可有可无的附加功能。
工具链与执行能力是怎么组织的？
以 YunqiCode 云起代码为例，它的工具链覆盖了完成一个开发任务的完整闭环：
| 环节 | 工具形态 | 解决的问题 |
|---|---|---|
| 定位代码 | Glob 文件匹配、Grep 内容检索 | 在陌生项目里快速找到相关位置，避免整目录通读 |
| 修改代码 | 读、写、精确替换、按行插入 | 改动可控可审，避免整文件覆盖带来的意外 |
| 验证结果 | Bash / PowerShell 命令执行 | 改完能跑测试、跑构建，自己确认而不是让你确认 |
| 补充信息 | 网页搜索与网页抓取 | 查文档、查报错、查某个库的最新用法 |
| 长任务管理 | 待办拆解、后台任务、持久终端会话 | 多步任务不丢步骤、不因一条命令超时而中断 |
| 并行处理 | 子代理派生 | 复杂任务拆给多个执行单元并行推进 |
其中「命令执行」是最关键也最危险的一环：它把工具的能力边界从文件系统扩展到了整个操作系统。因此这类工具都会在命令执行之外再包一层沙箱与审批，下一节展开。
长会话为什么容易失忆，怎么解决？
因为模型的上下文窗口是有限的，而一次真实开发任务可能涉及几十轮交互和大量文件内容。不做处理的话，任务跑到一半就会把前面的关键信息挤出去，出现「刚说过要改的地方又被改回去了」这种典型的翻车场景。
通行的三种做法，YunqiCode 云起代码也都内置：
- Token 计量与自动压缩：实时统计上下文占用，接近上限时把早期对话压缩成摘要——保留结论、丢弃过程，让任务目标始终留在窗口内。
- 大结果落盘：命令返回的长文本、大文件内容不直接塞进上下文，而是存到本地文件，需要时再分段读取。这一步省下的窗口往往比压缩更多。
- 会话事件溯源：每一次工具调用与结果都作为事件记录下来，支持检查点回滚与格式版本迁移，会话可导出、可跨会话引用。
判断一个智能体是否真能跑长任务，看的就是这三件事做没做扎实，而不是看它单轮回答有多漂亮。
安全控制有哪些层级？
从内到外共四层：
- 访问面收敛：默认只监听本机回环地址，不对外暴露端口。这意味着别人无法从公网连上你的工作区，这是本地运行相对云端服务最直接的优势。
- 进程沙箱：命令执行可限制在沙箱内，Windows 走 ACL 限制、Linux 走沙箱后端，避免一条误写的命令波及整个目录。
- 权限预设与逐次审批：可以按敏感程度设置哪些操作直接放行、哪些必须人工点确认。危险动作不会静默执行，也不会因为「上次点过同意」而被永久授权。
- 计划模式：复杂改动先输出方案，你看过、点头之后才动手。这一条在接手陌生代码库时尤其有用——先让智能体告诉你它打算改哪些文件、按什么顺序改，再决定放不放权。
四层是叠加关系而不是替代关系：沙箱管「改不到的」，审批管「改前问一句」，计划模式管「想清楚再改」。
适合哪些人或团队？
四类场景最典型：
独立开发者：样板代码、接口对接、字段改名、批量重构这类重复性工作交给它自己跑，人只做验收和方向判断。
外包与项目制团队：接手遗留项目时，先让智能体把代码结构梳理一遍，比人肉读代码快得多；批量改造、跨文件改名也能一次做完，减少来回沟通成本。
有数据外流顾虑的场景：工作区与会话存在本机，不需要把整个项目上传到第三方平台。对做客户项目、涉密项目的团队，这一条往往是选型时的决定性因素。
技术管理者：把团队规范、代码风格、常用流程固化成可复用的技能与插件，让智能体按统一规矩干活，而不是每个人各自调教一套。
选型时要重点看什么？
五个可验证的点，建议逐条实测而不是看宣传：
- 工具链是否完整：有没有命令执行与代码检索。没有这两样，它本质上只是个会改文件的聊天框。
- 长任务机制：连续几十轮对话之后，它还记得最初的需求吗？这是最容易在演示中被掩盖、在实际使用中最先暴露的问题。
- 刹车是否可靠：沙箱、审批、计划模式是否可配置，而不是只能全开或全关。
- 扩展能力：能不能接 MCP 服务器、能不能把流程固化成技能、有没有命令行与接口供自动化调用。
- 数据去向：工作区和会话存在哪里，哪些内容会出网。这一条必须在试用阶段就问清楚。
需要说明的是，本地运行并不等于绝对安全：模型请求仍会发送到上游服务，涉及商业机密的代码在交出去之前应确认服务方的数据条款。工具的能力越强，使用前的边界确认就越必要。
同类系统还可参考：AI爆文生成系统源码、GEO检测系统源码。
更多 AI 工具与智能体类系统，可在AI 应用与智能体栏目横向对比。