shyxin 文档/日志追加历史机制（doc-append-log）
把项目的文档与日志沉淀成只追加、不改写的历史，让任何智能体（CodeBuddy / Claude Code / Codex）读 INDEX.md 就能拼出全貌，且原始记录永不被覆盖。
何时使用
- 项目里要新增一份设计记录、决策纪要、改造日志、复盘、变更说明。
- 已有文档需要被"取代"但不想改写原文件，只想加新文件并在索引里标注状态。
- 智能体需要在多次会话间保持对项目演进的连续理解。
核心约定（只追加，不改写）
- 每篇历史/结论文档创建后不再修改其内容，保留原貌作为历史。
- 新增内容时新建一个
YYYY-MM-DD_主题.md文件，并在INDEX.md末尾追加一行索引项；不回改旧文档。 - 智能体阅读顺序：先读
INDEX.md→ 按"状态"定位需关注的文档 → 按需精读对应 md。 - 状态含义：
当前事实：最新且生效当前参考：仍有效，但属于某专题沉淀历史背景：已被取代，仅作溯源
文件名用日期前缀（
2026-08-14_改造全过程日志.md）是为了让目录天然按时间有序；即使不重命名旧文件，也能靠INDEX.md里记录的日期掌握先后。
用法（脚本辅助，保证结构统一）
脚本位于 scripts/，目录无关：不硬编码 docs/，而是先定位文档目录（用 locate_docs.sh），也接受显式路径参数。不破坏任何已有文件。
# 0) 定位文档目录（优先已有 INDEX.md 的目录；否则 docs/log/logs/ 等常见候选；否则回退 docs）
bash scripts/locate_docs.sh # 打印要用的目录
bash scripts/locate_docs.sh log # 也可显式指定，如同事放在 log/
# 1) 初始化索引（已存在则跳过，绝不覆盖）
bash scripts/init_index.sh # 用定位到的目录
bash scripts/init_index.sh log # 或显式指定
# 2) 追加一篇新文档 + 自动在索引末插入一行
bash scripts/append_entry.sh "" "改造全过程日志" 当前事实 "从三版演进到新版改造的完整记录"
bash scripts/append_entry.sh log "故障排查复盘" 当前参考 "某次线上故障的排查与结论"
locate_docs.sh [目录]：返回文档目录——传了路径就用路径；否则优先返回已有INDEX.md的目录，再退而求其次返回第一个存在的常见候选（docs/doc/document/documentation/log/logs/logs/docs/wiki），都没有则回退docs。init_index.sh [目录]：在目录下生成INDEX.md（含约定说明、时间线表格、追加哨兵）。若已存在则提示跳过。append_entry.sh [目录] <主题> [状态] [摘要]：创建YYYY-MM-DD_<主题>.md（同名已存在则跳过创建，不覆盖），并在INDEX.md的哨兵前插入索引行（已存在则跳过追加）。
阅读入口
智能体介入任意项目时，先用 locate_docs.sh 定位文档目录（或采用用户指定的路径，可能叫 docs/、log/、logs/，也可能是你中途加入的某个项目的 docs/），再阅读其中的 INDEX.md；若不存在且用户希望沉淀历史，可调用 init_index.sh 建索引，之后每次变更用 append_entry.sh 追加。
设计取舍
- 为什么不改写原 md：智能体在后续会话读取时，能拿到当时真实写下的结论，避免被后来的"修订"误导；溯源也靠原文。
- 为什么用 INDEX.md 而非纯靠文件名排序：纯文件名排序无法表达"哪篇是当前事实、哪篇已被取代"；索引用状态标记解决这一点，且是智能体的单一入口。
- 为什么脚本也要轻量：约定若只写在文档里，容易被多次会话写歪；两个小脚本把"建索引 / 追加一行"固化成命令，结构才稳定。