# LTCTM的软件推荐站v4

**Repository Path**: ltctm/software-nav4

## Basic Information

- **Project Name**: LTCTM的软件推荐站v4
- **Description**: 一个用于管理和展示软件信息的导航系统，支持从winget manifest和GitHub自动生成软件数据，并提供Web界面进行搜索和浏览。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://software.ltctm.net
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-11
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LTCTM 软件导航 v4

一个面向**中国大陆网络环境**的软件下载导航站。无需安装任何客户端，打开浏览器即可搜索和下载软件。编辑端自动从 winget 和 GitHub 采集版本信息，前端用 Vue 3 展示。

> **背景**：国内用户常面临新装机无网络代理、公司环境受限、旧系统无 winget 等问题，导致下载软件困难。本项目通过 URL 镜像替换、磁盘缓存、两级版本库等机制，让用户在无代理的环境下也能快速可靠地获取软件。详见 [设计背景与难点分析](docs/diagrams/FLOW_SUMMARY.md#设计背景)。

## 环境要求

- **编辑端**：Python 3.11+，依赖管理使用 [uv](https://docs.astral.sh/uv/)
- **前端**：Vue 3 + Vite + Tailwind CSS (DaisyUI)

## 快速开始

### 1. 生成 GitHub 软件的 Manifest

```bash
cd localend
uv run app/generate_manifests.py
```

从 GitHub 拉取 `softwares.csv` 中 `update_source=github` 的软件最新 Release，生成 YAML Manifest 到 `source/manifests/`，并更新本地版本数据库。

### 2. 生成前端数据

```bash
cd localend
uv run app/generate_json.py
```

读取 `softwares.csv` 全部软件，解析 Manifest 文件（或手动 TOML），生成 `web/software_data.json`。

### 3. 启动前端

```bash
cd web
npm install
npm run dev
```

## 添加软件

有三种方式，取决于软件的来源：

### 方式 A：winget 仓库已有

在 `localend/app/softwares.csv` 添加一行，`update_source` 留空即可：

```csv
Publisher.PackageName,显示名称,,,图标URL,,
```

### 方式 B：有 GitHub Release

在 `softwares.csv` 添加一行，设置 `update_source=github`：

```csv
Publisher.PackageName,显示名称,moniker,别名,图标URL,github,720
```

- `moniker`：若需自定义生成器子类则填写，否则留空（使用基类自动推断）
- `update_interval`：缓存过期时间，单位小时

### 方式 C：手动配置（网盘/直链等）

在 `source/manual/{首字母}/{publisher}/{package}/` 下创建 TOML 文件，参考已有文件格式。**不要**直接编辑 `manual_software.csv`，它由脚本自动生成。

添加完成后重新运行 `generate_json.py`。

## 常用命令

```bash
# 强制刷新指定包的 GitHub 缓存
uv run app/generate_manifests.py --force-refresh publisher.package1 publisher.package2

# 并行拉取 GitHub（3 线程）
uv run app/generate_manifests.py --workers 3
```

## 配置

编辑 `localend/app/config.toml`，或设置环境变量：

- `GITHUB_API_TOKEN` — GitHub API 令牌（推荐用环境变量）
- `GITEE_API_TOKEN` — Gitee API 令牌

详见 [configuration.md](docs/configuration.md)。

## 项目结构

```
software-nav4/
├── localend/                        # 编辑端 (Python)
│   ├── app/
│   │   ├── paths.py                   # 应用路径、根目录与路径解析工具
│   │   ├── config.py                  # 读取 config.toml，暴露配置项
│   │   ├── errors.py                  # 自定义异常类型体系
│   │   ├── generate_manifests.py      # 步骤1: GitHub 数据拉取
│   │   ├── generate_json.py           # 步骤2: JSON 生成
│   │   ├── softwares.csv              # 软件清单（核心配置）
│   │   ├── config.toml                # 全局配置
│   │   ├── github_manifests/          # GitHub 生成器（基类 + 子类）
│   │   ├── winget_manifest_parser/    # winget Manifest 解析器
│   │   └── utils/
│   │       ├── logging_config.py      # 日志配置 + ErrorCollector
│   │       ├── csv_utils.py           # CSV 工具函数
│   │       ├── index_db_manager.py    # 版本数据库管理
│   │       ├── request_cache.py       # 磁盘缓存连接封装（含延迟初始化）
│   │       └── ...                    # 其他工具函数
│   ├── source/
│   │   ├── manifests/                 # 自维护的 Manifest 仓库
│   │   ├── manual/                    # 手动 TOML 配置
│   │   └── db/                        # 版本索引数据库
│   ├── logs/                          # 运行日志 + 错误报告（自动生成）
│   └── cache/                         # 请求磁盘缓存
├── web/                             # 前端 (Vue 3 + Vite)
│   ├── src/
│   │   ├── App.vue                  # 主入口 + Fuse.js 搜索
│   │   └── components/              # Card.vue + Detail.vue
│   └── software_data.json           # 编辑端生成的数据文件
└── docs/                            # 文档
    ├── configuration.md             # 配置说明
    ├── GitHubManifestGeneratorSubclass.md  # 子类继承指南
    ├── architecture_review.md       # 项目架构评价
    └── diagrams/                    # 系统流程图
        ├── FLOW_SUMMARY.md          # 流程文档索引 + 速查
        ├── architecture.md          # 系统架构 + 数据流向
        ├── generate_manifests.md    # GitHub 数据拉取流程
        ├── generate_json.md         # JSON 生成流程
        ├── frontend.md              # 前端展示流程
        ├── data_priority.md         # 优先级与路由机制
        ├── d2/                      # D2 流程图源码（14 个子图）
        └── images/                  # 渲染后的 SVG
```

## 文档索引

| 文档 | 说明 |
|------|------|
| [configuration.md](docs/configuration.md) | config.toml 配置项、环境变量、URL 替换规则 |
| [GitHubManifestGeneratorSubclass.md](docs/GitHubManifestGeneratorSubclass.md) | 如何编写自定义 GitHub 生成器子类 |
| [architecture_review.md](docs/architecture_review.md) | 项目架构设计评价 |
| [error_handling.md](docs/error_handling.md) | 自定义异常类型体系与错误处理规范 |
| [diagrams/FLOW_SUMMARY.md](docs/diagrams/FLOW_SUMMARY.md) | 流程文档索引 + 关键约定速查 |
| [diagrams/architecture.md](docs/diagrams/architecture.md) | 系统架构、数据流向 |
| [diagrams/generate_manifests.md](docs/diagrams/generate_manifests.md) | GitHub 拉取 → Manifest 生成 |
| [diagrams/generate_json.md](docs/diagrams/generate_json.md) | 版本查询 → Manifest 解析 → JSON 输出 |
| [diagrams/frontend.md](docs/diagrams/frontend.md) | 前端构建、搜索、组件结构 |
| [diagrams/data_priority.md](docs/diagrams/data_priority.md) | update_source 路由、优先级机制 |