# xhs-parse-node

**Repository Path**: webqiang99/xhs-parse-node

## Basic Information

- **Project Name**: xhs-parse-node
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xhs-parse-node

小红书分享文案/链接 → 结构化菜谱 JSON 的 Node.js HTTP 服务。供同工作区 [`xhs-food-recipe`](../xhs-food-recipe) 小程序调用。

面向 AI 与维护者的**规格导航**：[`AGENTS.md`](./AGENTS.md)、[`docs/spec/index.md`](./docs/spec/index.md)。

## 技术栈

- Node.js、TypeScript、Express 4
- cheerio（页面抓取）
- better-sqlite3（可选缓存与历史）
- OpenAI SDK（DeepSeek / OpenAI 兼容接口）

## 快速开始

```bash
pnpm install
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY 或 OPENAI_API_KEY

pnpm dev
# 服务默认 http://127.0.0.1:8787
```

生产：

```bash
pnpm build
pnpm start
```

## 脚本

| 命令 | 说明 |
| --- | --- |
| `pnpm dev` | 开发（tsx watch） |
| `pnpm build` | 编译到 `dist/` |
| `pnpm start` | 运行编译产物 |
| `pnpm parse:url` | CLI 调试单条 URL |

## HTTP API（摘要）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/parse` | 解析为 `{ recipe, meta }` |
| `GET` | `/history` | 最近解析记录 |
| `GET` | `/health` | 探活与配置状态 |

完整契约见 [`api-doc.md`](./api-doc.md)。

## 环境变量

见 [`.env.example`](./.env.example)。常用项：

- `PORT`（默认 8787）
- `DEEPSEEK_API_KEY` / `OPENAI_API_KEY`
- `DATABASE_PATH`、`CACHE_TTL_HOURS`、`DATABASE_ENABLED`

## 目录说明（摘要）

| 路径 | 说明 |
| --- | --- |
| `src/index.ts` | Express 入口 |
| `src/xhsExtract.ts` | 小红书页面抓取 |
| `src/deepseekStructure.ts` | DeepSeek 结构化 |
| `src/db/` | SQLite 缓存与历史 |
| `docs/spec/` | 规格与 reference |
| `docs/technical-design.md` | 流水线技术设计 |

## 与前端联调

1. 启动本服务后访问 `GET /health` 确认 `ok: true`。  
2. 在 `xhs-food-recipe/src/config/xhsParse.ts` 设置可访问的 `XHS_PARSE_BASE_URL`。  
3. 微信小程序配置 request 合法域名（真机/线上）。

## 上线发布

- 流程说明：[`docs/小程序上线发布指南.md`](../docs/小程序上线发布指南.md)
- **Docker**：[`docs/Docker部署指南.md`](../docs/Docker部署指南.md)（`docker compose up -d api`）

## 文档索引

| 文档 | 用途 |
| --- | --- |
| [`AGENTS.md`](./AGENTS.md) | Agent 工作流 |
| [`api-doc.md`](./api-doc.md) | HTTP 请求/响应 |
| [`docs/technical-design.md`](./docs/technical-design.md) | 抓取与 AI 流水线 |