@vocmarket/tihao-sop 0.1.14

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "tihao-sourcing",
+  "description": "Tihao AI creator sourcing skills for Claude Code: upload/read client briefs, generate business-ready blogger lists, use sample or live VOC e-commerce data, handle token/recharge states, and keep sourcing preference memory.",
+  "version": "0.1.14",
+  "author": {
+    "name": "nkkj-BrainHack"
+  }
+}

package/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "tihao-sourcing": {
+      "command": "node",
+      "args": [
+        "E:\\workspace\\tihao-ai\\claude-code-tihao-sourcing\\.claude\\plugins\\tihao-sourcing\\mcp\\src\\server.js"
+      ]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,66 @@
+# Tihao SOP
+
+Claude Code 技能包：按提号 SOP 读取客户 Brief，生成商务可复核的博主/达人推荐名单。
+
+Published npm package:
+
+```text
+@vocmarket/tihao-sop
+```
+
+Recommended workspace install:
+
+```powershell
+npx --yes @vocmarket/tihao-sop@latest workspace --smoke
+```
+
+Full installation guide:
+
+```text
+docs/install-guide.md
+```
+
+Real-provider integration runbook:
+
+```text
+docs/live-provider-integration-runbook.md
+```
+
+## What It Does
+
+- `sample` 模式：无 token 跑通 brief -> 博主名单流程。
+- `live` 模式：调用公司 `voc-e-commerce` 代理接口，使用 JustOne-backed 数据。
+- 输出 Markdown、JSON、CSV 三份结果。
+- 无 token、401、403、额度不足时返回友好的开通/充值提示，不暴露原始错误或 token。
+- 支持偏好记忆，把客户反馈沉淀到下次选号。
+- 支持参考博主链接、TikHub-compatible 基线补证接口和 ffmpeg/ASR/Vision-ready 证据卡接口；真实 provider 通过 `docs/live-provider-integration-runbook.md` 单独验收。
+
+## Local Development
+
+```powershell
+npm install
+npm run sample
+npm run smoke:package
+npm run acceptance
+```
+
+Workspace install from local source:
+
+```powershell
+node install.js --workspace --smoke
+```
+
+Live small run:
+
+```powershell
+$env:TIHAO_SESSION_TOKEN="<your-session-token>"
+$env:TIHAO_COMPANY="<your-company-object-id>"
+npm run live
+npm run live:acceptance
+```
+
+## MCP Tools
+
+- `tihao_brief_sourcing_run`
+- `tihao_token_check`
+- `tihao_preference_update`

package/bin/tihao-sourcing.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const command = process.argv[2] || 'help';
+const root = path.resolve(__dirname, '..');
+
+if (command === 'install' || command === 'workspace') {
+  const args = [path.join(root, 'install.js')];
+  if (command === 'workspace') args.push('--workspace');
+  args.push(...process.argv.slice(3));
+  const result = spawnSync(process.execPath, args, { stdio: 'inherit', cwd: process.cwd() });
+  process.exit(result.status || 0);
+}
+
+if (command === 'sample') {
+  const result = spawnSync(process.execPath, [
+    path.join(root, 'mcp/src/tools/tihao-brief-sourcing-run.js'),
+    '--collection-mode',
+    'sample',
+    ...process.argv.slice(3)
+  ], { stdio: 'inherit', cwd: process.cwd() });
+  process.exit(result.status || 0);
+}
+
+console.log([
+  'tihao-sourcing commands:',
+  '  tihao-sourcing install              Install plugin to user Claude directory',
+  '  tihao-sourcing workspace --smoke    Install plugin into current workspace and run smoke',
+  '  tihao-sourcing sample --brief <file> Run sample brief-to-blogger-list workflow'
+].join('\n'));

package/docs/acceptance-checklist.md

@@ -0,0 +1,110 @@
+# Acceptance Checklist
+
+Updated: 2026-06-04
+
+## Automated Gates
+
+Run from the package root:
+
+```powershell
+npm install
+npm run acceptance
+```
+
+The acceptance script verifies:
+
+- package smoke: sample brief-to-list workflow writes Markdown, JSON, and CSV;
+- brief parser extracts the demo brief brand, platform target count, and fan range;
+- preference memory update writes a memory JSON;
+- no-token live path returns `needs_token` with `errors=[]`;
+- mocked 403 returns `needs_recharge` with `errors=[]`;
+- mocked 401 returns `needs_valid_token` with `errors=[]`;
+- mocked 200 live response normalizes at least one creator;
+- product-manager acceptance audit verifies report sections, reference anchors, evidence cards, CSV/JSON evidence fields, and no token/provisional-pricing leakage;
+- MCP protocol smoke connects to the server, lists tools, and calls sample/token tools;
+- `npm pack --dry-run` includes only intended package files;
+- workspace install writes `.mcp.json`, `.claude/plugins/tihao-sourcing`, and `.claude/skills/tihao-creator-sourcing`.
+
+Dedicated product audit:
+
+```powershell
+npm run acceptance:pm
+```
+
+This audit runs a DHA-style sample with reference baselines and multimodal evidence cards, then checks that:
+
+- Markdown includes reference anchors, multimodal evidence cards, business list, review advice, and generated files;
+- JSON keeps `referenceLinks`, `referenceStyleAnchors`, `evidenceCards`, `referenceSimilarity`, and evidence signals;
+- CSV keeps `referenceSimilarity`, `evidenceSignals`, and `evidenceRiskHints`;
+- reports do not leak tokens or provisional pricing.
+
+Provider contract audit:
+
+```powershell
+npm run acceptance:providers:mock
+```
+
+This verifies the TikHub-compatible reference enrichment contract and multimodal evidence-card contract with a local mock provider.
+
+When real provider credentials are available, run:
+
+```powershell
+$env:TIKHUB_BASE_URL="<reference enrichment provider>"
+$env:TIKHUB_TOKEN="<optional tikhub token>"
+$env:TIHAO_EVIDENCE_BASE_URL="<multimodal evidence provider>"
+$env:TIHAO_EVIDENCE_TOKEN="<optional evidence provider token>"
+npm run acceptance:providers
+```
+
+The real provider gate verifies:
+
+- reference links can become at least one `referenceBaseline`;
+- candidates receive `referenceSimilarity`;
+- the evidence provider returns at least one `evidenceCard`;
+- candidates receive `evidenceSignals`;
+- provider results do not leak Authorization headers or env tokens.
+- mocked provider requests include `contractVersion=tihao-provider-v1`, reference links/style anchors, evidence creators, requested evidence capabilities, and optional evidence Authorization.
+- mocked Doubao video analysis contract verifies `doubao-seed-2-0-pro`, Authorization, requested visual capabilities, and OpenAI-style JSON evidenceCards parsing.
+
+Detailed real-provider runbook:
+
+```text
+docs/live-provider-integration-runbook.md
+```
+
+## Manual Live Gate
+
+Run only with a safe test account and enough quota:
+
+```powershell
+$env:TIHAO_SESSION_TOKEN="<Parse sessionToken>"
+$env:TIHAO_COMPANY="<Company objectId>"
+npm run live:acceptance
+```
+
+This gate verifies the real online `voc-e-commerce` proxy and billing path at the smallest useful scale:
+
+- `keywordLimit=1`;
+- `pagesPerKeyword=1`;
+- at least one live candidate is produced;
+- Markdown/JSON/CSV files are written;
+- the token is not present in the returned result.
+
+## Current Known Limit
+
+The package cannot prove the real online live gate unless a valid Parse `sessionToken` and `Company objectId` are available in the environment. The automated suite uses a local mock server to verify all user-facing auth/recharge states without consuming quota.
+
+## Customer-Ready Criteria
+
+The package is customer-demo ready when:
+
+- `npm run acceptance` passes;
+- a sample brief report shows target count, current candidate count, platform coverage, and gaps;
+- reference links and evidence cards are visible in the report when provided;
+- no raw 401/403/upstream body is shown in chat output;
+- no token appears in reports or structured results;
+- workspace install succeeds in a fresh temp directory.
+
+The package is production-live ready when the manual live gate also passes with the customer's own test token and company.
+
+The package is multimodal-live ready only when `npm run acceptance:providers` passes against the real TikHub/evidence providers, and at least one real ffmpeg/ASR/Vision evidence card has been reviewed manually.

package/docs/capability-map.md

@@ -0,0 +1,14 @@
+# Capability Map
+
+| Capability | Tool | Mode | Output |
+| --- | --- | --- | --- |
+| Brief parsing | `tihao_brief_sourcing_run` | sample/live | structured criteria |
+| Reference blogger anchors | `tihao_brief_sourcing_run` | sample/live | referenceLinks, referenceStyleAnchors, referenceSignals |
+| Reference baseline cache | `tihao_brief_sourcing_run` | sample/live | referenceBaselines, referenceSimilarity, referenceHitPoints |
+| Reference enrichment provider | `tihao_brief_sourcing_run` | sample/live | optional TikHub-compatible baseline enrichment with friendly warnings |
+| Multimodal evidence cards | `tihao_brief_sourcing_run` | sample/live | evidenceCards, visual/asr/text signals, manual-review hints |
+| Real provider runbook | docs | manual/live | `docs/live-provider-integration-runbook.md` |
+| Blogger list generation | `tihao_brief_sourcing_run` | sample/live | Markdown, JSON, CSV |
+| Token check | `tihao_token_check` | live | friendly state |
+| Preference memory | `tihao_preference_update` | sample/live | memory JSON |
+| No-token/recharge UX | `tihao_brief_sourcing_run` | live | payment link with `errors=[]` |

package/docs/install-guide.md

@@ -0,0 +1,309 @@
+# Tihao SOP 下载安装指南
+
+适用包名：
+
+```text
+@vocmarket/tihao-sop
+```
+
+适用对象：
+
+- 客户侧商务、运营或投放同事：在 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-sop@latest workspace --smoke
+```
+
+安装成功后，会在当前工作区写入：
+
+```text
+.mcp.json
+.claude/plugins/tihao-sourcing
+.claude/skills/tihao-creator-sourcing/SKILL.md
+```
+
+`--smoke` 会自动做一次本地检查，确认：
+
+- npm 包可正常下载；
+- Claude Code 插件文件已复制到工作区；
+- MCP server 入口可识别；
+- 提号技能入口可识别；
+- 不需要真实 token 也能完成基础安装验收。
+
+安装完成后，建议重启 Claude Code 或刷新当前工作区，让新的 skill 和 MCP server 生效。
+
+## 3. 全局安装方式
+
+如果内部交付同事需要在多套客户工作区重复安装，可以先全局安装：
+
+```powershell
+npm install -g @vocmarket/tihao-sop
+```
+
+之后进入任意客户工作区，执行：
+
+```powershell
+tihao-sourcing workspace --smoke
+```
+
+全局安装适合内部交付机；客户侧优先推荐第 2 节的 `npx` 工作区安装方式，因为命令更短，也更容易固定到最新发布版本。
+
+## 4. 在 Claude Code 中使用
+
+安装完成后，在 Claude Code 中用自然语言描述即可。例如：
+
+```text
+读取 E:\workspace\tihao-ai\dha_brief.xlsx，按照提号 SOP 给我一版小红书博主名单。
+```
+
+或先跑无消耗演示：
+
+```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-sop@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:acceptance
+```
+
+如果没有有效 token，不要把 live 验收写成已通过；只能说明 sample、安装和本地流程已通过。
+
+## 8. 更新版本
+
+客户侧更新到最新版本：
+
+```powershell
+npx --yes @vocmarket/tihao-sop@latest workspace --smoke
+```
+
+如果本机 npm 缓存导致拿到旧版本，可以换一个临时缓存：
+
+```powershell
+$cache = Join-Path $env:TEMP "npm-cache-tihao-sop"
+npx --yes @vocmarket/tihao-sop@latest workspace --smoke --cache $cache
+```
+
+查看 npm 最新版本：
+
+```powershell
+npm view @vocmarket/tihao-sop version
+```
+
+## 9. 卸载
+
+工作区卸载时，删除当前项目下这些文件或目录：
+
+```text
+.claude/plugins/tihao-sourcing
+.claude/skills/tihao-creator-sourcing
+```
+
+然后检查 `.mcp.json`，删除 `tihao-sourcing` 对应配置。
+
+如果曾经做过全局安装，可以执行：
+
+```powershell
+npm uninstall -g @vocmarket/tihao-sop
+```
+
+## 10. 常见问题
+
+### npx 提示找不到包
+
+确认包名必须是：
+
+```text
+@vocmarket/tihao-sop
+```
+
+不要再使用旧临时包名：
+
+```text
+@gangvy/claude-code-tihao-sourcing
+@gangvy/tihao-sop
+```
+
+旧包名只保留迁移提示，客户安装统一使用 `@vocmarket/tihao-sop`。
+
+### 安装后 Claude Code 没识别技能
+
+处理顺序：
+
+1. 确认安装命令是在目标工作区目录执行的。
+2. 确认 `.claude/skills/tihao-creator-sourcing/SKILL.md` 存在。
+3. 确认 `.mcp.json` 里存在 `tihao-sourcing`。
+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-sop` 的权限。
+
+发布到不同包名不需要新 npm token，前提是当前 npm 账号或 token 对目标 scope/package 有发布权限。包名变化由 `package.json` 的 `name` 决定。