Pi Notes

让 Pi 直接使用你的 Markdown 笔记。根笔记按属性提供全文或摘要，深层笔记可通过关键词主动提醒，AI 再用现有工具按需读取。

可以连接整个 Obsidian 库，也可以只连接其中的一个文件夹；无需 Obsidian 插件。全局目录之外，受信任项目内的 .note 目录会自动注入项目笔记。

开始使用

需要 Node.js 22.19+ 和 Pi 0.85.1+。

pi install npm:@liuser/pi-notes

本地开发安装：在仓库执行 npm ci --ignore-scripts && npm run build && pi install .。修改源码后重新构建。

安装后重新启动 Pi。未配置时，若当前 agent 目录下已有 notes/，会自动作为全局来源；也可用 /notes 指定其他目录。

配置跟随当前 agent 目录（PI_CODING_AGENT_DIR）。自动注入的笔记会随请求发送给当前模型，请选择适合共享的目录。插件不会迁移或修改现有的 USER.md。

写一篇笔记

---
description: 用户的协作偏好与表达习惯。
purpose: >-
  这是对用户的持续建模，用于理解用户并辅助沟通与判断。
  结合当前情境使用，区分明确偏好与推断，当前明确要求优先。
defaultopen: true
---

在 frontmatter 之后正常写 Markdown 正文。以下字段都是可选的：

| 字段 | 作用 | 未填写时 | | --- | --- | --- | | description | 说明笔记内容，以及何时值得读取 | 保留文件名和路径 | | purpose | 说明笔记对 AI 的价值和使用方式 | 省略定位说明 | | defaultopen | true 注入完整正文；false 只提供摘要 | false | | keywords | 字符串列表；深层笔记命中时提供摘要入口 | 不参与关键词提醒 |

purpose 在两种模式下都提供。defaultopen 使用 YAML 布尔值，不要写成带引号的 "false" 或 "true"。普通 Obsidian 属性如 tags、aliases 可以继续保留。

示例笔记见 examples/vault/，完整注入版式见 设计说明。

深层笔记的关键词提醒

在子目录笔记的 frontmatter 中添加：

---
keywords: [字体, font-family, 排版]
description: Web 项目的统一字体栈与使用约定。
purpose: 设置或调整 Web 字体时参考。
---

• 匹配用户输入、模型回复和渠道实际提供的可见思考文本，按字面短语匹配，英文大小写不敏感；不是语义搜索或正则表达式。
• 用户输入命中时，本次请求提供笔记名、路径、定位和摘要；模型输出命中则留到下一次正常调用，包括工具后续轮次。最终回复之后不会因此额外续跑。
• 全局目录和受信任的 .note 子目录都在范围内。根层已展示的笔记不重复提醒；深层笔记即使 defaultopen: true 也只提供摘要，全文由 AI 按需读取。
• 已在当前上下文保留的提醒不重复追加。恢复、分支与压缩会重新对账；提醒移出上下文后，新的命中可以再次提供。工具结果、工具参数和插件注入文本不触发提醒。

不需要新增命令；打开会话时后台准备索引，编辑笔记后按文件变化更新，下一次用户输入使用更新后的索引。/notes preview 展示默认内容及读取/索引问题，不预先罗列所有关键词候选。扩展代码更新后重启 Pi 或执行 /reload。

项目笔记目录（.note）

在项目根（或任意上层目录）创建 .note 文件夹，Pi 在该项目中工作时自动注入其中的笔记，无需修改全局配置：

my-repo/
  .note/
    说明.md      ← defaultopen: true 注入全文
    参考.md      ← defaultopen: false 只提供摘要
  src/

• 信任门槛：仅当项目已受 Pi 信任时注入，与 .pi/extensions、.pi/skills 的信任边界一致。未信任时不注入内容，/notes preview 会列出来源与原因。不含 trust-requiring 资源（如 .pi 目录）的普通项目按 Pi 的默认行为视为受信任。
• 发现范围：从工作目录向上到 git 根（无 git 时到文件系统根），每个目录的 .note 都是一个来源；发现范围内不嵌套查找；相同来源根路径去重，藏在全局目录内部的 .note 仍作为独立、受信任门槛控制的来源。
• 注入顺序：全局目录在前，项目来源由浅到深，各自带标题与绝对路径。
• 预算：超预算时整份来源排除并明确报告，不部分截断、不静默丢弃；其余来源照常注入。

日常操作

| 命令 | 用途 | | --- | --- | | /notes | 查看当前目录、注入概况，进入预览或更换目录 | | /notes set <目录> | 直接设置目录；支持相对路径、~、空格和外层引号 | | /notes preview | 查看完整默认上下文，以及读取和索引问题 | | /notes clear | 停用全局来源的默认注入与关键词提醒；项目来源、笔记文件和已有历史保留 | | /notes help | 查看命令与配置文件位置 |

预览是只读界面，不会把预览内容追加进对话。方向键滚动，PageUp / PageDown 翻页，Escape 返回；遵循 Pi 中对应按键的自定义绑定。当前回复结束后可使用这些命令。

自动发现与更新

• 默认展示各来源根目录的直接子项：普通 .md 文件和子文件夹；关键词索引递归读取可用来源的子目录。
• 忽略隐藏文件、隐藏目录、符号链接条目及非 Markdown 文件。显式配置的根目录本身可以是符号链接。
• 子目录中的 defaultopen: true 不会触发跨层级自动注入。AI 可以从文件夹入口继续深入。
• 每次新提示只检查根层默认笔记；深层关键词索引在打开会话时后台加载并校验，随后监听文件变化、只检查受影响的文件或子目录。未变化的消息发送不遍历全库、不重建索引。
• 索引缓存保存在 agent 目录的 cache/pi-notes/，跨会话和重启复用。缓存只含文件签名、关键词、定位、摘要和解析错误，不含正文；重启时后台检查签名，只重新读取变化的文件。可删除缓存目录，之后会自动重建。
• 首次准备时状态栏显示“索引准备中”。若立即发送，用户消息先显示，再等索引就绪后请求模型，保留当轮关键词提醒。监听不可用时明确告警，并每 30 秒后台检查。
• 同一轮工具调用期间复用本轮默认注入和关键词索引快照；模型消息完成时只在内存中匹配一次，不随流式片段反复扫描文件。
• 文件搜索、zg、双链读取和笔记修改沿用当前 Pi 环境的工具与任务授权。关键词索引仅保存元数据，不是全文搜索索引或权限沙箱。

配置与异常

配置文件是当前 agent 目录下的 notes.json，遵循 PI_CODING_AGENT_DIR（常见为 ~/.pi/agent/notes.json）。未写入 directory 时，若同级 notes/ 目录存在则用作全局来源。/notes set 会保存规范化的绝对目录路径。通常只需用命令配置；手工调整注入预算时，配置格式如下（目录为示例）：

{
  "directory": "/example/vault/AI",
  "maxContextBytes": 262144
}

directory: null 表示停用全局来源，项目来源仍独立生效。默认笔记与关键词提醒共用预算，默认内容优先；放不下的提醒整篇延后并报告。预算按 UTF-8 字节计，默认 256 KiB，可设为 1 KiB 到 16 MiB；这是笔记块的上限，不是模型 token 数，也不保证当前模型剩余空间足够。

• 单篇 frontmatter 超过 64 KiB、属性无效、文件不可读或全文文件超过预算时，保留路径并标明未展开原因，不注入该篇正文。
• 单份来源整体超预算或目录不可读时，整份来源排除并明确报告，其余来源照常注入。不会部分截断全文，也不会回用旧笔记块。
• 配置损坏时请按提示修复 notes.json；命令不会覆盖无法解析的配置。YAML 别名引用、自定义标签和重复字段会被拒绝。
• keywords 必须是字符串列表，空列表表示不触发，空白元素或其他类型被拒绝。每个来源的关键词索引和解析缓存各设 16 MiB 序列化估算上限，合并候选也以 16 MiB 为限；单次来源扫描最多处理 100,000 个深层条目，超限明确报告。

RPC 下预览通过 UI 通知返回；print / JSON 模式的命令输出写入 stderr，不污染 stdout 协议。

发布维护

自动发布与首次 OIDC 配置见 npm 发布。

开发与验证

npm run check
npm test
npm run test:integration
npm run test:keywords
npm run test:tui
npm run bench
npm run bench:keywords
npm run bench:store

集成测试使用真实 Pi 进程和本地测试模型端，无外部模型调用；TUI 测试需要 tmux。两者在隔离配置下运行，原始记录保存在 .artifacts/。

可选真实模型验证：

npm run test:live
npm run test:live:keywords

此命令使用现有 Pi 默认模型与该提供方认证的临时副本，最多 8 次模型请求，单次任务等待上限 150 秒。测试结束删除临时认证文件；原始请求和结果保存在 .artifacts/。该入口面向已有认证的内置提供方，自定义提供方配置不会被自动复制。

bench:store 测量后台准备、持久缓存重启和未变化发送，默认使用 10,000 篇合成笔记（2,500 篇有关键词）；npm run bench:store -- /absolute/vault 只读测量指定库，缓存写入隔离实验目录。bench:keywords 单独测量底层扫描与匹配引擎，不代表消息发送路径；可用 npm run bench:keywords -- /absolute/vault 额外只读测量实际笔记库。真实模型关键词验收检查按提醒路径读取，以及回复命中留到下一次输入。

已验证的环境与覆盖范围见 验证记录。首版在 Pi 0.85.1、Node.js 26.1.0、macOS 上验证；其他环境需要补测。