CI-First AI Agent CLI 工具

agent-mini 是一个极简的 AI Agent CLI 工具，具备 ReAct 推理循环、8 个内置工具、技能系统和会话持久化。

# 交互模式
npc

# 单次调用
npc agent --message "帮我查看 package.json"

# JSON 格式输出（方便程序化调用）
npc agent --json --message "列出当前目录的文件"

# 指定会话 ID（多轮对话复用）
npc agent --message "继续上次的任务" --session-id "my_session"

# 外部注入 system prompt
npc agent --message "评审这个 PR" --system-prompt "你是代码评审专家"

# 图片识别（需配置 vision，见下方说明）
npc agent --message "帮我识别这张图片" --images https://example.com/screenshot.png

# 多张图片
npc agent --message "对比这两张截图的差异" --images https://example.com/before.png https://example.com/after.png

# 图片 + JSON 输出
npc agent --json --message "识别图片中的文字" --images https://example.com/doc.png

# 测试模式
npc --test

参数	缩写	说明
agent	-	子命令，进入单次调用模式
--message	-m	发送的消息内容
--session-id	-s	会话 ID（默认 cli:local）
--system-prompt	-	外部注入的 system prompt
--json	-	JSON 格式输出
--test	-	测试模式，发送测试消息后退出

多来源配置，优先级：CLI 参数 > 环境变量 (.env) > 配置文件 (npc.json) > 默认值

配置文件按顺序查找：$NPC_CONFIG_PATH → ./npc.json → ~/.npc/npc.json

只需指定 API Key 和 Base URL 即可运行：

{
  "agent": {
    "defaultModel": "deepseek-chat",
    "providers": {
      "openai": {
        "apiKey": "sk-xxx",
        "baseUrl": "https://api.deepseek.com/v1"
      }
    }
  }
}

NPC 支持任何 OpenAI 兼容的 API 端点。通过 npc.json 的 agent.providers 字段配置。

字段	类型	必填	说明
agent.defaultModel	string	否	全局默认模型名（默认 gpt-4o）
agent.provider	string	否	首选 provider 名（对应 providers 中的 key）
agent.providers.<name>.apiKey	string	是	API 密钥，支持 ${ENV_VAR} 环境变量模板
agent.providers.<name>.baseUrl	string	否	API 基础 URL，支持 ${ENV_VAR} 环境变量模板
agent.providers.<name>.model	string	否	Provider 级模型名，优先于 defaultModel
agent.providers.<name>.type	string	否	openai / openai-compatible / anthropic（不填则自动推断）

{
  "agent": {
    "defaultModel": "deepseek-chat",
    "providers": {
      "openai": {
        "apiKey": "sk-xxx",
        "baseUrl": "https://api.deepseek.com/v1"
      }
    }
  }
}

{
  "agent": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx",
        "model": "claude-sonnet-4-20250514"
      }
    }
  }
}

{
  "agent": {
    "providers": {
      "openai": {
        "apiKey": "any-value",
        "baseUrl": "http://localhost:11434/v1",
        "model": "llama3",
        "type": "openai-compatible"
      }
    }
  }
}

可以配置多个 provider，通过 agent.provider 指定使用哪个：

{
  "agent": {
    "provider": "deepseek",
    "providers": {
      "openai": {
        "apiKey": "sk-openai-xxx",
        "baseUrl": "https://api.openai.com/v1",
        "model": "gpt-4o"
      },
      "deepseek": {
        "apiKey": "sk-deepseek-xxx",
        "baseUrl": "https://api.deepseek.com/v1",
        "model": "deepseek-chat",
        "type": "openai-compatible"
      },
      "anthropic": {
        "apiKey": "sk-ant-xxx",
        "model": "claude-sonnet-4-20250514"
      }
    }
  }
}

不指定 agent.provider 时，自动选择优先级：anthropic > openai > 其他（取第一个有 apiKey 的）。

配置文件中的字符串值支持 ${VAR_NAME} 语法引用环境变量，避免明文密钥：

{
  "agent": {
    "providers": {
      "openai": {
        "apiKey": "${MY_API_KEY}",
        "baseUrl": "${MY_BASE_URL}",
        "model": "gpt-4o"
      }
    }
  }
}

在项目根目录的 .env 文件或系统环境变量中设置：

MY_API_KEY=sk-xxxxxxxxxxxx
MY_BASE_URL=https://api.openai.com/v1

未显式设置 type 时，系统按以下规则自动推断：

条件	推断为
model 名包含 claude	anthropic
model 名包含 gpt 或匹配 o1/o3	openai
有 baseUrl 且 URL 包含 anthropic	anthropic
有 baseUrl（其他情况）	openai-compatible
都不匹配	openai-compatible（兜底）

当主模型不支持图片识别时，可配置独立的视觉模型。图片会先由 vision 模型识别为文本描述，再发给主模型处理。不配置则直接透传图片给主模型（要求主模型本身支持 vision）。

{
  "agent": {
    "defaultModel": "deepseek-chat",
    "providers": {
      "openai": { "apiKey": "sk-xxx", "baseUrl": "https://api.deepseek.com/v1" }
    },
    "vision": {
      "model": "gpt-4o",
      "provider": {
        "apiKey": "sk-xxx",
        "baseUrl": "https://api.openai.com/v1"
      }
    }
  }
}

字段	说明
vision.model	视觉模型名称，如 gpt-4o / glm-4v-plus / qwen-vl-max
vision.provider.apiKey	可选，不配则复用主 provider 的 apiKey
vision.provider.baseUrl	可选，不配则复用主 provider 的 baseUrl

除了配置文件，也可以直接通过环境变量配置（优先级高于配置文件）：

# 基础配置
OPENAI_API_KEY=sk-xxx              # → providers.openai.apiKey
LLM_BASE_URL=https://api.xxx/v1   # → providers.openai.baseUrl（type 自动改为 openai-compatible）
LLM_MODEL=gpt-4o                  # → agent.defaultModel
LLM_PROVIDER=openai               # → agent.provider

# Anthropic
ANTHROPIC_API_KEY=sk-ant-xxx       # → providers.anthropic.apiKey
ANTHROPIC_BASE_URL=https://...     # → providers.anthropic.baseUrl

# 可选
BRAVE_SEARCH_API_KEY=xxx           # 启用 Brave 搜索

# Vision（可选）
VISION_MODEL=gpt-4o
VISION_API_KEY=sk-xxx
VISION_BASE_URL=https://api.openai.com/v1

NPC 内置了一套技能系统，允许你通过 SKILL.md 文件为 Agent 注入领域知识、工作流程和自定义工具，无需修改源代码。

Skills 从以下目录自动加载，后加载的同名 skill 会覆盖先加载的：

优先级	目录	说明
1（最低）	<安装目录>/skills/bundled/	内置 skills
2	~/.npc/skills/	全局用户 skills
3	<项目>/skills/	项目级 skills
4（最高）	配置文件 skills.dirs 中指定的目录	自定义额外目录

每个 skill 是一个独立目录，必须包含 SKILL.md 文件：

skills/
└── my-skill/
    ├── SKILL.md          # 必须：技能定义文件
    ├── tools/            # 可选：自带工具
    │   └── my-tool.js
    └── scripts/          # 可选：脚本

SKILL.md 使用 YAML frontmatter + Markdown 正文。frontmatter 定义元数据，正文作为 prompt 注入到 Agent 的 system prompt 中：

---
name: my-skill # 必填：技能唯一标识
description: 我的自定义技能 # 必填：技能描述
version: "1.0" # 可选：版本号
requires: # 可选：运行条件检查
  bins: [node, npm] #   依赖的系统命令
  env: [MY_API_KEY] #   依赖的环境变量
os: [darwin, linux] # 可选：支持的操作系统
tools: # 可选：自带工具声明
  - name: my_tool
    file: ./tools/my-tool.js
depends: # 可选：依赖其他 skill
  - name: other-skill
    optional: true
---
## 你是 XXX 专家

这里写 prompt 正文，会自动注入到 Agent 的 system prompt 中。
可以包含工作流程、规范、示例等任何 Markdown 内容。

Skill 可以声明自带工具（JS 模块），工具需要导出一个符合 Tool 接口的对象：

// tools/my-tool.js
export default {
  name: "my_tool",
  description: "我的自定义工具",
  parameters: {
    type: "object",
    properties: {
      input: { type: "string", description: "输入参数" },
    },
    required: ["input"],
  },
  async execute(params) {
    // 实现逻辑...
    return { success: true, output: "执行结果" };
  },
};

在 npc.json 中通过 skills 字段配置：

{
  "skills": {
    "dirs": ["./my-skills", "/path/to/shared-skills"],
    "entries": {
      "my-skill": {
        "apiKey": "${MY_SKILL_API_KEY}",
        "env": { "CUSTOM_VAR": "value" },
        "disabled": false
      }
    }
  }
}

字段	类型	说明
skills.dirs	string[]	额外的技能搜索目录
skills.entries.<name>.apiKey	string	注入到该技能的 API Key，支持 ${ENV} 模板
skills.entries.<name>.env	Record<string, string>	注入到该技能的环境变量
skills.entries.<name>.disabled	boolean	设为 true 禁用该技能

1. 创建目录和文件：

mkdir -p skills/code-review

2. 编写 skills/code-review/SKILL.md：

---
name: code-review
description: 代码评审专家，遵循团队规范进行代码审查
version: "1.0"
---
## 代码评审规范

你是一个代码评审专家，在评审代码时请遵循以下规范：

1. **命名规范**：变量使用 camelCase，常量使用 UPPER_SNAKE_CASE
2. **错误处理**：所有异步操作必须有错误处理
3. **性能**：避免不必要的重渲染和内存泄漏
4. **安全**：检查 SQL 注入、XSS 等安全隐患

3. 启动 NPC，skill 会自动加载。

支持从 Git 仓库同步 skills：

{
  "skills": {
    "remotes": [
      {
        "url": "https://cnb.cool/org/skills-repo.git",
        "path": "skills/",
        "ref": "main"
      }
    ]
  }
}

远程 skills 会浅克隆到 ~/.npc/skills-cache/ 目录，支持增量更新。

开发模式下，修改 SKILL.md 文件会自动触发热重载，无需重启 Agent。

docker build -t npc .
docker run -it npc
docker run npc agent --message "列出文件"

MIT