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

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

pi install npm:safe-coder

cd /your/project
pi .

// ~/.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" | "edit" ...
    // event.input: 工具的输入参数
    // ctx.cwd: pi 启动时的工作目录
    // ctx.ui: 用于弹窗、通知等 UI 操作

    // 返回 undefined 表示放行
    // 返回 { block: true, reason: "..." } 表示拦截
  });
}

import path from "node:path";
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

/** 判断目标路径是否在工作目录之外 */
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);
}

export default function (pi: ExtensionAPI) {
  // 危险命令的正则匹配规则
  const dangerousPatterns = [
    /\brm\s+(-rf?|--recursive)/i,
    /\bsudo\b/i,
    /\b(chmod|chown)\b.*777/i,
  ];

  // 启发式检测：命令是否可能触碰工作目录之外的路径
  const outsideCwdPatterns = [
    /(\s|^|["'\`])\/\S+/,   // 绝对路径
    /(\s|^|["'\`])~\//,     // home 目录路径
    /\.\.\//,               // 相对上级路径
  ];

  pi.on("tool_call", async (event, ctx) => {
    const cwd = path.resolve(ctx.cwd);
    let reasonLabel: string | null = null;
    let detail = "";

    // 检查文件操作是否跨越工作目录边界
    if (["read", "write", "edit"].includes(event.toolName)) {
      const targetPath = event.input.path as string | undefined;
      if (targetPath && isOutsideCwd(cwd, targetPath)) {
        reasonLabel = "Path is outside current working directory";
        detail = \`${event.toolName}: ${targetPath}\n\nCWD: ${cwd}\`;
      }
    }

    // 检查 bash 命令是否包含危险操作
    if (event.toolName === "bash" && !reasonLabel) {
      const command = event.input.command as string;
      if (dangerousPatterns.some((p) => p.test(command))) {
        reasonLabel = "Dangerous command";
        detail = command;
      } else if (outsideCwdPatterns.some((p) => p.test(command))) {
        reasonLabel = "Command may touch paths outside current working directory";
        detail = \`${command}\n\nCWD: ${cwd}\`;
      }
    }

    if (!reasonLabel) return undefined; // 放行

    // 无 UI 环境（如 CI）则直接拦截
    if (!ctx.hasUI) {
      return { block: true, reason: \`${reasonLabel} (no UI for confirmation)\` };
    }

    // 弹出确认框，由用户决定
    const choice = await ctx.ui.select(
      \`⚠️ ${reasonLabel}:\n\n${detail}\n\nAllow?\`,
      ["Yes", "No"]
    );

    return choice !== "Yes" ? { block: true, reason: "Blocked by user" } : undefined;
  });
}

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  const protectedPaths = [".env", ".git/", "node_modules/"];

  pi.on("tool_call", async (event, ctx) => {
    const path = event.input.path as string;

    // .env 文件：任何操作都拦截
    if (path.includes(".env")) {
      if (ctx.hasUI) {
        ctx.ui.notify(\`Blocked access to protected path: ${path}\`, "warning");
      }
      return { block: true, reason: \`Path "${path}" is fully protected\` };
    }

    // 其他受保护路径：只拦截写入和编辑
    if (event.toolName !== "write" && event.toolName !== "edit") {
      return undefined;
    }

    const isProtected = protectedPaths.some(
      (p) => path.includes(p) && p !== ".env"
    );

    if (isProtected) {
      if (ctx.hasUI) {
        ctx.ui.notify(\`Blocked write to protected path: ${path}\`, "warning");
      }
      return { block: true, reason: \`Path "${path}" is protected\` };
    }

    return undefined;
  });
}

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

---
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**: 修复建议（附代码片段）

---
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.

brave-search/
├── SKILL.md         # 必须：frontmatter + 操作指南
├── search.js        # 辅助脚本
└── content.js       # 辅助脚本

---
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

description: Extracts text and tables from PDF files, fills PDF forms,
             and merges multiple PDFs. Use when working with PDF documents.

description: Helps with PDFs.

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

~/.pi/agent/skills/         # 全局（所有项目）
~/.agents/skills/            # 全局备选
.pi/skills/                  # 项目级
.agents/skills/              # 项目级备选
package.json 的 pi.skills 字段  # 包级

safe-coder/
├── package.json              # pi 配置入口
├── extensions/
│   ├── permission-gate.ts    # 权限门：拦截危险命令 + 边界保护
│   └── protected-paths.ts    # 路径保护：锁定 .env 等敏感文件
├── prompts/
│   ├── architect.md          # 架构设计 Prompt
│   ├── implement.md          # 代码实现 Prompt
│   ├── review.md             # Code Review Prompt
│   ├── debug.md              # 调试 Prompt
│   └── ...（更多模板）
└── skills/
    └── skills.txt            # Skills 说明文档

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

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

// 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;
  });
}

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

## 必须检查的项目

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

---
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 publish
# 团队成员只需要：
pi install npm:your-coding-cli