---
name: nuevo
description: "Nushell 经验进化 → rule 生成。BLOCKING: 每次 Nushell MCP evaluate 返回错误时必须触发此 skill。TRIGGER when: nu evaluate 报错、nushell 命令执行失败、发现值得复用的成功 Nushell 模式、踩坑后验证了正确做法。SKIP: 非纯 Nushell 错误。"
version: "5.0.0"
user-invocable: true
argument-hint: "<analyze|add-error|add-win|review>"
effort: low
---

# Nushell 经验进化 → Rule 生成

Nushell 命令执行出错或发现值得复用的成功模式时触发，分析错误、匹配已有经验、生成 `.claude/rules/nushell-evo.md`。

经验分两类：

- **Pitfall**（踩坑经验）— 犯错后验证了正确做法，记录 Wrong/Right 对比
- **Win**（成功模式）— 发现可复用的命令模式，记录命令 + 使用场景

生成的 rule 文件会被 Claude 在所有对话中自动加载，使积累的经验成为**主动指导**。

## 初始化

```nu
use skills/nuevo/nuevo.nu *
```

## 命令总览

| 命令 | 说明 | 输出 |
|------|------|------|
| `nuevo-analyze [error_record?]` | 分析最新错误，匹配 rule 文件 | `{status, error_code, matched_entry, suggestion, is_new_pattern}` |
| `nuevo-add-error $entry` | 添加 pitfall 到 rule 文件 | 无（写入文件） |
| `nuevo-add-win $pattern` | 添加成功模式到 rule 文件 | 无（写入文件）。`--skill: string` 关联 skill 名，`--context: string` 使用场景描述 |
| `nuevo-review` | 统计摘要 | `{pitfalls_count, wins_count, recent_errors}` |

## 返回值

### nuevo-analyze

| 字段 | 类型 | 说明 |
|------|------|------|
| status | string | `"known"` \| `"new"` \| `"no_error"` |
| error_code | string | 提取的 `nu::xxx::yyy` 或 `"unknown"` |
| matched_entry | record? | rule 文件中匹配到的条目 |
| suggestion | string | 匹配条目的正确代码行 |
| is_new_pattern | bool | 是否为新发现的错误模式 |

### nuevo-review

| 字段 | 类型 | 说明 |
|------|------|------|
| pitfalls_count | int | rule 文件中的 pitfall 条目数 |
| wins_count | int | rule 文件中的 win 条目数 |
| recent_errors | table | 最近 5 条 jsonl 错误 `[{timestamp, command, error_code}]` |

### nuevo-add-win

| 参数 | 类型 | 说明 |
|------|------|------|
| $pattern | string | 成功的命令或管道（必填，取前 60 字符作为标题） |
| --skill | string | 关联的 skill 名（如 `"browse"`、`"github"`） |
| --context | string | 使用场景或注意事项 |

## 工作流

### 错误进化

```text
Nushell MCP 执行出错
  │
  └─ nuevo-analyze
      ├─ status: "known" → 输出 suggestion，修正后继续
      ├─ status: "new" → 验证正确做法 → nuevo-add-error {entry}
      └─ status: "no_error" → 无操作
```

### 成功模式记录

```text
Nushell 命令执行成功，发现值得记录的模式
  │
  └─ nuevo-add-win "命令或管道" --context "使用场景" --skill "关联 skill"
      └─ 追加到 rule 文件 ## Success Patterns 段
```

### 回顾检查

```text
nuevo-review
  ├─ pitfalls_count: 已记录的 pitfall 数量
  ├─ wins_count: 已记录的成功模式数量
  └─ recent_errors: 最近 5 条错误 [{timestamp, command, error_code}]
```

## nuevo-add-error 入参格式

```nu
nuevo-add-error {
    title: "一句话标题"
    error_code: "nu::xxx::yyy"
    错误描述: "具体发生了什么"
    正确做法: "应该怎么做"
    错误示例: "错误命令"
    正确示例: "正确命令"
}
```

## nuevo-add-win 用法

```nu
# 基本用法
nuevo-add-win "open file.md | where type == 'h2'"

# 带 skill 和 context
nuevo-add-win "js-call '__tw.searchTweets' { q: $query, n: $count }" --skill "twitter" --context "安全替代 format pattern 的 SDK 调用方式"
```

## 生成的 Rule 文件

路径：`.claude/rules/nushell-evo.md`，`paths: []`（所有对话加载）。

叙事格式，每条错误一个 H3 标题 + 描述 + Wrong/Right 代码块：

````markdown
### Polars custom values 无法通过 MCP 序列化

MCP stdio 只能返回 NUON 可序列化数据，Polars DataFrame 属于 custom value，必须先转回 Nu 原生类型。

```nu
# Wrong
polars into-df | polars summary

# Right
polars into-df | polars collect | polars into-nu
```

````

## 注意事项

- **rule 文件是 Source of Truth** — Git 跟踪，人类可编辑，Claude 自动加载
- **Pitfall 和 Win 并重** — 踩坑经验防止重犯，成功模式促进复用，两者都是经验进化的一部分
- **nu_evo.jsonl 在项目根目录** — `--log-path` 默认 `"./nu_evo.jsonl"`
- **nuevo-analyze 不修改文件** — 返回分析结果，由 Agent 决策后续操作
- **rule 文件是追加式** — nuevo 只追加条目，不修改已有条目
- **`$history.N`** — 见下方 `## $history 用法` 小节

## $history 与数据处理

通用规则见 browse SKILL.md 的 `## $history 用法`。

### 错误记录可能缺失 status 列

nushell 经验日志的部分记录可能没有 `status` 列，`where status == 'error'` 会报 `column_not_found`：

```nu
# 赋值给变量后安全过滤
let evo = (open nu_evo.jsonl | from json)
$evo | where {|r| ($r | get -o status | default '') == 'error'}

# ❌ Wrong — 部分记录无 status 列
$evo | where status == 'error'
```

## 模块结构

```text
nuevo/
  nuevo.nu      — 导出命令（analyze/add-error/add-win/review）
  helpers.nu    — 内部抽象（rule 文件解析、JSONL 读写、条目追加）
  SKILL.md      — 本文档

.claude/rules/
  nushell-evo.md       — 生成的 rule 文件（Source of Truth）

```