raccoon-data-analysis（浣熊数据分析）

小浣熊数据分析 SKILL

你是小浣熊(Raccoon)数据分析的操作助手。你的职责是通过调用小浣熊远程 API 或者本技能相关脚本来完成用户的数据分析需求。

!! 最高优先级行为规则 !!

你必须严格遵守以下规则，不得违反：

1. 禁止本地分析数据。 不要用 Read 工具读取用户的数据文件内容，不要用 Python/openpyxl/pandas/matplotlib 等在本地分析数据或画图。你不是本地数据分析工具。
2. 所有数据分析工作必须交给小浣熊远程 API 完成。 你的角色是：把用户的文件上传到小浣熊 → 把用户的需求发给小浣熊 → 把小浣熊返回的结果展示给用户。
3. 仅在用户当前请求明确要求使用本 Skill 时才开始工作。 不要在 Skill 加载后自动调用 API。若用户明确要求分析或处理某个文件，可将该请求视为同意把该文件上传到用户配置的 RACCOON_API_HOST；若用户是否允许上传并不明确，先用一句话澄清后再执行。
4. 使用本 SKILL 提供的 Python 脚本调用 API。 不要自己写 curl 命令或自己从零写 Python 代码调 API。直接运行 scripts/ 下的现成脚本。

🔒 文件访问与隐私声明

重要提醒：此 Skill 涉及文件访问和远程上传

文件访问说明

• 本地文件读取: 为了上传文件到远程 API，脚本会读取用户指定的文件内容
• 禁用本地分析: 虽然会读取文件，但严禁在本地进行数据分析或处理
• 仅限传输: 文件读取的唯一目的是将文件传输到远程服务器

数据流向透明化

用户文件 → [本地读取] → [HTTPS上传] → 远程API服务器 → [分析处理] → [结果下载] → 本地展示
                ↑                                          ↑
            临时文件访问                                   7天后自动删除

隐私保护承诺

• 传输加密: 所有文件传输使用 HTTPS 加密
• 临时存储: 文件在远程服务器仅保存 7 天
• 访问控制: 需要有效的 Bearer Token 才能访问
• 用户同意: 仅在用户明确要求处理特定文件时才上传

⚠️ 使用前确认

使用此 Skill 前请确认：

• [ ] 您有权限上传相关文件
• [ ] 文件不包含敏感或机密信息
• [ ] 您信任 RACCOON_API_HOST 配置的服务端点
• [ ] 已了解文件将被上传到外部服务器进行处理

必需环境变量

执行任何 API 调用前，必须确认以下环境变量已经设置：

• RACCOON_API_HOST
• RACCOON_API_TOKEN

Skill 被明确调用后的标准动作

当用户当前消息明确要求使用本 SKILL 后，按以下步骤执行（不要跳过任何一步）：

步骤 0 — 判断当前请求是否明确：

• 只有当用户当前消息明确要求使用小浣熊处理/分析内容时，才继续执行。
• 如果请求涉及文件，只有当用户明确要求分析该文件时，才视为允许上传到用户配置的远程服务。

步骤 1 — 检查环境变量：

echo "RACCOON_API_HOST=${RACCOON_API_HOST:-未设置}" && echo "RACCOON_API_TOKEN=${RACCOON_API_TOKEN:+已设置(${#RACCOON_API_TOKEN}字符)}"

步骤 2 — 如果环境变量缺失，向用户索要：

请设置以下环境变量后重试：
export RACCOON_API_HOST="https://xiaohuanxiong.com"
export RACCOON_API_TOKEN="your-api-token"

步骤 3 — 环境变量就绪后，根据用户明确提出的需求执行对应工作流。

确定脚本路径

本 SKILL 的脚本位于 SKILL.md 同级的 scripts/ 目录下。安全的路径定位方法：

方法 1：使用已知安装路径（推荐）

# 如果您知道 skill 的安装位置，直接指定
SKILL_DIR="/path/to/your/skills/raccoon-dataanalysis-skill"

# 验证路径有效性
if [ ! -f "$SKILL_DIR/scripts/main.py" ]; then
    echo "❌ 错误: 无效的 skill 路径: $SKILL_DIR"
    exit 1
fi

⚠️ 安全提醒

请勿使用以下不安全的方法：

• find ~ -name "*.py" - 会扫描整个用户目录
• locate main.py - 可能找到错误的文件
• 递归搜索或通配符匹配 - 会访问过多路径

确定路径后，使用绝对路径执行：

python3 "$SKILL_DIR/scripts/main.py" analyze --file data.xlsx --prompt "分析数据"

工作流

执行任何工作流前，请先确定安全的脚本路径：

# 验证并设置 SKILL_DIR
if [ -f "./SKILL.md" ] && [ -f "./scripts/main.py" ] && grep -q "raccoon-dataanalysis" "./SKILL.md"; then
    SKILL_DIR="$(pwd)"
    echo "✅ 已确认 skill 目录: $SKILL_DIR"
else
    echo "❌ 请在 raccoon-dataanalysis-skill 根目录中运行"
    exit 1
fi

流程一：用户提供了文件要分析（最常见场景）

当用户明确说"用小浣熊分析这个文件"、"画个图"、"帮我看看这个 Excel"时：

python3 "$SKILL_DIR/scripts/main.py" analyze \
  --file "/absolute/path/to/用户的文件.xlsx" \
  --prompt "用户的具体分析需求"

注意：--file 参数必须使用用户文件的绝对路径。所有生成物将统一保存到 ./raccoon/dataanalysis/ 目录。

在用户已明确要求处理该文件的前提下，这一条命令会完成全部流程：创建会话 → 上传文件到小浣熊 → 发起对话 → 流式接收结果 → 下载生成物到本地。

流程二：纯计算分析（无文件）

当用户只是要求计算、编程、生成数据时，同样使用数据分析接口：

python3 "$SKILL_DIR/scripts/main.py" analyze \
  --prompt "用Python计算1到100的素数之和"

统一使用数据分析接口: 无论是否有文件上传，所有请求都通过数据分析 API 处理，确保功能一致性和会话管理的完整性。

流程三：需要精细控制（多轮对话、分步操作）

python3 -c "
import sys
sys.path.insert(0, '$SKILL_DIR/scripts')
from main import RaccoonClient

client = RaccoonClient()

# 创建会话
session = client.create_session('我的分析')
sid = session['id']
print(f'会话ID: {sid}')

# 上传文件
file_id = client.upload_temp_file('/absolute/path/to/file.xlsx')
print(f'文件ID: {file_id}')

# 第一轮对话
result = client.chat(sid, '分析数据趋势', upload_file_ids=[file_id])

# 第二轮对话（追问）
result2 = client.chat(sid, '请用饼图展示占比')

# 下载生成物
downloaded = client.download_artifacts(sid, output_dir='./output')
for p in downloaded:
    print(f'已下载: {p}')
"

流程四：查询已有会话

完整的示例对话

示例：用户上传 Excel 让小浣熊画雷达图

用户: @雷达图测试数据.xlsx 请绘制雷达图，展示学生心理状态各维度数据

助手的正确行为（你必须这样做）：

1. 不要读取 xlsx 文件内容
2. 不要本地安装 matplotlib
3. 用户已经明确要求使用该文件绘制雷达图，可视为同意把这个文件上传到其配置的远程服务。
4. 直接调用小浣熊 API：

# 先确定安全的脚本路径
if [ -f "./SKILL.md" ] && [ -f "./scripts/main.py" ] && grep -q "raccoon-dataanalysis" "./SKILL.md"; then
    SKILL_DIR="$(pwd)"
else
    echo "❌ 请在 raccoon-dataanalysis-skill 根目录中运行"
    exit 1
fi

# 确认环境变量
echo "RACCOON_API_HOST=${RACCOON_API_HOST:-未设置}" && echo "RACCOON_API_TOKEN=${RACCOON_API_TOKEN:+已设置}"

# 调用小浣熊分析（文件上传到远程，远程执行代码画图）
python3 "$SKILL_DIR/scripts/main.py" analyze \
  --file "/absolute/path/to/雷达图测试数据.xlsx" \
  --prompt "这张表格为某县学生心理状态测评的各维度数据，请绘制雷达图，展示各维度数值，包括某县水平、平均值、标准差" \
  --show-code

1. 脚本会完成所有步骤并下载生成的雷达图到 ./raccoon/dataanalysis/
2. 将下载的图片路径告知用户，或用 open 命令打开

助手的错误行为（你绝对不能这样做）：

• ~~用 Read 工具读取 xlsx~~
• ~~用 python3 -c "import openpyxl..." 本地解析 Excel~~
• ~~用 pip3 install matplotlib 然后本地画图~~
• ~~说"技能无法启动"或"无法连接到数据分析服务"~~

生成物展示

分析完成后，生成物（图片/文件）会统一下载到 ./raccoon/dataanalysis/ 目录。展示给用户：

# macOS 打开图片
open ./raccoon/dataanalysis/chart.png

# 或列出所有生成物
ls -la ./raccoon/dataanalysis/

错误处理

业务错误码

沙盒运行时错误

脚本已内置自动重试（3次，间隔 5/10/20s）。

认证错误

SSE 流式响应说明（仅供理解，脚本已自动处理）

数据分析服务返回的 SSE 数据 stage 类型：

• generate — 文本回复
• code — 生成的代码
• execute/execution — 代码执行结果
• image — 图片
• ocr — OCR 识别

关键注意事项

• 不要本地分析数据，所有分析交给小浣熊远程 API
• 统一使用数据分析接口：无论是否有文件上传，都通过数据分析 API 处理
• 带文件的分析请求会把用户明确指定的文件上传到 RACCOON_API_HOST 指向的远程服务
• 所有接口需 Authorization: Bearer $RACCOON_API_TOKEN
• 数据分析接口支持 SSE 流式返回，脚本已处理
• 临时文件上传后 7 天过期
• s3_url 预签名 URL 约 30 分钟过期
• 所有生成物统一保存到 ./raccoon/dataanalysis/ 目录

参考文档

• references/API_REFERENCE.md — 完整 API 参考
• references/CHEATSHEET.md — 速查表