# 最新分发与安装说明

## 1. 方案说明

当前推荐的分发方案是：

- 用 `arrivalcli` 作为本地安装底座
- 用 `arrivalcli setup-claude` 自动安装 Claude Code skill
- 在 Claude Code 中通过 `/arrival-card-api` 使用入境卡服务

也就是：

```text
Claude Code
-> /arrival-card-api
-> arrivalcli
-> 远程 API
-> 后台订单系统 / worker
```

这套方案的优点是：

- 不要求用户手工复制 skill 目录
- 不要求用户自己拼复杂命令
- 支持建单、查状态、补字段、加入执行队列
- 创建订单后，服务端会自动 OCR、生成 Profile，并返回核验结果

## 2. 推荐下载安装方式

### 推荐方式：直接安装 wheel

你需要提供给用户：

- `arrivalcli-0.1.2-py3-none-any.whl`

说明：

- **标准安装文件**建议保持 wheel 规范文件名，便于 `pip install`
- 如果你希望“分发文件名”带上**日期 + 版本号**，推荐额外生成一个 release zip
- 不建议直接随意改 wheel 文件名格式，否则可能影响 pip 识别

用户执行：

```bash
python3 -m pip install /path/to/arrivalcli-0.1.2-py3-none-any.whl --user
```

安装后验证：

```bash
arrivalcli --help
```

如果输出里能看到这些命令，说明安装成功：

- `setup-claude`
- `requirements`
- `create`
- `status`
- `update-profile`
- `queue`

### 其他用户如何获取最新 wheel

当前推荐三种方式，按优先级排序：

1. **你直接分发最新 wheel 文件**
   - 最适合内部同事、试点用户
   - 当前本地 wheel 文件路径通常是：

   ```text
   dist/arrivalcli-0.1.2-py3-none-any.whl
   ```

   你可以把这个文件：
   - 上传到 GitHub Release
   - 放到飞书/企业微信/共享盘
   - 放到内部下载页

   如果你想让最终给同事的文件名带上日期和版本号，推荐分发下面这种 release zip：

   ```text
   dist/arrivalcli-release-v0.1.2-20260605.zip
   ```

   zip 里面再放标准 wheel：

   ```text
   arrivalcli-0.1.2-py3-none-any.whl
   ```

2. **通过 GitHub Release 下载**
   - 推荐后续作为标准分发方式
   - 每次发新版时，把最新 wheel 上传到 GitHub Release
   - 用户只需要下载 wheel，再执行安装命令

3. **技术同事本地自行构建**
   - 适合内部开发或联调
   - 在项目根目录执行：

   ```bash
   python3 -m build
   ```

   构建完成后，wheel 会出现在：

   ```text
   dist/arrivalcli-0.1.2-py3-none-any.whl
   ```

   如果要同时生成“带日期 + 版本号”的分发 zip，可执行：

   ```bash
   bash scripts/build_release_bundle.sh
   ```

   生成结果类似：

   ```text
   dist/arrivalcli-release-v0.1.2-20260605.zip
   ```

### 当前不推荐的方式

- 不推荐普通用户自己 `git clone` 后再研究怎么打包
- 不推荐要求普通用户手工复制 skill 目录
- 不推荐把源码安装作为默认主路径

## 3. 初始化配置

安装后先执行：

```bash
arrivalcli init
```

然后编辑配置文件：

```text
~/.arrivalcli/config.json
```

填入真实值：

```json
{
  "base_url": "http://你的服务器地址:9527",
  "timeout_sec": 20,
  "api_key": "你的真实APIKey"
}
```

可用下面命令检查配置：

```bash
arrivalcli config show
```

## 4. 安装 Claude Code skill

先在 Claude Code 中输入：

```text
/skills
```

看这一行：

```text
User skills (实际目录)
```

如果目录是默认值，直接执行：

```bash
arrivalcli setup-claude
```

如果不是默认目录，执行：

```bash
arrivalcli setup-claude --skills-dir "实际目录"
```

安装完成后，在 Claude Code 中再次输入：

```text
/skills
```

应能看到：

- `arrival-card-api`

然后输入：

```text
/arrival-card-api
```

如果能进入 skill，说明安装成功。

## 5. Claude Code 中的使用方式

安装完成后，在 Claude Code 中可以直接说：

- `/arrival-card-api 帮我看韩国入境卡需要哪些资料`
- `/arrival-card-api 帮我创建一笔韩国订单`
- `/arrival-card-api 查询订单10的状态`
- `contact_in_korea:02112345678`
- `departure_date:2026-06-06`
- `加入队列`

当前支持的核心能力包括：

- 查询资料要求
- 创建订单
- 查询状态
- 持续轮询
- 下载结果
- 更新 profile 字段
- 加入执行队列

## 6. 当前推荐给用户的最小安装步骤

```bash
python3 -m pip install /path/to/arrivalcli-0.1.2-py3-none-any.whl --user
arrivalcli init
arrivalcli config show
arrivalcli setup-claude
```

然后在 Claude Code 中输入：

```text
/skills
```

确认 `arrival-card-api` 已出现。

## 7. 是否需要通过 git 安装

**不推荐普通用户通过 git 安装。**

### 推荐

- 直接安装 `wheel`

### 备选

如果是技术同事，也可以从源码安装：

```bash
git clone <repo_url>
cd e-arrival-card-project
python3 -m pip install . --user
```

但这条路径更适合：

- 内部开发
- 联调
- 调试最新代码

不适合作为普通试用用户的默认安装方式。

## 8. 当前最适合的分发方式

当前建议你对外分发时提供：

1. `arrivalcli-0.1.2-py3-none-any.whl`
2. 一份安装说明文档
3. 服务地址和 API Key 获取方式

**不再要求用户手工复制 skill 目录。**
因为 `arrivalcli setup-claude` 已经负责安装 skill。

## 9. 一句话总结

**最新方案不是让用户通过 git 手工配置，而是：先安装 `arrivalcli` 的 wheel，再执行 `arrivalcli setup-claude`，最后在 Claude Code 中通过 `/arrival-card-api` 使用入境卡服务。**