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

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

@@ -0,0 +1,167 @@
+#!/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';
+import { validateReadOptions, projectResponse, readAllFacts, readResponse } from './read.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).filter((flag) => flag !== '--all')]);
+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 (key === '--all') {
+      if (equals >= 0) throw Error(`${key} does not take a value`);
+      o.values[key] = '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');
+  }
+  validateReadOptions(o);
+}
+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, initialRequest;
+  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');
+    initialRequest = await requestFor(o);
+  } catch (error) { stderr.write(error.message + '\n'); return 2; }
+  const request = async (options, limit = 0) => {
+    const req = options === o ? initialRequest : await requestFor(options);
+    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 readResponse(response, limit);
+    if (response.status >= 400) throw Error(`HTTP ${response.status}: ${data.trim()}`);
+    try { JSON.parse(data); } catch { throw Error('server returned invalid JSON'); }
+    return data;
+  };
+  if (o.values['--all']) return readAllFacts(o, base, request, stdout, stderr);
+  try {
+    let data = await request(o, '--fields' in o.values ? 64 << 20 : 0);
+    if ('--fields' in o.values) data = projectResponse(o.command, data, o.values['--fields'].split(','));
+    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/read.mjs

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdtemp, open, link, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+// Retain every numeric token verbatim, including values outside JS precision.
+export const decodeRaw = (raw) => JSON.parse(raw, (_key, value, context) => typeof value === 'number' ? JSON.rawJSON(context.source) : value);
+export const encodeRaw = (value) => JSON.stringify(value);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) && !JSON.isRawJSON(value);
+const seq = (value) => {
+  if (!JSON.isRawJSON(value) || !/^-?\d+$/.test(value.rawJSON)) throw Error('invalid facts sequence');
+  const n = BigInt(value.rawJSON);
+  if (n < 0n || n > 9223372036854775807n) throw Error('invalid facts sequence');
+  return n;
+};
+const rawSeq = (n) => JSON.rawJSON(BigInt(n).toString());
+
+export function validateReadOptions(o) {
+  const v = o.values;
+  if ('--fields' in v) {
+    if (!o.json) throw Error('--fields requires --json');
+    const roots = o.command === 'get' ? ['id', 'title', 'description', 'description_version', 'metadata', 'created_at', 'updated_at'] : ['seq', 'type', 'actor_kind', 'actor_id', 'payload', 'idempotency_key', 'created_at'];
+    const paths = v['--fields'].split(',');
+    paths.forEach((field, i) => {
+      const parts = field.split('.');
+      if (!roots.includes(parts[0]) || (parts.length > 1 && !['metadata', 'payload'].includes(parts[0]))) throw Error(`unsupported field path ${JSON.stringify(field)} for ${o.command}`);
+      if (parts.some((part) => !part || part.trim() !== part || /[\[\]*\/\\\t\r\n]/.test(part))) throw Error(`invalid object field path ${JSON.stringify(field)}`);
+      if (paths.slice(0, i).some((earlier) => earlier === field || earlier.startsWith(field + '.') || field.startsWith(earlier + '.'))) throw Error('overlapping field paths');
+    });
+  }
+  const all = '--all' in v;
+  if (all && (!o.json || !v['--output-file']?.trim() || '--fields' in v)) throw Error('--all requires --json and --output-file, and cannot be combined with --fields');
+  for (const flag of ['--output-file', '--max-pages', '--max-bytes']) if (flag in v && !all) throw Error(`${flag} requires --all`);
+  for (const [flag, max] of [['--max-pages', 100], ['--max-bytes', 64 << 20]]) {
+    if (flag in v && (!/^\+?\d+$/.test(v[flag]) || BigInt(v[flag]) < 1n || BigInt(v[flag]) > BigInt(max))) throw Error(`${flag} must be between 1 and ${max}`);
+  }
+}
+
+function projectObject(source, paths) {
+  if (!isObject(source)) throw Error('expected a JSON object for field selection');
+  const selected = Object.create(null), children = new Map();
+  for (const field of paths) {
+    const [root, ...parts] = field.split('.');
+    if (parts.length) { if (!children.has(root)) children.set(root, []); children.get(root).push(parts.join('.')); }
+    else if (Object.hasOwn(source, root)) selected[root] = source[root];
+  }
+  for (const [root, subpaths] of children) {
+    if (!Object.hasOwn(source, root) || !isObject(source[root])) continue;
+    const projected = projectObject(source[root], subpaths);
+    if (Object.keys(projected).length) selected[root] = projected;
+  }
+  return selected;
+}
+export function projectResponse(command, raw, paths) {
+  const data = decodeRaw(raw);
+  if (command === 'get') return encodeRaw(projectObject(data, paths));
+  if (!isObject(data) || !Array.isArray(data.facts)) throw Error('expected facts array');
+  data.facts = data.facts.map((fact) => projectObject(fact, paths));
+  return encodeRaw(data);
+}
+const normalizedID = (id) => typeof id === 'string' ? id.toLowerCase().replace(/^urn:uuid:/, '').replace(/[{}-]/g, '') : '';
+export function validateFactPage(raw, taskID, after) {
+  const page = decodeRaw(raw);
+  if (!isObject(page) || !Array.isArray(page.facts) || !Object.hasOwn(page, 'next_after_seq')) throw Error('invalid facts page identity, facts or cursor');
+  if (!/^[0-9a-f]{32}$/.test(normalizedID(page.task_id)) || normalizedID(page.task_id) !== normalizedID(taskID)) throw Error('facts page task_id does not match query');
+  let last = after;
+  for (const fact of page.facts) {
+    if (!isObject(fact) || typeof fact.type !== 'string' || !fact.type || seq(fact.seq) <= last) throw Error(`facts page is not strictly ordered after ${after}`);
+    last = seq(fact.seq);
+  }
+  if (seq(page.next_after_seq) !== last) throw Error(`facts cursor does not match last seq ${last}`);
+  return { facts: page.facts, next: last };
+}
+export async function readResponse(response, limit = 0) {
+  if (!limit) return response.text();
+  let bytes = 0; const chunks = [];
+  for await (const chunk of response.body) {
+    bytes += chunk.length;
+    if (bytes > limit) throw Object.assign(Error('read byte budget exhausted'), { byteLimit: true });
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export async function readAllFacts(o, baseURL, request, stdout, stderr) {
+  const output = path.resolve(o.values['--output-file']);
+  let temp;
+  try {
+    try { await lstat(output); throw Error(`output file must not exist: ${output}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    temp = await mkdtemp(path.join(path.dirname(output), '.task-facts-'));
+  } catch (error) { stderr.write(error.message + '\n'); return 2; }
+  try {
+    const query = { task_id: o.args[0], base_url: baseURL, after_seq: '0', limit: '200' };
+    for (const flag of ['--after', '--types', '--limit', '--metadata-source', '--metadata-query-key']) if (flag in o.values) query[flag === '--after' ? 'after_seq' : flag.slice(2).replaceAll('-', '_')] = o.values[flag];
+    const manifest = { query, complete: false, stop_reason: 'page_limit', pages: 0, count: 0, next_after_seq: rawSeq(query.after_seq), type_counts: Object.create(null), response_bytes: 0, output_file: output };
+    const facts = [], budget = Number(o.values['--max-bytes'] || (8 << 20));
+    let cursor = BigInt(query.after_seq);
+    for (let i = 0; i < Number(o.values['--max-pages'] || 10); i++) {
+      const remaining = budget - manifest.response_bytes;
+      if (remaining <= 0) { manifest.stop_reason = 'byte_limit'; break; }
+      let raw, page;
+      try { raw = await request({ ...o, values: { ...o.values, '--after': String(cursor) } }, remaining); }
+      catch (error) { manifest.stop_reason = error.byteLimit ? 'byte_limit' : 'request_error'; stderr.write(error.message + '\n'); break; }
+      manifest.response_bytes += Buffer.byteLength(raw);
+      try { page = validateFactPage(raw, o.args[0], cursor); }
+      catch (error) { manifest.stop_reason = 'invalid_page'; stderr.write(error.message + '\n'); break; }
+      manifest.pages++;
+      if (!page.facts.length) { manifest.complete = true; manifest.stop_reason = 'empty_page'; break; }
+      for (const fact of page.facts) {
+        if (!manifest.count) manifest.first_seq = fact.seq;
+        manifest.last_seq = fact.seq;
+        manifest.type_counts[fact.type] = (manifest.type_counts[fact.type] || 0) + 1;
+        manifest.count++;
+      }
+      facts.push(...page.facts); cursor = page.next; manifest.next_after_seq = rawSeq(cursor);
+    }
+    const data = Buffer.from(encodeRaw({ query, facts, complete: manifest.complete, stop_reason: manifest.stop_reason, next_after_seq: manifest.next_after_seq }));
+    const staging = path.join(temp, 'facts.json'), file = await open(staging, 'wx', 0o600);
+    try { await file.writeFile(data); } finally { await file.close(); }
+    await link(staging, output);
+    manifest.file_bytes = data.length; manifest.file_sha256 = createHash('sha256').update(data).digest('hex');
+    stdout.write(encodeRaw(manifest) + '\n');
+    if (!manifest.complete) { stderr.write(`incomplete facts read: ${manifest.stop_reason}; next_after_seq=${cursor}\n`); return 1; }
+    return 0;
+  } catch (error) { stderr.write(error.message + '\n'); return 1; }
+  finally { await rm(temp, { recursive: true, force: true }); }
+}

package/runtime/df-task/release.json

@@ -0,0 +1 @@
+{"version":"0.3.1","project":"deepflow-task","sourceCommit":"a5b9064298158aad2fef2a67f0baa0a638c89f4b","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.1","project":"deepflow-task-driver","sourceCommit":"c05efdc13dfd0d7a9043007f7421dbd1ac6daab2","sourceDirty":false}

package/runtime/{df-workbench.mjs → df-workbench/df-workbench.mjs}

@@ -3,7 +3,8 @@
 import { randomUUID, createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { basename } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
 
 const DEFAULT_BASE_URL = "http://127.0.0.1:8793";
 const MAX_MESSAGE_LENGTH = 20000;
@@ -467,6 +468,7 @@ task create/send 可重复传入 --attachment-id <id>，每次最多 10 个。
   DF_WORKBENCH_BASE_URL       Workbench 根地址，默认 http://127.0.0.1:8793
   DF_WORKBENCH_TOKEN          OIDC 环境使用的 personal token
   DF_WORKBENCH_WORKSPACE_ID   当前工作区覆盖值
+  Token 获取：公司账号登录 → 个人设置 → 个人 Token
   --base-url <url>             覆盖 Workbench 根地址
   --workspace <id>             覆盖当前工作区
   --expected-actor <user-id>    固定操作身份；身份变化时停止请求
@@ -769,13 +771,20 @@ async function run(options) {
 }
 
 export async function main(argv = process.argv.slice(2), env = process.env) {
+  if (argv[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-workbench', version, entry: fileURLToPath(import.meta.url) };
+    process.stdout.write((argv.includes('--json') ? JSON.stringify(report) : `df-workbench ${version}`) + '\n');
+    return;
+  }
   const options = parseArgs(argv, env);
   await run(options);
 }
 
 if (
   process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
+  fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
 ) {
   main().catch((error) => {
     if (error instanceof UsageError) {

package/runtime/df-workbench/release.json

@@ -0,0 +1 @@
+{"version":"0.3.1","project":"deepflow-workbench","sourceCommit":"b83963f15f4ed187164464dddbfd2ea460f52971","sourceDirty":false}

package/scripts/build-package.mjs

@@ -1,26 +1,30 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { cp, mkdir, rm, readFile } from "node:fs/promises";
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chmod, cp, mkdir, rm, readFile, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { assembleBundle } from '../src/bundle.mjs';
+import { loadManifest } from '../src/manifest.mjs';
 
-import { assembleBundle } from "../src/bundle.mjs";
-import { buildRuntimePackages } from "../src/runtime-build.mjs";
-
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const workspaceRoot = path.resolve(packageRoot, "../..");
-const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
-await assembleBundle({
-  workspaceRoot,
-  outputDir: path.join(packageRoot, "bundle"),
-  manifestPath: path.join(packageRoot, "manifest.json"),
-});
-await rm(path.join(packageRoot, "runtime"), { recursive: true, force: true });
-await mkdir(path.join(packageRoot, "runtime"), { recursive: true });
-await cp(
-  path.join(workspaceRoot, "deepflow-workbench", "cli", "df-workbench.mjs"),
-  path.join(packageRoot, "runtime", "df-workbench.mjs"),
-);
-await buildRuntimePackages({
-  workspaceRoot,
-  outputRoot: path.join(packageRoot, "platform-packages"),
-  version: packageJson.version,
-});
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const workspaceRoot = path.resolve(packageRoot, '../..');
+const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+const manifest = await loadManifest(path.join(packageRoot, 'manifest.json'));
+if (manifest.version !== packageJson.version) throw Error('Manifest and npm package versions differ');
+await promisify(execFile)(process.execPath, ['cli/generate-protocol.mjs', '--check'], { cwd: path.join(workspaceRoot, 'deepflow-task') });
+await assembleBundle({ workspaceRoot, outputDir: path.join(packageRoot, 'bundle'), manifestPath: path.join(packageRoot, 'manifest.json') });
+const runtime = path.join(packageRoot, 'runtime');
+await rm(runtime, { recursive: true, force: true });
+await mkdir(runtime, { recursive: true });
+for (const cli of manifest.clis) {
+  const target = path.join(runtime, cli.name);
+  await cp(path.join(workspaceRoot, cli.project, 'cli'), target, {
+    recursive: true,
+    filter: (source) => !/(?:[\\/]contract(?:[\\/]|$)|\.test\.mjs$|[\\/]generate-protocol\.mjs$)/.test(source),
+  });
+  const { stdout } = await promisify(execFile)('git', ['rev-parse', 'HEAD'], { cwd: path.join(workspaceRoot, cli.project) });
+  const { stdout: status } = await promisify(execFile)('git', ['status', '--porcelain'], { cwd: path.join(workspaceRoot, cli.project) });
+  await writeFile(path.join(target, 'release.json'), JSON.stringify({ version: packageJson.version, project: cli.project, sourceCommit: stdout.trim(), sourceDirty: !!status.trim() }) + '\n');
+  await chmod(path.join(target, path.basename(cli.entry)), 0o755);
+  if (cli.name === 'df-agentrt') await chmod(path.join(target, 'agentrt.mjs'), 0o755);
+}

package/src/bundle.mjs

@@ -65,7 +65,10 @@ async function assembleInto({ workspaceRoot, outputDir, manifestPath }) {
       throw new Error(`missing or empty Skill source: ${skillFile}`);
     }
     const destination = path.join(outputDir, "skills", skill.name);
-    await cp(skill.sourcePath, destination, { recursive: true, dereference: false });
+    await cp(skill.sourcePath, destination, {
+      recursive: true, dereference: false,
+      filter: (source) => !/(?:_test\.go$|\.test\.mjs$|[\\/]__pycache__(?:[\\/]|$))/.test(source),
+    });
     skills.push({
       name: skill.name,
       source: skill.source,