> 核心功能: 本技能提供中文交互、化工作流场景等能力。

异常处理指南

问题1: Better Auth认证系统登录返回500错误

现象: 用户登录时返回500 Internal Server Error
原因: BETTER_AUTH_SECRET未配置或数据库连接失败
解决:
1. 检查 BETTER_AUTH_SECRET 环境变量是否配置（会话签名密钥）
2. 确认数据库连接字符串正确，数据库服务在线
3. 检查auth-schema.sql是否已执行，数据库表结构是否完整
4. 使用key-vault-manager查看密钥存储状态，确认密钥未过期
5. 查看Node.js应用日志，确认Better Auth初始化无报错

问题2: 调试医生定位到的根因在并发代码中

现象: Bug仅在并发场景下出现，单线程测试无法复现
原因: 竞态条件或死锁，需要并发调试技术
解决:
1. 调试医生切换到并发调试模式：Thread Sanitizer/线程转储/锁图分析
2. 使用条件等待策略：记录触发频率与条件，增加日志等待下次触发
3. 生成线程转储（jstack/Node.js --inspect），分析锁竞争情况
4. 使用git bisect定位引入并发Bug的提交
5. 修复后使用验证闭环：回归测试（先验证失败→修复后通过）+ 完整测试套件

问题3: 浏览器自动化频繁被封号

现象: 多账号浏览器自动化操作后，账号被平台封禁
原因: 浏览器指纹未隔离或操作频率过高，被平台检测到自动化行为
解决:
1. 确认每个账号使用独立的浏览器配置目录（profile_dir参数）
2. 确认每个账号使用独立的Cookie存储（会话隔离）
3. 增加操作间隔频率控制（模拟真人操作节奏）
4. 敏感操作走独立WebSocket直连CDP，执行反检测JS
5. 使用CDP探针验证反检测有效性
6. 先访问首页建立Session再执行搜索（Cookie预热）

问题4: 密钥保险箱审计日志查询缓慢

现象: 查询审计日志响应时间超过5秒
原因: 审计日志数据量大，未建立索引或未分区
解决:
1. 确认审计日志表已建立时间戳索引
2. 按月分区审计日志表，减少单次查询数据量
3. 定期归档180天前的审计日志到冷存储
4. 使用key-vault-manager的合规报告功能，按时间段生成摘要

问题5: OAuth登录回调URL不匹配

现象: Google OAuth登录回调时报redirect_uri_mismatch错误
原因: OAuth Provider配置的回调URL与应用实际URL不一致
解决:
1. 确认Google Cloud Console中配置的Authorized redirect URIs
2. 确认应用环境变量GOOGLE_REDIRECT_URI与配置一致
3. 开发环境使用localhost回调，生产环境使用域名回调
4. 国内环境替换为微信/支付宝/飞书/钉钉OAuth Provider
5. 使用Better Auth的genericOAuth插件配置自定义Provider

功能适用范围

认证架构限制

• Better Auth框架限制: 部分高级功能（如OIDC Provider模式）仍在迭代，企业SSO(SAML)配置复杂需IdP端配合
• WebAuthn兼容性: Passkey/WebAuthn在旧浏览器（IE、部分安卓WebView）不支持，需提供降级方案
• 安全测试边界: 本技能提供架构设计与配置模板，不替代完整的安全渗透测试
• 性能依赖LLM: 复杂权限策略可能需要人工审查，性能取决于底层LLM能力

调试医生限制

• 不适用于: 代码审查与静态分析（请使用lint工具）、自动化测试编写（请使用测试框架）、部署与发布管理（请使用CI/CD工具）、安全漏洞挖掘（请使用安全测试工具）、代码重构与性能优化（聚焦Bug修复）
• 间歇性Bug: 无法保证100%复现间歇性故障，需增加监控等待触发
• 多语言覆盖: 支持Python/JS/Go/Java/Rust主流语言，小众语言可能需要适配

浏览器助手限制

• 合规要求: 仅用于合法合规场景（自动化测试/RPA流程/合规多账号管理），禁止用于爬虫滥用、刷量、欺诈
• Chrome版本: 需要Chrome/Chromium浏览器，不支持Firefox/Safari
• 反检测边界: 反检测方案无法保证100%不被检测，平台检测技术持续升级
• 资源消耗: 多账号并行时内存消耗较大，建议单实例管理不超过20个账号

密钥管理限制

• 本地存储: 密钥存储在本地文件系统，不支持云端同步（安全考虑）
• 团队共享: 需要所有成员安装key-vault-manager，加密分发需手动确认
• 轮换窗口: 密钥轮换期间需双密钥兼容，轮换窗口内旧密钥仍有效

不适用场景

• 网络层安全（防火墙、WAF配置，属基础设施范畴）
• 数据库加密设计（属数据层安全）
• 代码漏洞扫描（属SAST/DAST工具职责）
• 物理安全与办公网络安全
• 监控告警系统搭建（请使用Prometheus/Grafana）
• 实时性要求<100ms的场景
• 需要完全离线运行的场景（LLM由Agent内置但部分API需网络）

疑问解答

Q1: Better Auth与NextAuth/Auth.js有何区别？

A: Better Auth提供更完整的开箱即用功能（2FA、组织管理、Passkey内置），TypeScript优先，数据库Schema透明可控；NextAuth更轻量，社区生态成熟。企业级场景优先Better Auth。

Q2: 调试医生的4阶段调试法适用于所有Bug吗？

A: 适用于复杂Bug、生产事故、间歇性故障、性能问题、并发问题。不适用于简单语法错误和UI样式微调（直接修改即可）。回归Bug可使用git bisect快速定位引入提交。

Q3: 反检测浏览器助手合规吗？

A: 本工具仅用于合法合规的浏览器自动化场景（自动化测试/RPA流程/合规多账号管理）。使用者需遵守各平台服务条款和当地法律法规，禁止用于爬虫滥用、刷量、欺诈等违规行为。

Q4: 密钥保险箱支持云端同步吗？

A: 不支持。出于安全考虑，密钥存储在本地文件系统，不支持云端同步。团队共享通过加密分发实现，需所有成员安装key-vault-manager。

Q5: 国内环境如何替代Google OAuth？

A: 接入微信开放平台（扫码登录）、支付宝开放平台、飞书登录、钉钉登录。Better Auth支持自定义OAuth Provider，使用genericOAuth插件配置。

安全

API Key零暴露原则

• 所有密钥（BETTER_AUTH_SECRET/OAuth Secret/JWT Secret/SMTP密码）通过环境变量注入
• Skill内零硬编码，所有密钥通过key-vault-manager统一管理
• 密码哈希强制：使用argon2（推荐）或bcrypt，禁止明文/MD5/SHA1存储
• 令牌安全：Access Token短有效期 + Refresh Token轮换 + httpOnly Cookie存储
• 密钥轮换：建议每90天轮换BETTER_AUTH_SECRET，提供轮换期间双密钥兼容
• 审计日志：记录登录、权限变更、组织操作、密钥操作等敏感行为，保留180天

认证安全防护

• OWASP Top 10: 注入防护 + XSS(CSP) + CSRF(SameSite+Token) + 速率限制
• 防暴力破解: 登录尝试5次/15分钟 + 账号锁定 + IP封禁
• 会话安全: 登录后重新生成会话ID（防会话固定攻击）
• 账号枚举防护: 统一响应消息"若账号存在，邮件已发送"
• 密码重置安全: 令牌时效性（15分钟）+ 一次性使用 + IP绑定

国内适配性

• OAuth Provider: 微信/支付宝/飞书/钉钉（替代Google/GitHub）
• 短信服务: 阿里云短信/腾讯云短信（替代Twilio）
• 邮件服务: 阿里云邮件推送/腾讯企业邮（替代SendGrid）
• 身份认证服务: 阿里云IDaaS/腾讯云身份管家（替代Auth0）
• 数据库: 达梦/人大金仓/TDSQL（替代MySQL/数据库）

• 浏览器: 360/搜狗浏览器（基于Chromium，兼容CDP协议）

技术创新

效率提升量化分析

# 安装和初始化
skill install plug-enterprise-security-suite
# 基本调用示例
skill execute plug-enterprise-security-suite --input "示例输入"

高级用法

# Python API调用示例
import requests
# 配置API端点
api_url = "http://localhost:8080/api/skills/plug-enterprise-security-suite"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
# 执行技能
response = requests.post(api_url, json={
    "input": "示例输入数据",
    "options": {"mode": "advanced"}
})
result = response.json()
print(result)

命令行批处理

# 批量处理多个输入
for file in *.csv; do
  skill execute plug-enterprise-security-suite --input "$file" --output "result_$file"
done

企业安全开发套件

> 认证架构、科学调试、浏览器反检测、密钥管理四大能力协同，覆盖企业安全开发全生命周期

能力清单

本Plug将企业安全开发拆解为4个独立又互补的能力域：认证安全架构师负责认证授权体系设计，调试医生负责Bug根因分析，反检测浏览器助手负责浏览器自动化稳定性，密钥保险箱负责敏感凭证安全管理。4个技能形成从架构设计到运行时调试到密钥保护的完整安全闭环。

包含技能

auth-security-architect (认证架构) ──设计安全体系──> 应用开发
         │                                            │
    生成密钥/凭证                                      │
         │                                            │
         v                                            v
key-vault-manager (密钥管理) <──存储/轮换/审计──> debug-doctor (调试排障)
         │                                            │
    管理API Key                                定位生产Bug根因
         │                                            │
         v                                            v
stealth-browser-assistant (浏览器自动化) <──自动化测试/验证──┘

• auth-security-architect 设计认证授权体系，生成OAuth Client Secret、JWT Secret等凭证
• key-vault-manager 安全存储auth-security-architect生成的所有凭证，支持轮换和审计
• debug-doctor 在安全系统运行时使用4阶段科学调试法定位Bug根因
• stealth-browser-assistant 为安全系统的E2E自动化测试提供反检测浏览器能力

使用时机

{
  "plug": "plug-enterprise-security-suite",
  "action": "execute_workflow | execute_single",
  "input": {
    "workflow": "full | auth_only | debug_only | stealth_only | vault_only",
    "auth_input": {
      "app_type": "B2C SaaS",
      "auth_methods": ["email_password", "google_oauth", "totp_2fa"],
      "tech_stack": "Next.js + better-auth + 数据库",
      "session_strategy": "database"
    },
    "debug_input": {
      "bug_description": "间歇性登录失败，约5%请求返回401",
      "environment": "production",
      "reproduction_steps": "随机出现，无法稳定复现",
      "logs": "..."
    },
    "stealth_input": {
      "action": "locate_element",
      "intent": "点击登录按钮",
      "url": "https://app.example.com/login",
      "fallback_selectors": ["#login-btn", "button[type=submit]"]
    },
    "vault_input": {
      "action": "store_key",
      "vault_id": "project_alpha",
      "key_name": "BETTER_AUTH_SECRET",
      "key_value": "***",
      "rotation_days": 90
    }
  },
  "options": {
    "format": "json",
    "verbose": true
  }
}

返回格式

{
  "status": "success",
  "plug": "plug-enterprise-security-suite",
  "results": [
    {
      "step": 1,
      "skill": "auth-security-architect",
      "status": "completed",
      "output": {
        "files": ["auth.ts", "auth-schema.sql", "LoginForm.tsx", "TwoFactorSetup.tsx"],
        "auth_methods": ["email_password", "google_oauth", "totp"],
        "session_strategy": "database",
        "rate_limit": "10 requests/minute"
      }
    },
    {
      "step": 2,
      "skill": "key-vault-manager",
      "status": "completed",
      "output": {
        "vault_id": "project_alpha",
        "keys_stored": 5,
        "rotation_configured": true,
        "audit_log_enabled": true
      }
    }
  ],
  "metadata": {
    "total_steps": 2,
    "duration_ms": 8000,
    "timestamp": "2026-07-29T10:00:00Z"
  }
}

运行环境

运行环境

• Agent平台: Claude Code / Cursor / Codex / Gemini CLI / Windsurf 等支持SKILL.md的任意Agent
• 操作系统: Windows / macOS / Linux
• 运行时: 需要Agent支持 exec（命令行执行）能力
• Node.js: 18+（认证安全架构师运行Better Auth必需）

依赖项