LOOK

PortLoom 教程：用一台 VPS 把 NAS 服务发布到公网

Fri, 17 Jul 2026 00:00:00 GMT

家里的 NAS 跑了 Jellyfin、相册、下载工具和各种管理页面，但家庭宽带没有稳定公网入口。常见处理办法是手写 SSH 反向隧道，再配一层 Nginx 或 Caddy。服务少的时候还能维护，服务一多，端口、域名、隧道状态和配置文件很快就会乱。

PortLoom 把这套流程做成了一个 Web 控制台。公网 VPS 负责接收 HTTPS 请求，NAS 上的 Agent 主动连接 VPS，再把流量送回本地服务。NAS 不需要开放入站端口，也不用在路由器上逐个做端口转发。

本文使用当前正式版 v0.2.1。下面的域名和 IP 都是示例，部署时换成自己的值。

PortLoom 的工作方式

PortLoom 需要两台能运行 Docker Compose 的 Linux 主机：

位置	安装内容	用途
公网 VPS	Server、专用 SSHD、Caddy	WebUI、HTTPS 入口、路由网关和隧道入口
NAS 或内网服务器	Agent	主动连接 VPS，并把请求转发给本地服务

一次访问大致会经过这条链路：

浏览器
  │ HTTPS
  ▼
公网 VPS
  Caddy → PortLoom Gateway
                    │
                    │ SSH 反向隧道
                    ▼
内网 NAS
  PortLoom Agent → Jellyfin / 相册 / 管理页面

Agent 只向外连接 VPS 的 HTTPS 和 SSH 端口。公网请求沿已经建立的加密隧道返回 NAS，因此家庭网络不需要公网 IPv4，也不需要把 NAS 的服务端口直接暴露出去。

PortLoom 当前完整管理的是 HTTP/HTTPS 域名路由。它不会替你发布任意原始 TCP 端口。如果要暴露数据库、游戏端口或其他 TCP 服务，需要另找合适的方案。

开始前要准备什么

1. 公网 VPS

VPS 需要：

一个稳定的公网 IP
Linux 系统
Docker Engine
Docker Compose v2
TCP 80、443 和 2222 可以从公网访问

80/443 由 Caddy 处理 HTTPS，2222 是 PortLoom 专用 SSH 隧道端口。

2. NAS 或内网服务器

NAS 需要能运行 Docker Compose，并且可以主动访问 VPS 的 443 和 2222 端口。NAS 端不需要放行公网入站端口。

3. 域名和 DNS

假设：

VPS 公网 IP：203.0.113.10
PortLoom 管理域名：portloom.example.com
准备发布的 Jellyfin 域名：jellyfin.example.com

添加两条 DNS 记录：

portloom.example.com  A  203.0.113.10
*.example.com         A  203.0.113.10

通配符记录不是强制的，也可以给每个服务单独添加 A 记录。使用 Cloudflare 时，第一次部署建议先设为“仅 DNS”（灰云），避免 SSH 端口和证书签发被代理状态干扰。

确认解析结果：

nslookup portloom.example.com
nslookup jellyfin.example.com

两次查询都应该返回 VPS 的公网 IP。

在 VPS 安装 PortLoom Server

先下载脚本并查看内容，再执行安装。这里固定使用 0.2.1，避免日后 latest 更新后教程与实际版本对不上。

curl -fsSLo install-server.sh https://docs.961121.xyz/install-server.sh
less install-server.sh
chmod 0700 install-server.sh
./install-server.sh \
  --domain portloom.example.com \
  --version 0.2.1

安装器会启动三个容器：

portloom-server：WebUI、API 和路由网关
portloom-sshd：专门用于反向隧道的受限 SSH 服务
portloom-caddy：自动申请和续期 HTTPS 证书

默认安装目录是：

~/.portloom/server

安装完成后，终端会显示：

WebUI 地址
随机生成的管理员 Token
配置文件目录

:::warning 管理员 Token 相当于控制台密码。不要放进截图、博客、聊天记录或公开仓库。建议立即保存到密码管理器，服务器上的 .env 也要保持私有。 :::

用下面的命令查看容器状态：

cd ~/.portloom/server
docker compose --env-file .env -f compose.yml ps

三个容器都正常后，在浏览器打开：

https://portloom.example.com

输入安装器输出的管理员 Token 登录。

在 WebUI 添加 NAS

登录后进入“添加代理”页面，填写：

字段	示例
代理名称	`home-nas`
Server URL	`https://portloom.example.com`
公网 Server 主机	`portloom.example.com`
SSH 隧道端口	`2222`

点击“生成命令”。WebUI 会生成一条完整安装命令，其中包含一次性注册令牌和已经核验的 SSH 主机公钥。

这条命令只显示一次，不要自己拆开修改，也不要把它发到公开的地方。

在 NAS 安装 Agent

SSH 登录 NAS，把 WebUI 生成的完整命令原样执行。它会下载 install-agent.sh，并安装与 Server 相同版本的 Agent。

安装过程会自动完成这些事情：

生成独立 Ed25519 密钥
写入 Server 的 SSH 主机公钥
使用一次性令牌注册 Agent
上传 Agent 公钥并更新受限授权文件
建立反向隧道
注册成功后，从环境文件中删除一次性令牌

默认安装目录是：

~/.portloom/agent

查看 Agent 状态：

cd ~/.portloom/agent
docker compose --env-file .env -f compose.yml ps
docker compose --env-file .env -f compose.yml logs --tail=100 agent

回到 WebUI 的“客户端”页面，应该能看到 home-nas，并且心跳时间会持续更新。

发布第一个服务

下面以 Jellyfin 为例。假设 Jellyfin 在 NAS 上监听 8096。

进入“路由”，点击“添加 HTTP 路由”，填写：

字段	示例
名称	`Jellyfin`
客户端	`home-nas`
协议	`HTTP`
公网域名	`jellyfin.example.com`
本地主机	`127.0.0.1`
本地端口	`8096`

Agent 使用 host network，因此这里的 127.0.0.1 指 NAS 宿主机。如果目标服务在另一台局域网设备上，也可以填写对应的 LAN 地址，例如 192.168.1.20。

保存后，PortLoom 会分配 VPS 回环端口、建立 SSH 反向转发，并把域名加入 Gateway。Caddy 只会为 WebUI 中已经启用的 HTTP 路由提供入口。

等待状态收敛后访问：

https://jellyfin.example.com

如果页面能打开，说明第一条路由已经打通。

怎么看懂三层状态

PortLoom 没有把所有问题压成一个绿色圆点，而是分成三层：

Local

Agent 能否访问 local_host:local_port。

如果 Local down，先在 NAS 上检查：

curl -I http://127.0.0.1:8096

如果这里就不通，问题通常在本地服务、监听地址、端口或 NAS 防火墙，与 VPS 和域名无关。

Tunnel

SSH 反向转发是否已经建立。Tunnel down 常见原因包括：

NAS 无法访问 VPS 的 2222
SSH 密钥或 known_hosts 权限不正确
VPS 防火墙没有放行 2222
远程端口冲突

Public

Agent 是否已经应用最新配置，以及内置 Gateway 是否已经收敛。

Public 显示 published，不代表外部 DNS 和 TLS 一定正确。如果 Local、Tunnel、Public 都正常，但公网仍打不开，就继续检查域名解析、VPS 的 80/443 防火墙和 Caddy 日志。

常见故障怎么排

按链路从近到远检查，通常比反复重装更快。

1. 控制台打不开

cd ~/.portloom/server
docker compose --env-file .env -f compose.yml ps
docker compose --env-file .env -f compose.yml logs --tail=100 server
docker compose --env-file .env -f compose.yml logs --tail=100 caddy

确认 DNS 指向 VPS，并检查 80/443 是否放行。

2. Agent 无法注册

检查：

一次性令牌是否已经使用或过期
NAS 和 VPS 的系统时间是否正确
NAS 是否能访问管理域名的 HTTPS
Agent 数据目录是否持久化且可写

注册命令失败后不要删除 Agent 状态目录。修好网络后，先重新执行同一条安装命令，安装器会尝试安全恢复。

3. Gateway 返回 404

一般是 Host 没有匹配到路由。检查公网域名是否填写正确、路由是否启用，以及请求使用的域名是否和 WebUI 完全一致。

4. Gateway 返回 502

这通常表示 VPS 侧没有可用的隧道监听。先看 Tunnel 状态和 Agent 日志，不要先删除路由或数据库。

5. 页面能开，但视频或大文件异常

首页返回 200 只说明基础链路可用。媒体服务还要验证：

大文件连续下载
HTTP Range 请求
WebSocket（如果应用需要）
长连接
实际上行带宽

备份和升级

Server 使用 SQLite 保存配置。零停机备份时应该使用 SQLite 在线备份 API；如果直接复制数据库文件，应先停止 Server，或者同时一致地保存数据库、WAL 和 SHM 文件。

至少备份这些内容：

Server 数据目录
Agent 的 data/agent.json
Agent SSH 私钥和 known_hosts
Server 与 Agent 的 .env、compose.yml

升级前先看对应版本的 Release Notes，并固定明确的镜像标签。不要在生产环境长期依赖浮动的 latest。一次只升级一个组件，先 Server，再普通 Web Agent，最后处理高流量 Agent；每一步都检查心跳、Revision 和公网请求。

官方升级与回滚说明：

https://docs.961121.xyz/operations/backup-upgrade

几个安全细节

PortLoom 已经把 Server、SSHD 和 Agent 拆开，并对容器做了非 root 运行、只读根文件系统和能力裁剪，但部署者仍需要保护好凭据：

不要公开管理员 Token
不要把一次性注册命令发给别人
.env、SSH 私钥和备份目录使用严格权限
不要让 PortLoom 容器访问 Docker Socket
管理域名只使用 HTTPS
删除路由或重建数据前先备份
不要把删除 SQLite、Agent 状态目录或重新注册当成首选排错手段

PortLoom 的管理域名同时承载 Agent API。如果还要叠加来源 IP 限制、VPN 或身份验证网关，必须保证 NAS 仍能访问 Agent 所需的 API；不要直接给整个域名套一层只适合浏览器的登录页，否则心跳和配置同步也会被拦截。

适合哪些场景

PortLoom 适合把这些 Web 服务发布出去：

Jellyfin、Emby 等媒体服务
自建博客和静态站点
NAS 相册、文件管理页面
Home Assistant 等家庭服务
内网开发环境和测试页面

如果只发布一个临时页面，手写一条 SSH 隧道可能更快。服务多、域名多，或者希望在一个界面里看清本地、隧道和公网状态时，PortLoom 会省下不少重复配置。

项目和文档地址：

GitHub：https://github.com/lkhmm520/portloom
中文文档：https://docs.961121.xyz/
v0.2.1 Release：https://github.com/lkhmm520/portloom/releases/tag/v0.2.1

VPS 购买、重装 Ubuntu 与 3X-UI 面板搭建教程

Tue, 09 Jun 2026 00:00:00 GMT

这篇教程记录一次从零开始搭建 VPS 的完整流程：购买服务器、重装 Ubuntu、用 Termius SSH 连接服务器，最后安装 3X-UI 面板并创建 VLESS + REALITY 入站。

截图和步骤主要以搬瓦工为例。其他 VPS 商家的后台入口会不一样，但核心流程基本相同：购买实例、拿到公网 IP、重装或选择系统、通过 SSH 登录，然后安装面板。

开始之前先准备好：

一个可接收邮件的邮箱
一个可完成海外网站付款的支付方式，不同商家的可用付款方式以结算页为准
一台电脑，用来安装 Termius 并 SSH 连接服务器
如果选择 DMIT，提前准备一组 SSH 密钥，DMIT 主要通过 SSH key 登录服务器
可选：一个已经解析到服务器 IP 的域名，用来后续开启 TLS

提醒：VPS、域名和代理相关服务请遵守所在地法律法规以及服务商条款。本文只记录服务器自主管理和面板部署流程，页面选项、价格和可售机房可能会变化，以实际页面为准。

购买 VPS（以搬瓦工为例）

新手自用可以优先看两家：

搬瓦工：后台简单，KiwiVM 控制台好上手，适合第一次买 VPS 的用户。
DMIT：网络质量和线路选择也不错，更偏向熟悉 SSH key 的用户。DMIT 购买入口：https://www.dmit.io/aff.php?aff=24112

下面的截图统一以搬瓦工为例。打开搬瓦工购买入口：

https://bandwagonhost.com/aff.php?aff=81515

进入页面后，选择 VPS 套餐。新手自用直接买最便宜的一档就够了，机房推荐选择 Los Angeles / 洛杉矶。如果页面里有多个洛杉矶机房或多个套餐，优先选价格最低、带宽和流量够用的一档。DMIT 或其他商家的下单逻辑也类似，重点是确认机房、套餐、流量和付款周期。

下单时注意这些信息：

Location / 机房：推荐 Los Angeles
Billing cycle / 付款周期：按自己预算选择，年付通常更省事
Operating System / 系统：搬瓦工一般是在服务开通后进入 KiwiVM 再重装系统，这里按页面实际提示操作

确认套餐后点击 Order，进入注册和结算页面。

注册账号并完成支付

注册时按页面要求填写个人信息即可。手机号需要带国际区号，中国大陆手机号前面加 86。

常见填写方式：

First Name：名字
Last Name：姓氏
Email Address：邮箱
Password：账号密码
Country or territory：选择所在国家或地区
Phone Number：填写带国际区号的手机号，例如 8613800000000

阅读并勾选 Terms of Service 后提交订单。支付方式可以选择支付宝或银联，按支付页面完成付款。

购买成功后，点击右上角 Client Area 登录客户后台。

进入 My Services 并打开 KiwiVM

顶部菜单选择 Services
点击 My Services

在服务列表中找到刚购买的 VPS
点击 Manage 列里的齿轮图标
在弹出的菜单中选择 Open KiwiVM

KiwiVM 是搬瓦工的 VPS 控制台，可以在里面查看 IP、重装系统、重启服务器、查看流量和管理基础设置，后面的操作基本都在这里完成。

重装 Ubuntu 22.04

进入 KiwiVM 后，先在右侧主控制区域暂停当前系统：

点击 Stop
等待服务器状态变为停止
左侧菜单选择 Install new OS
系统列表选择 ubuntu-22.04-x86_64
勾选确认会清空当前服务器数据的选项
点击重装按钮并等待系统安装完成

这里推荐 Ubuntu 22.04 x86_64，兼容性好，后续跑安装脚本也更省心。

重装过程中页面会生成新的 root 密码。这个密码只展示一次，务必马上复制保存到本地密码管理器或安全笔记里，后续 SSH 连接服务器时会用到。

系统安装完成后，回到 KiwiVM 主页面，记录下面几项信息：

Public IP address：服务器 IP
SSH Port：一般是 22
Operating system：确认已经是 Ubuntu 22.04 x86_64
root 密码：刚才安装系统时页面展示的密码

安装 Termius 并连接 VPS

拿到 IP 和 root 密码后，就可以从本地电脑连上服务器了。Termius 是一个常用的 SSH 工具。搬瓦工重装系统后通常会给 root 密码，可以直接用密码登录；DMIT 更常见的方式是先在后台上传或选择 SSH 公钥，开通后用对应的私钥登录。

官网地址：

https://termius.com/index.html

如果你买的是搬瓦工，下载并注册 Termius 后，按下面步骤添加服务器：

打开 Termius
点击 New host
弹窗出现时选择 ADD & CONTINUE
Address 填写 KiwiVM 里看到的服务器 IP
SSH Port 保持 22
Username 填写 root
Password 填写重装系统时保存的 root 密码
点击 Connect

第一次连接时如果出现主机指纹确认提示，确认 IP 没填错后选择继续。看到终端命令行，就说明已经成功登录服务器。

如果你买的是 DMIT，在创建 VPS 时一般要先添加 SSH public key。服务器开通后，在 Termius 里新建 Host：Address 填 DMIT 分配的公网 IP，Username 通常填 root，认证方式选择 Key，并导入与你后台公钥对应的私钥。私钥不要发给别人，也不要上传到不可信的网盘或聊天工具。

安装 3X-UI 面板

连接到服务器后，建议先更新系统软件包：

apt update -y && apt upgrade -y

然后安装 curl，并执行 3X-UI 官方一键安装命令：

apt install -y curl
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

这个脚本来自 MHSanaei/3x-ui 项目，官方教程入口是：

https://github.com/MHSanaei/3x-ui/wiki

安装过程中脚本会引导完成面板设置，并生成或要求确认面板账号、密码和访问路径。不管是脚本自动生成还是自己设置的，这几项都要保存好：

面板访问地址
面板端口
面板访问路径
面板账号
面板密码

安装完成后，终端会输出面板地址，通常类似下面这种格式：

http://服务器IP:面板端口/面板路径

在浏览器中打开这个地址，输入刚才保存的账号密码登录 3X-UI。登录后如果界面不是中文，可以在面板设置中切换语言。

如果忘记地址、账号或密码，可以在服务器终端执行：

x-ui

进入管理菜单后选择查看面板设置，或按菜单提示重置账号密码。

如果无法打开面板，优先检查：

服务器 IP 是否填写正确
面板端口是否复制完整
面板路径是否复制完整
KiwiVM 中服务器是否处于 Running 状态
本地网络是否能访问该 IP
服务器防火墙是否放行了面板端口

添加入站节点

面板能正常登录后，就可以创建第一个节点了。进入左侧 入站列表，点击 添加入站。

新手建议直接创建 VLESS + TCP(RAW) + REALITY 节点。这个方案不依赖自己的域名和证书，配置简单，隐蔽性和安全性也比传统裸露 TLS/WS 方案更适合新手自用。后续即使有了域名，也可以继续使用 REALITY，不一定非要改成 TLS 或 WebSocket。

启用：开启
备注：自定义一个好记的名称，例如 美国-洛杉矶-1
协议：选择 VLESS
监听 IP：不填即可，表示监听所有地址
端口：填写一个未被占用的端口，例如 41507
总流量：填 0 表示不限制流量
到期时间：不填表示不限制到期时间
传输：一般选择 TCP (RAW)
安全：选择 REALITY
uTLS：选择 chrome 或 firefox
目标 / Target / Dest：填写一个稳定的 HTTPS 站点，例如 www.microsoft.com:443
SNI / Server Names：填写同一个域名，例如 www.microsoft.com
SpiderX：保持 /
Short IDs：使用面板默认值，或点击生成按钮重新生成

REALITY 区域里如果看到 Get New Cert、Get New Seed 这类按钮，直接点击生成新的密钥和种子；不要复用网上教程里的公钥、私钥或 Short ID。

客户端区域保留自动生成的用户即可，也可以把 Email 改成自己能识别的名字，例如 my-phone。如果 VLESS 客户端设置里有 Flow 选项，优先选择 xtls-rprx-vision；如果当前面板或传输方式没有这个选项，保持默认就行。

有些新版 3X-UI 会把“入站”和“客户端”分开管理。如果你需要单独新增客户端，可以进入左侧 客户端，点击 添加客户端，填写一个便于识别的 Email 或备注，再在 关联入站 里选择刚创建的 VLESS + REALITY 入站，最后点击创建。

确认配置后点击添加或 Create。添加完成后，检查入站状态是否启用，并确认 xray state 是 Running。

如果服务器开启了 ufw，还需要放行刚才设置的节点端口：

ufw allow 41507/tcp

端口要换成你实际填写的入站端口。只放行面板端口是不够的，节点端口也必须能从外部访问。

添加完成后，回到入站列表，点击该入站左侧的展开按钮，再点击信息图标或二维码图标即可查看节点详情和连接 URL。复制 URL 后，可以导入到客户端使用。

常见客户端：

iOS：Shadowrocket
Android：v2rayNG、Hiddify 或支持 VLESS REALITY 的客户端
电脑端：v2rayN、Nekoray、Hiddify 等

手机端也可以点击二维码图标，用客户端扫码导入。

有域名时的 TLS 方案

如果你有自己的域名，也可以把域名解析到服务器 IP 后走 TLS 方案。不过对新手来说，前面推荐的 VLESS + REALITY 通常已经够用，而且不需要处理证书申请、续期和域名解析，这部分只作为备用方案。

整体流程是：

在域名 DNS 管理后台添加 A 记录，指向搬瓦工 VPS 的 IP
等待 DNS 生效
在 3X-UI 管理脚本中申请 HTTPS 证书
回到入站配置，将安全选项切换为 TLS
证书位置选择 从面板设置证书 自动填充
保存入站配置

官方 wiki 已经把证书管理集中到 x-ui 管理脚本中。服务器终端执行：

x-ui

然后选择 SSL Certificate Management，按提示申请域名证书、续期证书或设置面板证书路径。证书申请前要确保域名已经解析到当前服务器 IP，并且服务器的 80 端口没有被其他服务占用。

如果域名托管在 Cloudflare，也可以在管理菜单里选择 Cloudflare SSL Certificate，按提示填入 Cloudflare API Token 申请证书。细节以 3X-UI 官方 wiki 为准：

https://github.com/MHSanaei/3x-ui/wiki

在 3X-UI 添加入站时，选择 TLS 后，可以点击 从面板设置证书 自动填充证书路径。确认 SNI、证书路径和密钥路径无误后，点击添加或保存。

复制节点并导入客户端

节点创建完成后，进入 入站列表：

点击入站左侧的展开按钮
点击信息图标查看详情
在 URL 区域复制节点链接
打开客户端，选择从剪贴板导入

如果是手机端，可以点击二维码图标，然后用 Shadowrocket、Clash Verge 或其他支持对应协议的客户端扫码导入。

导入后建议先测试连通性。如果连不上，按下面顺序排查：

入站端口是否和客户端配置一致
服务器安全组或防火墙是否放行入站端口
协议、UUID、传输方式是否一致
开启 TLS 时域名是否解析正确
证书路径和密钥路径是否正确
使用 REALITY 时，客户端是否支持 VLESS + REALITY
REALITY 的目标域名、SNI、公钥、Short ID 和客户端链接是否一致

安全建议

面板搭好后，建议立刻做几件事：

使用强密码，不要使用默认账号密码
面板端口尽量使用随机高位端口
保留安装时生成的随机面板路径，不要改成过于简单的路径
不要把面板地址公开发到群聊或论坛
定期更新系统和 3X-UI
不再需要密码登录时，可以改用 SSH key
重要配置做好备份，避免重装系统后丢失

如果只是自用，最简单稳定的路径是：搬瓦工或 DMIT VPS + Ubuntu 22.04 + Termius SSH + 3X-UI 面板。搬瓦工可以先用 root 密码登录，DMIT 主要用 SSH key 登录；入站协议优先选 VLESS + TCP(RAW) + REALITY。先把这个节点跑通，再考虑域名、证书和其他传输方案，这样遇到问题时更容易定位。

Qmai Playbook 索引：AI 执行手册清单

Thu, 28 May 2026 00:00:00 GMT

Playbook 是 AI 执行任务时使用的场景手册。

它不替代宏观规则，也不替代仓库职责清单。正确顺序是：先判断需求和仓库，再选择最小 playbook。

使用前先读

Playbook 清单

Playbook	适合处理什么
`需求解析.md`	需求、飞书、工单或接口文档还没有明确目标仓库时，先分析系统和仓库归属
`国际交付工作流.md`	一个需求需要从分析、方案、实现、验证一直走到交付说明
`Vue业务子应用.md`	普通 `*-vue-international` 业务页面、组件、路由、API、i18n、样式改动
`基座与跨应用.md`	qiankun 基座、登录、菜单、头部、容器、微应用挂载、跨应用状态
`公共业务与打印模板.md`	公共业务页、公共配置、打印模板、票据模板，以及 `operation` 打印项目边界判断
`共享组件库.md`	`vue-kylin-international` 共享组件、组件样式、组件 API、跨仓一致性问题
`样式设计规范.md`	UI、UX、页面布局、后台视觉、设计 token、长文本和 RTL
`装修平台.md`	装修平台主工程和 `design-v0-international` 组件库相关任务
`预发布流程.md`	明确进入发布阶段后的普通国际仓 `pre` 发布、发布状态检查和 OPMS 排障

为什么不把路由写在索引里

索引只负责“有哪些手册”。

完整路由逻辑统一放在工作流路由中，避免同一套规则在多个文档里重复维护，最后出现分叉。

使用示例

需求描述	应该怎么走
“飞书需求说要改会员权益，但没说仓库”	先走 `需求解析.md`
“商品列表页新增一个筛选项”	明确归属后走 `Vue业务子应用.md`
“菜单入口不显示”	走 `基座与跨应用.md`，必要时联查业务仓
“多个仓库的门店选择器样式都不一致”	走 `共享组件库.md`
“打印纸面内容字段顺序要调整”	先判断 common 模板还是 `operation` 运行时，再走 `公共业务与打印模板.md`
“部署预发布环境”	这是可选发布阶段，走 `预发布流程.md`

新增 playbook 的规则

新增 playbook 前，先确认现有手册无法覆盖。

如果确实需要新增，要同步检查：

工作流路由。
Playbook 索引。
维护映射。
相关宏观文档是否已经先更新。

Playbook 的目标不是越多越好，而是让 AI 在正确边界内稳定执行。

Qmai 项目识别：先判断项目角色，再选择规则

Thu, 28 May 2026 00:00:00 GMT

项目识别回答一个基础问题：当前工作区到底是不是 Qmai 国际前端项目？如果是，它属于哪类系统？

只有先回答这个问题，后面的规则和 playbook 才有意义。

三步判断法

找到项目根目录
  -> 判断是否命中 Qmai 信号
  -> 判断系统角色和仓库职责

1. 找到当前项目根目录

AI 进入项目后，先从当前目录向上找最近的 package.json。

如果一个工作区里有多个项目，就根据用户提供的文件、路由、需求关键词，定位最相关的项目。

如果无法确定项目根目录，需要说明缺少上下文，而不是继续猜。

2. 判断是否是 Qmai 项目

命中以下任意强信号，可以按 Qmai 项目处理：

信号	说明
`scripts` 中出现 `qmai build`、`qmai format`、`qmai deploy` 等命令	构建链路属于 Qmai 体系
依赖中出现 `@qmai/*`	使用 Qmai 组件或工程能力
出现 `eslint-plugin-qmai`	使用 Qmai 代码规范
依赖别名中出现 `npm:@qmai/*`	通过别名引入 Qmai 包

目录名或包名里出现 qmai、qimai 只能作为辅助信号，不能作为唯一依据。

如果完全没有命中 Qmai 信号，就按当前项目自己的 README、配置和代码风格处理，不强行套用 Qmai 规则。

3. 判断系统角色

Qmai 国际前端里，不同系统角色有不同处理方式。

系统角色	常见信号	典型职责
qiankun 基座	依赖 `qiankun`，涉及登录、菜单、头部、容器、微应用注册	`console-vue-international`
普通业务子应用	Vue2、业务路由、业务页面、子应用生命周期	多数 `*-vue-international`
公共业务页	`/commonCenter/`、公共配置、打印模板	`common-vue-international`
共享组件库	包名或源码指向 `vue-kylin`	`vue-kylin-international`
打印项目	打印插件、桥接、国际打印代码、打印通用入口	`operation`
装修平台	Vue3 装修主工程或装修组件库	`design-vue-3-international`、`design-v0-international`

`*-vue-international` 必须查职责清单

当目标可能是某个 *-vue-international 仓库时，不能只靠仓库名猜。

必须先查“国际 Vue 仓库职责清单”，它会说明：

每个仓库的一句话职责。
哪些需求优先改这个仓库。
关键模块和路由线索。
容易混淆的边界。

例如：

需求关键词	优先判断
菜单、登录、容器、微应用挂载	`console-vue-international`
公共配置、公共打印模板、硬件、KDS 公共配置	`common-vue-international`
商品、SKU、分类、配方、商品库存	`goods-vue-international`
餐饮订单、外卖、堂食、排队、桌台、KDS	`catering-vue-international`
会员、积分、等级、会员画像	`member-vue-international`
传统 BI 报表	`bi-vue-international`
自助 BI、数据集、数据源、工作空间	`qmbi-vue-international`

完整职责不要在项目识别页重复维护，应回到仓库职责清单。

Vite 不是优先判断依据

如果仓库里还存在 vite.config.*，通常按历史遗留或兼容配置读取。

国际前端当前开发和验证优先看仓库自己的 package.json scripts，通常是 rsbuild 或 qmai 构建链路。

输出结果应该包含什么

AI 完成项目识别后，应能说清楚：

当前项目是否命中 Qmai 信号。
当前项目更像哪类系统角色。
目标仓库判断的证据是什么。
是否需要联查基座、组件库、公共页或打印项目。
当前工作区缺少哪些跨仓上下文。

项目识别不是为了“多读文件”，而是为了让后续修改落在正确边界内。

Qmai 国际前端规则模式：让 AI 先懂业务边界，再写代码

Thu, 28 May 2026 00:00:00 GMT

它是什么

Qmai 国际前端规则中心不是一个业务系统，也不是一份普通提示词。

它是一套前端协作规则模式：把“需求应该落到哪里”“不同仓库负责什么”“AI 修改代码前要遵守什么”这些团队经验，整理成清晰、可读取、可执行的规则。

简单说，它让 AI 在写代码前先完成三件事：

看懂需求属于哪个业务系统。
找到应该修改的前端仓库。
按团队约束完成实现、验证和交付。

为什么需要它

Qmai 国际前端不是一个单仓库项目，而是一组系统共同工作：

console-vue-international 负责后台基座、菜单、登录、容器和微应用挂载。
多个 *-vue-international 仓库负责不同业务域页面。
common-vue-international 负责公共业务页和公共打印模板。
vue-kylin-international 负责共享业务组件。
operation 负责打印运行时、打印桥接和国际打印代码。
装修平台、BI、供应链、营销、会员、支付等又有各自边界。

如果没有统一规则，AI 或新人很容易遇到这些问题：

只看需求关键词就猜仓库。
把共享组件问题复制修到多个业务仓库。
把打印模板和打印运行时代码混在一起。
UI 页面只按通用模板做，忽略 Qmai 后台真实工作台风格。
进入发布阶段后误用 feature 分支、正式环境或浏览器操作。

规则中心解决的就是这些边界问题。

新版规则怎么分层

新版规则中心用“人先看地图，AI 再执行细则”的方式组织。

层级	作用	可以怎么理解
`00-总览`	解释国际前端整体由什么构成	一张系统全景图
`01-PRD到系统拆分`	把需求、飞书、工单拆到系统和仓库	需求归属判断表
`02-系统内部结构`	说明每类系统内部怎么拆模块和文件	仓库内部导航
`03-模块页面命名`	统一页面、路由、API、i18n、样式命名	落代码的命名规则
`04-样式与组件库`	说明样式入口、主题变量、组件库和 UI 规范	页面和组件怎么长
`05-AI执行规则`	给 AI 的全局约束、项目识别、路由和 playbook	AI 真正执行时读这里
`06-维护映射`	说明宏观规则变更后要同步哪些执行规则	规则更新检查表

这套分层的好处是：人读起来像文档，AI 执行起来像流程。

一个需求如何被处理

可以把一次交付想成一条固定链路：

收到需求
  -> 读取需求内容
  -> 提取业务词、页面词、接口词
  -> 查仓库职责清单
  -> 判断目标系统和目标仓库
  -> 判断是否涉及基座、组件库、公共页、打印或 UI
  -> 选择最小 playbook
  -> 修改前给出目标、影响范围和步骤
  -> 实现、验证、交付说明

这里最关键的是前半段。代码不是第一步，判断边界才是第一步。

最重要的规则

1. 先判断仓库，不先写代码

普通 *-vue-international 需求必须先查“国际 Vue 仓库职责清单”。这个清单会说明每个仓库的一句话职责、优先处理的需求、关键模块线索和容易混淆的边界。

2. UI 任务先读 UI 详细规范

只要涉及页面布局、组件视觉、样式、长文本或 RTL，就必须先读 UI 详细规范。Qmai 国际后台是高频业务工作台，不是营销官网，也不是通用 SaaS 卡片模板。

3. 打印要分清两个世界

公共打印模板和纸面内容布局优先看 common-vue-international。

打印插件、桥接、国际打印代码和运行时调试属于 operation。

4. 可选发布阶段有独立约束

发布不属于默认交付主流程。只有任务明确进入发布或部署阶段时，才应用发布规则。

普通国际仓发布到 OPMS 平台时，必须走本地配置和 opms_release.py 脚本，不能通过浏览器页面点击完成。

如果发布 pre，必须先把当前任务分支合到 pre，推送 origin/pre，然后只部署 branch/pre。不能直接部署 feature 分支。

5. AI 不主动做高风险动作

未经明确要求，不执行 git commit、git push 或发布。修改前先给方案，完成后说明改了什么、为什么、如何验证。

核心价值

Qmai 国际前端规则中心的价值体现在三个层面。

层面	价值
业务层	需求先拆到系统和仓库，减少改错位置、重复联调和边界争议
工程层	基座、业务仓、公共页、组件库、打印、装修平台和 UI 规范都有清晰职责
AI 层	AI 在明确约束下执行，修改前有方案，修改后有验证和交付说明

这套模式把多仓库协作经验沉淀为可读、可执行、可维护的规则，让 AI 编码从“直接生成代码”变成“先识别边界，再稳定交付”。

Qmai 工作流路由：一个任务应该走哪条流程

Thu, 28 May 2026 00:00:00 GMT

工作流路由回答一个问题：当前任务应该进入哪份执行手册？

路由不是越复杂越好。它的目标是让 AI 选择“最小但足够”的 playbook，避免一个小页面问题被当成完整交付流程，也避免跨仓问题被当成单文件修改。

路由前先做两件事

按项目识别判断当前项目角色。
如果需求可能落在 *-vue-international，先查仓库职责清单。

没有完成这两步，不应该直接进入代码修改。

路由原则

先按业务需求判断系统，再按当前项目证据判断仓库。
选择最小匹配 playbook。
不要求所有仓库位于同一个父目录。
不维护个人本机路径映射。
当前工作区不可见的跨仓上下文，只说明缺失，不猜路径。
路由逻辑只维护在新版执行规则中，playbook 索引只做清单。

任务路由表

任务类型	进入的 playbook	怎么理解
飞书链接、需求文案、目标仓库不明确	`需求解析.md`	先把需求翻译成系统和仓库判断
从需求分析到实现、验证、交付的完整链路	`国际交付工作流.md`	适合完整需求交付
普通 Vue2 业务子应用页面、组件、路由、API 改动	`Vue业务子应用.md`	适合明确落在业务仓库的改动
登录、菜单、头部、容器、微应用挂载、跨应用状态	`基座与跨应用.md`	适合 qiankun 基座和跨应用问题
公共业务页、公共配置、打印模板、票据模板	`公共业务与打印模板.md`	适合 common 仓和模板内容
打印插件、桥接、国际打印代码、打印通用入口	`公共业务与打印模板.md`，并按 `operation` 打印项目边界处理	打印运行时不是普通业务仓流程
共享 UI 组件、组件行为、跨仓样式一致性	`共享组件库.md`	适合 `vue-kylin-international`
UI、UX、页面布局、设计 token、后台视觉规范	`样式设计规范.md`，并先读 UI 详细规范	适合页面和组件视觉任务
装修平台主工程或装修组件库	`装修平台.md`	适合装修相关需求
明确要求普通国际仓 `pre` 发布、状态检查、OPMS 排障	`预发布流程.md`	可选发布阶段，必须走配置文件和脚本

路由后的输出要求

AI 进入 playbook 前，应该先说明：

目标系统。
目标仓库。
判断置信度。
判断证据。
是否需要联查基座、组件库、公共业务页或打印项目。

例如，一个“商品选择器在多个业务仓都展示异常”的问题，不能只进入当前业务仓页面修样式。它很可能需要进入 共享组件库.md，检查 vue-kylin-international。

常见误区

误区	正确做法
看到 `*-vue-international` 就直接改当前仓库	先查仓库职责清单
看到打印就直接归到一个仓库	先区分 common 模板和 `operation` 运行时
UI 任务只看当前页面	先读 UI 详细规范，再判断组件库或业务页归属
明确发布 `pre` 时直接部署 feature 分支	先合到 `pre`，推送 `origin/pre`，再部署 `branch/pre`
规则中心接入时打开浏览器	接入只做本地文件和配置，不用浏览器

工作流路由的价值，是把“这个任务应该怎么开始”标准化。

Qmai 全局约束：AI 做事前先守住这些底线

Thu, 28 May 2026 00:00:00 GMT

全局约束是 AI 执行任务前必须遵守的底线。

它不解决“具体需求怎么写代码”，而是先规定什么能做、什么不能做、什么时候要先说明、什么时候必须停下来确认。

1. 修改前先说清楚

除非用户明确要求直接修改，否则 AI 修改前必须先给出简要方案：

修改目标是什么。
影响范围有哪些。
准备怎么改。
如何验证。

如果涉及多个文件或多个模块，还要先列出预计影响文件。

这条规则的目的不是拖慢执行，而是避免 AI 在没有边界判断时直接动手。

2. 先读上下文，再改代码

AI 不能只凭需求关键词猜仓库或路径。

开始前至少要确认：

当前项目根目录在哪里。
当前项目是否属于 Qmai 国际前端体系。
当前文件属于哪个系统、模块和业务边界。
是否需要联查基座、组件库、公共业务页或打印项目。

如果当前工作区看不到相关仓库，只能说明缺少上下文，不能猜本机路径。

3. 跨仓影响要先分析

这些场景不能只看当前页面：

场景	需要关注
菜单、登录、头部、侧栏、容器、微应用挂载	`console-vue-international`
多仓库共享组件、选择器、表格、上传、弹窗、组件样式	`vue-kylin-international`
公共业务页、公共配置、打印模板、票据模板	`common-vue-international`
打印插件、桥接、国际打印代码、打印通用入口	`operation`

4. 代码改动保持最小

AI 实现时遵守：

保持当前文件和模块已有风格。
不主动引入新依赖、新范式或新目录结构。
不做无关重构。
不删除错误处理、异常捕获或兼容逻辑。
不把临时需求名写进长期变量名。

一个需求只做一个可验证闭环，不把历史治理混进来。

5. 接口规则

如果接口文档路径包含 /sellers，默认按 /assistant 进行接口定位、联调和代码映射，除非用户明确要求保持原样。

涉及 sellerId 的接口入参、路由参数或函数透传参数时，默认不需要前端主动传递。后端会从登录态中解析。

历史代码已有 sellerId 时，不顺手治理；只有当前需求明确要求、联调确认或它已经导致问题时再处理。

6. UI、i18n 和 RTL

只要任务涉及 UI、UX、页面布局、组件视觉、后台视觉规范、长文本或 RTL，就必须先读 UI 详细设计规范。

实现时还要遵守：

可见文案走项目既有 i18n 方案。
不把中文、英文或临时文案硬编码进模板。
样式考虑长文本和 RTL。
共享组件问题优先评估组件库，不在多个业务仓库复制补丁。

7. 飞书内容先读取，再判断

用户提供飞书链接时，AI 的第一步是读取内容，再判断目标系统和仓库。

业务任务中的读取链路是：

MCP -> lark-cli -> 浏览器兜底

只有三条链路都失败、权限不足或内容不可读时，才说明阻塞原因。

注意：规则中心安装或接入不属于业务内容读取，不使用浏览器或 Chrome。

8. Git 和发布不能越界

未经用户明确要求，AI 不执行：

git commit
git push
发布或部署

国际需求开发默认从目标仓最新 pre 切出 feature/* 分支，不能直接在 pre 上改需求代码。

发布不属于默认主流程。只有任务明确进入发布或部署阶段时，才应用发布规则。

普通国际仓发布到 OPMS 平台必须走本地配置文件和 opms_release.py 脚本，不使用浏览器或 Chrome 控制发布平台。

部署 pre 的固定顺序是：

当前任务分支
  -> merge 到 pre
  -> push origin/pre
  -> OPMS 部署 branch/pre

不能直接部署 feature 分支，也不能把 master、main、tag 作为普通国际仓 pre 环境发布 ref。

9. 最小自查

AI 每次交付前至少自查：

是否明确目标系统和目标仓库？
是否读了必要的职责清单或 UI 规范？
是否只改了当前需求相关文件？
是否说明了验证方式？
是否没有擅自提交、推送或发布？
是否把不确定处标成“需确认”？

Qmai 维护映射：规则变更后怎么同步

Thu, 28 May 2026 00:00:00 GMT

维护映射回答一个问题：规则变了以后，应该同步哪些文档？

新版规则中心不鼓励直接改 AI 执行细则。更稳的方式是：

先改宏观文档
  -> 查维护映射
  -> 同步 AI 执行规则
  -> 检查入口、链接和重复事实源

为什么需要维护映射

如果所有规则都写在 AI 执行文件里，会出现两个问题：

人不好读，只知道 AI 应该怎么做，不知道业务边界为什么这样定。
规则容易重复，多个入口各写一套，后续更新时很容易分叉。

维护映射把规则分成两类：

类型	作用
宏观文档	人和 AI 都能读懂的业务语义源
AI 执行规则	AI 真正执行任务时读取的约束、路由和 playbook

新版维护原则

00-04 是业务语义源。
05-AI执行规则 是 AI 执行投影。
06-维护映射 是同步协议。

也就是说，业务边界、仓库职责、UI 规范、命名规则这些内容，应优先维护在宏观文档里。

AI 执行规则只负责把这些内容投影成可执行动作。

常见同步场景

你修改了什么	需要同步检查什么
系统全景、仓库角色、系统边界	项目识别、工作流路由、playbook 索引
PRD 归属、需求类型、接口规则	需求解析、国际交付工作流、全局约束
国际 Vue 仓库职责清单	需求解析、项目识别、工作流路由
基座、业务子应用、公共页、打印、装修平台结构	对应 playbook 和工作流路由
页面、路由、API、i18n、样式命名	Vue 业务子应用、国际交付工作流、全局约束
UI 规范、主题变量、组件库依赖	样式设计规范、共享组件库、基座与跨应用
打印模板和打印运行时边界	公共业务与打印模板、项目识别、全局约束

一次规则变更怎么做

例如，团队新增一个业务仓库职责：

先更新仓库职责清单，让人能看懂这个仓库负责什么。
再检查项目识别是否能识别这个仓库。
再检查工作流路由是否需要新增或调整分流。
再检查 playbook 索引是否需要补充说明。
最后检查博客入口和旧规则残留。

AI 同步输出模板

规则变更后，AI 应该用这种格式说明：

已修改宏观文档：
已同步微观规则：
未同步但已检查：
可能影响：
自检结果：
需确认：

一句话总结

维护映射让规则中心保持一个事实源：人先维护业务地图，AI 再同步执行细则。

Qmai 国际交付工作流：从需求到验证的 7 步

Thu, 28 May 2026 00:00:00 GMT

国际交付工作流用于处理完整需求。

它不是单个页面的写法说明，而是一条从需求读取到最终交付的固定链路。

适用场景

适合使用完整交付工作流的场景：

用户给了飞书需求、工单或一段较完整的需求说明。
需要分析目标系统和目标仓库。
需求可能涉及多个仓库、共享组件、公共业务页、打印或基座。
需要完成方案、实现、验证和交付说明。

如果只是一个明确的单点修改，应该优先选择更小的 playbook。

7 步流程

1. 读取需求
2. 判断系统和仓库
3. 判断跨仓影响
4. 制定修改方案
5. 实现最小闭环
6. 验证
7. 输出交付说明

1. 读取需求

如果用户提供飞书链接，先读取内容，再判断目标系统。

如果用户只给文字需求，就提取：

业务目标。
用户动作。
页面或路由关键词。
接口路径。
状态、角色、异常路径。
是否涉及 UI、i18n、RTL、打印，以及是否明确进入发布阶段。

这一步的产物不是代码，而是需求要落到哪里。

2. 判断系统和仓库

先按系统地图判断大类：

基座。
业务子应用。
公共业务页。
共享组件库。
打印运行时。
装修平台。

如果目标可能是 *-vue-international，必须查仓库职责清单。

判断结果应包含：

目标系统。
目标仓库。
置信度。
证据。
需确认事项。

3. 判断跨仓影响

这些情况要特别注意：

需求线索	可能需要联查
菜单、登录、容器、微应用挂载、跨应用状态	`console-vue-international`
多仓共享组件、表格、选择器、上传、弹窗	`vue-kylin-international`
公共业务页、公共配置、打印模板	`common-vue-international`
打印插件、桥接、国际打印代码	`operation`
UI、长文本、RTL、组件视觉	UI 详细设计规范

当前工作区不可见的仓库，不能猜路径，只能说明缺少上下文。

4. 制定修改方案

动手前先说明：

修改目标。
影响范围。
涉及文件。
实现步骤。
验证方式。

多文件或多模块改动必须列出文件清单。

5. 实现最小闭环

实现时遵守全局约束：

不做无关重构。
不引入新依赖。
不删除兼容逻辑。
可见文案走 i18n。
样式兼顾长文本和 RTL。
接口路径含 /sellers 时默认按 /assistant 映射。
sellerId 默认不由前端重复传递。

一个阶段只做一个可验证闭环，不留下半成品路径。

6. 验证

按改动范围选择验证方式：

改动范围	验证方式
文档或规则	检查 Markdown 链接、入口引用和旧规则残留
单页面逻辑	本地路由自测关键状态
样式或 UI	浏览器或截图检查默认、空、加载、错误、长文本
i18n	检查翻译 key 和至少一种非中文语言
RTL 敏感布局	构造 RTL 或逻辑方向样式验证
共享组件	构建组件库，并检查至少一个下游调用路径
子应用页面	按仓库 `package.json` scripts 构建或本地验证
可选发布流程	仅在明确要求发布时，检查分支、配置文件、脚本和 OPMS ref

验证不是附加动作，而是交付的一部分。

7. 输出交付说明

完成后用中文说明：

改了什么。
为什么这么改。
如何验证。
还有哪些需确认事项。

未经用户明确要求，不执行 git commit、git push 或发布。

可选发布阶段提醒

国际需求开发默认从目标仓最新 pre 切出 feature/*。

禁止直接在 pre 上改需求代码。

发布不是默认交付主流程。只有任务明确进入发布或部署阶段时，才应用下面的规则。

普通国际仓发布到 OPMS 平台时：

任务分支 -> merge 到 pre -> push origin/pre -> 部署 branch/pre

不能直接部署 feature 分支，不能触发 gray、staging、pro、prod、tag、master 或 main 发布。

一句话总结

完整交付工作流不是让 AI “快点写”，而是让 AI 先判断边界、再最小修改、最后验证交付。

Qmai 国际前端系统地图与仓库职责

Thu, 28 May 2026 00:00:00 GMT

这一页回答一个最容易出错的问题：一个需求到底应该改哪个前端仓库？

Qmai 国际前端不是单个项目，而是一组系统协作。需求来了以后，不能只靠关键词猜仓库，要先看系统地图和职责边界。

先看整体地图

Qmai 国际前端
  ├─ qiankun 基座
  │   └─ console-vue-international
  ├─ 业务子应用
  │   └─ 多个 *-vue-international 仓库
  ├─ 公共业务页和公共打印模板
  │   └─ common-vue-international
  ├─ 共享组件库
  │   └─ vue-kylin-international
  ├─ 打印运行时
  │   └─ operation
  ├─ 装修平台
  │   ├─ design-vue-3-international
  │   └─ design-v0-international
  └─ 可选发布流程
      └─ OPMS pre 发布脚本与配置

判断顺序

先读需求原文，不先猜仓库。
提取业务词、页面词、接口词、路由词。
先判断系统类型：基座、业务子应用、公共页、组件库、打印、装修平台。
如果目标可能是 *-vue-international，查完整仓库职责清单。
判断是否需要联查基座、组件库、公共业务页或打印项目。
再进入对应 playbook。

系统角色表

系统角色	仓库或项目	主要职责
qiankun 基座	`console-vue-international`	登录、菜单、头部、侧栏、容器、微应用注册、跨应用状态、全局主题
公共业务页	`common-vue-international`	`/commonCenter/`、公共能力页、公共配置、公共打印模板、票据模板
共享组件库	`vue-kylin-international`	选择器、表格、上传、业务弹窗、跨仓共享组件和组件包发布
打印运行时	`operation`	打印插件、桥接、国际打印代码、打印通用入口、本地调试
装修平台主工程	`design-vue-3-international`	点餐小程序、SOK、KDS、智慧屏、叫号屏等装修能力
装修组件库	`design-v0-international`	装修平台复用组件能力

`*-vue-international` 仓库职责清单

下面是业务子应用仓库的简化职责表。真实任务中仍要结合当前仓库源码、路由和页面确认。

仓库	一句话职责	典型需求关键词
`console-vue-international`	国际后台 qiankun 基座和壳层	登录、菜单、头部、侧栏、主页、账号中心、微应用挂载
`common-vue-international`	公共业务能力页、公共打印模板和多业务复用页面	公共配置、收款、配送中心、硬件、KDS、桌台、打印模板、消息中心
`org-vue-international`	组织、企业、账号、员工、门店、权限和品牌基础资料	企业信息、品牌、组织架构、角色权限、员工、账号、门店、语言
`goods-vue-international`	商品中心、菜单商品、分类、门店商品、库存和配方资料	商品、SKU、套餐、商品分组、分类、门店商品、库存、配方、税率
`catering-vue-international`	餐饮业务订单、门店经营设置、堂食、外卖、排队、桌台	餐饮订单、售后、外卖、买单、取餐、预约、排队、KDS、桌台
`std-vue-international`	标准商城订单和售后轻量项目	商城订单、商城售后、商城设置
`coupon-vue-international`	优惠券、卡券、券活动、券核销和第三方券	券模板、券规则、卡券、实体卡、第三方券、团购券、券分析
`marketing-vue-international`	营销活动中心、广告、促销玩法和营销配置	满减、促销、广告、会员价、推广员、帖子、营销管控
`cmk-vue-international`	CMK 营销画布、营销流程和活动编排	营销画布、营销工作流、流程统计、活动编排、专属分享
`member-vue-international`	会员中心、会员资料、等级积分、会员营销和第三方会员渠道	会员列表、标签、画像、RFM、积分、等级、付费会员、精准营销
`payment-vue-international`	支付、商户、台账、终端、钱包和会员资产	支付配置、商户、交易订单、终端、台账、钱包、会员资产
`message-vue-international`	消息中心、消息渠道、订阅消息和消息推送	短信、微信渠道、消息推送、推送记录、订阅消息
`connector-vue-international`	连接器事件中心和审批运营平台	事件中心、事件详情、审批管理、创建审批
`operating-vue-international`	运营平台、应用中心、业务中心、帮助中心和平台能力	应用市场、业务中心、连接器、数据标准、帮助中心、工单、SDK
`scm-vue-international`	供应链、采购、仓储、配送、生产、分拣和库存流转	供应商、仓库、采购、调拨、入库、出库、配送、生产、分拣
`bi-vue-international`	传统 BI、经营报表、数据分析、大屏和指标看板	数据中心、经营报表、商品分析、会员分析、热力图、财务报表
`qmbi-vue-international`	新版自助 BI、报表设计、数据集、数据源和工作空间	分析设计器、报表、数据立方体、数据源、数据集、工作空间

常见混淆边界

容易混淆	判断方式
`bi-vue-international` 和 `qmbi-vue-international`	传统经营报表看 `bi`；自助 BI、报表设计器、数据集、工作空间看 `qmbi`
`marketing-vue-international` 和 `cmk-vue-international`	常规活动、广告、促销看 `marketing`；营销画布和工作流看 `cmk`
`catering-vue-international` 和 `std-vue-international`	餐饮完整订单链路看 `catering`；标准商城订单和售后轻量项目看 `std`
`connector-vue-international` 和 `operating-vue-international`	事件中心和审批看 `connector`；平台运营、应用、业务中心看 `operating`
`common-vue-international` 和业务子应用	多业务复用、公共配置、公共模板看 `common`；单业务页面看对应业务仓
打印模板和打印运行时	模板和纸面内容看 `common`；插件、桥接、运行时代码看 `operation`

样式和组件归属

问题	优先归属
菜单、头部、壳层、容器、全局主题	`console-vue-international`
当前业务页面布局和局部样式	当前业务子应用
多仓重复出现的组件视觉或行为	`vue-kylin-international`
公共业务页或打印模板视觉	`common-vue-international`
打印插件、桥接、国际打印代码	`operation`

涉及 UI、UX、页面布局、组件视觉、长文本或 RTL 时，必须先读 UI 详细设计规范。

给新人记住的口诀

先问系统，再问仓库；先看职责，再看代码。

共享问题回组件库，壳层问题看基座，公共页看 common，打印运行时看 operation。

Qmai 国际后台 UI 详细设计规范

Thu, 28 May 2026 00:00:00 GMT

UI 详细设计规范用于 Qmai 国际后台页面和组件。

它的重点不是“让页面更花”，而是让后台业务界面更清晰、更稳定、更适合国际化。

什么时候必须读

只要任务涉及下面任意内容，就要先读 UI 规范：

新增或改造后台页面。
页面布局、视觉层级、表格、筛选区、配置页。
组件视觉、弹窗、选择器、工作台、画布页。
长文本、多语言、RTL。
console-vue-international 壳层和容器视觉。
common-vue-international 公共页或打印模板视觉。
vue-kylin-international 共享组件视觉和交互。

这套 UI 的定位

Qmai 国际后台是给连锁餐饮总部、区域运营、门店管理、实施、财务、营销和配置人员使用的高频工作台。

它不是：

营销官网。
数据大屏秀场。
通用 SaaS 卡片模板。
每个仓库各自发明风格的拼盘。

它应该是：

专业。
克制。
清晰。
高信任。
可复用。
国际化友好。

五个核心原则

原则	解释
结构先于装饰	优先用布局、对齐、分组、边框、留白解决问题
层级先于颜色	标题、主信息、辅助信息先通过位置和字号表达
绿色是默认动作色	主动作、启用态、正向状态优先使用绿色体系
白底是工作面	普通业务内容区保持白底和清晰边界
页面先归类，再设计	先判断页面类型，再套合适骨架

页面类型

新增或改造页面时，先判断它属于哪种类型。

页面类型	适合场景	设计重点
列表页	订单、商品、会员、优惠券等列表	表格是主角，筛选区清晰，主 CTA 不抢查询按钮
配置页	规则、开关、策略、参数配置	保存路径稳定，说明短而准确
全屏编辑器	深度编辑、复杂表单、规则编排	顶部返回和保存明确，分区节奏统一
选择器	商品、门店、渠道、会员等选择	搜索、分页、选中态和已选汇总清楚
工作台 / 画布页	打印模板、票据预览、设计编辑器	画布是主角，配置器是辅助
数据总览页	KPI、趋势、排行、异常关注	数据帮助行动，不做装饰性大屏

如果无法归入这些类型，再考虑新增页面骨架。

组件规则

按钮

同一区域只保留一个最高权重主按钮。
删除、停用、解绑等危险操作不能用主绿色。
按钮文案走 i18n，不依赖中文短文案固定宽度。

表单

label、输入区、提示和错误状态要清晰。
长文本和多语言场景不能固定死宽。
必填、校验、保存中、禁用状态必须完整。

表格

列表页优先保留主身份字段。
状态使用浅底胶囊或清晰文本，不只靠颜色表达。
行内操作超过 3 个时考虑收进更多菜单。

弹窗和抽屉

轻确认用弹窗。
复杂编辑用全屏页或专门编辑器。
高风险弹窗必须写清影响范围和后果。

卡片和容器

普通业务内容使用白底、轻边框、少阴影。
不把列表页做成卡片墙。
不在卡片里再嵌套卡片。

原型还原和组件边界

产品原型已经给出明确结构时，优先还原业务页内部体验。

但要注意：

不复制示例工程的壳层、侧栏、导航或调试水印。
不为了复用 Element UI 而牺牲关键业务结构。
已有成熟能力，例如商品选择、门店选择、渠道选择，应先搜索项目和 vue-kylin-international 是否已有组件。
接口没有字段承载的说明性提示，不应做成可保存、可切换的配置控件。

技术归属

UI 问题	优先处理位置
菜单、头部、侧栏、容器、主题注入	`console-vue-international`
当前业务页面局部布局	当前业务子应用
多仓重复出现的组件视觉或行为	`vue-kylin-international`
公共业务页、打印模板、票据预览	`common-vue-international`
打印插件、桥接、国际打印运行时代码	`operation`

共享组件问题不要在多个业务仓库复制补丁。

i18n、RTL 和可访问性

UI 改动必须考虑国际化：

所有新增可见文案进入仓库既有 i18n 流程。
不把中文、英文或临时文案硬编码进模板。
长英文、泰文、阿语等文本要预留换行和宽度。
尽量使用 gap、逻辑属性或自适应布局，避免只写 margin-left、padding-left。
颜色不能成为唯一状态表达，必须有文字或图标辅助。
focus、loading、disabled、empty、error 状态要完整。

样式落地规则

局部样式优先写在当前组件 scoped 样式里。
微前端全局样式必须加项目级前缀，避免污染其他子应用。
不为单个需求新增全局样式文件，除非已有模块模式要求。
优先复用仓库已有 CSS 变量和组件库 token。
不引入新的 UI 依赖或图标体系。
不用大面积浅彩背景、彩色阴影、过大圆角制造高级感。

设计系统预览模板

新版规则中心新增了可运行的 Vue2 预览模板，位置在：

04-样式与组件库/设计系统预览模板/

它的作用是把抽象 UI 规则翻译成一张可以对照的后台页面。

看布局：侧栏、页面头、内容区和工作台区域怎么分层。
看组件：按钮、状态、表单、表格、空状态、确认弹窗怎么保持一致。
看边界：页面局部样式、共享组件、打印/票据预览分别应该落到哪里。
看国际化：文案只是预览 fallback，进入业务代码时必须换成目标仓库 i18n key。

模板页面预览

下面是文档内的静态预览。完整运行版以新版规则中心里的 Vue2 组件为准。

<div class="qmai-doc-preview"> <aside class="qmai-doc-preview__rail"> <div class="qmai-doc-preview__brand"> <div class="qmai-doc-preview__mark">Q</div> <div> <strong>Qmai International</strong> <span>Design System</span> </div> </div> <div class="qmai-doc-preview__nav"> <span>设计原则</span> <span>颜色与层级</span> <span>按钮与状态</span> <span>表单与表格</span> <span>反馈与弹窗</span> <span>工作台画布</span> </div> </aside> <main class="qmai-doc-preview__main"> <section class="qmai-doc-preview__head"> <div> <h3>组件库预览</h3> <p>用于统一国际后台的按钮、表单、表格、状态、弹窗和工作台类页面视觉基线。</p> </div> <div class="qmai-doc-preview__actions"> <span class="qmai-doc-preview__button">导出规范</span> <span class="qmai-doc-preview__button qmai-doc-preview__button--primary">应用模板</span> </div> </section> <section class="qmai-doc-preview__section"> <div class="qmai-doc-preview__section-head"> <h4>设计原则</h4> <p>先定结构，再做视觉；先判断归属，再落代码。</p> </div> <div class="qmai-doc-preview__grid"> <div class="qmai-doc-preview__card"> <span class="qmai-doc-preview__index">01</span> <strong>Structure Before Decoration</strong> <p>先用结构、对齐、留白和信息顺序解决问题。</p> </div> <div class="qmai-doc-preview__card"> <span class="qmai-doc-preview__index">02</span> <strong>One Action Authority</strong> <p>一个局部区域只保留一个最高权重动作。</p> </div> <div class="qmai-doc-preview__card"> <span class="qmai-doc-preview__index">03</span> <strong>Shared Component First</strong> <p>重复组件问题优先回到共享组件库处理。</p> </div> </div> </section> <section class="qmai-doc-preview__section"> <div class="qmai-doc-preview__section-head"> <h4>颜色与层级</h4> <p>绿色承担动作，中性色承担大部分界面表达。</p> </div> <div class="qmai-doc-preview__grid"> <div class="qmai-doc-preview__swatch"> <span class="qmai-doc-preview__color" style="background:#1fc069"></span> <span class="qmai-doc-preview__meta"><strong>Color Primary</strong><span>主按钮 / 启用态</span></span> </div> <div class="qmai-doc-preview__swatch"> <span class="qmai-doc-preview__color" style="background:#e9f9f0"></span> <span class="qmai-doc-preview__meta"><strong>Primary Light</strong><span>选中浅底 / 状态浅底</span></span> </div> <div class="qmai-doc-preview__swatch"> <span class="qmai-doc-preview__color" style="background:#101828"></span> <span class="qmai-doc-preview__meta"><strong>Ink 900</strong><span>页面标题 / 强标题</span></span> </div> </div> </section> <section class="qmai-doc-preview__section"> <div class="qmai-doc-preview__grid qmai-doc-preview__grid--two"> <div class="qmai-doc-preview__card"> <h4>按钮</h4> <div class="qmai-doc-preview__row"> <span class="qmai-doc-preview__button qmai-doc-preview__button--primary">保存</span> <span class="qmai-doc-preview__button">取消</span> <span class="qmai-doc-preview__button qmai-doc-preview__button--danger">删除</span> </div> <p>危险操作不用主绿色，保存中、禁用态、二次确认都要完整。</p> </div> <div class="qmai-doc-preview__card"> <h4>状态</h4> <div class="qmai-doc-preview__row"> <span class="qmai-doc-preview__pill qmai-doc-preview__pill--success">已启用</span> <span class="qmai-doc-preview__pill qmai-doc-preview__pill--info">待同步</span> <span class="qmai-doc-preview__pill qmai-doc-preview__pill--warn">需确认</span> <span class="qmai-doc-preview__pill qmai-doc-preview__pill--danger">失败</span> </div> <p>状态必须有文字，不只依赖颜色表达。</p> </div> </div> </section> <section class="qmai-doc-preview__section"> <div class="qmai-doc-preview__grid qmai-doc-preview__grid--two"> <div class="qmai-doc-preview__card"> <h4>表单</h4> <div class="qmai-doc-preview__field"> <label>模板名称</label> <div class="qmai-doc-preview__input">总部默认票据模板</div> </div> <div class="qmai-doc-preview__field"> <label>适用范围</label> <div class="qmai-doc-preview__select">全部门店</div> </div> <div class="qmai-doc-preview__field"> <label>备注</label> <div class="qmai-doc-preview__textarea">给运营人员看的短说明，长文本需要可换行。</div> </div> </div> <div class="qmai-doc-preview__card"> <h4>表格</h4> <div class="qmai-doc-preview__toolbar"> <div class="qmai-doc-preview__search">搜索名称、编码或门店</div> <span class="qmai-doc-preview__button qmai-doc-preview__button--primary">查询</span> <span class="qmai-doc-preview__button">重置</span> </div> <div class="qmai-doc-preview__table-wrap"> <table> <thead> <tr> <th>模板名称</th> <th>编码</th> <th>状态</th> <th>操作</th> </tr> </thead> <tbody> <tr> <td>总部默认票据模板</td> <td>TPL-001</td> <td><span class="qmai-doc-preview__pill qmai-doc-preview__pill--success">已启用</span></td> <td>编辑 · 复制</td> </tr> <tr> <td>外卖渠道小票模板</td> <td>TPL-002</td> <td><span class="qmai-doc-preview__pill qmai-doc-preview__pill--info">待同步</span></td> <td>编辑 · 复制</td> </tr> </tbody> </table> </div> </div> </div> </section> <section class="qmai-doc-preview__section"> <div class="qmai-doc-preview__grid qmai-doc-preview__grid--two"> <div class="qmai-doc-preview__card"> <h4>空状态</h4> <div class="qmai-doc-preview__empty"> <div> <div class="qmai-doc-preview__empty-icon"></div> <strong>当前筛选条件下暂无数据</strong> <p>调整筛选条件，或新建一个模板后继续配置。</p> <span class="qmai-doc-preview__button qmai-doc-preview__button--primary">新建模板</span> </div> </div> </div> <div class="qmai-doc-preview__card"> <h4>确认弹窗</h4> <div class="qmai-doc-preview__dialog"> <strong>停用模板</strong> <p>停用后，关联门店将不再使用该模板。请确认已有替代模板。</p> <div class="qmai-doc-preview__row" style="margin-top:12px"> <span class="qmai-doc-preview__button">取消</span> <span class="qmai-doc-preview__button qmai-doc-preview__button--danger">确认停用</span> </div> </div> </div> </div> </section> <section class="qmai-doc-preview__section"> <div class="qmai-doc-preview__section-head"> <h4>工作台 / 画布页</h4> <p>画布是主角，配置器是辅助；适合打印模板、票据预览、设计编辑器。</p> </div> <div class="qmai-doc-preview__workbench"> <div class="qmai-doc-preview__tools"> <span>返回</span> <span>预览</span> <span>校验</span> <span>发布</span> </div> <div class="qmai-doc-preview__paper"> <div class="qmai-doc-preview__paper-head"></div> <div class="qmai-doc-preview__line qmai-doc-preview__line--long"></div> <div class="qmai-doc-preview__line"></div> <div class="qmai-doc-preview__line qmai-doc-preview__line--long"></div> <div class="qmai-doc-preview__line"></div> <div class="qmai-doc-preview__total"></div> </div> <div class="qmai-doc-preview__inspector"> <h4>配置器</h4> <p>布局密度</p> <div class="qmai-doc-preview__bar"></div> <p>打印模块</p> <div class="qmai-doc-preview__select">订单信息</div> </div> </div> </section> </main> </div>

运行版入口

新版规则中心提供三种查看方式：

方式	适合场景	入口
独立本地预览项目	不依赖业务仓库，直接查看完整模板	`standalone-preview-app/`
嵌入式预览入口	复用 `common-vue-international` 已安装依赖，不修改业务代码	`embedded-preview/main.js`
Vue2 单文件组件	挂到目标仓库临时路由或作为评审对照页	`components/QmaiInternationalDesignSystemPreview.vue`

独立预览启动命令：

cd <qmai-rule-root>/04-样式与组件库/设计系统预览模板/standalone-preview-app
pnpm install
pnpm dev

嵌入式预览启动命令：

cd <common-vue-international-root>
./node_modules/.bin/vue-cli-service serve \
  <qmai-rule-root>/04-样式与组件库/设计系统预览模板/embedded-preview/main.js \
  --host 127.0.0.1 \
  --port 5177

预览模板不是生产业务页面。真正进入业务代码时，示例数据和 fallback 文案必须替换为目标仓库的真实数据与 i18n key；重复组件问题优先回到 vue-kylin-international，不要在多个业务仓库复制补丁。

交付前检查

这页属于哪种页面类型？
主工作面是否明确？
页面标题是否可以减少一层？
文案是否都走 i18n？
是否出现多个同权重主按钮？
是否把列表页做成卡片墙？
是否把壳层装饰带进内容区？
保存、返回、确认路径是否稳定？
是否需要联查基座或组件库？
RTL 和长文本是否会撑破布局？
空、错、加载、禁用、保存中状态是否完整？

一句话总结

Qmai 国际后台 UI 不是追求装饰感，而是追求清楚、有秩序、可复用、能承载真实业务操作。

中国大陆用户通过 Google Play 订阅 ChatGPT / Codex 会员教程

Mon, 25 May 2026 00:00:00 GMT

大陆用户想给 ChatGPT / Codex 开会员，麻烦主要出在付款上。走 Google Play 订阅是一条相对省心的路：把一张支持海外线上支付的 Visa 卡绑到 Google 账号，然后在安卓环境里通过应用内订阅完成付款。后续的扣费、退款、取消订阅都由 Google Play 统一管理，不用再和别的支付渠道打交道。

这条路门槛不高：一个 Google 账号，一张能海外线上支付的 Visa 卡，再加一台安卓手机——没有安卓手机也没关系，电脑上装个 BlueStacks 模拟器一样能走通。下面按实际操作顺序过一遍。

先把要用的东西备齐

具体来说，你需要：

一个可以正常登录的 Google 账号
一张支持海外线上支付的 Visa 信用卡或借记卡
一台安卓手机，或一台能装安卓模拟器的电脑
一个可以正常登录的 ChatGPT 账号

都齐了就可以开始绑卡。

打开 Google 账号的付款页面

绑卡在网页端完成。浏览器打开 Google 账号的付款与订阅页面：

https://myaccount.google.com/payments-and-subscriptions

登录后进入 钱包和订阅 页面，找到 付款方式 区域，点击 管理付款方式。

绑定 Visa 卡

在付款方式管理页面选择添加新的银行卡，填上 Visa 卡信息。几个容易踩坑的点：

持卡人姓名要和银行卡信息一致
卡号、有效期、CVV 按银行卡实际信息填写
账单地址可以从 https://usaddressgen.com/tax-free-address/ 复制一个美国免税州的随机地址，能免去税费
支付失败的话，先检查银行卡有没有开境外线上支付权限

绑定成功后回到付款方式页面，确认这张卡已经保存在当前 Google 账号下。到这里网页端的事就做完了，接下来切到安卓环境。

安装 ChatGPT App

订阅要在 App 内完成，所以需要一个能跑 Google Play 的安卓环境，有没有安卓手机都行。

有安卓手机

直接打开 Google Play 商店，搜索并安装 ChatGPT。装之前确认一下应用名称是 ChatGPT、开发者是 OpenAI，别装错。

没有安卓手机：用 BlueStacks

在电脑上装 BlueStacks 安卓模拟器，下载地址：

https://www.bluestacks.com/

装好后：

打开 BlueStacks
登录前面绑好 Visa 卡的那个 Google 账号
打开 Google Play 商店
搜索 ChatGPT
安装 OpenAI 官方的 ChatGPT App

在 Google Play 下载 ChatGPT

不管用手机还是模拟器，最后都是在 Google Play 里搜 ChatGPT，进入 OpenAI 官方应用页面。

页面显示安装就直接点安装；显示打开或更新，说明应用已经装过了，直接打开或先更新到最新版都行。

登录并订阅会员

App 装好就到最后一步了。打开 ChatGPT App：

登录你的 ChatGPT 账号
进入账号、设置或订阅页面
选好要升级的会员方案
核对 Google Play 弹出的订阅付款信息
用前面绑定的 Visa 卡完成支付

支付成功后回到 App 里看一眼，确认会员状态已经生效。没生效的话，往下看常见问题。

常见问题

Google 绑卡失败怎么办

优先检查这几项：

Visa 卡是否支持海外线上支付
银行卡是否开了境外支付权限
账单地址是否与付款方式信息一致
Google 账号是否存在付款资料异常或风控限制

Google Play 搜不到 ChatGPT 怎么办

多半和 Google Play 的账号地区、设备环境或网络环境有关。可以确认：

Google Play 是否已经正常登录
当前网络是否稳定
搜索结果里的开发者是不是 OpenAI
当前 Google Play 环境是否支持显示该应用

账单地址怎么填更稳妥

如果比起省税费你更在意稳定，建议按这个顺序确认：

优先以银行卡发卡行登记的账单地址为准
持卡人姓名、卡号、账单地址尽量保持一致
不确定发卡行预留地址的，先联系银行客服确认
不要用地址生成器、代填地址或所谓“免税州地址”去试

订阅成功但会员没生效怎么办

可以依次试试：

退出并重新登录 ChatGPT App
等几分钟后刷新订阅状态
到 Google Play 的订阅页面确认付款是否成功
还不行就联系 Google Play 或 OpenAI 官方支持

最后几点提醒

不要在非官方渠道买所谓的低价会员或代充服务
订阅扣费、退款和取消订阅通常由 Google Play 管理
会员权益和可用功能以 ChatGPT App 内实际展示为准

打造完美的网络分流体验：订阅转换与自定义规则指南

Thu, 12 Feb 2026 00:00:00 GMT

日常用 Clash、Surge、Sing-box 这类代理软件时，机场默认订阅的规则往往比较臃肿，分流不够准，也不一定符合自己的使用习惯。

订阅转换（Subscription Converter）就是解决这个问题的：把原始订阅链接转换成各客户端能用的格式，同时换上自己的分流规则。

这篇记录一下我用在线工具加载自己维护的规则（CustomRules）的流程，顺便解释转换后那些策略组各自是干什么的，遇到“节点连不上”时也好自己排查。

工具准备

需要两个东西：

在线订阅转换工具：

打开 ACL4SSR 在线转换

这是一个基于 Subconverter 搭建的前端页面，界面简洁，支持输出多种主流客户端格式。
个人自用规则（Remote Config）：
- 规则地址（点击右侧复制按钮）：
```
https://raw.githubusercontent.com/lkhmm520/ssr-rules/refs/heads/main/CustomRules.ini
```
- 这是我按日常开发和使用习惯整理的规则集，包含去广告、国内直连优化和流媒体分流。

:::note 为什么不直接用机场自带规则？

相比机场默认配置，这套规则有几个好处：

去广告：内置了广告拦截规则。
分流更准：区分国内外流量，访问百度不会绕道代理。
对开发友好：GitHub、StackOverflow 等常用站点做了单独处理。 :::

基础流程：转换订阅

第一步：填写基础信息

打开 ACL4SSR。
在 “订阅链接” 中粘贴你的机场订阅地址（多个链接用 | 分隔，或直接换行）。
“后端地址” 建议选自建后端，或 api.wcc.best 这类可用性较好的后端，转换更稳定。

第二步：加载自定义规则（关键）

在 “远程配置” 下拉框中选择 “Custom（自定义）”，把上面准备好的规则地址粘贴进去。

第三步：生成并导入

客户端：选择你使用的软件（如 Clash、Surge 等）。
点击 “生成订阅链接”。
点击 “一键导入”，客户端里就能看到新的配置文件。

用网页功能微调节点

如果不想 fork 代码，只是想过滤掉一些没用的节点（比如“过期时间”“官网”这类信息节点），或者只保留特定国家的节点，直接用 ACL4SSR 网页自带的高级功能就够了。

点击页面上的 “更多选项” 展开高级菜单：

排除节点（Exclude Nodes）

有些机场订阅里混着不少纯信息节点，可以按关键词过滤掉。

操作：在“排除节点”输入框中填写正则表达式。
示例：
```
(流量|时间|官网|产品|过期|剩余)
```
名字里包含“流量”“官网”等字眼的节点都会被丢弃。

包含节点（Include Nodes）

如果只想保留某几个地区的节点（比如美国、日本、新加坡），用这个。

操作：在“包含节点”输入框中填写。
示例：
```
(US|SG|JP|美国|新加坡|日本)
```
转换出的订阅将只保留匹配这些关键词的节点，其余全部丢弃。

重命名节点

机场节点命名混乱的话，可以用“正则替换”批量改名。比如把 [高级机场] 香港 01 改成 🇭🇰 香港 01，列表会整齐不少。

策略组说明：转换后怎么选

导入后会看到一堆“自动选择”“手动选择”“漏网之鱼”，这里按我的规则逻辑逐个解释，方便按场景选择。

节点选择（Proxy）

总开关，决定所有需要走代理的流量默认走哪条路。

推荐设置：自动选择 或 手动选择。

自动选择（Auto / UrlTest）

机制：客户端自动测试所有节点的延迟，切换到延迟最低的那个。
适用场景：不想操心选节点的话，用它就行。

漏网之鱼（Final / Match）

含义：当一个网址既不在国内直连名单，也不在广告屏蔽名单，没有命中任何规则时，就会落到这里。
推荐设置：节点选择 或 自动选择。
注意：如果某些冷门国外网站打不开，先检查这个选项是不是被设成了 Direct（直连）。

AI 平台（ChatGPT / Gemini / Claude）

OpenAI 等平台对地区限制很严，这一组需要单独注意。

不要选香港（HK）、澳门（MO）或台湾（TW）节点，很容易被封号或无法访问。
建议手动指定新加坡（SG）、日本（JP） 或 美国（US） 节点。

流媒体与应用分组（Netflix、Telegram 等）

规则里对常见服务做了独立分组。

作用：可以给 Netflix 单独指定一个“新加坡”节点，同时让 Telegram 走“美国”节点，互不干扰。
推荐设置：自动选择，或手动指定对应地区的节点。

广告拦截（AdBlock）

推荐设置：REJECT（拒绝连接）。
作用：直接阻断广告域名的请求，省流量，页面也干净。

自己维护规则

如果对现有规则还有不满意的地方，想自己定义策略组，可以直接改模板。

CustomRules.ini 本质上是一个模板文件，里面可以定义：

Rule Sets（规则集）：引用外部的 list 文件（如 GeoIP、AdBlock 列表）。
Proxy Groups（策略组）：定义“自动选择”“手动选择”“故障转移”等分组逻辑。

想在我的规则基础上改，可以 fork lkhmm520/ssr-rules，修改 CustomRules.ini 后，在转换时填入你自己的 Raw URL 即可。

Codex CLI 使用指南

Thu, 29 Jan 2026 00:00:00 GMT

Codex CLI 是 OpenAI 推出的终端编码代理：不用切浏览器，直接在本地仓库里和 AI 对话，它能读你的文件、执行命令、改代码，而且每一步执行都有审批机制兜底。如果你习惯待在终端里干活，又厌倦了在网页 Chat 和编辑器之间来回粘贴上下文，这个工具值得一试。

这篇文章把我整理的安装、常用命令、AGENTS.md、MCP 和 Skills 的用法都过一遍，基本覆盖日常使用场景。

为什么选 Codex CLI

先用一张表对比它和传统网页 Chat 的差异，核心就是"上下文"和"可控性"这两点：

维度	传统 AI Chat 对话	Codex CLI
入口	浏览器/网页为主	终端统一入口，直接在本地仓库内工作（编辑器无关）
上下文	主要靠手动粘贴/描述	可读取仓库文件与变更，任务上下文持续
可信控制	缺少命令级审批与执行控制	内建审批模式与会话状态，可控制何时执行命令
复用能力	以对话模板/复制粘贴为主	支持内置 Slash 命令、可扩展 Prompt 与 Skill
扩展	需要手动切换外部工具	通过 MCP 接入第三方工具与上下文（如 Figma）

安装与启动

全局装一个 npm 包就行：

npm i -g @openai/codex

然后进入你的项目目录，直接运行：

codex

首次运行会提示登录，用 ChatGPT 账号或 API key 都可以。

常用快捷键

进入交互界面后，这几个快捷键用得最多，建议先记住 /、@ 和 ! 三个：

/：命令列表
!：Shell 命令
Ctrl+J：换行
@：补全文件路径
Ctrl+G：外部编辑器输入
Ctrl+T：查看对话记录
Ctrl+C：退出
Tab：排队发送消息
Ctrl+V：粘贴图片（Mac/Windows/Linux 通用）
Esc Esc：编辑上一条消息

Slash 命令速查

在 CLI 里输入 / 会弹出命令列表，支持模糊过滤。内置命令不多，一张表就能列全：

命令	用途
/approvals	设置审批模式（例如只读/自动/需确认）
/compact	对话压缩，保留要点
/diff	查看 Git diff（含未跟踪文件）
/exit /quit	退出 CLI
/feedback	发送诊断与反馈
/init	生成 AGENTS.md 模板
/logout	退出登录
/mcp	查看已配置 MCP 工具
/mention	添加文件/路径到上下文
/model	切换模型
/new	开新对话（同目录）
/review	代码/改动审查
/status	查看会话配置与状态
/undo	撤销最近一次变更

一套典型的工作流程

上面的命令单看有点抽象，串成一个实际流程就清楚了：初始化、设权限、加上下文、看改动、审查。

初始化项目指令

/init

生成 AGENTS.md 模板，作为项目级指令入口，后面会专门讲怎么写。

限制或放开权限

/approvals

选择审批策略（例如只读/自动/需确认）。第一次用建议保守一点，熟了再放开。

把关键文件加入上下文

这一步的核心是：把你正在处理的关键文件加入上下文，不必拘泥固定路径。两种常见场景：

如果有现成文件（例如纯 HTML 待办演示）：
```
/mention index.html
```
如果目录暂时还不存在（或准备新建）：
```
/mention README.md
```
然后让 Codex 生成/创建你要的目标文件。

文件加入上下文后，后续指令会自动带上，联动修改很方便。

查看和审查改动

改完之后先看 diff，再让它自己审一遍：

/diff
/review

实战：生成一个纯 HTML 待办页

拿一个完整例子走一遍上面的流程。目标：生成一个可直接打开的静态待办页面（HTML + CSS + 原生 JS，支持本地保存）。

先准备一个空项目：

mkdir codex-demo-page
cd codex-demo-page
touch index.html
codex

然后在 Codex CLI 里直接描述需求：

请生成一个纯 HTML 待办事项页面：包含任务输入、列表、完成状态、筛选（全部/未完成/已完成），数据存 localStorage；要求响应式、排版清晰、配色干净。

生成后检查改动：

/diff
/review

想在浏览器里看效果，起个本地服务即可：

python -m http.server 8000

AGENTS.md：给仓库写持续指令

AGENTS.md 的作用是为当前仓库提供持续生效的指令，Codex 会自动读取并遵守——相当于把你每次都要重复交代的规矩写死在仓库里。用 /init 就能生成模板。

下面是我推荐的模板结构，可以直接复制改：

# AGENTS.md

## Repository Guidelines

### 项目结构与模块组织
- 说明主要目录与模块的职责边界
- 指出入口文件与页面组件位置

### 构建与开发命令
- 统一列出安装、开发、构建、预览命令

### 编码风格
- 缩进、命名规范、组件职责边界

### 数据存储与约束
- localStorage key 命名、后端接口、字段约束

### 代码审查重点
- 修改功能时需补充的测试点
- 高风险模块注意事项

### 输出要求（每次改动后需说明）
- 说明改动内容（做了什么）
- 说明影响范围（哪些文件/模块/功能受影响）
- 提供回滚或兜底方案（如何恢复到改动前）

MCP：接入外部工具

MCP（Model Context Protocol）让 Codex 能接入第三方工具与上下文，比如设计稿、浏览器、文档。下面以 Figma 为例，两种配置方式任选。

方式一，直接用命令行添加：

# 使用 HTTP MCP Server（以 Figma 为例，URL 以实际服务商提供为准）
codex mcp add figma --url https://mcp.figma.com/mcp

# 查看已配置的 MCP 列表
codex mcp list

方式二，写配置文件（项目级或全局都行）：

# ~/.codex/config.toml 或 <repo>/.codex/config.toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

配置好之后，在 CLI 里输入 /mcp 就能查看已接入的工具。

Skills：把常用流程封装成可复用能力

如果你有一套固定流程反复在用（比如每天生成日报），可以封装成 Skill。

一个 Skill 长什么样

Skill 就是一个文件夹，核心是 SKILL.md（必需），外加可选的 scripts/、references/、assets/。SKILL.md 用 YAML Front Matter 描述元信息（至少 name 与 description），正文写具体流程说明。

怎么触发

Codex 启动时会扫描可用 Skill，但只读取 name 与 description 用于匹配；只有被触发时才加载完整内容，所以不用担心 Skill 多了拖慢上下文。触发方式两种：

显式：输入 /skills 选择，或在提示中直接写 $skill-name
隐式：当任务描述与 Skill 的 description 匹配时，Codex 自动启用

保存位置

Codex 会按由近到远的顺序扫描这些目录：

$CWD/.codex/skills
$CWD/../.codex/skills
$REPO_ROOT/.codex/skills
$CODEX_HOME/skills（macOS/Linux 默认 ~/.codex/skills）
/etc/codex/skills
系统内置 Skills（随 Codex 发布）

注意同名 Skill 不会去重，选择器里可能同时出现多个。技能目录用软链接也是支持的。

创建与安装

方式 1：使用内置 $skill-creator 在 Codex CLI 中描述你要的能力，Codex 会引导你创建 Skill。

方式 2：手动创建 在任意有效技能目录下创建文件夹与 SKILL.md，保存后重启 Codex 生效。

安装官方示例（experimental）

$skill-installer install the create-plan skill from the .experimental folder

安装完成后同样需要重启 Codex。

SKILL.md 完整示例

拿一个"生成 git 日报"的 Skill 做例子，可以直接复制改：

---
name: Daily Git Log Report
description: 根据指定目录路径生成日报摘要
---

## 目标
在指定仓库与目录范围内，收集当天 git log 并生成日报摘要。

## 输入要求
在执行前向用户确认以下信息：
1) REPO_PATH：仓库路径（绝对路径）
2) FOCUS_PATH：仅统计的目录或文件路径（相对 REPO_PATH）
3) DATE：日报日期（YYYY-MM-DD；若未提供则使用当天）

## 执行步骤
1) 在 shell 中执行 git log，范围限定为 DATE 当天。
2) 排除 merge commit。
3) 输出清单 + 摘要两段。

## 命令模板
git -C "$REPO_PATH" log \
  --since "$DATE 00:00" \
  --until "$DATE 23:59" \
  --no-merges \
  --date=short \
  --pretty=format:"%h %ad %s (%an)" \
  -- "$FOCUS_PATH"

## 输出格式

### Commit 清单

- 逐条列出：hash + 日期 + 标题 + 作者

### 日报摘要

- 归纳为 3~6 条重点
- 按功能模块或主题归类

没有 Hooks？替代方案

官方文档目前聚焦在 Slash 命令、Skills 和 MCP 上，没有描述与"自动触发 Hook"等价的机制。想要类似效果，可以这样绕：

Git hooks：在 pre-commit / pre-push 中调用 Codex 或固定脚本
Skills：把流程固化成可分享的能力（比脚本更可读）

总结

Codex CLI 本质上是一个跑在终端里的本地编码代理，直接在你的仓库里执行、编辑与协作。它解决的是网页 Chat 的几个老问题：上下文零散、工具切换频繁、流程难复用、权限不可控。上手成本不高，装完先用 /init 和 /approvals 把规矩立好，再把常用流程沉淀成 AGENTS.md 和 Skills，日常开发里能省下不少重复沟通。

LOOK

PortLoom 教程：用一台 VPS 把 NAS 服务发布到公网

PortLoom 的工作方式

开始前要准备什么

1. 公网 VPS

2. NAS 或内网服务器

3. 域名和 DNS

在 VPS 安装 PortLoom Server

在 WebUI 添加 NAS

在 NAS 安装 Agent

发布第一个服务

怎么看懂三层状态

Local

Tunnel

Public

常见故障怎么排

1. 控制台打不开

2. Agent 无法注册

3. Gateway 返回 404

4. Gateway 返回 502

5. 页面能开，但视频或大文件异常

备份和升级

几个安全细节

适合哪些场景

VPS 购买、重装 Ubuntu 与 3X-UI 面板搭建教程

购买 VPS（以搬瓦工为例）

注册账号并完成支付

进入 My Services 并打开 KiwiVM

重装 Ubuntu 22.04

安装 Termius 并连接 VPS

安装 3X-UI 面板

添加入站节点

有域名时的 TLS 方案

复制节点并导入客户端

安全建议

Qmai Playbook 索引：AI 执行手册清单

使用前先读

Playbook 清单

为什么不把路由写在索引里

使用示例

新增 playbook 的规则

Qmai 项目识别：先判断项目角色，再选择规则

三步判断法

1. 找到当前项目根目录

2. 判断是否是 Qmai 项目

3. 判断系统角色

*-vue-international 必须查职责清单

Vite 不是优先判断依据

输出结果应该包含什么

Qmai 国际前端规则模式：让 AI 先懂业务边界，再写代码

它是什么

为什么需要它

新版规则怎么分层

一个需求如何被处理

最重要的规则

1. 先判断仓库，不先写代码

2. UI 任务先读 UI 详细规范

3. 打印要分清两个世界

4. 可选发布阶段有独立约束

5. AI 不主动做高风险动作

核心价值

Qmai 工作流路由：一个任务应该走哪条流程

路由前先做两件事

路由原则

任务路由表

路由后的输出要求

常见误区

Qmai 全局约束：AI 做事前先守住这些底线

1. 修改前先说清楚

2. 先读上下文，再改代码

3. 跨仓影响要先分析

4. 代码改动保持最小

5. 接口规则

6. UI、i18n 和 RTL

7. 飞书内容先读取，再判断

8. Git 和发布不能越界

9. 最小自查

Qmai 维护映射：规则变更后怎么同步

为什么需要维护映射

新版维护原则

`*-vue-international` 必须查职责清单

`*-vue-international` 仓库职责清单