# zed-notify — Agent 规范

## 项目一句话定位

Pi 扩展：在 `agent_end` 时发一个终端 `BEL`（`\x07`），让 Zed Terminal Thread 显示完成通知。

## 先读文档顺序
1. 本文件
2. `README.md`
3. `doc/README.md`

## 技术栈
- TypeScript Pi extension
- 无运行时依赖

## 验证方式
- 在 Zed Terminal Thread 中先跑 `printf '\a'`
- 再跑 `pi --no-session -e /path/to/zed-notify -p "reply once: test"`

## 文档沉淀出口
- `README.md`：用户安装、配置、验证
- `doc/README.md`：设计边界、已知限制

## 工程纪律
- 默认保持最小实现，不为跨终端兼容提前做复杂抽象
- 改行为时先验证 Zed bell 链路，再改扩展代码
- 不引入 `OSC 9` 作为 Zed 主路径，除非 Zed 上游明确支持

## 分发与加载约定（v0.0.2 起）

本扩展的发布物是一个 **pi 包**（`pi.extensions: ["./index.ts"]`），应通过以下方式加载，**不在 `~/.pi/agent/extensions/zed-notify/` 下手挂副本**：

- **包安装**：`pi install npm:zed-notify` / `pi install git:github.com/ssdiwu/zed-notify` / `pi install /absolute/path/to/zed-notify`
- **手挂注册**：在 `~/.pi/agent/settings.json` 的 `packages` 数组里加一行本仓绝对路径或相对路径

为什么不要在 `~/.pi/agent/extensions/<name>/` 下手挂：

- pi 的扩展扫描是 **包列表** + **自动发现目录** 双轨。手挂副本可被自动发现机制加载一份、包列表又加载一份，同一个 `agent_end` 事件会被两个 handler 各发一次 `\x07` —— 形成「双源漂移」。
- 改一处忘改另一处 → 行为漂移、版本漂移、bug 难定位。
- 单源切包列表后改的都是 `index.ts`，reload 即生效。

回退方法：如需紧急冻结、临时把手挂副本复活，可执行 `mv /tmp/zed-notify.bak.1783183007 /Users/diwu/.pi/agent/extensions/zed-notify`，并相应处理 `settings.json` 的 `packages` 项。本仓的 `v0.0.2` 切单源时按此路径留过 `/tmp` 回退备份。