README HTML Converter Skill

这个 skill 是做什么的

readme-html-converter 是一个 Codex skill，用来把项目里的 README.md 和实际项目结构转换成独立的 README.html。

它不是简单把 Markdown 渲染成网页，也不是只读取 README。它会先读取 README，再扫描项目结构、入口文件、配置文件、脚本、环境变量样例和部署文件，最后生成一个分区分层、分页分标签、带交互能力的技术文档页面。

生成页面需要标出信息来源、提示 README 与项目文件的冲突，并对真实密钥、token、数据库密码等敏感信息做脱敏处理。

适用场景

文档交付需要把 README.md 转成更适合展示、交付或部署的 README.html。

技术参数多技术文档里有安装步骤、运行命令、环境变量、部署参数、API 示例或配置项。

结构要真实希望 HTML 结合真实项目结构展示入口、脚本、配置、部署和测试信息。

来源要清楚希望区分信息来自 README、manifest、配置文件、部署文件还是项目扫描。

安全要默认希望发现冲突并自动隐藏真实密钥、token、数据库密码等敏感信息。

需要交互希望 HTML 文档里提供一键复制命令、参数预览、标签导航、分页阅读和搜索过滤。

面板化说明希望文档从纯文本说明升级成一个可交互的说明面板。

安装方式

把这个仓库克隆到 Codex 的 skills 目录。

git clone git@github.com:paipaiio/readme.html.git "${CODEX_HOME:-$HOME/.codex}/skills/readme-html-converter"

如果已经安装过，可以进入 skill 目录更新：

cd "${CODEX_HOME:-$HOME/.codex}/skills/readme-html-converter"
git pull

安装后，在新的 Codex 会话中就可以通过 $readme-html-converter 调用。

使用方式

在目标项目目录中发出类似请求：

Use $readme-html-converter to convert the current README.md and project structure into one complete interactive README.html.

中文也可以这样说：

使用 $readme-html-converter，把当前项目的 README.md 和项目结构转换成一个单文件 README.html，要求保留全部信息，并做成分区、分页、分标签和可交互的说明页面。

默认执行流程

1. 完整读取

完整读取当前目录的 README.md，再扫描项目结构，重点查看入口文件、配置文件、脚本、环境变量样例、部署文件、测试目录和已有 docs。

2. 校验整理

盘点 README 内容，并用真实项目文件校验运行命令、配置项、入口和部署说明；发现冲突时保留 README 说法，同时标注项目文件证据。

关键事实需要带来源标记，例如 README、package.json、.env.example、Dockerfile、Observed。

3. 生成页面

在 README.md 同目录生成唯一的单文件 README.html，并给命令、配置、API 示例和重要参数增加一键复制按钮。

4. 交互与验收

在存在参数设置的场景里增加简单的交互预览，并检查 HTML 是否保留了原始 README 的全部信息、体现关键项目结构、没有泄露真实敏感信息。

输出效果

能力	说明
分级展示	按 README 的标题层级组织内容。
项目结构展示	基于实际文件树展示入口、脚本、配置、部署、测试和 docs。
扫描摘要	展示识别到的技术栈、入口、脚本、配置、部署文件和测试目录。
来源标记	标出信息来自 README、配置文件、manifest、部署文件或项目扫描。
冲突提示	README 与真实项目文件不一致时显示警告。
敏感信息脱敏	不展示真实 `.env`、token、私钥、数据库密码等内容。
分标签展示	按概览、安装、使用、配置、部署、FAQ 等主题拆分标签。
分页或步骤展示	对较长的安装、部署、使用流程做分页或步骤切换。
一键复制	对命令、配置文件、环境变量、JSON、URL 等增加复制按钮。
参数交互预览	用输入框、开关、下拉框等演示参数变化后的配置或命令。
搜索过滤	对内容较多的文档提供快速查找能力。
响应式布局	在手机和桌面端都能正常阅读。

来源与安全规则

来源标记命令、配置、入口、部署说明和项目结构摘要要标明来自 README、package.json、.env.example、Dockerfile 或项目扫描。

冲突提示如果 README 写了 npm start，但 package.json 没有 start，HTML 应该显示明确警告，而不是静默改写。

敏感脱敏真实 .env、token、私钥、cookie、数据库密码和生产凭据不能展示，也不能被复制按钮复制。

扫描边界大型项目只总结关键入口、manifest、配置、路由、部署、测试和 docs，不读取生成物、依赖目录和缓存。

如果某个配置值只在敏感文件里出现，页面只展示变量名和安全占位符，例如 replace-with-a-secure-secret。

参数交互示例

如果 README 中包含类似这些参数：

APP_MODE=development
PORT=3000
API_BASE_URL=http://localhost:3000
JWT_SECRET=replace-with-a-secure-secret

那么 README.html 里可以提供一个小型交互面板，让用户选择运行模式、端口和接口地址，然后实时生成新的 .env 示例，并提供复制按钮。

运行模式

端口

接口地址

这个演示不需要连接真实系统，只需要帮助读者理解不同参数设置后的效果。

仓库结构

.
├── SKILL.md
├── README.md
├── README.html
├── LICENSE
├── agents/
│   └── openai.yaml
└── references/
    └── conversion-checklist.md

文件	作用
`SKILL.md`	skill 的核心说明，定义何时触发以及执行规则。
`README.md`	当前仓库的使用说明。
`README.html`	当前仓库的可交互使用说明。
`agents/openai.yaml`	skill 在 Codex UI 中展示的元数据。
`references/conversion-checklist.md`	转换完成前的检查清单。
`LICENSE`	MIT 开源许可证。

质量要求

README.html 没有丢失 README.md 的信息。
已扫描项目结构，并把关键入口、脚本、配置、部署文件和测试信息体现在 HTML 中。
README 中的命令、配置、入口和部署说明尽量与真实项目文件交叉校验。
关键事实有来源标记或来源说明。
README 与项目文件冲突的地方有可见提示。
真实密钥、token、数据库密码、私钥等敏感信息不会出现在 HTML 或复制内容里。
原文中的所有标题、命令、代码块、表格、链接、图片和配置项都被保留。
代码块和关键参数都有复制入口。
左侧目录、标签页和分页之间能正确联动，不能出现目录点了但内容仍在隐藏标签页里的情况。
直接打开 README.html#某个章节 时，页面能自动显示对应标签页并定位到章节。
生成结果只有一个单文件 README.html，CSS 和 JavaScript 都内联在这个文件里。
参数演示使用的是 README 中出现过的真实字段，或明确标注为示例值。
交互控件可以通过键盘访问，并有清晰的激活和反馈状态。
HTML 可以直接从本地打开，不依赖外部 CDN。
移动端不会出现正文或按钮严重溢出。

许可证

本项目使用 MIT License。详见 LICENSE。