Flatnotes 笔记服务

Flatnotes 笔记服务操作技能。用于创建、搜索、获取、更新、删除 Markdown 笔记，支持全文搜索和附件管理。**必需环境变量**：FLATNOTES_BASE_URL（服务地址）、FLATNOTES_USERNAME（用户名）、FLATNOTES_PASSWORD（密码，敏感）。使用时必须先获取用户明...

Security Scan

技能总体功能与描述一致，但清单与运行时代码/文档之间存在不一致（特别是环境变量声明与同意流程），并且脚本会直接读取敏感凭证而依赖“代理必须先询问用户”这一外部约束——这构成了风险/不一致性。

Purpose & Capability

技能名/描述与所含脚本一致：它确实是用于与 Flatnotes API 交互（创建、搜索、获取、更新、删除笔记），因此请求 FLATNOTES_* 凭证在目的上是合理。但 registry metadata 的“Requirements”部分声称“无必需环境变量/凭证”，与 SKILL.md 和脚本直接要求 FLATNOTES_BASE_URL/FLATNOTES_USERNAME/FLATNOTES_PASSWORD 不一致。

Instruction Scope

SKILL.md 强调“必须先获得用户明确同意后才使用存储的凭证”，但随附的 Python 脚本会直接从环境变量读取用户名/密码并向服务请求令牌——脚本本身不实现用户确认逻辑。这意味着如果代理或用户自动运行脚本，凭证可能在未再次确认下被使用，形成权限/隐私风险。文档没有约束或强制在调用脚本前进行交互式确认。

Install Mechanism

无安装规范（instruction-only + Python 脚本随包提供），没有从网络下载或执行不明二进制，风险较低。脚本使用标准库 urllib，不拉取外部包。

Credentials

请求的三个环境变量（服务URL、用户名、密码）与功能直接相关，但两点值得注意：1) registry metadata omits这些必需变量（声明/实现不一致）；2) 文档建议将密码写入 ~/.bashrc 并通过环境变量使用，这会在多数系统中以明文持久化凭证；技能没有提供或建议使用更安全的秘密存储（如平台 secret 管理或注入只读 API token）。

Persistence & Privilege

技能未请求常驻(always:false)，亦未声明修改其他技能或系统范围配置。默认的自主调用能力存在（disable-model-invocation:false），这是平台默认并非单独风险，但与上述凭证/同意问题合并时要小心。

What to consider before installing

这项技能看起来确实实现了 Flatnotes 的常见操作，但在安装/使用前请注意： - 核实 metadata 与实际需求：注册表条目没有列出必需的环境变量，但技能文档和脚本确实需要 FLATNOTES_BASE_URL、FLATNOTES_USERNAME 和 FLATNOTES_PASSWORD；确保平台/管理员知道并同意向技能提供这些凭证。 - 不要把密码明文写入 ~/.bashrc：优先使用平台的安全 secret 存储或临时令牌，避免把敏感凭证放入长期可读的 shell 配置文件或日志中。 - 确认“用户同意”流程：SKILL.md 要求在使用已配置凭证前获得明确同意，但脚本本身不会强制询问。只有当运行此技能的代理/前端确实实现了交互确认，才符合文档要求。 - 审核服务端 URL 与信任：确保 FLATNOTES_BASE_URL 指向你信任的服务器（检验证书/域名），以防凭证被发送到恶意接口。 - 测试在受控环境中运行：先在非生产账户/测试实例上调用脚本，观察行为和网络流量，确认没有意外的数据外发或日志泄露。 如果你不能保证代理会在每次调用前提示并要求确认，或者不能使用安全的秘密注入机制，则在生产环境中谨慎使用该技能。

用于与 Flatnotes 笔记服务交互，支持创建、搜索、管理 Markdown 笔记。

使用场景

1. 保存长文本报告 - 将股票行情分析、调研报告等长内容保存为笔记
2. 格式化输出 - 利用 Markdown 支持生成带格式的文档
3. 内容检索 - 搜索已有笔记，获取历史记录
4. 知识沉淀 - 将对话中的重要信息保存到笔记系统

环境变量配置

export FLATNOTES_BASE_URL="https://your-flatnotes-host"  # 服务地址
export FLATNOTES_USERNAME="your-username"
export FLATNOTES_PASSWORD="your-password"

所有配置项均通过环境变量注入，脚本不包含任何硬编码地址或凭证。

添加到 ~/.bashrc 后执行 source ~/.bashrc 生效。

服务当前启用密码认证 (authType: password)，脚本会自动使用账号密码获取访问令牌。

自动检测机制

重要：执行技能前，先检查环境变量是否已配置：

• 如果三个环境变量均已设置 → 先向用户确认是否需要调用（如"是否保存到笔记？"），获得同意后再执行
• 如果环境变量未配置 → 提示用户配置后再执行

⚠️ 注意：使用存储的凭证前必须获得用户明确同意，禁止在用户未确认的情况下自动操作。

示例检查命令：

if [ -n "$FLATNOTES_BASE_URL" ] && [ -n "$FLATNOTES_USERNAME" ] && [ -n "$FLATNOTES_PASSWORD" ]; then
    echo "环境变量已配置，可直接调用"
else
    echo "环境变量未配置，需要设置"
fi

核心功能

获取令牌

脚本会自动处理认证，如需手动获取令牌：

python3 scripts/get_token.py [--username USER] [--password PASS] [--base-url URL]

创建笔记

使用脚本（推荐）:

python3 scripts/create_note.py "笔记标题" "笔记内容"

直接 API 调用:

curl -X POST $FLATNOTES_BASE_URL/api/notes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"title": "标题", "content": "# Markdown 内容"}'

搜索笔记

使用脚本（推荐）:

python3 scripts/search_notes.py "关键词" --limit 10

可用参数:

• --sort: score (默认) | title | lastModified
• --order: desc (默认) | asc
• --limit: 结果数量限制

获取笔记

使用脚本:

python3 scripts/get_note.py "笔记标题"

更新笔记

curl -X PATCH $FLATNOTES_BASE_URL/api/notes/原标题 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"newTitle": "新标题", "newContent": "新内容"}'

删除笔记

curl -X DELETE $FLATNOTES_BASE_URL/api/notes/标题 \
  -H "Authorization: Bearer <token>"

典型工作流

保存股票分析报告

1. 生成报告内容（Markdown 格式）
2. 创建笔记保存:

   python3 scripts/create_note.py "2026-03-12 恒生科技分析" "# 恒生科技指数分析\n\n## 行情概述\n..."
   

3. 向用户返回笔记链接/标题

检索历史报告

python3 scripts/search_notes.py "恒生科技" --sort lastModified --limit 5

数据格式

笔记对象

{
  "title": "string",
  "content": "string (Markdown)",
  "lastModified": 1234567890
}

搜索结果

[
  {
    "title": "string",
    "lastModified": 1234567890,
    "score": 0.95,
    "contentHighlights": "匹配内容高亮..."
  }
]

完整 API 参考

详见 references/api_docs.md

认证 API

获取访问令牌：

POST /api/token
Content-Type: application/json

{
  "username": "用户名",
  "password": "密码"
}

返回：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

注意：旧版使用 /api/login，新版改为 /api/token

笔记URL格式

访问笔记的完整URL格式为：

https://your-flatnotes-host/note/{笔记标题}

示例:

• 笔记标题: 太子工作日志 - 2026年3月12日
• 访问URL: https://your-flatnotes-host/note/太子工作日志%20-%202026年3月12日

注意：标题中的空格需编码为 %20，特殊字符需进行URL编码。

注意事项

1. 标题唯一性: 笔记标题是唯一的，重复创建会返回 409 错误
2. Markdown 支持: 内容支持标准 Markdown 语法
3. 全文搜索: 支持笔记内容和标题的模糊搜索
4. URL 编码: 标题含特殊字符时需要 URL 编码
5. 认证方式: 服务使用 Bearer Token 认证，脚本会自动从环境变量获取凭证并请求令牌