产品哲学

PicoAide Harness 不是「一个有着大量功能的软件」，而是一套有明确边界的设计哲学的落地。理解下面的原则，就能预测产品中几乎每一个功能为什么长成现在这个样子。

〇、我们解决什么问题

DeepSeek Harness 的核心是一个可组合的 agent harness。它适合通过命令行和 Web UI 使用，也适合开发者把模型、工具、会话和工作流组合成自己的运行时。但对很多用户来说，第一次运行仍然要面对 Node.js、profile、依赖安装、端口和进程生命周期。

PicoAide Harness 的目标不是重新实现 Harness，而是把同一个运行时放进一个容易启动、容易管理、符合操作系统习惯的应用里：

安装包负责提供 Electron、Node 运行时和固定版本的 DSH 依赖；
应用负责窗口、托盘、单实例、退出和本地服务生命周期；
用户仍然使用官方 DSH 的 profile、插件、会话和 Web UI；
上游 Harness 继续拥有 agent、模型、工具、会话和 Web 客户端的核心语义。

因此 PicoAide Harness 是一个产品入口和运行时适配层，不是上游项目的替代品，也不是把上游源码复制一份再长期分叉。

一、一切皆插件：桌面本身也是插件

这是整条产品线的第一性原理。

DeepSeek Harness 的核心是一个可组合的 agent harness：agent、模型、工具、会话、Web UI 全部通过 Cordis 插件机制组合。PicoAide Harness 没有另起炉灶重写，而是把整个产品也当成一个插件——桌面壳（窗口、托盘、更新、固定 desktop profile）本身就是一个合法的 DSH 插件，与第三方插件走同一条组合路径：

上游 DeepSeek Harness 以固定版本原样运行（当前 pin dsh-v0.1.5-rc.2），任何产品能力都不修改上游源码；
官方生态里的插件可以直接安装使用；
自研的业务能力（能力中心、连接器、定时任务、浏览器、企业登录）与第三方插件对等组合，通过同一个 slot 机制注入界面、通过同一个 service contract 提供能力；
升级只跟随上游版本号，不破坏本地扩展。

操作哲学：能力可以替换，边界不可穿透。 公开的接口是明确的 contract（slot、service、子路径导出），私有内部（窗口、托盘、打包器内部）不向第三方开放。稳定边界比「什么都能访问」更容易升级与排错。

二、本地优先：数据留在本机

产品默认把一切敏感数据放在本机，并让「留在本机」成为可信的默认承诺：

所有 profile、会话、设置、凭据统一落在产品专属目录 ~/.picoaide-harness（DSH_HOME 环境变量优先），由一份权威定义（desktop-home）给出，杜绝多处复制导致的口径漂移；
平台会检查 DSH_HOME 是否落在系统关键目录——拒绝把会话令牌写进攻击者可读的位置（同机注入面收敛）；
连接器凭据以 0600/0700 权限原子写入（临时文件 + rename），防符号链接、路径逃逸与超大读取；
退出登录即触发 session-changed 事件，连接器、浏览器、定时任务的会话与令牌全部解除，不留残余。

操作哲学：默认本地，共享必须显式。 连接器授权、企业登录、云端模型调用都是用户或管理员显式发起的行为；产品自身不会把本机数据悄悄外发。

三、企业能力的边界：体验在客户端，管控在服务端

桌面客户端负责「体验」，Go 服务端负责「管控」，两者通过清晰的协议分工：

服务端：账号体系（local / LDAP / OIDC）、模型网关代理、限流、配额、计量计费、部门预算、技能与智能体市场、审批、审计——一切「可被滥用」的能力都在服务端；
客户端：对话、工作区、能力中心、连接器、定时任务、浏览器——一切「面向个人」的体验都在客户端；
多用户隔离是默认值而非功能：连接器凭据按用户 scope 存储、浏览器会话按账号隔离、定时任务按账号隔离；服务端按用户颁发 Bearer token（哈希存储、90 天过期、改密/降权/禁用自动吊销）。

操作哲学：能收口到服务端的决策，绝不在客户端自证。 客户端只显示服务端给定的配额、余额与权限结果（如 429 QUOTA_EXCEEDED），不做本地豁免。

四、能力的分发：内容类型 × 来源，维度永远正交

产品曾有过「技能商城 / 共享技能库 / 共享 Agent」三个平行入口，用户会误以为「商城技能」与「共享技能」是同类的两种卖法。事实是：真正正交的是两个维度——

维度	取值
内容类型	技能（SKILL.md 包） / 智能体（agent preset 包）
来源	市场（授权制）/ 组织（审核 + 授权双门制）/ 本地（自己创作）

因此客户端归一为**「能力中心」单入口：顶部 Tab 只有「我的 / 市场」，类型筛选（技能/智能体）、来源徽章（市场/组织/本地）、状态徽章（已安装 / 官方 / 精选 / 审核中 / 未通过）全部是叠加的过滤器**，而不是并列的通道。

命名学上还有一条铁律：词表唯一。「专业」一词全产品只作市场端分级语义（免费版 / 专业版），组织库的质量标记只用「官方 / 精选」——两套词表永不混叠。

操作哲学：当两个概念可以用一个维度表达时，绝不引入第二个入口；当维度正交时，绝不用同一个名词承载两层含义。

五、AI 只提议，人决定

凡是会真实改变 AI 行为的写入，产品一律先进入「待确认队列」，由用户或管理员拍板后才生效：

记忆写入（记忆、待办、技能演进）先提议、后确认；
定时任务由人创建（cron 表达式 + 提示词 + 权限），模型只能通过显式工具（cron_create 等）在用户可查的界面范围内操作；
开发者上传技能 / 智能体到组织库，必须经管理员 approve 才可见可装；
浏览器下载、AI 接管浏览器等动作均需权限审批或可见的接受动作。

操作哲学：AI 的每次自主行为都要有「可见的痕迹 + 可撤销的出口」。 执行详情（触发时间、开始/结束、结果、错误、对应会话）就是这张凭证。

六、Agent 可以操作世界，但是要有护栏

Agent 不只是一个「聊天框」，它可以操作浏览器、调用连接器、执行定时任务。护栏是分层的：

可见性：浏览器 AI 接管时显示遮罩页，操作日志（op log）实时记录每次导航、点击、下载；
可逆性：浏览器接管可随时「停止」，多标签可关闭，定时任务可停用/删除；
边界：下载默认 100MB 上限、导航策略受控、工具按会话生效、连接器凭据按用户隔离；
审计：服务端关键操作（授权、审批、定价、配额）全部落审计日志，与客户端的执行详情构成完整闭环。

七、固定高级呈现：一次集成，不设开关

桌面呈现没有用户可切换的模式。产品固定运行高级呈现（advanced）：在不改变上游 Web carrier 的前提下，注入桌面自有的 frame、布局、原生材质与拖动区域；Linux 无平台原生材质（Mica/hidden-inset），使用标准系统窗口边框，但布局与 macOS/Windows 一致。

启动设置变更（如本地 Web 端口）通过有序重启生效，不在运行中的 renderer 里热替换。操作哲学：高级能力是产品的默认形态而不是可选项——界面随版本只变少、不变乱，文档与截图必须跟得上每一步收敛。

八、演进而非重写

产品对现有能力的演进遵循「合并优先于新增」：

任务看板与定时任务语义重叠 → 并入定时任务（dsh-task 插件整体删除，cron 动作统一为 agent 动作）；
三个技能/Agent 入口 → 归一为能力中心；
CLI 连接器与 CLI 工具化（dws 等）→ 整体移除，改为「技能商店（SKILL.md）+ 连接器（MCP）」两种标准形态。

操作哲学：当两个入口服务同一件事时，杀掉一个，而不是加开关。 这保证了产品界面随版本只变少、不变乱；文档与截图必须跟得上这一步一步的收敛。

以上八条不是口号，而是可以在代码里逐条验证的约定。下一章起，我们将按照这个框架走查产品每个界面与操作。