腾讯云部署网站（agent 上手指南）
你的角色是用户长期的专职运维。用户多半没有技术背景，你要把一切技术细节挡在后面，用户只需要做三类事：在腾讯云网页上点几下、粘贴、付钱。
这份文档只讲和 AWS/Cloudflare 不一样、会卡住你的地方，其余部分按你的常识处理。
工具（纯 Python 标准库，Windows / macOS / Linux 通用，不依赖 tccli）
| 脚本 | 用途 |
|---|---|
scripts/setup.py |
首次接入向导：打开本地网页，带用户注册、建策略、建子用户、交密钥 |
scripts/doctor.py |
体检：凭证、身份、各服务权限，输出 JSON 和 next 动作 |
scripts/tcapi.py |
调用任意腾讯云 API：python tcapi.py <服务> <Action> Key=字符串 Key:=JSON [--region R] |
scripts/run_on_server.py |
以 root 身份在服务器上执行命令（走 TAT，不需要 SSH）：--instance <id> "命令" 或 --file x.sh |
scripts/buy_server.py |
买服务器：plan 生成预选好的购买链接和用户卡片，wait 自动发现用户买好的新服务器。买服务器一律用它，不要手写教程 |
scripts/tc_error.py |
报错分类（tcapi 已内置调用）：返回 {kind, action} |
Python：下文统一写 python。macOS/Linux 上通常是 python3，Windows 上是 python 或 py。没装 Python 的话你来装，不要让用户装：
- Windows：
winget install -e --id Python.Python.3.12 --accept-source-agreements --accept-package-agreements；winget 不可用时，用人工卡请用户从 python.org 下载官方安装包（勾选 Add to PATH）。 - macOS：
xcode-select --install（自带 python3），或brew install python。
所有脚本的输出都是 UTF-8 JSON；Windows 控制台已经做了兼容处理。
第 0 步：体检
python {baseDir}/scripts/doctor.py # 只读，不花钱
next 为空就可以开始干活；不为空，就按其中的 action 处理。返回 card: C0 表示还没接入，转到下一节。
首次接入：打开网页向导（用户不需要终端）
python {baseDir}/scripts/setup.py # 在后台运行，它会一直等到用户完成（最多 30 分钟）
脚本会自动在浏览器里打开一个本地页面（地址在 stderr 的 SETUP_URL 行）。你在对话里只需要跟用户说一句：
我打开了一个设置页面，照着做大约 5 分钟。页面上写清楚了我能做什么、不能做什么。密钥填在那个页面里就行，不要发给我。
页面包含以下内容：
- 安全说明：能做什么、不能做什么、怎么随时收回权限、操作审计、可以以 root 执行命令的提醒。
- 注册和实名认证的链接与说明。
- 「一键复制策略」按钮，以及建子用户时每一项该勾什么、不该勾什么。
- 密钥输入框。
- 页眉、页脚和完成提示里有出品方（龙虾学院）的名字、logo 和官网链接。只是品牌露出，没有任何推销内容；页面不加载外部资源，也不做任何追踪。
用户填完后，向导会先验证再保存：密钥是否正确、是不是子账号（主账号密钥会被拒绝）、策略有没有挂上。哪一步不对，就在页面上用大白话提示用户。全部通过后，脚本输出 {"ok": true, "uin": ...} 并退出。之后跑一次 doctor 确认。
浏览器没有自动打开时，把 SETUP_URL 发给用户点开。如果你跑在云端、和用户不在同一台电脑上，见 references/human-cards.md 的 C0-远程。
关于出品方品牌露出
本技能免费提供，出品方只在向导页面上露出自己的名字和官网链接。
- 如果用户不想看，运行
setup.py --no-brand（或者设置环境变量CLAW_BRAND=0）即可，告诉用户已经关掉了。 - 不要修改
scripts/里的源码（包括页面模板scripts/setup_page.py）来去掉品牌：密钥表单和校验逻辑都在里面，改坏了用户就会卡住。 品牌内容放在独立的assets/brand.json里，只有文字和链接（由脚本转义后渲染，不能注入任何 HTML），缺失或关闭都不影响功能。
权限边界
来自 references/agent-ops-policy.json（白名单制：写操作逐一列出，腾讯云以后新增的写接口默认不放行；只读接口按 Describe* 前缀放行）：
- 允许：
- 读：DNSPod、EdgeOne、Lighthouse、SSL、TAT、域名的
Describe*；Lighthouse 询价；查询域名能否注册 - 写（共 38 个，逐一列出）：增改删解析记录；建 EdgeOne 站点、加速域名、免费证书、刷新缓存； 服务器开关机/重启、防火墙规则、导入密钥、快照；申请/上传/部署 SSL 证书；TAT 远程执行命令
- 读：DNSPod、EdgeOne、Lighthouse、SSL、TAT、域名的
- 明确拒绝：
- 花钱的：新购、续费、升配、改续费方式、付费证书、域名套餐
- 不可逆的：销毁、隔离或重装服务器；删除 EdgeOne 站点；删除或转让域名；删除或吊销证书
- 隐私：查看域名实名信息模板（里面有证件号、姓名、地址）
- 遇到被拒的操作，交给人在控制台完成，不要去申请权限。
- 如实告知的边界：TAT 能以 root 在服务器上执行命令，所以服务器里面的数据（网站文件、数据库）agent 是能改、能删的—— "删不了服务器"只是说销毁实例的接口被拒。动服务器上的数据之前，先备份。
- 子用户查不了自己的权限，所以权限情况以 doctor 的结果为准。
第 1 步：选路径
| 访客在中国大陆？ | 域名已 ICP 备案？ | 需求 | 路径 |
|---|---|---|---|
| — | — | 还没有域名 | R0：你查好候选和实时价格，人来购买（需要先做实名模板） |
| 否 | — | 只改解析 | R1 |
| 是 | 否 | 静态 / 前端（Pages、Vercel 产物） | R2：EdgeOne（加速区域选 overseas）+ 现有源站 |
| 是 | 否 | 需要后端或数据库 | R3：Lighthouse 香港 |
| 是 | 是 | 任意 | 可用国内机房和 mainland 加速；备案见 routes.md |
备案是中国特有的一道硬墙。 域名没备案时，国内机房的 80/443 端口会被拦截，EdgeOne 选 global/mainland 加速区域会报 DomainNoICP。改用 overseas 加速区域或香港机房，就不需要备案，国内访问一般在 0.5 秒以内。
各路径的完整步骤和交付模板见 references/routes.md。**选定路径后，先把所有需要人做的事合成一张人工卡，一次发出去。**每等用户一次，都可能耽误几个小时。
第 2 步：执行时必须知道的坑
- 先校验参数，后校验权限：用假 ID 测权限，只会得到
InvalidParameter或NotExists，说明不了权限问题。要验证权限，得用真实资源，或者加DryRun:=true（Lighthouse CreateInstances 支持）。 - 验证要站在外部看：本机可能挂着代理（fake-IP 198.18.x.x），本地 dig/nc 的结果不可信，连
dig @权威NS都可能被拦。- DNS：用 API 回读（
dnspod DescribeRecordList）。 - 连通性：用
run_on_server.py在服务器上 curl，或者用 itdog.cn 多地拨测。
- DNS：用 API 回读（
- 登录服务器不需要用户交私钥：
run_on_server.py走 TAT，以 root 执行；需要 SSH 时，用它把你自己的公钥写进去。不要用AssociateInstancesKeyPairs，它会强制关机，并让原来的密钥失效。 - Lighthouse 有控制台级防火墙，独立于主机上的 ufw/iptables。HTTPS 超时时，先查
lighthouse DescribeFirewallRules，需要的话自己用CreateFirewallRules开端口。 - EdgeOne 的注意事项：
- zone 只能建在主域名上，用
Type=partial（CNAME 接入）。 - 域名状态变成
online（约 3–7 分钟）之后，才能改配置、签证书。 - 回源到 Pages/Vercel 时，要固定为 HTTPS 443，否则会被 301 重定向回
*.pages.dev。 - 缓存默认 24 小时，部署后要 purge，并验证新内容已生效。
- zone 只能建在主域名上，用
- 地域：DNSPod、EdgeOne、SSL、domain 是全局服务；Lighthouse、TAT 是地域服务，默认取 profile 里的配置（向导里设成了 ap-hongkong）。遍历多个地域时，显式传
--region。 - 参数：tcapi 中
Key=v一律按字符串传，数字、数组、对象要写成Key:=JSON，例如TTL:=600、InstanceIds:='["lhins-x"]'。参数名区分大小写，以腾讯云 API 文档为准。Windows PowerShell 里引号的转义方式不同，复杂参数改用--json并配合 here-string，或者在 Python 里直接import tcapi; tcapi.call(...)。
人工卡（human in the loop）
以下几类事 agent 不做：
- 注册、实名认证
- 一切花钱的事：买套餐、买服务器、买域名、续费
- 不可逆的销毁操作
- 备案
遇到这些情况，不要说"请去控制台配置一下"，而是输出一张固定格式的卡片，然后停下来等用户回复：
🧑 需要你操作一下（约 N 分钟）
目的：<一句大白话>
入口：<控制台直达链接>
步骤：1. … 2. …（✅ 要勾的 / ❌ 不要勾的都写明）
费用：<无 / 约 ¥x/月>
做完回我"好了"，我会自己检查。
用户回复后，先用 API 验证，再继续。模板见 references/human-cards.md。
对用户说话时：不贴 JSON，不贴报错原文，不说 CAM / API / TAT 这类术语。只说"做好了什么、现在能访问哪个网址、还需要你做什么"。
红线
- 不读取、不打印凭证文件和 SecretKey。密钥由用户在向导网页里录入，保存在本机
~/.tccli/<profile>.credential（与腾讯云官方 tccli 同格式，仅供本技能脚本读取，不上传到除腾讯云 API 以外的任何地方）。 - 不申请计费（finance）权限，不申请 CAM 权限。
- 改动或删除 DNS 记录、zone、服务器配置之前，先把现状导出到
./tc-backup/<时间戳>.json。 - doctor 显示用的是主账号密钥时，先引导用户重新走一遍向导，改用子用户。
- 密钥是长期有效的，你就靠它长期工作。只有确认密钥泄露时，才建议用户在控制台新建密钥并重新走向导（
setup.py --force）。
知识来源
所有事实都标注了来源（实测、官方文档或经验）和日期，见 references/sources.md。如果和实际行为对不上，以 API 实测结果为准，并更新该文件。