feat(eino): update docs and optimize mermaid rendering (#1501)

Author: shentongmartin

assets/js/mermaid.js

@@ -2,37 +2,31 @@
 {{ if .enable }}
 (function($) {
     var needMermaid = false;
+    function parseFrontMatter(text) {
+        var m = text.match(/^\s*---\s*[\r\n]([\s\S]*?)[\r\n]---\s*[\r\n]?/);
+        if (!m) return { cfg: null, body: text };
+        var yamlStr = m[1];
+        var doc = null;
+        try {
+            if (window.jsyaml && typeof window.jsyaml.load === 'function') {
+                doc = window.jsyaml.load(yamlStr);
+            } else {
+                doc = JSON.parse(yamlStr);
+            }
+        } catch (e) {
+            console.warn('Mermaid front matter parse failed, fallback to global settings:', e);
+            return { cfg: null, body: text.replace(m[0], '') };
+        }
+        var cfg = doc && typeof doc === 'object' && doc.config ? doc.config : doc;
+        return { cfg: cfg, body: text.replace(m[0], '') };
+    }
+
     function preprocessMermaid(text) {
-        var fm = text.match(/^\s*---\s*\n([\s\S]*?)\n---\s*\n?/);
+        var fm = parseFrontMatter(text);
         var directive = '';
-        var body = text;
-        if (fm) {
-            var yaml = fm[1];
-            var obj = {};
-            var current = null;
-            yaml.split('\n').forEach(function(line) {
-                var l = line.trim();
-                if (!l) return;
-                if (/^[\w-]+\s*:\s*$/.test(l)) {
-                    current = l.replace(/:\s*$/, '').trim();
-                    obj[current] = obj[current] || {};
-                    return;
-                }
-                var m = l.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
-                if (m) {
-                    var k = m[1];
-                    var v = m[2].trim();
-                    v = v.replace(/^['"]|['"]$/g, '');
-                    if (current) {
-                        obj[current][k] = v;
-                    } else {
-                        obj[k] = v;
-                    }
-                }
-            });
-            var cfg = obj.config || obj;
-            directive = '%%{init: ' + JSON.stringify(cfg) + '}%%\n';
-            body = text.replace(fm[0], '');
+        var body = fm.body;
+        if (fm.cfg && typeof fm.cfg === 'object' && Object.keys(fm.cfg).length > 0) {
+            directive = '%%{init: ' + JSON.stringify(fm.cfg) + '}%%\n';
         }
         var isV10 = typeof mermaid !== 'undefined' && mermaid.version && parseInt(mermaid.version.split('.')[0], 10) >= 10;
         body = body.replace(/<br\s*\/?>(?![^`]*`)/gi, '\\n');

content/en/docs/eino/Eino: Cookbook.md

@@ -1,10 +1,10 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: FAQ
-weight: 6
+weight: 7
 ---
 
 # Q: cannot use openapi3.TypeObject (untyped string constant "object") as *openapi3.Types value in struct literal，cannot use types (variable of type string) as *openapi3.Types value in struct literal

content/en/docs/eino/FAQ.md

@@ -4,7 +4,7 @@ date: "2025-07-21"
 lastmod: ""
 tags: []
 title: 'Eino: Core Modules'
-weight: 3
+weight: 4
 ---
 
 Eino’s core modules include the following parts:

content/en/docs/eino/core_modules/_index.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: 'Eino: Callback Manual'
@@ -155,7 +155,7 @@ Inject Handlers at graph runtime through `compose.WithCallbacks`, these Handlers
 
 Inject Handlers to a specific Node of the top-level Graph through `compose.WithCallbacks(...).DesignateNode(...)`. When this Node itself is a nested Graph, it will be injected into this nested Graph itself and its internal Nodes.
 
-Inject Handlers to a specific Node of an internally nested Graph through `compose.WithCallbacks(...).DesignateNodeForPath(...)`.
+Inject Handlers to a specific Node of an internally nested Graph through `compose.WithCallbacks(...).DesignateNodeWithPath(...)`.
 
 ### Injecting Handlers Outside Graph
 

content/en/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: Eino Streaming Essentials

content/en/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: 'Eino: Retriever Guide'

content/en/docs/eino/core_modules/components/retriever_guide.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: How to Create a Tool
@@ -41,7 +41,7 @@ type StreamableTool interface {
 
 ## ToolInfo Representations
 
-In LLM function-call flows, the model must understand whether generated parameters satisfy constraints. Eino supports two representations: `params map[string]*ParameterInfo` and `*openapi3.Schema`.
+In LLM function-call flows, the model must understand whether generated parameters satisfy constraints. Based on developer habits and domain standards, Eino provides two representations: `params map[string]*ParameterInfo` and `JSON Schema`.
 
 ### 1) `map[string]*ParameterInfo`
 
@@ -77,26 +77,27 @@ map[string]*schema.ParameterInfo{
 }
 ```
 
-### 2) JSON Schema (2020-12)
+### 2) JSON Schema
 
-JSON Schema’s constraint system is rich. In practice, you usually generate it from struct tags or helper functions.
+Another common way to represent parameter constraints is `JSON Schema`: [https://json-schema.org/draft/2020-12](https://json-schema.org/draft/2020-12).
 
-#### `GoStruct2ParamsOneOf`
+The JSON Schema standard provides very rich ways to constrain parameters. In practice, developers generally don't construct this structure themselves, but use methods to generate it.
 
-Describe constraints via Go tags on a struct and generate `ParamsOneOf`:
+#### Using GoStruct2ParamsOneOf
+
+Eino provides a way to describe parameter constraints through go tags in structs, and provides the GoStruct2ParamsOneOf method to generate parameter constraints for a struct:
 
 ```go
 func GoStruct2ParamsOneOf[T any](opts ...Option) (*schema.ParamsOneOf, error)
 ```
 
-Supported tags:
+The tags used to extract parameter field names and descriptions from T are as follows:
 
-- `jsonschema_description:"xxx"` [recommended] or `jsonschema:"description=xxx"`
-- Note: descriptions often include commas; tag commas separate fields and cannot be escaped. Prefer `jsonschema_description`.
-- `jsonschema:"enum=xxx,enum=yyy,enum=zzz"`
-- `jsonschema:"required"`
-- `json:"xxx,omitempty"` → `omitempty` implies not required
-- Customize via `utils.WithSchemaModifier`
+- jsonschema_description:"xxx" [recommended] or jsonschema:"description=xxx"
+  - Descriptions often contain commas, and commas in tags are separators for different fields and cannot be escaped. It's strongly recommended to use the separate jsonschema_description tag.
+- jsonschema:"enum=xxx,enum=yyy,enum=zzz"
+- Fields are required by default; json:"xxx,omitempty" => use json tag's omitempty to indicate not required
+- Use utils.WithSchemaModifier to implement custom parsing methods
 
 Example:
 
@@ -109,7 +110,7 @@ import (
 )
 
 type User struct {
-    Name   string `json:"name" jsonschema_description=the name of the user jsonschema:"required"`
+    Name   string `json:"name,omitempty" jsonschema_description=the name of the user`
     Age    int    `json:"age" jsonschema_description:"the age of the user"`
     Gender string `json:"gender" jsonschema:"enum=male,enum=female"`
 }
@@ -119,7 +120,7 @@ func main() {
 }
 ```
 
-You usually won't call this directly; prefer `utils.GoStruct2ToolInfo()` or `utils.InferTool()`.
+This method is generally not called by developers directly; instead, use `utils.GoStruct2ToolInfo()` to build ToolInfo, or use `utils.InferTool()` directly to build a tool. See the "Converting local functions to tools" section below for details.
 
 ## Ways to Implement a Tool
 
@@ -238,9 +239,9 @@ import (
 )
 
 type User struct {
-    Name   string `json:"name" jsonschema:"required,description=the name of the user"`
-    Age    int    `json:"age" jsonschema:"description=the age of the user"`
-    Gender string `json:"gender" jsonschema:"enum=male,enum=female"`
+    Name   string `json:"name" jsonschema:"description=the name of the user"`
+    Age    int    `json:"age,omitempty" jsonschema:"description=the age of the user"`
+    Gender string `json:"gender,omitempty" jsonschema:"enum=male,enum=female"`
 }
 
 type Result struct {
@@ -256,9 +257,9 @@ func createTool() (tool.InvokableTool, error) {
 }
 ```
 
-#### `InferOptionableTool`
+#### Using InferOptionableTool
 
-Eino’s Option mechanism passes dynamic runtime parameters. Details: `Eino: CallOption capabilities and conventions` at `/docs/eino/core_modules/chain_and_graph_orchestration/call_option_capabilities`. The same mechanism applies to custom tools.
+The Option mechanism is a mechanism provided by Eino for passing dynamic parameters at runtime. For details, see [Eino: CallOption Capabilities and Conventions](/docs/eino/core_modules/chain_and_graph_orchestration/call_option_capabilities). This mechanism also applies to custom tools.
 
 When you need custom option parameters, use `InferOptionableTool`:
 
@@ -310,10 +311,7 @@ func useInInvoke() {
 
 ### Approach 3 — Use tools from eino-ext
 
-Beyond custom tools, the `eino-ext` project provides many ready-to-use implementations: `Googlesearch`, `DuckDuckGoSearch`, `wikipedia`, `httprequest`, etc. See implementations at https://github.com/cloudwego/eino-ext/tree/main/components/tool and docs:
-
-- Tool — Googlesearch: `/docs/eino/ecosystem_integration/tool/tool_googlesearch`
-- Tool — DuckDuckGoSearch: `/docs/eino/ecosystem_integration/tool/tool_duckduckgo_search`
+Beyond custom tools that need to be implemented yourself, the eino-ext project has many general-purpose tool implementations that can be used out of the box, such as [Tool - Googlesearch](/docs/eino/ecosystem_integration/tool/tool_googlesearch), [Tool - DuckDuckGoSearch](/docs/eino/ecosystem_integration/tool/tool_duckduckgo_search), wikipedia, httprequest, etc. See various implementations at [https://github.com/cloudwego/eino-ext/tree/main/components/tool](https://github.com/cloudwego/eino-ext/tree/main/components/tool).
 
 ### Approach 4 — Use MCP protocol
 

content/en/docs/eino/core_modules/components/tools_node_guide/how_to_create_a_tool.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: 'Eino ADK: Quickstart'

content/en/docs/eino/core_modules/eino_adk/agent_quickstart.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2026-01-20"
+date: "2026-01-30"
 lastmod: ""
 tags: []
 title: 'Eino: ReAct Agent Manual'