wishforge-ide/wiki/index.md

6.3 KiB
Raw Blame History

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 迁移的标注规范、算子约束与业务规则,每条带代码/测试引用

内容规则(新增页面前必须遵守)

  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. 不把推测写成结论。 无法从代码或测试确认的行为,写进“未确认/待验证”。

自检

# 文件数量
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)。迁移只收录能在代码中找到执行点的规则,不搬运纯愿景描述。