posecode-mcp

Posecode

以文本描述运动学动作。
一种可检查、可编辑的动作格式，适用于动画工具、大模型和 Web 产品。

如同用于动作描述的 Mermaid：用简短的文本文件描述、验证并渲染
确定性人体动作，且无需将源内容藏在黑箱中。

在线体验 · 动作库 · 语言规范（SPEC.md） · 大模型编写指南 · 示例 · MCP 服务

---

为什么选择 Posecode？

动画片段和生成的轨迹可以展示动作，但往往会隐藏生成动作时所作的语义决策。

Posecode 会将这些决策保留在易读的源文件中。人可以编写文档，动画工具可以生成文档，大模型也可以起草文档。解析、验证、编辑和渲染都不需要 AI 模型。

_{一个 .posecode 文档 — shoulders: abduct 160、 hips: abduct 30、 repeat 12 — 在浏览器中实时渲染。}

例如：

弯曲膝盖，将臀部向后移动，并保持胸部挺直。

人可能理解这条指令，但渲染器无法可靠地确定：

• 哪些关节应该移动，
• 移动多少度，
• 使用哪个坐标系，
• 持续多长时间，
• 按什么顺序进行，
• 或者有哪些物理限制。

人、工具和语言模型都需要一种通用语法，以可渲染、可测试的形式表达动作。

Posecode 提供了这种缺失的表示形式。

28 秒了解 Posecode

从易读的动作源文件，到经过验证的 3D 渲染、MCP 工具，以及 只需一个脚本即可嵌入网页。

▶ 观看 28 秒的构建器演示
_{输入纯文本，输出流畅、可编程的 3D 动作。}

### 动作示例

pelvis: hinge — 硬拉

knees: flex 95 — 深蹲

shoulders: abduct 90 — 侧平举

---

为什么不使用扩散式文本转动作？

神经文本转动作系统可以生成令人印象深刻的动作，但用于轻量、可编程的应用时，会带来一些问题。

资源开销大

许多系统需要大型模型和 GPU 推理，导致在消费级设备上进行实时部署成本高昂。

难以控制

它们通常生成坐标轨迹，而不是可编辑的语义指令。

想要提出精确的修改要求并不容易，例如：

在第二阶段将膝关节屈曲角度减少 10 度。

难以验证

黑盒轨迹不会自然呈现可读的关节规则、阶段定义或活动范围限制。

难以调试

动作看起来不对时，开发者可能不知道是哪条语义指令导致了问题。

---

Posecode 方法

Posecode 使用轻量、文本驱动的工作流。

• 易读： 动作以小型 .posecode 文档存储。
• 结构化： 关节、动作、角度、时间安排和约束都明确列出。
• 可编辑： 开发者和模型可以修改单个动作属性。
• 快速： 解析和渲染都在客户端完成。
• 确定性： 相同的 Posecode 输入会生成相同的验证后表示。
• 可检查： 解析器警告和保真度检查能够说明问题所在。
• 适合 Agent： MCP 服务提供生成、验证、评估和分享工具。
• 注重安全： 编写的角度和由 IK 生成的角度都会受已配置的活动范围限制。

---

30 秒了解核心概念

.posecode 文件通过带时间安排的阶段及其指定的关节动作来描述动作。

1. 编写 .posecode	2. 渲染动作
posecode exercise "徒手深蹲" rig humanoid pose start = standing step "下蹲" 1.6s settle:   hips: flex 80   knees: flex 95   ankles: dorsiflex 14   ground-lock: feet   cue "臀部向后坐" step "站起" 1.2s drive:   hips: flex 0   knees: flex 0   ankles: dorsiflex 0   ground-lock: feet repeat 8

---

OpenAI Build Week 2026： Posecode 在黑客马拉松之前就已存在。在 Build Week 期间，项目使用 Codex（运行于 GPT-5.6）作为主要工程工具进行了扩展，完成了一批实际交付的工作：动作与接地质量、语言契约诊断、许可证结构调整、发布自动化以及面向产品的页面。下文根据实际提交历史区分此前完成的工作与 Build Week 期间的工作，而非路线图。

---

OpenAI Build Week 扩展

Build Week 之前已有的内容

Build Week 之前，Posecode 已经包含：

• 核心 .posecode 领域专用语言，
• 解析器和中间运动表示，
• 基本的活动范围验证，
• Three.js/WebGL 渲染器，
• 正向运动学，
• 基本的逆运动学和地面锁定行为，
• 浏览器 Playground，
• 动作示例文件，
• 可分享的 Posecode 链接，
• 以及 MCP 服务基础架构。

这个早期版本主要借助 Claude 作为 AI 辅助工程工具开发。

这些前期工作为项目奠定了基础，但并未被列为本次黑客马拉松的新增贡献。

Build Week 期间新增的内容

以下每项都是已合并且注明日期的拉取请求，使用 Codex（GPT-5.6）构建——直接链接请参见Build Week 证据。

1. 运动与接地全面升级 — 受 ROM 约束的触及 IK、语义化的手掌／拳头／脚底／膝盖／骨盆接触面、多接触点优化、稳定的支撑转换，以及适配 XBot 的接地功能（#76）。
2. 语言规范与诊断 — Posecode 语言／IR v0.3 自定义起始姿势块（支持经 ROM 检查的覆盖）、实时和整个片段范围内的接地／自碰撞诊断，以及易于使用的公制地面辅助线（#92）。
3. 许可证重组 — 将单体仓库拆分为 Apache-2.0 标准层（规范、解析器、分享、语言、LSP、VS Code）和 AGPL-3.0 产品层（渲染、嵌入、MCP、评估、Playground），并提供商业许可证途径（#84）。
4. 发布自动化 — 通过 GitHub OIDC 使用 Changesets 发布 npm 包、发布到 MCP Registry，以及在 CI 中验证软件包版本、入口点和 tarball 内容（#66）。
5. 第三方集成就绪 — Posecode 0.2 时序词汇（drive/settle/flow/snap）、解析器验证 CLI，以及嵌入兼容性元数据（#62）。
6. 地面锁定正确性 — 由解析器负责验证左右两侧脚／手／肘的地面锁定，并为仰卧动作提供背部接触支撑，取代对无效接触的静默接受（#61、#64）。
7. LLM 优先的落地页和产品页 — 重新设计落地页，围绕提示词 → Posecode → 实时 3D 展开叙述；新增 /for-products 页面，为集成方介绍 Web 组件、解析器、渲染器和 MCP 服务（#82、#74）。
8. 移动端和搜索修复 — 移动端工具栏／查看器布局、自然的手部朝向，以及 Google 搜索索引修正（#78、#65）。

Build Week 功能状态

• 运动／接地质量全面升级已发布（#76）
• 语言规范 + 诊断已发布（#92）
• 许可证重组已发布（#84）
• 发布自动化已发布（#66）
• 地面锁定正确性已发布（#61、#64）
• 落地页／产品页已发布（#82、#74）

---

GPT-5.6 的使用方式

在 Build Week 期间，Codex 会话使用 GPT-5.6（GPT-5.6 Terra）运行，这是为本次活动提供 Codex 支持的模型。GPT-5.6 是上述每项 Build Week 改动背后的推理引擎：读取现有的 monorepo，在 #76 中提出受 ROM 约束的 IK 和接触面设计，在 #92 中设计语言/IR v0.3 诊断功能，并在 #84 中起草许可边界。

借助 GPT-5.6 的自然语言转 Posecode 生成功能（用通俗英语描述一个动作，获取经过验证的 .posecode 文档）是顺理成章的下一步，因为现有的 posecode_authoring_guide MCP tool 已具备基础，但该功能尚未开发——此处并未声称它已作为已发布功能提供。

---

Codex 的使用方式

Codex 是 Build Week 扩展所使用的主要工程工具。

在黑客松期间，Codex 用于：

• 在每次改动之前检查并理解现有的 monorepo，
• 设计并实现受 ROM 约束的触及 IK 和接触面系统（#76），
• 设计并实现语言/IR v0.3 诊断功能和地面指南（#92），
• 重构整个 monorepo 的软件包许可（#84），
• 构建 Changesets/OIDC npm 和 MCP Registry 发布流水线（#66），
• 修复地面锁定验证和静默接受错误（#61、#64），
• 重新设计着陆页并添加产品集成页面（#82、#74），
• 为每项改动编写单元、集成和评估框架测试，
• 以及修复移动端 UI 和搜索索引回归问题。

Codex 能加快实现进度，但项目仍由人类主导。以下决策均经过人工审核和选择：DSL 语义、系统架构、许可边界、生物力学约束、验证策略、用户体验，以及对生成代码的接受或拒绝。

Codex 开发工作流

Build Week 工作流遵循以下流程：

1. 明确具体的产品或工程问题。
2. 请 Codex 检查相关实现。
3. 请求一种或多种可能的方案。
4. 审核权衡因素并选择架构。
5. 使用 Codex 实现所选方案。
6. 运行类型检查、测试和生物力学评估（npm run eval）。
7. 手动检查失败项。
8. 通过更多 Codex 会话完善实现。
9. 在提交前审核最终改动。

---

Build Week 证据

所有 Build Week 工作均已公开，标注日期，并在下方直接链接——没有占位内容。

Build Week 拉取请求

PR	已合并	完成内容
#62	2026-07-15	Posecode 0.2 时序词汇、验证 CLI、嵌入兼容性
#61	2026-07-15	按侧进行的地面锁定验证
#65	2026-07-16	Google 搜索索引修复
#66	2026-07-16	npm + MCP Registry 发布自动化
#64	2026-07-16	仰卧动作的背部地面锁定
#74	2026-07-16	/for-products 集成页面
#76	2026-07-17	动作/接地全面改进：受 ROM 约束的到达 IK、接触面
#78	2026-07-17	移动端查看器尺寸调整与自然手部朝向
#82	2026-07-17	面向大模型的首页重新设计
#84	2026-07-17	Apache-2.0 / AGPL-3.0 许可结构调整
#92	2026-07-19	语言/IR v0.3、接地/自碰撞诊断、地面引导

Build Week 对比

Build Week 之前	Build Week 期间新增
核心 Posecode DSL	语言/IR v0.3 自定义起始姿势区块
基本 ROM 限制	接地、自碰撞和地面引导诊断
可用的 IK/接地功能	受 ROM 约束的到达 IK，支持语义接触面
单一许可文件	Apache-2.0 / AGPL-3.0 分层许可，并提供商业路径
手动发布	自动化 npm + MCP Registry 发布流程
编辑型首页	面向大模型的首页 + /for-products 集成页面
现有测试	新增诊断、IK 和许可回归测试

---

---

架构

┌─────────────────────────┐
│ Natural-language prompt │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ GPT-5.6 authoring layer │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│     .posecode source    │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ Parser and ROM checking │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ Kinematics and IK layer │
└────────────┬────────────┘
             │
             ├─────────────────────┐
             ▼                     ▼
┌─────────────────────────┐  ┌──────────────────────┐
│ Three.js/WebGL renderer │  │ Fidelity measurements│
└─────────────────────────┘  └──────────┬───────────┘
                                        │
                                        ▼
                             ┌──────────────────────┐
                             │ GPT-5.6 Physics     │
                             │ Critic and revision │
                             └──────────────────────┘

---

安装与使用

在线 Playground

无需安装，即可预览、编辑和分享动作：

https://posecode.org/play

---

本地开发

要求：

• Node.js 20 或更高版本
• npm

克隆仓库：

git clone https://github.com/posecode-dev/posecode.git
cd posecode

安装依赖：

npm install

启动 Playground：

npm run dev

运行测试：

npm test

运行类型检查：

npm run typecheck

运行保真度评估：

npm run eval

构建 Playground：

npm run build

---

编辑器支持

VS Code 扩展为 .posecode 文件提供语法高亮、ROM 诊断和自动补全——请参阅 editors/vscode。扩展发布前，你可以将 .posecode 文件关联到 Markdown，以立即启用基本的高亮显示：

"files.associations": {
  "*.posecode": "markdown"
}

请参阅编辑器指南 ，了解 VS Code、Cursor、Sublime Text 和 Neovim 的配置说明。

---

MCP 服务

Posecode 包含一个供 AI Agent 使用的 Model Context Protocol 服务。

运行方式：

npx -y posecode-mcp@latest

MCP 客户端配置示例：

{
  "mcpServers": {
    "posecode": {
      "command": "npx",
      "args": ["-y", "posecode-mcp@latest"]
    }
  }
}

MCP 服务提供：

• validate_posecode
• render_posecode

完整配置和工具文档请参阅 packages/posecode-mcp。

---

Web 组件嵌入

在页面中嵌入 Posecode 播放器：

<script src="https://unpkg.com/posecode-embed/dist/posecode-embed.js"></script>

<posecode-player src="/movements/squat.posecode"></posecode-player>

播放器可用于：

• 文档，
• 教育内容，
• 锻炼指南，
• 博客文章，
• 以及动作库。

---

核心库

安装解析器：

npm install posecode-parser

安装渲染器：

npm install posecode-render

示例：

import { parse } from "posecode-parser";
import { createViewer } from "posecode-render";

const source = `
posecode exercise "Lateral raise"
  rig humanoid
  pose start = standing

  step "Raise" 1.4s settle:
    shoulders: abduct 90
`;

const { ir, errors, warnings } = parse(source);

if (!ir || errors.length > 0) {
  console.error(errors);
} else {
  console.warn(warnings);
  const viewer = createViewer(document.querySelector("#viewer"));
  viewer.load(ir);
  viewer.play();
}

#viewer 元素是一个 HTML <canvas>。

导出动作（BVH）

posecode-render 可以将动作烘焙为 Biovision Hierarchy （.bvh）文件，以便导入 Blender 和其他动画工具。在 Playground 中，使用 Download BVH 按钮；以编程方式导出：

import { parse } from "posecode-parser";
import { exportBVH } from "posecode-render";

const { ir } = parse(source);
const bvh = exportBVH(ir!, { fps: 30 }); // string, ready to write to disk

选项：fps（默认值为 30）、scale（默认值为 1，即米；传入 100 表示厘米）、includeFingers（默认值为 false），以及用于校准骨架的 proportions。

• **坐标系：**右手系，Y 轴朝上；人物在静止姿势下朝向 +Z（与渲染器和 Three.js 相同）。启用 Blender 的 “Y up” BVH 导入选项。
• **单位：**默认使用米。
• 旋转通道：Zrotation Xrotation Yrotation（欧拉角顺序为 ZXY）。
• **范围：**此功能导出创作的关节动作，以及根节点的位移和转向。目前不会重新运行渲染器的接触/IK 求解，因此依赖 IK 的动作（例如 reach: hand_left floor）导出的是创作的姿势，而非求解后的姿势。请参阅 issue #63。

导出动作（glTF / GLB）

对于 Web 动画工作流，posecode-render 可以将骨架以及烘焙后的动画片段导出为 glTF/GLB 资源。在 Playground 中，使用 Download glTF；以编程方式导出：

import { parse } from "posecode-parser";
import { exportGLTF } from "posecode-render";

const { ir } = parse(source);
const glb = await exportGLTF(ir!);            // GLB ArrayBuffer (default)
const gltf = await exportGLTF(ir!, { binary: false }); // glTF JSON object

导出的文件可通过 Three.js GLTFLoader 加载，动画片段可在内置骨架上播放：

const gltf = await new GLTFLoader().loadAsync(url);
const mixer = new THREE.AnimationMixer(gltf.scene);
mixer.clipAction(gltf.animations[0]).play();

• 关节节点以 Posecode 骨骼 ID 命名；动画根节点为 posecode_root。
• 限制：导出的是程序生成的人偶骨架，而非 humanoid/Mixamo 骨架，因此目前无法重定向到外部骨架；与 BVH 一样，导出的是创作的动作，而非接触/IK 求解后的动作。请参阅 issue #90。

---

Posecode 如何保持准确

Posecode 使用多层检查机制。

1. 运动范围钳制

渲染前会限制关节角度。

例如：

knees: flex 200

会将角度钳制在配置的膝关节屈曲限值内，并发出警告，而不是渲染不可能的角度。

2. 运动学评估

引擎会在以下步骤完成后测量实际生成的骨架：

• 解析，
• 正向运动学，
• 逆向运动学，
• 以及地面锁定修正。

3. 几何保真度不变量

动作示例可以定义预期属性。

例如，硬拉可能要求：

• 躯干倾斜度足够，
• 膝盖向前移动的距离有限，
• 足部接触稳定，
• 髋部运动对称。

4. GPT-5.6 Physics Critic

Build Week Critic 会结合动作解读与确定性测量结果进行评估。

它会用自然语言解释生物力学问题，并提出具体的修改建议。

---

软件包

软件包	用途
posecode-language	语言定义和编辑器支持
posecode-parser	将 .posecode 文本转换为经过验证且受范围约束的中间表示
posecode-render	使用 Three.js、正向运动学和 IK 渲染动画人物
posecode-share	将 Posecode 文档编码为 URL 安全的分享令牌
posecode-mcp	通过 MCP 向 AI Agent 提供 Posecode 功能
posecode-eval	运行无头生物力学和几何保真度评估
playground	交互式编辑器、3D 视口、警告、生成、评析和分享

---

技术

Posecode 使用以下技术构建：

• TypeScript
• JavaScript
• Node.js
• Three.js
• WebGL
• Vite
• CodeMirror
• Model Context Protocol
• Zod
• Vitest
• Playwright
• esbuild
• GPT-5.6
• Codex

---

范围

版本 0.1

Posecode 目前侧重于：

• 单人肢体动作，
• 健身，
• 物理治疗演示，
• 姿势，
• 舞蹈，
• 教育，
• 康复可视化，
• 正向运动学，
• 地面锁定，
• 受 ROM 约束的逆向运动学，
• 髋部屈伸，
• 站立、坐姿和躺卧姿势，
• 基础场景道具，
• 以及基于浏览器的渲染。

暂缓支持

以下内容不在当前范围内：

• 双人或搭档动作，
• 全面的碰撞检测和刚体动力学，
• 详细的物体物理模拟，
• 高级器材模拟，
• 多关节手指动画，
• FBX 或 GLB 动画导出，
• 以及医学诊断。

---

限制与安全

Posecode 是一个工程与可视化项目。

其活动范围数值和生物力学检查基于通用参考数据和简化模型。

这些内容不构成：

• 医疗建议，
• 诊断，
• 预防伤害的保证，
• 物理治疗处方，
• 或合格专业人员的替代方案。

生成的动作在用于医疗保健、康复或安全关键型应用之前，应由合格专家审核。

---

潜在应用

Posecode 可用于：

• 游戏和角色动画，
• 健身指导，
• 运动可视化，
• 解剖学教育，
• 物理治疗演示，
• 姿势训练，
• 舞蹈和编舞原型设计，
• 运动技巧分析，
• 机器人研究，
• 合成运动数据生成，
• 以及具身 AI 系统。

---

仓库结构

posecode/
├── packages/
│   ├── posecode-language/
│   ├── posecode-parser/
│   ├── posecode-render/
│   ├── posecode-share/
│   ├── posecode-mcp/
│   └── posecode-eval/
├── playground/
├── editors/
├── spec/
├── docs/
├── scripts/
└── README.md

---

测试

运行所有单元测试：

npm test

运行覆盖率测试：

npm run coverage

运行类型检查：

npm run typecheck

运行生物力学评估：

npm run eval

CI 工作流会验证项目是否：

• 成功构建，
• 通过类型检查，
• 通过单元测试，
• 并满足已配置的动作不变量。

---

背景

Posecode 遵循以下设计研究：

面向大模型的运动学动作定义协议

该项目探索语义化的文本动作程序能否为黑盒动作生成提供一种可控、可检查的替代方案。

语言规范与契约

Posecode 将规范性协议定义与可选的提示词辅助材料分开：

• 规范性协议规范（spec/SPEC.md）（或访问网页 posecode.org/spec.html）：权威规范，定义了语法、骨骼、关节动作、活动范围限制、接触语义（ground-lock、reach、pin、grip）、求解器不变量和中间表示（IR）。
• LLM 编写指南（spec/llm-authoring.md）（或访问网页 posecode.org/llm-guide.html）：一份独立的任务导向提示词指南，用于借助生成模型起草 .posecode 文档。

接触语义速查

• pin moves the body：平移人物的浮动根节点，使末端效应器与锚点相接（pin: knee_left floor）。每个阶段最多接受一个 pin。
• reach moves the limb：沿肢体链引导逆向运动学，不平移根节点（reach: hand_left floor）。
• ground-lock：保持现有的地面支撑状态（ground-lock: feet）。多个同时存在的地面接触（例如双脚着地）必须通过 ground-lock 或单独的 reach 指令处理，绝不能使用多个 pin。
• grip：双手支撑已声明的 bar 或 dip-bars 道具。
• cue：仅用于显示的指导文本；不会改变运动学、约束或播放。

另请参阅：

• docs/market-research.md

角色资源

目前，托管版 Playground 使用 Adobe Mixamo 角色和一个展示动画，并遵循适用的 Adobe 条款。这些二进制资源不受 Posecode 软件许可证涵盖。请参阅第三方声明。

渲染器还包含一个无需资源的程序化角色，并支持通过 characterUrl 加载兼容的人形 GLB 角色。

多种角色外观（avatar avatar1 / avatar2 / avatar3）

所有内置角色都使用相同的 rig humanoid 骨架拓扑。可选的 avatar 指令用于选择外观，而无需重新定义该骨架（参见 spec/SPEC.md）。向 createViewer 传入 characterUrls（选择器 → GLB URL 映射）， 而不是单个 characterUrl；如果存在 ir.avatar，则使用它，否则由 ir.rig 提供默认选择器。切换文档或编辑 avatar 指令都会更换可见角色。如果映射中没有对应选择器（或加载失败）， 则会回退到程序化角色。关于此选项，请参阅 packages/posecode-render/README.md； 如需在 Web 组件中实现相同行为，请参阅 packages/posecode-embed 的 character 属性文档（默认不设置；设置明确的 URL 可固定使用某个角色，不受 avatar 影响）。

使用自己的角色骨架

传入指向带蒙皮 GLB 的 characterUrl（固定角色）或 characterUrls（按选择器选择，见上文）， 即可替换捆绑的 Mixamo 角色。要求：

• **格式：**包含 THREE.SkinnedMesh 的 glTF 二进制文件（.glb）。
• **静止姿势：**T 姿势。
• **骨骼命名：**Mixamo 约定。名称可以带有 mixamorig: / mixamorigN: 命名空间前缀，系统会自动移除。必须包含以下所有骨骼：
  • 躯干／头部：Hips、Spine、Spine2、Neck、Head
  • 手臂：LeftArm、LeftForeArm、LeftHand、RightArm、RightForeArm、RightHand
  • 腿部：LeftUpLeg、LeftLeg、LeftFoot、RightUpLeg、RightLeg、RightFoot
  • 手指（仅第一节指骨）：LeftHandThumb1、LeftHandIndex1、 LeftHandMiddle1、LeftHandRing1、LeftHandPinky1，以及对应的 RightHand*1

如果缺少任何必需骨骼，角色加载就会失败，查看器会静默回退到无需资源的程序化角色——错误的骨架 不会破坏场景。

获取兼容骨架最简单的方式是访问 mixamo.com： 导出 T 姿势角色并选择“skin with skeleton”，然后将 FBX 转换为 GLB（例如，使用 Blender 的 glTF 导出器或 FBX2glTF）。骨骼名称 会自动符合 Mixamo 约定。

骨骼映射表和重定向／校准逻辑位于 packages/posecode-render/src/character.ts。 要支持其他命名约定（例如 VRM 人形骨骼），需要修改其中的 BONE_MAP 表和 plainName() 前缀剥离逻辑。

---

许可

Posecode 采用开源许可，标准与产品之间有明确的界限：

层级	组件	许可证
开放标准	规范、示例、解析器、分享编解码器、语言服务、LSP、VS Code 扩展	Apache-2.0
产品层	渲染器、Web 嵌入组件、MCP 服务、评估工具、托管版 Playground	AGPL-3.0-only

需要在闭源产品中使用 AGPL 组件的组织，可通过 [email protected] 联系我们，洽谈单独的商业协议。

此前授予的许可保持不变。MIT 版本仍采用 MIT 许可证，0.2.2 版本的 npm 包仍采用 Apache-2.0 许可证。请参阅许可说明、商业许可和商标政策。

---

反馈与支持

欢迎提供反馈和贡献。

• 邮箱：[email protected]
• 问题：GitHub Issues

---

动画工具、大模型和 Web 产品需要可供检查的动作。
Posecode 让动作成为可读的源代码。