Skip to content

API_TOKEN_IMPLEMENTATION.md

Latest commit

 

History

History
274 lines (212 loc) · 6.39 KB

API_TOKEN_IMPLEMENTATION.md

File metadata and controls

274 lines (212 loc) · 6.39 KB

API Token 实现文档

🎯 目标

允许用户通过 Claude Code 直接发布技能到 SkillCode.cc 平台。

📋 完整流程

1. 用户登录 skillcode.cc
   ↓
2. 进入个人中心，生成 API Token
   ↓
3. 保存 Token 到本地配置（~/.skillcode/config.json）
   ↓
4. 在 Claude Code 中：告诉 Claude "发布技能到 skillcode.cc"
   ↓
5. Claude 读取本地技能文件和配置
   ↓
6. Claude 调用 API 上传技能（使用 Bearer Token 认证）
   ↓
7. 返回技能链接：skillcode.cc/[code]

🏗️ 技术实现

1. 数据库层

新增表：api_tokens

CREATE TABLE public.api_tokens (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES profiles(id),
  token TEXT UNIQUE NOT NULL,          -- 格式: sk_xxxxx
  name TEXT NOT NULL,                  -- Token 名称
  last_used_at TIMESTAMP,              -- 最后使用时间
  expires_at TIMESTAMP,                -- 过期时间（可选）
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

关键函数

  • verify_api_token(token_string) - 验证 Token 并返回用户 ID
  • generate_api_token() - 生成格式为 sk_xxxxx 的随机 Token

2. 认证层

文件：lib/auth/verify-token.ts

双重认证支持：

export async function verifyAuth(request: Request) {
  // 方式 1: Bearer Token（API 调用）
  if (request.headers.get('Authorization').startsWith('Bearer ')) {
    // 验证 API Token
  }

  // 方式 2: Session Cookie（浏览器登录）
  // 验证 Supabase Session
}

3. API 层

修改的端点

POST /api/skills - 创建技能

  • ✅ 已支持 Bearer Token 认证
  • ✅ 已支持 Session Cookie 认证

新增端点

GET /api/tokens - 获取用户的所有 Tokens

curl https://skillcode.cc/api/tokens \
  -H "Cookie: supabase-auth-token=xxx"

POST /api/tokens - 创建新 Token

curl -X POST https://skillcode.cc/api/tokens \
  -H "Cookie: supabase-auth-token=xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My MacBook", "expiresInDays": 90}'

DELETE /api/tokens/[id] - 删除 Token

curl -X DELETE https://skillcode.cc/api/tokens/[token-id] \
  -H "Cookie: supabase-auth-token=xxx"

4. Claude Code Skill

文件位置

publish-to-skillcode-skill/
├── SKILL.md          # Skill 定义和说明
└── README.md         # 使用文档

工作流程

  1. 用户说："发布我的技能到 skillcode.cc"
  2. Claude 执行： 
    # 读取配置
cat ~/.skillcode/config.json

# 读取技能文件
cat SKILL.md
cat README.md
# ... 其他文件

# 打包并上传
curl -X POST https://skillcode.cc/api/skills \
  -H "Authorization: Bearer sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{...}'
  3. 返回结果：技能已发布！链接：skillcode.cc/abc123

📁 已创建的文件

SQL 脚本

  • ✅ skillcode/supabase/add-api-tokens.sql - 创建 Token 表和函数

代码文件

  • ✅ skillcode/lib/auth/verify-token.ts - Token 验证工具
  • ✅ skillcode/app/api/tokens/route.ts - Token CRUD API
  • ✅ skillcode/app/api/tokens/[id]/route.ts - 删除 Token API
  • ✅ skillcode/app/api/skills/route.ts - 已修改支持 Token

Skill 文件

  • ✅ publish-to-skillcode-skill/SKILL.md - Skill 定义
  • ✅ publish-to-skillcode-skill/README.md - 使用说明

🚀 部署步骤

步骤 1: 执行 SQL（创建 Token 表）

在 Supabase SQL Editor 中执行：

skillcode/supabase/add-api-tokens.sql

步骤 2: 部署代码到 Vercel

cd /Users/xllin/小异空间/coding/skillshare
git add .
git commit -m "feat: 添加 API Token 认证功能

- 创建 api_tokens 表
- 实现 Bearer Token 认证
- 添加 Token 管理 API
- 创建 publish-to-skillcode skill

用户现在可以通过 Claude Code 直接发布技能！"
git push

Vercel 会自动部署。

步骤 3: 测试功能

# 1. 手动创建一个测试 Token（临时，直接在数据库）
INSERT INTO api_tokens (user_id, token, name)
VALUES (
  '00000000-0000-0000-0000-000000000001',
  'sk_test123456789',
  'Test Token'
);

# 2. 测试 API
curl -X POST https://skillcode.cc/api/skills \
  -H "Authorization: Bearer sk_test123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Skill",
    "description": "Testing API Token auth",
    "files": [{"path": "test.md", "content": "test", "type": "file"}]
  }'

🔒 安全考虑

  1. Token 格式: sk_ 前缀 + 32 位随机字符
  2. 存储: Token 明文存储（因为需要验证）
  3. 传输: 只通过 HTTPS
  4. 过期: 支持设置过期时间
  5. 撤销: 用户可随时删除 Token
  6. 审计: 记录最后使用时间

📊 数据流

Claude Code (本地)
    ↓
    POST /api/skills
    Authorization: Bearer sk_xxxxx
    ↓
Vercel (Next.js API)
    ↓
verifyAuth(request)
    ↓
Supabase.rpc('verify_api_token')
    ↓
返回 user_id
    ↓
创建技能 (author_id = user_id)
    ↓
返回技能链接

🎓 用户使用指南

对于技能创建者

  1. 访问 skillcode.cc
  2. 登录（暂时需要手动创建账号，后续会添加 OAuth）
  3. 个人中心 → 生成 API Token
  4. 保存到 ~/.skillcode/config.json
  5. 使用 Claude Code 发布技能

对于技能使用者

  1. 在社交媒体看到技能链接
  2. 访问 skillcode.cc/[code]
  3. 复制安装链接
  4. 告诉 Claude: "安装 skillcode.cc/[code]"
  5. Claude 自动下载并安装

✅ 当前状态

  • ✅ API Token 表和函数已创建
  • ✅ 认证逻辑已实现
  • ✅ Token 管理 API 已完成
  • ✅ Skill 文件已创建
  • ⏳ 需要执行 SQL 创建表
  • ⏳ 需要部署代码到 Vercel
  • ⏳ 需要实现用户登录（OAuth）
  • ⏳ 需要创建个人中心页面

🔜 后续工作

  1. 立即做:

    • 执行 SQL 创建 Token 表
    • 提交并部署代码

  2. 短期:

    • 实现 Google/GitHub OAuth 登录
    • 创建个人中心页面（显示和管理 Token）

  3. 中期:

    • 完善 publish-to-skillcode skill
    • 添加更详细的错误处理
    • 创建使用教程视频

📝 注意事项

  • Token 生成后只显示一次，用户需要立即复制保存
  • Token 删除后立即失效，无法恢复
  • 用户可以创建多个 Token（用于不同设备）
  • 管理员可以查看所有 Token 使用情况（用于监控）

实现完成度: 90%（核心功能完成，需要部署和测试）