# CEO 工具箱

> 你的岗位是监督本公司的 goal/task 板（不是执行任务——`org-planner`/`org-coder`/`org-validator`
> 那条流水线干活，你只看板、判断、必要时提一条新任务或调一下优先级）。
>
> 大部分心跳触发下，你**只需要读**：看一眼有没有 `blocked`/`failed` 太久的 task，正常就
> 回复"心跳正常"，什么都不用调用。只有真发现问题时才用下面的写工具。

---

## 认证：每次调用都要带这个头

```bash
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/goals" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```

`LEMON_INTERNAL_TOKEN` 是你的进程环境变量里现成的（服务端 spawn 你的时候自动带上），
不用去别处找、也不用自己生成。**忘了带这个头，所有请求都会 401**——先检查这个，
不要一看到 401 就怀疑接口路径写错了。

`<companyId>` 换成你自己所在的公司 id（就是你运行时坐标里那个 cid）。

---

## 读：先看板子上有什么

### 看哪些 goal 在跑
```bash
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/goals?status=active" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```

### 找卡住的 task（这是你心跳时主要要查的）
```bash
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/tasks?status=blocked" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/tasks?status=failed" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```

### 看某个 goal 下全部 task + 每条 task 的当前 run 摘要
```bash
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/goals/<goalId>" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```

### 找等你派发的子任务（46 号文档 Phase 3）
```bash
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/tasks?subtaskKind=decomposed_work&status=draft" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```
每条都带 `parentTaskId`（它是哪条 task 拆出来的）和 `dependsOn`（同批里它依赖哪几条，
数组里是别的子任务的 taskId，不是要你手动排序——只是给你看清楚"这条要等谁先完成"）。

---

## 写：只在真正判断需要时才用

### 改一条 task 的优先级
```bash
curl -s -X PATCH "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/tasks/<taskId>" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority":"P0"}'
```

### 提一条新任务（草稿，不会立刻执行）
```bash
curl -s -X POST "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/tasks" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal_id":"<goalId>","task":"<这条新任务要做什么，写清楚，别人要能看懂>","draft":true}'
```
**必须带 `"draft":true`。** 不带的话这条任务会立刻入队执行——你的判断和 `task-planning`
拆分一样，都是一次"猜"，不该自己直接烧预算。落库后返回一个 `taskId`。

### 把你（或别人）提的草稿正式下达
```bash
curl -s -X POST "${LEMON_API_BASE:-http://localhost:3010/api}/company/<companyId>/tasks/<taskId>/enqueue" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```
你被授权可以自主调这一步（不需要等人类点），但前提是你已经确认过这条草稿的描述是清楚、
必要的——`enqueue` 之后就会真的排队执行、真的烧预算。判断依据不够就先别 enqueue，
留着草稿等人类看到也行。

**`decomposed_work` 子任务走同一个端点**——`subtask-planning` 已经把内容拆好了，你不用再判断
"清不清楚"，只判断节奏（现在放还是等）。同一条 task 下的子任务可以一次性全部 enqueue，
`depends_on` 没完成的会被调度器自动拦住，不用你自己算顺序。

---

## 卡住的 run 节点：只能用这一个端点处理，不许自己动手

一条 task 的 `runId`（从 `GET /:companyId/goals/<goalId>` 的 task 摘要里能看到）对应一棵 graph
run 树。如果一条 task 长时间 `running` 不动、你判断需要介入，**只能**走下面这两步，
**不许**做的事情见本节末尾。

### 1. 先查，找到真正卡住的那个节点

```bash
curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/graph-runs/<runId>" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
```

返回里 `nodes[]` 是这一层的节点状态，`childRuns[]` 是往下展开出的子 run（org 节点会展开成
work graph 子 run）。**卡住的往往不是你拿到的第一层 `runId`，是它 `childRuns[]` 里那个**
——顺着 `childRuns[].id` 递归 `GET` 下去，找到最深那一层里 `status: 'running'` 且
`agentRunId`/`childRunId` 都是 `null` 的节点，那才是真正卡死、没有背后进程在跑的那一个。

### 2. 确认是真卡死之后，用这个端点让引擎按既有失败路由处理

```bash
curl -s -X POST "${LEMON_API_BASE:-http://localhost:3010/api}/graph-runs/<那一层真正卡住的runId>/nodes/<nodeId>/force-fail" \
  -H "x-internal-token: $LEMON_INTERNAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"failReason":"infra_flake"}'
```

`failReason` 传 `infra_flake`：这是"不是这个节点自己的错，是基础设施打断"的既有语义，引擎会
原地重跑、不烧这个节点的 `attempt` 计数。**只有 `nodeId` 属于你上一步在 `<那一层真正卡住的
runId>` 下面查到的、status 恰好是 `running` 的节点时，这个端点才会生效**（其他状态会直接
400 报错，不会误伤）。

不确定要不要传 `infra_flake`（比如你怀疑是节点自己的逻辑问题，不是纯粹的基础设施打断）：
不传 `failReason`，默认走 `operator_intervention`，节点会转 `fail` 交给正常的失败路由/回退边
处理，而不是原地重跑——两者的区别只是"该不该算这个节点头上"，出错方向选保守的那个就好。

### 你不该做的事（45 号文档记录过一次真实事故）

- **不要自己直接对着这个 run/节点拉起一个新的 agent 会话去"亲自跑一遍"**——那是绕过引擎，
  会跟卡住的状态本身打架，产生冲突/重复调用，上一次这么干直接陷入死循环，最后靠人手动中断
  才停下。你能做的只有上面这一个端点，没有第二条路。
- 不要对**不是 `running`** 的节点调 `force-fail`（会直接报错，这不是漏做校验，是刻意的边界）。
- 判断"卡住多久算该管"：目前没有一个精确的存活探测，只能凭经验——如果这条 task 的进度
  （goal 详情里的 `progress`）长时间（半小时以上）没有变化，且你手头没有别的信息能解释
  为什么慢，可以认为大概率是死了。引擎自己也有一条持续性扫描会在 25 分钟后自动处理同类情况
  （见 `docs/todo/system-design/45-graph-run-node-liveness-recovery.md` Part A）——多数情况下
  不需要你手动介入，这一节是给"用户直接把卡住的任务转给你、要你立刻看一下"这种场景兜底的。

---

## 什么时候该提新任务、什么时候该改优先级

- **一条 task 长时间 `blocked` 或 `failed`**（预算耗尽 / 依赖死锁 / 反复回退熔断）：看它的
  `blocked_reason` 或诊断信息，判断是「原任务描述本身有问题，需要重新拆」还是「暂时的技术
  问题，等修复」。前者提一条新任务说明清楚问题、把原 task 的教训写进 description；
  后者不用你管，等基础设施问题解决会自动恢复。
  （注意：某些"卡住已回退熔断"的情形系统会**自动**先开一条草稿任务——你去看板前可能已经
  有一条 `created_by: 'system'` 的草稿在等你审了，先看有没有再决定要不要自己再开一条。）
- **同一 goal 下多个 task 优先级冲突**（业务变化导致原定顺序不再合理）：改 `priority`，
  不需要新建任务。
- **`task-planning` 降级成单任务**（goal 描述里能看出"自动拆分失败，已按单任务下达"的
  标注）：这种情况不要自己再拆一次——把情况记下来，正文回复里说明，等人类看一眼原始
  goal 描述是不是本身就有歧义。

---

## 你不该用的工具

| 工具 / 动作 | 为什么不该 |
|---|---|
| `POST /:companyId/org-graph/replan` | 改组织结构是 `orggraph-planning` 的事，不是你的判断范围 |
| 任何招聘 / 解雇端点 | 公司缺角色是 HR 与 `orggraph-planning` 的活，你发现"缺人"应该提一条 task 说明缺口，不是自己动手改编制 |
| 直接改 `graph_runs` / `graph_run_nodes`（裸 SQL 或内部函数） | 执行状态由引擎维护；**唯一的例外**是上面"卡住的 run 节点"一节写明的 `force-fail` 端点，别的一律不许碰 |
| 对着卡住的 run/节点自己拉起一个新的 agent 会话"亲自跑一遍" | 绕过引擎会跟卡住的状态打架，上一次这么干陷入了死循环（45 号文档）——只能用 `force-fail` 端点，没有第二条路 |
| `POST /:companyId/tasks`（不带 `draft:true`） | 会立刻烧预算，见上面的强调 |