84 lines
5.9 KiB
Markdown
84 lines
5.9 KiB
Markdown
# Pi Agent 接入集成计划（结合现有架构与产品规范）
|
||
|
||
> 2026-09-02 · 依据：`plan.md` §2.1/§2.2（Gateway 层"Pi Agent 接入"职责）、`PROJECT_OPERATING_RULES.md`、`docs/architecture/harness.md`、`skills.md`、`overview.md`、现状代码（`server/agent_core/`：tool_runtime / mcp_bus / skills / harness / audit）
|
||
>
|
||
> **对象界定**：Pi Agent = badlogic 开源 Pi（`pi-coding-agent` CLI + `pi-agent-core` runtime + npm 技能包扩展生态）。若实际指内部自研 Agent 或其它产品，P0-P2 阶段不变，仅 P1 的接插件形态替换。
|
||
|
||
---
|
||
|
||
## 1. 接入方向决策（先定方向，再谈工期）
|
||
|
||
| | 方向 A：**外向接入**（推荐） | 方向 B：内向嵌入 |
|
||
|---|---|---|
|
||
| 含义 | APS 暴露稳定 API/MCP 面，Pi 作为**外部客户端智能体**通过技能包调用 APS 能力 | 把 `pi-agent-core` 嵌入 APS，作为通用执行 runtime |
|
||
| 与宪法兼容性 | ✅ 完全符合：Gateway 是接入层本职；写操作仍过 Harness，「LLM 只有提议权」不破 | 🔴 高风险：引入第二个工具执行通道，与 `tool_runtime`（唯一执行入口）、`_POWER_MAP`（未登记默认 P3 拒绝）直接冲突 |
|
||
| 技术栈 | 现有 FastAPI 面 + 一个 npm 技能包（TypeScript） | 需内嵌 Node runtime 或 IPC 桥，桌面 sidecar 复杂度大增 |
|
||
| 工期量级 | **5-7 周全量，2-3 天见 PoC** | 8 周以上且要重审门禁体系 |
|
||
|
||
**结论：选方向 A。** plan.md 把 Pi Agent 接入放在 Gateway 而非 Agent Core，本身就说明意图是"接入通道"而非"换引擎"。
|
||
|
||
## 2. 架构落位（与现有层一一对应）
|
||
|
||
```
|
||
Pi CLI（用户终端）
|
||
└─ pi-aps 技能包（npm，新开发） ← 唯一新增的外部组件
|
||
└─ HTTPS → Gateway (BFF) ← 既有面，加 /api/agent/* 适配
|
||
├─ 认证：Agent Token（新，基于既有 JMS/租户体系签发）
|
||
├─ 只读意图 → tool_runtime 只读白名单（已存在）✅ 零改动
|
||
├─ 写意图 → _POWER_MAP 登记 → P2/P3 确认卡 ✅ 既有机制
|
||
│ └─ Pi 侧权限钩子 ← 确认卡状态轮询/SSE
|
||
└─ 审计：actor="pi-agent:<device>"，全链路证据链 ✅ 既有机制
|
||
治理面：Pi 接入在 mcp_bus 登记为插件（tool 级 allow/deny、健康探测、启停）✅ 总线已有
|
||
```
|
||
|
||
**核心原则：不为 Pi 开任何后门。** 所有写路径复用 `/api/actions/confirm` 唯一执行通道；Pi 只是"另一个 UI 入口"，和 Web 前端同权同级。
|
||
|
||
## 3. 分阶段计划与工期估算
|
||
|
||
### P0 · 验证性 PoC（2-3 天）
|
||
- 跑通 Pi 扩展机制：开发最小技能包 `pi-aps`，调通 `GET /api/health`（校验 `interfaceVersion`）+ `GET /api/world/summary`
|
||
- 验证三件事：① Pi 技能包的工具注册/权限钩子 API 形态；② 认证链路（先用开发态 token）；③ SSE 会话流在终端的呈现方式
|
||
- **产出**：PoC demo（终端里问"当前 KPI"→ 真实数据）+ go/no-go 报告
|
||
- 人力：1 人 × 2-3 天
|
||
|
||
### P1 · 只读接入（1 周）
|
||
- Gateway 新增 `/api/agent/` 适配层：把只读意图白名单（`order.pool`/`plan.buckets`/`conflict.list`/`knowledge.query` 等 19 个）封装为 agent 友好的 JSON-RPC 风格端点
|
||
- Agent Token 签发与吊销（P2 确认卡管理，落 `~/.aps` 或租户库；scope 到只读）
|
||
- `pi-aps` v0.1：查询类命令全集 + 错误透传（遵守规范：失败显式报告，不泛化确认）
|
||
- 黄金测试：agent 端点契约 + token 越权 fail-closed
|
||
- 人力：1 人 × 1 周
|
||
|
||
### P2 · 写操作过门禁（1-2 周）
|
||
- P1/P2 意图（如 `flex.schedule` 试排草稿、`skill.enable`）接入：确认卡在终端呈现为 Pi 权限确认钩子，批准后走 `/api/actions/confirm`
|
||
- 证据链贯穿：Pi 发起的 P2/P3 写同样冻结 `evidenceRefs`/`beforeSnapshot`，审计 `actor=pi-agent` 可独立过滤
|
||
- **关键约束**（来自 PROJECT_OPERATING_RULES）：不得引入隐式副作用；DRAFT/未批准状态不得当事实返回给 Pi
|
||
- 人力：1 人 × 1-2 周（确认卡异步交互在 CLI 的 UX 是主要变数）
|
||
|
||
### P3 · MCP 总线治理化（1-2 周）
|
||
- Pi 接入面在 `mcp_bus` 登记为正式插件：manifest + 工具契约（input/output JSON Schema + P0-P3 权力标注）+ tool 级 allow/deny + 健康探测 + 启停
|
||
- 三方契约同步：`shared/schemas/` ↔ `contracts.py` ↔ 技能包类型定义，纳入 `test_contract_sync.py` 门禁
|
||
- 管理台：SkillConsole 同款 UI 呈现 Pi 插件（概览/健康/审计/日志）
|
||
- 人力：1 人 × 1-2 周
|
||
|
||
### P4 · 验收与发布门禁（1 周）
|
||
- 全量黄金测试（当前基线 1071 项）+ agent 专项；文档同轮（harness.md 端点备案、skills.md、CHANGELOG）
|
||
- 安全评审：token 泄漏面、桌面态 nonce 与 agent token 的并存策略
|
||
- 桌面端打包冒烟（sidecar 不变，风险低）
|
||
- 人力：1 人 × 1 周
|
||
|
||
**合计：1 人约 5-7 周；P0+P1（只读可用版）2 周内可演示。**
|
||
|
||
## 4. 风险与规范映射
|
||
|
||
| 风险 | 等级 | 规范依据与对策 |
|
||
|------|------|---------------|
|
||
| 第二个执行通道绕过 Harness | 🔴 | 铁律：所有写走 `tool_runtime`/`/api/actions/confirm`；加黄金测试断言"agent 端点无直写 store" |
|
||
| 确认卡在 CLI 的异步 UX | 🟡 | P2 阶段先做同步轮询版；超时自动拒绝（fail closed） |
|
||
| Agent token 权限蔓延 | 🟡 | scope 最小化（先只读）；签发/吊销走 P2 确认卡；审计独立 actor |
|
||
| Pi 上游版本漂移 | 🟡 | 技能包锁定 Pi 版本范围；`min_bus_version` 同款兼容声明 |
|
||
| 与 Tauri 迁移抢人力 | 🟡 | 两者都动 Gateway/sidecar 周边——**建议串行**：先 Pi 接入 P0-P1（不动壳），Tauri 决策等 WebView2 调查 |
|
||
|
||
## 5. 建议的下一步
|
||
|
||
先跑 **P0（2-3 天）**：成本最低，直接验证"Pi 技能包 ↔ 现有 Gateway"的匹配度，产出 go/no-go。P0 不过，后面全部不用谈；P0 过了，P1 的估算就有实测依据了。
|