项目文档与内容发布流程
说明内容包依赖、只新增与同步模式、父子文档发布、冲突处理和公开侧验收。
内容来源与依赖
运维场景主清单位于 scripts/data/ops-scenarios.json，分片通过 content_files 合并；知识正文在 scripts/data/knowledge/。项目与文档由项目内容包维护，本站元数据在 scripts/data/projects/website.json，正文在 scripts/data/project-docs/douya-ops-website/。修改正文文件不会自动修改数据库。
导入通过管理 API 创建、关联并发布，因此会维护审计、搜索和更新记录。项目文档引用既有分类、标签、工具和场景，先初始化运维目录；不要直接写 SQL 绕过发布事务。
执行前检查
需要可访问的 API、已初始化且具备相应发布权限的管理员。Make 载入本地 .env 的管理员配置，脚本也支持 OPS_CONTENT_ADMIN_*；已启用 MFA 时需通过安全环境变量提供当前绑定密钥。不要在命令行参数或文章中粘贴密码、Cookie、CSRF Token。
先只检查文件与依赖，不进行发布：
make check-ops-content
make check-knowledge-content
make check-project-docs-content首次发布与同步
确认目标为授权写入的本地或测试环境后执行：
make seed-ops-scenarios
make seed-knowledge
make seed-project-docs默认只新增缺失内容，保留已发布条目；并不把已有数据库全文强制覆盖成内容包。修订包内项目和文档后，审核差异再运行 make sync-project-docs，它使用 --update-existing 同步包内内容与关系，不修改已有工具、分类、标签或知识文章。
非默认 API 地址可使用 OPS_CONTENT_API_BASE=http://127.0.0.1:8081 make seed-project-docs。运行前确认该地址属于本次任务，不要因端口相同就认定数据库正确。
层级与公开路径
本站手册根节点是 handbook，子节点如 local-development 的公开路径为 /docs/douya-ops-website/handbook/local-development。新文档先关联正确项目，再确定父节点和排序；项目和祖先必须满足公开条件，不能仅看当前节点状态。
Slug 与父节点共同影响 URL。移动目录可能改变整个子树路径，服务端路径更新并不会自动修订其他正文中的手写链接。调整前记录原路径和入链，完成后重新验证。文档 version 是可选文本标记，不是自动生成的版本快照。
公开侧验收
直接执行 Node 脚本需自行提供环境变量；只读核验不需要管理员凭据：
OPS_CONTENT_API_BASE=http://127.0.0.1:8080 node scripts/seed-project-docs.mjs --verify-only同时打开项目页和手册根节点，检查全文、父子目录、相邻文档、安全链接和搜索结果。代码块是供人工审查的示例，不会在浏览器执行。
冲突、停止与恢复
遇到 Slug 冲突、归档项、未预期草稿、依赖不可公开或乐观锁冲突时停止同步，先保留双方版本并查明归属，不自动覆盖他人改动。导入跨多个请求，不是整包原子事务；中途失败应先检查已创建记录，再安全重跑。文字错误通过后台修订恢复，不能靠数据库回滚撤销整次内容发布。