300 lines
13 KiB
Markdown
300 lines
13 KiB
Markdown
# SPEC: Markdown-First 物理落盘与来源分级架构
|
||
|
||
> **版本**: v1.0
|
||
> **前置依赖**:
|
||
> - [SPEC_deepview_metadata_scoping_v3.md](./SPEC_deepview_metadata_scoping_v3.md) (Prosumer-First 沙箱隔离)
|
||
> - [SPEC_tri_domain_knowledge_architecture.md](./SPEC_tri_domain_knowledge_architecture.md) (三元知识域)
|
||
> - [DESIGN_PHILOSOPHY_AI_NATIVE.md](./DESIGN_PHILOSOPHY_AI_NATIVE.md) (AI-Native 产品心法)
|
||
> **状态**: 草案 (Proposal)
|
||
|
||
---
|
||
|
||
## 1. 问题陈述
|
||
|
||
当前管线中存在三个结构性隐患，它们共享同一根源——**AI 产出物与原始素材在文件系统中无法区分**。
|
||
|
||
### 1.1 Ghost Response 问题
|
||
|
||
Hermes Agent 在执行"分析素材并生成报告"类任务时，天然地会通过 `write_file` 工具将分析结果写入物理文件，而 `final_response` 仅返回"操作完成"的告知性消息。如果管线代码从 `final_response` 取值，拿到的是一段无意义的摘要而非真正的分析内容。
|
||
|
||
这不是 Agent 的 bug——这是 Agent 作为**自主工作者**的正确行为。人类分析师也不会口述 2000 字报告给你，他会"写完放这里，告诉你一声"。
|
||
|
||
| 管线 | 当前取值方式 | 风险 |
|
||
|------|-------------|------|
|
||
| 录音笔记 Stage 1 | `result.get("final_response")` | 碰巧可靠（Agent 恰好未写文件），但不稳定 |
|
||
| 客户档案 Stage 1 | `result.get("final_response")` | **已验证失效** — Agent 将内容写入 `profile.md`，response 仅 401 字符 |
|
||
|
||
### 1.2 幻觉复利效应
|
||
|
||
当前 `profile.md` 既是 Agent 的**输入素材**（读取既往档案），又是 Agent 的**输出目标**（生成新档案后覆盖写入）。文件系统中没有任何标记区分：
|
||
|
||
- `asr.md`（L0 原始转写，可信度最高）
|
||
- `profile.md`（L2 AI 聚合产出，可能包含错误推断）
|
||
|
||
当 Agent 下次执行时，它 `read_file("profile.md")`——无法判断这是人类录入的事实，还是上一轮 AI 的推测。如果上一次的 profile.md 含有错误推断（如"客户属于价格不敏感型"），Agent 会将其当作已有事实继续叠加推理。
|
||
|
||
**错误被放大而非纠正——这是幻觉的复利。**
|
||
|
||
### 1.3 Token 消耗悖论
|
||
|
||
一位客户积累 50 次面诊后：
|
||
- **暴力拼接所有 asr.md**（每条 1-3 万字）→ 100 万字 → 上下文直接爆炸
|
||
- **只读 report.md 摘要**（每条 3000 字）→ 15 万字 → 可控
|
||
|
||
但前提是：**Agent 必须知道 report.md 是 AI 生成的一阶摘要（有损），asr.md 才是无损证据。当需要考据时，应回溯 asr.md 原文，而非引用 report.md 中的话当作原声。**
|
||
|
||
可靠的中间产出物反而减少 Token 消耗；不可靠的中间产出物则制造幻觉。
|
||
|
||
---
|
||
|
||
## 2. 核心原则：Markdown-First 物理落盘
|
||
|
||
### 2.1 总则
|
||
|
||
> **管线各阶段之间的接口契约，必须是物理文件，不是内存态变量。**
|
||
|
||
| 接口方式 | 韧性 | 可审计性 | Agent 兼容性 |
|
||
|----------|------|---------|-------------|
|
||
| `final_response`（内存态） | ❌ 进程崩溃即丢 | ❌ 需翻 session 日志 | ❌ 与 Agent 的 `write_file` 行为冲突 |
|
||
| 物理 `.md` 文件 | ✅ 落盘即不丢 | ✅ `cat` 即可审 | ✅ 顺应 Agent 自然行为 |
|
||
|
||
### 2.2 两段式管线的物理接口
|
||
|
||
```
|
||
Stage 0 (ASR/上传) Stage 1 (Hermes Agent) Stage 2 (Qwen JSON)
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
asr.md ──read───► Agent ──write──► report_draft.md ──read──► LLM ──► DB JSON
|
||
(L0 原始) (L1 AI 产出)
|
||
```
|
||
|
||
- **Stage 0 → Stage 1**：Agent 通过 `read_file` 自主读取 `asr.md`（及其他素材）
|
||
- **Stage 1 → Stage 2**：管线代码从 Agent 写入的物理文件读取内容，传入 Stage 2
|
||
- **Stage 2 → DB**：JSON 写入数据库（已实现，无变更）
|
||
|
||
### 2.3 Agent 指令约定
|
||
|
||
Agent 的 user_message 必须明确指定**输出目标路径**，让 Agent 将分析结果写入该路径。管线代码执行完 Agent 后，从该路径读取内容。
|
||
|
||
```python
|
||
# ✅ 正确：明确输出路径，Agent 写入后管线读取
|
||
result = agent.run_conversation(
|
||
user_message=f"分析 {historyDir}/ 下的素材，将全景档案写入 {outputPath}",
|
||
system_message=systemPrompt,
|
||
)
|
||
with open(outputPath, "r") as f:
|
||
mdReport = f.read()
|
||
|
||
# ❌ 错误：依赖 final_response（Ghost Response 风险）
|
||
mdReport = result.get("final_response", "")
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 来源分级标记 (Provenance Levels)
|
||
|
||
### 3.1 三级分类
|
||
|
||
| 级别 | 标识 | 含义 | 可信度 | 文件命名约定 | 示例 |
|
||
|------|------|------|--------|-------------|------|
|
||
| **L0** | `source: human` | 物理世界直接采集的原始素材 | 最高——可回溯到原声/原件 | `asr.md`, `asr_raw.m4a`, 用户上传照片 | 录音转写文本（ASR 原始输出） |
|
||
| **L1** | `source: ai-single` | AI 基于**单个** L0 素材生成的一阶分析 | 高——有损摘要，但来源明确 | `report_draft.md` | 单条录音的面诊 X 光片报告 |
|
||
| **L2** | `source: ai-aggregate` | AI 基于**多个** L0/L1 素材聚合生成的产物 | 中——叠加推理，幻觉风险最大 | `profile.md` | 客户全景档案（跨录音合成） |
|
||
|
||
### 3.2 文件头元数据标注
|
||
|
||
所有 AI 生成的 `.md` 文件，必须在文件头以 HTML 注释形式嵌入来源元数据：
|
||
|
||
```markdown
|
||
<!-- provenance: ai-single | level: L1 | generated_at: 2026-04-12T19:42:30+08:00 | model: gemini-pro-vertex | sources: [rep_bc439351/asr.md] -->
|
||
# 面诊沟通X光片深度分析报告
|
||
...
|
||
```
|
||
|
||
```markdown
|
||
<!-- provenance: ai-aggregate | level: L2 | generated_at: 2026-04-12T19:54:39+08:00 | model: gemini-pro-vertex | sources: [rep_bc439351/asr.md, rep_abc123/asr.md] -->
|
||
# 👤 客户全景档案：测女士
|
||
...
|
||
```
|
||
|
||
L0 文件（asr.md）**不需要**标注——没有标注即为 L0。这是"无标记即原始"的默认原则。
|
||
|
||
### 3.3 Agent 行为约束（注入 SKILL.md）
|
||
|
||
在 Agent 的 SKILL 指令中，追加来源分级感知规则：
|
||
|
||
```markdown
|
||
## 📋 来源分级阅读规则
|
||
|
||
1. **L0 文件**（asr.md, asr_raw.m4a）是不可变的原始证据，所有核心论断必须以 L0 文件为最终考据依据。
|
||
2. **L1 文件**（report_draft.md）是单次录音的 AI 摘要，可用于快速浏览历史，但引用原声时必须回溯 L0 验证。
|
||
3. **L2 文件**（profile.md）是跨录音的 AI 聚合分析，优先级最低。如果 L2 中的结论与 L0 原文冲突，以 L0 为准。
|
||
4. **引用格式**：所有洞察必须标注来源文件名和大致行号，并注明来源级别。
|
||
- ✅ `(来源: rep_bc439351/asr.md L0, 125 行)`
|
||
- ❌ `(来源: profile.md)` ← 禁止引用 L2 作为唯一证据
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 文件系统约定
|
||
|
||
### 4.1 录音笔记管线（单条录音 → 报告）
|
||
|
||
**当前**:
|
||
```
|
||
inbox/{asrId}/
|
||
├── asr.md ← L0 原始转写
|
||
└── asr_raw.m4a ← L0 原始音频
|
||
```
|
||
|
||
**改造后**（归档前）:
|
||
```
|
||
inbox/{asrId}/
|
||
├── asr.md ← L0 原始转写
|
||
├── asr_raw.m4a ← L0 原始音频
|
||
└── report_draft.md ← L1 AI 单次分析（Agent 写入，管线读取后传入 Stage 2）
|
||
```
|
||
|
||
**改造后**（归档后）:
|
||
```
|
||
clients/{clientId}/history/{reportId}/
|
||
├── asr.md ← L0 不可变
|
||
├── asr_raw.m4a ← L0 不可变
|
||
└── report_draft.md ← L1 随迁（审计留痕）
|
||
```
|
||
|
||
### 4.2 客户档案管线（多条录音 → 全景档案）
|
||
|
||
```
|
||
clients/{clientId}/
|
||
├── profile.md ← L2 AI 聚合产出（每次生成时覆盖）
|
||
└── history/
|
||
├── {reportId_A}/
|
||
│ ├── asr.md ← L0
|
||
│ ├── asr_raw.m4a ← L0
|
||
│ └── report_draft.md ← L1
|
||
├── {reportId_B}/
|
||
│ ├── asr.md ← L0
|
||
│ └── report_draft.md ← L1
|
||
└── ...
|
||
```
|
||
|
||
### 4.3 不可变性规则
|
||
|
||
| 文件 | 可读 | 可写/覆盖 | 可删除 |
|
||
|------|------|----------|--------|
|
||
| `asr.md` (L0) | ✅ Agent + 管线 | ❌ 上传后不可变 | ❌ |
|
||
| `asr_raw.m4a` (L0) | ✅ 审计用 | ❌ | ❌ |
|
||
| `report_draft.md` (L1) | ✅ Agent + 管线 | ✅ 重新生成时覆盖 | ❌ |
|
||
| `profile.md` (L2) | ✅ Agent + 管线 | ✅ 每次归档后重新生成 | ❌ |
|
||
|
||
---
|
||
|
||
## 5. 代码改造清单
|
||
|
||
### 5.1 录音笔记管线 (`_handleReportGenerate`)
|
||
|
||
| 步骤 | 现状 | 改造 |
|
||
|------|------|------|
|
||
| Agent user_message | 未指定输出路径 | 新增 `report_draft.md` 输出路径指令 |
|
||
| Stage 1 取值 | `result.get("final_response")` | 优先读取 `inbox/{asrId}/report_draft.md`，兜底 `final_response` |
|
||
| report_draft.md 写入 | 无 | Agent 自行写入（prompt 引导），或管线兜底写入 |
|
||
| 文件头标注 | 无 | Agent prompt 中要求写入 `<!-- provenance -->` 标注 |
|
||
|
||
### 5.2 客户档案管线 (`_generateClientProfile`)
|
||
|
||
| 步骤 | 现状 | 改造 |
|
||
|------|------|------|
|
||
| Agent user_message | 含 `profileMdPath` 路径 | 保持（Agent 已自然写入此路径） |
|
||
| Stage 1 取值 | ~~`result.get("final_response")`~~ **已修复** → 读取 `profile.md` | ✅ 已完成 |
|
||
| 文件头标注 | 无 | 需追加 `<!-- provenance: ai-aggregate ... -->` |
|
||
|
||
### 5.3 SKILL.md 追加
|
||
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `skills/deepview_assistant/SKILL.md` | 追加"来源分级阅读规则"章节 |
|
||
| `skills/deepview_profile/PROMPT_stage1.md` | 要求输出文件头带 `<!-- provenance -->` 标注 |
|
||
|
||
---
|
||
|
||
## 6. Agent 信息获取策略（规模化场景）
|
||
|
||
当客户积累大量面诊录音后，Agent 应自主规划信息获取策略，而非被管线代码预先读取所有文件：
|
||
|
||
### 6.1 分层阅读策略
|
||
|
||
```
|
||
Agent 收到任务: "生成 p_b1232417 的全景档案"
|
||
│
|
||
├─ Step 1: search_files → 扫描 history/ 目录结构，确认有 N 条录音
|
||
│
|
||
├─ Step 2: read_file(profile.md) → 读取 L2 既有档案（如果存在）
|
||
│ └── Agent 识别 provenance: ai-aggregate → 知道这是上一轮 AI 自己的产出，仅供参考
|
||
│
|
||
├─ Step 3: 逐条读取 report_draft.md (L1) → 快速掌握每条录音的核心结论
|
||
│ └── Token 消耗: N × ~3000 字（远小于 N × ~20000 字的 asr.md）
|
||
│
|
||
├─ Step 4 (按需): 对关键论断回溯 asr.md (L0) 验证
|
||
│ └── 仅在需要考据原声时才读取完整 ASR，避免全量加载
|
||
│
|
||
└─ Step 5: write_file(profile.md) → 生成新的 L2 档案，覆盖旧版
|
||
```
|
||
|
||
### 6.2 Token 经济模型
|
||
|
||
| 录音数量 | 暴力全读 (asr.md) | 分层阅读 (report_draft.md + 按需 asr.md) | 节省比 |
|
||
|----------|-------------------|----------------------------------------|--------|
|
||
| 5 条 | ~10 万字 | ~1.5 万字 + 按需 ~2 万字 | ~65% |
|
||
| 20 条 | ~40 万字 | ~6 万字 + 按需 ~4 万字 | ~75% |
|
||
| 50 条 | ~100 万字 (上下文爆炸) | ~15 万字 + 按需 ~6 万字 | **可行 vs 不可行** |
|
||
|
||
---
|
||
|
||
## 7. 与已有 SPEC 的关系
|
||
|
||
```mermaid
|
||
graph TB
|
||
A["DESIGN_PHILOSOPHY_AI_NATIVE<br/>先有价值，后有治理"] --> B["SPEC_metadata_scoping_v3<br/>Prosumer-First 沙箱隔离"]
|
||
B --> C["SPEC_tri_domain_knowledge<br/>三元知识域"]
|
||
B --> D["SPEC_md_first_persistence<br/>📄 本规范"]
|
||
D --> E["来源分级标记"]
|
||
D --> F["管线物理接口"]
|
||
D --> G["Agent 分层阅读策略"]
|
||
```
|
||
|
||
- **V3 SPEC** 定义了"数据在哪"（`users/{userId}/` 沙箱）
|
||
- **三元域 SPEC** 定义了"知识从哪来"（平台/机构/个人三级注入）
|
||
- **本 SPEC** 定义了"文件怎么流"（物理落盘、来源标记、Agent 感知证据层级）
|
||
|
||
三者合力构成了完整的数据治理体系：**沙箱隔离 × 知识分域 × 来源追溯**。
|
||
|
||
---
|
||
|
||
## 8. 验证计划
|
||
|
||
### 8.1 自动化测试
|
||
|
||
```bash
|
||
# 1. 录音笔记管线：验证 report_draft.md 是否被生成
|
||
test -f inbox/{asrId}/report_draft.md && echo "✅ L1 文件存在"
|
||
head -1 inbox/{asrId}/report_draft.md | grep "provenance" && echo "✅ 来源标记存在"
|
||
|
||
# 2. 客户档案管线：验证 profile.md 来源标记
|
||
head -1 clients/{clientId}/profile.md | grep "ai-aggregate" && echo "✅ L2 标记正确"
|
||
|
||
# 3. 归档后文件完整性
|
||
ls clients/{clientId}/history/{reportId}/ | grep -c ".md" # 应 >= 2 (asr.md + report_draft.md)
|
||
```
|
||
|
||
### 8.2 人工审计
|
||
|
||
- 对比 `profile.md` 中的引述与 `asr.md` 原文，确认无二次幻觉放大
|
||
- 检查 Agent session 日志，确认分层阅读行为（先读 L1 摘要，按需回溯 L0）
|
||
|
||
---
|
||
|
||
> *本规范定义了深维面诊助理的 Markdown-First 物理落盘与来源分级架构。*
|
||
> *核心信念：物理文件是管线各阶段之间的唯一接口契约。AI 产出必须标注来源级别，原始素材不可变。*
|
||
> *审阅确认后，将指导两条管线的统一改造。*
|