docs/pi-frontend-uiux-guidelines-zh.md
状态：当前 Pi 前端的评审基线 适用范围：供应商、提示词、Skills、Sessions，以及以后考虑接入的 Pi 原生设置 最后更新：2026-08-05
这份文档面向 cc-switch 的设计者、开发者和评审者。它不是功能清单，也不是用户手册。新增 Pi 界面或字段时，应先用本文判断该能力是否该由 cc-switch 提供，再讨论具体组件。
文中的“必须”是合并前要求；“应该”允许有明确理由的例外；“不得”表示当前产品边界。
Pi 界面必须同时满足两类用户：
“简单”指默认路径短、入口少、术语清楚，不是删除必要能力。普通字段直接展示，少用解释文字；只有在不解释就可能误用、丢数据或改变 Pi 行为时才保留提示。
稳定性优先于覆盖所有边界。P0、P1 问题必须解决；罕见且低影响的 P2 可以记录后延期。不要为了单条评审意见叠加新的影子状态、特殊分支或一次性组件。
Pi 不建立独立设计系统。交互参考顺序如下：
应该复用现有的 ProviderPresetSelector、BasicFormFields、ApiKeySection、EndpointField、RequestHeadersEditor、JsonEditor、供应商卡片、图标、分类与合作伙伴排序。只有 Pi 原生语义无法用现有组件表达时，才增加 Pi 专用组件。
同一种信息在不同应用中应使用相同的层级、字号、间距和操作位置。Pi 可以有不同的数据语义，不能因此出现一套完全不同的布局。
所有认证、模型、文件路径、加载顺序和传输行为，必须由开发时最新 Pi 或 request capture 验证。源码阅读和经验判断只能用于提出假设，不能作为产品状态的依据。实现取舍见 Pi 原生契约与实现边界。
前端必须遵守以下规则：
exists = active，不得再增加一个 enabled 字段。models.json 时，涉及 Pi 供应商成员关系的写操作必须失败关闭。无法读取全局默认项时不阻止成员关系操作。供应商页面采用统一结构：
供应商卡片不展示模型列表。模型只在添加或编辑表单中配置，避免卡片高度失控和信息重复。
列表中的常规操作沿用家族组件：
供应商标识是成员身份。Pi models.json 中存在该标识即表示已启用，不再比较整份 JSON 来制造“漂移”或“所有权”状态。凡是显式存在于 models.json.providers 的供应商都应同步到供应商列表，包括与 Pi 内置供应商同名的 ID；原生修改同步回已保存档案，原生移除只改变启用状态。只存在于 auth.json、/login 或环境变量中的认证状态始终由 Pi 管理，不生成 CC Switch 卡片。详细规则见 Pi 显式供应商同步需求。
CC Switch 不设置、展示或标记 Pi 的当前供应商和模型。
/model。defaultProvider 或 defaultModel；失效引用及后续选择由 Pi 原生逻辑和 /model 管理。models.json 状态未知时，启用、移除和删除操作应禁用。全局默认项读取失败时不显示条件提醒，也不阻止供应商成员关系操作。不得用“列表第一个模型”推导默认模型，也不得在保存供应商时偷偷修改 Pi 默认选择。
项目级 .pi/settings.json 依赖启动 Pi 时的工作目录，供应商页没有权威项目上下文，不扫描目录或猜测活动会话。因此条件提醒只基于全局默认项；项目级选择仍由对应 Pi 会话管理。
添加流程的心智模型是：
选择预设或自定义配置 → 填写凭证与请求信息 → 配置模型 → 保存
具体要求：
1、2、3 编号步骤，不增加向导专属页面。piProviderPresets 是独立维护的 Pi 原生预设目录。可以参考其他应用的供应商知识，但不得在运行时导入或派生另一个应用的预设；Pi 的协议、请求根地址和模型能力必须在自己的目录中明确表达。供应商级字段分为三类：
| 字段 | 前端处理 | 原因 |
|---|---|---|
| 供应商标识 | 自定义创建时显示，编辑时锁定 | Pi models.json 的稳定键 |
| 显示名称 | 直接展示 | 列表识别所必需 |
| 备注、官网链接 | 直接展示 | cc-switch 家族元数据 |
| API Key | 直接展示 | API Key 供应商的核心凭证 |
请求地址 baseUrl | 直接展示 | 自定义供应商通常必填 |
接口格式 api | 直接展示 | 决定 Pi 调用的原生协议 |
模型 models | 直接展示 | 新建自定义供应商必须声明；已有显式内置节点可为空 |
请求头 headers | 直接展示，复用家族请求头编辑器 | 常见兼容需求，且是 Pi 原生字段 |
| 配置 JSON | 可编辑、默认展开，与结构化字段双向同步 | 与 Claude Code、Codex 等应用的配置编辑行为一致 |
接口兼容性 compat | 直接展示键值编辑器 | Pi 当前稳定支持的供应商级兼容选项 |
oauth、authHeader、modelOverrides 等罕见字段 | 不做结构化入口，原样透传 | 不属于普通创建路径 |
接口格式默认使用 OpenAI Chat Completions。可选项来自 Pi 已验证支持的协议：
创建时不提供“自定义接口格式”。编辑已有未知格式时，应显示并保留该值，不能因为下拉列表不认识就覆盖。
请求地址的示例沿用家族写法 https://api.example.com/v1。占位文字只作格式示例，不推导实际路径。
接口兼容性与模型配置采用相同的信息层级，不使用折叠箭头。默认只显示说明和“添加”按钮；点击后，键值行直接向下追加。未配置时不向 Pi JSON 写入空的 compat。
一个供应商拥有多个模型。供应商级请求地址和接口格式是默认值，不为每个模型重复创建“模型 API”和“模型基础地址”字段。
模型行默认只显示：
选择或填写模型 ID 后，仅在显示名称仍为空时同步模型 ID。预设供应商已经填好模型能力；自定义供应商不根据模型 ID 猜测能力。展开区只放 Pi 原生且常用的能力：
reasoninginputcontextWindowmaxTokensthinkingLevelMap自定义模型默认关闭扩展思考并使用文本输入；上下文长度和最大输出 Token 必须由用户填写正数后才能保存。后台不得根据已知名称、模型前缀、相似版本、URL 或外部目录自动写入能力，也不显示“自动值”“已覆盖自动值”或“恢复自动值”。
thinkingLevelMap 排在上下文长度和最大输出 Token 之后，作为最后一项模型能力提供渐进式编辑。它默认折叠并保持整行宽度、左侧对齐；展开后用七行轻量列表直接展示字符串、Pi 默认和不可用三种状态，点击某一行才在表单中部打开该档位的编辑浮层。关闭“支持扩展思考”时整段隐藏，但不删除已有映射。
所有推理预设模型都显式提供 thinkingLevelMap；已确认的接口组合写入对应映射，其余预设使用 {} 明确沿用 Pi 默认行为。自定义模型不自动生成映射，用户可以手动配置。模型级 api、baseUrl、cost 等少见字段不做结构化入口，但编辑保存必须保留。
请求头使用 Pi 原生 headers，不得增加“请求头身份”“Claude Code”“Codex”等模板选择器，也不得自动把 API Key 塞进某个 Header。
名称统一使用“配置 JSON”，不使用“配置 JSON 预览”。
配置 JSON 默认展开并允许编辑，复用共享 JSON 编辑器的语法校验和格式化操作。结构化字段只改写自己负责的键；合法 JSON 会回填结构化字段。输入暂时不合法时保留原始草稿，不用旧结构化状态覆盖，保存前必须完成校验。
配置编辑器需要显示用户正在编辑的真实值。API Key、Authorization、Token、Secret、Password 等敏感值不得出现在编辑器以外的日志、toast、列表或测试输出中。
原配置缺少可选字段时，用户未主动修改就应保持缺失。例如根级 api 不存在时，界面可以显示默认协议帮助理解，但保存不能自动补写该字段。
Pi 原生订阅登录和 OAuth 由 Pi 管理：
/login。auth.json，不保存或刷新 OAuth Token。界面不得出现“CC Switch 显示已登录，但 Pi 仍使用旧凭证或旧请求路径”的半状态。
Pi 前端不提供路由、网关和故障转移：
gatewayStatus。allowGateway 等能力字段。后端不得为 Pi 建立路由投影、网关状态或故障转移配置。通用代理基建遇到 Pi 时应明确跳过。
Pi 提示词沿用 cc-switch 的列表、标签页、全屏编辑器和顶部主操作，不创建侧边栏专用设计。页面使用三个标签：
AGENTS.md。APPEND_SYSTEM.md 和 SYSTEM.md。全局提示同一时间只允许一项与 AGENTS.md 精确匹配。原生文件与提示库内容不一致时，显示“外部 AGENTS.md”，不得假装某个数据库选项仍在使用。编辑或停用旧选项不能覆盖外部内容；用户明确选择另一项时，先把非空的外部内容保存进提示库，再写入所选项。
APPEND_SYSTEM.md 是普通用户的推荐入口。SYSTEM.md 会完整替换系统提示，创建前必须明确警告。文件存在就是生效，不增加启用开关。
APPEND_SYSTEM.md、SYSTEM.md 与提示词模板复用全局提示的全屏编辑表单。内容区只使用应用统一的外边距，不增加固定最大宽度；编辑器随窗口宽度伸缩。
顶部“+”根据当前标签执行对应的添加动作；系统提示标签直接编辑两个固定文件，不显示无意义的添加按钮。
提示文字只保留以下情况：
APPEND_SYSTEM.md 与 SYSTEM.md。不要在页面上重复显示操作完成后 toast 已经说明的内容。
Pi Skills 复用统一 Skills 页面和已有卡片。是否被 Pi 发现必须来自原生目录检查，不读取通用 skill.apps.pi 作为第二状态源。
不要在所有 Skill 卡片上无条件显示“Pi：未启用”。Pi 状态只在 Pi 上下文或确实需要解释发现结果时出现。
Pi Sessions 复用现有会话管理器。相对 session 目录缺少项目上下文时，应说明需要项目目录；目录不可用时显示错误。不要制造 CC Switch 专用的 Pi 会话格式。
Pi Packages、Extensions 与 Themes 由 Pi 原生管理，当前不进入 CC Switch 产品界面。CC Switch 不复制扩展文件，也不维护第二套安装、启用或更新状态。
固定术语如下：
| 使用 | 不使用 |
|---|---|
| 请求地址 | 供应商 API、供应商基础地址 |
| 接口格式 | 自定义接口格式（作为重复标题） |
| 模型配置 | 默认模型配置、模型 API |
| 请求头 | 请求头身份 |
| 配置 JSON | 配置 JSON 预览 |
| 启用、移除 | 切换、设为默认 |
普通字段 Label、模型配置标题和请求头标题使用同一视觉等级。当前实现基准为 14px / 400 / 20px。不要仅把某一组字段加粗，造成虚假的一级分区。
按钮、图标、圆角、边框和 hover 状态使用现有设计令牌。交互动画保持 150–300ms，并支持 prefers-reduced-motion。深色和浅色主题都必须保证文字、边框和禁用状态可辨认。
每个输入都有可关联的 Label。图标按钮需要可访问名称。动态错误使用 role="alert" 或合适的 live region。键盘操作不能丢失尚未提交的输入。
计划新增任何 Pi 设置时，依次回答：
/login、/model 等原生命令？四项都满足才进入默认界面。Pi 原生但罕见的字段优先透传；需要专业用户偶尔修改的字段可以进入渐进区域；不属于 CC Switch 或缺少可靠后端支持的能力不进入 UI。
参考 OpenCode 或 Hermes 时只复用相同问题的成熟交互。不能因为另一个应用有某个字段，就假设 Pi 也需要。
功能验收至少覆盖：
/model、/login 的所有权没有被 CC Switch 接管。真实联调应使用已安装的 Pi，验证添加、启用、移除、编辑、模型获取、请求发送和 Pi 原生命令后的状态同步。协议与能力结论必须保留 oracle 或 request-capture 证据。