企业官网建设流程全解析

最近我把主力编码助手换成了 pi，用了一周多以后，结论是：回不去了。并不是说它生成的代码比其他工具“聪明”多少，而是它把“技能沉淀”这件事做成了正经的产品功能——同一套项目规范、代码风格、踩坑记录，定义一次就能反复加载，不用每次对话都从零交代一遍。如果你是刚下载 pi desktop 不知道怎么开始，或者正纠结要不要把手头的项目迁到 pi 上，这篇把安装、技能导入、子代理配置和真实踩坑记录都串一遍，可以直接当参考手册用。

开始之前先说明：我用的版本和具体菜单路径可能和你拿到的版本有差异，但核心逻辑是通用的。文章里涉及“按常见实践补充”的地方，我会明确标注，方便你对照自己手里的版本调整。

1. Pi的定位：不是聊天机器人，是能自己动手改代码的代理

1.1 它解决的问题

传统对话式 AI 助手最大的痛点是“失忆”。你上午告诉它“这个项目错误处理统一用 Result 封装，不许抛裸异常”，下午开个新会话，它又回到默认行为；你花半小时描述项目背景，它理解了个大概，但一进到具体文件还是经常跑偏。

pi 的核心思路是把这类上下文拆成“可复用的技能包”。所谓 skill，本质就是一套结构化的指令集合：触发条件、执行规则、输入输出约定、示例代码。定义一次，项目里任何会话都能一键加载。我把它理解为把“提示词”从消耗品变成了资产——这也是我换掉旧工具的根本原因。

1.2 它和普通 AI 编程工具的本质区别

我画过一张对比表，方便理解各个工具的分工差异：

这里说的“主动执行多步任务”，指的是你可以直接给它一个目标，比如“把 login 模块的重试逻辑抽成公共函数，并补齐单测”。它会自己读相关文件、分析调用链、改代码、跑测试，然后把结果汇报给你。中间怎么拆步骤，是它自己决定的，你只需要在关键节点检查和拍板。这个体验和“你问我答”完全不是一个层级。

1.3 适合谁用

根据我这一周的实测，下面几类用户最值得上手：

• 维护老项目的人：项目里充满了历史包袱和隐性规则，skill 可以把“哪些文件不能动”“哪些接口必须走封装”这类信息固化下来，避免 AI 瞎改。
• 团队协作开发者：把团队的代码规范做成 skill，所有成员共享，AI 生成的代码天然符合约定，code review 的摩擦能少一大截。
• 多端工作流的人：一会儿在电脑前，一会儿在服务器上，pi 的三端同步让我在终端里发起一个任务，回到桌面版继续查看结果，上下文不丢。

如果你是偶尔问一句“这个函数什么意思”的轻度用户，pi 的收益不会太明显，继续用轻量工具就好。但如果你想让 AI 真正“干活”，而不是“聊天”，pi 值得花半天时间折腾。

2. 三端布局：Web、Desktop、CLI 到底怎么分工

2.1 先分清三个入口

pi 不是只有一个窗口，它有三套入口，底层的 agent 引擎是共通的：

• pi web：浏览器里跑的完整版，主打 skill 管理和跨设备会话。
• pi desktop：桌面客户端，本质是 web 版的能力包了一层本地运行时，好处是能直接感知本地文件系统，配合编辑器使用更顺手。
• pi CLI：终端里的命令行入口，适合在服务器上、或者习惯纯键盘操作时用。

网上搜“oh my pi 桌面版”，其实是社区对 pi desktop 的戏称，类似“oh my zsh”那种意思——默认配置不够顺手，社区有人出了一套增强配置脚本，把常用模型预设、快捷键、主题都调好了。我建议新手直接下载官方桌面版，先把流程跑通，再考虑社区增强包。

2.2 安装与初始化（按常见实践补充）

以桌面版为例，安装流程一般是：

1. 从官网下载对应操作系统的安装包，macOS 和 Windows 都有现成的 dmg/exe。
2. 安装完成后首次启动，会让你选择模型接入方式，常见的两种：
   • 本地模型：通过 Ollama 加载，完全离线，适合代码补全和简单重构，但大模型跑复杂任务会慢。
   • API 模式：接入云端模型服务，速度快、理解能力强，但需要配置 API Key。
3. 初始化完成后，pi 会在本地起一个服务端口，Web 端和 CLI 端都复用这个服务，所以你在桌面版登录之后，网页端不用重新认证。

这一段的精确按钮名称以你下载的版本为准，但流程骨架基本不会变。我个人的建议是先选 API 模式跑通全流程，本地模型等熟悉了再慢慢调，一上来就折腾本地模型容易消磨耐心。

2.3 三个入口的取舍经验

用了一周，我的习惯是这样的：

• 日常写代码：桌面版挂着，需要 AI 改文件时直接拖进对话，它能感知整个项目的文件结构。
• 跨设备续接：出门在外用 web 版继续白天的任务，会话记录在云端同步，回到电脑前接着聊。
• 服务器排查：SSH 到机器上直接敲 pi，快速解读日志、写脚本，不用开 GUI。

这里有个容易踩的坑：如果你同时开了三个入口操作同一个项目，注意确认它们指向的是同一个工作目录。否则会出现 web 版改的是 A 目录、桌面版看的是 B 目录的错乱。我后来固定了一个习惯——每个项目只在一个入口里跑任务，其他入口只读聊天记录。

3. Skill体系：把经验和规范变成可复用的资产

3.1 一个 skill 里到底装了什么

前面说 skill 是结构化指令，具体拆开看，一份标准的 skill 定义包含这么几块：

• name：技能名称，agent 用来识别。
• description：描述这个技能在什么情况下触发，写得越具体，agent 自动调用的准确率越高。
• instructions：核心指令，告诉 agent 该怎么做，包括约束、优先级、禁止事项。
• examples：输入输出示例，帮助 agent 理解预期行为。
• hooks（可选）：执行前后的钩子，比如“改动前必须检查 git status”“改完必须跑一遍相关测试”。

用生活类比来说，这就像给新同事写的一份“岗位说明书”：不光告诉他岗位职责（instructions），还告诉他什么情况该主动上手（description）、做得好是什么样（examples）、哪些红线不能碰（约束）。

3.2 为什么要用 skill 而不是直接写提示词

我见过很多人把 skill 理解成“高级一点的提示词”，这个理解不够准确。提示词是每次对话都要粘贴的一次性文本，而 skill 是注册在 agent 运行环境里的正式组件，有几个实打实的区别：

• 自动触发：你描述任务时，agent 会根据 description 自动匹配并加载技能，不需要手动粘贴。
• 版本管理：skill 是文件，可以放进 git 仓库，改了什么一目了然，也能回滚。
• 团队共享：一份 skill 文件发给同事，他导入之后行为完全一致，不用口头复述“你记得要那样那样做”。

3.3 手写一个 skill 的实操模板

以我写的一个“前端代码规范”skill 为例，核心结构大概是这样的：

name: frontend-style-guide description: 适用于前端项目代码评审和新增页面开发，强制遵循项目现有的 Vue3 + TypeScript 风格 instructions: | 1. 组件文件统一放在 src/components 下，按业务模块分子目录 2. 禁止在组件内部直接修改 props，所有状态变更走 emit 3. 样式一律使用 CSS Modules，禁止全局样式穿透 4. 错误提示统一使用项目封装的 ElMessage，不要直接调用原生 alert 5. 所有异步请求必须经过 src/api 下的封装函数，禁止在组件里直接写 fetch examples: - input: 帮我新增一个用户列表页面 output: 生成 components/user/UserList.vue，并补全对应的 api 封装

这里有个细节值得注意：examples 一定要写“输入-输出”对，而且输出要具体到文件路径和命名规范。我一开始只写了 instructions，结果 agent 生成的代码路径七零八落，后来补上 examples，准确率立刻上去了。原因是 agent 对“抽象规则”的理解远不如对“具体例子”的模仿。

3.4 导入 skill 的两种路径

关于热词里那个高频问题“pi web 导入 skill 怎么操作”，我实际走下来的流程有两种：

方式一：从文件导入

1. 打开 pi web，进入左侧“技能管理”面板。
2. 点击“导入”按钮，选择本地的 skill 文件（普遍支持 .md、.yaml、.json，有的也支持打包成 .zip 的 multi-skill 包）。
3. 导入后系统会做一次格式校验，字段缺失时会给出警告，补全即可。
4. 导入完成可以立即在对话里测试，输入一句匹配 description 的任务，看是否自动触发。

方式二：从 URL 导入

如果你看到社区分享的 skill 托管在 GitHub 等地方，可以直接粘贴仓库链接导入。这种方式的优势是后续可以拉取更新，缺点是依赖网络可达性，内网环境会失败。

导入后我还习惯做一步：在项目根目录放一份.pi-skills.json，声明这个项目启用了哪些技能。这样不同项目自动加载不同规则，不会出现前端项目把后端接口规范也加载进来的混乱。

4. Subagent机制：把一个大任务拆成一支“虚拟团队”

4.1 为什么需要子代理

用过一段时间 pi 之后，你会发现单个 agent 处理复杂任务时有两个瓶颈：一是上下文有限，任务一多就“忘事”；二是串行执行效率低，改完 A 文件才能改 B 文件。

pi 的 subagent 机制就是为了解决这两个问题。主 agent 收到一个复杂任务后，可以拆成多个子代理并行处理，每个子代理有独立的指令、技能和文件范围。最后主 agent 汇总各子代理的结果，做整合和冲突处理。

4.2 子代理的配置逻辑

子代理的配置主体是一份独立的指令文件，和 skill 类似，但多了两个关键字段：

• scope：限定子代理能访问的目录或文件，避免它越权改动不该碰的地方。
• delegation：决定子代理是否能继续往下派出孙代理（一般限制两层就够，多了管理不过来）。

以我实际配的一个“重构任务”为例，主任务是“把用户中心的接口调用从 axios 迁移到项目封装的 request”，我拆了两个子代理：

两个子代理并行开工，主代理在最后统一查看 diff，解决两边同时改了同一文件的冲突。整体耗时比我原来串行操作少了差不多一半。

4.3 子代理协作的注意事项

这里必须提醒几个实操中容易翻车的地方：

• 文件范围一定要限定。我第一版没配 scope，api-migrator 把 node_modules 里一个第三方库的请求代码也给“顺手”改了，导致构建直接挂掉。从那以后，所有子代理的 scope 我都按目录白名单写死。
• 冲突避免靠拆分规则。两个子代理尽量不要改同一个文件，如果一定避免不了，明确指令里写上“只改指定函数，不动文件内其他内容”。
• 子代理数量不是越多越好。我实测过，超过 3-4 个并行子代理时，主代理的汇总成本会急剧上升，冲突处理消耗的时间可能超过并行节省的时间。2-3 个是性价比最高的区间。

5. 实操走一遍：两种典型场景的完整流程

5.1 场景一：新项目从零初始化

接到一个新需求，要起一个带用户登录的后端服务。我以前的做法是自己搭框架，再让 AI 补接口；用 pi 之后整个流程反过来了。

第一步，先把项目规范写成 skill。我花十分钟写了一个 backend-go-skill，里面规定了：项目布局、ORM 使用约束、错误处理方式、接口返回格式。写完导入 pi。

第二步，在桌面版里发起任务：“基于 gin 框架初始化项目，按 backend-go-skill 的规范生成目录结构、数据库连接、用户注册登录接口。”

第三步，pi 开始自动工作。它先读取 skill，确认规范，然后生成文件、初始化 go module、拉取依赖、写接口。中间它自己发现数据库配置还缺环境变量，还主动在项目根目录生成了一份.env.example。

整个过程我做的只是最后跑一遍测试、修了两个小问题。对比之前从零手搭，至少省了两个小时。这里有个心得：skill 写得越具体，初始化生成的项目越接近你想要的样子。我第二次接新项目时直接复用同一个 skill，生成的骨架几乎不用改。

5.2 场景二：老项目排查线上 bug

线上反馈说用户导入 Excel 超过一万行就卡死。这种问题的排查链路通常很长：前端 → 接口 → 服务端解析 → 数据库写入，哪一环都可能出问题。

我把任务发给 pi，没有拆子代理，先让它自己读代码。它依次做了这些事：

1. 定位到导入接口的入口文件，顺着调用链读到解析逻辑。
2. 发现解析用的是单线程逐行处理，而且每行都触发一次数据库写入。
3. 主动跑了一个小基准测试，确认瓶颈在数据库写入次数而不是解析本身。
4. 给出修复方案：批量插入 + 限制单批 500 条。

我确认方案后，它直接改了代码，并补了针对大文件的单测。整个排查过程的中间步骤它都用对话形式汇报了，我能看到它的推理链路，这点比直接给结论更让人放心。

这类场景我最大的体会是：让 agent 先“说出”排查路径，再动手改代码。pi 默认就是这么做的，但如果你发现它直接跳到了修改步骤，可以在指令里加一句“先分析原因并列出证据，再给我修改方案，等我确认后动手”。这样能有效防止它在理解偏差的情况下乱改代码。

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

6.1 问题速查表

把这一周遇到的高频问题整理成表，基本覆盖了新手期 80% 的卡点：

6.2 避坑经验分享

经验一：先小后大，不要一上来就全量重构。我第一次让 pi 重构一个老模块，直接说“把整个模块重写”，结果它产出了 2000 多行新代码，风格倒是符合规范，但有几处业务逻辑理解错了。后来我改成先让它读代码、画调用关系、列改动计划，确认后再动手。控制每次改动的粒度，宁可多开几轮对话，也不要让它一次性大包大揽。

经验二：把“禁止事项”写进 skill 比“应该事项”更有效。我试过在 skill 里写一堆“应该使用缓存”“应该做参数校验”，agent 经常选择性忽略。但把“禁止直接修改 props”“禁止跳过错误处理”这类反向约束写进去后，违规率明显降低。可能是因为禁止项更明确、可校验，agent 更容易判断“我是不是要踩红线的”。

经验三：定期用 git 保护自己。不管工具多智能，动手改代码前先确保工作区是干净的、分支是对的。我习惯在发起任何重构类任务前敲一下git stash或确认分支名，这样即使 pi 改崩了，一条git checkout就能回到安全点。这不是不信任，而是所有 agent 工具使用的第一原则。

6.3 一个值得留意的版本差异

pi 的版本迭代很快，社区里的教程和实际功能常常有出入。比如 skill 导入入口，我一个同事用的版本是在“设置”里，我的版本是在左侧独立面板。遇到不一致时，优先在官方文档里搜“skill 管理”之类的关键词，比看第三方教程可靠。养成这个习惯，能省很多无效折腾的时间。

最后再分享一个小技巧

如果你刚开始用 pi，我建议第一个 skill 不要写复杂的业务规则，而是写“项目简介 + 目录地图 + 常用命令”。比如你的项目有特殊的构建命令、测试命令、目录命名习惯，把这些沉淀成一份 skill。这个动作看起来简单，但对后续所有会话的提效是立竿见影的——agent 接任何任务前，都会先加载这份地图，行为明显更“懂行”。

我在实际使用中还有一个心得：skill 不是一次写好的，而是边用边补的。每次发现 agent 在某个点上反复犯同样的错，就把它写进 skill 的禁止事项里；每次发现它某个操作特别符合预期，就把对应行为固化进 examples。一周下来，那个 skill 从最初的一页纸变成了我团队的事实标准文档，新同事入职都不用我口述规范了，直接导入 skill 就行。

这种“越用越顺手、越用越懂你”的积累感，是我觉得 pi 最值的地方。工具本身的代码生成能力各家差距不大，差距在谁能把经验留下来、复用出去。pi 的 skill 和 subagent 机制，算是把这条路走通了。剩下的，就交给你的项目去验证了。