4.8 KiB
4.8 KiB
模块:运行时适配与领域契约(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 | 不可靠链路的读重试节奏 |
三个最容易被误改的地方:
verify.ts的导出树。 被测代码必须与验证器仓库分离,否则 Git filter/hook 可以逃逸。git.ts的检查点上限。 bundle 与补丁各 4 MiB(CHECKPOINT_BUNDLE_LIMIT、CHECKPOINT_PATCH_LIMIT),这是为了避免把整个仓库塞进数据库。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 |
前端打包边界 |
修改时的检查清单
- 改契约字段:跑
npm run typecheck(含 tests 的 tsconfig),并检查所有 consumer。 - 改 runtime 的 Git/验证逻辑:至少跑对应
packages/runtime/test/*.test.ts与tests/local-poc-delivery.test.ts。 - 新增摘要字段:确认
canonical.ts的序列化稳定,否则审批会随机失效。 - 改沙箱:生产模式必须保持 fail closed,host 模式只能显式开启。