AlphaTown DGX Spark 版（Linux ARM64）· 使用说明

一、这是什么
AlphaTown 是 A 股 AI 投研智能体。这个版本是给 NVIDIA DGX Spark 准备的免安装包（Linux ARM64 终端版）：自带 Python 3.13 和全部依赖，
解压就能用，不用联网安装，也不需要管理员权限。AlphaTown 本身不用 GPU，GPU 留给你在 Spark 上运行的本地模型。

二、系统要求
· NVIDIA DGX Spark，系统为 DGX OS（Ubuntu 24.04，ARM64）。
· 其他 ARM64 Linux 未测试。x86 电脑、Mac 和 Windows 不能用这个包。
· 一个普通用户账号即可。在 Spark 自己的桌面上用浏览器打开，或者从另一台电脑经 SSH 隧道打开（见第四节）。

三、启动
1. 把两个文件放到 Spark 上的同一个文件夹，例如 ~/alphatown：
   AlphaTown-0.3.0-linux-arm64.tar.gz 和 AlphaTown-0.3.0-linux-arm64.SHA256SUMS。
   在 Spark 上打开终端（桌面上的「终端」，或者从别的电脑 SSH 登录），先校验：
     cd ~/alphatown && sha256sum -c AlphaTown-0.3.0-linux-arm64.SHA256SUMS
   显示「AlphaTown-0.3.0-linux-arm64.tar.gz: OK」才继续，否则请重新下载。
2. 解压。一定要在 Spark 上用 tar 解压，不要在 Mac 或 Windows 上解压后再复制过来（那样会丢掉运行权限）：
     tar -xzf AlphaTown-0.3.0-linux-arm64.tar.gz
   文件夹所在的路径里不要有空格。
3. 启动：
     cd ~/alphatown/AlphaTown-0.3.0-linux-arm64 && ./start.sh
   第一次启动要等一会儿。在 Spark 自己的桌面上会自动打开浏览器并登录；从别的电脑 SSH 登录时，终端里会显示
   在你电脑上要执行的那一行命令（见第四节）。
   访问令牌默认开启（见第四节末尾）。Spark 桌面上自动打开的浏览器会直接登录；给别的电脑用的地址
   结尾是 #login=…，这是一次性登录地址，在浏览器里打开就自动登录，30 分钟内有效，只能用一次。
   在终端里按 Ctrl+C 退出。想关掉终端也一直运行、开机自动启动，见第五节。

四、从另一台电脑打开（SSH 隧道）
AlphaTown 默认只在 Spark 的本机地址上监听，别的电脑通过 SSH 隧道打开，传输经过 SSH 加密。
1. 在你自己的电脑上打开终端（Mac 用「终端」，Windows 10 / 11 用 PowerShell，都自带 ssh），执行：
     ssh -N -L 8858:127.0.0.1:8848 你的用户名@Spark的IP地址
   「你的用户名」是你登录 Spark 用的账号名，「Spark的IP地址」例如 192.168.1.50。
   start.sh 启动时会显示已经填好的这一行，直接复制即可。
   输入密码后没有任何输出，就是连上了。用 AlphaTown 期间不要关这个窗口；按 Ctrl+C 断开。
2. 在这台电脑的浏览器里打开终端里显示的一次性登录地址 http://localhost:8858/#login=…
   这个浏览器登录过以后，直接打开 http://localhost:8858 即可。
· 用 8858 是为了不和你电脑上自己运行的 AlphaTown（8848）冲突。地址请写 localhost，不要写 127.0.0.1：
  两个 AlphaTown 都设了访问令牌时，浏览器会把同一地址上的令牌混在一起。
· 访问令牌默认开启。这台 Spark 上别人的账号也连得到本机地址，有了令牌，他们打不开你的 AlphaTown。
  令牌在第一次启动时自动生成，保存在数据目录里的 access_token 文件中（只有你的账号能读），升级后照常沿用。
  换浏览器、换电脑或登录地址过期了，在程序文件夹里运行 ./start.sh --token：它显示访问令牌和一个新的
  一次性登录地址（给别的电脑用），不会再启动一个 AlphaTown。网页提示「需要访问令牌」时，粘贴访问令牌即可。
  在 Spark 自己的桌面上，不带参数运行 ./start.sh 会打开浏览器并直接登录，AlphaTown 已在运行时也一样。
  一次性登录地址不要在 Spark 本机的浏览器里打开：同一台机器上的其他账号能看到打开它的那条命令。
  令牌输错多次会被暂时限制尝试，从 Spark 本机连接也一样；带着正确令牌的连接不受影响。
  想用自己定的令牌，在 app/.env 里设置 APP_ACCESS_TOKEN；只有你一个人用这台 Spark、确实不想要令牌时，
  在 app/.env 里加一行 ALPHATOWN_AUTO_TOKEN=0。改完都要重启 AlphaTown。共享的 Spark 上不要关。

五、开机自动启动（后台服务）
在程序文件夹里运行一次：
  ./install-service.sh
它把 AlphaTown 装成你这个用户的后台服务（systemd --user），不需要管理员权限：关掉终端也一直运行，出错了会自动重启。
装好后会显示怎么打开（给别的电脑用的一次性登录地址）和常用命令。在 Spark 桌面上打开：在程序文件夹里运行 ./start.sh，
它发现后台服务已在运行，会直接打开浏览器并登录。
  ./start.sh --token                      查看访问令牌，获取新的一次性登录地址
  systemctl --user status alphatown       查看是否在运行
  journalctl --user -u alphatown -f       查看运行日志（按 Ctrl+C 退出查看）
  systemctl --user restart alphatown      重启（改了 app/.env 以后）
  systemctl --user stop alphatown         停止
要让它在你退出登录后继续运行、Spark 开机后自动启动，还要执行一次：
  loginctl enable-linger
提示没有权限时改用 sudo loginctl enable-linger 你的用户名，然后输入你的登录密码。
· 装了后台服务以后不用再运行 ./start.sh；再运行它只会显示「AlphaTown 已在运行」和访问方法。
· 把程序文件夹挪到别处以后，要在新位置重新运行一次 ./install-service.sh。
· 后台服务的端口和数据目录记在服务里，改 app/.env 里的 ALPHATOWN_PORT、ALPHATOWN_DATA_DIR 不起作用。
  要换，用 ./install-service.sh --port 8849 或 ./install-service.sh --data-dir 新目录（见第八节）。

六、接入模型
点页面左下角的模型卡片，打开「选择模型」：
· Spark 上的 Ollama：点「本地 Ollama」就能用（先用 ollama list 确认模型已经下载）。Spark 有 128 GB 统一内存，
  推荐 ollama pull qwen3.8:27b；对话和圆桌都要调用工具，请选支持工具调用的模型。
· llama.cpp（llama-server）、vLLM 等兼容 OpenAI 格式的服务：点「自定义」，「接口地址（Base URL）」填到 /v1 为止，
  例如 vLLM 常用 http://127.0.0.1:8000/v1，llama-server 常用 http://127.0.0.1:8080/v1；「模型 ID」填服务里的模型名，
  再点「测试连接」→「使用此模型」。
· API Key：服务在本机或内网 IP 地址上时可以不填。启动服务时加了 --api-key 的，把同一个 Key 填进「API Key」框。
· 另一台机器上的模型（例如第二台 Spark）：接口地址请写 IP 地址，例如 http://192.168.1.50:8000/v1。
  写主机名会被当成云端接口：必须填 API Key，还会走系统代理。
· 对话 Agent 要靠工具调用查数据：vLLM 启动时加 --enable-auto-tool-choice 和与模型对应的 --tool-call-parser；
  llama-server 加 --jinja。
· 云端模型（DeepSeek、Claude 等，默认是 DeepSeek）也在「选择模型」里选，粘贴 Key 即可。
· 证据模式：Linux 版的机构圆桌和主题深度研究默认用证据模式（同样的席位和数据卡，只给证据、各维度评分、多空论据与风险，
  不出评级、目标价、交易计划和仓位），发起时可以在「输出」里改选「完整结论」或「完整报告」。要改默认值，在 app/.env 里加一行
  RESEARCH_EVIDENCE_DEFAULT=off（或 on）再重启。经 MCP 调用的深度研究始终是证据模式。

七、首次激活
第一次打开会显示「激活 AlphaTown」：粘贴发行方提供的授权码（ATL1. 开头的一整段）即可。
授权码只限本人使用，请不要转给别人。

八、数据在哪里、怎么备份和升级
· 自选、报告、对话、设置、API Key、授权和访问令牌都保存在 ~/.local/share/AlphaTown，和程序文件夹是分开的。
  「设置」页的「数据目录」一行显示的就是它。以前在这台 Spark 上装过 AlphaTown 后台服务的，
  start.sh 和 install-service.sh 会沿用那个服务的数据目录，启动时会显示出来。
· 备份：先停掉 AlphaTown（前台运行的按 Ctrl+C；后台服务运行 systemctl --user stop alphatown），
  把整个数据文件夹复制到安全的地方，再启动。里面有 API Key，请妥善保管备份。
· 换数据目录：前台运行用 ALPHATOWN_DATA_DIR=~/alphatown/data ./start.sh；
  后台服务用 ./install-service.sh --data-dir ~/alphatown/data。不要放在程序文件夹里，升级删旧文件夹时会一起删掉。
· 升级：没有自动更新（从 0.1.0 升级也一样）。下载新版本，按第三节校验，解压到旧版本旁边；在新文件夹里运行 ./install-service.sh
  （只在前台用的，运行新文件夹里的 ./start.sh），确认能打开以后再删掉旧文件夹。数据和授权不受影响。
  改过 app/.env 的，把它复制到新文件夹的 app/ 里。

九、已知限制
· 只在一台 DGX Spark（DGX OS / Ubuntu 24.04 ARM64）上验证过，其他 ARM64 Linux 未测试。
· 代码隔离：macOS 上，策略代码和 python_exec 除了 Python 层的限制（AST 白名单、运行时审计、资源限制），还有一层
  系统强制的 sandbox-exec（禁止联网、只能写任务目录）。Linux 上没有 sandbox-exec，只有 Python 层的限制。
  所以对话 Agent 自由运行 Python 代码的工具（python_exec）默认关闭；确实需要时，在 app/.env 里加一行
  ALPHATOWN_SANDBOX_PYTHON_EXEC=1 再重启，请只在你自己用的 Spark 上开。
  python_exec 关着，Agent 自己写的策略代码也照常运行：对话里 Agent 调用回测、参数优化、轮动和策略信号工具时
  可以附上策略代码，运行前不需要你确认，同样只受 Python 层的限制；经 MCP 接入的 AI 客户端调用这些工具也一样。
  策略工作室「AI 生成」的试运行和模型实验室的测评，跑的也是模型写的代码。
  别人给的策略代码，请先读一遍再回测或托管。改成局域网直连时一定要设访问令牌 APP_ACCESS_TOKEN。
· 识图（OCR）：扫描版 PDF 不能识别文字；截图里的文字只有当前模型选 Claude 时才能识别，其他情况请粘贴文字。
  HEIC 照片请先转成 JPG 或 PNG；旧版 Word 文档（.doc）请先另存为 .docx。
· 导出 PDF 的字体：Spark 自带的 Noto CJK 中文字体不能嵌入 PDF，AlphaTown 会自动改用系统里能嵌入的字体，不用另装：
  研报 PDF 用 Droid Sans Fallback（中文）加 DejaVu Sans（英文、数字和符号），资料研究 PDF 用 AR PL UMing（宋体风格）。
  这两款中文字体都没有粗体：研报的标题、表头和封面靠颜色和字号区分，其中的英文也不加粗，正文里加粗的数字和
  红绿涨跌数字照常加粗；资料研究 PDF 全文不加粗。导出 Markdown、HTML 不受影响。
  想让两种 PDF 都用黑体，可以换成文泉驿微米黑（它也没有粗体，换用后全文不加粗）。
  有 sudo 时运行 sudo apt install fonts-wqy-microhei；没有 sudo 时先运行：
    cd /tmp && apt-get download fonts-wqy-microhei && dpkg -x fonts-wqy-microhei_*.deb ~/.local/share/fonts/wqy
  再在程序文件夹的 app/.env 里加一行（Spark 上已经有能用的字体，不加这一行，AlphaTown 不会改用解压出来的字体）：
    REPORT_FONT_PATH=~/.local/share/fonts/wqy/usr/share/fonts/truetype/wqy/wqy-microhei.ttc
  两种做法都要重启 AlphaTown 才生效。REPORT_FONT_PATH 指定两种 PDF 优先使用的中文 TrueType 字体文件（.ttf / .ttc）；
  研报 PDF 想要中文粗体，要自备带粗体的中文 TrueType 字体，用 REPORT_FONT_PATH 和 REPORT_FONT_BOLD_PATH 分别指定
  常规体和粗体。
· 模型实验室：GB10 的模型可用内存按统一内存约 80% 估算，能放下多大的模型以 Ollama 实际加载的结果为准。
  Ollama 在 Linux 上把日志写进系统日志，模型实验室读不到，部分数字只能按估算显示。「NVIDIA CUDA 生态接入」里的
  pip install 命令是给 x86 GPU 服务器写的；在 Spark 上运行 vLLM、TensorRT-LLM 请用 NVIDIA NGC 为 DGX Spark 构建的容器。
  Ollama 是用 snap 装的（snap list ollama 能列出它）时，加速建议按 snap 版给出升级（snap refresh）和重启命令；
  不要用 Ollama 官网的安装脚本升级，那样会再装一个 Ollama 服务，和 snap 版抢 11434 端口。
  调整 Ollama 设置的建议只给出查看方法（snap info ollama），能设哪些项以 snap 自己的说明为准。
· 内网模型的接口地址请写 IP 地址，不要写主机名（见第六节）。
· 数据工作室的「本机文件夹」不能选家目录下以 . 开头的隐藏文件夹（如 ~/.config、~/.mozilla）和 ~/snap，
  也不能选 /proc、/sys、/dev、/boot、/root、/var、/tmp、/snap：这些地方存着设置、密钥和浏览器资料。
  NAS 共享和 U 盘在 /media、/mnt、/run/user/<uid>/gvfs 下，可以正常使用。
· 后台服务只在本机地址上监听，别的电脑请用 SSH 隧道（见第四节）。在终端里运行、改成局域网直连并用 IP 地址打开时，
  浏览器不允许网页直接写剪贴板，个别「复制」按钮会提示手动复制。
· MCP：「知识库与集成」页「MCP 服务」卡片里 Claude Desktop 的配置路径是 macOS 的；在 Spark 上请用
  「Claude Code 命令行」那一项接入。
· 页面里的「帮助」（用户手册）其他章节按 macOS 写成：⌘ 在 Spark 上换成 Ctrl；提到「访达」和 /Volumes 的地方，
  在 Spark 上对应「文件」应用和 /media、/run/user/<uid>/gvfs。DGX Spark 的内容在手册 1.8。
· 没有自动更新。程序没有数字签名：请用随包的 SHA256SUMS 校验下载的文件。

十、卸载
1. 装过后台服务的，先在程序文件夹里运行 ./uninstall-service.sh（只卸载服务，不删除数据）。
2. 删掉程序文件夹。
3. 数据在 ~/.local/share/AlphaTown（或你换过的数据目录），确定不要了再自己删除：
   里面有你的报告、对话、API Key 和授权。

十一、遇到问题
· 后台服务的日志：journalctl --user -u alphatown -n 100
· 检查程序文件是否完整：在程序文件夹里运行 sha256sum -c --quiet SHA256SUMS（没有输出就是完好的）。
· 需要帮助时，把终端里显示的文字复制下来发给我们。
