---
## v0.16.3 DeepSeek Thinking 与智能周复盘收口
v0.16.3 将 Garmin 恢复事实、Partial Facts / Decision Readiness、DeepSeek Thinking、多轮 Tool Calling、Weekly Review Analysis、独立 Plan Design、Evidence Judge / Reflect 与 Approval Checkpoint 收口为一个正式版本。周复盘分析和计划设计使用相互独立的模型请求、上下文与输出预算；计划修改仍必须经过 Python/Pydantic 物化、确定性校验、HITL 审批和服务端重新校验。
详见 [v0.16.3 发布说明](docs/release/v0.16.3.md)。原始 Provider reasoning 仅作为可配置的内部诊断数据，不进入 REST、MCP、Trace、Metrics、Evaluation Report、Canonical Evidence 或前端。
### v0.16.0 检索质量与安全边界
训练知识检索支持 Dense Exact、可选 Qdrant、确定性 BM25、固定 Hybrid RRF 与可选 Reranker。策略通过独立的 40 条公开虚构 Holdout v2 消融评测选择，而不是将已反复使用的 Legacy 回归集当作盲测。当前默认保持 Dense Exact：它在 Holdout 上与 Rerank 同为 33/40 通过，同时拥有更低的运行复杂度；Rerank 保留为真实 Provider 已验证的非默认能力，并在故障时安全回退。
详见 [v0.16.0 发布说明](docs/release/v0.16.0.md) 与 [Holdout 报告](docs/evaluation/reports/retrieval-holdout-v2.md)。检索只提供知识解释，不修改 Runner State、TODAY 确定性建议或训练计划。
### v0.16.1 / v0.16.2 已合并开发记录
以下两个开发快照未单独发布，现已合并进入 **v0.16.3**：
- **v0.16.1 Garmin Recovery Data Sync**：在既有 Garmin Pipeline 中归一化睡眠、静息心率、HRV、压力、Body Battery 和呼吸率等日级恢复事实；字段缺失保持为空并形成 limitation，用户手动填写的恢复信息优先保留。
- **v0.16.2 Partial Facts & Decision Readiness**：将“缺少部分指标”和“核心数据不可用”区分为 `PARTIAL` 与 `BLOCKED`。例如缺 RPE 不再让 Coach TODAY 整体失效；相关负荷规则显示为“未参与判断”，而不是把缺失数据误当作正常值。
这两项都不改变 TODAY 的确定性决策所有权：训练事实、规则结论、warning、limitation 和 Evidence 继续由服务端控制。详情见 [更新历史](docs/更新历史.md)。
---
## 🧭 一屏看懂
GaitLogic Planner 不是一个简单的跑步打卡工具。它更关注训练管理闭环：
```text
制定计划 -> 执行训练 -> 填写日志 -> 查看统计 -> 复盘调整 -> 继续训练
```
AI 生成内容仅作为训练计划草稿，不构成医疗建议、康复建议或专业教练处方。请结合自身恢复、伤病情况、天气、地形和实际训练反馈调整。
### 当前能力主线
| 能力 | 解决的问题 | 安全边界 |
| --- | --- | --- |
| 训练管理闭环 | 计划、执行、日志、日历、统计与复盘分散 | 多用户隔离，正式计划变更需要用户确认 |
| Runner State 与 Training Readiness | 近期负荷、恢复和数据质量难以统一理解 | 确定性计算；部分数据可分析但会显式标注限制 |
| Coach Agent | 模型容易脱离训练事实自由回答 | 只读工具提供事实，规则确定边界，Validator 拦截越权 |
| Training Knowledge RAG | 训练解释缺少可核验依据 | 引用由服务端还原；知识检索不能覆盖 TODAY 决策 |
| Weekly Review 与 Proposal | 周复盘结论难以转化为可审查调整 | Proposal、HITL、版本校验、事务和回滚共同保护写入 |
| Garmin 与 Data Sync | 外部活动导入、去重和关联链路复杂 | 统一 Pipeline、稳定运行标识、事务隔离与非阻塞快照 |
| MCP 与可观测性 | 外部客户端接入和 Agent 故障定位困难 | MCP 默认只读；Trace/Metric 采用白名单且不记录业务正文 |
### v0.11.0 Coach Agent
v0.11.0 新增只读 Coach Agent：八个严格 Schema 约束的训练工具提供事实，Runner State 与确定性规则负责决策边界，OpenAI-compatible Gateway 负责受控工具编排与语言解释，Validator 和 Fallback 负责阻止越权输出并在 Provider 不可用时维持可用建议。
```text
训练事实 → 只读工具 → 确定性规则 → 受控模型解释 → Validator → 可解释建议
```
今日训练建议中的 decision、计划状态、风险、数据质量、警告、限制与 canonical Evidence 均由服务端确定；模型只生成说明文本并引用服务器分配的 Evidence ID。系统不会自动修改训练计划，也不提供医疗诊断。
### v0.10.3 Runner State
v0.10.3 新增跑者当前状态、7/28 天训练指标、确定性推断、Evidence 与数据质量说明，并提供手动历史快照、趋势和详情。Garmin 同步在训练事实发生有效变化后，可通过独立事务创建非阻塞状态快照：
```text
Garmin 训练事实 -> Material Change -> Runner State -> 自动快照 -> 历史趋势 -> 可解释反馈
```
Runner State 不提供医疗诊断，不调用大语言模型计算状态，也不会自动生成或修改正式训练计划。
### Runner State
Runner State 根据近期训练事实、数据质量和规则证据形成可解释的当前状态，并保留历史快照和趋势。
### Training Readiness
Training Readiness 用于展示当前训练准备情况、关键依据和限制，不用于医疗诊断。
## GaitLogic Coach Agent
Coach Agent 把结构化训练事实、确定性规则和受限模型解释组合成一个只读训练建议界面：
```text
结构化训练数据负责事实
→ Runner State 与规则引擎负责决策边界
→ LLM 负责受限工具编排和解释
→ Validator 阻止越权或覆盖规则的输出
→ Fallback 保证模型不可用时仍可返回确定性建议
```
它不是普通聊天接口：LLM 不直接访问数据库，用户身份由服务端认证上下文注入，Tool 输入输出经过 Pydantic Schema 校验，今日建议的 Decision 来自确定性规则，而且模型不能修改正式计划。
### AI 教练 Agent
GaitLogic Coach Agent 将结构化训练事实、确定性训练规则和大语言模型解释能力组合起来。规则和 Runner State 负责结论边界，模型只负责工具编排和自然语言解释。
### v0.14.0 Agent 可观测性、评测与可靠性
v0.14.0 将既有 Coach、RAG、Weekly Review 与人工批准链路工程化：安全 Trace/Span、可选 OpenTelemetry 输出、低基数运行 Metrics、统一 Provider Failure Taxonomy、有限重试与确定性 Fallback，以及四套公开虚构回归评测。运行指标不保存用户问题、Prompt、训练正文、原始模型响应、身份信息或凭据；它们只用于定位组件延迟、失败和降级趋势。
评测复现命令为 `python scripts/evaluate_agent.py --suite all`。当前 Coach、RAG、Weekly Adaptive 套件通过；Retrieval 保留基线中的 17 项失败，整体为 `PARTIAL`，未伪装为 PASS。详见 [v0.14.0 学习地图](docs/learning/v0.14.0/00-v0.14.0-overview.md)。
### v0.13.0 周复盘与自适应训练闭环
v0.13.0 新增确定性 Weekly Facts、LangGraph 周复盘、训练知识引用、可审查的计划调整 Proposal、人工批准/拒绝、持久 Checkpoint、计划版本与受控回滚。模型只负责解释和受限候选生成；训练事实与规则由服务端确定，计划只有在当前用户明确批准并通过服务端重新校验后才会写入。
```text
训练计划 -> 训练日志 -> Weekly Facts -> Rules -> LangGraph Review
-> Proposal Diff -> Human Approval -> New Plan Version -> Audit/Rollback
```
前端入口为 `/adaptive-weekly-review`。公开虚构评测与复现命令见 [Weekly/Adaptive Evaluation](docs/weekly-review/evaluation/weekly-adaptive-eval-v1.md)，实现复习见 [v0.13.0 Learning Docs](docs/learning/v0.13.0/01-v0.13.0-architecture.md)。本能力不构成医疗诊断，也不会把通用数据库写权限交给 LLM。
下一周训练调整
### v0.12.0 训练知识 RAG 与可信引用
Coach Agent 通过只读 `retrieve_training_knowledge` 工具检索版本化训练知识。模型只选择本次请求内的临时 Reference ID，服务端负责校验并物化标题、来源、版本、证据等级和摘录，避免模型伪造来源。知识用于解释，不参与或覆盖 TODAY 的确定性 Decision。
```text
结构化业务工具 → 用户训练事实
确定性规则引擎 → 训练决策边界
训练知识 RAG → 专业知识与解释依据
LLM → 受限工具编排与自然语言
Canonical Reference → 服务端还原可信引用
Validator / Fallback → 越权拦截与安全降级
```
v0.12.0 当前按邀请制 Alpha 发布。界面、状态和安全边界见 [Training Knowledge Reference UI v1](docs/rag/training-knowledge-reference-ui-v1.md)，升级与回滚见 [v0.12.0 Release Notes](docs/releases/v0.12.0-release-notes.md)。私有 Retrieval 标签确认和人工盲评尚未完成，不影响产品公开能力，但不得表述为竞赛总门禁已通过。
### Agent 能力
当前注册八个训练事实工具和一个训练知识检索工具：
- `get_runner_state`
- `get_runner_state_history`
- `get_recent_training`
- `get_today_workout`
- `get_current_training_cycle`
- `get_training_rules`
- `evaluate_today_workout`
- `get_training_data_quality`
- `retrieve_training_knowledge`
Agent 调用链遵循“前端请求 → 服务端身份与 Intent Policy → 只读工具/知识检索 → Provider → Canonical Materializer → Validator → 正常响应或确定性 Fallback”。业务代码不直接把数据库、Prompt 或任意工具权限交给模型。完整关系见下方[系统架构图](#-系统架构)和 [Coach Agent Architecture v1](docs/agent/coach-agent-architecture-v1.md)。
### Evaluation
Coach Agent Evaluation v1 使用 32 条固定日期、完全虚构的案例验证工具召回、Decision/Plan 一致性、Warning/Limitation 保留、Fallback 和越权声明。它默认使用 Mock Gateway，不读取 API Key，不访问网络或生产数据库，也不使用第二个 LLM 当裁判。
真实运行结果见 [Coach Agent Evaluation v1 Results](docs/agent/evaluation/results/coach-agent-eval-v1.md)；复现命令：
```powershell
python scripts/evaluate_coach_agent.py
```
### Coach Quick Start
```powershell
# 后端
python -m uvicorn server.main:app --reload
# 前端
cd web
npm ci
npm run dev
```
`.env.example` 中 Coach Provider 默认关闭且 Key 为空。此时 `/coach` 使用确定性 Fallback 展示可用的只读建议；安全 Demo 流程见 [Coach Agent Demo v1](docs/agent/coach-agent-demo-v1.md)。
部署 Training Knowledge RAG 前先执行离线校验：
```powershell
python scripts/knowledge_corpus.py validate
python scripts/knowledge_index.py validate --index-id 
