worklog-update

worklog-update：skill 升级器

与用户交互的语言跟随其消息语言。安全边界（hard deny）：只写 vault 的 .agents/skills/ 白名单路径、项目级 .claude/skills 兼容软链接，以及已安装的全局 ~/.agents/skills/{aireadme,stash,pitfalls} 与对应 ~/.claude/skills/ 兼容软链接。diaries/、wiki/、inbox/、两层 config、AIREADME/、根文档、~/.local/share/project-memory/、~/.local/share/pitfalls-memory/ 与 ~/.local/share/worklog/memory/ 一律不碰；.claude/settings.json 只展示 diff 供 Claude Code 用户手动决定。

前置

• .ingest.lock 存在 → 拒绝运行（等 ingest 跑完）。
• upstream 默认 https://github.com/iyuenan3/worklog-kit（config 顶层键 upstream_repo 可覆盖，适配 fork 用户；模板注释里有示例）。

流程

1. 取版本：git ls-remote --tags --refs --sort=-version:refname <upstream> 'v*'，只接受首个符合 v<数字>.<数字>.<数字> 的 release tag；无 tag（上游 pre-alpha 期）→ 明确告知「没有可锁定 release tag，main 是持续变化的非 release 版本」，经用户确认后才用 main，不确认则干净退出。不得按文本顺序猜“最新”，也不得把 annotated tag 的 ^{} 行当成版本。
2. 浅克隆到临时目录：git clone --depth 1 --branch <tag> <upstream> <scratch 临时目录>（绝不 git remote add / git merge，上游历史不进用户仓）。
3. 兼容形态预检：当前标准形态是 .agents/skills/ 实体目录 + .claude/skills -> ../.agents/skills 软链接。若本地仍是旧版 .claude/skills/ 实体目录，先列出迁移计划，经确认后将它整体移动到 .agents/skills/，再建立并验证兼容软链接；若两边同时是实体目录，拒绝自动合并，先让用户决定保留哪份，避免覆盖本地改动。
4. 差异盘点：白名单 = 上游 .agents/skills/ 下全部子目录。逐 Skill 与本地 diff -rq 分类，列出新增（上游新 Skill，供用户选择装不装）/ 有变更（明确列出「本地存在但上游已移除」的文件，镜像同步会移走它们）/ 本地独有 Skill（用户自己加的，永不动）。内容级审计：对「有变更」Skill 里的 SKILL.md 与脚本类文件（*.sh / *.py），逐个 diff -ru 展示实际改动内容再请求确认（这些是将被 agent 执行的指令与代码，只报文件名不构成 §12 说的人工审计点）；摘录上游 AIREADME/CHANGELOG.md 相关段给用户看「这次更新带来什么」（kit 发布史与 vault 版本流合在该文件，读上游 clone 里的那份、不动本地）。再单列已安装全局三件套与本轮 vault 新版之间的差异，明确它们会随本轮一起刷新；全局目标内有用户修改时，同样展示内容级 diff，不可把它当普通旧副本静默覆盖。
5. 确认后同步：逐 Skill（或用户说全部）做镜像同步。先在临时目录准备上游副本并验证 SKILL.md，再把本地目录移动到同一临时目录作可恢复备份，最后把新目录移动到 .agents/skills/<name>/；任一步失败立即把备份移回，不留下半套状态。用户在该 Skill 目录内自加过文件的，在 Step 4 已看到移出清单、确认才动；本地独有 Skill 与一切用户数据不动。注意：worklog-lint 与 worklog-ingest 共享校验脚本（标点门 / 日期门在 ingest 目录），两者建议成对升级；locale 模板在 worklog-init 目录内，随该 Skill 一起同步。
6. 刷新全局三件套：只处理 aireadme / stash / pitfalls。若 ~/.agents/skills/<name> 已是指向当前 vault .agents/skills/<name> 的正确软链接，只验证并保留。若是实体目录，按 Step 4 已确认的 diff 执行「新副本预校验 → 旧目录移入临时备份 → 从 vault 新版完整复制 → 校验失败则恢复」，不得用 cp -R 合并。若是指向其他 canonical 的软链接，先报告目标，只有用户确认切换来源才替换。最后确保 ~/.claude/skills/<name> -> ../../.agents/skills/<name>，实体目录或错误链接仍按同一备份、确认与恢复纪律处理。全程不得读取、移动或重建任何 ~/.local/share/*memory* 数据。
7. config schema 检查：比对上游模板 worklog.config.yaml 的 schema_version 与本地：上游更新则列出需补的键 + 默认值。实施口径：一律只展示、不代写（config 在上方 hard deny 清单内）：顶层键给出可直接粘贴的追加块（含注释），嵌套键（modules 子键、sources 条目属性）以 diff 形式标注应插入的层级（盲 append 会破坏 YAML 结构）；用户明确说「帮我改」才代改并逐键复述。绝不覆盖已有值。
8. 兼容 dry-run：跑 python3 .agents/skills/worklog-lint/scripts/lint.py 验证契约锚点仍匹配；验证项目级 .claude/skills 解析到 .agents/skills，再验证全局 Codex 与 Claude Code 三件套入口最终读取同一份实现；🔴 则输出手动调整清单。
9. 收尾：commit（chore: skill 升级至 <tag>）+ 校验通过后清理临时备份 + 报告（升级了什么 / 跳过了什么 / 全局三件套状态 / settings diff 提示 / 需要手动做的）。