PPanel
本地 Web 控制面:pi-agent SDK 编排开发、独立 CR、QA 与 Git 集成,Gitea 保存可读业务交流,SQLite 保存运行状态。后端监听 127.0.0.1:4380。
启动实际 Web 与后端
需要 Node 24、Git,以及已配置的 pi、opencode、codex CLI。Gitea 凭据从本机 Git credential helper 获取,不写入仓库、命令参数或前端配置。下面命令均从仓库根目录执行。
node --version
npm ci --prefix apps/server
npm ci --prefix apps/web
npm run typecheck
npm run build
npm start
浏览器打开 http://127.0.0.1:4380。生产方式由后端同时提供 apps/web/dist 和 /api,不需要另起静态服务器。必须先完成两端构建;根 npm start 只重新构建后端,不更新前端产物。根 build/typecheck 已覆盖两端,因此无需新增入口。
建议显式固定运行数据目录,避免不同启动目录产生不同数据库;例如从仓库根目录运行:
PPANEL_DATA="$PWD/.ppanel/control" npm start
npm start --prefix apps/server 的实际工作目录为 apps/server,未设置 PPANEL_DATA 时数据在 apps/server/.ppanel。数据包含 SQLite、任务独立 clone、会话与完整脱敏日志,不提交 Git。
开发模式使用两个终端,在根目录执行:
# 终端一:后端 4380
PPANEL_DATA="$PWD/.ppanel/control" npm start
# 终端二:Vite 4381,/api 代理到 4380
npm run dev --prefix apps/web
打开 http://127.0.0.1:4381。后端没有自动重编译监听,修改后端后需重启;前端由 Vite 热更新。隔离检查可使用 PPANEL_PORT=4488 PPANEL_DATA="$PWD/.ppanel/check" npm start,然后访问 http://127.0.0.1:4488;开发代理仍固定为 4380,隔离检查应使用生产页面。
在启动终端按 Ctrl-C 停止服务。关闭浏览器不会停止后台任务;停止控制面也不等于取消独立 supervisor。需要终止任务时先使用页面取消,再停止服务;保留原数据目录用于下次恢复,不删除运行数据来模拟取消。
默认模型配置只读加载 ~/.d-sre-agent/config/sre-agent.yaml,使用 D-SRE 的 llm.items 格式;模型映射参考其 packages/agent-core/src/model-provider/ 的配置语义,包括本地 provider ID、上游 model ID 和 OpenAI compat 参数。不复制其密钥或依赖整个参考项目。SDK 固定 0.85.0。
可通过本机环境调整:
| 环境变量 | 默认 |
|---|---|
PPANEL_MODEL_CONFIG |
~/.d-sre-agent/config/sre-agent.yaml |
PPANEL_DATA |
当前目录 .ppanel |
PPANEL_PORT |
4380 |
PPANEL_REPOSITORIES |
https://gitea.d-robotics.cc/peng01.guo/ppanel,逗号分隔允许列表 |
PPANEL_RUN_MINUTES |
15 |
PPANEL_TASK_MINUTES |
90 |
PPANEL_MAX_RUNS |
20 |
PPANEL_MAX_CORRECTIONS |
3 |
工作流程
通过 POST /api/tasks 提交 {title,goal,acceptance?,repository?,targetBranch?,modelId?},获得 HTTP 202。默认目标分支 mvp/acceptance,不存在则从 main 建立。运行期间可补充要求或取消,详情、原始事件和完整脱敏日志由契约 API 提供。
模型只能调用受限决定工具,不能编辑代码或执行测试。每次分派创建子 Issue、独立 clone 和 supervisor;最多两位执行者并行。角色报告通过 worker.js 从绑定会话发布,身份、revision 和 SHA 由服务校验。报告必须有中文正文与仓库证据链接。独立 CR/QA 同版本通过后合并;合入后 QA 通过才完成。
supervisor 独立于 HTTP 服务存活,保存 PID、启动身份、会话和日志。服务恢复会核对实际进程;未知身份标记 recovery_required。关闭浏览器无影响。取消先持久化,再请求运行进程停止。运行目录是协作隔离,不是操作系统安全沙箱。
验证
npm run typecheck --prefix apps/server
npm run build --prefix apps/server
npm test --prefix apps/server
npm test --prefix apps/web
npm run test:e2e --prefix apps/web
node acceptance/control-plane/check.mjs "$PWD" all
测试包括 SQLite 去重/重启、SHA/revision 门禁、Codex 连续事件读取、HTTP 状态/单活跃任务/取消与配置安全投影。真实联调证据及已知限制记录在 Issue #6;单测不代表冻结 A01–A12 或最终项目验收通过。开发者不自行宣布最终验收。
冻结验收文件与升级
后端在首次开发前,从目标基线自动冻结已有测试/验收目录(如 tests/、e2e/)及 test_*、*.test.*、*.spec.* 文件。acceptance/ 可以包含被测业务实现,因此只按测试文件命名规则及验收文档(.md)、摘要清单(.sha256/.sha512)自动识别,不整目录冻结;显式声明仍优先保护。任务描述中“冻结/不可修改”后用反引号指定的基线文件也会纳入。对于不符合这些命名的验收程序,创建任务可附加 acceptanceFiles: ["checks/paging.py"];路径必须已存在于基线。新增项目尚不存在的测试不会被冒充为开发前冻结程序,正式验收样本必须先准备基线程序。
根 Issue 公布原始 blob、mode 和 SHA-256 清单摘要,worker 的 read 响应包含同一清单。清单不可被开发者报告、后续候选或目标分支前进覆盖。修改业务代码允许,修改、删除、改名、替换冻结文件会阻断开发通过报告、合并以及合入后 QA 分派。已有测试不能在原文件内增加断言,需新增测试文件;这是冻结样本的明确约束。
升级后不从普通事件表推断旧报告可信:活跃任务若缺少独立已发布 outbox 来源记录,会进入 recovery_required,不沿用旧评审合并。已完成历史记录保持原样。Codex 执行者使用已授权的 danger-full-access / never 配置以完成真实开发;这不提供 OS 沙箱隔离。
当前集成与验收范围
本集成分支汇入独立通过的后端 a953ed02、前端 2b1b3d5、样本 v2 efa390c 与控制面故障程序 ae01ccff,固定交付 SHA 和本轮证据以 Gitea Issue #25 为准。默认目标分支为 mvp/acceptance;尚未获准推进 main。
前端 e2e 使用真实本机 Google Chrome,但 /api 是明确的契约替身,占用 4380/4381,运行前需停止占用这些端口的服务。控制面 20 场景包含受控故障注入,不能代替真实模型或 Gitea 全链路。生产方式的只读联调只检查真实 API、空任务页与创建表单,不提交任务。
样本以 acceptance/FROZEN.v2.sha256 为当前冻结依据,v1 清单仅保留历史。原样样本故意保留缺陷:HTTP 8 失败/2 通过,真实 Chrome 浏览器 5 失败/0 通过;这些预期失败不是产品交付成功。详见 acceptance/README.md。
A01–A12、两个真实 A02、真实 A03 返工与最终扑克项目尚不能由这些集成检查宣告通过。正式 A02/A03 由独立验收 Issue #26 在固定完整 SHA 执行;本阶段不提交真实任务。
角色私有临时文件(A05 修复)
新启动或续报的每个 run 在自身运行目录下使用 tmp/,TMPDIR、TMP、TEMP 均指向它;PPANEL_REPORT_PATH 指向本 run 的 tmp/report.md。执行者应将临时脚本、报告与测试输出写入这里,不硬编码共享 /tmp,不读取其他角色目录。worker 的 read 响应提供同一 workspace 路径;pr/report 桥对文件 realpath 校验,拒绝本 run 根目录以外的报告及越界符号链接。
这是协作规则与报告桥边界,不是操作系统沙箱,也不改变已经运行的旧 supervisor 环境。完整事件原文由任务详情保留,完整运行日志通过 GET /api/runs/:id/log 获取。正文/链接显示修复已随独立通过的前端 2b1b3d5 集成;完整原文仍可查看。当前版本供 #26/#35 独立真实验收,不代表最终验收通过。