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