20260904｜我如何把 Pi Agent 接进 Office/WPS 办公流程：从安装到 Excel 长任务

我最初接触 Pi Agent 时，也只是把它当成一个写代码的终端工具。真正让我觉得它适合办公，是我把一项复杂任务拆开之后发现：办公里最耗时间的部分，往往不是写一段话，而是把邮件、会议记录、网页、表格和历史文件里的信息拼起来，再按一套不够明确的规则反复处理，最后还要证明结果没有改错。 关键词：#Office #WPS #Pi 对经常使用 Office 或 WPS 的人，我更愿意把 Pi 理解成一个坐在旁边的办公助理：它不替我换掉 Word、Excel、PowerPoint 或 WPS，而是帮我在多个文件之间找信息、整理内容、生成草稿、执行低风险的重复动作。它可以在本地的“办公工作区”——也就是我专门放这项工作的文件夹——里读取资料、调用工具、保存一次连续的工作记录，并把中间结果留下来。但它不是“按一下就全自动”的魔法，也不是替我做业务判断的数字员工。

本文先把安装对象和桌面适配讲清楚，再用 Excel 月报这个长任务说明我如何让它参与办公，以及我为什么坚持把验证和最终提交留给自己。先把名字理顺：大家口中的“pi-agent”，对普通使用者来说通常指的是会安装出 pi 命令的 @earendil-works/pi-coding-agent；@earendil-works/pi-agent-core 是底层运行时库，不是新手第一步要装的客户端。下面的命令和版本判断以我在 2026 年 9 月 4 日查到的官方快速开始文档、官方仓库和相关 package 资料为准。

下面看到的黑色窗口命令，主要只在安装和整理文件时使用；装好以后，我仍然可以继续用熟悉的 Excel、Word、PPT 或 WPS 图形界面办公。对不熟悉命令行的朋友，我建议把它理解成“给办公助理下达准备工作指令”，先照着复制执行即可。

1. 先准备运行环境：当前官方仓库的 package.json声明 Node.js >=22.19.0。Node.js 是 Pi 运行所依赖的基础环境，我会先用 node --version 检查版本；低于这个版本就先升级 Node.js。旧文章里如果还写着 @mariozechner/pi-coding-agent，以当前官方文档使用的 @earendil-works/pi-coding-agent 为准。然后安装并验证：

   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
   pi --version
   

   macOS 或 Linux 也可以使用官方安装脚本 curl -fsSL https://pi.dev/install.sh | sh；Windows 则建议先安装 Git for Windows，因为 Pi 默认通过 Git Bash 执行 Bash 命令，官方也支持在设置里指定 shellPath。安装成功后，进入我准备给它工作的目录再启动：

   mkdir -p ~/办公工作区
   cd ~/办公工作区
   pi
   

2. 再配置模型身份：进入 Pi 后执行 /login，按提示选择订阅登录；或者在启动前设置 API Key。API Key 可以理解成“让 Pi 调用模型服务的授权密码”，例如 export ANTHROPIC_API_KEY=你的密钥。我建议新手第一次只做一件小事，比如让它“列出当前目录的文件，并说明每个文件可能的用途”，确认模型能回答、工具能工作，再开始交给它真实资料。Pi 默认给模型 read、write、edit、bash 四类工具，也就是说它不只是聊天，还可能读写文件、执行命令；官方明确提醒要用 Git 或其他检查点方便回滚。不要把真实 API Key 写进文章、截图、共享文档或项目目录里。 装完后我还会用 pi list 确认扩展包是否已登记，需要更新时用 pi update --extensions，卸载时用 pi remove npm:包名；如果只是想试用一次，可以用 pi -e npm:包名，避免立刻写入全局设置。

我理解的“安装桌面 package”，不是再装一个叫 Pi Desktop 的图形客户端，而是给 Pi 增加一项能力的小插件。英文资料里的 package 可以理解为“扩展包”，extension 可以理解为“扩展”；有的扩展让 Pi 处理文件，有的让它看见桌面上的窗口。若目标是 Excel，我建议先按下面的清单选择，不要全部一次性安装：

1. 必装：@earendil-works/pi-coding-agent，它提供 pi 命令和基本的会话、文件、命令能力。
2. 需要操作已打开的 Excel 窗口时再装：社区维护的 @injaneity/pi-computer-use，安装命令是 pi install npm:@injaneity/pi-computer-use；只绑定当前项目则用 pi install -l npm:@injaneity/pi-computer-use。它提供发现窗口、观察界面、搜索控件、读取文字、点击、输入、滚动和等待界面变化等能力。
3. 主要处理 .xlsx / .xlsm 文件时可选：@firstpick/pi-extension-workbook，安装命令是 pi install npm:@firstpick/pi-extension-workbook。它强调先检查、渲染、修改，再比较和验证；但当前要求 Node.js >=24，会把运行环境基线抬高，所以我不会把它当成所有人的默认依赖。
4. 需要 Python 做批量表格转换时可选：@sttronn/pi-sheets，它走 openpyxl 等工具，安装后还要按文档准备 Python >=3.10 和虚拟环境；这条路线更适合“文件进、文件出”，不适合直接控制 Excel 窗口。
5. 想把 AI 放进 Excel 侧边栏时另选：Pi for Excel 是一个实验性的 Office 加载项，不是 pi install package，要从安装页下载 manifest.prod.xml，再从 Excel 的加载项入口安装。它把工作簿结构、当前选区、单元格变化、会话和回滚放在 Excel 内，适合不想来回切换窗口的人，但它与 Pi CLI 是两种安装方式，不建议新手同时维护两套入口。

pi-agent-core、pi-ai、pi-tui 不需要新手单独安装，它们会作为 Pi 生态的依赖或开发库出现；对 Excel 长任务而言，先装“Pi 命令 + 一条 Excel 路线”就够了：要操作窗口选 pi-computer-use，要处理文件选 pi-extension-workbook 或 pi-sheets，要进 Excel 侧边栏就选 Pi for Excel。如果你平时用的是 WPS，也不用先换软件：WPS 主要通过桌面操作方式接入；如果只是处理 .xlsx 文件，则让 Pi 生成副本，再用 WPS 或 Excel 打开复核。

我会按目标选择组合，而不是把所有东西都装上：

同一台机器可以有多种组合，但我建议先选一行跑通；尤其不要因为“长任务”就默认安装循环执行 package。

为了把它和每天的办公动作对应起来，我会这样理解：

这里最重要的一点是：Pi 不是要求我放弃 Office/WPS，而是把它接在原来的办公流程旁边。我仍然可以在熟悉的 Excel 或 WPS 界面里查看结果；Pi 更擅长处理“从多处找资料、按规则批量整理、把过程记录下来”这些跨文件、跨应用的工作。

pi-computer-use 提供的是桌面操作能力，安装后重启 Pi，并在会话里执行 /computer-use 查看实际配置。macOS 需要 14 或更高版本，通常要给 ~/Applications/pi-computer-use.app 开启“辅助功能”和“屏幕录制”权限；Windows 要在已登录的交互式桌面里运行；Linux 则要在目标用户的图形会话里准备 AT-SPI2，无头环境不要想当然地认为能点桌面。我会把这个 package 当成“最后一公里”：应用有稳定 API 时优先用 API，只有必须面对屏幕上的按钮和表格时才用 computer use。 这一步尤其要慢一点，因为 Pi 官方 package 文档说明 package 和 extension 具有完整系统权限，第三方 package 可能执行任意代码；Pi 官方安全文档也明确说明项目信任不是沙箱，工作区目录不是硬权限边界。我的做法是先读源码，先用不带版本的 package 做一次小范围验证，确认后再改成带版本号的安装，并且只在专门的办公工作区里运行，降低误改其他目录的机会——这不是硬权限边界，不能代替隔离或人工确认。需要注意，网上也有名为 pi-agent-desktop、Pi Desktop 的第三方 GUI 壳，它们解决的是“用窗口操作 Pi”，不等于 Pi 官方核心，也不一定会替你安装全局 pi 命令；不要把桌面壳、Pi CLI、Excel 加载项和桌面操作 extension 当成同一个东西。

我现在不把 Pi 当成“会聊天的办公软件”，而把它当成一个运行在专门文件夹里的流程执行器。它真正能帮我省下来的，不只是打字时间，而是四个经常被低估的断点：资料散落在邮件、文件夹和网页里；同一套判断规则每周重复解释；跨应用复制粘贴容易漏项；最后结果没有清晰的核对记录。Pi 的文件读取、命令执行、扩展和会话能力，恰好可以把这四段接起来。对我来说，Pi 的办公价值可以拆成四个词：汇总信息、固化规则、执行重复动作、留下证据。 但它不是替我承担业务责任的“自动员工”：最终判断、敏感数据授权和对外提交，仍然要由我负责。

举一个更接近日常的流转：早上把会议转写和邮件附件放进工作文件夹，让 Pi 整理出结论、待办和负责人；中午把销售明细的副本交给它，生成一版带异常标记的月报；下午根据月报提炼 Word/WPS 汇报稿和 PPT/WPS 演示提纲，最后生成一封待发送的邮件。Pi 负责把信息流转起来，我负责判断内容是否正确，以及是否真的要发出去。这就是我认为它比“单独在一个软件里问问题”更有价值的地方：它参与的是一条办公链路，而不是某一个孤立动作。

我会先用四个条件判断一项办公任务值不值得交给 Pi，而不是看到“自动化”三个字就上手：

1. 输入是否已经数字化：邮件正文、会议转写、CSV、XLSX、PDF 和网页内容，比纸张或口头信息更适合交给它。
2. 规则是否可以说清楚：例如“订单号 + 明细行去重”“金额保留两位小数”“异常值单独列出”；如果规则只能靠某个人的经验临场判断，就先让 Pi 整理问题，不要让它直接执行。
3. 结果是否可以验证：总数能不能对账，公式能不能检查，文件差异能不能回读，输出格式能不能由人抽查；不可验证的自动化，我不会放进正式流程。
4. 错误是否可以回退：能否使用副本、版本、日志或会话分支恢复；付款、发邮件、提交审批、删除记录等不可逆动作，永远放在最后一步。

相反，一次性、规则模糊、涉及重大决策或无法回滚的工作，不适合直接交给 Pi。我的经验是：任务越重要，越不能只用一句“帮我做完”描述；越应该把输入、规则、产物、检查点和停止条件写出来。

我把日常办公流程固定成五个阶段，这比记住一堆花哨命令更重要：

1. 建立上下文：在工作区准备一份名为 AGENTS.md 的“办公规则说明”、模板、字段说明和敏感信息规则；让 Pi 知道“什么能读、什么不能改、输出要长什么样”。它不是程序代码，更像贴在文件夹里的长期工作须知。
2. 只读盘点：先让它列出文件、字段、表格结构、缺失项、冲突项和不确定之处，明确要求“只读，不修改”。
3. 把判断写成方案：让它先输出假设、处理规则、预计改动范围和验收方式，我确认后再执行；不让模型把猜测偷偷变成事实。
4. 分批执行：按文件、工作表、月份或客户分批处理，每一批都保存变更摘要；长任务不要依赖对话记忆，要依赖文件和会话记录。
5. 验证并交付：让 Pi 生成差异、异常和未决项，我做关键抽查，最后才复制、发送或提交。官方支持用 pi -c 继续最近会话、用 /fork 分出试验分支、用 /export 导出记录；这些能力让我可以把“继续工作”变成可追踪的过程，而不是重新描述一遍背景。详细命令见官方日常使用文档。

在这个框架下，会议纪要适合做“转写 → 结论/待办/负责人/截止时间 → 人工确认”；材料写作适合做“资料汇总 → 约束提取 → Markdown 初稿 → 人工润色”；浏览器操作适合做低风险检索、复制、录入和状态核对，但我的提示会明确写出“只观察，不提交；到最后一步停下”。真正有价值的不是让 Pi 一次性完成所有动作，而是把这些动作变成下一周还能复用的模板、规则和检查清单。

如果是第一次把 Pi 用到 Office/WPS，我会先从下面三类“看得懂、验得回、出错能撤销”的任务开始：

1. 文档整理：把三份会议记录合并成一页摘要，分出“已决定、待确认、负责人、截止时间”，不直接替我发邮件。
2. 表格核对：对销售明细副本统一日期和名称，找出重复订单、空金额和合计不一致的地方，先输出问题清单。
3. 汇报准备：根据已经确认的月报生成 Word/WPS 汇报稿和 PPT/WPS 页纲，事实必须来自表格，不擅自补充数字。

我给 Pi 的提示也会尽量使用 Office 用户熟悉的说法，而不是只说“执行自动化”：

请先读取 work/会议记录、work/销售月报.xlsx 和 work/客户名单.docx。
先不要修改文件，也不要发送邮件。
请用表格列出：资料来源、关键结论、需要我确认的地方、下一步动作。
对不确定的内容标记“待确认”，不要自行猜测。

这样写的好处是，第一次使用的人能清楚看到“读什么、产出什么、哪些事不能做”；等流程稳定后，再把这段提示和规则放进工作区，逐步减少每周重复交代的内容。

Excel 是最能体现 Pi 边界的办公场景：它同时包含结构化数据、业务规则、公式依赖和人眼才能快速发现的格式问题。下面以一个“运行半天、不能一次性拍脑袋改完”的月报任务为例：假设有 12 个月的销售明细，目标是统一日期和客户名称、去重、补齐公式、标记异常值、刷新汇总页，同时保留原有格式，并生成一份新的月报文件。我会先复制出工作副本，再安装必要包：

# 基础能力：已安装 Pi CLI 就不用重复执行
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 直接检查、修改和验证 xlsx/xlsm 文件；需要 Node.js >= 24
pi install npm:@firstpick/pi-extension-workbook

# 只有必须操作已打开的 Excel 窗口时才安装
pi install npm:@injaneity/pi-computer-use

如果我不需要操作 Excel 窗口，就删掉最后一行；如果 Node.js 只有 22.19 而不是 24，就把 @firstpick/pi-extension-workbook 换成 @sttronn/pi-sheets，再按它的文档准备 Python >=3.10。WPS 用户可以把“Excel 窗口”理解成“WPS 表格窗口”：桌面操作路线关注的是屏幕上的窗口和按钮，文件处理路线关注的是 .xlsx 文件本身；两者都要在最后用 WPS 或 Excel 打开结果检查兼容性。我会把下面这段提示词作为任务起点，先让 Pi 读规则，再让它逐回合执行：

请处理 work/销售明细-副本.xlsx，并将结果写入 work/销售月报-YYYYMMDD.xlsx。

目标：统一日期为 YYYY-MM-DD；按“订单号 + 明细行”去重；补齐缺失公式；标记金额、日期和客户名称异常；刷新汇总页；尽量保留原有格式。

硬约束：
1. 原始文件只读，任何修改只能发生在副本。
2. 先盘点工作簿和风险，再提出规则，不要直接改表。
3. 每次只处理一个工作表或一个月份；每回合结束都报告修改范围、行数变化、公式变化和异常数量。
4. 不删除工作表、不覆盖原文件、不发送邮件、不提交外部系统。
5. 每个回合把摘要写入 logs/，发现规则不明确就停下来提问。
6. 最后只给出差异摘要和待人工确认项，等我确认后再收口。

我不会直接说“把这本表整理好”，而是把长任务拆成可以暂停和验收的回合，并给每回合留下文件：

1. 回合一：只读盘点。让 Pi 输出工作簿、工作表、表头、公式区域、合并单元格、数据量和可能的敏感列，禁止写入；先保存一份 01-inventory.md。
2. 回合二：制定规则。明确日期格式、客户名映射、重复行判断、空值处理、金额小数位和异常阈值，保存成 02-rules.md，让我先确认，不让它边猜边改。
3. 回合三：分批修改。一次只处理一张表或一个月份，先写入副本，再让 Pi 回读修改范围、公式数量和行数变化；每批输出 03-change-log-月份.md。
4. 回合四：验证与回滚。检查汇总数是否与明细合计一致、公式是否出现 #REF!、行数是否异常变化、格式是否保留；验证不通过就回到上一份副本，而不是让 Pi 在错误结果上继续修。
5. 回合五：人工收口。让 Pi 生成差异摘要和待确认事项，我打开最终工作簿抽查关键客户、金额和汇总页，确认后再覆盖正式文件或发给同事。

为了判断这套流程是否真的有价值，我不会只凭“感觉快了”，而会记录四个指标：从原始资料到第一版结果的时间、人工介入次数、被发现的异常数量、最终交付前缺少证据的项目数。第一轮可以接受人工介入多一点，但第二轮开始，我希望减少的是重复解释和重复检查，而不是减少必要的审阅。这样一来，Pi 带来的收益才是可比较的：效率提升能被看见，质量问题能被定位，规则也能持续改进。

如果中途要离开电脑，我会给任务设置明确的“停机点”，用 pi -c 或会话恢复继续，而不是默认让它无人看管地运行。确实需要循环执行时可以另外研究 pi-loop-mode，安装命令是 pi install npm:pi-loop-mode，但它是为无人值守长时间运行设计的，官方页面也提醒要放在专用目录、虚拟机或容器中；对于真实财务表，我更愿意用上面的“分批 + 副本 + 验证”方式。

给读者的启示：我最后给自己的使用边界只有三条：让 Pi 负责整理、草拟、核对和执行可回退的重复动作；让我自己负责业务判断、敏感数据授权和最终发送；每一个会改变外部状态的动作都停在提交前让我看一眼。 如果只想记住一个最小流程，可以按下面的顺序开始：

1. 安装 @earendil-works/pi-coding-agent，完成 /login，用一个无关紧要的小目录验证。
2. 写一份几十行以内的 AGENTS.md，先定义办公目录、输出格式和禁止事项。
3. 只有遇到“文件和 API 都解决不了、必须操作屏幕”的任务，再安装 @injaneity/pi-computer-use，并逐项检查系统权限。
4. 日常任务遵循“读取资料 → 生成草稿 → 回读核对 → 人工提交”，把高风险的发送、付款、审批、删除永远留在最后一步。

我的结论是：Pi Agent 的价值不在于替我按下所有按钮，而在于把一堆零散的办公动作串成可复用、可观察、可暂停的流程。先用 CLI 建立信任，再用 package 补桌面能力，最后把真正重复的部分沉淀成规则，这样更容易用得久，也更不容易在一次“自动化成功”之后留下无法追回的错误。