最近我一直在折腾 AgentGlass 和 Pi 这对组合起因其实很简单身边有不少朋友开始让 AI 帮忙改代码但每次 AI 噼里啪啦输出完之后他们根本不知道哪些文件被碰过、改成了什么样、有没有顺手删掉不该删的东西。有人干脆不敢用还有人用完一次就慌了总觉得哪里被动过又说不清楚。我自己也有过这种体验直到把 AgentGlass 和 Pi 放在一起用才真正解决了这个痛点AI 动手改文件之前你就能看到它准备做什么改完之后还能回头复盘每一步。AgentGlass 解决的恰恰是“AI 操作黑箱”这个环节。它像一层透明的玻璃罩把 Pi一个跑在本地、能直接改代码的开源编程 agent的工作过程完整暴露在你面前。Pi 准备动哪个文件、改哪几行、删掉什么内容AgentGlass 都会提前摆出来甚至可以让你在关键时刻喊停。这篇就是我的完整上手记录从安装配置、连接方式到一次真实的文件修改演示再到我踩过的几个坑全部整理出来。如果你也是一个不敢轻易把代码交给 AI 的新手或者你想让团队里其他成员更放心地使用 AI 编程工具这篇内容应该能帮你省不少事。1. 为什么非要把 AI 的操作“亮出来”1.1 新手面对 AI 改代码的第一个恐慌市面上大多数 AI 编程工具的逻辑都是“你给它一个指令它直接输出结果”。对老手来说这很爽反正我最后会 review 代码出了问题 git revert 就行。但对新手完全不是一回事很多人连当前目录里有哪些文件都摸不清更别说判断 AI 改得对不对了。我见过一个真实案例朋友让 AI 给 Python 脚本加一个日志功能结果 AI 顺手把配置文件里的环境变量也改了朋友完全没察觉直到程序启动报错才发现问题。那一刻他跟我说这种感觉就像有人趁你不在进房间动了一圈东西还告诉你“都弄好了”——你根本不知道丢了什么。所以问题的核心不是 AI 改得对不对而是改之前没有一种机制让新手看懂会发生什么。老手可以靠经验和 git diff 事后补救新手需要的是“事前透明”也就是在文件真正发生变化之前先把 AI 的计划呈现出来。这个需求听起来很基础但很多 AI 编码工具都没做好。1.2 AgentGlass 与 Pi一个负责执行一个负责“直播”我这次组合里的两个角色分工非常明确。Pi 是个干活的主力。我把它理解成一个跑在终端里的编程 agent你给它自然语言任务比如“帮我把订单模块的错误处理补全”它会自己规划步骤、读取项目文件、调用工具最后直接动手修改代码。Pi 这类工具的优势是可以在本地跑你的代码不会传到某一个网页对话框里对重视代码隐私的场景很有吸引力。它本身不是新人友好型的工具因为默认情况下你只看到一堆终端日志根本猜不到它下一步要干嘛。AgentGlass 就是来解决这个“看不到”的问题。它可以理解为一个运行在本地的可视化面板以 Web 页面的形式展示 agent 正在做什么。它挂在你指定的项目目录上监听这个目录里发生的文件变化。Pi 在这个目录里改出来的任何一个文件AgentGlass 都会实时捕捉然后按时间顺序整理成一条条事件。你可以看到哪个文件被新增、修改、删除甚至可以看到文件修改前后的差异对比。这两个工具加在一起的效果就是Pi 负责干活Glass 负责全程“直播”。我在实际操作里最直观的感受是以前让 AI 改代码心里是悬着的现在随时可以打开面板看一眼进度和变更内容心里踏实很多。2. 动手之前环境准备与安装记录2.1 先装 Pi 这个干活的主力我这里记录的是当时版本的安装方式不同版本命令可能会有差异建议以官方 README 为准。我用的环境是 macOS之前已经装好了 Node.js 18 以上版本因为 Pi 本身是 Node 技术栈的 CLI 工具所以安装走 npm 最省事。打开终端执行npm install -g pi-agent装完之后验证一下版本号pi --version能正常打印出版本号就说明装好了。如果你用的是 Windows思路一样只是终端命令在 PowerShell 里跑注意全局安装路径要加到环境变量里。整个安装过程大概十几分钟网络情况正常的话基本不会出岔子。这里有一个很容易被新手忽略的点Pi 虽然是个命令行工具但它实际改文件的时候是需要完整的 Node 运行环境的。如果你的机器上同时装了多个 Node 版本比如用 nvm 管理建议把 Pi 安装和运行锁定在同一个 Node 版本上否则很容易出现“昨天还能用的命令今天突然报错”这种诡异问题。我第一次就踩了这个坑后来重新切换到默认版本才消停。2.2 再装 AgentGlass 这个旁观者AgentGlass 我装的是 Python 版它本质上是一个本地服务用浏览器作为操作界面。安装同样很简单pip install agentglass安装成功后需要启动一个本地面板agentglass serve --port 8787启动完成后浏览器打开 http://127.0.0.1:8787 你会看到一个类似仪表盘的空页面目前还没有任何数据。这时候 AgentGlass 已经处于待命状态等你去关联一个具体的项目目录。默认端口我习惯用 8787如果你那边端口被占用了换成 9000 之类的就行。这里我想多说一句关于“本地化”的价值。AgentGlass 是一个完全跑在你自己机器上的服务所有监听数据都不经过第三方服务器这一点对处理敏感项目的人来说挺重要。你不需要把代码内容发给任何外部接口面板上看到的全是你本机的东西。对于像我这样有轻微隐私洁癖的人这种“数据不出机器”的方案比云端可视化工具更让人放心。2.3 连接方式让 Glass 看到 Pi 的一举一动安装完两个工具之后最关键的一步是让它们连接起来。AgentGlass 的监听模式提供了一条命令叫watch专门用来挂载项目目录。打开一个新的终端窗口进入你想让 AI 干活的项目目录然后执行cd ~/projects/myapp agentglass watch .执行完这条命令后AgentGlass 会开始递归监听当前目录下所有文件的变化包括新增、修改、删除、重命名这几种常见操作。这里最妙的设计是AgentGlass 并不依赖 Pi 主动上报什么它是通过监听文件系统事件来工作的。所以理论上不管哪个 agent 在这个目录里跑只要它碰了文件Glass 都能看到。我在实际操作中还试过另一种连接方式就是把 watch 的目标直接指向 Pi 的工作区。Pi 默认会在项目目录下生成一个.pi文件夹里面有一些中间产物和任务记录。只要你 watch 的是整个项目目录这些变化自然也会被 Glass 捕捉到。不过我个人建议在展示时把.pi这类内部目录隐藏掉不然时间线里会出现大量无关事件影响阅读。3. 第一次实操让 Pi 给脚本加日志3.1 我准备的最小测试项目为了不把事情搞复杂我建了一个非常小的 Python 项目来跑通全流程。目录里就一个文件order_price.py里面是一个计算订单总价的函数代码很简单def calc_total(items): total 0 for item in items: total item[price] * item[qty] return total这个函数的逻辑是遍历订单商品列表把每个商品的单价乘以数量累加出总价。够简单也没有外部依赖。我选它做测试是因为它一眼就能看明白后续 Pi 改了什么不需要懂业务也能直观理解。我还额外放了一个data.json模拟订单数据纯粹是为了让 Pi 在分析时能有一个输入样例。测试项目就这两个文件非常干净。项目越简单越容易观察 AI 的行为模式这是我一直以来的习惯第一次用新工具绝不拿复杂项目试水。3.2 向 Pi 下达指令按照我预先想好的任务我在另一个终端里给 Pi 发出指令pi 给 calc_total 函数添加日志输出要求支持通过参数传入 logger日志要记录每个商品的小计和最终总价不要改变原有返回值逻辑提交指令之后Pi 会先输出一段任务理解然后开始读文件。这些中间日志在终端里滚动得很快如果只看终端你大概能感觉到它在忙但绝对看不清它到底读了什么、准备改什么。这正是 AgentGlass 发挥作用的时候。我同时打开浏览器切到 AgentGlass 面板点击“开始捕捉”按钮。从这一刻起Pi 在项目目录里做的所有文件操作都会按时间顺序出现在面板上。我在实操过程中习惯把终端窗口放在左侧面板放在右侧这样既能看命令输出又能看文件事件两边对照起来特别直观。3.3 见证修改过程Glass 上的实时时间线Pi 开始工作之后AgentGlass 面板上迅速出现了一条时间线。第一次运行我印象很深事件大概分成这么几段新建临时文件Pi 先创建了一个临时记录文件用来存自己的任务状态。读取order_price.pyPi 这个读操作本身不会触发文件修改但 Glass 会把访问历史记录下来方便你追溯它看了哪些文件。修改order_price.py这是核心事件Glass 标记为“修改”并且把修改前后的内容都保存了下来。删除临时文件收尾时 Pi 清理掉自己的临时产物Glass 也如实记录了这一笔。每一条事件都可以点开面板会展示该文件的路径、操作类型、时间戳以及一个非常关键的“查看差异”按钮。我在实操里把这个按钮几乎点烂了因为它的体验非常像代码评审工具新增行高亮成绿色删除行高亮成红色一眼就能看出改动范围。对于新手来说这种可视化比读终端日志友好得多。3.4 修改前后的文件对比Pi 实际把order_price.py改成了下面这样def calc_total(items, loggerNone): total 0 for item in items: subtotal item[price] * item[qty] if logger: logger.info(fitem{item[name]}, subtotal{subtotal}) total subtotal if logger: logger.info(ftotal{total}) return total在 AgentGlass 的差异视图里我能清楚看到三处变化函数签名多了一个loggerNone参数循环体里新增了 subtotal 变量并增加了日志输出最后返回前多了一条总价日志。整个改动逻辑合理并且没有破坏原来的计算方式。这个过程给我最大的触动是以前让 AI 改完代码我至少要自己重新读一遍文件才能确认它干了什么。现在直接在面板上扫一眼差异就够了注意力完全集中在关键变化上不需要再做一次完整的代码走读。对于新手这种体验几乎是从“盲赌”变成了“全程监督”改文件的失控感一下就消失了。4. 核心机制AgentGlass 是怎么做到全程可见的4.1 文件系统事件监听背后是一个底层通知机制AgentGlass 之所以能实时捕捉 Pi 的每一步操作是因为它调用了操作系统底层的文件系统事件通知机制。在 macOS 上对应的是 FSEventsLinux 上一般是 inotifyWindows 上则是 ReadDirectoryChangesW。这些机制可以让程序不依赖轮询而是由操作系统在文件发生变化时主动推一个事件。这里我用一个生活化的比喻轮询方式就像一个保安每隔几秒拿手电筒扫一圈看有没有人费电又反应慢事件监听方式则像是在门口装了传感器有人经过立刻触发警报精确又及时。AgentGlass 正是靠这套传感器级别的机制才能在 Pi 保存文件的同一瞬间看到变化并且把事件按发生顺序记录下来。理解了这一层你就能明白为什么 AgentGlass 能兼容各种不同的 agent 工具。不管是 Pi还是其他跑在终端里的编程 agent只要它们最终是通过修改文件系统来完成任务Glass 就能监听到。它根本不关心 agent 内部是怎么思考的只关心文件层面发生了什么这也是这个方案最巧妙的地方。4.2 变更快照与差异计算不是只告诉你“动了”光知道哪个文件被动了价值还不大。AgentGlass 做得更到位的一步是它为每个修改事件保存了“变更前后的快照”然后通过差异算法把两个版本的内容做对比生成我们看到的绿色和红色高亮差异视图。这个流程我第一次看的时候没觉得多难但自己实现过类似功能之后才发现难点不在 diff 算法本身而是如何处理反复修改的情况。一个复杂任务里Pi 可能对同一个文件改上四五轮如果每一轮都生成一次快照时间线上会挤满事件。AgentGlass 的处理方式是在同一个“任务会话”里对同一个文件的多次修改会聚合成一条记录差异视图展示的是第一次修改前和最后一次修改后的对比。中间过程没有直接显示但可以在事件详情里逐段展开。这个设计我认为非常实用尤其是面对复杂项目的时候你不会被几十条琐碎事件淹没而是能快速聚焦到每个文件的最终变化。加上面板里的会话分组功能你可以把 Pi 一次任务产生的所有文件变化归类整理复盘效率高不少。4.3 确认机制先看再允许把“后悔药”提前到修改前AgentGlass 还提供了一个我特别欣赏的功能执行拦截与确认。你可以把面板切换到“确认模式”在这种模式下Pi 对文件的操作不会立刻写入磁盘而是被挂起等待人工批准。你在面板上看到差异预览后可以点击“允许”放行也可以点击“拒绝”让 Pi 换一个改法。这个机制在标题里强调的“AI 修改文件前先看懂会发生什么”体现得最为充分。它把控制权真正交回给用户而不是让你事后靠 git 反悔。我第一次测试确认模式时故意让 Pi 去做一个删除配置项的操作Glass 直接把这次删除拦截下来我在预览里看到差异后点了拒绝那个改动就没有落地。对于新手来说这种一道“闸门”的保护价值比任何功能都实在。实现上我理解 AgentGlass 是在 watch 层的缓存目录里拦截写操作等用户确认后才同步到真实文件。当然确认模式只适合对速度要求不高的场景因为每一步修改都要人工点头整体速度会慢不少。我在平时快速实验时通常开着实时模式遇到真正重要的项目才切换成确认模式两条路线配合着用。5. 踩坑实录这几天我遇到的高频问题5.1 Pi 的事件推不到 Glass路径不一致惹的祸我第一天用这个组合就卡住了。Pi 在终端里正常干活代码也改成功了但 AgentGlass 面板上一片空白什么都不显示。我排查半天才发现问题出在目录路径上我在一个终端里用agentglass watch ~/projects/myapp挂载了项目但 Pi 是在另一个终端里通过相对路径启动的实际工作目录因为软链接的关系指向了/Users/xxx/mylink操作系统把它识别成了不同的路径位置事件自然就传不到 Glass 的监听范围里。解决方案其实很简单统一用绝对路径。挂载和启动 Pi 的时候我都改成agentglass watch /Users/xxx/projects/myapp pi --workdir /Users/xxx/projects/myapp 任务描述这样两边指向的是同一个真实位置事件传输立刻恢复正常。我建议你把这条固定住凡是遇到 Glass 不捕捉事件的情况第一个检查项就是路径是否一致。5.2 明明改了文件时间线却是空的另一个让我抓狂的问题是Pi 明确说文件已经改好了终端日志也显示写入成功但 Glass 时间线依然空白。后来我发现这种情况通常发生在编辑器或 IDE 的“自动保存”机制上。有些工具不会直接修改原文件而是先把改动写到临时文件再通过改名的方式覆盖原文件。这个流程里原文件本身会先收到一个“删除事件”紧接着再收到一个“创建事件”而不是常规的“修改事件”。AgentGlass 默认会吞掉一些系统内部产生的临时文件噪音但如果写入方式太特殊事件确实可能被过滤掉。我的解决办法是把监听粒度调到“完整模式”并且去事件设置里开启对“重命名”和“创建”事件的展示。这么调之后那些被吞掉的写入操作就能显示出来了虽然时间线上会多一些噪音但至少不会漏事件。事后记得调回常规模式否则临时文件事件太多会影响阅读。5.3 大文件和二进制文件简直是一场灾难Pi 在跑一个小型前端项目时顺手改了一个package-lock.json这个文件有几千行AgentGlass 的差异视图瞬间就卡住了浏览器滚动都费劲。更夸张的是项目里还有几张 PNG 图片Pi 只是碰了一下时间戳Glass 试图对二进制数据做 diff结果界面上全是乱码。后来我学乖了在 AgentGlass 的配置文件里加了一段忽略规则把node_modules、*.png、*.jpg、*.lock这类文件全部排除在 diff 计算之外。对于大文件我只关心它是否被修改不关心具体改了什么所以让 Glass 只记录行数变化和修改时间就够了。这样时间线依然完整但不再出现卡死和乱码的场景。这个优化对实际使用体验的提升非常明显。5.4 权限收太紧Glass 会变成一个瞎子我给项目目录设过比较严格的权限只允许当前用户读写其他用户一律拒绝。结果有一次 Pi 是在后台服务模式下运行的这个服务用的账号和我的终端账号不是同一个它对项目目录的文件操作权限不足根本没有真正改动文件。Pi 自己没意识到它的任务状态还显示成功了但 Glass 侧什么都看不到两个工具的数据对不上。这个坑花费了我不少时间。检查权限这一步我建议放在最开始直接在终端里跑一下ls -l看目录归属再用启动 Pi 的同一个账号去测试目录写入权限。如果项目目录放在共享盘或者挂载卷上还要额外检查挂载参数是不是只读模式。我最终把项目目录改成了用户组可读写让 Pi 的运行账号也加入同一用户组事件才稳定下来。5.5 高频问题速查表问题现象可能原因排查要点Glass 完全没有事件挂载路径和 Pi 工作路径不一致统一使用绝对路径检查软链接文件改了很多但时间线很空临时文件覆盖原文件开启完整事件模式显示重命名和创建差异视图卡死或乱码大文件、二进制文件参与 diff配置忽略规则限制 diff 范围两个工具状态不一致运行账号权限不同检查用户组权限和挂载参数端口被占用启动失败本地服务端口冲突更换端口比如--port 9000Pi 执行失败但 Glass 不报错拦截模式未被用户确认在确认模式下手动批准或拒绝挂起事件结尾一点个人的实操体感折腾完这一圈我最直观的感受是AI 改代码这件事本身已经很成熟了缺少的从来不是能力而是“可控感”。AgentGlass 与 Pi 的组合让我第一次觉得自己不是在追着 AI 跑而是让 AI 在我的视线范围内干活。对新手来说这种“先看见再信任”的路径确实比直接面对一个黑箱要舒服太多。最后再分享一个小技巧当你想让 Pi 干活但又担心它动到不想碰的文件时不要只靠事后 review直接在给 Pi 的指令里写清楚“只允许修改 XXX 文件其他目录一律不动”再配合 AgentGlass 的确认模式基本上可以做到万无一失。我试过几次之后现在连提交代码前都习惯先在 Glass 里扫一遍变更记录等于多了一道自动审计。这个组合后续我还会继续用如果你想看实际场景的更多演示也欢迎告诉我具体的项目类型我下次直接拿真实项目再跑一遍给你看。