π的三层架构#

• Pi 分三层：pi-ai（管模型）→ pi-agent-core（管循环）→ pi-coding-agent（管业务）
• 分层的核心规则是依赖方向单向向上，底层对上层一无所知
• 类型从底层到顶层逐步扩展：Tool → AgentTool → ToolDefinition
• 三层不是必须的，层数取决于你的复杂度；但依赖方向控制是必须的

可学习的地方#

1. “依赖漏斗”分层#

是什么：设计包结构的时候，画出依赖箭头。底层是“不知道外面世界的”，中间层是”知道底层但不知道业务”，顶层是“知道一切”
怎么做：

1. 找出代码里完全不依赖外部知识的部分放底层
2. 找出依赖底层但是不知道具体业务的部分放中间层
3. 找出知道用户要什么的部分放顶层
4. 检查：如果有任何高层的东西被下层 impor，分层有问题
   验证：如果去掉上层，这一层还能不能跑？如果能跑，那么依赖方向正确，反之则有泄露，属于上层的部分泄露到了下层

2. “类型递进扩展”#

是什么：底层定义最小的类型接口，上层通过联合类型或继承来扩展，而不是修改底层类型
怎么做：

1. 底层定义原子类型（如 Tool = { name, description, parameters }）
2. 中间层用继承扩展（如 AgentTool extends Tool，加上 execute）
3. 顶层叠加业务属性（如 ToolDefination）
4. 每一层只加自己关心的事
   底层可以独立发布或者被复用，其余层可以引入底层而无需引入整个 agent 框架