chore(docs): update docus (#216)

* chore(docs): update docus

* feat: add cli kb

* update trouble shooting

* fix picture bugs

Author: yaozheng-fang

docs/content/1.introduction/4.troubleshooting.md

@@ -33,3 +33,7 @@ navigation:
 
 2. **安装依赖失败，显示依赖安装空间不足**
    - VeFaaS 最大依赖安装大小默认为 250 MB，若需更大空间，请联系 VeFaaS 产品团队扩容。
+
+3. **显示`[apig_gateway][][get_info][Error] ExceededQuota`**
+   - ![网关超额报错](/images/troubleshooting-03.jpeg)
+   - 火山引擎 APIG 中，Serveless 类型的网关实例最多只能有1个。需要指定唯一的网关实例。

docs/content/3.agent/1.agent.md

@@ -93,55 +93,7 @@ print(response) # 北京天气晴朗，气温25°C。
 
 下面提供了不同类型工作流智能体的定义方法：
 
-#### 顺序类 `SequentialAgent`
-
-#### 循环类 `LoopAgent`
-
-```python [loop_agent.py]
-
-```
-
-#### 并行类 `ParallelAgent`
-
-```python [parallel_agent.py]
-
-```
-
-### 选项
-
-工作流 Agent 采用统一的参数：
-
-::field-group
-  ::field{name="name" type="string"}
-  智能体的名称
-  ::
-
-  ::field{name="description" type="string"}
-  默认为 `DEFAULT_DESCRIPTION` - 智能体的描述，在 A2A 场景下会有帮助
-  ::
-
-  ::field{name="instruction" type="string"}
-  默认为 `DEFAULT_INSTRUCTION` - 智能体的指令，例如函数调用的原则
-  ::
-
-  ::field{name="sub_agents" type="list[BaseAgent]"}
-  默认为 `[]` - 提供给该智能体的子智能体列表
-  ::
-
-  ::field{name="tracers" type="list[BaseTracer]"}
-  默认为 `[]` - 提供给该智能体的 tracer
-  ::
-::
-
-::note
-更多兼容字段请参考 [Google ADK Agents 定义](https://github.com/google/adk-python/blob/main/src/google/adk/agents/)。
-::
-
-## 多智能体协作
-
-使用 VeADK 可以构建多 Agent 协作， 主 Agent 通过 `sub_agents` 机制协调多个子 Agent 完成复杂任务。
-
-### 自主决策 Agent
+#### LLM 模式
 
 利用能够自主决策的 Agent 来定义一个生活提醒智能体，分别定义了三个智能体：
 
@@ -182,9 +134,9 @@ print(response)
 # It's a comfortable and warm day. You can choose light and breathable clothes. For example, a short - sleeved T - shirt or a thin shirt paired with casual pants or a skirt would be great. Since it's sunny, don't forget to wear a hat and sunglasses to protect yourself from the sun. Also, you can carry a light jacket in case the temperature drops in the evening, but it might not be necessary. Enjoy your day in Beijing!
 ```
 
-### `SequentialAgent`
+#### 顺序类 `SequentialAgent`
 
-```python [sequential_agent.py]
+```python[seq_agent.py]
 import asyncio
 
 from veadk import Agent, Runner
@@ -210,14 +162,106 @@ response = asyncio.run(runner.run("你好"))
 print(response)
 ```
 
-### `LoopAgent`
+#### 循环类 `LoopAgent`
 
 ```python [loop_agent.py]
+import asyncio
+from veadk import Agent, Runner
+from veadk.agents.loop_agent import LoopAgent
+from google.adk.tools.tool_context import ToolContext
+
+def exit_loop(tool_context: ToolContext):
+  print(f"  [Tool Call] exit_loop triggered by {tool_context.agent_name}")
+  tool_context.actions.escalate = True
+  return {}
+
+planner_agent = Agent(
+    name="planner_agent",
+    description="Decomposes a complex task into smaller actionable steps.",
+    instruction=(
+        "Given the user's goal and current progress, decide the NEXT step to take. You don't need to execute the step, just describe it clearly. "
+        "If all steps are done, respond with 'TASK COMPLETE'."
+    ),
+)
 
+executor_agent = Agent(
+    name="executor_agent",
+    description="Executes a given step and returns the result.",
+    instruction="Execute the provided step and describe what was done or what result was obtained. If you received 'TASK COMPLETE', you must call the 'exit_loop' function. Do not output any text.",
+    tools=[exit_loop],
+)
+
+root_agent = LoopAgent(
+    sub_agents=[planner_agent, executor_agent],
+    max_iterations=3,  # Limit the number of loops to prevent infinite loops
+)
+
+runner = Runner(root_agent)
+
+response = asyncio.run(runner.run("帮我写一首三行的小诗，主题是秋天"))
+
+print(response)
 ```
 
-### `ParallelAgent`
+#### 并行类 `ParallelAgent`
 
 ```python [parallel_agent.py]
+import asyncio
+
+from veadk import Agent, Runner
+from veadk.agents.parallel_agent import ParallelAgent
+
+pros_agent = Agent(
+    name="pros_agent",
+    description="An expert that identifies the advantages of a topic.",
+    instruction="List and explain the positive aspects or advantages of the given topic.",
+)
 
+cons_agent = Agent(
+    name="cons_agent",
+    description="An expert that identifies the disadvantages of a topic.",
+    instruction="List and explain the negative aspects or disadvantages of the given topic.",
+)
+
+root_agent = ParallelAgent(sub_agents=[pros_agent, cons_agent])
+
+runner = Runner(root_agent)
+
+response = asyncio.run(runner.run("请分析 LLM-as-a-Judge 这种评测模式的优劣"))
+
+print(response)
 ```
+
+### 选项
+
+工作流 Agent 采用统一的参数：
+
+::field-group
+  ::field{name="name" type="string"}
+  智能体的名称
+  ::
+
+  ::field{name="description" type="string"}
+  默认为 `DEFAULT_DESCRIPTION` - 智能体的描述，在 A2A 场景下会有帮助
+  ::
+
+  ::field{name="instruction" type="string"}
+  默认为 `DEFAULT_INSTRUCTION` - 智能体的指令，例如函数调用的原则
+  ::
+
+  ::field{name="sub_agents" type="list[BaseAgent]"}
+  默认为 `[]` - 提供给该智能体的子智能体列表
+  ::
+
+  ::field{name="tracers" type="list[BaseTracer]"}
+  默认为 `[]` - 提供给该智能体的 tracer
+  ::
+::
+
+::note
+更多兼容字段请参考 [Google ADK Agents 定义](https://github.com/google/adk-python/blob/main/src/google/adk/agents/)。
+::
+
+## 多智能体协作
+
+使用 VeADK 可以构建多 Agent 协作， 主 Agent 通过 `sub_agents` 机制协调多个子 Agent 完成复杂任务。

docs/content/6.memory/3.long-term-memory.md

@@ -12,39 +12,47 @@ VeADK 的长期记忆通常存储在数据库中，通过如下方式定义一
 ```python
 from veadk.memory.long_term_memory import LongTermMemory
 
-long_term_memory = LongTermMemory()
+# 由于长期记忆需要构建索引，因此你必须在初始化长期记忆时定义 `app_name` 以及 `user_id`
+long_term_memory = LongTermMemory(app_name="my_app_name", user_id="user_id")
 ```
 
 通过如下例子说明长期记忆：
 
 以下示例展示了如何在 VeADK 中使用长期记忆实现跨会话的信息保留与调用。开发者可以通过 `save_session_to_long_term_memory` 方法，将某一会话中的知识性信息存入长期记忆存储后端。在新的会话中，即使上下文为空，Agent 依然能够基于长期记忆准确回忆并回答相关问题。
 
 ```python
+import asyncio
+
 from veadk import Agent, Runner
 from veadk.memory.long_term_memory import LongTermMemory
-from veadk.memory.short_term_memory import ShortTermMemory
 
-session_id = "..."
-new_session_id = "..."
+app_name = "ltm_demo"
+user_id = "temp_user"
+
+teaching_session_id = "teaching_session"
+student_session_id = "student_session"
+
+long_term_memory = LongTermMemory(backend="local", app_name=app_name, user_id=user_id)
 
-long_term_memory = LongTermMemory(backend=...)  # default backend is `opensearch`
-agent = Agent(long_term_memory=long_term_memory) # agent with long term memort backend
+agent = Agent(long_term_memory=long_term_memory)
 
 runner = Runner(
     agent=agent,
-    app_name="...",
-    user_id="...",
-    short_term_memory=ShortTermMemory(),
+    app_name=app_name,
+    user_id=user_id,
 )
-teaching_prompt = "..."
-await runner.run(messages=teaching_prompt, session_id=session_id)
+
+teaching_prompt = "My secret is 0xabcd"
+asyncio.run(runner.run(messages=teaching_prompt, session_id=teaching_session_id))
 
 # save the teaching prompt and answer in long term memory
-await runner.save_session_to_long_term_memory(session_id=session_id)
+asyncio.run(runner.save_session_to_long_term_memory(session_id=teaching_session_id))
 
 # now, let's validate this in a new session
-student_prompt = "..."
-response = await runner.run(messages=student_prompt, session_id=new_session_id)
+student_prompt = "What is my secret?"
+response = asyncio.run(
+    runner.run(messages=student_prompt, session_id=student_session_id)
+)
 print(response)
 ```
 

docs/content/90.cli/1.overview.md

@@ -14,3 +14,4 @@ VeADK 提供如下命令便捷您的操作：
 | `veadk prompt` | 优化智能体系统提示词 | 借助火山引擎 PromptPilot 产品 |
 | `veadk web` | 支持长短期记忆、知识库的前端调试界面 | 兼容 Google ADK web |
 | `veadk eval` | 支持不同后端的评测 | 评测后端包括 `adk` 与 `deepeval`，评测数据集源包括 Google ADK 评测集格式文件，以及 Tracing 文件 |
+| `veadk kb` | 知识库相关操作 | 向知识库添加本地文件或目录 |

docs/content/90.cli/2.commands.md

@@ -84,3 +84,45 @@ veadk web --session_service_uri="mysql+pymysql://{user}:{password}@{host}/{datab
   火山引擎 Secret Key
   ::
 ::
+
+## 知识库操作
+
+您可以通过 `veadk kb add` 命令来向您的知识库添加本地文件或者目录。例如，准备如下目录：
+
+::code-tree{default-value="knowledges/id.txt"}
+
+```txt [knowledges/id.txt]
+My id is 20250101.
+```
+
+::
+
+之后，将 `knowledges/id.txt` 中的内容存入到 OpenSearch 知识库中：
+
+```bash
+# 知识库的相关配置将会从环境变量中读取
+veadk kb add --backend opensearch --app_name=cmd_app --path=./knowledges
+```
+
+可使用如下代码测试：
+
+```python
+import asyncio
+
+from veadk import Agent, Runner
+from veadk.knowledgebase import KnowledgeBase
+
+app_name = "cmd_app"
+
+knowledgebase = KnowledgeBase(backend="opensearch", app_name=app_name)
+
+agent = Agent(knowledgebase=knowledgebase)
+
+runner = Runner(agent=agent, app_name=app_name)
+
+response = asyncio.run(
+    runner.run(messages="Please help me to fetch my ID from my knowledgebase")
+)
+
+print(response) # Your ID is 20250101.
+```

docs/nuxt.config.js

@@ -3,5 +3,8 @@ export default {
   extends: ['docus'],
   app: {
     baseURL: '/veadk-python/'
+  },
+  image: {
+    provider: 'none' // 禁用 IPX 图片优化
   }
 }

docs/public/images/troubleshooting-03.jpeg

@@ -18,6 +18,7 @@
 from veadk.cli.cli_deploy import deploy
 from veadk.cli.cli_eval import eval
 from veadk.cli.cli_init import init
+from veadk.cli.cli_kb import kb
 from veadk.cli.cli_pipeline import pipeline
 from veadk.cli.cli_prompt import prompt
 from veadk.cli.cli_web import web
@@ -39,6 +40,7 @@ def veadk():
 veadk.add_command(web)
 veadk.add_command(pipeline)
 veadk.add_command(eval)
+veadk.add_command(kb)
 
 if __name__ == "__main__":
     veadk()