个人信息助理项目 - 从多个端点(微信/飞书/邮箱)收集个人隐私数据,构建个人知识库,并通过 LLM 分析生成洞察。
- 🔒 隐私优先: 本地存储,端到端加密,最小权限
- 🔌 端点模块化: 独立的数据源适配器(微信/飞书/邮箱)
- 🕸️ 知识图谱: 实体提取、关系建模、语义搜索
- 🤖 LLM 驱动: AI 分析生成可操作洞察
- 🧪 可观测可测试: 完整的测试覆盖率和结构化日志
通过第三方微信API服务连接和管理微信设备,获取账号信息和接收消息通知。
核心功能:
- ✅ API 连通性测试: 验证 API 凭证和设备连接状态
- ✅ 账号信息获取: 获取登录账号的昵称、头像等基本信息
- ✅ Webhook 消息接收: 接收并记录所有微信通知消息
- ✅ 健康检查端点: 实时监控服务运行状态
快速开始:
# 1. 配置 API 凭证
cp config/wechat.yaml.example config/wechat.yaml
# 编辑 config/wechat.yaml,填入你的 app_key, app_secret, guid
# 2. 测试 API 连接
python cli.py get-profile --device-index 0
# 3. 启动 Webhook 服务
python cli.py serve --port 8000技术特性:
- 🔐 敏感数据脱敏: 自动脱敏日志中的 app_key/app_secret
- ⏱️ 超时和重试: 可配置的连接/读取超时和重试策略
- 🔍 结构化日志: 所有 API 请求/响应完整记录到 JSON 日志
- 🧪 完整测试覆盖: 单元测试、集成测试、契约测试
- 📝 类型安全: 使用 Pydantic 模型验证所有数据
异常处理:
AuthenticationError: API凭证无效或过期NetworkError: 网络连接失败TimeoutError: 请求超时BusinessError: API 业务层面错误(设备不存在等)InvalidParameterError: 请求参数格式或值无效
详细文档:
- 📖 微信 API 快速上手 - 10分钟完成配置和测试
- 📖 微信 Webhook 服务 - Webhook 服务部署指南
- 📖 数据模型 - API 请求/响应数据结构
- 📖 API 契约 - OpenAPI 规范和 JSON Schema
代码示例:
from diting.endpoints.wechat.client import WeChatAPIClient
from diting.endpoints.wechat.config import load_from_yaml
from diting.endpoints.wechat.exceptions import WeChatAPIError
# 加载配置
config = load_from_yaml("config/wechat.yaml")
client = WeChatAPIClient(config)
try:
# 获取用户信息
user_info = client.get_profile(device_index=0)
print(f"昵称: {user_info.nickname}")
print(f"微信号: {user_info.wechat_id}")
except WeChatAPIError as e:
print(f"API 错误: {e.message} (code: {e.error_code})")- 📅 消息同步
- 📅 日历事件提取
- 📅 文档知识库
- 📅 邮件内容提取
- 📅 联系人关系图谱
- 📅 重要邮件标记
新开发人员可在 15 分钟内完成环境配置:
-
克隆仓库
git clone https://github.com/diting/diting.git cd diting -
按照环境设置指南操作
查看详细的分步指南: 📖 环境设置快速开始
指南包含:
- Python 3.12 安装(使用 pyenv)
- uv 依赖管理工具安装
- 虚拟环境创建和激活
- 开发依赖安装
- Pre-commit 钩子配置
- IDE(VS Code/PyCharm)配置
- 验证检查清单
- 常见问题排查
-
验证环境
python --version # 应显示 Python 3.12.x pytest tests/ -v # 运行测试
- 语言: Python 3.12
- 依赖管理: uv
- 代码质量: Ruff (格式化 + linting), Mypy (类型检查)
- 测试框架: Pytest + pytest-cov
- Pre-commit: 自动化代码质量检查
- IDE: VS Code / PyCharm
diting/
├── specs/ # 功能规格和设计文档
├── src/ # 源代码(后续添加)
├── tests/ # 测试代码
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── contract/ # 契约测试
├── docs/ # 项目文档
├── pyproject.toml # 项目配置
├── .python-version # Python 版本固定
└── .pre-commit-config.yaml # Pre-commit 钩子配置
Diting 项目实现了完整的自动化 CI/CD 流程:
每次代码推送时,GitHub Actions 自动运行:
- 代码质量检查: Ruff linter + formatter
- 类型检查: Mypy 类型验证
- 测试套件: Pytest with 80% 覆盖率要求
- 覆盖率报告: 自动生成并上传
合并到 master 分支后,自动部署到阿里云 ECS:
- 零停机部署: 基于符号链接的版本切换
- 健康检查: 部署后自动验证服务状态
- 自动回滚: 健康检查失败时回滚到上一个版本
- 版本管理: 保留最近 3 个版本,自动清理旧版本
- 状态徽章: README 顶部显示 workflow 状态
- 部署历史: GitHub Actions 界面查看详细日志
- 失败通知: 部署失败时自动创建 GitHub Issue
相关文档:
- 📖 CI/CD 快速上手 - 首次部署指南
- 📖 环境差异说明 - 本地/CI/生产环境差异
- 📖 act 本地 CI 工具 - 本地复现 CI 环境
Diting 项目采用 GitHub Flow 分支管理策略:
- Master 分支始终可部署 - master 分支上的代码始终处于稳定状态
- 功能分支开发 - 所有新功能和修复都在独立分支上进行
- Pull Request 审查 - 通过 PR 进行代码审查和 CI 验证
- 快速合并 - 功能完成后尽快合并,避免长期分支
详细文档:
- 📖 贡献指南 - 完整开发流程说明
- 📖 GitHub Flow 详解 - 分支策略详解
- 📖 Commit 规范 - 提交信息规范
# 1. 从 master 创建功能分支
git checkout master
git pull origin master
git checkout -b 003-your-feature-name
# 2. 本地开发和提交(遵循 Conventional Commits 规范)
git add src/your_changes.py
git commit -m "feat(scope): implement your feature"
# 3. 本地测试验证
pytest tests/ -v --cov=src
ruff check . --fix
mypy src/
# 4. 推送功能分支
git push origin 003-your-feature-name
# 5. 创建 Pull Request
# 访问 GitHub 仓库,填写 PR 模板
# 6. 合并到 Master (CI 通过后)
# 使用 "Squash and merge" → 自动删除功能分支# 格式化代码
ruff format .
# Linting 检查
ruff check . --fix
# 类型检查
mypy src/
# 运行所有 pre-commit 检查
pre-commit run --all-files# 运行所有测试
pytest tests/ -v
# 生成覆盖率报告
pytest --cov=src --cov-report=html
open htmlcov/index.html # 查看详细报告
# 运行特定测试
pytest tests/unit/test_example.py -v
# 检查覆盖率阈值(≥ 80%)
coverage report --fail-under=80遵循 Conventional Commits 规范:
# 格式: <type>(<scope>): <subject>
# 新功能
git commit -m "feat(webhook): implement message retry logic"
# Bug 修复
git commit -m "fix(wechat): handle API timeout gracefully"
# 文档更新
git commit -m "docs: update README installation guide"
# 测试代码
git commit -m "test(webhook): add integration tests"常用 Type: feat, fix, docs, test, refactor, perf, chore, style, ci
常用 Scope: wechat, webhook, kg, llm, cli, config, logger
欢迎贡献!请遵循以下步骤:
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'feat: Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
所有代码必须:
- ✅ 通过 Ruff 格式化和 linting
- ✅ 通过 Mypy 类型检查
- ✅ 包含单元测试(覆盖率 ≥ 80%)
- ✅ 通过所有现有测试
Diting 项目遵循严格的宪章,定义了 5 个核心原则:
- Privacy First (非协商): 本地存储,端到端加密,最小权限
- Endpoint Modularity (非协商): 独立的端点适配器
- Knowledge Graph Core: 实体提取和关系建模
- LLM-Powered Insights: AI 驱动的洞察生成
- Observability & Testability: 可观测和可测试
MIT License - 详见 LICENSE 文件
- 项目主页: https://github.com/diting/diting
- Issue 追踪: https://github.com/diting/diting/issues
- 文档: https://github.com/diting/diting/tree/main/docs
版本: 0.1.0 最后更新: 2025-11-01