Amadeus

Amadeus

基于 DeepSeek Harness 的单用户 AI 工作台，把对话、文件、编辑器与浏览器放在一起。

目录

简介 · 功能一览 · 快速开始 · noVNC AI 浏览器 · 配置 · 数据与升级 · 架构 · 开发与测试 · 文档 · 致谢

简介

DeepSeek Harness（DSH）提供了对话、文件树与预览、Web 自动化和插件体系。Amadeus 是一组 DSH 插件，补上了自托管个人工作台还缺的那些东西：写代码和论文的编辑器、能定位原文的注释、可以人工接管的 AI 浏览器、跨会话的记忆与人格，以及安全的远程访问。

所有定制都通过 DSH 公开的插件扩展点实现，不改写 DSH 本身，可以随上游版本升级。当前版本 1.3.0-alpha.1（预发布，稳定版为 1.2.0），基于 DSH 0.2.1-alpha.2；推荐用 Docker Compose 一键部署，宿主机无需安装 Node.js、code-server 或 TeX Live。

Amadeus 面向单用户自托管：登录者拥有工作区和容器终端的完整权限，不提供多用户隔离。

功能一览

• 内嵌 VS Code 编辑器：侧栏直接打开 code-server，支持文件标签、保存和 VS Code 扩展；AI 或外部改动文件后自动同步，未保存的修改给出冲突提示。
• 开箱即用的 LaTeX：镜像内置 TeX Live、XeLaTeX、latexmk、Biber、中文字体和 LaTeX Workshop，Ctrl+Alt+B 编译、Ctrl+Alt+V 预览 PDF。
• 选区注释：在对话、文档预览、编辑器或 PDF 中选中文字并写下评论，一起发给 AI；回答里引用的注释可以一键跳回原文位置，PDF 保留文件路径和页码。
• 可接管的 AI 浏览器：在侧栏实时观看 AI 操作网页。启用 noVNC 模式后，遇到登录、验证码等情况可一键接管，操作完交还给 AI 继续；每个对话拥有独立、持久的浏览器登录状态，下载的文件自动回传到工作区。
• 个性化：可自定义的 SOUL 人格、跨会话共享的 MEMORY / USER 记忆（每条记录来源会话，并保存本地 Git 历史）、个人 Skills，以及跨工作目录的历史会话检索；人格和记忆可分别开关。
• 工作区文件增强：上传文件或整个文件夹、文件夹打包下载、重名处理和带内容校验的删除确认。
• 安全的远程访问：Basic 登录配合 scrypt 密码哈希与失败节流，编辑器和浏览器画面都走同一个认证入口；单端口即可反向代理，并可安装为 PWA。
• 外观：工作台与编辑器分别设置浅色、深色或跟随系统，可收起对话区为工作台腾出空间。

对话、文件树与预览、Office 转换和 Web 自动化沿用 DSH 自带的功能，Amadeus 不重复造轮子。

快速开始

准备 Docker Engine + Compose，或使用 Linux 容器的 Docker Desktop。以下命令适用于 Bash；Windows PowerShell、WSL 和远端 Linux 的完整步骤见部署与连接教程。

git clone https://github.com/whyself/Amadeus.git
cd Amadeus
cp amadeus.docker.example.yml amadeus.local.yml
mkdir -p workspace
docker compose build

构建完成后生成登录密码哈希（终端要求输入两次密码，不回显）：

docker compose run --rm --no-deps --entrypoint node amadeus scripts/hash-password.mjs

编辑 amadeus.local.yml，修改 username，将输出的完整哈希填入 passwordHash，替换 CHANGE-ME。保留示例中的容器路径，再启动：

docker compose config --quiet
docker compose up -d
docker compose logs -f amadeus

日志出现 dsh web: 后，打开 http://127.0.0.1:3080，使用用户名和原密码登录。Ctrl+C 只退出日志查看。首次构建会下载编辑器、TeX Live 与浏览器资源，耗时取决于网络和缓存。

Compose 默认只向宿主机 127.0.0.1:3080 发布端口。远程访问必须使用 HTTPS，反向代理还需转发 WebSocket；可选择 Tailscale HTTPS 或公网域名，详见连接教程与 nginx 示例。code-server 只监听容器回环地址，由 Amadeus 的认证代理提供访问。

可选的 noVNC AI 浏览器

默认 browserUse.mode: launch 使用 Amadeus 容器内的 Chromium，用户只能查看 AI 画面。需要人工登录或操作网页时，可启用 novnc 模式：每个主会话拥有独立 Selenium Chromium 容器与 profile，用户接管后该会话的浏览器工具暂停接受操作，交还后 AI 需重新获取页面快照。

browserUse:
  enabled: true
  mode: novnc
  idleTimeoutMs: 600000
  maxInstances: 4
  userControlEnabled: true

部署时叠加 compose.novnc.yml，先拉取文档指定的固定镜像，并显式设置：

• DOCKER_GID：Docker socket 的实际组号，仅供控制器使用。
• AMADEUS_NOVNC_DATA_VOLUME：已有 /data 命名卷的实际名称，避免创建空卷。
• 自定义 DSH home 时，同步 AMADEUS_BROWSER_STATE_DIR 为对应的 <home>/browser。

services/browser-controller 是独立服务，也是该 Compose 部署中唯一挂载 docker.sock 的服务；只提供固定的浏览器启停、输入权限和屏幕操作接口。不要给运行 AI 的 Amadeus 容器挂载 Docker socket 或添加 Docker 附加组。

启用、迁移、接管、持久化与容量规则见 noVNC 浏览器说明。控制器链路已在 Docker Desktop（WSL2）上完成启动、输入权限切换、屏幕调整与停止删除的真实验收；接管 / 交还等界面交互仍需人工验收。

要在侧栏展示工作区里的开发页面或静态 HTML，见在 AI 浏览器中打开本地网页。

配置

Docker 使用 amadeus.docker.example.yml 作为模板，原生部署参考 amadeus.example.yml。私有配置不要提交到仓库。

Docker 镜像默认支持经用户批准的完全访问命令使用容器内 sudo，关闭参数及安全边界见容器内 sudo。

宿主机已安装 Node.js 24 时，也可直接运行：

npm run hash-password

旧版的明文 password 仍可使用，启动时会提示迁移；迁移后记得删掉配置备份里的明文。password 与 passwordHash 不能同时配置。

Plugins → 个性化 提供总开关和统一保存的子设置。初始化保留已有文件，记忆写入使用版本校验、租约锁与原子保存，并保留本地 Git 历史；个人 Skills 由 Agent 用普通文件工具直接编辑，管理及确认开关是行为指导，不是文件权限。用法及事实快照规则见个性化插件。

数据与升级

amadeus-data 是 Compose 卷键，实际卷名通常带项目前缀。升级时保持同一项目目录或 COMPOSE_PROJECT_NAME，沿用原配置、工作区、持久化 HOME 与数据卷；自定义个性化目录也需备份。

• 升级前备份，升级时不删卷。不要执行 docker compose down -v。 普通 docker compose down 会保留命名卷。
• 从已提交代码构建镜像，记录源码 commit 和镜像标签，保留上一镜像用于回滚。归档构建约定为 git archive HEAD | docker build -t amadeus:<主题>-<10 位提交哈希> -，部署时确保 Compose 使用对应镜像。
• 旧容器 HOME 未挂载时，先按部署教程备份和迁移，再启用挂载；历史会话中的 Windows 绝对路径不会自动转换为容器路径。
• 从旧浏览器模式切换为 noVNC 不会自动导入旧 profile；控制器部署复用已有 /data 卷，迁移步骤见 noVNC 文档。

架构

开发与测试

使用 Node.js 24 与 npm workspaces，遵守 AGENTS.md。原生开发还需配置固定版本的 code-server 4.104.2、LaTeX Workshop 10.9.0 和 Bridge，并应用两项编辑器补丁；详细步骤见部署教程。

npm ci
npm test
npm run build
npm start

npm test 执行 node --test tests/*.test.mjs；行为改动需单元测试。涉及界面或浏览器交互时，还需运行对应真实浏览器脚本：

npm run test:files-browser
npm run test:annotations-browser
npm run test:browser-compat

个性化 Web 验收先运行 node tests/personalization-web-host.mjs，再把输出的 origin 设为 AMADEUS_TEST_ORIGIN 运行 node tests/personalization-web-live.mjs。其余浏览器与编辑器测试入口见 package.json。

npm run pack:plugins 会把插件归档和 SHA256SUMS 输出到 .release/。

文档

• 部署与连接教程：Docker、WSL、远端 Linux、HTTPS、备份与排查。
• noVNC AI 浏览器：控制器、接管 / 交还、容量、迁移与验收边界。
• 个性化插件：当前实现、设置、文件与快照机制。
• 客户端兼容说明：注释与原生客户端行为差异。
• 个性化计划初稿与记忆来源和浏览器容量规则：需求依据；待设计项不代表已实现。
• CHANGELOG、上游记录与v1.2.0 发布审计：变更与历史来源；当前依赖以 package.json 和 lock 文件为准。

致谢

• DeepSeek Harness：Amadeus 运行其上的工作台与插件体系。
• code-server、LaTeX Workshop、noVNC、Selenium 等上游项目。

第三方组件按各自的许可证分发，声明随对应目录保留（例如 packages/browser/NOTICE.md、packages/session-query-global/NOTICE.md 和 third-party/）。依赖来源见 UPSTREAMS.md，贡献者见 CONTRIBUTORS.md。