---
name: systematic-optimization
description: |
  系统化优化流程：发现问题→量化→根因→机制方案→业界调研→归纳→实施→验证实装→度量闭环。核心原则：规则存在≠被执行，机制优先于建议；拒绝临时补丁，追求大局观；优化必须可度量。
  用于用户要求"优化""改进""复盘""为什么反复出问题""效率低/token 浪费/防御过度"等系统性改进场景，或接手反复失败的任务时。
  不用于单点小修复（用 minimal-implementation）；不用于只读审查不出方案的场景。
---

# 系统化优化流程（Systematic Optimization）

> 来源：2026-08-24 对"严格好论文榜"长任务会话的完整优化实践（9 个悬挂 supervisor、44 分钟无看门狗 Deep diving、214 万 token 输入、24 次上下文压缩）。这次实践暴露的核心教训：**规则存在 ≠ 被执行**，优化必须落到"无法绕过的机制"而不是再写一条建议。

## 触发边界

- 用户说"优化 / 改进 / 复盘 / 为什么反复出问题 / 效率是不是低 / 有没有浪费 token / 防御是不是过度"；
- 接手一个反复失败或长期停滞的任务；
- 审查发现同一类问题反复出现（反模式重演）。

## 流程（八步）

### 第 0 步：证据先行，量化基线

**没有数字的"问题"是感觉。** 先量化再下结论：

- 从日志/转录/数据提取：事件数、工具调用分布、等待次数、轮询次数、时间线 gap、token 统计（输入/输出比）、上下文压缩次数、行数/文件变化；
- 用时间戳重建时间线，找"长时间无产出"的段（如 44 分钟 WAIT→GET 循环）；
- 建立优化前的基线数字，供第 7 步对比。

### 第 1 步：发现所有问题（全量列举）

- 不修修补补，先把问题**全部**列出来（挂起、轮询、纠偏、方向丢失、token 浪费、效率低……）；
- 每个问题标注证据（哪个事件/哪段日志/哪个数字）；
- 区分表象与真问题（"9 个悬挂 supervisor"是表象，真问题是"收尾无机制"）。

### 第 2 步：寻找根因（分类定位）

根因分三类，处理方式不同：

| 根因类型 | 特征 | 对策 |
|---|---|---|
| 缺规则 | 规则库没有该条目 | 补规则 |
| 有规则没执行 | 规则存在但执行者/管理者没遵守 | 加执行点自查（skill 自查清单） |
| **执行无法强制** | 规则靠"记得遵守"，没有拦截机制 | **改平台/工具层做强制约束（唯一真正根治）** |

典型：本次根因是第三类——"及时关闭 supervisor"规则早已存在，但收尾依赖人工记忆，没有 broker 层自动回收。

### 第 3 步：寻找解决方案（机制优先，拒绝临时）

每提出一个方案先问：**这是临时方案还是机制方案？**

- 临时方案：手动清理 9 个悬挂 supervisor、这次注意点、下次记得……（会复发）
- 机制方案：broker 自动回收闲置 supervisor、interrupt 预算上限、参数必填门禁……（无法绕过）

**追求大局观**：不从单个问题出发打补丁，而是看"这一类问题"缺什么机制。临时方案只用于止血，必须伴随机制方案。

### 第 4 步：网上找相同问题解决方案

- 先定义问题域，再搜索（关键词来自根因，如 "agent orchestration supervisor lifecycle zombie"）；
- 用已有通道：内置 web_search 不可用时，走 CLI worker 搜索（`queue_cli_request` + `request_result`，见 agent-switchboard-ops examples）；
- 只回收结构化结果 + 来源 URL，不灌脏网页；
- 业界对照表：机制名 | 框架 | 实现方式 | URL。

### 第 5 步：归纳成为最终方案（取舍）

- 业界方案对照本系统约束，标注哪些能移植、哪些不能、怎么改造（如 OpenAI Agents SDK 的 max_turns → 本系统的 interrupt 预算；Temporal 终态状态机 → 惰性 zombie 检测）；
- 最终方案必须包含：机制落点（哪个文件/哪个工具）、行为变化（什么条件下拒绝/回收）、可验证的验收点（返回什么新字段）；
- 决定哪些优化值得做（成本/收益），不做过度防御。

**约束分层（本步必做，逐方案标注）**：每个方案必须标注它属于哪个约束层，只有"平台/代码层"才算机制化：

| 约束层 | 例子 | 可靠性 | 判定 |
|---|---|---|---|
| 平台/代码层 | broker 参数门禁、自动回收、预算上限 | ✅ 强制（无法绕过） | 真机制 |
| 执行点自查 | skill 自查清单、回合结束检查 | ⚠️ 依赖"记得查" | 半机制，需观察 |
| 文档/规则层 | skill 里的"应当""禁止"条款 | ❌ **经常不执行** | 弱约束，不算方案 |

**文档层不执行是经验事实，不是假设**：2026-08-24 实证——WAIT→GET 禁令写入 skill 并被会话加载后，下一次调用依然夹用；"及时关闭 supervisor"规则存在数月，9 个 supervisor 仍悬挂。因此：

- 写入文档的规则 = 弱约束，必须显式标注"未强制，待观察"；
- 如果该规则对应的问题**反复出现**，就必须升级到平台/代码层（第 3 类根因），不能停留在文档层；
- 方案清单里，文档层条目不得自称"已解决"，只能算"已记录"。

### 第 6 步：实施

- 按 minimal-implementation：最小正确改动 + 可复核验证证据；
- 新机制必须配测试（防回归）；
- 全部门禁（validate_repo、quality_report、回归测试、diff check）。

### 第 7 步：验证实装（三件套，缺一不可）

**文件改了 ≠ 已生效。** 检查运行时链路：

1. **文件 hash**：改动确实写盘；
2. **运行时加载**：skill 是否同步到加载目录（`~/.dsh/skills`）、进程是否重启加载新代码（Python 进程 import 旧代码不会自动更新）；
3. **行为观察**：实际调用一次，确认新行为出现（如新字段 `zombie_reclaimed`、新错误 `interrupt_budget_exceeded`）。

### 第 8 步：度量闭环（对比基线）

- 用第 0 步的同一指标重新量化：token 消耗、调用次数、空转时长、supervisor 悬挂数；
- 确认改进真实发生（不是自我感觉）；
- 若未改进，回到第 2 步重新找根因。

## 核心原则

1. **规则存在 ≠ 被执行**：能落到机制（参数门禁、自动回收、预算上限）就不写建议；
2. **临时方案必须伴随机制方案**：否则问题复发；
3. **量化优先**：每个问题带数字，每个优化带前后对比；
4. **验证实装三件套**：hash → 加载 → 行为，缺一不可；
5. **不重复造轮子**：先找业界方案再设计；
6. **文档层不执行**：文档/规则层条目必须标注"未强制，待观察"；同一问题反复出现即升级到平台/代码层，不停留在文档层。

## 输出契约

优化完成报告：

```text
基线（第 0 步数字）
问题清单（全量，带证据）
根因分类（缺规则/没执行/无法强制）
方案（临时 + 机制，机制落点与行为变化；每个方案标注约束层：平台/代码 | 执行点 | 文档）
业界对照（机制 | 框架 | URL）
实施（文件/测试/门禁）
实装验证（hash / 加载 / 行为观察）
度量对比（优化前 vs 优化后）
文档层条目单独列出并标注"未强制，待观察"（不得自称已解决）
```

## 与相邻 skill 的分工

- `minimal-implementation`：单点小改的执行纪律；本 skill 管"系统性优化"全流程；
- `execution-discipline`：执行层不空转；本 skill 管"优化方法论"；
- `decision-gates`：决策正确性；本 skill 第 5 步的取舍可叠加使用。

相关示例见 `examples/`。