TypeScript · Node.js · CLI Agent · MCP

把 AI Agent 运行链路
浓缩进一个可读、可讲、可扩展的终端项目

QX Agent CLI 是一个轻量级但结构完整的 AI Agent 命令行项目：从命令入口、配置解析、Provider 抽象，到多步 Agent 循环、工具调用、MCP 集成与本地 Skills 自动加载，适合做学习样板、二次开发底座，以及面试/简历展示项目。

查看运行链路 了解 Provider / Tools / MCP / Skills
CLI First 交互式 REPL 与 one-shot 命令共存，适合真实终端使用场景。
Agentic 支持多步推理、工具调用、会话落盘与任务上下文注入。
Extensible 可扩展 Provider、内置 Tools、MCP 工具和本地 Skills。 
$ qx-agent chat "summarize this repo"

> load config
> create provider: deepseek / openai-compatible / mock
> load built-in tools
> connect MCP servers from mcp.config.json
> auto-select local skills from skills/
> run multi-step agent loop
> save session under .qx-agent/sessions/

Result:
A compact TypeScript AI agent CLI with a clear runtime path,
provider abstraction, tool calling, MCP integration,
and local skill loading.
Highlights

为什么这个项目适合做展示页主角

它不是只有“调 API”的玩具脚手架，而是把一个 Agent CLI 的关键组成模块都串了起来，既能跑起来，也能清楚说明设计边界。

完整运行链路

入口位于 src/index.ts，进入 src/entrypoints/cli.ts 做参数解析、命令选择与配置加载，然后转入具体命令执行。

Provider 抽象清晰

src/providers/index.ts 统一创建 Provider，当前支持 mock 与 OpenAI-compatible / DeepSeek 模式，便于替换底层模型服务。

扩展点足够真实

内置工具、MCP 远程工具、本地 Skills 三层扩展同时存在，既体现工程化能力，也方便演示 Agent 系统的可组合性。

Architecture

从命令入口到 Agent 循环的运行路径

项目结构紧凑，阅读成本低，但包含了一个终端 Agent 实际运行时最重要的几个环节。

1

Entrypoint

src/index.ts 调用 CLI 主入口，作为可执行命令 qx-agent 的启动点。

2

CLI & Commands

src/entrypoints/cli.ts 解析 argv、识别命令，并通过命令注册表分发到 chat、mcp、skills 等模块。

3

Config

配置按默认值、用户目录、本地项目、环境变量、CLI 参数顺序合并，支持 provider、model、session、skillsDir、mcpConfigPath 等项。

4

Agent Loop

src/agent/runAgent.ts 负责系统提示词构造、消息拼接、模型请求、工具执行、事件回调与会话持久化。

5

Persistence

Session 与任务数据写入项目作用域存储，使 REPL、one-shot 和多轮操作之间能共享上下文。

Provider / Tools

模型接入与工具能力

这部分最适合向面试官说明“我不只是会调模型，而是把模型能力装进一个可控执行框架里”。

Provider 抽象

src/providers/index.ts 根据配置创建 Provider；默认走 OpenAI-compatible 适配层，也支持 mock 进行离线 smoke test。

Built-in Tools

src/tools/index.ts 统一注册 list_files、glob_files、search_files、grep_files、read_file、edit_file、write_file、todo_write、web_search、web_fetch、shell_command。

多步执行

Agent 可在一个会话内多次请求模型、触发工具、接收工具结果，再继续推进任务，形成标准的 tool-calling loop。

MCP / Skills

远程工具协议与本地能力注入

这两部分使项目从“命令行聊天工具”升级为“可扩展 Agent 容器”。

MCP Runtime

src/mcp/manager.ts 负责读取 mcp.config.json、连接 server、拉取 tools，并把远程 MCP 工具转换为统一 ToolDefinition。

Local Skills

src/skills/loadSkills.ts 会从 skills/ 自动加载 Markdown skill，解析 frontmatter，抽取名称、描述与 triggers，供运行时按 prompt 选择。

Prompt-level Guidance

Skills 更像可组合的行为说明书，适合放入 code-review、project-summary 这类任务导向规则，提升 Agent 的稳定输出风格。

Use Cases

适合展示的应用场景

如果你要做作品集页面，这些场景可以直接拿来作为项目价值说明。

学习 Agent 架构

项目体量比成熟框架小很多，但保留了 Provider、Tool Calling、Session、MCP、Skills 等关键概念，便于完整读懂。

做二次开发底座

你可以继续接入新的 provider、文件系统能力、浏览器自动化工具，或把 skill 系统接到企业内部规范上。

面试与简历表达

它非常适合回答“你是如何组织一个 AI Agent 项目的”这类问题，因为每个模块都有明确文件位置与职责边界。

Resume-friendly

可以直接复用到简历/项目介绍中的表达

下面这段话适合作为项目简介、作品集描述或答辩开场白。

基于 TypeScript / Node.js 独立实现轻量级 AI Agent CLI，完成从命令入口、配置合并、Provider 抽象到多步 Agent 执行循环的完整链路；集成文件/搜索/Web/Shell 等内置工具，支持通过 MCP 挂载外部工具，并通过本地 Skills 机制实现任务级提示词增强与自动匹配，具备良好的可读性、可扩展性与演示价值。

  • 适合强调：工程拆分能力、Agent runtime 理解、Prompt orchestration、可扩展架构设计。
  • 适合关键词：TypeScript、Node.js、OpenAI-compatible、DeepSeek、MCP、Tool Calling、CLI、REPL。
  • 适合演示方式：现场运行 qx-agent chat、展示 mcp tools、说明 skills/ 自动加载机制。