b2c-docs

B2C 文档技能

对于任何尚未由已加载技能或当前项目上下文解答的 B2C Commerce 开发者或管理员问题，请使用此技能。 文档集涵盖 Script API 参考、Commerce API（SCAPI/OCAPI）集成模式、店面框架指南（SFRA、PWA Kit、Storefront Next）、Business Manager 管理和商品运营（Salesforce Help）、作业步骤参数、身份验证流程以及工具配置。

使用 b2c CLI 搜索和阅读涵盖多个文档集的 B2C Commerce 文档：Script API 参考（dw.* 类/模块）、Developer Center 指南（涵盖 Commerce API、PWA Kit、SFRA 等的概念性内容和操作指南）、Salesforce Help（来自 help.salesforce.com 的 Business Manager 管理和商品运营内容）、工具文档（本项目自带的指南）、标准（系统）作业步骤目录以及 XSD 架构。

提示： 如果未全局安装 b2c，请改用 npx @salesforce/b2c-cli（例如，npx @salesforce/b2c-cli docs search ProductMgr）。

MCP 一致性： 如果已连接 b2c-dx-mcp 服务，其文档工具 — docs_search、docs_read、docs_list、docs_schema_search、docs_schema_read 和 docs_schema_list — 涵盖相同的文档集，并具有本文所述的相同搜索、工作区感知和主题范围限定行为。

主要功能

• 多文档集搜索 — 在统一索引中搜索 Script API、Developer Center 指南、OCAPI 参考、Salesforce Help（管理 + 商品运营）、内部工具文档（指南、CLI 参考、MCP 和 VS Code 扩展）、作业步骤和架构
• 工作区感知搜索 — 自动检测项目类型（cartridge、SFRA、PWA Kit、Storefront Next），并提升相关文档的排名，同时降低竞争店面框架文档的排名
• 类别筛选 — 使用 --category 将结果限定到特定文档集（例如，commerce-api、pwa-kit-managed-runtime、sfra、script-api、help-admin、help-merchant、help-kb）
• 分类元数据 — 搜索结果包含 category、summary、keywords 和 url，帮助识别合适的匹配项，无需阅读完整内容
• 在线内容与本地缓存 — 阅读时在线获取 Script API、Developer Center 指南和 Salesforce Help，并在本地缓存（内存 + 磁盘，TTL 为 7 天），以便重复阅读时无需联网；离线时会优雅回退，显示摘要、标题和两个 URL
• 内容感知排序 — 采用 BM25 风格搜索，对标题、章节标题、摘要和关键词建立索引，以更好地召回概念性问题的相关内容
• 双 URL — 每个公开可用的文档条目都包含 url（面向用户的 .html 页面）和 sourceUrl（原始 .md 源文件）。Script API 条目链接到 developer.salesforce.com；Salesforce Help 条目链接到 help.salesforce.com 上的实时帮助文章，而内容则由原始 Markdown 镜像提供。内容通过 sourceUrl 获取，并支持离线回退
• 相关内容 — Developer Center 指南将其直接 TOC 父级和子级作为 relatedEntries 提供；Salesforce Help 落地页条目使用同一字段列出链接的子文章，并在其原始 Markdown 中包含匹配的 相关内容 部分
• 主题允许列表 — 通过 --topics 标志、SFCC_DOCS_TOPICS 环境变量或 docsCategories 配置字段（dw.json 中的 docs-categories、SFCC_DOCS_CATEGORIES、package.json）将整个文档集限定到所选类别。MCP 服务提供 --docs-topics 启动标志
• 兼顾负载的默认设置 — MCP 工具限制结果数量（5）并默认返回精简字段；CLI 默认返回 20 条结果；详细模式会添加扩展字段

示例

搜索文档

# Search across all documentation
b2c docs search "passwordless login"

# Filter by category for targeted results
b2c docs search "passwordless login" --category commerce-api

# Search Developer Center guides
b2c docs search "storefront components" --category sfra
b2c docs search "deploy bundle" --category pwa-kit-managed-runtime

# Search Script API reference
b2c docs search ProductMgr --category script-api
b2c docs search "catalog product"

# Find a standard job step by type ID
b2c docs search ImportCatalog

# Search Salesforce Help — administration (import/export, jobs, security, Account Manager)
b2c docs search "site import export" --category help-admin

# Search Salesforce Help — merchandising (catalogs, promotions, search, pricing)
b2c docs search "price book assignment" --category help-merchant

# Search Salesforce Help Knowledge Articles — troubleshooting, known issues, how-to answers
b2c docs search "code upload certificate hyperforce" --category help-kb

# Search tooling documentation
b2c docs search "authentication setup" --category tooling
b2c docs search "import set" --category tooling

# Limit results (CLI default is 20, MCP default is 5)
b2c docs search authentication --limit 5

# Read the next page of ranked results
b2c docs search authentication --limit 5 --offset 5

# Show extended fields (url, sourceUrl, summary, keywords)
b2c docs search authentication --columns id,title,category,url,summary
# or use -x for extended output
b2c docs search authentication -x

# Workspace awareness is ON by default — search auto-detects the project type
b2c docs search "components"

# Opt out of workspace awareness
b2c docs search "components" --workspace all

# Force auto-detection explicitly
b2c docs search "hooks" --workspace auto

# Search with specific workspace types (boosts relevant docs)
b2c docs search "page designer" --workspace sfra

# Search with multiple workspace types (union of their boost categories)
b2c docs search "checkout" --workspace cartridges,pwa-kit-v3

# List all available documentation
b2c docs search --list

# List entries in a specific category
b2c docs search --list --category commerce-api

# List docs relevant to a specific workspace (list does not auto-detect)
b2c docs search --list --workspace cartridges

# Bound the entire corpus to specific topics (allowlist; env: SFCC_DOCS_TOPICS)
b2c docs search "login" --topics sfnext,commerce-api

--topics 与 --category 的区别：--category 用于筛选单次查询；--topics（CLI 标志或 SFCC_DOCS_TOPICS 环境变量）是允许列表，用于限定_整个_可用语料库的范围；--category/--workspace 会在此范围内进一步缩小结果，而 docs read 不会解析范围以外的 ID。固定该选项，即可仅开放与项目相关的文档。MCP 服务有对应的 --docs-topics 启动标志和 SFCC_DOCS_TOPICS 环境变量。

工作区感知搜索

文档搜索会识别项目使用的工作区框架，并自动优先显示相关文档。这有助于展示适用于 SFRA、PWA Kit 或 Storefront Next 项目的指南，且默认启用。

工作原理：

• 自动检测（默认）：docs search 会根据工作区结构自动检测项目类型；传入 --workspace auto 可显式强制启用此功能
• **显式指定：**以逗号分隔指定一种或多种工作区类型：cartridges、sfra、pwa-kit-v3 或 storefront-next。多种类型会合并其加权类别
• **禁用感知：**使用 --workspace all 可在不优先考虑任何工作区的情况下搜索

类别加权映射：

• 始终相关（适用于任何工作区）：b2c-commerce、commerce-solutions、ocapi、tooling
• cartridges → script-api、job-step
• sfra → sfra
• pwa-kit-v3 → pwa-kit-managed-runtime、commerce-api
• storefront-next → sfnext、commerce-api

**降低竞争框架的权重：**检测到或指定工作区后，搜索引擎会降低（x0.3）不属于当前工作区的店面框架指南的权重。例如，如果工作区是 sfra，则 pwa-kit-managed-runtime 和 sfnext 类别的权重会降低；这会重新调整结果权重，但不会隐藏这些内容。

**SFRA 与 cartridges 的区别：**SFRA 项目会同时检测为 cartridges 和 sfra（SFRA 是更具体的类型——它包含 app_storefront_base cartridge）。非 SFRA 的 cartridge 项目（自定义 API cartridges，或同时包含 cartridges 的 PWA Kit / Storefront Next 仓库）只会检测为 cartridges，因此不会提高 sfra 文档的权重。

检测到或指定工作区后，相关文档的权重总会提高（排名更靠前），但不会隐藏任何类别。如需将结果严格限定在某个类别，请使用 --category 或 --topics。

**--list 的行为：**使用 --list 浏览目录时，不会启用工作区自动检测——除非显式传入 --workspace <type> 来缩小范围，否则列表会显示完整语料库。

示例：

# Auto-detect and boost relevant docs (default behavior)
b2c docs search "components"

# Search with specific workspace type
b2c docs search "checkout" --workspace sfra

# Search with multiple workspace types
b2c docs search "deploy" --workspace pwa-kit-v3,storefront-next

阅读文档

# Read Script API documentation
b2c docs read ProductMgr
b2c docs read dw.catalog.ProductMgr

# Read Developer Center guides by namespaced ID
b2c docs read sfnext/sfnext-get-started
b2c docs read commerce-api/slas-passwordless-login-registration
b2c docs read pwa-kit-managed-runtime/getting-started

# Read Salesforce Help articles by namespaced ID
b2c docs read help-admin/b2c_site_import_export
b2c docs read help-merchant/b2c_creating_price_books
b2c docs read help-kb/002772125

# Read tooling guides
b2c docs read guide-authentication
b2c docs read guide-configuration

# Output raw markdown (for piping)
b2c docs read ProductMgr --raw

# Output as JSON
b2c docs read ProductMgr --json

精确匹配与模糊匹配：docs read 会确定性地解析精确 ID（例如 dw.catalog.ProductMgr）。对于模糊查询（例如 productmgr），它会应用与 docs search 相同的工作区感知排名，因此模糊读取会解析为搜索排名第一的同一条结果。传入 --workspace all 可选择退出此功能。

**内容来源：**Script API、Developer Center 指南、Salesforce Help 和工具文档会从 .md 源（sourceUrl）在线获取并缓存到本地；离线时则会优雅地回退显示摘要、标题和两个 URL。只有标准作业步骤会随 CLI 打包。

如需获取面向用户的 .html 页面 URL（用于引用或在浏览器中打开）或原始 .md 源 URL，请使用 --json 输出，或在搜索结果中使用 --columns url,sourceUrl。

标准作业步骤目录

打包的语料库包含标准（系统）作业步骤类型 ID 目录——即添加到 Business Manager 作业流中的内置步骤（例如 ImportCatalog、ExportCatalog、ImportInventoryLists）。每个步骤的页面都会列出其用途和配置参数（必填项、默认值、允许的值）。

# Read the catalog overview (all standard step type IDs)
b2c docs read job-steps

# Read a specific step's purpose + configuration parameters
b2c docs read ImportCatalog

# Search for a step
b2c docs search "import price"
b2c docs search ExportInventoryLists --category job-step

有关标准步骤如何融入作业流——与自定义步骤串联、移交 IMPEX 文件，以及何时使用流内步骤而非 CLI 等效项——请参阅 b2c:b2c-custom-job-steps 和 b2c-cli:b2c-job 技能。

下载文档

从 B2C Commerce 实例下载最新的 Script API 文档。CLI 会从 dw.json、SFCC_* 环境变量和配置插件中自动发现目标服务器和凭据——只有在需要覆盖时才使用 --server。运行 b2c setup inspect，确认 CLI 获取到的信息；如需排查问题，请参阅 b2c-cli:b2c-config 技能。

# Download to a directory (uses configured instance)
b2c docs download ./my-docs

# Override server explicitly
b2c docs download ./docs --server sandbox.demandware.net

# Keep the original archive
b2c docs download ./docs --keep-archive

读取 XSD 架构

读取用于导入/导出数据格式的内置 XSD 架构文件：

# Read a schema by name
b2c docs schema catalog

# Fuzzy match schema name
b2c docs schema order

# List all available schemas
b2c docs schema --list

# Print the filesystem path to the schema file
b2c docs schema catalog --path

# Validate an XML file against a schema using xmllint
xmllint --schema "$(b2c docs schema catalog --path)" my-catalog.xml --noout

文档类别

类别	描述	示例 ID
script-api	服务器端 Script API 参考（dw.* 类/模块）	dw.catalog.ProductMgr, dw.order.Basket
commerce-api	Commerce API（SCAPI/OCAPI）概念指南和操作指南	commerce-api/slas-passwordless-login-registration
pwa-kit-managed-runtime	PWA Kit 和 Managed Runtime（MRT）指南	pwa-kit-managed-runtime/getting-started
sfra	Storefront Reference Architecture（SFRA）指南	sfra/controllers-and-routes
sfnext	Storefront Next 指南	sfnext/sfnext-get-started
b2c-commerce	B2C Commerce 平台通用指南	b2c-commerce/business-manager-overview
commerce-solutions	B2C Commerce 解决方案 — 机器人管理、缓存策略、限时抢购流量和行业解决方案	commerce-solutions/bot-management
ocapi	OCAPI 参考 — Open Commerce API 的用法、钩子、设置和最佳实践	ocapi/ocapisettings, ocapi/bestpractices
tooling	B2C CLI 参考、指南、MCP 文档、SDK 指南和 VS Code 扩展文档	guide-authentication, cli-jobs
job-step	标准（系统）作业步骤目录	ImportCatalog, ExportCatalog, job-steps
help-admin	Salesforce 帮助 — 管理/运维（导入/导出、作业、复制、安全、Account Manager、权限、日志、库存）	help-admin/b2c_site_import_export
help-merchant	Salesforce 帮助 — 商品管理（目录、产品、促销、搜索、内容、分析、SEO）	help-merchant/b2c_creating_price_books
help-kb	Salesforce 帮助知识文章 — 故障排除、已知问题和操作指南（按文章编号索引）	help-kb/002772125

URL： 除 job-step 外，所有类别都包含 url（面向用户的 .html 页面）和 sourceUrl（机器可读的 .md）。对于 help-admin/help-merchant/help-kb，url 是实时的 help.salesforce.com 文章，内容从 sourceUrl 读取。job-step 条目两者都没有（内容以内联形式打包）。

缓存： 在线语料（script-api、指南类别、help-admin/help-merchant/help-kb、tooling）的内容会在执行 docs read 时获取并缓存到本地。使用 b2c docs cache 检查缓存，使用 b2c docs cache --clear 清除缓存（强制重新获取）。

常用脚本 API 类

类	描述
dw.catalog.ProductMgr	商品管理和查询
dw.catalog.Product	商品数据和属性
dw.order.Basket	购物篮操作
dw.order.Order	订单处理
dw.customer.CustomerMgr	客户管理
dw.system.Site	站点配置
dw.web.URLUtils	URL 生成工具

常用架构

架构	描述
catalog	商品目录导入/导出
order	订单数据导入/导出
customer	客户数据导入/导出
inventory	库存数据导入/导出
pricebook	价格簿导入/导出
promotion	促销定义
coupon	优惠券代码导入/导出
jobs	作业步骤定义

查找 CLI 命令

b2c docs search 用于搜索文档。若要查找哪个 b2c 命令可以执行某项任务，请改为搜索 CLI 自身的命令：

b2c commands search "deploy cartridges"
b2c commands search "environment variables" --topic mrt --json

阅读 Agent 技能

CLI 捆绑了其 Agent 技能（类似本指南的工作流指南）。无需安装插件，即可阅读某个命令或主题对应的技能，或搜索这些技能：

b2c docs skill                          # list b2c-cli skills
b2c docs skill code deploy              # skill covering a command or topic
b2c docs skill --search "site import"   # search skills
b2c docs skill --all --search "hooks"   # include b2c, b2c-ops, storefront-next

更多命令

请参阅 b2c docs --help，查看所有可用命令和选项。