> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/mattzh72/articraft) · [上游 README](https://github.com/mattzh72/articraft/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # Articraft [](LICENSE) [](https://www.python.org/) [](https://github.com/mattzh72/articraft/actions/workflows/ci.yml) **用于可扩展关节式 3D 资产生成的智能体（Agentic）系统。** [论文](https://arxiv.org/abs/2605.15187) | [项目主页](https://articraft3d.github.io/) | [数据集](https://github.com/mattzh72/articraft-data) Articraft 将关节式 3D 资产的创建转变为由 LLM 驱动的程序化、代码生成工作流。它现在是一个本地优先（local-first）的运行框架：本仓库包含生成/查看器逻辑，而公开数据集单独托管于 [`mattzh72/articraft-data`](https://github.com/mattzh72/articraft-data).  > **安全提示：** Articraft 通过将生成记录的 `model.py` 文件作为 Python 代码执行来编译和检查这些记录。仅运行来自可信来源的生成记录和模型脚本。 --- ## 快速入门 ### 1. 前置要求 - 推荐使用 Python 3.12（或 3.11）。*注意：目前不支持 3.13+。* - [`uv`](https://docs.astral.sh/uv/)，用于极快的 Python 包管理。 - [`just`](https://github.com/casey/just) 作为命令运行器。 - [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)（可选，但本地查看器前端需要）。 ### 2. 安装配置 在仓库根目录运行： ```bash just setup ``` 若从其他工作目录进行安装，请传入仓库根目录： ```bash just setup ./path/to/checkout ``` Articraft 将记录存储在 git 忽略的数据根目录中。默认为 `/data`。要浏览已发布的数据集，请克隆 [`mattzh72/articraft-data`](https://github.com/mattzh72/articraft-data) 并将 Articraft 指向它： ```bash git clone https://github.com/mattzh72/articraft-data.git ../articraft-data export ARTICRAFT_DATA_DIR="$(cd ../articraft-data && pwd)" uv run articraft status uv run articraft library check --require-records ``` 你也可以通过 `--data-dir` 显式指定任意数据文件夹。 ### 3. 添加 API 密钥 打开 `.env` 并设置一个或多个提供商密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEYS`、`ANTHROPIC_API_KEYS`、`DASHSCOPE_API_KEY`）。 > **没有 API 密钥？** 没关系。你可以改用 Claude Code、Codex 或 Cursor 等外部 AI 智能体。有关 Codex 配置（包括如何添加 Codex 插件），请参阅 [Codex 插件配置](docs/codex_plugin.md)。然后将智能体指向本仓库并提示： > > *"在 Articraft 中创建一个逼真的关节式 [object name]。请遵循 EXTERNAL_AGENT_DATA.md。"* ### 4. 创建资产 使用 `articraft generate` 直接从提示词生成你的第一个模型： ```bash uv run articraft generate "Create a realistic articulated desk lamp with a weighted base, two hinged arms, and an adjustable lamp head." ``` 若不指定覆盖项，当 `.env` 中存在时将使用其中的 `ARTICRAFT_MODEL` 和 `ARTICRAFT_THINKING_LEVEL`，否则使用 `--model gpt-5.5-2026-04-23 --thinking-level high`。你可以更改模型和上限： ```bash uv run articraft generate --max-cost-usd 1.5 "Create a compact desk fan with adjustable tilt." ``` 要从参考图像生成，请参阅 [图像条件生成](docs/image_conditioned_generation.md)。 ### 5. 打开查看器 浏览你刚生成的对象。可使用以下命令启动本地查看器 API 和 React 前端： ```bash just viewer ``` 要显式浏览外部数据文件夹： ```bash uv run articraft viewer --data-dir /Users/mzhou/articraft-data ``` ### 6. 编辑现有资产 当你要修改现有记录时，可对其进行分叉（fork）： ```bash uv run articraft fork "make the handle longer" ``` 分叉会创建新的子记录，且父记录保持不变。有关模型选项和历史查看，请参阅 [编辑现有记录](docs/record_editing.md)。 --- ## 本地库 使用精简的库界面来检查和维护数据文件夹： ```bash uv run articraft library list uv run articraft library rebuild-manifest uv run articraft library check --require-records uv run articraft library set-category ``` **数据使用与许可** 向 Articraft 项目贡献数据即表示你确认并同意：你的提交将用于构建、评估和改进机器学习模型，并可能作为 Articraft 数据发布的一部分公开发布。你明确同意所有贡献的数据均在 **[Creative Commons Attribution 4.0 International (CC-BY 4.0)](https://creativecommons.org/licenses/by/4.0/)** 许可下发布。 --- ## 文档与高级用法 - **[架构与项目结构](docs/architecture.md)** - **[Qwen / DashScope 快速入门](docs/qwen_dashscope_quickstart.md)** - **[Codex 插件配置](docs/codex_plugin.md)** - **[编辑现有记录](docs/record_editing.md)** - **[图像条件生成](docs/image_conditioned_generation.md)** - **[贡献规范与工作流](CONTRIBUTING.md)** - **[安全策略](SECURITY.md)** ## 引用 ```bibtex @article{zhou2026articraft, title = {Articraft: An Agentic System for Scalable Articulated 3D Asset Generation}, author = {Zhou, Matt and Li, Ruining and Lyu, Xiaoyang and Song, Zhaomou and Huang, Zhening and Zheng, Chuanxia and Rupprecht, Christian and Vedaldi, Andrea and Wu, Shangzhe}, journal = {arXiv preprint arXiv:2605.15187}, year = {2026} } ``` 本仓库在 [Apache-2.0 License](LICENSE) 许可下发布。