suzmii
2257a78d6b
思考展开时隐藏重复预览并使用灯泡图标，首个响应前显示临时思考提示。 统一分钟内小数和分钟以上整数秒，保持内外过程的紧凑间距与正文层级。 失败工具与分组显示错误色，非零退出码不再误判为成功。 补齐状态、格式、样式和交互回归，本批其余需求留待后续PR。
58 lines
5.2 KiB
Markdown
58 lines
5.2 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 状态链路先建立主规范、里程碑规范和单里程碑实现计划，并在评审通过后实现。
|
|
|
|
## 开发中
|
|
|
|
- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 只在展开正文走既有安全渲染，折叠预览只取纯文本，不在 summary 嵌套链接或按钮。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色，不由自然语言输出猜测。
|
|
|
|
- Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。
|
|
|
|
- AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。
|
|
|
|
- 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
|
|
- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
|
|
- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
|
|
- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；宿主不按 Agent 类型重新定义过程字号和颜色，错误状态保留语义色。
|
|
- 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
|
|
- 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
|
|
- 对已明确退役且无现役调用方、公开契约、持久化迁移或活跃实例的对象，不写兼容实现、维持旧行为的测试、墓碑注释或墓碑文档。
|
|
- 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
|
|
- 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
|
|
- 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。
|
|
- 中文文案、注释和文档保持 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。
|
|
- 已完成计划、阶段测试数字、分支合并流水账和已失效实现口径。
|