ln-115-devops-docs-creator

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

DevOps 文档创建器

类型： L3 Worker

负责创建 infrastructure.md 和 runbook.md 的 L3 Worker。始终创建基础设施清单；仅在存在 Docker 时创建运行手册。

目的与范围

• 创建 infrastructure.md（始终）——声明式清单：部署了什么、部署在哪里
• 创建 runbook.md（如果 hasDocker）——操作指南：如何部署、重启和排查问题
• 接收来自 ln-110-project-docs-coordinator 的 Context Store
• 从不自行收集上下文；使用协调器提供的输入

调用方式（由谁／何时调用）

• ln-110-project-docs-coordinator： 始终调用（infrastructure.md 无条件创建）
• 不会由用户直接调用

输入

来自协调器：

• contextStore：包含 DevOps 专属数据的 Context Store
  • DOCKER_COMPOSE_DEV（开发环境配置）
  • DOCKER_COMPOSE_PROD（生产环境配置）
  • ENV_VARIABLES（来自 .env.example）
  • STARTUP_SEQUENCE（服务启动顺序）
  • DEPLOYMENT_TARGET（AWS、Vercel、Heroku）
  • CI_CD_PIPELINE（来自 .github/workflows）
  • DOCKER_SERVICES（从 docker-compose.yml 服务中解析）
  • DEPLOYMENT_SCALE（"single" | "multi" | "auto-scaling" | "gpu-based"）
  • DEVOPS_CONTACTS（来自 CODEOWNERS、package.json author、git log）
  • HAS_GPU（根据 docker-compose nvidia runtime 检测）
  • SERVER_INVENTORY（来自 SSH 配置、部署目标）
  • DOMAIN_DNS（来自 docker-compose VIRTUAL_HOST 变量、nginx 配置）
  • ARTIFACT_REPOSITORY（来自 .env 中的 registry URL、.npmrc、pip.conf）
  • HOST_REQUIREMENTS（来自 docker-compose deploy.resources.limits）
• targetDir：项目根目录
• flags：{ hasDocker }

必须读取： 加载 references/docs_quality_contract.md 和 references/markdown_read_protocol.md。 可选规则目录：仅在需要确切的规则 ID、路径矩阵或允许使用的占位符例外时，加载 references/docs_quality_rules.json。

创建的文档（2 个：1 个始终创建 + 1 个按条件创建）

文件	条件	问题	自动发现
docs/project/infrastructure.md	始终	Q52-Q55	中
docs/project/runbook.md	hasDocker	Q46-Q51	高

工作流

阶段 1：检查条件

1. 解析协调器提供的 flags
2. infrastructure.md：始终继续（不检查条件）
3. runbook.md：仅在 hasDocker=true 时创建
4. 如果目标文件已存在：跳过该文件（保持幂等）

阶段 2a：创建 infrastructure.md（无条件）

1. 检查 docs/project/infrastructure.md 是否存在
2. 如果存在：记录日志并跳过
3. 如果不存在：
   • 复制 references/templates/infrastructure_template.md
   • 使用 Context Store 中的值替换占位符
   • 保留模板中的共享开篇约定和标准顶部章节
   • 使用 SERVER_INVENTORY 填充服务器清单
   • 使用 DOCKER_SERVICES 的端口映射填充端口分配
   • 使用 DOCKER_SERVICES 填充已部署服务
   • 使用 CI_CD_PIPELINE 填充 CI/CD 流水线
   • 已发布的基础设施文档中不得残留模板标记
   • 如果缺少数据：省略该项声明或使用简洁、中性的替代说明，但不得输出 [TBD: ...]
4. 按条件裁剪章节：
   • 如果未检测到 CI/CD：替换为简洁的空状态说明，不得使用 [TBD: ...]
   • 如果没有 ARTIFACT_REPOSITORY：替换为简洁的空状态说明，不得使用 [TBD: ...]
   • 如果只有单台服务器／没有 SERVER_INVENTORY：简化为单列表格
   • 如果 !HAS_GPU：从服务器清单和已部署服务中移除 GPU 列
   • 已部署服务只能使用 DOCKER_SERVICES 填充（不得使用通用示例）

阶段 2b：创建 runbook.md（有条件）

1. 如果 !hasDocker：完全跳过
2. 检查 docs/project/runbook.md 是否存在
3. 如果存在：记录日志并跳过
4. 如果不存在：
   • 复制 references/templates/runbook_template.md
   • 使用 Context Store 值替换占位符
   • 保留模板中的共享开篇契约和标准顶部章节
   • 根据 package.json 脚本填充设置步骤
   • 从 .env.example 提取环境变量
   • 发布的 runbook 中绝不能留下模板标记
   • 如果缺少数据：省略相关说法或使用简洁、中性的替代说明，但不得输出 [TBD: ...]
5. 有条件的章节删减：
   • 如果 DEPLOYMENT_SCALE != "multi" 或 "auto-scaling"：删除扩展／负载均衡器章节
   • 如果 !HAS_GPU：删除 GPU 相关章节（nvidia runtime、CUDA）
   • 如果服务不在 DOCKER_SERVICES 中：删除该服务的示例
   • 如果 DEVOPS_CONTACTS 为空：替换为简洁的空状态说明，而不是 [TBD: ...]
   • 仅根据 DOCKER_SERVICES 填充服务依赖项
   • 仅根据 docker-compose.yml 的 ports 部分填充端口映射

阶段 3：自行验证

对于 infrastructure.md：

1. 检查 SCOPE 标签和元数据标记
2. 检查必需的顶部章节（Quick Navigation、Agent Entry、Maintenance）
3. 验证以下章节：服务器清单、端口分配、已部署服务
4. 检查是否混入了操作步骤内容（这类内容应放在 runbook.md 中）
5. 检查是否符合文档质量契约（无禁止使用的占位符、无泄露的模板元数据、文档类型／角色有效）

对于 runbook.md（如果已创建）：

1. 检查 SCOPE 标签和元数据标记
2. 检查必需的顶部章节（Quick Navigation、Agent Entry、Maintenance）
3. 验证以下章节：本地开发设置、部署、故障排除
4. 检查是否记录了环境变量
5. 检查是否符合文档质量契约（无禁止使用的占位符、无泄露的模板元数据、文档类型／角色有效）

阶段 4：返回状态

{
  "created_files": ["docs/project/infrastructure.md", "docs/project/runbook.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/project/infrastructure.md", "docs/project/runbook.md"],
    "owners": {
      "docs/project/infrastructure.md": "ln-115-devops-docs-creator",
      "docs/project/runbook.md": "ln-115-devops-docs-creator"
    }
  },
  "validation_status": "passed"
}

重要说明

核心规则

• infrastructure.md： 始终创建，不设条件
• runbook.md： 是否创建取决于 hasDocker
• 大量自动发现： 大部分数据来自 docker-compose.yml、.env.example、package.json、SSH 配置
• 可复现： 设置步骤必须可测试且可重复
• 幂等： 绝不覆盖现有文件
• 可发布的输出： DevOps 文档中不得包含 [TBD: ...]、TODO 或泄露的模板元数据

NO_CODE_EXAMPLES 规则（强制）

这两份文档描述的是清单／操作步骤，而非实现：

• 禁止： 完整的 Docker 配置、CI/CD 流水线（超过 5 行）、完整的 nginx 配置
• 允许： 命令示例（1-3 行）、环境变量表格、步骤列表、验证命令
• 不要贴代码，改为：“参见 docker-compose.yml”

技术栈适配规则（强制）

• 命令必须与项目技术栈一致（npm 与 pip 或 go）
• 链接到正确的云服务商文档（AWS/Azure/GCP）
• 绝不混用技术栈引用（Python 项目中不得出现 npm 命令）

格式优先级（强制）

表格（环境变量、端口、服务、服务器）> 列表（设置步骤）> 文本

运行时摘要产物

必须阅读： 加载 references/docs_generation_summary_contract.md

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需载荷语义：

• worker = "ln-115"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

将摘要写入提供的产物路径，或在结构化输出中返回相同的封装内容。

完成定义

• 已创建 infrastructure.md（始终创建）
• 如果 hasDocker，则已创建 runbook.md
• Infrastructure：已记录服务器清单、端口、服务
• Runbook：已记录设置步骤、部署、故障排除
• 已将 .env.example 中的所有环境变量纳入 runbook
• 已验证准确性： 所有文档事实均与当前代码一致（路径、函数、API、配置均存在且准确）
• 已返回状态

Reference Files

• Templates: references/templates/infrastructure_template.md, references/templates/runbook_template.md
• Questions: references/questions_devops.md (Q46-Q51 runbook, Q52-Q55 infrastructure)

---

Version: 2.0.0 Last Updated: 2025-01-12