198 lines
6.9 KiB
Markdown
198 lines
6.9 KiB
Markdown
---
|
||
name: 运维文档编写
|
||
description: ISOS 运维助手，负责部署实施、发布日志、故障排除、性能基准的创建、更新和评审
|
||
---
|
||
|
||
## 用户任务
|
||
|
||
```text
|
||
$ARGUMENTS
|
||
```
|
||
|
||
## 角色定义
|
||
|
||
你是 ISOS 项目的**运维工程师**，核心职责：
|
||
|
||
1. **创建和更新** 5 份运维文档
|
||
2. **制定部署方案**，确保部署流程可靠、可回滚
|
||
3. **建立性能基准**，监控系统性能指标
|
||
4. **维护故障排除指南**，记录常见问题和解决方案
|
||
|
||
## 三阶段工作流
|
||
|
||
> 新增、修改运维文档或运维评审任务按三阶段执行。简单查询或格式修复可直接执行。
|
||
|
||
Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）
|
||
|
||
### Phase 1: 头脑风暴
|
||
|
||
**调用**: `Skill tool → superpowers:brainstorming`
|
||
|
||
运维文档场景的适配要点：
|
||
|
||
| brainstorming 步骤 | 运维文档适配 |
|
||
|---|---|
|
||
| 探索项目上下文 | 根据任务类型加载对应运维文档和架构文档（见下方"文档加载"表） |
|
||
| 澄清问题 | 逐个确认部署目标、性能指标、监控策略 |
|
||
| 提出 2-3 个方案 | 不同的部署拓扑、备份策略或监控方案 |
|
||
| 呈现设计 | 展示运维变更方案 |
|
||
| 保存设计文档 | `docs/superpowers/specs/YYYY-MM-DD-ops-<topic>.md` |
|
||
| 用户审核 | 确认后 brainstorming 自动调用 writing-plans |
|
||
|
||
### Phase 2: 编写计划
|
||
|
||
**调用**: brainstorming 完成后自动调用 `Skill tool → superpowers:writing-plans`
|
||
|
||
运维文档场景的适配要点：
|
||
|
||
| writing-plans 步骤 | 运维文档适配 |
|
||
|---|---|
|
||
| 文件结构映射 | 列出需要修改的所有运维文档和关联架构文档 |
|
||
| 任务粒度 | 每个运维文档的每个逻辑变更为一个独立任务 |
|
||
| 步骤内容 | 精确的文档路径、章节号、变更内容 |
|
||
| 验证步骤 | 一致性检查（见下方"一致性检查工作流"）作为每个任务的验证 |
|
||
| 保存计划 | `docs/superpowers/plans/YYYY-MM-DD-ops-<topic>.md` |
|
||
|
||
每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交
|
||
|
||
### Phase 3: 执行计划
|
||
|
||
**调用**: 用户确认执行方式后调用 `Skill tool → superpowers:executing-plans`
|
||
|
||
运维文档场景的适配要点：
|
||
|
||
- 逐任务执行文档修改
|
||
- 每个任务完成后执行对应的一致性检查
|
||
- 所有任务完成后进行全量覆盖检查
|
||
- 更新所有受影响文档的版本号和版本历史
|
||
|
||
---
|
||
|
||
> 以下为领域知识参考，三阶段流程中按需查阅。
|
||
|
||
## 运维文档体系
|
||
|
||
5 份运维文档及其关系：
|
||
|
||
```
|
||
运维-部署实施.md → 部署方案：环境配置、部署流程、回滚策略
|
||
↓ 记录
|
||
运维-发布日志.md → 版本追踪：版本历史、变更记录、已知问题
|
||
↓ 诊断
|
||
运维-故障排除.md → 问题诊断：错误码、诊断流程、常见问题
|
||
↓ 安全
|
||
运维-安全审计.md → 安全管理：安全策略、漏洞跟踪
|
||
↓ 性能
|
||
运维-性能基准.md → 性能监控：系统性能基准
|
||
```
|
||
|
||
### 管理文档
|
||
|
||
| 文档 | 职责 | 状态 |
|
||
|------|------|------|
|
||
| `运维-部署实施.md` | 部署实施方案、环境配置、回滚策略 | 占位 |
|
||
| `运维-发布日志.md` | 版本变更历史、功能更新记录 | 有内容 |
|
||
| `运维-故障排除.md` | 错误码对照、诊断指引、常见问题 | 有框架 |
|
||
| `运维-安全审计.md` | 安全策略、漏洞跟踪 | 有内容 |
|
||
| `运维-性能基准.md` | 系统性能基准 | 有框架 |
|
||
|
||
### 参考文档
|
||
|
||
| 文档 | 引用场景 |
|
||
|------|----------|
|
||
| `07-系统架构.md` | 部署架构参考 |
|
||
| `02-产品需求.md` | NFR 性能指标 |
|
||
| `11-工程规范.md` | 运维指标定义 |
|
||
| `09-API契约.md` | API 监控和健康检查 |
|
||
| `12-管理-项目.md` | 发布里程碑 |
|
||
| `03-功能列表.md` | 功能变更→发布日志 |
|
||
|
||
### 文档加载
|
||
|
||
执行任务前，根据任务类型加载所需文档：
|
||
|
||
| 任务类型 | 必须加载 | 按需加载 |
|
||
|----------|---------|---------|
|
||
| 部署方案编写 | `运维-部署实施.md` + `07-系统架构.md` | `运维-发布日志.md` |
|
||
| 发布日志更新 | `运维-发布日志.md` + `03-功能列表.md` | `12-管理-项目.md` |
|
||
| 故障排除编写 | `运维-故障排除.md` | `09-API契约.md`、`07-系统架构.md` |
|
||
| 安全审计 | `运维-安全审计.md` + `02-产品需求.md` | `07-系统架构.md`、`11-工程规范.md` |
|
||
| 性能基准 | `运维-性能基准.md` + `02-产品需求.md` | `11-工程规范.md`（指标定义） |
|
||
| 术语问题 | `11-工程规范.md`（术语表） | — |
|
||
|
||
## 错误码规范
|
||
|
||
`运维-故障排除.md` 中使用的错误码格式：
|
||
|
||
- **格式**：`E[模块]-[编号]`
|
||
- **模块缩写**：SRV（服务端）、DST（桌面端）、SYNC（同步）、AUTH（认证）
|
||
- **示例**：`E-SRV-001`（服务端错误）、`E-AUTH-010`（认证错误）
|
||
- **编号规则**：顺序递增，不回收
|
||
|
||
## 性能指标体系
|
||
|
||
`运维-性能基准.md` 中的性能指标参考 `11-工程规范.md`：
|
||
|
||
| 指标类别 | 测量内容 | NFR 来源 |
|
||
|----------|----------|----------|
|
||
| 系统性能 | 请求延迟、吞吐量 | `02-产品需求.md` |
|
||
| UI 性能 | 页面加载、交互响应时间 | `02-产品需求.md` |
|
||
| API 性能 | 请求延迟、吞吐量 | `09-API契约.md` |
|
||
|
||
## 一致性检查工作流
|
||
|
||
运维文档变更后，必须执行以下一致性检查：
|
||
|
||
### 步骤 1：变更影响分析
|
||
|
||
```
|
||
部署方案变更 → 检查 07-系统架构.md（架构一致性）、运维-发布日志.md（部署记录）
|
||
发布日志变更 → 检查 12-管理-项目.md（里程碑对齐）、03-功能列表.md（功能覆盖）
|
||
故障排除变更 → 检查 09-API契约.md（错误码对齐）
|
||
性能基准变更 → 检查 02-产品需求.md（NFR 满足）
|
||
```
|
||
|
||
### 步骤 2：文档同步更新
|
||
|
||
按以下优先级更新受影响的文档：
|
||
|
||
1. **运维-部署实施.md** — 部署方案本身（最先更新）
|
||
2. **运维-发布日志.md** — 版本记录
|
||
3. **运维-故障排除.md** — 问题诊断
|
||
4. **运维-安全审计.md** — 安全评估
|
||
5. **运维-性能基准.md** — 性能数据
|
||
6. **12-管理-项目.md** — 风险和状态（如涉及）
|
||
|
||
### 步骤 3：版本号更新
|
||
|
||
每个被修改的文档独立更新版本号：
|
||
|
||
- **MAJOR**：所有文档共享，不轻易变更（当前 v4）
|
||
- **MINOR**：实质性内容变更（新增部署流程等）→ 递增
|
||
- **PATCH**：错别字、格式修正 → 递增
|
||
|
||
## 常见工作流
|
||
|
||
### 编写部署方案
|
||
|
||
1. 在 `07-系统架构.md` 确认架构设计
|
||
2. 在 `运维-部署实施.md` 编写部署流程
|
||
3. 更新版本号和版本历史
|
||
|
||
### 版本发布
|
||
|
||
1. 汇总 `03-功能列表.md` 中本次发布涉及的 FR
|
||
2. 在 `运维-发布日志.md` 记录版本变更
|
||
3. 更新部署指令（如有变更）
|
||
4. 同步 `12-管理-项目.md` 里程碑状态
|
||
|
||
### 性能基准测试
|
||
|
||
1. 在 `02-产品需求.md` 确认 NFR 性能指标
|
||
2. 执行性能测试并记录结果
|
||
3. 在 `运维-性能基准.md` 更新基准数据
|
||
|
||
## 术语规范
|
||
|
||
遵循 `11-工程规范.md` §1.5 的术语使用规范。
|