From d991e0b8e31ab022f9b1ca57113165c995c0203d Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 06:11:57 -0800 Subject: [PATCH 01/46] =?UTF-8?q?=F0=9F=93=9D=20Add=20Git=20Wiki=20baselin?= =?UTF-8?q?e:=20features,=20modules=20and=20droboticflow=20domain=20glossa?= =?UTF-8?q?ry?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../agent-entrypoints-and-permissions.md | 76 +++++++ .../console-observability-and-usage.md | 60 ++++++ ...ndependent-verification-and-self-repair.md | 57 +++++ .../integration-build-release-rollback.md | 59 ++++++ wiki/features/run-lifecycle-and-waiting.md | 60 ++++++ .../wish-submission-and-refinement.md | 54 +++++ wiki/glossary/business-rules.md | 194 ++++++++++++++++++ wiki/index.md | 83 ++++++++ wiki/modules/api-control-plane.md | 62 ++++++ .../modules/provisioner-runner-git-service.md | 75 +++++++ wiki/modules/runtime-and-contracts.md | 83 ++++++++ wiki/modules/web-console.md | 75 +++++++ wiki/modules/worker-pipeline.md | 91 ++++++++ 13 files changed, 1029 insertions(+) create mode 100644 wiki/features/agent-entrypoints-and-permissions.md create mode 100644 wiki/features/console-observability-and-usage.md create mode 100644 wiki/features/independent-verification-and-self-repair.md create mode 100644 wiki/features/integration-build-release-rollback.md create mode 100644 wiki/features/run-lifecycle-and-waiting.md create mode 100644 wiki/features/wish-submission-and-refinement.md create mode 100644 wiki/glossary/business-rules.md create mode 100644 wiki/index.md create mode 100644 wiki/modules/api-control-plane.md create mode 100644 wiki/modules/provisioner-runner-git-service.md create mode 100644 wiki/modules/runtime-and-contracts.md create mode 100644 wiki/modules/web-console.md create mode 100644 wiki/modules/worker-pipeline.md diff --git a/wiki/features/agent-entrypoints-and-permissions.md b/wiki/features/agent-entrypoints-and-permissions.md new file mode 100644 index 0000000..31d1552 --- /dev/null +++ b/wiki/features/agent-entrypoints-and-permissions.md @@ -0,0 +1,76 @@ +# 入口与权限:Web / MCP / IDE / 连接器 + +## 四类入口,同一套事实 + +| 入口 | 使用者 | 实现 | 能做什么 | +|---|---|---|---| +| Web 工作台 | 人 | `apps/web`(Next.js + BFF) | 全部操作,包括发布审批与 Diff 审核 | +| MCP | Codex / WorkBuddy 等 Agent 客户端 | `apps/api/src/mcp.ts`(Streamable HTTP) | 列项目、提交愿望、跟进、回答、控制、查询交付、请求发布 | +| 云 IDE | 开发者 | `apps/ide`(Theia)+ `apps/web/src/app/ide` | 编辑代码、推送 `ide/` 前缀分支 | +| 连接器配置 | 部署侧 | `connectors/`(Codex、WorkBuddy) | 把 MCP 服务接入第三方 Agent 客户端 | + +四类入口共享同一控制面与同一权限模型,不存在「MCP 快捷通道」。MCP 工具说明明确写出:发布审批只在 Web 控制台进行(`apps/api/src/mcp.ts:43`)。 + +## MCP 工具清单(以代码为准) + +`apps/api/src/mcp.ts` 注册了 8 个工具: + +| 工具 | 作用 | 关键约束 | +|---|---|---| +| `list_projects` | 列出可提交愿望的项目 | 返回项目 ID、仓库、目标分支、是否配置验证 | +| `submit_wish` | 提交愿望,快速返回 `run_id` 与控制台链接 | 必须带 ≥8 字符的幂等键 | +| `get_run` | 读取阶段、状态、等待原因说明 | — | +| `get_run_events` | 按游标读取进度事件 | 游标是最后看到的 `seq` | +| `answer_question` | 补充信息 | 会创建新的需求版本并重新验证 | +| `control_run` | 暂停 / 继续 / 取消 | 取消不会回滚已上线的发布 | +| `get_delivery` | 读取验证证据、合入 commit、应用地址 | 只有被接受的回执才有地址 | +| `request_release` | 请求部署已验证并构建的 commit | 高风险发布仍需人工在控制台批准 | + +「提交返回」不等于完成:工具说明要求客户端继续用 `get_run` / `get_run_events` 跟进,并用 `get_delivery` 报告结果。 + +## 权限模型:四种能力,六种账户类型 + +代码定义在 `packages/contracts/src/permissions.ts`。权限不是角色名,而是四个布尔/枚举能力: + +- `wish`:`none | frontend | review | full`,决定能许愿改什么。 +- `reviewCode`:能否批准/驳回别人的后端改动。 +- `releases`:能否发起、批准、拒绝、回滚发布。 +- `manage`:成员与权限、项目设置、环境、执行器与预算;包含其他全部能力(`normalizePermissions`,`packages/contracts/src/permissions.ts:41`)。 + +预置账户类型(`accountTypes`,`:25`):`admin`、`fullstack`、`reviewed`、`frontend`、`releaser`、`viewer`。项目级还可以用 `codeReview.paths` 定义「什么算后端代码」,并把某些路径放进 `exceptPaths` 放行。 + +> 文档差异:`docs/wishforge-summary.md:84-88` 用「全栈开发 / 后端需审核开发 / 前端开发」描述角色,源码里的对应物是 `fullstack` / `reviewed` / `frontend` 三种账户类型,加上 `reviewCode` 这一独立能力。以 `permissions.ts` 为准。 + +## 身份类型决定能做什么 + +`packages/contracts/src/index.ts:85` 定义了 actor 类型:`human | connector | worker | verifier | deployer`。校验不是只按角色,还按身份类型: + +- 连接器(`connector`)不能完成人工审批、修改凭据或环境配置(`docs/requirements.md` FR-A6)。 +- 执行器(`worker`)与验证器(`verifier`)只能写自己租约范围内的阶段与证据。 +- 发布者(`deployer`)只能提交发布回执,不能伪造通用部署证据绕过签名回执(`tests/local-poc-delivery.test.ts:475`)。 + +## 幂等 + +所有创建与控制类写操作都要求幂等键:同一键重复请求返回同一结果,同一键不同内容返回冲突(`docs/requirements.md` FR-A4)。MCP 的 `submit_wish`、`answer_question`、`control_run`、`request_release` 都强制要求 `idempotency_key`,这就是为什么 Agent 客户端可以安全重试网络错误。 + +## 云 IDE 的边界 + +- 工作区打开时克隆项目仓库;有编辑会话时得到 15 分钟仓库令牌,令牌只允许更新 `refs/heads/ide/`。 +- 平台 Git 的 pre-receive 钩子拒绝越界引用;所有推送只接受快进,不能删除分支。 +- IDE 分支通过「从该分支开始的愿望」进入目标分支,与 Agent 改动走同一条验证与合入路径。 +- 扩展必须来自平台预置白名单并校验摘要。 + +## 代码入口与测试集 + +| 关注点 | 入口 | 测试 | +|---|---|---| +| MCP 工具 | `apps/api/src/mcp.ts` | `tests/mcp.test.ts` | +| 权限与账户类型 | `packages/contracts/src/permissions.ts` | `tests/permissions.test.ts`、`tests/application-access.test.ts` | +| 身份与租约 | `apps/api/src/auth.ts`、`apps/api/src/domain/control-plane.ts:931` | `tests/internal-auth.test.ts`、`tests/auth-expiry.test.ts` | +| IDE 网关 | `apps/ide/gateway/`、`apps/web/src/app/ide/[id]` | `apps/ide/gateway/test/*.test.mjs` | +| 连接器 | `connectors/codex`、`connectors/workbuddy` | `tests/mcp.test.ts` | + +## 已知边界 + +- 平台不提供应用访问网关;应用地址由目标环境负责访问控制。 +- 访客(viewer)不能进入编辑会话;撤销成员资格后现有 IDE 连接会被关闭(`docs/requirements.md` FR-H1)。 diff --git a/wiki/features/console-observability-and-usage.md b/wiki/features/console-observability-and-usage.md new file mode 100644 index 0000000..113a753 --- /dev/null +++ b/wiki/features/console-observability-and-usage.md @@ -0,0 +1,60 @@ +# 控制台:进度、证据、报告与用量 + +## 控制台负责什么 + +`apps/web` 是 Next.js 工作台,职责是交互与 BFF 转换,**不直接触碰业务数据库**。所有业务事实来自 `apps/api`,前端只做展示与转发。这条边界可以在 `apps/web/src/app/api/[...path]/route.ts` 这类代理路由中看到,也由 `tests/console-bundle.test.ts` 保护:控制台可以打包 `packages/contracts` 的纯函数(例如 `permissions.ts`),但不能把服务端实现拉进浏览器包。 + +## 页面与能力 + +| 页面 | 前端入口 | 主要能力 | +|---|---|---| +| 概览 | `apps/web/src/features/dashboard.tsx` | 待确认、运行中、失败等聚合指标 | +| 运行列表 | `apps/web/src/features/runs.tsx:69` `RunsView` | 按阶段/状态筛选,进入详情 | +| 新建愿望 | `apps/web/src/features/runs.tsx:422` `NewWishView` | 目标、验收标准、模型选择、AI 优化 | +| 运行详情 | `apps/web/src/features/runs.tsx:789` `RunDetailView` | 阶段、事件、Diff、等待卡片、继续/取消/补充需求、代码审核、撤销改动 | +| 发布与审批 | `apps/web/src/features/releases.tsx` | 批准/拒绝、一键回滚、环境状态 | +| 项目设置 | `apps/web/src/features/project-settings.tsx` | 目标分支、验证命令、验证配置、可用模型、后端路径规则 | +| 成员与权限 | `apps/web/src/features/members.tsx` | 成员、账户类型与项目级权限 | +| 环境 | `apps/web/src/features/environments.tsx` | 环境与应用地址 | +| 执行器 | `apps/web/src/features/providers.tsx` | 模型/执行器连接与凭据 | +| 用量 | `apps/web/src/features/usage.tsx` | 月度 token、按运行明细、CSV 导出 | +| Agent 与技能 | `apps/web/src/features/agent.tsx`、`skills.tsx`、`lessons.tsx` | 提示词/模型版本、项目技能与经验 | +| 运行报告 | `apps/web/src/app/reports/wishes/[id]`、`apps/web/src/features/wish-report.tsx` | 单次愿望的交付报告 | + +## 事件流与断线续读 + +- 查询历史事件:`GET /v1/runs/:id/events?after=`(`apps/api/src/http.ts:444`)。 +- 实时订阅:`GET /v1/runs/:id/events/stream`(`apps/api/src/http.ts:447`)。 +- 事件类型的中文标签集中在 `apps/web/src/lib/events.ts:58` 的 `eventLabel`;新增事件类型而忘记补标签,会让详情页出现原始英文类型名,这是可观察的缺陷。 + +SSE 的设计要求是「断线重连后不丢失、不重复事件」(`docs/requirements.md` FR-C2),因此游标是接口契约的一部分,而不是前端缓存技巧。 + +## Diff 与代码审核 + +运行详情页展示生成的文件 Diff,后端审核卡片复用同一渲染。审核动作通过 `POST /v1/runs/:id/code-review`(`apps/api/src/http.ts:492`)提交,批准绑定被审核的 commit 与需求版本;批准后运行自动继续合入,不再重复检查。 + +## 证据展示 + +- 证据隔离标签:`apps/web/src/lib/evidence-isolation.ts`,用于让用户区分「沙箱内验证」与「本机 host 模式」的结果。 +- 产物:`GET /v1/runs/:id/artifacts`(`apps/api/src/http.ts:502`),存储契约见 `docs/reference/artifact-storage.md` 与 `apps/api/src/domain/artifacts.ts`。 +- 交付:`GET /v1/runs/:id/delivery`(`apps/api/src/http.ts:506`)。 + +## 报告与用量 + +- 运行报告:`apps/api/src/domain/wish-report.ts`,把一次运行的目标、验证证据、合入 commit 与交付结果整理成可读报告;测试 `tests/wish-report.test.ts`。 +- 用量与配额:`apps/api/src/domain/usage.ts`、`entitlements.ts`;测试 `tests/entitlements-usage.test.ts`。关键语义是「暂停、等待中或已结束的运行不长期占用预留额度」,因此暂停后应能提交新愿望。 +- 通知:`apps/api/src/domain/notifications.ts`;测试 `tests/notifications.test.ts`。 + +## 已知边界 + +- 控制台不做业务判定:所有状态与阶段以 API 返回为准,前端不做乐观状态机。 +- 「待确认」指标同时聚合 `waiting` 运行、`awaiting_approval` 发布与 `pending` 审批;取消运行时应级联失效,否则会出现「运行已取消但待确认仍大于 0」的历史问题(`docs/wishforge-summary.md:217-221`)。 + +## 代码入口与测试集 + +| 关注点 | 入口 | 测试 | +|---|---|---| +| 页面组件 | `apps/web/src/features/*.tsx` | `tests/console-bundle.test.ts` | +| 前端纯逻辑 | `apps/web/src/lib/*.ts` | `apps/web/src/lib/*.test.ts` | +| BFF 代理 | `apps/web/src/app/api/[...path]/route.ts` | `tests/application-access.test.ts` | +| 事件与报告 API | `apps/api/src/http.ts:444-512` | `tests/local-loop.test.ts`、`tests/wish-report.test.ts` | diff --git a/wiki/features/independent-verification-and-self-repair.md b/wiki/features/independent-verification-and-self-repair.md new file mode 100644 index 0000000..6cd57dc --- /dev/null +++ b/wiki/features/independent-verification-and-self-repair.md @@ -0,0 +1,57 @@ +# 独立验证与自修复 + +## 客户看到的承诺 + +「Agent 说做完了」不构成交付。WishForge 采信的是验证器在**独立环境**里跑出的命令退出码与输出。客户能看到的证据包括:每条命令的退出码、耗时、输出摘要与输出尾部;失败信息会回灌给执行器触发自修复。 + +## 验证器为什么无法被被测代码欺骗 + +`packages/runtime/src/verify.ts:110` 的 `verifyWorkspace` 是这一机制的核心实现: + +1. 先核对工作区 `HEAD` 等于检查点 commit,不等就报 `CHECKPOINT_CHANGED`(`:151-152`)。 +2. 把该 commit 的树**导出到兄弟目录** `${workspace}-tree`(`:153-156`),被测代码不能修改验证器继续使用的仓库。 +3. 在导出目录里 `git init` 并只 fetch 这个 commit 的对象(`:159-172`),因此仓库里的 Git 配置、hooks、历史都带不进来。验证器自身调用 Git 时还使用 `core.hooksPath=/dev/null`、`GIT_CONFIG_NOSYSTEM=1`、`GIT_CONFIG_GLOBAL=/dev/null`(`:144-146`)。 +4. 安装依赖允许联网(`:193-202`),**检查命令默认不获得网络**;沙箱执行器由 `packages/runtime/src/sandbox.ts:34` 的 `isolatedVerifierExecutor` 提供。 + +这解释了文档里反复强调的「物理隔离」:不是靠提示词要求模型诚实,而是让作弊在文件系统与进程层面做不到。 + +## 受保护的验收配置(verification profile) + +项目验证命令保存在平台上,但测试代码在仓库里,Agent 可以改写。因此生产交付还要求一份**运维独立安装**的验收配置:脚本构建进 verifier 镜像的 `/usr/local/lib/wishforge-verification/`,verifier 镜像根文件系统只读,配置按文件路径 + SHA-256 固定,随证据与发布绑定。 + +- 契约与安装说明:`docs/reference/verification-profiles.md`。 +- 选择接口:`POST /v1/projects/:id/verification-profile`(`apps/api/src/http.ts:252`),只允许 owner/admin 人类操作,连接器不行。 +- 生产模式下没有验收配置时进入 `verification_unconfigured` 等待,**不会**退回只跑仓库测试。 + +## 证据的内容与上限 + +- 输出尾部保留 `OUTPUT_TAIL_CHARS = 4000` 字符(`packages/runtime/src/verify.ts:36`),避免把巨量日志写进数据库。 +- 超时退出码固定为 `124`(`packages/runtime/src/verify.ts:38`),与真实命令退出码区分。 +- 证据类型 `CommandEvidence` 在 `packages/runtime/src/verify.ts:19` 定义;写入控制面走 `ControlPlane.evidence`(`apps/api/src/domain/control-plane.ts:1213`),必须带租约令牌。 + +## 自修复如何工作 + +验证失败时,失败命令与输出尾部被回灌给 executor,最多 `maxRepairRounds` 轮。边界要分清: + +| 情况 | 处理 | 是否消耗修复轮 | +|---|---|---| +| 测试断言失败 | 回灌 executor 修复 | 是 | +| 沙箱启动失败、依赖安装失败、Git 访问失败 | 进入 `infrastructure` 等待 | 否 | +| 目标分支自身检查失败 | 进入 `target_broken` 等待 | 否 | +| 修复轮用尽 | 进入 `repair_exhausted` 等待,等人补充需求或再修复一轮 | — | + +## 代码入口与测试集 + +| 关注点 | 入口 | 测试 | +|---|---|---| +| 精确 commit 验证 | `packages/runtime/src/verify.ts:110` | `packages/runtime/test/verify.test.ts` | +| 沙箱执行器 | `packages/runtime/src/sandbox.ts:34` | `packages/runtime/test/host-check-sandbox.test.ts` | +| 验收配置绑定 | `apps/api/src/domain/verification-policy.ts`、`apps/api/src/http.ts:252` | `tests/verification-profile.test.ts` | +| 自修复与轮次 | `apps/worker/src/verifier.ts`、`apps/worker/src/executor.ts` | `tests/run-lifecycle.test.ts`、`tests/control-hardening.test.ts` | +| 隔离证据 | `apps/web/src/lib/evidence-isolation.ts` | `apps/web/src/lib/evidence-isolation.test.ts` | + +## 已知边界 + +- 验证配置变更会使此前的验证、构建与审批失效;这是有意的,避免用旧证据发布新代码。 +- 开发模式可以没有验收配置,但其结果**不代表**受保护的生产验收。 +- 空脚本或只做表面检查的验收配置不构成业务验收;平台只保证「配置被固定摘要执行」,不保证配置本身写得对。 diff --git a/wiki/features/integration-build-release-rollback.md b/wiki/features/integration-build-release-rollback.md new file mode 100644 index 0000000..3184c95 --- /dev/null +++ b/wiki/features/integration-build-release-rollback.md @@ -0,0 +1,59 @@ +# 合入、构建、发布与回滚 + +这是流水线的后半段:`integrate → build → release → accept`。客户需要理解一个核心事实:**运行成功(Run succeeded)与交付成功(delivered)不是同一件事**。配置了交付的项目,必须走完发布并由目标环境回报证据才算闭环。 + +## 合入(integrate) + +- 合入权由租约串行化:`apps/api/src/domain/integration-lease.ts:24` 的 `IntegrationLeases`,每个项目同一时间只允许一个运行集成。 +- 推送策略是「祖先检查 + `--force-with-lease`」,目标分支前进了就基于最新提交重新准备候选,最多三次;规则写在 `docs/reference/repository-contract.md`。 +- 后端路径门禁:改动命中 `codeReview.paths` 且提交人权限不足时,验证通过后仍要停在 `code_review`,由有「审核代码」权限的人批准。批准绑定被审核的 commit 与需求版本。 +- 声明「只改前端」的愿望若改到后端文件,平台在修复轮开始前把这些文件恢复到运行开始时的内容,失败类型为 `scope`。 + +## 构建(build) + +`packages/runtime/src/build.ts:29` 的 `buildDockerImage` 负责镜像构建,产出不可变 digest。关键不变式:**构建所用 commit 必须等于已验证 commit**,不一致时拒绝构建证据(`docs/requirements.md` FR-F3)。 + +## 发布(release) + +| 概念 | 实现位置 | 说明 | +|---|---|---| +| 发布绑定 | `apps/api/src/domain/releases.ts:42` `releaseBinding` | 把 commit、镜像 digest、架构、环境、配置版本、验证策略与证据绑定成一个摘要 | +| 发起发布 | `apps/api/src/domain/releases.ts:280` `request` | 需要验证证据与构建证据 | +| 审批 | `apps/api/src/domain/releases.ts:435` `decide` | 必须提交 `bindingDigest`;摘要不匹配即拒绝 | +| 交付查询 | `apps/api/src/domain/releases.ts:257` `delivery` | 只有被接受的回执才带应用地址 | +| 回滚 | `apps/api/src/domain/releases.ts:662` `rollback` | 生成新的回滚日志并签名下发 | + +任何一项绑定内容变化(包括运维改了 POC profile)都会让审批失效,报 `POC_POLICY_CHANGED` 或等价的绑定校验错误。`tests/local-poc-delivery.test.ts:376-386` 专门覆盖「构建后改 profile → 审批被拒」。 + +风险计算在 `packages/contracts/src/release-risk.ts`:受保护路径、数据迁移、权限扩大、生产环境会提高风险,高风险发布必须人工审批,且**请求人不能批准自己的发布**,连接器也不能批准。 + +## 驻地交付(accept)与 POC 的真实约束 + +目标环境运行 `apps/runner`,以出站轮询拉取 Ed25519 签名任务,不需要公网入站端口。`docs/reference/poc-delivery-profile.md` 定义了对既有 `droboticflow` 命名空间的采用方式: + +- 固定 Gitea 仓库、`poc` 分支、API server、namespace UID、三个 Deployment UID、容器名、镜像仓库、公网地址与固定摘要的 Kaniko 执行器。 +- 只更新命名镜像与 `wishforge.d-robotics.cc/*` 审计注解;不重建 Service/Secret/RBAC/PVC/应用配置。 +- 更新顺序固定为 Coordinator → Worker → API。多个 Deployment 不是事务,因此**跨服务协议不兼容的改动必须在发布前被策略拒绝**。 +- 完成条件包括三个 rollout、精确就绪副本数、Pod 实际镜像 digest、配置指纹不变、公网健康/就绪/入口响应,以及签名发布里的业务冒烟检查。API 变更时 `/api/health.buildCommit` 必须等于交付的源码 SHA。 +- 日志状态只有三种终态:`succeeded`、`rolled_back`、`needs_reconciliation`。 + +这些不是文档愿景,而是被测试固化的行为:`tests/local-poc-delivery.test.ts` 覆盖伪造回执不置为成功(`:446`)、缺少匹配的组件与 HTTP 证据前运行不成功(`:461`)、普通 deployer 不能用通用部署证据绕过签名回执(`:475`)、首次交付前不能凭空回滚(`:498`)、回滚日志携带前一版镜像与完整基线(`:506`)、不兼容回滚在取锁前拒绝(`:572`)。 + +## 回滚的边界 + +回滚只改回仍由本次发布拥有的镜像,不会覆盖更新的外部镜像;它**不回滚** Gitea 提交与数据库变更。配置漂移会停止自动补偿并进入对账。这与「撤销这次改动(Revert Run)」是两件不同的事:后者基于最新主干生成反向 Diff,重新走完整验证。 + +## 代码入口与测试集 + +| 关注点 | 入口 | 测试 | +|---|---|---| +| 发布绑定与审批 | `apps/api/src/domain/releases.ts` | `tests/local-poc-delivery.test.ts`、`tests/release-risk.test.ts` | +| Runner 队列 | `apps/api/src/domain/runner-broker.ts` | `tests/local-poc-delivery.test.ts`、`tests/control-hardening.test.ts` | +| 签名任务 | `packages/runtime/src/runner.ts`、`packages/runtime/src/poc-runner.ts` | `packages/runtime/test/poc-release.test.ts` | +| POC 构建与发布 | `packages/runtime/src/poc-build.ts`、`poc-release.ts` | `packages/runtime/test/poc-release.test.ts`、`tests/local-poc-delivery.test.ts` | +| 交付适配 | `apps/runner/src/adapters.ts` | `apps/runner/test/local-entry.test.ts` | + +## 已知边界 + +- 发布审批只在 Web 控制台进行;MCP 可以发起请求,但不能代替人批准。 +- 回执里的应用地址由目标环境提供,平台不提供应用访问网关;唯一的 HTTP 例外是本地 POC 绑定的开发项目,且在生产模式被拒绝(`tests/local-poc-delivery.test.ts:401-419`)。 diff --git a/wiki/features/run-lifecycle-and-waiting.md b/wiki/features/run-lifecycle-and-waiting.md new file mode 100644 index 0000000..5367bda --- /dev/null +++ b/wiki/features/run-lifecycle-and-waiting.md @@ -0,0 +1,60 @@ +# 运行生命周期与等待出口 + +## 八阶段流水线 + +阶段定义在 `packages/contracts/src/index.ts:20`: + +``` +clarify → plan → implement → verify → integrate → build → release → accept +``` + +运行状态定义在同一文件的 `:22`:`queued / running / waiting / paused / succeeded / failed / canceled`。阶段与状态是两个正交概念:阶段说「做到哪一步」,状态说「现在是否在推进」。 + +## 谁在推进状态 + +- 工作流编排:`apps/worker/src/workflows.ts:16` 的 `runWorkflow`。executor、verifier、release 各是一个 activity;模型、构建、部署类 activity 的 `retry.maximumAttempts` 都是 1(例如 `apps/worker/src/workflows.ts:63-76`),因为**未知结果的外部副作用不允许自动重放**。 +- 状态写入:`apps/api/src/domain/control-plane.ts`。提交 `:358`、领取租约 `:931`、阶段迁移 `:1076`、证据 `:1213`。所有迁移都要求租约令牌(lease token),过期执行者无法写入。 +- 执行代次(generation):`apps/worker/src/workflows.ts:41-53` 用 `Set` 记录已见代次,延迟到达的旧信号不能把运行拉回旧身份;`tests/execution-generation.test.ts` 覆盖这一行为。 + +## 18 种等待原因,每一种都有出口 + +`packages/contracts/src/index.ts:25-44` 定义了 18 个等待原因: + +`credentials`、`git_storage`、`sandbox_provisioner`、`worker_unavailable`、`budget`、`clarification`、`verification_unconfigured`、`repair_exhausted`、`infrastructure`、`provider_error`、`ambiguous_execution`、`integration_conflict`、`target_broken`、`code_review`、`github_review`、`github_unconfigured`、`approval`、`deployment`。 + +每个原因在 `apps/web/src/lib/waiting.ts:15` 都有中文标题、可执行动作、可选链接,以及「继续」是否有效的 `resumable` 标记。这不是装饰:`waitingGuides` 的类型是 `Record`,**新增等待原因而不同时补齐前端指引会直接类型检查失败**,这是把「不允许死锁」写进类型系统的做法。 + +> 文档差异:`docs/wishforge-summary.md:166` 写「16 种结构化等待原因」,源码是 18 种(多了 `github_unconfigured` 与 `worker_unavailable` 等)。以源码为准。 + +## 三类出口的实际语义 + +| 出口 | 语义 | 代码路径 | +|---|---|---| +| 继续 / resume | 用信号唤醒工作流;同一代次内不重放未知副作用 | `apps/worker/src/workflows.ts:45-53`、`apps/api/src/http.ts:499` 之后的命令接口 | +| 补充需求 / answer | 生成新的需求版本;旧版本的验证证据与审批失效 | `docs/requirements.md` FR-C3;`apps/api/src/domain/control-plane.ts` 的 `submit` 与命令处理 | +| 取消 / cancel | 终止运行,并级联失效关联的发布单与审批单 | `docs/wishforge-summary.md:217-221` | + +`ambiguous_execution` 特别值得客户理解:它表示「一次外部操作结果未知」,系统**故意**不自动重试,而是要求人查看阶段事件后决定。自动重试在这里会造成重复部署或重复写库。 + +## 修复轮与等待的边界 + +- 测试失败会回灌 executor 自修复,最多 `maxRepairRounds` 轮,用尽后进入 `repair_exhausted`。 +- 基础设施类失败(沙箱启动失败、依赖安装失败、Git 访问失败)进入 `infrastructure`,**不消耗修复轮数**。 +- 目标分支自身被别人的提交弄坏时进入 `target_broken`,同样不消耗修复轮数,也不归因于本次愿望。 + +这三条区分的验收标准写在 `docs/requirements.md` FR-E5 与 FR-C6。 + +## 代码入口与测试集 + +| 关注点 | 入口 | 测试 | +|---|---|---| +| 阶段/状态/等待原因契约 | `packages/contracts/src/index.ts:20-47` | `tests/control-plane.test.ts` | +| 工作流推进与信号 | `apps/worker/src/workflows.ts` | `tests/run-lifecycle.test.ts`、`tests/execution-generation.test.ts` | +| 状态迁移与租约 | `apps/api/src/domain/control-plane.ts` | `tests/control-hardening.test.ts`、`tests/integration-lease.test.ts` | +| 等待提示 | `apps/web/src/lib/waiting.ts` | 类型检查(`npm run typecheck`) | +| 派发与恢复 | `apps/worker/src/activities.ts`、`apps/api/src/dispatcher.ts` | `tests/dispatcher.test.ts` | + +## 已知边界 + +- 暂停不是「释放资源」:暂停的运行仍占并发名额的实现细节见 `docs/requirements.md` FR-J2 与 `apps/api/src/domain/entitlements.ts`。 +- 运行成功不等于交付成功:配置了交付的项目还要经过 build/release/accept,见 [integration-build-release-rollback](integration-build-release-rollback.md)。 diff --git a/wiki/features/wish-submission-and-refinement.md b/wiki/features/wish-submission-and-refinement.md new file mode 100644 index 0000000..da5a4a8 --- /dev/null +++ b/wiki/features/wish-submission-and-refinement.md @@ -0,0 +1,54 @@ +# 提交愿望与需求优化 + +## 客户看到的是什么 + +一个「愿望」由**目标**和**至少一条验收标准**组成,提交后在隔离环境中由编码 Agent 实现。页面上的表单是最小契约:缺验收标准不能提交;不可用的执行器在表单里不可选,并显示原因。 + +提交入口: + +- 工作台「+ 提交愿望」:`apps/web/src/features/runs.tsx:422`(`NewWishView`)。 +- 控制面接口:`POST /v1/projects/:id/wishes`,定义在 `apps/api/src/http.ts:416`,返回 `202`,因为运行是异步推进的。 +- MCP 连接器:`submit_wish`(`apps/api/src/mcp.ts:87`),供 Codex/WorkBuddy 使用。 + +## 愿望文本的固定格式 + +`packages/contracts/src/wish.ts` 定义了愿望标题与详情的解析规则: + +- `wishTitle(goal)` 只取第一行作为列表、标题和消息里显示的目标(`packages/contracts/src/wish.ts:5`)。 +- `wishDetails(goal)` 取第一行之后的全部内容,作为需求与限制(`packages/contracts/src/wish.ts:11`)。 +- `withAnswers(goal, answers)` 把用户在澄清卡片里选择的答案插入到「不改:」之前;没有「不改:」时追加到末尾(`packages/contracts/src/wish.ts:18`)。这条规则保证补充答案不会覆盖用户明确写下的不可破坏约束。 + +因此工作台与文档推荐的三段式(目标 / `范围:` / `不改:`)不是提示词风格建议,而是**被解析代码固化的结构**:第一行一定会被单独抽取展示,`不改:` 行一定会被保留在答案之后。 + +## AI 优化愿望 + +`POST /v1/projects/:id/wish-refinements`(`apps/api/src/http.ts:409`)调用 `WishRefiner`(`apps/api/src/domain/wish-refiner.ts:113`)。行为要点: + +- 使用项目规则与内置 `WISH_RULES` 一起改写草稿(`apps/api/src/domain/wish-refiner.ts:10`)。 +- 首选模型是 `deepseek-flash@latest[1m]`,失败后回退到 `deepseek-pro@latest[1m]`;两个模型都可由环境变量覆盖(`apps/api/src/domain/wish-refiner.ts:98-104`)。 +- 返回不可用时明确报错,而不是伪造一份「优化后的愿望」(`tests/wish-refiner.test.ts:131`)。 + +## 模型白名单 + +项目设置里只允许使用管理员勾选的模型;`GET /v1/models`(`apps/api/src/http.ts:218`)通过受保护通道从模型网关拉取清单,`PATCH /v1/projects/:id` 写入 `models`(`apps/api/src/http.ts:302-344`)。这解决两个现实问题:手输模型名容易漏掉 `[1m]` 这类上下文后缀;企业需要可控的模型范围。 + +## 边界与常见误解 + +- **验收标准必须是可自动判定的断言。** 平台只采信命令退出码与输出,不采信 Agent 的文字陈述;主观标准(「体验更流畅」)无法形成证据。 +- **优化愿望不会替用户做业务决策。** 它只整理表达,不访问仓库,因此不会补出代码事实。 +- **提交是异步的。** `202` 只表示运行已建立,后续必须在运行详情或 MCP 的 `get_run` 跟进。MCP 工具说明里明确写了「A finished agent turn is not a verified delivery」(`apps/api/src/mcp.ts:43`)。 + +## 代码入口与测试集 + +| 关注点 | 入口 | 测试 | +|---|---|---| +| 愿望解析与标题 | `packages/contracts/src/wish.ts` | `tests/wish-refiner.test.ts:147`(wish format) | +| 需求优化 | `apps/api/src/domain/wish-refiner.ts` | `tests/wish-refiner.test.ts:35` | +| 提交路由 | `apps/api/src/http.ts:416` | `tests/control-plane.test.ts`、`tests/local-loop.test.ts` | +| 工作台表单 | `apps/web/src/features/runs.tsx:422` | `tests/console-bundle.test.ts`、`apps/web/src/lib/*.test.ts` | +| MCP 提交 | `apps/api/src/mcp.ts:87` | `tests/mcp.test.ts` | + +## 已知边界(首版核对) + +- 愿望一旦提交,目标文本本身不可原地编辑;补充需求会生成新的需求版本,并使旧版本的验证与审批失效(`docs/requirements.md` FR-C3)。 +- 表单中的「不可用执行器」判定来自项目连接与凭据状态,不由前端猜测。 diff --git a/wiki/glossary/business-rules.md b/wiki/glossary/business-rules.md new file mode 100644 index 0000000..e9b5cd4 --- /dev/null +++ b/wiki/glossary/business-rules.md @@ -0,0 +1,194 @@ +# 受控 Domain Glossary:droboticflow 业务规则与算子约束 + +## 这份文档是什么 + +这是从 `droboticflow` 仓库迁移过来的**受控业务词汇表**。它只回答一个问题:**哪些业务规则是硬约束,执行点在哪一行代码,违反时系统会怎样。** + +- 来源仓库:Gitea `longtao.wu/droboticflow`;本地核对副本 `/Users/d-robotics/Desktop/fanyu/droboticflow`。 +- 核对版本:`877307cb`(`877307cbe2616a00aee1086221d5aa1a1119a10e`,2026-10-27 16:28 +0800)。 +- 收录标准:必须能在代码中找到执行点(handler、校验函数、唯一索引、运行时注入),并至少有一个测试文件覆盖。**纯愿景、计划稿、会议结论不收录**,见文末「未收录」。 +- 引用格式:`仓库相对路径:行号`。`internal/`、`custom-operators/`、`tests/` 均指 droboticflow 仓库。 +- 与 WishForge Wiki 的关系:WishForge 的 Wish 会修改这个仓库。编码 Agent 在动手前应读本页,避免「测试通过但业务规则被破坏」。 + +## 规则索引 + +| 编号 | 规则 | 领域 | +|---|---|---| +| BR-01 | 三类人工角色领取后不能主动释放任务 | 标注协作 | +| BR-02 | 切片名称必须来自项目启用字典,名称按组织+用途防重 | 标注规范 | +| BR-03 | 舍弃必须选择项目字典原因,原因以服务端快照为准 | 标注规范 | +| BR-04 | 切片必须完整分区共同时间范围,空区域不自动赋义 | 标注规范 | +| BR-05 | 无效动作属于外层切片内部,整理必须显式选择并重新验证 | 标注规范 | +| BR-06 | 随机领取只返回数量,不泄露候选 | 标注协作 | +| BR-07 | 人工编辑以版本号乐观锁,冲突返回 409 | 标注协作 | +| OPR-01 | 算子必须遵循统一运行时环境契约 | 算子约束 | +| OPR-02 | 大对象不得内联,必须走受控引用 | 算子约束 | + +--- + +## BR-01 三类人工角色领取后不能主动释放任务 + +**规则**:标注员、质检员、最终验收员领取 `annotation-qa` 人工任务后,不能主动释放回公共池;接口返回 403。管理员改派与管理操作仍然保留;标注员仍可在本人任务中重新切片,不退回公共池。 + +**执行点**: + +- `internal/api/human_loop.go:1286-1290`:`handleHumanItemRelease` 先判断 `annotationWorkerCannotRelease(principal) && item.PluginID == "annotation-qa"`,命中即写 `human_task_release_forbidden`(标注员为 `annotator_release_forbidden`)并返回 403。 +- `internal/api/human_loop.go:1299-1303`:通过角色检查后,仍只允许「领取人本人或管理员」释放,且状态必须是 claimed/in_progress。 + +**测试依据**:`internal/api/annotation_random_claim_test.go:185`(标注员不能释放或选择未领取任务,管理员仍可释放)、`:206`(质检员不能释放)。 + +**违反后果**:403 + 明确错误码;任务归属不变,不会造成任务在池中重复被领取。 + +**WishForge 关联**:任何修改人工任务释放、改派、重新切片权限的 Wish,必须同时更新 `docs/annotation-five-rules.md` 与上述测试。 + +--- + +## BR-02 切片名称必须来自项目启用字典,名称按组织+用途防重 + +**规则**:新确认的切片名称必须来自本项目启用的切片字典,界面名称只读、用选择器;多个实际切片可同名,拆分沿用名称,不追加 A/B。字典名称按「组织 + 字典用途」分别防重,比较时忽略首尾/连续空白与大小写。历史已保存名称原样保留,不自动改写历史产物。 + +**执行点**: + +- `internal/domain/annotation_labels.go:22`:`NameKey` 字段(`json:"-"`,仅用于唯一性)。 +- `internal/api/annotation_labels.go:337-360`:`DictionaryNameKey(kind, name)` 生成规范化键,并在批量写入前用 `seenNames` 拒绝同组重复。 +- `internal/api/unified_dictionary_mongo_test.go:40`:Mongo 对 `{organizationId, nameKey}` 建唯一索引 `organizationId_nameKey_unique`(partial filter 只作用于字符串 nameKey),并发写入只有一条成功。 + +**测试依据**:`internal/api/unified_dictionary_mongo_test.go`(唯一索引与并发)、`internal/store/dictionary_names_test.go`(历史名称与规范化)、`internal/api/annotation_five_rules_test.go`(非法/跨项目/停用词条不能确认)。 + +**违反后果**:新增/改名/项目配置被拒绝;历史重复不删除、不合并,需管理员显式处理。 + +**WishForge 关联**:改字典写入路径时,**不能**绕过 `DictionaryNameKey` 直接写 `name`,否则唯一索引失效且历史兼容规则被破坏。 + +--- + +## BR-03 舍弃必须选择项目字典原因,原因以服务端快照为准 + +**规则**:项目已配置字典时,舍弃片段必须单选项目已有原因;「其他」及要求说明的词条必须填写说明,最多 1000 字。项目未配置字典时允许手填非空原因。恢复(保留)不依赖字典可用性。词条名称、版本、ID 由服务端确认,客户端提交的值不能篡改。 + +**执行点**: + +- `internal/api/slice_disposition.go:533-546`:服务端先清空 `DiscardReasonLabelID/Version/Name`,只有在 `reasonLabel != nil` 时才用**服务端查到的** `reasonLabel.ID/Version/Name` 覆盖;客户端字段不直接落库。 +- `internal/api/slice_disposition.go:164-190`:合并/拆分时继承已保存的原因与版本,并校验候选一致性。 + +**测试依据**:`internal/api/slice_disposition_test.go:20`(接口校验与版本冲突)、`internal/api/discard_reason_manual_test.go:33`(未配置字典时手填原因的字段形态)、`tests/backend/test_slice_discard_package.py`(真实双目/PTS/IMU 审核文件与交付过滤)。 + +**违反后果**:请求被拒绝(400/409);历史记录不被追写,字典改名/停用不影响已保存快照。 + +--- + +## BR-04 切片必须完整分区共同时间范围,空区域不自动赋义 + +**规则**:切片分区共同有效范围;描述分区每个切片;相邻描述共享边界,编辑边界同时更新两侧;空区域不自动赋义,最终提交拒绝未覆盖区域与重叠。`hardware-frame-v1` 边界网格把整数硬件时间戳映射到双目帧索引与 CFR 左视频媒体时间;内部边界必须同时推进两个相机索引;区间半开。 + +**执行点**: + +- `internal/api/human_slice_materialization.go:959`:同步 JSON 写入 `window.semantics = "half-open"`、`commonRange` 与逐片边界。 +- `internal/api/human_slice_materialization.go:994`:`coverage` 声明 `mode = "full_common_range"`、`contiguous = true`、`gapMicroseconds = 0`、`overlapMicroseconds = 0`,并记录双目帧数与 IMU 行数。 + +**测试依据**:`internal/api/annotation_boundary_grid_test.go`、`internal/api/human_slice_materialization_test.go`、`internal/api/annotation_operations_test.go:78`(完整分区被接受)、`tests/frontend/unified-annotation-boundaries.test.mjs`。 + +**违反后果**:最终提交被拒绝;导出的媒体与 JSON 覆盖不一致,下游交付不可用。 + +--- + +## BR-05 无效动作属于外层切片内部,整理必须显式选择并重新验证 + +**规则**:把动作标记为无效不新增外层切片边界。送检前可识别「连续三个保留切片同名、首尾精确相接、中间切片被明确无效动作完整覆盖」的候选,由用户逐项选择是否合并;取消选择保留原划分。服务器重新验证选择后才改变送检版本的外层划分;动作数组(ID、描述、无效判断、起止、硬件时间戳)不因合并改变。 + +**执行点**: + +- `internal/api/annotation_invalid_slice_consolidation.go:13`:`consolidateInvalidActionSlices(input, actions, selected)` 只处理被显式选中的候选;`:76` 记录 `consolidate_invalid_actions` 操作与原切片快照。 + +**测试依据**:`internal/api/annotation_invalid_slice_consolidation_test.go:16`(选中合并)、`:34`(未选择保留原划分)、`:49`(非法选择被拒绝)、`:66`(重叠候选合成连续区间)。 + +**违反后果**:非法选择被拒绝且不占用任务;已送检/已审核任务不被自动修改。 + +--- + +## BR-06 随机领取只返回数量,不泄露候选 + +**规则**:`claim-count` 只返回选定项目内、当前标注员具有有效供应商权限、处于可领取阶段的数量;不返回候选 ID、视频或排序。数量是读取瞬间快照;领取仍以服务端原子竞争结果为准。跨项目、非标注员、无有效供应商权限一律 403。 + +**执行点**: + +- `internal/api/annotation_random_claim.go:84-163`:`handleAnnotationClaimCount` 校验角色、项目归属/状态、供应商有效性,只累加 `count`,最终返回 `{projectId, count}`。 +- `internal/api/human_loop.go:1193`:领取接口拒绝「指定任务领取」(`random_claim_required`)。 + +**测试依据**:`internal/api/annotation_five_rules_test.go:53`(数量与私有池一致,领取后数量变化,跨项目/无权限 403)。 + +**违反后果**:泄露候选列表会让「随机」变成「挑选」,破坏质检公平性;因此任何返回候选 ID 的改动都是规则违反。 + +--- + +## BR-07 人工编辑以版本号乐观锁,冲突返回 409 + +**规则**:所有人工任务写操作必须提交 `version`;服务端版本不匹配返回 409 `version_conflict`,不覆盖他人编辑。 + +**执行点**: + +- `internal/api/human_loop.go:1171`、`:1232`:两处统一返回 `Human item version conflict` + `code: version_conflict`。 + +**测试依据**:`internal/api/slice_disposition_test.go:44`(过期版本 409)、`internal/api/human_loop.go:1171` 与 `:1232` 两处统一冲突响应、`docs/review-draft-conflict-recovery.md`(草稿冲突恢复流程)。 + +**违反后果**:并发编辑不会静默丢失;客户端必须刷新后重试。 + +--- + +## OPR-01 算子必须遵循统一运行时环境契约 + +**规则**:算子不是「函数调用」,而是受平台约束的一次节点执行。worker 先把上游 artifact 汇总到 `INPUT_ARTIFACTS_PATH`,节点配置通过 `NODE_DATA_JSON` 注入,算子在 `OUTPUT_DIR` 产出业务文件,worker 再收集 `RESULT_OUTPUT_PATH` 与 `STAGE_MANIFEST_PATH`。 + +**执行点**: + +- `internal/worker/executor.go:792`:注入 `INPUT_ARTIFACTS_PATH` 等环境变量。 +- `internal/worker/executor_test.go:74`:断言 `INPUT_ARTIFACTS_PATH` 被填充。 +- `custom-operators/h2r-rgbd-pipeline/operator.py:64`:自定义算子读取 `INPUT_ARTIFACTS_PATH`。 +- `lightweight-operators/ubt-mcap-pipeline/ubt_pipeline/common.py:116`:轻量算子同样读取该变量。 + +**违反后果**:算子拿不到输入或产出不被收集,节点显示成功但下游无数据。 + +**设计含义**:新增算子时先回答五个问题——输入是结构化 JSON、远程引用还是本地路径;输出是否被下游消费;是否有真实外部副作用;失败是否幂等可重试;验收看平台记录还是外部系统。 + +--- + +## OPR-02 大对象不得内联,必须走受控引用 + +**规则**:大视频、大包体结果不得写进日志或 Mongo;必须使用 `artifact.path`、`dataRef.payloadPath`、共享 PVC 或对象存储引用。仅当结构化 JSON 不需要引用时才允许 `payload.inline`。 + +**执行点**: + +- `internal/worker/artifact_storage.go:373-377`:只有在 `structuredJSONRequiresReference` 为假时才写 `ArtifactTransferModeInline`。 +- `internal/worker/artifact_storage.go:413`:否则必须提供 worker 可访问的路径或持久引用,否则报 `artifact_externalization_failed`。 +- `internal/worker/executor_test.go:211`:小输入清单保持 inline 的便利性;`:405` 覆盖 `payloadPath` 形态。 + +**测试依据**:`internal/worker/executor_test.go`、`internal/worker/runtime_test.go:161`(读取 `payloadPath`)。 + +**违反后果**:大对象内联会撑爆 API/数据库;外置失败则节点直接报错,而不是「看起来成功」。 + +--- + +## 未收录(有意) + +以下内容没有进入本 Glossary,因为无法在代码中找到可指认的执行点,或有更权威的代码覆盖: + +- `docs/fanyu-vnext-workflow-draft.md` 等草稿/未来工作流:属于计划,不是现状。 +- `docs/annotation-keyboard-guide.zh-CN.md` 的快捷键:属于交互偏好,不是业务不变量。 +- 会议结论、性能优化记录(如 `docs/annotation-operation-latency.md`):属于工程改进记录,规则会随实现变化。 + +## 变更流程 + +1. **改规则**:先改代码与测试,再改本页;不允许先改 Wiki 让实现去追。 +2. **改编号**:只增不改;废弃规则保留编号并标注「已废止 + 替代编号」。 +3. **迁移新规则**:补充「执行点」「测试依据」「违反后果」三项,缺一项不得提交。 +4. **最后核对**:每次修改记录 droboticflow 的 commit(当前 `877307cb`),便于回溯。 + +## 自检命令 + +```bash +# 规则条数与编号 +grep -c '^## BR-' wiki/glossary/business-rules.md +grep -c '^## OPR-' wiki/glossary/business-rules.md + +# 每条规则至少有一个代码/测试引用 +grep -c '^- `internal/\|^ - `internal/\|^- `custom-operators/' wiki/glossary/business-rules.md +``` diff --git a/wiki/index.md b/wiki/index.md new file mode 100644 index 0000000..abb6e8f --- /dev/null +++ b/wiki/index.md @@ -0,0 +1,83 @@ +# WishForge Wiki + +这是 WishForge 仓库内的受控知识库(Git Wiki)。它面向三类读者,并且只服务于一个目的:让人和 Agent 在**不重新扫描整个代码库**的前提下,找到可信的现状描述、代码入口和业务约束。 + +| 读者 | 从这里开始 | 需要的回答 | +|---|---|---| +| 客户 / 使用者 | [`features/`](features/) | 这个功能现在到底怎么用、边界在哪里、失败时怎么办 | +| 编码 Agent | [`modules/`](modules/) | 改这个功能要动哪些文件、测试在哪里、哪些契约不能破 | +| 业务与维护者 | [`glossary/business-rules.md`](glossary/business-rules.md) | 哪些业务规则是硬约束、依据在哪个代码/测试文件 | + +## 项目速览 + +WishForge 是「远程、意图驱动的软件交付平台」:用户用一句话提出愿望(目标 + 验收标准),编码 Agent 在隔离环境中实现,独立验证器按受保护命令判定,失败回灌自修复,通过后合入、按需构建与部署(`README.md:3`)。 + +仓库分层与 Wiki 的对应关系: + +| 仓库目录 | 内容(`README.md:65-79`) | 对应 Wiki 页面 | +|---|---|---| +| `apps/api` | 控制面 API(REST、内部接口、MCP、模型代理) | [modules/api-control-plane](modules/api-control-plane.md) | +| `apps/web` | Web 工作台(Next.js,OIDC BFF) | [modules/web-console](modules/web-console.md) | +| `apps/worker` | Temporal worker:coordinator / executor / verifier / deployer | [modules/worker-pipeline](modules/worker-pipeline.md) | +| `apps/provisioner`、`apps/runner`、`apps/git-service` | 执行环境、驻地部署、平台 Git | [modules/provisioner-runner-git-service](modules/provisioner-runner-git-service.md) | +| `packages/contracts`、`packages/runtime` | 领域契约与执行适配 | [modules/runtime-and-contracts](modules/runtime-and-contracts.md) | + +运行前置与检查命令见 `README.md:33-59` 与 `:83-93`(`npm ci`、`npm run setup:local`、`docker compose`、`npm run db:migrate`、`npm run dev:all`;`format:check`、`typecheck`、`test`)。 + +## 目录 + +### features/ — 面向客户的现状说明书 + +| 页面 | 说明 | +|---|---| +| [wish-submission-and-refinement](features/wish-submission-and-refinement.md) | 提交愿望、验收标准、AI 优化、模型白名单 | +| [run-lifecycle-and-waiting](features/run-lifecycle-and-waiting.md) | 八阶段流水线、运行状态、18 种等待原因与解除路径 | +| [independent-verification-and-self-repair](features/independent-verification-and-self-repair.md) | 验证器独立裁决、受保护验收配置、自修复轮次 | +| [integration-build-release-rollback](features/integration-build-release-rollback.md) | 合入、构建、发布审批、回滚与 POC 驻地交付 | +| [agent-entrypoints-and-permissions](features/agent-entrypoints-and-permissions.md) | Web / MCP / IDE / 连接器四类入口与角色权限 | +| [console-observability-and-usage](features/console-observability-and-usage.md) | 控制台、事件流、Diff、报告、用量与配额 | + +### modules/ — 面向 Agent 的代码地图 + +| 页面 | 覆盖范围 | 关键入口 | +|---|---|---| +| [api-control-plane](modules/api-control-plane.md) | 控制面 API、领域状态机、数据库与 Outbox | `apps/api/src/main.ts`、`apps/api/src/domain/control-plane.ts` | +| [worker-pipeline](modules/worker-pipeline.md) | Temporal 工作流、executor、verifier、发布请求 | `apps/worker/src/workflows.ts`、`apps/worker/src/verifier.ts` | +| [runtime-and-contracts](modules/runtime-and-contracts.md) | Git/验证/构建/部署适配、领域契约 | `packages/runtime/src/`、`packages/contracts/src/index.ts` | +| [web-console](modules/web-console.md) | Next.js 工作台、BFF、事件与等待提示 | `apps/web/src/features/`、`apps/web/src/lib/waiting.ts` | +| [provisioner-runner-git-service](modules/provisioner-runner-git-service.md) | 执行环境、驻地 Runner、平台 Git 服务 | `apps/provisioner/main.mjs`、`apps/runner/src/main.ts`、`apps/git-service/src/service.ts` | + +### glossary/ — 受控领域词汇与业务规则 + +| 页面 | 说明 | +|---|---| +| [business-rules](glossary/business-rules.md) | 从 `droboticflow` 迁移的标注规范、算子约束与业务规则,每条带代码/测试引用 | + +## 内容规则(新增页面前必须遵守) + +1. **一条事实必须有一个可追溯依据。** 使用相对仓库根的路径加行号或函数名,例如 `packages/contracts/src/index.ts:20`;测试依据写成 `tests/xxx.test.ts`。没有依据的内容不进入 Wiki。 +2. **代码优先于文档。** 当 `docs/` 与源码不一致时,以源码为准,并在页面里显式记录差异。本 Wiki 首版已经记录了至少一处:`docs/wishforge-summary.md` 称 16 种等待原因,而 `packages/contracts/src/index.ts:25-44` 定义了 18 种。 +3. **不写空模板。** 每个页面至少包含:现状描述、代码入口、测试集位置、已知边界。占位符页面视为缺陷。 +4. **业务规则只用受控表述。** 规则编号(`BR-xx`、`OPR-xx`)只增不改;修改规则需要同步更新引用与“最后核对”版本。 +5. **不把推测写成结论。** 无法从代码或测试确认的行为,写进“未确认/待验证”。 + +## 自检 + +```bash +# 文件数量 +find wiki -name '*.md' | wc -l + +# 每个文件的正文字数(去掉 Markdown 语法符号后) +for f in $(find wiki -name '*.md'); do printf '%s %s\n' "$(tr -d '[:space:]#*`|->[]()' < "$f" | wc -m)" "$f"; done + +# 业务规则必须带代码引用 +grep -c '^### BR-' wiki/glossary/business-rules.md +``` + +当前基线:13 个 Markdown 文件,6 个 features 页面,5 个 modules 页面,1 个 glossary 页面;全部页面正文超过 200 字,`glossary/business-rules.md` 含 9 条带代码引用的规则。 + +## 维护方式 + +- 人工 Review 为主:任何页面改动都必须能指出对应的代码或测试变化。 +- 本目录是后续「Run 成功后增量修订 Wiki」流程的**基线结构**:`features/` 对应用户可见行为,`modules/` 对应代码地图,`glossary/` 对应不可违反的业务约束。三者分开,是为了让增量修订时能明确该改哪一类页面。 +- 迁移来源:`droboticflow` 仓库(Gitea `longtao.wu/droboticflow`,本地核对版本 `877307cb`,2026-10-27)。迁移只收录能在代码中找到执行点的规则,不搬运纯愿景描述。 diff --git a/wiki/modules/api-control-plane.md b/wiki/modules/api-control-plane.md new file mode 100644 index 0000000..327ecd5 --- /dev/null +++ b/wiki/modules/api-control-plane.md @@ -0,0 +1,62 @@ +# 模块:控制面 API(apps/api) + +## 职责 + +`apps/api` 是平台的**唯一事实来源**:项目与成员、愿望与运行、租约与证据、发布与审批、额度与用量、连接器与模型代理。它自己不跑模型、不跑测试,而是把长时间工作交给 Temporal(`apps/worker`)和目标环境的 Runner。 + +## 启动与组装顺序 + +入口 `apps/api/src/main.ts:24` 的 `bootstrap()`: + +1. `requireDeploymentMode(process.env)`(`main.ts:25`):部署模式必须显式声明,默认拒绝(fail closed),不靠 `NODE_ENV` 推断。 +2. 删除迁移用管理员凭据(`main.ts:27-28`),并对数据库角色做安全检查 `store.assertSafeRole()`(`apps/api/src/db/store.ts:108-110`):超级用户或 `BYPASSRLS` 角色会让租户隔离失效,因此拒绝启动。 +3. 若派发开启,强制要求 Temporal TLS 文件与租户命名空间(`main.ts:30-34`),避免通过未认证或共享命名空间派发。 +4. 组装 `Services(new ControlPlane(store))`,启动后台技能沉淀与资源对账 worker。 + +## 代码地图 + +| 文件 | 职责 | 关键点 | +|---|---|---| +| `apps/api/src/main.ts` | 启动、依赖组装、后台循环 | 206 行;fail-closed 配置校验 | +| `apps/api/src/http.ts` | REST 路由与 DTO 校验 | 933 行;NestJS 控制器;`/v1` 与 `/internal` | +| `apps/api/src/domain/control-plane.ts` | 运行状态机 | 1564 行;`submit:358`、`lease:931`、`transition:1076`、`evidence:1213` | +| `apps/api/src/domain/releases.ts` | 发布绑定、审批、回滚 | 724 行;`releaseBinding:42`、`request:280`、`decide:435`、`rollback:662` | +| `apps/api/src/domain/runner-broker.ts` | Runner 注册、任务队列、回执 | 508 行;`register:54`、`poll:127`、`result:290` | +| `apps/api/src/domain/provider-proxy.ts` | 模型网关代理与短期令牌 | 933 行;原始密钥不进入执行环境 | +| `apps/api/src/domain/local-poc.ts` | POC 绑定与构建证据校验 | `assertPocBuild`;`POC_BINDING_REQUIRED` 等错误码 | +| `apps/api/src/domain/integration-lease.ts` | 每项目单一集成者 | 与 fencing token 配合 | +| `apps/api/src/domain/entitlements.ts` | 套餐限额与并发预留 | 与 `usage.ts` 配合 | +| `apps/api/src/domain/skills.ts` | 项目技能沉淀 | 423 行;后台 harvest | +| `apps/api/src/domain/lessons.ts` | 运行经验注入 | 90 行 | +| `apps/api/src/mcp.ts` | MCP Streamable HTTP 服务 | 8 个工具;OAuth 资源元数据 | +| `apps/api/src/auth.ts`、`internal-auth.ts` | 人类会话与内部身份 | 身份类型见 `packages/contracts/src/index.ts:85` | +| `apps/api/src/dispatcher.ts` | Outbox → Temporal 派发 | 多副本安全 | +| `apps/api/src/db/store.ts` | PostgreSQL 事务与 RLS 上下文 | 每个事务 `set_config('app.tenant_id', …)`(`:116`) | +| `apps/api/src/db/migrate.ts`、`migrations/` | 版本化迁移 | `npm run db:migrate` | +| `apps/api/src/telemetry.ts` | OpenTelemetry 与指标 | Prometheus | + +## 数据层约束 + +- 每个租户事务在进入时设置 `app.tenant_id` 与 `app.actor_id`(`apps/api/src/db/store.ts:116-119`),RLS 策略据此过滤;应用层另有检查,两者都不能省。 +- Outbox 表把「状态已提交」与「工作流已派发」解耦:`outbox()` 只取未投递且到期的记录,按 `run.signal` → `workspace.reconcile` → 其他排序(`apps/api/src/db/store.ts:264`),投递成功写 `delivered_at`,失败累加 `attempts` 并退避。 +- 清理策略:已投递 outbox 保留 7 天,幂等记录 30 天(`apps/api/src/db/store.ts:84`)。 + +## 测试集 + +| 测试 | 覆盖 | +|---|---| +| `tests/control-plane.test.ts` | 提交、租约、阶段迁移、证据 | +| `tests/control-hardening.test.ts` | 取消/补充/暂停的级联失效、越权、租约边界 | +| `tests/local-loop.test.ts` | 本地端到端主链路 | +| `tests/local-poc-delivery.test.ts` | POC 发布绑定、签名回执、回滚 | +| `tests/entitlements-usage.test.ts` | 配额与计量 | +| `tests/internal-auth.test.ts`、`tests/auth-expiry.test.ts` | 身份与过期 | +| `tests/path-rules.test.ts` | 后端路径规则 | +| `tests/mcp.test.ts` | MCP 工具契约 | + +## 修改时的检查清单 + +1. 改状态迁移:必须同时更新 `packages/contracts` 的 schema、`tests/control-plane.test.ts` 与前端等待指引。 +2. 改证据结构:确认历史证据仍能反序列化;证据是审计资产。 +3. 改发布绑定字段:会让既有审批失效,需要在 PR 中说明。 +4. 新增路由:`/v1` 面向人类与连接器,`/internal` 面向 worker/verifier,权限模型不同,不能混用。 diff --git a/wiki/modules/provisioner-runner-git-service.md b/wiki/modules/provisioner-runner-git-service.md new file mode 100644 index 0000000..19c07b2 --- /dev/null +++ b/wiki/modules/provisioner-runner-git-service.md @@ -0,0 +1,75 @@ +# 模块:执行环境、驻地 Runner 与平台 Git + +这三个应用分别位于「执行面的两端」和「代码交接点」,共同决定愿望能否在真实环境里落地。 + +## apps/provisioner — 执行环境 + +**入口**:`apps/provisioner/main.mjs`;后端实现 `local.mjs` 与 `kubernetes.mjs`;工作区 `workspaces.mjs`、`workspace-lifecycle.mjs`;发布/运行资源 `run-release.mjs`、`run-operations.mjs`、`resource-grants.mjs`。 + +| 后端 | 适用 | 行为 | +|---|---|---| +| `local` | 本地开发 | 为每个代次在本机启动两个 worker 进程(`WF_SANDBOX_MODE=host`),**没有隔离**;只在 `WF_DEPLOYMENT_MODE=development` 下启动 | +| `kubernetes` | 生产 | 用 `kubectl` 创建 Kata Job、PVC、Secret、ServiceAccount、NetworkPolicy;IDE 工作区为独立 Deployment | + +接口(全部要求 `Authorization: Bearer `,除 `/healthz`): + +| 方法与路径 | 作用 | +|---|---| +| `POST /runs` | 为该代次启动 executor 与 verifier;同一代次重复请求不重复启动 | +| `POST /runs/release` | 停止计算资源;控制面收到后才归还并发名额 | +| `POST /runs/purge` | 删除该运行所有代次保留的卷;仍有活动进程时返回 `busy` | +| `POST /workspaces` | 创建/返回 IDE 工作区 | +| `GET/PUT /workspaces/:id/lifecycle` | 仅 kubernetes 后端:暂停/恢复 | +| `GET /healthz` | 健康检查 | + +**资源授权**:API 用 `WF_RESOURCE_GRANT_SECRET` 做 HMAC 签名,绑定租户、运行、代次、套餐、CPU/内存/存储与运行镜像,有效期 5 分钟。两个后端都校验签名与有效期;kubernetes 后端还要求镜像在允许列表内。这是「执行资源不能被随便要」的机制。 + +**测试**:`apps/provisioner/test/local.test.mjs`、`kubernetes.test.mjs`、`workspaces.test.mjs`、`workspace-lifecycle.test.mjs`;`npm test` 会跑 `node --test apps/provisioner/test/*.test.mjs`。 + +## apps/runner — 驻地交付代理 + +**入口**:`apps/runner/src/main.ts:15` 的 `main()`。 + +- 必需配置:`WF_CONTROL_PLANE_URL`、`WF_RUNNER_TOKEN`、`WF_TENANT_ID`、`WF_ENVIRONMENT_ID`、`WF_RUNNER_PUBLIC_KEYS`、`WF_RUNNER_STATE_DIR`;缺一项直接启动失败(`main.ts:17-25`)。 +- 出站拉取:`apps/runner/src/runner.ts` 的 `OutboundRunner` 轮询控制面的签名任务,目标环境**不需要**公网入站端口。 +- 签名校验:公钥来自控制面注册;任务内容是 Ed25519 签名报文。 +- `WF_RUNNER_EXECUTE=true` 才真正执行部署,默认只渲染(`render()` 只读)。 +- POC 采用:设置 `WF_POC_PROFILE_FILE` 时,**必须**是本地开发模式(`main.ts:28-32`),否则拒绝启动;同时把 profile 摘要与公网地址作为 `trustedPocDelivery` 传入验签,防止换个 profile 冒充。 +- 健康与日志:`apps/runner/src/health.ts`、`log.ts`。 + +**测试**:`apps/runner/test/local-entry.test.ts`;POC 语义由 `packages/runtime/test/poc-release.test.ts` 与 `tests/local-poc-delivery.test.ts` 覆盖。 + +## apps/git-service — 平台 Git + +**入口**:`apps/git-service/src/main.ts`;实现 `service.ts`。 + +- 平台 Git 是裸仓库服务,按仓库范围签发短期令牌:`issueGitToken` / `verifyGitToken`(`service.ts:99`、`:103`)。 +- 推送边界由 `PRE_RECEIVE_HOOK`(`service.ts:44`)执行:令牌里写明允许的引用前缀(例如 `refs/heads/ide/`),越界引用被拒绝;平台自己的合入不受该前缀限制。 +- 分支列举:`branchesIn(repository, prefix)`(`service.ts:70`),供工作台列出 IDE 分支。 +- 所有推送只接受快进,不能删除分支。 + +**测试**:`apps/git-service/test/hooks.test.ts`(例如 `:17` 验证 `ide/` 作用域令牌只能推 `ide/` 分支)、`service.test.ts`。 + +## 三者如何串起来 + +``` +控制面 --(HTTP + 资源授权)--> provisioner --(Kata Job)--> executor / verifier + | | + |<---------------- 证据 / 阶段迁移(内部接口)------------------+ + | + +--(签名任务, 出站轮询)--> runner --(kubectl patch)--> 目标集群 + | + +--(Git 令牌, 引用前缀)--> git-service <--- IDE / verifier 推送 +``` + +关键不变式: + +1. provisioner 不访问数据库、不持有签名密钥;它只执行资源创建。 +2. runner 不接收入站连接;目标环境无需暴露端口。 +3. git-service 的令牌按引用前缀限权,IDE 令牌无法直接推目标分支。 + +## 已知边界 + +- 本地 `host` 模式没有隔离,只能显式开启;生产部署模式下无法启动,其证据也会被拒绝(`docs/requirements.md` FR-D2)。 +- provisioner 的 local 后端不支持工作区暂停/恢复,返回 `lifecycle: "unmanaged"`。 +- 平台 Git 不是通用 Git 托管:不支持 LFS、子模块、SSH/SCP 地址。 diff --git a/wiki/modules/runtime-and-contracts.md b/wiki/modules/runtime-and-contracts.md new file mode 100644 index 0000000..34b5073 --- /dev/null +++ b/wiki/modules/runtime-and-contracts.md @@ -0,0 +1,83 @@ +# 模块:运行时适配与领域契约(packages/) + +## 为什么把这一层单独成页 + +`packages/` 是**不依赖具体进程**的可复用内核:契约定义「什么算合法状态」,runtime 定义「怎么在物理世界里执行」。控制面、worker、Runner 都引用它们,因此这里的改动影响面最大。 + +## packages/contracts — 领域契约 + +| 文件 | 行数 | 职责 | +|---|---:|---| +| `index.ts` | 868 | 角色、阶段、状态、等待原因、实体、Zod 输入、规范化 JSON | +| `entities.ts` | 117 | 领域实体字段(含集成租约) | +| `permissions.ts` | 88 | 四种能力与六种账户类型,可被控制台直接打包 | +| `path-rules.ts` | 61 | 后端路径 glob 规则与限制 | +| `poc-delivery.ts` | 56 | POC 发布组件集合的 schema 与目标镜像 | +| `deployment-mode.ts` | 47 | 显式部署模式,fail closed | +| `release-risk.ts` | 33 | 发布风险原因与标签 | +| `wish.ts` | 22 | 愿望标题/详情/答案插入 | +| `application-access.ts` | 66 | 应用地址证据匹配 | +| `canonical.ts` | 25 | 规范化 JSON(摘要稳定性的基础) | +| `redaction.ts` | 13 | 日志/证据脱敏 | + +关键事实: + +- 阶段 `clarify…accept` 与 18 种等待原因都在 `index.ts:20-44`,是全平台唯一来源。 +- `canonical.ts` 存在的意义是:同样的语义必须得到同样的摘要,否则发布绑定会被无意义地判为变化。 +- `permissions.ts` 显式「不 import 任何东西」,因此控制台可以打包它而不引入服务端代码(`tests/console-bundle.test.ts` 保护这条边界)。 + +## packages/runtime — 物理执行适配 + +| 文件 | 行数 | 职责 | +|---|---:|---| +| `git.ts` | 795 | `GitWorkspace`:克隆、基线、检查点 bundle/补丁(各 4 MiB 上限)、推送、合并 | +| `bluegreen.ts` | 762 | 蓝绿部署与流量切换 | +| `poc-release.ts` | 643 | POC 发布:指纹、JSON Patch 前置条件、回滚、对账 | +| `check-pods.ts` | 547 | 瞬态检查 Pod 的创建、等待、清理 | +| `poc-build.ts` | 492 | Kaniko 构建、源码归档、Pod 生命周期 | +| `deployment-secrets.ts` | 439 | 部署密钥按固定版本注入 | +| `sandbox.ts` | 273 | 隔离执行器(bubblewrap / seatbelt)与 host 检查 | +| `project-manifest.ts` | 264 | `wishforge.yaml` 严格解析 | +| `verify.ts` | 232 | `verifyWorkspace`:精确 commit、导出树、证据与输出尾部 | +| `deploy.ts` | 226 | Compose/Kubernetes 部署适配 | +| `poc-runner.ts` | 165 | POC Runner 适配与签名任务校验 | +| `poc-profile.ts` | 133 | 运维 profile schema 与摘要 | +| `build.ts` | 127 | Docker 镜像构建 | +| `runner.ts` | 108 | Ed25519 任务签名/验签 | +| `process.ts` | 129 | 子进程执行、超时、输出上限 | +| `patience.ts` | 46 | 不可靠链路的读重试节奏 | + +三个最容易被误改的地方: + +1. **`verify.ts` 的导出树。** 被测代码必须与验证器仓库分离,否则 Git filter/hook 可以逃逸。 +2. **`git.ts` 的检查点上限。** bundle 与补丁各 4 MiB(`CHECKPOINT_BUNDLE_LIMIT`、`CHECKPOINT_PATCH_LIMIT`),这是为了避免把整个仓库塞进数据库。 +3. **`poc-release.ts` 的前置条件。** 每个 JSON Patch 都带 UID、resourceVersion、容器名与旧镜像的 `test` 操作;去掉任何一个都会让并发/漂移场景下的误覆盖成为可能。 + +## 其他包 + +| 包 | 入口 | 职责 | +|---|---|---| +| `packages/agent` | `prompt.ts`(209 行)、`bundle.ts` | Agent 提示词组装与配置打包 | +| `packages/github` | `src/index.ts`(479 行) | GitHub App 客户端、分支/PR 操作 | +| `packages/artifacts` | `src/index.ts`(236 行) | 对象存储与产物引用 | + +## 测试集 + +| 测试 | 覆盖 | +|---|---| +| `packages/runtime/test/git-contract.test.ts` | 仓库 URL、分支、检查点 | +| `packages/runtime/test/verify.test.ts` | 精确 commit 验证与失败证据 | +| `packages/runtime/test/sandbox` 相关(`host-check-sandbox.test.ts`) | 隔离执行器 | +| `packages/runtime/test/poc-release.test.ts` | 漂移、不可变镜像、回滚、丢失应答 | +| `packages/runtime/test/poc-fanyu.test.ts` | Fanyu 命名空间采用 | +| `packages/runtime/test/project-manifest.test.ts` | `wishforge.yaml` 拒绝规则 | +| `packages/contracts/test/models.test.ts` | 模型清单 | +| `tests/path-rules.test.ts` | 后端路径规则 | +| `tests/console-bundle.test.ts` | 前端打包边界 | + +## 修改时的检查清单 + +1. 改契约字段:跑 `npm run typecheck`(含 tests 的 tsconfig),并检查所有 consumer。 +2. 改 runtime 的 Git/验证逻辑:至少跑对应 `packages/runtime/test/*.test.ts` 与 `tests/local-poc-delivery.test.ts`。 +3. 新增摘要字段:确认 `canonical.ts` 的序列化稳定,否则审批会随机失效。 +4. 改沙箱:生产模式必须保持 fail closed,host 模式只能显式开启。 diff --git a/wiki/modules/web-console.md b/wiki/modules/web-console.md new file mode 100644 index 0000000..52efddd --- /dev/null +++ b/wiki/modules/web-console.md @@ -0,0 +1,75 @@ +# 模块:Web 控制台(apps/web) + +## 职责与边界 + +`apps/web` 是 Next.js 工作台与 BFF。它负责会话、CSRF、页面渲染、SSE 消费与 Diff 展示;**不直接访问业务数据库**,所有请求经 `apps/web/src/app/api/[...path]/route.ts` 转发到 `apps/api`。这条边界让 API 可以独立部署、独立限流,也让前端无法绕过权限检查。 + +## 目录地图 + +| 路径 | 内容 | +|---|---| +| `apps/web/src/app/(console)/` | 工作台路由组:dashboard 隐含在根页、`runs`、`runs/[id]`、`runs/new`、`releases`、`projects`、`projects/[id]`、`projects/new`、`environments`、`members`、`providers`、`usage`、`agent` | +| `apps/web/src/app/ide/[id]` | 云 IDE 入口与 launch 路由 | +| `apps/web/src/app/login`、`login/callback`、`logout` | OIDC 授权码 + PKCE 与本地开发登录 | +| `apps/web/src/app/reports/wishes/[id]` | 单次愿望报告页 | +| `apps/web/src/app/api/[...path]` | BFF 代理 | +| `apps/web/src/features/` | 业务页面组件(见下表) | +| `apps/web/src/components/` | `console-shell.tsx`、`run-table.tsx`、`diff-view.tsx`、`ui.tsx` | +| `apps/web/src/lib/` | 纯前端逻辑与会话(含配套 `*.test.ts`) | + +## features/ 组件 + +| 文件 | 页面 | +|---|---| +| `dashboard.tsx` | 概览指标 | +| `runs.tsx` | 运行列表、新建愿望(`:422`)、运行详情(`:789`) | +| `releases.tsx` | 发布、审批、回滚 | +| `projects.tsx`、`project-settings.tsx` | 项目列表与设置(目标分支、验证命令、模型、后端路径) | +| `environments.tsx` | 环境与应用地址 | +| `members.tsx` | 成员与账户类型 | +| `providers.tsx` | 执行器/模型连接 | +| `usage.tsx` | 用量与配额 | +| `agent.tsx`、`skills.tsx`、`lessons.tsx` | Agent 配置、项目技能、经验 | +| `wish-report.tsx` | 愿望报告 | +| `runner-registration.tsx` | Runner 注册与公钥 | + +## lib/ 纯逻辑(每个都有测试) + +| 文件 | 职责 | 测试 | +|---|---|---| +| `auth.ts` | OIDC、会话加密 Cookie、本地访问凭据 | `auth.test.ts` | +| `api.ts` | SWR 客户端与 `ApiError` | 由组件测试间接覆盖 | +| `events.ts` | 事件类型中文标签(`:58` `eventLabel`) | `events.test.ts` | +| `patch.ts` | unified diff 解析为可渲染行 | `patch.test.ts` | +| `waiting.ts` | 18 种等待原因的中文指引与 `resumable` | 类型检查覆盖完整性 | +| `readiness.ts` | 数据态 `ready/refreshing/stale/unavailable` | `readiness.test.ts` | +| `risk.ts` | 复用 `@wishforge/contracts/release-risk` | `risk.test.ts` | +| `evidence-isolation.ts` | 「沙箱验证 / 本机 host」标签 | `evidence-isolation.test.ts` | +| `people.ts` | 本地账号、操作员与服务的显示名 | — | +| `markdown.tsx` | 受限 Markdown 渲染 | `markdown.test.ts` | +| `browser-id.ts` | 浏览器标识 | `browser-id.test.ts` | +| `local-access.ts` | 本机访问开关 | `local-access.test.ts` | +| `types.ts` | API 响应类型 | 类型检查 | + +> `readiness.ts` 的 `resourceState` 值得注意:它把「有旧数据但请求失败」标为 `stale` 而不是清空,避免网络抖动时页面显示成「没有项目」。 + +## 两个前端陷阱 + +1. **不要在组件里重新推导状态。** 阶段、等待原因、风险都来自 API;前端只做映射。`waiting.ts` 已经承担了「原因 → 指引」的唯一映射,新增原因必须在此补齐。 +2. **不要引入服务端依赖到客户端 bundle。** `packages/contracts/src/permissions.ts` 刻意零 import,正是为了让 `apps/web` 打包它而不把 `pg`、NestJS 等拉进浏览器。`tests/console-bundle.test.ts` 会检查这一点。 + +## 测试集 + +| 测试 | 覆盖 | +|---|---| +| `tests/console-bundle.test.ts` | 控制台打包边界与禁止依赖 | +| `apps/web/src/lib/*.test.ts` | 会话、事件标签、Diff 解析、就绪态、证据隔离、本地访问 | +| `tests/application-access.test.ts` | 应用地址与访问证据 | +| `tests/local-loop.test.ts` | 通过 BFF 的端到端链路 | + +## 修改时的检查清单 + +1. 新增页面:同时补 `console-shell` 导航与权限判断。 +2. 新增等待原因:改 `packages/contracts` → `apps/web/src/lib/waiting.ts` → 运行详情卡片,三处缺一不可。 +3. 改 Diff 渲染:先确认 `patch.ts` 的解析测试,再改组件。 +4. 改登录:生产模式必须拒绝开发令牌,回调重放必须被拒绝(`docs/requirements.md` FR-A1)。 diff --git a/wiki/modules/worker-pipeline.md b/wiki/modules/worker-pipeline.md new file mode 100644 index 0000000..49bcdba --- /dev/null +++ b/wiki/modules/worker-pipeline.md @@ -0,0 +1,91 @@ +# 模块:Temporal 执行流水线(apps/worker) + +## 职责 + +`apps/worker` 承载长时间运行的分布式状态机:把一次愿望拆成 executor → verifier → (可选)release 的 activity 序列,并在外部故障、进程重启、人工等待后从精确断点继续。它不拥有业务数据库,所有状态写入都通过 `/internal` 接口回到控制面。 + +## 代码地图 + +| 文件 | 行数 | 职责 | +|---|---:|---| +| `apps/worker/src/workflows.ts` | 141 | 工作流主体、resume 信号、执行代次(generation) | +| `apps/worker/src/activities.ts` | 97 | activity 注册:inspect、execute、verify、requestRelease、prepareRepair、recordWaiting | +| `apps/worker/src/executor.ts` | 486 | 拉取工作区、准备依赖、调用编码 Agent、产出检查点 | +| `apps/worker/src/verifier.ts` | 903 | 独立验证、验收配置、失败分类、修复证据 | +| `apps/worker/src/common.ts` | 237 | `RunInput`、`WorkerConfig`、内部 API 客户端 | +| `apps/worker/src/lease.ts` | 99 | activity 上下文与租约令牌传递 | +| `apps/worker/src/github-delivery.ts` | 123 | GitHub 分支/PR 交付路径 | +| `apps/worker/src/host-checks.ts` | 121 | 本机 host 模式的安全检查 | +| `apps/worker/src/providers.ts` | 134 | 执行器适配选择 | +| `apps/worker/src/main.ts` | 130 | worker 进程启动、任务队列 | +| `apps/worker/src/workflow-failures.ts` | 19 | 失败到等待原因的分类 | + +## 工作流的关键设计 + +### 1. 每次尝试都有独立任务队列 + +`apps/worker/src/workflows.ts:63-76`: + +```ts +taskQueue: `wishforge-executor-${tenantId}-${runId}-${generation}` +taskQueue: `wishforge-verifier-${tenantId}-${runId}-${generation}` +``` + +按代次隔离队列,意味着一次卡死的执行不会阻塞其他运行;进程重启后,只有同一代次的 worker 会接单。 + +### 2. 外部副作用不自动重试 + +模型调用、构建、部署类 activity 的 `retry: { maximumAttempts: 1 }`(`workflows.ts:66-76`)。失败后由 `waitingForFailure(error, phase)` 转成结构化等待原因,而不是盲目重放。这是「未知结果必须由人确认」的代码表达。 + +### 3. resume 信号与代次防回退 + +`workflows.ts:45-53`: + +- 收到新代次信号时取消当前 `CancellationScope`。 +- `seenGenerations` 记录已见代次,晚到的重复信号不能恢复旧身份。 +- 循环顶部先 `inspectRunState`,若运行已结束则直接返回,避免对已完成运行继续调用模型。 + +### 4. 等待记录的一条硬约束 + +`apps/worker/src/activities.ts` 的 `recordWaiting`: + +- 先读状态;代次不匹配返回 `superseded`,不写。 +- 已有租约未过期时抛 `EXECUTION_LEASE_HELD`,要求等待租约过期,**不允许**两个执行者同时写等待原因。 +- 只有确认后才 `POST /internal/runs/:id/wait`,detail 截断到 2000 字符。 + +### 5. 发布请求的幂等键 + +`requestRelease` 用 `release:${runId}:${generation}:${buildEvidenceId}:${environmentId}` 作为幂等键(`apps/worker/src/activities.ts`)。重试不会产生两个发布单;继续一个失败的发布则会因为代次变化产生新键。 + +## 验证器的失败分类 + +`verifier.ts` 负责把失败分成「测试失败 / 基础设施失败 / 范围失败」,决定是否消耗修复轮: + +- 测试失败:回灌 executor。 +- 安装失败、沙箱启动失败:`infrastructure`,不消耗轮次。 +- 前端专用愿望改到后端文件:`scope`,先恢复文件再重做。 +- 合并冲突:`integration_conflict`。 + +这些分类与 `docs/requirements.md` FR-E5、`packages/contracts/src/index.ts:256` 的证据类型一致。 + +## 启动与配置 + +`apps/worker/src/main.ts:10` 读取 `WorkerConfig`,连接 Temporal 与内部 API。开发时由 `apps/provisioner` 的 local 后端按代次启动 worker 进程;生产由 Kubernetes Job 启动。 + +## 测试集 + +| 测试 | 覆盖 | +|---|---| +| `tests/run-lifecycle.test.ts` | 阶段推进、失败分类、修复 | +| `tests/execution-generation.test.ts` | 代次与旧信号 | +| `tests/dispatcher.test.ts` | Outbox 派发与多副本 | +| `tests/verification-profile.test.ts` | 验收配置执行与失效 | +| `tests/local-loop.test.ts` | 本地端到端 | +| `packages/runtime/test/verify.test.ts` | 验证器行为 | + +## 修改时的检查清单 + +1. 新增 activity:必须考虑「结果未知」的恢复路径,不能不设上限重试。 +2. 改任务队列命名:provisioner 与 worker 必须同步,否则运行会停在 `worker_unavailable`。 +3. 改等待原因:同步 `packages/contracts` 与 `apps/web/src/lib/waiting.ts`。 +4. 改修复轮语义:同步 `docs/requirements.md` FR-E4/E5 与 `tests/run-lifecycle.test.ts`。 From cd1878b54cc0cdc2b7198d70565b567e934744ef Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 06:24:12 -0800 Subject: [PATCH 02/46] =?UTF-8?q?=F0=9F=93=9D=20Correct=20test=20coverage?= =?UTF-8?q?=20note=20in=20the=20web=20console=20module=20map?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- wiki/modules/web-console.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wiki/modules/web-console.md b/wiki/modules/web-console.md index 52efddd..8c13dd2 100644 --- a/wiki/modules/web-console.md +++ b/wiki/modules/web-console.md @@ -38,7 +38,7 @@ | 文件 | 职责 | 测试 | |---|---|---| | `auth.ts` | OIDC、会话加密 Cookie、本地访问凭据 | `auth.test.ts` | -| `api.ts` | SWR 客户端与 `ApiError` | 由组件测试间接覆盖 | +| `api.ts` | SWR 客户端与 `ApiError` | 无独立单测(由端到端 `tests/local-loop.test.ts` 间接覆盖) | | `events.ts` | 事件类型中文标签(`:58` `eventLabel`) | `events.test.ts` | | `patch.ts` | unified diff 解析为可渲染行 | `patch.test.ts` | | `waiting.ts` | 18 种等待原因的中文指引与 `resumable` | 类型检查覆盖完整性 | From a12dcc3628fee9c78a8b9cbb81da95b04e1cc084 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 20:20:49 -0800 Subject: [PATCH 03/46] =?UTF-8?q?=F0=9F=8E=A8=20docs(design):=20add=20UI?= =?UTF-8?q?=20audit,=20tokens,=20and=20core=20page=20designs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/audit.md | 123 ++++++++++ docs/design/pages.md | 540 ++++++++++++++++++++++++++++++++++++++++++ docs/design/tokens.md | 173 ++++++++++++++ 3 files changed, 836 insertions(+) create mode 100644 docs/design/audit.md create mode 100644 docs/design/pages.md create mode 100644 docs/design/tokens.md diff --git a/docs/design/audit.md b/docs/design/audit.md new file mode 100644 index 0000000..89c5f5c --- /dev/null +++ b/docs/design/audit.md @@ -0,0 +1,123 @@ +# WishForge 视觉与体验摸底报告 (Audit) + +> 审计基准:WishForge 仓库(分支 `review/overhaul`,`apps/web`) +> 审计日期:2026-11-09 +> 审计环境说明:当前终端执行环境无图形界面及无头浏览器渲染驱动,无法输出自动化像素级截屏。本摸底严格基于 `apps/web/src` 源码、组件树遍历、CSS 静态词法分析(AST/Regex)、DOM 结构以及 droboticflow(`docs/ui/copy-guidelines.md`)最简文案规范进行系统性走查。 + +--- + +## 1. 现有页面与组件资产盘点 + +### 1.1 路由与页面清单 + +| 页面 / 路由 | 对应 Feature 文件 | 页面核心职责与客户可见内容 | +| :--- | :--- | :--- | +| `/` (概览) | `features/dashboard.tsx` | 工作概览、进行中运行数、待确认事项、执行器就绪状态、最近运行列表、交付路径(5 步) | +| `/runs` (运行列表) | `features/runs.tsx` | 许愿与执行记录列表、项目/状态筛选器、愿望检索、状态指示 | +| `/runs/[id]` (运行详情) | `features/runs.tsx` | 执行目标、阶段流转状态机、命令证据、Diff 审阅、交付报告、日志抽检与分支锁 | +| `/runs/new` (新建愿望) | `features/runs.tsx` | 目标输入框、验收标准编辑、执行模型/执行器选择、分支指派与前置检查 | +| `/releases` (发布与审批) | `features/releases.tsx` | 部署发布列表、审批状态核对、代码/镜像摘要验证、回滚入口、上线应用直达 | +| `/environments` (环境管理) | `features/environments.tsx` | 目标环境卡片(生产/测试)、运行时配置、分支关联、在线健康状态 | +| `/projects` (项目列表) | `features/projects.tsx` | 客户项目看板、代码仓库关联、验证配置文件绑定 | +| `/projects/[id]/wiki` (Wiki 知识库) | `features/wiki-source.tsx` | 业务规则(BR-01~07)、操作规范(OPR-01~02)、算子手册与结构化索引 | +| 全局侧栏 / 浮层 Copilot | `features/copilot.tsx` | 诊断对话、Wiki 依据链(文件:行号)、置信度判别、一键转成许愿 | +| `/usage` (用量监控) | `features/usage.tsx` | Token/时间额度消耗、按提供商与任务划分的成本账单 | +| `/providers` (执行器配置) | `features/providers.tsx` | Claude CLI、Codex 等模型执行器凭据、配额与连通性自检 | +| `/members` (成员与权限) | `features/members.tsx` | 租户成员列表、角色指派(客户负责人/开发者/观察员)、Token 审计 | +| `/settings` (项目配置) | `features/project-settings.tsx` | 验证基线配置、门禁敏感路径规则(CodeReviewPolicy)、沙箱策略 | + +### 1.2 核心基础组件 (`components/ui.tsx`, `console-shell.tsx`, `run-table.tsx`, `diff-view.tsx`) + +1. **Button / ButtonLink**:支持 `primary`、`secondary`、`ghost`、`danger`,支持 `busy`(加载转圈)。 +2. **PageHeader**:页面主标题 + 一句话说明 + 右侧主操作 + 面包屑后退链接。 +3. **Panel**:卡片容器,支持 `title`、`aside` 及通用内嵌 children。 +4. **EmptyState**:居中空状态图标(默认 `Inbox`,字重 1.35)+ 标题 + 简述 + 恢复操作。 +5. **ErrorNotice / Notice**:基于 HTTP 状态码的标准化错误报警与信息栏。 +6. **Loading**:居中 spinner + 固定文案「正在读取控制面数据…」。 +7. **Status**:24 种状态字典映射的徽章,带有内嵌圆点指示灯。 +8. **Field / FormError / Success**:表单输入框包装、错误与成功提示。 +9. **Modal**:原生 `` 封装,支持普通与 wide 视图。 +10. **RunTable**:多列运行记录表格(ID、目标、执行器、状态、时间)。 +11. **DiffView**:Git 变更差异高亮对比组件。 + +--- + +## 2. 样式异味与重复分析 (CSS Smells) + +### 2.1 `globals.css` 规模与膨胀成因 +- **总行数**:`3580` 行。 +- **变量仅 14 个**:其余 3500+ 行全为全局选择器与局部选择器混杂。 +- **硬编码 Hex 颜色**:静态统计共有 **131 个** 不同的 Hex 颜色代码。同一种灰色在不同选择器中存在 `#d8e0ea`、`#b4c1d0`、`#edf1f5`、`#f6f8fb`、`#fbfcfe`、`#e1e7ef` 等 28 种极细微的变体,未形成层级梯队。 +- **字号碎片化**:存在 **23 种** 不同的字号定义(如 `8px`、`10px`、`11px`、`12px`、`13px`、`14px`、`15px`、`16px`、`17px`、`18px`、`20px`、`22px`、`25px`、`28px`、`34px` 等),缺少比例阶梯系统。 +- **圆角不规范**:虽有 `--radius: 7px`,但在代码中同时存在 `4px`、`5px`、`8px`、`9px`、`10px`、`12px`、`20px`、`999px` 等 **15 种** 显式 border-radius。 +- **间距无规则**:`margin` 和 `padding` 使用任意像素值(`7px`、`11px`、`13px`、`17px`、`23px`、`29px` 等奇数间距随处可见),组件间节奏感脱节。 + +--- + +## 3. 缺失的状态矩阵盘点 (States Audit) + +依据 droboticflow 界面规范要求的**四态闭环(正常、加载、空、错误)**以及企业多租户必备的**无权限态**,走查各主要功能模块: + +| 模块 / 页面 | 加载态 (Loading) | 空数据态 (Empty) | 错误态 (Error) | 权限限制态 (No Permission) | 诊断评价 | +| :--- | :---: | :---: | :---: | :---: | :--- | +| **工作概览 Dashboard** | ✅ 有全局加载骨架 | ⚠️ 仅 Recent Runs 有空状态 | ⚠️ ErrorNotice 置顶,但 metric 变成假 0 或空白 | ❌ 403 仅简单置空数据,无申请/提升权限指引 | 需补全单模块骨架屏 | +| **运行列表 Runs** | ⚠️ 无骨架,仅由 SWR 延迟刷新 | ❌ 搜索无结果时直接渲染空表格头部,无提示 | ✅ 有通用 ErrorNotice | ⚠️ 非租户只隐藏按钮,无说明 | 搜索空态缺失 | +| **运行详情 Run Detail** | ⚠️ 加载中时页面大面积空白 | ❌ 门禁未运行时显示为「-」,缺少未就绪说明 | ⚠️ 任务失败与控制面接口错误混合 | ❌ 无敏感分支查看鉴权拦截兜底 | 门禁结果四态极不规范 | +| **发布审批 Releases** | ✅ 有 `` | ⚠️ 空数据时渲染空面板,无首次发布引导 | ✅ 有 ErrorNotice 且可重试 | ⚠️ 非审批人(普通成员)按钮灰显无 hover 解释 | 需明确谁能审批(客户负责人/平台方) | +| **Wiki 知识库** | ⚠️ 内容拉取时跳动 | ❌ 检索无结果时空白 | ⚠️ 文件读取失败报错暴露后端路径 | ❌ 无租户隔离提示 | 需结构化空态与报错遮罩 | +| **Copilot 面板** | ❌ 仅发送按钮转圈,无会话流式骨架 | ❌ 首次进入无典型问题推荐 | ⚠️ 网络错误直接断开,无断线重连/重试 | ❌ 只读日志越权时仅报未知异常 | 缺失引导与优雅断网处理 | +| **集群资源 (新增)** | *待实现* | *待实现* | *待实现* | *待实现* | 必须按标准四态完整设计交付 | + +--- + +## 4. 最影响观感的前 10 个界面体验与视觉问题 + +### TOP 1: 缺少系统级设计系统,CSS 严重缺乏语义化与复用 +- **涉及文件**:`apps/web/src/app/globals.css` (3580 行) +- **现象描述**:样式全部平铺在单一巨大 css 文件中,类名如 `.run-row-3`、`.copilot-inner-box-v2` 等临时拼凑样式泛滥,修改一处极易产生未知回归。 +- **观感危害**:布局不稳、视觉断层、样式维护难度指数级上升。 + +### TOP 2: 品牌色与主动作饱和度/对比度不协调,视觉焦点发暗 +- **涉及文件**:`apps/web/src/app/globals.css:10-12` (`--teal: #168574`, `--navy: #102031`) +- **现象描述**:现行 Teal 绿偏墨暗,作为主要操作按钮(CTA)背景时,在暗灰底与白底上的存在感偏重且沉闷;而警告色 Amber 与错误色 Red 同样偏暗红泥黄色,高危操作缺乏即时震撼力。 +- **观感危害**:整体界面显得陈旧、缺乏现代研发协同工具应有的科技感与清爽感。 + +### TOP 3: 运行详情页(Run Detail)信息层级混乱,关键证据与风险被折叠埋没 +- **涉及文件**:`apps/web/src/features/runs.tsx:840-1120` +- **现象描述**:Run 详情页将近 1600 行代码,包含了执行目标、阶段时间线、沙箱命令证据、Diff 审阅、日志与交付报告。所有内容以简单的 vertical stack 罗列,页面极长,缺少核心看板(4 栏交付矩阵)。 +- **观感危害**:客户无法在 3 秒内看清「改了什么」、「风险高不高」、「验证过了没有」。 + +### TOP 4: 风险等级与审批门禁缺乏醒目、统一的徽章规范 +- **涉及文件**:`apps/web/src/features/releases.tsx:80-140`, `apps/web/src/lib/risk.ts` +- **现象描述**:低/中/高风险判定逻辑已存在于 `risk.ts`(例如涉数据迁移、超卖、权限扩大为高风险),但在 UI 上仅以朴素的小字体或普通标签呈现,未区分「客户负责人可批」与「必须平台方介入」的视觉权重。 +- **观感危害**:审批人极易误触高风险发布,带来重大生产事故隐患。 + +### TOP 5: Copilot 对话面板缺乏结构化视觉卡片与可信度分级 +- **涉及文件**:`apps/web/src/features/copilot.tsx:17-43` +- **现象描述**:Copilot 输出时,代码引用与 Wiki 链接混合在正文下方,样式类似一段简陋的小字;当 LLM 判断「依据不足/不确定」时,仅有一行小字标注 `unknown`,没有半透明警示背景与清晰免责卡片。 +- **观感危害**:用户无法迅速建立对 Copilot 诊断答案的信任边界,不敢将诊断直接转为许愿。 + +### TOP 6: 表格与卡片间距密度失控,屏幕利用率极低 +- **涉及文件**:`apps/web/src/components/run-table.tsx`, `apps/web/src/app/globals.css:1240-1420` +- **现象描述**:列表每一行高度高达 68px 以上,但有效文字仅占不到 30%;水平方向上有大量空白,垂直方向上信息却被挤出屏外。 +- **观感危害**:在标准 1440 笔记本屏幕下,一屏只能看到 5~6 条运行记录,排查问题体验繁重。 + +### TOP 7: 移动端(390px 视口)适配粗糙,大量横向滚动与溢出 +- **涉及文件**:`apps/web/src/components/console-shell.tsx:40-90`, `apps/web/src/app/globals.css:2900-3100` +- **现象描述**:侧边栏在手机端遮挡主界面,表格未做移动端卡片化(Cardify)适配,直接出现横向滚动条;按钮组(Button Group)在移动端发生折行错位与挤压。 +- **观感危害**:现场运维或移动端紧急确认发布时几乎不可用。 + +### TOP 8: 加载骨架屏缺失,内容加载时发生剧烈布局偏移 (CLS) +- **涉及文件**:`apps/web/src/components/ui.tsx:168-175` (``) +- **现象描述**:全站通用加载仅为一个居中的转圈小菊花 ``,一旦数据返回,页面元素瞬间撑开,视觉抖动极度严重。 +- **观感危害**:给人一种系统极不稳定、卡顿、开发未完成的粗糙毛坯感。 + +### TOP 9: 报错与异常反馈文案充斥内部技术黑话,缺失下一步动作指引 +- **涉及文件**:`apps/web/src/components/ui.tsx:119-158`, `apps/web/src/features/copilot.tsx:98` +- **现象描述**:遇到失败时直接抛出如 `API 500: MongoNetworkError` 或 `Command failed with code 124`,缺少 droboticflow `docs/ui/copy-guidelines.md` 规范要求的「最简业务语言 + 明确恢复按钮」。 +- **观感危害**:客户看不懂报错,恐慌感加剧,频繁打扰平台技术支持。 + +### TOP 10: 空状态 (EmptyState) 缺乏场景化与直接引导动作 +- **涉及文件**:`apps/web/src/components/ui.tsx:96-117` +- **现象描述**:全站所有空状态千篇一律地渲染灰色小盒子,文案空洞(如「尚未加载数据」),缺少符合业务语境的下一步引导按钮(例如「新建第一个愿望」、「去连接执行器」)。 +- **观感危害**:新接入项目的客户面对空白界面不知所措,流失率高。 diff --git a/docs/design/pages.md b/docs/design/pages.md new file mode 100644 index 0000000..363fd70 --- /dev/null +++ b/docs/design/pages.md @@ -0,0 +1,540 @@ +# WishForge 核心页面线框与交互规范 (Page Designs) + +> 文档版本:1.0.0 +> 设计目标:依据《界面文案规范》(参考 droboticflow `copy-guidelines.md` 最简文案原则)与《设计规范与令牌》(`docs/design/tokens.md`),为 WishForge 四个核心关键页面提供像素级落地的文字线框、网格布局、断点自适应(桌面 1440px / 移动端 390px)与四态闭环定义(正常、加载中、空数据、错误)。 + +--- + +## 页面 1:问题诊断 (Copilot 面板) + +### 1. 业务职责与交互流 +- **定位**:客户定位生产与测试环境异常的首要入口。通过输入日志片段或现象描述,Copilot 结合只读只取脱敏日志、集群事件与项目 Wiki 进行推理诊断。 +- **核心组件**: + 1. 诊断对话流(流式输出、免责置信度标注); + 2. 引用依据(精准到 `文件:行号` 或 Wiki 条目外链); + 3. 「依据不足 / 不确定」的警戒警示框与免责说明; + 4. 一键「转成许愿 (Create Wish)」带入上下文的快捷表单; + 5. 关联的集群实时资源告警卡片(如 Pod OOMKilled、CPU Throttling)。 + +--- + +### 2. 界面线框与布局 (Wireframes) + +#### 2.1 桌面端 (1440px) +- **形态**:两栏布局(或控制台全局右侧抽屉 520px / 独立全屏视图 1120px 容器)。以下按独立工作台视图展示: + +``` ++------------------------------------------------------------------------------------------------------------------+ +| TopNav: WishForge [项目: 泛宇标注平台 v] [环境: 生产环境 v] [集群资源] [运行记录] [发布审批] (用户) | ++------------------------------------------------------------------------------------------------------------------+ +| 面包屑: 控制台 / 问题诊断 (Copilot) | +| | +| 诊断会话: #CP-8921 标注切片任务偶发 504 Gateway Timeout [清空对话] [导出记录] [关联集群资源告警 (1)] | +|------------------------------------------------------------------------------------------------------------------| +| | +| [10:24:02] 用户: | +| 生产环境今天上午 10 点后,大视频切片任务大量报 504 错误,麻烦排查是哪里的问题。 | +| | +| [10:24:05] Copilot [AI 诊断助手] · 置信度 [依据确凿 - 92%] | +| 排查到 10:00~10:20 期间,worker 节点 `fanyu-gpu-01` 发生显存溢出及算子调度堆积: | +| 1. `droboticflow-worker` 切片算子未释放临时显存,触发 Pod 重启。 | +| 2. 网关超时阈值(当前 30s)小于视频切片平均响应时间(42s)。 | +| | +| +--- [关联依据 · Wiki 版本 877307cb] --------------------------------------------------------------------------+ | +| | [BookOpen] 算子超时配置规范 docs/operators/视频切片.md:42 [查看 Wiki] [代码跳转] | | +| | [BookOpen] 网关代理超时基线 k8s/ingress-nginx.yaml:18 [查看配置] | | +| | [Terminal] 节点只读事件 Warning: OOMKilled at Pod slice-worker-x9 [查看事件日志 (只读)] | | +| +--------------------------------------------------------------------------------------------------------------+ | +| | +| +--- [关联资源告警卡片] ---------------------------------------------------------------------------------------+ | +| | [!] 告警:节点 fanyu-gpu-01 内存限制 (Limits) 达到 102%,发生 3 次 OOMKilled 重启。 | | +| | 影响服务:droboticflow-worker (副本 2/2) | 对应指标:Mem Request 24Gi / Limit 32Gi | | +| +--------------------------------------------------------------------------------------------------------------+ | +| | +| [操作栏] [转成许愿并排期修复] [仅复制结论] [补充上下文/重新诊断] | +| | +| - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | +| | +| [10:28:11] 用户: | +| 能不能把超时时间改到 60s,顺便把 worker 内存限制调大到 48Gi? | +| | +| [10:28:15] Copilot [AI 诊断助手] · 置信度 [不确定 / 依据不足] | +| +--- [警告:当前结论依据不足] ---------------------------------------------------------------------------------+ | +| | [AlertTriangle] 注意:扩大资源 Limits 需核对集群空闲总账。 | | +| | 当前节点 fanyu-gpu-01 内存已分配 93%,若调至 48Gi 将导致节点 Limits 超卖超标 (118%)。 | | +| | 涉及生产部署与资源配额调整属于【高风险】变更,平台方禁止 Copilot 自动修改。 | | +| +--------------------------------------------------------------------------------------------------------------+ | +| 建议操作路径: | +| 1. 点击下方按钮,将「网关超时改至 60s」独立拆为许愿; | +| 2. 节点规格调整请提交集群配额工单,由平台方运维审批。 | +| | +| [操作栏] [仅为网关超时创建许愿] [放弃修改] | +| | ++------------------------------------------------------------------------------------------------------------------+ +| 输入框区域: | +| +----------------------------------------------------------------------------------------------+ [发送 / Enter] | +| | 描述异常现象、粘贴日志行、或询问集群组件配置... (支持 Shift+Enter 换行) | [上传脱敏日志] | +| +----------------------------------------------------------------------------------------------+ | ++------------------------------------------------------------------------------------------------------------------+ +``` + +#### 2.2 移动端 (390px) +- **形态**:单列自适应流,顶部紧凑状态栏,底部固定输入条。 + +``` ++---------------------------------------+ +| [=] WishForge [资源告警 (1)] | ++---------------------------------------+ +| Copilot 问题诊断 · 生产环境 | +|---------------------------------------| +| 10:24 用户 | +| 生产切片任务报 504 错误... | +| | +| 10:25 Copilot | +| 诊断发现显存溢出及网关 30s 超时截断。 | +| | +| [依据: 视频切片.md:42] | +| [日志: Pod slice-worker-x9 OOM] | +| | +| +-----------------------------------+ | +| | [!] 告警: fanyu-gpu-01 内存超限 | | +| +-----------------------------------+ | +| | +| [转成许愿 (Wish)] [复制诊断] | +| | +| ------------------------------------- | +| 10:28 Copilot | +| [!] 置信度不足: | +| 调大内存涉及【高风险】集群超卖。 | +| | +| [仅为网关超时提许愿] | ++---------------------------------------+ +| [ 输入问题或日志... ] [发送] | ++---------------------------------------+ +``` + +--- + +### 3. 四态定义 (States Definition) + +1. **正常态 (Normal)**: + - 气泡区分清晰:用户提问居右(中性浅灰底),Copilot 回答居左(纯白底 + 1px Slate-200 边框 + 左侧 3px Teal-700 标记线)。 + - 「依据确凿」:展示绿色微标及可点击的代码/Wiki锚点。 + - 「不确定」:展示黄红警戒卡片,前景色 Amber-700,底色 Amber-50,明确标示知识库盲区与人工核实建议。 +2. **加载中态 (Loading)**: + - 输入框发送按钮变为 `LoaderCircle (spin)` 态,禁用输入。 + - 对话流尾部追加 Copilot 思考气泡:展示骨架波纹(3 行渐变骨架条,脉冲呼吸动效),附最简文案「正在检索 Wiki 规则与集群事件…」。 +3. **空数据态 (Empty)**: + - 首次进入或清空对话后,主屏居中展示微图标 `Bot`,主标题「输入现象或日志开始诊断」,副标题「已挂载当前项目 Wiki 与集群只读监控」。 + - 下方提供 3 个快速排查建议胶囊按钮(如:「切片任务超时排查」、「查看今日 OOMKilled Pod」、「检查网关 Ingress 状态」)。 +4. **错误态 (Error)**: + - 若调用 API 超时或 Token 耗尽:气泡内渲染红色弱底警示栏「暂时无法完成诊断推演 (网络连接超时)」,提供单动作按钮「重新生成」。 + +--- + +## 页面 2:许愿进度 (Run 详情) + +### 1. 业务职责与交互流 +- **定位**:客户跟踪单一许愿从「意图澄清 -> 独立沙箱编码 -> 自动化验证 -> 门禁检查 -> 交付报告」全生命周期的核心看板。 +- **核心组件**: + 1. 顶部 Header:目标 (Goal)、分支 (Branch)、触发人、执行器(如 Claude Code)、实时状态; + 2. 阶段时间线 (Timeline):串联意图澄清、沙箱运行、自动化验证、代码审查、待确认; + 3. 风险等级徽标 (Risk Level Badge):动态计算并醒目标注 Low / Medium / High; + 4. 门禁结果矩阵 (Gates Grid):展示 G1 新鲜度门、G2 验证门、G3 基线门、G4 风险分级门等通过情况; + 5. **交付报告四栏 (Four-column Delivery Report)**:依据 droboticflow 经验沉淀的四栏核验清单: + - **通过项 (Passed)** + - **失败项 (Failed)** + - **待验证项 (Pending Verification)** + - **未做项 (Out of Scope / Skipped)** + +--- + +### 2. 界面线框与布局 (Wireframes) + +#### 2.1 桌面端 (1440px) + +``` ++------------------------------------------------------------------------------------------------------------------+ +| TopNav: WishForge / 运行记录 / RUN-20261109-082 [返回列表] | ++------------------------------------------------------------------------------------------------------------------+ +| PageHeader: | +| 运行 RUN-20261109-082 [风险等级: 中风险 (Medium)] [运行状态: 待发布确认] | +| 目标:调整视频切片算子超时从 30s 至 60s,并修正网关代理 Ingress 匹配前缀 | +| 元信息: 分支 `wishforge/slice-timeout-60s` | 执行器: Claude Code (沙箱运行) | 耗时: 3m 42s | 触发人: 张工 (客户) | ++------------------------------------------------------------------------------------------------------------------+ +| 阶段时间线 (Timeline): | +| (✓) 1. 意图澄清 (✓) 2. 沙箱执行 (✓) 3. 自动化验证 (✓) 4. 防事故门禁 (●) 5. 发布确认 | +| 已对齐验收标准 3 条 改动 2 文件 +14/-3 用例 18/18 通过 G1~G4 全部核准 等待客户负责人审批 | ++------------------------------------------------------------------------------------------------------------------+ +| 主内容区栅格 (2:1 左右分栏): | +| | | +| [左栏 66%]: 交付报告与证据核验 | [右栏 33%]: 防事故门禁结果 | +| +-----------------------------------------------------------------+ | +----------------------------------------+ | +| | 交付核查四栏报告 (Delivery Ledger) | | | 门禁自检结果 (Security Gates) | | +| |-----------------------------------------------------------------| | |----------------------------------------| | +| | [√ 通过项 (Passed) - 3] | | | [✓ PASS] G1 新鲜度门 (Freshness) | | +| | • 视频切片算子超时环境变量配置支持 DEFAULT_TIMEOUT_SECS=60s | | | 对齐线上 origin/dev 最新提交 877307c | | +| | • tests/operators/slice.test.ts 单元测试通过 | | | [✓ PASS] G2 自动化验证门 (Verify Gate) | | +| | • 编译与类型检查 (typecheck) 无错误 | | | 退出码 0,生成结构化 JSON 证据包 | | +| |-----------------------------------------------------------------| | | [✓ PASS] G3 基线完整门 (Baseline) | | +| | [× 失败项 (Failed) - 0] | | | 未篡改 known-failures / 未删减断言 | | +| | 无失败项 | | | [! WARN] G4 风险定级门 (Risk Level) | | +| |-----------------------------------------------------------------| | | 评级: 中风险 (修改网关路由配置) | | +| | [? 待验证项 (Pending Verification) - 1] | | | 权限要求: 需客户团队负责人双重确认 | | +| | • 线上 4K 巨型视频切片实测需在真实环境观察 (退出码 2) | | +----------------------------------------+ | +| |-----------------------------------------------------------------| | | +| | [- 没做/延期项 (Out of Scope) - 1] | | [代码变更摘要 (Diff Summary)] | | +| | • 节点物理内存配额未修改(已拆出独立工单处理) | | +----------------------------------------+ | +| +-----------------------------------------------------------------+ | | k8s/ingress-nginx.yaml +4 / -1 | | +| | | docs/operators/视频切片.md +10 / -2 | | +| [代码改动审阅 (Diff Viewer)]: | | [查看完整 Diff 比对 (2 文件)] | | +| +-----------------------------------------------------------------+ | +----------------------------------------+ | +| | @@ -42,3 +42,5 @@ proxy-read-timeout: 30s | | +| | - proxy-read-timeout: "30s" | [操作入口] | +| | + proxy-read-timeout: "60s" | [前往发布确认页面 ->] | +| +-----------------------------------------------------------------+ | [终止任务 / 丢弃分支] | ++------------------------------------------------------------------------------------------------------------------+ +``` + +#### 2.2 移动端 (390px) + +``` ++---------------------------------------+ +| [< 返回] 运行详情 #082 | ++---------------------------------------+ +| 调整视频切片算子超时至 60s | +| 状态: 待发布确认 | [中风险徽标] | +| 分支: wishforge/slice-timeout-60s | +|---------------------------------------| +| 阶段: 4/5 步 (自动化验证已过) | +| 耗时: 3m 42s | 执行器: Claude Code | +|---------------------------------------| +| 门禁自检结果 (G1~G4): | +| [✓] G1 新鲜度对齐 | +| [✓] G2 验证通过 (exit 0) | +| [✓] G3 测试基线未动 | +| [!] G4 评级: 中风险 | +|---------------------------------------| +| 交付四栏报告: | +| [✓ 通过 - 3 项] | +| • 环境变量超时支持 60s | +| • slice.test.ts 跑通 | +| • typecheck 通过 | +| [? 待验证 - 1 项] | +| • 4K 巨型切片需实测 | +| [- 没做 - 1 项] | +| • 节点物理配额超卖未改 | +|---------------------------------------| +| 改动文件: 2 个 (+14 / -3) | +| [查看代码 Diff] | +|---------------------------------------| +| [ 前往发布确认页面 (主按钮) ] | ++---------------------------------------+ +``` + +--- + +### 3. 四态定义 (States Definition) + +1. **正常态 (Normal)**: + - 风险徽标根据级别渲染专属样式:低风险(绿色小盾牌)、中风险(橙黄盾牌)、高风险(刺目红盾牌 + 加粗实线)。 + - 四栏报告以卡片矩阵展示,分类明确,不可折叠隐藏重要未做/待验证项。 +2. **加载中态 (Loading)**: + - 顶部 Header 显示 2 条骨架条。 + - 时间线与四栏报告区域渲染 4 块 `wf-pulse` 灰色占位方块,保持高度 320px,防止内容跳动。 +3. **空数据态 (Empty)**: + - 任务刚创建尚未进入执行队列时:时间线第一步高亮,下方四栏报告区域展示空卡片,文案「执行器准备中,等待沙箱启动与分支检出…」。 +4. **错误态 (Error)**: + - 若 G2 验证失败或命令超时(退出码 124):时间线第 3 步标记红叉 `(X)`,四栏报告「失败项」置顶并展开红色终端日志框,展示最近 50 行错误输出与一键「向 Copilot 发起修复」快捷按钮。 + +--- + +## 页面 3:发布确认 (Release Review & Approval) + +### 1. 业务职责与交互流 +- **定位**:变更投入运行环境(测试/生产)前的最后一道安全门。 +- **决策规则**: + - **低/中风险**:由客户团队负责人(如张工)自主核验并单人批准。 + - **高风险**:涉及数据库改动、权限升级、超卖超出节点余量、副本缩为 0 等,**必须平台方技术管理员(Platform Admin)与客户负责人双人批准**,普通客户界面明确禁用批准按钮并注明原因。 +- **核心组件**: + 1. 改动摘要(文件清单、影响服务、镜像 Digest); + 2. 风险等级评定与依据拆解; + 3. **审批权限说明**(明确指出「谁能批准」); + 4. 验证证据链(集成测试退出码、沙箱命令报告); + 5. 醒目的生产「一键回滚」与版本切换按钮。 + +--- + +### 2. 界面线框与布局 (Wireframes) + +#### 2.1 桌面端 (1440px) + +``` ++------------------------------------------------------------------------------------------------------------------+ +| TopNav: WishForge / 发布与审批 / REL-20261109-019 [查看发布列表] | ++------------------------------------------------------------------------------------------------------------------+ +| PageHeader: | +| 部署发布确认 · 生产环境 (Production) [当前状态: 待审批 (Awaiting Approval)] | +| 绑定运行: RUN-082 (调整切片超时至 60s) | 目标环境: fanyu-production | 目标镜像: droboticflow/api@sha256:7f9a8c... | ++------------------------------------------------------------------------------------------------------------------+ +| 风险与审批权限决策看板 (Approval Authority Banner): | +| +--------------------------------------------------------------------------------------------------------------+ | +| | [ShieldAlert] 风险综合评定:中风险 (Medium Risk) | | +| | 判定依据:修改了网关路由超时配置 (k8s/ingress-nginx.yaml),无数据库 Schema 变更,无权限放大。 | | +| | 审批权限:【客户负责人】即可独立批准发布 | | +| | 当前操作员身份:张工 (客户团队负责人) · 具备批准权限 | | +| +--------------------------------------------------------------------------------------------------------------+ | +| | +| 主区域分栏栅格 (左右 1:1 或 7:5): | +| | +| [左栏]: 改动摘要与制品溯源 | [右栏]: 验证证据与审批操作 | +| +-----------------------------------------------------------------+ | +----------------------------------------+ | +| | 改动明细 (Changeset) | | | 自动化验证证据 (Verification Evidence) | | +| |-----------------------------------------------------------------| | |----------------------------------------| | +| | • Git 目标基准: dev (877307c) -> 分支 wishforge/slice-timeout | | | • 单元测试验证: 18 passed, 0 failed | | +| | • 变更统计: 2 个文件修改,新增 14 行,删除 3 行 | | | • 验证环境: 沙箱隔离 Pod (seatbelt 容器) | | +| | • 制品镜像: droboticflow/api:v1.4.2-patch01 | | | • 证据校验包: SHA-256 (e3b0c44298fc...) | | +| | 镜像摘要: sha256:7f9a8c12... (已完成完整性签名验证) | | | • 冒烟测试时长: 1m 15s (退出码: 0) | | +| |-----------------------------------------------------------------| | +----------------------------------------+ | +| | 变更影响的服务组件: | | | +| | 1. droboticflow-api (滚动更新,副本数 2 -> 2) | | [双重确认与批准操作区] | | +| | 2. ingress-controller (配置热重载,无中断) | | +----------------------------------------+ | +| +-----------------------------------------------------------------+ | | [ ] 我已仔细核对变更摘要与关联证据 | | +| | | [ ] 确认已获知当前为生产环境发布 | | +| [历史版本与快速回滚准备]: | | | | +| +-----------------------------------------------------------------+ | | [ 批准并立即部署上线 (Primary) ] | | +| | 当前运行版本: v1.4.1 (REL-018,发布于 3 天前) | | [ 驳回本次发布请求 (Secondary) ] | | +| | 紧急预案: 如部署后指标异常,可随时点击下方回滚按钮: | | +----------------------------------------+ | +| | [ 预置回滚至 v1.4.1 按钮 (琥珀黄描边) ] | | | ++------------------------------------------------------------------------------------------------------------------+ +``` + +#### 2.2 移动端 (390px) + +``` ++---------------------------------------+ +| [< 返回] 发布审批 REL-019 | ++---------------------------------------+ +| 生产环境发布确认 | +| 状态: 待审批 | 评级: [中风险] | +|---------------------------------------| +| 审批权限提示: | +| 客户负责人即可批准。 | +| 你的身份: 张工 (具备权限) | +|---------------------------------------| +| 改动摘要: | +| • 分支: wishforge/slice-timeout | +| • 文件: 2 个 (+14 / -3) | +| • 镜像: ...sha256:7f9a8c | +| • 影响服务: droboticflow-api (2副本) | +|---------------------------------------| +| 验证证据: | +| • 自动化测试通过 (18 用例, exit 0) | +| • 完整性校验通过 (SHA-256 匹配) | +|---------------------------------------| +| [√] 我已核对代码与证据 | +| | +| [ 批准并立即发布 (高亮大按钮) ] | +| [ 驳回发布请求 ] | +| | +| ------------------------------------- | +| 应急保障: | +| [ 紧急回滚至上一版本 (v1.4.1) ] | ++---------------------------------------+ +``` + +--- + +### 3. 四态定义 (States Definition) + +1. **正常态 (Normal)**: + - 明确突出「谁能批准」:若为高风险,卡片显示红框「必须平台方审批」,下方批准按钮禁用,附文案「等待平台方运维介入」;若为低/中风险,允许客户负责人一键勾选复选框并点击「批准」。 + - 回滚按钮常驻在页面底部,次要幽灵/警告样式,防止误触,但紧急时刻 1 秒内可定位。 +2. **加载中态 (Loading)**: + - 点击批准后,按钮进入 `busy` 态(内置 Spinner,文案变为「正在提交控制面部署流水线…」)。 + - 页面顶部浮现渐变进度条。 +3. **空数据态 (Empty)**: + - 访问 `/releases` 且当前无待审批任务时:展示绿色勾选卡片,标题「所有发布均已完成」,副标题「当前环境运行版本与最新审批一致」,附「查看历史发布记录」链接。 +4. **错误态 (Error)**: + - 审批提交失败(如:租约过期、代码冲突或权限不足):弹窗或在操作区上方展示固定 `ErrorNotice`:「发布审批失败:目标环境锁定,已有并发部署正在进行中」,附重试与刷新按钮。 + +--- + +## 页面 4:集群资源 (Cluster Resources) + +### 1. 业务职责与交互流 +- **定位**:客户与平台方透视底层物理算力、服务健康度、存储状态与超卖风险的专业仪表盘。 +- **业务数据实况 (真实基准)**: + - **总物理节点**:3 台物理/虚拟机: + - 1 台大节点:`56 核 CPU / 220 GiB 内存 / 2 张 GPU (NVIDIA A100)` + - 2 台小节点:`8 核 CPU / 31 GiB 内存`(合计 16 核 / 62 GiB,无 GPU) + - **超卖特征**:两台小节点严重承载基础设施,Requests 虽未超,但 Limits 合计已达 **CPU 178%**(严重超卖)、**内存 93%**(濒临 OOM 危险阈值)。 +- **核心组件**: + 1. **顶部总账 (Cluster Overview Ledger)**:CPU、内存、GPU、存储四大仪表,严格并列展示 5 个数值: + - `总量 (Total Capacity)` + - `保底已占 (Requests)` + - `最坏情况 (Limits)` + - `实际在用 (Actual Used)` + - `剩余可用 (Available Free)` + 2. **节点列表 (Nodes Grid)**:展示 3 个节点的 CPU/内存/GPU 详细占用,当 Limits > 100% 时,以刺目警示色突出展示**超卖倍数**(如 1.78x 超卖); + 3. **服务列表 (Services & Workloads)**:每个服务包含用途说明、副本数、使用率占上限比例、重启与 OOM 次数、实时健康告警; + 4. **存储卷 (Persistent Volumes)**:存储卷挂载路径、容量、使用率、读写模式; + 5. **快捷入口**:「问 Copilot」诊断入口常驻,支持一键将当前集群水位数据作为 Prompt 带入 Copilot。 + +--- + +### 2. 界面线框与布局 (Wireframes) + +#### 2.1 桌面端 (1440px) + +``` ++------------------------------------------------------------------------------------------------------------------+ +| TopNav: WishForge / 集群资源监控 (Cluster Infrastructure) [问 Copilot 排查资源] [刷新] | ++------------------------------------------------------------------------------------------------------------------+ +| PageHeader: | +| 集群算力与服务总账 [集群状态: 存在超卖告警 (Warning)] | +| 3 个节点在线 | 2 张 GPU 就绪 | 运行 8 个关键微服务 | 数据基于只读 ServiceAccount 实时采集 | ++------------------------------------------------------------------------------------------------------------------+ +| 顶部四大核心资源总账 (Overview Ledger - 4 列卡片): | +| +--------------------------------------------------------------------------------------------------------------+ | +| | [CPU 算力总账] | [内存容量总账] | [GPU 算力 (专用)] | [集群共享存储 (NFS/Local)] | | +| | 总量: 72 核 | 总量: 282 GiB | 总量: 2 张 (A100) | 总量: 2.0 TiB | | +| | 保底(Req): 38 核 (52%) | 保底(Req): 142 GiB | 保底(Req): 1 张 (50%) | 实际在用: 840 GiB (41%) | | +| | 最坏(Lim): 94 核 (130%)| 最坏(Lim): 224 GiB | 最坏(Lim): 2 张 (100%)| 剩余可用: 1.16 TiB | | +| | 实际在用: 26 核 (36%) | 实际在用: 98 GiB | 实际在用: 1 张 (50%) | 挂载卷数: 6 个 PVC | | +| | 剩余空间: 34 核 (空闲) | 剩余空间: 140 GiB | 剩余空间: 1 张 (空闲) | 状态: 读写正常 | | +| | [!] 警示: Lim 已超卖 | 运行水位: 正常 | 运行水位: 充足 | 运行水位: 健康 | | +| +--------------------------------------------------------------------------------------------------------------+ | +| | +| 节点明细 (Nodes Status - 突出超卖与瓶颈): | +| +--------------------------------------------------------------------------------------------------------------+ | +| | 节点主机名 规格规格 CPU 分配 (Req / Lim / 超卖) 内存分配 (Req / Lim) GPU 状态与告警 | | +| |--------------------------------------------------------------------------------------------------------------| | +| | node-big-01 56C / 220Gi 22C (39%) / 48C (85%) / 0.85x 90Gi (40%) / 160Gi(72%) 2/2 [√ 健康] | | +| | node-small-01 (小) 8C / 31Gi 8C (100%) / 23C [178% 超卖!] 26Gi (83%) / 29Gi (93%) 0/0 [! 内存超卖告警] | | +| | node-small-02 (小) 8C / 31Gi 8C (100%) / 23C [178% 超卖!] 26Gi (83%) / 29Gi (93%) 0/0 [! 内存超卖告警] | | +| +--------------------------------------------------------------------------------------------------------------+ | +| | +| 服务与负载列表 (Workloads & Pods): | +| +--------------------------------------------------------------------------------------------------------------+ | +| | 服务名称 用途说明 副本数 CPU/内存占上限比例 重启/OOM 计数 健康状态 操作 | | +| |--------------------------------------------------------------------------------------------------------------| | +| | droboticflow-api 业务主接口与调度 2 / 2 CPU 12% | 内存 42% 0 / 0 [√ 正常] [查看日志] | | +| | droboticflow-worker 异步标注切片计算 2 / 2 CPU 78% | 内存 89% 3 次 / 2 OOM [! 告警] [问 Copilot]| | +| | drosync-coordinator 同步协同与心跳 1 / 1 CPU 5% | 内存 18% 0 / 0 [√ 正常] [查看日志] | | +| | headpose-inference 姿态推理模型容器 1 / 1 GPU 80% | 内存 64% 0 / 0 [√ 正常] [查看指标] | | +| | mongodb-cluster 业务数据主从实例 1 / 1 只读受控挂载 0 / 0 [√ 只读] [监控] | | +| +--------------------------------------------------------------------------------------------------------------+ | +| | +| 存储卷与数据资产 (Storage Volumes): | +| +--------------------------------------------------------------------------------------------------------------+ | +| | PVC 名称 挂载服务 挂载路径 容量大小 使用率 读写模式 | | +| |--------------------------------------------------------------------------------------------------------------| | +| | pvc-video-raw-data droboticflow-worker /data/raw-videos 1.0 TiB 45% (健康) ReadWriteMany| | +| | pvc-model-qwen-cache headpose-inference /root/.cache/modelscope 500 GiB 68% (健康) ReadOnlyMany | | +| | pvc-mongo-storage mongodb-cluster /data/db 200 GiB 28% (健康) ReadWriteOnce| | +| +--------------------------------------------------------------------------------------------------------------+ | ++------------------------------------------------------------------------------------------------------------------+ +``` + +#### 2.2 移动端 (390px) + +``` ++---------------------------------------+ +| [=] 集群资源总账 [问 Copilot] | ++---------------------------------------+ +| 集群容量总览: | +| • CPU: 72核 | Req 52% | Lim 130%(超) | +| • 内存: 282Gi| Req 50% | Lim 79% | +| • GPU: 2张 (A100) | 在用 1 张 | +| • 存储: 2.0TiB | 已用 840GiB (41%) | +|---------------------------------------| +| 物理节点状态 (3): | +| [!] node-small-01 (8C/31Gi) | +| CPU Limits: 178% [严重超卖] | +| 内存 Limits: 93% [频临 OOM] | +| | +| [!] node-small-02 (8C/31Gi) | +| CPU Limits: 178% [严重超卖] | +| | +| [√] node-big-01 (56C/220Gi/2GPU) | +| 运行健康,负载 40% | +|---------------------------------------| +| 服务异常监控: | +| [!] droboticflow-worker | +| 切片计算 | 副本 2/2 | +| 内存 89% | 重启 3次 (2次 OOM) | +| [点击一键诊断此服务] | +| | +| [√] 其余 7 个微服务运行平稳 | +|---------------------------------------| +| 存储卷概况: 6 个 PVC 全部就绪 | ++---------------------------------------+ +``` + +--- + +### 3. 四态定义 (States Definition) + +1. **正常态 (Normal)**: + - 顶部四个总账卡片整齐排列,清晰列出「总量、Requests、Limits、实际用量、剩余」。 + - 当小节点 Limits 超过 100% 时,字体自动由常规灰黑色转为高饱和橙黄色,超卖倍数标签增加实线边框(如 `1.78x 超卖`),Hover 弹出轻量 Tooltip 说明「容器极限配置超额,峰值并发下可能触发内核降频或 OOM 驱逐」。 + - OOM 计数大于 0 的服务自动置顶并显示醒目的红点。 +2. **加载中态 (Loading)**: + - 四个指标卡片显示 60px 高的灰色骨架块。 + - 节点列表与服务列表显示为 4 行透明度呼吸过渡的表格骨架,防止数据刷新时的卡顿跳动。 +3. **空数据态 (Empty)**: + - 仅在未配置只读 ServiceAccount 时发生:屏幕展示盾牌插图,标题「集群资源监控未接入」,副标题「尚未配置集群只读 ServiceAccount 或 Kubeconfig」,下方提供「查看接入文档」按钮。 +4. **错误态 (Error)**: + - K8s API 访问受阻或网络超时:保留最后一次成功的缓存数据并在顶部浮起黄色警示条「控制面数据同步延迟(10:25:00 缓存数据)」,右侧放置「立即重连」按钮。 + +--- + +## 4. 全栈工程师实现顺序与验收标准 (Implementation Guide & Acceptance Criteria) + +### 4.1 推荐落地实现顺序 (Milestones) + +``` +[M1: 规范入库与 UI 组件升级] -> [M2: 集群资源监控页] -> [M3: 发布审批流改造] -> [M4: Run 详情与四栏报告] -> [M5: Copilot 面板增强] +``` + +1. **Milestone 1:设计系统变量引入与基础组件改造 (2 天)** + - 将 `docs/design/tokens.md` 中的 CSS 变量注入 `apps/web/src/app/globals.css` 头部; + - 升级 `apps/web/src/components/ui.tsx`:为 `Button`、`EmptyState`、`Status` 补齐对应样式与骨架屏组件 `Skeleton`; + - 确保原有页面完全向后兼容,无样式崩塌。 +2. **Milestone 2:集群资源页新建 (`features/cluster-resources.tsx`) (2 天)** + - 纯前端依据本设计稿的文字线框与网格搭建页面骨架; + - 严格实现「顶部总账五大数值(总量、Req、Lim、用量、剩余)」与「小节点超卖醒目警示」; + - 接入现有只读 ServiceAccount 聚合接口。 +3. **Milestone 3:发布确认页审批逻辑改造 (`features/releases.tsx`) (2 天)** + - 增加「风险等级与审批权限决策看板」; + - 依据 `risk.ts` 实施严格的按钮拦截:高风险仅允许平台方批准,低/中风险开放给客户负责人; + - 强化生产环境回滚入口。 +4. **Milestone 4:Run 详情页四栏报告与时间线重构 (`features/runs.tsx`) (2.5 天)** + - 重构信息架构:将垂直堆叠改为「左侧交付四栏清单 + 右侧门禁矩阵」; + - 严格落地「通过项、失败项、待验证项、未做项」四栏布局。 +5. **Milestone 5:Copilot 面板结构化卡片与依据链适配 (`features/copilot.tsx`) (2 天)** + - 引入「置信度不足/依据不足」警示卡片; + - 代码依据高亮(`文件:行号`); + - 一键将诊断结论带入「转成许愿」表单。 + +--- + +### 4.2 严格验收标准 (Acceptance Criteria) + +全栈工程师交付 PR 时,必须按以下四项门槛逐条核对并提供证据: + +1. **双断点严格适配 (1440px & 390px)**: + - **桌面端 (1440px 视口)**:核心内容容器居中或全屏响应,无留白失控或文字过长不易阅读的问题,栅格分栏比例严格符合设计稿。 + - **移动端 (390px 视口)**:所有表格必须自适应卡片化(Cardify)或优雅折叠,绝对严禁出现页面级横向滚动条(Horizontal Scrollbar);按钮点击热区高度 ≥ 38px。 +2. **四态闭环检查 (4 States Completed)**: + - 交付的 4 个核心页面,每个页面都必须包含完整的代码处理路径: + - **正常态 (Normal)**:数据渲染整洁,文案遵循最简文案规范; + - **加载中态 (Loading)**:必须呈现结构匹配的脉冲骨架屏,拒绝单一全局 Spinner,保证页面加载无剧烈跳动; + - **空数据态 (Empty)**:有语义明确的业务图标、简明描述和明确恢复操作入口; + - **错误态 (Error)**:提供友好、无黑话的错误提示条与重试/重新连接按钮。 +3. **状态截图归档 (Visual Evidence)**: + - 在开发机或测试环境浏览器中,完成 4 个页面 × 2 种宽度(1440、390)× 4 种状态的界面走查与截图留存,按规范归档到 `docs/verification/` 目录下备查。 +4. **静态类型与构建检查 (Typecheck & Lint Pass)**: + - 运行 `npm run typecheck`(或 `turbo run typecheck`)一次性通过,TypeScript 0 error; + - 运行前端基础单测与构建检查,无 regression 错误。 diff --git a/docs/design/tokens.md b/docs/design/tokens.md new file mode 100644 index 0000000..c991568 --- /dev/null +++ b/docs/design/tokens.md @@ -0,0 +1,173 @@ +# WishForge 设计规范与设计令牌 (Design Tokens & Component Rules) + +> 适用范围:WishForge 前端 (`apps/web`) +> 设计语言与基调:工程严谨、数据透彻、零冗余装饰、轻盈沉稳。以最简文案规范(参考 droboticflow `copy-guidelines.md`)为底座。 + +--- + +## 1. 颜色系统 (Color Tokens) + +将原本分散、硬编码的 131 种颜色统一归纳为高辨识度、高无障碍对比度(WCAG AA/AAA,文字对比度 ≥ 4.5:1)的语义化色板。 + +### 1.1 品牌色与中性色 (Brand & Neutrals) + +| 语义变量名 | Hex 建议值 | 对比度与用途 | 迁移映射说明 | +| :--- | :--- | :--- | :--- | +| `--wf-brand-primary` | `#0f766e` (Teal-700) | 核心主动作 (CTA)、主要链接、关键高亮。比老旧 `#168574` 更温润且稳健 | 替换老 `--teal` 及相关变体 | +| `--wf-brand-hover` | `#0d625b` (Teal-800) | 主动作 hover / active 态 | 替换老 `--teal-dark` | +| `--wf-brand-surface` | `#f0fdfa` (Teal-50) | 选中卡片浅底、高亮徽标背景 | 替换老 `--teal-pale`、`#eaf5f1` | +| `--wf-brand-border` | `#ccfbf1` (Teal-100) | 品牌浅色边框 | 替换分散的浅绿色边框 | +| `--wf-navy-dark` | `#0f172a` (Slate-900) | 侧边栏底色、深色终端背景、强强调文字 | 替换老 `--navy: #102031` | +| `--wf-bg-app` | `#f8fafc` (Slate-50) | 控制台主背景、灰底卡片槽位 | 保持并规范 `--bg` | +| `--wf-bg-surface` | `#ffffff` | 面板卡片、模态弹窗、下拉菜单纯白背景 | 替换 `--surface` | +| `--wf-bg-subtle` | `#f1f5f9` (Slate-100) | 表头背景、代码块背景、弱卡片背景 | 替换 `#f6f8fb`、`#fbfcfe`、`#edf2f6` | +| `--wf-border-subtle`| `#e2e8f0` (Slate-200) | 卡片常规描边、表格行分割线 | 替换老 `--border: #e1e7ef`、`#d8e0ea` | +| `--wf-border-strong`| `#cbd5e1` (Slate-300) | 输入框聚焦外沿、关键分割线、Tab底边 | 替换 `#b4c1d0` | +| `--wf-text-strong` | `#0f172a` (Slate-900) | 大标题、加粗数值、核心状态 | 替换 `--ink: #122033` | +| `--wf-text-body` | `#334155` (Slate-700) | 正文描述、表单输入文字、表格通用项 | 保证 7:1 极高对比度 | +| `--wf-text-muted` | `#64748b` (Slate-500) | 次要说明、时间戳、辅助标签(4.6:1 达标)| 替换老 `--muted: #5b6b80` | +| `--wf-text-disabled`| `#94a3b8` (Slate-400) | 禁用态文字、占位符文字 | 替换零散灰色 | + +### 1.2 状态反馈色 (State Feedbacks) + +| 语义状态 | 主前景色 (Solid/Text) | 浅背景底色 (Surface) | 边框色 (Border) | 业务语境应用 | +| :--- | :--- | :--- | :--- | :--- | +| **成功 (Success)** | `#15803d` (Green-700) | `#f0fdf4` (Green-50) | `#bbf7d0` (Green-200) | 运行成功、门禁全绿、服务就绪、健康 | +| **警告 (Warning)** | `#b45309` (Amber-700) | `#fffbeb` (Amber-50) | `#fde68a` (Amber-200) | 排队等待、需人工确认、超卖预警、待审 | +| **危险 (Danger)** | `#b91c1c` (Red-700) | `#fef2f2` (Red-50) | `#fecaca` (Red-200) | 运行失败、门禁阻断、容器 OOM、异常崩溃 | +| **信息 (Info)** | `#0369a1` (Sky-700) | `#f0f9ff` (Sky-50) | `#bae6fd` (Sky-200) | 阶段通知、只读说明、执行器准备中 | + +### 1.3 核心分级风控色 (Risk Level Hierarchy) + +*用于防事故门禁(G4)与发布审批,严格杜绝误操作*: + +| 风险级别 | 主题色与 Tag 表现 | 适用范围与阻断规则 | 审批要求与视觉指示 | +| :--- | :--- | :--- | :--- | +| **低风险 (Low)** | 文字 `#15803d`
底色 `#f0fdf4`
边框 `#bbf7d0` | 纯前端样式、文档修订、只读配置、无破坏性脚本 | 客户负责人自主审批。
浅绿扁平徽标,小勾图标。 | +| **中风险 (Medium)** | 文字 `#b45309`
底色 `#fffbeb`
边框 `#fde68a` | 后端普通业务逻辑变更、依赖小版本升级、轻量配置增删 | 客户负责人审批,双重确认提示。
明黄警示徽标。 | +| **高风险 (High)** | 文字 `#b91c1c`
底色 `#fef2f2`
边框 `#ef4444` (实线 1.5px) | 涉及数据库迁移/破坏性改动、权限放大、节点资源超限/缩为0、测试基线篡改 | **必须平台方技术审批**,客户无权单独发布。
刺目朱红、外圈呼吸脉冲边框、双人签名卡。 | + +--- + +## 2. 标尺阶梯与排版 (Type & Layout Scales) + +### 2.1 字号与行高阶梯 (Typography) +统一采用系统字体栈:`Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif`。代码/数字等宽字体栈:`"JetBrains Mono", SFMono-Regular, Consolas, monospace`。 + +| Token | 字号 / 行高 | 字重 (Weight) | 推荐使用场景 | +| :--- | :--- | :--- | :--- | +| `--wf-font-xs` | `11px` / `16px` | 400 / 500 | 徽章 Tag、细小时间戳、辅助注释 | +| `--wf-font-sm` | `12px` / `18px` | 400 / 500 / 600 | 表格正文、键值对标签、代码片段、终端日志 | +| `--wf-font-base` | `14px` / `20px` | 400 / 500 | 页面正文字体、输入框文本、按钮文字 | +| `--wf-font-md` | `16px` / `24px` | 600 | 卡片二级标题、列表分组标题、弹窗标题 | +| `--wf-font-lg` | `20px` / `28px` | 600 | 核心模块标题、阶段大步标题 | +| `--wf-font-xl` | `24px` / `32px` | 700 | 页面一级标题 (PageHeader)、关键总账数字 | + +### 2.2 间距网格 (Spacing Grid - 4px/8px System) + +| Token | 数值 | 经典对齐场景 | +| :--- | :--- | :--- | +| `--wf-space-1` | `4px` | 图标与文字间隙、Tag 内部小间距 | +| `--wf-space-2` | `8px` | 紧凑表单控件行距、按钮内边距上下、表格紧凑单元格 | +| `--wf-space-3` | `12px` | 标准表单控件行距、按钮内边距左右、卡片内小组件间距 | +| `--wf-space-4` | `16px` | 面板 Padding、列表项间距、标准栅格缝隙 (Gap) | +| `--wf-space-6` | `24px` | 页面区块大间隔、PageHeader 与主内容分界 | +| `--wf-space-8` | `32px` | 页面顶部与底部大外边距、空状态垂直撑开高度 | + +### 2.3 圆角、边框与投影 (Radius, Borders & Elevation) + +```css +:root { + /* 圆角规范 */ + --wf-radius-sm: 4px; /* 小型 Tag、复选框、代码片段 */ + --wf-radius-md: 6px; /* 标准按钮、输入框、常规卡片内元素 (取代原本古怪的 7px) */ + --wf-radius-lg: 10px; /* 核心 Panel、Modal 对话框、悬浮浮窗 */ + --wf-radius-full: 9999px; /* 胶囊型 Status 指示器、头像 */ + + /* 边框规范 */ + --wf-border-width: 1px; + --wf-border-focus: 2px solid var(--wf-brand-primary); + + /* 阴影层级 */ + --wf-shadow-xs: 0 1px 2px 0 rgba(15, 23, 42, 0.05); /* 平铺卡片微投影 */ + --wf-shadow-sm: 0 1px 3px 0 rgba(15, 23, 42, 0.1), 0 1px 2px -1px rgba(15, 23, 42, 0.1); + --wf-shadow-md: 0 4px 6px -1px rgba(15, 23, 42, 0.1), 0 2px 4px -2px rgba(15, 23, 42, 0.1); /* 下拉菜单、Hover浮起 */ + --wf-shadow-lg: 0 10px 15px -3px rgba(15, 23, 42, 0.1), 0 4px 6px -4px rgba(15, 23, 42, 0.1); /* Modal、侧滑 Copilot */ +} +``` + +--- + +## 3. 标准组件规范 (Component Specs) + +### 3.1 按钮 (Button) +- **Primary**:实心背景 `var(--wf-brand-primary)`,文字纯白,无外边框。Hover 为 `var(--wf-brand-hover)`。高度统一为 34px(移动端 40px),内边距 `0 14px`。 +- **Secondary**:纯白底 `var(--wf-bg-surface)`,边框 `1px solid var(--wf-border-subtle)`,文字 `var(--wf-text-strong)`。Hover 浅灰底 `var(--wf-bg-subtle)`。 +- **Danger**:浅红底 `var(--wf-danger-surface)`,红边框 `var(--wf-danger-border)`,文字 `var(--wf-danger-solid)`。涉及破坏性操作(如强制回滚、终止任务)。 +- **Ghost**:无底色无描边,Hover 浅灰底,用于折叠展开、次要辅助操作。 +- **Busy 状态**:禁用指针,文案透明度 0.6,内置 14px Lucide Spinner 平滑旋转,严禁产生宽度抖动。 + +### 3.2 表格与数据列 (Table & Data Grid) +- **表头 (Th)**:高度 36px,背景 `var(--wf-bg-subtle)`,文字 `var(--wf-text-muted)`,字号 `12px`,大写字母略微间距,底边 `1px solid var(--wf-border-subtle)`。 +- **单元格 (Td)**:高度 48px(紧凑模式 40px),垂直居中,正文字号 `13px`。斑马纹可选,Hover 单行整体着色浅蓝/灰 `var(--wf-brand-surface)`。 +- **操作列**:靠右对齐,操作按钮紧凑化排列。 + +### 3.3 面板与卡片 (Panel & Card) +- 容器采用 `var(--wf-bg-surface)`,描边 `1px solid var(--wf-border-subtle)`,圆角 `var(--wf-radius-lg)`,阴影 `var(--wf-shadow-xs)`。 +- **Panel Header**:高度 48px,左右 flex 布局,左侧标题 `15px` 粗体加图标,右侧次要操作或统计标签。 +- 移除非必要的多层嵌套内边框,减少视觉噪点。 + +### 3.4 状态与徽标 (Badges & Statuses) +- 统一为 **圆角胶囊 (Capsule)** 或 **微圆角矩形 (Tag)**。 +- 必须包含 **前置实体微圆点 (Status Dot, 6px)**: + - 成功:绿点呼吸(运行中为青蓝点脉冲); + - 待审/等待:明黄点常亮; + - 失败/告警:鲜红点常亮。 +- 杜绝纯依靠颜色传递信息,文案必须严格使用受控词汇(如「健康」、「待审批」、「平台审批中」)。 + +### 3.5 表单与输入控件 (Form Controls) +- 高度 36px,边框 `1px solid var(--wf-border-strong)`,圆角 `var(--wf-radius-md)`。 +- 聚焦态统一为 `box-shadow: 0 0 0 3px rgba(15, 118, 110, 0.15)` 加主色实线,替代粗暴的全局黑色粗外框。 +- 错误态:边框标红,输入框下方紧跟单行 12px 错误提示与 Alert 图标,不造成表单高度突变。 + +### 3.6 空状态与加载骨架屏 (EmptyState & Skeleton) +- **空状态**:禁止单调的白板或无意义灰色图标。必须包含: + 1. 32px 扁平线条业务图标(如 `Inbox`、`FolderSearch`、`ShieldCheck`); + 2. 极简标题(如「暂无待审批发布」); + 3. 一句简明上下文; + 4. 恢复入口(主操作按钮或一键清空筛选)。 +- **骨架屏 (Skeleton)**:彻底替代粗暴的全局居中 Spinner。 + - 使用 `@keyframes wf-pulse`(0% 灰度 0.06,50% 灰度 0.15); + - 骨架严格按照目标卡片/表格的实际网格尺寸渲染占位条,彻底消除 CLS(累计布局位移)。 + +--- + +## 4. `globals.css` 拆分方案与迁移顺序 (Refactor Roadmap) + +### 4.1 拆分架构目标 +将 3580 行单体 CSS 解耦为: +1. **全局核心层 (`app/globals.css`, ~200 行)**:仅保留 CSS Reset、全局 `@theme / :root` Tokens 变量定义、全局 Typography 字体栈与通用工具类。 +2. **基础 UI 组件层 (`components/ui.module.css`, ~400 行)**:Buttons, Modals, Forms, Panels, Badges, EmptyStates, Skeletons。 +3. **领域特性层 (Feature CSS Modules)**: + - `features/copilot.module.css` (Copilot 对话流、引用卡、转 Wish 界面) + - `features/runs.module.css` (时间线、门禁网格、Diff 对比、四栏交付报告) + - `features/releases.module.css` (审批流、改动核验单、回滚确认抽屉) + - `features/cluster-resources.module.css` (总账看板、节点负载、服务列表、存储卷) + - `features/dashboard.module.css` (工作概览) + +### 4.2 渐进式迁移四阶段 (Migration Phases) + +``` +[阶段 1: 变量沉淀] -> [阶段 2: 基础 UI 抽取] -> [阶段 3: 核心 4 页迁移] -> [阶段 4: 缩容清理] +``` + +1. **阶段 1:全局 Tokens 注入 (无风险)** + - 在 `globals.css` 头部注入本规范定义的 `--wf-*` 语义变量系统,将现有的 `--teal`、`--navy` 等指向新变量作为向后兼容层。 +2. **阶段 2:公共组件模块化 (`components/ui.module.css`)** + - 提取 `button`, `panel`, `modal`, `notice`, `status`, `empty-state` 到 CSS Module。 + - `components/ui.tsx` 切换使用 CSS Module 局部类名。 +3. **阶段 3:按业务领域页面逐一解耦 (重点是四大核心页)** + - 先为新页创建独立 CSS Module(如 `cluster-resources.module.css`); + - 逐步将 `runs.tsx`、`releases.tsx`、`copilot.tsx` 页面级私有类(如 `.run-timeline`、`.diff-container`)迁移至对应的 `.module.css`。 +4. **阶段 4:老旧样式剪除与死代码清理** + - 借助 CSS 检查工具扫描 `globals.css` 中未被引用的历史类名并删除,最终将 `globals.css` 行数控制在 250 行以内。 From b11536fcfcba0219aa4c169ed63d2829e86dfc57 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 20:30:29 -0800 Subject: [PATCH 04/46] =?UTF-8?q?=F0=9F=94=92=20Add=20read-only=20cluster?= =?UTF-8?q?=20observer=20identity=20for=20Copilot=20and=20health=20checks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- infra/k8s/cluster-observer.yaml | 70 +++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 infra/k8s/cluster-observer.yaml diff --git a/infra/k8s/cluster-observer.yaml b/infra/k8s/cluster-observer.yaml new file mode 100644 index 0000000..4b4f93a --- /dev/null +++ b/infra/k8s/cluster-observer.yaml @@ -0,0 +1,70 @@ +# Read-only cluster observer for WishForge's Copilot and health checks. +# +# Purpose: let the platform read cluster state (resource accounting, service inventory, live +# alerts) without any ability to change it. The identity can list and watch workloads, events, +# persistent storage, quotas and metrics in every namespace, and read Pod logs for triage. +# +# Deliberately excluded: Secrets and ConfigMaps (they hold credentials and connection strings), +# pods/exec and pods/portforward (they are command execution paths), and every write verb. The +# only verbs granted are get, list and watch. +# +# Apply with an administrator kubeconfig: +# kubectl apply -f infra/k8s/cluster-observer.yaml +# The long-lived token lives in Secret wishforge-observer-token; deleting that Secret revokes it. +apiVersion: v1 +kind: ServiceAccount +metadata: + name: wishforge-observer + namespace: droboticflow-fanyu + labels: { app.kubernetes.io/part-of: wishforge, app.kubernetes.io/component: cluster-observer } +automountServiceAccountToken: false +--- +# Long-lived token for the read-only kubeconfig that WishForge keeps outside the repository. +apiVersion: v1 +kind: Secret +type: kubernetes.io/service-account-token +metadata: + name: wishforge-observer-token + namespace: droboticflow-fanyu + labels: { app.kubernetes.io/part-of: wishforge, app.kubernetes.io/component: cluster-observer } + annotations: { kubernetes.io/service-account.name: wishforge-observer } +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: wishforge-observer + labels: { app.kubernetes.io/part-of: wishforge, app.kubernetes.io/component: cluster-observer } +rules: + - apiGroups: [''] + resources: [nodes, namespaces, persistentvolumes] + verbs: [get, list, watch] + - apiGroups: [''] + resources: + [pods, pods/log, events, services, persistentvolumeclaims, resourcequotas, limitranges] + verbs: [get, list, watch] + - apiGroups: [apps] + resources: [deployments, statefulsets, replicasets, daemonsets] + verbs: [get, list, watch] + - apiGroups: [batch] + resources: [jobs, cronjobs] + verbs: [get, list, watch] + - apiGroups: [storage.k8s.io] + resources: [storageclasses] + verbs: [get, list, watch] + - apiGroups: [metrics.k8s.io] + resources: [nodes, pods] + verbs: [get, list, watch] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: wishforge-observer + labels: { app.kubernetes.io/part-of: wishforge, app.kubernetes.io/component: cluster-observer } +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: wishforge-observer +subjects: + - kind: ServiceAccount + name: wishforge-observer + namespace: droboticflow-fanyu From 60e911d4273dcdf77077a09c7dd9815481950895 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 20:34:29 -0800 Subject: [PATCH 05/46] =?UTF-8?q?=F0=9F=93=9D=20Document=20the=20read-only?= =?UTF-8?q?=20MongoDB=20account=20for=20Copilot=20diagnostics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ops/mongodb-readonly.md | 113 +++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/ops/mongodb-readonly.md diff --git a/docs/ops/mongodb-readonly.md b/docs/ops/mongodb-readonly.md new file mode 100644 index 0000000..0b1438d --- /dev/null +++ b/docs/ops/mongodb-readonly.md @@ -0,0 +1,113 @@ +# MongoDB 只读账号(给平台方管理员执行) + +Copilot 与运维排查需要读取线上 MongoDB 的**元数据**(集合、计数、连接数、慢操作),但绝不能改动客户数据。 +本文给出一次性创建只读账号的步骤、验证方法和凭据存放位置。**本文不含、也不应写入任何真实连接串或密码。** + +## 1. 现有部署事实(推断依据) + +| 事实 | 依据 | +| --- | --- | +| 平台使用 MongoDB,且数据库在集群外托管,不在 K8s 清单里创建 | `docs/deployment.md:150-158`“主部署路径不再创建平台 MongoDB Pod/Service,必须外部提供 URI” | +| 连接串来自命名空间内的 Secret `droboticflow-mongo-secret`,键名 `MONGO_URI` | `docs/deployment.md:159`、`k8s/droboticflow.template.yaml` 中的 `secretKeyRef` | +| 业务库名来自 ConfigMap `droboticflow-config` 的 `MONGO_DB` | `k8s/droboticflow.template.yaml:132`、`k8s/annotation-processor.template.yaml:33-35` | +| 部署脚本拒绝 `localhost`、`mongodb:27017`、`.svc` 等集群内地址,只接受具体的外部 `mongodb://` / `mongodb+srv://` | `docs/deployment.md:224` | +| 验收探针用短命 `mongo:7` Pod 读取 `MONGO_DB` 做校验,且只读、不打印 URI | `docs/operations.md:300` | +| 平台整体部署在百度云(镜像走百度云 CCR) | `docs/custom-operator-manual.zh-CN.md:176` | + +推断结论:这是一个**集群外的托管 MongoDB(部署在百度云,具体产品与主机以现有 Secret 的 host 和百度云控制台为准)**。 +核对时只看 `MONGO_DB` 与主机域名,**不要在终端、日志、聊天或提交里打印 `MONGO_URI`**。 + +同理,**不要用应用自身的 `MONGO_URI` 账号去建用户**(它大概率是读写账号),也不要在这个库上执行任何写入。 +下面所有命令都由平台方用管理员账号在 `mongosh` 里手动执行。 + +## 2. 创建只读账号(管理员执行) + +密码用你自己的强随机密码替换占位符,不要写进仓库、聊天或工单。 + +```js +// 以管理员身份连接(连接串单独从安全位置读取,勿粘贴到共享终端记录里) +// mongosh "<管理员连接串>" + +use admin +db.auth("<管理员账号>", "<管理员密码>") + +// 业务库名以 ConfigMap 为准:kubectl -n <命名空间> get cm droboticflow-config -o jsonpath='{.data.MONGO_DB}' +use <业务库名> + +db.createUser({ + user: "wishforge_observer", + pwd: "<强随机密码,占位符>", + roles: [ + { role: "read", db: "<业务库名>" }, // 只读业务库 + { role: "clusterMonitor", db: "admin" } // 连接数、慢操作、副本集状态 + ] +}) +``` + +说明: + +- 只给 `read`,**不要**给 `readWrite`、`dbAdmin`、`dbOwner`、`userAdminAnyDatabase`、`root`。 +- `clusterMonitor` 是内置只读角色,可看 `serverStatus`(连接数)、`currentOp`(慢操作)、`replSetGetStatus`,不含集合数据写权限。 +- 账号建在业务库上,因此连接时 `authSource` 必须是业务库名,而不是 `admin`。 +- 慢查询若要看 `system.profile`,需要 `dbAdmin` 才能开 profiling 并读该集合;默认**不授予**,慢操作排查用 `currentOp` 采样即可。 + +## 3. 验证账号确实不能写(只读账号执行) + +用新账号连一次(`readPreference=primary`,`authSource=<业务库名>`),逐条确认: + +```js +use <业务库名> + +db.runCommand({ connectionStatus: 1 }) +// 期望:authenticatedUsers 只有 wishforge_observer; +// authenticatedUserRoles 只有 <业务库名>.read 与 admin.clusterMonitor + +db.getCollectionNames() // 期望:正常返回集合名 +db.getCollection("<任一集合>").findOne() // 期望:正常返回一条文档(只读可读) + +db.getCollection("<任一集合>").insertOne({ _id: "readonly_probe" }) +// 期望:MongoServerError: not authorized on <业务库名> to execute command { insert: ... } + +db.getCollection("<任一集合>").updateOne({ _id: "<任一存在的 id>" }, { $set: { readonly_probe: 1 } }) +// 期望:not authorized ... update + +db.getCollection("<任一集合>").deleteOne({ _id: "<任一存在的 id>" }) +// 期望:not authorized ... delete + +db.createCollection("readonly_probe") +// 期望:not authorized ... create + +// 只读可观测能力(clusterMonitor) +db.runCommand({ serverStatus: 1 }).connections // 期望:返回连接数 +db.currentOp({ active: true, secs_running: { $gt: 5 } }) // 期望:返回慢操作列表 +db.adminCommand({ replSetGetStatus: 1 }) // 期望:副本集状态(单机部署会报 not supported) +``` + +四条写入命令(insert / update / delete / create)必须全部报 `not authorized`;任何一条成功,说明角色给多了,立即 `db.updateUser` 收回。 + +## 4. 凭据存放位置 + +- 只读连接串存 `local-data/mongodb-readonly.env`(`chmod 600`),字段形如 + `MONGO_READONLY_URI=<占位符>`、`MONGO_READONLY_DB=<业务库名>`。 +- `local-data/` 不进仓库。本仓库 `.gitignore` 目前**没有** `local-data/` 规则, + 需在 `.gitignore` 增补(或至少写进 `.git/info/exclude`),并在提交前用 + `git check-ignore -v local-data/mongodb-readonly.env` 确认。 +- 不要把它写进 K8s Secret 之外的任何清单;需要给 Copilot 用时,由平台侧注入环境变量。 +- 不要把该账号写进 `.scratch/` 笔记、验收日志或聊天记录。 + +## 5. 吊销与轮换 + +```js +use <业务库名> +db.dropUser("wishforge_observer") // 吊销 +// 或仅轮换密码: +db.updateUser("wishforge_observer", { pwd: "<新密码,占位符>" }) +``` + +轮换后同步更新 `local-data/mongodb-readonly.env`,并确认 Copilot 侧重新读取配置。 + +## 6. 禁止事项 + +- 不用应用自身的读写账号建用户或测试权限。 +- 不对业务库执行任何写入、建集合、建索引、profiling 开关操作(验证步骤里的写入命令**只允许失败**)。 +- 不打印、不记录、不提交连接串;报告里只写“已创建/已验证”,不写主机、账号、密码。 From 17629ac812204d3cd0a86d947bbda61a0a97aa16 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 21:08:29 -0800 Subject: [PATCH 06/46] =?UTF-8?q?=F0=9F=93=9D=20docs(product):=20add=20ris?= =?UTF-8?q?k=20levels,=20gate=20rules=20v1,=20cluster=20resource=20draft,?= =?UTF-8?q?=20and=20delivery=20report=20copy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/product/copy/delivery-report.md | 92 ++++++++++ docs/product/drafts/cluster-resources.md | 212 +++++++++++++++++++++++ docs/product/risk-levels.md | 106 ++++++++++++ wiki/features/gates.md | 176 +++++++++++++++++++ 4 files changed, 586 insertions(+) create mode 100644 docs/product/copy/delivery-report.md create mode 100644 docs/product/drafts/cluster-resources.md create mode 100644 docs/product/risk-levels.md create mode 100644 wiki/features/gates.md diff --git a/docs/product/copy/delivery-report.md b/docs/product/copy/delivery-report.md new file mode 100644 index 0000000..15fb4fc --- /dev/null +++ b/docs/product/copy/delivery-report.md @@ -0,0 +1,92 @@ +# 交付报告模板与系统提示文案(Delivery Report & UI Copy) + +本文档定义面向客户的 G9 四栏交付报告模板,以及门禁拦截、等待审批、发布回滚、Copilot 答「不确定」、集群资源告警五类核心场景的标准提示文案。 + +> **文案准则**(遵循 `copy-guidelines.md` 与 `error-messages.md`): +> 1. **最简直白**:一句话说清「当前状态 + 原因 + 下一步能做什么」。 +> 2. **零内部黑话**:严禁向客户展示接口路径、`APIError`、堆栈、Commit Hash、Pod/PVC/OOM/maxTimeMS/known-failures 等底层工程术语。 +> 3. **区分「确认失败」与「结果未知」**:网络或服务超时统一使用「暂时无法确认操作结果」,不误报为操作失败。 + +--- + +## 一、交付报告四栏客户版模板(G9) + +每次修改完成后、客户点击「批准发布」前,卡片仅展示以下简明摘要与四栏核对表: + +```markdown +### 本次修改交付报告 + +**修改内容**:{用一句话描述客户能感知的变化,例:将审核池列表默认排序改为按更新时间倒序} +**风险等级**:{低风险 / 中风险 / 高风险}({谁批准,例:您确认无误后可直接发布 / 需平台技术团队审核后发布}) +**已检查角色与状态**:{例:标注员、质检员、管理员 | 正常加载、空列表、无权限只读、报错提示} + +| ✅ 通过 | ❌ 失败 | 👀 待验证(需您确认) | ⏸️ 没做(本次未改) | +| :--- | :--- | :--- | :--- | +| • 页面编译与显示检查通过
• 审核池筛选与翻页功能测试通过
• 原有其它页面功能未受影响 | 无
*(注:只要此栏有内容,『批准发布』按钮自动禁用)* | • 请您在预览页看一眼新的排序顺序是否符合预期 | • 未修改历史已审核数据的导出格式(不在本次需求范围内) | +``` + +### 四栏填写规范(供生成器与前端遵循) +- **通过(Passed)**:用业务语言列出实际跑通的检查项(如「登录与权限检查通过」「任务领取与保存测试通过」),附上可点击查看的预览截图,不贴命令行输出。 +- **失败(Failed)**:无失败时固定写「无」;有失败时直接写明哪项业务动作没走通(如「点击保存草稿时报错」),此时严禁开放发布按钮。 +- **待验证(To Verify)**:列出自动测试无法代替人工审美或业务判断的事项(如「新文案读起来是否顺口」「新颜色是否醒目」),无则写「无」。 +- **没做(Out of Scope)**:明确写出客户对话中提到但本次刻意未改动的部分,防止客户误以为已包含;无则写「无」。 + +--- + +## 二、五类核心场景极简提示文案 + +### 1. 门禁拦下(Gate Blocked) + +| 细分场景 | 标题 / 状态标签 | 提示正文 | 按钮文案 | +| :--- | :--- | :--- | :--- | +| **验证未通过(S3/G2)** | 检查未通过,暂不可发布 | 还有 {N} 项自动检查未通过,直接发布可能会影响页面正常使用。 | `让 Copilot 继续修复` / `转交技术支持` | +| **触碰删改数据(S2)** | 已拦截:涉及数据删改 | 本次修改包含批量修改或删除数据的操作。为防止数据丢失,不能自助发布,已转交平台技术团队为您核对处理。 | `查看详情` | +| **触碰权限/核心配置(S1)** | 已拦截:涉及安全与配置 | 本次修改涉及【账号权限 / 系统配置】,为保障平台稳定运行,需由平台技术团队审核后发布。 | `提交技术团队审核` | +| **基线过时冲突(G1)** | 正在同步最新线上版本 | 线上刚刚有其他更新发布。为防止冲掉最新功能,系统正在基于最新版本重新核对您的修改,请稍候。 | `刷新状态` | +| **测试标准被改动(G3)** | 已拦截:检查标准异常 | 检测到自动测试的放行标准被改动,系统已停止发布并通知平台技术团队核查。 | `联系技术支持` | +| **3 次自动修复未果(S5)** | 自动修复已暂停 | Copilot 已连续尝试修复 3 次仍未彻底解决。为避免无效等待,请补充更具体的修改说明,或直接交由技术团队处理。 | `补充说明` / `转交技术团队` | + +--- + +### 2. 等待审批(Waiting for Approval) + +| 细分场景 | 标题 / 状态标签 | 提示正文 | 按钮文案 | +| :--- | :--- | :--- | :--- | +| **低/中风险(待客户负责人批)** | 等待批准发布 | 本次修改为【{低/中}风险】,所有自动检查已通过。请核对交付报告后确认是否上线。 | `批准并发布` / `再改改` | +| **高风险(待平台方批)** | 等待平台技术团队审核 | 本次修改为【高风险】,已提交平台技术团队做安全复核,审核通过后将第一时间通知您。 | `查看交付报告` / `撤回申请` | +| **待发布的检查结果发生变动** | 请重新确认后再发布 | 修改内容刚刚发生了更新,请查看最新的检查报告后再点击发布。 | `查看最新报告` | +| **审批请求网络超时** | 暂时无法确认操作结果 | 网络连接超时,暂时无法确认审批状态是否已更新,请刷新页面查看最新进度。 | `刷新页面` | + +--- + +### 3. 发布回滚(Release Rollback) + +| 细分场景 | 标题 / 状态标签 | 提示正文 | 按钮文案 | +| :--- | :--- | :--- | :--- | +| **客户手动点击回滚(二次确认弹窗)** | 确认恢复到上一版本? | 恢复后,本次修改的内容将下线,系统会回到修改前的稳定状态,您已有的数据不会丢失。 | `确认恢复` / `取消` | +| **客户手动回滚成功** | 已恢复到上一版本 | 系统已恢复到修改前的稳定版本,线上功能和数据均正常。 | `知道了` | +| **健康检查失败触发自动回滚(S4)** | 已自动恢复至稳定版本 | 新版本启动检查未通过,系统已自动帮您恢复到修改前的稳定版本,线上业务和您的数据未受影响。 | `查看原因` / `重新修改` | +| **回滚过程出现异常(需人工介入)** | 正在由技术团队人工恢复 | 版本恢复过程中遇到异常,已自动通知平台技术团队紧急处理,请稍候。 | `刷新状态` | + +--- + +### 4. Copilot 答「不确定」(Copilot Uncertainty & Escalation) + +| 细分场景 | 提示正文(Copilot 气泡文案) | 快捷操作按钮 | +| :--- | :--- | :--- | +| **定位不到把握的文件/原因** | 我暂时没法 100% 确定这个问题对应的具体位置。为了避免改错影响其他功能,建议您补充一下「在哪个页面、点了哪个按钮出现的问题」,或者直接转交技术团队排查。 | `补充页面和按钮信息` / `转交技术团队` | +| **拿不准风险等级(默认升档告知)** | 这次修改除了您提到的位置,还牵涉到关联的【{判断逻辑 / 权限检查}】。为了稳妥起见,系统已按更高安全等级(【{中/高}风险】)为您补充了安全检查。 | `查看检查报告` | +| **客户要求直接改/删线上数据库** | 为了保护您的数据安全,我只有线上记录的「只读查看」权限,无法直接帮您修改或删除数据库里的数据。如果您需要某个页面支持修改功能,我可以帮您调整页面功能。 | `改为调整页面功能` / `联系技术团队处理数据` | +| **只读日志/监控暂时查不到线索** | 我查看了最近的运行日志,暂时没有找到对应的报错记录。如果您刚刚遇到操作报错,请把页面上的提示语发给我,我继续帮您排查。 | `发送报错提示` | + +--- + +### 5. 集群资源告警(Resource Alerts) + +| 细分场景 | 告警级别 | 标题 / 状态标签 | 提示正文 | 按钮文案 | +| :--- | :--- | :--- | :--- | :--- | +| **服务计算资源忙碌(水位 ≥ 80%)** | 提醒(黄) | 当前任务较多,处理可能变慢 | 当前同时执行【{视频校验 / 切片生成 / 批量导出}】的任务较多,页面响应或后台处理可能需要多等几分钟,无需重复点击提交。 | `查看资源状态` | +| **校验排队导致暂无可领任务** | 提醒(蓝) | 新数据正在后台校验中 | 新导入的视频正在后台排队做准入检查,检查完成后会自动进入可领取列表,请稍候再试。 | `刷新可领数量` | +| **工作区存储空间预警(200Gi 达 85%)** | 告警(橙) | 临时存储空间即将用满 | 系统工作区剩余空间不足 15%,大批量导出或大视频切片可能会失败。系统已通知平台运维清理过期临时文件。 | `知道了` | +| **GPU 算子已被占满(2/2 卡占用)** | 拦截(红) | AI 预标显卡资源已被占用 | 当前服务器的 2 张 AI 加速卡正在运行其他预标任务。新发起的【{头部姿态 / 手部姿态}】自动预标将排队等待,或请联系平台团队协调。 | `排队等待` / `查看运行中任务` | +| **修改配额超出服务器余量(S5)** | 拦截(红) | 服务器剩余空间不足 | 本次调整所需的资源超过了当前服务器的安全余量,强行开启会导致线上页面卡顿或中断,已转交平台技术团队统筹调配。 | `提交技术团队调配` | diff --git a/docs/product/drafts/cluster-resources.md b/docs/product/drafts/cluster-resources.md new file mode 100644 index 0000000..635509a --- /dev/null +++ b/docs/product/drafts/cluster-resources.md @@ -0,0 +1,212 @@ +# droboticflow 集群资源与服务说明草稿(Cluster Resources & Services) + +> **说明**:本文档目前存放于 WishForge 仓库 `docs/product/drafts/cluster-resources.md`,作为资源监控页(R1–R3)与客户 Copilot 诊断问答的权威底座,后续核对无误后迁入 droboticflow 仓库 `wiki/modules/cluster-resources.md`。 + +--- + +## 一、集群硬件、存储与外部依赖总览 + +### 1. 节点总账(共 3 台节点) +| 节点 IP | CPU | 内存 | GPU | 主要承担角色 | 出处 | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `10.189.16.33` | 56 核 | 220 Gi | 2 卡 GPU | 主计算与高并发节点(`annotation-validator` 设 `preferred` 亲和权重 100;GPU 算子承载节点) | 集群实况 & `local-data/worktrees/worktree-salvage/k8s/fanyu-validator-scale.patch.yaml` | +| `10.189.16.4` | 8 核 | 31 Gi | 0 | 通用工作节点(分担 API / Worker / Coordinator 等常驻负载) | 集群实况 | +| `10.189.16.5` | 8 核 | 31 Gi | 0 | 通用工作节点(分担 API / Worker / Coordinator 等常驻负载) | 集群实况 | +| **合计** | **72 核** | **282 Gi** | **2 卡 GPU** | 命名空间:`droboticflow-fanyu`(100人源引用切片容量预算 54 CPU / 120 GB,常驻请求约 31.3 CPU / 29.5 GiB,常驻上限 48 CPU / 76 GiB) | `local-data/worktrees/worktree-salvage/docs/capacity/source-index-100.md` & `source-index-100.json` | + +### 2. 存储与数据库现状 +| 资源名称 | 类型 / 位置 | 容量与限制 | 用途说明 | 出处 | +| :--- | :--- | :--- | :--- | :--- | +| `workspace` | PVC(`csi-bos`) | **200 Gi(不支持在线扩容)** | 工作区共享文件与切片产物暂存,一旦写满将导致切片/导出/上传任务直接报错失败 | 集群实况 & `k8s/droboticflow.template.yaml` | +| `qwen-node-cache` | 节点本地盘 Local PV(RWO) | **80 Gi**(`stale_staging=86400s`) | 仅对内置算子 `operator-builtin-qwen-behavior-rough-cut` 生效的节点本地模型与缓存盘,通过 `flock` 与 `CACHE_RECEIPT.json` 校验,异常时回退至 Pod 本地临时目录 | `docs/qwen-node-local-cache.md`、`k8s/qwen-node-cache.*.template.yaml` | +| **MongoDB** | **集群外独立部署** | 外部实例(不占 K8s 节点 CPU/内存) | 存储所有项目、任务、标注草稿、版本、压缩时间轴索引(`annotationTimelineIndexes`)及同步状态;各服务启用 `DROBOTICFLOW_PROJECT_WRITE_LOCK_MODE=striped` 与 `DROBOTICFLOW_DATABASE_BOOTSTRAP=verify-existing` | 集群实况、`docs/annotation-processing.md`、`local-data/worktrees/worktree-salvage/docs/capacity/source-index-100.md` | + +--- + +## 二、`droboticflow-fanyu` 命名空间服务逐项说明 + +### 1. `api`(当前副本数:4) +- **当前资源配置**:4 副本 ×(requests `1 CPU / 2 GiB`,limits `2 CPU / 4 GiB`);启用分区项目写锁 `DROBOTICFLOW_PROJECT_WRITE_LOCK_MODE=striped`。 +- **用途**:对外提供 Web 前端页面与全量 HTTP REST API,处理登录鉴权、项目与字典管理、任务随机领取、标注工作台读写、审核池搜索、看板统计及发布健康检查(`/api/health`)。 +- **对应客户功能**: + - 打开网页、登录系统、查看个人与项目看板; + - 标注员/质检员/验收员点击「领取任务」、打开视频标注工作台、保存草稿与提交版本; + - 审核池筛选搜索、切片字典维护、导出与算子任务下发。 +- **依赖**: + - **MongoDB(集群外)**:核心业务数据读写; + - **BOS 对象存储 / `workspace` PVC**:读取视频源、预览图与导出产物; + - **下游异步服务**:将耗时修订与源数据校验任务交由 `annotation-processor` 与 `annotation-validator` 异步处理。 +- **资源吃紧时的典型症状**: + - **CPU 跑满或连接池打满**:所有页面打开变慢、保存标注草稿转圈(p95 延迟从 ~350ms 飙升至数秒)、审核池搜索或领取任务报超时(`暂时无法确认操作结果`); + - **内存触顶(OOMKilled)**:单个大批量查询或导出请求导致 Pod 重启,正在操作的客户短暂遇到连接中断。 +- **常见扩容方向**: + - 高并发访问或领取/查询高峰优先 **加副本**(如 4 → 6)或 **加单副本 CPU/内存**(高容量模板 `k8s/fanyu-high-capacity.resources.yaml` 支持提升至 `8C / 16G`); + - 若因慢查询堆积导致卡顿,加副本无效,需检查查询是否缺失游标分页或 `maxTimeMS`(参考审核池与看板超时修复)。 +- **出处**: + - `k8s/droboticflow.template.yaml` + - `k8s/fanyu-high-capacity.resources.yaml` + - `local-data/worktrees/worktree-salvage/docs/capacity/source-index-100.md` + - `local-data/worktrees/worktree-salvage/docs/verification/claim-dashboard-timeout-20261103.md` + - `local-data/worktrees/worktree-salvage/docs/verification/review-pool-search.md` + +--- + +### 2. `annotation-validator`(当前副本数:4) +- **当前资源配置**:4 副本 ×(requests `6 CPU / 4 GiB`,limits `8 CPU / 8 GiB`),合计请求 24 CPU / 16 GiB、上限 32 CPU / 32 GiB;环境变量 `ANNOTATION_PROCESSOR_ROLE=validation`,每副本并发 `ANNOTATION_INDEX_CONCURRENCY=4`(共 16 个并发校验槽位);配置 `preferred` 节点亲和优先调度至大节点 `10.189.16.33`。 +- **用途**:专职负责源视频/源数据的准入校验与帧时间轴索引(`annotationTimelineIndexes`)构建,确保源数据帧率、时间轴与切片完整性合格后才允许进入待领取池。 +- **对应客户功能**: + - 新导入批次/源视频后的「源数据准入检查」; + - 决定任务能否出现在标注员的「可领取」列表(校验中或校验失败的任务不计入可领取数量 `claim-count`,已领取任务遇源异常会在工作台提示并自动跳过)。 +- **依赖**: + - **MongoDB(集群外)**:读写源校验状态(`sourceValidationStatus`)与压缩时间轴索引集合 `annotationTimelineIndexes`; + - **BOS 对象存储 / `workspace` PVC**:拉取并解码校验源视频文件。 +- **资源吃紧时的典型症状**: + - **CPU 跑满 / 16 个并发槽位排满**:新导入的数据长时间停留在「等待校验 / 校验中」状态,**标注员点击领取时提示「没有可领取的任务」(看似没活干,实则是校验队列积压未放行)**; + - **内存吃紧**:超长或高码率视频解码校验时触发 OOM 重启,任务租约(2 分钟租约、10 秒续期)中断并触发重试(最多 3 次)。 +- **常见扩容方向**: + - **加核(CPU)与加副本并重**:因其是计算密集型服务,优先在大节点 `10.189.16.33` 余量内 **加核** 或微调单副本并发槽位 `ANNOTATION_INDEX_CONCURRENCY`; + - 注意:当前 4 副本已请求 24 核(上限 32 核),继续加副本前必须先核对 `10.189.16.33`(56 核)的剩余可分配核数,防止挤占同节点其他服务。 +- **出处**: + - `local-data/worktrees/worktree-salvage/docs/capacity/validator-scale-20261026.md` + - `local-data/worktrees/worktree-salvage/k8s/fanyu-validator-scale.patch.yaml` + - `local-data/worktrees/worktree-salvage/k8s/fanyu-validator-scale.rollback.patch.yaml` + - `local-data/worktrees/worktree-salvage/docs/verification/source-validation-admission.md` + - `docs/annotation-processing.md` + +--- + +### 3. `annotation-processor`(当前副本数:2) +- **当前资源配置**:2 副本 ×(requests `1 CPU / 2 GiB`,limits `2 CPU / 4 GiB`);环境变量 `ANNOTATION_PROCESSOR_ROLE=revision`,每副本并发 `ANNOTATION_PROCESSOR_CONCURRENCY=8`(共 16 个并发处理槽位)。 +- **用途**:专职负责持久化标注版本(Revision)的异步后台处理,包括标注提交后的切片生成、纯元数据修改的 BOS 服务端快速拷贝、新切片视频解码(最多 8 路共享解码、4 路并发 BOS 传输)以及最终 `manifest` 发布。 +- **对应客户功能**: + - 标注员/质检员提交标注结果后的后台「生成切片 / 版本落盘」; + - 修改标注标签或属性后的版本更新与回放文件生成。 +- **依赖**: + - **MongoDB(集群外)**:读取标注草稿/版本记录,维护 2 分钟处理租约(每 10 秒续期); + - **BOS 对象存储 & `workspace` PVC**:执行 BOS 服务端拷贝、读写临时解码切片文件并最终上传发布 `manifest`。 +- **资源吃紧时的典型症状**: + - **CPU / 内存吃紧**:客户在前端点击「提交」后,任务长时间处于「处理中」,回放切片或下游导出迟迟看不到最新结果; + - **`workspace` PVC 空间不足或 BOS 带宽打满**:新切片落盘失败、任务反复重试 3 次后转入失败状态。 +- **常见扩容方向**: + - 提交高峰期若纯元数据修改多、排队明显,优先 **加副本**(2 → 4); + - 若新增大量需要重编码的视频切片导致单机吃紧,优先 **加核 + 加内存**,并严密监控 `workspace`(200Gi 不可扩容)剩余空间。 +- **出处**: + - `k8s/annotation-processor.template.yaml` + - `docs/annotation-processing.md` + - `local-data/worktrees/worktree-salvage/docs/capacity/source-index-100.md` + +--- + +### 4. `worker`(当前副本数:2) +- **当前资源配置**:2 副本 ×(requests `250m CPU / 512 MiB`,limits `1 CPU / 8 GiB`);高容量模板 `k8s/fanyu-high-capacity.resources.yaml` 下可配置至 `4C / 8G`。 +- **用途**:通用后台任务与工作流(Workflow / 算子编排)执行器,负责调度非标注修订类的异步作业、数据导入导出、批处理脚本及算子流水线串联(如 `real-source` → 算子推理 → `upload`)。 +- **对应客户功能**: + - 批量数据导入、数据集打包与旧媒体导出; + - 自动预标注/算子工作流任务的排队、分发与结果回传。 +- **依赖**: + - **MongoDB(集群外)**:拉取异步作业队列与回写执行状态; + - **BOS 对象存储 & `workspace` PVC**:暂存导入导出压缩包与算子中间产物; + - **算子服务 / 本地缓存**:调用 `headpose`、`wilor` 或挂载 `qwen-node-cache`(当调度 `operator-builtin-qwen-behavior-rough-cut` 时)。 +- **资源吃紧时的典型症状**: + - **内存打满(8GiB 触顶)**:大批量导出或大视频打包时发生 OOM,导出任务中断报错; + - **CPU 偏小(默认上限 1 核)**:多任务并发打包/转换时进度条推进极慢,后台任务队列积压; + - **`workspace` 200Gi 写满**:导出或算子流水线因临时文件无法写入而全部报错停止。 +- **常见扩容方向**: + - 遇到大文件导出/视频处理慢时,优先 **加核(CPU 1C → 4C)**; + - 遇到多批任务排队时 **加副本**;若 `workspace` 存储逼近水位,不能靠扩容 PVC(`csi-bos` 不支持扩容),必须清理过期临时产物。 +- **出处**: + - `k8s/droboticflow.template.yaml` + - `k8s/fanyu-high-capacity.resources.yaml` + - `local-data/worktrees/worktree-salvage/docs/capacity/source-index-100.md` + - `docs/qwen-node-local-cache.md` + +--- + +### 5. `drosync-coordinator`(当前副本数:2) +- **当前资源配置**:2 副本 ×(requests `200m CPU / 256 MiB`,limits `1 CPU / 2 GiB`);通过 `DROBOTICFLOW_OBJECT_SYNC_ENABLED` 与 `drosync-signing-secret` 启用。 +- **用途**:跨环境/对象存储数据同步协调器(DroSync),负责协调元数据与 BOS 对象文件的增量同步、签名校验、同步任务编排与过期清理(Mongo TTL 90天/1年,设计恢复点目标 RPO 15 分钟)。 +- **对应客户功能**: + - 外部数据源同步入库、跨存储桶/跨环境资产同步、同步状态巡检(客户日常界面较少直接点击,但决定新批次外部数据能否按时同步到位)。 +- **依赖**: + - **MongoDB(集群外)**:记录同步游标、状态与 TTL 审计记录; + - **BOS 对象存储 & `drosync-signing-secret`**:对象校验与传输协调。 +- **资源吃紧时的典型症状**: + - **CPU / 内存吃紧或异常重启**:新批次外部视频/资产同步延迟超过 15 分钟,上游已上传的数据在平台里搜不到; + - 发布更新时若未先更新 Coordinator 即更新 API/Worker,可能出现短暂的同步契约不一致(因此发布规范要求按 Coordinator → Worker/Processor → API 顺序滚动)。 +- **常见扩容方向**: + - 平时开销极低(200m/256Mi);若遇海量历史对象集中同步导致内存上涨,优先 **加内存(2GiB → 4GiB)**,一般无需超过 2 个副本。 +- **出处**: + - `k8s/droboticflow.template.yaml` + - `docs/drosync/operations-runbook.md` + - `local-data/worktrees/worktree-salvage/docs/capacity/source-index-100.md` + - `docs/reference/poc-delivery-profile.md`(WishForge 侧滚动顺序参考) + +--- + +### 6. `headpose`(当前副本数:0,按需启用时占 1 GPU) +- **当前资源配置**:当前副本为 `0`(冷备);启动时单副本需独占 **1 张 NVIDIA GPU**(端口 `8080`,高容量 profile `fanyu-high-capacity-v1` 下可配 `16C / 64G / 1 GPU`)。 +- **用途**:内置 6DRepNet 头部姿态估计 AI 算子服务(`operator-builtin-head-pose` / `builtin_head_pose`),对视频中的人物头部三维朝向进行自动预标注并生成带渲染结果。 +- **对应客户功能**: + - 客户在工作流中发起「6DRepNet 头部姿态自动预标(带渲染)」任务。 +- **依赖**: + - **GPU 硬件**:必须调度在具备空闲 GPU 的节点 `10.189.16.33`(`device=cuda`); + - **BOS / `workspace` PVC**:读取源视频并输出姿态预标与渲染文件; + - **调用方**:由 `worker` / 算子工作流调度调用。 +- **资源吃紧时的典型症状**: + - **副本为 0 时直接调用**:头部姿态预标任务一直停留在排队/等待算子就绪状态; + - **GPU 被占满(节点共 2 张 GPU)**:若其他 GPU 任务已占满 2 张卡,Pod 处于 `Pending`(`Insufficient nvidia.com/gpu`)无法启动; + - **显存/内存不足**:高分辨率长视频渲染时推理中断报错。 +- **常见扩容方向**: + - 需要跑头部姿态预标时,由平台方将副本从 **0 扩到 1**; + - 受限于全集群仅 `10.189.16.33` 有 **2 张 GPU**(且需与 `wilor` 或其他 GPU 算子共享这 2 张卡),**严禁盲目把副本扩到 2 以上**,否则必然因无 GPU 可用而卡死。 +- **出处**: + - `k8s/droboticflow.template.yaml` + - `k8s/fanyu-high-capacity.resources.yaml` + - `docs/fanyu-resource-profile.md` + - `docs/operators/6DRepNet-HeadPose-预标-带渲染.md` + +--- + +### 7. `wilor`(当前副本数:0,按需启用时占 1 GPU) +- **当前资源配置**:当前副本为 `0`(冷备);启动时单副本需独占 **1 张 NVIDIA GPU**(高容量 profile `fanyu-high-capacity-v1` 下可配 `16C / 64G / 1 GPU`;分块参数 `VIDEO_CHUNK_FRAMES=119 < MAX_FRAMES=120` 保障全视频无截断覆盖)。 +- **用途**:内置 WiLoR 3D 手部姿态估计 AI 算子服务(`operator-builtin-wilor-hand-pose` / `builtin_wilor_hand_pose`),自动检测视频中的人手(`detectedHands >= 1`)并输出 `wilor-result.json` 等四类 3D 手部关键点预标产物。 +- **对应客户功能**: + - 客户在工作流中发起「WiLoR 3D 手部姿态自动预标」任务。 +- **依赖**: + - **GPU 硬件**:必须调度在节点 `10.189.16.33`(`device=cuda`,占用 1 张 GPU); + - **BOS / `workspace` PVC**:通过 `operator-builtin-real-source` 拉取视频,推理完成后由 `operator-builtin-upload` 上传四类产物。 +- **资源吃紧时的典型症状**: + - **副本为 0 时**:手部姿态预标任务无法执行; + - **GPU 争用**:当 `headpose` 与 `wilor` 同时各开 1 副本时,2 张 GPU 刚好 100% 占满,任何第 3 个 GPU 实例或滚动重启时的临时新 Pod 都会因无卡可用而 `Pending`; + - **分块/存储压力**:长视频连续分块推理时占用较多 CPU/内存与 `workspace` 临时空间。 +- **常见扩容方向**: + - 按需将副本从 **0 扩到 1**; + - **不能在当前 2 GPU 集群上盲目加副本**;若需同时跑多个 GPU 算子,必须先核对 `10.189.16.33` 的 2 张 GPU 占用情况,错峰启停或向平台方申请新增 GPU 节点。 +- **出处**: + - `docs/operators/WiLoR-3D-HandPose-自动.md` + - `scripts/wilor-operator-workflow-acceptance.sh` + - `docs/fanyu-resource-profile.md` + - `k8s/fanyu-high-capacity.resources.yaml` + - *待确认项*:`droboticflow-fanyu` 命名空间下 `wilor` 线上 Deployment 的独立 YAML 文件路径(`k8s/droboticflow.template.yaml` 已内含 `headpose`,`wilor` 在线 Deployment 声明位置**待确认**)。 + +--- + +## 三、通俗解释:什么是 Requests、Limits 和「超卖」? +> *以下段落采用大白话编写,供 WishForge 资源监控页(R1–R3)说明气泡与客户 Copilot 直接引用。* + +可以把我们的服务器集群想象成一栋**共享办公大楼**,里面的每个服务(比如网页服务 `api`、视频校验服务 `validator`)都是入驻大楼的**团队**: + +1. **保底工位(Requests / 资源请求)**: + - 就是每个团队入驻时**必须保证时刻留给它的专属工位**。 + - 比如某个服务设置了「保底 6 核 CPU」,哪怕它现在没活干闲着,大楼管理员也会把这 6 核给它留好,绝对不会把超过大楼总工位数的保底名额租出去。如果所有服务的「保底工位」加起来超过了服务器的实际大小,新服务就进不去(排不上号)。 + +2. **最大借用上限(Limits / 资源上限)**: + - 就是某个团队突然来了一大批急活时,**最多允许它临时借用到多少工位**。 + - 比如「保底 6 核、上限 8 核」,平时用 6 核,忙的时候只要大楼里还有人没坐满,它可以临时借用到 8 核;但最多只能用到 8 核,防止它把整栋楼的资源全抢光。 + - **注意内存和 CPU 的区别**:CPU 触碰到上限最多只是「干活变慢、排队等一等」;但**内存(Memory)一旦超过上限,系统为了保护整台服务器不死机,会当场把这个服务强制重启(也就是常说的 OOM)**。 + +3. **什么是「超卖(Overcommit)」?为什么会有风险?**: + - 因为大家不会每分每秒都同时忙到极点,所以所有服务的**「保底工位(Requests)」加起来虽然没超过服务器总量,但所有服务的「最大上限(Limits)」加起来往往会超过服务器的真实物理大小**——这就叫**「超卖」**。 + - **平时的好处**:大家错峰使用,不用买太多闲置服务器,省钱又高效。 + - **什么时候会出事?**:如果赶上业务高峰(比如几十个人同时上传大视频做校验、同时批量导出、同时跑 AI 算子),好几个服务**在同一秒钟都想借用到自己的「最大上限」**,大楼里的真实工位瞬间不够分了!这时候就会出现**全员卡顿、任务超时,甚至内存不够用导致部分服务被强制重启**。 + - **我们的保护措施**:所以系统会实时盯着每台服务器的「已承诺保底量」和「真实剩余空间」。当您或 Copilot 想要调大某个服务、或者开启 GPU 算子时,如果超过了服务器的安全余量,门禁就会及时拦住并交由平台团队统筹,确保线上业务稳稳当当。 diff --git a/docs/product/risk-levels.md b/docs/product/risk-levels.md new file mode 100644 index 0000000..443b0a0 --- /dev/null +++ b/docs/product/risk-levels.md @@ -0,0 +1,106 @@ +# 风险分级规则(Risk Levels) + +本文档定义 WishForge 面向客户场景的改动风险分级标准、工程判定信号、审批流转与发布后回滚策略。所有规则的目标是**避免平台崩溃与客户数据丢失,同时让小修改快速、准确地上线**。 + +--- + +## 一、三级风险定义与典型示例 + +### 1. 低风险(Low Risk) +**定义**:仅涉及界面展示层文案、样式微调或静态说明,不改变接口协议、不修改业务逻辑分支、不触碰数据库与部署配置。即使存在瑕疵,也仅影响单处视觉展示,不会阻断业务操作或污染数据。 + +**客户能看懂的例子**: +1. **改按钮文案**(例如:把「提交审核」改成「完成并送审」)。 +2. **调表格列宽或标签颜色**(例如:把「已超时」标签从灰色改成红色,调整列表筛选项间距)。 +3. **改空状态或报错提示语**(例如:把「暂无数据」改成「当前没有可领取的任务」)。 +4. **调整只读展示字段顺序**(例如:任务详情卡片里把「创建时间」挪到「创建人」下方)。 +5. **更新项目 Wiki 或内置帮助文档**。 + +--- + +### 2. 中风险(Medium Risk) +**定义**:涉及前端交互逻辑、状态流转或经限定范围的常规业务接口修改,但不涉及数据结构变更、历史数据批量改写、权限扩大、认证机制调整或基础设施改动。若出现问题,可能影响单个页面的操作体验或单个功能的局部流程,但不会造成全站不可用或数据损毁。 + +**客户能看懂的例子**: +1. **增加列表筛选条件或排序方式**(例如:在审核池增加按「批次号」筛选或按「更新时间」排序)。 +2. **修改表单前端校验规则**(例如:新建字典时限制名称不超过 30 个字符,必填项未填时高亮提示)。 +3. **调整单个业务按钮的二次确认弹窗逻辑**(例如:点击「驳回」时必须填写驳回原因才能提交)。 +4. **修复特定页面的查询超时或列表卡顿**(仅优化只读查询条件或前端分页加载,不改动底层写入逻辑)。 +5. **在现有接口返回中增加一个已有字段用于前端展示**(不改表结构、不改写库逻辑)。 + +--- + +### 3. 高风险(High Risk) +**定义**:任何可能引发平台级故障、数据丢失或错乱、越权访问、验证失真或集群资源枯竭的修改。包括但不限于:**数据库迁移、删除或批量修改数据、权限和认证、部署配置、测试基线和验证配置、副本缩到 0、资源请求超过节点余量**。 + +**客户能看懂的例子**: +1. **删除或批量修改历史数据**(例如:「把上个月所有驳回的任务全部删掉」或「批量把 1000 条旧数据的状态改成已完成」)。 +2. **修改谁能看、谁能改的权限规则**(例如:「让普通标注员也能释放别人领取的任务」或「允许免登录直接访问导出接口」)。 +3. **修改数据库表结构或做数据迁移**(例如:拆分或合并存量业务表、删除已有字段、修改唯一索引)。 +4. **修改服务器部署配置、服务副本数或硬件资源配额**(例如:把某个后台服务停掉缩到 0、把单服务内存上限调高到超出服务器剩余空间)。 +5. **修改自动化测试的放行标准或已知失败清单**(例如:为了让发布通过,把报错的测试用例加进忽略名单)。 + +--- + +## 二、每级工程判定信号(开发实现依据) + +判定器按 **「高风险优先拦截 → 中风险特征匹配 → 其余归入低风险(须满足低风险白名单)」** 的顺序执行。只要命中任意一条高等级信号,立即按高等级定级。 + +### 1. 高风险判定信号(命中任一即判高风险) + +| 信号类别 | 路径 / 文件类型匹配 | 代码 / 配置特征模式(AST / 正则 / 结构对比) | 范围与上下文信号 | +| :--- | :--- | :--- | :--- | +| **数据库迁移与 Schema** | `**/migrations/**`
`**/schema/**`
`**/*migration*.{ts,js,go,py,sql}`
`**/indexes/**` | `createIndex`, `dropIndex`, `dropCollection`, `dropDatabase`, `renameCollection`, `ALTER TABLE`, `DROP TABLE`, `TRUNCATE`, `DROBOTICFLOW_DATABASE_BOOTSTRAP` | 新增或修改任何数据库初始化/迁移脚本 | +| **删除或批量修改数据** | 任何后端业务代码(`**/*.{ts,js,go,py}`) | MongoDB / SQL 破坏性或批量写操作:
`deleteMany`, `deleteOne`(非草稿/非临时会话), `updateMany`, `bulkWrite`, `replaceOne`, `findOneAndDelete`, `drop`, `$unset`, `$rename`, `remove(` | 包含无严格单文档主键约束的写操作,或循环调用写接口 | +| **权限与认证** | `**/permissions.{ts,js,go}`
`**/auth/**`, `**/rbac/**`
`**/middleware/auth*`
`packages/contracts/src/permissions.ts`
`packages/contracts/src/path-rules.ts`
`packages/contracts/src/release-risk.ts` | `Permissions.`, `accountTypes`, `normalizePermissions`, `role`, `jwt`, `session`, `cookie`, `token`, `oauth`, `allowBackend`, `pathsNeedingReview`, `protectedChange` | `releaseRisk` 标记 `permissionsExpanded`;修改角色权限映射或接口鉴权中间件 | +| **部署配置与容器构建** | `Dockerfile*`, `docker-compose*`
`k8s/**`, `infra/**`, `helm/**`
`scripts/deploy*`, `scripts/release*`
`scripts/poc-release.ts`
`**/*.env*`, `**/poc.env` | `replicas:`, `resources:`, `requests:`, `limits:`, `nodeAffinity`, `nodeSelector`, `tolerations`, `hostPath`, `local-storage`, `secretKeyRef`, `image:` | 修改容器镜像构建、启动命令、环境变量注入或 K8s 清单 | +| **副本缩到 0** | `k8s/**/*.yaml`, `infra/**/*.yaml`
或任何扩缩容补丁 | `replicas:\s*0`(除本来即为按需冷备且未发生变更的静态声明外,任何将在线服务 replicas 改为 `0` 的 diff) | 导致在线常驻服务实例数为 0 | +| **资源请求超过节点余量** | `k8s/**/*.yaml`, `infra/**/*.yaml`
`docs/capacity/*.json` | 计算变更后 `replicas × resources.requests`(CPU / Memory / `nvidia.com/gpu` / PVC 存储)与集群目标节点可用余量对比 | 变更后总请求超过节点可分配余量(或触发节点 CPU/内存水位红线、GPU 超配、不可扩容 PVC 超限) | +| **测试基线与验证配置** | `tests/known-failures.json`
`scripts/verification-scopes.json`
`packages/runtime/src/verify.ts`
`packages/runtime/src/sandbox.ts`
`**/fanyu-policy.json` | 新增 `known-failures` 条目、缩减 `verification-scopes` 映射范围、使用 `.skip` / `xit` / `t.skip` 跳过既有断言、修改 `core.hooksPath` 或沙箱隔离参数 | 削弱验证门禁或篡改测试通过基线 | +| **依赖清单与构建工具链** | `package.json`, `pnpm-lock.yaml`, `package-lock.json`, `go.mod`, `go.sum`, `requirements.txt` | 新增、升级或移除第三方依赖包,修改 `scripts` 中的构建/测试入口 | 命中 `dependencyManifest` 受保护路径 | + +### 2. 中风险判定信号(未命中高风险,且命中以下任一) + +| 信号类别 | 路径 / 文件类型匹配 | 代码 / 配置特征模式 | 范围与上下文信号 | +| :--- | :--- | :--- | :--- | +| **前端交互与状态逻辑** | `apps/web/src/**/*.{ts,tsx,js,jsx}`
`src/**/*.{ts,tsx,js,jsx}`(非纯样式/文案) | 修改 React hooks(`useState`, `useEffect`, `useMemo`)、表单提交处理、路由跳转、接口调用参数组装、前端分页与状态机 | 改动文件数 **2–5 个**,且总变更行数(增+删)**51–300 行** | +| **受限的后端/契约常规调整** | `apps/api/src/**/*.{ts,js}`
`packages/contracts/src/**/*.{ts,js}`
`internal/**/*.go`(非权限/非迁移/非批量写) | 只读查询优化(如增加游标分页、`maxTimeMS`、查询过滤条件)、单记录非破坏性字段校验、新增非敏感展示字段 | 未超出 Copilot 定位文件及其直接引用模块;包含对应单测更新 | +| **超出低风险白名单的微小修改** | 任何非高风险文件 | 虽未触碰高风险特征,但包含条件分支(`if/else`、`switch`)或函数签名变更 | 改动行数 ≤ 50 行但涉及逻辑分支变化 | + +### 3. 低风险判定信号(必须同时满足以下全部条件) + +| 信号类别 | 判定要求 | +| :--- | :--- | +| **路径与文件类型白名单** | 仅限前端视图/样式/文案/文档文件:
- 样式文件:`**/*.css`, `**/*.module.css`, `**/*.scss`
- 文案/常量/页面展示组件:`apps/web/src/**/*.{tsx,ts}` 或 `src/**/*.{ jsx,js,tsx,ts }` 中仅涉及 JSX 文本节点、文案字典、样式类名
- 文档:`wiki/**/*.md`, `docs/**/*.md` | +| **代码特征要求** | - 无任何后端、数据库、权限、配置、依赖、测试基线文件改动
- 无新增或修改网络请求调用(`fetch`, `axios`, API Client 方法)
- 无数据写操作或状态机流转分支变更 | +| **改动规模与范围** | - 改动文件数 **≤ 2 个**
- 总变更行数(增+删)**≤ 50 行**
- **100% 在 Copilot 定位的目标文件范围内**(未波及定位范围外的文件) | + +--- + +## 三、审批权限、发布前证据与发布后观察/回滚 + +| 维度 | 低风险(Low) | 中风险(Medium) | 高风险(High) | +| :--- | :--- | :--- | :--- | +| **谁批准发布** | **客户自己批准**(具备发布权限的客户业务责任人) | **客户自己批准**(具备发布权限的客户业务责任人) | **必须平台方审批**(客户确认需求意向后,转交平台方技术/运维负责人审批) | +| **发布前必须具备的证据** | 1. G1 代码与分支新鲜度检查通过
2. 前端构建与类型检查通过(`build:web` / `typecheck`)
3. 修改前后的界面对比截图或文案 diff 预览
4. G9 客户版交付报告(「通过 / 失败 / 待验证 / 没做」四栏完整,且「失败」栏为 0) | 1. 包含低风险全部证据
2. G2 分层验证通过(`verify:quick` 及改动映射的 `verify:task` 全部退出码为 0)
3. G3 基线保护通过(未新增 `known-failures`,无绕过测试)
4. 涉及的角色与页面状态(加载/空态/报错/只读)实测记录 | 1. 包含中风险全部证据 + 完整集成验证(`verify:integration`)
2. **平台方专项审查记录**:
- 数据类:备份快照确认、影响行数预估、只读演练结果
- 权限类:全角色权限矩阵回归测试报告
- 资源/部署类:集群节点余量核算单(R1–R3)与回滚补丁(`.rollback.patch.yaml`) | +| **发布后怎么观察** | 1. 自动核对 `/api/health` 的 `buildCommit` 与发布版本一致
2. 观察 **5 分钟**内前端页面加载与接口 5xx 错误率 | 1. 自动核对 `/api/health` 的 `buildCommit` 与服务 Ready 状态
2. 观察 **15 分钟**内目标接口耗时(p95)、5xx 错误率及脱敏线上错误日志
3. 客户在页面执行 1 次真实业务动作确认 | 1. 按 Coordinator → Worker/Processor → API 顺序分步观察健康检查
2. 持续观察 **30 分钟**集群 CPU/内存/GPU 水位、慢查询日志与业务核心指标
3. 平台方值班人员在线盯屏确认 | +| **怎么回滚** | - 客户可在界面一键点击「回滚到上一版本」或「撤销本次修改」
- 若健康检查连续失败,系统自动回滚至上一稳定镜像/提交 | - 客户可在界面一键触发版本回滚(拥有独立回滚权限的客户负责人可直接操作,无需等待平台方)
- 健康检查失败或核心接口 5xx 激增时自动回滚 | - 优先使用预先准备的对偶回滚补丁(如 `*.rollback.patch.yaml`)或镜像 digest 条件回滚
- 涉及数据库迁移或数据的,按平台方审批的专项回滚预案执行(严禁盲目回退代码导致新旧数据结构不兼容) | + +--- + +## 四、拿不准时的兜底规则(默认升档原则) + +当系统或 Copilot 遇到以下任一情况,视为**「拿不准(Uncertain)」**: +1. **超出定位范围**:实际修改的文件超出了与客户对话时 Copilot 定位的文件列表。 +2. **信号混合或无法解析**:改动同时包含低风险样式修改与未明确分类的脚本/配置,或 AST/Diff 解析器无法100%确认某次数据库调用是否为只读。 +3. **验证结果不完整**:验证命令返回超时/跳过/未映射(如退出码 `2`),或存在「待验证」项无法在沙箱内自动完成。 +4. **缺少明确规则匹配**:命中了新的文件目录或未知文件后缀(既不在低风险白名单,也未明确写入中/高风险特征库,即 `unclassified`)。 + +### 处理方式: +1. **默认判到更高一级**: + - 原本像低风险但拿不准(例如改文案时顺手改了旁边的条件判断,或改动超出了定位文件) → **一律升为中风险**。 + - 原本像中风险但拿不准(例如改查询接口时碰到了权限校验函数、公共中间件或未知后端路径) → **一律升为高风险**,转交平台方审批。 +2. **向客户透明告知原因(禁止隐瞒或使用内部黑话)**: + - 必须在界面与交付报告中用一句话告诉客户**为什么升档**以及**接下来谁来处理**。 + - **低升中话术示例**:「这次修改除了改文字,还调整了按钮的显示条件,为了稳妥已按『中风险』为您补充了功能测试,您可以查看测试结果后决定是否发布。」 + - **中升高话术示例**:「这次修改涉及后台权限检查(或超出了原本定位的页面范围),为保护平台和您的数据安全,已自动转为『高风险』并提交平台技术团队审核,审核通过后会第一时间通知您。」 diff --git a/wiki/features/gates.md b/wiki/features/gates.md new file mode 100644 index 0000000..601f365 --- /dev/null +++ b/wiki/features/gates.md @@ -0,0 +1,176 @@ +# 门禁清单 v1(Gates & Safeguards) + +本文档定义 WishForge 面向客户自助修改与发布全流程的防事故门禁(S1–S5、G1–G3、G9)及门禁自我迭代机制(G10)。所有门禁的核心目标是**防止平台崩溃、防止客户数据丢失、杜绝「带病上线」与「口头说修好了但实际没验证」**。 + +--- + +## 一、核心防事故安全门禁(S1–S5) + +### S1:改动分级门禁(Change Risk Classification Gate) +- **目的**:识别改动的影响面与破坏性,把低/中风险交给客户自主快速决策,把高风险(迁移、删改数据、权限、部署配置、测试基线、缩到 0 副本、超节点余量)强制交由平台方把关,杜绝越权改动引发生产事故。 +- **触发条件**:每次修改代码生成 Diff 后、进入发布申请(`releases.request`)前自动触发;检测修改路径、AST/关键字特征(如 `deleteMany`、`migration`、`permissions`、`k8s/`、`replicas: 0`、`resources.requests`)、改动行数及是否超出 Copilot 定位文件范围。 +- **拦下还是只提醒**: + - **低/中风险**:不拦死客户,标记风险等级并在界面提醒客户核对对应验证证据后自主批准。 + - **高风险 / 拿不准升档为高风险**:**硬拦截客户自助发布**,冻结客户侧「立即发布」按钮,自动转为「等待平台方审批」状态。 +- **客户看到的提示文案**: + - *判为低/中风险时*:「本次修改为【低/中风险】,已完成自动检查,请核对下方检查结果后点击『批准发布』。」 + - *判为高风险拦下时*:「这次修改涉及【数据安全 / 权限规则 / 服务器配置】,为防止影响线上运行,已提交平台技术团队审核,审核通过后方可发布。」 + - *拿不准自动升档时*:「这次修改超出了原本定位的页面范围,为稳妥起见已按更高安全等级处理,需等待平台技术团队确认。」 +- **来源**: + - WishForge 业务许愿试点差距分析(`docs/reviews/2026-10-28-business-wish-pilot-gap-analysis.md`:P0 简化业务提报模式、禁止诱导业务用户通过 `allowBackend` 自行扩围、收口发布审批); + - WishForge 发布风险与受保护路径契约(`packages/contracts/src/release-risk.ts:6-33`、`packages/contracts/src/change-paths.ts:1-16`、`apps/api/src/domain/policy.ts:41`)。 + +--- + +### S2:数据保护门禁(Data Protection & Read-Only Gate) +- **目的**:严防 Copilot 排查、验证或代码修改过程中误删、误改客户线上业务数据,防止无超时约束的慢查询拖垮线上 MongoDB。 +- **触发条件**: + 1. Copilot 或诊断工具连接线上 MongoDB / 集群 API 时; + 2. 提交的代码 Diff 中出现数据库删除、批量覆写、删表/删索引(`deleteMany`、`drop`、`$unset`、`updateMany` 等)或修改只读探针逻辑时; + 3. 列表/聚合查询未携带分页或超时保护(`maxTimeMS`)时。 +- **拦下还是只提醒**:**硬拦下(Block)**。 + - 线上数据库强制使用只读账号 `wishforge_observer`(仅 `read` 权限,写操作在数据库层直接报错拒绝); + - 集群仅授予只读 ServiceAccount; + - 代码中检出破坏性写操作或高危无界查询时,直接拦截自助发布。 +- **客户看到的提示文案**: + - *Copilot 被要求直接改线上数据时*:「为了保护您的数据安全,我只有线上数据的只读查看权限,不能直接修改或删除数据库里的记录。如果您需要调整某项功能,我可以帮您生成修改方案。」 + - *代码包含删改数据操作被拦下时*:「检测到本次修改包含批量删除或改写数据的操作,为防止数据丢失,系统已拦截自助发布,请由平台技术团队协助核对并执行。」 +- **来源**: + - WishForge MongoDB 只读账号运维规范(`docs/ops/mongodb-readonly.md`); + - droboticflow 看板超时与慢查询事故复盘(`docs/verification/claim-dashboard-timeout-20261103.md`:镜像 `dffba6ca` 中 `63714753` 引入无 `maxTimeMS` 的 3 次 lookup 聚合,导致 83 个超 2 分钟陈旧 `getMore` 读操作堆积,最终需人工 `killOp` 恢复); + - droboticflow 源数据校验只读探针教训(`docs/verification/source-validation-admission.md`:`GET /tasks/{id}/frame-timeline` 会持久化隔离状态,严禁作为生产只读探针,必须用 `?view=status`)。 + +--- + +### S3:验证不过不能发布门禁(Verification Must Pass Gate) +- **目的**:确保任何上线代码都经过与改动范围匹配的独立自动化验证,杜绝「代码编不过、测试跑不通、或者验证超时跳过」的改动混入生产环境。 +- **触发条件**:每次 Run 完成代码修改准备进入待发布状态时,以及点击「批准发布」执行 `releases.decide` / `scripts/release.py check` 时。 +- **拦下还是只提醒**:**硬拦下(Block)**。只要存在任一验证失败(退出码 `1`)、超时/跳过/未映射(退出码 `2` 或 `124`)、工作区提交不一致(`CHECKPOINT_CHANGED`)或生产验证配置缺失(`verification_unconfigured`),一律禁止发布。 +- **客户看到的提示文案**: + - *验证未通过时*:「还有检查项未通过,暂时不能发布。您可以点击『让 Copilot 继续修复』,或转交技术团队处理。」 + - *验证超时或环境异常时*:「自动检查未能在规定时间内完成,为确保线上稳定,本次修改暂不可发布,请重试或联系技术支持。」 +- **来源**: + - WishForge 独立沙箱验证机制(`packages/runtime/src/verify.ts:110` `verifyWorkspace`、`packages/runtime/src/sandbox.ts:34` `isolatedVerifierExecutor`、`apps/api/src/http.ts:252`); + - droboticflow 分层验证与发布规范(`docs/agents/verification.md`、`docs/release/README.md`、`fanyu-policy.json` 强制核对 8 项 `requiredEvidence` 与 19 项 `localChecks`)。 + +--- + +### S4:发布审批 + 健康检查 + 自动回滚门禁(Release Approval, Healthcheck & Rollback Gate) +- **目的**:保证每次发布都有明确的责任人确认、发布内容与审批内容严格一致(防篡改)、按安全顺序滚动更新,且一旦新版本启动异常或健康检查失败能立即回滚,避免平台长时间中断。 +- **触发条件**: + 1. 发起发布申请与点击批准时(校验审批人权限与 `bindingDigest` 摘要绑定); + 2. 执行集群滚动更新时(拦截全量 `kubectl apply`,强制按 Coordinator → Worker/Processor → API 顺序,校验 UID/resourceVersion/previous image); + 3. 发布后验证 `/api/health.buildCommit` 与服务探针状态时。 +- **拦下还是只提醒**:**硬拦下 + 失败自动回滚(Block & Auto-Rollback)**。 + - 未获对应等级审批人批准、或代码摘要 `bindingDigest` 发生变化的,直接拦下拒绝部署; + - 严禁设置 `autoDeploy=true` 绕过人工批准; + - 发布后若健康检查超时或 `buildCommit` 不匹配,自动触发回滚至上一稳定镜像 digest,并将状态记为 `rolled_back`(若回滚异常则记为 `needs_reconciliation` 并立即告警)。 +- **客户看到的提示文案**: + - *等待审批时*:「修改已准备就绪,正在等待【客户负责人 / 平台技术团队】批准发布。」 + - *发布内容变更被拦下时*:「待发布的内容发生了变化,请重新查看检查报告后再确认发布。」 + - *健康检查失败触发自动回滚时*:「新版本启动检查未通过,系统已自动恢复到修改前的稳定版本,您的线上业务和数据未受影响。」 +- **来源**: + - WishForge 发布绑定与回滚实现(`apps/api/src/domain/releases.ts:42` `releaseBinding`、`:280` `request`、`:435` `decide`、`:662` `rollback`); + - WishForge POC 驻地交付规范(`docs/reference/poc-delivery-profile.md`、`packages/runtime/src/poc-profile.ts`、`scripts/poc-release.ts`); + - WishForge 差距分析(`docs/reviews/2026-10-28-business-wish-pilot-gap-analysis.md`:P0 拆出独立回滚权限、防止 `autoDeploy=true` 绕过确认); + - droboticflow 发布脚本防误操作门禁(`scripts/deploy-k8s.sh:17-20` 硬阻断 `fanyu` 全量 apply,`scripts/release.py` 绑定不可变镜像 digest)。 + +--- + +### S5:Run 资源隔离与集群余量门禁(Run Isolation & Cluster Capacity Gate) +- **目的**:防止单个自动修复/验证任务(Run)耗尽宿主机或集群算力、网络、磁盘,同时防止服务扩容或算子启动超出集群节点物理余量导致业务 Pod 被驱逐或 OOM 崩溃。 +- **触发条件**: + 1. 启动任何 WishForge Run 或独立验证沙箱时; + 2. 修改 K8s 资源配额(`requests`/`limits`/`replicas`)或调度大算子(如 WiLoR、HeadPose、Qwen 粗切)时; + 3. 集群节点 CPU/内存、GPU 或 `workspace`(200Gi 不可扩容 BOS PVC)水位逼近阈值时。 +- **拦下还是只提醒**: + - **沙箱隔离、超时与重试上限**:**硬拦下**(Linux `/usr/bin/bwrap` 无网沙箱、单步超时退出码 `124`、自修复最多 3 次耗尽进入 `repair_exhausted` 停止自动重试); + - **水位预警(达 80%)**:**提醒**(在资源页与发布页黄字提示); + - **超出节点余量 / GPU 被占满 / 不可扩容存储达红线(90%)**:**硬拦下**,禁止直接扩容或发布。 +- **客户看到的提示文案**: + - *3 次自修复耗尽被拦下时*:「Copilot 已尝试自动修复 3 次仍未彻底解决,为避免无效消耗系统资源,已暂停自动尝试。您可以补充更具体的说明,或转交技术团队处理。」 + - *资源请求超节点余量被拦下时*:「当前服务器剩余资源不足以支持本次调整,强行发布可能导致线上服务卡顿或中断,已转交平台技术团队统筹调配。」 +- **来源**: + - WishForge 沙箱隔离与预算控制(`packages/runtime/src/sandbox.ts:34`、`packages/contracts/src/index.ts:414` `repair_exhausted`、`tests/run-budget.test.ts`); + - droboticflow 100 人容量基线与 validator 扩容复盘(`docs/capacity/source-index-100.md`、`docs/capacity/validator-scale-20261026.md`、`docs/fanyu-resource-profile.md`)。 + +--- + +## 二、研发与交付质量门禁(G1、G2、G3、G9) + +### G1:代码与基线新鲜度门禁(Freshness Gate) +- **目的**:防止基于过时的旧分支或旧代码修改,导致上线后把别人刚修好的功能覆盖掉(代码回退回归),或者因工作区有未清理的脏改动导致构建结果与源码不一致。 +- **触发条件**:Run 启动前、验证执行前(核对 `HEAD`)、以及打包发布前(源码审计)。 +- **拦下还是只提醒**:**硬拦下(Block)**。 + - 验证过程发现 `HEAD` 变化报 `CHECKPOINT_CHANGED` 立即中止; + - 改动分支落后于目标发布基线且存在冲突或触碰相同模块、或构建镜像的 `buildCommit` 与源码 commit 不一致时,直接拦截发布。 +- **客户看到的提示文案**:「线上系统刚刚有其他更新上线,为了防止冲掉最新功能,系统正在基于最新版本重新核对您的修改,请稍候确认。」 +- **来源**: + - droboticflow `d7201ebf` 领取功能回归与 worktree 分叉治理复盘(多个陈旧 worktree 基于旧基线修改,若不核对最新基线直接合入会导致已修复的随机领取与审核池逻辑回归); + - droboticflow 发布源码一致性审计(`scripts/release_source_audit.py`、`scripts/release-build-api-image.sh` 强制绑定 `DROBOTICFLOW_BUILD_COMMIT`); + - WishForge 验证工作区快照检查(`packages/runtime/src/verify.ts:110` `CHECKPOINT_CHANGED`)。 + +--- + +### G2:分层验证证据门禁(Verification Evidence Gate) +- **目的**:确保不同范围的改动必须拿到真实跑通的测试证据(日志、退出码、耗时、接口响应与页面多角色状态检查),杜绝「只改代码不跑测试」或「用口头保证代替实测证据」。 +- **触发条件**:根据改动文件路径映射 `scripts/verification-scopes.json` 执行对应层级的验证(`verify:plan` / `verify:quick` / `verify:task` / `verify:integration`),并在生成发布申请单时核对证据包。 +- **拦下还是只提醒**:**硬拦下(Block)**。缺少改动范围对应的必选测试报告(如 `local-data/test-results/verify-*`)、或未记录所检查的角色与页面状态(加载/空态/错误/只读)时,禁止进入发布批准环节。 +- **客户看到的提示文案**:「系统正在为您本次修改的功能做实测验证,全部检查通过并生成验证报告后即可发布。」(若缺失证据被拦:「本次修改缺少完整的自动测试记录,暂不能发布。」) +- **来源**: + - droboticflow 分层验证规范(`docs/agents/verification.md`、`scripts/verification-scopes.json`); + - droboticflow 审核池搜索与源数据准入验证复盘(`docs/verification/review-pool-search.md`、`docs/verification/source-gate-pool-search.md`、`docs/verification/owned-source-exceptions-20261102.md`); + - droboticflow UI 文案与交付核对规范(`docs/ui/copy-guidelines.md`:交付必须注明检查过的角色、状态及验证证据)。 + +--- + +### G3:测试基线保护门禁(Baseline Protection Gate) +- **目的**:严防智能体或开发人员为了「让红灯变绿灯」而偷偷修改测试放行标准、把新写出的 Bug 塞进「已知失败清单(`known-failures.json`)」、注释断言或禁用 Git Hooks。 +- **触发条件**:每次提交或验证时,检查 `tests/known-failures.json`、`scripts/verification-scopes.json`、测试文件中的 `.skip` / `only` 标记以及 Git 配置。 +- **拦下还是只提醒**:**硬拦下(Block)**。 + - 独立验证器强制设置 `core.hooksPath=/dev/null` 并导出干净工作树; + - 任何扩大 `tests/known-failures.json` 失败列表、缩减 `verification-scopes.json` 或跳过断言的改动,直接拦下并判为违规(若确需调整测试基线,必须按 S1 高风险走平台方人工审批)。 +- **客户看到的提示文案**:「检测到自动测试标准被改动,为确保检查真实有效,系统已拦截本次操作并转交平台技术团队核查。」 +- **来源**: + - droboticflow 分层验证铁律(`docs/agents/verification.md`:使用 `test:frontend:gate` 与 `test:go:gate` 对照 `tests/known-failures.json`,**严禁扩大 known-failures 基线或手工忽略断言**); + - WishForge 独立验证防作弊沙箱(`packages/runtime/src/verify.ts:110` 导出兄弟目录 `${workspace}-tree`、禁用 hooks)。 + +--- + +### G9:客户版四栏交付报告门禁(Delivery Report Gate) +- **目的**:让客户在批准发布前,一眼看清这次修改「哪些检查通过了、哪些失败了、哪些还需要人工看一眼、哪些没做」,杜绝报喜不报忧或用满屏英文日志糊弄客户。 +- **触发条件**:每次 Run 结束准备交付客户确认、或发起发布审批前。 +- **拦下还是只提醒**: + - **缺少四栏报告或「失败」栏不为 0**:**硬拦下(Block)**,不允许点批准发布; + - **「失败」栏为 0,但「待验证 / 没做」栏有内容**:**强提醒(Remind & Confirm)**,在批准按钮上方高亮展示待客户人工确认的事项,客户知情勾选/确认后可批准(低/中风险)。 +- **客户看到的提示文案**:「请查看本次修改的交付报告(已通过 / 未通过 / 需您确认 / 本次未改),确认无误后即可批准发布。」(详细模板见 `docs/product/copy/delivery-report.md`) +- **来源**: + - WishForge 业务页面与技术页面分层改造(`docs/reviews/2026-10-28-business-wish-pilot-gap-analysis.md`:隐藏底层冗余日志,提供清晰的中文业务总结); + - droboticflow 极简文案与交付透明规范(`docs/ui/copy-guidelines.md`、`docs/ui/error-messages.md`)。 + +--- + +## 三、门禁自我迭代机制(G10 预留规则) + +随着线上运行的许愿单、拦截记录和事故复盘不断积累,门禁规则支持通过 **G10(Gate Self-Iteration)** 持续演进,既避免规则僵化,又防止门禁被随意放水。 + +### 1. 提议来源(Proposal Sources) +系统在以下四类事件发生时,自动分析并生成「门禁规则调整提议卡」: +1. **线上回滚或故障复盘**:某次发布通过了现有门禁,但上线后触发了健康检查回滚或报错告警(说明现有门禁漏检,自动提议新增或收紧规则)。 +2. **高频重复修复失败(`repair_exhausted`)**:某类文件或接口连续多次出现相同的测试失败模式(自动提议补充前置检查或细化路径风险定级)。 +3. **误拦反馈**:某类纯展示或常规修改连续多次被判为「拿不准」升档,但人工复核 100% 安全通过(自动提议明确其判定信号)。 +4. **集群容量与慢查询新特征**:监控发现新的慢查询模式或资源瓶颈(如新的算子或新聚合接口,自动提议纳入 S2/S5 扫描特征)。 + +### 2. 分类管控:收紧类 vs 放松类 + +| 调整类型 | 定义举例 | 试运行要求 | 谁有批准权限 | +| :--- | :--- | :--- | :--- | +| **收紧类(Tightening)** | - 新增一条高/中风险代码特征(如新增某个危险函数拦截)
- 缩短某类接口的超时阈值
- 为某个模块增加必跑的验证用例 | **先「只提醒」试运行 1–2 周(Shadow / Remind Mode)**:
试运行期间命中新规则时,只记录日志并在报告中给出温和提醒,不直接阻断发布;观察 1–2 周确认无大面积误伤后,再切换为正式拦截。 | **客户负责人批准**(平台方提供试运行数据说明,由客户业务负责人拍板启用) | +| **放松类(Relaxing)** | - 将某类路径从高风险降为中/低风险
- 放宽改动行数上限或移除某项必跑检查
- 调高资源告警阈值或放宽 `known-failures` | **不允许直接试运行放行**:
在平台方正式批准前,仍按原严格标准执行。 | **必须平台方批准**(严禁客户侧或智能体自行放松安全底线) | + +### 3. 每月门禁健康报告(Monthly Gate Report) +系统每月自动向**客户负责人**与**平台方团队**生成一份简明《门禁运行与演进月报》,包含四项核心内容: +1. **本月拦截与保护统计**:共拦截多少次高危修改、避免了几次潜在数据删改或资源超限、触发了几次自动回滚。 +2. **试运行中的新规则表现**:当前处于 1–2 周试运行期的「收紧类」规则命中了多少次、是否有误报、是否建议转正。 +3. **误拦与耗时分析**:哪些检查项耗时最长、哪些修改触发了「拿不准升档」,是否存在优化空间。 +4. **待审批提议清单**:列出下月建议启用的收紧规则(待客户负责人批准)与精简提议(待平台方审批)。 From bf721b84a7525276b16c92611cc060aec6c39c59 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 22:23:01 -0800 Subject: [PATCH 07/46] =?UTF-8?q?=F0=9F=8E=A8=20Format=20source=20files=20?= =?UTF-8?q?and=20ignore=20local=20acceptance=20artifacts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .prettierignore | 3 +++ apps/web/src/features/runs.tsx | 3 +-- infra/k8s/cluster-observer.yaml | 3 +-- infra/k8s/cluster-poc/platform.yaml | 2 +- packages/contracts/src/models.ts | 3 +-- tests/model-catalog.test.ts | 9 +++++++-- tests/run-budget.test.ts | 8 +++++++- tests/wish-refiner.test.ts | 25 +++++++++---------------- 8 files changed, 30 insertions(+), 26 deletions(-) diff --git a/.prettierignore b/.prettierignore index 9050450..6ccf472 100644 --- a/.prettierignore +++ b/.prettierignore @@ -21,3 +21,6 @@ apps/web/next-env.d.ts # Sandbox-protected client configuration **/.mcp.json + +# Local acceptance run artifacts (each carried its own .gitignore) +.acceptances/ diff --git a/apps/web/src/features/runs.tsx b/apps/web/src/features/runs.tsx index 83301da..ab73460 100644 --- a/apps/web/src/features/runs.tsx +++ b/apps/web/src/features/runs.tsx @@ -462,8 +462,7 @@ export function NewWishView() { const provider = chosenProvider ?? initialWishProvider(providers.data, Boolean(localPoc)); // The project's models, flash when offered; a choice made for another project does not carry over. const projectModels = project?.models ?? []; - const model = - chosenModel && projectModels.includes(chosenModel) ? chosenModel : defaultProjectModel(projectModels); + const model = chosenModel && projectModels.includes(chosenModel) ? chosenModel : defaultProjectModel(projectModels); // The choice exists where the project says which code is backend. const scopePolicy = project?.codeReview?.paths.length ? project.codeReview : undefined; const scope = wishScopeFor(identity.data, project); diff --git a/infra/k8s/cluster-observer.yaml b/infra/k8s/cluster-observer.yaml index 4b4f93a..621b245 100644 --- a/infra/k8s/cluster-observer.yaml +++ b/infra/k8s/cluster-observer.yaml @@ -39,8 +39,7 @@ rules: resources: [nodes, namespaces, persistentvolumes] verbs: [get, list, watch] - apiGroups: [''] - resources: - [pods, pods/log, events, services, persistentvolumeclaims, resourcequotas, limitranges] + resources: [pods, pods/log, events, services, persistentvolumeclaims, resourcequotas, limitranges] verbs: [get, list, watch] - apiGroups: [apps] resources: [deployments, statefulsets, replicasets, daemonsets] diff --git a/infra/k8s/cluster-poc/platform.yaml b/infra/k8s/cluster-poc/platform.yaml index ac0e546..38fe33d 100644 --- a/infra/k8s/cluster-poc/platform.yaml +++ b/infra/k8s/cluster-poc/platform.yaml @@ -29,7 +29,7 @@ spec: metadata: labels: { app.kubernetes.io/part-of: wishforge-cluster-poc, app.kubernetes.io/name: wishforge } # The settings the containers read when they start (cluster-poc.mjs secrets): a change rolls the Pod. - annotations: { wishforge.io/settings: "${SETTINGS_DIGEST}" } + annotations: { wishforge.io/settings: '${SETTINGS_DIGEST}' } spec: serviceAccountName: wishforge automountServiceAccountToken: false diff --git a/packages/contracts/src/models.ts b/packages/contracts/src/models.ts index 0a7447e..5e95369 100644 --- a/packages/contracts/src/models.ts +++ b/packages/contracts/src/models.ts @@ -9,8 +9,7 @@ export const MAX_PROJECT_MODELS = 20; */ export const knownModels = ['deepseek-flash@latest[1m]', 'deepseek-pro@latest[1m]'] as const; export type KnownModel = (typeof knownModels)[number]; -export const isKnownModel = (name: string): name is KnownModel => - (knownModels as readonly string[]).includes(name); +export const isKnownModel = (name: string): name is KnownModel => (knownModels as readonly string[]).includes(name); /** Selected models in catalog order, then any name the catalog does not list. */ export const orderProjectModels = (models: string[]): string[] => { const selected = [...new Set(models)]; diff --git a/tests/model-catalog.test.ts b/tests/model-catalog.test.ts index 0bd7920..5ad56e3 100644 --- a/tests/model-catalog.test.ts +++ b/tests/model-catalog.test.ts @@ -17,7 +17,10 @@ const env = { WF_CLAUDE_LOCAL_AUTH_HOME: '/home/api', }; const settings = async () => ({ ANTHROPIC_BASE_URL: 'https://gateway.invalid/', ANTHROPIC_API_KEY: 'sk-fixture-key' }); -const answer = (body: unknown, status = 200) => async () => new Response(JSON.stringify(body), { status }); +const answer = + (body: unknown, status = 200) => + async () => + new Response(JSON.stringify(body), { status }); describe('model catalog', () => { it('lists the gateway’s models, sorted and each once, and asks with the operator’s key', async () => { @@ -49,7 +52,9 @@ describe('model catalog', () => { const catalog = new ModelCatalog(env, answer({ data: [] }) as unknown as typeof fetch, settings); await expect(catalog.list({ ...owner, role: 'developer' })).rejects.toMatchObject({ code: 'FORBIDDEN' }); await expect( - new ModelCatalog({ ...env, WF_CLAUDE_BIN: '' }, answer({ data: [] }) as unknown as typeof fetch, settings).list(owner), + new ModelCatalog({ ...env, WF_CLAUDE_BIN: '' }, answer({ data: [] }) as unknown as typeof fetch, settings).list( + owner, + ), ).rejects.toMatchObject({ code: 'MODELS_UNAVAILABLE' }); await expect( new ModelCatalog(env, answer({ data: [] }) as unknown as typeof fetch, async () => ({})).list(owner), diff --git a/tests/run-budget.test.ts b/tests/run-budget.test.ts index 1acb29a..a0ab9e8 100644 --- a/tests/run-budget.test.ts +++ b/tests/run-budget.test.ts @@ -95,7 +95,13 @@ describe('manual stopped-run budget adjustments', () => { await expect(control.updateBudget(owner, id, { maxTokens: 1100000 }, 'budget-reused-key')).rejects.toMatchObject({ code: 'IDEMPOTENCY_CONFLICT', }); - for (const input of [{}, { usedTokens: 0 }, { maxTokens: 500_000_001 }, { maxMinutes: 181 }, { maxRepairRounds: 4 }]) + for (const input of [ + {}, + { usedTokens: 0 }, + { maxTokens: 500_000_001 }, + { maxMinutes: 181 }, + { maxRepairRounds: 4 }, + ]) expect(budgetPatchSchema.safeParse(input).success).toBe(false); expect(budgetPatchSchema.parse({ maxTokens: 1000000 })).toEqual({ maxTokens: 1000000 }); expect(budgetPatchSchema.parse({ maxTokens: 500_000_000 })).toEqual({ maxTokens: 500_000_000 }); diff --git a/tests/wish-refiner.test.ts b/tests/wish-refiner.test.ts index 47b4784..aac2f06 100644 --- a/tests/wish-refiner.test.ts +++ b/tests/wish-refiner.test.ts @@ -93,18 +93,14 @@ describe('wish optimization', () => { }); it('lets the operator name a different model for optimization', async () => { const asked: { model?: string }[] = []; - const refiner = new WishRefiner( - store, - { ...env, WF_CLAUDE_ASK_MODEL: 'deepseek-pro@latest[1m]' }, - async input => { - asked.push(input); - return { - goal: '下载文件名带上数据集类型。\n范围:例如 xxx-episode.zip。', - acceptanceCriteria: ['现有测试、类型检查和构建全部通过'], - questions: [], - }; - }, - ); + const refiner = new WishRefiner(store, { ...env, WF_CLAUDE_ASK_MODEL: 'deepseek-pro@latest[1m]' }, async input => { + asked.push(input); + return { + goal: '下载文件名带上数据集类型。\n范围:例如 xxx-episode.zip。', + acceptanceCriteria: ['现有测试、类型检查和构建全部通过'], + questions: [], + }; + }); await refiner.refine(owner, projectId, { goal: '下载文件名要带上类型' }); expect(asked[0]!.model).toBe('deepseek-pro@latest[1m]'); expect(asked).toHaveLength(1); @@ -130,10 +126,7 @@ describe('wish optimization', () => { return asked.length === 4 ? usable : { goal: '', acceptanceCriteria: 'none' }; }); await unusable.refine(owner, projectId, { goal: '下载文件名要带上类型' }); - expect(asked.slice(2).map(call => call.model)).toEqual([ - 'deepseek-flash@latest[1m]', - 'deepseek-pro@latest[1m]', - ]); + expect(asked.slice(2).map(call => call.model)).toEqual(['deepseek-flash@latest[1m]', 'deepseek-pro@latest[1m]']); }); it('says so when no local Claude account serves this tenant, and when the answer is unusable', async () => { const unavailable = new WishRefiner(store, { ...env, WF_DEPLOYMENT_MODE: 'production' }, async () => ({})); From 3f6e0e269234c112ce3a599fb945199672cf0bb4 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 22:24:11 -0800 Subject: [PATCH 08/46] =?UTF-8?q?=E2=9C=85=20Assert=20canceled=20runs=20fa?= =?UTF-8?q?il=20their=20pending=20release=20with=20the=20cancellation=20re?= =?UTF-8?q?ason?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tests/control-hardening.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/control-hardening.test.ts b/tests/control-hardening.test.ts index 5afe9e9..cd1e0de 100644 --- a/tests/control-hardening.test.ts +++ b/tests/control-hardening.test.ts @@ -399,9 +399,11 @@ describe('signed runner receipts and real rollback state machine', () => { const envelope = (await broker.poll(runner, environment.id))!; expect(envelope.payload.release.id).toBe(oldest.id); const status = async (id: string) => (await db.transaction('alpha', tx => tx.get('release', id)))!; + // Canceled runs fail their pending release outright (see run-lifecycle's invalidation case), + // so the stale release no longer waits on the queue with a "request a new release" reason. expect(await status(canceled.release.id)).toMatchObject({ status: 'failed', - failureReason: expect.stringContaining('request a new release'), + failureReason: 'The run was canceled', }); // Continuing the paused run may make its release current again. expect((await status(paused.release.id)).status).toBe('ready'); From ae007d7bbe40251d815d53c94a016dbc58424501 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 22:24:35 -0800 Subject: [PATCH 09/46] =?UTF-8?q?=F0=9F=99=88=20Ignore=20local-data=20and?= =?UTF-8?q?=20local=20runtime=20artifacts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.gitignore b/.gitignore index 5373dfa..1c38c9e 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,13 @@ test-results/ # Generated by Next.js next-env.d.ts + +# Local agent/runtime artifacts +.env.local.bak* +.env*.bak* +infra/compose.local.yaml +.agents/ +.agent-teams/ + +# Local-only runtime state (cluster kubeconfig, operator notes) +local-data/ From e1194fbf8b37d461f2133d7ac097662db66ed197 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 22:35:31 -0800 Subject: [PATCH 10/46] =?UTF-8?q?=E2=9C=A8=20Serve=20repository=20Wiki=20r?= =?UTF-8?q?eads=20and=20let=20a=20server-held=20credential=20answer=20for?= =?UTF-8?q?=20the=20tenant?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/git-service/src/service.ts | 32 +++++++++++++++++++- apps/git-service/test/service.test.ts | 19 ++++++++++++ packages/runtime/src/providers/claude-ask.ts | 18 +++++++++-- packages/runtime/test/claude-ask.test.ts | 32 ++++++++++++++------ 4 files changed, 87 insertions(+), 14 deletions(-) diff --git a/apps/git-service/src/service.ts b/apps/git-service/src/service.ts index 4ed6d0e..78129bf 100644 --- a/apps/git-service/src/service.ts +++ b/apps/git-service/src/service.ts @@ -26,6 +26,13 @@ export interface GitClaims { refPrefix?: string; } const REF_PREFIX = /^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._-]{0,63}\/$/; +const REPOSITORY_FILE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/; +function repositoryFile(value: unknown) { + const file = String(value ?? ''); + if (!REPOSITORY_FILE.test(file) || file.includes('..') || file.endsWith('/')) + throw new RuntimeError('INVALID_PATH', 'Repository file path is not safe'); + return file; +} const gitEnv = () => ({ PATH: process.env.PATH, LANG: 'C.UTF-8', @@ -189,7 +196,7 @@ export async function createGitService(config: GitServiceConfig) { json(response, 200, { status: 'ok', service: 'git-storage' }); return; } - if (['/repos', '/tokens', '/refs'].includes(url.pathname) && request.method === 'POST') { + if (['/repos', '/tokens', '/refs', '/wiki'].includes(url.pathname) && request.method === 'POST') { const auth = request.headers.authorization ?? ''; if (!auth.startsWith('Bearer ') || !sameSecret(auth.slice(7), config.adminToken)) { json(response, 401, { error: 'UNAUTHORIZED' }); @@ -247,6 +254,29 @@ export async function createGitService(config: GitServiceConfig) { await lock.close(); await unlink(lockPath); } + } else if (url.pathname === '/wiki') { + await stat(repository); + const branch = requireBranchName(String(body.branch ?? 'main')); + const version = (await git(repository, ['rev-parse', '--verify', `${branch}^{commit}`])).trim(); + if (body.path !== undefined) { + const file = repositoryFile(body.path); + const content = await git(repository, ['show', `${branch}:${file}`]); + if (Buffer.byteLength(content) > 512 * 1024) + throw new RuntimeError('PAYLOAD_TOO_LARGE', 'File is too large'); + json(response, 200, { version, file: { path: file, content } }); + return; + } + const listed = await git(repository, ['ls-tree', '-r', '--name-only', branch, '--', 'wiki']); + const paths = listed + .split('\n') + .filter(file => file.endsWith('.md')) + .slice(0, 100); + const files = []; + for (const file of paths) { + const content = await git(repository, ['show', `${branch}:${file}`]); + if (Buffer.byteLength(content) <= 128 * 1024) files.push({ path: file, content }); + } + json(response, 200, { version, files }); } else if (url.pathname === '/refs') { await stat(repository); json(response, 200, { branches: await branchesIn(repository, String(body.prefix ?? '')) }); diff --git a/apps/git-service/test/service.test.ts b/apps/git-service/test/service.test.ts index 5e1c00a..a37e292 100644 --- a/apps/git-service/test/service.test.ts +++ b/apps/git-service/test/service.test.ts @@ -88,6 +88,12 @@ it('provisions a real bare repository and serves authenticated clone/CAS push ov targetBranch: 'release/v1', }); await writeFile(path.join(checkout.workspace, 'README.md'), 'A persistent project\n'); + await mkdir(path.join(checkout.workspace, 'wiki', 'features'), { recursive: true }); + await writeFile(path.join(checkout.workspace, 'wiki', 'index.md'), '# Project Wiki\n'); + await writeFile( + path.join(checkout.workspace, 'wiki', 'features', 'wish.md'), + '# Wish\nSee `apps/api/src/http.ts:416`.\n', + ); const checkpoint = await git.checkpoint(checkout.workspace, checkout.baseCommit, 'run', 'test'); const push = { repository: checkout.workspace, @@ -106,6 +112,19 @@ it('provisions a real bare repository and serves authenticated clone/CAS push ov targetBranch: 'release/v1', }); expect(second.baseCommit).toBe(checkpoint.sourceCommit); + const wiki = await post('/wiki', { tenantId: 'tenant', projectId: 'project', branch: 'release/v1' }); + expect(wiki.version).toBe(checkpoint.sourceCommit); + expect(wiki.files).toHaveLength(2); + const source = await post('/wiki', { + tenantId: 'tenant', + projectId: 'project', + branch: 'release/v1', + path: 'wiki/features/wish.md', + }); + expect(source.file).toMatchObject({ + path: 'wiki/features/wish.md', + content: expect.stringContaining('apps/api/src/http.ts:416'), + }); const afterPush = await post('/repos', { tenantId: 'tenant', projectId: 'project', defaultBranch: 'other' }); expect(afterPush.defaultBranch).toBe('release/v1'); expect(afterPush.initialCommit).toBe(checkpoint.sourceCommit); diff --git a/packages/runtime/src/providers/claude-ask.ts b/packages/runtime/src/providers/claude-ask.ts index ff2d81b..37948a6 100644 --- a/packages/runtime/src/providers/claude-ask.ts +++ b/packages/runtime/src/providers/claude-ask.ts @@ -20,6 +20,8 @@ export async function askClaude( schema: Record; /** Model the CLI should use; otherwise it uses ANTHROPIC_MODEL from the operator's settings. */ model?: string; + /** Server-held tenant credentials for a development Copilot call; never accepted from a browser. */ + credentialEnv?: Record; timeoutMs?: number; signal?: AbortSignal; }, @@ -51,7 +53,12 @@ export async function askClaude( ...(input.model ? ['--model', input.model] : []), ], cwd: directory, - env: { PATH: process.env.PATH, HOME: input.home, ...(await localCredentialEnv(input.home)) }, + env: { + PATH: process.env.PATH, + HOME: input.home, + ...(await localCredentialEnv(input.home)), + ...input.credentialEnv, + }, timeoutMs: input.timeoutMs ?? 120_000, signal: input.signal, }); @@ -61,8 +68,13 @@ export async function askClaude( } catch { throw new RuntimeError('ASK_FAILED', `Claude CLI exited ${result.exitCode} without a JSON result`); } - if (result.exitCode !== 0 || output.is_error) - throw new RuntimeError('ASK_FAILED', `Claude CLI could not answer (${output.subtype ?? result.exitCode})`); + if (result.exitCode !== 0 || output.is_error) { + const detail = typeof output.result === 'string' ? `: ${output.result.slice(0, 500)}` : ''; + throw new RuntimeError( + 'ASK_FAILED', + `Claude CLI could not answer (${output.subtype ?? result.exitCode})${detail}`, + ); + } if (output.structured_output !== undefined) return output.structured_output; // Older CLIs leave the answer as text: take the JSON object in it. const text = typeof output.result === 'string' ? output.result : ''; diff --git a/packages/runtime/test/claude-ask.test.ts b/packages/runtime/test/claude-ask.test.ts index bc7718b..242ec71 100644 --- a/packages/runtime/test/claude-ask.test.ts +++ b/packages/runtime/test/claude-ask.test.ts @@ -43,18 +43,30 @@ describe('asking the local Claude CLI', () => { expect(seen!.env).not.toHaveProperty('WF_DEV_AUTH_TOKEN'); expect(existsSync(seen!.cwd!)).toBe(false); }); - it('passes a named model to the CLI', async () => { + it('passes a named model and server-held credential environment to the CLI', async () => { let seen: Command | undefined; - await askClaude({ ...input, model: 'deepseek-flash@latest[1m]', timeoutMs: 140_000 }, async command => { - seen = command; - return { - exitCode: 0, - stdout: JSON.stringify({ is_error: false, structured_output: { goal: 'y' } }), - stderr: '', - durationMs: 1, - }; - }); + await askClaude( + { + ...input, + model: 'deepseek-flash@latest[1m]', + credentialEnv: { ANTHROPIC_API_KEY: 'server-fixture', ANTHROPIC_BASE_URL: 'https://model.example' }, + timeoutMs: 140_000, + }, + async command => { + seen = command; + return { + exitCode: 0, + stdout: JSON.stringify({ is_error: false, structured_output: { goal: 'y' } }), + stderr: '', + durationMs: 1, + }; + }, + ); expect(seen!.args[seen!.args.indexOf('--model') + 1]).toBe('deepseek-flash@latest[1m]'); + expect(seen!.env).toMatchObject({ + ANTHROPIC_API_KEY: 'server-fixture', + ANTHROPIC_BASE_URL: 'https://model.example', + }); expect(seen!.timeoutMs).toBe(140_000); }); it('takes the JSON object from a text answer, and fails on an error result', async () => { From ccd87cc23e0aa79334d822394c0333e89c2a4695 Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 22:36:06 -0800 Subject: [PATCH 11/46] =?UTF-8?q?=E2=9C=A8=20Add=20the=20grounded=20projec?= =?UTF-8?q?t=20Copilot=20API=20over=20the=20Wiki=20snapshot?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/api/src/domain/copilot.ts | 348 ++++++++++++++++++++++++++++ apps/api/src/domain/project-wiki.ts | 101 ++++++++ apps/api/src/http.ts | 43 +++- packages/contracts/src/copilot.ts | 57 +++++ packages/contracts/src/index.ts | 4 +- tests/copilot.test.ts | 234 +++++++++++++++++++ 6 files changed, 785 insertions(+), 2 deletions(-) create mode 100644 apps/api/src/domain/copilot.ts create mode 100644 apps/api/src/domain/project-wiki.ts create mode 100644 packages/contracts/src/copilot.ts create mode 100644 tests/copilot.test.ts diff --git a/apps/api/src/domain/copilot.ts b/apps/api/src/domain/copilot.ts new file mode 100644 index 0000000..609445e --- /dev/null +++ b/apps/api/src/domain/copilot.ts @@ -0,0 +1,348 @@ +import { randomUUID } from 'node:crypto'; +import os from 'node:os'; +import { z } from 'zod'; +import { askClaude } from '@wishforge/runtime'; +import { + DomainError, + copilotMessageInput, + copilotWishInput, + isProduction, + providerBaseUrl, + withAnswers, + type ProviderConnection, + type Actor, + type CopilotMessage, + type CopilotQuestion, + type CopilotSession, +} from '@wishforge/contracts'; +import type { Transaction } from '../db/store.js'; +import { ControlPlane, must, projectAccess, record, touch } from './control-plane.js'; +import { nativeClaudeEnabled } from './local-execution.js'; +import { CredentialVault } from './connections.js'; +import { requireHuman } from './policy.js'; +import { ProjectWiki, wikiSources, type WikiFile, type WikiSnapshot } from './project-wiki.js'; + +const option = z.object({ + label: z.string().trim().min(1).max(40), + wish: z.string().trim().min(1).max(500), + acceptanceCriterion: z.string().trim().min(1).max(500).optional(), +}); +const question = z.object({ + question: z.string().trim().min(1).max(300), + sourcePath: z.string().trim().min(1).max(256), + options: z.array(option).min(2).max(4), +}); +const modelAnswer = z.object({ + kind: z.enum(['faq', 'bug', 'feature', 'unknown']), + answer: z.string().trim().min(1).max(12000), + goal: z.string().trim().max(20000).optional(), + acceptanceCriteria: z.array(z.string().trim().min(1).max(2000)).max(30).default([]), + reproductionSteps: z.array(z.string().trim().min(1).max(1000)).max(12).default([]), + contextSummary: z.string().trim().max(4000).optional(), + questions: z.array(question).max(3).default([]), +}); +const responseSchema = { + type: 'object', + properties: { + kind: { type: 'string', enum: ['faq', 'bug', 'feature', 'unknown'] }, + answer: { type: 'string' }, + goal: { type: 'string' }, + acceptanceCriteria: { type: 'array', items: { type: 'string' } }, + reproductionSteps: { type: 'array', items: { type: 'string' } }, + contextSummary: { type: 'string' }, + questions: { + type: 'array', + items: { + type: 'object', + properties: { + question: { type: 'string' }, + sourcePath: { type: 'string' }, + options: { + type: 'array', + items: { + type: 'object', + properties: { + label: { type: 'string' }, + wish: { type: 'string' }, + acceptanceCriterion: { type: 'string' }, + }, + required: ['label', 'wish'], + additionalProperties: false, + }, + }, + }, + required: ['question', 'sourcePath', 'options'], + additionalProperties: false, + }, + }, + }, + required: ['kind', 'answer'], + additionalProperties: false, +}; +const SYSTEM = `你是 WishForge 项目 Copilot。只能依据随请求提供的 Wiki 快照回答项目事实,不能使用模型记忆补充,也不能编造代码、配置或来源。 +将问题分为 faq(FAQ/配置问题)、bug(有实际异常或复现线索的疑似系统 Bug)、feature(需求或改进)、unknown(依据不足或不清楚)。 +FAQ 的答案必须能由给定页面直接支撑;否则选择 unknown 并明确说不知道。Bug 要给出 answer、reproductionSteps、contextSummary,以及可编辑的 goal 和 acceptanceCriteria,但不能声称已经确认是代码缺陷。 +Feature 要给出可编辑的 goal 和 acceptanceCriteria。只有 Wiki 能支撑且必须由用户拍板的问题才进入 questions;每个 question 的 sourcePath 必须逐字使用一个给定 Wiki 路径,选项包含加入 goal 的 wish,必要时包含 acceptanceCriterion。FAQ 和 unknown 的 questions 必须为空。 +所有文字使用中文,answer 简洁但直接。`; +const terms = (value: string) => { + const normalized = value.toLowerCase(); + const words = normalized.match(/[a-z0-9_.-]{2,}|[\u4e00-\u9fff]+/g) ?? []; + const grams = words.flatMap(word => + /^[\u4e00-\u9fff]+$/.test(word) + ? [...word].map((_, i) => word.slice(i, i + 2)).filter(x => x.length === 2) + : [word], + ); + return new Set(grams); +}; +function retrieve(snapshot: WikiSnapshot, query: string): WikiFile[] { + const wanted = terms(query); + const ranked = snapshot.files + .map(file => { + const haystack = `${file.path}\n${file.content}`.toLowerCase(); + const score = [...wanted].reduce((total, term) => total + (haystack.includes(term) ? 1 : 0), 0); + return { file, score }; + }) + .sort((a, b) => b.score - a.score); + const matches = ranked + .filter(item => item.score > 0) + .slice(0, 4) + .map(item => item.file); + const index = snapshot.files.find(file => file.path === 'wiki/index.md'); + return [ + ...new Map( + [...matches, ...(index && !matches.includes(index) ? [index] : [])].map(file => [file.path, file]), + ).values(), + ]; +} +async function sessionAccess(tx: Transaction, actor: Actor, projectId: string, sessionId: string) { + await projectAccess(tx, actor, projectId); + const session = await must(tx, 'copilot_session', sessionId); + if (session.projectId !== projectId || session.userId !== actor.userId) + throw new DomainError('NOT_FOUND', 'Copilot session not found', 404); + return session; +} + +export class Copilot { + constructor( + private control: ControlPlane, + private env = process.env, + private askModel = askClaude, + private wiki: Pick = new ProjectWiki(control.store, env), + ) {} + private get store() { + return this.control.store; + } + private async tenantConnection(actor: Actor) { + if (isProduction(this.env) || !this.env.WF_CLAUDE_BIN) return undefined; + return this.store.read(actor.tenantId, async tx => + (await tx.list('provider_connection')).find( + connection => connection.provider === 'claude-code' && connection.status === 'active' && connection.ciphertext, + ), + ); + } + async available(tenantId: string) { + if (nativeClaudeEnabled(this.env, tenantId)) return true; + if (isProduction(this.env) || !this.env.WF_CLAUDE_BIN) return false; + return this.store.read(tenantId, async tx => + (await tx.list('provider_connection')).some( + connection => connection.provider === 'claude-code' && connection.status === 'active' && connection.ciphertext, + ), + ); + } + private async tenantCredentials(actor: Actor) { + const connection = await this.tenantConnection(actor); + if (!connection?.ciphertext) return undefined; + const apiKey = await new CredentialVault(this.env).open(actor.tenantId, String(connection.ciphertext)); + const baseUrl = providerBaseUrl(this.env, 'claude-code'); + return { ANTHROPIC_API_KEY: apiKey, ...(baseUrl ? { ANTHROPIC_BASE_URL: baseUrl } : {}) }; + } + async createSession(actor: Actor, projectId: string) { + requireHuman(actor); + return this.store.transaction(actor.tenantId, async tx => { + await projectAccess(tx, actor, projectId); + const session = { ...record(actor.tenantId), projectId, userId: actor.userId, messages: [] } as CopilotSession; + await tx.put('copilot_session', session); + return session; + }); + } + async session(actor: Actor, projectId: string, sessionId: string) { + requireHuman(actor); + return this.store.transaction(actor.tenantId, async tx => { + const session = await sessionAccess(tx, actor, projectId, sessionId); + const interrupted = session.messages.some( + message => message.status === 'pending' && Date.now() - Date.parse(message.createdAt) > 210_000, + ); + if (!interrupted) return session; + const next = { + ...touch(session), + messages: session.messages.map(message => + message.status === 'pending' && Date.now() - Date.parse(message.createdAt) > 210_000 + ? { ...message, status: 'error' as const, content: '上次回答因连接或服务中断而停止,请重新提问。' } + : message, + ), + }; + await tx.put('copilot_session', next); + return next; + }); + } + async ask(actor: Actor, projectId: string, sessionId: string, input: unknown) { + requireHuman(actor); + const data = copilotMessageInput.parse(input); + if (!(await this.available(actor.tenantId))) + throw new DomainError('COPILOT_UNAVAILABLE', 'The project Copilot model is not configured', 503); + const pending = await this.store.transaction(actor.tenantId, async tx => { + const session = await sessionAccess(tx, actor, projectId, sessionId); + const existing = session.messages.find(message => message.role === 'user' && message.clientId === data.clientId); + if (existing) + return { + session, + assistantId: session.messages.find(message => message.id === existing.id.replace(':user', ':assistant'))?.id, + }; + const userId = `${randomUUID()}:user`; + const assistantId = `${randomUUID()}:assistant`; + const time = new Date().toISOString(); + const user: CopilotMessage = { + id: userId, + role: 'user', + content: data.content, + clientId: data.clientId, + status: 'complete', + createdAt: time, + }; + const assistant: CopilotMessage = { + id: assistantId, + role: 'assistant', + content: '', + status: 'pending', + createdAt: time, + }; + const next = { ...touch(session), messages: [...session.messages, user, assistant].slice(-100) }; + await tx.put('copilot_session', next); + return { session: next, assistantId }; + }); + if (pending.session.messages.find(message => message.id === pending.assistantId)?.status !== 'pending') + return pending.session; + if (pending.session.messages.at(-1)?.id !== pending.assistantId) return pending.session; + try { + const snapshot = await this.wiki.snapshot(actor, projectId); + const files = retrieve(snapshot, data.content); + const sources = wikiSources(snapshot, files); + const attempts = nativeClaudeEnabled(this.env, actor.tenantId) ? ['native', 'tenant'] : ['tenant']; + let result: z.infer | undefined; + let failure: unknown; + for (const attempt of attempts) { + try { + const credentialEnv = attempt === 'native' ? undefined : await this.tenantCredentials(actor); + if (attempt === 'tenant' && !credentialEnv) continue; + result = modelAnswer.parse( + await this.askModel({ + binary: this.env.WF_CLAUDE_BIN!, + home: this.env.WF_CLAUDE_LOCAL_AUTH_HOME || os.tmpdir(), + system: SYSTEM, + ...(this.env.WF_CLAUDE_ASK_MODEL ? { model: this.env.WF_CLAUDE_ASK_MODEL } : {}), + timeoutMs: attempt === 'tenant' ? 300_000 : 180_000, + schema: responseSchema, + credentialEnv, + prompt: JSON.stringify({ + project: snapshot.project.name, + question: data.content, + currentContext: data.context, + wikiVersion: snapshot.version, + wiki: files.map(file => ({ path: file.path, content: file.content.slice(0, 16000) })), + }), + }), + ); + break; + } catch (error) { + failure = error; + console.warn(`Copilot ${attempt} model failed: ${error instanceof Error ? error.message : 'unknown error'}`); + } + } + if (!result) throw failure ?? new Error('No Copilot model credential is available'); + const kind = result.kind === 'faq' && files.length === 0 ? 'unknown' : result.kind; + const allowedPaths = new Set(files.map(file => file.path)); + const questions: CopilotQuestion[] = + kind === 'feature' ? result.questions.filter(item => allowedPaths.has(item.sourcePath)) : []; + const content = + kind === result.kind + ? result.answer + : '当前 Wiki 没有足够依据回答这个问题。请补充上下文,或改成一个明确的需求。'; + return await this.store.transaction(actor.tenantId, async tx => { + const session = await sessionAccess(tx, actor, projectId, sessionId); + const messages = session.messages.map(message => + message.id === pending.assistantId + ? { + ...message, + status: 'complete' as const, + content, + kind, + sources: kind === 'unknown' ? [] : sources, + knowledgeVersion: snapshot.version, + ...(result.goal + ? { goal: result.goal } + : kind === 'bug' || kind === 'feature' + ? { goal: data.content } + : {}), + ...(kind === 'bug' || kind === 'feature' ? { acceptanceCriteria: result.acceptanceCriteria } : {}), + ...(kind === 'bug' + ? { reproductionSteps: result.reproductionSteps, contextSummary: result.contextSummary } + : {}), + questions, + } + : message, + ); + const next = { ...touch(session), messages }; + await tx.put('copilot_session', next); + return next; + }); + } catch (error) { + await this.store.transaction(actor.tenantId, async tx => { + const session = await sessionAccess(tx, actor, projectId, sessionId); + const next = { + ...touch(session), + messages: session.messages.map(message => + message.id === pending.assistantId + ? { ...message, status: 'error' as const, content: '本次回答未完成,请重试;你的问题已保留。' } + : message, + ), + }; + await tx.put('copilot_session', next); + }); + if (error instanceof DomainError) throw error; + throw new DomainError('COPILOT_FAILED', 'The Copilot could not produce a grounded answer', 502); + } + } + async createWish(actor: Actor, projectId: string, sessionId: string, input: unknown) { + requireHuman(actor); + const data = copilotWishInput.parse(input); + const session = await this.session(actor, projectId, sessionId); + const message = session.messages.find(item => item.id === data.messageId && item.role === 'assistant'); + if (!message || message.status !== 'complete' || !['bug', 'feature'].includes(message.kind ?? '')) + throw new DomainError('COPILOT_WISH_NOT_READY', 'Only a completed Bug or feature answer can become a Wish', 409); + if (message.wish) return message.wish; + const provider = (await this.control.providers(actor)).find(item => item.enabled); + if (!provider) + throw new DomainError('COPILOT_NO_PROVIDER', 'Configure an enabled executor before creating a Wish', 409); + const created = await this.control.submit( + actor, + projectId, + { + goal: withAnswers(data.goal, data.answers), + acceptanceCriteria: data.acceptanceCriteria, + provider: provider.id, + budget: { maxTokens: 300000, maxMinutes: 30, maxRepairRounds: 3 }, + }, + `copilot:${sessionId}:${message.id}`, + ); + const wish = { wishId: created.wish_id, runId: created.run_id, url: `/runs/${created.run_id}` }; + await this.store.transaction(actor.tenantId, async tx => { + const current = await sessionAccess(tx, actor, projectId, sessionId); + const next = { + ...touch(current), + messages: current.messages.map(item => (item.id === message.id ? { ...item, wish } : item)), + }; + await tx.put('copilot_session', next); + }); + return wish; + } +} diff --git a/apps/api/src/domain/project-wiki.ts b/apps/api/src/domain/project-wiki.ts new file mode 100644 index 0000000..c16681e --- /dev/null +++ b/apps/api/src/domain/project-wiki.ts @@ -0,0 +1,101 @@ +import { DomainError, plainHttpAllowed, type Actor, type CopilotSource, type Project } from '@wishforge/contracts'; +import type { Store } from '../db/store.js'; +import { projectAccess } from './control-plane.js'; +import { requireHuman } from './policy.js'; + +export type WikiFile = { path: string; content: string }; +export type WikiSnapshot = { version: string; files: WikiFile[]; project: Project }; + +export function codeReferences(projectId: string, version: string, content: string) { + const found = new Map(); + const pattern = + /(?:^|[\s`(])((?:apps|packages|tests|infra|docs)\/[A-Za-z0-9._/-]+\.(?:tsx|ts|mjs|js|yaml|yml|json|md))(?::(\d+))?/g; + for (const match of content.matchAll(pattern)) { + const path = match[1]!; + const line = match[2] ? Number(match[2]) : undefined; + const query = new URLSearchParams({ path, version }); + found.set(`${path}:${line ?? ''}`, { + path, + ...(line ? { line } : {}), + url: `/projects/${projectId}/wiki?${query}`, + }); + } + return [...found.values()].slice(0, 12); +} + +export function wikiSources(snapshot: WikiSnapshot, files: WikiFile[]): CopilotSource[] { + return files.map(file => ({ + path: file.path, + title: file.content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? file.path, + version: snapshot.version, + url: `/projects/${snapshot.project.id}/wiki?${new URLSearchParams({ path: file.path, version: snapshot.version })}`, + excerpt: file.content + .replace(/[#*`|>\[\]]/g, ' ') + .replace(/\s+/g, ' ') + .trim() + .slice(0, 240), + references: codeReferences(snapshot.project.id, snapshot.version, file.content), + })); +} + +export class ProjectWiki { + constructor( + private store: Store, + private env = process.env, + private fetcher: typeof fetch = fetch, + ) {} + + private async project(actor: Actor, projectId: string) { + requireHuman(actor); + return this.store.read(actor.tenantId, tx => projectAccess(tx, actor, projectId)); + } + + private async readRepository(project: Project, path?: string) { + if (project.repositoryStorage !== 'platform' || project.repositoryStatus !== 'ready') + throw new DomainError('WIKI_UNAVAILABLE', 'This project has no readable platform Wiki', 503); + if (!this.env.WF_GIT_SERVICE_URL || !this.env.WF_GIT_ADMIN_TOKEN) + throw new DomainError('WIKI_UNAVAILABLE', 'Wiki storage is not configured', 503); + const base = new URL(this.env.WF_GIT_SERVICE_URL); + if (base.protocol !== 'https:' && !plainHttpAllowed(this.env, base)) + throw new DomainError('INSECURE_GIT_STORAGE', 'Wiki storage requires HTTPS', 503); + let response: Response; + try { + response = await this.fetcher(new URL('/wiki', base), { + method: 'POST', + headers: { Authorization: `Bearer ${this.env.WF_GIT_ADMIN_TOKEN}`, 'Content-Type': 'application/json' }, + body: JSON.stringify({ tenantId: project.tenantId, projectId: project.id, branch: project.targetBranch, path }), + redirect: 'error', + signal: AbortSignal.timeout(15000), + }); + } catch { + throw new DomainError('WIKI_UNAVAILABLE', 'The project Wiki cannot be read right now', 503); + } + if (!response.ok) + throw new DomainError('WIKI_UNAVAILABLE', 'The project Wiki is missing or unreadable at this revision', 503); + return response.json() as Promise<{ version: string; files?: WikiFile[]; file?: WikiFile }>; + } + + async snapshot(actor: Actor, projectId: string): Promise { + const project = await this.project(actor, projectId); + const result = await this.readRepository(project); + return { project, version: result.version, files: result.files ?? [] }; + } + + async source(actor: Actor, projectId: string, path: string, expectedVersion?: string) { + const project = await this.project(actor, projectId); + const result = await this.readRepository(project, path); + if (expectedVersion && result.version !== expectedVersion) + throw new DomainError( + 'WIKI_VERSION_CHANGED', + 'The Wiki changed; reload this source at the current revision', + 409, + ); + if (!result.file) throw new DomainError('NOT_FOUND', 'Source not found', 404); + return { + project: { id: project.id, name: project.name }, + version: result.version, + file: result.file, + references: codeReferences(project.id, result.version, result.file.content), + }; + } +} diff --git a/apps/api/src/http.ts b/apps/api/src/http.ts index 5b52b5a..32d02b1 100644 --- a/apps/api/src/http.ts +++ b/apps/api/src/http.ts @@ -53,6 +53,8 @@ import { permissionsOf } from './domain/permissions.js'; import { WishRefiner } from './domain/wish-refiner.js'; import { ModelCatalog } from './domain/model-catalog.js'; import { notificationsConfigured } from './domain/notifications.js'; +import { Copilot } from './domain/copilot.js'; +import { ProjectWiki } from './domain/project-wiki.js'; export class Services { auth: Authenticator; @@ -67,6 +69,8 @@ export class Services { accounts: LocalAccounts; refiner: WishRefiner; modelCatalog: ModelCatalog; + copilot: Copilot; + wiki: ProjectWiki; constructor(readonly control: ControlPlane) { this.auth = new Authenticator(control.store, control.env); this.releases = new Releases(control.store, control.env); @@ -80,6 +84,8 @@ export class Services { this.accounts = new LocalAccounts(control.store, control.env); this.refiner = new WishRefiner(control.store, control.env); this.modelCatalog = new ModelCatalog(control.env); + this.copilot = new Copilot(control, control.env); + this.wiki = new ProjectWiki(control.store, control.env); } } type AuthRequest = Request & { actor: Actor }; @@ -206,9 +212,10 @@ export class ApiController { }); } /** What this deployment offers, so the console shows only what works here. */ - @Get('capabilities') capabilities(@Req() req: AuthRequest) { + @Get('capabilities') async capabilities(@Req() req: AuthRequest) { return ok({ wishRefinement: this.s.refiner.available(req.actor.tenantId), + copilot: await this.s.copilot.available(req.actor.tenantId), modelCatalog: this.s.modelCatalog.available(req.actor.tenantId), localAccounts: localAccountsEnabled(this.s.control.env), notifications: notificationsConfigured(this.s.control.env), @@ -413,6 +420,40 @@ export class ApiController { ) { return ok(await this.s.refiner.refine(r.actor, id, b)); } + @Post('projects/:id/copilot/sessions') async createCopilotSession(@Req() r: AuthRequest, @Param('id') id: string) { + return ok(await this.s.copilot.createSession(r.actor, id)); + } + @Get('projects/:id/copilot/sessions/:sessionId') async copilotSession( + @Req() r: AuthRequest, + @Param('id') id: string, + @Param('sessionId') sessionId: string, + ) { + return ok(await this.s.copilot.session(r.actor, id, sessionId)); + } + @Post('projects/:id/copilot/sessions/:sessionId/messages') @HttpCode(200) async copilotMessage( + @Req() r: AuthRequest, + @Param('id') id: string, + @Param('sessionId') sessionId: string, + @Body() b: unknown, + ) { + return ok(await this.s.copilot.ask(r.actor, id, sessionId, b)); + } + @Post('projects/:id/copilot/sessions/:sessionId/wish') @HttpCode(202) async copilotWish( + @Req() r: AuthRequest, + @Param('id') id: string, + @Param('sessionId') sessionId: string, + @Body() b: unknown, + ) { + return ok(await this.s.copilot.createWish(r.actor, id, sessionId, b)); + } + @Get('projects/:id/wiki') async wikiSource( + @Req() r: AuthRequest, + @Param('id') id: string, + @Query('path') path: string, + @Query('version') version?: string, + ) { + return ok(await this.s.wiki.source(r.actor, id, z.string().min(1).max(256).parse(path), version)); + } @Post('projects/:id/wishes') @HttpCode(202) async submit( @Req() r: AuthRequest, @Param('id') id: string, diff --git a/packages/contracts/src/copilot.ts b/packages/contracts/src/copilot.ts new file mode 100644 index 0000000..48292a2 --- /dev/null +++ b/packages/contracts/src/copilot.ts @@ -0,0 +1,57 @@ +import { z } from 'zod'; +import type { Entity } from './index.js'; + +export type CopilotSource = { + path: string; + title: string; + version: string; + url: string; + excerpt: string; + references: { path: string; line?: number; url: string }[]; +}; +export type CopilotQuestion = { + question: string; + sourcePath: string; + options: { label: string; wish: string; acceptanceCriterion?: string }[]; +}; +export type CopilotMessage = { + id: string; + role: 'user' | 'assistant'; + content: string; + clientId?: string; + status: 'complete' | 'pending' | 'error'; + createdAt: string; + kind?: 'faq' | 'bug' | 'feature' | 'unknown'; + sources?: CopilotSource[]; + knowledgeVersion?: string; + goal?: string; + acceptanceCriteria?: string[]; + reproductionSteps?: string[]; + contextSummary?: string; + questions?: CopilotQuestion[]; + wish?: { wishId: string; runId: string; url: string }; +}; +export interface CopilotSession extends Entity { + projectId: string; + userId: string; + messages: CopilotMessage[]; +} + +export const copilotMessageInput = z + .object({ + content: z.string().trim().min(1).max(8000), + clientId: z.string().trim().min(8).max(200), + context: z + .object({ pathname: z.string().max(1000).optional(), runId: z.string().max(200).optional() }) + .strict() + .optional(), + }) + .strict(); +export const copilotWishInput = z + .object({ + messageId: z.string().min(1).max(200), + goal: z.string().trim().min(8).max(20000), + acceptanceCriteria: z.array(z.string().trim().min(1).max(2000)).min(1).max(30), + answers: z.array(z.string().trim().min(1).max(1000)).max(12).default([]), + }) + .strict(); diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 5d60781..9d4f64a 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -1,4 +1,5 @@ import { pocReleaseInput, type PocReleaseSet } from './poc-delivery.js'; +export * from './copilot.js'; export { pocReleaseInput, pocTargetImage, @@ -69,7 +70,8 @@ export type EntityKind = | 'local_account' | 'notification' | 'skill' - | 'skill_harvest'; + | 'skill_harvest' + | 'copilot_session'; export interface Entity { id: string; tenantId: string; diff --git a/tests/copilot.test.ts b/tests/copilot.test.ts new file mode 100644 index 0000000..84374ef --- /dev/null +++ b/tests/copilot.test.ts @@ -0,0 +1,234 @@ +import { beforeEach, describe, expect, it } from 'vitest'; +import type { Actor, CopilotSession, Wish } from '@wishforge/contracts'; +import { ControlPlane } from '../apps/api/src/domain/control-plane.js'; +import { Copilot } from '../apps/api/src/domain/copilot.js'; +import { Connections } from '../apps/api/src/domain/connections.js'; +import { ProjectWiki } from '../apps/api/src/domain/project-wiki.js'; +import { ApiController, Services } from '../apps/api/src/http.js'; +import { MemoryStore } from './helpers/memory-store.js'; + +const owner: Actor = { tenantId: 'demo', userId: 'owner', role: 'owner', kind: 'human' }; +const env = { + NODE_ENV: 'test', + WF_DEPLOYMENT_MODE: 'development', + WF_PROVISIONER_BACKEND: 'local', + WF_TENANT_ID: 'demo', + WF_CLAUDE_BIN: '/usr/local/bin/claude', + WF_CLAUDE_LOCAL_AUTH_HOME: '/Users/operator', +}; +let store: MemoryStore, + control: ControlPlane, + projectId: string, + snapshot: Awaited>; +const files = [ + { path: 'wiki/index.md', content: '# WishForge Wiki\n从模块地图找到代码入口。' }, + { + path: 'wiki/features/wishes.md', + content: '# 提交 Wish\n填写目标和验收标准。\n依据 `apps/web/src/features/runs.tsx:416`。', + }, +]; +beforeEach(async () => { + store = new MemoryStore(); + store.seed('demo'); + control = new ControlPlane(store, env); + snapshot = await control.createProject(owner, { name: 'Pilot', repositoryUrl: 'https://example.org/pilot.git' }); + projectId = snapshot.id; +}); +const wiki = { + snapshot: async () => ({ project: snapshot, version: 'a'.repeat(40), files }), +}; +const input = (content: string) => ({ + content, + clientId: `client-${content.length}-abcdef`, + context: { pathname: '/projects/demo' }, +}); +function copilot(answer: (question: string) => unknown) { + return new Copilot(control, env, async request => answer(JSON.parse(request.prompt).question), wiki); +} + +describe('project Copilot API', () => { + it('answers FAQ from a versioned Wiki without creating a Wish and recovers its session', async () => { + const service = copilot(() => ({ kind: 'faq', answer: '填写目标和验收标准后提交。' })); + const session = await service.createSession(owner, projectId); + const answered = await service.ask(owner, projectId, session.id, input('如何提交 Wish?')); + const assistant = answered.messages[1]!; + expect(assistant).toMatchObject({ kind: 'faq', status: 'complete', knowledgeVersion: 'a'.repeat(40) }); + expect(assistant.sources?.[0]).toMatchObject({ path: 'wiki/features/wishes.md' }); + expect(assistant.sources?.[0].references[0]).toMatchObject({ path: 'apps/web/src/features/runs.tsx', line: 416 }); + expect((await service.session(owner, projectId, session.id)).messages).toHaveLength(2); + expect(await store.read('demo', tx => tx.list('wish'))).toHaveLength(0); + }); + + it('turns only a confirmed Bug draft into a real Wish, idempotently', async () => { + const service = copilot(() => ({ + kind: 'bug', + answer: '这是一个疑似提交异常,需要进一步复现。', + goal: '修复提交 Wish 时的异常。', + acceptanceCriteria: ['重复提交不会丢失已填写内容'], + reproductionSteps: ['打开提交页', '点击提交'], + contextSummary: '当前位于项目页面。', + })); + const session = await service.createSession(owner, projectId); + const answered = await service.ask(owner, projectId, session.id, input('提交时总是报错')); + const message = answered.messages[1]!; + expect(message).toMatchObject({ kind: 'bug', reproductionSteps: ['打开提交页', '点击提交'] }); + const draft = { + messageId: message.id, + goal: message.goal!, + acceptanceCriteria: message.acceptanceCriteria!, + answers: [], + }; + const first = await service.createWish(owner, projectId, session.id, draft); + const second = await service.createWish(owner, projectId, session.id, draft); + expect(second).toEqual(first); + expect(first.url).toBe(`/runs/${first.runId}`); + expect(await store.read('demo', tx => tx.list('wish'))).toHaveLength(1); + }); + + it('puts Wiki-grounded Grill-me answers into the goal and acceptance criteria', async () => { + const service = copilot(() => ({ + kind: 'feature', + answer: '需求可以先明确导出范围。', + goal: '为项目增加报告导出。\n不改:现有权限。', + acceptanceCriteria: ['可以导出报告'], + questions: [ + { + question: '导出什么格式?', + sourcePath: 'wiki/features/wishes.md', + options: [ + { label: 'Markdown', wish: '导出 Markdown。', acceptanceCriterion: '下载内容是 Markdown' }, + { label: 'PDF', wish: '导出 PDF。', acceptanceCriterion: '下载内容是 PDF' }, + ], + }, + ], + })); + const session = await service.createSession(owner, projectId); + const answered = await service.ask(owner, projectId, session.id, input('我要导出 Wish 报告')); + const message = answered.messages[1]!; + expect(message.questions?.[0].sourcePath).toBe('wiki/features/wishes.md'); + const created = await service.createWish(owner, projectId, session.id, { + messageId: message.id, + goal: message.goal!, + acceptanceCriteria: [...message.acceptanceCriteria!, '下载内容是 Markdown'], + answers: ['导出 Markdown。'], + }); + const wish = await store.read('demo', tx => tx.get('wish', created.wishId)); + expect(wish?.goal).toContain('导出 Markdown。'); + expect(wish?.goal.indexOf('导出 Markdown。')).toBeLessThan(wish?.goal.indexOf('不改:') ?? -1); + expect(wish?.acceptanceCriteria).toContain('下载内容是 Markdown'); + }); + + it('falls back to the server-held tenant Claude credential in development', async () => { + const secureEnv = { ...env, WF_VAULT_KEY: 'a'.repeat(64) }; + await new Connections(store, secureEnv).create(owner, { + provider: 'claude-code', + label: 'test', + apiKey: 'tenant-fixture-key', + }); + const credentials: (Record | undefined)[] = []; + const service = new Copilot( + control, + secureEnv, + async request => { + credentials.push(request.credentialEnv); + if (!request.credentialEnv) throw new Error('native login disabled'); + return { kind: 'faq', answer: '由租户凭据完成的有源回答。' }; + }, + wiki, + ); + const session = await service.createSession(owner, projectId); + const answered = await service.ask(owner, projectId, session.id, input('如何提交 Wish')); + expect(answered.messages[1]).toMatchObject({ status: 'complete', kind: 'faq' }); + expect(credentials).toHaveLength(2); + expect(credentials[0]).toBeUndefined(); + expect(credentials[1]).toMatchObject({ ANTHROPIC_API_KEY: 'tenant-fixture-key' }); + const production = new Copilot(control, { ...secureEnv, WF_DEPLOYMENT_MODE: 'production' }, async () => ({}), wiki); + expect(await production.available('demo')).toBe(false); + }); + + it('admits unknown answers, rejects cross-user sessions and persists model failures', async () => { + const unknown = copilot(() => ({ + kind: 'unknown', + answer: '当前 Wiki 没有足够依据。', + sources: [{ path: 'fake' }], + })); + const session = await unknown.createSession(owner, projectId); + const answered = await unknown.ask(owner, projectId, session.id, input('火星环境怎么配置')); + expect(answered.messages[1]).toMatchObject({ kind: 'unknown', sources: [] }); + const other: Actor = { ...owner, userId: 'other' }; + await expect(unknown.session(other, projectId, session.id)).rejects.toMatchObject({ code: 'NOT_FOUND' }); + const failing = new Copilot( + control, + env, + async () => { + throw new Error('model offline'); + }, + wiki, + ); + const failedSession = await failing.createSession(owner, projectId); + await expect(failing.ask(owner, projectId, failedSession.id, input('模型现在可用吗'))).rejects.toMatchObject({ + code: 'COPILOT_FAILED', + }); + expect((await failing.session(owner, projectId, failedSession.id)).messages[1]).toMatchObject({ status: 'error' }); + const unavailable = new Copilot(control, { ...env, WF_DEPLOYMENT_MODE: 'production' }, async () => ({}), wiki); + await expect(unavailable.createSession(owner, projectId)).resolves.toBeDefined(); + await expect(unavailable.ask(owner, projectId, session.id, input('还能回答吗'))).rejects.toMatchObject({ + code: 'COPILOT_UNAVAILABLE', + }); + }); + + it('marks an orphaned pending answer as interrupted so a new question can be sent', async () => { + const service = copilot(() => ({ kind: 'unknown', answer: '不知道' })); + const created = await service.createSession(owner, projectId); + await service.ask(owner, projectId, created.id, input('中断恢复')); + await store.transaction('demo', async tx => { + const current = (await tx.get('copilot_session', created.id))!; + await tx.put('copilot_session', { + ...current, + messages: current.messages.map(message => + message.role === 'assistant' + ? { ...message, status: 'pending', createdAt: new Date(Date.now() - 211_000).toISOString() } + : message, + ), + }); + }); + expect((await service.session(owner, projectId, created.id)).messages[1]).toMatchObject({ + status: 'error', + content: expect.stringContaining('中断'), + }); + }); + + it('exposes the recoverable session and Wiki version through the HTTP controller', async () => { + const services = new Services(control); + services.copilot = copilot(() => ({ kind: 'faq', answer: '从 Wiki 提交入口操作。' })); + const api = new ApiController(services); + const created = await api.createCopilotSession({ actor: owner } as never, projectId); + const session = (created as { data: CopilotSession }).data; + const answered = await api.copilotMessage({ actor: owner } as never, projectId, session.id, input('Wish 入口在哪')); + expect((answered as { data: CopilotSession }).data.messages[1]).toMatchObject({ + kind: 'faq', + knowledgeVersion: 'a'.repeat(40), + }); + }); + + it('enforces project access and rejects a stale Wiki version at the source API', async () => { + await store.transaction('demo', async tx => { + await tx.put('project', { ...snapshot, repositoryStorage: 'platform', repositoryStatus: 'ready' }); + }); + const service = new ProjectWiki( + store, + { ...env, WF_GIT_SERVICE_URL: 'https://git.example', WF_GIT_ADMIN_TOKEN: 'server-side-fixture' }, + async () => + new Response(JSON.stringify({ version: 'b'.repeat(40), file: { path: 'wiki/index.md', content: '# Wiki' } }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }), + ); + await expect(service.source(owner, projectId, 'wiki/index.md', 'a'.repeat(40))).rejects.toMatchObject({ + code: 'WIKI_VERSION_CHANGED', + status: 409, + }); + const other: Actor = { ...owner, userId: 'other', role: 'viewer' }; + await expect(service.source(other, projectId, 'wiki/index.md')).rejects.toMatchObject({ code: 'NOT_FOUND' }); + }); +}); From 4118e30872fdd01a5c1a55abccb4f45453f25e2f Mon Sep 17 00:00:00 2001 From: wishforge Date: Sun, 8 Nov 2026 22:36:27 -0800 Subject: [PATCH 12/46] =?UTF-8?q?=E2=9C=A8=20Add=20the=20Copilot=20sidebar?= =?UTF-8?q?,=20Wiki=20source=20page,=20and=20browser=20acceptance=20script?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../app/(console)/projects/[id]/wiki/page.tsx | 14 + apps/web/src/app/api/[...path]/route.ts | 5 +- apps/web/src/app/globals.css | 300 ++++++++++++++ apps/web/src/components/console-shell.tsx | 19 +- apps/web/src/features/copilot.tsx | 376 ++++++++++++++++++ apps/web/src/features/wiki-source.tsx | 60 +++ docs/copilot.md | 37 ++ scripts/copilot-e2e.mjs | 107 +++++ 8 files changed, 915 insertions(+), 3 deletions(-) create mode 100644 apps/web/src/app/(console)/projects/[id]/wiki/page.tsx create mode 100644 apps/web/src/features/copilot.tsx create mode 100644 apps/web/src/features/wiki-source.tsx create mode 100644 docs/copilot.md create mode 100644 scripts/copilot-e2e.mjs diff --git a/apps/web/src/app/(console)/projects/[id]/wiki/page.tsx b/apps/web/src/app/(console)/projects/[id]/wiki/page.tsx new file mode 100644 index 0000000..375dfe9 --- /dev/null +++ b/apps/web/src/app/(console)/projects/[id]/wiki/page.tsx @@ -0,0 +1,14 @@ +import { WikiSourceView } from '@/features/wiki-source'; + +export default async function WikiPage({ + params, + searchParams, +}: { + params: Promise<{ id: string }>; + searchParams: Promise<{ path?: string; version?: string }>; +}) { + const { id } = await params; + const query = await searchParams; + if (!query.path) return

缺少要读取的 Wiki 页面路径。

; + return ; +} diff --git a/apps/web/src/app/api/[...path]/route.ts b/apps/web/src/app/api/[...path]/route.ts index 8c37b7c..edf166a 100644 --- a/apps/web/src/app/api/[...path]/route.ts +++ b/apps/web/src/app/api/[...path]/route.ts @@ -41,8 +41,9 @@ async function proxy(request: NextRequest, context: Context) { if (value) headers.set(key, value); } const stream = path.at(-1) === 'stream'; - // Two model attempts, 180 s each, plus a margin so the proxy does not cut the fallback short. - const timeout = path.at(-1) === 'wish-refinements' ? 400_000 : 30_000; + // Model routes need enough time for their configured attempts; other control calls stay short. + const route = path.at(-1); + const timeout = route === 'messages' ? 700_000 : route === 'wish-refinements' ? 400_000 : 30_000; try { const upstream = await fetch(url, { method: request.method, diff --git a/apps/web/src/app/globals.css b/apps/web/src/app/globals.css index dcb49d4..b1e6135 100644 --- a/apps/web/src/app/globals.css +++ b/apps/web/src/app/globals.css @@ -3278,3 +3278,303 @@ fieldset:disabled label { break-inside: auto; } } + +.copilot-toggle { + display: inline-flex; + align-items: center; + gap: 7px; + min-height: 34px; + padding: 5px 10px; + border: 1px solid var(--border); + border-radius: 6px; + color: var(--teal-dark); + background: white; + white-space: nowrap; +} +.copilot-toggle.active, +.copilot-toggle:hover { + background: var(--teal-pale); + border-color: #b8dcd3; +} +.copilot-sidebar { + position: fixed; + inset: 0 0 0 auto; + width: 400px; + max-width: 100vw; + z-index: 45; + display: flex; + flex-direction: column; + background: #fbfcfe; + border-left: 1px solid var(--border); + box-shadow: -8px 0 28px #1020310a; + transform: translateX(100%); + visibility: hidden; + transition: transform 0.18s ease; +} +.copilot-sidebar.is-open { + transform: translateX(0); + visibility: visible; +} +.copilot-header { + min-height: 65px; + display: flex; + align-items: center; + justify-content: space-between; + padding: 12px 16px; + border-bottom: 1px solid var(--border); + background: white; +} +.copilot-header > div, +.copilot-header span { + display: flex; + align-items: center; + gap: 10px; +} +.copilot-header span { + align-items: flex-start; + flex-direction: column; + gap: 0; +} +.copilot-header small { + color: var(--muted); +} +.copilot-project { + display: flex; + gap: 8px; + padding: 12px 14px; + border-bottom: 1px solid var(--border); +} +.copilot-project select { + min-width: 0; + flex: 1; +} +.copilot-messages { + flex: 1; + min-height: 0; + overflow-y: auto; + padding: 16px 14px; +} +.copilot-welcome { + text-align: center; + color: var(--muted); + padding: 38px 20px; +} +.copilot-welcome svg { + color: var(--teal); + margin-bottom: 12px; +} +.copilot-welcome h2 { + color: var(--ink); + margin-bottom: 8px; +} +.copilot-message { + margin-bottom: 16px; + overflow-wrap: anywhere; +} +.copilot-message.user { + display: flex; + justify-content: flex-end; +} +.copilot-message.user span { + max-width: 90%; + padding: 9px 12px; + background: var(--teal-pale); + border-radius: 10px 10px 2px 10px; + white-space: pre-wrap; +} +.copilot-message.assistant { + padding: 12px; + background: white; + border: 1px solid var(--border); + border-radius: 8px; +} +.copilot-message.error { + border-color: #e8bfc2; +} +.copilot-answer { + white-space: pre-wrap; + margin-bottom: 10px; +} +.copilot-kind { + display: inline-flex; + align-items: center; + gap: 5px; + padding: 2px 7px; + border-radius: 12px; + background: #eef2f6; + color: #42546a; + font-size: 11px; +} +.copilot-kind.bug { + background: #fff0f0; + color: #9d343c; +} +.copilot-kind.feature { + background: var(--teal-pale); + color: var(--teal-dark); +} +.copilot-sources { + margin: 12px 0; + padding: 10px; + background: #f6f8fb; + border-radius: 6px; +} +.copilot-source { + padding: 7px 0; + border-top: 1px solid var(--border); +} +.copilot-source > a, +.copilot-code-link { + display: inline-flex; + align-items: center; + gap: 4px; + color: var(--teal-dark); +} +.copilot-source small { + display: block; + color: var(--muted); +} +.copilot-code-link { + margin: 4px 10px 0 0; + font-family: 'SFMono-Regular', Consolas, monospace; + font-size: 10px; +} +.copilot-wish-draft { + display: grid; + gap: 12px; + margin-top: 12px; +} +.copilot-wish-draft label { + display: grid; + gap: 5px; + font-size: 12px; + font-weight: 600; +} +.copilot-wish-draft textarea { + font-weight: 400; + width: 100%; +} +.copilot-bug-context { + padding: 10px; + background: #fff8f2; + border-radius: 6px; +} +.copilot-bug-context ol { + padding-left: 20px; + margin: 5px 0 10px; +} +.grill-card { + border: 1px solid #c9ded9; + border-radius: 7px; + padding: 10px; + margin: 0; +} +.grill-card legend { + padding: 0 5px; + font-weight: 600; +} +.grill-card > small { + display: block; + color: var(--muted); + margin-bottom: 8px; +} +.grill-card > div { + display: flex; + flex-wrap: wrap; + gap: 7px; +} +.grill-card button { + border: 1px solid var(--border); + background: white; + border-radius: 5px; + padding: 5px 9px; +} +.grill-card button.selected { + border-color: var(--teal); + background: var(--teal-pale); + color: var(--teal-dark); +} +.copilot-wish-link { + justify-content: center; +} +.copilot-composer { + padding: 12px 14px 14px; + border-top: 1px solid var(--border); + background: white; +} +.copilot-composer textarea { + width: 100%; + min-height: 72px; + max-height: 180px; +} +.copilot-composer > div { + display: flex; + align-items: center; + justify-content: space-between; + gap: 8px; + margin-top: 8px; +} +.copilot-composer small { + color: var(--muted); +} +.copilot-error { + color: var(--red); + margin-top: 8px; +} +.wiki-source { + background: white; + border: 1px solid var(--border); + border-radius: var(--radius); + overflow: hidden; +} +.wiki-source > pre { + margin: 0; + padding: 24px; + white-space: pre-wrap; + overflow-wrap: anywhere; + line-height: 1.75; +} +.wiki-source footer { + padding: 18px 24px; + border-top: 1px solid var(--border); + background: #f8fafc; +} +.wiki-source footer div { + display: flex; + flex-direction: column; + gap: 6px; + margin-top: 8px; +} +.wiki-source footer a { + color: var(--teal-dark); + font-family: 'SFMono-Regular', Consolas, monospace; + font-size: 12px; +} +@media (min-width: 1101px) { + .console.copilot-open .main-shell { + margin-right: 400px; + } + .console.copilot-open .main-content { + padding-left: 22px; + padding-right: 22px; + } +} +@media (max-width: 1100px) { + .copilot-sidebar { + box-shadow: -12px 0 40px #10203126; + } +} +@media (max-width: 760px) { + .copilot-toggle { + padding: 5px 7px; + } + .copilot-toggle svg { + margin: 0; + } + .topbar-actions { + gap: 8px; + } + .copilot-sidebar { + width: 100vw; + } +} diff --git a/apps/web/src/components/console-shell.tsx b/apps/web/src/components/console-shell.tsx index 6f7b8ba..8187481 100644 --- a/apps/web/src/components/console-shell.tsx +++ b/apps/web/src/components/console-shell.tsx @@ -22,6 +22,7 @@ import { useEffect, useState } from 'react'; import { useSWRConfig } from 'swr'; import type { ReactNode } from 'react'; import { useResource } from '@/lib/api'; +import { CopilotSidebar } from '@/features/copilot'; const navigation = [ ['/', '工作概览', Home], @@ -36,6 +37,14 @@ const navigation = [ export function ConsoleShell({ children }: { children: ReactNode }) { const pathname = usePathname(); const [open, setOpen] = useState(false); + const [copilotOpen, setCopilotOpen] = useState(false); + useEffect(() => setCopilotOpen(localStorage.getItem('wishforge.copilot.open') !== 'false'), []); + const toggleCopilot = () => { + setCopilotOpen(current => { + localStorage.setItem('wishforge.copilot.open', String(!current)); + return !current; + }); + }; // Below 760 px the navigation is a drawer: closed, its links leave the tab order; Esc closes it. const [narrow, setNarrow] = useState(false); useEffect(() => { @@ -61,7 +70,7 @@ export function ConsoleShell({ children }: { children: ReactNode }) { }>('/session'); const current = navigation.find(([href]) => (href === '/' ? pathname === '/' : pathname.startsWith(href))); return ( -
+
跳转到主要内容 @@ -127,6 +136,13 @@ export function ConsoleShell({ children }: { children: ReactNode }) { )} +
+
); } diff --git a/apps/web/src/features/copilot.tsx b/apps/web/src/features/copilot.tsx new file mode 100644 index 0000000..7c0e4e8 --- /dev/null +++ b/apps/web/src/features/copilot.tsx @@ -0,0 +1,376 @@ +'use client'; +import { BookOpen, Bot, Bug, ExternalLink, Lightbulb, Plus, Send, X } from 'lucide-react'; +import Link from 'next/link'; +import { usePathname } from 'next/navigation'; +import { useEffect, useState } from 'react'; +import { useSWRConfig } from 'swr'; +import { withAnswers } from '@wishforge/contracts/wish'; +import type { CopilotMessage, CopilotSession } from '@wishforge/contracts'; +import { api, messageOf, mutateApi, useResource } from '@/lib/api'; +import { browserId } from '@/lib/browser-id'; +import type { Project } from '@/lib/types'; +import { Button, ErrorNotice, Notice } from '@/components/ui'; + +const kindLabels = { faq: 'FAQ / 配置', bug: '疑似 Bug', feature: '需求', unknown: '依据不足' } as const; +const sessionKey = (projectId: string) => `wishforge.copilot.session.${projectId}`; + +function Sources({ message }: { message: CopilotMessage }) { + if (!message.sources?.length) return null; + return ( +
+ 依据 · Wiki {message.knowledgeVersion?.slice(0, 8)} + {message.sources.map(source => ( +
+ + {source.title} + + {source.path} + {source.references.slice(0, 3).map(reference => ( + + {reference.path} + {reference.line ? `:${reference.line}` : ''} + + ))} +
+ ))} +
+ ); +} + +function WishDraft({ + message, + projectId, + sessionId, + onCreated, +}: { + message: CopilotMessage; + projectId: string; + sessionId: string; + onCreated: () => void; +}) { + const baseGoal = message.goal ?? ''; + const baseCriteria = message.acceptanceCriteria ?? []; + const [goal, setGoal] = useState(baseGoal); + const [criteria, setCriteria] = useState(baseCriteria.join('\n')); + const [selected, setSelected] = useState>({}); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(''); + const [created, setCreated] = useState(message.wish); + const choose = (questionIndex: number, optionIndex: number) => { + const next = { ...selected, [questionIndex]: optionIndex }; + setSelected(next); + const answers = (message.questions ?? []) + .map((question, index) => question.options[next[index] ?? -1]?.wish ?? '') + .filter(Boolean); + setGoal(withAnswers(baseGoal, answers)); + const additions = (message.questions ?? []) + .map((question, index) => question.options[next[index] ?? -1]?.acceptanceCriterion) + .filter((value): value is string => Boolean(value)); + setCriteria([...baseCriteria, ...additions].join('\n')); + }; + const submit = async () => { + if (busy || created) return; + setBusy(true); + setError(''); + try { + const wish = await mutateApi<{ wishId: string; runId: string; url: string }>( + `/projects/${projectId}/copilot/sessions/${sessionId}/wish`, + { + messageId: message.id, + goal: goal.trim(), + acceptanceCriteria: criteria + .split('\n') + .map(line => line.trim()) + .filter(Boolean), + answers: [], + }, + 'POST', + `copilot-wish:${sessionId}:${message.id}`, + ); + setCreated(wish); + onCreated(); + } catch (failure) { + setError(messageOf(failure)); + } finally { + setBusy(false); + } + }; + return ( +
+ {message.kind === 'bug' ? ( +
+ 复现信息 + {message.reproductionSteps?.length ? ( +
    + {message.reproductionSteps.map(step => ( +
  1. {step}
  2. + ))} +
+ ) : ( +

尚未提供复现步骤,请在 Wish 中补充。

+ )} + 当前上下文 +

{message.contextSummary || '未提供额外上下文。'}

+
+ ) : null} + {message.questions?.map((question, questionIndex) => ( +
+ Grill me · {question.question} + 依据 {question.sourcePath} +
+ {question.options.map((option, optionIndex) => ( + + ))} +
+
+ ))} +