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

84 lines
4.8 KiB
Markdown
Raw Permalink 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.

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