多平台 AI 智能连接中枢
统一接入钉钉 / 飞书 / 企业微信，融合 RAG 知识库、规则引擎、LLM 对话与 Web 管理台 —— 连接企业智能，桥接无限可能。
灵桥（Linkora） 把企业级 AI 助手挂到团队日常 IM（钉钉 / 飞书 / 企业微信）上：让一个「能读懂企业知识、会调用工具、可被人工审核」的 AI 分身，直接出现在你已经在用的群聊和单聊里。
典型链路：消息进来 → 规则 / 意图分流 → 命中知识库或调用工具 → LLM 生成回复 → 原路发回；全过程在 Web 管理台可查、可调、可审批。三套平台各自独立适配、独立数据库、独立轮询器，数据物理隔离，可按平台独立启停。
| 维度 | 规模（当前代码实测） |
|---|---|
| 接入平台 | 3 个（钉钉 / 飞书 / 企业微信，数据物理隔离） |
| 内置工具 | 47 个（Tool Calling，单一真源 BUILTIN_TOOL_MANIFEST） |
| 意图分类 | 41 个（9 处置 + 7 动作 + 25 领域） |
| Web 管理台 | 18 个页面（SPA） / 35 个路由模块 / 174 端点 |
| 代码规模 | 216 个 src Python 模块 / 294 测试文件 / 4465 个测试用例 / 告警中心 Web 页面 |
flowchart TB
DT["钉钉"]:::im
FS["飞书"]:::im
WC["企微"]:::im
subgraph IM_ADAPTER["IM Adapter — 平台适配层"]
DA["DwsAdapter<br/>钉钉 CLI"]
FA["FeishuCliAdapter<br/>lark-cli"]
WA["WecomCliAdapter<br/>wecom-cli"]
end
POL["Poller<br/>轮询器"]
RE["Rule Engine<br/>规则引擎"]
KW["关键词匹配 /<br/>快速回复"]
IN["意图识别"]
LLM["LLM 生成"]
RP["Reply<br/>发回原平台"]
subgraph WEB["Web 管理台 :8080"]
W_DASH["仪表盘 & 统计"]
W_CONV["对话记录"]
W_KB["知识库管理"]
W_RULE["规则引擎配置"]
W_DRAFT["草稿审批"]
W_CFG["系统配置"]
end
subgraph DB["数据库 — 各平台物理隔离"]
DB_DT["linkora.db"]
DB_FS["feishu-ai.db"]
DB_WC["wecom-ai.db"]
end
subgraph RAG["RAG 知识库"]
EMB["BGE 向量"]
RR["BM25 混合重排序"]
end
DT --> DA
FS --> FA
WC --> WA
DA --> POL
FA --> POL
WA --> POL
POL --> RE
RE --> KW
RE --> IN
RE --> LLM
KW --> RP
IN --> RP
LLM --> RP
WEB -. "读 / 写" .-> DB
DB -. "供给" .-> RAG
RAG -- "检索上下文" --> LLM
classDef im fill:#e6f3ff,stroke:#4a86e8,color:#1a3a6e
分层细节与处理时序见 架构设计。
钉钉 / 飞书 / 企微各自独立适配器、独立数据库、独立轮询器，可按平台独立启停；物理隔离到不同 SQLite 库。自动区分单聊 / 群聊 / 系统推送，消息编辑 / 撤回实时同步，同一发送者短时间多条消息防抖合并。Web 与后台轮询器（worker）进程分离，改 Web 代码只重启 web 进程不打断 ingestion。
入库格式覆盖 PDF / Word / PPT / 图片 OCR / Markdown / URL / 钉钉文档 / 飞书文档 / 维基空间；BGE 中文模型本地离线推理，混合重排序（向量 0.6 + BM25 0.4）；标题行与正文粘连分块；低于置信度阈值不强行作答，转草稿 / 转人工。另有「严格问答模式」开关——开启后回答只能依据知识库内容、未命中直接返回固定「未收录」文案，答案 100% 可溯源、零编造，适合制度问答 / 产品资料这类对出处要求极高的场景。
高频场景关键词精确匹配、毫秒级响应、不走 LLM；41 个内置意图覆盖天气 / 联网搜索 / 日程 / 待办 / 审批 / 考勤 / 组织 / 配置 / 维基 / 日志 / 企业语义检索等；黑白名单按会话 / 用户 / 关键词多维度控制；每条消息的意图判定与路由决策可追溯。
由 BUILTIN_TOOL_MANIFEST 单一真源声明并自动注册，按意图关键词自动匹配，覆盖消息通讯、知识文档、组织人员、日程待办、审批（钉钉 9 个）、考勤、会议纪要、钉钉日志、企业语义检索、长期记忆、运维工具等。
仪表盘统计、对话记录检索、知识库管理、规则引擎配置、草稿审批、在线编辑 config.yaml、日志 / 健康检查 / 决策追踪 / 成本质量看板 / 对话摘要实时页（结构化卡片展示，支持今日 / 昨日 / 近七天时间窗口切换）。
跨会话长期记忆（按用户隔离、自动压缩归档）、图片 OCR 让 LLM 看懂截图、长对话后台异步摘要压缩、从主人历史消息抽取语气人格、RAG 门控减少 token 浪费、收信探针告警、定时同步 / 备份 / 清理；主动触达可在每日定时把近期对话摘要主动推送给主人（钉钉 1:1，默认关闭），并在 Web 后台「对话摘要」页实时查看同源汇总；摘要按日期与主题拆分、以卡片网格呈现，自动提取主题关键词与待办建议，一目了然。
# 1. 克隆并安装依赖
git clone <repo-url> linkora && cd linkora
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 依赖锁定：requirements.lock 为完整传递闭包（CI / pip-audit 使用），
# 日常开发与 Docker 用 requirements.txt（直接依赖唯一真源）即可。
# 2. 准备配置
cp config.yaml.example config.yaml
# 至少填写：llm.api_key / llm.base_url，platforms[].adapter.cli_path
# 3. 平台 CLI 登录（以钉钉为例）
dws auth login
# 飞书：lark-cli login 企业微信：wecom-cli login
# 前端资源改动后需重新构建（vitest 单测见 npm run test:frontend）：
npm run build:frontend
# 4. 启动
.venv/bin/python scripts/run_linkora.py
# Web 管理台 → http://localhost:8080后台常驻：nohup .venv/bin/python scripts/run_linkora.py > logs/$(date +%Y%m%d).log 2>&1 &
推荐：单进程模式（
--single-process）。默认的双进程模式（web + worker 分属两个 进程）会同时打开同一个数据库文件，SQLite 只允许单写者，跨进程写锁竞争可能表现为database is locked、轮询丢会话。单进程让 Web 与后台轮询同驻一个进程、共用同一把 写锁，从根上消除这类争用：.venv/bin/python scripts/run_linkora.py --single-process停止：
pkill -f run_linkora.py
更多启动形态（指定端口、--no-worker / --worker-only / --dev 等）见 scripts/run_linkora.py --help。
docker compose up -dconfig.yaml 为 YAML 格式，Web 管理台同步读写，保存即生效。顶层配置段：
platforms 多平台主配置（适配器 / 存储 / 轮询器）★
llm LLM 接入与高级策略 embedding 向量模型
rag 检索策略 memory 长期记忆
proactive 主动触达（每日摘要推送） rules 黑白名单 / 关键词 / 意图
tools 工具开关与速率限制 skills 技能系统
skillhub 技能市场 web 管理台与鉴权
storage 默认存储 logging 日志
safety 安全护栏 llm_throttle 限流
dead_letter 死信队列 dws 钉钉 CLI 全局设置
platforms:
- id: dingtalk
display_name: 钉钉
enabled: true
adapter_type: dingtalk
storage:
type: sqlite
path: ./data/linkora.db
backup_enabled: true
backup_dir: ./data/backups
backup_interval_hours: 24
poller:
interval_seconds: 20 # 轮询间隔（秒）；stream 长连接启用时轮询仅为兜底
unread_convs_cache_ttl_seconds: 30 # 未读会话列表缓存 TTL（降频用，设 0=每轮都拉）
forced_fetch_min_interval_seconds: 30 # 未读会话抓取下限间隔（降频用，设 0=每轮必抓）
conv_info_negative_cache_ttl_seconds: 300 # 对方信息解析失败负缓存 TTL（降频用，设 0=下轮重试）
history_days: 3
poll_new_message_max_age_hours: 24 # 仅处理最近 N 小时内的新消息（默认 24，防历史重放）
max_concurrent_replies: 4
skip_msg_types: [system, app]
adapter:
cli_path: /path/to/cli
timeout: 30
- id: feishu
enabled: true
adapter_type: feishu
storage: { path: ./data/feishu-ai.db }
adapter: { cli_path: lark-cli }
- id: wecom
enabled: false
adapter_type: wecom
storage: { path: ./data/wecom-ai.db }
adapter: { cli_path: wecom-cli }轮询配置真源在
platforms[].poller（按平台隔离）；根级poller:为 legacy 兼容段，运行期以platforms[].poller为准。
全部配置项与 llm / embedding 段示例见 配置参考。
linkora/
├── main.py # 兼容门面；真实入口在 src/platform/lifecycle.py
├── scripts/run_linkora.py # 多进程启动器：web(:8080) + worker
├── config.yaml(.example) # 核心配置 / 完整示例
├── src/ # ~170 个 Python 模块
│ ├── platform/ # 运行时层：启动、生命周期、消息循环
│ ├── im_adapter/ # 多平台适配层（CLI 执行 + 适配器）
│ ├── dws_adapter/ # 钉钉 CLI 适配器包（chat/media/oa/wiki…）
│ ├── llm/ # LLM 编排：agent / client / router / RAG
│ ├── memory/ # 存储检索：SQLite + BGE 向量 + FAISS
│ ├── tools/ # 47 个内置工具（registry 单一真源）
│ ├── skills/ # 技能系统：发现 / 加载 / 路由
│ ├── intent/ # 意图分类注册表（41 意图 + 工具映射）
│ └── poller*.py # 消息轮询器与核心子模块
├── web/ # FastAPI 管理台（api.py / routers/ / static SPA）
├── docs/ # 文档（见下方索引）
├── tests/ # 200+ 测试文件
└── data/ · logs/ · docker/
# 一律使用项目内 .venv，不要直用系统 python
.venv/bin/python -m pytest tests/ -q
# macOS 上涉及 torch 的测试需绕过 OpenMP 重复注册
KMP_DUPLICATE_LIB_OK=TRUE .venv/bin/python -m pytest tests/ -q环境要求、构建流程、贡献规范见 开发指南。
以内部协作方式演进，欢迎按以下约定提交改动。
- 一律使用项目内
.venv运行 / 调试 / 装包，避免「依赖装了却 ModuleNotFoundError」。 - 改完
src/后需重启 bot（scripts/run_linkora.py）让修复生效；纯测试改动无需重启。 - 涉及 torch / faiss 的测试在 macOS 上加
KMP_DUPLICATE_LIB_OK=TRUE。
采用中文 type(scope) 前缀：
| type | 含义 |
|---|---|
feat |
新功能 |
fix |
缺陷修复 |
refactor |
重构（零行为变更） |
perf |
性能优化 |
test |
测试补充 / 对齐 |
docs |
文档 |
chore |
杂项 / 配置 |
新增 agent 工具必须同步 5 处（单一真源 BUILTIN_TOOL_MANIFEST → config.py → config.yaml.example → live config.yaml → TOOL_ACTION_MAP），详见 开发指南。
上手与使用
| 文档 | 说明 |
|---|---|
| 配置参考 | config.yaml 全部配置项 |
| 部署指南 | 本地运行、Docker、后台服务 |
| 进阶部署 | 平台前置条件、CI、systemd/launchd |
| 常见问题 | FAQ 与排障 |
理解系统
| 文档 | 说明 |
|---|---|
| 架构设计 | 整体架构、分层、目录、处理流程 |
| 设计总览 | 设计哲学、路由模式、决策追踪（系统结构见架构设计） |
| RAG 知识库 | 格式支持、分块、检索与重排序 |
| 意图分类 | 意图体系、工具映射、决策追踪 |
| 工具清单 | 内置工具详情 |
| Web API | 后端接口概览 |
开发与演进
| 文档 | 说明 |
|---|---|
| 开发指南 | 环境、构建、测试、贡献 |
| 长期记忆 | 数据模型、写入与召回策略 |
| 第三方组件声明 | 开源依赖清单、许可证与合规要点 |
Linkora 站在一堆优秀的开源项目肩上。完整的第三方组件清单、版本、许可证与上游地址见 THIRD_PARTY_NOTICES.md（文档站镜像：第三方组件声明）。
主要依赖一览
| 领域 | 组件 | 许可证 |
|---|---|---|
| Web 服务 | FastAPI、Uvicorn、Starlette、Jinja2、PyJWT | MIT / BSD-3-Clause |
| 配置与校验 | pydantic、PyYAML、python-dotenv | MIT / BSD-3-Clause |
| RAG 与检索 | sentence-transformers、faiss-cpu、numpy、jieba、transformers、tokenizers | Apache-2.0 / MIT / BSD-3-Clause |
| LLM 接入 | openai（OpenAI 兼容协议客户端） | Apache-2.0 |
| 文档解析 | pdfplumber、python-docx、python-pptx、openpyxl、beautifulsoup4 | MIT |
| OCR | RapidOCR（rapidocr-onnxruntime）、onnxruntime、pytesseract、Pillow | Apache-2.0 / MIT / MIT-CMU |
| PDF 渲染 | pypdfium2（含捆绑的 PDFium） | Apache-2.0 / BSD-3-Clause |
| 前端 | Bootstrap 5.3.3、Chart.js 4.4.1、Font Awesome Free 7.3.1 | MIT / CC BY 4.0 + OFL-1.1 |
| 工具链 | ruff、pyright、pytest、esbuild、vitest、uv、gitleaks | MIT / Apache-2.0 |
| AI 模型权重 | BAAI bge 系列（MIT）、Qwen3-Embedding（Apache-2.0） | 运行时下载，不随仓库分发 |
署名（必需）
图标由 Font Awesome Free 7.3.1 提供，© Fonticons, Inc.， 依 CC BY 4.0 授权使用。 字体依 SIL OFL 1.1 授权，代码依 MIT 授权。
合规提示：本项目当前不含任何 AGPL 组件，因此不触发 AGPL §13 的「网络服务须提供源码」义务。
早期版本曾依赖 PyMuPDF（AGPL-3.0 / 商业双许可）做 PDF 页面渲染，现已替换为 pypdfium2
（Apache-2.0 / BSD-3-Clause）——它原本就是 pdfplumber 的传递依赖，替换未引入任何新增依赖。
详见 第三方组件声明 · 替换记录。
外部工具：钉钉 dws、飞书 lark-cli、企业微信 wecom-cli 及 Tesseract OCR
均由使用者自行安装，不随本仓库分发，其许可与使用条款以各自官方发布为准。
本项目基于 GNU General Public License v3.0 (GPL-3.0) 发布。
- 完整许可证文本见 LICENSE。
- 您可以自由地使用、修改和分发本项目的源代码；任何分发（含修改后版本）都必须以 GPL-3.0 开源，并保留原始版权声明与许可证。
- 本项目按"现状"（as-is）提供，不提供任何明示或暗示的担保。
使用过程中请遵守所在组织各办公平台（钉钉 / 飞书 / 企业微信）开放平台的相关规范与权限要求。