导航 SOP 创建者技能

创建标准操作程序（SOPs）-可重用的流程、集成、调试解决方案和工作流文档。

何时调用

当用户：

说“记录此解决方案”，“下次保存”
说“创建SOP”，“使其可重用”
解决了一个新问题并提到“不想再遇到这个问题”
设置集成并说“记录设置”
建立模式并提到“团队应该遵循这个”

不要调用如果：

创建任务文档（使用nav-task技能）
更新架构文档（不同目的）
简单的错误修复，没有可重用的模式

执行步骤

第1步：确定SOP类别

询问用户哪个类别（或从上下文中推断）：

类别：

集成 - 第三方服务设置
调试 - 常见问题和解决方案
开发 - 开发工作流、模式
部署 - 部署程序、CI/CD

示例：

“如何设置Stripe webhooks” → integrations/
“修复CORS错误” → debugging/
“测试认证路由” → development/
“部署到生产” → deployment/

第2步：确定SOP名称

如果用户提供了名称：

使用他们的名称（清理：小写，连字符）
示例：“Stripe Payment Setup” → “stripe-payment-setup”

如果没有提供名称：

从上下文中生成：{service}-{action}
示例：github-oauth-integration
示例：cors-proxy-errors

第3步：检查SOP是否已存在

检查类别中现有的SOPs：

ls .agent/sops/{category}/*.md 2>/dev/null

如果找到类似的SOP：

⚠️  找到类似的SOP：
   .agent/sops/{category}/{similar-name}.md

选项：
1. 阅读现有SOP（不要重复）
2. 更新现有SOP（添加到其中）
3. 创建新的SOP（足够不同）

你的选择 [1-3]：

第4步：生成SOP内容

从对话中创建SOP文档：

# {SOP标题}

**类别**：{integrations|debugging|development|deployment}
**创建**：{YYYY-MM-DD}
**最后更新**：{YYYY-MM-DD}

---

## 上下文

**何时使用此SOP**：
[描述此适用的场景]

**它解决的问题**：
[这个地址什么问题？]

**先决条件**：
- [需求1]
- [需求2]

---

## 问题

### 症状
[问题看起来像什么？]
- 错误消息：`{特定错误}`
- 行为：[意外行为]
- 影响：[什么坏了]

### 根本原因
[为什么会这样？技术解释]

---

## 解决方案

### 第1步：{行动}

**做这个**：
```bash
# 命令或代码
npm install stripe

为什么： [解释这个完成什么]

预期输出：

+ stripe@12.0.0
added 1 package

第2步：{下一个行动}

做这个：

// 代码示例
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

为什么： [解释]

配置：添加到.env：

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

第3步：{继续…}

…

完整示例

完整工作代码

文件：src/services/stripe.ts

import Stripe from 'stripe';

export class StripeService {
  private stripe: Stripe;

  constructor() {
    this.stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
      apiVersion: '2023-10-16',
    });
  }

  async createPaymentIntent(amount: number) {
    return await this.stripe.paymentIntents.create({
      amount: amount * 100, // 转换为分
      currency: 'usd',
    });
  }
}

文件：src/routes/webhook.ts

export async function handleStripeWebhook(req: Request, res: Response) {
  const sig = req.headers['stripe-signature'];

  try {
    const event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    // 处理事件
    switch (event.type) {
      case 'payment_intent.succeeded':
        // 处理成功的支付
        break;
    }

    res.json({ received: true });
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
}

测试

验证它是否有效

测试1：创建支付意向

curl -X POST http://localhost:3000/api/create-payment \
  -H "Content-Type: application/json" \
  -d '{"amount": 10}'

预期结果：

{
  "clientSecret": "pi_xxx_secret_yyy"
}

测试2：Webhook交付

stripe listen --forward-to localhost:3000/webhook

预期结果：

Ready! You are using Stripe API Version [2023-10-16]

预防

如何避免将来出现这个问题：

[预防策略1]
[预防策略2]

要警惕的红旗：

[警告标志1]
[警告标志2]

故障排除

问题：Webhook签名验证失败

症状：

错误：没有找到与预期签名匹配的签名

原因：Webhook密钥不匹配或正文已解析

修复：

// 使用原始正文进行Webhook验证
app.post('/webhook', express.raw({type: 'application/json'}), handleStripeWebhook);

问题：支付金额不正确

症状：收取了错误的金额

原因：忘记转换为分

修复：Stripe金额总是乘以100

维护说明

何时更新：

Stripe API版本更改
支付流程更改
添加了新的Webhook事件

所有者：[负责的团队或个人]

最后更新：{YYYY-MM-DD} 测试与：Stripe API v2023-10-16, Node.js v18+

导航SOP创建者 nav-sop