Items 工程能力

Items 是什么？

Items 提供可落地的工程模板、配置或工具函数，例如网络请求封装、状态管理脚手架、Biome 配置等。通过下载对应的 JSON 文件即可在项目中生成标准化的代码与配置。

基础流程

1. 在文档站点找到目标能力，例如 make-api-request。
2. 点击下载按钮或复制 RegistryDownload 链接。
3. 根据生成文件内的 target 路径，将代码整合进项目结构。
4. 安装 index.json 中声明的 npm 依赖。

示例：make-api-request

1. 打开文档 make-api-request 查看能力说明。
2. 下载能力：

npx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/make-api-request.json

yarn dlx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/make-api-request.json

pnpx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/make-api-request.json

bunx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/make-api-request.json

3. 生成的文件会包含：

• services/base.ts：核心请求封装
• services/example/index.template.ts：接口模板
• services/example/index.schema.ts：Zod 校验
• services/example/index.ts：示例 API 函数

4. 安装依赖：

bun add zod

5. 在实际业务中使用：

import { makeApiRequest } from "@/services/base"
import { ProductApi } from "@/services/example/index.template"

export async function fetchProducts() {
  const template = ProductApi.getProducts
  return makeApiRequest(template, {
    query: { page: 1, pageSize: 10 }
  })
}

示例：Biome 配置

1. 访问 /docs/ssp/(item)/biome。
2. 下载配置文件：

npx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/biome-rules.json

yarn dlx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/biome-rules.json

pnpx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/biome-rules.json

bunx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/biome-rules.json

3. 将文件放在项目根目录，命名为 biome.json 并按需调整。
4. 在 package.json 中添加脚本：

{
  "scripts": {
    "lint": "biome check --write",
    "format": "biome format --write"
  }
}

验证与更新

• Items 的文件路径和目标路径记录在 index.json 内，导入后请确认路径符合项目结构。
• 可使用 bun run registry:sync 与 bun run registry:build 验证所有能力是否一致。
• 若进行本地修改，请保留注释和类型，便于后续与 Registry 同步。

下一步

• 结合 Hook 与 Items 建立完整的数据流，如 make-api-request + use-cancelable-swr。
• 若构建了新的工程模板或工具，可参考 贡献指南 提交回 Registry。