6.3 KiB
6.3 KiB
WishForge Wiki
这是 WishForge 仓库内的受控知识库(Git Wiki)。它面向三类读者,并且只服务于一个目的:让人和 Agent 在不重新扫描整个代码库的前提下,找到可信的现状描述、代码入口和业务约束。
| 读者 | 从这里开始 | 需要的回答 |
|---|---|---|
| 客户 / 使用者 | features/ |
这个功能现在到底怎么用、边界在哪里、失败时怎么办 |
| 编码 Agent | modules/ |
改这个功能要动哪些文件、测试在哪里、哪些契约不能破 |
| 业务与维护者 | glossary/business-rules.md |
哪些业务规则是硬约束、依据在哪个代码/测试文件 |
项目速览
WishForge 是「远程、意图驱动的软件交付平台」:用户用一句话提出愿望(目标 + 验收标准),编码 Agent 在隔离环境中实现,独立验证器按受保护命令判定,失败回灌自修复,通过后合入、按需构建与部署(README.md:3)。
仓库分层与 Wiki 的对应关系:
| 仓库目录 | 内容(README.md:65-79) |
对应 Wiki 页面 |
|---|---|---|
apps/api |
控制面 API(REST、内部接口、MCP、模型代理) | modules/api-control-plane |
apps/web |
Web 工作台(Next.js,OIDC BFF) | modules/web-console |
apps/worker |
Temporal worker:coordinator / executor / verifier / deployer | modules/worker-pipeline |
apps/provisioner、apps/runner、apps/git-service |
执行环境、驻地部署、平台 Git | modules/provisioner-runner-git-service |
packages/contracts、packages/runtime |
领域契约与执行适配 | modules/runtime-and-contracts |
运行前置与检查命令见 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 | 提交愿望、验收标准、AI 优化、模型白名单 |
| run-lifecycle-and-waiting | 八阶段流水线、运行状态、18 种等待原因与解除路径 |
| independent-verification-and-self-repair | 验证器独立裁决、受保护验收配置、自修复轮次 |
| integration-build-release-rollback | 合入、构建、发布审批、回滚与 POC 驻地交付 |
| agent-entrypoints-and-permissions | Web / MCP / IDE / 连接器四类入口与角色权限 |
| console-observability-and-usage | 控制台、事件流、Diff、报告、用量与配额 |
modules/ — 面向 Agent 的代码地图
| 页面 | 覆盖范围 | 关键入口 |
|---|---|---|
| api-control-plane | 控制面 API、领域状态机、数据库与 Outbox | apps/api/src/main.ts、apps/api/src/domain/control-plane.ts |
| worker-pipeline | Temporal 工作流、executor、verifier、发布请求 | apps/worker/src/workflows.ts、apps/worker/src/verifier.ts |
| runtime-and-contracts | Git/验证/构建/部署适配、领域契约 | packages/runtime/src/、packages/contracts/src/index.ts |
| web-console | Next.js 工作台、BFF、事件与等待提示 | apps/web/src/features/、apps/web/src/lib/waiting.ts |
| provisioner-runner-git-service | 执行环境、驻地 Runner、平台 Git 服务 | apps/provisioner/main.mjs、apps/runner/src/main.ts、apps/git-service/src/service.ts |
glossary/ — 受控领域词汇与业务规则
| 页面 | 说明 |
|---|---|
| business-rules | 从 droboticflow 迁移的标注规范、算子约束与业务规则,每条带代码/测试引用 |
内容规则(新增页面前必须遵守)
- 一条事实必须有一个可追溯依据。 使用相对仓库根的路径加行号或函数名,例如
packages/contracts/src/index.ts:20;测试依据写成tests/xxx.test.ts。没有依据的内容不进入 Wiki。 - 代码优先于文档。 当
docs/与源码不一致时,以源码为准,并在页面里显式记录差异。本 Wiki 首版已经记录了至少一处:docs/wishforge-summary.md称 16 种等待原因,而packages/contracts/src/index.ts:25-44定义了 18 种。 - 不写空模板。 每个页面至少包含:现状描述、代码入口、测试集位置、已知边界。占位符页面视为缺陷。
- 业务规则只用受控表述。 规则编号(
BR-xx、OPR-xx)只增不改;修改规则需要同步更新引用与“最后核对”版本。 - 不把推测写成结论。 无法从代码或测试确认的行为,写进“未确认/待验证”。
自检
# 文件数量
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仓库(Gitealongtao.wu/droboticflow,本地核对版本877307cb,2026-10-27)。迁移只收录能在代码中找到执行点的规则,不搬运纯愿景描述。