飞书 → Cursor AI 远程遥控桥接服务。用户通过飞书即时通讯发送消息（文字、语音、图片、文件），服务自动转发给本地 Cursor Agent CLI 执行，结果通过飞书卡片实时回传。
| 业务域 | 子系统 | 职责 | 说明 |
|---|---|---|---|
| 消息桥接 | server.ts | 飞书消息接收 → 指令解析 → Cursor Agent 调度 → 结果回传 | 核心主链路，单进程常驻服务 |
| API 桥接 | bridge.ts | OpenAI 兼容 API → Cursor Agent CLI → OpenAI 格式响应 | 供 OpenClaw 等外部系统以标准 API 方式调用 |
| 飞书集成 | feishu/ | 飞书 SDK 封装、消息收发、流式卡片、@提及、表情回应、策略管控 | 17 个文件，完整封装飞书开放平台交互细节 |
| 记忆系统 | memory.ts, memory-tool.ts | 向量嵌入 + BM25 混合搜索、增量索引、嵌入缓存 | SQLite 存储，Cursor Agent 通过 CLI 工具调用 |
| 自动化调度 | scheduler.ts | 定时任务执行（at / every / cron 三种调度模式） | 读取工作区 cron-jobs.json，自动触发 Cursor Agent |
| 心跳巡检 | heartbeat.ts | 定期触发 Cursor Agent 执行心跳检查清单 | 按协议决定是否通过飞书汇报异常 |
| 语音处理 | server.ts 内置 | 语音消息 → STT 转文字 → 作为文本指令执行 | 火山引擎豆包 STT 为主，本地 whisper-cpp 兜底 |
| 工作区模板 | templates/ | 新工作区初始化模板：人格、身份、记忆、规则、技能 | Cursor Agent 自动加载的完整配置体系 |
| AI 编程辅助 | 瑞小美-harness/ | 专家 Agent、命令、技能、编码规范的可分发配置包 | 独立于主服务，可复制到任意项目使用 |
| 桌面操控 | plugins/turix-cua/ | AI 视觉理解 + 鼠标键盘操控，自然语言驱动 macOS 桌面自动化 | Python（Conda），截屏→AI→操控循环 |
| 运维部署 | service.sh, setup.sh | macOS launchd 服务管理、开机自启、崩溃恢复 | 纯 Shell 脚本，零外部依赖 |
虾群平台版/
├── server.ts # 主服务入口：飞书 WebSocket → 消息解析 → Cursor Agent 调度 → 流式回传
├── start.ts # 启动引导
├── bridge.ts # OpenAI 兼容 API 桥接层
├── memory.ts # 记忆管理器 v2（SQLite + 向量 + BM25 混合搜索）
├── memory-tool.ts # 记忆 CLI 工具（供 Cursor Agent shell 调用）
├── scheduler.ts # 定时任务调度器（at / every / cron）
├── heartbeat.ts # 心跳巡检系统
├── sync-apple-notes.ts # Apple Notes → 工作区同步
├── backfill-embeddings.ts # 向量嵌入批量回填工具
├── agent-run.exp # Expect 脚本：Cursor Agent CLI 交互控制
├── agent-session.exp # Expect 脚本：Agent 会话管理
│
├── feishu/ # 飞书集成模块（17 个文件）
│ ├── client.ts # 飞书 SDK 客户端初始化
│ ├── send.ts # 消息发送（文本、富文本、文件）
│ ├── streaming-card.ts # 流式交互卡片（实时进度推送）
│ ├── mention.ts # @提及 解析与处理
│ ├── media.ts # 媒体文件下载与处理
│ ├── accounts.ts # 多账号/多应用管理
│ ├── external-keys.ts # 外部密钥管理
│ ├── policy.ts # 消息策略（过滤、限流、权限）
│ ├── reactions.ts # 表情回应
│ ├── typing.ts # 正在输入状态
│ ├── dedup.ts # 消息去重
│ ├── runtime.ts # 运行时上下文
│ ├── sdk-shim.ts # SDK 兼容层
│ ├── send-result.ts # 发送结果封装
│ ├── send-target.ts # 发送目标解析
│ ├── targets.ts # 目标管理
│ └── types.ts # 类型定义
│
├── templates/ # 工作区初始化模板
│ ├── AGENTS.md # Cursor 自动加载的工作区指南
│ ├── README.md # 工作区说明
│ └── .cursor/
│ ├── SOUL.md # AI 人格 / 灵魂
│ ├── IDENTITY.md # 身份元数据
│ ├── USER.md # 主人信息
│ ├── MEMORY.md # 长期记忆
│ ├── BOOT.md # 启动自检清单
│ ├── BOOTSTRAP.md # 首次启动仪式（运行后删除）
│ ├── HEARTBEAT.md # 心跳检查清单
│ ├── TASKS.md # 定时任务文档
│ ├── TOOLS.md # 工具能力清单
│ ├── rules/ # 9 个规则文件
│ │ ├── soul.mdc
│ │ ├── agent-identity.mdc
│ │ ├── user-context.mdc
│ │ ├── workspace-rules.mdc
│ │ ├── tools.mdc
│ │ ├── memory-protocol.mdc
│ │ ├── scheduler-protocol.mdc
│ │ ├── heartbeat-protocol.mdc
│ │ └── cursor-capabilities.mdc
│ └── skills/ # 技能模板
│ ├── create-skill/
│ └── apple-notes-sync/
│
├── 瑞小美-harness/ # AI 编程辅助配置工具包（可分发）
│ ├── agents/ # 5 个专家 Agent
│ ├── commands/ # 21 个命令
│ ├── skills/ # 9 个技能
│ ├── hooks/ # 钩子脚本
│ ├── rules/ # 编码规范和安全规则
│ └── 项目模板/
│ └── 瑞小美AiOS/ # 含 12 个业务技能的项目模板
│
├── 文档/ # 项目文档
├── plugins/ # 插件系统
│ └── turix-cua/ # 桌面操控代理（AI 截屏 → 理解 → 操控鼠标键盘）
│ ├── turix.sh # 一键启动脚本
│ ├── config.json # AI 模型配置
│ ├── examples/main.py # Python 入口
│ ├── src/ # 核心代码（agent/controller/mac/utils）
│ └── skills/ # AI 技能手册
│
├── 参考代码/ # 第三方参考代码
│
├── service.sh # launchd 服务管理脚本
├── setup.sh # 环境初始化脚本
├── package.json # Bun 依赖管理
├── tsconfig.json # TypeScript 配置
├── bun.lock # 依赖锁定
├── .env # 凭据和配置（不提交）
├── .env.example # 环境变量模板
├── .sessions.json # 会话历史
└── .gitignore
- 飞书 → server.ts：飞书开放平台通过 WebSocket 长连接推送消息事件，
server.ts作为唯一入口接收全部消息类型（文字、语音、图片、文件） - server.ts → feishu/：调用
feishu/media.ts下载附件，feishu/mention.ts解析 @提及，feishu/dedup.ts去重，feishu/policy.ts执行策略管控 - server.ts → 语音处理：语音消息先发往火山引擎豆包 STT（WebSocket 二进制协议），失败时回退到本地 whisper-cpp，转写结果作为文本指令继续处理
- server.ts → Cursor Agent CLI：通过
spawn调用本地~/.local/bin/agent，使用--resume保持会话连续性 - server.ts → feishu/streaming-card.ts：Cursor Agent 的输出通过流式卡片实时推送回飞书，用户能看到执行进度
- 外部系统 → bridge.ts → Cursor Agent CLI：接收 OpenAI Chat Completions 格式的 HTTP 请求，转发给 Cursor Agent 执行，返回 OpenAI 格式响应
- Cursor Agent → memory-tool.ts → memory.ts → SQLite：Agent 在执行过程中通过 shell 调用
memory-tool.ts，实现记忆的写入、搜索和索引管理 - memory.ts → 火山引擎嵌入 API：文本转向量时调用豆包 Embedding API，结果缓存在 SQLite 中避免重复计算
- scheduler.ts → cron-jobs.json → Cursor Agent CLI → feishu/send.ts：定时读取工作区的任务配置，到期时 spawn Cursor Agent 执行，结果通过飞书推送
- heartbeat.ts → Cursor Agent CLI → HEARTBEAT.md → feishu/send.ts：定期触发 Agent 执行心跳检查清单，Agent 按协议判断是否需要汇报
所有模块单向依赖，server.ts 和 bridge.ts 是两个独立入口，共享 feishu/ 和 memory.ts 等底层模块。
┌─────────────────────────────────────────────────────────┐
│ macOS（Apple Silicon）本机 │
│ │
│ ┌──────────────┐ spawn ┌──────────────────────┐ │
│ │ Bun 进程 │ ────────→ │ Cursor Agent CLI │ │
│ │ (server.ts) │ ←──────── │ (~/.local/bin/agent)│ │
│ │ │ stdout │ │ │
│ │ ┌─────────┐ │ │ ┌──────────────────┐│ │
│ │ │scheduler│ │ │ │ Cursor IDE ││ │
│ │ │heartbeat│ │ │ │ (本地工作区) ││ │
│ │ └─────────┘ │ │ └──────────────────┘│ │
│ └──────┬───────┘ └──────────────────────┘ │
│ │ │
│ ┌──────┴───────┐ ┌──────────────┐ │
│ │ SQLite │ │ .env │ │
│ │ (.memory.sqlite) │ .sessions │ │
│ │ │ │ cron-jobs │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ launchd 守护（service.sh 管理） │
│ · 开机自动启动 │
│ · 崩溃自动恢复 │
│ · .env 热更换（无需重启） │
│ · projects.json 热更换 │
└────────────┬────────────────────────────────────────────┘
│ WebSocket 长连接（无需公网地址）
▼
┌──────────────────────┐ ┌──────────────────────┐
│ 飞书开放平台 │ │ 火山引擎 │
│ · 消息推送 │ │ · 豆包 STT（语音） │
│ · 卡片更新 │ │ · 豆包 Embedding │
│ · 媒体下载 │ │ （向量嵌入） │
└──────────────────────┘ └──────────────────────┘
- 单进程架构：整个服务运行在一个 Bun 进程中，server.ts 为主入口，scheduler 和 heartbeat 作为内部模块共存
- 无公网依赖：飞书通过 WebSocket 长连接主动推送，不需要公网 IP 或域名
- 本地 AI 能力：Cursor Agent CLI 和 Cursor IDE 运行在同一台 macOS 机器上，通过进程 spawn 通信
- projects.json 路由：上层目录的
projects.json定义工作区映射，决定消息转发到哪个 Cursor 工作区
| 存储 | 类型 | 用途 | 路径 |
|---|---|---|---|
| .env | 环境变量文件 | 飞书凭据、火山引擎密钥、各项配置 | 项目根目录 |
| .sessions.json | JSON 文件 | Cursor Agent 会话历史（用于 --resume 连续对话） | 项目根目录 |
| .memory.sqlite | SQLite 数据库 | 向量嵌入索引 + FTS5 全文搜索 + 嵌入缓存 | 工作区目录 |
| cron-jobs.json | JSON 文件 | 定时任务配置（at / every / cron 三种格式） | 工作区目录 |
| projects.json | JSON 文件 | 工作区路由映射（消息 → 工作区） | 上层目录 |
| inbox/ | 临时目录 | 飞书下载的媒体文件（图片、文件等），24 小时自动清理 | 工作区目录 |
| HEARTBEAT.md | Markdown | 心跳检查清单，Agent 按此执行巡检 | 工作区 .cursor/ |
| MEMORY.md | Markdown | Agent 可读写的长期记忆文件 | 工作区 .cursor/ |
| TASKS.md | Markdown | 定时任务的人类可读文档 | 工作区 .cursor/ |