@metagptx/deepflow-suite-cli 0.2.11-dev.20261020.1 → 0.3.0

package/src/package-cli.mjs

@@ -1,66 +1,50 @@
-import { access, lstat } from "node:fs/promises";
-import path from "node:path";
-
-import { resolveInstalledPackageRoot } from "./cli-launcher.mjs";
-import { verifyRuntimePackage } from "./runtime-build.mjs";
-import { runtimeBinaryNames, runtimePackageForPlatform } from "./runtime-package.mjs";
-
-const PACKAGE_BINARIES = ["deepflow-suite", "df-workbench", ...runtimeBinaryNames()];
-
-async function regularFile(filePath) {
-  try {
-    const stats = await lstat(filePath);
-    if (!stats.isFile()) return false;
-    await access(filePath);
-    return true;
-  } catch {
-    return false;
+import { access, readFile, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import { CLI_NAMES } from './constants.mjs';
+
+export const PACKAGE_BINARIES = ['deepflow-suite', ...CLI_NAMES];
+const execute = promisify(execFile);
+export async function commandOnPath(name, env = process.env) {
+  const extensions = process.platform === 'win32' ? ['', '.cmd', '.exe', '.bat'] : [''];
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(dir, name + extension);
+      try { await access(candidate, process.platform === 'win32' ? constants.F_OK : constants.X_OK); return candidate; } catch {}
+    }
   }
 }
-
-export async function verifyPackageClis({
-  packageRoot,
-  expectedVersion,
-  platform = process.platform,
-  arch = process.arch,
-}) {
-  const missing = [];
-  const invalid = [];
-  const binaries = [];
+export async function verifyPackageClis({ packageRoot, expectedVersion, checkPath = false, env = process.env }) {
+  const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+  const missing = [], invalid = [], binaries = [];
   for (const name of PACKAGE_BINARIES) {
-    const filePath = path.join(packageRoot, "bin", `${name}.js`);
-    if (await regularFile(filePath)) binaries.push({ name, path: filePath });
-    else missing.push(name);
-  }
-
-  const packageName = runtimePackageForPlatform(platform, arch);
-  const platformInfo = { platform, arch, package: packageName };
-  if (!packageName) {
-    invalid.push({ name: "platform", reason: `unsupported DeepFlow CLI platform: ${platform}/${arch}` });
-  } else {
+    const relative = packageJson.bin?.[name];
+    const entry = relative && path.resolve(packageRoot, relative);
+    if (!entry || !entry.startsWith(path.resolve(packageRoot) + path.sep)) { missing.push(name); continue; }
     try {
-      const runtimeRoot = resolveInstalledPackageRoot(packageRoot, packageName);
-      await verifyRuntimePackage({
-        packageRoot: runtimeRoot,
-        target: platformInfo,
-        expectedVersion,
-      });
-    } catch (error) {
-      invalid.push({ name: packageName, reason: error.message });
-    }
+      await access(entry);
+      const { stdout } = await execute(process.execPath, [entry, '--cli-version', '--json'], { env, timeout: 10000 });
+      const version = JSON.parse(stdout);
+      if (version.name !== name || version.version !== expectedVersion) throw Error(`CLI version ${version.version} does not match ${expectedVersion}`);
+      await execute(process.execPath, [entry, '--help'], { env, timeout: 10000 });
+      const binary = { name, path: entry, version: version.version };
+      if (checkPath) {
+        binary.resolvedPath = await commandOnPath(name, env);
+        if (!binary.resolvedPath) missing.push(name);
+        else {
+          const canonical = await realpath(binary.resolvedPath);
+          const matches = process.platform === 'win32' && /\.(cmd|bat)$/i.test(canonical)
+            ? (await readFile(canonical, 'utf8')).replaceAll('\\', '/').includes(relative.replaceAll('\\', '/'))
+              && [path.resolve(path.dirname(canonical), 'node_modules', packageJson.name), path.resolve(path.dirname(canonical), '..', packageJson.name)].includes(await realpath(packageRoot))
+            : canonical === await realpath(entry);
+          if (!matches) invalid.push({ name, reason: 'another installation shadows this Suite on PATH', expected: entry, actual: binary.resolvedPath });
+        }
+      }
+      binaries.push(binary);
+    } catch (error) { invalid.push({ name, reason: error.message }); }
   }
-
-  const workbenchEntry = path.join(packageRoot, "runtime", "df-workbench.mjs");
-  if (!await regularFile(workbenchEntry)) invalid.push({ name: "df-workbench", reason: "packaged Workbench CLI entry is missing" });
-
-  return {
-    ok: missing.length === 0 && invalid.length === 0,
-    platform: platformInfo,
-    package: packageRoot,
-    binaries,
-    missing,
-    invalid,
-  };
+  return { ok: !missing.length && !invalid.length, package: packageRoot, version: expectedVersion, binaries, missing, invalid };
 }
-
-export { PACKAGE_BINARIES };

package/bin/df-agentctrl.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { runRuntimeCli } from "../src/cli-launcher.mjs";
-
-try {
-  process.exitCode = await runRuntimeCli("df-agentctrl", process.argv.slice(2));
-} catch (error) {
-  console.error(error.message);
-  process.exitCode = 1;
-}

package/bin/df-agentrt.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { runRuntimeCli } from "../src/cli-launcher.mjs";
-
-try {
-  process.exitCode = await runRuntimeCli("df-agentrt", process.argv.slice(2));
-} catch (error) {
-  console.error(error.message);
-  process.exitCode = 1;
-}

package/bin/df-task.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { runRuntimeCli } from "../src/cli-launcher.mjs";
-
-try {
-  process.exitCode = await runRuntimeCli("df-task", process.argv.slice(2));
-} catch (error) {
-  console.error(error.message);
-  process.exitCode = 1;
-}

package/bin/df-taskdriver.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { runRuntimeCli } from "../src/cli-launcher.mjs";
-
-try {
-  process.exitCode = await runRuntimeCli("df-taskdriver", process.argv.slice(2));
-} catch (error) {
-  console.error(error.message);
-  process.exitCode = 1;
-}

package/bin/df-workbench.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { runWorkbench } from "../src/cli-launcher.mjs";
-
-try {
-  process.exitCode = await runWorkbench(process.argv.slice(2));
-} catch (error) {
-  console.error(error.message);
-  process.exitCode = 1;
-}

package/bundle/skills/deepflow-suite/manifest.yaml

@@ -1,20 +0,0 @@
-id: deepflow-suite
-version: 0.2.9
-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

package/bundle/skills/df-agentctrl/references/environment.md

@@ -1,40 +0,0 @@
-# 环境与地址
-
-
-每次调用控制面前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
-
-```text
-请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
-```
-
-环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
-
-| 目标环境 | 集群外访问地址 | 对应环境集群内地址 |
-| --- | --- | --- |
-| `local` | `http://127.0.0.1:8080` | 不适用 |
-| `dev` | `https://deepflowagentctrl.dev.deepwisdomai.com` | `http://deepflowagentctrl.deepflow.svc.cluster.local:8080` |
-| `prod` | `https://deepflowagentctrl.deepwisdomai.com` | `http://deepflowagentctrl.deepflow.svc.cluster.local:8080` |
-
-`prod` 指国内生产 `prod-cn`。集群内地址只在对应环境集群中访问；dev 与 prod 的 Service DNS 字符串相同，不能仅凭该字符串反查环境，也不能从本机直接访问它来代替生产入口。CLI 不会按环境名自动选址：本地调用须显式设置已选环境的地址；可以使用用户提供且已确认归属的 `--base-url`，地址与已选环境冲突时先澄清，连接失败不得改用其他环境。生产写操作仍只执行当前任务已授权的范围。
-
-本地操作 dev 时示例：
-
-```bash
-df-agentctrl --base-url https://deepflowagentctrl.dev.deepwisdomai.com list --json
-```
-
-### Run 内的目标环境
-
-`DF_TASK_ID`、`DF_RUN_ID`、`DF_TASK_ACTOR_KIND` 都非空时，你运行在推进器拉起的 Run 里。`DF_AGENTCTRL_BASE_URL` 由部署注入，绑定当前流程使用的控制面；沿用它读取 Agent 目录与定义，不重新询问环境、不根据同名 Service DNS 猜成 dev，也不因业务需求中出现“生产/开发”就重定向流程服务。业务项目的目标环境与 DeepFlow 流程服务的部署环境分别核对。
-
-注入地址缺失或与当前流程已确认的部署环境冲突时，停止相关调用并说明缺口；不回退 localhost、不自行改地址或伪造身份。不在 Run 里时，先由用户选择环境，再按上表显式选址；内部 DNS 需要已确认的集群访问上下文。
-
-先请求选定地址的 `GET /healthz`，确认控制面可用后再执行创建、保存、启停或回退。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
-
-```bash
-df-agentctrl help
-df-agentctrl list --json
-```
-
-若命令不存在，说明缺少CLI部署：本项目源码可用时运行`make install-cli`，否则向调用方说明需要安装`df-agentctrl`及提供控制面地址。不要因为这个Skill是在runtime里加载的，就把runtime地址当作控制面地址。
-

package/bundle/skills/df-agentctrl/references/query-scope.md

@@ -1,50 +0,0 @@
-# metadata 与软范围查询
-
-
-Agent 定义可以在创建时携带业务方自定义的 JSON metadata。基础服务只约定顶层的
-`source`、`query_keys` 和 `data`：`source` 与 `query_keys` 用于可选的软范围查询，`data`
-由业务方自行组织，服务不会解释其中字段。
-
-创建时把 metadata 放在快照文件的顶层：
-
-```json
-{
-  "name": "代码评审Agent",
-  "description": "阅读代码变更并给出可操作的评审意见",
-  "instructions": "根据任务提供的代码和上下文完成评审。",
-  "skills": [],
-  "mcp_config": {},
-  "metadata": {
-    "source": "workbench",
-    "query_keys": ["account:u123"],
-    "data": {"project": "orders"}
-  },
-  "change_note": "初始版本"
-}
-```
-
-```bash
-df-agentctrl create --file agent.json --json
-```
-
-有业务上下文时，优先限定目录和读取范围：
-
-```bash
-df-agentctrl list \
-  --metadata-source workbench \
-  --metadata-query-key account:u123 \
-  --json
-df-agentctrl get <agent-id> \
-  --metadata-source workbench \
-  --metadata-query-key account:u123 \
-  --json
-```
-
-查询规则：`query_keys` 可以包含多个标识；`"*"` 表示显式共享，匹配任意来源和查询标识；
-不提供过滤参数仍然查询全部启用Agent（`list`）或按 ID 读取（`get`）。metadata 是查询范围，
-不是权限控制。若按范围 `get` 返回不存在，应同时考虑 Agent 不属于该范围的情况。
-
-metadata 归属于 Agent 定义本身，而不是某个版本。当前 CLI 只有 `create --file` 能在创建时
-写入 metadata；`save` 是版本快照写入，不要把 metadata 加进保存文件，也没有单独修改 metadata
-的命令。保存已有 Agent 时沿用维护说明中的快照格式。
-

package/bundle/skills/df-agentrt/references/environment.md

@@ -1,29 +0,0 @@
-# 环境与地址
-
-
-使用外部 `agentrt` CLI 指向 Runtime 服务时，必须先确认用户要操作的目标环境；当前会话的 `df-agentrt` 操作沿用下文的部署绑定。外部操作中用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
-
-```text
-请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
-```
-
-环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
-
-| 目标环境 | 集群外访问地址 | 对应环境集群内地址 |
-| --- | --- | --- |
-| `local` | `http://127.0.0.1:8141` | 不适用 |
-| `dev` | `https://deepflowagentruntime.dev.deepwisdomai.com` | `http://deepflowagentruntime.deepflow.svc.cluster.local:8141` |
-| `prod` | `https://deepflowagentruntime.deepwisdomai.com` | `http://deepflowagentruntime.deepflow.svc.cluster.local:8141` |
-
-`prod` 指国内生产 `prod-cn`。集群内地址只在对应环境集群中访问；dev 与 prod 的 Service DNS 字符串相同，不能仅凭地址反查环境。外部操作确认环境后显式设置 `AGENTRT_ADDR`；用户提供的地址须已确认属于该环境，冲突时先澄清，连接失败不切换环境。生产操作仍只执行当前任务已授权的范围。
-
-本地操作 dev 时示例：
-
-```bash
-AGENTRT_ADDR=https://deepflowagentruntime.dev.deepwisdomai.com agentrt session ls
-```
-
-先请求选定地址的 `GET /healthz`，确认 runtime 可用后再执行操作。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
-
-`df-agentrt` 的 `session`、`repo`、`events` 等命令操作的是部署绑定的当前 Runtime 会话控制面，不接受 `AGENTRT_ADDR`。当前会话的操作沿用注入上下文，无须再次询问环境；不能由 Service DNS 或业务项目目标环境推断并切换流程服务。不要把当前会话与另一个环境的 Runtime 混用。需要明确操作某个环境的 Runtime 服务时，使用 `agentrt` 并设置对应的 `AGENTRT_ADDR`。
-

package/bundle/skills/df-agentrt/references/invocation-result.md

@@ -1,11 +0,0 @@
-# Invocation 结果读取契约
-
-`df-agentrt invocation result <id> --json [--max-bytes N] [--output-file PATH]`；外部 `agentrt` 命令相同，分别沿用注入 MULTICA_SERVER_URL 和显式 AGENTRT_ADDR。只调用既有 GET /v1/invocations/{id}，不启动执行、不汇总事件。
-
-输出 invocation_id、session_id（Runtime 身份）、status、terminal、finished_at（存在时）、result_state、output_present、output、output_bytes、output_returned_bytes、output_truncated、output_sha256（完整正文的 hash），以及存在时的 error/result_error/failure_reason/format_error、output_file。
-
-result_state：pending=已知的非终态；available=终态且有字符串 output（可以为空）；missing=终态缺 result/output 或 output=null；invalid=无法识别状态、结果格式或字段类型。failed/cancelled 仍可能有 partial output，available 只说明存在正文。状态未知保留原值并且 terminal=false。缺正文不创建空报告；合法空字符串则写 0 字节文件并有空内容的 SHA。
-
-默认最多返回 4096 UTF-8 字节，可显式设置 1..1048576；字符不切半。output_truncated 是展示截断，与执行是否结束无关。HTTP 响应最多 64 MiB，超过则失败且不伪造结果。output_file 保存全部解码正文，不保存完整 API/config；权限 0600，新路径原子发布，不覆盖已有文件或符号链接。文件路径不是跨 Session 产物，完整报告仍由 Runtime Invocation 固定引用读取。
-
-退出 0=读取成功（含 failed、pending、缺正文和已明确标记的未知格式），1=HTTP/外层响应/本地写入失败，2=参数错误（未发请求），3=部署上下文缺失。判断完成须同时看 terminal/status 和产物内容，不能只看退出码或 succeeded。若引用/正文不匹配、结果缺失或未知，保留失败/未知证据，按需读取 turns/events，不用另一轮结果替代。

package/bundle/skills/df-agentrt/references/query-scope.md

@@ -1,30 +0,0 @@
-# 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 响应（`df-agentrt session get <session-id> --json`）；CLI 过滤仍然可以正常使用。
-

package/bundle/skills/df-agentrt/references/session-create.md

@@ -1,14 +0,0 @@
-# 创建幂等性
-
-创建结果不确定时，用稳定 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 的保留随之终止。
-

package/bundle/skills/df-task/references/environment.md

@@ -1,50 +0,0 @@
-# 环境与地址
-
-
-每次调用服务前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
-
-```text
-请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
-```
-
-环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
-
-| 目标环境 | 集群外访问地址 | 对应环境集群内地址 |
-| --- | --- | --- |
-| `local` | `http://127.0.0.1:8090` | 不适用 |
-| `dev` | `https://deepflowtask.dev.deepwisdomai.com` | `http://deepflowtask.deepflow.svc.cluster.local:8090` |
-| `prod` | `https://deepflowtask.deepwisdomai.com` | `http://deepflowtask.deepflow.svc.cluster.local:8090` |
-
-`prod` 指国内生产 `prod-cn`。集群内地址只在对应环境集群中访问；dev 与 prod 的 Service DNS 字符串相同，不能仅凭该字符串反查环境，也不能从本机直接访问它来代替生产入口。CLI 不会按环境名自动选址：本地调用须显式设置已选环境的地址；可以使用用户提供且已确认归属的 `--base-url`，地址与已选环境冲突时先澄清，连接失败不得改用其他环境。生产写操作仍只执行当前任务已授权的范围。
-
-本地操作 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` 由部署注入，绑定当前 Run 所属的事实服务；沿用它访问本 Task，不重新询问环境、不根据同名 Service DNS 猜成 dev，也不因业务需求中出现“生产/开发”就重定向流程服务。业务项目的目标环境与 DeepFlow 流程服务的部署环境分别核对。
-
-注入地址缺失或与当前流程已确认的部署环境冲突时，停止相关调用并说明缺口；不回退 localhost、不自行改地址或伪造身份。不在 Run 里时，先由用户选择环境，再按上表显式选址；内部 DNS 需要已确认的集群访问上下文。
-
-先用 `GET /healthz` 验证选定地址，再执行读写操作。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
-
-下面的示例还用到两个变量，同样由 runtime 注入，同样不要自己编：`DF_TASK_ID` 是你这次执行所属的 Task，`DF_RUN_ID` 是你自己这个 Run 的标识（写事实时 payload 里的 `run_id` 填它）。如果它们是空的，说明这次执行不是由推进器兑现唤起起来的 —— 别猜一个填进去，写一条 `summary` 说明情况。
-
-**在 Run 里一律加 `--json`。** 不加 `--json` 的输出是给人看的排版，字段随时会调整。
-
-```bash
-# 按本轮需要选择事实类型（选择标准见「读日志」）
-df-task facts "$DF_TASK_ID" --types user_message,artifact_published --json
-df-task facts "$DF_TASK_ID" --types user_message,artifact_published --after 128 --limit 100 --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
-```
-

package/bundle/skills/df-task/references/query-scope.md

@@ -1,49 +0,0 @@
-# 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 做鉴权。
-

package/bundle/skills/df-task/references/reading.md

@@ -1,9 +0,0 @@
-# CLI 读取契约
-
-`--fields` 只在 `get/facts --json` 可用，默认 `--json` 不变。get 顶层可选 `id,title,description,description_version,metadata,created_at,updated_at`；facts 每条可选 `seq,type,actor_kind,actor_id,payload,idempotency_key,created_at`。metadata/payload 允许点分对象路径；无数组下标、表达式、通配符或父子路径重叠。不存在的路径省略，直接选中的 null 保留；数值不经过浮点转换。facts 的 task_id、next_after_seq 及其他信封字段保留。没有业务摘要、排序或正文裁剪。
-
-`facts --all --output-file PATH --json` 可沿用 `--after/--types/--limit/--metadata-source/--metadata-query-key`。默认 page limit=200，max-pages=10，max-bytes=8388608；显式预算范围分别 1..100、1..67108864。字节预算按接纳前的 HTTP 响应计，超过预算的页整体不接纳，游标不跳过该页。页必须匹配 Task、严格递增，next_after_seq 必须等于该页末 seq；空页保留输入游标。
-
-清单字段：query（Task、地址、类型、过滤、起始游标、page limit）、complete、stop_reason、pages（接纳页数，含终止空页）、count、first_seq/last_seq（有事实时）、next_after_seq、type_counts、response_bytes、output_file、file_bytes、file_sha256。正文不会进入清单。文件包含 query、facts、complete、stop_reason、next_after_seq，权限 0600，原子发布且不覆盖。SHA 对应实际文件字节。
-
-stop_reason：empty_page 表示本次见到空页；page_limit/byte_limit 表示预算耗尽；request_error/invalid_page 表示失败。除 empty_page 外 complete=false 且退出 1；本地参数/路径预检错误退出 2（未发请求）。本地写入失败不返回伪造的成功清单。显式续读须保持过滤条件，使用已返回的 next_after_seq 和新的文件名；先前文件不会被补写。complete 不承诺事务快照或不存在晚提交。