@metagptx/deepflow-suite-cli 0.2.10 → 0.3.0

package/runtime/df-task/commands.mjs

@@ -0,0 +1,181 @@
+export const help = `df-task — DeepFlow Task fact log CLI
+
+Usage:
+  df-task ls [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task get <task-id> [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task create --title <text> [--description <text>] [--message <text>] [--metadata <json>]
+  df-task facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task append <task-id> --type <type> --file payload.json [--idempotency-key <k>]
+  df-task stream [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]
+  df-task title <task-id> --title <text>
+  df-task metadata <task-id> --metadata <json> [--metadata-source <source>] [--metadata-query-key <key>]
+
+Scheduling shorthands (each one is a wrapper around append):
+  df-task dispatch <task-id> --agent <name> --instruction <text> [--run <run-id>]
+  df-task wait <task-id> --on <what> --reason <text> [--waiting-run <run-id>]
+  df-task handoff <task-id> --ask <text> [--assignee <who>]
+
+Global options (before or after the command):
+  --base-url <url>   Service URL (or DF_TASK_BASE_URL)
+  --json             Machine-readable JSON output
+  help [command]     Show general or command help (-h / --help also supported)
+
+Environment:
+  DF_TASK_BASE_URL     Service URL, default http://127.0.0.1:8090
+  DF_TASK_ACTOR_KIND   Write identity: human | external | task_run | scheduler_run | driver
+  DF_TASK_ACTOR_ID     Write identity id, e.g. the current run id
+
+Facts are append-only. The API has no way to change or remove a fact, so neither does this CLI.
+`;
+export const commands = {
+  "ls": {
+    "usage": "ls [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "List tasks, newest first.",
+    "flags": [
+      "--limit",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": false,
+    "writes": false
+  },
+  "get": {
+    "usage": "get <task-id> [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read one task's identity.",
+    "flags": [
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": true,
+    "writes": false
+  },
+  "create": {
+    "usage": "create --title <text> [--description <text>] [--message <text>] [--metadata <json>]",
+    "description": "Create a task, optionally with its first user message in the same transaction.",
+    "flags": [
+      "--title",
+      "--description",
+      "--message",
+      "--metadata"
+    ],
+    "required": [
+      "--title"
+    ],
+    "needsID": false,
+    "writes": true
+  },
+  "facts": {
+    "usage": "facts <task-id> [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read one task's facts in seq order.",
+    "flags": [
+      "--after",
+      "--types",
+      "--limit",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": true,
+    "writes": false
+  },
+  "append": {
+    "usage": "append <task-id> --type <type> --file payload.json [--idempotency-key <k>]",
+    "description": "Append one fact from a JSON payload file.",
+    "flags": [
+      "--type",
+      "--file",
+      "--idempotency-key"
+    ],
+    "required": [
+      "--type",
+      "--file"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "stream": {
+    "usage": "stream [--after <seq>] [--types <a,b>] [--limit <n>] [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Read facts across all tasks from a cursor. One-shot pull, not a long connection.",
+    "flags": [
+      "--after",
+      "--types",
+      "--limit",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [],
+    "needsID": false,
+    "writes": false
+  },
+  "title": {
+    "usage": "title <task-id> --title <text>",
+    "description": "Change a task's title. Writes no fact.",
+    "flags": [
+      "--title"
+    ],
+    "required": [
+      "--title"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "metadata": {
+    "usage": "metadata <task-id> --metadata <json> [--metadata-source <source>] [--metadata-query-key <key>]",
+    "description": "Replace a task's metadata as human. Writes no fact.",
+    "flags": [
+      "--metadata",
+      "--metadata-source",
+      "--metadata-query-key"
+    ],
+    "required": [
+      "--metadata"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "dispatch": {
+    "usage": "dispatch <task-id> --agent <name> --instruction <text> [--run <run-id>]",
+    "description": "Append a dispatch intent. Without --run it asks for a new run; with --run it posts a message to that run.",
+    "flags": [
+      "--agent",
+      "--instruction",
+      "--run"
+    ],
+    "required": [
+      "--agent",
+      "--instruction"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "wait": {
+    "usage": "wait <task-id> --on <what> --reason <text> [--waiting-run <run-id>]",
+    "description": "Append a waiting reason. It is context for humans and the next scheduling run, not a gate for the driver.",
+    "flags": [
+      "--on",
+      "--reason",
+      "--waiting-run"
+    ],
+    "required": [
+      "--on",
+      "--reason"
+    ],
+    "needsID": true,
+    "writes": true
+  },
+  "handoff": {
+    "usage": "handoff <task-id> --ask <text> [--assignee <who>]",
+    "description": "Append a handoff to a human. Handing the ball back and asking a human to do a step are the same fact.",
+    "flags": [
+      "--ask",
+      "--assignee"
+    ],
+    "required": [
+      "--ask"
+    ],
+    "needsID": true,
+    "writes": true
+  }
+};

package/runtime/df-task/df-task.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { help, commands } from './commands.mjs';
+import { factTypes, actorKinds } from './protocol.mjs';
+
+const uuid = /^(?:urn:uuid:)?(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\})$/i;
+const valueFlags = new Set(['--base-url', ...Object.values(commands).flatMap((spec) => spec.flags)]);
+export function parse(args) {
+  const o = { command: '', args: [], values: {}, json: false, help: false };
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('-')) { if (!o.command) o.command = arg; else o.args.push(arg); continue; }
+    const equals = arg.indexOf('=');
+    const key = equals < 0 ? arg : arg.slice(0, equals);
+    if (seen.has(key)) throw Error(`duplicate option ${key}`);
+    seen.add(key);
+    if (['--help', '-h', '--json'].includes(key)) {
+      if (equals >= 0) throw Error(`${key} does not take a value`);
+      o[key === '--json' ? 'json' : 'help'] = true;
+    } else if (valueFlags.has(key)) {
+      if (equals < 0 && (i + 1 === args.length || args[i + 1].startsWith('--'))) throw Error(`${key} requires a value`);
+      o.values[key] = equals < 0 ? args[++i] : arg.slice(equals + 1);
+    } else throw Error(`unknown option ${key}`);
+  }
+  o.command ||= 'help';
+  if (o.command === 'help' && o.args.length === 1) { o.command = o.args.pop(); o.help = true; }
+  return o;
+}
+
+export function validate(o, env) {
+  const spec = Object.hasOwn(commands, o.command) ? commands[o.command] : undefined;
+  if (!spec) throw Error(`unknown command ${o.command}`);
+  for (const key of Object.keys(o.values)) if (key !== '--base-url' && !spec.flags.includes(key)) throw Error(`${key} is not supported by ${o.command}`);
+  for (const key of spec.required) if (!o.values[key]?.trim()) throw Error(`${o.command} requires ${key}`);
+  if (spec.needsID) {
+    if (o.args.length !== 1) throw Error(`${o.command} requires exactly one task-id`);
+    if (!uuid.test(o.args[0])) throw Error('task-id must be a UUID');
+  } else if (o.args.length) throw Error(`${o.command} does not accept positional arguments`);
+  for (const key of ['--type', '--types']) if (key in o.values) {
+    for (const raw of o.values[key].split(',')) {
+      const name = raw.trim();
+      if (!name) throw Error('--types must not contain an empty entry');
+      if (!factTypes.includes(name)) throw Error(`unknown fact type ${name}`);
+    }
+  }
+  if ('--run' in o.values && !o.values['--run'].trim()) throw Error('--run must not be empty');
+  if ('--metadata' in o.values) object(o.values['--metadata'], '--metadata must be a JSON object');
+  for (const key of ['--limit', '--after']) if (key in o.values) {
+    const raw = o.values[key];
+    if (!/^[+]?\d+$/.test(raw) || BigInt(raw) > 9223372036854775807n || (key === '--limit' && BigInt(raw) === 0n)) throw Error(`${key} must be a non-negative integer`);
+  }
+  if (spec.writes) {
+    if (!env.DF_TASK_ACTOR_KIND?.trim() || !env.DF_TASK_ACTOR_ID?.trim()) throw Error('writing a fact requires DF_TASK_ACTOR_KIND and DF_TASK_ACTOR_ID');
+    if (!actorKinds.includes(env.DF_TASK_ACTOR_KIND)) throw Error(`unknown DF_TASK_ACTOR_KIND ${env.DF_TASK_ACTOR_KIND}`);
+    if (o.command === 'metadata' && env.DF_TASK_ACTOR_KIND !== 'human') throw Error('metadata requires DF_TASK_ACTOR_KIND=human');
+  }
+}
+function object(raw, message) {
+  let value;
+  try { value = JSON.parse(raw); } catch { throw Error(message); }
+  if (!value || Array.isArray(value) || typeof value !== 'object') throw Error(message);
+  return value;
+}
+function query(values) {
+  const pairs = Object.entries(values).filter(([, value]) => value !== undefined && value !== '');
+  pairs.sort(([a], [b]) => a.localeCompare(b));
+  const q = new URLSearchParams(pairs).toString();
+  return q ? `?${q}` : '';
+}
+export async function requestFor(o) {
+  const v = o.values, c = o.command;
+  const path = o.args.length ? `/api/v1/tasks/${encodeURIComponent(o.args[0])}` : '/api/v1/tasks';
+  const metadata = { metadata_source: v['--metadata-source'], metadata_query_key: v['--metadata-query-key'] };
+  const post = (p, body) => ({ method: 'POST', path: p, body: JSON.stringify(body) });
+  if (c === 'ls') return { method: 'GET', path: path + query({ ...metadata, limit: v['--limit'] || '50' }) };
+  if (c === 'get') return { method: 'GET', path: path + query(metadata) };
+  if (c === 'facts' || c === 'stream') return { method: 'GET', path: (c === 'facts' ? `${path}/facts` : '/api/v1/facts') + query({ ...metadata, after_seq: v['--after'], types: v['--types'], limit: v['--limit'] }) };
+  // Preserve user JSON bytes, including integer precision and unknown fields.
+  if (c === 'create') return { method: 'POST', path, body: `{"title":${JSON.stringify(v['--title'])},"description":${JSON.stringify(v['--description'] || '')}${v['--message'] ? `,"first_message":${JSON.stringify(v['--message'])}` : ''}${v['--metadata'] ? `,"metadata":${v['--metadata']}` : ''}}` };
+  if (c === 'title') return post(`${path}/title`, { title: v['--title'] });
+  if (c === 'metadata') return { method: 'POST', path: `${path}/metadata${query(metadata)}`, body: `{"metadata":${v['--metadata']}}` };
+  if (c === 'append') {
+    const raw = await readFile(v['--file'], 'utf8');
+    object(raw, `${v['--file']} must contain a JSON object`);
+    return { method: 'POST', path: `${path}/facts`, body: `{"type":${JSON.stringify(v['--type'])},"payload":${raw}${v['--idempotency-key'] ? `,"idempotency_key":${JSON.stringify(v['--idempotency-key'])}` : ''}}` };
+  }
+  let type, payload;
+  if (c === 'dispatch') { type = 'dispatch_intent'; payload = { agent: v['--agent'], instruction: v['--instruction'], mode: v['--run'] ? 'message' : 'new_run', ...(v['--run'] ? { target_run_id: v['--run'] } : {}) }; }
+  if (c === 'wait') { type = 'waiting_reason'; payload = { waiting_on: v['--on'], reason: v['--reason'], ...(v['--waiting-run'] ? { waiting_run_id: v['--waiting-run'] } : {}) }; }
+  if (c === 'handoff') { type = 'handoff_to_human'; payload = { ask: v['--ask'], ...(v['--assignee'] ? { assignee: v['--assignee'] } : {}) }; }
+  return post(`${path}/facts`, { type, payload });
+}
+function human(command, data, stdout) {
+  const page = JSON.parse(data, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/.test(context.source) ? BigInt(context.source) : value) || {};
+  if (typeof page !== 'object' || Array.isArray(page) || (page.tasks != null && !Array.isArray(page.tasks)) || (page.facts != null && !Array.isArray(page.facts))) { stdout.write(pretty(data) + '\n'); return; }
+  if (command === 'ls') {
+    for (const task of page.tasks || []) stdout.write(`${task.id}  ${task.updated_at}  ${task.title}\n`);
+    if (!page.tasks?.length) stdout.write('No tasks.\n');
+  } else if (command === 'facts' || command === 'stream') {
+    for (const f of page.facts || []) {
+      const payload = Array.from(JSON.stringify(f.payload, (_key, value) => typeof value === 'bigint' ? JSON.rawJSON(value.toString()) : value));
+      const text = payload.length > 120 ? payload.slice(0, 117).join('') + '...' : payload.join('');
+      stdout.write(`${String(f.seq).padEnd(8)} ${f.created_at || ''}  ${f.task_id ? f.task_id + '  ' : ''}${(f.type || '').padEnd(20)} ${f.actor_kind || ''}:${f.actor_id || ''}  ${text}\n`);
+    }
+    stdout.write(`next_after_seq=${page.next_after_seq || 0}${command === 'stream' ? ` max_seq=${page.max_seq || 0}` : ''}\n`);
+  } else stdout.write(pretty(data) + '\n');
+}
+function pretty(raw) {
+  const tokens = raw.match(/"(?:\\.|[^"\\])*"|[{}\[\],:]|[^\s{}\[\],:]+/g) || [];
+  let level = 0, out = '';
+  const newline = () => '\n' + '  '.repeat(level);
+  tokens.forEach((token, i) => {
+    if (token === '{' || token === '[') { out += token; level++; if (tokens[i + 1] !== (token === '{' ? '}' : ']')) out += newline(); }
+    else if (token === '}' || token === ']') { level--; if (tokens[i - 1] !== (token === '}' ? '{' : '[')) out += newline(); out += token; }
+    else out += token === ',' ? ',' + newline() : token === ':' ? ': ' : token;
+  });
+  return out;
+}
+export async function run(args, { env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (args[0] === '--cli-version') {
+    let version = 'workspace';
+    try { version = JSON.parse(await readFile(new URL('./release.json', import.meta.url), 'utf8')).version; } catch {}
+    const report = { name: 'df-task', version, entry: fileURLToPath(import.meta.url) };
+    stdout.write((args.includes('--json') ? JSON.stringify(report) : `df-task ${version}`) + '\n');
+    return 0;
+  }
+  let o, base, req;
+  try {
+    o = parse(args);
+    if (o.command === 'help' && !o.args.length) { stdout.write(help); return 0; }
+    if (o.help) {
+      const spec = Object.hasOwn(commands, o.command) ? commands[o.command] : undefined; if (!spec) throw Error(`unknown command ${o.command}`);
+      stdout.write(`df-task ${spec.usage} [--base-url <url>] [--json]\n\n${spec.description}\n`); return 0;
+    }
+    validate(o, env);
+    base = o.values['--base-url'] || env.DF_TASK_BASE_URL || 'http://127.0.0.1:8090';
+    const url = new URL(base);
+    if (!['http:', 'https:'].includes(url.protocol) || url.search || url.hash || url.username || url.password) throw Error('invalid base URL');
+    req = await requestFor(o);
+  } catch (error) { stderr.write(error.message + '\n'); return 2; }
+  try {
+    const headers = req.body ? { 'Content-Type': 'application/json' } : {};
+    if (req.method !== 'GET') { headers['X-DF-Actor-Kind'] = env.DF_TASK_ACTOR_KIND; headers['X-DF-Actor-Id'] = env.DF_TASK_ACTOR_ID; }
+    const response = await fetch(base.replace(/\/+$/, '') + req.path, { method: req.method, body: req.body, headers, signal: AbortSignal.timeout(30000) });
+    const data = await response.text();
+    if (response.status >= 400) throw Error(`HTTP ${response.status}: ${data.trim()}`);
+    try { JSON.parse(data); } catch { throw Error('server returned invalid JSON'); }
+    if (o.json) stdout.write(data + '\n'); else human(o.command, data, stdout);
+    return 0;
+  } catch (error) { stderr.write(error.message + '\n'); return 1; }
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) process.exitCode = await run(process.argv.slice(2));

package/runtime/df-task/protocol.mjs

@@ -0,0 +1,3 @@
+// Generated by generate-protocol.mjs from internal/model/fact.go.
+export const factTypes = ["task_lifecycle","user_message","external_result","artifact_published","summary","help_requested","run_outcome","dispatch_intent","waiting_reason","handoff_to_human","adjudication","run_terminated","invocation_started","invocation_accepted","invocation_ended","attempt_failed"];
+export const actorKinds = ["human","external","task_run","scheduler_run","driver"];

package/runtime/df-task/release.json

@@ -0,0 +1 @@
+{"version":"0.3.0","project":"deepflow-task","sourceCommit":"3a8f5c8915cf5df74236eb4da693ac75f4c816a8","sourceDirty":false}

package/runtime/df-taskdriver/df-taskdriver.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const commands = { health: '存活探针：进程还在吗', ready: '就绪探针：能不能干活（未就绪时退出码 1）', locks: '当前哪些 Task 正在被处理、被谁', task: '这个 Task 为什么不动', metrics: '抓取指标，可按子串过滤', help: '打印这段用法' };
+export function displayWidth(text) {
+  return Array.from(text).reduce((width, char) => { const r = char.codePointAt(0); return width + ((r >= 0x1100 && r <= 0x115f) || (r >= 0x2e80 && r <= 0xa4cf) || (r >= 0xac00 && r <= 0xd7a3) || (r >= 0xf900 && r <= 0xfaff) || (r >= 0xfe30 && r <= 0xfe4f) || (r >= 0xff00 && r <= 0xff60) || (r >= 0xffe0 && r <= 0xffe6) ? 2 : 1); }, 0);
+}
+export const pad = (text, width) => text + ' '.repeat(Math.max(1, width - displayWidth(text)));
+function usage(out) {
+  out.write('df-taskdriver —— deepflow-task-driver 运维 CLI\n\n用法: df-taskdriver [选项] <子命令> [参数]\n\n子命令:\n');
+  for (const [name, description] of Object.entries(commands)) out.write(`  ${pad(name === 'task' ? 'task <task-id> [limit]' : name === 'metrics' ? 'metrics [过滤子串]' : name, 26)} ${description}\n`);
+  out.write('\n选项:\n  --base-url string  driver 实例的 ops 地址\n  --timeout duration  单次请求超时 (default 10s)\n  --json  原样输出实例返回的 JSON\n\n退出码: 0 肯定 / 1 实例给出否定回答 / 2 连不上或用法错误\n');
+}
+function duration(raw) {
+  if (raw === '0') return 0;
+  let total = 0, consumed = '';
+  for (const match of raw.matchAll(/(\d+(?:\.\d+)?)(ns|us|µs|μs|ms|s|m|h)/g)) {
+    consumed += match[0]; total += Number(match[1]) * { ns: 1e-6, us: 1e-3, 'µs': 1e-3, 'μs': 1e-3, ms: 1, s: 1000, m: 60000, h: 3600000 }[match[2]];
+  }
+  if (!consumed || consumed !== raw || !Number.isFinite(total)) throw Error(`invalid duration ${raw}`);
+  return total;
+}
+export function parse(args, env) {
+  const options = { args: [], base: env.DF_TASKDRIVER_BASE_URL || 'http://127.0.0.1:8081', timeout: 10000, json: false };
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith('-') || args[i] === '-') { options.args.push(args[i]); continue; }
+    if (args[i] === '--') { options.args.push(...args.slice(i + 1)); break; }
+    const [key, inline] = args[i].replace(/^-{1,2}/, '').split(/=(.*)/s);
+    if (key === 'help' || key === 'h') { options.help = true; break; }
+    if (key === 'json') { if (inline !== undefined && !['true', 'false'].includes(inline)) throw Error('invalid boolean value'); options.json = inline !== 'false'; continue; }
+    if (!['base-url', 'timeout'].includes(key)) throw Error(`flag provided but not defined: -${key}`);
+    const value = inline ?? args[++i]; if (value === undefined) throw Error(`flag needs an argument: -${key}`);
+    if (key === 'base-url') options.base = value; else options.timeout = duration(value);
+  }
+  return options;
+}
+const humanMS = (ms) => ms < 0 ? '未知' : `${(Number(ms || 0) / 1000).toFixed(1)}s`;
+const compact = (payload) => Object.keys(payload || {}).sort().map((key) => `${key}=${typeof payload[key] === 'object' ? JSON.stringify(payload[key]) : payload[key]}`).join(' ') || '{}';
+// Format tokens rather than re-encoding parsed numbers: seq values are int64.
+function pretty(raw) {
+  const tokens = raw.match(/"(?:\\.|[^"\\])*"|[{}\[\],:]|[^\s{}\[\],:]+/g) || [];
+  let level = 0, out = '';
+  const newline = () => '\n' + '  '.repeat(level);
+  tokens.forEach((token, i) => {
+    if (token === '{' || token === '[') { out += token; level++; if (tokens[i + 1] !== (token === '{' ? '}' : ']')) out += newline(); }
+    else if (token === '}' || token === ']') { level--; if (tokens[i - 1] !== (token === '}' ? '{' : '[')) out += newline(); out += token; }
+    else out += token === ',' ? ',' + newline() : token === ':' ? ': ' : token;
+  });
+  return out;
+}
+function human(command, body, status, out) {
+  const b = body || {};
+  if (command === 'health') out.write(`存活: ${b.status || ''}  instance=${b.instance_id || ''}\n`);
+  if (command === 'ready') out.write(status === 200 ? '就绪\n' : `未就绪: ${b.error || ''}\n`);
+  if (command === 'locks') {
+    if (status !== 200) out.write(`读取失败: ${b.error || ''}\n`);
+    else if (!b.count) out.write('当前没有任何 Task 被持锁\n');
+    else {
+      out.write(`${b.count} 个 Task 正在被处理\n`);
+      for (const lock of b.locks || []) out.write(`  ${lock.task_id}  holder=${lock.holder} (${lock.recognized ? '本实例' : '其他实例'})  剩余 ${humanMS(lock.remaining_ttl_ms)}\n`);
+    }
+  }
+  if (command === 'task') {
+    if (status !== 200) { out.write(`读取失败: ${b.error || ''}\n`); return; }
+    const d = b.decision || {};
+    out.write(`${b.task_id || ''}\n  结论: ${d.should_schedule ? '下一轮会调度' : '不会调度'} —— ${d.reason || ''}\n  事实: ${b.facts || 0} 条，max_seq=${b.max_seq || 0}\n`);
+    out.write(`  水位线: ${d.max_watermark || 0}，最大触发事实: ${d.max_trigger_seq || 0}，本轮锚点: ${d.anchor || 0}\n`);
+    out.write(`  失败预算: 组 ${d.budget_group || 0} 内 ${d.failures_in_budget_group || 0}/${d.failure_budget || 0} 次失败${d.budget_exhausted ? '（已耗尽，等人介入；发一条新的用户消息即可恢复）' : ''}\n`);
+    if (b.inflight?.length) {
+      out.write('  在飞唤起:\n');
+      for (const inv of b.inflight) out.write(`    ${inv.run_id} kind=${inv.run_kind} started_seq=${inv.started_seq || 0} intent_seq=${inv.intent_seq || 0} 水位线=${inv.watermark || 0} 锚点=${inv.anchor || 0}${inv.needs_replay ? '  [待重放]' : ''}\n`);
+    }
+    if (b.unfulfilled_intents?.length) {
+      out.write('  未兑现意图:\n');
+      for (const intent of b.unfulfilled_intents) out.write(`    seq=${intent.seq} ${compact(intent.payload)}\n`);
+    }
+    out.write(b.inflight?.length || b.unfulfilled_intents?.length ? '  驱动这边还有未了之事（见上方在飞唤起／未兑现意图），先看它们卡在哪一步\n' : d.should_schedule ? '  驱动这边没有未了之事，谓词已成立，下一拍就会起一轮调度——这一刻不用做什么\n' : '  驱动无未了之事，继续查上游（事实是否写入、调度智能体是否下发）\n');
+  }
+}
+export async function run(args, { env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (args[0] === '--cli-version') {
+    let version = 'workspace';
+    try { version = JSON.parse(await readFile(new URL('./release.json', import.meta.url), 'utf8')).version; } catch {}
+    const report = { name: 'df-taskdriver', version, entry: fileURLToPath(import.meta.url) };
+    stdout.write((args.includes('--json') ? JSON.stringify(report) : `df-taskdriver ${version}`) + '\n');
+    return 0;
+  }
+  let o, command, rest, path;
+  try {
+    o = parse(args, env); [command, ...rest] = o.args;
+    if (o.help || command === 'help') { usage(stdout); return 0; }
+    if (!command || !Object.hasOwn(commands, command)) { if (command) stderr.write(`未知子命令: ${command}\n\n`); usage(stderr); return 2; }
+    path = { health: '/healthz', ready: '/readyz', locks: '/debug/locks', metrics: '/metrics' }[command];
+    if (command === 'task') {
+      if (!rest.length) throw Error('用法: df-taskdriver task <task-id> [limit]');
+      if (rest[1] !== undefined && (!/^\+?\d+$/.test(rest[1]) || BigInt(rest[1]) < 1n || BigInt(rest[1]) > 9223372036854775807n)) throw Error(`limit 必须是正整数: ${rest[1]}`);
+      path = `/debug/tasks/${encodeURIComponent(rest[0])}${rest[1] !== undefined ? `?limit=${encodeURIComponent(rest[1])}` : ''}`;
+    }
+  } catch (error) { stderr.write(`错误: ${error.message}\n`); return 2; }
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  const timer = o.timeout ? setTimeout(stop, o.timeout) : undefined;
+  try {
+    const response = await fetch(o.base.replace(/\/+$/, '') + path, { signal: controller.signal });
+    const chunks = []; let length = 0;
+    for await (const chunk of response.body) { length += chunk.length; if (length > 8 * 1024 * 1024) throw Error('response exceeds 8 MiB'); chunks.push(chunk); }
+    const data = Buffer.concat(chunks).toString('utf8'), affirmative = response.status >= 200 && response.status < 300;
+    let body, valid = true;
+    if (command !== 'metrics') { try { body = JSON.parse(data, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/.test(context.source) ? BigInt(context.source) : value); } catch { valid = false; } }
+    if (command === 'metrics') {
+      stdout.write(rest.length ? data.split('\n').filter((line) => line.includes(rest[0])).join('\n') + '\n' : data);
+      return affirmative ? 0 : 1;
+    }
+    if (o.json) {
+      // Raw server JSON preserves unknown fields and integer precision.
+      stdout.write(valid ? pretty(data) + '\n' : data + (data.endsWith('\n') ? '' : '\n'));
+      return affirmative ? valid ? 0 : 2 : 1;
+    }
+    if (!valid || (body !== null && (typeof body !== 'object' || Array.isArray(body)))) {
+      stderr.write(`错误: 解析 ${path} 的响应失败（HTTP ${response.status}，响应体前 200 字节: ${Array.from(data.trim()).slice(0, 200).join('')}）\n`);
+      return affirmative ? 2 : 1;
+    }
+    human(command, body, response.status, stdout);
+    return command === 'ready' ? response.status === 200 ? 0 : 1 : affirmative ? 0 : 1;
+  } catch (error) { stderr.write(`错误: 请求 ${o.base} 失败: ${error.message}（检查 --base-url / DF_TASKDRIVER_BASE_URL）\n`); return 2; }
+  finally { clearTimeout(timer); process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop); }
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) process.exitCode = await run(process.argv.slice(2));

package/runtime/df-taskdriver/release.json

@@ -0,0 +1 @@
+{"version":"0.3.0","project":"deepflow-task-driver","sourceCommit":"ab582505c8d60a99c8d2939c3d58b31803a8a229","sourceDirty":false}