docs(runtime): optimize runbook for ops workflow

2026-02-25 17:21:20 +08:00
parent 36131cc001
commit aa30054d64
2 changed files with 283 additions and 102 deletions
@@ -0,0 +1,132 @@
+# Runtime Runbook Optimization Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 将 `docs/runtime/runtime-runbook.md` 重构为面向运维的可执行手册，覆盖门禁、启动、验证、故障与回滚全流程。
+
+**Architecture:** 保持单文档模式，在不改变脚本和运行时代码的前提下重排章节与命令。先做命令基线校对，再做文档结构重构，最后执行可达性验证并提交。所有命令以仓库现有脚本和 compose 路径为准。
+
+**Tech Stack:** Markdown, Bash, Docker Compose, tmux, uv。
+
+---
+
+### Task 1: 命令与脚本基线核对
+
+**Files:**
+- Modify: `docs/runtime/runtime-runbook.md`
+- Verify: `infra/scripts/app-up.sh`
+
+**Step 1: 写失败校验（当前 runbook 存在 TODO 与历史表述）**
+
+```bash
+grep -n "TODO\|dev-app-up" docs/runtime/runtime-runbook.md
+```
+
+**Step 2: 运行并确认失败**
+
+Run: `grep -n "TODO\|dev-app-up" docs/runtime/runtime-runbook.md`  
+Expected: 命中至少 1 条（表示需重构）。
+
+**Step 3: 写最小实现（命令映射清单）**
+
+```markdown
+- 启动脚本统一为 infra/scripts/app-up.sh
+- bootstrap 命令统一为 docker compose --env-file .env -f infra/docker/docker-compose.yml ...
+- 迁移/初始化强调 init-job --build
+```
+
+**Step 4: 运行验证**
+
+Run: `bash -n infra/scripts/app-up.sh`  
+Expected: exit 0。
+
+### Task 2: 文档结构重构为运维分层
+
+**Files:**
+- Modify: `docs/runtime/runtime-runbook.md`
+
+**Step 1: 写失败校验（缺失目标章节）**
+
+```bash
+grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback" docs/runtime/runtime-runbook.md
+```
+
+**Step 2: 运行并确认失败**
+
+Run: `grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback" docs/runtime/runtime-runbook.md`  
+Expected: 命中不完整或为空。
+
+**Step 3: 写最小实现（章节重排）**
+
+```markdown
+1. Scope & Preconditions
+2. Bootstrap Gate (Mandatory)
+3. Service Start/Stop
+4. Operational Verification (L1/L2/L3)
+5. Incident Playbook
+6. Rollback Procedure
+```
+
+**Step 4: 运行验证**
+
+Run: `grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback Procedure" docs/runtime/runtime-runbook.md`  
+Expected: 4 个目标章节都能命中。
+
+### Task 3: 补齐运维验证与故障处理细则
+
+**Files:**
+- Modify: `docs/runtime/runtime-runbook.md`
+
+**Step 1: 写失败校验（缺少通过判定）**
+
+```bash
+grep -n "通过标准\|判定" docs/runtime/runtime-runbook.md
+```
+
+**Step 2: 运行并确认失败**
+
+Run: `grep -n "通过标准\|判定" docs/runtime/runtime-runbook.md`  
+Expected: 命中不足。
+
+**Step 3: 写最小实现（每段加判定）**
+
+```markdown
+- L1 必跑：health/compose/smoke + 通过标准
+- L2 可选：auth/profile + 通过标准
+- L3 可选：agent_chat tests + 通过标准
+- 故障条目：症状/定位/修复
+```
+
+**Step 4: 运行验证**
+
+Run: `grep -n "L1 必跑\|L2 可选\|L3 可选\|通过标准" docs/runtime/runtime-runbook.md`  
+Expected: 关键段落均命中。
+
+### Task 4: 收尾校验与提交
+
+**Files:**
+- Modify: `docs/runtime/runtime-runbook.md`
+
+**Step 1: 运行文档语义检查（关键命令可达）**
+
+```bash
+bash -n infra/scripts/app-up.sh
+PYTHONPATH=backend/src uv run python -c "import core.runtime.cli"
+```
+
+**Step 2: 运行并确认通过**
+
+Run: `bash -n infra/scripts/app-up.sh`  
+Expected: exit 0。
+
+Run: `PYTHONPATH=backend/src uv run python -c "import core.runtime.cli"`  
+Expected: 无报错并 exit 0。
+
+**Step 3: 提交**
+
+```bash
+git add docs/runtime/runtime-runbook.md \
+  docs/plans/2026-02-25-runtime-runbook-optimization-design.md \
+  docs/plans/2026-02-25-runtime-runbook-optimization-implementation-plan.md
+git commit -m "docs(runtime): optimize runbook for ops workflow"
+```