老系统接入AI：核心概念地图与三条落地路径

一、教程目标

本教程要帮你完成三件事：

1. 建立概念地图：弄清 Model、Agent、Skill、CLI、MCP 各自是什么、处在哪一层、谁调用谁，不再被术语困扰；
2. 掌握三条接入路径：直连模型 API、把老系统封装成工具经 MCP 接入 Agent、用 CLI 桥接既有脚本，并明确各自适合的场景；
3. 学会验证与排查：每条路径给出可操作的验证方法，以及常见故障的定位思路。

二、适用场景与读者

• 适合读者：后端与运维开发者、系统架构师、技术负责人。不要求具备大模型算法背景，但需要掌握 REST 调用、JSON 结构、命令行操作等基础知识。
• 适合场景：已有稳定运行多年的内部系统（订单、工单、报表、运维脚本等），希望在不大改核心链路的前提下接入 AI 能力；或者团队刚接触 AI 相关术语，需要一张地图加一份选型清单。

三、概念地图：五个概念各是什么、谁调用谁

先给一句话结论：Model 是大脑，Agent 是完整的人，工具是手，MCP 是手与外部世界之间约定的标准接口，Skill 是把一套成熟打法打包的技能包，CLI 是工具最常见的具体形态之一。

3.1 Model（模型）：只负责“想”

模型接收一段结构化输入（消息列表），返回一段输出。它本身不联网、不执行任何动作、没有上下文之外的记忆。常见两类用法：一是对话生成，二是工具调用决策——即根据指令判断“是否需要调用某个工具、传什么参数”。

agent-">3.2 Agent（智能体）：负责“想 + 做 + 循环”

Agent 以模型为推理核心，再加上四件事：任务规划、工具执行、结果观察、循环决策，直到任务完成。关系上要记住：Agent 调用 Model，而不是 Model 调用 Agent，Model 只是 Agent 的一个组件。

3.3 Tool（工具）：Agent 的手

工具是一个可被程序调用的函数或接口，用一份结构化描述（通常基于 JSON Schema）告诉模型“名称、用途、参数”。老系统的查询接口、写入接口、脚本，都可以被包装成工具。

3.4 Skill（技能）：把打法打包

Skill 通常指把“提示词模板 + 执行流程 + 依赖的工具组合”封装成可复用、可分发的能力单元。与工具的区别在于：工具是单个动作，技能是一套完成某类任务的组合方案，技能内部往往还要调用多个工具。

3.5 CLI（命令行接口）：工具的常见形态

CLI 泛指命令行形态的可执行入口。它之所以重要，是因为大量老系统天然存在运维脚本、批处理命令、管理入口。对 Agent 而言，“执行一条命令并读取输出”是最容易标准化的动作，因此 CLI 是老系统接入 AI 性价比很高的切口。

3.6 MCP（模型上下文协议）：工具接入的标准

MCP（Model Context Protocol，模型上下文协议）是业界出现的开放协议之一，目标是统一“模型应用”与“外部能力”之间的连接方式。其基本结构是客户端—服务端模式：Agent 侧持有 MCP 客户端，工具提供方实现 MCP 服务端；服务端通过协议暴露三类原语——工具（可执行动作）、资源（可读取数据）、提示（可复用的指令模板）；通信基于 JSON 消息，常见传输方式包括标准输入输出（适合本地进程）与 HTTP（适合远程服务）。在统一协议出现之前，各 Agent 框架分别定义一套工具接入方式，工具提供方要重复适配；有了统一协议，“一次实现、多处接入”才成为可能。

3.7 调用关系一张图

用户
 │  提出目标
 ▼
Agent（调度与决策循环）
 ├─ 调用 ──► Model（推理：规划、选择工具、生成参数）
 ├─ 加载 ──► Skill（技能包：提示词 + 流程 + 工具组合）
 └─ 调用 ──► MCP 客户端 ──协议──► MCP 服务端
                                      ├─ 工具：执行动作（内部常封装 CLI 或 API）
                                      └─ 资源：读取数据
                                         │
                                         ▼
                                      老系统（数据库 / 服务 / 脚本）
 结果逐层回传 → Agent 观察结果 → 继续决策或汇总输出 → 用户

标准与工具的分层可以这样记：描述层用 JSON Schema 定义工具；连接层用 MCP 这类协议；能力层用 Skill 封装；执行层落到 CLI 或 API。以后看到任何新名词，先问“它在哪一层”，概念就不会乱。

四、前置准备

1. 模型访问：开通一个模型服务并取得访问凭证（可使用百度智能云等模型服务平台提供的通用推理接口，也可使用自建推理服务），建议先在测试环境验证连通性。
2. 运行环境：具备主流脚本运行时，以及到模型服务的网络连通（出网或内网均可，视部署方式而定）。
3. 老系统盘点材料：接口文档、可用命令清单、数据字典、权限说明。
4. 测试账号：老系统的只读或低权限账号，用于先行验证，避免误操作。
5. 基础知识：JSON 结构、REST 调用、命令行操作、超时与重试的基本概念。

五、路径一：直连模型 API——最小改造

适合场景：先落地文本类能力（摘要、分类、信息抽取、文案生成），不动业务链路，风险集中在内容质量而非系统操作。

实施步骤：

1. 圈定 1-2 个高价值低风险场景。选“输出错了也无害”的场景，最容易快速出成果并获得团队信任。
2. 封装统一调用模块。把“拼装消息、设置参数、处理返回、超时重试”收敛到一处，业务代码只传业务字段，避免调用逻辑散落各处。
3. 设置保守参数：temperature 取低值（如 0.1~0.3）保证输出稳定；设置合理超时与有限次重试。
4. 数据脱敏：把姓名、证件号、手机号等敏感字段替换为占位符后再送入模型。
5. 灰度放量：按流量比例逐步开放，记录输入输出样本用于持续评估。

通用伪代码：

function summarize(text):
    safe = desensitize(text)          # 脱敏
    resp = model.chat(
        messages = [
            {role: "system", content: "你是摘要助手，输出不超过200字"},
            {role: "user",   content: safe}
        ],
        temperature = 0.2,
        timeout = 15s, retries = 2
    )
    log(hash(text), resp)             # 留痕，便于审计与评估
    return resp.content

注意：本路径的定位是“辅助判断 + 人工确认”，不要把模型返回直接写库或触发业务动作。

六、路径二：工具化封装，经 MCP 接入 Agent——让 AI 能“操作系统”

适合场景：希望 Agent 能查询、流转工单、提交操作等，直接与老系统交互。

实施步骤：

1. 盘点并筛选工具候选。筛选标准：参数结构清晰、幂等或可回滚、权限可单独授权。查询类工具先行，写入类后置。
2. 为每个工具写“描述三件套”：名称、给模型看的功能说明、参数 Schema。描述质量直接决定模型调用的准确率——写给模型看的话要写清适用条件、取值单位、枚举含义，而不是照搬给人看的接口注释。
3. 实现 MCP 服务端。选择传输方式：与 Agent 同机部署用标准输入输出，跨机器用 HTTP。服务端内部把工具执行转发到老系统的 API 或函数调用。
4. Agent 侧注册 MCP 客户端，加载工具清单。
5. 加安全层：工具级白名单、参数强校验、执行前权限检查、全量审计日志。
6. 端到端联调：先验证工具清单能被枚举，再验证单工具调用，最后跑多轮任务。

工具定义示例（通用 JSON 结构）：

{
  "name": "query_order_status",
  "description": "查询订单当前状态。入参 order_id 为业务单号，形如 SO2024xxxx。仅支持查询近90天订单。",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "业务订单号"}
    },
    "required": ["order_id"]
  }
}

注意：写入类工具务必在描述中显式说明副作用，并在生产环境增加人工确认环节。

七、路径三：CLI 桥接——盘活既有脚本

适合场景：老系统没有好用的 API，但存在大量运维脚本、批处理命令、管理工具。

实施步骤：

1. 整理命令清单：命令名、必选/可选参数、输出格式、危险等级。危险等级决定是否允许 Agent 直接执行。
2. 把命令说明转成结构化工具描述（写法同路径二），让模型理解每个命令的用法与边界。
3. 实现受控执行器：白名单校验、参数转义、超时控制、输出截断。这一层是安全核心，绝不能让模型自由拼接任意命令。
4. 把执行器注册为 Agent 的工具（可直接注册，也可包一层 MCP 服务端，复用给多个 Agent）。
5. 输出结构化：命令结果转换为带明确字段的 JSON 或文本，便于模型读取与总结。

通用伪代码：

ALLOWED  = {"query_log", "backup_report", "list_jobs"}
DANGEROUS = {"restart_service", "purge_cache"}   # 需人工确认
function run_cli(cmd, args):
    if cmd not in ALLOWED + DANGEROUS:
        error("命令不在白名单")
    if cmd in DANGEROUS and not approved_by_human:
        error("等待人工确认")
    result = exec(cmd, args, timeout = 30s)
    return truncate(result.stdout, limit = 4000)  # 防止超长输出撑爆上下文

注意：输出截断很重要——命令行输出动辄上千行，直接送入模型既贵又慢，还会稀释关键信息。

八、三条路径对比与选型

维度	路径一：直连 API	路径二：MCP 工具化	路径三：CLI 桥接
改造成本	低	中	低-中
能力上限	文本理解与生成	可操作系统全流程	依赖既有脚本覆盖面
主要风险	内容质量	误操作、越权	命令副作用
建议起步	所有团队的第一步	有稳定 API 的系统	脚本资产丰富的系统

三条路径不互斥，推荐组合演进：路径一快速见效 → 路径三低成本打通系统操作 → 路径二沉淀为标准工具服务，再逐步向“技能包”形态组织能力。

九、结果验证

• 路径一：抽样评估。固定一组测试输入，人工评分输出质量；对比脱敏前后结果一致性；观察 P95 延迟与失败率是否达标。
• 路径二：分层验证。第一层验证 MCP 握手与工具枚举（能列出全部注册工具即连通）；第二层单工具直调（参数正确、返回结构正确）；第三层端到端任务（Agent 多轮完成一个真实任务）；第四层安全验证（用无权限账号确认调用被拒）。
• 路径三：白名单拦截测试（构造非法命令确认被拒）；危险命令人工确认流程是否生效；同一命令重放验证幂等性；审计日志是否完整可查。

十、常见问题与排查

1. 模型不调用工具：优先检查工具描述是否清晰、参数 Schema 是否有歧义；其次确认所用模型支持工具调用能力；再把任务指令写得更明确。
2. 工具参数错误：多为枚举值、单位、格式未在描述中说明。在描述中补充“取值范围/示例”，通常立竿见影。
3. MCP 连接失败：核对两端传输方式是否一致（本地用标准输入输出、远程用 HTTP）、端口与凭证是否正确；本地方式还要确认服务进程的启动方式。
4. 响应慢：先区分是模型推理慢还是工具执行慢；工具侧加缓存与索引；整体任务改异步与流式输出。
5. 幻觉或误操作：坚持只读优先；写入类动作加人工确认；工具返回中附带明确的“是否成功”字段，减少模型自行猜测。
6. 成本失控：记录每次调用的 token 消耗；对高频重复查询加缓存；简单任务路由到更小的模型执行。

十一、优化建议

• 性能：高频工具结果做缓存；长任务异步化；对工具输出做截断与分页，控制上下文长度。
• 安全：坚持最小权限账号；入参强校验；全链路审计（谁、何时、调用了什么工具、什么参数、什么结果）。
• 稳定性：模型调用设置超时与指数退避重试；工具执行失败时把错误信息回传给模型，让 Agent 自行换路，而不是让整个任务直接崩溃。
• 可维护性：工具描述纳入版本管理，改动后运行回归用例；为每个工具维护 3-5 个标准测试样例。
• 成本控制：按任务难度分流不同规模模型；沉淀技能包固化提示词，减少每次现场探索的 token 消耗。

十二、总结

本文先用一张概念地图厘清了五个高频术语：Model 负责推理、Agent 负责决策与执行循环、工具负责动作、MCP 提供统一连接标准、Skill 是能力封装、CLI 是工具的常见形态；随后给出老系统接入 AI 的三条路径——直连模型 API、工具化封装经 MCP 接入、CLI 桥接，并配套了步骤、示例、验证与排查方法。落地建议是：从低风险场景起步，按“直连 → CLI 桥接 → MCP 工具化”的顺序渐进演进，始终把权限控制、审计留痕和人工确认放在设计的第一优先级。后续可以持续关注统一协议生态的演进、技能包的沉淀方式，以及小模型分流带来的成本优化空间。