GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 35 Pull Requests 13 Actions Packages Projects 1 Releases Wiki Activity

Refactor local dev stack scheduler

Browse Source
This commit is contained in:
kdletters
2026-05-15 09:37:08 +08:00
parent 0152f9bd67
commit 7a3b137565
20 changed files with 2393 additions and 2088 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.hermes/shared-memory/decision-log.md
+83 -171
View File
File diff suppressed because it is too large Load Diff
.hermes/shared-memory/development-workflow.md
+158 -56
View File
@@ -1,20 +1,40 @@
# 开发工作流
更新时间：`2026-05-15`
> 用途：给本地 Hermes 和开发人员提供统一的开发、测试、提交流程。具体命令以 `package.json`、`server-rs/Cargo.toml`、`AGENTS.md` 和相关 `docs/` 最新文档为准。
## 标准流程
## 标准任务流程
```text
同步代码 -> 读取 AGENTS.md -> 读取 .hermes/shared-memory -> 查当前 docs -> 小步实现 -> 本地验证 -> 更新 docs / .hermes -> 提交
同步代码 → 读取 AGENTS.md → 读取 .hermes/shared-memory → 查找/完善 docs → 制定计划 → 小步实现 → 本地验证 → 更新文档/记忆 → 提交
```
当前 `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`
在项目根目录启动 Hermes：
```bash
cd /path/to/Genarrative
hermes
```
在本机当前常见路径为：
```bash
/home/dsk/workspace/Genarrative
```
其他开发者以自己本地实际路径为准，不要把个人绝对路径写入共享文档作为通用规则。
## 开发前检查清单
- [ ] 当前分支是否正确
- [ ] 是否已拉取最新代码
- [ ] 是否阅读 `AGENTS.md`
- [ ] 是否阅读 `.hermes/shared-memory/` 相关文件
- [ ] 是否阅读 `README.md` 中的运行和检查命令
- [ ] 是否阅读 `docs/README.md` 及任务相关分类 README
- [ ] 是否存在足够具体的 PRD / 设计 / 技术文档
- [ ] 是否明确测试、验收和文档更新方式
## 本地运行命令
@@ -24,108 +44,190 @@
npm install
```
完整联调：
完整联调开发环境：
```bash
npm run dev
```
该命令会启动：
- SpacetimeDB standalone
- Rust `api-server`
- 主站 Vite
- 后台 Vite
开启自动刷新：
```bash
npm run dev -- --watch
```
watch 模式只由外层调度器自动处理后端侧刷新：`spacetime-module` 改动后重新发布模块但不重启 standalone 宿主，`api-server` 改动后重启 Rust 进程。主站 Vite 与后台 Vite 的源码变化交给 Vite 自身 HMR，避免外层 watcher 监听到依赖缓存或临时文件后循环重启。
非 watch 模式下，`npm run dev` 终端支持输入 `rs spacetime`、`rs api-server`、`rs web`、`rs admin-web` 或 `rs all`。其中 `rs spacetime` 只会重新发布 `spacetime-module`，不会重启 standalone 宿主；其他模块仍按进程重启。
单独启动 SpacetimeDB：
```bash
npm run dev:spacetime
```
单独启动 Rust API server：
```bash
npm run dev:api-server
```
单独启动前端：
```bash
npm run dev:web
```
单独启动 Rust API server：
单独启动后台管理前端：
```bash
npm run api-server
npm run dev:admin-web
```
后台前端：
`npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-<timestamp>.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。
查看本地 Rust/SpacetimeDB 日志：
```bash
npm run dev:spacetime:logs
```
后台管理前端：
```bash
npm run admin-web:dev
npm run admin-web:build
npm run admin-web:typecheck
```
SpacetimeDB bindings：
SpacetimeDB bindings 生成：
```bash
npm run spacetime:generate
```
## 常用检查
## 常用检查命令
- 后端通用用户行为埋点统一通过 `record_tracking_event_and_return` procedure、`SpacetimeRuntimeClient::record_tracking_event(...)` 与 api-server `tracking` 中间件写入 `tracking_event` / `tracking_daily_stat`；后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 默认排除；作品级游玩埋点统一使用 `work_play_start`，详细事件清单见 `docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md`。
编码检查：
```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
```
综合检查：
ESLint：
```bash
npm run lint:eslint
```
类型检查：
```bash
npm run typecheck
```
综合 lint：
```bash
npm run lint
```
测试：
```bash
npm run test
```
生产构建：
```bash
npm run build
```
内容检查：
```bash
npm run check:data
npm run check:overrides
npm run check:smoke
npm run check:content
```
全量检查：
```bash
npm run check
```
视觉小说门禁：
DDD 边界检查：
```bash
npm run check:visual-novel-vn11
npm run check:visual-novel-vn12
npm run check:server-rs-ddd
```
## 后端默认验证
## 后端相关默认验证
后端代码修改后按范围选择：
后端修改后，按 DDD 文档中的验收命令执行。涉及 API smoke 时：
- `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`
- 使用 `npm run dev:api-server` 重新拉起后端。
- 禁止使用 `npm run api-server:maincloud`、`npm.cmd run api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径；这些只属于历史残留。
- 检查 `/healthz`。
- 执行对应自动测试。
- 涉及 SpacetimeDB 表、reducer、procedure、row shape 或绑定变化时，同步更新 `migration.rs`、表目录和生成绑定。
- SpacetimeDB 已有表新增字段必须放在 Rust 表结构体最后，并设置明确默认值；需要修改字段名时，先询问用户并确认迁移计划，再同步更新 `server-rs/crates/spacetime-module/src/migration.rs`、表目录和生成绑定。
- 修改 SpacetimeDB schema 后运行 `npm run check:spacetime-schema`，用自动检查拦截缺 default、插入中间、字段删除/改名/重排/改类型，以及漏改迁移、表目录或绑定。
涉及 SpacetimeDB table、reducer、procedure、row shape 或 bindings 时，还必须运行：
关键文档：
```bash
npm run spacetime:generate
npm run check:spacetime-schema
```
- `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
- `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
- `docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
- `docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
- `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
- `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
- `docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`
禁止使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
## 前端相关默认验证
## 前端默认验证
前端修改后按范围选择：
前端修改后，应根据修改范围选择：
- `npm run check:encoding`
- `npm run lint:eslint`
- `npm run typecheck`
- `npm run test -- <具体测试文件>`
- `npm run test`
- 页面交互 smoke
- 移动端视口检查
UI 相关修改重点检查：
前端原则：
- 390px 左右移动端宽度不横向溢出。
- 输入法弹出时平台画布不被压缩。
- 弹窗、抽屉和独立面板没有实现成当前面板下方展开。
- UI 不包含默认规则说明长文。
- 私有图片和音频不裸请求 `/generated-*`。
- 移动端优先，再兼容网页端。
- 页面只展示后端返回的状态，不自行计算结论型业务状态。
- 创作中心入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；前端只在 `platformEntryCreationTypes.ts` 做展示派生，api-server 路由熔断也使用同一份配置，禁止恢复前端硬编码入口配置文件。
- 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
- 不在 UI 中默认写功能说明类文本。
- 弹出独立面板的交互不要实现成在当前面板下方追加内容。
## 文档更新
## 文档更新规则
- 工程修改要同步更新当前 `docs/` 文档。
- 新增稳定知识优先合并进现有 4 份文档；只有现有文档无法容纳时才新增带 `【标签名】` 的 Markdown。
- `.hermes/shared-memory/` 只记录高频、长期、团队共享的摘要和索引。
- 阶段性流水账、一次性计划和已关闭 TODO 不再作为长期仓库文档依据。
- 工程修改要同步更新对应文档。
- 如果没有现成文档，新文档统一放入 `docs/` 下合适分类。
- `.hermes/shared-memory/` 只记录高频、长期、团队共享的摘要和索引，不替代完整 PRD/技术文档。
- 如果 `.hermes/shared-memory/` 与代码或 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正共享记忆。
## 提交前建议让 Hermes 执行
```text
请检查当前 git diff，指出：
1. 是否违反 AGENTS.md 或 .hermes/shared-memory 约定；
2. 是否需要补充 docs；
3. 是否有长期知识需要写入 .hermes/shared-memory；
4. 建议的测试命令和提交信息。
```
.hermes/shared-memory/pitfalls.md
+133 -196
View File
File diff suppressed because it is too large Load Diff
.hermes/shared-memory/team-conventions.md
+70 -34
View File
@@ -1,64 +1,100 @@
# 团队协作约定
更新时间：`2026-05-15`
> 用途：约定 3 名开发人员在各自本地 Hermes 中协作开发、共享项目记忆的方式。
## 基本模式
- 每位开发人员在自己的电脑上使用本地 Hermes。
- 团队共享内容放在仓库 `.hermes/` 与 `docs/` 中，通过 Git 同步。
- 不共享个人 `~/.hermes` 目录、密钥、会话、Token、Cookie、认证文件、本地私密路径或构建产物。
- 每位开发人员本地拉取同一个项目仓库，独立修改代码、运行测试、提交分支。
- 团队共享内容优先放在本仓库 `.hermes/` 与 `docs/` 中，通过 Git 同步。
- 不共享个人 `~/.hermes` 目录。
## 共享与禁止共享
推荐共享：
- `.hermes/shared-memory/` 团队级长期记忆
- `.hermes/plans/` 阶段性实施计划
- `.hermes/todos/` 已确定需要执行、但尚未进入实施的共享 TODO 计划
- `.hermes/skills/` 未来可复用仓库级 skills
- `docs/` 中 PRD、设计、技术、经验、审计、查询手册
- `AGENTS.md` 项目级 Agent 约束
禁止提交：
- 个人 `~/.hermes/config.yaml`
- 个人 `~/.hermes/.env`
- 个人 `~/.hermes/sessions/`
- API Key、Token、Cookie、认证文件
- 个人本地私密路径和个人隐私信息
- 构建产物、日志、缓存、数据库 dump
## 开发前
1. 拉取最新代码。
2. 阅读 `AGENTS.md`。
3. 阅读 `.hermes/shared-memory/` 中与任务相关的文件。
4. 阅读 `docs/README.md` 和 4 份当前融合文档中与任务相关的部分。
5. 如果文档不足以指导编码，先补充或修正文档。
当前文档入口：
- `docs/【项目基线】当前产品与工程约束-2026-05-15.md`
- `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
- `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
- `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
4. 阅读 `docs/README.md` 和任务相关分类 README。
5. 阅读对应 PRD、设计、技术、经验或审计文档。
6. 如果文档不足以指导编码，先补充或修正文档。
## 开发中
- 保持修改范围聚焦，不做无关重构。
- 优先复用、修改、扩展现有系统、页面、组件和弹层。
- 新增 Markdown 文档时，文件名必须以分类标签开头，格式为 `【标签名】中文标题-YYYY-MM-DD.md`。
- 阶段性计划、一次性 TODO 和已关闭实验不要长期沉淀为仓库文档；仍有效内容合并进当前 `docs/` 或 `.hermes/shared-memory/`。
- 复用、修改、扩展现有系统优先，避免新建重复系统或页面。
- 新增 Markdown 文档时，文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；只在任务需要时重命名历史文档，避免无关大 diff。
- 涉及中文文本时注意 UTF-8 编码和乱码排查。
- 涉及后端时遵循 DDD 分层，不把业务真相下沉到前端或临时兼容层。
- `maincloud` / `Maincloud` / `MAINCLOUD` 相关代码、脚本、测试、环境变量、命令和文档要求均视为历史残留，禁止新增、运行或引用。
- API smoke 统一使用 `npm run api-server` 与 `/healthz`。
- 涉及 SpacetimeDB 表结构、发布或迁移时，先看当前后端架构文档的 schema 变更规则和表目录。
- 涉及生产发布、服务器配置、Jenkins Job 重建或回滚时，先看当前开发运维文档。
- `maincloud` / `Maincloud` / `MAINCLOUD` 相关代码、脚本、测试、环境变量、命令和文档要求均视为历史残留，禁止新增、运行或引用；API smoke 统一使用 `npm run dev:api-server` 与 `/healthz`。
- 涉及 SpacetimeDB 表结构、发布或迁移时，先看 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md` 和 `SPACETIMEDB_TABLE_CATALOG.md`。
- 涉及生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
## 开发后
1. 运行与修改范围匹配的测试或验证命令。
2. 更新相关 `docs/` 当前文档。
3. 若产生长期有效知识，更新 `.hermes/shared-memory/`。
4. 若形成可复用流程，考虑沉淀到 `.hermes/skills/`。
5. 提交信息区分代码变更、文档变更和共享记忆变更。
2. 更新相关 `docs/` 文档。
3. 新增或沉淀 Markdown 文档时，确认文件名已使用 `【标签名】` 前缀。
4. 若产生长期有效知识，更新 `.hermes/shared-memory/`。
5. 若形成可复用流程，考虑沉淀到 `.hermes/skills/`。
6. 在提交信息中区分代码变更与文档/记忆变更。
## 文档阅读顺序
通用任务建议：
1. `README.md`
2. `AGENTS.md`
3. `.hermes/shared-memory/`
4. `docs/README.md`
5. `docs/experience/README.md`
6. `docs/audits/README.md`
7. 任务所属分类：`docs/design/`、`docs/technical/`、`docs/planning/`、`docs/prd/`、`docs/reference/`、`docs/tracking/`、`docs/operations/`
后端任务建议：
1. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
2. `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
3. `docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
4. `docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
5. `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
6. `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
7. `docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`
## 共享记忆更新准则
适合更新：
- 稳定架构约定。
- 长期开发流程。
- 已验证的踩坑和排障步骤。
- 重要接口契约变化。
- 团队协作规范变化。
- 当前文档索引或阅读顺序变化。
- 新增稳定架构约定
- 新增长期开发流程
- 已验证的踩坑和排障步骤
- 重要接口契约变化
- 团队协作规范变化
- 文档索引或阅读顺序变化
不适合更新：
- 一次性临时计划。
- 未验证猜测。
- 个人偏好和个人路径。
- 敏感信息。
- 大段聊天记录。
- 一次性临时计划
- 未验证猜测
- 个人偏好和个人路径
- 敏感信息
- 大段聊天记录