# Tihao SOP 下载安装指南

适用包名：

```text
@vocmarket/tihao
```

当前版本：

```text
1.0.9
```

适用对象：

- 客户侧商务、运营或投放同事：在 Claude Code 中上传/指定 Brief，生成可复核的博主名单。
- 内部交付同事：给客户安装、验收、排查环境问题。
- 开发/发布同事：确认 npm 包名、安装命令、版本更新与本地验证流程。

> 说明：本指南不包含接口定价。价格与套餐以后单独维护，避免客户侧文档和实际计费口径不一致。

## 1. 安装前准备

客户电脑或演示机需要具备：

- 已安装 Node.js，建议 Node.js 18 或更高版本。
- 已安装 Claude Code，并能打开目标工作区。
- 能访问 npm registry。
- 如需使用真实数据 live 模式，需要已开通的 Tihao / VOC 电商数据中台 token。

检查 Node.js：

```powershell
node -v
npm -v
```

## 2. 推荐安装方式：工作区安装

在需要使用提号 SOP 的项目目录中打开终端，执行：

```powershell
npx --yes @vocmarket/tihao@latest workspace --smoke
```

安装成功后，会在当前工作区写入：

```text
.mcp.json
.claude/plugins/tihao
.claude/skills/tihao/SKILL.md
```

`--smoke` 会自动做一次本地检查，确认：

- npm 包可正常下载；
- Claude Code 插件文件已复制到工作区；
- MCP server 入口可识别；
- 提号技能入口可识别；
- 不需要真实 token 也能完成基础安装验收。

安装完成后，建议重启 Claude Code 或刷新当前工作区，让新的 skill 和 MCP server 生效。

## 3. 全局安装方式

如果内部交付同事需要在多套客户工作区重复安装，可以先全局安装：

```powershell
npm install -g @vocmarket/tihao
```

如果要安装到当前用户的 Claude Code 全局目录，执行：

```powershell
tihao install --smoke
```

它会写入：

```text
%USERPROFILE%\.claude\plugins\tihao
%USERPROFILE%\.claude\skills\tihao\SKILL.md
```

如果要使用这个全局 CLI 安装到某个客户项目，进入该工作区后执行：

```powershell
tihao workspace --smoke
```

全局安装适合内部交付机；客户侧优先推荐第 2 节的 `npx` 工作区安装方式，因为命令更短，也更容易固定到最新发布版本。

## 4. 在 Claude Code 中使用

安装完成后，在 Claude Code 中用自然语言描述即可。例如：

```text
读取 E:\workspace\tihao-ai\dha_brief.xlsx，按照提号 SOP 给我一版小红书博主名单。
```

这类“读取 brief / 出博主名单 / 提号 / 选号 / 商务可用名单”请求默认按 live 小规模检索处理，首轮使用 `keywordLimit=1`、`pagesPerKeyword=1`。如果缺少 token 或额度，技能包会提示补 token、开通或充值，不会静默改成 sample。

或先跑无消耗演示：

```text
先用 sample 模式跑通这个 brief，输出商务可复核名单。
```

真实数据小规模验证：

```text
用 live 小规模检索这个 brief，keywordLimit=1，pagesPerKeyword=1。
```

常见输入材料：

- `.xlsx` 客户 Brief；
- `.xls` 表格型 Brief；
- `.md` 或 `.txt` 文本 Brief；
- Brief 中的参考博主、参考链接、平台目标、粉丝量要求、内容风格、禁投规则等。

## 5. Token 配置

sample 模式不需要 token。

live 模式需要平台侧可用 token。任选一种方式配置。

当前终端临时配置：

```powershell
$env:TIHAO_SESSION_TOKEN="<Parse sessionToken>"
$env:TIHAO_COMPANY="<Company objectId>"
```

写入当前工作区 `.env.local`：

```text
TIHAO_SESSION_TOKEN=<Parse sessionToken>
TIHAO_COMPANY=<Company objectId>
```

兼容变量名：

```text
TIHAO_SESSION_TOKEN
VOC_ECOMMERCE_TOKEN
VOC_TOKEN
TIHAO_COMPANY
VOC_ECOMMERCE_COMPANY
COMPANY_OBJECT_ID
```

安全要求：

- 不要把真实 token 发到群里。
- 不要把 `.env.local` 提交到 git。
- 不要把 token 写进 Brief、报告或交付文档。
- 客户侧演示优先用 sample 模式确认流程，再切 live 模式做小规模验证。

## 6. 输出文件

每次运行会输出三类结果：

```text
tihao-sourcing-report.md
tihao-sourcing-result.json
tihao-sourcing-client-list.csv
```

用途：

- `tihao-sourcing-report.md`：给商务和客户看的可读报告。
- `tihao-sourcing-result.json`：给后续系统或二次分析使用的结构化结果。
- `tihao-sourcing-client-list.csv`：给商务筛选、导入表格或继续补充报价信息。

Claude Code 聊天窗口里也会直接返回核心名单摘要，客户不需要只靠文件路径找结果。

## 7. 验收命令

客户侧安装验收：

```powershell
npx --yes @vocmarket/tihao@latest workspace --smoke
```

本地源码验收：

```powershell
cd E:\workspace\tihao-ai\claude-code-tihao-sourcing
npm run smoke:package
npm run smoke:briefs
npm run mcp:smoke
npm run acceptance
```

真实数据 live 验收需要有效 token 和额度：

```powershell
cd E:\workspace\tihao-ai\claude-code-tihao-sourcing
$env:TIHAO_SESSION_TOKEN="<Parse sessionToken>"
$env:TIHAO_COMPANY="<Company objectId>"
npm run live:preflight -- --strict
npm run live:acceptance
```

如果没有有效 token，不要把 live 验收写成已通过；只能说明 sample、安装和本地流程已通过。

真实 provider / 视频 / 长跑验收：

```powershell
npm run acceptance:providers:mock
npm run acceptance:video-ab
npm run overnight:quality
```

`acceptance:video-ab` 和真实 `overnight:quality` 需要运行时提供 VOC social、视频分析 URL、模型和 token。模型固定使用：

```text
doubao-seed-2-0-pro
```

商务标注后统计质量指标：

```powershell
npm run review:metrics -- --input <已标注CSV> --output <输出目录>
```

准备真实历史样本后验证是否够做长期优化：

```powershell
npm run history:audit -- --input <history-dataset目录> --output <输出目录> --strict
```

没有真实客户最终选择字段时，不要宣称客户选中率达到 30%/50%；只能统计商务复核通过率。

## 8. 更新版本

客户侧更新到最新版本：

```powershell
npx --yes @vocmarket/tihao@latest workspace --smoke
```

如果本机 npm 缓存导致拿到旧版本，可以换一个临时缓存：

```powershell
$cache = Join-Path $env:TEMP "npm-cache-tihao"
npx --yes @vocmarket/tihao@latest workspace --smoke --cache $cache
```

查看 npm 最新版本：

```powershell
npm view @vocmarket/tihao version
```

## 9. 卸载

工作区卸载时，删除当前项目下这些文件或目录：

```text
.claude/plugins/tihao
.claude/skills/tihao
```

然后检查 `.mcp.json`，删除 `tihao` 对应配置。
如果曾经安装过 1.0.7 或更早版本，也可以删除旧目录 `.claude/plugins/tihao-sourcing`；1.0.8 起安装器会自动清理该 legacy plugin 目录。
如果曾经安装过 1.0.5 或更早版本，也可以删除旧目录 `.claude/skills/tihao-creator-sourcing`；1.0.6 起安装器会自动清理该 legacy skill 目录。

如果曾经做过全局安装，可以执行：

```powershell
npm uninstall -g @vocmarket/tihao
```

## 10. 常见问题

### npx 提示找不到包

确认包名必须是：

```text
@vocmarket/tihao
```

不要再使用旧临时包名：

```text
@gangvy/claude-code-tihao-sourcing
@gangvy/tihao-sop
@vocmarket/tihao-sop
```

旧包名只保留迁移提示，客户安装统一使用 `@vocmarket/tihao`。

### 安装后 Claude Code 没识别技能

处理顺序：

1. 确认安装命令是在目标工作区目录执行的。
2. 确认 `.claude/skills/tihao/SKILL.md` 存在。
3. 确认 `.mcp.json` 里存在 `tihao`。
4. 重启 Claude Code 或重新打开工作区。

### live 提示需要 token

说明当前工作区没有读到可用的 token。按第 5 节重新配置：

```text
TIHAO_SESSION_TOKEN
```

或：

```text
VOC_ECOMMERCE_TOKEN
VOC_TOKEN
```

### live 提示需要开通或充值

说明账号或公司维度的 `/apig/voc-e-commerce` 权限、额度或余额不足。

技能包会返回友好的开通/充值提示，不会把原始鉴权报错、上游错误体或 token 暴露给客户。

### 只想演示流程，不想消耗额度

使用 sample 模式：

```text
先用 sample 模式按这个 brief 跑一版提号名单。
```

sample 模式适合演示：

- Brief 读取；
- 提号规则识别；
- 博主名单结构；
- 偏好记忆；
- 报告和 CSV 输出。

它不代表真实平台库存结果，正式交付前仍需用 live 模式小规模复核。

## 11. 内部发布提示

内部发布时使用包内 npm 脚本，不要手写散装命令：

```powershell
cd E:\workspace\tihao-ai\claude-code-tihao-sourcing
npm run publish:dry
npm run publish:npm
```

发布前必须确认：

- `package.json` 版本号已更新；
- `npm run acceptance` 已通过；
- 文档没有真实 token、价格、未确认承诺；
- npm 登录态或 npm token 有发布 `@vocmarket/tihao` 的权限。

发布到不同包名不需要新 npm token，前提是当前 npm 账号或 token 对目标 scope/package 有发布权限。包名变化由 `package.json` 的 `name` 决定。