在实际开发中真正难的不是“学会某个工具”而是“知道自己该用什么工具以及怎么把它排进自己的工作流”。这一期内容来自个人自用 Pi 扩展和 AI 编程工具的实践总结我把它拆成两条线一条是Pi Agent 如何辅助生成一个 HTML 名片网页另一条是配合日常编码、网页调试、内容抓取用得上的插件清单。文章不会面面俱到只写自己真正用过、能跑通、能解释清楚的方案。“不太负责任”的意思不是说推荐得随意而是这些选择高度个人化版本变化又快落地前一定要结合自己的环境和版本重新确认。适合阅读这篇文章的读者有三类第一次听说 Pi、Pi Agent、oh-my-pi 这些名字但不知道它们能干什么的新手。手头已经装着 VS Code、Chrome想优化自己编码和网页制作工作流的开发者。想快速生成一个有介绍卡片、链接聚合、响应式布局的个人名片页又不想从零手写全部 CSS 和交互逻辑的同学。这份教程的目标很明确用 Pi Agent 的自然语言描述生成一个能本地打开、能发布到静态托管平台的名片网页同时把过程中我实际使用的插件筛选逻辑和排查路径讲清楚。1. 先分清“Pi 插件”到底指什么工具链、扩展和生态名很多人看到“Pi 插件推荐”会以为是一个具体软件里的插件市场。实际上在 2025 年左右的开发者语境里Pi 相关词汇至少包含三个层面。1.1 Pi 作为 AI 编程代理Pi Agent 和它周边的工具Pi Agent 是一个以“代理”形式工作的 AI 编程助手。和普通代码补全插件不同它不只是在你输入时补全代码而是可以接收一个任务描述自己规划步骤、创建文件、执行命令、运行检查、返回修改结果。它的核心价值在“代理”两个字你定义目标和边界它在项目里帮你完成一部分可自动化的开发动作。在常见用法中Pi Agent 会根据任务描述创建项目目录和初始文件。生成 HTML、CSS、JavaScript 代码并调用系统命令验证语法。读取项目文件内容后做增量修改而不是反复生成整份文档。配合 Web 端和本地 CLI 共存的模式让用户可以在浏览器里查看项目状态。Pi Agent 的安装和使用方式在不同平台有差异。官方站点通常提供 CLI 安装包也可能提供网页版入口。安装前要确认 Node.js 或系统包管理器的版本因为这类工具对运行时有明确要求。一些第三方脚本或插件会以oh-my-pi之类的名字封装新的命令实际上是把常用配置和别名集中管理。这里先提醒一句不要看到一个命令就本机执行。凡是安装类命令建议先查看脚本内容确认它安装了哪些依赖、修改了哪些配置文件再决定是否运行。1.2 Pi 相关的 VS Code 编辑器和浏览器插件在制作网页的过程中VS Code 插件和浏览器插件解决的是另外两类不同问题。VS Code 插件解决的是“写代码和改代码时的效率问题”例如HTML 标签自动闭合。CSS 类名智能提示。内置浏览器预览。AI 代码生成和聊天式修改。代码格式化、Git 操作增强、Markdown 预览增强。浏览器插件解决的是“看网页和采素材时的效率问题”例如网页整页截图。页面结构调整、临时修改 CSS 观察效果。翻译插件方便阅读外文技术资料。图片和视频资源嗅探方便拿到网页中引用的静态资源。制作名片网页时很多同学会把注意力放在写代码本身却忽略了工作流里的另一个重要环节如何观察页面效果、如何获取参考素材、如何快速验证不同浏览器下的表现。这些正是浏览器插件和 VS Code 插件擅长的部分。1.3 不要混淆Pi 还有其它含义Pi 也可以指树莓派Raspberry Pi和数学常数 π。在搜索“Pi插件”时会出现大量树莓派相关教程也会出现和金融、数字货币相关的词汇。在技术博客里写“PI”插件推荐核心场景应当是开发工具链。为避免歧义文中所有 Pi 默认指代 AI 编程代理生态里的工具如果涉及树莓派会特别说明。2. 制作名片网页的核心思路用自然语言拆需求交给 Pi Agent 生成基础代码如果以前没有做过 HTML 网页可以先理解一个基本事实现代前端开发已经不再是“必须手写每一行标签和样式”的时代而是“你能清楚描述需求和约束工具帮你生成并维护代码”的时代。但“描述清楚”这件事本身依然需要学习和练习。2.1 先把名片网页的需求拆成可描述的模块在接触 Pi Agent 之前先在纸上列出名片网页需要包含的模块。个人名片页通常包括头像或品牌标识区域。姓名、头衔、简短介绍。联系方式和社交链接。项目作品或代表经历列表。页脚版权信息。继续细化还要考虑风格和体验层面的需求页面是否要适配手机屏幕。配色想走浅色、深色还是跟随系统。是否需要动画效果例如滚动出现、悬停变化。是否希望引入第三方字体图标库。这些描述最终会成为 Pi Agent 的输入提示词。提示词越清楚生成的代码越接近目标提示词越模糊生成的页面就越“通用”最后还是要手动改。一个可用的提示词示例帮我在当前目录生成一个个人名片网页 index.html。 要求 1. 卡片式布局居中显示卡片宽度不超过 420px。 2. 包含头像图片位置当前可以使用 https://example.com/avatar.png 占位。 3. 头部显示姓名、一句话介绍。 4. 中部是我的代表项目区域至少三个条目使用列表展示。 5. 底部是社交链接区包括 GitHub、邮件、掘金。 6. 整体浅色风格圆角卡片阴影不要太重。 7. 适配移动端viewport 设置正确。 8. 只生成一个 html 文件CSS 使用内部样式JS 只做链接点击统计占位。这个提示词包含了输出格式的约束也给出了布局、样式、模块和文件数量要求。Pi Agent 可以根据这段描述直接生成一个可预览页面。2.2 Pi Agent 安装与首次运行的最小流程不同版本的 Pi Agent 安装方式差异较大。比较常见的流程是# 检查 Node.js 版本最好 18 或以上 node -v # 通过 npm 安装 pi-agent 命令行工具具体包名以官方文档为准 npm install -g pi-agent # 查看命令帮助 pi-agent --help # 在项目目录初始化 pi-agent init执行pi-agent init时工具可能会询问项目类型比如是否使用前端框架、是否使用 TypeScript、CSS 预处理方式等。制作一个纯 HTML 名片页不需要选择框架选择普通 HTML 项目即可。如果安装过程出现权限错误通常是因为全局安装目录没有写入权限。可以检查 npm 的前缀路径或者使用nvm管理 Node.js 版本避免直接使用 sudo 修改全局目录。初始化完成后可以运行pi-agent run 你的需求描述如果命令行不支持直接把长文本当作参数传入也可以先创建task.md文件再把需求描述写入然后通过pi-agent run --file task.md这类参数指定任务文件。具体参数名以当前版本帮助输出为准。2.3 生成后的本地验证方式生成结果后不要急着打开文件。先用编辑器或命令行确认目录结构是否正常ls -la预期能看到index.html和可能的任务文件。接下来本地预览 HTML 页面最方便的方式之一是启动一个简单的静态服务器# Python 3 自带模块 python3 -m http.server 8080也可以使用 VS Code 的 Live Server 插件右键index.html选择 Open with Live Server。浏览器访问http://localhost:8080就能看到页面。这里有一个新手经常踩的坑直接双击本地 HTML 文件打开页面上能看到内容但某些资源加载会失败。如果网页里没有访问本地其它文件双击打开通常没问题一旦引入了外部模块或使用了某些浏览器 API就需要通过 HTTP 服务访问。注意学习阶段用 Python 的http.server足够生产环境部署时不要使用它它没有安全配置和生产级并发能力。3. 手把手跑通用 Pi Agent 生成可上线名片页并补齐工程细节这一节给出一个从零到可发布的完整案例。假设目录名为my-card最终产物是单文件index.html不依赖构建工具。3.1 创建项目并准备任务描述打开终端执行mkdir my-card cd my-card创建工作目录的目的是把网页相关文件隔离在一个独立目录里避免 Pi Agent 扫描或修改到其它项目文件。接下来在目录中创建task.md内容按 2.1 中的提示词示例补充即可。这里再给一个带更多细节的完整描述项目个人名片页 输出文件index.html 要求 1. 单文件页面CSS 写在 style 标签里JavaScript 写在 script 标签里。 2. 页面背景使用浅灰 #f5f5f5卡片背景白色主文字色 #222。 3. 卡片内包含头像占位区域尺寸 96x96圆形背景色 #e0e0e0。 4. 姓名和头衔居中介绍不超过 40 字。 5. 项目列表三项每项包含标题和一句话说明。 6. 链接区包含 GitHub、邮箱、博客使用文本链接即可不要求图标库。 7. 底部版权信息固定写法© 2025 Your Name。 8. 页面必须设置 viewport支持移动端访问。 9. 整页高度不需要强制等于视口高度卡片垂直居中即可。任务文件的好处是方便反复迭代。如果对生成结果不满意可以修改任务文件后再执行而不是重新输入一长串命令。3.2 执行生成并检查输出在my-card目录下运行pi-agent run --file task.md运行过程中Pi Agent 可能打印规划步骤例如计划 1. 创建 index.html 2. 填充基础 HTML 结构 3. 编写内部 CSS 样式 4. 添加交互脚本 5. 检查文件内容这些日志不是噪音而是用来理解“代理”工作方式的窗口。代理并不是一次性生成最终结果而是按步骤逐步完成。生成后查看文件内容cat index.html确认以下几点!DOCTYPE html是否位于第一行。head中是否包含meta nameviewport。CSS 是否存在明显语法问题例如花括号是否闭合。文本链接的href是否为占位地址或空链接。这里要说明一点AI 生成代码后审查环节不能省略。即使生成结果能打开也要检查内容、样式和脚本是否符合预期。工具帮你写代码但你要为最终上线内容负责。3.3 手动修改图片占位、链接地址和版权信息Pi Agent 只能依据提示词工作它不知道你的真实 GitHub 地址、邮箱和项目链接。生成后需要手动替换。打开index.html找到头像区域把占位图片替换成自己的头像。如果没有头像可以使用正规的占位图服务例如img srchttps://pic.example.com/avatar.jpg alt个人头像 width96 height96 styleborder-radius: 50%; object-fit: cover;不建议在正式页面使用不可控的临时链接。生产页面中的图片建议放到自己的服务器或对象存储上避免第三方服务失效导致页面破图。链接区修改为真实地址a hrefhttps://github.com/yourname target_blank relnoopener noreferrerGitHub/a a hrefmailto:yournameexample.comEmail/a a hrefhttps://yourblog.com target_blank relnoopener noreferrerBlog/a外链加target_blank时必须同时加relnoopener noreferrer否则新页面可以通过window.opener反向操作原页面存在安全风险。这一点即使写得少也必须记住。版权信息改为自己的名字或品牌名年份按实际年份填写。3.4 本地预览与响应式验证在项目目录启动静态服务python3 -m http.server 8080浏览器访问http://localhost:8080。验证响应式布局时打开开发者工具按 F12使用设备工具栏切换手机尺寸。重点检查卡片是否溢出屏幕。文字是否换行良好。链接区是否挤在一行导致点击区域过小。图片是否变形。如果发现问题可以手动修改 CSS。例如针对移动端body { padding: 16px; } .card { width: 100%; max-width: 420px; margin: 0 auto; } .links { display: flex; flex-wrap: wrap; gap: 8px; }flex-wrap: wrap的作用是允许链接在窄屏上换行避免横向溢出。3.5 部署到静态托管平台生成的名片页是纯静态文件部署方式很轻量。常见选择包括 GitHub Pages、Vercel、Netlify、Cloudflare Pages 等。以下是 GitHub Pages 的最小流程在 GitHub 新建仓库名称可以叫my-card。在本地目录初始化 Git 并提交文件git init git add index.html git commit -m feat: init personal card page git branch -M main git remote add origin gitgithub.com:yourname/my-card.git git push -u origin main进入 GitHub 仓库页面选择 Settings Pages将 Source 设置为main分支根目录为根路径。等待一到两分钟访问https://yourname.github.io/my-card/。部署后要检查的资源路径问题如果首页代码引用了相对路径资源href./style.css这类可以正常解析如果引用了/style.css这类根路径部署在子路径时会 404。单文件页面最稳妥的方式是使用相对路径或者全部使用打包后的绝对路径。当前案例中的单文件方案部署后基本不会出现路径问题。4. 插件推荐的筛选标准不追求全追求真实可用插件推荐类内容最怕两件事一是推荐了一堆永远用不上的工具二是推荐了没经过验证的方案读者安装了反而增加负担。这里列出的是个人日常使用过程中留下来的选择优先考虑“能直接改善制作和调试网页体验”的插件。4.1 VS Code 插件清单与适用场景个人制作 HTML 页面时的 VS Code 插件组合如下插件名称主要作用适用场景说明Live Server本地启动静态服务器并自动刷新修改 HTML/CSS 后实时预览对单页名片这种项目非常方便Prettier - Code formatter统一代码格式多人协作、发布前整理格式需要配置保存时自动格式化Auto Rename Tag自动同步修改 HTML 标签名修改嵌套标签时避免遗漏闭合显著减少手改标签成本HTML CSS Support在 HTML 中提示 CSS 类名使用外部样式表时查找类名单文件项目作用有限Error Lens在行内直接显示错误提示快速发现语法错误配合 ESLint 插件使用效果更好Markdown All in One增强 Markdown 编辑体验写说明文档、任务描述写 task.md 时比较舒服这些插件都在 VS Code 扩展市场可搜索到。安装时注意查看维护状态和下载量避免使用长期未更新的插件。安装核心命令code --install-extension ritwickdey.LiveServer code --install-extension esbenp.prettier-vscode code --install-extension formulahendry.auto-rename-tag code --install-extension ecmel.vscode-html-css code --install-extension usernamehw.errorlens code --install-extension yzhang.markdown-all-in-one插件的核心作用是把操作成本降下来。Live Server 省去了反复手动刷新页面的过程Prettier 省去了手动对齐代码Auto Rename Tag 避免修改标签时漏改配对标签。对新手来说这三个是优先安装项。4.2 浏览器插件清单与适用场景浏览器端推荐度较高的插件类别包括插件类型代表性能力实际用途网页翻译阅读英文技术资料遇到英文文档时减少切换成本整页截图捕获超出视口的页面内容保存网页设计参考、提交页面效果截图CSS 实时编辑在当前页面临时修改样式并查看效果调整颜色、间距、字号确认最终值后回写代码图片素材嗅探获取页面中用到的图片资源地址寻找参考网站的素材资源注意版权视频下载嗅探网页视频地址技术教程缓存使用时注意版权和平台规则以 Chrome 浏览器为例通过设置中的扩展程序选项打开开发者模式后可以加载已下载的.crx文件或未打包扩展。但更安全的做法是直接从 Chrome 网上应用店搜索安装因为第三方渠道下载的插件可能存在权限滥用和恶意代码风险。4.3 插件安装的安全原则插件行业一直存在“插件越多风险越大”的问题。评估插件时至少要确认三件事插件是否开源或者是否有明确的开发者信息。插件申请了哪些权限是否需要访问所有网站的浏览数据。最近的更新时间和用户评价。不要因为一个插件功能看起来强大就忽略它可能读取页面内容、上传浏览数据的能力。对只需要离线工作的工具优先选择本地处理类型的插件。5. 生成网页过程中的常见坑与排查路径这一节专门记录制作名片网页时最容易遇到的三类问题以及它们的排查链路。5.1 页面能打开但样式完全丢失现象浏览器打开index.html看到的是纯文字列表没有卡片、背景、圆角等效果。排查步骤打开开发者工具进入 Console 面板看是否有红色报错。进入 Sources 面板确认 CSS 是否被成功加载。检查style标签是否在正确位置是否被意外闭合。检查 HTML 中元素名称是否正确例如 Class 名与 CSS 选择器是否完全一致。常见原因包括CSS 选择器写错使用了.card但 HTML 里类名是card-content。style标签内部写到了/style后浏览器将其视为普通文本。使用了浏览器不支持的 CSS 新语法例如过新的property特性。处理建议先在 HTML 元素上内联一个临时背景色如果内联样式生效说明选择器或外部样式加载有问题。5.2 页面在手机上显示拥挤现象手机浏览器打开页面文字和卡片边界几乎贴着屏幕边缘或者链接挤在一行。处理建议确认head中有 viewport meta 标签。给页面 body 添加水平和垂直内边距使用box-sizing: border-box避免盒子模型导致宽度超出。卡片使用width: 100%; max-width: 420px;组合而不是固定width: 420px。* { box-sizing: border-box; } body { margin: 0; padding: 16px; } .card { width: 100%; max-width: 420px; margin: 0 auto; }box-sizing: border-box的含义是元素的 padding 和 border 包含在元素的宽度内。如果不设置width: 100%再加上 padding 会导致元素实际宽度超过父容器。5.3 Pi Agent 生成文件后终端无响应或报权限错误现象运行任务后终端长时间没有输出或者出现EACCES、EPERM错误。排查顺序检查网络是否正常因为代理类工具通常需要请求远程模型服务。检查 API Key 或认证信息是否配置很多工具需要先登录或配置密钥。检查目录是否有写入权限特别是安装到系统级目录时。检查 Node.js 版本是否满足要求。处理建议先运行简单命令验证环境例如pi-agent --version能输出版本号说明工具本身安装正常。再尝试在空目录里运行一个小任务例如创建一个 hello.txt内容为 hello world小任务能跑通再运行复杂任务。这样可以把“工具问题”和“任务描述问题”分开排查。注意不要把敏感密钥写在任务文件里也不要提交到 Git 仓库。项目中的密钥一律通过环境变量或本地密钥文件读取并加入.gitignore。6. 个人工作流最佳实践Pi Agent 和网页制作如何配合工具链的价值最终体现在工作流里。以下是一套比较顺手的个人实践流程适合独立开发者或学习阶段的技术爱好者。6.1 任务文件作为项目的一部分在项目根目录创建task.md用来描述当前页面的需求。这样有两个好处后续改动需求时只要修改任务文件再让 AI 根据变更生成增量修改不用重写全部代码。项目交给其他人或未来自己维护时task.md本身就成了需求文档。任务文件模板可以这样设计# 项目个人名片页 ## 当前目标 生成一个单文件个人名片页 index.html ## 功能清单 - 显示头像 - 显示姓名和头衔 - 显示代表项目列表 - 显示社交链接 ## 样式要求 - 浅色背景 - 卡片居中 - 移动端适配 ## 约束 - 不引入前端框架 - 不引入构建工具 - 所有资源尽量内联6.2 每次变更走“描述需求 - 生成修改 - 检查 diff - 本地预览”的循环不要直接让 AI 一次性生成一个大而全的项目。更稳的做法是分步迭代先生成基础 HTML 结构。预览后补充样式。样式稳定后增加交互。交互完成后做移动端适配。修改代码前先让 Pi Agent 生成 diff 级别的内容。如果工具支持对当前文件做增量修改可以明确说“在现有 index.html 基础上升级”。6.3 女巫模式的“最小确认”原则当 AI 生成了包含交互脚本的页面也要检查脚本的实际作用。例如有些生成器会在 HTML 中加入统计脚本如果这个脚本发送数据到未知域名就需要立即移除。在浏览器开发者工具的 Network 面板里刷新页面观察所有网络请求。如果发现非预期域名回到代码里查找对应的脚本来源删除不需要的请求。一个简单的交互脚本可以控制在几行内例如链接点击控制台输出script document.querySelectorAll(.links a).forEach(function (link) { link.addEventListener(click, function () { console.log(click link: link.getAttribute(href)); }); }); /script这类代码简单、可读、易排查适合学习。6.4 给新手的练习建议如果完全不懂 HTML不建议直接学 Pi Agent 的复杂工程用法。先找一个纯 HTML 教程理解标签、属性、CSS 选择器和盒模型的基础。然后用 Pi Agent 生成几个不同页面包括个人名片、文章列表页、博客归档页对比生成代码和自己手写代码的差异。练习路线可以是手写一个 20 行的 HTML 页面包含标题、段落、链接和图片。用 CSS 调整文字颜色、间距和背景。使用 Pi Agent 生成一个同类页面对比两者结构差异。尝试在 AI 结果上修改一个模块例如把链接列表改成卡片布局。最后把页面发布到 GitHub Pages。这个路线不依赖复杂工具也能让 AI 编程代理真正成为学习辅助而不是“代码生成器”。6.5 发布与可维护性建议发布后要做三件事提交到 Git 仓库并打 tag方便回滚。检查页面在无痕模式下的表现避免不同浏览器插件的干扰。把任务文件和部署文档一起提交后续维护有依据。对于纯静态名片页开启 HTTPS 后基本不需要后端服务。如果后续要增加表单、访问统计或者内容管理系统再考虑引入服务端框架。单页面阶段保持代码简单。生产环境还需要考虑图片资源压缩避免首屏加载慢。外链统一使用https协议。页面设置合适的title和 meta description便于分享和搜索。使用语义化标签如header、main、footer提升可读性。7. 最后总结Pi 插件和 Pi Agent 的推荐本质上是在解决同一个核心诉求让“想法 - 网页 - 上线”这个过程变得更短、更可控。插件负责降低操作成本Pi Agent 负责降低从零写代码的启动成本而真正决定成果质量的仍然是你对页面需求的描述能力、对代码的审查习惯和排错时按链路查找问题的耐心。实际使用过程中最值得记住的三个判断是插件不是越多越好而是每个都解决一个明确问题否则会制造更多干扰。AI 生成代码后不代表任务结束审查、预览、修改、发布仍然是必须完成的工作。把需求写进task.md既能让生成结果更准也是项目可维护性的低成本保障。如果刚开始接触就按“手写 20 行 HTML - 用 Pi Agent 生成同名页面 - 对比修改 - 发布上线”的路径走一遍。完整走通一次之后再逐步加入表单、交互、样式框架等概念会比直接拿着复杂工具做项目扎实得多。