wjx-ai-kit：用 AI 重新定义问卷调研

问卷星官方开源 · TypeScript SDK + MCP Server + CLI 三合一工具包

一句话说清楚

wjx-ai-kit 是问卷星官方开源的 AI 开发工具包。它让你用自然语言创建问卷、用对话分析数据、用命令行自动化一切——把原来需要反复点击网页的问卷操作，变成 AI 可以直接完成的事。

AI 工具配置指南

在你常用的 AI 工具中接入问卷星。点击对应指南，5 分钟内完成配置。

不确定该用哪个？先试 Skill 包入门指南，让 AI 一句话帮你安装，最快上手。

为什么做这件事

AI 正在重塑工作方式——对 AI 说"帮我做一份员工满意度调查"，30 秒就能创建一份专业问卷。同时，企业和研究人员需要把问卷系统和 CRM、HRM、BI 打通，靠网页操作做不到。wjx-ai-kit 就是连接 AI 和问卷星的桥梁。

三个工具，一个目标

wjx-ai-kit 包含三个包，覆盖从 AI 对话到底层编程的全部场景：

MCP Server — 让 AI 直接操作问卷星

MCP 是 Anthropic 提出的 AI 工具调用协议。wjx-mcp-server 实现了 58 个工具，让 Claude、Cursor、Windsurf 等 AI 客户端可以直接操作问卷星。

• 58 个 Tools + 8 个 Resources + 22 个 Prompts
• 开箱即用：配置 API Key，接入你的 AI 工具即可使用

适合谁： 使用 AI 编程工具的开发者、想用自然语言管理问卷的企业用户

CLI — AI Agent 原生命令行

wjx-cli 是为 AI Agent 设计的命令行工具。67 个子命令覆盖问卷星全部 API 能力，输出结构化 JSON，天然适配 AI Agent 工作流和自动化脚本。

• 67 个子命令：问卷、答卷、通讯录、部门、管理员、标签、用户体系、子账号、SSO、数据分析
• AI Agent 友好：JSON 输出 + 管道输入 + 结构化错误 + Shell 补全
• 6 个离线分析命令：NPS、CSAT、异常检测、答卷解码等不需要 API Key

适合谁： AI Agent 开发者、自动化脚本编写者、命令行爱好者

SDK — 零依赖 TypeScript 基础层

wjx-api-sdk 是零运行时依赖的 TypeScript SDK，提供 48+ 类型安全的函数，覆盖问卷星 OpenAPI 全部能力。

• 零依赖：只用 Node.js 内置 API（fetch + crypto），无第三方包
• DSL 双向转换：纯文本 ↔ 问卷结构体，支持 27 种题型标签
• 本地分析引擎：NPS/CSAT 计算、异常检测、数据解码，无需网络

适合谁： 构建调研 SaaS 的开发者、需要集成问卷能力的系统、学术研究自动化

选择你的工具

你想怎么用问卷星？
│
├─ 最快上手：让 AI 帮你装 ──→ Skill 包入门指南
│
├─ 在 AI 对话中操作 ──→ 选择你的 AI 工具（见上方配置指南）
│
├─ 命令行 / 自动化脚本 ──→ CLI 入门指南
│
└─ 构建应用 / 系统集成 ──→ SDK 入门指南

三层能力递进

wjx-ai-kit 不只是 MCP Server——它还提供 Agent 定义 和 Skill 参考文档，让 AI 从"能用工具"进化到"懂业务流程"：

对比：大多数同类工具只有工具层。问卷星的 Agent + Skill 体系让 AI 像问卷星专家一样主动规划工作流。

Skill 市场

能力全景

参与贡献

wjx-ai-kit 是问卷星官方开源项目，采用 MIT 协议，欢迎社区贡献。

• GitHub: github.com/wjxcom/wjx-ai-kit
• Issues: 提交反馈
• npm: wjx-api-sdk · wjx-mcp-server · wjx-cli
• Skill 市场: Vercel Agent Skills · ClawHub

深入了解

入门指南

• Skill 包入门指南 — 最快上手，让 AI 一句话帮你安装
• MCP Server 入门指南 — 5 分钟接入 Claude/Cursor
• CLI 入门指南 — 命令行快速上手
• SDK 入门指南 — TypeScript 开发快速上手

进阶指南

• MCP Server 进阶指南 — 58 个工具深度用法、HTTP 部署、Docker
• CLI 进阶指南 — 67 个命令完全攻略、Skill 系统
• SDK 进阶指南 — DSL 引擎、分析函数、Webhook 解密

MCP Server 入门指南：让 AI 直接操作问卷星

5 分钟配置，用自然语言创建问卷、查询数据、分析结果

什么是 MCP Server

MCP (Model Context Protocol) 是 AI 工具调用的标准协议。wjx-mcp-server 让 Claude、Cursor、Windsurf 等 AI 客户端可以直接操作你的问卷星账户——创建问卷、查看答卷、做数据分析，全部用自然语言完成。

打个比方：如果问卷星是一栋大楼，MCP Server 就是给 AI 配了一把钥匙和一份楼层指南。AI 知道每个房间在哪、能做什么，你只需要说目的地。

准备工作

1. 获取问卷星 API Key

微信扫码登录 API Key 获取页，登录后页面直接显示 API Key。

企业用户如需管理通讯录，还需要获取 Corp ID（企业通讯录 ID）。登录问卷星后台 → 我的问卷 → 通讯录 → 通讯录设置，页面中会显示通讯录 ID。

2. 确认 Node.js 版本

node --version
# 需要 v20 或更高版本

如果版本低于 20，请前往 nodejs.org 下载安装最新 LTS 版本。

接入 Claude Desktop

安装

npm install -g wjx-mcp-server

配置

找到 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的API Key"
      }
    }
  }
}

保存后重启 Claude Desktop。在输入框底部会看到工具图标，点击可以看到 58 个问卷星工具已就绪。

更详细的配置说明请参阅 Claude Desktop 配置指南。

验证

对 Claude 说：

"列出我的问卷"

Claude 会调用 list_surveys 工具，返回你账户下的问卷列表。如果看到问卷数据，说明配置成功。

接入 Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的API Key"
      }
    }
  }
}

重启 Cursor，在 AI 对话中即可使用问卷星工具。

更详细的配置说明请参阅 IDE 插件配置指南。

接入 Claude Code

claude mcp add wjx --env WJX_API_KEY=你的APIKey -- npx wjx-mcp-server

Claude Code 支持完整的 Agent + Skill 体验，详见 Claude Code 配置指南。

第一个任务：创建问卷

接入完成后，试试对 AI 说：

"帮我创建一份客户满意度调查，包含：

1. NPS 推荐意愿评分（0-10）
2. 5 个维度的量表评分（产品质量、服务态度、响应速度、性价比、整体体验）
3. 一个开放建议题"

AI 会：

1. 设计问卷结构
2. 调用 create_survey_by_json（覆盖 70+ 题型，含矩阵/比重/滑块/文件上传/排序）创建问卷
3. 返回问卷 ID 和预览链接

整个过程不到 1 分钟。

常用对话示例

问卷管理

"列出我最近创建的 5 份问卷"
"获取问卷 12345 的详细信息"
"把问卷 12345 发布上线"
"暂停问卷 12345 的收集"
"删除草稿问卷 12345"

答卷查询

"问卷 12345 收到了多少份答卷？"
"查询问卷 12345 最近 7 天的答卷数据"
"下载问卷 12345 的全部答卷为 CSV"
"查看问卷 12345 的统计报告"

数据分析

"分析问卷 12345 的 NPS 得分"
"帮我做问卷 12345 的满意度分析"
"检测问卷 12345 的异常答卷（刷题、秒答等）"
"对比问卷 12345 和 67890 的关键指标"

问卷创建

"创建一份员工敬业度调查"
"帮我出一套高中物理力学考试题，20 题"
"做一份 360 度评估问卷，包含领导力、协作、创新三个维度"
"创建一份产品 NPS 调查，中英双语"

工具分类速览

MCP Server 提供 58 个工具（含 1 个系统工具 get_config），按功能分为 7 个模块：

内置参考资源

AI 可以随时查阅 8 个参考资源，不需要你提供文档：

预设 Prompt 模板

22 个预设 Prompt 提供标准化工作流：

调研分析类：

• nps-analysis — 完整 NPS 分析流程
• csat-analysis — 满意度分析 + 驱动因素识别
• cross-tabulation — 交叉分析
• sentiment-analysis — 开放题情感分析
• survey-health-check — 问卷质量诊断（0-100 健康分）
• comparative-analysis — 多问卷对比分析

问卷生成类：

• generate-survey — 通用问卷生成
• generate-nps-survey — NPS 调查生成
• generate-satisfaction-survey — 满意度调查生成
• generate-engagement-survey — 员工敬业度调查生成
• generate-360-evaluation — 360 度评估生成
• generate-exam-from-document — 从文档出考试题
• generate-exam-from-knowledge — 从知识领域出考试题

运维操作类：

• design-survey — 引导式问卷设计
• analyze-results — 数据分析工作流
• create-nps-survey — 一键创建标准 NPS 问卷
• configure-webhook — Webhook 配置向导
• anomaly-detection — 异常答卷检测
• user-system-workflow — 用户体系端到端指南

环境变量参考

常见问题

Q: 我看不到工具图标 / AI 说找不到问卷星工具

检查：

1. 配置文件路径是否正确
2. API Key 是否已填入
3. 是否重启了 Claude Desktop / Cursor
4. 运行 npx wjx-mcp-server 看是否有报错

Q: AI 创建问卷失败，说认证错误

确认 API Key 是否有效。可以在终端测试：

WJX_API_KEY=你的Key npx wjx-mcp-server

然后在 Claude 中重试。

Q: 可以在团队中共享使用吗？

可以。有两种方式：

1. 每人独立配置：每个团队成员用自己的 API Key 配置本地 MCP Server
2. HTTP 模式共享：部署一个 HTTP 模式的 MCP Server，团队共用（详见进阶指南）

Q: 支持哪些 AI 客户端？

任何支持 MCP 协议的客户端都可以接入。已验证的包括：

• Claude Desktop
• Claude Code
• Cursor
• Windsurf
• Continue.dev

下一步

• MCP Server 进阶指南 — HTTP 部署、Docker、多租户、自动化工作流
• CLI 入门指南 — 命令行工具快速上手
• 总纲 — wjx-ai-kit 全景概览

CLI 入门指南：命令行操作问卷星

安装 → 配置 → 第一个问卷，5 分钟上手

什么是 wjx-cli

wjx-cli 是问卷星的命令行工具，67 个子命令覆盖问卷星全部 API 能力。它有两个特点：

1. AI Agent 原生：默认输出 JSON，支持管道输入，结构化错误码。Claude Code、Cursor 等 AI 工具可以直接调用。
2. 人类也好用：--table 格式化输出、Shell 补全、--dry-run 预览、交互式配置向导。

安装

npm install -g wjx-cli

验证安装：

wjx --version
# wjx-cli/0.2.4

需要 Node.js >= 20。如果版本不够，运行 wjx doctor 会提示。

配置

方式 1：交互式配置（推荐新用户）

wjx init

按提示输入：

• API Key（必填）：微信扫码登录 API Key 获取页 获取
• Base URL（可选）：默认 https://www.wjx.cn
• Corp ID（可选）：企业通讯录 ID

配置保存到 ~/.wjxrc。最后会询问是否安装 Claude Code 技能包。

方式 2：参数模式（适合 AI Agent 和 CI）

wjx init --api-key 你的APIKey
wjx init --api-key 你的APIKey --base-url https://your.domain.com --corp-id org001

不弹交互，直接保存。--no-install-skill 跳过技能安装。

方式 3：环境变量

export WJX_API_KEY=你的APIKey

认证优先级

--api-key 参数 > 环境变量 WJX_API_KEY > 配置文件 ~/.wjxrc

环境检查

wjx doctor

输出示例：

✓ Node.js v22.0.0 (>= 20 required)
✓ Config file: ~/.wjxrc
✓ API Key: sk-****...****
✓ API connectivity: OK (12 surveys found)
✓ SDK version: wjx-api-sdk@0.2.4

第一个问卷

用 DSL 文本创建

wjx survey create-by-text --text "
客户满意度调查

1. 您愿意向朋友推荐我们吗？[量表题]
0~10

2. 您对以下方面的满意程度 [矩阵量表题]
行：
- 产品质量
- 服务态度
- 响应速度
列：
- 非常不满意
- 不满意
- 一般
- 满意
- 非常满意

3. 您有什么建议？[填空题]
"

也可以从文件创建：

wjx survey create-by-text --file survey.txt --publish

--publish 会在创建后自动发布问卷。

查看结果

# 列出问卷
wjx survey list

# 表格格式，人类友好
wjx --table survey list

# 获取问卷详情
wjx survey get --vid 12345

# 导出为纯文本
wjx survey export-text --vid 12345

常用命令速查

问卷生命周期

# 创建（唯一推荐：JSONL，覆盖 70+ 题型）
wjx survey create-by-json --file survey.jsonl --publish
# 已弃用命令（仅兼容保留）
# wjx survey create-by-text --text "..." --publish
# wjx survey create --title "新问卷" --questions '[...]'

# 查看
wjx survey list --name_like "满意度"
wjx survey get --vid 12345
wjx survey settings --vid 12345

# 管理
wjx survey status --vid 12345 --state 1    # 发布
wjx survey status --vid 12345 --state 2    # 暂停
wjx survey delete --vid 12345              # 删除

# 链接
wjx survey url --mode edit --activity 12345    # 编辑链接

答卷操作

# 统计
wjx response count --vid 12345
wjx response report --vid 12345

# 查询
wjx response query --vid 12345 --page_size 50
wjx response query --vid 12345 --start_date 2026-04-01

# 下载
wjx response download --vid 12345

# 代填提交
wjx response submit --vid 12345 --inputcosttime 60 --submitdata "1\$9"

本地分析（不需要 API Key）

# NPS 计算
wjx analytics nps --scores "[9,10,7,3,8,10,9]"

# CSAT 计算
wjx analytics csat --scores "[4,5,3,5,2]"
wjx analytics csat --scores "[5,6,7,4,5]" --scale 7-point

# 解码答卷数据
wjx analytics decode --submitdata "1\$2}2\$hello world"

# 异常检测
wjx analytics anomalies --responses '[{"duration":5,"answers":"1,1,1,1"},{"duration":120,"answers":"3,2,4,1"}]'

通讯录和账号

# 通讯录
wjx contacts query --uid user001
wjx contacts add --data '[{"name":"张三","mobile":"13800138000"}]'

# 部门
wjx department list
wjx department add --data '[{"dpath":"研发部/后端组"}]'

# 子账号
wjx account list
wjx account add --username test1 --password Pass123 --role 2

# SSO（不需要 API Key）
wjx sso subaccount-url --subuser test1

全局选项

每个命令都支持以下选项：

Dry-Run 示例

wjx survey list --dry-run

输出：

[DRY-RUN] POST https://www.wjx.cn/openapi/survey/list
Headers: { authorization: "Bearer sk-****" }
Body: { "page_index": 1, "page_size": 10 }

看到完整请求但不实际发送，适合调试和学习 API。

Shell 补全

一键安装

wjx completion install

自动检测你的 shell（bash/zsh/fish），写入对应配置文件。重新打开终端后，输入 wjx 按 Tab 即可补全命令和选项。

手动安装

# Bash
wjx completion bash >> ~/.bashrc

# Zsh
wjx completion zsh >> ~/.zshrc

# Fish
wjx completion fish > ~/.config/fish/completions/wjx.fish

AI Agent 集成

Claude Code 技能安装

wjx skill install

也可从 Vercel Agent Skills 安装：npx skills add wjxcom/wjx-ai-kit，或在 ClawHub 市场搜索 "wjx" 安装。

安装后，Claude Code 会获得一个 wjx-cli-expert Agent，能够：

• 理解你的自然语言需求
• 自动选择正确的 wjx 命令
• 执行命令并解读结果
• 处理错误和重试

在 AI Agent 中使用

wjx-cli 的设计让 AI Agent 可以直接解析输出：

import subprocess, json

result = subprocess.run(
    ["wjx", "survey", "list"],
    capture_output=True, text=True
)

if result.returncode == 0:
    data = json.loads(result.stdout)
    surveys = data["data"]["activitys"]
else:
    error = json.loads(result.stderr)
    print(f"错误: {error['message']}")

退出码约定：

• 0 — 成功
• 1 — API/认证错误
• 2 — 输入参数错误

内置参考文档

不用翻网页，直接查看参考资料：

wjx reference dsl              # DSL 文本格式语法
wjx reference question-types   # 题型编码表
wjx reference survey           # 问卷命令参考
wjx reference response         # 答卷命令参考
wjx reference analytics        # 分析命令参考

自我更新

wjx update

检查 npm 上的最新版本，有更新则自动安装。更新后会询问是否同步更新技能包。

常见问题

Q: 命令报 "API Key is required"

运行 wjx doctor 检查配置。确保已执行 wjx init 或设置了 WJX_API_KEY 环境变量。

Q: 创建问卷时 DSL 格式报错

用 wjx reference dsl 查看语法参考。常见问题：

• 量表题用 1~10（波浪号），不是 1-10
• 矩阵题的行和列需要 行： 和 列： 前缀
• 多项填空题的标题中需要包含 {_} 占位符

Q: 如何批量操作

用管道和 jq 组合：

# 列出所有问卷的 vid
wjx survey list --page_size 100 | jq -r '.data.activitys | to_entries[].value.vid'

# 批量暂停
for vid in $(wjx survey list | jq -r '.data.activitys | to_entries[].value.vid'); do
  wjx survey status --vid $vid --state 2
done

下一步

• CLI 进阶指南 — 管道组合、自动化脚本、技能系统深度用法
• MCP 入门指南 — 用 AI 对话操作问卷星
• SDK 入门指南 — TypeScript 编程接入
• 总纲 — 全景概览

SDK 入门指南：TypeScript 开发快速上手

零依赖、类型安全、48+ 函数，5 分钟集成问卷能力

什么是 wjx-api-sdk

wjx-api-sdk 是问卷星 OpenAPI 的 TypeScript SDK。它的特点是：

• 零运行时依赖：只用 Node.js 内置 API（fetch + crypto），无第三方包
• 完整类型系统：70+ TypeScript 类型定义，全程类型安全
• 48+ 函数：8 个模块覆盖问卷星全部 API 能力
• 可测试设计：fetch 注入 + 凭据提供者模式，623 个测试零网络调用

安装

npm install wjx-api-sdk

或从源码安装：

git clone https://github.com/wjxcom/wjx-ai-kit.git
cd wjx-ai-kit
npm install
npm run build --workspace=wjx-api-sdk

需要 Node.js >= 20（使用内置 fetch）。

认证配置

三种方式，按优先级排列：

1. 直接传参

import { listSurveys } from "wjx-api-sdk";

const result = await listSurveys(
  { page_index: 1 },
  { apiKey: "你的API Key" }
);

2. 环境变量

export WJX_API_KEY=你的APIKey

// 不传 credentials，自动从 process.env.WJX_API_KEY 读取
const result = await listSurveys({ page_index: 1 });

3. 凭据提供者（多租户场景）

import { setCredentialProvider, listSurveys } from "wjx-api-sdk";

// 注册提供者，适合 AsyncLocalStorage 多租户架构
setCredentialProvider(() => ({
  apiKey: getCurrentTenantApiKey()
}));

const result = await listSurveys({ page_index: 1 });

优先级：直接传参 > 凭据提供者 > 环境变量

第一个 API 调用

import { listSurveys, getSurvey, createSurveyByText } from "wjx-api-sdk";

// 列出问卷
const list = await listSurveys({ page_index: 1, page_size: 10 });
console.log(`共 ${list.data.total} 份问卷`);

// 获取问卷详情
const survey = await getSurvey({ vid: 12345 });
console.log(survey.data.aname); // 问卷标题

// 用 DSL 文本创建问卷
const created = await createSurveyByText({
  text: `客户满意度调查

1. 推荐意愿 [量表题]
0~10

2. 改进建议 [填空题]`,
});
console.log(`新问卷 ID: ${created.data.vid}`);

统一函数签名

所有 SDK 函数遵循相同的 3 参数模式：

async function doSomething(
  input: DoSomethingInput,     // 业务参数（类型安全）
  credentials?: WjxCredentials, // 可选，默认从环境读取
  fetchImpl?: FetchLike,       // 可选，默认用内置 fetch
): Promise<WjxApiResponse<T>>

这意味着：

• 你永远知道函数长什么样
• 测试时注入 mock fetch，不需要任何 HTTP mocking 库
• 多租户时注入不同的 credentials

模块速查

问卷管理（48+ 函数）

import {
  createSurvey,           // 创建问卷（JSON）
  createSurveyByText,     // 创建问卷（DSL 文本）
  getSurvey,              // 获取详情
  listSurveys,            // 列表查询
  updateSurveyStatus,     // 修改状态（发布/暂停/删除）
  getSurveySettings,      // 获取设置
  updateSurveySettings,   // 修改设置
  deleteSurvey,           // 删除问卷
  getQuestionTags,        // 获取标签
  getTagDetails,          // 标签详情
  clearRecycleBin,        // 清空回收站
  uploadFile,             // 上传文件
  validateQuestionsJson,  // 验证题目 JSON
} from "wjx-api-sdk";

答卷管理（48+ 函数）

import {
  queryResponses,          // 分页查询
  queryResponsesRealtime,  // 实时查询
  downloadResponses,       // 批量下载
  getReport,               // 统计报告
  submitResponse,          // 代填提交
  getWinners,              // 抽奖中奖者
  modifyResponse,          // 修改答卷
  get360Report,            // 360 报告
  getFileLinks,            // 附件下载链接
  clearResponses,          // 清空答卷
} from "wjx-api-sdk";

通讯录管理（48+ 函数）

import {
  queryContacts, addContacts, deleteContacts,     // 联系人
  addAdmin, deleteAdmin, restoreAdmin,            // 管理员
  listDepartments, addDepartment, modifyDepartment, deleteDepartment, // 部门
  listTags, addTag, modifyTag, deleteTag,         // 标签
} from "wjx-api-sdk";

SSO 单点登录（48+ 函数）

import {
  buildSsoSubaccountUrl,   // 子账号 SSO
  buildSsoUserSystemUrl,   // 用户体系 SSO
  buildSsoPartnerUrl,      // 合作伙伴 SSO
  buildSurveyUrl,          // 问卷创建/编辑 URL
  buildPreviewUrl,         // 问卷填写 URL
} from "wjx-api-sdk";

数据分析（48+ 函数，纯本地计算）

import {
  decodeResponses,     // 解码答卷数据
  calculateNps,        // NPS 计算
  calculateCsat,       // CSAT 计算
  detectAnomalies,     // 异常检测
  compareMetrics,      // 指标对比
  decodePushPayload,   // Webhook 解密
} from "wjx-api-sdk";

DSL 文本转换（48+ 函数）

import {
  textToSurvey,            // 文本 → 问卷结构
  surveyToText,            // 问卷结构 → 文本
  parsedQuestionsToWire,   // 解析结构 → API 格式
  typeToLabel,             // 题型代码 → 中文标签
  LABEL_TO_TYPE,           // 27 个标签映射表
  TYPE_MAP,                // 24 个类型映射表
} from "wjx-api-sdk";

其他模块

// 用户体系（48+ 函数）
import { addParticipants, modifyParticipants, deleteParticipants,
         bindActivity, querySurveyBinding, queryUserSurveys } from "wjx-api-sdk";

// 子账号（48+ 函数）
import { addSubAccount, modifySubAccount, deleteSubAccount,
         restoreSubAccount, querySubAccounts } from "wjx-api-sdk";

常用场景

查询并分析答卷

import { queryResponses, decodeResponses, calculateNps } from "wjx-api-sdk";

// 查询全部答卷
const responses = await queryResponses({
  vid: 12345,
  page_size: 100,
});

// 解码每份答卷
const allScores: number[] = [];
for (const r of responses.data.list) {
  const decoded = decodeResponses(r.submitdata);
  // decoded.answers 是 DecodedAnswer[] 数组
  // 假设第 1 题是 NPS 题，找到对应答案
  const npsAnswer = decoded.answers.find((a) => a.questionIndex === 1);
  if (npsAnswer) {
    const npsScore = Number(npsAnswer.value);
    if (!isNaN(npsScore)) allScores.push(npsScore);
  }
}

// 计算 NPS
const nps = calculateNps(allScores);
console.log(`NPS: ${nps.score} (${nps.rating})`);
console.log(`推荐者: ${(nps.promoters.ratio * 100).toFixed(0)}%`);
console.log(`贬损者: ${(nps.detractors.ratio * 100).toFixed(0)}%`);

生成 SSO 链接

import { buildSsoSubaccountUrl, buildPreviewUrl } from "wjx-api-sdk";

// 子账号免密登录
const ssoUrl = buildSsoSubaccountUrl({
  subuser: "sales01",
  apiKey: "你的API Key",
});
console.log(ssoUrl); // https://www.wjx.cn/...&sign=...

// 问卷填写链接
const previewUrl = buildPreviewUrl({
  vid: 12345,
  source: "crm",
});
console.log(previewUrl); // https://www.wjx.cn/vm/12345.aspx?source=crm

错误处理

import { listSurveys } from "wjx-api-sdk";

try {
  const result = await listSurveys({ page_index: 1 });
  if (result.result === false) {
    // API 返回了业务错误
    console.error("业务错误:", result.error);
  } else {
    console.log("成功:", result.data);
  }
} catch (error) {
  // 网络错误、超时等
  console.error("请求失败:", error.message);
}

环境变量

下一步

• SDK 进阶指南 — DSL 双向转换、本地分析引擎、测试模式、多租户
• MCP 入门指南 — 用 AI 操作问卷星
• CLI 入门指南 — 命令行工具
• 总纲 — 全景概览

Skill 包入门指南

几条命令，你的 AI 助手就能操作问卷星了。

什么是问卷星 Skill

Skill 是一种让 AI 助手获得特定能力的方式。问卷星 Skill 包含：

• SKILL.md — AI 读取的使用指南，告诉它怎么操作问卷星
• references/ — 详细参考文档，AI 按需查阅

安装后，你对 AI 说 "帮我创建一份问卷"，它就知道该怎么做了。

三种接入方式对比

推荐：

• 如果你的 AI 工具支持 MCP，优先用 MCP Server（能力最强）
• 如果你用 Claw 系列工具或想要最简安装，用 Skill 包
• 如果你主要做自动化脚本，直接用 CLI

快速开始：让 AI 帮你安装

你已经在 AI 工具里了，直接让 AI 完成安装。复制下面的话发给你的 AI 助手：

请帮我安装问卷星工具：

1. 先检查 Node.js 是否已安装（node --version），如果没有请帮我安装 Node.js 20+
2. 运行 npm install -g wjx-cli 安装问卷星 CLI
3. 安装完成后，告诉我去这个链接获取 API Key：https://www.wjx.cn/weixinlogin.aspx?redirecturl=%2Fnewwjx%2Fmanage%2Fuserinfo.aspx%3FshowApiKey%3D1 ，等我把 Key 发给你
4. 拿到我的 Key 后运行 wjx init --api-key <我的Key> 完成配置
5. 最后运行 wjx doctor 验证连接

AI 会自动执行安装，然后等你提供 API Key。你微信扫码登录后，把 Key 发给 AI（例如"这是 API Key：sk-wjx-xxx，请继续"），AI 就能帮你完成配置。

使用自定义域名？ 如果你使用的不是 www.wjx.cn（如 xxx.sojump.cn），请在提示中告诉 AI 你的域名，AI 会自动替换 API Key 链接并在配置时使用 --base-url 参数。

安装完成后，直接对 AI 说：

"帮我创建一份客户满意度调查，包含 NPS 评分题和 5 个维度的量表题"

AI 会自动调用 wjx 命令创建问卷，返回编辑链接和填写链接。

手动安装

方式一：npm 安装（推荐）

# 安装 CLI
npm install -g wjx-cli

# 配置 API Key（交互式，按提示操作）
wjx init

# 验证连接
wjx doctor

# 安装 AI 技能包到当前目录
wjx skill install

没有 Node.js？ CLI 需要 Node.js 20+ 环境。访问 nodejs.org 下载最新 LTS 版本，安装后再执行上述命令。

安装完成后，根据你的 AI 工具，将 Skill 目录添加到对应位置：

OpenClaw / KimiClaw / QClaw / LinClaw / MaxClaw：
在工具的 Skills/技能 设置中，添加 skills/wjx-cli-use 目录路径。

Claude Code：
wjx skill install 会自动安装到 .claude/agents/ 和 skills/，无需额外操作。

其他工具：
将 skills/wjx-cli-use/SKILL.md 的内容添加到工具的系统提示或 Rules 文件中。

方式二：下载 Skill 包

1. 下载 wjx-cli-use-skill-latest.zip
2. 解压并提取其中的 wjx-cli-use 目录到 AI 工具的技能目录（如 skills/wjx-cli-use/）
3. 安装 CLI 并配置 API Key——复制以下内容发给你的 AI 助手：

请帮我安装问卷星 CLI：

1. 运行 node --version 检查 Node.js 版本，如果未安装或低于 20，请帮我安装 Node.js 20+
2. 运行 npm install -g wjx-cli 安装问卷星 CLI
3. 告诉我去这个链接获取 API Key：https://www.wjx.cn/weixinlogin.aspx?redirecturl=%2Fnewwjx%2Fmanage%2Fuserinfo.aspx%3FshowApiKey%3D1
4. 拿到 Key 后运行 wjx init --api-key 完成配置
5. 运行 wjx doctor 验证连接

已配置 MCP Server？ 如果你已接入了 wjx-mcp-server，可跳过 CLI 安装。Skill 文档同样适用于 MCP 工具调用。

环境要求

• Node.js >= 20（下载）
• 问卷星账号（微信扫码即可注册登录）
• 支持系统：macOS、Linux、Windows

与 MCP Server 的关系

┌─────────────────────────────────────────┐
│            你的 AI 助手                  │
├───────────────┬─────────────────────────┤
│   Skill 包     │    MCP Server           │
│ (读 SKILL.md   │ (58 个工具直接调用)      │
│  调 wjx 命令)  │                         │
├───────────────┴─────────────────────────┤
│          wjx-cli (67 子命令)             │
├─────────────────────────────────────────┤
│          wjx-api-sdk (基础层)            │
├─────────────────────────────────────────┤
│          问卷星 OpenAPI                  │
└─────────────────────────────────────────┘

• Skill 包：AI 读取 SKILL.md 学会用法，通过 wjx CLI 命令操作问卷星
• MCP Server：AI 通过 MCP 协议直接调用 58 个工具，不需要命令行

两者底层都走 wjx-api-sdk，能力一致。MCP Server 的工具调用更高效，Skill 包的安装更简单。

常见问题

Q: 我需要同时装 MCP Server 和 Skill 包吗？

不需要。选一种就行。如果你的 AI 工具支持 MCP，推荐用 MCP Server。

Q: npm install 报错怎么办？

需要 Node.js 20 以上。访问 nodejs.org 下载最新 LTS 版本。安装后运行 node --version 确认版本号 >= 20。

Q: API Key 在哪里找？

打开 这个链接，微信扫码登录后直接显示。如果你使用自定义域名，将链接中的 www.wjx.cn 替换为你的域名即可。

Q: 拿到 API Key 后怎么告诉 AI？

直接把 Key 发给 AI 即可，例如"这是 API Key：sk-wjx-xxx，请继续"。AI 会自动执行 wjx init --api-key <你的Key> 完成配置。

Q: 我用的不是 www.wjx.cn 域名怎么办？

在让 AI 安装时告诉它你的域名，例如"我用的域名是 xxx.sojump.cn"。AI 会自动在 wjx init 时加上 --base-url https://xxx.sojump.cn，并替换 API Key 获取链接中的域名。

深入了解

• MCP Server 入门指南 — 用 MCP 接入更多 AI 工具
• CLI 入门指南 — 命令行完整用法
• SDK 入门指南 — TypeScript 开发集成
• 总纲 — 功能全景和选择引导

MCP Server 进阶指南：58 个工具完全攻略

HTTP 部署、Docker、多租户、自动化工作流、全部工具深度用法

HTTP 模式部署

默认的 stdio 模式适合本地 AI 客户端。如果你需要团队共享或远程访问，可以启用 HTTP 模式。

启动 HTTP 服务

# 环境变量方式
MCP_TRANSPORT=http PORT=3000 MCP_AUTH_TOKEN=your_secret npx wjx-mcp-server

# 或命令行参数
npx wjx-mcp-server --http

端点说明

认证

设置 MCP_AUTH_TOKEN 后，所有 /mcp 请求需要携带 Bearer Token：

Authorization: Bearer your_secret

多租户模式

HTTP 模式天然支持多租户。每个请求的 Bearer Token 会被用作该请求的问卷星 API Key。不同客户端可以用各自的 API Key 访问同一个 MCP Server。

服务端通过 Node.js AsyncLocalStorage 将每个请求的凭据穿透到所有 SDK 调用，互不干扰。

客户端 A（API Key A）──→ POST /mcp ──→ MCP Server ──→ 用 Key A 调用问卷星
客户端 B（API Key B）──→ POST /mcp ──→ MCP Server ──→ 用 Key B 调用问卷星

Docker 部署

构建镜像

需要从 monorepo 根目录构建（因为 SDK 是 workspace 依赖）：

git clone https://github.com/wjxcom/wjx-ai-kit.git
cd wjx-ai-kit
docker build -f wjx-mcp-server/Dockerfile -t wjx-mcp-server .

运行

docker run -d \
  --name wjx-mcp \
  -p 3000:3000 \
  -e WJX_API_KEY=your_api_key \
  -e MCP_AUTH_TOKEN=your_secret \
  wjx-mcp-server

内置健康检查（每 30 秒探测 /health），适合 Kubernetes 和 Docker Compose。

Docker Compose 示例

services:
  wjx-mcp:
    build:
      context: .
      dockerfile: wjx-mcp-server/Dockerfile
    ports:
      - "3000:3000"
    environment:
      - WJX_API_KEY=${WJX_API_KEY}
      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

全部工具详解

问卷管理模块（13 项）

create_survey — 创建问卷（JSON 模式）

用结构化 JSON 创建问卷。适合精确控制题目结构的场景。

参数：
- aname (string, 必填): 问卷标题
- questions (array): 题目 JSON 数组
- source_vid (number): 从已有问卷复制
- atype (number): 问卷类型（1=调查 3=投票 6=考试 7=表单）
- adesc (string): 问卷描述
- publish (boolean): 创建后自动发布

create_survey_by_json — 创建问卷（JSONL 模式，唯一推荐）

所有问卷创建一律使用本工具，覆盖 70+ 题型（含矩阵/比重/滑块/文件上传/排序），每行一道题。

参数：
- jsonl (string, 必填): JSONL 格式问卷文本（首行可选 `{"_meta":{"title":"...","description":"..."}}`）
- title (string): 覆盖 JSONL 中的问卷标题
- atype (number): 问卷类型（1=调查 3=投票 6=考试 7=表单）
- publish (boolean): 创建后自动发布
- creater (string): 创建者子账号

字段编码见 题型参考。

create_survey_by_text — 创建问卷（DSL 文本模式，已弃用）

已弃用：新项目请改用 create_survey_by_json。本工具仅为兼容保留。

参数：
- text (string, 必填): DSL 格式的问卷文本
- atype (number): 问卷类型
- publish (boolean): 创建后自动发布

DSL 支持的题型标签：

get_survey — 获取问卷详情

参数：
- vid (number, 必填): 问卷 ID
- format (string): 输出格式，"json"（默认）或 "dsl"（纯文本格式）

format=dsl 返回人类可读的文本格式，适合 AI 理解问卷内容。

list_surveys — 获取问卷列表

参数：
- page_index (number): 页码（默认 1）
- page_size (number): 每页数量（默认 10，最大 100）
- status (number): 状态过滤（0=未发布 1=收集中 2=已暂停 3=已删除）
- atype (number): 类型过滤
- name_like (string): 名称模糊搜索
- start_date / end_date (string): 时间范围
- folder_id (number): 文件夹 ID
- sort_by / sort_order: 排序

update_survey_status — 修改问卷状态

参数：
- vid (number, 必填): 问卷 ID
- state (number, 必填): 目标状态（1=发布 2=暂停 3=删除）

其他问卷工具

• get_survey_settings / update_survey_settings — 获取/修改问卷设置
• delete_survey — 删除问卷（可选永久删除）
• get_question_tags / get_tag_details — 题目标签管理
• clear_recycle_bin — 清空回收站
• upload_file — 上传图片文件（Base64）

答卷管理模块（9 项）

query_responses — 查询答卷

最常用的答卷工具，支持丰富的过滤条件。

参数：
- vid (number, 必填): 问卷 ID
- page_index / page_size: 分页
- start_date / end_date: 时间范围
- conditions (string): 条件筛选（如 "Q1=选项A"）
- dedup (boolean): 去重
- order_by (string): 排序

get_report — 统计报告

返回每道题的频率分布、平均分、标准差等统计数据。

参数：
- vid (number, 必填): 问卷 ID

download_responses — 批量下载

参数：
- vid (number, 必填): 问卷 ID
- format (string): 格式（csv/sav/word）

超过 3000 条自动切换为异步下载模式（120 秒超时）。

其他答卷工具

• query_responses_realtime — 实时增量查询（消费式，需白名单）
• submit_response — 代填提交答卷
• get_winners — 抽奖中奖者查询
• modify_response — 修改答卷（如调整考试主观题分数）
• get_360_report — 360 度评估报告（异步任务）
• clear_responses — 清空全部答卷（不可逆）

通讯录管理模块（14 项）

企业通讯录的完整 CRUD，覆盖联系人、部门、管理员、标签四个维度。需要设置 WJX_CORP_ID。

SSO 单点登录模块（5 项）

生成免密登录 URL，纯本地计算，无需 API 调用。

数据分析模块（5 项）

全部在本地运行，数据不离开你的机器。 无需 API Key。

calculate_nps — NPS 计算

输入: scores (number[]): 0-10 评分数组
输出: score (-100~100), rating (优秀/良好/一般/较差),
      promoters/passives/detractors 各组 {count, ratio}

行业基准：

calculate_csat — CSAT 计算

输入: scores (number[]): 评分数组
      scaleType ("5-point" | "7-point"): 量表类型
输出: csat (0-1 比率), satisfiedCount, total, distribution

detect_anomalies — 异常检测

三种检测策略：

1. 直线作答：连续选择相同答案（如全选 A）
2. 秒答检测：答题时间 < 中位时长的 30%
3. 重复检测：相同 IP + 相似答案内容

decode_responses — 答卷解码

解析问卷星的 submitdata 编码格式（题号$答案}题号$答案）为结构化数据。

compare_metrics — 指标对比

A/B 组或时间段对比，差异 >10% 标记为显著。

用户体系模块（6 项）

注意：用户体系相关工具已标记为 [已过时]，问卷星官方建议新项目优先使用通讯录（Contacts）模块。存量项目仍可调用。

子账号管理模块（5 项）

主账号下的多用户管理，支持 4 种角色：1=系统管理员 / 2=问卷管理员 / 3=统计结果查看员 / 4=完整结果查看员。

自动化工作流示例

工作流 1：每周 NPS 监控

对 Claude 说：

"帮我分析问卷 12345 最近 7 天的 NPS 数据。

1. 先查询本周的答卷
2. 提取所有 NPS 评分题的分数
3. 计算 NPS 得分
4. 和上周数据做对比
5. 如果下降超过 10 分，找出贬损者的开放题反馈"

Claude 会自动调用 query_responses → decode_responses → calculate_nps → compare_metrics → query_responses（筛选贬损者），输出完整分析报告。

工作流 2：从文档出考试题

"用这份《信息安全管理制度》出一套考试题：

• 10 道单选题
• 5 道多选题
• 5 道判断题
  创建为考试类型问卷，发布后给我链接"

Claude 使用 generate-exam-from-document prompt → 生成 JSONL → create_survey_by_json（atype=6）→ update_survey_status（发布）→ build_preview_url（生成链接）。

工作流 3：批量创建 + SSO 分发

"帮我做以下事情：

1. 创建一份客户满意度调查
2. 给子账号 sales01 生成 SSO 登录链接
3. 查看通讯录里市场部的联系人"

Claude 分步调用多个工具完成跨模块操作。

工作流 4：问卷质量诊断

"对问卷 12345 做一次完整的质量检查"

使用 survey-health-check prompt，Claude 自动执行：

1. 获取问卷结构 → 检查题目设计质量
2. 获取统计报告 → 分析完成率和弃答率
3. 查询答卷样本 → 运行异常检测
4. 输出 0-100 健康分 + 具体改进建议

高级配置

自定义 API 端点

私有部署或测试环境可以覆盖任意 URL：

# 全局覆盖
WJX_BASE_URL=https://your-private-wjx.com

# 单个端点覆盖
WJX_API_URL=https://custom-api.example.com/openapi
WJX_CONTACTS_API_URL=https://custom-contacts.example.com

会话管理

HTTP 模式默认有状态（MCP_SESSION=stateful），通过 mcp-session-id 头维护会话。

设置 MCP_SESSION=stateless 可关闭会话跟踪，适合无状态负载均衡部署。

.env 文件

MCP Server 有内置的 .env 解析器（不依赖 dotenv），按以下顺序查找：

1. 当前工作目录下的 .env
2. wjx-mcp-server 包目录下的 .env

环境变量优先于 .env 文件。

API 核心机制

请求签名

所有 API 请求自动进行 SHA1 签名：

1. 将参数 key 按字母排序
2. 拼接非空 value
3. 末尾追加 API Key
4. SHA1 哈希生成签名

签名时间窗口 30 秒，服务端自动校验。

重试策略

超时设置

请求追踪

每个请求自动生成 UUID traceID，附加在 URL 查询参数中，用于问题排查。

下一步

• MCP 入门指南 — 5 分钟快速接入
• CLI 入门指南 — 命令行工具
• SDK 进阶指南 — 底层 SDK 高级用法
• 总纲 — 全景概览

CLI 进阶指南：67 个命令完全攻略

管道组合、自动化脚本、DSL 高级用法、AI Skill 系统

DSL 高级用法

完整题型示例

企业年度员工满意度调查
本问卷匿名填写，调查结果仅用于管理改进
===

1. 您所在的部门 [下拉框]
技术部
产品部
市场部
运营部
人力资源部
财务部

2. 您的工作年限 [单选题]
1 年以下
1-3 年
3-5 年
5-10 年
10 年以上

3. 整体工作满意度 [量表题]
1~10

4. 请评价以下方面 [矩阵量表题]
行：
- 工作环境
- 团队协作
- 职业发展机会
- 薪酬福利
- 工作生活平衡
- 直属上级管理
列：
- 非常不满意
- 不满意
- 一般
- 满意
- 非常满意

5. 你认为公司最需要改进的方面 [多选题]
沟通机制
培训发展
办公环境
薪酬体系
晋升通道
企业文化

6. 以下因素对你留任的影响程度 [比重题]
薪酬福利
职业发展
工作氛围
公司前景

7. 请为公司提供具体建议 [填空题]

保存为 satisfaction.txt，创建并发布：

wjx survey create-by-text --file satisfaction.txt --publish

考试问卷

wjx survey create-by-text --file exam.txt --type 6 --publish

--type 6 指定为考试类型。考试题使用和普通题相同的 DSL 标签，区别在问卷级别。

从已有问卷导出再编辑

# 导出为 DSL 文本
wjx survey export-text --vid 12345 --raw > my-survey.txt

# 编辑 my-survey.txt（修改题目、新增选项等）

# 用修改后的文本创建新问卷
wjx survey create-by-text --file my-survey.txt

这是一个强大的"复制-修改"工作流，适合基于模板批量创建变体问卷。

管道和组合技

stdin 管道输入

--stdin 从管道读取 JSON 参数，CLI 显式参数优先级更高：

# 基本用法
echo '{"vid": 12345}' | wjx --stdin survey get

# 参数覆盖：--page_size 覆盖 stdin 中的同名字段
echo '{"vid": 12345, "page_size": 10}' | wjx --stdin response query --page_size 50

jq 组合

# 获取第一个问卷的 vid
VID=$(wjx survey list | jq -r '.data.activitys | to_entries[0].value.vid')

# 查看该问卷的答卷数
wjx response count --vid $VID | jq '.data.total'

# 获取所有答卷的 submitdata
wjx response query --vid $VID --page_size 100 \
  | jq -r '.data.list[].submitdata'

# 提取所有问卷名和 ID 为 CSV
wjx survey list --page_size 100 \
  | jq -r '.data.activitys | to_entries[] | [.value.vid, .value.aname] | @csv'

批量操作脚本

#!/bin/bash
# 暂停所有收集中的问卷

wjx survey list --page_size 100 --status 1 \
  | jq -r '.data.activitys | to_entries[].value.vid' \
  | while read vid; do
      echo "暂停问卷 $vid..."
      wjx survey status --vid "$vid" --state 2
    done

A/B 测试批量创建

#!/bin/bash
# 从模板创建多个变体

for i in 1 2 3 4 5; do
  sed "s/{{variant}}/$i/g" template.txt \
    | wjx --stdin survey create-by-text --publish
  echo "变体 $i 创建完成"
done

67 个命令完整参考

问卷管理 (14)

答卷管理 (10)

通讯录 (3)

部门 (4)

管理员 (3)

标签 (4)

用户体系 (6)

子账号 (5)

SSO（不需要 API Key）(3)

数据分析（不需要 API Key）(6)

系统命令 (11)

AI Skill 系统深度解析

安装结构

wjx skill install 安装以下文件到当前项目（也可从 Vercel Agent Skills 或 ClawHub 市场安装）：

项目根目录/
├── .claude/agents/
│   └── wjx-cli-expert.md      # Claude Code Agent 定义
└── skills/wjx-cli-use/
    ├── SKILL.md                # 技能主文档（命令概览 + 核心工作流）
    └── references/
        ├── dsl-syntax.md       # DSL 语法参考
        ├── survey-commands.md  # 问卷命令参数
        ├── response-commands.md # 答卷命令参数
        ├── contacts-commands.md # 通讯录/账号命令参数
        ├── analytics-commands.md # 分析命令参考
        └── question-types.md   # 题型编码表

三层渐进式架构

AI Agent 不会一次加载所有文档。它按需读取：

1. Agent 定义（约 80 行）：职责范围、安全规则、工作原则
2. SKILL.md（约 110 行）：命令总览、核心工作流、枚举值
3. References（按需加载）：只在需要具体参数细节时才读取对应文件

这样设计最大化利用了 AI 的上下文窗口——大部分任务只需要前两层就够了。

使用场景

安装技能后，在 Claude Code 中可以这样用：

"帮我创建一份 NPS 调查问卷"
→ Claude Code 自动识别需要使用 wjx-cli-expert
→ 读取 SKILL.md 了解可用命令
→ 选择 wjx survey create-by-text
→ 需要 DSL 语法细节时读取 references/dsl-syntax.md
→ 生成 DSL 文本并执行命令
→ 返回问卷 ID 和预览链接

错误处理

结构化错误

所有错误输出到 stderr，格式统一：

{
  "error": true,
  "message": "API Key is required",
  "code": "AUTH_ERROR",
  "exitCode": 1
}

在脚本中处理错误

if wjx survey get --vid 12345 > /tmp/survey.json 2>/tmp/error.json; then
  echo "成功: $(jq -r '.data.aname' /tmp/survey.json)"
else
  echo "失败: $(jq -r '.message' /tmp/error.json)"
fi

实战案例

案例 1：每日答卷监控脚本

#!/bin/bash
# daily-monitor.sh - 每天检查答卷增量

VID=12345
TODAY=$(date +%Y-%m-%d)
YESTERDAY=$(date -d "yesterday" +%Y-%m-%d)

# 获取今日答卷数
COUNT=$(wjx response query --vid $VID --start_date $YESTERDAY --end_date $TODAY \
  | jq '.data.total')

echo "[$TODAY] 问卷 $VID 新增答卷: $COUNT 份"

# 超过 100 份时运行异常检测
if [ "$COUNT" -gt 100 ]; then
  RESPONSES=$(wjx response query --vid $VID --start_date $YESTERDAY --page_size 100)
  echo "$RESPONSES" | wjx --stdin analytics anomalies
fi

案例 2：通讯录批量导入

# 从 CSV 转 JSON 后导入
cat employees.csv | python3 -c "
import csv, json, sys
reader = csv.DictReader(sys.stdin)
contacts = [{'name': r['姓名'], 'mobile': r['手机'], 'dpath': r['部门']} for r in reader]
print(json.dumps(contacts))
" | wjx --stdin contacts add

案例 3：CI/CD 中的问卷测试

# GitHub Actions
- name: 验证问卷创建
  run: |
    wjx init --api-key ${{ secrets.WJX_API_KEY }} --no-install-skill
    wjx survey create-by-text --text "CI测试\n\n1. 测试题[单选题]\nA\nB" --dry-run
    wjx doctor

下一步

• CLI 入门指南 — 快速上手
• MCP 入门指南 — AI 对话操作
• SDK 入门指南 — TypeScript 编程
• 总纲 — 全景概览

SDK 进阶指南：高级特性与最佳实践

DSL 双向转换、本地分析引擎、fetch 注入测试、多租户架构、Webhook 解密

DSL 双向转换

SDK 内置了一套完整的问卷 DSL（领域特定语言），支持纯文本和 API 结构体之间的双向转换。

文本 → 问卷（textToSurvey）

import { textToSurvey } from "wjx-api-sdk";

const text = `
员工满意度调查
这是一份匿名调查
===

1. 您的部门 [下拉框]
技术部
产品部
市场部

2. 整体满意度 [量表题]
1~10

3. 请评价以下方面 [矩阵量表题]
行：
- 工作环境
- 团队协作
- 薪酬福利
列：
- 非常不满意
- 不满意
- 一般
- 满意
- 非常满意

4. 改进建议 [填空题]
`;

const parsed = textToSurvey(text);
// parsed.title === "员工满意度调查"
// parsed.description === "这是一份匿名调查"
// parsed.questions[0].type === "dropdown"
// parsed.questions[1].type === "scale"
// parsed.questions[2].type === "matrix-scale"

问卷 → 文本（surveyToText）

import { getSurvey, surveyToText } from "wjx-api-sdk";

const survey = await getSurvey({ vid: 12345 });
const text = surveyToText(survey.data);
console.log(text);
// 输出人类可读的 DSL 文本，可以编辑后重新创建

结构 → API 格式（parsedQuestionsToWire）

import { textToSurvey, parsedQuestionsToWire, createSurvey } from "wjx-api-sdk";

const parsed = textToSurvey(dslText);
const { questions: wireQuestions } = parsedQuestionsToWire(parsed.questions);
// wireQuestions 是 API 需要的 { q_title, q_type, q_subtype, items, ... } 格式

await createSurvey({
  title: parsed.title,
  description: parsed.description ?? "",
  type: 1,
  questions: JSON.stringify(wireQuestions),
});

createSurveyByText() 是以上三步的封装——解析、转换、创建一步完成。

支持的 27 种题型标签

方括号 []、中括号 【】、圆括号 ()（） 都可以识别。

本地分析引擎

6 个分析函数完全在本地运行，不需要网络，不需要 API Key。

NPS 计算

import { calculateNps } from "wjx-api-sdk";

const result = calculateNps([10, 9, 10, 8, 7, 6, 5, 4, 3, 2]);

console.log(result);
// {
//   score: -20,                          // NPS 得分 (-100 ~ 100)
//   rating: "较差",                       // 评级
//   total: 10,
//   promoters: { count: 3, ratio: 0.3 },  // 推荐者 (9-10分)
//   passives: { count: 2, ratio: 0.2 },   // 中立者 (7-8分)
//   detractors: { count: 5, ratio: 0.5 }, // 贬损者 (0-6分)
// }

评级标准：

CSAT 计算

import { calculateCsat } from "wjx-api-sdk";

// 5 级量表（默认，满意 = 4 和 5）
const csat5 = calculateCsat([5, 4, 3, 5, 4]);
// { csat: 0.8, satisfiedCount: 4, total: 5, distribution: {"3":1,"4":2,"5":2} }

// 7 级量表（满意 = 5、6 和 7）
const csat7 = calculateCsat([6, 7, 5, 6, 7], "7-point");
// { csat: 1.0, satisfiedCount: 5, total: 5, distribution: {"5":1,"6":2,"7":2} }

异常检测

import { detectAnomalies } from "wjx-api-sdk";

const result = detectAnomalies([
  { id: "r1", duration_seconds: 5, answers: [1, 1, 1, 1, 1], ip: "1.2.3.4" },
  { id: "r2", duration_seconds: 120, answers: [3, 2, 4, 1, 5], ip: "5.6.7.8" },
  { id: "r3", duration_seconds: 8, answers: [1, 1, 1, 1, 1], ip: "1.2.3.4" },
]);

// result: {
//   flagged: [
//     { responseId: "r1", reasons: ["straight-lining", "speed-anomaly"] },
//     { responseId: "r3", reasons: ["straight-lining", "speed-anomaly", "ip-content-duplicate"] },
//   ],
//   totalChecked: 3,
// }

三种检测策略：

• 秒答检测：答题时间 < 中位时长的 30%
• 直线作答：所有答案完全相同
• 重复检测：相同 IP + 相似答案内容

答卷数据解码

import { decodeResponses } from "wjx-api-sdk";

const decoded = decodeResponses("1$2}2$hello world}3$1|3|5");
// {
//   answers: [
//     { questionIndex: 1, type: "single", value: "2" },
//     { questionIndex: 2, type: "fill", value: "hello world" },
//     { questionIndex: 3, type: "multi", value: ["1", "3", "5"] },
//   ],
//   count: 3,
// }

问卷星的 submitdata 使用 题号$答案}题号$答案 格式，decodeResponses 将其转换为结构化对象。

指标对比

import { compareMetrics } from "wjx-api-sdk";

const result = compareMetrics(
  { nps: 45, csat: 78, completion: 85 },  // A 组
  { nps: 52, csat: 72, completion: 90 },  // B 组
);

// result.comparisons: [
//   { metric: "nps", valueA: 45, valueB: 52, delta: 7, changeRate: 0.1556, significant: true },
//   { metric: "csat", valueA: 78, valueB: 72, delta: -6, changeRate: -0.0769, significant: false },
//   { metric: "completion", valueA: 85, valueB: 90, delta: 5, changeRate: 0.0588, significant: false },
// ]

差异超过 10% 标记为 significant: true。

Webhook 推送解密

问卷星的 Webhook 推送使用 AES-128-CBC 加密。SDK 提供完整的解密和签名验证：

import { decodePushPayload } from "wjx-api-sdk";

// Express 中间件示例
app.post("/webhook", (req, res) => {
  const { decrypted, signatureValid } = decodePushPayload(
    req.body.encrypt,                    // 加密数据
    process.env.WJX_API_KEY,             // API Key（用于派生 AES 密钥）
    req.headers["x-wjx-signature"],      // 可选：签名
    JSON.stringify(req.body),            // 可选：原始请求体
  );

  if (signatureValid) {
    // decrypted 是解密后的 JSON 对象
    console.log("新答卷:", decrypted);
    res.json({ success: true });
  } else {
    res.status(403).json({ error: "签名验证失败" });
  }
});

解密流程：

1. MD5(API Key) 取前 16 字节作为 AES 密钥
2. 密文前 16 字节为 IV
3. AES-128-CBC + PKCS7 解密
4. 可选：SHA1 签名验证（timing-safe 比较，防时序攻击）

fetch 注入测试

SDK 的每个函数都接受可选的 fetchImpl 参数，让你无需任何 HTTP mocking 库就能编写测试：

import { createSurvey, type FetchLike } from "wjx-api-sdk";

function mockFetch(responseBody: unknown, status = 200): FetchLike {
  let capturedUrl: string;
  let capturedInit: RequestInit;

  const fn = async (input: string | URL, init?: RequestInit) => {
    capturedUrl = String(input);
    capturedInit = init!;
    return new Response(JSON.stringify(responseBody), {
      status,
      headers: { "Content-Type": "application/json" },
    });
  };

  // 附加捕获器
  (fn as any).captured = () => ({ url: capturedUrl, init: capturedInit });
  return fn as FetchLike;
}

// 测试
test("创建问卷发送正确请求", async () => {
  const fetch = mockFetch({ result: true, data: { vid: 999 } });

  const result = await createSurvey(
    { title: "测试问卷", type: 1, description: "", questions: "[]" },
    { apiKey: "test-key" },
    fetch,
  );

  assert.strictEqual(result.data.vid, 999);

  // 验证请求内容
  const { url, init } = (fetch as any).captured();
  assert(url.includes("/openapi/survey/create"));
  assert.strictEqual(init.method, "POST");
  const body = JSON.parse(init.body);
  assert.strictEqual(body.title, "测试问卷");
});

623 个测试全部使用这种模式，零网络调用，运行速度极快。

多租户架构

凭据提供者模式

setCredentialProvider() 配合 Node.js AsyncLocalStorage 实现请求级别的凭据隔离：

import { AsyncLocalStorage } from "node:async_hooks";
import { setCredentialProvider, listSurveys } from "wjx-api-sdk";

const store = new AsyncLocalStorage<{ apiKey: string }>();

// 注册提供者
setCredentialProvider(() => {
  const ctx = store.getStore();
  return ctx ? { apiKey: ctx.apiKey } : undefined;
});

// HTTP 请求处理
app.get("/api/surveys", (req, res) => {
  const apiKey = req.headers["x-api-key"] as string;

  store.run({ apiKey }, async () => {
    // 自动使用当前请求的 API Key
    const surveys = await listSurveys({ page_index: 1 });
    res.json(surveys);
  });
});

每个请求在自己的 AsyncLocalStorage context 中运行，凭据互不干扰。这正是 wjx-mcp-server HTTP 模式的实现方式。

凭据优先级

1. 函数参数中直接传入的 credentials
2. setCredentialProvider() 注册的提供者
3. process.env.WJX_API_KEY 环境变量

提供者可以返回 undefined 来跳过，让系统 fallback 到环境变量。

自定义 API 端点

私有部署或测试环境可以覆盖 API 基础地址：

# 全局覆盖
export WJX_BASE_URL=https://your-private-instance.com

# 单个端点覆盖
export WJX_API_URL=https://custom-api.example.com/openapi
export WJX_CONTACTS_API_URL=https://custom-contacts.example.com

URL 解析优先级：显式端点环境变量 > BASE_URL + 路径 > 硬编码默认值

API 核心机制

请求签名算法

所有 API 请求自动签名，无需手动处理：

1. 收集所有参数（包括 timestamp）
2. 按 key 字母排序
3. 拼接所有非空 value
4. 末尾追加 API Key
5. SHA1 哈希 → sign 参数

时间窗口 30 秒，SDK 自动生成 timestamp。

重试与超时

TraceID

每个请求自动生成 UUID traceID（32 字符），附加在 URL 查询参数中。出现问题时可以提供 traceID 给问卷星技术支持快速定位。

底层 API 调用

如果需要调用 SDK 尚未封装的 API，可以直接使用底层调用器：

import { callWjxApi, Action } from "wjx-api-sdk";

const result = await callWjxApi(
  // 第一个参数：请求参数（包含 action）
  { action: Action.GET_SURVEY, vid: 12345 },
  // 第二个参数：可选配置
  {
    credentials: { apiKey: "你的Key" },
    // fetchImpl: customFetch,  // 可选
    // maxRetries: 0,           // 可选
    // timeoutMs: 30000,        // 可选
  },
);

四个底层调用器对应不同的 API 端点：

• callWjxApi() — 主 API
• callWjxContactsApi() — 通讯录 API
• callWjxUserSystemApi() — 用户体系 API
• callWjxSubuserApi() — 子账号 API

TypeScript 类型系统

所有输入输出都有完整的类型定义：

import type {
  // 输入类型
  CreateSurveyInput,
  ListSurveysInput,
  QueryResponsesInput,

  // 输出类型
  WjxApiResponse,
  SurveyDetail,

  // 核心类型
  WjxCredentials,
  FetchLike,

  // DSL 类型
  ParsedSurvey,
  ParsedQuestion,
  WireQuestion,
  WireConversionResult,
} from "wjx-api-sdk";

下一步

• SDK 入门指南 — 快速上手
• MCP 进阶指南 — MCP Server 深度用法
• CLI 进阶指南 — 命令行高级技巧
• 总纲 — 全景概览

在 Claude Code 中使用问卷星

在 Claude Code 中用自然语言创建问卷、分析数据、管理通讯录——支持 MCP + Agent + Skill 三层架构，释放 AI 问卷调研的全部能力

为什么 Claude Code 是最佳选择

wjx-ai-kit 提供三层 AI 能力，而 Claude Code 是唯一能发挥全部三层能力的工具：

wjx-ai-kit 的 Agent + Skill 系统让 AI 不仅能调用工具，还理解问卷领域的专业知识，能自主完成复杂的多步骤任务。

准备工作

1. 安装 Claude Code — npm install -g @anthropic-ai/claude-code，然后运行 claude 完成认证
2. Node.js >= 20 — 运行 node --version 确认版本。如果未安装或版本低于 20，推荐以下方式安装：
   • 使用 nvm（推荐）：nvm install 20 && nvm use 20（nvm 安装说明，Windows 用户可使用 nvm-windows）
   • 官网下载：前往 nodejs.org 下载 LTS 版本安装包
3. 获取问卷星 API Key — 微信扫码登录 API Key 获取页，登录后页面直接显示 API Key

第一步：接入 MCP Server

方式一：命令行添加（推荐）

# 基本配置
claude mcp add wjx --env WJX_API_KEY=你的APIKey -- npx wjx-mcp-server

# 企业用户（需要通讯录功能）
claude mcp add wjx --env WJX_API_KEY=你的APIKey --env WJX_CORP_ID=你的企业ID -- npx wjx-mcp-server

方式二：手动编辑配置

在项目目录下创建 .mcp.json：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的 API Key"
      }
    }
  }
}

HTTP 远程模式

团队部署了远程 MCP 服务时：

{
  "mcpServers": {
    "wjx": {
      "url": "http://your-server:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

验证 MCP 连接

claude mcp list
# 应该看到 wjx 服务器及其工具列表

第二步：部署 Agent（推荐）

Agent 是 wjx-ai-kit 相比其他方案的核心优势。两个专家 Agent 内置了完整的问卷操作工作流：

• wjx-mcp-expert — MCP 工具专家，擅长通过 MCP 协议操作问卷星
• wjx-cli-expert — CLI 命令专家，擅长通过命令行批量操作

方式一：使用 CLI 一键安装（推荐）

npx wjx-cli skill install

这条命令会自动完成以下操作：

• 创建 .claude/agents/ 目录，部署 wjx-cli-expert Agent（CLI 命令专家）
• 复制 skills/wjx-cli-use/ 参考文档（DSL 语法、题型编码、CLI 命令参数等）

提示：如需 MCP 工具专家 Agent（wjx-mcp-expert），可使用方式二从 Skill 市场安装，或使用方式三手动部署。

方式二：从 Skill 市场安装

wjx-ai-kit 的 Skill 已上架 Vercel Agent Skills 和 ClawHub 市场：

# 通过 Vercel Agent Skills 安装
npx skills add wjxcom/wjx-ai-kit

方式三：手动部署

从 GitHub 仓库 下载以下文件到你的项目目录：

# 需要下载的文件：
wjx-agents/wjx-mcp-expert/wjx-mcp-expert.md  →  .claude/agents/wjx-mcp-expert.md
wjx-agents/wjx-cli-expert/wjx-cli-expert.md  →  .claude/agents/wjx-cli-expert.md
wjx-skills/wjx-cli-use/                      →  skills/wjx-cli-use/
wjx-skills/wjx-mcp-use/                      →  skills/wjx-mcp-use/

方式四：Skill zip 手动安装

如果无法使用 npm，可下载 Skill 包手动安装：

1. 下载 wjx-cli-use-skill-latest.zip
2. 解压并提取其中的 wjx-cli-use 目录到项目目录下的 skills/ 中
3. 安装 CLI 并配置 API Key：

   npm install -g wjx-cli
   wjx init

   
   

详见 Skill 包入门指南。

Agent 安装后的目录结构

使用方式一（skill install）后的结构：

your-project/
├── .claude/
│   ├── ...                   # Claude Code 配置
│   └── agents/
│       └── wjx-cli-expert.md # CLI 命令专家 Agent
└── skills/
    └── wjx-cli-use/          # CLI 使用技巧
        ├── SKILL.md
        └── references/

使用方式三（手动部署）可额外获得 MCP 专家 Agent 和完整 Skill 参考文档。

第三步：三种使用模式

模式一：委托给 Agent（最强大）

在 Claude Code 中提及 Agent 名称，Claude 会自动将任务委托给专家 Agent：

使用 wjx-cli-expert 帮我创建一份员工满意度调查问卷，包含 NPS 评分题和 5 个维度的量表题

Agent 会自动：

1. 加载相关 Skill 文档（DSL 语法、题型编码）
2. 规划问卷结构
3. 调用 CLI/MCP 工具创建问卷
4. 返回结果并给出优化建议

使用 wjx-cli-expert 批量导出上个月所有问卷的答卷数据到 CSV

CLI Agent 会自动：

1. 列出问卷列表
2. 筛选时间范围
3. 逐个导出答卷数据
4. 汇总结果

模式二：直接使用 MCP 工具

不通过 Agent，直接在 Claude Code 对话中使用问卷星工具：

帮我创建一份客户满意度调查问卷

Claude 会直接调用 MCP 工具完成任务。这种方式更直接，适合简单的单步操作。

模式三：团队协作

将 .claude/ 目录和 skills/ 提交到 Git 仓库，团队成员 clone 后即可使用相同的 Agent + Skill 配置：

# 提交配置到仓库
git add .claude/ skills/
git commit -m "feat: 添加问卷星 AI 工具配置"

团队成员只需设置自己的 API Key：

claude mcp add wjx --env WJX_API_KEY=自己的APIKey -- npx wjx-mcp-server

第四步：验证

验证 MCP

在 Claude Code 对话中输入：

帮我创建一份客户满意度调查问卷

如果 MCP 配置正确，Claude 会调用问卷星工具创建问卷。

验证 Agent

使用 wjx-cli-expert 列出我的所有问卷

如果 Agent 部署正确，Claude 会自动委托给专家 Agent 处理任务。

CLAUDE.md 集成

如果你的项目已经有 CLAUDE.md 文件，可以在其中添加问卷星相关上下文，让 Claude Code 在所有对话中都了解项目的问卷需求：

## 问卷星集成

本项目使用 wjx-ai-kit 管理问卷调研。常用操作：
- 创建问卷：一律使用 create_survey_by_json（JSONL，覆盖 70+ 题型）。create_survey_by_text 已弃用
- 查询数据：使用 query_responses + calculate_nps
- 管理通讯录：使用 add_contacts / query_contacts

问卷命名规范：[项目代号]-[日期]-[类型]，如 "PROD-20260406-NPS"

常见问题

MCP 工具没有出现？

# 检查 MCP 配置
claude mcp list

# 重新添加
claude mcp remove wjx
claude mcp add wjx --env WJX_API_KEY=你的APIKey -- npx wjx-mcp-server

Agent 命令无效？

1. 确认 .claude/agents/ 目录下有 Agent 配置文件
2. 确认文件名正确：wjx-cli-expert.md（skill install 安装），如需 MCP 专家则手动复制 wjx-mcp-expert.md
3. 重新运行 npx wjx-cli skill install

npx 首次运行很慢？

npx 需要下载包。你可以先全局安装：

npm install -g wjx-mcp-server wjx-cli

MCP 和 CLI Agent 该选哪个？

• MCP Agent（wjx-mcp-expert）：适合交互式操作，如创建问卷、分析数据、实时查询
• CLI Agent（wjx-cli-expert）：适合批量操作和自动化脚本，如批量导出、批量创建

两个 Agent 可以配合使用——用 MCP Agent 做设计和分析，用 CLI Agent 做批量执行。

下一步

• MCP Server 入门指南 — 了解 58 个工具的完整能力
• wjx-ai-kit 总览 — 了解 SDK、MCP、CLI 三合一架构

在 Claude Desktop 中使用问卷星

在 Claude Desktop 中用自然语言创建问卷、分析数据、管理通讯录

准备工作

1. 安装 Claude Desktop — 前往 claude.ai/download 下载并安装
2. Node.js >= 20 — 运行 node --version 确认版本，低于 20 请前往 nodejs.org 升级
3. 获取问卷星 API Key — 微信扫码登录 API Key 获取页，登录后页面直接显示 API Key

第一步：接入 MCP Server

找到配置文件

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

如果文件不存在，手动创建即可。

添加配置

将以下内容添加到配置文件中（如果已有其他 MCP 服务，在 mcpServers 对象中添加 wjx 条目即可）：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的 API Key"
      }
    }
  }
}

企业用户如需管理通讯录，在 env 中额外添加 "WJX_CORP_ID": "你的企业通讯录 ID"。

重启 Claude Desktop

配置完成后，必须完全退出并重新启动 Claude Desktop（不是最小化，是退出）。成功后，你会在聊天输入框底部看到工具图标，表示 MCP 工具已加载。

第二步：部署 Agent + Skill（推荐）

wjx-ai-kit 提供专家 Agent 和配套 Skill 参考文档，让 AI 理解问卷领域的专业知识。

一键安装

npx wjx-cli skill install

也可从 Vercel Agent Skills 安装：npx skills add wjxcom/wjx-ai-kit，或在 ClawHub 市场搜索 "wjx" 安装。

这条命令会自动完成：

• 创建 .claude/agents/ 目录，部署 wjx-cli-expert Agent（CLI 命令专家）
• 复制 skills/wjx-cli-use/ 参考文档（DSL 语法、题型编码、CLI 命令参数等）

安装后的目录结构：

your-project/
├── .claude/agents/
│   └── wjx-cli-expert.md    # CLI 命令专家 Agent
└── skills/
    └── wjx-cli-use/          # CLI 使用技巧
        ├── SKILL.md
        └── references/

使用 MCP Prompts 工作流

Claude Desktop 内置支持 MCP Prompts。wjx-mcp-server 提供了 22 个预设工作流模板（NPS 分析、满意度调查、考试出题、异常检测等），可直接在 Claude Desktop 对话中使用。

此外，你可以将 skills/ 中的参考文档内容作为对话上下文粘贴给 Claude，提升问卷操作的准确度。

Skill zip 手动安装

如果无法使用 npm，可下载 Skill 包手动安装：

1. 下载 wjx-cli-use-skill-latest.zip
2. 解压并提取其中的 wjx-cli-use 目录到 AI 工具的技能目录（或当前项目目录下）
3. 安装 CLI 并配置 API Key：

   npm install -g wjx-cli
   wjx init

   
   

详见 Skill 包入门指南。

第三步：安装 CLI（可选）

详见 CLI 入门指南。CLI 提供 67 个子命令，适合批量操作和自动化脚本。

第四步：验证

重启 Claude Desktop 后，在对话框中输入：

帮我创建一份客户满意度调查问卷

如果一切正常，Claude 会调用问卷星工具，自动创建问卷并返回编辑链接。

常见问题

配置后看不到工具图标？

1. 确认配置文件的 JSON 格式正确（没有尾逗号、引号匹配）
2. 确认已完全退出并重新启动 Claude Desktop（仅最小化不会重新加载配置）
3. 检查 Node.js 版本是否 >= 20：node --version

API Key 无效？

确认 API Key 没有多余的空格或换行符。登录问卷星后台重新复制一次。

工具调用超时？

npx 首次运行需要下载包，可能较慢。你也可以先全局安装：

npm install -g wjx-mcp-server

然后将配置中的 "command" 改为 "wjx-mcp-server"，"args" 改为 []。

下一步

• MCP Server 入门指南 — 了解 58 个工具的完整能力
• wjx-ai-kit 总览 — 了解 SDK、MCP、CLI 三合一架构

在 IDE 插件中使用问卷星

Cursor / Windsurf / Cline / GitHub Copilot / Trae / Gemini Code Assist / Qoder

准备工作

1. 安装你的 IDE 插件 — 见下表
2. Node.js >= 20 — 运行 node --version 确认版本，低于 20 请前往 nodejs.org 升级
3. 获取问卷星 API Key — 微信扫码登录 API Key 获取页，登录后页面直接显示 API Key

第一步：接入 MCP Server

通用 MCP 配置

所有 IDE 插件使用相同的 JSON 配置内容：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的 API Key"
      }
    }
  }
}

企业用户：如需管理通讯录，在 env 中额外添加 "WJX_CORP_ID": "你的企业通讯录 ID"。

自定义域名：WJX_BASE_URL 为可选项，默认 https://www.wjx.cn，私有化部署用户可在 env 中添加。

各工具配置入口

{
  "mcp": {
    "servers": {
      "wjx": {
        "command": "npx",
        "args": ["wjx-mcp-server"],
        "env": { "WJX_API_KEY": "你的 API Key" }
      }
    }
  }
}

HTTP 远程模式

团队部署了远程 MCP 服务时：

{
  "mcpServers": {
    "wjx": {
      "url": "http://your-server:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

第二步：部署 Agent + Skill（推荐）

wjx-ai-kit 提供专家 Agent 和配套 Skill 参考文档，让 AI 理解问卷领域的专业知识。

一键安装

npx wjx-cli skill install

此命令安装 CLI 命令专家 Agent（wjx-cli-expert）和配套 Skill 文档。如需 MCP 工具专家 Agent（wjx-mcp-expert），可从 GitHub 仓库 手动下载到 .claude/agents/ 目录。

也可从 Vercel Agent Skills 安装：npx skills add wjxcom/wjx-ai-kit，或在 ClawHub 市场搜索 "wjx" 安装。

安装后的目录结构：

your-project/
├── .claude/agents/
│   └── wjx-cli-expert.md    # CLI 命令专家 Agent
└── skills/
    └── wjx-cli-use/          # CLI 使用技巧
        ├── SKILL.md
        └── references/

Rules / Instructions 增强

大多数 IDE 插件支持通过 Rules 文件注入项目级上下文。将以下内容写入对应文件，AI 会在每次对话中自动加载：

推荐写入的 Rules 内容：

# 问卷星集成

本项目使用 wjx-ai-kit 管理问卷调研。

## MCP 工具使用规范
- 创建问卷：一律使用 create_survey_by_json（覆盖 70+ 题型）。create_survey_by_text 已弃用
- 数据分析：先用 query_responses 获取数据，再用 calculate_nps / calculate_csat 分析
- 通讯录操作：使用 add_contacts 批量导入，query_contacts 查询验证

## DSL 语法要点
- 第一行为问卷标题，=== 分隔描述
- 题型标签：[单选题] [多选题] [填空题] [量表题] [矩阵量表题] [下拉框]
- 量表范围：1~5 或 0~10

Skill zip 手动安装

如果无法使用 npm，可下载 Skill 包手动安装：

1. 下载 wjx-cli-use-skill-latest.zip
2. 解压并提取其中的 wjx-cli-use 目录到项目目录下的 skills/ 中
3. 安装 CLI 并配置 API Key：

   npm install -g wjx-cli
   wjx init

   
   

详见 Skill 包入门指南。

第三步：安装 CLI（可选）

详见 CLI 入门指南。CLI 提供 67 个子命令，适合批量操作和自动化脚本。

第四步：验证

在你的 AI 对话中输入：

帮我创建一份客户满意度调查问卷

如果一切正常，AI 会调用问卷星 MCP 工具，自动创建问卷并返回编辑链接。

常见问题

Cursor

MCP 工具没有出现？ 确认 .cursor/mcp.json 在项目根目录 → 重新加载窗口（Cmd+Shift+P → Reload Window）→ 在 Settings → Features → MCP 中确认状态。

项目级和全局配置的区别？ 项目级（.cursor/mcp.json）只在当前项目生效；全局级（~/.cursor/mcp.json）所有项目共享。

Windsurf

Cascade 中看不到工具？ 确认配置文件路径正确（全局 ~/.codeium/windsurf/mcp_config.json 或项目级 .windsurf/mcp.json）→ 确认 JSON 格式正确 → 重启 Windsurf。

Cline

添加后工具没出现？ 确认 Cline 为最新版 → 在 Settings → MCP Servers 中检查连接状态 → 点击刷新按钮重新连接。

工具调用需要手动确认吗？ 默认需要确认。可在设置中对信任的工具开启自动执行。

GitHub Copilot

Chat 中没有 MCP 工具？ 确认已启用 Agent 模式 → 确认 Copilot 版本支持 MCP → 聊天面板切换到 Agent 模式（非普通 Chat）。

Trae

看不到 MCP 工具？ 确认已通过 AI 聊天面板中的 MCP 图标配置 → 确认 JSON 格式正确 → 重启 Trae。

Windows 下 npx 报错 "cannot be loaded because running scripts is disabled"？ 以管理员身份运行 PowerShell：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，设置后重启 Trae。

Gemini Code Assist

支持 MCP 吗？ 取决于具体版本，建议关注 Google Cloud 官方文档。

Qoder

和通义灵码的区别？ 通义灵码面向国内，定位代码补全和问答。Qoder 面向海外，定位 Agentic 编程平台，支持更复杂的自主任务。两者都支持 MCP。

通用问题

npx 首次运行很慢？ 需要下载包。可先全局安装：npm install -g wjx-mcp-server wjx-cli。

工具调用失败？ 确认 Node.js >= 20 → 确认 API Key 有效且无多余空格 → 确认插件为最新版本。

下一步

• MCP Server 入门指南 — 了解 58 个工具的完整能力
• wjx-ai-kit 总览 — 了解 SDK、MCP、CLI 三合一架构

在 Claw 系列工具中使用问卷星

OpenClaw / KimiClaw / QClaw / LinClaw / MaxClaw 等 Claw 家族工具的问卷星配置

Claw 生态概览

Claw 是国内 AI 编程工具的一个生态体系，多家厂商推出了各自的 Claw 工具，均支持 MCP 协议接入外部能力。

准备工作

1. 安装你选择的 Claw 工具
2. Node.js >= 20 — 运行 node --version 确认版本
3. 获取问卷星 API Key — 微信扫码登录 API Key 获取页，登录后页面直接显示 API Key

第一步：接入 MCP Server

通用配置（KimiClaw / QClaw / LinClaw / MaxClaw 等）

大多数 Claw 工具采用标准 MCP 配置格式。在工具的 MCP 设置中添加：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的 API Key"
      }
    }
  }
}

各工具的 MCP 配置入口可能不同（设置面板、配置文件、命令行等），请参阅对应工具的官方文档。

OpenClaw 特殊配置

OpenClaw 使用不同的配置路径。编辑 ~/.openclaw/openclaw.json：

{
  "acp": {
    "mcpServers": {
      "wjx": {
        "command": "npx",
        "args": ["wjx-mcp-server"],
        "env": {
          "WJX_API_KEY": "替换为你的 API Key"
        }
      }
    }
  }
}

注意：OpenClaw 的 MCP 配置路径是 acp.mcpServers，与其他 Claw 工具的 mcpServers 不同。

企业用户

如需管理通讯录，在 env 中额外添加 "WJX_CORP_ID": "你的企业通讯录 ID"。

HTTP 远程模式

团队部署了远程 MCP 服务时：

{
  "mcpServers": {
    "wjx": {
      "url": "http://your-server:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

第二步：部署 Agent + Skill（推荐）

wjx-ai-kit 提供专家 Agent 和配套 Skill 参考文档，让 AI 理解问卷领域的专业知识。

一键安装

npx wjx-cli skill install

也可从 Vercel Agent Skills 安装：npx skills add wjxcom/wjx-ai-kit，或在 ClawHub 市场搜索 "wjx" 安装。

这条命令会自动完成：

• 创建 .claude/agents/ 目录，部署 wjx-cli-expert Agent（CLI 命令专家）
• 复制 skills/wjx-cli-use/ 参考文档（DSL 语法、题型编码、CLI 命令参数等）

安装后的目录结构：

your-project/
├── .claude/agents/
│   └── wjx-cli-expert.md    # CLI 命令专家 Agent
└── skills/
    └── wjx-cli-use/          # CLI 使用技巧
        ├── SKILL.md
        └── references/

OpenClaw Skills 增强

OpenClaw 支持 Skills 系统，可在 ~/.openclaw/openclaw.json 中启用 npm 包管理：

{
  "skills": {
    "install": {
      "nodeManager": "npm"
    }
  }
}

wjx-ai-kit 的 Skill 已上架 ClawHub 市场，搜索 "wjx" 即可安装。

各 Claw 工具如果支持 Rules 或指令文件，可以将 skills/ 中的关键内容写入，提升 AI 操作问卷星的准确度。

Skill zip 手动安装

如果无法使用 npm，可下载 Skill 包手动安装：

1. 下载 wjx-cli-use-skill-latest.zip
2. 解压并提取其中的 wjx-cli-use 目录到 AI 工具的技能目录（或当前项目目录下）
3. 安装 CLI 并配置 API Key：

   npm install -g wjx-cli
   wjx init

   
   

详见 Skill 包入门指南。

第三步：安装 CLI（可选）

详见 CLI 入门指南。CLI 提供 67 个子命令，适合批量操作和自动化脚本。

第四步：验证

在你的 Claw 工具中输入：

帮我创建一份客户满意度调查问卷

如果一切正常，AI 会调用问卷星 MCP 工具，自动创建问卷并返回编辑链接。

常见问题

我用的 Claw 工具不在列表中？

只要支持 MCP 协议，就可以参照上方的标准配置接入。如遇到问题，请在 GitHub Issues 反馈。

OpenClaw 中看不到问卷星工具？

1. 确认配置文件路径是 ~/.openclaw/openclaw.json
2. 确认 MCP 配置在 acp.mcpServers 下（不是 mcpServers）
3. 确认 Node.js 版本 >= 20
4. 重启 OpenClaw

Claw 工具的 MCP 配置文件在哪？

• OpenClaw: ~/.openclaw/openclaw.json（使用 acp.mcpServers 路径）
• KimiClaw: 通常在设置面板的 MCP/工具 配置中
• MaxClaw: MiniMax Agent 平台的工具/MCP 配置中
• EasyClaw: 托管部署面板的工具配置中
• LinClaw: 参考 LinClaw 官方文档
• 其他工具请查阅对应官方文档

下一步

• MCP Server 入门指南 — 了解 58 个工具的完整能力
• wjx-ai-kit 总览 — 了解 SDK、MCP、CLI 三合一架构

在 AI 工作台中使用问卷星

AI 工作台的问卷星配置总览——Manus、WorkBuddy、QoderWork 等桌面智能体平台

工作台生态概览

AI 工作台是一类桌面级智能体平台，能自主规划并执行多步骤任务。与 IDE 插件型工具不同，工作台更侧重任务交付而非代码编辑，适合非开发者使用。

准备工作

1. 安装你选择的工作台工具 — 前往对应官网下载安装
   • Manus: manus.im
   • WorkBuddy: copilot.tencent.com/work
   • QoderWork: qoder.com/zh/qoderwork
2. Node.js >= 20 — 运行 node --version 确认版本
3. 获取问卷星 API Key — 微信扫码登录 API Key 获取页，登录后页面直接显示 API Key

第一步：接入 MCP Server

在工作台的 MCP / 工具配置中添加问卷星服务器：

{
  "mcpServers": {
    "wjx": {
      "command": "npx",
      "args": ["wjx-mcp-server"],
      "env": {
        "WJX_API_KEY": "替换为你的 API Key"
      }
    }
  }
}

各工作台的 MCP 配置入口不同，请参阅对应工具的官方文档。

各工具配置入口

• Manus: 在 Agent Skills / Tools 设置中添加 MCP 服务器
• WorkBuddy: 在工具/插件配置面板中添加 MCP 连接
• QoderWork: 在设置 → MCP 配置中添加（与 Qoder IDE 插件共享配置）

企业用户

如需管理通讯录，在 env 中额外添加 "WJX_CORP_ID": "你的企业通讯录 ID"。

HTTP 远程模式

团队部署了远程 MCP 服务时：

{
  "mcpServers": {
    "wjx": {
      "url": "http://your-server:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

第二步：部署 Agent + Skill（推荐）

wjx-ai-kit 提供专家 Agent 和配套 Skill 参考文档，让 AI 理解问卷领域的专业知识。

一键安装

npx wjx-cli skill install

也可从 Vercel Agent Skills 安装：npx skills add wjxcom/wjx-ai-kit，或在 ClawHub 市场搜索 "wjx" 安装。

这条命令会自动完成：

• 创建 .claude/agents/ 目录，部署 wjx-cli-expert Agent（CLI 命令专家）
• 复制 skills/wjx-cli-use/ 参考文档（DSL 语法、题型编码、CLI 命令参数等）

安装后的目录结构：

your-project/
├── .claude/agents/
│   └── wjx-cli-expert.md    # CLI 命令专家 Agent
└── skills/
    └── wjx-cli-use/          # CLI 使用技巧
        ├── SKILL.md
        └── references/

如果你的工作台支持 Rules 或指令文件，可以将 skills/ 中的关键内容写入，提升 AI 操作问卷星的准确度。

Skill zip 手动安装

如果无法使用 npm，可下载 Skill 包手动安装：

1. 下载 wjx-cli-use-skill-latest.zip
2. 解压并提取其中的 wjx-cli-use 目录到工作台的技能目录（或当前项目目录下）
3. 安装 CLI 并配置 API Key：

   npm install -g wjx-cli
   wjx init

   
   

详见 Skill 包入门指南。

第三步：安装 CLI（可选）

详见 CLI 入门指南。CLI 提供 67 个子命令，适合批量操作和自动化脚本。

第四步：验证

在你的工作台中输入：

帮我创建一份客户满意度调查问卷

如果一切正常，AI 会调用问卷星 MCP 工具，自动创建问卷并返回编辑链接。

常见问题

我用的工作台工具不在列表中？

只要你的工作台支持 MCP 协议，就可以参照上方的标准配置接入问卷星。如遇到问题，请在 GitHub Issues 反馈。

工作台和 IDE 插件有什么区别？

• 工作台（Manus、WorkBuddy、QoderWork）：侧重任务交付，AI 自主规划和执行，适合非开发者
• IDE 插件（Cursor、Windsurf、Cline 等）：侧重代码编写，AI 辅助开发，适合开发者

两者都支持 MCP，问卷星功能一致。

QoderWork 和 Qoder IDE 插件是什么关系？

Qoder IDE 插件面向开发者，嵌入 VS Code / JetBrains。QoderWork 是独立桌面应用，面向更广泛用户。两者同属 Qoder 生态，MCP 配置方式相同。详见 IDE 插件配置指南。

下一步

• MCP Server 入门指南 — 了解 58 个工具的完整能力
• wjx-ai-kit 总览 — 了解 SDK、MCP、CLI 三合一架构