13 KiB

Raw Blame History

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）

在 Pi 终端输入自然语言/命令 → 返回真实 APS 数据（非 mock）；
Pi 权限钩子能在工具调用前拦截（P2 确认卡的技术前提）；
无明显阻塞性限制（如技能包无法持久化配置、无法发 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`）

{
  "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）

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

13 KiB Raw Blame History Unescape Escape

Pi Agent 接入 · 详细实施计划

0. 总览

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

目标

任务分解

PoC 技术约束（防止 PoC 污染产品路径）

出口标准（全部满足才进 P1）

P1 · 只读接入（5 人日）

目标

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

任务分解

出口标准

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

目标

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

任务分解

出口标准

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

目标

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

任务分解

出口标准

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

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

7. 风险登记册

8. 关键依赖与前置

9. 里程碑视图

13 KiB

Raw Blame History

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

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