laoyang/wordpress-kratos-yang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme.html 整体重写：从 57 节版本日志改为功能与用法说明 #36

New Issue
Closed
opened 2026-10-28 09:57:58 +00:00 by laoyang · 2 comments
laoyang commented 2026-10-28 09:57:58 +00:00
Owner
Copy Link
Copy Source

现象

当前线上 https://yangyq.net/theme-update/readme.html 是 57 节的版本更新日志，从 V3.2.9 一路记到 V4.1.1，18.6 万字节。

问题不在于写得多，而在于它被当成什么用：

  • 用户在后台点「查看版本详情」时，这个页面会弹出来 —— 他此刻想知道的是"这主题能干什么、怎么配"，看到的却是一堆"某某 bug 修好了"。
  • 想查某个功能怎么用，得在 57 节里翻，而且很多功能是分几次版本逐步完善的，说明散在好几处。

要求

整体重写，以功能介绍 + 用法为主体。

  • 主要写：有哪些功能、每个功能干什么、怎么开、关键的坑在哪。
  • 不要写更新机制（打包、发布、update.json、版本检测那套东西）。
  • 不要写逐版更新日志（V3.2.44：…… 那种一节一节的）。
  • 版本号可以出现在开头一句（"当前版本 4.1.1"），但不作为正文结构。

内容来源（已核实的模块清单）

主题代码里现有这些独立模块（inc/ 下），readme 应覆盖到：

模块 文件
全站配置 / 顶部导航 / 首页 / 文章 theme-core.php、theme-options.php
自动头像（按邮箱本地生成，14 套风格） theme-avatar.php
自动目录（正文内 + 浮层，可分别配置） theme-toc.php
代码高亮（自研，10 浅 + 10 深配色、语言标签、复制） theme-highlight.php
图片灯箱（当前页放大、多图轮播） theme-lightbox.php
评论增强（所见即所得、格式工具条、回复层级） theme-comments.php
侧栏挂件（个人简介 / 最近评论 / 文章分类 / 文章聚合） theme-widgets.php
归档短代码 [Archives] theme-archives.php、theme-shortcode.php
CDN 加速（一个地址 + 白名单 + 黑名单） theme-cdn.php
邮件通知（SMTP + 评论提醒 + 邮件模板） theme-mail.php、theme-smtp.php、theme-mail-template.php
写作增强（别名/标签/分类/摘要四引擎） theme-writing.php
访问统计面板（百度统计 API 直出后台） theme-stat.php
哀悼模式（纪念日自动出现） theme-mourning.php、theme-mourning-page.php
自定义代码（CSS/JS 兜底） theme-custom-code.php
导航多级下拉 theme-navwalker.php
后台设置框架 theme-setting.php、theme-options.php、options-framework/

设置页现有分组（可直接作为 readme 的一级结构参考）：全站配置 / 自动头像 / 顶部导航 / 首页配置 / 文章配置 / 自动目录 / 站长信息 / 页脚配置 / 哀悼模式 / 收录与统计 / 邮件通知 / CDN 加速 / 图片灯箱 / 代码高亮 / 写作增强 / 自定义代码。

验收标准

  1. 线上 readme.html 不再有 V3.2.x / V4.0.0 这类逐版小节标题（判据：<b>V 开头的节标题数量为 0 或仅 1 个"当前版本"标注）。
  2. 不出现更新机制相关内容：update.json、download_url、md5、PUC、theme-update 等词零命中。
  3. 上表 16 个模块，每个都能在正文里找到对应说明（不只是列个名字，要有"干什么 / 怎么开"）。
  4. 页面在后台「版本详情」弹层里能正常渲染（HTML 片段，不是完整文档，不依赖外部资源）。
  5. 语言风格与正文一致：讲清楚"为什么这么做"，而不是罗列参数。

本单由需求拆解生成，主单 laoyang/wordpress-kratos-yang #34。

## 现象 当前线上 `https://yangyq.net/theme-update/readme.html` 是 **57 节的版本更新日志**，从 V3.2.9 一路记到 V4.1.1，18.6 万字节。 问题不在于写得多，而在于**它被当成什么用**： - 用户在后台点「查看版本详情」时，这个页面会弹出来 —— 他此刻想知道的是"这主题能干什么、怎么配"，看到的却是一堆"某某 bug 修好了"。 - 想查某个功能怎么用，得在 57 节里翻，而且很多功能是分几次版本逐步完善的，说明散在好几处。 ## 要求 **整体重写**，以**功能介绍 + 用法**为主体。 - 主要写：有哪些功能、每个功能干什么、怎么开、关键的坑在哪。 - **不要写更新机制**（打包、发布、update.json、版本检测那套东西）。 - **不要写逐版更新日志**（`V3.2.44：……` 那种一节一节的）。 - 版本号可以出现在开头一句（"当前版本 4.1.1"），但不作为正文结构。 ## 内容来源（已核实的模块清单） 主题代码里现有这些独立模块（`inc/` 下），readme 应覆盖到： | 模块 | 文件 | |---|---| | 全站配置 / 顶部导航 / 首页 / 文章 | `theme-core.php`、`theme-options.php` | | 自动头像（按邮箱本地生成，14 套风格） | `theme-avatar.php` | | 自动目录（正文内 + 浮层，可分别配置） | `theme-toc.php` | | 代码高亮（自研，10 浅 + 10 深配色、语言标签、复制） | `theme-highlight.php` | | 图片灯箱（当前页放大、多图轮播） | `theme-lightbox.php` | | 评论增强（所见即所得、格式工具条、回复层级） | `theme-comments.php` | | 侧栏挂件（个人简介 / 最近评论 / 文章分类 / 文章聚合） | `theme-widgets.php` | | 归档短代码 `[Archives]` | `theme-archives.php`、`theme-shortcode.php` | | CDN 加速（一个地址 + 白名单 + 黑名单） | `theme-cdn.php` | | 邮件通知（SMTP + 评论提醒 + 邮件模板） | `theme-mail.php`、`theme-smtp.php`、`theme-mail-template.php` | | 写作增强（别名/标签/分类/摘要四引擎） | `theme-writing.php` | | 访问统计面板（百度统计 API 直出后台） | `theme-stat.php` | | 哀悼模式（纪念日自动出现） | `theme-mourning.php`、`theme-mourning-page.php` | | 自定义代码（CSS/JS 兜底） | `theme-custom-code.php` | | 导航多级下拉 | `theme-navwalker.php` | | 后台设置框架 | `theme-setting.php`、`theme-options.php`、`options-framework/` | 设置页现有分组（可直接作为 readme 的一级结构参考）：全站配置 / 自动头像 / 顶部导航 / 首页配置 / 文章配置 / 自动目录 / 站长信息 / 页脚配置 / 哀悼模式 / 收录与统计 / 邮件通知 / CDN 加速 / 图片灯箱 / 代码高亮 / 写作增强 / 自定义代码。 ## 验收标准 1. 线上 `readme.html` 不再有 `V3.2.x` / `V4.0.0` 这类逐版小节标题（判据：`<b>V` 开头的节标题数量为 0 或仅 1 个"当前版本"标注）。 2. 不出现更新机制相关内容：`update.json`、`download_url`、`md5`、`PUC`、`theme-update` 等词零命中。 3. 上表 16 个模块，每个都能在正文里找到对应说明（不只是列个名字，要有"干什么 / 怎么开"）。 4. 页面在后台「版本详情」弹层里能正常渲染（HTML 片段，不是完整文档，不依赖外部资源）。 5. 语言风格与正文一致：讲清楚"为什么这么做"，而不是罗列参数。 --- > 本单由需求拆解生成，主单 laoyang/wordpress-kratos-yang #34。
laoyang commented 2026-10-28 10:25:54 +00:00
Author
Owner
Copy Link
Copy Source

已交付

线上 readme.html 已从 186336 字节 / 57 节版本日志 换成 18548 字节 / 17 节功能与用法说明。

结构

一、装好之后先做这三件事
二、正文排版：标题、目录、代码、图片
三、评论区
四、头像
五、侧栏挂件
六、归档短代码 [Archives]
七、导航
八、CDN 加速
九、邮件通知
十、写作增强：四个引擎
十一、访问统计面板
十二、哀悼模式
十三、页脚
十四、自定义代码
十五、几个常见问题
十六、这个主题不做什么
十七、遇到问题

开头一句：当前版本 4.2.0。下面按「你会用到的顺序」讲，每块都写了怎么开和为什么要这么设计。

按「你会用到的顺序」排，不按代码模块排 —— 用户点「查看版本详情」时想知道的是怎么用，不是 inc/ 下有几个文件。

明确不写的东西

  • 更新机制（update.json / download_url / md5 / PUC / 打包发布）—— 已实测清零
  • 逐版更新日志（V3.2.44：…… 那种）—— <b>Vx.y.z： 出现 0 次
  • 版本号只在开头出现一次，不作为正文结构

验证

正向判据 _readme421_check.py：24 / 0

七段：逐版日志结构清零、不提更新机制、日志腔调 ≤2 次、16 模块覆盖、每模块附近有操作描述、HTML 片段可用性、体量合理。

双向区分力：同一套判据跑旧版 57 节日志 → 17 通过 / 7 失败。判据有牙齿，不是恒绿。

反证 _readme421_falsify.py：7/7 抓到

注入 期望红报
A 首节改回 <b>V4.1.1： 没有 <b>Vx.y.z： 形式的版本小节标题
B 加「这一版新增/修复了」 日志腔调
C 加 update.json/md5/PUC 不出现「update.json」
D 删掉代码高亮整节 16 个模块
E 退化成只有模块名的目录 每个模块附近
F 漏出 **粗体** 正文里没有漏出来的 Markdown 粗体
G 塞 <script>/<link> 不依赖外部资源

反证的反证 _readme421_meta_falsify.py：4/4 抓到

包括「MODULES 全换成『的』⇒ E 组抓不到」「每个模块有用法改成恒真 ⇒ E 组抓不到」「日志腔调阈值放 9999 ⇒ B 组抓不到」。

部署

传 readme.html 到站点根 /theme-update/，公网 HTTP 200、18548 字节、<b>V[0-9] 出现 0 次。旧版已备份为 readme.html.keep-20261028182*。

源文件留档：_tooling/yang_theme_test/readme420.html。

## 已交付 线上 `readme.html` 已从 **186336 字节 / 57 节版本日志** 换成 **18548 字节 / 17 节功能与用法说明**。 ## 结构 ``` 一、装好之后先做这三件事 二、正文排版：标题、目录、代码、图片 三、评论区 四、头像 五、侧栏挂件 六、归档短代码 [Archives] 七、导航 八、CDN 加速 九、邮件通知 十、写作增强：四个引擎 十一、访问统计面板 十二、哀悼模式 十三、页脚 十四、自定义代码 十五、几个常见问题 十六、这个主题不做什么 十七、遇到问题 ``` 开头一句：`当前版本 4.2.0。下面按「你会用到的顺序」讲，每块都写了怎么开和为什么要这么设计。` 按「你会用到的顺序」排，不按代码模块排 —— 用户点「查看版本详情」时想知道的是怎么用，不是 `inc/` 下有几个文件。 ## 明确不写的东西 - **更新机制**（`update.json` / `download_url` / md5 / PUC / 打包发布）—— 已实测清零 - **逐版更新日志**（`V3.2.44：……` 那种）—— `<b>Vx.y.z：` 出现 0 次 - 版本号只在开头出现一次，不作为正文结构 ## 验证 **正向判据 `_readme421_check.py`：24 / 0** 七段：逐版日志结构清零、不提更新机制、日志腔调 ≤2 次、16 模块覆盖、每模块附近有操作描述、HTML 片段可用性、体量合理。 **双向区分力**：同一套判据跑**旧版 57 节日志** → 17 通过 / **7 失败**。判据有牙齿，不是恒绿。 **反证 `_readme421_falsify.py`：7/7 抓到** | 注入 | 期望红报 | |---|---| | A 首节改回 `<b>V4.1.1：` | 没有 `<b>Vx.y.z：` 形式的版本小节标题 | | B 加「这一版新增/修复了」 | 日志腔调 | | C 加 update.json/md5/PUC | 不出现「update.json」 | | D 删掉代码高亮整节 | 16 个模块 | | E 退化成只有模块名的目录 | 每个模块附近 | | F 漏出 `**粗体**` | 正文里没有漏出来的 Markdown 粗体 | | G 塞 `<script>`/`<link>` | 不依赖外部资源 | **反证的反证 `_readme421_meta_falsify.py`：4/4 抓到** 包括「MODULES 全换成『的』⇒ E 组抓不到」「每个模块有用法改成恒真 ⇒ E 组抓不到」「日志腔调阈值放 9999 ⇒ B 组抓不到」。 ## 部署 传 `readme.html` 到站点根 `/theme-update/`，公网 HTTP 200、18548 字节、`<b>V[0-9]` 出现 0 次。旧版已备份为 `readme.html.keep-20261028182*`。 源文件留档：`_tooling/yang_theme_test/readme420.html`。
laoyang commented 2026-10-28 11:40:59 +00:00
Author
Owner
Copy Link
Copy Source

升级后最终验收通过

线上 readme.html 实测（公网取回，非服务器本地）：

HTTP 200 / 18548 字节
逐版标题 <b>V[0-9]                  0 个  ✅
更新机制词(update.json/md5/PUC)      0 个  ✅
章节数（一、二、…）                  17 节
Markdown 星号残留                    0 个  ✅
script/link/iframe/img 标签          0 个  ✅

首两行：

<b>Kratos Yang —— 一个给中文技术博客用的 WordPress 主题</b><br>
<br>

旧版 57 节版本日志已备份为 readme.html.keep-202610281821*（186336 字节），需要可随时回滚。

判据保持全绿：正向 24/0（旧版对照 17/7，有区分力）· 反证 7/7 · 反证的反证 4/4。

关闭工单。

## 升级后最终验收通过 线上 `readme.html` 实测（公网取回，非服务器本地）： ``` HTTP 200 / 18548 字节 逐版标题 <b>V[0-9] 0 个 ✅ 更新机制词(update.json/md5/PUC) 0 个 ✅ 章节数（一、二、…） 17 节 Markdown 星号残留 0 个 ✅ script/link/iframe/img 标签 0 个 ✅ ``` 首两行： ``` <b>Kratos Yang —— 一个给中文技术博客用的 WordPress 主题</b><br> <br> ``` 旧版 57 节版本日志已备份为 `readme.html.keep-202610281821*`（186336 字节），需要可随时回滚。 判据保持全绿：正向 24/0（旧版对照 17/7，有区分力）· 反证 7/7 · 反证的反证 4/4。 关闭工单。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
laoyang (老杨)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: laoyang/wordpress-kratos-yang#36