From bda7754dcbe6e6f54215263241d4989ad71e9f18 Mon Sep 17 00:00:00 2001 From: mpv945 Date: Wed, 12 Aug 2026 16:34:48 +0000 Subject: [PATCH] =?UTF-8?q?add=20pi=E7=BC=96=E7=A8=8B.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: mpv945 --- pi编程 | 3564 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3564 insertions(+) create mode 100644 pi编程 diff --git a/pi编程 b/pi编程 new file mode 100644 index 00000000..67b350c9 --- /dev/null +++ b/pi编程 @@ -0,0 +1,3564 @@ +查看https://pi.dev/文档，告诉我pi如何在安装和使用，如何添加自己购买的模型代理商 + +[Pi Documentation](https://pi.dev/docs/latest?utm_source=chatgpt.com) 是一个面向开发者的 **终端 AI Coding Agent（类似 Claude Code、OpenCode、Aider）**。它的设计理念是： + +* 核心保持轻量 +* 支持扩展（TypeScript Extension） +* 支持多模型 Provider +* 支持自定义模型代理 +* 支持企业内部 AI Gateway / OpenAI 兼容接口 +* 支持本地模型（Ollama、vLLM、LM Studio、llama.cpp） + +官方支持通过 `models.json` 添加自定义模型代理，也可以通过 Extension 注册完全自定义 Provider。([Pi][1]) + +--- + +# 一、Pi 安装 + +## 1. 环境要求 + +推荐： + +| 组件 | 版本 | +| ------- | ----------------------- | +| Node.js | 20+ | +| npm | 10+ | +| 系统 | Linux/macOS/Windows WSL | + +检查： + +```bash +node -v +npm -v +``` + +--- + +# 2. npm 安装（推荐） + +```bash +npm install -g --ignore-scripts @earendil-works/pi-coding-agent +``` + +官方使用： + +```bash +pi +``` + +即可启动。([Pi][2]) + +--- + +# 3. Linux/macOS 一键安装 + +```bash +curl -fsSL https://pi.dev/install.sh | sh +``` + +安装完成： + +```bash +pi --version +``` + +([Pi][2]) + +--- + +# 二、第一次启动 + +进入你的代码目录： + +例如： + +```bash +cd ~/workspace/my-project + +pi +``` + +第一次运行： + +``` +Welcome to pi + +/login +``` + +登录模型。 + +--- + +# 三、Pi 常用命令 + +进入 Pi 后： + +## 查看模型 + +``` +/model +``` + +例如： + +``` +Claude Sonnet 4 +GPT-5 +DeepSeek +Qwen +``` + +--- + +## 登录 Provider + +``` +/login +``` + +支持： + +* OpenAI +* Anthropic +* GitHub Copilot +* OpenRouter +* xAI +* Radius + +等。([Pi][3]) + +--- + +## 切换模型 + +``` +/model claude-sonnet +``` + +或者： + +```bash +pi --model xxx +``` + +--- + +## 查看帮助 + +``` +/help +``` + +--- + +# 四、Pi 配置目录 + +默认： + +``` +~/.pi/ +└── agent/ + ├── auth.json + ├── models.json + ├── models-store.json + ├── sessions/ + └── extensions/ +``` + +重要： + +| 文件 | 作用 | +| ----------------- | ------------ | +| auth.json | 保存 API Token | +| models.json | 添加自定义模型 | +| models-store.json | 模型缓存 | +| extensions | 扩展 | + +([Pi][1]) + +--- + +# 五、添加自己购买的模型代理商 + +这里是重点。 + +假设你购买了： + +* DeepSeek API +* 硅基流动 +* 火山方舟 +* OpenRouter +* OneAPI +* New API +* 自建 OpenAI Proxy +* 公司 AI Gateway + +只要兼容： + +``` +OpenAI Chat Completions API +``` + +都可以接入。 + +Pi 使用： + +``` +~/.pi/agent/models.json +``` + +配置。([Pi][1]) + +--- + +# 六、案例1：添加 OpenAI 兼容代理 + +例如你的代理： + +``` +https://api.example.com/v1 +``` + +模型： + +``` +deepseek-chat +``` + +创建： + +```bash +mkdir -p ~/.pi/agent + +vim ~/.pi/agent/models.json +``` + +内容： + +```json +{ + "providers": { + "my-ai": { + "baseUrl": "https://api.example.com/v1", + "api": "openai-completions", + "apiKey": "sk-your-key", + "models": [ + { + "id": "deepseek-chat", + "name": "DeepSeek Chat", + "reasoning": false, + "input": [ + "text" + ], + "contextWindow": 128000, + "maxTokens": 8192 + } + ] + } + } +} +``` + +重新启动： + +```bash +pi +``` + +查看： + +``` +/model +``` + +应该看到： + +``` +my-ai/deepseek-chat +``` + +--- + +# 七、案例2：接入国内大模型代理 + +例如： + +## 硅基流动 + +假设： + +``` +https://api.siliconflow.cn/v1 +``` + +配置： + +```json +{ + "providers": { + "siliconflow": { + + "baseUrl": + "https://api.siliconflow.cn/v1", + + "api": + "openai-completions", + + "apiKey": + "$SILICONFLOW_API_KEY", + + "models":[ + { + "id": + "deepseek-ai/DeepSeek-V3", + + "name": + "DeepSeek V3", + + "reasoning": + true, + + "input":[ + "text" + ], + + "contextWindow": + 128000, + + "maxTokens": + 8192 + } + ] + } + } +} +``` + +环境变量： + +```bash +export SILICONFLOW_API_KEY=sk-xxxx +``` + +启动： + +```bash +pi +``` + +--- + +# 八、接入 OneAPI / New API 聚合平台 + +这是企业最推荐方式。 + +例如： + +你的内部： + +``` +http://ai-gateway.company.com/v1 +``` + +后端： + +``` +OneAPI + | + +-- OpenAI + +-- Claude + +-- DeepSeek + +-- Qwen + +-- Gemini +``` + +Pi： + +```json +{ + "providers": { + + "company-ai": { + + "baseUrl": + "http://ai-gateway.company.com/v1", + + "api": + "openai-completions", + + "apiKey": + "$COMPANY_AI_KEY", + + "models":[ + + { + "id": + "gpt-5", + + "name": + "GPT-5 Internal", + + "reasoning": + true + }, + + { + "id": + "deepseek-chat", + + "name": + "DeepSeek" + + } + + ] + } + } +} +``` + +优势： + +* Pi 不需要知道真实厂商 +* 统一计费 +* 统一权限 +* 统一审计 +* 可切换模型 + +生产环境非常推荐。 + +--- + +# 九、接入 Ollama 本地模型 + +例如： + +安装： + +```bash +ollama pull qwen3 +``` + +启动： + +```bash +ollama serve +``` + +Pi： + +```json +{ + "providers": { + + "ollama": { + + "baseUrl": + "http://localhost:11434/v1", + + "api": + "openai-completions", + + "apiKey": + "ollama", + + "models":[ + + { + "id": + "qwen3" + } + + ] + + } + + } +} +``` + +官方也支持 Ollama/vLLM/LM Studio 这种 OpenAI 兼容服务。([Pi][1]) + +--- + +# 十、接入 vLLM 企业部署模型 + +例如： + +vLLM： + +```bash +vllm serve Qwen/Qwen3-32B \ + --port 8000 +``` + +Pi： + +```json +{ + "providers":{ + + "vllm":{ + + "baseUrl": + "http://localhost:8000/v1", + + "api": + "openai-completions", + + "apiKey": + "EMPTY", + + "models":[ + + { + "id": + "Qwen/Qwen3-32B", + + "reasoning": + true + } + + ] + + } + + } +} +``` + +--- + +# 十一、如果代理不是 OpenAI 协议怎么办？ + +例如： + +你的公司接口： + +``` +POST /chat +{ + question:"xxx" +} +``` + +不是： + +``` +POST /v1/chat/completions +``` + +需要写 Pi Extension。 + +Pi 支持： + +```typescript +pi.registerProvider() +``` + +注册自己的 Provider。([Pi][4]) + +结构： + +``` +~/.pi/agent/extensions/ + +company-provider/ +| +├── index.ts +└── package.json +``` + +示例： + +```typescript +export default function(pi) +{ + + pi.registerProvider( + "company", + + { + + baseUrl: + "https://ai.company.com", + + api: + "openai-completions", + + apiKey: + "$COMPANY_KEY", + + models:[ + { + id:"company-coder", + name:"Company Coder" + } + ] + + }) + +} +``` + +--- + +# 十二、企业生产推荐架构 + +结合你的大数据/平台经验，我更推荐： + +``` + Pi Client + | + | + OpenAI Compatible API + | + AI Gateway + | + ┌───────────────┼───────────────┐ + | | | +OpenAI Claude DeepSeek + | | | +国内代理 Anthropic 自建vLLM +``` + +组件： + +| 层 | 推荐 | +| ----- | ---------------- | +| 客户端 | Pi | +| 统一入口 | OneAPI / New API | +| 权限 | OAuth2/JWT | +| 审计 | ELK | +| 限流 | Nginx/OpenResty | +| 模型服务 | vLLM | +| GPU调度 | Kubernetes | + +--- + +# 十三、和 Claude Code / OpenCode 对比 + +| 能力 | Pi | Claude Code | OpenCode | +| ------- | ----- | ----------- | -------- | +| 终端Agent | ★★★★★ | ★★★★★ | ★★★★ | +| 模型自由度 | ★★★★★ | ★★ | ★★★★★ | +| 自定义代理 | ★★★★★ | ★★★ | ★★★★★ | +| 本地模型 | ★★★★★ | ★★ | ★★★★★ | +| 企业部署 | ★★★★★ | ★★★ | ★★★★★ | +| 扩展能力 | ★★★★★ | ★★★ | ★★★★ | + +如果你有自己的模型采购渠道（OpenAI、Claude、DeepSeek、Qwen、内部GPU模型），Pi 的 Provider 机制非常适合做企业统一 AI Coding 平台。([Pi][2]) + +对于你的技术栈（Java/Spring Boot/Flink/HBase/Kafka/ES），建议采用： + +**Pi + OneAPI/New API + 多模型路由 + vLLM 私有模型**，基本可以替代企业版 Copilot 类方案。 + +[1]: https://pi.dev/docs/latest/models?utm_source=chatgpt.com "Custom Models · Documentation · Pi" +[2]: https://pi.dev/docs/latest?utm_source=chatgpt.com "Pi Documentation · Documentation · Pi" +[3]: https://pi.dev/docs/latest/providers?utm_source=chatgpt.com "Providers · Documentation · Pi" +[4]: https://pi.dev/docs/latest/custom-provider?utm_source=chatgpt.com "Custom Providers · Documentation · Pi" + + + + + + +Pi 的设计和 Claude Code、Cursor Agent 不太一样：**Pi 核心不内置 MCP、Skills、Prompt Templates，而是通过 Extension / Packages / Skills / Prompt Templates 扩展。** 官方定位就是保持核心最小化，把能力放到扩展体系中。([Pi][1]) + +另外需要特别说明： + +* **Skills：Pi 原生支持** +* **Prompt Templates：Pi 原生支持** +* **MCP：Pi 当前不是内置功能，需要通过 Extension 或 Package 接入 MCP Server**（官方明确说明 Pi 不内置 MCP，需要通过扩展实现）。([Pi][2]) + +下面按照生产使用方式讲。 + +--- + +# 一、Pi 的目录结构 + +安装后： + +```bash +~/.pi/ +└── agent/ + | + ├── skills/ + | + ├── prompts/ + | + ├── extensions/ + | + ├── packages/ + | + └── settings.json +``` + +常用： + +| 功能 | 目录 | +| ---------------- | ------------------------ | +| Skills | `~/.pi/agent/skills` | +| Prompt Templates | `~/.pi/agent/prompts` | +| Extensions | `~/.pi/agent/extensions` | + +([Pi][3]) + +--- + +# 二、安装 Skills + +## 方式1：直接安装官方 Skill Package（推荐） + +Pi 支持 package： + +```bash +pi install npm:xxx +``` + +例如： + +```bash +pi install npm:pi-skills +``` + +安装后： + +```bash +pi list +``` + +查看： + +``` +pi-skills + +skills: + ├── brave-search + ├── browser + └── transcription +``` + +--- + +# 三、手动添加 Skill + +创建： + +```bash +mkdir -p ~/.pi/agent/skills/java-review +``` + +结构： + +``` +java-review +| +├── SKILL.md +| +├── scripts +│ └── check.sh +| +└── references + └── spring.md +``` + +--- + +## SKILL.md + +例如： + +```markdown +--- +name: java-review +description: +Review Java enterprise code including Spring Boot, +security issues, concurrency and performance. +--- + +# Java Code Review Skill + + +## Rules + + +检查： + +1. Spring Bean生命周期 + +2. Thread safety + +3. JVM memory + +4. SQL performance + +5. Security + + +## Workflow + + +读取代码： + +``` + +src/**/*.java + +``` + + +输出： + +- Bug +- Risk +- Improvement +``` + +--- + +启动 Pi： + +```bash +pi +``` + +查看： + +``` +/skill: +``` + +应该出现： + +``` +/skill:java-review +``` + +执行： + +``` +/skill:java-review +``` + +官方 Skill 机制就是扫描 `SKILL.md`，启动时加载描述，需要时读取完整内容。([Pi][3]) + +--- + +# 四、项目级 Skill + +生产开发更推荐项目隔离： + +例如： + +``` +my-project + +├── src +├── pom.xml +| +└── .pi + | + └── skills + | + └── spring-cloud + | + └── SKILL.md +``` + +进入项目： + +```bash +cd my-project + +pi +``` + +Pi 会自动发现： + +``` +.pi/skills +``` + +但是： + +第一次： + +``` +/trust +``` + +信任项目。 + +官方规则： + +* 全局： + +``` +~/.pi/agent/skills +``` + +* 项目： + +``` +.pi/skills +``` + +([Pi][3]) + +--- + +# 五、安装 Claude Code Skills 到 Pi + +Pi 支持兼容其他 Agent Skills。 + +例如你已有： + +``` +~/.claude/skills +``` + +可以： + +编辑： + +``` +~/.pi/agent/settings.json +``` + +增加： + +```json +{ + "skills":[ + "~/.claude/skills" + ] +} +``` + +然后： + +```bash +pi +``` + +即可使用 Claude Code 的 skills。 + +官方支持： + +``` +~/.claude/skills +~/.codex/skills +``` + +迁移。([Pi][3]) + +--- + +# 六、Prompt Templates 安装 + +Prompt Template 本质： + +``` +Markdown文件 ++ +frontmatter +``` + +目录： + +``` +~/.pi/agent/prompts +``` + +创建： + +```bash +mkdir -p ~/.pi/agent/prompts +``` + +--- + +例如： + +``` +~/.pi/agent/prompts/review.md +``` + +内容： + +```markdown +--- +description: Review Java code +argument-hint: "" +--- + +请审查Java代码： + +文件： + +$1 + + +关注： + +- Bug +- 性能 +- 安全 +- 并发 +``` + +--- + +启动： + +```bash +pi +``` + +输入： + +``` +/review UserService.java +``` + +自动展开。 + +官方规则： + +``` +review.md + +变成 + +/review +``` + +([Pi][4]) + +--- + +# 七、Prompt Template 参数 + +支持： + +## 参数 + +```markdown +$1 +$2 +``` + +例如： + +文件： + +``` +deploy.md +``` + +内容： + +```markdown +部署服务： + +环境: + +$1 + + +服务: + +$2 +``` + +调用： + +``` +/deploy prod api +``` + +结果： + +``` +环境: +prod + +服务: +api +``` + +--- + +## 默认值 + +```markdown +${1:-dev} +``` + +例如： + +```markdown +部署环境: + +${1:-test} +``` + +执行： + +``` +/deploy +``` + +默认： + +``` +test +``` + +([Pi][4]) + +--- + +# 八、MCP 如何接入 Pi + +这里重点。 + +Pi 官方： + +> 不直接内置 MCP + +需要： + +``` +Pi Extension + | + | + MCP Client + | + | + MCP Server +``` + +架构： + +``` + Pi + + | + MCP Extension + + | + + ---------------------- + + | | | + + GitHub Database Browser + + MCP MCP MCP + +``` + +([Pi][2]) + +--- + +# 九、安装 MCP Extension + +例如： + +```bash +pi install npm:pi-mcp +``` + +然后： + +``` +~/.pi/agent/extensions +``` + +加载： + +```bash +pi +``` + +--- + +# 十、配置 MCP Server + +类似： + +``` +~/.pi/agent/mcp.json +``` + +例如： + +GitHub MCP： + +```json +{ + "mcpServers": { + + "github": { + + "command": + "npx", + + "args":[ + "-y", + "@modelcontextprotocol/server-github" + ], + + "env":{ + + "GITHUB_TOKEN": + "xxx" + + } + + } + + } +} +``` + +启动： + +``` +pi +``` + +看到： + +``` +Tools: + +github.search +github.issue +github.pr +``` + +--- + +# 十一、数据库 MCP 示例 + +例如 PostgreSQL： + +安装： + +```bash +npm install -g \ +@modelcontextprotocol/server-postgres +``` + +配置： + +```json +{ + "mcpServers":{ + + "postgres":{ + + "command":"postgres-mcp", + + "args":[ + "postgresql://user:pass@host/db" + ] + + } + + } +} +``` + +以后： + +直接： + +``` +查询订单表最近数据 +``` + +Pi 调用： + +``` +postgres.query +``` + +--- + +# 十二、生产级推荐组合（结合你的 Java + 大数据场景） + +我建议： + +``` + Pi + + | + + Skills + Prompt Templates + + | + + MCP Layer + + | + + ------------------------------------------------ + + | | | | + +GitHub PostgreSQL Kafka ES + +MCP MCP MCP MCP + + + | + + 企业AI Gateway + + | + + GPT-5 / Claude / DeepSeek / Qwen + +``` + +--- + +# 十三、推荐你建立的企业 Skills + +你的技术栈比较适合： + +``` +~/.pi/agent/skills/ + +├── java-enterprise +│ +├── spring-boot-review +│ +├── flink-job-review +│ +├── hbase-performance +│ +├── kafka-design +│ +├── elasticsearch-tuning +│ +├── sql-review +│ +├── linux-debug +│ +└── kubernetes-deploy + +``` + +对应： + +``` +/skill:spring-boot-review + +/skill:flink-job-review + +/skill:hbase-performance +``` + +--- + +# 十四、推荐企业 Prompt Templates + +例如： + +``` +~/.pi/agent/prompts/ + + +├── code-review.md + +├── architecture-design.md + +├── sql-optimize.md + +├── production-debug.md + +├── security-audit.md + +└── migration-plan.md + +``` + +调用： + +``` +/architecture-design +``` + +直接生成： + +* 架构图 +* 技术选型 +* 风险 +* 部署方案 + +--- + +# 十五、最终推荐安装顺序 + +生产环境： + +```bash +# 1. 安装Pi + +npm install -g @earendil-works/pi-coding-agent + + +# 2. 安装skills + +pi install npm:pi-skills + + +# 3. 建立企业skills + +~/.pi/agent/skills + + +# 4. 建立prompt模板 + +~/.pi/agent/prompts + + +# 5. 安装MCP Extension + +pi install npm:xxx-mcp + + +# 6. 接入企业MCP + +GitHub +PostgreSQL +ES +Kafka +Jira + +``` + +对于你的技术背景（Flink/HBase/Kafka/ES/Spring Boot），Pi 最有价值的不是简单写代码，而是打造： + +**Pi + 企业 MCP + 专业 Skills + Prompt Templates + 私有模型代理** + +形成一个类似企业版 Claude Code 的研发 Agent 平台。 + +[1]: https://pi.dev/docs/latest?utm_source=chatgpt.com "Pi Documentation · Documentation · Pi" +[2]: https://pi.dev/docs/latest/usage?utm_source=chatgpt.com "Using Pi · Documentation · Pi" +[3]: https://pi.dev/docs/latest/skills?utm_source=chatgpt.com "Skills · Documentation · Pi" +[4]: https://pi.dev/docs/latest/prompt-templates?utm_source=chatgpt.com "Prompt Templates · Documentation · Pi" + + + + + + + +支持，而且 **Pi 对 `CLAUDE.md` 有兼容支持**，但它的设计理念更推荐使用 **`AGENTS.md` 作为通用 Agent 项目上下文文件**。也就是说，你可以把 Claude Code 项目直接迁移到 Pi，不需要重新维护一份配置。([Pi][1]) + +不过需要区分几个概念： + +| Claude Code | Pi 对应 | +| ----------------------- | ---------------- | +| `CLAUDE.md` | 支持 | +| `AGENTS.md` | 推荐 | +| `.claude/settings.json` | 不直接兼容 | +| `.claude/rules` | 不直接兼容 | +| `/init` 生成配置 | Pi 使用手动 Markdown | +| System Prompt | `.pi/SYSTEM.md` | + +([GitHub][2]) + +--- + +# 1. Pi 加载 CLAUDE.md 的方式 + +Pi 启动时会自动查找： + +```text +当前项目目录 + | + ├── CLAUDE.md + | + ├── AGENTS.md + | + └── 父目录 + | + └── CLAUDE.md +``` + +同时支持全局： + +```bash +~/.pi/agent/AGENTS.md +``` + +也就是说： + +```bash +~/workspace/demo/ +| +├── pom.xml +├── src +└── CLAUDE.md +``` + +启动： + +```bash +cd ~/workspace/demo + +pi +``` + +Pi 会自动读取： + +```text +CLAUDE.md +``` + +作为项目上下文。([GitHub][3]) + +--- + +# 2. 推荐企业使用 AGENTS.md + +虽然： + +```text +CLAUDE.md +``` + +可以用。 + +但是现在多个 Coding Agent 都开始支持： + +```text +AGENTS.md +``` + +例如： + +* Pi +* Codex +* VS Code Agent +* 其他 Agent + +所以建议： + +```text +project + +├── AGENTS.md +├── CLAUDE.md +├── pom.xml +└── src +``` + +其中： + +## AGENTS.md + +放公共规范： + +````markdown +# Project Instructions + + +## 技术栈 + +这是 Spring Boot 3.5 项目。 + +使用： + +- Java 21 +- Maven +- PostgreSQL + + +## Coding Rules + +修改代码必须： + +1. 保持现有架构 + +2. 不允许引入未经批准依赖 + +3. Controller 不写业务逻辑 + + +## Testing + +修改后执行： + +```bash +mvn clean test +```` + +## Database + +禁止： + +* 自动修改生产数据库 +* 删除表 + +```` + + +--- + +## CLAUDE.md + +只放 Claude 特有： + +```markdown +# Claude Specific + + +使用 Sonnet 模型时： + +- 优先分析 +- 不要一次修改大量文件 +```` + +--- + +# 3. Pi 的全局 CLAUDE.md + +Claude Code 常用： + +```bash +~/.claude/CLAUDE.md +``` + +Pi 推荐： + +```bash +~/.pi/agent/AGENTS.md +``` + +例如： + +```bash +mkdir -p ~/.pi/agent + +vim ~/.pi/agent/AGENTS.md +``` + +内容： + +```markdown +# Global Developer Rules + + +我的默认开发环境： + +- Linux +- Java 25 +- Spring Boot +- Kafka +- Flink + + +代码要求： + +- 生产级 +- 考虑异常处理 +- 考虑性能 +- 给出完整代码 +``` + +以后所有项目自动加载。 + +--- + +# 4. Pi 还有更强的 SYSTEM.md + +Claude Code： + +```text +CLAUDE.md +``` + +主要影响： + +* 项目规范 + +Pi： + +```text +SYSTEM.md +``` + +更底层。 + +目录： + +项目级： + +```bash +.pi/SYSTEM.md +``` + +例如： + +```text +project + +├── .pi +│ └── SYSTEM.md +│ +├── AGENTS.md +└── src +``` + +内容： + +```markdown +你是一个高级Java架构师。 + + +回答要求： + +1. 优先生产方案 + +2. 给出完整代码 + +3. 分析性能 + +4. 分析安全风险 +``` + +启动后： + +```text +System Prompt + + +SYSTEM.md + + +AGENTS.md + + +Skills + + +Prompt Templates +``` + +形成完整上下文。([GitHub][2]) + +--- + +# 5. Pi 如何查看是否加载成功 + +启动： + +```bash +pi +``` + +执行： + +```text +/reload +``` + +然后问： + +``` +你读取到了哪些项目规则？ +``` + +例如： + +回答： + +``` +Loaded: + +AGENTS.md +CLAUDE.md +.pi/SYSTEM.md +``` + +--- + +# 6. Claude Code 项目迁移到 Pi + +假设： + +原项目： + +``` +project + +├── .claude +│ ├── settings.json +│ └── rules +│ +├── CLAUDE.md +└── src +``` + +迁移： + +保留： + +``` +CLAUDE.md +``` + +新增： + +``` +AGENTS.md +``` + +迁移： + +``` +.claude/rules/*.md +``` + +变成： + +``` +.pi/prompts/ +``` + +或者： + +``` +.pi/skills/ +``` + +例如： + +原： + +``` +.claude/rules/database.md +``` + +改： + +``` +.pi/skills/database/SKILL.md +``` + +--- + +# 7. 对你这种企业 Java / 大数据项目，我建议结构 + +例如： + +``` +flink-hbase-platform + +├── AGENTS.md + +├── .pi +│ +│ ├── SYSTEM.md +│ │ +│ ├── prompts +│ │ ├── architecture.md +│ │ ├── code-review.md +│ │ └── sql-optimize.md +│ │ +│ └── skills +│ ├── flink +│ │ └── SKILL.md +│ │ +│ ├── hbase +│ │ └── SKILL.md +│ │ +│ ├── kafka +│ │ └── SKILL.md +│ │ +│ └── springboot +│ └── SKILL.md +│ +├── pom.xml +└── src +``` + +启动 Pi： + +```bash +pi +``` + +自动拥有： + +``` +项目架构知识 ++ +编码规范 ++ +领域技能 ++ +Prompt模板 ++ +MCP工具 ++ +企业模型代理 +``` + +--- + +# 8. Pi 与 Claude Code 配置能力对比 + +| 能力 | Claude Code | Pi | +| --------------- | ----------- | ---------- | +| CLAUDE.md | ★★★★★ | ★★★★★ | +| AGENTS.md | 部分 | ★★★★★ | +| 全局规则 | ★★★★★ | ★★★★★ | +| System Prompt | 有限 | ★★★★★ | +| Skills | ★★★★★ | ★★★★★ | +| Prompt Template | 一般 | ★★★★★ | +| MCP | ★★★★★ | 需Extension | +| 自定义模型 | 弱 | ★★★★★ | + +([GitHub][2]) + +--- + +所以如果你已经大量使用 Claude Code 的： + +* `CLAUDE.md` +* 项目规范 +* 技术约束 +* Coding Rule + +**Pi 可以直接接管。** + +对于你的场景（Spring Boot、Flink、HBase、Kafka、ES、Linux 运维），推荐最终组合： + +``` +~/.pi/agent/AGENTS.md # 个人长期规则 + +项目/AGENTS.md # 项目规范 + +项目/.pi/SYSTEM.md # 架构师角色 + +.pi/skills # 技术领域能力 + +.pi/prompts # 常用任务模板 + +MCP # 数据库/ES/Git/Kafka工具 +``` + +这套结构比单纯 Claude Code 的 `CLAUDE.md` 更适合企业级长期维护。 + +[1]: https://pi.dev/docs/latest/quickstart?utm_source=chatgpt.com "Quickstart · Documentation · Pi" +[2]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md?utm_source=chatgpt.com "pi/packages/coding-agent/README.md at main · earendil-works/pi · GitHub" +[3]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md?utm_source=chatgpt.com "pi/packages/coding-agent/docs/quickstart.md at main · earendil-works/pi · GitHub" + + + + + + + + + + + + + +下面以一个**企业级 Spring Boot CMR（Customer Management / Customer Relationship Management，客户关系管理）系统**为例，设计一套 Pi Agent 配置。 + +目标： + +让 Pi 在开发过程中具备： + +* Spring Boot 架构师能力 +* 数据库设计能力 +* DDD 建模能力 +* MyBatis/JPA 编码规范 +* Redis/ES/Kafka 使用经验 +* 自动代码 Review +* SQL 优化 +* 接口设计 +* 安全审计 +* DevOps 部署能力 + +最终目录： + +```text +cmr-system +│ +├── pom.xml +├── src +│ +├── AGENTS.md # 项目规范 +│ +├── .pi +│ │ +│ ├── SYSTEM.md # 架构师角色 +│ │ +│ ├── skills +│ │ ├── springboot +│ │ │ └── SKILL.md +│ │ │ +│ │ ├── database +│ │ │ └── SKILL.md +│ │ │ +│ │ ├── redis +│ │ │ └── SKILL.md +│ │ │ +│ │ ├── elasticsearch +│ │ │ └── SKILL.md +│ │ │ +│ │ ├── kafka +│ │ │ └── SKILL.md +│ │ │ +│ │ └── security +│ │ └── SKILL.md +│ │ +│ └── prompts +│ │ +│ ├── design-api.md +│ ├── review-code.md +│ ├── optimize-sql.md +│ └── create-module.md +│ +└── docker-compose.yml +``` + +--- + +# 一、个人长期规则 + +位置： + +```bash +~/.pi/agent/AGENTS.md +``` + +作用： + +所有项目生效。 + +例如： + +```markdown +# Global Engineering Rules + + +## Role + +你是一名拥有15年以上经验的Java架构师。 + + +## 技术偏好 + + +默认： + +- Java 21+ +- Spring Boot 3.x/4.x +- Maven +- PostgreSQL/MySQL +- Redis +- Kafka +- Elasticsearch + + +## Coding Style + + +生成代码必须： + +1. 遵循SOLID原则 + +2. 优先使用设计模式 + +3. 避免过度设计 + +4. 考虑异常处理 + + +## Production Requirements + + +所有代码必须考虑： + +- 高并发 + +- 数据一致性 + +- 幂等 + +- 安全 + +- 日志 + + +## Database + + +SQL必须考虑： + +- 索引 + +- 执行计划 + +- 分页性能 + +- 数据量增长 + + +## API + + +REST API: + +必须包含： + +- 参数校验 + +- 统一返回 + +- 异常处理 + +- OpenAPI注释 + + +## Security + + +禁止： + +- SQL拼接 + +- 明文密码 + +- 敏感信息日志输出 + +``` + +以后： + +```bash +pi +``` + +任何项目默认继承。 + +--- + +# 二、CMR项目规范 + +位置： + +```text +cmr-system/AGENTS.md +``` + +这是项目核心。 + +内容： + +```markdown +# CMR System Development Guide + + +## 项目介绍 + + +这是一个企业级CRM系统。 + + +业务模块： + +- 客户管理 + +- 联系人管理 + +- 商机管理 + +- 合同管理 + +- 权限管理 + +- 数据分析 + + + +# 技术栈 + + +## Backend + + +Spring Boot 3.5 + +Java 21 + +Maven + + +## ORM + + +MyBatis Plus + + +## Database + + +PostgreSQL 16 + + +## Cache + + +Redis Cluster + + +## Search + + +Elasticsearch 8.x + + +## Message + + +Kafka 3.x + + + +# Architecture + + +采用： + +DDD + Modular Monolith + + +模块： + +customer + +├── domain + +├── application + +├── infrastructure + +└── interfaces + + + +# Package Rule + + +禁止： + +controller调用mapper + + +正确： + +Controller + + ↓ + +Application Service + + ↓ + +Domain Service + + ↓ + +Repository + + + +# Entity Rule + + +数据库Entity: + +xxxEntity + + +领域对象: + +xxx + + +DTO: + +xxxDTO + + + +# API规范 + + +返回： + +Result + + +例如： + +{ + code:0, + message:"success", + data:{} +} + + + +# Database + + +所有表： + +必须： + +- bigint主键 + +- created_time + +- updated_time + +- deleted + + +例如： + +customer_customer + + +# Testing + + +新增功能必须： + +- Unit Test + +- Integration Test + + + +# Git + + +commit格式： + +feat: + +fix: + +refactor: + +``` + +--- + +# 三、架构师角色 SYSTEM.md + +位置： + +```text +cmr-system/.pi/SYSTEM.md +``` + +作用： + +改变 Pi 思考方式。 + +内容： + +```markdown +# Role + + +你现在是CMR系统首席架构师。 + + +你的职责： + +- 设计系统架构 + +- 审查代码 + +- 发现风险 + +- 优化性能 + + + +# Architecture Principles + + +设计方案必须回答： + + +1. 为什么这样设计？ + +2. 数据如何流转？ + +3. 高并发怎么办？ + +4. 数据一致性怎么办？ + +5. 如何扩展？ + + + +# Review Standard + + +代码Review重点： + + +## Java + + +检查： + +- 空指针 + +- 线程安全 + +- 事务 + +- GC压力 + + + +## Database + + +检查： + +- 索引 + +- 慢SQL + +- 锁 + + +## Distributed + + +检查： + +- 分布式事务 + +- 重试 + +- 幂等 + + + +# Output Format + + +回答必须包含： + +## 方案 + +## 架构 + +## 代码 + +## 风险 + +## 优化建议 + +``` + +--- + +# 四、Skills设计 + +目录： + +```text +.pi/skills +``` + +Skill 是专业能力。 + +--- + +# 1. Spring Boot Skill + +文件： + +``` +.pi/skills/springboot/SKILL.md +``` + +内容： + +```markdown +--- +name: springboot-expert +description: Spring Boot enterprise development +--- + + +# Spring Boot Expert + + +关注： + +- Bean生命周期 + +- 自动配置 + +- Spring Security + +- Transaction + + +生成代码要求： + +必须包含： + +- Controller + +- Service + +- Repository + +- DTO + +- Exception + + +禁止： + +Controller写业务逻辑 + + +``` + +--- + +# 2. 数据库 Skill + +``` +.pi/skills/database/SKILL.md +``` + +```markdown +--- +name: database-expert +description: PostgreSQL/MySQL design +--- + + +# Database Expert + + +设计表必须考虑： + +- 主键 + +- 索引 + +- 分区 + +- 数据增长 + + +SQL必须提供： + +EXPLAIN分析。 + + +大表： + +超过千万： + +必须考虑： + +- 分页优化 + +- 分区 + +- 归档 + + +``` + +--- + +# 3. Elasticsearch Skill + +```text +.pi/skills/elasticsearch/SKILL.md +``` + +```markdown +--- +name: elasticsearch-expert +description: Elasticsearch CRM search +--- + + +负责： + +客户搜索 + + +要求： + +mapping明确 + +避免text误用 + + +查询必须考虑： + +- 分页 + +- 高亮 + +- 聚合 + +- 性能 + + +``` + +--- + +# 4. Kafka Skill + +```text +.pi/skills/kafka/SKILL.md +``` + +```markdown +--- +name:kafka-expert +description:kafka event architecture +--- + + +CRM事件： + +CustomerCreated + +CustomerUpdated + + +要求： + +事件必须： + +- version + +- timestamp + +- traceId + + +考虑： + +- 重试 + +- 幂等 + +- 顺序 + + +``` + +--- + +# 五、Prompt Templates + +目录： + +```text +.pi/prompts +``` + +--- + +## 创建模块 + +文件： + +``` +create-module.md +``` + +内容： + +```markdown +--- +description:create spring boot module +argument-hint:"module name" +--- + + +设计CMR模块： + +模块: + +$1 + + +输出： + +1. DDD设计 + +2. 数据库表 + +3. API + +4. Java代码结构 + +5. 测试方案 + +``` + +使用： + +```text +/create-module customer +``` + +--- + +## 代码Review + +文件： + +``` +review-code.md +``` + +内容： + +```markdown +--- +description:review java code +--- + + +请Review代码。 + + +检查： + +- 架构 + +- Bug + +- 性能 + +- 安全 + +- 可维护性 + + +输出： + +问题列表 + +修改建议 + +优化代码 + + +``` + +使用： + +```text +/review-code CustomerService.java +``` + +--- + +## SQL优化 + +``` +optimize-sql.md +``` + +```markdown +--- +description:sql optimization +--- + + +分析SQL： + +$1 + + +输出： + +1.执行计划 + +2.索引建议 + +3.SQL优化版本 + +4.风险 + +``` + +--- + +# 六、MCP配置 + +建议： + +CMR系统接： + +``` +GitHub MCP +PostgreSQL MCP +Redis MCP +Elasticsearch MCP +Kafka MCP +``` + +结构： + +```text +.pi/mcp.json +``` + +--- + +## PostgreSQL MCP + +```json +{ + "mcpServers":{ + + "postgres":{ + + "command":"npx", + + "args":[ + "-y", + "@modelcontextprotocol/server-postgres", + "postgresql://user:pass@localhost/cmr" + ] + + } + + } +} +``` + +能力： + +Pi可以： + +``` +查询客户表 +分析索引 +检查SQL +``` + +--- + +## Git MCP + +```json +{ +"git":{ + + "command":"npx", + + "args":[ + "-y", + "@modelcontextprotocol/server-git" + ] + +} +} +``` + +能力： + +``` +查看commit +分析diff +生成release note +``` + +--- + +## Elasticsearch MCP + +例如： + +```json +{ +"elasticsearch":{ + +"command":"node", + +"args":[ +"/opt/mcp/es-server.js" +] + +} +} +``` + +能力： + +``` +查询客户索引 +分析mapping +优化DSL +``` + +--- + +# 七、最终使用效果 + +启动： + +```bash +cd cmr-system + +pi +``` + +你可以直接： + +--- + +## 创建客户模块 + +``` +/create-module customer +``` + +生成： + +``` +customer-domain + +customer-application + +customer-infrastructure + +customer-interface +``` + +--- + +## Review代码 + +``` +/review-code CustomerService.java +``` + +得到： + +``` +问题: + +1.事务传播错误 + +2.Redis缓存击穿风险 + +3.SQL缺少索引 + + +修改方案: +... +``` + +--- + +## 设计架构 + +输入： + +``` +设计CMR客户360视图 +``` + +Pi 会结合： + +``` +AGENTS.md ++ +SYSTEM.md ++ +Skills ++ +MCP数据库 ++ +模型能力 +``` + +输出企业级方案。 + +--- + +# 八、针对你的技术背景推荐增强 + +你的技术栈包含 Flink/HBase/Kafka/ES，因此建议额外增加： + +``` +.pi/skills + +├── flink +│ └── SKILL.md + +├── hbase +│ └── SKILL.md + +├── kafka +│ └── SKILL.md + +├── elasticsearch +│ └── SKILL.md + +├── linux +│ └── SKILL.md + +└── kubernetes + └── SKILL.md +``` + +这样 Pi 就不只是代码生成器，而是一个： + +**Spring Boot + 大数据 + 中间件领域架构师 Agent。** + + + + + + + + + + +可以，**Windows 可以安装 Pi**，但是目前官方推荐方式不是类似 `.exe` 安装包，而是通过 **Node.js + npm 全局安装**。官方文档提供的安装方式是 npm：([Pi][1]) + +```powershell +npm install -g --ignore-scripts @earendil-works/pi-coding-agent +``` + +安装完成： + +```powershell +pi --version +``` + +启动： + +```powershell +pi +``` + +官方文档说明 Pi 本身通过 npm 分发，`--ignore-scripts` 是推荐参数，用于关闭安装阶段脚本执行。([Pi][2]) + +--- + +# 一、Windows 推荐安装流程 + +## 1. 安装 Node.js + +推荐： + +* Node.js 22 LTS +* npm 10+ + +下载： + +[https://nodejs.org/](https://nodejs.org/) + +安装后检查： + +```powershell +node -v + +npm -v +``` + +例如： + +``` +v22.18.0 + +10.9.3 +``` + +--- + +# 二、安装 Pi + +PowerShell： + +```powershell +npm install -g --ignore-scripts @earendil-works/pi-coding-agent +``` + +验证： + +```powershell +where pi +``` + +正常： + +``` +C:\Users\<用户名>\AppData\Roaming\npm\pi.cmd +``` + +--- + +# 三、Windows 推荐使用 Git Bash + +Pi 是终端 Agent，默认大量依赖 shell 命令。 + +Windows 下建议： + +安装： + +[https://git-scm.com/downloads](https://git-scm.com/downloads) + +安装完成： + +打开： + +``` +Git Bash +``` + +执行： + +```bash +pi +``` + +原因： + +你的 Spring Boot 项目会大量使用： + +```bash +git +mvn +grep +find +sed +awk +docker +kubectl +``` + +Git Bash 体验比纯 CMD/PowerShell 更接近 Linux。 + +--- + +# 四、配置 Windows Shell + +Pi 会调用 shell 执行： + +例如： + +``` +mvn test + +git diff + +docker compose + +grep +``` + +建议配置： + +文件： + +``` +C:\Users\<用户名>\.pi\agent\settings.json +``` + +创建： + +```json +{ + "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe" +} +``` + +这样 Pi 使用 Git Bash。 + +--- + +# 五、Windows 下 Pi 配置目录 + +对应 Linux： + +``` +~/.pi/agent +``` + +Windows： + +``` +C:\Users\<用户名>\.pi\agent +``` + +例如： + +``` +C:\Users\admin\.pi\agent + +├── AGENTS.md + +├── settings.json + +├── models.json + +├── skills + +├── prompts + +├── extensions + +└── sessions +``` + +--- + +# 六、配置你的 Spring Boot CMR项目 + +例如： + +``` +D:\workspace\cmr-system +``` + +结构： + +``` +cmr-system + +├── pom.xml + +├── src + +├── AGENTS.md + +├── .pi + +│ ├── SYSTEM.md + +│ │ + +│ ├── skills + +│ │ ├── springboot + +│ │ │ └── SKILL.md + +│ │ │ + +│ │ ├── postgresql + +│ │ │ └── SKILL.md + +│ │ │ + +│ │ └── kafka + +│ │ └── SKILL.md + +│ │ + +│ └── prompts + +│ ├── review-code.md + +│ └── create-module.md + +``` + +启动： + +```powershell +cd D:\workspace\cmr-system + +pi +``` + +Pi 会自动加载： + +``` +项目/AGENTS.md + +项目/.pi/SYSTEM.md + +项目/.pi/skills + +项目/.pi/prompts +``` + +--- + +# 七、Windows 配置模型代理 + +例如你的： + +* OpenAI +* Claude +* DeepSeek +* Qwen +* OneAPI + +配置： + +``` +C:\Users\<用户名>\.pi\agent\models.json +``` + +例如： + +```json +{ + "providers": { + "company-ai": { + + "baseUrl": + "https://api.example.com/v1", + + "api": + "openai-completions", + + "apiKey": + "sk-xxxx", + + "models":[ + { + "id":"deepseek-chat", + "name":"DeepSeek" + } + ] + } + } +} +``` + +启动： + +```bash +pi +``` + +查看： + +``` +/model +``` + +--- + +# 八、Windows 安装 MCP + +MCP 通常依赖： + +* Node.js +* Python +* Docker + +例如： + +## PostgreSQL MCP + +安装： + +```powershell +npm install -g @modelcontextprotocol/server-postgres +``` + +配置： + +``` +C:\Users\<用户名>\.pi\agent\mcp.json +``` + +例如： + +```json +{ + "mcpServers": { + + "postgres": { + + "command":"npx", + + "args":[ + "-y", + "@modelcontextprotocol/server-postgres", + "postgresql://user:password@localhost/cmr" + ] + + } + + } +} +``` + +--- + +# 九、Windows + Docker + Pi 推荐架构 + +你的场景（Spring Boot + Kafka + ES + PostgreSQL）： + +推荐： + +``` +Windows 11 + +| +| ++-- Git Bash +| ++-- Pi Agent +| ++-- Docker Desktop + | + | + +-- PostgreSQL + | + +-- Elasticsearch + | + +-- Kafka + | + +-- MCP Server +``` + +--- + +# 十、如果你经常开发 Java 项目，建议安装 + +## JDK + +```powershell +java -version +``` + +推荐： + +``` +JDK 21 +JDK 25 +``` + +--- + +## Maven + +```powershell +mvn -version +``` + +--- + +## Git + +```powershell +git --version +``` + +--- + +## Docker + +```powershell +docker version +``` + +--- + +# 十一、Windows 使用体验优化 + +建议： + +| 组件 | 推荐 | +| -------- | ----------------------- | +| Terminal | Windows Terminal | +| Shell | Git Bash | +| 编辑器 | IntelliJ IDEA / VS Code | +| Java | JDK 21/25 | +| 容器 | Docker Desktop | +| AI模型 | OneAPI/New API | +| Pi配置 | 项目级 `.pi` | + +--- + +# 十二、和 Claude Code Windows 对比 + +| 能力 | Pi Windows | Claude Code | +| ---------------- | ---------- | ----------- | +| npm安装 | ✅ | ✅ | +| Git Bash | 推荐 | 推荐 | +| CLAUDE.md | ✅兼容 | ✅ | +| AGENTS.md | ✅ | 部分 | +| Skills | ✅ | ✅ | +| Prompt Templates | ✅ | 弱 | +| 自定义模型 | ★★★★★ | 较弱 | +| 本地模型 | ★★★★★ | 较弱 | +| 企业Gateway | ★★★★★ | 一般 | + +--- + +结合你的环境（Windows + Spring Boot + Flink/HBase/Kafka/ES），我建议： + +``` +Windows 11 + | + +-- Git Bash + | + +-- Pi + | + +-- AGENTS.md + | + +-- Skills + | + +-- MCP + | + +-- PostgreSQL + +-- Elasticsearch + +-- Kafka + +-- Git + | + +-- OneAPI + | + +-- Claude + +-- GPT-5 + +-- DeepSeek + +-- Qwen +``` + +这套基本就是一个本地企业级 AI 开发工作台。 + +[1]: https://pi.dev/docs/latest/quickstart?utm_source=chatgpt.com "Quickstart · Documentation · Pi" +[2]: https://pi.dev/docs/latest?utm_source=chatgpt.com "Pi Documentation · Documentation · Pi" +