secondme-reference

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SecondMe API 技术参考

SecondMe API Technical Reference

本文档包含 SecondMe API 的完整技术参考信息,供开发时查阅。

This document contains complete technical reference information for the SecondMe API, for reference during development.

API 基础 URL

API Base URL

https://app.mindos.com/gate/lab

https://app.mindos.com/gate/lab

OAuth2 授权 URL

OAuth2 Authorization URL

https://go.second.me/oauth/

https://go.second.me/oauth/

OAuth2 流程

OAuth2 Flow

1. 用户点击登录 → 跳转到 SecondMe 授权页面
2. 用户授权 → 重定向回你的应用(带 authorization_code)
3. 后端用 code 换取 access_token 和 refresh_token
4. 使用 access_token 调用 SecondMe API
5. Token 过期时使用 refresh_token 刷新

1. User clicks Login → Redirect to SecondMe authorization page
2. User authorizes → Redirect back to your application (with authorization_code)
3. Backend exchanges code for access_token and refresh_token
4. Call SecondMe API using access_token
5. Refresh with refresh_token when Token expires

Token 有效期

Token Validity Period

Token 类型前缀有效期
授权码
lba_ac_
5 分钟
Access Token
lba_at_
2 小时
Refresh Token
lba_rt_
30 天

Token TypePrefixValidity Period
Authorization Code
lba_ac_
5 minutes
Access Token
lba_at_
2 hours
Refresh Token
lba_rt_
30 days

权限列表(Scopes)

Permission List (Scopes)

权限说明
user.info
用户基础信息
user.info.shades
用户兴趣标签
user.info.softmemory
用户软记忆
note.add
添加笔记
chat
聊天功能
chat
结构化动作判断(Act)

ScopeDescription
user.info
Basic user information
user.info.shades
User interest tags
user.info.softmemory
User soft memory
note.add
Add notes
chat
Chat functionality
chat
Structured action judgment (Act)

API 响应格式与处理

API Response Format and Handling

重要:所有 SecondMe API 响应都遵循统一格式:
json
{
  "code": 0,
  "data": { ... }  // 实际数据在 data 字段内
}
前端代码必须正确提取数据:
typescript
// 注意:以下 /api/secondme/... 是 Next.js 本地路由(由 secondme-nextjs skill 生成),
// 本地路由会代理请求到上游 SecondMe API,并透传上游的响应格式。

// ❌ 错误写法 - 直接使用响应会导致 .map is not a function
const response = await fetch('/api/secondme/user/shades');  // Next.js 本地路由
const shades = await response.json();
shades.map(item => ...)  // 错误!

// ✅ 正确写法 - 提取 data 字段内的数据
const response = await fetch('/api/secondme/user/shades');  // Next.js 本地路由
const result = await response.json();
if (result.code === 0) {
  const shades = result.data.shades;  // 正确!
  shades.map(item => ...)
}

Important: All SecondMe API responses follow a unified format:
json
{
  "code": 0,
  "data": { ... }  // Actual data is in the data field
}
Frontend code must extract data correctly:
typescript
// Note: The following /api/secondme/... is a Next.js local route (generated by secondme-nextjs skill),
// which proxies requests to the upstream SecondMe API and passes through the upstream response format.

// ❌ Wrong approach - Directly using the response will cause .map is not a function
const response = await fetch('/api/secondme/user/shades');  // Next.js local route
const shades = await response.json();
shades.map(item => ...)  // Error!

// ✅ Correct approach - Extract data from the data field
const response = await fetch('/api/secondme/user/shades');  // Next.js local route
const result = await response.json();
if (result.code === 0) {
  const shades = result.data.shades;  // Correct!
  shades.map(item => ...)
}

各 API 的数据路径

Data Paths for Each API

以下路径均为上游 SecondMe API 路径,完整 URL =
{base_url}/api/secondme{path}
其中
base_url
来自
state.api.base_url
(默认
https://app.mindos.com/gate/lab
上游 API 路径数据路径类型
/api/secondme/user/info
result.data
object(含 email, name, avatarUrl, route 等字段)
/api/secondme/user/shades
result.data.shades
array
/api/secondme/user/softmemory
result.data.list
array
/api/secondme/chat/session/list
result.data.sessions
array
/api/secondme/chat/session/messages
result.data.messages
array
/api/secondme/act/stream
SSE 流式 JSON(需拼接 delta)SSE stream
/api/secondme/note/add
result.data.noteId
number

The following paths are upstream SecondMe API paths, complete URL =
{base_url}/api/secondme{path}
Where
base_url
comes from
state.api.base_url
(default
https://app.mindos.com/gate/lab
)
Upstream API PathData PathType
/api/secondme/user/info
result.data
object (contains fields like email, name, avatarUrl, route, etc.)
/api/secondme/user/shades
result.data.shades
array
/api/secondme/user/softmemory
result.data.list
array
/api/secondme/chat/session/list
result.data.sessions
array
/api/secondme/chat/session/messages
result.data.messages
array
/api/secondme/act/stream
SSE streaming JSON (needs delta concatenation)SSE stream
/api/secondme/note/add
result.data.noteId
number

Act API(结构化动作判断)

Act API (Structured Action Judgment)

Act API 是独立于 Chat API 的接口,约束模型仅输出合法 JSON 对象,适用于情感分析、意图分类等结构化决策场景。权限使用
chat
scope。
The Act API is an interface independent of the Chat API, which restricts the model to output only valid JSON objects. It is suitable for structured decision-making scenarios such as sentiment analysis and intent classification. It uses the
chat
scope for permissions.

端点(上游 API)

Endpoint (Upstream API)

POST {base_url}/api/secondme/act/stream
POST {base_url}/api/secondme/act/stream

请求参数

Request Parameters

参数类型必需说明
messagestring用户消息内容
actionControlstring动作控制说明(20-8000 字符),定义 JSON 结构与判断规则
appIdstring应用 ID
sessionIdstring会话 ID,不提供则自动生成
systemPromptstring系统提示词,仅新会话首次有效
ParameterTypeRequiredDescription
messagestringYesUser message content
actionControlstringYesAction control instructions (20-8000 characters), defining JSON structure and judgment rules
appIdstringNoApplication ID
sessionIdstringNoSession ID, automatically generated if not provided
systemPromptstringNoSystem prompt, only valid for the first time in a new session

actionControl 示例

actionControl Example

仅输出合法 JSON 对象,不要解释。
输出结构:{"is_liked": boolean}。
当用户明确表达喜欢或支持时 is_liked=true,否则 is_liked=false。
Only output valid JSON objects, no explanations.
Output structure: {"is_liked": boolean}.
Set is_liked=true when the user clearly expresses liking or support, otherwise is_liked=false.

响应格式(SSE)

Response Format (SSE)

event: session
data: {"sessionId": "labs_sess_xxx"}

data: {"choices": [{"delta": {"content": "{\"is_liked\": true}"}}]}

data: [DONE]
event: session
data: {"sessionId": "labs_sess_xxx"}

data: {"choices": [{"delta": {"content": "{\"is_liked\": true}"}}]}

data: [DONE]

前端处理示例

Frontend Handling Example

typescript
// 调用 Act API 进行结构化判断(通过 Next.js 本地路由代理到上游)
const response = await fetch('/api/secondme/act/stream', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: userMessage,
    actionControl: '仅输出合法 JSON。结构:{"intent": "like"|"dislike"|"neutral"}。根据用户表达判断意图。信息不足时返回 {"intent": "neutral"}。'
  })
});

// 拼接 SSE 流中的 delta content,最终 JSON.parse 得到结果
typescript
// Call Act API for structured judgment (proxied to upstream via Next.js local route)
const response = await fetch('/api/secondme/act/stream', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: userMessage,
    actionControl: 'Only output valid JSON. Structure: {"intent": "like"|"dislike"|"neutral"}. Judge intent based on user expression. Return {"intent": "neutral"} when information is insufficient.'
  })
});

// Concatenate delta content in the SSE stream, then JSON.parse to get the result

Chat vs Act 使用场景

Chat vs Act Usage Scenarios

场景使用 API原因
自由对话
/chat/stream
返回自然语言文本
情感/意图判断
/act/stream
返回结构化 JSON
是/否决策
/act/stream
返回
{"result": boolean}
多分类判断
/act/stream
返回
{"category": "..."}
内容生成
/chat/stream
需要长文本输出

ScenarioAPI to UseReason
Free conversation
/chat/stream
Returns natural language text
Sentiment/intent judgment
/act/stream
Returns structured JSON
Yes/no decision making
/act/stream
Returns
{"result": boolean}
Multi-category judgment
/act/stream
Returns
{"category": "..."}
Content generation
/chat/stream
Requires long text output

开发注意事项

Development Notes

State 参数

State Parameter

直接忽略
state
参数验证。
在回调处理时不需要验证 state,直接处理授权码即可。
Ignore the
state
parameter validation directly.
There is no need to validate the state during callback processing; just process the authorization code directly.

CSS @import 规则顺序

CSS @import Rule Order

重要: 在 CSS 文件中,
@import
语句必须放在文件的最开头(只能在
@charset
@layer
之后)。如果在其他 CSS 规则之后使用
@import
,会导致解析错误。
css
/* 正确写法 - @import 放在最前面 */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC&display=swap');

:root {
  --primary-color: #000;
}

/* 错误写法 - @import 不能放在其他规则之后 */
:root {
  --primary-color: #000;
}
@import url('...'); /* 这会报错! */

Important: In CSS files,
@import
statements must be placed at the very beginning of the file (only after
@charset
and
@layer
). Using
@import
after other CSS rules will cause parsing errors.
css
/* Correct approach - @import placed at the top */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC&display=swap');

:root {
  --primary-color: #000;
}

/* Wrong approach - @import cannot be placed after other rules */
:root {
  --primary-color: #000;
}
@import url('...'); /* This will cause an error! */

官方文档链接

Official Document Links