# STORAGE LABOS / FlashOps — AI 协作与系统操作指南

> 文档版本：1.0
>
> 核对日期：2026-07-27
>
> 适用对象：Codex、Claude Code、Cursor、GitHub Copilot Agent，以及参与项目的人类开发者
>
> 目标：只把本文件交给 AI，也能让它安全地理解、运行、修改、验证和交付本系统

本文件是 AI 接手项目时的第一入口。更完整的产品、架构、数据模型、状态机和生产运维说明见
[ProjectManual.md](ProjectManual.md)。如果本文件与代码冲突，以代码和测试为准，并在本次变更中
同步修正文档；如果生产信息与代码冲突，先做只读核验，不要凭文档直接修改服务器。

---

## 0. 直接交给 AI 的任务开场词

把下面内容和具体任务一起发给 AI：

~~~text
你正在维护 STORAGE LABOS / FlashOps。

请先完整阅读仓库根目录 CONTRIBUTING.md，再按其中的权限边界、架构红线、测试门禁和
Git 交付流程工作。需要深入理解时再阅读 ProjectManual.md 及 flashops/docs/。

先检查仓库状态并保护现有未提交改动。默认只操作本地开发环境；除非任务明确要求，不得修改
生产服务器、生产数据、DNS、证书、Gitea 设置或调用生产环境写接口。任何真实硬件、固件刷写、
Format、Sanitize、Reset、断电或 OOB 动作都必须停下并取得明确授权。

任务：<在这里写具体目标>

完成后请报告：改动文件、关键决策、测试结果、未完成项、风险、提交号和远程分支。
~~~

---

## 1. AI 必须先记住的系统事实

| 项目 | 当前值 |
|---|---|
| 产品 | STORAGE LABOS，后端代号 FlashOps |
| 用途 | 存储固件回归测试的无人值守控制平面 |
| Git 网页 | <https://git.imagebrewing.com/yuanshuai/storage-labos> |
| 克隆地址 | <https://git.imagebrewing.com/yuanshuai/storage-labos.git> |
| 默认分支 | main |
| 公网预览 | <https://flashops.imagebrewing.com/> |
| 公网 API 文档 | <https://flashops.imagebrewing.com/docs> |
| 本地控制台 | <http://localhost:8000/console/Dashboard.dc.html> |
| 本地 API 文档 | <http://localhost:8000/docs> |
| 后端 | Python 3.9+、FastAPI、SQLAlchemy |
| 当前数据库 | SQLite，必须保持单 worker |
| 当前执行能力 | 模拟 Run 与 Agent dry-run；不代表真实硬件动作已交付 |
| 当前测试基线 | 25 项 |
| 生产认证边界 | 预览站匿名开放，尚无应用级 RBAC |
| Gitea | 公开仓库匿名可读；注册账号需管理员批准 |
| CI | 生产服务器没有 Runner，测试结果必须由提交者本地提供 |

重要：公网预览虽然没有登录限制，但这不等于 AI 获得了生产写权限。当前部分 POST 接口在技术上
也能匿名调用，这是尚未补齐 RBAC 的原型边界，不应被当作授权。

---

## 2. 权限与行为边界

AI 应按以下顺序判断是否可以行动：

| 行为 | 默认是否允许 | 条件 |
|---|---:|---|
| 阅读仓库、文档、Git 历史 | 是 | 保持只读 |
| 查看公网页面、调用健康检查和 GET 查询 | 是 | 不产生业务状态变化 |
| 在本地新分支修改代码和文档 | 用户要求开发时允许 | 保护已有改动 |
| 本地运行测试和模拟演示 | 是 | 不连接真实设备 |
| 创建本地模拟 Run | 是 | 仅使用本地数据库 |
| 提交 Git | 用户要求开发或交付时允许 | 检查范围、测试和秘密后提交 |
| 推送功能分支 | 用户要求共享或交付时允许 | 不强推 main |
| 合并 Pull Request | 否 | 需要仓库负责人明确授权或正常评审 |
| 调用生产 POST、PATCH、PUT、DELETE | 否 | 必须得到针对该动作的明确授权 |
| 修改 DNS、Nginx、systemd、证书、Gitea 设置 | 否 | 必须明确要求部署或运维 |
| 操作真实 DUT、NVMe、固件或 OOB | 否 | 必须明确目标、批准范围和回滚方案 |
| Format、Sanitize、刷写、Reset、断电 | 绝不默认执行 | 需要明确授权、可牺牲 DUT、审批和证据链 |

遇到权限不清时，继续完成安全的本地分析、测试或方案设计，把真正需要授权的动作单独列出。

---

## 3. 信息源优先级

AI 不应只根据文件名或旧说明猜测当前能力，按下面顺序取证：

1. 当前用户的明确任务与限制；
2. 当前工作树、Git diff 和实际源码；
3. 自动化测试及可重复的本地运行结果；
4. 本文件；
5. ProjectManual.md；
6. flashops/docs/ 下的架构、状态机和 ADR；
7. README、历史提交、部署模板；
8. 推测。

如果代码、测试和文档互相矛盾，必须在交付说明中指出。不得把“规划”“草案”“静态页面”描述成
已经可用于真实硬件的能力。

---

## 4. 第一次接手：安全启动流程

### 4.1 全新克隆

~~~bash
git clone https://git.imagebrewing.com/yuanshuai/storage-labos.git
cd storage-labos
git status -sb

cd flashops
make setup
make test
make demo
~~~

make setup 会初始化本地虚拟环境，并重建 flashops/var 下的本地 SQLite 数据。它只适合全新克隆
或确认可以重置的本地开发环境；如果工作目录里已有需要保留的本地演示数据，不要直接运行。

### 4.2 已存在的工作目录

~~~bash
git status -sb
git diff
git diff --cached
git log -5 --oneline
~~~

先识别用户已有的未提交改动。不得使用 reset --hard、checkout 丢弃文件、clean -fd 或其他会
抹掉用户工作的命令。不得把不相关改动混进自己的提交。

### 4.3 推荐阅读路线

按任务读取最少但足够的资料：

| 任务 | 必读文件 |
|---|---|
| 普通开发 | 本文件、根 README、flashops/README.md |
| 状态机或恢复 | flashops/docs/state-machine.md、decisions/0003-* |
| 事件和数据一致性 | flashops/docs/domain-model.md、decisions/0002-* |
| 安全门禁 | flashops/docs/decisions/0004-*、safety/gates.py |
| Agent | flashops/docs/agent-protocol.md、services/host-agent/README.md |
| 工作流 | flashops/docs/workflow-spec.md |
| 适配器或真实工具 | flashops/docs/adapter-sdk.md |
| 部署、域名、备份 | ProjectManual.md 第 12 章、flashops/deploy/ |

---

## 5. 系统结构与当前边界

~~~text
STORAGE LABOS/
├── CONTRIBUTING.md                 AI 与团队统一入口
├── ProjectManual.md                完整产品、开发和运维手册
├── README.md                       项目总览
├── .gitea/                         PR 模板与未来 CI 工作流
├── flashops/
│   ├── services/control-plane/     FastAPI 控制平面
│   ├── services/host-agent/        拉模式 Host Agent
│   ├── docs/                       架构、协议、状态机、ADR
│   ├── deploy/                     FlashOps 与 Gitea 部署模板
│   ├── var/                        本地数据库和证据，禁止提交
│   ├── Makefile                    开发和验证入口
│   └── README.md                   可运行能力说明
└── 前端UI八页面完成/               FastAPI 同源挂载的静态控制台
~~~

当前已经具备：

- FastAPI 控制平面、14 张持久化表和 SQLite 数据库；
- Run 事件溯源、状态投影、状态机和安全门禁；
- 模拟回归、故障注入、L1–L3 恢复演示和 Evidence Bundle；
- Agent 注册、token、心跳、步骤租约、ACK、续租、事件、完成、超时回收和幂等链路；
- 公开预览控制台及部分真实 API 接入页面。

当前不应声称已经具备：

- 真实 nvme-cli 固件刷写、Format 或 Sanitize；
- 真实 JetKVM、PDU 或 AC 断电控制；
- 完整 SSO、RBAC、审批与审计授权；
- 多工位生产调度、PostgreSQL 高可用；
- 已验收的失败聚类自动决策。

---

## 6. AI 如何安全使用正在运行的系统

### 6.1 公网只读检查

以下请求只读取公开信息，可用于健康诊断：

~~~bash
curl -fsS https://flashops.imagebrewing.com/api/v1/health
curl -fsS https://flashops.imagebrewing.com/api/v1/dashboard/summary
curl -fsS 'https://flashops.imagebrewing.com/api/v1/runs?limit=10'
curl -fsS https://flashops.imagebrewing.com/api/v1/agent/hosts
~~~

不要在诊断任务中为了“试一下”调用生产 POST 接口。健康检查成功不代表业务能力或真实硬件已经验收。

### 6.2 本地启动

~~~bash
cd flashops
make dev
~~~

另开终端检查：

~~~bash
curl -fsS http://127.0.0.1:8000/api/v1/health
curl -fsS http://127.0.0.1:8000/api/v1/dashboard/summary
~~~

### 6.3 本地创建安全的模拟 Run

只在 localhost 使用下面示例：

~~~bash
curl -fsS -X POST http://127.0.0.1:8000/api/v1/runs \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "AI local verification",
    "loops": 2,
    "inject_failure": true,
    "execution_mode": "simulated",
    "created_by": "ai-local"
  }'
~~~

返回 Run ID 后：

~~~bash
curl -fsS http://127.0.0.1:8000/api/v1/runs/RUN_ID
curl -fsS 'http://127.0.0.1:8000/api/v1/runs/RUN_ID/events?after_seq=0'
~~~

也可以直接执行 make demo；它会创建独立的本地模拟链路并输出 Evidence Bundle 路径。

### 6.4 API 快速索引

| 方法与路径 | 含义 | 默认安全级别 |
|---|---|---|
| GET /api/v1/health | 服务健康 | 只读 |
| GET /api/v1/dashboard/summary | 汇总指标 | 只读 |
| GET /api/v1/runs | Run 列表 | 只读 |
| GET /api/v1/runs/{run_id} | Run 详情与证据 | 只读 |
| GET /api/v1/runs/{run_id}/events | 增量事件 | 只读 |
| GET /api/v1/agent/hosts | Agent Host 状态 | 只读 |
| POST /api/v1/preflight | 安全预检 | 计算型；生产调用仍需明确目的 |
| POST /api/v1/runs | 创建 Run | 写操作；生产默认禁止 |
| POST /api/v1/runs/demo | 创建演示 Run | 写操作；生产默认禁止 |
| POST /api/v1/runs/{id}/pause | 暂停 | 写操作 |
| POST /api/v1/runs/{id}/resume | 继续 | 写操作 |
| POST /api/v1/runs/{id}/emergency-stop | 紧急停止 | 高影响写操作 |
| POST /api/v1/agent/* | Agent 注册与执行协议 | 凭据操作；不得随意调用 |

请求体和响应模型以运行时 OpenAPI 为准。本地启动后优先读取
<http://localhost:8000/openapi.json> 或 <http://localhost:8000/docs>，不要凭记忆构造字段。

### 6.5 Agent 使用规则

- 生产注册需要 X-FlashOps-Enrollment-Token；
- 注册成功返回的原始 bearer token 只出现一次，只能保存到权限 0600 的本机状态文件；
- 后续 Agent 请求使用 Authorization: Bearer；
- ACK、续租、事件和完成接口要求 UUID 格式的 Idempotency-Key；
- 不得把 enrollment token、bearer token 或 agent-state.json 输出到聊天、日志或 Git；
- 未经授权不得代表真实 Host 注册、轮换 token 或领取生产步骤；
- 日常开发优先使用 make dev-agent、make agent-demo 和测试夹具。

---

## 7. 三条不可破坏的架构红线

### 7.1 控制面是状态唯一真相

Agent 和测试主机只持有执行缓存。Run、Step、锁、检查点和证据索引的权威状态在控制平面。
不得把 Agent 本地状态反向当成数据库真相。

### 7.2 状态变化必须追加事件

所有 Run 状态变化必须经过 events/recorder.py 的 append_event。不得绕过事件记录直接 UPDATE
Run 状态。新增状态或事件时必须同步修改枚举、转移表、投影逻辑、测试和文档。

### 7.3 安全默认拒绝

序列号、破坏性授权、系统盘、固件型号、Host 和 OOB 任一条件不满足都必须拒绝下发。危险步骤
默认不可自动重试。数据完整性失败要冻结现场，不能为了完成率自动重跑并覆盖证据。

---

## 8. AI 修改代码的标准流程

### 8.1 开始前

1. 确认用户目标属于解释、诊断、开发还是部署；
2. 检查 Git 状态、当前分支和已有改动；
3. 阅读与任务直接相关的源码、测试和文档；
4. 找到当前行为的证据，不能只根据 UI 文案猜测；
5. 若涉及高影响选择，先说明方案和边界。

### 8.2 实现时

- 修改现有项目，不随意建立第二套平行架构；
- 优先小而完整的改动，不混入无关格式化；
- 修复缺陷时增加能复现问题的测试；
- API、状态、事件、环境变量或部署变化必须同步文档；
- 保持 Python 3.9 兼容，不在未修改运行基线前使用更高版本独占语法；
- SQLite 环境保持单 worker；
- 不绕过 service、event recorder、state machine 或 safety gate；
- 保留用户未提交的改动，不擅自覆盖或清理。

### 8.3 完成前

~~~bash
cd flashops
make test
make demo
~~~

回到仓库根目录：

~~~bash
git status -sb
git diff --check
git diff --stat
~~~

只暂存本次任务相关文件：

~~~bash
git add <明确的文件或目录>
git diff --cached --stat
git diff --cached --check
~~~

AI 还必须确认暂存区没有：

- .env、密码、Token、私钥或证书私钥；
- SQLite、日志、Evidence Bundle、Agent state；
- 虚拟环境、缓存、构建输出；
- 未脱敏的客户数据或真实设备标识；
- 无关的用户改动。

---

## 9. 测试与验收门禁

| 变更类型 | 最低验证 |
|---|---|
| 纯文档 | 链接和命令核对、git diff --check |
| Python 逻辑 | make test |
| 状态机、恢复、安全 | 对应单测 + make test + make demo |
| API | 正常、错误、幂等或冲突路径测试 |
| Agent | 控制面与 host-agent 测试，凭据权限检查 |
| 前端 | 真实浏览器检查受影响页面，确认控制台与 API 一致 |
| Nginx | nginx -t 后才能 reload |
| systemd | systemd-analyze verify 或目标机安全验证 |
| 生产部署 | 本地测试、备份、健康检查、HTTPS、日志和回滚检查 |

测试失败时不得把失败包装成完成。先判断是本次回归、环境差异还是已有问题，并保留原始证据。

---

## 10. Git 与 Gitea 交付规范

### 10.1 分支

- main：稳定、可测试、可发布，禁止强推；
- feat/<short-name>：功能；
- fix/<short-name>：缺陷；
- docs/<short-name>：文档；
- chore/<short-name>：工具、依赖和部署。

~~~bash
git switch main
git pull --ff-only
git switch -c docs/ai-operating-guide
~~~

### 10.2 提交

使用 Conventional Commits：

| 类型 | 示例 |
|---|---|
| feat | feat(agent): add signed command registry |
| fix | fix(events): preserve sequence under concurrent writes |
| docs | docs(ai): add system operating guide |
| test | test(safety): reject system disk target |
| refactor | refactor(runs): isolate checkpoint projection |
| perf | perf(api): reduce event timeline query cost |
| chore | chore(deploy): pin gitea image |

一次提交只表达一个完整意图。提交前检查暂存区，不能用一条模糊提交吞掉多项无关工作。

### 10.3 推送与 Pull Request

~~~bash
git commit -m 'docs(ai): add system operating guide'
git push -u origin docs/ai-operating-guide
~~~

在 Gitea 创建 Pull Request，说明：

- 改了什么、为什么；
- 影响的系统边界；
- 实际运行的测试及结果；
- 安全影响；
- 风险、回滚方法和未完成项。

至少一名团队成员评审后合并。优先 Squash merge，PR 标题使用 Conventional Commit。
生产服务器没有 Gitea Actions Runner；仓库中的工作流是未来隔离 Runner 的模板，不能把“工作流存在”
误报成“CI 已运行”。

### 10.4 凭据

公开仓库允许匿名读取和克隆。写操作需要经过批准的 Gitea 账号。管理员密码和访问令牌只允许存在于
系统钥匙串、密码管理器或被 .gitignore 覆盖的本机文件中；不得写进 remote URL、文档、脚本或提交。

---

## 11. 生产部署上下文

| 资源 | 当前值 |
|---|---|
| 云服务器 | 腾讯云 CVM，62.234.39.66 |
| FlashOps 域名 | flashops.imagebrewing.com |
| FlashOps 服务 | flashops.service |
| 应用目录 | /data/wangzhan/app/storage-labos |
| 内部端口 | 127.0.0.1:18080 |
| 应用数据 | /data/wangzhan/app/storage-labos/flashops/var |
| 私有环境文件 | /etc/flashops/flashops.env |
| Gitea 域名 | git.imagebrewing.com |
| Gitea 容器 | gitea，镜像版本固定为 1.27.0 |
| Gitea 内部端口 | 127.0.0.1:13000 |
| Gitea 实时数据 | /data/gitea/data |
| COS 挂载 | /chucun |
| Gitea 备份 | /chucun/wangzhan-production/backups/gitea/ |

生产操作规则：

1. 只有用户明确要求部署或运维时才连接服务器；
2. 先核对主机、域名、当前服务、端口和目标文件；
3. 部署前运行本地测试并备份当前版本和数据；
4. 不直接在服务器编辑项目源码，应由 Git 提交或可核验发布包交付；
5. Nginx 修改必须先测试配置再 reload；
6. SQLite 继续使用单 worker，扩展并发前先迁移 PostgreSQL；
7. Gitea 实时仓库和 SQLite 不得放到 COSFS；
8. COS 只作备份目标，备份需要 ZIP 与 SHA-256 sidecar；
9. 不在输出中展示 SSH、Gitea、Agent、DNS 或云平台凭据；
10. 部署后验证内部 health、外部 HTTPS、最终跳转、日志和回滚点。

FlashOps 当前是匿名预览环境。接入真实硬件或非公开数据前，必须先完成应用级 SSO / RBAC、
审批、审计和命令模板签名；不能只依赖 Nginx Basic Auth。

---

## 12. 常见任务剧本

### 12.1 “看看项目并继续完善”

1. 阅读本文件、README 和相关源码；
2. 运行测试与演示建立基线；
3. 区分已实现、部分实现和待实现；
4. 优先选择一个能独立验收的纵向切片；
5. 实现、补测试、同步文档；
6. 报告实际证据，不把规划写成完成。

### 12.2 “排查网站打不开”

1. 从公网检查 DNS、TLS、重定向和最终状态码；
2. 检查 Nginx 生效配置和日志；
3. 检查本机内部端口和服务状态；
4. 区分 401、403、404、502 和浏览器缓存；
5. 诊断任务只报告原因，除非用户同时要求修复。

### 12.3 “修改 API”

1. 阅读路由、schema、service 和相关测试；
2. 保持业务逻辑不堆在 route；
3. 状态写入走事件记录；
4. 为正常与错误路径增加测试；
5. 检查 OpenAPI；
6. 更新 ProjectManual 和本文件中的接口索引。

### 12.4 “增加真实硬件能力”

先停止直接实现危险命令。必须先确认：

- 使用可牺牲 DUT，不是系统盘；
- 有明确序列号和固件型号匹配；
- 已实现签名命令模板与 allowlist；
- 有审批、短期授权、审计和 Evidence Bundle；
- Agent 与控制面身份可信；
- 有恢复、急停和人工接管方案；
- 用户明确批准真实动作。

条件不完整时，只允许实现接口、模拟器、只读探针和测试。

### 12.5 “发布一个版本”

1. 确认工作树和目标提交；
2. 运行完整测试与演示；
3. 检查秘密和发布范围；
4. 备份服务器应用数据；
5. 部署可追溯提交；
6. 重启并验证内部与公网健康；
7. 检查日志、证书和备份；
8. 记录提交号、时间、验证结果和回滚点。

---

## 13. AI 交付时的固定报告格式

AI 最终回复至少包含：

~~~text
结果：
- 本次目标是否完成

改动：
- 文件与关键行为

验证：
- 实际运行的命令
- 通过/失败数量
- 浏览器或生产验收结果

Git：
- 分支
- 提交号
- Pull Request 或远程地址

风险与边界：
- 尚未实现或未验证的内容
- 是否涉及生产、真实设备或凭据

下一步：
- 仅列真正需要用户决定或后续开发的事项
~~~

不得只说“应该可以”“理论上完成”。必须区分已执行验证、静态检查和推断。

---

## 14. 完成定义

一项 AI 开发任务只有同时满足以下条件才算完成：

- 用户要求的行为已经实现，而不是只写方案；
- 原有未提交工作得到保护；
- 相关测试通过，或失败原因被明确记录；
- 安全门禁、事件写路径和状态机未被绕过；
- 文档与实际代码、API 和部署保持一致；
- 没有提交凭据、生产数据或运行产物；
- Git 提交范围清晰并可回滚；
- 如果要求部署，公网、内部健康、日志和备份均已验证；
- 最终报告包含证据、提交号、风险和边界。

当本文件中的域名、端口、路径、API、安全策略、测试数量或部署结构发生变化时，修改代码的 AI
必须在同一个 Pull Request 中同步更新本文件。