Protocol Launcher 系列：Agenda 优雅组织你的想法与日程

在介绍了 2Do 的集成后，今天我们将介绍如何通过 Protocol Launcher 与 Agenda 联动，让笔记管理和日程组织变得更加高效。

作为创意人士、写作者或项目管理者，你可能经常遇到这些场景：

• 在网页或应用中提供一个"在 Agenda 中创建笔记"的按钮，方便用户快速记录灵感。
• 从任务管理工具点击链接，直接在 Agenda 中打开对应的项目或笔记。
• 自动化工作流中动态创建笔记、追加内容或替换已有记录。

现在，通过 Protocol Launcher ，你可以摆脱手动拼接复杂的 agenda:// 协议链接，以类型安全的方式提升笔记管理效率。

---

Agenda 与深度链接

Agenda 是一款专为创意人士和专业人士设计的笔记应用，让你能够按日期组织想法。它提供了强大的深度链接支持，允许从网页或第三方应用直接触发创建笔记、打开项目、搜索内容等操作。

然而，手动拼接这些链接通常需要处理各种参数（如 project-title、on-the-agenda 等），且缺乏类型提示，极易出错。

---

核心能力：全面的笔记与项目管理

Protocol Launcher 为 Agenda 专门提供了 protocol-launcher/agenda 模块，支持以下核心功能：

1. 笔记管理：创建、打开、追加、替换笔记内容
2. 项目管理：创建和打开项目，管理笔记分类
3. 分类管理：创建新的分类来组织项目
4. 搜索与导航：打开搜索、概览、今日视图等
5. 状态获取：获取当前选中的笔记、项目或标识符
6. 自动处理协议逻辑：内部自动处理参数编码规则，确保链接 100% 可用

---

快速上手

首先，确保你的项目中已安装：

npm install protocol-launcher

在代码中你可以根据场景选择两种导入方式：

• 按需加载（通过子路径导入），支持 Tree Shaking，体积更小；
• 全量导入（从根包导入），写法更简单，但会引入所有已支持应用的逻辑。

// ✅ 推荐：按需加载 Agenda 模块
import { createNote, openProject } from 'protocol-launcher/agenda'

// 也可以从根包导入，但会包含所有应用模块
// import { agenda } from 'protocol-launcher'

场景一：创建笔记 (createNote)

这是最常用的功能。你可以快速创建带有标题、内容、日期等信息的笔记：

import { createNote } from 'protocol-launcher/agenda'

const url = createNote({
  title: '会议记录',          // 笔记标题
  text: '讨论项目路线图',      // 笔记内容
  projectTitle: '工作',        // 所属项目
  onTheAgenda: true,          // 添加到日程
  date: '2024-01-15',         // 日期（支持自然语言如 'yesterday'）
})

提示： date、startDate、endDate 参数支持自然语言表达，如 'yesterday'、'tomorrow'、'next Monday' 等。

场景二：创建项目 (createProject)

为新的工作流或主题创建项目：

import { createProject } from 'protocol-launcher/agenda'

const url = createProject({
  title: '新项目',                    // 项目标题
  categoryTitle: '工作',              // 所属分类
  select: true,                       // 创建后选中该项目
  sortOrder: 'newest-first',          // 笔记排序方式
})

场景三：创建分类 (createCategory)

组织项目的更高层级分类：

import { createCategory } from 'protocol-launcher/agenda'

const url = createCategory({
  title: '新分类',  // 分类标题
})

场景四：打开笔记 (openNote)

快速定位并打开已有笔记：

import { openNote } from 'protocol-launcher/agenda'

const url = openNote({
  title: '与 Peta 的会议',    // 笔记标题
  projectTitle: '工作',       // 所属项目
  separateWindow: true,       // 在新窗口打开（Agenda 18.0+）
})

场景五：打开项目 (openProject)

打开指定项目查看所有相关笔记：

import { openProject } from 'protocol-launcher/agenda'

const url = openProject({
  title: '工作项目',            // 项目标题
  separateWindow: true,         // 在新窗口打开
})

场景六：打开概览 (openOverview)

打开保存的概览视图：

import { openOverview } from 'protocol-launcher/agenda'

const url = openOverview({
  title: '本周',              // 概览标题
  separateWindow: true,       // 在新窗口打开
})

场景七：打开搜索 (openSearch)

快速启动搜索功能：

import { openSearch } from 'protocol-launcher/agenda'

const url = openSearch({
  query: '#重要',             // 搜索关键词（支持标签）
  separateWindow: true,       // 在新窗口打开
})

场景八：追加到笔记 (appendToNote)

向已有笔记追加内容：

import { appendToNote } from 'protocol-launcher/agenda'

const url = appendToNote({
  title: '某些笔记',          // 笔记标题
  text: '更多文本',           // 要追加的内容
  onTheAgenda: true,          // 添加到日程
})

场景九：替换笔记 (replaceNote)

完全替换笔记内容：

import { replaceNote } from 'protocol-launcher/agenda'

const url = replaceNote({
  title: '某些笔记',          // 笔记标题
  text: '新内容',             // 替换后的完整内容
})

场景十：获取标识符 (getIdentifier)

获取笔记或项目的唯一标识符：

import { getIdentifier } from 'protocol-launcher/agenda'

const url = getIdentifier({
  projectTitle: '欢迎',       // 项目标题
  title: '尝试事项',          // 笔记标题
})

场景十一：获取选择 (getSelection)

获取当前选中的内容：

import { getSelection } from 'protocol-launcher/agenda'

const url = getSelection()
// => 'agenda://x-callback-url/get-selection'

场景十二：获取选中的笔记 (getSelectedNote)

获取当前选中的笔记：

import { getSelectedNote } from 'protocol-launcher/agenda'

const url = getSelectedNote()
// => 'agenda://x-callback-url/get-selected-note'

场景十三：获取选中的项目 (getSelectedProject)

获取当前选中的项目：

import { getSelectedProject } from 'protocol-launcher/agenda'

const url = getSelectedProject()

场景十四：打开今天 (today)

快速打开今日视图：

import { today } from 'protocol-launcher/agenda'

const url = today()

场景十五：打开在议程上 (onTheAgenda)

打开在议程上视图：

import { onTheAgenda } from 'protocol-launcher/agenda'

const url = onTheAgenda()

---

高级用法：模板与附件

使用模板创建笔记

Agenda 支持从模板创建笔记，可以大大提高重复性工作的效率：

import { createNote } from 'protocol-launcher/agenda'

const url = createNote({
  title: '每日站会记录',
  projectTitle: '工作',
  templateName: '站会模板',      // 模板名称
  templateInput: '今天完成了 X',  // 模板输入内容
  date: 'today',
})

添加附件到笔记

支持添加图片等附件到笔记：

import { createNote } from 'protocol-launcher/agenda'

const url = createNote({
  title: '带附件的笔记',
  text: '这是一个带有图片的笔记',
  attachment: 'base64 编码的图片数据',  // base64 编码
  filename: 'screenshot.png',           // 文件名
  displayStyle: 'thumbnail',            // 显示样式
  displaySize: 'medium',                // 显示大小
})

链接到日历事件

将笔记链接到日历事件：

import { createNote } from 'protocol-launcher/agenda'

const url = createNote({
  title: '会议记录',
  text: '会议讨论内容...',
  eventTitle: '项目评审会议',  // 关联的日历事件
  date: '2024-01-15',
})

---

为什么选择 Protocol Launcher？

1. 类型安全与参数提示：TypeScript 的智能补全会确保你提供了必要的参数，并提醒你可选的配置项。
2. 自动编码与 Unicode 支持：库内部会自动处理所有的 URL 编码逻辑，确保生成的 URL 在唤起应用时绝不乱码。
3. 一致的用户体验：通过封装复杂的协议逻辑，你可以专注于业务功能的实现，而不用担心不同操作系统下协议触发的细微差异。
4. 极致的按需加载 (Tree Shaking) ：采用了模块化设计，支持按需加载以最小化包体积：
   • 推荐方式 ：使用子路径导入（如 import { createNote } from 'protocol-launcher/agenda'），这样构建工具只会打包相关的代码。
   • 全量方式 ：也可以从根包导入（如 import { agenda } from 'protocol-launcher'），建议生产环境始终使用按需加载。
5. 完整的 API 覆盖：支持 Agenda 所有深度链接命令，包括笔记管理、项目管理、搜索导航等 15 个功能。

---

结语

通过 Protocol Launcher，你可以将 Agenda 深度集成到你的工作流中。无论是在网页应用中提供快速记录入口，还是在自动化工具中动态管理笔记，它都是连接 Web 与 Agenda 最优雅的桥梁。

---

🔗 相关链接

• Protocol Launcher 官网：https://protocol-launcher.huayi-data.com/
• Agenda 模块文档：Agenda | Protocol Launcher