TaskLens pi 扩展

把 TaskLens 的 vault 能力接进 pi.dev 编码 agent：17 个工具 + 4 个斜杠命令， 让 agent 直接读写任务、日志、经验、成果笔记，并做 Git 同步。

底层是 tasklens-cli（Rust core 的 NDJSON over stdio 接口），所以 pi、MCP 客户端与桌面应用 操作的是同一套 vault 语义，工具名和参数也完全一致。

安装

任选一种：

# 1) 按文件安装（写进 settings.json 的 extensions）
pi install /absolute/path/to/TaskLens/pi-extension/tasklens.ts

# 2) 拷到扩展目录（自动发现，/reload 可热重载）
cp pi-extension/tasklens.ts ~/.pi/agent/extensions/   # 全局
cp pi-extension/tasklens.ts .pi/extensions/           # 项目内

# 3) 临时试用
pi -e ./pi-extension/tasklens.ts

前置：CLI 二进制

扩展按以下顺序找 tasklens-cli（Windows 为 tasklens-cli.exe）：

1. 环境变量 TASK_LENS_CLI（App 启动 agent 时会设成绝对路径）；
2. PATH 上的 tasklens-cli。

两者都没有时，工具会返回一条可读错误，提示设置 TASK_LENS_CLI 或先执行：

bun run core:build   # 产物：target/debug/tasklens-cli.exe
export TASK_LENS_CLI="$PWD/target/debug/tasklens-cli.exe"   # Windows: set TASK_LENS_CLI=...

vault 根目录由 tasklens-cli 自己决定：--vault 参数 → 环境变量 TASK_LENS_VAULT → 已保存的活动 vault。设置 TASK_LENS_VAULT 即可把 agent 固定到某个 vault。

工具

所有工具返回 Markdown 文本；出错时返回 错误：… / 参数错误：…，不会抛异常打断会话。

工具	参数	用途 / 什么时候用
vault_list	{type?}	列笔记（可按类型过滤），动手前看全貌
vault_read	{path}	读原文（含 frontmatter），确认行号
vault_search	{query, limit?}	全文检索，返回路径 + 行号
vault_task_brief	{path}	信息梳理主入口：子任务行号 + 变更日志 + 相关日志/经验/成果/反向链接 + 事件
vault_events	{path?, limit?}	结构化事件时间线
vault_create_note	{folder, name, content}	新建笔记（自动建目录、补 .md）
vault_write	{path, content}	整篇覆盖写入
vault_update_frontmatter	{path, updates, removals?, source?}	改 status/priority/related_to 等字段
vault_replace_section	{path, heading, text}	按 ## 标题 整段替换（缺失则创建）
vault_append_item	{path, heading, item}	往「## 子任务」「## 变更日志」末尾追加一行
vault_set_line	{path, line, text}	按行号改写一行
vault_insert_line	{path, afterLine, text}	在某行之后插入
vault_delete_line	{path, line}	按行号删除一行
vault_toggle_checkbox	{path, lines}	勾选/取消勾选子任务（可用多个行号）
vault_git_status	{}	看分支/远端/变更
vault_git_sync	{message}	提交并同步（message 留空用设置里的默认值）

Vault 约定

• 笔记类型写在 frontmatter type:（目录只是分类，类型目录下的子目录不改变类型）：
  • 任务 → 任务/，字段 status / priority / category / created / owner / related_to
  • 日志 → 工作日志/，字段 date
  • 经验 → 经验/
  • 成果 → 成果/
  • 记忆碎片 → 记忆碎片/，字段 created / related_to 以上是默认目录；用户会在「设置 → 类型」里改成别的，动手前先用 vault_list 看该类型笔记实际在哪。
• 任务正文分节：## 背景、## 子任务（- [ ] 清单）、## 变更日志（- 日期: 内容）。
• 关联用 wikilink：related_to: ["[[软包工作-任务]]"]。
• vault_replace_section / vault_append_item / vault_*_line 都是按标题或行号做手术式改写， 改动前先用 vault_read 或 vault_task_brief 看清行号。

斜杠命令

命令	作用
/tasklens-file	把当前对话里的待办整理成任务笔记（建笔记 + 补 frontmatter + 关联）
/tasklens-today	梳理今天的日志，归并到任务 / 经验 / 成果
/tasklens-distill	从已完成任务沉淀经验与成果，并双向关联
/tasklens-sync	看 vault_git_status，有变更就 vault_git_sync

命令会把一段带工具清单的指令发回给 agent（pi.sendMessage），由 agent 实际执行；可以跟参数缩小范围， 例如 /tasklens-distill 支付重构。

作为进程内 SDK 组件复用

tasklens.ts 除了 default export 工厂，还导出 VAULT_TOOLS: VaultTool[]（VaultTool 就是 pi SDK 的 ToolDefinition）：17 个工具定义，含 name / label / description / parameters / promptSnippet / promptGuidelines / execute。把 pi 当进程内 SDK 嵌入时可直接复用：

import { VAULT_TOOLS } from "../pi-extension/tasklens.ts";

const session = await createAgentSession({ customTools: VAULT_TOOLS, /* … */ });

模块导入零副作用：不启动 CLI、不读文件、不写 stdout；CLI 只在真正调用某个工具时才 spawn，并按 TASK_LENS_CLI → PATH 的顺序解析。session_start 的就绪提示只在走 pi 扩展加载时才会触发。

说明

• 依赖 typebox 的 Type.Object 描述工具参数，类型来自仓库依赖 @earendil-works/pi-coding-agent@^0.85.1。
• 测试：bunx vitest run pi-extension。CLI 不存在时真实调用那组用例自动 skip。