5.9 KiB

Raw Blame History

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 的估算就有实测依据了。

5.9 KiB Raw Blame History Unescape Escape