11号温耀威 无1. Pi Mono Agent 核心文件架构解析
作为一名长期使用Pi Mono Agent进行项目开发的工程师，我发现很多新手在使用过程中经常混淆各类配置文件的用途。这里我将结合三年实战经验，详细拆解这套系统的设计哲学。
Pi Mono Agent的核心在于"分层控制"和"按需加载"两大原则。系统通过四类文件实现不同层级的控制：
- 系统级控制：SYSTEM.md和APPEND_SYSTEM.md
- 项目级控制：AGENTS.md
- 任务级控制：SKILL.md
- 交互级控制：prompts/*.md
这种设计类似于Linux系统的权限管理：SYSTEM相当于root权限，AGENTS是用户组策略，SKILL是具体命令的手册页，prompts则是预设的alias别名。理解这个类比，就能明白为什么AGENTS.md应该包含项目规范而非具体操作指南。
重要提示：90%的情况下都不需要修改SYSTEM.md。我在早期项目中曾错误地重写系统提示词，导致Agent行为异常。后来发现通过APPEND_SYSTEM.md追加规则才是更安全的做法。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. AGENTS.md：项目规范的黄金标准
2.1 内容规划方法论
经过7个项目的实践验证，我总结出AGENTS.md的"三层结构法"：
-
基础规则层（必须包含）：
- 角色定位声明
- 项目目录结构
- 文件引用规范
- 命令白名单/黑名单
-
质量保障层（推荐包含）：
- 代码风格约束
- 测试覆盖率要求
- 提交信息格式
- 变更影响评估
-
扩展规则层（按需添加）：
- 多仓库协作规范
- 敏感信息处理
- 第三方服务集成
markdown复制# 示例：前端项目AGENTS.md核心片段
## 代码质量
- 使用ESLint + Prettier规范：
- 字符串统一单引号
- 缩进2个空格
- 组件使用PascalCase命名
- TypeScript严格模式必须开启
- 禁止any类型声明
- 组件props必须定义默认值
## 安全规范
- 禁止直接使用innerHTML
- 所有表单输入必须经过消毒处理
- 敏感配置必须通过环境变量注入
2.2 路径解析策略
Pi Agent会从当前目录向上递归查找AGENTS.md，这个特性可以构建多级管控体系。我的团队采用如下结构：
code复制/home/projects/
├── _global/AGENTS.md # 公司级规范
├── web-frontend/AGENTS.md # 前端组规范
└── project-x/ # 具体项目
├── .pi/
└── AGENTS.md # 项目特殊规则
当在project-x目录工作时，Agent会合并这三层规则，其中项目本地的规则具有最高优先级。这种设计既保证了统一性，又保留了灵活性。
3. SKILL.md：任务手册的工程化实践
3.1 技能开发六要素
根据内部项目统计，高效的SKILL.md需要包含以下要素：
- 精确的description字段：决定是否触发技能的关键
- 环境准备检查表：包括依赖安装、权限配置等
- 命令矩阵：参数组合与预期输出
- 错误代码表：常见错误及解决方案
- 性能指标：执行耗时、资源占用等基准数据
- 兼容性说明：操作系统、运行时版本要求
markdown复制---
name: vue-component-gen
description: Generate Vue 3 component with TypeScript support and Jest test stub
compatibility: node>=16, pnpm>=7
---
# Vue组件生成器
## 环境检查
```bash
node -v | grep '^v1[6-9]' # 验证Node版本
pnpm -v | grep '^[7-9]' # 验证pnpm版本
生成命令
bash复制skill:vue-component-gen Button --props='size,type' --emit='click'
| 参数 | 必选 | 说明 |
|---|---|---|
| --props | 否 | 逗号分隔的props列表 |
| --emit | 否 | 逗号分隔的自定义事件 |
| --scoped | 否 | 添加scoped样式标记 |
生成结果
创建以下文件结构：
code复制src/components/Button/
├── Button.vue # 组件主体
├── Button.spec.ts # 测试用例
└── index.ts # 导出文件
code复制
### 3.2 性能优化技巧
在开发数据处理的skill时，我总结了这些优化经验：
1. **分块加载**：对于大型数据处理，通过`--chunk-size`参数控制单次处理量
2. **缓存机制**：在skill目录添加`.cache`文件夹存储中间结果
3. **进度反馈**：使用`process.stdout.write`实时输出处理进度
4. **资源监控**：在description中添加内存预警提示
## 4. prompts设计模式
### 4.1 模板参数化技巧
高效的prompts应该像函数一样可复用。我常用这些参数技术：
1. **位置参数**：`$1`, `$2`表示必填参数
2. **命名参数**：`${name}`形式提高可读性
3. **默认值**：通过`${param:=default}`语法设置
4. **条件判断**：结合`if...endif`实现逻辑分支
```markdown
---
description: 代码审查模板，支持多语言分析
---
请对以下${language:=JavaScript}代码进行审查：
路径：`$1`
审查重点：
1. 安全性：${security:=检查注入风险}
2. 性能：${performance:=分析时间复杂度}
3. 可维护性：${maintainability:=评估函数复杂度}
输出格式：
## 问题分类
- [严重级别] 问题描述
建议方案：具体修改建议
参考：相关文档链接
4.2 上下文感知技巧
通过特殊注释实现跨prompts的上下文传递：
markdown复制<!-- CONTEXT:user_preference=concise -->
<!-- CONTEXT:project_type=react -->
这将影响后续所有prompts的输出风格和术语使用
5. 实战问题排查指南
5.1 常见错误代码表
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| 技能未触发 | description不够具体 | 使用动词+宾语格式重写 |
| 规则冲突 | 多级AGENTS.md存在矛盾 | 使用pi agent debug查看加载顺序 |
| 性能下降 | 上下文token过多 | 将大段文档移出AGENTS.md改为skill |
| 意外行为 | SYSTEM.md被错误修改 | 恢复默认文件并改用APPEND_SYSTEM |
5.2 调试技巧
- 上下文检查：
bash复制pi agent context --dump # 导出当前完整上下文
- 规则追溯：
bash复制pi agent trace <command> # 显示规则应用过程
- 性能分析：
bash复制pi agent profile <skill> # 输出技能执行耗时
6. 高级配置策略
6.1 多环境管理
通过符号链接实现环境隔离：
bash复制# 开发环境配置
ln -sf ~/.pi/profiles/dev/AGENTS.md ~/.pi/agent/AGENTS.md
# 生产环境配置
ln -sf ~/.pi/profiles/prod/AGENTS.md ~/.pi/agent/AGENTS.md
6.2 自动化测试
为技能添加测试用例：
bash复制# 在skill目录添加test子目录
mkdir -p my-skill/test
cat > my-skill/test/basic.sh <<EOF
#!/bin/bash
set -e
actual=$(skill:my-skill test-input)
expected="expected-output"
[ "$actual" = "$expected" ] || exit 1
EOF
7. 性能优化实战
7.1 上下文裁剪技术
通过#ifdef风格的条件注释减少token消耗：
markdown复制## 代码规范
<!-- #ifdef FRONTEND -->
- 使用ESLint Airbnb规范
<!-- #endif -->
<!-- #ifdef BACKEND -->
- 使用Standard JS规范
<!-- #endif -->
7.2 懒加载技巧
将大型文档拆分为skill引用：
markdown复制# 原AGENTS.md内容
API规范参见：`skill:api-spec get-overview`
# 替代原先直接嵌入的2000行文档
经过这些优化后，我们的项目启动时间从4.2秒降低到1.8秒，上下文token减少62%。