Pose CLI 文档

概览

Pose Coach 录制 → JointData3D CSV → Pose CLI → JSON 输出
                                              │
                                              ├── stats
                                              ├── detect_peak_energy
                                              ├── segment_motion_phases
                                              ├── detect_velocity
                                              ├── detect_action_boundaries
                                              ├── detect_highlight
                                              ├── annotate (web UI)
                                              └── ... 超过 15 个工具

内置轻量后端

Pose CLI 内置 pose serve — 一个零配置的本地服务器，将你的电脑变为 Pose Coach iOS App 的开发后端：

pose serve
# → http://0.0.0.0:8000
# → LAN  →  http://192.168.1.x:8000  （在 iPhone 上配置此地址）

运行前需先安装 pip install 'pose-platform[server]'（fastapi + uvicorn）。详见安装指南 →

在 iPhone 上录制 → 骨骼文件自动到达你的电脑。分析、AI 教练对话、训练计划和综合报告全部通过同一本地服务器运行。Pose Coach iOS App 将 pose serve 作为全功能后端连接。无需数据库、无需云端。配置指南 →

数据如何到达 Pose CLI

三种将录制数据从 iPhone（Pose Coach）传输到电脑的方式：

iPhone 录制 → 文件 App → iCloud Drive 或 AirDrop → 电脑 → pose analyze
✅ 全区域可用    ✅ 完整会话文件夹（视频 + 骨骼 + 附属文件）    ⚠ 每次手动操作
• iCloud Drive：通过文件 App 导出文件夹 → 通过 iCloud 同步到电脑
• AirDrop：导出全部数据 → ZIP 包含所有会话文件，直接发送（仅 Mac）

iPhone 录制 → 你的电脑（WiFi, pose serve）→ pose analyze
✅ 全区域可用    ✅ 自动上传 + 分析 + 对话    🔧 pip install pose-platform[server,llm]
（需要 TestFlight 版本 — 设置中的 研究者后端）

iPhone 录制 → Staging API（自动上传）→ pose data seed-session → 电脑 → pose analyze
✅ 全自动化      ❌ 中国不可用    ⚠ 不含 .mov 视频

推荐：首次录制使用AirDrop（路径 A）— 即时传输，无需配置。频繁录制时，一个命令即可配置路径 B：pose serve。完整本地后端配置指南 →

为未支持运动录制

如果你想分析 Pose Coach 尚未正式支持的运动（如篮球、高尔夫、网球）：

1. 打开 Pose Coach → 选择 Freeplay 作为运动
2. 正常录制 — 你会获得完整的 3D 骨骼数据
3. 将数据传输到电脑（使用上述路径 A 或 B）
4. 使用 Pose CLI 的通用工具（stats、segment_motion_phases、detect_action_boundaries、detect_highlight）进行分析
5. 在此基础上构建运动专项工具 — 参见贡献指南

适用人群

运动即插件

Pose CLI 使用 Python entry_points 自动发现运动包。内置运动（freeplay、sprint）随基础安装提供。额外运动以独立 pip 包形式安装：

# 内置（始终可用）
pose version
# → sports: freeplay, sprint

# 安装羽毛球 — 由羽毛球研究者维护的独立包
pip install pose-platform[badminton]
# → 安装 pose-sport-badminton（v1.13.4，8 个工具）

# 或直接安装运动包
pip install pose-sport-badminton

# 创建你自己的运动包
pose sports create basketball
# → 生成 sports/basketball/ 脚手架及示例工具
# → pip install -e sports/basketball
# → pose tools --sport basketball

# 列出已安装的运动
pose sports

面向研究者：运动包是由领域专家维护的独立 PyPI 包。每个包有自己的版本、发布周期和维护者。参见贡献指南 →

Web 标注工具

在浏览器中交互式标注录制数据，视频与 2D 骨骼叠加同步显示：

pose annotate serve data/session.csv
# → 自动打开 http://localhost:8001

在时间轴上拖拽即可标记动作（短跑阶段、挥拍、投篮）。标注数据可作为校准和算法验证的标准答案。

前提条件

Web 标注工具需要骨骼 CSV 和原始视频文件（.mov）。视频通过 iCloud Drive 或 AirDrop（路径 A）传输时包含，但本地后端和 Staging（路径 B/C）不包含视频。

界面

• 左侧面板：视频播放器 + 2D 骨骼叠加（15 根骨骼，21 个关节）+ 播放控制
• 右侧面板：标注列表 + 创建表单（起止时间、标签、质量、备注）

CLI 命令

# 创建标注
pose annotate create data/session.csv --start 2.3 --end 3.1 --label "sprint_drive"

# 列出所有标注
pose annotate list data/session.csv

# 打开 Web 标注界面
pose annotate serve data/session.csv

校准工作流

1. 标注录制数据（Web 或 CLI）— pose annotate serve
2. 自动评分已标注动作 — pose calib auto-label
3. 人工审查并修正评分（专家审核）
4. 验证工具一致性 — pose calib validate

核心原则

• 数据本地化。所有分析在你的机器上运行。无需上传到云端。
• 内置本地后端。pose serve 提供完整的开发后端 — iPhone 自动上传、分析和 AI 对话全部在本地运行。
• 一次编写，全平台使用。构建一个工具 — 即可在 CLI、Pose Coach 应用或你的自定义应用中使用。
• 可扩展设计。每个工具都是一个 Python 类。编写你自己的，注册后即可随处使用。
• 内置缓存。分析结果自动缓存。重复运行同一文件 → 即时返回结果。

快速入门 — 5 分钟

从零到完成首次分析。

pip install pose-platform
pose version

pose sample
# → sample_sprint.csv 已复制到当前目录（438 KB）

pose analyze sample_sprint.csv --tool stats

# 找出运动片段（短跑 vs 站立）
pose analyze sample_sprint.csv --tool segment_motion_phases

# 检测速度峰值
pose analyze sample_sprint.csv --tool detect_velocity --param joint=body_position

# 提取高光时刻
pose analyze sample_sprint.csv --tool detect_highlight --param sport_id=sprint

# 使用运动员档案测量短跑速度
pose analyze sample_sprint.csv --tool measure_running_speed \
    --param age=16 --param gender=male --param region=cn

pose analyze /path/to/your/data.csv --tool stats

pip install 'pose-platform[server,llm]'

pose serve
# → LAN  →  http://192.168.1.x:8000

安装指南

系统要求

方式一：pip（推荐）

pip install pose-platform
pose version

方式二：从源码安装（适用于工具开发者）

git clone https://github.com/posecap/pose-platform.git
cd pose-platform
pip install -e .

-e 参数表示"可编辑"模式 — 源码修改立即生效。

方式三：虚拟环境（干净隔离）

python3 -m venv pose-env
source pose-env/bin/activate        # macOS / Linux
# pose-env\Scripts\activate         # Windows

pip install pose-platform

可选依赖

# 运动包 — 安装专项运动分析工具
pip install 'pose-platform[badminton]'         # 羽毛球：挥拍检测、击球分类、评分
# pip install 'pose-platform[basketball]'     # 篮球（即将推出）

# 全部运动
pip install 'pose-platform[all-sports]'

# 本地后端 (pose serve) — 接收 iPhone 上传 + 运行分析服务器
pip install 'pose-platform[server]'

# LLM 对话 (pose chat) — 三种模式可选
pip install 'pose-platform[llm]'                   # REPL 模式（openai SDK）
pip install 'pose-platform[mcp]'                   # Claude Code 模式（mcp SDK, >=1.0,<2.0）

# 全部 — 所有运动 + 后端 + AI 对话
pip install 'pose-platform[all]'

# Claude Code 前端（可选，用于 --mode claude / --mode claude-ds）
npm install -g @anthropic-ai/claude-code

常见问题排查

python3 -m ensurepip --upgrade

pip install --break-system-packages pose-platform

# 添加到 ~/.zshrc 或 ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

# Windows（原生安装）— 先找到 Scripts 目录：
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
# → 例如 C:\Users\you\AppData\Roaming\Python\Python312\Scripts
# 将该目录加入 PATH（系统属性 → 环境变量），然后重启终端。

# 任何系统上的替代方案 — 不通过 pose 命令运行
python3 -m products.pose_cli.cli version   # Windows 上用 python

python3 -c "import platform; print(platform.machine())"
# 应输出：arm64

wsl --install
wsl
# 然后按上述 Linux 方式操作

pip install openai>=1.50
echo 'POSE_DEEPSEEK_API_KEY=sk-xxx' > .env   # 免费注册：platform.deepseek.com
pose chat

数据格式 — JointData3D

这是使用 Pose CLI 之前需要理解的最重要概念。每个工具都读取 JointData3D CSV 文件。

12 列格式

Pose CLI 接受无表头的 CSV 文件。每行代表一个时间戳上的一个关节。

timestamp, joint, wx, wy, wz, mx, my, mz, ldq_x, ldq_y, ldq_z, ldq_w

世界坐标 vs. 模型坐标

经验法则：所有生物力学分析都使用模型坐标（mx/my/mz）。所有内置工具默认使用模型坐标。

数据质量检查清单

• jitter_ratio < 0.3（运行 pose analyze data.csv --tool stats）
• tracking_coverage > 0.5（大部分录制时间骨骼被追踪到）
• 录制距离 2–8 米（ARKit 最佳范围）
• 全身可见（未被物体或其他人遮挡）
• 画面中仅一人（ARKit 只能追踪一个身体）
• 设备保持静止（建议使用三脚架）

从其他系统准备数据

如果你使用 OpenPose、MediaPipe、BlazePose 或动作捕捉系统，请将数据转换为 12 列格式。关键要求：

1. 时间戳：单调递增，自起始秒数
2. 关节顺序：必须匹配 19 关节 ARKit 人体骨骼（或使用字符串名称）
3. 模型坐标：如不可用，设为与世界坐标相同（部分工具精度会降低）
4. 四元数：如不可用，设为 ldq_x=0, ldq_y=0, ldq_z=0, ldq_w=1（单位四元数）

import numpy as np

# 你的数据：timestamps (T,), joint_names 列表, world_positions (T, J, 3)
for t_idx, t in enumerate(timestamps):
    for j_idx, jname in enumerate(joint_names):
        wx, wy, wz = world_positions[t_idx, j_idx]
        mx, my, mz = world_positions[t_idx, j_idx]  # 或计算模型坐标
        # 单位四元数：无旋转数据
        print(f"{t},{jname},{wx},{wy},{wz},{mx},{my},{mz},0,0,0,1")

CLI 命令参考

所有命令在本地运行。分析命令无需网络连接。

pose analyze

对 JointData3D CSV 文件运行分析工具。

pose analyze <file.csv> [--tool <name>] [--no-cache] [--param KEY=VALUE ...]

# 基本分析
pose analyze data/session.csv

# 指定工具
pose analyze data/session.csv --tool detect_peak_energy

# 带参数
pose analyze data/session.csv --tool measure_running_speed \
    --param age=16 --param gender=male --param region=cn

# 强制重新计算
pose analyze data/session.csv --tool stats --no-cache

pose tools

列出所有已注册的工具，含版本号。

pose tools                  # 简洁表格：名称、版本、状态、运动、描述
pose tools --detail         # 每个工具的完整参数详情
pose tools --sport <id>     # 按运动筛选（如 badminton、sprint）

pose sample

将内置的示例数据文件（sample_sprint.csv）复制到当前目录。无需网络 — 示例文件已包含在 pip 包中。

pose sample
# → 示例数据已复制到当前目录（438 KB）
# → 下一步：pose analyze sample_sprint.csv --tool stats

pose sports

管理运动：列出已安装的运动、添加自定义运动或创建新的运动包。

pose sports list                # 内置 + 已安装运动包（默认）
pose sports add <id>            # 添加自定义运动（写入 .pose/config.json）
pose sports remove <id>         # 移除自定义运动
pose sports create <id>         # 生成新的运动包脚手架

安装运动包：额外运动以独立 pip 包形式分发。通过 pip extras 或直接安装：

pip install pose-platform[badminton]
# 或
pip install pose-sport-badminton

创建新运动：使用 pose sports create 生成脚手架，然后以可编辑模式安装：

pose sports create basketball
# → 生成 sports/basketball/ 含 pyproject.toml、示例工具、测试
pip install -e sports/basketball
pose tools --sport basketball

pose gaps

管理能力缺口登记 — 本地追踪功能请求与工具构想。

pose gaps list                           # 活跃的缺口
pose gaps list --all-statuses            # 全部包括已解决的
pose gaps submit "<title>"               # 登记新的缺口
pose gaps show <gap_id>                  # 查看缺口详情及临时实现
pose gaps summary                        # 统计摘要

pose cache

管理分析结果缓存。当源文件或工具版本变更时缓存自动失效。

pose cache list                          # 所有缓存条目
pose cache clear                         # 清空全部缓存
pose cache clear <file.csv>             # 清空特定文件的缓存

pose version

显示版本信息 — 动态检测已安装的运动包。

pose version                            # 平台 + 已安装运动
pose version --changelog                # 技术更新日志（CHANGELOG.md）
pose version --release-notes            # 面向用户的发布说明

示例输出：

{
  "platform": "1.25.10",
  "sports": {
    "freeplay":  {"version": "1.25.10", "builtin": true},
    "sprint":    {"version": "1.25.10", "builtin": true},
    "badminton": {"version": "1.13.4", "builtin": false, "tools_count": 8}
  }
}

pose chat

启动交互式 LLM 分析会话。需要 [llm] 扩展（pip install openai）和 API key。配置方式见LLM 对话。

pose chat [data_dir]                    # 默认数据目录：../pose-data

pose annotate

创建、列出和删除录制的标注。也可启动 Web 标注界面。

pose annotate create <file.csv> --start <s> --end <s> --label <名称>
                                [--peak_s <s>] [--hand left|right]
                                [--quality good|acceptable|poor] [--note "备注"]
pose annotate list <file.csv>
pose annotate delete <file.csv> <标注ID>
pose annotate serve <file.csv>       # Web 标注界面

pose calib

评分校准工作流 — 将工具评分与专家标注进行对比，验证算法准确性。

pose calib auto-label                  # 自动评分已标注动作
pose calib validate                    # 对比专家标注验证工具一致性

pose feedback

提交和管理反馈 — 包括 bug 报告、功能请求和工具改进建议。

pose feedback list                     # 列出所有反馈
pose feedback stats                    # 统计摘要
pose feedback resolve <id>            # 标记为已解决
pose feedback dismiss <id>            # 带原因驳回

pose telemetry

pose telemetry stats                    # 今日统计
pose telemetry stats --since 7d         # 最近 7 天
pose telemetry stats --since 24h        # 最近 24 小时

pose data

管理本地数据文件。

pose data delete <file> [--yes] [--dry-run]

工具参考

Pose CLI 拥有 20+ 内置工具。以下是三个主要的通用工具。运动专项工具文档见完整仓库。

pose analyze data/session.csv --tool stats

# 篮球 — 找出跳跃、投篮、突破
pose analyze data/basketball_play.csv --tool detect_action_boundaries \
    --param min_action_duration_s=0.2 --param min_peak_gap_s=0.3

# 短跑 — 找出发力阶段
pose analyze data/sprint_100m.csv --tool detect_action_boundaries \
    --param onset_energy_ratio=0.01

pose analyze data/basketball_drill.csv --tool segment_motion_phases

环境变量

分析与数据

LLM 提供商（用于 pose chat）

对话模式

区域与语言

缓存机制

Pose CLI 缓存工具结果以避免重复计算相同分析。缓存键为：文件标识（mtime + size）+ 工具名称 + 工具版本。

缓存失效

源文件变更（mtime/size）或 pose-manifest.json 中工具版本变更时，缓存自动失效。工具升级后旧缓存自动作废。

缓存命令

pose cache list                          # 所有缓存条目
pose cache clear                         # 清空全部缓存
pose cache clear <file.csv>             # 清空特定文件的缓存

跳过缓存：pose analyze data.csv --tool stats --no-cache。命中缓存时 CLI 输出 [CACHE HIT]。

CI/CD 集成

在 CI 流水线中缓存 .pose/cache/ 目录。以 pose-manifest.json 的哈希值作为缓存键可在工具版本升级时正确失效。

LLM 驱动的分析（pose chat）

Pose CLI 包含 AI 对话模式，让你用自然语言询问数据问题。默认使用 DeepSeek — 免费额度，邮箱注册，全球可用。

快速配置

安装 LLM 扩展并创建 .env 文件 — Pose CLI 自动加载。无需 export、无需 source。

pip install 'pose-platform[llm]'
echo 'POSE_DEEPSEEK_API_KEY=sk-xxx' > .env
pose chat

在 platform.deepseek.com 免费注册获取 DeepSeek API key。

提供商配置

echo 'POSE_DEEPSEEK_API_KEY=sk-xxx' > .env
pose chat

export ANTHROPIC_API_KEY=sk-ant-...
pose chat

export POSE_REGION=cn
export POSE_CN_API_KEY=sk-xxx
pose chat

对话模式

pose chat 支持三种前端模式。通过 --mode 参数或 POSE_CHAT_MODE 环境变量切换。

# REPL 模式（默认）
pose chat

# Claude Code + Claude 原生（最佳体验）
npm install -g @anthropic-ai/claude-code
pip install 'pose-platform[mcp]'
pose chat --mode claude

# Claude Code + DeepSeek
echo 'POSE_DEEPSEEK_API_KEY=sk-xxx' > .env
pose chat --mode claude-ds

注意：如果你直接启动 Claude Code（不通过 pose chat），则需要自行设置 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN。pose chat --mode claude-ds 会自动为你完成这些配置。

使用 --mode claude 或 --mode claude-ds 时，Pose CLI 同时自动生成临时 .mcp.json，将 Claude Code 连接到 pose-analysis MCP 服务器并加载所有已注册工具 — 无需手动配置。

区域路由

默认配置在所有区域使用 DeepSeek。可通过 pose-manifest.json 或环境变量覆盖。

# 默认路由：
# US/EU 区域：DeepSeek (http_api) → Claude（如已配置则回退）
# CN 区域：  Qwen-Plus (http_api) → DeepSeek（回退）

# 强制指定区域：
export POSE_REGION=cn    # CN 路由（需 manifest 配置）
export POSE_REGION=us    # US 路由（默认）

示例会话

> 这段录制中有多少个动作片段？
[Tool: detect_action_boundaries] 检测到 14 个动作片段

> 最快的是哪个？
[Tool: detect_velocity] 峰值在 2.3 秒，18.5 m/s

> 分析跑步步态模式
[Tool: analyze_running_gait] 步频：180 spm，对称性：0.94，...

本地后端配置

用 iPhone 上的 Pose Coach 录制运动数据，骨骼文件自动传输到你的电脑 — 无需云端、无需 staging 服务器、无需 Mac。

前提条件

• iPhone 已通过 TestFlight 安装 Pose Coach（联系我们获取邀请链接）
• 电脑 已安装 Pose CLI（在 pose_platform 仓库中 pip install -e .）
• 两台设备连接同一 WiFi 网络

步骤 1：启动本地后端

# 安装服务端扩展（如尚未安装）
pip install 'pose-platform[server,llm]'

# 启动后端
pose serve
# → http://0.0.0.0:8000
# → LAN  →  http://192.168.1.x:8000  （在 iPhone 上配置此地址）
# → data → /Users/you/pose-data

服务器默认监听所有网络接口，局域网 IP 自动打印。可选参数：pose serve --port 9000、pose serve --data-dir ~/my-data。

步骤 2：在 iPhone 上配置 Pose Coach

1. 在 iPhone 上打开 Pose Coach
2. 进入设置（齿轮图标）
3. 滚动到 研究者后端 区域
4. 选择自定义 URL
5. 输入 http://<你的IP>:8000（例如 http://192.168.1.42:8000）
6. 点击应用
7. 按提示重启应用

步骤 3：录制与分析

1. 在 Pose Coach 中选择 Freeplay（任何尚未正式支持的运动都用此模式）
2. 录制动作 — 停止录制后骨骼 CSV 自动上传
3. 文件自动到达 pose-data/ 目录

# 查看到达的文件
ls pose-data/*_3d.csv | tail -5

# 运行分析
pose analyze pose-data/20260723T140000_seg_1_iPhone_3d.csv --tool stats
pose analyze pose-data/20260723T140000_seg_1_iPhone_3d.csv --tool segment_motion_phases
pose analyze pose-data/20260723T140000_seg_1_iPhone_3d.csv --tool detect_action_boundaries

步骤 4（可选）：获取视频文件

.mov 视频不会上传到后端（隐私保证）。获取方式：

1. 在 Pose Coach 录制后，点击导出按钮（分享图标）
2. 选择保存到文件 → iCloud Drive
3. 在电脑上从 iCloud Drive 下载
4. .mov 视频与 _3d.csv 骨骼文件同名配对

支持的端点

pose serve 实现了 20+ 个与 Pose Coach iOS App 兼容的 API 端点：

pose serve 与云端后端对比

常见问题排查

贡献指南

Pose CLI 被设计为可扩展的。构建新工具、添加运动支持或贡献代码。

构建新工具

一个工具就是一个 Python 类。编写一次，注册后即可在任何地方使用 — CLI、Pose Coach 应用、自定义应用。

from capabilities.tools.base import DirectTool
from capabilities.tools.loader import load_pose
import json
from pathlib import Path


class MyTool(DirectTool):
    name = "my_tool"
    description = "这个工具做什么"
    input_schema = {
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "CSV 文件路径"},
            "my_param": {"type": "number", "default": 1.0},
        },
        "required": ["path"]
    }
    status = "wip"                     # "wip" 或 "stable"
    supported_sports = []              # [] = 所有运动
    tier = 1                           # 1 = 主要, 2 = 备选
    depends_on = []                    # 可选：工具依赖
    requires_session_context_by_sport = ["badminton"]  # 可选：运动专项元数据

    def run(self, tool_input: dict, output_dir: Path) -> str:
        pose = load_pose(tool_input["path"])
        result = {"your_field": 42}
        return json.dumps(result, ensure_ascii=False)

export POSE_ENABLE_WIP_TOOLS=1
pose tools | grep my_tool
pose analyze data/test.csv --tool my_tool

扩展运动支持

三行代码添加一项新运动：

# pose_platform_core/sports_catalog.py
OFFICIAL_SPORTS = [
    # ... 已有的 ...
    SupportedSport(id="basketball", since_version="1.24.0"),
]

然后构建工具时设置 supported_sports = ["basketball"]。通用工具会自动适用。

将工具提升为稳定版

1. 编写单元测试（≥ 1 个）— pytest tests/unit/
2. 使用 10+ 个真实录制数据进行测试
3. 测试边缘情况（空数据、单帧、缺失关节）
4. 在 docs/features/<tool_name>.md 中添加文档
5. 将工具类中的 status = "stable"
6. 在 pose-manifest.json → tools 中添加版本条目

分发你的工具

两种分发自定义工具的方式：

数据加载最佳实践

• 使用 pose.mpoints（模型坐标）进行生物力学分析
• Oreason 过滤是自动的 — load_pose() 会排除异常帧
• 使用 pose.joint_names 动态查找关节索引
• 在输出中返回 data_quality 以帮助用户评估结果可靠性
• 算法变更时在 pose-manifest.json 中提升工具版本 — 旧缓存自动失效

许可证

Pose CLI — 运动分析工具包 · 版权所有 © 2026 PoseCap Inc. 保留所有权利。

@software{pose_platform,
  title = {Pose Platform: Open Motion Analysis Toolkit},
  author = {{PoseCap Inc.}},
  year = {2026},
  url = {https://github.com/posecap/pose-platform},
}