最近我一直在折腾 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.py：Pi 这个读操作本身不会触发文件修改，但 Glass 会把访问历史记录下来，方便你追溯它看了哪些文件。 - 修改
order_price.py：这是核心事件，Glass 标记为“修改”，并且把修改前后的内容都保存了下来。 - 删除临时文件：收尾时 Pi 清理掉自己的临时产物，Glass 也如实记录了这一笔。
每一条事件都可以点开，面板会展示该文件的路径、操作类型、时间戳，以及一个非常关键的“查看差异”按钮。我在实操里把这个按钮几乎点烂了，因为它的体验非常像代码评审工具，新增行高亮成绿色，删除行高亮成红色，一眼就能看出改动范围。对于新手来说，这种可视化比读终端日志友好得多。
3.4 修改前后的文件对比
Pi 实际把order_price.py改成了下面这样：
def calc_total(items, logger=None): total = 0 for item in items: subtotal = item["price"] * item["qty"] if logger: logger.info(f"item={item['name']}, subtotal={subtotal}") total += subtotal if logger: logger.info(f"total={total}") return total在 AgentGlass 的差异视图里，我能清楚看到三处变化：函数签名多了一个logger=None参数；循环体里新增了 subtotal 变量并增加了日志输出；最后返回前多了一条总价日志。整个改动逻辑合理，并且没有破坏原来的计算方式。
这个过程给我最大的触动是：以前让 AI 改完代码，我至少要自己重新读一遍文件才能确认它干了什么。现在直接在面板上扫一眼差异就够了，注意力完全集中在关键变化上，不需要再做一次完整的代码走读。对于新手，这种体验几乎是从“盲赌”变成了“全程监督”，改文件的失控感一下就消失了。
4. 核心机制：AgentGlass 是怎么做到全程可见的
4.1 文件系统事件监听：背后是一个底层通知机制
AgentGlass 之所以能实时捕捉 Pi 的每一步操作，是因为它调用了操作系统底层的文件系统事件通知机制。在 macOS 上对应的是 FSEvents，Linux 上一般是 inotify，Windows 上则是 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 9000 |
| Pi 执行失败但 Glass 不报错 | 拦截模式未被用户确认 | 在确认模式下手动批准或拒绝挂起事件 |
结尾：一点个人的实操体感
折腾完这一圈，我最直观的感受是，AI 改代码这件事本身已经很成熟了，缺少的从来不是能力，而是“可控感”。AgentGlass 与 Pi 的组合让我第一次觉得，自己不是在追着 AI 跑，而是让 AI 在我的视线范围内干活。对新手来说，这种“先看见，再信任”的路径，确实比直接面对一个黑箱要舒服太多。
最后再分享一个小技巧：当你想让 Pi 干活，但又担心它动到不想碰的文件时，不要只靠事后 review，直接在给 Pi 的指令里写清楚“只允许修改 XXX 文件，其他目录一律不动”，再配合 AgentGlass 的确认模式，基本上可以做到万无一失。我试过几次之后，现在连提交代码前都习惯先在 Glass 里扫一遍变更记录，等于多了一道自动审计。这个组合后续我还会继续用，如果你想看实际场景的更多演示，也欢迎告诉我具体的项目类型，我下次直接拿真实项目再跑一遍给你看。
