@aigne/doc-smith 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.8.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.0...v0.8.1) (2025-09-03)
+
+
+### Features
+
+* tune d2 chart generating with comprehensive examples ([#80](https://github.com/AIGNE-io/aigne-doc-smith/issues/80)) ([3423e4c](https://github.com/AIGNE-io/aigne-doc-smith/commit/3423e4cff24335552503916694a3489e5d91bf6c))
+
+
+### Miscellaneous Chores
+
+* release 0.8.1 ([21f64d4](https://github.com/AIGNE-io/aigne-doc-smith/commit/21f64d450377b1aef00f12613ba3b87aa4ef1d31))
+
 ## [0.8.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.7.2...v0.8.0) (2025-09-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "",
   "publishConfig": {
     "access": "public"

package/prompts/document/d2-chart/rules.md

@@ -1,48 +1,957 @@
 - 使用 d2 图表解释复杂的概念 (```d2``` format)，让页面内容展示形式更丰富
-  - 使用 d2 展示架构关系、流程与组件交互，节点与连线文案保持简洁
-  - d2 代码块必须完整且可渲染，避免使用未闭合的语法与奇异字符
-  - d2 图表使用补充说明：
-    - 示例：
-      {% include "diy-examples.md" %}
-    - 官方示例：
-      {% include "official-examples.md" %}
-    - 其他注意事项：
-      - 图表应简洁明了，节点和连线命名准确。
-      - 每个 d2 代码块必须完整闭合，避免语法错误。
-      - 不要添加注释说明，因为生成的图片无法进行交互。
-      - 不要随意更改节点和连线的颜色，这样会破坏配置好的主题。
-      - 节点的名称尽量使用 " 进行包裹，避免出现异常。
-        - bad: `SDK: @blocklet/js-sdk`
-        - good: `SDK: "@blocklet/js-sdk"`
-      - d2 中的 `shape` 只有这些值: `rectangle`, `square`, `page`, `parallelogram`, `document`, `cylinder`, `queue`, `package`, `step`, `callout`, `stored_data`, `person`, `diamond`, `oval`, `circle`, `hexagon`, `cloud`, `c4-person`，不要随意创建其他的 shape，会导致图表报错
-      - 页面的整体布局使用 `direction: down`，这样能确保图表适合在网页中进行阅读；子图中可以根据情况来使用其他的方向布局，需要确保图表的整体效果看起来不会太宽
-      - 如果一个对象中的元素太多了(超过3个)，请使用 `grid-columns` 限制一下单行的列数，`grid-columns` 的值不要超过 3，例如
-        ```d2
-        "Instance": {
+  - 使用的 d2 的版本是 0.7.x，d2 官方的文档请查看 https://d2lang.com/tour/intro/
+  - 图表应简洁明了，节点和连线命名准确，节点与连线文案保持简洁，不要太长
+    - bad
+      ```d2
+      "TokenService": {
+        label: "TokenService (Handles token storage & refresh)"
+        shape: class
+      }
+      ```
+    - good
+      ```d2
+      "TokenService": {
+        label: "TokenService"
+        shape: class
+      }
+      ```
+  - 使用 d2 展示架构关系、流程与组件交互
+  - d2 代码块必须完整且可渲染，避免使用未闭合的语法与奇异字符，避免语法错误
+  - 不要为节点添加 `tooltip`，保持简单即可
+    - bad
+      ```d2
+      "AuthService": {
+        label: "AuthService"
+        tooltip: "Manages user profiles, privacy, and authentication actions"
+        shape: class
+      }
+      ```
+    - good
+      ```d2
+      "AuthService": {
+        label: "AuthService"
+        shape: class
+      }
+      ```
+  - 节点的名称尽量使用 `"` 进行包裹，避免出现渲染异常
+    - bad: `SDK: @blocklet/js-sdk`
+    - good: `SDK: "@blocklet/js-sdk"`
+  - 不要随意给节点填充颜色，除非节点有明确的 yes/no 的状态，此时可以给节点 fill `error`, `warning`, `success` 之类的颜色
+    - bad
+      ```d2
+      "TokenService" {
+        shape: class
+        style.fill: "#fffbe6"
+      }
+      ```
+    - good
+      ```d2
+      "TokenService" {
+        shape: class
+      }
+      ```
+  - 对于单个节点和连线，可以使用 `animate: true` 可以让图表增加动画效果，看起来效果更好
+  - 对于节点 shape 的选择，可以参考
+    {% include "shape-rules.md" %}
+  - 页面的整体布局使用 `direction: down`，这样能确保图表适合在网页中进行阅读；子图中可以根据情况来使用其他的方向布局，需要确保图表的整体效果看起来不会太宽
+    - bad:
+      ```d2
+      direction: right
+
+      "online": {
+        shape: circle
+        style.fill: "#52c41a"
+      }
+
+      "offline": {
+        shape: circle
+        style.fill: "#faad14"
+      }
+
+      "expired": {
+        shape: circle
+        style.fill: "#ff4d4f"
+      }
+
+      "New Login" -> "online": "User authenticates"
+      "online" -> "offline": "User closes app/browser"
+      "online" -> "expired": "Token expires"
+      "offline" -> "online": "User returns"
+      "offline" -> "expired": "Extended inactivity"
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "online": {
+        shape: circle
+        style.fill: "#52c41a"
+      }
+
+      "offline": {
+        shape: circle
+        style.fill: "#faad14"
+      }
+
+      "expired": {
+        shape: circle
+        style.fill: "#ff4d4f"
+      }
+
+      "New Login" -> "online": "User authenticates"
+      "online" -> "offline": "User closes app/browser"
+      "online" -> "expired": "Token expires"
+      "offline" -> "online": "User returns"
+      "offline" -> "expired": "Extended inactivity"
+      ```
+  - 如果一个节点中的字节点太多了(超过3个)，请使用 `grid-columns` 限制一下单行的列数，`grid-columns` 的值优先使用2，最大不要超过 3，例如
+    - good:
+      ```d2
+      "Instance": {
+        grid-columns: 3
+        "A": "A"
+        "B": "B"
+        "C": "C"
+        "D": "D"
+        "E": "E"
+      }
+      ```
+      ```d2
+      "Instance": {
+        grid-columns: 2
+        "A": "A"
+        "B": "B"
+        "C": "C"
+        "D": "D"
+      }
+      ```
+  - 每一个容器节点中，最好设置 `grid-columns`
+    - bad:
+      ```d2
+      direction: down
+
+      "SDK": "@blocklet/js-sdk" {
+        shape: package
+        
+        "Core Instance": {
+          shape: rectangle
+          "BlockletSDK": "Main SDK Class"
+        }
+        
+        "Services": {
+          grid-columns: 3
+          "AuthService": "User Authentication" {
+            shape: class
+          }
+          "TokenService": "Token Management" {
+            shape: class  
+          }
+          "UserSessionService": "Session Management" {
+            shape: class
+          }
+          "BlockletService": "Blocklet Metadata" {
+            shape: class
+          }
+          "FederatedService": "Federated Login" {
+            shape: class
+          }
+        }
+        
+        "HTTP Clients": {
+          grid-columns: 2
+          "createAxios": "Axios-based Client" {
+            shape: rectangle
+          }
+          "createFetch": "Fetch-based Client" {
+            shape: rectangle
+          }
+        }
+      }
+
+      "Your App": "Application Code" {
+        shape: rectangle
+      }
+
+      "Blocklet Services": "Remote APIs" {
+        shape: cylinder
+      }
+
+      "Your App" -> "SDK": "Import & Use"
+      "SDK" -> "Blocklet Services": "Authenticated Requests"
+      "Blocklet Services" -> "SDK": "Responses & Tokens"
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "SDK": "@blocklet/js-sdk" {
+        shape: package
+        grid-columns: 1
+        
+        "Core Instance": {
+          shape: rectangle
+          "BlockletSDK": "Main SDK Class"
+        }
+        
+        "Services": {
+          grid-columns: 3
+          "AuthService": "User Authentication" {
+            shape: class
+          }
+          "TokenService": "Token Management" {
+            shape: class  
+          }
+          "UserSessionService": "Session Management" {
+            shape: class
+          }
+          "BlockletService": "Blocklet Metadata" {
+            shape: class
+          }
+          "FederatedService": "Federated Login" {
+            shape: class
+          }
+        }
+        
+        "HTTP Clients": {
+          grid-columns: 2
+          "createAxios": "Axios-based Client" {
+            shape: rectangle
+          }
+          "createFetch": "Fetch-based Client" {
+            shape: rectangle
+          }
+        }
+      }
+
+      "Your App": "Application Code" {
+        shape: rectangle
+      }
+
+      "Blocklet Services": "Remote APIs" {
+        shape: cylinder
+      }
+
+      "Your App" -> "SDK": "Import & Use"
+      "SDK" -> "Blocklet Services": "Authenticated Requests"
+      "Blocklet Services" -> "SDK": "Responses & Tokens"
+      ```
+  - 必须保证一个图中，所有的节点都是有关联的，不需要为图表设置 legend，如果就是有节点不存在关联性，则应该移除这些节点，或者拆分成多个独立的图表
+    - bad:
+      ```d2
+      direction: down
+
+      "Your App": {
+        shape: rectangle
+      }
+
+      "SDK Request Helper": {
+        label: "@blocklet/js-sdk (createAxios / createFetch)"
+        shape: package
+      }
+
+      "Blocklet Service": {
+        shape: cylinder
+      }
+
+      "Token Refresh Endpoint": {
+        label: "/api/did/refreshSession"
+        shape: rectangle
+      }
+
+      "Your App" -> "SDK Request Helper": "1. Make API Call (e.g., /api/profile)"
+
+      "SDK Request Helper" -> "Blocklet Service": "2. Adds Auth Header & Sends Request" {
+        style {
+          stroke-dash: 2
+        }
+      }
+
+      "Success Path": {
+        style.stroke: "#52c41a"
+
+        "Blocklet Service" -> "SDK Request Helper": "3a. 200 OK (Token Valid)"
+        "SDK Request Helper" -> "Your App": "4a. Returns Data"
+      }
+
+
+      "Token Renewal Path": {
+        style.stroke: "#faad14"
+
+        "Blocklet Service" -> "SDK Request Helper": "3b. 401 Unauthorized (Token Expired)"
+        "SDK Request Helper" -> "Token Refresh Endpoint": "4b. Request New Token"
+        "Token Refresh Endpoint" -> "SDK Request Helper": "5b. New Tokens"
+        "SDK Request Helper" -> "Blocklet Service": "6b. Retry Original Request"
+        "Blocklet Service" -> "SDK Request Helper": "7b. 200 OK" {
+          style.stroke: "#52c41a"
+        }
+        "SDK Request Helper" -> "Your App": "8b. Returns Data Transparently" {
+          style.stroke: "#52c41a"
+        }
+      }
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "Your App": {
+        shape: rectangle
+      }
+
+      "SDK Request Helper": {
+        label: "@blocklet/js-sdk (createAxios / createFetch)"
+        shape: package
+      }
+
+      "Blocklet Service": {
+        shape: cylinder
+      }
+
+      "Token Refresh Endpoint": {
+        label: "/api/did/refreshSession"
+        shape: rectangle
+      }
+
+      "Your App" -> "SDK Request Helper": "1. Make API Call (e.g., /api/profile)"
+
+      "SDK Request Helper" -> "Blocklet Service": "2. Adds Auth Header & Sends Request" {
+        style {
+          stroke-dash: 2
+        }
+      }
+      ```
+      ```d2
+      "Success Path": {
+        style.stroke: "#52c41a"
+
+        "Blocklet Service" -> "SDK Request Helper": "3a. 200 OK (Token Valid)"
+        "SDK Request Helper" -> "Your App": "4a. Returns Data"
+      }
+      ```
+      ```d2
+      "Token Renewal Path": {
+        style.stroke: "#faad14"
+
+        "Blocklet Service" -> "SDK Request Helper": "3b. 401 Unauthorized (Token Expired)"
+        "SDK Request Helper" -> "Token Refresh Endpoint": "4b. Request New Token"
+        "Token Refresh Endpoint" -> "SDK Request Helper": "5b. New Tokens"
+        "SDK Request Helper" -> "Blocklet Service": "6b. Retry Original Request"
+        "Blocklet Service" -> "SDK Request Helper": "7b. 200 OK" {
+          style.stroke: "#52c41a"
+        }
+        "SDK Request Helper" -> "Your App": "8b. Returns Data Transparently" {
+          style.stroke: "#52c41a"
+        }
+      }
+      ```
+  - 必须确保每个节点和子节点是有名称的
+    - bad:
+      ```d2
+      "SDK Core Instance": {
+        shape: package
+        "TokenService": "Manages session and refresh tokens"
+        "Services": {
+          grid-columns: 2
+          "AuthService": ""
+          "BlockletService": ""
+        }
+      }
+      ```
+    - good:
+      ```d2
+      "SDK Core Instance": {
+        shape: package
+        "TokenService": "Manages session and refresh tokens"
+        "Services": {
+          grid-columns: 2
+          "AuthService": "AuthService"
+          "BlockletService": "BlockletService"
+        }
+      }
+      ```
+  - 当有关联关系的节点，处于一个节点内部时，则它们的关联关系也应该写在节点内部
+    - bad
+      ```d2
+      direction: down
+
+      "@blocklet/js-sdk": {
+        shape: package
+        
+        "Main SDK Instance": {
+          shape: rectangle
+          "BlockletSDK Class": "Main entry point"
+          "getBlockletSDK()": "Singleton factory"
+        }
+        
+        "HTTP Clients": {
+          shape: rectangle
+          grid-columns: 2
+          "createAxios()": "Axios-based client"
+          "createFetch()": "Fetch-based client"
+        }
+        
+        "Core Services": {
+          shape: rectangle
+          grid-columns: 3
+          "AuthService": "User authentication"
+          "TokenService": "Token management"
+          "BlockletService": "Blocklet metadata"
+          "UserSessionService": "Session management"
+          "FederatedService": "Federated login"
+          "ComponentService": "Component utilities"
+        }
+      }
+
+      "Main SDK Instance" -> "HTTP Clients": "Uses for requests"
+      "Main SDK Instance" -> "Core Services": "Provides access to"
+      "HTTP Clients" -> "Core Services": "Configured with"
+      ```
+    - good
+      ```d2
+      direction: down
+
+      "@blocklet/js-sdk": {
+        shape: package
+        
+        "Main SDK Instance": {
+          shape: rectangle
+          "BlockletSDK Class": "Main entry point"
+          "getBlockletSDK()": "Singleton factory"
+        }
+        
+        "HTTP Clients": {
+          shape: rectangle
+          grid-columns: 2
+          "createAxios()": "Axios-based client"
+          "createFetch()": "Fetch-based client"
+        }
+        
+        "Core Services": {
+          shape: rectangle
           grid-columns: 3
-          "A": "A"
-          "B": "B"
-          "C": "C"
-          "D": "D"
-          "E": "E"
-        }
-        ```
-      - 尽量保证一个图中，只有一个关联所有元素的图，不要产生多个没有任何连接的子图
-      - 确保 `style` 中的值都是可用的，错误的字段会导致图片生成失败
-      - 尽量确保每个子元素是有名称的
-        - bad:
-          ```d2
-          "SDK Core Instance": {
-            shape: package
-            "TokenService": "Manages session and refresh tokens"
-            "Services": {
-              grid-columns: 2
-              "AuthService": ""
-              "BlockletService": ""
-              "FederatedService": ""
-              "UserSessionService": ""
-            }
-          }
-          ```
-      - 使用 animate: true 可以让图表增加动画效果，看起来效果更好
-      - 针对节点的状态(yes or no)，可以给定不同的颜色(error,warning,success)来增强表现力
+          "AuthService": "User authentication"
+          "TokenService": "Token management"
+          "BlockletService": "Blocklet metadata"
+          "UserSessionService": "Session management"
+          "FederatedService": "Federated login"
+          "ComponentService": "Component utilities"
+        }
+
+        "Main SDK Instance" -> "HTTP Clients": "Uses for requests"
+        "Main SDK Instance" -> "Core Services": "Provides access to"
+        "HTTP Clients" -> "Core Services": "Configured with"
+      }
+      ```
+    - bad:
+      ```d2
+      direction: down
+
+      "Your App": {
+        shape: rectangle
+      }
+
+      "SDK Request Helper": {
+        label: "@blocklet/js-sdk (createAxios / createFetch)"
+        shape: package
+      }
+
+      "Blocklet Service": {
+        shape: cylinder
+      }
+
+
+      "Your App" -> "SDK Request Helper": "1. Make API Call (e.g., /api/profile)"
+
+      "SDK Request Helper" -> "Blocklet Service": "2. Adds Auth Header & Sends Request" {
+        style {
+          stroke-dash: 2
+        }
+      }
+
+      "Token Renewal Path": {
+        style.stroke: "#faad14"
+
+        "Blocklet Service" -> "SDK Request Helper": "3. 401 Unauthorized (Token Expired)"
+        "SDK Request Helper" -> "Token Refresh Endpoint": "4. Request New Token"
+        "Token Refresh Endpoint" -> "SDK Request Helper": "5. New Tokens Received"
+        "SDK Request Helper" -> "Blocklet Service": "6. Retry Original Request with New Token"
+        "Blocklet Service" -> "SDK Request Helper": "7. 200 OK" {
+          style.stroke: "#52c41a"
+        }
+        "SDK Request Helper" -> "Your App": "8. Returns Data Transparently" {
+          style.stroke: "#52c41a"
+        }
+      }
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "Your App": {
+        shape: rectangle
+      }
+
+      "SDK Request Helper": {
+        label: "@blocklet/js-sdk (createAxios / createFetch)"
+        shape: package
+      }
+
+      "Blocklet Service": {
+        shape: cylinder
+      }
+
+
+      "Your App" -> "SDK Request Helper": "1. Make API Call (e.g., /api/profile)"
+
+      "SDK Request Helper" -> "Blocklet Service": "2. Adds Auth Header & Sends Request" {
+        style {
+          stroke-dash: 2
+        }
+      }
+
+      "Blocklet Service" -> "SDK Request Helper": "3. 401 Unauthorized (Token Expired)"
+      "SDK Request Helper" -> "Token Refresh Endpoint": "4. Request New Token"
+      "Token Refresh Endpoint" -> "SDK Request Helper": "5. New Tokens Received"
+      "SDK Request Helper" -> "Blocklet Service": "6. Retry Original Request with New Token"
+      "Blocklet Service" -> "SDK Request Helper": "7. 200 OK" {
+        style.stroke: "#52c41a"
+      }
+      "SDK Request Helper" -> "Your App": "8. Returns Data Transparently" {
+        style.stroke: "#52c41a"
+      }
+      ```
+  - 如果整个图表只有一个容器节点，就不要增加这个容器节点，直接将内部的节点放在最外层
+    - bad:
+      ```d2
+      direction: down
+
+      "User Sessions Flow": {
+        shape: package
+        grid-columns: 1
+        
+        "User Login": {
+          shape: person
+          style.fill: "#e6f7ff"
+        }
+        
+        "Session Creation": {
+          shape: rectangle
+          style.fill: "#f6ffed"
+        }
+        
+        "Session Storage": {
+          shape: cylinder
+          style.fill: "#fff7e6"
+        }
+        
+        "Multi-Device Access": {
+          shape: package
+          grid-columns: 3
+          "Web Browser": {
+            shape: rectangle
+          }
+          "Mobile App": {
+            shape: rectangle
+          }
+          "Desktop App": {
+            shape: rectangle
+          }
+        }
+        "User Login" -> "Session Creation": "Authenticate"
+        "Session Creation" -> "Session Storage": "Store session"
+        "Session Storage" -> "Multi-Device Access": "Access from devices"
+      }
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "User Login": {
+        shape: person
+        style.fill: "#e6f7ff"
+      }
+      
+      "Session Creation": {
+        shape: rectangle
+        style.fill: "#f6ffed"
+      }
+      
+      "Session Storage": {
+        shape: cylinder
+        style.fill: "#fff7e6"
+      }
+      
+      "Multi-Device Access": {
+        shape: package
+        grid-columns: 3
+        "Web Browser": {
+          shape: rectangle
+        }
+        "Mobile App": {
+          shape: rectangle
+        }
+        "Desktop App": {
+          shape: rectangle
+        }
+      }
+      "User Login" -> "Session Creation": "Authenticate"
+      "Session Creation" -> "Session Storage": "Store session"
+      "Session Storage" -> "Multi-Device Access": "Access from devices"
+      ```
+  - 某些情况下，单纯的设置 `direction: down` 还无法控制图表的整体方向，可以再结合 `grid-columns: 1` 来进行设置
+    - bad:
+      ```d2
+      direction: down
+
+      "Your Application": {
+        shape: rectangle
+      }
+
+      "@blocklet/js-sdk": {
+        shape: package
+        grid-columns: 1
+
+        "AuthService": {
+          shape: class
+        }
+      }
+
+      "Blocklet API Endpoints": {
+        shape: cylinder
+        grid-columns: 2
+        "/api/user/profile": {}
+        "/api/user/privacy/config": {}
+        "/api/user/notification/config": {}
+        "/api/user/logout": {}
+        "/api/user/follow/{did}": {}
+        "/api/user": {}
+      }
+
+      "Your Application" -> "@blocklet/js-sdk".AuthService: "e.g., sdk.auth.getProfile()"
+      "@blocklet/js-sdk".AuthService -> "Blocklet API Endpoints": "Makes authenticated API calls"
+      ```
+    - good:
+      ```d2
+      direction: down
+      grid-columns: 1
+
+      "Your Application": {
+        shape: rectangle
+      }
+
+      "@blocklet/js-sdk": {
+        shape: package
+        grid-columns: 1
+
+        "AuthService": {
+          shape: class
+        }
+      }
+
+      "Blocklet API Endpoints": {
+        shape: cylinder
+        grid-columns: 2
+        "/api/user/profile": {}
+        "/api/user/privacy/config": {}
+        "/api/user/notification/config": {}
+        "/api/user/logout": {}
+        "/api/user/follow/{did}": {}
+        "/api/user": {}
+      }
+
+      "Your Application" -> "@blocklet/js-sdk".AuthService: "e.g., sdk.auth.getProfile()"
+      "@blocklet/js-sdk".AuthService -> "Blocklet API Endpoints": "Makes authenticated API calls"
+      ```
+  - 当节点中子节点个数与 `grid-columns` 值相同时，则应该去掉 `grid-columns` 字段
+    - bad:
+      ```d2
+      "@blocklet/js-sdk": {
+        shape: package
+        grid-columns: 1
+
+        "AuthService": {
+          shape: class
+        }
+      }
+      ```
+    - good:
+      ```d2
+      "@blocklet/js-sdk": {
+        shape: package
+
+        "AuthService": {
+          shape: class
+        }
+      }
+      ```
+    - bad:
+      ```d2
+      "Browser Storage": {
+        shape: package
+        grid-columns: 2
+
+        "Cookies": {
+          shape: document
+          "Session Token": {}
+        }
+
+        "LocalStorage": {
+          shape: stored_data
+          "Refresh Token": {}
+        }
+      }
+      ```
+    - good:
+      ```d2
+      "Browser Storage": {
+        shape: package
+
+        "Cookies": {
+          shape: document
+          "Session Token": {}
+        }
+
+        "LocalStorage": {
+          shape: stored_data
+          "Refresh Token": {}
+        }
+      }
+      ```
+  - 当一个容器节点外部有节点与当前容器节点内部节点相互关联时，应该将这些节点放在同一层级
+    - bad:
+      ```d2
+      direction: down
+
+      "Federated Login Group": {
+        shape: package
+
+        "Master App": {
+          shape: rectangle
+          style.stroke: "#0052cc"
+          style.stroke-width: 2
+          "Provides central authentication"
+        }
+
+        "Member App 1 (Current App)": {
+          shape: rectangle
+          "User interacts here"
+        }
+
+        "Member App 2": {
+          shape: rectangle
+        }
+
+        "Master App" -> "Member App 1 (Current App)": "Shares user session"
+        "Master App" -> "Member App 2": "Shares user session"
+      }
+
+      User: {
+        shape: person
+      }
+
+      User -> "Member App 1 (Current App)": "Logs in via Master App"
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "Federated Login Group": {
+        shape: package
+
+        "Master App": {
+          shape: rectangle
+          style.stroke: "#0052cc"
+          style.stroke-width: 2
+          "Provides central authentication"
+        }
+
+        "Member App 1 (Current App)": {
+          shape: rectangle
+          "User interacts here"
+        }
+
+        "Member App 2": {
+          shape: rectangle
+        }
+
+        "Master App" -> "Member App 1 (Current App)": "Shares user session"
+        "Master App" -> "Member App 2": "Shares user session"
+
+        User: {
+          shape: person
+        }
+
+        User -> "Member App 1 (Current App)": "Logs in via Master App"
+      }
+
+      ```
+  - 当存在多层容器节点嵌套时，外层的容器节点应该使用 `grid-columns: 1`，这一点非常重要
+    - bad:
+      ```d2
+      direction: down
+
+      "User Account": {
+        shape: person
+      }
+
+      "Sessions": {
+        shape: package
+        grid-columns: 3
+
+        "Web Browser Session": {
+          shape: rectangle
+          "IP: 192.168.1.10"
+          "UA: Chrome on macOS"
+          "Status: online"
+        }
+
+        "iOS App Session": {
+          shape: rectangle
+          "IP: 10.0.0.5"
+          "UA: MyApp/1.2 iOS"
+          "Status: online"
+        }
+
+        "Old Laptop Session": {
+          shape: rectangle
+          "IP: 172.16.0.20"
+          "UA: Firefox on Windows"
+          "Status: expired"
+        }
+      }
+
+      "User Account" -> "Sessions": "Has multiple"
+      ```
+    - good:
+      ```d2
+      direction: down
+
+      "User Account": {
+        shape: person
+      }
+
+      "Sessions": {
+        shape: package
+        grid-columns: 1
+
+        "Web Browser Session": {
+          shape: rectangle
+          "IP: 192.168.1.10"
+          "UA: Chrome on macOS"
+          "Status: online"
+        }
+
+        "iOS App Session": {
+          shape: rectangle
+          "IP: 10.0.0.5"
+          "UA: MyApp/1.2 iOS"
+          "Status: online"
+        }
+
+        "Old Laptop Session": {
+          shape: rectangle
+          "IP: 172.16.0.20"
+          "UA: Firefox on Windows"
+          "Status: expired"
+        }
+      }
+
+      "User Account" -> "Sessions": "Has multiple"
+      ```
+  - 当一个节点容器中包含了其他的节点容器，建议使用 `grid-gap` 来增加各个节点容器的距离，尽量大于 100
+    - bad:
+      ```d2
+      direction: down
+
+      "Your Application": {
+        shape: rectangle
+      }
+
+      "SDK: @blocklet/js-sdk": {
+        shape: package
+        grid-columns: 1
+
+        "HTTP Clients": {
+          shape: rectangle
+          grid-columns: 2
+          "createAxios()": "Axios-based client"
+          "createFetch()": "Fetch-based client"
+        }
+
+        "Core Services": {
+          shape: rectangle
+          grid-columns: 3
+          "AuthService": "User & Auth"
+          "TokenService": "Token Management"
+          "UserSessionService": "Session Data"
+          "BlockletService": "Blocklet Metadata"
+          "FederatedService": "Federated Login"
+        }
+
+        "HTTP Clients" -> "Core Services".TokenService: "Uses for auth tokens"
+      }
+
+      "Blocklet Services": {
+        shape: cylinder
+        "Remote APIs"
+      }
+
+      "Your Application" -> "SDK: @blocklet/js-sdk": "Imports & Initializes"
+      "SDK: @blocklet/js-sdk" -> "Blocklet Services": "Makes authenticated requests"
+      ```
+    - bad:
+      ```d2
+      direction: down
+
+      "Your Application": {
+        shape: rectangle
+      }
+
+      "SDK: @blocklet/js-sdk": {
+        shape: package
+        grid-columns: 1
+        grid-gap: 100
+
+        "HTTP Clients": {
+          shape: rectangle
+          grid-columns: 2
+          "createAxios()": "Axios-based client"
+          "createFetch()": "Fetch-based client"
+        }
+
+        "Core Services": {
+          shape: rectangle
+          grid-columns: 3
+          "AuthService": "User & Auth"
+          "TokenService": "Token Management"
+          "UserSessionService": "Session Data"
+          "BlockletService": "Blocklet Metadata"
+          "FederatedService": "Federated Login"
+        }
+
+        "HTTP Clients" -> "Core Services".TokenService: "Uses for auth tokens"
+      }
+
+      "Blocklet Services": {
+        shape: cylinder
+        "Remote APIs"
+      }
+
+      "Your Application" -> "SDK: @blocklet/js-sdk": "Imports & Initializes"
+      "SDK: @blocklet/js-sdk" -> "Blocklet Services": "Makes authenticated requests"
+      ```
+  - 如果节点的 `shape: person`，则不要加任何其他内部的文字
+    - bad:
+      ```d2
+      "User Account": {
+        shape: person
+        "did:z... (John Doe)"
+      }
+      ```
+    - good:
+      ```d2
+      "User Account": {
+        shape: person
+      }
+      ```
+  - 示例参考：
+    {% include "diy-examples.md" %}

package/prompts/document/d2-chart/shape-rules.md

@@ -0,0 +1,182 @@
+# D2 图表绘制 Shape 选择指南与 Prompt 模板
+
+## 一、D2 Shape 类型与使用场景
+
+### 基础 Shape 类型
+- **rectangle** (默认): 通用节点、组件、系统模块
+- **square**: 数据库、存储、配置项
+- **circle**: 用户、角色、状态节点
+- **oval**: 开始/结束节点、事件
+- **diamond**: 决策节点、条件判断
+- **parallelogram**: 输入/输出、数据流
+- **hexagon**: 准备、预处理步骤
+- **cylinder**: 数据库、数据存储
+- **queue**: 消息队列、缓冲区
+- **package**: 模块、包、容器
+- **step**: 流程步骤
+- **callout**: 注释、说明
+- **stored_data**: 存储的数据
+- **person**: 用户、角色
+- **diamond**: 判断、网关
+- **document**: 文档、报告
+- **multiple_document**: 多个文档
+- **class**: 类定义
+- **sql_table**: 数据库表
+- **image**: 图片、媒体
+
+## 二、针对不同图表类型的 Prompt 模板
+
+### 1. 系统架构图 Prompt
+```
+请使用 D2 语法绘制系统架构图，遵循以下 shape 选择规则：
+- 用户/角色使用 person 或 circle
+- 前端应用使用 rectangle
+- API/服务使用 rectangle 
+- 数据库使用 cylinder 或 sql_table
+- 缓存使用 queue
+- 外部服务使用 package
+- 负载均衡器使用 diamond
+
+示例结构：
+用户 -> 前端 -> API网关 -> 微服务 -> 数据库
+```
+
+### 2. 流程图 Prompt
+```
+请使用 D2 语法绘制流程图，严格按照以下 shape 约定：
+- 开始/结束节点：oval
+- 处理步骤：rectangle
+- 判断节点：diamond
+- 输入/输出：parallelogram
+- 准备步骤：hexagon
+- 文档生成：document
+- 数据存储：cylinder
+
+连接线使用箭头表示流向，判断节点要标注 yes/no 分支。
+```
+
+### 3. 数据流图 Prompt
+```
+使用 D2 绘制数据流图，shape 选择原则：
+- 外部实体：square
+- 数据处理：circle
+- 数据存储：stored_data 或 cylinder
+- 数据流：带标签的箭头连接
+- 数据文件：document
+
+确保数据流方向清晰，标注数据类型和流向。
+```
+
+### 4. 组织架构图 Prompt
+```
+创建组织架构图，使用以下 D2 shape 规范：
+- 高层管理：person (设置较大尺寸)
+- 部门负责人：person
+- 团队/部门：package
+- 具体角色：circle
+- 外部合作方：rectangle (虚线边框)
+
+使用层次布局，体现汇报关系。
+```
+
+## 三、通用优化 Prompt 模板
+
+### 基础模板
+```
+请使用 D2 语法创建 [图表类型]，要求：
+
+1. **Shape 选择原则**：
+   - 根据元素功能选择最合适的 shape
+   - 保持同类元素使用相同 shape
+   - 重要元素可以使用特殊 shape 突出
+
+2. **样式要求**：
+   - 使用合适的颜色区分不同类型的元素
+   - 重要路径使用加粗或特殊颜色
+   - 添加适当的标签和注释
+
+3. **布局优化**：
+   - 使用合理的布局算法 (dagre, elk等)
+   - 避免连线交叉
+   - 保持整体美观和可读性
+
+4. **语法规范**：
+   - 使用正确的 D2 语法
+   - 节点命名简洁明了
+   - 连接关系清晰表达
+
+请提供完整的 D2 代码。
+```
+
+### 高级定制模板
+```
+创建专业级 D2 图表，具体要求：
+
+**图表信息**：[描述你要创建的图表]
+
+**定制要求**：
+1. **Shape 策略**：
+   - 为每种元素类型指定最佳 shape
+   - 列出 shape 选择理由
+   - 确保视觉一致性
+
+2. **颜色方案**：
+   - 使用企业级配色
+   - 不同模块用不同颜色区分
+   - 突出关键路径
+
+3. **高级功能**：
+   - 添加图标 (如需要)
+   - 使用容器分组相关元素
+   - 添加交互提示 (tooltip)
+
+4. **性能考虑**：
+   - 节点数量控制在合理范围
+   - 避免过于复杂的嵌套
+
+输出格式：
+- D2 代码
+- Shape 选择说明
+- 使用建议
+```
+
+## 四、特定场景 Prompt 示例
+
+### 网络拓扑图
+```
+绘制网络拓扑图，shape 使用规范：
+- 路由器：diamond
+- 交换机：rectangle  
+- 服务器：rectangle (填充色)
+- 终端设备：circle
+- 防火墙：hexagon
+- 云服务：package
+- 网络连接：实线
+- 无线连接：虚线
+```
+
+### 微服务架构图
+```
+设计微服务架构图：
+- API Gateway：diamond
+- 微服务：rectangle
+- 数据库：cylinder
+- 缓存：queue
+- 消息队列：queue (不同颜色)
+- 负载均衡：parallelogram
+- 监控服务：circle
+- 外部服务：package (虚线边框)
+```
+
+### 业务流程图
+```
+业务流程建模：
+- 开始事件：oval (绿色)
+- 结束事件：oval (红色)  
+- 用户任务：rectangle
+- 系统任务：rectangle (不同颜色)
+- 网关决策：diamond
+- 并行网关：diamond (特殊标记)
+- 数据对象：document
+- 消息流：虚线箭头
+```

package/prompts/document/detail-generator.md

@@ -15,7 +15,7 @@
 - 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
 - 参数优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
 - 接口/方法调用的说明必须包含 **响应数据示例**
-- 更多的使用 table、d2 图表来解释信息，过长的文本描述会让用户阅读有压力
+- 尽可能少的使用 d2 图表，图表中错误的逻辑会导致文档效果更差，绘制 d2 的图表一定要确保可读性和正确性
 - 概览部分，建议包含 d2 图表展示产品架构图
 {% include "d2-chart/rules.md" %}
 - 对输出的 markdown 进行检查，确认输出内容完整，table、d2 信息完整并且格式正确

package/utils/constants.mjs

@@ -513,30 +513,10 @@ export const RESOLUTION_STRATEGIES = {
 export const D2_CONFIG = `vars: {
   d2-config: {
     layout-engine: elk
-    theme-id: 0
+    theme-id: 300
     theme-overrides: {
-      N1: "#2AA7A1"
-      N2: "#73808C"
-
-      N4: "#FFFFFF"
-      N5: "#FAFBFC"
-
-      N7: "#ffffff"
-
-      B1: "#8EDDD9"
-      B2: "#C9DCE6"
-      B3: "#EEF9F9"
-      B4: "#F7F8FA"
-      B5: "#FCFDFD"
-      B6: "#E3E9F0"
-
-
-      AA2: "#9EB7C5"
-      AA4: "#E3EBF2"
-      AA5: "#F6FAFC"
-
-      AB4: "#B8F1F6"
-      AB5: "#E3F8FA"
+      AA4: "#90EFDF"
+      AA5: "#D2FFF7"
     }
   }
 }`;