# Santa 2026 接入指南

团队中控的固定网址是 [santa2026.lzhang.click](https://santa2026.lzhang.click/)。本页无需登录。打开中控或为 agent 授权时，请用加入团队仓库的 GitHub 账号。

**还在用旧地址？** `45-77-10-90.sslip.io` 的切换截止时间是 **2026 年 11 月 20 日（周五）日本时间 09:00，UTC 00:00**。请在此之前更新书签、ChatGPT 连接或上传脚本。已经收到回执的结果都已迁入新机。

## 网页和 GitHub 登录

1. 登录收到 `LZhangGJ/santa-2026` 邀请的 GitHub 账号。如果已经能打开私有仓库，可直接进行下一步。首次使用时，从邮件或 GitHub 通知接受邀请。若显示 404，先核对当前登录的账号，再请团队管理员确认受邀的用户名。[GitHub 通知](https://github.com/notifications) · [团队仓库](https://github.com/LZhangGJ/santa-2026)
2. 打开中控，选择 GitHub 登录，将新网址加入书签。通过网页交解时，打开「上传成果」，选择 CSV，提交后查看回执。[中控首页](https://santa2026.lzhang.click/) · [上传成果](https://santa2026.lzhang.click/progress)

## 连接 ChatGPT 或其他 MCP 客户端

1. 在 ChatGPT 网页版打开 **Plugins → + → Add custom MCP server**。名称填 `Santa 2026`，**Server URL** 填 `https://santa2026.lzhang.click/mcp`，认证方式选 **OAuth**。如果 ChatGPT 显示可选的 Client ID 和 Client Secret，留空即可。其他 MCP 客户端也使用这个地址和认证方式。
2. 在 ChatGPT 选择 **Create as a plugin**，安装后用登录中控的 GitHub 账号授权。在对话框输入 `@`，选中新建的 Santa 连接。[OpenAI 官方接入说明](https://developers.openai.com/api/docs/guides/custom-mcp-server)
3. 让 agent 调用 `team_status({})`。返回的 `puzzles` 是题数，`steps` 是队内已验证总步数，读到这两个值就说明连接成功。要读完整手册，调用 `read_system_guide({"lang":"zh"})`。这两项操作都是只读的。[成员手册](https://santa2026.lzhang.click/documents/system-guide)

## 用脚本上传 CSV

原有的 Santa 个人令牌在有效期内可以继续使用。需要新令牌时，在「成员与系统 → 连接 Agent 或计算节点」创建，并在运行脚本的机器上设置环境变量 `SANTA_API_TOKEN`。已有脚本只需把主机名换成 `santa2026.lzhang.click`。要先验证令牌，可用下方相同的认证头发起只读请求 `GET https://santa2026.lzhang.click/api/team_status`。[个人令牌设置](https://santa2026.lzhang.click/settings#agent-access)

准备 UTF-8 编码的 CSV，表头为 `id,program`。可以只交一道题，也可以交全部 1,000 道题。在 `submission.csv` 所在目录运行对应命令。

**macOS 或 Linux（Bash 或 zsh）**

如果当前终端还没设置令牌，运行 `read -rs SANTA_API_TOKEN && export SANTA_API_TOKEN`，粘贴令牌并按回车。

```sh
curl --fail-with-body -H "Authorization: Bearer $SANTA_API_TOKEN" \
  -F "file=@submission.csv" https://santa2026.lzhang.click/api/upload_results
```

**Windows PowerShell**

如果当前终端还没设置令牌，运行 `$env:SANTA_API_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host 'Santa token' -AsSecureString)).Password`，在提示出现时输入令牌。

```powershell
curl.exe --fail-with-body -H "Authorization: Bearer $env:SANTA_API_TOKEN" -F "file=@submission.csv" https://santa2026.lzhang.click/api/upload_results
```

打开回执中的 `receipt_url` 可看逐题结果。`saved_steps` 是相对团队原有最佳解净省的步数。成功回执中即使显示 `saved_steps: 0`，也表示已收到并验证。

## 更新计算节点

在 worker 启动命令中把中控地址设为 `https://santa2026.lzhang.click`，继续使用原来的节点名称、后端和求解程序。假设你从仓库目录启动 CPU 节点，求解程序是 `solver.py`，命令如下。

```sh
python worker.py --name my-cpu --url https://santa2026.lzhang.click -- python solver.py
```

worker 会自动上报运行状态，完成接单任务时调用 `report_run`。修改启动命令在下次启动时生效。如果正在运行的任务仍连着旧地址，并且会跨过切换时间，请在截止前把输出 CSV 或检查点保存到 worker 临时目录以外。保存好的 CSV 可以通过新网站的「上传成果」提交。

## 可以直接发给新 agent

> 请先读公开接入说明 https://santa2026.lzhang.click/start.md?lang=zh 。如果 Santa 工具还没出现，请提示我用受邀的 GitHub 账号接受 `LZhangGJ/santa-2026` 的邀请，并在客户端添加 `https://santa2026.lzhang.click/mcp`、选择 OAuth，由我授权。连接成功后，调用 `read_system_guide({"lang":"zh"})`，再调用 `team_status({})`，告诉我当前队内已验证总步数。
