memos-skill（备忘录技巧）

Memos Skill

管理你的 Memos 备忘录实例，支持完整的备忘录生命周期操作。

配置

在使用 memos API 之前，需要创建配置文件。

配置文件位置

在 skill 目录下创建 config.json 文件：

memos-skill/
├── SKILL.md
├── config.json          # 配置文件
└── ...

配置文件格式

{
  "instance_url": "https://your-memos-instance.com",
  "access_token": "your-access-token",
  "default_page_size": 10,
  "default_visibility": "PRIVATE"
}

配置说明

获取访问令牌

1. 登录你的 memos 实例
2. 进入 Settings → Tokens
3. 点击 "Create Token"
4. 复制生成的令牌并填入 config.json

在 JavaScript 中读取配置

import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 获取 skill 目录路径
const skillDir = __dirname;
const configPath = path.join(skillDir, "config.json");

// 读取配置
const config = JSON.parse(fs.readFileSync(configPath, "utf8"));

const instanceUrl = config.instance_url;
const accessToken = config.access_token;
const headers = {
  Authorization: `Bearer ${accessToken}`,
  "Content-Type": "application/json",
};

执行策略

处理任何 memos 相关请求时，默认遵循下面的实现方式：

1. 使用 Node.js 读取 config.json，拿到 instance_url 和 access_token
2. 使用 curl 调用 memos API 完成查询、创建、更新、删除、上传附件等操作
3. 除非用户明确要求，否则不要改用 Python、requests、axios 或其他 SDK

标准执行流程

1. 用 Node.js 读取配置

import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const configPath = path.join(__dirname, "config.json");
const config = JSON.parse(fs.readFileSync(configPath, "utf8"));

const instanceUrl = config.instance_url;
const accessToken = config.access_token;

2. 用 curl 调用 memos API

curl -X POST \
  -H "Authorization: Bearer $MEMOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"测试内容","tags":["test"]}' \
  "$MEMOS_URL/api/v1/memos"

操作要求

• 读取配置时，优先使用 Node.js 脚本而不是 shell 文本解析
• 对 memos 的增删改查操作，优先输出或执行 curl 命令
• 更新操作时，要显式带上 PATCH 和 updateMask
• 搜索、列表、详情、评论、反应、附件等请求，也保持 curl 风格一致
• 如果要给用户展示“将如何执行”，优先展示 Node 读取配置 + curl 请求两步

核心功能

1. Memo 管理

创建备忘录

• 端点: POST /api/v1/memos
• 关键字段:

- content: 备忘录内容（支持 Markdown） - visibility: 可见性（PRIVATE, PROTECTED, PUBLIC） - tags: 标签数组 - resources: 关联资源

示例:

{
  "content": "今天要完成的任务：\
- 完成项目文档\
- 回复客户邮件",
  "visibility": "PRIVATE",
  "tags": ["todo", "work"]
}

获取备忘录列表

• 端点: GET /api/v1/memos
• 参数:

- pageSize: 每页数量（默认 10） - pageToken: 分页令牌 - filter: 过滤条件（遵循 Google AIP-160 标准） - creator == "users/1": 按创建者过滤 - row_status == "NORMAL": 正常状态的备忘录 - create_time > "2024-01-01": 按创建时间过滤 - tag == "work": 按标签过滤 - content.contains("关键词"): 内容搜索 - sort: 排序方式（createTime, updateTime）

获取单个备忘录

• 端点: GET /api/v1/memos/{memo}
• 返回完整的备忘录详情，包括内容、标签、评论等

更新备忘录

• 端点: PATCH /api/v1/memos/{memo}
• 使用 updateMask 指定要更新的字段，如 content,visibility,tags

删除备忘录

• 端点: DELETE /api/v1/memos/{memo}

2. 搜索与过滤

使用 Google AIP-160 过滤语法进行高级搜索：

# 组合条件
content.contains("项目") AND tag == "work"

# 按时间范围
create_time > "2024-01-01" AND create_time < "2024-12-31"

# 多标签查询
tag == "work" OR tag == "personal"

# 排除条件
NOT tag == "archive"

# 完整示例
filter: "creator == \"users/1\" AND (tag == \"work\" OR tag == \"urgent\") AND create_time > \"2024-01-01\""

3. 评论与反应

添加评论

• 端点: POST /api/v1/memos/{memo}/comments

获取评论列表

• 端点: GET /api/v1/memos/{memo}/comments

添加反应（表情）

• 端点: POST /api/v1/memos/{memo}/reactions
• 支持的表情：THUMBS_UP, THUMBS_DOWN, HEART, FIRE, ROCKET, EYES, THINKING, CLAPPING, PARTY, ROCKET

4. 附件管理

上传附件

• 端点: POST /api/v1/attachments
• 支持 multipart/form-data 上传文件

获取附件列表

• 端点: GET /api/v1/attachments

将附件关联到备忘录

• 端点: POST /api/v1/memos/{memo}/attachments
• 请求体：{"attachmentIds": ["attachments/1", "attachments/2"]}

5. 关联备忘录

创建关联

• 端点: POST /api/v1/memos/{memo}/relations
• 关联类型：REFERENCE, COMMENT

6. 用户管理

获取当前用户

• 端点: GET /api/v1/auth/status

创建个人访问令牌

• 端点: POST /api/v1/users/{user}/personalAccessTokens
• 返回的 token 只在创建时显示一次

API 请求格式

认证头

Authorization: Bearer <YOUR_ACCESS_TOKEN>

标准响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应

{
  "code": 3,
  "message": "Invalid argument",
  "details": []
}

使用场景示例

场景 1: 快速记录想法

用户说："帮我记录一条备忘录，内容是今天和客户的会议要点..."

POST /api/v1/memos
{
  "content": "今天和客户的会议要点：\
1. 确认交付时间...",
  "visibility": "PRIVATE",
  "tags": ["meeting", "client"]
}

场景 2: 搜索备忘录

用户说："搜索我上个月关于项目的备忘录"

GET /api/v1/memos?filter=content.contains("项目") AND create_time > "2024-02-01"&pageSize=20

场景 3: 批量整理

用户说："把标签为'temp'的所有备忘录改成'archive'"

GET /api/v1/memos?filter=tag == "temp"&pageSize=100
# 然后对每个 memo 调用 PATCH 更新标签

场景 4: 带附件的备忘录

用户说："创建一个备忘录并附上这张图片"

# 1. 先上传附件
POST /api/v1/attachments
Content-Type: multipart/form-data

# 2. 创建备忘录
POST /api/v1/memos
{
  "content": "图片说明...",
  "resources": [{"name": "attachments/1"}]
}

场景 5: 配置 memos 实例

用户说："把我的 memos 实例配置为 https://memo.example.com，token 是 abc123"

处理步骤：

1. 检查是否存在 config.json 文件
2. 如果存在，询问用户是否覆盖现有配置
3. 创建或更新配置文件：

{
  "instance_url": "https://memo.example.com",
  "access_token": "abc123",
  "default_page_size": 10,
  "default_visibility": "PRIVATE"
}

1. 验证配置（可选：发送测试请求）
2. 返回配置成功的确认信息

代码示例：

import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const config = {
  instance_url: "https://memo.example.com",
  access_token: "abc123",
  default_page_size: 10,
  default_visibility: "PRIVATE",
};

const skillDir = __dirname;
const configPath = path.join(skillDir, "config.json");

fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\
`, "utf8");

console.log(`配置已保存到: ${configPath}`);

输出格式建议

根据用户需求，灵活返回以下格式：

1. 简要摘要: 返回备忘录标题/ID、创建时间、标签列表
2. 完整内容: 返回完整内容（包括 Markdown 渲染）
3. 表格形式: 多条备忘录时用表格展示 ID、内容预览、时间、标签
4. JSON 格式: 用户需要编程处理时返回原始 JSON

最佳实践

1. 内容格式: 鼓励使用 Markdown 格式编写备忘录内容
2. 标签管理: 建议使用统一的标签命名规范（小写、用连字符连接）
3. 可见性设置: 默认为 PRIVATE，分享时才设为 PUBLIC
4. 分页处理: 列表查询时注意处理分页，避免一次返回过多数据
5. 错误处理: API 可能返回 401（未授权）、404（不存在）、400（参数错误）等状态码

注意事项

• 备忘录 ID 格式为 memos/{id}，如 memos/123
• 用户 ID 格式为 users/{id}，如 users/1
• 附件 ID 格式为 attachments/{id}
• 创建时间字段是 ISO 8601 格式，如 2024-03-12T10:30:00Z
• 更新操作使用 PATCH，需要指定 updateMask 避免覆盖其他字段