warehouse-cad-agent 是一个 Windows 优先的 Codex 插件和 Python 引擎，用于可追溯的仓库 CAD 往返流程：
审计已声明 DXF 中的每个模型空间实体，或审计其读取 DXF 转换具有匹配哈希收据的 DWG；
将可见设备与结构分开，而不静默接受未解析的候选对象；
编写一份自包含的 Markdown 设备台账；
仅凭空白 CAD 和该台账重建可编辑的 2D CAD；
创建受证据限制的可移植 3D，并在存在完整的来源支持的占地、高度和高程证据时创建原生 AutoCAD 3DSOLID；
让智能体通过五个有界 MCP 工具检查和编辑自动创建的 AutoCAD 工作副本。
该项目刻意不推断缺失的设备身份、高度、高程、流向、端口或制造商几何形状。协议握手、截图、文件存在性检查或输出选择计数均不被视为所请求的 CAD 工件已完成的证据。
此仓库仅包含通用引擎、插件、技能、MCP 桥接、合成夹具和验证代码。客户图纸、客户名称、来源哈希、私有分类配置文件和交付证据属于单独的私有集成仓库。
Related MCP server: AgentCAD
要求：Python 3.11+，以及可选的、带 COM 自动化的完整 AutoCAD，用于实时编辑和原生 DWG 实体。Autodesk DWG TrueView 不是可写的 AutoCAD 运行时。
受管理的 AutoCAD 打开操作仅在 Documents.Open 周围临时使用 DWGCHECK=0，打开后等待 AutoCAD 静默，然后恢复并验证确切的先前值。这仅抑制非 Autodesk 生产者警告，同时保留 AutoCAD 的损坏错误对话框；它并不声明图纸有效。
实时审阅注释创建绝不重试非幂等的 AddText 调用。如果 AutoCAD 在创建某些内容后报告调用失败，桥接会使用写入前的模型空间句柄快照以及类型、插入点和高度，仅恢复一个唯一可归属的新文本实体。该注释、其图层及其注册应用程序属于一个撤销事务。已知字段各自最多写入一次并读回。如果不完整的结果更改了句柄/图层/注册应用程序快照，桥接会请求一次撤销并验证全部三组；如果快照从未更改，则不会撤销或声称回滚。任何未经证明的恢复都会以结构化部分编辑错误保留受管理的工作副本。
已保存/已关闭/已重新打开的验收可以使用由智能体新启动的 AutoCAD 进程。shutdown 会话操作是失败即关闭的：它要求没有受管理的会话、没有控制图纸、零个打开的文档，并确认绑定到应用程序窗口的确切进程已退出。其可选的 force_if_graceful_timeout=true 回退仅限于该由智能体启动的进程：在一次优雅的 Application.Quit 超时后，桥接必须重新确认 AutoCAD 处于空闲状态且零文档，然后才能终止一次已绑定的 Windows 进程句柄。它绝不会退出或终止智能体仅附加到的 AutoCAD 应用程序。
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\warehouse-cad-agent doctor
.\.venv\Scripts\python.exe examples\synthetic\make_fixture.py
.\.venv\Scripts\warehouse-cad-agent roundtrip examples\synthetic\project.yamlCodex 仓库市场清单是 .agents/plugins/marketplace.json。将克隆的仓库注册为本地市场，安装插件，然后启动一个新的 Codex 线程：
git clone https://github.com/X-isdoingreat/warehouse-cad-agent.git
Set-Location warehouse-cad-agent
codex plugin marketplace add .
codex plugin add warehouse-cad-agent@warehouse-cad-agent在该新线程中调用 $warehouse-cad-agent。市场使用 ON_USE 身份验证：以交互方式批准首次本地 MCP 使用。配置了 approval=never 的非交互式会话将发现这五个工具，但除非该调用被明确授权，否则必须拒绝该调用。
project.yaml 是运行允许列表。一个独立的 source.read_dxf 必须包含 source.read_conversion_receipt；未解析的对象只能通过绑定的 source.resolution.inventory 加上 source.resolution.ledger 进行分类。产品审计会枚举文件，但它本身并不是独立的客户验收分母。
空白 CAD 和 Markdown 不被视为可互换的有效文件：空白文件带有嵌入的项目/来源绑定，Markdown 台账还绑定确切的空白文件 SHA-256，并且每次重建都会在写入输出之前拒绝不匹配或已修改的文件对。发出原生实体规格的客户适配器使用相同的精确空白规则，并将先前的来源台账验收目标与当前的原生 CAD 产品目标分开。
合成空白 + Markdown + 隔离 2D + 可移植 3D 路径以及一次全新的 Codex/MCP doctor 调用已在本地执行。在一个确切的合成 DWG 上，已安装的插件还通过了真实 AutoCAD 2027 Trial 的创建/查询/回滚/保存以及新进程重新打开对账。一个确切的、私有的、哈希绑定的仓库 DWG + 设备台账来源集还通过了原生 3DSOLID 生成、最终 DWG 保存、版本匹配的 ObjectDBX 重新打开、记录级智能体身份/几何对账以及真实 AutoCAD 2027 Trial 中的最终结构对账。这些是狭窄的来源集结果，而不是任意 DWG、制造商模型、BIM 或生产就绪性的声明。doctor 区分已安装/活动的完整 AutoCAD 身份与当前足够空闲以接受自动化的进程；它不推断付费或试用权利。当原生实体规格仍绑定到来源空白 DXF 时，AutoCAD 仅打开单独提供的运行时 DWG，其转换收据绑定两个哈希，并证明零不匹配的流式 DXF→DWG→DXF 结构比较。TrueView 不满足该门槛。
在做出能力声明之前，请参阅 docs/PRODUCT_BOUNDARY.md。可移植的 DXF 3D 是审计衍生物；原生工程 3D 主文件是包含由完整 AutoCAD 根据来源支持的证据生成的、可重新打开且可测量的 3DSOLID 对象的 DWG。
Apache-2.0。COM/MCP 设计借鉴了 Apache-2.0 的 multiCAD-mcp 项目；请参阅 NOTICE。
Apply a bounded, traceable edit to the active managed AutoCAD work copy. Deletion is limited to provably agent-owned entities; source-backed text updates require provenance.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, so the description is not required to restate that. It adds value by disclosing limits on destructive actions: deletion is restricted to agent-owned entities and source-backed text updates require provenance. This gives operational constraints beyond the annotation, though it doesn't detail error/rollback behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler. It front-loads the core purpose and then delivers key constraints, making it both concise and well-ordered. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six distinct actions and an unstructured params object, the description is far too brief. It only hints at two use-case constraints but says nothing about how to invoke each action, what params to pass, or what the result looks like. The high complexity demands significantly more explanation than given.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description mentions no parameter details whatsoever. The params object is unstructured (additionalProperties: true) with six possible actions, yet the description provides no guidance on what each action expects or how to construct params, leaving the agent entirely without parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb 'apply edit' and a specific resource 'active managed AutoCAD work copy'. It further distinguishes itself from sibling tools (query, export, session, project) by being the modification tool, and it adds constraints about deletion and source-backed text updates, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and the context of sibling tools—this is obviously the edit tool for the warehouse CAD work copy. However, the description does not explicitly state when to use it versus alternatives, nor does it mention when not to use it, leaving some routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the managed work copy or build a native 3DSOLID DWG. All paths remain under the authorized root; native solids require source-verified footprint, height, and elevation.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| params | No | ||
| project_file | No | User-selected absolute or current-workspace project.yaml path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full responsibility for behavioral disclosure. It mentions path restrictions and prerequisites for native solids, but does not disclose whether the operation modifies data, creates files, has side effects, or requires specific permissions. For an export tool, it is likely to create files, but this is not stated. The description adds some transparency about constraints but lacks detail on side effects and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It efficiently states the core function and key constraints, front-loading the action and important prerequisites. Every word adds value, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a nested params object, an action enum with five values, and no output schema, the description is insufficient. It does not explain the purpose of each action, what parameters to pass for each, or what the return format will be. While it notes path restrictions and prerequisites, it omits crucial operational details needed for correct invocation, especially for the 'params' object which is entirely opaque.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only project_file has a description). The tool description does not explain the 'action' enum values or the structure of the 'params' nested object. It vaguely references requirements for native solids (footprint, height, elevation) but does not map these to specific parameters. With low schema coverage, the description fails to compensate, leaving agents uncertain about how to fill the params object and what each action entails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: exporting the managed work copy or building a native 3DSOLID DWG. It specifies two primary modes and distinguishes this from sibling tools (warehouse_project, warehouse_cad_session, etc.) as an export operation. However, it does not enumerate all action enum values (data, dxf, pdf, snapshot), leaving some ambiguity about the full scope of export types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context for when to use the tool, indicating that native solids require source-verified footprint, height, and elevation, and that all paths are restricted to the authorized root. However, it does not explicitly contrast with alternative tools or provide explicit when-to-use versus when-not-to-use guidance. The conditions given are more about prerequisites than about choosing this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List, inspect, highlight, measure, or compare entities in the active managed AutoCAD work copy. Geometry measurements remain calculations, not verified business facts.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a meaningful caveat beyond the readOnlyHint annotation: 'Geometry measurements remain calculations, not verified business facts.' This warns the agent that measurement results are not authoritative, which is valuable. However, it does not elaborate on behaviors for each action (e.g., whether 'highlight' changes the UI selection state) or other side effects beyond the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no waste. The first sentence front-loads the core operations and target, and the second delivers an important caveat. Both sentences earn their place and the structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five distinct actions and an open-ended params object, the description is too sparse. It does not define what each action does, what parameters they expect, or what the return looks like (no output schema). It also does not clarify prerequisites like an active session or what 'managed work copy' means. The description is incomplete for an agent to call this tool correctly without further inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It lists verbs that roughly correspond to the action enum (e.g., 'inspect' vs 'get', 'highlight' vs 'select') but does not explain each action's purpose or the expected structure of the params object. The generic params is left entirely unexplained, and the wording mismatch between the description and enum values adds confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to list, inspect, highlight, measure, or compare entities in the active managed AutoCAD work copy. The verb set is specific and distinguishes it from sibling tools like warehouse_cad_edit (modification) and warehouse_cad_export (export). The read-only nature is implied by the verbs and consistent with the annotation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus the sibling tools. The description only mentions the active managed AutoCAD work copy, but does not explain when to choose query over edit/export/session/project. The name 'query' suggests a read-only role, but the description lacks any 'use this when...' or 'use X instead' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to writable full AutoCAD and manage exactly one automatically-created work copy. Never opens the customer source as a write target; TrueView is rejected. Shutdown can quit only a document-free AutoCAD instance launched by this Agent.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| params | No | ||
| project_file | No | User-selected absolute or current-workspace project.yaml path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose key safety behaviors: it never opens the customer source as a write target, rejects TrueView, and shutdown can only quit a document-free instance launched by this Agent. These are valuable but do not cover the full range of actions or their side effects, so partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The core purpose is front-loaded, followed by key constraints. It is efficient and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 actions, a nested params object, and no output schema, the description is insufficient. It does not explain what any of the actions do, what parameters they need, or what the return looks like. The agent is left guessing on crucial execution details, so completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% — only project_file is described in the schema. The description adds no information about the 'action' enum values or the 'params' object (which is untyped with additionalProperties true). The agent has no idea what each action requires or how to structure params, and the description fails to compensate for this low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool connects to writable full AutoCAD and manages 'exactly one automatically-created work copy', giving a specific verb and resource. It also clarifies it rejects TrueView and never writes to the customer source, which helps distinguish it from other CAD tools. However, it does not explicitly name sibling tools to differentiate, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides constraints (never write to source, TrueView rejected, shutdown limits) but gives no guidance on when to choose this tool over the sibling tools like warehouse_cad_edit or warehouse_cad_query. There is no explicit 'use this when...' or 'use that instead...' guidance, leaving the agent to infer the tool's scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate, audit, rebuild, verify, package, or control one declared warehouse CAD project. Long jobs are single-worker and return job_id. Audit output is not an independent acceptance denominator by itself.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| job_id | No | ||
| params | No | ||
| project_file | No | User-selected absolute or current-workspace project.yaml path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that long jobs are single-worker and that audit output is not an independent acceptance denominator, which are useful caveats. However, it omits other behavioral aspects like side effects, permission requirements, or reversibility, leaving transparency incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loads the key actions. It avoids unnecessary words, but the brevity somewhat undermines clarity. The structure is acceptable for a short description, though it could benefit from a brief explanation of the actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10-action enum, nested params object, no output schema), the description is far from complete. It does not describe each action's purpose, the format of params, or expected outcomes. The note about job_id and audit output provides some context, but an agent would still need significant external knowledge to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers only 25% of parameters (only project_file has a description). The description does not explain the 'action' enum values, the purpose of job_id, or the 'params' object. It mentions job_id in passing but provides no guidance on how to construct or interpret it. This is insufficient for an agent to correctly fill parameters, especially given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description lists specific verbs (validate, audit, rebuild, verify, package, control) acting on 'one declared warehouse CAD project', giving a clear resource and a set of operations. It distinguishes this tool from siblings that handle sessions, queries, edits, and exports by focusing on project-level actions, though the broad action list makes the primary purpose less crisp than a single-verb description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not indicate when to use this tool versus the sibling tools (warehouse_cad_session, warehouse_cad_query, etc.) or when not to use it. The only usage hint is that long jobs are single-worker and return job_id, but there is no explicit guidance on scenario selection or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0warehouse_cad_editwarehouse_cad_exportwarehouse_cad_querywarehouse_cad_sessionwarehouse_projectScored across 5 tools
Each tool targets a distinct level: project management, session management, querying, editing, and exporting. No two tools overlap in purpose, making selection unambiguous.
All tools share the 'warehouse_' prefix, and four of five follow the 'warehouse_cad_' pattern. The sole exception, 'warehouse_project', still fits the broad naming scheme but lacks the 'cad_' segment, a minor inconsistency.
With only 5 tools, the set is tightly focused and each tool covers a major capability area. This is an ideal scope for a CAD agent, avoiding bloat while remaining useful.
The tools cover the full workflow from project validation/rebuild, session control, query, edit, to export. Minor gaps exist (e.g., no explicit import or undo), but the core lifecycle is well supported.
MCP CAD services; bundles with SmartScale (measure to CAD).
Agent-first CAD: editable .kcad.ts source, deterministic review, OpenCASCADE kernel.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Read and edit the Revit 2024–2027 model on your PC. Needs the free Revit MCP add-in.
