@kudashi/kds-api 2.13.1 → 2.13.3

package/api.d.ts

@@ -257,72 +257,132 @@ declare global {
     }
 
     /**
+     * KApplication 是使用酷大师前端 Plugin API 的起点。
+     *
+     * 从这里我们可以获取很多其他有用的 API 接口。例如：
+     *  1. 代表当前打开的酷大师方案的 KDesign 接口，从这里我们可以调用酷大师的各种建模命令，如拉伸、扫掠、布尔等，对方案数据进行修改;
+     *  2. 代表酷大师视图窗口的 KView 接口，从这里我们可以获取酷大师的画布和相机对象，并在画布中绘制各种临时图形元素；
+     *  3. 代表酷大师选择集的 KSelection 接口，从这里我们可以获取酷大师画布中的各种被选择的对象，如造型面、造型边、参考线、成组等
+     *  ... ...
+     *
+     * KApplication 还可以激活一个插件自定义工具对象 (KTool)，它可以响应各种鼠标、键盘事件，实现和酷大师内置建模工具类似的交互效果;
+     * KApplication 还可以注册、注销酷大师应用的事件观察者，供插件响应酷大师发出的各种事件
+     *
+     * 请阅读下面的方法注释，以获取更详细的信息
+     *
+     *
      * The KApplication interface serves as the "entry point" for most other APIs. From here we can get the active design,
      * which represents the user's design data; we can get the active view, which represents the application's graphics view.
-     * We can also activate a custom tool, which is the tool that plugin provides to interact with the design daa...
+     * We can also activate a custom tool, which is the tool that plugin provides to interact with the design data...
      * please check the comments below for more information.
      */
     interface KApplication {
         /**
+         *
+         * 获取酷大师信息提示接口
+         *
          * Get the toast operation handle.
          * @returns The toast operation handle.
          */
         getToast(): KToast;
+    
         /**
+         *
+         * 获取酷大师选择集。用户在视图窗口中用鼠标选中的造型面、造型边、参考线、成组等，都可以从此选择集中得到
+         *
          * Get the selection operation handle.
          * @returns The selection operation handle.
          */
         getSelection(): KSelection;
+    
         /**
+         * 获取当前打开的酷大师方案。从 KDesign 接口我们可以调用酷大师各种建模命令，如拉伸、扫掠、布尔等，对方案数据进行修改
+         *
          * Get the active design.
          * @returns The active design.
          */
         getActiveDesign(): KDesign;
+    
         /**
+         *
+         * 获取酷大师视图窗口。从 KView 接口我们可以获取酷大师的画布和相机对象，并在画布中绘制各种临时图形元素
+         *
          * Get the active view.
          * @returns The active view.
          */
         getActiveView(): KView;
+    
         /**
+         *
+         * 获取插件 UI 面板。插件如果提供了 UI html，就是在这个 UI 面板里打开的。我们可以调整此 UI 面板的大小，发送和响应插件自定义消息
+         *
          * Get the KPluginUI object for operating the plugin UIs.
          * @returns The KPluginUI object for operating the plugin UIs.
          */
         getPluginUI(): KPluginUI;
+    
         /**
+         *
+         * 获取酷大师应用的 UI 面板，即顶部工具栏、左侧栏、右侧属性面板等组成的酷大师 UI 面板
+         *
          * Get the KApplicationUI object for operating the application UI.
          * @returns The KApplicationUI object for operating the application UI.
          */
         getApplicationUI(): KApplicationUI;
+    
         /**
+         *
+         * 获取客户端临时存储对象。通过该对象，插件可在客户端进行临时数据存取
+         *
          * Get the KClientStorage object for allowing you to store data on the user's local machine.
          * @returns The KClientStorage object.
          */
         getClientStorage(): KClientStorage;
+    
         /**
+         *
+         * 获取自定义工具 KTool 的帮助接口，此接口提供了一组帮助自定义工具实现更复杂交互效果的方法，例如激活选择功能，激活框选功能，设置选择过滤器等
+         *
          * Get the utility helper for plugin tools.
          * @returns The KToolHelper object.
          */
         getToolHelper(): KToolHelper;
+    
         /**
+         *
+         * 获取选择帮助器，此接口提供了按屏幕 2d 点选，按屏幕 2d 矩形框选等进行选择的方法
+         *
          * Get the KPickHelper object for allowing you to pick entities.
          * @returns The KPickHelper object.
          */
         getPickHelper(): KPickHelper;
+    
         /**
+         *
+         * 激活插件自定义工具。插件自定义工具能响应各种鼠标、键盘事件，从而实现和酷大师内置建模工具类似的交互效果
+         *
          * Activate the custom tool.
          * @param tool The custom tool.
          * @param clearSelection If the clearSelection flag is set to true, when the tool is activated, the selection will be cleared. The default value is false.
          * @returns Return true if successful, otherwise return false.
          */
         activateCustomTool(tool: KTool, clearSelection?: boolean): boolean;
+    
         /**
+         *
+         * 反激活插件自定义工具
+         *
          * Daactivate the custom tool.
          * @param tool The custom tool.
          * @param clearSelection If the clearSelection flag is set to true, when the tool is deactivated, the selection will be cleared. The default value is false.
          * @returns Return true if successful, otherwise return false.
          */
         deactivateCustomTool(tool: KTool, clearSelection?: boolean): boolean;
+    
         /**
+         *
+         * @deprecated：延时若干毫秒后执行一个函数 （本方法将被移除。建议直接使用 JS 内置的 setTimeout 方法）
+         *
          * The method is used to call a function after the specified number of milliseconds.
          * @param callback The called function.
          * @param time The specified number of milliseconds.
@@ -330,13 +390,21 @@ declare global {
          * @returns
          */
         setTimeout(callback: (...args: any[]) => void, time: number, ...args: any[]): void;
+    
         /**
+         *
+         * 添加酷大师应用观察者。目前观察者主要用于响应插件关闭的消息，这样插件本身可以完成一些业务逻辑，比如保存插件本身的业务数据
+         *
          * The method is used to add an plugin observer to the application object.
          * @param observer The observer to add.
          * @returns Return true if successful, else return false.
          */
         addObserver(observer: KApplicationObserver): boolean;
+    
         /**
+         *
+         * 移除酷大师应用观察者
+         *
          * The method is used to remove the plugin observer from the application object.
          * @param observer The observer to remove.
          * @returns Return true if successful, else return false.
@@ -344,6 +412,9 @@ declare global {
         removeObserver(observer: KApplicationObserver): boolean;
     
         /**
+         *
+         * @deprecated 获取酷大师测试帮助器。目前此接口仅用于酷大师 UI 自动化测试，不建议插件开发者使用
+         *
          * Get the utility helper that is only used for testing.
          * @returns The KTestHelper object
          */
@@ -351,6 +422,12 @@ declare global {
     }
 
     /**
+     * 应用观察者用于响应酷大师发出的各种事件
+     *
+     * 目前酷大师只会发出一种事件，就是插件 UI 面板被关闭的事件。
+     *
+     * 插件可以实现此接口，并调用 KApplication.addPluginObserver 方法将观察者注册到酷大师，用于响应酷大师事件
+     *
      * This observer interface is implemented to react to plugin events.
      * To create a new observer, you must define a new class that implements all the methods of the KPluginObserver class.
      * Once you have defined a observer class, you can add it to the application object by the KApplication.addPluginObserver method.
@@ -358,6 +435,9 @@ declare global {
      */
     interface KApplicationObserver {
         /**
+         *
+         * 酷大师关闭插件 UI 面板时，会调用观察者的这个方法
+         *
          * The method is called whenever the plugin is closed.
          * @return
          */
@@ -365,15 +445,27 @@ declare global {
     }
 
     /**
+     *
+     * 本接口代表酷大师的 UI 面板，如工具栏、菜单栏、属性栏等。
+     *
+     * 目前只提供了激活、抑制所有 UI 面板元素的方法
+     *
      * The KApplicationUI contains a number of methods for manipulating the application UI, such as tool bar, menu bar, resource panel, etc.
      */
     interface KApplicationUI {
         /**
+         *
+         * 激活所有 UI 面板元素
+         *
          * Enable tool bar, menu bar, resource panel, etc.
          * @return
          */
         enableAll(): void;
+    
         /**
+         *
+         * 抑制所有 UI 面板元素
+         *
          * Disable tool bar, menu bar, resource panel, etc.
          * @return
          */
@@ -381,24 +473,38 @@ declare global {
     }
 
     /**
+     *
+     * 参考线段对象。即用户在酷大师界面中，用“参考线段”命令画出的各种参考线段、参考圆弧等
+     *
      * The KAuxiliaryBoundedCurve class represents the auxiliary bounded curve.
      * NOTE: Now only the auxiliary line segment and the auxiliary arc are supported.
      */
     interface KAuxiliaryBoundedCurve extends KAuxiliaryCurve {
         /**
+         *
+         * 获取参考线段的几何外形曲线，如直线段、圆弧等
+         *
          * Get the geometric bounded curve corresponding to the bounded curve.
          * NOTE: Now only the line segment and the arc are supported.
          * @returns Return the geometric bounded curve if successful, otherwise return null.
          */
         getBoundedCurve(): KBoundedCurve3d | null;
+    
         /**
+         *
+         * 获取参考线段的起始顶点
+         *
          * Get the auxiliary vertex at the start of the auxiliary bounded curve.
          * NOTE: Even if the auxiliary bounded curve is not connected to other auxiliary bounded curves at the start,
          * we can still get the auxiliary vertex.
          * @returns The auxiliary vertex at the start of the auxiliary bounded curve.
          */
         getStartVertex(): KAuxiliaryVertex;
+    
         /**
+         *
+         * 获取参考线段的终止顶点
+         *
          * Get the auxiliary vertex at the end of the auxiliary bounded curve.
          * NOTE: Even if the auxiliary bounded curve is not connected to other auxiliary bounded curves at the end,
          * we can still get the auxiliary vertex.
@@ -408,10 +514,16 @@ declare global {
     }
 
     /**
+     *
+     * 参考线基类，其派生类有参考直线和参考线段
+     *
      * The base class for all auxiliary curves, such as KAuxiliaryLine and KAuxiliaryBoundedCurve.
      */
     interface KAuxiliaryCurve extends KEntity {
         /**
+         *
+         * 获取参考线的唯一标识符
+         *
          * Get a unique key assigned to an auxiliary curve.
          * @returns The unique key.
          */
@@ -419,10 +531,15 @@ declare global {
     }
 
     /**
+     * 参考线。虽然在画布中只有有限的长度，但它实际上代表了一条无限长的直线
+     *
      * The KAuxiliaryLine class represents the auxiliary line. It is infinite in length.
      */
     interface KAuxiliaryLine extends KAuxiliaryCurve {
         /**
+         *
+         * 获取参考线对象的几何直线表达
+         *
          * Get the geometric 3D line corresponding to the auxiliary line.
          * @returns The geometric 3D line.
          */
@@ -430,6 +547,10 @@ declare global {
     }
 
     /**
+     *
+     * 参考线顶点
+     * 参考线顶点是参考线段的端点。如果两个参考线段是相连的，那么它们共享一个参考线顶点。移动此参考线顶点，会导致相邻的参考线段形状发生改变
+     *
      * The KAuxiliaryVertex class represents the auxiliary vertex.
      * The auxiliary vertex is the connection point between auxiliary bounded curves.
      * Through the auxiliary vertex you can get all auxiliary bounded curves connected through this vertex.
@@ -437,16 +558,27 @@ declare global {
      */
     interface KAuxiliaryVertex extends KEntity{
         /**
+         *
+         * 获取唯一标识符
+         *
          * Get a unique key assigned to an auxiliary vertex.
          * @returns The unique key.
          */
         getKey(): string;
+    
         /**
+         *
+         * 获取参考线顶点的几何点表达
+         *
          * Get the geometric 3D point corresponding to the auxiliary vertex.
          * @returns The geometric 3D point.
          */
         getPoint(): KPoint3d;
+    
         /**
+         *
+         * 获取相邻的参考线段
+         *
          * Get all auxiliary bounded curves connected through this vertex.
          * @returns An array of bounded curves connected through this vertex.
          */
@@ -454,49 +586,87 @@ declare global {
     }
 
     /**
+     *
+     * 相机模式
+     *
      * The KCameraMode class represents the camera modes.
      */
     enum KCameraMode {
         /**
+         *
+         * 2D正交模式。选中一个造型面，即可从选择菜单上进入“2D正交模式”
+         *
          * For2DView mode.
          * Using orthographic view for 2d view.
          */
         For2DView = 0,
+    
         /**
+         *
+         * 透视模式
+         *
          * Perspective view mode.
          */
         Perspective = 1,
+    
         /**
+         *
+         * 正交模式
+         *
          * Orthographic view mode.
          */
         Orthographic = 2,
     }
+    
     /**
+     *
+     * 酷大师相机
+     * 可以将酷大师画布中显示的内容，想象成从一个虚拟的照相机中看到的内容。可阅读任何计算机图形学课程资料，获取关于相机的基础知识。
+     *
      * The KCamera class contains methods for getting the camera information.
      * The camera in KuDaShi is the “point of view” from which you look at the model.
      */
     interface KCamera {
         /**
+         *
+         * 获取相机缩放比例
+         *
          * Get the camera's zoom factor.
          * @returns The camera's zoom factor.
          */
         getZoomFactor(): number;
+    
         /**
+         *
+         * 获取相机模式
+         *
          * Get the camera's mode.
          * @returns The camera's mode.
          */
         getMode(): KCameraMode;
+    
         /**
+         *
+         * 获取相机位置
+         *
          * Get the camera's position.
          * @returns The camera's position.
          */
         getPosition(): KPoint3d;
+    
         /**
+         *
+         * 获取相机的观察点
+         *
          * Get the camera's target, which is the camera is pointing at.
          * @returns The camera's target.
          */
         getTarget(): KPoint3d;
+    
         /**
+         *
+         * 获取相机向上方向
+         *
          * Get the camera's up direction.
          * @returns The camera's up direction.
          */
@@ -505,6 +675,9 @@ declare global {
 
     
     /**
+     *
+     * 布尔类型
+     *
      * The KBooleanType class represents the boolean types.
      */
     enum KBooleanType {
@@ -523,34 +696,62 @@ declare global {
     }
     
     /**
+     *
+     * KDesign 代表酷大师方案数据。从这里我们可以调用酷大师的各种建模命令，如拉伸、扫掠、布尔等，对方案数据进行修改
+     *
      * The KDesign class is the interface to a KuDaShi model, and from here you can use the model-level methods
      * to start getting information and making changes.
      * NOTE: The entity you are operating must be in active definition, or an Error will be shrew.
      */
     interface KDesign {
         /**
+         *
+         * 获取方案 id
+         *
+         * 如果此方案是从酷大师网站的“开始建模”按钮打开的，那它还没有一个方案id。调用此方法会导致此方案保存，并生成一个id
+         *
          * Get the design id.
          * NOTE: If the design has not design id, it will trigger the design to save and generate an id.
          * @returns The design id.
          */
         getDesignId(): HostPromise<string | undefined>;
+    
         /**
+         *
+         * 保存方案
+         *
          * Save the design.
          * NOTE: If the design is not saved, it will trigger the design to save.
          * @returns True if successful, or false.
          */
         save(): HostPromise<boolean>;
+    
         /**
+         *
+         * 获取方案顶层的成组
+         *
          * Get the top group definition.
          * @returns The top group definition.
          */
         getTopGroupDefinition(): KGroupDefinition;
+    
         /**
+         *
+         * 获取当前的活跃成组，即正在编辑的成组
+         *
          * Get the active group definition.
          * @returns The active group definition.
          */
         getActiveGroupDefinition(): KGroupDefinition;
+    
         /**
+         *
+         * 向当前活跃成组中添加造型边
+         * 传入的一组几何点，代表依次相连的一组造型边。这些造型边中如果有封闭的部分，那封闭的区域将自动形成造型面。这些造型面将和场景中原有的面互相分割
+         * 注意：
+         *   1. 传入的所有几何点都必须在一个平面上，否则本方法不起作用，会返回 null
+         *   2. 如果传入的几何点里，最后一个点和第一个点不重合，则会自动在最后一个点和第一个点之间加上一条边
+         *
          * The method is used to add a set of connected edges to the active group definition by the input points.
          * The area surrounded by edges will automatically generate faces, and at the same time, the generated faces will merged with other intersecting faces.
          * NOTE: 1.All the input Points should be on one surface (e.g., a plane), or null will be returned.
@@ -559,7 +760,20 @@ declare global {
          * @returns Return an object that contains added edges if successful, otherwise return null.
          */
         addEdges(points: KPoint3d[]): { addedEdges: KEdge[] } | null;
+    
         /**
+         *
+         * 向当前活跃的成组中添加一组造型面
+         * 添加的造型面，将和现有的造型面互相分割
+         *
+         * 输入的参数是一个点的二维数组。二维数组的每一个元素代表一个面，它自己本身又是一个数组，代表一个面的外轮廓.
+         *
+         * 对组成一个面的点的数组而言，其要求和 addEdges 类似：
+         *   1. 传入的所有几何点都必须在一个平面上，否则不会生成一个面，整个方法也会返回null
+         *   2. 如果传入的几何点里，最后一个点和第一个点不重合，则会自动在最后一个点和第一个点之间加上一条边
+         *
+         * 通常，这个方法用来向酷大师中添加一组网格面
+         *
          * The method is used to add a set of faces to the active group definition by the input points.
          * The generated faces will merged with other intersecting faces.
          * The input parameter is two-dimensional points array. We can make one-dimensional points array to represent a face, and then we
@@ -570,35 +784,59 @@ declare global {
          * @returns Return an object that contains added edges if successful, otherwise return null.
          */
         addFaces(points: KPoint3d[][]): { addedEdges: KEdge[] } | null;
+    
         /**
+         * 向当前成组中加入一条圆弧线段
+         * 如果圆弧线段和现有的某些边围成了一个封闭的面，则会创建出一个新的面。这个新的面会和已有的面互相分割
+         * numSegments 表示这条圆弧线段将由多少段直线段来表达
+         *
          * The method is used to add an arc curve segment to the active group definition.
          * The area surrounded by edges will automatically generate faces, and at the same time, the generated faces will merged with other intersecting faces.
          * @param arc The input arc.
-         * @param numSegments How many segments to draw.
+         * @param numSegments the number of line segments the arc is represented by
          * @returns Return an object that contains added edges which define the arc if successful, otherwise return null.
          */
         addArc(arc: KArc3d, numSegments?: number): { addedEdges: KEdge[] } | null;
+    
         /**
+         * 向当前成组中加入一个整圆围成的面，这个新的面会和已有的面互相分割
+         * numSegments 表示这个圆将由多少段直线段来表达
+         *
          * The method is used to add a circle curve segment to the active group definition.
          * The area surrounded by edges will automatically generate faces, and at the same time, the generated faces will merged with other intersecting faces.
          * @param circle The input circle.
-         * @param numSegments How many segments to draw.
+         * @param numSegments the number of line segments the circle is represented by
          * @returns Return an object that contains added edges which define the circle if successful, otherwise return null.
          */
         addCircle(circle: KCircle3d, numSegments?: number): { addedEdges: KEdge[] } | null;
+    
         /**
+         *
+         * 向当前成组中添加一条参考直线
+         *
          * The method is used to create an auxiliary Line to the active group definition by the input 3D line.
          * @param line The input 3D line.
          * @returns Return an object that contains added auxiliary Line if successful, otherwise return null.
          */
         addAuxiliaryLine(line: KLine3d): { addedAuxiliaryLine: KAuxiliaryLine } | null;
+    
         /**
+         *
+         * 向当前成组中添加一条参考线段。
+         * 如果参考线段是圆弧，则 numSegments 表示这条圆弧线段将由多少段直线段来表达
+         *
          * The method is used to create an auxiliary bounded curve to the active group definition by the input 3D bounded curve.
          * @param line The input 3D bounded curve.
          * @returns Return an object that contains added bounded auxiliary curve if successful, otherwise return null.
          */
         addAuxiliaryBoundedCurve(boundedCurve: KBoundedCurve3d, numSegments?: number): { addedCurve: KAuxiliaryBoundedCurve } | null;
+    
         /**
+         *
+         * 对一个单独的面，在其两条边，edge1 和 edge2 之间，加一个圆弧的倒角
+         * distance 表示倒角圆弧的半径
+         * approxCount 表示这条倒角的圆弧将由多少段直线段来表达
+         *
          * The method is used to create a round corner by the input edges and round distance to the active group definition.
          * @param edge1 The first edge.
          * @param edge2 The second edge.
@@ -607,45 +845,74 @@ declare global {
          * @returns Return an object that contains added edges which define the round corner if successful, otherwise return null.
          */
         addRoundCorner(edge1: KEdge, edge2: KEdge, distance: number, approxCount?: number): { addedEdges: KEdge[] } | null;
+    
         /**
+         *
+         * 从当前成组中删除一条边
+         *
          * The method is used to remove an edge from the active group definition.
          * @param edge The edge to remove.
          * @returns Return an object that contains success flag.
          */
         removeEdge(edge: KEdge): { isSuccess: boolean };
+    
         /**
+         *
+         * 从当前成组中删除一组边
+         * 如果某条边属于一个连续边，则整条连续边都会被删除
+         *
          * The method is used to remove a list of edges from the active group definition.
          * If an edge is in continuous edge group, the whole continuouse edge group will be removed.
          * @param edges The edges to remove.
          * @returns Return an object that contains success flag.
          */
         removeEdges(edges: KEdge[]): { isSuccess: boolean };
+    
         /**
-         * The method is used to merge one collection of faces with another collection of faces.
+         *
+         * 对两组面做布尔并操作
+         *
+         * The method is used to merge (boolean union) one collection of faces with another collection of faces.
          * @param subjects The subject faces to merge with the tool faces.
          * @param tools The tool faces
          * @returns Return an object which contains the modified shells if successful, otherwise return null.
          */
         mergeFaces(subjects: KFace[], tools: KFace[]): { modifiedShells: KShell[] } | null;
+    
         /**
+         *
+         * 删除一组面
+         *
          * The method is used to remove faces from the active group definition.
          * @param faces The faces to remove.
          * @returns Return an object that contains success flag.
          */
         removeFaces(faces: KFace[]): { isSuccess: boolean };
+    
         /**
+         *
+         * 删除参考线
+         *
          * The method is used to remove auxiliary curve from the active group definition.
          * @param auxiliaryCurve The auxiliary curve to remove.
          * @returns Return an object that contains success flag.
          */
         removeAuxiliaryCurve(auxiliaryCurve: KAuxiliaryCurve): { isSuccess: boolean };
+    
         /**
+         *
+         * 删除成组实例
+         *
          * The method is used to remove group instance from the active group definition.
          * @param groupInstance The group instance to remove.
          * @returns Return an object that contains success flag.
          */
         removeGroupInstance(groupInstance: KGroupInstance): { isSuccess: boolean };
+    
         /**
+         *
+         * 使用一组点，打断一条边
+         *
          * The method is used to split an edge into two or more distinct edges by the input points.
          * NOTE: the input points must be points that are on the edge.
          * @param edge The group instance to split.
@@ -653,7 +920,11 @@ declare global {
          * @returns Return an object that contains added edges if successful, otherwise return null.
          */
         splitEdge(edge: KEdge, points: KPoint3d[]): { addedEdges: KEdge[] } | null;
+    
         /**
+         *
+         * 设置一组边的软化信息，true为软化边，false为非软化边
+         *
          * Set the edges to be soft. If you want to set the edge one by one, you can use the setIsSoft method in KEdge.
          * A soft edge will cause the connected faces to be treated as a surface.
          * This means that if you select one face it will also
@@ -663,14 +934,23 @@ declare global {
          * @return Return true if successful, otherwise return false.
          */
         setEdgesSoft(edges: KEdge[], isSoft: boolean): { isSuccess: boolean };
+    
         /**
+         *
+         * @deprecated 酷大师内置的建模命令造出的软化边默认为不可见。请只在代码调试等特殊情况下使用这个 API
+         * 设置一组软化边的可见性，true为可见，false为不可见。
+         *
          * Set the soft edges visibility.
          * @param softEdges The edges to set.
          * @param isVisible The visible value.
          * @return Return true if successful, otherwise return false.
          */
         setSoftEdgesVisible(softEdges: KEdge[], isVisible: boolean): { isSuccess: boolean };
+    
         /**
+         *
+         * 设置一组顶点的软化信息，true为软化顶点，false为非软化顶点
+         *
          * Set the vertex to be soft. If you want to set the vertex one by one, you can use the setIsSoft method in KVertex.
          * A soft vertex will cause the connected edges to be treated as a curve.
          * This means that if you select one edge it will also
@@ -680,21 +960,34 @@ declare global {
          * @return Return true if it is a soft vertex, otherwise return false.
          */
         setVerticesSoft(vertices: KVertex[], isSoft: boolean): { isSuccess: boolean };
+    
         /**
+         *
+         * 移动参考线顶点
+         *
          * The method is used to move the auxiliary vertex to the target position.
          * @param auxiliaryVertex The auxiliary vertex to move.
          * @param targetPosition The target position.
          * @returns Return an object that contains moved auxiliary bounded curves if successful, otherwise return null.
          */
         moveAuxiliaryVertex(auxiliaryVertex: KAuxiliaryVertex, targetPosition: KPoint3d): { movedCurves: KAuxiliaryBoundedCurve[] } | null;
+    
         /**
+         *
+         * 移动参考圆弧的中点 (用起点、中点、终点三点定义圆弧)
+         *
          * The method is used to move the auxiliary middle point to the target position.
          * @param auxiliaryCurve The auxiliary bounded curve to move.
          * @param targetPosition The target position.
          * @returns Return an object that contains success flag.
          */
         moveAuxiliaryMiddlePoint(auxiliaryCurve: KAuxiliaryBoundedCurve, targetPosition: KPoint3d): { isSuccess: boolean };
+    
         /**
+         *
+         * @deprecated 此 API 已过时，请使用transformVertices
+         * 移动一组顶点
+         *
          * The method is used to move the vertices.
          * @param vertices An array of vertices to move.
          * @param moveVectors An array of vectors to apply.
@@ -704,14 +997,24 @@ declare global {
          * @returns Return an object that contains modified shells if successful, otherwise return null.
          */
         moveVertices(vertices: KVertex[], moveVectors: KVector3d[], propagateContinuousEdge?: boolean): { modifiedShells: KShell[] } | null;
+    
         /**
+         *
+         * @deprecated 此 API 已过时，请使用transformVertices
+         * 移动一条边
+         *
          * The method is used to move the edge.
          * @param edge The edge to move.
          * @param moveVector The move vector.
          * @returns Return an object that contains modified shells if successful, otherwise return null.
          */
         moveEdge(edge: KEdge, moveVector: KVector3d): { modifiedShells: KShell[] } | null;
+    
         /**
+         *
+         * @deprecated 此 API 已过时，请使用transformVertices
+         * 移动一个面
+         *
          * The method is used to move the face.
          * @param face The face to move.
          * @param moveVector The move vector.
@@ -719,7 +1022,13 @@ declare global {
          * @returns Return an object that contains modified shells if successful, otherwise return null.
          */
         moveFace(face: KFace, moveVector: KVector3d, loftFlag?: boolean): { modifiedShells: KShell[] } | null;
+    
         /**
+         *
+         * 拉伸命令：推/拉一个面，以创建或修改一个 3D 造型
+         * 如果 copy 为 true，则会保持原始 face 不变，而在推/拉的终止位置新生成一个 face
+         * （相当于在酷大师里手工执行推/拉命令时，按住ctrl键）
+         *
          * The method is used to perform a push/pull on a face.
          * @param face The face to push/pull.
          * @param distance The distance to push/pull the face.
@@ -727,7 +1036,11 @@ declare global {
          * @returns Return an object that contains success flag.
          */
         pullPushFace(face: KFace, distance: number, copy: boolean): { isSuccess: boolean };
+    
         /**
+         *
+         * 扫掠命令：将一个不带洞的平面轮廓（contour），沿一条路径（path），扫掠生成一个 3d 造型（addedShells）
+         *
          * The method is used to create a shape by making the face follow along an array of edges.
          * NOTE: The method will remove the face that the contour belongs to.
          * @param contour The face's contour.
@@ -735,7 +1048,12 @@ declare global {
          * @returns Return an object that contains success flag and added shells.
          */
         sweepFollowEdges(contour: KLoop, path: KEdge[]): { isSuccess: boolean, addedShells: KShell[] };
+    
         /**
+         *
+         * 扫掠命令：将一个不带洞的平面轮廓（contour），沿一条路径（path），扫掠生成一个 3d 造型（addedShells）
+         * 同上，只不过路径可以是一组参考线段
+         *
          * The method is used to create a shape by making the face follow along an array of auxiliary bounded curves.
          * NOTE: The method will remove the face that the contour belongs to.
          * @param contour The face's contour.
@@ -743,7 +1061,13 @@ declare global {
          * @returns Return an object that contains success flag and added shells.
          */
         sweepFollowCurves(contour: KLoop, path: KAuxiliaryBoundedCurve[]): { isSuccess: boolean, addedShells: KShell[] };
+    
         /**
+         *
+         * 将两个成组实例做布尔运算 （交、并、差），生成一个新的成组实例
+         * 输入的两个成组实例 (subject & tool) 必须是实体。即：所有的面围合起来形成一个封闭的实体 (真实世界中能存在的物体)
+         * 从拓扑结构上说，一个实体，里面的每一条造型边，有且仅有两个相邻面
+         *
          * The method is used to make boolean operation of the two group instances.
          * @param subject The subject instance.
          * @param tool The tool instance.
@@ -751,7 +1075,12 @@ declare global {
          * @returns Return an object that contains new instances if successful, otherwise return null.
          */
         boolean(subject: KGroupInstance, tool: KGroupInstance, type: KBooleanType, coplanarFacesUnion?: boolean): { newInstances: KGroupInstance[] } | null;
+    
         /**
+         *
+         * 将造型面的轮廓进行偏移
+         * halfEdge 是进行偏移的基准边，moveVector是偏移的方向，两者共同决定面的轮廓是放大偏移还是缩小偏移
+         *
          * The method is used to offset the contour of the face.
          * NOTE: The moveVector must be perpendicular to the normal of the face and the halfEdge, or null will be returned.
          * @param face The face to offset.
@@ -760,34 +1089,56 @@ declare global {
          * @returns Return an object that contains added edges if successful, otherwise return null.
          */
         offset(face: KFace, halfEdge: KHalfEdge, moveVector: KVector3d): { addedEdges: KEdge[] } | null;
+    
         /**
+         *
+         * 将当前活跃成组里面的所有东西（造型面、成组实例、参考线等）一起旋转/移动/缩放
+         *
          * The method is used to transform the active group definition.
          * @param matrix The transformation matrix.
          * @returns Return an object that contains success flag.
          */
         transformActiveGroupDefinition(matrix: KMatrix4): { isSuccess: boolean };
+    
         /**
+         *
+         * 移动/旋转/缩放 一组造型壳体 （shells）
+         *
          * The method is used to transform the shells.
          * @param shells The shells to transform.
          * @param matrix The transformation matrix.
          * @returns Return an object that contains success flag.
          */
         transformShells(shells: KShell[], matrix: KMatrix4): { isSuccess: boolean };
+    
         /**
+         *
+         * 移动/旋转/缩放 某一个成组实例
+         *
          * The method is used to transform the group instances.
          * @param groupInstances The group instances to transform.
          * @param matrix The transformation matrix.
          * @returns Return an object that contains success flag.
          */
         transformGroupInstances(groupInstances: KGroupInstance[], matrix: KMatrix4): { isSuccess: boolean };
+    
         /**
+         *
+         * 移动/旋转/缩放 一组参考线
+         *
          * The method is used to transform the auxiliary Curves.
          * @param auxiliaryCurves The auxiliary Curves to transform.
          * @param matrix The transformation matrix.
          * @returns Return an object that contains success flag.
          */
         transformAuxiliaryCurves(auxiliaryCurves: KAuxiliaryCurve[], matrix: KMatrix4): { isSuccess: boolean };
+    
         /**
+         *
+         * 拷贝一组造型面
+         * 如果 beCopyToInstance 为 true，则会将拷贝出的造型面加到一个新的成组内，不会与当前成组中现有的造型面发生相交、分割
+         * 如果 beCopyToInstance 为 false，则会将拷贝出的造型面加到当前活跃成组内，它们会与当前成组中现有的造型面发生相交、分割
+         *
          * The method is used to copy the faces.
          * @param faces The faces to copy.
          * @param matrix The transformation matrix. The default value is an identity matrix.
@@ -798,27 +1149,44 @@ declare global {
         copyFaces(faces: KFace[], matrix?: KMatrix4, beCopyToInstance?: boolean): { addedShells: KShell[], addedInstance?: KGroupInstance } | null;
     
         /**
+         *
+         * 拷贝生成一组新的成组实例
+         *
          * The method is used to copy the group instances.
          * @param groupInstances The group instances to copy.
          * @param matrix The transformation matrix. The default value is an identity matrix.
          * @returns Return an object that contains added group instances if successful, otherwise return null.
          */
         copyGroupInstances(groupInstances: KGroupInstance[], matrix?: KMatrix4): { addedInstances: KGroupInstance[] } | null;
+    
         /**
+         *
+         * 拷贝一组成组实例，每一个成组实例，都按照matricesForEachInstance中的一个matrices 数组指定的位姿，拷贝多次
+         * 目前酷大师官方的“外景设计”插件，用这个 API 来实现“随机种树”功能
+         *
          * The method is used to copy each group multile times with different matrices.
          * @param groupInstances The group instances to copy.
          * @param matricesForEachInstance The transformation matrices for each group instance.
          * @returns Return an object that contains added group instances if successful, otherwise return null.
          */
         bulkCopyGroupInstances(groupInstances: KGroupInstance[], matricesForEachInstance: KMatrix4[][]): { addedInstances: KGroupInstance[] } | null;
+    
         /**
+         *
+         * 拷贝一组参考线
+         *
          * The method is used to copy the auxiliary curves.
          * @param auxiliaryCurves The auxiliary curves to copy.
          * @param matrix The transformation matrix. The default value is an identity matrix.
          * @returns Return an object that contains added auxiliary curves if successful, otherwise return null.
          */
         copyAuxiliaryCurves(auxiliaryCurves: KAuxiliaryCurve[], matrix?: KMatrix4): { addedCurves: KAuxiliaryCurve[] } | null;
+    
         /**
+         *
+         * 将一组造型面/成组实例/参考线成组。这将生成一个新的成组定义 （KGroupDefinition）和一个新的成组实例 (KGroupInstance)
+         * 新生成的成组实例就是 addedInstance
+         *
          * The method is used to make the faces, group instances, auxiliary curves to a group.
          * @param faces The faces to make to the group.
          * @param groupInstances The group instances to make to the group.
@@ -826,33 +1194,57 @@ declare global {
          * @returns Return an object that contains the added instance if successful, otherwise return null.
          */
         makeGroup(faces: KFace[], groupInstances: KGroupInstance[], auxiliaryCurves: KAuxiliaryCurve[]): { addedInstance: KGroupInstance } | null;
+    
         /**
+         *
+         * 将一个成组实例解组
+         *
          * The method is used to break the group into individual entities, such as shells, group instances, auxiliary curves.
          * @param groupInstance The group instance to break.
          * @returns Return an object that contains shells, group instances, auxiliary curves if successful, otherwise return null.
          */
         breakGroup(groupInstance: KGroupInstance): { shells: KShell[], groupInstances: KGroupInstance[], auxiliaryCurves: KAuxiliaryCurve[] } | null;
+    
         /**
+         *
+         * 开启一个 undo/redo 的会话
+         * 在一个 startOperation 和一个 commitOperation 之间的所有建模操作，都会被放到一个 undo/redo 步骤中
+         *
          * The method is used to notify KuDaShi that a new operation (which can be undone) is starting.
          * NOTE: If already in operation, an error will be threw.
          * @returns
          */
         startOperation(): void;
+    
         /**
+         *
+         * 提交一个 undo/redo 的会话
+         * 在一个 startOperation 和一个 commitOperation 之间的所有建模操作，都会被放到一个 undo/redo 步骤中
+         *
          * The method is used to commit an operation for undo.
          * It is normally called at the end of a method to commit the operation that the method performs.
          * NOTE: If not in operation, an error will be threw.
          * @returns
          */
         commitOperation(): void;
+    
         /**
+         *
+         * 提前终止一个 undo/redo 的会话
+         * 在一个 startOperation 和一个 abortOperation 之间的所有建模操作，都会被 undo 掉，并不会被放到一个 undo/redo 步骤中
+         *
          * The method is used to abort the current operation started with the startOperation method.
          * It is normally called from inside of a rescue clause to cancel an operation if something goes wrong.
          * NOTE: If not in operation, an error will be threw.
          * @returns
          */
         abortOperation(): void;
+    
         /**
+         *
+         * 用一组 toolFaces 去分割一组 sourceFaces
+         * toolFaces 和 sourceFaces 都必须在当前活跃的成组中
+         *
          * The method is used to split the source faces by the tool faces.
          * NOTE: source faces and tool faces must be both in the active group definition.
          * @param sourceFaces The faces to be split.
@@ -860,7 +1252,12 @@ declare global {
          * @returns Return an object that contains the changed shells if successful, otherwise return null.
          */
         faceSplitByFace(sourceFaces: KFace[], toolFaces: KFace[]): { modifiedShells: KShell[] } | null;
+    
         /**
+         *
+         * 用一个 tool 成组实例里包含的造型面，去分割 sourceFaces
+         * tool 成组实例和 sourceFaces 都必须在当前活跃的成组中
+         *
          * The method is used to split the source faces by group instance.
          * NOTE: the source faces and the group instance must be both in the active group definition.
          * @param sourceFaces The faces to be split.
@@ -868,18 +1265,33 @@ declare global {
          * @returns Return an object that contains the changed shells if successful, otherwise return null.
          */
         faceSplitByGroup(sourceFaces: KFace[], tool: KGroupInstance): { modifiedShells: KShell[] } | null;
+    
         /**
+         *
+         * 从一个网格数据，生成一个造型壳体 (shell)
+         * 目前这个 API 被用于酷大师官方插件“外景设计”中的“地形生成”功能
+         *
          * The method is used to create a continuous shell from a mesh
          * @param mesh The input mesh.
          * @returns Return an object that contains new shell information if successful, otherwise return null.
          */
         createShellFromMesh(mesh: KMesh): { newShell: KShell } | null;
+    
         /**
+         *
+         * 创建一个空的成组实例
+         *
          * The method is used to create empty group instance.
          * @returns Return an object that contains added instance if successful, otherwise return null.
          */
         createEmptyGroupInstance(): { addedInstance: KGroupInstance } | null;
+    
         /**
+         *
+         * 激活一个成组实例。
+         * 激活后的成组实例的组定义（KGroupDefinition），即成为当前的活跃成组 (KDesign.getActiveGroupDefinition 的返回值)
+         * 这相当于酷大师用户界面上的“进入组编辑”功能
+         *
          * The method is used to activate the group instance.
          * When we activate the input group instance, the groupDefinition got by the KDesign.getActiveGroupDefinition method is the group definition
          * for this input group instance, so anything we do is to edit it.
@@ -888,12 +1300,22 @@ declare global {
          * @returns Return an object that contains success flag.
          */
         activateGroupInstance(groupInstance: KGroupInstance): HostPromise<{ isSuccess: boolean }>;
+    
         /**
+         *
+         * 反激活一个成组实例
+         * 这相当于酷大师用户界面上的“退出组编辑”功能
+         *
          * The method is used to deactivate the final group instance in the activated instance path.
          * @returns Return an object that contains success flag.
          */
         deactivateGroupInstance(): { isSuccess: boolean };
+    
         /**
+         *
+         * 为一个插件外部模型生成一个成组实例
+         * resourceId 是外部模型唯一标识符。可阅读《酷大师插件开发教程》中的《酷大师插件官方定义消息》部分
+         *
          * The method is used to create the group instance from external resources.
          * The type of the group definition for this group instance is Xref.
          * @param resourceId The resource id, the resource is used to create group instances.
@@ -902,17 +1324,32 @@ declare global {
          * @returns Return an object that contains new instances if successful, otherwise return null.
          */
         createInstanceFromExternalResources(resourceId: string, box: KBoundingBox3d, pluginId?: string): HostPromise<{ newInstance: KGroupInstance } | null>;
+    
         /**
+         *
+         * 获取当前处于组编辑状态的成组实例的路径 （从顶层成组一直到当前激活成组实例的路径，路径中的每一个元素都是一个KGroupInstance）
+         *
          * The method is used to get the path of the editing group instance.
          * @returns Return the path of the editing group instance, return empty path if the root group definition is editing.
          */
         getEditPath(): KGroupInstance[];
+    
         /**
+         *
+         * @deprecated 此 API 仅供酷大师内部开发团队使用
+         * 加载一个材质，材质id为酷大师内部材质库的材质id
+         *
          * Load and cache the material if it is first time used.
          * @param materialId The id of the material.
          */
         loadMaterial(materialId: string): HostPromise<{ isSuccess: boolean }>;
+    
         /**
+         *
+         * @deprecated  此 API 仅供酷大师内部开发团队使用
+         * 给一组面赋材质
+         * 可通过originVertexs 和 vertexUVs 来指定材质铺贴的uv
+         *
          * The method is used to assign material for a group of faces.
          * @param faces the faces to be assigned material
          * @param materialId material id
@@ -924,6 +1361,10 @@ declare global {
         assignMaterialForFaces(faces: KFace[], materialId: string, bgId?: string, originVertexs?: KVertex[], vertUVs?: KPoint2d[]): boolean;
     
         /**
+         *
+         * @deprecated  此 API 仅供酷大师内部开发团队使用
+         * 给一个成组实例赋材质
+         *
          * The method is used to assign material for group instance.
          * @param groupInstance the group instance to be assigned material
          * @param materialId material id
@@ -933,6 +1374,10 @@ declare global {
         assignMaterialForGroupInstance(groupInstance: KGroupInstance, materialId: string, bgId?: string): boolean;
     
         /**
+         *
+         * 对一组造型边做 3D 倒角
+         * stripCount是倒角圆弧轮廓的分段数
+         * smoothTransit 为true时，在三边交汇处会做圆滑过渡
          *
          * @param edges the edges to be fillet
          * @param radiuses radiuses for each edges
@@ -941,7 +1386,10 @@ declare global {
          * @returns Return an object that contains a map of the input edges and the resulted corner faces, otherwise return null.
          */
         fillet(edges: KEdge[], radiuses: number[], stripeCount: number, smoothTransit?: boolean): { edgeFacesMap: Map<KEdge, KFace[]> } | null
+    
         /**
+         *
+         * 平移/旋转/缩放 一组造型顶点。与这些造型顶点相连的造型边/造型面也会一起移动
          *
          * @param vertices vertices to be transformed
          * @param matrix  transform matrix
@@ -953,6 +1401,8 @@ declare global {
 
     
     /**
+     * @deprecated 本接口即将下线
+     *
      * The KContinuousEdgeGroup class is used by KuDaShi to unite a series of KEdge objects into one continuous edge group, which represents a conceptual curve.
      * Since KuDaShi is a surface modeler, all circles, arcs, and arbitrary curves are really just edges that are bound together in sequence.
      */
@@ -969,47 +1419,74 @@ declare global {
     }
     
     /**
+     * 酷大师图形实体：造型边
+     * 它对应于一个Brep数据结构的边（Edge）
+     *
      * The KEdge class represents the BRep edge.
-     * Since KuDaShi is a surface modeler, all circles, arcs, and arbitrary curves are really just edges that are bound together in sequence.
-     * So you can think of all circles, arcs, and arbitrary curves as conceptual curve.
-     * If one edge are united into one conceptual curve, it is a soft edge.
+     *
      */
     interface KEdge extends KTopoEdge, KEntity {
         /**
+         *
+         * 获取图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type which is KTopoType
          */
         getType(): KTopoType;
+    
         /**
+         *
+         * 获取所从属的壳体
+         *
          * Retrieve the shell that the edge belongs to.
          * @returns The shell if successful, otherwise null.
          */
         getShell(): KShell | null;
+    
         /**
+         *
+         * 获取对应的半边
+         *
          * Retrieve all the involved half edges of this edge.
          * @return The array of half edges.
          */
         getHalfEdges(): KHalfEdge[];
+    
         /**
+         *
+         * 获取起始顶点
+         *
          * Retrieve edge's start vertex.
          * @return The start vertex if successful, otherwise null.
          */
         getVertexA(): KVertex | null;
+    
         /**
+         *
+         * 获取终止顶点
+         *
          * Retrieve edge's end vertex.
          * @return The end vertex if successful, otherwise null.
          */
         getVertexB(): KVertex | null;
+    
         /**
-         * Set the edge to be soft.
-         * A soft edge will cause the connected faces to be treated as a surface.
-         * This means that if you select one face it will also
-         * select all faces connected with soft edges. A soft edge will also appear hidden.
+         *
+         * 设置为这条边是否为软化边
+         * 软化边默认在酷大师画布中不显示
+         * 当在酷大师中选择一个造型面时，会将从这个面开始，所有通过软化边相连的面一起选中
+         *
+         * Set the edge to be soft. A soft edge is invisible in viewport by default
+         * When selelcting a face, all faces that connected with soft edges will be selected together
+         *
          * @param isSoft The soft value.
          * @return Return true if successful, otherwise return false.
          */
         setIsSoft(isSoft: boolean): boolean;
+    
         /**
+         * @deprecated 本方法即将下线，请不要使用
          * Retrieve the continuous edge group which the edge belongs to.
          * @return The continuous edge group if successful, otherwise null.
          */
@@ -1018,6 +1495,9 @@ declare global {
 
     
     /**
+     *
+     * 酷大师应用图形实体类型
+     *
      * The KEntityType class represents entity types.
      */
     enum KAppEntityType {
@@ -1039,15 +1519,25 @@ declare global {
         AuxiliaryVertex = 'auxiliaryVertex',
     }
     
+    /**
+     * 酷大师图形实体类型
+     */
     type KEntityType = KTopoType | KAppEntityType;
     // https://github.com/microsoft/TypeScript/issues/17592
     const KEntityType = {...KTopoType, ...KAppEntityType};
     
     /**
+     * 酷大师图形实体的基类
+     * 造型面、造型边、造型顶点、参考线、参考线段、参考线顶点、成组实例等统称酷大师图元。
+     * 可阅读《酷大师基本概念》第二节，“酷大师图形实体”，获取更多信息
+     *
      * The KEntity class is the base class for all KuDaShi entities. Entities are basically anything that can be contained in a model.
      */
     interface KEntity {
         /**
+         *
+         * 获取图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type.
          */
@@ -1056,6 +1546,7 @@ declare global {
 
     
     /**
+     * @deprecated 本接口即将下线，请不要使用
      * The KContinuousFaceGroup class is used by KuDaShi to unite a series of KFace objects into one continuous face group, which represents a conceptual surface.
      * Since KuDaShi is a surface modeler, all surfaces are really just faces that are bound together in sequence.
      */
@@ -1066,49 +1557,79 @@ declare global {
         readonly faces: KFace[];
     }
     /**
+     *
+     * 酷大师图形实体：造型面
+     * 它对应于一个Brep数据结构的面 (Face)
+     *
      * The KFace class represents the BRep face.
-     * Since KuDaShi is a surface modeler, all surfaces are really just faces that are bound together in sequence.
-     * So you can think of all surfaces as conceptual surfaces.
      */
     interface KFace extends KEntity, KTopoFace {
         /**
+         *
+         * 获取图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type.
          */
         getType(): KTopoType;
     
         /**
+         *
+         * 获取所从属的壳体
+         *
          * Get the shell that the face belongs to.
          * @returns The shell if successful, otherwise null.
          */
         getShell(): KShell | null;
+    
         /**
+         *
+         * 获取所有包含的边
+         *
          * Retrieve all the involved edges of this face.
          * @return The array of edges.
          */
         getEdges(): KEdge[];
+    
         /**
+         *
+         * 获取所有包含的顶点
+         *
          * Retrieve all the involved vertices of this face.
          * @return The array of vertices.
          */
         getVertices(): KVertex[];
+    
         /**
+         *
+         * 获取所有包含的半边
+         *
          * Retrieve all the involved half edges of this face.
          * @return The array of half edges.
          */
         getHalfEdges(): KHalfEdge[];
+    
         /**
+         *
+         * 获取所含的外环
+         *
          * Retrieve face's outer loop.
          * @return The outer loop if successful, otherwise null.
          */
         getOuterLoop(): KLoop | null;
+    
         /**
+         *
+         * 获取所含的内环
+         *
          * Retrieve face's inner loops.
          * @return The inner loops.
          */
         getInnerLoops(): KLoop[];
     
         /**
+         * @deprecated 该接口即将下线
+         *
          * Retrieve the continuous face which the face belongs to.
          * @return The continuous face if successful, otherwise null.
          */
@@ -1117,15 +1638,25 @@ declare global {
 
     
     /**
+     *
+     * 组定义的类型
+     *
      * The KGroupDefinitionType class represents group definition types.
      */
     enum KGroupDefinitionType {
         /**
+         *
+         * 原生成组
+         *
          * Native Type.
          * It means the definition is constructed in KuDaShi, you can edit the definition in KuDaShi.
          */
         Native = 'native',
+    
         /**
+         *
+         * 外部模型
+         *
          * Xref Type.
          * It means the definition is constructed by other applications or services, such as smart 3d text, etc.
          * You can not change the xref definition.
@@ -1134,9 +1665,20 @@ declare global {
     }
     
     /**
+     *
+     * 组定义
+     *
+     * 组定义用来定义一个成组里面的内容。一个成组里面可包括一组酷大师图形实体，如造型面、参考线、参考线段、子级的成组实例等
+     * 例如，我们可以画一个茶杯，把它做成一个成组(组定义)。然后为它创建6个实例，围绕在一张桌子的周围
+     * 注意，在酷大师图形界面里使用“成组”的命令，会创建一个成组的组定义，并同时创建一个成组的组实例。我们在画布中看到的对象，其实是组实例。
+     * 在酷大师图形界面里编辑一个“成组”，实际上是在编辑它的组定义。对组定义的修改，会应用到它所有的组实例上。因此，所有的组实例的外观在组定义修改后，都会变化。
+     * 酷大师的组定义可以有两种类型，原生成组和外部模型
+     * 在酷大师里用“成组”命令创建的，或用KDesign.makeGroup这个API创建的成组都属于原生成组。我们可以在酷大师里编辑原生成组的组定义内容（即进行“组编辑”）
+     * 外部模型是由外部的应用（体现为一个酷大师插件）插入到酷大师方案中的，例如酷大师官方插件中的“智能模型”。外部模型的组定义只能由创建它的外部应用，即酷大师插件来编辑。
+     *
      * The KGroupDefinition class is used to define the contents for a KuDaShi group instance.
      * The group definition is a collection of entities that can be instanced and reused multiple times throughout a KuDaShi model.
-     * For example, you could draw a tea-cup once, turn it into a group instance, and then use 6 instances of it to surround a tea table.
+     * For example, you could draw a tea-cup once, turn it into a group definition, and then use 6 instances of it to surround a tea table.
      * Editing to the original “definition” will then propagate across all of its instances.
      * The KGroupDefinition class contains sub group instances, shells and auxiliary curves, etc. The group definition has two types, native and xref.
      * The native type means the definition is constructed in KuDaShi, you can edit the definition in KuDaShi.
@@ -1146,16 +1688,27 @@ declare global {
      */
     interface KGroupDefinition {
         /**
+         *
+         * 获取成组的类型
+         *
          * Get the group definition's type.
          * @returns The group definition's type.
          */
         getType(): KGroupDefinitionType;
+    
         /**
+         *
+         * 获取成组的唯一标识符
+         *
          * Get a unique key assigned to a group definition.
          * @returns The unique key.
          */
         getKey(): string;
+    
         /**
+         *
+         * 通过酷大师图形实体的唯一标识符，查找一个酷大师图形实体
+         *
          * The method is used to find and return the entity by its unique key.
          * NOTE: 1.Only supports to find by face, group instance and auxiliary curve's keys.
          * 2. Can only find the entity in the current definition, not recursive.
@@ -1163,7 +1716,14 @@ declare global {
          * @returns The found entity if successful, otherwise null.
          */
         findEntity(key: string): KEntity | null;
+    
         /**
+         *
+         * 使用酷大师图形实体的唯一标识符，来匹配一个酷大师图形实体
+         * 这个 API 和上面的 findEntity 的不同点在于，这里用来查找的key，可以是一个老的 key，不一定是现有的图形实体的 key
+         * 例如，在一个矩形的造型面上添加了一条边，将其分割成两个面。那么，用一个老的造型面的key，就可以匹配到两个新的造型面
+         * 目前，这种匹配功能只支持造型面和造型边。且只支持当前组定义所直接包含的造型面和造型边的匹配，不包含其子级成组实例里面引用的造型面和造型边
+         *
          * Find the surviviors of the old entity after model modification.
          * Note: 1. only support face and edge for now.
          *       2. only can find the entities in the current definition, not recursive.
@@ -1171,32 +1731,58 @@ declare global {
          * @returns The survivor entities of the old entity. If the old entity was not modified, then itself will be returned.
          */
         matchEntities(key: string): KEntity[];
+    
         /**
+         *
+         * 获取子级的成组实例
+         *
          * Get all the sub group instances in this group definition.
          * @returns An array of sub group instances in this group definition.
          */
         getSubGroupInstances(): KGroupInstance[];
+    
         /**
+         *
+         * 获取组定义里直接包含的造型壳体
+         *
          * Get all the shells in this group definition.
          * @returns An array of shells in this group definition.
          */
         getShells(): KShell[];
+    
         /**
+         *
+         * 获取参考线
+         *
          * Get all the auxiliary curves in this group definition.
          * @returns An array of auxiliary curves in this group definition.
          */
         getAuxiliaryCurves(): KAuxiliaryCurve[];
+    
         /**
+         *
+         * 获取酷大师方案中，所有应用本成组定义的成组实例
+         *
          * Get all the instances of this group definition.
          * @returns An array of instances of this group definition.
          */
         getAllReferenceGroupInstances(): KGroupInstance[];
+    
         /**
+         *
+         * 检查本成组定义是否处于快速模式
+         * 快速模式是成组的一种特殊显示模式。在这种模式下，我们不会在酷大师画布中加载成组的Brep数据，而只会加载它的三角网格数据。
+         * 这样可以大大减轻内存的压力，从而使酷大师打开更大的方案
+         *
          * Check whether the group definition is in express mode.
          * @returns A flag to indicate whether the group definition is in express mode.
          */
         isInExpressMode(): boolean;
+    
         /**
+         *
+         * 获取本成组定义的外包围盒
+         *
          * Get the bounding box of this group definition.
          * @returns The bounding box.
          */
@@ -1204,27 +1790,48 @@ declare global {
     }
 
     /**
+     *
+     * 组实例
+     *
+     * 组实例用来表达一个成组的实例。可以把“组定义”看成面向对象编程中的“类”，而“组实例”看成面向对象编程中的“对象”
+     * 组实例会包含一个对组定义的应用，然后包含一个齐次变换矩阵，用来表达它在酷大师 3D 场景中的位姿
+     *
      * The KGroupInstance class is used to represent group instances of a group definition.
      * Therefore, the KGroupInstance class contains a reference to a corresponding KGroupDefinition object
      * and a Transformation object (which contains the location of the group instance in the Drawing Window).
      */
     interface KGroupInstance extends KEntity {
         /**
+         *
+         * 获取唯一标识符
+         *
          * Get a unique key assigned to a group instance.
          * @returns The unique key.
          */
         getKey(): string;
+    
         /**
+         *
+         * 获取组定义
+         *
          * Get the group definition for this group instance.
          * @returns The group definition if successful, else false.
          */
         getGroupDefinition(): KGroupDefinition | null;
+    
         /**
+         *
+         * 获取齐次变换矩阵。此矩阵用于表达组实例在酷大师 3D 场景中的位姿
+         *
          * Get the transformation matrix of this group instance.
          * @returns The transformation matrix.
          */
         getTransform(): KMatrix4;
+    
         /**
+         *
+         * 获取组实例的外包围盒
+         *
          * Get the bounding box of this group instance.
          * @returns The bounding box.
          */
@@ -1232,51 +1839,90 @@ declare global {
     }
 
     /**
+     *
+     * 半边
+     *
+     * 半边不是一个可以独立存在的酷大师图形实体。它对应于一个Brep数据结构的半边（HalfEdge）。它从属于酷大师图形实体中的面和边
+     *
      * The KHalfEdge class represents the BRep half edge.
      */
     interface KHalfEdge extends KEntity, KTopoHalfEdge {
         /**
+         *
+         * 获取图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type.
          */
         getType(): KTopoType;
     
         /**
+         *
+         * 获取所从属的造型边
+         *
          * Get the edge that the half edge belongs to.
          * @returns The edge if successful, otherwise null.
          */
         getEdge(): KEdge | null;
+    
         /**
+         *
+         * 获取所从属的环
+         *
          * Get the loop that the half edge belongs to.
          * @returns The loop if successful, otherwise null.
          */
         getLoop(): KLoop | null;
+    
         /**
+         *
+         * 获取所从属的壳体
+         *
          * Get the shell that the half edge belongs to.
          * @returns The shell if successful, otherwise null.
          */
         getShell(): KShell | null;
+    
         /**
+         *
+         * 获取环中的下一个半边
+         *
          * Get this half edge's next half edge in the loop.
          * @return The next half edge if successful, otherwise null.
          */
         getNext(): KHalfEdge | null;
+    
         /**
+         *
+         * 获取环中的上一个半边
+         *
          * Get this half edge's previous half edge in the loop.
          * @return The previous half edge if successful, otherwise null.
          */
         getPrev(): KHalfEdge | null;
+    
         /**
+         *
+         * 获取半边的起点
+         *
          * Get this half edge's start vertex.
          * @return The start vertex if successful, otherwise null.
          */
         getVertexA(): KVertex | null;
+    
         /**
+         *
+         * 获取半边的终点
+         *
          * Get this half edge's end vertex.
          * @return The end vertex if successful, otherwise null.
          */
         getVertexB(): KVertex | null;
+    
         /**
+         *
+         * 获取半边的方向是否和边的方向相反。如果相反，返回 true；否则返回 false
+         *
          * Check whether the half edge is reversed to its edge.
          * @return true if reversed, false if the orientations are same.
          */
@@ -1284,36 +1930,62 @@ declare global {
     }
 
     /**
+     *
+     * 酷大师键盘事件
+     *
      * The KKeyBoardEvent class describes a user interaction with the keyboard.
      * It is similar to the KeyBoardEvent class in Web APIs.
      */
     interface KKeyBoardEvent {
         /**
+         *
+         * 获取按键的名称
+         *
          * Get the value of the key pressed by the user.
          * @returns
          */
         getKey(): string;
+    
         /**
+         *
+         * 获取按键的编码
+         *
          * Get a physical key on the keyboard.
          * @returns
          */
         getCode(): string;
+    
         /**
+         *
+         * 判断是否是 ctrl 键
+         *
          * Get a Boolean that indicates if the control key was pressed (true) or not (false) when the event occurred.
          * @returns True if the control key was pressed, else false.
          */
         ctrlKey(): boolean;
+    
         /**
+         *
+         * 判断是否是 alt 键
+         *
          * Get a Boolean that indicates if the alt key was pressed (true) or not (false) when the event occurred.
          * @returns True if the alt key was pressed, else false.
          */
         altKey(): boolean;
+    
         /**
+         *
+         * 判断是否是复合按键
+         *
          * Get a Boolean value indicating if the event is fired within a composition session.
          * @returns True if within a composition session, else false.
          */
         isComposing(): boolean;
+    
         /**
+         *
+         * 判断是否是 shift 键
+         *
          * Get a Boolean that indicates if the shift key was pressed (true) or not (false) when the event occurred.
          * @returns True if the shift key was pressed, else false.
          */
@@ -1321,26 +1993,53 @@ declare global {
     }
 
     /**
+     *
+     * 环
+     *
+     * 环不是一个可以独立存在的酷大师图形实体。它对应于一个Brep数据结构的环（Loop）。它从属于酷大师图形实体中的面
+     *
      * The KLoop class represents the BRep loop.
      */
     interface KLoop extends KEntity, KTopoLoop {
         /**
+         *
+         * 获取图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type.
          */
          getType(): KTopoType;
+    
         /**
+         *
+         * 获取所从属的面
+         *
          * Get the face that the loop belongs to.
          * @returns The face if successful, otherwise null.
          */
         getFace(): KFace | null;
+    
         /**
+         *
+         * 获取所包含的半边
+         *
          * Get all the involved half edges of this loop.
          * @return The array of half edges.
          */
         getHalfEdges(): KHalfEdge[];
     }
 
+    /**
+     *
+     * 网格面
+     *
+     * 定义了一个网格面数据结构
+     * vertices 数组里面的每一个元素代表一个网格面的顶点。这个元素自身是一个数组，包含三个数字，分别代表顶点的 X， Y， Z 坐标
+     * tirangleIndices 数组里面的每一个元素代表一个三角形。这个元素自身是一个数组，包含三个数字，分别代表组成三角形的顶点在vertices数组里的下标
+     * softEdges 数组里面的每一个元素代表一条边。这个元素自身是一个数组，包含两个数字，分别代表组成这个边的顶点在vertices数组里的下标。
+     * 所有在 softEdges 数组里面的边，都会被设置为软化边
+     *
+     */
     interface KMesh {
         vertices: number[][];
         triangleIndices: number[][];
@@ -1348,16 +2047,26 @@ declare global {
     }
 
     /**
+     *
+     * 酷大师鼠标事件
+     *
      * The KMouseEvent class describes a user interaction with the mouse.
      * It is similar to the MouseEvent class in Web APIs.
      */
     interface KMouseEvent {
         /**
+         *
+         * 获取 client 窗口中的 X 坐标
+         *
          * Get the horizontal position of the mouse event on the client window of user's screen.
          * @returns
          */
         clientX(): number;
+    
         /**
+         *
+         * 获取 client 窗口中的 Y 坐标
+         *
          * Get the vertical position of the mouse event on the client window of the user's screen.
          * @returns
          */
@@ -1366,54 +2075,92 @@ declare global {
 
     
     /**
+     *
+     * 框选类型
+     *
      * The KPickType class represents pick types.
      */
     enum KPickType {
         /**
+         *
+         * 包含选中。框选时，所有被包含在框里面的图形实体才会被选中
+         *
          * Pick Inside Type.
          */
         PickInside = 'pick_inside',
+    
         /**
+         *
+         * 交叉选中。框选时，所有被选择框交叉到的图形实体就会被选中
+         *
          * Pick Crossing Type.
          */
         PickCrossing = 'pick_crossing'
     }
+    
     /**
+     *
+     * 选择设置
+     *
      * The KPickSetting class represents the pick settings.
      */
     interface KPickSetting {
         /**
+         *
+         * 选择操作类型（仅用于框选）
+         *
          * The pick type. Default is PickCrossing.
          * NOTE: It is only used when picking by rectangle.
          */
         pickType?: KPickType;
+    
         /**
+         *
+         * 可被选择的图形实体类型。默认情况下，所有图形实体都会被选中
+         *
          * The pickable entity type. Default is that all types are pickable.
          */
         pickableEntityType?: KEntityType[];
     }
     
     /**
+     *
+     * 点选结果
+     *
      * The KPointPickResult class represents the point pick result.
      */
     interface KPointPickResult {
         /**
+         *
+         * 获取选中的图形实体的数量
+         *
          * Get the size of all the picked entities.
          * @return The size of all the picked entities.
          */
         getSize(): number;
+    
         /**
+         * 获取选中的所有图形实体
+         *
          * Get all the picked entities.
          * NOTE: The picked entities are arranged from near to far.
          * @return All the picked entities.
          */
         getAllPicked(): KEntity[];
+    
         /**
+         *
+         * 获取在被选中的图形实体中，排在最前面的那一个实体（第 0 号元素）
+         *
          * Get the front picked entity.
          * @return The front picked entity.
          */
         getFrontPicked(): KEntity | null;
+    
         /**
+         *
+         * 获取在被选中的图形实体中，排在最前面的那一个实体的被选中的 3D 点
+         *
          * Get the front picked point.
          * @return The front picked point.
          */
@@ -1421,15 +2168,25 @@ declare global {
     }
     
     /**
+     *
+     * 框选结果
+     *
      * The KRectPickResult class represents the rect pick result.
      */
     interface KRectPickResult {
         /**
+         *
+         * 获取选中的图形实体的数量
+         *
          * Get the size of all the picked entities.
          * @return The size of all the picked entities.
          */
         getSize(): number;
+    
         /**
+         *
+         * 获取选中的所有图形实体
+         *
          * Get all the picked entities.
          * @return All the picked entities.
          */
@@ -1437,10 +2194,16 @@ declare global {
     }
     
     /**
+     *
+     * 选择帮助器
+     *
      * The KPickHelper class is used to pick entities.
      */
     interface KPickHelper {
         /**
+         *
+         * 点选。 使用一个 client 窗口的 x，y 坐标来做选择
+         *
          * The method is used to pick by point.
          * @param x X screen coordinate for the pick.
          * @param y Y screen coordinate for the pick.
@@ -1448,7 +2211,11 @@ declare global {
          * @return The result of point pick.
          */
         pickByPoint(x: number, y: number, pickSetting?: KPickSetting): KPointPickResult;
+    
         /**
+         *
+         * 框选。 使用一个 client 窗口的 2d 矩形来做选择
+         *
          * The method is used to pick by rectangle.
          * @param startPoint First screen coordinate point.
          * @param endPoint Second screen coordinate point.
@@ -1460,6 +2227,16 @@ declare global {
 
     
     /**
+     *
+     * 酷大师选择集
+     *
+     * 代表在当前酷大师画布中选中的一组图形实体
+     *
+     * 注意：
+     * 1.酷大师选择集中的图形实体的顺序是不固定的，因此，不要依赖于选择集中的图形实体的顺序去写业务逻辑
+     * 2.酷大师选择集中只会包含酷大师图形实体类型，如KEntityType.Edge, KEntityType.Face等
+     *
+     *
      * The KSelection represents a set of the currently selected entities.
      * Use the app.selection method to get a selection object.
      * NOTE: 1.The order of entities in the set is in no particular order and should not be assumed to be
@@ -1470,12 +2247,18 @@ declare global {
      */
     interface KSelection {
         /**
+         * 获取选择集中所有的图形实体
+         *
          * Get all the entities in the selection.
          * NOTE: Only the entities of supported types are returned.
          * @return All the entities in the selection.
          */
         getAllEntities(): KEntity[];
+    
         /**
+         *
+         * 在选择集中添加图形实体
+         *
          * Add entities to the selection.
          * NOTE: If the entity belongs to one conceptual curve or surface,
          * all the edges or faces that make up the conceptual curve or surface will be added to the selection automatically.
@@ -1483,7 +2266,11 @@ declare global {
          * @returns Return true if successful, else return false.
          */
         add(entities: KEntity[]): boolean;
+    
         /**
+         *
+         * 从选择集中移除图形实体
+         *
          * Remove entities from the selection.
          * NOTE: If the entity belongs to one conceptual curve or surface,
          * all the edges or faces that make up the conceptual curve or surface will be removed from the selection automatically.
@@ -1491,18 +2278,30 @@ declare global {
          * @returns Return true if successful, else return false.
          */
         remove(entities: KEntity[]): boolean;
+    
         /**
+         *
+         * 清空选择集
+         *
          * Clear the selection.
          * @returns Return true if successful, else return false.
          */
         clear(): boolean;
+    
         /**
+         *
+         * 添加选择集观察者
+         *
          * The method is used to add an observer to the selection object.
          * @param observer The observer to add.
          * @returns Return true if successful, else return false.
          */
         addObserver(observer: KSelectionObserver): boolean;
+    
         /**
+         *
+         * 移除选择集观察者
+         *
          * The method is used to remove an observer from the selection object.
          * @param observer The observer to remove.
          * @returns Return true if successful, else return false.
@@ -1511,6 +2310,11 @@ declare global {
     }
 
     /**
+     *
+     * 选择集观察者
+     *
+     * 此观察者接口用于接收酷大师选择集的变化事件
+     *
      * This observer interface is implemented to react to selection events.
      * To create a new observer, you must define a new class that implements all the methods of the KSelectionObserver class.
      * Once you have defined a observer class, you can add it to the selection object by the KSelection.addObserver method.
@@ -1518,6 +2322,9 @@ declare global {
      */
     interface KSelectionObserver {
         /**
+         *
+         * 当酷大师选择集发生变化时，酷大师会调用这个接口
+         *
          * The method is called whenever items are added or removed from the selection object.
          * @return
          */
@@ -1525,20 +2332,39 @@ declare global {
     }
 
     /**
+     *
+     * 壳体
+     *
+     * 壳体是一组面的集合。它代表一个 Brep 数据结构的壳体（Shell）
+     *
+     * 酷大师会尽最大可能将相互连接的面放置在一个壳体中。
+     * 但这并不永远成立，有可能一个壳体会包含一些互不相连的面。插件开发者最好不要依赖于这一假设来写业务逻辑
+     *
      * The KShell class represents the BRep shell.
      */
     interface KShell extends KEntity, KTopoShell {
         /**
+         *
+         * 获取酷大师图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type.
          */
          getType(): KTopoType;
+    
         /**
+         *
+         * 获取所包含的面
+         *
          * Retrieve all the involved Faces of this Shell.
          * @return The array of Faces.
          */
          getFaces(): KFace[];
+    
          /**
+          *
+          * 获取所包含的边
+          *
           * Retrieve all the involved Edges of this Shell.
           * @return The array of Edges.
           */
@@ -1546,7 +2372,12 @@ declare global {
     }
 
     /**
+     * @deprecated 酷大师测试帮助器
+     *
+     * 插件开发者不应使用这一接口
+     *
      * The KTestHelper class contains some utilities that are only used for testing.
+     * Plugin developers shouldn't use this interface for it plugin development, as it would rapidly change and might also be removed later
      */
     interface KTestHelper {
         /**
@@ -1563,63 +2394,104 @@ declare global {
     
         /**
          * @private used for automation test only!! execute test command.
-         * @param cmd 
+         * @param cmd
          */
         executeCmd(cmd: string): HostPromise<boolean>;
     }
 
     /**
+     *
+     * 信息提示选项
+     *
      * The KToastOption class represents the toast option.
      */
     interface KToastOption {
         /**
+         *
+         * 信息提示内容
+         *
          * The toast prompt content.
          */
         content: string,
+    
         /**
+         *
+         * 信息提示持续时间
+         *
          * The toast prompt close delay time in milliseconds. The default value is 3000ms.
          */
         timeout?: number,
+    
         /**
+         *
+         * 信息提示是否可关闭
+         *
          * Whether to show the close button or not.The default value is false
          */
         closable?: boolean,
     }
+    
     /**
+     *
+     * 酷大师信息提示
+     *
      * The KToast class is the handle to show toasts in the UI.
      */
     interface KToast {
         /**
+         *
+         * 展示一个成功信息提示
+         *
          * Show a success.
          * @param option The toast option.
          * @returns
          */
         success(option: KToastOption): void;
+    
         /**
+         *
+         * 展示一个普通信息提示
+         *
          * Show an info.
          * @param option The toast option.
          * @returns
          */
         info(option: KToastOption): void;
+    
         /**
+         *
+         * 展示一个警告信息提示
+         *
          * Show a warn.
          * @param option The toast option.
          * @returns
          */
         warn(option: KToastOption): void;
+    
         /**
+         *
+         * 展示一个错误信息提示
+         *
          * Show an error.
          * @param option The toast option.
          * @returns
          */
         error(option: KToastOption): void;
+    
         /**
+         *
+         * 展示一个加载信息提示
+         *
          * Show an loading.
          * @param option The toast option.
          * @returns
          */
         loading(option: KToastOption): void;
+    
         /**
+         *
+         * 清空所有信息提示
+         *
          * Clear all the toasts.
          * @returns
          */
@@ -1628,14 +2500,24 @@ declare global {
 
     
     /**
+     *
+     * 推断吸附结果
+     *
      * The KInferenceResult class represents the inference result.
      */
     interface KInferenceResult {
         /**
+         *
+         * 吸附点
+         *
          * The inference point.
          */
         position: KPoint3d;
+    
         /**
+         *
+         * 吸附图形实体
+         *
          * The inference entity from which we get the inference point.
          * NOTE: The inference entities can only be the following types:
          * KEntityType.Vertex, KEntityType.Edge, KEntityType.Face, KEntityType.AuxiliaryBoundedCurve,
@@ -1643,7 +2525,10 @@ declare global {
          * If other objects from which we get the inference point, undefined will be returned.
          */
         entity?: KEntity;
+    
         /**
+         * 被吸附图形实体所在的组实例的路径
+         *
          * The instance path the inference point.
          * When the inference entity are from group instances, The group instances will be in the instance path.
          */
@@ -1651,6 +2536,10 @@ declare global {
     }
     
     /**
+     *
+     * 酷大师插件自定义工具
+     * 实现此接口，即可接受酷大师的各种键盘和鼠标事件，从而创建出一个像酷大师内置工具一样的自定义工具
+     *
      * The KTool class is the interface that you implement to create a KuDaShi tool.
      * To create a new tool, you must define a new class that implements all the methods of the KTool class.
      * Once you have defined a tool class, you select that tool by creating an instance of it
@@ -1658,63 +2547,103 @@ declare global {
      */
     interface KTool {
         /**
+         *
+         * 工具激活响应函数
+         *
          * The method is called by KuDaShi when the tool is activated.
          * @return
          */
         onToolActive(): void;
+    
         /**
+         *
+         * 工具反激活响应函数
          * The method is called by KuDaShi when the tool is deactivated.
          * @return
          */
         onToolDeactive(): void;
+    
         /**
+         *
+         * 工具撤销回调函数。当用户点击鼠标右键，或者键盘上的 ESC 键的时候，会调用这个回调函数
+         * 如果自定义工具没有实现这个回调函数，那么系统会直接关闭自定义工具
+         *
          * This is an optional callback to retract the KTool from one status to a previous status. It is called when user clicks RMB or presses ESC key.
          * If the tool does not implement this callback, then system will close the tool directly without ask when user click RMB.
          * @return Return an object which contains the retraction result and a flag about whether all the tool steps were retracted and the tool is ready to exit.
          * If that return flag is false, then it means the tool was retracted but it has multiple steps and still in one of the steps.
          */
         onToolRetract?(): { retracted: boolean, readyToExit: boolean };
+    
         /**
+         *
+         * 鼠标移动事件响应函数
+         *
          * The method is called by KuDaShi whenever the mouse is moved.
          * @param event It describes a user interaction with the mouse.
          * @param inferenceResult The inference result if Using inference, else undefined.
          * @return
          */
         onMouseMove(event: KMouseEvent, inferenceResult?: KInferenceResult): void;
+    
         /**
+         *
+         * 鼠标左键抬起响应函数
+         *
          * The method is called by KuDaShi when the left mouse button is released.
          * @param event It describes a user interaction with the mouse.
          * @param inferenceResult The inference result if Using inference, else undefined.
          * @return
          */
         onLButtonUp(event: KMouseEvent, inferenceResult?: KInferenceResult): void;
+    
         /**
+         *
+         * 鼠标右键抬起响应函数
+         *
          * The method is called by KuDaShi when the right mouse button is released.
          * @param event It describes a user interaction with the mouse.
          * @param inferenceResult The inference result if Using inference, else undefined.
          * @return
          */
         onRButtonUp(event: KMouseEvent, inferenceResult?: KInferenceResult): void;
+    
         /**
+         *
+         * 鼠标左键双击响应函数
+         *
          * The method is called by KuDaShi when the user double clicks with the left mouse button.
          * @param event It describes a user interaction with the mouse.
          * @param inferenceResult The inference result if Using inference, else undefined.
          * @return
          */
         onLButtonDbClick(event: KMouseEvent, inferenceResult?: KInferenceResult): void;
+    
         /**
+         *
+         * 允许使用吸附行为的回调函数
+         * 如果此函数返回 true， 则酷大师的默认吸附行为将被打开
+         *
          * The method used to set whether to use the inference.
          * It is called by KuDaShi when the tool is activated or the user presses a key on the keyboard or moves the mouse.
          * @return True if using the inference, else false.
          */
         allowUsingInference(): boolean;
+    
         /**
+         *
+         * 按键按下响应函数
+         *
          * The method is called by KuDaShi when the user presses a key on the keyboard.
          * @param event It describes a user interaction with the keyboard.
          * @return
          */
         onKeyDown(event: KKeyBoardEvent): void;
+    
         /**
+         *
+         * 按键抬起响应函数
+         *
          * The method is called by KuDaShi when the user releases a key on the keyboard.
          * @param event It describes a user interaction with the keyboard.
          * @return
@@ -1724,24 +2653,75 @@ declare global {
 
     
     /**
+     *
+     * 选择行为
+     *
      * The KSelectBehavior class represents select behavior types.
      */
     enum KSelectBehavior {
+        /**
+         * 反选。点击一个图元，会使其选择状态在选中和非选中之间切换。
+         * 提示：在酷大师中，选择时按住 shift 键会进入反选状态
+         *
+         * toggle selection. clicking on an entity will toggle its selection status between selected/un-selected
+         * hint: in UI opeation, pressing shift when doing selection turns on the toggle selection mode
+         *
+         */
         TOGGLE = 'toggle',
+    
+        /**
+         * 减选。点击一个图元，会使其从选择集中删除。如果它本来就不在选择集中，则无变化。
+         * 提示：在酷大师中，选择时按住 ctrl + shift 键会进入减选状态
+         *
+         * remove selection. clicking on an entity will remove it from the selection set
+         * hint: in UI operation, pressing ctrl + shift when doing selection turns on the remove selection mode
+         *
+         */
         REMOVE = 'remove',
+    
+        /**
+         * 加选。点击一个图元，会使其加入选择集。如果它本来就在选择集中，则无变化。
+         * 提示：在酷大师中，选择时按住 ctrl 键会进入加选状态
+         *
+         * add selection. clicking on an entity will add it to the selection set
+         * hint: in UI operation, pressing ctrl when doing selection turns on the add selection mode
+         *
+         */
         ADD = 'add',
+    
+        /**
+         * 单选。点击一个图元，会使其加入选择集。如果它本来就在选择集中，则无变化。点击另一个图元会使另一个图元加入选择集，而使当前被选择图元退出选择集。点击空白处会清空选择集。
+         * 提示：在酷大师中，选择时不按任何键的默认选择状态就是单选
+         *
+         * replace selection. also known as single selection. clicking on an entity will add it to the selection set. clicking on another entity will add another entity
+         * to the selection set, and remove the current selected entity from it. clicking on empty space will clear the selection set.
+         * hit: in UI operation, replace selection is the default behavior when doing selection, without pressing any keys
+         *
+         */
         REPLACE = 'replace',
     }
     
+    /**
+     *
+     * 自定义工具帮助器
+     *
+     */
     interface KToolHelper {
         /**
+         *
+         * 允许或禁止酷大师默认的选择行为
+         *
          * Enable or disable the picking process of the system defauts.
          * Note: This method only works within an activated KTool. By default, picking process is not enabled for a KTool.
          * @param enable enable the picking if true, or disable if false.
          * @returns void
          */
         enablePicking(enable: boolean): void;
+    
         /**
+         *
+         * 允许或禁止酷大师的框选行为
+         *
          * Enable or disable the rect picking process of the system defauts.
          * Note: This method only works within an activated KTool. By default, rect picking process is not enabled for a KTool.
          * Rect picking only can be enabled when picking process is enabled.
@@ -1749,19 +2729,34 @@ declare global {
          * @returns void
          */
         enableRectPicking(enable: boolean): void;
+    
         /**
+         *
+         * 设置选择器过滤器。可以仅允许用户选择特定类型的图形实体
+         *
          * Set the selectable entity types.
          * Note: This method only works within an activated KTool.
          * @param pickableEntityTypes the selectable entity types. If it is empty, then all entities are selectable.
          * @returns void
          */
         setPickingFilter(pickableEntityTypes: KEntityType[]): void;
+    
         /**
+         *
+         * 清空选择器过滤器
+         *
          * Clear the user setting of selectable entity types.
          * @returns void
          */
         clearPickingFilter(): void;
+    
         /**
+         *
+         * 设置酷大师的默认选择行为。
+         * 这可以使用户在并没有按住 shift, control 或 shift + control 时，可以拥有不一样的选择行为。（酷大师在没有按住上述按键时的默认选择行为是单选）
+         * 用户在做框选时，总是要按住 shift, control 或者 shift + control，所以框选没有默认选择行为
+         * 但是如果插件禁止了酷大师的框选行为，实现了它自己的框选，那这里设置的默认选择行为也会应用到插件自定义的框选行为中
+         *
          * Set the default select behavior when user didn't press shift key, control key or shift + control key.
          * Note: by default system uses the replace mode.
          * user has to allways explicitly press shift key, control key or shift + control key to do box picking, so box picking has no default select behavior.
@@ -1770,23 +2765,38 @@ declare global {
          * @returns void
          */
         setDefaultSelectBehavior(behavior: KSelectBehavior): void;
+    
         /**
+         *
+         * 设置被排除在外的用于吸附的图形实体列表
+         *
          * Set the excluded inference entities.
          * @param entities The excluded inference entities.
          * @returns Return true if successful, else return false.
          */
         setExcludedInferenceEntities(entities: KEntity[]): boolean;
+    
         /**
+         * 清空被排除在外的用于吸附的图形实体列表
+         *
          * Clear the excluded inference entities.
          * @returns Return true if successful, else return false.
          */
         clearExcludedInferenceEntities(): boolean;
+    
         /**
+         *
+         * 获取当前鼠标 hover 高亮的图形实体
+         *
          * Get the hovered item.
          * @returns Return the hovered entity. If it is a continuous edge or face, then return all its KEdges or KFaces.
          */
         getHoveredItem(): KEntity[] | null;
+    
         /**
+         *
+         * 将一个点投影到一组面上，求投影点、投影面、投影点法向和投影距离
+         *
          * The method is used to project a point onto a face region.
          * Note: currently it only supports faces in the active group definition.
          * @param targetFaces The face region where the point projects onto.
@@ -1796,7 +2806,11 @@ declare global {
          * otherwise return null. If the projected face is in a continuouse face group, then we will return all of the faces in that continuouse face group.
          */
         projectPointOntoFaces(targetFaces: KFace[], point: KPoint3d, projectDirection: KVector3d): { projectedFace: KFace[], projection: KPoint3d, normal: KVector3d, distance: number } | null;
+    
         /**
+         *
+         * 将一个点投影到一个成组实例上，求投影点、投影点法向和投影距离
+         *
          * The method is used to project a point onto a group instance.
          * Note: currently it only supports group instance in the active group definition.
          * @param groupInstance The target groupInstnace where the point projects onto.
@@ -1805,17 +2819,28 @@ declare global {
          * @returns Return an object which contains project location, face normal at the project location and project distance if successful, otherwise return null.
          */
         projectPointOntoGroupInstance(groupInstance: KGroupInstance, point: KPoint3d, projectDirection: KVector3d): { projection: KPoint3d, normal: KVector3d, distance: number } | null;
+    
         /**
+         * 获取一组面的顶点
+         *
          * @param faces The target faces where to collect vertices.
          * @returns Return the unique vertex array.
          */
         getVerticesOfFaces(faces: KFace[]): KVertex[];
+    
         /**
+         *
+         * 获取一组面的顶点的几何点
+         *
          * @param faces The target faces.
          * @returns Return the unique vertex point array.
          */
         getVertexPointsOfFaces(faces: KFace[]): KPoint3d[];
+    
         /**
+         *
+         * 获取一组面的包围盒
+         *
          * @param faces The target faces.
          * @returns Return the bounding box of the faces.
          */
@@ -1823,26 +2848,38 @@ declare global {
     }
 
     /**
+     *
+     * 酷大师图形实体：造型顶点
+     * 它对应于一个Brep数据结构的顶点 (Vertex)
+     *
      * The KVertex class represents the BRep vertex.
      */
     interface KVertex extends KTopoVertex, KEntity {
         /**
+         *
+         * 获取图形实体类型
+         *
          * Get the entity's type.
          * @returns The entity's type.
          */
          getType(): KTopoType;
     
         /**
+         *
+         * 获取和这个顶点相连的边
+         *
          * Retrieve the vertex's edges whose start or end vertex is this vertex.
          * @return The vertex's edges.
          */
          getEdges(): KEdge[];
     
         /**
+         *
+         * 设置这个顶点是否为软化顶点
+         * 当在酷大师中选择一条边时，会将从这条边开始，所有通过软化顶点相连的边一起选中
+         *
          * Set the vertex to be soft.
-         * A soft vertex will cause the connected edges to be treated as a curve.
-         * This means that if you select one edge it will also
-         * select all edges connected with soft vertices.
+         * If you select one edge it will also select all edges connected with soft vertices.
          * @param isSoft The soft value.
          * @return Return true if it is a soft vertex, otherwise return false.
          */
@@ -1850,111 +2887,205 @@ declare global {
     }
 
     /**
+     * 用红绿蓝三原色表示的颜色值
+     *
      * The KColor class represents a color.
      */
     interface KColor {
         /**
+         *
+         * 红色分量，在 0 到 255 之间取值
+         *
          * Red channel value between 0 and 255.
          */
         r: number;
+    
         /**
+         *
+         * 绿色分量，在 0 到 255 之间取值
+         *
          * Green channel value between 0 and 255.
          */
         g: number;
+    
         /**
+         *
+         * 蓝色分量，在 0 到 255 之间取值
+         *
          * Blue channel value between 0 and 255.
          */
         b: number;
     }
+    
     /**
+     *
+     * 临时点绘制选项
+     *
      * The KDrawPointsOption class represents the option for Drawing temporary points.
      */
     interface KDrawPointsOption {
         /**
+         *
+         * 点的颜色
+         *
          * The points color. Default is { r: 0, g: 0, b: 0}.
          */
         color?: KColor;
+    
         /**
+         *
+         * 点的尺寸
+         *
          * The points size. Default is 50.
          */
         size?: number;
     }
+    
     /**
+     *
+     * 临时线线型
+     *
      * The KLinePattern class represents the line pattern.
      */
     enum KLinePattern {
         /**
+         *
+         * 实线
+         *
          * The solid line.
          */
         Solid = 'solid line',
+    
         /**
+         *
+         * 虚线
+         *
          * The dash line.
          */
         Dash = 'dash line'
     }
+    
     /**
+     *
+     * 临时线绘制选项
+     *
      * The KDrawLinesOption class represents the option for Drawing temporary lines.
      */
     interface KDrawLinesOption {
         /**
+         *
+         * 颜色
+         *
          * The lines color. Default is { r: 0, g: 0, b: 0}.
          */
         color?: KColor;
+    
         /**
+         *
+         * 线型
+         *
          * The line pattern. Default is Solid.
          */
         pattern?: KLinePattern;
+    
         /**
+         *
+         * 虚线长度
+         *
          * The size of the dash. Default is 100.
          */
         dashSize?: number;
+    
         /**
+         *
+         * 虚线间距
+         *
          * The size of the gap. Default is 100.
          */
         gapSize?: number;
     }
+    
     /**
+     *
+     * 酷大师图形显示视口
+     *
      * The KViewport class represents the viewport.
      */
     interface KViewport {
         /**
+         *
+         * 视口长
+         *
          * The height of the viewport.
          */
         height: number;
+    
         /**
+         *
+         * 视口宽
+         *
          * The width of the viewport.
          */
         width: number;
     }
+    
     /**
+     *
+     * 临时文字绘制选项
+     *
      * The KDrawTextOption class represents the option for Drawing temporary text.
      */
     interface KDrawTextOption {
         /**
+         *
+         * 文字颜色
+         *
          * The text color. Default is { r: 0, g: 0, b: 0}.
          */
         color?: KColor;
+    
         /**
+         *
+         * 文字尺寸
+         *
          * The text size. Default is 12.
          */
         size?: number;
     }
+    
     /**
+     *
+     * 酷大师视图窗口
+     *
      * The KView class now contains methods for getting the camera handle.
      * You can access the KView by calling the app.activeView method.
      */
     interface KView {
         /**
+         *
+         * 获取相机
+         *
          * Get the camera handle.
          * @returns The camera handle.
          */
         getCamera(): KCamera;
+    
         /**
+         *
+         * 获取图形显示视口
+         *
          * Get the viewport for the view.
          * @returns The viewport.
          */
         getViewport(): KViewport;
+    
         /**
+         *
+         * 在视口中临时绘制点。
+         *
+         * 1. 一般我们只能在自定义工具的交互过程中绘制这种临时图形元素
+         * 2. 临时绘制的图形元素会在自定义工具退出时，自动清空
+         *
          * This method is used to draw temporary points.
          * Note: 1.This method is usually invoked within a KTool, and invalid elsewhere.
          * 2. The temporary points will be cleared when deactivating the KTool.
@@ -1963,7 +3094,14 @@ declare global {
          * @returns True if success, else false.
          */
         drawPoints(points: KPoint3d[], option?: KDrawPointsOption): boolean;
+    
         /**
+         *
+         * 在视口中临时绘制线段。
+         *
+         * 1. 一般我们只能在自定义工具的交互过程中绘制这种临时图形元素
+         * 2. 临时绘制的图形元素会在自定义工具退出时，自动清空
+         *
          * This method is used to draw a temporary polyline.
          * Note: 1.This method is usually invoked within a KTool, and invalid elsewhere.
          * 2. The temporary lines will be cleared when deactivating the KTool.
@@ -1972,7 +3110,14 @@ declare global {
          * @returns True if success, else false.
          */
         drawLines(points: KPoint3d[], option?: KDrawLinesOption): boolean;
+    
         /**
+         *
+         * 在视口中临时绘制一组多段线。
+         *
+         * 1. 一般我们只能在自定义工具的交互过程中绘制这种临时图形元素
+         * 2. 临时绘制的图形元素会在自定义工具退出时，自动清空
+         *
          * This a batch method to draw a set of polylines.
          * Note: 1.This method is usually invoked within a KTool, and invalid elsewhere.
          * 2. The temporary lines will be cleared when deactivating the KTool.
@@ -1981,7 +3126,14 @@ declare global {
          * @returns True if success, else false.
          */
         drawPolylines(points: KPoint3d[][], option?: KDrawLinesOption): boolean;
+    
         /**
+         *
+         * 在视口中临时绘制一段文字。
+         *
+         * 1. 一般我们只能在自定义工具的交互过程中绘制这种临时图形元素
+         * 2. 临时绘制的图形元素会在自定义工具退出时，自动清空
+         *
          * This method is used to draw temporary text.
          * Note: 1.This method is usually invoked within a KTool, and invalid elsewhere.
          * 2. The temporary text will be cleared when deactivating the KTool.
@@ -1992,7 +3144,14 @@ declare global {
          * @returns True if success, else false.
          */
         drawText(text: string, position: KPoint3d, direction?: KVector3d, option?: KDrawTextOption): boolean;
+    
         /**
+         *
+         * 在视口中临时绘制一段提示线。这段提升线类似于酷大师直线绘制工具中的虚线。
+         *
+         * 1. 一般我们只能在自定义工具的交互过程中绘制这种临时图形元素
+         * 2. 临时绘制的图形元素会在自定义工具退出时，自动清空
+         *
          * This method is used to draw prompt lines. This method is used to draw prompt lines quickly.
          * The style is consistent with the drawing line tool in KuDaShi and no modify style interface provided.
          * If the style does not meet the requirements, you may combine other interfaces in this KView class to draw.
@@ -2006,7 +3165,11 @@ declare global {
          * @returns True if success, else false.
          */
         drawPromptLine(startPoint: KPoint3d, endPoint: KPoint3d, normal?: KVector3d, promptText?: string): boolean;
+    
         /**
+         *
+         * 强制清空临时绘制的图形
+         *
          * This method is used to clear temporary shapes.
          * @returns
          */
@@ -5666,6 +6829,9 @@ declare global {
     }
 
     /**
+     *
+     * 代表异步操作的结果
+     *
      * The HostPromise class represents the eventual completion (or failure) of an asynchronous operation and its resulting value.
      * NOTE: The promise passed from host cannot be chained.
      */
@@ -5673,43 +6839,72 @@ declare global {
         then(resolve?: (value: T) => void, reject?: (error: any) => void): void;
         catch(reject?: (error: any) => void): void;
     }
+    
     /**
+     *
+     * 代表展示插件 UI html 的窗口
+     *
      * The KPluginUI class now contains methods for operating plugin UIs.
      * You can access the KPluginUI by calling the app.getPluginUI() method.
      */
     interface KPluginUI {
         /**
+         * 代表 UI 窗口是否已经被显示。true 为已显示
+         *
          * Return true if the plugin UI is mounted, else return false.
          */
         readonly mounted: boolean;
+    
         /**
+         *
+         * 显示插件 UI 窗口
+         *
          * Mount the plugin UI.
          * @returns
          */
         mount(): void;
+    
         /**
+         *
+         * 关闭插件 UI 窗口
+         *
          * UnMount the plugin UI.
          * @returns
          */
         unmount(): void;
+    
         /**
+         *
+         * 调整插件 UI 窗口大小
+         *
          * Resize the plugin UI.
          * @returns
          */
         resize(width: number, height: number): void;
+    
         /**
+         *
+         * 注册插件　UI 窗口显示完成后的回调函数
+         *
          * Register the callback function.
          * When the plugin UI is ready, the callback function will be called.
          * @returns
          */
         onReady(callback: () => void): void;
+    
         /**
+         * 注册插件 UI 窗口发送的自定义消息的响应函数
+         *
          * Register the callback function for the plugin UI.
          * When a message is sent from the plugin UI, the callback function will be called.
          * @returns
          */
         onMessage(callback: (data: any, origin: string) => void): void;
+    
         /**
+         *
+         * 从沙盒 JS 代码向插件 UI 窗口发送自定义消息
+         *
          * Post a message from the sandbox to the plugin UI.
          * @param data The data posted from the sandbox.
          * @param origin The origin of the sender.
@@ -5719,18 +6914,29 @@ declare global {
     }
     
     /**
+     *
+     * 本地浏览器临时存储接口
+     * 它类似于 Window.seesionStorage，可用于存储各种自定义数据。清空浏览器缓存会导致数据丢失
+     *
      * The KClientStorage class allows you to store data on the user's local machine. This data is not synchronized across users.
      * It's similar to the Window.sessionStorage, and allows storing objects, arrays, strings, numbers, booleans, null, undefined and Uint8Array.
      * Like sessionStorage, you should expect that user actions such as clearing the browser cache might clear all stored data.
      */
     interface KClientStorage {
         /**
+         *
+         * 根据 key 获取存储内容
+         *
          * Retrieve a value from client storage with the given key.
          * @param key The given key.
          * @returns The value from client storage with the given key.
          */
         getAsync(key: string): HostPromise<any | undefined>
+    
         /**
+         *
+         * 用 <key, value> 的形式存储内容
+         *
          * Set a value to client storage with the given key.
          * @param key The given key.
          * @param value The given value.