# 灵犀 AI Agent：智能体工厂与多模型接入深度解析

> 本文是灵犀 AI Agent 系列专栏的第二篇，将深入探讨智能体工厂的设计理念、五步创建向导的实现思路、17 个内置模板的设计逻辑，以及 14+ 家模型供应商统一接入的架构设计。
>
> GitHub 地址：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)

---

## 一、智能体工厂：不只是换个 System Prompt

很多 AI 应用对"智能体"的实现非常粗暴——就是换一段 System Prompt。灵犀的智能体工厂远不止于此。每个智能体是一个**完整的配置实体**，独立拥有 8 个维度的定制能力：

| 维度 | 说明 | 技术实现 |
|------|------|---------|
| 身份定义 | 名称、头像、描述 | `agents` 表：`name`, `avatar`, `description` |
| 角色设定 | System Prompt | `agents.system_prompt` |
| 专属模型 | 可绑定特定接入点 | `agents.profile_id` → `api_profiles` |
| 技能装备 | 已安装技能的子集 | `agents.skill_ids` (JSON 数组) |
| MCP 工具 | 可用 MCP 服务列表 | `agents.mcp_server_ids` (JSON 数组) |
| 知识库绑定 | 可访问的知识库 | `agents.knowledge_ids` (JSON 数组) |
| 参数调节 | temperature / max_tokens | `agents.temperature`, `agents.max_tokens` |
| 对外设置 | Nexus 协作能力标签、授权级别 | `agent_nexus_configs` 表 |

这种设计意味着，你可以创建一个"代码审查员"智能体：使用 Claude 3.5 模型、装备 Git 相关技能、绑定项目文档知识库、temperature 设为 0.1（更精确）、max_tokens 设为 8192——它就是一个专注于代码审查的专业 Agent。

### 1.1 数据模型设计

```go
// backend-desktop/model/model.go
// Agent 的核心数据模型精心设计了每个字段

type Agent struct {
    ID           int64  `json:"id"`
    Name         string `json:"name"`
    Avatar       string `json:"avatar"`
    Description  string `json:"description"`
    SystemPrompt string `json:"system_prompt"`
    ProfileID    int64  `json:"profile_id"`     // 关联接入点
    SkillIDs     string `json:"skill_ids"`      // JSON 数组
    MCPServerIDs string `json:"mcp_server_ids"` // JSON 数组
    KnowledgeIDs string `json:"knowledge_ids"`  // JSON 数组
    AllowAll     bool   `json:"allow_all"`      // 是否允许所有技能
    Temperature  float64 `json:"temperature"`   // 0 表示使用模型默认值
    MaxTokens    int    `json:"max_tokens"`     // 0 表示不限制
    PostActions  string `json:"post_actions"`   // 工作流后续动作
    Builtin      bool   `json:"builtin"`        // 是否内置
}
```

注意 `PostActions` 字段——这是为工作流编排预留的扩展点。一个智能体执行完任务后，可以链式触发下一步动作，形成自动化流水线。

### 1.2 内置的默认智能体

灵犀出厂自带一个默认智能体——"灵犀助理"。它的 System Prompt 长达 200+ 行，精心设计了以下行为规范：

**语言硬规则**：所有输出必须使用中文，包括思考过程（thinking）。这解决了很多 AI 应用中"AI 用英文思考然后翻译"导致回答不自然的问题。

**身份保护**：即使用户追问"你是什么模型"、"你用的是 Claude 吗"，灵犀也会统一回答"我是灵犀 AI 助理"。这是通过 System Prompt 中的保密规则实现的，而非代码层面的过滤。

**行动优先**：灵犀的默认行为模式是"直接动手"。收到"查看我的电脑配置"这类请求时，不会反问"你是 Mac 还是 Windows"，而是直接执行 `uname -a` 等命令自行判断。

```
收到用户消息 → 能直接答？→ 直接答
                ↓ No
          需要本机信息？→ 调用工具去做
                ↓ No
          复杂规划型？→ 提供规划模式选择
                ↓ No
          缺少必要参数？→ 反问用户
```

<!-- 截图占位：默认智能体对话效果 -->
![默认智能体对话](images/智能体对话效果.png)

---

## 二、五步引导式创建向导

灵犀提供了一个五步创建向导，引导用户从零构建专属智能体。每一步都经过精心设计，降低使用门槛的同时不牺牲灵活性。

### 第一步：身份设定

选择头像（26 个精选 emoji）、输入名称和描述。这一步看似简单，但对用户体验至关重要——给 AI 一个"身份"，用户会更倾向于信任和使用它。

```jsx
const EMOJIS = ['✦', '🤖', '🎯', '🧠', '💼', '🚀', '🎨', '📊', 
                '🔬', '⚡', '🌟', '🦾', '🔥', '💡', '🎓', '🛡️', 
                '🗃️', '🌐', '✍️', '📋', '💪', '💰', '✈️', '⚖️', 
                '🤝', '📝'];
```

### 第二步：角色设定（System Prompt）

这是智能体的灵魂。用户可以：
- 手动编写 System Prompt
- 从 4 个快速模板中选择（销售助理、代码审查员、产品经理、内容创作者）
- 从模板市场的 17 个模板中选择

系统提供了一个完整的 Textarea 编辑器，支持 Markdown 格式的 System Prompt。

### 第三步：能力配置

绑定技能、MCP 工具和知识库。这一步会列出用户已安装的所有资源，通过多选框进行勾选。

### 第四步：对外设置（Nexus 协作）

如果这个智能体需要参与 Agent 间对话（Project Nexus），可以配置：
- 是否公开可发现
- 能力标签（如"代码审查"、"产品设计"）
- 授权级别
- 禁止透露的敏感信息

### 第五步：预览与确认

汇总所有配置，预览智能体卡片的最终效果，确认后保存。

<!-- 截图占位：五步创建向导界面 -->
![五步创建向导](images/五步创建向导.png)

---

## 三、17 个模板市场：覆盖四大场景

灵犀的模板市场按四大场景分类，每个模板都精心设计了 System Prompt：

### 3.1 商业办公（4 个模板）

| 模板 | 定位 | System Prompt 要点 |
|------|------|-------------------|
| 销售助理 | 产品话术、客户跟进、商务邮件 | "语气专业、温暖、富有亲和力" |
| 商业分析师 | 数据分析、市场研究、竞品对比 | "回答要有数据支撑、逻辑清晰、可操作性强" |
| 人力资源 | JD 撰写、面试问题、员工管理 | "注重合规、关注团队文化" |
| 法务顾问 | 合同审阅、法律风险、条款建议 | "回答严谨专业、注意免责声明" |

### 3.2 技术开发（5 个模板）

| 模板 | 定位 | System Prompt 要点 |
|------|------|-------------------|
| 代码审查员 | 代码审查、性能优化、最佳实践 | "指出问题时简洁、精确，给出可执行的修改建议" |
| 架构师 | 系统设计、技术选型、可扩展方案 | "兼顾当下可行性与长远演进" |
| DevOps 专家 | CI/CD、Docker、K8s、监控 | "提供可直接执行的命令和配置" |
| 安全工程师 | 漏洞分析、安全审计、加固方案 | "注重实操、提供修复优先级建议" |
| DBA | SQL 优化、数据库设计、故障排查 | "精通 MySQL、PostgreSQL、Redis" |

### 3.3 内容创意（4 个模板）

| 模板 | 定位 | System Prompt 要点 |
|------|------|-------------------|
| 内容创作者 | 公众号、小红书、视频脚本 | "语言生动、有感染力，关注流量与用户共鸣" |
| 文案策划 | 品牌文案、广告语、营销策划 | "文风灵活多变，能根据品牌调性切换风格" |
| 翻译专家 | 中英互译、本地化、技术文档 | "注重信达雅，保留原文语气与风格" |
| 学术论文助手 | 论文润色、文献综述、方法论 | "遵循学术规范、引用格式正确、逻辑严密" |

### 3.4 生活效率（4 个模板）

| 模板 | 定位 | System Prompt 要点 |
|------|------|-------------------|
| 产品经理 | 需求拆解、PRD 撰写、用户研究 | "关注用户价值与可行性" |
| 健身教练 | 训练计划、饮食建议、运动科学 | "基于运动科学，安全第一" |
| 理财顾问 | 投资分析、理财规划、风险评估 | "客观中立，强调风险提示" |
| 旅行规划师 | 行程规划、签证攻略、当地推荐 | "根据用户偏好和预算给出个性化方案" |

每个模板的 System Prompt 都遵循一个设计原则：**明确角色定位 + 行为约束 + 输出风格**。这三要素决定了一个智能体的"人设"是否立得住。

### 3.5 模板的导入导出

灵犀支持智能体的 JSON 格式导出和导入。导出的 JSON 包含完整的配置信息：

```json
{
    "_type": "lingxi-agent-export",
    "_version": 1,
    "name": "代码审查员",
    "avatar": "🔍",
    "description": "代码审查、性能优化、最佳实践",
    "system_prompt": "你是资深工程师...",
    "temperature": 0.1,
    "max_tokens": 8192
}
```

这意味着用户可以分享自己精心调教的智能体配置，或从社区导入他人的智能体。

---

## 四、多模型多供应商接入

灵犀支持 14+ 家模型供应商，这不是简单地调用不同的 API——背后是一套完整的多协议路由架构。

### 4.1 支持的供应商

| 协议 | 供应商 | 代表模型 |
|------|--------|---------|
| **Anthropic 原生** | Anthropic 官方 | Claude 3.5 Sonnet, Claude 3 Opus |
| | DashScope（阿里云） | Claude 代理 |
| **OpenAI 兼容** | DeepSeek | DeepSeek V3, DeepSeek R1 |
| | Qwen（通义千问） | Qwen-Max, Qwen-Plus |
| | 豆包（字节） | Doubao-pro |
| | GLM（智谱） | GLM-4 |
| | Kimi（月之暗面） | Moonshot-v1 |
| | Gemini（Google） | Gemini Pro, Gemini Ultra |
| | OpenRouter | 聚合多模型 |
| | Groq | LLaMA 系列（高速推理） |
| | SiliconFlow | 国产模型聚合 |
| | Ollama | 本地模型（LLaMA, Mistral, Phi...） |
| | OpenAI | GPT-4, GPT-4o |

### 4.2 接入点（API Profile）管理

每个接入点包含完整的连接信息：

```
┌─────────────────────────────────────┐
│  接入点配置                          │
├─────────────────────────────────────┤
│  名称：DeepSeek V3                  │
│  供应商协议：openai_compatible       │
│  Base URL：https://api.deepseek.com │
│  模型：deepseek-chat                │
│  API Key：sk-*** (加密存储)          │
│  状态：已激活 ✓                      │
└─────────────────────────────────────┘
```

用户可以创建多个接入点，并随时一键切换。切换时，Electron 层会自动将新接入点的解密密钥推送给 Go 后端。

### 4.3 连通性测试

每个接入点都可以执行连通性测试。灵犀会发送一个简单的测试请求到供应商 API，验证 Base URL、API Key 和模型名称是否正确。

```
POST /api/api-profiles/:id/test

→ 发送测试消息到供应商 API
→ 验证返回是否正常
→ 返回延迟、模型信息
```

<!-- 截图占位：接入点管理界面 -->
![接入点管理](images/接入点管理截图.png)

### 4.4 Bridge 路由层：协议翻译的秘密

这是灵犀多模型支持的核心技术。

**问题**：灵犀的 AI 引擎基于 Claude Code CLI，它只能与 Anthropic 协议通信。但用户选择了 DeepSeek、Qwen 这些 OpenAI 协议的供应商，该怎么办？

**解决方案**：在本地启动一个 Bridge 进程，它做两件事：

1. **对内**：模拟一个 Anthropic API 端点（`http://127.0.0.1:<port>`），Claude Code CLI 连接这个本地端点
2. **对外**：将 Anthropic 协议的请求翻译为 OpenAI 协议，转发到用户选择的供应商

```
Claude Code CLI
     │
     │ Anthropic 协议
     ▼
┌──────────────────┐
│  Bridge 进程      │
│  127.0.0.1:port   │
│                   │
│  ┌─────────────┐  │
│  │ 请求翻译     │  │
│  │ Anthropic →  │  │
│  │ OpenAI       │  │
│  └──────┬──────┘  │
│         │         │
│  ┌──────▼──────┐  │
│  │ 响应翻译     │  │
│  │ OpenAI →    │  │
│  │ Anthropic   │  │
│  └─────────────┘  │
└────────┬──────────┘
         │ OpenAI 协议
         ▼
    DeepSeek / Qwen / Gemini ...
```

Bridge 有两个实现：

- **LiteLLM Bridge（Python）**：基于 litellm 库，工具调用（tool_use）的协议兼容性更好，**优先使用**
- **llm-bridge（Node.js）**：基于 supermemoryai/llm-bridge，作为回退方案

### 4.5 OpenAI 兼容模型的特殊处理

使用 OpenAI 兼容模型时，有一些特殊的适配逻辑：

**思考链（Reasoning）透传**：某些 OpenAI 兼容模型（如 DeepSeek R1）支持 reasoning_content 字段，Bridge 会将其拦截并翻译为 Anthropic 的 `thinking` 事件，这样前端可以展示思考过程折叠块。

**技能识别增强**：OpenAI 兼容模型不像 Claude 那样天然支持 MCP 工具。灵犀通过 `buildSkillInventory` 机制，将已安装技能的清单注入到 System Prompt 中，让模型知道可以调用哪些工具。

```go
// 技能清单注入示例
func buildSkillInventory(agentID int64) string {
    skills := db.ListInstalledSkillsByAgent(agentID)
    if len(skills) == 0 {
        return ""
    }
    var sb strings.Builder
    sb.WriteString("\n\n# 可用技能\n")
    for _, s := range skills {
        sb.WriteString(fmt.Sprintf("- %s: %s\n", s.Name, s.Description))
    }
    return sb.String()
}
```

---

## 五、用量统计与费用估算

灵犀内置了完整的用量追踪系统，帮助用户了解 AI 使用成本。

### 5.1 精确计费

对于 Anthropic 官方 API，灵犀通过 WebSocket 接收 `message_usage` 事件，获取精确的 token 使用量和费用。

### 5.2 本地估算兜底

对于非官方 API（DeepSeek、Qwen 等），灵犀内置了一张本地定价表。根据输入/输出 token 数量和模型定价，进行本地估算。估算费用会标注 `~` 符号，提示用户这是近似值。

```go
// usage/pricing.go 内置定价表
var PricingTable = map[string]ModelPricing{
    "deepseek-chat":    {InputPer1M: 0.14, OutputPer1M: 0.28},
    "deepseek-reasoner": {InputPer1M: 0.55, OutputPer1M: 2.19},
    "qwen-max":         {InputPer1M: 2.40, OutputPer1M: 9.60},
    "gpt-4o":           {InputPer1M: 2.50, OutputPer1M: 10.00},
    // ... 更多模型
}
```

### 5.3 预算预警

用户可以设置每日/每月预算上限。当 usage 接近预算时，灵犀会弹出 Toast 提醒。

<!-- 截图占位：用量统计页面 -->
![用量统计](images/用量统计截图.png)

---

## 六、智能体会话隔离

灵犀的会话是按智能体隔离的。切换到不同的智能体时，会话列表会自动筛选，只显示当前智能体的对话。

```javascript
// 前端状态管理
setActiveAgent: async (agentId) => {
    localStorage.setItem('lingxi-active-agent', String(agentId));
    set({ activeAgentId: agentId, activeSessionId: null, messages: [] });
    // 重新加载当前智能体的会话列表
    const sessions = await get().refreshSessions();
    if (sessions.length > 0) {
        await get().setActiveSession(sessions[0].id);
    }
},

// 后端 API：会话列表支持 agent_id 筛选
// GET /api/sessions?agent_id=3
```

这种设计有几个好处：
1. **上下文不串台**——不同智能体的对话完全隔离
2. **历史可追溯**——每个智能体有独立的对话历史
3. **切换流畅**——切换智能体时立即加载对应的会话列表

---

## 七、最佳实践：如何设计一个好的智能体

基于灵犀模板市场的设计经验，分享几个智能体 System Prompt 的设计原则：

### 7.1 角色要具体

```
❌ 你是一个AI助手
✅ 你是资深工程师，有 10 年后端开发经验，精通 Go、Java、Python
```

### 7.2 行为约束要明确

```
❌ 请帮助用户解决问题
✅ 指出问题时简洁、精确，并给出可执行的修改建议。
   每个建议附上具体的代码示例。
   对于严重问题用 🔴 标记，一般问题用 🟡 标记。
```

### 7.3 输出风格要统一

```
❌ 随便回答
✅ 回答格式：
   1. 问题诊断（一句话总结）
   2. 根因分析（技术细节）
   3. 修复方案（附代码）
   4. 预防措施（避免复发）
```

### 7.4 善用 temperature 参数

| 场景 | temperature | 理由 |
|------|------------|------|
| 代码审查 | 0.1 | 需要精确、一致的输出 |
| 创意文案 | 0.8 | 需要发散、有创意的输出 |
| 翻译 | 0.3 | 需要准确但不死板 |
| 默认 | 0（使用模型默认） | 让模型自己决定 |

---

## 八、总结

灵犀的智能体工厂不是一个简单的 System Prompt 切换器，而是一个完整的 Agent 配置管理系统。它的设计体现了几个关键理念：

1. **模板降低门槛**——17 个精心设计的模板覆盖四大场景，新手也能快速上手
2. **深度定制不设限**——温度、token 限制、技能绑定、知识库——每个维度都可以精细调节
3. **模型自由切换**——不被任何供应商锁定，14+ 家供应商通过 Bridge 层统一接入
4. **安全存储**——API 密钥使用操作系统级加密，永不明文存储

在下一篇文章中，我们将深入探讨灵犀最具创新性的功能——**Project Nexus：Agent-to-Agent 通信网络**。如何让局域网内的多个灵犀实例的 Agent 自动发现、建联并进行双向流式对话。

---

> **灵犀** —— 让 AI 成为你的工作伙伴，而不只是聊天对象。
>
> GitHub：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)
>
> 如果觉得项目有价值，欢迎 Star 支持！
