Frelink API v1

自动生成时间：2026-03-31 00:33:21 生成命令：php think api:doc --output docs/api-v1.md

Frelink 的 API 以 app/api/v1 为入口，当前更适合作为移动端、站点集成层和 agent 辅助能力的基础接口，而不是直接无约束开放的自动化控制面。

路由规则

• 默认路由格式：/api/{controller}/{function}
• 版本通过请求头 version 指定，默认值为 v1
• 例如：GET /api/Common/config

认证方式

• 登录态通过请求头 UserToken 传递
• 后台创建的 API 认证 token 可通过请求头 ApiToken 或 AccessToken 传递
• 当 token 绑定了用户 UID 时，可直接作为该用户的 API 登录态使用
• 敏感接口由控制器内部 needLogin 控制
• 当前建议为 agent 单独准备低权限账号，不直接复用管理员账号

关键请求头

• Content-Type: application/json
• version: v1
• UserToken: <token>

统一返回与错误码约定

• 成功时返回 code=1
• 失败时返回 code=0，并在 msg 中给出说明
• time 表示服务端返回时刻的 Unix 时间戳
• request_id 用于串联日志和排障
• error_code 仅在失败响应中返回，供程序侧做稳定分支判断
• data 承载接口实际数据
• 不同接口可能会在 data 中承载不同结构，调用前以具体接口为准

{
  "code": 1,
  "msg": "请求成功",
  "time": 1710000000,
  "request_id": "req_0123456789abcdef",
  "data": {}
}

{
  "code": 0,
  "msg": "参数错误",
  "time": 1710000000,
  "request_id": "req_0123456789abcdef",
  "error_code": "INVALID_REQUEST",
  "data": {}
}

认证兼容说明

• UserToken：面向普通用户登录态
• ApiToken：面向后台创建的 API 认证 token
• AccessToken：与 ApiToken 兼容的历史请求头
• 当 API 认证 token 绑定了用户 UID 后，/api 下需要登录的方法会自动按该用户身份放行

接口清单

Account

• 需要登录的方法：my

Article

• 需要登录的方法：publish, manager, remove_article

特殊返回说明

• /api/Article/publish

- 当命中文章审核时，接口仍返回 code=1。 - data.status 会返回 pending_review，并附带 data.approval_id。 - 调用方应把“发表成功,请等待管理员审核”视为待审成功，而不是发布失败。

Ask

Captcha

Column

• 需要登录的方法：my, apply, collect

Comment

• 需要登录的方法：save_comment, remove_comment

Common

• 需要登录的方法：set_vote, update_focus, get_access_key, upload, remove_attach, save_draft

Favorite

• 需要登录的方法：*

Inbox

• 需要登录的方法：*

Insight

• 需要登录的方法：summary, keywords, content_trends, topic_trends, topic_graph, opportunities, recommendations, publish_assist, weekly_execution, writing_workflow, agent_brief, agent_draft

Invitation

• 需要登录的方法：*

Notify

• 需要登录的方法：*

Page

Pay

• 需要登录的方法：createOrder, qrcode, balance

Permission

• 需要登录的方法：report

Question

• 需要登录的方法：publish, remove_answer, remove_question, manager, save_question_invite, answer_editor, save_answer, set_best_answer, remove_answer_comment

Rank

Reward

Topic

• 需要登录的方法：save_setting, create

特殊返回说明

• /api/Topic/create

- 当 create_topic_approval 生效时，创建话题会先进入审核队列。 - 待审场景返回 code=1，并在 data 中携带 status=pending_review 与 approval_id。 - 待审话题尚未产生正式 id，不能直接用于后续内容绑定。

User

• 需要登录的方法：my, save_profile, get_notify_config, logout, modify_password, integral, draft, remove_draft, verified, removeUser

Widget

爬虫与训练数据采集隐私声明

• 本站公开可访问的页面、摘要和接口响应，可能被搜索引擎、学术检索、通用爬虫以及 AI 数据采集工具访问，用于索引、摘要、分析或训练。
• 未经授权的采集不得绕过登录态、权限控制、限频策略或 robots.txt 等访问限制。
• 账号资料、私信、后台数据、未公开草稿、用户隐私字段以及任何受权限保护的内容，不应被采集、复制、再分发或用于训练数据集。
• 采集方应遵守适用法律法规，保留必要的审计与来源标记，并在触发高频访问时主动降频。
• 如需对公开内容进行批量数据采集、模型训练或商业再利用，请先获得站点运营方明确许可。

OpenAPI 导出

• 机器可读规范默认输出到 public/docs/api-v1.openapi.json
• 浏览器可直接访问 https://your-domain/docs/api-v1.openapi.json
• 生成命令：php think api:doc --format=openapi --output public/docs/api-v1.openapi.json

推荐的 agent 使用边界

• 允许：

- 搜索词采集与选题建议 - 内容健康巡检 - 发布后链接检查 - 收录状态巡检 - 低风险草稿生成 - 先调用 agent_brief 获取整合后的运营与写作上下文

• 不建议直接开放：

- 删除内容 - 修改权限 - 自动正式发布 - 无审批的生产运维操作

接入前建议

1. 为 agent 单独创建账号与权限组。
2. 先补齐接口 smoke test，再接入自动化发布流程。
3. 为发布、删除、推荐、置顶等动作记录审计日志。
4. 对登录、短信、发布、评论等接口增加限频与监控。

smoke test 建议

curl -H "version: v1" https://your-domain/api/Common/config
curl -H "version: v1" "https://your-domain/api/Common/search?q=frelink"
curl -H "version: v1" "https://your-domain/api/Question/index?page=1&page_size=5"
curl -H "version: v1" "https://your-domain/api/Article/index?page=1&page_size=5"
curl -H "version: v1" -H "UserToken: <token>" "https://your-domain/api/Insight/agent_brief?days=7&limit=3"
curl -H "version: v1" -H "UserToken: <token>" "https://your-domain/api/Insight/agent_brief?days=7&limit=3&format=markdown"
curl -H "version: v1" -H "UserToken: <token>" "https://your-domain/api/Insight/weekly_execution?days=7&limit=3"
curl -H "version: v1" -H "UserToken: <token>" "https://your-domain/api/Insight/weekly_execution?days=7&limit=3&format=markdown"
curl -H "version: v1" -H "UserToken: <token>" "https://your-domain/api/Insight/writing_workflow?mode=all&days=7&limit=3"
curl -X POST -H "version: v1" -H "Content-Type: application/json" \
  -d '{"event_type":"detail_view","item_type":"article","item_id":1,"visitor_token":"debug-token","source":"smoke_test"}' \
  https://your-domain/api/Insight/track

后续改造方向

• 增加 OpenAPI 文档
• 统一错误码规范
• 为 agent 提供只读巡检 token
• 为发布流程增加审批与回滚机制
• 为 Insight 增加后台面板与定时报表