ppanel/docs/implementation-contract.md

8.5 KiB
Raw Permalink Blame History

PPanel 实施契约与最终项目验收

2026-09-12:用户已开启 goal,授权实现与真实验收。此文补充 API 协作边界;原 MVP 规格继续有效。

实施分工

  1. 后端 agent:apps/server/**、根 package.json、根运行脚本与 README。实现持久化调度、pi SDK 编排、Gitea、执行适配、恢复、门禁及后端测试。
  2. 前端 agent:apps/web/**、docs/frontend-reuse.md。实现严格参考 D-SRE 的工作台,与下面 API 对接。
  3. 独立 CR 与 QA:读取固定 Git SHA,检查契约与实际运行;结果在 Gitea 中文 Markdown 回报。
  4. 控制面可用后,由其内置编排 agent 自行组织 projects/agent-poker 项目。当前根对话不提前实现该项目。

采用独立 apps/server/package.json 与 apps/web/package.json,各自 npm install;不依赖共享 workspace package,避免分工时修改同一 lockfile。Node 24、TypeScript,后端 Fastify 5,数据库使用 node:sqlite;前端 React 19、Vite 8、Tailwind 4,与 D-SRE 同系依赖。后端默认 127.0.0.1:4380,前端开发端口 4381,Vite 将 /api 代理到后端;生产后端服务 apps/web/dist。

Web API 契约

所有业务文案中文。JSON 顶层始终为对象;错误 HTTP 状态码对应 { "error": "可读的中文说明" }。API 不暴露密钥。时间为 ISO 字符串。ID 服务端生成。

type TaskStatus = 'queued'|'planning'|'running'|'reviewing'|'integrating'|'completed'|'failed'|'cancelled'|'blocked'|'recovery_required';
type RuntimeId = 'pi'|'opencode'|'codex';
type Role = 'developer'|'reviewer'|'qa'|'integrator';
interface Task {
 id:string; title:string; goal:string; acceptance:string; status:TaskStatus;
 revision:number; repository:string; targetBranch:string; baseSha:string;
 issueNumber:number|null; issueUrl:string|null; headSha:string|null;
 prNumber:number|null; prUrl:string|null;
 createdAt:string; updatedAt:string; error:string|null;
}
interface Run {
 id:string; taskId:string; role:Role; runtime:RuntimeId;
 status:'queued'|'running'|'completed'|'failed'|'cancelled'|'recovery_required';
 revision:number; cwd:string; sessionId:string|null; pid:number|null;
 startedAt:string|null; endedAt:string|null; headSha:string|null; error:string|null;
}
interface TaskEvent {
 id:string; taskId:string; kind:string; role:string|null;
 body:string; createdAt:string; url:string|null;
}
方法与路径 请求 成功响应
GET /api/health 无 {ok:true, version:string}
GET /api/models 无 {models:[{id,name,model}]},本机配置中模型的安全投影
GET /api/runtimes 无 {runtimes:[{id,name,available:boolean}]}
GET /api/tasks 无 {tasks:Task[]},最近任务在前
POST /api/tasks {title,goal,acceptance?,repository?,targetBranch?,modelId?} HTTP 202 {task:Task}
GET /api/tasks/:id 无 {task:Task,runs:Run[],events:TaskEvent[]}
POST /api/tasks/:id/messages {message:string} HTTP 202 {task:Task},更新目标版本并使旧评审失效
POST /api/tasks/:id/cancel 无 {task:Task},先保存取消状态再停止子进程
GET /api/runs/:id/log 无 text/plain 完整日志,可分块传输但必须全部可取

默认仓库 https://gitea.d-robotics.cc/peng01.guo/ppanel;默认目标分支 mvp/acceptance,不存在时从 main 建立。服务仅允许配置的仓库列表,前端默认不要求用户填写 Git 内部字段。任务接受明确自定义目标分支,例如 deliveries/agent-poker。后端保证分支命名验证。

界面任务选择用 URL 保持刷新恢复。轮询即可,无须为了 MVP 增加 WebSocket。运行中界面能看到完整中文 Markdown 事件、Issue/PR 链接、执行者、状态、证据和原始日志;可补充要求、取消;浏览器关闭不影响后台。

后端闭环的具体要求

  • pi SDK 模型注册与兼容参数映射复用 D-SRE;默认首个配置模型,允许任务指定 modelId。
  • 编排者只有读仓库上下文、分派角色、记录决定、等待、失败/交付等受限工具,无代码编辑/测试 shell。它必须实际调用模型作角色选择和解释结果,不能用硬编码状态机冒充 agent;程序对不合法决定拒绝并返回理由。
  • Gitea 是业务通信来源。中文 Markdown 正文后可附 <!-- ppanel:{...} --> 最小协议元数据。完整可读信息不能仅存在于隐藏块;前端保留原始消息查看能力。
  • 单活跃根任务,执行者最多两个并行。每次角色执行独立 clone,会话与 run ID 关联。使用 worker bridge 将中文报告发布到 Gitea;stdout 不是交接消息。
  • 创建任务后,编排者先分派开发;开发提交分支和 PR 后,编排者派独立 CR、QA;不通过则继续修复,成功则集成和合入后 QA。角色由模型决定,程序只约束依赖和安全门禁。
  • 提供工具/CLI 让 worker 读取其 Issue、发布报告、创建 PR;服务端绑定角色、run_id、revision,不信任模型任意伪造 sender。凭据从 Git credential helper 获取,子 agent 不接收明文 token。
  • SQLite 保存任务、运行、事件去重、游标、待发布动作和状态。Gitea 评论发布超时必须按 event_id 查询确认,避免重复。分页轮询与重叠读取必须避免丢消息。收到 RESULT 才唤醒编排者,空闲无模型调用。
  • 执行使用独立 supervisor 进程保存运行身份与日志,服务重启检查实际进程身份,不盲目重派。无法确认时 recovery_required。外部进程可继续,服务恢复后重新观测。取消持久化在前,终止整个进程组,迟到结果只留档。
  • pi JSON print/session,OpenCode run JSON 必须显式 --dir/session,Codex App Server stdio JSON-RPC。必须正确排队/路由事件,等待 turn/completed;取消在 turn 尚未 active 时保存意图,启动后 interrupt。
  • 每次 15 分钟、根任务 90 分钟、最多 20 次执行与 3 轮修正;都可在受控本机配置调整,不能无限循环。出现超限有失败报告。
  • CR、QA、目标 revision、当前 head/base SHA 必须匹配才允许合并;禁止 force merge。Gitea 405 重算状态时有界等待 mergeable,重查版本。合入后在 merged SHA 做 QA,成功才完成。
  • 任意网页内容/外来普通评论不能成为有效 assignment/report;验证 marker、身份、run 归属及有效状态。前端 Markdown 禁止执行 HTML。
  • 暴露完整日志给本机用户,日志写入前去除凭据值,配置 API 只安全投影。控制面绑定 loopback,不能把 agent 执行入口直接公开到互联网。

最终项目:Agent 德州扑克

这是目标新增的最终验收,不替代原控制面 A01–A12。

  1. 在做好的 PPanel 页面提交一个项目目标。此后由产品内编排 agent 自行分派、复核、返工、集成;不得由当前根对话手工编写扑克业务代码或代替角色交接。
  2. 项目是虚拟筹码的多人 No-Limit Texas Hold'em 演示,没有充值、提现或真钱交易。
  3. 支持建立牌桌、邀请不同 agent 加入、展示邀请地址/接入说明;至少三位真实 agent 玩家、至少两种模型/运行时参与。
  4. 玩家通过受控接口获取只属于自己的手牌与公开桌面,提交合法动作。拒绝越权看牌、重复动作、非当前玩家动作和非法下注。不能向玩家泄露其他人的手牌。
  5. 正确执行发牌、盲注、下注轮、公共牌、弃牌、跟注、加注、all-in、边池和摊牌结算;用确定性规则测试验证牌型与筹码守恒。
  6. 提供可从外网访问的在线观测地址,界面有牌桌、座位、筹码、底池、公共牌、当前动作、时间线和局况。观察者按预定权限看牌,默认对局中不公开所有手牌。
  7. 邀请至少三位真实 agent 并完成不少于三手真实对局,留存玩家动作、模型调用与结算证据;不能用固定脚本或伪造对话冒充 agent。
  8. 观测页面支持开始/暂停或停止演示、查看已完成局历史。公网仅开放扑克项目的必要入口,管理/模型密钥不暴露;邀请 token 不进入公开 Git。
  9. 项目代码经过独立 CR、QA,由控制面交付真实 Git 提交与运行说明。在线地址实际打开验证,并在最后给用户。

本轮进度

  • M0 已完成:真实接入和协作探针,详见 connectivity-verification 文档。
  • 当前:M1–M3 开发准备与独立任务委派。
  • 后续:独立 CR、真实运行、A01–A12、最终扑克项目自主交付与在线对局。