# link-show

**Repository Path**: null_056_1691/link-show

## Basic Information

- **Project Name**: link-show
- **Description**: 一种非线性的演示/展示工具，基于思维导图或者节点/链路的形式
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LinkShow

把任意文档(PDF / DOCX / PPTX / XLSX / HTML / EPUB / TXT / MD)转成可对话编辑、可播放、可生成讲稿的思维导图演示文稿。

## 项目结构

```
link-show/
├── linkshow/              Python 源码包(FastAPI + Anthropic + markitdown)
│   ├── server.py          API 入口
│   ├── converter.py       文档转 Markdown(markitdown)
│   ├── llm_client.py      Claude 调用 + 重试
│   ├── mindmap_builder.py 导图生成 + 对话编排
│   ├── _chat_ops.py       7 个对话工具应用器
│   ├── script_generator.py 讲稿批量生成
│   ├── instance_store.py  实例持久化 + 并发锁
│   ├── frontend/          上传页、播放页、对话面板、讲稿抽屉
│   └── templates/         项目导出模板
├── markitdown/            vendored 依赖(文档转 Markdown)
├── tests/                 71 个快线测试 + LLM 慢线测试
├── scripts/               smoke.sh、cleanup_outputs.py、dev.sh
├── docker/                Dockerfile.api、nginx.conf、entrypoint.sh
├── docs/                  PRD、各功能实施计划
├── pyproject.toml         Python 包元数据
├── docker-compose.yml     双容器编排(nginx + api)
├── Makefile               常用任务封装
└── .env.example           环境变量样板
```

## Quickstart · 本地开发

### Linux / macOS / Git Bash

```bash
# 1. 复制环境变量并填入 ANTHROPIC_API_KEY
cp .env.example .env
# 编辑 .env,填入真实 key

# 2. 一键启动(自动建 venv、装依赖)
bash scripts/dev.sh

# 或用 Makefile
make install
make dev
```

### Windows · PowerShell

```powershell
# 1. 复制环境变量(PowerShell)
Copy-Item .env.example .env
notepad .env   # 填入真实 key

# 2. 首次运行可能被执行策略拦截,临时绕过:
PowerShell -ExecutionPolicy Bypass -File .\scripts\dev.ps1

# 或永久允许(仅当前用户):
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
.\scripts\dev.ps1
```

### Windows · cmd.exe

```cmd
REM 1. 复制环境变量
copy .env.example .env
notepad .env

REM 2. 一键启动(双击 dev.bat 或在 cmd 中)
scripts\dev.bat
```

> Windows 下手动启动方式:
> ```cmd
> python -m venv .venv
> .venv\Scripts\activate
> pip install .\markitdown\packages\markitdown
> pip install -e ".[dev]"
> set ANTHROPIC_API_KEY=sk-ant-...
> python -m uvicorn linkshow.server:app --reload
> ```

启动成功后打开浏览器: <http://127.0.0.1:8000>

## Quickstart · Docker

```bash
cp .env.example .env
# 编辑 .env,填入真实 key

make docker-build
make docker-up
```

打开浏览器: <http://localhost>

停止: `make docker-down`(数据卷 `outputs` 保留)

## Windows 故障排查

| 现象 | 原因 / 解决 |
|---|---|
| `dev.ps1` 报"无法加载,因为在此系统上禁止运行脚本" | 执行策略限制。临时绕过: `PowerShell -ExecutionPolicy Bypass -File .\scripts\dev.ps1`;或永久放开(仅当前用户): `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |
| 找不到 `python` / `py` | 安装 Python 3.12+ 时勾选"Add to PATH";或通过 [python.org](https://www.python.org/downloads/) 重装 |
| `pip install ./markitdown/packages/markitdown` 失败 | 检查 pip 版本: `python -m pip install --upgrade pip`,需 pip ≥ 23 |
| 上传 PPTX/DOCX 转换失败 | 本地需安装 LibreOffice([下载](https://www.libreoffice.org/download/));或改用 Docker 部署 |
| `make` 命令找不到 | Windows 原生无 make。用 `scripts\dev.bat`、`scripts\dev.ps1`,或在 [Git for Windows](https://git-scm.com/) 提供的 Git Bash 中跑 `make` |
| 中文路径或文件名乱码 | cmd.exe 默认 GBK。建议用 PowerShell 或 Git Bash;或 `chcp 65001` 切 UTF-8 |
| 占用端口 8000 | 改用其它端口: `set LINKSHOW_PORT=8001 && scripts\dev.bat`,或 PowerShell: `$env:LINKSHOW_PORT="8001"; .\scripts\dev.ps1` |

## 常用命令

| 命令 | 用途 |
|---|---|
| `make help` | 列出所有 make 目标 |
| `make install` | 装依赖(含 vendored markitdown) |
| `make dev` | 本地开发模式(uvicorn --reload) |
| `make test` | 跑 71 个快线测试 |
| `make test-llm` | 跑 LLM 慢线测试(消耗 token) |
| `make smoke` | 跑烟雾测试脚本(需服务已启动) |
| `make docker-build` | 构建 Docker 镜像 |
| `make docker-up` | 启动 Docker 编排 |
| `make docker-down` | 停止 Docker 编排 |
| `make docker-logs` | 跟踪 API 日志 |
| `make cleanup` | 清理孤儿实例目录(dry-run) |
| `make clean` | 清本地缓存 |

## 端到端测试

### 自动化 API 测试（真实 LLM 调用）

需要先启动服务，然后在另一终端运行：

```cmd
REM cmd.exe
scripts\e2e-test.bat
```

```powershell
# PowerShell
PowerShell -ExecutionPolicy Bypass -File .\scripts\e2e-test.ps1
```

**测试流程**：
1. 上传 `tests/fixtures/sample.md` 生成导图
2. 获取导图结构并统计节点数
3. 对话编辑：添加测试子节点
4. 批量生成讲稿（真实 Haiku API 调用）
5. 手动编辑单个讲稿
6. 验证版本号

**预期耗时**：30-60 秒（真实 API 调用，消耗约 0.1-0.3 美元）

### 浏览器手动测试

完整的 UI 交互测试指南见 [`docs/MANUAL-E2E-TEST.md`](docs/MANUAL-E2E-TEST.md)，覆盖：

- F01: 文档上传与首次生成
- F02: 导图播放与键盘导航
- F04: 对话驱动编辑（多轮指令）
- F05: 讲稿批量生成
- F06: 讲稿手动编辑与状态角标
- F07: 多标签同步（版本轮询）
- F08: 错误处理（无效文件、网络中断）

测试完成后，实例保存在 `outputs/{instance_id}/`，浏览器访问 `http://127.0.0.1:8000/instance/{instance_id}/` 查看。

## 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `ANTHROPIC_API_KEY` | (必填) | Claude API Key |
| `LINKSHOW_OUTPUTS_DIR` | `outputs` | 实例数据目录 |
| `LINKSHOW_HOST` | `127.0.0.1` | 监听地址(Docker 内强制 0.0.0.0) |
| `LINKSHOW_PORT` | `8000` | 监听端口 |
| `LINKSHOW_HISTORY_TURNS` | `10` | 对话历史保留轮数 |
| `LINKSHOW_SCRIPT_CONCURRENCY` | `5` | 讲稿并发数 |

## API

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/convert` | 上传文档,生成首版导图 |
| POST | `/chat/{id}` | 自然语言编辑导图 |
| POST | `/chat/{id}/reset` | 清空对话历史 |
| POST | `/generate-scripts/{id}` | 批量生成讲稿 |
| POST | `/edit-script/{id}/{node_id}` | 手动编辑单节点讲稿 |
| GET | `/instance/{id}/version` | 查询版本号(多标签同步) |

## 系统要求

- **Python**: ≥ 3.12
- **OS 包**(本地或 Docker): LibreOffice、poppler-utils、ffmpeg(可选)
- **Claude API Key**: 来自 [console.anthropic.com](https://console.anthropic.com/)

详细设计与 PRD 见 `docs/PRD-LinkShow-2026-06-27.md`。