step-parts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CAD Parts

CAD零件

Overview

概述

Use the hosted step.parts machine endpoints instead of scraping HTML or relying on local repository files. Treat

https://api.step.parts

as the canonical API origin and

https://www.step.parts

as the site/static-asset origin unless the user provides a different hosted mirror. If the domain does not resolve or the API is unavailable, report that the hosted service is not reachable yet instead of falling back to repo-specific assumptions.

使用托管的step.parts机器端点，而非抓取HTML或依赖本地仓库文件。除非用户提供其他托管镜像，否则将

https://api.step.parts

视为标准API源，将

https://www.step.parts

视为站点/静态资源源。如果域名无法解析或API不可用，请报告托管服务暂无法访问，而非依赖仓库特定假设。

Quick Workflow

快速工作流

Interpret the requested part into search terms and optional facets:
- ```
q
```
  for fuzzy tokens, standards, aliases, dimensions, source/product URLs, and attribute names/values.
- ```
category
```
  ,
```
family
```
  ,
```
standard
```
  , or
```
tag
```
  when the user gives an exact facet.
Search
```
/v1/parts
```
and inspect
```
items
```
,
```
total
```
, and
```
facets
```
.
If results are ambiguous, present the best few options with
```
id
```
,
```
name
```
,
```
standard
```
, and key attributes before choosing. If one result clearly matches, return the selected record details without downloading unless the user asked for a local STEP file.
When the user asks to download or save a STEP file, download its
```
stepUrl
```
, then verify the file with the record's
```
sha256
```
when present.
When a STEP file is downloaded as a local CAD asset, hand its explicit path to
```
$render
```
when available;
```
$render
```
checks/reuses a live viewer and returns a link.
If the download path is outside the active CAD workspace/root, such as the default
```
/tmp/step-parts
```
, either choose a workspace output directory or tell
```
$render
```
to use the download directory as its workspace/root so the file is inside the viewer scan root.
For visual feedback, prefer
```
$render
```
snapshots over opening the viewer manually or using Playwright. Use still snapshots only; standard-part lookup should not generate GIFs.
Return the local path when downloaded, the render link when available, plus the selected part id and page/API URLs so the user can trace provenance.

将请求的零件转换为搜索词和可选筛选条件：
- ```
q
```
  用于模糊标记、标准、别名、尺寸、源/产品URL以及属性名/值。
- 当用户给出明确筛选条件时，使用
```
category
```
  、
```
family
```
  、
```
standard
```
  或
```
tag
```
  。
搜索
```
/v1/parts
```
并检查
```
items
```
、
```
total
```
和
```
facets
```
。
如果结果存在歧义，先展示几个最佳选项的
```
id
```
、
```
name
```
、
```
standard
```
和关键属性再做选择。如果有一个结果明显匹配，直接返回所选记录详情，除非用户要求下载本地STEP文件，否则无需下载。
当用户要求下载或保存STEP文件时，下载其
```
stepUrl
```
，若存在记录的
```
sha256
```
则验证文件。
当STEP文件作为本地CAD资产下载后，若
```
$render
```
可用，将其明确路径交给
```
$render
```
；
```
$render
```
会检查/复用实时查看器并返回链接。
如果下载路径在当前CAD工作区/根目录之外（如默认的
```
/tmp/step-parts
```
），要么选择工作区输出目录，要么告知
```
$render
```
将下载目录作为其工作区/根目录，确保文件在查看器扫描根目录内。
如需视觉反馈，优先使用
```
$render
```
快照，而非手动打开查看器或使用Playwright。仅使用静态快照；标准零件查找不应生成GIF。
返回下载后的本地路径（若已下载）、可用的渲染链接，以及所选零件的id和页面/API URL，方便用户追溯来源。

Bundled Downloader

捆绑下载器

Use

scripts/download_step_part.py

for deterministic search, download, and checksum verification:

bash

python skills/step-parts/scripts/download_step_part.py "M3 socket head 12" --download --out-dir /tmp/step-parts
python skills/step-parts/scripts/download_step_part.py --id iso4762_socket_head_cap_screw_m3x12 --download --out-dir /tmp/step-parts
python skills/step-parts/scripts/download_step_part.py "bearing 608zz" --limit 5

Useful options:

```
--origin
```
: override
```
https://api.step.parts
```
only when the user provides another hosted API origin.
```
--tag
```
,
```
--category
```
,
```
--family
```
,
```
--standard
```
: repeatable facet filters.
```
--out-dir
```
: directory for downloaded STEP files. Defaults to
```
/tmp/step-parts
```
.
```
--all
```
: with
```
--download
```
, download every result on the returned page as individual STEP downloads.
```
--overwrite
```
: replace an existing output file.

The script prints JSON to stdout. For searches, it prints matched records. For downloads, it prints saved file paths, checksums, and source URLs.

使用

scripts/download_step_part.py

进行确定性搜索、下载和校验和验证：

bash

python skills/step-parts/scripts/download_step_part.py "M3 socket head 12" --download --out-dir /tmp/step-parts
python skills/step-parts/scripts/download_step_part.py --id iso4762_socket_head_cap_screw_m3x12 --download --out-dir /tmp/step-parts
python skills/step-parts/scripts/download_step_part.py "bearing 608zz" --limit 5

实用选项：

```
--origin
```
：仅当用户提供其他托管API源时，覆盖
```
https://api.step.parts
```
。
```
--tag
```
、
```
--category
```
、
```
--family
```
、
```
--standard
```
：可重复使用的筛选条件。
```
--out-dir
```
：下载STEP文件的目录。默认值为
```
/tmp/step-parts
```
。
```
--all
```
：配合
```
--download
```
使用时，下载返回页面中的所有结果作为独立STEP文件。
```
--overwrite
```
：替换现有输出文件。

该脚本会向标准输出打印JSON。对于搜索操作，打印匹配记录；对于下载操作，打印保存的文件路径、校验和以及源URL。

API Reference

API参考

Read

references/step-parts-api.md

when you need endpoint details, field meanings, or query semantics. Prefer:

```
/v1/parts
```
for filtered search with absolute asset URLs.
```
/v1/parts/{id}
```
for one enriched record.
Returned
```
stepUrl
```
for STEP downloads.
```
/v1/catalog/parts.index.json
```
for a compact discovery index.
```
/v1/catalog/schema
```
for field and family attribute meanings.
```
/v1/openapi.json
```
when generating a client or tool.

当需要端点详情、字段含义或查询语义时，请阅读

references/step-parts-api.md

。优先使用：

```
/v1/parts
```
：用于带绝对资产URL的筛选搜索。
```
/v1/parts/{id}
```
：用于获取单个增强记录。
返回的
```
stepUrl
```
：用于STEP文件下载。
```
/v1/catalog/parts.index.json
```
：用于紧凑的发现索引。
```
/v1/catalog/schema
```
：用于字段和系列属性含义。
```
/v1/openapi.json
```
：用于生成客户端或工具时。

Search Guidance

搜索指南

Query tokens are ANDed by the API, so start specific but not overconstrained. For example, use
```
M3 SHCS 12
```
before adding exact family and standard filters.
Values within one facet are ORed together, and selected
```
tag
```
,
```
category
```
,
```
family
```
, and
```
standard
```
fields are ANDed together. Use exact facets to narrow within known categories, then rank manually by name and attributes.
Standards can be queried as
```
ISO 4762
```
,
```
ISO4762
```
, or the exact
```
standard.designation
```
.
The
```
attributes
```
object contains family-specific facts such as
```
thread
```
,
```
lengthMm
```
,
```
bore1Mm
```
,
```
material
```
,
```
profileSeries
```
,
```
slotSizeMm
```
, and dimensions in millimeters.
Part, GLB, and PNG URL patterns are predictable on
```
https://www.step.parts
```
; STEP URLs are environment-aware and may resolve to GitHub LFS media in production. Use catalog/API
```
stepUrl
```
for downloads.

API会对查询标记进行逻辑与运算，因此开始时应具体但不过度限制。例如，先使用
```
M3 SHCS 12
```
，再添加精确的系列和标准筛选条件。
同一筛选条件内的值为逻辑或运算，所选的
```
tag
```
、
```
category
```
、
```
family
```
和
```
standard
```
字段为逻辑与运算。使用精确筛选条件缩小已知分类范围，然后根据名称和属性手动排序。
标准可通过
```
ISO 4762
```
、
```
ISO4762
```
或精确的
```
standard.designation
```
进行查询。
```
attributes
```
对象包含系列特定信息，例如
```
thread
```
、
```
lengthMm
```
、
```
bore1Mm
```
、
```
material
```
、
```
profileSeries
```
、
```
slotSizeMm
```
以及毫米单位的尺寸。
零件、GLB和PNG的URL模式在
```
https://www.step.parts
```
上是可预测的；STEP URL会根据环境调整，在生产环境中可能指向GitHub LFS媒体。下载时请使用目录/API提供的
```
stepUrl
```
。