# Claude Code 原生版 VOC 技能包设计说明

更新时间：2026-05-22

## 目标修正

这里不是把 OpenClaw 技能包“迁移”成 Claude Code 版本，也不是兼容旧 `api-config.json`。

正确目标是：

> 为 Claude Code 重新写一套原生 VOC 技能包。旧 OpenClaw 技能包只作为业务流程、接口口径、数据结构、样例输出和测试经验参考。

也就是说：

- OpenClaw 版本继续保留。
- Claude Code 版本独立成包。
- 两套包可以共用底层 API 文档和部分业务算法思想，但目录结构、调用方式、技能说明、安装方式、运行协议都重新设计。

## Claude Code 版本应该长什么样

Claude Code 版本不建议做成一堆零散技能，而应该做成一个原生插件套件：

```text
claude-code-voc-intelligence/
  .claude-plugin/
    plugin.json

  skills/
    voc-setup/
      SKILL.md
      references/
        onboarding.md

    douyin-speaking-daily/
      SKILL.md
      references/
        user-workflows.md
        output-format.md
        script-co-creation.md
      examples/
        daily-report.md
        script-session.md

    douyin-video-transcript/
      SKILL.md
      references/
        provider-iflytek-gateway.md
        transcript-schema.md

    social-trend-intelligence/
      SKILL.md
      references/
        xiaohongshu-workflow.md
        industry-profile.md
        trend-report-format.md

  mcp/
    package.json
    src/
      server.ts
      tools/
        douyin-speaking-daily.ts
        douyin-video-transcript.ts
        douyin-search.ts
        douyin-comments.ts
        xiaohongshu-search.ts
        xiaohongshu-comments.ts
        social-trend-report.ts
        voc-token.ts
      core/
        credentials.ts
        http-client.ts
        result-envelope.ts
        workspace.ts
        memory-store.ts
        report-writer.ts
        transcript-cache.ts
      providers/
        voc-social-api.ts
        iflytek-gateway.ts

  hooks/
    preflight-token-check.ts
    postrun-archive.ts

  memory-templates/
    douyin-speaking-profile.json
    social-trend-profile.json
    script-preference-memory.json

  bin/
    voc-mcp.cmd
    voc-mcp

  README.md
  package.json
```

这个包和 OpenClaw 目录平级，不要塞回 `douyin/` 或 `industry-trend-intelligence/` 旧目录里。

## 和 OpenClaw 版本的区别

| 维度 | OpenClaw 版本 | Claude Code 原生版 |
| --- | --- | --- |
| 技能识别 | `SKILL.md + api-config.json` | `skills/<name>/SKILL.md` |
| 工具调用 | OpenClaw 读取 `api-config.json` | Claude Code 通过 MCP tools 调用 |
| 用户入口 | OpenClaw 聊天触发技能 | Claude Code Skill 自动触发或 `/skill-name` |
| 参数协议 | `{{profile}}`、`{{output}}` 模板参数 | MCP JSON schema + Skill 自然语言说明 |
| 输出协议 | stdout prefix JSON + `assistantMessage` | MCP structured result + Skill 展示策略 |
| 打包方式 | zip + `install.js` 安装到 `.openclaw` | Claude Code plugin / skills / MCP package |
| 记忆目录 | `.openclaw/workspace/memory` 或项目 `memory` | plugin data dir / project `.claude` / configurable memory root |

结论：

Claude Code 版本不应该继续依赖 `api-config.json` 作为主协议。可以参考其字段，但应重新定义 MCP tool schema。

## 哪些旧东西可以复用

### 可以复用业务流程

这些流程已经被测试过，应该复用为 Claude Code Skill 的工作流：

1. 抖音口播日报：建档、采集、评论、逐字稿、日报、校准。
2. 爆款视频逐字稿：链接解析、媒体下载、讯飞网关、transcript schema。
3. 脚本共创：选题、v0、反馈改稿、定稿、偏好沉淀。
4. 行业趋势情报官：行业建档、关键词矩阵、小红书采集、评论洞察、趋势报告。
5. 偏好记忆：保留方向、禁区方向、视角偏好、案例偏好。

### 可以复用数据结构

建议保留这些核心 schema 思想：

```text
assistantMessage
summary
warnings
errors
files
daily-report.json
transcript.json
script-session.json
profile.json
memory.json
```

但 Claude Code 版本要重新定义更干净的 schema，不要完全照搬 OpenClaw 里的历史字段。

### 可以复用接口经验

可以参考：

- 抖音搜索接口怎么返回视频。
- 抖音评论接口怎么分页。
- 抖音视频解析如何找音频 URL。
- 讯飞网关上传和查询如何跑。
- 小红书搜索、详情、评论如何组合。
- VOC token 如何鉴权。

但 Claude Code 版本应重新写 API client，不建议直接把旧 runner 当黑盒调用。

### 可以复用测试样本

可以把旧测试样本转成 Claude Code 版本 fixtures：

```text
claude-code-voc-intelligence/tests/fixtures/
  douyin-daily-sample-input.json
  douyin-daily-sample-output.json
  transcript-sample.json
  xiaohongshu-trend-sample.json
```

## 哪些旧东西不要复用

### 不要复用 OpenClaw `api-config.json` 作为 Claude Code 主协议

原因：

- Claude Code 不认识它。
- MCP 已经有自己的 JSON schema 工具协议。
- 原来的 `{{param}}` 模板适合 OpenClaw，不适合 Claude Code 原生工具调用。

可以写一个转换脚本辅助生成初版 MCP schema，但不要让 Claude Code 运行时依赖它。

### 不要复用旧技能目录作为 Claude Code 技能目录

不要这样：

```text
douyin/douyin-speaking-daily-runner/SKILL.md
```

而应该这样：

```text
claude-code-voc-intelligence/skills/douyin-speaking-daily/SKILL.md
```

### 不要复用旧 runner 的大而全主入口

旧 runner 为了 OpenClaw 闭环承担了太多事情。

Claude Code 版本应该拆开：

```text
MCP tool: voc_douyin_daily_run
MCP tool: voc_douyin_script_create
MCP tool: voc_douyin_script_revise
MCP tool: voc_douyin_script_finalize
MCP tool: voc_douyin_transcript_video
MCP tool: voc_social_trend_run
```

Skill 再负责把这些工具串成自然语言工作流。

### 不要让用户接触技术参数

Claude Code Skill 里也不要让用户说：

```text
profile=...
autoTranscriptTopN=1
autoTranscriptProvider=iflytek-gateway
```

用户应该说：

```text
启动抖音口播每日稿件日报。
选题2，进入脚本共创。
开头更狠一点，换老板视角。
定稿。
```

## Claude Code 原生版的技能拆分

建议第一版只做 4 个用户可见技能。

### 1. `voc-setup`

用途：

- 配置 VOC token。
- 检查余额。
- 初始化用户工作目录。
- 创建默认 profile。
- 解释技能包能做什么。

用户话术：

```text
帮我初始化 VOC 技能包。
配置我的 VOC 服务。
检查一下现在能不能采集社媒数据。
```

背后工具：

```text
voc_token_set
voc_token_check
voc_workspace_init
```

### 2. `douyin-speaking-daily`

用途：

- 生成抖音口播每日稿件日报。
- 自动补一条最值得拆的视频逐字稿。
- 展示 Top 选题。
- 支持校准偏好。
- 支持脚本共创和定稿。

用户话术：

```text
启动抖音口播每日稿件日报。
今天帮我找适合账号的爆款口播选题。
选题2，进入脚本共创。
开头更狠一点，老板视角。
定稿。
不要纯工具清单方向。
```

背后工具：

```text
voc_douyin_daily_run
voc_douyin_topic_select
voc_douyin_script_create
voc_douyin_script_revise
voc_douyin_script_finalize
voc_preference_update
```

### 3. `douyin-video-transcript`

用途：

- 用户给一个抖音视频链接。
- Claude Code 自动解析、下载媒体、转写逐字稿。
- 输出逐字稿拆解和可借鉴结构。
- 可继续生成本账号口播草案。

用户话术：

```text
帮我拆这个抖音视频。
把这个爆款视频转成逐字稿。
参考这个视频，给我的账号写一版口播稿。
```

背后工具：

```text
voc_douyin_video_resolve
voc_douyin_video_transcript
voc_script_from_transcript
```

### 4. `social-trend-intelligence`

用途：

- 面向小红书、抖音、知乎、微博等社媒趋势情报。
- 第一版可以先支持小红书。
- 适合家装全屋定制、女性消费、设计风格趋势、行业选题洞察。

用户话术：

```text
帮我做一份家装全屋定制行业的小红书趋势情报。
看看下季度女性客户更关注哪些设计元素。
帮我找小红书上最近流行的装修风格和用户顾虑。
```

背后工具：

```text
voc_social_profile_build
voc_xiaohongshu_search_notes
voc_xiaohongshu_note_detail
voc_xiaohongshu_note_comments
voc_social_trend_report
voc_social_preference_update
```

## MCP tools 设计

Claude Code 原生版建议直接用 MCP 做工具层。

### Tool 命名原则

统一前缀：

```text
voc_
```

按业务域命名：

```text
voc_douyin_daily_run
voc_douyin_video_transcript
voc_douyin_script_create
voc_douyin_script_revise
voc_douyin_script_finalize
voc_social_trend_run
voc_xiaohongshu_search_notes
voc_xiaohongshu_note_comments
voc_token_check
```

### Tool 输出原则

所有工具统一返回：

```json
{
  "status": "ok",
  "assistantMessage": "可以直接给用户看的正文",
  "summary": {},
  "data": {},
  "files": [],
  "nextActions": [],
  "warnings": [],
  "errors": []
}
```

Claude Code Skill 的要求：

> 如果工具返回 `assistantMessage`，优先把它作为主要回复，不要只告诉用户文件路径。

## 核心代码模块设计

Claude Code 原生版不要从旧 `scripts/tools/*.js` 直接开始复制，而应该重新拆核心模块。

```text
mcp/src/core/
  result-envelope.ts
  credentials.ts
  workspace.ts
  memory-store.ts
  file-store.ts
  report-writer.ts
  preference-engine.ts
  budget-guard.ts

mcp/src/providers/
  voc-social-api.ts
  iflytek-gateway.ts
  douyin-media-resolver.ts
  xiaohongshu-api.ts

mcp/src/features/
  douyin-speaking-daily/
    daily-runner.ts
    topic-ranker.ts
    transcript-selector.ts
    script-cocreation.ts
    script-memory.ts

  douyin-video-transcript/
    video-transcript-runner.ts
    transcript-normalizer.ts
    transcript-analyzer.ts

  social-trend-intelligence/
    profile-builder.ts
    keyword-matrix.ts
    collector.ts
    trend-report.ts
    preference-memory.ts
```

这样比旧 runner 更清晰，也方便 Claude Code 多工具组合。

## Skill 文档写法

每个 Skill 的 `SKILL.md` 要短，不要把所有 API 文档塞进去。

推荐结构：

```markdown
---
name: douyin-speaking-daily
description: Generate a Douyin talking-head daily content report, select viral topics, transcribe one high-value video, co-create scripts, and save preferences. Use when the user asks for 抖音口播日报、爆款选题、脚本共创、定稿 or content preference calibration.
allowed-tools: mcp__voc__voc_douyin_daily_run mcp__voc__voc_douyin_script_create mcp__voc__voc_douyin_script_revise mcp__voc__voc_douyin_script_finalize
---

## Rules

- Speak to the user in natural Chinese.
- Do not expose technical params such as profile path, output path, provider, or token unless troubleshooting.
- Prefer showing the tool's assistantMessage directly.
- If profile is missing, guide the user through 3-5 business questions.
- If the user says 选题N, enter script co-creation.
- If the user says 定稿, finalize and save preference memory.

## Workflow

1. Check profile.
2. Run daily report.
3. Show Top topics.
4. Ask for calibration.
5. Continue into script co-creation when user selects a topic.
```

详细格式放到 `references/`。

## 需要重写的部分

### 必须重写

1. Claude Code `skills/*/SKILL.md`
2. MCP server
3. MCP tools schema
4. Credential 管理
5. Memory 管理
6. Result envelope
7. Tool 输出展示策略
8. Claude Code 安装说明
9. Claude Code smoke tests

### 建议重写

1. 抖音日报 runner 内核
2. 小红书趋势 runner 内核
3. 逐字稿 runner 内核
4. 脚本共创模块
5. 偏好记忆模块

### 可以晚点重写

1. 完整报告 Markdown 模板
2. 详细 audit 文件
3. 课程教学文档
4. 多平台扩展
5. 插件 hooks

## 可以从旧代码借鉴但不要照搬的部分

| 旧文件 | 借鉴内容 | Claude Code 新写方向 |
| --- | --- | --- |
| `scripts/tools/douyin-speaking-daily-runner.js` | 完整闭环、自然语言续接、脚本共创、偏好记忆 | 拆成 `daily-runner.ts`、`script-cocreation.ts`、`preference-engine.ts` |
| `scripts/tools/douyin-video-transcriber.js` | 抖音链接解析、讯飞网关、transcript schema | 拆成 `video-resolver.ts`、`iflytek-gateway.ts`、`transcript-normalizer.ts` |
| `scripts/tools/douyin-speaking-daily-report.js` | 选题排序、日报结构、assistantMessage 输出 | 重写为 report writer + topic ranker |
| `industry-trend-intelligence/scripts/industry-trend-runner.js` | 行业趋势流程、小红书采集、偏好记忆 | 重写为 social trend feature |
| `industry-trend-intelligence/scripts/xiaohongshu-trend-collector.js` | 小红书采集策略 | 重写为 xiaohongshu provider + collector |
| `scripts/tools/set-voc-token.js` | token 存储和检查经验 | 重写为 voc setup tool |

## 第一版实施范围

建议 Claude Code 原生版第一版不要贪多，只做 3 个闭环。

### 闭环 1：VOC 初始化

```text
用户：帮我初始化 VOC 技能包
Claude：检查 token、余额、工作目录、默认 memory
```

### 闭环 2：抖音口播日报

```text
用户：启动抖音口播每日稿件日报
Claude：采集、转写一条、输出日报正文、给出校准问题
```

### 闭环 3：选题到稿件共创

```text
用户：选题2，进入脚本共创
Claude：生成 v0
用户：开头更狠，老板视角
Claude：生成 v1
用户：定稿
Claude：保存稿件和偏好
```

行业趋势/小红书可以作为第二批进入。

## 目录落地建议

在当前仓库新增：

```text
claude-code-voc-intelligence/
```

不要和旧 OpenClaw 包混在一起。

当前已经先按这个判断落地了小红书趋势情报官：

```text
claude-code-voc-intelligence/
  .claude-plugin/plugin.json
  .mcp.json
  skills/xiaohongshu-trend-intelligence/SKILL.md
  mcp/src/server.js
  mcp/src/tools/xiaohongshu-trend-run.js
  mcp/src/tools/xiaohongshu-preference-update.js
  mcp/src/providers/xiaohongshu-api.js
  mcp/src/features/xiaohongshu-trend/
  memory-templates/xiaohongshu-trend-profile.json
```

已验证的 MCP tools：

```text
voc_xiaohongshu_token_check
voc_xiaohongshu_trend_run
voc_xiaohongshu_preference_update
```

已新增独立打包脚本：

```text
scripts/deploy/claude-code-voc-intelligence-suite.js
```

本地交付产物：

```text
dist/claude-code-voc-intelligence.zip
  dist/claude-code-voc-intelligence-suite-manifest.json
```

验证方式：

```bash
npm run claude-voc:build
```

该命令会把包解压到临时目录、重新安装依赖，并在解压包里跑 sample、偏好记忆和 MCP smoke。

用户安装入口：

```bash
node install.js
```

现场自检入口：

```bash
node install.js --smoke
```

第一阶段文件：

```text
claude-code-voc-intelligence/
  skills/
    voc-setup/SKILL.md
    douyin-speaking-daily/SKILL.md
    douyin-video-transcript/SKILL.md

  mcp/
    package.json
    tsconfig.json
    src/server.ts
    src/tools/voc-token.ts
    src/tools/douyin-speaking-daily.ts
    src/tools/douyin-video-transcript.ts
    src/core/result-envelope.ts
    src/core/credentials.ts
    src/core/workspace.ts

  tests/
    smoke-douyin-daily.test.ts
    smoke-transcript.test.ts

  memory-templates/
    douyin-speaking-profile.json

  README.md
```

## P0/P1/P2 重新定义

### Claude Code P0

目标：Claude Code 原生技能能被识别，能跑 sample 模式。

交付：

- `voc-setup`
- `douyin-speaking-daily`
- `douyin-video-transcript`
- MCP server 基础版
- sample 数据模式
- 不调用真实付费接口也能演示

### Claude Code P1

目标：真实接口跑通。

交付：

- VOC token 设置和余额检查
- 抖音搜索、评论、逐字稿真实调用
- 脚本共创和定稿记忆
- 错误处理和预算保护
- Windows 中文路径测试

### Claude Code P2

目标：插件产品化。

交付：

- `.claude-plugin/plugin.json`
- hooks
- 安装脚本
- 自动更新说明
- 小红书/行业趋势技能加入
- 教学文档和录屏话术

## 关键设计判断

### 1. Skill 不负责跑业务逻辑

Skill 只负责：

- 什么时候触发。
- 怎么和用户说话。
- 调哪个 MCP tool。
- 如何展示结果。
- 后续如何续接。

业务逻辑在 MCP tool 里。

### 2. MCP tool 不负责长篇表达

MCP tool 负责：

- 拉数据。
- 算分。
- 写文件。
- 返回结构化结果。
- 生成基础 `assistantMessage`。

最终表达由 Skill 决定是否补充、压缩、追问。

### 3. Memory 是 Claude Code 版本自己的

不要直接写 `.openclaw/workspace/memory`。

建议：

```text
项目模式：<project>/.voc-memory/
插件模式：<plugin-data>/memory/
调试模式：claude-code-voc-intelligence/.tmp/memory/
```

### 4. 输出文件是备份，不是主要交付

Claude Code 用户体验要坚持：

```text
聊天里直接给结果
文件只是归档
```

## 验收标准

### 技术验收

- Claude Code 能识别 3 个 skills。
- MCP server 能启动。
- Claude 能看到 VOC tools。
- sample 模式无需 token 可跑通。
- live 模式 token 可检查余额。
- 工具返回统一 result envelope。
- 错误返回可读 `assistantMessage`。

### 用户体验验收

用户只需要说：

```text
启动抖音口播每日稿件日报。
```

不需要知道：

```text
profile
output
provider
autoTranscriptTopN
```

用户继续说：

```text
选题2，进入脚本共创。
开头更狠一点，老板视角。
定稿。
```

Claude Code 应能自然续接，不要求用户提供文件路径。

## 总结

如果是 Claude Code 原生版，就不要围绕 OpenClaw 的 `api-config.json` 做兼容适配。

正确做法是：

1. 新建独立 `claude-code-voc-intelligence/`。
2. 用 Claude Code Skill 做自然语言工作流入口。
3. 用 MCP tools 承接真实接口和业务执行。
4. 旧 OpenClaw 代码作为业务参考，不作为运行时依赖。
5. 第一版只做 VOC 初始化、抖音日报、逐字稿、脚本共创四个核心闭环。