# @huntye1/pi-auto-session-name

[English](README.md)

这是一个非阻塞、注重隐私的 Pi 扩展：新会话完成首个成功任务后，它会自动生成简短的会话名称。

## 安装

需要 Pi `1.1.0` 或兼容的后续版本，以及 Node.js `>=22.19.0`。

```bash
pi install npm:@huntye1/pi-auto-session-name
```

在运行中的 Pi 执行 `/reload`，再通过 `/new` 开始新会话。本地开发时可直接加载：

```bash
pi --extension ./packages/pi-auto-session-name/extensions/auto-session-name.ts
```

本包不会改写 Pi 设置、注册模型工具、改变主对话提示词或创建后台进程。请勿同时启用其他自动命名扩展。

## 默认行为

- 只对新建且持久化的 TUI/RPC 会话，在首个成功任务结束后自动尝试一次。
- 默认使用当前会话模型，不隐式选择其他服务，也不跨 provider 回退。
- 通过 `ctx.modelRegistry.streamSimple()` 命名，不向主会话记录注入工具或消息。
- `agent_settled` 不等待命名 Promise，因此命名进行中也可以开始下一轮。
- 最多读取原始需求 800 个 Unicode 字符和最近最终回答 400 个字符，忽略中途工具说明。
- 默认标题上限为 24 个 Unicode code points，并跟随用户语言。
- 使用独立 session-affinity ID，请求结束后清理 provider 资源。
- 默认端到端超时 10 秒（包含认证），无自动重试或定时改名。
- 已有名称、恢复、重载、分叉、临时、print 和 JSON 会话不会自动命名。
- 改名、清空、替换会话、重载、关闭或切换分支会取消或使待处理结果失效。
- 同一分支上的正常后续对话不会取消命名；上下文编辑和 compaction 会使旧快照失效。

## 命令

| 命令 | 行为 |
| --- | --- |
| `/auto-name` | 显式生成或重试；替换已有名称前会确认 |
| `/auto-name status` | 查看配置、实际模型、最近结果、耗时和独立调用 usage |
| `/auto-name model trae/gpt-5.5` | 校验并保存命名模型，立即生效 |
| `/auto-name trae/gpt-5.5` | 上一条命令的简写 |
| `/auto-name model current` | 恢复使用当前会话模型 |
| `/auto-name cancel` | 取消命名请求，不影响主任务 |
| `/auto-name clear` | 清空名称并锁定自动命名 |
| `/name 自定义名称` | Pi 内置手工改名；手工名称始终优先 |

显式命令会等待自己的结果，自动命名则保持非阻塞。没有交互 UI 时不会替换已有名称；缺少有效需求或成功最终回答时会跳过。

`/auto-name` 使用原始需求（最多 800 字符）、最新且不重复的需求（最多 400 字符）和最新最终回答（最多 400 字符）。自动失败后不会重试，除非显式执行命令。

## 配置

扩展只读取用户配置：

```text
${PI_CODING_AGENT_DIR:-~/.pi/agent}/auto-session-name.json
```

它故意忽略项目配置，避免仓库改变命名 provider。无需配置也可使用。

```json
{
  "enabled": true,
  "mode": "llm",
  "model": "",
  "language": "auto",
  "timeoutMs": 10000,
  "maxTitleChars": 24
}
```

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 总开关；关闭后显式模型命名也不可用 |
| `mode` | `llm` | `llm` 调用模型；`local` 从脱敏后的需求中截取，不调用模型 |
| `model` | `""` | 空值使用当前模型；也可写 `provider/modelId`。模型不存在时安全跳过，不回退 |
| `language` | `auto` | `auto`、`zh` 或 `en`；只影响 LLM 提示词 |
| `timeoutMs` | `10000` | 1,000–30,000 ms 的端到端超时 |
| `maxTitleChars` | `24` | 8–80 个 Unicode code points，不是终端列宽 |

手工修改配置后执行 `/reload` 生效；`/auto-name model ...` 会校验并原子更新配置，立即生效。未知字段、非法值、非普通文件、超过 8 KiB 或无效 JSON 都会安全禁用命名。配置不支持凭证，认证始终由 Pi 管理。

## 隐私与限制

- 忽略工具结果和参数、thinking、图片、system/custom 消息、分支摘要和 compaction 摘要。
- 只读取活动分支，并遵守 `context_edit` 的替换和删除。
- 启发式脱敏私钥、常见 API Key、Bearer/Basic、Cookie/Authorization、JWT、敏感赋值，以及 URL 凭据、查询参数和 fragment。
- 删除 Markdown 代码块和 Pi `<file>` 附件块；作为普通文本粘贴的代码仍可能进入摘录。
- 在截断前对有界输入执行过滤和脱敏：单条最多 8,192 个 UTF-16 code units、128 个内容块，活动分支最多 2,048 个条目。
- 模型只收到独立 system 规则和 JSON 摘录，不提供工具；输出中的疑似秘密、控制字符和双向文本控制符会被拒绝。
- **启发式脱敏不是 DLP，无法保证识别所有秘密。** LLM 模式会向选定 provider 发送少量会话文本。请使用获准的 provider；完全不希望额外发送内容时，请使用 `local` 模式或关闭扩展。
- 不上传遥测，也不持久化摘录和服务端错误文本。会话名称会写入 Pi Session JSONL，并可能出现在标题、footer 和恢复列表中。
- `pi-auto-session-name/v1` 自定义条目只保存尝试所有权、结果、耗时和数值 usage，不保存摘录或凭证。
- 命名会产生一次额外模型调用；最近费用可通过 `/auto-name status` 查看，不计入主会话 footer。

## 开发与发布

```bash
npm run check
npm run pack:check
npm publish --access public
```

`check` 包含类型检查、单元测试，以及使用假 provider 的真实 Pi SDK 离线集成测试。发布包只包含扩展入口、源码、中英文 README、LICENSE 和 package 元数据。Pi 宿主 API 作为 optional peer dependencies 由宿主提供。

## 许可证

MIT