本地开发指南

环境要求

前端包管理使用 pnpm。
Backend 使用 uv 管理 Python 依赖。
本地 PostgreSQL 与 Redis 通过 scripts/dev/compose.infra.yml 启动。
runtime/ 是演示运行时服务，进入子目录后按它自己的 package.json 执行命令。

本地启动总览

本地完整联调需要基础服务与四个应用进程：

scripts/dev/compose.infra.yml：只启动 PostgreSQL 与 Redis。
Backend：监听 127.0.0.1:8000，负责 API、登录、AI Agent、预览 artifact、截图和构建任务。
Runtime：监听 127.0.0.1:7373，负责预览、代码检查和构建。
Editor：监听 Vite 默认端口，负责创作工作台页面。
Renderer：监听 127.0.0.1:7400，运行真实 Chromium 截图和渲染诊断。

如果这些服务已经在本机运行，先用 docker compose -f .\scripts\dev\compose.infra.yml ps 或查看现有终端确认状态，不要重复启动。

本地基础服务

在仓库根目录启动 PostgreSQL 与 Redis：

powershell

docker compose -f .\scripts\dev\compose.infra.yml up -d

scripts/dev/compose.infra.yml 统一定位为本地开发和 CI 测试共享的基础设施入口，不属于 deploy/ 下的交付部署模板。当前 .github/scripts/*、本指南、测试治理文档和 Backend README 都统一引用该路径。

Backend 测试默认会把 REDIS_URL 设置为 memory://test，不依赖本机 Redis。手动联调时运行态按 REDIS_URL 选择后端：配 memory://lite（或任意 memory://<name>）即使用进程内适配器，无需启动 Redis，重启后临时 artifact 失效；需要跨进程共享、更长保留或按常规部署一致性验证时，再启动 scripts/dev/compose.infra.yml 中的 Redis 并把 REDIS_URL 指过去。AI run/HITL 状态由 Backend 主库中的平台运行态表承担，两种运行态后端都不影响它；边界见运行态存储适配器。

环境变量准备（全仓统一）

仓库支持全仓环境变量统一管理。推荐在根目录下一次性初始化，各子模块（Backend、Runtime、Renderer、Editor）会自动向上级联继承：

powershell

if (-not (Test-Path .\.env)) { Copy-Item .\.env.example .\.env }
pnpm run env:check

运行 pnpm run env:check 可自动验证全仓端口、跨服务内部调用地址、Audience 声明与共享密钥的一致性。如需对特定模块做临时覆盖，仍可在对应子目录下维护独立的 .env。

Backend 本地启动

以下命令均从仓库根目录执行。首次启动先同步 Python workspace、迁移数据库并初始化管理员；已有数据时不需要重复初始化：

powershell

uv sync --all-packages --all-groups --all-extras
uv run --project backend alembic -c backend/alembic.ini upgrade head
uv run --project backend python -m app.scripts.seed_admin

从仓库根目录启动 Backend 开发服务；--reload-dir backend 只监听 Backend 源码，不扫描整个仓库：

powershell

uv run --project backend uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000 --reload --reload-dir backend

默认管理员账号来自根目录 .env（或 backend/.env）：admin / Admin123456。如果需要调整默认账号，修改 DEFAULT_ADMIN_USERNAME、DEFAULT_ADMIN_PASSWORD 和 DEFAULT_ADMIN_DISPLAY_NAME 后重新启动 Backend。

Renderer 本地启动

依赖同步后，在仓库根目录安装 Python Playwright 对应的 Chromium，并使用独立包入口启动：

powershell

uv run --project renderer playwright install chromium
uv run --project renderer uvicorn wp_renderer.main:app --host 127.0.0.1 --port 7400

Linux 首次安装浏览器时使用 playwright install --with-deps chromium。Node Playwright 与 Python Playwright 的浏览器版本分别由 pnpm 和 uv 锁文件约束，两者都需要安装。

Renderer 的 RENDER_WORKER_ID、共享凭据与 profile 必须匹配 Backend 配置。启动流程及镜像说明见 Renderer README。

Runtime 本地启动

Runtime 是演示文稿运行时包。前端依赖统一走根目录 pnpm workspace（唯一 pnpm-lock.yaml）。首次启动前在新的终端中：

powershell

# 仓库根目录一次性安装 workspace（含 editor / runtime）
pnpm install
pnpm --filter web-runtime-vue dev

默认配置下 Runtime 监听 127.0.0.1:7373，并通过 http://127.0.0.1:8000 回源 Backend。所有通信地址已在根目录 .env 中预先对齐自洽。

Editor 本地启动

首次启动前在新的终端中，从仓库根目录启动（依赖已在 pnpm install 时装好，自动继承根目录 .env）：

powershell

pnpm --filter editor dev

Editor 默认通过 Vite 代理把同源 /api 转发到 Backend（默认 http://127.0.0.1:8000）。本地登录时优先使用 Editor 页面入口，不要混用 localhost 和 127.0.0.1，避免 Cookie 站点不一致导致后续接口返回 401。

根仓测试入口

powershell

pnpm install
pnpm run test:backend
pnpm run test:editor
pnpm run test:editor:check
pnpm run test:editor:build
pnpm run test:editor:gate
pnpm run test:runtime
pnpm run test:runtime:gate
pnpm run test:contracts
pnpm run test:e2e

常用分层：

pnpm run test:backend：Backend pytest。
pnpm run test:editor：Editor Vitest。
pnpm run test:editor:check：Editor 类型检查，执行 vue-tsc -b。
pnpm run test:editor:build：Editor 生产构建，执行 vue-tsc -b && vite build。
pnpm run test:editor:gate：Editor 质量门禁，执行 check + test + build。
pnpm run test:runtime：只执行 Runtime Vitest。
pnpm run test:runtime:gate：执行 Runtime check + test + build。
pnpm run test:contracts：根仓跨模块契约测试，不等同于 backend/tests/contracts。
pnpm run test:e2e:run：只执行 Playwright。
pnpm run test:e2e：先重置/播种 smoke 数据并确认服务，再执行 Playwright smoke。

E2E 入口（test:e2e、test:e2e:prepare、test:e2e:all）默认由脚本自启服务：未显式设置 TESTING_START_* 时会先校验 8000/5173/7373/7400 端口与本地 PostgreSQL/Redis 依赖，端口被占用时报错并给出提示。如果想复用已在运行的服务，可显式设置：

powershell

$env:TESTING_REUSE_BACKEND='true'   # 复用 Backend（必须满足 E2E 测试指纹）
$env:TESTING_START_EDITOR='true'    # 未在运行时由脚本启动
$env:TESTING_START_RUNTIME='true'
$env:TESTING_START_RENDERER='true'
pnpm run test:e2e

TESTING_REUSE_BACKEND=true 会跳过端口校验；Backend 指纹不匹配时 prepare 会明确报错。

E2E 报告与失败产物统一写入 test-results/e2e/：

test-results/e2e/html-report/：Playwright HTML 报告。
test-results/e2e/artifacts/：trace、截图、视频和 .last-run.json。

详细测试治理见测试治理说明。

测试数据

平台 smoke 数据 CLI：

powershell

pnpm run test:reset:data
pnpm run test:seed:smoke

E2E 默认应使用 AI_TEST_MODE=mock，避免依赖真实 LLM 响应顺序、时延和内容。

AI run 诊断 CLI

AI 会话、run、事件、消息、工具调用和 HITL requirement 的事实源都在 Backend 主库 ai_agent_* 表中。需要按 run_id 排查一次智能体运行时，使用只读诊断 CLI：

powershell

uv run --project backend python -m app.scripts.diagnose_ai_run --run-id <run_id> --format summary
uv run --project backend python -m app.scripts.diagnose_ai_run --run-id <run_id> --format json
uv run --project backend python -m app.scripts.diagnose_ai_run --session-id <session_id> --format summary
uv run --project backend python -m app.scripts.diagnose_ai_run --session-id <session_id> --format json --output .tmp/ai-session-diagnostics.json

summary 输出适合终端阅读的摘要，包括 run 基本状态、事件序列、工具调用、pending/resolved requirement、消息摘要和 message_history_json 摘要。
json 输出完整结构，适合保存后比对事件顺序或工具参数。
--run-id 输出单次 run 诊断；--session-id 输出会话基本信息、会话消息和该 session 下所有 run 的诊断。
--output <path> 将结果写入 UTF-8 文件，并自动创建父目录；未指定时输出到 stdout。
脚本只读查询数据库，不修改任何 ai_agent_* 表，也不读取或清理 Redis run 状态。
run_id/session_id 不存在时返回非 0 退出码。

从根仓运行 CLI 时会自动补读 backend/.env；已存在的环境变量优先，不会被 .env 覆盖。运行前仍需确认 Backend 的数据库环境变量指向要诊断的实例。如果要修复历史坏数据，应单独编写限定 run_id/session_id/user_id 范围的一次性维护脚本，不要把写操作加入诊断 CLI。

LLM HTTP trace

开发环境需要查看智能体实际发给模型供应商的 HTTP 请求时，可临时打开 Backend trace：

env

AI_LLM_HTTP_TRACE_ENABLED=true
AI_LLM_HTTP_TRACE_DIR=.tmp/llm-http-trace
AI_LLM_HTTP_TRACE_BODY_MAX_BYTES=200000

开启后，Backend 会把 Pydantic AI provider 发出的请求和响应摘要写入 backend/.tmp/llm-http-trace/llm-http-YYYYMMDD.jsonl。记录包含请求 URL、脱敏 headers、脱敏且按大小上限截断的请求体、响应状态码、响应 headers 和耗时；非 2xx 响应还会记录脱敏且按同一上限截断的响应 body，便于查看供应商错误码和消息；正常 2xx 流式响应不会读取 body，避免影响 Agent 正常消费模型输出。该能力只用于本地开发排障，提交复现材料前应检查 trace 文件中是否包含用户输入、页面源码或其它业务敏感内容。

Redis 临时态维护

Redis 保存预览 artifact 与构建心跳等临时运行态，不保存 AI run/HITL 事实源。截图去重、认领和恢复由主数据库中的持久化任务租约负责。

AI run 状态已经切到平台自有 ai_agent_* 表；旧 Redis run key 不需要维护脚本清理，按已有 TTL 自然过期。

Runtime 包命令

powershell

pnpm --filter web-runtime-vue install
pnpm --filter web-runtime-vue check
pnpm --filter web-runtime-vue test
pnpm --filter web-runtime-vue build
# 或使用根脚本：pnpm run test:runtime / test:runtime:gate

Runtime 内部能力、运行方式和镜像发布见 runtime/README.md。

Backend 开发文档

Editor 开发文档

Runtime 开发文档

Runtime 接入文档

测试文档

架构文档

参考资料

本地开发指南

环境要求

本地启动总览

本地基础服务

环境变量准备（全仓统一）

Backend 本地启动

Renderer 本地启动

Runtime 本地启动

Editor 本地启动

根仓测试入口

测试数据

AI run 诊断 CLI

LLM HTTP trace

Redis 临时态维护

Runtime 包命令

本地开发指南 ​

环境要求 ​

本地启动总览 ​

本地基础服务 ​

环境变量准备（全仓统一） ​

Backend 本地启动 ​

Renderer 本地启动 ​

Runtime 本地启动 ​

Editor 本地启动 ​

根仓测试入口 ​

测试数据 ​

AI run 诊断 CLI ​

LLM HTTP trace ​

Redis 临时态维护 ​

Runtime 包命令 ​

本地开发指南

环境要求

本地启动总览

本地基础服务

环境变量准备（全仓统一）

Backend 本地启动

Renderer 本地启动

Runtime 本地启动

Editor 本地启动

根仓测试入口

测试数据

AI run 诊断 CLI

LLM HTTP trace

Redis 临时态维护

Runtime 包命令