ace
47bd454fa3
- skills/builder: SKILL.md, README.md, references/contract.md (make/publish contract v1), references/registry.md - scripts/check.py: executable contract checker (make dry-run probes, secret scan, push thin-wrapper and script path checks; --build verifies real .deb) - scripts/upload_deb.sh: migrated from deb-publisher, adds project .env auto-load and dirty-worktree publish gate - scripts/publish_docker.sh: migrated from publish-docker-image publish.sh, now env-first (DOCKER_REGISTRY/REPOSITORY/IMAGE_TAG/PLATFORMS), refuses floating latest and multi-platform --load - scripts/verify_deb.sh: metadata/content/sha256 verification with v-prefix normalization - orc: deb+docker stages both route to $builder; routing table, DAGs, README, config untouched stage names; tests updated - ack delivery.md + skiff source-model.md: reference builder - remove skills/deb-publisher and skills/publish-docker-image
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# orc
|
||
|
||
ORC 是显式调用的薄路由器：只把开发、版本发布、DEB 和 Docker 意图映射成阶段，
|
||
按静态配置选择 `low`、`mid` 或 `high` worker，再交给对应 Skill。
|
||
|
||
## 什么时候使用
|
||
|
||
- 一个请求同时包含写代码、发版本和构建产物。
|
||
- 希望由 ORC 监督多个 Agent，并按阶段控制成本与推理能力。
|
||
- 需要继续中断的多阶段工程流程并保留依赖关系。
|
||
|
||
只做单一领域任务时可以直接调用对应 Skill；ORC 不替代它们的安全规则。
|
||
|
||
## 使用前准备
|
||
|
||
- Orca 正在运行并启用了 orchestration。
|
||
- 安装本次需要的 `$ack`、`$manage-release` 或 `$builder`（DEB 与 Docker 共用）。
|
||
- ORC 直接使用 skill 内共享的 `config.yaml`，不需要在每个项目初始化配置。修改这份
|
||
配置会影响所有项目；旧的项目级 `docs/orc/config.yaml` 不再参与解析。
|
||
- `/usr/bin/python3`；ORC v2 配置必须保持为 JSON-compatible YAML。
|
||
resolver 以 `-I -S` 隔离模式运行，不加载项目模块、用户 site-packages 或第三方解析器。
|
||
- ORC v2 worker 使用 `workspace-write` sandbox，以便发送 Orca lifecycle 消息；
|
||
只读任务会在阶段 prompt 中禁止文件修改。
|
||
- release worker 是受信任的发布角色，直接调用当前 shell 中已认证的 `git` 与 Forge CLI
|
||
（Gitea/Forgejo 使用 `tea`）；ORC 不读取认证配置，也不注入 credential helper。
|
||
- release 阶段要求 `origin` 只有一个且一致的 fetch/push URL。Codex 只为该阶段开启网络，
|
||
并用 network proxy 把出站目标限制到 remote/Forge API host；GitHub 额外允许其固定 API
|
||
与 release upload host，其它本地阶段默认继续禁网。
|
||
|
||
## Worker 档位
|
||
|
||
| 档位 | 典型任务 |
|
||
|------|----------|
|
||
| `low` | 输入明确的测试、构建、打包和上传 |
|
||
| `mid` | 常规版本发布与范围清晰的工程任务 |
|
||
| `high` | 需求理解、跨系统改动、异常恢复和高风险裁决 |
|
||
|
||
档位不是权限。三个档位仍受各自 profile 和下游 Skill 的授权边界约束。
|
||
这些档位只选择下游 worker，不会切换当前 ORC Coordinator 已经使用的模型。
|
||
结构化启动适配器支持 Codex 与 Cursor worker，并固定跟随当前宿主：从 Codex 调用就使用
|
||
Codex，从 Cursor 调用就使用 Cursor。共享配置为两个 CLI 分别维护三档模型，不设置跨宿主
|
||
默认值。
|
||
|
||
## 使用示例
|
||
|
||
```text
|
||
$orc high 修复登录问题，验证通过后发布新版本。
|
||
$orc code=high release=mid docker=low，完成修复、发版并推送镜像。
|
||
$orc low，检查并准备下一个版本，不执行远端写操作。
|
||
$orc mid 继续上次中断的 v1.4.0 发布流程。
|
||
```
|
||
|
||
阶段级档位优先于全局档位；未指定时只读取 `stageDefaults` / `defaultLevel`。ORC 不根据
|
||
任务复杂度动态升降档；worker 报告能力不足时，ORC 只转发请求。
|
||
|
||
## Agent 会做什么
|
||
|
||
1. 识别开发、源码发布、DEB 与 Docker 意图，并按固定表建立阶段依赖。
|
||
2. 从当前 Agent 的系统身份锁定宿主 CLI，再解析每个阶段的 profile，把共享配置快照、
|
||
可信 Agent CLI executable 和真实 Git
|
||
worktree 绑定成 launch fingerprint，并展示计划和外部写入边界。
|
||
3. 通过 Orca 分发给对应 Skill，转发完成消息、异常和决策门。
|
||
4. 按下游 Skill 声明的证据字段汇总状态和恢复入口，不重新做领域判断。
|
||
|
||
ORC 不分析实现、不建议版本、不评估发布风险、不选择合并或构建方案；这些工作全部属于
|
||
下游 Skill。
|
||
|
||
## 如何判断完成
|
||
|
||
最终结果会逐阶段列出所用 Skill、Agent 档位、源 revision、远端或产物状态，以及任何
|
||
未完成项。只有所有必要阶段都通过各自验证时，ORC 才会报告整个流程完成。
|