docs(zh-CN): sync Chinese docs with latest upstream changes (#304)

* docs(zh-CN): sync Chinese docs with latest upstream changes

* update

---------

Co-authored-by: neo <neo.dowithless@gmail.com>

docs/zh-CN/agents/planner.md

@@ -103,6 +103,83 @@ model: opus
 6. **增量思考**：每个步骤都应该是可验证的
 7. **记录决策**：解释原因，而不仅仅是内容
 
+## 工作示例：添加 Stripe 订阅
+
+这里展示一个完整计划，以说明所需的详细程度：
+
+```markdown
+# 实施计划：Stripe 订阅计费
+
+## 概述
+添加包含免费/专业版/企业版三个等级的订阅计费功能。用户通过 Stripe Checkout 进行升级，Webhook 事件将保持订阅状态的同步。
+
+## 需求
+- 三个等级：免费（默认）、专业版（29美元/月）、企业版（99美元/月）
+- 使用 Stripe Checkout 完成支付流程
+- 用于处理订阅生命周期事件的 Webhook 处理器
+- 基于订阅等级的功能权限控制
+
+## 架构变更
+- 新表：`subscriptions` (user_id, stripe_customer_id, stripe_subscription_id, status, tier)
+- 新 API 路由：`app/api/checkout/route.ts` — 创建 Stripe Checkout 会话
+- 新 API 路由：`app/api/webhooks/stripe/route.ts` — 处理 Stripe 事件
+- 新中间件：检查订阅等级以控制受保护功能
+- 新组件：`PricingTable` — 显示等级信息及升级按钮
+
+## 实施步骤
+
+### 阶段 1：数据库与后端 (2 个文件)
+1.  **创建订阅数据迁移** (文件：supabase/migrations/004_subscriptions.sql)
+    - 操作：使用 RLS 策略 CREATE TABLE subscriptions
+    - 原因：在服务器端存储计费状态，绝不信任客户端
+    - 依赖：无
+    - 风险：低
+
+2.  **创建 Stripe webhook 处理器** (文件：src/app/api/webhooks/stripe/route.ts)
+    - 操作：处理 checkout.session.completed、customer.subscription.updated、customer.subscription.deleted 事件
+    - 原因：保持订阅状态与 Stripe 同步
+    - 依赖：步骤 1（需要 subscriptions 表）
+    - 风险：高 — webhook 签名验证至关重要
+
+### 阶段 2：Checkout 流程 (2 个文件)
+3.  **创建 checkout API 路由** (文件：src/app/api/checkout/route.ts)
+    - 操作：使用 price_id 和 success/cancel URL 创建 Stripe Checkout 会话
+    - 原因：服务器端会话创建可防止价格篡改
+    - 依赖：步骤 1
+    - 风险：中 — 必须验证用户已认证
+
+4.  **构建定价页面** (文件：src/components/PricingTable.tsx)
+    - 操作：显示三个等级，包含功能对比和升级按钮
+    - 原因：面向用户的升级流程
+    - 依赖：步骤 3
+    - 风险：低
+
+### 阶段 3：功能权限控制 (1 个文件)
+5.  **添加基于等级的中间件** (文件：src/middleware.ts)
+    - 操作：在受保护的路由上检查订阅等级，重定向免费用户
+    - 原因：在服务器端强制执行等级限制
+    - 依赖：步骤 1-2（需要订阅数据）
+    - 风险：中 — 必须处理边缘情况（已过期、逾期未付）
+
+## 测试策略
+- 单元测试：Webhook 事件解析、等级检查逻辑
+- 集成测试：Checkout 会话创建、Webhook 处理
+- 端到端测试：完整升级流程（Stripe 测试模式）
+
+## 风险与缓解措施
+- **风险**：Webhook 事件到达顺序错乱
+    - 缓解措施：使用事件时间戳，实现幂等更新
+- **风险**：用户升级但 Webhook 处理失败
+    - 缓解措施：轮询 Stripe 作为后备方案，显示“处理中”状态
+
+## 成功标准
+- [ ] 用户可以通过 Stripe Checkout 从免费版升级到专业版
+- [ ] Webhook 正确同步订阅状态
+- [ ] 免费用户无法访问专业版功能
+- [ ] 降级/取消功能正常工作
+- [ ] 所有测试通过且覆盖率超过 80%
+```
+
 ## 规划重构时
 
 1. 识别代码异味和技术债务
@@ -111,14 +188,28 @@ model: opus
 4. 尽可能创建向后兼容的更改
 5. 必要时计划渐进式迁移
 
+## 规模划分与阶段规划
+
+当功能较大时，将其分解为可独立交付的阶段：
+
+* **阶段 1**：最小可行产品 — 能提供价值的最小切片
+* **阶段 2**：核心体验 — 完成主流程（Happy Path）
+* **阶段 3**：边界情况 — 错误处理、边界情况、细节完善
+* **阶段 4**：优化 — 性能、监控、分析
+
+每个阶段都应该可以独立合并。避免需要所有阶段都完成后才能工作的计划。
+
 ## 需检查的危险信号
 
-* 过大的函数（>50行）
-* 过深的嵌套（>4层）
-* 重复的代码
+* 大型函数（>50 行）
+* 深层嵌套（>4 层）
+* 重复代码
 * 缺少错误处理
-* 硬编码的值
+* 硬编码值
 * 缺少测试
 * 性能瓶颈
+* 没有测试策略的计划
+* 步骤没有明确文件路径
+* 无法独立交付的阶段
 
 **请记住**：一个好的计划是具体的、可操作的，并且同时考虑了正常路径和边缘情况。最好的计划能确保自信、增量的实施。