灵知系统 - 整体开发计划 (修正版)

版本: 2.0.0 (基于自我审计修正) 日期: 2026年3月31日 基线版本: v1.3.0-dev 计划周期: 2026年4月1日 - 2026年6月30日 (3个月) 项目: 智能知识系统 (Zhineng Knowledge System)

---

🔄 V2.0 修正说明

修正的 5 个关键点

#	原计划问题	修正方案	优先级
1	Phase 1 纯技术基建，用户无感知	Week 1-2 立即建立生命周期追踪机制	🔴 P0
2	测试覆盖率 29%→70% (1周) 不现实	分阶段: 29%→50%→60%→70%	🔴 P0
3	工作量估计基于经验，不准确	基于真实数据重新评估 (×1.5倍)	🔴 P0
4	生命周期测量从 Phase 2 开始	Week 1 立即开始基线收集	🔴 P0
5	风险管理不足	增加详细的应急预案和降级方案	🟠 P1

---

📋 执行摘要

核心定位

不是：简单的知识问答系统、技术展示平台 而是：帮助用户提升生命状态的智能辅助系统

核心公式

灵知系统 = (科学 + 理论 + 实践) × 智能 × 个性化

三个月目标 (修正版)

维度	当前	1个月	2个月	3个月
测试覆盖率	29%	45%	55%	65%
生命周期追踪	无	基线建立	数据收集	初步分析
实践转化率	未知	-	-	>10%
用户功能	问答	追踪MVP	计划MVP	完整功能

关键调整: - ✅ 降低测试覆盖率目标 (70% → 65%) - ✅ 立即启动生命周期追踪 - ✅ 用户功能从 Week 3 开始交付 - ✅ 实践转化率目标更现实 (>10% vs >30%)

---

🎯 一、战略对齐 (不变)

1.1 核心原则（最高准则）

"注重实践，避免空谈，一切围绕用户生命状态的提升提供服务"

1.2 核心原则三问

1. 这个功能如何帮助用户实践？
2. 如何验证它真的改善了用户生命状态？
3. 成功指标是什么？（技术+生命）

1.3 生命指标测量框架 (不变)

直接指标

指标	测量方式	数据来源	频率
连续练习天数	用户累计练习天数	practice_records表	实时
用户等级迁移	入门→进阶→高级	user_levels表	实时
生命状态自评	用户自评（1-10分）	life_state_tracking表	每周
练习完成率	计划vs实际完成	practice_plan表	每周

代理指标

指标	测量方式	代理目标	频率
实践转化率	知道理论后开始实践的比例	用户实际开始练习	每月
21天坚持率	持续练习21天的用户比例	形成习惯的能力	每月
生命状态改善率	自评有改善的用户比例	实际效果验证	每月
推荐意愿	愿意推荐给朋友的用户比例	满意度	每月

---

📊 二、当前状态基线 (不变)

2.1 项目规模

总代码: 33,070 行 (135个Python文件)
测试: 232个通过, 13个error (pgvector未安装)
覆盖率: 29% (目标60%)
版本: v1.3.0-dev
分支: develop

2.2 技术债务状态

等级	数量	已清理	待处理
P0	6	5	1 (测试覆盖率)
P1	8	7	1 (DB模式统一)
P2	10	3	7
P3	6	0	6
合计	30	15	15

---

🗓️ 三、三个月路线图 (修正版)

Phase 1: 快速交付用户价值 (4月1日 - 4月30日)

目标调整: 从"夯实基础"改为"快速交付用户价值"

Week 1-2: 生命周期追踪机制建立 🔴 P0

任务1.1: 创建生命周期数据库 (Day 1-2)

-- 用户等级表
CREATE TABLE user_levels (
    user_id VARCHAR(100) PRIMARY KEY,
    current_level VARCHAR(50),
    level_history JSONB,
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 生命状态追踪表
CREATE TABLE life_state_tracking (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(100),
    tracked_date DATE,
    physical_health INT CHECK (physical_health BETWEEN 1 AND 10),
    mental_peace INT CHECK (mental_peace BETWEEN 1 AND 10),
    energy_level INT CHECK (energy_level BETWEEN 1 AND 10),
    sleep_quality INT CHECK (sleep_quality BETWEEN 1 AND 10),
    emotional_stability INT CHECK (emotional_stability BETWEEN 1 AND 10),
    subjective_notes TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 练习记录表 (简化版)
CREATE TABLE practice_records (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(100),
    concept VARCHAR(200),
    practice_date TIMESTAMP,
    duration_minutes INT,
    subjective_feeling TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 练习计划表 (简化版)
CREATE TABLE practice_plans (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(100),
    plan_name VARCHAR(200),
    start_date DATE,
    end_date DATE,
    status VARCHAR(50),
    created_at TIMESTAMP DEFAULT NOW()
);

验收: ✅ 4 张表创建成功，迁移脚本完成

任务1.2: 建立手动记录机制 (Day 3-5)

最小化记录API (不需要AI):

POST /api/v1/life-state/record
- 记录生命状态自评
- 支持手动输入

POST /api/v1/practice/record
- 记录一次练习
- 最简单字段: 时间、内容、时长

GET /api/v1/practice/my-records
- 查看我的练习记录
- 简单列表展示

验收: ✅ 3 个 API 可用，前端简单表单

任务1.3: 收集首批基线数据 (Day 6-10)

目标: 收集 10 个用户的基线数据

方法: - 手动邀请 10 个测试用户 - 每人记录 1 次初始生命状态 - 每人创建 1 个初始练习计划

验收: ✅ 10 条 user_levels 记录，10 条 life_state_tracking 记录

价值: - 🎯 用户立即感知: 系统"关心我的状态" - 📊 建立基线: 后续测量才有意义

---

Week 3: 测试基础设施 + 向量嵌入对接

任务1.4: 修复 13 个测试错误 (Day 1-3)

# 安装 pgvector
sudo apt-get install postgresql-16-pgvector

# 重新运行测试
pytest tests/ -v

验收: ✅ 0 error, 232 passed

任务1.5: 补充核心模块测试 (Day 4-10)

# 优先级排序:
1. services/retrieval/      # 核心功能
2. api/v1/                  # 用户接口
3. domains/                 # 业务逻辑

目标: 覆盖率 29% → 45%

验收: ✅ pytest --cov 报告 ≥45%

任务1.6: 向量嵌入对接 (Day 11-15)

集成 BGE-M3 嵌入服务:

# services/embeddings/bge_service.py (新建)
from sentence_transformers import SentenceTransformer

class BGEEmbeddingService:
    def __init__(self):
        self.model = SentenceTransformer('BAAI/bge-small-zh-v1.5')

    def embed_text(self, text: str) -> List[float]:
        return self.model.encode(text)

集成到 VectorRetriever:

# services/retrieval/vector.py
from services.embeddings.bge_service import BGEEmbeddingService

class VectorRetriever:
    def __init__(self):
        self.bge = BGEEmbeddingService()

    def embed_text(self, text: str) -> List[float]:
        return self.bge.embed_text(text)  # 真实嵌入

验收: ✅ 向量检索准确率 >90%

---

Week 4: 实践计划 API (MVP版本)

任务1.7: 手动实践计划生成 (Day 1-7)

不需要AI的简化版本:

POST /api/v1/practice/plan/generate-mvp

输入:
{
  "user_level": "入门",
  "goal": "改善睡眠",
  "time_budget": "每天15分钟"
}

输出:
{
  "plan_name": "7天助眠入门计划",
  "daily_tasks": [
    {
      "day": 1,
      "task": "练习放松功法 - 卧式",
      "duration_minutes": 15,
      "content": "平躺床上... (详细步骤)"
    },
    ...
  ],
  "milestones": [
    {"day": 3, "milestone": "能快速入睡"},
    {"day": 7, "milestone": "睡眠质量提升"}
  ]
}

实现方式: - 基于模板生成 (不需要AI) - 支持几个预定义计划模板 - 7天入门、21天习惯养成

验收: ✅ API 可用，支持 3 个预定义模板

价值: - 🎯 用户立即获得: "我有具体的练习计划" - 📊 可追踪: 用户记录实践 → 系统验证效果

---

Phase 1 修正总结

原计划	修正后	价值提升
Week 1-4: 纯技术基建	Week 1-2: 生命周期追踪	⭐⭐⭐⭐⭐
Week 5-8: 用户功能	Week 3: 实践计划MVP	⭐⭐⭐⭐
测试覆盖率 29%→70% (1周)	29%→45% (分阶段)	⭐⭐⭐

关键改进: 用户从 Week 3 就能感知到新功能

---

Phase 2: 完善用户功能 (5月1日 - 5月31日)

目标: 从 MVP 走向完整功能

Week 1-2: AI 驱动的个性化计划

任务2.1: 集成 LLM 生成个性化计划

从手动模板 → AI 生成:

POST /api/v1/practice/plan/generate-ai

输入:
{
  "user_level": "入门",
  "goal": "改善睡眠",
  "time_budget": "每天15分钟",
  "experience": "我经常失眠，晚上睡不着"
}

# LLM 生成
- 理论依据
- 具体方法
- 每日计划
- 阶段目标
- 注意事项

验收: ✅ AI 生成的计划质量通过人工审核

Week 3-4: 数据库访问统一

任务2.2: 统一为 asyncpg raw SQL

范围: 只重构核心访问路径

# 优先级:
1. services/          # 业务逻辑层
2. api/v1/            # 接口层
3. domains/           # 领域层

# 暂不重构:
- core/database.py   # 已有单例
- cache/             # 已统一

验收: ✅ 核心代码统一，SQLAlchemy 引用移除

Week 5-6: 核心API 实践导向重构

任务2.3: 重构 /api/v1/search 端点

之前: 只返回知识

{
  "answer": "气功是通过...",
  "sources": [...]
}

之后: 询问用户意愿，返回完整方案

{
  "dialogue": {
    "current_level": "请问您是否有气功基础？",
    "goals": "您希望达到什么目标？",
    "time_budget": "您每天能投入多少时间？"
  },
  # 基于用户回答生成
  "personalized_plan": {
    "theory": "理论基础",
    "practice": "具体方法",
    "schedule": "每日计划",
    "milestones": "阶段目标"
  }
}

实现方式: - 对话式 API (多次请求) - 或者前端表单收集后一次性提交

验收: ✅ 新 API 可用，前端集成完成

---

Phase 3: 完善与优化 (6月1日 - 6月30日)

目标: 建立完整生态，准备规模化

Week 1-2: 自学习系统扩展

任务3.1: 科学研究监控 (简化版)

手动监控 (不需要自动化): - 每周手动搜索 arxiv 关键词 - 人工筛选相关研究 - 手动更新知识库科学依据

关键词: - qigong, meditation, mindfulness - traditional chinese medicine - confucianism, buddhism, taoism

验收: ✅ 每周更新 1 篇相关研究摘要

Week 3-4: 内容生成系统

任务3.2: 增强生成能力

新增功能: - 科学研究报告生成 - 实践指南生成 - 个性化计划生成

实现: - 基于 DeepSeek API - 提供高质量模板

验收: ✅ 生成内容通过人工审核

Week 5: 效果验证机制

任务3.3: 第一份效果分析报告

数据收集 (4-5 月累计): - 生命周期指标追踪 - 用户反馈收集 - 实践效果评估

分析报告: - 实践转化率: 目标 >10% - 平均练习天数 - 生命状态自评变化 - 用户反馈总结

验收: ✅ 第一份效果分析报告发布

Week 6: 外部API完善

任务3.4: API 管理

功能增强: - API密钥管理 - 基于角色的权限控制 - 使用量限制和监控

验收: ✅ 外部 API 文档完整

---

🎯 四、成功指标 (修正版)

4.1 技术指标

指标	当前	1个月	2个月	3个月	验证方式
测试覆盖率	29%	45%	55%	65%	pytest --cov
API响应时间	~200ms	<180ms	<160ms	<150ms	Prometheus
检索准确率	~85%	>88%	>90%	>92%	用户反馈
系统稳定性	95%	>96%	>97%	>98%	Uptime监控

关键修正: 测试覆盖率目标更现实，分阶段达成

4.2 生命周期指标

指标	基线	1个月	2个月	3个月	验证方式
追踪用户数	0	≥10	≥50	≥100	user_levels表
练习记录数	0	≥50	≥200	≥500	practice_records表
实践转化率	未知	-	-	>10%	用户反馈
生命状态改善	未知	-	-	>5%	life_state_tracking表

关键修正: - ✅ 立即开始追踪 (Week 1) - ✅ 目标更现实 (>10% vs >30%) - ✅ 渐进式验证

---

🚨 五、风险管理 (修正版)

5.1 技术风险

风险	影响	概率	缓解措施	应急预案
pgvector集成失败	向量检索不可用	中	提前测试，准备 BM25 兜底	BM25 检索
BGE服务不稳定	检索质量下降	中	缓存嵌入结果	SHA-256 临时
测试进度落后	无法达成目标	高	分阶段达成	65% 可接受
LLM API限流	计划生成失败	中	降级到手动模板	手动模板

5.2 产品风险

风险	影响	概率	缓解措施	应急预案
用户不追踪	无数据可分析	高	简化追踪流程	手动追踪
练习内容不足	用户无法实践	中	优先补充核心内容	分批上线
效果不明显	用户流失	高	长期追踪，降低预期	教育+引导

5.3 资源风险

风险	影响	概率	缓解措施	应急预案
开发时间不足	无法完成	中	分优先级，保 P0	调整到下个季度
数据库容量不足	无法存储追踪数据	低	定期清理，归档	扩容

---

📋 六、关键里程碑 (修正版)

Milestone 1: 生命周期追踪建立 (4月14日)

• ✅ 4 张生命周期表创建
• ✅ 手动记录 API 可用
• ✅ 首批 10 个用户基线数据

Milestone 2: 测试基础设施修复 (4月21日)

• ✅ 13 个测试错误修复
• ✅ 测试覆盖率 29% → 45%

Milestone 3: 向量嵌入对接 (4月28日)

• ✅ BGE-M3 嵌入服务集成
• ✅ 向量检索准确率 >90%

Milestone 4: 实践计划 MVP (4月30日)

• ✅ 3 个预定义计划模板
• ✅ 手动计划生成 API
• ✅ 用户可追踪练习

Milestone 5: AI 驱动个性化 (5月15日)

• ✅ LLM 生成个性化计划
• ✅ 核心API实践导向重构

Milestone 6: 数据库访问统一 (5月31日)

• ✅ 核心代码统一为 asyncpg raw SQL

Milestone 7: 第一份效果报告 (6月30日)

• ✅ 生命周期数据收集
• ✅ 效果分析报告
• ✅ 用户反馈总结

---

✅ 七、承诺与验收 (修正版)

7.1 开发团队承诺

• [ ] 每周必做: 询问"核心原则三问"
• [ ] Week 1 必做: 建立生命周期追踪机制
• [ ] 每双周: 进度回顾和优先级调整
• [ ] 每月: 生成一份进度报告

7.2 最终验收标准 (6月30日)

技术指标: - ✅ 测试覆盖率 ≥ 65% (修正: 原 70%) - ✅ API响应时间 < 150ms - ✅ 检索准确率 > 90% - ✅ 系统稳定性 > 98%

功能指标: - ✅ 生命周期追踪机制建立 - ✅ 个性化实践计划 API 可用 - ✅ 核心API实践导向重构

生命周期指标: - ✅ 追踪用户数 ≥ 100 - ✅ 练习记录数 ≥ 500 - ✅ 实践转化率 ≥ 10% - ✅ 第一份效果分析报告

---

📊 八、修正前后对比

维度	原计划	修正后	改进
用户价值感知时间	Phase 2 (5月)	Week 3 (4月)	⭐⭐⭐⭐⭐
测试覆盖率目标	29%→70% (1周)	29%→65% (分阶段)	⭐⭐⭐⭐
生命周期测量开始	Phase 2	Week 1	⭐⭐⭐⭐⭐
实践转化率目标	>30%	>10%	⭐⭐⭐⭐
风险管理	简单	详细应急预案	⭐⭐⭐⭐

---

🎯 九、核心原则践行示例 (更新)

示例1: 生命周期追踪功能 (Week 1-2)

三问回答:

1. 如何帮助用户实践？
2. 系统关心用户状态 (生命状态自评)
3. 记录用户练习进展

4. 提供可视化反馈

5. 如何验证改善生命状态？

6. Week 1: 收集基线数据 (10 个用户)
7. Week 4: 第一次趋势分析

8. Week 8: 第一次效果评估

9. 成功指标是什么？

10. 技术: API 可用，数据存储正确
11. 生命: 用户愿意记录 (记录数 ≥50)
12. 生命: 用户自评改善 (≥5%)

价值: ⭐⭐⭐⭐⭐ - 立即感知: 系统关心我的状态 - 建立基线: 后续测量有参照

---

示例2: 实践计划 MVP (Week 3-4)

三问回答:

1. 如何帮助用户实践？
2. 提供具体的每日练习计划
3. 明确练习步骤和要点

4. 设置阶段性目标

5. 如何验证改善生命状态？

6. 追踪用户是否按计划练习
7. 追踪用户是否达到里程碑

8. 用户自评是否有改善

9. 成功指标是什么？

10. 技术: API 可用，计划合理
11. 生命: 用户创建计划数 ≥20
12. 生命: 用户记录练习数 ≥50

价值: ⭐⭐⭐⭐ - 立即获得: "我有具体的练习计划" - 可追踪: 练习记录 → 效果验证

---

📝 十、开发计划与工作量修正

10.1 工作量估计修正原则

原计划: 基于经验的估计 修正后: 基于真实数据 × 1.5 倍缓冲

示例:

原估计: 测试覆盖率提升 1 周
修正: 1 周 × 1.5 = 1.5 周 ≈ 2 周

原估计: 向量嵌入对接 1 周
修正: 1 周 × 1.5 = 1.5 周 ≈ 2 周

10.2 关键任务工作量 (修正后)

任务	原估计	修正后	理由
生命周期数据库创建	2天	3天	×1.5
手动记录 API	3天	5天	包含前端
首批基线数据收集	5天	5天	保持
修复测试错误	3天	3天	保持
补充核心模块测试	5天	8天	×1.5
向量嵌入对接	5天	8天	×1.5
实践计划 MVP	5天	8天	×1.5
数据库访问统一	5天	8天	×1.5

---

🎓 十一、总结与承诺

核心修正

1. ✅ 用户价值优先: Week 1-2 立即建立生命周期追踪
2. ✅ 目标更现实: 测试覆盖率分阶段达成 (29%→45%→55%→65%)
3. ✅ 工作量准确: 基于真实数据 × 1.5 倍缓冲
4. ✅ 渐进式验证: 立即开始基线收集，持续测量
5. ✅ 风险可控: 详细的应急预案和降级方案

核心承诺

对用户承诺: - Week 3: 用户能感受到新功能 (生命周期追踪 + 实践计划) - Week 8: 用户能使用 AI 生成的个性化计划 - Week 12: 用户能看到效果分析报告

对团队承诺: - 每周回顾进度 - 每双周调整优先级 - 每月发布进度报告

---

📌 最后的话

核心公式:

灵知系统 = (科学 + 理论 + 实践) × 智能 × 个性化

核心逻辑:

用户感知价值 (Week 3)
    ↓
开始实践并记录 (Week 4-8)
    ↓
数据积累并分析 (Week 9-12)
    ↓
验证效果并优化 (持续进行)

最终目标:

不是建立最先进的技术系统 而是帮助最多的人提升生命状态

技术是工具，生命改变才是目的。

---

"注重实践，避免空谈，一切围绕用户生命状态的提升提供服务"

---

项目路径: /home/ai/zhineng-knowledge-system 计划版本: 2.0.0 (基于自我审计修正) 生效日期: 2026-04-01 下次回顾: 2026-04-14 (双周回顾)