aps-agent/Pi-Agent接入详细计划.md

# Pi Agent 接入 · 详细实施计划

> 版本 v1.0 · 2026-09-02 · 配套摘要文档：`Pi-Agent接入计划.md`
> 依据：`plan.md` §2.1/§2.2、`PROJECT_OPERATING_RULES.md`、`docs/architecture/harness.md`、`docs/architecture/skills.md`
> 现状代码基线：`server/agent_core/`（harness `_POWER_MAP` 62 项登记、tool_runtime 只读白名单 19 项、mcp_bus、skills、audit）、`server/auth/`（JMS provider + 许可证 token + 租户）、`server/gateway/app.py`
>
> **对象界定**：Pi Agent = badlogic 开源 Pi（pi-coding-agent CLI + pi-agent-core + npm 技能包生态）。方向 A：外向接入，Pi 作为外部客户端智能体经 Gateway 调用 APS 能力，不开第二个执行通道。

---

## 0. 总览

| 阶段 | 名称 | 工期（人日） | 出口标准（Go/No-Go 门禁） |
|------|------|------------|--------------------------|
| P0 | 验证性 PoC | 2-3 | 终端内完成真实查询往返；Pi 扩展 API 三个未知数全部有答案 |
| P1 | 只读接入 | 5 | 只读意图 19 项全部可经 agent 端点调用；token 越权测试 fail-closed |
| P2 | 写操作过门禁 | 5-10 | P1/P2 意图经确认卡执行；CLI 侧确认/拒绝/超时三态可演示 |
| P3 | MCP 总线治理化 | 5-10 | Pi 插件入总线清单；契约三方同步门禁通过；管理台可见 |
| P4 | 验收与发布门禁 | 5 | 全量黄金测试绿；文档同轮完成；安全评审签字 |
| **合计** | | **22-33 人日（约 5-7 周/1 人）** | |

**串行前提**：与 Tauri 迁移不并行（都动 Gateway/sidecar 周边）；FF-01 基线已提交（8b7063f）。

---

## P0 · 验证性 PoC（2-3 人日）

### 目标
用最小成本验证"Pi 技能包 ↔ 现有 FastAPI Gateway"匹配度，产出 go/no-go。

### 任务分解

| # | 任务 | 产出 | 工时 |
|---|------|------|------|
| P0-1 | 安装 Pi（`npm i -g` pi-coding-agent），跑通官方 hello 技能包，确认扩展 API 形态（工具注册签名、权限钩子、配置落点 `~/.pi/`） | 笔记 + 截图 | 0.5d |
| P0-2 | 起本地 APS server（`.venv` 固定 CPython，`python -m uvicorn server.main:app --port 8000`），确认 `/api/health` 返回 `interfaceVersion=1.0` | 环境就绪 | 0.5d |
| P0-3 | 写最小技能包 `pi-aps`（单文件）：注册 2 个工具 `aps_health` / `aps_summary`，调 `/api/health` 与 `/api/world/summary`，结果原样透传 | PoC 技能包 | 1d |
| P0-4 | 验证 SSE：终端订阅 `/api/chat` 会话流或等价端点，确认流式事件在 CLI 可读（决定 P2 确认卡用轮询还是 SSE） | 技术结论 | 0.5d |
| P0-5 | go/no-go 报告：三个未知数（扩展 API 形态 / 认证链路 / SSE 呈现）+ P1 估算修正 | 报告 | 0.5d |

### PoC 技术约束（防止 PoC 污染产品路径）
- PoC 技能包只读、不进仓库 `apps/` 或 `server/`；放 `poc/pi-aps/`；
- 认证用开发态临时方案（环境变量 token），**不写** token 签发产品代码——那是 P1 的事；
- 遵守规范：工具失败显式报错，不包装成泛化成功回复。

### 出口标准（全部满足才进 P1）
1. 在 Pi 终端输入自然语言/命令 → 返回真实 APS 数据（非 mock）；
2. Pi 权限钩子能在工具调用前拦截（P2 确认卡的技术前提）；
3. 无明显阻塞性限制（如技能包无法持久化配置、无法发 HTTPS 到自签证书内网服务器等）。

---

## P1 · 只读接入（5 人日）

### 目标
Pi 用户可完成全部只读场景：查订单池、KPI、分桶计划、冲突、知识库。

### API 设计（新增 `/api/agent/` 适配层）

设计原则：**薄适配，零业务逻辑**（Gateway 职责边界：不含排产算法/LLM 决策）。复用 `handle_intent`，不复制逻辑。

```
POST /api/agent/invoke
  请求：{ "intent": "order.pool", "params": {...}, "requestId": "uuid" }
  响应：{ "ok": true, "intent": "...", "power": "P0", "data": {...},
          "evidenceRefs": [...], "interfaceVersion": "1.0" }
  错误：{ "ok": false, "error": { "code": "INTENT_NOT_REGISTERED" |
          "POWER_DENIED" | "CONFIRM_REQUIRED" | "UPSTREAM_FAILED", ... } }

GET  /api/agent/intents        # 列出该 token scope 可调用的意图目录（从白名单/_POWER_MAP 派生）
GET  /api/agent/intents/{name} # 单意图参数 schema（供 Pi 动态生成工具签名）
```

行为规则：
- 只读意图（tool_runtime 白名单 19 项 + `_POWER_MAP` 中 P0 项）→ 直通执行；
- P1/P2/P3 → P1 阶段一律返回 `CONFIRM_REQUIRED`/`POWER_DENIED`（P2 阶段才接通）；
- **未登记意图 → 拒绝 + 审计**（与 tool_runtime 同语义，fail closed）。

### 任务分解

| # | 任务 | 涉及文件 | 工时 |
|---|------|---------|------|
| P1-1 | `/api/agent/*` 三个端点：参数校验（Pydantic）、intent 登记检查、委托 handle_intent、统一错误码 | `server/gateway/app.py`（新增路由段，<150 行） | 1d |
| P1-2 | Agent Token：基于 `server/auth/` 既有体系签发长期 token（type="agent"，scope=["read"]），绑定租户 + device；签发/吊销登记 P2 意图 `agent.token.issue` / `agent.token.revoke` 入 `_POWER_MAP` | `server/auth/`（新增 `agent_tokens.py`）、`harness.py` 登记 2 项 | 1.5d |
| P1-3 | 审计：`actor="pi-agent:<deviceId前8位>"`，全部调用落 TOOL/AGENT 审计事件，可按 actor 过滤 | `server/agent_core/audit.py`（复用，仅扩展 actor 约定） | 0.5d |
| P1-4 | `pi-aps` v0.1：从 `/api/agent/intents` 动态生成工具集；配置项（server URL、token、超时）落 `~/.pi/aps.json`；错误码 → 人类可读终端输出 | `poc/pi-aps/` → 转正为独立 npm 包 | 1.5d |
| P1-5 | 黄金测试：端点契约、未登记意图拒绝、token 无效/越权/吊销 fail-closed、审计落链断言 | `tests/golden/test_agent_gateway.py`（新增） | 0.5d |

### 出口标准
- 只读意图 100% 可调；非只读一律显式拒绝；
- token 六种异常（缺失/伪造/过期/吊销/scope 越界/跨租户）全部 fail-closed 且有审计；
- `pytest tests/golden/test_agent_gateway.py` 全绿；`test_contract_sync.py` 不受影响。

---

## P2 · 写操作过门禁（5-10 人日）

### 目标
Pi 可发起 P1/P2 意图（试排、登记 skill 等），确认卡在终端完成人机确认。

### 确认卡交互设计（CLI 三态）

```
Pi 发起 flex.schedule（P1 草稿类）→ 直通执行，返回 evidenceRefs（含 schedule-version）
Pi 发起 schedule.publish（P2）→ /api/agent/invoke 返回 CONFIRM_REQUIRED + cardId
  → Pi 权限钩子向用户呈现确认卡摘要（动作/影响/evidenceRefs 指纹）
  → 用户批准：POST /api/actions/confirm { cardId, approved: true }（既有唯一执行通道 ✅）
  → 用户拒绝/超时（默认 5min）：fail closed，审计留痕
```

### 任务分解

| # | 任务 | 工时 |
|---|------|------|
| P2-1 | invoke 端点接通 P1 意图（沙盒/草稿语义直通，返回 evidenceRefs） | 1d |
| P2-2 | invoke 端点接通 P2：生成确认卡（复用 harness 出卡逻辑，冻结 evidenceRefs/beforeSnapshot），返回 cardId + 摘要 payload | 1.5d |
| P2-3 | token scope 升级：`read` → `read+write`（签发改 P2 确认卡；scope 与意图权力交叉校验：P2 意图必须 write scope） | 1d |
| P2-4 | pi-aps v0.2：确认卡终端 UI（摘要渲染 + y/n + 超时倒计时）；批准后轮询/SSE 拿执行结果；失败显式呈现 | 1.5-3d |
| P2-5 | 证据链黄金测试：Pi 发起的 P2 写，审计含 beforeSnapshot + evidenceRefs + `verify_pending_evidence` 缺项拒绝 | 1d |
| P2-6 | 超时/并发边界：一 token 同时仅一张 pending 卡；卡过期自动拒绝 | 1d（含测试） |

### 出口标准
- 演示脚本全绿：试排→发布→回滚三链路在 Pi 终端闭环；
- 安全测试：无卡直调 confirm、伪造 cardId、过期卡、跨 token 用卡——全部拒绝 + 审计；
- 变数说明：P2-4 的 CLI 交互若 Pi 权限钩子能力受限（P0-4 结论），可能退化为"Web 确认 + CLI 只读结果"，工期取下限。

---

## P3 · MCP 总线治理化（5-10 人日）

### 目标
Pi 接入面成为 `mcp_bus` 正式插件，享受统一治理（契约、权限、健康、启停、审计、管理台）。

### 插件 manifest（落 `server/data/mcp_plugins/plugins.json`）

```json
{
  "plugin_id": "pi-agent-gateway",
  "name": "Pi Agent 接入面",
  "version": "1.0.0",
  "min_bus_version": "1.0",
  "endpoint": "self:///api/agent",
  "tools": [
    {"name": "order.pool",    "power": "P0", "input_schema_ref": "shared/schemas/..."},
    {"name": "flex.schedule", "power": "P1", "input_schema_ref": "shared/schemas/..."},
    {"name": "schedule.publish", "power": "P2", "input_schema_ref": "shared/schemas/..."}
  ],
  "ragScopes": []
}
```

### 任务分解

| # | 任务 | 工时 |
|---|------|------|
| P3-1 | 把 `/api/agent/intents` 目录生成为 MCP manifest（自动生成 + 版本化），注册进 mcp_bus | 1.5d |
| P3-2 | tool 级 allow/deny 配置面：按现场可裁剪 Pi 可用意图（deny 优先，fail closed） | 1d |
| P3-3 | 三方契约同步：`shared/schemas/agent_invoke.schema.json` ↔ `server/contracts.py` ↔ pi-aps 类型定义；入 `test_contract_sync.py` 门禁 | 1.5d |
| P3-4 | 管理台：SkillConsole 复用双面板模式呈现 Pi 插件（概览/健康/审计/日志页签） | 2d |
| P3-5 | 健康探测：agent 端点纳入总线探测历史（最近 20 次） | 0.5d |
| P3-6 | 文档同轮：harness.md 端点备案、skills.md 增补、CHANGELOG | 0.5d |

### 出口标准
- 总线清单可见、可启停（P2 确认卡）、审计可按插件过滤；
- 契约漂移测试阻断生效（故意改一端 → CI 红）。

---

## P4 · 验收与发布门禁（5 人日）

| # | 任务 | 工时 |
|---|------|------|
| P4-1 | 全量黄金测试（基线 1071 项 + 新增 agent 专项）固定 CPython 运行时全绿 | 1d |
| P4-2 | 安全评审：token 存储（`~/.pi/aps.json` 权限 600）、传输（内网 HTTP → 建议 HTTPS 或 SSH 隧道指引）、桌面态 nonce 与 agent token 并存策略 | 1.5d |
| P4-3 | 真实场景验收：康尼数据集上跑"查询→试排→确认发布"全链路 5 轮 | 1d |
| P4-4 | 发布物料：pi-aps npm 包版本化 + 安装文档 + 现场部署 runbook | 1d |
| P4-5 | 回顾：估算偏差分析，更新本计划为 v1.1 | 0.5d |

---

## 6. 横切约束（每阶段都必须遵守，来自 PROJECT_OPERATING_RULES）

1. **无后门**：任何写路径不得绕过 `tool_runtime`/`/api/actions/confirm`；P1 起加黄金测试断言"agent 端点代码无直接 store 写调用"（import 扫描级）。
2. **失败显式**：工具失败/为空/中止 → 结构化错误码透传到终端，禁止泛化确认。
3. **状态诚实**：DRAFT/未批准/失败状态在 agent 响应中显式标注 `status` 字段，不得当完成事实。
4. **证据链**：P2/P3 写全部携带 `beforeSnapshot` + `evidenceRefs`；审计 append-only。
5. **契约三方同步**：改契约必须三端同改 + `test_contract_sync.py`。
6. **文档同轮**：每阶段收尾同步 harness.md / CHANGELOG；`docs/README.md` 铁律。
7. **运行时**：所有验证用 `.venv` 固定 CPython，禁用 PATH 上的 Anaconda python（WinError 127 前科）。
8. **提交纪律**：未经用户授权不提交/不推送；每阶段一个独立 commit，conventional 中文提交信息。

## 7. 风险登记册

| # | 风险 | 概率 | 影响 | 触发阶段 | 对策 |
|---|------|------|------|---------|------|
| R1 | Pi 权限钩子不支持异步确认交互 | 中 | P2 降级为"CLI 发起 + Web 确认" | P0-4 暴露 | PoC 即验证；降级方案可接受 |
| R2 | token 长期持有泄漏 | 低 | 数据外泄 | P1 后 | scope 最小化 + 吊销通道 + 审计告警（audit_alerts 既有） |
| R3 | Pi 上游 API  breaking change | 中 | 技能包失效 | 长期 | 技能包锁版本范围；manifest `min_bus_version` 同款声明 |
| R4 | 与现场交付（康尼/徐工）抢人力 | 高 | 双方延期 | 全程 | P0/P1 先行（可演示价值），P2+ 按交付间隙排 |
| R5 | 内网无 npm registry，技能包分发难 | 中 | 现场装不上 | P4 | 离线 tarball 分发 + runbook 写明 |
| R6 | 与 Tauri 迁移冲突 | 低 | 返工 | — | 已约定串行 |

## 8. 关键依赖与前置

- ✅ FF-01 基线已提交（8b7063f）
- ⬜ P0 需要：本机可装 Pi（npm 网络）、APS server 本地可起
- ⬜ P1 需要：确认 agent token 在桌面态（sidecar nonce 门禁）与 Web 态（JMS 登录）两种部署下的统一策略——**建议 P0 期间出结论**
- ⬜ P4 需要：康尼数据集可用

## 9. 里程碑视图

```
W1        W2        W3-4       W5-6        W7
[P0 PoC]→[P1 只读]→[P2 写门禁]→[P3 治理化]→[P4 验收]
   ↑go/no-go  ↑可演示      ↑安全评审预备   ↑发布门禁
```