aida-cli

CDC 业务 CLI 工具。通过 域 > 资源 > 操作 三层命令结构覆盖 HR、考勤、VMS、薪资 4 个业务域，专为 AI agent 设计。

安装

npm 全局安装

安装前请确保本机 Node.js 版本 >= 18。

npm install -g aida-cli

安装完成后验证：

aida --help
aida doctor

GitHub 一键安装

也可以使用仓库安装脚本：

curl -fsSL https://raw.githubusercontent.com/swiftwind0405/aida-cli/master/install.sh | bash

如果当前网络不能直接访问 raw 文件，也可以 clone 仓库后执行：

./install.sh

安装指定版本：

curl -fsSL https://raw.githubusercontent.com/swiftwind0405/aida-cli/master/install.sh | AIDA_VERSION=0.0.3 bash

安装脚本会从 npmjs 全局安装 aida-cli，并验证 aida 命令可用。

更新

更新到最新版本：

aida update

更新到指定版本：

aida update 0.0.4

只查看将执行的更新命令，不实际安装：

aida --dry-run update

更新命令默认使用 npmjs：

npm install -g aida-cli@latest --registry=https://registry.npmjs.org/

如需临时切换 registry 或包名，可以设置 AIDA_NPM_REGISTRY / AIDA_PACKAGE。

开发者本地安装

pnpm install
pnpm build

环境与认证配置

CLI 支持多环境 profile，每个 profile 独立保存 API 地址和 token。配置文件位于 ~/config/aida/config.json。

管理环境

# 创建 / 更新环境
aida config set dev     --api-url http://localhost:8080 --token xxx
aida config set staging --api-url https://staging.example.com --token yyy
aida config set prod    --api-url https://api.example.com --token zzz

# 切换当前环境
aida config use staging

# 查看当前配置
aida config show

# 列出所有环境
aida config list

# 删除环境
aida config delete staging

临时切换环境

通过 --env 全局选项临时指定环境，不修改配置文件：

aida --env prod hr employee list

环境变量覆盖

环境变量优先级最高，适合 CI/CD 场景：

export CDC_TOKEN="你的 Access-Token"
export CDC_API_URL="https://dev.example.com"
export AIDA_CONFIG_PATH="/path/to/config.json"

优先级

| 配置项 | 优先级（高 → 低） | |--------|-------------------| | Token | CDC_TOKEN 环境变量 → 当前 profile 的 token | | API URL | CDC_API_URL 环境变量 → --env 指定 profile → 当前 profile → 内置默认值 | | 配置文件 | AIDA_CONFIG_PATH 环境变量 → ~/config/aida/config.json |

配置文件格式

~/config/aida/config.json：

{
  "current": "dev",
  "profiles": {
    "dev": {
      "apiUrl": "http://localhost:8080",
      "token": "your-dev-token"
    },
    "staging": {
      "apiUrl": "https://staging.example.com",
      "token": "your-staging-token"
    }
  }
}

Agent 使用

Repo-local Skill

本仓库和 npm 包都包含 skills/cdc-cli-usage/SKILL.md，用于指导 agent 安装、配置、发现命令、执行只读查询、dry-run 变更和排查 CLI 使用问题。

安装配置 Prompt

可以把下面这段 prompt 直接交给 Agent，让它自动安装 CLI、引导配置，并完成只读自检：

请帮我在当前电脑上安装并配置 aida-cli。

目标：
1. 确认本机 Node.js 版本 >= 18。
2. 安装 aida-cli。优先使用 npm：
   npm install -g aida-cli
   也可以使用官方安装脚本：
   curl -fsSL https://raw.githubusercontent.com/swiftwind0405/aida-cli/master/install.sh | bash
   如果 raw 文件不可访问，则引导我 clone 仓库后运行 ./install.sh。
3. 如果当前上下文能访问 aida-cli 仓库，请启用并读取 repo-local skill：
   skills/cdc-cli-usage/SKILL.md
   如果 `.agents/skills` 不存在，请在仓库内建立 `.agents/skills -> ../skills` 软链，确保后续 agent 能发现该 skill。
4. 安装完成后验证 aida 命令可用。
5. 引导我配置 CLI profile。配置命令格式：
   aida config set <env> --api-url <url> --token <token>
   如果我没有提供 env、API URL 或 token，请先向我询问，不要猜测。
6. 配置后执行只读自检：
   aida --help
   aida config show
   aida doctor
   aida list-tools --compact
   aida command-info payroll structure list --compact
7. 最后告诉我 CLI 是否安装成功、当前 profile 是什么、API URL 来源是什么、token 是否已配置、是否已启用 cdc-cli-usage skill。

注意：
- 不要把 token 明文输出到最终结果。
- 不要为了验证而调用新增、删除、保存、审批、发布等变更类业务命令。
- 如果安装、认证或 npm 权限失败，请给出具体失败原因和下一步需要我提供的信息。

发现能力

# 列出所有可用命令及参数（结构化 JSON）
aida list-tools

# 按域/类型/关键字过滤，单行 JSON 更适合 agent
aida list-tools --domain payroll --kind mutation --search structure --compact

# 查看单个命令的参数 schema、安全属性和示例
aida command-info payroll structure save

输出示例：

{
  "name": "aida",
  "version": "0.0.1",
  "globalOptions": [
    { "flag": "--format <type>", "description": "输出格式：json | table", "default": "json", "required": false },
    { "flag": "--env <env>", "description": "临时切换目标环境 profile", "required": false }
  ],
  "commands": [
    {
      "command": "hr employee list",
      "description": "查询员工列表",
      "options": [
        { "flag": "--page <page>", "description": "页码", "default": "1", "required": false },
        { "flag": "--size <size>", "description": "每页条数", "default": "20", "required": false },
        { "flag": "--keywords <keywords>", "description": "搜索关键字", "required": false }
      ],
      "example": "aida hr employee list",
      "metadata": {
        "domain": "hr",
        "resource": "employee",
        "action": "list",
        "kind": "query",
        "mutation": false,
        "dangerous": false,
        "dryRunSupported": false,
        "outputSchema": {
          "format": "json",
          "lowTokenOptions": ["--compact", "--fields <fields>", "--summary"]
        }
      }
    }
  ]
}

Agent 辅助命令

# 常用业务配方
aida recipes list
aida recipes info payroll-run

# CLI 使用指南
aida guide

# 诊断 token、API URL 和配置来源，不泄露 token 内容
aida doctor

调用命令

# 查询员工列表（JSON 输出）
aida hr employee list

# 查询员工列表（单行 JSON，且只输出指定字段）
aida --compact --fields id,name,status hr employee list

# 查询大列表摘要
aida --summary payroll structure list

# 查询员工列表（表格输出）
aida --format table hr employee list

# 查询员工详情
aida hr employee get --id 123

# 入职流程编排
aida hr onboard --name "张三" --position "前端开发" --org-id 456

# 复杂 JSON 使用文件或 stdin，避免 shell 转义问题
aida payroll structure save --data @payload.json
cat payload.json | aida payroll structure save --data -

# 变更类命令可先 dry-run；高风险命令建议显式加 --yes
aida --dry-run payroll structure delete --id 123
aida --yes payroll structure delete --id 123

退出码

| 退出码 | 含义 | agent 处理建议 | |--------|------|----------------| | 0 | 成功 | 解析 stdout JSON | | 1 | 业务错误（API 返回错误） | 解析 stderr JSON 获取错误详情 | | 2 | 认证失败（token 缺失/过期） | 提示用户运行 config set 或设置 CDC_TOKEN | | 3 | 参数错误（缺少必填参数等） | 检查命令参数，重新调用 |

错误输出格式

错误始终以结构化 JSON 输出到 stderr：

{"error": {"code": "AUTH_FAILED", "message": "未配置认证 token。请设置 CDC_TOKEN 环境变量或运行 aida config set <env> --token <token>", "hint": "运行 aida doctor 检查配置来源", "retryable": false}}

全局选项

| 选项 | 说明 | 默认值 | |------|------|--------| | --format <type> | 输出格式：json / table | json | | --env <env> | 临时切换目标环境 profile（覆盖 config 中的 current） | - | | --compact | JSON 单行输出，减少 agent token 消耗 | false | | --fields <fields> | 仅输出指定字段，多个字段用逗号分隔，支持点路径 | - | | --summary | 输出摘要结果，适合列表或大对象 | false | | --dry-run | 对变更类命令只返回将要执行的操作，不调用后端 | false | | --yes | 显式确认执行高风险变更命令 | false |

业务域命令

| 域 | 命令前缀 | 资源 | 流程编排 | |------|----------|------|----------| | HR | hr | employee, organization | hr onboard | | 考勤 | attendance | leave | attendance leave-flow | | VMS | vms | project, supplier | vms project-flow | | 薪资 | payroll | structure, sob | payroll payroll-run |

流程编排

流程编排命令串联多个原子 API 调用，中间结果自动传递。错误策略为 report-and-stop：任一步骤失败时输出已完成步骤的结果和失败信息，不回滚不重试。

# HR 入职流程：创建员工 → 更新任职信息
aida hr onboard --name "张三" --position "前端开发"

# 考勤请假流程：申请 → 查看列表
aida attendance leave-flow --type "年假" --start 2026-06-01 --end 2026-06-03

# VMS 项目全流程：创建项目 → 质量考核
aida vms project-flow --name "XX项目" --supplier-id 789

# 薪资核算流程：启动核算 → 查询进度 → 查看明细
aida payroll payroll-run --sob-id <账套ID> --detail

Codegen

从后端 Swagger spec 生成 action 函数：

# 自动扫描 specs/ 目录下的所有 JSON 文件
pnpm codegen

# 指定 Swagger spec 文件
pnpm codegen --spec specs/hr-api.json --spec specs/vms-api.json

生成产物在 src/generated/{domain}/，标记为 @generated，重新生成时整体覆盖。手动扩展逻辑写在 src/actions/{domain}/。

架构

commands/            ← CLI 命令路由（commander 注册）
  commands/config/   ← 环境 profile 管理命令
    ↓
  actions/           ← 手动编写层（业务逻辑 + 流程编排）
    ↓
 generated/          ← codegen 产物（原子 action 函数）
    ↓
   http/             ← Node-safe axios 适配器
   config/           ← 多环境 profile 管理（~/config/aida/）
    ↓
 后端微服务 API

开发

# 开发时直接跑 TS 源码
npx tsx bin/aida.ts --help
npx tsx bin/aida.ts hr employee list

# watch 模式构建
pnpm dev

# 生产构建
pnpm build

# 运行 codegen
pnpm codegen

# 运行测试
pnpm test

# 类型检查
pnpm typecheck

发布到 npm

包名为 aida-cli，发布到 npmjs。GitHub Actions 会在推送 v* tag 时运行 npm ci、npm run typecheck、npm test，然后执行公开发布。

仓库需要配置 NPM_TOKEN secret，且 npm 账号需要拥有 @cdc scope 的发布权限。

npm version patch
git push origin master --tags

全局 link

pnpm build
pnpm link --global
aida --help

取消全局 link：

pnpm uninstall --global aida-cli