常见问题
这一页按主题分组，问题用你真正会问的说法，答案给具体行为与边界（错误码、默认值、拒绝条件），需要展开时链接到对应文档页。
客户端启动后必须先登录吗？登录到哪一台服务端？
Section titled “客户端启动后必须先登录吗？登录到哪一台服务端？”是。未登录时主窗口的第一页就是登录页：填服务端地址 → 选择登录方式（本地账号 / LDAP / OIDC）→ 登录成功后同一窗口切到应用界面。远程地址必须是 https（只有 localhost / 127.0.0.1 允许 http）；渠道包内置了地址时这一步会被预填并跳过。
账号、模型清单、余额、能力中心内容、连接器目录都来自这台服务端。部署形态（企业内网容器化、并入已有反代、单机）见私有化部署。
我的数据在谁手里？
Section titled “我的数据在谁手里？”分两半，边界很清楚：
- 在员工机器上的：会话与消息日志、工作区文件、工具执行、沙箱状态、语音音频、连接器凭据。数据根由一份权威定义给出（
~/.picoaide-harness，DSH_HOME优先，渠道不同则目录不同）；凭据目录0700、文件0600、原子写入。 - 在客户自己服务器上的：账号、模型用量与费用、余额账本、内容与授权、审计事件。服务端不接触员工本机文件与会话日志。
厂商既不自建托管服务、也不中转数据。数据离开机器的路径全部由你自己配置：模型请求从员工机器发到你的服务端，再由服务端转发给你选择的上游 provider；连接器只连你在管理后台登记的那些 MCP 端点。用云端模型时内容会到那家 provider，用内网模型则不出内网。
部署要几张证书？怎么选？
Section titled “部署要几张证书？怎么选？”TLS_MODE 三选一：internal（Caddy 本地 CA 自签，内网 IP 场景，客户端首次连接需信任该 CA）、auto（公网域名自动签发，需要 A 记录直连、80/443 开放；经 CDN 会失败）、manual（企业正式证书，支持 IP）。详见部署总览的证书模式和容器化部署。
升级会不会丢数据？怎么回滚？
Section titled “升级会不会丢数据？怎么回滚？”升级只换镜像；数据全部落在部署目录下的 bind mount（picoaide-data/、pg-data/、caddy-data/、certs/）。回滚是切回旧镜像再 docker compose up -d server，但数据库迁移不可逆：回滚镜像不能把库降回旧结构，所以升级前必须备份并确认备份非空（master.key 丢了，库里加密的上游密钥就永久解不开）。
四条铁律：绝不 docker compose down -v / volume prune；绝不用 latest 标签；升级前必须备份；不得用 .env 覆盖已有部署目录。完整流程见升级、备份与回滚。
能不能并入已有反代，或者用外部 PostgreSQL？
Section titled “能不能并入已有反代，或者用外部 PostgreSQL？”可以。部署形态包含「只起 server + postgres 并挂进已有 vhost」，也支持单二进制 + 外部 PostgreSQL（含从 systemd 迁移）。注意容器 IP 与可信代理的对应关系要一起改，否则审计里的客户端 IP 归属与登录限流桶会失真——见运维与排障。
客户端与升级
Section titled “客户端与升级”客户端安装包在哪里下载？
Section titled “客户端安装包在哪里下载？”只有两个来源：企业服务器的门户页（https://<企业域名>/，公开页，列出三平台下载入口）或官方镜像包（从镜像里解出 client/ 目录，步骤见快速开始）。产品没有公开下载站：客户端与应用/服务端之间有版本契约，把安装包放在镜像里，「客户端版本跟随服务端版本」就是结构事实而不是纪律要求。
员工端要手动升级吗？
Section titled “员工端要手动升级吗？”不需要。升级源只有一个 = 客户端登录的那台服务端（GET /api/client/v2/updates/manifest）：打包版启动 60 秒后首次检查、之后每 6 小时一次；检查与下载都是后台静默的，下载按清单里的 SHA-256 流式校验，失败不安装、保持当前版本。所以升级客户端的正确做法是升级服务端——服务端升级后，员工端下一次检查就会拿到新版本。
为什么安装包没签名？
Section titled “为什么安装包没签名？”Windows 安装程序与 Linux AppImage 未签名（macOS 正式版已签名 + 公证）。Windows SmartScreen 可能提示「未知发布者」——用镜像包同目录的 SHA256SUMS 校验后再运行。macOS 若提示「未能验证开发者」，通常是你用的是预发布包（只签名、未公证）。
应用更新是静默重启吗？
Section titled “应用更新是静默重启吗？”不是。检查与下载静默，安装一律由用户显式触发：Windows 走安装程序向导，macOS 打开 DMG 后由用户拖入「应用程序」，Linux 由用户替换 AppImage（无静默自安装）。产品不做「静默重启安装」——客户端承载着本机会话与未保存的工作，静默重启的代价比晚几分钟升级大。
关掉窗口是不是退出了？
Section titled “关掉窗口是不是退出了？”不是。关闭窗口只是隐藏到托盘，本地 Harness 服务继续跑（自动化任务照常触发）。要真正结束应用与本地服务，走托盘菜单的「退出」。
端口冲突怎么办？
Section titled “端口冲突怎么办？”本地 Web 端口默认由系统随机分配（dsh-desktop.port: 0），只监听 127.0.0.1。固定端口被占用时本地服务监听失败、窗口无法加载：把端口改回 0 或换一个空闲端口，然后重启应用（改端口会有序重启，不会热替换）。
客户端能用系统代理吗？
Section titled “客户端能用系统代理吗？”默认不能：系统代理设置、代理环境变量、PAC 与 --proxy-server 全部被忽略。只有「必须经代理才能出公网」的部署才打开退路——渠道字段 desktop.allow_system_proxy，或真实进程环境变量 PICOAI_ALLOW_SYSTEM_PROXY=1（写在 .env 分层里不生效）；打开后启动日志会打印 proxy system/<来源>，默认直连时打印 proxy direct。
能在客户端装第三方 DSH 插件吗？
Section titled “能在客户端装第三方 DSH 插件吗？”能，走 profile 的用户补丁层：编辑 ~/.picoaide-harness/cordis.patch.yml（渠道不同则数据根不同），按 Loader patch 语法追加一行，重启应用后生效。
不能用 dsh plugin --profile desktop …：desktop profile 由桌面应用独占，CLI 会直接拒绝（profile "desktop" is managed exclusively by the Electron application），应用也没有终端或 profile 切换入口。
上游 API Key 存在哪？客户端能看到吗？
Section titled “上游 API Key 存在哪？客户端能看到吗？”只在服务端：以 AES-GCM 加密存储（密文前缀 enc:v1:），主密钥是部署目录里的独立文件 master.key（0600，永不入库）。客户端拿到的只是它自己的会话令牌，模型端点是 <服务端>/v1，从头到尾看不到上游密钥。
员工能用自己选的模型或自己的 Key 吗？
Section titled “员工能用自己选的模型或自己的 Key 吗？”不能。模型目录、输入模态、单价与折扣由管理员在管理后台统一配置；客户端的模型设置入口被显式禁用，也没有本地 provider 配置。没登录时客户端没有可用的模型路由——这是「密钥只在服务端」的直接结果，不是故障。
余额用完会怎样？
Section titled “余额用完会怎样？”网关返回 429 BALANCE_EXHAUSTED：余额是唯一的计费闸门（按用户、消费即扣、可逐笔对账）。管理员账号豁免；从未入账的账号在账户页不渲染余额行。未定价的模型默认 429 MODEL_NOT_PRICED，除非管理员用策略开关显式放行。高峰窗口外可按模型的低谷折扣折算。
员工令牌多久过期？改密会怎样？
Section titled “员工令牌多久过期？改密会怎样？”员工 API 令牌 90 天过期，服务端只存哈希。改密、降权、禁用会在同一事务里吊销该账号的全部 API 令牌与管理端会话；重置密码后服务端要求下次登录先改密（否则业务接口返回 403 PASSWORD_CHANGE_REQUIRED）。
管理员忘记密码或 MFA 怎么办？
Section titled “管理员忘记密码或 MFA 怎么办？”管理员 MFA（TOTP）没有恢复码：兜底是另一个超管重置（管理员不能重置自己），重置后该账号的全部会话被吊销。管理端会话本身有 12 小时硬上限 + 60 分钟空闲滑动过期。详见企业管控面。
登录被限流了怎么办？
Section titled “登录被限流了怎么办？”限流只对失败计数（5 分钟滑动窗口，成功即清空）：账号维度 10 次、来源 IP 维度 60 次。等窗口过去再试；如果是全组织都登不上，先检查反向代理是否正确传递了客户端 IP（配置见运维与排障）。
能力与连接器
Section titled “能力与连接器”能力中心的内容从哪来，谁能装？
Section titled “能力中心的内容从哪来，谁能装？”两个正交维度：内容类型（技能 / 智能体）× 来源（市场 / 组织 / 本地）。市场由管理员上架、按用户或部门授权后才可见可装；组织是员工上传后管理员审核（approve / reject），通过后仍要授权——「审核 + 授权」双门制；本地是你自己创作的，只在本机可见。质量标记只有「官方 / 精选」两种，由管理员在审批时打。
我上传的技能别人会看到吗？
Section titled “我上传的技能别人会看到吗？”不会立即看到。上传后进入 pending，管理员 approve 之后还要对你指定的人或部门授权，才对他们可见可装；未授权一律不可见。归属 = 首个成功占名的发布者：即使后来被拒或下架，名字仍归你，防止被抢占。
连接器支持哪些？怎么加一个新的？
Section titled “连接器支持哪些？怎么加一个新的？”对外契约收敛成一条标准 MCP 配置：type（streamableHttp / http / stdio，省略时按 url 或 command 推断）+ url，或 command / args / env，外加标题说明；未登记的键一律报错而不是忽略。认证模式默认自动：连上去探测——2xx 即公开端点；401 按 WWW-Authenticate 走 RFC 9728 → RFC 8414 发现 + 动态客户端注册 + PKCE；声明了凭据表单就走表单；两者都没有即免凭据。stdio 连接器首次运行需要本地确认（命令、参数、环境变量逐条披露），PATH / NODE_OPTIONS 一类进程引导变量永不注入。
连接器令牌会过期吗？到期怎么办？
Section titled “连接器令牌会过期吗？到期怎么办？”会，但通常不用你管：令牌自动续期（SDK 401 自愈 + 后台心跳，按到期时间提前续），轮换后的凭据原子落盘。只有授权被服务端吊销（死 grant）时，连接器行会变成「需要重新授权」并给出明确文案；5xx 一类临时故障会保留旧凭据重试。凭据按（账号 + 服务端地址）作用域存储，换账号或换服务端不会串用。
关掉客户端，自动化任务还会跑吗？
Section titled “关掉客户端，自动化任务还会跑吗？”窗口关掉不影响（只隐藏，本地服务继续跑）。应用完全退出期间不触发；下次启动后，属于当前登录账号的到期任务会补触发一次。任务到点把提示词发回创建它的原会话，执行记录（触发时间、投递消息 id）在「自动化任务」里可查。模型可以通过 schedule_create / schedule_list / schedule_update / schedule_delete 操作任务，但目录与投递都按账号隔离，它看不见的任务按「不存在」处理。
内置浏览器安全吗？AI 会不会乱点？
Section titled “内置浏览器安全吗？AI 会不会乱点？”控制权只能通过同一个按钮双向交接：右下角「我来操作」取得，同一个胶囊变成「交给 AI」交回；蒙版空白处、活动面板、Esc 都不会改变控制权。下载默认 100MB 上限，超限拒绝；每次导航 / 点击 / 下载都进操作日志；关窗只是隐藏，只有模型的 browser_close 才真正销毁窗口。
语音输入会把音频传到云端吗？
Section titled “语音输入会把音频传到云端吗？”不会。识别跑在本机子进程（SenseVoiceSmall + Silero VAD），音频不出机器、离线可用，也没有云端回退；中文、英文、日文、韩文、粤语自动识别。模型默认随客户端分发（装上即用、零下载），只有渠道显式关掉时才回落到首次使用下载。转写只落进输入框草稿，不写入会话、不自动发送；单次上限 120 秒 / 4MiB。
记忆是 AI 自己写的吗？
Section titled “记忆是 AI 自己写的吗？”不是。记忆是确认制：AI 通过 memory_suggest 之类的建议入口进入待确认队列，你采纳才写入。五条轨道（用户档案 / 全局事实 / 项目关键记忆 / 项目日志 / 每日日志）里，项目轨按目录与 git 分支隔离；主轨与归档可双向移动。
应用中心的应用需要公网入口或证书吗？
Section titled “应用中心的应用需要公网入口或证书吗？”不需要。员工自建的 WASM 应用只在客户端独立窗口里打开（自定义协议），服务端唯一入口是 POST /api/client/v2/apps/wasm/:app_id/request（带员工令牌转发执行）。所以部署时不需要为应用准备子域、通配证书或额外端口。应用配置 picoaide.app.json 的 access 取 public / login / whitelist（缺省 login），whitelist 由应用自己读取并判定；「允许 AI 读取此应用的数据」这类授权按（用户 + 服务端 + 应用）作用域记录。
PicoAide Harness 与 DeepSeek Harness 是什么关系？
Section titled “PicoAide Harness 与 DeepSeek Harness 是什么关系？”基于固定版本的 DeepSeek Harness（当前 pin dsh-v0.2.1-rc.2，真源为仓库根 upstream.json）构建。上游提供核心智能体、插件系统与 Web UI；本项目提供桌面封装、本地服务管理与企业级管控面。上游源码原样运行，不魔改——只保留少量带判据的补丁，升级只跟随上游版本号。
这是 DeepSeek 官方产品吗？
Section titled “这是 DeepSeek 官方产品吗？”不是。PicoAide Harness 是独立的开源社区项目（MIT License），与 DeepSeek 官方没有隶属关系，也未获得其背书。DeepSeek 是 DeepSeek AI 的商标。
开源许可是什么？可以商用/二次开发吗？
Section titled “开源许可是什么？可以商用/二次开发吗？”MIT License，可以自由使用、修改与分发（保留许可证与版权声明）。品牌与文案走渠道内容：名称、标语、欢迎语、标识、主题色、数据根等在构建期注入镜像，不同渠道的安装包与数据根互相独立；改品牌 = 重新构建对应渠道镜像，而不是在管理端在线编辑。二次开发与打包细节见系统架构与插件开发。
遇到问题在哪反馈？
Section titled “遇到问题在哪反馈？”先看桌面客户端的排查一节与运维与排障，仍无法解决再提交 GitHub Issue，并附上操作系统、应用版本、复现步骤与错误信息。应用持续闪退时，用 --export-diagnostics 或托盘「导出诊断信息…」生成诊断包（分享前请自行检查内容）。