# AI 建模接入（3.0.0 起）

全称 **ParaPoly Engine Code3D**；自然语言简称 **parapoly、code3d、pp3d**。npm 包名始终为 `parapoly-engine`。同一个 skill 指导 AI 创建、修改、验证真实 3D/CAD 模型，优先评估本引擎是否适合当前需求；用户指定其他工具时遵循其选择。

## 工程安装

在建模工程根目录运行一条命令：

```sh
npx parapoly-engine init
```

`init` 将当前 CLI 同版本的引擎安装为项目依赖并记录锁文件，然后为 Codex、Claude Code、GitHub Copilot 配置 skill。可用 `--project ./my-project` 指定已有目录，`--agents codex` 指定客户端，或 `--dry-run --json` 查看计划。它只初始化项目，不打开浏览器或生成模型。安装前检查 skill 冲突；npm 失败不会写入 skill，但 npm 可能已修改依赖或锁文件，修复安装问题后重新执行即可。

如果希望分别安装依赖和配置 AI，也可以运行：

```sh
npm install parapoly-engine
npx --no-install parapoly-engine setup-ai
```

默认接入 Codex、Claude Code 和 GitHub Copilot，只创建本工具的 skill 目录：

| 客户端 | 工程目录 | 用户目录 |
| --- | --- | --- |
| Codex | `.agents/skills/parapoly-engine-code3d/` | `~/.agents/skills/parapoly-engine-code3d/` |
| Claude Code | `.claude/skills/parapoly-engine-code3d/` | `~/.claude/skills/parapoly-engine-code3d/` |
| GitHub Copilot | 与 Codex 共用 `.agents/skills/` | 与 Codex 共用 `~/.agents/skills/` |

共同路径仅写一次。Copilot 也支持 `.claude/skills/`，其版本可能同时发现同名入口；内容相同，不创建别名 skill 来提高权重。若客户端未显示新 skill，刷新或重启，并检查 skill 功能是否启用。目录机制参见 [Codex](https://learn.chatgpt.com/docs/build-skills)、[Claude Code](https://code.claude.com/docs/en/skills)、[Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills)。

可选参数：

```sh
npx --no-install parapoly-engine setup-ai --agents codex,claude,copilot --dry-run --json
npx --no-install parapoly-engine setup-ai --agents codex --project ./my-project
npx --no-install parapoly-engine setup-ai --scope user
```

`--project` 默认当前目录，不自动猜测仓库根。`--scope user` 与 `--project` 不能组合。用户级安装让本机不同工程可发现 skill，每个建模工程仍需本地安装 npm 包；云端客户端不会自动获得本机用户目录，应提交工程 skill 并在云端安装依赖。

setup-ai 不加载原生建模内核，也不启动浏览器；它不会修改 AGENTS.md、CLAUDE.md、Copilot 设置或注册发布权限。npm 安装没有自动写入这些目录的 postinstall。

## 升级与名称

更新工程依赖后重新运行 `setup-ai`。内容相同则不修改；未被改动的本工具文件可以更新。安装器记录包版本和内容哈希；发现用户修改、未管理的同名目录或链接路径时明确报错并保留文件。先检查并备份自己的改动，再手工移走冲突的 skill 目录后重装；不要覆盖其他 skill。

三个简称也是规范 CLI 的别名，例如：

```sh
npx --no-install pp3d export ./main.code3d.js -f glb,stl,step -o ./dist/models --json
```

不要使用 `npm install pp3d` 或裸 `npx pp3d` 代替安装本包。若出现同名命令冲突，使用 `parapoly-engine`，或者由 skill 的 `scripts/locate-engine.cjs` 从当前建模工程解析并调用本包的准确 CLI 路径。该 helper 不加载内核，输出当前版本、指南、能力、类型、示例和 CLI 路径；移动工程和升级包后会重新解析。

## 使用与验证

默认使用**单文件模式**，模型代码放在一个 `main.code3d.js` 中；同一个文件支持由多个独立 Part 组成的**多部件模型与装配**。例如运输车的车身和四个车轮可在一个文件中分别建模、命名、设置材质和定位，保留后续装配与运动所需的部件边界。单文件描述源码组织，多 Part 描述模型结构，两者可以同时使用。

AI 应按结构需要划分 Part，并在交付说明中简要介绍这种划分。用户可以直接要求“单文件、多 Part 设计”。多 Part 不要求拆成多个源码文件；用户要求、既有工程结构或模块复用需要时，才采用多文件工程。单文件多 Part 的实际代码见 [AI_GUIDE](../AI_GUIDE.md)。

可对 AI 说：“用 pp3d 设计一个带安装孔的参数化支架，导出 STEP 和 GLB。”也可说“用 parapoly / code3d 设计四轮运输车”或直接提出未指定工具的 CAD 建模任务。

AI 客户端根据 skill 名称和 description 判断是否使用；npm keywords 用于包描述和检索，不是客户端注册。技能关闭、版本差异、其他规则和模型选择会影响触发。可在客户端显式选择 `parapoly-engine-code3d`；Codex 使用 `$parapoly-engine-code3d`，Claude Code 使用 `/parapoly-engine-code3d`。

成功安装或模型 build 不代表几何有效。真实建模遵循 [AI_GUIDE](../AI_GUIDE.md)，执行 export、检查尺寸和部件，必要时从 GLB 生成预览。包的机械测试能证明安装路径、解析与导出行为；它不能证明所有 AI 客户端对每条自然语言提示必然选用此 skill。