企业官网建设流程全解析

1. 先把这个"pi"说清楚

最近这段时间，"pi"在我的开发者朋友圈里出现频率高得吓人。有人在群里晒 pi agent 自动改完一个 PR 的截图，有人讨论 pi coding agent 拆 subagent 的技巧，还有人问 oh my pi 桌面版在哪下载。我做开发十几年，第一反应是"又一个套壳工具"，但实际用了一周之后，我承认这工具确实有独到的地方。

这篇文章不讲产品发布稿里那套话，就从普通用户的角度，把 Pi 是什么、能解决什么问题、怎么上手、subagent 和 skill 怎么玩、有哪些坑，全部摊开讲一遍。你可能刚听说这个词，也可能已经在用同类工具想横向对比，这两种读者我都尽量照顾到。文章里的路径、配置和操作步骤，基于我本地实测和官方文档整理出来，不同版本之间可能有细微差别，但整体思路是通用的，换到别的 agent 工具上也能参考。

1.1 它不是一个聊天窗口，而是一个能自己动手的"实习生"

Pi 最简单的理解是：一个能自主执行任务的编码智能体。它和聊天 AI 最大的区别在于，它不只是"你问一句它答一句"，而是能自己读代码库、搜索文件、修改代码、执行命令、看测试结果，再根据结果继续迭代。你交代一个目标，它会自己走完"理解需求、查资料、动手改、自我验证、汇报结果"这一整条链路。

我用一个比喻跟朋友解释：这就像你给团队招了个实习生。你把任务交代清楚，他自己去翻资料、动手做，把成果拿给你 review。你要做的，是把需求拆到足够清楚，并且在他跑偏的时候及时喊停。这个定位决定了它的使用方式——不是问问题，而是派活。你负责判断方向，他负责执行和试错，配合得好，效率是成倍的。反过来，如果需求本身一团浆糊，那再强的 agent 也只会给你交出一团更精致的浆糊。

1.2 和 Cursor、Claude Code 这类工具相比，它的差异在哪

市面上的 AI 编程工具很多，按干活方式大体能分三类。对话式助手只给答案，不碰你的工程；IDE 内嵌 AI 在你写代码的时候补全、改文件；终端里的 agent 类工具能独立执行任务。Pi 属于第三类，但它的特点在于"多智能体"设计：你可以拆出专门的 subagent，让它们像不同岗位的工程师一样并行工作，由主 agent 做统一协调。

我按自己平时使用的体感做个直观对比：

实际体验下来，Pi 最抓我的一点不是单次代码生成质量，而是它能把一个大任务拆成若干子任务，交给不同身份的 subagent 并行处理。这种模式在处理跨模块重构、批量补测试、查历史 bug 这类"牵一发动全身"的任务时，优势特别明显。单点写代码的能力各家差距其实不大，真正比拼的是编排能力，也就是让多个角色各干各的、最后还能严丝合缝拼起来的能力。

1.3 什么人适合马上上手

我觉得下面三类人可以重点试试。第一类是日常写代码经常要跨多个文件改动的开发者，这类活儿最费神，刚好是 agent 的强项。第二类是做技术调研和落地验证的人，让 Pi 自己拉代码、跑示例、写总结，效率比手动搜索高一个量级。第三类是刚入门、还在犹豫怎么用 AI 提效的新手，桌面版带图形界面，比纯命令行友好得多。

当然，不适合的人也有：完全不懂代码、只想"一键生成整个 App"的人，大概率会被 agent 的连环追问和 review 要求劝退。原因很简单，agent 是执行者，不是许愿机。它把一大段代码交给你，你得有基本能力判断好不好、能不能跑。这部分能力决定你能不能用好它，没有捷径。

2. 五分钟上手：装桌面版、配环境、跑通第一个任务

2.1 桌面版下载与安装

先说安装。去 Pi 官网的下载页，按自己系统选安装包就行：Windows 是 exe，macOS 是 dmg（Apple Silicon 记得选 arm64 版本），Linux 一般是 tar.gz 或 AppImage。我个人建议直接到官方 release 页拿最新版，用系统包管理器装容易滞后一两个版本，而这类工具迭代非常快，版本差一个月体验可能差很多。

很多人提到的"Oh My Pi"，其实是社区做的一套配置管理脚本，类似 oh-my-zsh 之于 zsh 的关系。它能把主题、快捷键、常用参数统一管理起来，适合喜欢折腾的人。如果你只是想先用起来，默认配置完全够，不需要第一步就上这套。安装完成后首次启动会有一个初始化向导，让你选工作目录、默认模型，以及一个很关键的选项：命令自动执行权限。我的建议是第一次先把自动执行关掉，让 agent 处于"只读观察"模式，等它在你眼皮底下跑过几轮、确认不会乱来之后，再逐步放开权限。

2.2 模型配置和凭证认证

Pi 支持接入多种模型来源，包括云端的 API，也包括本地运行的模型。配置里最核心就三样东西：接口地址、模型名、凭证。下面是我本地环境里的一份配置示例：

{ "provider": "openai-compatible", "base_url": "http://127.0.0.1:11434/v1", "api_key": "sk-local-demo", "model": "qwen2.5-coder:32b", "temperature": 0.2 }

base_url 指向本地模型的兼容接口，api_key 填一个占位符就行，整个链路在本地闭环，不需要数据出本机。如果你用的是云服务商的模型，就要填真实的接口地址和 key。这里有个很容易踩的坑：key 填错时 agent 不会直接报错，而是会反复重试，表现出一堆莫名其妙的"思考"行为。所以配置完一定要先点"测试连接"，确认通了再进项目，这一步能省掉后面半小时的排查时间。

模型选择上，如果机器配置一般，优先选带 coder 后缀的小参数模型，响应快，适配 agent 场景比通用对话模型稳得多。机器好的，可以上 32B 以上级别，复杂推理能力会有肉眼可见的提升。温度参数我习惯调低到 0.2 左右，agent 任务追求确定性，温度太高容易放飞自我。

2.3 跑通第一个任务

配置完，找一个小项目试水。我建议第一个任务别太野，就拿你熟悉的仓库，让它做信息整理。例如：

pi "先读一下当前项目的 README 和 src 目录，梳理模块结构，输出一份总结"

你可以看到它先列目录，再挑文件读，最后生成总结。我第一次用的时候，最直观的感受是它真的会"拆解动作"——不是一次性吐一大段文字，而是先告诉你"我打算先看配置文件，再读入口模块"，然后一步一步执行。这个过程中你随时可以打断它，纠正方向。第一个任务跑通后，你对它的"工作节奏"就有感觉了：它更像一个需要你盯着的执行者，而不是放出去就不用管的自动机。

2.4 第一次使用必须知道的三个注意事项

这一节的内容都是我付过学费换来的，建议看一眼。第一，工作目录越小越好。别把整个 home 目录丢给它，否则它会在无关文件里浪费时间，token 消耗也快得惊人。第二，任何自动执行命令的能力，都必须在虚拟环境或容器里放开，不要把生产环境直接暴露给它，它的一次误操作可能比你手动十次还快。第三，所有改动都要有版本控制兜底，哪怕是临时实验，也先 git init 再说。做到这三点，后面再怎么折腾都不会出大乱子。

3. 进阶玩法：Subagent 编排与 Skill 导入

3.1 主智能体和子智能体到底怎么配合

Pi 的多智能体机制是它最值得玩的部分。简单说，主 agent 负责理解你的总目标、拆解计划、汇总结果；subagent 是被临时拉起来的专职角色，各自有独立的上下文窗口和工具权限。这样一个 subagent 埋头查代码的时候，另一个 subagent 已经在写测试了，互不干扰。

类比的话，主 agent 是项目经理，subagent 是不同工种的施工队，而你才是那个拍板的人。项目经理不会把所有施工队叫到一个会议室里开大会，而是分别传达任务、分别验收。这样做的最大好处是上下文隔离——每个 subagent 只需要关心自己负责的那一小块，不会因为对话太长而把前面的指令忘掉。我见过很多人抱怨"agent 用着用着就变傻"，仔细一看，全是把几百个文件的阅读全都压在同一个上下文里，不傻才怪。

3.2 一个 subagent 配置文件长什么样

subagent 在 Pi 里一般通过配置文件定义。下面是我项目里一个后端开发角色的配置，格式做了简化，字段名不同版本可能有差异，但结构思路是通用的：

--- name: backend-dev description: 负责后端模块开发、接口实现与单元测试 tools: [read, search, edit, run, test] --- 你是项目里的资深后端工程师，主要使用 Python 和 FastAPI。 工作规范： - 动手前必须先列出要改动的文件清单 - 每个接口实现后必须补测试 - 禁止修改与任务无关的模块 - 依赖不明确时，先查 requirements.txt 再决定，不要自行假定

配置里最重要的不是 role 描述写得多华丽，而是 tools 权限列表。列表越窄，越不容易出事故。比如只给它 read、search、edit 三个权限，它就没办法执行命令，自然干不了"删库"这种坏事。这是我从翻车经历里总结出来的。role 描述部分则要用具体名词和规则去约束行为，越具象越稳定，模糊的形容词反而容易让模型自由发挥。每个 subagent 干完活，你还得让它在汇报里写清楚"改了什么、为什么这么改"，方便你 review。

3.3 用 Web 控制台导入 Skill 的完整流程

Skill 的概念很好理解，就是给 agent 预装的操作手册。它把一套成熟的工作流打包成"角色设定 + 规则 + 模板"，别人写好了你可以直接导入。比如"代码评审"skill，会把评审步骤、输出格式、问题分级标准都定义好，agent 一调就能用，不用你每次重新交代一遍。

"pi web 导入 skill"这个操作我实际走了一遍，流程是这样的：启动桌面版之后，在浏览器里打开本地控制台页面，找到技能市场；搜索你需要的 skill；点导入后，它会自动同步到本地技能目录，一般放在用户目录下的.pi/skills/或者项目里的.pi/skills/；最后重启当前会话，在对话里用斜杠命令调用。不同版本的界面可能有差异，但整体流程大差不差。

一个 skill 在本地通常是一个独立目录，结构类似：

~/.pi/skills/ └── code-review/ ├── SKILL.md ├── templates/ │ └── issue-list.md └── scripts/ └── collect_changed_files.py

SKILL.md 是核心，里面定义了触发词、执行步骤和输出格式。我抄一段简化示例：

--- name: code-review description: 扫描指定范围代码，输出问题清单与优先级 --- 执行步骤： 1. 先用 git diff 获取变更文件列表 2. 逐个文件做增量评审 3. 按 严重/一般/建议 三级输出

导入第三方 skill 之前，务必看一眼 SKILL.md 里申请了哪些工具权限。尤其是带 run 权限的，等于把执行命令的能力交给了别人的脚本，风险很高。我自己只导入那些明确不含危险操作的 skill，其他一律先打开源码确认再决定。skill 是可以自己写的，把团队里反复用到的工作流沉淀成一个 skill，比口头交代靠谱得多。

3.4 什么时候拆 subagent，什么时候不拆

很多新手一上来就把所有任务都拆给 subagent，结果发现反而更慢。我的判断标准很简单：看任务粒度。改一个函数、修一个文案，主 agent 直接做就行，拆 subagent 的开销比干活本身还大。跨模块重构、批量补测试、查历史问题这类大任务才值得拆。

记住一句话：拆 subagent 不是目的，控制上下文才是目的。哪个方案能让每个智能体专注在最小范围里，就用哪个方案。有时候你看着它"不并行"，但实际上它省下的 token 和避免的冲突，比并行省的时间更有价值。

4. 实战复盘：用 Pi 从零搭一个本地问答 API

4.1 项目需求和任务拆解

光聊概念没意思，我拿一个真实小项目说下完整过程。需求很简单：做一个极简的本地 RAG（检索增强生成）问答接口。把某个目录下的一堆 Markdown 文档当成知识库，提供一个 POST 接口，用户提问题，系统先检索出最相关的片段，再交给大模型生成答案，最后返回答案和来源路径。这个项目不涉及任何外部依赖，非常适合演示 agent 的完整工作流。

这个需求被我拆成三个子任务。第一个是项目骨架初始化，包括 FastAPI 应用和依赖清单。第二个是文档索引模块，负责把 Markdown 按段落切块、向量化、存到本地向量库。第三个是问答接口，负责把检索结果和问题拼成 prompt，调用本地模型生成回答。每个子任务对应一个 subagent，最后再由主 agent 统一整合。拆解的过程本身，其实就是架构设计的过程，对 pi coding agent 说清楚这三块，它就能各自开工。

4.2 让 Pi 动手前的关键 Prompt

很多人的 agent 用不好，问题出在 prompt 太含糊。需求只写一句"帮我做个问答系统"，agent 就只能靠猜，交出来的东西大概率不是你要的。我这次给 Pi 的任务描述是这么写的：

项目：本地问答 API。 请按以下顺序执行： 1. 创建 FastAPI 项目骨架，依赖尽量少； 2. 实现 docs 目录下 Markdown 的索引与检索，使用本地向量库持久化； 3. 实现 POST /ask，接收 question，返回 answer 和 sources； 4. 最后给出运行方式和测试命令。

注意这里我做了两件事：一是给了明确的执行顺序，让它先搭骨架再填血肉；二是要求"最后给出运行方式和测试命令"，等于逼它把交付物补完整，而不是只丢一堆代码。这个技巧对提高 agent 交付质量非常有效——你要求的交付物越具体，它就越不会糊弄。如果你希望某个环节重点做，比如"检索部分性能优先"，也得在 prompt 里明确写出来，否则它只会按默认方式实现。

4.3 核心代码：从索引到问答接口

整个项目的核心代码不多，我把关键文件贴出来，你照着就能跑。先是依赖清单：

fastapi uvicorn chromadb sentence-transformers httpx

索引模块 indexer.py 负责把 Markdown 切块并写入本地向量库：

from pathlib import Path from hashlib import md5 import chromadb from sentence_transformers import SentenceTransformer encoder = SentenceTransformer("all-MiniLM-L6-v2") client = chromadb.PersistentClient(path="./data/chroma") collection = client.get_or_create_collection(name="docs") def build_index(docs_dir: Path): ids, chunks, metadatas = [], [], [] for md in docs_dir.rglob("*.md"): text = md.read_text(encoding="utf-8") for i, para in enumerate(text.strip().split("\n\n")): if not para.strip(): continue chunks.append(para) ids.append(md5(f"{md}:{i}".encode()).hexdigest()) metadatas.append({"path": str(md), "chunk": i}) collection.upsert(ids=ids, documents=chunks, metadatas=metadatas)

问答接口 main.py 这样写：

from fastapi import FastAPI from pydantic import BaseModel from indexer import collection, encoder from llm import call_llm app = FastAPI() class AskRequest(BaseModel): question: str @app.post("/ask") def ask(req: AskRequest): results = collection.query( query_embeddings=[encoder.encode(req.question).tolist()], n_results=3, ) sources = [m["path"] for m in results["metadatas"][0]] context = "\n---\n".join(results["documents"][0]) answer = call_llm(req.question, context) return {"answer": answer, "sources": sources}

最后是调用本地模型生成回答的 llm.py：

import httpx def call_llm(question: str, context: str) -> str: resp = httpx.post( "http://127.0.0.1:11434/v1/chat/completions", json={ "model": "qwen2.5:7b", "messages": [ {"role": "system", "content": "你只能根据提供的上下文回答，不要编造事实。"}, {"role": "user", "content": f"上下文：\n{context}\n\n问题：{question}"}, ], "temperature": 0.2, }, timeout=60, ) return resp.json()["choices"][0]["message"]["content"]

这个项目跑起来之后，你往 docs 里丢几篇 Markdown，再 curl 一下接口，就能看到返回里带着答案和来源文件路径。整个链路从索引到检索到生成，都在本地闭环。你也可以把向量库换成别的存储，或者把 embedding 模型换大一点的效果更好的，但整体结构不需要动。

4.4 调试与 Review 的实操心得

这个项目我让 Pi 干了大半天，过程中有几次典型的翻车，正好用来讲经验。第一次翻车在 ChromaDB 的参数上：subagent 把query_embeddings和query_texts混用了。原因是它同时参考了旧版文档和新版文档，两边 API 不一样。这种细节问题，人眼 review 一眼就能看出来，但 agent 自己很难发现，所以"review 代码"这一步绝对不能省。

第二次是测试用例的问题。它写了一个 test_main.py，但测试里真的去调模型接口，导致跑测试必须先起模型服务。我让它在测试里把 call_llm 用 monkeypatch 换掉，只验证接口逻辑和返回结构。这个改动很小，但对自动化测试的可用性是决定性的。以后每次改动都能快速回归，不用背着模型服务跑测试。

我的操作习惯是：第一步让 Pi 自己跑测试，把报错原样贴回对话，它会自己修；第二步每个 subagent 在独立分支上工作，最后统一合并，避免互相覆盖；第三步合并前我亲自读一遍 diff，不信任任何"它说没问题"的结论。这套流程走下来，项目本身不难，但它把"用 agent 干活"的正确姿势演示了一遍：目标明确、角色拆分、代码审查、测试兜底，这四步少一步都会还债。

5. 常见问题与排查实录

5.1 问题速查表

我把这段时间里遇到的高频问题整理成了一张速查表，遇到类似情况可以直接对号入座。

这些问题的根源大部分是同一个：上下文管理没做好。不是模型不行，而是你把太多垃圾信息塞给了模型。想明白这一点，排查思路就清晰了。

5.2 我踩过最疼的几个坑

第一个坑是让两个 subagent 并行改同一个文件。一个在重构接口，一个在加注释，结果后面的覆盖了前面的。从那以后我规定：公共文件只能由主 agent 改，subagent 只负责自己模块内的文件。团队协作里"文件所有权"的概念，在 agent 协作里同样成立。

第二个坑是自动审批开得太早。当时为了省事，允许它直接执行命令，结果它为了装依赖，往系统 Python 里塞了一堆包，把环境搞得一团糟。教训非常明确：所有自动执行操作必须在虚拟环境或容器里进行，并且 run 命令要加白名单。这个白名单不是用来限制 agent 的，而是用来保护你的环境的。

第三个坑是上下文里积累了太多历史包袱。同一个 session 里连续跑了好几个不相关的任务，到后面它开始把上一个任务的输出当成参考，答案越来越离谱。现在我的习惯是：一个大任务结束就开新会话，绝不拖着旧状态跑新任务。这个习惯看似浪费，实际上省下了大量排查错误的时间，属于典型的"以小换大"。

5.3 几个让体验翻倍的小技巧

关于 agent 的"行为约束"，我发现负向指令比正向指令管用得多。你告诉它"不要使用 requirements.txt 之外的库"，比"请选择合适的库"有效一百倍。因为负向指令是一个硬边界，模型更容易遵守，而正向指令给了它发挥空间，发挥就意味着可能走偏。走偏一次，浪费的时间比省下的时间还多。

第二个技巧是让 agent 先写计划书。面对复杂任务，第一轮先让它只输出实施计划，你确认了再让它动手。这一步能在早期拦截掉大量方向性错误，比事后返工省钱多了。我在第一次做这个 API 项目的时候跳过这步，结果它先写了个数据库同步逻辑，跟需求毫无关系，白白浪费了二十分钟。

第三个技巧是给 subagent 起一个具象的名字。叫"backend-dev"比叫"assistant"稳定很多。看起来是玄学，但实测下来，身份描述的颗粒度直接影响模型的行为模式——它会更倾向于表现出对应角色的专业性。名字和角色描述就是它的"人设"，人设越清楚，行为越收敛。

6. 别搞混了：此 pi 非彼 pi

写到这里必须插一段，因为"pi"这个词在技术圈里同时指好几样东西。你搜"pi"的时候，可能一半结果是 AI 编码智能体，另一半是树莓派或者控制理论。不把这些对应关系理清楚，看文章很容易对不上号。

6.1 树莓派玩家说的 Pi：Raspberry Pi 与 RP2040

热词里有一个"raspberry pi 2040 + oled 0.96"，说的是用树莓派 Pico 开发板（主控芯片是 RP2040）驱动一块 0.96 英寸 OLED 屏，屏的驱动芯片一般是 SSD1306，走 I2C 接口。这类小项目的典型玩法是几分钟点亮屏幕显示文字：

from machine import Pin, I2C import ssd1306 i2c = I2C(0, scl=Pin(1), sda=Pin(0), freq=400000) oled = ssd1306.SSD1306_I2C(128, 64, i2c) oled.text("Hello, Pico!", 0, 0) oled.show()

如果你要用 0.96 寸 OLED 显示中文，就需要加载字库或者预先取模，这是新手最容易卡住的地方。i2c 地址不对、SCL/SDA 接反，也是高频问题。这个方向跟 AI 编码智能体完全是两个圈子，但都叫 pi，说明缩写这东西在实际交流中确实容易撞车。

6.2 控制工程师说的 PI：比例积分控制器

热词里"mmc环流抑制器的pi参数"和"pll pi控制带宽fb"都是自动控制领域的内容。PI 控制的传递函数是 Kp 加上 Ki 除以 s，Kp 决定响应速度，对应带宽；Ki 负责消除稳态误差。在 MMC（模块化多电平换流器）里做环流抑制，工程上常用 PI 或 PR 控制器把内部环流压到基波附近，参数整定的基本思路是先按期望带宽定 Kp，再让 Ki 提供足够的低频增益，同时加抗积分饱和措施。

锁相环（PLL）的 PI 参数同理：带宽设得越高，锁相越快，但抗扰动能力会下降。实际调试时我一般从期望带宽的三分之一到二分之一起步，观察动态响应再微调。这类问题里说的 pi，和 AI 编码智能体没有一点关系，完全是控制工程的经典内容。

6.3 硬件工程师说的 SI/PI：信号完整性与电源完整性

在高速 PCB 设计领域，SI（Signal Integrity）和 PI（Power Integrity）合在一起简写就是 "SI/PI"。做高速电路时，叠层设计、信号回流路径、去耦电容布局、眼图质量这些话题都归在这一类。如果你刷到的是"SI/PI 仿真报告"这类内容，那大概率是硬件方向的内容，别往编码智能体上靠。很多搞硬件的老哥看到 pi 相关热搜点进去，发现讲的是 AI 写代码，也是一脸懵。

6.4 一句话判断对方说的是哪个 pi

最后给一个快速判断的口诀：

另外你搜到的"k pi"，八成是输入法把 KPI 打成了 k pi，那是绩效考核的缩写，跟这些技术方向完全无关。技术上说不上搭边，职场里倒是人人都躲不开，但那是另一个话题了。

我把这段时间的实际使用感受放在最后。最大的体会是：这类工具的真正价值不在于"替你写代码"，而在于把查资料、翻代码、跑试验、改小 bug 这类重复劳动接过去，让你能把注意力放在架构、边界和取舍上。但它跑得越快，你越需要具备快速 review 的能力。它要是写错了，你一眼看不出，那它帮你节省的时间，最后都会以别的方式赔回去。我现在的习惯是：新项目、重构任务、补测试这类低风险高重复的活，大胆交给它；生产环境的敏感改动，一律自己过一遍再上。工具在变，但"想清楚再让工具干活"这个习惯，什么时候都不过时。