功能说明
Starlens 的核心目标是让 GitHub Stars 从普通收藏列表变成可搜索、可整理、可解释的个人知识库。
仓库同步
用户登录后，可以把 GitHub Stars 同步到自己的数据库。同步接口会使用 GitHub OAuth access token 调用 GitHub Star API，并按分页拉取全部收藏仓库。
同步会写入或更新以下字段：
| 数据 | 说明 |
|---|---|
| 仓库身份 | githubRepoId、fullName、ownerLogin、htmlUrl |
| 仓库元数据 | 描述、语言、主题、License、默认分支、主页、可见性 |
| 活跃度指标 | Stars、Forks、Watchers、Open Issues |
| 时间字段 | GitHub 创建、更新、推送、收藏和本地同步时间 |
| 内容摘要 | README 摘要、仓库摘要、搜索文档 |
| 个人整理 | 收藏状态、标签、备注和取消 Star 状态 |
同步不是简单覆盖。已有的标签、备注和收藏状态会保留，仓库 GitHub 数据更新后会刷新检索文本。用户已经取消 Star 的仓库会被标记为 isStarred = false，方便后续排查历史数据。
搜索与筛选
工作台支持按关键词、语言、Owner、标签、收藏状态和排序方式筛选仓库。搜索文本会结合仓库元数据、标签、备注和摘要，让模糊记忆也能找到对应项目。
可用查询能力：
| 参数 | 说明 |
|---|---|
q | 关键词，匹配 searchDocument，并结合 PostgreSQL to_tsvector 和模糊匹配 |
language | 按主要语言过滤 |
owner | 按仓库拥有者过滤 |
tag | 按个人标签过滤，标签会统一按小写匹配 |
favorite | 只看重点收藏或排除重点收藏 |
sort | recent、relevance、stars、updated |
默认排序是 recent。当传入关键词并选择 relevance 时，服务端会使用 PostgreSQL 全文检索排名，让更相关的仓库排在前面。
标签与备注
每个仓库都可以补充个人标签和备注。标签适合做分类，备注适合记录“为什么收藏”“适合什么场景”“和哪些项目类似”。
标签和备注会参与搜索文档构建。也就是说，给仓库添加“向量数据库”“前端动画”“可替代某工具”之类的个人语言后，后续可以直接用这些词找回仓库。
建议用法：
- 标签使用短词或短语，例如
agent、search、frontend。 - 备注记录决策信息，例如“适合本地优先的知识库，不适合多人权限模型”。
- 对需要近期研究的仓库开启重点收藏，作为工作台的轻量待办。
收藏状态
你可以在 Starlens 内部维护自己的重点收藏状态，用于标记近期关注或需要继续研究的仓库。这个状态独立于 GitHub Star，不会修改 GitHub 上的收藏关系。
这种设计让 Starlens 的整理动作保持本地私有，适合做个人知识管理和项目评估。
AI 辅助
AI 能力用于摘要、候选重排和自然语言问答。它不会替代搜索，而是在检索结果之上补充解释、对比和总结。
当前支持的 AI 相关能力：
| 能力 | 行为 |
|---|---|
| 摘要 | 根据仓库描述、README 摘要和元数据生成简短说明 |
| 重排 | 对搜索候选结果做语义相关性排序 |
| 问答 | 根据用户问题先检索 Stars，再组织回答和候选解释 |
| Provider 配置 | 支持 Vercel AI Gateway、OpenAI-compatible、Anthropic native 和 Gemini native |
AI Provider 密钥会加密保存，API 响应不会返回明文。验证 Provider 时会尝试拉取模型列表或请求对应模型接口，并把验证状态写回配置。
CLI 与工具接入
Starlens 支持个人 API Token，外部 CLI 或开发 Agent 可以通过 API 查询你的 Stars。这样收藏过的项目可以进入本地开发工作流，而不是只停留在浏览器收藏页里。
工具接入分为两层：
| 方式 | 适用场景 |
|---|---|
| HTTP API | 自定义脚本、CLI、Agent runtime 直接调用 /api/* |
| MCP server | Codex、opencode、Claude Code、Cursor、支持 MCP 的 IDE 和桌面 MCP 客户端通过 stdio 调用 |
Token 明文只在创建时展示一次，服务端只保存哈希、前缀和后缀。Token 被调用时会更新 lastUsedAt，撤销后立即失效。
工作台视图
工作台围绕“列表 + 详情 + 操作”的结构设计：
- 左侧或主列表展示搜索结果、语言、Stars、标签和收藏状态。
- 详情区展示 README 摘要、仓库元数据、License、时间信息和个人备注。
- 操作区支持同步、搜索、添加标签、更新备注、切换重点收藏和发起 AI 问答。
这种结构适合频繁扫描和比较仓库，不把知识管理流程拆散到多个页面。