Slogan: 让每一次连接，都更有价值

定位: 先成就关系，再促成合作 — 利他切入的个人商务关系经营系统

PromiseLink 是 AI 驱动的个人商务关系经营助手的开源基础版（MPL 2.0）。 提供事件录入 → 实体提取 → Todo 生成 → 承诺追踪 → 关联发现 → 仪表盘的核心闭环。

🔐 数据主权承诺：不提供 SaaS 服务——所有业务数据 100% 存储在用户本地设备（SQLite），数据从不出家门。这是 PromiseLink 与所有 SaaS AI-CRM 的根本区别：你的关系网络是你最宝贵的资产，不该交给第三方托管。

架构分层：

• 核心算法层（实体归一 / Todo 状态机 / 承诺履行 / 关联发现 / 动态评分）— 主逻辑纯算法实现（NetworkX + RapidFuzz + numpy），含可选 LLM 增强维度（entity_resolution 第5步 llm_reasoning / promise_fulfillment 的 llm_semantic 维度），均具备完整降级机制（PoC 中权重为 0.0），可离线运行、可审计、可复现
• LLM 增强层（实体提取 / NLG 响应生成）— 可选 LLM 增强，需配置 LLM_API_KEY（Moka AI / OpenAI / Anthropic 任选）

不含语音输入、语音查询、邮件同步、微信转发、OCR 名片扫描、隐私数据管理等专业版功能。 基础版可通过 relay_client 可选连接专业版云端网关以使用云端 AI 能力（需专业版 License）。 前端为 Taro H5（桌面浏览器宽屏优先，兼容移动端）。

Topics: crm relationship-management ai-assistant fastapi taro sqlite-vec local-first mpl

诚实声明：实体提取、NLG 响应生成等环节需配置 LLM_API_KEY；核心关系经营算法（5 大模块）为纯算法实现，LLM 不可用时核心闭环仍可降级运行。业务数据始终留在用户本地——即使配置 LLM，也仅传输待解析文本到 AI 服务，分析结果返回后不在云端留存。

• 快速启动
• 30 秒验证
• 质量指标
• 核心能力
• 与主流方案对比
• 项目结构
• 文档索引
• 当前进度
• 技术栈
• 产品版本
• 验证安装
• 团队
• License

⚡ 3 步启动，5 分钟上手，无需 Docker / 无需云账号 / 数据完全本地自主

# 1. 安装依赖
pip install -e '.[dev]'

# 2. 配置环境变量
cp .env.basic.example .env
# 编辑 .env 填入 LLM_API_KEY（Moka AI / OpenAI / Anthropic 任选其一）

# 3. 启动应用（本地直接运行，无需 Docker）
python -m uvicorn promiselink.main:app --host 0.0.0.0 --port 8000
# 或使用一键启动脚本（推荐）
bash scripts/start.sh

# 4. 访问
# API 文档：http://localhost:8000/docs
# 前端界面：http://localhost:8000

无需任何 LLM API Key，即可验证项目工程质量。

git clone https://github.com/lulin70/PromiseLink
cd PromiseLink
pip install -e '.[dev]'
pytest --co -q | tail -1   # 应显示 1953 tests collected
pytest tests/test_security_comprehensive.py -q --no-cov   # 50 项安全测试

分层覆盖率提示：核心算法层（entity_resolution / todo_state_machine / promise_fulfillment / association_discovery / priority_scorer）覆盖率高于项目平均 89%，主逻辑纯算法实现（含可选 LLM 增强维度），确定性可复现。

graph LR
  A[Step01<br/>事件校验+输入分类] --> B[Step02<br/>实体提取+归一]
  B --> C[Step03<br/>实体向量化]
  C --> D[Step04<br/>Todo生成<br/>6类]
  D --> E[Step05<br/>承诺双向分析]
  E --> F[Step06<br/>资源过度承诺检测]
  F --> G[Step07<br/>动态优先级评分]
  G --> H[Step08<br/>通知调度]
  H --> I[Step09<br/>记忆存储]
  I --> J[Step10<br/>关联发现<br/>3策略]
  J --> K[Step11<br/>关联→Todo生成]
  K --> L[Step12<br/>关系简报更新]
  L --> M[Step13<br/>事件完成]

架构分层 — 算法层与 LLM 层解耦：

核心算法层使用 NetworkX + RapidFuzz + numpy 实现，纯 Python 算法，可独立单测、可在无 LLM 环境下运行、确定性可复现、无幻觉风险。

Todo 类型（雾色系）:

• 手动输入 / CSV 导入（语音输入/微信转发/邮件同步为专业版功能）

• 动态优先级评分（4 维：紧急度×0.4 + 重要度×0.6）
• 隐式反馈学习（完成顺序→关系权重）
• 场景匹配（DependencyAnalyzer + ContextMatcher）

PromiseLink/
├── src/promiselink/              # 应用源码
│   ├── models/                 # 数据模型（8 个模型文件，10 个模型类）
│   │   ├── entity.py           # 人物实体
│   │   ├── event.py            # 互动事件
│   │   ├── todo.py             # 行动提醒（6 类）
│   │   ├── association.py      # 关联发现
│   │   └── relationship_brief.py  # 关系简报
│   ├── api/v1/                 # REST API（24 个路由文件）
│   │   ├── health.py           # 健康检查
│   │   ├── events.py           # 事件 CRUD + Pipeline 触发
│   │   ├── entities.py         # 实体管理
│   │   ├── todos.py            # Todo 管理
│   │   ├── associations.py     # 关联查询
│   │   ├── relationship_briefs.py  # 关系简报
│   │   ├── dashboard.py        # 数据看板
│   │   ├── export.py           # 数据导出
│   │   ├── demand_input.py     # 需求输入
│   │   └── auth.py             # 认证
│   ├── services/               # 核心引擎（38 个模块）
│   │   ├── event_pipeline.py   # 13 步事件处理管线
│   │   ├── entity_extractor.py    # LLM 实体提取
│   │   ├── entity_resolution.py    # 实体归一（5 步算法，不依赖 LLM）
│   │   ├── todo_generator.py       # Todo 生成（6 类型策略）
│   │   ├── todo_state_machine.py   # Todo 状态机（不依赖 LLM）
│   │   ├── promise_fulfillment.py  # 承诺履行追踪（不依赖 LLM）
│   │   ├── association_discovery.py # 关联发现（3 策略，不依赖 LLM）
│   │   ├── priority_scorer.py      # 动态优先级评分（不依赖 LLM）
│   │   ├── llm_client.py           # LLM 客户端（Moka AI）
│   │   ├── semantic_search.py      # 向量语义搜索
│   │   ├── memory_provider.py      # CarryMem 集成
│   │   └── ...                     # （20+ 其他服务模块）
│   ├── core/                    # 基础设施
│   │   ├── crypto.py           # 加密（HMAC-SHA256 + 字段加密）
│   │   ├── exceptions.py       # 三层异常体系
│   │   ├── natural_date.py     # 自然日期解析
│   │   └── logging.py / redis.py / wechat.py
│   ├── prompts/                # LLM Prompt 模板
│   └── main.py                 # FastAPI 入口
├── docs/                       # 文档体系
├── tests/                      # 测试（67 个文件 / 1953 用例）
├── data/                       # SQLite 数据存储
├── scripts/                    # 一键安装/启动脚本 + E2E 测试
└── frontend/                   # Taro H5 前端

• PRD v5.8 - 产品需求文档
• 技术设计 v3.2 - 完整技术方案
• 项目状态 - 11 阶段生命周期跟踪
• QUICKSTART - 快速开始指南（含配置参考和 FAQ）
• Setup 指南 - 安装说明（指向 QUICKSTART）

• 数据库设计 v3.0
• API 设计 v3.1
• 算法设计 v2.8
• 测试计划 v5.1
• 集成设计 v2.9
• 部署指南 v0.5.0

安全设计文档（Security_Design 系列、THREAT_MODEL）已随专业版迁移至 PromiseLink-Pro 私有仓库。

• PRD v5.2（关系经营核心闭环 + 向量化语义能力）
• 技术设计 v3.2（Insight Engine + DataSourceAdapter + 向量语义）
• P0 核心算法全部实现（实体归一 / 承诺履行 / 状态机 / 关联发现 / 动态评分）
• FastAPI 完整实现（24 个路由文件 / 63 个 API 端点 / 53 paths）
• 38 个服务模块（Pipeline / NLG / SemanticSearch / MemoryProvider 等）
• 8 个模型文件（entity / event / todo / association / relationship_brief / scheduled_event / reminder / score_audit_log）
• DataSourceAdapter 抽象层（手动 / CSV；语音 / 微信 / 邮件为专业版功能）
• CarryMem 协议解耦（NullMemoryProvider 优雅降级）
• 加密体系（HMAC-SHA256 + 字段级加密 + 行级安全）
• 67 个测试文件 / 1953 测试用例（含 50 个 relay_client 健壮性 + 12 个 v5.6 纠偏 + 6 真实 LLM E2E）/ 89% 覆盖率
• CI/CD + Alembic 就绪
• PoC Demo 4/4 场景通过
• 一键安装 / 启动脚本（本地直接运行，无需 Docker）
• Taro H5 前端打包发布

• 专业版: 网关中继开发（SQLite + relay gateway）
• 定制版: 团队协作功能（PG + Redis + 多租户）

# 健康检查
curl http://localhost:8000/api/v1/health

# 创建互动事件（触发完整 Pipeline）
curl -X POST http://localhost:8000/api/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "event_type": "meeting",
    "source": "manual",
    "raw_text": "今天和张总聊了合作，他说下周需要一份技术方案"
  }'

# 查询实体列表
curl http://localhost:8000/api/v1/entities \
  -H "Authorization: Bearer <token>"

# 查询 Todo 列表（含动态优先级排序）
curl http://localhost:8000/api/v1/todos \
  -H "Authorization: Bearer <token>"

# 语义搜索
curl "http://localhost:8000/api/v1/entities?search=技术合作" \
  -H "Authorization: Bearer <token>"

基础版为纯文本交互，不包含语音功能和图片扫描功能。专业版依赖云端服务凭证。 基础版通过 relay_client 可选连接专业版云端网关以使用云端 AI 能力（需专业版 License）。

依据《生成式人工智能服务管理暂行办法》（国家网信办等七部门联合发布，2023-08-15 施行）第十七条：

提供具有舆论属性或者社会动员能力的生成式人工智能服务的，应当按照国家有关规定开展安全评估，并按照《互联网信息服务深度合成管理规定》履行算法备案和变更、注销备案手续。

以及《生成式人工智能服务安全基本要求》（TC260-003 2024）关于日志留存的要求，PromiseLink 在专业版网关侧实现了国内大模型对话日志 6 个月以上留存机制：

• 存储位置：专业版网关 PostgreSQL 数据库 llm_chat_logs 表
• 留存周期：≥ 180 天（6 个月）
• 日志内容：用户 ID（脱敏）、时间戳、请求内容、响应内容、模型、Token 用量、请求 ID
• 自动清理：scripts/cleanup_chat_logs.py 按 retention_days 配置自动清理过期日志
• 基础版责任：基础版本地不存储 LLM 对话原文，所有 LLM 调用通过专业版网关中继（relay_client → 网关 /api/v1/pro/relay/llm），日志在网关侧统一留存

详见专业版仓库 PromiseLink-Pro docs/planning/LLM对话日志留存6个月方案_v1.md。

• 基础版数据：100% 存储在用户本地设备（SQLite），数据不离开用户设备
• 专业版数据：用户业务数据存储在用户本地设备，仅 LLM/ASR/TTS/OCR 调用经由云端网关中继，网关仅保留调用日志用于合规审计
• 不部署云端基础版：基础版禁止云端部署，所有云端组件（nginx + 网关 + 官网）均不接触用户业务数据

MPL-2.0 — 详见 LICENSE 文件