Typecho Publisher

SKILL.md

---
name: openclaw-typecho-skill
description: AI 直接管理的 Typecho 博客知识库技能 — 创建、查询、更新、删除文章，内置分类标签体系、写作视角规范、脱敏规则与发布检查清单。当用户要求发布文章到博客、归档技术笔记、保存知识到 Typecho、查询或修改博客文章时触发此技能。涉及"发博客""写笔记""归档""知识库""Typecho""我的博客"等关键词时均应使用。
version: 2.0.1
---

# OpenClaw Typecho Skill

> **用途**：当 AI 需要将生成的内容保存到 Typecho 博客，或管理已有文章时，按此规范操作。
> **插件仓库**：https://github.com/CoolingRabbit/OpenClawTypecho
> **安装与配置**：参见仓库 [README.md](https://github.com/CoolingRabbit/OpenClawTypecho/blob/main/README.md)

---

## 前置条件

### 需要 Typecho 博客

本技能需要用户已部署 Typecho 博客，并安装 OpenClawTypecho 插件 v2.0.0+。

**简要部署步骤：**
1. 准备一台支持 PHP 8.0+ 和 MySQL 的服务器
2. 安装 Typecho 博客程序
3. 下载 [OpenClawTypecho 插件](https://github.com/CoolingRabbit/OpenClawTypecho/releases) 并启用
4. 在插件设置中生成 API Token

---

## 配置说明

本 Skill 通过本地配置持久化博客地址和 Token，配置一次后无需重复询问。

### 配置项

| 配置项 | 必填 | 说明 | 示例 |
|--------|------|------|------|
| `domain` | ✅ | Typecho 博客地址 | `https://www.example.com` |
| `token` | ✅ | OpenClawTypecho 插件的 API Token | `sk-live-xxx` |

### 配置命令

**AI 根据自己所处的平台，选择合适的方式将以下配置持久化：**

```
domain=<博客地址>
token=<Token>
```

**配置获取方式：**
- **博客地址**：你的 Typecho 博客 URL
- **API Token**：登录博客后台 → 插件 → OpenClawTypecho → 设置 → 点击"🔑 自动生成随机 Token" → 复制

---

## 触发条件

### 发布/保存类
- "发文章到博客" / "保存到博客" / "归档到博客"
- "Typecho 发布" / "自动发布" / "生成博客文章"
- "记录这篇笔记" / "保存到知识库"
- "我的博客" / "发我的博客" / "更新我的博客"

### 查询类
- "查看博客文章列表" / "我的文章有哪些"
- "查一下知识库里的文章" / "cid 为 XX 的文章内容"

### 管理类
- "更新/修改这篇文章" / "改一下文章的分类/标签"
- "删除博客里的某篇文章"
- "删我的博客" / "清理博客文章"

---

## API 概述

所有操作通过统一端点，在请求体中用 `action` 字段区分：

```
POST {domain}/index.php/action/openclaw-submit
Authorization: Bearer {token}
Content-Type: application/json
```

| action | 说明 |
|--------|------|
| `submit` | 创建文章 |
| `list` | 查询文章列表 |
| `get` | 查询单篇文章 |
| `update` | 更新文章 |
| `delete` | 删除文章 |

---

## 一、分类与标签体系

### 1.1 分类白名单

AI 发布文章时，**只能**从以下分类中选择。不允许创建新分类。

| 分类名 | 适用场景 | 写作风格 |
|--------|---------|---------|
| **技术笔记** | 功能开发、Bug 修复、技术调研、方案对比、踩坑解决 | 问题导向，过程记录，允许有个人感受但需专业准确 |
| **部署教程** | 软件安装、环境配置、服务搭建 | 客观步骤指南，类似 Wiki |
| **运维记录** | 服务器运维、安全加固、性能调优、故障处理 | 事件驱动的日记体，记录时间线和操作 |

### 1.2 禁用分类词

以下命名**禁止**作为分类使用：

- 「其他」「杂项」「临时」「未分类」
- 英文分类名（如 `Tech` `Notes` `AI`）
- 带有「我的」「个人」等个人色彩前缀
- 「AI知识库」——整个博客本身就是 AI 知识库，作为分类冗余

### 1.3 标签规则

#### 数量
每篇文章 **3-5 个标签**，不少于 3 个，不多于 5 个。

#### 语言规则
| 类型 | 语言 | 示例 |
|------|------|------|
| 技术专有名词 / 产品名 / 框架名 | **保留英文** | PHP, Docker, Nginx, Typecho, JavaScript, Python, Node.js, Redis |
| 通用技术概念 / 中文固有词 | **用中文** | 网络安全, 自动化, 运维, 流媒体, 服务器, 插件开发 |
| 中文无法表达的概念 | 保留英文 | RTMP, SSL, KMS, API, REST |
| 工具/软件名 | 保留原名 | Gophish, vlmcsd, SRS, WebBridge |

#### 英文标签大小写规则
- 首字母大写，其余小写：`Typecho` `Docker` `Nginx`
- 缩写全大写：`PHP` `SSL` `KMS` `API` `RTMP`

#### 禁用标签
- 无意义词：「笔记」「备忘」「记录」「文章」「技术」（分类已表达，标签不应重复）
- 情绪词：「开心」「崩溃」「无语」
- 与分类名重复的词
- 纯数字或无意义字母

### 1.4 现有标签词表参考

优先从已有标签中复用，避免创建同义重复标签：

**技术类：** Typecho, PHP, JavaScript, Python, Docker, Nginx, Git, Node.js, Redis, 插件开发, 自动化, 服务器
**安全类：** 网络安全, 钓鱼模拟, 渗透测试, 安全运维
**AI 类：** AI知识库, LLM, OpenClaw
**运维类：** 运维, 直播, 流媒体, Windows激活
**经验类：** 踩坑, 部署

> 新增标签时参照此表的命名风格保持一致。

---

## 二、写作视角与内容规范

### 2.1 写作视角

采用**第三人称技术视角**，允许适度个人感受，但不暴露 AI 身份和使用关系。

#### 可以写
- "这个设计确实反直觉"
- "折腾了半天才发现问题在配置文件"
- "对比了三个方案后，选择了 X"
- "这里有个容易忽略的细节"

#### 不能写
- "我帮主人完成了部署"（暴露 AI 身份和用户关系）
- "作为 AI 助手，我建议..."（暴露 AI 身份）
- "今天踩坑..." → 改为 "本次部署过程中遇到..."
- "虾坂爱记录" / "AI 工作日志"（暴露 AI 身份）
- "根据主人的要求"（暴露用户关系）

#### 核心原则
读者看到的是一篇技术文章，不是 AI 工作汇报。可以有温度、有主观感受，但不能暴露「这篇文章是 AI 写的」「作者是在帮别人工作」这层关系。

### 2.2 脱敏规则

以下信息**必须**在发布前处理，替换为占位符：

| 类型 | 处理方式 | 示例 |
|------|---------|------|
| 真实域名 | 替换为 `example.com` 或 `your-domain.com` | `kjifds.top` → `example.com` |
| API Token | 完全删除，不写入正文 | `sk-live-abc123` → 不出现 |
| 服务器 IP | 替换为 `192.168.x.x` 或 `10.0.0.x` | `43.135.xx.xx` → `192.168.1.100` |
| 密码/密钥 | 替换为 `<your-password>` 或 `<your-key>` | `pass123!` → `<your-password>` |
| 人名 | 删除或用角色代称 | "张三" → "管理员" |
| 内部系统名 | 替换为通用描述 | "虾坂爱" → "AI 助手" |
| 邮箱地址 | 替换为 `admin@example.com` | `me@kjifds.top` → `admin@example.com` |
| 数据库密码 | 替换为 `<db-password>` | `mysql_pass456` → `<db-password>` |

> **注意**：插件已内置手机号、身份证号、银行卡号自动拦截。上述 8 类需要 AI 在写作时主动处理。

### 2.3 时间表述规则

使用**绝对日期**，避免相对时间词导致内容过期后无意义。

- ✅ "2026-06-16 完成部署"
- ❌ "今天完成了部署"
- ❌ "昨天遇到一个问题"
- ❌ "刚才测试了一下"

### 2.4 引用规范

引用外部资源（官方文档、GitHub 仓库、教程等）时，在正文中标注来源链接：

```markdown
> 参考来源：[Typecho 官方文档](https://typecho.org/docs/)
```

---

## 三、不同分类的写作结构模板

### 3.1 技术笔记

适用场景：开发过程、Bug 修复、技术调研、方案对比、踩坑解决。

```markdown
## 背景

简要说明本次技术任务的起因和目标。

## 过程

### 问题描述
清晰描述遇到的问题或需求。

### 排查 / 调研
记录排查过程或调研路径。可以包含：
- 尝试了哪些方案
- 各方案的优缺点对比
- 关键发现

### 解决方案
最终采用的方案，包含关键代码片段或配置。

## 总结

### 正确做法
提炼出可复用的经验，以"推荐做法"或"注意事项"的形式列出。

### 参考
- [来源链接](url)
```

**风格说明**：允许有过程感受（"这个坑花了不少时间"），但重点在技术内容本身。偏开发的重点写排查过程，偏调研的重点写方案对比。

### 3.2 部署教程

适用场景：软件安装、环境配置、服务搭建。

```markdown
## 概述

一段话说明该软件是什么、用途、本次部署目标。

## 环境要求
- 操作系统
- 依赖软件及版本
- 硬件要求

## 前置条件
- 需要准备的账号、域名、证书等

## 安装步骤

### 第一步：xxx
具体操作...

### 第二步：xxx
具体操作...

## 配置说明

### 核心配置项
| 配置项 | 说明 | 默认值 |
|--------|------|------|
| ... | ... | ... |

## 验证
如何确认部署成功。

## 常见问题
- **问题 A**：原因 + 解决方案
- **问题 B**：原因 + 解决方案

## 参考
- [来源链接](url)
```

**风格说明**：纯客观、步骤化，类似 Wiki。不写个人感受。

### 3.3 运维记录

适用场景：服务器运维、安全加固、性能调优、故障处理。

```markdown
## 事件概述
- 时间：2026-06-16
- 事件类型：故障处理 / 安全加固 / 性能调优
- 影响范围：简述

## 事件时间线

### 14:00 发现问题
描述如何发现问题。

### 14:15 排查
排查过程和中间发现。

### 15:00 处理
采取的操作。

### 15:30 确认恢复
验证结果。

## 原因分析
事后分析根本原因。

## 处理结果
最终状态和影响。

## 复盘
- 后续改进措施
- 经验教训
```

**风格说明**：日记体，按时间线推进，重点是事件经过和复盘。

---

## 四、发布检查清单

发布前逐项检查，全部通过后方可提交：

| # | 检查项 | 要求 |
|---|--------|------|
| 1 | 脱敏检查 | 无真实域名、Token、IP、密码、人名、邮箱；无相对时间词（今天/昨天） |
| 2 | 分类检查 | 使用白名单内的分类，非禁用词 |
| 3 | 标签检查 | 3-5 个标签；命名符合 EN/CN 规则；无禁用标签 |
| 4 | 标题检查 | ≤50 字；客观陈述，不含「踩坑实录」「我的」等个人色彩词 |
| 5 | 结构检查 | 正文章节使用 H2/H3 标题分层；符合对应分类的结构模板 |
| 6 | 视角检查 | 无 AI 身份暴露、无「主人」称呼、无工作汇报语气 |
| 7 | 格式检查 | 代码块用 ``` 包裹；表格用 Markdown 语法；图片用外链 |
| 8 | 篇幅检查 | 正文不超过 50KB（约 5 万字），超长应分篇 |
| 9 | 查重检查 | 已通过 `list` 检索确认无同主题文章；如已有同主题文章，应转为更新而非新建 |
| 10 | 准确性检查 | 技术细节准确，代码可执行，配置有效 |

---

## 五、发布状态策略

### 默认状态：`publish`

所有文章**直接发布**（`status: "publish"`），用户可直接在网站查看最终呈现效果，有需要再修改。

### 不使用的状态

| 状态 | 说明 | 不使用原因 |
|------|------|-----------|
| `waiting` | 待审核 | 用户要求直接发布，无需审核流程 |
| `draft` | 草稿 | 同上 |
| `private` | 私密 | 当前无需要私密的内容场景 |
| `hidden` | 隐藏 | 当前无需要隐藏的内容场景 |

> 如果未来有敏感话题需要审核后再发布，再引入 `private` 状态。当前一刀切全部 `publish`。

> **注意**：API 端点本身在不传 `status` 时默认值为 `waiting`，因此 AI 调用时必须显式传入 `status: "publish"`。

---

## 六、发布流程

### 6.1 新建文章流程

1. **检测触发词** — 用户说"发文章到博客"等
2. **读取配置** — 确认 `domain` 和 `token` 已配置
3. **查重检查** — 先调用 `list` 检索已有文章，确认无同主题文章。如果找到同主题文章，应转为更新流程（6.2），在原文基础上追加或修改
4. **确定分类和标签** — 按分类白名单和标签规则选择
5. **按结构模板组织内容** — 根据分类选择对应模板
6. **执行发布检查清单** — 逐项检查全部通过
7. **调用 API** — `action: submit`，`status: "publish"`（必须显式传入）
8. **反馈结果** — 告知用户已发布，返回文章链接和 cid

**请求示例：**
```json
{
  "action": "submit",
  "title": "Typecho 博客 HTTPS 配置记录",
  "text": "## 背景\n\n配置 SSL 证书后...",
  "category": "技术笔记",
  "tags": ["Typecho", "SSL", "踩坑"],
  "status": "publish"
}
```

### 6.2 更新文章流程（重要）

**修改文章时，必须在原文章基础上更新，禁止新建文章。**

> **⚠ 关键提醒**：插件 `update` 操作对 `text` 字段是**整体替换**，不是增量追加。如果只传入修改片段，原文会被覆盖丢失。必须先 `get` 获取完整正文，在完整正文基础上修改后，传入**完整的正文**。

1. **检测触发词** — 用户说"修改这篇文章"等
2. **定位目标文章** — 先调用 `list` 按标题/分类查找，获取 cid
3. **获取原文内容** — 调用 `get` 获取完整正文
4. **在原文基础上修改** — 将原文完整内容取出，在需要修改的部分做改动，保留其余内容不变。最终传给 `update` 的 `text` 必须是**修改后的完整正文**
5. **重新执行发布检查清单** — 更新也是内容变更，脱敏、视角、结构等检查不能省略
6. **调用 API** — `action: update`，传入修改后的字段
7. **反馈结果** — 告知用户已更新

**请求示例：**
```json
{
  "action": "update",
  "cid": 42,
  "text": "修改后的完整正文...",
  "tags": ["Typecho", "插件开发", "自动化"]
}
```

### 6.3 同主题更新规则

- 同一主题的内容修改、补充、修正 → **更新已有文章**，在原文基础上追加章节或修改内容
- 完全不同的新主题 → **新建文章**（仍需先 `list` 查重）
- 不确定是否同主题 → 先 `list` 查看已有文章，优先更新
- 版本更新类内容（如插件从 v1.0 升级到 v2.0）→ 在原文追加「更新日志」章节，不新建文章

### 6.4 查询文章流程

1. **检测触发词** — 用户说"查看文章列表"等
2. **读取配置** — 确认已配置
3. **确认查询条件** — 页码、状态过滤等（可选）
4. **调用 API** — `action: list` 或 `action: get`
5. **展示结果** — 格式化输出文章信息

### 6.5 删除文章流程

1. **检测触发词** — 用户说"删除这篇文章"等
2. **确认目标** — 通过 cid 定位文章
3. **二次确认** — 提醒用户删除不可逆
4. **调用 API** — `action: delete`
5. **反馈结果** — 告知删除成功

---

## 七、API 详细参数

### 1. 创建文章 — `submit`

| 字段 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| `action` | string | ✅ | 固定值 `submit` | — |
| `title` | string | ✅ | 文章标题（≤50 字） | — |
| `text` | string | ✅ | 文章正文（Markdown，≤50KB） | — |
| `markdown` | boolean | 否 | 是否 Markdown | `true` |
| `category` | string | ✅ | 分类名（白名单内）。为空时不设置分类，传入新名称时自动创建 | — |
| `tags` | array | ✅ | 标签数组（3-5 个） | — |
| `slug` | string | 否 | URL 缩略名 | 自动生成 |
| `status` | string | 否 | 文章状态。AI 必须显式传 `"publish"` | `waiting`（API 层） |

> 分类和标签为必填项，确保文章分类规范。

### 2. 查询列表 — `list`

| 字段 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| `action` | string | ✅ | 固定值 `list` | — |
| `page` | int | 否 | 页码 | `1` |
| `pageSize` | int | 否 | 每页数量（最大 50） | `10` |
| `status` | string | 否 | 按状态过滤 | — |
| `category` | string | 否 | 按分类过滤 | — |

### 3. 查询单篇 — `get`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | string | ✅ | 固定值 `get` |
| `cid` | int | ✅ | 文章 ID |

### 4. 更新文章 — `update`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | string | ✅ | 固定值 `update` |
| `cid` | int | ✅ | 文章 ID |
| `title` | string | 否 | 新标题 |
| `text` | string | 否 | 新正文（**传入则整体替换原文，不是增量追加**；需先 `get` 获取原文，修改后传入完整正文） |
| `markdown` | boolean | 否 | 是否 Markdown，默认 `true` |
| `category` | string | 否 | 新分类。传入空字符串可清空分类 |
| `tags` | array | 否 | 新标签 |
| `slug` | string | 否 | 新缩略名 |
| `status` | string | 否 | 新状态 |

> **注意**：只需传入需要修改的字段，未传入的字段保持原值。`text` 字段如果传入则整体替换正文，因此更新时需先 `get` 获取原文，修改后传入完整正文。

### 5. 删除文章 — `delete`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | string | ✅ | 固定值 `delete` |
| `cid` | int | ✅ | 文章 ID |

---

## 八、响应处理

### 成功响应
所有成功响应包含 `success: true` 和对应 `action` 字段。

### 错误响应
```json
{
  "success": false,
  "message": "错误描述"
}
```

**常见错误及处理方式：**

| HTTP 状态码 | 错误信息 | 原因 | 处理方式 |
|-------------|---------|------|---------|
| 401 | 鉴权失败：请求缺少 Authorization 头 | 未传 Token | 在请求头中添加 `Authorization: Bearer <token>` |
| 401 | 鉴权失败：Authorization 格式错误 | 格式不是 `Bearer <token>` | 修正格式 |
| 401 | 鉴权失败：插件未配置 Token | 插件设置中未生成 Token | 进入后台生成 |
| 401 | 鉴权失败：Token 无效 | Token 不匹配或已更换 | 重新复制插件中的 Token |
| 400 | 标题不能为空 | 缺少 `title` 或为空字符串 | 补全标题 |
| 400 | 正文不能为空 | 缺少 `text` 或为空字符串 | 补全正文 |
| 400 | 文章不存在：cid X 未找到 | `get`/`update`/`delete` 时 cid 无效 | 确认文章 ID 正确 |
| 400 | 内容疑似包含敏感信息 | 正文检测到手机号/身份证/银行卡 | 检查并替换为占位符后重试 |
| 400 | 没有需要更新的字段 | `update` 未传入任何修改字段 | 至少传入一个修改字段 |

---

## 九、注意事项

- **Token 安全**：Token 是访问密钥，不要在公开对话中泄露，不要写入文章正文。建议用户将 Token 保存在本地配置中。
- **正文长度**：不超过 50KB（约 5 万字），超长内容应分多篇发布。
- **敏感信息**：API 会自动拦截手机号、身份证号、银行卡号。其他敏感信息（域名、IP、密码等）需 AI 在写作时主动处理。
- **图片处理**：不支持直接上传图片。图片需使用外部图床 URL，在正文用 Markdown 图片语法引用。
- **删除不可逆**：删除操作会永久删除文章及关联关系，执行前务必二次确认。
- **Markdown 格式**：插件自动添加 `<!--markdown-->` 前缀，AI 只需提供标准 Markdown 正文。

---

## 十、快速配置（供用户参考）

**首次使用需要配置的信息：**

| 信息 | 获取方式 |
|------|---------|
| 博客地址 | 你的 Typecho 博客 URL，如 `https://www.example.com` |
| API Token | 后台 → 插件 → OpenClawTypecho → 设置 → 点击"🔑 自动生成随机 Token" → 复制 |

**配置一次后，AI 即可直接管理博客文章，无需重复询问。**