跳转至

灵知系统 - 流程、原则与规划对齐

版本: v1.3.0 更新日期: 2026-04-03 适用: 全体开发人员和AI助手

一、核心原则（最高准则）

🎯 项目定位

灵知系统 = 集科学研究、理论探索、实践指导于一体的智能生命状态提升系统

💡 核心价值观

价值观 含义
知行合一 理论理解 + 实践应用 + 科学验证
用户中心 尊重意愿、个性化服务、不死板不教条
技术服务生命 技术是手段、生命是目的
完整知识体系 🔬科学 + 📚理论 + 🎯实践

❓ 核心原则三问

所有功能设计、架构决策必须回答：

  1. 这个功能如何帮助用户实践？
  2. 如何验证它真的改善了用户生命状态？
  3. 成功指标是什么？（技术指标 + 生命指标）
如果无法回答这三个问题 → 功能不应该开发

二、开发流程

2.1 开发循环

需求 → 分支 → 编码 → 自检 → 提交 → PR → CI → 合并 → 部署
                  ↓                              ↑
            pre-commit hooks               GitHub Actions
         (black/isort/flake8/bandit)    (lint/test/security)

2.2 分支策略

main (生产，受保护)
  └── develop (集成)
      ├── feature/xxx (新功能)
      ├── fix/xxx (Bug修复)
      └── hotfix/xxx (紧急修复)

2.3 提交规范

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, perf, test, chore, revert
Scopes: backend, frontend, api, db, auth, docs, ci

示例:
feat(backend): 添加智能重试机制
fix(auth): 修复JWT过期验证
docs(readme): 更新安装说明

2.4 Pre-commit 钩子

钩子 功能 自动修复
black 代码格式化 ✅
isort import排序 ✅
flake8 代码规范检查 ❌
bandit 安全漏洞扫描 ❌
trailing-whitespace 清理尾随空格 ✅

三、架构原则

原则 说明
异步优先 所有I/O使用async/await
单例统一 连接池/Redis/Config各只有1个权威实例
委托优于复制 子模块通过委托访问权威实例
优雅降级 可选服务失败不阻塞启动
线程安全 共享资源初始化必须有锁
配置外部化 所有可变配置通过环境变量

关键架构决策(ADR)

ADR 决策
ADR-001 database.py拥有唯一权威db_pool
ADR-002 CacheService拥有唯一权威Redis客户端
ADR-003 核心读写使用asyncpg原生SQL
ADR-004 Pydantic Settings多继承配置
ADR-005 v2 API复用v1 Router

四、安全原则

原则 说明
不硬编码凭据 禁止代码中出现密码/Key
日志脱敏 URL/连接串中的密码不记录
常量时间比较 密码/Token使用hmac.compare_digest
请求体传Token JWT refresh使用POST body
参数化查询 禁止字符串拼接SQL
CORS白名单 生产环境必须配置

五、当前开发规划

5.1 自优化框架进度

┌─────────────────────────────────────────────────────────────┐
│  LingMinOpt 自优化框架 v1.3.0                            │
├─────────────────────────────────────────────────────────────┤
│  ✅ Phase 1 (已完成)                                        │
│     └─ API成功率优化: 95% → 99%                           │
│                                                             │
│  ⏳ Phase 2 (本周)                                            │
│     ├─ 提升用户满意度: 3.8 → 4.2                           │
│     └─ 提升竞品胜率: 45% → 60%                               │
│                                                             │
│  📅 Phase 3 (本月)                                            │
│     └─ Token成本优化、响应延迟优化                            │
└─────────────────────────────────────────────────────────────┘

5.2 短期规划 (04-01 ~ 04-15)

技术基建

优先级 任务 目标
P0 安装pgvector包 消除13个测试错误
P0 测试覆盖率提升至60% CI门槛达标
P1 BGE嵌入API对接 向量检索可用

用户功能

功能 对应原则 优先级
用户画像/评估系统 个性化服务 P1
个性化练习计划生成 知行合一 P1
练习记录与追踪 可验证效果 P1

5.3 中长期规划

┌─────────────────────────────────────────────────────────────┐
│  中期 (04-16 ~ 04-30)                                    │
│  ├─ 练习反馈闭环 (科学验证)                               │
│  ├─ 个性化推荐引擎 (尊重用户意愿)                           │
│  └─ 生命状态仪表板 (可验证效果)                           │
├─────────────────────────────────────────────────────────────┤
│  长期 (05-01+)                                             │
│  ├─ PostgreSQL主从复制 (高可用)                            │
│  ├─ API多实例部署 (高可用)                                │
│  ├─ 社区实践分享 (知行合一)                                 │
│  └─ 课程体系化 (完整知识体系)                               │
└─────────────────────────────────────────────────────────────┘

六、快速检查清单

开发前检查

  • [ ] 能回答核心原则三问？
  • [ ] 分支策略正确？
  • [ ] 符合架构原则？
  • [ ] 安全原则已考虑？

提交前检查

  • [ ] 代码已格式化 (black/isort)
  • [ ] 测试通过 (pytest)
  • [ ] 无安全警告 (bandit)
  • [ ] 提交信息规范？

功能上线检查

  • [ ] 设定了生命指标目标？
  • [ ] 有数据收集方案？
  • [ ] 有效果验证计划？

七、关键文件索引

需求 文件
项目定位 README.md
本文档 ENGINEERING_ALIGNMENT.md
开发规范 DEVELOPMENT_RULES.md
使用指南 USER_GUIDE.md
变更日志 CHANGELOG.md
自优化计划 config/lingminopt_plan.json
API文档 http://localhost:8001/docs

八、当前指标

技术指标

指标 当前值 目标值
API成功率 95% 99% ✅
API延迟 250ms 200ms
数据库超时 30s → 10s 10s ✅
重试次数 3次 5次 ✅

生命指标 (待补充)

指标 当前值 目标值
用户满意度 3.8/5.0 4.2/5.0
竞品胜率 45% 60%
21天坚持率 - >40%
生命状态改善率 - >50%

更新日期: 2026-04-03 下次审查: 每周回顾