mcpField
D
doc-append-log

doc-append-log

github.com/shyxin文档处理552 次安装今天更新
代码仓库

关于 doc-append-log

doc-append-log 是供项目团队和 Agent 使用的文档历史追加机制，以索引和脚本记录设计、决策与变更，同时保留旧记录原貌。

主要功能

  1. 01历史文档只追加、不改写
  2. 02按日期命名新文档
  3. 03在 INDEX.md 维护状态索引
  4. 04脚本定位目录并初始化索引
  5. 05避免覆盖已有文件

适用场景

  1. 01记录设计决策与改造日志
  2. 02用新文档取代旧说明并保留历史
  3. 03让 Agent 跨会话追踪项目演进

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shyxin/skills --skill doc-append-log

安装后在 Claude Code 中输入/doc-append-log确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
convention.md
scripts/
append_entry.sh
init_index.sh
locate_docs.sh

详细介绍

来自项目 README

文档/日志追加历史机制（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），也接受显式路径参数。不破坏任何已有文件。

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

评论

支持 Markdown