code-changelog

使用简单 HTML 查看器查看代码变更日志

这是一套解决方案，可将 AI 生成的所有代码变更记录到 reviews 文件夹，并通过简单的 HTML 查看器在浏览器中实时查看。

🎯 核心功能

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

🚀 快速开始

1. 初始设置（仅首次需要）

# 설치 불필요! Python만 있으면 OK
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", "old", "new", "암호화 추가")
logger.save_and_build()
# → reviews/20251020_140530.md 생성
# → index.html 자동 업데이트 (파일 목록 갱신)
# → 기본 페이지가 20251020_140530.md로 변경

# 세 번째 작업
logger.log_file_creation("test_auth.py", "test code", "테스트")
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 등에 배포
# 또는 내부 웹서버에 호스팅

🛠️ 实现代码

code_changelog_tracker.py（主记录器）

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

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

reviews/index.html（HTML 查看器）

将自动生成和更新！ 每次调用 save_and_build() 时，都会根据最新文件列表进行更新。

提供的功能：

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

📋 简单用法

步骤 1：记录变更

# create_changelog.py 예시
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",
    "old code",
    "new code",
    "signUp 메서드 추가"
)

# 저장
logger.save_and_build()

步骤 2：启动服务器

cd reviews
python3 -m http.server 4000

步骤 3：在浏览器中查看

http://localhost:4000

🎨 HTML 查看器特点

深色模式 UI

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

导航

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

Markdown 渲染

• 支持标题、列表和代码块
• 显示 Diff
• 支持表情符号

💻 命令指南

启动服务器

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

🔧 端口设置

默认端口：4000

python3 -m http.server 4000
# → http://localhost:4000

使用其他端口

python3 -m http.server 3000
# → http://localhost:3000

解决端口冲突

# 다른 포트 사용
python3 -m http.server 4001

# 또는 기존 프로세스 종료
lsof -ti:4000 | xargs kill -9

🌐 部署选项

GitHub Pages

# reviews 폴더를 gh-pages 브랜치에 푸시
git subtree push --prefix reviews origin gh-pages

Netlify

# Netlify에 reviews 폴더 배포
# Build command: (없음)
# Publish directory: reviews

Vercel

# Vercel에 reviews 폴더 배포
vercel reviews

📝 最佳实践

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

🎓 使用示例

实现注册功能

logger = CodeChangeLogger(
    "Daily Signal App - 회원 가입",
    user_request="이메일/비밀번호 회원 가입 기능"
)

# CustomTextField 생성
logger.log_file_creation(
    "lib/widgets/custom_text_field.dart",
    "CustomTextField 코드...",
    "재사용 가능한 입력 필드 위젯"
)

# SignUpScreen 생성
logger.log_file_creation(
    "lib/screens/signup_screen.dart",
    "SignUpScreen 코드...",
    "회원 가입 화면 구현"
)

# AuthProvider 수정
logger.log_file_modification(
    "lib/providers/auth_provider.dart",
    "old code",
    "new code with signUp",
    "signUp 메서드 추가"
)

# 저장
logger.save_and_build()

# 서버에서 확인: 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 文件夹
• 可作为静态网站托管在任何地方

自动更新 ⭐ NEW!

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

📊 对比：HonKit 与 Simple HTML

功能	HonKit	Simple HTML
安装	需要 npm、Node.js	只需要 Python
构建时间	5-10 秒	即时
依赖项	多	无
自定义	高	中
搜索功能	有	使用浏览器搜索
部署	_book 文件夹	reviews 文件夹

许可证

MIT 许可证

---

无需安装！用 Python 立即运行，并在网页浏览器中查看！ 🎉