06. 设置信息架构

翻译说明： 本页是与 英文源规格 一一对应的机器辅助翻译。代码、协议字段和标识符保持原文；如翻译与英文源事实有歧义，以英文版本为准。

1. 设置根目录（Codex 全页 shell）

设置是一个全窗口页面，取代了应用程序侧边栏+主镶边（Codex 电子行为）：

• 切换到不同的设置分类时，内容区回到顶部，包括插件提供的分类。再次点击 当前分类或在当前页更新设置时，保留滚动位置。通过全局搜索跳转时，会离开 当前打开的插件分类，并在绘制前定位到目标设置项。清除已消费的搜索锚点 不会再次重置滚动位置。
• 左侧设置导航宽 275px，与主侧栏共享 sidebar-surface 材质：macOS 使用原生 vibrancy 加相同 tint/sheen，Windows/Linux 使用不透明 --ds-bg-sidebar，并共享可选背景图。 macOS 下设置外壳透明，右侧内容区与顶部条仍不透明。只有内容区内部的入场包装播放路由入场（仅透明度，不位移）， 滚动容器、导航背景本身不淡入、不位移。设置弹框和抽屉挂到文档根上的 #pi-desktop-overlays，遮罩覆盖整窗含导轨。
• 返回应用直接恢复原来的侧栏折叠/展开状态，不播放入场动画或从零宽度展开。 可见主界面中的真实开关和自动折叠/恢复仍播放动画；首次显示和路由恢复不触发。
• 导轨顶部：交通灯区域和**搜索设置...**药丸
• 返回应用程序（返回应用）固定在导轨底部而不是顶部：保留箭头+文字形式，作为 32px 控件与主外壳侧边栏底部图标行（设置/插件/通知）处于同一条水平带上， 因此全页接管打开或关闭时该操作不会上下跳动。窗口过矮时其上方的目录滚动， 固定底部的操作因此不会遮住任何一行
• 横跨导轨和内容窗格的 46px 顶部带是一个原生窗口 拖动区域；交互式控件仍然明确不可拖动
• 带有图标和简洁平行标签的紧凑导航目录，按以下顺序。一个目的地只负责一个 主题（D684 / ADR 0345）：目的地绝不是「其他地方放不下的设置」的落脚处； 不属于任何目的地的主题说明缺少一个目的地，而不是应该在无关页面上多加一张卡：
  1. 外观 — Lucide Palette（主题、语言、字体、界面元素）
  2. 对话 — Lucide MessageSquare（转录呈现与输入框）
  3. 快捷键 — Lucide Keyboard（键盘快捷键）
  4. 语音 — Lucide Mic（实时语音开关与服务绑定）
  5. 行为 — Lucide SlidersHorizontal（会话默认、执行、电脑操作）
  6. 模型 — Lucide Bot（提供商和默认模型）
  7. 指令 — Lucide FileText（全局和项目指令文件）
  8. 技能 — Lucide BookOpen（可复用的智能体指令）
  9. MCP — Lucide Server（智能体连接）
  10. 子智能体 — Lucide Sparkles（内置与自建的并行工作智能体）
  11. 项目 — Lucide Archive（持久项目索引）
  12. 系统 — Lucide Monitor（网络、存储、电源、窗口关闭行为）
  13. 云同步 — Lucide CloudDownload（加密的可移植配置备份与双向同步；实验性，所有构建可见）
  14. 远程主机 — Lucide Globe（SSH 引导与配对清单；实验性，所有构建可见）
  15. 信息 — Lucide Info（版本、日志、更新、开发人员） 导轨图标具有装饰性（通过 SVG 默认设置为 aria-hidden）并与标签保持单色； 只有选中行的字形取强调色，与该行的强调色底片一起出现。不要在此处重复 使用 refresh/rotate 字形。两个目的地不得共用同一字形：模型保留 Bot， 子智能体接手已退役的 AI 目的地释放出的 Sparkles。
• general 与 ai 两个目的地已退役。它们的 id 仍可解析——general → 外观、 ai → 行为——这样已保存的选择、原生菜单项或拆分之前写下的链接都会落到真实 页面，而不是空白内容区；两个 id 都不出现在目录和搜索结果里。
• 目录仍是保持相同顺序的可搜索扁平列表。为便于扫描，目的地分为四个带标题 的视觉分组：“偏好”（外观、对话、快捷键、语音）、“智能体”（行为、模型、 指令、技能、MCP、子智能体）、“工作区”（项目）和“系统”（系统、云同步、 远程主机、信息；云同步和远程主机均为所有构建可见的实验性目的地）。标题 使用柔和的非交互文字，取最小可读字号并加字距，分组之间只使用留白，不绘制 分割线；搜索过滤后，空分组及其标题一并隐藏。
• 每个目的地都以页头开场：导轨字形以页面尺度重复出现在强调色底片上、页面 标题，以及——对于内容本身没有开场描述的目的地——一行说明该目的地负责什么。 能力页、模型页和项目页保留各自的开场描述、不带副标题，因此同一页不会把用途 说两遍。
• 云同步是所有构建均可用的实验性「系统」目的地：导轨行、页面和设置搜索命中 在开发版与打包版中都存在，导轨行和页面标题均带有实验性徽章 （settings.configSync.experimental）。开发者模式不影响可见性，同步行为本身不变。
• 远程主机是所有构建均可用的实验性目的地：导轨行、页面和设置搜索命中在开发版与 打包版中都存在，且不受 AppSettings.developerMode 影响。该行和页面标题均带有 实验性徽章（settings.remoteHosts.experimental）。
• 不显示其他设置目的地或占位符导航行
• 主表面上的主要内容窗格，带有大部分标题+升高 圆形的行卡。其内容使用后可用的完整宽度 固定导轨和窗格排水沟，并随着窗口不断调整大小。

2. 章节内容

外观

产品的观感以及对话周围的界面元素，共四张卡：界面、侧边栏、轮盘 右键菜单、启动。这里的任何设置都不改变智能体的行为；这一页过去附带的 机器层面的卡——网络、存储、电源、关闭行为——自 D684 起归系统。

• 界面卡：
  • 主题：可搜索的选择行（与语言相同的锚定菜单）。关闭时的触发器按当前文案收缩，不超过设置控件列，并显示当前名称。菜单把系统、浅色、深色钉在顶部，插件主题在分隔线之后列出，并带「由…提供」提示。搜索匹配名称、描述、id 和插件 id。选择更新 settings.theme。 With System selected, OS appearance changes refresh the resolved plugin palette and open Browser chrome without another settings write or restart. Explicit light/dark and registered plugin palettes remain fixed.
  • 语言：可搜索的选择行（不是卡片网格）。关闭时的触发器按当前文案收缩，不超过设置控件列，显示当前语言的本地名称，或「跟随系统」。菜单把「跟随系统」钉在顶部并内嵌显示检测到的语言（例如「当前：简体中文」），然后按本地名称（永不翻译的 endonym）和英文名称列出每个已发布语言，供搜索和排序。选择更新 settings.language。新增语言只需加一份目录和一行注册表；选择器不硬编码选项列表。
  • 字体：可搜索的选择行（触发器以该字体的字样显示当前字体） 提供「跟随系统」以及由 Electron 主进程枚举的系统已安装字体； 应用不再自带任何字体（ADR 0298），因此没有内置分组、也没有许可证角标， 此前保存的指向已移除字体的字体栈仍显示在「已保存」分组； 选择结果持久化为 AppSettings.fontFamily， 无需重载即可应用到全局界面字体栈（--font-sans）； 每个字体栈以纯系统 CJK 回退层收尾（PingFang SC、Hiragino Sans GB、 Microsoft YaHei、sans-serif）
  • 字体大小：星巴克式杯型档位（中杯 / 大杯 / 超大杯 / 超超大杯）加上百分比滑杆（80%–150%）。杯型标签单行显示、不换行。 选择持久化为 AppSettings.fontScale（1 = 产品字号阶；缺失表示 1）。 渲染器在根元素设置 --font-scale，全部 --text-* 阶和共享 Lucide 图标 按比例缩放，无需重载。窗口放大/缩小/重置仍独立。界面不出现 px 输入 （D343 / ADR 0180）
  • 自动语言检测通过主进程解析操作系统区域设置 (app.getLocale()) 而不是渲染器的 navigator.language，并且 「跟随系统」选项内嵌显示检测到的语言（例如“当前：简体中文”）
  • 本机选择触发器及其打开的选项列表使用活动主题的 macOS、Windows 和 Linux 上的可读 foreground/background 配对；的 共享的本机选择契约适用于每个应用程序表面
• 侧边栏卡片：一个项目运行活动总开关 (AppSettings.sidebarRunningIndicators) 与独立的数量徽标和活动流光开关 (sidebarRunningBadge、sidebarRunningRail)。未设置时总开关和数量徽标默认开启，活动流光默认关闭； 已保存的值优先生效。两个受管辖的开关以缩进子行呈现，因此依赖关系无需用一句话 解释。总开关关闭时它们置灰并保留各自已保存的选项，重新开启后恢复原选择。 提示样式见 01-ui-ia.md §3.2。
• 轮盘右键菜单卡：一个开关（在对话背景上启用）和四个方向选择器（上、 右、下、左）。AppSettings.radialMenu.enabled 缺省或为假时开关关闭， 保持原来的纵向背景菜单。每个方向保存一个 RadialMenuAction。开关关闭时选择器 置灰并保留已设方向。设置搜索索引该卡及其各行。
• 启动卡 — 启动动画（D679 / ADR 0338）：一个总开关，外加受其管辖的就绪后提前结束 子开关。动画本身是文件而不是取值，因此该行的另一项职责是让文件夹可被找到：它的 详情行说明下次启动将播放哪个视频（或提示未找到），并带上打开 <dataDir>/startup/ 的动作（必要时顺手创建）。两个偏好都持久化在 AppSettings.startupAnimation 下（enabled 缺省为开，所以放进文件即可； skipWhenReady 缺省会把视频播完），并且在创建主窗口之前读取，因此与毛玻璃开关 一样在下次启动生效。状态每次打开都重新扫描，因为刚放进文件的用户还没重启。

系统

关乎这台安装而不是产品观感或智能体行为：网络、存储、电源，以及 Windows/Linux 上的关闭行为。平台相关的关闭行为放在这里，因为它改变的是 应用程序窗口行为，而不是智能体行为。

• 电源卡：两个独立且默认关闭的开关。「保持电脑唤醒」使用 prevent-app-suspension，桌面应用运行期间阻止系统因空闲休眠，包括定时任务 等待下一次触发时；屏幕仍可关闭。「阻止屏幕休眠」使用 prevent-display-sleep 保持屏幕常亮。两项分别持久化为 AppSettings.keepAwakeWhileRunning 和 AppSettings.preventScreenSleep， 切换立即生效、启动时恢复，关闭对应开关或退出应用时分别释放阻止器。 手动睡眠和合盖遵循系统设置。
• 存储卡显示生效的应用数据目录与可回收缓存大小，并被设置搜索索引；选择目录 走原生选择器，确认框列出来源路径、目标、迁移范围与重启/备份策略，取消没有副作用。 清理缓存与删除旧备份各自需要就地确认。
• 网络卡：
  • 代理：分段控件 — 系统 / 直连 / 自定义。默认是系统（Chromium 跟随操作系统代理）。直连禁用代理。自定义将一个 HTTP、HTTPS 或 SOCKS5 URL 应用到应用自有出站请求（模型调用、扩展市场、更新、模型目录、插件 net.fetch、内置浏览器）。工作区 Bash 和 OAuth 用的系统浏览器不会被改写。
  • 自定义显示代理 URL（含 user:pass@）、默认 localhost,127.0.0.1,::1,<local>,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16 的绕过列表（本机、本地模型与所有局域网服务直连，不被代理吞掉），以及一次走该代理的测试。带认证的 URL 通过回环 SOCKS5 中继交给 Chromium（issue #490）。选择持久化为可选 AppSettings.networkProxy；系统/直连模式下同样保留用户填写的 url 与 bypass（只有 mode 决定谁生效），因此再次选择自定义会恢复它们而不是内置的 socks5://127.0.0.1:1080（issue #1541）。无协议/存储版本升级（D340 / ADR 0177）。
  • 网络宽松模式：一个开关，持久化为 AppSettings.networkPolicy.mode（relaxed | strict），默认开启。开启时，你自己填写的端点（模型服务、MCP 服务器、git 远端）可以是回环或局域网地址、可以使用明文 http，并容忍透明代理的 fake-IP 答案；关闭则回到"只允许公网 https"。首次用明文访问这类端点时会弹一次告知。它取代的三个旧确认开关（networkProxy.allowFakeIp、configSync.allowInsecureHttp、以及自填明文开关）都已删除（ADR 0304）。
• 关闭行为卡，仅 Windows/Linux：窗口关闭按钮的行为。
• 文件打开目标、菜单栏行为和底部面板行为不是 渲染直到其主机支持的设置模式和运行时效果存在。

对话（chat 选项卡）

转录如何呈现、输入框如何接收输入。两张卡：显示，然后输入与链接。 这一页的任何设置都不改变模型做什么或被允许做什么；显示卡用一行副标题说明 这一点，各行无需重复。

• 显示卡，按渲染顺序：显示思考开关及其自动折叠已完成思考子行、 过程显示分段控件及其自动折叠已结束活动组子行、上下文用量显示 （剩余或已用）、平滑流式、内联可视化。上下文用量显示控制输入框 工具栏上下文环及其弹层是以剩余容量还是已用容量为引导数值；默认为剩余。
• 输入与链接卡：回车发送控制、大段文本粘贴阈值、链接打开目标。 阈值决定纯文本粘贴何时转为会话临时文件，默认值为 600 个字符，接受 1 至 1,000,000 的整数。链接打开目标默认使用工作面板浏览器，可将对话、会话记录 和插件页的 HTTP(S) 点击路由到系统浏览器。插件/设置页若目标是工作面板， 会先回到对话再打开（不记入导航栈），避免被遮罩挡住；没有会话时才回退到 系统浏览器。工作区 HTML 预览、BrowserPreview、OAuth 和问题反馈仍走原有目标。

智能体行为（behavior 选项卡）

新对话以什么设置开始，以及智能体运行时可以做什么。卡片顺序是 会话默认 → 执行 → 电脑操作。

• 会话默认卡：主机支持的默认运行模式（Agent / Plan / Goal）、决定智能体 自主程度的全局权限模式（询问/接受编辑/自动），以及命令 Shell 选择。三者同卡， 因为它们是同一个问题的三种问法：一次运行从什么开始。权限控件是共享锚定菜单 表面上的菜单选择器，而不是由平台绘制的 <select> 弹层，因此设置里的每个 选择器都以相同方式展开。关闭时的触发器按当前文案收缩，不超过设置控件列。
• Goal 预算行位于会话默认卡的默认模式之下：两个数字框（轮数、Token）， 持久化为可选 AppSettings.goalBudget { maxTurns, maxTokens }。失焦或回车即 保存；留空为不限，超出范围（轮数 1–10000，Token 至少 1000）时恢复为已保存值。 缺失时沿用内置 Goal 预算（20 轮，Token 不限）。只影响新的 Goal 运行；已打开的 运行在其状态栏中编辑。
• 执行卡：无尽重试开关与应用级定时任务开关。无尽重试默认关闭；开启后 网络/临时提供商故障会持续重试到成功，但停止按钮仍可取消回合，开启期间可能 持续消耗 API 用量。定时任务开关持久化为可选 AppSettings.scheduledTasksEnabled， 缺失或为真时开启；关闭会隐藏底部时钟与全局搜索入口、离开已打开的路由、不再 提供定时类 Agent 工具，并在宿主侧阻止新的手动/自动运行与任务编辑，已有任务的 启用状态、排程与历史不变，进行中的运行可以跑完。
• 电脑操作卡：页面最后一张卡。它不渲染卡/行解释文案与静态范围提示；控件、 平台与权限状态、错误和缺少模型的提示保持不变。
• 输入框文本操作由用户主动安装的插件提供；仅当插件已启用并获得 composer.transform 权限时才会显示。宿主不包含提示词增强设置卡，也不会默认安装独立的 pi.prompt-enhancement 插件。插件设置在「插件」页编辑；旧提示词增强偏好的单次迁移见 04-ux/12-prompt-enhancement.md。
• 显示思考是一个开关，以可选的 showThinking 布尔值持久化到宿主设置。关闭时 隐藏已完成的推理行；仅在推理正在流式输出时保留整段运行的 TextShimmer Thinking 指示器，收起的行只显示该指示器，不显示摘录。已存推理仍会保留，重新打开时重新出现。 开启时，平铺显示与命令工具优先中的思考行默认展开，全折叠显示保留已发布的仅活动行 自动展开例外。它只影响展示，不改变模型推理配置，也不控制回合过程或活动组的折叠： 无论开关如何，运行中的过程默认展开，未操作的已完成过程默认收起。旧版 thinkingDisplayMode 字段（detailed / compact）仅为持久化设置兼容性保留， 不再在界面暴露；缺失或未知值显示推理，显式 compact 隐藏推理。设置搜索会索引 该行。
• 过程显示是显示思考之后紧邻的分段控件，以可选的 transcriptDisplayMode 字段持久化为 flat、command-first 或 fully-folded，标签为「平铺显示」 「命令工具优先」「全折叠显示」；缺失或未知值解析为「全折叠显示」，即 v0.20.0 发布的布局。「平铺显示」只渲染一个外层过程披露，不包含嵌套活动组。「命令工具优先」 保留活动组，但把 Bash／run 行提升为独立行；普通助手进度消息或命令都会结束当前组。 「全折叠显示」让命令留在所属组内，只有普通进度文字会拆分活动组。三者都只渲染一个 过程披露，只改变展示，并在渲染时读取，因此切换后立即重绘转录。已弃用的 keepCommandsExpanded 布尔值不再暴露，也不再参与渲染读取。设置搜索会索引该行。
• 环形右键菜单是外观页中侧边栏卡之后的一张卡，包含一个开关（在对话空白处启用） 和四个方向选择器（上、右、下、左）。AppSettings.radialMenu.enabled 缺失或为 false 时开关关闭，保留纵向的背景菜单。每个选择器保存一个 RadialMenuAction：复制整段对话、全选对话文本、复制最后一条回复、跳到顶部、 回到最新、打开内置浏览器、切换工作面板、打开项目文件夹，或留空。工作面板方向跟随面板状态： 收起时显示「打开工作面板」，打开时显示「关闭工作面板」。开关关闭时选择器禁用，但保留已存的方向，重新开启时继续使用。 设置搜索会索引该卡及其各行。
• 以上显示思考、过程显示及其两个自动折叠子行都属于对话 → 显示卡； 输入框文本操作属于对话 → 输入与链接。它们在此集中描述是为了把细则放在 一处，不表示它们渲染在智能体行为页上。
• 语音绑定（AppSettings.speech）不属于设置页面（ADR 0291）。宿主仍保留语音能力与 speech/* IPC，供插件和已存绑定使用；这里不再提供转写/朗读的服务、协议、模型或音色 选择，设置搜索也不再索引语音相关键。
• 会话默认卡中的命令 Shell行：主机发现的本机 PowerShell 5.1、PowerShell 7、 cmd、Git Bash 和 ID 为 windows-powershell、windows-pwsh、cmd、git-bash 的 Bash 和 bash（如果支持）。选定的 defaultCommandShell 持续存在 重新启动；写入拒绝不可用或错误的平台 ID。如果一个坚持 选择稍后变得不可用，使用第一个可用的平台 shell 并显示回退状态。选定的 Shell 可用时，选择器就是唯一的配置状态提示； 只有默认、回退和没有实际可用 Shell 时才显示状态文案。Bash 回合验证其固定的 ID/dialect 后再执行。该行渲染与同卡权限模式和外观选择器相同的菜单选择器。
• 上下文管理无卡且无控件（D200 / ADR 0061，由 D203 / ADR 0064）。自动保护始终开启，其预算和 保留限制源自活动模型的窗口，因此有 用户不能从这里调整任何东西——参考实现不能 也暴露这些值。设置搜索索引没有压缩键。 手动 /compact 在空闲状态下仍然可以从命令面板中使用 会话；记录显示每次压缩发生的位置以及上下文 使用检查器显示是否安装了检查点。

Token 用量不是设置目的地（D335 / ADR 0173）。已完成回合历史仍由宿主 持久化（session.endTurn.usage、stats.getTokenUsageHistory）。面向用户的 仪表盘是市场插件 pi.token-insights，从命令面板打开（usage、用量）。 设置搜索不索引用量页。

快捷方式（shortcuts 选项卡）

• 键盘快捷键卡：
  • 列出来自一个共享快捷方式地图的导航、代理和窗口操作
  • 渲染平台本机修饰符标签（⌘ 位于 macOS 上，Ctrl 位于 Windows/Linux) 和平台特定的全屏默认值
  • 单击绑定记录下一个修饰和弦或 F1–F12；Escape 取消录制
  • 每个绑定都可以明确设为“未绑定”；该状态仍可编辑，且不同于恢复默认值
  • 重复的应用程序绑定和 operating-system/editor-reserved 和弦 会以内联错误拒绝；未绑定的操作不参与冲突检查
  • 每个覆盖都可以独立恢复，并且所有覆盖都可以一起恢复；单项恢复时若默认组合 已被其他操作占用，则保留两项绑定并显示同样的冲突错误
  • 覆盖持续存在于可选的 AppSettings.keybindings 中：缺少属性使用平台默认值， 合法字符串使用自定义绑定，null 表示明确禁用；macOS 本机菜单加速器和 渲染器拥有的快捷键从同一张映射更新
• 插件启动器在 macOS 默认为 Option + Space，在 Windows/Linux 默认为 Alt + Space；本机全局注册遵循相同覆盖。未绑定时会同时关闭 Electron 注册、 Windows host hook 和聚焦窗口后备
  • 窗口可见性只有一行、一个开关键 Alt + Shift + W：把可见且在前台的窗口隐藏到 托盘，把已隐藏或已最小化的窗口调回来。它是唯一的窗口键 —— 已弃用的 Cmd/Ctrl + Shift + W 呼出组合键已移除 —— 并且避开 Cmd/Ctrl + W，因为 macOS 把它用于自己的关闭窗口命令；读取配置映射时，已存储的 closeWindow / summonWindow 覆盖项会并入它（D438、D439）

模型配置（agent 选项卡）

• Studio Hero：提供商计数、就绪计数和当前默认 provider/model 摘要
• 默认卡：默认提供商/模型选择器。全局运行模式、命令 Shell 和回车发送由全局 AI 目的地负责。
• 厂商账户卡片（D237），位于默认值与提供商之间：
  • 卡片列出的是账户而非厂商：已登录的厂商各占一行，一个也没有时用一句 说明取代列表。运行时目录不提供任何 OAuth 厂商时整个分区隐藏
  • 卡片头部的“添加账户”打开尚未登录的厂商选择器 —— 与“添加 AI 服务” 同一形态，这样认识七家厂商的版本不会用七行来说明谁都没登录。所有已知 厂商都已登录时该操作禁用
  • 账户行显示厂商名称、访问由套餐支撑时的“订阅”徽标、“已连接”徽标与 账户标签
  • 选中厂商后打开单个对话框，渲染流程要求的任何形态 —— 已打开的浏览器加 可复制链接、设备码、单选，或文本输入 —— 并带一个取消操作，用于中止 本地回调服务器或轮询循环
  • “退出登录”移除凭据与就绪状态；该行离开列表，厂商回到选择器中
  • “编辑账户”打开的对话框带有账户标签，以及与 AI 服务对话框完全相同的双栏 模型选择器（D270）：左侧是该账户已发现／有权使用的模型（列表标题旁可全选当前可见行，并可立刻获取列表），右侧是已选绑定， 每个模型在“高级”折叠区里可编辑别名、上下文窗口、输出上限、思考等级与附件能力； 行内以统一的紧凑格式显示模型 ID、来源、能力与上限（如 1.05M · 128K）， 相邻窗口不会被舍入成同一个字符串； 展开区是紧凑表单：别名说明放在输入框 title 上，数字框去掉原生步进按钮，思考档铺满一行且默认档与标签同行，附件与委派勾选同一行。 Chat Completions 的模型设置提供思考强度参数菜单：“自动”“发送”“不发送”。 自动恢复兼容默认值，其他选项保存模型级 supportsReasoningEffort 布尔值。 保存后重新打开、复制配置和配置同步均保留选择；其他 API 格式隐藏该控件， 但不删除已保存的偏好。 上下文窗口字段会说明自己的来源：数值仍跟随 models.dev 发布上限时，输入框下方显示 一行淡色提示（settings.contextWindowCatalogHint）；用户第一次改动（预设档位或 数字输入）即把该值固定为用户自己的值并移除提示。被用户固定的值不会被目录刷新 覆盖；目录没有该模型的记录时不显示提示。 因此两种凭据的模型选择完全一致。账户没有 API 密钥输入框，模型发现改由已保存 的 OAuth 登录解析。保存会更新该 OAuth 提供商行，并在该账户被选为默认时同步 全局默认模型
  • 视口宽度不超过 940px 时，服务与厂商账号的模型面板上下堆叠， 不压缩到对话框剩余高度。每份模型列表在有界区域内独立滚动， 对话框正文可滚动以访问两份列表；较矮的宽窗口仍保持左右布局。
• 提供商工作室：
  • OpenAI 兼容的添加提供程序对话框（从添加提供程序/空状态 CTA 打开）
  • 提供商区块标题提供“从其他工具导入”操作。内嵌面板仅在用户明确启动扫描后读取本地配置， 按来源分组显示草稿，且不渲染原始凭据；已存储的 API 密钥写入宿主密钥库， 订阅/OAuth 登录不导入，等价提供商会跳过。
  • 新建对话框先只显示服务。命名端点按厂商平铺（OpenAI、Anthropic、Google、OpenRouter、DeepSeek、通义千问、月之暗面、智谱、硅基流动、火山方舟、MiniMax、MiniMax (OpenAI)、小米、Kimi 编程等），不再分国际 / 国内。选中后显示服务 + API 密钥和主机摘要。自定义端点随后分三行显示服务、名称与接口地址、以及 API 密钥与接口格式，让字段在表单变化时保持稳定对齐；接口地址不附带解释性说明。获取模型失败时，分类结论以一条 toast 报出，空列表处只保留一行「无列表」文案，已有缓存列表时列表原样保留；两种情况都不展示原始 HTTP/JSON 报错。探测结论（已连接、来自目录或被拒绝）只播报一次，密钥下方不再保留状态行。名称（命名行）与可选自定义请求头放在高级设置中。对话框右上角提供明确的“高级设置”按钮，点击后打开独立紧凑弹框，主表单只保留端点和模型面板。弹框可直接添加包含 User-Agent 在内的常用请求头，可将与持久化相同的规范化请求头 JSON 复制到剪贴板（忽略空名称，后者覆盖前者），也支持导入直接请求头对象或 { "headers": { ... } } JSON；导入时按名称合并，不重复添加。列表最多显示五行，更多请求头在自身区域滚动；留空则使用适配器默认值。服务是可搜索锚定菜单（按显示名、厂商、主机过滤），不是原生下拉框。
  • 带有头像缩写、主机、默认模型、秘密状态的提供商卡， 和测试/make-default/删除操作
  • add/edit 对话框配置连接身份（名称、端点、API 样式、模型 ID 和密码）； 窄窗口下对话框收缩进 overlay，聚焦输入框的 2px 强调环不被滚动容器裁切； 模型参数来自 pi-ai，此处不可编辑
  • 具有主要添加操作的空状态
  • API 键在保存后永远不会显示原始内容
  • 已登录的厂商行带账户徽标，其编辑对话框用该徽标替换 API 密钥字段 —— 这里没有东西可粘贴
• 列表仍分两组：内置五个默认子智能体（explorer、code-reviewer、test-runner、 fixer、ui-designer）和 ~/.agents/subagents 下的用户文档。同名的已启用用户文档 会在 Task 目录中遮蔽对应的内置定义，内置行随之省略、只保留用户行；同名的已停用用户 文档会让该内置重新留在目录（以及内置列表）中，因为 Task 又用回随应用发布的定义。 内置行带来源角标、「复制为我的定义」（以该定义预填新建表单，并选中对应的模板芯片）， 以及与用户行相同的启用开关（D202 意义上的应用本地状态，ADR 0270）：关掉它写入的是 应用本地状态而不是文档，该行仍留在列表中并变暗，所以这个开关就是重新打开的入口； 下一次目录加载起不再提供给 Task。在文件夹中显示与删除仍然没有，因为内置不是文件。
• 子智能体新建/编辑表单使用与 Composer 相同的已配置、可运行模型， 控件是可搜索、按提供商分组的锚定菜单（与服务选择器同一套选项菜单控件）， 并提供“沿用会话模型”选项。原生下拉框无法承载该列表：一次安装可能配置数十个模型， 只有锚定浮层能在自身内部滚动并接受过滤。每个选项都来自已配置的提供商目录，表单不接受手填模型 ID； 当没有任何提供商提供可运行模型时，改为显示带操作按钮的空态（直接打开模型设置）。 内置项保留自己的内置行：可以开关，但永不编辑；模型选择器只用于新建和用户自有子智能体。 若已有 pin 不再配置，编辑时仍保留该选项，避免悄悄丢失。通用或重复的 厂商标识如果产生歧义，则依次使用唯一的提供商显示名和已存储的提供商 ID，保证不同提供商的 选项不会被合并。思考选择器提供沿用会话、不发送以及七个规范档位； 不发送持久化为 thinkingLevel: omit。 模型配置里已选中的思考档芯片在浅色和深色主题下都使用实心强调底和反色主文本。 新建表单在名称上方显示一行紧凑的模板名称 chips（探索者、代码审查员、测试执行者、 修复者、UI 设计师、空白开始）：只显示名称，选中项的一句话说明出现在整行下方。带连字符的 id（code-reviewer、test-runner、ui-designer）必须走目录映射（presetReviewerName / presetTestRunnerName / presetUiDesignerName），不能靠首字母大写拼 key。模型、推理、输出上限和作用域 放在“高级”折叠区：新建时默认收起，编辑时默认展开。

权限模式选择器在 Composer 中仍然可用，而 会话位于 Agent、Plan 或 Goal 中。在 Plan 和 Goal 中，它控制 Bash 仅确认：询问并接受编辑提示，而自动可能会运行变异 无需确认的 Bash 命令。全局 AI 默认项卡必须描述两者 契约模式是意图边界，而不是严格的只读安全配置文件。

说明（instructions 选项卡）

• 编辑每个 PI-Desktop Agent 会话使用的全局指令 Markdown。
• 显示解析的指令文件路径并通过主机支持保存 指令 API；项目指令仍由活动项目管理 菜单并在全局层之后解决。

内嵌导入工作台

• 模型配置、外部技能和外部 MCP 扫描分别位于“模型”“技能”和“MCP”设置页。每页保留 显式扫描与选择工作台；打开或关闭工作台不会自动扫描。
• 技能和 MCP 导入遵循当前“全局 / 项目”筛选及所选项目。项目扫描和写入都携带所选项目 路径；切换目标作用域会重置候选项与选择，避免导入到旧目标。
• 技能工作台保留复制/链接模式以及技能区块中的原生文件、文件夹导入操作。MCP 候选行 不显示秘密或请求头值，URL 元数据只显示主机；来源服务器原本禁用时，导入后仍保持禁用。
• 设置不提供会话扫描或导入面板。会话导入通过现有宿主拥有的插件会话 API 提供；项目绑定 与刷新行为遵循插件会话契约（D645 / ADR 0319）。
• 模型配置通过 ModelConfigImportPanel 审核提供商草稿 （08-组件规范 §18.5）。 CC Switch（~/.cc-switch）作为独立来源扫描，可导入已保存的配置档案，而不只是当前生效的 live 文件。同一规范化 base URL、API 风格和凭据的提供商会跳过；同一端点但凭据不同的 配置档案保持独立。若应用尚无默认模型，本次新建的首个提供商成为默认。工作台细节见 08-组件规范 §18。

项目档案

• 重用持久项目索引作为设置规模管理界面
• 始终包含存档记录；归档行被分组，从不隐藏，所以 目的地仍然没有可见性切换
• 支持项目搜索、添加、选中、激活、置顶、归档/恢复和关闭
• 该目的地是一个工作台（D267），由 D455 修订为单列：精简行，检查器在选中行下方铺满宽度； 现进一步改为 iOS 意义上的内嵌分组索引：选中行就是它自己卡片的表头， 因此详情在该行下方展开，且不重复行上已有的信息。 一个工具栏领起页面，且默认不展开任何内容：与能力页面和内嵌导入工作台一样， 该目的地不带说明行，页面标题与控制之间没有整句文字。 它复用与智能体能力页面（D257）相同的构成、控件高度和行节奏， 不引入页面专属装饰。
  1. 工具栏 — 一行承载使用共享分段控件的“最近/名称”排序、 带清除可供性并在搜索时显示匹配计数的搜索字段，以及右对齐的 主要“添加项目”操作。该目的地不展示页面级总计：没有英雄区块、 装饰渐变、计数器横幅或内联计数器串。索引分组上的计数是唯一的总计， 因此同一个数字绝不会在两处重复出现
  2. 工作台 — 单列。始终可见的索引部分按“固定”、“所有项目”、 “已存档”呈现为非交互标题行，每条带有标签和行数。 每个部分都是包裹自身列表的带标签区域，标题行绝不会作为列表的非列表子项。 单击一行时其卡片在该行下方铺满宽度展开，该行的展开指示器随之转向下方。 空部分被省略；完全没有行时呈现安静空状态
• 行的信息自左向右是身份、自右向左是细节：颜色字形、项目名和一个状态标签 （当前 / 已打开 / 已归档）、用于区分同名项目的缩短等宽路径， 然后是右对齐的会话计数与相对上次活动时间，最后是该行的展开指示器。 普通项目用文件夹字形，置顶项目用实心星标。行靠行间距分隔，从不使用分隔线。 单击一行打开其卡片并留在设置页，再次单击该行则收起卡片， 单击其他行则把打开的卡片移过去；索引初始即为收起状态。 展开指示器只在卡片展开时转向下方，不会把已收起的卡片说成展开。 双击或 Enter 激活项目并返回聊天
• 选中行下方的卡片即详情面板，它不重复行上已有的信息 —— 不会有第二份名称、 路径或状态标签。它先是一个操作栏（新任务、项目不是当前工作区时的“打开”、 以及更多菜单），接着是只读的文件夹与分支信息、会话计数， 最后是会话列表本身。更多菜单将创建/编辑放在置顶、归档/恢复和关闭之上， 并在 Escape 或外部点击时关闭
• 项目搜索还匹配会话标题。匹配的会话会使其所属项目留在索引中； 打开该项目后按最新活动列出匹配会话，以 8 条一批显示，而不是截断历史
• 激活项目或项目会话返回聊天；归档和关闭仍使项目归档页保持打开
• 明确打开已归档项目会清除渲染层归档状态，使其重新显示在主页侧边栏；仅选择详情行进行检查不会恢复项目

云同步

• Connection: S3 endpoint, region, private bucket, prefix, access key ID, secret key, optional token, addressing style, device label and vault password. Choose sync or backup mode and automatic runs. Conditional writes are required; there is no WebDAV/append-only fallback. Legacy data remains without migration.
• 可移植配置：支持的类别默认选中；凭据和项目 memory 必须明确选择。预览显示 supported、excluded、secret-bearing、mapping-required 和 pending-approval 计数。
• Safety: vault keys and exported secrets are never returned to the page. Connection secrets stay transient; imports keep local approval and mappings. Public HTTP and redirects are rejected; LAN HTTP follows Host network policy. Disconnect preserves local configuration, legacy data and remote objects.
• 状态与恢复：显示已配置、已锁定、同步中、离线、不支持服务器、冲突、等待激活、暂停和错误等不同状态。用户可以立即同步、解锁、暂停本设备、批准/拒绝暂存项目以及断开连接。存在待处理状态时，页面不会根据旧的成功记录暗示已经收敛。
• Drafts and recovery: cache only typed non-secret S3 choices under a new versioned key; ignore old drafts. Blank credentials reuse the exact connection, while explicit clearing/replacement clears the token. Never persist secrets or passwords. Invalidate old history requests when the saved destination/mode changes. Display the latest 30 revisions and disclose indefinite object retention. Sync restore confirms immediate publication; backup restore is local only. Unsaved mode edits do not change restore semantics. Password changes do not revoke unlocked devices.

信息

• app/host/protocol版本+开放日志
• 问题反馈行：一项操作在系统浏览器中打开 GitHub bug 表单。 Electron Main 拥有该 URL（pi-desktop/app/openFeedback），用主进程版本信息 预填应用版本、操作系统和环境，且从不接受渲染器提供的目标 （D313 / ADR 0157）
• 使用当前交付状态和一项适用操作更新行： 检查更新、查看版本或重新启动以更新
• 开发者卡：
  • 开发者模式关闭，除非可选持续存在 AppSettings.developerMode 值是 true
  • 开发者模式开关解锁“打开控制台”按钮，每个按钮上按 F12 平台、Windows/Linux 上的 Ctrl+Shift+I 以及 macOS 查看菜单开发人员 工具项，以及导轨上的远程主机目的地
  • 禁用开发者模式会关闭打开的控制台并禁用或删除 每个入口点；设置搜索索引卡、交换机和控制台 行动
• 更新行始终显示发行说明操作。它打开一个模式 包含按最新顺序排列的完整发布的稳定变更日志， 本地化为产品语言并标记当前可用的 存在的版本
• 当有更新可用、正在下载或已下载并附加主要更新时 本地化产品说明，更新行显示紧凑的“新增内容” 状态文本下的列表（与环境横幅相同的注释；D164）。的 当应用程序是最新的或更新时，完整历史模式仍然可用 检查在开发中被禁用

3. 导航规则

• 配置文件页脚/命令面板打开设置整页（默认外观，即目录中的第一个目的地）
• Composer 模型菜单和提供程序设置操作深层链接到模型页内的提供程序卡
• 插件管理仍然可以从独立的应用程序外壳中获得 插件目的地，包括加载、启用、禁用和卸载；是的 设置中不重复
• 项目档案由设置搜索索引，不会复制为主页 侧边栏目标或独立的全局搜索页面
• 返回应用程序从导轨固定的底部操作返回聊天外壳
• 仅开发者可用的目的地作为一个整体加入或离开导轨、页面和设置搜索。 云同步和远程主机不受开发者模式限制，在所有构建中均可用，并在导轨行与页面标题 显示实验性徽章。

4. 验收

1.打开设置隐藏编码应用侧边栏（全页接管） 2. 导轨顶部显示搜索药丸，底部固定返回应用程序操作并与主侧边栏底部图标行同一条线， 并精确显示外观、对话、快捷键、语音、行为、模型、指令、技能、MCP、 子智能体、项目、系统、云同步、远程主机和信息，按此顺序排列；云同步与远程主机 均在打包版中显示实验性标签，并按偏好、智能体、工作区、系统分组。 没有用量设置目的地，也没有「常规」或「AI」目的地：这两个 id 解析到外观与行为， 但不出现在导轨和搜索结果中。 3.外观是独立目的地；它过去同页的网络、存储、电源与关闭行为卡现在在系统页 4. Providers 是模型页的一部分，没有独立的导轨目的地 5. 插件没有设置目的地； app-shell 插件页面支持 加载、启用、禁用和卸载 6. 外观显示主机支持的界面卡；对话显示「显示」与「输入与链接」；行为显示 会话默认（含权限模式与命令 Shell 行）、执行与电脑操作；快捷键 目的地显示键盘快捷键卡；信息显示开发者卡。 不呈现其他设置目的地 7. 提供商机密从不显示原始密钥值 8.模型配置显示提供程序工作室（英雄+默认+添加对话框+卡片）而不是密集的始终在线表单转储 9.行的解释不是常驻第二行：它作为字符串进入标题旁的问号，在悬停与键盘聚焦时 显示，并在浅色和深色主题下与卡片表面保持至少 4.5:1 对比度。行的实时取值 （已固定的默认模型）属于数据而不是说明文字，始终可见。卡可以改为在标题 下携带一行可见副标题（D684），因为那一行说明的是整组的用途而不是某个开关； 需要第二句话的文案仍留在标题的问号后 10. 从“设置”两侧拖动空白顶部区域可移动本机 窗口，不会阻塞后退、搜索或导航控件 11. 调整窗口大小可扩展或收缩内容卡 可用内容窗格；固定导轨和窗格排水沟保持完好无损 页面没有水平溢出 12. 项目归档始终公开归档记录，并且可以在无需修复的情况下恢复它们 在应用程序 shell 中复制索引 13. 项目存档不呈现说明行 —— 没有英雄区块、横幅或页面级计数器串 —— 其下方是一个搜索+排序工具栏，以及带有 固定/所有项目/存档分组标题的单列工作台；每个分组的计数与其呈现的行数一致， 索引初始不展开任何内容，单击一行打开其卡片且不离开设置页， 排序对每个部分内的行重新排序而不隐藏任何内容， 清除搜索即可恢复完整索引 14.信息呈现禁用、检查、最新、可用、下载、 已下载，并且错误更新状态而不添加其他目标 15. 本机选择选项列表在浅色和深色主题中仍然可读， 包括 Chromium 将打开的列表表面委托给 Windows 时；的 相同的全局规则涵盖非设置本机选择 16.快捷录音拒绝无修饰符的非功能键，保留 editor/OS 和弦，以及冲突；成功覆盖立即驱动 应用程序行为和 macOS 菜单加速器并在重新启动后继续存在 17. 开发者工具默认不可用；启用开发者模式 解锁本地化设置操作和平台快捷方式，持续存在 重新启动后，禁用它会关闭打开的控制台 18. 上下文管理根本不公开任何设置；保护始终开启并且 其预算随着活动模型的上下文窗口而变化，因此不会持续存在 值可能会使小窗口模型无法压缩或防护被禁用 19. 默认操作模式选择器包含 Agent、Plan 和 Goal；遗产 聊天值迁移到 Plan 并且不会重新显示为可选选项 20. 命令 Shell 选择保留平台有效的目录 ID，仅在状态有额外信息时公开 默认、不可用、回退或无实际 Shell 文案，并且从不授权过时的 ID/dialect 21. 信息页提供「问题反馈」，打开已预填版本和操作系统的 GitHub bug 表单；设置搜索可索引该行 22. 技能页的市场视图浏览公网 HTTPS 目录、预览组装后的文档，并只通过 skills.create 安装；超限展开文档拒绝写入，来源角标跟随 sourceId；预览失败时面板给出可读原因与重试入口（安装按钮可以禁用,但不得无解释地禁用）；来源被公网策略守卫拒绝时明确说明,而不是笼统报「不可达」。目录查询全部失败或仅部分来源失败时都提供重试按钮；点击后按当前搜索和已配置来源重查，并在请求期间播报加载状态。成功加载过后再遇失败时，列表保留上次成功加载的结果并标注时间，重试入口不变；该列表不回答其他搜索词，重试成功后即消失 23. MCP 市场安装遵循添加按钮的目标：All 和 Global 保存到全局，Project 保存到所选项目。已安装标记只检查目标层级，其他层级中的同名条目不阻止安装。未选择项目时禁止项目安装，不回退到全局。查询全部失败或部分来源失败时提供重试按钮；点击后重跑当前搜索，并在请求期间播报加载状态。成功加载过后再遇失败时，列表保留上次成功加载的结果并标注时间，重试入口不变

5. Chrome 指标常规

外壳保留了 Codex 金铬，同时允许内容窗格使用 当前窗口宽度：

代币	价值
导轨宽度	〜275像素（--ds-settings-nav-width，由导轨与顶部带的内缩共用）
导航背景	与主侧栏共享材质；浅色不透明回退为 #f3f3f3，macOS 使用原生毛玻璃
顶部带	仅内容窗格，按导轨宽度内缩；导轨保留自己的表面
选中导航药丸	7px/10px 内边距，--radius-md，在导轨选中底色上混入约 12% 强调色；该行字形取 --ds-accent
导轨分组标题	最小可读字号（--text-xs-plus）、semibold、--tracking-wide、大写
页头	38px 强调色底片字形（--radius-md-plus）+ 14px 间距 + 标题块
章节标题	28px / 560，第一条基线 ~y70
页面副标题	--text-md、--ds-text-secondary，标题下一行
卡片副标题	--text-sm-plus、--ds-text-secondary，卡标题下一行
内容宽度	栏杆和天沟后的完整可用窗格宽度
卡半径	~14px 升高行程
切换	32×20 拇指 16，中性重音（非绿色）
开放靶点药丸	前导 VS Code 字形

MCP 创建归属（#1953）

MCP 在 All 筛选下优先创建、导入、安装到所选项目；未选项目时使用全局。 显式 Global 保持全局，Project 无选择时禁止写入。已打开编辑器固定其项目归属， 切换页面项目不会移动现有定义。其他能力页继续遵循各自已有默认规则。 保存前读取编辑器固定目标的最新列表，检查重复 ID 和名称；其他项目同名定义 不阻止合法保存，目标项目真实冲突仍拒绝。Host upsert 继续执行权威归属校验。