sdcmodeler

sdcmodeler

**面向 SDCStudio 的 Modeler 客户端。**搜索公共目录，估算、组装并发布 SDC4 数据模型，生成其软件包和应用。一个仅依赖 httpx 的 Python 客户端、一个命令行工具，以及 sdcmodeler mcp，可供任何 Agent 使用的 MCP 服务。

为什么

构建功能的 Agent 会在构建时决定数据模型。使用 sdcmodeler 时，数据默认以 SDC 建模：Agent 首先搜索目录，尽可能复用已发布的组件，只创建新组件，发布模型并获取软件包。由于模型由共享的已发布组件构成，因此具有互操作性；由于每条记录都通过已发布的架构验证，因此结果可验证。

这个名称遵循 Semantic Data Charter 其他服务的角色命名模式：sdcvalidator 负责验证，sdcgovernance 负责治理，sdcreader 负责读取，sdcmodeler 负责建模。它也对应 SDCStudio 对每位用户的称呼：Modeler。

安装

pip install sdcmodeler

查询目录和估算无需账户。构建需要 SDCStudio API 密钥，可在 Settings、API Keys 中创建，并为其设置持有者所需的作用域和支出限额：

export SDCSTUDIO_API_KEY=sdcs_...

三层结构

客户端

from sdcmodeler import SDCStudioClient

c = SDCStudioClient()                       # key from $SDCSTUDIO_API_KEY, URL from $SDCSTUDIO_URL
hits = c.search_components("blood pressure", type="xdquantity")
tree = {
    "label": "Vitals",
    "components": [
        {"ct_id": hits["results"][0]["ct_id"]},            # reuse: free
        {"label": "Pulse", "data_type": "XdCount"},        # mint: 100 credits
    ],
    "clusters": [],
}
estimate = c.estimate(tree, "Vitals")       # the server's estimate: reuse, mint, problems, total_credits, wallet, key, estimate_id
result = c.assemble("Vitals", tree, estimate_id=estimate["estimate_id"])   # 500 credits plus the mints

所有叶节点均已存在：服务端会在一次调用中组装、发布并生成软件包（result["mode"] == "reuse"；published 和 generated 会标明结果）。部分叶节点是新建的：流水线会运行，并通过 c.job_status(...) 或 c.wait_for_job(...) 轮询 result["job_ct_id"]，直至状态为 completed；此时作业已按要求发布并生成，结果中包含模型链接。publish=False 会保留草稿，供人员审核。如果自估算后树结构发生变化，服务端会拒绝构建。

402 错误会以 InsufficientCredits 返回，并附上以积分为单位的数值。密钥策略导致的 403 错误（缺少 spend 作用域或已超过限额）会以 KeyPolicyRefused 返回。客户端不会为钱包充值；充值需由人员在钱包页面完成。

命令行工具

sdcmodeler search "blood pressure" --type xdquantity
sdcmodeler models "patient"
sdcmodeler model <ct_id>
sdcmodeler artifact <ct_id> xsd --dir ./schemas
sdcmodeler estimate tree.json --title "Vitals"
sdcmodeler build tree.json --title "Vitals" --wait
sdcmodeler job <job_ct_id>
sdcmodeler package <ct_id> --dir ./packages
sdcmodeler app <ct_id> --profile lightweight --dir ./apps
sdcmodeler wallet

MCP 服务

sdcmodeler mcp

这是一个基于 JSON-RPC 2.0 的 stdio 服务，不使用 SDK，构建方式与 sdcvalidator 和 sdcgovernance 相同。客户端配置只需：

{"command": "uvx", "args": ["sdcmodeler", "mcp"], "env": {"SDCSTUDIO_API_KEY": "sdcs_..."}}

工具	功能	是否消耗积分
search_components	按标签、类型和项目搜索公共目录	否
list_models、get_model	列出已发布的模型及其工件路由	否
estimate_model	估算树结构将复用、创建的内容及费用；返回 estimate_id	否
build_model	组装、发布并生成（或使用 publish: false 创建草稿）；需要人员查看过的 estimate_id；若超出密钥限额则拒绝	是
job_status	按 ID 查询单个作业：状态、步骤、当前费用和模型链接	否
download_package	使用密钥下载模型的软件包 ZIP，包括私有项目中的模型；如果软件包不存在，会先免费生成一次（除非 generate 为 false）	否
generate_app	生成并下载应用；需要 confirm_charge；首次收费 1,500 积分，之后免费	是
wallet	以积分显示余额和密钥策略	否

**策略由服务端执行。**未展示估算结果时不会支出：build_model 使用 estimate_model 在当前进程中针对相同标题和树结构返回的 estimate_id。达到密钥限额即停止：如果估算费用超过密钥剩余可支出的额度，构建会在请求服务端前被拒绝。绝不付款：若返回 402，会提供钱包页面地址，并停止工具运行。没有任何工具会将 URL、密钥或支付方式作为参数；密钥是服务启动时所处环境的一部分。

软件包还是应用程序

get_model 用于命名各项产物：XSD 1.1 架构、实例模板、JSON、JSON-LD、SHACL、HTML、GraphQL。软件包是一份不附带运行时的契约；现有应用程序中的某项功能可以用任意语言基于它实现，并使用 sdcvalidator 在本地验证每条记录。如果这项功能是一个新服务，则生成的应用程序（轻量或企业配置）是基于同一软件包实现的 Django 应用。CordovaOS 就是这样构建的 10 个应用，共享数据且无需编写任何集成代码。

此处不包含的内容

验证（sdcvalidator 的服务）、治理（sdcgovernance 的服务）、收据验证（sdcreceipt 的服务）以及迁移现有数据（sdc-agents）都有各自注册的服务。sdcmodeler 会与它们组合使用，而不会重新实现它们。

发布

分两步：合并到 main，然后推送与 pyproject.toml 匹配的标签 v<version>。release.yml 会运行测试、构建，并通过受信任发布者发布到 PyPI 和 MCP 注册表。

许可证

Apache License 2.0。版权所有 Axius SDC, Inc。