wishforge-ide/docs/wishforge-summary.md

231 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# WishForge 深度综合指南:系统架构、使用手册与工程实践
---
## 目录
- [一、核心设计哲学与技术世界观](#一核心设计哲学与技术世界观)
- [1. 理解模型的能力边界,比知道哪个模型排名第一更重要](#1-理解模型的能力边界比知道哪个模型排名第一更重要)
- [2. Superagent 最大的竞争对手,是下一代基础模型](#2-superagent-最大的竞争对手是下一代基础模型)
- [3. 会做规划不代表会执行,会执行不代表会验收](#3-会做规划不代表会执行会执行不代表会验收)
- [4. 多一个验收 Agent,不等于多一份独立判断](#4-多一个验收-agent不等于多一份独立判断)
- [5. Agent 架构的进步,应该包括删掉多少东西](#5-agent-架构的进步应该包括删掉多少东西)
- [6. 模型会吞噬哪些工程?哪些工程具有不可替代的独立价值?](#6-模型会吞噬哪些工程哪些工程具有不可替代的独立价值)
- [二、简明使用与操作手册](#二简明使用与操作手册)
- [1. 访问与登录权限体系](#1-访问与登录权限体系)
- [2. 愿望提交与最佳工程实践](#2-愿望提交与最佳工程实践)
- [3. 智能模型选择与动态模型获取](#3-智能模型选择与动态模型获取)
- [4. 流水线跟进、异常解除与人工把关](#4-流水线跟进异常解除与人工把关)
- [5. 故障回滚与愿望撤销](#5-故障回滚与愿望撤销)
- [三、系统架构与内部设计](#三系统架构与内部设计)
- [1. 总体架构拓扑图](#1-总体架构拓扑图)
- [2. 关键组件与职责划分](#2-关键组件与职责划分)
- [3. 八阶段严密交付流水线](#3-八阶段严密交付流水线)
- [4. 物理隔离与“验证器独立裁决”机制](#4-物理隔离与验证器独立裁决机制)
- [5. 状态机驱动与所有等待均有出口](#5-状态机驱动与所有等待均有出口)
- [四、高频实战 QA 与故障诊断](#四高频实战-qa-与故障诊断)
- [Q1: 为什么任务经常停在「等待处理」?流程卡死了吗?](#q1-为什么任务经常停在等待处理流程卡死了吗)
- [Q2: 执行器报错「CLI output exceeded 16 MiB」是什么根因?如何处理?](#q2-执行器报错cli-output-exceeded-16-mib是什么根因如何处理)
- [Q3: 合入阶段提示「Gitea: Deploy Key ... is not authorized to write」怎么处理?](#q3-合入阶段提示gitea-deploy-key--is-not-authorized-to-write怎么处理)
- [Q4: 提交愿望时点击「AI 优化愿望」出现 502 或超时怎么解决?](#q4-提交愿望时点击ai-优化愿望出现-502-或超时怎么解决)
- [Q5: 运行已经全部取消了,为什么概览页的「待确认」数字依然大于 0?](#q5-运行已经全部取消了为什么概览页的待确认数字依然大于-0)
- [Q6: 可用模型为什么由原来的手输文本框改成了下拉勾选与动态拉取?](#q6-可用模型为什么由原来的手输文本框改成了下拉勾选与动态拉取)
---
## 一、核心设计哲学与技术世界观
WishForge 在设计之初并未将自己定位为一个“聊天玩具”,而是定位为**生产级软件工程自动化交付系统**。在与各类大模型深度集成的演化过程中,平台沉淀了 6 个贯穿始终的架构与模型哲学思想:
### 1. 理解模型的能力边界,比知道哪个模型排名第一更重要
模型能力不是一个抽象的综合跑分,必须按具体工程任务切片来看:
- **横向领域**:前端组件渲染、后端复杂业务逻辑、数据建模、纯文本问答;
- **纵向环节**:意图澄清(Clarify)、架构规划(Plan)、代码实现(Implement)、调试修复(Debug)、物理验收(Verify)。
同一个模型,在不同环节的可靠性可能天差地别。例如:大参数模型(如 `deepseek-pro`)具备强大的上下文逻辑推理能力,但在写高约束的极简 JSON 结构化输出时,推理耗时长且极易打穿连接超时;而轻量模型(如 `deepseek-flash`)在文本重构与意图提炼上响应极为迅敏,却可能在复杂后端并发控制上出现幻觉。
> **架构切口**:真正懂 AI 工程化的团队,不是盲目追求 Benchmark 第一的模型,而是清楚知道**在流水线的哪一步停止相信当前模型,以及下一步由谁接盘**。
### 2. Superagent 最大的竞争对手,是下一代基础模型
在当前技术热潮中,许多团队致力于在应用层堆砌极其繁复的任务拆解图、反复递归的反思循环(Reflection Loop)以及纷繁复杂的多角色辩论机制。但必须保持警惕:**如果这套复杂机制主要是在弥补当前模型的认知不足或注意力涣散,那么当下一代基础模型原生具备长程思考能力时,这些复杂的应用层代码将在顷刻间沦为技术负债。**
> **架构切口**:不要把模型“暂时的认知缺陷”当成了系统的“永久架构需求”。WishForge 绝不在 Agent 内部堆叠脆弱的虚假抽象,而专注于不可被模型吞噬的基础设施。
### 3. 会做规划不代表会执行,会执行不代表会验收
- **规划能力**需要提炼关键约束与依赖拓扑;
- **执行能力**需要严谨、持续、不走样地把代码敲进文件;
- **验收能力**需要极具对抗性地寻找反例、挑刺、挖掘边界崩溃点。
行业普遍习惯让“同一个模型”包揽“提需求 $\rightarrow$ 做规划 $\rightarrow$ 写代码 $\rightarrow$ 自测验收”全过程,这违背了基本的软件质量工程规范。一个模型在规划阶段夸夸其谈写出完美的方案文档,在编码时可能依然会犯低级语法错误,而在自测时更会对自己编写的错误视而不见。
> **架构切口**:“方案写得好”与“能把事情做好”之间隔着深渊;而“把代码写出来”与“代码能物理运行通过”更是两套完全异构的能力。
### 4. 多一个验收 Agent,不等于多一份独立判断
很多系统喜欢引入所谓的“评审 Agent”或“裁判模型”来进行代码审查。但本质上:**如果执行 Agent 与审查 Agent 来自同源模型、基于同一套上下文、共享同样的认知盲点,那么审查 Agent 大概率只会谄媚地附和执行者的错误。**
> **架构切口**:三个 Agent 一致点头同意,有时只是同一个错误获得了三票。在 WishForge 中,**验收绝不依赖另一个模型口头说“没问题”,而必须依靠干净沙箱中的物理编译器、真实单元测试、集成构建与网络探针作为唯一法定证据。**
### 5. Agent 架构的进步,应该包括删掉多少东西
伴随底层模型能力(如推理模型与超大上下文)的演进,架构师应该持续做减法:
- 曾经需要拆分成 10 步的微操任务,现在能否直接交给模型一步完成?
- 曾经繁冗的 Prompt 约束,能否随着遵循能力的提升而精简?
WishForge 坚信:优秀的系统架构应当具备**“模型变强,系统反而变简单”**的伸缩性,系统进化的衡量标准之一,就是能够在升级模型后平滑剔除多余的胶水代码与冗余控制。
### 6. 模型会吞噬哪些工程?哪些工程具有不可替代的独立价值?
在系统分工上,WishForge 明确区分两类工程:
1. **认知补偿型工程**:如上下文拼接、Prompt 词法雕琢、手工任务微拆、思维链诱导。这类工程极易被下一代更聪明的模型直接吞噬和降维打击。
2. **现实世界约束型工程**:如租户鉴权与访问控制(RBAC)、事务原子性与一致性保证、不可篡改证据存证(Audit Proof)、外部系统连接器、环境隔离沙箱、蓝绿部署与故障物理回滚。无论模型未来进化到何等高度,现实世界的物理边界、资产安全与业务审查永不会自动解决。
WishForge 的所有重度投入,全部集中在第二类工程中。
---
## 二、简明使用与操作手册
### 1. 访问与登录权限体系
- **访问入口**:访问平台公网入口 `https://wishforge.d-robotics.cc`(或内网解析地址)。
- **权限角色(RBAC)**:
- **管理员 (admin/owner)**:管理项目、查看全平台审计、配置目标分支与验收脚本、审批敏感发布。
- **全栈开发 (developer - full)**:可提交影响前端和后端的全量愿望,验证通过后直接合入。
- **后端需审核开发 (developer - reviewed)**:可许愿修改全量代码,但若改动涉及“后端代码路径”,验证通过后会自动拦截进入「等待代码审核」,必须由管理员在 Diff 界面确认后才合入。
- **前端开发 (developer - frontend)**:只能提交前端代码改动。即使 Agent 误改了后端文件,平台也会在合入前强制还原后端变更。
- **发布负责人 (deployer) / 访客 (viewer)**:专注于审批部署或只读查看进度。
### 2. 愿望提交与最佳工程实践
1. **进入新建页**:在仪表盘或运行记录页点击 **「+ 提交愿望」**。
2. **精准表达愿望(三段式黄金原则)**:
- 第一行(目标):一句话说明要做什么(如:*“在项目设置中增加可用模型下拉勾选”*)。
- 第二行(范围):以 `范围:` 开头,指出涉及的模块、页面或文件。
- 第三行(不改):以 `不改:` 开头,指明绝对不可破坏的接口契约或业务数据。
3. **编写验收标准(Acceptance Criteria)**:
- 必须是**客观、明确、自动化脚本可判定的断言**(如:*“单元测试覆盖新增组件”、“TypeScript 检查无报错”、“现有构建正常完成”*)。
- 避免主观感受词汇(如:“性能明显变好”、“代码看起来整洁”)。
4. **一键 AI 智能改写**:
- 若不确定如何规范编写,点击下方的 **「AI 优化愿望」**。
- 系统将调用高响应模型,结合项目特有的规约规则,将其自动整理为工业级规范草案。
### 3. 智能模型选择与动态模型获取
- **默认模型策略**:项目默认优先选用经过深度验证的 `deepseek-flash@latest`,在确保推理精度的同时最大化响应速度与节省 Token 额度。
- **获取最新模型**:
- 项目管理员进入 **「项目空间 $\rightarrow$ 项目设置」**;
- 展开「可用模型」下拉框,点击 **「获取模型」** 按钮;
- 系统后端会通过受保护的通道直连模型网关 `/v1/models`,实时拉取并展示当前支持的所有模型清单;
- 管理员勾选需要启用的模型并保存,许愿者即可在提交页自由切换。
### 4. 流水线跟进、异常解除与人工把关
- **流水线推进**:运行建立后,系统进入 8 阶段流水线。用户可实时查看阶段推进、模型流式输出日志及生成的文件 Diff。
- **处理「等待处理(waiting)」**:
- 若由于外部网络、密钥过期、环境中断触发等待,工作已被安全存盘,修复外部条件后点击卡片上的 **「继续」** 即可无缝恢复。
- 若遇到需求歧义,在卡片中的「补充需求」输入框提供明确答案,系统将生成新的需求代次(Revision)重新推进。
- 若遇到后端代码审核门禁,由项目管理员在 Diff 面板审查代码,点击 **「批准」** 后自动触发合并。
### 5. 故障回滚与愿望撤销
- **一键回滚发布**:若线上新版本出现异常,进入 **「部署与审批」** 找到对应环境,点击 **「一键回滚」**,Runner 将以原子方式切换回上一个稳定镜像。
- **一键撤销改动(Revert Run)**:在运行详情页点击 **「撤销这次改动」**,系统会自动基于当前最新主干生成一个“反向 Diff”的全新愿望,严格经过验证器测试后合入并部署。
---
## 三、系统架构与内部设计
### 1. 总体架构拓扑图
![WishForge 总体系统架构设计全景图](images/architecture-overview.svg)
系统由**接入层**、**控制面(唯一事实来源)**、**执行面(沙箱隔离)**以及**目标集群驻地交付面**四大物理层次构成:
1. **控制面 (Control Plane)**:采用 NestJS + PostgreSQL + Temporal 构成不可穿透的控制中枢,所有业务状态流转均由状态机原子裁决。
2. **执行与验证分离**:工作流调度 Executor 与 Verifier 执行彼此隔离的任务,Verifier 拥有绝对的物理验收判定权。
3. **驻地 Runner (Pull-Based)**:目标环境无需向公网暴露任何入站端口,由驻地 Runner 定期拉取携带非对称签名(Ed25519)的任务报文。
### 2. 关键组件与职责划分
| 组件 | 对应路径 | 核心技术 | 架构职责与边界 |
|---|---|---|---|
| **Web Console** | `apps/web` | Next.js 16 (React 19), SWR | 负责客户端交互与 BFF 转换。负责会话管理、CSRF 防护、SSE 流式事件消费与 Diff 视图渲染。不直接触碰业务核心数据库。 |
| **Control Plane API** | `apps/api` | NestJS, Express, Zod | 平台的**单一事实来源(Single Source of Truth)**。管理项目配置、租户额度配额、事务级 Outbox 事件发布、网关凭据代理。 |
| **Workflow Engine** | `apps/worker` | Temporal SDK | 承载长时间运行的分布式状态机。网络中断、节点宕机后自动从精确断点续跑,屏蔽长耗时任务的执行脆弱性。 |
| **Check Pods Runtime**| `packages/runtime` | Kubernetes Client, Kata | 瞬态验证容器。运行于独立命名空间,采用严苛的安全配置(只读挂载代码、无集群 Token、无外部特权),负责执行客观测试。 |
| **Deploy Runner** | `apps/runner` | Node.js, Ed25519, kubectl | 目标环境守护代理。拉取签名任务,驱动 Kubernetes 执行蓝绿/滚动部署,并执行冒烟探针验收。 |
### 3. 八阶段严密交付流水线
![WishForge 八阶段严密交付流水线与自修复状态机](images/eight-stages-lifecycle.svg)
流水线严格遵循单向推进约束,阶段定义如下:
1. **澄清 (Clarify)**:固定验收标准。当用户意图存在致命歧义时,在此阶段主动提出结构化问题并停顿。
2. **规划 (Plan)**:从目标分支 HEAD 切出隔离的任务分支,准备工作区结构。
3. **实现 (Implement)**:调起编码 Agent CLI 进行源码修改,输出检查点 Commit 与增量 Bundle。受 256 MiB 流式输出限额保护。
4. **验证 (Verify)**:在全新的受保护 Check Pod 中独立拉取代码,执行预设的安装与测试命令。**若失败,捕获错误输出尾部流,自动回退到实现阶段进行自修复**(上限轮次内)。
5. **合入 (Integrate)**:在受保护检查通过后,推送到目标分支。若触发后端路径规则,挂起等待代码审核。
6. **构建 (Build)**:在安全无特权环境下调度 Kaniko 构建容器镜像,生成不可变镜像摘要(Digest)。
7. **发布 (Release)**:对镜像与环境配置进行非对称签名,若命中高危风险策略则进入人工审批等待。
8. **验收 (Accept)**:Runner 完成集群 Pod 更新后,执行健康检查探针与冒烟测试,通过后向控制面提交证据并闭环。
### 4. 物理隔离与“验证器独立裁决”机制
这是 WishForge 抵御大模型幻觉与作弊的基石:
- **物理环境隔离**:Agent 工作的环境和跑测试的环境是两个完全独立的容器/命名空间。Agent 即使使用 root 权限破坏了自己的执行环境,也完全无法影响验证器。
- **只读代码源**:验证器工作区中的 `.git` 目录为只读挂载,被测代码直接检出自 Agent 提交的指定 Commit SHA。
- **客观物理证据链**:验证结果不看 Agent 的文字陈述(例如:“我已经通过了所有测试”),只严格依据操作系统捕获的退出状态码(Exit Code 0)和输出日志。
### 5. 状态机驱动与所有等待均有出口
WishForge 内部定义了 16 种结构化等待原因(`WaitingReason`),坚决杜绝“系统死锁”:
- 每一个等待原因(如 `repair_exhausted`、`clarification`、`infrastructure`、`code_review`、`approval` 等)在前端均有唯一的中文卡片说明、对应的解决建议和操作按钮。
- 用户或管理员只需根据页面提示点击「继续」、「回答问题」、「批准」或「取消」,即可让流水线恢复流转。
---
## 四、高频实战 QA 与故障诊断
### Q1: 为什么任务经常停在「等待处理」?流程卡死了吗?
**解答**:
- **并非卡死**:「等待处理(waiting)」是平台的主动防护机制,表明系统正在保护分支安全,等待客观条件满足或人工决策。
- **常见类型及处理办法**:
1. `clarification`(需补充需求):Agent 无法推断必要业务边界。在卡片内回答问题后点击「继续」。
2. `code_review`(等待代码审核):改动命中后端敏感路径,且提交人不具备直接合入权限。架构师/管理员在 Diff 面板审查代码后点击「批准」。
3. `approval`(等待发布审批):生产环境上线保护,发布人在卡片内核对变更镜像后点击「批准发布」。
4. `infrastructure` / `provider_error`(基础设施/网络超时异常):外部调用(如模型网关瞬态超时、Git 鉴权)异常。任务已在断点处自动存盘,检查网络或凭据后直接点击「继续」即可从断点续跑。
---
### Q2: 执行器报错「CLI output exceeded 16 MiB」是什么根因?如何处理?
**解答**:
- **根本原因**:控制面在驱动 Agent(Claude CLI)工作时,需要实时消费其标准输出的 `stream-json` 流。为了防止 Agent 在递归读取、错误打印大文件(如 `node_modules`、打包编译产物、巨量日志)时导致节点内存打爆,系统设置了流式累计输出安全上限。早期该值默认写死为 16 MiB,当大颗粒度愿望导致 Agent 读取了过多文件时便会触发安全断路。
- **平台优化与应对**:
1. 平台已在 `CodeBuddyConfig` 中将输出上限开放为可配置项,并将默认阈值大幅提升至 **256 MiB**,彻底解决常规任务的容积需求。
2. **工程最佳实践**:依然强烈建议用户在提交愿望时遵循“小步快跑”原则,明确约束修改文件范围(例如:“只修改 `apps/web/src/features/` 下的代码”),避免让模型进行全局无限制的大文件扫描。
---
### Q3: 合入阶段提示「Gitea: Deploy Key ... is not authorized to write」怎么处理?
**解答**:
- **根本原因**:代码验证通过后,验证器需要通过 SSH 部署密钥(Deploy Key)将 Commit 推送到远程仓库目标分支(如 `poc` 或 `dev`)。如果在 Git 服务端添加该部署密钥时没有勾选“启用写权限”,Git 服务端会报 128 错误拒绝推送。
- **处置方案**:
1. 登录 Gitea 仓库后台,进入 **仓库设置 $\rightarrow$ 部署密钥**;
2. 删除原有只读的部署公钥;
3. 在本机执行 `node scripts/cluster-poc.mjs deploy-key` 打印平台最新的 Ed25519 部署公钥;
4. 重新添加部署密钥,**务必勾选「启用写权限」**;
5. 若目标分支设置了保护分支规则,需将该密钥所属身份加入允许推送白名单;
6. 回到运行页面点击「继续」,系统将立即自动完成代码合入。
---
### Q4: 提交愿望时点击「AI 优化愿望」出现 502 或超时怎么解决?
**解答**:
- **根本原因**:AI 优化愿望是一次短耗时、高约束的自然语言转结构化 JSON 操作。过去系统默认继承了编码用的大参数模型(`deepseek-pro`),该模型在输出长规范 JSON 时耗时易打穿默认的 120 秒命令行超时,进而导致网关返回 502。
- **平台当前防御与兜底体系**:
1. **首选轻量模型**:默认优化通道调整为秒级响应的轻量模型 `deepseek-flash@latest`。
2. **双模型自动降级(Fallback)**:若 Flash 模型偶发超时或返回畸变格式,后端会自动无缝切换至 `deepseek-pro@latest` 进行二次重试。
3. **超时全链路放宽**:单次模型命令超时放宽至 180 秒,Web 反向代理等待超时扩展至 400 秒,为双模型重试留足安全边际。
---
### Q5: 运行已经全部取消了,为什么概览页的「待确认」数字依然大于 0?
**解答**:
- **根本原因**:控制台首页「待确认」指标的聚合口径不仅包含处于 `waiting` 状态的运行,还包含处于 `awaiting_approval` 状态的发布记录(Release)和 `pending` 状态的审批单(Approval)。在过去版本中,若用户在「发布」阶段取消了运行,控制面仅更新了 `run.status = 'canceled'`,未连带更新已生成的发布单,导致发布单孤立悬挂。
- **平台保障机制**:
- 平台已重构 `cancel` 及 `answer`(补充需求版本迭代)处理链,注入了全量级联失效机制:运行一旦终止,关联的未就绪发布单自动置为 `failed`,审批单及代码审核单同步置为 `invalidated`,指标实时清零对齐。
---
### Q6: 可用模型为什么由原来的手输文本框改成了下拉勾选与动态拉取?
**解答**:
- **根本原因与优势**:
1. **规避人工输入错误**:过去手输模式容易发生大小写错误、特殊字符错漏等问题。默认模型名统一用网关别名,不带 `[1m]` 后缀。
2. **白名单与受控交付**:项目管理员通过下拉复选框严格限定该项目允许使用的模型范围(默认勾选 `deepseek-flash@latest` 和 `deepseek-pro@latest`)。
3. **实时动态同步**:内置 **「获取模型」** 按钮,管理员可在界面上一键直接向公司模型网关查询最新上架的模型列表,即点即用,兼顾灵活性与企业合规管控。