Genarrative/docs/project-memory/shared-memory/team-conventions.md

团队协作约定

协作模式

• 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 状态链路先建立主规范、里程碑规范和单里程碑实现计划，并在评审通过后实现。

开发中

• AGC 主模型追溯保存在项目 .agent/model-usage.jsonl，请求目录标识与响应确认的型号分别记录；旧项目当前配置补录必须标注来源，不冒充历史事实。仅保存有界模型与回合身份字段，不保存配置、凭据或对话正文，不增加 UI 展示。详见 AGC 实施计划“项目主模型使用记录”。

• Agent 提示词正文与工具说明放在所属组件的 prompts/；AGC 通过现有 Prompt Bundle 编译加载，服务端独立 crate 编译包含自己的提示词文件。代码负责变量填充、结构化 schema 与执行校验。

• 策划 Agent 的顾问态由用户指示驱动，不自主推进项目、主动安排下一步或提交阶段审批；完成单次请求不结束顾问态。五个策划阶段的审批用于检阅已完成产物，关键选择先问询；过程文档按需记录且不重复正式正文。顶层设计按需保留易混淆方向及排除理由，提示词精简应保留这些行为与设计边界。详见策划 Agent 生产迁移与工作区浏览方案。

• AGC 思考与执行入口共用共享单行摘要骨架；Markdown 在展开正文走既有安全渲染，折叠预览使用纯文本。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色。

• Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。

• AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。

• AGC 平台服务固定为 https://dev.genarrative.world，会话凭据按 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。
• 已完成计划、阶段测试数字、分支合并流水账和已失效实现口径。