wishforge-ide/wiki/modules/runtime-and-contracts.md

4.8 KiB
Raw Permalink Blame History

模块:运行时适配与领域契约(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 模式只能显式开启。