代码变更日志与 HTML 查看器（Code Changelog）

将 AI 生成的所有代码变更记录到 reviews 文件夹中，并通过简易 HTML 查看器在浏览器中实时查看。每次修改都会生成文档，通过 Python 服务器即可立即确认。

核心功能

• 自动生成文档：每次修改都在 reviews 文件夹中生成 MD 文件
• 简易 HTML 查看器：无需安装，仅需 Python 即可运行
• 自动更新 index.html：添加新文档时自动刷新文件列表
• 实时服务器：在 http://localhost:4000 即时查看
• 暗色模式 UI：GitHub 风格的精美文档站点
• 导航：自动生成文件列表，方便浏览
• Markdown 渲染：代码高亮和 diff 展示
• 最新文档优先：最近编写的文档默认显示

快速开始

1. 初始设置（仅首次）

# 无需安装！只要有 Python 就行
python3 create_changelog.py

2. 开发过程中使用

from code_changelog_tracker import CodeChangeLogger

# 创建记录器
logger = CodeChangeLogger("项目名", user_request="需求描述")

# 记录变更
logger.log_file_creation("main.py", "代码内容", "原因")
logger.save_and_build()  # 保存！

3. 启动文档服务器

# 在 reviews 文件夹启动 Python 服务器
cd reviews
python3 -m http.server 4000

# 在浏览器中查看
# http://localhost:4000

或后台运行：

cd reviews && python3 -m http.server 4000 &

项目结构

your-project/
├── reviews/                    # 文档根目录
│   ├── index.html             # HTML 查看器（自动生成）
│   ├── README.md              # 首页
│   ├── SUMMARY.md             # 导航（自动生成）
│   │
│   ├── 20251020_140000.md    # 变更记录 1
│   ├── 20251020_140530.md    # 变更记录 2
│   ├── 20251020_141200.md    # 变更记录 3
│   └── ...
│
├── code_changelog_tracker.py  # 记录器脚本
└── create_changelog.py         # 变更记录脚本

使用场景

场景 1：边开发边文档化

logger = CodeChangeLogger("登录功能")

# 第一个任务
logger.log_file_creation("auth.py", "def login(): pass", "登录函数")
logger.save_and_build()
# -> 生成 reviews/20251020_140000.md
# -> 自动更新 index.html（添加到文件列表）
# -> 默认页面变更为 20251020_140000.md

# 第二个任务
logger.log_file_modification("auth.py", "旧代码", "新代码", "添加加密")
logger.save_and_build()
# -> 生成 reviews/20251020_140530.md
# -> 自动更新 index.html（刷新文件列表）
# -> 默认页面变更为 20251020_140530.md

# 第三个任务
logger.log_file_creation("test_auth.py", "测试代码", "测试")
logger.save_and_build()
# -> 生成 reviews/20251020_141200.md
# -> 自动更新 index.html（刷新文件列表）
# -> 默认页面变更为 20251020_141200.md

# 在浏览器访问 http://localhost:4000
# -> 自动显示最新文档！
# -> 左侧导航可查看之前的版本

场景 2：后台服务器运行

# 终端 1：启动文档服务器（保持运行）
cd reviews && python3 -m http.server 4000

# 终端 2：开发工作
python3 your_dev_script.py  # 调用 logger.save_and_build()

# 刷新浏览器查看最新文档！

场景 3：团队共享

# 将 reviews 文件夹与团队成员共享
# 可部署到 GitHub Pages、Netlify 等
# 或在内部 Web 服务器上托管

实现代码

code_changelog_tracker.py（主记录器）

使用已生成的文件。主要方法：

• log_file_creation() - 记录文件创建
• log_file_modification() - 记录文件修改
• log_file_deletion() - 记录文件删除
• update_index_html() - 自动更新 index.html 文件列表
• save_and_build() - 保存 + 更新 SUMMARY + 更新 index.html

reviews/index.html（HTML 查看器）

自动生成和更新！ 每次调用 save_and_build() 时都会刷新为最新文件列表。

提供功能：

• Markdown 自动渲染（marked.js）
• 暗色模式 UI（GitHub 风格）
• 文件列表导航（自动更新）
• 代码高亮
• 最新文档默认显示
• 活动链接高亮

简易使用方法

第一步：记录变更

from code_changelog_tracker import CodeChangeLogger

logger = CodeChangeLogger(
    "Daily Signal App - 注册功能",
    user_request="实现邮箱/密码注册"
)

# 记录文件创建
logger.log_file_creation(
    "lib/screens/signup_screen.dart",
    "SignUpScreen 代码...",
    "实现注册页面"
)

# 记录文件修改
logger.log_file_modification(
    "lib/providers/auth_provider.dart",
    "旧代码",
    "新代码",
    "添加 signUp 方法"
)

# 保存
logger.save_and_build()

第二步：启动服务器

cd reviews
python3 -m http.server 4000

第三步：在浏览器查看

http://localhost:4000

HTML 查看器特点

暗色模式 UI

• GitHub 风格的 Markdown 渲染
• 代码块高亮
• 响应式布局

导航

• 左侧自动显示文件列表
• 按日期/时间排序
• 点击即可轻松跳转

Markdown 渲染

• 支持标题、列表、代码块
• 显示 Diff
• 支持 Emoji

命令指南

启动服务器

cd reviews
python3 -m http.server 4000

更改端口

python3 -m http.server 3000
python3 -m http.server 8080

后台运行

cd reviews && python3 -m http.server 4000 &

关闭服务器

# 前台：Ctrl+C
# 后台：查找进程 ID 并终止
lsof -ti:4000 | xargs kill -9

部署选项

GitHub Pages

# 将 reviews 文件夹推送到 gh-pages 分支
git subtree push --prefix reviews origin gh-pages

Netlify

# 将 reviews 文件夹部署到 Netlify
# Build command：（无）
# Publish directory：reviews

Vercel

# 将 reviews 文件夹部署到 Vercel
vercel reviews

最佳实践

1. 保持服务器运行：开发期间持续运行服务器
2. 小单位记录：将每项工作拆分为小单位进行文档化
3. 明确标题：项目名称写清楚
4. 定期备份：使用 Git 管理 reviews 文件夹
5. 浏览器书签：添加 http://localhost:4000 为书签

故障排除

端口已被占用

# 使用其他端口
python3 -m http.server 4001

# 或终止现有进程
lsof -ti:4000 | xargs kill -9

文件未显示

# 确认 index.html 是否存在
ls reviews/index.html

# 若不存在，调用 logger.save_and_build() 时会自动生成

重要：调用 logger.save_and_build() 后 index.html 会自动更新！

• 新增 Markdown 文件时自动刷新文件列表
• 最新文件自动设为默认页面
• 仅需刷新浏览器即可查看最新文档

Markdown 未渲染

• 清除浏览器缓存（Cmd+Shift+R / Ctrl+Shift+R）
• 重启服务器
• 确认 index.html 是否最新（重新执行 save_and_build()）

优势

无需安装

• 不需要 Node.js、npm、HonKit
• 只要有 Python 即可使用
• 无依赖

快速运行

• 1 秒内启动服务器
• 即时确认文档

简单部署

• 只需部署 reviews 文件夹
• 作为静态站点可托管在任何地方

自动更新

• save_and_build() 调用时 index.html 自动刷新
• 无需手动编辑
• 始终保持最新文件列表
• 最新文档自动设为默认页面

对比：HonKit vs 简易 HTML

许可证

MIT License

无需安装！用 Python 直接运行，在浏览器中查看！