Skip to content

加上个人令牌和数据下载 - #142

Merged
JunieXD merged 1 commit into
mainfrom
agent-tokens
Nov 19, 2026
Merged

JunieXD merged 1 commit into
mainfrom
agent-tokens

Conversation

@JunieXD

@JunieXD JunieXD commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

关联

路线图 #2 三期的「Agent 接入」,这是第一步:个人令牌、开放 API 的认证和限额、数据下载、/llms.txt。MCP 服务(/mcp 和接 Codex、Claude Code 的命令)要加一个 MCP 的库,等维护者定了再做第二步。

改了什么

自己的 Agent 用个人令牌调鼠钟的接口,替本人查项目、订阅、记报名;登录后能下载一届的全部项目(总体设计 §13)。

  • api_tokens 表(迁移 0011),归 accounts 模块,只存 SHA-256;范围 read 只能查询,personal 还能订阅、关注、记报名、提反馈和修改申请
  • 带 Authorization: Bearer 的请求只按令牌认人。authorize 按令牌的范围放行:成员能读的 GET 算 read,个人操作标成 personal,别的(直接修改、审核、管理、管令牌)只认网页会话,带令牌返回 403 web_only
  • 每个令牌每分钟最多 60 次请求,超了返回 429 和 Retry-After;通过 Agent 每人 24 小时内最多提 10 条反馈,记录里标「通过 Agent」
  • 每人最多 10 个令牌,90 天没用过的失效;冻结了不能用,解冻后恢复;在鼠洞被封禁的,刷新时一起作废;有令牌的人也每小时从鼠洞刷新
  • 「我的」加「Agent」:生成令牌(只显示一次,附一段发给 Agent 的话:先读 /llms.txt,调接口带这个令牌)、列出和作废令牌、下载这一届
  • GET /export?cohort=&format=csv|json:CSV 只带总表那几列,UTF-8 加 BOM,像公式的文字保留成文字;JSON 带全部字段、证据和原文链接;和总表一样带 ETag。总表底部也有下载链接
  • /llms.txt:鼠钟是什么、有哪些页面、接口怎么认证、怎么下载,以及使用须知,放在 agents 模块
  • 报名时间的写法和类型的名称挪到服务端的 programs 模块,页面和 CSV 共用一份

怎么验证的

  • pnpm check:类型检查、lint、格式和 156 个测试通过;pnpm build 通过,pnpm db:codegen --verify 类型是最新的,pnpm openapi 后 openapi/crawler.json 没变。新测试覆盖:两种范围和只认网页会话的接口;认不出的令牌一律 401(带着 Cookie、在访客能读的接口上也一样),bearer 不分大小写;作废、90 天没用、冻结和鼠洞拒绝了的不能用;每人 10 个、每分钟 60 次;通过 Agent 的反馈记下来源、每天 10 条;鼠洞封禁后刷新时作废令牌;下载的 CSV(BOM、像公式的文字)、JSON、304 和访客 401
  • 在假鼠洞和本地库上走了一遍:生成令牌只显示一次,令牌和「发给 Agent 的话」都能一键复制;用 curl 带令牌查总表、订阅项目,管令牌和审核的接口返回 403 web_only,作废后返回 401;下载的 CSV 带 BOM、表头对;390px 宽下「我的」六个标签和令牌框都排得开
  • Codex 逐文件审查,报的这些都改了:鼠洞拒绝了的人在下次刷新前令牌还能用;认不出的令牌在访客能读的接口上被当成访客;Bearer 区分大小写;每分钟的计数只增不删;没有复制按钮;openapi.json 没写个人令牌的认证方式;api.md 和 /llms.txt 漏写了刷新和文件下载;范围的取值写了两份;测试依赖执行顺序
  • 没改的:同一处反复提反馈只算一条、并发时可能多出一条(都不会让审核的人多看);带令牌调退出登录不会删掉任何会话;last_used_at 并发时可能多写一次;CSV 也查了全部字段再丢掉(下载不常用,没测过耗时)。另一个跑检查的 Codex 被它的安全过滤拦下(内容涉及令牌),检查都由我自己跑了

影响

  • 表结构:新增 api_tokens,没有要补的旧数据
  • 接口:新增 GET、POST /me/tokens,DELETE /me/tokens/{id},GET /export;带 Bearer 的请求按个人令牌认人,新的错误码 401 invalid_token、403 token_scope、403 web_only、429 rate_limited、429 agent_feedback_limit。网页会话的行为不变
  • MCP 工具:还没有,第二步加;抓取节点不用改(它的令牌照旧,只在自己的接口上认)
  • 文档:api_tokens 的范围从 scopes 列改成一个 scope 列(personal 包含 read);api.md 去掉了没有定数、也没做的「按会话限制频率」

自己的 Agent 用个人令牌调鼠钟的接口,替本人查项目、订阅、记报名;登录后能下载一届的全部项目(总体设计 §13)。这是 Agent 接入的第一步,MCP 服务等定了用哪个库再做。

- api_tokens 表(迁移 0011),归 accounts 模块,只存 SHA-256;范围 read 只能查询,personal 还能订阅、关注、记报名、提反馈和修改申请
- 带 Authorization: Bearer 的请求只按令牌认人。authorize 按令牌的范围放行:成员能读的 GET 算 read,个人操作标成 personal,别的(直接修改、审核、管理、管令牌)只认网页会话;认不出的令牌一律 401,不当成访客
- 每个令牌每分钟最多 60 次请求,超了返回 429 和 Retry-After;通过 Agent 每人 24 小时内最多提 10 条反馈,记录里标「通过 Agent」
- 每人最多 10 个令牌,90 天没用过的失效;冻结了不能用,解冻后恢复;在鼠洞被封禁的马上不能用,刷新时一起作废;有令牌的人也每小时从鼠洞刷新
- 「我的」加「Agent」:生成令牌(只显示一次,附一段发给 Agent 的话,都能一键复制)、列出和作废令牌、下载这一届
- GET /export?cohort=&format=csv|json:CSV 只带总表那几列,UTF-8 加 BOM,像公式的文字保留成文字;JSON 带全部字段、证据和原文链接;和总表一样带 ETag。总表底部也有下载链接
- /llms.txt:鼠钟是什么、有哪些页面、接口怎么认证、怎么下载,以及使用须知,放在 agents 模块;openapi.json 写明个人令牌的认证方式
- 报名时间的写法和类型的名称挪到服务端的 programs 模块,页面和 CSV 共用一份
- api.md 写明令牌相关的错误码;会话的频率限制没有定数,也没有做,不再写
@JunieXD
JunieXD merged commit 50b3745 into main Nov 19, 2026
2 checks passed
@JunieXD
JunieXD deleted the agent-tokens branch November 19, 2026 21:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant