bkd

BKD

通过向 $BKD_URL 发送 HTTP 请求来操作 BKD；该变量必须指向 BKD API 根路径，例如 http://host:port/api。

保持此入口文件简洁。仅加载当前轮次所需的参考资料。

始终生效的规则

1. 发起任何请求前，先确认 $BKD_URL。如果缺少该变量，请询问其值。
2. 使用 curl -sS --fail-with-body，并在解析前检查其退出状态。 对于修改操作，还要断言 .success == true；切勿依赖 curl -s | jq， 否则 HTTP 错误和失败响应可能会被悄然放过。
3. 每次发送后续消息前，都要立即读取目标的 statusId——切勿使用 记忆中的状态，也绝不要向 done 状态的问题发送后续消息： 这只会将消息加入队列，无法唤醒任何内容。先将其 PATCH 到 review， 确认重新读取后显示 review，再发送消息（references/rest-api.md 中的 bkd_follow_up 会执行此操作）。这适用于所有后续消息，包括已派发问题发送的报告和唤醒消息。 根据 statusId 路由：todo -> POST 完整的后续消息，然后 PATCH 到 working；done -> PATCH 到 review，然后 POST 后续消息； review/working -> 直接 POST 后续消息。后续消息会自动将 review 转为 working。对已处于 working 状态的问题执行 PATCH 不会产生任何效果。 /restart 仅适用于失败/已取消的会话，并会重放已存储的提示词。若需要立即唤醒，仅有 {success:true} 并不足够：queued:true 并不能证明已唤醒；请检查 executionId、问题的 sessionStatus（pending/running），或 /processes。从 todo 到 working 的 PATCH 是发出后不等待结果的操作：重新读取问题；如果 sessionStatus 为 failed，则 POST 一条后续消息以刷新待处理输入。
4. 启动任何执行前，检查 /processes/capacity。
5. 将已完成的工作移至 review，而不是 done。只有在人类 确认后才使用 done——但三层模式中的 L1 或 MR 主控在其工作流或泳道 合并到基础分支后，应将其移至 done，而非自身（参见相应参考文档）。 转为 done 会取消正在运行的会话，并导致所有以该问题为目标的 cron 失败 （失败 3 次后会自动暂停）：请先删除由你管理的 cron。
6. 所有问题间通信都使用后续消息，并在每条后续消息正文中标记 bkd_with_sender （或通过 bkd_follow_up 发送），使其显示为来自你的问题，而非用户。请参阅 references/rest-api.md → 安全发送请求正文。
7. 除非 API 另有说明，否则将项目和问题的删除视为软删除。
8. 成功的 API 调用通常使用 { success, data }，应用层失败通常使用 { success, error }，但某些 HTTP 验证错误不会返回 JSON 封装。先检查传输/HTTP 是否成功，再检查响应封装； 任一检查失败时，都应安全地拒绝继续。
9. 等待子任务或长时间运行的操作时，绝不要使用 sleep。在三层模式中，L1 绝不会创建 cron：用户消息和 L2 后续消息会唤醒它。每个 L2 都负责自己的 issue-follow-up cron，并在每轮之间结束当前回合。对于非三层编排，请使用 references/orchestration.md 中所述的协调器 cron。
10. 绝不内联文本规则：绝不要将自由格式文本（提示词、描述）内联到 -d '{...}' 中——引号、$、反引号和换行符会在 Shell 与 JSON 转义过程中被破坏。将文本写入仓库外的临时文件，用 jq 构建正文，然后使用 --data-binary @file 发送 POST 请求。请参阅 references/rest-api.md → 安全发送请求正文。固定值正文（例如 {"statusId":"working"}）可以安全内联。
11. 若要紧急更正处于 working 状态的问题，请先停止当前回合，再发送 更正。可尝试使用 cancel 进行软中断（大约 3–20 s 后会转为 review），或使用 terminate 立即强制终止。重新读取问题，并要求其状态为 statusId:review；仍处于 working 状态时绝不要发送更正。如果在该时间范围内取消操作仍未使其转为 review，且更正不能等待，则终止该问题。进入 review 后，发送后续消息；BKD 会将其转为 working 并启动 替代回合。done 状态的问题采用相同的最终流程：将其移至 review，然后发送后续消息。

核心工作流

三层协调快捷方式

当用户说出“使用 bkd 开始协调”或“启动 BKD L1”之类的短语时，将当前 Agent 会话视为 L1，并加载 references/three-tier-coordination.md。用户无需在提示词中重复完整的 L1/L2/L3 规则。

自动模式快捷方式

当用户要求无人值守运行时——“自动模式”、“全自动”、“L1 自动审核 合并，把计划跑完”——加载 references/three-tier-coordination.md → 自动模式（无人值守 L1）。此激活即为常设授权，用于替代约定计划中 L1 的逐批派发和合并门槛：L1 自行审核并合并每个 L2 分支，与所属 L2 处理范围内的问题，运行一个看门狗 cron，并且仅在遇到文档规定的硬性停止条件时停止 （超出范围的工作、对外操作或不可逆操作、重试次数耗尽、轮次预算用尽）。这也适用于 MR 模式，此时主协调器自行接收每个通道报告的工作，而不向用户询问。

多仓库协调快捷方式（MR 模式）

当用户说出“启动 BKD 多仓库协调”或“启动多仓库协调”之类的短语，或者项目目录中发现有多个 git 仓库时，加载 references/multi-repo-coordination.md。所有操作都在当前项目中进行——MR 模式绝不创建项目：一个 L1 主协调器 issue 在工作区中维护 PMA 格式的台账，并且只负责协调和转发（不处理 diff、不构建、不判断代码）；每个仓库对应一个通道 issue（L2），并根据其提示词中注明的工作目录与该仓库绑定 （useWorktree:false，每次 git 调用都使用 git -C <repo>），因此任何 issue 都不会跨仓库提交。

消息系统

当用户要求启用消息系统——“启用消息系统”、“启用决策 系统”、“enable the messages system”、“use decision events”——或要求通知某事（“通知我”、“notify me when …”）时，在任何 BKD 会话中 加载 references/messages.md。随后，Agent 自己的 issue（发送方）会向 BKD 的 /messages 收件箱发送消息，该收件箱还会将消息转发到用户的 webhook / Telegram 频道：

• 对于任何需要人工选择的事项，发送决策——用户的回答会回复发送方，让其继续下一步；不受影响的工作会继续进行；
• 对于里程碑、完成事项或阻塞问题，发送通知（单向），或发送自由格式问题（expects: "reply"，按决策方式作答）。

它既适用于单个 issue，也适用于任何协调器；三层协调中的 L1 和 MR 主协调器默认使用此系统。切勿将其用于常规进度更新。只有 /decisions（contract v1）的服务器会提供决策，不提供通知；参考文档包含探测方式和对话回退方案。

单个 Issue 执行

set -o pipefail

# 1. Create issue
ISSUE=$(jq -n --arg title "short title" '{title:$title,statusId:"todo"}' \
  | curl -sS --fail-with-body -X POST "$BKD_URL/projects/{projectId}/issues" \
      -H 'Content-Type: application/json' -d @-) || exit 1
if ! printf '%s\n' "$ISSUE" | jq -e '.success == true and (.data.id | type == "string")' >/dev/null; then
  printf 'BKD error: %s\n' "$(printf '%s\n' "$ISSUE" | jq -r '.error // "invalid response"')" >&2
  exit 1
fi
ISSUE_ID=$(printf '%s\n' "$ISSUE" | jq -er '.data.id')

# 2. Queue the complete instruction while the issue is still todo
cat > /tmp/bkd-prompt.txt <<'PROMPT'
full implementation details
PROMPT
# sender: this issue, when running inside BKD (see bkd_with_sender in references/rest-api.md)
jq -n --rawfile prompt /tmp/bkd-prompt.txt --arg p "${BKD_PROJECT_ID:-}" --arg i "${BKD_ISSUE_ID:-}" \
  '{prompt: $prompt} + (if $i != "" then {sender: {kind: "agent", projectId: $p, issueId: $i}} else {} end)' \
  > /tmp/bkd-body.json
FOLLOWUP=$(curl -sS --fail-with-body -X POST "$BKD_URL/projects/{projectId}/issues/$ISSUE_ID/follow-up" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/bkd-body.json) || exit 1
printf '%s\n' "$FOLLOWUP" | jq -e '.success == true' >/dev/null || exit 1

# 3. Start the first execution; this transition consumes the queued instruction
START=$(curl -sS --fail-with-body -X PATCH "$BKD_URL/projects/{projectId}/issues/$ISSUE_ID" \
  -H 'Content-Type: application/json' \
  -d '{"statusId":"working"}') || exit 1
printf '%s\n' "$START" | jq -e '.success == true' >/dev/null || exit 1

每次 BKD 变更后都应用这两项检查：curl --fail-with-body 必须成功，然后 .success 必须为 true。使用 jq -er 获取必需的 .data 值。在缺少 set -e 的 shell 中，|| 块内单独的 false 不会中止执行。

快速操作

set -o pipefail

# Health check
curl -sS --fail-with-body "$BKD_URL/health" | jq

# Execution capacity
curl -sS --fail-with-body "$BKD_URL/processes/capacity" | jq

# Monitor logs (last 3 turns, assistant messages only)
curl -sS --fail-with-body "$BKD_URL/projects/{projectId}/issues/{issueId}/logs/filter/types/assistant-message/turn/last3" | jq

# Cron jobs (soft-deleted jobs are never listed)
curl -sS --fail-with-body "$BKD_URL/cron/actions" | jq
curl -sS --fail-with-body "$BKD_URL/cron" | jq

参考资料包

仅加载当前任务所需的内容：

• references/rest-api.md 用于查阅准确的 BKD 路由、负载结构、查询参数和字段列表。
• references/orchestration.md 用于了解多子任务分派工作流、模式选择（worktree 与 simple）、子任务创建和监控，以及后续沟通模式。
• references/quality-review.md 用于了解子任务自查职责、协调器日志筛选评估和信号分类。
• references/merge-strategy.md 用于了解 worktree 分支合并、冲突解决、合并后验证，以及 worktree 模式下子任务完成后的清理。
• references/multi-repo-coordination.md 用于 MR 模式：一个工作区目录包含多个 git 仓库时，采用仅负责协调的 L1 主协调器，每个仓库分配一个 L2 通道；所有议题均创建在当前项目中，并将仓库路径设为提示词中的工作目录；此外还包括 PMA 格式的工作区台账、跨仓库契约排序、边界检查，以及按仓库回滚提交。
• references/messages.md 当消息系统已启用时使用——用户在任意 BKD 会话中启用后，或在三层协调和 MR 协调中默认启用时——且 Agent 需要用户决策，或有信息需要告知用户时使用。内容包括启用消息系统、选择决策或通知、v2 /messages 和 v1 /decisions 的探测与 API、唤醒信号、消息扫描、如何应用、确认、关闭或撤回答复、webhook 负载，以及对话回退方案。
• references/three-tier-coordination.md 用于了解由事件驱动的 L1、由 cron 驱动的 L2 和短生命周期自主协调的 L3：面向用户的 L1 仅由用户或 L2 后续跟进唤醒；每个 campaign 划分为多个有明确范围的 L2 协调器；每个 L2 管理自己的 DAG 和 15 分钟自运行 cron；L3 议题执行短生命周期子任务。此模式与引擎无关——L1/L2/L3 可以分别运行在不同引擎上（Claude Code、Codex 等）；除非用户指定模型，否则使用服务器默认模型。若 campaign 跨越多个会话或数小时、需要根据容量调度 DAG，且必须持续运行、不得休眠，请优先选择此模式，而非 orchestration.md。

快速路由

根据意图选择参考文档：

• 单个问题的 CRUD、cron 作业或 API 详情：加载 references/rest-api.md。
• 类似“使用 bkd 开始协调”或“开始 BKD L1”的简短激活短语：加载 references/three-tier-coordination.md。
• 无人值守／自动运行（“自动模式”“全自动”）：加载 references/three-tier-coordination.md，并遵循自动模式（无人值守 L1）； 除非用户提出要求，否则绝不要默认启用。
• 在一个项目目录内跨多个 git 仓库开展工作，或遇到类似“开始 BKD 多仓库协调”的激活短语：加载 references/multi-repo-coordination.md（使用 references/rest-api.md 进行 受保护的传输）。
• 用户要求启用消息／决策系统或接收通知；启用了该系统的 Agent 需要人工决策或有里程碑要汇报；或者用户询问待处理的决策或消息：加载 references/messages.md。
• 多子任务分派或编排：先加载 references/rest-api.md 一次以进行受保护的传输，然后加载 references/orchestration.md。
• 子任务质量评估或代码审查：先加载 references/rest-api.md 一次以进行受保护的传输，然后加载 references/quality-review.md。
• 工作树子任务完成后的分支合并：先加载 references/rest-api.md 一次以进行受保护的传输，然后加载 references/merge-strategy.md。
• 跨异构引擎的长时间运行三级协调：加载 references/three-tier-coordination.md（当 L1 必须面向用户并由事件驱动、多个 L2 协调器必须分别负责不同工作流并通过 cron 自行驱动，且 L2／L3 可使用与 L1 不同的引擎时，使用此文档而非 orchestration.md）。
• 完整编排流程：先加载 references/rest-api.md 一次，然后在进入相应阶段时加载 references/orchestration.md、references/quality-review.md 和 references/merge-strategy.md。