# 开发工作流

更新时间：`2026-05-15`

## 标准流程

```text
同步代码 -> 读取 AGENTS.md -> 读取 .hermes/shared-memory -> 查当前 docs -> 小步实现 -> 本地验证 -> 更新 docs / .hermes -> 提交
```

当前 `docs/` 已压缩为少量融合文档。复杂任务优先读：

1. `docs/README.md`
2. `docs/【项目基线】当前产品与工程约束-2026-05-15.md`
3. `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
4. `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
5. `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`

## 本地运行命令

安装依赖：

```bash
npm install
```

完整联调：

```bash
npm run dev
```

单独启动前端：

```bash
npm run dev:web
```

单独启动 Rust API server：

```bash
npm run api-server
```

后台前端：

```bash
npm run admin-web:dev
npm run admin-web:build
npm run admin-web:typecheck
```

SpacetimeDB bindings：

```bash
npm run spacetime:generate
```

## 常用检查

```bash
npm run check:encoding
npm run check:spacetime-schema
npm run check:server-rs-ddd
npm run lint:eslint
npm run typecheck
npm run test
npm run build
npm run check:content
```

综合检查：

```bash
npm run lint
npm run check
```

视觉小说门禁：

```bash
npm run check:visual-novel-vn11
npm run check:visual-novel-vn12
```

## 后端默认验证

后端代码修改后按范围选择：

- `cargo test -p <crate> --manifest-path server-rs/Cargo.toml`
- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
- `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`
- `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`
- `npm run check:server-rs-ddd`
- `npm run api-server` 后请求 `/healthz`

涉及 SpacetimeDB table、reducer、procedure、row shape 或 bindings 时，还必须运行：

```bash
npm run spacetime:generate
npm run check:spacetime-schema
```

禁止使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。

## 前端默认验证

前端修改后按范围选择：

- `npm run check:encoding`
- `npm run lint:eslint`
- `npm run typecheck`
- `npm run test -- <具体测试文件>`
- 页面交互 smoke
- 移动端视口检查

UI 相关修改重点检查：

- 390px 左右移动端宽度不横向溢出。
- 输入法弹出时平台画布不被压缩。
- 弹窗、抽屉和独立面板没有实现成当前面板下方展开。
- UI 不包含默认规则说明长文。
- 私有图片和音频不裸请求 `/generated-*`。

## 文档更新

- 工程修改要同步更新当前 `docs/` 文档。
- 新增稳定知识优先合并进现有 4 份文档；只有现有文档无法容纳时才新增带 `【标签名】` 的 Markdown。
- `.hermes/shared-memory/` 只记录高频、长期、团队共享的摘要和索引。
- 阶段性流水账、一次性计划和已关闭 TODO 不再作为长期仓库文档依据。
- 如果 `.hermes/shared-memory/` 与代码或 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正共享记忆。