当前项目的全量设计方案位于： docs\gold-band\产品设计文档 当前项目的MVP版本开发计划位于： docs\gold-band\开发计划 每次代码修改，必须同步维护以上两类文档
每次实现需求时，都应该先思考，当前的需求，是否已经有现有的开源组件可以满足需求，是否已经有行业内最佳实践，都没有的话，才考虑自己实现。 每次出方案时，必须先告诉用户当前的方案才开始实现，方案设计时对问题的解决思路是：1.这个问题是否来源于根本性的设计缺陷？如果是则需要把设计缺陷一起修复掉，宁愿多付出一些成本 2.这个问题是否是来源于好的设计但是实现不够完善？如果是则基于好设计，继续完善实现。必须杜绝针对特定问题的补丁式修复。 每次实现功能后并验证无误后，必须进行单元测试，从接口层面把正确验收固化下来，这样方便后续改动时进行回归。
优秀的设计思路： 1.分析哪些数据结构 2.不同数据结构分属于哪些不同领域 3.生命周期相关联的数据结构，状态应该统一管理 4.先定数据、再定接口、再补实现 5.杜绝硬编码，应该统一设置成变量，设计时要考虑到变量的应用范围，可复用的应该有单独的类管理，类中单独的变量则可以放在类中 6.错误码等不要使用简单的string，而是用结构体管理，至少包含code、msg等字段，后端只返回错误码，前端根据错误码进行处理，后端不应该包含任何对客文案的处理 7.使用现代开发的最佳实践，积极使用现成的库、框架、工具、组件等，严禁无效地重复造轮子
当前项目前端使用tailwindcss+shadcn-ui, chat ui界面使用prompt-kit。必须优先根据页面需要使用组件库生成copy-in代码，不能自己手写代码，可以在生成的copy-in代码中，根据需要进行修改
当前项目所有内置提示词（profile、runtime、repair、AI-DYNAMIC 等）必须统一放在 src/prompts/ 下管理，不允许把长 prompt 文本散落硬编码在实现代码里。
提示词目录必须按语言组织为 src/prompts/zh-CN/... 和 src/prompts/en/...，语言目录下的子目录结构必须保持一致；新增或修改提示词时，必须同步维护中英文版本。
system prompt / user prompt 的固定区分标准：
- 由 runtime 决定、用户不需要直接操心、且需要稳定执行的上下文，放 system prompt，例如角色、历史、目录路径、文件规则、能力边界、剩余预算、输出协议、repair 指令。
- 与本次执行目标直接相关、会随任务变化的内容，放 user prompt，例如 requirement、goal、当前 task。
- 任何需要模板变量、条件分支或修复重试的提示词，也必须继续放在
src/prompts/下统一管理和渲染，不能回退成代码内硬编码字符串。
- Gold Band 是 EXE 桌面产品，主路径不要保留 command bar / terminal 心智。
- 优先使用菜单、工具栏、按钮、上下文菜单、对话框、设置页等原生可视化交互。
- 前端样式和交互优先使用 shadcn/ui、Tailwind CSS utilities 和成熟依赖。
- AI chat / ACP / agent session UI 优先使用 prompt-kit copy-in 组件。
- 不要自研消息容器、输入框、工具调用卡片、Markdown 渲染等基础控件；只在项目 i18n、数据映射或样式 token 需要时修改 copy-in 组件。
- 涉及 UI、交互、页面布局、样式或客户端流程时，必须启动前端并验证。
- 优先 deep link 到目标页面，避免从任务列表反复手动点入。
- 验证结束后清理自己启动的测试资源，避免长期会话堆积。
- 当前项目仍处于开发阶段，明确替换旧方案时优先删除旧入口、旧字段、旧消费路径。
- 不为旧 UI 或旧数据结构增加兼容层、灰度逻辑和 fallback。
- UI 只展示帮助用户决策或完成操作的文案。
- 不展示解释实现方式、布局原因、未来扩展性的说明。
- 深色主题减少浅黑色方块、嵌套卡片和强边框。
- 通过留白、层级、少量边界和重点状态表达，而不是堆叠面板。
- Chat / ACP / agent message 中 Markdown 标题不要使用文档页大标题样式。
- 标题字号接近正文，通过字重、轻量间距、细分隔表达层级。
- ACP 工具/思考结构化行不显示头像，但保留横向位置。
- ACP 工具卡片高度压缩，标题左对齐，展示操作名和关键参数。
- ACP 的“发送中 / 处理中 / 计时”状态放 composer 内，不作为消息流卡片。