# Doc Append Log

> 维护"只追加、不改写"的项目文档/日志历史机制：每次变更新建 YYYY-MM-DD_主题.md，并用 INDEX.md 时间线索引串联，供 CodeBuddy / Claude Code / Codex 等智能体阅读完整历史。当用户说"记录一下""写个日志""追加文档""整理文档历史""建个 docs 索引""把这次改动记下来"时使用。model-invoked。

- Skill: `shyxin/doc-append-log` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add shyxin/doc-append-log`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shyxin/doc-append-log/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: shyxin (https://skillmd.com/u/shyxin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shyxin/doc-append-log

---


# 文档/日志追加历史机制（doc-append-log）

把项目的文档与日志沉淀成**只追加、不改写**的历史，让任何智能体（CodeBuddy / Claude Code / Codex）读 `INDEX.md` 就能拼出全貌，且原始记录永不被覆盖。

## 何时使用

- 项目里要新增一份设计记录、决策纪要、改造日志、复盘、变更说明。
- 已有文档需要被"取代"但不想改写原文件，只想加新文件并在索引里标注状态。
- 智能体需要在多次会话间保持对项目演进的连续理解。

## 核心约定（只追加，不改写）

1. 每篇历史/结论文档**创建后不再修改其内容**，保留原貌作为历史。
2. 新增内容时**新建**一个 `YYYY-MM-DD_主题.md` 文件，并**在 `INDEX.md` 末尾追加一行**索引项；不回改旧文档。
3. 智能体阅读顺序：先读 `INDEX.md` → 按"状态"定位需关注的文档 → 按需精读对应 md。
4. 状态含义：
   - `当前事实`：最新且生效
   - `当前参考`：仍有效，但属于某专题沉淀
   - `历史背景`：已被取代，仅作溯源

> 文件名用日期前缀（`2026-08-14_改造全过程日志.md`）是为了让目录天然按时间有序；即使不重命名旧文件，也能靠 `INDEX.md` 里记录的日期掌握先后。

## 用法（脚本辅助，保证结构统一）

脚本位于 `scripts/`，**目录无关**：不硬编码 `docs/`，而是先定位文档目录（用 `locate_docs.sh`），也接受显式路径参数。**不破坏任何已有文件**。

```bash
# 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 而非纯靠文件名排序**：纯文件名排序无法表达"哪篇是当前事实、哪篇已被取代"；索引用状态标记解决这一点，且是智能体的单一入口。
- **为什么脚本也要轻量**：约定若只写在文档里，容易被多次会话写歪；两个小脚本把"建索引 / 追加一行"固化成命令，结构才稳定。