@clize/clize 0.32.0 → 0.33.0

package/skills/clize-site-debug/SKILL.md

@@ -1,92 +1,120 @@
 ---
 name: clize-site-debug
 description: >-
-  当用户说某个用 clize 部署的站点 / 域名「打不开、访问不了、部署了但没生效、还是占位页」时,用这个 skill 系统排查。
-  clize 站点托管 = 共享 worker clize-handle-site + KV clize-sites,按 hostname serve;域名经 CF Workers custom domain 绑到 worker。
-  v0.22.0+ 先跑 `clize domain check <域名>`(一条命令四层体检:注册局委派 DoH → zone → 绑定 → 内容);
-  没定位到再按「先排代理 → 内容层(KV) → 绑定层(workers/domains) → DNS 层(zone/NS)」手工四步,Vercel 注册域名要切 NS→CF。
-  触发:"我的站打不开"、"X 域名访问不了"、"deploy 了没生效"、"还是占位页"、"freevideocompressor 这种站不能用"。
+  Use when the user says a site or domain deployed with clize "does not open, is unreachable, was deployed
+  but nothing changed, still shows the placeholder page". Systematic diagnosis. clize site hosting = the
+  shared worker clize-handle-site + the KV namespace clize-sites, served by hostname; domains bind to the
+  worker as Cloudflare Workers custom domains. On v0.22.0+ run `clize domain check <domain>` first (one
+  command, four layers: registry delegation via DoH → zone → binding → content); if that does not locate
+  it, work by hand in the order proxy → content layer (KV) → binding layer (workers/domains) → DNS layer
+  (zone/NS); Vercel-registered domains need their NS moved to Cloudflare. Triggers: "my site does not
+  open", "X is unreachable", "deployed but no effect", "still the placeholder", "我的站打不开".
 ---
 
-# clize 托管站点打不开 —— 系统排查
+# A clize-hosted site does not open — systematic diagnosis
 
-clize 站点托管 = 共享 worker **`clize-handle-site`** + KV **`clize-sites`**,worker 按 hostname 从 KV 取 `${host}${path}`(无内容→占位页)。域名通过 **CF Workers custom domain** 绑到这个 worker,要求域名 zone 在 CF 且 **active**(NS 指向 CF)。
+clize site hosting = the shared worker **`clize-handle-site`** + the KV namespace **`clize-sites`**; the
+worker reads `${host}${path}` from KV by hostname (no content → the placeholder page). A domain reaches the
+worker through a **Cloudflare Workers custom domain**, which requires the zone to be on Cloudflare and
+**active** (NS pointing at Cloudflare).
 
-「打不开」基本是这条链某一环断了。
+"Does not open" almost always means one link in that chain is broken.
 
-## 先试一条命令(v0.22.0+)
+## Try one command first (v0.22.0+)
 
 ```bash
-clize domain check <域名>     # 四层体检:注册局委派(DoH 公网权威)→ CF zone → worker 绑定 → KV 内容,带修复建议
-clize domain check            # 不带域名 = 全部域名轻检,汇总不可达清单
+clize domain check <domain>     # four layers: registry delegation (public authoritative DoH) → CF zone → worker binding → KV content, with fix suggestions
+clize domain check              # no domain = a light check of every domain, listing the unreachable ones
 ```
 
-它以**公网权威 DNS 为准**(不吃本机代理假象、不信 CF zone 缓存),能直接定位 2026-06 断链事故那类注册局委派故障(NXDOMAIN / NS 指向别处)。注意 `domain list` 的 `status` 是接入方式(registered/external/pending),**不代表健康**,别拿它判断。平台每 30 分钟还会自动巡检,持续异常向账户邮箱(`clize account email` 配置)发告警。
+It uses **public authoritative DNS** as the truth (immune to local proxy illusions and to CF's cached zone
+status) and directly locates registry-delegation faults like the June 2026 outage (NXDOMAIN / NS pointing
+elsewhere). Note that the `status` in `domain list` is the access mode (registered / external / handle /
+pending), **not health**; do not judge by it. The platform also sweeps every 30 minutes and emails the
+account address (set with `clize account email`) when a domain stays broken.
 
-`domain check` 没定位到、或要查 TLS/边缘/KV key 细节时,再走下面手工四步。**按顺序查,别跳步。**
+If `domain check` does not locate it, or you need TLS / edge / KV-key detail, go through the four manual
+steps below. **In order; do not skip.**
 
-## 0. 先排除本机代理(最容易误判,务必第一步)
+## 0. Rule out the local proxy first (the most common misdiagnosis; always step one)
 
-用户本机若跑 Clash/Surge(TUN / fake-ip 模式),`dig` 会把域名解析到 **`198.18.x.x`**(fake-ip 段)或**连不上公共 DNS**。这种情况本机 `dig` / `curl` / 浏览器结果**全部不可信** —— 站点可能完全正常,只是被本机代理拦了。
+If the user's machine runs Clash / Surge (TUN / fake-ip mode), `dig` resolves the domain to **`198.18.x.x`**
+(the fake-ip range) or **cannot reach public DNS**. In that state every local `dig` / `curl` / browser
+result is **untrustworthy** — the site may be perfectly fine and only blocked by the local proxy.
 
-- 判据:`dig +short A <域名>` 返回 `198.18.*` / `198.19.*`,或 `dig @1.1.1.1 <域名>` 超时。
-- 对策:**从云端验证,别信本机**:
-  - `WebFetch https://<域名>` —— 从云端抓真实内容 / 看能否访问。
-  - `WebFetch "https://dns.google/resolve?name=<域名>&type=NS"` —— 查权威 NS。
-- 先让用户**关代理 / 换手机流量**再访问一次,很多「打不开」到此就解决。
+- Signs: `dig +short A <domain>` returns `198.18.*` / `198.19.*`, or `dig @1.1.1.1 <domain>` times out.
+- Fix: **verify from the cloud, not the machine**:
+  - `WebFetch https://<domain>` — fetch the real content from the cloud / see whether it responds.
+  - `WebFetch "https://dns.google/resolve?name=<domain>&type=NS"` — the authoritative NS.
+- Have the user **turn off the proxy / switch to mobile data** and try once more; many "does not open"
+  reports end right here.
 
-## 1. 内容层:站点真写进 KV 了吗
+## 1. Content layer: did the site actually land in KV?
 
 ```bash
 NSID=$(curl -s ".../accounts/<ACCT>/storage/kv/namespaces?per_page=100" "${A[@]}" | jq -r '.result[]|select(.title=="clize-sites").id')
-curl -s ".../accounts/<ACCT>/storage/kv/namespaces/$NSID/keys?limit=1000" "${A[@]}" | jq -r '.result[].name' | grep -i "<域名>"
+curl -s ".../accounts/<ACCT>/storage/kv/namespaces/$NSID/keys?limit=1000" "${A[@]}" | jq -r '.result[].name' | grep -i "<domain>"
 ```
-有 `<域名>/index.html` 等 key → deploy 的「写 KV」成功了,进第 2 步。没有 → 站点根本没部署,重新 `clize deploy ./site --domain <域名>`。
+Keys like `<domain>/index.html` exist → the deploy's KV write succeeded; go to step 2. Nothing → the site
+was never deployed; run `clize deploy ./site --domain <domain>` again.
 
-## 2. 绑定层:域名绑到 handle-site 了吗
+## 2. Binding layer: is the domain bound to handle-site?
 
 ```bash
-curl -s ".../accounts/<ACCT>/workers/domains" "${A[@]}" | jq -r '.result[]|select(.service=="clize-handle-site").hostname' | grep -i "<域名>"
+curl -s ".../accounts/<ACCT>/workers/domains" "${A[@]}" | jq -r '.result[]|select(.service=="clize-handle-site").hostname' | grep -i "<domain>"
 ```
-有 → 绑定 OK(若仍打不开,回第 0 步查代理 / 等 SSL)。**没有 → 域名没接到 worker(最常见的打不开原因)**,进第 3 步。
+Present → the binding is fine (if it still does not open, go back to step 0 or wait for SSL). **Absent →
+the domain is not attached to the worker (the most common cause)**; go to step 3.
 
-## 3. DNS 层:CF zone active 吗 / NS 指 CF 吗
+## 3. DNS layer: is the CF zone active / does the NS point at CF?
 
 ```bash
-curl -s ".../zones?name=<域名>" "${A[@]}" | jq -r '.result[0]|{id, status, name_servers}'
+curl -s ".../zones?name=<domain>" "${A[@]}" | jq -r '.result[0]|{id, status, name_servers}'
 ```
-- `status=active` → NS 已指 CF,直接跳第 5 步绑定。
-- `status=pending` → **NS 没委派给 CF**,这是断点。CF 注册的域名 NS 本应在 CF(异常,查 NS 记录);**Vercel 注册的域名**默认 `vercel-dns.com`,要切 → 第 4 步。
+- `status=active` → the NS is on CF; jump to step 5 and bind.
+- `status=pending` → **the NS is not delegated to CF**; that is the break. A CF-registered domain should
+  already have its NS on CF (abnormal; check the NS records); a **Vercel-registered domain** defaults to
+  `vercel-dns.com` and must be switched → step 4.
 
-## 4. ⚠️ Vercel 注册域名的 NS 坑
+## 4. ⚠️ The NS trap for Vercel-registered domains
 
-Vercel 注册(`boughtAt` 有值、`serviceType:"zeit.world"`)的域名默认用 Vercel DNS。切到 CF:
+Vercel-registered domains (`boughtAt` set, `serviceType:"zeit.world"`) use Vercel DNS by default. Switch to CF:
 ```bash
-# CF 的两个 NS = 第 3 步查到的 name_servers
-curl -s -X PATCH ".../v1/registrar/domains/<域名>/nameservers?teamId=<TEAM>" \
+# the two CF nameservers = the name_servers from step 3
+curl -s -X PATCH ".../v1/registrar/domains/<domain>/nameservers?teamId=<TEAM>" \
   -H "Authorization: Bearer <VERCEL_TOKEN>" -H "Content-Type: application/json" \
   -d '{"nameservers":["xxx.ns.cloudflare.com","yyy.ns.cloudflare.com"]}'
 ```
-**关键坑**:切完后 Vercel 自己的 `nameservers` / `intendedNameservers` 字段**会显示滞后**(还写着 vercel-dns),只有 `customNameservers` 是你设的值。**别信 Vercel 的字段** —— 用 `WebFetch "https://dns.google/resolve?name=<域名>&type=NS"` 查**注册局权威 NS**,看到 `cloudflare.com` 就是切成功了。(经验:Vercel 注册域名的 NS **是能切到 CF 的**,之前「NS 锁死」是被这个滞后字段误导。)
+**The trap**: after switching, Vercel's own `nameservers` / `intendedNameservers` fields **lag** (still
+showing vercel-dns); only `customNameservers` holds what you set. **Do not trust Vercel's fields** — check
+the **registry's authoritative NS** with `WebFetch "https://dns.google/resolve?name=<domain>&type=NS"`;
+seeing `cloudflare.com` means the switch worked. (Lesson: Vercel-registered domains **can** be switched to
+CF; the earlier "NS locked" belief came from that lagging field.)
 
-## 5. 修复:激活 zone + 绑 custom domain
+## 5. Fix: activate the zone + bind the custom domain
 
 ```bash
-# 催 CF 立即重查 NS(pending→active)
+# ask CF to re-check the NS now (pending → active)
 curl -s -X PUT ".../zones/<ZID>/activation_check" "${A[@]}"
-# zone active 后,绑 custom domain 到 handle-site
+# once the zone is active, bind the custom domain to handle-site
 curl -s -X PUT ".../accounts/<ACCT>/workers/domains" "${A[@]}" \
   -H "Content-Type: application/json" \
-  -d '{"hostname":"<域名>","service":"clize-handle-site","environment":"production","zone_id":"<ZID>"}'
+  -d '{"hostname":"<domain>","service":"clize-handle-site","environment":"production","zone_id":"<ZID>"}'
 ```
-绑成功 + KV 有内容 → 站点立刻上线(SSL 自动签,首访可能等几十秒)。
+Binding succeeded + KV has content → the site is live immediately (SSL is issued automatically; the first
+visit may take a few dozen seconds).
 
-## 认证速记 / 占位
+## Auth cheat sheet / placeholders
 
-- CF API base:`https://api.cloudflare.com/client/v4`;认证 `A=(-H "X-Auth-Email: <email>" -H "X-Auth-Key: <CF global key>")`。
-- Vercel base:`https://api.vercel.com`;认证 `-H "Authorization: Bearer <VERCEL_TOKEN>"` + `?teamId=<TEAM>`。
-- `<ACCT>` / `<ZID>` / `<NSID>` 都用上面的 list 接口现查,别硬编码。
+- CF API base: `https://api.cloudflare.com/client/v4`; auth `A=(-H "X-Auth-Email: <email>" -H "X-Auth-Key: <CF global key>")`.
+- Vercel base: `https://api.vercel.com`; auth `-H "Authorization: Bearer <VERCEL_TOKEN>"` + `?teamId=<TEAM>`.
+- `<ACCT>` / `<ZID>` / `<NSID>`: look them up with the list endpoints above; never hard-code.
 
 ---
 
-> **此排查流程已固化进部署**:[`src/core/sites.ts`](../../src/core/sites.ts) 的 `ensureZoneActiveForHandle` 会在 `clize deploy` 时自动建 zone / 切 NS(Vercel 域名)/ 激活 / 绑定,且绑定失败会**报错**(不再 `.catch(()=>{})` 假成功)。所以新部署一般不会再出这问题;这个 skill 主要用于**排查历史遗留**(那次 bug 期间「假成功」但没真接上的站)和**事后核验**已上线域名。建站流程见 `clize-site-build` skill。
+> **This diagnosis is now built into deploy**: `ensureZoneActiveForHandle` in
+> [`src/core/sites.ts`](../../src/core/sites.ts) creates the zone / switches the NS (Vercel domains) /
+> activates / binds during `clize deploy`, and a failed binding **is an error** (no more
+> `.catch(() => {})` false success). New deploys therefore rarely hit this; the skill is mainly for
+> **legacy sites** (from the period when the bug reported success without binding) and for **verifying**
+> live domains after the fact. Building a site is the `clize-site-build` skill.