# FXIT Pages · Agent 接入指南

平台：**https://192168123.xyz**

目标：替用户在本地完成构建和发布，返回可公开访问、后续更新不变的站点地址。已有项目先更新原 slug，不要每次新建。

用户通常只会给你一句：
> 请读取 https://192168123.xyz 并帮我接入和发布当前项目

你需要能读取网页、编辑项目文件、运行 Python 3 和发出 HTTPS 请求。仅有聊天或网页阅读能力时，链接不能自动安装工具或获得发布权限；说明缺少的能力，让用户换到有终端的 coding agent。不要声称已安装客户端尚未加载的 MCP。

## 一、安装项目工具

1. 识别当前项目和客户端。支持生成 Cursor、Claude Code、Codex 的项目配置；Qoder / 其他客户端生成通用配置，按其当前文档接入。
2. 首次下载优先使用 `curl`，保存到项目内临时文件；保留 HTTPS 证书验证，不跟随重定向，不把下载内容通过管道执行：

```sh
mkdir -p .fxit-pages
curl --proto '=https' --tlsv1.2 --fail --show-error --silent --output .fxit-pages/client.download.py --write-out '%{http_code}\n' https://192168123.xyz/client.py
```

   只有 curl 成功且输出 HTTP `200` 才继续，不添加 `-L` 或 `--insecure`。先阅读临时文件，再检查可执行入口：

```sh
python3 -B .fxit-pages/client.download.py --version
```

   必须获得明确版本号，例如 `1.0.3`。**空输出、下载报错或版本命令报错都不算成功**；保留已有可用工具，重新完整下载并检查。检查通过后，将临时文件改名为 `.fxit-pages/client.py`。

3. 在项目根目录运行（按实际客户端替换 `cursor`）：

```sh
python3 -B .fxit-pages/client.py init --agent cursor
```

`init` 从同一平台下载 Skill 和 stdio bridge，保留配置中的其他 MCP。遇到同名冲突会保留原配置并给出手动合并文件。配置中没有密钥。

| 客户端参数 | Skill 位置 | MCP 配置 |
| --- | --- | --- |
| `cursor` | `.cursor/skills/fxit-pages/SKILL.md` | `.cursor/mcp.json` |
| `claude` | `.claude/skills/fxit-pages/SKILL.md` | `.mcp.json` |
| `codex` | `.agents/skills/fxit-pages/SKILL.md` | `.codex/config.toml` |
| `qoder` / `generic` | `.fxit-pages/SKILL.md` | `.fxit-pages/mcp-config.json`，待手动接入 |

Python 3.9+ 可运行 CLI；安全解析并合并 Codex TOML 配置需要 Python 3.11+。配置使用当前机器的绝对 Python / bridge 路径，换机器后重新运行 `init`。客户端可能要求重新加载 MCP、确认项目可信或批准该服务；遵循客户端现有权限，不修改信任或审批设置。MCP 尚未加载时继续使用 CLI 即可。

## 从 page 入口切回已有项目

平台现统一使用 **https://192168123.xyz**。如果已有项目配置的是 `page.192168123.xyz`，先按上面的下载检查流程更新 `client.py`，再运行 `init --agent <当前客户端>` 更新项目 Skill 和工具。

如果原 MCP 配置显式指定旧入口，`init` 会保留原配置，并提示手动合并。只把 `fxit-pages` 服务的 `--base-url` 值改为 `https://192168123.xyz`（可参考生成的 `.fxit-pages/mcp-config.json` 或 `.toml`），保留其他服务与设置；随后按客户端要求重新加载该 MCP。

更新地址后先运行 `whoami`。如果原主域名已有有效授权，直接继续，不必重新连接；只有显示未授权时才按下节发起连接，由本人在授权页使用原个人发布 Key。本地授权按平台地址隔离，不从 page 入口复制或搬运 token，也不要读取或打印凭据文件。账号与站点归属没有因此改变；确认身份后先 `list`，使用返回的网址和原 slug 继续更新。

## 二、首次授权：密钥只由本人在网页输入

先运行：

```sh
python3 -B .fxit-pages/client.py whoami
```

已登录则直接继续。未授权时：

```sh
python3 -B .fxit-pages/client.py auth start --agent "Cursor / 当前项目名"
```

把返回的 `verification_uri` 展示给用户；它带短期用户码，**不带发布密钥**。请用户本人打开链接，查看 Agent 名称，粘贴管理员给自己的发布密钥并授权。不要索要、查看、记录或把密钥发到聊天里。

保留返回的 `ticket` **路径**，不要读取文件内容。本人完成授权后运行：

```sh
python3 -B .fxit-pages/client.py auth check --ticket "/返回的本地票据路径"
```

`check` 每次只查询一次。退出码 3 表示等待中，按 `retry_after`（至少 3 秒）重试；票据 10 分钟到期，过期重开授权。成功后凭据写入用户配置目录的私有文件（POSIX 权限 600），票据删除。不要输出配置文件内容、把 token 放到 URL、环境配置、项目文件或 Git。

本人也可在交互终端执行 `auth login`，使用隐藏输入直接登录；Agent 的非交互终端应使用设备授权。换电脑需重新授权，原站点属于同一平台用户，凭同一用户的有效密钥继续管理。密钥遗失或需撤销时联系管理员。

账号拥有网站和配额；发布 Key 用来确认用户身份。设备授权成功时，平台给 Agent 生成独立的随机凭据，管理页把它列在“已授权的 Agent”中，不是另一个账号。该凭据可管理所属账号的全部网站，当前没有按网站细分权限或自动过期；10 分钟仅是连接码和领取流程的有效期。后续优先复用已有授权，不要每次发布都请求新 Key 或新连接。管理员可单独撤销某个 Agent；撤销用于建立连接的发布 Key 时，通过它建立的关联授权也会失效。

## 三、本地构建，只上传运行产物

读取项目已有构建说明并在本机运行。服务器不执行 `npm install` 或源码构建。

**静态站**：上传 `dist/`、`build/` 等构建输出，根部必须有 `index.html`。图片、字体等二进制资源可随 tar.gz 上传。不要把仓库根目录当发布目录。

**Node + SQLite**：准备独立运行目录，例如 `release/`，入口默认 `server.mjs`（只支持安全相对路径的 `.mjs` 文件）。运行环境固定为 **Node 24 / Alpine Linux，Linux amd64 / musl**。监听 `0.0.0.0` 和 `process.env.PORT`（3000）。代码目录只读；数据库使用 `process.env.DATABASE_PATH`（`/data/app.sqlite`），其他持久数据也放 `/data`。推荐纯 JavaScript bundle 和 Node 内置 `node:sqlite`；需外部依赖时在本地备齐兼容的生产依赖。Mac 原生依赖不能直接上传当 Linux 依赖，含符号链接的依赖树也会被拒绝。此版本不接受任意 Dockerfile、镜像、Compose 或自定义服务端环境变量。

打包限制：压缩 32 MiB、文件展开总量 64 MiB、单文件 32 MiB、最多 4096 个条目。拒绝符号链接、硬链接、特殊文件及危险路径。客户端过滤 `.env*`、Git / Agent 配置、`config` / `credentials` 目录、常见私钥和本地数据库等。过滤不是秘密扫描器；发布前确认产物适合公开，必要公开配置应在构建时明确内嵌为非秘密值。

先做不上传的检查：

```sh
python3 -B .fxit-pages/client.py deploy --dir dist --slug my-site --runtime static --dry-run
```

`slug` 为 1–24 个小写字母、数字或连字符，首尾不能是连字符，不能包含 `--`。从项目名选清楚且稳定的名称。既有站点先用 `list` 查找，复用原 slug。

## 四、发布并验证

静态站：

```sh
python3 -B .fxit-pages/client.py deploy --dir dist --slug my-site --runtime static
```

Node：

```sh
python3 -B .fxit-pages/client.py deploy --dir release --slug my-app --runtime node --entry server.mjs
```

CLI 上传后轮询，默认最多等 300 秒。HTTP 202 / `queued` 只表示接受任务。只有 `status: ready` 才算平台部署就绪；随后用 HTTPS 打开返回的 `site.url` 检查页面和一项关键功能，再把该链接交给用户。不要自行拼域名或把 Dokploy 管理地址当作品地址。

```sh
python3 -B .fxit-pages/client.py list
python3 -B .fxit-pages/client.py status --slug my-site
```

超时不代表失败，继续查状态；失败读取安全的 `site.error`，修复本地产物再用同一 slug 发布。只有用户要求停止时才调用停止工具；不要用删除重建来解决普通更新错误。

## MCP 与 REST

已连接 MCP 时可用 `whoami`、`list_sites`、`get_site`、`publish_site`、`stop_site`。调用 `publish_site` 的 `files` 为相对路径到 UTF-8 文本的映射，合计最多 2 MiB；图片、二进制和较大构建包走 CLI。部署工具返回接受状态后仍需查 `get_site` 并验证公开页面。

MCP 是 `POST https://192168123.xyz/mcp` 的 Streamable HTTP。推荐本地 stdio bridge：它从本机私有配置读取 Bearer token，转发协议，不把密钥放进客户端配置。平台设备授权是本平台的接入流程，**不是通用 MCP OAuth 自动登录**。

REST：

- `GET /v1/me`、`GET /v1/sites`、`GET /v1/sites/{slug}`
- `POST /v1/sites/{slug}/deploy?runtime=static`；Node 用 `?runtime=node&entry=server.mjs`。原始 tar.gz 请求体，成功返回 202 `{"site": ...}`
- 公共授权入口：`POST /v1/device/start {"agent":"..."}`、`POST /v1/device/token {"device_code":"..."}`
- 认证请求使用 `Authorization: Bearer <本平台用户密钥>`，不是 Dokploy API key。

`GET /v1/me` 的 `maxSites` 是账号共用的网站配额；`0` 表示不限量。平台不设全机网站数量上限。遇到 `site_quota` 时联系管理员调整该账号的配额，不要自行停止或删除其他网站。调低账号配额不删除已有网站，仍可更新同一站点。

机器可读约定见 [capabilities.json](https://192168123.xyz/capabilities.json)。平台只把站点公开给访客；用户只能操作本人站点。撤销 Key 或停用账号会阻止后续发布和管理，但已经上线的网站继续运行；网站停止或删除是单独操作。管理员可查看并管理名下各账号的网站，访客无需登录。删除账号前必须先删除名下网站（包括已停止的网站）；账号删除会移除全部发布 Key 和 Agent 授权，历史网站的持久数据不会自动擦除。

## 对用户怎么说

首次只解释“打开这个授权链接，粘贴管理员给你的发布密钥；完成后我继续”。已经授权就继续构建和发布。完成后给出站点名称、公开链接、验证结果，以及“以后在这个项目里说更新发布即可”。不要把配服务器、登录 Dokploy 或理解 MCP 的工作推给用户。

客户端配置依据：[Cursor MCP](https://cursor.com/docs/mcp)、[Cursor Skills](https://cursor.com/docs/skills)、[Claude Code MCP](https://code.claude.com/docs/en/mcp)、[Claude Code Skills](https://code.claude.com/docs/en/skills)、[Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)、[Codex Skills](https://learn.chatgpt.com/docs/build-skills)。这些是配置格式依据，不代表每个客户端版本都已在本平台实机验证。
