# OpenSpecNexus

**Repository Path**: xcl09/open-spec-nexus

## Basic Information

- **Project Name**: OpenSpecNexus
- **Description**: No description available
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenSpec Task Network Visualizer

[![AI Studio](https://img.shields.io/badge/AI%20Studio-Google-blue?style=flat-square&logo=google)](https://ai.studio)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=nodedotjs)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/typescript-%5E5.8-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)

扫描工作区中的 OpenSpec 任务规范文件（`.md` / `.json`），使用 Gemini AI 或本地 LLM 分析任务之间的依赖关系，并渲染交互式 D3 力导向网络图，直观展示项目任务拓扑和完成进度。

---

## 功能特性

- **自动扫描** — 递归扫描工作区目录，解析 Markdown 任务清单和 JSON 任务规格
- **AI 依赖推导** — 通过 Gemini Cloud API 或本地 OpenCode 模型自动识别任务间的逻辑依赖、阻塞关系和语义关联
- **交互式网络图** — D3 力导向图，支持拖拽、缩放、节点点击居中，实时反映任务状态变更
- **双视图模式** — 网络脑图 + 任务卡片分组，可按文件、状态、关键词过滤
- **任务 CRUD** — 在 UI 中直接创建任务、修改状态，变更自动写回磁盘
- **文件预览** — 点击即可查看规范源文件原始内容
- **自动轮询** — 可配置的后台轮询，实时监控任务文件变更

## 快速开始

### 前提条件

- Node.js >= 18
- （可选）Gemini API Key，用于 AI 依赖分析

### 安装与运行

```bash
# 安装依赖
npm install

# 配置 Gemini API Key（用于 AI 分析）
echo 'GEMINI_API_KEY="your-api-key"' > .env.local

# 启动开发服务器
npm run dev
```

浏览器打开 `http://localhost:3000`。

### 生产构建

```bash
npm run build
npm start
```

## 任务文件格式

### Markdown Checklist (`.md`)

```markdown
## 核心任务
- [ ] AUTH-1: 初始化项目并选择认证提供商
- [/] AUTH-2: 创建 users/roles/refresh_tokens 数据库表
- [x] AUTH-3: 开发 JWT Token 生成与校验逻辑
- [-] AUTH-4: 集成第三方登录 (已取消)
- [o] AUTH-5: 多因子认证 MFA (无需实现)
```

状态标记：` ` 未开始 | `/` `~` 进行中 | `x` 已完成 | `-` 已取消 | `o` 无需实现

### JSON 规格 (`.json`)

```json
{
  "project": "Payment Engine",
  "tasks": [
    {
      "id": "PAY-1",
      "title": "配置 Stripe 开发者后台",
      "status": "completed",
      "dependencies": []
    },
    {
      "id": "PAY-2",
      "title": "实现 Stripe Checkout 流程",
      "status": "in_progress",
      "dependencies": ["PAY-1"]
    }
  ]
}
```

支持的 JSON 结构：顶层数组、`{ tasks: [...] }`、或包含 `id`/`title` 的单对象。

> `package.json`、`metadata.json`、`tsconfig.json` 会被自动排除。

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/tasks` | 扫描并返回所有任务及文件列表 |
| `GET` | `/api/specs` | 同 `/api/tasks` |
| `POST` | `/api/tasks/create` | 创建新任务（写回磁盘） |
| `POST` | `/api/tasks/update-status` | 更新任务状态（写回磁盘） |
| `POST` | `/api/analyze` | AI 依赖关系分析 |
| `GET/POST` | `/api/workspace` | 获取/切换工作区路径 |
| `GET` | `/api/workspace/folders` | 列出子目录 |
| `GET` | `/api/workspace/file` | 读取文件内容 |
| `GET/POST` | `/api/opencode/config` | OpenCode 本地模型配置 |

## AI 分析模式

### Gemini Cloud（默认）

在 `.env.local` 中设置 `GEMINI_API_KEY`，使用 `gemini-3.5-flash` 模型进行依赖推导。

### OpenCode 本地模式

在 UI 设置面板中启用，对接本地运行的 OpenAI 兼容 API（如 Ollama、LM Studio）：
- 接口：`/v1/chat/completions`（OpenAI 兼容）
- 模型发现：同时探测 `/v1/models` 和 `/api/tags`（Ollama 兼容）

## 项目结构

```
├── server.ts           # Express API 服务 (端口 3000)
├── src/
│   ├── main.tsx        # React 入口
│   ├── App.tsx         # 全部 UI：D3 图、卡片视图、弹窗、过滤
│   └── index.css       # Tailwind CSS v4
├── openspec-tasks/     # 示例任务规范文件
├── vite.config.ts
├── tsconfig.json
└── package.json
```

## 技术栈

| 技术 | 用途 |
|------|------|
| React 19 + TypeScript | 前端框架 |
| Express | API 服务器 |
| D3.js v7 | 力导向网络图 |
| Tailwind CSS v4 | 样式 |
| Vite | 开发/构建 |
| @google/genai | Gemini AI 分析 |
| lucide-react | 图标 |
| motion | 动画 |

## 命令速查

```bash
npm run dev       # 开发模式（端口 3000）
npm run build     # 生产构建
npm start         # 生产运行
npm run lint      # TypeScript 类型检查 (tsc --noEmit)
npm run clean     # 清理 dist/
```