@yosai/cli 0.0.0-stage → 0.2.0

package/dist/domain-executor.js

@@ -0,0 +1,257 @@
+import { readFileSync } from 'node:fs';
+import { EXIT, UsageError } from './errors.js';
+import { print, printJson } from './output.js';
+import { clientFromConfig } from './commands/context.js';
+const URN_PATTERN = /^cortex:\/\/kb\/[^\s:]+$/;
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DIGITS_PATTERN = /^\d+$/;
+const ITEMS_SAMPLE_HINT = "示例：--items '[{\"target\":\"cortex://kb/KBxxxx/doc/NDxxxx:10-60\"}]'";
+export function buildToolArgs(spec, context) {
+    const args = spec.buildArgs ? spec.buildArgs(context) : buildDeclaredArgs(spec, context);
+    spec.validateArgs?.(args);
+    return args;
+}
+function buildDeclaredArgs(spec, context) {
+    const declared = spec.positionals ?? [];
+    if (context.positionals.length < declared.length) {
+        throw new UsageError(`缺少参数 <${declared[context.positionals.length].name}>`, `用法: ${buildUsageForSpec(spec)}`);
+    }
+    const args = {};
+    declared.forEach((positional, index) => {
+        if (positional.variadic) {
+            const rest = context.positionals.slice(index);
+            args[positional.param] = positional.kind === 'space-join' ? rest.join(' ') : JSON.stringify(rest);
+            return;
+        }
+        const value = context.positionals[index];
+        if (positional.validate === 'urn') {
+            assertUrn(positional.name, value);
+        }
+        args[positional.param] = value;
+    });
+    for (const flag of spec.flags ?? []) {
+        const raw = context.flags[flag.flag];
+        if (raw === undefined || raw === false) {
+            if (flag.required) {
+                throw new UsageError(`缺少 --${flag.flag}`, `用法: ${buildUsageForSpec(spec)}`);
+            }
+            continue;
+        }
+        const values = Array.isArray(raw) ? raw : [raw];
+        const mapped = values.map((value) => {
+            if (flag.kind === 'number') {
+                return toNumber(value, flag.flag);
+            }
+            return flag.kind === 'boolean' ? value === true : String(value);
+        });
+        mapped.forEach((value) => assertFlagValue(flag, value));
+        args[flag.param] = flag.multiple ? JSON.stringify(mapped) : mapped[0];
+    }
+    return args;
+}
+export function assertUrn(name, value) {
+    if (!URN_PATTERN.test(value)) {
+        throw new UsageError(`${name} 不是合法 URN：${value}`, 'URN 格式 cortex://kb/{kb_code}/doc/{node_code}（库级为 cortex://kb/{kb_code}），'
+            + '可用 `yos retrieve search` 或 `yos docs tree <kb_code>` 取得');
+    }
+}
+export function assertDateRange(start, end, startFlag, endFlag) {
+    for (const [value, flag] of [[start, startFlag], [end, endFlag]]) {
+        if (typeof value === 'string' && !DATE_PATTERN.test(value)) {
+            throw new UsageError(`--${flag} 日期格式应为 yyyy-MM-dd：${value}`);
+        }
+    }
+    if (typeof start === 'string' && typeof end === 'string' && start > end) {
+        throw new UsageError(`日期区间非法：--${startFlag} 晚于 --${endFlag}`, `起 ${start} 应不晚于止 ${end}`);
+    }
+}
+export function assertTextLength(value, max, label) {
+    if (typeof value !== 'string' || value.length <= max) {
+        return;
+    }
+    throw new UsageError(`${label}超长（实际 ${value.length} 字，上限 ${max} 字）`);
+}
+export function assertNotBlank(value, label, hint) {
+    if (typeof value === 'string' && value.trim().length > 0) {
+        return;
+    }
+    throw new UsageError(`${label}不能为空`, hint);
+}
+export function assertAnyParam(args, params, labels) {
+    if (params.some((param) => args[param] !== undefined && args[param] !== '')) {
+        return;
+    }
+    throw new UsageError(`${labels.join('、')} 至少传一个`);
+}
+export function assertGrepOrder(target, pattern) {
+    const first = String(target ?? '');
+    const second = String(pattern ?? '');
+    if (!URN_PATTERN.test(first) && URN_PATTERN.test(second)) {
+        throw new UsageError('参数顺序疑似颠倒：第 1 个参数不是 URN', 'retrieve grep 的顺序为 <target> <pattern>，与 Unix grep 相反');
+    }
+    assertUrn('target', first);
+}
+export function assertNumericId(value, label, hint) {
+    const text = String(value ?? '');
+    if (!DIGITS_PATTERN.test(text)) {
+        throw new UsageError(`${label} 需为数字，实际收到：${text}`, hint);
+    }
+}
+function assertFlagValue(flag, value) {
+    if (flag.values !== undefined && !flag.values.includes(String(value))) {
+        throw new UsageError(`--${flag.flag} 取值非法：${String(value)}`, `可选：${flag.values.join(' / ')}`);
+    }
+    if (typeof value !== 'number') {
+        return;
+    }
+    if (flag.min !== undefined && value < flag.min) {
+        throw new UsageError(`--${flag.flag} 低于下限 ${flag.min}：${value}`, rangeHint(flag));
+    }
+    if (flag.max !== undefined && value > flag.max) {
+        throw new UsageError(`--${flag.flag} 超过上限 ${flag.max}：${value}`, rangeHint(flag));
+    }
+}
+function rangeHint(flag) {
+    return `取值范围 ${flag.min ?? '不限'}~${flag.max ?? '不限'}`;
+}
+export async function runDomainCommand(spec, context) {
+    const args = buildToolArgs(spec, context);
+    const result = await clientFromConfig().callTool(spec.tool, args);
+    if (context.flags.json) {
+        printJson(result);
+    }
+    else if (spec.render && !result.isError) {
+        spec.render(result);
+    }
+    else {
+        print(result.text);
+    }
+    return result.isError ? EXIT.BUSINESS : EXIT.OK;
+}
+export function buildUsageForSpec(spec) {
+    const parts = [`yos ${spec.name}`];
+    for (const positional of spec.positionals ?? []) {
+        parts.push(positional.variadic ? `<${positional.name}...>` : `<${positional.name}>`);
+    }
+    for (const flag of spec.flags ?? []) {
+        if (flag.kind === 'boolean') {
+            parts.push(`[--${flag.flag}]`);
+        }
+        else {
+            parts.push(flag.required ? `--${flag.flag} <值>` : `[--${flag.flag} <值>]`);
+        }
+    }
+    parts.push('[--json]');
+    return parts.join(' ');
+}
+export function buildOptionsForSpec(spec) {
+    const options = {
+        json: { type: 'boolean' },
+    };
+    for (const flag of spec.flags ?? []) {
+        const option = {
+            type: flag.kind === 'boolean' ? 'boolean' : 'string',
+        };
+        if (flag.multiple) {
+            option.multiple = true;
+        }
+        options[flag.flag] = option;
+    }
+    return options;
+}
+export function buildParamNotesForSpec(spec) {
+    const notes = [];
+    for (const positional of spec.positionals ?? []) {
+        if (positional.description !== undefined) {
+            notes.push([positional.variadic ? `<${positional.name}...>` : `<${positional.name}>`, positional.description]);
+        }
+    }
+    for (const flag of spec.flags ?? []) {
+        notes.push([`--${flag.flag}`, `${flag.description}${flag.required ? '（必填）' : ''}`]);
+    }
+    notes.push(['--json', '结构化输出（工具返回原文在 text 字段内）']);
+    return notes;
+}
+export function buildParamAliasForSpec(spec) {
+    const alias = {};
+    for (const flag of spec.flags ?? []) {
+        if (flag.param !== flag.flag) {
+            alias[flag.param] = flag.flag;
+        }
+    }
+    return alias;
+}
+export function parseReadTarget(raw) {
+    const matched = /:(\d+)-(\d+)$/.exec(raw);
+    if (!matched) {
+        assertUrn('target', raw);
+        return { target: raw, offset: 1, limit: 200 };
+    }
+    const offset = Number(matched[1]);
+    const end = Number(matched[2]);
+    if (offset < 1) {
+        throw new UsageError(`行号区间非法（起 < 1）：${raw}`, '行号从 1 开始，区间格式 <target>:起-止');
+    }
+    if (end < offset) {
+        throw new UsageError(`行号区间非法（止 < 起）：${raw}`, '区间格式 <target>:起-止，如 cortex://kb/KB1/doc/ND1:10-50');
+    }
+    const target = raw.slice(0, matched.index);
+    assertUrn('target', target);
+    return { target, offset, limit: end - offset + 1 };
+}
+export function normalizeReadItems(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError('--items 不是合法 JSON', ITEMS_SAMPLE_HINT);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new UsageError('--items 应为 JSON 数组', ITEMS_SAMPLE_HINT);
+    }
+    return JSON.stringify(parsed.map(normalizeReadItem));
+}
+function normalizeReadItem(item) {
+    const record = item;
+    if (typeof item !== 'object' || item === null || typeof record.target !== 'string') {
+        throw new UsageError('--items 每项须为含 target 字符串的对象', ITEMS_SAMPLE_HINT);
+    }
+    const normalized = { ...record };
+    const parsed = parseReadTarget(record.target);
+    normalized.target = parsed.target;
+    if (parsed.target !== record.target) {
+        normalized.offset = record.offset ?? parsed.offset;
+        normalized.limit = record.limit ?? parsed.limit;
+    }
+    return normalized;
+}
+export function resolveContent(flags, required) {
+    const content = typeof flags.content === 'string' ? flags.content : undefined;
+    const file = typeof flags.file === 'string' ? flags.file : undefined;
+    if (content !== undefined && file !== undefined) {
+        throw new UsageError('--content 与 --file 互斥', "二选一：--content '<文本>' 或 --file <本地文件路径>");
+    }
+    if (file !== undefined) {
+        try {
+            return readFileSync(file, 'utf8');
+        }
+        catch {
+            throw new UsageError(`文件不存在或不可读：${file}`);
+        }
+    }
+    if (content !== undefined) {
+        return content;
+    }
+    if (required) {
+        throw new UsageError('缺少正文内容', "用 --content '<文本>' 或 --file <本地文件路径> 提供");
+    }
+    return undefined;
+}
+function toNumber(value, flag) {
+    const num = Number(value);
+    if (Number.isNaN(num)) {
+        throw new UsageError(`--${flag} 需要数字，实际：${String(value)}`);
+    }
+    return num;
+}

package/dist/endpoints.js

@@ -0,0 +1 @@
+export const DEFAULT_ENDPOINT = 'https://yos-bff.linkduoo.com';

package/dist/errors.js

@@ -0,0 +1,37 @@
+export const EXIT = {
+    OK: 0,
+    BUSINESS: 1,
+    USAGE: 2,
+    NETWORK: 3,
+    AUTH: 4,
+};
+export class CliError extends Error {
+    exitCode;
+    hint;
+    constructor(message, exitCode, hint) {
+        super(message);
+        this.exitCode = exitCode;
+        this.hint = hint;
+        this.name = new.target.name;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT.USAGE, hint);
+    }
+}
+export class BusinessError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT.BUSINESS, hint);
+    }
+}
+export class NetworkError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT.NETWORK, hint);
+    }
+}
+export class AuthError extends CliError {
+    constructor(message) {
+        super(message, EXIT.AUTH, '请执行 `yos login` 重新配置访问令牌');
+    }
+}

package/dist/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import './commands/index.js';
+import { dispatch } from './cli.js';
+const exitCode = await dispatch(process.argv.slice(2));
+process.exitCode = exitCode;

package/dist/npm-meta.js

@@ -0,0 +1,96 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { NetworkError } from './errors.js';
+const execFileAsync = promisify(execFile);
+export const PUBLIC_REGISTRY = 'https://registry.npmjs.org';
+export function readPackageMeta() {
+    let dir = resolve(dirname(fileURLToPath(import.meta.url)));
+    for (;;) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            const parsed = tryParseJson(candidate);
+            if (parsed?.name && parsed?.version) {
+                return { name: parsed.name, version: parsed.version, dir };
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+}
+export async function runNpm(args) {
+    const useCmdWrapper = process.platform === 'win32';
+    const command = useCmdWrapper ? (process.env.ComSpec ?? 'cmd.exe') : 'npm';
+    const commandArgs = useCmdWrapper ? ['/d', '/s', '/c', 'npm', ...args] : args;
+    try {
+        const { stdout, stderr } = await execFileAsync(command, commandArgs, {
+            encoding: 'utf8',
+            maxBuffer: 8 * 1024 * 1024,
+            timeout: 30_000,
+            windowsHide: true,
+        });
+        return { ok: true, stdout: `${stdout}`.trim(), stderr: `${stderr}`.trim() };
+    }
+    catch (error) {
+        const failure = error;
+        return {
+            ok: false,
+            stdout: `${failure.stdout ?? ''}`.trim(),
+            stderr: `${failure.stderr || failure.message || ''}`.trim(),
+        };
+    }
+}
+export async function fetchLatestVersion(name) {
+    const result = await runNpm(['view', name, 'version', `--registry=${PUBLIC_REGISTRY}`]);
+    if (!result.ok) {
+        const reason = result.stderr.split(/\r?\n/)[0]?.trim() || result.stdout.split(/\r?\n/)[0]?.trim() || '';
+        throw new NetworkError(`无法获知 ${name} 的最新版本：npm view 调用失败`, `${reason ? `${reason}；` : ''}离线或 npm 不可用时，手动升级请执行 npm install -g ${name}@latest`);
+    }
+    const latest = result.stdout.split(/\r?\n/)[0]?.trim() ?? '';
+    if (!/^\d+\.\d+\.\d+/.test(latest)) {
+        throw new NetworkError(`无法解析 ${name} 的最新版本输出`, `npm view 返回：${result.stdout.slice(0, 120)}`);
+    }
+    return latest;
+}
+export function compareVersions(a, b) {
+    const left = toSegments(a);
+    const right = toSegments(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0) {
+            return diff < 0 ? -1 : 1;
+        }
+    }
+    return 0;
+}
+export async function detectGlobalInstall(meta) {
+    const result = await runNpm(['prefix', '-g']);
+    if (!result.ok || result.stdout.length === 0) {
+        return { global: false, prefix: '' };
+    }
+    const prefix = stripTrailingSep(resolve(result.stdout));
+    const packageDir = stripTrailingSep(meta.dir);
+    return {
+        global: packageDir === prefix || packageDir.startsWith(`${prefix}${sep}`),
+        prefix,
+    };
+}
+function toSegments(version) {
+    return version.trim().split('-')[0].split('.').map((part) => Number.parseInt(part, 10) || 0);
+}
+function tryParseJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function stripTrailingSep(path) {
+    return path.replace(/[/\\]+$/, '');
+}

package/dist/openapis-client.js

@@ -0,0 +1,112 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { AuthError, BusinessError, NetworkError } from './errors.js';
+export const MAX_UPLOAD_SIZE_BYTES = 20 * 1024 * 1024;
+export function formatIdentity(identity) {
+    return identity.userName ? `${identity.userName}（${identity.userCode}）` : identity.userCode;
+}
+export class OpenApisClient {
+    base;
+    apiKey;
+    constructor(base, apiKey) {
+        this.base = base;
+        this.apiKey = apiKey;
+    }
+    async whoami() {
+        return this.request('/user/whoami', {});
+    }
+    async listTools() {
+        const tools = await this.request('/tool/list', {});
+        return tools ?? [];
+    }
+    async toolSchema(name) {
+        return this.request('/tool/schema', { name });
+    }
+    async callTool(name, args) {
+        return this.request('/tool/call', { name, arguments: args });
+    }
+    async request(path, body) {
+        let response;
+        try {
+            response = await fetch(`${this.base}${path}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(body ?? {}),
+            });
+        }
+        catch (e) {
+            throw new NetworkError(`无法连接 YOS 服务：endpoint=${this.base}，原因：${e.message}`);
+        }
+        return parseEnvelope(response);
+    }
+}
+async function parseEnvelope(response) {
+    if (response.status === 401) {
+        let reason = '访问令牌无效或已过期';
+        try {
+            const body = await response.json();
+            if (body.error) {
+                reason = body.error;
+            }
+        }
+        catch {
+        }
+        throw new AuthError(`鉴权失败：${reason}`);
+    }
+    if (response.status === 404) {
+        throw new NetworkError(`HTTP 404：服务端不存在该接口（${response.url}）`, '确认服务端已部署开放接口通道；端点配错时用 yos login --endpoint <url> --key <key> 重新指定');
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new NetworkError(`服务返回无法解析的响应：HTTP ${response.status}`);
+    }
+    if (!response.ok || payload.code !== 200) {
+        throw new BusinessError(payload.message ?? `服务返回异常状态：HTTP ${response.status}`);
+    }
+    return payload.data;
+}
+export function parseToolJson(result) {
+    try {
+        return JSON.parse(result.text);
+    }
+    catch {
+        throw new BusinessError(`工具返回内容不是 JSON：${result.text.slice(0, 200)}`);
+    }
+}
+export async function uploadKnowledgeFile(endpoint, apiKey, filePath, kbCode, parentCode, fileName) {
+    let fileSize;
+    try {
+        fileSize = (await stat(filePath)).size;
+    }
+    catch {
+        throw new BusinessError(`文件不存在或不可读：path=${filePath}`);
+    }
+    if (fileSize > MAX_UPLOAD_SIZE_BYTES) {
+        throw new BusinessError(`文件超过 20MB 上限：size=${fileSize}，path=${filePath}`);
+    }
+    const content = await readFile(filePath);
+    const form = new FormData();
+    form.append('file', new Blob([content]), fileName ?? basename(filePath));
+    form.append('kb_code', kbCode);
+    if (parentCode) {
+        form.append('parent_code', parentCode);
+    }
+    let response;
+    try {
+        response = await fetch(`${endpoint}/open-apis/knowledge/file_upload`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${apiKey}` },
+            body: form,
+        });
+    }
+    catch (e) {
+        throw new NetworkError(`无法连接 YOS 服务：endpoint=${endpoint}，原因：${e.message}`);
+    }
+    return parseEnvelope(response);
+}

package/dist/output.js

@@ -0,0 +1,21 @@
+export function print(value) {
+    process.stdout.write(`${value}\n`);
+}
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function printErr(value) {
+    process.stderr.write(`${value}\n`);
+}
+export function renderRows(rows) {
+    const width = Math.max(...rows.map(([left]) => left.length), 0);
+    return rows.map(([left, right]) => `${left.padEnd(width)}  ${right}`).join('\n');
+}
+export function summarize(text, maxChars = 40) {
+    const firstLine = text.split('\n')[0].trim();
+    if (firstLine.length === 0) {
+        return '';
+    }
+    const sentence = firstLine.split('。')[0];
+    return sentence.length <= maxChars ? sentence : `${sentence.slice(0, maxChars)}…`;
+}

package/dist/prompt.js

@@ -0,0 +1,40 @@
+export async function readHiddenLine(question) {
+    process.stderr.write(question);
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+            if (chunk.includes(10)) {
+                break;
+            }
+        }
+        return Buffer.concat(chunks).toString('utf8').split('\n')[0].trim();
+    }
+    return new Promise((resolve) => {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+        let value = '';
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n') {
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.stdin.off('data', onData);
+                    process.stderr.write('\n');
+                    resolve(value.trim());
+                    return;
+                }
+                if (ch === '\u0003') {
+                    process.exit(130);
+                }
+                if (ch === '\u007f') {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += ch;
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}

package/dist/skill-sync.js

@@ -0,0 +1,34 @@
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readPackageMeta } from './npm-meta.js';
+import { updateConfig } from './config.js';
+import { saveVersionState } from './version-state.js';
+export const BUILTIN_SKILLS = ['yos', 'yos-shared', 'yos-kb', 'yos-retrieval', 'yos-transcript', 'yos-support', 'yos-install'];
+const AGENT_SKILL_DIRS = ['.claude/skills', '.workbuddy/skills', '.cursor/skills', '.codex/skills', '.qoder/skills', '.qoder-cn/skills', '.agentskill'];
+export function skillsSourceDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const distCandidate = join(here, 'skills');
+    return existsSync(distCandidate) ? distCandidate : join(here, '..', 'src', 'skills');
+}
+export function detectSkillTargets() {
+    return AGENT_SKILL_DIRS
+        .map((rel) => join(homedir(), rel))
+        .filter((dir) => existsSync(dir));
+}
+export function installSkillsTo(targets) {
+    const source = skillsSourceDir();
+    for (const target of targets) {
+        for (const skill of BUILTIN_SKILLS) {
+            const skillTarget = join(target, skill);
+            mkdirSync(skillTarget, { recursive: true });
+            cpSync(join(source, skill), skillTarget, { recursive: true });
+        }
+    }
+    updateConfig({ installedSkillDirs: targets });
+    const meta = readPackageMeta();
+    if (meta) {
+        saveVersionState(meta.version);
+    }
+}