技术架构
Starlens 采用 monorepo 组织，核心 Web 应用使用 Next.js App Router 构建，服务端模块复用 @starlens/server，共享类型和文本处理逻辑放在 @starlens/core，CLI、HTTP Agent 和 MCP 对接能力放在 @starlens/agent-tools。
核心模块
| 模块 | 责任 |
|---|---|
| Web 应用 | 提供首页、登录、工作台、设置和文档页面 |
| GitHub 登录 | 使用 GitHub OAuth 识别用户身份 |
| GitHub 同步 | 拉取用户 Stars，写入本地数据库 |
| 仓库工作台 | 展示仓库列表、筛选条件、详情、标签和备注 |
| 搜索服务 | 基于仓库元数据、README 摘要、标签和备注构建检索文本 |
| AI 服务 | 支持摘要、重排、自然语言问答和模型配置 |
| API Token | 让 CLI 或外部工具以 Bearer token 调用 Starlens API |
| MCP Server | 把 Starlens API 包装成本地 stdio 工具，供 Codex、opencode、Claude Code、Cursor 和支持 MCP 的 IDE 调用 |
运行时分层
| 层级 | 代码位置 | 责任 |
|---|---|---|
| Web App | apps/web | 页面、App Router API 入口、工作台和设置 UI |
| Mobile App | apps/mobile | 移动端入口和与 Web 一致的 API 路由代理 |
| Server Package | packages/server | 认证、数据库、GitHub 同步、AI 配置和业务路由 |
| Core Package | packages/core | 共享类型、搜索常量、仓库文本构建和 mock 数据 |
| Agent Tools | packages/agent-tools | HTTP API 的工具封装，供 CLI、HTTP Agent 和 MCP 复用 |
| MCP App | apps/mcp | stdio MCP server，向外暴露 search_stars 等工具 |
API 路由保持薄层设计：apps/web/src/app/api/* 主要转发到 packages/server/src/routes/* 的实现。这样 Web、Mobile 和 Agent 能共享同一套业务逻辑。
数据流
- 用户使用 GitHub 登录 Starlens。
- 同步任务读取用户授权范围内的 Stars。
- 服务端将仓库元数据、README 摘要、标签和备注写入 PostgreSQL。
- 搜索接口根据关键词、语言、Owner、标签、收藏状态和排序方式返回候选仓库。
- AI 问答接口先检索候选仓库，再按默认 AI Provider 生成回答或解释候选结果。
- CLI、HTTP Agent 和 MCP 工具通过 Bearer Token 复用同一组 HTTP API。
数据存储
Starlens 默认使用 PostgreSQL。核心数据包括用户身份、GitHub 仓库快照、个人标签、备注、收藏状态、AI Provider 配置和个人 API Token。
| 表 | 关键内容 |
|---|---|
users | 登录用户的邮箱、名称、头像和最后登录时间 |
github_accounts | GitHub 用户 ID、登录名、加密 access token、同步状态 |
starred_repos | 仓库元数据、README 摘要、搜索文档、AI 摘要、收藏状态 |
repo_tags | 用户级仓库标签，按仓库和标签做唯一约束 |
repo_notes | 用户级仓库备注，每个仓库一条备注 |
personal_api_tokens | Token 哈希、前缀、后缀、撤销状态和最后使用时间 |
user_ai_configs | Provider 类型、模型、Base URL、加密 API Key、验证状态 |
starred_repos.search_document 使用 PostgreSQL GIN 索引加速全文检索。标签和备注更新后会刷新搜索文档，保证个人整理信息能被搜索命中。
认证与授权
Starlens 同时支持浏览器会话和 Bearer Token：
| 调用方 | 鉴权方式 | 说明 |
|---|---|---|
| Web 页面 | GitHub OAuth + NextAuth 会话 | 用于登录后页面和浏览器内 API 请求 |
| CLI / Agent | Authorization: Bearer stl_xxx | 用于搜索、详情、同步、标签、备注、AI 问答等业务接口 |
| Token 管理 | 浏览器会话 | Bearer Token 不允许继续签发新的 Token |
服务端会基于当前用户 ID 隔离所有数据查询。个人访问令牌只保存 SHA-256 哈希，明文只在创建时返回一次。
GitHub 同步细节
同步任务会调用 https://api.github.com/user/starred?sort=created&direction=desc&per_page=100，并通过 GitHub Link 响应头追踪下一页。
每个仓库会被规范化为本地字段，再按 userId + githubRepoId upsert。README 只在新仓库或 pushedAtGithub 变化时重新拉取，避免每次同步都重复处理内容。
常见错误会归类为：
| 类型 | 触发条件 |
|---|---|
auth | GitHub access token 失效、权限不足或返回 401/403 |
rate_limit | GitHub 返回 429 或 rate limit 信息 |
network | 请求失败、连接错误或 fetch 异常 |
unknown | 其他未分类异常 |
AI Provider 架构
AI 配置是用户级资源。运行时只会读取启用并设为默认的配置，并在服务端内存中短暂解密密钥。
支持的 Provider 类型：
| Provider | 默认 Base URL | 说明 |
|---|---|---|
vercel_gateway | https://ai-gateway.vercel.sh/v1 | 通过 Vercel AI Gateway 代理模型 |
openai_compatible | 由用户填写 | 兼容 OpenAI /v1/models 的服务 |
anthropic_native | https://api.anthropic.com | 使用 x-api-key 和 anthropic-version 请求模型列表 |
gemini_native | https://generativelanguage.googleapis.com | 使用 Gemini v1beta/models 模型列表 |
Provider 验证会尝试获取模型列表。成功时写入 lastValidationStatus = success，失败时写入 error 和错误信息，但不会把密钥返回给客户端。
扩展方式
Starlens 的扩展重点在三个方向：增加新的 AI Provider、开放更多 API 给 CLI 或 Agent、增强仓库内容索引。文档页保持静态 MDX，避免把用户文档和业务逻辑耦合在一起。
推荐扩展原则：
- 新业务逻辑优先放入
packages/server，页面和 API 路由只做薄封装。 - 共享类型和文本构建逻辑放入
packages/core，避免 Web、MCP 和测试重复定义。 - Agent 能力优先复用 HTTP API，再由
packages/agent-tools做工具输入输出转换。 - 新 Provider 只扩展 Provider 类型、默认 Base URL、模型列表拉取和验证逻辑，不影响已有配置。