@metagptx/deepflow-suite-cli 0.0.0-stage → 0.1.1

package/bundle/skills/df-agentrt/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: df-agentrt
+description: 在 DeepFlow Agent Runtime 里执行任务时使用。说明你所处的运行环境、产出物怎么交付、工作目录的生命周期，以及 df-agentrt 的命令。
+---
+
+# DeepFlow Agent Runtime
+
+你运行在 **DeepFlow Agent Runtime** 上。这是一个把「会话 + 多轮消息 + 代码仓库」
+管起来的服务，你现在执行的是其中一轮。
+
+## 先读这条：任务简报里的命令清单大半是假的
+
+执行引擎是 multica 的 daemon，它拼简报时**默认自己是完整的 multica 产品**——
+issue、chat channel、squad、附件、workspace、project，简报里会提到这些。
+**这里一个都没有。**
+
+简报里那份 `multica` 命令手册，只有一条在本环境真实可用：
+
+```bash
+multica repo checkout <URL>
+```
+
+其余的 `multica` 子命令敲下去都会被明确拒绝，stderr 上会告诉你这里没有这个东西、
+以及改做什么。那些拒绝信息是给你看的，照着做就行，**不要换个写法重试**。
+
+你自己的能力在 `df-agentrt` 上，已经在 PATH 里，不需要定位路径。
+
+## 目标环境门禁与地址
+
+涉及直接调用 Agent Runtime 服务（例如使用 `agentrt` CLI）时，必须先确认用户要操作的目标环境。用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
+
+| 目标环境 | 本地执行时的地址 | 在 dev-k8s 内执行时的地址 |
+| --- | --- | --- |
+| `local` | `http://127.0.0.1:8141` | 不适用 |
+| `dev` | `https://deepflowagentruntime.dev.deepwisdomai.com` | `http://deepflowagentruntime.deepflow.svc.cluster.local:8141` |
+| `prod` | 尚未配置 | 尚未配置 |
+
+地址列描述的是同一目标环境的两种访问方式：本地 CLI 使用 dev Ingress，集群内 Agent 使用 dev Service DNS。确认环境后，用 `AGENTRT_ADDR` 指向该环境的地址；用户明确提供的地址只能覆盖已确认环境的默认地址，若与环境冲突则先停止并澄清。`prod` 目前没有地址，任何 prod 操作都必须停止并说明尚未接入。
+
+本地操作 dev 时示例：
+
+```bash
+AGENTRT_ADDR=https://deepflowagentruntime.dev.deepwisdomai.com agentrt session ls
+```
+
+先请求选定地址的 `GET /healthz`，确认 runtime 可用后再执行操作。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
+
+`df-agentrt` 的 `session`、`repo`、`events` 等命令操作的是当前 Runtime 会话控制面，不接受 `AGENTRT_ADDR`；不要把当前会话与另一个环境的 Runtime 混用。需要明确操作某个环境的 Runtime 服务时，使用 `agentrt` 并设置对应的 `AGENTRT_ADDR`。
+
+## 消息流是交付物本身
+
+这个会话的消息流**永久可见**，release 之后也仍然完整可读，而且是被人一行一行读的。
+
+所以：**你的输出就是产物。** 不要只说"我改好了"、"详见文件"——把结论、关键改动、
+你判断的依据写进回复。读的人多半不会去翻你的工作目录，很多时候他也翻不了
+（见下面「工作目录会被回收」）。
+
+## 没有附件通道
+
+任务简报每一轮末尾都会告诉你：要在回复里带文件就跑 `multica attachment upload`。
+**那条指令在这里是错的**，本环境没有附件通道，那个命令会失败。
+
+需要交付文件内容时，用文字描述，或者把关键片段直接贴进回复。**不要**写成本地路径链接，
+也不要写得像文件已经送到了——读的人会去找一个根本不存在的附件。
+
+## 工作目录：跨轮复用，检出是同级目录
+
+- 同一个会话的多轮**复用同一个工作目录**，上一轮留下的文件这一轮还在。
+- `repo add` / `repo checkout` 检出的仓库，落在**你当前工作目录的同级**，不在里面。
+- 目录名取自 URL 的最后一段，**不一定等于应用名**。不要猜，用命令打印出来的绝对路径。
+
+## release 之后工作目录会被回收
+
+会话 release 之后：消息流仍然可读，**工作目录会被删掉**。
+
+所以**不要把唯一的产出留在磁盘上**。重要的结论、生成的内容、分析结果，都要进消息流。
+磁盘是工作区，不是交付区。
+
+## 取消是协作式的
+
+被取消时你不会被当场杀掉：状态先变成 `cancelled`，你会收到停止的请求，
+然后有时间收尾。收到取消请求就**尽快收尾并把已有的结论说出来**，
+不要假装无事发生继续跑，也不要因为被取消就什么都不留下。
+
+---
+
+## 命令总览
+
+```
+本会话（不需要会话 id，它自己知道是哪个）
+  df-agentrt session info            你是谁：provider、model、工作目录、仓库，
+                                     以及上一轮的对话历史有没有续上
+  df-agentrt session turns           这个会话到目前为止的每一轮
+  df-agentrt events [--after N]      消息流，一行一条
+  df-agentrt repo list               本会话可以检出哪些仓库
+  df-agentrt repo search <应用名>     按应用名找仓库
+  df-agentrt repo add <url|应用代码>  加一个仓库进来并当场检出
+  df-agentrt msg cancel              请求停掉当前这一轮
+
+别的会话（必须显式给会话 id）
+  df-agentrt session ls              这个 runtime 上的会话
+  df-agentrt session get <会话id>     某个会话的完整信息
+  df-agentrt session create ...      新建会话 💰
+  df-agentrt msg send <会话id> <文本>  给别的会话排一轮 💰
+
+运行时
+  df-agentrt ops runtimes            执行引擎注册了哪些、还活着哪些
+  df-agentrt ops orphans             记录和现实哪里对不上（只读）
+```
+
+## 业务 metadata 与软范围查询
+
+Runtime Session 可以携带业务方自定义的 JSON metadata。基础服务只约定顶层的 source、
+query_keys 和 data：前两个用于可选的软范围查询，data 由业务方自行组织。
+
+需要由 CLI 创建 Session 时，把完整对象传给 session create：
+
+    df-agentrt session create \
+      --provider claude \
+      --metadata '{"source":"workbench","query_keys":["account:u123"],"data":{"project":"orders"}}'
+
+查询已有 Session 时可按同一范围过滤：
+
+    df-agentrt session ls \
+      --metadata-source workbench \
+      --metadata-query-key account:u123
+    df-agentrt session get <session-id> \
+      --metadata-source workbench \
+      --metadata-query-key account:u123
+
+query_keys 可以包含多个标识；"*" 表示显式共享，匹配任意来源和查询标识；不提供过滤
+参数仍保持历史上的全量行为。metadata 是查询范围，不是权限控制。标准 Task 流程中，
+deepflow-task-driver 会把 Task metadata 原样透传到它创建的 Session，Agent 不需要重新拼接；
+Runtime 也不会从登录身份或当前会话自动推断业务范围。
+
+当前 session info、session get 和 session ls 的人类可读输出不会打印 metadata 原文，
+不要把输出中没有 metadata 理解成 Session 没有 metadata。需要核对原值时读取 Runtime API 的
+JSON 响应；CLI 过滤仍然可以正常使用。
+
+💰 这两条会**真的跑起来一个 agent**，花的是真钱。而且新建的会话**不会自己结束**——
+它会一直占着一个工作目录，直到有人显式 release 它。确认你真的需要另一个会话再用，
+多数时候你要的只是自己把活干完。
+
+创建结果不确定时，用稳定 key 重试同一次创建：
+
+```bash
+df-agentrt session create --provider claude --idempotency-key cli:ticket-42
+df-agentrt session create --provider claude --idempotency-key cli:ticket-42
+```
+
+两次会返回同一个 id。新的创建意图必须换 key，不要在每次重试前重新生成。key 在当前 runtime
+数据库内全局有效、区分大小写，非空时最多 256 字节且只能是无空白、无逗号的可见 ASCII；不传
+key 时每次新建。同 key 只保留首次成功写入的配置，released 状态也会原样返回；物理删除 Session
+后该 key 的保留随之终止。
+
+`session info` 值得一开始就跑：它会告诉你**上一轮的对话历史有没有续上**。
+没续上的话，文件都在，但你读不到之前说过什么——这时候先看 `session turns` 和
+`events`，别凭空假设自己记得。
+
+`ops runtimes` 是「某一轮卡住不动」时第一个该问的问题：一个正在思考的 daemon，
+和一个一小时前就被杀掉的 daemon，从会话那边看起来一模一样。
+
+### 有三件事不归你做
+
+`session release`、`session rm`、`ops orphans --fix` **不要用**。它们都是替别人做决定：
+回收工作目录由控制面决定，删会话会抹掉永久可见的消息流，判死滞留轮次动的是别的会话。
+二进制不会拦你——它会照做，所以这条只能靠你守住。
+
+发现某个会话像是卡住了、或者某个工作目录该回收了，**在回复里说出来**，
+让读的人去处理。这比你直接动手有用——你只看得到这一轮，他看得到全局。
+
+### 退出码
+
+| 码 | 含义 | 该怎么办 |
+|---|---|---|
+| 0 | 成功 | —— |
+| 1 | 请求发出去了，但失败了 | 看 stderr，它写清了原因 |
+| 2 | 命令行写错了，一个请求都没发 | 改命令 |
+| 3 | 环境/部署不对 | **不是你的错，重试没用**，在回复里说明 |
+
+## 添加代码仓库
+
+`repo list` / `search` / `add` 的详细用法、`--ref` 的限制、以及三个容易做错的地方，
+见 `df-agentrt-repo` skill。一句话版本：**不要自己拼 `multica repo checkout` 去检出刚加的
+仓库**，daemon 的白名单按 URL 逐字符匹配，你手敲的那个字符串未必是服务端存下来的那个。

package/bundle/skills/df-agentrt-repo/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: df-agentrt-repo
+description: 任务进行中发现需要另一个代码仓库时使用。查看本会话已有的仓库、按应用名搜索仓库、把新仓库加进来并当场检出。
+---
+
+# 中途添加代码仓库
+
+会话创建时定下的配置里，只有**代码仓库**这一项是可以在任务进行中追加的。
+
+你可能在分析到一半时才发现答案不在手上这几个仓库里——这时不需要中断任务回报、
+等人重建会话，用 `df-agentrt` 自己把仓库加进来，一个回合内就能继续。
+
+`df-agentrt` 已经在 PATH 上，不需要定位路径。
+
+## 已经有哪些仓库
+
+```bash
+df-agentrt repo list
+```
+
+每行一个仓库：URL、`@分支`（如果固定了分支）、括号里是说明。
+**先跑这个**——需要的仓库很可能已经在列表里，那就只差一个检出：
+
+```bash
+multica repo checkout <上面列出的 URL>
+```
+
+## 找仓库
+
+知道应用叫什么、不知道代码在哪：
+
+```bash
+df-agentrt repo search 结算服务
+```
+
+输出三列，用 Tab 分隔：**应用代码**、应用名、仓库地址。第一列是下一步要用的参数。
+
+搜不到不是失败。换一个更短的词再试，或者你要是本来就知道 clone 地址，跳过这步。
+
+## 加进来
+
+```bash
+df-agentrt repo add <应用代码或 clone 地址> [...]
+```
+
+参数里带 `://` 或 `@` 的当作 clone 地址，其余当作应用代码去查。两种可以混在一条命令里。
+
+要固定分支：
+
+```bash
+df-agentrt repo add https://git.example.com/g/settle --ref release/2026-09
+```
+
+`--ref` 一次只能配一个 clone 地址。多个仓库共用一个分支名几乎都是写错了，
+真要这么做就分成几条命令。
+
+**这条命令会把仓库检出，不需要再跑别的。** stdout 上每行是一个检出目录的绝对路径，
+直接拿去读文件。
+
+## 三件容易做错的事
+
+**不要自己拼 `multica repo checkout` 去检出刚加的仓库。** daemon 的白名单按 URL
+**逐字符**匹配，你手敲的地址少一个 `.git`、多一个尾斜杠，就是另一个仓库，
+会得到「repo is not configured」——而 `repo list` 里明明有它。`repo add` 用的是服务端存下来的
+那个字符串，所以它检出得了，你重新敲一遍的不一定。
+
+**仓库只能加不能删。** 当前回合可能正在某个仓库里工作，删掉就把这个回合弄坏了。
+
+**重复添加是安全的。** 已经有了就不会重复加，但仍然会做一次检出——
+「在列表里」和「在磁盘上」是两回事。
+
+## 命令失败了怎么办
+
+stderr 上的话是给你看的，照着做：
+
+- 说「retrying will not help」——环境问题，不是参数问题，别换个写法再试，直接在回复里说明；
+- 说「remain configured」——仓库加上了，只是检出没成功，可以用 `multica repo checkout <URL>` 重试；
+- 其余的错误信息来自服务端，已经写清楚了原因和下一步。
+
+## 加完之后
+
+检出目录和你当前的工作目录是同级的。用 `repo add` 打印出来的绝对路径访问，
+不要猜目录名——仓库目录名来自 URL 最后一段，不一定等于应用名。

package/bundle/skills/df-task/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: df-task
+description: 在一次 Run 里用 df-task 读写 DeepFlow Task 事实日志 —— 读本 Task 的历史事实、发布产物引用、写关键摘要、求助、主张本 Run 目标达成或无法完成；调度智能体另外用它写唤起意图、等待依据、交给人、裁决与 Run 终止。本 Skill 不负责启动或停止 Run（那是 df-agentrt 与推进器的事），不负责智能体定义（那在 deepflow-agent-ctrl），也不提供任何修改或删除事实的手段。
+---
+
+# df-task
+
+`df-task` 是 DeepFlow Task 事实日志的命令行入口。Task 是一件工作的身份，它下面挂着一本**只追加**的事实日志：谁在什么时候写下了什么。**没有状态字段，也没有状态机** —— 「这件工作到哪一步了」是从这本日志里读出来的，不是查出来的。
+
+服务地址取自 `DF_TASK_BASE_URL`，默认 `http://127.0.0.1:8090`。写事实的身份取自 `DF_TASK_ACTOR_KIND` 与 `DF_TASK_ACTOR_ID`，由 runtime 在起进程时注入 —— **不要自己改这两个环境变量**，身份决定了你能写哪些事实。
+
+## 任务描述
+
+每轮工作先用 `df-task get "$DF_TASK_ID" --json` 读取 `description` 与 `description_version`。标题是简短名称，描述是当前需求，首条消息仅是历史事实；不能用首条消息替代描述。汇报前再次核对版本，若描述变化需重新核对范围与验收条件。
+
+## 目标环境门禁与地址
+
+每次调用服务前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
+
+| 目标环境 | 本地执行时的地址 | 在 dev-k8s 内执行时的地址 |
+| --- | --- | --- |
+| `local` | `http://127.0.0.1:8090` | 不适用 |
+| `dev` | `https://deepflowtask.dev.deepwisdomai.com` | `http://deepflowtask.deepflow.svc.cluster.local:8090` |
+| `prod` | 尚未配置 | 尚未配置 |
+
+地址列描述的是同一目标环境的两种访问方式：本地 CLI 使用 dev Ingress，集群内 Agent 使用 dev Service DNS。确认环境后，可以用用户明确提供的 `--base-url` 覆盖该环境的默认地址，但该地址必须属于已选环境；如果地址与环境冲突，先停止并澄清，不能用它绕过环境门禁。`prod` 目前没有地址，任何 prod 操作都必须停止并说明尚未接入。
+
+本地操作 dev 时示例：
+
+```bash
+df-task --base-url https://deepflowtask.dev.deepwisdomai.com facts "$DF_TASK_ID" --json
+```
+
+### Run 内的目标环境
+
+`DF_TASK_ID`、`DF_RUN_ID`、`DF_TASK_ACTOR_KIND` 都非空时，你运行在推进器拉起的 Run 里，没有用户可以询问。此时目标环境由部署决定：用注入的 `DF_TASK_BASE_URL` 对照上表反查所属环境，例如 `http://deepflowtask.deepflow.svc.cluster.local:8090` 即 `dev`。每一轮、每个 Run 都按同一规则确定，不需要也不应该等待任何人确认。
+
+反查不到任何环境、地址属于 `prod`，或指令要求操作的环境与反查结果不一致时，停止，不调用服务、不改用其他地址，在最终回复里说明注入地址和冲突原因。推进器会照常记录本次执行结束，交给下一轮调度或人处理。
+
+不在 Run 里时，只有在用户明确选择 `dev` 且 `DF_TASK_BASE_URL` 确认属于 dev 时，才可以复用它；用户选择 `local` 时必须忽略该值并使用 `http://127.0.0.1:8090`。用户没有先选环境都不能执行请求。
+
+先用 `GET /healthz` 验证选定地址，再执行读写操作。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
+
+下面的示例还用到两个变量，同样由 runtime 注入，同样不要自己编：`DF_TASK_ID` 是你这次执行所属的 Task，`DF_RUN_ID` 是你自己这个 Run 的标识（写事实时 payload 里的 `run_id` 填它）。如果它们是空的，说明这次执行不是由推进器兑现唤起起来的 —— 别猜一个填进去，写一条 `summary` 说明情况。
+
+**在 Run 里一律加 `--json`。** 不加 `--json` 的输出是给人看的排版，字段随时会调整。
+
+```bash
+# 读本 Task 的全部事实
+df-task facts "$DF_TASK_ID" --json
+
+# 只读某几类，或从某个序号往后读
+df-task facts "$DF_TASK_ID" --types user_message,artifact_published --json
+df-task facts "$DF_TASK_ID" --after 128 --json
+
+# 追加一条事实：payload 写成 JSON 文件再传
+# 注意 heredoc 的标记不加引号，加了引号 $DF_RUN_ID 就不会展开
+cat > /tmp/artifact.json <<JSON
+{"run_id":"$DF_RUN_ID","kind":"diff","ref":"abc1234def5678","title":"登录按钮溢出修复"}
+JSON
+df-task append "$DF_TASK_ID" --type artifact_published --file /tmp/artifact.json --json
+```
+
+## 业务 metadata 与软范围查询
+
+Task 可以携带业务方自定义的 JSON metadata。基础服务只约定顶层的
+`source`、`query_keys` 和 `data`：前两个用于可选的软范围查询，`data` 完全由业务方组织。
+例如：
+
+```bash
+df-task create \
+  --title '订单分析' \
+  --metadata '{"source":"workbench","query_keys":["account:u123"],"data":{"project":"orders"}}' \
+  --json
+```
+
+`--metadata` 必须是 JSON 对象；没有 metadata 时服务保存 `{}`，不会改变原有流程。创建、
+列表和单Task读取会返回 metadata。事实读取也支持同一范围过滤：
+
+```bash
+SCOPE_SOURCE=workbench
+SCOPE_KEY=account:u123
+
+df-task ls \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+df-task get "$DF_TASK_ID" \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+df-task facts "$DF_TASK_ID" \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+df-task stream \
+  --metadata-source "$SCOPE_SOURCE" \
+  --metadata-query-key "$SCOPE_KEY" \
+  --json
+```
+
+查询规则：
+
+- 同时提供 `source` 和 `query_key` 时，Task 必须匹配来源和查询标识；只提供其中一个时只按该条件过滤。`query_keys` 包含 `"*"` 的显式共享Task例外于这两个条件。
+- `query_keys` 可以包含多个标识；`"*"` 表示显式共享，匹配任意查询范围。
+- 不提供过滤参数仍然是历史上的全量查询。业务上下文存在时才携带过滤参数，不要把它当成权限边界。
+- 先从Task响应的 metadata 读取 `source` 和 `query_keys`，再把当前业务上下文中的具体 key 传给后续查询；不要从 `data` 中猜测过滤字段。
+
+metadata 只影响读请求的范围。`append`、`dispatch`、`wait`、`handoff` 和 `title` 仍按明确的
+Task ID 操作，不支持 metadata 过滤参数；事实服务不会根据 metadata 做鉴权。
+
+命令不存在时，本项目源码可用的话在 `deepflow-task/` 下运行 `make install-cli`，它把 `df-task` 装到 `$HOME/.local/bin`。**注意不要把 runtime 的地址填成 Task 服务的地址** —— `df-agentrt` 和 `df-task` 是两个服务、两个端口、两套授权。
+
+## 读日志
+
+1. 先 `df-task facts "$DF_TASK_ID" --json` 通读一遍，搞清这件工作已经发生过什么
+2. 关心产物就加 `--types artifact_published`；关心人说了什么就加 `--types user_message`
+3. 产物事实里存的是**引用坐标，不是内容**。要看 diff、spec、MR 的正文，拿着 `ref` 自己去外部系统取
+4. 要分页往后读就用上一页返回的 `next_after_seq` 当下一次的 `--after`
+
+序号有空洞，且落库顺序不保证与序号顺序一致。一次读不完就接着读，不要假设「序号连续就是读全了」。
+
+## 任务 Run 可以写什么
+
+| 命令 | 落成哪条事实 | 什么时候写 |
+| --- | --- | --- |
+| `df-task append <task-id> --type artifact_published --file p.json` | `artifact_published` | 产出了别人要用的东西：diff、spec、测试结果、MR。只写引用坐标 |
+| `df-task append <task-id> --type summary --file p.json` | `summary` | 有一个结论值得留给下一个 Run，或想说明「还需要做 X」 |
+| `df-task append <task-id> --type help_requested --file p.json` | `help_requested` | 卡住了，需要人或调度智能体给一个答案 |
+| `df-task append <task-id> --type run_outcome --file p.json` | `run_outcome` | 本 Run 目标达成或无法完成，附结论与理由 |
+
+四条都**不会触发下一轮调度**。真正触发下一轮的是「唤起结束」，它由推进器在观察到本次执行终态后写下 —— 所以你正常结束、异常崩溃，下一轮调度都照样会起来。
+
+**`run_outcome` 只是你的主张，不是这件工作的结论。** 调度智能体完全可以不采信并要求返工。
+
+**想派生一条支线，就在 `summary` 里写清「还需要做 X」**，下一轮调度会看到。不要试图自己开 Run。
+
+## 调度 Run 可以写什么
+
+| 命令 | 落成哪条事实 | 什么时候写 |
+| --- | --- | --- |
+| `df-task dispatch <task-id> --agent <name> --instruction <text>` | `dispatch_intent`（`mode` 为 `new_run`） | 把一块工作派给某个智能体，开一个新 Run |
+| `df-task dispatch <task-id> --agent <name> --instruction <text> --run <run-id>` | `dispatch_intent`（`mode` 为 `message`） | 往一个还活着的 Run 投一条消息 |
+| `df-task wait <task-id> --on <what> --reason <text>` | `waiting_reason` | 该派的都派了，在等人回话或等一条外部结果 |
+| `df-task handoff <task-id> --ask <text>` | `handoff_to_human` | 把球交给人。既用于「都做完了请验收」，也用于「这一步我做不了请你做」 |
+| `df-task append <task-id> --type adjudication --file p.json` | `adjudication` | 对某条事实下裁决，`subject` 是那条事实的序号 |
+| `df-task append <task-id> --type run_terminated --file p.json` | `run_terminated` | **已经用 `df-agentrt` 停完 Run 之后**，记录这个既成事实 |
+
+前四行是语法糖，落库的事实类型见中间那一列 —— 读日志时你看到的是 `dispatch_intent`，不是 `dispatch`。各列字段清单见 `references/fact-types.md`。
+
+**每一轮至少写一条。** 一轮调度什么都不写，这个 Task 就会静默停住 —— 那是最坏的失效模式。无事可做不是理由：无事可做就写 `wait` 或 `handoff`。
+
+`dispatch` 写完不等于 Run 起来了。**你写完就该结束**，真正拉起进程的是推进器。
+
+停 Run 要先用 `df-agentrt` 停并确认停住了，再写 `run_terminated` 记录。顺序反了就会留下一条假事实。
+
+## 职责边界
+
+- **本 Skill 不启动、不停止任何 Run。** 起 Run 由推进器兑现唤起意图，停 Run 用 `df-agentrt`
+- **没有修改和删除事实的命令**，因为 API 里就没有。写错了就再写一条把它说清楚
+- **不要在 payload 里塞产物正文。** 日志是路牌不是档案馆，只放引用坐标
+- **不查智能体正在干什么。** 那是 runtime 侧的 transcript，用 `df-agentrt` 看
+- **越权会拿到 `403` 且什么都不落库。** 拿到 `403` 说明这条事实不该由你写，不要换个类型重试，写一条 `summary` 或 `help_requested` 说明情况
+
+## 输出与错误
+
+`--json` 下 stdout 是服务端原样返回的 JSON。退出码只有三个：`0` 成功、`1` 网络或服务端失败、`2` 本地参数无效。**参数错误不会发出任何请求**，所以拿到 `2` 时日志里一定没有任何痕迹。
+
+追加成功返回那条事实，含它的 `seq`。`--idempotency-key` 重复提交同一个键时返回**已存在的那条事实**，HTTP 状态是 `200` 而不是 `201` —— 这不是错误，重试是安全的。
+
+各类事实的字段清单见 `references/fact-types.md`，可直接抄改的 payload 样例在 `assets/payload-examples/`。

package/bundle/skills/df-task/assets/payload-examples/adjudication.json

@@ -0,0 +1,5 @@
+{
+  "subject": 1042,
+  "verdict": "accepted",
+  "reason": "diff 与测试结果都在，spec 的验收点对得上，采信这条主张。"
+}

package/bundle/skills/df-task/assets/payload-examples/artifact_published.json

@@ -0,0 +1,6 @@
+{
+  "run_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
+  "kind": "diff",
+  "ref": "abc1234def5678",
+  "title": "登录按钮在 Safari 17 上溢出的修复"
+}

package/bundle/skills/df-task/assets/payload-examples/help_requested.json

@@ -0,0 +1,5 @@
+{
+  "run_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
+  "question": "spec 没写清弹窗在窄屏下是居中还是贴底，按哪个做？",
+  "blocking": true
+}

package/bundle/skills/df-task/assets/payload-examples/run_outcome.json

@@ -0,0 +1,5 @@
+{
+  "run_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
+  "result": "reached",
+  "reason": "diff 与测试结果已发布，spec 里的三条验收点逐条对过。"
+}

package/bundle/skills/df-task/assets/payload-examples/run_terminated.json

@@ -0,0 +1,4 @@
+{
+  "run_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
+  "confirmed_status": "stopped"
+}

package/bundle/skills/df-task/assets/payload-examples/summary.json

@@ -0,0 +1,4 @@
+{
+  "run_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
+  "text": "按 spec 改完了溢出问题，单测已过。还需要做：移动端断点下的同类问题没查，建议单独派一轮。"
+}

package/bundle/skills/df-task/references/fact-types.md

@@ -0,0 +1,48 @@
+# 事实类型与 payload 字段
+
+一共十六种事实。**类型决定语义，身份决定谁能写它。** 服务端只做浅校验：必填字段在不在、枚举值对不对，不校验内容是否合理。
+
+## 外部输入（人与外部系统写，**触发下一轮调度**）
+
+| 类型 | 谁写 | 必填 | 可选 |
+| --- | --- | --- | --- |
+| `user_message` | 人 | `text` | —— |
+| `external_result` | 外部系统 | `source`、`ref`、`result` | —— |
+
+对求助的回答、对产物的意见、对裁决的确认，全都是 `user_message`，没有专门的类型。
+
+## 人工任务管理（不触发调度）
+
+`task_lifecycle` 仅 human 可写，必填 `action`：`complete`、`archive`、`delete`、`reopen`。删除是移入回收站，事实记录保留。此记录不取消执行。
+
+## 任务 Run 写的（都**不触发**下一轮调度）
+
+| 类型 | 必填 | 可选 | 说明 |
+| --- | --- | --- | --- |
+| `artifact_published` | `run_id`、`kind`、`ref` | `title` | `ref` 是外部可验证的引用坐标（commit SHA、MR 地址…）。`kind` 决定界面怎么渲染、别的智能体怎么解读。`title` 只给人看 |
+| `summary` | `run_id`、`text` | —— | 留给下一个 Run 的结论。想派生支线就写在这里 |
+| `help_requested` | `run_id`、`question`、`blocking` | —— | `blocking` 是布尔值：不给答案就没法继续吗 |
+| `run_outcome` | `run_id`、`result` | `reason` | `result` 只能是 `reached` 或 `unreachable`。**只是主张，不是 Run 终止** |
+
+## 调度 Run 写的（都**不触发**下一轮调度）
+
+| 类型 | 必填 | 可选 | 说明 |
+| --- | --- | --- | --- |
+| `dispatch_intent` | `target_run_id`、`agent`、`instruction`、`mode` | —— | `mode` 是 `new_run` 或 `message`。用 `df-task dispatch` 更省事，它会替你填这四个字段 |
+| `waiting_reason` | `waiting_on`、`reason` | —— | 给人和给下一轮调度的上下文，**不是推进器的门** |
+| `handoff_to_human` | `ask` | `assignee` | 交球和派活是同一条事实，区别只在 `ask` 的内容 |
+| `adjudication` | `subject`、`verdict` | `reason` | `subject` 是被裁决那条事实的**序号**（数字，不是字符串） |
+| `run_terminated` | `run_id`、`confirmed_status` | —— | 已经停完并确认之后记录的既成事实 |
+
+## 推进器写的（智能体写会拿 `403`）
+
+唤起生命周期是整套设计里唯一不依赖智能体配合的推进信号，所以**只有推进器能写**。列在这里是为了让你读日志时认得它们。
+
+| 类型 | 必填 | 可选 | 含义 |
+| --- | --- | --- | --- |
+| `invocation_started` | `run_id`、`run_kind` | `intent_seq`、`input_watermark` | 推进器决定去启动，此时还没调用 runtime |
+| `invocation_accepted` | `run_id`、`session_id`、`invocation_id` | —— | runtime 受理了 |
+| `invocation_ended` | `run_id`、`invocation_id`、`terminal_status` | —— | **唯一由推进器写的触发事实** |
+| `attempt_failed` | `watermark`、`reason` | `intent_seq` | 推进失败 |
+
+**「有 started 没有 accepted」是合法的中间状态**，含义是「正在启动，结果未知」。读日志时不要把它当成异常 —— 推进器会靠幂等键重投把它推进到 accepted。`run_kind` 只能是 `scheduler` 或 `task`；只有调度唤起带 `input_watermark`。