# dsh-evolve 开发 Spec：轻量执行经验插件

> Status: proposed
> Version: 0.3
> Scope: 产品定位、行为边界、数据流、权限门禁和后续开发顺序

## 1. 项目定位

`dsh-evolve` 是一个旁挂在 DeepSeek Harness 上的轻量执行经验插件。

它观察 Agent 的任务执行轨迹，从失败、用户纠正、重复动作和成功路径中提炼经验；在后续相似任务中按需检索少量经验，帮助 Agent 少走弯路。它也可以观察已有 Skill 的实际使用效果，并在证据充分时提出 Skill 新版本候选。

项目不训练模型，不修改模型参数，不构建 Agentic RL 平台，也不接管 Agent Loop。

核心闭环：

```text
Session
  -> 轨迹分析
  -> 执行经验
  -> 任务匹配
  -> 临时建议/上下文注入
  -> 结果观察
  -> 经验升权、降权或淘汰
```

Skill 是独立对象：

```text
已有 Skill 被使用
  -> 观察成功、失败、纠正和效率
  -> 生成新版本候选
  -> Replay / Shadow / 用户确认
  -> 激活或回滚
```

## 2. 绝对边界

### 2.1 必须做到

- 默认后台运行，不能改变用户正常使用节奏。
- 只读观察 Session 和公开运行事件，不阻塞 Agent 主路径。
- 原始 Session、Prompt、源码、工具输出和凭据默认只保存在本地。
- 经验默认作为本地文档或结构化记录保存，不自动变成 Skill。
- 经验只在当前任务高度相关时临时注入；任务结束后不进入常驻上下文。
- 只有确实需要用户决定的动作才请求同意。
- 所有会影响未来行为的高影响变更都可查看、拒绝和回滚。
- 插件故障时暂停进化侧车，DSH Agent 继续正常工作。

### 2.2 明确不做

- 不进行 LoRA、Fine-tuning、在线 RL 或任何模型权重更新。
- 不自动构建训练数据集，不维护 reward model，不进行策略搜索。
- 不让 Agent 自主决定经验永久生效。
- 不把普通经验批量生成 Skill、Recipe 或 Runtime Policy。
- 不自动上传原始 Session 或用户行为数据。
- 不自动安装插件、执行社区代码、关闭 Sandbox、绕过 Approval 或获取凭据。

## 3. 用户体验原则：默认无感

### 3.1 静默工作范围

以下操作默认在后台完成，不弹窗、不打断当前任务：

- 监听和规范化事件；
- 任务 Episode 切分；
- 确定性经验挖掘；
- 经验去重、聚合和置信度计算；
- 本地经验文档写入；
- 相关性匹配和临时上下文草稿生成；
- 已确认经验的检索；
- Skill 使用结果记录；
- Replay、Shadow、隐私检查和本地审计；
- GitHub Commons 的缓存同步（不自动激活、不等待网络）。

### 3.2 允许请求用户同意的场景

只有以下情况可以向用户请求同意：

1. 将个人经验编译成可分享 Capsule 并准备贡献到公共 Commons；
2. 创建、修改、激活或停用 Skill；
3. 修改 Context、Tool 或 Runtime Policy；
4. 将稳定的用户工作方式蒸馏为 Skill；
5. 启用需要额外数据范围、网络范围或权限范围的能力；
6. 发现高影响建议且必须由用户选择是否采用。

普通经验记录、失败统计、局部效率分析和经验降权不得请求确认。

### 3.3 请求同意的交互要求

每次请求必须说明：

- 要做什么；
- 使用哪些数据；
- 为什么认为有价值；
- 可能影响哪些未来任务；
- 是否会联网或共享；
- 如何拒绝、撤销和回滚。

禁止使用模糊的“允许 AI 自我进化”授权。授权必须针对具体对象、具体变更和具体数据范围。

## 4. 核心对象边界

### 4.1 Experience

Experience 描述某类任务中的执行规律，不是可执行代码，也不是 Skill。

支持的主要类型：

- `correction`：原路径失败后，用户或 Agent 采用了替代路径；
- `successful-procedure`：一条曾经成功的任务执行路径；
- `failure-pattern`：重复错误、重复动作或无进展模式；
- `execution-comparison`：相似任务中两条路径的效果比较；
- `user-workflow-observation`：用户稳定的任务工作方式观察。

Experience 默认进入本地经验库，可被检索、引用、降权和淘汰，但不会直接改变 Agent 行为。

### 4.2 Skill

Skill 是用户已经拥有、明确创建或明确激活的能力。Skill 只能通过自身使用证据进化：

```text
Skill 使用
  -> 结果和效率记录
  -> 失败/纠正分析
  -> v+1 草稿
  -> 验证
  -> 用户确认
```

普通 Experience 只有在用户明确选择“蒸馏为 Skill”后才能生成 Skill Draft。

### 4.3 Mutation

Mutation 是待审批的变更提案，不是自动优化器。它必须有来源 Experience、影响范围、证据、风险等级和回滚方式。

## 5. 经验检索与临时注入

任务开始或任务执行中，插件可以根据任务上下文匹配经验，但遵循以下限制：

- 默认只返回 1–3 条经验；
- 只有高相关性经验才允许注入；
- 低置信度经验只能作为弱提示；
- 经验必须包含适用条件和来源摘要；
- 经验不得以不可见的永久 System Prompt 形式写入；
- 任务结束后清理本次注入状态；
- 注入后如果用户纠正增加或任务指标变差，经验自动降权；
- 不相关经验不进入上下文，也不影响 Agent。

推荐数据流：

```text
Task Context
  -> Experience Retriever
  -> relevance / confidence / risk filter
  -> bounded context summary
  -> optional injection
  -> outcome recorder
```

## 6. “更优路径”的证据

系统不把“成功过一次”直接等同于“更优”。经验可以记录以下轻量指标：

- `steps`：任务步数；
- `toolCalls`：工具调用次数；
- `failures`：失败次数；
- `corrections`：用户纠正次数；
- `retries`：重复尝试次数；
- `durationMs`：耗时（可选）；
- `outcome`：成功、失败、用户接受或用户修改。

当存在足够样本时，才允许形成比较结论：

```text
baseline A: success=60%, averageSteps=12, failures=4
alternative B: success=82%, averageSteps=7, failures=1
```

样本不足、任务上下文不兼容或指标冲突时，只能标记为“候选经验”，不能标记为“推荐路径”。不引入奖励模型或策略梯度。

## 7. 用户习惯观察与 Skill 蒸馏

后期可以观察用户如何使用 AI，但目标是改进用户工作方式，而不是建立用户画像。

允许观察：

- 用户反复补充的任务前置条件；
- 用户经常否定的输出类型；
- 用户稳定采用的任务步骤；
- 经常导致返工的交互模式；
- 用户在多个任务中重复使用的验收方式。

输出应是可见、可关闭的建议，例如：

> 你最近多次在修改后才补充测试要求，是否在代码任务开始时先生成验收标准？

蒸馏流程：

```text
稳定工作方式
  -> 本地聚合
  -> 展示案例和效果
  -> 用户确认范围与名称
  -> Skill Draft
  -> 用户编辑 / 测试 / 激活
```

默认不上传用户习惯，不自动生成永久 Skill，不将用户行为用于模型训练。

## 8. 风险门禁

| 动作 | 默认行为 | 用户同意 |
|---|---|---|
| 记录本地执行指标 | 静默 | 否 |
| 生成本地 Experience | 静默 | 否 |
| 检索并临时提供相关 Experience | 静默 | 否 |
| 经验降权、淘汰 | 静默 | 否 |
| Replay / Shadow | 后台 | 否 |
| 修改已有 Skill | 生成候选 | 是 |
| 从用户习惯蒸馏 Skill | 生成建议 | 是 |
| 修改 Context / Tool / Runtime Policy | 生成提案 | 是 |
| 贡献公共 Capsule | 生成预览 | 是 |
| 激活社区 Skill 或策略 | 隔离验证 | 是 |
| 修改 Sandbox、Approval、凭据或权限 | 永不自动 | 永不自动 |

## 9. 模块调整

现有实现需要按以下方向收敛：

1. `src/experience/` 保留为经验挖掘、规范化、聚合和存储层；
2. 新增 Experience Retrieval 层，负责匹配、排序和有界临时注入；
3. `src/mutation/planner.ts` 不再默认把普通 correction/procedure 生成 Skill；
4. `src/targets/skill/optimizer.ts` 作为已有 Skill 反馈进化的主入口；
5. 新增 User Workflow Observation 与显式 Skill Distillation 流程；
6. `failure-pattern` 默认生成诊断经验，不直接激活 Runtime Policy；
7. 前台 Runtime Plane 只保留轻量观察和已有、已批准的干预；
8. 所有挖掘、比较、隐私编译和同步继续放在 Background Evolution Plane；
9. 任何后台异常只暂停对应能力，不影响 DSH 主流程。

## 10. 验收标准

### 无感性

- 无高影响提案时，Agent 的输入、输出和工具轨迹与未安装插件一致；
- 经验挖掘不阻塞 Agent，不在每个 Session 中弹窗；
- 网络不可用时，任务仍可正常执行；
- 后台失败时，DSH 仍可继续使用。

### 经验质量

- 能从失败、纠正和成功路径生成 Experience；
- 能比较步骤、调用次数和失败次数；
- 不会因单次成功生成全局推荐；
- 不相关经验不会被注入；
- 注入经验导致结果变差时会降权。

### Skill 边界

- 普通 Experience 不自动创建或激活 Skill；
- 只有已有 Skill 的使用反馈可以生成 Skill 更新候选；
- 用户确认前 Skill 草稿不可生效；
- Skill 更新可回滚并保留来源证据；
- 用户工作方式蒸馏必须经过明确确认。

### 安全和隐私

- 原始 Session 不上传；
- 公共贡献必须经过预览、脱敏、Secret 扫描和用户确认；
- 社区内容不能自动进入 System Prompt 或自动执行；
- 用户可以关闭经验观察、删除本地经验和撤销已激活变更。

## 11. 开发顺序

### P0：边界和行为修正

- 固定默认无感和同意门禁；
- 调整 Experience → Skill 的默认映射；
- 更新配置、CLI 和文档中的“低风险自动生效”表述；
- 增加非干扰和无弹窗测试。

### P1：经验检索

- 实现 Experience Retriever；
- 实现相关性、置信度和风险过滤；
- 实现有界临时注入和结果记录；
- 增加错误注入后的自动降权。

### P2：路径比较

- 增加 Episode 执行指标；
- 增加 baseline / alternative 摘要；
- 增加样本门槛和比较报告；
- 不引入训练或奖励模型。

### P3：Skill 反馈进化

- 完善已有 Skill 的使用结果记录；
- 生成 v+1 草稿、Replay、Shadow 和回滚；
- 增加用户确认界面或 CLI 流程。

### P4：用户工作方式蒸馏

- 本地观察稳定工作模式；
- 生成可解释建议；
- 用户确认后生成 Skill Draft；
- 默认不共享、不自动激活。

### P5：公共经验 Commons

- 只贡献脱敏、声明式、可验证的 Experience Capsule；
- 公共经验下载后只进入本地候选状态；
- 不自动信任、不自动激活。

## 12. 成功指标

项目成功不以“自动修改了多少东西”为指标，而以以下指标衡量：

- 用户纠正率下降；
- 重复失败率下降；
- 相似任务的平均工具调用和步数下降；
- 经验注入后的负面影响率可控；
- 已有 Skill 的回归率下降；
- 用户主动确认并使用的蒸馏 Skill 数量；
- 后台运行期间的阻塞、弹窗和干扰次数接近零；
- 所有共享数据都经过用户确认和隐私门禁。

## 13. 最终定位

> `dsh-evolve` 是一个轻量、后台运行的 Agent 执行经验插件。它从 Session 中发现失败、纠正和高效路径，把它们整理成可检索经验，在相关任务中临时提供帮助；同时观察已有 Skill 的实际效果，并允许用户将稳定的工作方式蒸馏为 Skill。它不训练模型、不修改模型参数、不接管 Agent Loop，也不构建 Agentic RL 平台。