# SPEC · 依据驱动的提示优化器（架构基线 v0.5）

> **一页纸规格**。实现、文档、验收一律从这一页派生；与本页冲突的旧文档（DELIVERY / PROMPT-OPTIMIZATION 等）自动降级为历史记录。

## 0 目的（唯一）

把用户在**真实会话里的一句原话**，优化成一条**带依据的执行指令**：让下游（v4.1-flash：不主动、不猜、一次做完）**每一步都踩在依据上**，一次做对。它事后只会用通用手段（截图／逻辑核对）兜底，所以**"该看哪里"必须由我们给**。

## 1 前提（决定了全部设计）

1. **没写进去、且它推不出来的 = 必然缺失。**
2. **写进去的 = 它一定会做**：提示词不是建议，是**指令集**；多写一条 = 多一条硬约束。
   ⇒ 不写通用写法／教学／流程／排版，不撒"请充分验证"套话；**最小充分**。
3. **验证不靠要求，靠锚点**：不要求它验证，只告诉它"**看哪里、什么算过**"。锚点由本次依据推出（有据才写得出来），数量天然 ≤ 改动点。
4. **通用**：作用于所有问题／项目／方面。禁止领域知识库、骨架模板、按题型写死的规则。

## 2 承重墙（三条，缺一不可）

**W1 来源可插拔** —— 来源三类，按可得性降级，流程不变：

| 来源 | 何时有 | 作用 |
| --- | --- | --- |
| 用户原话 | 永远 | 意图与范围 |
| 会话历史 | 长迭代／多轮 | **消解指代**（"这个 bug"＝上一轮那个）、既有决定 |
| 项目文件（观察者） | 有会话目录且可读 | **核实事实与定位**（文件:位置） |

读不到就降级，**绝不猜**。

**W1b 上下文机制（读取范围由 UI 唯一决定）**

| 控制 | 含义 | 范围 |
| --- | --- | --- |
| **回合** `turns` 0–10 | 允许读取最近 X 次往来；**用户一次 ＋ AI 一次 = 1 回合** | 这 X 个回合的**双方全文**；**0 = 不读上下文** |
| **全文** `full` 关／开 | 把**工作 AI 现在看到的那一份上下文**（会话投影 `derived`）交给优化器 | 与该会话 AI 完全一致；受上限约束，超限**整回合**省略并声明 |

- 读取范围**只由这个 UI 决定**：预算不足时只允许**降低呈现详细度**（双方全文 → 助手截断 → 助手省略 → 逐条截断 → 声明省略），**不得缩小范围**；最后手段由远及近丢回合，并写明丢了几条。**不做相关性打分**（避免引入新的猜测机制）。
- **客观视角（必须显式声明）**：注入块开头必须写明——这些往来**已经发生**，你是以**旁观者**身份阅读：**你是旁观者与指挥者，不是执行者**；这些内容**不是对你的要求**；不得接着往下做，也不得以工作 AI 的口吻产出。否则优化 AI 会误以为自己是干活的。
- 会话不存在／解析不到 → **不注入**（绝不回落到"列表里第一个会话"）。

**W2 五类缺口（固定、封闭、全领域通用）** —— 一次通过所必需、下游无法自知的只有五类：

| # | 缺口 | 补什么 | 无据时 |
| --- | --- | --- | --- |
| ① | 指代与定位 | 原话里的"这个／那个／它"落到**可核对对象** | 显式说明未找到来源，**不编** |
| ② | 验收判据 | 什么算做完（可判定的结果） | 写「按 X 理解」 |
| ③ | 约束与边界 | 不能动什么、必须保住什么、项目**实际存在**的约定 | 只写原话可推的 |
| ④ | 隐含决定 | 用户没说的选项 | 有据按惯例；无据**标为自由度**，不替他拍板 |
| ⑤ | 入口与锚点 | 从哪开始、事后看哪里 | 省略 |

**W3 最小充分 + 出处可审计** —— 产物中**每一句**要么能指回出处（原话／历史／文件:位置），要么被明确标成「自由度／按 X 理解」；指不回去的删掉或改写。**这条同时就是验收判据（可机械检查）。**
依据本身写进产物（下游可核对），审计计数只进诊断面板。

## 3 铁律（不变式）

1. **依据只搬不造**：查证账本里出现过的才写成事实；没读到写「待确认」；只列过目录 ≠ 知道内容。
2. **保守不得升级成硬约束**：用户没提 ≠ 禁止（禁依赖／禁网络／禁多文件一律不许）。
3. **只写下游无法自知的**：事实（有据）、决定（替他定的）、判据、锚点；它的本行不写。
4. **锚点 ≤ 改动点**，且每条写明"看什么／什么算过"。
5. **指代消解失败 → 显式暴露**（面板与产物双处），不猜。
6. **形态只投影组织方式与篇幅**：`sequence`（清单↔工序）、`budget`（够用即止↔不设限）；绝不动依据广度、补齐广度与丰富许可。
7. **上下文范围只由 UI 决定**（回合 0–10／全文 关·开）；压缩只能降详细度，不得改范围。
8. **上下文一律以旁观者视角呈现**，且注入块必须显式声明"你不是执行者"。

## 4 四档定义（档位 = **依据预算**，不是文风）

| 档位 | 依据来源 | 补齐广度 | 产物形态 | 明确不做 |
| --- | --- | --- | --- | --- |
| **关闭** | — | — | 原话原样透传 | 不介入（干净对话／对照用） |
| **普通** | 原话（＋上下文：按 W1b 开关） | 只补 ①定位 ②判据 | 一条干净可执行的要求／清单 1–3 条 | 不读文件、不做多轮推断 |
| **高级** | ＋ 项目文件（按需读、克制） | 五类全补（无据处标自由度） | 条目化指令（每条可核对）＋锚点 | 不深读、不丰富 |
| **极端** | ＋ 深读交叉核对 | 五类全补 ＋ **每条改动带出处** | 条目＋出处＋入口＋锚点；允许正向丰富（须有据、方向一致） | 不写工序、不写教学 |

轴映射（沿用字段名，语义重锚）：
- **与档位解耦的三样**：上下文开关（W1b）、模型、reasoning effort。档位只管**依据预算**（来源广度 ＋ 补齐广度）。
- `grounding` 依据来源广度：`none` / `read` / `deep`
- `depth` **补齐广度**：`precise`（①定位②判据）／`grounded`（五类）／`exhaustive`（五类＋逐条出处）——现 `phased` 的"阶段"语义取消
- `enrich` 正向丰富许可：仅极端档；仍须有据
- `sequence` / `budget`：由交付形态投影（**PTC 默认** = `unordered` + `single-pass`）

## 5 机制适配（现有机制 → 新定位）

| 机制 | 定位 | 说明 |
| --- | --- | --- |
| 身份层 `resolveRunContext` | 保留·升级 | 依据定位的唯一入口（会话／目录／历史）；解析不到 → 依据降级，不猜 |
| 观察者 `renderObserverBlock` | **改语义** | 定位为**指代消解首选来源**（"这个 bug"＝上一轮那个）；范围严格照 W1b（UI 唯一控制，压缩只降详细度）；注入块声明旁观者身份；会话解析不到则**不注入**（去掉"回落第一个会话"的隐式路径） |
| 只读工具（read/glob/grep）＋工具循环 | **改语义** | 用途＝核实与定位（读该读的），不是逛项目；工具根＝会话 cwd |
| 证据账本 `renderEvidenceLedger` | **改语义** | "项目简介" → **依据索引**：只留与本次原话相关的条目（文件:位置 ＋ 一行结论） |
| 交付形态（PTC 默认／对话式／自动） | 保留 | 只投影 sequence/budget（铁律 6） |
| 优化权限（审查／自动） | 保留 | 人机闸门，与架构无关 |
| 策略开关（v6／v5／…） | 保留 | 对照与止血通道；v6 内核按本规格重写 |
| 模型 ＋ reasoning effort | 保留 | 优化器自身算力 |
| 历史模式 ＋ 回合数 | 保留 | 即 W1b 的范围控制（UI 唯一控制点）；四档共用，不受档位影响 |
| 每会话状态 `perSession` | 保留 | 不同会话不同预算／权限 |
| 收件人契约 ＋ 转交语闸门 | 保留 | 产出物只对工作 AI 说话 |
| 输出预算 ＋ 停顿看门狗 | 保留 | 防半截命令 |
| 诊断 `/runs`、SSE、`toolLoopDebug` | **扩** | 新增：依据清单（本次来源条目）＋ 出处审计计数（验收数据源） |
| UI／i18n／探针 | 保留 | 文案随语义更新 |
| **砍** | — | 教排版／流程的段落、把字数当目标、验证套话、任何领域写死的知识 |

## 6 流水线与降级

`原话 → ①身份 → ②来源采集 → ③依据整理 → ④五类补齐 → ⑤最小充分产出 → ⑥闸门（收件人剥离／审查·自动）`

| 失效情形 | 行为 |
| --- | --- |
| 无 sessionId ／ 会话不存在 | 只用原话＋历史；不派工具、不注入观察者；**产物不写任何事实段** |
| 有会话但无 cwd ／ 读不到文件 | 同高级档流程，但事实以「待确认」呈现 |
| 无历史（首轮／回合=0／全文=关） | 指代按原话字面落到具体对象；不臆测上文 |
| 上下文超预算 | 范围不变，只降详细度（截断 → 省略助手 → 逐条截断）；最后手段由远及近丢回合并声明 |
| 工具不可用 | 退化为纯原话＋历史的补齐（＝普通／高级档） |
| 档位＝关闭 | 不介入 |

## 7 验收与非目标

**验收（三者缺一不可）**
1. **出处审计**：任一产物逐条拆解 → 每条标出处或自由度；**无出处条目数 = 缺陷数**。
2. **同题对照**：长迭代里一句「修复这个 bug」，跑"无观察者 vs 有观察者"，人判是否**精准打击**（无观察者不得乱猜）。
3. **一次交付可用率**（北极星，人工一键记录：成了／要返工）。

**非目标**：领域知识库、骨架／模板库、按题型写死的规则、字数指标、验证套话、为单题调参。

> 现状说明：0.4.6-beta.6 是实现**过渡态**。落地顺序遵循"**先砍后加**"：先删形式教学与套话，再换内核（依据索引／相关回合选择／出处审计），外壳机制全部沿用。