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

package/bundle/skills/df-task/skill_test.go

@@ -0,0 +1,201 @@
+package skill
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/deepflow/deepflow-task/internal/authz"
+	"github.com/deepflow/deepflow-task/internal/model"
+	"github.com/deepflow/deepflow-task/internal/validate"
+)
+
+func readFile(t *testing.T, path string) string {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(data)
+}
+
+func TestSkillHasFrontmatter(t *testing.T) {
+	content := readFile(t, "SKILL.md")
+	if !strings.HasPrefix(content, "---\n") {
+		t.Fatal("SKILL.md must start with YAML frontmatter")
+	}
+	frontmatter, _, found := strings.Cut(strings.TrimPrefix(content, "---\n"), "\n---")
+	if !found {
+		t.Fatal("frontmatter is not closed")
+	}
+	for _, key := range []string{"name:", "description:"} {
+		if !strings.Contains(frontmatter, key) {
+			t.Errorf("frontmatter is missing %s", key)
+		}
+	}
+	if !strings.Contains(frontmatter, "name: df-task") {
+		t.Errorf("frontmatter name must be df-task, got %q", frontmatter)
+	}
+}
+
+func TestSkillReferenceDocumentsEveryFactType(t *testing.T) {
+	// **十六种全要，不是只要智能体写得了的那九种。** 这份 reference 的作用是让智能体
+	// 读日志时认得每一条事实 —— 只遍历两个 Run 身份的可写集合，把「## 外部输入」
+	// 或「## 推进器写的」整张表删掉照样全绿，而 `external_result` 与 `invocation_ended`
+	// 是三条触发事实里的两条，认不出它们，读日志就读漏了最关键的两种。
+	reference := readFile(t, filepath.Join("references", "fact-types.md"))
+	for _, factType := range model.FactTypes() {
+		if !strings.Contains(reference, string(factType)) {
+			t.Errorf("references/fact-types.md 没有记 %s", factType)
+		}
+	}
+	// 「一共十六种」这个数字也要钉住。不钉的话，将来加第十六种类型时 Task 10 的
+	// `len(payloadSchemas) != len(model.FactTypes())` 会红，而这份文档会悄悄过期。
+	// **两个条件要各给自己的报错。** 合成一句 `if A || B` 的话，「有人把文档里那句话
+	// 删了而类型数还是 15」这一路会红出「文档写的是十六种，而 FactTypes() 有 15 种」
+	// —— 一句不含任何矛盾的话，看的人不知道该改文档还是改代码。而这一路恰好是最
+	// 常见的那一路：改文档比加第十六种类型常见得多。
+	if len(model.FactTypes()) != 16 {
+		t.Errorf("model.FactTypes() 有 %d 种，而 fact-types.md 与本断言都按十六种写的 —— 加了新类型要同时改这两处", len(model.FactTypes()))
+	}
+	if !strings.Contains(reference, "一共十六种事实") {
+		t.Error("fact-types.md 里找不到「一共十六种事实」这句 —— 这个数字是文档过期的唯一机械信号，不要删")
+	}
+}
+
+func TestSkillCommandTablesMatchTheAuthorizationMatrix(t *testing.T) {
+	// 两个方向都要验。只验「不该出现的没出现」，那么往调度一节里插一行
+	// `--type run_outcome` 照样全绿，而任务 Run 读到它就会去写，然后拿一个 403；
+	// 只验「该出现的出现了」，那么删掉一整行命令也照样全绿，而 Agent 在 Run 里
+	// 只有这份文档可读 —— 少一行，那条事实它就永远不会写。
+	content := readFile(t, "SKILL.md")
+	sections := map[model.ActorKind]string{
+		model.ActorTaskRun:      "## 任务 Run 可以写什么",
+		model.ActorSchedulerRun: "## 调度 Run 可以写什么",
+	}
+	for kind, heading := range sections {
+		// strings.Cut 返回三个值：before、after、found。这里要的是标题**之后**那段，
+		// 所以第一个返回值丢掉 —— 接成两个变量编译就过不去。
+		_, afterHeading, found := strings.Cut(content, heading)
+		if !found {
+			t.Fatalf("SKILL.md is missing the %q section", heading)
+		}
+		// 截到下一个 `## ` 为止。两节各自只谈自己那个身份，所以「职责边界」一节里
+		// 那句「写一条 summary 或 help_requested 说明情况」不会被算进调度一节。
+		section, _, _ := strings.Cut(afterHeading, "\n## ")
+		for _, factType := range model.FactTypes() {
+			// 正向只认表格那一列的形状 `| ` + 类型名 + `` ` ``。用裸的 Contains 会被
+			// 同一节的正文喂饱 —— 「`run_outcome` 只是你的主张」「读日志时你看到的是
+			// `dispatch_intent`」这些句子里都有类型名，于是删掉对应那行命令照样全绿，
+			// 而 Agent 在 Run 里只有这份文档可读，少一行那条事实它就永远不会写。
+			inTable := strings.Contains(section, "| `"+string(factType)+"`")
+			// 反向要宽：正文里出现一个写不了的类型，同样会把 Agent 带去拿 403。
+			mentioned := strings.Contains(section, string(factType))
+			switch {
+			case authz.CanWrite(kind, factType) && !inTable:
+				t.Errorf("%s 的命令表里没有 %s，而这个身份写得了它", heading, factType)
+			case !authz.CanWrite(kind, factType) && mentioned:
+				t.Errorf("%s 一节提了 %s，而这个身份写它会拿 403", heading, factType)
+			}
+		}
+	}
+	// 上面那两节里没有推进器的身份，所以唤起生命周期靠这一条兜：整份文档里都不许
+	// 出现「让 Agent 用 append 写它」的样子。
+	for _, factType := range authz.WritableBy(model.ActorDriver) {
+		if strings.Contains(content, string(factType)+" --file") {
+			t.Errorf("SKILL.md shows an agent writing %s; only the driver writes the invocation lifecycle", factType)
+		}
+	}
+}
+
+func TestSkillStatesTheEnvironmentContract(t *testing.T) {
+	content := readFile(t, "SKILL.md")
+	// DF_TASK_ID 和 DF_RUN_ID 也在这份清单里：SKILL.md 的示例命令用了它们，
+	// 而它们由 runtime 注入、不由本服务定义。示例里出现却没说明来源，
+	// Agent 就会以为要自己编一个。
+	for _, needle := range []string{"DF_TASK_BASE_URL", "DF_TASK_ACTOR_KIND", "DF_TASK_ACTOR_ID", "DF_TASK_ID", "DF_RUN_ID", "--json"} {
+		if !strings.Contains(content, needle) {
+			t.Errorf("SKILL.md does not mention %s", needle)
+		}
+	}
+}
+
+// 推进器拉起的 Run 里没有人可问。环境门禁若在 Run 内也要求询问，调度 Agent
+// 每一轮都会停下不读事实，而推进器照常记下执行结束——多轮执行就此静默断掉。
+func TestSkillResolvesTheRunEnvironmentWithoutAsking(t *testing.T) {
+	content := readFile(t, "SKILL.md")
+	for _, needle := range []string{"### Run 内的目标环境", "http://deepflowtask.deepflow.svc.cluster.local:8090` 即 `dev`", "不询问"} {
+		if !strings.Contains(content, needle) {
+			t.Errorf("SKILL.md does not state %q", needle)
+		}
+	}
+}
+
+func TestSkillStatesFactsAreAppendOnly(t *testing.T) {
+	content := readFile(t, "SKILL.md")
+	if !strings.Contains(content, "只追加") {
+		t.Fatal("SKILL.md must state that facts are append-only")
+	}
+}
+
+func TestPayloadExamplesPassServerValidation(t *testing.T) {
+	entries, err := os.ReadDir(filepath.Join("assets", "payload-examples"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) == 0 {
+		t.Fatal("there must be at least one payload example")
+	}
+	checked := 0
+	for _, entry := range entries {
+		// 只看 .json。这台机器上到处都是 .DS_Store，不过滤的话它会被当成
+		// 一个叫 ".DS_Store" 的事实类型，测试在一个与代码无关的原因上变红。
+		if !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+		checked++
+		name := strings.TrimSuffix(entry.Name(), ".json")
+		factType := model.FactType(name)
+		if !model.KnownFactType(factType) {
+			t.Errorf("%s is not a fact type", entry.Name())
+			continue
+		}
+		raw := readFile(t, filepath.Join("assets", "payload-examples", entry.Name()))
+		if !json.Valid([]byte(raw)) {
+			t.Errorf("%s is not valid JSON", entry.Name())
+			continue
+		}
+		if err := validate.Payload(factType, []byte(raw)); err != nil {
+			t.Errorf("%s would be rejected by the server: %v", entry.Name(), err)
+		}
+	}
+	if checked == 0 {
+		t.Fatal("the directory has entries but none of them is a .json example")
+	}
+}
+
+func TestEveryHandWrittenPayloadHasAnExample(t *testing.T) {
+	// 凡是 SKILL.md 让智能体自己写 payload 的事实类型，都要有一份能抄的样例。
+	// 语法糖那三种（dispatch / wait / handoff）的字段由 CLI 填，不需要样例。
+	// **这里两个身份都要走。** 只走任务 Run 的话，调度 Run 那两种手写类型就露在外面：
+	// `adjudication` 的 `subject` 是全服务唯一一个数字字段，没样例的调度智能体会写成
+	// 字符串然后吃一个 422；而日志只追加，它既改不了那条，也没有别的地方能学对。
+	sugar := map[model.FactType]bool{
+		model.FactDispatchIntent: true,
+		model.FactWaitingReason:  true,
+		model.FactHandoffToHuman: true,
+	}
+	for _, kind := range []model.ActorKind{model.ActorTaskRun, model.ActorSchedulerRun} {
+		for _, factType := range authz.WritableBy(kind) {
+			if sugar[factType] {
+				continue
+			}
+			path := filepath.Join("assets", "payload-examples", string(factType)+".json")
+			if _, err := os.Stat(path); err != nil {
+				t.Errorf("%s 缺样例，而 %s 要手写这份 payload：%v", factType, kind, err)
+			}
+		}
+	}
+}

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

@@ -0,0 +1,126 @@
+---
+name: df-taskdriver
+description: 使用df-taskdriver CLI诊断DeepFlow任务推进器的运行状态，回答某个Task为什么没有被推进、当前哪些Task正在被处理、实例是否就绪。适用于任务卡住时的排查与部署后的健康确认，不负责创建Task、写入事实或决定下一步动作。
+---
+
+# DeepFlow Task Driver
+
+通过`df-taskdriver`查看一个正在运行的driver实例。运行命令前确认CLI已在PATH中；实例地址由`DF_TASKDRIVER_BASE_URL`或`--base-url`提供，默认`http://127.0.0.1:8081`。本Skill不安装二进制，也不启动服务。
+
+## 目标环境门禁与地址
+
+每次调用 driver 前，必须先确认用户要操作的目标环境。用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
+
+| 目标环境 | 本地执行时的地址 | 在 dev-k8s 内执行时的地址 |
+| --- | --- | --- |
+| `local` | `http://127.0.0.1:8081` | 不适用 |
+| `dev` | `https://deepflowtaskdriver.dev.deepwisdomai.com` | `http://deepflowtaskdriver.deepflow.svc.cluster.local:8081` |
+| `prod` | 尚未配置 | 尚未配置 |
+
+地址列描述的是同一目标环境的两种访问方式：本地 CLI 使用 dev Ingress，集群内 Agent 使用 dev Service DNS。确认环境后，可以用用户明确提供的 `--base-url` 覆盖该环境的默认地址，但该地址必须属于已选环境；如果地址与环境冲突，先停止并澄清，不能用它绕过环境门禁。`prod` 目前没有地址，任何 prod 操作都必须停止并说明尚未接入。
+
+本地操作 dev 时示例：
+
+```bash
+df-taskdriver --base-url https://deepflowtaskdriver.dev.deepwisdomai.com task <task-id>
+```
+
+执行任何诊断前先请求选定地址的 `GET /healthz`。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
+
+```bash
+df-taskdriver help
+df-taskdriver task <task-id>
+```
+
+若命令不存在，说明缺少CLI部署：本项目源码可用时运行`make install-cli`，否则向调用方说明需要安装`df-taskdriver`并提供实例地址。driver的地址不是事实服务的地址，也不是runtime的地址。
+
+## driver做什么，不做什么
+
+driver不决定任何业务动作。它只做两件事：发现某个Task有未被覆盖的触发事实时，起一个调度Run；看到调度智能体写下的`dispatch_intent`时，把它兑现成一次runtime唤起。**下一步做什么由调度智能体决定，写在事实日志里**——所以「Task停住了」有两种完全不同的原因，排查的第一步就是区分它们：
+
+- driver还欠着事（有在飞唤起、有未兑现意图、或谓词成立但还没跑到），问题在driver或它的上游依赖。
+- driver无未了之事，那是调度智能体没有下发新意图、或者事实压根没写进日志。这时候查driver是白费功夫。
+
+## Task metadata 的路由作用
+
+driver 会读取 Task metadata 里的 source 和 query_keys，把它作为软范围提示传给 Agent Control，
+并将完整 metadata 透传给新建的 Runtime Session。driver CLI 没有修改或筛选 metadata 的命令，
+也不会把它当成权限检查；没有 metadata 的旧Task仍按原有流程推进。
+
+如果某个Task因为范围内找不到Agent而没有推进，先用事实服务查看 Task metadata，再用同一范围
+检查控制面目录：
+
+    df-task get <task-id> --json
+    df-agentctrl list \
+      --metadata-source <source> \
+      --metadata-query-key <query-key> \
+      --json
+
+query_keys 可以包含多个标识；"*" 表示显式共享。没有业务上下文时不要凭空添加过滤条件，
+否则可能把本来可用的全量目录缩小。
+
+**只要实例答了 200**，`task`子命令的最后一行就会直接说明属于哪一种，**三句话必有一句**，不会出现「最后一行什么也没说」的情况：
+
+- `驱动这边还有未了之事（见上方在飞唤起／未兑现意图），先看它们卡在哪一步`⇒ 第一种，往上翻看在飞唤起和未兑现意图。
+- `驱动无未了之事，继续查上游（事实是否写入、调度智能体是否下发）`⇒ 第二种，查上游。
+- `驱动这边没有未了之事，谓词已成立，下一拍就会起一轮调度——这一刻不用做什么`⇒ 两者都不是：driver 手上是干净的，而且它**已经决定要起一轮了**，只是还没跑到那一拍。刚往Task写完一条`user_message`时看到的就是这一句。这一刻什么都不用做，隔一个扫描间隔再看；如果反复看到同一句而水位线一直不动，那才是故障，按第一种往下查。
+
+这三句只在人类输出、而且实例真的答了 200 的时候出现。`--json`走的是另一条路——响应体原样印出，没有这一行；用法错误、`limit`越界、非 2xx、响应体解析不了这几种情况下最后一行是报错本身，退出码也不是 0，其中最常撞上的是非 2xx（最后一行形如`读取失败: ...`）。看见这些就照下面「输出与错误」那一节读退出码，别在那里找这三句。
+
+第三句是刻意从第二句里拆出来的：它和第二句都是「驱动无未了之事」，但结论相反——一句叫你去查上游，一句叫你什么都别做。早先两句版本会把这种最常见的正常状态归到第一句，而那句让人「往上翻看在飞唤起」，上方偏偏什么都没印，等于把人指向一段不存在的输出。
+
+## 排查一个不动的Task
+
+```bash
+df-taskdriver task <task-id>
+df-taskdriver task <task-id> 20        # 每页 20 条读；整条日志照样会读完
+df-taskdriver --json task <task-id>    # 给脚本用
+df-taskdriver task <task-id> --json    # 等价，两个位置都认
+```
+
+第二个位置参数是 `limit`，透传成 `/debug/tasks/{id}?limit=`，必须是正整数（`0` 和负数会被 CLI 当场拒掉，退出 2，请求不会发出去）。**它是页大小，不是上限**：无论传多少，实例都会翻页把整条日志读完再折叠，所以**只要事实服务正常推进 `after_seq`**，这里的结论就是看全了日志得出的，和推进循环一致。传小值的唯一效果是把一次读拆成更多次上游请求——它不是「日志太长时用来少读点」的旋钮，那样用只会更慢。不传就用默认页大小。响应里的 `facts` 和 `max_seq` 是**这次读到并折叠了多少**：正常情况下就等于整条日志，而一个比预期小的数正是「这次没读全」的信号——上游不推进 `after_seq` 的时候翻页会提前收手、返回一个前缀，而那个前缀折出来的结论是会错的。排障时先看这两个数，因为你怀疑的上游恰恰是最可能干这件事的那一个。
+
+输出第一行是 Task ID，第二行是结论，其余是证据。按下面的顺序读：
+
+1. **结论行（第二行）**。`不会调度`后面跟着谓词给出的理由，这就是答案本身。
+2. **水位线 / 最大触发事实 / 本轮锚点**。谓词成立的条件是「最大触发事实的seq超过水位线」。水位线是某一轮调度声明「我已经看到这里」的位置，锚点是那一轮幂等键的推导来源——两者印在一起是为了让人看出它们不是一个东西。
+3. **在飞唤起**。有调度Run在飞时谓词必然不成立，这是正常的等待而不是故障。标着`[待重放]`的是「起了但结果未知」，下一轮对账会用同一把派生键重新POST，不需要人工干预。
+4. **失败预算**。标着`已耗尽`时driver主动停手等人：确认上游问题已修好后，往该Task写一条新的`user_message`即可恢复——它的seq高于当前水位线，谓词立刻重新成立。不要试图通过重启driver来恢复，重启不改变任何事实。
+5. **未兑现意图**。有意图却一直没有对应的在飞唤起，说明兑现路径在失败，看`attempt_failed`事实和driver日志。
+
+## 其他子命令
+
+```bash
+df-taskdriver health                    # 进程还在吗
+df-taskdriver ready                     # 能不能干活，未就绪时退出码 1
+df-taskdriver locks                     # 当前哪些 Task 正在被处理、被谁
+df-taskdriver metrics [过滤子串]         # 抓取指标
+```
+
+`health`和`ready`是两回事：连不上Redis的实例**不就绪但仍然存活**，不该被重启——Redis恢复后下一拍自己就接上了。
+
+`locks`里`其他实例`的持有者是正常的横向扩容现象。锁不续期，所以TTL在一轮还活着时过期、两个实例同时处理一个Task也是允许的：唤起键从日志事实推导。runtime 只有在已部署 `0004_session_idempotency.sql` 和支持 `Idempotency-Key` 的新 handler 时，Session 与 Invocation 幂等键才会把重复请求收敛到同一组资源；旧版本不具备这一保证。可运行 `scripts/accept-runtime-contract.sh`（或追加 `-race`）验证真实 HTTP+SQLite 恢复闭环。指标里`lock_expired_before_release`持续出现说明`LockTTL`配得比真实轮次时长短，仍需调参。
+
+## 输出与错误
+
+自动处理响应用`--json`：它把实例返回的响应体原样印出来（只重新缩进），不经过CLI自己的结构体。所以新实例多返回的字段不会被吞掉，CLI比实例旧一个版本时`--json`依然完整——而人类输出只显示这一版CLI认识的字段。`--json`写在子命令前后都认：`df-taskdriver --json task <task-id>` 和 `df-taskdriver task <task-id> --json` 完全等价。两种写法都支持是刻意的——技术设计 2.7 举的例子是后置形式，而它恰好是 Go `flag` 包默认解析不到的位置（解析在第一个位置参数处就停了），于是 `--json` 会被当成位置参数悄悄吞掉：`locks` 照样印人类文本并退出 0，脚本拿到的是「实例给了肯定回答」而不是它要的 JSON。
+
+`metrics`接受`--json`但忽略它：`/metrics`是Prometheus文本，没有第二种渲染可选。接受而不报错是刻意的，这样脚本可以给所有子命令统一加上`--json`。
+
+- 退出0：实例给出肯定回答。
+- 退出1：实例回答了但是否定的（未就绪、读取失败、指标注册表没接上）。**非2xx的响应体解析不了也算这一档**——多半是反向代理的错误页带着真实状态码，而状态码本身就是那个否定回答。
+- 退出2：**三种情况**——连不上实例（先核对`--base-url`）、用法错误（参数个数或`limit`越界）、以及**2xx**但响应体不是合法JSON（多半是反向代理返回的错误页披着200：此时状态行是唯一的肯定依据，而它已经不可信了）。后两种情况下响应体照样会印出来，看见它才是发现代理挡在前面的途径。
+
+**最后那一档不适用于`metrics`。** `/metrics`回的是Prometheus文本，它本来就不是JSON——对它做「响应体不是合法JSON就退出2」的检查，等于这个子命令永远退出2。所以`metrics`只按状态码算退出码：2xx是0，其余是1（连不上实例仍然是2——那一档跟响应体无关）。代价是一个披着200的代理错误页在`metrics`这一档会被当成肯定回答；这是没办法的事，Prometheus文本没有「合法性」可验（一份空的抓取结果和一个空的错误页在字节上没有区别），而真正的抓取端`/metrics`本身会由Prometheus自己的`up`指标兜住。其余四个真的发请求的子命令（`health` / `ready` / `locks` / `task`）都吃这一档；`help` 不发请求，所以六个子命令里只有 `metrics` 是豁免的那一个。
+
+区分1和2很重要：1说明实例活着且在正常表达状态，2说明根本没拿到回答（或者问法不对）。运维脚本把2当重试、把1当报警。
+
+**这套退出码与`df-agentctrl`的映射不同，不要套用。** 两边都用0/1/2，差别在于谁落到哪一档：ctrl 把「连不上」「HTTP≥400」「响应体不是合法JSON」全折进1（它的`doRequest`对这三种一律返回error），2只留给用法错误、未知子命令和base-url不合法；driver 把「连不上」和「2xx但响应体不是JSON」拆出去给2，1只留给「实例回答了但是否定的」。所以一段照着ctrl写的脚本搬过来，会把 driver 的「没问到」当成「问到了个否」。driver 要这么拆，是因为它的正常状态里就包含「上游全挂但我活着」：那种状态下`ready`必须是0而`task`必须是1，而「根本没拿到回答」必须和这两个都分得开——脚本对2重试、对1报警。
+
+本Skill的所有命令都是只读的GET，不会改变任何状态。需要往Task写事实、创建Task或查询事实日志，用事实服务自己的接口，不要指望在这里做。

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

@@ -0,0 +1,64 @@
+---
+name: df-workbench
+description: 面向普通用户的 DeepFlow Workbench 入口。使用 df-workbench 获取当前用户和工作区配置，创建 Task、发送后续对话、读取 Task 事实并反馈可见进度；不负责 driver、Agent Control 或 Runtime 的开发者排障，也不执行本地安装。
+---
+
+# df-workbench
+
+`df-workbench` 是普通用户的轻量入口。它保持与 Workbench 人工操作一致：先确定当前身份和工作区，再通过 Workbench 的用户 API 创建任务和发送消息。不要直接调用数据库、`df-task` 的写接口或伪造 `DF_TASK_ACTOR_*` 身份。
+
+## 环境和身份
+
+用户必须先明确目标环境：`local`、`dev` 或 `prod`。本轮不要因为连接失败自动切换环境。
+
+CLI 配置：
+
+```text
+DF_WORKBENCH_BASE_URL       Workbench 根地址；默认 http://127.0.0.1:8793
+DF_WORKBENCH_TOKEN          OIDC 环境使用的 personal token
+DF_WORKBENCH_WORKSPACE_ID   可选，覆盖当前工作区
+```
+
+运行前先调用：
+
+```bash
+df-workbench me --json
+df-workbench config --json
+```
+
+`me` 返回当前用户和可访问工作区；`config` 返回认证模式、当前工作区、Task 写入能力和 Workbench UI 能力。不要打印 Token、Cookie 或其他凭据。
+
+local 环境只允许从本机回环地址访问；OIDC 环境使用 Workbench personal token。Token 应通过公司内部配置或 Skill 平台提供，不在命令参数中传递。
+
+## 用户任务流程
+
+创建 Task：
+
+```bash
+df-workbench task create --message '请检查登录页按钮溢出问题' --json
+```
+
+继续对话：
+
+```bash
+df-workbench task send <task-id> --message '补充检查 Safari 浏览器' --json
+```
+
+读取任务和事实：
+
+```bash
+df-workbench task get <task-id> --json
+df-workbench task facts <task-id> --json
+```
+
+创建和发送必须使用稳定的 `--idempotency-key`。如果请求超时或返回未知结果，不要换一个 key 盲目重试；沿用原 key 核对结果。
+
+## 用户反馈边界
+
+可以根据 `task facts` 反馈已经写入的用户消息、Agent 回应、等待原因、交接和产物事实。默认将内部事实整理成用户可理解的里程碑，不展示内部游标、锁、Session 或 Invocation 细节。
+
+如果事实不足以解释任务为什么没有继续推进，只能如实反馈当前可见事实，并说明需要 DeepFlow 开发者排查。不要自行调用 `df-taskdriver`、`df-agentctrl` 或 `df-agentrt`，也不要把“没有新事实”描述成“已经定位故障”。
+
+## 缺少依赖
+
+如果 `df-workbench` CLI 或本 Skill 缺失，提示用户从公司内部 Skill 共享平台安装对应项目，不执行 `pnpm`、`go install`、`make install-cli`、`git clone` 或本地 Skill 目录复制。

package/bundle/skills/df-workbench/manifest.yaml

@@ -0,0 +1,5 @@
+id: df-workbench
+version: 1.0.0
+provides:
+  skill: df-workbench
+  cli: df-workbench

package/manifest.json

@@ -0,0 +1,68 @@
+{
+  "distribution": "deepflow-suite",
+  "version": "0.1.1",
+  "skills": [
+    {
+      "name": "deepflow-suite",
+      "source": "tools/deepflow-cli/skills/deepflow-suite",
+      "packageSource": "skills/deepflow-suite"
+    },
+    {
+      "name": "df-workbench",
+      "source": "deepflow-workbench/skills/df-workbench",
+      "packageSource": "skills/df-workbench"
+    },
+    {
+      "name": "df-task",
+      "source": "deepflow-task/skills/df-task",
+      "packageSource": "skills/df-task"
+    },
+    {
+      "name": "df-taskdriver",
+      "source": "deepflow-task-driver/skills/df-taskdriver",
+      "packageSource": "skills/df-taskdriver"
+    },
+    {
+      "name": "df-agentctrl",
+      "source": "deepflow-agent-ctrl/skills/df-agentctrl",
+      "packageSource": "skills/df-agentctrl"
+    },
+    {
+      "name": "df-agentrt",
+      "source": "deepflow-agent-runtime/skills/df-agentrt",
+      "packageSource": "skills/df-agentrt"
+    },
+    {
+      "name": "df-agentrt-repo",
+      "source": "deepflow-agent-runtime/skills/df-agentrt-repo",
+      "packageSource": "skills/df-agentrt-repo"
+    }
+  ],
+  "clis": [
+    {
+      "name": "df-workbench",
+      "project": "deepflow-workbench",
+      "install": "project"
+    },
+    {
+      "name": "df-task",
+      "project": "deepflow-task",
+      "install": "make install-cli"
+    },
+    {
+      "name": "df-taskdriver",
+      "project": "deepflow-task-driver",
+      "install": "make install-cli"
+    },
+    {
+      "name": "df-agentctrl",
+      "project": "deepflow-agent-ctrl",
+      "install": "make install-cli"
+    },
+    {
+      "name": "df-agentrt",
+      "project": "deepflow-agent-runtime",
+      "install": "make build"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@metagptx/deepflow-suite-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Agent-friendly installer and distribution CLI for the DeepFlow suite.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "deepflow-suite": "./bin/deepflow-suite.js"
+  },
+  "files": [
+    "bin/",
+    "bundle/",
+    "manifest.json",
+    "skills/",
+    "src/",
+    "scripts/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "prepack": "node scripts/build-package.mjs",
+    "pack:dry-run": "npm pack --dry-run"
+  }
+}

package/scripts/build-package.mjs

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assembleBundle } from "../src/bundle.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workspaceRoot = path.resolve(packageRoot, "../..");
+await assembleBundle({
+  workspaceRoot,
+  outputDir: path.join(packageRoot, "bundle"),
+  manifestPath: path.join(packageRoot, "manifest.json"),
+});

package/skills/deepflow-suite/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: deepflow-suite
+description: DeepFlow 统一入口。常规任务默认使用 df-workbench；只有用户明确要求或 Workbench 事实无法解释阻塞时，才按顺序检查 Task、Task Driver、Agent Control 和 Agent Runtime。
+---
+
+# DeepFlow Suite
+
+这是 DeepFlow 的统一用户和开发者入口。它开放完整的 DeepFlow 能力，但不默认调用整条链路：普通任务先走 `df-workbench`，只有确实需要解释推进、Agent 或 Runtime 问题时才升级到其他项目 CLI。
+
+## 依赖
+
+本 Skill 依赖以下项目级 Skill 和 CLI：
+
+- `df-workbench`：用户身份、工作区、Workbench 配置和任务事实；
+- `df-task`：Task 原始事实和事实落库核对；
+- `df-taskdriver`：任务推进和唤起兑现诊断；
+- `df-agentctrl`：Agent 定义、版本和可分配目录；
+- `df-agentrt`：Session、Invocation、transcript 和运行现场。
+- `df-agentrt-repo`：在 Runtime 会话中发现和追加代码仓库。
+
+这些依赖由 `deepflow-suite` 安装器统一安装。不要因为某个依赖缺失就自行复制 Skill、克隆仓库或切换安装源。
+
+## 环境门禁
+
+用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有 Workbench、Task、Driver、Agent Control 和 Runtime 请求保持在同一环境。连接失败不能静默切换环境。
+
+## 默认路由
+
+### 普通任务
+
+创建任务、继续对话、查看任务和读取可见进度，只调用 `df-workbench`：
+
+```bash
+df-workbench me --json
+df-workbench config --json
+df-workbench task create --message '<用户原始请求>' --json
+df-workbench task send <task-id> --message '<补充内容>' --json
+df-workbench task get <task-id> --json
+df-workbench task facts <task-id> --json
+```
+
+不要在普通用户入口直接调用 `df-task` 写接口，不要伪造 `DF_TASK_ACTOR_*`，不要自行创建 Run 或选择执行 Agent。
+
+### 深度排障
+
+用户询问“任务为什么卡住”“为什么没有执行”“查看 Session/Invocation”“检查 Driver/Agent/Runtime”时，按以下顺序只读检查：
+
+```text
+df-workbench
+  → df-task
+  → df-taskdriver
+  → df-agentctrl
+  → df-agentrt
+```
+
+前一步事实不足以解释问题时，才进入下一步。不要把某个服务可达描述成整条链路成功，也不要把未知状态描述成完成或失败。
+
+## 写操作安全
+
+- 普通排障优先只读；
+- 取消、释放 Session、修复孤儿执行、启停或回退 Agent 前必须获得明确确认；
+- 不直接修改 Task 事实；
+- 不因诊断失败而重建 Session、Invocation 或切换环境；
+- 所有服务请求保持在用户选定的环境。
+
+## 输出边界
+
+回复时区分：
+
+1. 已由事实确认的结果；
+2. Driver、Agent Control 或 Runtime 返回的诊断；
+3. 仍无法确认的未知状态；
+4. 需要用户或服务维护者采取的下一步。

package/skills/deepflow-suite/manifest.yaml

@@ -0,0 +1,20 @@
+id: deepflow-suite
+version: 0.1.1
+kind: composite-skill
+requires:
+  skills:
+    - df-workbench
+    - df-task
+    - df-taskdriver
+    - df-agentctrl
+    - df-agentrt
+    - df-agentrt-repo
+  cli:
+    - df-workbench
+    - df-task
+    - df-taskdriver
+    - df-agentctrl
+    - df-agentrt
+resolution:
+  managed_by: deepflow-suite
+  install_missing_dependencies: false