# PiE

**Repository Path**: nopc/pie

## Basic Information

- **Project Name**: PiE
- **Description**: Pi code agent Extensions.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PiE — Pi code agent Extensions

为 Pi code agent 提供一套定制的扩展，构建安全、可靠、高效、准确的 AI 工作流。

## 架构分层

PiE 采用两层架构：基础层由 aft-pi 承担代码分析与工具增强，工作流层由 PiE 自研扩展承担流程控制与编排。

```
工作流层 (PiE)   Decision-gate → Subagents → Todo → WebSearch
                   决策门禁        并行编排    任务管理   外部搜索

基础层 (aft-pi)   LSP 诊断 · 调用图导航 · 语义搜索 · 符号检查
                  read/write/edit/grep/bash 增强替换
                  Safety 文件撤销 · 格式化 · AST 搜索替换
```

## 基础层 — aft-pi

[aft-pi](https://github.com/cortexkit/aft) 已经覆盖了 LSP、DAP、代码导航、语义搜索、安全工具等基础设施能力。**审计结论：安全可用，无恶意提示词注入**。审计笔记见 [audit-aft.md](./docs/audit-aft.md)。

PiE 不再重复实现基础层能力，直接集成 aft-pi 作为底层。

## 工作流层 — PiE 自研扩展

| 优先级 | 扩展 | 状态 | 简要描述 |
|--------|------|------|----------|
| P1 | Decision-gate | v0.2 完成 | 决策门禁，Agent 在关键节点须获得用户确认方可继续 |
| P2 | Subagents | v0.1 完成 | 子智能体委托，隔离上下文，Single 模式 |
| P3 | Todo | v0.2 完成 | 会话内任务管理，三态模型，自定义渲染 |
| P4 | WebSearch | 待开工 | Web 搜索工具，Agent 可检索外部信息辅助决策 |

## 整体开发计划

| 序号 | 任务 | 依赖 | 说明 |
|------|------|------|------|
| 1 | Subagents v0.1 | — | Single 模式：spawn 隔离 + 能力注入 + Footer 状态栏 |
| 2 | Subagents v0.2 | 1 | Parallel / Chain 模式 + Widget 面板 |
| 3 | 预设 agent 定义 | 1 | 6 个开箱即用的 agent（explorer/worker/debugger/reviewer/planner/designer） |
| 4 | Decision-gate v0.3 | — | 豁免持久化 + 自定义渲染 + `/decision-log` 命令 |
| 5 | Subagents v0.3 | 2, 4 | Decision-gate 继承语义 |
| 6 | Todo v0.1 | — | 基础 CRUD + session details 持久化 + `/todos` 命令 |
| 7 | Todo v0.2 | 6 | 自定义渲染（renderCall/renderResult） |
| 8 | WebSearch 设计 + 实现 | — | 需求调研 → 设计 → 实现 |

当前第一个要开工的是 **Subagents v0.1**。

## 设计原则

见 [AGENTS.md](./AGENTS.md)。核心原则：安全可控、会话完整、准确可验证、最小可用优先、可组合不耦合。

---

## 1. Decision Gate

### 定位

在 Agent 执行流程中设置关键决策点，Agent 须向用户展示决策内容并获取显式确认方可继续。

区别于 Pi 内置的 permission-gate（危险操作拦截），decision-gate 处理的是**需要人的判断力介入的业务决策**。

### 典型场景

- 大范围文件修改（重构、批量重命名）
- 架构选型（库/框架/模式）
- 数据迁移方案选择
- 删除功能模块
- 外部服务调用

### 核心能力

- Agent 通过 `request_decision` 工具主动提交决策，附带选项和上下文
- 门禁状态：pending / approved / rejected
- 用户可对某类决策设置会话级豁免
- 所有决策记录写入 session entry，可回溯审计

### 待定

- 超时处理策略：阻塞等待 vs 默认拒绝 vs 超时自动通过
- 决策选项的 UI 呈现形式
- 对 aft-pi 增强工具（write、edit 等）的门禁兼容性

---

## 2. Subagents

### 定位

将复杂任务委托给独立的子智能体，每个子智能体拥有隔离的上下文窗口，支持并行或链式编排。

### 参考

Pi 示例中的 [subagent/](https://github.com/earendil/pi) 完整实现：独立 `pi` 子进程、三种编排模式、Agent 定义文件、流式输出和用量统计。

### 核心能力

- 子智能体默认 `--no-extensions --no-skills` 干净启动
- 按需通过 `--extension` / `--skill` 显式注入所需能力（如注入 aft-pi）
- Single / Parallel / Chain 三种编排模式
- Agent 定义文件：YAML frontmatter + Markdown system prompt

### 待定

- 安装方式（pi package vs symlink）
- 子智能体失败时的降级策略
- Parallel 模式的并发上限
- 与 decision-gate 的交互（子智能体是否受同一门禁约束）

---

## 3. Todo

### 定位

Agent 在会话中维护可操作的任务列表，用户也可通过命令直接管理。

### 参考

Pi 示例中已有的 [todo.ts](https://github.com/earendil/pi) 实现：状态存储在 tool result 的 `details` 中，天然跟随会话分支。

### 核心能力

- 纯文本任务项的增删改查和状态切换
- 状态跟随 session 分支，fork/clone 时自动隔离
- `/todos` 命令供用户直接操作
- 系统 prompt 中展示当前任务列表，引导 Agent 主动使用

### 待定

- 是否需要额外字段（优先级、截止时间等）
- 持久化机制选型：session details vs 外部文件
- 与 subagents 的交互方式

---

## 4. WebSearch

### 定位

为 Agent 提供 Web 搜索能力，在需要外部信息时自主发起搜索并整合结果。

### 核心能力

- 搜索 API 调用，返回标题 + URL + 摘要
- 结果缓存以节省 API 费用
- 搜索结果可追溯，不编造

### 待定

- 搜索后端选型（Google Custom Search、Brave、SerpAPI 等）
- API Key 配置方式
- 是否每次搜索需用户确认（隐私/成本）
- TUI 中的搜索结果渲染