Understand and verify the code behind your Vibe Coding workflow.

English · 中文说明

Simple Reviewer is a Codex skill for people who build and iterate with AI coding agents. It breaks AI-written code into functional blocks, explains what each block does and where it lives, and checks whether the implementation actually meets your goals using recorded evidence.

Use it after a Vibe Coding session, when inheriting unfamiliar AI-generated code, or before accepting a change. Start with a readable explanation, then inspect the behavior, evidence, and remaining gaps. Code that looks plausible is not enough to establish that a feature works.

Themes: AI-assisted coding · Vibe Coding · code explanation · evidence-based review.

Vibe Coding is fast, but a working-looking result can still hide an unclear requirement, an untested path, or a risky side effect. Simple Reviewer 1.2 adds a plain-language control layer around the coding session:

1. Clarify the goal — turn a natural-language request into observable acceptance criteria, assumptions, and open questions.
2. Explain the change — translate the AI's file and code changes into user-visible behavior and possible impacts.
3. Read the implementation — map functional blocks, inputs, outputs, source locations, and connected paths.
4. Verify behavior — connect each goal to an independent check and record what actually happened.
5. Surface risks — explain concrete data, credentials, external-service, cost, permission, or deployment effects and whether the action actually ran.
6. Choose the next step — give one to three specific follow-up checks or fixes, with a reason for each.

The report keeps these statements separate: code exists, a local check passed, a real user path worked, and the original goal is complete. A fluent explanation is not evidence by itself.

Full desktop diagram · Mobile diagram

Provide your code and intended outcome. The skill maps functional blocks, explains their responsibilities and source locations, performs applicable checks, and generates standalone explanations. A full review report is available when requested.

The HTML report is organized like a small review workspace: the goal and current verdict come first, followed by change summary, functional blocks, verification evidence, risks, and next actions. Technical details remain expandable so a new user can read the conclusion before opening source code.

Contrast follows the content: parallel cards use the same white treatment. Within a block, white input, green processing, and light-green output panels make the transformation visible; black section headers establish the reading hierarchy. Colors do not rotate with block IDs.

Status badges describe verification, not a quality score: green means verified within the recorded scope; red means a confirmed issue; yellow means pending verification; gray means unchecked. The responsibility graph uses these status colors too. Static reading does not count as a successful runtime check. Missing runtime access is recorded explicitly.

• Define acceptance criteria from your goals before reviewing the implementation.
• Explain functional blocks through inputs, processing, outputs, and upstream/downstream relationships.
• Identify source files, symbols, line ranges, and relevant code excerpts.
• Connect findings to actual observations, evidence, and verification limits.
• Read offline HTML reports with diagrams, keyboard navigation, expandable source, filtering, and print support.
• Detect changes to registered source files and evidence logs with SHA-256 snapshots; stale evidence requires revalidation.
• Produce a beginner-friendly goal brief, change summary, evidence matrix, risk notes, and next-action checklist when the reviewing agent has enough information to record them.
• Explain technical terms in two layers: a plain-language answer first, then the file, symbol, line range, and source excerpt.

The generator validates and displays an authored review record. It does not execute recorded commands or discover semantic defects on its own. The reviewing agent reads the code, performs appropriate checks, and records the results.

Copy the complete simple-reviewer-v1 directory into your configured Codex personal skills directory. The default Windows location is:

%USERPROFILE%\.codex\skills\simple-reviewer-v1

Start a new Codex conversation or refresh the skill list, then ask:

$simple-reviewer-v1 Review the code we just changed. Explain each functional block,
identify its source locations, verify whether it meets my goals, and generate
an HTML breakdown with a Markdown companion. Review only; do not change the code.

You do not need to repeat this wording exactly. The skill currently defaults to Simplified Chinese for explanations and reports; request English explicitly when needed. This bilingual README does not change that default.

Tool version: 1.2.0. Invocation: $simple-reviewer-v1. Display name: Simple Reviewer · 简单的审阅者1.0. Update the complete installed directory to include the generator and templates; updating SKILL.md alone is insufficient. Further Chinese documentation: usage guide and review record contract.

For a request such as “let users upload an Excel file and show the number of valid and invalid rows,” the skill should make the hidden checks visible:

The report uses green, red, yellow, and gray for verification state. It distinguishes actual execution from static reading, states the covered scope, and marks stale evidence. A static reading or a passing unit test never silently becomes full goal completion.

To update an existing installation, run powershell -NoProfile -File scripts/sync-installed-skill.ps1 from this checkout. It installs and hash-verifies the complete skill, archives the previous installation outside the active skills directory, and preserves the old files as a backup. Open a new Codex conversation to use the new invocation.

Python 3 is required; the generator uses only the standard library.

python -B scripts/test_reviewer_report.py
python -B scripts/reviewer_report.py validate assets/review.example.json
python -B scripts/reviewer_report.py breakdown assets/review.example.json --out review-output
python -B scripts/reviewer_report.py render assets/review.example.json --out review-output

Open review-output/reviewer-overview.html after render for the plain-language entry, then explore code-breakdown.html. breakdown produces only the two explanation files; render produces all seven files listed above. Existing schema 1.0 records remain supported. Optional context is authored by the reviewer; the generator does not infer AI changes or execute checks.

The visual direction combines Open Design's homepage reading hierarchy with its Arena page's comparison and grouping patterns, using the requested ai-website-cloner-template inspection workflow. It is adapted for offline code review: original report content, embedded fonts, local links, and evidence-state colors. It does not reproduce Open Design's branding, illustrations, rankings, or hosted services. See the design notes.

The HTML reports use the Arena reference's black, white, and green contrast: #172017 section headers, white peer cards, #70F28B processing panels, and #E1F1E1 output or supporting panels. Parallel items share a style; emphasis belongs to a transformation, a changed value, or a reading milestone. Albert Sans is embedded for offline reading under the SIL Open Font License; see assets/fonts/OFL.txt. Headlines use lighter 550–560 weights, section titles are 24–36px, and diagrams keep legible labels instead of shrinking the entire graphic on a phone. Verification badges retain their independent red/yellow/green/gray meanings. This is a style reference, not a copy of OpenDesign content or branding.

All three HTML reports now share a fixed page navigation bar: Overview / Code breakdown / Full report, with the current page highlighted. To link back to a separate illustrated guide, add --guide-page path/to/guide.html --guide-label "Illustrated guide" to the render command and provide report links in that guide. This adds a local relative link; it does not bundle or upload the guide. Keep the generated pages together when moving or sharing them. A breakdown-only export never links to reports that were not generated.

The bundled order-export example deliberately contains a pagination bug: exporting more than 20 matching orders loses records. Rebuild its reproducible evidence with:

python -B assets/order-export/build_example.py

The example is not evidence for your project. Generated reports may include source code and local paths; share them according to your project's rules.

Optional browser checks require Node.js and Playwright; the report generator does not:

npm install --no-save --package-lock=false playwright@1.56.1
npx playwright install chromium
node scripts/test_breakdown_browser.cjs review-output/code-breakdown.html review-output/browser
node scripts/test_overview_browser.cjs review-output/reviewer-overview.html review-output/overview-browser
node scripts/test_workflow_browser.cjs
node scripts/test_page_navigation_browser.cjs

CI runs Python tests on Windows and Linux and checks the illustrated report in Chromium, including source expansion, keyboard navigation, filtering, offline requests, and 390/700/1024px layouts. The example reports and screenshots are attached to Actions runs.

Maintainers can run powershell -NoProfile -File scripts/publish-github.ps1 from a clean, committed main checkout. It pushes main, applies the repository name, bilingual About description and topics from repository metadata, updates the local origin after a successful rename, preserves existing topics, and verifies the result. It uses the configured Git credential helper in memory; the account must have permission to edit repository settings. If a metadata request fails after the push, rerun the script after resolving access. Add -UpdateInstalledSkill to migrate the personal skill installation in the same run.

The helper uses OpenSSL and HTTP/1.1 for Git. It also uses the Windows system proxy when no Git or proxy environment setting is present. If Git reports a connection reset or timeout, pass -ProxyUrl with the actual HTTP proxy address shown by your proxy application. The override applies only to this run; it does not edit global Git configuration. A browser connection alone does not verify the Git connection.

No open-source license is currently included. Rights and reuse permissions remain with the rights holder unless a license is added.

一个 Codex skill，可用于拆解ai编写或修改的代码，说明各功能板块的作用和代码位置，并用可复核的运行证据检查作用是否生效、原始需求是否完成--辅助你与ai代码共同工作。适用于重度ai编码依赖，可以在不太懂代码编写的同时读懂ai写的代码结构和思路。

主题：AI 辅助编程 · Vibe Coding · 代码解释 · 基于证据的审查。 适合在 AI 编程完成一个功能后、接手不熟悉的 AI 代码时，或接受修改前使用。先读懂代码，再核对它是否完成目标。

Back to English / 返回英文

查看横版完整流程图 · 查看手机纵版流程图

将代码和希望实现的目标交给 skill。它先按职责拆解代码，说明每块的作用和位置，再根据可运行的检查核验实际行为，最后生成独立的 HTML 图文拆解与 Markdown 文字版。需要完整审查时，还可生成总报告和有效记录。

颜色表示检查状态，不是文件质量评分： 绿色为在所记录范围内实际验证通过，红色为有证据确认的问题，黄色为待核实，灰色为尚未验证。缺少运行条件时会明确说明，不会把静态阅读说成运行通过。

• 先依据用户目标建立验收项，再按实际职责划分代码板块。
• 默认生成独立的 code-breakdown.html 图文页面和 code-breakdown.md 文字版：逐块解释职责、输入输出、文件/符号/行号、源码片段、验证状态、证据和限制。
• HTML 内置板块导航、输入→职责→输出示意、可选步骤图和教学样例；支持源码展开、点击/键盘跳转、筛选及打印，离线可读，适配手机。
• 使用流程图标记状态：README 使用 SVG 展示整体处理流程，审查报告使用 Mermaid/SVG 展示代码职责；绿色表示范围内验证通过，红色表示已确认问题，黄色表示待核实，灰色表示未验证。
• 支持生成 Markdown 和离线 HTML 审查报告；报告生成器只校验记录并渲染，不执行记录内的命令。
• 提供 SHA-256 文件快照校验和 Python 标准库测试。

绿色状态只适用于明确记录的输入、环境和验证范围，不代表所有场景正确。缺少源码、依赖或环境时应保留未验证状态。

将 simple-reviewer-v1 目录复制到 Codex 个人 skills 目录下。Windows 默认路径为：

%USERPROFILE%\.codex\skills\simple-reviewer-v1

安装后在 Codex 中新开会话或刷新 skill 列表，然后调用：

$simple-reviewer-v1 检查刚刚的代码，并单独生成代码拆解文件。

完整使用方法见 使用说明。报告 JSON 格式见 报告记录规范。

要求 Python 3，无第三方依赖：

python -B scripts/test_reviewer_report.py
python -B scripts/reviewer_report.py validate assets/review.example.json
python -B scripts/reviewer_report.py breakdown assets/review.example.json --out .\review-output
python -B scripts/reviewer_report.py render assets/review.example.json --out .\review-output

内置订单导出示例故意保留“复用列表分页导致超过 20 条时导出不完整”的缺陷。构建示例会运行可复现检查并重写示例日志：

python -B assets/order-export/build_example.py

示例报告不是其他项目的检查结果。

完整审阅后先打开 review-output/reviewer-overview.html，再进入 code-breakdown.html 看详细图解。breakdown 输出 HTML 和 Markdown 两文件；render 输出上表全部七文件。现有 schema 1.0 记录兼容；缺少补充信息时明确显示缺口。变更说明由审查者基于实际基线填写，生成器不会自行推断 AI 改动或执行检查。

视觉混合参考 Open Design 首页的阅读层级与 Arena 页的信息分组，并采用指定的 ai-website-cloner-template 检视流程，按离线代码审阅场景调整。报告使用自己的内容、内嵌字体、本地链接和证据状态色；设计对应关系见设计说明。

HTML 图解采用参考 Arena 页的黑、白、绿对比：#172017 黑色标题栏、白色同级卡片、#70F28B 绿色处理面板和 #E1F1E1 浅绿色输出或辅助面板。并列内容保持一种样式，递进、参数改写和关键变化再用颜色强调，不按板块编号轮换颜色。标题采用较轻的 550–560 字重，小节标题约 24–36px；图中文字按阅读需要放大，窄屏可在图内滚动，避免整体缩小到看不清。验证结论仍由带文字的红、黄、绿、灰标签与状态图表示，绿色大面板不等于验证通过。内嵌 Albert Sans 字体按 SIL Open Font License 发布，许可文本见 assets/fonts/OFL.txt。这里只参考视觉语言，不复制 OpenDesign 的内容或品牌。

三张 HTML 页面都有固定的“审阅总览 / 代码拆解 / 完整报告”导航，当前页突出显示。若另有专题讲解页，生成时加 --guide-page 专题图解.html --guide-label "专题图解"，并在专题页提供进入报告的链接，即可双向切换。参数只增加本地相对链接，不打包或上传专题内容。移动、分享时请保留页面之间的目录关系；仅拆解模式不会显示未生成的完整报告入口。

当前工具版本为 1.2.0，skill 调用名为 $simple-reviewer-v1，界面名为“Simple Reviewer · 简单的审阅者1.0”。更新时用仓库完整内容替换原安装目录；仅下载单个 SKILL.md 不会更新模板和生成器。生成页面可能含源码与本地路径，请按项目约定保存和分享。

很多问题不是代码完全不能运行，而是“需求没有说清楚”“改了什么不知道”“测试通过但真实使用不对”或“AI 顺手执行了有影响的操作”。1.2 版的审阅顺序因此固定为：

我想要什么
    ↓
AI 改了什么
    ↓
代码各板块负责什么
    ↓
我实际检查了什么
    ↓
哪里仍然不能确认
    ↓
现在下一步做什么

报告会尽量生成以下内容：

• 需求翻译卡：保留用户原话，整理可观察的验收条件、假设和待确认问题。
• 目标验收矩阵：把需求、检查动作、预期结果、实际结果、证据和状态连起来。
• AI 改动说明：说明新增、修改、删除了哪些文件，以及用户能够看到的变化和潜在影响。
• 双层代码解释：先用日常语言说明“这部分负责什么”，再提供符号、行号、调用关系和源码片段。
• 风险提示：单独标出删除数据、密钥、外部服务、费用、权限、上传和部署等高影响动作。
• 下一步卡片：给出一到三个最小可执行的检查或修复动作，避免用户只能继续把错误原样丢给 AI。

没有目标、运行环境或独立证据时，报告会明确显示“未验证”，不会用“看起来合理”代替完成结论。

已有安装可在此仓库运行 powershell -NoProfile -File scripts/sync-installed-skill.ps1：脚本安装完整新版并校验文件哈希，将旧安装备份到启用中的 skills 目录之外。旧文件会保留为备份。新开 Codex 对话后使用新调用名。

可选浏览器自检（生成器本身无需 Node 或 Playwright）：

npm install --no-save --package-lock=false playwright@1.56.1
npx playwright install chromium
node scripts/test_breakdown_browser.cjs review-output/code-breakdown.html review-output/browser
node scripts/test_overview_browser.cjs review-output/reviewer-overview.html review-output/overview-browser
node scripts/test_workflow_browser.cjs
node scripts/test_page_navigation_browser.cjs

CI 在 Windows/Linux 运行 Python 测试，并在 Chromium 检查源码展开、键盘跳转、筛选、390/700/1024px 宽度及离线请求；订单示例 HTML 和截图随 Actions 产物保存。

维护者可在已提交且无未保存修改的 main 分支运行 powershell -NoProfile -File scripts/publish-github.ps1。脚本会推送 main，读取仓库元数据设置仓库名称、英中双语 About 简介和主题标签，改名成功后更新本地 origin，保留已有标签，并回读核对。凭据仅通过现有 Git 凭据助手在内存中使用；账号需有修改仓库设置的权限。如果推送后设置简介或标签失败，解决访问问题后可重新运行脚本。追加 -UpdateInstalledSkill 可在同一次运行中迁移个人 skill 安装。

脚本对 Git 使用 OpenSSL 和 HTTP/1.1；没有现有 Git 或代理环境设置时，会尝试使用 Windows 系统代理。若 Git 报连接重置或超时，可通过 -ProxyUrl 传入代理软件显示的实际 HTTP 代理地址。本次参数不会修改全局 Git 配置。浏览器能连接 GitHub，并不代表 Git 的连接也已通畅。

当前版本未附开源许可证。除非作者另行添加许可证，版权及复用权限仍由权利人保留。