eust-w 3217982f32 🔀 Merge project knowledge
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

# Conflicts:
#	apps/web/src/features/projects.tsx
#	apps/web/src/lib/types.ts
#	docs/architecture.md
#	docs/reference/ui.md
#	docs/requirements.md
#	docs/user-manual.md
#	tests/local-loop.test.ts
2026-11-04 12:45:22 +08:00

4.9 KiB
Raw Blame History

管理台设计规范

管理台位于 apps/web,使用 Next.js App Router、React、SWR 与 Lucide 图标。所有列表、状态、预算与操作反馈都来自真实的控制面数据,不内置演示数据或模拟流程。

视觉基线

概念图:apps/web/design/console-concept.png(零数据状态的工作概览)。

  • 新增样式使用 globals.css 顶部的设计变量(导航 --navy、页面背景 --bg、表面 --surface、主色 --teal / --teal-dark、边框 --border、正文与次要文字 --ink / --muted、警示 --amber / --red)。
  • 正文与次要文字对白色背景的对比度不低于 4.5:1,焦点环不低于 3:1;最小字号 12 px。
  • 桌面端左侧导航 248 px、顶部栏 58 px;760 px 以下使用抽屉导航,抽屉关闭时其中的链接不可聚焦,按 Esc 关闭。
  • 所有按钮与表单都有可见焦点、标签和错误反馈,并尊重 prefers-reduced-motion。

页面

页面 内容 主要接口
工作概览 / 进行中与待处理的运行数、最近运行、项目准备入口 GET /v1/dashboard
项目空间 /projects 项目列表、创建项目 GET/POST /v1/projects
项目详情 /projects/:id 仓库状态(平台仓库失败可重试)、项目运行、项目技能概况(链接到知识库)、设置(目标分支、验证命令、安装命令、交付配置、验收配置) GET/PATCH /v1/projects/:id、POST /repository、/skills
运行记录 /runs 运行列表与筛选;提交愿望(不可用的执行器不可选并显示原因) GET /v1/runs、POST /v1/projects/:id/wishes
运行详情 /runs/:id 阶段进度、等待原因与对应操作、最近一次失败(修复轮的输入);标签页:概览、代码变更(检查点按文件的 diff)、阶段事件(Agent 消息、命令、文件变更、计划)、验证证据(命令、退出码、耗时、输出尾部,合入与冲突);交付结果(合入的 commit 或应用地址) GET /v1/runs/:id、/events/stream、/artifacts、/delivery、POST /commands
发布与审批 /releases 发布列表(失败原因);审批对话框展示需求目标与验收标准、项目、环境(是否生产)、验证命令、commit、镜像、审批期限与请求人 GET /v1/releases、GET /v1/releases/:id/review、POST /v1/approvals/:id/decision
环境 /environments 环境列表与创建、应用地址、Runner 注册、部署密钥引用、部署结果未知时「核对后解锁」 /v1/environments*、POST /v1/environments/:id/unlock
执行器 /providers 执行器可用性与能力、保存或撤销 BYOK 凭据、执行器设置(网关、模型、时限,所有者和管理员) GET /v1/providers、/v1/provider-connections、GET /v1/executor-settings、PUT /v1/executor-settings/:provider
Agent 配置 /agent 配置版本列表、创建、激活、回滚 /v1/agent-bundles*
用量 /usage 套餐限额与当前用量、本月 token 与按运行明细、CSV 导出 GET /v1/entitlements、/v1/usage、/v1/usage/export

等待原因统一由 src/lib/waiting.ts 映射为中文说明和可执行操作(例如「连接执行器」「重试仓库创建」「去审批」「补充需求」),不直接展示后端的原始代码。

身份与代理

  • /api/* 是服务端代理,转发到控制面的 /v1/* 并附加当前用户的 access token;不存在绕过身份检查的公开 rewrite。
  • 只有 WF_DEPLOYMENT_MODE=development(且不是 Next 的生产构建)时,服务端才读取 WF_DEV_AUTH_TOKEN 自动登录;其他情况一律不接受开发令牌。
  • OIDC 使用 discovery、授权码 + PKCE(S256)、state 与 nonce,并校验 ID token 的签名、issuer 与 audience。
  • 会话保存在加密的 HttpOnly Cookie 中,浏览器脚本无法读取;access token 过期前 1 分钟内由服务端代理使用 refresh token 续期,会话最长 12 小时。身份服务没有签发 refresh token 时,会话随 access token 结束。
  • 写请求校验 Origin,代理拒绝上游重定向;界面上的权限控制只用于体验,最终以 API 的角色与成员检查为准。

环境变量:WF_DEPLOYMENT_MODE、WF_API_URL、WF_PUBLIC_URL、WF_DEV_AUTH_TOKEN(仅开发)、OIDC_ISSUER、OIDC_CLIENT_ID、OIDC_CLIENT_SECRET(可选)、WF_SESSION_SECRET(至少 32 字符)。

测试

  • src/lib/auth.test.ts:会话加密与篡改、生产禁用开发令牌、会话过期、返回地址校验、ID token 签名与 nonce、refresh token 续期与轮换。
  • src/lib/patch.test.ts:检查点补丁按文件解析(新增、删除、二进制、看起来像文件头的内容行)。
  • tests/run-lifecycle.test.ts:每个等待原因在 waiting.ts 中都有中文说明与操作。