vps-work 2.4.1 → 2.5.1

package/dist/packages/vps-work/src/utils/cli-option-helpers.js

@@ -0,0 +1,52 @@
+import { VertuError } from '../core/errors.js';
+export function resolveModelAlias(modelAlias, raw) {
+    if (!modelAlias) {
+        return;
+    }
+    const canonicalCamel = modelAlias.camelKey;
+    const canonicalFile = `${canonicalCamel}File`;
+    const aliasValue = raw['model'];
+    const aliasFile = raw['modelFile'];
+    if (aliasValue !== undefined && aliasFile !== undefined) {
+        throw new VertuError('--model and --model-file are mutually exclusive; pass only one.');
+    }
+    if (aliasValue !== undefined) {
+        if (raw[canonicalCamel] !== undefined) {
+            throw new VertuError(`--model and --${modelAlias.canonicalFlagName} are mutually exclusive; pass only one.`);
+        }
+        raw[canonicalCamel] = aliasValue;
+        delete raw['model'];
+    }
+    if (aliasFile !== undefined) {
+        if (raw[canonicalFile] !== undefined) {
+            throw new VertuError(`--model-file and --${modelAlias.canonicalFlagName}-file are mutually exclusive; pass only one.`);
+        }
+        raw[canonicalFile] = aliasFile;
+        delete raw['modelFile'];
+    }
+}
+export function pickPositionalOption(derived) {
+    const requiredStrings = derived.filter((o) => o.required && o.kind === 'string');
+    if (requiredStrings.length !== 1) {
+        return null;
+    }
+    return requiredStrings[0] ?? null;
+}
+export function pickModelAliasTarget(derived) {
+    const keys = new Set(derived.map((o) => o.key));
+    if (keys.has('model')) {
+        return null;
+    }
+    const hasModelName = keys.has('model_name');
+    const hasResModel = keys.has('res_model');
+    if (hasModelName && hasResModel) {
+        return null;
+    }
+    if (hasModelName) {
+        return { schemaKey: 'model_name', camelKey: 'modelName', canonicalFlagName: 'model-name' };
+    }
+    if (hasResModel) {
+        return { schemaKey: 'res_model', camelKey: 'resModel', canonicalFlagName: 'res-model' };
+    }
+    return null;
+}

package/dist/packages/vps-work/src/utils/frontmatter.js

@@ -0,0 +1,26 @@
+import YAML from 'yaml';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function parseFrontmatter(source) {
+    const match = FRONTMATTER_RE.exec(source);
+    if (!match) {
+        return { data: {}, body: source, hadFrontmatter: false };
+    }
+    const yamlBlock = match[1] ?? '';
+    let data = {};
+    try {
+        const parsed = YAML.parse(yamlBlock);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            data = parsed;
+        }
+    }
+    catch {
+        data = {};
+    }
+    const body = source.slice(match[0].length);
+    return { data, body, hadFrontmatter: true };
+}
+export function stringifyFrontmatter(data, body) {
+    const yaml = YAML.stringify(data, { lineWidth: 0 }).trimEnd();
+    const trimmedBody = body.startsWith('\n') ? body.slice(1) : body;
+    return `---\n${yaml}\n---\n\n${trimmedBody}`;
+}

package/dist/packages/vps-work/src/utils/normalize-argv.js

@@ -0,0 +1,51 @@
+/**
+ * Rewrite long-flag tokens that use snake_case (e.g. `--start_date`) into the
+ * kebab-case form (`--start-date`) that commander actually has registered.
+ *
+ * Why: server-side `parameters_schema` keys are snake_case (Python/Odoo
+ * convention), and we expose them as kebab-case CLI flags via
+ * `schema-to-options.toFlagName`. AI agents and humans reading the schema
+ * directly often type the snake_case form first; commander then rejects it
+ * with `unknown option '--start_date' (Did you mean --start-date?)`. Rather
+ * than burning a retry/round-trip on every such typo, normalize at the argv
+ * boundary so both spellings work transparently.
+ *
+ * Rules:
+ *   - Only long flags are touched (`--name`, `--name=value`); short flags and
+ *     positional values pass through unchanged.
+ *   - Anything after the standard `--` end-of-options sentinel is preserved
+ *     verbatim, so payload values like `--` `value_with_underscore` are safe.
+ *   - The value half of `--flag=value` is preserved verbatim — only the flag
+ *     name (left of the first `=`) is rewritten.
+ *   - Tokens without an underscore in the flag name are returned by reference
+ *     to keep the common path allocation-free.
+ */
+export function normalizeSnakeFlags(argv) {
+    const out = [];
+    let passthrough = false;
+    for (const tok of argv) {
+        if (passthrough) {
+            out.push(tok);
+            continue;
+        }
+        if (tok === '--') {
+            passthrough = true;
+            out.push(tok);
+            continue;
+        }
+        out.push(rewriteLongFlag(tok));
+    }
+    return out;
+}
+function rewriteLongFlag(tok) {
+    // Long flags must start with exactly two dashes followed by an alnum char.
+    // We deliberately reject `---foo` and `--=value` to match commander's parser.
+    if (!tok.startsWith('--') || tok.length < 3)
+        return tok;
+    const eq = tok.indexOf('=');
+    const name = eq === -1 ? tok.slice(2) : tok.slice(2, eq);
+    if (!/^[A-Za-z0-9][\w-]*$/.test(name) || !name.includes('_'))
+        return tok;
+    const rewritten = `--${name.replace(/_/g, '-')}`;
+    return eq === -1 ? rewritten : `${rewritten}${tok.slice(eq)}`;
+}

package/dist/packages/vps-work/src/utils/parse-json-arg.js

@@ -0,0 +1,85 @@
+import { VertuError } from '../core/errors.js';
+/**
+ * Parse a CLI-supplied JSON string and, on failure, surface a PowerShell-aware
+ * diagnostic that tells the user exactly which escape hatch to use.
+ *
+ * Why this exists:
+ *   `--params '{"k":"v"}'` looks fine in bash, but Windows PowerShell 5.1
+ *   strips the inner double quotes when forwarding to a native command, so
+ *   Node receives `{k:v}` and `JSON.parse` throws
+ *   `Expected property name or '}' in JSON at position 1`. Without a hint,
+ *   users (and AI agents) read the message literally and retry the same shape.
+ *
+ * Heuristic: if the raw input starts with `{`/`[` *and* contains **no** `"`
+ * characters anywhere, we are nearly certain the shell stripped quotes. In
+ * that case we attach a strong hint that names `PowerShell 5.1` explicitly
+ * (so the keyword shows up in searches) and lists three battle-tested
+ * workarounds: a `--<flag>-file` companion, the inline `@<path>` shorthand,
+ * and `@-` stdin piping. Outside the heuristic we still emit a weak hint
+ * pointing at the same escape hatches, because malformed JSON has the same
+ * fixes regardless of which shell mangled it.
+ *
+ * We deliberately do **not** attempt to repair stripped-quote input:
+ * `{k:1}` could mean `{"k":1}` or `{"k":"1"}` and auto-guessing trains the
+ * wrong habit. An explicit error with concrete fixes is the right teach.
+ */
+export function parseJsonArg(raw, label, opts = {}) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw buildJsonParseError(raw, label, opts, err.message);
+    }
+    if (opts.requireObject) {
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new VertuError(`${label} must decode to a JSON object (got ${describeValue(parsed)}).`);
+        }
+    }
+    return parsed;
+}
+function buildJsonParseError(raw, label, opts, jsonErrorMessage) {
+    const fileFlag = opts.fileFlagSuggestion ?? `${label}-file`;
+    const looksMangledByShell = detectStrippedQuotes(raw);
+    const exampleSkillKey = label === '--params' ? 'sales' : '<command>';
+    const inlineCmd = label === '--params'
+        ? `vps-work ${exampleSkillKey} +dept-breakdown ${label} @./payload.json`
+        : `vps-work … ${label} @./payload.json`;
+    const fileCmd = label === '--params'
+        ? `vps-work ${exampleSkillKey} +dept-breakdown ${fileFlag} ./payload.json`
+        : `vps-work … ${fileFlag} ./payload.json`;
+    const stdinCmd = label === '--params'
+        ? `Get-Content ./payload.json | vps-work ${exampleSkillKey} +dept-breakdown ${label} @-`
+        : `Get-Content ./payload.json | vps-work … ${label} @-`;
+    const lines = [];
+    lines.push(`Invalid ${label} JSON: ${jsonErrorMessage}`);
+    if (looksMangledByShell) {
+        lines.push('');
+        lines.push('Your shell likely stripped the inner double quotes (common on Windows PowerShell 5.1).');
+    }
+    lines.push('');
+    lines.push('Use any of the quoting-safe forms:');
+    lines.push(`  ${fileCmd}`);
+    lines.push(`  ${inlineCmd}`);
+    lines.push(`  ${stdinCmd}`);
+    const hint = looksMangledByShell
+        ? `PowerShell strips quotes from native-command args; pass payloads via ${fileFlag} or @file instead.`
+        : `Pass payloads via ${fileFlag} or @file to bypass shell quoting.`;
+    return new VertuError(lines.join('\n'), { hint });
+}
+function detectStrippedQuotes(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return false;
+    const first = trimmed[0];
+    if (first !== '{' && first !== '[')
+        return false;
+    return !trimmed.includes('"');
+}
+function describeValue(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}

package/dist/packages/vps-work/src/utils/prompt.js

@@ -0,0 +1,46 @@
+import { checkbox, confirm, input, password } from '@inquirer/prompts';
+export function isInteractive() {
+    return process.stdout.isTTY === true && process.stdin.isTTY === true;
+}
+export async function promptText(message, defaultValue) {
+    if (!isInteractive()) {
+        if (defaultValue !== undefined)
+            return defaultValue;
+        throw new Error(`Missing required value (${message}); stdin is not a TTY.`);
+    }
+    return input({ message, default: defaultValue });
+}
+export async function promptSecret(message) {
+    if (!isInteractive()) {
+        throw new Error(`Missing required secret (${message}); stdin is not a TTY.`);
+    }
+    return password({ message, mask: '*' });
+}
+export async function promptConfirm(message, defaultValue = true) {
+    if (!isInteractive())
+        return defaultValue;
+    return confirm({ message, default: defaultValue });
+}
+export async function promptCheckbox(message, choices, opts = {}) {
+    if (!isInteractive()) {
+        // 非交互场景：返回所有 checked === true 的选项作为兜底，调用方应自己保证有合理 default。
+        return choices.filter((c) => c.checked === true).map((c) => c.value);
+    }
+    return checkbox({
+        message,
+        choices,
+        pageSize: opts.pageSize ?? Math.min(20, Math.max(5, choices.length)),
+        required: opts.required ?? false,
+        loop: opts.loop ?? false,
+    });
+}
+export function normalizeBaseUrl(value) {
+    let trimmed = value.trim();
+    if (!trimmed)
+        throw new Error('base URL cannot be empty');
+    trimmed = trimmed.replace(/\/+$/, '');
+    if (!/^https?:\/\//i.test(trimmed)) {
+        throw new Error(`base URL must start with http(s)://: ${value}`);
+    }
+    return trimmed;
+}

package/dist/packages/vps-work/src/utils/read-text.js

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+const UTF8_BOM = '\uFEFF';
+/**
+ * Read a UTF-8 text file and strip a leading BOM if present.
+ *
+ * Why: Windows PowerShell's `Out-File`, `Set-Content`, and `>` redirection
+ * write UTF-8 with a BOM by default. `JSON.parse` then fails with
+ * `Unexpected token '\ufeff'`, forcing every PowerShell caller to remember the
+ * `[System.IO.File]::WriteAllBytes(..., [Text.Encoding]::UTF8.GetBytes(...))`
+ * incantation. Stripping the BOM at every file-input boundary removes that
+ * footgun without affecting bash/zsh callers (they don't write a BOM) or
+ * compliant payloads (a leading BOM is invalid in RFC 8259 JSON anyway).
+ *
+ * Use this helper instead of `fs.readFile(path, 'utf8')` for any file whose
+ * contents may originate from a user, agent, or external IDE.
+ */
+export async function readUtf8File(path) {
+    const text = await readFile(path, 'utf8');
+    return stripBom(text);
+}
+export function stripBom(text) {
+    return text.startsWith(UTF8_BOM) ? text.slice(UTF8_BOM.length) : text;
+}
+/**
+ * Read process stdin to end as UTF-8 text (BOM stripped).
+ *
+ * Used by `@-` and `--<flag>-file -` to pipe payloads from upstream commands
+ * without persisting to a temp file — the cleanest way to bypass shell quoting
+ * (especially Windows PowerShell 5.1's native-command argument mangling).
+ *
+ * If the stream is a TTY we surface a clear error rather than blocking forever;
+ * callers should only request stdin when an upstream `|` is in play.
+ */
+export async function readStdinText() {
+    const stdin = process.stdin;
+    if (stdin.isTTY) {
+        throw new Error('refused to read stdin: no data piped (stdin is a TTY)');
+    }
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk));
+    }
+    return stripBom(Buffer.concat(chunks).toString('utf8'));
+}

package/dist/packages/vps-work/src/utils/schema-to-options.js

@@ -0,0 +1,307 @@
+import { parseJsonArg } from './parse-json-arg.js';
+const PRIMITIVE_KINDS = new Set(['string', 'integer', 'number', 'boolean']);
+function pickType(prop) {
+    const t = prop.type;
+    if (Array.isArray(t)) {
+        const firstStr = t.find((x) => x !== 'null');
+        return typeof firstStr === 'string' ? firstStr : 'json';
+    }
+    if (typeof t === 'string')
+        return t;
+    return 'json';
+}
+function toFlagName(key) {
+    return key.replace(/_/g, '-').replace(/[^a-zA-Z0-9-]/g, '');
+}
+function buildDescription(prop, kind, itemKind) {
+    const parts = [];
+    if (prop.description)
+        parts.push(prop.description);
+    if (prop.enum && prop.enum.length)
+        parts.push(`enum: ${JSON.stringify(prop.enum)}`);
+    if (kind === 'array') {
+        parts.push(itemKind && itemKind !== 'json'
+            ? '(JSON array, e.g. \'["a","b"]\'; or comma-separated "a,b"; or repeat the flag)'
+            : '(JSON array; pass a JSON-encoded value)');
+    }
+    else if (kind === 'object' || kind === 'json') {
+        parts.push('(JSON; pass a JSON-encoded value)');
+    }
+    if (prop.default !== undefined)
+        parts.push(`default: ${JSON.stringify(prop.default)}`);
+    return parts.join(' ').trim();
+}
+export function deriveOptions(schema) {
+    if (!schema || typeof schema !== 'object')
+        return [];
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const out = [];
+    for (const [key, raw] of Object.entries(props)) {
+        const prop = raw ?? {};
+        const type = pickType(prop);
+        let kind = 'string';
+        let itemKind;
+        let placeholder = '<value>';
+        if (PRIMITIVE_KINDS.has(type)) {
+            kind = type;
+            placeholder =
+                kind === 'integer'
+                    ? '<int>'
+                    : kind === 'number'
+                        ? '<num>'
+                        : kind === 'boolean'
+                            ? ''
+                            : '<string>';
+        }
+        else if (type === 'array') {
+            kind = 'array';
+            const itemType = prop.items ? pickType(prop.items) : 'json';
+            itemKind = PRIMITIVE_KINDS.has(itemType) ? itemType : 'json';
+            // Show a friendlier placeholder when items are primitives — users can then pass either
+            // JSON, a comma-separated list, or repeat the flag.
+            placeholder = itemKind === 'json' ? '<json>' : '<list>';
+        }
+        else if (type === 'object') {
+            kind = 'object';
+            placeholder = '<json>';
+        }
+        else {
+            kind = 'json';
+            placeholder = '<json>';
+        }
+        const flagName = toFlagName(key);
+        if (!flagName)
+            continue;
+        const flag = kind === 'boolean'
+            ? `--${flagName}`
+            : required.has(key)
+                ? `--${flagName} ${placeholder}`
+                : `--${flagName} [${placeholder.replace(/[<>]/g, '')}]`;
+        out.push({
+            flag,
+            description: buildDescription(prop, kind, itemKind),
+            required: required.has(key),
+            key,
+            kind,
+            itemKind,
+            defaultValue: prop.default,
+            enumValues: prop.enum,
+        });
+    }
+    return out;
+}
+export function parseOptionValues(options, raw) {
+    const values = {};
+    const errors = [];
+    for (const opt of options) {
+        const flagKey = opt.flag.split(' ')[0]?.replace(/^--/, '') ?? opt.key;
+        const camel = flagKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        const v = raw[camel];
+        if (v === undefined)
+            continue;
+        try {
+            values[opt.key] = coerceValue(opt, v);
+        }
+        catch (err) {
+            errors.push({ key: opt.key, message: err.message });
+        }
+    }
+    return { values, errors };
+}
+function coerceValue(opt, value) {
+    switch (opt.kind) {
+        case 'string':
+            return String(value);
+        case 'integer': {
+            const n = Number(value);
+            if (!Number.isFinite(n) || !Number.isInteger(n))
+                throw new Error(`Expected integer for --${opt.key}, got ${String(value)}`);
+            return n;
+        }
+        case 'number': {
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                throw new Error(`Expected number for --${opt.key}, got ${String(value)}`);
+            return n;
+        }
+        case 'boolean':
+            if (typeof value === 'boolean')
+                return value;
+            if (value === 'true' || value === 1 || value === '1')
+                return true;
+            if (value === 'false' || value === 0 || value === '0')
+                return false;
+            throw new Error(`Expected boolean for --${opt.key}, got ${String(value)}`);
+        case 'array':
+            return coerceArray(opt, value);
+        case 'object':
+        case 'json':
+            if (typeof value !== 'string')
+                return value;
+            return parseJsonForSchemaField(toFlagName(opt.key), value);
+    }
+}
+/**
+ * Bridge `parseJsonArg` (throws VertuError carrying multi-line PowerShell hints)
+ * into the plain-`Error` contract that `parseOptionValues` expects when it
+ * aggregates per-field failures. We carry the full diagnostic message — the
+ * helpful 3-fix block stays visible to the user — but drop the `hint` channel
+ * because the upstream aggregator only inspects `.message`.
+ */
+function parseJsonForSchemaField(flagName, value) {
+    try {
+        return parseJsonArg(value, `--${flagName}`, {
+            fileFlagSuggestion: `--${flagName}-file`,
+        });
+    }
+    catch (err) {
+        throw new Error(err.message);
+    }
+}
+/**
+ * Array coercion accepts three shell-friendly shapes:
+ *   1. JSON literal (preferred):   --fields '["id","name"]'
+ *   2. Comma-separated shorthand:  --fields id,name        (only when items are primitives)
+ *   3. Repeated flag (variadic):   --fields id --fields name
+ *
+ * `value` may already be an `unknown[]` when commander's variadic collector accumulated
+ * multiple --flag invocations; in that case each element is treated as a single token
+ * (or a comma-separated group when the items are primitives), so 2 and 3 compose.
+ *
+ * For arrays of objects / nested arrays (`itemKind === 'json'`) we keep strict JSON to
+ * avoid silently mangling structured payloads (e.g. an Odoo domain).
+ */
+function coerceArray(opt, value) {
+    const itemKind = opt.itemKind ?? 'json';
+    if (Array.isArray(value)) {
+        // Single variadic call: defer to string handling so JSON / shorthand still works.
+        if (value.length === 1 && typeof value[0] === 'string') {
+            return parseArrayString(opt.key, itemKind, value[0]);
+        }
+        return value.flatMap((v) => splitArrayToken(itemKind, v));
+    }
+    if (typeof value !== 'string')
+        return value;
+    return parseArrayString(opt.key, itemKind, value);
+}
+/**
+ * Split a single repeated-flag token into typed items.
+ *
+ * Both commas and newlines act as separators for primitive item arrays — that
+ * way `--fields @list.txt` works whether the file lists names by row, by comma,
+ * or mixes both.
+ */
+function splitArrayToken(itemKind, token) {
+    if (typeof token !== 'string')
+        return [token];
+    if (itemKind === 'json') {
+        // Each variadic token is expected to be a standalone JSON value when items aren't primitives.
+        // TODO: wrap with parseJsonArg for consistent PowerShell-aware diagnostics; this path
+        // currently leaks a raw `SyntaxError` on bad input (narrow blast radius — only triggers
+        // when repeating a json-item flag like `--filters '{...}' --filters '{...}'`).
+        return [JSON.parse(token)];
+    }
+    return token
+        .split(/[\n,]+/u)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .map((s) => coerceArrayItem(itemKind, s));
+}
+function parseArrayString(key, itemKind, raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return [];
+    const flagName = toFlagName(key);
+    const looksJson = trimmed.startsWith('[') || trimmed.startsWith('{');
+    if (looksJson) {
+        let parsed;
+        let parseFailed = false;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            parseFailed = true;
+        }
+        if (!parseFailed) {
+            if (!Array.isArray(parsed)) {
+                throw new Error(`Expected JSON array for --${flagName} (got ${describeJsonValue(parsed)}).`);
+            }
+            return itemKind === 'json'
+                ? parsed
+                : parsed.map((v) => coerceArrayItem(itemKind, v));
+        }
+        // PowerShell strips inner double-quotes from `["id","name"]`, leaving `[id,name]`.
+        // For primitive item arrays we recover by stripping the outer brackets and splitting.
+        if (itemKind !== 'json') {
+            const inner = trimmed.replace(/^\[/, '').replace(/\]$/, '');
+            return inner
+                .split(/[\n,]+/u)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+                .map((s) => coerceArrayItem(itemKind, s));
+        }
+        // No primitive recovery available for json-item arrays (e.g. Odoo domain
+        // `[["a","=",1]]`): surface the PowerShell-aware diagnostic so users learn
+        // the @file / --<flag>-file escape hatch instead of guessing at quoting.
+        return parseJsonForSchemaField(flagName, trimmed);
+    }
+    if (itemKind !== 'json') {
+        // Comma- *or* newline-separated list — convenient when the value comes from
+        // `--fields @list.txt`, where users write one name per row.
+        return trimmed
+            .split(/[\n,]+/u)
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+            .map((s) => coerceArrayItem(itemKind, s));
+    }
+    // Last resort for arrays of arbitrary structure: still require valid JSON.
+    // Route through parseJsonForSchemaField so the failure message stays consistent
+    // with the leading-`[` path (same `--<flag>-file` / `@file` / `@-` hints).
+    const result = parseJsonForSchemaField(flagName, trimmed);
+    if (!Array.isArray(result)) {
+        throw new Error(`Expected JSON array for --${flagName} (got ${describeJsonValue(result)}).`);
+    }
+    return result;
+}
+function describeJsonValue(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function coerceArrayItem(itemKind, value) {
+    if (typeof value !== 'string')
+        return value;
+    switch (itemKind) {
+        case 'string':
+            return value;
+        case 'integer': {
+            const n = Number(value);
+            if (!Number.isFinite(n) || !Number.isInteger(n)) {
+                throw new Error(`expected integer item, got ${value}`);
+            }
+            return n;
+        }
+        case 'number': {
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                throw new Error(`expected number item, got ${value}`);
+            return n;
+        }
+        case 'boolean':
+            if (value === 'true' || value === '1')
+                return true;
+            if (value === 'false' || value === '0')
+                return false;
+            throw new Error(`expected boolean item, got ${value}`);
+        case 'json':
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+    }
+}

package/dist/packages/vps-work/src/utils/unwrap-envelope.js

@@ -0,0 +1,31 @@
+/**
+ * 服务端 ai_cli `/ai/cli/v1/execute` 与 ai_skills `/ai/skills/v1/execute`
+ * 在成功路径上恒返回 `{ "ok": true, "result": <真正数据> }`，失败时通过
+ * JSON-RPC `error` 通道抛出（不会以 `{ ok: false, ... }` 形式回到这里）。
+ *
+ * 该 envelope 因此不携带任何分支信息：`ok` 永远是 `true`、`result` 才是用户
+ * 真正想看的内容。再叠加 Odoo JSON-RPC 自身的一层 `result`，导致 CLI 用户每
+ * 次都在 stdout 看到双层包裹的 JSON，需要肉眼/jq 拆包。
+ *
+ * 这个工具按"严格匹配"剥掉这一层：
+ *   - 只在对象正好是 `{ ok: true, result: ... }`（且**只有**这两个键）时拆开；
+ *   - 任何其它形态（裸值、数组、含额外字段如 `warnings`、`ok=false`、缺少
+ *     `result` 等）一律按原样返回，避免把未来可能加上的 envelope 元数据吃掉。
+ *
+ * 这样如果服务端将来去掉 envelope（直接返回业务对象），或者为了承载告警/部分
+ * 成功新增字段，本工具都会自然降级为原值穿透。
+ */
+export function unwrapExecuteEnvelope(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return value;
+    }
+    const obj = value;
+    const keys = Object.keys(obj);
+    if (keys.length !== 2)
+        return value;
+    if (!keys.includes('ok') || !keys.includes('result'))
+        return value;
+    if (obj.ok !== true)
+        return value;
+    return obj.result;
+}