# 灵犀 AI Agent：技能生态、知识库管理、定时任务与企业 IM 集成

> 本文是灵犀 AI Agent 系列专栏的第五篇（完结篇），将深入探讨灵犀如何构建完整的 Agent 能力生态——从技能系统（AI 生成、市场安装、在线编辑）到知识库管理（多格式支持、分类体系），从定时任务调度到企业 IM 集成（企业微信/钉钉/飞书），再到 MCP 工具管理和可视化工作流编排。
>
> GitHub 地址：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)

---

## 一、技能系统：给 Agent 装备能力

灵犀的"技能"是 Agent 能力的扩展单元。每个技能本质上是一组脚本和配置文件，定义了 Agent 在特定场景下可以执行的操作。

### 1.1 技能的结构

每个技能是一个目录，包含核心文件：

```
my-skill/
├── SKILL.md      # 技能说明文件（描述触发条件、使用方法）
├── script.sh     # 执行脚本（Bash/Python/Node.js）
└── config.json   # 可选的配置文件
```

`SKILL.md` 是关键——它定义了技能的触发条件和使用说明。AI 引擎会读取这个文件来判断何时以及如何使用该技能。

### 1.2 四种获取方式

灵犀为技能提供了四种获取方式，覆盖从新手到高级用户的所有需求：

**方式一：AI 自动生成**

用户描述需求，灵犀通过流式 AI 调用自动生成技能代码。

```
POST /api/skills/generate/stream
Body: { "description": "一个可以查询天气的技能" }

→ 流式返回生成的 SKILL.md 和脚本代码
→ 用户预览后确认：POST /api/skills/generate/confirm
```

**方式二：ZIP 导入 / 批量上传**

```
POST /api/skills/upload        # 单个 ZIP 上传
POST /api/skills/batch-upload   # 批量上传多个 ZIP
```

**方式三：Smithery 市场安装**

灵犀集成了 Smithery.ai 技能市场，提供搜索、分类浏览、一键安装能力。

```
GET  /api/skills/marketplace                    # 搜索市场
GET  /api/skills/marketplace/categories         # 分类列表
GET  /api/skills/marketplace/:ns/:slug          # 技能详情
POST /api/skills/marketplace/install            # 一键安装
```

**方式四：在线编辑**

已安装的技能可以在线查看和编辑。灵犀提供了完整的代码编辑界面：

```
GET  /api/skills/:id/content   # 获取技能文件内容
PUT  /api/skills/:id/content   # 更新技能文件
GET  /api/skills/:id/export    # 导出为 ZIP 包
```

<!-- 截图占位：技能管理页面 -->
![技能管理](images/技能管理截图.png)

### 1.3 技能与智能体的绑定

技能不是全局生效的——每个智能体独立配置自己可用的技能列表。

```go
// Agent 的 skill_ids 字段是 JSON 数组
// [1, 3, 5] 表示该 Agent 只能使用 ID 为 1、3、5 的技能

// 当 allow_all 为 true 时，Agent 可以使用所有已安装的技能
```

这种设计确保了"安全工程师"Agent 不会意外使用"写邮件"技能，"翻译专家"Agent 也不会调用 Git 操作相关的技能。

### 1.4 OpenAI 兼容模型的技能识别增强

对于不原生支持 MCP 工具调用的 OpenAI 兼容模型，灵犀通过一个巧妙的方式让模型"知道"有哪些技能可用：

```go
// buildSkillInventory 将已安装技能清单注入 System Prompt
func buildSkillInventory(agentID int64) string {
    skills := getInstalledSkillsForAgent(agentID)
    if len(skills) == 0 {
        return ""
    }
    
    var sb strings.Builder
    sb.WriteString("\n\n# 可用技能清单\n\n")
    for _, s := range skills {
        sb.WriteString(fmt.Sprintf("- **%s**: %s\n", s.Name, s.Description))
    }
    sb.WriteString("\n你可以在需要时调用上述技能来完成任务。\n")
    return sb.String()
}
```

---

## 二、MCP 工具管理

MCP（Model Context Protocol）是 Anthropic 推出的工具调用标准。灵犀完整支持 MCP 的三种传输协议：

| 协议 | 适用场景 | 配置方式 |
|------|---------|---------|
| **stdio** | 本地命令行工具 | 指定可执行文件路径和参数 |
| **SSE** | HTTP 长连接服务 | 指定 URL 端点 |
| **HTTP** | RESTful 服务 | 指定 URL 端点 |

### 2.1 MCP 服务管理

```
GET    /api/mcp           # 列出所有 MCP 服务
POST   /api/mcp           # 创建/更新 MCP 服务
DELETE /api/mcp/:id        # 删除 MCP 服务
POST   /api/mcp/:id/toggle # 启用/禁用
GET    /api/mcp/export     # 导出配置（JSON 格式）
```

### 2.2 配置导出

灵犀支持将 MCP 配置导出为标准 JSON 格式，兼容 Claude Desktop 等其他工具。

```json
{
    "mcpServers": {
        "playwright": {
            "command": "/path/to/node",
            "args": ["/path/to/mcp/cli.js", "--browser", "chrome"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
        }
    }
}
```

### 2.3 内置 Playwright MCP

灵犀在启动时会自动检测系统是否安装了 Google Chrome。如果存在，会自动注册 Playwright MCP，让 AI 获得网页操作能力——浏览网页、截图、填写表单、点击按钮等。

```javascript
// electron/main.js
const chromePath = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
if (fs.existsSync(chromePath)) {
    claudeJsonObj.mcpServers.playwright = {
        command: nodeBin,
        args: [mcpCliPath, '--browser', 'chrome', '--headless'],
    };
}
```

<!-- 截图占位：MCP 管理页面 -->
![MCP 管理](images/mcp管理截图.png)

---

## 三、知识库管理

灵犀的知识库支持 7 种文件格式，分三类管理。

### 3.1 支持的文件格式

| 格式 | 处理方式 | Go 依赖 |
|------|---------|---------|
| `.md` | 直接读取 | 标准库 |
| `.txt` | 直接读取 | 标准库 |
| `.csv` / `.tsv` | 直接读取 | 标准库 |
| `.json` | 直接读取 | 标准库 |
| `.pdf` | 文本提取 | `ledongthuc/pdf` |
| `.docx` | 文本提取 | `nguyenthenguyen/docx` |

### 3.2 分类体系

```
knowledge/
├── docs/     # 文档类（技术文档、使用手册、规范）
├── qa/       # 问答类（FAQ、Q&A 知识库）
└── data/     # 数据类（CSV 数据集、JSON 配置）
```

### 3.3 索引机制

上传知识库文件后，灵犀会自动生成 `INDEX.md` 索引文件：

```markdown
# 知识库索引

## 文档类 (docs/)
- architecture.md — 项目架构文档
- api-guide.md — API 使用指南

## 问答类 (qa/)
- faq.md — 常见问题解答

## 数据类 (data/)
- pricing.csv — 产品定价表
```

AI 引擎在回答用户问题前，会先读取这个索引，快速判断是否有相关文档，然后精确检索。

### 3.4 知识库与智能体的绑定

和技能一样，知识库也可以按智能体绑定：

```
"代码审查员" Agent → 绑定项目技术文档
"销售助理" Agent  → 绑定产品手册 + 定价表
"法务顾问" Agent  → 绑定公司合同模板
```

这确保每个 Agent 只能访问与自己职责相关的知识。

### 3.5 拖拽批量上传

前端支持拖拽上传多个文件。上传后可以在管理界面预览文件内容（包括 PDF 和 DOCX 的提取文本）。

```
GET /api/knowledge/:id/preview
→ 返回文件的前 1000 行文本（预览用）
```

<!-- 截图占位：知识库管理页面 -->
![知识库管理](images/知识库截图.png)

---

## 四、定时任务调度

灵犀内置了完整的定时任务系统，让 Agent 可以周期性地自动执行任务。

### 4.1 支持的调度方式

| 方式 | 示例 |
|------|------|
| 每 N 分钟 | 每 30 分钟检查一次邮件 |
| 每 N 小时 | 每 2 小时汇总数据 |
| 每天 | 每天 9:00 生成日报 |
| 每周 | 每周一生成周报 |
| 每月 | 每月 1 日生成月报 |
| 自定义 Cron | `0 */2 * * 1-5`（工作日每 2 小时） |

### 4.2 有状态 vs 无状态模式

灵犀的定时任务有一个独特的设计——**有状态模式**。

- **无状态模式**：每次执行都是一次全新的对话，Agent 不记得之前执行过什么
- **有状态模式**：所有执行共享同一个会话，Agent 可以记忆之前的执行结果

```go
// model/model.go
type ScheduledTask struct {
    Stateful  bool   `json:"stateful"`   // 有状态模式
    SessionID *int64 `json:"session_id"` // 有状态时复用的会话 ID
}
```

有状态模式的典型场景：每天检查项目进度。Agent 记得昨天的进度，只汇报增量变化，而不是每次从头分析。

### 4.3 调度器实现

Go 后端的调度器每 15 秒检查一次是否有到期任务：

```go
// scheduler/scheduler.go
func Start() {
    go func() {
        ticker := time.NewTicker(15 * time.Second)
        for range ticker.C {
            checkAndRunDueTasks()
        }
    }()
}

func checkAndRunDueTasks() {
    tasks := db.ListEnabledScheduledTasks()
    now := time.Now()
    for _, task := range tasks {
        if task.NextRunAt != nil && now.After(*task.NextRunAt) {
            go executeTask(task) // 每个任务在独立 goroutine 中执行
        }
    }
}
```

### 4.4 执行通知

任务执行完成后，灵犀会通过 WebSocket 广播 `desktop_notify` 事件，前端收到后显示桌面通知。

```go
notifyFn := func(taskName, summary string) {
    payload, _ := json.Marshal(map[string]string{
        "title": "定时任务 — " + taskName,
        "body":  summary,
    })
    handler.BroadcastWSEvent("desktop_notify", string(payload))
}
```

在 Electron 环境下，这会触发系统级桌面通知（macOS 通知中心 / Windows 通知）。

### 4.5 执行记录

每次任务执行都会记录在 `scheduled_task_runs` 表中：

```
GET /api/scheduled-tasks/:id/runs
→ 返回执行记录列表（开始时间、结束时间、状态、摘要）
→ 点击记录可跳转到对应的会话查看完整对话
```

<!-- 截图占位：定时任务管理页面 -->
![定时任务](images/定时任务截图.png)

---

## 五、长期记忆

灵犀为每个 Agent 维护独立的长期记忆，跨会话持久保存。

### 5.1 记忆的存储

```go
type Memory struct {
    ID        int64     `json:"id"`
    AgentID   int64     `json:"agent_id"`   // 按智能体隔离
    Content   string    `json:"content"`     // 记忆内容
    Category  string    `json:"category"`    // 分类
    CreatedAt time.Time `json:"created_at"`
}
```

### 5.2 记忆的来源

- **自动添加**：AI 在对话中识别到重要信息（如用户偏好），自动记录
- **手动添加**：用户在"设置 > 长期记忆"页面手动添加

### 5.3 记忆的使用

每次对话开始时，灵犀会将当前 Agent 的所有记忆注入到对话上下文中。Agent 就像是"记住了"用户之前告诉它的所有信息。

### 5.4 管理界面

设置页面提供完整的记忆管理：

```
GET    /api/memories           # 列表（支持按分类筛选）
POST   /api/memories           # 添加
DELETE /api/memories/:id       # 删除单条
DELETE /api/memories/clear     # 清空所有
```

---

## 六、企业 IM 集成

灵犀支持将 Agent 能力接入三大企业 IM 平台：

| 平台 | 接入方式 | 功能 |
|------|---------|------|
| **企业微信** | 自定义机器人 | 接收群消息 → Agent 回复 |
| **钉钉** | 自定义机器人 | 接收群消息 → Agent 回复 |
| **飞书** | 自定义机器人 | 接收群消息 → Agent 回复 |

### 6.1 架构

```
企业微信群 / 钉钉群 / 飞书群
         │
         │ Webhook 回调
         ▼
┌─────────────────────┐
│  灵犀 Go 后端        │
│  connector/          │
│  ├── wecom.go       │ ← 企业微信适配器
│  ├── dingtalk.go    │ ← 钉钉适配器
│  └── feishu.go      │ ← 飞书适配器
│                      │
│  统一消息格式 →       │
│  handler.RunClaudeSync│
│                      │
│  Agent 回复 →        │
│  各平台消息 API 发送  │
└─────────────────────┘
```

### 6.2 配置管理

```
GET    /api/im-connectors              # 列出所有连接器
POST   /api/im-connectors              # 创建/更新连接器
PUT    /api/im-connectors/:platform/enable  # 启用
PUT    /api/im-connectors/:platform/disable # 禁用
DELETE /api/im-connectors/:platform     # 删除
```

配置信息包括：应用 ID、密钥、Webhook URL、绑定的 Agent 等。灵犀负责完成各平台的签名验证、消息解析和回复格式转换。

<!-- 截图占位：IM 连接器配置页面 -->
![IM 集成](images/im集成截图.png)

---

## 七、可视化工作流编排

灵犀提供了一个可视化的拖拽节点式工作流编辑器，用于构建复杂的 Agent 执行流程。

### 7.1 六种节点类型

| 节点 | 图标 | 功能 |
|------|------|------|
| **提示词** | 💬 | 发送 Prompt 给 AI，获取回复 |
| **条件分支** | 🔀 | 根据前一步的输出判断走哪条路径 |
| **循环** | 🔄 | 重复执行一组节点 N 次 |
| **延迟** | ⏱️ | 等待指定时间 |
| **代码执行** | 💻 | 运行自定义脚本（Bash/Python） |
| **输出** | 📤 | 最终输出结果 |

### 7.2 节点间连线

节点之间通过连线表示执行顺序和数据流向。前端使用 Canvas/SVG 绘制连线，支持拖拽调整。

### 7.3 执行预览

编辑完成后，可以在不实际执行的情况下预览执行路径。

```
提示词 → 条件分支 → True 分支 → 代码执行 → 输出
                  └→ False 分支 → 延迟 → 提示词 → 输出
```

---

## 八、自动更新机制

灵犀内置了 `electron-updater`，支持完整的 OTA 自动更新流程。

### 8.1 更新检查

```
启动 10 秒后 → 自动检查更新
之后每 4 小时 → 轮询检查
用户手动 → 设置 > 关于与更新 > 检查更新
```

### 8.2 更新流程

```
检查更新 → 发现新版本 → 弹窗提示下载
                          ↓ 用户确认
                     后台下载 → 下载进度推送到前端
                          ↓ 下载完成
                     弹窗提示重启
                          ↓ 用户确认
                     退出应用 → 安装更新 → 重新启动
```

### 8.3 增量更新

构建产物包含 `.blockmap` 文件，`electron-updater` 可以据此实现增量更新——只下载变化的部分，而不是整个应用。

---

## 九、防死循环保护

在实际使用中，AI 有时会陷入工具调用死循环（不停地调用同一个工具）。灵犀在 System Prompt 中实现了两层保护：

**第一层：禁止特定工具**

```
你拥有的工具集仅限：Bash / Read / Write / Edit / MultiEdit / 
Glob / Grep / LS / WebFetch / WebSearch，以及 mcp__ 开头的 MCP 工具。
除此之外的任何工具都不存在，禁止调用。
```

这防止了 AI 尝试调用不存在的工具（如 Cursor 专有的 AskQuestion、TodoWrite 等）导致的循环。

**第二层：isNonExistentTool 检测**

后端代码中有一个检测函数，当 AI 尝试调用不存在的工具时，自动拦截并返回提示信息，而不是让引擎反复重试。

---

## 十、挂起任务机制

当 Agent 需要向用户收集信息才能继续执行时，任务会进入"挂起"状态。

```
Agent 执行任务 → 需要用户输入参数
     │
     ▼
创建 PendingTask（记录缺少的字段）
     │
     ▼
前端检测到挂起任务 → 显示信息收集 UI
     │
     ▼
用户填写并提交 → 清除 PendingTask → 继续执行
```

```
GET    /api/sessions/:id/pending   # 查询挂起任务
DELETE /api/sessions/:id/pending   # 清除（用户提交后）
```

---

## 十一、快捷键体系

灵犀设计了一套完整的快捷键体系，覆盖高频操作：

| 快捷键 | 功能 |
|--------|------|
| `Cmd+K` | 全文搜索消息 |
| `Cmd+N` | 新建对话 |
| `Cmd+B` | 折叠/展开侧边栏 |
| `Cmd+,` | 打开设置 |
| `Cmd+/` | 显示快捷键面板 |
| `Cmd+Shift+S` | 截屏到输入框 |
| `Enter` | 发送消息 |
| `Shift+Enter` | 换行 |
| `/` | 唤起斜杠命令 |
| `Esc` | 关闭弹窗/面板 |

所有快捷键都在 `AppShell.jsx` 中统一注册，通过 `Cmd+/` 可以唤出快捷键面板查看。

---

## 十二、总结与展望

经过五篇文章的深度剖析，我们完整展现了灵犀 AI Agent 的全貌。让我们回顾一下灵犀的核心能力：

### 已实现的能力矩阵

| 维度 | 能力 |
|------|------|
| **对话** | 流式输出、思考链折叠、代码高亮、消息编辑/反馈/固定、快捷回复、对话中止 |
| **多模态** | 图片粘贴、文件拖入、语音输入（离线 whisper.cpp）、截屏（Cmd+Shift+S）、TTS 朗读 |
| **智能体** | 工厂创建、五步向导、17 个模板、参数调节、技能/知识库/MCP 绑定 |
| **模型** | 14+ 供应商、Anthropic + OpenAI 双协议、Bridge 路由层、密钥加密存储 |
| **协作** | Agent 间对话（Project Nexus）、mDNS 发现、PSK 建联、双向流式、人类监督 |
| **能力扩展** | 技能系统、MCP 工具、知识库 RAG、Smithery 市场集成 |
| **自动化** | 定时任务调度、有状态模式、桌面通知、执行记录 |
| **企业** | 企业微信/钉钉/飞书集成 |
| **体验** | 6 套主题、AnimatePresence 动画、虚拟滚动、规划模式、交互式向导 |

### 技术栈一览

```
桌面容器  │ Electron 36 + electron-builder 25 + electron-updater
前端 UI   │ React 19 + Vite 8 + Tailwind CSS 3.4 + Zustand 5
动画      │ Framer Motion 12 (AnimatePresence + layoutId)
渲染      │ react-markdown + prism-react-renderer + Recharts 3
后端引擎  │ Go 1.24 + Gin 1.10 + Gorilla WebSocket
数据存储  │ ncruces/go-sqlite3 (纯 Go WASM，无 CGO)
文档解析  │ ledongthuc/pdf + nguyenthenguyen/docx
AI 引擎   │ Claude Code CLI（内嵌，不依赖系统安装）
协议桥接  │ LiteLLM Bridge (Python) / llm-bridge (Node.js)
语音识别  │ whisper.cpp (Apple Metal 加速离线 ASR)
局域网    │ hashicorp/mdns (mDNS 自动发现)
```

### 设计理念

灵犀的设计哲学可以概括为五个关键词：

1. **本地优先**——数据不出本机，密钥加密存储，零云端依赖
2. **开箱即用**——双击运行，无需安装任何依赖，内嵌完整运行时
3. **自由选择**——14+ 供应商，不被任何模型锁定
4. **能力完整**——不是 Chat Wrapper，而是完整的 Agent 工作台
5. **人机协作**——AI 自主执行，人类随时监督和介入

### 如何参与

灵犀是一个开源项目，采用 MIT 协议。无论你是想使用还是参与开发，都非常欢迎：

- **GitHub**：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)
- **下载体验**：从 Release 页面下载最新版本的 DMG 安装包
- **提交 Issue**：发现 Bug 或有功能建议，欢迎提交 Issue
- **贡献代码**：Fork 项目，提交 PR

---

> **灵犀** —— 让 AI 成为你的工作伙伴，而不只是聊天对象。
>
> 感谢阅读本系列全部五篇文章。如果觉得项目有价值，请到 GitHub 给我们一个 Star，这是对开源项目最大的支持。
>
> GitHub：[https://github.com/OdysseyFather/lingxi](https://github.com/OdysseyFather/lingxi)
