Agent Interface

AI Agent 接口

让任意第三方 AI（Claude / ChatGPT / Codex / Cursor / TRAE 等）通过 /api/agent/* 通道操作你的 blog 知识库——查目录、列文章、读原文、发文、改文、移动、批量归档、软删除与回收站自救。

安装指引

1

准备凭证

确保你的 blog 已部署在 Cloudflare Pages，并在环境变量里设置了 AGENT_TOKEN。这个 token 是 AI 代发的"密钥"，需要提供给 AI 部署 skill。
2

复制提示词，发给 AI 以部署 blog skill

把下方提示词整段复制，粘贴给任意第三方 AI。AI 会自动从你的 blog 站点下载 /skills/blog/SKILL.md 并部署到本地、引导你填入站点地址和 token、做连通性验证。提示词只含部署指令，skill 内容由 AI 在线下载。

想自己先看一眼 skill 内容？下方「部署提示词」区域右侧有 下载 SKILL.md 和 在新窗口预览 按钮，点一下即可获取完整的 skill 定义（凭证配置、API 模板、模块路由、端点示例、工作流等）。

部署提示词

下载 SKILL.md 在新窗口预览

请帮我部署一个名为 "blog" 的 skill，让我之后能通过 /api/agent/* 通道操作用户的个人 blog 知识库（查目录/列文章/读原文/发文/改文/移动/批量/软删除/回收站自救）。

### 部署步骤

1. 下载 skill 文件：先问我要 blog 站点地址（形如 https://xxx.pages.dev），然后用 curl 从 {站点地址}/skills/blog/SKILL.md 下载 skill 内容，保存到 ~/.config/skills/blog/SKILL.md（目录不存在就 mkdir -p 创建）。下载后读一遍，确认是完整的 skill 定义。

2. 配置凭证：问我要 AGENT_TOKEN（在 Cloudflare Pages 环境变量里设置的那个），然后写入 ~/.config/blog/base_url（内容是站点地址）和 ~/.config/blog/agent_token（内容是 token），目录权限 700，文件权限 600。或问我是否倾向用环境变量（BLOG_BASE_URL / BLOG_AGENT_TOKEN）。

3. 连通性验证：调用 GET {站点地址}/api/agent/folders，带 header Authorization: Bearer {token}：
   - 返回 200（哪怕是空数组 []）→ 告诉我"部署成功，已能访问你的 blog 知识库"，并列出根目录下有哪些文件夹
   - 返回 401 → 提示我 AGENT_TOKEN 不对
   - 连不上 → 提示我检查站点地址

4. 安全要求：全程不要把我的 AGENT_TOKEN 回显在对话里，也不要写进任何日志文件。

### skill 内容来源

skill 的完整定义（凭证配置、API 调用模板、模块路由表、各端点示例、工作流、权限边界等）都在下载下来的 SKILL.md 里。下载后请阅读并遵循它。后续我让你操作 blog 时，按 SKILL.md 里的模块决策表和端点示例来调用。

如果下载失败（404 或网络错误），告诉我去检查 blog 站点是否已部署最新版本（站点需要有 /skills/blog/SKILL.md 这个静态文件）。

核心功能

查看知识库

目录树、文件夹统计、文章列表多维筛选、读原文、全文检索。AI 改文前先读，精确修改。

代发与更新

代发新文章、改内容、移动归类、改状态/标签。folder_path 自动逐级建层，无需手动建目录。

批量操作

批量移动/改状态/改标签文章，批量移动文件夹。上限 100，原子性强，减少 90% 往返。

软删除与回收站

所有删除均进回收站，AI 可查看并还原。设计原则：AI 的所有操作均可逆，不可逆操作留给人工。

增量同步

updated_since/updated_until 按更新时间自由筛选，AI 自由传时间戳，方便做增量同步。

安全边界

token 不入日志不回显，仅发往你的 blog 站点。物理删除/清空回收站不给 AI，需人工操作。

使用场景

精确修改

"帮我把上次那篇 Cloudflare 部署笔记的结尾补一段注意事项"

AI：已搜索定位到该文，读取原文后追加注意事项段落并 PATCH 更新。

整理归类

"把技术下所有关于 AI 的文章归到技术/AI 子文件夹"

AI：已列出相关文章，批量移动到技术/AI（文件夹自动建层）。

批量归档

"把 2023 年的所有草稿归档到归档/2023"

AI：已按时间筛选并批量移动 N 篇草稿到归档/2023。

误删自救

"刚刚删错了，把那个文件夹找回来"

AI：已查看回收站找到该项，调用 restore 还原文件夹及其子项。

代发新文

"整理这份报告，生成投资笔记，发到技术/行业研究"

AI：已生成笔记内容，通过 POST 代发，folder_path 自动建层归档。

API 端点速查

操作	方法	路径
目录树	`GET`	`/api/agent/folders`
文件夹统计	`GET`	`/api/agent/folders/:id/stats`
文章列表	`GET`	`/api/agent/articles`
文章详情	`GET`	`/api/agent/articles/:slug`
全文检索	`GET`	`/api/agent/search?q=`
代发文章	`POST`	`/api/agent/articles`
更新文章	`PATCH`	`/api/agent/articles/:slug`
软删除文章	`DELETE`	`/api/agent/articles/:slug`
批量更新文章	`POST`	`/api/agent/articles/batch`
新建/改/删文件夹	`POST/PATCH/DELETE`	`/api/agent/folders/:id`
批量移动文件夹	`POST`	`/api/agent/folders/batch`
查看回收站	`GET`	`/api/agent/recycle`
还原回收站	`POST`	`/api/agent/recycle/restore`

下一步

部署完成后，对那个 AI 说"帮我把这篇博客结尾补一段"、"把技术下 AI 文章归到子文件夹"、"把 2023 年的草稿归档"之类的话，它就会用这个 skill 操作你的 blog。完整接口细节见管理后台与项目 README。