使用 pi 打造属于你自己的 Coding CLI

如果你正在用 AI 辅助编程，却觉得主流工具越来越复杂，那你不是一个人。很多开发者都会遇到这样的情况：发一句简单的问候，就消耗掉当天模型配额的很大一部分；后台的服务器一直空跑，占用上下文窗口；那些计划模式和子代理听起来高级，但本质上只是把上下文管理变得更繁琐。你真的需要这么多层层封装的东西吗？

pi 提供了一个更直接的答案。它是一个开放、模块化的 AI Coding Agent CLI 工具，把所有核心接口和钩子完全敞开，让你能按照自己的实际需求来定制。不是黑盒子，而是你能完全掌控的工具。你可以用它来审查每一次调用、注入工程规范、打包常用流程，甚至把 pi 本身改造成更适合你的版本。

下面我们一步一步聊聊 pi 到底是什么、怎么安装、怎么用扩展来加安全防护、怎么定制提示词模板、怎么利用技能来复用工作流，以及怎么把这些组合成一个属于你自己的配置包。整个过程都基于真实可操作的步骤，你可以直接跟着做。

pi 到底是什么

pi 的设计思路很简单：AI 编程的核心交互无非是发送提示、获取回答，再加上一些工具调用。但主流工具往往把这些基础功能包裹在复杂的架构里，导致资源浪费。pi 把这一切拆开，让你看到并控制每一个环节。

它提供四种核心定制能力：

• 扩展（Extensions）：用 TypeScript 写插件，在 AI 执行工具调用前进行拦截、审查或确认。
• 提示模板（Prompts）：把代码风格、工程规范、最佳实践写成模板，每次对话自动注入，确保 AI 按你的标准工作。
• 技能（Skills）：把复杂工作流打包成自包含的包，AI 需要时才加载，平时不占上下文。
• 包（Packages）：打包成 npm 包，一行命令就能分享给团队或自己其他项目。

这些能力不是堆砌功能，而是让你真正掌控 AI 的行为。举例来说，你可以用 pi 来改造 pi 本身，把安全防护、代码审查规则直接嵌入进去。后面我们会以 safe-coder 这个安全配置包为例，一层层拆解它是怎么组成的。

这种开放设计解决了主流工具的痛点：你不再猜系统提示词写了什么，也不用担心 .env 文件被偷偷读取。你能精确控制上下文消耗，让 AI 真正成为帮手，而不是吞金巨兽。

先来安装 pi

安装 pi 非常 straightforward，不需要额外复杂环境。前提是你已经有 Node.js（建议用 LTS 版本）和 npm、pnpm 或 yarn 中的任意一个。

全局安装命令只有一行：

npm install -g @mariozechner/pi-coding-agent

安装完后，你就可以直接在终端输入 pi 命令了。

pi 还支持直接从 npm 安装配置包。比如要加载 safe-coder 这个安全防护包：

pi install npm:safe-coder

这会自动把包里的扩展、技能、提示模板全部加载到你的 pi 环境中。

在实际项目里启动 pi 也很简单。先进入你的项目目录：

cd /your/project
pi .

pi 会自动扫描项目里的配置文件夹，加载所有扩展和技能，然后进入交互界面。你现在就可以和 AI 开始对话了。

很多人会问：安装后怎么验证成功？很简单，输入 pi --version 就能看到版本信息。如果出现 pi 命令，就说明一切就绪。

用扩展给 pi 加装自定义机制

扩展是 pi 最强大的地方。它让你在 AI 每次调用工具（比如读文件、写文件、执行 bash 命令）之前插手干预。你可以用 TypeScript 写一个函数，监听事件，决定是放行、拦截，还是弹窗让用户确认。

每个扩展文件都是一个默认导出的函数，接收一个 ExtensionAPI 对象。基本结构长这样：

// ~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    // 这里写你的逻辑
    // event.toolName 可以是 "bash"、"read"、"write" 等
    // event.input 是工具的参数
    // ctx.cwd 是当前工作目录
    // ctx.ui 可以弹窗或通知
    return undefined; // 放行
  });
}

文件直接用 TypeScript 写，不需要编译，pi 会即时加载。

我们来看 safe-coder 包里的两个实际扩展，先说权限门（permission-gate.ts）。它主要做两件事：

1. 拦截危险命令，比如 rm -rf、sudo、chmod 777。
2. 保护工作目录边界，AI 不能随意读写项目外的文件。

代码里先定义了两个判断函数。一个是检查路径是否超出 cwd：

function isOutsideCwd(cwd: string, targetPath: string): boolean {
  const resolved = path.resolve(cwd, targetPath);
  const rel = path.relative(cwd, resolved);
  return rel.startsWith("..") || path.isAbsolute(rel);
}

然后监听 tool_call 事件：

• 如果是 read/write/edit，就检查路径是否超出 cwd。
• 如果是 bash，就用正则匹配危险命令或可能触碰外部路径的模式。
• 如果有风险，就弹窗问用户 “允许吗？”。没有 UI 环境（比如 CI）就直接拦截。

这个扩展直接解决了 AI 可能误操作的风险。你不用担心它突然删掉重要文件或跑到项目外乱改东西。

第二个扩展是路径保护（protected-paths.ts）。它锁定敏感文件：

• .env 文件任何操作都拦截。
• .git/ 和 node_modules/ 只拦截写入和编辑，读取可以放行。

代码里定义一个保护路径数组，然后检查 event.input.path 和 toolName。如果命中就通知用户并拦截。

这两个扩展怎么注册？在配置包的 package.json 里加一段：

{
  "name": "safe-coder",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"]
  }
}

pi 启动时会自动扫描 extensions 文件夹下的所有 .ts 文件并加载。你甚至可以写更多扩展，比如限制非工作时间执行部署命令：

// extensions/business-hours-guard.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName !== "bash") return undefined;
    const command = event.input.command as string;
    const isDeployCommand = /\b(deploy|release|publish)\b/i.test(command);
    if (!isDeployCommand) return undefined;

    const hour = new Date().getHours();
    const isBusinessHours = hour >= 9 && hour < 18;

    if (!isBusinessHours) {
      if (ctx.hasUI) {
        ctx.ui.notify("⛔ 非工作时间，禁止部署！", "warning");
      }
      return { block: true, reason: "Deploy blocked outside business hours" };
    }
    return undefined;
  });
}

这样你就把工作习惯也编进了规则里。扩展让 pi 变得真正安全、可控。

把工程规范写成提示词模板

pi 的提示模板系统让你把公司或个人的编码标准变成 AI 的“行为准则”。每个模板是一个 Markdown 文件，前面用 YAML frontmatter 写描述，正文就是提示词。用户输入用 $@ 占位。

举个代码审查模板（prompts/review.md）：

---
description: Code review for staged changes or the latest commit
---
You are a senior code reviewer performing a thorough, professional code review.

## Input
Optional focus area or context: $@

## Review Target
1. First, check for **staged changes**: run `git diff --cached`.
2. If no staged changes are found, compare the **latest commit**: run `git diff HEAD~1`.

## Review Checklist
### Correctness
- [ ] Logic errors, off-by-one errors, null/undefined handling
- [ ] Race conditions or concurrency issues

### Security
- [ ] Injection vulnerabilities (SQL, XSS, command injection)
- [ ] Sensitive data exposure (secrets, tokens, PII in logs)

## Output Format
### [SEVERITY] Issue Title
- **File**: `path/to/file.ext:LINE`
- **Category**: Correctness | Security | ...
- **Description**: 问题描述
- **Suggestion**: 修复建议（附代码片段）

再看代码实现模板（prompts/implement.md）：

---
description: Implement code from a spec or documentation with clean, modular practices
---
You are a senior software engineer implementing production-quality code.

## Input
The spec, doc, or feature description to implement: $@

## Implementation Principles
- **Readability First**: Write code that a mid-level developer can understand at first glance.
- **Single Responsibility**: Each function does one thing. Each module owns one concern.
- **No file may exceed 1000 lines.** If approaching this limit, split into logically cohesive modules.
- **No function may exceed 50 lines.** Extract helpers for complex logic.

## Process
1. Read and Understand
2. Plan the Implementation
3. Implement Incrementally
4. Wire It Together
5. Validate（运行构建和测试）

## Rules
- Follow the project's existing conventions strictly.
- Do NOT introduce new dependencies without explicit justification.
- Commit-ready quality: every file you produce must be mergeable as-is.

当 AI 执行对应任务时，模板自动注入上下文。AI 就会严格按照你的检查清单或实现原则来做事。你不用每次都重复叮嘱“要可读性优先”“函数不要超过 50 行”，这些规则已经内置了。

你还可以写架构设计模板、调试模板、更多自定义模板。模板让 AI 的输出更一致、更符合你的工程规范。

用技能打包常用工作流

技能是 pi 对复杂任务的封装方式。它把完整的工作流、脚本、参考文档放在一个文件夹里，AI 按需加载。

工作原理是“渐进式披露”：启动时只把技能名称和简短描述注入系统提示，占用很少上下文。当用户任务匹配时，才把整个 SKILL.md 文件加载进来。AI 按照里面的指令调用自带脚本。

一个技能的基本结构：

brave-search/
├── SKILL.md         # 必须文件
├── search.js        # 辅助脚本
└── content.js       # 辅助脚本

SKILL.md 例子：

---
name: brave-search
description: Web search and content extraction via Brave Search API.
             Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup
Run once before first use:

bash
cd /path/to/brave-search && npm install

## Search
bash
./search.js "query"              # 基础搜索
./search.js "query" --content    # 包含页面内容

## Extract Page Content
bash
./content.js https://example.com

描述写得越具体，AI 越容易判断什么时候用这个技能。好的描述会列出具体场景，比如“提取 PDF 文本和表格、填充表单、合并多个 PDF”。差的描述只是“帮助处理 PDF”。

你还可以手动触发技能：

/skill:brave-search            # 加载并执行
/skill:pdf-tools extract       # 带参数调用

技能可以放在全局目录（~/.pi/agent/skills/）、项目目录（.pi/skills/）或包里。pi 会自动扫描这些位置。

这种方式让常用流程变成可复用能力，却不会一直占用上下文。你可以把数据库迁移、PDF 处理、搜索等任务都做成技能，AI 需要时才展开完整指南。

safe-coder 配置包的项目结构

以 safe-coder 为例，一个完整的配置包长这样：

safe-coder/
├── package.json              # 入口
├── extensions/
│   ├── permission-gate.ts    # 权限门
│   └── protected-paths.ts    # 路径保护
├── prompts/
│   ├── architect.md
│   ├── implement.md
│   ├── review.md
│   ├── debug.md
│   └── ...
└── skills/
    └── skills.txt            # 技能说明

package.json 把一切关联起来：

{
  "name": "safe-coder",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills":     ["./skills"],
    "prompts":    ["./prompts"]
  }
}

这个结构清晰、模块化。你可以直接把 safe-coder 当模板，快速搭建自己的包。

一步步打造你自己的配置包

想把 pi 变成专属工具？跟着这五个步骤做就行。

第一步：克隆模板
用 safe-coder 作为起点：

git clone <your-repo-url> my-coding-cli
cd my-coding-cli
pnpm install

第二步：添加自己的扩展
在 extensions/ 目录新建 .ts 文件，写你需要的规则。比如上面提到的业务时间防护扩展，直接复制进去即可。pi 会自动加载。

第三步：编写提示词模板
在 prompts/ 下新建 Markdown 文件，加 frontmatter：

---
description: 按照公司编码规范进行 Code Review
---
你是一名资深工程师，负责对代码变更进行严格审查。

## 必须检查的项目
1. 所有函数必须有 JSDoc 注释
2. 变量名必须使用 camelCase，类名使用 PascalCase
3. 禁止使用 `any` 类型
4. 所有异步操作必须有错误处理
...

第四步：创建技能
在 skills/ 下新建文件夹，加 SKILL.md：

---
name: database-migration
description: Run and rollback database migrations using Flyway.
             Use when asked to migrate, rollback, or check migration status.
---

## Run Migration
bash
./scripts/migrate.sh up

## Rollback
bash
./scripts/migrate.sh down <version>

把对应的脚本放进去就行。

第五步：发布分享
打包成 npm 包：

npm publish

团队成员只需要：

pi install npm:your-coding-cli

这样你的配置就变成了可复用的标准工具。

整个过程不需要额外学习复杂框架，只用 TypeScript 和 Markdown 就能完成。完成后，你的项目里启动 pi 就会自动带上所有定制规则。

常见问题解答

pi 和主流 AI 编程工具有什么不一样？
主流工具往往是黑盒，系统提示词、上下文管理你看不见。pi 把一切开放，你能审查每一次工具调用、注入自己的规范、打包技能。资源消耗更低，控制力更强。

安装 pi 需要什么环境？
只要 Node.js LTS 和 npm/pnpm/yarn 就够。全局安装一行命令，项目启动也只要 pi .。

扩展能拦截哪些操作？
几乎所有工具调用：bash、read、write、edit 等。你可以写危险命令拦截、工作目录保护、文件锁定、时间限制等规则。

提示模板怎么生效？
AI 执行对应任务时自动注入。写好 frontmatter 描述，正文就是你的规则清单或实现原则。

技能和普通脚本有什么区别？
技能是自包含的工作流，AI 按步骤执行，还能渐进式加载，只在需要时展开完整内容。

可以把 pi 本身改掉吗？
可以。你可以用扩展和提示模板改造 pi 的行为，甚至用技能来管理 pi 自身的配置。

安全防护怎么实现？
用 permission-gate 和 protected-paths 这两个扩展就行。它们会弹窗确认或直接拦截危险操作和敏感文件。

怎么手动触发技能？
输入 /skill:技能名 或带参数调用。

配置包怎么分享给团队？
打包成 npm 包，别人用 pi install npm:包名 就能加载。

pi 支持多少种自定义？
扩展、提示模板、技能、主题（themes）都能自定义，几乎没有限制。

如果没有 UI 环境会怎样？
扩展会直接拦截并返回原因，不会尝试弹窗。

如何让 AI 遵守公司规范？
把规范写进提示模板，AI 每次都会自动参考。

这些问题覆盖了大多数人上手时会遇到的疑问。如果你还有其他具体场景，可以在自己的扩展或技能里继续扩展规则。

结语

pi 的核心价值在于把控制权还给你。你不再被动接受黑盒工具的限制，而是主动塑造 AI 的行为。无论是加安全门、注入编码规范、打包工作流，还是把配置分享给团队，都只需要几行代码和 Markdown。

从安装到发布，整个流程透明、可控、实用。试着从 safe-coder 模板开始，逐步加上你的业务规则，你会发现 AI 编程终于变得真正属于自己。

现在就打开终端，输入 npm install -g @mariozechner/pi-coding-agent，然后 pi . 启动你的第一个项目吧。定制的过程本身就是一次很好的练习，你会越来越清楚自己真正需要什么样的 AI 助手。

（全文约 4500 字，全部步骤和代码均可直接复制使用）