Wechat API Lite

微信公众号 API 轻量化工具 — 凭证获取、素材上传、草稿创建，主打最小化依赖和零冗余

Security Scan

The code matches the described WeChat API functionality, but the package metadata omits required credentials and provenance information, so the package is coherent functionally but has configuration/metadata inconsistencies you should verify before installing.

Purpose & Capability

The skill's name/description (WeChat Official Account API helpers) aligns with the included script: it implements token retrieval, image/thumb upload, draft creation and draft count. However the registry metadata declares no required environment variables or primary credential, while the code and SKILL.md clearly require WECHAT_APP_ID and WECHAT_APP_SECRET (via a local config.env). The missing credential declaration in metadata is an inconsistency.

Instruction Scope

SKILL.md and the CLI script limit actions to local file reads (config.env, image files, draft JSON), caching a token to scripts/.token_cache, and HTTP calls to api.weixin.qq.com. There are no instructions to read unrelated system files or to transmit data to endpoints outside WeChat's API. The runtime instructions ask the user to create a local config.env containing AppID/Secret, which the script reads.

Install Mechanism

This is an instruction-only skill with a Python script and no install spec. Nothing is downloaded or written by an install step; risk from install mechanism is low. The script will write a small token cache file under the skill directory when run.

Credentials

The script requires sensitive credentials (WECHAT_APP_ID, WECHAT_APP_SECRET) stored in a local config.env (config.env.example provided). The registry metadata did not list these required env vars or a primary credential, which is disproportionate to the metadata claim and could mislead users. The script also writes a token cache file containing access_token and expiry to scripts/.token_cache — expected for function but sensitive and should be protected.

Persistence & Privilege

The skill does not request persistent/global privileges (always:false). It writes only its own small token cache and reads a local config.env under its skill directory; it does not modify other skills' configs or system-wide settings.

What to consider before installing

This package appears to implement only the WeChat Official Account API calls advertised, but the registry metadata incorrectly lists no required environment variables while the code and SKILL.md require WECHAT_APP_ID and WECHAT_APP_SECRET in a local config.env. Before installing: (1) verify the skill's provenance — there is no homepage and the source is 'unknown'; prefer packages from known authors. (2) Create the config.env only under the skill directory and set file permissions so others can't read it (it contains your AppID/AppSecret). (3) Use a least-privileged / test WeChat account when first trying it. (4) Inspect the script locally (you already have it) and consider running it in an isolated environment; it only calls api.weixin.qq.com and writes a .token_cache file under the skill folder. (5) If you plan to publish or back up your home directory, ensure config.env is excluded (.gitignore noted in example). If you need assurance, contact the package author to correct the registry metadata so required credentials are declared explicitly.

微信公众号 API 轻量化工具。只保留发布图文必需的功能：token 获取、封面图上传、正文图片上传、草稿创建。无多余命令，无依赖膨胀。

---

凭证配置

复制示例文件并填入真实值：

SKILL_DIR="$HOME/.hermes/skills/wechat-api-lite"
cp "$SKILL_DIR/config.env.example" "$SKILL_DIR/config.env"
# 编辑 config.env，填入 AppID 和 AppSecret

AppID 和 AppSecret 获取：微信公众平台 → 设置与开发 → 基本配置

---

核心命令

token — 获取 access_token

有效期 7200 秒，脚本内自动缓存 + 提前刷新。

python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py token

---

upload-thumb — 上传封面图

返回 thumb_media_id，用于创建草稿时指定封面。

python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py upload-thumb <文件路径>
# 示例
python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py upload-thumb ~/hermes/research/Cover.png

封面图推荐尺寸：900 × 383 px（2.35:1 宽屏），PNG/JPG，不超过 2MB。

---

upload-image — 上传正文图片

返回 media_id + url，在正文 HTML 中用 url 嵌入图片。

python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py upload-image <文件路径>

---

create-draft — 创建图文草稿

python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py create-draft ~/hermes/research/draft.json

draft.json 格式：

[
  {
    "title": "文章标题（不超过32字）",
    "author": "作者名",
    "digest": "摘要",
    "content": "<p>HTML 格式正文...</p>",
    "thumb_media_id": "upload-thumb 返回的 ID",
    "show_cover_pic": 1,
    "need_open_comment": 1,
    "only_fans_can_comment": 0
  }
]

成功输出：✅ 草稿创建成功: media_id=XXXXXXXXXXXXXXXX

---

draft-list — 查看草稿数量

python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py draft-list

---

完整发布流程（wechat-post + wechat-api-lite 配合）

1. wechat-post 生成 Markdown 正文
         ↓
2. 将 Markdown 转为 HTML，写入 draft.json
         ↓
3. wechat-api-lite upload-thumb（上传封面 → thumb_media_id）
         ↓
4. wechat-api-lite create-draft（创建草稿 → media_id）
         ↓
5. 登录 mp.weixin.qq.com 草稿箱 → 预览 → 发布

---

草稿字段说明

字段	必填	说明
title	✅	标题，不超过 32 字符
author	否	作者名，不超过 16 字
digest	否	摘要，默认取正文前 54 字
content	✅	HTML 格式正文
thumb_media_id	✅	封面图 ID（来自 upload-thumb）
show_cover_pic	否	是否在正文显示封面（0/1）
need_open_comment	否	是否打开评论（0/1）
only_fans_can_comment	否	是否仅粉丝可评论（0/1）

---

已知问题 & API 行为

access_token 过期（40001）

token 过期后所有 API 调用均失败。清除缓存后重试：

rm ~/.hermes/skills/wechat-api-lite/scripts/.token_cache
python3 $HOME/.hermes/skills/wechat-api-lite/scripts/wechat_api.py upload-thumb ...

成功响应无 errcode

以下接口成功时不返回 errcode，判断成功仅看业务字段是否存在：

接口	成功判断依据
draft/add（创建草稿）	"media_id" in result
draft/count（草稿数量）	"total_count" in result

url vs media_id

• 正文 HTML 图片 → 用 upload-image 返回的 url
• 草稿封面图 → 用 upload-thumb 返回的 media_id

两者不可混用。

⚠️ 草稿正文图注位置注意

在 JSON 中写 HTML 正文时，如果要给配图加 caption 注释，caption 必须紧跟在对应的 <img> 标签后面，不要写在正文开头或其他位置。公众号渲染会把 caption 放在图片在正文中出现的相对位置，误放在文章顶部会导致 caption 跑到文章最下方显示。

• 正文 HTML 图片 → 用 upload-image 返回的 url
• 草稿封面图 → 用 upload-thumb 返回的 media_id

两者不可混用。

---

注意事项

• access_token 有效期 2 小时，脚本自动维护缓存，过期后手动清缓存重刷
• 永久素材有总量限制，缩略图不超过 2MB
• 封面图推荐 900 × 383 px，正文图片宽度建议 ≤ 1080px
• 草稿创建后在 mp.weixin.qq.com 草稿箱查看和编辑