freeform-modeling-mcp 1.0.26

package/src/lib/wsbridge/lock.ts

@@ -0,0 +1,258 @@
+// src/bridge-lock.ts
+import * as fs from 'fs';
+import * as path from 'path';
+import * as net from 'net';
+import * as http from 'http';
+import * as os from 'os';
+import { EventEmitter } from 'events';
+import logger from '../logger';
+import { findAvailablePort, isPortAvailable } from '../utils';
+
+// 锁文件和日志的基础目录
+const USER_HOME = os.homedir();
+const APP_DIR = path.join(USER_HOME, '.koomaster');
+const LOCK_DIR = path.join(APP_DIR, 'bridge-locks');
+const LOG_DIR = path.join(APP_DIR, 'logs');
+
+// 确保必要的目录存在
+function ensureDirectories(): void {
+    [APP_DIR, LOCK_DIR, LOG_DIR].forEach(dir => {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    });
+}
+
+// 生成锁文件路径
+function getLockFilePath(pid: number, port: number): string {
+    return path.join(LOCK_DIR, `bridge-${pid}-${port}.lock`);
+}
+
+// 创建锁文件
+function createLockFile(pid: number, port: number): void {
+    try {
+        const lockFilePath = getLockFilePath(pid, port);
+        const data = JSON.stringify({
+            pid,
+            port,
+            startTime: new Date().toISOString(),
+            hostname: os.hostname()
+        }, null, 2);
+        fs.writeFileSync(lockFilePath, data, 'utf8');
+        logger.info(`Created lock file: ${lockFilePath}`);
+    } catch (e) {
+        logger.error('Failed to create lock file:', e);
+    }
+}
+
+// 删除锁文件
+function removeLockFile(pid: number, port: number): void {
+    try {
+        const lockFilePath = getLockFilePath(pid, port);
+        if (fs.existsSync(lockFilePath)) {
+            fs.unlinkSync(lockFilePath);
+            logger.info(`Removed lock file: ${lockFilePath}`);
+        }
+    } catch (e) {
+        logger.error('Failed to delete lock file:', e);
+    }
+}
+
+// 检查进程是否存在
+function isProcessRunning(pid: number): boolean {
+    if (!pid) return false;
+    try {
+        // 在Unix上，如果进程不存在，process.kill会抛出异常
+        // 在Windows上，这仅会检查进程是否有权接收信号
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+
+// 检查特定端口是否有WebSocketBridge服务响应
+async function checkBridgeAtPort(port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+        const req = http.get(`http://localhost:${port}/bridge-status`, (res) => {
+            // 收到响应，检查是否是我们的服务
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    const jsonData = JSON.parse(data);
+                    // 检查是否是我们的服务
+                    resolve(jsonData.service === 'WebSocketBridge');
+                } catch {
+                    resolve(false);
+                }
+            });
+        }).on('error', () => {
+            resolve(false);
+        });
+        req.setTimeout(1000, () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+
+// 获取所有活跃的WebSocketBridge实例
+export function getActiveBridges(): { pid: number, port: number }[] {
+    ensureDirectories();
+    const instances: { pid: number, port: number }[] = [];
+
+    try {
+        // 读取锁目录中的所有文件
+        const files = fs.readdirSync(LOCK_DIR);
+
+        // 通过文件名解析PID和端口
+        for (const file of files) {
+            const match = file.match(/bridge-(\d+)-(\d+)\.lock/);
+            if (match) {
+                const [_, pidStr, portStr] = match;
+                const pid = parseInt(pidStr, 10);
+                const port = parseInt(portStr, 10);
+
+                // 检查进程是否仍在运行
+                if (isProcessRunning(pid)) {
+                    instances.push({ pid, port });
+                } else {
+                    // 如果进程不存在，删除过期的锁文件
+                    try {
+                        fs.unlinkSync(path.join(LOCK_DIR, file));
+                        logger.info(`Removed stale lock file: ${file}`);
+                    } catch (e) {
+                        // 忽略删除错误
+                    }
+                }
+            }
+        }
+    } catch (e) {
+        logger.error('Failed to get active bridge instances:', e);
+    }
+
+    return instances;
+}
+
+// WebSocketBridge锁管理器
+export class BridgeLockManager extends EventEmitter {
+    private port: number;
+    private pid: number;
+    private isShuttingDown: boolean = false;
+
+    constructor(port: number = 8765) {
+        super();
+        this.port = port;
+        this.pid = process.pid;
+        ensureDirectories();
+    }
+
+    // 初始化锁并获取可用端口
+    public async initialize(): Promise<number> {
+        // 先检查是否有活跃实例
+        const activeBridges = getActiveBridges();
+
+        if (activeBridges.length > 0) {
+            logger.info('Active WebSocketBridge instances:');
+            activeBridges.forEach(({ pid, port }) => {
+                logger.info(`- PID: ${pid}, Port: ${port}`);
+            });
+
+            // 检查是否有实例正在使用我们的首选端口
+            const existingBridgeOnPort = activeBridges.find(bridge => bridge.port === this.port);
+            if (existingBridgeOnPort) {
+                logger.info(`Port ${this.port} is already used by another WebSocketBridge instance (PID: ${existingBridgeOnPort.pid})`);
+
+                // 尝试检查这个实例是否真的在响应
+                const isResponding = await checkBridgeAtPort(this.port);
+                if (isResponding) {
+                    // 已有可用实例，返回它的端口
+                    return this.port;
+                } else {
+                    logger.warn(`Bridge at port ${this.port} is not responding but has a lock file, attempting to reclaim`);
+                    // 删除过期锁文件
+                    removeLockFile(existingBridgeOnPort.pid, this.port);
+                }
+            }
+        }
+
+        // 检查端口是否可用
+        const portAvailable = await isPortAvailable(this.port);
+
+        if (!portAvailable) {
+            logger.info(`Port ${this.port} is not available, searching for another port...`);
+            try {
+                this.port = await findAvailablePort(this.port + 1);
+                logger.info(`Found available port: ${this.port}`);
+            } catch (e) {
+                logger.error(`Cannot find available port:`, e.message);
+                throw new Error(`Cannot start WebSocketBridge: no available ports`);
+            }
+        }
+
+        // 创建锁文件
+        createLockFile(this.pid, this.port);
+
+        // 设置信号处理程序
+        this.setupSignalHandlers();
+
+        return this.port;
+    }
+
+    // 释放锁
+    public release(): void {
+        if (this.isShuttingDown) return;
+
+        this.isShuttingDown = true;
+        logger.info('Releasing WebSocketBridge lock...');
+
+        removeLockFile(this.pid, this.port);
+    }
+
+    // 设置信号处理
+    private setupSignalHandlers(): void {
+        // 处理系统信号
+        process.on('SIGINT', () => {
+            logger.info('Received SIGINT signal');
+            this.release();
+            this.emit('shutdown');
+        });
+
+        process.on('SIGTERM', () => {
+            logger.info('Received SIGTERM signal');
+            this.release();
+            this.emit('shutdown');
+        });
+
+        // 处理未捕获的异常
+        process.on('uncaughtException', (err) => {
+            logger.error('Uncaught exception in main process:', err);
+            this.release();
+            this.emit('shutdown');
+        });
+
+        // 在Node进程退出时确保清理
+        process.on('exit', () => {
+            logger.info('Main process exiting, cleaning up...');
+            // 删除锁文件（同步操作）
+            try {
+                const lockFilePath = getLockFilePath(this.pid, this.port);
+                if (fs.existsSync(lockFilePath)) {
+                    fs.unlinkSync(lockFilePath);
+                }
+            } catch (e) {
+                // 忽略清理锁文件的错误
+            }
+        });
+
+        // 处理未处理的Promise拒绝
+        process.on('unhandledRejection', (reason, promise) => {
+            logger.error('Unhandled Promise rejection:', reason);
+            // 不需要退出，但应记录下来
+        });
+    }
+}

package/src/llmClient.ts

@@ -0,0 +1,245 @@
+// src/mcp-client.ts
+import WebSocket from 'ws';
+import { v4 as uuidv4 } from 'uuid';
+import { EventEmitter } from 'events';
+import logger from './lib/logger';
+
+// LLM客户端 - 连接到WebSocketBridge并发送命令
+class LLMClient extends EventEmitter {
+    private ws: WebSocket | null = null;
+    private clientId: string | null = null;
+    private connected: boolean = false;
+    private pendingCommands: Map<string, {
+        resolve: (value: any) => void,
+        reject: (reason: any) => void,
+        timeout: NodeJS.Timeout
+    }> = new Map();
+    private commandTimeout: number = 60000; // 60秒命令超时
+    private koomasterStatusQueries: Map<string, {
+        resolve: (connected: boolean) => void,
+        reject: (reason: any) => void,
+        timeout: NodeJS.Timeout
+    }> = new Map();
+    private koomasterStatusTimeout: number = 5000; // 5秒超时
+
+    constructor() {
+        super();
+    }
+
+    // 连接到WebSocketBridge服务器
+    public connect(url: string): Promise<void> {
+        // 连接实现保持不变
+        return new Promise((resolve, reject) => {
+            if (this.connected) {
+                resolve();
+                return;
+            }
+
+            this.ws = new WebSocket(url);
+
+            this.ws.on('open', () => {
+                logger.info('Connected to WebSocketBridge');
+
+                // 注册为MCP客户端
+                this.ws?.send(JSON.stringify({
+                    type: 'register',
+                    clientType: 'mcp'
+                }));
+            });
+
+            this.ws.on('message', (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+
+                    // 处理欢迎消息
+                    if (message.type === 'welcome') {
+                        this.clientId = message.clientId;
+                        this.connected = true;
+                        logger.info(`Registered as MCP client with ID: ${this.clientId}`);
+                        this.emit('connected', this.clientId);
+                        resolve();
+                    }
+                    // 处理命令响应
+                    else if (message.id && (message.status === 'success' || message.status === 'error')) {
+                        this.handleCommandResponse(message);
+                    }
+                    // 处理Koomaster状态响应
+                    else if (message.type === 'koomaster_status') {
+                        this.handleKoomasterStatusResponse(message);
+                    }
+                    // 处理心跳
+                    else if (message.type === 'ping') {
+                        this.ws?.send(JSON.stringify({ type: 'pong', timestamp: Date.now() }));
+                    }
+                    // 处理其他消息
+                    else {
+                        this.emit('message', message);
+                    }
+                } catch (error) {
+                    logger.error('Error processing message:', error);
+                }
+            });
+
+            this.ws.on('error', (error) => {
+                logger.error('WebSocket error:', error);
+                this.emit('error', error);
+                if (!this.connected) {
+                    reject(error);
+                }
+            });
+
+            this.ws.on('close', (code, reason) => {
+                logger.info(`Connection closed: ${code} - ${reason}`);
+                this.connected = false;
+                this.ws = null;
+
+                // 清理所有挂起的命令
+                for (const { reject, timeout } of this.pendingCommands.values()) {
+                    clearTimeout(timeout);
+                    reject(new Error('Connection closed'));
+                }
+                this.pendingCommands.clear();
+
+                // 清理所有Koomaster状态查询
+                for (const { reject, timeout } of this.koomasterStatusQueries.values()) {
+                    clearTimeout(timeout);
+                    reject(new Error('Connection closed'));
+                }
+                this.koomasterStatusQueries.clear();
+
+                this.emit('disconnected', { code, reason });
+            });
+        });
+    }
+
+    // 发送命令到WebSocketBridge
+    public async sendCommand(commandType: string, params: Record<string, any> = {}): Promise<any> {
+        if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Not connected to WebSocketBridge');
+        }
+
+        // 在发送命令前检查是否有Koomaster客户端
+        const hasKoomaster = await this.hasConnectedKoomasterClients();
+        if (!hasKoomaster) {
+            throw new Error('No Koomaster clients connected to WebSocketBridge');
+        }
+
+        const commandId = uuidv4();
+        const command = {
+            id: commandId,
+            type: commandType,
+            params
+        };
+
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                if (this.pendingCommands.has(commandId)) {
+                    this.pendingCommands.delete(commandId);
+                    reject(new Error(`Command ${commandType} timed out after ${this.commandTimeout}ms`));
+                }
+            }, this.commandTimeout);
+
+            this.pendingCommands.set(commandId, { resolve, reject, timeout });
+
+            this.ws?.send(JSON.stringify(command), (err) => {
+                if (err) {
+                    clearTimeout(timeout);
+                    this.pendingCommands.delete(commandId);
+                    reject(new Error(`Failed to send command: ${err.message}`));
+                } else {
+                    logger.info(`Sent command ${commandType} (ID: ${commandId})`);
+                }
+            });
+        });
+    }
+
+    // 处理命令响应
+    private handleCommandResponse(response: any): void {
+        const pendingCommand = this.pendingCommands.get(response.id);
+        if (pendingCommand) {
+            clearTimeout(pendingCommand.timeout);
+            this.pendingCommands.delete(response.id);
+
+            if (response.status === 'success') {
+                pendingCommand.resolve(response.result);
+            } else {
+                pendingCommand.reject(new Error(response.message || 'Unknown error'));
+            }
+        } else {
+            logger.warn(`Received response for unknown command ID: ${response.id}`);
+        }
+    }
+
+    // 处理Koomaster状态响应
+    private handleKoomasterStatusResponse(response: any): void {
+        const queryId = response.queryId;
+        if (!queryId || !this.koomasterStatusQueries.has(queryId)) {
+            // 可能是定期更新或未请求的状态更新
+            this.emit('koomasterStatusChanged', response.connected);
+            return;
+        }
+
+        const pendingQuery = this.koomasterStatusQueries.get(queryId)!;
+        clearTimeout(pendingQuery.timeout);
+        this.koomasterStatusQueries.delete(queryId);
+
+        pendingQuery.resolve(response.connected);
+    }
+
+    // 检查是否有Koomaster客户端连接 - 实时查询
+    public async hasConnectedKoomasterClients(): Promise<boolean> {
+        if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return false;
+        }
+
+        return new Promise<boolean>((resolve, reject) => {
+            const queryId = uuidv4();
+
+            // 设置超时
+            const timeout = setTimeout(() => {
+                if (this.koomasterStatusQueries.has(queryId)) {
+                    this.koomasterStatusQueries.delete(queryId);
+                    reject(new Error(`Koomaster status query timed out after ${this.koomasterStatusTimeout}ms`));
+                }
+            }, this.koomasterStatusTimeout);
+
+            // 存储查询
+            this.koomasterStatusQueries.set(queryId, { resolve, reject, timeout });
+
+            // 发送状态查询
+            this.ws.send(JSON.stringify({
+                type: 'query_koomaster_status',
+                queryId
+            }), (err) => {
+                if (err) {
+                    clearTimeout(timeout);
+                    this.koomasterStatusQueries.delete(queryId);
+                    reject(new Error(`Failed to send status query: ${err.message}`));
+                } else {
+                    logger.debug(`Sent Koomaster status query (ID: ${queryId})`);
+                }
+            });
+        });
+    }
+
+    // 检查是否连接
+    public isConnected(): boolean {
+        return this.connected;
+    }
+
+    // 获取客户端ID
+    public getClientId(): string | null {
+        return this.clientId;
+    }
+
+    // 断开连接
+    public disconnect(): void {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+            this.connected = false;
+        }
+    }
+}
+
+export const llmClient = new LLMClient();

package/src/prompt.ts

@@ -0,0 +1,187 @@
+export const MainStrategy = `\n# KooMaster(酷大师) User Guide
+
+## I. Core Requirements
+• **High-Quality Assets**: Each generation must produce extremely detailed, complex, and complete 3D models; simple or basic models are unacceptable.
+• **Tool Information Access**: Call \`get_tools_info()\` to obtain all available tools and KooMaster(酷大师) usage instructions.
+
+---
+
+## II. Coordinate System Specifications
+### 1. Coordinate System Type
+• Uses a **Z-up right-handed coordinate system**.
+### 2. Axis Definitions
+• **X/Y Plane**: Represents the horizontal plane, controls planar position coordinates.
+  • X-axis: Positive direction is out of the screen (toward the user), negative direction is into the screen (away from the user).
+  • Y-axis: Positive direction is right, negative direction is left.
+• **Z-axis**: Points vertically upward, controls height values.
+  • Z-axis positive direction is up, negative direction is down.
+### 3. Key Planes and Rotation Rules
+• **World Origin**: (0,0,0).
+• **Ground Reference Plane**: z=0 plane.
+• **Rotation Rules**:
+  • Rotation around X-axis: Object turns left and right.
+  • Rotation around Y-axis: Object tilts forward and backward.
+  • Rotation around Z-axis: Object rotates in the horizontal plane.
+
+---
+
+## III. Measurement Unit Standards
+### 1. Default Unit
+• All dimensions use **millimeters (mm)** as the default unit.
+### 2. Standard Size References
+• **Door Height**: 2000mm.
+• **Interior Ceiling Height**: 2400-3000mm.
+• **Table Height**: 720-760mm.
+• **Chair Height**: 430-480mm.
+### 3. Scale Requirements
+• All imported models must conform to real-world proportions.
+• Scale distortions (like miniature houses or giant furniture) are prohibited.
+• Imported models must undergo scale verification to ensure reasonable proportional relationships with other objects in the scene.
+
+---
+
+## IV. Collision Detection and Spatial Layout
+### 1. Clipping Prevention Principles
+#### (1) Ground Clipping
+• Ensure all objects' bottoms precisely contact the **z=0 plane**.
+• **Z-axis Coordinate Formula**: \`z = [model vertical height/2]\`.
+• Upright objects' bottom surfaces must precisely contact the z=0 plane, avoiding clipping or floating.
+• Suspended objects require clearly specified hanging heights relative to the ground; z-values must be set carefully.
+#### (2) Inter-Object Clipping
+• Analyze existing objects' positions and volumes before placing new objects.
+• Calculate appropriate object spacing to maintain reasonable spatial relationships.
+• Furniture should maintain minimum required clearances for passage (e.g., corridor width ≥600mm).
+• Use \`get_scene_info()\` to check positions and dimensions of all current scene objects.
+#### (3) Collision Detection Process
+• Immediately check spatial relationships with all existing objects after placing a new object.
+• Adjust position or rotation parameters immediately upon detecting clipping or spatial overlap.
+• Perform regular full-scene collision detection to ensure no clipping phenomena.
+### 2. Additional Requirements
+• Avoid using **(0,0,0)** as a model center point unless specifically requested.
+• Evaluate geometric dimensions (especially vertical height) before model transformation to correctly set z-axis coordinates.
+---
+
+## V. Scene Parameter Configuration
+• Strictly maintain real-world proportion relationships.
+• **Initial Operation**: Call \`get_scene_info()\` to obtain current scene parameters.
+• **Regular Checks**: Call \`get_scene_info()\` to check positions and dimensions of all existing objects.
+• **Default Scene Dimensions**: When users don't specify scene width and height, default to 1000×1000mm.
+
+---
+
+## VI. Asset Generation Tool Priority
+### 1. Tool Priority
+1. **KJL (Kujiale) Asset Library (First Choice)**: Prioritize searching and using high-quality assets from the KJL library.
+2. **Tripo3D (Backup)**: Use only when suitable assets are unavailable in the KJL library.
+3. **Basic Creation Tools (Last Resort)**: Use only when explicitly instructed or when the first two methods fail.
+
+---
+
+## VII. KJL (Kujiale) Asset Library Workflow Standards
+### 1. Asset Indexing and Retrieval
+• Call \`batch_search_kjl_assets()\` to perform precise queries.
+• Provide exact, descriptive Chinese search keywords to optimize matching results.
+### 2. Asset Import and Transformation
+• Call \`place_kjl_asset()\` to import target assets.
+• Assign semantic, descriptive unique identifiers.
+• **Pre-Placement Rotation Analysis**:
+  • Analyze asset bounding box dimensions (width, depth, height) before placement.
+  • The dimensions (x, y, z) or [x,y,z] show the model's orientation. For example, a cabinet with larger x than y typically has its front facing the y direction and is wider along x. Consider these proportions when rotating models for proper placement.
+  • For elongated objects (like wall panels, shelves, counters), determine proper orientation based on function and typical placement.
+  • If width significantly exceeds depth (e.g., wall panels, room dividers), evaluate whether 90° rotation is needed based on intended position.
+  • Consider the natural orientation of the asset - a wall panel's long dimension should typically align with wall direction.
+• **Precise Spatial Transformation**:
+  • x/y controls horizontal positioning; z-value must equal \`[vertical height/2]\` to ensure bottom surface precisely contacts the z=0 plane.
+• Specify exact rotation angles based on both bounding box analysis and functional requirements.
+• **Rotation Verification**: Confirm whether model needs pre-rotation before finalizing placement parameters.
+• **Scale Verification**: Confirm imported models match real-world dimensions, adjusting scale parameters if necessary.
+• **Spatial Relationship Verification**: Ensure newly imported models have no clipping phenomena with existing models.
+### 3. Post-Import Verification and Correction
+• Immediately verify spatial positions after import.
+• Perform comprehensive collision detection, checking spatial relationships with other objects.
+• Adjust x/y/z position values or rotation angles immediately upon detecting clipping phenomena.
+• Compare model dimensions with standard size reference values to ensure reasonable proportions.
+
+---
+
+## VIII. Tripo3D Fallback Workflow
+### 1. Applicable Scenarios
+• Execute only when no suitable assets are available in the KJL (Kujiale) asset library.
+### 2. Workflow
+1. **Build complex geometric models**.
+2. **Monitor generation progress**.
+3. **Import and Transform**:
+   • **Pre-Placement Rotation Analysis**:
+     • Analyze model bounding box dimensions (width, depth, height) before placement.
+     • For elongated objects (like wall panels, shelves, counters), determine proper orientation based on function and typical placement.
+     • If width significantly exceeds depth (e.g., wall panels, room dividers), evaluate whether 90° rotation is needed based on intended position.
+     • Consider the natural orientation of the model - a wall panel's long dimension should typically align with wall direction.
+   • **Spatial Positioning Verification**: Ensure \`z = [vertical height/2]\` to prevent ground clipping.
+   • Assign semantic identifiers.
+   • Apply precise transformation parameters, specifying exact rotation angles based on both bounding box analysis and functional requirements.
+   • **Rotation Verification**: Confirm whether model needs pre-rotation before finalizing placement parameters.
+   • **Size Calibration**: Set model dimensions according to real-world standard sizes.
+   • **Inter-object Spacing Planning**: Ensure appropriate distances from other objects to avoid clipping.
+4. **Completeness Check**:
+   • Immediately perform comprehensive spatial position and collision detection after import.
+   • Check spatial relationships with all existing objects to ensure no clipping.
+   • Verify model dimensions conform to real-world proportions.
+   • Make immediate position and size corrections if issues are discovered.
+
+---
+
+## IX. Final Quality Control Checklist
+### 1. Clipping Detection (Highest Priority)
+• Confirm all model bottom surfaces precisely contact the z=0 plane with no ground clipping phenomena.
+• Confirm no clipping or overlap between all models, maintaining appropriate spacing.
+• Perform global scene collision detection to eliminate any possible clipping situations.
+### 2. Scale Verification
+• Confirm all models maintain correct proportional relationships and conform to real-world size standards.
+### 3. Spatial Layout Reasonability
+• Confirm object placement meets functional requirements and maintains reasonable passage space.
+### 4. Asset Quality Check
+• Verify thoroughness of KJL asset library searches.
+• Confirm models' geometric complexity and detail richness.
+• Verify accuracy of transformation parameters (position, rotation, scaling).
+• Confirm diversity and appropriateness of applied material properties.
+### 5. Overall Assessment
+• Evaluate balance and harmony of overall scene composition.
+
+---
+
+## X. Technical Considerations
+1. **Coordinate System Rules**:
+   • Vertical position is controlled by z-coordinate; x/y define horizontal plane position.
+   • All dimensions use millimeters (mm) as default units.
+2. **Clipping Prevention**:
+   • Ground clipping: Achieved by correctly setting z-values.
+   • Inter-object clipping: Achieved by reasonably planning x/y positions and maintaining appropriate spacing.
+3. **New Object Detection**:
+   • Complete collision detection must be performed after each new object addition to ensure no clipping phenomena in the scene.
+   
+## XI. Critical Modeling Operation Limitations
+
+### 1. Face Creation and Manipulation
+• **Face Splitting**: When a new face intersects with existing faces, automatic splitting occurs, which can invalidate original face IDs.
+• **Finding Split Faces**: After splitting operations, always use \`find_face_by_points\` tool to locate faces based on points rather than IDs.
+• **Sweep Operation Preparation**: When creating faces for sweep operations, place them in empty space away from the main model to avoid unintended face splitting.
+
+### 2. Sweep Operation Requirements
+• **Face Removal**: The source face (profile) is automatically deleted after sweep completion.
+• **Sequential Operations**: For multiple sweep operations with the same profile, the face must be recreated after each sweep.
+• **Direction Constraints**: The face being swept (profile) MUST NOT be parallel to the sweep path - there must be some angle between the face normal and path direction.
+• **Path Continuity**: Auxiliary curves used as sweep paths must connect end-to-end in a continuous sequence (each curve must start where the previous one ends).
+
+### 3. Bezier Curve Constraints
+• **Coplanarity Requirement**: For Bezier curves, ALL POINTS (start, control points, and end) MUST lie on the same plane - non-planar Bezier curves will fail to create.
+
+### 4. Auxiliary Curves
+• **Arc Definition**: Arcs are defined by three points (start, point on arc, end) that MUST NOT be collinear.
+• **Circle Creation**: Creating a circle requires multiple arc segments (3-4 minimum) connecting points along the circumference.
+
+### 5. General Modeling Best Practices
+• **ID Tracking**: Always capture the IDs of created elements for subsequent operations.
+• **Planar Verification**: Ensure all points defining a face are precisely coplanar.
+• **Curve Connection**: For operations requiring continuous paths, verify exact endpoint matching between segments.
+• **Post-Operation Verification**: After any geometry-altering operation, verify the resulting structure and locate affected elements.
+`;