gongxiangp2/docs/photocraft-client-design.md

详情页原生客户端设计标准

更新：2026-10-23。适用于 apps/detail-photocraft 的二次开发；不替换线上素材库、旧 Electron 客户端或品牌中心的设计规范。

定位与依据

给品牌中心制作产品详情页的 Windows 原生创作工具。主工作面属于 Operate：用户看作品、操作图层、与 Agent 协作，界面应退到作品之后。

视觉和排版布局以 PhotoCraft 原生编辑器为主要参考，不沿用用户已否定的网页式四步大面板。保留素材库 Logo、账户、品牌、产品和项目等业务语义。沿用 PhotoCraft Pro 系列的平面灰阶工作区与蓝色操作反馈；源码默认 Pro Medium，主题可切换，本次 Agent 面板回归覆盖 Pro Medium 与 Pro Light。界面不借用 ArtCraft 的名称或品牌标志。

本地源码基线固定为 PhotoCraft v0.10.0 / 8407d9ccb125af52944fca9d228383459f94aaef，与此前实际验收的原版一致。版本升级需重验中文文字、共享撤销历史、PSD 和 GPU 显示。

工作区布局

┌ Logo  原生菜单                                                    ┐
├ 当前工具选项                我的项目  添加素材  产品资料  同步  账户 ┤
├ 工具条 ┬ 文档标签 / 画布                              ┬ Agent / 图层 ┤
│        │                                             │ 对话与操作记录 │
│        │                  可编辑作品                  │               │
│        │                                             │               │
│        │                                             ├───────────────┤
│        │                                             │ 对话 / 生图    │
│        │                                             │ 要求输入 / 设置 │
│        │                                             │ 双模型同一行   │
│        │                                             │            发送 │
├────────┴ 缩放、尺寸、保存状态                          ┴───────────────┤

• 中央画布始终为主区域，开关项目、素材或设置不能清空、替换尚未保存的作品。
• 顶部只保留原生菜单、项目入口及当前工具必要选项，无大标题、欢迎横幅或步骤说明墙。
• 左侧沿用 PhotoCraft 工具分组、快捷键、鼠标与键盘语义；不另造一套操作方式。
• 右侧固定协作面板，默认 Agent，可切换图层；调节宽度后记住。图层、属性、历史沿用原生编辑器。
• 右侧对话区独立滚动，用户气泡靠右、段落仍左对齐，Agent 回复与产出靠左；每轮只显示一个 Agent 标识。操作记录默认收起为摘要，点击展开该轮原始历史。
• 底部统一输入区使用独立边框、内边距和焦点反馈，输入文字超过三行后在框内滚动。对话与生图模型放在同一行的两个独立选单；选中内容仅以紧凑上下文显示。滑杆图标打开个人 Key 和连接设置；账户弹窗只负责素材库网页登录授权。保存与校验有加载、失败和成功反馈，不把已保存的 Key 回显到界面。
• 没有文档时直接进入“我的项目”，不另设欢迎页或草稿入口。项目以真实首屏缩略图、名称、草稿角标与本机／账户来源呈现，按更新时间排序；没有页面时显示待生成。可见行才请求封面，后台渲染并限制并发与缓存。
• 项目垃圾桶入口保持可见，确认时明确删除本机还是账户项目。本机移入所属账户回收区，账户删除复用现有鉴权、版本和任务保护；网络、版本冲突、正在执行和结果待核查分别显示原因。列表已知受保护时禁用删除并给出悬停原因；最终提交仍实时核对，不乐观移除。存在待核查任务时保留项目和请求记录。删除错误只出现在项目和确认区，不混入 Agent 对话。
• “我的项目／添加素材／画布”是互斥的中央目的地，切换不重建或清空原文档。返回画布时关闭浏览层；没有文档时回到我的项目。
• “我的项目／添加素材”等入口放在原生工具选项行右侧，不额外占用一整行；左侧工具参数可横向滚动。隐藏工具选项时保留最小可达入口。“添加素材”支持 SKU / SPU / 条码从素材库查询，图片预览后置入当前画布。目录与图片采用独立有界只读队列；缩略图最多两张在途。私有图片每次 GET 保持实时鉴权，预览不生成临时图片，置入及画布修改仍串行。
• 默认窗口 1440×900，验收 1280×800、1440×900、1920×1080 与 125% / 150% 缩放。最低 1100×720；窄窗口收起辅助面板，不把桌面客户端伪装成移动网页。

视觉与文案

• 直接复用 PhotoCraft 的主题 Tokens、原生按钮、菜单、标签页、图标与停靠行为。尺寸采用 4 / 8 / 12 / 16 / 24 的间距节奏。
• 主操作用蓝色，灰阶承载结构，错误与警告只用于真实异常；不添加装饰渐变、营销卡片、超大圆角或无意义动画。
• 界面文字优先采用正常可读的 12–14pt；正文与辅助文字达到 4.5:1 对比度。命中区域、焦点和快捷键可发现。
• 画布字体独立管理，中文基线 Noto Sans SC。界面主题和字号不改作品尺寸、字体或导出结果。
• 按钮写动作，如“打开”“置入”“发送”“接手”“撤销”。只在必须决策或失败恢复时解释；常态不展示实现细节、接口名或免责声明。
• 帮助说明放在悬停提示和按需展开区域；不可用操作明确说明缺少的条件，不伪造完成或可用状态。
• Agent 页签指示与 Key 展开使用 160ms 原生 cubic-out 状态过渡，发送悬停为 120ms；设置内提供“减少动态效果”，相关过渡直接切换。沿用 Rust / egui 动效，不引入 JavaScript GSAP 运行时；静态截图不作为动效帧率或系统辅助技术验收。
• Agent 快捷建议及操作记录展开入口使用紧凑图标胶囊，完整保留悬停、键盘焦点和按需展开行为；建议只填入草稿，用户明确发送才调用模型。
• 本客户端不展示原项目的社区、推广网站、GitHub 或向原项目报错的入口。帮助菜单保留系统信息及本客户端“关于”；必要开源署名、原始 NOTICE、MIT / Apache 许可和第三方素材来源集中放在“开源许可”。不改写作品内容、文件名或嵌入色彩配置中的真实来源信息。

Agent 协作约定

1. 用户点击发送或在输入框内按 Ctrl+Enter 后，以一行实际状态呈现回复或画布更新；实际模型只通过 98k 对外接口调用。回复按真实 SSE 增量显示，部分说明不执行命令，完整结束并校验后才应用编辑；不用完整结果的打字动画模拟流式。预检查失败保留输入草稿。
2. 编辑建议绑定当前文档、图层和修订号。只允许已实现、已校验的画布命令，拒绝终端、脚本、任意本机文件和任意网络地址。
3. 操作逐步进入当前画布，每一步重新绘制并列出实际结果。不能只展示动画或最终截图。
4. 用户点击“接手”、切换文档、修改图层或执行撤销后，停止剩余自动编辑。旧建议不会覆盖新修改；继续前重新核对上下文。
5. Agent 与用户共用引擎的撤销、重做历史。撤销一步不影响此前无关人工操作；已经成功的步骤不因后续失败而被当作未执行。
6. 模型派发前保存请求身份；超时、断线、退出后的结果未知保持 unknown，只按原请求只读核查，绝不自动重发。接手画布不代表上游模型已取消。 重启核查先暂存到原项目，打开时核对账号、原任务、屏幕、方案和当前画布版本。只恢复未编辑的目标屏；其他屏的人工修改与图层身份必须保留。后台结果不切换当前项目，重复启动不重复插图；等待原结果不能阻塞本机保存。
7. 本地草稿、账户同步、工程文件和导出各有独立状态。任何联网失败都保留已保存的本机作品与输入草稿。
8. 实际生成结果在所属对话轮次中展示等比缩略图，点击打开默认居中的原生图片预览；只读本人项目任务内校验通过的产出，不接受任意本机路径或用占位图冒充结果。

账户、素材与资源边界

• 复用 /api/desktop 的网页登录授权、PKCE、本人项目及素材目录契约；密码和访问令牌不进入模型上下文、对话、工程包或日志。
• 正式验收前联网功能继续仅有效超级管理员使用；每次调用前重验账户、权限和模型开放政策，不信任界面缓存。
• 不读取 98k 的源码、数据库或服务器。每个素材库账户使用自己的 98k Key，只存本机操作系统凭据库；不打包或分发公司共用 Key。更换素材库账户后不共享模型连接。对话与生图分别保存选择，保留原有个人 Key 时切换模型不用重填。
• 模型选项复用线上现有的只读目录，对话用 agent-models、生图用 models.modelOptions.image。保存前与个人 Key 的公开 /v1/models 核对，不根据模型名称猜测用途；选择配置与原生生图执行分开验收。
• 输入区保留紧凑的“对话／生图”，不展示三个含糊任务的下拉选单。只有真实选中可替换图片时出现“替换选中图”；沿用原生生图与单屏替换能力，保持图框和独立文字层。没有自动模型路由实现时不声称已由 Agent 自动判断生图。生成过程用单行状态，接手后的结果待明确应用，进入同一份撤销历史。
• 品牌、品类在产品资料中一次选择，Agent 不重复询问。素材联动仅精确映射目录中的明确品类；旧资料缺品类保持空值，不能按近似名称套模板。项目按品牌和品类自动绑定已就绪规则；没有对应模板时显示待配置，不借用其他品类。
• 规则及模板模块目录由生产服务提供，首次下载后在所属账户本机缓存，使用内容 SHA 校验；后续先读本机，每五分钟在使用时后台检查一次。联网接口包括 304 响应之前均实时校验权限。已有项目使用固定快照，新版缓存不自动改写旧方案；延迟回包不能覆盖未保存输入。当前缓存范围是规则与模块元数据，完整 PSD、人物与参考图片资源包需另行接入和验收。
• 画布、图片处理、预览和导出在用户设备上执行。平台负责鉴权、目录、知识、私有文件传输与项目服务；不宣称平台没有资源开销。
• 以本机工程为主要工作副本：.pcraft、工作素材缓存、撤销历史与生成任务日志留在用户设备；个人 Key 的模型请求由客户端直连 98k。生产机不承担客户端的画布合成、PSD 导出或自动重跑任务。
• 服务端保留项目索引、权限、品牌／模板快照版本和必要的任务摘要（请求号、状态、所属项目与版本）；完成后接收成果。为跨设备与本机故障恢复保留可选工程备份及版本同步，不能只上传一张最终图片。
• 大文件传输按需、增量、流式进行，避免一次在生产机展开整份工程或解码长图；后续可评估授权直连对象存储。原生工程云备份、版本同步及跨设备恢复的定向验收见客户端与 Web 收尾记录；增量及对象存储直传仍需单独验证。
• 默认宽度 1440px，兼容 750px；最多 12 屏、总高 30000px。缩放只影响显示，不改变真实坐标。大图逐份加载、任务受控并发。

验收与完成口径

• 必须用实际编译的原生客户端检查，不以网页模型图、模拟数据或原版编辑器的通过记录代替二开验收。
• 覆盖：首次空态、加载、登录、撤权、项目列表与恢复、素材查询及置入、Agent 实际调用、逐步编辑、人工接手、共享撤销、重启后草稿和未知请求恢复。
• 用现有顾家 1440px 五屏样张回归中文排版、图片位置、保存恢复及分层 PSD；Photoshop 实际编辑另行验收，缺少环境时如实记录。
• 原生界面按 Impeccable critique / audit 检查布局、对比度、焦点、文案、溢出和反馈，保留实际窗口截图。
• 本次 Agent 停靠面板的局部 ship 裁定、真实流式调用与截图矩阵见 Agent 面板验收；不据此扩大为所有模型、系统辅助技术或完整客户端验收完成。
• 后续项目首页、删除、双模型及导航验收见 本轮记录，独立审查按对应截图和实际范围记录。
• 每次提交与发布以该次验收记录为准；设计标准不代表所有能力均已交付。同事表格的输入、输出和现有实现差距见流程对照。