内容
# 星际工作台 Starlens
[English](README.md) | [中文](README.zh-CN.md)
Starlens 是一个个人知识工作台，用于 GitHub 星标仓库。它将星标仓库同步到 PostgreSQL，丰富轻量级摘要，并为用户提供一个可搜索的工作空间，包括标签、笔记、收藏、AI 辅助回忆、CLI 访问和本地代理集成。
该项目目前处于活跃的 `v1` 开发阶段。主要目标是让大量的 GitHub 星标仓库再次变得有用，而无需转变为重量级的 RAG 或团队协作平台。
## 功能
- 通过 GitHub OAuth 同步 GitHub 星标仓库。
- 存储仓库元数据、主题、语言、星标数量、时间戳、README 摘录、用户标签、笔记和收藏状态。
- 在 `/app` 提供桌面工作台，在 `/mobile` 提供移动工作台。
- 支持关键词搜索、筛选、排序、仓库详情检查、标签编辑、笔记编辑和收藏管理。
- 支持高级搜索筛选：星标数量范围、星标日期范围、最后推送日期、笔记内容和笔记存在。
- 支持 AI 驱动的自然语言查询，具有 8 种意图类型：计数、存在、比较、统计、推荐、单个仓库分析、结构化筛选和语义搜索。
- 为 CLI、MCP 和代理工作流公开个人 API 令牌。
- 通过 `stars install-skill` 实现 Claude Code、Cursor、Codex、opencode 等 AI 客户端的一键安装。
- 在 `/docs` 包含静态产品文档。
## 当前范围
已实现或正在连接：
- 公共登陆页面、文档、更新日志、隐私和条款路由。
- 身份验证的 Web 工作台。
- 移动工作台壳和共享的移动工作台状态。
- 通过 `packages/server` 实现共享 API 路由。
- GitHub 星标同步和仓库搜索，带有高级筛选。
- AI 提供商配置、验证和 AI 查询路由，具有 8 种意图类型。
- CLI (`@starlens-app/cli`) 发布到 npm：`stars` 命令用于登录、状态、同步、搜索、显示、打开、询问、收藏、笔记、标签和 `install-skill`。
- 用于 IDE 和本地代理客户端的 MCP stdio 服务器。
- 用于托管客户端（Claude Code、Cursor）的 HTTP MCP 端点。
- Claude Code、Cursor、Codex、opencode、OpenClaw、Hermes 和 VS Code 的代理技能一键安装。
明确超出 `v1` 范围：
- 完整的 README 正文存储。
- 向量搜索、嵌入和完整的 RAG。
- 多提供商自动故障转移。
- 多用户协作。
- 通用的任意提供商请求适配器。
## 架构
Starlens 是一个 `pnpm` 工作空间：
```text
apps/
web/ Next.js Web 应用，桌面工作台、登陆页面、文档、API 代理
mobile/ Next.js 移动工作台应用
cli/ 本地 CLI，用于基于令牌的访问 (@starlens-app/cli)
mcp/ 本地 stdio MCP 服务器
packages/
core/ 共享 DTO、类型、模拟数据和仓库文本实用程序
server/ 身份验证、数据库、GitHub 同步、搜索、AI 配置、令牌和路由逻辑
workbench/ 共享移动工作台状态和格式化实用程序
agent-tools/ MCP/代理工具定义和 HTTP API 客户端逻辑
docs/ 产品、架构、模式、环境和集成说明
drizzle/ 数据库迁移和快照
scripts/ 环境和数据库帮助脚本
```
Web 和移动应用暴露薄路由处理程序。大多数后端行为位于 `packages/server`，因此 CLI、MCP、Web 和移动端都依赖于相同的 API 合同，而不是重复业务逻辑。
## 技术栈
- Next.js 应用路由器
- React
- TypeScript
- PostgreSQL
- Drizzle ORM
- NextAuth GitHub OAuth
- Vitest
- MCP SDK
- pnpm 工作空间
## 要求
- Node.js `>=20.11.0`
- pnpm `10.33.3` 通过 Corepack
- PostgreSQL 用于本地开发或 Neon 用于托管环境
- GitHub OAuth 应用
启用 pnpm 通过 Corepack：
```bash
corepack enable
corepack prepare pnpm@10.33.3 --activate
```
## 本地设置
安装依赖项：
```bash
corepack pnpm install
```
创建本地环境变量：
```bash
cp .env.example .env
```
填写必填值：
```bash
AUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
DATABASE_URL=postgres://starlens:starlens@localhost:54329/starlens_dev
TOKEN_ENCRYPTION_SECRET=
SYSTEM_AI_API_KEY=
SYSTEM_AI_BASE_URL=
SYSTEM_AI_MODEL=
SYSTEM_AI_PROVIDER_TYPE=openai_compatible
SYSTEM_AI_ENABLED=true
```
运行数据库迁移：
```bash
corepack pnpm db:migrate:local
```
启动 Web 应用：
```bash
corepack pnpm dev
```
单独启动移动应用：
```bash
corepack pnpm dev:mobile
```
## 环境变量
| 变量 | 必需 | 目的 |
| --- | --- | --- |
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串。 |
| `AUTH_SECRET` | 是 | NextAuth 会话密钥。 |
| `NEXTAUTH_URL` | 是 | 公共应用 URL，例如 `http://localhost:3000`。 |
| `AUTH_GITHUB_ID` | 是 | GitHub OAuth 客户端 ID。 |
| `AUTH_GITHUB_SECRET` | 是 | GitHub OAuth 客户端密钥。 |
| `TOKEN_ENCRYPTION_SECRET` | 是 | 用于加密提供商密钥和个人令牌的密钥。 |
| `SYSTEM_AI_API_KEY` | 可选 | 系统级 AI 密钥，仅在用户没有默认提供商时使用。 |
| `SYSTEM_AI_BASE_URL` | 可选 | 系统级 OpenAI 兼容的备用基准 URL。 |
| `SYSTEM_AI_MODEL` | 可选 | 系统级备用模型名称。 |
| `SYSTEM_AI_PROVIDER_TYPE` | 可选 | 系统级提供商类型，默认为 `openai_compatible`。 |
| `SYSTEM_AI_ENABLED` | 可选 | 设置为 `false` 以禁用系统级备用。 |
旧的 `OPENAI_*` 密钥仍用于迁移兼容性，但新部署应使用 `SYSTEM_AI_*`。
对于托管的 Neon 验证，请复制 `.env.neon.example` 到 `.env.neon` 并使用 Neon 池连接字符串，`sslmode=require`。
## 开发命令
| 命令 | 描述 |
| --- | --- |
| `corepack pnpm dev` | 使用 `.env` 启动 Web 应用。 |
| `corepack pnpm dev:mobile` | 使用 `.env` 启动移动应用。 |
| `corepack pnpm build` | 构建 Web 应用。 |
| `corepack pnpm build:mobile` | 构建移动应用。 |
| `corepack pnpm build:packages` | 构建内部包（如果看到类型错误，请先运行此命令）。 |
| `corepack pnpm lint` | 运行 Web 校验。 |
| `corepack pnpm lint:mobile` | 运行移动校验。 |
| `corepack pnpm test` | 运行 Web 测试。 |
| `corepack pnpm test:mobile` | 运行移动测试。 |
| `corepack pnpm db:migrate:local` | 将迁移应用于本地 PostgreSQL。 |
| `corepack pnpm db:check:local` | 检查本地数据库连接。 |
| `corepack pnpm mcp:start` | 启动本地 Starlens MCP 服务器。 |
包级测试：
```bash
corepack pnpm --filter @starlens-app/cli test
corepack pnpm --filter @starlens-app/agent-tools test
corepack pnpm --filter @starlens/workbench test
```
## CLI 用法
CLI 作为独立的 npm 包提供：
```bash
npm install -g @starlens-app/cli
```
在 Web 应用中创建个人令牌，然后登录：
```bash
printf '%s\n' 'stl_xxx' | stars login --token-stdin
```
常用命令：
```bash
stars status
stars sync
stars search "agent framework"
stars show owner/repo
stars ask "which repos are good for local agent workflows?"
stars ask "how many TypeScript projects do I have?"
stars favorite owner/repo
stars note owner/repo --set "Review for MCP integration"
stars tag add owner/repo agent
```
AI 客户端的安装命令：
```bash
stars install-skill
```
向导引导您选择客户端（Claude Code、Cursor、Codex、opencode 等），安装技能文件，并可选地编写 MCP 配置条目。
如果您更喜欢在开发过程中直接从 monorepo 运行：
```bash
corepack pnpm --filter @starlens-app/cli start -- <command>
```
## MCP / 代理集成
### 主机 HTTP MCP（推荐大多数客户端）
如果您使用 `https://starlens.520ai.xin` 的主机服务，请通过 HTTP MCP 连接 - 不需要本地进程：
**Claude Code:**
```bash
claude mcp add-json starlens '{
"type": "http",
"url": "https://starlens.520ai.xin/mcp",
"headers": { "Authorization": "Bearer stl_xxx" }
}'
```
**Cursor** (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"starlens": {
"url": "https://starlens.520ai.xin/mcp",
"headers": { "Authorization": "Bearer stl_xxx" }
}
}
}
```
**opencode** (`~/.config/opencode/opencode.json`):
```json
{
"mcp": {
"starlens": {
"type": "remote",
"url": "https://starlens.520ai.xin/mcp",
"headers": { "Authorization": "Bearer stl_xxx" },
"enabled": true
}
}
}
```
**Codex** (`~/.codex/config.toml`):
```toml
[mcp_servers.starlens]
url = "https://starlens.520ai.xin/mcp"
http_headers = {Authorization = "Bearer stl_xxx"}
startup_timeout_sec = 30
default_tools_approval_mode = "approve"
```
### 自托管_stdio MCP
在您自己的 Starlens 实例上启动本地 MCP 服务器：
```bash
STARLENS_TOKEN="stl_xxx" \
STARLENS_API_BASE_URL="http://localhost:3000" \
corepack pnpm mcp:start
```
Cursor 样式_stdio 配置：
```json
{
"mcpServers": {
"starlens": {
"command": "corepack",
"args": ["pnpm", "mcp:start"],
"cwd": "/path/to/starlens",
"env": {
"STARLENS_TOKEN": "stl_xxx",
"STARLENS_API_BASE_URL": "http://localhost:3000"
}
}
}
}
```
### 可用的 MCP 工具
| 工具 | 目的 |
| --- | --- |
| `search_stars` | 搜索和筛选星标仓库 |
| `show_star` | 查看单个仓库的详细信息 |
| `sync_stars` | 触发 GitHub 星标同步 |
| `favorite_star` | 将仓库标记为收藏（仅本地标志 - 不会更改您的实际 GitHub 星标） |
| `unfavorite_star` | 删除收藏状态（仅本地标志 - 不会更改您的实际 GitHub 星标） |
| `star_repo` | 实际上将仓库星标在 GitHub 上（任何所有者/仓库，甚至您从未星标过的） |
| `unstar_repo` | 实际上从 GitHub 取消星标仓库 |
| `set_star_note` | 设置或清除仓库笔记 |
| `add_star_tag` | 向仓库添加标签 |
| `remove_star_tag` | 从仓库删除标签 |
| `ask_stars` | 对星标进行自然语言 AI 查询 |
| `analyze_repo` | 分析仓库并建议标签/笔记（星标或不星标） |
| `recommend_for_task` | 推荐与编码任务相关的星标仓库 |
| `find_related` | 查找与给定仓库相关的星标仓库 |
| `suggest_organization` | 建议重复/过时/未标记的仓库进行清理 |
| `get_sync_summary` | 总结自上次同步以来发生的变化 |
不要提交包含机密的真实 API 令牌或 MCP 客户端配置。
## 文档
用户文档可在运行的 Web 应用的 `/docs` 下找到：
- [功能](/docs/features) - 搜索、筛选、AI 查询意图类型、标签、笔记
- [架构](/docs/architecture) - 模块布局和数据流
- [集成](/docs/integrations) - GitHub OAuth、API 令牌、AI 提供商、CLI、MCP
- [部署](/docs/deployment) - Docker 自托管、Node.js、本地开发
内部设计和 API 说明：
- [项目计划](docs/project-plan.md)
- [环境指南](docs/environments.md)
- [API 合同](docs/api-contract.md)
- [数据库模式](docs/database-schema.md)
- [同步流程设计](docs/sync-flow-design.md)
- [代理集成](docs/agent-integration.md)
## 部署说明
主要的部署路径是带有 PostgreSQL 的 Docker 自托管。有关完整的指南，请参阅[部署文档](https://starlens.520ai.xin/docs/deployment)。
Docker 快速参考：
```bash
# 运行迁移
docker compose -f deploy/docker-compose.yml --profile migrate run --rm starlens-migrate
# 构建并启动
docker compose -f deploy/docker-compose.yml up -d --build starlens-web
```
部署前：
```bash
corepack pnpm test
corepack pnpm lint
```
## 安全说明
- 个人 API 令牌仅在创建时显示一次。
- 存储的令牌和提供商机密在服务器端加密或哈希。
- MCP 作为本地_stdio 进程运行，不打开公共网络端口。
- `v1` 使用用户级令牌所有权作为授权边界；细粒度令牌范围不属于当前范围。
## 贡献
欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解本地设置、PR 指南、代码样式和好第一个问题。
## 项目状态
核心功能稳定并在生产中运行。积极的开发重点：
- 扩展 AI 查询覆盖率和准确性。
- 调度自动同步。
- 移动工作台抛光和真实设备测试。
- 改进部署文档和自托管体验。
