kdletters
485ed50b26
Project CI / AI game creator shell Rust smoke (push) Has been cancelled
Project CI / AI game creator shell Rust crates (push) Has been cancelled
Project CI / Backend tests (push) Has been cancelled
Project CI / Native shell tests (push) Has been cancelled
Project CI / Frontend tests (push) Has been cancelled
Project CI / Repository checks (push) Has been cancelled
Project CI / AI game creator shell web tests (push) Has been cancelled
Project CI / AI game creator shell Rust shard 2/4 (push) Has been cancelled
Project CI / AI game creator shell Rust shard 1/4 (push) Has been cancelled
Project CI / AI game creator shell Rust shard 3/4 (push) Has been cancelled
Project CI / AI game creator shell Rust shard 4/4 (push) Has been cancelled
## 背景 净月潭案例（2026-09-19 21:53 → 09-20 01:26，3 小时 33 分）的问题不是模型慢，而是环境未就绪、验收靠模型自述、预算只约束单个工具入口、工具调用被 SDK 全局串行闸门卡住。本 PR 落地确认后的七项交付效率合同，并把捆绑 Codex 升到当前 npm latest。 ## 结果 - 新建 Web 游戏在正式生成前由宿主自动预检：捆绑 Node/npm、真实 Vite 构建、受限浏览器桌面/移动截图；失败不启动生成或付费素材。 - 首个副作用前冻结交付合同，宿主保存权威证据与预算；证据齐全后先封口、排空并取得执行器完整退出证明，再产出交付报告，模型回复不再当作验收。 - 原生 shell、内置浏览器与托管命令、第三方 MCP 共用同一执行许可和累计执行时间；`validation.maxRuns` 改为执行/返修批次语义，另设 `maxTurnSeconds` 墙钟上限。 - 所有工具可并发：移除 SDK 全局串行的 `apply_patch`/`update_plan` 注册，改由宿主 `agc_apply_patch`（官方 parser + 当前回合写许可 + 受控进程树 + 短项目事务）和 `agc_update_plan` 提供等价能力；真实请求目录里已无串行注册，长 MCP 与补丁/计划实测在同一响应内重叠。 - 付费提交与本地写入绑定原回合原租约：容量与同动作锁等待可取消，封口、取消或预算耗尽后零新增提交；已越过提交边界的请求保留 operation ID 走 GET 对账，不自动重放。 - 新增请求与工具分段计时、有界并行批读和首轮上下文预取，未知耗时不补零。 - 捆绑 Codex 0.147.0 → 0.155.1：固定版本收敛到 `build_support/codex_bundle.rs` 单一声明，vendor 解析源码按 `rust-v0.155.1` 逐字节重取并更新 UPSTREAM 证据，适配 0.155 统一 exec（`exec_command`/`write_stdin`）；macOS 侧车最小系统版本仍为 15.0。 ## 验证 - 生产 CLI → 捆绑 Codex 0.155.1 → 本地 Responses/MCP 夹具 9/9：补丁、完成收尾、批次、只读/可写 MCP 并发、原生命令并发、原生资源并发、统一 exec 会话、期限终止（真实重叠 775 / 764 / 999 ms）。 - 真实模型目录 2/2；vendor 上游库 111 项；宿主定向与回归 106 项；真实 Windows 进程与取消 21 项；Node 侧门禁 52 项。 - 发行载荷：artifact-only 重建 NSIS，解包验证侧车清单 `codex-cli 0.155.1`、6 个组件哈希、打包后 `bin/codex.exe --version`、Node 运行时 2130 文件与双端 PNG、`--environment-check` ready。 - `check-config`、TypeScript、编码（4991 文件）、文档索引、`git diff --check`、`cargo fmt --check` 全部通过。 ## 未覆盖 - 真实陶泥儿登录态 Provider 生成尚未执行（本机 `--llm-status` 返回 `authentication-required`）。 - macOS 侧车只在本机做静态 Mach-O 与清单解析，未在 macOS 上跑 `check-macos-bundle.mjs`。 - 全仓库聚合套件在本机仍因负载敏感的后台 mock-provider 用例而红，与本次改动无关：改动前的旧二进制同样失败，换单线程后相关用例 3/3 通过。 --------- Co-authored-by: kdletters <61648117+kdletters@users.noreply.github.com> Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/439
77 lines
10 KiB
Markdown
77 lines
10 KiB
Markdown
# 团队协作约定
|
||
|
||
## 协作模式
|
||
|
||
- 3 名开发人员在各自环境使用本地 Agent，通过同一 Git 仓库同步代码和项目知识。
|
||
- 每个任务保持分支、工作树和修改范围清晰；多人或多 Agent 并行修改前先划分不重叠的文件边界。
|
||
- 项目知识进入 `docs/` 与 `docs/project-memory/`；个人 `~/.codex`、Agent 会话和本地配置不共享。
|
||
|
||
## 开发前
|
||
|
||
1. 同步目标分支并确认工作树状态，不覆盖他人的未提交修改。
|
||
2. 阅读 `AGENTS.md`；复杂任务继续读取 Agent 执行准则、项目概览、本文、开发工作流和当前专题文档。
|
||
3. 以源码、`package.json`、Cargo manifest、`app.rs`、OpenAPI 和生成契约核对易漂移事实；RAG 与历史记录只提供候选上下文。
|
||
4. 文档不足以确定字段、状态、迁移或验收时，先补当前权威文档再编码。
|
||
5. 跨模块功能、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路先建立主规范、里程碑规范和单里程碑实现计划，并在评审通过后实现。
|
||
|
||
## 开发中
|
||
|
||
- DirectProject 工具可并行调度，依赖由调用方等待，同资源事务与付费动作幂等不能放松。Web 创作先用客户端环境预检，分层验证共用持久的 `validation.maxRuns`，不改写 Provider 的 `llm.maxRetries`；成功证据按输入指纹复用，达标后交付。模型请求计时只保存安全元数据与可观测边界，未知不补零，写盘不能阻塞响应流。详见 AGC 主专题的“DirectProject 交付效率与可观测性”。
|
||
|
||
- DirectProject 源码修改走 `agc_apply_patch`、进度走 `agc_update_plan`：SDK 原生的 `apply_patch` / `update_plan` 注册会被按回合移除（全局串行单例），不要恢复它们或用伪造工具注解换取并发。补丁只在当前项目内、受当前回合 Write 许可和受控进程约束，失败可能已部分写入，未知结果不自动重放；计划完成不构成验收证据。
|
||
|
||
- 捆绑 Codex 版本只在 `build_support/codex_bundle.rs` 固定一次，不要在测试或脚本里另写字面量；升级 SDK 后必须重跑模型目录真实用例、宿主补丁往返、并发夹具与发行载荷 smoke。原生命令工具名随 SDK 版本变化（0.155 起为 `exec_command` / `write_stdin`），脚本与夹具应按真实目录取用，不要按旧名字硬编码。
|
||
- AGC 主模型追溯保存在项目 `.agent/model-usage.jsonl`，请求目录标识与响应确认的型号分别记录；旧项目当前配置补录必须标注来源，不冒充历史事实。仅保存有界模型与回合身份字段，不保存配置、凭据或对话正文，不增加 UI 展示。详见 AGC 实施计划“项目主模型使用记录”。
|
||
|
||
- Agent 提示词正文与工具说明放在所属组件的 `prompts/`；AGC 通过现有 Prompt Bundle 编译加载，服务端独立 crate 编译包含自己的提示词文件。代码负责变量填充、结构化 schema 与执行校验。
|
||
|
||
- 策划 Agent 的顾问态由用户指示驱动，不自主推进项目、主动安排下一步或提交阶段审批；完成单次请求不结束顾问态。五个策划阶段的审批用于检阅已完成产物，关键选择先问询；过程文档按需记录且不重复正式正文。顶层设计按需保留易混淆方向及排除理由，提示词精简应保留这些行为与设计边界。详见策划 Agent 生产迁移与工作区浏览方案。
|
||
|
||
- 策划 Agent 复用现有模型/推理档控件，宿主不另加模型检查或自动换模型。用户发起执行时采样全局选择，同轮工具循环和自动重试固定使用回合快照；自动恢复复用该快照，旧记录保留已知模型并补齐一次推理档。只持久化模型和档位，不保存连接凭据；GameAgent 保持原逻辑。详见策划 Agent 生产迁移与工作区浏览方案 §4.1。
|
||
|
||
- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 在展开正文走既有安全渲染，折叠预览使用纯文本。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色。
|
||
|
||
- Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。
|
||
|
||
- AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。
|
||
|
||
- AGC 正式包的平台服务跟随构建渠道：`release` 连接 `https://www.genarrative.world`，`dev` 连接 `https://dev.genarrative.world`；本地 debug 态保留 release/dev/custom 服务器选择，会话凭据始终按 origin 隔离。发布渠道为 `dev/release/自定义名称`，Windows/Mac 是系统，OSS 的 `<channel>-win/mac` 仅是延续既有地址的分区。官网通过服务端 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（默认 dev）选择渠道，公开同源 `/api/client-downloads` 汇总其各系统首装包与真实版本；未发布隐藏，单系统失败不影响其它下载，不跨渠道补齐。发布先上传 EXE/DMG 再写对应分区清单，不维护会互相覆盖的共享 OSS 索引。主站 Vite 代理复用实际 `runtimeServerTarget`。完整约定见 AGC 客户端更新检查与下载专题。
|
||
- AGC 模板库灰度复用 `agc:template-library`：未配置关闭，已配置时遵循现有灰度启停、用户 ID/标签和比例规则；服务端返回权威结论，客户端入口和原生清单/下载/建项均执行门禁，主体切换丢弃旧异步结果。公开 OSS 不是保密边界，已创建项目不受影响。
|
||
|
||
- 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
|
||
- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本。
|
||
- Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
|
||
- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用。共享组件承载通用表现与交互，领域规则、后端副作用和正式业务状态由后端负责。
|
||
- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；过程字号和颜色由共享组件统一定义，错误状态保留语义色。
|
||
- 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
|
||
- 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
|
||
- 对已明确退役且无现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
|
||
- 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
|
||
- 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
|
||
- 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。
|
||
- HTTP 横切能力集中在 Axum/Tower 中间件：正常与降级路由复用追踪层；指标与 trace 使用 `MatchedPath` 模板及固定兜底，不把请求 ID、实际资源 ID 或 query 放入指标标签。在途请求通过 RAII guard 覆盖 Future 取消与 panic unwind；请求执行和响应体存活分别计量，不能把 handler 耗时当作 SSE 全生命周期。
|
||
- 业务依赖在组合根显式装配，Axum `FromRef` 只抽取可浅拷贝的窄能力。项目元数据与 External API 鉴权不持有完整 `AppState`，测试经相同接口注入替代依赖。集中鉴权仍保留方法级 fallback、公开入口、MCP 和 body limit 顺序；Provider span 跳过完整参数，不隐藏计费、重试、幂等或事务规则。
|
||
- 中文文案、注释和文档保持中文与 UTF-8，优先局部补丁。
|
||
|
||
## 文档生命周期
|
||
|
||
- `docs/README.md` 只索引当前实现依据和仍维护专题。
|
||
- `shared-memory/` 只保留当前稳定概览、决策、流程和坑点；同一事实不复制多份版本。
|
||
- `plans/` 只放正在执行且有明确剩余门禁的短期计划；`todos/` 只放真实开放且有关闭条件的事项。
|
||
- 计划完成、事项关闭或对象退役后，稳定结论融合进权威专题或共享记忆，过程文档直接删除；历史由 Git 提供。
|
||
- 新增 Markdown 使用 `【标签名】中文标题-YYYY-MM-DD.md` 命名。
|
||
|
||
## 开发后
|
||
|
||
1. 运行范围匹配的测试、类型检查、`npm run check:encoding` 和 `git diff --check`。
|
||
2. 更新对应当前专题；产生长期有效变化时再更新共享记忆。
|
||
3. 检查 staged diff，确保没有无关文件、密钥、本地路径或他人改动。
|
||
4. 提交标题使用中文；标题后逐行写明修改项，每项单独一行。
|
||
|
||
## 禁止提交
|
||
|
||
- `.env`、API Key、Token、Cookie、认证文件和个人配置。
|
||
- 个人绝对路径、会话记录、隐私信息。
|
||
- 构建产物、日志、缓存和数据库 dump。
|
||
- 已完成计划、阶段测试数字、分支合并流水账和已失效实现口径。
|