前言¶
用 JSON 当内容源的知识库站、静态 CMS 或轻量后台，更新数据时常见失误是：incoming 文件只有几篇新稿，却被当成全量包直接覆盖正式数据源，历史 articles 一次性消失。手工 diff 大 JSON 成本高，项目里也未必已有合并脚本。下面介绍 SkillHub 社区 Skill「知识库安全合并」，用固定 SOP 和可选脚本，把「先识别数据源 → dry-run → 备份 → 合并 → 校验」串成可复现流程。
这是什么¶
知识库安全合并（坐标 @user_87a42d61/knowledge-safe-merge，版本 1.0.0）是社区发布者 user_87a42d61 在 SkillHub 上架的 knowledge-management 类 Agent Skill。SkillHub 页面简介为：安全合并知识库/内容库 JSON 数据，保留历史文章，避免整包覆盖。标签 requires_api_key=false，不依赖外部 API Key。
它面向根对象为 { "categories": [], "articles": [] } 的数据（articles 为核心，categories 可选），指导 Agent 区分正式数据源、镜像与 incoming 文件，默认假定 incoming 可能是增量而非全量，禁止未经预演与备份的覆盖写入。
官方入口：
- SkillHub 展示页：https://www.skillhub.cn/skills/user_87a42d61/knowledge-safe-merge
- API 坐标页：https://api.skillhub.cn/user_87a42d61/knowledge-safe-merge
（SkillHub 统计：评分 100000，下载 857，安装 32。）
核心功能¶
依据 Skill 包内 SKILL.md 与 scripts/merge_knowledge_json.py，已核实能力包括：
- 工作流约束：先识别 authoritative 正式数据源；incoming 默认按增量处理；先 dry-run 再看新增/更新/未变化/合并后总数；正式写入前备份；合并后校验 JSON 与页面（若涉及上线）。
- 合并规则：优先按文章
id匹配；id不一致时按「title+date」匹配；未匹配项追加为新文章；结果按日期倒序、再按id排序。 - 自带脚本：在无项目现成管道时，可用
merge_knowledge_json.py对--current与--incoming执行预演或落盘；支持--backup-dir、--mirror、--output。 - 产出清单：处理结束需汇报数据源路径、incoming 路径、统计项、是否备份/同步镜像、是否完成线上校验。
若仓库里已有稳定的合并或导入逻辑，Skill 要求优先复用项目方案，再考虑自带脚本。
安装与启用¶
通过 SkillHub CLI（Cursor、Claude Code、Codex 等通用）¶
先确认是否已安装 CLI：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档执行完整安装（文档地址：https://skillhub.cn/install/skillhub.md）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。社区坐标需带 namespace：
skillhub install knowledge-safe-merge --namespace user_87a42d61 --dir <你的 skills 目录>
常用路径（来自 SkillHub 安装文档）示例：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可将下列提示词交给 AI，让其按安装文档完成安装：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_87a42d61/knowledge-safe-merge`。
手工目录安装（WorkBuddy 系）¶
Skill 包 README.md 另提供文件夹拷贝方式：
- 项目级：
项目目录/.workbuddy/skills/knowledge-safe-merge/ - 用户级：
~/.workbuddy/skills/knowledge-safe-merge/
完整目录应包含 SKILL.md、README.md、references/、scripts/ 等，不宜只复制 SKILL.md。
典型用法¶
在 Skill 目录下，先对正式数据源与 incoming 做预演（--dry-run 只输出统计，不写文件）：
py -3 scripts/merge_knowledge_json.py --current "正式数据源.json" --incoming "新数据.json" --dry-run
确认统计符合预期后，正式合并并覆盖正式文件；未指定 --backup-dir 时，备份会写到正式文件同级 .knowledge-backups/：
py -3 scripts/merge_knowledge_json.py --current "public/knowledge-data.json" --incoming "incoming.json"
若站点同时维护镜像 JSON，可在一次命令里写入正式源并同步镜像：
py -3 scripts/merge_knowledge_json.py --current "public/knowledge-data.json" --incoming "incoming.json" --mirror "knowledge-data.json"
需要保留原文件、将结果写到新路径时：
py -3 scripts/merge_knowledge_json.py --current "current.json" --incoming "incoming.json" --output "merged.json"
在 Agent 对话中，当出现「合并知识库 JSON、导入新文章但保留历史、迁移内容库、先预演再落盘」等表述时，应触发本 Skill 的上述流程，而不是直接 cp 或整文件覆盖。
适用场景与注意¶
适合：知识库站、内容聚合站、静态 JSON 驱动站点、简易内容后台；定期从导出或外部系统接入 articles 数组的场景。
限制与坑：
- 数据结构若与
{ categories, articles }差异大，需先适配，不宜强行合并。 - 每篇文章至少应可识别
title、content；id不稳定时匹配会退化为「标题 + 日期」，需自行评估碰撞风险。 - Skill 明确禁止：跳过 dry-run 覆盖生产数据、无备份写盘、把镜像或测试文件误当正式源、只验证新文章不核对旧文章是否仍在。
- 合并脚本示例使用
py -3；在 Linux 上可改为python3，路径需换成你项目中的真实文件。
结尾¶
知识库安全合并把 JSON 内容更新从「整包覆盖」改成「可审计的增量合并」：规则写在 Skill 里，执行可交给 Agent 与 merge_knowledge_json.py。需要安装或查看说明时，打开 SkillHub 页面 https://www.skillhub.cn/skills/user_87a42d61/knowledge-safe-merge ，或按坐标 @user_87a42d61/knowledge-safe-merge 用 CLI 安装到当前 Agent 的 skills 目录。
