工作流（Orchestrator）和 AI 代理（Agent Runner）之间的"合同"。适用于所有 AI 驱动的工作流。
| 通道 | 规范 | 示例 |
|---|---|---|
| 环境变量 | 通过 env: 传入，命名用 UPPER_SNAKE_CASE |
ISSUE_NUMBER、ISSUE_TITLE、BRANCH、PR_NUMBER |
| 上下文文件 | 工作流用 gh CLI 预获取，存在 $RUNNER_TEMP 中 |
issue-context.json、PR_COMMENTS_JSON |
| Git 工作树 | 工作流负责 checkout 到正确的分支/commit | actions/checkout@v4 with ref: and fetch-depth: |
| 输出目录 | 通过 OUTPUT_DIR 环境变量告知 AI 写入位置 |
通常设为 $RUNNER_TEMP |
| 文件 | 由哪个工作流写入 | 工作流怎么读取 |
|---|---|---|
analysis.md |
Analyze Issue | cat analysis.md | gh issue comment --body-file - |
failure_reason.txt |
所有（失败时） | gh issue comment --body-file failure_reason.txt |
pr_title.txt |
Implement | gh pr create --title-file pr_title.txt |
pr_description.txt |
Implement | gh pr create --body-file pr_description.txt |
has_commits.txt |
Implement PR | 读 "true"/"false" 决定是否 push |
should_push.txt |
Update Branch | 读 "true"/"false" 决定是否 push |
comment.md |
Update Branch | gh pr comment --body-file comment.md |
summary.md |
Review | 诊断/记录用 |
verdict.txt |
Review | 决定 PR 是"ready"还是"needs changes" |
review_payload.json |
Review | 结构化评审数据（评论、行级建议等） |
replies.json |
Implement PR | 针对每条评审评论的回复 |
architecture_review_output.json |
Architecture Review | PRD 提案的结构化数据 |
适用：只是生成内容，不修改仓库（比如写 PR 标题/描述、拆解 PRD 为子 Issue）。prompt 带输出 schema，验证失败则重试（同一 session，最多 N 次）。
适用：会提交代码或评论的步骤。
为什么？如果一次 LLM 调用既做工作又输出严格 JSON，格式错一个字段整个运行就失败了——包括副作用。分离之后，工作不会丢，提取可以重试。
| Secret | 用途 |
|---|---|
GITHUB_TOKEN | 内置。工作流用于大部分 tracker 操作（标签、评论、PR 管理）。 |
AGENT_PAT | 强烈推荐。用于需要触发下游工作流的操作（绕过 GITHUB_TOKEN 的递归抑制）。 |
| Agent-runner credential | 必须。认证 AI 服务。sandcastle 用 CLAUDE_CODE_OAUTH_TOKEN。 |
| 工具 | 风险 | 何时允许 |
|---|---|---|
Read | 无 | 始终 |
Grep | 无 | 始终 |
Glob | 无 | 始终 |
Write | 会修改文件 | Implement 工作流 |
Edit | 会修改文件 | Implement 工作流 |
Bash | 会执行命令 | 需要编译/测试的工作流 |