ahel
Start free

说说笔记 Skill

SkillSearch

All-in-one skill for Shuoshuo notes. Uses the HTTP API by default; MCP is used only when explicitly enabled. Covers posting, search, pagination, details, update, delete, pinning, login, tokens, status, configuration, calendar, and RSS.

Available today. Use it from your connected AI after setup.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the 说说笔记 Skill skill

What this skill tells your AI

The instructions your AI receives, as published by rcy1314/echo-noise in skill/SKILL.md and read by ahel’s review.

本 skill 仅保留一份，统一封装“说说笔记”的两种调用模式：

  • API 模式：默认模式，项目默认部署通常不启用 MCP 时使用
  • MCP 模式：只有在环境明确已启用 MCP 时才使用

核心要求：

  • 不默认假设 MCP 已开启
  • 优先保证功能可用，再选择更合适的调用通道
  • 对用户隐藏底层差异，统一输出整理后的中文结果

何时调用

当用户有以下需求时，应调用本 skill：

  • 发布一条说说或笔记
  • 搜索、筛选、分页浏览内容
  • 查看某条内容详情
  • 更新、删除、置顶内容
  • 登录后台、获取或重建 token
  • 查询状态、前端配置、发布日历、RSS
  • 排查 API 或 MCP 是否可用

配置驱动（推荐）

为避免每次改文档，建议优先使用同目录 config.json 作为运行参数来源。

优先级建议如下：

  1. 用户本轮对话明确指定（最高优先）
  2. skill/config.json 中的配置
  3. 文档默认值（最低优先）

推荐 AI 行为：

  • 开始执行前先读取 skill/config.json
  • 将 baseUrl 作为 API 基础地址
  • 将 mcpBaseUrl 作为 MCP HTTP/SSE 验证地址
  • defaultMode=api 时默认走 API
  • 当 autoFallbackToApi=true 且 MCP 不可用时自动回退 API

首次安装自动引导（无需用户先说固定指令）

当满足以下任一条件时，AI 应进入“配置引导模式”并先提问，不直接执行写操作：

  • baseUrl 为空
  • baseUrl 仍是占位值（如 your-domain.com）
  • onboarding.completed=false 且 onboarding.enabled=true

引导模式建议提问顺序：

  1. 你的站点域名是什么（如 https://example.com）？
  2. 本次默认走 API 还是 MCP？
  3. 是否启用“MCP 失败自动回退 API”？

引导完成后，AI 应在后续对话中默认沿用本轮确认的配置，并在必要时提醒你同步更新 skill/config.json。

默认工作模式

默认决策顺序必须如下：

  1. 先判断是否已明确可用 MCP
  2. 若未明确启用 MCP，则直接走 API 模式
  3. 若已明确启用 MCP，再根据任务选择 MCP 模式
  4. MCP 失败时，若等价 API 可用，应回退到 API

以下情况视为“已明确启用 MCP”：

  • 用户明确说明已配置 MCP 客户端
  • 环境已提供可调用的 MCP server 配置
  • 已知服务运行在 final-mcp、独立 mcp 容器，或已暴露 /mcp/* 端点
  • 已验证 GET /mcp/tools 或 GET /mcp/sse 可访问

以下情况一律按“未启用 MCP”处理：

  • 普通默认部署
  • docker-compose.yml 使用主应用 target: final
  • 只有后端服务可访问，但未确认 1315 或 MCP 子进程

双模式能力总览

API 模式

API 模式为默认首选，直接调用后端 HTTP 接口。

  • 状态：GET /api 或 GET /api/status
  • 配置：GET /api/frontend/config 或 GET /api/settings
  • 分页：GET /api/messages/page 或 POST /api/messages/page
  • 详情：GET /api/messages/:id
  • 搜索：GET /api/messages/search
  • 标签内容：GET /api/messages/tags/:tag
  • 标签列表：GET /api/messages/tags
  • 日历：GET /api/messages/calendar
  • RSS：GET /rss
  • 登录：POST /api/login
  • 发布：POST /api/messages 或 POST /api/token/messages
  • 更新：PUT /api/messages/:id 或 PUT /api/token/messages/:id
  • 删除：DELETE /api/messages/:id 或 DELETE /api/token/messages/:id
  • 置顶：PUT /api/messages/:id/pin 或 PUT /api/token/messages/:id/pin
  • 读取 token：GET /api/user/token
  • 重建 token：POST /api/user/token/regenerate
  • 更新设置：PUT /api/settings 或 PUT /api/token/settings

MCP 模式

MCP 模式仅在确认已启用后使用，工具入口位于 mcp/server.js。

  • search / 搜索
  • page / 页面
  • message / 消息
  • publish / 发布 / 笔记 / 说说 / 说说笔记
  • delete / 删除
  • update / 更新
  • pin / 置顶消息
  • settings / 设置
  • status / 状态
  • calendar / 日历
  • config / 配置
  • login / 登录
  • token / 令牌
  • rss / RSS

模式选择规则

一般规则

  • 能用 API 直接完成的任务，默认优先 API
  • 只有在 MCP 已明确可用时，才使用 MCP
  • 不要为了“统一接口”而强行要求用户先启用 MCP
  • 若用户请求的是“给 AI 客户端接入技能自动调用”，再优先介绍 MCP 模式

读取类任务

以下任务默认走 API：

  • 搜索
  • 分页
  • 查看详情
  • 查询状态
  • 查询配置
  • 查询日历
  • 获取 RSS

写入类任务

以下任务在默认情况下也应优先 API：

  • 发布
  • 更新
  • 删除
  • 置顶
  • 修改设置
  • 登录并获取 token

只有当 AI 客户端已经接好 MCP，且用户希望通过 MCP 工具统一操作时，才切到 MCP。

认证规则

API 模式认证

读取接口通常无需认证：

  • /api
  • /api/status
  • /api/frontend/config
  • /api/settings
  • /api/messages/page
  • /api/messages/:id
  • /api/messages/search
  • /api/messages/calendar
  • /rss

写接口需要认证，分两类：

  • 会话认证：/api/login 成功后，调用 /api/messages/*、/api/settings、/api/user/token*
  • Token 认证：调用 /api/token/messages*、/api/token/settings

建议：

  • publish、delete 可优先使用 token 路由
  • update、pin、settings 更稳妥的方式是先登录，使用会话路由
  • 读取 token 与 重建 token 必须先登录

MCP 模式认证

  • search、page、message、status、calendar、config、rss 通常无需认证
  • publish、delete 可使用 NOTE_TOKEN 或已登录会话
  • update、pin、settings 应优先先执行 login
  • token 必须先执行 login

推荐执行流程

搜索与浏览

  1. 若未确认 MCP，直接调用 API 搜索或分页接口
  2. 用户提供 id 时，直接查详情
  3. 用户提供标签时，优先用标签或搜索接口
  4. 返回结果时整理为中文摘要

推荐输出字段：

  • id
  • 发布时间
  • 作者
  • 摘要
  • 图片数量或置顶状态（如有）

发布

  1. 先判断用户要发布的内容类型
  2. 再判断当前可用的是 API 还是 MCP
  3. 写入前确认认证方式
  4. 发布后返回成功结果与内容标识

内容类型建议：

  • 文本：type: "text"
  • Markdown：type: "markdown"
  • 单图：type: "image"
  • 多图：type: "multipart"

更新、删除、置顶

  1. 先通过搜索或详情确认目标
  2. 对危险操作再次确认目标 id
  3. 选择可用认证方式执行写操作
  4. 必要时重新读取结果确认变更已生效

API 参数速查

搜索

请求：

GET /api/messages/search?keyword=欢迎&page=1&pageSize=10

说明：

  • 也可使用 query 作为关键词字段
  • 关键词以 # 开头时，可按标签语义理解
  • 未提供关键词时更适合改用分页接口

分页

GET /api/messages/page?page=1&pageSize=10

或：

POST /api/messages/page
{
  "page": 1,
  "pageSize": 10
}

详情

GET /api/messages/123

发布文本

POST /api/token/messages
{
  "type": "text",
  "content": "今天完成了 skill 配置"
}

发布 Markdown

POST /api/token/messages
{
  "type": "markdown",
  "content": "# 标题\n正文内容"
}

发布单图

POST /api/token/messages
{
  "type": "image",
  "image": "https://example.com/a.jpg",
  "content": "图片配文"
}

发布多图

POST /api/token/messages
{
  "type": "multipart",
  "images": [
    "https://example.com/a.jpg",
    "https://example.com/b.jpg"
  ],
  "content": "多图说明"
}

更新

PUT /api/messages/123
{
  "content": "更新后的内容"
}

删除

DELETE /api/messages/123

置顶

PUT /api/messages/123/pin
{
  "pinned": true
}

登录

POST /api/login
{
  "username": "admin",
  "password": "your_password"
}

获取 token

GET /api/user/token

重建 token

POST /api/user/token/regenerate

MCP 参数速查

搜索

{
  "query": "欢迎",
  "page": 1,
  "pageSize": 10
}

分页

{
  "page": 1,
  "pageSize": 10
}

详情

{
  "id": "123"
}

发布

{
  "type": "text",
  "content": "今天完成了 skill 配置"
}

更新

{
  "id": "123",
  "content": "更新后的内容"
}

删除

{
  "id": "123"
}

置顶

{
  "id": "123",
  "pinned": true
}

登录

{
  "username": "admin",
  "password": "your_password"
}

安装说明

本目录为独立 skill 目录，可单独复制到本地 AI 客户端技能目录中使用。

建议目录结构：

skill/
    SKILL.md
    USAGE.md

安装步骤：

  1. 复制 skill 整个目录
  2. 保持主 skill 文件名为 SKILL.md
  3. 将配套说明文档保留为 USAGE.md
  4. 重启或刷新 AI 客户端技能索引

建议同时保留并按需修改：

  • config.json：集中维护域名、默认模式与认证偏好

API 使用建议

若你只是部署了默认项目，通常直接使用 API 即可。

推荐先定义：

export BASE_URL="https://your-domain.com"
export MCP_BASE_URL="https://your-domain.com"

基础地址示例：

  • 本地：http://localhost:1314
  • 线上：https://your-domain.com

建议优先检查：

  • GET /api/status
  • GET /api/messages/page?page=1&pageSize=5
  • GET /rss

MCP 使用建议

MCP 不是默认前提，需要单独启用后再使用。

本地 Node 运行

cd /Library/Github/Ech0-Noise/mcp
npm install

客户端配置思路：

{
  "mcpServers": {
    "shuoshuo-notes": {
      "command": "node",
      "args": ["/Library/Github/Ech0-Noise/mcp/server.js"],
      "env": {
        "NOTE_HOST": "https://your-domain.com",
        "NOTE_HTTP_PORT": "0",
        "NOTE_TOKEN": "你的后台token"
      }
    }
  }
}

独立容器运行

若使用独立 mcp 服务或 final-mcp 目标，可通过 /mcp/* 端点验证。

curl "$MCP_BASE_URL/mcp/tools"
curl -N "$MCP_BASE_URL/mcp/sse"

输出要求

使用本 skill 时，建议：

  • 默认先说明当前走的是 API 还是 MCP
  • 搜索结果使用中文整理，不直接裸露原始 JSON
  • 发布、更新、删除、置顶后明确说明是否成功
  • 出现失败时指出是认证失败、参数错误、接口不可用，还是 MCP 未启用
  • 对删除、覆盖更新、置顶切换等操作先确认目标对象

常见问题

为什么不能默认走 MCP

因为项目默认部署并不等于默认启用 MCP。

已知依据：

  • docker-compose.yml 中主应用使用 target: final
  • README.md 明确区分了不带 MCP 的 final 与带 MCP 的 final-mcp

API 可用但 MCP 不可用

这属于正常情况。

处理方式：

  • 继续走 API 模式
  • 不要要求用户必须先部署 MCP

写操作 401 或 403

处理方式：

  • 检查是否已登录
  • 检查 token 是否有效
  • 区分当前走的是会话路由还是 token 路由

MCP 端口占用

若遇到 EADDRINUSE：

  • 将 NOTE_HTTP_PORT 设为 0
  • 或更换未占用端口

配套文档

同目录已提供以下配套文档：

  • USAGE.md：完整使用说明主文档，包含快速开始、模式判断、认证流程、操作流程、排障与最佳实践
  • EXAMPLES.md：可直接照抄的 API / MCP 示例、响应模板、排错示例

参考位置

  • 项目说明：README.md
  • MCP 说明：mcp/README.md
  • API 路由：internal/routers/routers.go
  • MCP 服务入口：mcp/server.js

Signals

GitHub stars
57
Forks
9
Last commit
Jul 2026
Advanced
Catalog kind
skill
Gateway key
shuoshuo-notes
Source
github.com/rcy1314/echo-noise

github.com/rcy1314/echo-noise

More in Search

azure-ai
Skill · microsoftflags
Skill · verceldashboard
Skill · nexu-ioexa-search
Skill · affaan-madding-mcp-store-servers
Skill · posthoglark-im
Skill · larksuite