diff --git a/docs/07-ux-review-2026-09-05.md b/docs/07-ux-review-2026-09-05.md
new file mode 100644
index 00000000..1dab9e72
--- /dev/null
+++ b/docs/07-ux-review-2026-09-05.md
@@ -0,0 +1,254 @@
+# UX 全面 Review 与优化计划（2026-09-05）
+
+> 范围：takoapi.com 全部面向用户的页面（首页 / 市集 / 详情 / 技能 / 榜单 / 安装 / 博客 / 场景 / 登录注册 / 开发者控制台 / 提交流程 / 后台）+ 全站文案（`messages/en.json` 618 键，抽样 zh / ja / de）+ 邮件模板。
+> 方法：逐文件走读 `src/app/[locale]/**`、`src/components/**`；线上实测（curl 计时、HTML 结构、公开 API 返回）；对照 `docs/agent-marketplace/` 已拍板的产品决策（D1–D8）。
+> 配套技术审查见 [08-tech-review-2026-09-05.md](08-tech-review-2026-09-05.md)。
+
+> ## 实施状态（2026-09-07 更新）
+>
+> **本文的绝大部分已在 [PR #54](https://github.com/oratis/TakoAPI/pull/54) 中实现并通过 CI。**
+> 阅读时请把「现状」理解为**审查当时**（2026-09-05，`origin/main` = `b868319c`）的状态，不是当前 main。
+>
+> 已落地：U0 全部（首页精选按探活过滤、过期文案、登录回跳、My listings、404/error/loading、
+> 可点击账号菜单、隐藏 0 值指标）；U1 全部（统一导航与搜索、首页重排含 30 秒 quickstart、
+> `/agents` 筛选侧栏、`/skills` 与 `/trending` 改服务端渲染并把状态写回 URL、场景按深度过滤）；
+> U2 大部分（`/docs` API 参考、agent 详情多语言调用示例与 health、控制台 onboarding 与用量图、
+> 审核结果邮件、AgentCard 提交前校验、skill 详情服务端渲染与安装指引分流）；
+> U3 部分（对比度全站达标、RTL 物理方向类清零、cookie 同意门控、组件层抽取）。
+>
+> **未做**：母语校对（14 个语种是机器翻译，已按当前英文重译并统一了复数规则，但没有母语者过稿）；
+> 深色模式。
+
+---
+
+## 0. 一句话结论
+
+产品定位已经从「OpenClaw skills 市集」转向「One API to access all agents」，**但用户看到的仍是两个产品缝在一起**：导航、搜索、首页版块、登录文案、邮件都在两种叙事之间来回切换；而对已拍板的「开发者优先」（D4）这条主线，从首页到详情页到控制台，**缺一条清晰的「看到 → 拿 key → 30 秒调通」路径**。此外有一批影响信任的细节（首页精选中挂着探活为 down 的 agent、详情页仍写着「网关 Phase 2 才上线」、Skill 详情页纯客户端渲染），修复成本低但优先级高。
+
+线上基线（2026-09-05 实测）：
+
+| 指标 | 数值 |
+|---|---|
+| 目录规模（首页 hero 展示） | 52 个 HOSTED agent · 1,558 个开源项目 · 5,385 个 skill |
+| 首页 HTML | 271 KB，68 个 `<script>` |
+| 首页 TTFB | 冷 1.5 s / 热 0.8–0.9 s |
+| `/agents` TTFB | 热 0.7–1.1 s |
+| 404 页 | Next.js 默认「404: This page could not be found.」，无品牌无导航 |
+| Skill 详情页 SSR | 无（HTML 中无 `<h1>`，内容全靠客户端 fetch） |
+
+---
+
+## 1. 信息架构与产品叙事
+
+### 1.1 双产品叙事互相打架 🔴
+
+| 触点 | 现状 | 证据 |
+|---|---|---|
+| 顶部导航 | `Agents · Skills · Trending · Publish`：Trending 只有 skills，Publish 只发 agent，skill 提交入口藏在个人页 | `src/components/layout/Header.tsx:51-119` |
+| 两个搜索框去向不同 | Header 搜索 → `/agents?q=`；首页大搜索框 → `/skills?q=`（占位文案还是 "Search skills by name…"） | `Header.tsx:31`，`src/components/ui/HomeSearch.tsx:16` |
+| 首页结构 | hero 讲 agents，往下 8 个版块里 4 个是 skills（Official skill 横幅 / Must-Have / Categories / Latest Skills） | `src/app/[locale]/page.tsx` |
+| 页脚 | "Built for the OpenClaw community"；资源区只链 awesome-openclaw-skills 与 clawskills.sh | `messages/en.json` `Footer.copyright` |
+| 登录页副标题 | "Access your skills dashboard" | `Auth.signInSubtitle` |
+| 欢迎邮件 | 标题区「All in One OpenClaw Skills Marketplace」「5,000+ OpenClaw skills」「clawhub install takoapi」 | `src/lib/email.ts:37,41,53` |
+| KOL 外联邮件 | "the OpenClaw skills marketplace with 5,000+ skills" | `src/lib/email.ts:155` |
+| 用户菜单 | "My Skills"（个人页只列 skill 提交，**看不到自己提交的 agent**） | `Header.tsx:81`，`src/app/[locale]/profile/page.tsx` 只调 `/api/user/skills` |
+
+**影响**：新访客读完首页不知道 TakoAPI 到底是什么；publisher 提交 agent 后无处查看审核状态（见 §5.2）。
+
+**建议**：
+1. 明确主线 = **Agents（HOSTED + PROJECT）**，Skills 降级为「coding-agent skills」子品类（与 D2 一致）。导航改为 `Agents · Projects · Skills · Blog · Install`，主 CTA 固定为「Get API key」。
+2. 全站**一个搜索**：默认搜 agents，带作用域切换（Agents / Projects / Skills）；两处搜索框走同一组件与同一路由。
+3. 清一遍所有「OpenClaw skills marketplace」口径：页脚、登录副标题、欢迎邮件、外联邮件、README 项目结构段。
+4. 个人页改成「My Listings」：agents + skills 两个 tab。
+
+### 1.2 术语冲突 🟠
+
+- **"Agents"** 同时指：可调用的 HOSTED agent、开源 PROJECT、以及 skills 筛选里的「coding agent 类型」（`Skills.agentAll` = "All agents" → Claude Code / Cursor…）。
+- **"Skills"** 同时指：OpenClaw skill 条目，和 A2A AgentCard 里的 `skills[]`（agent 卡片上的 "5 skills"、详情页的 "Skills (5)"）。
+- **"Projects" / "self-host" / "open-source"** 三个标签混用在同一张卡上。
+
+**建议**：定一张术语表并落到 `messages/en.json`：`Agent`（可调用）、`Project`（开源，仅发现）、`Capability`（AgentCard skills[]）、`Skill`（coding-agent skill）、`Coding agent`（Claude Code 等）。
+
+---
+
+## 2. 首页
+
+| # | 问题 | 严重度 | 证据 / 建议 |
+|---|---|---|---|
+| 2.1 | hero 数字「52 AI agents」与「5,385 skills」并列，反而暴露可调用 agent 供给薄 | 🟠 | `Home.heroSubtitle`。建议改为「1,600+ agents & projects」或按场景讲价值，把精确数字下沉到市集页 |
+| 2.2 | **Featured Agents 无策展**：排第一的 VAP Execution Agent 当前探活状态为 `down`（2026-09-05 14:00 检测）；GanjaMon（"rasta translation"）、Cloud Latitude（"raffle entries"）等营销型 agent 占首页精选位 | 🔴 | 精选按 `featured desc, callsCount desc` 自动排（`page.tsx:36-38`），`featured` 几乎无人工维护。建议：首页只展示 `featured=true && healthStatus='ok'`，后台加「首页精选」独立开关与顺序 |
+| 2.3 | 开发者优先（D4）但首页没有「怎么调」：无 30 秒 quickstart 代码块、无 SDK/OpenAI 兼容示例、无 "Get API key" CTA；第二 CTA 是「Publish an agent」（新访客几乎不需要） | 🔴 | 建议 hero 下方紧跟一个双栏 quickstart（curl + OpenAI SDK），CTA 改为「Get API key」+「Browse agents」 |
+| 2.4 | 页面过长：17 个场景磁贴 + 8 精选 + 8 项目 + skill 横幅 + 8 must-have + 12 分类 + 12 最新 | 🟠 | 场景保留 8 个热门 + 「全部场景」；skills 合并为一个版块 |
+| 2.5 | Must-Have Skills 卡片每张都显示「0」赞（社区几乎无人点赞） | 🟡 | `SkillCard.tsx:45`。0 值指标一律隐藏 |
+| 2.6 | 「TakoAPI Skill for OpenClaw」横幅仍是 skills 时代的产物，链接到外部 GitHub 仓库 | 🟡 | 与 `/install` 页合并成一个「Install into your coding agent」版块 |
+| 2.7 | 首页 9 个 DB 查询、无缓存，热 TTFB 0.8–0.9 s，且无 `loading.tsx`，导航时无任何反馈 | 🟠 | 技术侧见 08 §4.1 |
+
+---
+
+## 3. 发现与浏览
+
+### 3.1 `/agents` 市集页 🟠
+
+- **筛选墙**：Kind（3）+ Scenario（17）+ Protocol（3）+ Pricing（4）+ Category（N）+ Sort（5）全部平铺成 chip，一屏 40+ 个可点元素（`agents/page.tsx:188-268`）。没有「当前筛选摘要 / 一键清除」，多选一次要滚回顶部。
+- 搜索表单是原生 `<form action="/agents">`（`:171`），在 `/zh/agents` 搜索会跳回英文 `/agents`。
+- 排序 `Popular` 按 `likesCount`（几乎全 0），等于随机；默认 `latest` 对 1,600 条目录不如 `stars` / `calls` 有意义。
+- 分页只有 Prev / Next，没有页码与总页数跳转；`PAGE_SIZE=24` 但 URL 参数 `page` 非法时静默回 1。
+- 卡片不显示 health / 最近更新时间 / 是否经验证，HOSTED 与 PROJECT 两种卡信息密度差异大。
+
+**建议**：筛选改为左侧栏（桌面）/ 抽屉（移动），顶部只留搜索 + Kind 切换 + 排序；显示 active filter chips；默认排序按 kind 自适应（HOSTED→calls，PROJECT→stars）；卡片加 health 点与「updated 3d ago」。
+
+### 3.2 `/skills` 列表页 🔴
+
+- 整页 `"use client"`，首屏是骨架屏再 fetch（`skills/page.tsx:1,42-63`）；对 5,385 个 skill 的入口页，搜索引擎拿到的是空壳。
+- 筛选/排序/页码只存 React state，**不写回 URL**：不能分享、刷新即丢、浏览器后退无效（`:32-35,121`）。
+- 分类是 `<button>` 而非链接，无法中键/新标签打开。
+- 从 header 搜索进入的是 `/agents`，从首页搜索进入的是 `/skills`，用户不会知道区别。
+
+### 3.3 `/trending` 🟡
+
+- 与 `/skills?sort=downloads` 是同一数据的另一套皮（同样 CSR）；表头 "Downloads" 是 clawskills.sh 抓取值而非本站数据（PR #52 已把文案改掉）。
+- 建议合并进 `/skills` 的排序，或做成真正的「7 日增量」榜单。
+
+### 3.4 `/scenarios` 🟡
+
+- 17 个场景分布极不均：Agent Frameworks 1,124 / Coding 417 / Research 366 vs Sales 4 / VC 4 / Product Design 5。四五个条目的场景落地页对用户和 SEO 都是 thin content。
+- 建议：≤10 条的场景不在首页磁贴出现、落地页加「相关场景」；分类器关键词按分布调整（08 §6.3）。
+
+---
+
+## 4. 详情页
+
+### 4.1 Agent 详情 `/agents/[slug]` 🔴
+
+| 问题 | 证据 |
+|---|---|
+| **过期文案**：侧栏写「Unified gateway — invocation ships in Phase 2」，而网关早已上线 | `AgentDetail.gatewayPhase2`，`agents/[slug]/page.tsx:297`；线上 HTML 可搜到 "Phase 2" |
+| 调用示例只有一段 curl，没有 OpenAI SDK（Python/TS）示例，没有「Try it」 | `:296-302` |
+| 不显示 health（探活为 down 的 agent 与正常的一模一样） | schema 有 `healthStatus`，UI 未用 |
+| PROJECT 详情除 stars 外没有任何增量信息（无 README 摘要、语言、license、最近 push），相比 GitHub 本页无价值——这也是它被标 `noindex` 的原因 | `:237-263` |
+| 评分 / 收藏未登录只显示灰字，点登录后固定回首页（`callbackUrl: "/"`），回不到原页 | `AgentEngagement.tsx`，`auth/signin/page.tsx:43,55` |
+| 「Signed card / Verified publisher」两个徽章永远不会出现（字段从未写入） | `cardSignatureVerified` / `namespaceVerified` 无写入路径 |
+
+### 4.2 Skill 详情 `/skills/[slug]` 🔴
+
+| 问题 | 证据 |
+|---|---|
+| 纯客户端渲染：线上 HTML 无 `<h1>`、正文靠 `fetch('/api/skills/:slug')`；5,385 个页面的 SEO 只剩 layout 里的 meta + JSON-LD | `skills/[slug]/page.tsx:1,194` |
+| 每次页面加载（含爬虫）都让 `viewsCount +1`，Views 指标失真（实测连续两次 GET 由 8 → 9） | `src/app/api/skills/[id]/route.ts:36-39` |
+| Like 按钮初始永远是「未赞」（没有回读用户是否已赞），已赞用户再点会变成取消赞并显示 -1 | `:189,208-215` |
+| 点赞未登录时 `window.location.href = "/auth/signin"`：丢 locale、丢回跳 | `:209` |
+| 「Installation」对 GitHub 抓取的 skill 显示伪命令 `clawhub install <slug>`（ClawHub 上并不存在） | 提交与抓取都硬写 `installCmd`（`api/skills/submit/route.ts:64`，`scripts/scrape-github-skills.ts:137`） |
+| 「OpenClaw Chat (paste this into your conversation)」对 Claude Code / Cursor 用户无意义 | `SkillDetail.openClawChat` |
+| README 原文只在符合 `## What This Skill Does` 等固定标题时才结构化，否则整段 `<pre>` 灰底展示 | `:35-46,331-350` |
+
+---
+
+## 5. 转化漏斗（开发者 & publisher）
+
+### 5.1 开发者：看到 → 拿 key → 调通 🔴
+
+1. 登录：无邮箱验证、无忘记密码、注册后自动登录固定跳首页；所有需登录的页面（dashboard / profile / submit / submit-agent / bookmarks）都是「请先登录」占位 + 跳转，登录后不回到原页。
+2. Dashboard（`dashboard/page.tsx`）：`status === "loading"` 时 `return null` 整页白屏（`:92`）；创建 key 默认命名 "Gateway key" 不可改；用量只有 15 条最近调用的表格，没有时间范围与图表；quickstart 仍只有 curl。
+3. 没有 `/docs`：API 说明只在 README 与 SKILL.md，控制台里没有错误码 / 限流 / 计费规则说明。
+4. 没有「在浏览器里试一次」：从拿 key 到第一次成功调用，用户必须离开网站。
+5. 充值面板文案「Credits are funded by the platform for now — self-serve PayPal top-up is coming soon」与 PayPal 是否已配置耦合，用户不知道自己有多少额度可用、超了会怎样。
+
+**建议**：登录全链路带 `callbackUrl`；dashboard 首屏加 onboarding checklist（创建 key → 复制示例 → 首次调用成功 ✅）；加「Try an agent」内嵌调用面板（用当前 key 调 `/v1/chat/completions`）；建 `/docs` 静态页（quickstart / auth / endpoints / errors / billing）。
+
+### 5.2 Publisher：提交 → 审核 → 上架 🔴
+
+- `/submit-agent` 提交成功后只显示「pending review」一屏，之后**没有任何地方能看到审核状态**（个人页只有 skills），也没有邮件通知（审核通过/拒绝都不发）。
+- `reviewNote` 通过公开 API 暴露（08 §2.6），却不在 publisher 自己的界面展示。
+- 提交表单没有预览、没有 AgentCard 校验的即时反馈（要提交后才知道 card 拉不下来）。
+
+**建议**：个人页加 My Agents（状态 + 审核备注）；审核结果邮件；表单加「Validate card」按钮（复用 `fetchAgentCard`）实时显示解析出的 name / skills。
+
+---
+
+## 6. 全局体验、可访问性、国际化
+
+| # | 问题 | 严重度 | 证据 / 建议 |
+|---|---|---|---|
+| 6.1 | 无自定义 404 / error / loading 页面（默认 Next 404，无品牌无导航） | 🟠 | `src/app` 下无 `not-found.tsx` / `error.tsx` / `loading.tsx`。补三件套，404 页给搜索框与热门入口 |
+| 6.2 | 账户菜单 hover 才出现（`group-hover`），触屏与键盘无法打开；移动菜单按钮无 `aria-label` / `aria-expanded` | 🟠 | `Header.tsx:72-76,123`。改成点击展开的 `<button aria-haspopup>` + 菜单 |
+| 6.3 | 对比度：说明文字大量使用 `text-gray-400`（#9CA3AF on white ≈ 2.5:1），不达 WCAG AA 4.5:1 | 🟠 | 全站 130 处。次要文字改 `gray-500`（4.6:1），注释级文字最低 `gray-500` |
+| 6.4 | 后台操作用浏览器原生 `prompt()` / `confirm()`（拒绝理由、删除确认） | 🟡 | `admin/agents/page.tsx:91,96`。改用页内对话框（admin/skills 已有 modal 可复用） |
+| 6.5 | 后台文案混入硬编码中文：「场景 Scenarios — 点击切换 / toggle to assign」「{nameZh} · {name}」，13 个语种照抄 | 🟡 | `Admin.scenariosEditorHint` / `Admin.scenarioOption`；`src/lib/scenarios.ts` 的 `nameZh`/`blurb` 双语硬编码。后台统一英文（或走 i18n） |
+| 6.6 | RTL（ar）：dashboard 充值输入用 `left-3` / `pl-6 pr-3` 物理方向类 | 🟡 | `dashboard/page.tsx:280,289`。改 `start-3` / `ps-6 pe-3` |
+| 6.7 | 13 个语种为机器翻译且未校对（GTM 文档承认）；抽样 zh/ja/de 质量尚可，但语气不一（de 用 du，ja 敬体混用） | 🟡 | 按 GTM §7 顺序找母语者过首页 / agents / scenarios / badge 四页 |
+| 6.8 | GA4 无 cookie 同意横幅，而站点面向 de/fr/es/it 等 EU 语种 | 🟡 | `src/components/Analytics.tsx`。加轻量 consent 或改用无 cookie 的统计 |
+| 6.9 | 表单校验只在提交后以红条显示，没有字段级错误；API 返回的 `details[]`（Zod 路径）前端未利用 | 🟡 | `submit/page.tsx`、`submit-agent/page.tsx` |
+| 6.10 | 无深色模式；`viewport.themeColor` 固定紫色 | 🟢 | 非必需，可后置 |
+| 6.11 | 视觉系统：按钮 / 输入框 / 卡片样式以 Tailwind 类串复制（同一主按钮类串出现 7 次、另一变体 4 次），没有组件层 | 🟡 | 抽 `Button` / `Input` / `Card` / `Badge` / `EmptyState` 组件（技术侧 08 §5.4） |
+
+---
+
+## 7. 文案与内容一致性清单（可直接改 `messages/*.json`）
+
+| 键 | 现状 | 建议 |
+|---|---|---|
+| `AgentDetail.gatewayPhase2` | "Unified gateway — invocation ships in Phase 2." | 删除该行，或改为「Call it now with your API key」 |
+| `Auth.signInSubtitle` | "Access your skills dashboard" | "Manage API keys, listings and usage" |
+| `Footer.copyright` | "Built for the OpenClaw community." | "One API to access all agents." |
+| `Home.skillTitle/skillDescription/askAgent` | OpenClaw skill 横幅 | 合并到 install 版块 |
+| `Components.homeSearchPlaceholder` | "Search skills by name…" | "Search agents, projects and skills" |
+| `Header.mySkills` | "My Skills" | "My listings" |
+| `Dashboard.topUpComingSoon` | 依赖 PayPal env | 分成「额度说明」+「充值不可用原因」 |
+| `SkillDetail.openClawChat` | OpenClaw Chat 粘贴文案 | 按 skill 来源（ClawHub / GitHub）分别给安装指引 |
+| `Admin.scenariosEditorHint` / `Admin.scenarioOption` | 中英混排 | 纯英文 |
+| `src/lib/email.ts` 三封邮件 | skills 市集口径 | 全部改为 agent 网关口径，欢迎邮件给「创建 API key」CTA |
+| `Trending.*` | PR #52 已修「live leaderboard」措辞 | 合并 PR 后核对 |
+
+---
+
+## 8. 优化计划
+
+> 沿用仓库约定：每阶段结束停下来验收，不一次性交付。人日为粗估。
+
+### Phase U0 · 止血（≈1 周）
+
+| 项 | 内容 | 验收 |
+|---|---|---|
+| U0-1 | 首页精选：只展示 `featured && healthStatus='ok'`；后台加「首页精选」开关 | 首页无 down agent；管理员可指定顺序 |
+| U0-2 | 过期文案：`gatewayPhase2` / 登录副标题 / 页脚 / 三封邮件 / README 项目结构 | 线上 HTML grep 不到 "Phase 2"、"OpenClaw Skills Marketplace" |
+| U0-3 | 登录回跳：所有「请先登录」入口与 `signIn()` 带 `callbackUrl=当前 locale 路径` | 从 `/zh/agents/x` 登录后回到同页 |
+| U0-4 | 个人页加 My Agents tab（复用 `/api/agents` 加 `mine=1` 或新 `/api/user/agents`），显示状态与 `reviewNote` | publisher 能看到 pending/rejected 原因 |
+| U0-5 | `not-found.tsx` / `error.tsx` / `loading.tsx`（根 + `[locale]`） | 任意错误 URL 返回带导航的 404；页面切换有骨架 |
+| U0-6 | 账户菜单改点击展开 + aria；移动菜单按钮 aria；隐藏 0 值指标 | 键盘 Tab 可打开菜单；卡片不再显示「0」 |
+| U0-7 | Dashboard loading 骨架替代 `return null`；Skill like 状态回读 | 无白屏；刷新后 like 状态正确 |
+
+### Phase U1 · 信息架构重排（≈2–3 周）
+
+| 项 | 内容 | 验收 |
+|---|---|---|
+| U1-1 | 导航与搜索统一：`Agents · Projects · Skills · Blog · Install` + 单一搜索（带作用域） | 两个搜索入口行为一致；`/zh` 下搜索不掉 locale |
+| U1-2 | 首页重排：hero（价值 + Get API key）→ 30 秒 quickstart（curl / OpenAI SDK 双栏）→ 场景（8 个）→ 精选 agents → 热门项目 → skills（一个版块）→ install | 首屏出现代码示例；页面长度减半 |
+| U1-3 | `/agents` 筛选侧栏化 + active filter chips + 页码分页 + health 点 + 自适应默认排序 | 移动端筛选进抽屉；URL 完整表达筛选状态 |
+| U1-4 | `/skills` 改 Server Component + URL 状态（含分类为链接）；`/trending` 并入排序或改 7 日增量 | `curl /skills` 返回含卡片的 HTML；后退可用 |
+| U1-5 | 场景：首页只展示 ≥30 条的场景；薄场景页加相关场景与「Publish first」引导 | 无 <10 条的场景磁贴 |
+
+### Phase U2 · 开发者体验（≈3–4 周）
+
+| 项 | 内容 | 验收 |
+|---|---|---|
+| U2-1 | `/docs`：quickstart、auth、endpoints（A2A / stream / OpenAI-compat / registry / MCP）、errors、billing、rate limits | 每个 API 都有请求 / 响应示例 |
+| U2-2 | Agent 详情：多语言调用示例（curl / Python / TS）、「Try it」内嵌调用（登录后用自己 key）、health 徽章、PROJECT 增加 README 摘要 / language / license / pushed_at | down agent 有醒目提示；PROJECT 页有增量内容 |
+| U2-3 | Dashboard：onboarding checklist、key 命名 / 重命名、用量按天图表 + 时间范围、额度与计费规则说明 | 新用户 5 分钟内完成首次调用 |
+| U2-4 | 审核通知邮件（approve / reject 附 reviewNote）；提交表单「Validate card」即时反馈 | 提交后 24h 内收到状态邮件 |
+| U2-5 | Skill 详情 SSR + 安装指引按来源区分 + views 去重 | 5,385 页 HTML 含正文；Views 增速合理 |
+
+### Phase U3 · 打磨（持续）
+
+- 可访问性审计（对比度、焦点态、表单错误 `aria-describedby`、skip link）；目标 WCAG 2.1 AA。
+- 母语校对（zh → ja → de → es → fr），每语种四页。
+- Cookie consent / 或切换到无 cookie 统计。
+- 组件层抽取（Button / Input / Card / Badge / EmptyState / Dialog），后台 `prompt/confirm` 全部替换。
+- 可选：深色模式。
+
+### 指标（建议在 GA4 / RequestLog 上落）
+
+- LCP、TTFB（首页、/agents、详情页）
+- 注册 → 创建 key → 首次成功调用 的转化率与耗时
+- 搜索使用率、零结果率
+- 首页 → 详情 → 调用 的点击路径
+- Publisher 提交 → 审核完成 的 SLA
diff --git a/docs/08-tech-review-2026-09-05.md b/docs/08-tech-review-2026-09-05.md
new file mode 100644
index 00000000..323300b7
--- /dev/null
+++ b/docs/08-tech-review-2026-09-05.md
@@ -0,0 +1,249 @@
+# 技术全面 Review 与优化计划（2026-09-05）
+
+> 范围：`origin/main` @ `b868319c`（含 PR #51）。全量走读 `src/`（130 个 ts/tsx，约 14.5k 行）、`prisma/`、`scripts/`、`docs/`、部署与 CI 配置；本地跑通 `tsc` / `lint` / `build` / `check:i18n` / `npm audit`；线上 curl 实测；GCP 只读 `gcloud run services describe`；并逐条对照**开放中的 PR #52**（2026-08-21，"fix(billing,security): verified gateway, billing and privacy defects"），避免重复其已修复项。
+> 配套 UX 审查见 [07-ux-review-2026-09-05.md](07-ux-review-2026-09-05.md)。
+
+> ## 实施状态（2026-09-07 更新）
+>
+> **本文的绝大部分已在 [PR #54](https://github.com/oratis/TakoAPI/pull/54) 中实现并通过 CI。**
+> 阅读时请把「现状」理解为**审查当时**（2026-09-05，`origin/main` = `b868319c`）的状态，不是当前 main。
+>
+> | 本文条目 | 状态 |
+> |---|---|
+> | §1.1 生产 DB 密码明文 | ⚠️ **仍需你操作**。PR #54 已删除脚本里的明文并改绑 Secret Manager，且加了 `check:secrets` 进 CI，但**密码本身必须轮换、历史必须清理**——从 tip 删除对已 clone 的人毫无作用 |
+> | §1.2 Apple 密钥 2026-09-25 到期 | ⚠️ **仍需你操作**。已把到期日历写进 `06-cron-schedule.md` |
+> | §1.3 PR #52 未合并 | ✅ 已并入 PR #54。`--no-cpu-throttling` 仍需部署时设置 |
+> | §1.4 `User.apiKey` 明文 | ⏸ 未做。但相关的提权风险已消除：网关 key 不再能当管理员凭据 |
+> | §1.5 登录无限流 | ✅ 已做（按账号分桶，不按可伪造的 IP 头） |
+> | §1.6 公开 API 泄露内部字段 | ✅ 已做（`lib/agent-dto` 白名单 + `reviewNote` 仅 owner/admin） |
+> | §1.7 安全响应头与 CORS | ✅ 已做 |
+> | §2 全部正确性缺陷 | ✅ 已做（含 §2.9 摄取静默失败——新增 `/api/cron/ingestion-health`） |
+> | §3 性能 | ✅ 缓存层、公开 GET 缓存头、迁移 014 搜索索引均已做。Cloud SQL 升配与连接池仍待运维决定 |
+> | §4 工程化 | ✅ 测试从 0 到 172、CI 跑全套、lockfile 修复、`engines`/`.nvmrc`、skill 正文单一来源 |
+> | §5 中期架构 | ⏸ 计量 outbox、搜索引擎升级、孤立表清理仍未做 |
+>
+> PR #54 还经过一轮 8 维度对抗式审查（每条发现由 3 名独立反驳者验证），确认并修复了 32 条缺陷，
+> 其中 4 条高危全部是该分支自己引入的回归。详见 PR 评论。
+
+---
+
+## 0. 基线快照
+
+| 检查 | 结果 |
+|---|---|
+| `npx tsc --noEmit` | ✅ 0 错误 |
+| `npm run lint` | ❌ 21 errors / 5 warnings（13 × `react-hooks/set-state-in-effect`，5 × `no-html-link-for-pages`，`no-explicit-any` ×2，`prefer-const`） |
+| `npm run build` | ✅ 通过；standalone 176 MB |
+| `npm run check:i18n` | ✅ 14 locales × 618 keys |
+| `npm ci`（Node 24 / npm 11） | ❌ lockfile 与 package.json 不同步（`@emnapi/*`）；PR #52 报告 GitHub Actions（node 20）自 2026-08-08 起同样失败 → CI 实际未在跑 |
+| `npm audit --omit=dev` | 7 high（`sharp` < 0.35，随 `next@16.3.4` 修复） |
+| 测试 | **0**（无 vitest / jest / playwright） |
+| CI | 仅 `.github/workflows/i18n.yml`（无 tsc / lint / build / test） |
+| Node 版本约束 | 无 `engines`、无 `.nvmrc`；Docker 用 node:20 |
+| Cloud Run（实测） | cpu 1 / 512Mi，`containerConcurrency=80`，`maxScale=20`，无 `minScale`，`timeoutSeconds=300`，**无 `cpu-throttling=false` 注解**（响应后 CPU 被节流） |
+| Cloud SQL | db-f1-micro（0.6 GB，docs/00 快照）；无连接池 |
+| 线上 TTFB | 首页冷 1.5 s / 热 0.8 s；`/api/agent?format=json` 冷 4.6 s / 热 0.55 s；所有页面 `Cache-Control: private, no-store` |
+| 安全响应头 | 无 HSTS / CSP / X-Frame-Options / X-Content-Type-Options / Referrer-Policy；暴露 `x-powered-by: Next.js` |
+| 公开 API CORS | 无 `Access-Control-Allow-Origin`（浏览器端无法直接调网关） |
+
+架构上值得肯定的部分：`src/lib` 分层清晰（api / schemas / ratelimit / requestLog / pagination 复用良好）；限流已落 Postgres 跨实例生效；AgentCard 抓取有大小 / 超时 / schema / SSRF（逐跳 + DNS）四重防护；ingestion 全链路幂等且尊重人工治理；i18n 深合并回退 + key 校验脚本；SEO（sitemap index、hreflang、noindex 策略、JSON-LD）完整；密钥已进 Secret Manager；cloudbuild 用 `--update-*` 不再覆盖密钥。**底子是健康的，下面是需要收口的债务。**
+
+---
+
+## 1. 🔴 P0 · 安全与运营（本周必须处理）
+
+### 1.1 生产数据库密码明文提交在公开仓库
+
+- `scripts/deploy-sync-job.sh:24,35`：`DATABASE_URL=postgresql://postgres:<redacted>@localhost/takoapi?host=/cloudsql/…`。
+- 该文件于 **2026-07-04**（`03901f2e`）进入 `main`；仓库 `oratis/TakoAPI` 为 **PUBLIC**。
+- `docs/03-secret-hardening.md` 状态追踪显示「步骤 5 密钥轮换」未做 → 这个密码大概率仍是生产密码；`docs/00-infrastructure.md` 记录该实例**有公网 IP**。
+
+**必须假定已泄露。** 行动顺序：
+1. Cloud SQL 重置 `postgres` 用户密码（或新建专用用户并回收 `postgres`）。
+2. `tako-database-url` 新增版本；Cloud Run `takoapi` 指向 `:latest` 已生效即可；Cloud Run Job `takoapi-daily-sync` 改用 `--set-secrets=DATABASE_URL=tako-database-url:latest`（当前用 `--set-env-vars` 明文）。
+3. 从脚本删除明文（改读 secret），并用 `git filter-repo` / BFG 清历史 + force push（仓库 star 1、fork 0，代价可接受）；在 GitHub 开启 secret scanning + push protection。
+4. 检查 Cloud SQL 授权网络（公网 IP 应关闭或仅允许代理）；检查 Cloud SQL 审计日志有无异常登录。
+
+### 1.2 Apple 登录密钥 2026-09-25 到期（20 天）
+
+`docs/00-infrastructure.md`：`APPLE_CLIENT_SECRET` JWT `exp=1790313380`（2026-09-25）。到期后 Apple 登录静默失败。需重签 JWT（Apple 上限 6 个月）→ `tako-apple-client-secret` 新版本，并把「Apple secret 每 5 个月续签」写进 `docs/06-cron-schedule.md` 的运维清单或建 Cloud Scheduler 提醒。
+
+### 1.3 PR #52 已开放两周未合并
+
+它修复了本次走读中同样命中的 8 个缺陷：计费 debit fire-and-forget 可丢单、SSE 按响应头即计费、限流按可伪造的 `X-Forwarded-For` 首元素分桶、cron `?key=` 进日志、`RequestLog.ip` 明文且无保留期、`ApiKey.rateLimit` 未生效、PayPal 手续费可丢、health 无历史。建议**优先合并**，并完成其 operator 清单：`--no-cpu-throttling`、迁移 010/011、`TAKO_IP_SALT`、retention scheduler job、`CRON_SECRET` 轮换。
+
+补充实测：Cloud Run 当前确实没有 `cpu-throttling=false` 注解。这意味着**所有响应后异步写都不可靠**——不只是 PR #52 说的计费，还包括 `logRequest()`（`src/lib/requestLog.ts:49`，`flushRequestLogs` 从未被调用）、`authenticateApiKey` 的 `lastUsedAt` 更新（`src/lib/apikey.ts:39`）、`meterInvocation`。要么开 always-on CPU，要么把这些写改为 await（或进队列）。
+
+### 1.4 `User.apiKey` 明文 + 管理员通道
+
+- `src/lib/admin.ts:11-14`：`x-api-key` 直接 `findUnique({ where: { apiKey } })`，命中 admin 即获全部后台 API。
+- `src/app/api/auth/register/route.ts:26,33`：`isAgent` 注册返回并明文存储 `tako_…`。
+- 与网关的 `ApiKey`（SHA-256 + prefix）并存，两套 key 体系；PR #52 已标为 deferred。
+
+方案：新增 `User.apiKeyHash`；`requireAdmin` / `getSubmitter` / `getUser` / `user/skills` 五处改为 hash 查找；过渡期双读（先 hash，再明文）；给现有 admin 重发 key；30 天后删明文列。或者更简单：**废弃 `User.apiKey`，管理员编程访问改用带 `admin` scope 的 `ApiKey`**（`scopes` 字段已存在，PR #52 标记 NOT ENFORCED）。
+
+### 1.5 密码登录无限流
+
+`/api/auth/callback/credentials` 由 NextAuth 处理，`src/proxy.ts` 的 matcher 排除 `/api`，`checkRateLimit` 只挂在 register / submit / like 等路由。撞库无成本。建议：在 `authorize()` 前按 email+IP 调 `checkRateLimit`（5 次 / 15 min），失败计数写 `RateLimitBucket`；同时补邮箱验证与密码重置（`VerificationToken` 表已存在但未用）。
+
+### 1.6 公开 API 泄露内部字段
+
+`GET /api/agents/[slug]`（`src/app/api/agents/[slug]/route.ts`）原样返回 Prisma 行：`reviewNote`（管理员内部备注）、`publisherId`（内部用户 id）、`securitySchemes`、`publisher.image`（Google 头像 URL）。`/api/registry` 与 `/api/skills/[id]`（返回 `submitter.image`、`readme` 全文 500 KB 上限）同理。建议每个公开路由定义 DTO 白名单（`select`），`reviewNote` 只对 owner / admin 可见。
+
+### 1.7 安全响应头与 CORS
+
+`next.config.ts` 无 `headers()`。补：`Strict-Transport-Security`、`X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY`（或 CSP `frame-ancestors`）、`Referrer-Policy: strict-origin-when-cross-origin`、`Permissions-Policy`，`poweredByHeader: false`。网关 `/v1/*` 与 `/api/registry` 按需开放 CORS（`Access-Control-Allow-Origin: *` + `Authorization` 头），否则浏览器端 SDK 无法使用。
+
+---
+
+## 2. 🟠 正确性缺陷（PR #52 未覆盖）
+
+| # | 缺陷 | 位置 | 影响 / 修法 |
+|---|---|---|---|
+| 2.1 | **首页与 agent 端点不过滤 `status=APPROVED`**：Must-Have / Latest Skills、`prisma.skill.count()`、`/api/agent`（供 LLM 消费的 skills 目录）、weekly digest 的 top/new 统计都包含 PENDING / REJECTED | `src/app/[locale]/page.tsx:24-33`；`src/app/api/agent/route.ts:11-27`；`src/app/api/cron/weekly-digest/route.ts:22-28` | 被拒内容出现在首页与 agent 目录。统一加 `where: { status: "APPROVED" }`，并给 `Skill` 查询封装 `approvedSkills()` helper |
+| 2.2 | `/api/agent` 搜索大小写敏感（`contains` 无 `mode: "insensitive"`）、无分页、`take: 100` 返回全文 description、无缓存，冷启动 4.6 s | `src/app/api/agent/route.ts:16-17,27` | 与 `/api/skills/search` 对齐；加 `Cache-Control` |
+| 2.3 | `viewsCount` 每次 API GET 自增（含爬虫、预取） | `src/app/api/skills/[id]/route.ts:36-39` | 实测连续两次 GET 8→9。改为页面渲染时按 IP+day 去重（`SkillEvent` 表已存在）或 sampled |
+| 2.4 | Skill 详情 like 状态不回读；`likesCount` 与 `Like` 表可漂移 | `src/app/[locale]/skills/[slug]/page.tsx:189,208-215` | GET 接口返回 `liked`；或改用 `SkillEngagement` 统一模式 |
+| 2.5 | OpenAI 兼容层：忽略 `stream: true`（返回非流 JSON，SDK 会报错）、只取最后一条 user 消息（丢 system / 历史）、无 `usage` 字段 | `src/app/v1/chat/completions/route.ts:46-47` | `stream` → 走 `message/stream` 并转成 `chat.completion.chunk` SSE；把整段 messages 编成 A2A parts；返回 `usage` 占位 |
+| 2.6 | A2A 透传只传 `text`，丢 A2A `taskId` / `contextId` / 多 parts / artifacts，多轮任务无法续接；空 `text` 也会调上游并计费 | `src/app/v1/agents/[slug]/message/route.ts:54-60` | 支持透传完整 `message`（Zod 校验），空消息 400；响应保留 task 结构 |
+| 2.7 | `/api/registry` 默认 `limit=1000` 小于目录总量（1,610 APPROVED），默认结果被截断；每次 `include skills` 全量拉取无缓存（Markdown 164 KB） | `src/app/api/registry/route.ts:9-10,52` | 默认返回 HOSTED 全量 + PROJECT 按 stars 前 N；加 `?kind=`；缓存 60 s |
+| 2.8 | `installCmd` 对 GitHub 抓取 / 用户提交的 skill 一律写 `clawhub install <slug>`（ClawHub 不存在该包） | `src/app/api/skills/submit/route.ts:64`；`scripts/scrape-github-skills.ts:137` | 只对 `source=CURATED`（ClawSkills）生成；其余给 GitHub 安装说明 |
+| 2.9 | Skills 目录自 **2026-07-04** 起零新增（daily-sync 每日 03:00 UTC 正常触发） | 线上 `/api/skills?sort=latest` 最新 createdAt = 2026-07-04 | 疑似 `scripts/daily-sync.ts` 的 puppeteer 选择器随 clawskills.sh 改版失效但静默成功。加「新增为 0 连续 N 天」告警；job 结束写 summary 到日志并在 admin 面板展示 |
+| 2.10 | `flushRequestLogs()` 定义但从未调用；`logRequest` fire-and-forget（见 §1.3） | `src/lib/requestLog.ts:47-75` | 合并到 PR #52 之后的 gatewayLog 方案：await 或队列 |
+| 2.11 | `admin.ts` 的 `unauthorized()` 返回 403 但 body 写 "Unauthorized"，与 `lib/api.ts` 的 401 语义冲突 | `src/lib/admin.ts:35` | 未登录 401 / 非 admin 403 |
+| 2.12 | 3 个 Zod schema 定义后从未使用（`adminSkillUpdateSchema` / `adminBatchSchema` / `likeParamSchema`）；5 个 admin 路由直接解构 `req.json()` 无校验 | `src/lib/schemas.ts`；`api/admin/{users/[id],skills/[id],skills/batch,categories,categories/[id]}` | 用 `parseJson()` 接上已有 schema；`categories` 补 schema |
+| 2.13 | `Rating` / `Bookmark` 旧表需手工 `id` / `updatedAt`；`Skill.clawHubUrl` 与 `clawSkillsUrl` 冗余；`AdCampaign / KolContact / KolOutreach / AuthorFollow / SkillEvent / Subscriber / BlogPost(DB)` 孤立表 | `prisma/schema.prisma` | 2026-04 决定保留；建议本季度做一次决断（导出后删除或迁移到独立 schema） |
+| 2.14 | 卡片 `AgentCard` 是 async Server Component，在列表中每张卡 `await getTranslations()` ×2 | `src/components/ui/AgentCard.tsx:59-60` | 由父级取一次 `t` 传入 |
+
+---
+
+## 3. 🟡 性能与扩展性
+
+### 3.1 零缓存 + 全站 `force-dynamic`
+
+首页 / `/agents` / 详情 / 场景 / badge 页全部 `export const dynamic = "force-dynamic"`，每次请求 5–9 个 Prisma 查询打 db-f1-micro；所有 HTML 与 JSON 都是 `Cache-Control: private, no-store`。热 TTFB 0.7–1.1 s 全部花在 DB 往返。目录数据（agents / skills / categories / counts）本质上分钟级新鲜度即可。
+
+方案（按仓库 Next 16.2.1 文档 `node_modules/next/dist/docs/01-app/02-guides/caching-without-cache-components.md` 与 `01-getting-started/08-caching.md`）：
+1. 短期：`unstable_cache` 包住只读查询（首页各版块、`/agents` 列表、categories、scenario counts、registry），`revalidate: 60–300`，打 tag（`agents`、`skills`、`categories`）；admin 写路径与 cron 结束时 `revalidateTag`。
+2. 公开 GET API 加 `Cache-Control: public, s-maxage=60, stale-while-revalidate=300`；在 Cloud Run 前挂 Cloud CDN（或 Cloudflare）让 sitemap / registry / badge / 列表页命中边缘。
+3. 中期：启用 `cacheComponents: true` + `"use cache"` / `cacheLife`，把首页做成静态 shell + Suspense 流式；登录态相关组件（Header 的 session）已是 client 组件，不阻塞。
+4. 目标：首页热 TTFB < 150 ms，DB QPS 下降一个量级。
+
+### 3.2 搜索无索引、无排序权重
+
+`name/description contains + mode: insensitive` → `ILIKE '%q%'` 全表扫描；`Skill.name` 的 btree 索引对 contains 无效；`Agent.scenarios` 数组 `has` 无 GIN 索引（migration 007 注释里明说「先不加」）；搜索结果只按 `likesCount desc`（全 0）。
+建议：`pg_trgm` GIN（`name`, `description`）+ `tsvector` 生成列（name A 权重、description B、AgentSkillDef.name C）做 `ts_rank` 排序；`scenarios` 加 GIN；MCP `search_agents` 与网页共用同一 search service。
+
+### 3.3 数据库与连接
+
+db-f1-micro（1 shared vCPU / 0.6 GB）+ Cloud Run `maxScale=20 × containerConcurrency=80` + Prisma 默认连接池（每实例 `num_cpus*2+1`）→ 峰值可超 Cloud SQL 连接上限；无 PgBouncer；`docs/agent-marketplace/03 §9` 早已列为网关前置。建议：升到 db-custom-1-3840 或 db-g1-small；`DATABASE_URL?connection_limit=5&pool_timeout=10`；评估 Cloud SQL 内置连接池 / PgBouncer sidecar。
+
+### 3.4 每请求写放大
+
+- 网关每次调用 `lastUsedAt` 更新（`apikey.ts:39`）→ 改为 60 s 内最多写一次（内存节流）或批量。
+- `RequestLog` 无限增长（PR #52 加 90 天保留）；`Invocation` 长期需要按月分区或归档。
+- 限流表每次请求 `INSERT … ON CONFLICT` 一次往返（可接受，但 60 s 窗口下 `RateLimitBucket` 清理靠随机触发）。
+
+### 3.5 前端体积
+
+首页 271 KB HTML / 68 个 script 标签，主要是 RSC payload 与 15 语种路由；`Header` 是 client 组件并把 `next-auth/react` 与 `lucide-react` 拉进首屏。建议：图标按需（已是 ESM tree-shake，确认 bundle）；Header 拆成 server shell + 小的 client 岛（session 菜单 / 搜索）；开启 `experimental.optimizePackageImports`。
+
+---
+
+## 4. 🟡 代码质量与工程化
+
+| # | 问题 | 证据 | 建议 |
+|---|---|---|---|
+| 4.1 | **无测试**；CI 只跑 i18n 且自 08-08 失败；本地 `npm ci` 失败 | `.github/workflows/i18n.yml`；`package.json` 无 test/typecheck | 见 §6 T0/T1 |
+| 4.2 | 工具链：无 `engines` / `.nvmrc`；package name 仍是 `takoapi-temp`；`scripts/` 排除在 tsc 之外 | `package.json`、`tsconfig.json:exclude` | `"engines": { "node": "20.x" }` + `.nvmrc`；scripts 纳入 `tsc -p tsconfig.scripts.json` |
+| 4.3 | lint 21 errors 长期存在（含 `react-hooks/set-state-in-effect` 13 处，全部是「effect 里 fetch 再 setState」的数据加载模式） | `npm run lint` | 数据加载改 Server Components / `use()`；剩余用 `useSyncExternalStore` 或 SWR |
+| 4.4 | 页面模式分裂：admin / dashboard / profile / skills / trending / submit 是 client 页 + `fetch('/api/…')`；其余是 server 页直连 Prisma。同一数据两套获取路径，且 API 路由为了页面而存在 | `src/app/[locale]/**` | 统一为 RSC 读 + Server Actions 写；对外 API 只保留真正对外的（registry / skills / agents / v1 / mcp） |
+| 4.5 | 重复代码：`AgentEngagement` ≈ `SkillEngagement`；agent/skill 的 rating、bookmark 路由成对复制；`getSubmitter` 两份；`slugify` 三份（`lib/utils`、`import-hosted`、`scrape-agents`、`seed`，行为还不一致：截断 60 / 80 / 120）；skill 正文四份（`takoapi_skill/SKILL.md` 与 `plugins/…` 已漂移，md5 不同） | grep 结果 | 抽 `Engagement` 泛型组件；`entityEngagement(model)` 路由工厂；`slugify` 单一实现；skill 正文 codegen（build 时从一份源生成 install.sh heredoc / plugin / npm assets） |
+| 4.6 | 吞错：6 处空 `catch {}`（`ratelimit.ts`、`apikey.ts`、stream 路由、admin skills、submit-agent） | grep | 至少 `console.error` 结构化日志；限流/计费类失败计 metric |
+| 4.7 | 无可观测性：仅 `console.error`，无 request id、无 tracing、无告警；cron 结果返回给 Scheduler 后丢弃 | — | OTel（`@vercel/otel` 或 `@opentelemetry/sdk-node`）→ Cloud Trace；结构化 JSON 日志；Cloud Monitoring 告警：5xx 率、DB 连接、cron 失败 / 零产出、Apple secret 到期 |
+| 4.8 | 依赖：`next-auth@5.0.0-beta.32`（生产用 beta，`npm outdated` 显示 latest 仍是 v4）；`prisma@6.19`（7.x 可升）；`next@16.2.1`（16.3.4 修 sharp 高危） | `npm outdated` / `npm audit` | 先升 next 到 16.3.x 修 audit；Prisma 7 单独评估（生成器 / 连接池变化） |
+| 4.9 | 文档漂移：README「Project Structure」还是 `app/agents/`（实际 `app/[locale]/`）；`docs/README.md` 仍写新方向「尚未动手实现」（Phase 1+2 已上线）；HANDOFF 说 registry 上限 200（已 1000）；`docs/00` 是 2026-04 快照（17 model → 现 30 model） | — | 每次迁移后更新 `docs/00`；README 结构段自动生成或删掉 |
+| 4.10 | i18n：`scenarios.ts` 的 `nameZh` / `blurb` 双语硬编码，admin 键值中英混排；`LOCALE_META` 与 `routing.locales` 需手工同步（已有 TS 约束，好） | `src/lib/scenarios.ts`、`messages/*.json` Admin.* | 场景文案全部进 messages；后台只保留英文 |
+
+---
+
+## 5. 🟢 中期架构建议
+
+1. **网关数据面**：透传完整 A2A（message parts / task / contextId），返回 task 结构；per-agent 断路器（连续失败 → 快速 503，而不是每次等 30 s 超时）；`healthStatus=down` 的 agent 直接快速失败；上游超时按 agent 可配；A2A 流式加 `X-Accel-Buffering: no`。
+2. **计量与计费**：PR #52 的 await debit 之后，再引入 outbox（`Invocation` 先写、结算异步）+ Cloud Tasks / Pub/Sub 重试；落地 `ApiKey.scopes`（`read` / `invoke` / `admin`）与 `monthlyQuota`；账本对账脚本（`CreditBalance` = Σ `LedgerEntry`）每日跑。
+3. **发现层**：Postgres FTS 起步；目录超过 1 万条或需要语义检索时上 Typesense / Meilisearch；对 AgentCard `skills[]` 做 embedding 支持「按能力找 agent」（这是差异化点）。
+4. **内容摄取**：daily-sync（puppeteer 抓 clawskills.sh）脆弱且已疑似失效 2 个月 → 优先找 ClawSkills 是否有 API / sitemap；统一三条 ingestion 管道的「结果摘要 → 日志 → 告警」。
+5. **数据模型清理**：决断孤立表；`Rating` / `Bookmark` 改 Prisma 管理 id；`Skill.downloads` → `externalDownloads`（PR #52 deferred）；`Agent` 拆出 `AgentHealthCheck`（PR #52 已加）。
+6. **部署链**：Cloud Build trigger 接 `main`（当前手动 `gcloud builds submit`，无法保证线上 = main）；镜像内跑 `prisma migrate deploy` 前先修正 `_prisma_migrations` 基线（HANDOFF §5 说明当前不可靠）；Cloud Run 开 `min-instances=1` 消除冷启动（首页冷 TTFB 1.5 s、`/api/agent` 4.6 s）。
+
+---
+
+## 6. 优化计划
+
+> 每阶段结束停下验收；T0 与 U0（UX 文档）可并行。
+
+### T0 · 本周（≤ 3 人日）
+
+| 项 | 内容 | 验收 |
+|---|---|---|
+| T0-1 | §1.1 DB 密码轮换 + 脚本去明文 + 历史清理 + push protection + 授权网络检查 | 旧密码连接失败；`git log -S '<旧密码>'` 为空 |
+| T0-2 | §1.2 Apple secret 续签 + 到期提醒 | Apple 登录 09-25 后仍可用 |
+| T0-3 | 合并 PR #52 并完成其 operator 清单（`--no-cpu-throttling`、迁移 010/011、`TAKO_IP_SALT`、retention job、`CRON_SECRET` 轮换） | 计费调用 debit 同步落库；`RequestLog.ip` 列已删除 |
+| T0-4 | §2.1 `APPROVED` 过滤（首页 / `/api/agent` / weekly digest）；§2.8 `installCmd` 修正 | 用 REJECTED skill 验证不再出现 |
+| T0-5 | §1.7 安全头 + `poweredByHeader:false`；§1.6 `/api/agents/[slug]` 与 `/api/skills/[id]` 白名单 | `curl -I` 可见 5 个安全头；响应无 `reviewNote` / `publisherId` |
+| T0-6 | 工具链：重生成 lockfile（node 20 环境）+ `engines` + `.nvmrc`；CI 加 `tsc --noEmit`、`lint`、`build`；lint 清零（`--fix` + 手改） | GitHub Actions 全绿；`npm ci` 在 node 20 / 24 均通过 |
+
+### T1 · 2 周
+
+| 项 | 内容 | 验收 |
+|---|---|---|
+| T1-1 | §3.1 缓存层：`unstable_cache` + tag 失效；公开 GET API `Cache-Control`；CDN | 首页热 TTFB < 150 ms；DB 查询量 −80% |
+| T1-2 | §1.5 登录限流 + 邮箱验证 + 密码重置 | 6 次错误密码 → 429 |
+| T1-3 | §1.4 `User.apiKey` 迁移（hash 或废弃改 `ApiKey` scopes） | DB 中无明文 key |
+| T1-4 | §3.2 `pg_trgm` / tsvector 索引 + 排序权重；`scenarios` GIN | `EXPLAIN` 走索引；搜索 p95 < 50 ms |
+| T1-5 | 测试基线：vitest 覆盖 `lib/`（ratelimit、billing、agentcard、scenarios、topup、pagination、sitemap-shape）；Playwright 冒烟 5 条路径（首页 / agents / 详情 / 登录 / dashboard）；CI 跑测试 | 覆盖率 lib ≥ 60%；PR 必过 |
+| T1-6 | §2.9 daily-sync 修复 + 三条 ingestion 的结果告警 | Skills 目录恢复增长；Cloud Monitoring 告警生效 |
+| T1-7 | §2.2 / §2.7 `/api/agent` 与 `/api/registry` 分页、大小写、缓存、默认范围 | `/api/agent` p95 < 300 ms |
+
+### T2 · 3–4 周
+
+| 项 | 内容 | 验收 |
+|---|---|---|
+| T2-1 | §4.4 skills / trending / skill 详情 / profile / dashboard 迁移为 RSC + Server Actions；组件层抽取 | Skill 详情 HTML 含正文；`set-state-in-effect` 为 0 |
+| T2-2 | §2.5 / §2.6 OpenAI shim 流式 + 历史；A2A 完整透传；断路器 + health 快速失败 | 用 OpenAI SDK `stream=True` 可用；down agent 100 ms 内 503 |
+| T2-3 | §4.7 OTel + 结构化日志 + 告警；request id 贯穿 | Cloud Trace 可见网关 → 上游 span |
+| T2-4 | §3.3 Cloud SQL 升配 + 连接池参数；`min-instances=1` | 冷启动消失；连接数曲线平稳 |
+| T2-5 | §4.5 去重（Engagement / 路由工厂 / slugify / skill 正文 codegen） | 四份 skill 正文 md5 一致且由脚本生成 |
+| T2-6 | §4.8 `next@16.3.x`（修 sharp）；评估 Prisma 7；next-auth 稳定版策略 | `npm audit` 0 high |
+
+### T3 · 季度
+
+- 计量 outbox / 队列化；`scopes` / `monthlyQuota` 生效；账本对账。
+- 搜索升级（FTS → 引擎 / embedding）。
+- 数据模型清理（孤立表决断、Rating/Bookmark 规范化、`downloads` 重命名）。
+- Cloud Build trigger + 迁移基线修复 + 一键回滚脚本。
+- 文档：`docs/00` 重新快照；README 结构段；API reference 从代码生成（OpenAPI）。
+
+---
+
+## 附录 A · 本次核验命令
+
+```bash
+npm install && git checkout -- package-lock.json   # npm ci 在 npm 11 下失败
+npx prisma generate && npx tsc --noEmit             # 0 errors
+npm run lint                                        # 21 errors / 5 warnings
+npm run build                                       # OK
+npm run check:i18n                                  # 14 locales × 618 keys
+npm audit --omit=dev                                # 7 high (sharp)
+for u in / /agents "/api/agent?format=json"; do curl -s -o /dev/null -w "$u %{time_starttransfer}\n" "https://takoapi.com$u"; done
+curl -sI https://takoapi.com/ | grep -iE 'strict|frame|content-type-options|cache-control|x-powered'
+gcloud run services describe takoapi --region us-central1 --project takoapi-491505 --format='yaml(spec.template.metadata.annotations,spec.template.spec)'
+```
+
+## 附录 B · 与 PR #52 的对照
+
+| 本文条目 | PR #52 状态 |
+|---|---|
+| 计费 fire-and-forget / SSE 计费 / 限流 IP 分桶 / cron `?key` / RequestLog IP 与保留 / `ApiKey.rateLimit` / PayPal 手续费 / health 历史 / trending 文案 | ✅ 已修（待合并） |
+| `User.apiKey` 明文、`Skill.downloads` 重命名、`scopes` / `monthlyQuota`、`userAgent` 全文存储 | ⏸ PR 内标为 deferred，本文纳入 T1 / T3 |
+| §1.1 DB 密码泄露、§1.2 Apple secret 到期、§1.5 登录限流、§1.6 API 字段泄露、§1.7 安全头、§2.1 状态过滤、§2.3 views 刷量、§2.5–2.9、§3 全部、§4 全部 | 🆕 本文新增 |
diff --git a/docs/README.md b/docs/README.md
index f7448637..3180d314 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,6 +10,13 @@
 
 ---
 
+## 🔍 全面 Review（2026-09-05）
+
+- **[07-ux-review-2026-09-05.md](07-ux-review-2026-09-05.md)** —— UX 全面审查：信息架构 / 首页 / 发现 / 详情 / 转化漏斗 / 可访问性 / 文案清单，附 U0–U3 分阶段优化计划。
+- **[08-tech-review-2026-09-05.md](08-tech-review-2026-09-05.md)** —— 技术全面审查：P0 安全运营（DB 密码泄露、Apple 密钥到期、PR #52）、正确性缺陷、性能、工程化、中期架构，附 T0–T3 分阶段计划与验收标准。
+
+---
+
 ## 📋 当前路线图
 
 按顺序执行：