aps-docs-portal

此技能提供一种分步方法，指导你通过浏览文档门户来回答 APS 相关问题。

行为

1. 如果用户的第一个问题含糊不清或范围过广，请先提出一个简短的澄清问题，了解其意图，再开始长篇回答。
2. 始终在回答中提供参考链接。
3. 始终尝试直接回答 APS 相关问题。
4. 根据访问者的需求调整回答深度：Business 提供摘要和 ROI，Builder 提供分步指导，Developer 提供 REST 架构和身份验证流程。如果不确定，请先询问。

基本规则

• 切勿获取 aps.autodesk.com/en/docs/...（无论使用 WebFetch、curl 还是其他方式）。该门户是一个 JavaScript 单页应用（SPA）：其下的每个 URL——无论有效与否——都会返回相同的约 10 KB HTML 外壳。它不包含文档内容，甚至无法判断某个 URL 是否存在。
• 所有内容只存放在两个静态位置：目录 JSON（developer.doc.config.autodesk.com）和页面 HTML（developer.doc.autodesk.com）。只能使用这两者。
• 切勿向用户展示这些 CDN URL，也不要根据 CDN 路径手动拼接门户链接。所有门户链接都来自目录索引的第 1 列（步骤 3）。
• 如果问题仅涉及术语，只根据术语表回答——无需获取其他内容。

---

方法：如何回答 APS 问题

步骤 1 — 阅读术语表，理解行话

如果问题提到了此处未列出的缩写，请在稍后获取的文档中查找其定义。

APS 术语表

• APS：Autodesk Platform Services（以前称为 Forge）
• ACC：Autodesk Construction Cloud。近期文档页面也会使用 Forma 指代 ACC 服务（例如“Forma Issues”“Forma Data Management”）；单独的 Forma Site Design API 为 forma_v1。
• BIM 360：旧版施工管理平台（ACC 的前身）
• MD：Model Derivative API — 将设计文件转换为可查看的格式（SVF/SVF2）
• DM：Data Management API — 管理文件、文件夹和存储（OSS、BIM 360、ACC 集线器）
• URN：在 APS API 中通用的 Base64 编码资源标识符
• SVF/SVF2：Scalable Viewing Format — 由 Model Derivative 生成、仅由 APS Viewer SDK 使用的优化型 3D Web 查看格式；概念类似于采用 openCTM 压缩的 glTF 格式
• OSS：Object Storage Service — APS 云存储服务，用于上传设计文件
• Webhook：由 APS 事件（例如模型转换完成、文件版本新增）触发的服务器到服务器回调
• 2LO/3LO：双腿 / 三腿 OAuth 身份验证流程
• Hub：Data Management 中的顶级容器（对应 ACC 或 BIM 360 账户）
• Manifest：Model Derivative 返回的转换状态和输出元数据
• ACAD：AutoCAD — Autodesk 旗舰级 2D/3D CAD 制图软件（生成 .dwg 文件）
• Civil：Autodesk Civil 3D — 面向基础设施项目的土木工程设计软件
• Revit：Autodesk Revit — 用于建筑、结构和 MEP 设计的 BIM 软件（生成 .rvt 文件）
• Build：Autodesk Build — ACC 中的施工管理模块（现场管理、成本等）
• IFC：Industry Foundation Classes — 用于工具之间交换 BIM 数据的开放标准文件格式
• RFI：信息请求 — 施工期间提交并在 ACC/BIM 360 中跟踪的正式问题
• SSA：Secure Service Accounts — 一种服务器到服务器身份，通过私钥对 JWT 断言签名并将其交换为三腿（用户上下文）访问令牌，无需交互式登录
• AEC：Architecture, Engineering, and Construction — APS 主要服务的行业领域
• AECDM：AEC Data Model API — 用于跨 ACC 访问设计和施工数据的统一 API
• DX：Data Exchange — 用于以中立格式在应用程序之间交换设计数据的 API
• Auth：身份验证 — APS OAuth 流程，包括 2LO、3LO、PKCE、PAT（个人访问令牌）和 SSA

转换成本（Model Derivative API）： 复杂任务包括 Revit（.rvt）、IFC 和 Navisworks（.nwd/.nwc）。其他所有任务均为简单任务。

---

步骤 2 — 确定相关 API

使用下方的来源表选择要打开的目录（TOC）。例如：

• “文件变更” → 数据管理事件，记录在 Webhooks API（webhooks_v1）中
• “模型转换” → Model Derivative API（model-derivative_v2）
• “数字孪生” → Tandem（tandem_v1）
• “事件/回调” → Webhooks API（webhooks_v1）——所有事件类别（dm.*、issue.*、extraction.*、成本、评审等）都位于其 reference/events/ 部分

来源 ID	API 标题
acc_v1	Autodesk Construction Cloud API
aecdatamodel_v1	AEC Data Model API
applications_v1	Application Management API
bim360_v1	BIM 360 API
buildingconnected_v2	BuildingConnected & TradeTapp API
data_v2	Data Management API
dataviz_v1	Data Visualization
design-automation_v3	Automation API
dx-sdk-beta_v7.2.0	Data Exchange .NET SDK v7.2.0
fdxgraph_v1	Data Exchange GraphQL
flow_graph_engine_v1	Flow Graph Engine
forma_v1	Forma Site Design API（Beta）
informed-design_v1	Informed Design API（Beta）
insights_v1	Business Success Plan Reporting API
mfgdataapi_v3	Manufacturing Data Model API
model-derivative_v2	Model Derivative API
oauth_v2	Authentication API
parameters_v1	Parameters API
profile_v2	User Profile API
ssa_v1	Secure Service Account API
sustainability_v3	Sustainability Data API
tandem_v1	Tandem Data
tokenflex_v1	Token Flex Usage Data API
vaultdataapi_v2	Vault Data API
viewer_v7	Viewer
webhooks_v1	Webhooks API

门户 URL ↔ 来源 ID： 门户 URL https://aps.autodesk.com/en/docs/{api}/{version}/… 始终对应来源 ID {api}_{version}（例如，/en/docs/acc/v1/… → acc_v1）。

---

步骤 3 — 下载并建立目录索引（每个来源仅一次）

将需要的每个目录（TOC）下载到本地文件一次，然后查询该文件。目录文件很大（ACC ≈ 140 KB，Data Exchange SDK ≈ 650 KB）——切勿直接打印原始内容，也不要重复下载。

curl -sL --create-dirs -o /tmp/aps-docs/acc_v1.json "https://developer.doc.config.autodesk.com/bPlouYTd/acc_v1.json"

将其转换为扁平索引——每页一行，包含门户 URL、标题和 CDN 来源路径，以制表符分隔：

jq -r '.url_path as $api | .doc_version as $v | def w($p): ($p + [.url_path // ""]) as $q | (if .source then "https://aps.autodesk.com/en/docs/\($api)/\($v)/\($q | map(select(. != "")) | join("/"))/\t\(.display_name)\t\(.source)" else empty end), (.children[]? | w($q)); .children[] | w([])' /tmp/aps-docs/acc_v1.json | grep -i 'issues'

使用 grep -i 按主题词筛选；若要快速查看结构，可使用 jq -r '.children[] | .url_path' FILE 列出顶级章节。

输出示例：

https://aps.autodesk.com/en/docs/acc/v1/reference/http/issues-issues-GET/	GET issues	acs-acs-api-documentation-main-52/acc/v1/reference/http/issues/issues-GET.html

• 第 1 列是该页面唯一有效的门户链接。 门户根据目录中的 url_path 值解析页面，而不是 CDN 文件路径；二者通常并不相同：

  CDN 来源路径（仓库标识之后）	正确的门户 URL
  acc/v1/reference/http/issues/issues-GET.html	…/en/docs/acc/v1/reference/http/issues-issues-GET/
  model-derivative/v2/overview.html	…/en/docs/model-derivative/v2/developers_guide/overview/
  dx-sdk-beta/v1/v720/developers_guide/overview.html	…/en/docs/dx-sdk-beta/v7.2.0/developers_guide/overview/

• 第 3 列是步骤 4 所需的页面 HTML 路径。

• 给定门户 URL（来自用户或其他来源）：将其映射到来源 ID（步骤 2），为该目录建立索引，然后使用 grep -F 搜索完整 URL（包括末尾的 /），以获取其 CDN 来源路径。给定 CDN URL：使用 grep -F 搜索第 3 列中 bPlouYTd/ 之后的路径；如果仓库标识已过时，则改为搜索路径末尾部分。

• 没有页面的章节节点不含 source，因此不会出现在索引中；请链接到其第一个子页面。

第 4 步 — 每个页面只获取一次，在本地提取

下载一次页面 HTML，然后在本地文件上运行所有提取操作：

curl -sL -o /tmp/aps-docs/page.html "https://developer.doc.autodesk.com/bPlouYTd/{source}"

# 1. Structure first — tells you whether it's a reference page, guide, tutorial, or event list
htmlq -f /tmp/aps-docs/page.html -r 'script, style' --text 'h1, h2, h3, h4'

# 2. Prose, lists, and code samples
htmlq -f /tmp/aps-docs/page.html -r 'script, style, noscript' --text 'p, li, pre'

# 3. Tables (parameters, response fields, status codes) — one row per line
htmlq -f /tmp/aps-docs/page.html -r 'script, style' --text 'tr' | sed 's/^[[:space:]]*//' | grep -v '^$'

注意：

• REST 参考页面以一个表格开头，其中包含方法和 URI、身份验证上下文（例如“需要用户上下文”）以及必需的 OAuth 作用域；随后是标头、URI/查询参数、请求正文和响应正文表格。必填字段会用 * 标记。与其阅读整个页面，不如在表格行中搜索所需的参数或字段（例如 grep -A2 '^limit'）。
• 如果需要同时处理多个页面，请为每个页面使用不同的文件名。
• 选择 tr，而不是 td/table：否则嵌套单元格会导致相同文本重复多次。

---

第 5 步 — 整理成连贯的回答

1. 定义术语（来自术语表或你在文档中找到的内容）
2. 说明相关 API 和端点（来自目录和获取的页面）
3. 列出具体事件、参数或功能（来自参考页面——准确引用值）
4. 提供参考链接——仅复制索引第 1 列中的门户 URL
5. 在适用时提供实用示例（curl 命令、代码片段等）

---

注意事项

• 不会预先安装 htmlq——在 macOS 上使用 brew install htmlq 安装，或使用 cargo install htmlq。如果无法使用，请改用 python3 -c 和 html.parser。
• 如果源 ID 有误，TOC JSON URL 会失效——它区分大小写且有版本号（data_v2，而不是 data）。请使用第 2 步中的表格。
• 旧的 CDN 仓库 slug 仍能解析，但提供的是过时内容——务必从当前 TOC 获取 source 路径，不要重复使用记忆中的路径或旧答案中的路径。
• Webhook 事件仅记录在 webhooks_v1 中，路径为 reference/events/{family}/（例如 data_management_events/dm.version.added/）。Data Management 事件使用 dm. 前缀；ACC Issues 事件带有版本号（issue.created-1.0）。

---

示例：“文件更改时有哪些 Webhook 可用？”

第 1 步 — 术语表。 Webhook 是服务器到服务器的回调。Data Management 管理 OSS、BIM 360 Docs 和 ACC Docs 中的文件。

第 2 步 — 确定 API。 文件事件属于 Data Management 事件，记录在 Webhooks API（webhooks_v1）中。

第 3 步 — 索引 TOC。

curl -sL --create-dirs -o /tmp/aps-docs/webhooks_v1.json "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json"
jq -r '<index filter from Step 3>' /tmp/aps-docs/webhooks_v1.json | grep 'data_management_events'

这会为每个事件生成一行——dm.version.added、dm.version.modified、dm.version.deleted、dm.version.moved、dm.version.copied、dm.lineage.reserved、dm.lineage.unreserved、dm.lineage.updated、dm.folder.added、dm.folder.modified、dm.folder.deleted、dm.folder.purged、dm.folder.moved、dm.folder.copied、dm.operation.started、dm.operation.completed 等——每行都包含其门户 URL 和源路径。

第 4 步 — 获取所需页面（例如第 3 列中的 dm.version.added 页面），提取标题，然后提取载荷表格。

第 5 步 — 整理。

• dm.version.added — “向文件夹添加项目的新版本时”（作用域：文件夹）
• dm.version.modified / dm.version.deleted / dm.version.moved / dm.version.copied — 版本更改
• dm.folder.* — 文件夹更改

链接（从第 1 列复制）：

• Data Management 事件
• dm.version.added
• Webhooks API 概览