# weapp-tailwindcss 上手与 AI 工作流
> 快速接入、模板、CLI 与 AI 辅助编排的完整内容，优先用于回答「如何开始」「如何让 AI 生成小程序代码」类问题。
This file contains all documentation content in a single document following the llmstxt.org standard.
## AI 编程助手落地实施方案
> 你会得到：一套“能拍板、能试点、能复制”的落地方法（可治理、可控成本、可降级、可回滚）。\
> 更新时间：2025-12-29。计价说明：人民币换算按 1 USD = ¥7.2；价格与配额可能随时调整；以供应商官网与实际账单为准。
:::tip 这篇文档怎么读（别从头硬啃）
- 只想快速决策：先看「0 一页结论」→「5 座席设计」→「11 执行清单」。
- 要做试点落地：先看「6 路线图」→「7 仓库接入」→「8 日常 SOP」→「9 网络/账号/合规」。
- 研发负责人：0 / 5 / 6 / 11
- 平台与工具团队：6 / 7 / 8 / 9
- 安全合规：2 / 7 / 9
- 采购与财务：4 / 5 / 11
:::
:::note 先记住三句话（后面所有细节都在解释这三句话）
1. 合规不清楚时，默认用国产把流程跑通。
2. 海外体验好不好，80% 取决于网络与代理是否“IDE + CLI + 登录”一致。
3. 成本能不能控住，靠“座席分层 + 预算上限 + 触顶降级”，不靠自觉。
:::
---
## 0. 一页结论（先做决策，再做对比）
### 0.1 决策最短路径（建议按这个顺序拍板）
1. **合规边界**：哪些仓库/文件允许出境？是否必须审计留痕？（决定能不能用海外、能用到什么程度）
2. **网络能力**：是否能提供“IDE + CLI + 登录”同策略代理，并有备用出口与健康检查？（决定海外体验与成本是否可控）
3. **治理能力**：是否需要 SSO/团队配额/账单中心/审计？预算上限与告警责任人是谁？（决定能不能规模化）
4. **交付策略**：默认走低价/国产，高阶/海外按任务升级（而不是全员默认高阶）（决定 ROI 与成本波动）
5. **复制方式**：仓库接入模板与 SOP 能不能“一键复制”（决定试点能不能扩散）
### 0.2 快速分流（用一句话选出“主力方案”）
```mermaid
flowchart TD
A[准备引入 AI 编程助手] --> B{代码出境/合规允许吗?}
B -- 否/不确定 --> C["主力：国产（GLM/Qoder）
先把规范、仓库分级、审计与 SOP 跑通"]
B -- 是 --> D{海外网络与采购能闭环吗?}
D -- 否 --> C
D -- 是 --> E{是否要统一 IDE 作为工作台?}
E -- 是 --> F["主力：Cursor（Business/Pro）
国产作为兜底与降级"]
E -- 否 --> G["主力：Claude Code / Codex / Gemini（CLI/插件）
国产作为兜底与降级"]
C --> H[按仓库分级 + 座席分层 + 预算上限 + 可回滚]
F --> H
G --> H
```
### 0.3 默认推荐（适用于大多数公司）
- **默认主力**：国产（GLM 或 Qoder）覆盖 70-85% 日常工作（补全、小改动、单测草稿、文档草稿）。
- **能力增强**：少量海外高阶座席（Cursor/Claude/Codex/Gemini）只用于“跨文件重构/疑难排查/核心模块审查/迁移方案”等高价值任务，并要求留痕与验收。
- **落地关键**：把“仓库分级 + 接入模板 + 预算上限 + 试点评估指标 + 回滚预案”当作一套工程系统，而不是发账号。
---
## 1. 我们要解决什么问题（落地目标与边界）
### 1.1 业务目标（建议写进 OKR）
- **效率**：提升日常编码速度（补全、重构、脚手架、查错、写测试、写文档）。
- **质量**：减少低级错误、提升可读性、一致性、单测覆盖率、PR 审查质量。
- **稳定**：在网络抖动/供应商限流/额度耗尽时，不影响核心交付（可降级/可回滚）。
- **合规**：明确哪些仓库/文件可用于 AI，上线前把出境、日志、留存、审计走通。
- **成本可控**：把“按量爆炸”风险降到最低（预算、告警、上限、分层座席）。
### 1.2 范围边界（避免项目失控）
- 本文仅讨论 **订阅型** AI 编程产品落地（IDE/CLI/Code Assist 套餐），**不单独设计“直接调用 API”的落地方案**。
- CI/CD 自动化如果要用 AI，优先使用供应商提供的 **官方能力**（如 PR Review、官方 CLI/插件），不建议自研“无限制 API 调用”。
- “AI 生成的代码”一律视为 **外部输入**：必须通过测试、代码审查、静态检查；不得直接上生产。
### 1.3 术语（让跨团队对齐）
- **补全**：Tab/Inline completion，一般成本最低、收益最高。
- **Chat / Agent**：对话式改代码、跨文件重构、读写文件、跑命令；成本更高、也更容易触碰合规边界。
- **座席分层**：并不是每个开发都用同样档位；核心成员/架构师/平台组用更高档位，其它人用基础档位。
- **仓库敏感度**：涉密/受限/合规严格的仓库与开源/公共仓库，允许的模型与策略不同。
---
## 2. 选型原则（先解决网络与合规）
### 2.1 两道门槛（Gate）：先能用、再用好
- **Gate A：合规与数据边界**（能不能用、能用到什么程度）
- 代码出境是否允许？允许到什么仓库等级/目录/分支？
- 是否必须可审计（谁在什么仓库用过什么能力）？日志如何留存、谁能访问？
- **Gate B：网络与采购闭环**（能不能稳定用、成本能不能控住）
- 是否能提供“IDE + CLI + 登录”同策略代理，并有备用出口与健康检查？
- 账号归属、统一账单、成本分摊、预算上限与告警责任人是否明确？
结论：**两道门槛都过了，海外能力才适合作为日常增强；任一没过关，优先按国产方案落地，把 SOP 与治理跑通，再引入海外。**
### 2.2 前提清单（要求“可验证”，避免口头承诺）
- 海外网络稳定：有健康检查数据（延迟/失败率）与备用出口；IDE 与 CLI 同策略；故障有降级预案。
- 合规已确认：书面结论明确出境范围；敏感目录黑名单可配置；审计与留存要求能落地。
- 采购支付可闭环：统一账单与成本中心；预算上限、告警阈值、责任人明确；离职回收流程明确。
- 用量能治理：团队配额/个人上限/触顶降级策略可执行（而不是“靠自觉”）。
### 2.3 怎么对比（前提满足后再对比）
| 维度 | 权重建议 | 评分要点（示例） | 怎么验证（建议） |
| ---------- | -------- | ------------------------------------------------ | ----------------------------------------------- |
| 合规/数据 | 30% | 出境边界、敏感路径屏蔽、审计日志、企业条款 | 合规书面结论 + 管理后台能力验证 + 试点抽样审计 |
| 可治理性 | 20% | 团队配额、SSO、成员管理、账单中心、管理员策略 | 管理后台演示/截图 + 账号回收演练 + 账单样例 |
| 体验与产能 | 20% | 补全质量、跨文件编辑、上下文、延迟、稳定性 | 用统一任务集试点对比（见 6.1/8.2 的场景） |
| 成本与可控 | 15% | 订阅单价、超额机制、是否易“按量爆炸”、是否可降级 | 账单实测 + 触顶降级演练 + 故障重试成本估算 |
| 集成能力 | 10% | VS Code/JetBrains/CLI/PR Review 支持、可配置性 | 在 1-2 个真实仓库接入验证（模板/忽略规则/命令） |
| 供应商风险 | 5% | 区域可用性、风控、服务 SLA、支付风险 | 历史可用性记录 + 支付与风控预案 + 可替代性评估 |
打分建议：每个方案 1-5 分，乘以权重；**先预设权重与通过条件**，试点后再复盘调整（避免“移动门槛”）。
### 2.4 选型评审要交付什么（避免只留一句“选 A”）
- 推荐结论：**主力方案 + 备份/降级方案**（故障/额度/风控时怎么切换）。
- 约束条件：仓库分级策略、允许能力（补全/对话/Agent）、审计与留存要求。
- 座席设计：分层（L1-L4）、升级流程、个人上限与团队配额、触顶降级策略。
- 落地计划：12 周里程碑（试点范围、复制范围、验收指标与 Go/No-Go）。
- 风险与缓解：合规、网络、供应商、成本波动、误改与质量风险，以及对应回滚方案。
---
## 3. 方案概览（我们讨论的 4 种可落地方案）
> 提示：如果网络/合规未就绪，先看 GLM/Qoder 两行，其它方案先当作备选。
| 方案 | 定位 | 典型个人月成本 | 典型团队 5 人月成本 | 关键依赖 | 适用结论 |
| ---------------------------- | -------------------- | -------------------- | ------------------- | --------------- | ------------------------------ |
| Cursor | AI IDE（统一工作台） | ¥144（Pro） | ~¥1,440（Business） | 海外网络/信用卡 | 体验优先、愿意统一 IDE 的团队 |
| Claude Code / Codex / Gemini | 海外订阅（插件/CLI） | ¥136-216 | ¥900-1,900 | 海外网络/信用卡 | 已有海外账单、偏 CLI/PR Review |
| GLM | 国产高刷新额度 | ¥100（Pro） | ~¥500（Pro\*5） | 无需代理 | 国内合规/报销友好、主力方案 |
| Qoder | 国产/混合路由 | ¥144-432（Pro/Pro+） | ~¥1,080（Teams\*5） | 国产为主 | 需要审计与团队管理、混合路由 |
---
## 4. 价格与额度（只保留对企业/大多数人有用的档位）
> 说明：下表用于预算与座席设计，不用于“攀比模型能力”。落地时真正影响成本的是：谁用高档位、是否有上限、网络稳定性（减少重复调用）、是否有明确的“默认低价模型策略”。
:::note 额度口径（先搞清楚你买的是什么）
不论是 Cursor、Kiro、GitHub Copilot 这类产品，本质上都是“使用 AI 的工作台/入口 + 各自最佳实践的工程化封装”，它们并不等同于某一个模型本身。
购买订阅时，你通常同时买到了两件事：
1. **工具能力**：IDE/插件/Agent 工作流、上下文管理、代码索引、团队治理等。
2. **供应商二次封装的模型调用额度**：对外表现为“对话次数/请求次数/快速请求/每周配额”等（而不是你能直接对账的 token 用量）。
优劣势也来自这里：
- **优势**：可以在不同模型之间切换/路由，按任务选“更强/更便宜/更稳”的模型；同时工具会给出默认提示词、工作流与防呆策略。
- **劣势**：你往往看不到真实 token 消耗与单次请求的边际成本；而按“对话/请求”计数时，**简单任务与复杂任务可能消耗同样 1 次额度**，导致成本预测与审计颗粒度变粗。
落地建议：预算口径按“座席 + 额度”做上限控制，同时用“默认低价模型 + 触顶降级 + 高阶任务审批/白名单”把波动压住。
:::
### 4.1 Cursor（官网可访问：已核实）
| 套餐 | 月付 | 年付折算 | 适用人群（企业落地建议） | 人民币估算 |
| -------- | -------- | -------- | ----------------------------- | ------------ |
| Pro | $20 | $200 | 普通开发（愿意用 Cursor IDE） | ¥144/月 |
| Pro+ | $60 | - | 核心开发/架构师（重度 Agent） | ¥432/月 |
| Business | $40/用户 | - | 需要 SSO/审计/团队配额的团队 | ¥288/用户/月 |
| Ultra | $200 | - | 极重度座席（专项、平台组） | ¥1,440/月 |
来源：（抓取到 Pro/Pro+/Ultra/Business）。
### 4.2 海外订阅（Claude Code / Codex / Gemini）
> 说明：海外产品的定价页可能因地区风控（如 Cloudflare）、登录态或动态渲染而不易自动抓取；以下仅保留“企业普遍会用的档位”与常见区间用于预算讨论。正式采购前请以供应商官网与合同条款再次核对。
| 方案 | 企业常用档位 | 常见价格（USD） | 适用人群 | 关键注意点 |
| ------------------ | --------------------- | ------------------------------------- | ----------------------- | ---------------------------------- |
| Claude Code | Pro / Teams | $20 / $40/用户 | CLI/Agent 重度团队 | 区域可用性、周配额、超额策略 |
| Codex / ChatGPT | Team | ~$25/用户（年付）或 ~$30/用户（月付） | 跨团队通用 | 网页难抓取，采购前核对；设账单上限 |
| Gemini Coding Plan | Standard / Enterprise | $19 / $45 | 有 PR Review 诉求的团队 | GCP 账单体系、日配额、账号治理 |
### 4.3 GLM Coding Plan（国产，主力）
| 套餐 | 月费 | 刷新周期 | 日可用（4-5 次刷新） | 企业落地建议 |
| ---- | ---- | --------- | -------------------- | ----------------- |
| Pro | ¥100 | 每 5 小时 | 2400-3000 次 | 默认给大多数研发 |
| Max | ¥400 | 每 5 小时 | 9600-12000 次 | 核心座席/批量任务 |
### 4.4 Qoder（国产/混合）
| 套餐 | 月付标价（USD） | 人民币估算 | 企业落地建议 |
| --------------- | --------------- | ------------ | ----------------------- |
| Pro | $20 | ¥144/月 | 普通席位 |
| Pro+ | $60 | ¥432/月 | 核心席位/偶尔重任务 |
| Ultra | $200 | ¥1,440/月 | 极重度席位（专项/平台） |
| Teams（按席位） | $30/用户 | ¥216/用户/月 | 需要审计/团队治理 |
说明：Qoder 定价接口会返回折扣字段（如 `discountedPrice` / `firstMonthPrice`），活动可能变化；预算建议按标价估算更稳。\
页面：。\
接口（用于抓取标价/折扣字段）：、。
---
## 5. 企业级座席设计（怎么买才不浪费）
### 5.1 分层座席（推荐）
| 层级 | 占比建议 | 目标 | 推荐档位（示例） |
| ------------- | -------- | -------------------------- | --------------------------------------------- |
| L1 普通开发 | 70-85% | 日常补全+小改动 | GLM Pro / Qoder Pro / Cursor Pro |
| L2 核心开发 | 10-20% | 跨文件改造、重构、疑难排查 | Cursor Pro+ / GLM Max / Qoder Pro+ |
| L3 审查/架构 | 3-8% | 评审、设计、复杂迁移 | Claude Code Teams / Cursor Business / GLM Max |
| L4 平台与专项 | 1-3% | 规范化、模板化、内建流程 | Cursor Ultra（少量）/ GLM Max |
### 5.2 典型公司规模预算模板
> 这里的关键是“组合”，而不是单点选择。你可以把海外座席当作“稀缺资源”，像数据库/CI 一样管理。
#### 10 人团队（初期）
- 8 人：GLM Pro（8 \* ¥100 = ¥800/月）
- 2 人：Cursor Pro（2 \* ¥144 = ¥288/月）或 Qoder Pro（2 \* ¥144 = ¥288/月）
- 合计：约 ¥1,000/月（视组合而定）
#### 30 人团队（业务线）
- 24 人：GLM Pro（¥2,400/月）
- 4 人：GLM Max（¥1,600/月）
- 2 人：海外高阶（Cursor Pro+/Claude Code Teams 按需）
- 合计：约 ¥4,000-6,000/月
#### 100 人公司（多业务线）
- 80 人：GLM Pro
- 15 人：Qoder Teams 或 GLM Max（根据是否需要审计/团队治理）
- 5 人：海外增强座席（Cursor Business/Claude Teams）
- 合计：根据审计诉求与海外座席数量决定，建议先做试点测算再采购。
---
## 6. 落地路线图（公司多团队循序渐进）
> 落地不是“一天开通全员账号”，而是建立 **规范 + 试点 + 复制 + 治理** 的闭环。
### 6.1 建议里程碑（12 周模板，可按公司节奏调整）
| 周期 | 目标 | 关键交付 | 通过标准（能不能进下一阶段） |
| ----------- | ---------- | -------------------------------------------------- | ---------------------------------- |
| 第 1-2 周 | 准备与对齐 | 使用规范、代理方案、仓库分级、预算与告警、试点名单 | 代理可用 + 合规确认 + 预算可控 |
| 第 3-6 周 | 试点落地 | 试点团队跑通补全/对话/审查 SOP；建立指标看板 | 指标不比基线差，且成本可解释 |
| 第 7-10 周 | 复制扩展 | 同业务线 3-5 个团队复制模板、固化仓库接入规范 | 运营体系可规模化（账号/配额/培训） |
| 第 11-12 周 | 公司级治理 | 座席分层、审计流程、离职回收、季度复盘机制 | 有回滚预案 + 能输出管理报告 |
### 6.2 角色与 RACI（建议落地前先定责）
| 事项 | 研发负责人 | 平台/中台 | 安全合规 | 采购财务 | 业务团队 TL |
| -------------- | ---------- | --------- | -------- | -------- | ----------- |
| 方案选型与原则 | A | C | C | C | C |
| 代理/网络方案 | C | A/R | C | - | C |
| 仓库分级与红线 | C | R | A/R | - | C |
| 账号/SSO/回收 | C | A/R | C | - | C |
| 预算/账单/告警 | A | R | C | A/R | C |
| 培训与推广 | C | R | C | - | A/R |
| 试点验收 | A | R | C | C | A/R |
说明：A=最终负责，R=执行负责，C=协作/咨询。看不懂 RACI 也没关系：关键是每一项都有明确“拍板的人”和“干活的人”。
### 6.3 试点怎么做，结果才“说得清”
很多试点翻车不是“工具不行”，而是两件事没做好：**口径不统一**、**过程不可复用**。下面这套做法的目标很简单：试点结束后，你能用数据和案例回答清楚——“值不值、为什么值、下一步怎么扩”。
**(1) 先写清楚：通过/不通过的条件（避免试点结束才开始争论）**
- 选 4 类指标（见阶段 1）：产能、质量、体验、成本；每类至少 1 个“硬指标”。
- 写清楚“最低可接受标准”，例如：
- 质量不下降：CI 失败率、线上缺陷率不高于基线（或有明确可解释原因）。
- 成本可控：人均月成本不超过预算上限；触顶/故障重试可被降级策略吸收。
- 体验可用：95 分位延迟与失败率在可接受区间（由平台/IT 提供数据）。
**(2) 用一套“真实任务样本”对比（避免“挑题做”）**
建议准备 10-20 个“真实任务样本”，覆盖 8.2 的高 ROI 场景，并记录最少信息：
| 字段 | 说明 |
| ----------- | ---------------------------------------------- |
| 任务类型 | 补全/小 bug/跨文件重构/补单测/PR Review/文档 |
| 仓库等级 | S0/S1/S2（决定允许能力与工具） |
| 复杂度 | 低/中/高（或 Story Points） |
| 基线耗时 | 试点前同类任务平均耗时（2-4 周窗口） |
| AI 辅助耗时 | 试点期间耗时（含验证时间） |
| 验证方式 | 跑了哪些命令/截图/日志 |
| 成本与失败 | 是否发生重试/超额/代理故障（以及怎么降级处理） |
**(3) 先把常见“试点错觉”写进复盘（避免“看起来提升”）**
- **人选偏差**：只让最强/最爱尝鲜的人用 → 尽量选“正常团队”，或分批灰度做对照。
- **新鲜感效应**：前 1-2 周提升很大、后面回落 → 试点至少 2-4 周，并单独看第 3-4 周的表现。
- **指标选错**：只看提交数会鼓励碎片化 → 同时看交付周期、返工率、缺陷率等质量指标。
- **外部干扰**：大版本/大促/人手变动会影响指标 → 记录关键事件，必要时只对同类任务做对比。
**(4) 试点结束必须产出的 3 件东西（否则很难复制）**
- “一页结论”：是否通过、通过条件是否满足、主要收益与代价、是否建议扩展。
- “可复制资产”：仓库接入模板（7.2）、日常 SOP（8）、培训材料、故障降级预案（9.1.5）。
- “治理数据”：账单样例、触顶次数、降级次数、代理故障次数、抽样审计结果。
### 阶段 0：基础准备（1-2 周）
**输出物（交付件）**
- 《AI 编程使用规范》（Do/Don’t、允许的仓库/文件类型、敏感信息处理）。
- 《网络与代理配置手册》（IDE/CLI 统一代理、故障排查）。
- 《座席分层与预算》（谁能用什么、如何申请升级、超额如何处理）。
- 《审计与留痕要求》（日志保存、审批流、回滚机制）。
**关键动作**
- 网络：确定海外代理出口、白名单域名、稳定性指标（例如 95 分位延迟 < 300ms）。
- 合规：建立“仓库分级”（涉密/一般/开源），明确每级允许的模型与功能（仅补全/允许 Agent/禁止上传）。
- 采购：海外信用卡/虚拟卡管控；国产发票与成本中心；设置预算上限与告警责任人。
- 工程：统一 PR 模板与仓库接入模板（`AI_RULES.md`/`.aiignore`/`.cursorignore`/`CLAUDE.md`），并要求所有新仓库默认带上。
- 指标：在试点前先采集 2-4 周基线（交付周期、PR 数、缺陷率、CI 失败率），否则试点“效果”无法客观评估。
### 阶段 1：试点（2-4 周，1-2 个低风险团队/仓库）
**选试点的原则**
- 优先选择：非涉密、迭代快、指标容易量化（例如 Web/工具链/中台项目）。
- 避免选择：强合规、强审计、外包多、依赖复杂且无法量化的项目作为第一个试点。
**试点最小可行配置（MVP）**
- 主力：GLM Pro 或 Qoder Pro（覆盖绝大多数人日常）
- 增强：1-2 个海外座席（Cursor Pro 或 Claude Code Pro），用于复杂任务对比
- 策略：默认国产/低价模型；高阶模型必须手动切换并记录原因（模板见后文）
**验收指标（建议至少选 4 个）**
- 产能：人均提交数/PR 数、交付周期、返工率（对比试点前 2-4 周基线）。
- 质量：PR 审查发现问题数、线上缺陷率、单测增量。
- 体验：补全采纳率、平均响应时间、失败率/重试率。
- 成本：人均月成本、超额次数、代理故障导致的重复调用次数。
- 对比口径：尽量按“同类任务 + 同时间窗口”对比，并记录版本发布/需求波峰等关键事件，避免把波动误判为收益或损失（见 6.3）。
**回滚预案**
- 一键禁用：插件/IDE 可快速关闭；路由切换到国产。
- 代理故障：提供备用节点/备用出口；明确故障期间“只允许补全，不允许 Agent”。
### 阶段 2：业务线扩展（4-8 周，同业务线复制）
**复制的关键不是“发账号”，而是“复制模板”**
- 复制：代理配置、索引黑名单、仓库接入模板、培训材料、指标看板。
- 分层路由：
- 基线：国产（GLM/Qoder）+ 本地索引。
- 提升：评审/复杂改造才切海外高质量模型（需要审批或留痕）。
- 限额：按团队等级设月/周上限，触顶自动降级到国产/低价。
**推广培训**
- 10-15 分钟“快速上手”培训：快捷键、常用 Prompt、如何让 AI 写测试、如何审查 AI 输出。
- 30-45 分钟“进阶训练营”（核心成员）：跨文件重构、定位性能问题、生成迁移方案、拆分任务。
### 阶段 3：全公司规模化（持续）
**公司级治理要点**
- 账号与权限：SSO/成员管理；离职/转岗自动回收；关键岗位开更高档位。
- 指标与报表：月度用量、超额、延迟、故障次数、单位 PR 成本；对管理层输出 1 页报告。
- 规范固化：将“AI 生成代码必须跑测试/必须评审”的规则写进工程模板与 PR 模板。
### 阶段 4：优化与复盘（季度节奏）
- 成本优化：把高阶模型使用集中到“收益最大”的场景（评审、迁移、疑难）；日常用低价/国产。
- 体验优化：根据延迟与失败率，优化代理与路由策略；必要时切换主力供应商。
- 合规复核：更新敏感目录黑名单、出境白名单；抽样审计调用日志与 PR 记录。
---
## 7. “落地到每个项目”怎么做（仓库接入规范）
### 7.1 仓库分级（强烈建议公司统一）
| 等级 | 示例 | 允许的能力 | 建议工具 |
| ------------ | ------------------ | ---------------------------------------------------- | ------------------------------ |
| S0（涉密） | 核心算法、密钥仓库 | 禁止出境；允许本地索引；仅允许国产且禁止上传敏感文件 | GLM/Qoder（国产，本地索引） |
| S1（内部） | 大多数业务仓库 | 国产为主；海外白名单座席可用；必须审计 | GLM/Qoder + 少量 Cursor/Claude |
| S2（低风险） | 开源/公共/示例 | 可用海外；可更激进试验 Agent | Cursor/Claude/Codex/Gemini |
### 7.2 每个仓库必须配置的“AI 约束文件”
> 目标：让 AI 有项目上下文，同时明确“哪些不能碰”。这些文件的最大价值在于“减少误用与泄漏”，并让新团队快速复制。
**建议统一放在仓库根目录：**
- `AI_RULES.md`：团队规则（允许/禁止上传目录、如何提问、审查要求）。
- `.aiignore`：敏感目录黑名单（`.env`、`secrets/`、`*.pem`、`id_rsa`、`*.p12`、`*.key` 等）。
- `docs/ai/`：放团队 Prompt 模板、示例、常见问题。
**如使用 Claude Code：**
- `CLAUDE.md`：声明项目结构、命令、测试入口、禁止触碰目录、代码风格。
**如使用 Cursor：**
- `.cursorignore`：同 `.aiignore`，并补充构建产物目录（`dist/`、`node_modules/`）。
#### 模板：`.aiignore`（建议公司统一并长期维护）
```gitignore
# Secrets / credentials
.env
.env.*
secrets/
**/secrets/
*.pem
*.key
*.p12
id_rsa
id_ed25519
# Customer / production data
data/
**/data/
*.sql
*.dump
*.bak
*.log
# Build outputs / noise
node_modules/
dist/
build/
coverage/
.turbo/
.next/
```
#### 模板：`AI_RULES.md`（每个仓库都应有）
```md
# AI 使用规则（本仓库）
## 允许
- 允许：补全、代码解释、小范围改动（限定目录）
- 允许：生成测试草稿（仅新增测试文件）
- 允许：生成文档草稿（需人工校对）
## 禁止
- 禁止上传/粘贴：任何密钥、证书、客户数据、未脱敏日志、数据库导出
- 禁止让 AI 修改：鉴权/支付/风控/数据出境相关代码（必须人工主导）
- 禁止在 S0 仓库使用海外模型
## 目录约束
- 允许改动目录：src/
- 禁止改动目录：secrets/、scripts/release/、infra/
## 验证要求
- 所有 AI 改动必须跑：pnpm test
- 有 UI 的必须提供：截图或录屏
```
#### 模板：`.cursorignore`（Cursor 仓库）
```gitignore
# Prefer reusing .aiignore content
.env
.env.*
secrets/
node_modules/
dist/
build/
coverage/
.turbo/
.next/
```
#### 模板：`CLAUDE.md`（Claude Code 仓库）
```md
# Project guidance for Claude Code
## Repo overview
- Tech stack: TypeScript (ESM), pnpm workspace
- Style: 2-space indent, keep changes minimal and focused
## Commands
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint
- Format: pnpm format
## Do / Don't
- DO keep edits scoped; prefer small PRs
- DON'T touch secrets/, .env*, certificates, or customer data
- DON'T change release scripts unless explicitly asked
## Where to make changes
- Prefer editing: packages/**/src
- Tests live in: **/__tests__ or **/test
```
### 7.3 PR 模板必须加的两条（防止 AI 直上生产）
- “本 PR 是否使用 AI 生成/改写代码？若是，说明使用范围与已做的验证（测试/手工验证）。”
- “涉及安全/权限/支付/数据出境变更时，必须标记并请求安全复核。”
### 7.4 为每个项目沉淀 Skill（把 SOP 变成可复制资产）
> 这里的 Skill 指“可复用的提示词/工作流模板”（Codex CLI/内部 Agent 的本地 Skill），不是 Claude Code 的 npm Skill（见 [Skill（技能系统）](./basics/skill)）。
#### 7.4.1 为什么要做
- **把“怎么问 AI”产品化**：把高 ROI 的提问方式固化下来，新人照做就能用。
- **降低合规与误改风险**：把禁止目录、验收清单、默认命令写进 Skill，减少口头传达。
- **减少重复沟通成本**：同类项目的 SOP 复用，跨团队复制更快。
#### 7.4.2 每个项目的“最小 Skill 套件”（建议至少 5 个）
| Skill（示例命名） | 解决什么 | 必填输入（写进 Skill） | 输出/验收标准（写进 Skill） |
| ------------------------ | ----------------------- | ---------------------------- | ---------------------------------- |
| `project-onboarding` | 新人/新模型快速理解项目 | 项目结构、关键目录、风格规范 | 先复述约束；给出常用命令与入口 |
| `project-safe-change` | 小改动不跑偏 | 允许/禁止目录、不可改行为 | 输出变更清单 + 风险点 + 验证命令 |
| `project-bug-triage` | 定位 bug 与最小复现 | 如何跑本地、日志位置、开关 | 先给“复现步骤/假设列表/验证计划” |
| `project-test-writer` | 补测试草稿 | 测试框架、目录约定、运行命令 | 只新增测试文件；覆盖边界；能跑通 |
| `project-release-helper` | 发版/变更日志/版本策略 | 发版命令、分支策略、制品产出 | 产出 checklist；禁止直接改发布脚本 |
> 补充可选：前端项目加 `project-ui-regression`（截图/对照）、后端项目加 `project-api-contract`（接口变更与兼容）、工具链项目加 `project-ci-debug`（CI 失败定位）。
**Monorepo（pnpm workspace/Turbo 等）建议额外加 3 个**
- `monorepo-build-matrix`：把“每个 workspace 怎么 build/test/lint”的矩阵固化，避免只跑了错误的命令。
- `monorepo-deps-guard`：依赖升级/新增依赖的规则（workspace 协议、版本范围、锁文件策略、回滚方式）。
- `monorepo-release-flow`：发版与包发布的分步流程（变更集/版本号/制品校验/回滚点）。
**按项目类型，常见“加餐 Skill”**
| 项目类型 | 建议新增 Skill | 关注点（写进 Skill 的约束/验收） |
| ------------------------------- | -------------------------- | -------------------------------------------------------- |
| UI/小程序/前端应用 | `project-ui-regression` | 必须给截图/录屏；必须跑构建；避免一次性大改 UI |
| 核心库/工具包（packages） | `project-api-compat-guard` | 不破坏公共 API；必须补单测；必要时更新变更日志/Changeset |
| 性能敏感模块 | `project-perf-check` | 需要基准对比；避免引入 O(n²)；给出性能验证方式 |
| e2e/快照密集项目 | `project-snapshot-guard` | 明确何时允许更新快照；更新必须附原因与验证命令 |
| 文档站/示例工程（website/demo） | `project-docs-sync` | 代码片段要可运行；链接不失效；示例与包版本同步 |
| CI/脚本/发布链路 | `project-ci-debug` | 只做最小改动；先复现再修；必须提供回滚点与验证日志 |
**企业级 Skill 库建议分 3 层（避免“每个项目各写一份”）**
- **公司基线（Company Baseline）**：合规红线、验收清单、默认输出格式、PR 声明模板。
- **技术栈预设（Stack Presets）**：Node/Java/Go/小程序等常用命令与目录约定（测试/构建/格式化）。
- **项目覆盖（Project Overrides）**：只写这个项目独有的入口、特殊目录、特殊回滚策略。
#### 7.4.3 Skill 规格模板（统一输入/输出，便于复制与审计）
为避免 Skill 退化成“散落的提示词”，建议所有项目 Skill 统一用同一份规格模板（内容可精简，但字段要齐）：
```md
# Skill:
## Purpose（目的/适用场景）
- 解决什么问题？适用哪些任务？不适用哪些任务？
## Guardrails（红线与边界）
- 禁止目录/文件类型：
- 禁止行为（例如：改鉴权/支付/数据出境；改发布脚本）：
- 允许改动目录：
- 是否允许新增依赖？（默认不允许）
## Commands（项目命令）
- Install:
- Build:
- Test:
- Lint/Format:
## Output Format（输出格式要求）
- 变更点列表（文件级）
- 风险点与兼容性说明
- 验证命令与预期结果
- 回退策略（如何撤销/如何拆小 PR）
## Acceptance Criteria（验收标准）
- 必须通过哪些检查/测试？
- 是否需要截图/日志/性能对比？
- 是否需要更新文档/变更日志/Changeset？
```
#### 7.4.4 治理建议（避免 Skill 变成“散落的提示词”）
- **归属**：公司级通用 Skill 由平台/中台维护；项目 Skill 由项目 TL 维护（但必须走 code review）。
- **存放**：建议用独立仓库集中管理（便于版本化与审计），并按“项目/技术栈”分组。
- **变更管理**：Skill 的更新要附带“验证任务/验证命令”；重大变更先在试点团队灰度。
---
## 8. 日常使用 SOP（把 AI 变成标准流程）
### 8.1 默认路由策略（最重要的一条）
- **默认**：国产/低价模型（用于补全、小改动、查错、写注释、生成测试草稿）。
- **升级条件**：跨文件重构、架构迁移、复杂 bug、性能问题、核心模块 PR 审查 → 申请或切换到高阶模型。
- **禁止条件**：涉密仓库、密钥/证书/个人信息文件、未脱敏的生产日志、客户数据。
#### 8.1.1 任务分级与“用什么档位”（减少争论、降低成本）
| 任务类型 | 推荐默认 | 何时升级到高阶/海外 | 验收要点 |
| ------------------------ | ----------------------- | --------------------------- | ---------------------- |
| Tab 补全/重命名 | 国产/低价 | 一般不需要 | lint/类型检查通过 |
| 小范围修 bug（1-2 文件） | 国产/低价 | 需要跨模块定位/复杂并发问题 | 有最小复现 + 单测覆盖 |
| 重构（跨 3+ 文件） | 国产（核心席位可高阶） | 影响公共 API/核心模块 | 拆小 PR + 每步测试 |
| 单测补齐 | 国产/低价 | 复杂边界/并发/时序 | 断言合理 + 覆盖边界 |
| PR Review | 国产/低价（或工具自带） | 核心模块/安全模块 | 只做建议，人工裁决 |
| 文档/变更日志 | 国产/低价 | 对外发布、合规文本 | 人工校对、避免事实错误 |
#### 8.1.2 AI 输出的“最小验收清单”（团队统一口径）
- 改动范围是否符合约束（目录/文件/接口）？
- 是否引入新依赖或新权限？如果有，是否经过评审？
- 是否提供了可复现的验证方式（命令/截图/日志）？
- 是否通过：类型检查、lint、单测（至少跑到与改动相关的部分）？
- 是否新增/更新了测试覆盖关键分支？
- 是否存在“看似合理但业务语义错误”的风险点（尤其是边界条件）？
### 8.2 六类高 ROI 场景（建议先打穿）
1. **补全与重命名**：提高编码速度，成本低。
2. **代码解释与定位 bug**：让 AI 先给可能原因 + 最小复现路径，再人工确认。
3. **重构与抽象**：先让 AI 提方案（分步、小 PR），再逐步执行。
4. **单测生成**：只生成草稿；必须人工校对断言与边界；必须跑测试。
5. **PR 审查**：AI 先扫出明显问题（命名、空指针、边界、性能），人工做最终裁决。
6. **文档与变更日志**：自动生成草稿，发布前人工校对。
### 8.3 三个必须养成的习惯（否则越用越乱）
- **先约束再生成**：在提问里写清楚“不得修改哪些文件/目录、必须保留哪些行为”。
- **先小步再合并**：要求 AI “拆成 3-5 个小 PR”，每一步都可回滚、可测试。
- **先验证再相信**：AI 输出必须通过单测/类型检查/静态检查；不通过就当作建议而不是结果。
一个最简单的写法是：**目标 + 约束 + 验收**，三段写完再让 AI 开始干活。
示例（小改动）：
- 不推荐：帮我修一下这个 bug。
- 推荐：
```text
目标：修复 xxx 问题（不改变现有行为）。
约束：不改公共 API；不新增依赖；只允许改 src/xxx；不要修改 security/ 与 scripts/。
验收：给出改动点列表 + 风险点；并提供我应该运行的验证命令（pnpm test / pnpm lint）。
```
### 8.4 标准 Prompt 模板（可复制给团队）
下面 3 个模板可以直接复制，按需替换里面的占位符即可。
**模板 A：小改动（低价/国产）**
```text
目标：在不改变行为的前提下，完成【重命名/整理/修复 lint/修复小 bug】。
上下文：仓库是 ，相关代码主要在 。
约束：
- 不改公共接口（除非我明确允许）
- 不新增依赖
- 只允许改动：
- 禁止改动：
输出要求：
1) 改动点列表（按文件）
2) 风险点（可能影响的行为/边界）
3) 我应该运行的验证命令（例如 pnpm test / pnpm lint），以及预期看到什么
```
**模板 B：跨文件重构（高阶/核心座席）**
```text
目标：做一次跨文件重构/抽象（影响范围较大），但要可审查、可回滚。
约束：
- 把改动拆成 3-5 步（每步都能独立合并）
- 不要修改快照/锁文件（除非我明确允许）
- 禁止触碰 security/、scripts/release/ 等高风险目录
- 必须保持向后兼容（或明确写出破坏点并给迁移方案）
输出要求：
1) 先给分步计划：每步改哪些文件、为什么这么拆
2) 每步的验收：要跑哪些测试/命令、预期结果
3) 风险点：哪一步最容易出错、怎么回滚
```
**模板 C：单测生成**
```text
目标：为 补齐关键路径的单元测试/集成测试。
约束：
- 只允许新增测试文件（不要改业务逻辑）
- 覆盖边界：null/undefined、空数组/空字符串、异常分支、权限/鉴权（如有）
- 如果你需要 mock，请说明 mock 的理由与范围（避免过度 mock）
输出要求：
1) 测试用例清单（用一句话说明每个 case 覆盖什么）
2) 关键断言的理由（为什么这样断言）
3) 我应该运行的测试命令，以及预期看到什么
```
---
## 9. 网络、账号、合规（公司落地必须过的三关）
### 9.1 海外模型的网络打通（必做）
**核心原则：同一套代理策略覆盖 IDE + CLI + 浏览器登录。**
常见失败模式是：浏览器能登录、IDE 插件不能用、CLI 走直连被阻断，导致开发者反复重试、延迟暴涨、成本放大。
#### 9.1.1 代理部署建议（企业做法）
- 小规模（<20 人）：可先用单一出口，但必须有备用节点与切换文档。
- 中大规模（20+ 人）：建议由平台/IT 提供“统一代理服务”，至少具备：
- 节点健康检查与自动切换
- 按用户/团队限速（防止单人把带宽打满）
- 访问日志（用于排障与合规审计，注意脱敏）
#### 9.1.2 CLI 代理环境变量（必须统一）
macOS/Linux（`~/.zshrc` / `~/.bashrc`）示例：
```bash
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7890"
# 内网域名与本机地址不要走代理（按公司实际补充）
export NO_PROXY="localhost,127.0.0.1,.corp.internal,10.0.0.0/8,192.168.0.0/16"
```
Windows PowerShell 示例：
```powershell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,.corp.internal"
```
#### 9.1.3 需要放行/可达的常见域名（按所选产品取舍）
- Cursor：`cursor.com`、`*.cursor.com`
- Claude/Anthropic：`claude.ai`、`claude.com`、`*.anthropic.com`
- OpenAI/ChatGPT：`openai.com`、`chatgpt.com`（部分地区可能 Cloudflare 风控更严）
- Google：`cloud.google.com`、`*.googleapis.com`、`*.gstatic.com`
建议做法：平台侧维护“域名白名单”，并在网络策略变更时同步更新。
#### 9.1.4 健康检查与排障（让开发者可自助）
- DNS：确认域名能解析（公司内网 DNS 不要劫持这些域名）。
- TLS：代理如果做了证书替换，需要明确安装企业根证书的流程（否则 IDE/CLI 会报证书错误）。
- 连通性：用 `curl -I https://cursor.com/pricing` 这类轻量请求做探测。
- 体验指标：至少记录“平均延迟/95 分位延迟/失败率”，并能定位到是“网络问题”还是“供应商限流”。
快速自检（给开发者的 1 分钟版本）：
```bash
# 1) DNS 能解析吗？
nslookup cursor.com
# 2) 走代理能连上吗？（看 HTTP 状态码即可）
curl -I https://cursor.com/pricing
# 3) 如果 CLI 总失败，先检查环境变量有没有被覆盖
env | grep -E 'HTTP_PROXY|HTTPS_PROXY|ALL_PROXY|NO_PROXY'
```
#### 9.1.5 故障时降级策略（必须写清楚）
- 代理异常：切换备用出口；在切换完成前仅允许补全，不允许 Agent 执行命令。
- 海外额度耗尽：降级到国产或低价模型，并冻结高阶座席的使用（避免“越急越烧钱”）。
- 供应商不可用：切换到另一家可用的方案（例如从 Cursor 临时切回 GLM/Qoder）。
### 9.2 账号与权限治理（避免“离职不回收”）
#### 9.2.1 基本要求（能做就不要“人工管理账号”）
- **优先团队/企业版**：至少要有成员管理与统一账单；最好有 SSO/审计日志。
- **禁止共享账号**：共享账号无法审计，也无法在离职时回收风险。
- **MFA**：要求开发者开启 MFA（尤其是拥有高阶座席/管理权限的人）。
#### 9.2.2 权限分层与申请流程（把“谁能用高阶”制度化）
- L1 普通开发：默认基础档位（国产 Pro / Cursor Pro）。
- L2 核心开发：按项目负责人提名或按指标（比如核心模块 ownership）授权。
- L3 审查/架构：拥有跨仓库权限，但必须接受更严格的审计与使用规范。
- 申请升级必须包含：仓库名称、使用场景、预计周期、验证方式、预算来源。
#### 9.2.3 离职/转岗回收（必须自动化）
- 与 IT/HR Offboarding 流程绑定：账号停用、座席回收、API/插件 token 失效（如存在）。
- 每月一次抽查：随机抽取 5-10 个账号核对在职状态与权限是否过大。
### 9.3 合规红线（建议写进制度）
#### 9.3.1 明确“什么算敏感”（给可执行的定义）
- 凭据类：密钥、证书、token、私钥、公钥、CI 密钥、签名文件。
- 数据类：客户数据、订单/支付信息、个人信息、生产数据库导出、未脱敏日志。
- 安全类：漏洞细节、攻防脚本、内部安全策略、未公开的架构与域名资产。
#### 9.3.2 红线策略（建议写成强制规则）
- **禁止上传**：以上敏感内容一律禁止粘贴/上传到任何外部模型。
- **涉密仓库禁出境**：S0 仓库默认禁止海外模型；如确需使用，必须先脱敏并走审批。
- **高风险模块双人复核**：鉴权/支付/风控/数据出境相关改动，AI 只能“建议”，最终必须双人 code review。
- **日志留痕**：至少保留“谁在什么仓库使用了什么能力”的记录；日志本身要脱敏且控制访问权限。
---
## 10. 方案落地要点（按产品拆解：怎么用到项目里）
> 这里强调“落地动作”，而不是产品宣传。每个方案都按：管理员准备 → 成员使用 → 仓库接入 → 治理与常见坑 来写。
### 10.1 Cursor（海外，体验优先，适合统一 IDE）
**适用**
- 希望统一 IDE/工作台，并把“补全 + Agent”作为主工作流。
- 海外网络、账号与采购链路已闭环，且能提供稳定代理与故障降级。
**不适用**
- 无法提供稳定海外网络（延迟高/失败率高）或无法在组织层面治理账号与账单。
- 团队强烈不愿切换 IDE（迁移成本高于收益）。
#### 管理员准备（公司/团队层）
1. 确认代理与白名单域名已就绪（见 9.1）。
2. 选择座席策略：
- 普通开发：`Pro`
- 核心开发/架构：`Pro+`（少量）
- 需要 SSO/审计：`Business`
- 极重度专项：`Ultra`（极少量）
3. 如果上 `Business`：优先完成 SSO 与成员回收流程，避免“账号散落”。
4. 设定团队规范：哪些仓库允许开 Agent、哪些仓库只允许补全。
#### 成员上手（个人层）
1. 安装 Cursor。
2. 在系统层配置代理，确保 Cursor、浏览器登录、终端一致走代理。
3. 先把日常习惯固化：
- 80% 用 Tab 补全 + 小改动
- 20% 才用 Agent 做跨文件重构/排障
4. 遇到“答非所问”，优先补充约束：不改行为、不改公共接口、必须通过测试。
#### 仓库接入（项目层）
- 必备：`AI_RULES.md` + `.cursorignore`（参考 7.2 模板）。
- 推荐：在 `AI_RULES.md` 写清楚“本仓库验证命令”（例如 `pnpm test`、`pnpm lint`）。
- 大仓库建议：先在子目录（模块）试点索引，不要一次性喂全仓库。
#### 治理与常见坑
- 坑 1：代理抖动导致 Agent 反复失败重试 → 成本增加。解决：故障时降级为“只补全”。
- 坑 2：没有忽略规则，索引了产物目录 → 回答质量下降、耗时变长。解决：维护 `.cursorignore`。
- 坑 3：重构一次性改太多 → PR 无法审查。解决：强制要求拆小 PR。
### 10.2 Claude Code（海外，CLI/Agent 强，适合重构与排障）
**适用**
- 团队更偏 CLI 工作流，或需要更强的 Agent 执行能力（读写多文件、跑命令、分步迁移）。
- 已经有相对标准的工程命令与仓库规范（安装/构建/测试/格式化），适合写进 `CLAUDE.md` 固化。
**不适用**
- 项目命令与工程规范不稳定（今天能跑、明天跑不了），或无法在仓库层面明确“允许/禁止目录”。
- 对执行命令与写文件权限无法做组织级边界约束与审计。
#### 管理员准备（公司/团队层）
1. 统一 Node 版本（建议 Node >= 18）与 npm 代理策略（避免装不上 CLI）。
2. 以团队为单位开通座席（`Pro`/`Teams`），并明确哪些成员有权限在 S1/S2 仓库使用。
3. 建立 `CLAUDE.md` 模板库：不同技术栈（Node/Java/Go）各一份，复制到仓库即可用。
#### 成员上手（个人层）
1. 安装 CLI（示例）：`npm i -g @anthropic-ai/claude-code`。
2. 登录：按官方流程授权；注意不要用个人账号绑定公司付费座席。
3. 使用方式建议：
- 先让 Claude “写计划”，再让它“按步骤执行”
- 对每一步要求输出：改动点 + 风险点 + 验证命令
#### 仓库接入（项目层）
- 必备：`CLAUDE.md` + `AI_RULES.md` + `.aiignore`。
- `CLAUDE.md` 要明确：
- 如何跑测试/构建/格式化
- 允许改动目录与禁止目录
- 代码风格与约束（例如 2 空格、ESM、禁新增依赖）
#### 治理与常见坑
- 坑 1：Agent 默认“能写文件能跑命令”，权限边界不清。解决：`CLAUDE.md` 写清楚允许范围。
- 坑 2：把“执行命令”当作最终答案。解决：命令输出必须进入 PR 说明与人工复核。
- 坑 3：复杂迁移不拆分。解决：要求先输出 3-5 步迁移计划，并逐步合并。
### 10.3 Codex / ChatGPT Team（海外，团队通用，偏“知识+草稿”）
**适用**
- 跨团队通用场景：代码解释、技术调研、设计草稿、评审检查点、测试用例清单等“产出草稿/清单”的任务。
- 希望用 Team/企业版统一成员与账单，并把“深度改代码”留在 IDE/CLI 工具里完成。
**不适用**
- 把它当作“自动落地改代码”的主工具（缺少仓库上下文与工程约束时，风险高且质量不可控）。
#### 管理员准备（公司/团队层）
1. 优先 Team：统一成员、权限、账单，避免个人报销与账号散落。
2. 输出团队 Prompt 规范：
- 必须写约束（目录/接口/依赖/测试）
- 必须写验收方式（测试命令/截图/日志）
3. 为“核心模块”建立更严格的规则：AI 只能提供建议，不直接落地改动。
#### 成员上手（个人层）
- 典型用法：
- 解释陌生代码、做技术调研、写设计草稿
- 生成 PR Review 检查点列表
- 生成测试用例清单（不是直接改业务代码）
#### 仓库接入（项目层）
- 依然需要仓库侧规则：`AI_RULES.md` + `.aiignore`。
- 核心模块 PR 要求：AI 输出必须包含“验证命令”，并在 PR 描述中说明已执行。
#### 治理与常见坑
- 坑 1：缺少仓库上下文导致“看起来对、实际错”。解决：让模型先复述项目约束与现有实现。
- 坑 2：生成大量代码但无测试。解决：把“必须补测试草稿”写进 SOP。
### 10.4 Gemini Coding Plan（海外，偏 PR Review 与 GCP 生态）
**适用**
- PR Review 辅助与质量扫描是核心诉求，且团队本身在 GCP 生态中工作较多。
- 账号与账单体系可以纳入公司治理（而不是个人零散账号）。
**不适用**
- 团队没有稳定的 Google 账号与账单体系，或无法满足组织级成员管理与审计要求。
#### 管理员准备（公司/团队层）
1. 确认 Google 账号与 GCP 账单体系可用（否则推进会卡住）。
2. 明确 PR Review 权责：AI 是辅助审查，最终由代码所有者裁决并承担责任。
3. 选择座席：Standard 覆盖多数人；Enterprise 给审查角色或核心项目。
#### 成员上手（个人层）
- 建议把 Gemini 用在两类任务：
- PR Review：提示潜在 bug、边界条件、性能问题
- 与 GCP 相关的代码/配置：更容易给出生态内建议
#### 仓库接入（项目层）
- PR 模板明确：AI Review 只是建议，必须人工确认与验证。
- 对大型 PR：限制 diff 大小、先拆 PR 再用 AI 审查。
### 10.5 GLM（国产主力，适合全员普及）
**适用**
- 合规与报销友好，希望快速全员覆盖，把补全/小改动/补测先规模化落地。
- 希望把“默认路由”稳定在国产/低价侧，通过座席分层控制成本波动。
**不适用**
- 强依赖海外生态（账号/插件/模型）且无法接受国产作为默认兜底的组织（这类通常要先解决 Gate 条件）。
#### 管理员准备（公司/团队层）
1. 以 GLM Pro 作为默认座席（覆盖 70-85% 人群），Max 作为核心席位。
2. 把“5 小时刷新”写进团队排班：批量重构/补测任务集中在刷新后执行。
3. 建立用量看板：每日/每周触顶风险提示（尤其是 Max 席位）。
#### 成员上手（个人层）
- 优先打穿三件事：
1. Tab 补全
2. 小范围修 bug（要求先给复现与验证命令）
3. 单测草稿（要求覆盖边界与异常）
#### 仓库接入（项目层）
- 必备：`AI_RULES.md` + `.aiignore`。
- S0 仓库：只允许国产，并强制启用敏感目录黑名单。
#### 治理与常见坑
- 坑 1：刷新周期误解导致“额度突然用完”。解决：把批量任务集中到刷新后窗口。
- 坑 2：把 AI 当成“自动提交器”。解决：统一验收清单（8.1.2）与 PR 模板。
### 10.6 Qoder（国产/混合，治理友好）
**适用**
- 既要国产可用性/合规友好，又希望在少数仓库/少数人上引入海外增强，并要求审计与团队治理。
- 希望把“混合路由”做成可控的白名单能力（默认关、按需开、可追溯）。
**不适用**
- 混合路由无法在组织层面做审批与审计（否则风险会集中爆发在“默认开”上）。
#### 管理员准备（公司/团队层）
1. 普通席位 `Pro`，重度/混合需求 `Pro+`，需要审计与成员管理用 `Teams`。
2. 建立混合路由白名单：哪些仓库/分支允许海外模型，谁可以开。
3. 配额策略：团队配额 + 个人上限，触顶自动降级到国产模型。
#### 成员上手（个人层）
- 建议默认国产路由，只有在“确实需要高质量推理/迁移方案”时才申请混合。
- 大改动先输出分步计划，再开始改代码。
#### 仓库接入（项目层）
- 必备：`AI_RULES.md` + `.aiignore`；团队版建议开启审计与操作留痕。
- 对涉密仓库：强制关闭海外路由。
#### 治理与常见坑
- 坑 1：混合路由“默认开”会直接引入合规风险。解决：默认关、审批开。
- 坑 2：缺少审计导致问题难追溯。解决：团队版启用审计并定期抽查。
---
## 11. 执行清单（公司落地逐项勾）
### 11.1 决策与采购
- [ ] 完成 Gate A/B：合规出境范围书面结论 + 海外网络与采购闭环确认。
- [ ] 明确默认主力（国产/海外）与增强座席策略。
- [ ] 选定座席分层与数量（L1/L2/L3/L4）。
- [ ] 账单中心与预算上限、告警责任人。
- [ ] 供应商可用性评估（区域、风控、支付）。
- [ ] 输出选型评审交付物（见 2.4）：主力+降级、约束条件、落地计划、风险与回滚。
### 11.2 网络与合规
- [ ] 海外代理可用（IDE/CLI 同策略），有备用出口。
- [ ] 代理健康检查与故障降级策略可执行（见 9.1.4/9.1.5）。
- [ ] 仓库分级（S0/S1/S2）完成，并绑定策略。
- [ ] 敏感目录黑名单（`.env`/`secrets/`/证书/客户数据）固化到模板。
- [ ] 审计与留痕（谁用、用在哪个仓库、做了什么）可追溯。
### 11.3 项目接入
- [ ] 每个仓库落地 `AI_RULES.md` / `.aiignore` /（可选）`CLAUDE.md` / `.cursorignore`。
- [ ] 关键工作流沉淀为项目 Skill（见 7.4），并用 1-2 个真实任务验证可用。
- [ ] PR 模板增加 AI 使用声明与验证说明。
- [ ] 将“必须跑测试/必须 code review”固化到工程规范。
### 11.4 运营与复盘
- [ ] 试点指标看板（效率/质量/体验/成本）建立。
- [ ] 试点“一页结论”与可复制资产沉淀（见 6.3）：模板、SOP、培训、降级预案、账单样例。
- [ ] 月度复盘机制：座席调整、路由调整、代理优化、合规抽查。
- [ ] 回滚预案演练（代理故障/额度耗尽/供应商不可用）。
---
## AI 编码助手五大方案选型指南
# AI 编程五大方案选型指南
## 概述
本文档将深入对比当前最主流的五种 AI 编程方案：**AWS Kiro**、**GitHub Copilot**、**Cursor IDE**、**Claude Code** 和 **OpenAI Codex**，帮助开发者根据自身需求选择最适合的工具。
| 方案 | 国内可用性 | 网络要求 |
| ---------------- | ---------- | ------------------- |
| **AWS Kiro** | ✅ 可直接用 | 无需代理 |
| **GitHub Copilot** | ✅ 可直接用 | 无需代理 |
| **Cursor IDE** | ❌ | 需要美国节点/代理 |
| **Claude Code** | ❌ | 需要美国节点/代理 |
| **OpenAI Codex** | ❌ | 需要美国节点/代理 |
---
## 国内直接可用方案
> **说明**：以下方案在中国大陆地区可直接访问，无需复杂的网络配置。
### 方案一：AWS Kiro ✅ 国内直接可用
### 选择理由
**Kiro** 是 Amazon AWS 推出的 AI 原生 IDE，采用独特的 Spec-Driven（规格驱动）开发模式：
- **国内直接可用**：通过 AWS 中国区域提供服务，**中国大陆用户无需代理即可访问**
- **AWS 背景加持**：由 Amazon 官方支持，依托 AWS 基础设施，企业级可靠性
- **Spec-Driven 开发**：独特的"先计划后构建"模式，将需求转化为可执行的规格说明
- **Claude 4.5 全系列**：支持 **Claude Opus 4.5**、Sonnet 4.5、Haiku 4.5 全系列模型
- **智能模型选择**：Auto 模式可根据任务复杂度自动选择最合适的模型
- **VS Code 架构**：基于 VS Code fork，界面熟悉，上手容易
- **Agent Hooks**：支持自动化触发器，工作流可定制
- **新用户福利**：注册后第一个月赠送 500 积分用于体验
### ⚠️ 中国用户注意事项
> **重要提示**：虽然 Kiro 目前在中国可通过 AWS 中国区域访问，但需要注意：
>
> 1. **政策风险**：各类产品的迭代与政策可能随时变化，不能保证一直可以在国内使用
> 2. **Anthropic 限制**：Claude 官方已于 2025 年 9 月更新政策，禁止中国控制的实体使用 Claude 服务
> 3. **AWS Bedrock 渠道**：Kiro 通过 AWS Bedrock 提供 Claude 模型访问，目前 AWS 中国区域仍可正常使用
> 4. **变化无常**：如遇访问问题，建议关注 AWS 中国官方公告或考虑替代方案
### 个人订阅方案
| 套餐 | 月费 | Credits | 超量使用 |
| --------- | ------- | --------------------------------- | ------------------------ |
| **试用** | - | 50 credits/月 + 首月赠送 500 | 不可超量，用完需等待下月 |
| **Pro** | $20/月 | 1,000 credits/月 | $0.04/credit |
| **Pro+** | $40/月 | 2,000-3,000 credits/月 | $0.04/credit |
| **Power** | $200/月 | 10,000 credits/月 | $0.04/credit |
**使用说明**：
- **试用额度**：每月 50 credits，新用户第一个月额外赠送 500 credits
- **刷新周期**：每月按订阅日期重置
- **超额处理**：付费套餐（Pro/Pro+/Power）可超量使用，按 $0.04/credit 计费
- **升级保留**：30 天内升级可保留未使用的试用额度
### 团队订阅方案
| 套餐 | 价格 | 最低人数 | 核心功能 |
| -------------- | -------- | --------- | ------------------------------------------------------------------------- |
| **Enterprise** | 定制定价 | **20 人** | 所有个人功能 + SSO/SCIM + 集中许可证管理 + 组织策略 + AWS 集成 + 专属支持 |
### 技术特点
| 特性 | 说明 |
| --------------- | ------------------------------------------------------ |
| **Spec-Driven** | 将想法转化为"活的可执行规格"，自动应用软件工程最佳实践 |
| **主要模型** | **Claude Opus 4.5**、Sonnet 4.5、Haiku 4.5 |
| **架构基础** | 基于 VS Code |
| **扩展协议** | 支持 MCP (Model Context Protocol) |
#### Claude 4.5 模型 Credit 倍率
| 模型 | Credit 倍率 | 适用场景 |
| ---------------- | ----------- | -------------------------------- |
| **Haiku 4.5** | 0.4× | 快速、低成本任务 |
| **Sonnet 4.5** | 1.3× | 复杂代理和编码（推荐大多数场景） |
| **Opus 4.5** | 2.2× | 最强推理能力，最具挑战性的任务 |
### 参考链接
- [Kiro 官方网站](https://kiro.dev/)
- [Kiro 官方定价页面](https://kiro.dev/pricing/)
- [AWS 中国 Kiro CDK 教程](https://aws.amazon.com/cn/blogs/china/blog-03-kiro-ai-cdk-development/)
---
### 方案二：GitHub Copilot ✅ 可直接用
### 选择理由
**GitHub Copilot** 是由 GitHub 和 OpenAI 联合开发的 AI 编程助手，是目前市场上最早的、用户基数最大的 AI 编码工具：
- **市场先驱**：2021年首次发布，用户数超过 150 万，占 AI 编程工具市场主导地位
- **深度集成**：与 GitHub 生态深度整合，支持 VS Code、Visual Studio、JetBrains 全系列 IDE
- **多模型支持**：支持 **Claude 4.5**（Sonnet/Opus/Haiku）、**GPT 5.2**、**Gemini Pro 3** 等多种模型
- **企业级支持**：GitHub 背书，企业版提供完善的权限管理和安全合规
- **Premium 请求系统**：2025年引入新的 premium requests 计费模式
- **⚠️ 国内限制**：中国大陆地区访问需要稳定的网络环境
### 个人订阅方案（2025-2026 最新）
| 套餐 | 月费 | 年费 | 核心额度 |
| ----------- | ---------- | --------------- | ------------------------------------------------------------ |
| **Free** | 免费 | 免费 | 基础代码补全，有限的 Copilot Chat 功能 |
| **Pro** | $10/月 | $100/年 (省17%) | 完整代码补全 + Copilot Chat + CLI + 多文件编辑 |
| **Pro+** | $39/月 | - | 全模型访问 + **1,500 次 premium 请求/月** + 超量 $0.04/次 |
**使用说明**：
- **Free 限制**：基础代码补全，有限的 Chat 功能
- **Pro 功能**：完整 Copilot 功能，包括代码补全、Chat、CLI
- **Pro+ 额度**：每月 1,500 次 premium 请求（使用更强大的模型）
- **超量计费**：Pro+ 超出部分按 **$0.04/次** 计费
- **刷新周期**：每月按订阅日期重置
### 支持的 AI 模型（2026）
| 模型分类 | 具体模型 | 说明 |
| -------------- | ------------------------------------- | ------------------------ |
| **OpenAI** | **GPT 5.2**、o3、o4-mini | OpenAI 最新推理模型 |
| **Anthropic** | **Claude 4.5**（Sonnet/Opus/Haiku） | Claude 最新高性能模型 |
| **Google** | **Gemini Pro 3** | Google 最新推理模型 |
> **注意**：模型可用性会根据 GitHub 和各 AI 提供商的合作协议动态调整。部分高级模型需要 Pro+ 订阅。
### 团队订阅方案
| 套餐 | 价格 | 最低人数 | 核心功能 |
| -------------- | ------------- | ---------- | ----------------------------------------------------------------------------- |
| **Business** | $19/人/月 | - | Pro 功能 + 管理控制台 + 组织策略 + 数据不训练 + 使用统计 |
| **Enterprise** | $39/人/月 | - | Business 全部 + SSO 单点登录 + 审计日志 + 私有化部署 + 专属支持 + 合规认证 |
**Business/Enterprise 额外功能**：
- **管理控制台**：集中管理用户许可证和策略
- **单点登录 (SSO)**：支持 SAML 2.0 和 SCIM
- **数据隐私**：承诺不使用企业代码训练模型
- **使用统计**：详细的使用报告和分析
- **合规认证**：SOC 2、ISO 27001 等认证
### 技术特点
| 特性 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| **支持的 IDE** | VS Code、Visual Studio、JetBrains 全系列、Vim/Neovim |
| **Copilot Chat** | 交互式对话编程，支持代码库级别的上下文理解 |
| **Copilot CLI** | 命令行工具，可直接在终端使用 |
| **Copilot Workspace** | AI 驱动的开发环境，支持从需求到代码的完整工作流 |
### 参考链接
- [GitHub Copilot 官方定价页面](https://github.com/features/copilot/plans)
- [GitHub Copilot 官方文档](https://docs.github.com/en/copilot/get-started/plans)
- [GitHub Copilot 支持的 AI 模型](https://docs.github.com/zh/copilot/reference/ai-models/supported-models)
- [GitHub Copilot 请求计费说明](https://docs.github.com/en/copilot/concepts/billing/copilot-requests)
- [GitHub Copilot Pricing Guide 2026](https://userjot.com/blog/github-copilot-pricing-guide-2025)
---
## 需要美国节点的方案
> **说明**：以下方案在中国大陆地区**无法直接访问**，需要美国节点或海外代理。
### 方案三：Cursor IDE ❌ 需要美国节点
### 选择理由
**Cursor** 是目前市场上最成熟的 AI 原生 IDE，基于 VS Code fork 而来，深度集成 AI 能力：
- **AI 原生体验**：专为 AI 编程设计，而非插件形式，体验更流畅
- **预测式补全**：可预测 5-10 行代码，补全质量业界领先
- **跨文件重构**：支持项目级别的代码理解和重构
- **Agent 模式**：Background Agent 可在后台自动完成复杂任务
- **生态完善**：v1.0/v1.1 新增 BugBot 审查、Memory 能力
- **市场地位**：估值 99 亿美元，年化收入 5 亿美元
- **⚠️ 国内限制**：中国大陆地区访问需要稳定的网络环境
### 个人订阅方案
| 套餐 | 月费 (月付) | 月费 (年付) | 核心额度 |
| --------- | ----------- | --------------- | ---------------------------------------------------- |
| **Hobby** | 免费 | 免费 | 基础功能，有限 AI 模型访问 |
| **Pro** | $20/月 | ~$16/月 (省20%) | 约 500 次 fast premium requests/月，包含 $20 API额度 |
| **Pro+** | $60/月 | - | 3x 所有模型使用额度，包含 $70 API额度 |
| **Ultra** | $200/月 | - | 20x 所有模型使用额度，包含 $400 API额度 |
**使用说明**：
- **Fast Requests**：Pro 计划每月约 500 次快速请求
- **Slow Requests**：超出后自动切换到慢速请求，无次数限制
- **刷新周期**：每月按订阅日期重置（如 15 日订阅则每月 15 日重置）
- **部分恢复**：用尽额度后 5-24 小时内可能会恢复少量额度
### 团队订阅方案
| 套餐 | 价格 | 核心功能 |
| -------------- | --------- | ---------------------------------------------------------------------------- |
| **Teams** | $40/人/月 | 所有 Pro 功能 + SSO 单点登录 + 管理控制台 + 使用分析 + 组织级隐私模式 + RBAC |
| **Enterprise** | 定制定价 | Teams 全部功能 + SCIM 用户预配 + 数据不用于训练 + 专属支持 + 更多企业功能 |
**Teams 最低要求**：无明确最低人数要求
### 参考链接
- [Cursor 官方定价页面](https://cursor.com/pricing)
- [Cursor Teams 定价详情](https://cursor.com/docs/account/teams/pricing)
- [Cursor 企业版介绍](https://cursor.com/enterprise)
---
### 方案四：Claude Code ❌ 需要美国节点
### 选择理由
**Claude Code** 是 Anthropic 推出的 CLI 工具，可与现有开发环境无缝集成：
- **顶尖代码能力**：Claude Opus 4.5 在编程基准测试中表现卓越
- **CLI 工具**：不改变现有 IDE 习惯，通过命令行与 AI 交互
- **深度代码理解**：可处理大型代码库，支持跨文件重构和代码审查
- **MCP 协议支持**：可扩展连接各种工具和数据源
- **成本效益**：相对较低的价格获得高质量编程辅助
- **⚠️ 国内限制**：Anthropic 已禁止中国用户使用
### 个人订阅方案
| 套餐 | 月费 (月付) | 月费 (年付) | 核心额度 |
| ----------- | ----------- | ----------------- | ---------------------------------------------------------- |
| **Pro** | $20/月 | $17/月 (年付$200) | 约 5x 免费用量，优先队列 |
| **Max 5x** | $100/月 | - | 5x Pro 额度，预计 140-280 小时 Sonnet 4/周 |
| **Max 20x** | $200/月 | - | 20x Pro 额度，约 900 条消息/5小时 或 200-800 prompts/5小时 |
**使用说明**：
- **刷新周期**：5 小时滚动窗口
- **周限额**：自 2024 年 8 月 28 日起引入周限额
- **超额处理**：达到限制后可选择升级或等待刷新
### 团队订阅方案
| 套餐 | 价格 | 最低人数 | 核心功能 |
| ------------------- | ------------------------------------ | -------- | ----------------------------------------------------------- |
| **Team (Standard)** | $30/人/月 (月付)$25/人/月 (年付) | **5 人** | Sonnet/Opus 高额度 + 团队共享池 + 管理后台 + 成员管理 + SSO |
| **Team (Premium)** | $150/人/月 | 5 人 | Standard 全部 + Premium 优先队列 + 更高配额 + 审计日志 |
| **Enterprise** | 联系销售 | - | 企业级功能 + DPA/BAA 合同 + 专属支持 + 定制部署 |
### 参考链接
- [Claude 官方定价页面](https://claude.com/pricing)
- [Claude Code 使用指南](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
---
### 方案五：OpenAI Codex (ChatGPT) ❌ 需要美国节点
### 选择理由
**OpenAI Codex** 已整合到 ChatGPT 订阅中，提供业界领先的代码生成能力：
- **GPT 5.2 模型**：最新一代模型，代码生成能力业界领先
- **o3/o4-mini 推理模型**：专为复杂编程和推理优化
- **深度集成**：ChatGPT 网页版、CLI、API 全覆盖
- **Code Interpreter**：可执行代码进行数据分析
- **生态成熟**：插件系统最完善，第三方工具支持最广泛
- **多模态能力**：支持图像、音频等多种输入方式
> **注意**：原独立 Codex API 已整合到 GPT-5 模型家族中，不再单独提供
### 个人订阅方案
| 套餐 | 月费 | 核心额度 |
| -------- | ------- | ------------------------------------------------------------------------------------------- |
| **Free** | 免费 | GPT 5.2: 约 10 条/5小时 |
| **Plus** | $20/月 | GPT 5.2: 160 条/3小时o3-mini: 150 条/天o3: 100 条/周o4-mini: 300 条/天 |
| **Pro** | $200/月 | 声称"无限消息"+ GPT 5.2 Pro更快图像生成 + 最大深度研究额度实际仍可能遇到 5 小时限制 |
**使用说明**：
- **Free 刷新周期**：5 小时滚动窗口
- **Plus 刷新周期**：3 小时滚动窗口（GPT 5.2），部分模型按天/周计算
- **Pro 说明**：官方宣传"无限"，但用户报告仍可能遇到限制
### 团队订阅方案
| 套餐 | 价格 | 最低人数 | 核心功能 |
| -------------- | ------------------------------------ | ----------------- | --------------------------------------------- |
| **Team** | $30/人/月 (月付)$25/人/月 (年付) | **2 人** | GPT 5.2 访问 + 协作工具 + 团队管理 + 数据不训练 |
| **Business** | $25-30/人/月 | - | Team 全部 + 管理控制台 + SSO + 数据分析 |
| **Enterprise** | 联系销售 | 通常 100-150 人起 | 企业级合规 + DPA/BAA + 私有端点 + 专属支持 |
**Team/Business 额外功能**：
- 管理控制台和用户管理
- 单点登录 (SSO)
- 数据不用于训练保证
- 团队协作空间
- 使用分析和报告
### API 定价（按量计费）
如需通过 API 使用 Codex 能力：
| 模型 | 输入 Token | 缓存输入 | 输出 Token |
| ---------------------- | ----------------- | ------------------ | ------------------ |
| **GPT 5.2-mini** | $0.25 / 1M tokens | $0.025 / 1M tokens | $1.00 / 1M tokens |
| **GPT 5.2** | $1.75 / 1M tokens | $0.175 / 1M tokens | $14.00 / 1M tokens |
**新用户福利**：新 API 账户可获得 $5 免费额度（约 400 万 GPT 5.2 tokens）
### 参考链接
- [ChatGPT 官方定价页面](https://chatgpt.com/pricing)
- [ChatGPT Pro 方案](https://chatgpt.com/plans/pro/)
- [OpenAI API 定价](https://openai.com/api/pricing/)
- [OpenAI 定价说明](https://platform.openai.com/docs/pricing)
- [ChatGPT 使用限制说明](https://northflank.com/blog/chatgpt-usage-limits-free-plus-enterprise)
- [OpenAI Codex 定价指南](https://userjot.com/blog/openai-codex-pricing)
- [GPT-5.2 定价说明](https://www.glbgpt.com/hub/chatgpt-5-2-price-guide-2025/)
---
## 五大方案对比总结
### 价格对比（个人版）
| 方案 | 入门价格 | 中级价格 | 高级价格 | 刷新周期 |
| ------------------ | ------------------------------ | ----------------- | ------------------ | -------- |
| **AWS Kiro** | 50 积分/月 + 首月赠送 500 | $20/月 (Pro) | $200/月 (Power) | 月度重置 |
| **GitHub Copilot** | $10/月 (Pro) | $39/月 (Pro+) | - | 月度重置 |
| **Cursor** | $20/月 (Pro) | $60/月 (Pro+) | $200/月 (Ultra) | 月度重置 |
| **Claude Code** | $20/月 (Pro) | $100/月 (Max 5x) | $200/月 (Max 20x) | 5小时/周 |
| **OpenAI Codex** | $20/月 (Plus) | - | $200/月 (Pro) | 3-5小时 |
### 价格对比（团队版）
| 方案 | 团队价格 | 最低人数 | 企业版 |
| ------------------ | -------------- | ---------- | ------------------ |
| **AWS Kiro** | - | **20 人** | 定制 |
| **GitHub Copilot** | $19/人/月 | - | $39/人/月 |
| **Cursor** | $40/人/月 | 无明确要求 | 定制 |
| **Claude** | $25-30/人/月 | **5 人** | 定制 |
| **OpenAI** | $25-30/人/月 | **2 人** | 定制 (通常100人起) |
### 刷新周期对比
| 方案 | 个人版刷新 | 团队版刷新 | 特点 |
| ------------------ | ---------- | ---------- | ------------------------ |
| **AWS Kiro** | 每月重置 | 每月重置 | 支持$0.04/credit超量计费 |
| **GitHub Copilot** | 每月重置 | 每月重置 | Pro+ 超量 $0.04/次 |
| **Cursor** | 每月重置 | 每月重置 | 5-24小时可能部分恢复 |
| **Claude** | 5小时/周 | 5小时/周 | 窗口期最短 |
| **OpenAI** | 3-5小时 | 3-5小时 | Plus 3小时，Free 5小时 |
### 国内可用性对比
| 方案 | 国内直接访问 | 需要美国节点 | 说明 |
| ------------------ | ------------ | ------------ | ------------------------------------- |
| **AWS Kiro** | ✅ | ❌ | 通过 AWS 中国区域可访问，但有政策风险 |
| **GitHub Copilot** | ✅ | ❌ | 可直接访问 |
| **Cursor** | ❌ | ✅ | 需要美国节点或代理 |
| **Claude Code** | ❌ | ✅ | 需要美国节点或代理 |
| **OpenAI Codex** | ❌ | ✅ | 需要美国节点或代理 |
### 选型建议
**选择 AWS Kiro 如果**：
- **位于国内**，希望无需代理即可使用
- 偏好 Spec-Driven（规格驱动）开发模式
- 团队已使用 AWS 生态系统
- 需要企业级可靠性和数据合规
- 可以接受潜在的政策变化风险
**选择 GitHub Copilot 如果**：
- 已习惯使用 VS Code/JetBrains 等 IDE
- 需要最成熟稳定的 AI 编码工具
- 预算有限，$10-39/月的价格更有吸引力
- 团队已深度使用 GitHub 生态
- 需要企业级合规和支持
**选择 Cursor 如果**：
- 希望使用 AI 原生 IDE，不想折腾插件
- 需要预测式代码补全和跨文件重构
- 团队需要统一的 IDE 环境和管理
- 预算 $20-200/月可接受
- 有稳定的海外网络环境
**选择 Claude Code 如果**：
- 已习惯现有 IDE (VS Code/JetBrains)，不想切换
- 需要顶尖的代码理解和审查能力
- 希望通过 CLI 与 AI 交互
- 需要频繁处理大型代码库
- 有稳定的海外网络环境
**选择 OpenAI Codex 如果**：
- 需要 GPT-5.2/o3 等最新推理模型
- 需要多模态能力（图像、音频）
- 需要 Code Interpreter 进行数据分析
- 需要 API 接入自定义应用
- 有稳定的海外网络环境
---
## 附录：Anthropic 公司股东与融资信息
### 公司背景
**Anthropic** 是一家美国人工智能安全公司，由 Dario Amodei 和 Daniela Amodei 于 2021 年创立。公司前身为 OpenAI 的核心成员，后独立发展专注于 AI 安全研究。Anthropic 推出了 Claude 系列 AI 模型，包括 Haiku、Sonnet 和 Opus。
### 融资历程与估值
#### 最新融资（2026 年 1 月）
| 融资轮次 | 金额 | 估值 | 领投方 | 状态 |
| -------- | ------------- | ------------- | ------------- | ------------ |
| **Series G** | **$100 亿** | **$3500 亿** | **GIC**（新加坡主权财富基金） | 洽谈中 |
#### 历史主要融资
| 时间 | 轮次 | 金额 | 估值 | 主要投资方 |
| ---------- | --------- | ------------ | ----------- | ------------------------------------ |
| 2025年9月 | Series F | $130 亿 | $1830 亿 | Lightspeed、Fidelity 等 |
| 2024年 | 多轮 | 累计约 $170+亿 | - | Google、Amazon、Spark Capital 等 |
| 2023年 | - | $40 亿（Amazon投资） | - | Amazon |
| 2023年 | - | $20 亿（Google投资） | - | Google |
**累计融资金额**：至少 **$400 亿**（约 14 轮融资）
### 主要股东与投资方
#### 机构投资者
| 投资方 | 类型 | 投资轮次/金额 |
| ------------------- | ------------------- | -------------------------------- |
| **GIC** | 新加坡主权财富基金 | 领投 Series G（洽谈中） |
| **Lightspeed Venture Partners** | 风险投资 | Series F 领投 |
| **Fidelity Management & Research** | 资产管理 | 多轮投资 |
| **Google (Alphabet)** | 战略投资者 | $20 亿 + 多轮投资 |
| **Amazon** | 战略投资者 | $40 亿投资，云服务合作 |
| **Spark Capital** | 风险投资 | 早期及后续轮次 |
| **Menlo Ventures** | 风险投资 | 早期投资者 |
#### 战略合作
- **Amazon AWS**：Anthropic 选择 AWS 作为主要云服务提供商，Amazon 累计投资 $40 亿
- **Google Cloud**：Google 投资并提供云基础设施支持
### 财务预期
| 指标 | 数据 |
| --------------- | ----------------------------- |
| **2025 年 ARR 预期** | $90 亿 |
| **2026 年收入预期** | $200-260 亿 |
| **增长率** | 3 年期内约 13-28% 增长预期 |
### 上市计划
根据多家媒体报道：
- **IPO 时间窗口**：最早可能在 **2026 年底** 或 2027 年
- **上市地点**：预计在美国公开市场上市
- **当前状态**：已开始筹备上市相关工作
### 参考链接
- [Anthropic 寻求 100 亿美元融资，估值达 3500 亿美元 - The New York Times](https://www.nytimes.com/2026/01/07/technology/anthropic-funding-valuation.html)
- [Anthropic 以 3500 亿美元估值筹集 100 亿美元 - Wall Street Journal](https://www.wsj.com/tech/ai/anthropic-raising-10-billion-at-350-billion-value-62af49f4)
- [Anthropic 瞄准 3500 亿美元估值进行大规模融资 - Yahoo Finance](https://finance.yahoo.com/news/anthropic-eyes-350-billion-valuation-190120429.html)
- [Anthropic 计划以 3500 亿美元估值筹集 100 亿美元 - Seeking Alpha](https://seekingalpha.com/news/4537469-anthropic-plans-to-raise-10b-at-350b-valuation)
- [Anthropic 寻求 100 亿美元融资，估值 3500 亿美元 - SiliconANGLE](https://siliconangle.com/2026/01/07/anthropic-reportedly-seeking-raise-10b-350-billion-valuation/)
- [Anthropic 公司介绍 - Wikipedia](https://en.wikipedia.org/wiki/Anthropic)
- [Anthropic 股权投资指南 - TSG Invest](https://tsginvest.com/anthropic-pbc/)
---
> **最后更新时间**：2026 年 1 月
>
> **注意**：以上价格和额度信息可能随时间变化，请以官方页面为准。如需最新信息，请访问各方案的官方定价页面。Anthropic 融资信息基于公开媒体报道，实际数据以公司官方披露为准。
---
## AI 共有的不足和缺陷
## 数据与知识层面
- 训练数据不可追溯：来源不透明，更新不可再现，难以审计和监管（例：医疗对话数据混入论坛内容，错误建议无法追责）。
- 时效性缺失：回答容易引用过时信息，对实时数据与趋势不敏感（例：被问到最新利率或 CVE 时仍返回去年数据）。
- 事实幻觉：缺少可验证引用，虚构数字、文献和代码依然常见（例：编造论文标题、捏造 npm 包版本或接口字段）。
- 领域不均衡：中文、少数语言、专业术语、方言与长尾格式支持薄弱（例：中医方剂、法律条文引用常错位，粤语/方言指令被误解）。
- 偏见与刻板印象：历史数据里的歧视被放大，跨地区/行业使用易冲突本地法规与文化（例：求职推荐偏向性别刻板印象，触犯当地公平招聘规定）。
- 检索依赖：RAG 质量受索引时效、噪声和稀疏影响，无法一劳永逸解决事实性（例：索引未刷新导致产品文档已改版但回答仍指向旧参数）。
## 模型与算法局限
- 概率当确定性：缺少置信度表达，难以分级处理高风险场景（例：医疗问答把低概率诊断当肯定结论）。
- 长文本脆弱：上下文窗口有限，早期约束易被遗忘，推理链断裂（例：合同审阅漏掉前文免除条款）。
- 多模态裁决不足：图文冲突时缺少稳健的决策逻辑，新攻击面频出（例：图中文字写“禁止吸烟”但模型按图像场景回答“可以吸烟”）。
- 逻辑/数值/物理推理弱：多步因果、数量守恒、空间推理常犯低级错误（例：流水线产能计算时把单位搞混、数量不守恒）。
- 微调与漂移：定向微调易被脏数据污染，旧能力遗忘，新行为难预测（例：加入少量脏数据后把安全回复改成敏感输出）。
- 解释性薄弱：难给出因果链与可追溯证据，审核与合规成本高（例：风控拒绝原因无法溯源到具体特征或规则）。
## 系统与工程稳定性
- 输出波动与延迟：服务抖动、偶发崩溃，难以满足 SLA 与韧性要求（例：高峰期响应从 1s 抖到 20s+）。
- 格式不稳定：结构化输出常偏离协议，需要大量后处理与人工兜底（例：约定 JSON 却混入自然语言或缺字段）。
- 工具/函数调用脆弱：异常返回、超时、限流易让模型陷入死循环或空洞回复（例：重试未设上限导致 API 雪崩）。
- 成本不可控：冗长上下文、重试和插件调用叠加，账单常超预期（例：一次客服对话因多次检索与重试耗费数十倍预估成本）。
- 资源与供应链风险：GPU/TPU 供应紧张或权重合规受限会整体拖垮服务质量（例：突发算力抢占导致延迟飙升）。
- 监控与回溯不足：缺少在线评测、自动报警和可重放数据，问题多依赖用户投诉暴露（例：生产错误格式连续数小时未被发现）。
- 代码执行高风险：AI 生成或运行的脚本若无隔离，可能修改全局配置甚至误删磁盘（例：未在沙箱跑安装脚本导致 `rm -rf /` 误删服务器数据）。
## 安全、对抗与隐私
- 提示注入与越权：系统提示泄露、对抗样本和花式绕过依然高效（例：用户通过“忽略之前指令”拿到后台工具调用说明）。
- 隐私泄漏：模型记忆输入，日志和回答中可能暴露敏感信息（例：复述先前工单中的手机号或订单号）。
- 价值观与伦理红线：安全策略在多地区/行业下易失效，输出仍可能触碰红线（例：未屏蔽地区敏感话题或行业合规禁区）。
- 权限与会话隔离弱：多用户上下文混用，存在跨会话泄漏风险（例：多人协作时引用了其他用户的历史聊天内容）。
- 安全基线缺失：缺少灾难恢复、降级与熔断策略，异常时容易雪崩（例：上游检索宕机导致整体对话不可用，没有降级答案）。
## 产品化与运营挑战
- 需求澄清能力弱：遇到模糊请求时少主动追问，倾向冗长且模糊的回答（例：用户问“做个活动页”未反问目标、预算、设备渠道）。
- 用户体验漂移：同一问题答案随时间、状态或微小措辞变化大，难以做稳定运营（例：FAQ 一天内多次输出不同价格策略）。
- 人力成本高：提示词工程、对话状态管理和后处理需要持续人工投入（例：为保持 JSON 输出要不断调整 system prompt）。
- 反馈闭环慢：负面反馈难以被快速吸收，模型迭代周期长，线上修复滞后（例：用户举报错误后需多周才能进入新版本权重）。
- 规则对齐难：模型不了解业务 KPI、调用成本或限流策略，易触发额外成本或风险（例：忽略调用限额反复触发付费 API 导致账单爆表）。
## 典型高风险场景
- 医疗、金融、法律：事实幻觉、过时信息与偏见会直接影响合规和人身/财产安全（例：给出不符合当地指南的用药建议；引用废止条款）。
- 工业控制、自动驾驶、能源调度：延迟、抖动和边界条件下的不稳定推理难以满足安全要求（例：异常传感器数据时仍输出正常指令）。
- 内容审核、舆情与推荐：偏见、对抗样本与格式不稳定会放大审核漏报或误报（例：被对抗样本绕过暴恐文本检测）。
- 代码与配置生成：忽略运行时依赖、版本兼容与安全基线，可能引入漏洞（例：生成的依赖存在已知 CVE，或配置未加鉴权）。
- 客服与多轮对话：错误累积、缺乏自我纠错和澄清，容易形成错误链（例：一次误解订单号后续全程使用了错误上下文）。
## 人的主导作用与落地原则
- 人定流程，机做辅助：关键环节先定义人类决策流程，AI 仅做草稿、对照或检索；最终决策与签字由人负责（例：招投标由人定评分表，AI 只初筛标书）。
- 明确“人类监督”角色：指定责任人审核高风险输出（医疗/金融/法律/自动驾驶/安全变更），建立双人复核或结对审查（例：医疗报告需主治与质控双人签字，AI 草稿仅供参考）。
- 人保准入，机做建议：让 AI 给选项而非直接执行，审批、下单、推送、发布、调度等动作必须经过人工确认（例：AI 生成折扣方案，运营手工确认后再上线）。
- 人控知识，机用引用：知识库由人维护版本与生效时间，AI 只能引用，不得自行增删；更新流程需人工验收与回溯标签（例：客服 FAQ 由知识管理员审核后上线，并标注生效日期）。
- 人验安全，机跑流程：安全策略、脱敏规则、合规模板由人制定；AI 输出必须过人设的校验（格式、术语、敏感词、地区合规）（例：代码生成需通过人写的安全扫描规则后才能提交）。
- 人管成本，机限配额：费用预算、配额和重试上限由人配置，AI 调用受限，超限直接降级或中止（例：每日检索调用超过配额时自动转为摘要模式并通知负责人）。
- 人做澄清，机做收敛：对模糊需求，先由人或前置问卷澄清核心参数，再让 AI 生成；避免 AI 自行假设（例：活动页需求先收集预算和渠道，再让 AI 出页面草稿）。
- 人设指标，机供度量：业务 KPI、安全阈值、可解释性要求由人定义；AI 需要输出置信度/引用/可追溯数据供人审阅（例：风控模型需附置信度和引用规则，审核员决定是否拒绝）。
- 人定迭代节奏：线上反馈、红队结果与误报/漏报统计由人评审，决定是否更新提示词、检索索引或模型版本（例：每周复盘高风险对话，人工决定是否切换新模型）。
## 应对建议（简要）
- 数据：做好来源审计、去偏与时效刷新，检索链路监控召回/精排质量（例：每周重建索引并人工抽检医疗条目）。
- 模型：提供置信度或自评估，限制长上下文依赖，针对关键任务做专项评测（例：财报问答需展示置信度并通过专门算例测试）。
- 系统：加熔断、降级和重试上限，强制结构化输出校验，建立在线监控与回溯（例：工具调用超时即降级为静态答案并记录重放日志）。
- 安全：定期红队，对抗样本库更新，隔离系统提示与用户输入，保护日志与隐私（例：每月红队拉通提示注入用例，更新过滤策略）。
- 运营：标准化提示与模板，AB/灰度发布，快速回滚通道，建立反馈闭环与标签体系（例：新客服提示先灰度 5% 流量，异常立即回滚）。
把模型当作不稳定的外部依赖来治理：先明确人类的职责、审批和复核流程，再让 AI 进入关键路径；留足监控、评测、韧性与人工兜底的预算，确保“人是决策者，AI 是工具”。
---
## AI 编程方案选型指南
## 一、方案概述
本文档旨在为公司提供全面的 AI 编程工具选型参考，涵盖国际主流与国产优秀方案，从订阅服务、IDE 工具到插件扩展，帮助决策者根据团队需求、预算和使用场景做出最优选择。
---
## 二、详细对比文档
对于更深入的模型和工具对比分析，可参考以下文档：
| 文档 | 说明 | 链接 |
| ---- | ---- | ---- |
| **国外顶尖编程模型选型建议书** | Claude Opus 4.5、GPT-5.2、Gemini 3 Pro 三大模型的深度对比，含价格、刷新周期、额度用完后如何继续使用 | [international-ai-models-comparison.md](./international-ai-models-comparison.md) |
| **AI 编程工具选型建议书** | GLM-4.7 + Claude Code CLI 最佳组合，Qoder vs Cursor IDE 对比，含刷新周期和额度限制详解 | [qoder-vs-glm47-cursor-claude-comparison.md](./qoder-vs-glm47-cursor-claude-comparison.md) |
> **核心要点**：
> - **刷新周期对比**：GLM-4.7/ChatGPT 每 **5 小时**（最快）> Gemini Code Assist 每 **日** > GitHub Copilot/Qoder/Cursor 每 **月** > Claude Code 每 **7 天**（最慢）
> - **额度用完后方案**：等待刷新周期 / 使用 API KEY 按量计费 / 切换其他订阅账号 / 升级更高版本套餐
---
## 三、核心平台特点总结
- **AI 编程能力排行**：可随时查看 **[LLM Stats](https://llm-stats.com/)** 获取最新模型榜单与分数，用于快速对比模型迭代效果。
- **综合榜单（能力/价格/上下文）**：如需更全面的横向对比，可参考 **[Vellum Leaderboard](https://www.vellum.ai/llm-leaderboard)**。
- **真实工程 Bug 修复基准**：SWE-bench（含真实 GitHub Issues）可参考 **[官方网站](https://www.swebench.com)**。
- **国产模型评测榜单**：OpenCompass（国内权威评测体系之一）可查看 **[排行榜](https://rank.opencompass.org.cn/home)**。
- **国产模型国际榜单入口**：AI Rank 汇总多家国际评测的国产模型成绩，可访问 **[AI Rank](https://airank.dev/)**。
- **上海人工智能实验室-国产模型评测项目**：开源评测框架 OpenCompass（国人自研，涵盖多维度对比）仓库见 **[github.com/open-compass/opencompass](https://github.com/open-compass/opencompass)**。
### 2.1 国际主流 AI 平台
#### **ChatGPT (OpenAI)**
- **核心优势**: GPT-5.2 在 SWE-Bench Pro 达到 55.6%，o1 pro 模式专为复杂编程优化
- **适用场景**: Plus 版 ($20/月) 适合个人开发者，Pro 版 ($200/月) 适合高强度专业用户，API 调用额度高 15-20 倍
- **评价**: o 系列模型在编程、数学、科学问题求解方面表现突出，业界认可度高
**ChatGPT 订阅梯度（以官网为准）**
| 功能 | Plus ($20/月) | Pro ($200/月) | Team ($25/人/月，≥5 人) |
| ---------------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
| 价格 | $20/月 | $200/月 | $30/人/月（按月） $25/人/月 （按年）（起售 5 席） |
| 模型访问 | GPT-5.2 / GPT-5.2 mini，o1-mini 轻量 | GPT-5.2 / GPT-5.2 mini，o1-pro & o3-mini 更高配额 | GPT-5.2 / GPT-5.2 mini，团队共享配额 |
| 高级推理 | o1-mini 低频 | o1-pro 高频、长上下文 | o1-pro 团队配额，可分配席位 |
| 上下文/文件 | 更高文件大小与上下文 | 最高文件大小/上下文，适合长文档与代码库 | 与 Pro 类似，可团队共享 |
| 代码执行（Code Interpreter） | 更高并发与用量 | 最高并发/用量，适合数据分析与脚本 | 团队并发/用量共享 |
| 自定义工具/Memory | ✓ | ✓（更高容量） | ✓（团队共享，权限可管控） |
| 团队/组织 | 个人订阅 | 可与 Team/Enterprise 联动 | 席位制，含团队管理/审计入口 |
- 定价计算: [OpenAI Pricing](https://openai.com/pricing) / [API Pricing](https://openai.com/api/pricing)
#### **Claude (Anthropic)**
- **核心优势**: Claude Code 编程能力业界顶尖，开发者用其完成 95% 编码工作，效率提升 3 倍以上
- **适用场景**: Pro 版 ($20/月) 提供 Sonnet 模型，Max 版 ($100/$200/月) 在 IDE 中独家使用 Opus 4 模型
- **评价**: 11.5 万开发者使用，单周处理 1.95 亿行代码，被评价为 "超值" 的编程助手
**Claude 订阅梯度（以官网为准）**
| 功能 | Pro ($20/月) | Team 标准席位 ($25/人/月，≥5 人) | Team Premium 席位 ($150/人/月) |
| -------------------- | --------------------------------- | ------------------------------------------------------ | ------------------------------------- |
| 价格 | $20/月 | $30/人/月（按月） $25/人/月 （按年）（起售 5 席） | $150/人/月 |
| 模型访问 | Sonnet 高额度，Opus/Opus 预览限量 | Sonnet/Opus 高额度，优先新模型 | Sonnet/Opus 高额度 + Premium 优先队列 |
| 消息额度 | ~5x 免费用量、优先队列 | 团队更高用量、共享池 | 更高配额，适合高频审查/重构 |
| 上下文/文件 | 更长上下文/文件上传 | 最高上下文/文件上限 | 最高上限，适合跨大仓库重构 |
| Artifacts / Projects | ✓ | ✓（团队项目/共享空间） | ✓（Premium 同享） |
| 管理与审计 | ✗ | 管理后台、成员管理、单点登录 | 管理后台、审计、Premium 支持 |
- 定价计算: [Claude Pricing](https://claude.com/pricing)
#### **Gemini Pro 3 / Flash (Google)**
- **核心优势**: 长上下文（百万级，具体以官方发布为准），工具调用与代码补全兼顾，多模态（文本/图像/音频）理解；Flash 版本主打低延迟与低成本，适合实时交互与批量脚本。
- **适用场景**: Pro 3 用于复杂推理、跨文件重构、代码审查；Flash 用于低延迟补全、对话式问答、批量生成；AI Pro/Ultra 套餐对创意多模态（图生图、视频生成）和深度研究额度提升明显。
- **计费/托管**: Google AI Studio 提供订阅（AI Pro $20/月，AI Ultra $250/月，均含免费试用期）与免费层，企业可通过 Vertex AI 获得 VPC-SC、CMEK、审计与私有服务访问（以官方定价为准）；部分功能限美国地区。
- **评价**: 在推理速度/性价比上优势明显，结合 Vertex AI 的安全与合规能力适合对合规有要求的团队；AI Ultra 独享 Deep Think / Project Mariner，适合重度研究或创意团队。
**Gemini Pro 3 订阅梯度**
| 功能 | AI Pro ($20/月) | AI Ultra ($250/月) |
| ------------------------- | ------------------ | ----------------------- |
| 价格 | $20/月（首月免费） | $250/月（前 3 月 $125） |
| Gemini 3 Pro 对话 | 更高权限 | 最高用量 |
| Deep Think | ✗ | ✓（Ultra 专属） |
| Gemini Agent | ✗ | ✓（仅限美国） |
| Deep Research（深度研究） | 20 份/天 | 200 份/天 |
| Gemini Code Assist/CLI | 更高上限 | 最高上限 |
| Jules（程式设计代理） | 更高额度 | 最高额度 |
- 定价计算: [Google AI Studio Pricing](https://ai.google.dev/pricing) / [Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing)
| Project Mariner | ✗ | ✓（抢先体验，仅限美国） |
**ChatGPT vs Claude vs Gemini Pro 3 对比（Team 编码场景）**
| 维度 | ChatGPT | Claude | Gemini Pro 3 |
| ------------- | ------------------------------------ | ------------------------------------ | ----------------------------------------- |
| 起步价格 | Plus $25/人/月 (按年) | Pro $25/人/月 (按年) | AI Pro $20/月 |
| 推理/代码 | o1-pro 强推理，Code Interpreter 稳定 | Sonnet/Opus 代码审查与长上下文表现佳 | Pro 3 长上下文，推理性价比高，纯代码稍弱 |
| 长上下文/文件 | Pro 版最高上下文与文件上传 | Team 版最高上下文与团队共享文件 | Ultra 更高上下文，适合跨文件重构 |
| 代码工具/代理 | Code Interpreter，工具/Memories | Artifacts/Projects，团队协作 | Gemini Code Assist/CLI，Jules（编程代理） |
| 适用场景 | 复杂编码/数据分析/脚本 | 代码审查、跨文件重构、团队配合 | 长上下文重构 + 研究/Agent 编排 |
### 2.2 国产 Coding Plan 平台
#### **GLM 智谱清言 (智谱 AI)**
- **核心优势**: GLM-4.6 代码能力对齐 Claude Sonnet 4，国内最强 Coding 模型，token 消耗比前代少 30%
- **性价比**: 最低 ¥40/月，约 Claude 价格的 1/7，性能达 Claude 的 9/10
- **评价**: 在 CC-Bench 等 7 大权威测试中表现卓越，真实编程测试中超过 Claude Sonnet 4
- **定价**: [bigmodel.cn/pricing](https://bigmodel.cn/pricing)
#### **MiniMax M2**
- **核心优势**: 专为 Agent 和代码而生，SWE-bench 冠军 (44% 成功率超 GPT-5 Codex)，价格仅 Claude 的 8%，速度是其 2 倍
- **技术参数**: 100 亿激活参数，2300 亿总参数，20 万+ 上下文窗口
- **评价**: 开源排名第一，前端设计和交互方案表现尤为出色
- **定价**: [MiniMax 定价](https://platform.minimaxi.com/docs/guides/pricing?key=68aec7e84c75b9c918ccd10d)
#### **Kimi K2 Thinking (月之暗面)**
- **核心优势**: 万亿参数混合专家架构，支持 256K 上下文，能执行 200-300 次连续工具调用
- **技术特点**: 原生 INT4 量化，低延迟模式下 2 倍加速且无损性能
- **评价**: NIST 评估为当时中国最强 AI 模型，在 SWE-Multilingual 得分 61.1%
- **定价**: [Kimi 定价](https://kimi.moonshot.cn/pricing)
#### **通义千问 (阿里云 Qwen 系列)**
- **最新模型族**: Qwen3（通用）/Qwen3-Coder（代码）/Qwen3-VL（多模态）/Qwen-Long（超长上下文）及轻量推理款 QwQ；覆盖推理、代码、视觉与长文档需求
- **核心能力**: 原生函数/工具调用、检索/联网、代码补全与跨文件重构，多模态理解（图文/表格/公式），长上下文版本可支持跨文件与长文档分析
- **适用场景**: 百炼平台一键编排多模型与工具，适合电商/内容/客服/代码等多轮推理场景；长文档与多模态（设计稿还原、表格解析）场景表现稳健
- **计费/托管**: 百炼提供按量/订阅与企业版（VPC、审计、CMEK、数据不出境），支持私有化或混合云部署，便于满足国内合规
- **评价**: 中文语料和行业场景打磨成熟，工程化与性价比兼顾，是国内团队可长期依赖的主力模型
- **定价**: [百炼模型市场-Qwen](https://bailian.console.aliyun.com/#/model-market/detail/qwen-max)
#### **火山方舟 (豆包 Doubao-Seed-Code)**
- **核心优势**: 国内首个支持视觉理解的编程模型，可根据 UI 设计稿/截图生成代码，在 TRAE 环境中 SWE-Bench Verified 达 78.80% (SOTA)
- **成本优势**: 业界综合成本降低 62.7%，国内最低价，同样任务成本仅为 Claude 的 8%，GLM 的 44%
- **评价**: 前端页面复刻能力 "遥遥领先"，兼容 Anthropic API，易于迁移
- **定价**: [Doubao 定价](https://www.volcengine.com/product/doubao)
### 2.3 IDE 与开发环境
#### **Cursor**
- **市场地位**: 估值 99 亿美元，年化收入 5 亿美元且每两月翻番，行业领导者
- **核心功能**: 预测式代码补全 (预测 5-10 行)、跨文件重构引擎、交互式调试
- **评价**: v1.0/v1.1 新增 BugBot 审查、Background Agent、Memory 能力，社区生态最完善
#### **GitHub Copilot**
- **核心优势**: 与 GitHub 深度集成，生态完善，2025 年 12 月新增组织级代码审查功能
- **Premium Requests**: Pro 版 300 次/月，Pro+ 版 1,500 次/月，超量 $0.04/次
- **评价**: 超时率从 4.3% 降至 1.1%，稳定性显著提升，适合 GitHub 重度用户
#### **Windsurf (Codeium)**
- **技术创新**: 全球首个 AI Flow 范式 IDE，Cascade 技术实现多步骤协同，Supercomplete 预测高层意图
- **定价优势**: 免费版 25 积分/月，Pro 版 $15/月 (500 积分)，可免费使用 GPT-4o 和 Claude 3.5 Sonnet
- **评价**: 上下文理解能力优于 Cursor，适合需要深度代码库理解的团队
#### **Trae (字节跳动)**
- **本土优势**: 中国首个 AI 原生 IDE，原生中文支持，配置 Doubao-1.5-pro/DeepSeek R1/V3
- **核心功能**: Builder 模式 (从零构建项目)、Solo 模式 (全流程自动化)
- **评价**: 目前完全免费，效率提升 300%，但低配置环境下性能问题明显
#### **Qoder（阿里）**
- **定位**: 阿里推出的全栈 AI IDE，强调跨文件重构与代码审查
- **核心功能**: 长上下文补全、Agent 式任务分解、项目级搜索与重构、终端/工具调用
- **定价**: Pro+ $30/月，Ultra $100/月（更高上下文与 Agent 并发）
#### **Kiro (AWS)**
- **核心特点**: 规格驱动开发 (Spec-Driven)，强制 "先计划后构建"，Agent Hooks 自动化触发器
- **技术架构**: 专用 Claude Sonnet 3.7/4.0 模型
- **评价**: 适合企业级项目管理和流程规范化，目前公测阶段免费
### 2.4 VSCode 插件
#### **Augment**
- **核心优势**: SWE-Bench Verified 冠军 (65.4%)，20 万 token 上下文窗口，基于 Claude Sonnet 4
- **功能特点**: Agent 智能体模式、持久记忆学习编码风格、支持多模态输入 (截图/Figma)
- **多 IDE 支持**: JetBrains、VS Code、GitHub、Slack、Vim 全覆盖
- **定价**: 新用户半月免费试用，之后 $60/月
---
## 三、选型建议
### 3.0 不同规模团队的决策要点
- **提效优先结论**：追求最佳 AI 编程提效时，优先选 Claude Code（AI 工程化最完善，$100/月足够覆盖重度开发）；成本敏感可选 codex（工程化稍弱，约 $20/月满足多数场景）。
- **多模态优势**：Gemini Pro 3 在图像/视觉理解上领先，适合涉及设计稿还原或多模态需求的团队，纯编程能力弱于 Claude Code/codex。
- **极致降本路径**：在 SaaS 订阅外，还可组合开源项目自建中转站与号池，进一步压缩调用成本（需评估合规与运维成本）。
- **个人 / 1-10 人**：优先 ChatGPT Plus、Claude Pro、Cursor Pro（或 Windsurf Free/Pro）+ Copilot Pro；关注易用与成本封顶。
- **10-50 人**：Cursor Pro/Pro+ + Claude Max / ChatGPT Pro；国内可选 Doubao Lite/Pro + Windsurf Pro；统一 1-2 款 IDE，建立提示词与代码片段库。
- **50-200 人**：国际（Cursor Pro+/Ultra + Claude Max / ChatGPT Pro）+ 国内（Doubao Pro 或 GLM Pro/Max + Windsurf/Trae）；开始启用 SSO、审计、内网代理，分团队额度管理。
- **200-300 人（大型研发）**：国际+国内双栈并行，企业版或 Team/Business 版启用 SSO/SCIM、审计日志、VPC/专线；指标化复盘（拒答率、幻觉率、代码审查命中率）。
- **300 人以上 / 跨境上市公司**：必须满足 SOX/内部控制、数据主权、GDPR/CCPA、渗透与安全评估；采用企业合同（DPA/BAA/SOW），双 Region 数据隔离，DLP + 本地检索，关键产出需人工复核留痕。
- **共通动作**：统一 IDE/插件、分级仓库访问、敏感项目禁传公有端点、月度成本与质量复盘，逐步升级模型与额度。
### 3.1 按预算分类
- **低成本方案**: MiniMax M2 (¥29 起)、火山方舟 (¥40 起)、Trae (免费)
- **中等预算**: GLM (¥40 起)、Windsurf Pro ($15)、GitHub Copilot Pro ($10)
- **高端方案**: Cursor Ultra ($200)、ChatGPT Pro ($200)、Claude Max ($200)
### 3.2 按使用场景分类
- **个人开发者**: ChatGPT Plus、Claude Pro、GLM Lite
- **中小团队**: Cursor Pro、Trae、Windsurf、MiniMax
- **企业级团队**: Cursor Teams、GitHub Copilot Enterprise、Kiro、Augment
- **前端开发优先**: 火山方舟 (视觉理解)、MiniMax M2
- **中文环境优先**: Trae、GLM、火山方舟、Kimi
### 3.3 按技术栈分类
- **VSCode 生态**: Augment、Trae、Windsurf 插件
- **JetBrains 用户**: Augment、Windsurf 插件
- **GitHub 重度用户**: GitHub Copilot
- **多语言项目**: Cursor、Kimi K2、GLM-4.6
### 3.4 推荐组合示例（多规模适用）
| 需求 | 推荐组合 | 说明 |
| ----------------------- | -------------------------------------------------------- | ------------------------------------------- |
| 代码生成 + 评审（国际） | Cursor Pro+/Ultra + Claude Max / ChatGPT Pro | 大上下文 + 强代理调度，覆盖多语言与复杂重构 |
| 代码生成 + 评审（国内） | Windsurf Pro 或 Trae + Doubao Seed-Code / GLM-4.6 | 便于内网代理与中文语境，成本可控 |
| IDE 轻量补全 | GitHub Copilot Business/Enterprise | 统一 GitHub 权限与审计，团队管理成熟 |
| Agent 式自动化 | Cursor Background Agent / Trae Solo 模式 / MiniMax Agent | 适合批量脚手架、重构、测试生成 |
| 合规/隔离 | OpenAI/Anthropic Enterprise 或 Doubao/GLM 私有化选项 | 支持 SSO、审计、VPC/专线、模型封装 |
### 3.5 模型与方案汇总表（选型速览）
| 类别 | 代表模型/方案 | 适合规模 | 主要优势 | 价格级别 | 合规要点 |
| ----------- | --------------------------------------- | ---------- | ----------------------------------- | -------- | ----------------------------------- |
| 国际通用 | ChatGPT Pro / Claude Max | 个人-200人 | 全能生成、复杂推理、API 额度高 | $$$ | 开启 SSO/日志控制；敏感仓库少量上传 |
| 国际企业 | OpenAI/Anthropic Enterprise | 200人以上 | 合规合同（DPA/BAA）、审计、私有端点 | $$$$ | 支持专线/VPC、数据隔离、可签 SOW |
| 国内主力 | Doubao Seed-Code / GLM-4.6 | 10-300人 | 中文/视觉理解强，成本低 | $$ | 企业版支持专线，需国内数据合规 |
| 性价比 | MiniMax M2 / Kimi K2 | 1-200人 | 价格低、长上下文 | $-$$ | 避免敏感代码上传公有端点 |
| IDE/Agent | Cursor Pro+/Ultra / Windsurf Pro / Trae | 10-300人 | IDE 深度集成，Agent/Flow 协同 | $-$$$ | 企业代理、最少遥测、私有仓库索引 |
| 补全/审查 | GitHub Copilot Business/Enterprise | 10-300人 | GitHub 权限与审计成熟 | $$ | 绑定组织 SSO/SCIM，禁外发私仓代码 |
| VSCode 插件 | Augment | 10-200人 | 大上下文，Agent/多模态 | $$ | 控制上传范围与日志，必要时本地检索 |
---
## 订阅计划
### ChatGPT
| **套餐等级** | **月度** |
| ----------------- | ------------- |
| **Plus** | $20 |
| **Pro** | $200 |
| **Business/Team** | $30/person |
| **Enterprise** | Sales Contact |
### Claude
[Pricing](https://platform.claude.com/docs/en/about-claude/pricing)
| **套餐等级** | **月度** |
| ------------ | -------- |
| **Pro** | $20 |
| **Max 5x** | $100 |
| **Max 20x** | $200 |
## IDE/插件
## Coding Plan
提供 API，可接入 Claude Code，Cline 和 Chat 软件中使用。
### GLM (z.ai)(智谱清言)
[Pricing](https://bigmodel.cn/glm-coding)
最新模型：GLM-4.6 GLM-4.6V
| **套餐等级** | **月度** | **季度** | 年度 | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| ------------ | -------- | -------- | ----- | ------------------------ | -------------------- |
| **Lite** | ¥40 | ¥120 | ¥480 | ~120 Prompts | Claude Pro 的 3 倍 |
| **Pro** | ¥200 | ¥600 | ¥2400 | ~600 Prompts | Lite 的 5 倍 |
| **Max** | ¥400 | ¥1200 | ¥4800 | ~2400 Prompts | Pro 的 4 倍 |
### MiniMax M2
[Pricing](https://platform.minimaxi.com/docs/pricing/coding-plan)
最新模型：MiniMax M2
| **套餐等级** | **月度** | **季度** | **年度** | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| ------------ | -------- | -------- | -------- | ------------------------ | ----------------------- |
| **Starter** | ¥29 | ¥87 | ¥348 | 40 Prompts | 约 Claude Pro 的 1 倍 |
| **Plus** | ¥49 | ¥147 | ¥588 | 100 Prompts | 约 Claude Pro 的 2.5 倍 |
| **Max** | ¥119 | ¥357 | —— | 300 Prompts | 约 Claude Pro 的 7.5 倍 |
## Kimi
[Pricing](https://www.kimi.com/membership/pricing)
最新模型：Kimi K2 Thinking
| **套餐等级** | **月度** | **季度** | **年度** | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| -------------- | -------- | -------- | -------- | ------------------------ | -------------------- |
| **Andante** | ¥49 | —— | —— | 1024 Prompts | —— |
| **Moderato** | ¥99 | —— | —— | 2048 Prompts | —— |
| **Allegretto** | ¥119 | —— | —— | 7168 Prompts | —— |
## 火山方舟(豆包)
[Pricing](https://www.volcengine.com/activity/codingplan)
最新模型：Doubao-Seed-Code DeepSeek-V3.2
| **套餐等级** | **月度** | **季度** | **年度** | **用量说明 (每 5 小时)** | **对应 Claude 额度** |
| ------------ | -------- | -------- | -------- | ------------------------ | -------------------- |
| **Lite** | ¥40 | ¥120 | ¥480 | ~120 Prompts | Claude Pro 的 3 倍 |
| **Pro** | ¥200 | ¥600 | ¥2400 | ~600 Prompts | Lite 的 5 倍 |
## IDE
### Cursor
[Pricing](https://www.cursor.com/pricing)
| **套餐** | **月度 (USD)** | **额度** |
| -------- | -------------- | ---------------------------------------------------------- |
| Hobby | $0 | 1 周试用 + 有限 Agent/Tab |
| Pro | $20 | 无限 Tab/Auto + $20 frontier model 额度 (~225 次 Sonnet 4) |
| Pro+ | $60 | Pro 的 3 倍模型使用额度 |
| Ultra | $200 | Pro 的 20 倍模型使用额度 |
| Teams | $40/人 | Pro 额度 + 团队管理 |
### Github Copilot
[Pricing](https://github.com/features/copilot/plans)
| **套餐** | **月度 (USD)** | **额度** |
| ---------- | -------------- | ------------------------------------------------- |
| Free | $0 | 2,000 completions/月 + 50 premium requests/月 |
| Pro | $10 | 无限 completions + 300 premium requests/月 |
| Pro+ | $39 | 无限 completions + 1,500 premium requests/月 |
| Business | $19/人 | 无限 completions + 300 premium requests/用户/月 |
| Enterprise | $39/人 | 无限 completions + 1,000 premium requests/用户/月 |
#### Winsurf
[Pricing](https://windsurf.com/pricing)
| **套餐** | **月度 (USD)** | **额度** |
| ---------- | -------------- | ------------------- |
| Free | $0 | 25 credits/月 |
| Pro | $15 | 500 credits/月 |
| Teams | $30/人 | 500 credits/人/月 |
| Enterprise | 联系销售 | 更高额度 + 企业功能 |
#### Trae
[Pricing](https://www.trae.ai/pricing)
[Billing](https://docs.trae.ai/ide/billing)
| **套餐** | **月度 (USD)** | **额度** |
| -------- | -------------- | ------------------------- |
| Free | $0 | 基础功能（有限额度） |
| Pro | $10 | 新用户首月 $3（原价 $10） |
#### Kiro
[Pricing](https://kiro.dev/pricing)
| **套餐** | **月度 (USD)** | **额度** |
| ---------- | -------------- | -------------------------------------- |
| Free | $0 | 50 credits |
| Pro | $20 | 1,000 credits/月（超量 $0.04/credit） |
| Pro+ | $40 | 2,000 credits/月（超量 $0.04/credit） |
| Power | $200 | 10,000 credits/月（超量 $0.04/credit） |
| Enterprise | 联系销售 | 自定义额度 + 企业功能 |
### VSCode 插件
#### Augment
[Pricing](https://augmentcode.com/pricing)
| **套餐** | **月度 (USD)** | **额度** |
| ---------- | -------------- | --------------------- |
| Indie | $20 | 40,000 credits/月 |
| Standard | $60 | 130,000 credits/月 |
| Max | $200 | 450,000 credits/月 |
| Enterprise | 联系销售 | 自定义额度 + 企业功能 |
## 共享方案
### New API
[GitHub](https://github.com/QuantumNous/new-api)
若上方的 coding plan 提供了 apikey 的方式，则可以将 apikey 添加到 new api 中进行聚合，然后分发出去。
### Claude Relay Service
[GitHub](https://github.com/Wei-Shaw/claude-relay-service)
若没有直接提供 key，例如 Claude Code, Codex 等，则可以部署 CRS 来登录 Claude Code 和 OpenAI 的账号来分发
## 注意点
Claude Code 由于环境要求严格，容易封号，所以部署环境要至少需要使用美国家庭宽带代理，否则容易封号 (虽然会退款)。
## 促销活动
- 当前 chatgpt 的 business 方案存在 $0 一个月，具有 5 个席位的 team 方案，市面上会有 ￥10/个席位并提供质保的商家，结束时间取决于 openai 的官方政策。
- GLM 存在首年/季度/年优惠，可使用多个账号购买并通过上方的方式共享和分发。
### Claude code/Codex 中转站
当前市面上存在 Claude Code/Codex 中转站，以 Claude Code 为例，价格普遍在每刀 ￥0.3-￥1 之间。由于价格计算涉及倍率/中转站内部计费规则，故不列出。
---
## AI Agent（智能体）
## 概述
**AI Agent（人工智能智能体）** 是一个能够**自主感知环境、做出决策并执行行动**的 AI 系统。与传统的聊天式 AI 不同，Agent 可以：
- 主动调用工具
- 规划多步骤任务
- 处理复杂的工作流
- 在失败时自动重试
> **核心特点**：自主性、交互性、反应性、主动性
---
## 核心概念
### 1. Agent 的定义
**Agent** 是能够：
1. **感知** (Perceive)：获取环境信息
2. **推理** (Reason)：分析情况并制定计划
3. **行动** (Act)：执行具体操作
4. **学习** (Learn)：从反馈中改进
### 2. Agent 与 Chatbot 的区别
| 特性 | Chatbot | AI Agent |
| ---- | ------- | -------- |
| **交互方式** | 问答式 | 任务导向 |
| **主动性** | 被动响应 | 主动规划 |
| **工具使用** | 有限 | 丰富 |
| **任务复杂度** | 单步任务 | 多步骤任务 |
| **记忆能力** | 会话级 | 长期记忆 |
| **自主决策** | 无 | 有 |
---
## Agent 的架构
### 基本架构
```
┌─────────────────────────────────────────────────────────┐
│ AI Agent 架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 输入 │ ──▶│ 推理 │ ──▶│ 输出 │ │
│ │ Input │ │ Reasoning│ │ Output │ │
│ └─────────┘ └────┬────┘ └─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ 工具调用 │ │
│ │ Tools │ │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ 环境反馈 │ │
│ │ Feedback │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### 核心组件
#### 1. 规划模块 (Planning)
- 任务分解
- 步骤排序
- 资源分配
- 时间估算
#### 2. 记忆模块 (Memory)
- 短期记忆（当前会话）
- 长期记忆（向量存储）
- 上下文管理
- 知识检索
#### 3. 工具模块 (Tools)
- 文件操作
- API 调用
- 命令执行
- 数据库查询
#### 4. 反思模块 (Reflection)
- 结果验证
- 错误处理
- 策略调整
- 重试机制
---
## Agent 的类型
### 1. 单 Agent 系统
由一个 Agent 完成所有任务：
```
┌─────────────────┐
│ Agent │
│ ┌───────────┐ │
│ │ Planning │ │
│ │ Memory │ │
│ │ Tools │ │
│ │ Action │ │
│ └───────────┘ │
└─────────────────┘
```
**特点**：
- 实现简单
- 适合单领域任务
- 容易调试
### 2. 多 Agent 系统
多个 Agent 协同工作：
```
┌─────────────────────────────────────────────────────────┐
│ Multi-Agent System │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Planner │ ──▶│ Coder │ ──▶│ Tester │ │
│ │ Agent │ │ Agent │ │ Agent │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └───────────────┴───────────────┘ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Coordinator │ │
│ │ Agent │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
**特点**：
- 专业化分工
- 可并行处理
- 适合复杂任务
**常见角色**：
| Agent 角色 | 职责 |
| ---------- | ---- |
| **Planner** | 任务规划、分解 |
| **Coder** | 代码生成、修改 |
| **Reviewer** | 代码审查、验证 |
| **Tester** | 测试用例生成 |
| **Debugger** | 问题定位、修复 |
| **Documenter** | 文档生成 |
### 3. 层级 Agent 系统
Agent 之间存在上下级关系：
```
┌─────────────────────────────────────────────────────────┐
│ Hierarchical Agent System │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────┐ │
│ │ Manager Agent (L1) │ │
│ │ 任务分配、进度监控、协调 │ │
│ └─────────────┬─────────────────────────┘ │
│ │ │
│ ┌──────────┼──────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Coder ││Tester││Doc │ (L2) │
│ │Agent ││Agent ││Agent │ │
│ └──────┘ └──────┘ └──────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## 主流 Agent 框架
### 1. LangChain Agent
```python
from langchain.agents import create_openai_functions_agent
from langchain.tools import Tool
# 定义工具
tools = [
Tool(
name="calculator",
func=lambda x: eval(x),
description="执行数学计算"
)
]
# 创建 Agent
agent = create_openai_functions_agent(
llm=chat_model,
tools=tools,
prompt=prompt
)
```
### 2. AutoGen
```python
from autogen import AssistantAgent, UserProxyAgent
# 创建 Agent
assistant = AssistantAgent(
name="assistant",
llm_config={"model": "gpt-4"}
)
user_proxy = UserProxyAgent(
name="user_proxy",
code_execution_config={"work_dir": "coding"}
)
# 启动对话
user_proxy.initiate_chat(
assistant,
message="计算斐波那契数列的第 10 项"
)
```
### 3. Claude Code Task Agent
```typescript
// 使用 Claude Code 的子代理
import { Task } from '@anthropic-ai/claude-code';
const result = await Task({
description: "分析项目代码结构",
subagentType: "explore",
model: "claude-opus-4-5"
});
```
### 4. Cursor Composer
Cursor 的 Agent 系统：
- **Composer**：多步骤任务执行
- **Background Agent**：后台处理
- **Multi-Agent Interface**：并行多智能体
---
## Agent 的设计模式
### 1. ReAct (Reasoning + Acting)
```
Thought (思考) → Action (行动) → Observation (观察) → Thought (思考) → ...
```
**示例**：
```
Thought: 我需要读取文件内容
Action: ReadFile(path="src/main.js")
Observation: 读取到 100 行代码
Thought: 我看到了问题所在
Action: EditFile(...)
```
### 2. Chain of Thought
逐步推理，展示思考过程：
```
问题：用户报告登录失败
思考步骤：
1. 检查认证逻辑
2. 查看日志文件
3. 验证 API 配置
4. 定位问题原因
```
### 3. Plan-and-Execute
先规划再执行：
```
1. 规划阶段：
- 分析需求
- 制定计划
- 分解任务
2. 执行阶段：
- 按步骤执行
- 记录进度
- 处理异常
```
### 4. Self-Refine
自我反思和改进：
```
1. 生成初始方案
2. 自我审查
3. 识别问题
4. 改进方案
5. 重复 2-4
```
---
## Agent 的最佳实践
### 1. 明确目标
- 清晰定义任务边界
- 设定成功标准
- 明确输出格式
### 2. 工具设计
- 工具功能单一
- 输入输出明确
- 错误处理完善
### 3. 记忆管理
- 合理设置上下文窗口
- 使用向量存储长期记忆
- 定期清理无关信息
### 4. 安全考虑
- 限制可执行的操作
- 实施权限控制
- 记录所有行动
### 5. 可观测性
- 记录决策过程
- 监控执行状态
- 追踪资源使用
---
## Agent 的应用场景
| 场景 | Agent 类型 | 说明 |
| ---- | ---------- | ---- |
| **代码生成** | Coder Agent | 生成、修改代码 |
| **代码审查** | Reviewer Agent | 审查代码质量 |
| **自动化测试** | Tester Agent | 生成测试用例 |
| **Bug 修复** | Debugger Agent | 定位和修复问题 |
| **文档生成** | Documenter Agent | 生成技术文档 |
| **数据分析** | Analyst Agent | 处理数据任务 |
| **运维自动化** | Ops Agent | 自动化运维操作 |
---
## 参考资源
### 论文
- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)
- [AutoGen: Enabling Next-Gen LLM Applications](https://arxiv.org/abs/2308.08155)
### 框架文档
- [LangChain Agents](https://python.langchain.com/docs/modules/agents/)
- [AutoGen Documentation](https://microsoft.github.io/autogen/)
- [Claude Code CLI](https://docs.anthropic.com/claude-code)
---
**文档更新时间：2025 年 12 月**
---
## AI 沙箱（Sandbox）
# AI 沙箱（AI Sandbox）
## 概述
**AI 沙箱** 是一个**隔离的执行环境**，用于安全地运行 AI 生成的代码、执行命令或进行实验。沙箱确保 AI 操作不会影响宿主系统，同时提供可控的测试环境。
> **核心价值**：安全性 + 可控性 + 可重复性
---
## 为什么需要 AI 沙箱
### 1. 安全风险
没有沙箱的情况下，AI 可能：
- 删除重要文件
- 执行恶意命令
- 访问敏感数据
- 消耗系统资源
- 感染网络环境
### 2. 典型场景
| 场景 | 风险 | 沙箱解决方案 |
| ---- | ---- | ----------- |
| AI 生成代码执行 | 代码可能包含恶意逻辑 | 在容器中执行 |
| AI 调用系统命令 | 命令可能破坏系统 | 限制可用命令 |
| AI 访问网络 | 可能访问恶意网站 | 网络隔离/代理 |
| AI 修改文件 | 可能删除重要文件 | 文件系统隔离 |
---
## 沙箱的类型
### 1. 进程级沙箱
隔离单个进程：
```
┌─────────────────────────────────────────────────────────┐
│ 进程沙箱 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 宿主系统 │ │ 沙箱进程 │ │
│ │ │ │ │ │
│ │ ┌────────┐ │ ──▶ │ ┌────────┐ │ │
│ │ │ 其他 │ │ │ │ AI 代码 │ │ │
│ │ │ 进程 │ │ │ │ 执行 │ │ │
│ │ └────────┘ │ │ └────────┘ │ │
│ │ │ │ │ │
│ └──────────────┘ └──────────────┘ │
│ ▲ ▲ │
│ └─────────────────────────┘ │
│ 权限隔离（chroot, namespace） │
│ │
└─────────────────────────────────────────────────────────┘
```
**技术**：
- Linux: chroot, namespace, seccomp
- macOS: sandbox_exec
- Windows: Job Objects, Restricted Tokens
### 2. 容器级沙箱
使用容器技术隔离：
```
┌─────────────────────────────────────────────────────────┐
│ 容器沙箱 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 宿主系统 │ │
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ Docker/Podman 容器 │ │ │
│ │ │ ┌─────────────────────────────┐ │ │ │
│ │ │ │ AI 执行环境 │ │ │ │
│ │ │ │ - 独立文件系统 │ │ │ │
│ │ │ │ - 独立网络栈 │ │ │ │
│ │ │ │ - 资源限制 │ │ │ │
│ │ │ └─────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
**技术**：
- Docker
- Podman
- Kubernetes (Pod)
- gVisor (用户空间内核)
### 3. 虚拟机级沙箱
完整的虚拟化隔离：
```
┌─────────────────────────────────────────────────────────┐
│ 虚拟机沙箱 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 宿主操作系统 │ │
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ Hypervisor (KVM/VMware) │ │ │
│ │ │ ┌─────────────────────────────┐ │ │ │
│ │ │ │ 虚拟机操作系统 │ │ │ │
│ │ │ │ ┌─────────────────────┐ │ │ │ │
│ │ │ │ │ AI 执行环境 │ │ │ │ │
│ │ │ │ │ - 完整隔离 │ │ │ │ │
│ │ │ │ │ - 独立内核 │ │ │ │ │
│ │ │ │ │ - 硬件虚拟化 │ │ │ │ │
│ │ │ │ └─────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
**技术**：
- KVM / QEMU
- VMware
- VirtualBox
- Firecracker (微虚拟机)
### 4. Web 沙箱
在浏览器/服务器端执行 JavaScript：
```
┌─────────────────────────────────────────────────────────┐
│ Web 沙箱 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 浏览器/服务器 │ │
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ iframe / Web Worker │ │ │
│ │ │ ┌─────────────────────────────┐ │ │ │
│ │ │ │ AI 生成的 JavaScript │ │ │ │
│ │ │ │ - SOP 限制 │ │ │ │
│ │ │ │ - CSP 策略 │ │ │ │
│ │ │ │ - 内存隔离 │ │ │ │
│ │ │ └─────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
**技术**：
- iframe + sandbox 属性
- Web Workers
- Service Workers
- QuickJS (嵌入式 JS 引擎)
---
## 主流 AI 沙箱方案
### 1. E2B
专为 AI 代码执行设计的沙箱：
```bash
# 安装 E2B
pip install e2b
# 使用示例
from e2b import Sandbox
sandbox = Sandbox()
result = sandbox.run_code("print('Hello from AI!')")
```
**特点**：
- 专为 LLM 设计
- 预装常用工具
- 支持多种编程语言
- API 简单易用
### 2. Docker Exec
直接使用 Docker 作为沙箱：
```bash
# 运行容器执行代码
docker run --rm -v $(pwd):/workspace python:3.12 \
python /workspace/script.py
# 限制资源
docker run --rm \
--memory="512m" \
--cpus="1.0" \
--network=none \
python:3.12 python script.py
```
### 3. Firecracker
AWS Lambda 使用的微虚拟机：
```json
{
"boot_source": {
"kernel_image_path": "vmlinux.bin"
},
"drives": [
{
"drive_id": "rootfs",
"path_on_host": "rootfs.ext4",
"is_root_device": true,
"is_read_only": false
}
],
"machine_config": {
"vcpu_count": 1,
"mem_size_mib": 512
}
}
```
### 4. WebAssembly (WASM)
在浏览器中安全执行：
```javascript
// QuickJS WASM 沙箱
import { getQuickJS } from 'quickjs-emscripten';
const { evalCode } = await getQuickJS();
// 在隔离环境中执行代码
const result = evalCode(`
const sum = (a, b) => a + b;
sum(1, 2);
`);
```
---
## AI 工具中的沙箱使用
### Claude Code CLI
Claude Code 使用系统级沙箱：
```typescript
// 安全执行命令
const result = await Bash({
command: "npm test",
options: {
timeout: 30000,
cwd: workspaceDir,
env: { ...process.env, NODE_ENV: 'test' }
}
});
```
**安全措施**：
- 命令超时限制
- 工作目录限制
- 环境变量过滤
- 文件访问权限控制
### Cursor IDE
Cursor 使用容器执行代码：
- 每个 Tab 在独立环境中运行
- 文件系统访问需用户授权
- 网络请求可配置
### GitHub Codespaces
完整的云开发环境作为沙箱：
```
用户代码 → Codespaces 容器 → 隔离执行环境
↓
资源限制
↓
网络隔离
```
---
## 构建自己的 AI 沙箱
### 基础方案：Python subprocess
```python
import subprocess
import tempfile
import os
def execute_in_sandbox(code: str, timeout: int = 30):
"""在临时目录中执行代码"""
with tempfile.TemporaryDirectory() as tmpdir:
# 写入代码文件
code_file = os.path.join(tmpdir, 'script.py')
with open(code_file, 'w') as f:
f.write(code)
# 执行代码（带超时）
result = subprocess.run(
['python', code_file],
cwd=tmpdir,
timeout=timeout,
capture_output=True,
text=True
)
return result.stdout, result.stderr, result.returncode
```
### 中级方案：Docker
```python
import docker
def execute_in_docker(code: str, language: str = 'python'):
"""在 Docker 容器中执行代码"""
client = docker.from_env()
# 运行容器
container = client.containers.run(
f'{language}:3.12-slim',
command=['python', '-c', code],
mem_limit='512m',
cpu_quota=100000,
network_disabled=True,
detach=True
)
# 等待执行完成
result = container.wait()
logs = container.logs()
# 清理
container.remove()
return logs.decode('utf-8')
```
### 高级方案：gVisor
```bash
# 使用 gVisor 运行容器
docker run --runtime=runsc --rm python:3.12 python -c "print('Hello')"
```
---
## 沙箱的最佳实践
### 1. 资源限制
| 资源 | 建议限制 | 原因 |
| ---- | -------- | ---- |
| CPU | 1-2 核心 | 防止 CPU 占用 |
| 内存 | 512MB-2GB | 防止内存耗尽 |
| 磁盘 | 1GB | 限制存储使用 |
| 网络 | 禁用或代理 | 防止恶意访问 |
| 时间 | 30-60秒 | 防止无限循环 |
### 2. 文件系统隔离
- 使用临时文件系统
- 禁止访问宿主目录
- 提供虚拟文件系统
### 3. 网络隔离
- 默认禁用网络
- 需要时使用白名单
- 记录所有网络请求
### 4. 日志和监控
- 记录所有操作
- 监控资源使用
- 异常行为告警
### 5. 清理机制
- 执行后自动清理
- 定时清理残留
- 资源回收
---
## 沙箱方案对比
| 方案 | 隔离级别 | 性能 | 复杂度 | 适用场景 |
| ---- | -------- | ---- | ------ | -------- |
| **进程级** | 低 | 高 | 低 | 简单脚本 |
| **容器** | 中 | 高 | 中 | 通用场景 |
| **虚拟机** | 高 | 中 | 高 | 高安全要求 |
| **Web WASM** | 中 | 中 | 低 | 浏览器环境 |
| **E2B** | 中 | 高 | 低 | 快速集成 |
---
## 参考资源
### 开源项目
- [E2B](https://github.com/e2b-dev/e2b) - AI 代码执行沙箱
- [gVisor](https://github.com/google/gvisor) - 用户空间内核
- [Firecracker](https://github.com/firecracker-microvm/firecracker) - 微虚拟机
- [QuickJS](https://github.com/quickjs-ng/quickjs) - 轻量级 JS 引擎
### 文档
- [Docker 安全](https://docs.docker.com/engine/security/)
- [Linux Namespace](https://man7.org/linux/man-pages/man7/namespaces.7.html)
- [seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html)
---
**文档更新时间：2025 年 12 月**
---
## 上下文窗口（Context Window）
## 概述
**上下文窗口 (Context Window)** 是大语言模型在单次对话中**能够记忆和处理的最大 Token 数量**。它决定了模型能"看到"和"理解"多少信息。
> **简单理解**：上下文窗口 = 模型的"短期记忆容量"
---
## 核心概念
### 1. 上下文窗口的组成
```
┌─────────────────────────────────────────────────────────┐
│ 上下文窗口 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 系统提示 │ │对话历史 │ │ 用户 │ │
│ │ System │ │ History │ │ Query │ │
│ │ Prompt │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ [========|============|============] │
│ └───────────────────────────────────────────────────┘ │
│ 总 Token 数 ≤ 上下文窗口 │
│ │
└─────────────────────────────────────────────────────────┘
```
### 2. 输入 vs 输出窗口
| 类型 | 说明 |
| ---- | ---- |
| **输入窗口** | 模型能接收的最大 Token 数 |
| **输出窗口** | 模型能生成的最大 Token 数（通常 < 输入） |
---
## 主流模型的上下文窗口
### 超长上下文模型 (>500K)
| 模型 | 上下文长度 | 发布时间 |
| ---- | ---------- | -------- |
| **Gemini 2.0 Pro** | 2M tokens | 2025.02 |
| **Gemini 1.5 Pro** | 1M tokens | 2024.02 |
| **GPT-5.2** | 1M tokens | 2024.12 |
| **Claude 3** | 200K tokens | 2024.03 |
### 标准上下文模型 (100K-200K)
| 模型 | 上下文长度 |
| ---- | ---------- |
| **Claude Opus 4.5** | 200K |
| **Claude Sonnet 4.5** | 200K |
| **GPT-4o** | 128K |
| **GLM-4.7** | 128K |
### 中等上下文模型 (32K-100K)
| 模型 | 上下文长度 |
| ---- | ---------- |
| **GPT-4** | 32K / 8K |
| **Claude 2** | 100K |
| **Llama 3.1** | 128K |
### 小上下文模型 (<32K)
| 模型 | 上下文长度 |
| ---- | ---------- |
| **GPT-3.5** | 16K / 4K |
| **原始 Claude** | 9K / 72K |
| **Llama 2** | 4K |
---
## 上下文窗口的演进
```
2020 ────── 2022 ────── 2024 ────── 2026
│ │ │ │
2048 → 32K → 128K → 2M
(GPT-3) (GPT-4) (GPT-4 Turbo) (Gemini)
```
**关键里程碑**：
| 时间 | 模型 | 窗口大小 | 意义 |
| ---- | ---- | -------- | ---- |
| 2020.06 | GPT-3 | 2K | 首次大规模应用 |
| 2023.03 | GPT-4 | 32K | 长文本处理 |
| 2023.07 | Claude 2 | 100K | 超长上下文 |
| 2024.02 | Gemini 1.5 | 1M | 百万级突破 |
| 2025.02 | Gemini 2.0 | 2M | 当前最大 |
---
## 上下文窗口的作用
### 1. 代码分析
```
项目规模 所需窗口 推荐模型
────────────────────────────────────
单个文件 1K 任意
小型项目 50K-100K Claude, GPT-4
中型项目 200K-500K Gemini 1.5
大型项目 1M+ Gemini 2.0 Pro
全库分析 2M+ Gemini 2.0 Pro (需分块)
```
### 2. 文档处理
| 文档类型 | 长度 | 所需模型 |
| -------- | ---- | -------- |
| 短文章 | <5K tokens | 任意 |
| 长文章 | 20-50K tokens | Claude 3, GPT-4 |
| 书籍 | 100-500K tokens | Gemini 1.5, Claude 3 |
| 法律文档 | 500K-1M tokens | Gemini 2.0 Pro |
### 3. 多轮对话
```
对话轮数 平均Token/轮 总Token 需要模型
────────────────────────────────────────
10轮 500 5K 任意
50轮 500 25K Claude, GPT-4
100轮 500 50K Claude 3
500轮 500 250K Gemini 1.5+
```
---
## 上下文管理技术
### 1. 滑动窗口
```
原始上下文: [A][B][C][D][E][F][G][H][I][J]
窗口大小: 4
步骤1: [A][B][C][D]
步骤2: [B][C][D][E]
步骤3: [C][D][E][F]
步骤4: [D][E][F][G]
...
```
### 2. 重要性采样
```
完整上下文: [A][B][C][D][E][F][G][H][I][J]
重要性: ↑ ↑ ↑ ↑
保留: [A][C][E][G][I]
```
### 3. 分块处理
```
大文档: [==== ==== ==== ==== ==== ====]
↓
分块: [块1][块2][块3][块4][块5][块6]
↓
汇总: [摘要1][摘要2][摘要3][摘要4][摘要5][摘要6]
↓
最终: [综合摘要]
```
### 4. 向量检索 (RAG)
```
用户问题 → 向量化 → 检索相关片段 → 添加到上下文
↓
[系统提示] + [检索片段] + [用户问题]
↓
模型回答
```
---
## 超长上下文技术
### 1. 注意力机制优化
**核心问题**：传统注意力的复杂度是 O(n²)
| 技术 | 复杂度 | 说明 |
| ---- | ------ | ---- |
| **Flash Attention** | O(n²) | 优化内存访问 |
| **Ring Attention** | O(n²) | 块级计算 |
| **Linear Attention** | O(n) | 线性近似 |
### 2. 位置编码
| 技术 | 最大长度 | 说明 |
| ---- | -------- | ---- |
| **绝对位置编码** | 2048 | GPT-3 使用 |
| **相对位置编码** | 8192 | T5 使用 |
| **RoPE (旋转位置)** | ∞ | LLaMA, Gemini 使用 |
| **ALiBi** | ∞ | BLOOM 使用 |
### 3. KV Cache 压缩
```
原始 KV Cache: [==== ==== ==== ==== ====] (占用大量内存)
压缩后: [== == == == ==] (保留关键信息)
```
---
## 上下文窗口的最佳实践
### 1. 选择合适的模型
| 场景 | 推荐模型 | 窗口大小 |
| ---- | -------- | -------- |
| 简单对话 | GPT-4o-mini, Claude Haiku | 128K |
| 代码审查 | Claude Opus 4.5 | 200K |
| 全库分析 | Gemini 2.0 Pro | 2M |
| 文档问答 | Gemini 1.5 Pro | 1M |
### 2. 优化上下文使用
```diff
- 包含整个文件历史
+ 只包含当前修改的部分
- 重复发送相同信息
+ 使用引用或缓存
- 冗长的系统提示
+ 精简有效的提示词
```
### 3. 监控 Token 使用
```python
import anthropic
client = anthropic.Anthropic()
# 检查 Token 使用
response = client.messages.count_tokens(
model="claude-3-opus-20240229",
text="你的内容..."
)
print(f"输入 Token: {response.input_tokens}")
print(f"窗口使用率: {response.input_tokens / 200000 * 100:.1f}%")
```
---
## 上下文窗口的局限性
### 1. 质量下降
当上下文接近窗口上限时，模型可能：
- 遗忘早期信息
- 回答质量下降
- 出现幻觉
### 2. 成本增加
```
Token 数量 ∝ API 成本
```
### 3. 延迟增加
```
上下文长度 → 推理时间
10K tokens → ~2秒
100K tokens → ~10秒
1M tokens → ~60秒+
```
---
## 参考资源
### 论文
- [Transformer-XL](https://arxiv.org/abs/1901.02860) - 超长上下文 Transformer
- [Ring Attention](https://arxiv.org/abs/2310.01889) - 块级注意力
- [MegaByte](https://arxiv.org/abs/2310.05414) - 百万级上下文
### 技术博客
- [Anthropic Context Window](https://www.anthropic.com/index/context-window)
- [Google Gemini 1.5](https://blog.google/technology/ai/google-gemini-next-generation-model-february-2025/)
---
**文档更新时间：2025 年 12 月**
---
## LLMs.txt（LLM 友好文档）
## 概述
**llms.txt** 是一个项目根目录下的文本文件，用于为**大语言模型（LLM）提供项目上下文**。它类似于 `README.md`，但专门为 AI 工具（如 Claude Code、Cursor、Cline）设计，帮助 AI 更好地理解和操作代码库。
> **核心价值**：让 AI 快速理解项目结构、编码规范、技术栈，提供更精准的帮助
---
## llms.txt 的作用
### 1. 为 AI 提供项目上下文
```
传统方式:
AI: "这个项目是做什么的?"
用户: "这是一个小程序项目..."
AI: "使用什么框架?"
用户: "使用原生小程序..."
AI: "有什么编码规范?"
用户: "......"
有了 llms.txt:
AI 直接读取 llms.txt → 自动了解项目信息 → 精准提供帮助
```
### 2. 与 Claude Code CLAUDE.md 的关系
| 文件 | 目标用户 | 内容侧重 |
| ---- | -------- | -------- |
| **llms.txt** | 通用 LLM | 项目概述、技术栈、快速开始 |
| **CLAUDE.md** | Claude Code 专属 | 详细的工作流、命令、最佳实践 |
### 3. 标准 vs 自定义
```
llms.txt (标准)
├── 通用格式
├── 所有 LLM 都能理解
└── 社区标准
自定义命名
├── .cursorrules (Cursor 专属)
├── .clinerules (Cline 专属)
└── project_context.md (自定义)
```
---
## llms.txt 的标准格式
### 推荐结构
```markdown
# 项目名称
## 项目概述
一句话描述项目
## 技术栈
- 框架: ...
- 语言: ...
- 工具: ...
## 项目结构
简短的目录说明
## 快速开始
如何运行项目
## 编码规范
代码风格要求
## 重要说明
其他需要注意的事项
```
---
## llms.txt 模板
### 完整模板
```markdown
# [项目名称]
## 项目概述
[一句话描述项目是做什么的]
## 技术栈
- **框架**: [使用的主要框架]
- **语言**: [主要编程语言]
- **构建工具**: [如 webpack, vite, gulp]
- **测试框架**: [如 vitest, jest]
- **其他工具**: [其他重要依赖]
## 项目结构
```
src/
├── components/ # 组件目录
├── utils/ # 工具函数
├── pages/ # 页面
└── styles/ # 样式文件
```
## 快速开始
### 安装依赖
```bash
pnpm install
```
### 开发模式
```bash npm2yarn
npm run dev
```
### 构建
```bash npm2yarn
npm run build
```
### 测试
```bash npm2yarn
npm test
```
## 编码规范
- 使用 TypeScript 严格模式
- 组件使用函数式声明
- 文件命名使用 kebab-case
- 遵循 ESLint 规则
## 重要说明
- [特殊约定]
- [注意事项]
- [已知问题]
```
### 小程序项目模板
```markdown
# 小程序项目名称
## 项目概述
一个基于原生小程序框架的 [功能描述] 应用
## 技术栈
- **框架**: 原生小程序 (微信/支付宝/抖音)
- **构建**: gulp + weapp-tailwindcss
- **样式**: TailwindCSS (原子化 CSS)
- **语言**: JavaScript / TypeScript
## 项目结构
```
pages/ # 页面目录
├── index/ # 首页
├── profile/ # 个人中心
components/ # 组件目录
utils/ # 工具函数
styles/ # 全局样式
assets/ # 静态资源
```
## 快速开始
```bash
# 安装依赖
pnpm install
# 开发模式 (微信小程序)
pnpm dev:wechat
# 构建
pnpm build
```
## 编码规范
- 组件命名使用 kebab-case
- 页面命名使用 kebab-case
- 样式使用 TailwindCSS 原子类
- 避免使用 id 选择器
## 重要说明
- 使用 weapp-tailwindcss 进行 CSS 转换
- 图片资源需放在 assets/ 目录
- 遵循小程序开发规范
```
### React 项目模板
```markdown
# React 项目名称
## 项目概述
使用 React + TypeScript 构建的 [项目描述]
## 技术栈
- **框架**: React 18+
- **语言**: TypeScript
- **构建**: Vite
- **状态管理**: Zustand / Redux
- **路由**: React Router
- **UI**: TailwindCSS + shadcn/ui
## 项目结构
```
src/
├── components/ # 通用组件
├── pages/ # 页面组件
├── hooks/ # 自定义 Hooks
├── store/ # 状态管理
├── services/ # API 服务
├── types/ # TypeScript 类型
└── utils/ # 工具函数
```
## 快速开始
```bash
pnpm install
pnpm dev
```
## 编码规范
- 组件使用函数式声明 + hooks
- 使用 TypeScript 类型
- 遵循 ESLint + Prettier 规则
```
---
## AI 工具对 llms.txt 的支持
### 1. Claude Code
Claude Code 会**自动读取**项目根目录的 `llms.txt`：
```
项目根目录/
├── llms.txt ← AI 自动读取
├── CLAUDE.md ← Claude Code 专属配置
├── package.json
└── src/
```
### 2. Cursor
Cursor 支持 `llms.txt`，同时也支持 `.cursorrules`：
```diff
+ llms.txt # 通用 LLM 上下文
+ .cursorrules # Cursor 特定规则
```
### 3. Cline
Cline（VS Code 插件）读取 `.clinerules` 或 `llms.txt`：
```
项目根目录/
├── .clinerules ← Cline 配置
├── llms.txt ← 备用
└── src/
```
### 4. 其他工具
| 工具 | 支持的文件 |
| ---- | ---------- |
| **Roo Code** | `roo-rules.txt` |
| **Continue** | `continue_config.json` |
| **Aider** | `.aider.conf.yml` |
---
## llms.txt 最佳实践
### 1. 保持简洁
```markdown
# ❌ 太详细
本项目是一个复杂的企业级应用，包含......（长篇大论）
# ✅ 简洁明确
电商小程序，包含商品展示、购物车、支付功能
```
### 2. 结构化信息
```markdown
# ✅ 使用列表和代码块
## 技术栈
- React 18
- TypeScript
- TailwindCSS
## 命令
```bash
pnpm dev # 开发
pnpm build # 构建
```
```
### 3. 突出重点
```markdown
## 重要约定
1. 所有 API 请求必须经过 services/api.ts
2. 组件必须使用 TypeScript 定义 props
3. 样式只能使用 TailwindCSS 原子类
```
### 4. 保持更新
```markdown
## 最后更新
2025-12-26
## 最近变更
- 迁移到 Vite 6
- 添加 PWA 支持
```
---
## llms.txt 示例
### 示例 1：小程序项目
```markdown
# 小程序商城
## 项目概述
微信小程序商城，支持商品浏览、购物车、微信支付
## 技术栈
- 原生小程序框架
- weapp-tailwindcss (TailwindCSS)
- gulp 构建工具
## 项目结构
```
pages/
├── home/ # 首页
├── category/ # 分类
├── product/ # 商品详情
├── cart/ # 购物车
└── order/ # 订单
components/
├── product-card/ # 商品卡片
├── address-picker/# 地址选择
utils/
├── request.js # API 封装
└── auth.js # 登录认证
```
## 快速开始
```bash
pnpm install
pnpm dev:wechat
```
## 编码规范
- 组件命名: kebab-case
- 样式: TailwindCSS 原子类
- 不使用 id 选择器
- 图片路径使用绝对路径
## API 配置
- 基础 URL: `https://api.example.com`
- 需要登录的接口自动带上 token
## 重要说明
- 使用微信登录获取用户信息
- 支付使用微信支付 API
```
### 示例 2：全栈项目
```markdown
# 全栈任务管理系统
## 项目概述
全栈任务管理应用，包含前端、后端和数据库
## 技术栈
### 前端
- React 18 + TypeScript
- Vite
- TailwindCSS + shadcn/ui
- React Query (TanStack Query)
### 后端
- Node.js + Express
- TypeScript
- Prisma ORM
- PostgreSQL
## 项目结构
```
frontend/ # React 前端
├── src/
│ ├── components/
│ ├── pages/
│ ├── hooks/
│ └── services/
backend/ # Node.js 后端
├── src/
│ ├── routes/
│ ├── services/
│ ├── models/
│ └── middleware/
```
## 快速开始
```bash
# 前端
cd frontend && pnpm dev
# 后端
cd backend && pnpm dev
# 数据库
docker-compose up -d postgres
```
## 编码规范
- 前后端都使用 TypeScript
- API 遵循 RESTful 规范
- 组件使用函数式声明
- 使用 ESLint + Prettier
## 环境变量
```
DATABASE_URL=postgresql://...
JWT_SECRET=your-secret
API_URL=http://localhost:3001
```
```
---
## llms.txt 与 CLAUDE.md 的配合
### 推荐的配置结构
```
项目根目录/
├── llms.txt # AI 通用上下文（所有 LLM）
├── CLAUDE.md # Claude Code 专属配置
├── .cursorrules # Cursor 专属规则（可选）
└── .clinerules # Cline 专属规则（可选）
```
### 内容分工
| 文件 | 内容 |
| ---- | ---- |
| **llms.txt** | 项目概述、技术栈、结构、快速开始 |
| **CLAUDE.md** | Claude 专属工作流、命令、插件配置 |
### llms.txt 示例
```markdown
# 项目名称
## 项目概述
一个 React + Node.js 的全栈应用
## 技术栈
- React 18 + TypeScript
- Node.js + Express
- PostgreSQL
## 快速开始
pnpm install
pnpm dev
```
### CLAUDE.md 示例
```markdown
# Claude Code 配置
## 项目上下文
本项目使用 React + Node.js 全栈架构
## 工作流
1. 新功能先在 frontend/src/ 中创建组件
2. API 变更在 backend/src/routes/ 中修改
3. 运行 pnpm test 验证
## 常用命令
- pnpm dev: 启动开发服务器
- pnpm test: 运行测试
- pnpm lint: 代码检查
## 注意事项
- 前端组件必须使用 TypeScript
- API 路由需要添加认证中间件
```
---
## 参考
### 官方资源
- [llmstxt.org](https://llmstxt.org) - llms.txt 官方网站
- [llms.txt 规范](https://github.com/pydantic/llms.txt)
### 相关文档
- [CLAUDE.md 最佳实践](https://docs.anthropic.com/claude-code/project-knowledge)
- [Cursor Rules](https://cursor.com/docs/rules)
---
**文档更新时间：2025 年 12 月**
---
## MCP (Model Context Protocol)
## 概述
**MCP (Model Context Protocol)** 是一个开放协议，用于连接 AI 助手与系统上下文（数据源、工具、环境）。它由 Anthropic 于 2024 年 11 月发布，旨在解决 AI 应用与外部系统集成的标准化问题。
> **官方文档**：[https://modelcontextprotocol.io](https://modelcontextprotocol.io)
> **GitHub**：[https://github.com/modelcontextprotocol](https://github.com/modelcontextprotocol)
---
## 核心概念
### 1. MCP 的定义
MCP 是一种**客户端-服务端协议**，定义了：
- AI 应用（客户端）如何请求数据和操作
- 数据源/工具（服务端）如何暴露其能力
- 消息传输的标准格式
### 2. 架构组件
```
┌─────────────────────────────────────────────────────────┐
│ MCP 架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ MCP Client │ ───────▶│ MCP Server │ │
│ │ (AI 应用) │ ◀──────│ (数据源) │ │
│ └──────────────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Claude Code │ │ 文件系统 │ │
│ │ Cursor IDE │ │ 数据库 │ │
│ │ Cline │ │ API 服务 │ │
│ │ 自定义应用 │ │ Git 仓库 │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## MCP 的核心能力
### 1. 资源 (Resources)
**资源**是服务端暴露给客户端的**数据读取接口**。
```typescript
// 资源示例
{
"uri": "file:///Users/project/README.md",
"name": "项目 README",
"description": "项目根目录的 README 文件",
"mimeType": "text/markdown"
}
```
**常见资源类型**：
| 类型 | URI 示例 | 说明 |
| ---- | -------- | ---- |
| 文件 | `file:///path/to/file` | 本地文件系统 |
| Git | `git:///repo/file` | Git 仓库内容 |
| 数据库 | `postgres://query` | 数据库查询结果 |
| API | `https://api/data` | HTTP API 响应 |
| 内存 | `memory://variable` | 运行时数据 |
### 2. 提示词模板 (Prompts)
**提示词模板**是服务端提供的**预定义提示词**。
```typescript
// 提示词模板示例
{
"name": "code-review",
"description": "代码审查提示词",
"arguments": {
"file": "要审查的文件路径",
"focus": "审查重点（安全/性能/风格）"
}
}
```
### 3. 工具 (Tools)
**工具**是服务端暴露的**可执行功能**。
```typescript
// 工具示例
{
"name": "execute_command",
"description": "在终端执行命令",
"inputSchema": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "要执行的命令"
}
}
}
}
```
---
## MCP 传输层
MCP 支持多种传输方式：
### 1. STDIO（标准输入/输出）
适用于**本地进程间通信**：
```bash
# 通过 STDIO 启动 MCP 服务端
claude-code mcp install my-server
my-server --stdio
```
### 2. SSE（Server-Sent Events）
适用于**本地 HTTP 通信**：
```typescript
// SSE 连接
const client = new MCPClient({
url: "http://localhost:3000/sse",
transport: "sse"
});
```
### 3. 自定义传输
支持自定义 WebSocket、gRPC 等传输层。
---
## 使用场景
### 1. Claude Code 中的 MCP
Claude Code 原生支持 MCP，可以：
- 通过 MCP 读取项目文件
- 通过 MCP 执行 Git 命令
- 通过 MCP 访问数据库
- 通过 MCP 调用外部 API
**配置示例**：
```json
// .claude/mcp_config.json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/project"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}
```
### 2. Cursor IDE 中的 MCP
Cursor 支持 MCP 扩展：
- 安装 MCP 兼容的服务端
- Cursor 自动发现可用资源
- 在 Chat 中引用 MCP 资源
### 3. Cline 中的 MCP
Cline（VS Code 插件）支持 MCP：
- 通过 MCP 获取项目上下文
- 通过 MCP 执行构建命令
- 通过 MCP 访问测试结果
---
## MCP 服务端示例
### 文件系统服务端
```bash
# 官方文件系统服务端
npx -y @modelcontextprotocol/server-filesystem /path/to/directory
```
### GitHub 服务端
```bash
# 官方 GitHub 服务端
npx -y @modelcontextprotocol/server-github
```
### 数据库服务端
```bash
# PostgreSQL 服务端
npx -y @modelcontextprotocol/server-postgres "postgresql://..."
```
### 自定义服务端
```typescript
// 自定义 MCP 服务端
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = new Server({
name: 'my-custom-server',
version: '1.0.0'
});
// 添加资源
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
resources: [
{
uri: 'custom://data',
name: '自定义数据',
description: '我的自定义数据源'
}
]
}));
// 启动服务端
const transport = new StdioServerTransport();
await server.connect(transport);
```
---
## MCP 的优势
| 优势 | 说明 |
| ---- | ---- |
| **标准化** | 统一的协议，无需为每个 AI 应用单独适配 |
| **模块化** | 数据源独立于 AI 应用，可复用 |
| **可扩展** | 支持自定义传输层和数据源 |
| **安全性** | 明确的权限控制和数据隔离 |
| **开放性** | 开源协议，社区驱动发展 |
---
## MCP 与其他方案的对比
| 方案 | MCP | LangChain Tools | OpenAI Function Calling |
| ---- | --- | --------------- | ---------------------- |
| **标准化程度** | ✅ 开放协议 | ❌ 厂商特定 | ❌ 厂商特定 |
| **传输层** | 多种支持 | HTTP/RPC | HTTP |
| **AI 兼容性** | 多模型 | 主流 LLM | OpenAI only |
| **社区生态** | 快速增长 | 成熟 | 成熟 |
| **学习曲线** | 简单 | 中等 | 简单 |
---
## 快速开始
### 1. 安装 Claude Code MCP 集成
```bash
# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code
# 初始化 MCP 配置
claude-code mcp init
```
### 2. 添加 MCP 服务端
```bash
# 添加文件系统服务端
claude-code mcp install @modelcontextprotocol/server-filesystem
# 添加 GitHub 服务端
claude-code mcp install @modelcontextprotocol/server-github
```
### 3. 在 Claude Code 中使用
```
@mcp://filesystem/Users/project/src 请分析这个目录下的代码结构
```
---
## 参考资源
### 官方资源
- [MCP 官方网站](https://modelcontextprotocol.io)
- [MCP GitHub](https://github.com/modelcontextprotocol)
- [MCP SDK 文档](https://modelcontextprotocol.io/sdk)
### 社区资源
- [MCP 服务端列表](https://github.com/modelcontextprotocol/servers)
- [MCP 客户端列表](https://github.com/modelcontextprotocol/clients)
- [Claude Code MCP 文档](https://docs.anthropic.com/claude-code/mcp)
---
**文档更新时间：2025 年 12 月**
---
## Power（规范驱动编程）
# Power（规范驱动编程能力）
## 概述
**Power** 是由 **Kiro** 提出的一个概念，用于衡量 **AI 工具理解复杂规范并生成符合规范代码的能力**。在 Spec-Driven Development（规范驱动开发）的语境下，Power 指的是 AI 将非结构化的需求描述转换为结构化的技术规范，并最终生成可执行代码的能力。
> **核心理念**：Power = 规范理解能力 × 代码生成能力 × 约束遵循能力
---
## Power 的定义
### 1. 基本概念
**Power** 是 AI 编程工具的核心能力指标：
```
┌─────────────────────────────────────────────────────────┐
│ Power 的构成 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 规范理解 (Spec Understanding) │ │
│ │ 理解自然语言需求 → 结构化规范 │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 规范生成 (Spec Generation) │ │
│ │ 生成 API、数据模型、UI 规范 │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 代码实现 (Code Implementation) │ │
│ │ 根据规范生成符合要求的代码 │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 约束遵循 (Constraint Adherence) │ │
│ │ 遵循编码规范、技术约束、业务规则 │ │
│ └──────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### 2. Power 的维度
| 维度 | 说明 | 评估标准 |
| ---- | ---- | -------- |
| **理解力** | 理解复杂需求的能力 | 能否准确提取关键信息 |
| **结构化** | 生成结构化规范的能力 | 规范是否完整、一致 |
| **实现力** | 生成可执行代码的能力 | 代码是否可用、正确 |
| **遵循力** | 遵循约束的能力 | 是否符合规范要求 |
| **一致性** | 多次输出的稳定性 | 相同输入是否得到相似结果 |
---
## Power 的级别
### Level 0: 无规范能力
```
特征:
- 无法理解结构化需求
- 只能处理简单指令
- 生成代码需要大量人工修改
示例:
输入: "写个登录"
输出: [基础代码，但缺类型、验证、错误处理]
```
### Level 1: 基础规范理解
```
特征:
- 能理解简单的结构化需求
- 能生成基本的代码框架
- 需要人工补充细节
示例:
输入: "用 React + TypeScript 写登录，包含邮箱和密码"
输出: [带类型的组件，但可能缺验证逻辑]
```
### Level 2: 中级规范能力
```
特征:
- 能理解多层级规范
- 能生成完整的 API 规范
- 代码基本可用，需少量调整
示例:
输入: "用户登录功能，需验证、错误处理、JWT"
输出: [完整的登录流程，含前后端]
```
### Level 3: 高级规范能力
```
特征:
- 能理解复杂的业务规范
- 能生成前后端联调代码
- 包含测试和文档
示例:
输入: "完整的用户认证系统（注册、登录、登出、权限）"
输出: [全栈代码 + API 文档 + 测试用例]
```
### Level 4: 专家级规范能力
```
特征:
- 能理解企业级规范
- 自动处理边界情况和异常
- 生成生产级代码
示例:
输入: "电商订单系统（含支付、库存、物流、退款）"
输出: [微服务架构 + 数据库设计 + 完整实现]
```
---
## Power 的评估
### 1. 评估维度
```markdown
## Power 评估卡
### 需求理解
- [ ] 能识别核心功能
- [ ] 能识别非功能需求（性能、安全）
- [ ] 能识别依赖和约束
- [ ] 能识别边界条件
### 规范生成
- [ ] API 规范完整性
- [ ] 数据模型合理性
- [ ] 错误处理覆盖
- [ ] 验证规则完整
### 代码质量
- [ ] 语法正确性
- [ ] 类型安全性
- [ ] 代码可读性
- [ ] 最佳实践遵循
### 约束遵循
- [ ] 技术栈约束
- [ ] 编码规范约束
- [ ] 业务规则约束
- [ ] 性能约束
```
### 2. 评分标准
| 分数 | 描述 |
| ---- | ---- |
| **0-20** | 几乎无法理解规范 |
| **20-40** | 能理解简单规范，代码需大量修改 |
| **40-60** | 能理解中等规范，代码需少量修改 |
| **60-80** | 能理解复杂规范，代码基本可用 |
| **80-100** | 完全理解规范，生成生产级代码 |
### 3. 自动化评估
```python
# Power 评估脚本示例
def evaluate_power(ai_tool, test_cases):
scores = []
for case in test_cases:
# 生成规范
spec = ai_tool.generate_spec(case.requirement)
# 生成代码
code = ai_tool.generate_code(spec)
# 评估
score = {
"spec_completeness": check_spec_completeness(spec, case),
"code_correctness": check_code_correctness(code),
"constraint_adherence": check_constraints(code, case.constraints),
"test_pass_rate": run_tests(code, case.tests)
}
scores.append(score)
return aggregate_scores(scores)
```
---
## Power 在不同工具中的体现
### 1. Cursor Composer
Cursor 的 **Composer** 特性：
```
特点:
├── 自动规划任务步骤
├── 跨文件代码生成
├── 上下文感知
└── 迭代优化
Power 水平: Level 2-3
```
### 2. Claude Code
Claude Code 的 **Plan Mode**：
```
特点:
├── 深度代码理解
├── 分步实施计划
├── 人工确认机制
└── 详细说明
Power 水平: Level 3
```
### 3. GitHub Copilot Workspace
Copilot 的 **Workspace**：
```
特点:
├── Issue → Spec → Code 流程
├── 测试生成
├── Pull Request 描述
└── 迭代改进
Power 水平: Level 2-3
```
---
## 提升 Power 的技巧
### 1. 编写更好的规范
#### 使用结构化格式
```markdown
# ❌ 模糊的规范
"做一个用户管理功能"
# ✅ 结构化的规范
## 功能：用户管理
### 需求
- 用户列表（分页、搜索）
- 用户详情
- 创建用户
- 编辑用户
- 删除用户（软删除）
### 字段定义
- id: UUID
- name: 字符串，2-50字符
- email: 邮箱格式，唯一
- role: 枚举（admin, user, guest）
- status: 枚举（active, inactive）
- created_at: 时间戳
### 验证规则
- name 必填
- email 唯一
- role 默认为 user
### API 设计
GET /api/users # 列表
GET /api/users/:id # 详情
POST /api/users # 创建
PUT /api/users/:id # 更新
DELETE /api/users/:id # 删除
### 技术要求
- React + TypeScript
- RESTful API
- 使用 Prisma ORM
```
### 2. 使用模板
```markdown
# 功能规范模板
## 功能概述
[一句话描述]
## 用户故事
作为 [角色]，我想要 [功能]，以便 [目的]
## 验收标准
- [ ] 标准1
- [ ] 标准2
## 技术规范
### 数据模型
### API 接口
### UI 规范
## 非功能需求
### 性能
### 安全
### 兼容性
```
### 3. 渐进式规范
```
第一版（粗略）:
"用户登录功能"
第二版（添加细节）:
"用户登录，邮箱和密码，需要验证"
第三版（完整规范）:
[完整的功能规范，含所有细节]
第四版（迭代优化）:
[基于反馈的优化版本]
```
### 4. 提供示例
```
# 在规范中添加示例
## 输入示例
{
"email": "user@example.com",
"password": "SecurePass123"
}
## 输出示例
成功（200）:
{
"success": true,
"token": "eyJhbGc...",
"user": {...}
}
失败（401）:
{
"success": false,
"error": "Invalid credentials"
}
```
---
## Power 的局限
### 1. 复杂业务逻辑
```
问题: AI 难以理解复杂的业务规则
解决:
- 分解为多个小功能
- 提供详细规则说明
- 添加决策树/流程图
```
### 2. 隐性知识
```
问题: AI 无法获取团队隐性知识
解决:
- 使用 llms.txt/CLAUDE.md
- 维护项目规范文档
- 建立代码示例库
```
### 3. 上下文限制
```
问题: 大型项目规范超出上下文窗口
解决:
- 分模块编写规范
- 使用 RAG 检索相关规范
- 建立规范层次结构
```
---
## Power 与 Spec-Driven Development
### 关系
```
┌─────────────────────────────────────────────────────────┐
│ Power 在 SDD 中的作用 │
├─────────────────────────────────────────────────────────┤
│ │
│ Spec-Driven Development 流程: │
│ │
│ 1. 需求 → 规范 │
│ └── Power 决定转换质量 │
│ │
│ 2. 规范 → 代码 (Spec → Code) │
│ └── Power 决定代码质量 │
│ │
│ 3. 代码 → 测试 (Code → Test) │
│ └── Power 影响测试覆盖 │
│ │
│ 结论: Power 越高，SDD 效率越高 │
│ │
└─────────────────────────────────────────────────────────┘
```
### 最佳实践
1. **高 Power 工具 + 完整规范** = 最佳效果
2. **低 Power 工具 + 简单规范** = 基础自动化
3. **高 Power 工具 + 简单规范** = 过度设计
4. **低 Power 工具 + 复杂规范** = 效果有限
---
## Power 的发展趋势
### 当前状态 (2025)
```
Level 1-2: 主流
- 大多数 AI 编码工具处于这个水平
- 适合简单到中等复杂度任务
Level 3: 先进
- 少数工具达到
- 需要良好的规范编写
Level 4: 探索
- 研究阶段
- 需要更强的模型和更好的工具支持
```
### 未来方向
```
┌─────────────────────────────────────────────────────────┐
│ Power 的未来 │
├─────────────────────────────────────────────────────────┤
│ │
│ 短期（1-2年） │
│ ├── 更好的规范理解 │
│ ├── 更准确的代码生成 │
│ └── 更强的约束遵循 │
│ │
│ 中期（2-3年） │
│ ├── 自动化规范生成 │
│ ├── 规范版本管理 │
│ └── 团队协作支持 │
│ │
│ 长期（3-5年） │
│ ├── 自演进规范 │
│ ├── 跨项目规范复用 │
│ └── 规范市场/交换 │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## 参考资源
### 相关文档
- [Spec-Driven Development](./spec-driven-development)
- [Vibe Coding](./vibe-coding)
- [Prompt Engineering](./prompt-engineering)
### 工具
- [Cursor](https://cursor.sh) - Composer 功能
- [Claude Code](https://claude.ai/code) - Plan Mode
---
**文档更新时间：2025 年 12 月**
---
## Prompt Engineering（提示词工程）
## 概述
**Prompt（提示词）** 是用户输入给大语言模型的**指令或问题**。**Prompt Engineering（提示词工程）** 是设计和优化提示词以获得更好输出结果的技术。
> **核心原则**：好的提示词 = 清晰、具体、有结构
---
## 什么是提示词
### 1. 基本定义
**提示词** 是与 AI 交互的文本输入：
```
用户输入: "帮我写一个快速排序算法"
↑
这就是 Prompt
```
### 2. 提示词的组成部分
```
┌─────────────────────────────────────────────────────────┐
│ 提示词结构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 角色/身份设定 │ │
│ │ "你是一个资深前端工程师..." │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 任务描述 │ │
│ │ "帮我实现一个登录表单..." │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 上下文/背景信息 │ │
│ │ "使用 React + TypeScript..." │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 约束/要求 │ │
│ │ "使用 shadcn/ui 组件，遵循以下规范..." │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 输出格式 │ │
│ │ "以 Markdown 格式输出，包含代码块..." │ │
│ └──────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 示例/参考 │ │
│ │ "参考以下代码风格..." │ │
│ └──────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## 好的提示词原则
### CREATE 框架
| 原则 | 说明 | 示例 |
| ---- | ---- | ---- |
| **C**lear | 清晰明确 | "用 Python 写一个冒泡排序" |
| **R**ole | 设定角色 | "你是一个资深前端工程师" |
| **E**xact | 精确具体 | "生成 10 个随机整数，范围 1-100" |
| **A**udience | 明确受众 | "向初学者解释闭包的概念" |
| **T**one | 设定语气 | "用专业但友好的语气" |
| **E**xample | 提供示例 | "参考以下代码风格" |
---
## 好的提示词 vs 差的提示词
### 示例 1：代码生成
#### ❌ 差的提示词
```
写一个登录功能
```
**问题**：
- 没有指定技术栈
- 没有说明需求细节
- 没有定义输入输出
#### ✅ 好的提示词
```
你是一个资深前端工程师。请帮我创建一个 React + TypeScript 的登录表单组件：
需求：
1. 包含邮箱和密码输入框
2. 使用 shadcn/ui 组件库
3. 支持表单验证（邮箱格式、密码最少8位）
4. 包含"记住我"复选框
5. 登录按钮在加载时显示 Loading 状态
6. 使用 TypeScript 定义类型
请提供完整的组件代码和类型定义。
```
---
### 示例 2：Bug 修复
#### ❌ 差的提示词
```
这段代码有问题，帮我看看
```
**问题**：
- 没有说明具体问题
- 没有提供错误信息
- 没有说明期望行为
#### ✅ 好的提示词
```
我的 React 组件有问题，需要你帮忙排查：
问题描述：
点击"提交"按钮后，表单没有提交，也没有任何提示
代码：
```tsx
function SubmitForm() {
const handleSubmit = () => {
console.log('Form submitted')
}
return
}
```
期望行为：
点击按钮后应该显示"提交成功"的提示
请分析问题并给出修复后的代码。
```
---
### 示例 3：代码重构
#### ❌ 差的提示词
```
优化这段代码
```
**问题**：
- 没有说明优化目标
- 没有说明约束条件
- 没有说明优先级
#### ✅ 好的提示词
```
请帮我优化以下代码，目标是提升可读性和性能：
代码：
```typescript
const getUserData = async (id: string) => {
const user = await fetchUser(id)
const posts = await fetchPosts(user.id)
const comments = await fetchComments(posts.map(p => p.id))
return { user, posts, comments }
}
```
优化要求：
1. 减少不必要的等待（并行处理）
2. 添加错误处理
3. 添加 TypeScript 类型
4. 保持函数命名清晰
请提供优化后的代码和改动说明。
```
---
### 示例 4：文档编写
#### ❌ 差的提示词
```
帮我写个文档
```
#### ✅ 好的提示词
```
请为以下函数编写 API 文档：
函数：
```typescript
async function createUser(data: {
email: string
password: string
name: string
}): Promise<{id: string; email: string}>
```
文档格式：
- 函数描述
- 参数说明（类型、是否必填）
- 返回值说明
- 使用示例
- 可能抛出的错误
使用 Markdown 格式输出。
```
---
### 示例 5：代码审查
#### ❌ 差的提示词
```
审查这段代码
```
#### ✅ 好的提示词
```
请作为代码审查专家，审查以下 React 组件：
审查重点：
1. 类型安全性
2. 性能问题（不必要的重渲染）
3. 错误处理
4. 代码可读性
5. 最佳实践遵循情况
代码：
```tsx
import { useState, useEffect } from 'react'
export function UserProfile({ userId }: { userId: string }) {
const [user, setUser] = useState(null)
const [posts, setPosts] = useState([])
useEffect(() => {
fetchUser(userId).then(setUser)
fetchUserPosts(userId).then(setPosts)
}, [userId])
if (!user) return Loading...
return (
{user.name}
{posts.map(p => - {p.title}
)}
)
}
```
请以列表形式输出：
- 发现的问题
- 严重程度（高/中/低）
- 修复建议
```
---
## 高级提示词技巧
### 1. Few-Shot Prompting（少样本提示）
提供示例帮助 AI 理解期望：
```
请将以下自然语言转换为 SQL 查询语句。
示例1：
输入：查找所有姓张的用户
输出：SELECT * FROM users WHERE name LIKE '张%'
示例2：
输入：查找年龄大于25的用户
输出：SELECT * FROM users WHERE age > 25
示例3：
输入：查找今年注册的用户
输出：SELECT * FROM users WHERE YEAR(created_at) = YEAR(CURDATE())
现在请转换：
输入：查找所有状态为"活跃"且注册时间在2024年之后的用户
输出：
```
### 2. Chain of Thought（思维链）
引导 AI 展示推理过程：
```
请使用逐步推理的方式解决以下问题：
问题：如果一个数列的前三项是 2, 6, 18，求第四项。
推理过程：
1. 观察相邻两项的关系
2. 计算比例关系
3. 验证规律
4. 应用规律求解
请按照以上步骤逐步推理并给出答案。
```
### 3. 角色设定
```
你是一个有 10 年经验的前端工程师，擅长 React 和 TypeScript。
你熟悉各种设计模式和最佳实践。
你的回答应该专业、准确，并包含实用的代码示例。
```
### 4. 结构化输出
```
请以以下格式输出：
## 问题描述
[问题简述]
## 根本原因
[根本原因分析]
## 解决方案
### 选项1
[方案描述]
优点：...
缺点：...
### 选项2
[方案描述]
优点：...
缺点：...
## 推荐
[推荐方案及理由]
## 代码示例
```typescript
[代码]
```
```
### 5. 约束和边界
```
请生成一个随机密码生成函数。
约束条件：
- 密码长度：16-32 位（可配置）
- 必须包含：大写字母、小写字母、数字、特殊字符
- 不能包含容易混淆的字符（如 l, 1, O, 0）
- 使用 TypeScript 实现
请不要使用任何外部库。
```
---
## 常见提示词模板
### 代码生成模板
```
你是一个{语言/框架}专家。
请帮我实现以下功能：
{功能描述}
技术要求：
- 框架：{框架名称}
- 语言：{编程语言}
- 样式：{CSS方案}
- 状态管理：{状态方案}
功能需求：
{详细需求列表}
请提供：
1. 完整的代码实现
2. 必要的说明注释
3. 使用示例
代码风格：
{风格要求}
```
### Bug 修复模板
```
我遇到了一个问题，需要你帮忙解决：
**问题描述**
{问题描述}
**错误信息**
```
{错误日志}
```
**相关代码**
```{language}
{代码}
```
**环境信息**
- 框架：{框架和版本}
- 运行环境：{浏览器/Node版本}
- 构建工具：{webpack/vite等}
**已尝试的解决方案**
{尝试过的方案}
请分析问题原因并提供修复方案。
```
### 代码审查模板
```
请审查以下代码：
**审查重点**
{审查重点列表}
**代码**
```{language}
{代码}
```
**上下文**
{相关背景信息}
请输出：
1. 发现的问题
2. 风险评估
3. 改进建议
```
### 重构建议模板
```
请分析以下代码并提供重构建议：
```{language}
{代码}
```
重构目标：
{目标：如提升性能、提高可读性、降低复杂度}
约束条件：
{约束：如保持 API 不变、不引入新依赖}
请提供：
1. 当前代码的问题分析
2. 重构后的代码
3. 改动说明
```
---
## 提示词反模式
### ❌ 需要避免的模式
| 反模式 | 问题 | 改进 |
| ------ | ---- | ---- |
| **模糊指令** | "帮我优化" | "优化性能，减少 50% 响应时间" |
| **过多信息** | 冗长的背景描述 | 提取关键信息 |
| **矛盾要求** | "简单但功能全" | 明确优先级 |
| **缺少上下文** | "这个函数怎么改" | 提供完整代码和目的 |
| **假设过多** | "你应该知道..." | 明确说明所有信息 |
### ✅ 良好模式
| 模式 | 说明 |
| ---- | ---- |
| **明确目标** | 清晰说明想要什么 |
| **提供上下文** | 给出必要的背景信息 |
| **结构清晰** | 使用分段和列表 |
| **具体约束** | 明确限制和要求 |
| **示例引导** | 用示例说明期望 |
---
## 针对不同场景的提示词
### 1. 前端开发
```
请创建一个 React + TypeScript 的用户列表组件：
需求：
- 使用 TypeScript 定义 User 类型：{ id, name, email, avatar }
- 使用 shadcn/ui 的 Table 组件展示用户列表
- 支持分页（每页 10 条）
- 支持按姓名搜索
- 点击行可查看用户详情
API 接口：GET /api/users?page=1&limit=10&search=keyword
返回格式：{ data: User[], total: number }
请提供完整组件代码和必要的类型定义。
```
### 2. 后端开发
```
请用 Node.js + Express 创建一个用户认证 API：
需求：
- POST /api/auth/register - 用户注册
- POST /api/auth/login - 用户登录
- POST /api/auth/logout - 用户登出
- GET /api/auth/me - 获取当前用户信息
技术要求：
- 使用 TypeScript
- 使用 Prisma ORM
- 使用 JWT 进行认证
- 密码使用 bcrypt 加密
- 数据库使用 PostgreSQL
数据模型（User）：
- id: UUID
- email: 唯一
- password: 加密存储
- name: 用户名
- createdAt: 创建时间
请提供完整的路由、控制器和中间件代码。
```
### 3. 数据分析
```
请帮我分析以下数据：
销售数据：
```
月份,Q1,Q2,Q3,Q4
产品A,120,150,180,200
产品B,80,90,100,110
产品C,200,180,150,120
```
请提供：
1. 季度增长趋势分析
2. 产品表现对比
3. 潜在问题识别
4. 改进建议
使用 Markdown 格式输出，包含数据可视化建议。
```
### 4. 文档生成
```
请为以下 API 生成 Swagger/OpenAPI 文档：
API 端点：POST /api/users
请求体：
{
"email": "string (required, email format)",
"password": "string (required, minLength: 8)",
"name": "string (required)"
}
成功响应（201）：
{
"id": "uuid",
"email": "string",
"name": "string",
"createdAt": "datetime"
}
错误响应：
- 400: 参数验证失败
- 409: 邮箱已存在
请生成完整的 OpenAPI 3.0 规范（YAML 格式）。
```
---
## 提示词迭代优化
### 迭代流程
```
第一版（基础版）
"写一个登录功能"
↓
❌ 结果不符合预期
↓
第二版（添加细节）
"用 React 写一个登录表单，包含邮箱和密码"
↓
⚠️ 接近了，但还不完美
↓
第三版（精细化）
"请创建一个 React + TypeScript 登录表单，使用 shadcn/ui..."
↓
✅ 满意
```
### 迭代技巧
1. **从简单开始**：先给基础版本
2. **逐步添加细节**：一次只加一个要求
3. **观察输出**：分析不符合预期的部分
4. **针对性修正**：指出具体问题
5. **验证结果**：确认是否满足需求
---
## 参考资源
### 官方文档
- [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)
- [Anthropic Prompt Library](https://docs.anthropic.com/prompt-library)
- [Google Prompting Guide](https://ai.google.dev/gemini-api/prompting-strategies)
### 学习资源
- [Learn Prompting](https://learnprompting.org/)
- [Prompt Engineering Guide](https://www.promptingguide.ai/)
### 社区资源
- [Awesome Prompt Engineering](https://github.com/f/awesome-prompt-engineering)
- [Prompt Examples](https://github.com/matthew-burrell/prompt-examples)
---
**文档更新时间：2025 年 12 月**
---
## RAG（检索增强生成）
## 概述
**RAG (Retrieval-Augmented Generation)** 是一种结合了**信息检索（Retrieval）**和**生成式AI（Generation）**的技术架构。它让大语言模型在生成回答时，能够先从外部知识库中检索相关信息，然后基于检索到的内容生成更准确、更及时的回答。
> **核心价值**：解决 LLM 的知识滞后和幻觉问题，让 AI 拥有"外挂知识库"
---
## RAG 的核心概念
### 1. 为什么需要 RAG
```
纯 LLM 的问题:
├── 知识截止：训练数据有时间边界
├── 幻觉问题：可能生成不准确的内容
├── 领域知识：缺乏专业领域的私有数据
└── 可追溯性：无法验证信息来源
RAG 的解决:
├── 实时知识：可检索最新信息
├── 准确性：基于真实文档生成
├── 私有数据：可接入企业内部知识
└── 可验证：提供信息来源引用
```
### 2. RAG vs Fine-tuning
| 维度 | RAG | Fine-tuning（微调） |
| ---- | --- | ------------------- |
| **知识更新** | 实时更新 | 需要重新训练 |
| **数据来源** | 外部知识库 | 模型权重 |
| **实施成本** | 低 | 高 |
| **幻觉控制** | 好 | 中 |
| **领域适应** | 快速适应 | 需要训练数据 |
| **隐私安全** | 数据不进入模型 | 数据融入模型 |
| **适用场景** | 知识查询、问答 | 风格适应、格式化 |
---
## RAG 的工作原理
### 1. 基本流程
```
┌─────────────────────────────────────────────────────────────────┐
│ RAG 工作流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 用户问题 │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 向量化 (Embedding) │ │
│ │ 问题 → 向量 │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 相似度检索 │ │
│ │ 在向量库中搜索 │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 获取相关文档 │ │
│ │ Top-K 结果 │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Prompt 构建 │ │
│ │ 问题 + 文档上下文│ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ LLM 生成回答 │ │
│ │ 基于检索内容 │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ 带引用的回答 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 2. 关键组件
#### 向量嵌入 (Embedding)
```
文本: "人工智能是计算机科学的一个分支"
│
▼
向量化模型 (如 OpenAI Embeddings)
│
▼
向量: [0.123, -0.456, 0.789, ...] (1536 维)
```
#### 向量数据库 (Vector Database)
| 数据库 | 特点 |
| ------ | ---- |
| **Pinecone** | 托管服务，易用 |
| **Chroma** | 轻量级，本地部署 |
| **Qdrant** | 高性能，开源 |
| **Milvus** | 企业级，可扩展 |
| **Weaviate** | 支持多种数据类型 |
#### 相似度计算
```python
# 余弦相似度
similarity = cosine_similarity(query_vector, document_vector)
# 欧氏距离
distance = euclidean_distance(query_vector, document_vector)
```
---
## RAG 的实现方式
### 1. Naive RAG（基础 RAG）
最简单的 RAG 实现：
```python
# 伪代码
def naive_rag(query):
# 1. 向量化查询
query_vector = embedding_model.encode(query)
# 2. 检索相关文档
docs = vector_db.search(query_vector, top_k=5)
# 3. 构建 Prompt
prompt = f"""
基于以下文档回答问题：
{docs}
问题：{query}
"""
# 4. 生成回答
answer = llm.generate(prompt)
return answer
```
### 2. Advanced RAG（高级 RAG）
包含更多优化技术：
```
┌─────────────────────────────────────────────────────────┐
│ Advanced RAG │
├─────────────────────────────────────────────────────────┤
│ │
│ 查询理解 │
│ ├── 查询重写 (Query Rewriting) │
│ ├── 查询扩展 (Query Expansion) │
│ ├── 查路由 (Query Routing) │
│ └── 多重查询 (Multi-Query) │
│ ↓ │
│ 混合检索 │
│ ├── 向量检索 (Semantic Search) │
│ ├── 关键词检索 (Keyword Search) │
│ └── 结果融合 (Result Fusion) │
│ ↓ │
│ 重排序 (Reranking) │
│ └── 使用更精细的模型重新排序 │
│ ↓ │
│ 上下文管理 │
│ ├── 长上下文压缩 │
│ └── 动态选择相关片段 │
│ ↓ │
│ 生成回答 │
│ │
└─────────────────────────────────────────────────────────┘
```
### 3. Modular RAG（模块化 RAG）
可灵活组合的 RAG 模块：
```
RAG 模块:
├── 检索模块
│ ├── 单路检索
│ ├── 递归检索
│ └── 混合检索
├── 生成模块
│ ├── 单次生成
│ ├── 迭代生成
│ └── 分步生成
└── 优化模块
├── 查询优化
├── 文档优化
└── 结果优化
```
---
## RAG 的优化技术
### 1. 查询优化
#### 查询重写
```python
# 原始查询
"怎么用这个功能"
# 重写后
"如何使用 [产品名称] 的 [具体功能名称]？"
```
#### 多重查询
```python
# 生成多个查询变体
query_variants = [
"人工智能的发展历史",
"AI 发展历程",
"机器学习和深度学习的起源"
]
# 并行检索后合并结果
```
#### 查询路由
```python
def route_query(query):
if is_code_question(query):
return "code_kb_index"
elif is_business_question(query):
return "business_kb_index"
else:
return "general_kb_index"
```
### 2. 文档优化
#### 分块策略 (Chunking)
```python
# 固定大小分块
chunk_size = 512
overlap = 50
# 语义分块（按段落、章节）
chunks = split_by_semantic_unit(document)
# 递归分块
chunks = recursive_split(document, max_length=1000)
```
#### 元数据增强
```python
{
"content": "文档内容...",
"metadata": {
"source": "user_manual.pdf",
"page": 15,
"chapter": "安装指南",
"last_updated": "2024-01-15",
"author": "技术文档团队"
}
}
```
### 3. 检索优化
#### 混合检索
```python
# 结合向量检索和关键词检索
vector_results = vector_search(query, top_k=10)
keyword_results = bm25_search(query, top_k=10)
# 结果融合
final_results = reciprocal_rank_fusion(vector_results, keyword_results)
```
#### 重排序 (Reranking)
```python
# 初步检索
initial_results = vector_db.search(query, top_k=50)
# 使用更强的模型重排序
reranker = CrossEncoderReranker()
final_results = reranker.rerank(query, initial_results, top_k=10)
```
### 4. 生成优化
#### 引用生成
```markdown
根据以下内容回答，并标注引用来源：
[文档1] 我们app支持 iOS 和 Android...
[文档2] 安装包大小约为 50MB...
[文档3] 需要注册账户才能使用...
问题：这个应用支持哪些平台？
回答：该应用支持 iOS 和 Android 平台 [1]。
```
#### 自我修正 (Self-RAG)
```
生成回答 → 检查相关性 → 检查支持性 →
如果不相关/不支持 → 重新检索 → 重新生成
```
---
## RAG 的应用场景
### 1. 企业知识库
```
员工: "公司的报销流程是什么？"
↓
RAG: [从员工手册、OA系统文档中检索]
↓
回答: "根据《员工手册》第5章，
报销流程如下：1.提交申请 2.主管审批..."
来源: employee-handbook.pdf, page 23
```
### 2. 客户服务
```
客户: "产品如何保修？"
↓
RAG: [从产品手册、售后政策中检索]
↓
回答: "本产品提供2年质保，
保修范围包括..."
来源: warranty-policy.html
```
### 3. 代码助手
```
开发者: "这个项目怎么用 Webpack 构建？"
↓
RAG: [从项目 README、文档中检索]
↓
回答: "根据项目文档，
运行 pnpm build 即可..."
来源: README.md, docs/build.md
```
### 4. 技术文档问答
```
用户: "TailwindCSS 怎么在小程序中使用？"
↓
RAG: [从 weapp-tailwindcss 文档中检索]
↓
回答: "在 weapp-tailwindcss 中，
配置 postcss.config.js..."
来源: docs/getting-started.md
```
---
## RAG 的评估指标
### 1. 检索质量
| 指标 | 说明 |
| ---- | ---- |
| **Precision@K** | 前K个结果中有多少是相关的 |
| **Recall@K** | 所有相关文档中检索到了多少 |
| **MRR** | 第一个相关结果的倒数排名 |
| **NDCG** | 考虑位置的相关性评分 |
### 2. 生成质量
| 指标 | 说明 |
| ---- | ---- |
| **Faithfulness** | 回答是否与检索内容一致 |
| **Answer Relevance** | 回答是否解决了问题 |
| **Context Precision** | 检索的上下文是否相关 |
| **Context Recall** | 是否检索到了所有必要信息 |
### 3. 端到端评估
```python
# RAG 评估框架示例
from ragas import evaluate
results = evaluate(
dataset=test_dataset,
metrics=[
"faithfulness",
"answer_relevancy",
"context_precision",
"context_recall"
]
)
```
---
## RAG 的常见问题
### 1. 检索不到相关内容
**原因**：
- 向量质量差
- 分块策略不当
- 知识库内容缺失
**解决**：
- 使用更好的 Embedding 模型
- 调整分块大小和重叠
- 补充知识库内容
- 使用混合检索
### 2. 回答不准确
**原因**：
- 检索内容不相关
- 上下文过长导致注意力分散
- 模型理解能力不足
**解决**：
- 提高检索精度（重排序）
- 压缩上下文
- 使用更强的生成模型
### 3. 回答缺少引用
**原因**：
- Prompt 设计不当
- 模型未遵循指令
**解决**：
- 明确要求标注来源
- 使用结构化输出
- 后处理添加引用链接
---
## RAG 开源框架
### 1. LangChain
```python
from langchain.chains import RetrievalQA
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings
# 创建 RAG 链
qa_chain = RetrievalQA.from_chain_type(
llm=llm,
retriever=vectordb.as_retriever(search_kwargs={"k": 3}),
return_source_documents=True
)
```
### 2. LlamaIndex
```python
from llama_index import VectorStoreIndex, SimpleDirectoryReader
# 创建索引
documents = SimpleDirectoryReader('data').load_data()
index = VectorStoreIndex.from_documents(documents)
# 查询
query_engine = index.as_query_engine()
response = query_engine.query("问题")
```
### 3. Haystack
```python
from haystack import Pipeline, Document
from haystack.nodes import BM25Retriever, FARMReader
# 创建 RAG Pipeline
retriever = BM25Retriever(document_store)
reader = FARMReader(model_name="deepset/roberta-base-squad2")
pipe = Pipeline()
pipe.add_node(retriever, name="Retriever", inputs=["Query"])
pipe.add_node(reader, name="Reader", inputs=["Retriever"])
```
### 4. FastRAG / RAGFlow
专注于 RAG 的轻量级框架。
---
## RAG 实现清单
### 数据准备
- [ ] 收集文档数据
- [ ] 清洗和预处理
- [ ] 选择分块策略
- [ ] 添加元数据
### 向量化
- [ ] 选择 Embedding 模型
- [ ] 选择向量数据库
- [ ] 构建向量索引
- [ ] 测试检索质量
### Prompt 设计
- [ ] 设计系统提示词
- [ ] 定义输出格式
- [ ] 添加引用要求
- [ ] 处理无结果情况
### 评估优化
- [ ] 准备测试数据集
- [ ] 评估检索质量
- [ ] 评估生成质量
- [ ] 迭代优化
---
## 参考资源
### 论文
- [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401) - RAG 原始论文
- [Building RAG-based Applications with LangChain](https://blog.langchain.dev/building-a-full-rag-application-with-langchain/)
### 工具
- [LangChain](https://langchain.com) - AI 应用开发框架
- [LlamaIndex](https://llamaindex.ai) - 数据框架
- [Pinecone](https://pinecone.io) - 向量数据库
- [Qdrant](https://qdrant.tech) - 开源向量数据库
### 学习资源
- [RAG Tutorial](https://github.com/langchain-ai/rag-from-scratch)
- [Building RAG Applications](https://www.deeplearning.ai/short-courses/building-evaluating-advanced-rag/)
---
**文档更新时间：2025 年 12 月**
---
## Skill 发布与同步
`sonofmagic/weapp-tailwindcss` 的 `skills/` 是官方 Skill 内容的唯一事实源。用户安装使用的 `sonofmagic/skills` 是聚合仓库，不在这里手工维护副本。
## 同步关系
```text
sonofmagic/weapp-tailwindcss@main:skills/
-> sonofmagic/skills@main:skills/weapp-tailwindcss/
```
聚合仓库的 `Sync Skills From Upstreams` workflow 根据 `.github/skills-sources.json` 定时拉取整个 `skills/` 目录。新增、删除或重命名 Skill 时不需要直接提交聚合仓库。
## 发布前检查
1. 校验目录、frontmatter、references、UI 元数据和触发用例：
```bash
pnpm skills:validate
```
2. 使用官方 skill validator 逐个校验目录。
3. 本地检查可发现的名称：
```bash
npx skills add . --list
```
4. 临时安装完整套件，确认每个 `--skill` 名称有效。
5. 用正向、相邻边界和负向提示词做独立前向测试。
6. 同步 README、AI 首页、Skill 页面与 LLM 入口后构建 website。
## 发布流程
1. 在本仓库提交 `skills/**`、验证语料和文档入口。
2. 合并到 `main`。
3. 等待聚合仓库定时同步，或在需要立即发布时手动运行聚合仓库的 `Sync Skills From Upstreams` workflow。
4. 检查同步提交是否包含 7 个 Skill 目录。
5. 从 `sonofmagic/skills` 执行 `--list` 和临时安装验证。
Skill 不再使用独立 `skill-weapp-tailwindcss-v*` tag 或 GitHub Release 作为内容分发机制。版本历史以源仓库提交和聚合仓库同步提交为准。
## 用户安装命令
文档中的完整套件命令保持一致：
```bash
npx skills add sonofmagic/skills \
--skill weapp-tailwindcss \
--skill weapp-tailwindcss-setup \
--skill weapp-tailwindcss-migrate \
--skill weapp-tailwindcss-troubleshoot \
--skill weapp-tailwindcss-runtime \
--skill weapp-tailwindcss-custom-build \
--skill weapp-tailwindcss-react-native \
-y
```
不要对聚合仓库使用 `--all` 代替该命令，因为聚合仓库还包含其他项目的 Skill。
---
## Skill（技能系统）
`weapp-tailwindcss` 官方 Skill 面向业务项目使用者。它把当前 v5 的接入、迁移、排障和高级能力拆成独立工作流，避免一个大 Skill 同时维护所有框架与 API。
本项目使用 [`vercel-labs/skills`](https://github.com/vercel-labs/skills) 安装 Skill。`sonofmagic/weapp-tailwindcss` 是内容事实源，`sonofmagic/skills` 是面向用户的聚合安装仓库。
## 安装完整套件
```bash
npx skills add sonofmagic/skills \
--skill weapp-tailwindcss \
--skill weapp-tailwindcss-setup \
--skill weapp-tailwindcss-migrate \
--skill weapp-tailwindcss-troubleshoot \
--skill weapp-tailwindcss-runtime \
--skill weapp-tailwindcss-custom-build \
--skill weapp-tailwindcss-react-native \
-y
```
只安装兼容协调入口也可以：
```bash
npx skills add sonofmagic/skills --skill weapp-tailwindcss
```
协调入口负责识别任务并推荐专用 Skill；完整实现和参考资料位于各专用 Skill 中。
查看聚合仓库全部可安装内容：
```bash
npx skills add sonofmagic/skills --list
```
## Skill 分工
| Skill | 使用场景 |
| --- | --- |
| `weapp-tailwindcss` | 泛化请求、任务识别、安全基线与兼容入口 |
| `weapp-tailwindcss-setup` | 新接入、框架选型、Tailwind CSS 4 与多端配置 |
| `weapp-tailwindcss-migrate` | v4 到 v5、旧 patch/生成插件与环境迁移 |
| `weapp-tailwindcss-troubleshoot` | 样式生成、class 转译、rpx、HMR 和运行端排障 |
| `weapp-tailwindcss-runtime` | 动态 class、merge、cva、variants 与 escape/unescape |
| `weapp-tailwindcss-custom-build` | Core API、自研 bundler、样式注入和分包隔离 |
| `weapp-tailwindcss-react-native` | Expo Metro、Native manifest 和 Android/iOS 运行时 |
## 当前共同基线
- 当前主线只维护 Tailwind CSS 4。
- 当前 `weapp-tailwindcss` manifest 要求 Node.js `^22.18.0 || >=24.11.0`；HBuilderX 项目至少使用 5.11。
- 同一次受管构建只由 `WeappTailwindcss` 生成 Tailwind CSS，不叠加官方 Tailwind PostCSS/Vite 生成插件。
- Tailwind 入口使用纯 CSS，必须被项目实际导入；`cssEntries` 使用绝对路径且不能替代构建图导入。
- H5/Web 通常保留插件，由 generator 自动选择 Web target。
- JavaScript class 只转换 Tailwind 验证过的 `classNameSet` 精确候选。
## 本地开发安装
在本仓库根目录执行：
```bash
npx skills add . \
--skill weapp-tailwindcss \
--skill weapp-tailwindcss-setup \
--skill weapp-tailwindcss-migrate \
--skill weapp-tailwindcss-troubleshoot \
--skill weapp-tailwindcss-runtime \
--skill weapp-tailwindcss-custom-build \
--skill weapp-tailwindcss-react-native \
-y
```
## 提示词示例
```text
使用 $weapp-tailwindcss-setup，为新的 uni-app Vue3 Vite 项目配置微信小程序和 H5，给出完整文件与验证步骤。
```
```text
使用 $weapp-tailwindcss-migrate，把仍在运行 weapp-tw patch 和 @tailwindcss/vite 的旧项目迁移到 v5。
```
```text
使用 $weapp-tailwindcss-troubleshoot，定位为什么新加的任意值 class 在第二次 HMR 后不再生成。
```
```text
使用 $weapp-tailwindcss-custom-build，设计基于 weapp-tailwindcss/core 的内存转换和分包样式注入时序。
```
```text
使用 $weapp-tailwindcss-react-native，为 Expo SDK 54 配置 Metro 并验证 manifest warnings。
```
## 维护与验证
源码位于 `skills//`。每个目录包含 `SKILL.md`、`agents/openai.yaml` 和按需加载的 `references/`。
```bash
pnpm skills:validate
npx skills add . --list
```
发布链路见：[Skill 发布与同步](/docs/ai/basics/skill-release)。
---
## Spec-Driven Development（规范驱动开发）
## 概述
**Spec-Driven Development (SDD)** 或 **Spec-Driven Coding** 是一种**以规范（Specification）为先导**的软件开发方法论。开发者先编写详细的需求规范，然后由 AI 根据规范自动生成代码。
> **核心理念**：明确规范 → 自动实现 → 减少沟通成本
---
## 核心概念
### 1. 什么是 Spec（规范）
**Spec** 是对软件功能的**精确、可执行的描述**：
```markdown
# 用户登录功能规范
## 功能描述
用户可以使用邮箱和密码登录系统。
## 输入
- email: 字符串，符合邮箱格式
- password: 字符串，8-32位，包含字母和数字
## 输出
- 成功：返回用户信息和 JWT token
- 失败：返回错误信息
## 验证规则
- 邮箱必须已注册
- 密码必须正确
- 连续失败5次后锁定账户30分钟
## API 端点
POST /api/auth/login
```
### 2. Spec-Driven vs 传统开发
| 开发方式 | 流程 | 优势 | 劣势 |
| -------- | ---- | ---- | ---- |
| **传统开发** | 需求 → 设计 → 编码 | 灵活 | 沟通成本高 |
| **Spec-Driven** | 规范 → AI 生成代码 | 自动化、可追溯 | 需要编写规范 |
| **敏捷开发** | 用户故事 → 迭代 | 快速响应 | 文档缺失 |
---
## Spec-Driven Development 的流程
```
┌─────────────────────────────────────────────────────────┐
│ Spec-Driven Development 流程 │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. 需求收集 │
│ │ │
│ ▼ │
│ 2. 编写规范 (Spec) ┌─────────────────┐ │
│ │ │ 自然语言规范 │ │
│ ├────────────────────▶│ API 规范 │ │
│ │ │ 数据模型规范 │ │
│ │ │ UI 规范 │ │
│ │ └─────────────────┘ │
│ │ │
│ ▼ │
│ 3. AI 代码生成 ┌─────────────────┐ │
│ │ │ Claude Code │ │
│ ├────────────────────▶│ Cursor Agent │ │
│ │ └─────────────────┘ │
│ │ │
│ ▼ │
│ 4. 代码审查 │
│ │ │
│ ▼ │
│ 5. 测试验证 │
│ │ │
│ ▼ │
│ 6. 部署上线 │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## Spec 的类型
### 1. 功能规范
描述软件应该做什么：
```markdown
## 功能：用户注册
### 需求
用户可以注册新账户
### 输入字段
- username: 3-20字符，字母数字下划线
- email: 有效的邮箱地址
- password: 最少8位，必须包含大小写字母和数字
### 业务规则
- 用户名必须唯一
- 邮箱必须未被注册
- 注册后自动发送验证邮件
```
### 2. API 规范
描述 API 接口：
```yaml
# OpenAPI 规范
openapi: 3.0.0
info:
title: 用户认证 API
version: 1.0.0
paths:
/auth/login:
post:
summary: 用户登录
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
password:
type: string
minLength: 8
responses:
'200':
description: 登录成功
```
### 3. 数据模型规范
描述数据结构：
```typescript
// TypeScript 接口规范
interface User {
id: string;
username: string;
email: string;
createdAt: Date;
updatedAt: Date;
}
interface LoginRequest {
email: string;
password: string;
}
interface LoginResponse {
success: boolean;
token?: string;
user?: User;
error?: string;
}
```
### 4. UI 规范
描述界面要求：
```markdown
## 登录页面 UI 规范
### 布局
- 居中卡片式布局
- 宽度 400px
### 组件
- 邮箱输入框
- 密码输入框（带显示/隐藏切换）
- "记住我" 复选框
- "忘记密码" 链接
- 登录按钮
### 样式
- 主色调：#3B82F6
- 圆角：8px
- 阴影：0 4px 6px rgba(0,0,0,0.1)
```
---
## 支持 Spec-Driven 的工具
### 1. Cursor Composer
Cursor 的多步骤任务执行：
```typescript
// 用户输入
"实现用户认证功能，包含注册、登录、登出"
// Cursor 自动规划
1. 分析需求 → 生成规范
2. 设计数据模型
3. 实现 API 端点
4. 创建 UI 组件
5. 编写测试用例
```
### 2. Claude Code CLI
通过 CLAUDE.md 定义规范：
```markdown
# 项目规范
## 编码规范
- 使用 TypeScript 严格模式
- 遵循 ESLint 规则
- 组件使用函数式声明
## API 规范
- RESTful 风格
- 统一错误处理
- JWT 认证
## 测试规范
- 单元测试覆盖率 > 80%
- 使用 Vitest
```
---
## Spec 编写最佳实践
### 1. SMART 原则
| 原则 | 说明 | 示例 |
| ---- | ---- | ---- |
| **Specific** | 具体明确 | "用户可以登录" 而非 "实现认证" |
| **Measurable** | 可衡量 | "密码8-32位" 而非 "密码足够复杂" |
| **Achievable** | 可实现 | 考虑技术限制 |
| **Relevant** | 相关性 | 与业务目标一致 |
| **Time-bound** | 有时限 | "在2秒内完成" |
### 2. 结构化规范
```markdown
## 功能概述
一句话描述功能
## 用户故事
作为 [角色]，我想要 [功能]，以便 [目的]
## 验收标准
- [ ] 场景1：描述
- [ ] 场景2：描述
## 技术规范
### 数据模型
### API 接口
### 业务逻辑
## 非功能需求
### 性能：响应时间 < 200ms
### 安全：HTTPS + JWT
### 兼容：支持主流浏览器
```
### 3. 使用规范语言
- 使用**自然语言**但保持结构化
- 避免歧义词汇（"尽可能"、"大概"）
- 使用**具体数字**（"3次"而非"多次"）
- 包含**边界条件**（"空值"、"超长输入"）
---
## Spec-Driven vs 其他开发方式
### Spec-Driven vs Vibe Coding
| 维度 | Spec-Driven | Vibe Coding |
| ---- | ----------- | ----------- |
| **规划** | 详细规范 | 随性发挥 |
| **可追溯** | 高 | 低 |
| **团队协作** | 容易 | 困难 |
| **AI 参与** | 核心 | 辅助 |
| **适用场景** | 大型项目、团队 | 原型、个人项目 |
### Spec-Driven vs Test-Driven Development
| 维度 | Spec-Driven | TDD |
| ---- | ----------- | --- |
| **起点** | 规范 | 测试 |
| **顺序** | 规范 → 代码 → 测试 | 测试 → 代码 |
| **AI 友好** | 是 | 否 |
| **可组合** | 可组合 | 相对独立 |
---
## 实施建议
### 1. 规范模板
```markdown
# [功能名称] 规范
## 背景
为什么需要这个功能
## 目标
这个功能要达到什么效果
## 功能描述
详细的功能说明
## 验收标准
如何判断功能完成
## 技术考虑
- 性能要求
- 安全考虑
- 兼容性要求
## 依赖
依赖的其他功能或模块
```
### 2. 工具配置
```json
// .claude/spec-template.json
{
"template": "# 功能规范\n\n## 功能概述\n{summary}\n\n## 需求\n{requirements}\n\n## 验收标准\n{acceptance}",
"requiredFields": ["summary", "requirements"],
"outputFormat": "markdown"
}
```
### 3. 版本管理
```
specs/
├── v1.0/
│ ├── auth-spec.md
│ ├── user-spec.md
│ └── api-spec.md
├── v1.1/
│ ├── auth-spec.md (更新)
│ └── payment-spec.md (新增)
```
---
## 参考资源
### 相关工具
- [Cursor Composer](https://cursor.com/docs/composer)
- [OpenAPI Specification](https://swagger.io/specification/)
### 相关方法论
- [Behavior-Driven Development (BDD)](https://en.wikipedia.org/wiki/Behavior-driven_development)
- [Feature-Driven Development (FDD)](https://en.wikipedia.org/wiki/Feature-driven_development)
---
**文档更新时间：2025 年 12 月**
---
## Token（词元）
## 概述
**Token** 是大语言模型（LLM）处理文本的**基本单位**。不同于人类理解的"单词"或"字符"，Token 是模型内部使用的最小语义单元。
> **核心概念**：1 Token ≈ 0.75 个英文单词 ≈ 4 个字符 ≈ 2-3 个汉字
---
## Token 的本质
### 1. 什么是 Token
Token 是将文本切分成的**序列片段**：
```
输入文本: "Hello, world!"
Token序列: ["Hello", ",", "world", "!"]
Token数量: 4
```
### 2. 分词 (Tokenization)
将文本转换为 Token 序列的过程：
```python
# GPT 分词示例
text = "Artificial Intelligence is amazing"
tokens = ["Art", "ificial", " Int", "elligence", " is", " am", "azing"]
# 7 tokens
# Claude 分词示例
text = "Artificial Intelligence is amazing"
tokens = ["Art", "ificial", " Intelligence", " is", " amazing"]
# 5 tokens（不同模型分词不同）
```
### 3. 字节对编码 (BPE)
主流的 Tokenization 方法：
```
原始: "unbelievable"
步骤1: u n b e l i e v a b l e (字符级)
步骤2: un bel ieve able (词级+字符级混合)
步骤3: ["un", "believable"] (最终Token)
```
---
## Token 的计数规则
### 1. 英文文本
| 文本类型 | Token 估算 |
| -------- | ---------- |
| 1 个单词 | ~1.3 tokens |
| 1 个句子 (15词) | ~20 tokens |
| 1 段落 (100词) | ~130 tokens |
| 1 页文档 (500词) | ~650 tokens |
### 2. 中文文本
| 文本类型 | Token 估算 |
| -------- | ---------- |
| 1 个汉字 | ~0.5-1 token |
| 1 个词 (2-3字) | ~1-2 tokens |
| 1 个句子 (20字) | ~10-15 tokens |
| 1 段落 (100字) | ~50-70 tokens |
### 3. 代码
| 代码类型 | Token 估算 |
| -------- | ---------- |
| 1 行简单代码 | ~10-20 tokens |
| 1 行复杂代码 | ~30-50 tokens |
| 1 个函数 (50行) | ~300-500 tokens |
| 1 个文件 (500行) | ~3000-5000 tokens |
### 4. 特殊场景
| 场景 | Token 计数 |
| ---- | ---------- |
| 空格 | 1 token |
| 换行 | 1 token |
| 缩进 (2空格) | 1 token |
| 制表符 | 1 token |
| 数字 (12345) | 1-2 tokens |
| URL | ~10-20 tokens |
---
## 各模型的 Token 限制
### 上下文窗口 (Context Window)
| 模型 | 上下文长度 | 输出限制 |
| ---- | ---------- | -------- |
| **Claude Opus 4.5** | 200K tokens | ~8K 输出 |
| **Claude Sonnet 4.5** | 200K tokens | ~8K 输出 |
| **GPT-4o** | 128K tokens | ~4K 输出 |
| **GPT-5.2** | 1M tokens | ~8K 输出 |
| **Gemini 2.0 Pro** | 2M tokens | ~8K 输出 |
| **Gemini 1.5 Pro** | 1M tokens | ~8K 输出 |
| **GLM-4.7** | 128K tokens | ~4K 输出 |
### Token 价格对比（$/百万 tokens）
| 模型 | 输入 | 输出 |
| ---- | ---- | ---- |
| **Claude Opus 4.5** | $15 | $75 |
| **Claude Sonnet 4.5** | $3 | $15 |
| **GPT-4o** | $5 | $15 |
| **GPT-5.2** | $2 | $8 |
| **Gemini 2.0 Pro** | $1.25 | $5 |
| **GLM-4.7** | ¥2.2 (≈$0.3) | ¥6.6 (≈$0.9) |
---
## Token 实用计算
### 1. 快速估算
```
英文: 字符数 ÷ 4 ≈ Token 数
中文: 字符数 ÷ 2 ≈ Token 数
代码: 行数 × 10 ≈ Token 数
```
### 2. 精确计算工具
#### Tiktoken (OpenAI)
```python
import tiktoken
# GPT-4 编码器
encoding = tiktoken.encoding_for_model("gpt-4")
text = "Hello, world!"
tokens = encoding.encode(text)
print(f"Token 数量: {len(tokens)}")
```
#### Anthropic Tokenizer
```python
import anthropic
client = anthropic.Anthropic()
response = client.messages.count_tokens(
model="claude-3-opus-20240229",
text="Hello, world!"
)
print(f"Token 数量: {response.input_tokens}")
```
#### 在线工具
- [Token 计算](https://platform.openai.com/tokenizer)
- [Claude Token 计数](https://calculator.anthropic.com/)
---
## Token 使用优化
### 1. 减少 Token 消耗
| 优化方法 | 效果 |
| -------- | ---- |
| **删除无用信息** | 节省 20-40% |
| **精简提示词** | 节省 30-50% |
| **使用压缩格式** | 节省 10-20% |
| **避免重复内容** | 节省 15-30% |
### 2. 系统提示词优化
```diff
- verbose: "You are a highly intelligent and capable assistant designed to help users with a wide variety of tasks..."
+ concise: "你是一个智能助手，擅长代码开发和问题解决。"
```
### 3. 上下文管理
```python
# 只包含相关文件
relevant_files = [
"src/utils/auth.ts", # 包含
"src/utils/helpers.ts", # 包含
# "src/utils/deprecated.ts", # 排除
]
# 使用摘要代替全文
file_summary = summarize_large_file("large_file.ts") # 100 tokens
# vs 完整文件: # 5000 tokens
```
### 4. 缓存策略
| 缓存类型 | 说明 | 节省 |
| -------- | ---- | ---- |
| **系统提示缓存** | Claude/GPT 支持 | 可重用 |
| **文档缓存** | 预处理文档 | 减少重复输入 |
| **向量检索** | 只取相关片段 | 大幅减少上下文 |
---
## Token 成本计算
### 1. 成本估算示例
假设使用 GPT-4o 分析代码库：
```
代码库规模: 100,000 行代码
Token 估算: 100,000 × 10 = 1,000,000 tokens
输入成本: 1M × $5/1M = $5
输出成本: 50K × $15/1M = $0.75
总成本: ~$6
```
### 2. 不同模型成本对比
假设处理 1M tokens：
| 模型 | 输入成本 | 总成本 |
| ---- | -------- | ------ |
| **Claude Opus 4.5** | $15 | ~$90 |
| **Claude Sonnet 4.5** | $3 | ~$18 |
| **GPT-4o** | $5 | ~$30 |
| **GPT-5.2** | $2 | ~$12 |
| **Gemini 2.0 Pro** | $1.25 | ~$7.50 |
| **GLM-4.7** | ¥2.2 (≈$0.3) | ~¥15 (≈$2) |
---
## Token 常见问题
### Q1: 为什么中英文 Token 数不同？
中文使用 Unicode 编码，一个汉字可能被拆分成多个字节，因此需要更多或更少的 tokens。
### Q2: 空格和换行算 Token 吗？
是的，空格、换行、缩进等空白字符都会被计入 tokens。
### Q3: 代码注释是否计入 Token？
是的，所有发送给模型的内容都会计入，包括注释。
### Q4: 如何减少 API 成本？
- 使用更小的模型（如 Sonnet 代替 Opus）
- 优化提示词长度
- 使用缓存和向量化
- 批量处理
### Q5: Token 和字符的精确比例？
| 语言 | Token/字符 |
| ---- | ---------- |
| 英文 | ~1:4 |
| 中文 | ~1:2 |
| 代码 | ~1:3-5 |
---
## 参考资源
### 官方文档
- [OpenAI Tokenizer](https://platform.openai.com/tokenizer)
- [Anthropic Token 计数](https://calculator.anthropic.com/)
- [Google Token 计数](https://gemini.google.com/token)
### 开源工具
- [tiktoken](https://github.com/openai/tiktoken) - OpenAI 分词器
- [tokenizers](https://github.com/huggingface/tokenizers) - Hugging Face 分词器
---
**文档更新时间：2025 年 12 月**
---
## Vibe Coding（直觉编程）
## 概述
**Vibe Coding**（直觉编程、感觉编程）是一种**依赖直觉、经验和即时反馈**的编程方式。开发者不严格遵循规范或计划，而是根据"感觉"来编写和调整代码。
> **核心理念**：跟着直觉走，快速迭代，边做边改
---
## 核心概念
### 1. 什么是 Vibe Coding
**Vibe Coding** 的特点：
- **无明确规划**：不写详细设计文档
- **快速迭代**：写代码 → 调整 → 再调整
- **依赖直觉**：凭"感觉"判断代码好坏
- **即时反馈**：边运行边修改
- **AI 辅助**：用 AI 快速探索想法
### 2. Vibe Coding vs 传统编程
| 维度 | 传统编程 | Vibe Coding |
| ---- | -------- | ----------- |
| **规划** | 详细设计 | 即兴发挥 |
| **文档** | 先写文档 | 代码即文档 |
| **流程** | 需求→设计→编码 | 想法→代码→调整 |
| **测试** | 先写测试 | 后补测试 |
| **灵活性** | 结构化 | 高度灵活 |
---
## Vibe Coding 的风格
### 1. 探索式编程
```
想法: "我想做一个简单的待办事项应用"
↓
快速原型: 用 AI 生成基础代码
↓
运行测试: 看看效果如何
↓
直觉调整: "这个颜色不好看，改一下"
↓
添加功能: "再加个分类功能"
↓
继续调整: "布局有点乱，重构一下"
```
### 2. 对话式编程
```
开发者: "帮我做个登录页面"
AI: [生成代码]
开发者: "颜色太深了"
AI: [调整颜色]
开发者: "加个忘记密码链接"
AI: [添加功能]
开发者: "这个位置不对"
AI: [调整布局]
...
```
### 3. 试错式编程
```
尝试1: [方案A] → 不行，太复杂
尝试2: [方案B] → 还是不对
尝试3: [方案C] → 感觉对了！
完善: [方案C改进] → 完成
```
---
## Vibe Coding 的场景
### 适合场景
| 场景 | 原因 |
| ---- | ---- |
| **原型开发** | 快速验证想法 |
| **创意项目** | 需要灵活探索 |
| **学习新技术** | 边做边学 |
| **个人项目** | 无需团队协作 |
| **黑客马拉松** | 时间有限，求快 |
### 不适合场景
| 场景 | 原因 |
| ---- | ---- |
| **大型团队项目** | 缺乏规范导致混乱 |
| **安全关键系统** | 需要严格验证 |
| **长期维护项目** | 技术债务积累 |
| **复杂业务系统** | 需要详细设计 |
---
## Vibe Coding + AI
### 1. AI 作为"直觉放大器"
```
开发者的直觉 → AI 快速实现 → 即时反馈 → 强化直觉
↑ ↓
└────────────────────────────────────────┘
持续迭代循环
```
### 2. 工具支持
| 工具 | Vibe Coding 支持 |
| ---- | --------------- |
| **Cursor** | 快速生成、即时修改 |
| **Claude Code** | 对话式开发 |
| **Cline** | VS Code 内的快速迭代 |
| **Replit** | 浏览器内即时运行 |
### 3. 典型工作流
```bash
# 1. 想到什么直接让 AI 做
claude-code "创建一个 React 待办组件"
# 2. 看着效果，凭直觉调整
claude-code "把按钮改成圆角，加个阴影"
# 3. 继续添加功能
claude-code "加个删除按钮，用红色"
# 4. 发现问题
claude-code "删除没反应，检查一下"
# 5. 重构调整
claude-code "代码有点乱，整理一下"
```
---
## Vibe Coding 的技巧
### 1. 快速原型
```
第一步: 5分钟实现核心功能
第二步: 运行看看效果
第三步: 凭直觉调整
第四步: 继续添加
第五步: 随时重构
```
### 2. 最小可行产品
```
不要一开始就想完整
先做最简单的能用的版本
然后逐步完善
```
### 3. 相信直觉
```
"感觉这个颜色不对" → 改
"感觉逻辑有点复杂" → 简化
"感觉这里可以优化" → 优化
```
### 4. 拥抱不完美
```
Vibe Coding 接受:
- 代码可能不够优雅
- 结构可能不够完美
- 测试可能不够完整
但重点是: 快速做出能用的东西
```
---
## Vibe Coding vs Spec-Driven Development
### 对比表
| 维度 | Vibe Coding | Spec-Driven Development |
| ---- | ----------- | ------------------------ |
| **规划** | 随性 | 严格 |
| **文档** | 代码即文档 | 详细规范 |
| **灵活性** | 极高 | 中等 |
| **可维护性** | 低 | 高 |
| **团队协作** | 困难 | 容易 |
| **学习曲线** | 低 | 高 |
| **AI 参与度** | 高 | 高 |
| **适用规模** | 小 | 大 |
### 何时使用
| 场景 | 推荐 |
| ---- | ---- |
| **创意验证** | Vibe Coding |
| **黑客马拉松** | Vibe Coding |
| **个人项目** | Vibe Coding |
| **团队项目** | Spec-Driven |
| **企业级系统** | Spec-Driven |
| **长期产品** | Spec-Driven |
---
## Vibe Coding 的最佳实践
### 1. 保持代码整洁
即使采用 Vibe Coding，也要：
```
- 定期重构
- 删除无用代码
- 保持一致的命名
- 添加必要注释
```
### 2. 使用 Git 分支
```
main (稳定版本)
↑
feature/experiment (随意尝试)
↓
实验成功了 → 合并到 main
实验失败了 → 直接删除
```
### 3. 设置时间限制
```
- 单次会话不超过 2 小时
- 避免陷入无休止的调整
- 定期回顾和整理
```
### 4. 记录重要决策
```
即使不写详细文档，也要记录:
- 为什么选择这个方案
- 遇到的坑和解决方案
- 下次改进的方向
```
---
## Vibe Coding 的风险
### 1. 技术债务
```
快速原型 → 技术债务积累
↓
如果不及时还债
↓
项目变得难以维护
```
### 2. 缺乏可追溯性
```
"为什么这样写?"
"我也不知道，当时感觉这样对"
```
### 3. 团队协作困难
```
"这个代码是什么意思?"
"我也不懂，是他凭感觉写的"
```
### 4. 难以复现
```
"这个功能怎么实现的?"
"忘记了，当时随便写的"
```
---
## 混合策略
### Vibe + Spec
最好的方式是**结合两者**：
```
┌─────────────────────────────────────────────────────────┐
│ Vibe + Spec 混合策略 │
├─────────────────────────────────────────────────────────┤
│ │
│ 探索阶段 (Vibe) │
│ ├── 快速原型 │
│ ├── 验证想法 │
│ └── 找到方向 │
│ ↓ │
│ 稳定阶段 (Spec) │
│ ├── 编写规范 │
│ ├── 重构代码 │
│ └── 添加测试 │
│ ↓ │
│ 迭代循环 │
│ │
└─────────────────────────────────────────────────────────┘
```
### 实践建议
```
1. 个人项目: 多用 Vibe Coding
2. 团队项目: 核心用 Spec，边缘用 Vibe
3. 紧急需求: 先 Vibe 解决，后 Spec 规范
4. 创新探索: Vibe 先行，Spec 跟进
```
---
## 参考资源
### 相关概念
- [Spaghetti Code](https://en.wikipedia.org/wiki/Spaghetti_code) - 反面模式
- [Technical Debt](https://en.wikipedia.org/wiki/Technical_debt) - 技术债务
- [Prototype](https://en.wikipedia.org/wiki/Software_prototyping) - 原型开发
### 工具
- [Cursor](https://cursor.sh) - AI IDE
- [Claude Code](https://claude.ai/code) - AI CLI
- [Replit](https://replit.com) - 在线 IDE
---
**文档更新时间：2025 年 12 月**
---
## AI 生成小程序代码
## 提升效率
本页面为使用 AI 快速构建小程序的专题，希望能够帮助大家不断的提升自己的开发效率
同时也希望大家一起讨论参与，快速的生成他个成百上千个小程序, APP, 和网站！
## AI 学习中心：Skill 快速安装
官方 Skill 已按任务拆分为 1 个兼容协调入口和 6 个专用工作流。推荐安装整套，以覆盖接入、迁移、排障、运行时、自定义构建和 Expo React Native：
```bash
npx skills add sonofmagic/skills \
--skill weapp-tailwindcss \
--skill weapp-tailwindcss-setup \
--skill weapp-tailwindcss-migrate \
--skill weapp-tailwindcss-troubleshoot \
--skill weapp-tailwindcss-runtime \
--skill weapp-tailwindcss-custom-build \
--skill weapp-tailwindcss-react-native \
-y
```
原来的 `weapp-tailwindcss` 名称继续作为轻量协调入口，旧安装命令不会失效。
详细说明见：[Skill（技能系统）](/docs/ai/basics/skill)
## 如何参与贡献
### 前置环境
1. `nodejs@22`
2. `pnpm@11`
3. `Github` 账号
### 开始
点击 [`fork weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss/fork), 然后 `git clone` 到本地在打开这个目录:
1. 执行 `pnpm i` 安装依赖
2. 执行 `pnpm build:pkg` 构建 `website` 的本地依赖包
3. 然后 `cd website && pnpm dev` (切换到 `website` 目录, 跑 `pnpm dev`，当然你也可以在 `vscode` 里面右键打开终端，然后 `pnpm dev` 运行)
4. 访问 `http://localhost:4000` 就是 `weapp-tailwindcss` 的官方文档网站了
然后，你可以在 `website/docs/ai` 目录下，新建 `md` / `mdx` 文件，进行写作，路由会自动映射到:
`http://localhost:4000/docs/ai/{your_doc_name}` 路径中去
> 比如你创建一个 `v0.md`，你的路由就是 `http://localhost:4000/docs/ai/v0`
>
> 假如你创建一个 `index.md`，比如这个页面就是一个 `index.md` 这个页面访问路径为 http://localhost:4000/docs/ai
假如你有素材，可以放在 `website/docs/ai/assets/{your_doc_name}` 目录下，然后在 `md` 文件中，进行引用
## 示例
### 网站
1. https://v0.dev/
2. https://docs.crewai.com/guides
3. https://bolt.new/
### 上传图片
比如要实现 `网页云音乐`，就手机上打开 `网页云音乐`，然后截长图，上传到 `v0.dev`
> 此处有截图
### 提示词
然后提示词为
- `技术栈为 uni-app vue3 tailwindcss, 实现这个页面`(根据你的需求自定义)
然后复制代码即可
> 此处有截图
---
## 国外顶尖编程模型选型建议书
> **核心结论**：在三大国外顶尖模型中，**Claude Opus 4.5** 在代码质量上保持领先，**GPT-5.2** 在数学推理上最强，**Gemini 3 Pro** 在多模态和长上下文场景表现突出。
## 执行摘要
经过对当前三大国外顶尖 AI 编程模型的深入分析，我们建议：
1. **代码质量优先**：采用 **Claude Opus 4.5**
- 代码质量排名全球第 1
- 代码理解和重构能力最强
- 适合复杂系统架构设计
- 代码审查和重构场景首选
2. **数学推理优先**：采用 **GPT-5.2**
- AIME 2025 排名第 1（1.0 分，满分）
- 算法和复杂数学问题最强
- 适合算法竞赛、科学计算、量化交易
- 逻辑推理能力领先
3. **多模态和长上下文**：采用 **Gemini 3 Pro**
- 支持 200 万 token 超长上下文
- 多模态能力最强（视频、音频、图片）
- 适合处理大规模代码库和多媒体内容
- Google 生态系统集成最佳
---
## 一、三大模型核心对比
### 1.1 基础信息对比
| 对比维度 | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| ------------------------ | ----------------- | -------------------- | -------------------- |
| **发布时间** | 2025.11.24 | 2025.12.11 | 2025.12 |
| **开发商** | Anthropic（美国） | OpenAI（美国） | Google（美国） |
| **代码能力排名** | **第 1 名** | 前 3 名 | 前 5 名 |
| **AIME 2025** | 高分 | **第 1 名（1.0分）** | 高分 |
| **最大上下文** | 200K tokens | 1M tokens | **2M tokens** |
| **多模态** | 图片、音频 | 图片、音频 | **视频、音频、图片** |
| **价格（$/百万tokens）** | $5-25 | $1.75-14 | $1.25-10 |
| **开源状态** | ❌ 闭源 | ❌ 闭源 | ❌ 闭源 |
**数据来源**：[LLM Stats](https://llm-stats.com/)、各模型官方文档、权威基准测试榜单
### 1.2 核心能力雷达图
```
代码生成能力
Claude Opus 4.5: ★★★★★ (代码质量第1)
GPT-5.2: ★★★★★
Gemini 3 Pro: ★★★★
数学推理能力
Claude Opus 4.5: ★★★★
GPT-5.2: ★★★★★ (AIME满分)
Gemini 3 Pro: ★★★★
长上下文处理
Claude Opus 4.5: ★★★
GPT-5.2: ★★★★
Gemini 3 Pro: ★★★★★ (200万tokens)
多模态能力
Claude Opus 4.5: ★★★
GPT-5.2: ★★★
Gemini 3 Pro: ★★★★★ (支持视频)
中文支持
Claude Opus 4.5: ★★★
GPT-5.2: ★★★
Gemini 3 Pro: ★★★
价格竞争力
Claude Opus 4.5: ★★ (最贵)
GPT-5.2: ★★★
Gemini 3 Pro: ★★★★ (较便宜)
```
---
## 二、Claude Opus 4.5：代码质量之王
### 2.1 为什么 Claude Opus 4.5 代码质量第一？
#### 权威排名
根据 [LLM Stats](https://llm-stats.com/) 最新数据：
- **代码质量排名：全球第 1 名**
- 综合排名前 5
- 在代码生成、代码理解、重构场景中表现最优
#### 核心优势
1. **代码理解能力**
- 深度理解复杂代码结构
- 准确识别代码异味和反模式
- 跨文件依赖关系分析
2. **代码生成质量**
- 生成代码可读性强
- 遵循最佳实践和设计模式
- 类型安全和错误处理完善
3. **重构能力**
- 大规模代码重构
- 架构演进建议
- 技术债务识别和管理
4. **安全性意识**
- 主动识别安全漏洞
- 符合 OWASP 最佳实践
- 输入验证和授权建议
### 2.2 适用场景
| 场景 | 适用度 | 说明 |
| ---------------- | ------ | --------------------------------- |
| **代码审查** | ★★★★★ | 能发现深层问题，提供重构建议 |
| **系统架构设计** | ★★★★★ | 理解复杂系统，提供架构方案 |
| **技术债务管理** | ★★★★★ | 识别技术债务，制定重构计划 |
| **算法实现** | ★★★★ | 代码质量高，但数学推理略逊GPT-5.2 |
| **遗留系统迁移** | ★★★★★ | 深度理解旧代码，提供迁移方案 |
| **测试用例生成** | ★★★★★ | 覆盖边界情况，测试质量高 |
| **CI/CD 集成** | ★★★★★ | Claude Code CLI 官方工具 |
### 2.3 Claude Code CLI：官方工程化工具
Claude Opus 4.5 配合 Claude Code CLI 提供完整的工程化能力：
```
Claude Code CLI
├── 官方维护（Anthropic）
├── 成熟的 Agent 架构
├── 150+ 插件生态
├── 项目级上下文管理
├── LSP 集成
└── 企业级最佳实践
```
**关键优势**：
- Anthropic 是 AI 安全和工程化规范的核心制定者
- 符合 ASL-3 安全标准
- 企业级合规框架
- 详见：[Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
### 2.4 成本分析
#### 订阅价格与使用限制
| 版本 | 月费 | 额度刷新周期 | 使用额度 | 适用对象 |
| --------- | ------------------ | ------------ | -------- | ---------- |
| **Pro** | $20（≈¥140） | **每周** | 基础额度 | 个人开发者 |
| **Teams** | $40/人/月（≈¥280） | **每周** | 团队额度 | 小团队 |
| **Max** | $200（≈¥1400） | **每周** | 大量额度 | 重度用户 |
> **重要说明（2025年8月28日起）**：
>
> - Anthropic 引入了新的**每周使用额度限制**
> - 额度每**7天**重置一次
> - Pro 和 Max 用户均有独立的每周使用上限
> - 超出额度后需等待下一周期或升级套餐
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（7天后自动恢复）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：切换/注册其他订阅账号（需遵守服务条款）
#### API 按量计费
| 场景 | 输入 | 输出 |
| -------- | ---------------- | ----------------- |
| **标准** | $1-5/百万 tokens | $3-15/百万 tokens |
> **成本对比**：
>
> - Claude Opus 是三者中最贵的
> - 但代码质量最高，复杂场景下反而更经济（减少调试时间）
> - 代码审查和重构场景 ROI 最高
---
## 三、GPT-5.2：数学推理之王
### 3.1 为什么 GPT-5.2 数学推理最强？
#### 权威排名
根据 AIME 2025（美国数学邀请赛）：
- **AIME 2025 排名：第 1 名（1.0 分，满分）**
- 综合排名前 3
- 在数学、算法、逻辑推理场景中表现最优
#### 核心优势
1. **数学推理能力**
- 复杂数学问题求解
- 算法设计和优化
- 数学证明生成
- 量化策略分析
2. **逻辑推理**
- 复杂条件判断
- 多步骤推理链
- 抽象问题建模
- 逻辑漏洞识别
3. **算法能力**
- 数据结构选择
- 算法复杂度分析
- 性能优化建议
- 并发和并行计算
4. **科学计算**
- 数值分析
- 统计建模
- 机器学习算法
- 量子计算
### 3.2 适用场景
| 场景 | 适用度 | 说明 |
| ------------ | ------ | ---------------------- |
| **算法竞赛** | ★★★★★ | 数学推理满分，算法最优 |
| **量化交易** | ★★★★★ | 复杂数学模型，策略回测 |
| **科学计算** | ★★★★★ | 数值分析，统计建模 |
| **机器学习** | ★★★★★ | 算法实现，模型优化 |
| **游戏 AI** | ★★★★★ | 博弈论，策略优化 |
| **密码学** | ★★★★★ | 数学基础，安全算法 |
| **性能优化** | ★★★★ | 算法复杂度分析 |
### 3.3 GPT-5.2-Codex-Max：代码专用版本
OpenAI 提供专门的代码模型：
```
GPT-5.2-Codex-Max
├── 专注代码生成
├── 代码补全能力
├── 多语言支持
└── 深度代码理解
```
**特点**：
- 代码能力与 GPT-5.2 相当
- 专为编程场景优化
- 适合集成到 IDE 和工具
### 3.4 成本分析
#### 订阅价格与使用限制
| 版本 | 月费 | 额度刷新周期 | 使用额度 | 适用对象 |
| -------------- | ------------------ | ------------ | ---------------------------------------- | ---------- |
| **Plus** | $20（≈¥140） | **每5小时** | 30-150条消息/5小时 | 个人开发者 |
| **Pro** | $200（≈¥1400） | **每5小时** | 300-1500条本地消息或50-400个云任务/5小时 | 专业用户 |
| **Team** | $30/人/月（≈¥210） | **每5小时** | 团队共享额度 | 团队 |
| **Enterprise** | 定制 | 灵活 | 定制 | 大企业 |
> **重要说明**：
>
> - **每5小时**刷新一次额度（滚动窗口）
> - Plus 用户还有**每周限制**（约6-7次完整会话后达到上限）
> - 超出额度后会提示 _"You've hit your usage limit. Upgrade to Pro or try again in X days Y hours"_
> - Codex CLI、Chat、Agent 模式、代码审查等功能消耗"premium requests"
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（5小时后自动恢复）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：升级到 Pro 版本获得更高额度
> - **方案四**：切换/注册其他订阅账号（需遵守服务条款）
#### API 按量计费
| 场景 | 输入 | 输出 |
| -------- | ------------------- | ------------------- |
| **标准** | $0.25-2/百万 tokens | $0.75-6/百万 tokens |
> **成本对比**：
>
> - GPT-5.2 价格中等，介于 Claude 和 Gemini 之间
> - 数学推理场景性价比最高
> - 适合算法密集型应用
---
## 四、Gemini 3 Pro：长上下文和多模态之王
### 4.1 为什么 Gemini 3 Pro 在长上下文和多模态领先？
#### 核心优势
1. **超长上下文**
- **200 万 tokens**（三者中最长）
- 可处理整个大型代码库
- 跨文件深度关联分析
- 长文档理解能力
2. **多模态能力**
- **视频理解**（独有）
- 音频处理
- 图片分析
- 多模态综合推理
3. **Google 生态集成**
- Google Cloud 集成
- Android 开发支持
- TensorFlow/ML 集成
- Google Workspace 协作
### 4.2 适用场景
| 场景 | 适用度 | 说明 |
| ---------------- | ------ | ------------------------- |
| **大规模代码库** | ★★★★★ | 200万tokens，一次分析全库 |
| **视频内容分析** | ★★★★★ | 独有视频理解能力 |
| **多模态应用** | ★★★★★ | 图文音视频综合处理 |
| **Android 开发** | ★★★★★ | Google 官方支持 |
| **长文档处理** | ★★★★★ | 超长文档理解 |
| **知识库构建** | ★★★★★ | 大规模资料整合 |
| **代码迁移** | ★★★★ | 全库分析，迁移方案 |
### 4.3 Gemini 2.0 Flash：速度优先版本
Google 提供轻量级版本：
```
Gemini 2.0 Flash
├── 响应速度快
├── 成本更低
├── 适合简单任务
└── 实时交互场景
```
### 4.4 成本分析
#### Gemini Code Assist 订阅价格
| 版本 | 月费 | 刷新周期 | 使用额度 | 适用对象 |
| -------------- | ------------ | -------- | ------------------ | ---------- |
| **Standard** | $19（≈¥130） | **每日** | 无限代码补全 | 个人开发者 |
| **Enterprise** | $45（≈¥310） | **每日** | 100个PR reviews/天 | 企业团队 |
> **使用限制说明**：
>
> - **代码补全**：Standard 和 Enterprise 均为无限次
> - **Pull Request 审查**：Enterprise 100次/天，Consumer 版本 33次/天
> - **Flash Free Tier**：1500 requests/天（Flash 和 Flash-Lite 共享）
> - **Gemini 3 Pro Preview**：250 messages/24小时
> - **Gemini 3.0 Ultra**：20 requests/天（2025年从250次大幅削减92%）
> - **Main Gemini App**：100 queries/天限制
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（1天后自动恢复）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：升级到 Enterprise 版本获得更高额度
> - **方案四**：切换/注册其他订阅账号（需遵守服务条款）
#### API 按量计费
| 场景 | 输入 | 输出 |
| -------- | ----------------------- | ----------------------- |
| **标准** | $0.125-1.25/百万 tokens | $0.375-3.75/百万 tokens |
> **成本对比**：
>
> - Gemini 3 Pro 是三者中最便宜的
> - 长上下文场景性价比最高
> - 适合大规模代码库分析
---
## 五、三大模型深度对比
### 5.1 编程能力对比
| 能力维度 | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| ---------------- | --------------- | ------- | ------------ |
| **代码生成质量** | ★★★★★ | ★★★★★ | ★★★★ |
| **代码理解** | ★★★★★ | ★★★★ | ★★★★ |
| **代码重构** | ★★★★★ | ★★★★ | ★★★ |
| **调试能力** | ★★★★★ | ★★★★ | ★★★ |
| **测试用例生成** | ★★★★★ | ★★★★ | ★★★ |
| **文档生成** | ★★★★★ | ★★★★ | ★★★★ |
| **架构设计** | ★★★★★ | ★★★★ | ★★★ |
**结论**：
- **代码质量**：Claude Opus 4.5 全面领先
- **代码生成**：Claude 和 GPT-5.2 相当
- **文档生成**：三者都较强
### 5.2 推理能力对比
| 能力维度 | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| -------------- | --------------- | ------- | ------------ |
| **数学推理** | ★★★★ | ★★★★★ | ★★★★ |
| **逻辑推理** | ★★★★★ | ★★★★★ | ★★★★ |
| **算法设计** | ★★★★ | ★★★★★ | ★★★★ |
| **抽象思维** | ★★★★★ | ★★★★★ | ★★★★ |
| **多步骤推理** | ★★★★★ | ★★★★★ | ★★★★ |
| **创造性思维** | ★★★★★ | ★★★★ | ★★★★ |
**结论**：
- **数学推理**：GPT-5.2 一骑绝尘（AIME满分）
- **逻辑推理**：Claude 和 GPT-5.2 相当
- **创造性**：Claude 略强
### 5.3 工程化能力对比
| 能力维度 | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| -------------- | --------------- | -------- | ------------ |
| **CLI 工具** | ✅ Claude Code | ⭐⭐⭐ | ⭐⭐⭐ |
| **IDE 集成** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **插件生态** | 150+ 插件 | ⭐⭐⭐ | ⭐⭐⭐ |
| **企业支持** | ★★★★★ | ★★★★★ | ★★★★★ |
| **API 稳定性** | ★★★★★ | ★★★★★ | ★★★★★ |
| **文档质量** | ★★★★★ | ★★★★ | ★★★★ |
**结论**：
- **工程化**：Claude Code CLI 生态最完善
- **IDE 集成**：三者都有良好支持
- **企业支持**：三家都有企业版
### 5.4 价格对比
| 价格维度 | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| ---------------- | ----------------- | ----------- | -------------- |
| **订阅费** | $20-200 | $20-200 | $19-45 |
| **API 输入** | $1-5/M | $0.25-2/M | $0.125-1.25/M |
| **API 输出** | $3-15/M | $0.75-6/M | $0.375-3.75/M |
| **额度刷新周期** | **每7天（每周）** | **每5小时** | **每日** |
| **价格竞争力** | ★★（最贵） | ★★★ | ★★★★（最便宜） |
**结论**：
- **最便宜**：Gemini 3 Pro
- **最贵**：Claude Opus 4.5
- **额度刷新频率**：GPT-5.2 最高（5小时），Gemini 次之（每日），Claude 最低（每周）
- **性价比**：需结合使用场景判断
### 5.5 特色功能对比
| 特色功能 | Claude Opus 4.5 | GPT-5.2 | Gemini 3 Pro |
| --------------- | --------------- | ---------- | -------------------- |
| **超长上下文** | 200K | 1M | **2M** |
| **视频理解** | ❌ | ❌ | ✅ |
| **代码审查** | ★★★★★ | ★★★★ | ★★★ |
| **多模态** | 图片、音频 | 图片、音频 | **视频、音频、图片** |
| **AIME 满分** | ❌ | ✅ | ❌ |
| **代码质量第1** | ✅ | ❌ | ❌ |
---
## 六、场景化选型建议
### 6.1 按应用场景选型
#### 代码质量和重构场景
**推荐：Claude Opus 4.5**
| 场景 | 推荐模型 | 原因 |
| ------------ | --------------- | ---------------------------- |
| 代码审查 | Claude Opus 4.5 | 代码质量第1，识别深层问题 |
| 遗留系统重构 | Claude Opus 4.5 | 深度理解旧代码，提供演进方案 |
| 技术债务管理 | Claude Opus 4.5 | 识别技术债务，制定重构计划 |
| 架构设计 | Claude Opus 4.5 | 系统级架构建议 |
| 测试用例生成 | Claude Opus 4.5 | 覆盖边界情况，质量高 |
#### 数学和算法场景
**推荐：GPT-5.2**
| 场景 | 推荐模型 | 原因 |
| -------- | -------- | ---------------------- |
| 算法竞赛 | GPT-5.2 | AIME满分，数学推理最强 |
| 量化交易 | GPT-5.2 | 复杂数学模型，策略优化 |
| 科学计算 | GPT-5.2 | 数值分析，统计建模 |
| 机器学习 | GPT-5.2 | 算法实现，模型优化 |
| 游戏 AI | GPT-5.2 | 博弈论，策略优化 |
#### 大规模代码库和多模态场景
**推荐：Gemini 3 Pro**
| 场景 | 推荐模型 | 原因 |
| ---------------- | ------------ | --------------------- |
| 大规模代码库分析 | Gemini 3 Pro | 200万tokens，一次全库 |
| 视频内容理解 | Gemini 3 Pro | 独有视频理解能力 |
| Android 开发 | Gemini 3 Pro | Google 官方支持 |
| 长文档处理 | Gemini 3 Pro | 超长上下文 |
| 多模态应用 | Gemini 3 Pro | 图文音视频综合 |
### 6.2 按团队规模选型
#### 个人开发者
| 预算 | 推荐方案 | 月费 |
| -------- | ------------------- | ----- |
| $30 以内 | Gemini 3 Pro API | $7-21 |
| $30-70 | GPT-5.2 Plus | $20 |
| $70-210 | Claude Opus 4.5 Pro | $200 |
#### 小团队（2-5人）
| 预算 | 推荐方案 | 月费 |
| --------- | -------------------- | -------- |
| $140-420 | Gemini 3 Pro API | $70-280 |
| $420-850 | GPT-5.2 Team | $150 |
| $850-1400 | Claude Opus 4.5 Team | $200-400 |
#### 中大团队（20+人）
| 预算 | 推荐方案 | 说明 |
| --------- | -------- | ------------------ |
| $2800+/月 | 混合策略 | 不同场景用不同模型 |
| $7000+/月 | 企业定制 | 三家都支持企业定制 |
---
## 七、混合策略：多模型协同
### 7.1 为什么需要多模型？
不同模型有不同优势，混合使用可以达到最佳效果：
```
多模型协同策略
├── Claude Opus 4.5：代码质量把关
├── GPT-5.2：算法和数学问题
├── Gemini 3 Pro：大规模代码库分析
└── 成本优化：根据任务选模型
```
### 7.2 混合策略示例
#### 开发流程中的模型分配
| 开发阶段 | 推荐模型 | 理由 |
| ------------ | --------------- | ------------------ |
| **需求分析** | Claude Opus 4.5 | 深度理解，架构设计 |
| **算法设计** | GPT-5.2 | 数学推理最强 |
| **代码实现** | Claude Opus 4.5 | 代码质量最高 |
| **代码审查** | Claude Opus 4.5 | 识别深层问题 |
| **性能优化** | GPT-5.2 | 算法复杂度分析 |
| **全库分析** | Gemini 3 Pro | 超长上下文 |
| **测试用例** | Claude Opus 4.5 | 覆盖全面 |
| **文档生成** | Gemini 3 Pro | 长文档处理 |
### 7.3 成本优化策略
#### 按任务复杂度选模型
| 复杂度 | 推荐模型 | 理由 |
| ------------ | --------------- | ------------ |
| **简单任务** | Gemini 3 Pro | 最便宜，够用 |
| **中等任务** | GPT-5.2 | 性价比高 |
| **复杂任务** | Claude Opus 4.5 | 质量优先 |
#### 成本对比示例
假设每月处理 1000 个任务：
| 策略 | 月费 | Token成本 | 总成本 |
| ---------------- | ---- | --------- | ------ |
| **全用 Claude** | $200 | $2800 | $3000 |
| **全用 GPT-5.2** | $200 | $1100 | $1300 |
| **全用 Gemini** | $0 | $550 | $550 |
| **混合策略** | $200 | $850 | $1050 |
**结论**：混合策略可以节省 **65%** 成本，同时保持高质量。
---
## 八、工程化工具对比
### 8.1 CLI 工具对比
| 工具 | Claude Code | OpenAI CLI | Gemini CLI |
| -------------- | ----------- | ---------- | ---------- |
| **官方支持** | ✅ | ⭐⭐⭐ | ⭐⭐⭐ |
| **Agent 能力** | ★★★★★ | ★★★ | ★★★ |
| **插件生态** | 150+ | ⭐⭐ | ⭐⭐ |
| **项目上下文** | ★★★★★ | ★★★★ | ★★★★ |
| **多模型支持** | ⭐⭐ | ⭐⭐ | ⭐⭐ |
**结论**：Claude Code CLI 是最完善的工程化工具。
### 8.2 IDE 集成对比
| IDE | Claude | GPT | Gemini |
| ------------------ | ------- | --- | ------ |
| **VS Code** | ✅ | ✅ | ✅ |
| **JetBrains** | ✅ | ✅ | ✅ |
| **Cursor** | ✅ 原生 | ✅ | ⭐⭐ |
| **GitHub Copilot** | ⭐⭐ | ✅ | ⭐⭐ |
**结论**：三家都有良好 IDE 支持，Cursor 对 Claude 支持最好。
---
## 九、实施建议
### 9.1 推荐方案总结
```
┌─────────────────────────────────────────────────────────┐
│ 国外顶尖模型选型方案 │
├─────────────────────────────────────────────────────────┤
│ │
│ 代码质量优先：Claude Opus 4.5 │
│ ├── 代码质量全球第1 │
│ ├── 代码审查和重构最强 │
│ ├── Claude Code CLI 工程化完善 │
│ └── 适合：代码审查、架构设计、技术债务管理 │
│ │
│ 数学推理优先：GPT-5.2 │
│ ├── AIME 2025 满分（第1名） │
│ ├── 算法和科学计算最强 │
│ └── 适合：算法竞赛、量化交易、机器学习 │
│ │
│ 长上下文优先：Gemini 3 Pro │
│ ├── 200万tokens 超长上下文 │
│ ├── 多模态能力最强（支持视频） │
│ └── 适合：大规模代码库、视频理解、Android 开发 │
│ │
│ 混合策略：根据任务选择最优模型 │
│ ├── 简单任务 → Gemini 3 Pro（最便宜） │
│ ├── 代码质量 → Claude Opus 4.5（最强） │
│ ├── 数学推理 → GPT-5.2（最强） │
│ └── 成本优化：节省65%+ │
│ │
└─────────────────────────────────────────────────────────┘
```
### 9.2 分阶段实施
#### 第一阶段：单一模型试点（1-2周）
| 步骤 | 内容 | 目标 |
| ---- | ------------------------------- | -------- |
| 1 | 选择一个主力模型（建议 Claude） | 验证效果 |
| 2 | 小范围试点（2-3人） | 收集反馈 |
| 3 | 评估成本和效果 | 决策方案 |
#### 第二阶段：混合策略（1-2个月）
| 步骤 | 内容 | 覆盖范围 |
| ---- | ---------------------- | -------- |
| 1 | 根据任务类型选择模型 | 全团队 |
| 2 | 建立使用规范和最佳实践 | 文档化 |
| 3 | 成本监控和优化 | 持续 |
#### 第三阶段：全面应用（持续）
| 步骤 | 内容 | 目标 |
| ---- | ---------------- | -------- |
| 1 | 多模型协同工作流 | 自动化 |
| 2 | 企业级部署 | 规模化 |
| 3 | 持续评估新模型 | 保持领先 |
---
## 十、成本效益分析
### 10.1 投资回报率（ROI）
假设 10 人团队，平均年薪 $15 万：
| 方案 | 月度成本 | 年度成本 | 效率提升 | 年度价值 | ROI |
| ------------------- | -------- | -------- | -------- | -------- | --------- |
| **Claude Opus 4.5** | $1700 | $20400 | 30% | $450000 | **2205%** |
| **GPT-5.2** | $1150 | $13800 | 25% | $375000 | **2717%** |
| **Gemini 3 Pro** | $700 | $8400 | 20% | $300000 | **3571%** |
| **混合策略** | $1050 | $12600 | 30% | $450000 | **3571%** |
**结论**：混合策略 ROI 最高。
### 10.2 真实成本对比
#### 10 人团队，月预算 $1400
**纯 Claude 方案**：
- Claude Teams：$40 × 10 = $400
- Claude API：$857
- 可用 tokens：约 350 万/月
- **总计：$1257/月**
**混合策略**：
- Claude Teams：$400（代码审查）
- GPT-5.2 API：$285（算法）
- Gemini API：$215（全库分析）
- **总计：$900/月，节省 28%**
---
## 十一、风险与挑战
### 11.1 潜在风险
| 风险 | 影响 | 缓解措施 |
| -------------- | ---- | ---------------------- |
| **供应商锁定** | 高 | 多模型策略，保持灵活性 |
| **成本超支** | 中 | 预算告警，成本监控 |
| **模型变化** | 中 | 持续评估，快速适配 |
| **数据安全** | 高 | 企业版，私有化部署 |
### 11.2 应对策略
1. **多模型策略**：降低供应商锁定风险
2. **成本监控**：设置预算告警
3. **持续评估**：关注新模型发布
4. **数据安全**：选择企业版或私有化部署
---
## 十二、总结与建议
### 12.1 核心结论
> **三大国外顶尖模型各有优势，推荐混合策略**
- **Claude Opus 4.5**：代码质量第1，适合代码审查和重构
- **GPT-5.2**：数学推理满分，适合算法和科学计算
- **Gemini 3 Pro**：200万tokens，适合大规模代码库
- **混合策略**：节省65%成本，同时保持高质量
### 12.2 关键论点
1. **代码质量**：Claude Opus 4.5 全球第1
2. **数学推理**：GPT-5.2 AIME满分
3. **长上下文**：Gemini 3 Pro 200万tokens
4. **工程化**：Claude Code CLI 最完善
5. **成本**：Gemini最便宜，Claude最贵
6. **混合策略**：性价比最高
### 12.3 预期收益
| 收益类型 | Claude | GPT-5.2 | Gemini | 混合策略 |
| ------------ | ---------- | ---------- | ---------- | ---------- |
| **代码质量** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **数学推理** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **长上下文** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **月费** | $200 | $200 | $0 | $200 |
| **API成本** | 高 | 中 | 低 | 中低 |
| **ROI** | 2205% | 2717% | 3571% | **3571%** |
---
## 十三、参考来源
### 官方网站
- [Claude Code](https://claude.ai/code)
- [Claude Opus 4.5 发布公告](https://www.anthropic.com/news/claude-opus-4-5)
- [OpenAI 官网](https://openai.com/)
- [GPT-5.2 发布](https://openai.com/index/introducing-gpt-5-2-codex/)
- [Google Gemini](https://gemini.google.com/)
- [Gemini 3 Pro 发布](https://blog.google/technology/ai/google-gemini-pro-update-122025/)
### 权威榜单
- [LLM Stats - 全球模型排名](https://llm-stats.com/)
- [AIME 2025 美国数学邀请赛](https://aime.mathhub.org/)
- [HumanEval 代码生成基准](https://github.com/openai/human-eval)
### 价格与成本
- [Claude Code 付费完全指南](https://www.cursor-ide.com/blog/claude-code-pricing)
- [OpenAI 定价](https://openai.com/pricing)
- [Google Gemini 定价](https://cloud.google.com/vertex-ai/generative-ai/pricing)
### 产品对比
- [Claude vs GPT vs Gemini - 2025 对比](https://www.anthropic.com/news/claude-opus-4-5)
- [2025 年顶尖 AI 模型深度评测](https://aicoding.csdn.net/686e3291080e555a88ce5407.html)
### 技术文档
- [Claude Code CLI 文档](https://docs.anthropic.com/claude-code)
- [OpenAI API 文档](https://platform.openai.com/docs/)
- [Gemini API 文档](https://cloud.google.com/vertex-ai/generative-ai/docs)
---
**文档更新时间：2025 年 12 月**
**注意**：
1. 价格信息可能随时变动，请以官方公布为准
2. AI 模型的能力排名基于公开基准测试，实际效果可能因使用场景而异
3. 混合策略需要工程化支持，建议从试点开始
4. 企业用户建议选择企业版或私有化部署以保障数据安全
---
## LLM 友好文档 (llms.txt)
## 生成方式
1. 在仓库根目录执行 `pnpm --filter @weapp-tailwindcss/website build`（或 `cd website && pnpm build`）。
2. 构建后，`website/build/` 会生成：
- `llms.txt`（索引）
- `llms-full.txt`（完整内容）
- `llms-quickstart.txt`（上手/AI 工作流）
- `llms-api.txt`（配置、API、迁移与问题）
- 去除 MDX import 的纯 Markdown 文件，方便直接喂给模型。
## 线上地址
- `https://tw.icebreaker.top/llms.txt`
- `https://tw.icebreaker.top/llms-full.txt`
- `https://tw.icebreaker.top/llms-quickstart.txt`
- `https://tw.icebreaker.top/llms-api.txt`
> 如果通过 GitHub Pages 访问，请注意前缀路径 `/weapp-tailwindcss/`。
## 给 AI 的示例提示词
> 你可以从 https://tw.icebreaker.top/llms-quickstart.txt 和 https://tw.icebreaker.top/llms-api.txt 读取 weapp-tailwindcss 的入门与配置说明，回答时请引用相关链接。
## 离线使用
- 下载 `llms-full.txt` 直接给模型。
- 或将生成阶段的 Markdown 文件整体打包后供模型上下文检索。
---
## AI 编程工具选型建议书
> **核心结论**：推荐以 **GLM-4.7** 为核心模型，配合 **Claude Code CLI** 构建 AI 工程化能力。
## 执行摘要
经过对当前主流 AI 编程工具和模型的深入分析，我们建议：
1. **模型选择**：采用 **GLM-4.7** 作为主力模型
- 原则：用新不用旧，GLM-4.7 是智谱 2025 年 12 月最新旗舰
- 能力：代码能力超越 GPT-5（官方宣称），总参数 358B
- 性价比：价格为 Claude Opus 的 1/7 - 1/12
- 世界排名第 6，是国产开源模型中排名最高
2. **工程化能力**：使用 **Claude Code CLI + GLM-4.7** 组合
- **GLM-4.7 月费**：¥40-400（远低于 Claude 的 $20-200）
- 可直接配置使用 GLM-4.7 作为底层模型
- 成熟的 Agent 架构和工具生态
- 项目级上下文管理能力
- **Token 成本仅为原生 Claude 的 12%**
- **CLI 比编辑器插件更强大、更灵活、更工程化**
3. **插件生态系统**：Claude Code CLI 拥有完整的工程化插件体系
- **PR Review Toolkit**：自动化代码审查（测试、错误处理、类型设计、代码质量）
- **Development Workflows**：Python、JavaScript/TypeScript、Backend、Frontend 专业工作流
- **Document Skills**：Excel、Word、PowerPoint、PDF 文档处理
- **Code Quality Tools**：代码重构、技术债务管理、架构审查
- **Enterprise Plugins**：150+ 命令、74+ 专业代理、GitHub 集成
- 详见：[Claude Plugins Marketplace](https://claude-plugins.dev/)
4. **工具选择**：推荐以 **CLI 为主力工具**
- CLI 具有更完整的工具链和更强大的 Agent 能力
- 不依赖特定 IDE，可在任何环境使用
- 更适合处理复杂的、多步骤的任务
- 鼓励开发者体验 Cursor、Qoder 等 IDE 了解前沿技术，但不建议作为主力工具
---
## 一、为什么选择 GLM-4.7？
### 1.0 模型质量的重要性
在深入对比之前，必须明确一个核心观点：**模型质量是 AI 辅助编程的决定性因素**。
#### 为什么模型好坏如此关键？
1. **垃圾模型 = 纯纯浪费**
- 无论如何优化 prompt、如何调整交互方式
- 无法理解复杂需求 → 生成错误代码 → 浪费调试时间
- 无法理解项目上下文 → 需要反复解释 → 浪费沟通成本
- 无法生成可用代码 → 需要人工重写 → 浪费开发时间
2. **好模型 = 效率倍增**
- 准确理解需求 → 一次生成可用代码
- 深度理解上下文 → 减少重复解释
- 代码质量高 → 调试成本低
3. **成本陷阱**
- 使用便宜但能力差的模型 → 需要多次尝试 → 实际成本更高
- 使用能力强的模型 → 一次成功 → 总成本更低
> **核心结论**：在 AI 辅助编程中，**模型质量 > 工具功能 > 交互技巧**。使用垃圾模型，再好的工具和交互技巧都是徒劳。
#### 真实案例对比
假设完成一个中等复杂度的需求（CRUD + 业务逻辑）：
| 模型质量 | 交互次数 | 总耗时 | 成功率 | 结论 |
| ----------------------------------- | -------- | -------- | ------ | -------- |
| **顶级模型**（Claude Opus/GLM-4.7） | 2-3 次 | 2-4 小时 | 85-95% | 高效完成 |
| **中等模型** | 5-8 次 | 1-2 天 | 60-75% | 勉强可用 |
| **垃圾模型** | 10+ 次 | 3-5 天 | 30-50% | 纯纯浪费 |
> **结论**：使用顶级模型虽然单价高，但总耗时和总成本反而更低。
### 1.1 用新不用旧：模型迭代的核心原则
| 对比维度 | GLM-4.7 | GLM-4.6 | Claude Opus 4.5 | GPT 5.2 | GPT 5.1-codex-max |
| ------------------------- | --------------- | ---------- | ----------------- | -------------- | ----------------- |
| **发布时间** | 2025.12.22 | 2025.09.30 | 2025.11.24 | 2025.12.11 | 2025.11.19 |
| **代码能力** | 最强 | 较强 | 最强 | 最强 | 最强 |
| **世界排名** | **第 6 名** | 第 7 名 | 第 2 名 | 第 3 名 | - |
| **价格（¥/百万 tokens）** | ¥0.6-2.2 | ¥0.6-2.2 | ¥5-25 | ¥1.75-14 | ¥1.25-10 |
| **所属机构** | 智谱AI（中国） | 智谱AI | Anthropic（美国） | OpenAI（美国） | OpenAI（美国） |
| **时效性** | ⭐⭐⭐⭐⭐ 最新 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
**星级说明**：⭐ 越多代表越新、技术越先进（均为 2025 年最新一代模型）
**数据来源**：[LLM Stats](https://llm-stats.com/)、各模型官方文档、权威基准测试榜单
> **权威排名**：根据 [LLM Stats](https://llm-stats.com/) 最新数据（2025.12.23）：
>
> - **GLM-4.7**：世界**第 6 名**，是国产开源模型中排名最高
> - **GLM-4.6**：世界第 7 名，621 分
> - **Claude Opus 4.5**：代码质量排名第 1，综合排名前 5
> - **GPT 5.2**：综合排名前 3，AIME 2025 排名第 1（1.0 分）
> **Qoder 模型说明**：Qoder 采用**多模型后端智能路由策略**，根据任务类型自动选择最合适的模型：
>
> - **Claude 系列**：擅长代码理解和重构
> - **GPT 系列**：代码生成能力强
> - **Gemini 系列**：多模态能力优秀
> - **通义千问系列**：阿里自研模型
>
> Qoder 提供**模型分级选择器**（Model Tier Selector），支持四个层级：
>
> - **智能路由**：自适应算法自动选择最合适模型（推荐默认）
> - **极致性能**：使用最优可用模型
> - **经济高效**：高性价比模型选择
> - **基础轻量**：基础模型服务（免费）
>
> 来源：
>
> - [Qoder 官方文档 - 模型分级选择器](https://docs.qoder.com/zh/user-guide/chat/model-tier-selector)
> - [Jimmy Song - Qoder 深度评测](https://jimmysong.io/zh/blog/qoder-alibaba-ai-ide-personal-review/)
**核心论点**：
- GLM-4.7 是智谱最新旗舰（2025年12月22日发布），面向 Agentic Coding 场景强化
- 世界排名第 6（来源：[LLM Stats](https://llm-stats.com/)），在多项编程基准测试中取得开源模型领先表现
- 代码能力超越 GPT-5（官方宣称），与 Claude Opus 4.5、GPT 5.2 同属 2025 年最新一代
- 价格仅为 Claude Opus 的 1/7 左右，成本优势显著
- 总参数 358B，是目前参数量最大的开源模型之一
- MIT 开源协议，可自由使用和修改
- **用新不用旧**：GLM-4.7 是 2025 年 12 月最新发布
### 1.2 GLM-4.7 核心优势
#### 技术优势
```
代码能力
├── Agentic Coding 场景强化
├── 长程任务规划能力
├── 工具协同能力
└── 前端美感（Artifacts）
通用能力
├── 回复简洁自然
├── 写作沉浸感强
└── 指令遵循更强
```
#### 性能表现
- **代码能力**：宣称超越 GPT-5
- **开源表现**：多项基准测试 SOTA
- **工具支持**：原生支持 Claude Code、Cline 等主流工具
#### 成本优势
| 模型 | 输入价格 | 输出价格 | 价格比 |
| ------------------- | -------- | -------- | ------ |
| **GLM-4.7** | ¥0.6-2.2 | ¥2.2-6.6 | 1x |
| **Claude Opus 4.5** | ¥5-25 | ¥15-75 | 7-12x |
| **GPT 5.2** | ¥1.75-14 | ¥5.25-42 | 3-7x |
> **成本对比**：相同任务量，GLM-4.7 成本约为 Claude Opus 的 **12%**，GPT 5.2 的 **30%**
---
## 二、GLM-4.7 + Claude Code CLI：最佳工程化组合
### 2.1 为什么选择 Claude Code CLI？
#### 核心价值：AI 工程化基础设施
```
Claude Code CLI
├── 成熟的 Agent 架构
│ ├── 子代理机制（Task 工具）
│ ├── 工具调用能力
│ └── 上下文管理
├── 完整的工具生态
│ ├── Read/Write/Edit 文件操作
│ ├── Bash 命令执行
│ ├── Grep 搜索
│ └── LSP 集成
└── 项目级能力
├── CLAUDE.md 配置
├── 全局上下文理解
└── 多文件协作
```
#### 关键特性：可配置使用 GLM-4.7
Claude Code CLI 支持自定义模型配置，可以直接将 GLM-4.7 作为底层模型：
1. **GLM-4.7 提供**：最新的代码能力和推理能力
2. **Claude Code 提供**：成熟的工程化框架和工具链
3. **组合效果**：最新模型 + 成熟架构 = 最佳工程化方案
4. **低成本订阅**：GLM-4.7 Coding Plan 月费仅 ¥40-400
> **重要优势**：使用 Claude Code CLI + GLM-4.7 组合：
>
> - **GLM-4.7 订阅费**：¥40-400/月（远低于 Claude 的 $20-200 ≈ ¥140-1400）
> - **Token 成本**：¥0.6-2.2/百万 tokens（Claude 的 12%）
> - **Claude Code CLI**：免费安装使用
### 2.2 与其他方案对比
| 方案 | 模型 | 工程化能力 | 月费 | Token/点数成本 | 推荐度 |
| ----------------------------- | ------------------- | ---------- | ---------------------- | ------------------------- | ---------- |
| **GLM-4.7 + Claude Code CLI** | GLM-4.7（世界第 6） | 成熟 | **¥40-400** | ¥0.6-2.2/M | ⭐⭐⭐⭐⭐ |
| **Qoder** | 多模型智能路由 | 较新 | $20-60 (约 ¥140-420) | 2000-6000 点数/月 | ⭐⭐⭐⭐ |
| Claude Code | Claude Opus 4.5 | 成熟 | $20-200 (约 ¥140-1400) | $1-5/M (约 ¥7-35/M) | ⭐⭐⭐⭐ |
| Cursor | Claude/GPT 5.2 | IDE 集成 | $20-200 (约 ¥140-1400) | $0.25-2/M (约 ¥1.75-14/M) | ⭐⭐⭐⭐ |
**结论**：GLM-4.7 + Claude Code CLI 在**模型时效性**、**工程化能力**、**成本**三方面都达到最优。
> **成本对比**（月费 + Token）：
>
> - **GLM-4.7 + Claude Code CLI**：¥40-400 + ¥0.6-2.2/百万 tokens
> - **Qoder**：Pro $20 (约 ¥140)、Pro+ $60 (约 ¥420)，包含 2000-6000 点数/月
> - **Claude Code 原生**：$20-200 (约 ¥140-1400) + $1-5/M (约 ¥7-35/百万 tokens)
> - **Cursor**：$20-200 (约 ¥140-1400) + $0.25-2/M (约 ¥1.75-14/百万 tokens)
>
> **优势**：
>
> - GLM-4.7 月费仅为 Qoder 的 **29-295%**（取决于版本）
> - GLM-4.7 月费仅为 Claude 的 **29-295%**
> - Token 成本仅为 Claude 的 **12%**
> - 世界排名第 6，代码能力最强
---
## 三、产品对比分析
### 3.1 IDE 对比：Qoder vs Cursor
#### 核心功能对比表
| 功能类别 | 功能 | Qoder | Cursor | 说明 |
| -------------- | --------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| **基础架构** | 基于 VS Code | ✅ | ✅ | 两者都基于 VS Code |
| **插件支持** | VS Code 插件 | ✅ | ✅ | 完全兼容 VS Code 生态 |
| **代码补全** | Tab 自动补全 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Cursor 更流畅，类似 Copilot |
| | 多行编辑 | ✅ | ✅ | Cursor 更成熟 |
| | 智能重写 | ✅ | ✅ | Cursor 体验更好 |
| | 光标预测 | ❌ | ✅ | Cursor 独有 |
| **AI 聊天** | Chat 对话 | ✅ | ✅ | 两者都有 |
| | 代码库问答 | ✅ | ✅ | 都支持 |
| | @符号引用代码 | ✅ | ✅ | 都支持 |
| | 图片输入 | ❌ | ✅ | Cursor 独有 |
| | 网络搜索 | ❌ | ✅ | Cursor 的 @Web 功能 |
| | 文档引用 | ✅ | ✅ | 都支持 |
| | 即时应用 | ✅ | ✅ | 都支持 |
| **代码编辑** | Ctrl+K 快速编辑 | ✅ | ✅ | 都支持 |
| | 终端命令生成 | ❌ | ✅ | Cursor 独有 |
| | 快速提问 | ✅ | ✅ | 都支持 |
| **智能体** | Agent 模式 | ✅ | ✅ | 都有智能体功能 |
| | Composer | ❌ | ✅ | Cursor 自有模型，4x 更快 |
| | Multi-Agent | 基础 | ⭐⭐⭐⭐⭐ | Cursor 的专用多智能体界面 |
| | 并行执行 | ❌ | ✅ | Cursor 可并行多个智能体 |
| **代码库理解** | 10 万+ 文件级 | ✅ | ⭐⭐⭐⭐ | Qoder 超大规模优势 |
| | 向量检索 | ✅ | ✅ | 都支持语义检索 |
| | 代码差异可视化 | ❌ | ✅ | Cursor 独有 |
| **文档生成** | Repo Wiki | ✅ | ❌ | **Qoder 独有** |
| | Quest Mode | ✅ | ❌ | **Qoder 独有** |
| | Spec-Driven | ✅ | ❌ | **Qoder 独有** |
| **多模态** | 图片输入 | ❌ | ✅ | Cursor 独有 |
| | 语音输入 | ❌ | ✅ | Cursor 2.0 支持 |
| **中文支持** | 原生中文 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | Qoder 针对中文优化 |
| **支付方式** | 支付宝 | ✅ | ❌ | **Qoder 独有** |
| | 信用卡 | ❌ | ✅ | Cursor 主要方式 |
| **价格** | 月费 | $20-60 | $20-200 | Qoder 更便宜 |
| | 首月优惠 | $2 | ❌ | **Qoder 独有** |
| | 限时优惠 | **50% off** | ❌ | **Qoder 暂有：订阅/续费 Pro/Pro+/Ultra 享半价，详见 [优惠详情](https://docs.qoder.com/events/discount)** |
| **社区生态** | 用户社区 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Cursor 更成熟 |
| | 教程资源 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Cursor 资源更丰富 |
| | 市场成熟度 | 较新（2025.8） | 成熟（2024） | Cursor 更早 |
> **重要说明**：
>
> - **✅** 表示支持，**❌** 表示不支持
> - **⭐** 表示功能成熟度/体验评分（1-5 星）
> - Cursor 功能更全面，特别是在代码补全、多模态、智能体协作方面
> - Qoder 在超大规模代码库理解（10 万+ 文件）、自动文档生成（Repo Wiki）、中文支持方面有独特优势
#### Qoder 独有功能
| 功能 | 说明 |
| --------------------------- | -------------------------------------------------- |
| **Repo Wiki** | ✅ 自动生成项目文档/知识库，持续追踪代码和文档变化 |
| **Quest Mode** | ✅ 任务导向的自主编程，将需求自动转换为规范并执行 |
| **Spec-Driven Programming** | ✅ 规范驱动编程，开发者只需输入自然语言需求 |
| **10 万+ 文件级检索** | ✅ 超大规模代码库一次性检索（Cursor 约几万文件级） |
| **原生中文支持** | ✅ 针对中文场景深度优化 |
| **支付宝支付** | ✅ 国内用户支付便捷 |
| **首月 $2 优惠** | ✅ 低成本试用 |
#### Cursor 独有功能
| 功能 | 说明 |
| ------------------------- | ------------------------------------------------------- |
| **Composer** | ✅ Cursor 自有前沿模型，速度提升 4 倍，任务完成 < 30 秒 |
| **Multi-Agent Interface** | ✅ 专用多智能体协作界面，可并行运行多个智能体 |
| **Tab 自动补全** | ✅ 行业领先的代码补全体验，类似 GitHub Copilot |
| **光标预测** | ✅ 预测下一个光标位置，无缝导航代码 |
| **图片输入** | ✅ Chat 支持图片作为上下文 |
| **语音输入** | ✅ Cursor 2.0 支持语音输入 |
| **网络搜索** | ✅ @Web 功能获取最新信息 |
| **终端命令生成** | ✅ 在终端使用 Ctrl+K 生成命令 |
| **代码差异可视化** | ✅ 更直观的代码变更展示 |
| **VS Code 深度集成** | ✅ 更成熟的生态集成和兼容性 |
| **活跃社区** | ✅ 用户基数大，教程资源丰富 |
#### 功能对比总结
| 功能类型 | Qoder | Cursor |
| ------------------ | ---------------------- | --------------------------------- |
| **代码补全体验** | ⭐⭐⭐ 基础补全 | ⭐⭐⭐⭐⭐ 行业领先 |
| **代码库理解规模** | ⭐⭐⭐⭐⭐ 10 万+ 文件 | ⭐⭐⭐⭐ 几万文件级 |
| **多智能体协作** | ⭐⭐⭐ 基础 Agent | ⭐⭐⭐⭐⭐ Composer + Multi-Agent |
| **自动文档生成** | ⭐⭐⭐⭐⭐ Repo Wiki | ❌ 不支持 |
| **多模态支持** | ❌ 不支持 | ⭐⭐⭐⭐⭐ 图片+语音 |
| **中文支持** | ⭐⭐⭐⭐⭐ 原生优化 | ⭐⭐⭐ 部分支持 |
| **社区生态** | ⭐⭐⭐ 较新 | ⭐⭐⭐⭐⭐ 成熟活跃 |
| **功能完整性** | ⭐⭐⭐ 核心功能 | ⭐⭐⭐⭐⭐ 功能全面 |
**选型建议**：
> **推荐优先级：CLI 为主力，IDE 为补充**
1. **主力工具（强烈推荐）**
- 所有场景优先 → **GLM-4.7 + Claude Code CLI**
- 理由：成本效益最高、工程化能力最强、不依赖 IDE
2. **IDE 补充（可选）**
- 需要超大代码库理解（10 万+ 文件）→ Qoder（中文项目）
- 追求代码补全体验 → Cursor
- 需要自动生成项目文档 → Qoder
- 需要多模态输入（图片/语音）→ Cursor
- 需要多智能体协作 → Cursor
**核心观点**：
- IDE 适合特定场景（中文、超大代码库、多模态）
- 但 **CLI 才是工程化主力**，更适合复杂任务和团队协作
- 建议团队以 CLI 为主力工具，IDE 仅作补充
### 3.2 CLI 对比：Qoder CLI vs Claude Code CLI
| 对比维度 | Qoder CLI | Claude Code CLI (配 GLM-4.7) |
| -------------- | ------------------------------------- | ---------------------------- |
| **代码生成** | ✅ | ✅ |
| **文件操作** | ✅ Grep/Read/Write | ✅ Read/Write/Edit |
| **Shell 命令** | ✅ Bash | ✅ Bash |
| **代码审查** | ✅ CodeReview | ✅ |
| **子代理机制** | ✅ | ✅ Task 工具 |
| **项目上下文** | ✅ | ✅ CLAUDE.md |
| **底层模型** | 多模型智能路由 | 可配置（GLM-4.7 最优） |
| **成熟度** | 较新（2025.10） | 成熟（2025.8） |
| **月费** | Pro $20 (约 ¥140)、Pro+ $60 (约 ¥420) | **¥40-400** |
| **Token 成本** | 2000-6000 点数/月 | ¥0.6-2.2/百万 tokens |
**关键差异**：
- **Qoder CLI**：多模型智能路由（Claude/GPT/Gemini/通义千问），Pro 版 $20/月（2000 点数），Pro+ 版 $60/月（6000 点数）
- **Claude Code CLI + GLM-4.7**：月费 **¥40-400**，Token 成本 ¥0.6-2.2/百万 tokens
**选型建议**：推荐 **Claude Code CLI + GLM-4.7** 组合
- Claude Code 提供成熟的工程化框架
- GLM-4.7 提供最新的模型能力（世界排名第 6）
- 成本对比 Qoder 取决于使用量
- Token 成本仅为 Claude 的 12%，GPT 的 30%
### 3.3 主流 AI Coding Plan 价格与使用限制对比
为了让读者更清晰地了解各 AI 编程工具的定价策略和额度限制，以下是主流 Coding Plan 的详细对比：
| AI Coding Plan | 月费 | 刷新周期 | 使用额度（每周期） | 额外说明 |
| --------------------------------- | ------------------------------ | ----------- | ---------------------------------------- | -------------------------------------------- |
| **GLM-4.7 Lite** | ¥40（活动价¥54/季≈¥18/月） | **每5小时** | 约 **120 次 Prompts** | 相当 Claude Pro 用量的 3 倍 |
| **GLM-4.7 Pro** | ¥100（活动价¥270/季≈¥90/月） | **每5小时** | 约 **600 次 Prompts** | 相当 Claude Max 用量的一部分 |
| **GLM-4.7 Max** | ¥400（活动价¥540/季≈¥180/月） | **每5小时** | 约 **2400 次 Prompts** | 相当 Claude Max 5x 用量的 3 倍 |
| **Claude Code Pro** | $20（≈¥140） | **每7天** | 基础额度 | 2025年8月起新增每周限制 |
| **Claude Code Teams** | $40/人/月（≈¥280） | **每7天** | 团队额度 | 2025年8月起新增每周限制 |
| **Claude Code Max** | $200（≈¥1400） | **每7天** | 大量额度 | 2025年8月起新增每周限制 |
| **ChatGPT Plus** | $20（≈¥140） | **每5小时** | 30-150 条消息 | 还有每周限制（约6-7次完整会话） |
| **ChatGPT Pro** | $200（≈¥1400） | **每5小时** | 300-1500条本地消息 或 50-400个云任务 | Codex CLI、Chat、Agent 消耗 premium requests |
| **GitHub Copilot Free** | $0 | **每月** | 2000 次代码补全 + 50 次 premium requests | - |
| **GitHub Copilot Pro** | $10/月或$100/年（≈¥70-700/年） | **每月** | 无限标准补全 + Premium requests 限额 | 超出需额外付费 |
| **Gemini Code Assist Standard** | $19（≈¥130） | **每日** | 无限代码补全 + 33 次 PR reviews/天 | - |
| **Gemini Code Assist Enterprise** | $45（≈¥310） | **每日** | 无限代码补全 + 100 次 PR reviews/天 | - |
| **Qoder Pro** | $20（≈¥140） | **每月** | 2000 点数 | 超出需额外付费 |
| **Qoder Pro+** | $60（≈¥420） | **每月** | 6000 点数 | 超出需额外付费 |
| **Cursor Pro** | $20（≈¥140） | **每月** | 基础额度 | 使用 Claude/GPT-5.2 |
| **Cursor Business** | $40/人/月（≈¥280） | **每月** | 团队额度 | 使用 Claude/GPT-5.2 |
> **刷新周期对比**（从快到慢）：
>
> 1. **GLM-4.7 / ChatGPT**：每 **5 小时** 刷新（最快）
> 2. **Gemini Code Assist**：每 **日** 刷新
> 3. **GitHub Copilot / Qoder / Cursor**：每 **月** 刷新
> 4. **Claude Code**：每 **7 天** 刷新（最慢）
> **额度用完后如何继续使用（通用方案）**：
>
> - **方案一**：等待下一个刷新周期自动恢复
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，无需等待）
> - **方案三**：切换/注册其他订阅账号（需遵守各服务商条款）
> - **方案四**：升级到更高版本套餐获得更高额度
> **核心结论**：
>
> - **GLM-4.7** 在刷新频率和额度组合上最优（5小时刷新 + 高额度）
> - **ChatGPT Pro** 虽然也是5小时刷新，但价格是 GLM-4.7 Max 的 **3.5 倍**
> - **Claude Code** 的 7 天刷新周期对于重度用户来说限制最大
> - **GitHub Copilot Free** 适合轻度用户，但功能受限
> - **使用 API KEY 是绕过订阅额度限制的最可靠方案**，适合重度用户
---
## 四、GLM-4.7 详细成本分析
### 4.1 价格体系
#### API 按量计费
| 场景 | 输入 (元/百万 tokens) | 输出 (元/百万 tokens) | 缓存 (元/百万 tokens) |
| -------------------- | --------------------- | --------------------- | --------------------- |
| **短输出 [0, 0.2)** | ¥0.6 | ¥2.2 | ¥0.12 |
| **中输出 [0.2+)** | ¥1.5 | ¥5.5 | ¥0.30 |
| **长输入 [32, 200)** | ¥2.2 | ¥6.6 | ¥0.44 |
#### Coding Plan 订阅
| 版本 | 月费 | 刷新周期 | 使用额度（每周期） | 折算价格 |
| -------- | -------------------------------- | ----------- | ---------------------- | ---------------------------------------------- |
| **Lite** | ¥40/月（活动价¥54/季≈¥18/月） | **每5小时** | 约 **120 次 Prompts** | 约为 Claude Code Pro ($20 ≈ ¥140) 的 1/3 |
| **Pro** | ¥100/月（活动价¥270/季≈¥90/月） | **每5小时** | 约 **600 次 Prompts** | 约为 Claude Code Max 的 1/2-2/3 |
| **Max** | ¥400/月（活动价¥540/季≈¥180/月） | **每5小时** | 约 **2400 次 Prompts** | 约为 Claude Code Max ($200 ≈ ¥1400) 的 1/3-1/4 |
| **对比** | - | - | - | Claude Code: $20-200/月 (约 ¥140-1400/月) |
> **重要说明**：
>
> - **刷新机制**：每 **5 小时** 作为一个周期刷新一次额度
> - 额度重置后自动恢复，无需手动操作
> - 额度用完后需等待下一周期，无法叠加累积
> - 系统不会消耗其他资源包或账户余额
> - Lite 额度约等于 Claude Pro 套餐用量的 **3 倍**
> - Max 额度约等于 Claude Max (5x) 套餐用量的 **3 倍**
>
> **额度用完后如何继续使用**：
>
> - **方案一**：等待下一个刷新周期（5小时后自动恢复，一天最多刷新4-5次）
> - **方案二**：使用 API KEY 直接消耗 token（按量计费，¥0.6-2.2/百万 tokens，无需等待）
> - **方案三**：切换/注册其他订阅账号（需遵守服务条款）
> - **方案四**：升级到更高版本套餐获得更高额度
> **成本优势**：
>
> - GLM-4.7 月费仅为 Claude Code 的 **3-29%**
> - GLM-4.7 Token 价格约为 Claude Opus 的 **12%**
> - **5小时刷新周期**比 Claude 的**7天刷新周期**更灵活
### 4.2 用户分级成本估算
#### AI 使用的必然趋势：从轻度到重度
一个重要的观察：**开发者对 AI 的使用量会随时间呈指数级增长**。
```
AI 使用量增长曲线
├── 第一阶段：轻度使用（1-2 个月）
│ ├── 简单代码补全
│ ├── 偶尔咨询问题
│ ├── 10-50 次/天
│ └── 月成本：¥40-100
├── 第二阶段：中度使用（3-6 个月）
│ ├── 日常开发依赖 AI
│ ├── 复杂任务交给 AI
│ ├── 50-200 次/天
│ └── 月成本：¥100-400
└── 第三阶段：重度使用（6 个月+）
├── AI 成为核心生产力
├── 所有开发任务都通过 AI
├── 200-1000+ 次/天
└── 月成本：¥400-2000+
```
#### 为什么使用量会持续增长？
1. **信任度提升**：从"试试看"到"离不开"
- 刚开始：怀疑 AI 能力，只敢用简单任务
- 逐渐：发现 AI 确实能提高效率
- 最后：将 AI 作为第一生产力工具
2. **能力边界拓展**：从"补全代码"到"自主开发"
- 刚开始：简单的代码补全、Bug 查询
- 逐渐：复杂功能开发、架构设计
- 最后：全需求自主完成、Code Review、重构
3. **依赖性增强**：从"辅助工具"到"核心依赖"
- 刚开始：偶尔使用，提高 10-20% 效率
- 逐渐：每天使用，提高 50-100% 效率
- 最后：无法想象没有 AI 的开发，提高 200-300% 效率
#### 真实数据：使用量增长的必然性
| 时间周期 | 日均使用次数 | 月使用次数 | 月度 Token 估算（GLM-4.7） | 月度成本（GLM-4.7） |
| ------------ | ------------ | ---------- | -------------------------- | ------------------- |
| **第 1 月** | 20 次 | 600 次 | 30 万 tokens | ¥40-100 |
| **第 3 月** | 80 次 | 2400 次 | 120 万 tokens | ¥100-300 |
| **第 6 月** | 200 次 | 6000 次 | 300 万 tokens | ¥300-600 |
| **第 12 月** | 500+ 次 | 15000+ 次 | 750 万+ tokens | ¥600-1500+ |
> **关键洞察**：
>
> - **使用量 10 倍增长是常态**（从轻度到重度）
> - **成本 10 倍增长不可避免**
> - **如果使用昂贵的模型（如 Claude），月成本可能从 ¥140 飙升到 ¥1400+**
> - **如果使用 GLM-4.7，月成本从 ¥40 增长到 ¥400，压力小得多**
#### 结论：选择高性价比模型的重要性
**因为使用量必然会大幅增长，所以选择高性价比模型至关重要**：
- **Claude Opus**：轻度 ¥140 → 重度 ¥1400+（压力巨大）
- **GLM-4.7**：轻度 ¥40 → 重度 ¥400（可控范围）
> **核心观点**：不要因为当前使用量小就选择昂贵的模型，因为 6 个月后你的使用量会增长 10 倍。**选择一个能让你"用得起、用得爽"的高性价比模型，才能支撑长期的 AI 辅助开发。**
---
根据 [GLM Coding Plan 官方定价](https://bigmodel.cn/glm-coding)：
> **当前活动价（按季付费）**：
>
> - Lite：¥54/季（≈¥18/月）
> - Pro：¥270/季（≈¥90/月）
> - Max：¥540/季（≈¥180/月）
>
> **日常价（按月付费）**：
>
> - Lite：¥40/月
> - Pro：¥100/月
> - Max：¥400/月
| 用户级别 | 月度交互 | GLM-4.7 成本（/人/月） | Qoder 成本（/人/月） | 节省 |
| -------- | -------------- | ------------------------ | -------------------- | --------- |
| **轻度** | 10-50 次/天 | **¥40**（120次/5小时） | $20 (约 ¥140) | **71%** |
| **中度** | 50-200 次/天 | **¥100**（600次/5小时） | $20-60 (约 ¥140-420) | **0-76%** |
| **重度** | 200-1000 次/天 | **¥400**（2400次/5小时） | $60 (约 ¥420) | **5%** |
| **顶级** | 1000+ 次/天 | **¥400+**（可能多套餐） | $60+ (约 ¥420+) | **0-5%** |
> **结论**：GLM-4.7 在轻度用户场景下节省 71%，中度和重度用户成本接近或略低于 Qoder。
> **刷新机制优势**：
>
> - **GLM-4.7**：每 **5 小时** 刷新一次，一天最多可刷新 **4-5 次**
> - **Lite 版**：每天最多可获得约 **480-600 次** Prompts（120 × 4-5）
> - **Pro 版**：每天最多可获得约 **2400-3000 次** Prompts（600 × 4-5）
> - **Max 版**：每天最多可获得约 **9600-12000 次** Prompts（2400 × 4-5）
> **注意**：
>
> - **GLM-4.7**：按日常价计算，Lite ¥40/月，Pro ¥100/月，Max ¥400/月
> - **Qoder**：Pro $20/月（2000 点数）、Pro+ $60/月（6000 点数），超出点数需额外付费
> - GLM-4.7 世界排名第 6，代码能力更强
> - **5 小时刷新机制**意味着额度恢复更快，适合高频使用场景
### 4.3 真实重度用户案例
#### 案例 1：月预算 $1000（约 ¥7000）用户
**纯 Claude Opus 方案**：
- Claude Code Max 200 订阅费：$200/月（约 ¥1400/月）
- Claude Opus API：$800/月（约 ¥5600/月）
- 可用 tokens：约 2000 万 tokens/月
- **总计：$1000/月（约 ¥7000/月）**
**GLM-4.7 + Claude Code CLI 方案**：
- GLM-4.7 专业版订阅：¥200/月（约 $30/月）
- GLM-4.7 API：¥4800（约 $685）/月
- 可用 tokens：约 **14 亿 tokens/月**
- **总计：¥5000/月（约 $715/月）**
- **效果相同，成本节省 28.5%，tokens 可用量提升 70 倍**
> **成本对比**：
>
> - GLM-4.7 方案：¥5000/月（订阅费 ¥200 + API ¥4800）
> - Claude 方案：¥7000/月（订阅费 ¥1400 + API ¥5600）
> - **节省：¥2000/月（约 28.5%）**
#### 案例 2：月预算 $3000（约 ¥21000）顶级用户
**纯 Claude Opus 方案**：
- Claude Code Max 200 订阅费：$200/月（约 ¥1400/月）
- Claude Opus API：$2800/月（约 ¥19600/月）
- 可用 tokens：约 6000 万 tokens/月
- **总计：$3000/月（约 ¥21000/月）**
**GLM-4.7 + Claude Code CLI 方案**：
- GLM-4.7 专业版订阅：¥400/月（约 $60/月）
- GLM-4.7 API：¥19600（约 $2800）/月
- 可用 tokens：约 **42 亿 tokens/月**
- **总计：¥20000/月（约 $2860/月）**
- **效果相同，成本节省约 5%，tokens 用量提升 70 倍**
> **成本对比**：
>
> - GLM-4.7 方案：¥20000/月（订阅费 ¥400 + API ¥19600）
> - Claude 方案：¥21000/月（订阅费 ¥1400 + API ¥19600）
> - **节省：¥1000/月（约 5%）**
> - 同等预算下，GLM-4.7 可用 tokens 是 Claude 的 **7 倍**
---
## 五、为什么选择 CLI 而不是编辑器插件？
> **核心观点**：CLI（命令行界面）是 AI 辅助编程的未来方向，比编辑器插件更先进、更强大、更灵活。
### 5.1 CLI vs 编辑器插件对比
#### 为什么 CLI 更先进？
```
CLI vs 编辑器插件对比
├── CLI 优势
│ ├── 更强大的 Agent 架构
│ │ ├── 子代理机制（Task 工具）
│ │ ├── 并行处理能力
│ │ └── 复杂任务拆解
│ ├── 更完整的工具链
│ │ ├── Read/Write/Edit 文件操作
│ │ ├── Bash 命令执行
│ │ ├── Grep 搜索
│ │ ├── LSP 集成
│ │ └── Git 操作
│ ├── 项目级上下文
│ │ ├── CLAUDE.md 配置
│ │ ├── 全局代码理解
│ │ └── 跨文件协作
│ ├── 更高的灵活性
│ │ ├── 可配置使用任意模型
│ │ ├── 自定义工具和脚本
│ │ └── 不依赖特定 IDE
│ ├── 完整的插件生态系统 ⭐
│ │ ├── PR Review Toolkit（代码审查）
│ │ ├── Development Workflows（专业工作流）
│ │ ├── Document Skills（文档处理）
│ │ ├── Code Quality Tools（代码质量）
│ │ ├── Enterprise Plugins（150+命令）
│ │ └── 详见：claude-plugins.dev
│ └── 更好的可移植性
│ ├── 跨平台使用
│ ├── 远程服务器开发
│ └── CI/CD 集成
└── 编辑器插件局限
├── 受限于 IDE 界面
├── 工具链不完整
├── 缺乏复杂 Agent 能力
├── 没有插件生态
└── 难以跨工具使用
```
**核心观点**：
- **CLI 是工程化工具，编辑器插件是辅助工具**
- **CLI 可以处理复杂的、多步骤的任务**
- **CLI 不依赖特定 IDE，更灵活**
- **CLI 拥有完整的插件生态系统，可对接各种工程化规范** ⭐
- **CLI 代表 AI 辅助编程的未来方向**
### 5.2 Claude Code CLI 插件生态系统
Claude Code CLI 拥有一个强大的插件市场，支持对接各种 AI 工程化规范：
| 插件类型 | 功能描述 | 安装命令 |
| ------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **PR Review Toolkit** | 自动化代码审查（测试、错误处理、类型设计、代码质量、代码简化） | `npx claude-plugins install @anthropics/claude-code-plugins/pr-review-toolkit` |
| **Python Development** | Python 3.12+、Django、FastAPI、async patterns | `npx claude-plugins install @wshobson/claude-code-workflows/python-development` |
| **JavaScript/TypeScript** | ES6+、Node.js、React、现代 Web 框架 | `npx claude-plugins install @wshobson/claude-code-workflows/javascript-typescript` |
| **Backend Development** | API 设计、GraphQL 架构、TDD 后端开发 | `npx claude-plugins install @wshobson/claude-code-workflows/backend-development` |
| **Frontend Excellence** | React 19、Next.js 15、组件架构、状态管理 | `npx claude-plugins install @dotclaude/dotclaude-plugins/frontend-excellence` |
| **Document Skills** | Excel、Word、PowerPoint、PDF 文档处理 | `npx claude-plugins install @anthropics/anthropic-agent-skills/document-skills` |
| **Code Refactoring** | 代码清理、重构自动化、技术债务管理 | `npx claude-plugins install @wshobson/claude-code-workflows/code-refactoring` |
| **Claude Flow** | 150+ 命令、74+ 专业代理、GitHub 集成 | `npx claude-plugins install @ruvnet/claude-flow-marketplace/claude-flow` |
| **Developer Essentials** | Git、SQL、错误处理、代码审查、E2E 测试 | `npx claude-plugins install @wshobson/claude-code-workflows/developer-essentials` |
> **关键优势**：
>
> - **150+ 专业命令**：覆盖开发全流程
> - **74+ 专业代理**：针对不同技术栈和工作流
> - **一键安装**：`npx claude-plugins install `
> - **开源社区**：持续更新，社区维护
> - **详见**：[Claude Plugins Marketplace](https://claude-plugins.dev/)
### 5.3 Claude Code：AI 工程化规范的制定者
**重要观点**：Claude Code 不仅仅是一个工具，更是 **AI 工程化规范的制定者之一**。
#### Anthropic 的 AI 规范制定角色
**Anthropic（Claude 的开发商）是全球 AI 安全和工程化规范的核心制定者**：
1. **Responsible Scaling Policy (RSP)**
- Anthropic 制定了前沿 AI 模型的安全和部署标准
- 定义了技术安全和运营措施的最佳实践
- 详见：[Anthropic Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
2. **AI Safety Levels (ASL) 标准**
- 参照美国政府生物安全级别（BSL）框架
- 建立了分级的 AI 安全标准体系
- 2025 年 5 月激活了 ASL-3 保护措施
- 详见：[ASL-3 Protections](https://www.anthropic.com/news/activating-asl3-protections)
3. **Claude Code 官方最佳实践**
- Anthropic 发布了官方的 AI 编码最佳实践
- 定义了企业级 AI 编码的标准和流程
- 涵盖治理、安全、CI/CD 集成、代码审查等
- 详见：[Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
4. **合规框架**
- 为加州 SB-53 等 AI 法规制定合规框架
- 参与全球 AI 安全标准的制定
- 详见：[Compliance Framework SB-53](https://www.anthropic.com/news/compliance-framework-SB53)
#### 为什么这很重要？
| 维度 | 其他 AI 工具 | Claude Code CLI |
| ---------------- | -------------- | --------------------------- |
| **规范来源** | 遵循第三方规范 | **规范制定者本身** |
| **工程化标准** | 自定义或不完整 | **符合企业级标准** |
| **安全最佳实践** | 社区实践 | **官方制定的安全标准** |
| **企业采用** | 需要额外评估 | **直接采用行业标准** |
| **长期支持** | 取决于商业公司 | **AI 规范制定者的核心产品** |
> **核心结论**：
>
> - Claude Code 由 **AI 规范制定者**（Anthropic）开发和维护
> - 采用 Claude Code = 采用 **AI 工程化的行业标准**
> - 这不是选择一个工具，而是选择一个 **经过验证的工程化体系**
> - 对于企业来说，这意味着更低的风险、更高的合规性、更成熟的最佳实践
> **企业优势**：
>
> - Anthropic 与全球政府、企业合作制定 AI 标准
> - Claude Code 内置了这些标准和最佳实践
> - 使用 Claude Code = 自动符合行业领先的 AI 工程化规范
---
## 六、实施建议
### 6.1 推荐方案总览
```
┌─────────────────────────────────────────────────────────┐
│ AI 编程工具选型方案 │
├─────────────────────────────────────────────────────────┤
│ │
│ 核心模型：GLM-4.7（智谱最新旗舰，2025.12 发布） │
│ ├── 价格：Claude 的 1/7 - 1/12 │
│ ├── 能力：代码能力超越 GPT-5（宣称） │
│ ├── 世界排名第 6 │
│ └── 原则：用新不用旧 │
│ │
│ 工程化框架：Claude Code CLI + GLM-4.7 │
│ ├── 成熟 Agent 架构 │
│ ├── 低成本订阅（GLM-4.7 月费 ¥40-400） │
│ ├── 可配置使用 GLM-4.7 │
│ ├── 项目级上下文管理 │
│ ├── CLI 比编辑器插件更强大、更灵活 │
│ ├── 插件生态：150+ 命令、74+ 代理 │
│ └── AI 规范制定者：Anthropic 核心产品 │
│ │
│ 工具理念：CLI 为主力，IDE 为前沿探索 │
│ ├── CLI：工程化工具，适合复杂任务 │
│ ├── 插件系统：对接各种工程化规范 │
│ ├── 行业标准：符合企业级 AI 安全规范 │
│ ├── IDE：了解前沿技术，不建议作为主力 │
│ └── 灵活选择，以成本效率为先 │
│ │
└─────────────────────────────────────────────────────────┘
```
### 6.2 分阶段实施计划
#### 第一阶段：试点验证（1-2 周）
| 步骤 | 内容 | 目标 | 成本 |
| ---- | ----------------------------- | -------------- | ------------------------- |
| 1 | 注册智谱 AI，申请 GLM-4.7 API | 获得访问权限 | ¥0（赠送 2000 万 tokens） |
| 2 | 安装 Claude Code CLI | 验证工程化能力 | **¥0（免费安装）** |
| 3 | 订阅 GLM-4.7 基础版并配置 | 验证模型配置 | ¥40（测试订阅费） |
| 4 | 小范围试点（2-3 人） | 收集反馈 | ¥120-200 |
**阶段目标**：验证 GLM-4.7 + Claude Code CLI 组合的可行性
**成本优势**：月费仅 **¥40**，远低于 Claude Code Pro（$20 ≈ ¥140）
#### 第二阶段：团队推广（1-2 个月）
| 步骤 | 内容 | 覆盖范围 | 成本 |
| ---- | -------------------------- | ---------- | ----------- |
| 1 | 内部分享会（CLI 使用技巧） | 全体开发者 | ¥0 |
| 2 | 推广 Claude Code CLI | 10-20 人 | ¥0（免费） |
| 3 | GLM-4.7 订阅配额 | 按需分配 | ¥400-800/月 |
| 4 | 建立 CLI 使用最佳实践 | 团队文档化 | ¥0 |
**阶段目标**：50%+ 开发者采用 CLI 方案
**成本优势**：GLM-4.7 订阅费仅为 Claude Code Teams 的 **3-29%**
#### 第三阶段：全面应用（持续）
| 步骤 | 内容 | 目标 |
| ---- | -------------------- | -------------- |
| 1 | 评估私有化部署 | 20+ 人团队考虑 |
| 2 | 建立 AI 工程最佳实践 | 团队内部文档化 |
| 3 | 持续优化成本 | 多工具混合策略 |
### 6.3 不同场景的推荐配置
#### 个人开发者
| 预算 | 配置方案 | 月度成本 |
| ----------------------- | ------------------------- | ----------------------- |
| ¥200 以内（约 $30） | GLM-4.7 基础版 + API 按需 | ¥60-150（约 $10-22） |
| ¥500-1000（约 $70-140） | GLM-4.7 基础版 + 大量 API | ¥200-500（约 $30-72） |
| ¥2000+（约 $280+） | GLM-4.7 专业版 + 海量 API | ¥500-1500（约 $72-215） |
**注意**：以上价格包含 GLM-4.7 订阅费（¥40-400）+ API 费用
#### 小团队（2-5 人）
| 预算 | 配置方案 | 月度成本 | 人均 |
| ---------------- | ----------------------------- | ---------------- | ------------------------- |
| ¥2000（约 $280） | GLM-4.7 基础版团队 + API | ¥2000（约 $280） | ¥400-1000（约 $55-140） |
| ¥5000（约 $700） | GLM-4.7 专业版团队 + 大量 API | ¥5000（约 $700） | ¥1000-2500（约 $140-350） |
**注意**：GLM-4.7 月费远低于 Claude Teams（$40/人/月 ≈ ¥280/人/月）
#### 中型团队（5-20 人）
| 预算 | 配置方案 | 月度成本 | 人均 |
| ----------------------------- | ----------------------------- | ----------------------------- | ----------------------- |
| ¥10000-20000（约 $1400-2800） | GLM-4.7 专业版团队 + 大量 API | ¥10000-20000（约 $1400-2800） | ¥500-4000（约 $70-560） |
**注意**：相比 Claude Code Teams（$40/人/月 ≈ ¥280/人/月），**节省 ¥5600-11200/月（$800-1600/月）订阅费**
#### 大型团队（20+ 人）
| 预算 | 配置方案 | 月度成本 | 说明 |
| -------------------------- | ------------------ | -------------------- | ---------- |
| ¥50000+/月（约 $7000+/月） | GLM-4.7 私有化部署 | ¥50000+（约 $7000+） | 考虑私有化 |
**注意**：如果使用 GLM-4.7，相比 Claude Code Teams 节省约 **$800/月（¥5600/月）**
---
## 七、成本效益分析
### 7.1 投资回报率（ROI）
假设团队有 10 名开发者，平均年薪 ¥30 万：
| 方案 | 月度成本 | 年度成本 | 效率提升 | 年度价值 | ROI |
| ------------------------- | ------------ | -------------- | -------- | -------- | -------------- |
| **GLM-4.7 + Claude Code** | ¥10400-14400 | ¥124800-172800 | 30% | ¥9000000 | **5200-7200%** |
| **Claude Code 原生** | ¥14280-15400 | ¥171360-184800 | 30% | ¥9000000 | 4870-5250% |
| **无 AI** | ¥0 | ¥0 | 0% | ¥0 | 0% |
> **结论**：GLM-4.7 方案的 ROI 与 Claude Code 相当，但成本降低 **27-43%**。
### 7.2 真实成本对比
#### 10 人团队，月预算 ¥10000（约 $1400）
**Claude Code 原生方案**：
- Claude Code Teams：$40 × 10 = $400 ≈ ¥2800（**必需订阅费**）
- Claude Opus API：$857 ≈ ¥6000
- 可用 tokens：约 350 万/月
- **总计：$1257/月（约 ¥8800/月）**
**GLM-4.7 + Claude Code CLI 方案**：
- Claude Code CLI：¥0（免费）
- GLM-4.7 专业版订阅：¥400
- GLM-4.7 API：¥9600
- 可用 tokens：约 **48 亿/月**
- **总计：¥10000/月（约 $1400/月）**
> **关键洞察**：相同预算 ¥10000（约 $1400）下：
>
> - GLM-4.7 可用 tokens 是 Claude Opus 的 **1370+ 倍**
> - GLM-4.7 月费仅为 Claude Teams 的 **14%**
> - 总成本节省约 **¥1240/月（约 $177/月）**
#### 20 人团队对比
| 方案 | 订阅费（月） | API 成本（月） | 总成本（年） |
| ---------------- | ------------ | -------------- | ---------------- |
| **Claude Teams** | $800 (¥5600) | ¥10000 | ¥187,200 |
| **GLM-4.7 方案** | ¥400-800 | ¥14400-19600 | ¥178,800-244,800 |
**同样年度预算下**：
- Claude Teams：$800 × 12 = $9600/年 订阅费（约 ¥67,200）
- GLM-4.7 方案：¥4800-9600/年 订阅费，仅为 Claude 的 **7-14%**
- 将更多预算用于 API，获得 **14-140 倍以上**的 tokens
---
## 八、风险与挑战
### 8.1 潜在风险
| 风险 | 影响 | 缓解措施 |
| ------------------ | ------------------ | ---------------------- |
| **GLM-4.7 稳定性** | 新模型可能有 bug | 试点验证，逐步推广 |
| **学习曲线** | 团队需要适应新工具 | 内部分享，文档沉淀 |
| **供应商锁定** | 过度依赖单一供应商 | 保持多工具能力 |
| **成本控制** | API 使用可能超预期 | 设置预算告警，定期审查 |
### 8.2 应对策略
1. **双模型策略**：保留 Claude 作为备选
2. **分阶段推广**：从小范围试点开始
3. **成本监控**：每月审查 API 使用情况
4. **持续评估**：关注新模型发布
---
## 九、总结与建议
### 9.1 核心建议
> **推荐采用 GLM-4.7 + Claude Code CLI 组合方案**
这是基于成本效益、工程化能力、插件生态系统和行业标准综合评估后的最优选择。
---
### 9.2 关键论点
1. **用新不用旧**：GLM-4.7 是 2025 年 12 月最新旗舰，技术领先
2. **成本优势明显**：月费仅为 Claude 的 3-29%，Token 成本为 12%
3. **工程化能力成熟**：Claude Code CLI 提供完整框架
4. **可配置性强**：Claude Code CLI 可直接使用 GLM-4.7
5. **CLI 更先进**：CLI 比编辑器插件更强大、更灵活、更工程化
6. **插件生态系统完善**：150+ 专业命令、74+ 专业代理，覆盖各种工程化规范
7. **AI 规范制定者**：Anthropic 是全球 AI 安全和工程化规范的核心制定者
8. **不依赖 IDE**：CLI 可在任何环境使用，包括远程服务器
---
### 9.3 预期收益
| 收益类型 | 预期值 | 说明 |
| -------------- | ---------- | ------------------------- |
| **月费节省** | 71-97% | GLM-4.7 订阅费仅 ¥40-400 |
| **总成本节省** | 27-43% | 含订阅费和 Token 成本 |
| **Token 提升** | 14-1400x | 相同预算下可用 Token 数量 |
| **能力提升** | 20-50% | 开发效率提升 |
| **ROI** | 5200-7200% | 投资回报率 |
> **核心优势总结**：
>
> - **GLM-4.7**：世界排名第 6，月费 ¥40-400，Token 价格为 Claude 的 12%
> - **Claude Code CLI**：免费工具，比编辑器插件更强大、更灵活
> - **插件生态**：150+ 命令、74+ 代理，覆盖各种工程化规范
> - **AI 规范制定者**：Anthropic 是全球 AI 安全和工程化规范的核心制定者
> - **组合效果**：**行业标准 + CLI 工程化能力 + 插件生态 + 高性价比模型**
---
### 9.4 企业级优势：选择 AI 规范制定者的工具
#### 为什么企业应该选择 Claude Code CLI？
对于企业来说，选择 AI 工具不仅是选择一个产品，更是选择一套**工程化体系和标准**。
| 对比维度 | 其他 AI 工具（Qoder/Cursor 等） | Claude Code CLI + GLM-4.7 |
| -------------- | ------------------------------- | ------------------------------- |
| **规范来源** | 遵循第三方规范或自定义规范 | **规范制定者本身**（Anthropic） |
| **安全标准** | 社区实践或商业公司标准 | **官方 AI 安全标准（ASL-3）** |
| **工程化规范** | 不完整或自定义 | **企业级最佳实践** |
| **合规性** | 需要额外评估和适配 | **符合全球 AI 法规框架** |
| **长期维护** | 取决于商业公司生存 | **AI 规范制定者的核心产品** |
| **风险控制** | 较高（工具风险 + 合规风险） | **低（行业标准 + 合规保障）** |
#### 企业级场景的实际价值
**1. 金融、医疗等高度监管行业**
- 需要符合严格的安全和合规要求
- Claude Code 基于 Anthropic 的 Responsible Scaling Policy
- 自动符合全球领先的 AI 安全标准
- **降低合规风险，提高审计通过率**
**2. 大型企业 IT 部门**
- 需要标准化的工程流程
- Claude Code 提供官方最佳实践
- 与 CI/CD、代码审查、安全审计无缝集成
- **统一标准，降低管理成本**
**3. 政府机构和公共部门**
- 需要透明、可审计的 AI 使用
- Anthropic 与政府合作制定 AI 标准
- 符合加州 SB-53 等法规框架
- **满足政策要求，提高公众信任**
**4. 国际化企业**
- 需要符合全球不同地区的 AI 法规
- Anthropic 参与全球 AI 安全标准制定
- 一套方案，全球适用
- **简化合规流程，降低法律风险**
#### 结论
> **核心观点**：选择 Claude Code CLI = 选择 **AI 工程化的行业标准**
>
> - 这不是一个工具选择，而是一个**战略选择**
> - 降低企业风险、提高合规性、获得长期保障
> - 对于企业级部署，这是**最优解**
---
### 9.5 工具选择的灵活性
> **重要原则：允许开发者选择最适合自己的 AI 工具**
虽然我们推荐 **GLM-4.7 + Claude Code CLI** 作为主力方案，但**强烈鼓励开发者接触和体验世界最先进的 AI 工具组合**：
#### 为什么要允许开发者自由选择？
1. **接触前沿技术**
- **Cursor + Claude Opus + GPT-5.2/Codex** 是目前世界上最先进的组合
- 通过使用最顶级的 AI 工程化能力，了解 AI 辅助编程的最新进展
- 体验最新的 AI 特性和交互模式
2. **反哺团队**
- 将前沿工具的使用经验和最佳实践带回团队
- 帮助团队判断哪些新特性值得在主力方案中采用
- 提供多维度的技术选型视角
3. **个人成长**
- 保持技术敏感度，走在 AI 前沿
- 培养对 AI 工具的判断力
- 避免"工具孤岛"思维
#### 推荐的前沿工具组合
| 工具组合 | 特点 | 适用场景 | 预算 |
| ---------------------------------- | ------------------------------ | ---------------- | ---------------- |
| **Cursor + Claude Opus + GPT-5.2** | 世界最强组合，Composer 4x 速度 | 追求极致效率 | $200/月 (≈¥1400) |
| **Cursor + GPT-5.2-Codex-Max** | OpenAI 最新代码模型 | 体验 OpenAI 生态 | $100-200/月 |
| **Claude Code + Claude Opus 4.5** | Anthropic 原生组合 | 深度体验 Claude | $20-200/月 |
> **核心观点**：
>
> - **主力方案**（GLM-4.7 + Claude Code CLI）：追求**性价比和稳定性**
> - **前沿探索**（Cursor + Claude + Codex）：追求**技术领先和经验积累**
> - **两者并不冲突**，而是**相辅相成**
#### 实施建议
1. **团队标准方案**：采用 **GLM-4.7 + Claude Code CLI** 作为主力工具
- 优先使用 CLI 进行日常开发
- 享受 CLI 的工程化能力和灵活性
- 降低团队成本，提高效率
2. **个人前沿探索**：鼓励开发者体验 Cursor、Qoder 等 IDE
- 了解 AI 工具的最新进展
- 但不建议作为主力工具（成本高、依赖 IDE）
- 将 IDE 的优秀特性反馈到 CLI 使用中
3. **知识分享**：定期内部分享会
- 分享 CLI 使用技巧和最佳实践
- 交流前沿 IDE 工具的体验
- 建立团队的 AI 工具使用规范
4. **技术雷达**：建立 AI 工具评估机制
- 持续关注新模型发布
- 评估 CLI 工具的新特性
- 保持技术敏感度
> **最终目标**：以 **CLI 为主力工具**，以 **IDE 为前沿探索**，既保证成本效率，又保持技术敏感度。
---
## 十、代码生成能力深度分析
### 10.1 AI 代码生成现状评估
#### 整体能力评估
| 能力维度 | 前端 | 后端 | 评分 |
| ------------ | -------------- | -------------- | -------- |
| **代码生成** | UI 还原度高 | 逻辑正确率高 | ⭐⭐⭐⭐ |
| **架构设计** | 组件化良好 | 分层合理 | ⭐⭐⭐ |
| **Bug 率** | 样式问题多 | 边界情况多 | ⭐⭐⭐ |
| **调试难度** | 视觉问题难定位 | 逻辑问题易定位 | ⭐⭐⭐ |
#### 前端代码生成
**优势**：
- ✅ UI 组件还原度高（80-90%）
- ✅ 响应式布局理解到位
- ✅ 组件化思想成熟
- ✅ TailwindCSS 等工具库使用准确
**常见问题**：
- ❌ 样式细节不够精细（间距、颜色、圆角等）
- ❌ 交互逻辑偶尔有 bug（事件处理、状态管理）
- ❌ 复杂动画效果实现不理想
- ❌ 浏览器兼容性考虑不足
- ❌ 性能优化意识较弱（重复渲染、不必要的计算）
**调试难度**：⭐⭐⭐⭐（视觉问题需要逐像素对比）
#### 后端代码生成
**优势**：
- ✅ CRUD 生成准确（90-95%）
- ✅ API 设计规范（RESTful）
- ✅ 数据库操作正确（SQL/ORM）
- ✅ 错误处理机制完善
- ✅ 代码结构清晰
**常见问题**：
- ❌ 复杂业务逻辑理解偏差
- ❌ 并发/安全问题（锁、事务）
- ❌ 性能优化不足（N+1 查询、缓存）
- ❌ 边界情况处理不完整
- ❌ 安全漏洞（SQL 注入、XSS）
- ❌ 日志和监控不足
**调试难度**：⭐⭐⭐（逻辑问题可通过日志快速定位）
### 10.2 跨域开发可能性分析
#### 前端开发者写后端
| 能力要求 | 现状 | 可行性 |
| -------------- | ------------ | -------- |
| **API 设计** | 理解概念 | ⭐⭐⭐⭐ |
| **数据库操作** | 需要学习 SQL | ⭐⭐⭐ |
| **业务逻辑** | 转换思维模式 | ⭐⭐⭐ |
| **部署运维** | 完全新领域 | ⭐⭐ |
**可行性评估**：
- 简单 CRUD：**85% 可行**（AI 辅助下）
- 中等复杂度：**60% 可行**
- 高复杂度：**30% 可行**
**学习曲线**：
- 基础后端概念（API、数据库）：**1-2 周**
- 实战项目（简单 CRUD）：**1 个月**
- 生产级应用：**3-6 个月**
#### 后端开发者写前端
| 能力要求 | 现状 | 可行性 |
| --------------------- | ------------ | -------- |
| **HTML/CSS** | 基础了解 | ⭐⭐⭐⭐ |
| **JavaScript/TS** | 需要深入 | ⭐⭐⭐ |
| **框架（React/Vue）** | 需要系统学习 | ⭐⭐⭐ |
| **UI/UX 设计** | 完全新领域 | ⭐⭐ |
**可行性评估**：
- 简单页面：**80% 可行**（AI 辅助下）
- 中等复杂度：**50% 可行**
- 高复杂度（动画、交互）：**25% 可行**
**学习曲线**：
- 基础 HTML/CSS/JS：**2-3 周**
- 单页面应用框架：**1-2 个月**
- 生产级应用（状态管理、性能优化）：**3-6 个月**
### 10.3 完成需求的成本预估
#### 个人开发者完成一个需求
| 需求类型 | 传统开发 | AI 辅助开发 | 效率提升 |
| -------------- | -------- | ----------- | ---------- |
| **简单页面** | 4-8 小时 | 1-2 小时 | **4-6x** |
| **CRUD 功能** | 1-2 天 | 2-4 小时 | **3-4x** |
| **中等复杂度** | 3-5 天 | 1-2 天 | **2-3x** |
| **高复杂度** | 1-2 周 | 3-7 天 | **1.5-2x** |
#### 团队开发成本对比
假设 10 人团队，月薪 ¥30,000：
| 开发模式 | 月度人力成本 | AI 工具成本 | 总成本 | 产出对比 |
| ------------ | ------------ | ----------- | -------- | -------- |
| **传统开发** | ¥300,000 | ¥0 | ¥300,000 | 1x |
| **AI 辅助** | ¥300,000 | ¥10,000 | ¥310,000 | **2-3x** |
> **结论**：AI 辅助下，**10% 的成本增加带来 200-300% 的产出提升**。
### 10.4 AI 生成代码的常见问题
#### 前端问题分布
| 问题类型 | 占比 | 调试难度 | 预防措施 |
| ------------ | ---- | ---------- | ------------------- |
| **样式细节** | 40% | ⭐⭐⭐ | 精确描述设计稿 |
| **交互逻辑** | 25% | ⭐⭐⭐⭐ | 明确状态流转 |
| **性能问题** | 20% | ⭐⭐⭐⭐⭐ | 代码审查 + 性能测试 |
| **兼容性** | 10% | ⭐⭐⭐⭐ | 指定浏览器支持 |
| **其他** | 5% | ⭐⭐ | - |
#### 后端问题分布
| 问题类型 | 占比 | 调试难度 | 预防措施 |
| ---------------- | ---- | ---------- | --------------- |
| **业务逻辑偏差** | 35% | ⭐⭐⭐ | 详细需求文档 |
| **边界情况** | 25% | ⭐⭐⭐⭐ | 完整测试用例 |
| **性能问题** | 20% | ⭐⭐⭐⭐⭐ | 性能测试 + 优化 |
| **安全问题** | 15% | ⭐⭐⭐⭐⭐ | 安全审查 |
| **其他** | 5% | ⭐⭐ | - |
### 10.5 调试 AI 生成代码所需能力
#### 前端调试能力图谱
```
前端调试能力
├── 基础能力
│ ├── 浏览器 DevTools 使用
│ ├── Console 日志调试
│ ├── 断点调试
│ └── 网络请求分析
├── 样式调试
│ ├── CSS 选择器优先级
│ ├── Flexbox/Grid 布局
│ ├── 响应式断点
│ └── 浏览器兼容性
├── 交互调试
│ ├── 事件处理机制
│ ├── 状态管理（Redux/Vuex/Pinia）
│ ├── 异步操作（Promise/async-await）
│ └── 生命周期钩子
└── 性能调试
├── React DevTools / Vue DevTools
├── 性能分析（Performance）
├── 内存泄漏检测
└── 渲染优化
```
#### 后端调试能力图谱
```
后端调试能力
├── 基础能力
│ ├── 日志系统使用
│ ├── 断点调试
│ ├── 单元测试
│ └── 集成测试
├── 逻辑调试
│ ├── 业务流程追踪
│ ├── 数据流转分析
│ ├── 错误堆栈分析
│ └── 边界情况测试
├── 性能调试
│ ├── 慢查询分析
│ ├── 接口性能测试
│ ├── 内存/CPU 分析
│ └── 缓存命中率
└── 安全调试
├── SQL 注入检测
├── XSS/CSRF 防护
├── 权限验证
└── 数据加密
```
### 10.6 前后端互相调试的缺失能力
#### 前端开发调试后端缺失能力
| 缺失能力 | 重要程度 | 学习周期 | 影响范围 |
| ---------------- | ---------- | -------- | -------- |
| **API 设计规范** | ⭐⭐⭐⭐⭐ | 1 周 | 接口对接 |
| **数据库基础** | ⭐⭐⭐⭐⭐ | 2 周 | 数据理解 |
| **服务器部署** | ⭐⭐⭐ | 1 个月 | 环境搭建 |
| **日志分析** | ⭐⭐⭐⭐ | 2 周 | 问题定位 |
| **性能优化** | ⭐⭐⭐ | 1 个月 | 系统优化 |
| **安全意识** | ⭐⭐⭐⭐ | 持续 | 系统安全 |
**学习优先级**：
1. API 设计 + 数据库基础（**必须**，2-3 周）
2. 日志分析（**重要**，2 周）
3. 服务器部署（**建议**，1 个月）
4. 性能优化 + 安全（**持续**）
#### 后端开发调试前端缺失能力
| 缺失能力 | 重要程度 | 学习周期 | 影响范围 |
| --------------------- | ---------- | -------- | -------- |
| **CSS/Flexbox** | ⭐⭐⭐⭐⭐ | 2 周 | 页面布局 |
| **JavaScript 深入** | ⭐⭐⭐⭐⭐ | 1 个月 | 交互逻辑 |
| **框架（React/Vue）** | ⭐⭐⭐⭐⭐ | 1-2 个月 | 组件开发 |
| **浏览器 DevTools** | ⭐⭐⭐⭐ | 1 周 | 问题定位 |
| **UI/UX 基础** | ⭐⭐⭐ | 持续 | 用户体验 |
| **前端性能优化** | ⭐⭐⭐ | 1 个月 | 体验优化 |
**学习优先级**：
1. CSS/Flexbox + 浏览器 DevTools（**必须**，2-3 周）
2. JavaScript 深入 + 框架（**必须**，2-3 个月）
3. UI/UX + 性能优化（**建议**，持续）
### 10.7 AI 辅助下的学习路径
#### 路径一：前端开发者 → 全栈（AI 辅助）
**学习周期**：3-6 个月
| 阶段 | 时间 | 内容 | AI 辅助效果 |
| ------------ | ------- | --------------------------------------------- | ----------- |
| **第一阶段** | 2-4 周 | 后端基础（Node.js/Express、API 设计、数据库） | ⭐⭐⭐⭐⭐ |
| **第二阶段** | 4-8 周 | 实战项目（CRUD、认证、文件上传） | ⭐⭐⭐⭐ |
| **第三阶段** | 4-12 周 | 生产级应用（部署、监控、性能优化） | ⭐⭐⭐ |
**预期效果**：
- 3 个月后：能独立完成 80% 的全栈需求
- 6 个月后：能独立完成 95% 的全栈需求
#### 路径二：后端开发者 → 全栈（AI 辅助）
**学习周期**：4-8 个月
| 阶段 | 时间 | 内容 | AI 辅助效果 |
| ------------ | ------- | -------------------------------- | ----------- |
| **第一阶段** | 3-4 周 | 前端基础（HTML/CSS、JavaScript） | ⭐⭐⭐⭐ |
| **第二阶段** | 8-12 周 | 框架深入（React/Vue、状态管理） | ⭐⭐⭐ |
| **第三阶段** | 8-16 周 | 生产级应用（性能优化、部署） | ⭐⭐⭐ |
**预期效果**：
- 4 个月后：能独立完成 70% 的前端需求
- 8 个月后：能独立完成 90% 的前端需求
#### 路径三：零基础 → AI 辅助开发（GLM-4.7）
**学习周期**：6-12 个月
| 阶段 | 时间 | 内容 | AI 辅助效果 |
| ------------ | ------- | -------------------------------- | ----------- |
| **第一阶段** | 4-8 周 | 编程基础（语法、数据结构、算法） | ⭐⭐⭐ |
| **第二阶段** | 8-12 周 | 前端或后端专项 | ⭐⭐⭐⭐ |
| **第三阶段** | 8-16 周 | 框架 + 工程化 | ⭐⭐⭐⭐ |
| **第四阶段** | 8-24 周 | 实战项目 + 调试能力 | ⭐⭐⭐ |
**预期效果**：
- 6 个月后：能独立完成简单需求
- 12 个月后：能独立完成中等复杂度需求
### 10.8 掌握 AI 辅助开发的关键能力
#### 核心能力清单
| 能力 | 重要程度 | 学习周期 | AI 辅助效果 |
| ---------------------- | ---------- | --------- | ----------- |
| **Prompt Engineering** | ⭐⭐⭐⭐⭐ | 1-2 周 | - |
| **需求理解与拆解** | ⭐⭐⭐⭐⭐ | 持续 | ⭐⭐⭐ |
| **代码阅读能力** | ⭐⭐⭐⭐⭐ | 2-3 个月 | ⭐⭐ |
| **调试能力** | ⭐⭐⭐⭐⭐ | 3-6 个月 | ⭐⭐⭐ |
| **架构设计** | ⭐⭐⭐⭐ | 6-12 个月 | ⭐⭐⭐⭐ |
| **测试能力** | ⭐⭐⭐⭐ | 1-2 个月 | ⭐⭐⭐⭐ |
#### 学习建议
1. **先掌握 Prompt Engineering**（1-2 周）
- 学习如何清晰描述需求
- 学习如何分步骤拆解任务
- 学习如何提供上下文
2. **提升代码阅读能力**（2-3 个月）
- 阅读开源项目代码
- 理解常见设计模式
- 熟悉框架最佳实践
3. **重点培养调试能力**（3-6 个月）
- 前端：精通浏览器 DevTools
- 后端：掌握日志系统和测试
- 通用的：问题定位思路
4. **架构设计能力**（6-12 个月）
- 学习系统设计
- 理解设计模式
- 关注性能和安全
### 10.9 成功掌握 AI 辅助开发的估算
#### 不同基础的学习周期
| 当前基础 | 达成目标 | 学习周期 | 每周投入 | 成功概率 |
| ------------------------ | ------------------- | --------- | ---------- | -------- |
| **有编程基础（1-2 年）** | AI 辅助完成中等需求 | 1-2 个月 | 10-15 小时 | 95% |
| **有编程基础（3-5 年）** | AI 辅助完成复杂需求 | 2-4 周 | 10-15 小时 | 98% |
| **零基础** | AI 辅助完成简单需求 | 4-6 个月 | 15-20 小时 | 70% |
| **零基础** | AI 辅助完成中等需求 | 8-12 个月 | 20-25 小时 | 60% |
#### 知识量估算
**前端方向**：
- HTML/CSS：约 50 个核心概念
- JavaScript：约 100 个核心概念
- 框架（React/Vue）：约 80 个核心概念
- 工程化：约 40 个核心概念
- **总计：约 270 个核心概念**
**后端方向**：
- 语言基础：约 80 个核心概念
- 框架：约 60 个核心概念
- 数据库：约 50 个核心概念
- 部署运维：约 40 个核心概念
- **总计：约 230 个核心概念**
**学习速度**：
- 有编程基础：每周掌握 15-20 个概念
- 零基础：每周掌握 8-12 个概念
### 10.10 关键结论
1. **前端生成代码问题更多在视觉层面**，调试难度更高
2. **后端生成代码问题更多在逻辑和安全层面**，影响更严重
3. **前端写后端可行性高于后端写前端**（85% vs 80% 简单场景）
4. **AI 辅助下，有编程基础者 1-2 个月即可掌握 AI 辅助开发**
5. **零基础需要 6-12 个月才能熟练使用 AI 辅助开发**
6. **调试能力是区分能否独立完成需求的关键**
---
## 十一、参考来源
### 官方网站
- [Claude Code Plugins - Plugin Marketplace](https://claude-plugins.dev/)
- [Anthropic Responsible Scaling Policy](https://www.anthropic.com/responsible-scaling-policy)
- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
- [ASL-3 Protections](https://www.anthropic.com/news/activating-asl3-protections)
- [Compliance Framework SB-53](https://www.anthropic.com/news/compliance-framework-SB53)
- [Qoder 官网](https://www.qoder.com/)
- [Qoder 定价](https://qoder.com/pricing)
- [Qoder 文档](https://docs.qoder.com/)
- [Qoder CLI 快速上手](https://docs.qoder.com/zh/cli/quick-start)
- [智谱 AI 开放平台](https://bigmodel.cn/)
- [GLM-4.7 文档](https://docs.bigmodel.cn/cn/guide/models/text/glm-4.7)
- [GLM Coding Plan 定价](https://bigmodel.cn/glm-coding)
- [智谱 AI 定价页面](https://bigmodel.cn/pricing)
- [Cursor 官网](https://cursor.sh/)
- [Claude Code](https://claude.ai/code)
### 模型发布信息
- [GLM-4.7 发布 - 新浪财经](https://finance.sina.com.cn/tob/2025-12-23/doc-inhctxhu0912725.shtml)
- [GLM-4.7 开源 - 开源中国](https://www.oschina.net/news/391481/glm-4-7)
- [GLM-4.6 文档 - 智谱AI](https://docs.bigmodel.cn/cn/guide/models/text/glm-4.6)
- [Claude Opus 4.5 发布 - Anthropic](https://www.anthropic.com/news/claude-opus-4-5)
- [GPT-5.2 发布 - OpenAI](https://openai.com/index/introducing-gpt-5-2-codex/)
- [GPT-5.1-Codex-Max - OpenAI](https://openai.com/index/gpt-5-1-codex-max/)
### 价格与成本分析
- [Qoder 降价信息 - CSDN](https://blog.csdn.net/IRpickstars/article/details/154772522)
- [Qoder 首月 $2 - 阿里云开发者社区](https://developer.aliyun.com/article/1688536)
- [Claude Code 付费完全指南](https://www.cursor-ide.com/blog/claude-code-pricing)
- [Cursor vs Codex vs Claude Code](https://www.cursor-ide.com/blog/cursor-vs-codex-vs-claude-code)
- [2025 AI 工具月度成本分析 - 知乎](https://www.zhihu.com/question/15137704620)
### 重度用户真实案例
- [员工每天花 $1000 用 Claude Code - 腾讯新闻](https://news.qq.com/rain/a/20250614A04FSW00)
- [月烧 35 万元 token，官方连夜限速 - InfoQ](https://www.infoq.cn/article/07mywmhiocsah2m9eqot)
- [用户集体大逃亡！Cursor 自杀式策略 - InfoQ](https://www.infoq.cn/article/06ov3meaqskngp6gm9od)
- [70+ 万一年的 AI 账单 - 网易](https://www.163.com/dy/article/K6UN60JI0511FQO9.html)
- [顶级用户 AI 账单 $10 万/年 - 知乎](https://zhuanlan.zhihu.com/p/1938666160594878863)
- [Cursor 再次调价，包月模式搞不下去了](https://hub.baai.ac.cn/view/49065)
- [12 小时高强度 Claude Code 使用体验 - OneV's Blog](https://onevcat.com/2025/08/claude-code/)
### 产品对比与评测
- [2025 年 AI 编程工具深度对比](https://aicoding.csdn.net/686e3291080e555a88ce5407.html)
- [AI 辅助编程工具深度评测 - 51CTO](https://www.51cto.com/article/817056.html)
- [2025 主流 AI 开发工具对比 - Lewin's Blog](https://lewinblog.com/blog/page/2025/250306-AI-IDEs.md)
- [Claude Code vs Cursor 性价比对比](https://poloapi.com/poloapi-blog/Claude%20is%20the%20king%20of%20cost-effectiveness)
### Qoder CLI 相关
- [Qoder CLI 入门指南 - 知乎](https://zhuanlan.zhihu.com/p/1962499950236632743)
- [阿里发布 Qoder CLI - InfoQ](https://www.infoq.cn/article/t3kbl5pus6watht1huya)
- [使用 Qoder 2 个月经验总结](https://www.cnkirito.moe/qoder-use-guide/)
- [Qoder CLI 社区版部署文档 - 阿里云](https://help.aliyun.com/zh/compute-nest/use-cases/qoder-cli-community-edition-service-instance-deployment-document)
- [Qoder 全栈开发实战指南 - 阿里云开发者社区](https://developer.aliyun.com/article/1687659)
### Qoder 官方文档
- [Qoder 官方文档](https://docs.qoder.com/)
- [Qoder 模型分级选择器](https://docs.qoder.com/zh/user-guide/chat/model-tier-selector)
- [Qoder CLI 使用指南](https://docs.qoder.com/zh/cli/using-cli)
- [Qoder 官网](https://www.qoder.com/)
- [Qoder Repo Wiki 文档](https://docs.qoder.com/zh/user-guide/repo-wiki)
- [Qoder 定价](https://qoder.com/pricing)
### 产品对比与评测
- [阿里Qoder vs Trae vs Cursor：谁才是2025年程序猿的效率之王？ - 知乎](https://zhuanlan.zhihu.com/p/1942632539849200345)
- [Qoder：阿里巴巴推出的AI IDE，全方位了解其能力与未来 - Jimmy Song](https://jimmysong.io/zh/blog/qoder-alibaba-ai-ide-personal-review/)
- [Introducing Cursor 2.0 and Composer - Cursor Blog](https://cursor.com/blog/2-0)
- [Composer: Building a fast frontier model with RL - Cursor Blog](https://cursor.com/blog/composer)
- [阿里Qoder 体验超预期，Repo Wiki 功能迎来全新升级 - InfoQ](https://xie.infoq.cn/article/5e17452ab233d55a2403323ec)
- [从"代码补全"到"知识对齐"：Qoder Repo Wiki 迎来重磅升级 - 阿里云开发者社区](https://developer.aliyun.com/article/1682576)
### 其他
- [无限量供应 Claude，AI IDE 的百亿补贴 - PingWest](https://www.pingwest.com/a/306855)
- [相信大模型成本会下降，是业内最大幻觉 - 知乎](https://zhuanlan.zhihu.com/p/1941285603967742207)
- [Token 成本下降，订阅费却飞涨 - 新浪财经](https://finance.sina.cn/2025-08-06/detail-infizhrw8528637.d.html)
---
**文档更新时间：2025 年 12 月**
**注意**：
1. 价格信息可能随时变动，请以官方公布为准
2. AI 工具的定价策略正在快速变化，建议定期查看官方最新定价
3. 重度用户成本基于真实案例，实际情况可能因使用模式而异
---
## 简介
## 总览
由于小程序运行时，本身有自己的一套 **独特的** 技术规范标准。这导致你无法使用 `web` 开发中的很多的特性，
你也无法 **直接** 使用像 [`tailwindcss`](https://www.tailwindcss.com/) 这种原子化 `css` 生成器来提升你的开发效率。
而 `weapp-tailwindcss` 就能让你，在小程序开发中使用 `tailwindcss` **大部分** 特性。
它支持目前上所有使用 `webpack` 和 `vite` 的主流多端小程序框架和使用 `webpack` / `gulp` 的原生小程序打包方式。
你可以很容易在各个框架，或原生开发中集成 `tailwindcss`。
现在，就让我们开始使用吧！
:::info
从本质上讲，它是一个字符串转义器。它负责把 `tailwindcss` 中，所采集的类名，以及生成的结果，转化成小程序中可以接受的方式。
:::
## 环境要求
- `weapp-tailwindcss@5.2.0` 起要求 Node.js `>=22.12.0`。Node.js 22 从该版本开始默认支持从 CommonJS 加载 ESM。
- 使用 HBuilderX 的 `uni-app` / `uni-app x` 项目要求 HBuilderX `>=5.11`。
## Why `weapp-tailwindcss`?
- ✅ 自动处理所有文件：以微信小程序为例，不但可以处理和转义 `wxml` / `wxss`，还能处理 `js` 和 `wxs` 产物
- ✅ 支持最原生的小程序开发，也支持许多框架如 `taro`、`uni-app`、`mpx` 等等..
- ✅ 提供多种使用方式，方便项目集成：包括 `webpack` / `vite` / `gulp` 插件和直接的 `nodejs api`
- ✅ 生态好，解决方案丰富，提供大量现成模板，可以利用许多 `tailwindcss` 现有的生态来构建小程序。
- ✅ 高效的解析和缓存机制，热更新响应时间快
- ✅ 贴合 `tailwindcss` 的设计思路，智能提示友好
## 快速开始 :rocket:
### 👉 [安装依赖](/docs/quick-start/install)
当前文档默认使用 `tailwindcss@4` 与 `weapp-tailwindcss` 当前版本。
### 👉 [各框架模板](/docs/community/templates)
如果你想直接对照可运行项目，可以优先查看模板项目。
### 👉 [Tailwind CSS 4 默认模式参考](/docs/tailwindcss/v4-reference)
这里有 CSS-first、`@source`、`@apply`、`@layer` 和 IntelliSense 的补充说明。
## 演示视频
## 另外特别感谢 [舜岳同学](https://space.bilibili.com/475498258) 为 `weapp-tailwindcss` 制作的视频
---
## 小程序多主题方案
## 自由的 web 方案
对于 `web` 来说，多主题色的需求是非常常见的，比如 `暗黑模式` 就是一个极其常见的需求，
`web` 上的解决方案无非就是，通过动态切换 `css` 变量的值达成效果，或者通过 `.dark / [data-theme]` 选择器，包裹暗黑模式下页面和组件的样式，通过增加选择器的优先级，来覆盖默认的样式等等...
那么小程序的方案应该怎么去实现呢？
答案就是有 [page-meta 页面属性配置节点](https://developers.weixin.qq.com/miniprogram/dev/component/page-meta.html) 的情况下，优先使用它的 `page-style` 属性，进行 `css` 变量的切换
没有 `page-meta` 页面属性配置节点的情况下，我们只能通过配置单个 `view` 组件的样式变量，来进行主题色的切换
## 方案的设计和实现
切换多主题主要依赖 `css` 变量切换，所以我们只要依照这个设计去实现即可
### 1. 页面属性配置节点 page-meta
利用 `page-meta` 页面属性配置节点的 `page-style` 属性，来进行 `css` 变量的切换
另外我们也可以通过 `page-meta` 组件的，来切换一些原生的样式
[page-meta 页面属性配置节点](https://developers.weixin.qq.com/miniprogram/dev/component/page-meta.html)
### 2. 自己实现 css 变量切换组件
首先既然我们无法利用**根**节点的变量切换来达成效果，但是我们可以通过组件的特性，即数据的响应式和插槽来达成效果。
我们可以设计一个 `ConfigProvider` 组件，它拥有一个`dom`节点，内部是一个插槽
其中那个`dom`节点就是我们主题相关变量寄居在的节点，而这个组件往往会作为一个根组件，在每个页面中被使用，去包裹我们真正的业务页面
甚至我们可以再设计一个 `BaseLayout` 这样的组件，去包含每个页面公共的部分，再在其中去引用 `ConfigProvider`，然后做一层插槽的透传即可。
#### 实现
> 这里我以 `vue` 的语法作为示例，因为我个人认为它比 `react` 和 `原生` 更容易让新手看懂
`ConfigProvider`的实现：
```html
```
其中，`mode` 这个 `prop` 用来模拟实现了 `` 的效果，而 `vars` 则用来模拟实现 `js api` 设置 `css` 变量的效果。
通过这 `2` 个 `props`，你既可以通过 `mode` 的切换，把多个主题以及对应的变量值全部给写在你自己的 `css`中，然后通过切换`mode`，触发样式的覆盖来切换主题，这种是为静态的切换。
又可以通过设置 `vars`的值去动态的覆盖和切换，比如从服务端获取`css`变量的值，然后`set`进组件中，这显然是非常灵活的，这种是为动态的切换。
现在有了这个组件，我们就可以用它去包裹每一个页面了。
然后下一步，自然是要我们的页面和组件，都去应用那些我们设计的 `css` 变量了。
这一块可以参考下方链接中的`动态调整系统主题色(4)`中的`CssVar`方案，里面也有和 `tailwindcss` 相结合的部分，也欢迎阅读`动态调整web系统主题` 系列文章，并与在下进行探讨。
## 动态调整主题参考链接
1. [动态调整web系统主题? 看这一篇就够了](https://icebreaker.top/articles/2021/12/18-flexible-theme)
2. [动态调整web主题(2) 萃取篇](https://icebreaker.top/articles/2022/1/15-custom-theme-2)
3. [动态调整web主题(3): 基于tailwindcss插件的主题色生成方案](https://icebreaker.top/articles/2022/9/26-custom-theme-3)
4. [动态调整系统主题色(4): CssVar 与 Variant 方案的探索](https://icebreaker.top/articles/2023/10/5-custom-theme-4)
## 参考示例
微信上搜索 `tailwind`（未交 `30` 元个人资质费用，已无法搜索），进入小程序即可，小程序码：
实现源代码详见: [weapp-tailwindcss/tailwindcss-weapp](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/tailwindcss-weapp)
---
## 构建以及引入外部组件
## 前言
我们在日常的开发中，经常会去使用和封装各种各样的组件库。有些是开源的，第三方开发的UI库，有些是我们开发人员给自己的特定的业务封装的UI库。其中很多情况其实是以流行的 `开源UI库(或者fork的改版)` + `自己封装的业务组件为主的`
`开源UI库` 它们的样式相对来说是独立于整套系统的，比如它们的样式都是 `ant-`，`el-` 开头的，一般引入之后不会和原先系统里的样式产生冲突。而 `自己封装的业务组件`，由于往往和系统高度绑定也没有这样的问题。
那么如何用 `tailwindcss` 来构建/发布和引入自己封装的业务组件呢？
## 构建组件
### 核心思想
首先我必须重点把本篇文章的核心思想预先抛出：
`tailwindcss` 只是一个`css`生成器，它只是帮你按照一定的规则，从你的源代码中匹配字符串去生成`css`。所以在用它去构建组件的时候，一定要去思考你用 `tailwindcss` 生成的 `css` 的影响范围，因为大部分用 `tailwindcss` 都是默认全局应用的。但是你在组件里面的自定义样式很多情况下，是没有必要的。
根据这个核心思想，我们就可以知道在封装组件时可行和不可行的方式了，大致如下:
### 可行方案
1. `custom css selector` + `Functions & Directives`
2. `add prefix` (添加前缀)
3. `add scoped` (像 `vue` 的 `scoped` 一样添加 data-v-[hash] 类似的自定义属性，然后去修改css选择器)
4. 不打包方案 (不构建产物，直接发布，然后在项目里安装，再提取 `node_modules` 里制定的文本重新生成。)
### 不可行方案
1. module css 这会去修改 css 选择器。
## 可行方案详解
这里我写了2个`demo`分别是 `react` 和 `vue`，其中下方代码以 `vue` 为示例，`react`示例见下方的 `构建demo链接`
### custom css selector + Functions & Directives
这种方案其实非常的传统，仅仅使用到了 `tailwindcss` 中 `@apply` 和 `theme` 等等指令的功能。
比如我们有个组件 `ApplyButton.vue`，它的模板，样式和独立的 `tailwind.config.js` 分别如下所示:
```html
```
```css
@config 'tailwind.config.js';
@tailwind utilities;
.apply-button {
@apply text-white p-4 rounded;
background-color: theme("colors.sky.600")
}
```
```js
const path = require('node:path')
/** @type {import('tailwindcss').Config} */
export default {
content: [path.resolve(__dirname, './index.vue')],
// ...
}
```
然后在打包的时候，以这个文件或者导出文件(`index.ts`) 为打包入口即可。
这样它的产物css中，选择器由于是你自己定义的，就能尽可能保证它是独一无二的。
它对应的`css`产物为:
```css
.apply-button {
border-radius: 0.25rem;
--tw-bg-opacity: 1;
background-color: rgb(2 132 199 / var(--tw-bg-opacity));
padding: 1rem;
--tw-text-opacity: 1;
color: rgb(255 255 255 / var(--tw-text-opacity));
}
```
### add prefix
这个也很好理解，前缀嘛，各个UI库都是这样搞的，我们就可以创建出以下的代码:
```html
```
```js
const path = require('node:path')
/** @type {import('tailwindcss').Config} */
export default {
prefix: 'ice-',
content: [path.resolve(__dirname, './index.vue')],
}
```
它对应的`css`产物为:
```css
.ice-rounded {
border-radius: 0.25rem;
}
.ice-bg-sky-600 {
--tw-bg-opacity: 1;
background-color: rgb(2 132 199 / var(--tw-bg-opacity));
}
.ice-p-4 {
padding: 1rem;
}
.ice-text-white {
--tw-text-opacity: 1;
color: rgb(255 255 255 / var(--tw-text-opacity));
}
```
### add scoped
这个就是通过同时添加html标签属性和修改css选择器来做的了:
```html
```
这里仅仅给 `style` 加了一个 `scoped` 属性
```js
const path = require('node:path')
/** @type {import('tailwindcss').Config} */
export default {
content: [path.resolve(__dirname, './index.vue')],
}
```
`css` 生成结果为:
```css
.rounded[data-v-10205a53] {
border-radius: 0.25rem;
}
.bg-sky-600[data-v-10205a53] {
--tw-bg-opacity: 1;
background-color: rgb(2 132 199 / var(--tw-bg-opacity));
}
.p-4[data-v-10205a53] {
padding: 1rem;
}
.text-white[data-v-10205a53] {
--tw-text-opacity: 1;
color: rgb(255 255 255 / var(--tw-text-opacity));
}
```
### 不打包
以上三种方式总结一下，都是通过在选择器上下功夫来制作组件库的，而且它们都有一个打包的过程，即 `src`->`dist` 然后发布 `dist`
可是这第四种方案就不怎么一样了: 核心就是 `不打包`
即我们写好组件之后，直接把 `npm`的入口文件，指向 `src` ，然后直接把里面的组件发布(比如直接发布 `vue`组件)
这种情况下，你需要让你在 `node_modules` 里的组件再次经受一遍 `js` 的处理，比如 `vue sfc compiler`,`babel`,`swc`等等。
同时你也需要配置你项目里的 `tailwind.config.js` 去提取你 `node_modules` 里的组件源代码内容:
```diff
module.exports = {
content: [
'./index.html',
'./src/**/*.{html,js,ts,jsx,tsx,vue}',
+ './node_modules/mypkg/src/components/**/*.{html,js,ts,jsx,tsx,vue}'
]
}
```
这样才能重新提取生成 `css` 在项目主`css chunk`里。
## 构建demo链接
## 相关 issues
---
## CSS 单位转化
最常见的情况是 `rem` 转 `rpx`，直接在 `WeappTailwindcss` 的 `cssOptions` 里开启 `rem2rpx`：
```js
WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
})
```
`true` 表示 `1rem = 32rpx`。这页只讲另外两种情况：`px` 转 `rpx`，以及多单位转 `px`。
## px 转 rpx
从 `weapp-tailwindcss@4.3.0` 开始，插件内置了 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform)。需要 `px` 转 `rpx` 时，在 `cssOptions` 中开启 `px2rpx`：
```js
// vite
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
WeappTailwindcss({
cssOptions: {
px2rpx: true,
},
})
```
```js
// webpack
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
new WeappTailwindcss({
cssOptions: {
px2rpx: true,
},
})
```
`true` 会按 `1:1` 转换，比如 `10px` 输出成 `10rpx`。
如果你的设计稿是 375 宽，希望 `10px` 输出为 `20rpx`，传对象：
```js
WeappTailwindcss({
cssOptions: {
px2rpx: {
designWidth: 375,
deviceRatio: {
375: 2,
},
},
},
})
```
更多参数看 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform)。不要为了单位转换再把 Tailwind CSS 官方 PostCSS 插件注册进来，小程序样式生成仍然由 `weapp-tailwindcss` 接管。
## 多单位转 px
`uni-app x` 等场景更适合输出 `px`。这时可以启用 `cssOptions.unitsToPx`，把 `rem`、`em`、`vw`、`vh`、`vmin`、`vmax`、`rpx` 等单位转成 `px`。
```js
// vite
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
WeappTailwindcss({
cssOptions: {
unitsToPx: true,
},
})
```
默认换算里：
- `1rem` 输出为 `16px`
- `2rpx` 输出为 `1px`
需要自定义时传对象：
```js
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
new WeappTailwindcss({
cssOptions: {
unitsToPx: {
unitPrecision: 2,
unitMap: {
rem: 16,
rpx: 0.5,
vw: 3.75,
},
},
},
})
```
如果最终想输出 `px`，不要同时开启 `cssOptions.px2rpx` 或 `cssOptions.rem2rpx`。`cssOptions.unitsToPx` 会先转成 `px`，后续还会继续被转成 `rpx`。
---
## Node.js API
`weapp-tailwindcss/core` 提供不依赖 Vite、Webpack 或 Gulp 生命周期的文本转换 API。它适合自研构建器、批处理脚本、构建平台适配器，以及需要直接管理内存产物的工具。
:::caution 高阶入口
普通 `uni-app`、Taro、Mpx、weapp-vite 或原生小程序项目，应优先使用对应的 Vite、Webpack 或 Gulp 插件。构建器插件已经负责 CSS 入口、模块图、watch/HMR、缓存和产物写回；Core API 会把这些职责交给调用方。
当前包要求 Node.js `^22.18.0 || >=24.11.0`。
:::
## 先理解职责边界
Core API 只处理传入的内存文本，不会扫描输出目录、替你写文件，也不会因为配置了 `cssEntries` 就把 CSS 入口自动加入构建图。
| 能力 | Core API 负责 | 调用方负责 |
| --- | --- | --- |
| Tailwind 类名集合 | 从明确配置的 Tailwind CSS 入口和 source 中收集、缓存与刷新 | 保证入口和 source 正确，并在合适的构建阶段触发刷新 |
| CSS | 把已经生成的 CSS 转成目标端兼容样式 | 让 Tailwind CSS 入口实际参与生成，并把结果交给 `transformWxss()` |
| WXML / AXML 等模板 | 转义静态 class 与表达式中的已确认类名 | 读取、写回产物并选择正确的平台模板文件 |
| JavaScript | 只转译运行时集合确认的 class，保留普通业务字符串 | 处理解析错误、source map、关联模块与文件写回 |
| watch / HMR | 复用同一个上下文中的运行时缓存 | 监听源码和配置变化，并在变化后重新收集运行时集合 |
Tailwind CSS v4 的样式生成必须继续由 `weapp-tailwindcss` 链路接管。不要为 Core API 额外注册 `@tailwindcss/postcss` 或 `@tailwindcss/vite` 作为生成兜底。
## 配置 Tailwind CSS 入口
Tailwind CSS v4 项目应给 `cssEntries` 传入绝对路径。入口用于识别 `@import "tailwindcss"`、`@source` 与 `@config`，但它仍然必须由你的构建流程实际加载。
```css title="src/tailwind.css"
@import "tailwindcss" source(none);
@source "./**/*.{html,wxml,js,ts,jsx,tsx,vue}";
@source not "../dist";
@source not "../unpackage";
```
```js
import path from 'node:path'
import { createContext } from 'weapp-tailwindcss/core'
const root = process.cwd()
const cssEntry = path.resolve(root, 'src/tailwind.css')
const ctx = createContext({
tailwindcssBasedir: root,
cssEntries: [cssEntry],
})
```
多入口、分包或独立分包项目应列出全部真实入口。`cssEntries` 等价于 `tailwindcss.v4.cssEntries` 的快捷配置。完整配置类型见 [`UserDefinedOptions`](/docs/api/interfaces/UserDefinedOptions) 和 [`cssEntries`](/docs/api/options/important#cssentries)。
## API 一览
`createContext(options)` 返回的四个方法共享同一份 Tailwind 运行时状态与类名集合。
| 方法 | 输入 | 返回值 | 关键行为 |
| --- | --- | --- | --- |
| `getRuntimeSet(options?)` | 刷新选项 | `Promise>` | 收集或刷新 Tailwind 已确认的运行时类名 |
| `transformWxss(rawCss, options?)` | 已生成的 CSS | `Promise` | 通过 `result.css` 读取目标端 CSS，并更新内部运行时集合 |
| `transformWxml(rawTemplate, options?)` | 模板字符串 | `Promise` | 转义 class 属性及模板表达式中的已确认类名 |
| `transformJs(rawJs, options?)` | JS 字符串 | `Promise` | 返回 `code`，并按配置返回 `map`、`error` 或 `linked` |
:::warning 返回值不是同一种类型
不要把三个 transform 的返回值都当成字符串：
- `transformWxss()` 返回 PostCSS Result，最终 CSS 在 `result.css`。
- `transformWxml()` 直接返回字符串。
- `transformJs()` 返回对象，最终 JavaScript 在 `result.code`。
:::
## 推荐调用时序
一个生产构建周期建议遵循下面的顺序：
1. 创建并复用一个 `createContext()`，不要为每个文件重新创建上下文。
2. 让 Tailwind CSS 入口先进入实际生成链路，得到待适配的 CSS。
3. 调用 `transformWxss()` 处理主样式；该步骤结束后会同步内部运行时集合。
4. 调用 `getRuntimeSet()` 读取同一集合，或在自定义生命周期中显式强制收集。
5. 使用同一个上下文调用 `transformWxml()` 和 `transformJs()`。
6. 检查 JS 解析错误，再由你的构建器通过自身产物 API 或文件流程写回结果。
如果你的构建流程先处理模板或 JavaScript，也可以先调用：
```js
const runtimeSet = await ctx.getRuntimeSet({
forceCollect: true,
})
```
未显式传入 `runtimeSet` 时，`transformWxml()` 和 `transformJs()` 会在内部集合为空时自动收集一次。显式调用的价值是让构建阶段、错误定位和 watch 刷新更加清楚。
## 完整文件处理示例
下面假设上游生成步骤已把 Tailwind CSS 写入 `.build/tailwind.generated.css`。示例只展示 Core API 的内存转换和文件写回边界。
```js title="scripts/transform.mjs"
import { mkdir, readFile, writeFile } from 'node:fs/promises'
import path from 'node:path'
import { createContext } from 'weapp-tailwindcss/core'
const root = process.cwd()
const sourceRoot = path.resolve(root, 'src')
const outputRoot = path.resolve(root, 'dist')
const ctx = createContext({
tailwindcssBasedir: root,
cssEntries: [path.resolve(sourceRoot, 'tailwind.css')],
rem2rpx: true,
})
async function main() {
const [generatedCss, rawWxml, rawJs] = await Promise.all([
readFile(path.resolve(root, '.build/tailwind.generated.css'), 'utf8'),
readFile(path.resolve(sourceRoot, 'pages/index/index.wxml'), 'utf8'),
readFile(path.resolve(sourceRoot, 'pages/index/index.js'), 'utf8'),
])
const cssResult = await ctx.transformWxss(generatedCss)
const runtimeSet = await ctx.getRuntimeSet()
const wxmlCode = await ctx.transformWxml(rawWxml)
const jsResult = await ctx.transformJs(rawJs)
if (jsResult.error) {
throw jsResult.error
}
console.log(`collected ${runtimeSet.size} Tailwind classes`)
await mkdir(path.resolve(outputRoot, 'pages/index'), { recursive: true })
await Promise.all([
writeFile(path.resolve(outputRoot, 'app.wxss'), cssResult.css),
writeFile(path.resolve(outputRoot, 'pages/index/index.wxml'), wxmlCode),
writeFile(path.resolve(outputRoot, 'pages/index/index.js'), jsResult.code),
])
}
main().catch((error) => {
console.error(error)
process.exitCode = 1
})
```
CommonJS 项目可以使用 `const { createContext } = require('weapp-tailwindcss/core')`，其余 API 契约一致。
## `getRuntimeSet()` 刷新选项
默认调用会优先复用签名未变化的缓存；如果首次结果为空，还会刷新运行时并重新收集一次。
| 选项 | 行为 | 适用场景 |
| --- | --- | --- |
| `forceCollect` | 跳过当前集合缓存，从现有 Tailwind 运行时重新提取 | watch 中源码内容变化、新增运行时 class |
| `forceRefresh` | 先重建 Tailwind 运行时，再强制提取 | CSS 入口、`@source`、`@config` 或 Tailwind 配置发生结构变化 |
| `clearCache` | 在强制收集或刷新时同步清理 Tailwind 运行时缓存 | 配置或依赖变化后需要排除旧缓存；通常与 `forceRefresh` 一起使用 |
| `allowEmpty` | 接受空集合，不执行默认的第二次刷新 | 确认当前项目允许没有 Tailwind class，或只做状态探测 |
`clearCache: true` 单独使用不保证触发刷新，应该与 `forceCollect` 或 `forceRefresh` 组合。
```js
// 初次构建或普通源码变化
await ctx.getRuntimeSet({ forceCollect: true })
// Tailwind 配置、入口或 source 图发生变化
await ctx.getRuntimeSet({
forceRefresh: true,
clearCache: true,
})
```
watch/HMR 中必须先刷新集合，再处理受影响的 JS 和模板。不要用启发式转义弥补过期的集合；新 class 尚未进入集合时，保持原值比误改业务字符串更安全。
`jsArbitraryValueFallback` 已废弃，仅用于兼容旧配置。`true` 和 `'auto'` 都不会绕过 `classNameSet`；集合为空或候选未命中时，`transformJs()` 会保持源码不变。
## `runtimeSet` 的安全边界
`transformJs()` 的核心原则是 `classNameSet` 精确命中：只有 Tailwind 生成或验证过的 class 才能进入普通 JS 字符串的转译路径。
```js
const rawJs = [
'const className = "text-[12px] w-1/2"',
'callApi("order/get_order_amount", {}, "POST")',
].join('\n')
const { code, error } = await ctx.transformJs(rawJs)
if (error) {
throw error
}
// text-[12px] w-1/2 -> text-_b12px_B w-1_f2
// order/get_order_amount 保持原样
console.log(code)
```
`transformJs(rawJs, { runtimeSet })` 是测试和自研构建器深度集成用的覆盖入口。传入它时应遵守以下约束：
- 集合应来自 `getRuntimeSet()` 或 Tailwind v4 的生成/验证结果。
- 不要把扫描器发现的所有字符串直接塞入集合。
- 不要把 API、路由、资源路径、MIME 或日志文本当成 class。
- 不要修改一个正在被其他并发转换复用的 `Set`；刷新后使用新的集合快照。
从 `weapp-tailwindcss@5.1.8` 起，非 class 上下文中的普通斜杠路径还有额外保护，但这只是纵深防御，不能替代正确的候选验证。相关回归见 [issue #903](https://github.com/sonofmagic/weapp-tailwindcss/issues/903)。
## 精确忽略冲突字符串
正常项目不需要为 API 路径配置忽略规则。如果业务字符串确实与有效 Tailwind class 完全相同，可以选择局部或全局保护。
### 局部保护
默认会识别名为 `weappTwIgnore` 的标签模板：
```js
import { weappTwIgnore } from 'weapp-tailwindcss/escape'
const value = weappTwIgnore`w-1/2`
```
### 全局规则
```js
const ctx = createContext({
jsPreserveClass: keyword => keyword.startsWith('internal-route:'),
})
```
`jsPreserveClass` 返回 `true` 时保留当前字符串。详细配置见 [`jsPreserveClass`](/docs/api/options/important#jspreserveclass) 和 [`ignoreTaggedTemplateExpressionIdentifiers`](/docs/api/options/important#ignoretaggedtemplateexpressionidentifiers)。
:::danger 谨慎使用 `alwaysEscape`
`transformJs(rawJs, { alwaysEscape: true })` 会绕过 `classNameSet` 安全边界。它只适合输入内容已经确定全部是 class 的专用转换步骤，不应对普通业务 JavaScript 启用。
:::
## 返回值与错误处理
### `transformWxss()`
返回 PostCSS Result。常用字段包括：
- `css`：最终目标端 CSS。
- `map`：启用 source map 后的 PostCSS source map。
- `messages`：PostCSS 插件产生的元数据和提示。
- `warnings()`：收集 PostCSS warning。
不传 `isMainChunk` 时默认按主样式处理。处理分包或次级样式时，应根据你的构建图显式传入正确的 `IStyleHandlerOptions`。
### `transformWxml()`
直接返回模板字符串。可以通过 `{ runtimeSet }` 覆盖当前调用使用的集合，但通常应复用上下文自动维护的集合。
### `transformJs()`
返回 `JsHandlerResult`：
- `code`：转换后的 JavaScript；解析失败时保持原始输入。
- `map`：启用时生成的 source map。
- `error`：Babel 解析错误。Core API 会把错误放在结果中，调用方必须主动检查。
- `linked`：启用 `filename + moduleGraph` 跨模块分析后产生的关联模块结果，以绝对路径为键；调用方负责把它们交回构建图。
除显式底层参数 `alwaysEscape: true` 外，`transformJs()` 只转译精确命中当前 `classNameSet` 的候选。空集合、缺失集合和未命中候选都会原样保留。
## 常见问题排查
| 现象 | 优先检查 |
| --- | --- |
| 提示“未检测到 cssEntries” | 是否传入了绝对路径；入口是否真的包含 Tailwind 引用 |
| CSS 有 class，JS/WXML 没有转义 | `@source` 是否覆盖源码；是否在 Tailwind 生成完成前收集了集合 |
| watch 新增 class 不生效 | 是否在源码变化后调用 `getRuntimeSet({ forceCollect: true })`，并在刷新后再转换产物 |
| 修改 Tailwind 配置后仍使用旧结果 | 调用 `getRuntimeSet({ forceRefresh: true, clearCache: true })` |
| API、路由或资源路径被改写 | 升级到最新版；确认未使用 `alwaysEscape`，并检查手工 `runtimeSet` 是否被普通字符串污染 |
| `transformJs()` 没有抛错但代码未变化 | 检查返回值中的 `error`；解析失败时 `code` 会保持原文 |
| 配置了 `cssEntries` 但没有 CSS 产物 | `cssEntries` 只提供入口语义，不会替代构建器加载或生成 CSS |
## 和构建器插件的区别
| 使用方式 | 适合场景 | 构建生命周期 |
| --- | --- | --- |
| `weapp-tailwindcss/vite` | Vite、uni-app Vite、Taro Vite、weapp-vite | 插件接管模块图、CSS 生成、运行时集合和 HMR |
| `weapp-tailwindcss/webpack` | Webpack、Taro Webpack、Mpx | 插件接管 compilation、loader 与产物图 |
| `weapp-tailwindcss/gulp` | 原生小程序流式构建 | 插件接管 Vinyl 文件和增量任务 |
| `weapp-tailwindcss/core` | 自研构建器、批处理脚本、平台适配器 | 调用方显式组织生成、刷新、转换和写回 |
普通项目请先阅读 [Tailwind CSS 4 默认模式参考](/docs/tailwindcss/v4-reference)，再选择对应框架的接入页。
---
## uni-app HBuilderX 使用方式
:::caution
本文同时包含两条 `HBuilderX` 路线：
- `HBuilderX Vue3 Vite`：推荐
- `HBuilderX Vue2 Webpack`：仅供存量项目维护
:::
## HBuilderX Vue3 Vite
这条路线适合 HBuilderX 创建的 Vue3 Vite 项目。HBuilderX 会改变运行时的 `process.cwd()`，所以扫描路径和 `cssEntries` 都建议使用绝对路径。
当前文档面向 `tailwindcss@4`。当前文档仅维护 Tailwind CSS 4 接入说明。
### CSS 入口
```css title="src/app.css"
@import "tailwindcss";
@source "../pages/**/*.{html,js,ts,jsx,tsx,vue}";
@source "../components/**/*.{html,js,ts,jsx,tsx,vue}";
@source not "../uni_modules";
@source not "../unpackage";
```
Tailwind 4 的入口只放在纯 `.css` 文件里，不要直接写进 `scss`、`less`、`sass` 入口。VS Code IntelliSense 需要时，可以把 `tailwindCSS.experimental.configFile` 指向这个 CSS 文件。
入口 CSS 仍然要被项目实际引入，例如在 `src/App.vue` 的全局 `
```
`UNI_PLATFORM=h5`、`app` 或 `app-plus` 时，生成器默认目标会自动切换为 `web`，不再需要写 `disabled: WeappTailwindcssDisabled`。如果自定义构建环境没有注入这些变量，可以显式指定 Web 输出：
```js
WeappTailwindcss({
generator: {
target: "web",
},
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
resolve(projectRoot, "src/app.css"),
],
});
```
`disabled` 只适合完全不希望插件参与的独立原生或自定义构建，不是 H5 / 普通 App WebView 的常规配置。
生成模式下不要再注册 Tailwind 官方生成插件，不要注册 `@tailwindcss/postcss` 或 `@tailwindcss/vite`。项目已有 PostCSS 配置时，只保留框架或业务需要的非 Tailwind 插件。
`hbuilderx` 正式版本的 `vue2` 项目由于使用 `webpack4` 和 `postcss7`，不再适配当前版本。存量项目请继续停留在旧版本，或者迁移到 `HBuilderX Vue3 Vite` / `uni-app cli vue2 webpack5` 链路。
## HBuilderX 与 uni-app CLI 环境汇总
先确认项目实际使用的构建链路。下面是文档维护时的常见组合，项目以本机 HBuilderX 安装的编译插件为准：
| | webpack | vite | postcss |
| ---------------- | -------- | ---- | -------- |
| HBuilderX Vue2 | webpack4 | x | postcss7 |
| uni-app CLI Vue2 | webpack5 | x | postcss8 |
| HBuilderX Vue3 | x | √ | postcss8 |
| uni-app CLI Vue3 | x | √ | postcss8 |
当前版本推荐使用 Vite 或 Webpack5 链路。HBuilderX Vue2 Webpack4 项目建议停留在旧版插件，或迁移到 Vue3 Vite / uni-app CLI Vue2 Webpack5。
## HBuilderX Vue2 Webpack（存量项目） {#hbuilderx-vue2-webpack}
当前版本不再内置 Webpack4 / PostCSS7 / Tailwind CSS v2 兼容入口。如果你必须维护 `hbuilderx vue2` 项目，请继续使用旧版 `weapp-tailwindcss`，或迁移到上方推荐的 Vite / Webpack5 链路。
## 不建议全局改 HBuilderX Vue2 编译器
:::caution
下面这种做法会改动 HBuilderX 内置编译器，影响同一台机器上的所有 HBuilderX Vue2 项目。除非你清楚回滚成本，否则不要在日常项目里使用。
:::
早期 HBuilderX Vue2 项目通常锁在 Webpack4 / PostCSS7。有人会直接升级 `HBuilderX/plugins/uniapp-cli` 里的 `@vue/cli-*`、loader、`postcss` 和 `postcss-loader`，把内置链路改到 Webpack5 / PostCSS8。
这不是推荐路径。它会让 HBuilderX 的全局编译环境和官方插件状态不一致，升级 HBuilderX 或重新安装编译插件后也可能失效。
> macOS uniapp-cli 路径在 /Applications/HBuilderX.app/Contents/HBuilderX/plugins/uniapp-cli
>
> Windows 的路径通常也在 HBuilderX 安装目录下。需要先安装 Vue2 编译插件，这个目录才会出现。
更稳的做法是迁移项目，或者用 uni-app CLI 单独维护 Vue2 Webpack5 链路。这样一个项目对应一套依赖，排查问题也简单。
## 视频演示
---
## ReactLynx / Rspeedy
`@weapp-tailwindcss/lynx` 通过 Rspeedy 的 Rspack 生命周期生成 Lynx 可消费的普通 CSS。它保留 ReactLynx 原生 `className`，不引入运行时样式表或 JSX 转换。
## 安装
```bash npm2yarn
npm install -D @weapp-tailwindcss/lynx tailwindcss
```
当前集成要求 Node.js `>=22.12.0`、Rspeedy `>=0.16.0` 和 Tailwind CSS `>=4.0.0`，仅支持 ReactLynx + Rspeedy 构建目标。
## 注册 Rspeedy 插件
```ts title="lynx.config.ts"
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginLynxTailwindcss } from '@weapp-tailwindcss/lynx'
export default defineConfig({
plugins: [pluginReactLynx(), pluginLynxTailwindcss()],
})
```
插件固定使用 `platform: 'lynx'`、`generator.target: 'web'` 与 Lynx 兼容输出。Tailwind CSS 4 的 theme 变量会在构建期静态化；应用自行定义的动态 CSS 变量保持不变。
## 配置 Tailwind CSS 入口
在应用 CSS 入口中引入 Tailwind CSS 4，并用 `@source` 指向实际源码。Lynx 不需要浏览器 preflight，推荐只引入 theme 与 utilities，以减少 Rspeedy 对浏览器专用规则的兼容警告。
```css title="src/global.css"
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities) source(none);
@source "./**/*.{ts,tsx}";
```
随后可以直接使用 ReactLynx 的 `className`：
```tsx
weapp-tailwindcss + Lynx
```
## 任意值与动态类名
任意值必须以完整静态字符串出现在 `@source` 覆盖的文件中：
```tsx
```
不要运行时拼接 `w-[${width}px]`。动态场景应枚举完整类名，或在 CSS 中显式注册候选：
```css
@source inline("w-[120px] w-[240px] bg-[#123456]");
```
Tailwind 能生成 CSS 不代表 Lynx 支持每个属性和选择器。当前 Lynx encoder 会删除 `padding-inline`、`mask-type` 等不支持的属性，以及包含复杂 `:is()` / `:where()` 的选择器。需要横向内边距时，优先使用 `pl-*` 与 `pr-*` 等物理方向 utility。伪元素、交互状态、媒体查询和复杂视觉效果必须在目标端验收。
## 构建警告
完整的 `@import "tailwindcss"` 会带入浏览器 preflight。Rspeedy 可能报告并移除 `:root`、`:host`、`:where(...)`、`::file-selector-button` 等 Lynx 不支持的规则。
- 浏览器专用 preflight 警告：改用上面的 theme + utilities 入口。
- 业务 utility 对应的属性或选择器警告：调整 Tailwind 写法，不能只忽略警告。
## 验证与示例
仓库中的完整示例位于 [`examples/react-lynx`](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/examples/react-lynx)。仓库开发者可以运行：
```bash
pnpm --filter @weapp-tailwindcss/lynx test
pnpm --filter @weapp-tailwindcss/example-react-lynx build
pnpm e2e:lynx
```
静态构建只能证明 CSS 已生成并进入 bundle。iOS Simulator 与 LynxExplorer 的视觉验收可运行 `pnpm e2e:lynx:ios`。
首版不覆盖 Rspeedy Web 输出、非 React Lynx 框架、Tailwind CSS 3 或 React Native 风格的运行时样式映射。
---
## Mpx
Mpx 使用 Webpack 链路，应显式配置 `cssEntries`，让 `weapp-tailwindcss` 稳定定位 Tailwind CSS 入口。
## 注册插件
在 `vue.config.js` 中注册：
```js title="vue.config.js"
const { defineConfig } = require('@vue/cli-service')
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
module.exports = defineConfig({
// other options
configureWebpack(config) {
config.plugins.push(
new WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
appType: 'mpx',
cssEntries: [
path.resolve(__dirname, 'src/app.css'),
],
})
)
}
})
```
## 引入 Tailwind CSS 样式
Tailwind CSS 生成由 `WeappTailwindcss` 接管，不要再注册 Tailwind 官方 PostCSS 生成插件。
当前文档仅维护 Tailwind CSS 4 接入说明。
```css title="src/app.css"
@import "tailwindcss";
@source "../src";
@source not "../dist";
@source not "../node_modules";
```
Tailwind 4 入口请放在纯 `.css` 文件里，不要直接放进 `scss`、`less`、`sass` 入口。
### 在 app.mpx 中引入
```html title="src/app.mpx"
```
## mpx 中的 vscode tailwindcss 智能提示缺失设置
如果在 `mpx` 文件中写 `class` 没有智能提示，可以在 VS Code 的 `Tailwind CSS IntelliSense` 扩展设置里处理。
在 `include languages` 里，把 `mpx` 标记为 `html`。
保存设置后，再到 `mpx` 文件里写 `class`，就能看到智能提示。
---
## 原生开发(打包方案)
:::warning
这是原生开发的打包方案。如果你需要纯原生方案，请查看 [快速开始（纯原生）](/docs/quick-start/native/install)。
:::
> 由于原生小程序没有 `webpack/vite/gulp` 工具链暴露出来，所以我们要添加这一套机制，来整个前端社区接轨，以此来实现更强大的功能。
:::tip
给原生小程序加入编译时这块 `webpack/vite/gulp` 等等工具，思路都是一样的，然而实现起来比较复杂，损耗精力，在此不提及原理。
更改模板工具链流程前，请确保你比较熟悉工具链开发（到我这样的水平就差不多了）。
另外这些模板，只需要稍微改一下产物后缀，调整 `@source` 扫描范围就可以适配百度，头条，京东...各个平台。
:::
## gulp 模板
模板项目 [weapp-tailwindcss-gulp-template(gulp打包)](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/gulp-app)
## weapp-vite 模板
如果你希望原生小程序也走 Vite 构建，推荐查看 [纯原生 weapp-vite 接入](/docs/quick-start/native/install)。当前文档面向 `tailwindcss@4`。当前文档仅维护 Tailwind CSS 4 接入说明。
然后在 `vite.config.ts` 中注册 `weapp-tailwindcss/vite`：
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
WeappTailwindcss({
cssEntries: [
resolve(projectRoot, 'app.css'),
],
cssOptions: {
rem2rpx: true,
},
}),
],
})
```
生成模式会接管 Tailwind CSS 生成和小程序转译，不需要再注册 `tailwindcss` PostCSS 插件，也不需要执行 `weapp-tw patch`。
Tailwind CSS 4 项目应显式配置 `cssEntries`，让 `WeappTailwindcss` 稳定读取入口 CSS 里的 `@source` 与 Tailwind 指令。`cssEntries` 只负责入口识别，入口 CSS 仍然要通过项目入口实际引入。
Tailwind CSS 4 的入口 CSS：
```css title="app.css"
@import "tailwindcss";
@source "./src/**/*.{wxml,js,ts,vue}";
@source "./app.{js,ts,json}";
@source not "./dist";
```
Tailwind 4 的入口只放在纯 `.css` 文件里。完整写法见 [纯原生 weapp-vite 接入](/docs/quick-start/native/install)。
## 组件样式的隔离性
:::tip
发现很多用户，在使用原生开发的时候，经常会问，为什么样式不生效。
这可能有以下几个原因:
1. 代码文件不在 `@source` 扫描范围内
2. 原生小程序组件是默认开启 **组件样式隔离** 的，默认情况下，自定义组件的样式只受到自定义组件 wxss 的影响。而 `tailwindcss` 生成的工具类，都在 `app.wxss` 这个全局样式文件里面。不属于组件内部，自然不生效。
这时候可以使用:
```js
/* 组件 custom-component.js */
Component({
options: {
addGlobalClass: true,
}
})
```
来让组件应用到 `app.wxss` 里的样式。
[微信小程序相关开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)
:::
## vscode tailwindcss 智能提示设置
我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。
如果在 `vscode` 的 `wxml` 文件中写 `class` 没有智能提示，可以按下面步骤处理。
这里我们以 `vscode` 为例:
1. 安装 [`WXML - Language Services 插件`](https://marketplace.visualstudio.com/items?itemName=qiu8310.minapp-vscode)(一搜 wxml 下载量最多的就是了)
2. 安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
接着找到 `Tailwind CSS IntelliSense` 的 `扩展设置`
在 `include languages` 里，把 `wxml` 标记为 `html`。
智能提示就出来了:
---
## Taro
Taro v4 可以走 Webpack，也可以走 Vite。新项目优先选 Webpack，问题少一些；Taro Vite 可以用，但更适合已有项目排障。
:::caution
如果 `tailwindcss` 工具类不生效，先检查微信开发者工具是否开启了 `代码自动热重载`。关闭它后再重新预览。
如果你同时使用 `NutUI`，或启用了 `@tarojs/plugin-html`，请先看这个[注意事项](/docs/issues/use-with-nutui)。
:::
下面的配置适用于 Taro 的 `react` / `preact` / `vue2` / `vue3`。文档默认你的源码都放在 `src` 目录下，这也是 Taro 模板的默认结构。
## Tailwind CSS 入口
当前文档面向 `tailwindcss@4`。当前文档仅维护 Tailwind CSS 4 接入说明。
小程序构建只注册 `WeappTailwindcss`。不要再在 PostCSS 中注册 `tailwindcss` 或 `@tailwindcss/postcss`，也不要为 Taro Vite 注册 `@tailwindcss/vite`。
```css title="src/app.css"
@import "tailwindcss" source(none);
@source "../src";
```
这里不用再单独写 `pages`、`components`。Taro 默认源码都在 `src` 里，扫 `../src` 更简单，也能覆盖你后面新增的 `src/features`、`src/utils`、`src/widgets` 这类目录。
`source(none)` 会关掉 Tailwind 4 的默认自动扫描，只按我们写的 `@source "../src"` 扫源码。这样不会把 `dist`、`node_modules` 这类目录带进来。
Tailwind 4 的入口请放在纯 `.css` 文件里。业务样式可以继续使用 Sass/Less，但不要把 `@import "tailwindcss"` 直接写进预处理入口。记得在 `src/app.ts` 或 `src/app.js` 里引入这个 CSS 文件：
```ts title="src/app.ts"
import './app.css'
```
## 使用 Webpack 作为打包工具
### 注册插件
在项目的配置文件 `config/index` 中注册。小程序和 H5 都需要注册 `WeappTailwindcss`：小程序目标会输出小程序可用 CSS，`TARO_ENV=h5` 时会自动切到 Web 目标。
```js title="config/index.[jt]s"
const path = require('node:path')
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
// 使用 ts 配置时，可以改用下方 import 写法
// import { WeappTailwindcss } from 'weapp-tailwindcss/webpack'
const projectRoot = path.resolve(__dirname, '..')
const weappTailwindcssOptions = {
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/app.css'),
],
}
function registerWeappTailwindcss(chain) {
chain.merge({
plugin: {
install: {
plugin: WeappTailwindcss,
args: [weappTailwindcssOptions],
},
},
})
}
{
mini: {
webpackChain(chain, webpack) {
// highlight-start
registerWeappTailwindcss(chain)
// highlight-end
}
},
h5: {
webpackChain(chain, webpack) {
// highlight-start
registerWeappTailwindcss(chain)
// highlight-end
}
}
}
```
然后正常运行项目即可。Tailwind CSS 4 项目应显式配置 `cssEntries`，同时仍要在 `src/app.ts` 或 `src/app.js` 里引入 `./app.css`。
如果你把 Tailwind 入口放到了别的目录，或者项目有多个 Tailwind 入口，把这些纯 `.css` 入口都写进 `cssEntries`：
```js title="config/index.[jt]s"
const path = require('node:path')
const projectRoot = path.resolve(__dirname, '..')
const weappTailwindcssOptions = {
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/app.css'),
],
}
```
`cssEntries` 指向的是 Tailwind 入口文件，请指向纯 `.css`。
不要在 H5 里写 `disabled: process.env.TARO_ENV === 'h5'`。小程序和 H5 都注册插件，`weapp-tailwindcss` 会按目标端处理。
:::info
`weapp-tailwindcss/webpack` 对应的推荐插件名 `WeappTailwindcss` 适用于 `webpack@5`
在使用 `Taro` 时，检查一下 `config/index` 文件的配置项 `compiler`，来确认你的 `webpack` 版本。当前版本不再内置 Webpack4 入口，推荐使用 `'webpack5'`
如果你使用了 [`taro-plugin-compiler-optimization`](https://www.npmjs.com/package/taro-plugin-compiler-optimization)，建议移除。它会让打包结果变得混乱。详见 [issues/123](https://github.com/sonofmagic/weapp-tailwindcss/issues/123) [issues/131](https://github.com/sonofmagic/weapp-tailwindcss/issues/131)
`taro` 的 `prebundle` 也容易干扰排查。如果项目启动异常且原因不明，可以先关闭这个配置。
:::
## 使用 Vite 作为打包工具
:::danger
`Taro Vite` 目前整体稳定性较差，已知问题和样式链路 bug 较多，不推荐在新项目里使用。
如果你没有强依赖 `Taro Vite`，优先选择 `Taro Webpack`、`uni-app`、`weapp-vite` 等更稳定的方案。
:::
Taro Vite 需要把 `WeappTailwindcss` 注册到 `config/index` 的 `compiler.vitePlugins`，这样小程序和 H5 都能走同一份插件配置。Tailwind CSS 由 `WeappTailwindcss` 生成，不需要再注册 Tailwind 官方 Vite 或 PostCSS 插件。
### 在 `config/index.ts` 中注册插件
```ts title="config/index.[jt]s"
import type { Plugin } from 'vite'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const baseConfig: UserConfigExport<'vite'> = {
// ... 其他配置
// highlight-start
compiler: {
type: 'vite',
vitePlugins: [
WeappTailwindcss({
cssOptions: {
// rem转rpx
rem2rpx: true,
// Taro Vite 可能移除 Tailwind CSS 变量，需要重新注入变量作用域
injectAdditionalCssVarScope: true,
},
})
] as Plugin[] // 从 vite 引入 type, 为了智能提示
},
// highlight-end
// ... 其他配置
}
```
Tailwind CSS 生成由 `weapp-tailwindcss` 接管，不需要再把 Tailwind 官方生成插件注册到 PostCSS 或 Vite 配置里。`src/app.css` 按上方写 Tailwind 4 入口。
Taro Vite 也应显式配置 `cssEntries`。它只负责让 `weapp-tailwindcss` 稳定读取 Tailwind CSS 入口，入口 CSS 仍然要通过 Taro 入口实际引入。
`TARO_ENV=h5` 时，生成器默认目标会自动切换为 `web`，不再需要写 `disabled: process.env.TARO_ENV === 'h5'`。如果 RN 或 Harmony 构建不希望插件参与，可以只针对这些目标显式设置 `disabled`。
> `vite.config.ts` 只有在运行小程序时才会加载，`h5` 不会。小程序 + h5 双端兼容请把插件注册放在 `config/index` 的 `compiler.vitePlugins` 中。
> `Taro Vite` 当前仍然不稳定，这部分内容仅作为历史方案和排障参考，不建议作为新项目默认选型。
## 视频演示
---
## uni-app CLI Vue3 Vite
:::warning
这是 `uni-app cli` 创建的 Vue3 Vite 项目。如果你使用 `HBuilderX` 创建项目，请看 [uni-app HBuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx)。
:::
## Tailwind 入口
当前文档面向 `tailwindcss@4`。当前文档仅维护 Tailwind CSS 4 接入说明。
Tailwind CSS 生成由 `WeappTailwindcss` 接管，不要在小程序构建里再注册 `tailwindcss`、`@tailwindcss/postcss` 或 `@tailwindcss/vite`。
```css title="src/app.css"
@import "tailwindcss";
@source "./**/*.{html,js,ts,jsx,tsx,vue}";
@source not "./uni_modules";
@source not "../node_modules";
@source not "../dist";
@source not "../unpackage";
```
Tailwind 4 的入口请放在纯 `.css` 文件里。业务里仍然可以使用 Sass/Less，但不要把 `@import "tailwindcss"` 直接写进预处理入口。
入口 CSS 还需要被项目实际引入，例如在 `src/App.vue` 的全局 `
```
## 扫描范围提醒
### 问题现象
如果项目把第三方插件或依赖放进 `src/uni_modules`，同时扫描整个 `src`，Tailwind 可能会把依赖源码里的正则片段、README 示例或产物误识别为 class，最终生成异常 CSS。
在小程序产物中，可能会看到类似：
```css
._ba-zA-Z_c__B {
a-z-a--z:;
}
```
### 根因
这不是业务代码真的写了这样的类名，而是扫描范围太宽，把第三方源码、文档或构建产物也纳入了提取范围。使用 `@source not` 排除这些目录。
### 最佳实践
- 扫描范围只覆盖业务源码，不要无差别扫整个 `src`
- 默认排除 `uni_modules`、`node_modules`、`dist`、`unpackage`
- 如果必须包含某个 `uni_modules` 包，只精确包含其中真正承载模板类名的文件
## 创建项目参考
可以通过 `cli` 命令创建项目，具体参数以 [uni-app 官网文档](https://uniapp.dcloud.net.cn/quickstart-cli.html) 为准：
- JavaScript 项目：
```bash
npx degit dcloudio/uni-preset-vue#vite my-vue3-project
```
- TypeScript 项目：
```bash
npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project
```
## 视频演示
---
## uni-app x
:::info 运行环境要求
使用 `weapp-tailwindcss@5.2.0` 或更高版本时，需要 Node.js `>=22.12.0` 和 HBuilderX `>=5.11`。Node.js 22 从 `22.12.0` 开始默认支持从 CommonJS 加载 ESM；较旧的 HBuilderX 内置 Node 可能无法加载当前依赖。
:::
`uni-app x` 使用 HBuilderX 和 `@dcloudio/vite-plugin-uni`。建议配合内置的 `uniAppX` 预设使用。
当前仓库的 HBuilderX 本地 E2E 覆盖了 uni-app x Web、微信小程序、Android、iOS 和鸿蒙。小程序与 App E2E 依赖本机 HBuilderX、开发者工具或模拟器，只在本地执行。
:::warning 能力边界
`uvue` 原生 App 端不要依赖 `gap`、`gap-x-*`、`gap-y-*`，这些布局能力当前都不支持。
`space-x-*`、`space-y-*` 也不要在 `uni-app x` 中使用。请直接改用子项显式 `mt-*` / `ml-*`，或封装固定结构的间距组件。
:::
```bash npm2yarn
npm run e2e:hbuilderx:local
npm run e2e:hbuilderx:local:web
npm run e2e:hbuilderx:local:mp
npm run e2e:hbuilderx:local:android
npm run e2e:hbuilderx:local:ios
npm run e2e:hbuilderx:local:harmony
```
## 注册插件
`uniAppX` 从 `weapp-tailwindcss/presets` 导出，应显式传入 `cssEntries`。
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
import { uniAppX } from 'weapp-tailwindcss/presets'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
uni(),
WeappTailwindcss(
uniAppX({
base: projectRoot,
cssEntries: [resolve(projectRoot, 'main.css')],
rem2rpx: true,
}),
),
],
})
```
Tailwind CSS 生成由 `weapp-tailwindcss` 接管，不要再注册 `tailwindcss`、`@tailwindcss/postcss` 或 `@tailwindcss/vite`。
当前文档仅维护 Tailwind CSS 4 接入说明。
:::info Web 与 App 调试注意
`cssEntries` 用来告诉 `weapp-tailwindcss` Tailwind CSS 4 的入口文件，入口仍应是 HBuilderX / Vite 能处理到的真实 CSS 文件。Web/H5、Android 和 iOS 都需要保持 `appType: 'uni-app-x'`，不要因为运行到 Web 端手动关闭 `uniAppX`，否则 `.uvue` 模板里的任意值类名不会转换成安全选择器。
`rem2rpx`、`unitsToPx`、`unitConversion` 是 `uniAppX()` 预设的顶层选项，不要放进 `cssOptions`。
:::
## Tailwind CSS 入口
Tailwind CSS 4 使用 CSS-first 入口，`@source` 要覆盖页面、组件和可能产出类名的脚本目录：
```css title="main.css"
@import "tailwindcss" source(none);
@source "./App.uvue";
@source "./pages/**/*.{uts,uvue}";
@source "./components/**/*.{uts,uvue}";
@source "./stores/**/*.{uts,uvue}";
@source not "./uni_modules/**/*";
@source not "./unpackage/**/*";
```
不要把 `unpackage` 放进扫描范围，否则 HBuilderX 产物会反过来干扰开发构建。
## 在 App.uvue 中引入入口
`cssEntries` 负责生成入口识别，不负责把 CSS 自动加入 HBuilderX / Vite 模块图。必须在全局样式中实际导入：
```html title="App.uvue"
```
如果缺少这个导入，Tailwind 可以扫描到 `.uvue` 候选，但 Web、小程序和 App 页面都不会加载生成样式。
## 验证任意值类名
在任意页面写一段最小用例：
```html
Tailwind CSS
```
依次运行到 Web、微信小程序和目标 App 平台后，检查元素样式是否生效。App 端文本使用 ``，文本相关样式要直接写在 `` 上。
## 参考模板
- [仓库内 Tailwind CSS 4 demo](https://github.com/sonofmagic/weapp-tailwindcss/tree/next/demo/uni-app-x-hbuilderx-tailwindcss-v4)
---
## uni-app CLI Vue2 Webpack
:::caution
这条 `uni-app cli vue2 webpack` 路线已经不推荐，仓库中的对应 classic demo 也已经移除。
新项目请直接使用 [uni-app cli vue3 vite](/docs/quick-start/frameworks/uni-app-vite)。
:::
:::warning
本文仅作为存量项目归档说明保留，不再作为推荐接入方式。
:::
```js title="vue.config.js"
const path = require('node:path')
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
/**
* @type {import('@vue/cli-service').ProjectOptions}
*/
const config = {
// some option...
// highlight-start
configureWebpack: (config) => {
config.plugins.push(
new WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
cssEntries: [
path.resolve(__dirname, 'src/app.css'),
],
})
)
}
// highlight-end
// other option...
}
module.exports = config
```
`src/app.css` 使用 Tailwind CSS 4 入口。当前文档仅维护 Tailwind CSS 4 接入说明。
```css title="src/app.css"
@import "tailwindcss";
@source "./**/*.{html,js,ts,jsx,tsx,vue}";
@source not "../dist";
@source not "../node_modules";
@source not "../unpackage";
```
扫描范围写在 CSS 入口的 `@source` 里。生成模式下不要再在 PostCSS 中注册 Tailwind 官方生成插件。
`cssEntries` 只负责入口识别，存量项目仍要在 `src/App.vue` 的全局样式中 `@import './app.css';`，否则生成 CSS 不会进入 Webpack 模块图。
---
## Tailwind CSS 多入口与分包隔离
小程序拆分主包、普通分包和独立分包后，通常不希望把所有 Tailwind 工具类复制到每一份样式产物中。更合理的结果是：
- 主包入口只生成主包使用的工具类。
- 普通分包入口只生成该分包使用的工具类。
- 独立分包入口只生成该独立分包使用的工具类。
- 分包页面通过 `@import` 引用本分包入口，同时保留页面自己的局部 CSS。
独立分包尤其需要单独的样式入口，因为主包中的全局样式不会作用到独立分包。
## 三项配置分别负责什么
| 配置 | 职责 |
| --- | --- |
| `cssEntries` | 告诉 `weapp-tailwindcss` 哪些文件是 Tailwind CSS 入口 |
| 入口中的 `@source` | 决定当前入口扫描哪些模板和脚本、生成哪些候选类 |
| `styleInjector.rules` | 生成分包入口资产，并把入口通过 `@import` 注入匹配的页面或组件样式 |
`styleInjector` 不负责扫描模板，也不会替代 `cssEntries`。反过来，`cssEntries` 只负责识别和生成入口，不会自动让分包页面引用入口。三者需要一起配置。
## 目录结构
下面以 uni-app Vite + Tailwind CSS 4 为例：
```text
src/
├── main.css
├── main.ts
├── pages/
│ └── index/index.vue
├── sub-normal/
│ ├── index.css
│ └── pages/
│ ├── index.css
│ └── index.vue
└── sub-independent/
├── index.css
└── pages/
├── index.css
└── index.vue
```
`main.css`、两个分包根目录下的 `index.css` 是三份 Tailwind 入口。页面目录中的 `index.css` 只是页面局部样式，不包含 Tailwind 入口指令。
## 配置 cssEntries 与内置 Style Injector
`weapp-tailwindcss` 已内置 `weapp-style-injector`，无需再注册一个独立插件：
```ts title="vite.config.ts"
import { createRequire } from 'node:module'
import { dirname } from 'node:path'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import uni from '@dcloudio/vite-plugin-uni'
import { defineConfig } from 'vite'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const require = createRequire(import.meta.url)
const projectRoot = dirname(fileURLToPath(import.meta.url))
const uniMpVueRuntimePath = require.resolve('@dcloudio/uni-mp-vue/dist/vue.runtime.esm.js')
export default defineConfig({
plugins: [
uni(),
WeappTailwindcss({
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/main.css'),
path.resolve(projectRoot, 'src/sub-normal/index.css'),
path.resolve(projectRoot, 'src/sub-independent/index.css'),
],
styleInjector: {
rules: {
'index.css': [
'pages/**/*.css',
'pages/**/*.wxss',
'pages/**/*.acss',
'pages/**/*.ttss',
'pages/**/*.qss',
'pages/**/*.jxss',
],
},
},
}),
],
resolve: {
alias: {
'@dcloudio/uni-mp-vue/dist/vue.runtime.esm.js': uniMpVueRuntimePath,
},
},
})
```
uni-app 预设会读取 `pages.json` 中的分包根目录。规则里的 `index.css` 会分别匹配：
- `src/sub-normal/index.css`
- `src/sub-independent/index.css`
目标 glob 覆盖常见小程序样式后缀和 H5 的 `.css`。如果项目只构建微信小程序，可以缩小为 `pages/**/*.wxss`。
## 限定三个入口的扫描范围
主包入口只扫描主包页面，并显式排除两个分包：
```css title="src/main.css"
@import "tailwindcss" source(none);
@config "../tailwind.config.js";
@source "./pages/**/*.{vue,js,ts}";
@source not "./sub-normal/**/*";
@source not "./sub-independent/**/*";
```
普通分包入口只扫描普通分包：
```css title="src/sub-normal/index.css"
@import "tailwindcss" source(none);
@config "../../tailwind.config.sub-normal.js";
@source "./pages/**/*.{vue,js,ts}";
```
独立分包入口只扫描独立分包：
```css title="src/sub-independent/index.css"
@import "tailwindcss" source(none);
@config "../../tailwind.config.sub-independent.js";
@source "./pages/**/*.{vue,js,ts}";
```
每个 `@config` 的 `content` 也应保持相同边界。不要让主配置重新扫描全部分包，否则会绕过入口中的隔离意图。
## 页面只引入局部 CSS
分包页面不需要手工引入根目录的 Tailwind 入口：
```vue title="src/sub-normal/pages/index.vue"
normal subpackage
```
```css title="src/sub-normal/pages/index.css"
.normal-page-local {
border-width: 3rpx;
}
```
构建时，内置 Style Injector 会生成分包入口，并把引用插入页面产物。
## 预期产物
以微信小程序为例：
| 产物 | 应包含 | 不应包含 |
| --- | --- | --- |
| `main.wxss` | 主包专属工具类 | 普通分包、独立分包专属工具类 |
| `sub-normal/index.wxss` | 普通分包专属工具类 | 主包、独立分包专属工具类 |
| `sub-independent/index.wxss` | 独立分包专属工具类 | 主包、普通分包专属工具类 |
| `sub-normal/pages/index.wxss` | 页面局部 CSS、`@import "../index.wxss"` | 三组入口工具类的内联副本 |
| `sub-independent/pages/index.wxss` | 页面局部 CSS、`@import "../index.wxss"` | 三组入口工具类的内联副本 |
页面产物类似：
```css title="dist/build/mp-weixin/sub-normal/pages/index.wxss"
@import "../index.wxss";
.normal-page-local {
border-width: 3rpx;
}
```
隔离针对的是入口专属候选。若主包和多个分包都使用 `text-white`，每个入口各自生成该共享工具类是正常现象。
## 独立使用 weapp-style-injector
如果项目没有使用 `weapp-tailwindcss`，或者只需要注入已经生成的样式入口，可以独立注册框架预设：
```ts
import uni from '@dcloudio/vite-plugin-uni'
import { defineConfig } from 'vite'
import { StyleInjector } from 'weapp-style-injector/vite/uni-app'
export default defineConfig({
plugins: [
uni(),
StyleInjector({
rules: {
'index.css': ['pages/**/*.wxss'],
},
}),
],
})
```
已经使用 `weapp-tailwindcss` 时，优先使用内置 `styleInjector`，避免注册两套相同的构建生命周期。
## 验证
先构建微信小程序：
```bash
pnpm build:mp-weixin
```
如果项目支持其他平台，再至少检查一个非微信目标，例如支付宝或抖音：
```bash
pnpm build:mp-alipay
pnpm build:mp-toutiao
```
验证时不要只检查固定的 `app.wxss` 文件名，应按真实平台后缀检查 `.wxss`、`.acss`、`.ttss` 等产物，并同时做正向和反向断言，确认入口之间没有串包。
## 完整示例
仓库中的 [subpackage-uni-app-vite-tailwindcss-v4](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/subpackage-uni-app-vite-tailwindcss-v4) demo 同时覆盖：
- 内置 `styleInjector` 的隔离入口模式。
- 主包、普通分包、独立分包的候选隔离。
- 微信、支付宝、抖音和 H5 产物。
- 用于兼容性回归的单入口模式。
---
## 安装依赖
这一页只处理包安装。框架注册方式放到下一章。
## 安装当前版本
当前文档面向 `tailwindcss@4` 与最新版 `weapp-tailwindcss`。当前文档仅维护 Tailwind CSS 4 接入说明。
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
下一步：进入 [各框架注册方式](/docs/quick-start/frameworks/uni-app-vite)。
---
## IDE 智能提示设置
## VS Code
> 首先，确保你已经安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
### 让 `Tailwind CSS IntelliSense` 识别 Tailwind CSS v4
`tailwindcss-intellisense` 在 Tailwind CSS 4 中必须看到 `@import "tailwindcss"` 才会将工作区视为 Tailwind 根文件。生成模式也推荐在真实入口直接写 `@import 'tailwindcss';`，再由 `WeappTailwindcss` 输出小程序目标 CSS。
如果仍希望与源码解耦，也可以使用 CLI 为 VS Code 生成一个仅供扩展使用的辅助 CSS：
```bash npm2yarn
npx weapp-tailwindcss vscode-entry --css src/app.css
```
- 默认输出在 `.vscode/weapp-tailwindcss.intellisense.css`，其中包含 `@import 'tailwindcss';`、常见的 `@source` globs 以及你传入的 CSS 入口（例如 `src/app.css`）。
- 该文件只用于激活 IntelliSense，不需要、也不应该被打包流程引用。
- 若需自定义文件名或额外的 `@source`，可通过 `--output`、`--source`、`--force` 等参数调整，运行 `npx weapp-tailwindcss vscode-entry --help` 查看全部选项。
- 如果不想生成独立文件，可以直接在真实入口写 `@import 'tailwindcss';`，并把这个入口写入 `tailwindCSS.experimental.configFile`。
保存/重载任意文件后 VS Code 会检测到该辅助文件，从而让 Tailwind CSS 4 项目享受到完整的补全、悬浮和跳转体验。
如果你希望显式告诉 `Tailwind CSS IntelliSense`“某个 CSS 根文件对应哪些源码目录”，可以继续补充 `tailwindCSS.experimental.configFile`：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": {
".vscode/weapp-tailwindcss.intellisense.css": "src/**"
}
}
```
- 键名是给 `Tailwind CSS IntelliSense` 使用的 CSS 入口文件路径，它通常需要包含 `@import "tailwindcss";`。
- 键值是这个入口生效的源码范围，支持 glob；上面的配置表示，当你编辑 `src/**` 下的文件时，扩展会使用 `.vscode/weapp-tailwindcss.intellisense.css` 作为 Tailwind 根文件。
- 在 monorepo 或一个工作区里有多个 Tailwind 入口时，这种写法比“让扩展自动猜测”更稳定，也适合配合 `npx weapp-tailwindcss vscode-entry` 生成的辅助 CSS 一起使用。
### wxml 的智能提示
我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。
假如你遇到了，在 `vscode` 的 `wxml` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。
这里我们以 `vscode` 为例:
安装 [`WXML - Language Services 插件`](https://marketplace.visualstudio.com/items?itemName=qiu8310.minapp-vscode)(一搜 wxml 下载量最多的就是了)
然后下方提供了 `2` 种方式, `全局设置` 和 `工作区设置`, 根据你的需求仍选其一即可
#### 全局设置
点击 `vscode` 左下角的设置图标里，通过搜索关键词 `tailwindcss` ，找到 `Tailwind CSS IntelliSense` 插件的 `扩展设置`
在 `include languages`,手动标记 `wxml` 的类型为 `html`
智能提示就出来了:
#### 工作区设置
在你的打开的工作区目录的根目录里，创建 `.vscode` 文件夹，然后添加 `settings.json` 内容如下:
```json
{
"tailwindCSS.includeLanguages": {
"wxml": "html"
}
}
```
这样就通过你工作区的 `vscode` 设置，去覆盖了你全局的 `vscode` 设置，也能够达到上图中的效果。
### js,jsx,ts,tsx,vue...这类文件的智能提示
#### 场景
在安装配置好插件后，我们在写代码时，写到那些标签中的 `class=`,`className=`，这种场景时，智能提示一下子就可以出来。
然而我们在写 `js` 代码的时候，很多时候是直接在代码里，去写 `tailwindcss` 字符串字面量，比如:
```jsx
const clsName = 'bg-[#123456] text-[#654321]'
return
```
写这种字符串是没有任何的智能提示的，怎么办呢？
#### 解决方案
这里给出一种基于插件的解决方案：
1. 安装 `clsx`:
```bash npm2yarn
npm i clsx
```
2. 进入你的 `vscode` 设置的 [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings)
在里面加入下方的配置:
```json
{
"tailwindCSS.experimental.classRegex": [
[
"clsx\\(([^)]*)\\)",
"(?:'|\"|`)([^']*)(?:'|\"|`)"
]
]
}
```
这样配置之后，智能提示就出来了:
[Refer link](https://github.com/lukeed/clsx#tailwind-support)
#### 存在问题
这种原理也是依赖正则匹配，即 `Tailwind CSS IntelliSense 插件` 匹配到了当前 `vscode` 活动的文本域中，存在着 `clsx()` 方法这个关键词，所以就把智能提示给注入进去。
所以你这样写就不会生效:
```js
import { clsx as AAA } from 'clsx'
const btn = AAA('')
```
另外，你可以依据这个特性，修改/添加 `"tailwindCSS.experimental.classRegex"` 里的正则，然后自行封装一个方法，用来进行 `tailwindcss` 的智能提示。
## WebStorm
> 和 `vscode` 方式类似，同样使用 `clsx` 函数
1. 确保你的版本大于等于 [WebStorm 2023.1](https://www.jetbrains.com/webstorm/whatsnew/#version-2023-1-tailwind-css-configuration)
2. 打开设置，前往 [Languages and Frameworks | Style Sheets | Tailwind CSS](https://www.jetbrains.com/help/webstorm/tailwind-css.html#ws_css_tailwind_configuration)
3. 添加以下的配置:
```json
{
"experimental": {
"classRegex": ["clsx\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
}
}
```
> 如果你使用 `class-variance-authority` 的 `cva` 函数，只需再添加 `"cva\\(([^)]*)\\)"` 正则即可。
## HbuilderX
---
## 1. 安装与配置 Tailwind CSS
## 前言
本教程演示原生微信小程序 JS 模板接入 `tailwindcss@4` 与 `weapp-tailwindcss` 的方式。重点是两件事：源码要进入 Tailwind 扫描范围，小程序目标转译交给 `weapp-tailwindcss`。
当前文档仅维护 Tailwind CSS 4 接入说明。
### 运行环境
从 `weapp-tailwindcss@5.2.0` 开始，需要 Node.js `>=22.12.0`。Node.js 22 从该版本开始默认支持从 CommonJS 加载 ESM，这也是当前仓库与核心包的 engines 要求。Node 版本不满足时，不建议用 `--ignore-engines` 硬装，后续构建错误会更难排查。
如果项目通过 HBuilderX 运行 `uni-app` 或 `uni-app x`，还需要升级到 HBuilderX `>=5.11`，确保 IDE 内置 Node 能正确加载当前 ESM 依赖。
## 创建项目
打开微信开发者工具, 点击 `+` 创建一个项目，依次选择:
0. `AppID` 使用测试号
1. 开发模式: `小程序`
2. 后端服务: `不使用云服务`
3. 模板选择: 第二项选择 `基础`
4. 选择 `JS 基础模板`
> 使用 JS 基础模板创建的项目，依然可以使用 `Typescript`
先把 Tailwind CSS 的入口准备好，下一页再注册 `weapp-tailwindcss` 和 `weapp-vite`。
## 0. 初始化 `package.json`
如果使用原生 JS 模板创建项目，项目目录里通常没有 `package.json`。
这时需要先执行：
`npm init -y`，在项目下创建 `package.json`。
## 1. 安装 Tailwind CSS
```bash npm2yarn
# 安装 tailwindcss 和 weapp-tailwindcss
npm i -D tailwindcss weapp-tailwindcss
```
`weapp-tailwindcss` 会接管 Tailwind CSS 生成，不要再创建 Tailwind 专用的 `postcss.config.js`。如果项目已有 PostCSS 配置，只保留业务自己的非 Tailwind 插件。
## 2. 配置扫描范围
Tailwind CSS 4 在 CSS 入口里写扫描范围：
```css title="app.css"
@import "tailwindcss";
@source "./components/**/*.{wxml,js,ts}";
@source "./pages/**/*.{wxml,js,ts}";
@source "./app.{js,ts,json}";
@source not "./node_modules";
@source not "./dist";
```
Tailwind 4 的入口请放在纯 `.css` 文件里。不要直接写进 `less`、`scss`、`sass` 入口。
## 3. 引入 Tailwind CSS
在小程序项目入口样式文件中写 Tailwind 入口，使用上方的 `@import "tailwindcss";` 和 `@source`。
在入口 CSS 加入这一段代码后，微信开发者工具可能会先报错。这通常是因为 `weapp-tailwindcss` 插件还没有注册完成。
下一步继续安装并注册 `weapp-tailwindcss`。
---
## 2. 安装这个插件并运行
## 安装插件
在项目目录下，执行:
```bash npm2yarn
npm i -D weapp-tailwindcss weapp-vite
```
这样 `weapp-tailwindcss` 和 `weapp-vite` 就被安装在你的本地了
## 执行初始化命令
在命令行中运行
```sh
npx weapp-vite init
```
这个命令会对现有的原生小程序项目，进行 `weapp-vite` 的初始化
执行后，会发现主要有许多文件改动，`CLI` 主要做了 `3` 件事情:
- 创建 `vite.config.ts` 文件，这个是 `weapp-vite` 和 `vite` 的配置文件
- 修改 `package.json`, 添加 `dev` 和 `build` 开发和构建脚本，还有构建 `npm` 和打开微信开发者工具
- 修改 `project.config.json` 内容，来适配构建产物
- 添加适配 vite 的 `dts` 和 `tsconfig.json`
## 安装所有的依赖包
在执行完成 `weapp-vite init` 初始化命令之后，我们需要在项目里执行一下安装命令:
```bash npm2yarn
npm i
```
## 注册插件
在你的 `vite.config.ts` 里对插件进行注册:
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
// highlight-start
plugins: [
WeappTailwindcss({
cssEntries: [
resolve(projectRoot, 'app.css'),
],
cssOptions: {
rem2rpx: true,
},
}),
],
// highlight-end
})
```
Tailwind CSS 4 的扫描范围写在 CSS 入口的 `@source` 里。生成模式下不要再注册 Tailwind 官方生成插件，也不需要执行 `weapp-tw patch`。当前文档仅维护 Tailwind CSS 4 接入说明。
Tailwind CSS 4 项目应显式配置 `cssEntries`。`cssEntries` 只负责让 `WeappTailwindcss` 稳定读取入口 CSS，入口 CSS 仍然要通过项目入口实际引入；如果有多个 Tailwind CSS 入口，就都写进数组：
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
cssEntries: [
resolve(projectRoot, 'app.css'),
],
}),
],
})
```
## 开始运行
使用 `npm run dev` 进入开发模式, 此模式带有热更新的，主要用于开发
使用 `npm run build` 进行构建
不论是 `npm run dev` 还是 `npm run build`, 他们的构建产物，都在工程目录下的 `dist` 目录
使用微信开发者工具，直接导入工程目录，然后即可预览效果！
> 注意不是导入 `dist` 目录，是你工程的根目录! 通常是 `dist` 的父级目录，不要搞错了！
## 配置好的模板
如果配置不成功，可以用下面的模板对比配置文件：
[weapp-vite-tailwindcss-template](https://github.com/weapp-vite/weapp-vite/tree/main/apps/weapp-vite-tailwindcss-template)
或者直接执行命令:
```bash npm2yarn
npx weapp-vite create my-app
```
此命令会在当前目录下，创建一个目录名为 `my-app` 的 `weapp-vite` + `weapp-tailwindcss` 集成模板
{/* [vite-native](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/apps/vite-native) */}
{/* [native-weapp-tailwindcss-template](https://github.com/sonofmagic/native-weapp-tailwindcss-template) */}
## 原生组件样式的隔离性
:::tip
发现很多用户，在使用原生开发的时候，经常会问，为什么 `tailwindcss` 样式对自定义组件不生效。
这可能有以下几个原因:
1. 代码文件不在 `@source` 扫描范围内
2. 原生小程序组件是默认开启 **组件样式隔离** 的，默认情况下，自定义组件的样式只受到自定义组件 `wxss` 的影响。而 `tailwindcss` 生成的工具类，都在 `app.wxss` 这个全局样式文件里面。不属于组件内部，自然不生效。
这时候可以在你组件的 `json` 文件配置中，设置下面一行 `styleIsolation` 来开启样式共享:
```json title="custom-component.json"
{
"styleIsolation": "apply-shared"
}
```
> `apply-shared` 表示页面 `wxss` 样式将影响到自定义组件，但自定义组件 `wxss` 中指定的样式不会影响页面；
来让组件应用到 `app.wxss` 里的样式。
更多的文档详见: [微信小程序相关开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)
:::
## 想了解更多 weapp-vite
更多场景和配置，请查看 [weapp-vite 文档网站](https://vite.icebreaker.top/)
---
## React Native / Expo
`@weapp-tailwindcss/react-native` 是独立的 React Native 编译器包。它复用 `weapp-tailwindcss` 的 Tailwind CSS v4 source 扫描和候选集合，将生成的原始 CSS 编译为内存中的 RN style manifest；运行时不依赖 NativeWind 或 `react-native-css`。
## 安装
```bash
pnpm add @weapp-tailwindcss/react-native
pnpm add -D tailwindcss
```
首个版本面向 Expo SDK 54+、React 19、React Native 0.81+。项目仍然使用 `pnpm` 和仓库要求的 Node 版本。
## CSS 入口
```css title="global.css"
@import "tailwindcss";
@source "./src/**/*.{js,jsx,ts,tsx}";
```
## Metro 与 Babel
```js title="metro.config.js"
const { getDefaultConfig } = require('expo/metro-config')
const { withWeappTailwindcss } = require('@weapp-tailwindcss/react-native/metro')
const config = getDefaultConfig(__dirname)
module.exports = withWeappTailwindcss(config, {
input: './global.css',
sourceGlobs: ['./src/**/*.{js,jsx,ts,tsx}'],
})
```
```js title="babel.config.js"
module.exports = function (api) {
api.cache(true)
return {
presets: ['babel-preset-expo'],
}
}
```
Expo 只配置一次 Metro；它会把 source 扫描、manifest 生成和 Babel JSX transform 自动接起来，不再手写第二份 `classNameSet`。静态 `className="flex items-center"` 会编译为预生成的 StyleSheet lookup，不会在 render 中调用通用 `tw()`；动态 `className={condition ? "bg-red-500" : "bg-blue-500"}` 才会保留为受控的 `tw(...)` 调用。普通 inline `style` 覆盖 Tailwind class，`!important` class 覆盖 inline style。非 Expo 或定制 Metro 场景仍可显式使用 `@weapp-tailwindcss/react-native/babel`。
## 运行时与边界
Metro virtual module 会把 manifest、`Platform.OS` 和 `Appearance` 颜色模式注入 runtime，因此 `dark:`、`ios:`、`android:`、`native:` 变体可以按当前环境选择规则。编译器覆盖常用 layout、flex、spacing、sizing、colors、typography、border、radius、opacity、transform、shadow 和 arbitrary values；浏览器 preflight 默认忽略。不支持的 CSS 特性会产生中文 warning，可在 `manifest.warnings` 中检查。
类型增强从 `@weapp-tailwindcss/react-native/env` 引入；普通自定义组件只要接收 `className` 和 `style` 就可以复用同一套写法，不需要第三方组件 prop 映射。
```ts
import { tw } from '@weapp-tailwindcss/react-native/runtime'
const style = tw(condition ? 'bg-red-500' : 'bg-blue-500')
```
Tailwind 仍由 `weapp-tailwindcss` generator 生成，不要同时注册 `@tailwindcss/vite` 或 `@tailwindcss/postcss`。Expo Web 只建议作为 smoke test，Android/iOS 模拟器或真机才是首个版本的验收目标。
## 验证
```bash
pnpm --filter @weapp-tailwindcss/react-native test
pnpm --filter @weapp-tailwindcss/react-native build
pnpm --filter @weapp-tailwindcss/example-react-native-expo build
pnpm --filter @weapp-tailwindcss/example-react-native-expo test
```
---
## uni-app 条件编译样式
Tailwind CSS v4 可以直接用 `@custom-variant` 描述 uni-app 的条件编译分支，不再需要额外声明 `weapp-tailwindcss/css-macro`。它适合多端项目里少量平台差异样式，比如“微信小程序蓝色，H5 橙色”，或者“非微信小程序隐藏某个样式分支”。
## 能解决什么
uni-app 本身支持 CSS 条件编译：
```css
/* #ifdef MP-WEIXIN */
.button {
background: #1677ff;
}
/* #endif */
```
写 Tailwind 原子类时，可以先在入口 CSS 中定义条件变体：
```css
@import "tailwindcss";
@custom-variant wx {
/* #ifdef MP-WEIXIN */
@slot;
/* #endif */
}
@custom-variant not-wx {
/* #ifndef MP-WEIXIN */
@slot;
/* #endif */
}
```
然后在模板里使用语义化前缀：
```html
微信小程序为蓝色，其他平台为红色
```
也可以定义 H5 / 小程序组合条件：
```css
@custom-variant h5-or-wx {
/* #ifdef H5 || MP-WEIXIN */
@slot;
/* #endif */
}
@custom-variant not-h5-or-wx {
/* #ifndef H5 || MP-WEIXIN */
@slot;
/* #endif */
}
```
```html
H5 和微信小程序使用蓝色，其他平台使用灰色
```
## 当前生成链路
`@custom-variant` 由 Tailwind CSS v4 原生解析。`weapp-tailwindcss` 继续负责生成目标端 CSS、处理小程序选择器兼容与平台裁剪：
1. Tailwind CSS 根据 `@custom-variant` 生成带条件编译注释的工具类规则。
2. `weapp-tailwindcss` 在生成目标端 CSS 时保留条件注释结构。
3. 当构建链路能识别当前平台时，会在最终样式输出前裁剪不匹配分支；识别不到平台时，条件注释交给后续 uni-app 构建处理。
这意味着：
- 小程序目标构建会输出已经适配小程序选择器的样式，并移除不匹配的平台分支。
- H5 / Web 目标构建会保留 Web 选择器格式，并同样按平台裁剪。
- 不需要再配置 `@plugin "weapp-tailwindcss/css-macro"`。
- 不需要手动注册 `weapp-tailwindcss/css-macro/postcss`。
## 推荐写法
把平台差异集中在入口 CSS 中，模板里只使用业务可读的变体名：
```css
@import "tailwindcss";
@source "../src/**/*.{vue,js,ts,jsx,tsx,wxml,axml}";
@custom-variant wx {
/* #ifdef MP-WEIXIN */
@slot;
/* #endif */
}
@custom-variant h5 {
/* #ifdef H5 */
@slot;
/* #endif */
}
@custom-variant app {
/* #ifdef APP-PLUS */
@slot;
/* #endif */
}
```
```html
不同平台使用不同背景色
```
如果需要“非某平台”分支，单独声明反向变体：
```css
@custom-variant not-app {
/* #ifndef APP-PLUS */
@slot;
/* #endif */
}
```
```html
App 隐藏，其他平台显示
```
## 平台表达式
条件注释中的平台表达式仍然使用 uni-app 官方语法：
```css
@custom-variant mp {
/* #ifdef MP */
@slot;
/* #endif */
}
@custom-variant wx-or-alipay {
/* #ifdef MP-WEIXIN || MP-ALIPAY */
@slot;
/* #endif */
}
```
常见平台值包括：
- `H5` / `WEB`
- `MP-WEIXIN`
- `MP-ALIPAY`
- `MP-TOUTIAO`
- `MP-QQ`
- `MP`
- `APP` / `APP-PLUS`
- `QUICKAPP-WEBVIEW`
完整平台值以 uni-app 官方条件编译文档为准。
## 平台裁剪行为
当构建链路能拿到当前平台时，`weapp-tailwindcss` 会在最终样式输出前裁剪条件分支。平台来源包括 `cssOptions.platform` 和常见环境变量：
- `WEAPP_TW_TARGET`
- `WEAPP_TAILWINDCSS_TARGET`
- `UNI_PLATFORM`
- `UNI_UTS_PLATFORM`
- `TARO_ENV`
- `MPX_CLI_MODE`
- `MPX_CURRENT_TARGET_MODE`
例如当前平台为 `mp-weixin` 时：
```html
```
最终只保留匹配微信小程序的 `bg-blue-500` 分支，不会把 `#ifndef MP-WEIXIN` 的样式残留到最终样式里。
## 旧 css-macro 写法迁移
旧项目里的写法可以按下面方式迁移：
```diff
@import "tailwindcss";
-@plugin "weapp-tailwindcss/css-macro";
+@custom-variant wx {
+ /* #ifdef MP-WEIXIN */
+ @slot;
+ /* #endif */
+}
+
+@custom-variant not-wx {
+ /* #ifndef MP-WEIXIN */
+ @slot;
+ /* #endif */
+}
```
模板中把动态平台表达式改成稳定别名：
```diff
-
+
```
常规项目不要再手动添加 `weapp-tailwindcss/css-macro/postcss`：
```diff
// postcss.config.js / vite.config.ts
plugins: [
- require('weapp-tailwindcss/css-macro/postcss'),
]
```
## 在 `@apply` 中使用
条件变体也可以放进 CSS 的 `@apply`：
```css
.apply-test {
@apply wx:bg-blue-400 not-wx:bg-red-400;
}
```
和模板 class 一样，最终会按目标平台裁剪。
## IDE 智能提示
安装 VS Code / WebStorm 的 Tailwind CSS 官方插件后，在入口 CSS 中声明的 `@custom-variant` 名称可以参与补全。
如果刚改完配置没有提示，先重启编辑器的 Tailwind CSS Language Server。
---
## UnoCSS 写法兼容
`weapp-tailwindcss` 仍然使用 Tailwind CSS 作为样式生成引擎。`unocss` 配置只负责兼容一部分常见的 UnoCSS class 写法，默认关闭。
## 1. 启用方式
```ts
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
export default {
plugins: [
WeappTailwindcss({
unocss: true,
}),
],
}
```
开启后会同时做两件事：
| 能力 | 说明 |
| --- | --- |
| 裸任意值生成 | 将 `p-10%`、`bg-#fff`、`text-rgb(255,0,0)` 等候选交给 Tailwind CSS v4 运行时生成链路处理。 |
| class 名称转义 | 继续使用 `weapp-tailwindcss` 现有的 `customReplaceDictionary` 转义链路，例如默认会把 `:`、`[`、`#` 转为小程序安全字符。 |
> 注意：JS 转译仍然遵循 `classNameSet` 精确命中原则，不会对普通字符串做启发式猜测。
## 2. 支持的写法
开启 `unocss: true` 后，Tailwind CSS v4 生成链路可以识别下面这类写法：
| 类型 | 示例 |
| --- | --- |
| 尺寸与间距 | `p-10%`、`p-2.5px`、`m-4rem`、`w-100px`、`h-50vh`、`m-10rpx`、`rounded-10px` |
| 颜色 | `bg-#fff`、`text-#f00`、`border-#123456`、`from-#123`、`via-#456`、`to-#789` |
| 函数值 | `text-rgb(255,0,0)`、`bg-rgba(0,0,0,0.5)`、`w-calc(100%-1rem)`、`bg-var(--brand)` |
| 部分变体组合 | `hover:!-mt-2rem`、`dark:bg-#000`、`group-hover:bg-#fff` |
原本 Tailwind 支持的任意值写法仍然可用：
```html
```
## 3. 当前不支持的写法
`unocss` 配置不是 UnoCSS 引擎，也不会加载 UnoCSS preset。下面这些写法不属于当前兼容范围：
| 写法 | 原因 |
| --- | --- |
| `i-carbon-add` | 这是 UnoCSS Icons preset 语法，Tailwind CSS 不会生成对应图标规则。 |
| `~mt-2/4` | 这是 UnoCSS/Windi shortcut 风格，当前不会展开。 |
| `bg-$color` | 当前不支持这种变量简写。 |
| `sm:-top-1.5rem` | 小程序目标会过滤不支持的响应式变体。 |
## 4. 自定义转义规则
需要自定义 `:`、`[`、`#` 等 class 字符替换时，使用 `customReplaceDictionary`：
```ts
WeappTailwindcss({
unocss: true,
customReplaceDictionary: {
':': '-c-',
},
})
```
这样可以确保 class 转义只有 `customReplaceDictionary` 一个配置入口。
---
## Tailwindcss 2.x
目前，有些用户由于现有的项目，已经是 `webpack 4`, `postcss 7.x` 且无法往上升级，但是又想要使用 `tailwindcss`,
所以写了这个文档作为参考，在现有版本的情况下，**不推荐**任何的新项目使用
## 安装
在这种条件下，只能使用 `tailwindcss 2.x` 版本。
参考 https://v2.tailwindcss.com/docs/installation#post-css-7-compatibility-build 中的安装方式
安装好之后，一定要打开 `jit` 模式, https://github.com/icebreaker-trash/uni-app-vue2-tailwind-hbuilder-template/blob/master/tailwind.config.js
具体更多的细节，详见下方模板代码。
## vue2 hbuilderx 参考模板
注意，一定要在开发环境中设置
```js
process.env.TAILWIND_MODE = "watch"
```
才能正常热更新
模板源代码地址:
https://github.com/icebreaker-template/uni-app-vue2-tailwind-hbuilder-template
---
## 初始化 package.json
## 1. 安装
```bash npm2yarn
# 初始化 package.json
npm init
# 安装包
npm install -D tailwindcss weapp-tailwindcss
```
## 2. 添加 `vite.config.ts`
```ts title="vite.config.ts"
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
uni(),
WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
// Tailwind CSS 入口文件绝对路径
resolve(projectRoot, 'src/app.css'),
],
}),
],
});
```
> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `weapp-tailwindcss` 无法稳定定位 CSS 入口。
## 3. 添加样式
在页面里写一段可观察的工具类，例如 `bg-[#123456] text-[#654321]`，再运行到微信开发者工具检查效果。
## 布局限制
- `uni-app x` 中不要使用 `gap`、`gap-x-*`、`gap-y-*`
- `uni-app x` 中也不要使用 `space-x-*`、`space-y-*`
- 需要间距时，请直接对子项写 `mt-*` / `ml-*`，或封装固定结构的间距组件
## 参考模板
- [uni-app-x-hbuilderx 模板](https://github.com/icebreaker-template/uni-app-x-hbuilderx)
- [uni-app-hbuilderx 模板](https://github.com/icebreaker-template/uni-app-hbuilderx-tailwindcss-v4)
---
## UniappCliStyle
在 `src/app.css` 中引入 Tailwind CSS，这个文件会作为 Tailwind CSS 入口：
```css title="src/app.css"
@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";
```
为了解决 IDE 智能提示问题，需要在 VS Code 里显式告诉 `Tailwind CSS IntelliSense` 哪个文件是 Tailwind 4 的 CSS 入口。最直接的做法是把它指向真实生效的 `src/app.css`：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": "src/app.css"
}
```
如果你更想单独放一个“只给编辑器识别”的文件，也可以额外创建 `src/main.css`：
```css title="src/main.css"
@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";
```
然后把 `experimental.configFile` 指向它：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": "src/main.css"
}
```
这个 `src/main.css` 只用于 IntelliSense，不要在 `App.vue` 里实际引入。应用运行时仍然使用 `src/app.css` 作为 Tailwind CSS 入口。
## `@source` 扫描范围排障
### 问题现象
如果你的 `uni-app` 项目把第三方插件或依赖放在 `src/uni_modules` 下，同时 Tailwind 4 的 CSS 入口又没有显式排除这个目录，那么扫描源码时也可能把依赖里的正则片段、README 示例文本或构建产物误当成候选，最终生成无意义样式。
### 根因
根因是扫描范围过宽，把业务源码以外的第三方内容也纳入了提取范围。
### 推荐配置
对于 `uni-app cli` 项目，推荐在 Tailwind 4 的 CSS 入口里显式排除：
```css title="src/main.css"
@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";
```
### 最佳实践
- `@source` 应尽量只覆盖业务源码目录
- 默认排除 `src/uni_modules`、`node_modules`、`dist`、`unpackage`、文档和生成产物
- 如果必须扫描某个 `uni_modules` 包，只精确包含真正承载模板类名的文件，不要全量扫描整个目录
这里要写 `@import "tailwindcss"`，因为 `tailwindcss-intellisense` 当前用于触发 v4 设计系统加载的判断只认 `@import "tailwindcss"` 或 `@theme {}`，并不认 `@import "weapp-tailwindcss/index.css"`。
:::warning
千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容
所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了
:::
---
## UniappHbuilderStyle
在 `src/app.css` 中引入 Tailwind CSS，这个文件会作为 Tailwind CSS 入口：
```css title="src/app.css"
@import "tailwindcss";
@source not "unpackage";
@source not "uni_modules";
```
为了 IDE 智能提示，需要在 VS Code 里显式告诉 `Tailwind CSS IntelliSense` 哪个文件是 Tailwind 4 的 CSS 入口。最直接的做法是把它指向真实生效的 `src/app.css`：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": "src/app.css"
}
```
如果你更想单独放一个“只给编辑器识别”的文件，也可以额外创建 `src/main.css`：
```css title="src/main.css"
@import "tailwindcss";
@source not "unpackage";
@source not "uni_modules";
```
然后把 `experimental.configFile` 指向它：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": "src/main.css"
}
```
这个 `src/main.css` 只用于 IntelliSense，不要在 `App.vue` / `App.uvue` 里实际引入。应用运行时仍然使用 `src/app.css` 作为 Tailwind CSS 入口。
## `@source` 扫描范围排障
### 问题现象
如果你的 `uni-app` / `uni-app x` 项目把第三方插件或依赖直接放在根目录下的 `uni_modules`，同时 Tailwind 4 的 CSS 入口没有显式排除它，那么 Tailwind 4 也可能把依赖源码、README 示例文本或构建产物误当成候选，最终生成无意义样式。
### 根因
根因仍然是扫描范围过宽。Tailwind 4 会根据 `@source` 收集候选，如果把 `uni_modules` 一并扫进去，就会把第三方目录中的非业务文本也纳入提取范围。
### 推荐配置
对于 `HBuilderX` 工作流，推荐在 Tailwind 4 的 CSS 入口里显式排除：
```css title="src/main.css"
@import "tailwindcss";
@source not "unpackage";
@source not "uni_modules";
```
### 最佳实践
- `@source` 应尽量只覆盖业务源码目录
- 默认排除 `uni_modules`、`node_modules`、`dist`、`unpackage`、文档和生成产物
- 如果必须扫描某个 `uni_modules` 包，只精确包含真正承载模板类名的文件，不要扫描整个目录
这里要写 `@import "tailwindcss"`，因为 `tailwindcss-intellisense` 当前用于触发 v4 设计系统加载的判断只认 `@import "tailwindcss"` 或 `@theme {}`，并不认 `@import "weapp-tailwindcss/index.css"`。
> 添加 `@source not "unpackage";` 是为了避免 `HBuilderX` 差量编译死循环问题；再加上 `@source not "uni_modules";`，则可以避免把第三方依赖源码一并扫进 Tailwind 4 的候选集合。
:::warning
千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容
所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了
:::
---
## Mpx(V4)
:::tip
主线接入文档已合并到 [Mpx](/docs/quick-start/frameworks/mpx)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
## 安装
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
## 配置
更改 `mpx.config.js` 注册 `weapp-tailwindcss`
```js title="mpx.config.js"
const { defineConfig } = require('@vue/cli-service')
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
module.exports = defineConfig({
outputDir: `dist/${process.env.MPX_CURRENT_TARGET_MODE}`,
pluginOptions: {
mpx: {
plugin: {
postcssInlineConfig: {
ignoreConfigFile: true,
plugins: []
},
srcMode: 'wx',
hackResolveBuildDependencies: ({ files, resolveDependencies }) => {
const path = require('path')
const packageJSONPath = path.resolve('package.json')
if (files.has(packageJSONPath)) files.delete(packageJSONPath)
if (resolveDependencies.files.has(packageJSONPath)) {
resolveDependencies.files.delete(packageJSONPath)
}
}
},
loader: {}
}
},
configureWebpack(config) {
// 添加的代码在这里
// highlight-start
config.plugins.push(
new WeappTailwindcss({
appType: 'mpx',
cssOptions: {
rem2rpx: true,
},
cssEntries: [
// Tailwind CSS 入口文件绝对路径
path.resolve(__dirname, './src/app.css'),
],
})
)
// highlight-end
}
})
```
> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。
> Mpx 的 CSS 生成也由 `WeappTailwindcss` 接管，不要再注册 Tailwind PostCSS 生成插件。
> 这里的注册目标也必须是纯 `css` 入口文件，不要把 `tailwindcss@4` 放进 `scss` / `less` / `sass` 入口里，否则样式生成和 `weapp-tailwindcss` 转译都可能失效。
## 添加样式
在 `src/app.css` 中引入 Tailwind CSS：
```css title="src/app.css"
@import "tailwindcss";
@source "../src";
```
> Tailwind CSS 4.x 使用 CSS-first 入口。`@source "../src";` 用于告诉 Tailwind 扫描 Mpx 源码目录。
然后在项目目录下，小程序全局的 `app.mpx` 中，通过 `@import` 引入该文件：
```html title="app.mpx"
```
更改好配置之后，直接启动即可
## 参考模版
https://github.com/icebreaker-template/mpx-tailwindcss-v4
---
## Tailwind CSS 4 旧入口已迁移
`/docs/quick-start/v4` 不再作为快速开始入口，也不再表示 Tailwind CSS 4 是可选或实验性的额外接入方式。当前文档默认使用 Tailwind CSS 4 生成模式；CSS-first、`@source`、`@apply`、`@layer`、IntelliSense 与多端补充说明，已经迁移到 Tailwind 专题下。
请前往 [Tailwind CSS 4 默认模式参考](/docs/tailwindcss/v4-reference)。
如果你是第一次接入项目，请从 [安装依赖](/docs/quick-start/install) 开始，再进入对应框架注册页。
---
## Taro vite
:::tip
主线接入文档已合并到 [Taro](/docs/quick-start/frameworks/taro)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
:::danger
`Taro Vite` 目前不稳定，已知 bug 较多，而且依赖链版本较老，不推荐在新项目里使用。
如果没有强依赖，优先选择 `Taro Webpack`、`uni-app`、`weapp-vite` 等更稳定的方案。
:::
## 安装
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
> `Taro Vite` 里 Tailwind CSS 生成由 `weapp-tailwindcss` 接管，不需要再额外注册 `@tailwindcss/vite` 或 `@tailwindcss/postcss`。
## 配置
```js title="config/index.ts"
import path from 'node:path'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = path.resolve(__dirname, '..')
{
compiler: {
type: 'vite',
vitePlugins: [
WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/app.css'),
],
}),
]
},
}
```
> Tailwind CSS 4 项目应显式配置 `cssEntries`，并使用项目根目录解析出的绝对路径指向纯 `.css` 入口。
> 这里说的是 Tailwind CSS 4：`cssEntries` 请指向纯 `.css` 文件，不要指向 `scss` / `less` / `sass`。业务 Sass/Less 可以继续用，但 Tailwind 4 的 `@import "tailwindcss"` 入口建议单独放在 CSS 文件里。
`cssEntries` 只负责让 `WeappTailwindcss` 稳定读取 Tailwind CSS 入口，入口 CSS 仍然要通过 Taro 入口实际引入。多入口或分包入口请都写进数组：
```js
import path from 'node:path'
const projectRoot = path.resolve(__dirname, '..')
WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/app.css'),
],
})
```
## 添加样式
在项目目录下的 `src/app.css` 中，添加以下内容：
```css title="src/app.css"
@import "tailwindcss" source(none);
@source "../src";
```
> `Taro Vite` 场景同样使用 Tailwind CSS 4 的 CSS-first 入口。小程序目标 CSS 由 `WeappTailwindcss` 输出，不需要把官方 Tailwind Vite 或 PostCSS 插件加入构建。
这里默认 Tailwind 入口在 `src/app.css`。`@source "../src";` 会扫描整个源码目录，页面、组件和你自己新增的业务目录都能覆盖到。
更改好配置之后，直接运行启动项目，微信开发者工具导入这个项目，即可看到效果。
> 再强调一次：这页内容更适合作为历史接入说明与排障参考，不建议把 `Taro Vite` 作为新的默认技术选型。
## 参考模板
https://github.com/icebreaker-template/taro-vite-tailwindcss-v4
---
## Taro webpack
:::tip
主线接入文档已合并到 [Taro](/docs/quick-start/frameworks/taro)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
## 安装
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
## 配置
### 在你的 `app.css` 里面添加
```css
@import "tailwindcss" source(none);
@source "../src";
```
这段默认你的 Tailwind 入口是 `src/app.css`，所以 `../src` 指向整个源码目录。Taro 模板里的页面、组件和后续新增目录都在 `src` 下面，不需要单独写 `pages`、`components`。
### 注册插件
在项目的配置文件 `config/index` 中注册:
```js title="config/index.[jt]s"
import path from 'node:path'
import { WeappTailwindcss } from 'weapp-tailwindcss/webpack'
// 假如你使用 js 配置，则使用下方 require 的写法
// const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
{
// 找到 mini 这个配置
mini: {
// postcss: { /*...*/ },
// 中的 webpackChain, 通常紧挨着 postcss
webpackChain(chain, webpack) {
// 复制这块区域到你的配置代码中 region start
// highlight-start
const projectRoot = path.resolve(__dirname, '..')
chain.merge({
plugin: {
install: {
plugin: WeappTailwindcss,
args: [{
// 这里可以传参数
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/app.css'),
],
}],
},
},
})
// highlight-end
// region end
}
}
}
```
> Tailwind CSS 4 项目应显式配置 `cssEntries`，同时仍要在 `src/app.ts` 或 `src/app.js` 里引入 `./app.css`。
> `weapp-tailwindcss@5` 默认接管 Tailwind CSS 样式生成，不需要再创建 `postcss.config.mjs` 注册 `@tailwindcss/postcss`。如果项目已有 PostCSS 配置，只保留非 Tailwind 的业务插件即可。
多入口、入口不在 `src/app.css` 或有分包独立入口时，把所有纯 `.css` Tailwind 入口都写进 `cssEntries`：
```js
import path from 'node:path'
const projectRoot = path.resolve(__dirname, '..')
args: [{
cssOptions: {
rem2rpx: true,
},
tailwindcssBasedir: projectRoot,
cssEntries: [
path.resolve(projectRoot, 'src/app.css'),
],
}]
```
## 运行
然后执行命令发布到微信小程序
```bash npm2yarn
npm run dev:weapp
```
微信开发者工具导入这个项目，即可看到效果
## 参考模板
https://github.com/icebreaker-template/taro-webpack-tailwindcss-v4
---
## 高阶篇：性能、兼容与团队协作
Tailwind CSS 4 带来了更强大的原生语法，但在小程序环境中仍需平衡兼容性与团队协作。本篇从工程化视角出发，帮助你在真实项目中稳定地落地、优化与维护。
## 1. 处理 `@layer` 与兼容性
小程序运行时目前对 CSS Cascade Layers 支持有限，当你引用第三方组件或自定义样式时可能出现覆盖关系错乱。`weapp-tailwindcss` 内置的 `postcss-preset-env` 可将 `@layer` 转译成传统写法来提升兼容性。
```ts title="vite.config.ts"
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
export default defineConfig({
plugins: [
WeappTailwindcss({
cssEntries: [
/* ... */
],
cssOptions: {
cssPresetEnv: {
stage: 1,
features: {
'cascade-layers': true,
},
},
},
}),
],
})
```
> 如果你只在微信小程序调试，可使用开发者工具的「自定义编译」观察处理前后的差异；若仍存在覆盖问题，可结合传统的 `!important` 或布局拆分策略。
额外提示：
- `cssOptions.cssSelectorReplacement.root` 默认包含 `['page', '.tw-root', 'wx-root-portal-content']`。当页面外的容器（例如自定义 tab bar、弹出层根节点等）需要承载 Tailwind 注入的 `--tw-*` 变量时，只需在容器上加上 `class="tw-root"` 即可复用整套预设，无需额外配置。下面是一个在自定义 tab bar 中注入主题变量的示例：
```xml title="custom-tab-bar/index.mpx"
```
搭配 `cssOptions.cssPreflight` 注入的变量或自定义 `@theme`，可以把 tab bar 的主题色、渐变背景等统一交给 Tailwind 管理。若你需要覆盖其他容器名称，仍可以通过配置把 `cssOptions.cssSelectorReplacement.root` 扩展为更多选择器。
- `cssOptions.cssPresetEnv` 会参与最终构建，请在发布前执行一次 `pnpm build:apps` 或对应的 `pnpm build` 命令确认产物
## 2. 多端共存与按需构建
团队常同时维护小程序与 H5 版本，此时可以通过多个 `@source` 区分模板范围，并结合条件编译实现按需打包：
```css title="src/app.css"
@source "../src/**/*.{vue,wxml}";
@source not "../src/**/*.h5.*"; /* 排除只用于 H5 的模板 */
@import "tailwindcss";
```
当需要拆分体积时，可以把不同业务域的样式写到各自的 `entry.css`，再将路径加入 `cssEntries`：
```ts
WeappTailwindcss({
cssEntries: [
path.resolve(import.meta.dirname, './src/app.css'),
path.resolve(import.meta.dirname, './src/features/order/app.css'),
],
})
```
这样 Tailwind 只会为实际引用的模板生成原子类，避免冗余。
## 3. 产物体积与性能优化
- **控制扫描范围**：`@source` 支持 `not` 语法，排除 `dist`、`node_modules` 等目录能显著加快增量编译
- **合理使用自定义工具类**：把相同组合提炼成 `@utility`，既减少模板体积，也方便统一调整
- **按需开启 `cssOptions.rem2rpx` / `cssOptions.px2rpx`**：在仅小程序端需要 rpx 的情况下，可以在多端构建中动态开启
- **缓存管理**：Tailwind 会在 `.tailwind` 写入缓存。CI 环境可缓存该目录以提升构建速度，发布前若需彻底清理运行 `pnpm exec tailwindcss --config tailwind.config.js --clean` 或直接删除缓存目录
## 4. 调试与质量保障
- **可视化定位**：使用 `outline` 类临时标记组件边界，例如在调试时加上 `outline outline-1 outline-dashed outline-brand/60`
- **断言样式存在**：核心组件可引入快照测试或 DOM 断言，结合 Vitest + @testing-library 验证关键类名
- **lint 约束**：在 `eslint-plugin-tailwindcss` 或团队约定的 lint 规则中，限制自定义类名必须通过 `@utility`
- **回归验证**：Tailwind 升级时执行 `pnpm test`, `pnpm e2e` 确认核心链路稳定，同时在主流机型（尤其是低版本安卓）上真机预览
## 5. 升级与维护策略
1. **版本对齐**：Tailwind 4 迭代频繁，升级前先在 `CHANGELOG` 与 GitHub Release 查 Breaking Change，再在测试分支试跑。
2. **切分 Changeset**：对外发布库时遵循 [Changesets](https://github.com/changesets/changesets) 约定，确保依赖者知道何时需要手动介入。
3. **文档同步**：团队内部记录 `@utility`、`@theme` 的设计规范，推荐把核心样式写进 Storybook 或内部组件示例库。
4. **遇到问题及时回馈**：`weapp-tailwindcss` 社区对 Tailwind 4 的需求反馈快速，遇到兼容问题可通过 Issue 或 PR 参与共建。
至此，你已经掌握了 Tailwind CSS 4 在小程序中的完整落地思路：从环境搭建、组件实践到性能与协同。结合现有的框架集成文档，就能为新成员提供一套体系化的学习路径。
---
## 入门篇：快速认识 Tailwind CSS 4 与 weapp-tailwindcss
Tailwind CSS 4 把配置入口移到 `CSS`：主题变量与自定义工具都可以用原生语法声明。`weapp-tailwindcss` 已经适配这套编译流程。本篇用 30 分钟搭好一套 `tailwindcss@4` + `weapp-tailwindcss` 的基础开发环境，并说明几个必须看懂的配置点。
## 本篇能学到什么
- 搭建一套可运行的 Tailwind CSS 4 + 小程序项目骨架
- 分清核心配置（`@source`、`@reference`、`cssEntries` 等）各自负责的事情
- 理解 v5 生成模式为什么只需要注册 `WeappTailwindcss` 构建器插件
- 掌握验证样式是否生效的最小闭环，避免“写了没生效”的常见坑
如果你还未接触过 `weapp-tailwindcss`，建议先浏览 [安装依赖](/docs/quick-start/install) 和对应框架接入页，了解插件能解决的问题，再回来完成 4.x 的配置。
## 环境准备
| 名称 | 说明 |
| --- | --- |
| Node.js `>=22.12.0` | `weapp-tailwindcss@5.2.0` 起的最低版本，默认支持从 CommonJS 加载 ESM |
| pnpm ≥ 8 | Monorepo 与文档项目统一使用 `pnpm` |
| 小程序框架 | 任选 `weapp-vite`、`uni-app`、`taro` 等，推荐使用现成模板 |
| 代码编辑器 | VS Code 并安装 `Tailwind CSS IntelliSense` 插件 |
初始化项目后，执行一次 `pnpm install` 以及框架 CLI 的初始化命令（如 `pnpm create @tarojs/cli`）。随后即可进入 Tailwind CSS 配置步骤。
## 步骤一：安装依赖
在项目根目录执行：
```bash npm2yarn
npm install -D tailwindcss@latest weapp-tailwindcss
```
> `weapp-tailwindcss@5` 默认启用生成模式，大部分 Vite / Webpack 小程序项目只需要注册 `WeappTailwindcss`。不要再额外注册 `@tailwindcss/vite` 或 `@tailwindcss/postcss`。
通过 HBuilderX 运行 `uni-app` / `uni-app x` 时，还需要 HBuilderX `>=5.11`。
## 步骤二：注册 weapp-tailwindcss 插件
以 `weapp-vite` 为例（不同框架请对照对应的 [默认模式参考](/docs/tailwindcss/v4-reference) 和框架注册页）：
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'weapp-vite/config'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
WeappTailwindcss({
cssEntries: [
resolve(projectRoot, 'src/app.css'),
],
// 常用内置能力：开启 px 自动转换
cssOptions: {
rem2rpx: true,
},
}),
],
})
```
Tailwind CSS 4 项目应显式配置 `cssEntries`。它让 `WeappTailwindcss` 稳定读取入口 CSS 里的 `@import "tailwindcss"`、`@source`、`@config` 与运行时 class 来源，避免不同框架、不同平台的构建图差异导致样式缺失。
`cssEntries` 不是替代 import 的开关。入口 CSS 仍然要通过框架的全局样式入口或业务入口文件被实际引入，否则框架不会生成对应 CSS 资产。多个 Tailwind CSS 入口、分包入口、独立分包入口都要写进同一个 `cssEntries` 数组。
## 步骤三：检查 PostCSS 配置
生成模式下不需要为了 Tailwind CSS 新增 `postcss.config.js`。如果项目已经有 PostCSS 配置，保留业务自己的插件即可；请不要在这里注册 `@tailwindcss/postcss` 或 `tailwindcss`，否则会和 `WeappTailwindcss` 形成两套 Tailwind 生成链路。
## 步骤四：创建入口 CSS
在 `src/app.css` 中写入：
```css title="src/app.css"
@import "tailwindcss";
/* 声明模板扫描路径，确保原子类能被收集 */
@source "../src/**/*.{vue,tsx,jsx,svelte,wxml}";
/* 需要自定义设计令牌时可在此编写 */
@theme {
--color-brand: oklch(67% 0.2 264);
--spacing-safe: clamp(12px, 1.2vw + 8px, 24px);
}
```
`@source` 是 Tailwind 4 的新写法，用于替代旧版本的 `content` 配置。路径请根据项目结构调整。若你需要在局部样式文件使用 `@apply`，在对应文件顶部添加 `@reference "./app.css";`。
## 步骤五：验证类名是否生效
创建一个最小页面（以 `src/pages/index/index.vue` 为例）：
```html title="src/pages/index/index.vue"
Tailwind CSS 4
欢迎来到 weapp-tailwindcss
现在可以尝试修改 bg-brand 或自定义 utility。
```
> `py-safe` 是我们在上文 `@theme` 中声明的自定义变量（通过 `--spacing-safe` 导出），可验证主题自定义是否生效。
运行框架命令（如 `pnpm dev:weapp` 或 `pnpm run build -- --watch`），查看开发者工具中的页面是否渲染出预期样式。如果没有：
- 确认 `@source` 是否包含当前文件扩展名
- 确认入口 CSS 是否被构建器引入，并检查 `cssEntries` 是否指向这些已经被项目引入的入口 CSS
- 若在单文件组件内使用 `@apply`，确保添加了 `@reference`
## 常见下一步
- 阅读 [Tailwind CSS 4 官方文档](https://tailwindcss.com/docs/installation) 了解更多原生指令
- 针对不同框架的集成细节，请查阅「🧪Tailwind CSS @4.x」分类中的各篇文档
- 想理解 `@layer` 在小程序下的降级方案，可继续阅读本教程的 [进阶篇](/docs/quick-start/v4/tutorial/workflow) 与 [高阶篇](/docs/quick-start/v4/tutorial/advanced)
完成本篇后，可以继续看真实组件里的写法，重点关注 `@source`、`@reference` 和小程序目标 CSS 的输出结果。
---
## 进阶篇：用 Tailwind CSS 4 构建真实页面
基础环境搭建完成后，真正的挑战来自“如何把抽象的原子类应用到真实业务”。本篇精选小程序常见的页面模块，结合 `tailwindcss@4` 的新指令，总结出一套从设计拆解到代码落地的流程。
## 工具优先的心智模型
Tailwind CSS 的核心不在于背公式，而是把 UI 拆成「布局」「排版」「状态」三个维度，然后使用类名组合快速拼装。Tailwind 4 进一步引入 `@theme`、`@utility` 等指令，让自定义能力与项目约束保持同步：
- `@theme` 管理设计令牌：颜色、间距、字号、阴影等
- `@utility` 声明可复用的工具类，代替传统的 `.btn { ... }`
- `@variant` / `@custom-variant` 管理状态类（如 `dark:` 与业务属性状态）
掌握这些指令后，就可以在不离开 CSS 语法的前提下扩展 Tailwind。
:::note 小程序交互状态
小程序不支持 CSS `:active`。`weapp-tailwindcss` 默认从小程序样式产物中删除 `active:*` 生成的 selector，但 H5 与 App 的 Web 构建仍会保留。小程序按压反馈应优先使用组件的 `hover-class`。
:::
## 1. 拆解一个卡片组件
以「订单卡片」为例，先在 `src/components/order-card/index.vue` 写出骨架：
```html title="src/components/order-card/index.vue"
{{ createdAt }}
{{ amount }}
```
接下来在 `src/components/order-card/index.css` 中使用 Tailwind 原子类重构：
```css title="src/components/order-card/index.css"
@reference "../../app.css";
/* 使用 @utility 提升可读性 */
@utility order-card {
@apply block rounded-3xl bg-white shadow-lg shadow-slate-200/70 p-5 space-y-4;
}
@utility order-card__header {
@apply flex items-center justify-between gap-3;
}
@utility order-card__title {
@apply text-base font-semibold text-slate-900;
}
@utility order-card__meta {
@apply flex items-center justify-between text-sm text-slate-500;
}
@utility order-card__status {
@apply inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium uppercase tracking-[0.28em];
}
/* 通过 @variant 声明业务状态 */
@custom-variant status-pending (&[data-status="pending"]);
@custom-variant status-finished (&[data-status="finished"]);
@custom-variant status-failed (&[data-status="failed"]);
.order-card__status {
@apply status-pending:bg-amber-100 status-pending:text-amber-600;
@apply status-finished:bg-emerald-100 status-finished:text-emerald-600;
@apply status-failed:bg-rose-100 status-failed:text-rose-600;
}
```
关键点：
- 使用 `@reference` 让局部样式文件继承入口 CSS 中的主题与工具
- `@utility` 让类名语义化，同时还能继续 `@apply` 原子类
- `@custom-variant`（Tailwind 4 新增）能让业务状态转换成语义化前缀
最后在组件实例上应用：
```html title="src/pages/index/index.vue"
自动续费:
```
## 2. 构建可复用的设计令牌
Tailwind 4 把主题抽象为原生 CSS 变量。你可以在 `app.css` 中集中维护令牌，再通过 `@theme` 输出：
```css title="src/app.css" {2-7}
@import "tailwindcss";
@theme {
--color-brand: oklch(66% 0.21 268);
--color-brand-muted: oklch(80% 0.04 268);
--radius-xl: 24px;
--shadow-elevated: 0 18px 40px -20px rgb(99 102 241 / 45%);
}
```
然后在业务样式中直接引用这些变量，或结合 Tailwind 的 `bg-[...]` 写法：
```css
.order-card {
@apply shadow-[var(--shadow-elevated)];
}
.order-card__status {
@apply status-finished:bg-[var(--color-brand-muted)] status-finished:text-[var(--color-brand)];
}
```
得益于 CSS 变量特性，你还可以在不同页面覆写 `:root` 或对应容器的变量，以实现主题切换。
## 3. 管理复杂布局与响应式
小程序虽然没有传统意义上的宽度断点，但我们仍可以借助媒体查询、`min()` / `max()` 等函数实现容错布局：
```css
@layer utilities {
@responsive {
@media (min-width: 560px) {
.md\\:card-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: clamp(16px, 4vw, 36px);
}
}
}
}
```
在页面中配合默认的原子类即可：
```html
```
对于需要横向滚动的卡片，Tailwind 4 提供的 `snap-x`, `snap-mandatory`, `snap-center` 等类仍旧适用，不同端的处理逻辑交给 `weapp-tailwindcss`。
## 4. 多文件协作与团队约定
当项目迎来多人协作时，建议遵循以下约定：
1. **入口 CSS 只做聚合**：集中维护 `@import`、`@source` 与 `@theme`，其余逻辑拆到独立文件。
2. **组件目录内固定 `index.css`**：组件内声明 `@utility`、`@apply`，并写在组件同名文件夹下，便于按需引用。
3. **公共工具抽成包**：例如 `src/styles/utilities/forms.css`，内部声明所有表单相关的 `@utility`。
4. **lint 与提示配置**：确保团队成员的 VS Code `tailwindCSS.experimental.classRegex` 包含 `.wxml`、`.vue` 等模板。
## 5. 调试与性能提示
- Tailwind 4 的编译沿用增量模式，`pnpm run:watch` 时生成的原子类会写入缓存。需要彻底清理时删除 `.tailwind`、`node_modules/.cache/tailwind`。
- 小程序开发者工具不支持 `@layer`，若遇到覆盖问题，可以开启 `cssOptions.cssPresetEnv` 的降级行为，详情见 [高阶篇](/docs/quick-start/v4/tutorial/advanced)。
- 借助 `pnpm dev:h5`（部分框架提供）可快速在浏览器预览，调试完后再回到真机验证。
完成本篇后，你应该可以把 Tailwind 应用到实际业务模块，并形成一套可复用的组件写法。接下来，我们会关注性能优化、跨端适配与团队协作等更高阶的话题。
---
## HBuilderX
:::tip
主线接入文档已合并到 [uni-app HBuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
:::caution
这条 `HBuilderX（uni-app）` 路线对应 `Vue3 + Vite`，属于推荐方案。
如果你已经使用 `HBuilderX` 工作流、插件生态或发布流程，可以直接按本文接入；如果你希望更贴近当前仓库推荐的开发方式，也可以评估 [weapp-vite](/docs/quick-start/v4/weapp-vite)。
:::
---
## uni-app cli vue3 vite(V4)
:::tip
主线接入文档已合并到 [uni-app CLI Vue3 Vite](/docs/quick-start/frameworks/uni-app-vite)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
## 1. 安装
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
## 2. 配置 `vite.config.ts`
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
uni(),
WeappTailwindcss({
cssEntries: [
resolve(projectRoot, 'src/app.css'),
],
cssOptions: {
rem2rpx: true,
},
}),
],
});
```
> Tailwind CSS 4 项目应显式配置 `cssEntries`，并使用项目根目录解析出的绝对路径指向纯 `.css` 入口。
> `cssEntries` 只负责让 `WeappTailwindcss` 稳定读取入口中的 `@source` / `@config` / Tailwind 指令，入口 CSS 仍然要通过 `App.vue`、`main.ts` 或框架全局样式入口实际引入到项目里。
> Tailwind CSS 4 入口建议放在纯 `.css` 文件里，不要直接写进 `scss`、`less` 等预处理样式文件。
## 3. 添加样式
接着直接运行 `npm run dev:mp-weixin`，
微信开发者工具导入这个项目，即可看到效果
## 参考模板
[uni-app-tailwindcss-v4](https://github.com/icebreaker-template/uni-app-tailwindcss-v4)
---
## uni-app cli vue2 webpack(V4)
:::tip
主线接入文档已合并到 [uni-app CLI Vue2 Webpack](/docs/quick-start/frameworks/uni-app)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
:::caution
这条 `uni-app cli vue2 webpack` 路线已经不推荐，仓库中的对应 classic demo 也已经移除。
请优先使用 [uni-app cli vue3 vite](/docs/quick-start/v4/uni-app-vite)。
:::
## 安装
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
## 配置
### 创建 `vue.config.js`
```js title="vue.config.js"
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
/**
* @type {import('@vue/cli-service').ProjectOptions}
*/
const config = {
// some option...
configureWebpack: (config) => {
config.plugins.push(
new WeappTailwindcss({
cssOptions: {
rem2rpx: true,
},
cssEntries: [
// Tailwind CSS 入口文件绝对路径
path.resolve(__dirname, './src/app.css'),
],
})
)
}
// other option...
}
module.exports = config
```
> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。
## PostCSS 配置
`weapp-tailwindcss@5` 默认由 Webpack 插件接管 Tailwind CSS 样式生成，不需要再在 `postcss.config.js` 里注册 `@tailwindcss/postcss`。如果这个存量项目已经有 PostCSS 配置，只保留 `postcss-import`、`autoprefixer`、`@dcloudio/vue-cli-plugin-uni/packages/postcss` 等非 Tailwind 插件即可。
## 添加样式
然后直接运行到小程序，微信开发者工具导入这个项目，即可看到效果
## 说明
本文仅为存量项目迁移和排查保留，不再提供推荐模板。
---
## uni-app x(V4)
:::info 运行环境要求
使用 `weapp-tailwindcss@5.2.0` 或更高版本时，需要 Node.js `>=22.12.0` 和 HBuilderX `>=5.11`。Node.js 22 从 `22.12.0` 开始默认支持从 CommonJS 加载 ESM；较旧的 HBuilderX 内置 Node 可能无法加载当前依赖。
:::
:::tip
主线接入文档已合并到 [uni-app x](/docs/quick-start/frameworks/uni-app-x)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
`weapp-tailwindcss@5` 可以在 HBuilderX 的 uni-app x 项目中接入 Tailwind CSS 4。当前仓库用本地 HBuilderX E2E 覆盖了 Web、微信小程序、Android、iOS、鸿蒙，以及 Web HMR 任意值类名连续新增场景。
:::info 本地验证
HBuilderX、开发者工具和 App 模拟器都依赖开发机环境，所以小程序与 App E2E 只在本地跑，不进入 CI/CD。
```bash npm2yarn
npm run e2e:hbuilderx:local
npm run e2e:hbuilderx:local:web
npm run e2e:hbuilderx:local:mp
npm run e2e:hbuilderx:local:android
npm run e2e:hbuilderx:local:ios
npm run e2e:hbuilderx:local:harmony
```
:::
## 安装
```bash npm2yarn
npm init -y
npm install -D tailwindcss weapp-tailwindcss
```
## 注册插件
uni-app x 要使用 `uniAppX` 预设。Tailwind CSS 4 的入口应放在纯 `.css` 文件里，并通过 `cssEntries` 显式传入绝对路径。
```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { uniAppX } from 'weapp-tailwindcss/presets'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
uni(),
WeappTailwindcss(
uniAppX({
base: projectRoot,
cssEntries: [resolve(projectRoot, 'main.css')],
rem2rpx: true,
}),
),
],
})
```
不要再注册 `@tailwindcss/postcss` 或 `@tailwindcss/vite`。小程序和 App 目标下的 Tailwind 生成、类名转译与单位处理都由 `weapp-tailwindcss` 接管。
:::info Web 与 App 调试注意
`cssEntries` 用来告诉 `weapp-tailwindcss` Tailwind CSS 4 的入口文件，入口仍应是 HBuilderX / Vite 能处理到的真实 CSS 文件。Web/H5、Android 和 iOS 都需要保持 `appType: 'uni-app-x'`，不要因为运行到 Web 端手动关闭 `uniAppX`，否则 `.uvue` 模板里的任意值类名不会转换成安全选择器。
`rem2rpx`、`unitsToPx`、`unitConversion` 是 `uniAppX()` 预设的顶层选项，不要放进 `cssOptions`。
:::
## 添加 CSS 入口
```css title="main.css"
@import "tailwindcss" source(none);
@source "./App.uvue";
@source "./pages/**/*.{uts,uvue}";
@source "./components/**/*.{uts,uvue}";
@source "./stores/**/*.{uts,uvue}";
@source not "./uni_modules/**/*";
@source not "./unpackage/**/*";
```
`@source` 要覆盖页面、组件和可能产出类名的脚本目录。不要把 `unpackage` 放进扫描范围，否则 HBuilderX 产物会反过来干扰开发构建。
## 在 App.uvue 中引入入口
`cssEntries` 不会把 CSS 自动加入 HBuilderX / Vite 模块图，必须在全局样式中实际导入：
```html title="App.uvue"
```
缺少这个导入时，候选扫描仍可能成功，但 Web、小程序和 App 页面不会加载生成样式。
## 验证任意值类名
在任意页面写一段最小用例：
```html
Tailwind CSS 4
```
依次运行到 Web、微信小程序和目标 App 平台后，检查元素样式是否生效。仓库里的 App E2E 也会向页面追加 `bg-[#102938] text-[#f7fbff] w-[173px]`，再检查 HBuilderX 产物里是否出现转译后的类名。
## 布局限制
- `uni-app x` 中不要依赖 `gap`、`gap-x-*`、`gap-y-*`
- `space-x-*`、`space-y-*` 也不要作为跨端间距方案
- 原生 App 端文本使用 ``，文本相关样式要直接写在 `` 上
- 需要跨端稳定的间距时，直接给子项写 `mt-*` / `ml-*`，或封装固定结构的间距组件
## 参考模板
- [仓库内 Tailwind CSS v4 demo](https://github.com/sonofmagic/weapp-tailwindcss/tree/next/demo/uni-app-x-hbuilderx-tailwindcss-v4)
---
## Weapp-vite
:::tip
主线接入文档已合并到 [原生小程序 / weapp-vite](/docs/quick-start/native/install)。本页保留给旧链接和 Tailwind CSS 4 专项排障。
:::
## 安装
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
## 配置
更改 `vite.config.ts` 注册 `weapp-tailwindcss`
```js title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
import { defineConfig } from 'weapp-vite/config'
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
WeappTailwindcss({
cssEntries: [
resolve(projectRoot, 'app.css'),
],
cssOptions: {
rem2rpx: true,
},
}),
],
})
```
`weapp-tailwindcss@5` 默认启用生成模式，不需要再注册 `@tailwindcss/vite` 或 `@tailwindcss/postcss`。如果项目已有 `postcss.config.js`，可以继续保留业务自己的 PostCSS 插件，但请移除 Tailwind 官方生成插件。
Tailwind CSS 4 项目应显式配置 `cssEntries`，让 `WeappTailwindcss` 稳定读取 `app.css` 这类 Tailwind CSS 入口。`cssEntries` 只负责入口识别，入口 CSS 仍然要通过项目入口实际引入。
## 添加样式
在项目目录下，小程序全局的 `app.css` 中，添加以下内容：
```css title="app.css"
@import "tailwindcss";
@source "./src/**/*.{wxml,js,ts,vue}";
@source "./app.{js,ts,json}";
@source not "./dist";
```
更改好配置之后，直接启动即可
---
## Web 直接使用
`weapp-tailwindcss` 可以直接用于纯 Web 项目。它适合小程序、H5/Web 共用同一套 Tailwind CSS 生成链路，或者在普通 Vite Web 项目里验证浏览器原生输出。
## 安装依赖
如果项目已经安装过 `tailwindcss` 和 `weapp-tailwindcss`，可以跳过这一步。
```bash npm2yarn
npm install -D tailwindcss weapp-tailwindcss
```
## 准备 CSS 入口
入口 CSS 仍然要被 Web 项目实际引入。`cssEntries` 只负责让 `weapp-tailwindcss` 稳定读取这个入口里的 `@import "tailwindcss"`、`@source` 与 `@config`，不会替代 Vite 生成 CSS 资产。
```ts title="src/main.ts"
import './style.css'
```
```css title="src/style.css"
@import "tailwindcss";
@source "./**/*.{html,js,ts,jsx,tsx,vue}";
```
## 注册 Vite 插件
纯 Web 项目建议显式配置 `generator.target: 'web'`。这样生成结果会保留浏览器原生 Tailwind CSS 选择器，不会生成小程序转义后的 class。
```ts title="vite.config.ts"
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
const __dirname = path.dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
WeappTailwindcss({
generator: {
target: 'web',
},
cssEntries: [
path.resolve(__dirname, 'src/style.css'),
],
}),
],
})
```
选择这条链路后，不要再同时注册 `@tailwindcss/vite` 或 `@tailwindcss/postcss` 来生成同一份 Tailwind CSS。Taro H5、uni-app H5、Mpx Web、Weapp-vite Web 等多端框架会按环境变量自动切到 `web` 目标；自定义 Web 构建或纯 Vite 项目建议显式配置。更多目标判断规则见 [跨多端开发 CSS 兼容](/docs/multi-platform)。
---
## wxs的转义与处理
:::info
`2.5.2+` 版本中，已经添加了对 `wxs`,`sjs`等视图层运行 `js` 的转义和处理，默认关闭
具体见配置项:
- [`wxsMatcher`](/docs/api/options/matchers#wxsmatcher)
- [`inlineWxs`](/docs/api/options/matchers#inlinewxs)
:::
---
## Tailwind CSS 4 默认模式参考
:::info
当前版本的 `weapp-tailwindcss` 已经默认按 Tailwind CSS 4 生成模式组织配置与文档。本页不是新的快速开始入口，而是补充说明默认模式下仍需要理解的 CSS-first、`@source`、`cssEntries`、`@apply`、`@layer`、IntelliSense 与多端兼容细节。
第一次接入请从 [安装依赖](/docs/quick-start/install) 和对应框架注册页开始；从 v3 或旧 v4 示例迁移时，再回到本页核对需要保留或删除的配置。
:::
本页只维护 Tailwind CSS 4 默认生成模式相关说明；Tailwind CSS 3 或历史实验接入方式请优先参考迁移文档。
## 定位的变化: 样式预处理器
`tailwindcss@4` 存在定位的重大变更
它直接变成了一个样式预处理器，和原生 `css` 已经它的规范相结合，相辅相成。
所以你在 `4.x` 版本中，不应该让 `tailwindcss` 和 `sass`,`less`,`stylus` 一起使用
详见: https://tailwindcss.com/docs/compatibility#sass-less-and-stylus
## 集成选择
`tailwindcss` 集成上提供了多种选择（`cli`、`vite`、`postcss`）。在 `weapp-tailwindcss@5` 的生成模式下，大部分小程序项目不再直接注册这些官方 Tailwind 构建插件，而是只注册 `weapp-tailwindcss` 自己的构建器插件：
1. Vite 项目注册 `weapp-tailwindcss/vite` 的 `WeappTailwindcss`。
2. Webpack 项目注册 `weapp-tailwindcss/webpack` 的 `WeappTailwindcss`。
3. Tailwind CSS 4 由 `WeappTailwindcss` 读取配置并生成目标 CSS。
4. `postcss.config.js` 里不再注册 `@tailwindcss/postcss` 或 `tailwindcss` PostCSS 插件。
这样可以避免同一个构建里同时存在两套 Tailwind 生成链路：官方 Tailwind 插件先生成一次浏览器 CSS，`weapp-tailwindcss` 再尝试二次后处理。生成模式会直接输出小程序目标 CSS，并让模板 / JS 类名转译共享同一份 `classSet`。
Mpx 也使用 `weapp-tailwindcss/webpack` 的 `WeappTailwindcss` 接管 CSS 生成、模板与 JS 转译。不要再为 Tailwind CSS 额外注册 PostCSS 生成插件。
## 小程序样式入口
在 v5 生成模式下，小程序 CSS 入口直接写 `@import "tailwindcss"`，`WeappTailwindcss` 会按默认 `target: 'weapp'` 生成小程序目标 CSS。存量项目里如果还看到 `@import "weapp-tailwindcss/index.css"`，建议迁移为 Tailwind 官方 CSS-first 入口写法。
### 为什么统一写 `@import "tailwindcss"`?
`tailwindcss@4` 的配置、主题变量和扫描范围都从 CSS 入口读取。统一使用 `@import "tailwindcss"` 可以让 Tailwind 官方 IntelliSense、`@source`、`@theme` 和 `WeappTailwindcss` 生成器读取同一份入口。小程序不支持或不适合直接保留的选择器、`@layer` 与浏览器 preflight，会在 `WeappTailwindcss` 输出小程序 CSS 时处理。
### 多端开发
假如你需要进行多端的开发，那么可以使用对应框架的样式条件编译写法，比如 `uni-app`:
`uni-app` / `uni-app x` / `Taro` / `Mpx` / `Weapp-vite` 这类多端或多构建入口项目，建议在 H5/Web 与小程序构建里都保留 `WeappTailwindcss`：插件会按环境变量把 H5/Web 生成器目标切到 `web`，小程序目标继续输出小程序 CSS。两端可以共享同一个包含 `@import "tailwindcss"`、`@theme` 和 `@source` 的 CSS 文件，但不要在同一个多端构建里同时注册两套 Tailwind 生成插件。只有独立 Web 应用不经过小程序构建链路时，才适合继续单独使用 Tailwind 官方 Vite/PostCSS 插件。
详见 https://uniapp.dcloud.net.cn/tutorial/platform.html
## css 作为配置文件
由于在 `tailwindcss@4` 中，配置文件默认为一个 `css` 文件，所以需要让 `weapp-tailwindcss` 能稳定找到你的入口 `css` 文件。
Tailwind CSS 4 项目应显式配置 `cssEntries`，让 `weapp-tailwindcss` 和 `tailwindcss` 保持一致的处理模式。多入口、分包、独立分包、Webpack、Gulp、自定义构建和多平台构建都应该写清楚这些入口，并使用项目根目录解析出的绝对路径。`cssEntries` 只负责入口识别，入口 CSS 仍然要被项目实际 import 或纳入构建图。
> `cssEntries` 为一个数组，就是你写 `@import "tailwindcss";` 的那些 CSS 入口文件，可以有多个。请使用绝对路径。
```ts
{
cssEntries: [
// Tailwind CSS 入口文件
// 比如 tarojs
path.resolve(__dirname, '../src/app.css')
// 比如 uni-app (没有 app.css 需要先创建，然后让 `main` 入口文件引入)
// path.resolve(__dirname, './src/app.css')
],
}
```
不要漏掉 `cssEntries`。一旦构建图拆分、分包 CSS 独立输出或平台产物名变化，缺少显式入口就可能导致 CSS 没生成、JS 字符串 class 已转译但缺少对应样式。
:::warning 只注册到 CSS，不要注册到预处理样式文件
`tailwindcss@4` 的入口请只放在 `.css` 文件里，例如 `app.css`。
不要把 `@import "tailwindcss"` 或对应的 `cssEntries` 指向 `scss`、`less`、`sass` 这类预处理样式文件，否则很容易导致最终样式生成失败，或者 `weapp-tailwindcss` 转译失效。
推荐做法是：
1. 新建一个纯 `css` 入口文件，例如 `src/app.css`
2. 只在这个 `css` 文件里写 `@import "tailwindcss";`
3. 再让业务里的 `scss` / `less` 去间接引用这个 `css`，或者由主入口文件引入它
:::
> 插件会自动根据已安装的 Tailwind 版本开启 v4 模式。只有在调试自定义 `tailwindcss` 目录或多版本共存时，才需要在 `tailwindcss` 配置里手动指定 `version`。
## 使用 @apply
如果你想在 页面或者组件独立的 `CSS` 模块中使用 `@apply` 或 `@variant`，你需要使用 `@reference` 指令，来导入主题变量、自定义工具和自定义变体，以使这些值在该上下文中可用。
```css
/* 到你引入 tailwindcss 的 css 相对路径 */
@reference "../../app.css";
/* 如果你只使用默认主题，没有自定义，你可以直接 reference tailwindcss */
@reference "tailwindcss";
```
详见: https://tailwindcss.com/docs/functions-and-directives#reference-directive
## @layer 在小程序的降级方案
`tailwindcss@4` 使用原生的 `@layer` 去控制样式的优先级
> 如果你不知道什么是 `@layer`，你可以阅读这篇文档 https://developer.mozilla.org/zh-CN/docs/Web/CSS/@layer
但是像 `uni-app` / `taro` 这种框架，默认都是直接引入很多内置样式的。
于是就会出现下方尴尬的情况: 优先级 `(0,1,0)` 的 `class` 选择器样式无法覆盖 `(0,0,1)` 的标签选择器样式:
这种情况，你就非常需要兼容性降级方案，即使用 [`postcss-preset-env`](https://www.npmjs.com/package/postcss-preset-env)（`weapp-tailwindcss` 已经内置了这个插件，可通过 [`cssOptions.cssPresetEnv`](/docs/api/options/important#cssoptions) 配置）。
这在开发需要兼容低版本移动端 h5 的时候很重要。
## 使用 pnpm
默认使用 `pnpm` 的时候，由于 `pnpm` 是无法使用幽灵依赖的
但是 `uni-app`/`taro` 出于一些历史原因，是需要幽灵依赖的，这时候可以在项目下创建 `.npmrc` 添加内容如下
```txt title=".npmrc"
shamefully-hoist=true
```
然后重新执行 `pnpm i` 安装包即可运行
## 智能提示
目前 `tailwindcss@4` 的 VS Code `Tailwind CSS IntelliSense` 插件，会优先从它识别到的 Tailwind 入口里推导配置与候选类名。
在小程序项目里，现在推荐直接写 `@import "tailwindcss";`。这样既符合 Tailwind CSS 4 的 CSS-first 入口，也能让 `WeappTailwindcss` 在生成模式下输出小程序目标 CSS。
相关修复可以关注这个 PR：
- https://github.com/tailwindlabs/tailwindcss-intellisense/pull/1557
根据 `tailwindcss-intellisense` 当前实现，真正生效的做法是显式配置 `tailwindCSS.experimental.configFile`。对于 `tailwindcss@4`，这里传入的不是 `tailwind.config.js`，而是你的 **CSS 入口文件**。
如果项目只有一个入口，直接把它指向实际使用的那个 `app.css` 即可：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": "src/app.css"
}
```
这样配置后，扩展会直接把 `src/app.css` 当成 Tailwind 4 项目入口来加载，恢复补全、悬浮提示和诊断。
如果你的项目有多个 Tailwind 入口，则改用对象写法，把每个 CSS 入口映射到对应的文件范围：
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": {
"packages/a/src/app.css": "packages/a/src/**",
"packages/b/src/app.css": "packages/b/src/**"
}
}
```
如果你仍然想额外创建一个只给编辑器使用的 CSS 文件，也必须把这个文件写进 `tailwindCSS.experimental.configFile`，仅仅在 `App.vue` 里引入它并不会让 IntelliSense 绑定到该入口。
下面是一个编辑器专用入口的可选写法：
```css title="main.css"
@import "tailwindcss";
@source not "dist";
@source not "../src/uni_modules";
```
```json title=".vscode/settings.json"
{
"tailwindCSS.experimental.configFile": "src/main.css"
}
```
这个 `main.css` 只用于 IntelliSense，不需要也不应该在实际应用入口里引入。业务真正生效的入口仍然是你的 `app.css` 里的 `@import "tailwindcss"`。
这里必须使用 `@import "tailwindcss"`，而不是 `@import "weapp-tailwindcss/index.css"` 或 `@import "weapp-tailwindcss/theme.css"`。原因是 `tailwindcss-intellisense` 当前源码里，真正决定是否按 v4 设计系统加载的是 `packages/tailwindcss-language-server/src/util/v4/design-system.ts` 里的 `isMaybeV4()`，它只检查：
- `@import "tailwindcss"`
- `@theme {}`
也就是说：
- `@import "weapp-tailwindcss/index.css"`：不会触发这段 v4 识别
- `@import "weapp-tailwindcss/theme.css"`：同样不会触发
- `@import "tailwindcss"`：可以稳定触发 v4 IntelliSense
如果你的项目不是 `dist` 目录，而是 `unpackage`、`build` 等其他输出目录，请把 `@source not "dist";` 改成自己的实际产物目录。
## `uni-app` / `uni-app x` 项目里的 `@source` 扫描范围排障
### 问题现象
当 `uni-app` 项目把第三方插件或依赖放在 `src/uni_modules` 下，或者 `HBuilderX` / `uni-app x` 项目把依赖放在根目录 `uni_modules` 下时，如果 Tailwind 4 的 CSS 入口没有显式排除这些目录，扫描阶段就可能把依赖源码中的正则片段、README 示例文本或构建产物误识别为候选。
最终表现通常不是业务代码真的写了这些类名，而是产物里平白多出很多无意义样式，增加排查成本。
### 根因
根因是扫描范围过宽，把第三方源码、README 示例文本或构建产物误当成候选。
### 推荐配置
命令行 `uni-app` 项目推荐：
```css
@source not "../src/uni_modules";
```
`HBuilderX` / `uni-app x` 项目推荐：
```css
@source not "uni_modules";
```
同时保留对实际构建产物目录的排除，例如：
```css
@source not "dist";
```
或：
```css
@source not "unpackage";
```
### 最佳实践
- `@source` 应尽量只覆盖业务源码目录
- 默认排除 `uni_modules`、`node_modules`、`dist`、`unpackage`、文档和生成产物
- 如果必须扫描某个 `uni_modules` 包，应只精确包含真正承载模板类名的文件，而不是全量扫描整个目录
> **注意**：从 `tailwindcss-intellisense` 的源码来看，`experimental.configFile` 在 v4 下支持 `string` 和 `object` 两种形式，路径会相对于工作区或 `.code-workspace` 文件解析。关键是“显式声明 CSS 入口”，并且这个入口本身要满足它的 v4 识别条件。
## 如何去除 preflight 样式
使用 `@import "tailwindcss"` 时，`WeappTailwindcss` 会按当前 Tailwind 主版本注入小程序可用的基础 reset。
### 什么是 preflight 样式
一些全局的 `reset` 样式，用来让一些标签行为统一的，比如你在你的样式中，看到的:
```css
view,text,::before,::after,::backdrop {
box-sizing: border-box;
margin: 0;
padding: 0;
border: 0 solid;
}
```
类似这样的就是 `weapp-tailwindcss` 给你的应用注入的 `preflight` 样式
### 解决方案
如果你确认不需要这段基础 reset，可以在 `WeappTailwindcss` 里关闭：
```ts
WeappTailwindcss({
cssOptions: {
cssPreflight: false,
},
})
```
如果只是要覆盖其中一部分声明，可以传入对象覆盖默认值，例如：
```ts
WeappTailwindcss({
cssOptions: {
cssPreflight: {
margin: '0',
padding: '0',
},
},
})
```
## 使用大写单位 (h-[100PX]) 无效问题
默认情况下，在 `process.env.NODE_ENV === 'production'` 的时候，Tailwind CSS v4 会进入优化模式，并可能校准 CSS 单位，例如把大写的 `PX` 转为小写的 `px`。
在当前默认生成模式下，不要为了保留大写单位额外注册 `@tailwindcss/postcss` 或官方 Vite 插件。更稳妥的做法是把业务样式改成小程序推荐的 `rpx` / `px` 写法，并用目标端构建产物确认最终单位符合预期。
---
## weapp-tw CLI 使用指南
`@weapp-tailwindcss/cli` 独立发布 `weapp-tw` 和 `weapp-tailwindcss` 两个等价命令。构建命令默认输出 Web CSS，并对齐当前 Tailwind CSS CLI 的输入、输出、watch、优化和 source map 行为。
注意：npm 上的 `3.x` 与 `4.0.0-alpha.x` 是旧版原生小程序 Gulp 工具链。本 CLI 的新实现从 `5.x` 版本线开始发布；升级时请按本文档配置 CSS 输入，不再使用旧版 `init`、Sass/Less 编译或项目目录扫描流程。
CLI 直接复用 `weapp-tailwindcss` 的 Tailwind v4 generator、design system 与 source graph，不安装或调用 `@tailwindcss/cli`。watch 默认使用 `@parcel/watcher` 原生文件事件；在容器、网络文件系统或需要稳定轮询行为时，可使用 `--poll[=ms]` 切换到轮询模式。
## 安装
```bash
pnpm add -D @weapp-tailwindcss/cli weapp-tailwindcss tailwindcss
```
其中 `@weapp-tailwindcss/cli` 提供命令层，`weapp-tailwindcss` 提供生成和 CSS 转换能力，项目使用的 Tailwind CSS v4 由 `tailwindcss` 提供。
```bash
pnpm exec weapp-tw -i src/input.css -o dist/output.css
pnpm exec weapp-tw build -i src/input.css -o dist/output.css
```
## 构建参数
| 参数 | 简写 | 说明 |
| --- | --- | --- |
| `--input ` | `-i` | 输入 CSS；传 `-` 时读取 stdin。省略时使用 `@import "tailwindcss";`。 |
| `--output ` | `-o` | 输出 CSS；默认或传 `-` 时写入 stdout。 |
| `--watch[=always]` | `-w` | 监听依赖并增量重建；`always` 会在 stdin 关闭后继续监听。 |
| `--poll[=ms]` | | watch 时使用轮询而不是原生 watcher；不传间隔时默认 250ms。 |
| `--minify` | `-m` | 优化并压缩 CSS。 |
| `--optimize` | | 优化 CSS，但不压缩。 |
| `--cwd ` | | 设置输入、输出和依赖解析的工作目录。 |
| `--map[=]` | | 不传路径时内联 source map，传路径时写入独立 map 文件。 |
| `--silent` | | 隐藏非错误构建日志。 |
| `--target web\|weapp` | | 输出目标，默认 `web`。 |
stdin 与 stdout 可以组合使用：
```bash
pnpm exec weapp-tw -i - -o - --minify < src/input.css > dist/output.css
```
监听模式：
```bash
pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch
pnpm exec weapp-tw -i src/input.css -o dist/output.css --watch --poll=100
```
## 小程序 CSS 目标
显式传入 `--target weapp` 后，CLI 会先生成 Tailwind CSS，再调用 `weapp-tailwindcss` 的 CSS 兼容转换链路：
```bash
pnpm exec weapp-tw -i src/input.css -o dist/app.wxss --target weapp
```
:::warning CSS-only 边界
`--target weapp` 只转换 CSS，不扫描或改写 WXML、JS、TS、JSX、TSX。完整小程序项目仍应使用 `weapp-tailwindcss/vite`、Webpack、Rspack 或 Gulp 集成，使模板、脚本和样式共享同一个 `classNameSet` 与构建生命周期。
转换后的 CSS 与 Web CSS 行号不再一一对应，因此 `--target weapp` 不支持 `--map`。
:::
## canonicalize
`canonicalize` 使用 Tailwind design system 合并等价工具类，并输出规范候选：
```bash
pnpm exec weapp-tw canonicalize "py-3 p-1 px-3"
# p-3
printf 'py-3 p-1 px-3\nmt-2 mr-2 mb-2 ml-2\n' \
| pnpm exec weapp-tw canonicalize --stream
```
可通过 `--css ` 加载自定义 theme、plugin 和 config，并通过 `--format text|json|jsonl` 选择输出格式。
## 兼容与辅助命令
| 命令 | 用途 |
| --- | --- |
| `weapp-tw doctor [--json] [--strict]` | 检查项目配置。 |
| `weapp-tw vscode-entry --css ` | 生成 Tailwind IntelliSense 辅助入口。 |
| `weapp-tw patch` / `install` | v5 兼容 no-op；应从 `postinstall` 中移除。 |
| `weapp-tw status [--json]` | 返回 patch 已不再需要的兼容状态。 |
## 常见错误
- 输入与输出解析到同一文件时命令会失败，避免覆盖入口 CSS。
- `--poll` 必须是大于 0 的毫秒数。
- `--map=-` 不表示 inline map；请直接传 `--map`。
- Windows、macOS 与 Linux 均按当前平台的文件系统路径解析，不要在脚本中手动拼接 `/`。
---
## uni-app x 专题
:::info 运行环境要求
使用 `weapp-tailwindcss@5.2.0` 或更高版本时，需要 Node.js `>=22.12.0` 和 HBuilderX `>=5.11`。Node.js 22 从 `22.12.0` 开始默认支持从 CommonJS 加载 ESM；较旧的 HBuilderX 内置 Node 可能无法加载当前依赖。
:::
跨端原子化样式方案
Tailwind CSS × uni-app x
查看已验证 demo（推荐）
或者按步骤手动集成
## 这篇文档适合谁
- 想在 uni-app x 项目里使用 Tailwind CSS 的开发者
- 需要一套能同时覆盖 Web/小程序/Android/iOS/鸿蒙 的原子化样式方案
- 已经使用 HBuilderX 运行或发布 uni-app x 项目
## 当前支持范围
当前文档面向 Tailwind CSS 4。uni-app x 项目建议通过 `WeappTailwindcss(uniAppX(...))` 注册插件，Tailwind 的生成和小程序/App 转译都交给 `weapp-tailwindcss`。
| Tailwind 版本 | 入口方式 | 扫描方式 | 当前验证 |
| --- | --- | --- | --- |
| Tailwind CSS 4 | `@import "tailwindcss" source(none);` | CSS 入口里的 `@source` | HBuilderX Web、微信小程序、Android、iOS、鸿蒙 |
:::info 本地 E2E
HBuilderX 依赖本机安装环境，所以 Web/小程序/App E2E 都在本地运行。仓库里对应的命令是 `pnpm e2e:hbuilderx:local:web`、`pnpm e2e:hbuilderx:local:mp`、`pnpm e2e:hbuilderx:local:android`、`pnpm e2e:hbuilderx:local:ios` 和 `pnpm e2e:hbuilderx:local:harmony`。
:::
## 最快开始
- 想最快跑起来：点击上方「一键使用模板项目」，按 README 步骤打开 HBuilderX 运行即可
- 想了解每一步：前往「手动集成」教程 → 快速集成
## 开发建议
- 推荐编辑器协作：用 VS Code 写代码，用 HBuilderX 负责运行与构建
- 首选 Android 端调试：CSS 兼容度一般是 Web > 小程序 > App（Android/iOS/鸿蒙）。先用 Android 模拟器打通路径，跨端成本最低
- 组件语义注意：原生 App 端文字需放在 `` 标签，且文本样式需要直接作用在该元素上
- 渐进增强：若某些样式在 App 端受限，优先保证 Android 端体验，再按需做条件编译适配小程序/Web
## 布局能力边界
- `uvue` 原生 App 端不支持 `gap`、`gap-x-*`、`gap-y-*`，包括所有 grid gap 与 flex gap 场景
- `space-x-*`、`space-y-*` 在 `uni-app x` 中也不再支持，请不要使用
- 需要稳妥跨端时，优先改为对子项显式写 `mt-*` / `ml-*`，或封装 `Stack` 一类组件统一处理间距
## 为什么推荐先用 Android
1) 原生端样式约束更严格，例如文本必须使用 ``，许多 CSS 特性仍在补齐中
2) 如果你的页面在 Android 端无告警、展示正确，迁移到小程序与 Web 的心智负担会小很多
3) iOS/鸿蒙的调试门槛更高（设备/系统要求），多数团队以 Android 作为优先目标更务实
## 常见问题
### VS Code 对 uvue/uts 的高亮与跳转
安装官方语言服务插件：
- ID: dcloud-ide.hbuilderx-language-services
- 说明: 支持 uni-app x 项目的提示、悬浮、转到定义、查找引用、校验等
- 链接: https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services
### Tailwind CSS 智能提示
VS Code 原生不识别 `uvue/uts`，建议为 Tailwind 扩展加上语言映射。在项目根目录创建 `.vscode/settings.json`：
```json title=".vscode/settings.json"
{
"tailwindCSS.includeLanguages": {
"uvue": "html",
"uts": "javascript"
}
}
```
### 运行方式
uni-app x 的运行和构建仍以 HBuilderX 为准。需要命令行自动化时，可以使用 HBuilderX CLI；本仓库的本地 E2E 就是通过 `hbuilderx launch` 跑 Web、小程序和 App 目标。
## 接下来
- 跟着步骤手动完成集成：快速集成
- 对照当前可运行配置：仓库内 uni-app x + Tailwind CSS 4 demo
---
## 快速集成
:::info 运行环境要求
使用 `weapp-tailwindcss@5.2.0` 或更高版本时，需要 Node.js `>=22.12.0` 和 HBuilderX `>=5.11`。Node.js 22 从 `22.12.0` 开始默认支持从 CommonJS 加载 ESM；较旧的 HBuilderX 内置 Node 可能无法加载当前依赖。
:::
## 最简单：直接用已验证 demo
仓库内 demo 与当前版本一起维护，并提供 HBuilderX Web、微信小程序、Android、iOS 和鸿蒙本地 E2E 用例：
查看已验证 demo
不要使用旧的 `icebreaker-template/uni-app-x-hbuilderx` 作为 Tailwind CSS 4 起点；它仍是 `tailwindcss@3 + weapp-tailwindcss@4` 配置。
---
## 手动集成
下面给出 Tailwind CSS 4 配置，当前文档仅维护 Tailwind CSS 4 接入说明。
### 前置条件
- 已安装 HBuilderX `>=5.11`，并安装 uni-app x 的 Android / iOS 编译插件
- Node.js 满足 `weapp-tailwindcss@5.2.0` 起的要求：`>=22.12.0`
- 本地 App E2E 需要 Android 模拟器或 iOS 模拟器；iOS 还需要完整 Xcode
### 1) 创建项目
在 HBuilderX 中创建新的 `uni-app x` 项目，然后在项目根目录初始化 `package.json`：
```bash npm2yarn
npm init -y
```
### 2) 安装依赖
```bash npm2yarn
npm i -D tailwindcss weapp-tailwindcss
```
### 3) 注册 weapp-tailwindcss
建议显式声明 CSS 入口，指向纯 `.css` 文件：
```ts title="vite.config.ts"
const projectRoot = dirname(fileURLToPath(import.meta.url))
export default defineConfig({
plugins: [
uni(),
WeappTailwindcss(
uniAppX({
base: projectRoot,
cssEntries: [resolve(projectRoot, 'main.css')],
rem2rpx: true,
}),
),
],
})
```
### 4) 配置 Tailwind CSS 入口
Tailwind CSS 4 使用 CSS-first 入口。入口文件应放在项目根目录或源码目录下，并在 `cssEntries` 中使用绝对路径引用：
```css title="main.css"
@import "tailwindcss" source(none);
@source "./App.uvue";
@source "./pages/**/*.{uts,uvue}";
@source "./components/**/*.{uts,uvue}";
@source "./stores/**/*.{uts,uvue}";
@source not "./uni_modules/**/*";
@source not "./unpackage/**/*";
```
### 5) 把入口 CSS 加入 HBuilderX 构建图
`cssEntries` 只告诉 `weapp-tailwindcss` 从哪里生成 Tailwind CSS，不会替代 HBuilderX / Vite 引入样式。在 `App.uvue` 的全局样式中导入入口：
```html title="App.uvue"
```
缺少这一步时，候选类可以被扫描到，但 Web、小程序和 App 页面都不会加载生成后的 CSS。这正是 issue #964 中“构建不报错但所有端样式都没有反应”的核心原因。
### 6) 运行与验证
在 HBuilderX 中依次运行到 Web、微信小程序和计划支持的 App 平台。先用一个任意值类名验证生成和转译是否生效：
```html
Hello Tailwind on uni-app x
```
本仓库的本地验证命令：
```bash npm2yarn
npm run e2e:hbuilderx:local
pnpm e2e:hbuilderx:local:web
pnpm e2e:hbuilderx:local:mp
pnpm e2e:hbuilderx:local:app
pnpm e2e:hbuilderx:local:android
pnpm e2e:hbuilderx:local:ios
pnpm e2e:hbuilderx:local:harmony
```
这些命令依赖本机 HBuilderX、模拟器和 Xcode，不放进 CI/CD。
### 7) 编辑器智能提示
VS Code 默认不认识 `uvue` / `uts`。可以给 Tailwind 扩展加语言映射：
```json title=".vscode/settings.json"
{
"tailwindCSS.includeLanguages": {
"uvue": "html",
"uts": "javascript"
}
}
```
同时安装 DCloud 的语言服务插件：`dcloud-ide.hbuilderx-language-services`。
---
## 重要限制
- 原生 App 端文本需要放在 `` 元素里，文本样式也要直接作用在 `` 上
- `uvue` 原生 App 端不支持 `gap`、`gap-x-*`、`gap-y-*`
- `space-x-*`、`space-y-*` 在 `uni-app x` 中也不要作为布局方案
- 跨端间距建议直接对子项写 `mt-*` / `ml-*`，或者封装固定结构的间距组件
- HBuilderX 控制台出现 CSS 兼容警告时，优先按目标平台限制调整样式