Typecho Blog Publish

通过 XML-RPC 自动发布文章到 Typecho 博客。支持文件读取、草稿模式、标签管理、智能配图。

Security Scan

The skill's code, docs, and runtime instructions are consistent with a Typecho XML-RPC blog publisher; requested credentials and binaries match the stated purpose, but review defaults and test safely before use.

Purpose & Capability

Name/description (publish to Typecho via XML-RPC) match the shipped scripts (publish_post.py, publish_v2_full.py, upload_image.py, manage.py, etc.). Required binary (python3) and primaryEnv (BLOG_PASSWORD) are appropriate and expected for this functionality. No unrelated cloud credentials or unexpected system paths are requested.

Instruction Scope

SKILL.md and other docs instruct the agent to read Markdown files, a local .env, run the included Python scripts, upload images, download images from external image services (Pexels/Unsplash/LoremFlickr/etc.), and call the Typecho XML-RPC endpoint — all within the declared purpose. However, the documentation is inconsistent about publish defaults: some docs state 'default draft mode' while QUICKSTART/README_V2 mention 'v2.0 default directly publish (immediate)'. This mismatch could lead to unexpected public posts if a user assumes draft-only behavior. Also note that the scripts perform network calls (blog server + third-party image hosts) and will read/write local files (logs, temp images).

Install Mechanism

No install spec is provided (instruction-only install), and all code is included in the package. There are no network install steps that would download and execute arbitrary archives during install, so installation risk is low. The package does include many scripts and example articles which will be present on disk when installed.

Credentials

The skill requires the blog password (BLOG_PASSWORD) and optionally BLOG_URL, BLOG_USERNAME, BLOG_XMLRPC — these are proportionate to an XML-RPC publisher. There are no unrelated secrets requested. The skill will read a local .env and local article files (expected).

Persistence & Privilege

Flags show always:false and model invocation allowed (default). The skill does not request permanent platform-wide privileges. Scripts will write local logs and can create/delete posts via XML-RPC (manage.py supports deletion) — appropriate for a blog management tool but worth being aware of.

Assessment

This package is coherent with its stated purpose, but take these precautions before installing or running it: 1) Treat BLOG_PASSWORD as a high-value secret — prefer an app-specific password and store .env with strict permissions (chmod 600). 2) Verify the publish mode in your installed copy: test on a staging Typecho instance (set BLOG_URL to a test server) to confirm whether scripts publish immediately or only save drafts, because docs conflict about the default. 3) Audit the publish and upload scripts (publish_post.py, publish_v2_full.py, upload_image.py, manage.py) to confirm they call only your blog's XML-RPC endpoint and to understand delete behavior. 4) Be aware the skill downloads images from external hosts (Unsplash/Pexels/LoremFlickr/etc.) and uploads binaries to your blog — check licensing and network use. 5) Run initial tests against a non-production blog to avoid accidental public posts or unwanted deletions. 6) If you want extra safety, remove or disable any automatic 'publish now' code paths or add a forced --draft flag in the scripts before use.

Typecho 博客发布技能

使用此技能来自动发布文章到你的 Typecho 博客。

⚠️ 发布流程规范（铁律！）

重要提示：发布完成≠工作完成！必须像真实用户一样检查实际效果！

发布前检查清单（必须逐条核对！）

1. 配图要求 ✅ 必需（血泪教训！）

• 必须包含至少一张配图（不能纯文字）
• 配图应与文章主题相关
• 图片应插入在文章开头或前 3 段内
• 必须使用完整的绝对 URL（如 http://yuanblog.tk:9980/usr/uploads/2026/03/xxx.png）
• 禁止使用相对路径（如 /upload/2026/03/xxx.png 会失败！）
• 使用 upload_image.py 上传后，复制返回的完整 URL
• 配图命令示例：

  # 1. 上传图片，获取完整 URL
  python3 scripts/upload_image.py /path/to/screenshot.png
  # 返回：http://yuanblog.tk:9980/usr/uploads/2026/03/2512184318.png
  
  # 2. 在文章中使用完整 URL
  # ![描述](http://yuanblog.tk:9980/usr/uploads/2026/03/2512184318.png)
  
  # 智能搜索配图（基于主题关键词）
  python3 scripts/smart_image.py "ADB Android 技术"
  

2. YAML 头部格式 ✅ 必需

• 文章必须包含标准 YAML front matter 头部
• 使用 --- 包裹头部信息
• 必须包含 title（标题）字段
• 必须包含 categories（分类）字段
• 必须包含 tags（标签）字段
• 格式示例：

  ---
  title: 文章标题
  categories: 技术
  tags: 标签 1, 标签 2
  ---
  

3. 发布命令 ✅ 必需

• 使用 --file 参数从文件发布（保留 YAML 头部）
• 不要直接使用标题 + 内容方式发布
• 命令示例：

  python3 scripts/publish_post.py --file article.md
  

4. 验证步骤 ✅ 必需（发布后必须检查！铁律！）

• 立即在浏览器中打开文章链接（不要只看后台返回的"发布成功"）
• 检查标题是否正确显示（不能是文件名）
• 检查配图是否正常显示（不能是裂开的图标）
• 右键点击图片→复制图片地址（验证是否为完整 URL）
• 检查分类和标签是否正确显示
• 检查内容格式是否正常（无乱码、无错位）
• 如发现问题，立即删除并重新发布（不凑合、不侥幸）

验证命令：

# 检查文章中的图片路径
curl -s "文章 URL" | grep -o 'img src="[^"]*"'
# 应该显示完整 URL，如 http://yuanblog.tk:9980/usr/uploads/...
# 如果显示 /upload/... 说明路径错误！

铁律：不检查就汇报=找死！

• ❌ 禁止只看后台返回就以为完成
• ❌ 禁止不实际访问文章就汇报"已完成"
• ❌ 禁止发现问题不处理就交差
• ✅ 必须像真实用户一样检查
• ✅ 发现问题立即修复
• ✅ 确保用户看到的是完美效果

血的教训（2026-03-31）：

• 第一次发布：标题显示为文件名（❌ 未发现）
• 第二次发布：配图路径错误，图片不显示（❌ 未检查）
• 第三次发布：亲自检查后发现问题，修复（✅）
• 教训：不亲自检查就不知道问题在哪！发布完成≠工作完成！

配置

在 .env 文件中配置以下环境变量：

变量	说明	默认值
BLOG_URL	博客地址	http://yuanblog.tk:9980
BLOG_USERNAME	博客用户名	admin
BLOG_PASSWORD	博客密码（必需）	-
BLOG_XMLRPC	XML-RPC 路径	/index.php/action/xmlrpc

使用方法

1. 发布文章（推荐方式）

# 从文件发布（保留 YAML 头部）
python3 {baseDir}/scripts/publish_post.py --file article.md

# 保存为草稿
python3 {baseDir}/scripts/publish_post.py --file article.md --draft

2. 智能配图与上传

# 智能搜索配图（基于主题关键词）
python3 {baseDir}/scripts/smart_image.py "AI 技术 未来"

# 上传图片到博客媒体库
python3 {baseDir}/scripts/upload_image.py image.jpg

# 从 URL 下载并上传图片
python3 {baseDir}/scripts/upload_image.py --url "https://example.com/image.jpg"

3. 批量发布

# 批量发布草稿箱文章
python3 {baseDir}/scripts/batch_publish.py

# 管理文章（查看、删除）
python3 {baseDir}/scripts/manage.py

完整发布流程

步骤 1: 准备文章内容

创建 Markdown 文件，包含 YAML 头部：

---
title: 文章标题
categories: 技术
tags: 标签 1, 标签 2
---

这里是正文内容...

步骤 2: 智能配图

python3 scripts/smart_image.py "文章主题关键词"

或在文章中使用图片语法：

![描述](image.jpg)

步骤 3: 发布文章

python3 scripts/publish_post.py --file article.md

步骤 4: 验证发布结果

1. 访问返回的文章链接
2. 检查标题、配图、标签是否正确
3. 如有问题，删除文章并重新发布

错误处理

常见问题

问题 1: 标题显示为文件名

• 原因：YAML 头部格式错误或不存在
• 解决：确保使用标准 YAML 格式，用 --- 包裹

问题 2: 没有配图或图片不显示

• 原因：使用了相对路径（如 /upload/xxx.png）
• 解决：必须使用完整 URL（如 http://yuanblog.tk:9980/usr/uploads/xxx.png）
• 验证：右键图片→复制图片地址，检查是否是完整 URL

问题 3: 链接 404

• 原因：未开启伪静态
• 解决：使用正确链接格式 http://blog/index.php/archives/ID/

血泪教训（2026-03-31 实战总结）

教训：配图路径错误导致图片不显示

• 错误做法：![描述](/upload/2026/03/adb_unlock_demo.png)
• 正确做法：![描述](http://yuanblog.tk:9980/usr/uploads/2026/03/2512184318.png)
• 原因：Typecho 不支持相对路径的图片 URL
• 解决方案：上传后复制完整 URL，直接写在文章中

相关文件

• publish_post.py - 主要发布脚本
• smart_image.py - 智能配图脚本
• upload_image.py - 图片上传脚本
• batch_publish.py - 批量发布工具
• manage.py - 文章管理工具

最佳实践

1. 始终使用 YAML 头部 - 确保标题、分类、标签正确解析
2. 必分配图 - 文章开头插入相关图片
3. 使用 --file 参数 - 保留完整的元数据
4. 发布后立即验证 - 检查标题、配图、标签
5. 及时清理错误文章 - 发现问题立即删除重发

---

维护者：团子 🌟
版本：1.1.0
更新时间：2026-03-31