feishu-cursor-claw AGENTS.md

AGENTS.md — feishu-cursor-claw（虾群平台版）

本文件是 AI 编码助手理解本项目的入口。所有信息矛盾时以 文档/ 目录为准。

---

项目定位

飞书 → Cursor AI 远程遥控桥接服务。用户在飞书发消息，server 自动转发给本地 Cursor Agent CLI 执行，执行结果通过飞书卡片回传。灵感来自 OpenClaw。

---

技术栈

层	技术
运行时	Bun 1.x + TypeScript（直接运行，无需编译）
飞书 SDK	@larksuiteoapi/node-sdk（WebSocket 长连接）
数据库	SQLite（Bun 内置，记忆向量索引 + FTS5）
语音	火山引擎豆包 STT → 本地 whisper-cpp 兜底
向量	火山引擎豆包 Embedding API
部署	macOS launchd（service.sh 管理）

---

目录结构

虾群平台版/
├── server.ts              # 主服务入口：飞书 WebSocket → Cursor Agent CLI
├── bridge.ts              # OpenAI API 桥接（供 OpenClaw 调用）
├── memory.ts              # 记忆管理器 v2（SQLite + 向量 + FTS5）
├── memory-tool.ts         # 记忆 CLI（Cursor Agent 通过 shell 调用）
├── scheduler.ts           # 定时任务调度器（cron-jobs.json 驱动）
├── heartbeat.ts           # 心跳系统（定期触发 HEARTBEAT.md 检查）
├── sync-apple-notes.ts    # Apple Notes 同步
├── backfill-embeddings.ts # 向量嵌入回填工具
├── feishu/                # 飞书集成（17 个 .ts 文件）
│   ├── client.ts          # 飞书 SDK 客户端
│   ├── send.ts            # 消息发送
│   ├── streaming-card.ts  # 流式卡片更新
│   ├── mention.ts         # @提及处理
│   └── types.ts           # 类型定义
├── templates/             # 工作区初始化模板
├── plugins/               # 插件系统
│   └── turix-cua/         #   桌面操控代理（AI 视觉 + 鼠标键盘操控）
├── 瑞小美-harness/        # AI 编程辅助配置工具包
├── .cursor/               # 本项目 Cursor 配置
├── 参考代码/              # 参考项目集合（不参与构建）
├── 文档/                  # 结构化知识库（唯一真相源）
├── 架构.md                # 系统架构鸟瞰图
├── .env / .env.example    # 环境变量
├── package.json           # 项目依赖
└── service.sh / setup.sh  # 部署脚本

---

模块职责与依赖

进程模型

单进程架构，server.ts 是唯一的进程入口。所有模块在同一进程内运行。

模块关系

• server.ts — 主进程，实例化 memory.ts、scheduler.ts、heartbeat.ts，导入 feishu/ 模块
• memory.ts — 被 server.ts 实例化，提供记忆读写能力
• memory-tool.ts — 独立 CLI 进程，供 Cursor Agent 通过 shell 调用记忆系统
• scheduler.ts — 被 server.ts 实例化，读取 cron-jobs.json 驱动定时任务
• heartbeat.ts — 被 server.ts 实例化，定期触发 HEARTBEAT.md 检查
• bridge.ts — 独立服务，提供 OpenAI 兼容 API（供 OpenClaw 调用）
• feishu/ — 飞书功能集合，被 server.ts 通过 SDK 导入
• plugins/turix-cua/ — 独立 Python 进程，通过 turix.sh 启动，AI 截屏→理解→操控鼠标键盘完成桌面任务