项目开发与 Agent 协作约定

交付正确、可验证、易维护的行为变化。用户明确要求优先；先理解目标和约束，再在根因所在的位置解决问题，不以少改文件或测试变绿代替完整修复。

建立上下文

• 开始前检查分支、工作区 diff 和相关入口，区分已有改动与本次变更。保护用户文件与未提交内容，不擅自覆盖、清理或回退。
• 沿调用链阅读受影响的实现、调用方和测试；只扩展到与目标行为有关的范围，不机械遍历全仓或顺手重构无关模块。
• 代码、测试和文档不一致时查明依据，不把现有实现自动当作正确设计。不确定性先通过源码和可逆实验消解，必须由用户决定的取舍再具体询问。
• 长任务保留目标、关键证据、已排除方案、当前状态和下一步；恢复时先核对现有改动，避免重复已证伪的尝试。
• 排查"改了却没生效"时，先确认应用在用哪个数据 home：开发模式可能走便携模式——src-tauri/target/debug/portable-data.json（release 构建对应 target/release/）的 appHome 会把会话库、设置、插件整体重定向到别处（本机曾被指到一个非默认目录，形如 D:\<便携数据目录>），此时 ~/.ccgui-next/app.db 是另一个旧库；看错库会得出完全相反的结论（本项目真实发生过：据此误判"分叉标题从未写入"，浪费一轮）。另外 app.db 走 WAL，写入先进 app.db-wal、checkpoint 时才回写主库，主库文件 mtime 不随每次写入更新，不能用它判断库是否活跃（要看 app.db-wal）。该文件在 target/ 下，cargo clean 会删掉它并切回默认 home。

项目边界

• 本项目是 Tauri 桌面客户端：前端功能在 src/features，通用 UI 在 src/components，原生能力在 src-tauri/src，插件公共契约在 packages/plugin-sdk。
• 行为放在实际负责它的模块，优先复用既有入口。引擎协议差异在适配层处理，不在 UI 中散布引擎特判；插件通过公共 SDK 与注册接口接入。
• 修改 IPC、事件格式或插件契约时，同时核查生产方、消费方、兼容行为和失败路径。不用空实现、吞异常或假成功隐藏缺口。
• 用户可见文本沿用 src/i18n 的国际化方式。日志保留必要错误上下文，不输出凭据、完整用户对话或其他敏感数据；清理临时调试输出。
• 工具版本和命令以当前 package.json、锁文件与实际配置为准。当前使用 pnpm workspace，pnpm dev 启动 Tauri，pnpm build 执行类型检查与前端构建；不要照搬过时 README 中的启动命令。

设计与修复

• 先明确成功、失败和取消时的预期行为。缺陷优先构造能够揭示旧行为错误的复现或回归用例，再证明修复有效。
• 同一根因影响多个入口时一并处理；有明确语义差异的实现不强行统一。不为猜测中的未来需求引入抽象。
• 权限、插件隔离、进程生命周期、异步事件、数据迁移等改动，额外核查边界条件、兼容性与恢复方式。风险提高意味着加强分析和验证，不自动要求停工或重复确认。
• 不通过放宽断言、跳过测试或修改验收标准制造通过结果。删除旧实现前核对调用方、外部契约和迁移状态。
• 用户可见的交互反馈、基础组件视觉与动效时长以 docs/ui-ux-spec.zh-CN.md 为准；新增或修改这类行为时同一个提交内更新该文档，新增刷新/重载入口按规范登记到其清单。
• 改动插件 SDK、扩展点或权限目录后，同一个提交内跑 pnpm plugin-skill:docs 重新生成内置插件开发 skill（src-tauri/resources/skills/ccgui-plugin-creator/references/sdk-api.md）：它是插件作者与 AI 看到的说明书，pnpm test 里的 creator-skill-docs.test.ts 会断言生成物与源码一致，过期即红。

对话性能与完整性

• 存储内容与展示动画分离：平滑输出不得丢字、重复、乱序、回退或修改原文；完成、中断、错误和恢复必须正确收敛。
• 优化时同时检查中文与 emoji 边界、Markdown 结构、代码块、复制内容、历史加载和会话切换。不要为了增量渲染破坏引用链接、表格或插件扩展。
• 保持未变消息引用稳定，避免历史列表、已完成工具行和代码块随每个增量重复计算。缓存必须有边界，并考虑外部插件修改节点时的隔离。
• 定时器、帧回调、订阅和子进程必须有清理路径；检查卸载、后台、取消以及旧任务晚到的更新。
• 性能结论必须说明测量对象与条件。区分上游到达间隔、IPC 等待、解析成本和页面显示延迟；局部基准、回放与真实原生应用结果不能混称。未测量不宣称提升，不用不断增加展示延迟掩盖根因。

按影响验证

• 纯文档、注释等低影响改动做内容与差异检查即可，不强制跑全量构建。
• 功能、Bug 和重构按受影响链路验证；高风险改动增加失败、取消、并发及恢复场景。检查通过后，除非出现新改动或新疑点，不机械重复无关测试。
• 常用验证入口按需选用：
  • pnpm build：前端类型检查和构建。
  • pnpm exec vitest run <相关测试路径>：Vitest 测试；核对实际发现及执行的用例。
  • pnpm test:node（pnpm test 会先跑它）：tests/*.test.ts 下的流式调度、Markdown 与缓存回归，需 Node 22.13+。
  • 在 src-tauri 下执行 cargo test <相关过滤条件>；发送与中断链路可用 cargo test --test send_path。
  • 真实 React 提交与定时器交错验证见 tests/browser/README.md。
• 报告实际通过、失败、跳过和未覆盖项；不能仅凭退出码为零或构建通过，就声称用户问题已经解决。

运行与交付

• 用户要求「生成版本记录 / release notes / changelog」时，必须同步更新 src/version/changelog.ts 的 CHANGELOG_DATA（应用内「版本更新」弹窗的唯一数据源：双语条目、最新在前、需人工追加）；只生成外部 Markdown 文件不算完成。若同时产出独立版本记录文件，两处内容应一致。
• 启动或重启前检查当前项目的应用进程和开发端口，确保只运行一份；只停止已确认属于本项目的进程，不误杀其他项目。完成后核实应用和服务均已启动。
• 区分前端热更新、后端自动重新编译与完整重启，不把热更新说成已重启。未安装的可选引擎应如实说明，不因此擅自安装或修改用户配置。
• 严禁主动提交：任何 git commit、git push 都必须由人类明确决策，AI 不得自行执行。完成改动后先报告结果并等待用户指示；只有用户在当前对话中明确要求提交或推送时才执行，历史授权或惯性不得作为依据。提交只包含本次相关文件，使用描述性标题，说明行为变化与验证结果。推送不等于获准合并 PR、部署或操作共享环境。
• 创建 PR 前检查是否已有对应 PR，确认目标分支与最终差异；描述面向未参与对话的评审者，写清问题、改动、验证和实际限制。
• 交付说明以结果为先：改了什么、为何修改、如何验证、还有哪些限制。不要把阶段性结果说成全部完成。

维护规则

根文件只保留适用于本项目的高价值约定。新增规则应来自真实问题，合并重复项、删除失效内容；不要照搬其他技术栈、组织流程或不存在的文档链接。