dsh-trajectory-teacher

Readme

# dsh-trajectory-teacher

把 DeepSeek Harness (DSH) 里 AI Agent 的一次执行轨迹，自动转成一份可读的**复盘报告**。

- **输入**：DSH 的 Trajectory 事件流（Agent 每次运行自动记录）
- **处理**：提取关键事件 → 调 LLM 分析
- **输出**：markdown 复盘文档（决策点 / 踩的坑 / 可复用做法）

## 效果示例

对话里输入 `/trajectory-teacher`，几秒后得到一份结构化复盘：

```markdown
# Agent 执行复盘报告

> | 工作目录 | `/path/to/your-project` |
> | 回合数 | 11 | 工具调用 | 50 次 |

## 总结
会话围绕一个项目的下一步展开……

## 决策点
1. **面对「项目下一步」提问时，先读 README/CHANGELOG/git log 再回答** ✅ 走对
   - 为什么：用户提供的是过时交接文档，必须用仓库实际状态校正上下文

## 踩的坑
1. **沙箱环境 TLS 凭证缺失，导致无法实测后端**
   - 教训：遇到环境类故障要快速识别「沙箱限制」而非「服务故障」

## 可复用做法
1. **用「漏斗缺口」而不是「功能清单」定位项目下一步**
   - 适用场景：产品能跑、但增长停滞时
```

## 安装

```bash
dsh plugin add dsh-trajectory-teacher
```

安装后重启 DSH，插件自动挂载。

## 用法

在对话里跑完一轮任务后，输入：

```
/trajectory-teacher
```

插件会复盘**当前会话**的完整轨迹，返回一份 markdown 复盘报告。

### 可选配置

默认复用当前会话正在用的模型来生成复盘。若要指定，在 profile 的 `cordis.patch.yml` 里覆盖：

```yaml
- id: trajectory-teacher
  config:
    provider: deepseek-official
    model: deepseek-v4-flash
```

> 复盘分析已默认关掉 thinking（`reasoningEffort: 'off'`）——提取+总结不需要深度推理，更快更便宜、输出更稳定。

## How it works

```
session.events（内存事件流）
    ↓ extract   过滤噪音（token 级 chunk 等），提取关键事件并摘要化 + 脱敏
    ↓ analyze   调 LLM，产出结构化 JSON（决策点 / 坑 / 可复用做法）
    ↓ render    套模板生成 markdown
复盘报告
```

- **噪音过滤**：一次流式回复会产生几百个 token 级 chunk，全部丢弃，只留 `tool/call`、`assistant/message`、`turn/*`、`approval/*` 等关键事件。
- **脱敏**：轨迹里可能混入 API key 明文，报告输出前自动打码（`sk-***`）。
- **成本控制**：手动触发（不自动跑）、只喂关键事件摘要（有长度上限）、关 thinking、用便宜模型。

## 为什么是「手动命令」而非「自动跑」

复盘要烧 LLM token，所以不自动触发——用 `/trajectory-teacher` 命令，你想复盘时才跑。

## Project structure

```
trajectory-teacher/
├── index.ts            # apply(ctx) 插件入口，注册 /trajectory-teacher 命令
├── cordis.patch.yml    # bundle 的 patch 层（dsh plugin add 安装时用）
├── lib/
│   ├── parse.ts        # zstd 解压 + 事件流解析（历史轨迹文件）
│   ├── extract.ts      # 过滤噪音 + 提取关键事件 + 摘要 + 脱敏
│   ├── analyze.ts      # 调 LLM 产出结构化复盘
│   └── render.ts       # JSON → markdown
├── scripts/
│   ├── build.mjs       # esbuild 打包成 dist/index.js
│   └── link-deps.mjs   # 软链 DSH 的 @deepseek-ai 包（开发用）
└── tests/              # node:test 单测
```

## Development

本地调试（从源码挂载到 DSH）：

```bash
cd <deepseek-harness 源码根目录>
pnpm dsh web --patch <本仓库>/dev/cordis.patch.yml --port 0
```

运行测试与构建：

```bash
npm test        # node:test 单测
npm run build   # esbuild 打包成 dist/index.js
```

## License

[MIT](LICENSE)