内容
# 教练
**智能体自我评分.** 教练将智能体的执行轨迹转化为可查询的模型，描述智能体自身的行为，然后通过MCP将该模型返回给智能体，以便Claude Code可以加载自己的会话并展示自己的昂贵、幻觉或低效步骤。现有的智能体追踪是为工程师设计的，用于观察智能体；而教练的目标是闭环反馈到智能体本身，同时工程师监控该循环。
教练基于**OpenTelemetry（OTEL）追踪**设计，这使得教练与具体实施无关。
**第二个支柱**与优化工作并行：由于教练持有完整会话且数量众多，它旨在推断用户的**后验意图**，并跨会话聚合为每个智能体的**用户模型**（用户想要什么，如何表达，哪些未明确表达）——一种无法通过群体强化学习产生的个性化信号。参见 **[docs/agent-model.md](docs/agent-model.md)** 获取概念模型。
本README分为两个层级： **[当前功能](#当前功能)** 是您可以立即运行的已发布功能； **[未来规划](#未来规划)** 是路线图——明确标记为尚未发布——以便上述愿景不会被误解为当前版本的承诺。
## 当前功能
已发布功能包括三个部分：纯粹、分阶段的**管道**，React Flow **可视化**，和只读的**MCP查询服务器**。
- **管道** (`@coach/pipeline`) — 将跟踪/日志文件转换为标准化的、以ID为键的**执行图**，这是一个与关系数据库一一对应的模型。纯粹且与文件系统无关；在Node和浏览器中均可运行。
- **可视化** (`@coach/app`) — 用于预计算执行图的React Flow渲染器。
- **MCP查询服务器** (`@coach/mcp`) — 将图暴露为只读、可查询的关系表面，以便分析智能体可以驱动其自身的分析，适用于您的会话。
有关完整情况——包布局、管道阶段、数据流、MCP查询表面和部署——请参见 **[ARCHITECTURE.md](ARCHITECTURE.md)**。它是实时源代码；本README仅涵盖入门指南。
### 快速入门
需要 [pnpm](https://pnpm.io) （不要使用npm/yarn）和 Node ≥ 20.11。
```bash
pnpm install
pnpm check # 类型检查 + 校验 + 格式化 + 测试 + knip（与CI相同）
```
从跟踪目录生成执行图并检查每个阶段的输出：
```bash
pnpm e2e <路径或固定装置> # 输出/out/<名称>/01-classified.json … 06-enriched-graph.json
```
`<路径或固定装置>` 是相对于当前工作目录的路径，或 `packages/pipeline/fixtures/` 下的固定装置名称。
在浏览器中查看图表：
```bash
pnpm --filter @coach/app dev # 首页在 http://localhost:5173
```
通过 **"加载管道输出"** 按钮加载 `06-enriched-graph.json`（或任何预计算的图表），或直接从 URL 启动，参数为 `?data=<url>`；添加 `?focus=<nodeId>` 以显示并居中节点。
### 从Claude Code（MCP）使用
教练附带一个MCP服务器 (`@coach/mcp`)，将分析的执行图作为只读、可查询的表面暴露出来——这样智能体可以驱动其自身的分析，适用于您的会话。**目前，Claude Code是唯一支持的智能体。**
**1. 注册服务器.** 从任何位置运行——使用此仓库的绝对路径，以便Claude Code启动服务器时能够解析：
```bash
# 预加载数据集（OTEL跟踪/日志JSON目录，或原生.jsonl会话）
claude mcp add coach -- node --experimental-strip-types \
/ABSOLUTE/PATH/TO/coach/packages/mcp/bin/mcp.ts /ABSOLUTE/PATH/TO/traces
# … 或省略目录，在运行时通过load_dataset工具加载数据
claude mcp add coach -- node --experimental-strip-types \
/ABSOLUTE/PATH/TO/coach/packages/mcp/bin/mcp.ts
```
服务器通过stdio与MCP通信。可选的尾随目录预加载，以便数据集可以立即查询；如果没有，可以让智能体调用`load_dataset`并带上路径。开发过程中，您也可以直接使用`pnpm mcp [dataset-dir]`从仓库根目录运行。
**2. 验证和使用.** 在Claude Code会话中，运行 `/mcp` 以确认"coach"已连接，然后用自然语言提问——例如 _"加载./out中的跟踪并找到最昂贵的交互"_。服务器暴露：
| 工具 | 功能 |
| ----------------- | -------------------------------------------------------------- |
| `load_dataset` | 运行管道处理目录，使其图可查询 |
| `describe_schema` | 转储关系模式 + 示例分析SQL以扩展 |
| `query` | 运行只读SQL查询执行图表/视图 |
| `resolve` | 解析节点ID为其完整记录 |
| `subtree` | 遍历节点的包含树 |
| `causal_path` | 跟踪导致/来自节点的因果边缘 |
| `open_viz` | 在浏览器中打开React Flow图，聚焦于节点 |
要删除它：`claude mcp remove coach`.
还可以通过`pnpm build-db <traces-dir> [out.db]`为`duckdb` CLI提供独立的DuckDB快照，用于临时检查（MCP本身重新从源派生，而不是加载它）。
有关使用这些工具构建的分析示例——按恢复成本排名的失败工具调用，附带SQL——请参见 **[docs/case-study.md](docs/case-study.md)**。
### 开发
| 命令 | 功能 |
| ------------------------------------------ | ----------------------------------------------------- |
| `pnpm check` | 完整检查：类型检查、校验、格式化、测试、knip |
| `pnpm lint:fix` | 自动修复校验问题 |
| `pnpm format` | 使用Prettier自动格式化 |
| `pnpm --filter @coach/pipeline test:watch` | Vitest处于监视模式 |
| `pnpm e2e <fixture>` | 运行管道 + 确定性增强，写入`out/` |
| `pnpm mcp [dataset-dir]` | 通过stdio提供MCP分析工具 |
### 贡献
从`main`分支开新分支，发起PR，确保`pnpm check`通过。完整的流程、代码风格和模块约定位于 **[CONTRIBUTING.md](CONTRIBUTING.md)** 和 **[CLAUDE.md](CLAUDE.md)**。
#### 维护者一次性设置（需要GitHub远程仓库）
使CI成为必需检查，以便PR在红色时无法合并：
```bash
gh api -X PUT repos/{owner}/{repo}/branches/main/protection \
-F required_status_checks.strict=true \
-F 'required_status_checks.contexts[]=check' \
-F enforce_admins=true \
-F required_pull_request_reviews.required_approving_review_count=1 \
-F restrictions=
```
## 未来规划
本节中的所有内容都是 **路线图——尚未发布**。它陈述了设计意图，而不是当前行为。目前，教练针对的是**工程师**：您加载数据集并查询它。下面两个线程是关于最终为谁提供服务。
- **闭环反馈回到智能体.** 目标是让智能体对其自身的发现采取行动，而不仅仅是让工程师阅读它们——Claude Code加载其自身的会话并纠正其自身的昂贵、幻觉或低效步骤。如何“闭环”仍未决定，因此第一阶段故意针对工程师，直到我们了解哪些问题实际上是可解的。
- **跨会话的每个智能体用户模型（第二个支柱）。** 由于教练持有完整会话且数量众多，它旨在推断用户的**后验意图**，并将其汇总到每个智能体的**用户模型**中——用户想要什么，他们如何表达，哪些未明确表达，需要澄清的问题。这是一个单独的输出，带有单独的消费者（智能体，用于个性化）；它不会取代面向工程师的优化工作。概念模型及其诚实的警惕位于 **[docs/agent-model.md](docs/agent-model.md)**。
