18307996893/tihao-ai @ a301ac367ae3d27f1d2b7de4d4989aba430cfbb2

# Tihao SOP 下载安装指南

适用包名：

@vocmarket/tihao

当前版本：

1.0.9

适用对象：

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

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

1. 安装前准备

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

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

检查 Node.js：

node -v
npm -v

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

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

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

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

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

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

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

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

3. 全局安装方式

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

npm install -g @vocmarket/tihao

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

tihao install --smoke

它会写入：

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

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

tihao workspace --smoke

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

4. 在 Claude Code 中使用

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

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

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

或先跑无消耗演示：

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

真实数据小规模验证：

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

常见输入材料：

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

5. Token 配置

sample 模式不需要 token。

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

当前终端临时配置：

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

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

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

兼容变量名：

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. 输出文件

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

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. 验收命令

客户侧安装验收：

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

本地源码验收：

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 和额度：

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 / 视频 / 长跑验收：

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

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

doubao-seed-2-0-pro

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

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

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

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

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

8. 更新版本

客户侧更新到最新版本：

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

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

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

查看 npm 最新版本：

npm view @vocmarket/tihao version

9. 卸载

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

.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 目录。

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

npm uninstall -g @vocmarket/tihao

10. 常见问题

npx 提示找不到包

确认包名必须是：

@vocmarket/tihao

不要再使用旧临时包名：

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

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

安装后 Claude Code 没识别技能

处理顺序：

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

live 提示需要 token

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

TIHAO_SESSION_TOKEN

或：

VOC_ECOMMERCE_TOKEN
VOC_TOKEN

live 提示需要开通或充值

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

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

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

使用 sample 模式：

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

sample 模式适合演示：

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

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

11. 内部发布提示

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

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 决定。

install-guide.md 8.9 KB Előzmények Nyers