Back to Details

ln-115-devops-docs-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DevOps Documentation Creator

DevOps文档生成工具

L3 Worker that creates runbook.md. CONDITIONAL - only invoked when project has Docker or deployment config.
用于生成runbook.md的L3 Worker，仅在项目包含Docker或部署配置时才会被条件式调用。

Purpose & Scope

目标与范围

  • Creates runbook.md (if hasDocker)
  • Receives Context Store from ln-110-project-docs-coordinator
  • Step-by-step setup and deployment instructions
  • Troubleshooting guide
  • Never gathers context itself; uses coordinator input
  • 当检测到Docker时创建runbook.md文档
  • 接收来自ln-110-project-docs-coordinator的上下文存储数据
  • 提供分步式的环境搭建与部署说明
  • 包含故障排查指南
  • 不会自行收集上下文数据，仅使用协调器提供的输入

Invocation (who/when)

调用规则（调用方/触发时机）

  • ln-110-project-docs-coordinator: CONDITIONALLY invoked when: 
    • hasDocker=true
      (Dockerfile or docker-compose.yml detected)
  • Never called directly by users
  • 调用方：ln-110-project-docs-coordinator，满足以下条件时触发： 
    • hasDocker=true
      （检测到Dockerfile或docker-compose.yml文件）
  • 不会由用户直接调用

Inputs

输入参数

From coordinator:
  • contextStore
    : Context Store with DevOps-specific data
    • DOCKER_COMPOSE_DEV (development setup)
    • DOCKER_COMPOSE_PROD (production setup)
    • ENV_VARIABLES (from .env.example)
    • STARTUP_SEQUENCE (services order)
    • DEPLOYMENT_TARGET (AWS, Vercel, Heroku)
    • CI_CD_PIPELINE (from .github/workflows)
    • DOCKER_SERVICES (parsed from docker-compose.yml services)
    • DEPLOYMENT_SCALE ("single" | "multi" | "auto-scaling" | "gpu-based")
    • DEVOPS_CONTACTS (from CODEOWNERS, package.json author, git log)
    • HAS_GPU (detected from docker-compose nvidia runtime)
  • targetDir
    : Project root directory
  • flags
    : { hasDocker }
来自协调器的输入：
  • contextStore
    ：包含DevOps专属数据的上下文存储
    • 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的services字段解析而来）
    • DEPLOYMENT_SCALE（部署规模："single" | "multi" | "auto-scaling" | "gpu-based"）
    • DEVOPS_CONTACTS（从CODEOWNERS、package.json的author字段、git日志中获取）
    • HAS_GPU（从docker-compose的nvidia runtime检测而来）
  • targetDir
    ：项目根目录
  • flags
    ：{ hasDocker }

Documents Created (1, conditional)

生成的文档（1个，条件式生成）

FileConditionQuestionsAuto-Discovery
docs/project/runbook.mdhasDockerQ46-Q51High
文件生成条件关联问题自动发现能力
docs/project/runbook.mdhasDocker为trueQ46-Q51高

Workflow

工作流程

Phase 1: Check Conditions

阶段1：条件检查

  1. Parse flags from coordinator
  2. If 
    !hasDocker
    : return early with empty result
  1. 解析协调器传入的flags参数
  2. 若
    !hasDocker
    ：直接返回空结果

Phase 2: Create Document

阶段2：创建文档

  1. Check if file exists (idempotent)
  2. If exists: skip with log
  3. If not exists:
    • Copy template
    • Replace placeholders with Context Store values
    • Populate setup steps from package.json scripts
    • Extract env vars from .env.example
    • Mark 
      [TBD: X]
      for missing data
  4. Conditional Section Pruning:
    • If DEPLOYMENT_SCALE != "multi" or "auto-scaling": Remove scaling/load balancer sections
    • If !HAS_GPU: Remove GPU-related sections (nvidia runtime, CUDA)
    • If service not in DOCKER_SERVICES: Remove that service's examples (e.g., no Redis = no Redis commands)
    • If DEVOPS_CONTACTS empty: Mark {{KEY_CONTACTS}} as 
      [TBD: Provide DevOps team contacts via Q50]
    • Populate {{SERVICE_DEPENDENCIES}} ONLY from DOCKER_SERVICES (no generic examples)
    • Populate {{PORT_MAPPING}} ONLY from docker-compose.yml ports section
  1. 检查文件是否已存在（幂等性）
  2. 若已存在：记录日志并跳过创建
  3. 若不存在：
    • 复制模板文件
    • 使用上下文存储中的值替换模板占位符
    • 从package.json的scripts字段填充环境搭建步骤
    • 从.env.example文件提取环境变量
    • 对缺失的数据标记为
      [TBD: X]
  4. 条件式章节裁剪：
    • 若DEPLOYMENT_SCALE不等于"multi"或"auto-scaling"：移除扩容/负载均衡相关章节
    • 若!HAS_GPU：移除GPU相关章节（nvidia runtime、CUDA）
    • 若服务不在DOCKER_SERVICES中：移除该服务的示例内容（例如：无Redis则删除Redis命令示例）
    • 若DEVOPS_CONTACTS为空：将{{KEY_CONTACTS}}标记为
      [TBD: 通过Q50提供DevOps团队联系人信息]
    • 仅从DOCKER_SERVICES中填充{{SERVICE_DEPENDENCIES}}（不使用通用示例）
    • 仅从docker-compose.yml的ports字段填充{{PORT_MAPPING}}

Phase 3: Self-Validate

阶段3：自我校验

  1. Check SCOPE tag
  2. Validate sections:
    • Local Development Setup (prerequisites, install, run)
    • Deployment (platform, build, deploy steps)
    • Troubleshooting (common errors, debugging)
  3. Check env vars documented
  4. Check Maintenance section
  1. 检查SCOPE标签
  2. 验证章节完整性：
    • 本地开发环境搭建（前置依赖、安装、运行）
    • 部署流程（平台选择、构建、部署步骤）
    • 故障排查（常见错误、调试方法）
  3. 检查环境变量是否已文档化
  4. 检查维护章节是否存在

Phase 4: Return Status

阶段4：返回状态

json
{
  "created": ["docs/project/runbook.md"],
  "skipped": [],
  "tbd_count": 0,
  "validation": "OK"
}
json
{
  "created": ["docs/project/runbook.md"],
  "skipped": [],
  "tbd_count": 0,
  "validation": "OK"
}

Critical Notes

重要说明

Core Rules

核心规则

  • Conditional: Skip entirely if no Docker detected
  • Heavy auto-discovery: Most data from docker-compose.yml, .env.example, package.json
  • Reproducible: Setup steps must be testable and repeatable
  • Idempotent: Never overwrite existing files
  • 条件执行： 未检测到Docker时直接跳过所有操作
  • 高度自动发现： 大部分数据来自docker-compose.yml、.env.example、package.json
  • 可复现性： 环境搭建步骤必须可测试、可重复执行
  • 幂等性： 绝不会覆盖已存在的文件

NO_CODE_EXAMPLES Rule (MANDATORY)

NO_CODE_EXAMPLES规则（强制要求）

Runbook documents procedures, NOT implementations:
  • FORBIDDEN: Full Docker configs, CI/CD pipelines (>5 lines)
  • ALLOWED: Command examples (1-3 lines), env var tables, step lists
  • INSTEAD OF CODE: "See docker-compose.yml"
Runbook文档仅记录操作流程，而非实现细节：
  • 禁止： 完整的Docker配置、超过5行的CI/CD流水线代码
  • 允许： 1-3行的命令示例、环境变量表格、步骤列表
  • 替代代码的方式： "查看docker-compose.yml"

Stack Adaptation Rule (MANDATORY)

技术栈适配规则（强制要求）

  • Commands must match project stack (npm vs pip vs go)
  • Link to correct cloud provider docs (AWS/Azure/GCP)
  • Never mix stack references (no npm commands in Python project)
  • 命令必须匹配项目技术栈（npm/pip/go等）
  • 链接到对应云服务商的官方文档（AWS/Azure/GCP）
  • 禁止混合不同技术栈的参考内容（例如：Python项目中不得出现npm命令）

Format Priority (MANDATORY)

格式优先级（强制要求）

Tables (env vars, ports, services) > Lists (setup steps) > Text
表格（环境变量、端口、服务） > 列表（搭建步骤） > 文本

Definition of Done

完成标准

  • Condition checked (hasDocker)
  • Document created if applicable
  • Setup steps, deployment, troubleshooting documented
  • All env vars from .env.example included
  • Status returned to coordinator
  • 已检查Docker存在条件
  • 按需创建了文档
  • 已记录环境搭建步骤、部署流程、故障排查内容
  • 已包含.env.example中的所有环境变量
  • 已向协调器返回执行状态

Reference Files

参考文件

  • Templates: 
    references/templates/runbook_template.md
  • Questions: 
    references/questions_devops.md
    (Q46-Q51)
Version: 1.1.0 (Added NO_CODE, Stack Adaptation, Format Priority rules) Last Updated: 2025-01-12
  • 模板：
    references/templates/runbook_template.md
  • 关联问题：
    references/questions_devops.md
    （Q46-Q51）
版本： 1.1.0（新增NO_CODE、技术栈适配、格式优先级规则） 最后更新： 2025-01-12