write-maintenance-log

name	write-maintenance-log
description	按 NixKits 规范撰写或更新 MAINTENANCE.md 维护日志。支持软件更新记录和错误修复记录两种类型，自动关联 git commit、生成摘要、五语同步。

维护日志撰写

按 NixKits 统一规范撰写 MAINTENANCE.md 维护记录，确保格式一致、信息完整、多语同步。

自动发现契约

本技能通过纯自然语言约定发现语言扩展：

1. 扫描 — 在 skills/translate-*/ 目录下查找所有翻译技能
2. 读取 — 解析各 SKILL.md frontmatter 中的 language_code / display_name / base_language 字段
3. 注册 — 自动将发现的语言扩展纳入多语同步流程。各翻译技能的 SKILL.md 正文中定义翻译规则（词典、语序调整、假名剥离）和列名映射表（TITLE / SUBTITLE / SUMMARY 等多语对照）。

入口

本技能由 AGENTS.md 规则强制触发：每次 git push 后必须执行入口 1 的 SHA 查重流程。

本技能提供两个独立入口，根据用户意图自动匹配。

入口 1：记入维护记录

触发词：「记入维护记录」「记录本次修复」「写入维护日志」

基于当前对话中完成的软件更新或错误修复，撰写单条维护记录并插入 MAINTENANCE.md。

此入口被 nixkits-check-updates 技能在软件更新完成后自动调用。

入口 2：更新维护记录

触发词：「更新维护记录」「补全维护记录」「同步维护日志」

基于 git log 扫描全部提交历史，找出以下未记录的内容并补全：

• 未被记录的 fix(...) / feat(...) 提交
• 缺失关联 commit id 的旧记录（回填 | 提交 | 说明 | 表）
• 格式不统一、行文不规范的历史条目（统一为新格式）

执行流程：

# 1. 提取所有 fix / feat 提交（排除 docs 和 chore(pkgs) 类型）
git log --oneline --all | grep -E 'fix\(|feat\(' | while read hash msg; do
  # 检查是否已在 MAINTENANCE.md 中
  grep -q "$hash" MAINTENANCE.md || echo "MISSING: $hash $msg"
done

# 2. 对每个缺失的提交：
#    a. 按日期分组
#    b. 生成摘要（从 commit message 提取）
#    c. 按格式规范生成条目
#    d. LIFO 插入 MAINTENANCE.md

# 3. 补全已有记录缺失的 commit id
#    a. 解析所有现有记录日期
#    b. 按 ±2h 窗口匹配未关联的提交
#    c. 补充到对应记录的提交表中

# 4. 多语同步并提交

此入口不修改软件版本表中已记录的版本号与 hash 值，仅补充元数据。

记录范围

维护日志覆盖以下类别的变更：

类别	记录条件	示例
软件	版本更新或 bug 修复	chore(pkgs): bump codewhale fix(mcp-searxng): ...
技能	新增技能、重大章节添加、bug 修复、重大重构	feat(skill): extract write-maintenance-log fix(skill): generalize 基本情報 rule refactor(skills): generalize hardcoded content
文档	模块/包文档的实质性更新（新增章节、配置指南、故障排查、迁移指南）	docs(mcp-searxng): add CodeWhale config docs(llama-cpp-rocm): add multilingual migration guide
模块	新增模块或重大功能添加	feat(rcc-fix): add NixOS module feat(llama-cpp-rocm): restore modelsPreset

不记录：纯机械性多语 sync（docs(skills): sync ... to multilingual docs）、仅涉及维护日志本身的提交（docs(MAINTENANCE): ...）。

记录类型

类型 1：软件版本更新

当上游发布新版本并完成构建时，记录以下字段：

• 日期时间（ISO 8601 精确秒，JST 时区）
• 一句话摘要（允许从上游 release note 摘录）
• 关联提交表（所有相关 commit id 及说明）
• 软件版本表（包名、旧版本、新版本）
• 有变更的 hash（省略无变更项）

类型 2：错误修复

当修复了影响功能的 bug（即使无版本变更）时，记录：

• 日期时间
• 一句话摘要（描述修复内容）
• 关联提交表

判断标准：git log 中 fix(...) 或 feat(...) 类型、且涉及包/模块功能变更的提交应记录。纯文档 (docs(...)) 不记录。

类型 3：技能与文档变更

当技能有重大更新（新增技能、新增章节、重大重构）或模块/包文档有实质性内容添加时，记录：

• 日期时间
• 一句话摘要
• 关联提交表

判断标准：feat(skill): refactor(skill): docs(skill):（新增章节）fix(skill): 应记录。docs(skills): sync 机械性同步不记录。

类型 4：CI/CD 与二进制缓存变更

当项目的 CI/CD 工作流或二进制缓存配置发生变更时，记录：

• 日期时间
• 一句话摘要（如「添加 CI/CD 工作流与 Cachix 二进制缓存」）
• 关联提交表
• CI 配置表（可选，记录工作流变更概要）

记录示例：

## <timestamp>

**摘要**：CI/CD 与二进制缓存 — 添加 GitHub Actions 构建矩阵 + Cachix 推送，README 加入缓存徽章与 NixOS 配置方案

| 提交 | 说明 |
|------|------|
| `<sha7>` | feat: add CI/CD workflow, binary cache, and AGENTS.md |
| `<sha7>` | docs: add cache badge and NixOS config instructions |

判断标准：feat: fix(ci): 或新增 .github/workflows/、缓存配置变更时应记录。

格式规范

章节标题

ISO 8601 精确到秒的日期时间，JST 时区（+09:00）。

时间戳获取规则

强制使用工具，禁止手动输入：

# 已有提交 → 从 git commit 时间获取（首选）
git log -1 --format="%ai" <commit>

# 尚无提交 → 使用系统当前时间（备用）
TZ='Asia/Tokyo' date '+%Y-%m-%dT%H:%M:%S+09:00'

禁止：

• 使用 T00:00:00 占位符
• 凭记忆或估算填写时间
• 使用非 JST 时区（除非 commit 原始时区非 JST）

业务逻辑：维护日志的时间戳在后续审计、关联 git history、跨语言同步校验中作为唯一标识使用。占位时间破坏了时间线的完整性，且人工填写在多任务并行时极易出错。即使当时记得，延迟提交后时间也会偏移。

验证

生成条目后，立即执行：

grep 'T00:00:00' MAINTENANCE.md && echo "ERROR: placeholder found" || echo "OK"

## 2026-06-14T07:56:11+09:00

行文标准

• 语言：中文（MAINTENANCE.md）、英文（docs/MAINTENANCE.en.md）、日文（docs/MAINTENANCE.ja.md）
• 标题：zh # 维护日志、en # Maintenance Log、ja # メンテナンスログ
• 摘要：以粗体 **摘要**（en: **Summary**, ja: **概要**）开头，一句话说明变更。格式为 <包名> <版本号> — <一句话简述>
  • 多个包用「；」分隔
  • 新增包：<包名> <版本号> — 新包
  • 无版本变更的修复：fix(<包名>): <简述>
• 提交表：表头 | 提交 | 说明 |（en: | Commit | Description |, ja: | コミット | 説明 |）
  • 关联提交按时间升序排列
  • commit id 使用短格式（7 位）
• 软件版本表：表头 | 软件名 | 旧版本 | 新版本 |（en: | Package | Old | New |, ja: | パッケージ | 旧 | 新 |）
  • 已有软件更新：| pkg | old | new |
  • 首次添加：新旧版本列合并为一列，| pkg | 新增 v<version> |
  • hash 行以 | 　 | <hash类型> | <旧值> → <新值> | 缩进

统一规则

规则	说明
LIFO	最新记录插入文件顶部（紧随 --- 分隔线）
仅记录实质变更	无实际软件/配置变更时不写入
省略无变更信息	构建验证结果不记录；未变化的 hash 不标出
新包合并列	首次添加时旧版本列留空或合并
纯 bug 修复无版本表	若本次无软件版本变更，省略软件版本表

撰写流程

第 1 步：确认记录内容

与用户确认摘要描述（若为自动触发则从 commit message 提取）。

# 自动生成摘要 — 从最新 commit 提取
git log -1 --format="%s"

第 2 步：查找关联提交

# 查找本次变更相关的所有提交
git log --oneline --since="<时间范围>"

第 3 步：生成维护记录

按格式规范生成新条目，插入到 MAINTENANCE.md 顶部（第一个 --- 分隔线之后）。

第 4 步：多语同步

必须执行，不可跳过。 MAINTENANCE.md（zh 基准）写入后，立即同步到全部已注册语言版本。

4a. 发现已注册语言

# 基准语言 + 基础扩展
BASE_LANGS="zh en ja"

for skill in skills/translate-*/SKILL.md; do
  lang=$(sed -n '/^language_code:/s/.*: *//p' "$skill")
  EXTRA_LANGS="$EXTRA_LANGS $lang"
done

4b. 逐语言翻译并写入

对每个非 zh 语言，以 zh 基准 MAINTENANCE.md 为蓝本：

1. 复制结构：保留所有 ## <timestamp> 条目、提交表、软件版本表的骨架
2. 替换固定标记：按映射表替换标题（# 维护日志）、摘要前缀（**摘要**）、表头
3. 翻译摘要正文：**摘要** / **Summary** 后的自然语言正文必须翻译为目标语言
   • en → AI 直译
   • ja → AI 直译
   • pcn → 按 skills/translate-pseudocn/SKILL.md 规则假名剥离 + 语序保持
4. 保持原文：commit SHA、包名、版本号、hash 值、命令、路径不翻译
5. 写入对应 docs/MAINTENANCE.<lang>.md

4c. 验证同步完整性

# 各语言版本条目数必须一致
zh_count=$(grep -c '^## 20' MAINTENANCE.md)
for f in docs/MAINTENANCE.*.md; do
  count=$(grep -c '^## 20' "$f")
  if [ "$count" -ne "$zh_count" ]; then
    echo "MISMATCH: $f has $count entries, expected $zh_count"
  fi
done

条目数不一致时必须修复后再进入第 5 步提交。

多语映射表

|------|----|----|-----|---------|-----| | TITLE | # 维护日志 | # Maintenance Log | # メンテナンスログ | # ﾒﾝﾃﾅﾝｽ ﾛｸﾞ | # 維護記録 | | SUBTITLE | NixKits 软件更新维护日志。 | NixKits package update changelog. | NixKits パッケージ更新履歴。 | ﾆｯｸｽｷｯﾄ ﾊﾟｯｹｰｼﾞ ｱｯﾌﾟﾃﾞｰﾄ ﾁｪﾝｼﾞﾛｸﾞ。 | NixKits 軟件更新維護記録。 | | SUMMARY | **摘要** | **Summary** | **概要** | **ｻﾏﾘｰ** | **摘要** | | COMMIT_HDR | \| 提交 \| 说明 \| | \| Commit \| Description \| | \| コミット \| 説明 \| | \| ｺﾐｯﾄ \| ﾃﾞｨｽｸﾘﾌﾟｼｮﾝ \| | \| 提交 \| 説明 \| | | SW_TABLE_HDR | \| 软件名 \| 旧版本 \| 新版本 \| | \| Package \| Old \| New \| | \| パッケージ \| 旧 \| 新 \| | \| ﾊﾟｯｹｰｼﾞ \| ｵｰﾙﾄﾞ \| ﾆｭｰ \| | \| 軟件名 \| 舊版本 \| 新版本 \| |

第 5 步：提交

git commit -m "docs(MAINTENANCE): record <date> — <summary>"

软件更新示例

## 2026-06-14T07:56:11+09:00

**摘要**：codewhale 0.8.59 — 修复若干 TUI 渲染问题；mcp-searxng 1.4.0 — 新增 HTTP 传输模式

| 提交 | 说明 |
|------|------|
| `a71aae7` | chore(pkgs): bump codewhale 0.8.59 |
| `e8f0299` | chore(pkgs): bump mcp-searxng 1.4.0 |
| `ec7d5ca` | docs(MAINTENANCE): record 2026-06-14 updates |

| 软件名 | 旧版本 | 新版本 |
|--------|--------|--------|
| codewhale | 0.8.58 | 0.8.59 |
| mcp-searxng | 1.3.4 | 1.4.0 |
| 　 | cli hash | `...` → `...` |

错误修复示例

## 2026-06-17T06:48:47+09:00

**摘要**：fix(mcp-searxng): 修复入口文件错误 — dist/index.js → dist/cli.js，MCP 服务器可正常启动

| 提交 | 说明 |
|------|------|
| `73a3b10` | fix(mcp-searxng): use dist/cli.js as entry point instead of dist/index.js |

自动触发

本技能被以下技能自动调用：

• nixkits-check-updates：软件更新完成后自动记录
• 用户执行任何修复后，可通过「记录本次修复」触发

自动触发时，摘要从前置技能的输出或最新 commit message 提取，无需重复确认。