Compare commits
5 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 laily
|
337f1a9098 | ||
|
laily
|
f02a34e751 | ||
|
laily
|
a0f1c15b85 | ||
|
laily
|
f8d03fad4d | ||
|
laily
|
5b0e41199d |
@@ -59,6 +59,7 @@ AGENTS.md # 本文档
|
||||
|
||||
| Skill | 说明 |
|
||||
| ---------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| [orc](skills/orc/SKILL.md) | ORC 入口：显式编排开发、版本发布与产物任务，支持 Agent 分档 |
|
||||
| [ack](skills/ack/SKILL.md) | ACK 入口：显式初始化、检查并运行项目三角色协作闭环 |
|
||||
| [skiff](skills/skiff/SKILL.md) | 本项目工作流：创建、使用、反馈与更新 builtin skill |
|
||||
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
|
||||
|
||||
@@ -36,6 +36,7 @@ AGENTS.md # 详细规范与架构说明
|
||||
|
||||
| Skill | 说明 |
|
||||
|-------|------|
|
||||
| [orc](skills/orc/SKILL.md) | 显式编排开发、版本发布和产物任务，支持 low/mid/high Agent 档位 |
|
||||
| [ack](skills/ack/SKILL.md) | 显式初始化、检查并运行 ACK 三角色协作及可选交付闭环 |
|
||||
| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
|
||||
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
# ACK 飞书多维表格 Bug 收件箱
|
||||
|
||||
## 目标
|
||||
|
||||
让用户在飞书多维表格中跨设备记录文字和截图，随后由 ACK Coordinator 通过官方
|
||||
`lark-cli` 读取项目配置的 `ACK Ready` 视图，整理为独立、可验收、可幂等追踪的 ACK
|
||||
任务。不同项目通过不同 CLI profile 访问各自飞书租户。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不用 Skill 承担人工记录入口。
|
||||
- 不抓取公开网页或依赖浏览器登录态。
|
||||
- 不把 App Secret、access token 或飞书用户凭据写入项目。
|
||||
- 第一版不反向更新飞书记录，不把飞书状态与 ACK 状态做双向同步。
|
||||
- 不把多条互不相关的 Bug 合成一次 Developer 派发。
|
||||
|
||||
## 项目配置契约
|
||||
|
||||
可选配置位于 `docs/ack/tasks.yaml` 的 `project.bugIntake`。未配置时 ACK 保持现有行为。
|
||||
配置存在时必须包含：
|
||||
|
||||
| 字段 | 约束 |
|
||||
|------|------|
|
||||
| `provider` | 固定为 `feishu-base` |
|
||||
| `profile` | `lark-cli` profile 名称；每次命令显式传入 |
|
||||
| `baseToken` | 飞书 Base token |
|
||||
| `tableId` | 数据表 ID |
|
||||
| `viewId` | 只包含可导入记录的 `ACK Ready` 视图 ID |
|
||||
| `fields` | 逻辑字段到飞书字段 ID/名称的映射 |
|
||||
|
||||
`fields` 必须映射 `title`、`actual`、`expected`、`stepsToReproduce`、
|
||||
`acceptance`、`priority`、`attachments`、`updatedAt`。字段值只作为单个 argv 传给
|
||||
`lark-cli`，不经过 shell。
|
||||
|
||||
## CLI 契约
|
||||
|
||||
- 可执行文件固定为可信路径中的 `lark-cli`。
|
||||
- 允许官方 npm 包生成且 package/bin 映射校验通过的 `run.js` wrapper，并解析到包内
|
||||
native binary 执行；拒绝缺少 native binary 或其它同名软链接目标。
|
||||
- profile 由项目显式选择；不得执行 `profile use` 或读取 active profile作为回退。
|
||||
- 子进程使用最小环境，不继承可能覆盖 profile/config/凭据或注入运行时的环境变量。
|
||||
- 记录读取使用 `base +record-list`、JSON 输出、指定 Base/table/view 和投影字段。
|
||||
- 记录超过一页时按 offset/limit 继续读取，并设置总页数/记录数上限。
|
||||
- 附件仅通过 `base +record-download-attachment` 下载到调用者显式提供的临时目录。
|
||||
- 附件数量、单文件大小、批次总大小和子进程文件写入均有硬上限；落盘大小必须与
|
||||
元数据一致。
|
||||
- 标准输出必须是单一 JSON；CLI stderr 只作为错误摘要，不把可能的凭据写入结果。
|
||||
|
||||
## 标准化结果
|
||||
|
||||
读取器输出批次元数据和 `records`。每条记录至少包含：
|
||||
|
||||
- `sourceRef`：对 provider、profile、Base、table、record ID 做域隔离 SHA-256
|
||||
后得到的稳定匿名引用；原始 profile、Base token 与 record ID 不拼入引用文本；
|
||||
- `recordId` 与 `updatedAt`；
|
||||
- title、actual、expected、steps、acceptance、priority；
|
||||
- 附件的 name/type/size 与可选本地临时路径；附件 token 只在下载命令内部使用；
|
||||
- 原始字段中无法映射但不影响导入的警告。
|
||||
|
||||
输出不得包含 App ID、App Secret、Base token、附件 file token、tenant/user access
|
||||
token 或 CLI 配置文件内容。
|
||||
|
||||
## Coordinator 整理规则
|
||||
|
||||
1. 先运行读取器 `check`，确认 `lark-cli`、项目 profile 和所需只读能力可用。
|
||||
2. 运行读取器 `plan` 读取 `ACK Ready` 视图并生成 create/refresh/unchanged/drift
|
||||
整理动作；需要看截图时使用临时下载目录。
|
||||
3. 将记录分类为 Bug、已有功能、接受的改进、样式偏好或超范围；只导入确认接受的项。
|
||||
4. 每条导入任务保存 `source.kind=feishu-base`、`source.ref`、`source.recordId`、
|
||||
`source.updatedAt`，并把截图观察转成文字证据。
|
||||
5. 导入前扫描已有任务的 `source.ref`。相同来源不得新建第二条任务。
|
||||
6. 来源更新但任务尚为 `open` 时可由 Coordinator刷新描述；任务已派发或进入终态时只报告漂移，由用户决定是否新开任务。
|
||||
7. 飞书记录删除、不可访问或 CLI 暂时失败时保留已有 ACK 任务，不反向删除。
|
||||
|
||||
## 可观测验收信号
|
||||
|
||||
1. 两个假租户 profile 同时存在时，项目指定 `tenant-b`，所有记录和附件命令都显式包含 `--profile tenant-b`，不会读取 active 的 `tenant-a`。
|
||||
2. 只读取配置的 `ACK Ready` view ID，并投影配置字段；不查询整张表或其它视图。
|
||||
3. 一条含截图附件的假记录被标准化为稳定 `sourceRef`、完整文字字段和本地附件路径，输出中不存在任何 secret/token 凭据。
|
||||
4. CLI 缺失、profile 缺失、畸形 JSON、错位矩阵、分页越界、路径穿越或附件下载失败均返回非零退出码且不输出伪成功结果。
|
||||
5. ACK 文档明确要求按 `source.ref` 幂等整理；同一读取结果重复提交不会生成第二个来源任务。
|
||||
6. 现有无 `bugIntake` 的 ACK 项目仍能通过任务板校验并按原流程工作。
|
||||
|
||||
## 最脆弱假设与降级
|
||||
|
||||
本设计假设官方 `lark-cli` 的 Base JSON 输出保持 `fields`、`record_id_list` 与行矩阵
|
||||
对应关系。读取器必须校验三者长度和字段映射；若上游输出契约变化，立即失败并提示
|
||||
升级适配器，不能错列生成 Bug。飞书或 CLI 不可用时，只停止新的同步，已经进入
|
||||
`tasks.yaml` 的任务继续按 ACK 闭环执行。
|
||||
@@ -0,0 +1,9 @@
|
||||
# 复制为 docs/ack/knowledge.yaml，替换占位符。结构见 templates/knowledge.schema.json。
|
||||
# Developer/Test 只能在任务证据中提出 candidate；只有 Coordinator 写入这里。
|
||||
version: 1
|
||||
updatedAt: "2026-08-01T12:43:06+08:00"
|
||||
project:
|
||||
name: "skills"
|
||||
# 检查 ID 映射到仓库内相对 path 和结构化 args；这里的内容不会被校验器执行。
|
||||
verificationRegistry: {}
|
||||
entries: []
|
||||
@@ -0,0 +1,71 @@
|
||||
# Agent Skills 仓库 ACK 协作协议（项目覆盖层）
|
||||
|
||||
> 本项目基于 ACK Skill v0.12.0。通用规范由 `/ack` 从 Skill 自身的
|
||||
> `references/` 读取；本文件只保存当前仓库差异。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`skills`
|
||||
- 技术栈：Python 3、Markdown、JSON Schema
|
||||
- 运行命令：`python3 -m unittest discover -s tests -p 'test_*.py'`
|
||||
- Base URL：`n/a`
|
||||
- 任务板：`docs/ack/tasks.yaml`
|
||||
- 项目知识：`docs/ack/knowledge.yaml`
|
||||
- 覆盖层文件：`docs/ack/project.md`
|
||||
|
||||
## 通用规范（由 ACK Skill 按需读取）
|
||||
|
||||
- 开始需求：`references/kickoff.md`
|
||||
- 角色、权限、状态机与完成定义：`references/roles-and-permissions.md`
|
||||
- 模型档位与升级规则：`references/model-routing.md`
|
||||
- 闭环流程与 worktree 对齐：`references/closed-loop.md`
|
||||
- 验收信号与三轮策略：`references/optimization-method.md`
|
||||
- 派发 prompt 模板：`references/prompt-templates.md`
|
||||
- Orca 编排命令：`references/orca-adapter.md`
|
||||
|
||||
## Worker 路由
|
||||
|
||||
机器可校验的 worker profile、允许 worktree 和 receipt 只以
|
||||
`docs/ack/tasks.yaml` 为准。本次 Developer 使用当前 `record-bug` worktree；Test
|
||||
必须使用 fresh worker，并在独立临时项目、独立假 CLI 配置目录中完成黑盒演练。
|
||||
|
||||
## 路径权限
|
||||
|
||||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `docs/ack-feishu-bug-intake.md` | R/W | Read-only | Read-only | 本需求规格与验收契约 |
|
||||
| `docs/ack/` | R/W | Read-only | Read-only | ACK 项目状态，只有 Coordinator 写 |
|
||||
| `skills/ack/` | Read-only | Read-only | R/W | ACK Skill 实现、模板与通用规范 |
|
||||
| `tests/test_ack_feishu_intake_unit.py` | Read-only | Read-only | R/W | Developer 白盒测试 |
|
||||
| `tests/test_ack_feishu_intake_e2e.py` | Read-only | R/W | Read-only | Test 独立黑盒演练与回归测试 |
|
||||
| 其它 `tests/test_ack*.py` | Read-only | Read-only | Read-only | 既有 ACK 回归测试 |
|
||||
| 临时测试目录 | Read-only | R/W | R/W | 必须由 `tempfile`/`mktemp -d` 创建，不保存凭据 |
|
||||
| `~/.lark-cli/` | Read-only | Read-only | Read-only | 不读取、不修改真实飞书 profile；测试只能使用假 CLI |
|
||||
|
||||
## 命令
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_unit.py'
|
||||
python3 -m unittest tests.test_ack_skill tests.test_ack_tasks_validation
|
||||
python3 -m compileall -q skills/ack/scripts
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_e2e.py'
|
||||
python3 -m unittest discover -s tests -p 'test_ack*.py'
|
||||
python3 skills/ack/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||||
python3 skills/ack/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
## 本次任务硬规则
|
||||
|
||||
- 只支持官方 `lark-cli`，所有读取命令必须显式携带项目配置的 `--profile`，不能依赖当前 active profile。
|
||||
- 项目只保存 profile 名称、Base/table/view 标识和字段映射；App Secret、token 与用户凭据不得进入仓库、任务板或日志。
|
||||
- 飞书接入第一版只读，不更新或删除表格记录，不切换 CLI active profile。
|
||||
- 外部 CLI 缺失、profile 不存在、返回结构异常、附件下载失败时 fail closed，不回退到网页抓取。
|
||||
- 只有 `ACK Ready` 视图中的记录可进入整理；每条记录保留稳定 `record_id` 来源引用，重复读取不得制造重复 ACK 来源。
|
||||
- 不修改 `AGENTS.md`、`CLAUDE.md`，不提交或推送。
|
||||
@@ -0,0 +1,533 @@
|
||||
version: 1
|
||||
updatedAt: "2026-08-01T13:34:00+08:00"
|
||||
source: "Coordinator (PM) Agent"
|
||||
ackVersion: "0.12.0"
|
||||
project:
|
||||
name: "skills"
|
||||
repoPath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
baseUrl: "n/a"
|
||||
devWorktree: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
overlayFile: "docs/ack/project.md"
|
||||
knowledgeFile: "docs/ack/knowledge.yaml"
|
||||
orchestration:
|
||||
profileVersion: 1
|
||||
mode: "orca"
|
||||
allowedWorktrees:
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
modelAllowlist:
|
||||
codex:
|
||||
developer:
|
||||
standard: ["gpt-5.6-terra"]
|
||||
strong: ["gpt-5.6-sol"]
|
||||
test:
|
||||
standard: ["gpt-5.6-luna"]
|
||||
profiles:
|
||||
codex-dev-standard:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
codex-test-standard:
|
||||
role: "test"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
codex-dev-strong:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "strong"
|
||||
model: "gpt-5.6-sol"
|
||||
reasoningEffort: "high"
|
||||
permissionMode: "workspace-write"
|
||||
defaults:
|
||||
developer: "codex-dev-standard"
|
||||
test: "codex-test-standard"
|
||||
developerUpgraded: "codex-dev-strong"
|
||||
|
||||
workerReceipts:
|
||||
- receiptVersion: 1
|
||||
id: "WR-1c9755604c0de98ce5ccc5913faa4984e9d975879250095b3553a796bccb261d"
|
||||
launchId: "1c9755604c0de98ce5ccc5913faa4984e9d975879250095b3553a796bccb261d"
|
||||
profileId: "codex-dev-standard"
|
||||
profileHash: "sha256:fd5bc08d5d8a154175675a2de3b29cabbf016fdae0ed5f76167c63bced0bc47b"
|
||||
launchFingerprint: "sha256:7de2f9ebf3065e7c044150fa87aed39582a8018b63a0dabac22194bf52ad52b7"
|
||||
slot: 1
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A1"
|
||||
role: "developer"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-terra"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=medium"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:a17f4a56e4324a6c170773dffdf0b986c4f070e04fe404ba8395135c686182ee"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_4d6278c9-83ac-4876-a29d-022adc346e6c"
|
||||
incarnationId: "6daffb4c-e705-47f3-b7c2-d1ee1fb16c56"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T04:46:51.629061Z"
|
||||
createdAt: "2026-08-01T04:46:42.869861Z"
|
||||
receiptHash: "sha256:93e7e4454438a4d1c9a64eb7429563bb4b71348715cc4cb3e42c96cb9ca75fa4"
|
||||
- receiptVersion: 1
|
||||
id: "WR-035285dde990c7f59be5842a6c98eab8f715dd9c4400fba79aba341fab53ffc3"
|
||||
launchId: "035285dde990c7f59be5842a6c98eab8f715dd9c4400fba79aba341fab53ffc3"
|
||||
profileId: "codex-test-standard"
|
||||
profileHash: "sha256:30a1cf4d0f1b180ca1aebd759cf8a9425047ed9563f4cf3eb3fe8b3935ca2078"
|
||||
launchFingerprint: "sha256:981fe3c23594573f564de9ab321e724324962958ed689ad3c0c98d7d165c1aa9"
|
||||
slot: 2
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A1"
|
||||
role: "test"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-luna"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=low"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:ad1991c9d70fc574c856a2f7cb51a7e93eca5d286dfc689b09b414f7144f6369"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_ab858ba7-b972-45fb-bf50-61e96ced2830"
|
||||
incarnationId: "9e20c158-7ac3-4a18-8dca-f9fec50126d6"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T04:57:33.909375Z"
|
||||
createdAt: "2026-08-01T04:57:25.086609Z"
|
||||
receiptHash: "sha256:1245532d66814f5d3b2a6a3b22293ead597f04390e628333569a7ba8763d0a84"
|
||||
- receiptVersion: 1
|
||||
id: "WR-3202fbd30c60dfc6614787e82d0f8e10701f811fdc3d43af54b8cc269d8165f1"
|
||||
launchId: "3202fbd30c60dfc6614787e82d0f8e10701f811fdc3d43af54b8cc269d8165f1"
|
||||
profileId: "codex-dev-standard"
|
||||
profileHash: "sha256:fd5bc08d5d8a154175675a2de3b29cabbf016fdae0ed5f76167c63bced0bc47b"
|
||||
launchFingerprint: "sha256:8264af6531e9828c0f994845b3a24931e22abea72d8a1d54a7c764577e544873"
|
||||
slot: 3
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A2"
|
||||
role: "developer"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-terra"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=medium"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:a17f4a56e4324a6c170773dffdf0b986c4f070e04fe404ba8395135c686182ee"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_d1b02227-6bd6-4bd3-a432-bb50f64fca8c"
|
||||
incarnationId: "f77f05ff-fb2b-4099-ab03-070f61671673"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:01:26.824435Z"
|
||||
createdAt: "2026-08-01T05:01:17.965038Z"
|
||||
receiptHash: "sha256:c20c47c7491b5b399d2c29fce67a7035b432969bda0ccb74948eb03c3d085380"
|
||||
- receiptVersion: 1
|
||||
id: "WR-12c3784e1719302b77728917b913c3233ef022f811a94050d1842e2d54971ebd"
|
||||
launchId: "12c3784e1719302b77728917b913c3233ef022f811a94050d1842e2d54971ebd"
|
||||
profileId: "codex-test-standard"
|
||||
profileHash: "sha256:30a1cf4d0f1b180ca1aebd759cf8a9425047ed9563f4cf3eb3fe8b3935ca2078"
|
||||
launchFingerprint: "sha256:621c7d5d6b7182d9a1ebf211fa11a80d7b100a3b682f8800f61031a651f5bf2a"
|
||||
slot: 4
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A2"
|
||||
role: "test"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-luna"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=low"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:ad1991c9d70fc574c856a2f7cb51a7e93eca5d286dfc689b09b414f7144f6369"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_1ec9d2e1-a1b6-45db-8477-097e39a93ee4"
|
||||
incarnationId: "a6f79ac3-9cc6-40a1-a38a-e7b7c2a49b02"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:05:36.189001Z"
|
||||
createdAt: "2026-08-01T05:05:27.500696Z"
|
||||
receiptHash: "sha256:824227bda0e78558807e10da9d89ec32ee4d7f37d782b866bca4629c5ac9e8fb"
|
||||
- receiptVersion: 1
|
||||
id: "WR-90c5c8a69173ce07d1db3f6065eaf956ca6cacbdc5396ac3a224e04a7fe8ed21"
|
||||
launchId: "90c5c8a69173ce07d1db3f6065eaf956ca6cacbdc5396ac3a224e04a7fe8ed21"
|
||||
profileId: "codex-dev-standard"
|
||||
profileHash: "sha256:fd5bc08d5d8a154175675a2de3b29cabbf016fdae0ed5f76167c63bced0bc47b"
|
||||
launchFingerprint: "sha256:97ef498caf4a5f0d48fef22773c942a5065dfcf5cecefa22a6ad21df8d04bcd1"
|
||||
slot: 5
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
role: "developer"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-terra"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=medium"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:a17f4a56e4324a6c170773dffdf0b986c4f070e04fe404ba8395135c686182ee"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_88079d90-29a3-48ac-9b97-bec011abc249"
|
||||
incarnationId: "5d4f785f-e0b5-4ab3-9de3-72ebc2da3b06"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:16:40.565911Z"
|
||||
createdAt: "2026-08-01T05:16:31.788668Z"
|
||||
receiptHash: "sha256:c62417b2ee8e9815228a18b2ee1be84b2844dada50eb9703a061e08e51e57eb7"
|
||||
- receiptVersion: 1
|
||||
id: "WR-8d81f78e66ba7c82c7a6a734b35e5941ef0aa3f03f8ef694baae75eeaf9ebfd7"
|
||||
launchId: "8d81f78e66ba7c82c7a6a734b35e5941ef0aa3f03f8ef694baae75eeaf9ebfd7"
|
||||
profileId: "codex-test-standard"
|
||||
profileHash: "sha256:30a1cf4d0f1b180ca1aebd759cf8a9425047ed9563f4cf3eb3fe8b3935ca2078"
|
||||
launchFingerprint: "sha256:6c7a45f7dd119bb6ef3bfaed7961c30f257285d940f248e0b16678dcad1bd19d"
|
||||
slot: 6
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
role: "test"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-luna"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=low"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:ad1991c9d70fc574c856a2f7cb51a7e93eca5d286dfc689b09b414f7144f6369"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_44ab2675-445a-4f51-a0f5-83960bc1ca3b"
|
||||
incarnationId: "6e37ac75-5725-410c-87af-63f8bb42a911"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:25:08.564556Z"
|
||||
createdAt: "2026-08-01T05:24:59.720042Z"
|
||||
receiptHash: "sha256:dcbed5b2a3fa99312deba61951253992741eca885068e8f649613bd97eb3f59f"
|
||||
|
||||
summary:
|
||||
verified: ["FEISHU-001"]
|
||||
open: []
|
||||
failedRetest: []
|
||||
leftovers: []
|
||||
|
||||
tasks:
|
||||
- id: "FEISHU-001"
|
||||
type: "feature"
|
||||
title: "ACK 从飞书多维表格按项目 profile 读取并整理 Bug"
|
||||
priority: "P1"
|
||||
status: "verified"
|
||||
assignee: "test"
|
||||
component: "skills/ack"
|
||||
specRefs:
|
||||
- "docs/ack-feishu-bug-intake.md"
|
||||
testRefs:
|
||||
- "tests/test_ack_feishu_intake_unit.py"
|
||||
- "tests/test_ack_feishu_intake_e2e.py"
|
||||
knowledgeRefs: []
|
||||
knowledgeApplied: []
|
||||
knowledgeCandidates: []
|
||||
knowledgeChecks: []
|
||||
|
||||
description: >
|
||||
扩展完整 ACK Skill，使项目可以在 tasks.yaml 中声明飞书多维表格 Bug 收件箱和
|
||||
lark-cli profile。ACK 通过可信、无 shell 的读取器读取 ACK Ready 视图、按需
|
||||
下载截图并输出可幂等整理的标准化记录；不同项目不会串用飞书租户。
|
||||
|
||||
stepsToReproduce:
|
||||
- "创建两个假 lark-cli profile：tenant-a 为 active，项目配置 tenant-b"
|
||||
- "在 tenant-b 的 ACK Ready 视图返回一条带截图附件的 Bug 记录"
|
||||
- "运行 ACK 飞书读取器 check/fetch，并重复提交同一标准化结果"
|
||||
|
||||
expected: >
|
||||
读取器每次显式使用 tenant-b，仅读取配置 view，正确标准化文字与截图附件，
|
||||
对所有错误 fail closed；ACK 按稳定 source.ref 整理，重复来源不产生新任务，
|
||||
未配置飞书的旧项目保持兼容。
|
||||
|
||||
actual: >
|
||||
当前 ACK 没有飞书 Bug 数据源、CLI profile 配置、附件读取或来源幂等规则。
|
||||
|
||||
evidence:
|
||||
browser: "飞书多维表格记录可包含文字字段和截图附件；本次使用假 CLI 离线复现"
|
||||
api: "官方 lark-cli base +record-list 与 +record-download-attachment"
|
||||
logs: "本机当前没有 lark-cli，验证必须通过隔离假 CLI 完成"
|
||||
|
||||
verification:
|
||||
commands:
|
||||
- "python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_unit.py'"
|
||||
- "python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_e2e.py'"
|
||||
- "python3 -m unittest discover -s tests -p 'test_ack*.py'"
|
||||
- "python3 skills/ack/scripts/validate_tasks.py docs/ack/tasks.yaml"
|
||||
browser:
|
||||
page: "n/a"
|
||||
checks:
|
||||
- "假 CLI 记录证明所有数据命令显式使用 tenant-b profile"
|
||||
- "标准化输出包含唯一 sourceRef 与本地截图路径"
|
||||
- "重复来源整理结果只对应一个 ACK 任务"
|
||||
|
||||
dispatch:
|
||||
developer:
|
||||
profileId: "codex-dev-standard"
|
||||
receiptId: "WR-90c5c8a69173ce07d1db3f6065eaf956ca6cacbdc5396ac3a224e04a7fe8ed21"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
taskId: "task_9bc1dba1e21a"
|
||||
dispatchId: "ctx_0791582a526f"
|
||||
test:
|
||||
profileId: "codex-test-standard"
|
||||
receiptId: "WR-8d81f78e66ba7c82c7a6a734b35e5941ef0aa3f03f8ef694baae75eeaf9ebfd7"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
taskId: "task_4f70d2496d13"
|
||||
dispatchId: "ctx_66ab3460dda2"
|
||||
rounds:
|
||||
- round: 1
|
||||
attemptId: "FEISHU-001-A1"
|
||||
result: failed
|
||||
evidence: >
|
||||
Isolated fake tenant and screenshot intake passed profile isolation,
|
||||
download containment, fail-closed behavior, organization rules and
|
||||
legacy validation, but normalized output leaked baseToken inside
|
||||
sourceRef and exposed the attachment file token.
|
||||
- round: 2
|
||||
attemptId: "FEISHU-001-A2"
|
||||
result: failed
|
||||
evidence: >
|
||||
Strengthened isolated E2E passed after the secret-output fix, but
|
||||
Coordinator final gate compared the adapter with official lark-cli
|
||||
source: profile list returns a raw JSON array and has no --format
|
||||
flag, while the adapter requires an object and sends --format.
|
||||
Executable lookup also trusts arbitrary PATH instead of the fixed
|
||||
trusted directories required by the product spec; template source
|
||||
reference still documents the obsolete raw form.
|
||||
- round: 3
|
||||
attemptId: "FEISHU-001-A3"
|
||||
result: passed
|
||||
evidence: >
|
||||
Fresh Test ran a file-backed fake Feishu submission containing all
|
||||
Bug text fields and a screenshot through the production check/fetch
|
||||
entry points. Six focused E2E tests and five unit tests passed. The
|
||||
run verified the official raw profile array and data.data matrix,
|
||||
explicit tenant-b selection, trusted executable resolution,
|
||||
screenshot containment, stable opaque sourceRef deduplication and
|
||||
fail-closed handling for malformed, ambiguous, non-progressing and
|
||||
over-limit responses. Validators, skiff check, compileall and diff
|
||||
checks also passed.
|
||||
|
||||
resolution:
|
||||
fixedBy: "term_88079d90-29a3-48ac-9b97-bec011abc249"
|
||||
verifiedBy: "term_44ab2675-445a-4f51-a0f5-83960bc1ca3b"
|
||||
verifiedAt: "2026-08-01T13:31:40+08:00"
|
||||
leftoverReason: null
|
||||
evidence:
|
||||
developer: >
|
||||
FEISHU-001-A1 implemented ACK 0.12.0 Feishu Base intake. Focused unit
|
||||
tests, ACK contract tests, compileall, task validation and diff check
|
||||
passed. The fresh worker could not deliver worker_done through its
|
||||
workspace-write sandbox because Orca relay/FUSE was unavailable;
|
||||
Coordinator preserved the terminal evidence in Orca task
|
||||
task_ed87b3386a80 and did not treat it as final verification.
|
||||
testRound1: >
|
||||
Fresh Test term_ab858ba7-b972-45fb-bf50-61e96ced2830 created the
|
||||
isolated E2E fixture and found secret-safe output failing while all
|
||||
other targeted signals passed. Evidence is retained in Orca task
|
||||
task_251a9b5265cd; Test relay was unavailable for the same sandbox
|
||||
reason, so this remains a failed retest rather than verification.
|
||||
developerRound2: >
|
||||
Fresh Developer term_d1b02227-6bd6-4bd3-a432-bb50f64fca8c changed
|
||||
sourceRef to a domain-separated SHA-256 digest and kept file tokens
|
||||
internal to download calls. Focused unit, ACK contract, read-only E2E,
|
||||
compileall and diff checks passed; independent round-2 Test is still
|
||||
required.
|
||||
coordinatorGateRound2: >
|
||||
Targeted Test evidence was green, but final source-contract review
|
||||
against official larksuite/cli cmd/profile/list.go rejected the round:
|
||||
actual profile list output is a JSON array, the command exposes no
|
||||
format flag, and the current reader resolves lark-cli through caller
|
||||
PATH rather than fixed trusted directories.
|
||||
developerRound3: >
|
||||
Fresh Developer term_88079d90-29a3-48ac-9b97-bec011abc249 added the
|
||||
trusted resolver, official raw profile-list and data.data parsing,
|
||||
strict envelopes, sanitized execution PATH, revised unit coverage and
|
||||
complete setup/source examples. Five focused unit tests, 34 ACK
|
||||
contracts (one skipped), compileall, task validation and diff check
|
||||
passed; final independent Test remains required.
|
||||
testRound3: >
|
||||
Fresh Test term_44ab2675-445a-4f51-a0f5-83960bc1ca3b passed six
|
||||
isolated E2E cases and all five Feishu unit tests. It exercised the
|
||||
production entry points with a real fake-CLI subprocess and a separate
|
||||
submitted-bug JSON file, downloaded a screenshot into a temporary
|
||||
directory, repeated the fetch to prove a stable opaque sourceRef, and
|
||||
simulated ACK source.ref organization without duplicates. The four
|
||||
failures in the wider legacy suite reproduce unchanged on base commit
|
||||
f08edb6 and are classified as existing environment/layout failures.
|
||||
Orca worker_done transport was unavailable inside the worker sandbox
|
||||
because FUSE was absent; the full fresh-terminal evidence is retained
|
||||
in Orca task task_4f70d2496d13.
|
||||
+12
-3
@@ -96,14 +96,18 @@ description: >-
|
||||
docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml --project-root <project-root>`
|
||||
校验交付能力、顺序、安全边界和跨文件引用。只报告证据明确的问题，不因旧项目
|
||||
缺少可选交付配置而宣称失败。
|
||||
5. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且
|
||||
5. 若存在 `project.bugIntake`，运行
|
||||
`python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml`。
|
||||
它只接受 `feishu-base` 和显式 profile；详细的飞书配置、凭据初始化和读取方式见
|
||||
`references/feishu-bug-intake.md`。
|
||||
6. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且
|
||||
`stale`、`superseded` 和 `archived` 不会被当作可派发的 `active` 知识。
|
||||
6. 若存在 `project.orchestration`，检查 profile、model allowlist、默认 profile、
|
||||
7. 若存在 `project.orchestration`，检查 profile、model allowlist、默认 profile、
|
||||
允许 worktree、顶层 `workerReceipts` 与 `dispatch.developer/test` 的引用；receipt
|
||||
必须绑定当前 ACK task、同一 role/profile/attempt，`receiptId` 与 `attemptId`
|
||||
必须同时为空或同时填写。
|
||||
缺少结构化路由的旧任务板只能使用手动模式，不能自动创建 worker。
|
||||
7. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
|
||||
8. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
|
||||
|
||||
## 工作
|
||||
|
||||
@@ -121,6 +125,11 @@ description: >-
|
||||
worker 启动规则。项目覆盖层优先于通用示例命令。按 scope 推荐相关 `active`
|
||||
知识，经确认后把固定 revision 的显式 `knowledgeRefs` 写入当前任务上下文；
|
||||
不全量注入知识库。
|
||||
配置了 `project.bugIntake` 时，先按 `references/feishu-bug-intake.md` 运行 check，
|
||||
再运行 plan 获取标准化记录及 `create` / `refresh` / `unchanged` / `drift` 整理动作。
|
||||
按每条记录的 `sourceRef` 去重：仅 `open` 任务可刷新描述；
|
||||
`dispatched`、`fixed_by_dev`、`retesting`、`failed_retest`、`verified`、`blocked` 和
|
||||
`leftover` 只报告来源漂移，绝不覆盖；来源消失或读取失败时绝不删除已有任务。
|
||||
4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 `tasks.yaml` 并校验，
|
||||
然后交给用户确认；若启用了交付，还要把本次 profile、目标、停止点和需要审批的
|
||||
步骤放入同一份计划。确认前不派发实现，也不执行交付。
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
0.11.0
|
||||
0.12.0
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# notes-web Agent 协作协议（示例，项目覆盖层）
|
||||
|
||||
> 本项目基于 ack v0.11.0。
|
||||
> 本项目基于 ack v0.12.0。
|
||||
> 通用规范由 `/ack` 从 Skill 自身的 `references/` 读取，本文件只填项目差异。
|
||||
> 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
|
||||
> ACK 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
version: 1
|
||||
updatedAt: "2026-07-06T09:40:00+08:00"
|
||||
source: "Coordinator (PM) Agent"
|
||||
ackVersion: "0.11.0"
|
||||
ackVersion: "0.12.0"
|
||||
project:
|
||||
name: "notes-web"
|
||||
repoPath: "/home/dev/notes-web"
|
||||
@@ -104,6 +104,12 @@ tasks:
|
||||
evidence: "服务实例、worktree 与 commit 9f8e7d6 一致"
|
||||
checkedBy: "test-worker-1"
|
||||
checkedAt: "2026-07-06T09:36:00+08:00"
|
||||
# 飞书导入时使用不透明 digest；不要在 source.ref 中放 profile、Base、table 或 record ID。
|
||||
source:
|
||||
kind: "feishu-base"
|
||||
ref: "feishu-base:sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||||
recordId: "recExample"
|
||||
updatedAt: "2026-07-06T09:00:00Z"
|
||||
description: >
|
||||
用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
|
||||
stepsToReproduce:
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
# 飞书 Base Bug 收件箱
|
||||
|
||||
这是可选的只读接入。项目在 `docs/ack/tasks.yaml` 的 `project.bugIntake` 声明
|
||||
`provider: feishu-base`、显式 `profile`、`baseToken`、`tableId`、ACK Ready 的 `viewId`
|
||||
和八个字段映射；不要保存 App Secret、access token 或任何 profile 凭据。
|
||||
|
||||
## 一次性安装与 profile 设置
|
||||
|
||||
在账号级可信工具目录安装官方 CLI；ACK 读取器只会搜索账号的 `~/.local/bin`、mise/cargo
|
||||
shim 目录和固定系统目录，绝不会采用项目 `PATH` 中的同名文件。它同时识别官方 npm
|
||||
包生成的 `lark-cli -> @larksuite/cli/scripts/run.js` wrapper，并校验 package 名与 bin
|
||||
映射，然后直接执行该官方包下载的 native binary；这样不依赖 nvm PATH，也不会让 Node
|
||||
运行时变量进入凭据边界。缺少 native binary 或同名仿冒 wrapper 都会被拒绝：
|
||||
|
||||
```bash
|
||||
npm install --global --prefix "$HOME/.local" @larksuite/cli@latest
|
||||
```
|
||||
|
||||
固定 `--prefix "$HOME/.local"` 是接入契约的一部分，确保 npm wrapper 落在读取器会检查的
|
||||
账号级可信目录；不要依赖 nvm 或其它由当前 shell 动态注入的 PATH 位置。
|
||||
|
||||
随后在受控终端中用 stdin 提供 App Secret，选择 Feishu brand，避免 secret 进入 shell
|
||||
history、进程参数或项目文件：
|
||||
|
||||
```bash
|
||||
printf '%s' "$FEISHU_APP_SECRET" | lark-cli profile add \
|
||||
--name project-feishu --app-id "$FEISHU_APP_ID" \
|
||||
--app-secret-stdin --brand feishu
|
||||
```
|
||||
|
||||
随后在 project 配置里只填写 `profile: project-feishu`。不要执行 `profile use`，也不要
|
||||
依赖 active profile；每次读取和附件下载都由 adapter 显式传 `--profile project-feishu`。
|
||||
为读取记录和下载附件，profile 必须具有 `base:record:read` 和
|
||||
`docs:document.media:download`。请在飞书开发者后台的应用权限中为该 app 授予这两个
|
||||
scope；不要把 `lark-cli auth check` 当作 app/bot scope 的证明，因为它检查的是当前用户的
|
||||
stored user token。
|
||||
|
||||
## 使用
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml
|
||||
tmpdir=$(mktemp -d)
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py fetch docs/ack/tasks.yaml \
|
||||
--output-dir "$tmpdir"
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py plan docs/ack/tasks.yaml \
|
||||
--output-dir "$tmpdir"
|
||||
```
|
||||
|
||||
`fetch` 只调用官方 `base +record-list`（限定配置的 view 和字段）和按配置附件字段的
|
||||
`base +record-download-attachment`。它输出单一 JSON，验证行矩阵、分页和下载路径；CLI、
|
||||
profile、JSON、分页、附件或路径任一异常都会失败且不输出伪成功结果。
|
||||
|
||||
`plan` 在同一批标准化记录上读取现有 `tasks`，只输出整理计划而不修改文件：新来源为
|
||||
`create`，同来源且现有任务为 `open`、来源时间有变化时为 `refresh`，未变化为
|
||||
`unchanged`，其它 ACK 状态发生来源变化时为 `drift`。任务板或读取结果出现重复
|
||||
`sourceRef` 会直接失败。
|
||||
|
||||
子进程只收到实际账号 HOME、可信 PATH 和基础 locale；调用者环境中的
|
||||
`LARKSUITE_CLI_*`、`FEISHU_*`、`NODE_OPTIONS` 等变量不会传入，避免环境凭据或运行时
|
||||
注入绕过项目 profile。每条记录最多 10 个附件、单批最多 100 个，单个附件最多
|
||||
20 MiB、合计最多 200 MiB，整批附件下载最多 5 分钟，并校验声明大小与落盘大小；
|
||||
请始终使用新的临时目录作为 `--output-dir`。
|
||||
|
||||
`profile list` 只作存在性检查，不会输出 profile 内容。官方 record-list JSON 使用
|
||||
`data.fields`、`data.record_id_list` 与同长度的 `data.data` 行矩阵；`ok: true` 或
|
||||
`code: 0` 是唯一可接受的成功 envelope。
|
||||
|
||||
## Coordinator 整理
|
||||
|
||||
读取结果的每条 `sourceRef` 是稳定且不透明的键，例如
|
||||
`feishu-base:sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`。
|
||||
导入时写入 task 的
|
||||
`source.kind: feishu-base`、`source.ref`、`source.recordId` 与 `source.updatedAt`；先按
|
||||
`source.ref` 查重。相同来源只更新 `open` 任务；`dispatched`、`fixed_by_dev`、
|
||||
`retesting`、`failed_retest`、`verified`、`blocked` 和 `leftover` 任务只告警来源漂移，
|
||||
由用户决定是否新建任务；飞书记录消失、不可访问或同步失败时，已有 ACK 任务一律保留。
|
||||
@@ -0,0 +1,583 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Read an ACK-ready Feishu Base view through the official lark-cli.
|
||||
|
||||
This is deliberately a small, non-mutating adapter. It never reads the
|
||||
active profile and emits one JSON document only on success.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import math
|
||||
import os
|
||||
import pwd
|
||||
import re
|
||||
import resource
|
||||
import signal
|
||||
import stat
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from yaml_subset import DuplicateKeyError, YamlSubsetError, load_json_unique, load_yaml_subset, make_unique_pyyaml_loader
|
||||
|
||||
REQUIRED_FIELDS = ("title", "actual", "expected", "stepsToReproduce", "acceptance", "priority", "attachments", "updatedAt")
|
||||
MAX_PAGES = 100
|
||||
MAX_RECORDS = 10_000
|
||||
PAGE_SIZE = 100
|
||||
MAX_CLI_STDOUT = 1024 * 1024
|
||||
MAX_CLI_STDERR = 64 * 1024
|
||||
MAX_ATTACHMENTS_PER_RECORD = 10
|
||||
MAX_TOTAL_ATTACHMENTS = 100
|
||||
MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024
|
||||
MAX_TOTAL_ATTACHMENT_BYTES = 200 * 1024 * 1024
|
||||
MAX_ATTACHMENT_BATCH_SECONDS = 300
|
||||
SAFE_VALUE = re.compile(r"^[^\s\x00-\x1f]{1,256}$")
|
||||
PROFILE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
||||
RECORD_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$")
|
||||
SOURCE_REF = re.compile(r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
|
||||
|
||||
class IntakeError(Exception):
|
||||
pass
|
||||
|
||||
|
||||
def account_home() -> Path:
|
||||
"""Return the actual account home, never a caller-controlled HOME value."""
|
||||
try:
|
||||
home = Path(pwd.getpwuid(os.getuid()).pw_dir).resolve(strict=True)
|
||||
except (KeyError, OSError) as exc:
|
||||
raise IntakeError("cannot resolve current account home") from exc
|
||||
if not home.is_dir():
|
||||
raise IntakeError("current account home is not a directory")
|
||||
return home
|
||||
|
||||
|
||||
def trusted_lark_cli_dirs() -> list[Path]:
|
||||
"""Fixed account and system locations; intentionally never consult PATH."""
|
||||
home = account_home()
|
||||
candidates = (
|
||||
home / ".local" / "bin",
|
||||
home / ".local" / "share" / "mise" / "shims",
|
||||
home / ".cargo" / "bin",
|
||||
Path("/home/linuxbrew/.linuxbrew/bin"),
|
||||
Path("/usr/local/go/bin"),
|
||||
Path("/usr/local/bin"),
|
||||
Path("/usr/bin"),
|
||||
Path("/bin"),
|
||||
)
|
||||
result: list[Path] = []
|
||||
for candidate in candidates:
|
||||
try:
|
||||
resolved = candidate.resolve(strict=True)
|
||||
except OSError:
|
||||
continue
|
||||
if resolved.is_dir() and resolved not in result:
|
||||
result.append(resolved)
|
||||
return result
|
||||
|
||||
|
||||
def resolve_lark_cli() -> Path:
|
||||
"""Resolve a safe lark-cli from the fixed trusted locations only."""
|
||||
for directory in trusted_lark_cli_dirs():
|
||||
candidate = directory / "lark-cli"
|
||||
try:
|
||||
candidate_metadata = os.lstat(candidate)
|
||||
resolved = candidate.resolve(strict=True)
|
||||
metadata = resolved.stat()
|
||||
except OSError:
|
||||
continue
|
||||
if not (stat.S_ISREG(candidate_metadata.st_mode) or stat.S_ISLNK(candidate_metadata.st_mode)):
|
||||
continue
|
||||
if candidate_metadata.st_uid not in {0, os.getuid()}:
|
||||
continue
|
||||
if not stat.S_ISREG(metadata.st_mode) or not os.access(resolved, os.X_OK):
|
||||
continue
|
||||
if metadata.st_uid not in {0, os.getuid()} or stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
continue
|
||||
if resolved.name == "lark-cli":
|
||||
return resolved
|
||||
if not stat.S_ISLNK(candidate_metadata.st_mode):
|
||||
continue
|
||||
official_binary = official_npm_binary(resolved)
|
||||
if official_binary is not None:
|
||||
return official_binary
|
||||
raise IntakeError("lark-cli is not installed in a trusted account or system directory")
|
||||
|
||||
|
||||
def official_npm_binary(path: Path) -> Path | None:
|
||||
"""Resolve a validated npm wrapper to its downloaded native CLI binary."""
|
||||
if path.name != "run.js" or path.parent.name != "scripts":
|
||||
return None
|
||||
manifest = path.parent.parent / "package.json"
|
||||
try:
|
||||
metadata = manifest.stat()
|
||||
if not stat.S_ISREG(metadata.st_mode):
|
||||
return None
|
||||
if metadata.st_uid not in {0, os.getuid()} or stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
return None
|
||||
package = json.loads(manifest.read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeError, json.JSONDecodeError):
|
||||
return None
|
||||
if not (
|
||||
isinstance(package, dict)
|
||||
and package.get("name") == "@larksuite/cli"
|
||||
and isinstance(package.get("bin"), dict)
|
||||
and package["bin"].get("lark-cli") == "scripts/run.js"
|
||||
):
|
||||
return None
|
||||
native = path.parent.parent / "bin" / "lark-cli"
|
||||
try:
|
||||
native_lstat = os.lstat(native)
|
||||
resolved = native.resolve(strict=True)
|
||||
metadata = resolved.stat()
|
||||
except OSError:
|
||||
return None
|
||||
if not stat.S_ISREG(native_lstat.st_mode) or resolved.name != "lark-cli":
|
||||
return None
|
||||
if not stat.S_ISREG(metadata.st_mode) or not os.access(resolved, os.X_OK):
|
||||
return None
|
||||
if metadata.st_uid not in {0, os.getuid()} or stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
return None
|
||||
return resolved
|
||||
|
||||
|
||||
def cli_environment() -> dict[str, str]:
|
||||
"""Build a minimal environment so env credentials cannot override `--profile`."""
|
||||
environment = {
|
||||
"HOME": str(account_home()),
|
||||
"PATH": os.pathsep.join(str(path) for path in trusted_lark_cli_dirs()),
|
||||
}
|
||||
for name in ("LANG", "LC_ALL", "LC_CTYPE"):
|
||||
value = os.environ.get(name)
|
||||
if value and "\x00" not in value and len(value) <= 256:
|
||||
environment[name] = value
|
||||
return environment
|
||||
|
||||
|
||||
def load_board(path: Path) -> dict[str, Any]:
|
||||
try:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
if path.suffix.lower() == ".json":
|
||||
value = load_json_unique(text)
|
||||
else:
|
||||
try:
|
||||
import yaml # type: ignore
|
||||
value = yaml.load(text, Loader=make_unique_pyyaml_loader(yaml))
|
||||
except ImportError:
|
||||
value = load_yaml_subset(text)
|
||||
except (OSError, json.JSONDecodeError, DuplicateKeyError, YamlSubsetError) as exc:
|
||||
raise IntakeError(f"cannot read task board: {exc}") from exc
|
||||
except Exception as exc: # PyYAML errors are intentionally not exposed verbatim.
|
||||
raise IntakeError("cannot parse task board") from exc
|
||||
if not isinstance(value, dict):
|
||||
raise IntakeError("task board must be an object")
|
||||
return value
|
||||
|
||||
|
||||
def config_from_board(board: dict[str, Any]) -> dict[str, Any]:
|
||||
project = board.get("project")
|
||||
if not isinstance(project, dict) or "bugIntake" not in project:
|
||||
raise IntakeError("project.bugIntake is not configured")
|
||||
config = project["bugIntake"]
|
||||
if not isinstance(config, dict):
|
||||
raise IntakeError("project.bugIntake must be an object")
|
||||
allowed = {"provider", "profile", "baseToken", "tableId", "viewId", "fields"}
|
||||
unknown = sorted(set(config) - allowed)
|
||||
if unknown:
|
||||
raise IntakeError("bugIntake has unknown fields")
|
||||
if config.get("provider") != "feishu-base":
|
||||
raise IntakeError("bugIntake.provider must be feishu-base")
|
||||
profile = config.get("profile")
|
||||
if not isinstance(profile, str) or not PROFILE.fullmatch(profile):
|
||||
raise IntakeError("bugIntake.profile is invalid")
|
||||
for key in ("baseToken", "tableId", "viewId"):
|
||||
value = config.get(key)
|
||||
if not isinstance(value, str) or not SAFE_VALUE.fullmatch(value):
|
||||
raise IntakeError(f"bugIntake.{key} is invalid")
|
||||
fields = config.get("fields")
|
||||
if not isinstance(fields, dict) or set(fields) != set(REQUIRED_FIELDS):
|
||||
raise IntakeError("bugIntake.fields must map exactly the required logical fields")
|
||||
if any(not isinstance(value, str) or not SAFE_VALUE.fullmatch(value) for value in fields.values()):
|
||||
raise IntakeError("bugIntake.fields values are invalid")
|
||||
if len(set(fields.values())) != len(fields):
|
||||
raise IntakeError("bugIntake.fields values must be unique")
|
||||
return config
|
||||
|
||||
|
||||
def limit_child_file_size(limit: int) -> None:
|
||||
"""Bound regular-file writes by the CLI and any child spawned by its wrapper."""
|
||||
_, hard = resource.getrlimit(resource.RLIMIT_FSIZE)
|
||||
bounded = limit if hard == resource.RLIM_INFINITY else min(limit, hard)
|
||||
resource.setrlimit(resource.RLIMIT_FSIZE, (bounded, bounded))
|
||||
|
||||
|
||||
def run_cli(
|
||||
args: list[str], *, allow_profile_list: bool = False, max_file_bytes: int = 0,
|
||||
timeout: float = 60, cwd: Path | None = None,
|
||||
) -> Any:
|
||||
"""Run the official CLI and accept only explicit successful JSON shapes."""
|
||||
executable = resolve_lark_cli()
|
||||
file_limit = max(MAX_CLI_STDOUT, MAX_CLI_STDERR, max_file_bytes)
|
||||
with tempfile.TemporaryFile() as stdout_file, tempfile.TemporaryFile() as stderr_file:
|
||||
try:
|
||||
process = subprocess.Popen(
|
||||
[str(executable), *args],
|
||||
shell=False,
|
||||
stdin=subprocess.DEVNULL,
|
||||
stdout=stdout_file,
|
||||
stderr=stderr_file,
|
||||
env=cli_environment(),
|
||||
cwd=cwd,
|
||||
start_new_session=True,
|
||||
preexec_fn=lambda: limit_child_file_size(file_limit),
|
||||
)
|
||||
try:
|
||||
returncode = process.wait(timeout=timeout)
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
try:
|
||||
os.killpg(process.pid, signal.SIGKILL)
|
||||
except ProcessLookupError:
|
||||
pass
|
||||
process.wait()
|
||||
raise IntakeError("lark-cli failed to execute") from exc
|
||||
except (OSError, subprocess.SubprocessError) as exc:
|
||||
raise IntakeError("lark-cli failed to execute") from exc
|
||||
stdout_size = os.fstat(stdout_file.fileno()).st_size
|
||||
stderr_size = os.fstat(stderr_file.fileno()).st_size
|
||||
if stdout_size > MAX_CLI_STDOUT or stderr_size > MAX_CLI_STDERR:
|
||||
raise IntakeError("lark-cli output exceeded the safety limit")
|
||||
if returncode:
|
||||
raise IntakeError("lark-cli command failed")
|
||||
stdout_file.seek(0)
|
||||
try:
|
||||
stdout = stdout_file.read(MAX_CLI_STDOUT + 1).decode("utf-8")
|
||||
except UnicodeDecodeError as exc:
|
||||
raise IntakeError("lark-cli returned malformed JSON") from exc
|
||||
try:
|
||||
value = json.loads(
|
||||
stdout,
|
||||
parse_constant=lambda value: (_ for _ in ()).throw(
|
||||
ValueError(f"non-finite JSON constant: {value}")
|
||||
),
|
||||
)
|
||||
except (json.JSONDecodeError, ValueError) as exc:
|
||||
raise IntakeError("lark-cli returned malformed JSON") from exc
|
||||
if isinstance(value, list):
|
||||
if allow_profile_list:
|
||||
return value
|
||||
raise IntakeError("lark-cli returned an unexpected JSON array")
|
||||
if not isinstance(value, dict):
|
||||
raise IntakeError("lark-cli returned an invalid JSON response")
|
||||
if "ok" in value and value["ok"] is not True:
|
||||
raise IntakeError("lark-cli returned an error response")
|
||||
if "code" in value and (not isinstance(value["code"], int) or isinstance(value["code"], bool) or value["code"] != 0):
|
||||
raise IntakeError("lark-cli returned an error response")
|
||||
if "ok" not in value and "code" not in value:
|
||||
raise IntakeError("lark-cli returned an ambiguous JSON response")
|
||||
return value
|
||||
|
||||
|
||||
def profile_check(config: dict[str, Any]) -> None:
|
||||
# `profile list` is the official non-mutating profile inspection command.
|
||||
value = run_cli(["profile", "list"], allow_profile_list=True)
|
||||
if isinstance(value, list):
|
||||
profiles = value
|
||||
else:
|
||||
# Compatibility wrapper: only a successful envelope with a direct list
|
||||
# is accepted. Do not loosen this into arbitrary nested objects.
|
||||
profiles = value.get("data")
|
||||
if not isinstance(profiles, list):
|
||||
raise IntakeError("profile check returned an invalid response")
|
||||
matching_profile: dict[str, Any] | None = None
|
||||
for item in profiles:
|
||||
# Match the official profile-list item shape. `user` and
|
||||
# `tokenStatus` are optional and deliberately never propagated.
|
||||
if (
|
||||
not isinstance(item, dict)
|
||||
or not isinstance(item.get("name"), str)
|
||||
or not PROFILE.fullmatch(item["name"])
|
||||
or not isinstance(item.get("appId"), str)
|
||||
or not isinstance(item.get("brand"), str)
|
||||
or not isinstance(item.get("active"), bool)
|
||||
):
|
||||
raise IntakeError("profile check returned an invalid profile entry")
|
||||
if item["name"] == config["profile"]:
|
||||
matching_profile = item
|
||||
if matching_profile is None:
|
||||
raise IntakeError("configured lark-cli profile does not exist")
|
||||
if matching_profile["brand"] != "feishu":
|
||||
raise IntakeError("configured lark-cli profile must use the feishu brand")
|
||||
|
||||
|
||||
def text(value: Any) -> str:
|
||||
if value is None:
|
||||
return ""
|
||||
if isinstance(value, str):
|
||||
return " ".join(value.split())
|
||||
if isinstance(value, float) and not math.isfinite(value):
|
||||
raise IntakeError("text field contains a non-finite number")
|
||||
if isinstance(value, (int, float, bool)):
|
||||
return str(value)
|
||||
if isinstance(value, list):
|
||||
return "\n".join(part for part in (text(item) for item in value) if part)
|
||||
if isinstance(value, dict):
|
||||
for key in ("text", "name", "value"):
|
||||
if key in value:
|
||||
return text(value[key])
|
||||
raise IntakeError("text field contains an unsupported object")
|
||||
raise IntakeError("text field contains an unsupported value")
|
||||
|
||||
|
||||
def attachment_items(value: Any) -> list[tuple[dict[str, Any], str]]:
|
||||
if value in (None, ""):
|
||||
return []
|
||||
if not isinstance(value, list):
|
||||
raise IntakeError("attachments cell must be a list")
|
||||
if len(value) > MAX_ATTACHMENTS_PER_RECORD:
|
||||
raise IntakeError("record exceeded the attachment count limit")
|
||||
attachments: list[tuple[dict[str, Any], str]] = []
|
||||
for item in value:
|
||||
if not isinstance(item, dict):
|
||||
raise IntakeError("attachment metadata must be an object")
|
||||
token = item.get("file_token", item.get("token"))
|
||||
if not isinstance(token, str) or not SAFE_VALUE.fullmatch(token):
|
||||
raise IntakeError("attachment token is invalid")
|
||||
metadata = {"name": text(item.get("name")), "type": text(item.get("type", item.get("mime_type"))), "size": item.get("size")}
|
||||
if (
|
||||
not isinstance(metadata["size"], int)
|
||||
or isinstance(metadata["size"], bool)
|
||||
or metadata["size"] < 0
|
||||
or metadata["size"] > MAX_ATTACHMENT_BYTES
|
||||
):
|
||||
raise IntakeError("attachment size is invalid")
|
||||
attachments.append((metadata, token))
|
||||
return attachments
|
||||
|
||||
|
||||
def matrix_from_response(response: dict[str, Any], field_ids: list[str]) -> tuple[list[str], list[list[Any]]]:
|
||||
data = response.get("data", response)
|
||||
if not isinstance(data, dict):
|
||||
raise IntakeError("record list data is invalid")
|
||||
fields = data.get("fields")
|
||||
ids = data.get("record_id_list", data.get("recordIds"))
|
||||
rows = data.get("data", data.get("records", data.get("items", data.get("rows"))))
|
||||
if not isinstance(fields, list) or not all(isinstance(x, str) for x in fields):
|
||||
raise IntakeError("record list fields are invalid")
|
||||
if fields != field_ids:
|
||||
raise IntakeError("record list fields do not match configured projection")
|
||||
if not isinstance(ids, list) or not all(isinstance(x, str) and RECORD_ID.fullmatch(x) for x in ids):
|
||||
raise IntakeError("record list record_id_list is invalid")
|
||||
if not isinstance(rows, list) or len(rows) != len(ids) or any(not isinstance(row, list) or len(row) != len(fields) for row in rows):
|
||||
raise IntakeError("record list matrix does not match fields and record_id_list")
|
||||
return ids, rows
|
||||
|
||||
|
||||
def fetch_pages(config: dict[str, Any]) -> list[tuple[str, list[Any]]]:
|
||||
field_ids = [config["fields"][logical] for logical in REQUIRED_FIELDS]
|
||||
all_rows: list[tuple[str, list[Any]]] = []
|
||||
offset = 0
|
||||
for _ in range(MAX_PAGES):
|
||||
args = ["base", "+record-list", "--profile", config["profile"], "--base-token", config["baseToken"], "--table-id", config["tableId"], "--view-id", config["viewId"], "--format", "json", "--offset", str(offset), "--limit", str(PAGE_SIZE)]
|
||||
for field_id in field_ids:
|
||||
args.extend(["--field-id", field_id])
|
||||
response = run_cli(args)
|
||||
ids, rows = matrix_from_response(response, field_ids)
|
||||
if len(ids) > PAGE_SIZE:
|
||||
raise IntakeError("record list exceeded requested page size")
|
||||
all_rows.extend(zip(ids, rows))
|
||||
if len(all_rows) > MAX_RECORDS:
|
||||
raise IntakeError("record list exceeded record limit")
|
||||
data = response.get("data", response)
|
||||
has_more = data.get("has_more", data.get("hasMore", False))
|
||||
if not isinstance(has_more, bool):
|
||||
raise IntakeError("record list pagination marker is invalid")
|
||||
if not has_more:
|
||||
return all_rows
|
||||
if not ids:
|
||||
raise IntakeError("record list pagination made no progress")
|
||||
offset += len(ids)
|
||||
raise IntakeError("record list exceeded page limit")
|
||||
|
||||
|
||||
def download(
|
||||
config: dict[str, Any], record_id: str, file_token: str,
|
||||
output_dir: Path, expected_size: int, timeout: float,
|
||||
) -> str:
|
||||
try:
|
||||
output_dir.mkdir(parents=True, exist_ok=False)
|
||||
except OSError as exc:
|
||||
raise IntakeError("attachment output directory is unsafe") from exc
|
||||
if not output_dir.is_dir() or output_dir.is_symlink():
|
||||
raise IntakeError("attachment output directory is unsafe")
|
||||
run_cli(
|
||||
["base", "+record-download-attachment", "--profile", config["profile"], "--base-token", config["baseToken"], "--table-id", config["tableId"], "--record-id", record_id, "--file-token", file_token, "--output", output_dir.name],
|
||||
max_file_bytes=expected_size,
|
||||
timeout=timeout,
|
||||
cwd=output_dir.parent,
|
||||
)
|
||||
try:
|
||||
created = list(output_dir.iterdir())
|
||||
except OSError as exc:
|
||||
raise IntakeError("attachment download output is unreadable") from exc
|
||||
if len(created) != 1 or not created[0].is_file() or created[0].is_symlink():
|
||||
raise IntakeError("attachment download did not produce one safe file")
|
||||
root = output_dir.resolve()
|
||||
resolved = created[0].resolve()
|
||||
if root not in resolved.parents:
|
||||
raise IntakeError("attachment download escaped output directory")
|
||||
if resolved.stat().st_size != expected_size:
|
||||
raise IntakeError("attachment download size did not match metadata")
|
||||
return str(resolved)
|
||||
|
||||
|
||||
def source_ref(config: dict[str, Any], record_id: str) -> str:
|
||||
"""Return a stable opaque identity without serializing configured identifiers."""
|
||||
identity = "\x1f".join(("ack-feishu-base-source-ref-v1", config["profile"], config["baseToken"], config["tableId"], record_id))
|
||||
return f"feishu-base:sha256:{hashlib.sha256(identity.encode('utf-8')).hexdigest()}"
|
||||
|
||||
|
||||
def fetch(config: dict[str, Any], output_dir: Path | None) -> dict[str, Any]:
|
||||
profile_check(config)
|
||||
prepared: list[tuple[dict[str, Any], list[tuple[dict[str, Any], str]]]] = []
|
||||
total_attachments = 0
|
||||
total_attachment_bytes = 0
|
||||
for record_id, row in fetch_pages(config):
|
||||
cells = dict(zip(REQUIRED_FIELDS, row))
|
||||
attachment_data = attachment_items(cells["attachments"])
|
||||
total_attachments += len(attachment_data)
|
||||
total_attachment_bytes += sum(metadata["size"] for metadata, _ in attachment_data)
|
||||
if total_attachments > MAX_TOTAL_ATTACHMENTS:
|
||||
raise IntakeError("batch exceeded the attachment count limit")
|
||||
if total_attachment_bytes > MAX_TOTAL_ATTACHMENT_BYTES:
|
||||
raise IntakeError("batch exceeded the attachment byte limit")
|
||||
record = {"sourceRef": source_ref(config, record_id), "recordId": record_id, "updatedAt": text(cells["updatedAt"]), "title": text(cells["title"]), "actual": text(cells["actual"]), "expected": text(cells["expected"]), "steps": text(cells["stepsToReproduce"]), "acceptance": text(cells["acceptance"]), "priority": text(cells["priority"]), "attachments": [metadata for metadata, _ in attachment_data], "warnings": []}
|
||||
for field in ("title", "actual", "expected", "steps", "acceptance", "priority", "updatedAt"):
|
||||
if not record[field]:
|
||||
raise IntakeError(f"record {field} must not be empty")
|
||||
prepared.append((record, attachment_data))
|
||||
download_root: Path | None = None
|
||||
if output_dir is not None:
|
||||
try:
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
if not output_dir.is_dir() or output_dir.is_symlink():
|
||||
raise OSError("unsafe output directory")
|
||||
download_root = output_dir.resolve(strict=True)
|
||||
except OSError as exc:
|
||||
raise IntakeError("attachment output directory is unsafe") from exc
|
||||
records = []
|
||||
attachment_deadline = time.monotonic() + MAX_ATTACHMENT_BATCH_SECONDS
|
||||
for record, attachment_data in prepared:
|
||||
if download_root is not None:
|
||||
for index, (attachment, file_token) in enumerate(attachment_data, start=1):
|
||||
remaining = attachment_deadline - time.monotonic()
|
||||
if remaining <= 0:
|
||||
raise IntakeError("attachment batch exceeded the time limit")
|
||||
attachment_dir = download_root / record["recordId"] / f"attachment-{index:02d}"
|
||||
attachment["localPath"] = download(
|
||||
config, record["recordId"], file_token, attachment_dir,
|
||||
attachment["size"], min(60, remaining),
|
||||
)
|
||||
records.append(record)
|
||||
return {"provider": "feishu-base", "profile": config["profile"], "tableId": config["tableId"], "viewId": config["viewId"], "records": records}
|
||||
|
||||
|
||||
def plan_actions(board: dict[str, Any], records: list[dict[str, Any]]) -> list[dict[str, str]]:
|
||||
"""Plan idempotent Coordinator actions without mutating the task board."""
|
||||
tasks = board.get("tasks")
|
||||
if not isinstance(tasks, list):
|
||||
raise IntakeError("task board tasks must be a list")
|
||||
existing: dict[str, dict[str, Any]] = {}
|
||||
for task in tasks:
|
||||
if not isinstance(task, dict):
|
||||
continue
|
||||
source = task.get("source")
|
||||
if not isinstance(source, dict) or source.get("kind") != "feishu-base":
|
||||
continue
|
||||
ref = source.get("ref")
|
||||
task_id = task.get("id")
|
||||
status = task.get("status")
|
||||
updated_at = source.get("updatedAt")
|
||||
if (
|
||||
not isinstance(ref, str) or SOURCE_REF.fullmatch(ref) is None
|
||||
or not isinstance(task_id, str) or not task_id
|
||||
or not isinstance(status, str) or not status
|
||||
or not isinstance(updated_at, str) or not updated_at
|
||||
):
|
||||
raise IntakeError("existing Feishu task source is invalid")
|
||||
if ref in existing:
|
||||
raise IntakeError("task board contains duplicate Feishu source references")
|
||||
existing[ref] = task
|
||||
|
||||
actions: list[dict[str, str]] = []
|
||||
seen_records: set[str] = set()
|
||||
for record in records:
|
||||
ref = record.get("sourceRef")
|
||||
record_id = record.get("recordId")
|
||||
updated_at = record.get("updatedAt")
|
||||
if (
|
||||
not isinstance(ref, str) or SOURCE_REF.fullmatch(ref) is None
|
||||
or not isinstance(record_id, str) or RECORD_ID.fullmatch(record_id) is None
|
||||
or not isinstance(updated_at, str) or not updated_at
|
||||
):
|
||||
raise IntakeError("normalized Feishu record identity is invalid")
|
||||
if ref in seen_records:
|
||||
raise IntakeError("fetched records contain a duplicate source reference")
|
||||
seen_records.add(ref)
|
||||
task = existing.get(ref)
|
||||
if task is None:
|
||||
actions.append({"sourceRef": ref, "recordId": record_id, "action": "create"})
|
||||
continue
|
||||
source = task["source"]
|
||||
if source["updatedAt"] == updated_at:
|
||||
action = "unchanged"
|
||||
elif task["status"] == "open":
|
||||
action = "refresh"
|
||||
else:
|
||||
action = "drift"
|
||||
actions.append({
|
||||
"sourceRef": ref,
|
||||
"recordId": record_id,
|
||||
"taskId": task["id"],
|
||||
"status": task["status"],
|
||||
"action": action,
|
||||
})
|
||||
return actions
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(description="Read a configured Feishu Base bug intake")
|
||||
sub = parser.add_subparsers(dest="command", required=True)
|
||||
for name in ("check", "fetch", "plan"):
|
||||
command = sub.add_parser(name)
|
||||
command.add_argument("tasks", type=Path, help="ACK tasks.yaml or JSON board")
|
||||
if name in {"fetch", "plan"}:
|
||||
command.add_argument("--output-dir", type=Path, help="explicit directory for downloaded attachments")
|
||||
args = parser.parse_args(argv)
|
||||
try:
|
||||
board = load_board(args.tasks)
|
||||
config = config_from_board(board)
|
||||
if args.command == "check":
|
||||
profile_check(config)
|
||||
output = {"provider": "feishu-base", "profile": config["profile"], "ok": True}
|
||||
elif args.command == "fetch":
|
||||
output = fetch(config, args.output_dir)
|
||||
else:
|
||||
output = fetch(config, args.output_dir)
|
||||
output["actions"] = plan_actions(board, output["records"])
|
||||
except IntakeError as exc:
|
||||
sys.stderr.write(f"Feishu bug intake failed: {exc}\n")
|
||||
return 1
|
||||
except (OSError, subprocess.SubprocessError):
|
||||
sys.stderr.write("Feishu bug intake failed: local I/O failed\n")
|
||||
return 1
|
||||
print(json.dumps(output, ensure_ascii=False, separators=(",", ":")))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -113,6 +113,15 @@ DELIVERY_STATUSES = {
|
||||
}
|
||||
DELIVERY_ARTIFACT_FIELDS = {"id", "type", "reference", "digest"}
|
||||
DELIVERY_DEPLOYMENT_FIELDS = {"environment", "result", "evidence"}
|
||||
FEISHU_REQUIRED_FIELDS = {
|
||||
"title", "actual", "expected", "stepsToReproduce", "acceptance", "priority",
|
||||
"attachments", "updatedAt",
|
||||
}
|
||||
FEISHU_CONFIG_FIELDS = {"provider", "profile", "baseToken", "tableId", "viewId", "fields"}
|
||||
FEISHU_SOURCE_FIELDS = {"kind", "ref", "recordId", "updatedAt"}
|
||||
FEISHU_PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
||||
FEISHU_SOURCE_REF_RE = re.compile(r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
FEISHU_RECORD_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$")
|
||||
DISPATCH_FIELDS = {
|
||||
"taskId",
|
||||
"dispatchId",
|
||||
@@ -654,6 +663,28 @@ def validate_builtin(data: dict) -> list[str]:
|
||||
{"repoPath", "baseUrl", "devWorktree", "overlayFile", "deliveryFile"},
|
||||
"project",
|
||||
)
|
||||
if "bugIntake" in project:
|
||||
intake = project["bugIntake"]
|
||||
if not isinstance(intake, dict):
|
||||
errors.append("project.bugIntake 必须是对象")
|
||||
else:
|
||||
reject_unknown_fields(intake, FEISHU_CONFIG_FIELDS, "project.bugIntake", errors)
|
||||
if intake.get("provider") != "feishu-base":
|
||||
errors.append("project.bugIntake.provider 必须是 feishu-base")
|
||||
profile = intake.get("profile")
|
||||
if not isinstance(profile, str) or FEISHU_PROFILE_RE.fullmatch(profile) is None:
|
||||
errors.append("project.bugIntake.profile 非法")
|
||||
for key in ("baseToken", "tableId", "viewId"):
|
||||
value = intake.get(key)
|
||||
if not isinstance(value, str) or not value.strip() or any(char.isspace() for char in value):
|
||||
errors.append(f"project.bugIntake.{key} 必须是无空白非空字符串")
|
||||
fields = intake.get("fields")
|
||||
if not isinstance(fields, dict) or set(fields) != FEISHU_REQUIRED_FIELDS:
|
||||
errors.append("project.bugIntake.fields 必须且只能映射所需逻辑字段")
|
||||
elif any(not isinstance(v, str) or not v.strip() or any(c.isspace() for c in v) for v in fields.values()):
|
||||
errors.append("project.bugIntake.fields 字段值必须是无空白非空字符串")
|
||||
elif len(set(fields.values())) != len(fields):
|
||||
errors.append("project.bugIntake.fields 字段值不能重复")
|
||||
if (
|
||||
"knowledgeFile" in project
|
||||
and project.get("knowledgeFile") != "docs/ack/knowledge.yaml"
|
||||
@@ -710,6 +741,7 @@ def validate_builtin(data: dict) -> list[str]:
|
||||
return errors
|
||||
|
||||
seen_ids: set[str] = set()
|
||||
seen_source_refs: set[str] = set()
|
||||
for i, task in enumerate(tasks):
|
||||
where = f"tasks[{i}]"
|
||||
if not isinstance(task, dict):
|
||||
@@ -756,6 +788,25 @@ def validate_builtin(data: dict) -> list[str]:
|
||||
)
|
||||
validate_object_fields(task, {"evidence", "verification"}, where)
|
||||
|
||||
if "source" in task:
|
||||
source = task["source"]
|
||||
# `source` was historically an open extension point. Preserve
|
||||
# non-Feishu strings/objects and tighten only the namespaced shape.
|
||||
if isinstance(source, dict) and source.get("kind") == "feishu-base":
|
||||
reject_unknown_fields(source, FEISHU_SOURCE_FIELDS, f"{where}.source", errors)
|
||||
ref = source.get("ref")
|
||||
if not isinstance(ref, str) or FEISHU_SOURCE_REF_RE.fullmatch(ref) is None:
|
||||
errors.append(f"{where}.source.ref: 必须是不透明 feishu-base SHA-256 引用")
|
||||
else:
|
||||
if ref in seen_source_refs:
|
||||
errors.append(f"{where}.source.ref: 来源引用重复")
|
||||
seen_source_refs.add(ref)
|
||||
record_id = source.get("recordId")
|
||||
if not isinstance(record_id, str) or FEISHU_RECORD_ID_RE.fullmatch(record_id) is None:
|
||||
errors.append(f"{where}.source.recordId: 必须是合法飞书记录 ID")
|
||||
if not _nonempty_string(source.get("updatedAt")):
|
||||
errors.append(f"{where}.source.updatedAt: 必须是非空字符串")
|
||||
|
||||
validate_knowledge_fields(task, where, status, errors)
|
||||
|
||||
if "dispatch" not in task:
|
||||
|
||||
@@ -42,6 +42,7 @@
|
||||
"const": "docs/ack/delivery.yaml",
|
||||
"description": "可选项目交付契约的唯一权威路径"
|
||||
},
|
||||
"bugIntake": { "$ref": "#/definitions/feishuBugIntake" },
|
||||
"orchestration": {
|
||||
"$ref": "#/definitions/orchestration"
|
||||
}
|
||||
@@ -164,6 +165,50 @@
|
||||
"type": "string",
|
||||
"pattern": "^sha256:[0-9a-f]{64}$"
|
||||
},
|
||||
"feishuBugIntake": {
|
||||
"type": "object",
|
||||
"required": ["provider", "profile", "baseToken", "tableId", "viewId", "fields"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"provider": { "const": "feishu-base" },
|
||||
"profile": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
|
||||
"baseToken": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"tableId": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"viewId": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"fields": {
|
||||
"type": "object",
|
||||
"required": ["title", "actual", "expected", "stepsToReproduce", "acceptance", "priority", "attachments", "updatedAt"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"title": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"actual": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"expected": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"stepsToReproduce": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"acceptance": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"priority": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"attachments": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
|
||||
"updatedAt": { "type": "string", "minLength": 1, "pattern": "^\\S+$" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"feishuTaskSource": {
|
||||
"type": "object",
|
||||
"required": ["kind", "ref", "recordId", "updatedAt"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"kind": { "const": "feishu-base" },
|
||||
"ref": {
|
||||
"type": "string",
|
||||
"pattern": "^feishu-base:sha256:[0-9a-f]{64}$"
|
||||
},
|
||||
"recordId": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$"
|
||||
},
|
||||
"updatedAt": { "type": "string", "minLength": 1, "pattern": "\\S" }
|
||||
}
|
||||
},
|
||||
"profileId": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z][a-z0-9-]{1,63}$"
|
||||
@@ -940,6 +985,16 @@
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/knowledgeCheck" }
|
||||
},
|
||||
"source": {
|
||||
"if": {
|
||||
"type": "object",
|
||||
"required": ["kind"],
|
||||
"properties": { "kind": { "const": "feishu-base" } }
|
||||
},
|
||||
"then": {
|
||||
"$ref": "#/definitions/feishuTaskSource"
|
||||
}
|
||||
},
|
||||
"description": { "type": "string" },
|
||||
"stepsToReproduce": { "type": "array", "items": { "type": "string" } },
|
||||
"expected": { "type": "string" },
|
||||
|
||||
@@ -11,6 +11,22 @@ project:
|
||||
overlayFile: "docs/ack/project.md"
|
||||
knowledgeFile: "docs/ack/knowledge.yaml"
|
||||
deliveryFile: "docs/ack/delivery.yaml"
|
||||
# 可选：飞书 Base Bug 收件箱。只保存 profile 名和资源 ID，绝不保存 App Secret。
|
||||
# bugIntake:
|
||||
# provider: "feishu-base"
|
||||
# profile: "project-feishu"
|
||||
# baseToken: "<base_token>"
|
||||
# tableId: "<table_id>"
|
||||
# viewId: "<ack_ready_view_id>"
|
||||
# fields:
|
||||
# title: "<field_id>"
|
||||
# actual: "<field_id>"
|
||||
# expected: "<field_id>"
|
||||
# stepsToReproduce: "<field_id>"
|
||||
# acceptance: "<field_id>"
|
||||
# priority: "<field_id>"
|
||||
# attachments: "<field_id>"
|
||||
# updatedAt: "<field_id>"
|
||||
orchestration:
|
||||
profileVersion: 1
|
||||
mode: "orca"
|
||||
@@ -95,6 +111,13 @@ tasks:
|
||||
knowledgeCandidates: []
|
||||
knowledgeChecks: []
|
||||
|
||||
# 从飞书导入时由 Coordinator 写入；source.ref 是幂等键。
|
||||
# source:
|
||||
# kind: "feishu-base"
|
||||
# ref: "feishu-base:sha256:<64-lowercase-hex>"
|
||||
# recordId: "<record-id>"
|
||||
# updatedAt: "<source-updated-at>"
|
||||
|
||||
description: >
|
||||
<What is wrong, in user-visible terms.>
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# orc
|
||||
|
||||
ORC 是显式调用的工程编排入口：把开发、版本发布、DEB 和 Docker 任务拆成阶段，
|
||||
交给对应 Skill，并为每个执行 Agent 选择 `low`、`mid` 或 `high` 档位。
|
||||
|
||||
## 什么时候使用
|
||||
|
||||
- 一个请求同时包含写代码、发版本和构建产物。
|
||||
- 希望由 ORC 监督多个 Agent，并按阶段控制成本与推理能力。
|
||||
- 需要继续中断的多阶段工程流程并保留依赖关系。
|
||||
|
||||
只做单一领域任务时可以直接调用对应 Skill；ORC 不替代它们的安全规则。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
- Orca 正在运行并启用了 orchestration。
|
||||
- 安装本次需要的 `$ack`、`$manage-release`、`$deb-publisher` 或
|
||||
`$publish-docker-image`。
|
||||
- 运行 `$orc 初始化` 生成 `docs/orc/config.yaml`，确认三档对应的精确模型。
|
||||
- `/usr/bin/python3`；ORC v1 配置必须保持为内置模板使用的 JSON-compatible YAML。
|
||||
resolver 以 `-I -S` 隔离模式运行，不加载项目模块、用户 site-packages 或第三方解析器。
|
||||
- ORC v1 worker 使用 `workspace-write` sandbox，以便发送 Orca lifecycle 消息；
|
||||
只读任务会在阶段 prompt 中禁止文件修改。
|
||||
|
||||
## Agent 档位
|
||||
|
||||
| 档位 | 典型任务 |
|
||||
|------|----------|
|
||||
| `low` | 输入明确的测试、构建、打包和上传 |
|
||||
| `mid` | 常规版本发布与范围清晰的工程任务 |
|
||||
| `high` | 需求理解、跨系统改动、异常恢复和高风险裁决 |
|
||||
|
||||
档位不是权限。三个档位仍受各自 profile 和下游 Skill 的授权边界约束。
|
||||
当前 ORC v1 的结构化启动适配器支持 Codex worker；其它 Agent CLI 需要独立适配器，
|
||||
不会通过自由命令接入。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```text
|
||||
$orc high 修复登录问题，验证通过后发布新版本。
|
||||
$orc code=high release=mid docker=low，完成修复、发版并推送镜像。
|
||||
$orc mid 继续上次中断的 v1.4.0 发布流程。
|
||||
```
|
||||
|
||||
阶段级档位优先于全局档位。用户显式指定后，ORC 不会静默改档；能力不足时会暂停并
|
||||
请求确认。
|
||||
|
||||
## Agent 会做什么
|
||||
|
||||
1. 识别开发、源码发布、DEB 与 Docker 阶段及其依赖。
|
||||
2. 解析每个阶段的 Agent profile，把配置快照、可信 Codex executable 和真实 Git
|
||||
worktree 绑定成 launch fingerprint，并展示计划和外部写入边界。
|
||||
3. 通过 Orca 分发给对应 Skill，监督完成消息、异常和决策门。
|
||||
4. 汇总每个阶段的实际状态、证据和安全恢复入口。
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
最终结果会逐阶段列出所用 Skill、Agent 档位、源 revision、远端或产物状态，以及任何
|
||||
未完成项。只有所有必要阶段都通过各自验证时，ORC 才会报告整个流程完成。
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
name: orc
|
||||
description: >-
|
||||
显式编排开发、源码版本发布、DEB 和 Docker 产物任务，把阶段分发给对应 Skill，
|
||||
并用 low、mid、high 选择执行 Agent 档位。仅在用户显式调用 $orc 或 /orc，要求
|
||||
跨阶段协调、指定 Agent 级别、监督多个 worker 或继续 ORC 编排时使用。
|
||||
---
|
||||
|
||||
# ORC 工程编排入口
|
||||
|
||||
当前会话担任 Coordinator：拆分阶段、选择档位、派发 worker、监督依赖与决策门，
|
||||
但不替代下游 Skill 执行其领域流程。
|
||||
|
||||
开始时解析当前 `SKILL.md` 所在目录，记为 `<orc-skill-dir>`；解析真实项目根目录，
|
||||
优先使用 `git rev-parse --show-toplevel`。项目配置固定为
|
||||
`<project-root>/docs/orc/config.yaml`。
|
||||
|
||||
## 选择模式
|
||||
|
||||
- 用户要求初始化 ORC：执行“初始化”。
|
||||
- 用户要求检查 ORC、档位或运行环境：执行“检查”。
|
||||
- 用户要求用 ORC 完成任务：执行“编排”。
|
||||
|
||||
不要静默初始化，也不要在配置缺失或无效时退回裸命令或当前会话直接执行。
|
||||
|
||||
## 初始化
|
||||
|
||||
1. 若 `docs/orc/config.yaml` 已存在，停止创建并转入“检查”，不得覆盖。
|
||||
2. 确认 `docs/orc/` 和目标文件都不是 symlink，再从
|
||||
`<orc-skill-dir>/templates/config.template.yaml` 以 create-only 方式创建配置，不覆盖
|
||||
或跟随既有路径。ORC v1 配置必须保持 JSON-compatible YAML，只由隔离的 Python
|
||||
标准库解析；模板中的 `.` 表示当前项目根。模型 ID 必须由用户或项目的可信配置确认，
|
||||
不能从任务文本猜测。
|
||||
3. 运行：
|
||||
|
||||
```bash
|
||||
/usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py validate \
|
||||
<project-root>/docs/orc/config.yaml
|
||||
```
|
||||
|
||||
4. 报告三个档位的 CLI、模型、reasoning、权限和阶段默认值。除非用户明确要求，
|
||||
不安装下游 Skill、不创建终端、不修改 Agent 全局配置。
|
||||
|
||||
## 检查
|
||||
|
||||
1. 校验 `docs/orc/config.yaml`，确认只存在 `low`、`mid`、`high` 三档。
|
||||
2. 检查 `orca status --json`，并确认 orchestration 命令可用。
|
||||
3. 确认本次所需下游 Skill 已安装：`ack`、`manage-release`、`deb-publisher`、
|
||||
`publish-docker-image`。只检查实际会用到的项。
|
||||
4. 解析 profile 时把项目根和目标 worktree 一并交给 resolver；只有 resolver 验证目标
|
||||
命中 `allowedWorktrees`、属于当前 Git 仓库且身份稳定后才可创建终端。不得只做文本
|
||||
比较或跳过机器校验。
|
||||
5. 任何 profile、Skill、运行时或 worktree 不可用时 fail closed；不得选择相邻档位、
|
||||
复用身份不明的终端或手写替代流程。
|
||||
|
||||
## 编排
|
||||
|
||||
1. 读取 [routing.md](references/routing.md)，把请求拆成 `code`、`release`、`deb`、
|
||||
`docker` 阶段。没有匹配下游 Skill 的工作留在范围外并明确报告。
|
||||
2. 锁定用户授权的最远动作、目标版本、产物目标、源 commit/tag 与停止点。ORC 的调用
|
||||
本身不扩大 push、合并、打 tag、上传或部署权限；每个下游 Skill 的授权边界继续生效。
|
||||
3. 解析档位：阶段级指定 > 全局指定 > `stageDefaults` > `defaultLevel`。只接受
|
||||
`low`、`mid`、`high`；用户显式指定后不得静默升降级。若该档位不足以安全完成，
|
||||
建立 decision gate，等待用户改档或缩小范围。
|
||||
4. 用户未指定档位时采用以下判断：清晰、机械的构建或上传可用 `low`；常规版本流程
|
||||
用 `mid`；需求理解、跨系统改动、恢复中断流程、目标含糊或高风险裁决用 `high`。
|
||||
5. 对每个阶段运行 profile resolver。全局档位用 `--global-level`，阶段档位用
|
||||
`--stage-level`；项目根与目标 worktree 必须使用规范绝对路径。模型认证默认复用
|
||||
`codex-login`，只有明确使用对应环境凭据时才选 `openai` 或 `azure-openai`。远端认证
|
||||
默认 `none`；只有目标 provider 与 transport 已确认时，才选择一个精确的
|
||||
`github-token`、`gitlab-token`、`gitea-token`、`forgejo-token`、`ssh-agent` 或
|
||||
`deb-token`。不得把多个 provider 凭据一起交给 worker。resolver 不存在静默
|
||||
fallback：
|
||||
|
||||
```bash
|
||||
/usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py resolve \
|
||||
<project-root>/docs/orc/config.yaml --stage <stage> \
|
||||
--project-root <absolute-project-root> \
|
||||
--worktree <absolute-target-worktree> \
|
||||
[--global-level <low|mid|high>] [--stage-level <low|mid|high>] \
|
||||
[--model-auth <codex-login|openai|azure-openai>] \
|
||||
[--remote-auth <exact-provider-or-transport>]
|
||||
```
|
||||
|
||||
6. 核对 resolver 返回的 `launchFingerprint`、绝对 executable、worktree identity 和选择
|
||||
来源，再读取 [orca-adapter.md](references/orca-adapter.md)，把阶段组织为 Orca task DAG。
|
||||
worker prompt 必须显式写出对应 `$skill`、阶段范围、输入 revision、用户授权边界、
|
||||
验收证据和依赖结果；下游 Skill 无需知道 ORC。
|
||||
7. 监督 `worker_done`、`escalation` 与 `decision_gate`。`worker_done` 只代表该 worker
|
||||
回报完成；Coordinator 仍需核对下游 Skill 要求的证据和 DAG 后置条件。
|
||||
8. 逐阶段汇报所选档位、执行 Skill、结果、外部状态和未完成项。任一阶段失败时保留
|
||||
已成功阶段的准确状态，说明安全恢复入口，不把部分成功概括成全部完成。
|
||||
|
||||
## 固定路由边界
|
||||
|
||||
- 功能、缺陷、重构与验证闭环交给 `$ack`。
|
||||
- 发布版本、release 分支/PR/MR、合并、tag 与 Forge Release 交给
|
||||
`$manage-release`。
|
||||
- DEB 构建或上传交给 `$deb-publisher`。
|
||||
- Docker/OCI 镜像构建或上传交给 `$publish-docker-image`。
|
||||
- 普通非发布 PR/MR 不伪装成版本发布；只有 ACK 已验证交付或明确的 release 流程才
|
||||
进入对应下游能力。
|
||||
|
||||
## 依赖与安全边界
|
||||
|
||||
- 依赖始终单向：`orc -> 下游 Skill`。不得要求 ACK 或其它下游 Skill 引用 ORC、读取
|
||||
ORC 配置或改变自身触发规则。
|
||||
- ORC 档位只选择阶段 worker。进入 `$ack` 后，ACK 自己的 Coordinator、Developer、
|
||||
Test 角色和 `standard/strong` 模型路由仍完全由 ACK 管理。
|
||||
- ORC 的 `code` 阶段必须锁定停止点：纯开发停在 ACK `verified`；用户明确要求普通
|
||||
PR/MR 时最多到 ACK `review_ready`。不得让 ACK 在同一阶段继续执行版本发布、DEB、
|
||||
Docker 或部署；这些动作由 ORC 的独立阶段负责。
|
||||
- 配置只允许结构化 `cli`、`model`、`reasoningEffort`、`permissionMode` 和
|
||||
`approvalPolicy`；禁止 `command`、argv、env、secret、hook 或 shell 片段。
|
||||
- ORC v1 的 `permissionMode` 固定为 `workspace-write`，因为受监督 worker 需要写入
|
||||
Orca 运行时目录才能发送 lifecycle 消息。只读任务仍由 prompt 限制不得改文件。
|
||||
不接受 full-access、bypass、YOLO/force 或关闭 sandbox；文本中的“已授权”不能
|
||||
放宽 profile。
|
||||
- ORC v1 的安全启动适配器只支持 `cli: codex`。遇到其它 CLI 时 fail closed，不把
|
||||
Codex 参数套用到其它 Agent；新增 provider 必须增加独立适配与测试。
|
||||
- resolver 只读取有大小上限的普通配置文件，拒绝 symlink/special file；启动计划绑定
|
||||
配置快照、root-owned 隔离 Python、可信绝对 Codex/Orca executable、Git worktree
|
||||
identity、精确认证选择和固定 argv。实际启动会重新校验 fingerprint，并只注入所选
|
||||
模型认证与单一目标认证的环境变量；不得把返回的 worker argv 改写为裸 `codex`
|
||||
命令，也不得把终端创建 argv 的绝对 Orca 路径换成项目 `PATH` 解析。
|
||||
- 不把模型档位当作权限。`high` 不自动获得更多文件、凭据、网络或远端写权限。
|
||||
- 不执行 `orca orchestration reset`，除非用户明确要求放弃全部相关运行时状态。
|
||||
|
||||
## 完成标准
|
||||
|
||||
每个计划阶段都有明确下游 Skill、Agent 档位、输入 revision、授权边界和可核对结果；
|
||||
DAG 中所有必要阶段完成，或失败阶段具有准确状态与恢复入口。ACK 和其它下游 Skill
|
||||
保持独立且不存在对 ORC 的反向引用。
|
||||
@@ -0,0 +1,6 @@
|
||||
interface:
|
||||
display_name: "ORC"
|
||||
short_description: "按阶段编排开发、版本发布与产物构建，并选择 Agent 档位"
|
||||
default_prompt: "Use $orc to coordinate this engineering task with explicit low, mid, or high worker levels."
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -0,0 +1,95 @@
|
||||
# ORC 的 Orca 适配
|
||||
|
||||
Orca 保存运行时任务、依赖、dispatch 和消息；ORC 保存稳定路由规则。不要在项目中
|
||||
复制一份 Orca 运行时任务板。
|
||||
|
||||
## 运行前
|
||||
|
||||
```bash
|
||||
orca status --json
|
||||
orca orchestration task-list --json
|
||||
orca orchestration inbox --limit 20 --json
|
||||
```
|
||||
|
||||
确认 runtime 可达、orchestration 可用，并识别是否存在与当前请求相同的活跃任务。
|
||||
恢复流程时复用身份匹配的 task；身份不明时不要猜测或清空全局状态。
|
||||
|
||||
## 解析安全启动计划
|
||||
|
||||
对每个阶段调用 `resolve_profile.py resolve`，同时传入规范绝对 `--project-root` 和
|
||||
`--worktree`，以及本阶段精确的 `--model-auth`、`--remote-auth`。JSON 结果包含选择来源、
|
||||
结构化 profile、认证选择、配置与 worktree identity、可信 Python/Codex/Orca executable、
|
||||
`launchFingerprint`、固定 worker/launcher argv，以及完整的 `terminalCreateArgv` 和
|
||||
`terminalCreateShellCommand`。
|
||||
|
||||
- 优先把返回的 `terminalCreateArgv` 原样交给 argv-capable 进程工具；若工具只接受 shell
|
||||
字符串，则执行完整的 `terminalCreateShellCommand`。不得再插值、包引号或追加参数。
|
||||
- `terminalCreateArgv` 的首项是 resolver 选定的绝对 Orca executable，不替换成裸
|
||||
`orca` 或重新通过项目 `PATH` 查找。
|
||||
- 不从 YAML 自行拼接命令，不追加 argv、环境变量、hook 或权限参数。
|
||||
- `remote-auth` 必须与本阶段唯一目标 provider/transport 一致；默认 `none`，不为方便
|
||||
同时暴露多个 token 或 SSH agent。需要代理、额外凭据或 Docker registry env secret 时
|
||||
fail closed，由用户确认新的最小权限适配，不继承 ambient proxy/credential 变量。
|
||||
- resolver 失败时停止；不改用默认模型、邻近档位或已有未知终端。
|
||||
- 不重复手写 worktree 检查；resolver 已拒绝 root、不存在、非规范、含 symlink、未注册、
|
||||
跨仓库或不在 allowlist 的目标，并把身份写入 fingerprint。
|
||||
- ORC v1 profile 必须使用 `workspace-write`。`read-only` sandbox 可能阻止 Orca CLI
|
||||
写入自身运行时或挂载目录，导致 worker 无法发送 `worker_done`；只读工作通过 task
|
||||
spec 限制，而不是换成无法完成 lifecycle 的 sandbox。
|
||||
|
||||
## 创建与派发
|
||||
|
||||
每个需要 fresh worker 的阶段依次执行：
|
||||
|
||||
1. 使用解析结果创建目标 worktree 内的终端。下面整行代表 resolver 返回的一个完整值，
|
||||
不是待替换的参数模板：
|
||||
|
||||
```bash
|
||||
<resolver-terminalCreateShellCommand>
|
||||
```
|
||||
|
||||
2. 使用返回的具体 handle 等待 Agent TUI 可接收输入：
|
||||
|
||||
```bash
|
||||
orca terminal wait --terminal <handle> --for tui-idle \
|
||||
--timeout-ms 60000 --json
|
||||
```
|
||||
|
||||
3. 先为前置阶段创建 task，再用其 ID 构造依赖数组创建后置 task。task spec 使用
|
||||
`routing.md` 的 worker prompt 契约。
|
||||
4. 对已就绪 task 执行：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task-id> --to <handle> --inject --json
|
||||
```
|
||||
|
||||
不要把同一 task 同时派给多个写 worker。并行阶段必须使用不会竞争同一工作树写入的
|
||||
独立 worker；否则串行执行。`terminal create` 超时或连接中断时状态不确定：先用
|
||||
`terminalTitle`、worktree 和 fingerprint 核对 `orca terminal list --json`，没有完成
|
||||
reconciliation 前不得重试创建。
|
||||
|
||||
## 监督循环
|
||||
|
||||
```bash
|
||||
orca orchestration check --wait \
|
||||
--types worker_done,escalation,decision_gate \
|
||||
--timeout-ms 900000 --json
|
||||
```
|
||||
|
||||
- timeout 或空结果是检查点，不等于失败；任务仍活跃时继续滚动等待。
|
||||
- 收到 `decision_gate` 时只回答当前问题，不扩大用户授权。
|
||||
- 收到 `escalation` 时保留已完成状态，判断是改档、补输入还是停止。
|
||||
- 收到 `worker_done` 后核对 task/dispatch ID、下游完成证据和外部状态，再把依赖 task
|
||||
标记完成并派发新就绪阶段。
|
||||
- 三次连续同因失败后停止重派，报告恢复入口；不要用新终端掩盖同一阻塞。
|
||||
|
||||
## ACK 特例
|
||||
|
||||
`code` worker 是运行 `$ack` 的阶段 Coordinator。ORC 的 `low/mid/high` 只决定这个
|
||||
worker 的启动 profile；ACK 启动 Developer/Test 时继续读取自己的项目配置与
|
||||
`standard/strong` 规则。ORC 不读取、改写或覆盖 ACK 的内部 worker profiles。
|
||||
|
||||
## 收尾
|
||||
|
||||
不要自动关闭仍承担恢复入口的终端，不自动删除 worktree 或清空 runtime-global task。
|
||||
只有用户明确要求清理时，才按 Orca 和下游 Skill 的安全规则处理。
|
||||
@@ -0,0 +1,74 @@
|
||||
# ORC 阶段路由
|
||||
|
||||
ORC 只负责拆分、依赖、档位和监督。领域步骤、授权检查和完成标准由下游 Skill 自己
|
||||
决定。
|
||||
|
||||
## 路由表
|
||||
|
||||
| 阶段 | 下游 Skill | 包含 | 不包含 |
|
||||
|------|------------|------|--------|
|
||||
| `code` | `$ack` | 功能、缺陷、重构、测试、三角色验证闭环，以及用户明确要求的普通非发布 PR/MR | 版本发布、单独上传产物 |
|
||||
| `release` | `$manage-release` | 版本号、release worktree/分支、release PR/MR、合并、tag、Forge Release、恢复发布 | 普通非发布 PR/MR、构建或上传 DEB/Docker |
|
||||
| `deb` | `$deb-publisher` | DEB 构建、校验、上传与仓库可见性 | 源码 tag、Docker 镜像 |
|
||||
| `docker` | `$publish-docker-image` | Docker/OCI 构建、push、digest 与平台验证 | 源码版本生命周期、DEB |
|
||||
|
||||
没有匹配项时不要临时扩写某个 Skill 的职责，也不要让 ORC 自己模仿领域流程。报告缺少
|
||||
的能力，由用户决定直接执行、安装新 Skill 或另行设计。
|
||||
|
||||
## 拆分规则
|
||||
|
||||
1. 先从用户请求提取最终结果，再拆出真正需要的阶段；不要因为安装了某个 Skill 就
|
||||
自动增加发布或上传。
|
||||
2. 为每个阶段锁定输入：项目、worktree、源 commit/tag、版本、目标和用户授权的最远
|
||||
写操作。
|
||||
3. 同一领域的连续动作保留在一个下游任务中。例如版本号、release PR、合并和 tag
|
||||
属于一个 `manage-release` 生命周期，不拆成多个互相争抢状态的 worker。
|
||||
4. 只有输入 revision 完全相同且互不修改同一工作树时，才并行执行 DEB 与 Docker。
|
||||
5. 普通代码改动进入 ACK。若项目尚未初始化 ACK，`code` 阶段停在前置条件，不由 ORC
|
||||
静默初始化。
|
||||
6. `code` 阶段默认停在 ACK `verified`；用户明确要求普通 PR/MR 时最多到
|
||||
`review_ready`。worker prompt 必须禁止继续执行版本发布、DEB、Docker 或部署。
|
||||
|
||||
## 常见 DAG
|
||||
|
||||
完整交付：
|
||||
|
||||
```text
|
||||
code ($ack)
|
||||
-> release ($manage-release)
|
||||
-> deb ($deb-publisher)
|
||||
-> docker ($publish-docker-image)
|
||||
```
|
||||
|
||||
只从当前 commit 构建产物：
|
||||
|
||||
```text
|
||||
deb ($deb-publisher) || docker ($publish-docker-image)
|
||||
```
|
||||
|
||||
仅发布源码版本：
|
||||
|
||||
```text
|
||||
release ($manage-release)
|
||||
```
|
||||
|
||||
依赖不是固定模板，但 ORC v1 不拆分一个 `manage-release` 生命周期。若项目要求在打开
|
||||
release PR 与合并之间插入 DEB/Docker gate，当前 task 粒度无法安全表达该中间里程碑；
|
||||
在打开 PR 前建立 decision gate 并报告该流程暂不支持，不得用循环依赖或两个 release
|
||||
worker 临时拼接。
|
||||
|
||||
## Worker prompt 契约
|
||||
|
||||
每个 worker prompt 至少包含：
|
||||
|
||||
- 第一条指令显式调用唯一的下游 Skill，例如 `Use $manage-release ...`。
|
||||
- 阶段目标与明确的非目标。
|
||||
- 项目/worktree、输入 commit/tag 和前置阶段的可核对结果。
|
||||
- 用户已经授予的最远动作；未授权动作明确禁止。
|
||||
- 要求遵循项目 Agent 指令和下游 Skill 自身的停止条件。
|
||||
- 完成证据，以及通过 live dispatch preamble 回报 `worker_done` 的要求。
|
||||
- `code` prompt 还必须写明 ACK 停止点是 `verified` 或普通 PR 的 `review_ready`，并禁止
|
||||
ACK 路由版本、DEB、Docker 或部署动作。
|
||||
|
||||
不要把 ORC 的 profile、路由器内部规则或其它下游 Skill 注入 worker。worker 只需要
|
||||
当前阶段、对应 Skill 和必要依赖结果。
|
||||
Executable
+889
@@ -0,0 +1,889 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate ORC config and build a worktree-bound Codex launch plan."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import pwd
|
||||
import re
|
||||
import shlex
|
||||
import stat
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
LEVELS = ("low", "mid", "high")
|
||||
STAGES = ("code", "release", "deb", "docker")
|
||||
EXPECTED_EFFORT = {"low": "low", "mid": "medium", "high": "high"}
|
||||
TOP_LEVEL_KEYS = {
|
||||
"version",
|
||||
"defaultLevel",
|
||||
"stageDefaults",
|
||||
"allowedWorktrees",
|
||||
"profiles",
|
||||
}
|
||||
PROFILE_KEYS = {
|
||||
"cli",
|
||||
"model",
|
||||
"reasoningEffort",
|
||||
"permissionMode",
|
||||
"approvalPolicy",
|
||||
}
|
||||
MODEL_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}\Z")
|
||||
MAX_CONFIG_SIZE = 64 * 1024
|
||||
MAX_CONTROL_OUTPUT = 64 * 1024
|
||||
CONTROL_TIMEOUT_SECONDS = 15
|
||||
CONFIG_RELATIVE_PATH = Path("docs/orc/config.yaml")
|
||||
COMMON_ENVIRONMENT_NAMES = {
|
||||
"COLORTERM",
|
||||
"LANG",
|
||||
"LC_ALL",
|
||||
"NO_COLOR",
|
||||
"TERM",
|
||||
"TZ",
|
||||
}
|
||||
MODEL_AUTH_ENVIRONMENT = {
|
||||
"codex-login": frozenset(),
|
||||
"openai": frozenset({"OPENAI_API_KEY"}),
|
||||
"azure-openai": frozenset({"AZURE_OPENAI_API_KEY"}),
|
||||
}
|
||||
REMOTE_AUTH_ENVIRONMENT = {
|
||||
"none": frozenset(),
|
||||
"github-token": frozenset({"GITHUB_TOKEN"}),
|
||||
"gitlab-token": frozenset({"GITLAB_TOKEN"}),
|
||||
"gitea-token": frozenset({"GITEA_TOKEN"}),
|
||||
"forgejo-token": frozenset({"FORGEJO_TOKEN"}),
|
||||
"ssh-agent": frozenset({"SSH_AUTH_SOCK"}),
|
||||
"deb-token": frozenset({"DEB_TOKEN"}),
|
||||
}
|
||||
STAGE_REMOTE_AUTH = {
|
||||
"code": frozenset(
|
||||
{
|
||||
"none",
|
||||
"github-token",
|
||||
"gitlab-token",
|
||||
"gitea-token",
|
||||
"forgejo-token",
|
||||
"ssh-agent",
|
||||
}
|
||||
),
|
||||
"release": frozenset(
|
||||
{
|
||||
"none",
|
||||
"github-token",
|
||||
"gitlab-token",
|
||||
"gitea-token",
|
||||
"forgejo-token",
|
||||
"ssh-agent",
|
||||
}
|
||||
),
|
||||
"deb": frozenset({"none", "deb-token", "ssh-agent"}),
|
||||
"docker": frozenset({"none"}),
|
||||
}
|
||||
|
||||
|
||||
class ConfigError(ValueError):
|
||||
"""ORC configuration or launch state is invalid or unsafe."""
|
||||
|
||||
|
||||
def _json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
|
||||
result: dict[str, Any] = {}
|
||||
for key, value in pairs:
|
||||
if key in result:
|
||||
raise ConfigError("JSON-compatible YAML contains a duplicate key")
|
||||
result[key] = value
|
||||
return result
|
||||
|
||||
|
||||
def _read_bounded_regular_file(path: Path) -> tuple[str, dict[str, int]]:
|
||||
absolute = path.absolute()
|
||||
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
|
||||
descriptor: int | None = None
|
||||
try:
|
||||
descriptor = os.open(absolute, flags)
|
||||
with os.fdopen(descriptor, "rb") as stream:
|
||||
descriptor = None
|
||||
before = os.fstat(stream.fileno())
|
||||
if not stat.S_ISREG(before.st_mode):
|
||||
raise ConfigError(f"config must be a regular file: {absolute}")
|
||||
if before.st_size > MAX_CONFIG_SIZE:
|
||||
raise ConfigError(f"config exceeds {MAX_CONFIG_SIZE} bytes")
|
||||
content = stream.read(MAX_CONFIG_SIZE + 1)
|
||||
after = os.fstat(stream.fileno())
|
||||
except OSError as exc:
|
||||
raise ConfigError(f"cannot safely read config {absolute}: {exc}") from exc
|
||||
finally:
|
||||
if descriptor is not None:
|
||||
os.close(descriptor)
|
||||
|
||||
if len(content) > MAX_CONFIG_SIZE:
|
||||
raise ConfigError(f"config exceeds {MAX_CONFIG_SIZE} bytes")
|
||||
identity_before = (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns)
|
||||
identity_after = (after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns)
|
||||
if identity_before != identity_after:
|
||||
raise ConfigError("config changed while it was being read")
|
||||
try:
|
||||
text = content.decode("utf-8")
|
||||
except UnicodeDecodeError as exc:
|
||||
raise ConfigError("config must be valid UTF-8") from exc
|
||||
return text, {
|
||||
"device": before.st_dev,
|
||||
"inode": before.st_ino,
|
||||
"size": before.st_size,
|
||||
"mtimeNs": before.st_mtime_ns,
|
||||
}
|
||||
|
||||
|
||||
def _mapping(value: Any, path: str) -> dict[str, Any]:
|
||||
if not isinstance(value, dict):
|
||||
raise ConfigError(f"{path} must be a mapping")
|
||||
return value
|
||||
|
||||
|
||||
def _exact_keys(
|
||||
value: dict[str, Any],
|
||||
*,
|
||||
required: set[str],
|
||||
path: str,
|
||||
) -> None:
|
||||
missing = sorted(required - set(value))
|
||||
unknown = sorted(set(value) - required)
|
||||
if missing:
|
||||
raise ConfigError(f"{path} is missing fields: {', '.join(missing)}")
|
||||
if unknown:
|
||||
raise ConfigError(f"{path} has unknown fields: {', '.join(unknown)}")
|
||||
|
||||
|
||||
def _enum(value: Any, allowed: tuple[str, ...] | set[str], path: str) -> str:
|
||||
if not isinstance(value, str) or value not in allowed:
|
||||
raise ConfigError(f"{path} must be one of: {', '.join(sorted(allowed))}")
|
||||
return value
|
||||
|
||||
|
||||
def validate_config(document: Any) -> dict[str, Any]:
|
||||
config = _mapping(document, "config")
|
||||
_exact_keys(config, required=TOP_LEVEL_KEYS, path="config")
|
||||
|
||||
version = config["version"]
|
||||
if isinstance(version, bool) or version != 1:
|
||||
raise ConfigError("version must be integer 1")
|
||||
|
||||
_enum(config["defaultLevel"], LEVELS, "defaultLevel")
|
||||
|
||||
stage_defaults = _mapping(config["stageDefaults"], "stageDefaults")
|
||||
unknown_stages = sorted(set(stage_defaults) - set(STAGES))
|
||||
if unknown_stages:
|
||||
raise ConfigError(
|
||||
f"stageDefaults has unknown fields: {', '.join(unknown_stages)}"
|
||||
)
|
||||
for stage, level in stage_defaults.items():
|
||||
_enum(level, LEVELS, f"stageDefaults.{stage}")
|
||||
|
||||
allowed = config["allowedWorktrees"]
|
||||
if not isinstance(allowed, list) or not allowed:
|
||||
raise ConfigError("allowedWorktrees must be a non-empty list")
|
||||
seen_worktrees: set[str] = set()
|
||||
for index, entry in enumerate(allowed):
|
||||
if (
|
||||
not isinstance(entry, str)
|
||||
or not entry
|
||||
or entry != entry.strip()
|
||||
or any(character in entry for character in ("\x00", "\n", "\r"))
|
||||
):
|
||||
raise ConfigError(
|
||||
f"allowedWorktrees[{index}] must be a safe non-empty path"
|
||||
)
|
||||
if entry != "." and not Path(entry).is_absolute():
|
||||
raise ConfigError(
|
||||
f"allowedWorktrees[{index}] must be '.' or an absolute path"
|
||||
)
|
||||
normalized = entry if entry == "." else str(Path(entry).absolute())
|
||||
if normalized in seen_worktrees:
|
||||
raise ConfigError(f"allowedWorktrees contains duplicate path: {entry}")
|
||||
seen_worktrees.add(normalized)
|
||||
|
||||
profiles = _mapping(config["profiles"], "profiles")
|
||||
_exact_keys(profiles, required=set(LEVELS), path="profiles")
|
||||
for level in LEVELS:
|
||||
profile = _mapping(profiles[level], f"profiles.{level}")
|
||||
_exact_keys(profile, required=PROFILE_KEYS, path=f"profiles.{level}")
|
||||
if profile["cli"] != "codex":
|
||||
raise ConfigError(f"profiles.{level}.cli must be codex in ORC v1")
|
||||
model = profile["model"]
|
||||
if not isinstance(model, str) or not MODEL_RE.fullmatch(model):
|
||||
raise ConfigError(f"profiles.{level}.model is not a safe exact model ID")
|
||||
expected_effort = EXPECTED_EFFORT[level]
|
||||
if profile["reasoningEffort"] != expected_effort:
|
||||
raise ConfigError(
|
||||
f"profiles.{level}.reasoningEffort must be {expected_effort}"
|
||||
)
|
||||
if profile["permissionMode"] != "workspace-write":
|
||||
raise ConfigError(
|
||||
f"profiles.{level}.permissionMode must be workspace-write in ORC v1"
|
||||
)
|
||||
_enum(
|
||||
profile["approvalPolicy"],
|
||||
{"untrusted", "on-request", "never"},
|
||||
f"profiles.{level}.approvalPolicy",
|
||||
)
|
||||
return config
|
||||
|
||||
|
||||
def load_config_snapshot(path: Path) -> tuple[dict[str, Any], dict[str, Any]]:
|
||||
raw, identity = _read_bounded_regular_file(path)
|
||||
try:
|
||||
document = json.loads(raw, object_pairs_hook=_json_object)
|
||||
except ConfigError:
|
||||
raise
|
||||
except Exception as exc:
|
||||
raise ConfigError("invalid JSON-compatible YAML config") from exc
|
||||
config = validate_config(document)
|
||||
snapshot = {
|
||||
"sha256": hashlib.sha256(raw.encode("utf-8")).hexdigest(),
|
||||
**identity,
|
||||
}
|
||||
return config, snapshot
|
||||
|
||||
|
||||
def load_config(path: Path) -> dict[str, Any]:
|
||||
config, _ = load_config_snapshot(path)
|
||||
return config
|
||||
|
||||
|
||||
def resolve_profile(
|
||||
config: dict[str, Any],
|
||||
*,
|
||||
stage: str,
|
||||
global_level: str | None = None,
|
||||
stage_level: str | None = None,
|
||||
model_auth: str = "codex-login",
|
||||
remote_auth: str = "none",
|
||||
) -> dict[str, Any]:
|
||||
_enum(stage, STAGES, "stage")
|
||||
if global_level is not None:
|
||||
_enum(global_level, LEVELS, "global level")
|
||||
if stage_level is not None:
|
||||
_enum(stage_level, LEVELS, "stage level")
|
||||
_enum(model_auth, set(MODEL_AUTH_ENVIRONMENT), "model auth")
|
||||
_enum(remote_auth, STAGE_REMOTE_AUTH[stage], f"{stage} remote auth")
|
||||
|
||||
if stage_level is not None:
|
||||
level, source = stage_level, "request.stage"
|
||||
elif global_level is not None:
|
||||
level, source = global_level, "request.global"
|
||||
elif stage in config["stageDefaults"]:
|
||||
level, source = config["stageDefaults"][stage], f"config.stageDefaults.{stage}"
|
||||
else:
|
||||
level, source = config["defaultLevel"], "config.defaultLevel"
|
||||
|
||||
profile = config["profiles"].get(level)
|
||||
if profile is None:
|
||||
raise ConfigError(f"requested profile does not exist: {level}")
|
||||
worker_args = [
|
||||
"--model",
|
||||
profile["model"],
|
||||
"-c",
|
||||
f'model_reasoning_effort="{profile["reasoningEffort"]}"',
|
||||
"--sandbox",
|
||||
profile["permissionMode"],
|
||||
"--ask-for-approval",
|
||||
profile["approvalPolicy"],
|
||||
"--strict-config",
|
||||
]
|
||||
return {
|
||||
"stage": stage,
|
||||
"level": level,
|
||||
"selectionSource": source,
|
||||
"modelAuth": model_auth,
|
||||
"remoteAuth": remote_auth,
|
||||
"profile": dict(profile),
|
||||
"workerArgs": worker_args,
|
||||
}
|
||||
|
||||
|
||||
def _path_has_parent_reference(value: str) -> bool:
|
||||
return ".." in Path(value).parts
|
||||
|
||||
|
||||
def _assert_no_symlink_components(path: Path, label: str) -> None:
|
||||
if not path.is_absolute():
|
||||
raise ConfigError(f"{label} must be absolute: {path}")
|
||||
current = Path(path.anchor)
|
||||
for part in path.parts[1:]:
|
||||
current /= part
|
||||
try:
|
||||
metadata = os.lstat(current)
|
||||
except OSError as exc:
|
||||
raise ConfigError(f"{label} does not exist: {current}") from exc
|
||||
if stat.S_ISLNK(metadata.st_mode):
|
||||
raise ConfigError(f"{label} must not contain symlinks: {current}")
|
||||
|
||||
|
||||
def canonical_directory(value: str | Path, label: str) -> Path:
|
||||
text = str(value)
|
||||
if (
|
||||
not text
|
||||
or text != text.strip()
|
||||
or any(character in text for character in ("\x00", "\n", "\r"))
|
||||
or _path_has_parent_reference(text)
|
||||
):
|
||||
raise ConfigError(f"{label} must be a safe canonical absolute path")
|
||||
raw = Path(text)
|
||||
_assert_no_symlink_components(raw, label)
|
||||
try:
|
||||
resolved = raw.resolve(strict=True)
|
||||
except OSError as exc:
|
||||
raise ConfigError(f"{label} does not exist: {raw}") from exc
|
||||
if resolved != raw or resolved == Path(resolved.anchor) or not resolved.is_dir():
|
||||
raise ConfigError(f"{label} must be a canonical non-root directory: {resolved}")
|
||||
return resolved
|
||||
|
||||
|
||||
def account_identity() -> tuple[Path, str]:
|
||||
account = pwd.getpwuid(os.getuid())
|
||||
account_home = Path(account.pw_dir).resolve(strict=True)
|
||||
if not account_home.is_dir():
|
||||
raise ConfigError("current account home is unavailable")
|
||||
return account_home, account.pw_name
|
||||
|
||||
|
||||
def trusted_path_entries() -> list[Path]:
|
||||
account_home, _ = account_identity()
|
||||
candidates = [
|
||||
account_home / ".local" / "bin",
|
||||
account_home / ".local" / "share" / "mise" / "shims",
|
||||
account_home / ".cargo" / "bin",
|
||||
Path("/home/linuxbrew/.linuxbrew/bin"),
|
||||
Path("/usr/local/bin"),
|
||||
Path("/usr/bin"),
|
||||
Path("/bin"),
|
||||
]
|
||||
result: list[Path] = []
|
||||
for candidate in candidates:
|
||||
try:
|
||||
resolved = candidate.resolve(strict=True)
|
||||
except OSError:
|
||||
continue
|
||||
if resolved.is_dir() and resolved not in result:
|
||||
result.append(resolved)
|
||||
return result
|
||||
|
||||
|
||||
def _trusted_executable(path: Path, expected_name: str) -> Path | None:
|
||||
try:
|
||||
candidate_metadata = os.lstat(path)
|
||||
resolved = path.resolve(strict=True)
|
||||
metadata = resolved.stat()
|
||||
except OSError:
|
||||
return None
|
||||
if not (
|
||||
stat.S_ISREG(candidate_metadata.st_mode)
|
||||
or stat.S_ISLNK(candidate_metadata.st_mode)
|
||||
):
|
||||
return None
|
||||
if not stat.S_ISREG(metadata.st_mode) or not os.access(resolved, os.X_OK):
|
||||
return None
|
||||
if metadata.st_uid not in {0, os.getuid()}:
|
||||
return None
|
||||
if stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
return None
|
||||
if expected_name == "python3":
|
||||
if not resolved.name.startswith("python3"):
|
||||
return None
|
||||
elif resolved.name != expected_name:
|
||||
return None
|
||||
return resolved
|
||||
|
||||
|
||||
def resolve_trusted_executable(name: str) -> Path:
|
||||
if name not in {"codex", "git", "orca"}:
|
||||
raise ConfigError(f"unsupported executable: {name}")
|
||||
search_paths = trusted_path_entries()
|
||||
if name == "git":
|
||||
search_paths = [
|
||||
path
|
||||
for path in search_paths
|
||||
if str(path) in {"/usr/local/bin", "/usr/bin", "/bin"}
|
||||
]
|
||||
for directory in search_paths:
|
||||
resolved = _trusted_executable(directory / name, name)
|
||||
if resolved is not None:
|
||||
return resolved
|
||||
raise ConfigError(f"trusted {name} executable was not found in fixed directories")
|
||||
|
||||
|
||||
def resolve_trusted_python() -> Path:
|
||||
for candidate in (Path("/usr/bin/python3"), Path("/usr/local/bin/python3")):
|
||||
resolved = _trusted_executable(candidate, "python3")
|
||||
if resolved is not None and resolved.stat().st_uid == 0:
|
||||
return resolved
|
||||
raise ConfigError("a root-owned Python executable was not found in fixed paths")
|
||||
|
||||
|
||||
def control_environment() -> dict[str, str]:
|
||||
account_home, username = account_identity()
|
||||
result = {
|
||||
"HOME": str(account_home),
|
||||
"LOGNAME": username,
|
||||
"PATH": os.pathsep.join(str(path) for path in trusted_path_entries()),
|
||||
"USER": username,
|
||||
}
|
||||
for name, value in os.environ.items():
|
||||
if (
|
||||
name in COMMON_ENVIRONMENT_NAMES or name.startswith("LC_")
|
||||
) and "\x00" not in value:
|
||||
result[name] = value
|
||||
return result
|
||||
|
||||
|
||||
def selected_credential_names(
|
||||
stage: str,
|
||||
*,
|
||||
model_auth: str,
|
||||
remote_auth: str,
|
||||
) -> frozenset[str]:
|
||||
_enum(stage, STAGES, "stage")
|
||||
_enum(model_auth, set(MODEL_AUTH_ENVIRONMENT), "model auth")
|
||||
_enum(remote_auth, STAGE_REMOTE_AUTH[stage], f"{stage} remote auth")
|
||||
names = MODEL_AUTH_ENVIRONMENT[model_auth] | REMOTE_AUTH_ENVIRONMENT[remote_auth]
|
||||
for name in names:
|
||||
value = os.environ.get(name)
|
||||
if not value or "\x00" in value:
|
||||
raise ConfigError(
|
||||
f"selected authentication variable is unavailable: {name}"
|
||||
)
|
||||
if name == "SSH_AUTH_SOCK":
|
||||
socket_path = Path(value)
|
||||
if (
|
||||
not socket_path.is_absolute()
|
||||
or value != value.strip()
|
||||
or any(character in value for character in ("\n", "\r"))
|
||||
or _path_has_parent_reference(value)
|
||||
):
|
||||
raise ConfigError("selected SSH_AUTH_SOCK is not a safe absolute path")
|
||||
_assert_no_symlink_components(socket_path, "selected SSH_AUTH_SOCK")
|
||||
try:
|
||||
metadata = os.lstat(socket_path)
|
||||
except OSError as exc:
|
||||
raise ConfigError("selected SSH_AUTH_SOCK is unavailable") from exc
|
||||
if (
|
||||
not stat.S_ISSOCK(metadata.st_mode)
|
||||
or metadata.st_uid != os.getuid()
|
||||
or stat.S_IMODE(metadata.st_mode) & 0o022
|
||||
):
|
||||
raise ConfigError("selected SSH_AUTH_SOCK is not a trusted user socket")
|
||||
return names
|
||||
|
||||
|
||||
def worker_environment(
|
||||
stage: str,
|
||||
*,
|
||||
model_auth: str,
|
||||
remote_auth: str,
|
||||
) -> dict[str, str]:
|
||||
result = control_environment()
|
||||
for name in selected_credential_names(
|
||||
stage,
|
||||
model_auth=model_auth,
|
||||
remote_auth=remote_auth,
|
||||
):
|
||||
result[name] = os.environ[name]
|
||||
return result
|
||||
|
||||
|
||||
def _run_control(argv: list[str], label: str) -> str:
|
||||
try:
|
||||
completed = subprocess.run(
|
||||
argv,
|
||||
shell=False,
|
||||
check=False,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=CONTROL_TIMEOUT_SECONDS,
|
||||
env=control_environment(),
|
||||
)
|
||||
except (OSError, subprocess.TimeoutExpired) as exc:
|
||||
raise ConfigError(f"{label} could not be executed safely") from exc
|
||||
if completed.returncode != 0:
|
||||
raise ConfigError(f"{label} failed with exit {completed.returncode}")
|
||||
output = completed.stdout.strip()
|
||||
if not output or len(output.encode("utf-8")) > MAX_CONTROL_OUTPUT:
|
||||
raise ConfigError(f"{label} returned invalid output")
|
||||
return output
|
||||
|
||||
|
||||
def _git_path(value: str, cwd: Path, label: str) -> Path:
|
||||
candidate = Path(value)
|
||||
if not candidate.is_absolute():
|
||||
candidate = cwd / candidate
|
||||
_assert_no_symlink_components(candidate, label)
|
||||
try:
|
||||
resolved = candidate.resolve(strict=True)
|
||||
except OSError as exc:
|
||||
raise ConfigError(f"{label} is invalid") from exc
|
||||
if not resolved.is_dir():
|
||||
raise ConfigError(f"{label} is not a directory")
|
||||
return resolved
|
||||
|
||||
|
||||
def validate_worktree(
|
||||
config: dict[str, Any],
|
||||
*,
|
||||
project_root_value: str | Path,
|
||||
worktree_value: str | Path,
|
||||
) -> dict[str, Any]:
|
||||
project_root = canonical_directory(project_root_value, "project root")
|
||||
worktree = canonical_directory(worktree_value, "target worktree")
|
||||
git = resolve_trusted_executable("git")
|
||||
|
||||
top_level = canonical_directory(
|
||||
_run_control(
|
||||
[str(git), "-C", str(project_root), "rev-parse", "--show-toplevel"],
|
||||
"Git project-root check",
|
||||
),
|
||||
"Git project root",
|
||||
)
|
||||
if top_level != project_root:
|
||||
raise ConfigError("project root is not the repository top level")
|
||||
|
||||
common_dir = _git_path(
|
||||
_run_control(
|
||||
[str(git), "-C", str(project_root), "rev-parse", "--git-common-dir"],
|
||||
"Git common-directory check",
|
||||
),
|
||||
project_root,
|
||||
"Git common directory",
|
||||
)
|
||||
listed = _run_control(
|
||||
[str(git), "-C", str(project_root), "worktree", "list", "--porcelain"],
|
||||
"Git worktree listing",
|
||||
)
|
||||
registered: set[Path] = set()
|
||||
for line in listed.splitlines():
|
||||
if line.startswith("worktree "):
|
||||
try:
|
||||
registered.add(
|
||||
canonical_directory(line[9:], "registered worktree")
|
||||
)
|
||||
except ConfigError:
|
||||
continue
|
||||
|
||||
allowed: set[Path] = set()
|
||||
for entry in config["allowedWorktrees"]:
|
||||
allowed.add(
|
||||
project_root
|
||||
if entry == "."
|
||||
else canonical_directory(entry, "allowed worktree")
|
||||
)
|
||||
if not allowed <= registered:
|
||||
raise ConfigError("allowedWorktrees contains an unregistered Git worktree")
|
||||
if worktree not in allowed:
|
||||
raise ConfigError("target worktree is not in allowedWorktrees")
|
||||
|
||||
target_top = canonical_directory(
|
||||
_run_control(
|
||||
[str(git), "-C", str(worktree), "rev-parse", "--show-toplevel"],
|
||||
"Git target-worktree check",
|
||||
),
|
||||
"target Git worktree",
|
||||
)
|
||||
target_common = _git_path(
|
||||
_run_control(
|
||||
[str(git), "-C", str(worktree), "rev-parse", "--git-common-dir"],
|
||||
"target Git common-directory check",
|
||||
),
|
||||
worktree,
|
||||
"target Git common directory",
|
||||
)
|
||||
if target_top != worktree or target_common != common_dir:
|
||||
raise ConfigError("target worktree does not belong to the project repository")
|
||||
|
||||
worktree_metadata = worktree.stat()
|
||||
common_metadata = common_dir.stat()
|
||||
return {
|
||||
"projectRoot": str(project_root),
|
||||
"worktree": str(worktree),
|
||||
"gitCommonDir": str(common_dir),
|
||||
"worktreeIdentity": {
|
||||
"device": worktree_metadata.st_dev,
|
||||
"inode": worktree_metadata.st_ino,
|
||||
"gitCommonDevice": common_metadata.st_dev,
|
||||
"gitCommonInode": common_metadata.st_ino,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def _file_facts(path: Path) -> dict[str, Any]:
|
||||
metadata = path.stat()
|
||||
return {
|
||||
"path": str(path),
|
||||
"device": metadata.st_dev,
|
||||
"inode": metadata.st_ino,
|
||||
"size": metadata.st_size,
|
||||
"mtimeNs": metadata.st_mtime_ns,
|
||||
}
|
||||
|
||||
|
||||
def _executable_facts(path: Path) -> dict[str, Any]:
|
||||
return {
|
||||
**_file_facts(path),
|
||||
"version": _run_control([str(path), "--version"], "Codex version check"),
|
||||
}
|
||||
|
||||
|
||||
def _python_facts(path: Path) -> dict[str, Any]:
|
||||
version = _run_control(
|
||||
[
|
||||
str(path),
|
||||
"-I",
|
||||
"-S",
|
||||
"-c",
|
||||
"import sys; print(sys.version.split()[0])",
|
||||
],
|
||||
"Python version check",
|
||||
)
|
||||
return {
|
||||
**_file_facts(path),
|
||||
"version": version,
|
||||
}
|
||||
|
||||
|
||||
def _fingerprint(value: dict[str, Any]) -> str:
|
||||
canonical = json.dumps(
|
||||
value,
|
||||
ensure_ascii=False,
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
).encode("utf-8")
|
||||
return "sha256:" + hashlib.sha256(canonical).hexdigest()
|
||||
|
||||
|
||||
def build_launch_plan(
|
||||
config_path: Path,
|
||||
*,
|
||||
project_root: str | Path,
|
||||
worktree: str | Path,
|
||||
stage: str,
|
||||
global_level: str | None = None,
|
||||
stage_level: str | None = None,
|
||||
model_auth: str = "codex-login",
|
||||
remote_auth: str = "none",
|
||||
) -> dict[str, Any]:
|
||||
project = canonical_directory(project_root, "project root")
|
||||
expected_config = project / CONFIG_RELATIVE_PATH
|
||||
if config_path.absolute() != expected_config:
|
||||
raise ConfigError(f"config path must be {expected_config}")
|
||||
_assert_no_symlink_components(expected_config, "config path")
|
||||
config, config_snapshot = load_config_snapshot(expected_config)
|
||||
worktree_facts = validate_worktree(
|
||||
config,
|
||||
project_root_value=project,
|
||||
worktree_value=worktree,
|
||||
)
|
||||
profile = resolve_profile(
|
||||
config,
|
||||
stage=stage,
|
||||
global_level=global_level,
|
||||
stage_level=stage_level,
|
||||
model_auth=model_auth,
|
||||
remote_auth=remote_auth,
|
||||
)
|
||||
selected_credential_names(
|
||||
stage,
|
||||
model_auth=model_auth,
|
||||
remote_auth=remote_auth,
|
||||
)
|
||||
codex = resolve_trusted_executable("codex")
|
||||
executable = _executable_facts(codex)
|
||||
orca = resolve_trusted_executable("orca")
|
||||
orca_executable = _file_facts(orca)
|
||||
python = resolve_trusted_python()
|
||||
python_executable = _python_facts(python)
|
||||
script = Path(__file__).resolve(strict=True)
|
||||
script_metadata = script.stat()
|
||||
script_sha256 = hashlib.sha256(script.read_bytes()).hexdigest()
|
||||
launch_facts = {
|
||||
**profile,
|
||||
**worktree_facts,
|
||||
"config": {
|
||||
"path": str(expected_config),
|
||||
**config_snapshot,
|
||||
},
|
||||
"executable": executable,
|
||||
"orca": orca_executable,
|
||||
"python": python_executable,
|
||||
"launcher": {
|
||||
"path": str(script),
|
||||
"device": script_metadata.st_dev,
|
||||
"inode": script_metadata.st_ino,
|
||||
"size": script_metadata.st_size,
|
||||
"mtimeNs": script_metadata.st_mtime_ns,
|
||||
"sha256": script_sha256,
|
||||
},
|
||||
}
|
||||
fingerprint = _fingerprint(launch_facts)
|
||||
worker_argv = [str(codex), *profile["workerArgs"]]
|
||||
launcher_argv = [
|
||||
str(python),
|
||||
"-I",
|
||||
"-S",
|
||||
str(script),
|
||||
"_launch",
|
||||
str(expected_config),
|
||||
"--project-root",
|
||||
str(project),
|
||||
"--worktree",
|
||||
str(worktree_facts["worktree"]),
|
||||
"--stage",
|
||||
stage,
|
||||
"--expected-fingerprint",
|
||||
fingerprint,
|
||||
]
|
||||
if global_level is not None:
|
||||
launcher_argv.extend(["--global-level", global_level])
|
||||
if stage_level is not None:
|
||||
launcher_argv.extend(["--stage-level", stage_level])
|
||||
if model_auth != "codex-login":
|
||||
launcher_argv.extend(["--model-auth", model_auth])
|
||||
if remote_auth != "none":
|
||||
launcher_argv.extend(["--remote-auth", remote_auth])
|
||||
terminal_command = shlex.join(launcher_argv)
|
||||
worktree_selector = "path:" + str(worktree_facts["worktree"])
|
||||
terminal_title = f"ORC-{stage}-{profile['level']}-{fingerprint[7:15]}"
|
||||
terminal_create_argv = [
|
||||
str(orca),
|
||||
"terminal",
|
||||
"create",
|
||||
"--worktree",
|
||||
worktree_selector,
|
||||
"--title",
|
||||
terminal_title,
|
||||
"--command",
|
||||
terminal_command,
|
||||
"--json",
|
||||
]
|
||||
return {
|
||||
**launch_facts,
|
||||
"argv": worker_argv,
|
||||
"launchFingerprint": fingerprint,
|
||||
"launcherArgv": launcher_argv,
|
||||
"terminalCommand": terminal_command,
|
||||
"worktreeSelector": worktree_selector,
|
||||
"terminalTitle": terminal_title,
|
||||
"terminalCreateArgv": terminal_create_argv,
|
||||
"terminalCreateShellCommand": shlex.join(terminal_create_argv),
|
||||
}
|
||||
|
||||
|
||||
def execute_launch(args: argparse.Namespace) -> int:
|
||||
plan = build_launch_plan(
|
||||
args.config,
|
||||
project_root=args.project_root,
|
||||
worktree=args.worktree,
|
||||
stage=args.stage,
|
||||
global_level=args.global_level,
|
||||
stage_level=args.stage_level,
|
||||
model_auth=args.model_auth,
|
||||
remote_auth=args.remote_auth,
|
||||
)
|
||||
if plan["launchFingerprint"] != args.expected_fingerprint:
|
||||
raise ConfigError("launch fingerprint changed; resolve the profile again")
|
||||
current = canonical_directory(Path.cwd(), "launcher working directory")
|
||||
if current != Path(plan["worktree"]):
|
||||
raise ConfigError("launcher working directory does not match target worktree")
|
||||
current_python = Path(sys.executable).resolve(strict=True)
|
||||
if current_python != Path(plan["python"]["path"]):
|
||||
raise ConfigError("launcher Python does not match the resolved interpreter")
|
||||
if _python_facts(current_python) != plan["python"]:
|
||||
raise ConfigError("Python executable changed before launch")
|
||||
executable = Path(plan["executable"]["path"])
|
||||
if _executable_facts(executable) != plan["executable"]:
|
||||
raise ConfigError("Codex executable changed before launch")
|
||||
try:
|
||||
os.execve(
|
||||
executable,
|
||||
plan["argv"],
|
||||
worker_environment(
|
||||
plan["stage"],
|
||||
model_auth=plan["modelAuth"],
|
||||
remote_auth=plan["remoteAuth"],
|
||||
),
|
||||
)
|
||||
except OSError as exc:
|
||||
raise ConfigError("Codex worker could not be launched") from exc
|
||||
return 1 # pragma: no cover - os.execve does not return on success
|
||||
|
||||
|
||||
def _add_resolution_arguments(parser: argparse.ArgumentParser) -> None:
|
||||
parser.add_argument("config", type=Path)
|
||||
parser.add_argument("--project-root", required=True)
|
||||
parser.add_argument("--worktree", required=True)
|
||||
parser.add_argument("--stage", required=True, choices=STAGES)
|
||||
parser.add_argument("--global-level", choices=LEVELS)
|
||||
parser.add_argument("--stage-level", choices=LEVELS)
|
||||
parser.add_argument(
|
||||
"--model-auth",
|
||||
choices=tuple(MODEL_AUTH_ENVIRONMENT),
|
||||
default="codex-login",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--remote-auth",
|
||||
choices=tuple(REMOTE_AUTH_ENVIRONMENT),
|
||||
default="none",
|
||||
)
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
subparsers = parser.add_subparsers(dest="command", required=True)
|
||||
|
||||
validate = subparsers.add_parser("validate", help="validate config only")
|
||||
validate.add_argument("config", type=Path)
|
||||
|
||||
resolve = subparsers.add_parser("resolve", help="resolve a bound launch plan")
|
||||
_add_resolution_arguments(resolve)
|
||||
|
||||
launch = subparsers.add_parser("_launch", help=argparse.SUPPRESS)
|
||||
_add_resolution_arguments(launch)
|
||||
launch.add_argument("--expected-fingerprint", required=True)
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
args = build_parser().parse_args(argv)
|
||||
try:
|
||||
if args.command == "validate":
|
||||
config = load_config(args.config)
|
||||
result: dict[str, Any] = {
|
||||
"ok": True,
|
||||
"config": str(args.config.absolute()),
|
||||
"levels": list(LEVELS),
|
||||
"stages": list(STAGES),
|
||||
"defaultLevel": config["defaultLevel"],
|
||||
}
|
||||
elif args.command == "resolve":
|
||||
result = build_launch_plan(
|
||||
args.config,
|
||||
project_root=args.project_root,
|
||||
worktree=args.worktree,
|
||||
stage=args.stage,
|
||||
global_level=args.global_level,
|
||||
stage_level=args.stage_level,
|
||||
model_auth=args.model_auth,
|
||||
remote_auth=args.remote_auth,
|
||||
)
|
||||
else:
|
||||
return execute_launch(args)
|
||||
except ConfigError as exc:
|
||||
print(f"ORC config error: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
print(json.dumps(result, ensure_ascii=False, sort_keys=True))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"version": 1,
|
||||
"defaultLevel": "mid",
|
||||
"stageDefaults": {
|
||||
"code": "high",
|
||||
"release": "mid",
|
||||
"deb": "low",
|
||||
"docker": "low"
|
||||
},
|
||||
"allowedWorktrees": [
|
||||
"."
|
||||
],
|
||||
"profiles": {
|
||||
"low": {
|
||||
"cli": "codex",
|
||||
"model": "gpt-5.6-luna",
|
||||
"reasoningEffort": "low",
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "never"
|
||||
},
|
||||
"mid": {
|
||||
"cli": "codex",
|
||||
"model": "gpt-5.6-terra",
|
||||
"reasoningEffort": "medium",
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "never"
|
||||
},
|
||||
"high": {
|
||||
"cli": "codex",
|
||||
"model": "gpt-5.6-sol",
|
||||
"reasoningEffort": "high",
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "never"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,272 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import contextlib
|
||||
import io
|
||||
from unittest import mock
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
READER = ROOT / "skills/ack/scripts/feishu_bug_intake.py"
|
||||
sys.path.insert(0, str(READER.parent))
|
||||
import feishu_bug_intake # noqa: E402
|
||||
|
||||
|
||||
class FeishuIntakeBlackBox(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.tmp = tempfile.TemporaryDirectory(prefix="feishu-e2e-")
|
||||
self.d = Path(self.tmp.name)
|
||||
self.bin = self.d / "bin"
|
||||
self.bin.mkdir()
|
||||
self.fixture = self.d / "submitted-bug.json"
|
||||
self.fixture.write_text(json.dumps({
|
||||
"recordId": "recBug1",
|
||||
"title": "Crash on save", "actual": "button crashes",
|
||||
"expected": "save succeeds", "steps": ["open app", "click Save"],
|
||||
"acceptance": "regression covered", "priority": "P1",
|
||||
"attachments": [{"file_token": "fileTok", "name": "screen.png", "type": "image/png", "size": 4}],
|
||||
"updatedAt": "2026-08-01T12:00:00Z",
|
||||
}), encoding="utf-8")
|
||||
self.mode_file = self.d / "mode.txt"
|
||||
self.mode_file.write_text("", encoding="utf-8")
|
||||
self.log = self.d / "argv.jsonl"
|
||||
self.fake = self.bin / "lark-cli"
|
||||
self.fake.write_text(
|
||||
"#!" + sys.executable + "\n"
|
||||
"import json, os, pathlib, sys\n"
|
||||
f"fixture=json.loads(pathlib.Path({str(self.fixture)!r}).read_text())\n"
|
||||
f"mode=pathlib.Path({str(self.mode_file)!r}).read_text().strip()\n"
|
||||
f"log=pathlib.Path({str(self.log)!r}); a=sys.argv[1:]\n"
|
||||
"with log.open('a') as f: f.write(json.dumps(a)+'\\n')\n"
|
||||
"p=a[a.index('--profile')+1] if '--profile' in a else None\n"
|
||||
"if a[:2]==['profile','list']:\n"
|
||||
" if '--format' in a: raise SystemExit(8)\n"
|
||||
" print(json.dumps([{'name':'tenant-a','appId':'cli_a','brand':'feishu','active':True},{'name':'tenant-b','appId':'cli_b','brand':'feishu','active':False}])); raise SystemExit\n"
|
||||
"if p != 'tenant-b': print('wrong tenant',file=sys.stderr); raise SystemExit(9)\n"
|
||||
"if mode=='malformed': print('{bad'); raise SystemExit\n"
|
||||
"if a[:2]==['base','+record-list']:\n"
|
||||
" if mode=='okfalse': print(json.dumps({'ok':False})); raise SystemExit\n"
|
||||
" if mode=='code': print(json.dumps({'code':7})); raise SystemExit\n"
|
||||
" if mode=='ambiguous': print(json.dumps({'data':{}})); raise SystemExit\n"
|
||||
" if mode=='noprog': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':[],'data':[],'has_more':True}})); raise SystemExit\n"
|
||||
" if mode=='max': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[['x']*8],'has_more':True}})); raise SystemExit\n"
|
||||
" if mode=='matrix': print(json.dumps({'code':0,'data':{'fields':['fTitle'],'record_id_list':['recBug1'],'records':[]}})); raise SystemExit\n"
|
||||
" if mode=='cell': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[[{'unexpected':'value'},'actual','expected','steps','accept','P1',[],f['updatedAt']]]}})); raise SystemExit\n"
|
||||
" if mode=='empty': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[['title',None,'expected','steps','accept','P1',[],f['updatedAt']]]}})); raise SystemExit\n"
|
||||
" f=fixture; print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':[f['recordId']],'data':[[f['title'],f['actual'],f['expected'],f['steps'],f['acceptance'],f['priority'],f['attachments'],f['updatedAt']]]}})); raise SystemExit\n"
|
||||
"if a[:2]==['base','+record-download-attachment']:\n"
|
||||
" out=pathlib.Path(a[a.index('--output')+1]); out.mkdir(parents=True,exist_ok=True)\n"
|
||||
" if mode=='escape': (out/'escape').symlink_to('/tmp'); raise SystemExit\n"
|
||||
" (out/'screen.png').write_bytes(b'fake'); print(json.dumps({'ok':True})); raise SystemExit\n"
|
||||
"raise SystemExit(2)\n", encoding="utf-8")
|
||||
self.fake.chmod(0o755)
|
||||
self.env = {**os.environ, "PATH": f"{self.bin}{os.pathsep}{os.environ.get('PATH','')}"}
|
||||
self.env["FAKE_FIXTURE"] = str(self.fixture)
|
||||
self.board = self.d / "tasks.yaml"
|
||||
self.board.write_text("""version: 1
|
||||
project:
|
||||
name: isolated-fake
|
||||
bugIntake:
|
||||
provider: feishu-base
|
||||
profile: tenant-b
|
||||
baseToken: base-secret
|
||||
tableId: tbl-bugs
|
||||
viewId: view-ready
|
||||
fields:
|
||||
title: fTitle
|
||||
actual: fActual
|
||||
expected: fExpected
|
||||
stepsToReproduce: fSteps
|
||||
acceptance: fAcceptance
|
||||
priority: fPriority
|
||||
attachments: fAttachments
|
||||
updatedAt: fUpdated
|
||||
tasks: []
|
||||
""", encoding="utf-8")
|
||||
|
||||
def tearDown(self) -> None:
|
||||
self.tmp.cleanup()
|
||||
|
||||
def invoke(self, command: str, *, mode: str | None = None, output: Path | None = None, resolver=None):
|
||||
env = dict(self.env)
|
||||
self.mode_file.write_text(mode or "", encoding="utf-8")
|
||||
args = [command, str(self.board)]
|
||||
if output:
|
||||
args += ["--output-dir", str(output)]
|
||||
stdout, stderr = io.StringIO(), io.StringIO()
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=self.fake) if resolver is None else mock.patch.object(feishu_bug_intake, "resolve_lark_cli", side_effect=resolver), \
|
||||
mock.patch.dict(os.environ, env, clear=True), \
|
||||
contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
|
||||
try:
|
||||
code = feishu_bug_intake.main(args)
|
||||
except SystemExit as exc:
|
||||
code = int(exc.code or 0)
|
||||
return subprocess.CompletedProcess(args, code, stdout.getvalue(), stderr.getvalue())
|
||||
|
||||
def test_isolated_tenant_check_fetch_and_triage_contract(self) -> None:
|
||||
self.assertEqual(self.invoke("check").returncode, 0)
|
||||
downloads = self.d / "downloads"
|
||||
result = self.invoke("fetch", output=downloads)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
record = payload["records"][0]
|
||||
self.assertEqual(record["recordId"], "recBug1")
|
||||
self.assertEqual(record["priority"], "P1")
|
||||
self.assertEqual(record["updatedAt"], "2026-08-01T12:00:00Z")
|
||||
self.assertIn("Crash on save", record["title"])
|
||||
self.assertTrue(Path(record["attachments"][0]["localPath"]).is_relative_to(downloads))
|
||||
self.assertRegex(record["sourceRef"], r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
for secret in ("tenant-b", "base-secret", "tbl-bugs", "recBug1", "fileTok"):
|
||||
self.assertNotIn(secret, record["sourceRef"])
|
||||
for secret in ("base-secret", "fileTok", "app-secret-sentinel"):
|
||||
self.assertNotIn(secret, result.stdout)
|
||||
second = self.invoke("fetch", output=self.d / "repeat")
|
||||
self.assertEqual(second.returncode, 0, second.stderr)
|
||||
second_record = json.loads(second.stdout)["records"][0]
|
||||
self.assertRegex(second_record["sourceRef"], r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
self.assertEqual(record["sourceRef"], second_record["sourceRef"])
|
||||
for secret in ("tenant-b", "base-secret", "tbl-bugs", "recBug1", "fileTok"):
|
||||
self.assertNotIn(secret, second_record["sourceRef"])
|
||||
for secret in ("base-secret", "fileTok", "app-secret-sentinel"):
|
||||
self.assertNotIn(secret, second.stdout)
|
||||
calls = [json.loads(x) for x in self.log.read_text().splitlines()]
|
||||
for call in calls:
|
||||
if call[:1] == ["base"]:
|
||||
self.assertEqual(call[call.index("--profile") + 1], "tenant-b")
|
||||
self.assertNotIn("tenant-a", call)
|
||||
if call[:2] == ["base", "+record-download-attachment"]:
|
||||
self.assertFalse(Path(call[call.index("--output") + 1]).is_absolute())
|
||||
self.assertEqual(sum(1 for c in calls if c[:2] == ["base", "+record-list"]), 2)
|
||||
list_call = next(c for c in reversed(calls) if c[:2] == ["base", "+record-list"])
|
||||
self.assertEqual(list_call[list_call.index("--view-id") + 1], "view-ready")
|
||||
self.assertEqual(list_call[:2], ["base", "+record-list"])
|
||||
self.assertEqual(list_call.count("--field-id"), 8)
|
||||
|
||||
def test_fail_closed_wrong_profile_and_unsafe_response(self) -> None:
|
||||
bad = self.board.read_text().replace("profile: tenant-b", "profile: tenant-a")
|
||||
self.board.write_text(bad)
|
||||
result = self.invoke("fetch")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.board.write_text(bad.replace("profile: tenant-a", "profile: tenant-b"))
|
||||
result = self.invoke("fetch", mode="malformed")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="matrix", output=self.d / "matrix-output")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="cell", output=self.d / "cell-output")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="empty", output=self.d / "empty-output")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="escape", output=self.d / "downloads")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
|
||||
def test_resolver_trust_and_no_executable_override_surface(self) -> None:
|
||||
trusted, hostile = self.d / "trusted", self.d / "hostile"
|
||||
trusted.mkdir(); hostile.mkdir()
|
||||
safe = trusted / "lark-cli"
|
||||
safe.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8"); safe.chmod(0o755)
|
||||
(hostile / "lark-cli").write_text("#!/bin/sh\nexit 99\n", encoding="utf-8")
|
||||
(hostile / "lark-cli").chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]), mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=False):
|
||||
self.assertEqual(feishu_bug_intake.resolve_lark_cli(), safe)
|
||||
safe.chmod(0o775)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.resolve_lark_cli()
|
||||
help_result = self.invoke("--help")
|
||||
self.assertEqual(help_result.returncode, 0)
|
||||
self.assertNotIn("--lark-cli", help_result.stdout + help_result.stderr)
|
||||
self.assertNotIn("--executable", help_result.stdout + help_result.stderr)
|
||||
self.assertNotIn("executable_override", READER.read_text(encoding="utf-8"))
|
||||
|
||||
def test_fail_closed_envelopes_pagination_and_missing_trusted_cli(self) -> None:
|
||||
for mode in ("okfalse", "code", "ambiguous", "noprog"):
|
||||
result = self.invoke("fetch", mode=mode)
|
||||
self.assertNotEqual(result.returncode, 0, mode)
|
||||
self.assertEqual(result.stdout, "", mode)
|
||||
with mock.patch.object(feishu_bug_intake, "MAX_PAGES", 2):
|
||||
result = self.invoke("fetch", mode="max")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.assertEqual(result.stdout, "")
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", side_effect=feishu_bug_intake.IntakeError("missing trusted")):
|
||||
result = self.invoke("fetch", resolver=feishu_bug_intake.IntakeError("missing trusted"))
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.assertEqual(result.stdout, "")
|
||||
|
||||
def test_reference_template_example_contract_signals(self) -> None:
|
||||
paths = [ROOT / "skills/ack/references/feishu-bug-intake.md", ROOT / "skills/ack/templates/tasks.template.yaml", ROOT / "skills/ack/examples/tasks.example.yaml"]
|
||||
content = "\n".join(path.read_text(encoding="utf-8") for path in paths)
|
||||
self.assertIn("feishu-base:sha256:", content)
|
||||
self.assertIn('npm install --global --prefix "$HOME/.local" @larksuite/cli@latest', content)
|
||||
self.assertIn("profile add", content)
|
||||
self.assertIn("--brand feishu", content)
|
||||
self.assertTrue("scope" in content)
|
||||
self.assertIn("不要把 `lark-cli auth check`", content)
|
||||
self.assertNotIn("--lark-cli", content)
|
||||
self.assertNotIn("--executable", content)
|
||||
|
||||
def test_plan_organizes_stable_sources_against_a_real_task_board(self) -> None:
|
||||
first = json.loads(self.invoke("fetch").stdout)["records"][0]["sourceRef"]
|
||||
second = json.loads(self.invoke("fetch").stdout)["records"][0]["sourceRef"]
|
||||
self.assertRegex(first, r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
self.assertEqual(first, second)
|
||||
empty_plan = json.loads(self.invoke("plan").stdout)
|
||||
self.assertEqual(empty_plan["actions"], [{
|
||||
"sourceRef": first,
|
||||
"recordId": "recBug1",
|
||||
"action": "create",
|
||||
}])
|
||||
|
||||
base = self.board.read_text(encoding="utf-8")
|
||||
|
||||
def write_existing(status: str, updated_at: str, *, duplicate: bool = False) -> None:
|
||||
task = f"""tasks:
|
||||
- id: BUG-1
|
||||
title: Existing imported bug
|
||||
status: {status}
|
||||
source:
|
||||
kind: feishu-base
|
||||
ref: "{first}"
|
||||
recordId: recBug1
|
||||
updatedAt: "{updated_at}"
|
||||
"""
|
||||
if duplicate:
|
||||
task += f""" - id: BUG-2
|
||||
title: Duplicate imported bug
|
||||
status: open
|
||||
source:
|
||||
kind: feishu-base
|
||||
ref: "{first}"
|
||||
recordId: recBug1
|
||||
updatedAt: "{updated_at}"
|
||||
"""
|
||||
self.board.write_text(base.replace("tasks: []\n", task), encoding="utf-8")
|
||||
|
||||
write_existing("open", "2026-07-31T12:00:00Z")
|
||||
validator = ROOT / "skills/ack/scripts/validate_tasks.py"
|
||||
validated = subprocess.run(
|
||||
[sys.executable, str(validator), str(self.board)],
|
||||
text=True, capture_output=True, check=False,
|
||||
)
|
||||
self.assertEqual(validated.returncode, 0, validated.stderr)
|
||||
self.assertEqual(json.loads(self.invoke("plan").stdout)["actions"][0]["action"], "refresh")
|
||||
|
||||
write_existing("verified", "2026-07-31T12:00:00Z")
|
||||
self.assertEqual(json.loads(self.invoke("plan").stdout)["actions"][0]["action"], "drift")
|
||||
|
||||
write_existing("verified", "2026-08-01T12:00:00Z")
|
||||
self.assertEqual(json.loads(self.invoke("plan").stdout)["actions"][0]["action"], "unchanged")
|
||||
|
||||
write_existing("open", "2026-07-31T12:00:00Z", duplicate=True)
|
||||
duplicate_result = self.invoke("plan")
|
||||
self.assertNotEqual(duplicate_result.returncode, 0)
|
||||
self.assertEqual(duplicate_result.stdout, "")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,232 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from unittest import mock
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
ACK_SCRIPTS = REPO_ROOT / "skills" / "ack" / "scripts"
|
||||
sys.path.insert(0, str(ACK_SCRIPTS))
|
||||
import feishu_bug_intake # noqa: E402
|
||||
|
||||
|
||||
BOARD = """version: 1
|
||||
project:
|
||||
name: demo
|
||||
bugIntake:
|
||||
provider: feishu-base
|
||||
profile: tenant-b
|
||||
baseToken: bascnDemo
|
||||
tableId: tblDemo
|
||||
viewId: vewReady
|
||||
fields:
|
||||
title: fldTitle
|
||||
actual: fldActual
|
||||
expected: fldExpected
|
||||
stepsToReproduce: fldSteps
|
||||
acceptance: fldAcceptance
|
||||
priority: fldPriority
|
||||
attachments: fldAttachments
|
||||
updatedAt: fldUpdated
|
||||
tasks: []
|
||||
"""
|
||||
|
||||
|
||||
class FeishuBugIntakeUnitTests(unittest.TestCase):
|
||||
def make_fake_cli(self, root: Path) -> tuple[Path, Path]:
|
||||
log_path = root / "calls.jsonl"
|
||||
fake = root / "lark-cli"
|
||||
fake.write_text(
|
||||
"#!" + sys.executable + "\n"
|
||||
"import json, pathlib, sys\n"
|
||||
f"log = pathlib.Path({str(log_path)!r})\n"
|
||||
"args = sys.argv[1:]\n"
|
||||
"with log.open('a') as f: f.write(json.dumps(args) + '\\n')\n"
|
||||
"if args[:2] == ['profile', 'list']:\n"
|
||||
" if '--format' in args: raise SystemExit(8)\n"
|
||||
" print(json.dumps([{'name':'tenant-a','appId':'cli_a','brand':'feishu','active':True},{'name':'tenant-b','appId':'cli_b','brand':'feishu','active':False}]))\n"
|
||||
"elif args[:2] == ['base', '+record-list']:\n"
|
||||
" print(json.dumps({'code': 0, 'data': {'fields': ['fldTitle','fldActual','fldExpected','fldSteps','fldAcceptance','fldPriority','fldAttachments','fldUpdated'], 'record_id_list': ['recA'], 'data': [[' Bug\\n title ', ' actual ', 'expected', ['one', 'two'], 'accept', 'P1', [{'file_token':'fileA','name':'shot.png','type':'image/png','size':3}], '2026-08-01']]}}))\n"
|
||||
"elif args[:2] == ['base', '+record-download-attachment']:\n"
|
||||
" out = pathlib.Path(args[args.index('--output') + 1]); out.mkdir(parents=True, exist_ok=True); (out / 'shot.png').write_bytes(b'png'); print(json.dumps({'ok': True, 'data': {}}))\n"
|
||||
"else: raise SystemExit(2)\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
fake.chmod(0o755)
|
||||
return fake, log_path
|
||||
|
||||
def invoke(self, argv: list[str], executable: Path) -> tuple[int, str, str]:
|
||||
stdout, stderr = io.StringIO(), io.StringIO()
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=executable), contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
|
||||
code = feishu_bug_intake.main(argv)
|
||||
return code, stdout.getvalue(), stderr.getvalue()
|
||||
|
||||
def test_reader_exposes_check_and_fetch_commands(self) -> None:
|
||||
with self.assertRaises(SystemExit) as exited, contextlib.redirect_stdout(io.StringIO()):
|
||||
feishu_bug_intake.main(["--help"])
|
||||
self.assertEqual(exited.exception.code, 0)
|
||||
|
||||
def test_fetch_uses_mocked_trusted_executable_and_official_wire_shapes(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
board_path = temp / "tasks.yaml"
|
||||
board_path.write_text(BOARD, encoding="utf-8")
|
||||
fake, log_path = self.make_fake_cli(temp)
|
||||
hostile = temp / "hostile"
|
||||
hostile.mkdir()
|
||||
(hostile / "lark-cli").write_text("#!/bin/sh\nexit 99\n", encoding="utf-8")
|
||||
(hostile / "lark-cli").chmod(0o755)
|
||||
|
||||
with mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=False):
|
||||
code, output, error = self.invoke(["fetch", str(board_path), "--output-dir", str(temp / "downloads")], fake)
|
||||
|
||||
self.assertEqual(code, 0, error)
|
||||
payload = json.loads(output)
|
||||
self.assertEqual(payload["records"][0]["title"], "Bug title")
|
||||
self.assertEqual(payload["records"][0]["steps"], "one\ntwo")
|
||||
self.assertRegex(payload["records"][0]["sourceRef"], r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
self.assertNotIn("bascnDemo", output)
|
||||
self.assertNotIn("fileA", output)
|
||||
self.assertNotIn("token", payload["records"][0]["attachments"][0])
|
||||
self.assertTrue(Path(payload["records"][0]["attachments"][0]["localPath"]).is_file())
|
||||
calls = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
|
||||
self.assertEqual(calls[0], ["profile", "list"])
|
||||
for call in calls:
|
||||
if call[:1] == ["base"]:
|
||||
self.assertEqual(call[call.index("--profile") + 1], "tenant-b")
|
||||
|
||||
def test_resolver_ignores_hostile_path_and_rejects_unsafe_target(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
trusted, hostile = temp / "trusted", temp / "hostile"
|
||||
trusted.mkdir()
|
||||
hostile.mkdir()
|
||||
safe = trusted / "lark-cli"
|
||||
safe.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
safe.chmod(0o755)
|
||||
(hostile / "lark-cli").write_text("#!/bin/sh\nexit 99\n", encoding="utf-8")
|
||||
(hostile / "lark-cli").chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]), mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=False):
|
||||
self.assertEqual(feishu_bug_intake.resolve_lark_cli(), safe)
|
||||
safe.chmod(0o775)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
with self.assertRaisesRegex(feishu_bug_intake.IntakeError, "trusted"):
|
||||
feishu_bug_intake.resolve_lark_cli()
|
||||
|
||||
def test_resolver_accepts_only_the_official_npm_wrapper_shape(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
trusted = temp / "trusted"
|
||||
scripts = temp / "node_modules" / "@larksuite" / "cli" / "scripts"
|
||||
trusted.mkdir()
|
||||
scripts.mkdir(parents=True)
|
||||
wrapper = scripts / "run.js"
|
||||
wrapper.write_text(
|
||||
"#!" + sys.executable + "\nimport json\nprint(json.dumps({'ok': True}))\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
wrapper.chmod(0o755)
|
||||
manifest = scripts.parent / "package.json"
|
||||
manifest.write_text(json.dumps({
|
||||
"name": "@larksuite/cli",
|
||||
"bin": {"lark-cli": "scripts/run.js"},
|
||||
}), encoding="utf-8")
|
||||
native = scripts.parent / "bin" / "lark-cli"
|
||||
native.parent.mkdir()
|
||||
native.write_text(
|
||||
"#!" + sys.executable + "\nimport json\nprint(json.dumps({'ok': True}))\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
native.chmod(0o755)
|
||||
(trusted / "lark-cli").symlink_to(wrapper)
|
||||
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
self.assertEqual(feishu_bug_intake.resolve_lark_cli(), native)
|
||||
self.assertEqual(feishu_bug_intake.run_cli(["probe"]), {"ok": True})
|
||||
|
||||
manifest.write_text(json.dumps({
|
||||
"name": "lookalike",
|
||||
"bin": {"lark-cli": "scripts/run.js"},
|
||||
}), encoding="utf-8")
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.resolve_lark_cli()
|
||||
|
||||
def test_cli_environment_drops_credential_and_runtime_overrides(self) -> None:
|
||||
hostile = {
|
||||
"LARKSUITE_CLI_APP_ID": "wrong-app",
|
||||
"LARKSUITE_CLI_APP_SECRET": "wrong-secret",
|
||||
"LARKSUITE_CLI_CONFIG_DIR": "/tmp/wrong-config",
|
||||
"LARKSUITE_CLI_BRAND": "lark",
|
||||
"FEISHU_APP_SECRET": "wrong-feishu-secret",
|
||||
"NODE_OPTIONS": "--require=/tmp/inject.js",
|
||||
"PYTHONPATH": "/tmp/inject",
|
||||
}
|
||||
with mock.patch.dict(os.environ, hostile, clear=False):
|
||||
environment = feishu_bug_intake.cli_environment()
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
fake = Path(temp_dir) / "lark-cli"
|
||||
fake.write_text(
|
||||
"#!" + sys.executable + "\n"
|
||||
"import json, os\n"
|
||||
"keys = ['LARKSUITE_CLI_APP_ID','LARKSUITE_CLI_APP_SECRET','LARKSUITE_CLI_CONFIG_DIR','LARKSUITE_CLI_BRAND','FEISHU_APP_SECRET','NODE_OPTIONS','PYTHONPATH']\n"
|
||||
"print(json.dumps({'ok': True, 'data': {key: os.environ.get(key) for key in keys}}))\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
fake.chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=fake):
|
||||
child = feishu_bug_intake.run_cli(["probe"])
|
||||
self.assertEqual(set(environment) - {"HOME", "PATH"}, set(environment) & {"LANG", "LC_ALL", "LC_CTYPE"})
|
||||
for name in hostile:
|
||||
self.assertNotIn(name, environment)
|
||||
self.assertIsNone(child["data"][name])
|
||||
|
||||
def test_run_cli_rejects_error_and_ambiguous_envelopes(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
fake = temp / "lark-cli"
|
||||
fake.write_text(
|
||||
"#!" + sys.executable + "\nimport json, sys\nprint(sys.argv[1])\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
fake.chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=fake):
|
||||
for response in ('{"ok":false}', '{"code":7}', '{"data":{}}'):
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.run_cli([response])
|
||||
|
||||
def test_matrix_accepts_official_ok_envelope_and_data_rows(self) -> None:
|
||||
fields = ["fldTitle"]
|
||||
response = {
|
||||
"ok": True,
|
||||
"data": {"fields": fields, "record_id_list": ["recA"], "data": [["Bug"]]},
|
||||
}
|
||||
self.assertEqual(feishu_bug_intake.matrix_from_response(response, fields), (["recA"], [["Bug"]]))
|
||||
|
||||
def test_attachments_and_required_text_are_resource_bounded_and_strict(self) -> None:
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.attachment_items([{
|
||||
"file_token": "fileA",
|
||||
"name": "huge.png",
|
||||
"type": "image/png",
|
||||
"size": feishu_bug_intake.MAX_ATTACHMENT_BYTES + 1,
|
||||
}])
|
||||
too_many = [
|
||||
{"file_token": f"file{index}", "name": f"{index}.png", "size": 1}
|
||||
for index in range(feishu_bug_intake.MAX_ATTACHMENTS_PER_RECORD + 1)
|
||||
]
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.attachment_items(too_many)
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.text({"unexpected": "value"})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
+11
-1
@@ -64,13 +64,23 @@ class AckSkillContentTests(unittest.TestCase):
|
||||
"references/delivery.md",
|
||||
):
|
||||
self.assertTrue((ack_dir / relative_path).is_file(), relative_path)
|
||||
self.assertEqual((ack_dir / "VERSION").read_text(encoding="utf-8").strip(), "0.11.0")
|
||||
version = (ack_dir / "VERSION").read_text(encoding="utf-8").strip()
|
||||
self.assertEqual(version, "0.12.0")
|
||||
self.assertIn(
|
||||
f'ackVersion: "{version}"',
|
||||
(ack_dir / "examples" / "tasks.example.yaml").read_text(encoding="utf-8"),
|
||||
)
|
||||
self.assertIn(
|
||||
f"ack v{version}",
|
||||
(ack_dir / "examples" / "project.example.md").read_text(encoding="utf-8"),
|
||||
)
|
||||
self.assertIn(
|
||||
'ackVersion: "<接入时的 ack skill 版本>"',
|
||||
(ack_dir / "templates" / "tasks.template.yaml").read_text(
|
||||
encoding="utf-8"
|
||||
),
|
||||
)
|
||||
self.assertTrue((ack_dir / "references" / "feishu-bug-intake.md").is_file())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -148,6 +148,39 @@ class AckTaskValidationTests(unittest.TestCase):
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
self.assertIn("任务板校验通过", result.stdout)
|
||||
|
||||
def test_legacy_sources_remain_open_while_feishu_sources_are_strict(self) -> None:
|
||||
for legacy_source in (
|
||||
"manual",
|
||||
{"kind": "jira", "ref": "JIRA-123", "project": "OPS"},
|
||||
):
|
||||
with self.subTest(legacy_source=legacy_source):
|
||||
board = valid_knowledge_board()
|
||||
board["tasks"][0]["source"] = legacy_source
|
||||
self.assert_board_accepted_in_all_modes(board)
|
||||
|
||||
valid_ref = "feishu-base:sha256:" + "a" * 64
|
||||
valid = valid_knowledge_board()
|
||||
valid["tasks"][0]["source"] = {
|
||||
"kind": "feishu-base",
|
||||
"ref": valid_ref,
|
||||
"recordId": "recA",
|
||||
"updatedAt": "2026-08-01T12:00:00Z",
|
||||
}
|
||||
self.assert_board_accepted_in_all_modes(valid)
|
||||
|
||||
raw = copy.deepcopy(valid)
|
||||
raw["tasks"][0]["source"]["ref"] = "feishu-base:tenant:base-secret:recA"
|
||||
self.assert_board_rejected_in_all_modes(
|
||||
raw,
|
||||
"必须是不透明 feishu-base SHA-256 引用",
|
||||
)
|
||||
|
||||
duplicate = copy.deepcopy(valid)
|
||||
second = copy.deepcopy(duplicate["tasks"][0])
|
||||
second["id"] = "T-2"
|
||||
duplicate["tasks"].append(second)
|
||||
self.assert_board_rejected_in_all_modes(duplicate, "来源引用重复")
|
||||
|
||||
def test_v010_requires_structured_routing_but_v009_remains_readable(self) -> None:
|
||||
current = valid_knowledge_board()
|
||||
current["ackVersion"] = "0.10.0"
|
||||
|
||||
@@ -0,0 +1,405 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import shlex
|
||||
import shutil
|
||||
import socket
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from unittest import mock
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
ORC_DIR = REPO_ROOT / "skills" / "orc"
|
||||
SCRIPT = ORC_DIR / "scripts" / "resolve_profile.py"
|
||||
CONFIG = ORC_DIR / "templates" / "config.template.yaml"
|
||||
|
||||
spec = importlib.util.spec_from_file_location("orc_resolve_profile", SCRIPT)
|
||||
assert spec is not None and spec.loader is not None
|
||||
orc_profiles = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(orc_profiles)
|
||||
|
||||
|
||||
class OrcSkillTests(unittest.TestCase):
|
||||
def test_orc_is_explicit_and_routes_to_independent_skills(self) -> None:
|
||||
skill = (ORC_DIR / "SKILL.md").read_text(encoding="utf-8")
|
||||
routing = (ORC_DIR / "references" / "routing.md").read_text(encoding="utf-8")
|
||||
metadata = (ORC_DIR / "agents" / "openai.yaml").read_text(encoding="utf-8")
|
||||
|
||||
self.assertIn("allow_implicit_invocation: false", metadata)
|
||||
self.assertIn("low", skill)
|
||||
self.assertIn("mid", skill)
|
||||
self.assertIn("high", skill)
|
||||
self.assertIn("只支持 `cli: codex`", skill)
|
||||
for child in ("$ack", "$manage-release", "$deb-publisher", "$publish-docker-image"):
|
||||
self.assertIn(child, routing)
|
||||
|
||||
def test_children_do_not_reference_orc(self) -> None:
|
||||
for child in ("ack", "manage-release", "deb-publisher", "publish-docker-image"):
|
||||
for path in (REPO_ROOT / "skills" / child).rglob("*"):
|
||||
if not path.is_file() or "__pycache__" in path.parts:
|
||||
continue
|
||||
content = path.read_text(encoding="utf-8", errors="ignore")
|
||||
self.assertNotIn("$orc", content, str(path))
|
||||
self.assertNotRegex(
|
||||
content,
|
||||
r"(?<![A-Za-z0-9_-])/orc(?![A-Za-z0-9_-])",
|
||||
str(path),
|
||||
)
|
||||
self.assertNotRegex(content, r"\bORC\b", str(path))
|
||||
self.assertNotIn("skills/orc", content, str(path))
|
||||
|
||||
def test_routing_pins_normal_pr_and_unsupported_release_gate(self) -> None:
|
||||
routing = (ORC_DIR / "references" / "routing.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
|
||||
self.assertIn("普通非发布 PR/MR", routing)
|
||||
self.assertIn("最多到", routing)
|
||||
self.assertIn("review_ready", routing)
|
||||
self.assertIn("当前 task 粒度无法安全表达", routing)
|
||||
|
||||
def test_template_and_cli_validate(self) -> None:
|
||||
config = orc_profiles.load_config(CONFIG)
|
||||
self.assertEqual(set(config["profiles"]), {"low", "mid", "high"})
|
||||
completed = subprocess.run(
|
||||
[sys.executable, str(SCRIPT), "validate", str(CONFIG)],
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(completed.returncode, 0, completed.stderr)
|
||||
self.assertIn('"ok": true', completed.stdout)
|
||||
|
||||
clean_python = subprocess.run(
|
||||
[sys.executable, "-I", "-S", str(SCRIPT), "validate", str(CONFIG)],
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(clean_python.returncode, 0, clean_python.stderr)
|
||||
|
||||
def test_level_precedence_is_stage_then_global_then_config(self) -> None:
|
||||
config = orc_profiles.load_config(CONFIG)
|
||||
stage = orc_profiles.resolve_profile(
|
||||
config, stage="docker", global_level="mid", stage_level="high"
|
||||
)
|
||||
global_choice = orc_profiles.resolve_profile(
|
||||
config, stage="docker", global_level="mid"
|
||||
)
|
||||
configured = orc_profiles.resolve_profile(config, stage="docker")
|
||||
fallback_config = copy.deepcopy(config)
|
||||
del fallback_config["stageDefaults"]["docker"]
|
||||
fallback = orc_profiles.resolve_profile(fallback_config, stage="docker")
|
||||
|
||||
self.assertEqual((stage["level"], stage["selectionSource"]), ("high", "request.stage"))
|
||||
self.assertEqual((global_choice["level"], global_choice["selectionSource"]), ("mid", "request.global"))
|
||||
self.assertEqual((configured["level"], configured["selectionSource"]), ("low", "config.stageDefaults.docker"))
|
||||
self.assertEqual((fallback["level"], fallback["selectionSource"]), ("mid", "config.defaultLevel"))
|
||||
|
||||
def test_resolver_builds_fixed_worker_args_without_free_command_fields(self) -> None:
|
||||
config = orc_profiles.load_config(CONFIG)
|
||||
plan = orc_profiles.resolve_profile(config, stage="release")
|
||||
|
||||
self.assertEqual(plan["workerArgs"][:2], ["--model", "gpt-5.6-terra"])
|
||||
self.assertIn("--strict-config", plan["workerArgs"])
|
||||
self.assertNotIn("danger-full-access", " ".join(plan["workerArgs"]))
|
||||
self.assertNotIn("env", plan["profile"])
|
||||
self.assertNotIn("command", plan["profile"])
|
||||
|
||||
def test_worker_environment_selects_one_model_and_remote_auth(self) -> None:
|
||||
ambient = {
|
||||
"OPENAI_API_KEY": "openai-secret",
|
||||
"AZURE_OPENAI_API_KEY": "azure-secret",
|
||||
"GITHUB_TOKEN": "github-secret",
|
||||
"GITLAB_TOKEN": "gitlab-secret",
|
||||
"GITEA_TOKEN": "gitea-secret",
|
||||
"FORGEJO_TOKEN": "forgejo-secret",
|
||||
"DEB_TOKEN": "deb-secret",
|
||||
"SSH_AUTH_SOCK": "/tmp/agent.sock",
|
||||
"HTTPS_PROXY": "https://user:secret@proxy.example",
|
||||
}
|
||||
with mock.patch.dict(os.environ, ambient, clear=True):
|
||||
environment = orc_profiles.worker_environment(
|
||||
"release",
|
||||
model_auth="openai",
|
||||
remote_auth="forgejo-token",
|
||||
)
|
||||
|
||||
self.assertEqual(environment["OPENAI_API_KEY"], "openai-secret")
|
||||
self.assertEqual(environment["FORGEJO_TOKEN"], "forgejo-secret")
|
||||
for rejected in (
|
||||
"AZURE_OPENAI_API_KEY",
|
||||
"GITHUB_TOKEN",
|
||||
"GITLAB_TOKEN",
|
||||
"GITEA_TOKEN",
|
||||
"DEB_TOKEN",
|
||||
"SSH_AUTH_SOCK",
|
||||
"HTTPS_PROXY",
|
||||
):
|
||||
self.assertNotIn(rejected, environment)
|
||||
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "deb remote auth"):
|
||||
orc_profiles.worker_environment(
|
||||
"deb",
|
||||
model_auth="codex-login",
|
||||
remote_auth="forgejo-token",
|
||||
)
|
||||
|
||||
with mock.patch.dict(os.environ, {}, clear=True):
|
||||
with self.assertRaisesRegex(
|
||||
orc_profiles.ConfigError,
|
||||
"selected authentication variable is unavailable",
|
||||
):
|
||||
orc_profiles.worker_environment(
|
||||
"release",
|
||||
model_auth="openai",
|
||||
remote_auth="none",
|
||||
)
|
||||
|
||||
with mock.patch.dict(os.environ, {"OPENAI_API_KEY": ""}, clear=True):
|
||||
with self.assertRaisesRegex(
|
||||
orc_profiles.ConfigError,
|
||||
"selected authentication variable is unavailable",
|
||||
):
|
||||
orc_profiles.worker_environment(
|
||||
"release",
|
||||
model_auth="openai",
|
||||
remote_auth="none",
|
||||
)
|
||||
|
||||
def test_ssh_auth_requires_a_trusted_user_socket(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
socket_path = root / "agent.sock"
|
||||
with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as agent:
|
||||
agent.bind(str(socket_path))
|
||||
socket_path.chmod(0o600)
|
||||
with mock.patch.dict(
|
||||
os.environ,
|
||||
{"SSH_AUTH_SOCK": str(socket_path)},
|
||||
clear=True,
|
||||
):
|
||||
environment = orc_profiles.worker_environment(
|
||||
"release",
|
||||
model_auth="codex-login",
|
||||
remote_auth="ssh-agent",
|
||||
)
|
||||
self.assertEqual(environment["SSH_AUTH_SOCK"], str(socket_path))
|
||||
|
||||
regular_file = root / "not-a-socket"
|
||||
regular_file.write_text("not a socket", encoding="utf-8")
|
||||
regular_file.chmod(0o600)
|
||||
with mock.patch.dict(
|
||||
os.environ,
|
||||
{"SSH_AUTH_SOCK": str(regular_file)},
|
||||
clear=True,
|
||||
):
|
||||
with self.assertRaisesRegex(
|
||||
orc_profiles.ConfigError,
|
||||
"not a trusted user socket",
|
||||
):
|
||||
orc_profiles.worker_environment(
|
||||
"release",
|
||||
model_auth="codex-login",
|
||||
remote_auth="ssh-agent",
|
||||
)
|
||||
|
||||
def test_trusted_orca_ignores_ambient_path(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
trusted = root / "trusted"
|
||||
hostile = root / "hostile"
|
||||
trusted.mkdir()
|
||||
hostile.mkdir()
|
||||
trusted_orca = trusted / "orca"
|
||||
hostile_orca = hostile / "orca"
|
||||
for executable in (trusted_orca, hostile_orca):
|
||||
executable.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
executable.chmod(0o700)
|
||||
|
||||
with (
|
||||
mock.patch.object(
|
||||
orc_profiles,
|
||||
"trusted_path_entries",
|
||||
return_value=[trusted],
|
||||
),
|
||||
mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=True),
|
||||
):
|
||||
resolved = orc_profiles.resolve_trusted_executable("orca")
|
||||
|
||||
self.assertEqual(resolved, trusted_orca)
|
||||
|
||||
def test_config_rejects_unsafe_or_ambiguous_profiles(self) -> None:
|
||||
base = orc_profiles.load_config(CONFIG)
|
||||
|
||||
free_command = copy.deepcopy(base)
|
||||
free_command["profiles"]["low"]["command"] = "codex --dangerously-bypass"
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "unknown fields"):
|
||||
orc_profiles.validate_config(free_command)
|
||||
|
||||
full_access = copy.deepcopy(base)
|
||||
full_access["profiles"]["high"]["permissionMode"] = "danger-full-access"
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "workspace-write in ORC v1"):
|
||||
orc_profiles.validate_config(full_access)
|
||||
|
||||
read_only = copy.deepcopy(base)
|
||||
read_only["profiles"]["low"]["permissionMode"] = "read-only"
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "workspace-write in ORC v1"):
|
||||
orc_profiles.validate_config(read_only)
|
||||
|
||||
missing_level = copy.deepcopy(base)
|
||||
del missing_level["profiles"]["mid"]
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "missing fields: mid"):
|
||||
orc_profiles.validate_config(missing_level)
|
||||
|
||||
option_model = copy.deepcopy(base)
|
||||
option_model["profiles"]["low"]["model"] = "--model"
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "safe exact model ID"):
|
||||
orc_profiles.validate_config(option_model)
|
||||
|
||||
list_policy = copy.deepcopy(base)
|
||||
list_policy["profiles"]["low"]["approvalPolicy"] = ["never"]
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "approvalPolicy"):
|
||||
orc_profiles.validate_config(list_policy)
|
||||
|
||||
def test_config_reader_rejects_symlinks_and_redacts_parser_input(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temporary:
|
||||
root = Path(temporary)
|
||||
real = root / "real.yaml"
|
||||
real.write_text(CONFIG.read_text(encoding="utf-8"), encoding="utf-8")
|
||||
linked = root / "linked.yaml"
|
||||
linked.symlink_to(real)
|
||||
with self.assertRaisesRegex(orc_profiles.ConfigError, "safely read"):
|
||||
orc_profiles.load_config(linked)
|
||||
|
||||
malformed = root / "malformed.yaml"
|
||||
secret_marker = "PRIVATE_MATERIAL_MUST_NOT_APPEAR"
|
||||
malformed.write_text(f"{secret_marker}: [unterminated\n", encoding="utf-8")
|
||||
completed = subprocess.run(
|
||||
[sys.executable, str(SCRIPT), "validate", str(malformed)],
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(completed.returncode, 1)
|
||||
self.assertNotIn(secret_marker, completed.stderr)
|
||||
|
||||
def test_bound_plan_enforces_registered_allowlisted_worktree(self) -> None:
|
||||
git = shutil.which("git")
|
||||
self.assertIsNotNone(git)
|
||||
assert git is not None
|
||||
git_path = Path(git).resolve()
|
||||
|
||||
with tempfile.TemporaryDirectory(prefix="orc shell $(id) ' ") as temporary:
|
||||
temporary_root = Path(temporary).resolve()
|
||||
root = temporary_root / "project"
|
||||
root.mkdir()
|
||||
subprocess.run(
|
||||
[str(git_path), "init", "-q", str(root)],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
)
|
||||
config_path = root / "docs" / "orc" / "config.yaml"
|
||||
config_path.parent.mkdir(parents=True)
|
||||
config_path.write_text(CONFIG.read_text(encoding="utf-8"), encoding="utf-8")
|
||||
fake_codex = root / "trusted-codex" / "codex"
|
||||
fake_codex.parent.mkdir()
|
||||
fake_codex.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
fake_codex.chmod(0o700)
|
||||
fake_orca = root / "trusted-orca" / "orca"
|
||||
fake_orca.parent.mkdir()
|
||||
fake_orca.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
fake_orca.chmod(0o700)
|
||||
|
||||
def executable(name: str) -> Path:
|
||||
return {
|
||||
"git": git_path,
|
||||
"codex": fake_codex,
|
||||
"orca": fake_orca,
|
||||
}[name]
|
||||
|
||||
with (
|
||||
mock.patch.object(
|
||||
orc_profiles,
|
||||
"resolve_trusted_executable",
|
||||
side_effect=executable,
|
||||
),
|
||||
mock.patch.object(
|
||||
orc_profiles,
|
||||
"resolve_trusted_python",
|
||||
return_value=Path(sys.executable).resolve(),
|
||||
),
|
||||
mock.patch.object(
|
||||
orc_profiles,
|
||||
"_executable_facts",
|
||||
return_value={
|
||||
"path": str(fake_codex),
|
||||
"device": 1,
|
||||
"inode": 2,
|
||||
"size": 3,
|
||||
"mtimeNs": 4,
|
||||
"version": "codex-test 1",
|
||||
},
|
||||
),
|
||||
):
|
||||
plan = orc_profiles.build_launch_plan(
|
||||
config_path,
|
||||
project_root=root,
|
||||
worktree=root,
|
||||
stage="code",
|
||||
stage_level="high",
|
||||
)
|
||||
|
||||
self.assertEqual(plan["argv"][0], str(fake_codex))
|
||||
self.assertEqual(plan["terminalCreateArgv"][0], str(fake_orca))
|
||||
self.assertEqual(plan["worktree"], str(root))
|
||||
self.assertEqual(plan["selectionSource"], "request.stage")
|
||||
self.assertTrue(plan["launchFingerprint"].startswith("sha256:"))
|
||||
self.assertIn("_launch", plan["launcherArgv"])
|
||||
self.assertEqual(plan["launcherArgv"][1:3], ["-I", "-S"])
|
||||
self.assertIn("python", plan)
|
||||
self.assertEqual(plan["worktreeSelector"], f"path:{root}")
|
||||
self.assertNotIn("PRIVATE", json.dumps(plan))
|
||||
self.assertEqual(shlex.split(plan["terminalCommand"]), plan["launcherArgv"])
|
||||
self.assertEqual(
|
||||
shlex.split(plan["terminalCreateShellCommand"]),
|
||||
plan["terminalCreateArgv"],
|
||||
)
|
||||
command_index = plan["terminalCreateArgv"].index("--command")
|
||||
self.assertEqual(
|
||||
plan["terminalCreateArgv"][command_index + 1],
|
||||
plan["terminalCommand"],
|
||||
)
|
||||
|
||||
outside = temporary_root / "outside"
|
||||
outside.mkdir()
|
||||
subprocess.run(
|
||||
[str(git_path), "init", "-q", str(outside)],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
)
|
||||
with mock.patch.object(
|
||||
orc_profiles,
|
||||
"resolve_trusted_executable",
|
||||
side_effect=executable,
|
||||
):
|
||||
with self.assertRaisesRegex(
|
||||
orc_profiles.ConfigError,
|
||||
"not in allowedWorktrees",
|
||||
):
|
||||
orc_profiles.validate_worktree(
|
||||
orc_profiles.load_config(config_path),
|
||||
project_root_value=root,
|
||||
worktree_value=outside,
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user