@dreamor/atlas-cli 0.7.0

package/dist/adapters/atlas/cli.js

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+// Auth
+import { authLoginCmd, authStatusCmd } from './commands/auth.js';
+// Project commands (find, projects, link, unlink)
+import { findCmd, projectsCmd, linkCmd, linkStatusCmd, unlinkCmd, } from './commands/project/index.js';
+// Baseline commands (month, summary, export)
+import { monthCmd as baselineMonthCmd, summaryCmd as baselineSummaryCmd, exportCmd as baselineExportCmd, } from './commands/baseline/index.js';
+// Actual commands (list, show, month, summary, export)
+import { showCmd as actualShowCmd, monthCmd as actualMonthCmd, summaryCmd as actualSummaryCmd, exportCmd as actualExportCmd, } from './commands/actual/index.js';
+// Compare
+import { compareCmd } from './commands/compare/index.js';
+// Utility commands
+import { daemonCmd } from './daemon/index.js';
+import { schemaCommandsCmd, schemaExportCmd } from './commands/schema.js';
+import { execCmd } from './commands/exec.js';
+import { suggestCmd } from './commands/suggest.js';
+import { updateCmd } from './commands/update.js';
+import { BanmaApiError, ConfigError, NotImplementedError, SessionExpiredError, isAtlasError, } from './util/errors.js';
+import { isJsonMode, printError } from './util/output.js';
+import { getOutputSchema } from './commands/_output_schema.js';
+export function handleError(err) {
+    if (isJsonMode()) {
+        printError(err, { json: true });
+        process.exit(exitCodeFor(err));
+    }
+    if (err instanceof SessionExpiredError) {
+        console.error(err.message);
+        process.exit(2);
+    }
+    if (err instanceof ConfigError) {
+        console.error(`Config error: ${err.message}`);
+        process.exit(64);
+    }
+    if (err instanceof BanmaApiError) {
+        console.error(`Banma API error [${err.errCode}] ${err.errorMsg}`);
+        process.exit(3);
+    }
+    if (err instanceof NotImplementedError) {
+        console.error(err.message);
+        process.exit(64);
+    }
+    const debug = process.env.DEBUG === '1';
+    console.error(err instanceof Error ? (debug ? err.stack ?? err.message : err.message) : String(err));
+    process.exit(1);
+}
+export function exitCodeFor(err) {
+    if (err instanceof SessionExpiredError)
+        return 2;
+    if (err instanceof BanmaApiError)
+        return 3;
+    if (err instanceof NotImplementedError)
+        return 64;
+    if (isAtlasError(err)) {
+        switch (err.code) {
+            case 'AMBIGUOUS_PROJECT': return 4;
+            case 'PROJECT_NOT_FOUND': return 5;
+            case 'RATE_LIMITED': return 6;
+            case 'NETWORK_ERROR': return 7;
+            case 'UPDATE_ERROR': return 8;
+            case 'CONFIG_ERROR': return 64;
+            default: return 1;
+        }
+    }
+    return 1;
+}
+export function emitDescribe(cmd) {
+    const path = [];
+    let cursor = cmd;
+    while (cursor && cursor.name() !== 'atlas') {
+        path.unshift(cursor.name());
+        cursor = cursor.parent;
+    }
+    const commandPath = ['atlas', ...path].join(' ');
+    const outSchema = getOutputSchema(commandPath);
+    const payload = {
+        command: commandPath,
+        description: cmd.description() ?? '',
+        options: cmd.options.map((o) => {
+            const opt = o;
+            return {
+                flags: opt.flags,
+                description: opt.description ?? '',
+                required: opt.mandatory ?? false,
+                ...(opt.defaultValue !== undefined ? { default: opt.defaultValue } : {}),
+            };
+        }),
+        args: cmd.registeredArguments?.map((a) => ({
+            name: a.name(),
+            required: a.required,
+        })) ?? [],
+        subcommands: cmd.commands.map((c) => c.name()),
+        outputSchema: outSchema.jsonSchema,
+    };
+    const envelope = { ok: true, data: payload };
+    process.stdout.write(JSON.stringify(envelope) + '\n');
+}
+function addProjectOptions(cmd) {
+    return cmd
+        .option('--project-id <id>', '项目ID，精确名称或唯一子串（或使用 BANMA_PROJECT_ID 环境变量）')
+        .option('--refresh-projects', '解析 --project-id 前重新获取项目目录缓存');
+}
+// ---------------------------------------------------------------------------
+// Registration functions
+// ---------------------------------------------------------------------------
+function registerAuthCommands(program) {
+    const auth = program.command('auth').description('SSO 会话管理');
+    auth
+        .command('login')
+        .description('打开浏览器完成 SSO 登录并持久化会话')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await authLoginCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    auth
+        .command('status')
+        .description('显示当前会话信息')
+        .option('--json', '输出 JSON')
+        .action(async (opts) => {
+        try {
+            await authStatusCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+function registerProjectCommands(program) {
+    // atlas find
+    program
+        .command('find <kind> <query>')
+        .description('搜索项目/部门/字典值（kind: project|department|mp-type|line-plan-type|area-code）')
+        .option('--json', '输出 JSON 信封')
+        .option('--refresh', '刷新字典/部门/项目缓存')
+        .option('--limit <n>', '最多返回 N 个候选（默认 20）')
+        .action(async (kind, query, opts) => {
+        try {
+            await findCmd(kind, query, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas projects
+    program
+        .command('projects')
+        .description('列出我有权限的所有项目')
+        .option('--json', '输出 JSON 信封')
+        .option('--refresh', '刷新项目缓存')
+        .action(async (opts) => {
+        try {
+            await projectsCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas link
+    program
+        .command('link [project]')
+        .description('绑定当前项目（精确名称/子串/数字ID）。不带参数时显示当前绑定状态')
+        .option('--json', '输出 JSON 信封')
+        .option('--dry-run', '仅预览，不实际写入绑定')
+        .option('--refresh-projects', '解析 project 前重新获取项目目录缓存')
+        .action(async (project, opts) => {
+        try {
+            if (project === undefined) {
+                await linkStatusCmd(opts);
+            }
+            else {
+                await linkCmd(project, opts);
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas unlink
+    program
+        .command('unlink')
+        .description('清除当前项目绑定')
+        .option('--json', '输出 JSON 信封')
+        .option('--dry-run', '仅预览，不实际清除绑定')
+        .action(async (opts) => {
+        try {
+            await unlinkCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+function registerBaselineCommands(program) {
+    const base = program.command('baseline').description('基线（计划）人力数据');
+    // atlas baseline month
+    addProjectOptions(base
+        .command('month')
+        .description('人力基线汇总（按月显示人力投入）'))
+        .option('--json', '输出 JSON')
+        .option('--department <name>', '按部门名称/ID 筛选（子串，不区分大小写）')
+        .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
+        .option('--area-code <code>', '按地域筛选（子串，不区分大小写）')
+        .option('--mp-type <type>', '按人力类型筛选（子串，不区分大小写）')
+        .option('--month <yyyymm>', '查询月份（YYYY-MM，与 --from/--to 互斥）')
+        .option('--from <yyyymm>', '起始月份（YYYY-MM，包含）')
+        .option('--to <yyyymm>', '结束月份（YYYY-MM，包含）')
+        .option('--all-months', '显示所有月份（默认：只显示有人力的月份）')
+        .action(async (opts) => {
+        try {
+            await baselineMonthCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas baseline summary
+    addProjectOptions(base
+        .command('summary')
+        .description('按月/部门/角色汇总基线人力投入'))
+        .option('--by <axis>', 'month | department | role', 'month')
+        .option('--department <name>', '按部门名称/ID 筛选（子串，不区分大小写）')
+        .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
+        .option('--area-code <code>', '按地域筛选（子串，不区分大小写）')
+        .option('--mp-type <type>', '按人力类型筛选（子串，不区分大小写）')
+        .option('--from <yyyymm>', '起始月份（YYYY-MM，包含）')
+        .option('--to <yyyymm>', '结束月份（YYYY-MM，包含）')
+        .option('--json', '输出 JSON')
+        .action(async (opts) => {
+        try {
+            await baselineSummaryCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas baseline export
+    addProjectOptions(base
+        .command('export')
+        .description('导出基线条目到 CSV/JSON'))
+        .requiredOption('--format <fmt>', 'csv | json')
+        .requiredOption('--out <path>', '输出文件路径')
+        .option('--from <yyyymm>', '起始月份（YYYY-MM，包含）')
+        .option('--to <yyyymm>', '结束月份（YYYY-MM，包含）')
+        .option('--department <name>', '按部门名称/ID 筛选（子串，不区分大小写）')
+        .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
+        .option('--since <iso>', '仅导出指定时间后修改的条目（ISO 时间戳）')
+        .option('--json', '输出 JSON 信封（结果摘要）')
+        .action(async (opts) => {
+        try {
+            if (!['csv', 'json'].includes(opts.format)) {
+                throw new ConfigError(`--format must be csv|json, got "${opts.format}"`);
+            }
+            await baselineExportCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+function registerActualCommands(program) {
+    const base = program.command('actual').description('实际人力数据');
+    // atlas actual show <staffId>
+    addProjectOptions(base
+        .command('show <staffId>')
+        .description('查看单个人员的实际工时明细'))
+        .option('--month <yyyymm>', '查询月份（YYYY-MM，默认当前月）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (staffId, opts) => {
+        try {
+            await actualShowCmd(staffId, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas actual month
+    addProjectOptions(base
+        .command('month')
+        .description('实际工时明细（人员×周透视表）。无参数时默认查当前自然年'))
+        .option('--month <yyyymm>', '查询月份（YYYY-MM，与 --from/--to 互斥）')
+        .option('--from <yyyymm>', '起始月份（YYYY-MM，包含，与 --month 互斥）')
+        .option('--to <yyyymm>', '结束月份（YYYY-MM，包含，与 --month 互斥）')
+        .option('--status <status>', '筛选审批状态: pending | approved | all', 'all')
+        .option('--department <name>', '按团队负责人/部门筛选（子串，不区分大小写）')
+        .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
+        .option('--staff-name <name>', '按姓名/工号筛选（子串，不区分大小写）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await actualMonthCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas actual summary
+    addProjectOptions(base
+        .command('summary')
+        .description('按月/部门/角色汇总实际工时'))
+        .option('--by <axis>', 'month | department | role', 'month')
+        .option('--month <yyyymm>', '查询月份')
+        .option('--status <status>', 'pending | approved | all', 'all')
+        .option('--department <name>', '按部门筛选')
+        .option('--role <name>', '按角色筛选')
+        .option('--from <yyyymm>', '起始月份')
+        .option('--to <yyyymm>', '结束月份')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await actualSummaryCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // atlas actual export
+    addProjectOptions(base
+        .command('export')
+        .description('导出实际工时数据（CSV/JSON）'))
+        .requiredOption('--format <fmt>', 'csv | json')
+        .requiredOption('--out <path>', '输出文件路径')
+        .option('--by <axis>', 'month | department | role', 'month')
+        .option('--status <status>', 'pending | approved | all', 'all')
+        .option('--department <name>', '按部门筛选')
+        .option('--role <name>', '按角色筛选')
+        .option('--from <yyyymm>', '起始月份')
+        .option('--to <yyyymm>', '结束月份')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await actualExportCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+function registerCompareCommands(program) {
+    addProjectOptions(program
+        .command('compare')
+        .description('Compare baseline (计划) vs actual (实际) manpower'))
+        .option('--by <axis>', 'month | department | role', 'month')
+        .option('--from <yyyymm>', '起始月份（YYYY-MM，包含）')
+        .option('--to <yyyymm>', '结束月份（YYYY-MM，包含）')
+        .option('--month <yyyymm>', '查询月份（YYYY-MM，优先级高于 from/to 用于实际数据 API）')
+        .option('--department <name>', '按部门名称/ID 筛选（子串，不区分大小写）')
+        .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
+        .option('--status <status>', '筛选审批状态: pending | approved | all', 'all')
+        .option('--threshold <n>', '差异绝对值阈值（人月），低于此值不标记', '0')
+        .option('--flag-overrun', '用 ⚠️ 标记实际 > 基线的情况')
+        .option('--page <n>', '页码（从 1 开始）')
+        .option('--page-size <n>', '每页条目数（大于 0 时启用分页）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await compareCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+function registerUtilityCommands(program) {
+    // daemon
+    program
+        .command('daemon')
+        .description('启动本地守护进程（沙盒环境使用，保持浏览器会话）')
+        .option('--port <n>', '监听端口（默认 8765，也可用 ATLAS_DAEMON_PORT 环境变量）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await daemonCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // schema
+    const schema = program.command('schema').description('CLI 自省 / 字段字典导出');
+    schema
+        .command('export')
+        .description('导出字典 + 部门树，供 skill 缓存对照')
+        .option('--out <path>', '同时写入文件路径')
+        .option('--refresh', '刷新缓存')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await schemaExportCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    schema
+        .command('commands')
+        .description('列出所有命令的参数 schema 及输出 schema 标注')
+        .option('--json', '输出 JSON 信封')
+        .option('--describe', '输出完整命令 schema 含 outputSchema（agent 自省用）')
+        .action((opts) => {
+        try {
+            schemaCommandsCmd(program, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // exec
+    program
+        .command('exec')
+        .description('按 plan-file 顺序执行多条命令（agent 批处理用）')
+        .requiredOption('--plan-file <path>', 'JSON 计划文件路径')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await execCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // update
+    program
+        .command('update')
+        .description('检查并自动升级到最新版本（设置 ATLAS_DISABLE_UPDATE=1 禁用）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await updateCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // suggest
+    program
+        .command('suggest <query...>')
+        .description('将自然语言查询翻译为候选 atlas 命令（纯规则，不调 LLM）')
+        .option('--json', '输出 JSON 信封')
+        .action((tokens, opts) => {
+        try {
+            suggestCmd(tokens.join(' '), opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+// Version is generated from package.json by scripts/sync-version.mjs (run as
+// prebuild). Inlined as a string constant so both `tsc` and bun --compile
+// single-file binaries can read it without runtime fs access.
+import { ATLAS_VERSION } from './util/version.js';
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('atlas')
+        .description('Atlas CLI - 斑马云图人力基线管理工具')
+        .version(ATLAS_VERSION, '-V, --version', '显示版本号')
+        .option('--json', '以 JSON 信封输出（也可用环境变量 ATLAS_OUTPUT=json）')
+        .option('--quiet', '静默模式：抑制非信封输出（设置 ATLAS_QUIET=1 也可）')
+        .option('--describe', '不执行命令，仅输出该命令的参数 schema（agent 自省用）')
+        .addHelpText('after', `
+退出码:
+   0  成功
+   1  通用错误 / exec 中某 step 失败
+   2  会话过期（需重新登录）
+   3  API 返回错误（BanmaApiError）
+   4  项目匹配歧义（AmbiguousProject）
+   5  项目未找到（ProjectNotFound）
+   6  API 限流（RateLimited）
+   7  网络错误（NetworkError）
+   8  版本更新异常（UpdateError）
+  64  配置错误 / 未实现（ConfigError）
+`)
+        .showHelpAfterError()
+        .hook('preAction', (thisCommand, actionCommand) => {
+        const opts = thisCommand.opts();
+        if (opts.json === true && process.env.ATLAS_OUTPUT === undefined) {
+            process.env.ATLAS_OUTPUT = 'json';
+        }
+        if (opts.quiet === true) {
+            process.env.ATLAS_QUIET = '1';
+        }
+        if (opts.describe === true) {
+            emitDescribe(actionCommand);
+            process.exit(0);
+        }
+    });
+    registerAuthCommands(program);
+    registerProjectCommands(program);
+    registerBaselineCommands(program);
+    registerActualCommands(program);
+    registerCompareCommands(program);
+    registerUtilityCommands(program);
+    return program;
+}
+// 注意：auto-run 入口已移至 bin/atlas.ts
+// 此模块仅 export buildProgram / handleError / emitDescribe

package/dist/adapters/atlas/commands/_output_schema.js

@@ -0,0 +1,100 @@
+const schemas = {
+    'atlas auth login': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean', const: true },
+                data: {
+                    type: 'object',
+                    properties: {
+                        status: { type: 'string', enum: ['logged_in'] },
+                    },
+                },
+            },
+        },
+    },
+    'atlas auth status': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        loggedIn: { type: 'boolean' },
+                        expiresAt: { type: 'number' },
+                    },
+                },
+            },
+        },
+    },
+    'atlas projects': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: { type: 'array', items: { type: 'object' } },
+            },
+        },
+    },
+    'atlas link': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        projectId: { type: 'string' },
+                        projectName: { type: 'string' },
+                        linkedAt: { type: 'string' },
+                    },
+                },
+            },
+        },
+    },
+    'atlas baseline month': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        months: { type: 'array', items: { type: 'string' } },
+                        totalManpower: { type: 'number' },
+                    },
+                },
+            },
+        },
+    },
+    'atlas baseline summary': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            month: { type: 'string' },
+                            manpower: { type: 'number' },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+export function getOutputSchema(commandPath) {
+    return schemas[commandPath] ?? {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {},
+            },
+        },
+    };
+}

package/dist/adapters/atlas/commands/actual/_logic.js

@@ -0,0 +1,41 @@
+/**
+ * actual 命令的纯逻辑层。
+ *
+ * 与命令解析层（index.ts）分离：这里不做 IO、不调 API、不输出，
+ * 只做数据变换。便于单元测试（参见 tests/actual_logic.test.ts）。
+ *
+ * 单位约定：manpower 字段为人月（API 直接返回人月）。
+ */
+/**
+ * expandMonths 已移至 util/months.ts，此处不再导出。
+ */
+/** 给每条记录标注 month 字段，返回新数组（不改原数据） */
+export function annotateWithMonth(entries, month) {
+    return entries.map((p) => ({ ...p, month }));
+}
+/**
+ * 按轴聚合人月。
+ * - month：按月份分组（需先用 annotateWithMonth 打标）
+ * - department：按 departmentName 分组，缺失归 "其他"
+ * - role：按 role 分组，缺失归 "其他"
+ * 返回 [{ [axis]: key, manpower }]，manpower 四舍五入到 2 位。
+ */
+export function aggregateByAxis(rows, axis) {
+    const groups = new Map();
+    for (const p of rows) {
+        const k = axis === 'month' ? p.month
+            : axis === 'department' ? (p.departmentName ?? '其他')
+                : (p.role ?? '其他');
+        groups.set(k, (groups.get(k) ?? 0) + (p.manpower ?? 0));
+    }
+    return [...groups.entries()].map(([k, v]) => ({
+        [axis]: k,
+        manpower: Math.round(v * 100) / 100,
+    }));
+}
+/**
+ * 过滤出指定人员的记录：staffId 精确匹配，或 staffName 包含匹配。
+ */
+export function filterByStaff(entries, staffId) {
+    return entries.filter((p) => p.staffId === staffId || p.staffName?.includes(staffId));
+}