中文 · English
小丑鱼是一款本机优先、带长期记忆、能够真实执行任务的 AI 工作应用。用户只需要描述目标；小丑鱼负责选择能力、调用专业执行单元、处理文件或启动编程引擎，并把过程、修改和结果留在同一个任务中。
本版本完成了能力真实质量验收，并统一应用、桌面壳、清单和文档版本。23 项内置能力均有真实执行路径；复杂能力拥有独立超时和结构修复边界；设置中心提供与当前版本绑定的隐私协议入口。
| 入口 | 用户操作 | 交付结果 |
|---|---|---|
| 任务 | 直接说明想完成的事情，可附加图片和文件 | 可继续的任务记录、自动标题、执行进度与结果 |
| 能力 | 自动选择或直接启动专门能力 | 研究、文档、演示、分析、设计等结构化成果 |
| 文件 | 打开常见办公文件，转换后编辑、处理和导出 | 原文件、可编辑副本、版本记录与新导出文件 |
| 开发 | 关联或新建本地项目，用自然语言提出开发要求 | 真实代码修改、检查结果、提案、回滚与运行历史 |
| 自动化 | 管理需要重复执行的任务 | 可暂停、编辑、立即执行的计划任务 |
| 设置 | 配置模型、开发引擎、连接器和数据保存 | 加密配置、连接状态与本地/自托管保存方式 |
这些入口共享任务、附件、决定和产物编号。任务转交给能力时会携带完整原文、提炼后的上下文、附件和已有决定，不会只传最后一句话。
新任务支持三种方式：
- 直接聊聊：问答、讨论和临时处理；
- 完成任务：围绕明确结果持续推进，可在后台并行执行；
- 学习辅导：使用讲解、追问、练习和反馈帮助理解。
小丑鱼是统一的用户入口。专家不是需要配置或一对一聊天的角色，而是按本轮任务动态选择的内部执行单元；任务变化时，参与的专业判断也会重新选择。最终结果始终由小丑鱼整合和交付。
任务运行保留检查点、取消、失败原因、重试入口和交付回执。运行完成与结果送达分开记录，刷新或重启不会把未送达结果误标为完成。
当前内置 23 项能力，主要分为：
- 研究与核验：深度研究、信息源发现、决策辅助、市场资料简报；
- 办公与内容：文档稿、文档转换、OCR、会议纪要、文章润色、HTML 报告；
- 演示与设计：演示文稿、产品设计、图片提示词反推；
- 工作与商业：任务工作台、群聊进展、流程搭建、商务推进、市场机会模拟；
- 开发与扩展：开发项目、生成新能力。
能力页默认展示全部常用能力。用户也可以先输入目标，让系统自动选择。能力之间可以连续流转，仍沿用原任务及其完整上下文。
底层采用统一能力注册表：工具负责一次真实操作，能力负责完整做事流程，开发引擎负责项目修改，服务提供方负责模型、搜索、语音和图像等外部连接。任务、学习辅导、能力、文件、开发和工作六个入口只组合自己需要的工具，并共享就绪检查；MCP 与其他扩展保留独立生命周期，只在请求命中时加载。界面可以直接说明某项能力是否可用以及缺少什么配置。
工具状态会区分“可直接调用”和“由产品流程承接”，不会把只有提示词的能力冒充成独立工具。直接调用会保存工具来源、开始与完成时间、耗时及结果截断状态，过长结果会明确提示缩小范围。
设置中心还提供四组按需安装的能力插件：微软官方 Playwright MCP 浏览器、安全 CSV/JSON 分析、EML/ICS 文件整理，以及通过用户自有 OpenAI 兼容端点生成图像和视频。数据分析与 EML/ICS 整理完全在本机运行；浏览器需要本机 Chrome；图像和视频生成需要用户自己的媒体 API。安装前会显示权限和依赖，媒体密钥只从本机环境变量读取。
实时价格、余票、房态和订座等数据只有在可靠实时来源实际返回时才会标记为已确认；目前不内置动车、航班、酒店和餐馆的实时交易适配器。
支持 Word、PowerPoint、Excel、PDF、OpenDocument、RTF、EPUB、CSV、TXT 和 Markdown。
文件处理遵循一个清楚的边界：原文件保留，转换成可编辑副本，导出时生成新文件。
- Word 保留标题、段落、空行、连续空格、缩进、编号、表格和段落对齐等可转换结构；
- PDF 通过 AnyDoc 转换为可编辑 Markdown 副本，扫描版仍需要 OCR；
- PowerPoint 按页保留文字、表格和讲者备注；Excel 按工作表保留表格；
- TXT 与 Markdown 可在明确授权且通过冲突检查后写回原文件；
- 其他格式不覆盖原件，并显示转换变化和已知限制；
- 支持自动保存、版本比较、恢复、垃圾桶和独立导出；
- 可导出 DOCX、PDF、PPTX、XLSX、HTML 和 Markdown。
复杂浮动对象、批注、跨节页眉页脚、公式、图表、演示母版和电子表格公式仍由原文件或桌面 Office/WPS 保真承接。
开发是独立一级入口，交互面向普通用户，实际执行交给选中的编程引擎。
- 默认使用 Pi Agent 0.84.2；
- 可切换 DeepSeek Harness、Kilo Code、OpenCode、Codex；
- 五个引擎使用统一插件契约，各自保留独立适配器和真实能力边界；
- Pi 使用原生事件和持久会话；外部 CLI 以增量事件统一显示，并在支持时恢复原生会话；
- 新项目建立在受管默认目录；任务中提供已有目录时直接关联外部项目；
- 上下文面板可自动选择相关代码，也可明确加入文件和当前 Git 差异；
- 运行过程统一显示上下文、工具调用、检查、待确认修改和完成状态；
- 支持项目归档、版本比较、逐文件审阅、选择性写入和安全回滚。
权限模式按引擎真实能力展示。常规修改优先在隔离工作区形成提案；Codex 的“完全控制”会在用户明确选择后直接修改当前项目。
服务启动时会只读检查五个引擎的 npm 发布版本：
- 比较版本跨度、命令入口和 Node.js 要求；
- 兼容信号正常时提示可升级；
- 主版本、0.x 次版本、发布通道、命令入口或运行环境变化时显示风险警告；
- 只有用户确认后才安装；
- 安装后运行项目构建和对应引擎测试；失败则恢复升级前依赖。
升级不会静默发生。成功后需要重启小丑鱼，所有升级操作都会留下审计记录。
记忆内核来自独立依赖 @nemos/sdk，本仓库不保留重复副本。
- 用户事实、角色自身内容和任务上下文分开保存，避免身份互换；
- 普通任务只召回当前问题需要的内容；
- 能力可以只采用文笔、排版和格式等少量交付习惯，也可单次关闭；
- 当前任务的明确要求始终高于历史偏好；
- 记忆页只展示用户可理解的分类内容，不暴露内部原始归档。
模型设置支持智谱 GLM、OpenAI、Anthropic Claude、DeepSeek、通义千问、MiniMax 和自定义 OpenAI/Anthropic 兼容服务。日常请求可使用轻量模型，复杂任务和能力使用主任务模型。Windows 下密钥使用当前用户的 DPAPI 加密，接口不会回显完整密钥。
默认数据目录为 ~/.clownfish。默认纯本地保存；也可以连接仓库提供的 Docker 同步服务。客户端使用 AES-256-GCM 加密快照，服务器只保存密文，本机仍是工作副本。
$env:CLOWNFISH_SYNC_TOKEN="请替换为至少24位随机令牌"
docker compose up -d --build本机服务可使用 http://127.0.0.1:8799，远程部署必须使用 HTTPS。
截至 2026-08-17：
- 构建和类型检查通过；
- 483 项自动化测试：482 项通过，1 项因本机缺少 Blender 跳过；
- 五个开发引擎均有真实 CLI/SDK 适配与就绪检查；
- Pi Agent 已升级到 0.84.2，升级后构建和引擎专项测试通过；
- 官方 Playwright MCP 已完成真实进程发现；媒体连接器完成本机模拟 API 的生成、查询和下载闭环；
- 文档转换、Office 导出、开发隔离、提案写入、回滚、任务恢复和加密同步均有自动化验证。
测试证明具体代码路径工作，不等于所有外部模型账号、实时数据源或复杂 Office 版式都已人工核验。
需要 Node.js 22.19 或更高版本。
cd sdk\typescript
npm install
npm run companion打开 http://localhost:8787。使用 PORT 修改端口，使用 CLOWNFISH_HOME 修改数据目录。
cd sdk\typescript
powershell -NoProfile -ExecutionPolicy Bypass -File examples\companion\client\Build-Clownfish.ps1输出目录：examples\companion\client\dist\portable\小丑鱼。
| 文档 | 用途 |
|---|---|
| 应用使用与运维说明 | 页面、数据、接口、开发引擎与桌面构建 |
| TypeScript 接入层 | Agent 运行时导出与记忆 API |
| 记忆架构 | 当前实现结构和边界 |
| Agent 运行架构 | 任务、工具、权限与恢复 |
| 文档导航 | 全部公开文档入口 |
| 安全策略 | 漏洞报告方式 |
| 隐私协议 | 本机数据、外部服务、同步、导出与删除边界 |
以 LICENSING.md 为准：
- TypeScript 接入层、Agent 运行时与公开研究资料采用 PolyForm Noncommercial 1.0.0；
- 独立记忆内核
@nemos/sdk以其仓库许可证为准； - 小丑鱼应用
sdk/typescript/examples/companion/保留全部权利，见其单独声明； - 随包分发的开源组件、版本与许可证见第三方软件声明。
严格来说，本仓库整体不是单一 OSI 开源许可证项目：接入层是非商业源码开放，小丑鱼应用另行授权，第三方组件继续适用各自的开源或软件许可条款。