# pi-auto-name

[English](README.md) | 简体中文

本插件用于在会话结束时，根据会话的实际执行内容为会话生成名称。

术语解释：
- 会话（Session）：在 Pi 中与模型进行的一轮持续对话任务记录。
- 桩记录（Custom Entry）：保存在会话数据文件末尾的标记数据，用于记录该名称由本插件生成。

```bash
pi install npm:@light-cat/pi-auto-name
```

## 为什么在会话结束时命名

- 会话开始时仅有首条消息，无法反映后续数小时的实际工作内容。
- 随对话进行频繁重命名会导致会话列表反复跳动，并产生频繁的文件写入。
- 会话结束时完整内容已写入磁盘，模型读取一次即可生成准确概括会话实际工作的名称。
- 用户通过 `/name` 手动指定的名称绝不会被覆盖。

## 触发时机

| 操作 | 执行逻辑 |
| --- | --- |
| `/new`、`/resume`、`/fork` | 为刚刚离开的会话命名。恢复执行的会话因内容增长，离开时会再次命名。 |
| 启动 Pi | 检查当前工作目录下最近 24 小时内结束且未命名的会话并补齐名称，最多处理 3 个。覆盖进程被强杀等异常退出的情况。 |
| `/autoname [偏好]` | 立即根据当前会话内容生成名称。支持附带关注点说明（例如 `/autoname 侧重后端修复`）。 |

## 名称格式

```text
主标题 · 副标题
```

- 主标题：最多 14 个字符，概括会话的核心任务，使用名词短语。若会话中途更换过任务，以耗时最长的任务为准，忽略开场寒暄与收尾说明。
- 副标题：最多 20 个字符，属于可选内容。仅在会话确实包含第二个实质性任务时生成；中文以「另」开头。若无第二任务，则仅保留主标题。
- 长度计算基于终端显示列宽（中文字符计 2 列宽，半角字符计 1 列宽）。

## 模型选择顺序

依次尝试以下候选配置，使用首个可用的模型：

1. 环境变量 `PI_RENAME_MODEL`（格式为 `provider/model`）
2. 配置文件中的 `model` 字段
3. 配置文件中的 `models` 候选列表
4. 当前会话所使用的模型（默认项，无需额外配置）

配置文件路径：`~/.pi/agent/config/auto-name.json`

```json
{
  "model": "opencode-go/deepseek-flash",
  "models": ["zai/glm-5.3-flash"],
  "thinking": "off"
}
```

字段说明：
- `model`：首选模型，格式为 `provider/model`
- `models`：备用模型列表，按顺序尝试
- `thinking`：推理思考强度，可选 `off`、`minimal`、`low`、`medium`、`high`，默认为 `off`

## 隐私与安全

- 模型调用仅发送截取的会话摘要片段，不发送完整会话：单条消息上限 400 字符，最多提取 20 个区块（首 2 轮、中间均匀抽样、尾 8 轮）。
- 模型请求通过 Pi 的模型服务层发出，不引入未配置的第三方服务。
- 名称通过追加记录写入已结束的会话文件，不修改当前正在交互的会话。

## 使用限制

- 用户手动设置的名称绝不覆盖。
- 对话轮数少于 2 轮且首条消息不足 200 字符的过短会话不予命名。
- 模型调用失败不会抛出中断错误，保留原名称并在状态栏显示提示。
- 设置环境变量 `PI_RENAME_AUTO=0` 可关闭会话结束时的自动命名，此时手动命令 `/autoname` 依然可用。