PPanel
本地 Web 控制面:pi-agent SDK 编排开发、独立 CR、QA 与 Git 集成,Gitea 保存可读业务交流,SQLite 保存运行状态。后端监听 127.0.0.1:4380。
启动
需要 Node 24、Git credential helper 中的 Gitea 凭据,以及已经配置的 pi、opencode、codex CLI。
npm install --prefix apps/server
npm run build --prefix apps/server
npm start --prefix apps/server
前端独立安装/构建;当 apps/web/dist 存在时,后端直接托管。开发前端使用 4381,并代理 /api 到 4380。根 npm start 先构建后端;根 build/typecheck 同时检查两端。
默认模型配置只读加载 ~/.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
测试包括 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 沙箱隔离。