功能说明
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 |
minStars | Star 数下限，只返回 Star 数不低于该值的仓库 |
maxStars | Star 数上限，只返回 Star 数不超过该值的仓库 |
starredAfter | 只返回在该日期之后收藏的仓库（ISO 日期） |
starredBefore | 只返回在该日期之前收藏的仓库（ISO 日期） |
pushedAfter | 只返回在该日期之后有推送的仓库（ISO 日期） |
hasNote | true 时只返回已添加备注的仓库 |
noteContains | 只返回备注内容包含该关键词的仓库 |
默认排序是 recent。当传入关键词并选择 relevance 时，服务端会使用 PostgreSQL 全文检索排名，让更相关的仓库排在前面。
标签与备注
每个仓库都可以补充个人标签和备注。标签适合做分类，备注适合记录“为什么收藏”“适合什么场景”“和哪些项目类似”。
标签和备注会参与搜索文档构建。也就是说，给仓库添加“向量数据库”“前端动画”“可替代某工具”之类的个人语言后，后续可以直接用这些词找回仓库。
建议用法：
- 标签使用短词或短语，例如
agent、search、frontend。 - 备注记录决策信息，例如“适合本地优先的知识库，不适合多人权限模型”。
- 对需要近期研究的仓库开启重点收藏，作为工作台的轻量待办。
收藏状态
你可以在 Starlens 内部维护自己的重点收藏状态，用于标记近期关注或需要继续研究的仓库。这个状态独立于 GitHub Star，不会修改 GitHub 上的收藏关系。
这种设计让 Starlens 的整理动作保持本地私有，适合做个人知识管理和项目评估。
AI 辅助
AI 能力用于摘要、候选重排和自然语言问答。它不会替代搜索，而是在检索结果之上补充解释、对比和总结。
当前支持的 AI 相关能力：
| 能力 | 行为 |
|---|---|
| 摘要 | 根据仓库描述、README 摘要和元数据生成简短说明 |
| 重排 | 对搜索候选结果做语义相关性排序 |
| 问答 | 根据用户问题自动识别意图，路由到专用执行器后返回答案和候选仓库 |
| 多轮对话 | 通过 SSE 返回执行事件和最终答案，持久化会话与候选仓库；上游模型不保证逐 token 输出 |
| Provider 配置 | 可保存和验证 OpenAI-compatible、Anthropic native、Gemini native 和 DeepSeek native；当前问答运行时使用 OpenAI-compatible Chat Completions |
AI Agent 问答链路
/api/ai/ask 和 /api/ai/chat 当前使用工具调用 Agent，而不是固定意图分类器。模型会根据问题组合下列工具，所有仓库结论必须来自真实工具结果：
| 工具 | 用途 |
|---|---|
search_repos | 关键词、语言、Owner、标签、Star 区间、时间和备注等常规检索 |
get_repo_detail | 查看已召回仓库的 README 摘要、标签、备注和完整元数据 |
get_repo_stats | 统计收藏总数、语言分布、月度趋势和高 Star 仓库 |
run_readonly_query | 常规参数无法表达的复杂过滤、聚合和 Join；仅允许只读查询指定仓库表 |
recommend_for_task | 根据编码任务全文召回候选仓库 |
find_related | 按 Owner、语言和 Topic 查找关联收藏 |
suggest_organization | 发现重复、过时和未分类仓库，不自动修改 |
| 写操作工具 | 在用户明确要求时添加/删除标签、更新备注和重点收藏；取消 GitHub Star 需要二次确认 |
submit_answer | 基于前述真实结果提交最终答案和要展示的仓库 ID |
/api/ai/ask 是单次 JSON 问答；/api/ai/chat 共享同一 Agent 工具链，通过 SSE 返回执行状态和结果，并持久化多轮会话。Provider 必须支持 OpenAI-compatible Chat Completions 工具调用；没有可用 Provider 时不会生成推测性兜底答案。
run_readonly_query 只允许单条 SELECT 或 WITH ... SELECT，限制访问 starred_repos、repo_tags 和 repo_notes，并通过数据库只读角色和 RLS 隔离当前用户数据。
AI Provider 密钥会加密保存，API 响应不会返回明文。验证 Provider 时会尝试拉取模型列表或请求对应模型接口，并把验证状态写回配置。
CLI 与工具接入
Starlens 支持个人 API Token，外部 CLI 或开发 Agent 可以通过 API 查询你的 Stars。这样收藏过的项目可以进入本地开发工作流，而不是只停留在浏览器收藏页里。
工具接入分为三层：
| 方式 | 适用场景 |
|---|---|
| Agent Skill | Claude Code、Cursor、VS Code、OpenClaw、Hermes 等支持 Skill 文件的客户端，通过 npx skills add 安装行为说明 |
| HTTP API | 自定义脚本、CLI、Agent runtime 直接调用 /api/* |
| MCP server | Codex、opencode、Claude Code、Cursor 等通过 HTTP MCP（托管）或 stdio MCP（自部署）调用 |
推荐运行 stars setup 一次完成 Skill 安装与 MCP 配置；已有 Skill 时可用 stars install-mcp 只更新 MCP 配置。
Token 明文只在创建时展示一次，服务端只保存哈希、前缀和后缀。Token 被调用时会更新 lastUsedAt，撤销后立即失效。
Agent 主动式分析与建议
除了被动查询，Starlens 还提供 5 个主动型工具，让 Claude Code、Hermes、OpenClaw 等 AI Agent 在用户开发过程中主动分析收藏仓库、推荐相关项目、给出整理建议。这些工具会让 Agent 像一个了解你收藏历史的助手，在你写代码、做技术选型、整理收藏时主动提供上下文。
| 工具 | 触发场景 | 返回内容 |
|---|---|---|
analyze_repo | 用户提到某个仓库（owner/repo）希望分析用途 | 仓库元数据、README 摘要、topics、收藏状态——Agent 自行分析适用场景、建议标签和备注 |
recommend_for_task | 用户开始新功能/技术选型/库对比任务 | 按任务描述全文检索召回的候选仓库列表（ts_rank 排序）——Agent 自行重排并解释相关性 |
find_related | 用户在某个仓库上下文中想找相似项目 | 从同 owner、同 language、同 topics 三维度召回的候选仓库——Agent 自行判断语义关联 |
suggest_organization | 用户想整理收藏（去重、清理过期、补标签） | 重复仓库、长期未整理仓库、缺少标签仓库的分组列表 |
get_sync_summary | Agent 需要了解最近收藏变化 | 最近一次同步时间，以及指定时间之后检测到的新增和取消 Star 仓库 |
get_sync_summary 当前是轻量实现：added 基于 lastSyncedAt 推断，可能同时包含元数据更新过的仓库；changed 暂不做精确区分。精确变化历史需要后续引入持久化变更事件表。
数据端点与 AI 端点
这 5 个工具有一个关键设计：MCP / Agent Skill 调用走数据端点，不调用 Starlens 后端 AI。
| 调用路径 | 端点 | AI 调用 | 适用场景 |
|---|---|---|---|
| MCP / Agent Skill | /api/repos/*-data | ❌ 返回原始数据，Agent 自行分析 | Claude Code、Hermes 等 Agent 自带 AI 模型的场景 |
| CLI / Web | /api/ai/* | ✅ Starlens 后端 AI 分析 | stars analyze 命令、Web 工作台等无 Agent 包裹的场景 |
这样做的原因是 Claude Code、Hermes 等 Agent 本身就自带 AI 模型（Claude、GPT 等），如果 Starlens 后端再调一次 AI，会形成重复调用——既浪费 token 又让响应变慢。重构后 MCP 工具只返回原始数据（README 摘要、topics、检索分数、召回原因等），由 Agent 用自己的模型和上下文分析，结果更贴合当前对话。
响应结构
所有主动型工具的响应都遵循统一结构，方便不同 Agent 解析：
| 字段 | 说明 |
|---|---|
data | 主数据（仓库详情、候选列表等） |
meta | 元信息（empty 标记空结果、hint 给出冷启动提示） |
suggestedNextActions | 建议的下一步工具调用（如 show_star、add_star_tag）及原因 |
reasoningHints | 数据来源说明（如"全文检索召回 N 个候选，未做 AI 重排"） |
CLI 对称命令
CLI 提供两个对称命令，方便在终端直接使用（走 AI 端点，因为 CLI 没有 Agent 包裹）：
| 命令 | 说明 |
|---|---|
stars analyze <repo> | 分析仓库并生成适用场景、建议标签、建议备注，--apply 自动应用建议 |
stars suggest [--focus duplicates|stale|untagged|all] | 检测重复、过时、未分类仓库，给出整理建议 |
工作台视图
工作台围绕“列表 + 详情 + 操作”的结构设计：
- 左侧或主列表展示搜索结果、语言、Stars、标签和收藏状态。
- 详情区展示 README 摘要、仓库元数据、License、时间信息和个人备注。
- 操作区支持同步、搜索、添加标签、更新备注、切换重点收藏和发起 AI 问答。
这种结构适合频繁扫描和比较仓库，不把知识管理流程拆散到多个页面。