# travel-skill-creator

**Repository Path**: cuixc2018/travel-skill-creator

## Basic Information

- **Project Name**: travel-skill-creator
- **Description**: 旅游场景cteator技能打造
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 旅游达人 Skill Creator（演示闭环）

对应研讨结论：**先做一个面向达人的对话式 Creator**，把经验沉淀为带 `SKILL.md` + `reference/` 的文件包；再用**同一套火山方舟 Responses API** 模拟「游客」按 `SKILL.md` 执行。

## 安全说明

- **切勿**把 API Key 写进仓库或发给他人。你在对话里粘贴的 Key 建议视为已泄露，请在火山控制台**轮换**。
- 本项目通过环境变量 `ARK_API_KEY` 读取密钥。

## 分享给他人（对方要能自己跑起来）

**发什么：** 把整个 **`travel-skill-creator`** 文件夹交给对方即可（压缩成 zip 最省事）。

**不要打包进去：**

- **`node_modules/`**（让对方自己 `npm install`，体积小、避免平台差异）
- **`.env` / `.env.local`**（里有你的密钥；对方用 `.env.example` 自己建 `.env`）

**建议一并说明：** 可选附带根目录下的 **`DEMO_INPUTS.md`**（演示时复制粘贴用，已在文件夹里）。

**对方环境：** 已安装 **Node.js**（建议 18+），能开终端。

**对方步骤：**

```bash
cd travel-skill-creator
npm install
cp .env.example .env
# 编辑 .env 填入自己的火山方舟 ARK_API_KEY
npm run dev:ui
```

用浏览器打开终端里显示的地址（多为 `http://127.0.0.1:5173/`）。未配置 Key 时页面可开，但对话会提示配置密钥；也可在页面黄条里**临时粘贴 Key**（仅当前标签页）。

**联网摘要（无 UI）：** 在 **② 达人创建** / **④ 游客使用** 里每次发送时，会请求同源 **`/search-proxy`**，把返回的正文拼进当次请求的 system。仅 `npm run dev:ui` / `vite preview` 有中间件；静态 `dist-web` 需自备反代。

**搜索从哪来（`.env`，不要加 `VITE_`，密钥勿进前端）：**

| 方式 | 你需要准备 | 去哪申请 |
|------|------------|----------|
| 自动（推荐） | 只填 **一种** 密钥即可 | 见下行；不配则走 DuckDuckGo |
| `duckduckgo`（兜底） | 无 | Instant Answer，中文/泛查询常**空摘要** |
| `brave` | `BRAVE_SEARCH_API_KEY` | [Brave Search API](https://brave.com/search/api/) |
| `tavily` | `TAVILY_API_KEY` | [Tavily](https://www.tavily.com/) |
| `bing` | `BING_SEARCH_KEY`，可选 `BING_SEARCH_ENDPOINT` | [Bing Web Search API](https://www.microsoft.com/en-us/bing/apis/bing-web-search-api)（Azure 资源） |

示例（Brave，**不必再写** `SEARCH_PROVIDER`，有 Key 即走 Brave）：

```bash
BRAVE_SEARCH_API_KEY=你的密钥
```

若需强制指定引擎，可设 `SEARCH_PROVIDER=brave|tavily|bing|duckduckgo`。选了某引擎但未配 Key 或 API 报错，会**自动退回** DuckDuckGo。

**Brave 报 `fetch failed`：** 多为本机到 `api.search.brave.com` 的网络/TLS 连不上（大陆环境较常见）。可改用 **`SEARCH_PROVIDER=tavily`** 并配置 `TAVILY_API_KEY`；或在保留 Brave 的同时配置 Tavily（或 Bing），Brave 失败时 dev 服会**自动回退**到 Tavily/Bing（见 `vite.search-proxy.ts`）。

**常见误会：** 页面里填的火山方舟 Key 只负责**对话模型**，**不会**当作搜索 Key；没配 Brave/Tavily/Bing 时，后台仍是 DuckDuckGo，容易出现「没拉到网页摘要」。另：直接打开 `dist-web` 静态文件没有 `/search-proxy`，必须用 `npm run dev:ui` 或自建反代。

## 配置

```bash
cd travel-skill-creator
cp .env.example .env
# 编辑 .env 填入 ARK_API_KEY
```

**`.env` 为什么会被「清空」？** 本仓库里的代码**不会**自动删除或重置 `.env`。常见原因只有这几类：

1. **执行了 `cp .env.example .env`**：会**整文件覆盖**已有 `.env`，模板里若密钥行为空，看起来就像被清空了。**已有 `.env` 时不要再用 cp 覆盖**；只缺某一行就用手动编辑补上。
2. **改错文件**：搜索相关变量必须写在 **`.env`**（或下面的 **`.env.local`**）里；只改 **`.env.example`** 不会让运行中的 Vite 读到密钥（example 只是给别人抄的模板）。
3. **多份项目目录 / 同步盘**：在另一份拷贝里改的配置，不会同步到你当前打开的这一份。

**更稳的做法：** 把密钥放在 **`.env.local`**（与 `.env` 同级）。Vite 会合并 `.env` + `.env.local`，且 `.env.local` 已列入 `.gitignore`，一般也不会被「照抄 example」误覆盖。

可选环境变量：

| 变量 | 默认 |
|------|------|
| `ARK_BASE_URL` | `https://ark.cn-beijing.volces.com/api/v3` |
| `ARK_MODEL` | `doubao-seed-2-0-pro-260215` |
| `SKILLS_DIR` | `./skills`（绝对路径亦可） |
| `VITE_ARK_ROUTER_MODEL` | 空则与主模型相同；**游客选技能**专用，可走更小模型省延迟 |
| `VITE_ROUTER_KEYWORD_HEURISTIC` | 默认关：游客每轮走**语义路由**（`routeVisitorSkill`），从**达人已创建技能 + 内置技能**中选子 Skill；`true` 时先关键词抢选（省一次路由请求） |

## 安装与运行

```bash
npm install
npm run creator
```

### 可视化界面（推荐演示）

全链路 UI 与仓库内 `skill_real_demo.jsx` **同构**：① 元技能（**Skill Creator**）说明与文件树 → ② 旅小哇 Creator（`SYS_C`）→ ③ 技能包展示 → ④ 旅小哇游客（`SYS_U` + 达人 Skill 全文）。差异仅在于本实现通过 **火山方舟 Responses** 调豆包。

```bash
npm run dev:ui
```

浏览器打开终端里打印的地址（默认 `http://localhost:5173/`；若 `localhost` 打不开可试 **`http://127.0.0.1:5173/`**）。

**注意：必须先保持该命令在终端里运行**，关掉终端或按 Ctrl+C 后页面会无法访问。

若提示端口被占用，Vite 会自动改用 `5174` 等端口，请以终端输出为准。

**网页端不再提供 Key 输入框**：与 CLI 一样，在项目目录配置 `.env` / `.env.local` 中的 **`ARK_API_KEY`**（可选 **`ARK_MODEL`**）。Vite 启动时会读入并注入前端；修改 `.env` 后需**重启** `npm run dev:ui`。未配置 Key 时**不会**向方舟发请求，因此**不会产生豆包计费**；配置正确后，每次发送/首轮自动对话都会 `POST /ark-proxy/responses`，计费以控制台为准。

开发模式下请求走 Vite 代理 ` /ark-proxy ` → `ark.cn-beijing.volces.com`，避免浏览器 CORS。**生产环境**需自行配置 Nginx 等同源反向代理；**切勿**把带密钥的 `dist-web` 暴露公网（密钥会进打包产物）。

```bash
npm run build:ui   # 输出到 dist-web/
```

演示时若需现成话术，可复制 **`DEMO_INPUTS.md`** 中的段落到输入框（页面不再提供「演示输入」一键填入）。

- 与达人多轮对话，收齐场景、触发词、输入输出契约、禁忌、步骤、参考知识等。
- 说 **「导出」** 或输入 **`/export`**，模型会输出带 `skill-package` 标记的 JSON 代码块；若解析成功，会询问是否写入 `skills/<slug>/`。
- 若模型在普通回复里已包含同种代码块，程序也会提示是否落盘。

### 模拟游客使用

**Web ④ 游客**：已改为 **Agent 流水线**（主调度 Skill + 内置行程子 Skill + 行程向用户画像字段 + 模拟工具 + 标记解析）；宽屏右侧为「后端处理流程」追踪。CLI 仍为单 Skill 注入：

```bash
npm run use -- skills/<slug>
```

会读取该目录下的 `SKILL.md`，把全文注入系统提示，多轮回答游客问题。

无需先调用 Creator 时，可直接试用内置示例：

```bash
npm run use -- examples/demo-seafood
```

## 目录约定（与研讨一致）

落盘后示例：

```
skills/
  jeju-seafood-guide/
    SKILL.md          # 含 YAML frontmatter + 步骤 + 参考索引
    INDEX.md          # 可选：索引/状态
    reference/*.md    # 可选：达人提供的详细参考
```

## API 说明

使用与用户提供的 curl 相同的 Endpoint：`POST {ARK_BASE_URL}/responses`，请求体含 `model` 与 `input`（`input_text` / `input_image` 片段）。若方舟对 `system`/`assistant` 角色与多轮格式有限制，CLI 会自动回退为「单条 user 拼接 transcript」，以保证演示可跑通。

### 401 `AuthenticationError` / `API key format is incorrect`

- **`.env` 里只填密钥本体**，不要写 `Bearer ` 前缀（HTTP 头会自动加 `Bearer`）。
- Key 须来自 **火山方舟控制台 → API Key 管理**，并与当前使用的接入地域一致（默认北京 `ark.cn-beijing`）。
- 勿混用火山引擎其它产品线的 Key；粘贴时避免首尾空格、引号或从文档里带出的隐藏字符。
- CLI 与网页请求前会对 Key 做规范化（去 `Bearer`、去零宽字符等）；若仍 401，在控制台重新创建 Key 再试。

生产构建的静态站没有 Vite 代理时，需在网关把 `/ark-proxy` 反向代理到同一地域的方舟 API，否则也可能表现为鉴权失败。

## 文档与参考资产（仓库内阅读）

以下目录/文件**仅供产品与研发对照**，**默认不参与 Vite 打包与运行时加载**；线上演示与游客 Agent 仍以 `src/ui`（含 `skillBuiltinMarkdown.js`、`demoPrompts.js`、`agent/*`）及 **`assets/nanwan_sea_play_products.json`** 为准。

| 路径 | 说明 |
|------|------|
| `docs/wechat-bundle-skill.md` | 外发包中的总述型 `SKILL.md` 归档，与 Creator 运行时 `SYS_C` 并存为文档，勿与 `examples/*/SKILL.md` 混淆。 |
| `references/` | 内置 Skill 拆条、本体、路由/检索规则等 Markdown 与一份 `references/nanwan_sea_play_products.json`（与 `assets/` 下现行 JSON 可人工 diff，**运行时商品解析以 `assets/` 为准**）。 |
| `scripts/*.md` | 与 `vite.search-proxy.ts`、解析与路由相关的说明文档。 |
| `assets/mock_data/` | 结构化演示样例（活动/景点/酒店等）。 |
| `assets/poi_data.md`、`assets/webapp_config.md` | POI/前端配置说明，与 `src/ui/weizhouPoi.js` 等实现对照用。 |