zhuyongxin
473bb5d004
- rewrite RAG architecture doc for py-rag service contract mapping, ingest and rebuild ops - refresh observability/trace doc for post-L0 single-attempt semantics - add py-rag chain exploration note; mark superseded Milvus/L0 notes with status banners - close ISS-017 (superseded by L0 sinking); mark knowledge_domain table orphaned - refresh architecture/mvp/engineering indexes
91 lines
6.8 KiB
Markdown
91 lines
6.8 KiB
Markdown
# MVP 工程纪要（Engineering Notes）
|
||
|
||
**更新日期**：2026-07-30
|
||
**定位**：项目推进中真实遇到的问题、决策、解决思路与 E2E 验收叙事。
|
||
|
||
与其它目录分工：
|
||
|
||
| 目录 | 读什么 |
|
||
|---|---|
|
||
| [architecture/](../architecture/) | **现行架构**（系统现在怎么跑） |
|
||
| **engineering/**（本目录） | **为何这样定**、踩坑、方案取舍、live 验收导读 |
|
||
| [issues/](../issues/) | 未完成事项与状态 |
|
||
| [tables/](../tables/) | 表结构说明 |
|
||
|
|
||
| `devflow/projects/` | 单次变更的 brief/decisions/evidence 切片 |
|
||
|
||
本文档**不是** API 规范的唯一真理源；冲突时以 `architecture/` 与代码为准。
|
||
|
||
---
|
||
|
||
## RAG
|
||
|
||
> 2026-09-29 RAG 模块已抽离为独立 py-rag 知识服务（架构见
|
||
> [../architecture/RAG知识检索架构.md](../architecture/RAG知识检索架构.md)）。
|
||
> 下列纪要保留决策过程价值，涉及进程内 Milvus / L0 的实现细节以各文顶部说明为准。
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [rag/RAG证据链探索笔记-从py-rag响应到引用验真.md](rag/RAG证据链探索笔记-从py-rag响应到引用验真.md) | **抽离后链路首发导读**：数据逐站形态、关键字段、设计哲学与化石清单 |
|
||
| [rag/RAG排序-多路召回与RRF.md](rag/RAG排序-多路召回与RRF.md) | K、多路融合、RRF、L0 边界（实现已下沉 py-rag，判断框架仍有效） |
|
||
| [rag/RAG-Hybrid质量分与后处理.md](rag/RAG-Hybrid质量分与后处理.md) | qualityScore 统一、后处理（分数语义现为 RERANK 直传） |
|
||
| [rag/RAG-Agent如何读relevance_level.md](rag/RAG-Agent如何读relevance_level.md) | Agent 侧相关度标签含义与误读（现行） |
|
||
| [rag/RAG离线评测-基线设计.md](rag/RAG离线评测-基线设计.md) | Golden/Fixture、hybrid 评测与闸门（需按新语义重新校准） |
|
||
| [rag/Milvus-Hybrid接入清单.md](rag/Milvus-Hybrid接入清单.md) | Hybrid 交付拆分与接入清单（已过时，仅历史追溯） |
|
||
| [rag/RAG审计补丁-stepid-query-E2E验收.md](rag/RAG审计补丁-stepid-query-E2E验收.md) | step_id / query 审计 live 验收（现行） |
|
||
|
||
架构对照：
|
||
|
||
- [architecture/RAG知识检索架构.md](../architecture/RAG知识检索架构.md)
|
||
- [architecture/RAG检索可观测性与审计.md](../architecture/RAG检索可观测性与审计.md)
|
||
|
||
相关 Issue：
|
||
|
||
- [ISS-017 L0 过滤收窄与 Fallback 加固](../issues/active/ISS-017-rag-l0-filter-fallback-hardening.md)（已失效：L0 下沉 py-rag，问题前提不复存在）
|
||
|
||
---
|
||
|
||
## Harness
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [harness/README.md](harness/README.md) | **从这里开始**：用一次诊断请求理解 Harness，不要求先掌握组件和状态 |
|
||
| [harness/Harness面试速查-一张图讲清设计.md](harness/Harness面试速查-一张图讲清设计.md) | **收尾速查**：一张架构图、一条请求主链、三个核心决策和常见面试追问 |
|
||
| [harness/案例-从一次支付超时诊断看Harness如何控制Agent.md](harness/案例-从一次支付超时诊断看Harness如何控制Agent.md) | **案例导读**：跟随一次真实支付超时 Run，看 Agent、Tool、Guard 和 Release 如何协作 |
|
||
| [harness/Harness设计演进-从多Agent编排到确定性控制边界.md](harness/Harness设计演进-从多Agent编排到确定性控制边界.md) | **设计演进**：从多 Agent、Gatekeeper 和 StateGraph 逐步收敛到 Single ReAct + Harness |
|
||
| [harness/Harness失败图谱-异常-停止-降级与终态.md](harness/Harness失败图谱-异常-停止-降级与终态.md) | **失败图谱**：用可继续性、安全进展和发布资格解释异常、停止、降级与终态 |
|
||
| [harness/components/README.md](harness/components/README.md) | **组件渐进式导读**：沿一次请求分四步理解运行控制、Agent 收敛、Tool 事实边界和验证发布 |
|
||
| [harness/CONTEXT.md](harness/CONTEXT.md) | Harness 统一术语、命名规则、状态维度与已知命名债务 |
|
||
| [harness/Harness生命周期与状态.md](harness/Harness生命周期与状态.md) | Run、Tool、Progress、Guard、Release、SSE 和持久化生命周期及状态映射 |
|
||
| [harness/Harness设计-非确定性Agent的确定性控制边界.md](harness/Harness设计-非确定性Agent的确定性控制边界.md) | Harness 根问题、设计不变量、方案取舍、关键决策、代价与真实问题反推 |
|
||
| [harness/Harness组件全景-职责-设计原因与边界.md](harness/Harness组件全景-职责-设计原因与边界.md) | 当前 Harness 10 个职责域、全部生产类型、设计原因、作用与边界 |
|
||
| [harness/Harness-Tool双视图-从原始结果到可验证证据.md](harness/Harness-Tool双视图-从原始结果到可验证证据.md) | canonical truth、Control View、Agent Observation 与 metadata audit 的数据边界 |
|
||
| [harness/Harness证据安全链-从引用真实到结论可发布.md](harness/Harness证据安全链-从引用真实到结论可发布.md) | EvidenceGuard、EvidenceRepair、SemanticGuard 和唯一 Release Policy |
|
||
| [harness/Harness信息增益停止-让无证据诊断正常收敛.md](harness/Harness信息增益停止-让无证据诊断正常收敛.md) | GAINED/NO_GAIN、重复检测、协议停止、ProgressSnapshot 与过程型 Fallback |
|
||
|
||
---
|
||
|
||
## 审计
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [audit/README.md](audit/README.md) | **从这里开始**：从“这份答案为什么可信”理解审计系统，不要求先掌握表和事件类型 |
|
||
| [audit/从一次诊断Run看审计系统如何记录决策.md](audit/从一次诊断Run看审计系统如何记录决策.md) | **真实 Run 案例**：从最终结果倒推 Run、Timeline、Agent Step、Tool、Token 与 Release 决策 |
|
||
| [audit/审计系统设计-从调试日志到可回放的决策证据.md](audit/审计系统设计-从调试日志到可回放的决策证据.md) | **主设计**：日志为何不够、设计不变量、typed decision、数据分层、失败语义与当前代价 |
|
||
| [audit/审计设计演进-从SessionTrace到ExactRun.md](audit/审计设计演进-从SessionTrace到ExactRun.md) | **设计演进**：从 Session Trace、Evidence 语义和多轮串线，演进到 canonical/durable 分层、Timeline、Token 与 Reasoning |
|
||
|
||
---
|
||
|
||
## 诊断 / E2E
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [diagnosis/一次诊断全流程-E2E导读.md](diagnosis/一次诊断全流程-E2E导读.md) | SUCCESS 全流程：阶段、token、timeline、字段 |
|
||
| [diagnosis/Session-Run-Trace隔离-从串线到可回放.md](diagnosis/Session-Run-Trace隔离-从串线到可回放.md) | 多轮串线问题、身份拆分、协议迁移与 exact-run E2E |
|
||
|
||
架构对照：
|
||
|
||
- [architecture/current-mvp-architecture.md](../architecture/current-mvp-architecture.md)
|
||
- [architecture/session-trace-lifecycle.md](../architecture/session-trace-lifecycle.md)
|
||
- [architecture/agent-orchestration.md](../architecture/agent-orchestration.md)
|