# 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 的子代理 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 沙箱 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 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 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 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 pnpm dev ``` ### 构建 ```bash pnpm build ``` ### 测试 ```bash pnpm 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 服务端 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 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（技能系统） ## 概述 **Skill** 是 Claude Code CLI 的**插件/技能系统**，允许开发者扩展 AI 助手的能力。每个 Skill 是一个独立的 npm 包，可以添加特定的功能、工作流或集成。 > **相关概念**：MCP 是协议，Skill 是实现。 > **插件市场**：[https://claude-plugins.dev](https://claude-plugins.dev) --- ## 核心概念 ### 1. Skill 的定义 **Skill** 是 Claude Code 的功能扩展单元： - 打包为 npm 包 - 包含特定的工具、工作流或代理 - 通过 `claude-plugins install` 安装 - 可与 Claude Code 深度集成 ### 2. Skill 与 MCP 的关系 ``` ┌─────────────────────────────────────────────────────────┐ │ Claude Code 扩展体系 │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Skill 系统 │ │ │ │ ├── 高级封装（工作流、代理、专业功能） │ │ │ │ ├── npm 包分发 │ │ │ │ ├── 配置驱动 │ │ │ │ └── 示例：PR Review Toolkit, Python Workflow │ │ │ └───────────────────────────────────────────────────┘ │ │ ▲ │ │ │ 可能使用 │ │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ MCP 协议 │ │ │ │ ├── 底层协议 │ │ │ │ ├── 标准化数据传输 │ │ │ │ ├── 语言无关 │ │ │ │ └── 示例：Filesystem Server, GitHub Server │ │ │ └───────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ ``` --- ## Skill 的类型 ### 1. 工作流类 (Workflows) 提供特定开发场景的完整工作流： | Skill | 功能 | 安装命令 | | ----- | ---- | -------- | | **Python Development** | Python 3.12+、Django、FastAPI | `npx claude-plugins install @wshobson/claude-code-workflows/python-development` | | **JavaScript/TypeScript** | ES6+、Node.js、React | `npx claude-plugins install @wshobson/claude-code-workflows/javascript-typescript` | | **Backend Development** | API 设计、GraphQL | `npx claude-plugins install @wshobson/claude-code-workflows/backend-development` | | **Code Refactoring** | 代码清理、重构 | `npx claude-plugins install @wshobson/claude-code-workflows/code-refactoring` | | **Developer Essentials** | Git、SQL、测试 | `npx claude-plugins install @wshobson/claude-code-workflows/developer-essentials` | ### 2. 工具包类 (Toolkits) 提供特定的工具集： | Skill | 功能 | 安装命令 | | ----- | ---- | -------- | | **PR Review Toolkit** | 自动化代码审查 | `npx claude-plugins install @anthropics/claude-code-plugins/pr-review-toolkit` | | **Document Skills** | Excel、Word、PDF 处理 | `npx claude-plugins install @anthropics/anthropic-agent-skills/document-skills` | ### 3. 综合类 (Comprehensive) 提供完整的企业级功能： | Skill | 功能 | 安装命令 | | ----- | ---- | -------- | | **Claude Flow** | 150+ 命令、74+ 代理 | `npx claude-plugins install @ruvnet/claude-flow-marketplace/claude-flow` | | **Frontend Excellence** | React 19、Next.js 15 | `npx claude-plugins install @dotclaude/dotclaude-plugins/frontend-excellence` | --- ## 使用 Skill ### 1. 安装 Skill ```bash # 基本安装 npx claude-plugins install # 安装 Python 开发工作流 npx claude-plugins install @wshobson/claude-code-workflows/python-development # 安装 PR 审查工具包 npx claude-plugins install @anthropics/claude-code-plugins/pr-review-toolkit ``` ### 2. 列出已安装的 Skill ```bash npx claude-plugins list ``` ### 3. 卸载 Skill ```bash npx claude-plugins uninstall ``` ### 4. 更新 Skill ```bash npx claude-plugins update ``` --- ## 创建自定义 Skill ### 项目结构 ``` my-custom-skill/ ├── package.json ├── README.md ├── src/ │ ├── index.ts # 入口文件 │ ├── tools/ # 工具定义 │ ├── agents/ # 代理定义 │ └── workflows/ # 工作流定义 └── dist/ # 编译输出 ``` ### package.json ```json { "name": "@myorg/my-custom-skill", "version": "1.0.0", "description": "My custom Claude Code skill", "main": "dist/index.js", "types": "dist/index.d.ts", "keywords": [ "claude-code", "claude-plugin", "skill" ], "peerDependencies": { "@anthropic-ai/claude-code": "*" } } ``` ### 入口文件 (index.ts) ```typescript export default defineSkill({ id: 'my-custom-skill', name: 'My Custom Skill', description: 'A custom skill for my needs', // 定义工具 tools: [ { name: 'my-tool', description: 'Does something useful', parameters: { type: 'object', properties: { input: { type: 'string' } } }, handler: async (params) => { return `Processed: ${params.input}`; } } ], // 定义代理 agents: [ { name: 'my-agent', description: 'Handles specific tasks', handler: async (context) => { // 代理逻辑 } } ] }); ``` ### 发布到 npm ```bash # 构建 npm run build # 发布 npm publish ``` --- ## Skill 配置 ### 配置文件位置 Claude Code 读取以下位置的配置： ``` ~/.claude-code/ ├── skills.json # 已安装的技能列表 ├── skills.config.json # 技能配置 └── skills/ # 本地技能目录 ``` ### skills.config.json 示例 ```json { "enabledSkills": [ "@wshobson/claude-code-workflows/python-development", "@anthropics/claude-code-plugins/pr-review-toolkit" ], "skillSettings": { "@wshobson/claude-code-workflows/python-development": { "pythonVersion": "3.12", "framework": "fastapi" } } } ``` --- ## 热门 Skill 推荐 ### 1. PR Review Toolkit **功能**： - 自动化代码审查 - 测试覆盖率检查 - 错误处理验证 - 类型安全审查 - 代码质量评估 **适用**：团队协作、代码质量保证 ### 2. Python Development Workflow **功能**： - Python 3.12+ 最佳实践 - Django/FastAPI 项目模板 - 异步编程模式 - 类型提示支持 **适用**：Python 开发者 ### 3. JavaScript/TypeScript Workflow **功能**： - ES6+ 语法 - Node.js 开发 - React/Vue 框架 - 现代 Web 工具链 **适用**：前端/全栈开发者 ### 4. Claude Flow **功能**： - 150+ 专业命令 - 74+ 专业代理 - GitHub 集成 - 企业级工作流 **适用**：企业团队 --- ## Skill 与 MCP 的选择 | 场景 | 推荐方案 | 原因 | | ---- | -------- | ---- | | **标准化数据访问** | MCP | 跨平台兼容，协议标准 | | **专业工作流** | Skill | 高级封装，开箱即用 | | **自定义工具** | MCP | 灵活控制底层逻辑 | | **团队协作** | Skill | 配置共享，版本管理 | | **快速集成** | Skill | npm 安装，即插即用 | --- ## 参考资源 ### 官方资源 - [Claude Code 插件文档](https://docs.anthropic.com/claude-code/plugins) - [Claude Plugins 市场](https://claude-plugins.dev) ### 社区资源 - [Python Development Workflow](https://github.com/wshobson/claude-code-workflows) - [PR Review Toolkit](https://github.com/anthropics/claude-code-plugins) - [Claude Flow](https://github.com/ruvnet/claude-flow-marketplace) --- **文档更新时间：2025 年 12 月** --- ## 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 # GPT-4 编码器 encoding = tiktoken.encoding_for_model("gpt-4") text = "Hello, world!" tokens = encoding.encode(text) print(f"Token 数量: {len(tokens)}") ``` #### Anthropic Tokenizer ```python 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, 和网站！ ## 如何参与贡献 ### 前置环境 1. `nodejs@22` 2. `pnpm@10` 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` 中，所采集的类名，以及生成的结果，转化成小程序中可以接受的方式。 ::: ## Why `weapp-tailwindcss`? - ✅ 自动处理所有文件：以微信小程序为例，不但可以处理和转义 `wxml` / `wxss`，还能处理 `js` 和 `wxs` 产物 - ✅ 支持最原生的小程序开发，也支持许多框架如 `taro` , `uni-app` , `mpx` , `rax` 等等.. - ✅ 提供多种使用方式，方便项目集成：包括 `webpack` / `vite` / `gulp` 插件和直接的 `nodejs api` - ✅ 生态好，解决方案丰富，提供大量现成模板，可以利用许多 `tailwindcss` 现有的生态来构建小程序。 - ✅ 高效的解析和缓存机制，热更新响应时间快 - ✅ 贴合 `tailwindcss` 的设计思路，智能提示友好 ## 快速开始 :rocket: ### 🔥 Tailwind CSS @3.x `weapp-tailwindcss` 主要提供了 `3` 种使用方式: #### 👉 [1. 框架类( `taro` , `uni-app` , `mpx` )小程序开发的快速开始](/docs/quick-start/install) #### 👉 [2. 原生小程序开发的快速开始](/docs/quick-start/native/install) #### 👉 [3. 可直接使用的各个框架的小程序模板](/docs/community/templates) ### 🧪 Tailwind CSS @4.x #### 👉 [Tailwindcss@4.x 快速开始](/docs/quick-start/v4) ## 演示视频 ## 另外特别感谢 [舜岳同学](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` 元个人资质费用，已无法搜索），进入小程序即可，小程序码： ![tailwind](./frameworks/img/tailwind-mp-qrcode.jpg) 实现源代码详见: [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 (或 px) 在 [rem 转 rpx (或 px)](/docs/quick-start/rem2rpx) 章节，我们做了 `CSS` 中 `rem` 转化成 `px` / `rpx` 的方式。 但是除了 [rem 转 rpx (或 px)](/docs/quick-start/rem2rpx)，我们可能也有 `px 转 rpx` 的需求，这种情况实际上也很容易就能做到。 ## px 转 rpx ### 4.3.0 以后 从 `weapp-tailwindcss@4.3.0` 开始，我们内置了 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 插件，提供了开箱即用的 `px` 转 `rpx` 的方式。 只需传入配置项: ```js // vite UnifiedViteWeappTailwindcssPlugin({ // ...other-options px2rpx: true }) // webpack const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') new UnifiedWebpackPluginV5({ // ...other-options px2rpx: true }) ``` 只需传入一个 `true`，你写的所有的 `px` 都会被 `1:1` 的转换成 `rpx`，比如 `10px` -> `10rpx` 当然这个选项也可以传入一个 `object`, 这个默认值和参数，可以参考 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 插件。 ### 4.3.0 以前 这里我们使用 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 这个 `postcss` 插件来做。 > [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 由京东团队出品，应该是目前质量最高的 `px` 转 `rpx` 插件，而且已经被内置在了 `tarojs` 框架内 #### 安装插件 ```bash npm2yarn npm i -D postcss-pxtransform ``` #### 注册到 postcss 配置中 ```js title="postcss.config.js" module.exports = { plugins: { 'tailwindcss': {}, 'autoprefixer': {}, // highlight-start // 下方为 px 转 rpx 区域 'postcss-pxtransform': { platform: 'weapp', // 根据你的设计稿宽度进行配置 // 可以传入一个 function // designWidth (input) { // if (input.file.replace(/\\+/g, '/').indexOf('@nutui/nutui-taro') > -1) { // return 375 // } // return 750 // }, designWidth: 750, // 可以设置为 375 等等来应用下方的规则, deviceRatio: { 640: 2.34 / 2, // 此时应用到的规则，代表 1px = 1rpx 750: 1, 828: 1.81 / 2, // 假如你把 designWidth 设置成 375 则使用这条规则 1px = 2rpx 375: 2 / 1, }, }, // highlight-end }, } ``` 这样就能进行转化了，此时假如你写 `w-[20px]` 这种 `class` 它最终生效的样式会经过 `postcss-pxtransform` 转化，转变为 `width: 20rpx`, 当然这取决于你传入插件的配置，比如设计稿宽度 (`designWidth`) 你可以在 [taro 官网的设计稿及尺寸单位章节内](https://docs.taro.zone/docs/size) 查看这个插件的所有用法。 另外，假如你要禁止单个文件 `px` 转 `rpx`，可以在样式表文件内头部，添加 `/*postcss-pxtransform disable*/` 这样的注视，禁用该文件 `px` 转 `rpx`。 --- ## Nodejs API > 版本 2.11.0+ , 此为高阶 `api`，使用起来有难度，不适合新手，假如你不清楚你在做什么，请使用 `webpack/vite/gulp` 插件 有时候,我们不一定会使用 `webpack/vite/gulp`，可能是直接使用 `nodejs` 去构建应用，或者封装更高阶的工具，这时候可以使用`api`去转义你的应用。 ## 如何使用 ```js // mjs or // cjs const { createContext } = require('weapp-tailwindcss/core') async function main(){ // createContext 可传入参数，类型为 UserDefinedOptions const ctx = createContext() // 3.1.0 开始 api 都是异步的，为 rust 工具链做准备 const wxssCode = await ctx.transformWxss(rawWxssCode) const wxmlCode = await ctx.transformWxml(rawWxmlCode) const jsCode = await ctx.transformJs(rawJsCode) // 传入参数和输出结果均为 字符串 string // 然后你就可以根据结果去复写你的文件了 } main() ``` :::tip 有一点要特别注意，在使用 `ctx.transformJs` 的时候，一定要确保 `tailwindcss` 已经执行完毕了！也就是说对应的 `postcss` 执行完毕。 因为 `js` 的转义依赖 `tailwindcss` 的执行结果，然后根据它，再去从你的代码中找到 `tailwindcss` 提取出的字符串，再进行处理的。 假如此时 `tailwindcss` 还没有执行，则插件就只能获取到一个 **空的** 提取字符串集合，这就无法进行匹配，从而导致你写在 `js` 里的类名转义失效。 比如这种情况: ```js // index.js const classNames = ['mb-[1.5rem]'] ``` 另外使用此种方式，编译缓存需要自行处理，且暂时没有类名的压缩与混淆功能 ::: --- ## uni-app HbuilderX 使用方式 ## 默认使用方式 > 配置会稍微复杂一些，这里推荐直接使用或者参考模板: [uni-app-vue3-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template) 或者 [若依移动端 (Gitee 地址)](https://gitee.com/sonofmagic/RuoYi-App) ### tailwind.config.js 注意: 在使用 `hbuilderx` 进行开发时，由于目录结构和启动项的不同，你必须要给你 `tailwind.config.js` 传入**绝对路径**: ```js title="tailwind.config.js" const path = require("path"); const resolve = (p) => { return path.resolve(__dirname, p); }; /** @type {import('tailwindcss').Config} */ module.exports = { // 注意此处，一定要 `path.resolve` 一下, 传入绝对路径 // 你要有其他目录，比如 components，也必须在这里，添加一下 content: ["./index.html", "./pages/**/*.{html,js,ts,jsx,tsx,vue}"].map(resolve), // ... corePlugins: { // 跨多端可以 h5 开启，小程序关闭 preflight: false, }, }; ``` ### vite.config.[tj]s 另外使用 `vite.config.[tj]s` 中注册 `tailwindcss` 时，也要传入绝对路径: ```js title="vite.config.[tj]s" // 注意： 打包成 h5 和 app 都不需要开启插件配置 const isH5 = process.env.UNI_PLATFORM === "h5"; const isApp = process.env.UNI_PLATFORM === "app"; const WeappTailwindcssDisabled = isH5 || isApp; const resolve = (p) => { return path.resolve(__dirname, p); }; export default defineConfig({ plugins: [ uni(), uvwt({ rem2rpx: true, disabled: WeappTailwindcssDisabled, // 由于 hbuilderx 会改变 process.cwd 所以这里必须传入当前目录的绝对路径 tailwindcssBasedir: __dirname }) ], css: { postcss: { plugins: [ require("tailwindcss")({ // 注意此处，手动传入你 `tailwind.config.js` 的绝对路径 config: resolve("./tailwind.config.js"), }), require("autoprefixer"), ], }, }, }); ``` `hbuilderx` 正式版本的 `vue2` 项目,由于使用 `webpack4` 和 `postcss7`，所以只能使用本插件的 `weapp-tailwindcss/webpack4` 版本， 详见[uni-app-vue2-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-hbuilder-template) 或者下方也有一种 `Hack hbuilderx vue2 Way` 来在 `hbuilderx` `vue2` 项目中，使用 `webpack5` 和 `postcss8` ## Hbuilderx 与 uni-app cli 环境汇总 首先，你需要知道你的项目究竟使用的是什么打包工具，截止今天 `2023/12/18` 目前如下所示: | | 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 | 也就是说，目前 `hbuilderx vue2` 的项目是最老的，无法使用最新版本的 `tailwindcss`，其他都可以使用。 ## hbuilderx vue2 webpack4 postcss7 版本模板 如果你实在必须在 `hbuilderx vue2` 的项目中使用 `tailwindcss`，那么你可以使用下面的方法来使用 `tailwindcss` 详见 [uni-app-vue2-tailwind-hbuilder-template](https://github.com/icebreaker-trash/uni-app-vue2-tailwind-hbuilder-template) ## Hack hbuilderx vue2 Way :::caution 以下方式为全局 Hack, 可能会在 `hbuilderx` 升级后出现问题 ::: `hbuilderx` 和 `hbuilderx alpha` 新建的 `vue2` 项目，发现它们的 `webpack` 版本被锁死在了 **`4`** ，我又用 `cli` 创建了一个 `vue2` 项目，发现已经是 `webpack5` 了，看起来只有 `cli` 创建的项目，会被默认升级 `webpack5`。 当然这并不意味着 `hbuilderx` 创建的 `vue2` 项目无法使用最新的这个插件，我们可以强行升级 `HBuilderX/plugins/uniapp-cli` 中的依赖，使得它适配 `webpack5` > Macos uniapp-cli 路径在 /Applications/HBuilderX.app/Contents/HBuilderX/plugins/uniapp-cli > > Windows 的路径应该也在类似的地方，记得要先下载 vue2 的编译器，这个文件夹才有 来到 `uniapp-cli` 这个项目路径，执行 `yarn upgradeInteractive --latest` 升级项目依赖，重点升级 `@vue/cli-*` 相关包到 `5` 这时候 `webpack` 已经被升级到 `5` 版本了，然后你升级其他的 `loader` 到适配 `webpack5` 的版本(通常是最新版本) 再安装 `postcss` 和 `postcss-loader` 的最新版本，这时候你就把整个 `uni-app vue2` 项目的 `hbuilderx` 内置 `cli` 从 `webpack4`,`postcss7`变为了 `webpack5`,`postcss8` 了 不过代价是什么呢？那就是，这项改动是全局的！ 你要想恢复设置，那只有重新安装 `uni-app vue2` 编译插件，或者重新安装整个 `hbuilderx`，所以这里还是推荐使用 `cli` 方式去创建项目，保证一个项目一个编译模式，你要节省空间就用 `pnpm`, 想用什么版本编译就用什么版本。 ## 视频演示 --- ## mpx (原生增强) 在 `vue.config.js` 中注册： ```js title="vue.config.js" const { defineConfig } = require('@vue/cli-service') const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') module.exports = defineConfig({ // other options configureWebpack(config) { config.plugins.push( new UnifiedWebpackPluginV5({ rem2rpx: true, }) ) } }) ``` ## 引入 Tailwind CSS 样式 Tailwind 的底层样式需要显式导入。不同主版本的包结构略有差异： ### Tailwind CSS v3.x 仍然可以直接引用 Tailwind 提供的底层样式文件（带 `.css` 扩展名）： ```html title="src/app.mpx" ``` ### Tailwind CSS v4.x v4 官方改用了全新的 CSS 包结构，推荐直接引入 `weapp-tailwindcss` 提供的聚合样式文件： ```html title="src/app.mpx" ``` 这样即可获得预置的 base / components / utilities，同时避免 `postcss-import` 误解析到 JS 入口导致构建报错。 ## mpx 中的 vscode tailwindcss 智能提示缺失设置 我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。 假如你遇到了，在 `vscode` 的 `mpx` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。 这里我们以 `vscode` 为例: 接着找到 `Tailwind CSS IntelliSense` 的 `扩展设置` 在 `include languages`,手动标记 `mpx` 的类型为 `html` ![如图所示](./img/vscode-tailwindcss.png) 保存设置，再去`mpx`文件里写`class`的时候，智能提示就出来啦。 --- ## 原生开发(打包方案) :::warning 注意！这是原生开发(**打包方案**)，假如你需要纯原生方案，请查看 [快速开始(纯原生)](/docs/quick-start/native/install) ::: > 由于原生小程序没有 `webpack/vite/gulp` 工具链暴露出来，所以我们要添加这一套机制，来整个前端社区接轨，以此来实现更强大的功能。 :::tip 给原生小程序加入编译时这块 `webpack/vite/gulp` 等等工具，思路都是一样的，然而实现起来比较复杂，损耗精力，在此不提及原理。 更改模板工具链流程前，请确保你比较熟悉工具链开发（到我这样的水平就差不多了）。 另外这些模板，只需要稍微改一下产物后缀，添加 `tailwind.config.js` 的 `content` 就可以适配百度，头条，京东...各个平台。 ::: ## gulp 模板 模板项目 [weapp-tailwindcss-gulp-template(gulp打包)](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/tree/main/demo/gulp-app) ## webpack5 模板 模板项目 [weapp-native-mina-tailwindcss-template(webpack打包)](https://github.com/sonofmagic/weapp-native-mina-tailwindcss-template) ## 组件样式的隔离性 :::tip 发现很多用户，在使用原生开发的时候，经常会问，为什么样式不生效。 这可能有以下几个原因: 1. 代码文件不在 `tailwind.config.js` 的 `content` 配置内 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` ![如图所示](./img/vscode-setting.png) 智能提示就出来了: ![智能提示](./img/wxml-i.png) --- ## Rax (react) 在根目录下创建一个 `build.plugin.js` 文件，然后在 `build.json` 中注册： ```json title="build.json" { "plugins": [ "./build.plugin.js" ], } ``` 回到 `build.plugin.js` ```js title="build.plugin.js" const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') module.exports = ({ context, onGetWebpackConfig }) => { onGetWebpackConfig((config) => { config.plugin('UnifiedWebpackPluginV5').use(UnifiedWebpackPluginV5, [ { rem2rpx: true, }, ]); }); }; ``` --- ## Taro (所有框架) 目前 Taro v4 同时支持了 `Webpack` 和 `Vite` 进行打包编译，`weapp-tailwindcss` 这 `2` 者都支持，但是配置有些许的不同 :::caution 假如你写了 `tailwindcss` 工具类不生效，可能是由于微信开发者工具默认开启了 `代码自动热重载` 功能，关闭它即可生效。 假如你和 `NutUI` 一起使用，或者启用了 `@tarojs/plugin-html` 插件，请一定要查看这个[注意事项](/docs/issues/use-with-nutui)! ::: 下列配置同时支持 `taro` 的 `react` / `preact` / `vue2` / `vue3` 所有框架 ## 使用 Webpack 作为打包工具 ### 注册插件 在项目的配置文件 `config/index` 中注册: ```js title="config/index.[jt]s" const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') // 假如你使用 ts 配置，则使用下方 import 的写法 // import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss/webpack' { // 找到 mini 这个配置 mini: { // postcss: { /*...*/ }, // 中的 webpackChain, 通常紧挨着 postcss webpackChain(chain, webpack) { // 复制这块区域到你的配置代码中 region start // highlight-start chain.merge({ plugin: { install: { plugin: UnifiedWebpackPluginV5, args: [{ // 这里可以传参数 rem2rpx: true, }] } } }) // highlight-end // region end } } } ``` 然后正常运行项目即可，相关的配置可以参考模板 [taro-react-tailwind-vscode-template](https://github.com/sonofmagic/taro-react-tailwind-vscode-template) :::info `weapp-tailwindcss/webpack` 对应的插件 `UnifiedWebpackPluginV5` 对应 `webpack@5` `weapp-tailwindcss/webpack4` 对应的插件 `UnifiedWebpackPluginV4` 对应 `webpack@4` 在使用 `Taro` 时，检查一下 `config/index` 文件的配置项 `compiler`，来确认你的 `webpack` 版本，推荐使用 `'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` 功能老是出错，最近更新之后，由于 `prebundle` 默认开启，有时候连 `taro cli` 初始化的模板项目都跑不起来，假如遇到问题找不到原因，可以尝试关闭这个配置。 ::: ## 使用 Vite 作为打包工具 由于 `taro@4` 的 `vite` 版本，目前加载 `postcss.config.js` 配置是失效的，所以我们目前暂时只能使用内联 `postcss` 插件的写法 ### 在 `config/index.ts` 中注册插件 ```ts title="config/index.[jt]s" const baseConfig: UserConfigExport<'vite'> = { // ... 其他配置 // highlight-start compiler: { type: 'vite', vitePlugins: [ { // 通过 vite 插件加载 postcss, name: 'postcss-config-loader-plugin', config(config) { // 加载 tailwindcss if (typeof config.css?.postcss === 'object') { config.css?.postcss.plugins?.unshift(tailwindcss()) } }, }, uvtw({ // rem转rpx rem2rpx: true, // 除了小程序这些，其他平台都 disable disabled: process.env.TARO_ENV === 'h5' || process.env.TARO_ENV === 'harmony' || process.env.TARO_ENV === 'rn', // 由于 taro vite 默认会移除所有的 tailwindcss css 变量，所以一定要开启这个配置，进行css 变量的重新注入 injectAdditionalCssVarScope: true, }) ] as Plugin[] // 从 vite 引入 type, 为了智能提示 }, // highlight-end // ... 其他配置 } ``` `tailwindcss` 即可注册成功，正常使用了 这段代码的意思为，在 `vite` 里注册 `postcss` 插件和 `vite` 插件 > `vite.config.ts` 只有在运行小程序的时候才会加载，`h5` 不会，所以只能通过这种方式进行 `小程序` + `h5` 双端兼容 ## 视频演示 --- ## uni-app cli vue3 vite :::warning 这是 `uni-app cli` 创建的项目的注册方式，如果你使用 `HbuilderX`，应该查看 [uni-app HbuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx) ::: ## 注册插件 创建完成后，快速上手中的准备工作都完成之后，就可以便捷的注册了： ```js title="vite.config.[jt]s" export default defineConfig({ // uni 是 uni-app 官方插件， uvtw 一定要放在 uni 后，对生成文件进行处理 plugins: [uni(),uvwt()], css: { postcss: { plugins: [ // require('tailwindcss')() 和 require('tailwindcss') 等价的，表示什么参数都不传，如果你想传入参数 // require('tailwindcss')({} <- 这个是postcss插件参数) require('tailwindcss'), require('autoprefixer') ], }, }, }); ``` 这里只列举了插件的注册，包括`postcss`配置完整的注册方式，参考配置项文件链接: ## 创建项目参考 `uni-app vite` 版本是 `uni-app` 最新的升级，它使用 `vue3` 的语法。 你可以通过 `cli` 命令创建项目 ([参考官网文档](https://uniapp.dcloud.net.cn/quickstart-cli.html)): - 创建以 javascript 开发的工程（如命令行创建失败，请直接访问 gitee 下载模板） ```bash npx degit dcloudio/uni-preset-vue#vite my-vue3-project ``` - 创建以 typescript 开发的工程（如命令行创建失败，请直接访问 gitee 下载模板） ```bash npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project ``` > gitee 地址见上方的 `参考官网文档` 链接，点击跳转到 uni-app 官网即可 ## 视频演示 --- ## 🔥 uni-app x 目前 `weapp-tailwindcss` 从 `4.2.0` 版本开始，插件已经支持 `uni-app-x` 同时构建包括 `web`,`小程序`, `安卓`,`IOS`,`鸿蒙` 五端项目 ## 创建工具类 在项目中创建 `shared.js` 文件，用于存放一些工具函数： ```js title="shared.js" const path = require('node:path') function r(...args) { return path.resolve(__dirname, ...args) } module.exports = { r, } ``` ## 注册插件 创建 `vite.config.ts` 文件，注册插件： > 这里特别注意 `uniAppX` 是从 `weapp-tailwindcss/presets` 这个预设中导出的 ```js title="vite.config.[jt]s" export default defineConfig({ plugins: [ uni(), UnifiedViteWeappTailwindcssPlugin( uniAppX({ base: __dirname, rem2rpx: true, }), ), ], css: { postcss: { plugins: [ tailwindcss({ config: r('./tailwind.config.js'), }), ] } } }); ``` ## 更改 tailwindcss 配置 使用绝对路径，包括所有的提取文件 ```js title="tailwind.config.js" const { r } = require('./shared') /** @type {import('tailwindcss').Config} */ module.exports = { content: [ r('./pages/**/*.{uts,uvue}'), r('./components/**/*.{uts,uvue}') ], corePlugins: { preflight: false, }, } ``` ## 现成模板可以直接使用或者参考 https://github.com/icebreaker-template/uni-app-x-hbuilderx 使用方式详见项目中的 `README.md` --- ## uni-app cli vue2 webpack :::warning 这是 `uni-app cli` 创建的项目的注册方式，如果你使用 `HbuilderX`，应该查看 [uni-app HbuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx) ::: :::tip 截止到 (2023/09/08)，目前所有的 `uni-app vue2 cli` 项目的 `webpack` 版本，已经切换到了 `webpack@5`，`@vue/cli@5`，`postcss@8` 了 另外如果你有旧有的 `uni-app webpack4` 项目需要迁移到 `webpack5`，可以看这篇 [旧有uni-app项目升级webpack5指南](/docs/upgrade/uni-app) ::: ```js title="vue.config.js" const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') /** * @type {import('@vue/cli-service').ProjectOptions} */ const config = { // some option... // highlight-start configureWebpack: (config) => { config.plugins.push( new UnifiedWebpackPluginV5({ rem2rpx: true, }) ) } // highlight-end // other option... } module.exports = config ``` 这样所有的配置便完成了！赶紧启动你的项目试试吧！ --- ## tailwindcss 多上下文与独立分包 你看过动漫《百兽王》吗？《百兽王》的主人公是五个飞行员，他们分别驾驶黑、红、青、黄、绿五头机器狮，它们平时可以单独进行作战，遇到强敌时，也能进行五狮合体，成为巨大机器人“百兽王”。 同样，在日常开发中，我们经常遇到这样的问题，一个很大的程序，它有很多个独立的部分组成，每一个部分可以单独运行，也有独立的入口，相互之间没有任何的依赖，但是它们在同一个项目/任务里进行构建。 在这种场景下，去使用 `tailwindcss` 就往往需要去创建多个上下文，让这些上下文各自去管理我们程序中的指定的一块区域。 当然我写到这，相信大家也啥都没看懂，于是我搬出一个小程序中，独立分包的示例，来让大家理解这种思想。 ## 什么是独立分包 独立分包是小程序中一种特殊类型的分包，可以独立于主包和其他分包运行。从独立分包中页面进入小程序时，不需要下载主包。当用户进入普通分包或主包内页面时，主包才会被下载。 独立分包属于分包的一种。普通分包的所有限制都对独立分包有效。独立分包中插件、自定义组件的处理方式同普通分包。此外，使用独立分包时要注意： 1. 独立分包中不能依赖主包和其他分包中的内容，包括 js 文件、template、wxss、自定义组件、插件等（使用 分包异步化 时 js 文件、自定义组件、插件不受此条限制） 2. 主包中的 `app.wxss` 对独立分包无效，应避免在独立分包页面中使用 `app.wxss` 中的样式； 3. App 只能在主包内定义，独立分包中不能定义 App，会造成无法预期的行为； 4. 独立分包中暂时不支持使用插件。 > 更多信息详见 [微信独立分包官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/independent.html) --- 这里要特别注意第二条: **主包中的 `app.wxss` 对独立分包是无效的!!!** 在我之前提供的`tailwindcss`小程序模板的示例中，所有 `tailwindcss` 生成的 `wxss` 工具类都是在主包里共用的 (`app.wxss`)，这在大部分情况下运转良好，然而这在独立分包场景下，是不行的！因为主包的样式无法影响到独立分包。 那么应该怎么做才能解决这个问题呢？ ## 创建与配置示例 这里笔者先以 `taro@3.6.7` 和 `weapp-tailwindcss@2.5.2` 版本的项目作为示例。 首先配置好 `weapp-tailwindcss` 的配置，然后在 `config/index.js` 中关闭 `prebundle` 功能，因为这在独立分包场景下会报一些未知的错误: ```js const config = { compiler: { prebundle: { enable: false, }, type: 'webpack5' }, // ..... } ``` 其次关闭插件对 `tailwindcss css var` 主块的寻址行为： ```js chain.merge({ plugin: { install: { plugin: UnifiedWebpackPluginV5, args: [{ // 方法1: 不要传 appType // 注释掉 appType : 'taro' // 或者方法2: 让所有css chunk 都是 main chunk // mainCssChunkMatcher: ()=> true // 2 种选其一即可 }] } } }) ``` 接下来我们就可以创建一个独立分包 `moduleA`，在里面新建一个 `"pages/index"` 页面，并写入一个只属于 `moduleA` 的独一无二的 `tailwindcss class`，然后在 `app.config.ts` 里注册它: ```js subpackages: [ { root: "moduleA", pages: [ "pages/index", ], // 下方这个标志位，声明独立分包 independent: true }, ] ``` 到这里，准备工作就完成了，接下来就可以设计方案了。 ## 单 `tailwindcss` 上下文的方案（不完美不推荐） 这个方案是一个不完美的方案，在这里写出来是为了促进大家对 `tailwindcss` 的理解。 首先在独立分包中，也创建一个 `index.scss` 内容为: ```css @import 'tailwindcss/base'; @import 'tailwindcss/components'; @import 'tailwindcss/utilities'; ``` 然后在所有独立分包中的页面引用它，这样打包之后，独立分包里的 `tailwindcss` 样式也就生效了。 然而这种方式有一个巨大的问题，就是它会带来严重的 `css` 冗余。 因为此时 `tailwindcss` 上下文有且仅有一个，它会把在这个项目中，所有提取出来的 `css` 工具类，全部注入到所有的 `@tailwind` 指令里去。`@import 'tailwindcss/utilities'` 这个引入(本质实际上是`@tailwind`指令)一下子膨胀了起来。 这导致了，主包里的 `app.wxss` 里，会包含主包里所有的 `class` + 独立分包里所有的 `class`，而独立分包里的 `index.scss` 里，也包含主包里所有的 `class` + 独立分包里所有的 `class`! 这显然是不可接受的，因为主包是没有必要包含独立分包的 `class`，而独立分包里，也没有必要包含主包里的 `class`! 这只会白白增大打包后`wxss`文件的体积。 所以这个方案需要改进! ## 多 `tailwindcss` 上下文的方案 由于上面那个方案的问题，我们开始改进，就必须要创建多个 `tailwindcss` 上下文。 那么第一步就是要 **`↓`** ### 创建多个 `tailwind.config.js` 比如说我们只有一个独立分包，所以我们创建了2个 `tailwind.config.js`: 1. `tailwind.config.js` 用于主包以及相互依赖的子包 2. `tailwind.config.sub.js` 用于 `moduleA` 这个独立分包 内容如下: #### 独立分包的上下文配置 ```js // `moduleA` 这个独立分包的 tailwind.config.sub.js /** @type {import('tailwindcss').Config} */ module.exports = { // 这里只提取 moduleA 这个独立分包下的文件内容 content: ["./src/moduleA/**/*.{html,js,ts,jsx,tsx}"], // .... corePlugins: { preflight: false } } ``` #### 主包以及相互依赖的子包的上下文配置 ```js // 主包以及相互依赖的子包的 tailwind.config.js /** @type {import('tailwindcss').Config} */ module.exports = { // https://github.com/mrmlnc/fast-glob // 这里需要限定范围，不去提取 moduleA 这个独立分包下的文件内容 // 所以后面跟了一个 `!` 开头的路径 content: [ "./src/**/*.{html,js,ts,jsx,tsx}", // 不提取独立分包里的 class "!./src/moduleA/**/*.{html,js,ts,jsx,tsx}"], // .... corePlugins: { preflight: false } } ``` 这样 `2` 个配置文件创建好了，接下来就要通过配置让它们各自在打包中生效。 ### `postcss.config.js` 配置 这是非常重要的一块配置，我们需要把 `postcss.config.js` 的配置变成一个函数，这样才能把构建时的上下文传入进来： ```js const path = require('path') module.exports = function config(loaderContext) { // moduleA 下面的所有 scss 文件，都是独立模块的，应用不同的 tailwindcss 配置 const isModuleA = /moduleA[/\\](?:\w+[/\\])*\w+\.scss$/.test( loaderContext.file ) // 多个独立子包同理，加条件分支即可 if (isModuleA) { return { plugins: { tailwindcss: { config: path.resolve(__dirname, 'tailwind.config.sub.js') }, autoprefixer: {}, } } } return { plugins: { // 不传默认取 tailwind.config.js tailwindcss: {}, autoprefixer: {}, } } } ``` 通过这种方式，我们成功的创建了 `2` 个不同的 `tailwindcss` 上下文，此时你进行打包之后，会发现 主包里的 `app.wxss` 和独立分包里的 `index.wxss`，里面的内容就已经各归各了，不再相互包含了。 ## 尾言 当然，上面只是一种方案，达到这样的目的方式有很多种，比如你可以在运行时去修改 `postcss-loader` 对它进行劫持，或者拆成多个项目，分开构建。 我这篇文章只是抛砖引玉，相信聪明的你们一定可以举一反三的。 ## 参考示例 示例见: --- ## 1. 安装与配置 tailwindcss > 请确保你的 `nodejs` 版本 `^18.17.0 || >=20.5.0`。目前低于 `18` 的长期维护版本(`偶数版本`) 都已经结束了生命周期，建议安装 `nodejs` 的 `LTS` 版本，详见 [nodejs/release](https://github.com/nodejs/release)。 > > 假如你安装的 `nodejs` 太新，可能会出现安装包不兼容的问题，这时候可以执行安装命令时，使用 `--ignore-engines` 参数进行 `nodejs` 版本的忽略 。 首先安装本插件前，我们需要把 `tailwindcss` 对应的环境和配置安装好。 这里我们参考 `tailwindcss` 官网中 `postcss` 的使用方式进行安装 ([参考链接](https://tailwindcss.com/docs/installation/using-postcss)) ## 1. 使用包管理器安装 `tailwindcss` ```bash npm2yarn # 安装 tailwindcss@3 版本的依赖 npm i -D tailwindcss@3 postcss autoprefixer ``` ```bash npm2yarn # 初始化 tailwind.config.js 文件 npx tailwindcss init ``` :::info `tailwindcss` 最新版本(`3.x`)对应的 `postcss` 大版本为 `8`，假如你使用像 `uni-app` 或 `taro` 这样的跨端框架，大概率已经内置了 `postcss` 和 `autoprefixer` ::: ## 2. 在项目目录下创建 `postcss.config.js` 并注册 `tailwindcss` > 注意：这只是比较普遍的注册方式，各个框架很有可能是不同的! 比如 `uni-app vue3 vite` 项目就必须要内联注册 `postcss` 选项! 详见下方的注意事项 ```js title="postcss.config.js" // 假如你使用的框架/工具不支持 postcss.config.js 配置文件，则可以使用内联的写法 module.exports = { plugins: { tailwindcss: {}, // 假如框架已经内置了 `autoprefixer`，可以去除下一行 autoprefixer: {}, } } ``` :::tip 注意事项 `uni-app vite vue3` 项目，必须在`vite.config.ts` 文件中，使用 `postcss` 内联的写法注册插件。相关写法可以参考我的这个模板项目: [uni-app-vite-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template)。 而 `uni-app vue webpack5` 项目中的 `postcss.config.js`，在默认情况下，已经预置很多插件在里面，配置比较繁杂，可以参考这个文件 [uni-app-webpack5/postcss.config.js](https://github.com/sonofmagic/weapp-tailwindcss/blob/main/demo/uni-app-webpack5/postcss.config.js) ::: ## 3. 配置 `tailwind.config.js` `tailwind.config.js` 是 `tailwindcss` 的配置文件，我们可以在里面配置 `tailwindcss` 的各种行为。 ```js title="tailwind.config.js" /** @type {import('tailwindcss').Config} */ module.exports = { // 这里给出了一份 uni-app /taro 通用示例，具体要根据你自己项目的目录结构进行配置 // 不在 content 包括的文件内，你编写的 class，是不会生成对应的css工具类的 content: ['./public/index.html', './src/**/*.{html,js,ts,jsx,tsx,vue}'], // 其他配置项 // ... corePlugins: { // 小程序不需要 preflight，因为这主要是给 h5 的，如果你要同时开发小程序和 h5 端，你应该使用环境变量来控制它 preflight: false } } ``` ## 4. 引入 `tailwindcss` 在你的项目入口引入 `tailwindcss` 使它在小程序全局生效 ### uni-app 比如 `uni-app` 的 `App.vue` 文件: ```html title="App.vue" ``` :::warning 千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容 所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了 ::: ### Taro 又或者 `Taro` 的 `app.scss` 文件: ```scss title="app.scss" @import 'tailwindcss/base'; @import 'tailwindcss/components'; @import 'tailwindcss/utilities'; // sass 版本1.25+ 使用 @use // @use 'tailwindcss/base'; // @use 'tailwindcss/components'; // @use 'tailwindcss/utilities'; // 非 scss 的纯 css 文件，下列写法也是可以生效的 // @tailwind base; // @tailwind components; // @tailwind utilities; ``` 然后在 `app.ts` 里引入这个样式文件即可。 这样 `tailwindcss` 的安装与配置就完成了，接下来让我们进入第二个环节：安装 `weapp-tailwindcss`。 ## 参考链接 [`tailwindcss` 官方配置项](https://tailwindcss.com/docs/configuration) --- ## IDE 智能提示设置 ## VS Code > 首先，确保你已经安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) ### 让 `Tailwind CSS IntelliSense` 识别 weapp-tailwindcss v4 `tailwindcss-intellisense` 在 v4 中必须看到 `@import "tailwindcss"` 才会将工作区视为 Tailwind 根文件。从 v4.7.10 起，`weapp-tailwindcss` 默认会在构建阶段把这些 `@import 'tailwindcss'` 自动改写成 `@import 'weapp-tailwindcss'`（可通过 `rewriteCssImports: false` 关闭）。这意味着你可以直接在项目入口写 `@import 'tailwindcss';` 以获得 IntelliSense，而插件会在最早的 PostCSS 流程中替换成小程序可用的样式。 如果仍希望与源码解耦，也可以使用 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';`，默认启用的 `rewriteCssImports` 会让 webpack/vite 在 CSS 解析阶段把它映射到 `weapp-tailwindcss`（只影响样式导入，JS/TS `import 'tailwindcss'` 不会被修改）。 保存/重载任意文件后 VS Code 会检测到该辅助文件，从而让 `@import 'weapp-tailwindcss';` 的项目享受到完整的补全、悬浮和跳转体验。 ### 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` ![如图所示](./frameworks/img/vscode-setting.png) 智能提示就出来了: ![智能提示](./frameworks/img/wxml-i.png) #### 工作区设置 在你的打开的工作区目录的根目录里，创建 `.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\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)" ] ] } ``` 这样配置之后，智能提示就出来了: ![智能提示](./frameworks/img/js-intelliSense.png) [Refer link](https://github.com/lukeed/clsx#tailwind-support) #### 存在问题 这种原理也是依赖正则匹配，即 `Tailwind CSS IntelliSense 插件` 匹配到了当前 `vscode` 活动的文本域中，存在着 `clsx()` 方法这个关键词，所以就把智能提示给注入进去。 所以你这样写就不会生效: ```js 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. 安装与配置 tailwindcss(Native) ## 前言 很荣幸，我们在 `weapp-tailwindcss@3.2.0` 版本开始，引入了微信小程序原生支持的能力。 (其他平台的原生小程序开发，也非常容易兼容) 接下来让我们看看，如何进行使用吧！ 本教程演示的是，使用微信开发者工具创建的原生 `js` 小程序，以及原生 `js` `skyline` 小程序使用 `tailwindcss` 的方式 ### 运行环境 请确保你的 `nodejs` 版本 `>=16.6.0`。目前低于 `16` 的长期维护版本(`偶数版本`) 都已经结束了生命周期，建议安装 `nodejs` 的 `LTS` 版本，详见 [nodejs/release](https://github.com/nodejs/release)。 假如你安装的 `nodejs` 太新，可能会出现安装包不兼容的问题，这时候可以执行安装命令时，使用 `--ignore-engines` 参数进行 `nodejs` 版本的忽略 。 ## 创建项目 打开微信开发者工具, 点击 `+` 创建一个项目，依次选择: 0. `AppID` 使用测试号 1. 开发模式: `小程序` 2. 后端服务: `不使用云服务` 3. 模板选择: 第二项选择 `基础` 4. 选择 `JS 基础模板` ![](/img/create-project.png) > 使用 JS 基础模板创建的项目，依然可以使用 `Typescript` 首先安装本插件前，我们需要把 `tailwindcss` 对应的环境和配置安装好。 ## 0. 初始化 `package.json` 首先，假如你使用原生的 JS 模板创建的项目。 在创建的项目目录下，是没有 `package.json` 文件 (`原生的 TS 模板有这个文件`), 你需要执行命令: `npm init -y`，快速创建一个 `package.json` 文件在你的项目下 ## 1. 使用包管理器安装 `tailwindcss` 然后执行: ```bash npm2yarn # 安装 tailwindcss@3 版本的依赖 npm i -D tailwindcss@3 postcss autoprefixer ``` ```bash npm2yarn # 初始化 tailwind.config.js 文件 npx tailwindcss init ``` 这样 `tailwindcss` 就被安装到你项目本地了 ## 2. 配置 `tailwind.config.js` `tailwind.config.js` 是 `tailwindcss` 的配置文件，我们可以在里面配置 `tailwindcss` 的各种行为。 这里给出了一份 `JS微信小程序` 通用示例，具体要根据你自己项目的目录结构进行配置 ```js title="tailwind.config.js" /** @type {import('tailwindcss').Config} */ module.exports = { content: [ // 添加你需要提取的文件目录 'components/**/*.{wxml,js,ts}', 'pages/**/*.{wxml,js,ts}', // 不要使用下方的写法，这会导致 vite 开发时监听文件数量爆炸 // '**/*.{js,ts,wxml}', '!node_modules/**', '!dist/**' ], // 假如你使用 ts 模板，则可以使用下方的配置 // content: ['miniprogram/**/*.{ts,js,wxml}'], corePlugins: { // 小程序不需要 preflight 和 container，因为这主要是给 h5 的，如果你要同时开发小程序和 h5 端，你应该使用环境变量来控制它 preflight: false, container: false, } } ``` ## 3. 在项目目录下创建 `postcss.config.js` 并注册 `tailwindcss` 内容如下: ```js title="postcss.config.js" module.exports = { plugins: { tailwindcss: {}, autoprefixer: {}, } } ``` > 这个文件和 `tailwind.config.js` 平级 ## 4. 引入 `tailwindcss` 在你的小程序项目入口 `app.wxss` 文件中，引入 `tailwindcss` 使它在小程序全局生效 ```css @tailwind base; @tailwind components; @tailwind utilities; ``` 在 `app.wxss` 加入这一段代码之后，微信开发者工具会报错。不用担心，这是因为我们还没有完全配置好。 接下来，赶紧进入下一步，安装 `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 ``` ## 注册插件 给 `package.json` 添加下列脚本: ```json title="package.json" { "scripts": { "postinstall": "weapp-tw patch" } } ``` 然后在你的 `vite.config.ts` 里对插件进行注册: ```ts title="vite.config.ts" export default defineConfig({ // highlight-start plugins: [ uvwt({ rem2rpx: true, }), ], // highlight-end }) ``` ## 开始运行 使用 `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. 代码文件不在 `tailwind.config.js` 的 `content` 配置内 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/) --- ## 4. rem 转 rpx (或 px) > 此为可选步骤，根据你自己的需求进行配置。通常此配置的值，是由你拿到的设计稿尺寸决定的。 ## 为什么要配置 rem 转 rpx 呢？ 这是因为 `tailwindcss` 里面工具类的长度单位，默认都是 `rem`，比如: ```css .m-4 { margin: 1rem; } .h-4 { height: 1rem; } /*......*/ ``` `rem`这个单位在 `h5` 环境下自适应良好，但小程序环境下，我们大部分都是使用 `rpx` 这个 `wxss` 单位来进行自适应，所以就需要把默认的 `rem` 单位转化成 `rpx`。 ## 三种转化方式(根据你的需求选其一即可) ## 插件内置 rem 转 rpx 功能 (推荐) 在 `^3.0.0` 版本中，所有插件都内置了 `rem2rpx` 参数，默认不开启，要启用它只需将它设置成 `true` 即可 ```js // vite.config.js UnifiedViteWeappTailwindcssPlugin({ // ...other-options // highlight-next-line rem2rpx: true }) // webpack const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') new UnifiedWebpackPluginV5({ // ...other-options // highlight-next-line rem2rpx: true }) ``` 设置为 `true` 相当于 `rem2rpx` 传入下方这样一个配置对象: ```js { // 32 意味着 1rem = 16px = 32rpx rootValue: 32, // 默认所有属性都转化 propList: ['*'], // 转化的单位,可以变成 px / rpx transformUnit: 'rpx' } ``` :::tip 为什么 `rootValue` 默认值是 `32`? 这是因为开发微信小程序时, 设计师基本都使用 `iPhone6` 作为视觉稿的标准，此时 `1px = 2rpx`。 然后默认情况下 `1rem = 16px`，所以 `1rem = 16px = 32rpx`。 详见 [WXSS 尺寸单位](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxss.html#%E5%B0%BA%E5%AF%B8%E5%8D%95%E4%BD%8D) 章节， ::: 当然你也可以自行传入一个 `object` 来进行更多配置，具体的配置项见 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) ### 优势 这种方式 **最简单**，和插件集成度高，传入一个配置就好了。 ## 外置 postcss 插件 首先我们安装 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) ```bash npm2yarn npm i -D postcss-rem-to-responsive-pixel ``` 安装好之后，把它注册进你的 `postcss.config.js` 即可: ```js title="postcss.config.js" module.exports = { plugins: { tailwindcss: {}, autoprefixer: {}, 'postcss-rem-to-responsive-pixel': { // 32 意味着 1rem = 32rpx rootValue: 32, // 默认所有属性都转化 propList: ['*'], // 转化的单位,可以变成 px / rpx transformUnit: 'rpx' // postcss-rem-to-responsive-pixel@6 版本添加了 disabled 参数，用来禁止插件的转化 // disabled: process.env.TARO_ENV === 'h5' || process.env.TARO_ENV === 'rn' } } } ``` :::tip 一些用户在使用 `tarojs` 开发的时候，错误的把 `tailwindcss` 配置在了 `config/index.js` 的 `postcss` 里，导致不生效。 原因实际上是因为 `config/index.js` 的 `postcss`这个配置，只是用来配置 `tarojs` **内置** `postcss` 插件的参数。 要使用 `tailwindcss`，你需要在项目根目录，新建一个 `postcss.config.js`，然后把上面的代码写入进去。 ::: ### 优势 这种方式 **最灵活**，你可以自由的决定 `postcss` 插件的加载顺序，也可以按你自己的策略按需加载插件 (比如特定目录下的样式才接受这个插件的转化) ## 外置 tailwindcss 插件 你想缩小一下范围，只把 `tailwindcss` 生成的工具类的单位，从 `rem` 转变为 `rpx`，那么我写的 `tailwindcss preset`: [tailwindcss-rem2px-preset](https://www.npmjs.com/package/tailwindcss-rem2px-preset) 适合你。 同样我们安装它： ```bash npm2yarn npm i -D tailwindcss-rem2px-preset ``` 然后在 `tailwind.config.js` 中，注册这个预设： ```js title="tailwind.config.js" module.exports = { presets: [ require('tailwindcss-rem2px-preset').createPreset({ // 32 意味着 1rem = 32rpx fontSize: 32, // 转化的单位,可以变成 px / rpx unit: 'rpx' }) ] // ... } ``` 这样即可完成 `tailwindcss` 默认工具类的 `rem` 转 `rpx` 的配置了。 ### 优势 这种方式受影响范围 **最小**，因为 `preset` 方式处理 `tailwindcss`,不会把你写的其他样式里的 `rem` 转化成 `rpx` ## px 转 rpx 如果你也有 [`px 转 rpx`](/docs/quick-start/css-unit-transform) 的需求，你可以查看 [CSS 单位转化](/docs/quick-start/css-unit-transform) 这个章节。 --- ## 2. 安装 weapp-tailwindcss 在项目目录下，执行: ```bash npm2yarn npm i -D weapp-tailwindcss # 假如 tailwindcss 在 weapp-tailwindcss 之后安装，可以手动执行一下 patch 方法 # npx weapp-tw patch ``` 然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里: ```json title="package.json" "scripts": { // highlight-next-line "postinstall": "weapp-tw patch" } ``` :::caution 使用 pnpm@10+ `pnpm@10` 默认只允许 `onlyBuiltDependencies` 中的包运行生命周期脚本。安装完本插件后，请执行 `pnpm approve-builds weapp-tailwindcss` 将其加入白名单，避免 `postinstall` 的 `weapp-tw patch` 被跳过。 ::: :::info 执行 `weapp-tw patch` 主要是做2件事情 ### 1. 给当前你本地的 `tailwindcss` 打上支持 `rpx` 的补丁 (小程序特有单位，非 `web` 标准)。 否则你一旦使用像 `text-[14.43rpx]` 这样的任意值写法，生成出来的 `css` 样式就是 `color: 14.43rpx;`，显然是错误的。 它会被 `tailwindcss` 认为是一种颜色，从而导致生成错误，样式不生效。 详见 [rpx 任意值颜色或长度单位二义性与解决方案](/docs/issues/rpx-ambiguities) ### 2. 暴露 `tailwindcss` 运行上下文给 `webpack`/`vite`/`glup` 插件。 这样就能够在 `js` 中，和 `postcss` 插件进行通信，从而达到共享上下文的效果。 --- 而添加上面一段 `npm scripts` 的用途是，利用 `npm hook`, 每次安装包后，都会自动执行一遍 `weapp-tw patch` 这个脚本。 这样即使 `tailwindcss` 更新了版本导致了补丁失效，也会在重新下载后，第一时间被打上。 如果你希望在补丁前“强制刷新 `tailwindcss-patch` 的缓存目录（如 `node_modules/.cache/tailwindcss-patch`）”，可以在命令后附加 `--clear-cache`： ```json title="package.json" "scripts": { "postinstall": "weapp-tw patch --clear-cache" } ``` 默认不清理缓存，更加保守稳定；仅当怀疑缓存导致补丁未生效或版本不一致时再开启该参数。 ::: 我们已经完成了这些步骤了，最后就是注册这个插件，到各个不同的框架里去，马上就好！ --- ## uni-app 条件编译语法糖插件 > 版本需求 2.10.0+ ## 这是什么玩意? 在 `uni-app` 里，存在一种类似宏指令的[样式条件编译写法](https://uniapp.dcloud.net.cn/tutorial/platform.html#%E6%A0%B7%E5%BC%8F%E7%9A%84%E6%9D%A1%E4%BB%B6%E7%BC%96%E8%AF%91): ```css /* #ifdef %PLATFORM% */ 平台特有样式 /* #endif */ ``` > uni-app `%PLATFORM%` 的所有取值可以参考这个[链接](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor) 在 `weapp-tailwindcss@2.10.0+` 版本中内置了一个 `css-macro` 功能，可以让你的 `tailwindcss` 自动生成带有条件编译的样式代码，来辅助你进行多平台的适配开发，效果类似如下方式: ```html Web和微信小程序平台蓝色背景 非MP-WEIXIN平台红色背景 微信小程序为蓝色，不是微信小程序为红色 微信小程序为蓝色，不是微信小程序为红色 头条小程序蓝色 ``` 或者这样的条件样式代码: ```css /*只在 H5 和 MP-WEIXIN, 背景为蓝色，否则为红色 */ .apply-test-0 { @apply ifdef-[H5||MP-WEIXIN]:bg-blue-400 ifndef-[H5||MP-WEIXIN]:bg-red-400; } /* 自定义 */ .apply-test-1 { @apply mv:bg-blue-400 -mv:bg-red-400 wx:text-blue-400 -wx:text-red-400; } ``` 让我们看看如何使用吧！ ## 如何使用 这里需要同时配置 `tailwindcss` 和 `postcss` 的配置文件才能起作用，其中 `tailwindcss` 配置修改的方式大体类似， `uni-app` `vue2/3` `postcss`插件的注册方式，有些许不同: ### tailwind.config.js 注册 首先在你的 `tailwind.config.js` 注册插件 `cssMacro`: #### Tailwind CSS 3.x 配置 ```js const cssMacro = require('weapp-tailwindcss/css-macro'); /** @type {import('tailwindcss').Config} */ module.exports = { // ... plugins: [ /* 这里可以传入配置项，默认只包括 ifdef 和 ifndef */ cssMacro(), ], }; ``` #### Tailwind CSS 4.x 配置 > v4 推荐直接在入口 CSS 中通过 `@plugin` 引入。 ```css /* tailwind.css */ @import "tailwindcss"; @plugin "weapp-tailwindcss/css-macro"; /* 可选：为常用平台创建语义别名 */ @utility platform-weixin:(value) { @apply ifdef-[MP-WEIXIN]:$(value); } @utility not-alipay:(value) { @apply ifndef-[MP-ALIPAY]:$(value); } ``` 若需要自定义更多静态变体，可额外保留一个 `tailwind.config.ts` 以传入参数： ```ts export default { plugins: { cssMacro: cssMacro({ variantsMap: { wx: 'MP-WEIXIN', '-wx': { value: 'MP-WEIXIN', negative: true }, }, }), }, } ``` > [!TIP] > `cssMacro` 的动态变体（`ifdef:` / `ifndef:`）依赖 Tailwind 内置的 `matchVariant`，请确保 Tailwind 版本 ≥ 3.2；在 v4 中该 API 同样可用。 ### postcss 插件注册 对应的 `postcss` 插件位置为 `weapp-tailwindcss/css-macro/postcss` 值得注意的是，你必须把这个插件，注册在 `tailwindcss` 之后和 `@dcloudio/vue-cli-plugin-uni/packages/postcss` 之前。 > `@dcloudio/vue-cli-plugin-uni/packages/postcss` 为 vue2 cli项目特有，vue3不用管。 注册在 `tailwindcss` 之后很好理解，我们在针对 `tailwindcss` 的产物做修改，自然要在它执行之后处理，注册在 `@dcloudio/vue-cli-plugin-uni/packages/postcss` 之前则是因为 `uni-app` 样式的条件编译，靠的就是它。假如在它之后去处理不久已经太晚了嘛。 > 这里提一下 postcss 插件的执行顺序，假如注册是数组，那就是按照顺序执行，如果是对象，那就是从上往下执行，详见[官方文档](https://www.npmjs.com/package/postcss-load-config#ordering) #### uni-app vite vue3 ```diff // vite.config.ts 文件 // postcss 插件配置 const postcssPlugins = [require('autoprefixer')(), require('tailwindcss')()]; // ... 其他省略 + postcssPlugins.push(require('weapp-tailwindcss/css-macro/postcss')); // https://vitejs.dev/config/ export default defineConfig({ plugins: vitePlugins, css: { postcss: { plugins: postcssPlugins, }, }, }); ``` > 可以参考这个项目的配置 [demo/uni-app-vue3-vite](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/uni-app-vue3-vite) #### uni-app vue2 vue2 cli 项目默认会带一个 `postcss.config.js` 我们之间直接在里面注册即可: ```diff const webpack = require('webpack') const config = { parser: require('postcss-comment'), plugins: [ // ... require('tailwindcss')({ config: './tailwind.config.js' }), // ... + require('weapp-tailwindcss/css-macro/postcss'), require('autoprefixer')({ remove: process.env.UNI_PLATFORM !== 'h5' }), + // 注意在 tailwindcss 之后和 这个之前 require('@dcloudio/vue-cli-plugin-uni/packages/postcss') ] } if (webpack.version[0] > 4) { delete config.parser } module.exports = config ``` > 可以参考这个项目的配置 [demo/uni-app](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/uni-app) ### 配置完成 现在配置好了这2个地方，目前你就可以直接使用 `ifdef` 和 `ifndef` 的条件编译写法了！ ```html Web和微信小程序平台蓝色背景 非MP-WEIXIN平台红色背景 微信小程序为蓝色，不是微信小程序为红色 微信小程序为蓝色，不是微信小程序为红色 头条小程序蓝色 ``` 不过你肯定会觉得这种默认写法很烦！要写很多，不要紧，我还为你提供了自定义的方式，接下来来看看配置项吧！ ## 配置项 这里提供了一份示例， > uni-app `%PLATFORM%` 的所有取值可以参考这个[链接](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor) ```js const cssMacro = require('weapp-tailwindcss/css-macro'); /** @type {import('tailwindcss').Config} */ module.exports = { // ... plugins: [ /* 这里可以传入配置项，默认只包括 ifdef 和 ifndef */ cssMacro({ // 是否包含 ifdef 和 ifndef，默认为 true // dynamic: true, // 传入一个 variantsMap variantsMap: { // wx 对应的 %PLATFORM% 为 'MP-WEIXIN' // 有了这个配置，你就可以使用 wx:bg-red-300 wx: 'MP-WEIXIN', // -wx，语义上为非微信 // 那就传入一个 obj 把 negative 设置为 true // 就会编译出 ifndef 的指令 // 有了这个配置，你就可以使用 -wx:bg-red-300 '-wx': { value: 'MP-WEIXIN', negative: true }, mv: { // 可以使用表达式 value: 'H5 || MP-WEIXIN' }, '-mv': { // 可以使用表达式 value: 'H5 || MP-WEIXIN', negative: true } } }), ], }; ``` ## IDE智能提示 只要你使用 `vscode`/`webstorm` 这类IDE，加上安装了 `tailwindcss` 的官方插件。 智能提示会根据你对 `cssMacro` 这个插件的配置，直接生成出来！ > 假如没有下方的智能提示出现，有可能是 `tailwindcss` 插件挂了，这时候可以改好配置之后 **重启** `vscode` 以重新运行插件 这里我们以上面 `配置项` 为例: ### 动态提示: ifdef-[] 和 ifndef-[] ![macro-tip0](./img/macro-tip0.png) ### 配置的静态提示: wx 和 -wx ![macro-tip1](./img/macro-tip1.png) --- ## 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 @tailwindcss/postcss weapp-tailwindcss ``` ## 2. 添加 `vite.config.ts` ```ts title="vite.config.ts" export default defineConfig({ plugins: [ uni(), UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true, tailwindcssBasedir: __dirname, cssEntries: [ // 你 @import "tailwindcss"; 那个文件绝对路径 path.resolve(__dirname, './src/app.css'), ], }), ], css: { postcss: { plugins: [ tailwindcss({ base: __dirname }) ] } } }); ``` > tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。 ## 3. 添加样式 现在，在你的页面里面去随意的编写样式，比如 `bg-[#123456] text-[#654321]`, 然后运行到微信开发者工具即可 ## 参考模板 - [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` 中引入 `tailwindcss`，这个文件会作为 `cssEntries` 的入口： ```css title="src/app.css" @import "tailwindcss"; ``` 为了解决 IDE 智能提示问题，再额外创建一个 `main.css` 并引入 `tailwindcss/css`。 ```css title="src/main.css" @import "tailwindcss/css"; @source not "dist"; ``` 在项目目录下的 `App.vue` 中，添加以下内容： ```html title="App.vue" ``` :::warning 千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容 所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了 ::: --- ## UniappHbuilderStyle 在 `src/app.css` 中引入 `tailwindcss`，这个文件会作为 `cssEntries` 的入口： ```css title="src/app.css" @import "tailwindcss"; ``` 为了 IDE 智能提示，再额外创建一个 `main.css` 并引入 `tailwindcss/css`。 ```css title="src/main.css" @import "tailwindcss/css"; @source not "unpackage"; ``` 在项目目录下的 `App.vue` / `App.uvue`(uni-app x 项目) 然后添加以下内容： ```html title="App.vue" ``` > 添加 `@source not "unpackage";` 是为了避免 `HBuilderX` 差量编译死循环问题 :::warning 千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容 所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了 ::: --- ## Mpx ## 安装 ```bash npm2yarn npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss ``` ## 配置 更改 `mpx.config.js` 注册 `weapp-tailwindcss` ```js title="mpx.config.js" const { defineConfig } = require('@vue/cli-service') const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') const path = require('node:path') const tailwindPostcss = require('@tailwindcss/postcss') module.exports = defineConfig({ outputDir: `dist/${process.env.MPX_CURRENT_TARGET_MODE}`, pluginOptions: { mpx: { plugin: { postcssInlineConfig: { // tailwindcss@4 需要在此处注册 @tailwindcss/postcss，详见 templates/mpx-tailwindcss-v4/mpx.config.js ignoreConfigFile: true, plugins: [tailwindPostcss()] }, 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 UnifiedWebpackPluginV5({ appType: 'mpx', rem2rpx: true, cssEntries: [ // 你 @import "tailwindcss"; 那个文件绝对路径 path.resolve(__dirname, './src/app.css'), ], }) ) // highlight-end } }) ``` > tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。 > tailwindcss@4 下必须在 `mpx.config.js` 里用 `postcssInlineConfig` 注册 `@tailwindcss/postcss`（同仓库 `templates/mpx-tailwindcss-v4/mpx.config.js` 的写法），否则插件不会生效，无需再单独维护 `postcss.config.js`。 ## 添加样式 在 `src/app.css` 中引入 `weapp-tailwindcss`： ```css title="src/app.css" @import "tailwindcss"; ``` > 💡 如果你希望在任意样式文件中直接引用包内样式，请使用 `@import "weapp-tailwindcss/index.css";`。这样可以确保 `postcss-import` 解析到的是真实的 CSS 资源，避免出现 "Unknown word "use strict"" 这一类由于误解析到 JS 文件导致的构建报错。 ### Tailwind CSS 样式引用指引 - **Tailwind CSS v3.x**：沿用旧模块名即可（例如 `@import 'tailwindcss/base.css'`、`@import 'tailwindcss/components.css'`、`@import 'tailwindcss/utilities.css'`）。 - **Tailwind CSS v4.x**：推荐直接引入 `weapp-tailwindcss` 提供的聚合样式： ```html title="src/app.mpx" ``` 这样可以一次性获得 base / components / utilities，并规避 `postcss-import` 误解析 JS 入口的报错。如果你是从 v3 升级，只需将原来的三个 `@import` 换成这条语句即可。 然后在项目目录下，小程序全局的 `app.mpx` 中，通过 `@import` 引入该文件： ```html title="app.mpx" ``` 更改好配置之后，直接启动即可 ## 参考模版 https://github.com/icebreaker-template/mpx-tailwindcss-v4 --- ## Patch 然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里: ```json title="package.json" "scripts": { // highlight-next-line "postinstall": "weapp-tw patch" } ``` :::caution 使用 pnpm@10+ `pnpm@10` 默认只允许 `onlyBuiltDependencies` 中的包运行生命周期脚本。安装完本插件后，请执行 `pnpm approve-builds weapp-tailwindcss` 将其加入白名单，避免 `postinstall` 的 `weapp-tw patch` 被跳过。 ::: 这是为了给 `tailwindcss@4` 打上支持 `rpx` 单位的补丁，否则它会把 `rpx` 认为是一种颜色 如需在补丁前强制刷新 `tailwindcss-patch` 的缓存，可改为： ```json title="package.json" "scripts": { "postinstall": "weapp-tw patch --clear-cache" } ``` 默认不清理缓存；只有当你怀疑缓存导致补丁未生效或目标不一致时，才需要添加 `--clear-cache`。*** --- ## 开发参考手册 :::warning 由于 `tailwindcss@4.x` 本身还在快速的开发迭代中，即使是小版本也可能带有一些意外的 `Breaking Change` 所以以下内容可能会经常变更，如果发现已经过时，请提 `issue` 或者直接修复提 `pr` ::: 所以假如你要兼容更多的手机机型，请使用 `tailwindcss@3.x`。 ## 定位的变化: 样式预处理器 相对于 `tailwindcss@3` 版本， `tailwindcss@4` 存在定位的重大变更 它直接变成了一个样式预处理器，和原生 `css` 已经它的规范相结合，相辅相成。 所以你在 `4.x` 版本中，不应该让 `tailwindcss` 和 `sass`,`less`,`stylus` 一起使用 详见: https://tailwindcss.com/docs/compatibility#sass-less-and-stylus ## 集成选择 `tailwindcss` 集成上提供了多种选择 (`cli`,`vite`,`postcss`)，这里我们主要选择 `@tailwindcss/postcss`，原因如下: 1. `@tailwindcss/postcss` 兼容性更好，开发打包器使用 `vite` 和 `webpack` 的都能用，而 `@tailwindcss/vite` 这里只有 `vite` 能用。 2. `@tailwindcss/vite` 很容易和其他的 `vite` 插件起冲突，尤其是和 `uni-app` / `taro` 一起使用的时候，依赖注册的顺序和编译 `hook` 注册的顺序 3. `uni-app`/`taro` 这种框架，默认都是 `cjs` 加载的，而 `@tailwindcss/vite` 只提供了 `esm` 的版本，所以集成上可能会遇到问题 4. `tailwindcss@3.x` 是 `postcss` 插件，`@tailwindcss/postcss` 也是 `postcss` 插件，所以选择它，项目迁移升级的成本会更低。 所以，综合考虑下来，我们主要选择 `@tailwindcss/postcss`。 当然，你也完全可以使用 `uni-app vite vue3` + `@tailwindcss/vite` 这种组合。从编译速度出发, `@tailwindcss/vite` 会更快，但是可能需要一些额外的配置，行为也有可能和 `tailwindcss@3.x` 不一致。 ## 小程序样式引入 `tailwindcss` 不同点 :::tip 自动导入转换 从 v4.7.10 起，`weapp-tailwindcss` 默认会通过 `rewriteCssImports` 选项，将代码中的 `@import "tailwindcss"` 自动改写为 `@import "weapp-tailwindcss/index.css"`。这意味着你可以直接使用官方文档的标准写法，插件会自动处理小程序适配。 如果遇到报错或样式不生效，可以手动改为 `@import "weapp-tailwindcss/index.css"`，或将 `rewriteCssImports` 设置为 `false`。 ::: ### 有什么区别? `@import "weapp-tailwindcss/index.css"` 相比 `@import "tailwindcss"` 的主要区别是: 1. `"weapp-tailwindcss"` 没有 `"tailwindcss"` 中 `h5` `preflight` 的类(这些都是给 `h5` 用的，小程序用不到) 2. `"weapp-tailwindcss"` 中，不使用 `tailwindcss` 默认的 `@layer` 来控制样式优先级。这是因为小程序本身不支持 `css` `@layer` 这个特性，强行启用会造成一些样式难以覆盖的问题。 ### 多端开发 假如你需要进行多端的开发，那么可以使用对应框架的样式条件编译写法，比如 `uni-app`: ```css /* #ifdef H5 */ @import "tailwindcss"; /* #endif */ /* #ifndef H5 */ @import "tailwindcss"; /* weapp-tailwindcss 会自动改写为小程序适配版本 */ /* #endif */ ``` 详见 https://uniapp.dcloud.net.cn/tutorial/platform.html ## css 作为配置文件 由于在 `tailwindcss@4` 中，配置文件默认为一个 `css` 文件，所以你需要显式的告诉 `weapp-tailwindcss` 你的入口 `css` 文件的绝对路径。 来让 `weapp-tailwindcss` 和 `tailwindcss` 保持一致的处理模式 > `cssEntries` 为一个数组，就是你 @import "tailwindcss"; 那些文件，可以有多个 ```ts { cssEntries: [ // 就是你 @import "tailwindcss"; 那个文件 // 比如 tarojs path.resolve(__dirname, '../src/app.css') // 比如 uni-app (没有 app.css 需要先创建，然后让 `main` 入口文件引入) // path.resolve(__dirname, './src/app.css') ], } ``` 假如不添加这个，会造成 `tailwindcss` 插件生成的样式，转义不了的问题。 > 插件会自动根据已安装的 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)` 的标签选择器样式: ![](./tailwindcss-v4-uniapp-layer.png) 这种情况，你就非常需要兼容性降级方案，即使用 [`postcss-preset-env`](https://www.npmjs.com/package/postcss-preset-env) (`weapp-tailwindcss` 已经内置了这个插件了，你可以直接使用它的配置，详见 [cssPresetEnv](/docs/api/interfaces/UserDefinedOptions#csspresetenv)) 这在开发需要兼容低版本移动端 h5 的时候很重要。 ## 使用 pnpm 默认使用 `pnpm` 的时候，由于 `pnpm` 是无法使用幽灵依赖的 但是 `uni-app`/`taro` 出于一些历史原因，是需要幽灵依赖的，这时候可以在项目下创建 `.npmrc` 添加内容如下 ```txt title=".npmrc" shamefully-hoist=true ``` 然后重新执行 `pnpm i` 安装包即可运行 ## 智能提示 目前 `tailwindcss@4` 的 `vscode` 插件，会扫描目录下的 `css` 来获取 `tailwindcss` 的配置。 但是这里有个非常坑的点是，它不会去自动的扫描 `.vue` 文件里面的 `tailwindcss` 引入 这就导致，我们假如想在 `vue` 项目(比如 `uni-app`) 中获得智能提示，必须再随便创建一个 `main.css`，然后通过 `App.vue` 文件引入它 ```css title="main.css" @import "tailwindcss/css"; @source not "dist"; ``` > **注意**：`weapp-tailwindcss` 的 `rewriteCssImports` 选项会自动将 `@import 'tailwindcss/css'` 改写为 `@import 'weapp-tailwindcss/css'`。如果遇到报错或样式不生效，请手动改为 `@import 'weapp-tailwindcss/css'`。 ```html title="App.vue" ``` ## 如何去除 preflight 样式 在引入 `@import "tailwindcss"` 时，默认会引入 `preflight` 样式。 ### 什么是 preflight 样式 一些全局的 `reset` 样式，用来让一些标签行为统一的，比如你在你的样式中，看到的: ```css view,text,::before,::after,::backdrop { box-sizing: border-box; margin: 0; padding: 0; border: 0 solid; } ``` 类似这样的就是 `weapp-tailwindcss` 给你的应用注入的 `preflight` 样式 ### 解决方案 `@import "tailwindcss"` (被改写为 `@import "weapp-tailwindcss/index.css"`) 本质上由三个部分组成: ```css @import 'weapp-tailwindcss/theme.css'; @import 'weapp-tailwindcss/preflight.css'; @import 'weapp-tailwindcss/utilities.css'; ``` 所以想要去除 `preflight` 样式，只需像下面一样写即可 ```diff - @import "tailwindcss"; + @import 'weapp-tailwindcss/theme.css'; + @import 'weapp-tailwindcss/utilities.css'; ``` ## 使用大写单位 (h-[100PX]) 无效问题 默认情况下，在 `process.env.NODE_ENV === 'production'` 的时候， `tailwindcss` 会自动进入优化模式 它会进行 `CSS` 单位的校准，比如把大写的 `PX` 转化为小写的 `px`，你要禁用这个行为可以这样传入。 ```js export default { plugins: { "@tailwindcss/postcss": { optimize: false }, } } ``` 详见: [@tailwindcss/postcss](https://github.com/tailwindlabs/tailwindcss/blob/7779d3d080cae568c097e87b50e4a730f4f9592b/packages/%40tailwindcss-postcss/src/index.ts#L73C35-L73C72) --- ## Taro vite ## 安装 ```bash npm2yarn npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss ``` > 这里不使用 `@tailwindcss/vite` 是由于 `taro` 配置没法加载纯 `esm` 不是 `cjs` 的包, 会爆错误 `No "exports" main defined` ## 配置 ```js title="config/index.ts" { compiler: { type: 'vite', vitePlugins: [ { name: 'postcss-config-loader-plugin', config(config) { // 加载 tailwindcss if (typeof config.css?.postcss === 'object') { config.css?.postcss.plugins?.unshift(tailwindcss()) } }, }, UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true, cssEntries: [ // 你 @import "tailwindcss"; 那个文件绝对路径 path.resolve(__dirname, '../src/app.css'), ], }), ] }, } ``` > tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。 > 这里使用 `vite` 插件直接去加载 `tailwindcss`，这是由于 `taro4 vite` 不会自动去加载项目下的 `postcss.config.js`，所以只能定义这个 `postcss-config-loader-plugin` ## 添加样式 在项目目录下的 `src/app.css` 中，添加以下内容： ```css title="src/app.css" @import "tailwindcss"; ``` 更改好配置之后，直接运行启动项目，微信开发者工具导入这个项目，即可看到效果。 ## 参考模板 https://github.com/icebreaker-template/taro-vite-tailwindcss-v4 --- ## Taro webpack ## 安装 ```bash npm2yarn npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss ``` ## 配置 ### 在你的根目录创建 `postcss.config.mjs` ```js title="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, } } ``` ### 在你的 `app.css` 里面添加 ```css @import "tailwindcss"; ``` ### 注册插件 在项目的配置文件 `config/index` 中注册: ```js title="config/index.[jt]s" // 假如你使用 js 配置，则使用下方 require 的写法 // const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack') // const path = require('node:path') { // 找到 mini 这个配置 mini: { // postcss: { /*...*/ }, // 中的 webpackChain, 通常紧挨着 postcss webpackChain(chain, webpack) { // 复制这块区域到你的配置代码中 region start // highlight-start chain.merge({ plugin: { install: { plugin: UnifiedWebpackPluginV5, args: [{ // 这里可以传参数 rem2rpx: true, cssEntries: [ // 你 @import "tailwindcss"; 那个文件绝对路径 path.resolve(__dirname, '../src/app.css'), ], }], }, }, }) // highlight-end // region end } } } ``` > tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。 ## 运行 然后执行命令发布到微信小程序 ```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" export default defineConfig({ plugins: [ UnifiedViteWeappTailwindcssPlugin({ cssEntries: [ /* ... */ ], cssPresetEnv: { stage: 1, features: { 'cascade-layers': true, }, }, }), ], }) ``` > 如果你只在微信小程序调试，可使用开发者工具的「自定义编译」观察处理前后的差异；若仍存在覆盖问题，可结合传统的 `!important` 或布局拆分策略。 额外提示： - `cssSelectorReplacement.root` 默认包含 `['page', '.tw-root']`。当页面外的容器（例如自定义 tab bar、弹出层根节点等）需要承载 Tailwind 注入的 `--tw-*` 变量时，只需在容器上加上 `class="tw-root"` 即可复用整套预设，无需额外配置。下面是一个在自定义 tab bar 中注入主题变量的示例： ```xml title="custom-tab-bar/index.mpx" ``` 搭配 `cssPreflight` 注入的变量或自定义 `@theme`，可以把 tab bar 的主题色、渐变背景等统一交给 Tailwind 管理。若你需要覆盖其他容器名称，仍可以通过配置把 `cssSelectorReplacement.root` 扩展为更多选择器。 - `cssPresetEnv` 会参与最终构建，请在发布前执行一次 `pnpm build:apps` 或对应的 `pnpm build` 命令确认产物 ## 2. 多端共存与按需构建 团队常同时维护小程序与 H5 版本，此时可以通过多个 `@source` 区分模板范围，并结合条件编译实现按需打包： ```css title="src/app.css" @source "../src/**/*.{vue,wxml}"; @source not "../src/**/*.h5.*"; /* 排除只用于 H5 的模板 */ /* 多端开发：H5 用官方 tailwindcss，小程序用 weapp-tailwindcss */ /* #ifdef H5 */ @import "tailwindcss"; /* #endif */ /* #ifndef H5 */ @import "tailwindcss"; /* weapp-tailwindcss 会自动改写为 @import 'weapp-tailwindcss/index.css' */ /* #endif */ ``` 当需要拆分体积时，可以把不同业务域的样式写到各自的 `entry.css`，再将路径加入 `cssEntries`： ```ts UnifiedViteWeappTailwindcssPlugin({ 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`，既减少模板体积，也方便统一调整 - **按需开启 `rem2rpx` / `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 + 小程序项目骨架 - 分清核心配置（`cssEntries`、`@source`、`@reference` 等）各自负责的事情 - 理解 `@tailwindcss/postcss`、`@tailwindcss/vite` 与编译插件的差异 - 掌握验证样式是否生效的最小闭环，避免“写了没生效”的常见坑 如果你还未接触过 `weapp-tailwindcss`，建议先浏览 [新手快速上手（Tailwind CSS 3.x）](/docs/quick-start/install) 了解插件能解决的问题，再回来完成 4.x 的配置。 ## 环境准备 | 名称 | 说明 | | --- | --- | | Node.js ≥ 18 | Tailwind CSS 4 要求更高的 Node 版本，建议使用 LTS 20 | | pnpm ≥ 8 | Monorepo 与文档项目统一使用 `pnpm` | | 小程序框架 | 任选 `weapp-vite`、`uni-app`、`taro` 等，推荐使用现成模板 | | 代码编辑器 | VS Code 并安装 `Tailwind CSS IntelliSense` 插件 | 初始化项目后，执行一次 `pnpm install` 以及框架 CLI 的初始化命令（如 `pnpm create @tarojs/cli`）。随后即可进入 Tailwind CSS 配置步骤。 ## 步骤一：安装依赖 在项目根目录执行： ```bash pnpm add -D tailwindcss@latest @tailwindcss/postcss postcss weapp-tailwindcss ``` > `@tailwindcss/postcss` 兼容 Vite、Webpack、Rspack 等大多数构建链路；对于纯 Vite 项目也可以酌情改用 `@tailwindcss/vite`，但在小程序场景下 `postcss` 方案更稳定。 ## 步骤二：注册 weapp-tailwindcss 插件 以 `weapp-vite` 为例（不同框架请对照对应的 [集成指南](/docs/quick-start/v4)）： ```ts title="vite.config.ts" export default defineConfig({ plugins: [ UnifiedViteWeappTailwindcssPlugin({ // 常用内置能力：开启 px 自动转换 rem2rpx: true, cssEntries: [ // 声明 Tailwind 的入口 CSS，必须是绝对路径 path.resolve(import.meta.dirname, './src/app.css'), ], }), ], }) ``` `cssEntries` 对 `tailwindcss@4` 至关重要，它告诉 `weapp-tailwindcss` 哪些 CSS 需要参与编译与转义。漏掉该配置将导致产物中缺失样式。 ## 步骤三：配置 PostCSS ```js title="postcss.config.js" export default { plugins: { '@tailwindcss/postcss': {}, }, } ``` Tailwind CSS 4 已内置 Autoprefixer，无需手动补充。若项目仍需其他 PostCSS 插件，保持旧的写法即可。 ## 步骤四：创建入口 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" ``` > `py-safe` 是我们在上文 `@theme` 中声明的自定义变量（通过 `--spacing-safe` 导出），可验证主题自定义是否生效。 运行框架命令（如 `pnpm dev:weapp` 或 `pnpm run build -- --watch`），查看开发者工具中的页面是否渲染出预期样式。如果没有： - 检查 `cssEntries` 是否指向了正确路径 - 确认 `@source` 是否包含当前文件扩展名 - 若在单文件组件内使用 `@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) 完成本篇后，你已经拥有了稳定的基础开发环境。接着让我们通过真实业务组件把 Tailwind CSS 4 的能力串联起来。 --- ## 进阶篇：用 Tailwind CSS 4 构建真实页面 基础环境搭建完成后，真正的挑战来自“如何把抽象的原子类应用到真实业务”。本篇精选小程序常见的页面模块，结合 `tailwindcss@4` 的新指令，总结出一套从设计拆解到代码落地的流程。 ## 工具优先的心智模型 Tailwind CSS 的核心不在于背公式，而是把 UI 拆成「布局」「排版」「状态」三个维度，然后使用类名组合快速拼装。Tailwind 4 进一步引入 `@theme`、`@utility` 等指令，让自定义能力与项目约束保持同步： - `@theme` 管理设计令牌：颜色、间距、字号、阴影等 - `@utility` 声明可复用的工具类，代替传统的 `.btn { ... }` - `@variant` / `@custom-variant` 管理状态类（如 `active:`、`dark:`） 掌握这些指令后，就可以在不离开 CSS 语法的前提下扩展 Tailwind。 ## 1. 拆解一个卡片组件 以「订单卡片」为例，先在 `src/components/order-card/index.vue` 写出骨架： ```html title="src/components/order-card/index.vue" ``` 接下来在 `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`，若遇到覆盖问题，可以开启 `cssPresetEnv` 的降级行为，详情见 [高阶篇](/docs/quick-start/v4/tutorial/advanced)。 - 借助 `pnpm dev:h5`（部分框架提供）可快速在浏览器预览，调试完后再回到真机验证。 完成本篇后，你应该可以把 Tailwind 应用到实际业务模块，并形成一套可复用的组件写法。接下来，我们会关注性能优化、跨端适配与团队协作等更高阶的话题。 --- ## HBuilderX --- ## uni-app cli vue3 vite(V4) ## 1. 安装 ```bash npm2yarn npm install -D tailwindcss @tailwindcss/postcss weapp-tailwindcss ``` ## 2. 配置 `vite.config.ts` ```ts title="vite.config.ts" export default defineConfig({ plugins: [ uni(), UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true, cssEntries: [ // 你 @import "tailwindcss"; 那个文件绝对路径 path.resolve(import.meta.dirname, './src/app.css'), ], }), ], css: { postcss: { plugins: [ tailwindcss(), ], }, }, }); ``` > tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。 ## 3. 添加样式 接着直接运行 `npm run dev:mp-weixin`， 微信开发者工具导入这个项目，即可看到效果 {/* :::warning 这里必须创建一个额外的 `css` 文件，而不是直接在 `App.vue` 里的 `style` 标签下直接写， 这是因为 `@tailwindcss/vite` 目前只转化 `.css` 文件。后续可能会支持更多格式的文件，比如 `vue` 编译的中间文件 详见 http://github.com/tailwindlabs/tailwindcss/blob/main/packages/%40tailwindcss-vite/src/index.ts#L122 中的 `isCssFile` 判断 ::: */} ## 参考模板 [uni-app-tailwindcss-v4](https://github.com/icebreaker-template/uni-app-tailwindcss-v4) --- ## uni-app cli vue2 webpack(V4) ## 安装 ```bash npm2yarn npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss ``` ## 配置 ### 创建 `vue.config.js` ```js title="vue.config.js" const { UnifiedWebpackPluginV5 } = 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 UnifiedWebpackPluginV5({ rem2rpx: true, cssEntries: [ // 你 @import "tailwindcss"; 那个文件绝对路径 path.resolve(__dirname, './src/app.css'), ], }) ) } // other option... } module.exports = config ``` > tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。 ## 配置 `postcss.config.js` ```js title="postcss.config.js" const path = require('path') const webpack = require('webpack') const config = { parser: require('postcss-comment'), plugins: [ // highlight-next-line require('@tailwindcss/postcss')(), // 只添加这一行 require('postcss-import')({ resolve (id, basedir, importOptions) { if (id.startsWith('~@/')) { return path.resolve(process.env.UNI_INPUT_DIR, id.substr(3)) } else if (id.startsWith('@/')) { return path.resolve(process.env.UNI_INPUT_DIR, id.substr(2)) } else if (id.startsWith('/') && !id.startsWith('//')) { return path.resolve(process.env.UNI_INPUT_DIR, id.substr(1)) } return id } }), require('autoprefixer')({ remove: process.env.UNI_PLATFORM !== 'h5' }), require('@dcloudio/vue-cli-plugin-uni/packages/postcss') ] } if (webpack.version[0] > 4) { delete config.parser } module.exports = config ``` ## 添加样式 然后直接运行到小程序，微信开发者工具导入这个项目，即可看到效果 ## 参考模板 https://github.com/icebreaker-template/uni-app-webpack-tailwindcss-v4 --- ## uni-app x :::warning tailwindcss@4 版本，暂时只支持 hbuilderx uni-app x 跨 `h5` 和 `小程序` 平台， 原生安卓和IOS平台无法支持，因为 uni-app x 目前对 css 各种现代语法的兼容较差，兼容不了 tailwindcss@4 生成的样式 未来此功能的适配，取决于 uni-app x 团队对现代 css 的兼容程度 (2025-07-27) ::: --- ## Weapp-vite ## 安装 ```bash npm2yarn npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss ``` ## 配置 更改 `vite.config.ts` 注册 `weapp-tailwindcss` ```js title="vite.config.ts" export default defineConfig({ plugins: [ UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true, cssEntries: [ // app.css 的路径 path.resolve(import.meta.dirname, './app.css'), ], }), ], }) ``` 添加 `postcss.config.js` 注册 `@tailwindcss/postcss` ```js title="postcss.config.js" export default { plugins: { '@tailwindcss/postcss': {}, }, } ``` ## 添加样式 在项目目录下，小程序全局的 `app.css` 中，添加以下内容： ```css title="app.css" @import "tailwindcss"; ``` 更改好配置之后，直接启动即可 --- ## wxs的转义与处理 :::info `2.5.2+` 版本中，已经添加了对 `wxs`,`sjs`等视图层运行 `js` 的转义和处理，默认关闭 具体见配置项: - [`wxsMatcher`](/docs/api/interfaces/UserDefinedOptions#wxsmatcher) - [`inlineWxs`](/docs/api/interfaces/UserDefinedOptions#inlinewxs) ::: --- ## weapp-tw CLI 使用指南 `weapp-tailwindcss` 自带一个 `weapp-tw` 命令行工具，负责提前给 Tailwind CSS 打补丁、生成类名缓存以及收集 token。以下内容介绍常用命令及最佳实践。 ## 常见场景 | 场景 | 命令 | 说明 | | --- | --- | --- | | 给 Tailwind CSS 打补丁、注入 `rpx` 支持 | `npx weapp-tw patch` | 运行一次即可，推荐写在 `postinstall`；支持 `--cwd` 指向子包目录。 | | 强制刷新补丁缓存后再打补丁 | `npx weapp-tw patch --clear-cache` | 默认不会清理缓存；仅在怀疑缓存导致补丁未生效或版本不一致时使用。 | | 在 monorepo 针对子包补丁 | `pnpm --filter exec weapp-tw patch --cwd .` | `pnpm` 场景建议显式传 `--cwd .`，每个子包只写入自己的缓存，避免 hoist 后的 `node_modules` 不一致。 | | 一键扫描 workspace 并补丁 | `weapp-tw patch --workspace --cwd ` | 自动读取 `pnpm-lock.yaml`/`pnpm-workspace.yaml` 批量补丁，跳过未安装 Tailwind 的包，并输出每个子包状态。 | | 查看补丁应用/缺失情况 | `npx weapp-tw status --json` | 复用 `tailwindcss-patch` 的状态检查，输出各补丁是否已应用，可配合 `--cwd` 指定子包。 | | 收集 Tailwind 产出的类名缓存 | `npx weapp-tw extract --css src/app.css` | 适用于 Tailwind v3/v4，v4 需传入 `--css`，生成 `.tw-patch/tw-class-cache.*`，支持 `--output`/`--format`。 | | 输出 Tailwind token 和定位信息 | `npx weapp-tw tokens --format grouped-json` | 调试 `content` 配置时非常有用，可与 `--no-write` 一起纯输出。 | ## `patch` 子命令 ### 功能 - 扫描当前工作目录所依赖的 `tailwindcss`，给其打上 `rpx` 单位补丁。 - 暴露 Tailwind 运行时上下文，供 `webpack`/`vite`/`gulp` 插件复用。 - 检测到未安装 Tailwind 时会输出中文警告。 ### 常用参数 | 参数 | 默认值 | 含义 | | --- | --- | --- | | `--cwd ` | `WEAPP_TW_PATCH_CWD` \| `INIT_CWD` \| `npm_config_local_prefix` \| 当前工作目录 | 指定要补丁的子包目录，等价于先 `cd`。默认会按顺序读取上述环境变量，避免在 `pnpm`/CI 里被 wrapper 覆盖成根目录。 | | `--record-target` | `true` | 默认记录本次打补丁对应的 `tailwindcss` 根路径到子包专属的 `node_modules/.cache/weapp-tailwindcss//tailwindcss-target.json`，包含 `cwd`、Tailwind 路径、补丁版本与时间戳；如需关闭请传 `--record-target false`。 | | `--clear-cache` | `false` | 按需清理 `tailwindcss-patch` 缓存目录后再执行补丁。默认不清理，避免不必要的 IO 和 CI 侧效应。 | | `--workspace` | `false` | 批量扫描 workspace（`pnpm-lock.yaml`/`pnpm-workspace.yaml`/`workspaces`），逐个子包执行 patch 并输出“补丁/跳过/失败”状态。 | 默认会记录补丁目标，运行日志类似： ```bash $ pnpm --filter demo/native-mina weapp-tw patch weapp-tw patch 绑定 Tailwind CSS -> ./node_modules/tailwindcss (v3.4.18) 记录 weapp-tw patch 目标 -> ./node_modules/.cache/weapp-tailwindcss//tailwindcss-target.json Tailwind CSS 运行时补丁已完成。 ``` 随后每次启动构建工具，运行时会输出 `tailwindcss-patcher 绑定 Tailwind CSS -> ...`；若检测到与缓存记录不一致，会自动重打补丁并刷新记录，无需手动清理跨包告警。若不希望生成记录，可在命令后追加 `--record-target false`。补丁记录按子包（package.json 路径 hash）隔离，避免 `pnpm` hoist 或 `workspace:` 互相引用时互相覆盖。 ## `extract` 子命令 ```bash npx weapp-tw extract --css src/app.css --format lines ``` - `--css`：Tailwind 入口 CSS。v4 必填；v3 可省略以沿用 Tailwind 默认入口。 - `--output`：指定输出文件，默认写入 `.tw-patch/tw-class-cache.json`。 - `--format`：`json`/`lines`，配合 `--no-write` 可仅打印到终端。 - `--cwd` 与 `patch` 一致，也支持放在子包里执行。 生成的缓存可以让构建器快速读取 `tailwindcss` 编译结果，减少重复启动的开销。 ## `tokens` 子命令 ```bash npx weapp-tw tokens --format grouped-json --group-key absolute ``` - `--format`：`json`、`lines` 或 `grouped-json`。后一种会按文件分组，便于排查 `content` 匹配不到的问题。 - `--group-key`：`relative`(默认)/`absolute`，决定输出路径的基准。 - `--no-write`：终端预览，不落盘；默认写入 `.tw-patch/tw-token-report.json`。 输出的数据包含扫描到的文件、类名 token、出现位置（行列）、以及被跳过的文件列表。 ## `status` 子命令 ```bash npx weapp-tw status --cwd demo/native-mina npx weapp-tw status --json ``` - 复用 `tailwindcss-patch` 的状态检查，按补丁列出 `applied`/`not-applied`/`skipped`/`unsupported`。 - `--cwd`：指定要检查的子包目录，默认沿用 `patch` 的自动推断。 - `--json`：输出 JSON 报告，方便 CI 或脚本读取。 ## 快速排查指引 1. **始终在子包目录执行 `weapp-tw patch`**：`pnpm --filter my-demo weapp-tw patch --cwd demo/my-demo`。 2. **如确实不需要追踪，可传 `--record-target false`**，避免生成额外 JSON。 3. **看到自动重补丁/记录迁移提示**：确认日志里的 Tailwind 路径与子包一致，`pnpm --filter ... exec weapp-tw patch --cwd .` 或 `weapp-tw patch --workspace --cwd ` 可避免 `INIT_CWD` 导致的跨包记录污染。 4. **类名缺失**： 用 `weapp-tw extract` 或 `weapp-tw tokens --no-write` 辅助定位是哪段代码没有被 Tailwind `content` 收录。 5. **需要强制指定根目录时**：在 monorepo 根执行 `WEAPP_TW_PATCH_CWD=$PWD weapp-tw patch --workspace`，可覆盖外层脚本设置的 `INIT_CWD`，确保一次性为所有子包补丁并写入各自的缓存记录。 配合这些命令，可以更直观地观察 Tailwind 依赖解析与补丁状态，减少“rpx 被当成颜色” 等由于上下游不一致导致的问题。 --- ## uni-app x 专题 跨端原子化样式方案 Tailwind CSS × uni-app x 一键使用模板项目（推荐） 或者按步骤手动集成 ## 这篇文档适合谁 - 想在 uni-app x 项目里使用 Tailwind CSS 的开发者 - 需要一套能同时覆盖 Web/小程序/Android/iOS/鸿蒙 的原子化样式方案 - 希望以最少的改动尽快起步，并有清晰的后续扩展路线 ## 你将收获什么 - 完整的从 0 到 1 集成流程（含运行与验证） - 可复用的模板项目与配置清单 - 多端开发的实践建议与避坑说明 :::info 支持范围 当前跨端集成仅支持 `tailwindcss@3.x`。 `tailwindcss@4.x` 生成的 CSS 依赖诸多现代特性，`uni-app x` 暂未全部覆盖，故不建议在该场景使用 v4。 ::: ## 最快开始 - 想最快跑起来：点击上方「一键使用模板项目」，按 README 步骤打开 HBuilderX 运行即可 - 想了解每一步：前往「手动集成」教程 → 快速集成 ## 开发建议（从用户出发） - 推荐编辑器协作：用 VS Code 写代码，用 HBuilderX 负责运行与构建 - 首选 Android 端调试：CSS 兼容度一般是 Web > 小程序 > App（Android/iOS/鸿蒙）。先用 Android 模拟器打通路径，跨端成本最低 - 组件语义注意：原生 App 端文字需放在 `` 标签，且文本样式需要直接作用在该元素上 - 渐进增强：若某些样式在 App 端受限，优先保证 Android 端体验，再按需做条件编译适配小程序/Web ## 为什么推荐先用 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` 尚无 CLI，需通过 HBuilderX 进行运行与构建。 建议配合 Android 模拟器进行开发调试。 ## 接下来 - 跟着步骤手动完成集成：快速集成 - 直接基于模板起步：uni-app x + Tailwind 模板（HBuilderX） --- ## 快速集成 ## 最简单：直接用模板项目（推荐） 立即上手而不纠结配置细节，点击下面链接即可： 使用模板一键开始 打开后按 README 步骤，用 HBuilderX 运行到 Android 模拟器或真机即可看到效果。 --- ## 手动集成（由浅入深） 你也可以按下面步骤，从零开始完成配置。 ### 前置条件 - 已安装最新 HBuilderX - 安装 Node.js（建议 ≥ 18） - 建议准备 Android 模拟器（或真机），便于快速验证 ### 1) 创建项目 在 HBuilderX 中创建一个全新的 `uni-app x` 项目；随后在项目根目录初始化 `package.json`： ```bash npm2yarn npm init -y ``` > 也可以手动创建 `package.json` 文件。 ### 2) 安装并引入 Tailwind CSS 3 ```bash npm2yarn # 安装 tailwindcss@3 所需依赖 npm i -D tailwindcss@3 postcss autoprefixer ``` ```bash npm2yarn # 初始化 Tailwind 配置文件 npx tailwindcss init ``` 在应用入口 `App.uvue` 中全局引入： ```html title="App.uvue" ``` ### 3) 安装 weapp-tailwindcss 并添加补丁脚本 ```bash npm2yarn npm i -D weapp-tailwindcss ``` 在 `package.json` 中增加 `postinstall` 脚本： ```json title="package.json" { "scripts": { // highlight-next-line "postinstall": "weapp-tw patch" } } ``` > 了解原因可阅读：weapp-tailwindcss 使用说明 ### 4) 在 uni-app x 中注册 weapp-tailwindcss 先创建一个简单的路径工具函数，方便在配置里引用绝对路径： ```js title="shared.js" const path = require('node:path') function r(...args) { return path.resolve(__dirname, ...args) } module.exports = { r } ``` 创建 `vite.config.ts` 并注册插件（注意 `uniAppX` 预设来自 `weapp-tailwindcss/presets`）： ```js title="vite.config.ts" export default defineConfig({ plugins: [ uni(), UnifiedViteWeappTailwindcssPlugin( uniAppX({ base: __dirname, rem2rpx: true, }), ), ], css: { postcss: { plugins: [ tailwindcss({ config: r('./tailwind.config.js'), }), ], }, }, }) ``` ### 5) 配置 Tailwind 使用绝对路径包含所有需要提取原子类的文件： ```js title="tailwind.config.js" const { r } = require('./shared') /** @type {import('tailwindcss').Config} */ module.exports = { content: [ r('./pages/**/*.{uts,uvue}'), r('./components/**/*.{uts,uvue}'), ], corePlugins: { // 由 uni-app x 提供基础样式，这里关闭 preflight 避免冲突 preflight: false, }, } ``` 如需从更多目录提取样式，按需扩展 `content` 的 glob。 ### 6) 运行与验证 - 在 HBuilderX 中点击「运行」并选择目标平台（推荐 Android 模拟器/真机） - 新建/打开任意页面，写入示例类名验证： ```html Hello Tailwind on uni-app x ``` ### 7) 编辑器智能提示（可选） VS Code 配合插件体验最佳。为 Tailwind 扩展增加语言映射，让其识别 `uvue/uts`： ```json title=".vscode/settings.json" { "tailwindCSS.includeLanguages": { "uvue": "html", "uts": "javascript" } } ``` 同时安装官方语言服务插件（ID: dcloud-ide.hbuilderx-language-services）以获得完整语法支持。 --- ## 重要说明与限制 - 仅推荐在 `tailwindcss@3.x` 下跨端使用（v4 在该场景下暂不兼容） - 原生 App 端对文本与部分 CSS 特性有约束：文本使用 `` 元素，且样式需直接作用其上 - 如遇到 HBuilderX 控制台 CSS 警告，请按提示做兼容性调整或采用条件编译