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