企业官网建设流程全解析

先说明一件事：虽然“pi”这个关键词在热搜里还带着一大堆完全不同领域的东西（电力电子控制里的PI参数、树莓派RP2040、OLED屏幕之类），但这篇我重点聊的是Pi coding agent——最近在开发者圈子里讨论度相当高的本地优先编程助手。如果你搜“pi”是想找控制器参数整定或者嵌入式硬件玩法，本文会让你失望；但如果你是想找个能自己部署、能按项目定制工作流、又能保护代码隐私的AI编程搭档，这篇文章应该能帮你省下不少折腾时间。

Pi 本质上是一个开源的“个人编程代理”，它跟 GitHub Copilot、Cursor 那一类直接怼在IDE里的补全工具不同，它更像是一个能理解项目上下文、能调用工具、能自主规划执行多步骤任务的“影子工程师”。项目完全自托管，你的代码不会出本机，模型可以接本地Ollama，也可以接各家大模型API。适合谁？适合对代码隐私敏感的自由开发者、想折腾自动化工作流的技术爱好者、以及想用最低成本体验“AI写代码到底能写到什么程度”的人群。

下面内容全部来自我这段时间从零开始搭 Pi、写技能、调子代理、翻车再救回来的实操记录。不是官方文档复读，是踩过坑之后觉得应该写下来的东西。

1. 整体构思：Pi 和其他编码助手到底差在哪

1.1 先搞清楚 Pi 的运行逻辑

Pi 的核心架构其实不复杂，本质上是一个“调度中枢”：它接收你的自然语言指令，结合项目里的上下文文件，调用底层的大模型做推理，再通过工具（读取文件、搜索代码、执行命令等）去操作实际代码库，最后把结果汇报给你。

但它跟“对话式补全”工具有一个根本区别：Pi 是拿整个项目当上下文，而不只是拿你当前打开的文件夹当上下文。它启动时会读取你项目里的AGENTS.md、各种技能文件（skills）、以及子代理（subagents）定义，先构建出一个“项目认知地图”，再开始干活。这意味着第一次接入的项目越规范，Pi 的表现就越接近一个真正熟悉你代码库的老同事。

我自己在体验的时候，最大的感受是：Pi 不急着回答，它先去看代码。你说“帮我查一下登录模块为什么在并发下会偶发500”，它不是泛泛给出几个猜测，而是会搜索代码里 session 相关的逻辑、查中间件、找锁的用法，再给出带代码定位的回答。这种“先调研再回答”的路径，才是它喊出“coding agent”而不是“coding assistant”的底气。

1.2 本地优先和“代码不出库”的取舍

Pi 卖点里最吸引我的一点就是“self-host，数据不出本机”。现在主流的编码助手都是云端服务，代码片段、项目结构、甚至注释都会被送上去做模型推理。对个人开发者来说可能无所谓，但我接触过不少做内部工具、金融系统、甚至游戏脚本的朋友，公司对代码外发是零容忍的。Pi 的本地部署方案直接解决了这个顾虑：模型跑在本地（Ollama），代码也只在本地被处理。

代价也很明显——本地模型的效果和云端一线模型还有差距。我自己在普通消费级显卡上试过跑 7B 级别的模型，做简单重构和代码解释还过得去，但要让它完全自主地完成跨文件的多步改动，连续性和准确度还是不够稳。所以我的建议是：日常开发可以用云端API来获得最佳体验，涉及敏感项目再切本地模型，两边都配好配置切换即可。这也是 Pi 做得比很多同类工具聪明的地方，它不逼你做单选，接入层是开放的。

1.3 配置文件和技能体系的威力

Pi 还有一个被很多人低估的设计，就是“项目即配置”的理念。它支持项目根目录放AGENTS.md，这其实借鉴了 Agent 模式里的一个成熟做法：把一个项目的背景、构建方式、代码风格、常见雷区全部用 Markdown 文档化。Pi 每次启动后会自动读取这个文件，把它当成“入职培训手册”。

再配合skills目录下挂载的技能文件，你等于在给 Pi 安装“专业资格证”。比如我写了个专门处理日志脱敏的技能，以后只要我提“处理这些日志”，Pi 就自动知道要去识别 IP、邮箱、身份证号，然后打码输出。这套东西叠加起来的效果是：同样是面对一个陌生仓库，别人的 Pi 像刚入职的实习生，你的 Pi 像干过同类项目三年的外包骨干。

2. 核心细节：安装、配置、技能和子代理的关键要点

2.1 安装环境选择和配置流程

Pi 官方提供了好几种安装方式，我这里直接说结论：日常使用推荐 Desktop 版本，喜欢终端操作的就用 CLI 版本。Desktop 说白了就是把聊天界面、文件浏览、Agent 状态可视化做成了本地 Web 应用，对新手友好很多；CLI 则适合我这种习惯了终端里一格一格跑日志的老家伙。

在开始安装之前，有几样东西要提前确认好：

安装命令其实不复杂：

# 以 CLI 安装为例（不同系统略有差异，请以官方文档为准） curl -LsSf https://astral.sh/uv/install.sh | sh pip install pi-code-agent

这里有个值得说的细节：官方现在推荐用uv做 Python 包管理，而不是传统的pip。原因很简单，uv快得不是一点半点，而且依赖解析更干净。我第一次直接用pip install也装上了，但后续卸载重装、升级版本的时候各种残留依赖把我整烦了，换uv之后清爽很多。

装完以后第一件事不是急着打开，而是配置模型。如果你用 Ollama 做本地推理：

ollama pull qwen2.5-coder:14b pi configure --model ollama/qwen2.5-coder:14b

用云端模型的话，直接把 API Key 填进配置，例如：

pi configure --provider anthropic --model claude-sonnet

这里给个忠告：别迷信大参数量模型就一定好。本地跑 70B 模型，如果显存不够会退化成极慢的 CPU 推理，一个简单问题能卡好几分钟，体验远不如 14B 模型配一个合理的上下文窗口。我的经验是，本地日常用 14B 级别的 coder 类模型，速度和质量的平衡点最好；测试阶段先用 7B 跑通流程，确认技能和配置正确了，再切到更大的模型。

2.2 AGENTS.md 的正确写法

AGENTS.md 是 Pi 的“项目宪法”，它告诉 agent 这项目是什么、怎么跑、有什么约定。这可能是所有配置里投入产出比最高的一项，但大部分人第一次用的时候都写得过于抽象。

我一开始犯的错误是写了一堆空话，比如“请编写高质量的代码”“请注意代码规范”这种。模型看了跟没看一样。后来我改成了一种更实用的结构：

# 项目：内部工单系统（FastAPI + SQLite + Jinja2） ## 指令 - 优先阅读 README.md 和 docs/architecture.md 后再修改代码 - 所有数据库操作必须走 repository 层，禁止直接裸写 SQL - 新增接口需要补 pytest 测试，覆盖率不低于 80% ## 构建与运行 - 启动服务：uvicorn app.main:app --reload --port 8000 - 跑测试：pytest tests/ -v - lint：ruff check . ## 常见误区和雷区 - 不要把业务逻辑写在路由装饰器函数里 - SQLite 并发写入会锁库，批量更新必须分批处理 - 修改模型字段后需要运行 alembic 生成迁移文件，不能直接改了模型就完事 ## 代码风格 - 类型标注必须完整，禁止使用 Any 糊弄 - 注释只写“为什么”，不写“做了什么”

改动之后，Pi 的输出质量提升非常明显。原因是AGENTS.md不只是给 Pi 看的一句话提示，它相当于把项目的隐式知识和团队规范变成了显式文档。模型在推理的每一步都会参考这份“手册”，相当于凭空多了一个熟悉业务的把关人。

写AGENTS.md的几个核心原则：一是按“先看什么、后做什么”排列，把指令的优先级写出来；二是使用祈使句，帮助模型理解是约束还是建议；三是不要超过 100 行，太长模型会抓不住重点。你甚至可以放一份AGENTS.md在用户目录下作为全局默认配置，再在具体项目里用项目级配置覆盖它，两层配合效率很高。

2.3 技能（Skills）的挂载和编写入门

Pi 的技能系统是这个项目里最有潜力也最少人用明白的功能。说白了就是给 agent 预装一套“操作手册”，让它遇到某类任务时知道按什么流程走、用哪些工具、注意哪些细节。

一个完整技能大概长这样：

--- name: log-sanitizer description: 对日志文件进行脱敏处理，识别 IP、邮箱、手机号并替换为占位符 version: 1.0.0 --- # 日志脱敏执行步骤 1. 使用 `grep` 或 Python 脚本扫描目标文件。 2. 正则匹配 IP 地址、邮箱、手机号。 3. 按类型替换：IP -> [IP]，邮箱 -> [EMAIL]，手机号 -> [PHONE]。 4. 保留文件目录结构，输出到 `cleaned/` 目录。 5. 输出统计：各类型替换数量。

写完以后放到项目的.pi/skills/log-sanitizer.md或者用户级技能目录里，在对话里提到“日志脱敏”“清洗日志”时，Pi 就会自动加载这个技能再执行。

我开发这个技能时踩过一个很典型的坑：第一次版本没有在第 5 步加上“输出统计”，结果 agent 处理完文件后就跟没事人一样，也不汇报处理了多少条数据，我根本没法验证它到底做没做对。加了一步强制统计输出之后，每次都能看到“IP 替换 37 处、邮箱替换 12 处”这类结果，可验证性一下子起来了。

写技能的思路，要把它理解成“给一个人的流程文档”，而不是“给 API 写的调用参数说明”。用自然语言讲清楚步骤、用到什么工具、判断条件是什么。技能文件和AGENTS.md的区别在于：后者是项目级的全局约束，前者是任务级的局部流程。

2.4 子代理（Subagents）的划分策略

Pi 的另一个进阶玩法是“子代理”。你可以把一个大任务拆成几个角色，比如代码审查代理、测试编写代理、文档生成代理，Pi 会按情况自动把任务委派给更专业的子代理来执行。

我的划分策略其实很朴素：按“职责边界”而不是“技术栈”来切。比如我给这个项目做了两个子代理，一个叫reviewer，专门做代码评审；另一个叫docs-bot，专门梳理接口文档。reviewer 的 prompt 里我强调“只关注逻辑正确性、安全性和性能隐患，不纠结代码风格”；docs-bot 的 prompt 里则要求“读取源码后先更新 OpenAI 格式的 API 文档，再更新 README 中的示例”。这样切的好处是，职责互不重叠，模型在子代理里的行为也更稳定。

子代理的定义文件里有一个很重要的字段：tools。你给子代理开放了什么工具，它就有什么样的能力边界。我这里会刻意收紧权限，比如只允许 reviewer 读取文件和执行测试命令，不允许它修改代码；docs-bot 只允许读取和写 Markdown 文件，不允许它动源码。这种“最小权限”思路能有效防止代理在一个任务里跑偏了胡乱改代码。

配置子代理需要做的工作单位不大，但收益非常实。原本一个“帮我加个功能顺便更新文档”的大任务，如果让同一个代理串行做，它很容易做了功能忘了文档；拆成两个角色后，Pi 的调度逻辑会自然地在合适时机把文档任务分配出去，产出结构更像一个真实团队的分工结果。

3. 实操过程：从零搭一个可用的 Pi 工作环境

3.1 桌面版与 Web 界面的启动流程

我选择的是桌面版（Desktop）来承担大部分日常操作，装好之后启动流程很简单：

pi desktop

或者如果你更习惯在 Web 端操作，可以先启动服务再打开浏览器：

pi web

第一次打开界面的时候，它让我选择“导入技能”还是“创建空项目”。我选择导入了一个我之前写好的日志脱敏技能，然后在“目标文件路径”里填了一个真实项目的日志目录。整个过程比我预想的顺滑：Pi 先扫描了目录，读了几行日志样例，然后问我“是否确认敏感字段格式与技能中描述一致”。这种交互方式让我觉得它真的在“理解任务”，而不是机械地跑一个正则。

如果你是新手，我建议第一个任务不要选择太复杂的重构，而是找一个“可验证、收益快”的小任务。比如“给这个 Python 脚本加上命令行参数解析”“为这几个 API 补充单元测试”，这类任务模型完成度高，你也能很快判断配置是否正常。

3.2 给别人项目的 AGENTS.md 做一次“体检”

写入配置以后，我发现一个很有意思的应用场景：把 Pi 当成“项目体检工具”。具体做法是，在任意仓库根目录先让它分析一遍代码结构和依赖关系，然后基于分析结果生成一份初始的AGENTS.md。

这个功能对接手老项目的人特别实用。我们团队接手的早期项目，文档基本上属于“前人写过，但是没人更新”的状态。我用 Pi 打开那个老项目，它花了大概一分钟读代码，生成了一份基础架构说明。虽然里面有一些它推测出来的信息有误，但整体框架是可用的。我再基于这份草稿修正补充，最终得到一份比原来完善得多的项目说明文档。

这个操作本身也印证了 Pi 整体设计的核心理念：让代理先读代码、再形成认知、然后输出成果，而不是仗着大模型的“常识”上来就动手。这一个好习惯的养成，能让它的输出质量提升一整个级别。

3.3 用 Skill 自动化一个真实任务（日志脱敏案例）

为了不让这篇博客停留在“看起来很好用但实际没试过”的层面，我把前面那个日志脱敏技能真正的使用流程完整跑了一遍。

场景：一个 Python 服务的日志文件app.log，里面混着用户 IP、邮箱和手机号。需求是生成一份脱敏后的日志，同时保留时间字段用于后续分析。

我向 Pi 发出的指令是：

运行日志脱敏技能，处理/tmp/app.log，统计各类字段替换的数量。

Pi 先是识别到技能文件，读取了技能里的步骤说明，然后用 Python 脚本扫描日志，执行正则替换，最后输出结果统计：

IP 替换：42 处 邮箱替换：7 处 手机号替换：3 处 输出文件：/tmp/app_cleaned.log

整个过程大概 30 秒。比起以前我手动写 Python 脚本处理，快得不是一点半点。而更重要的是：这类任务现在不需要每次重新描述具体的脱敏规则，技能文件里存好以后，一句话就能复用。哪天真要加一种新的敏感字段（比如银行卡号），只需要改技能文件里的一行正则定义，所有项目都能生效。

3.4 配置过程中必须注意的几个原则

配置 Pi 时我总结出了几条原则，虽然不是官方文档里的内容，但实操中非常关键：

第一，上下文长度要用在刀刃上。不要把一个巨大的代码文件整段贴给模型。我试过让 Pi 分析一个 3000 行的大模块，结果它读到一半就开始“失忆”，后续回答的质量明显下降。后来我的做法是：先让 Pi 用grep或rg定位关键函数，只读相关片段。这既省 token 又更准确。

第二，大任务要拆成小步骤。不要图省事一句“帮我重构整个模块的架构”，这超出了当前模型能稳定处理的规模。我一般会让 Pi 先出重构方案，我再逐个阶段让它实施。这个过程中“评审步骤”不能省，必须让它自己跑一遍测试再汇报。自动化流程的优势在于稳定，劣势在于如果你不给它检查关卡，它往往会过于自信地给出“感觉没问题”的回答。

第三，记得用版本控制兜底。Pi 虽然本身也会谨慎操作，但作为 agent 它依然可能做出你没想到的文件改动。接入 Git 以后，我在让它做任何批量修改前都会先确认工作区状态干净，这样万一翻车也能轻松回滚。我吃过一次亏：让 Pi 批量重命名了一批工具函数，它光改源码没改 import 引用，项目直接全部报错，还好有 Git 兜底才能很快恢复。

4. 常见问题与排查技巧实录

4.1 模型连接失败与推理速度异常

最典型的问题是启动后 Pi 一直报“model not found”或“connection refused”。这个问题 80% 的情况是配置文件中模型名写错或者服务没启动。用 Ollama 的话，先跑一下：

ollama list

确认你拉取的那个模型真实存在，再看服务是否在运行：

ollama serve

另一个高频问题是模型推理速度奇慢无比。如果你用的是本地模型，先检查显存占用。ollama ps能直接显示当前加载模型的计算设备（GPU/CPU）。如果模型被加载到 CPU，基本就说明显存不够，要么换小模型，要么调低上下文长度。我自己的经验是：num_ctx默认值经常偏大，手动设成 8192 或 4096 对速度改善明显，且对大多数代码任务的准确度影响不大。

4.2 技能没有生效的排查步骤

技能系统偶尔会出“文件放对了位置但 agent 就是没反应”的尴尬。排查顺序很重要：

第一步，确认技能文件放到了正确目录。用户级技能目录与项目级技能目录是并存的，项目里放的位置不对，它就不会被加载。

第二步，检查文件头部有没有 YAML front-matter。缺失name和description字段，技能文件会被 Pi 视为普通文档而不是“可触发技能”。这是最容易踩的坑。

第三步，确认对话里触发词是否覆盖。Pi 的技能触发逻辑高度依赖描述文本的匹配，你如果技能描述里没有“日志”相关词语，对话里说“帮我清洗一下 runtime 日志”就触发不了。把触发词写得自然、覆盖多一点，是使用体验提升最大的技巧。

4.3 子代理行为的边界控制

子代理用久了以后，我发现最大的问题不是“它做不来”，而是“它做了超出你预期的事”。有时候我让它审查代码，它会顺手修掉一个小问题；站在该子代理的角度这没什么，但站在整个项目的角度，这属于未授权变更。

我最后的解法是双管齐下：一是在子代理定义里明确写下“禁止任何未明确要求的代码修改”；二是在工具权限上做约束，reviewer 只给read和run tests的权限，不给write。这两个措施合起来，基本杜绝了乱改代码的现象。如果你想重复我的验证，可以在对话里问它“帮我审查 utils.py”，然后观察它有没有动文件内容。

4.4 快速故障速查表

为了方便排查，我整理了一张小表，都是我实际撞过的问题：

4.5 关于“性能优化”的一点心得

最后说一下大家都关心的“性能”问题。想提升 Pi 的实际表现，与其盲目换大模型，不如先把三件事做好：项目AGENTS.md写具体、技能文件按真实任务沉淀、子代理按角色拆分并用工具权限约束。这三件事对所有模型都有效果，属于“配置红利”。

我测试过一个很有意思的对照组：同一个项目，一份只有简单提示词的配置，另一份带完整 AGENTS.md 和两个 skill 的配置。用同一个模型跑同一个改功能任务，后者的第一次通过率高了不少，中途返工次数明显减少。工具的先进程度固然重要，但决定天花板的是你怎么用它。

另外一个经验是“让 Pi 自己总结自己的用法”。每次完成一个复杂任务后，我会让它总结一份“本次任务中使用了哪些技能和子代理、哪些步骤可以沉淀为技能文件”，然后用这份总结反过来补充配置。等于让 Pi 参与进化自己的操作手册，几轮下来，整个环境会越来越贴合你的实际开发节奏。有朋友问我为什么用了几周后 Pi 好像“变聪明了”，其实不是模型变了，是配置长出来了。