项目维护与文章归档指南

本仓库是“同尘”的个人博客，基于 Jekyll Now，通过 GitHub Pages 发布。维护时优先遵循当前仓库的配置、模板和同类文章约定。本文约定用于后续新增及修改；不要求批量改写历史文章。

一、更新原则

• 以用户本次要求为准，修改范围保持明确。新增文章通常只需增加一篇 Markdown 文件及必要的配图，不顺带调整主题、导航、样式或全站配置。
• 用户提供完整稿件时，博客原稿保留标题、观点、段落、强调和来源链接。可以补充发布所需的元信息；没有要求润色时，不自行改写正文、扩写结论或添加事实。公众号派生版本按第九节删除参考资料引用，并以直接、通俗、易读为原则适配。
• 用户已授权在新增文章及公众号适配时，按内容需要自动生成、检查并插入合适配图；这项授权不等于改写博客原稿，也不等于自动公开发布。具体执行规则见第十节。
• 新增事实、数据、引文时应核实来源；仅录入原稿时，不把格式检查表述为事实核验。发现疑点应说明，不默默替换作者的说法。
• 操作前查看 git status --short，保留已有修改及未跟踪文件。不得覆盖、删除或顺带提交其他工作。
• 编辑旧文时保留原始发布日期及文件名。不要因修正文字而把旧文改成当天发布，也不要为了统一命名批量重命名历史文件。
• 本地添加文件、提交、推送及上线是不同步骤。按用户授权执行，并在交付时说明实际完成到哪一步。

二、目录与分类

读书类的目录名是 read，分类值是 reading，两者不能直接照抄。 read/index.html 使用 site.categories.reading 汇总文章。

用户指定分类时优先采用指定分类；未指定时按文章主旨选择。不要仅凭“AI”等关键词归类，例如技术实践可以归入 tech，个人感想可以归入 blog。每篇新文章沿用一个主分类，不为跨主题内容复制多份文章。

• index.html 使用 site.posts 自动展示文章；各分类页按分类自动汇总。正常新增文章不需修改这些页面。
• feed.xml 自动选取最近 10 篇文章，无需手工登记。
• collections/index.html 按 tags: [study] 汇总专题内容，不是所有文章的归档目录。tags 为可选字段，仅在确有专题需要时添加。
• 不另建按年份划分的子目录或手工文章清单。确需增加新分类时，应同时处理分类目录、分类字段、分类入口页及导航。

三、文件名与文章地址

新文章统一使用：

_posts/<分类目录>/YYYY-MM-DD-<slug>.md

例如：

_posts/tech/2026-10-03-jev-is-not-a-silver-bullet.md

• 日期优先使用用户指定的发布日期；未指定时使用用户所在时区的当天日期。补录旧文应使用明确的原始发布日期。
• 年、月、日写完整，月和日补足两位。历史文件中存在未补零的日期，不作为新文件的格式参考。
• 新文件的 slug 优先使用简短、可读的小写英文词，以连字符分隔；中文标题放在 title 中。历史中文文件名保留。
• _config.yml 配置了 permalink: /:title/。默认情况下，文章路径来自文件名中日期之后的 slug，不包含日期和分类目录。因此应在所有分类中检查 slug，避免不同日期或目录的文章生成相同地址。
• 修改显示标题通常只改 title；改文件名中的 slug 会改变文章地址。确需改地址时，要检查站内引用并考虑已有外链的兼容。
• 不随意添加 date、slug、permalink 或 published 等覆盖字段。未来日期的文章需要另行确认发布安排，不能假定它会立即显示。

四、文章模板与元信息

每篇文章以 YAML front matter 开头，第一行就是 ---，结束后留一个空行再写正文。新文章至少包含以下四个字段：

---
layout: post
title: "文章标题"
description: "用一句话概括文章主题与核心观点"
category: tech
---

正文第一段。

## 小节标题

后续正文。

• layout 固定为 post，不要使用独立页面的 page 布局。
• title 使用用户确定的完整标题，保留其命名方式。
• description 写简明、准确的纯文本摘要，不堆关键词，不添加正文没有支持的判断。
• category 按上表填写，沿用仓库的单数键名。
• 标题或摘要包含冒号、井号、引号等可能影响 YAML 解析的字符时，使用合法的 YAML 引号与转义；不要只凭肉眼判断格式正确。
• tags 不是必填项。如确有需要，可使用 tags: [study] 这样的 YAML 列表。

当前首页显示的是 post.excerpt，通常来自正文首段；文章模板中的 description 显示代码已被注释，页面元描述也优先取 excerpt。因此填写 description 不等于修改首页摘要，不要为了让它显示而顺带修改模板。

五、正文、链接与图片

• 使用 UTF-8 编码的 Markdown，文件末尾保留换行。段落之间留一个空行。
• _layouts/post.html 已生成文章的一级标题，正文不重复写 # 文章标题。有分节需要时从 ## 开始，子节使用 ###；短文不强制增加小节。
• 标题标记与文字间留空格。列表、代码块与普通段落之间留空行，避免依赖历史文章中的不规范写法。
• 保留原稿中有意义的加粗、引用和列表，避免为排版而大量增加强调。
• 代码使用围栏代码块，并尽量标明语言，例如 python、bash、json。示例中若含 Liquid 模板语法，需检查是否会被 Jekyll 提前解释，必要时用 Liquid 的 raw/endraw 标签保护。
• 来源使用可读的 Markdown 链接，如 [来源：文档名称](https://example.com/docs)。保留用户提供的来源及其对应论述，不用无关主页替代具体来源。
• 站内文章链接使用实际发布地址，不链接到 _posts/ 下的源文件。需要兼容站点前缀时使用 ``。
• 现有文章有外部图床图片，录入时保留有效的原始链接。新增本地图片可放在 images/<文章 slug>/ 下，使用清晰的文件名，避免覆盖其他文章的素材。
• 本地图片引用示例：![图片说明](/images/<文章 slug>/example.png)。不要把电脑上的绝对路径或仅在本机可访问的地址写进文章。
• 不为了普通文章引入新的 JavaScript、样式库或构建依赖。

六、新增与归档流程

1. 查看工作区状态，读取目标分类中最近的同类文章，确认用户的标题、正文、分类与发布日期。
2. 在整个 _posts/ 下搜索标题和 slug，判断应新增还是更新已有文章，避免重复发布。
3. 在对应分类目录创建文件，补齐四项元信息，再放入正文和必要素材。
4. 核对正文与原稿，检查段落、强调、链接、代码和图片是否完整。
5. 核对目录与 category 的映射，确认首页及分类页能够通过现有模板自动收录。
6. 若为重新分类，移动原文件并修改 category，保留日期和 slug，不留下两个副本。检查相关站内链接及素材引用。
7. 完成下述检查，并说明修改文件、分类、日期、验证结果及发布状态。

这里的“归档”是把文章放入正确分类并由站点自动汇总；除非用户明确要求下线，不通过移出 _posts/、设置未发布或删除旧文来归档。

七、完成前检查

• 文件路径符合约定；日期有效；slug 在全站没有冲突。
• YAML 能正常解析，layout、title、description、category 完整且准确。
• 正文与交付稿一致，没有重复标题、遗漏段落、占位文字、断开的代码围栏或误改来源。
• 本地图片和站内链接的目标存在；外链如未联网核验，不宣称已验证可访问。
• 查看 git status --short 和相关文件差异；新增的未跟踪文件需直接检查，因为普通 git diff 不显示其内容。使用 git diff --check 检查已有差异中的空白问题，并另行检查新增文件。
• 若本机已具备 Jekyll 及项目所需插件，运行 jekyll build；需要视觉检查时运行 jekyll serve，核对首页、分类页、文章详情与图片展示。生成目录 _site/ 不纳入提交。
• 若缺少 Jekyll 环境，完成元信息、路径和内容检查，并明确说明未运行整站构建。不要只为录入文章引入新的构建体系，也不要把静态检查说成构建成功。
• 单纯内容更新无需编写自动化测试。涉及模板或行为变更时，再执行与变更相符的验证。

八、维护规则时的依据

分类映射以 tech/index.html、blog/index.html、read/index.html 为依据；文章展示以 _layouts/post.html 和 index.html 为依据；地址、Markdown 引擎与插件以 _config.yml 为依据。README.md 主要是 Jekyll Now 模板说明，遇到差异时应核对本仓库实际配置。

本文件按项目约定命名为 agent.md。使用自动化助手时，应显式让它读取本文件，不假定所有工具都会自动加载该文件名。

九、同步到微信公众号草稿箱

目标与当前状态

用户希望在博客文章写好后，通过“把《文章标题》同步到公众号草稿箱”这样的指令完成公众号适配与上传。博客 Markdown 是内容源；公众号版本可以调整排版和行文，但不反向覆盖博客原稿。

本节记录 2026-10-03 的调研结果和后续操作约定。已通过本机保存的 SSH 发布方式，完成《Jev不是银弹》的封面上传、草稿新建与回读验证。 发布辅助工具保存在仓库外，目前支持已准备稿件的新建与回读校验，尚未实现完整的自动编辑和旧草稿更新流程。本次无法访问微信官方文档正文，接口流程交叉参考了 WxJava 项目的源码；账号权限、字段上限和平台规则仍应按实际接口及当时官方文档确认。

推荐方式与适用条件

优先采用“本地文章转换 + 微信官方 API”：助手负责阅读文章和适度润色，本地工具负责解析、图片上传、凭据管理、草稿写入与结果核对。相比自动操作网页，这种方式更适合重复执行，也便于识别同一篇草稿。

首次使用前确认以下条件：

1. 已取得目标公众号的 AppID 和 AppSecret。它们不是网页扫码登录凭证，也不是小程序的凭据。接口所需 access_token 由程序获取及刷新，不要求用户手工长期保存。
2. 公众号后台实际具备所需的草稿与素材接口权限。能登录后台、能手工写文章、能获取 token，都不等于一定拥有草稿 API 权限；不能笼统承诺所有个人号或未认证号可用。
3. 按后台要求配置调用来源的 IP 白名单。应使用实际请求的公网出口 IP；切换网络、代理或 VPN 后出口可能变化。若需要固定出口，可再评估由用户控制的固定 IP 服务执行请求。
4. 提交图文草稿前须备好可用封面或目标账号下的永久封面素材 ID。可复用用户指定的图片或按第十节自动生成；不要求用户必须提前准备默认封面。

权限不满足时，仍可生成适配后的正文、HTML 和图片包，交给用户在后台导入或粘贴。网页自动化可作为用户选择的备选，但不绕过扫码、验证或平台权限。暂不引入需要托管 AppSecret 的第三方发布平台。

本地配置文件约定

默认配置文件放在仓库外：~/.config/tongchen-blog/wechat.json。用户也可以指定其他绝对路径；后续工具可通过 WECHAT_CONFIG_PATH 接收该路径。以下仅为结构示例，真实文件由用户在本机填写：

{
  "app_id": "填写目标公众号 AppID",
  "app_secret": "填写目标公众号 AppSecret",
  "author": "同尘",
  "default_thumb_media_id": "",
  "default_cover_path": "",
  "site_url": ""
}

• app_id、app_secret 为必需凭据；author 是署名偏好，可按用户要求修改或留空。
• default_thumb_media_id 与 default_cover_path 是可选的默认封面来源。单篇文章指定的封面优先，其次复用已为该文章生成的合适封面，再使用适合该文的默认封面。均不可用时自动生成主题封面并上传，不因这两个配置为空而提前中断。
• site_url 填写经过核实的博客完整站点地址，包含协议。当前 _config.yml 的 url 为空，不能直接用它生成“阅读原文”链接；CNAME 仅能提供域名线索。
• 这些字段是本项目拟定的配置格式，不是微信要求的配置文件格式；后续实现须与这里保持一致。
• 凭据文件建议仅当前用户可读写（权限 600）。程序直接读取文件，不将文件全文、AppSecret 或 access_token 输出到对话、日志、命令参数、预览 HTML 或报错堆栈。
• 不把凭据写进 _config.yml、文章 front matter、agent.md 或提交记录。不要要求用户把密钥粘贴到聊天里。
• 默认将 token 缓存放在 ~/.cache/tongchen-blog/wechat/，公众号版本、同步记录及素材映射放在 ~/.local/share/tongchen-blog/wechat/，按 AppID 和文章标识隔离。缓存应限制权限，token 按接口返回的有效期更新。
• 如确需把配置、缓存或导出物放在仓库内，必须同时检查 Git 忽略规则和 Jekyll 发布排除规则；仅加入 .gitignore 不代表文件不会被本地构建复制到站点。当前默认方案使用仓库外目录，不需要为了存放密钥修改博客配置。

本机已配置的 SSH 发布方式

• 后续发布优先读取仓库外的 ~/.config/tongchen-blog/ssh-publisher.json，通过其中配置的服务器执行微信 HTTPS 请求，避免依赖家庭网络的动态出口 IP。
• 用户明确要求服务器信息仅在本地保存：服务器地址、端口、用户名、私钥路径、主机密钥和实际凭据均不得写入本仓库、提交信息或仓库文档。此处只记录通用配置入口，不记录连接内容。
• 本机操作说明位于 ~/.local/share/tongchen-blog/wechat/LOCAL-PUBLISHING.md；辅助入口为 ~/.local/share/tongchen-blog/wechat/tools/submit_prepared.py，接受一个文章 slug 参数。先读取本机说明并准备公众号版本、封面及清单，再执行入口。
• SSH 使用已保存的主机密钥严格校验身份。公众号凭据通过加密 SSH 标准输入传给远端临时进程，不在远端落盘；微信 token 和同步记录保存在本机。不要在日志中打印传输正文或带 token 的地址。
• 当前辅助入口不自动覆盖旧草稿：已关联草稿会先回读校验；有内容差异或无法确认先前请求结果时，先核对再处理，不能以重新新建代替更新。

公众号版本的编辑与排版

公众号适配包括两层，均在派生版本中完成：

• 文字调整： 保留原文观点、事实、数据和不确定性表述；表达直接、通俗易懂，优先使用自然行文、短段落和必要的小标题，让读者在手机上轻松读下去。避免学术论文式的组织方式、频繁的出处标注和不必要的术语堆砌。默认保留原标题，不擅自改成夸张标题，不删减关键论据或凭空补充事实。记录有实质影响的文字调整，便于交付时说明。
• 格式转换： 提取正文，去掉 YAML、博客导航及模板内容，输出微信可接收的 HTML 正文片段。将必要样式写在元素的 style 中，不依赖博客 CSS、外部字体、JavaScript、iframe 或交互组件。

初始排版建议为正文 16px、行高约 1.8、左对齐、清晰段间距、小标题与少量重点加粗。这是项目的默认审美选择，不是微信的强制规格；最终以手机预览为准。不要在正文开头重复后台已经单独显示的文章标题。

其他转换要求：

• Markdown 列表、引用、代码块和表格需分别适配。代码保留缩进并转义 HTML；宽表格可转换成分项说明或清晰图片，避免窄屏横向挤压。无法可靠转换的内容应明确指出，不静默丢弃。
• 博客保留参考资料，公众号删除参考资料引用。 公众号正文移除“[来源：……]”等出处链接、引用编号、脚注、单独列出的来源名称或 URL，以及文末参考资料列表，不再改写成另一种引用格式。删除后检查句子衔接，避免残留空括号或编号。作为论述一部分的“官方表示”等必要归属可以自然保留；原话若改为转述，应忠实保留含义。删除引用不等于删除事实、关键论据或不确定性限定，也不免除事实核验；完整来源继续保留在博客原稿中。
• 文章已在博客上线且地址核实后，将其地址写入 content_source_url，用于“阅读原文”。博客尚未上线时，不生成看似可用的虚假链接，可以暂时留空并在后续同步补上。
• 正文图片应通过微信的正文图片接口上传，再用返回的地址替换 HTML 中的引用。上传前核实图片来源、类型和大小，不将网页、登录页或错误响应当作图片上传。
• 封面走永久素材流程，不能把正文图片 URL 或临时素材 ID 当作 thumb_media_id。封面缺失时按第十节自动生成并检查，已有授权不再重复询问。仅在生成工具不可用、图片无法满足要求且无可复用素材时，请用户补充图片或选择替代方式。
• 摘要 digest 可从博客 description 提炼。标题、署名、摘要、HTML 长度及图片大小都要做预检；具体限制在联调时核对，不把网页编辑器与 API 的限制混用，超限时不静默截断原文。

拟实现的接口流程

下列路径均属于 https://api.weixin.qq.com。接口凭据只发送给微信官方接口，不发送给文章中的外链、图片源或第三方转换服务。

除获取 token 外，上述接口需要按其要求附加 access_token，不得将带 token 的完整 URL 写入日志。token 过期时按有效期刷新，不以反复强制刷新作为常规重试方式，以免影响同账号其他工具。

图文请求主要包含 title、author、digest、HTML content、content_source_url 和 thumb_media_id。首次默认每篇博客对应一个单篇图文草稿，不自动把多篇博客合并成一期。评论等额外选项沿用账号或用户明确指定的设置。

本节接口名称和数据结构参考 WxJava 草稿接口源码、图文数据结构、素材接口源码及 token 请求实现。这些是开源实现参考，不替代微信对当前账号的权限判定。

重复同步、失败恢复与验收

1. 先生成可检查的公众号稿件、预览 HTML 和待上传素材清单。纯预览模式不调用微信接口，不获取微信 token、不向微信上传图片、不写入草稿；需要新配图时可按第十节调用图像生成工具。用户要求完全离线时，只使用本地已有素材。
2. 同步记录至少保存：AppID、源文件相对路径、稳定文章标识（初始可用全站唯一 slug）、源内容和派生内容摘要、草稿 media_id、图文索引、上次回读内容摘要及同步时间。token 与 AppSecret 不写入记录。
3. 按账号和文章串行同步。同一内容已成功上传且远端未变时跳过写入；有新内容时更新已关联草稿，不默认反复调用新增接口。图片按账号及文件内容摘要复用上传结果，失效时再处理。
4. 更新前先回读远端草稿。如果用户在微信后台改过文章，比较上次同步快照并保留其修改；无法自动合并时输出差异供用户处理，不直接覆盖。如果原草稿已发布或删除，也不默认自动重建。
5. 检查 HTTP 状态及微信 JSON 中的 errcode，不能将 HTTP 200 一概当作成功。遇到权限、IP 白名单、凭据、素材或长度问题，说明具体阻塞点并保留本地成果。
6. 新建草稿发生超时、连接中断等结果不明确的情况时，记录“结果待核对”，先查询草稿并比对内容、封面和时间，不盲目重发新增请求。成功写入后回读失败时，同样保留已返回的 media_id，下次优先验证它。
7. 回读时比较标题、正文内容、关键结构和封面；对微信正常的 HTML 规范化做合理处理，不要求无意义的字节完全相等。后台手机预览用于确认实际字体、段落、代码及图片显示；仅 API 回读不能证明视觉效果完全正确。
8. 最后报告文章标题、目标账号、是新增还是更新、草稿 ID、文字适配摘要、验证结果。只展示接口实际提供且不含凭据的预览链接，不拼造后台编辑地址。

指令边界与首次落地

• 用户明确要求“同步到公众号草稿箱”，即授权为指定文章生成公众号版本、按需生成配图、上传必要素材并新增或更新其草稿；条件齐备时不再重复询问是否生成或上传。
• 只要求“预览公众号版”时仅生成本地预览；只要求“添加博客文章”时不自动同步公众号。
• 同步草稿不包含公开发布或群发，不调用 freepublish/submit 或群发接口。即便用户口语中说“发布到草稿箱”，也按保存草稿处理；正式发布须有另行明确指令。
• 博客上线与公众号同步分别报告结果。两者没有跨平台事务保障，一个失败时不删除或回滚另一个已成功的结果。
• 首次落地顺序：用户配置凭据（默认封面可选）→ 确认接口权限及出口 IP → 实现并本地验证转换/同步工具 → 为指定文章复用或生成配图后联调 → 回读及手机预览核对。工具测试应覆盖纯预览不调用微信接口、密钥不出日志、图片替换、重复同步、远端编辑冲突及新增请求结果不明确等场景。
• 联调时优先复核微信官方的新增草稿、稳定版调用凭据和永久素材管理文档；链接迁移时从官方导航查找相应章节。

十、自动生成配图与双平台素材管理

默认授权与配图判断

用户已明确授权：后续新增博客文章、准备发布稿或同步微信公众号时，助手可以按需构思、生成、检查、保存并插入图片；同步指令也包含将这些图片上传至目标公众号的授权。无需逐张请求批准。用户本次要求“纯文字”“不要生图”“使用这张封面”或限定数量、风格时，以本次要求为准。

• 先读懂文章，判断图片是否能帮助解释概念、展示关系或增强主题表达。纯观点短文可不配正文图，不为装饰凑数量。
• 公众号需要封面时，按第九节的优先顺序复用或生成一张主题封面；博客按内容需要使用封面，不强制每篇文章添加头图。
• 普通文章以少量图片为宜，通常先考虑一张主题图及零至两张有明确作用的正文图；这是起点，不是固定配额。
• 仅同步公众号时，新增图片和排版保存在公众号派生版本中，不自动修改已完成的博客原稿。用户同时要求给博客配图时，再将合适图片插入博客。
• 本规则不授权批量给全部历史文章补图，也不扩大博客推送、上线或公众号正式群发的范围。

生成方式与内容准确性

主题插画、概念封面和视觉隐喻优先使用当前环境内置图像生成工具，并遵循 imagegen 技能。图像提示词描述文章主题、用途、构图、风格、比例及需要避免的误导；不把公众号密钥、本地凭据或无关私密信息提供给生图工具。

精确的数据图表、流程图、架构图及带大量文字的示意图，应优先通过可核对的数据和绘图工具制作，不让图像模型凭空编造数字、节点关系或标签。需要截图证明的软件行为、评测结果和真实事件，使用实际截图或可核实资料；生成的概念插图不能冒充证据或官方素材。

• 同一篇文章的配图尽量保持配色、画风和视觉密度一致。默认避免水印、无关标识、密集小字和无法解释的装饰元素。
• 封面优先使用简洁构图，将主体放在较安全的中心区域，为横向与方形裁切留余量。具体裁切按当前公众号后台要求检查，不将固定像素尺寸当成永久规则。
• 尽量避免把长标题或正文烧录进图片；必须包含文字时，逐字核对中文、术语和标点。无法保证文字准确时改用不含文字的插画，文字保留在正文。
• 博客和公众号文章的配图不附加“AI 生成”“AI 生成的概念插图”等生成方式标注，也不为说明生成方式单独添加图注。保留描述画面内容的替代文本；只有帮助读者理解内容时才添加简短图注。生成工具、提示词等信息保存在仓库外的素材记录中，不作为文章正文展示。概念插图仍不得冒充真实照片、截图或实验结果。
• 内置生图不可用或失败时，先保留正文及已有素材，不默默切换到另外付费的 API。若确需独立 API/CLI 方案，另行说明所需凭据和执行方式；公众号 AppSecret 不能用于调用生图服务。

保存、引用与上传

1. 生成后先查看实际图片，核对主题、准确性、文字、裁切和小屏可读性。有问题时做针对性修改，检查通过后再用于文章，不以“接口返回成功”代替验图。
2. 博客的文章配图优先按下节上传 OSS，并在仓库外保留原图和上传记录。采用本地素材时，最终图片保存至 images/<文章 slug>/，建议使用 cover.png、concept-overview.png 等可读文件名；扩展名与实际格式一致。替换图片使用新版本名或内容摘要，不覆盖旧图。
3. 不将博客引用指向工具内部生成目录、临时目录或本机绝对路径。OSS 图片使用经过验证的公开 HTTPS 地址；本地图片使用 ![图意说明](/images/<文章 slug>/文件名)。图片放在解释对应概念的段落附近；头图优先放在首段之后，保留当前主题使用的首段摘要。
4. 只用于公众号的生成图片、裁切版本及上传记录放在第九节约定的仓库外工作目录。博客和公众号可复用同一张已检查的原始图片，根据各平台需要另存输出版本，不反复生成几乎相同的图。
5. 根据用途选择清晰且体积合适的图片格式。上传微信前核对实际编码、文件大小、尺寸及当前接口限制；另存压缩或裁切版本时保留原始图，并再次检查清晰度及构图。
6. 公众号正文图走 media/uploadimg，用返回的 URL 替换公众号 HTML 引用；封面走 material/add_material，用返回的永久素材 ID 设置 thumb_media_id。同一张图若兼作封面和正文图，分别记录两个接口的结果，不能互相代用。
7. 微信返回的图片地址只用于公众号版本，博客使用自己的 OSS 地址或本地素材路径，不依赖微信图床外链。公众号直接上传微信，不经 OSS 中转。重复同步按文件内容摘要、用途和账号复用已上传素材，避免重复占用素材库。
8. 保留本地素材记录，包含源文章、用途、生成工具、最终提示词、图片版本及上传映射；记录不含凭据，也不自动进入公开站点。这样可在后续修改或重新生成时保持一致。

博客 OSS 配置与上传

• 配置独立保存在仓库外的 ~/.config/tongchen-blog/.oss，使用 JSON 顶层字段，不混入 wechat.json，不读取旧的 oss.example.json 模板作为实际配置。
• 必需信息为 bucket、region、access_key_id、access_key_secret；项目同时使用 endpoint 和 object_prefix。调用 SDK 时将 oss-cn-hongkong 这样的地域值规范为 cn-hongkong，为 Endpoint 补充 HTTPS 协议，并核对目标属于指定的 OSS 服务。
• security_token 仅用于 STS 临时凭据；使用长期 AccessKey 时留空。配置及密钥不得进入仓库、命令参数、文章或日志。
• public_base_url 是可选的公开访问前缀，不要求一定是自定义域名。留空时可从常规公网 Endpoint 和 Bucket 推导 https://<bucket>.oss-<region>.aliyuncs.com，但必须实测，不能将内网地址或带有效期的签名 URL 写入文章。
• 自定义域名需先完成 OSS 绑定、DNS 和 HTTPS 证书配置并验证，再填写 public_base_url。长期使用自有图片域名有利于迁移存储或接入 CDN；仅修改本地配置不会替换历史文章中的地址，历史链接需另行迁移。
• 对象路径使用 <object_prefix>/<文章 slug>/<用途>-<内容摘要>.<扩展名>，设置准确的 Content-Type；带内容摘要的文件可设置长期缓存。启用禁止覆盖，重复运行时核对已有对象，不重复上传或覆盖不同内容。
• 上传后使用不带密钥的 HTTPS 请求核对状态码、图片类型和内容摘要，并检查博客来源的访问是否被防盗链拦截。权限问题只针对目标图片处理，不擅自将整个 Bucket 改为公开。
• 原图与上传映射保存在 ~/.local/share/tongchen-blog/oss/ 等仓库外目录，记录对象路径、公开 URL、源图片和内容摘要，不记录凭据。小型主题图标仍可保存在仓库内。

完成标准与能力边界

• 博客：最终图片已上传并验证公开访问，或已保存到项目素材目录；正文引用存在，图注合适。在可用预览环境中检查排版，并随文章一同纳入用户授权的发布步骤。
• 公众号：图片生成并验收后完成相应用途的上传，草稿回读确认引用和封面正确；实际手机显示仍按第九节检查。
• 交付时展示选用的图片或可点击文件链接，说明配图用途、使用的生成方式和必要的图注。若判断无需正文图，简要说明即可。
• 当前环境已验证图像生成、经 SSH 上传封面、新建草稿及回读校验；新文章仍需完成适配和素材准备，旧草稿更新按第九节处理。生成图片成功不等于已经上传、保存草稿或公开发布，必须分别报告各步骤的结果。