企业官网建设流程全解析

1. 项目概述：这不是一个“外壳”，而是一套让 Pi Coding Agent 真正落地的本地操作系统级接口

你搜到“Pi Coding Agent”时，大概率看到的是它在网页端或 CLI 里跑 demo 的样子——输入一段需求，Agent 思考几秒，调用几个模拟 API，返回一段带代码块的 Markdown。很酷，但离“能干活”还差一层关键的东西：它没法真正触达你的键盘、鼠标、文件系统、剪贴板、正在运行的 Excel 或 Chrome 标签页。它像一个被关在玻璃房里的高级实习生，看得见任务，却够不着电脑本身。而Pi-Harness这个名字里的 “Harness”，不是“马具”那种束缚感，而是工程术语里的“线束”或“接口套件”——它把 Pi Coding Agent 这个智能体（Agent）和你真实的桌面操作系统（macOS / Windows / Linux）之间，用一套稳定、低延迟、可审计的原生通道给“捆扎”在一起了。它不替代 Agent，也不伪装成工具；它让 Agent 能安全、可控、按需地发起工具调用——比如“把当前 Chrome 标签页的 URL 复制到剪贴板”，“在 Desktop 新建一个以今天日期命名的文件夹”，“读取 ~/Documents/weekly_report.csv 的前 5 行”。这些操作，过去需要你手动点开浏览器、右键新建文件夹、打开终端敲命令；现在，Agent 只需生成一条结构化的工具调用指令，Pi-Harness 就在后台静默执行，并把结果原样回传。这背后没有魔法，只有三件事：一个轻量级本地服务进程、一套定义清晰的 IPC（进程间通信）协议、以及对各平台原生 API 的最小化封装。我做这个项目的直接动因，是发现团队里三位工程师在用 Pi Coding Agent 写自动化脚本时，有两人卡在“怎么让 Agent 把生成的 Python 脚本自动保存并双击运行”这一步上——他们试过用os.system()模拟，结果权限报错；试过写 WebHook 到本地 Flask 服务，又嫌启动慢、不安全。Pi-Harness 就是为解决这种“最后一公里”的断层而生的。它面向的不是算法研究员，而是每天要和 Excel、PDF、邮件客户端打交道的真实开发者、数据分析师、产品经理。如果你的场景是“让 AI 帮我操作我的电脑”，而不是“让 AI 在沙盒里模拟操作”，那 Pi-Harness 就是你需要的那个“本地控制台”。

2. 核心设计思路：为什么必须是“本地进程 + IPC”，而不是 Web UI 或远程 API？

2.1 拒绝 Web UI 方案：安全与权限的硬边界

最直观的想法，是给 Pi Coding Agent 套一个 Electron 或 Tauri 的桌面壳，做成一个带按钮和日志窗口的 GUI 应用。我试过第一版原型，两周后就彻底废弃了。原因很现实：Web 技术栈无法绕过操作系统的权限沙箱。当你在 Electron 渲染进程中想调用fs.writeFileSync()写入用户桌面，Electron 默认会拦截并抛出EACCES错误——因为渲染进程运行在 Chromium 的沙箱里，它连自己的主进程都无权直接通信，更别说访问磁盘。你当然可以配置nodeIntegration: true和contextIsolation: false，但这等于主动拆掉 Electron 最核心的安全护栏，一旦 Agent 加载了恶意网页或被注入脚本，它就能直接读取你的~/.ssh/id_rsa。这不是理论风险，2023 年就有真实案例：某知名低代码平台的 Electron 客户端因类似配置缺陷，导致用户本地数据库被批量导出。Pi-Harness 的设计哲学是“最小权限原则”：Agent 进程永远运行在受限环境（如 Docker 容器或独立用户账户），它只拥有网络请求权；所有高危操作（文件读写、进程启动、剪贴板访问）全部由一个独立的、经过严格签名的本地守护进程（daemon）代理执行。这个守护进程启动时要求用户明确授权（macOS 弹出“是否允许 Pi-Harness 控制此电脑？”），之后所有操作都在该进程上下文中完成，与 Agent 彻底隔离。这种架构下，即使 Agent 被攻破，攻击者拿到的只是一个 HTTP 客户端，它连守护进程的进程 ID 都不知道。

2.2 拒绝远程 API 方案：延迟与可靠性的致命伤

另一个常见思路，是把 Pi-Harness 做成一个部署在本地localhost:8000的 REST API 服务，Agent 通过curl http://localhost:8000/v1/clipboard/read来获取剪贴板内容。我在内网测试过，单次调用平均耗时 47ms（含 TCP 握手、HTTP 解析、JSON 序列化）。听起来很快？但实际场景中，一个典型任务链可能是：“读剪贴板 → 解析 URL → 用 Puppeteer 打开该 URL → 截图 → 保存到 Desktop → 发送截图路径给 Slack”。这 5 个步骤如果全走 HTTP，光网络开销就接近 250ms，加上每个步骤的处理时间，整个流程从“用户点击运行”到“Slack 收到消息”要等 1.2 秒以上。更糟的是，HTTP 是无状态协议，一旦中间某个请求超时（比如 Puppeteer 启动 Chrome 失败），整个链路就中断，Agent 必须从头开始重试，而重试逻辑本身又会引入新的复杂度。Pi-Harness 采用 Unix Domain Socket（macOS/Linux）或 Named Pipe（Windows）作为 IPC 通道，这是操作系统内核提供的零拷贝通信机制。实测数据显示，同一台 M2 MacBook Pro 上，Socket 通信的 P99 延迟稳定在 0.8ms 以内，且支持流式传输（streaming），Agent 可以一边生成工具调用指令，守护进程一边执行并实时回传进度（例如{"type":"progress","step":2,"total":5,"message":"正在截图..."}）。这种毫秒级响应，是构建流畅人机协作体验的物理基础。

2.3 “Harness” 与 “Agent” 的本质区别：责任边界的重新划分

网络热词里反复强调“harness 和 agent 区别”，这绝非文字游戏。我画了一张对比表，记录了我们团队在重构前后的认知转变：

这个表格背后，是我们踩过的坑：曾有一次，Agent 因pyautogui在 macOS Sonoma 上的 DPI 缩放 bug，把鼠标点到了屏幕左上角的 Dock 图标上，意外关闭了正在调试的 VS Code 窗口。那次事故后，我们彻底明确了原则——Agent 只做决策，Harness 只做执行；决策层抽象，执行层具体。Pi-Harness 的存在，本质上是在 AI 与操作系统之间，插入了一个可验证、可替换、可审计的“执行中间件”。

3. 核心实现细节：从零搭建一个跨平台的 Agent Harness

3.1 架构全景：三层解耦模型

Pi-Harness 的代码结构严格遵循“控制-传输-执行”三层分离：

• Control Layer（控制层）：一个极简的 Rust 二进制程序pi-harness，它不包含任何业务逻辑，只做三件事：1）监听 IPC 通道（Socket/Pipe）；2）解析收到的 JSON 指令；3）根据指令中的tool字段，分发给对应的 Executor。它的编译产物是一个不到 3MB 的静态链接可执行文件，无运行时依赖，下载即用。

• Transport Layer（传输层）：IPC 通道的抽象模块。在 macOS/Linux 上，使用tokio::net::UnixListener创建/tmp/pi-harness.sock；在 Windows 上，使用tokio::net::windows::named_pipe::NamedPipeServer创建\\.\pipe\pi-harness-pipe。关键设计是：所有通信强制启用 TLS 1.3 加密。你可能会问：“本地通信也要加密？”。答案是肯定的。因为 IPC 通道可能被同主机上的其他进程嗅探（如socat - UNIX-CONNECT:/tmp/pi-harness.sock），而 TLS 能确保即使通道被截获，指令内容也无法被明文读取。我们使用rustls库，证书由 Harness 启动时自动生成并存于~/.pi-harness/cert/，首次运行时向用户展示指纹并要求确认，杜绝中间人攻击。

• Executor Layer（执行层）：按工具类型划分的独立模块。目前包含 7 个核心 Executor：

  • clipboard_executor：调用 macOS 的pbpaste/ Windows 的GetClipboardData/ Linux 的xclip；
  • file_executor：封装std::fs，但增加路径白名单校验（默认只允许~/Desktop,~/Documents,~/Downloads）；
  • app_executor：macOS 用NSWorkspace.launchApplication，Windows 用ShellExecuteEx，Linux 用xdg-open；
  • screenshot_executor：macOS 用screencapture命令，Windows 用 GDI+ 截图 API，Linux 用maim；
  • shell_executor：限制为白名单命令（ls,cat,date,pwd），禁用rm,curl,wget等高危命令；
  • browser_executor：通过 Chrome DevTools Protocol (CDP) 连接本地 Chrome 实例，实现标签页控制；
  • notification_executor：调用系统原生通知 API（macOS 的osascript -e 'display notification'，Windows 的 Toast Notification API）。

这种分层让扩展变得极其简单。上周有用户提需求：“希望 Agent 能控制音乐播放”。我们只新增了一个music_executor，封装playerctl（Linux）、osascript（macOS）和PowerShell（Windows）的播放控制命令，然后在 Control Layer 的分发逻辑里加一行if tool == "play_music" { exec_music(params) }，整个功能就完成了，Agent 侧完全无感。

3.2 指令协议设计：为什么用 JSON-RPC 2.0 而不是自定义格式？

Agent 与 Harness 之间的指令，采用标准的 JSON-RPC 2.0 协议，而非简单的{ "tool": "...", "params": {...} }。这是经过三次迭代后的选择。第一版用自定义格式，第二版改用 gRPC（Protocol Buffers），第三版才定型为 JSON-RPC 2.0。原因如下：

• 调试友好性：JSON-RPC 有明确的id字段和error对象。当 Agent 发送{"jsonrpc":"2.0","method":"clipboard/read","id":123}，Harness 必须返回{"jsonrpc":"2.0","result":"https://example.com","id":123}或{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":123}。这个id让我们在日志里能 100% 匹配请求与响应，排查“指令发了但没回”这类问题时，效率提升 5 倍。而自定义格式没有这种强关联机制。

• 生态兼容性：JSON-RPC 2.0 是工业级标准，几乎所有编程语言都有成熟客户端库。我们的 Agent 是 Python 写的，用jsonrpclib-pelix；但团队里有同事用 Go 写了个轻量 Agent，直接go get github.com/ethereum/go-ethereum/rpc就能连上 Harness，零适配成本。

• 未来扩展性：JSON-RPC 2.0 支持批量请求（batch requests）。当 Agent 需要“同时读剪贴板、查当前时间、获取桌面文件列表”，它可以发送一个包含 3 个对象的数组，Harness 会原子性地执行并返回 3 个结果。这比串行调用快 2.3 倍（实测数据），且避免了中间状态不一致的问题。

以下是真实抓包的一次完整交互（已脱敏）：

// Agent 发送的请求（ID 为 456） { "jsonrpc": "2.0", "method": "file/list", "params": { "path": "~/Desktop", "max_items": 10 }, "id": 456 }

// Harness 返回的响应 { "jsonrpc": "2.0", "result": [ { "name": "report_q3.pdf", "type": "file", "size_bytes": 2457600, "modified": "2024-05-20T09:15:22Z" }, { "name": "screenshots", "type": "directory", "size_bytes": 0, "modified": "2024-05-19T14:33:01Z" } ], "id": 456 }

注意result中的modified字段是 ISO 8601 格式，而非 Unix 时间戳。这是 Harness 主动做的标准化——Agent 不需要关心各平台文件系统的时间格式差异（macOS 用NSDate，Windows 用FILETIME），Harness 统一转换。

3.3 安全沙箱实现：如何让shell_executor既可用又安全？

shell_executor是最危险也最常用的 Executor。用户总想让 Agent 执行git status或python --version，但绝不能让它执行rm -rf /。我们的方案是“白名单 + 参数过滤 + 临时目录隔离”三重防护：

1. 命令白名单：只允许以下 12 个命令：ls,cat,head,tail,wc,date,pwd,whoami,git,python,node,jq。任何其他命令（包括sh,bash,zsh）均被拒绝。白名单硬编码在shell_executor.rs中，启动时加载到内存，不读取外部配置文件，防篡改。

2. 参数过滤：对允许的命令，进一步校验参数。例如ls命令，只接受-l,-a,-h,--color=auto等安全选项；禁止ls /etc/shadow这类路径。我们用正则表达式预编译所有规则：

   // ls 命令的参数规则 let ls_args_regex = Regex::new(r"^(-l|-a|-h|--color=auto|\.|~\/(Desktop|Documents|Downloads))$").unwrap();

   如果用户传ls -la /root，Harness 直接返回{"error":{"code":-32001,"message":"Invalid argument: /root is not in allowed paths"}}。

3. 临时工作目录：每次执行 shell 命令前，Harness 会创建一个随机命名的临时目录（如/tmp/pi-harness-tmp-8a3f2b），将 Agent 指定的工作目录（params.cwd）软链接到该目录下，然后chdir进入。命令执行完毕后，该临时目录被rm -rf清理。这意味着，即使git clone下载了恶意仓库，它也只能存在于这个瞬时目录中，不会污染用户主目录。

这套机制经受住了内部红队的渗透测试。他们尝试了 37 种绕过手法（包括 Unicode 零宽空格注入、$()命令替换、..路径遍历），全部被拦截。最关键的经验是：安全不是靠“堵漏洞”，而是靠“收权限”。我们不试图判断“这个命令是否危险”，而是直接定义“只允许做什么”，把问题从“如何防住所有攻击”简化为“如何确保只做允许的事”。

4. 实操部署与日常使用：从安装到第一个自动化任务

4.1 三步极速安装（macOS / Windows / Linux 通用）

Pi-Harness 的安装设计为“零配置、零依赖、一分钟完成”。我们放弃传统的brew install或choco install，而是提供一个单文件安装脚本，它会自动检测系统、下载对应二进制、设置权限、注册开机自启。以下是真实操作记录：

第一步：下载并运行安装脚本

# macOS & Linux 用户 curl -fsSL https://get.pi-harness.dev/install.sh | sh # Windows 用户（PowerShell） Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://get.pi-harness.dev/install.ps1'))

这个脚本做了什么？它首先检查$SHELL和uname -s，确定系统类型；然后从 GitHub Releases 下载预编译的pi-harness-macos-arm64或pi-harness-windows-x64.exe；接着chmod +x（macOS/Linux）或添加到系统 PATH（Windows）；最后，它会询问是否启用开机自启——macOS 用launchd创建 plist，Windows 用schtasks创建计划任务，Linux 用 systemd user unit。整个过程无交互，除非用户明确拒绝自启。

第二步：验证 Harness 是否运行

# 查看进程 ps aux | grep pi-harness # macOS/Linux tasklist | findstr pi-harness # Windows # 检查 IPC 通道 ls -l /tmp/pi-harness.sock # macOS/Linux # 或 dir \\.\pipe\pi-harness-pipe # Windows

正常情况下，你会看到pi-harness进程在运行，且 IPC 文件存在。此时 Harness 已就绪，等待 Agent 连接。

第三步：让 Pi Coding Agent 连接到 Harness这一步取决于你的 Agent 部署方式。如果你用的是官方 Docker 镜像，只需在docker run时添加两行：

docker run -d \ --name pi-coding-agent \ -v /tmp/pi-harness.sock:/tmp/pi-harness.sock \ # 挂载 IPC 通道 -e PI_HARNESS_SOCKET=/tmp/pi-harness.sock \ # 告诉 Agent Harness 地址 -p 3000:3000 \ pi-coding/agent:latest

如果你是本地 Python 运行 Agent，则在初始化 Agent 时指定 Harness 客户端：

from pi_harness_client import PiHarnessClient harness = PiHarnessClient( socket_path="/tmp/pi-harness.sock", # macOS/Linux # pipe_name="\\\\.\\pipe\\pi-harness-pipe" # Windows ) # 在 Agent 的工具调用函数中 def call_harness_tool(tool_name, params): return harness.call(tool_name, params)

pi_harness_client是我们开源的 Python SDK，已发布到 PyPI，pip install pi-harness-client即可使用。它封装了所有底层细节：自动重连、请求超时（默认 5s）、JSON-RPC 错误映射。你不需要懂 Rust 或 IPC，只要会调用一个函数。

4.2 第一个实战任务：用 Agent 自动生成周报并发送邮件

我们用一个真实工作流来演示 Pi-Harness 的威力。场景：每周五下午，数据分析师需要从~/Documents/reports/下读取最新 CSV，用 Pandas 生成汇总图表，保存为 PNG，再用 Outlook 发送邮件。过去要手动打开 Terminal、运行脚本、切换到 Outlook 填写收件人。现在，只需对 Agent 说：“帮我生成本周销售周报并邮件给王经理”。

Agent 的决策逻辑（简化版）：

1. 调用file/list获取~/Documents/reports/下的文件，按修改时间排序，取最新一个（如sales_20240517.csv）；
2. 调用file/read读取该 CSV 内容（Harness 会自动处理编码，返回 UTF-8 字符串）；
3. Agent 在内存中用 Pandas 处理数据，生成图表；
4. 调用file/write将图表 PNG 保存到~/Desktop/weekly_report_20240517.png；
5. 调用app/open启动 Outlook；
6. 调用clipboard/write将邮件正文（含图表路径）写入剪贴板；
7. 调用shell/exec运行osascript -e 'tell application "Outlook" to make new outgoing message with properties {subject:"销售周报", content: (the clipboard as text)}'（macOS）。

关键实操心得：

• 路径处理要绝对谨慎：Harness 的file/read接口要求path参数必须是绝对路径，且以~开头会被自动展开为用户主目录。但 Agent 生成的路径如果写成../reports/sales.csv，Harness 会直接拒绝。我们强制要求所有路径在 Agent 侧用os.path.expanduser()处理，这是踩过坑后的硬性规范。
• 大文件传输要分块：CSV 文件超过 10MB 时，file/read会返回{"error":{"code":-32002,"message":"File too large"}}。解决方案是 Agent 先调用file/stat获取大小，若超限，则改用shell/exec运行head -n 1000 sales.csv流式读取前 N 行。
• 邮件客户端启动有延迟：app/open返回成功，不代表 Outlook 界面已就绪。我们增加了app/wait_for_window工具（Harness 新增），它会轮询系统窗口列表，直到找到名为 “Outlook” 的进程窗口，超时 10 秒后报错。这避免了“Outlook 还在加载，Agent 就往剪贴板写内容”的竞态问题。

这个任务从触发到邮件草稿出现在 Outlook 中，全程耗时 8.3 秒（M2 Mac）。而人工操作平均需要 2 分钟。更重要的是，它 100% 可复现——同样的输入，每次执行结果一致，没有“有时成功有时失败”的玄学问题。

4.3 日常维护与监控：如何确保 Harness 长期稳定运行？

Pi-Harness 不是“安装完就不管”的黑盒。我们内置了完整的可观测性支持，让运维变得像查看天气预报一样简单。

日志系统：Harness 启动时，会在~/.pi-harness/logs/下创建两个文件：

• access.log：记录每一次成功的工具调用，格式为2024-05-20T09:15:22Z [INFO] file/read path=~/Desktop/report.pdf duration_ms=12.4
• error.log：只记录错误，格式为2024-05-20T09:16:01Z [ERROR] clipboard/read error="Failed to open clipboard: Access denied"

我们禁用了传统 syslog，因为它的时间精度低（秒级），且难以按进程过滤。Harness 的日志自带微秒级时间戳和结构化字段，可直接用grep或jq分析。例如，统计今天剪贴板被读取了多少次：

grep "clipboard/read" ~/.pi-harness/logs/access.log | wc -l

健康检查端点：Harness 提供一个 HTTP 健康检查接口（http://localhost:8080/healthz），返回 JSON：

{ "status": "ok", "uptime_seconds": 14285, "ipc_connections": 1, "last_call_time": "2024-05-20T09:15:22Z", "disk_usage_percent": 62.3 }

你可以用任何监控工具（如 Prometheus + Grafana）抓取这个端点，绘制ipc_connections曲线。如果连接数长期为 0，说明 Agent 没连上来；如果disk_usage_percent> 90%，则触发告警——因为 Harness 的临时目录会占用磁盘空间。

紧急熔断机制：当 Harness 检测到连续 5 次shell/exec调用失败（如git命令超时），它会自动进入“熔断模式”：接下来 5 分钟内，所有shell/exec请求直接返回{"error":{"code":-32003,"message":"Shell executor temporarily disabled due to repeated failures"}}，并记录到error.log。这防止了 Agent 因逻辑错误陷入无限重试循环，拖垮整个系统。熔断时间可配置，但默认值 5 分钟是经过生产验证的——足够让运维人员登录服务器journalctl -u pi-harness查看日志，又不至于影响正常业务。

5. 常见问题与避坑指南：那些文档里不会写的血泪教训

5.1 “Harness 启动了，但 Agent 连不上” —— IPC 权限的隐形陷阱

这是新手遇到的第一道墙。现象：ps aux | grep pi-harness显示进程在运行，ls -l /tmp/pi-harness.sock显示 socket 文件存在，但 Agent 报错Connection refused或Permission denied。

根本原因与解决方案：

• macOS Gatekeeper 阻止未签名二进制：如果你是curl | sh安装，macOS 可能将pi-harness标记为“来自互联网”，首次运行时会弹窗阻止。解决方案：xattr -d com.apple.quarantine /usr/local/bin/pi-harness，然后重新启动。
• Docker 容器内无法访问宿主机 Socket：很多人把 Agent 放在 Docker 里，却忘了挂载 socket 文件。正确做法是docker run -v /tmp/pi-harness.sock:/tmp/pi-harness.sock，但要注意：socket 文件权限是srw-rw-rw- 1 root root，而容器内 Agent 进程通常以非 root 用户运行。解决方案：启动 Harness 时加参数--socket-mode 0666，或在容器内用usermod -u 0 agent-user临时提权（仅开发环境）。
• Windows Named Pipe 权限不足：Windows 的 Named Pipe 默认只允许 SYSTEM 和 Administrators 访问。普通用户运行的 Agent 无法连接。解决方案：Harness 启动时自动调用SetSecurityInfoAPI，将管道 DACL 设置为Everyone:READ|WRITE。这个逻辑在windows_pipe.rs中，但文档里没写，因为它是 Harness 内部实现细节。

提示：遇到连接问题，先运行nc -U /tmp/pi-harness.sock（macOS/Linux）或powershell "echo 'ping' | Out-File -FilePath \\\\.\\pipe\\pi-harness-pipe -Encoding ASCII"（Windows）。如果能通，说明 Harness 正常；不通，则是权限或路径问题。

5.2 “Agent 调用file/write，文件却出现在奇怪的位置” —— 路径解析的魔鬼细节

现象：Agent 传{"path":"/tmp/report.txt","content":"hello"}，但文件实际被创建在~/tmp/report.txt。

真相：Harness 的路径解析逻辑是“先尝试绝对路径，失败则 fallback 到用户主目录”。当/tmp/report.txt因权限不足（如/tmp是 noexec 挂载）无法写入时，Harness 不会报错，而是默默把路径解释为~/tmp/report.txt。这个行为是为了兼容性（很多用户习惯写相对路径），但极易引发混淆。

避坑技巧：

• 永远用file/stat预检：在file/write前，先调用file/stat检查目标路径是否存在且可写。Harness 的file/stat会返回{"exists":true,"is_writable":false,"error":"Permission denied"}，让你提前感知问题。
• 强制使用~前缀：所有路径都显式写成~/Desktop/report.txt，Harness 会 100% 展开到用户目录，杜绝歧义。
• 启用严格模式：启动 Harness 时加--strict-path参数，此时任何非~开头的路径都会被拒绝，强制规范路径写法。

5.3 “截图功能在 macOS 上偶尔黑屏” —— 系统隐私权限的动态变化

现象：Harness 的screenshot_executor在 macOS 上大部分时间正常，但重启系统或更新 macOS 后，第一次截图返回全黑图片。

根因：macOS 的 Screen Capture 权限是“按应用授予”的，而非“按进程授予”。Harness 的二进制文件每次更新（哪怕只是 patch 版本），系统都会视为“新应用”，需要重新授权。但 Harness 启动时不会主动弹窗申请，而是静默失败。

终极解决方案：

1. 手动授予权限：System Settings > Privacy & Security > Screen Recording > +，然后选择/usr/local/bin/pi-harness；
2. 自动化脚本：我们提供了一个fix-macos-permissions.sh，它会调用tccutil reset ScreenCapture重置权限，然后用 AppleScript 模拟用户点击授权弹窗（需配合 Accessibility 权限）；
3. 预防性设计：在 Harness 启动日志中，增加一行Checking ScreenCapture permission... OK或MISSING - please run 'tccutil reset ScreenCapture'，让问题暴露在第一时间。

注意：这个权限问题只影响截图和录屏，不影响文件、剪贴板等其他功能。它提醒我们：桌面自动化不是纯技术问题，更是与操作系统隐私策略的持续博弈。每次 macOS 大版本更新，我们都要花半天时间适配新 API，这是无法回避的成本。

5.4 “为什么不用现成的自动化工具，比如 AutoHotkey 或 Keyboard Maestro？”

这是被问得最多的问题。答案很直接：它们不是为 AI Agent 设计的。AutoHotkey 的脚本是静态的，你得预先写好^!s::Run, notepad.exe；而 Pi-Harness 的指令是动态生成的，Agent 可以根据上下文决定“现在该打开 Notepad 还是 VS Code”。Keyboard Maestro 的宏是 GUI 配置的，无法用 JSON API 调用。更重要的是，它们缺乏 Pi-Harness 的核心特性：

• 标准化协议：JSON-RPC 2.0 让任何语言写的 Agent 都能接入；
• 集中审计：所有操作有统一日志，而 AHK 脚本散落在各处；
• 安全沙箱：AHK 脚本拥有用户全部权限，一个Run, cmd /c del /q %USERPROFILE%\*.*就是灾难；
• 跨平台一致性：AHK 是 Windows 专属，KM 是 macOS 专属，Pi-Harness 三端统一。

所以，Pi-Harness 不是取代它们，而是为 AI 时代的新工作流，提供一个专属于“智能体-操作系统”对话的基础设施。就像 TCP/IP 不是取代电话线，而是定义了数据如何在网络中可靠传输一样。

6. 后续演进与个人体会：当 Agent 开始真正“拥有”你的电脑

Pi-Harness 当前已支撑我们团队 23 个日常自动化任务，从“自动整理下载文件夹”到“根据会议日历生成待办清单”，平均每天执行 1700+ 次工具调用。但它远未完成。接下来半年，我们聚焦三个方向：

第一，硬件级集成：让 Agent 不仅能控制软件，还能操作硬件。我们已启动与 Logitech Options+ SDK 的合作，目标是让 Agent 能识别鼠标侧键按下事件，并触发自定义动作（如“侧键长按 → 启动语音转文字”）。这需要 Harness 新增hardware/inputExecutor，直接监听 HID 设备事件。难点在于跨平台 HID API 的抽象——Windows 用 Raw Input，macOS 用 IOKit，Linux 用 evdev，但核心思路不变：Harness 做底层适配，Agent 只管消费事件。

第二，多 Agent 协同调度：当前一个 Harness 实例服务一个 Agent。未来要支持多个 Agent（如“代码 Agent”、“文案 Agent”、“数据分析 Agent”）共享同一个 Harness，由 Harness 根据工具类型和资源占用进行优先级调度。例如，当“数据分析 Agent”正在执行耗 CPU 的 Pandas 计算时，“代码 Agent”发起的shell/exec请求会被排队，避免系统卡死。这需要引入轻量级任务队列（我们倾向用tokio::sync::mpsc而非 Redis，保持零依赖）。

第三，可视化操作审计面板：目前正在开发一个基于 Tauri 的本地 Web UI，它不处理任何业务逻辑，只读取 Harness 的access.log和error.log，用 ECharts 绘制“今日工具调用 Top 10”、“各 Agent 调用成功率趋势”、“错误类型