2025-12-04 更新 3 阅读

这不仅是一个好习惯，更是专业开发的必经之路！好记性不如烂笔头，一份清晰的文档能让这个功能在几年后依然为你服务。

因为你使用的是 腾讯云 COS，确实比自建服务器更稳，那我就放心了。

下面是为你量身定制的 《Typecho 智能碎碎念接口 v1.0 使用手册》。建议你把这段内容保存为 README.md 或者直接贴在你的 Notion/备忘录置顶位置。

📘 Typecho 智能碎碎念接口 v1.0 使用手册

核心功能：通过手机备忘录/快捷指令，向 Typecho 博客快速发送带图、带分类、带自定义字段的“碎碎念”动态。
最近更新：2025-12-04 (最终完美版)

1. 核心语法速查

我们在备忘录里写内容时，遵循以下规则，脚本会自动解析。

📝 基础格式

这里写正文内容...
这里是第二段...
#标签1 #标签2
  • 效果：发布一篇纯文字碎碎念，标签自动关联。

🖼️ 发送图片（支持相册拼图）

关键点：链接不要手动换行，脚本会自动处理为“紧凑模式”，方便前端 CSS 做九宫格或相册布局。

今天天气真好，出门扫街！

https://cos.example.com/img1.jpg https://cos.example.com/img2.jpg
https://cos.example.com/img3.jpg
  • 逻辑：脚本识别 URL 后会自动转换为 ![]() 格式，且不强制插入换行符。

📂 指定分类（@cate）

如果不指定，默认归类到 ID=1 的分类下。

@cate:摄影
今天去拍了一组人像...
  • 逻辑：自动查找名为“摄影”的分类，如果没有会自动创建。

⚙️ 自定义字段（@key:value）

用于给文章添加额外的属性（如心情、天气、位置等），方便前端调用显示。

@mood:开心
@weather:晴朗
@location:上海

今天心情不错！
  • 效果：文章会多出 mood, weather, location 三个自定义字段。

2. 典型场景示例

场景 A：随手记（最简单）

刚才突然想到一个好点子，关于博客的交互设计... #想法
结果：归入默认分类，标签为“想法”，标题为“202x年xx月xx日 xx:xx 的碎碎念”。

场景 B：摄影相册（最常用）

@cate:相册
@mood:放松
周末去公园散步，随手拍了几张。

https://你的COS域名/01.jpg https://你的COS域名/02.jpg
https://你的COS域名/03.jpg

结果：

  • 分类自动设为“相册”。
  • 字段 mood = 放松。
  • 图片在 Markdown 中是紧挨着的（便于前端做拼图样式）。

场景 C：影评/读书（高级用法）

@cate:书单
@rating:5星
@book:三体

看完《三体》太震撼了，特别是黑暗森林法则... #科幻 #阅读
结果：归类到“书单”，带有 rating 和 book 字段，前端可以据此显示五星好评样式。

3. 部署与配置说明

如果你更换了服务器或域名，需要修改 api_note.php 顶部的配置区。

📂 文件路径

通常放置在网站根目录：https://你的域名.com/api_note.php

⚙️ 必填配置项 (代码第 20 行左右)

$config = [
    'db_host' => 'localhost',     // 数据库地址
    'db_user' => 'root',          // 数据库用户名
    'db_pass' => 'root',          // 数据库密码
    'db_name' => 'typecho',       // 数据库名
    'prefix'  => 'typecho_',      // 表前缀 (默认是 typecho_)
    'api_pwd' => '******',   // 【重要】你的通讯密码
    'def_cid' => 1                // 默认分类ID (不知道就填1)
];

4. 常见问题排查 (FAQ)

Q: 为什么发送成功了，但博客里没显示图片？
A: 检查你的 Markdown 解析器。脚本生成的格式是 ![](url)。如果是前端不显示，检查 CSS 是否隐藏了图片。

Q: 为什么所有图片都挤在一起了？
A: 这是特性的设定！ 为了让你前端能做相册集（grid layout）。如果你希望图片换行，请在备忘录里，手动在两个链接之间空一行。

Q: 标题的时间怎么不对？
A: 代码中已强制设置时区为 Asia/Shanghai。如果还不对，检查服务器系统时间设置。

Q: 发送失败，提示“密码错误”？
A: 检查你在快捷指令/POST请求里填写的 password 字段，必须和代码里的 $config['api_pwd'] 完全一致。

5. 快捷指令/POST 请求参数

如果你要重新配置 iOS 快捷指令或类似工具：

  • URL: https://你的域名.com/api_note.php
  • Method: POST
  • Header: Content-Type: application/x-www-form-urlencoded 或 multipart/form-data

  • Body (表单数据):

    • password: (你的通讯密码)
    • content: (输入的内容变量)
寄语：这套系统是你作为“产品经理”与 AI 共同打磨的结晶。它兼顾了灵活性与结构化，愿它能长久地记录下你生活中的每一个闪光瞬间。