Feat/search sirchmunk (#882)

Co-authored-by: suluyan <suluyan.sly@alibaba-inc.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

docs/en/Components/Config.md

@@ -166,3 +166,20 @@ In addition to yaml configuration, MS-Agent also supports several additional com
     ```
 
 > Any configuration in agent.yaml can be passed in with new values via command line, and also supports reading from environment variables with the same name (case insensitive), for example `--llm.modelscope_api_key xxx-xxx`.
+
+- knowledge_search_paths: Knowledge search paths, comma-separated multiple paths. When provided, automatically enables SirchmunkSearch for knowledge retrieval, with LLM configuration automatically inherited from the `llm` module.
+
+### Quick Start for Knowledge Search
+
+Use the `--knowledge_search_paths` parameter to quickly enable knowledge search based on local documents:
+
+```bash
+# Using default agent.yaml configuration, automatically reuses LLM settings
+ms-agent run --query "How to implement user authentication?" --knowledge_search_paths "./src,./docs"
+
+# Specify configuration file
+ms-agent run --config /path/to/agent.yaml --query "your question" --knowledge_search_paths "/path/to/docs"
+```
+
+LLM-related parameters (api_key, base_url, model) are automatically inherited from the `llm` module in the configuration file, no need to configure them repeatedly.
+If you need to use independent LLM configuration in the `knowledge_search` module, you can explicitly configure `knowledge_search.llm_api_key` and other parameters in the yaml.

docs/zh/Components/config.md

@@ -1,12 +1,12 @@
 ---
 slug: config
 title: 配置与参数
-description: Ms-Agent 配置与参数：类型配置、自定义代码、LLM配置、推理配置、system和query、callbacks、工具配置、其他、config_handler、命令行配置
+description: Ms-Agent 配置与参数：类型配置、自定义代码、LLM 配置、推理配置、system 和 query、callbacks、工具配置、其他、config_handler、命令行配置
 ---
 
 # 配置与参数
 
-MS-Agent使用一个yaml文件进行配置管理，通常这个文件被命名为`agent.yaml`，这样的设计使不同场景可以读取不同的配置文件。该文件具体包含的字段有：
+MS-Agent 使用一个 yaml 文件进行配置管理，通常这个文件被命名为 `agent.yaml`，这样的设计使不同场景可以读取不同的配置文件。该文件具体包含的字段有：
 
 ## 类型配置
 
@@ -17,31 +17,31 @@ MS-Agent使用一个yaml文件进行配置管理，通常这个文件被命名
 type: llmagent
 ```
 
-标识本配置对应的agent类型，支持`llmagent`和`codeagent`两类。默认为`llmagent`。如果yaml中包含了code_file字段，则code_file优先生效。
+标识本配置对应的 agent 类型，支持 `llmagent` 和 `codeagent` 两类。默认为 `llmagent`。如果 yaml 中包含了 code_file 字段，则 code_file 优先生效。
 
 ## 自定义代码
 
-> 可选，在需要自定义LLMAgent时使用
+> 可选，在需要自定义 LLMAgent 时使用
 
 ```yaml
 code_file: custom_agent
 ```
 
-可以使用一个外部agent类，该类需要继承自`LLMAgent`。可以复写其中的若干方法，如果code_file有值，则`type`字段不生效。
+可以使用一个外部 agent 类，该类需要继承自 `LLMAgent`。可以复写其中的若干方法，如果 code_file 有值，则 `type` 字段不生效。
 
-## LLM配置
+## LLM 配置
 
 > 必须存在
 
 ```yaml
 llm:
-  # 大模型服务backend
+  # 大模型服务 backend
   service: modelscope
-  # 模型id
+  # 模型 id
   model: Qwen/Qwen3-235B-A22B-Instruct-2507
-  # 模型api_key
+  # 模型 api_key
   modelscope_api_key:
-  # 模型base_url
+  # 模型 base_url
   modelscope_base_url: https://api-inference.modelscope.cn/v1
 ```
 
@@ -51,7 +51,7 @@ llm:
 
 ```yaml
 generation_config:
-  # 下面的字段均为OpenAI sdk的标准参数，你也可以配置OpenAI支持的其他参数在这里。
+  # 下面的字段均为 OpenAI sdk 的标准参数，你也可以配置 OpenAI 支持的其他参数在这里。
   top_p: 0.6
   temperature: 0.2
   top_k: 20
@@ -60,25 +60,25 @@ generation_config:
     enable_thinking: false
 ```
 
-## system和query
+## system 和 query
 
-> 可选，但推荐传入system
+> 可选，但推荐传入 system
 
 ```yaml
 prompt:
-  # LLM system，如果不传递则使用默认的`you are a helpful assistant.`
+  # LLM system，如果不传递则使用默认的 `you are a helpful assistant.`
   system:
-  # LLM初始query，通常来说可以不使用
+  # LLM 初始 query，通常来说可以不使用
   query:
 ```
 
 ## callbacks
 
-> 可选，推荐自定义callbacks
+> 可选，推荐自定义 callbacks
 
 ```yaml
 callbacks:
-  # 用户输入callback，该callback在assistant回复后自动等待用户输入
+  # 用户输入 callback，该 callback 在 assistant 回复后自动等待用户输入
   - input_callback
 ```
 
@@ -90,9 +90,9 @@ callbacks:
 tools:
   # 工具名称
   file_system:
-    # 是否是mcp
+    # 是否是 mcp
     mcp: false
-    # 排除的function，可以为空
+    # 排除的 function，可以为空
     exclude:
       - create_directory
       - write_file
@@ -104,20 +104,20 @@ tools:
       - map_geo
 ```
 
-支持的完整工具列表，以及自定义工具请参考[这里](./tools)
+支持的完整工具列表，以及自定义工具请参考 [这里](./tools)
 
 ## 其他
 
 > 可选，按需配置
 
 ```yaml
-# 自动对话轮数，默认为20轮
+# 自动对话轮数，默认为 20 轮
 max_chat_round: 9999
 
 # 工具调用超时时间，单位秒
 tool_call_timeout: 30000
 
-# 输出artifact目录
+# 输出 artifact 目录
 output_dir: output
 
 # 帮助信息，通常在运行错误后出现
@@ -127,13 +127,13 @@ help: |
 
 ## config_handler
 
-为了便于在任务开始时对config进行定制化，MS-Agent构建了一个名为`ConfigLifecycleHandler`的机制。这是一个callback类，开发者可以在yaml文件中增加这样一个配置：
+为了便于在任务开始时对 config 进行定制化，MS-Agent 构建了一个名为 `ConfigLifecycleHandler` 的机制。这是一个 callback 类，开发者可以在 yaml 文件中增加这样一个配置：
 
 ```yaml
 handler: custom_handler
 ```
 
-这代表和yaml文件同级有一个custom_handler.py文件，该文件的类继承自`ConfigLifecycleHandler`，分别有两个方法：
+这代表和 yaml 文件同级有一个 custom_handler.py 文件，该文件的类继承自 `ConfigLifecycleHandler`，分别有两个方法：
 
 ```python
     def task_begin(self, config: DictConfig, tag: str) -> DictConfig:
@@ -143,18 +143,18 @@ handler: custom_handler
         return config
 ```
 
-`task_begin`在LLMAgent类构造时生效，在该方法中可以对config进行一些修改。如果你的工作流中下游任务会继承上游的yaml配置，这个机制会有帮助。值得注意的是`tag`参数，该参数会传入当前LLMAgent的名字，方便分辨当前工作流的节点。
+`task_begin` 在 LLMAgent 类构造时生效，在该方法中可以对 config 进行一些修改。如果你的工作流中下游任务会继承上游的 yaml 配置，这个机制会有帮助。值得注意的是 `tag` 参数，该参数会传入当前 LLMAgent 的名字，方便分辨当前工作流的节点。
 
 
 ## 命令行配置
 
-在yaml配置之外，MS-Agent还支持若干额外的命令行参数。
+在 yaml 配置之外，MS-Agent 还支持若干额外的命令行参数。
 
-- query: 初始query，这个query的优先级高于yaml中的prompt.query
-- config: 配置文件路径，支持modelscope model-id
-- trust_remote_code: 是否信任外部代码。如果某个配置包含了一些外部代码，需要将这个参数置为true才会生效
-- load_cache: 从历史messages继续对话。cache会被自动存储在`output`配置中。默认为`False`
-- mcp_server_file: 可以读取一个外部的mcp工具配置，格式为：
+- query: 初始 query，这个 query 的优先级高于 yaml 中的 prompt.query
+- config: 配置文件路径，支持 modelscope model-id
+- trust_remote_code: 是否信任外部代码。如果某个配置包含了一些外部代码，需要将这个参数置为 true 才会生效
+- load_cache: 从历史 messages 继续对话。cache 会被自动存储在 `output` 配置中。默认为 `False`
+- mcp_server_file: 可以读取一个外部的 mcp 工具配置，格式为：
     ```json
     {
       "mcpServers": {
@@ -165,5 +165,21 @@ handler: custom_handler
       }
     }
     ```
+- knowledge_search_paths: 知识搜索路径，逗号分隔的多个路径。传入后会自动启用 SirchmunkSearch 进行知识检索，LLM 配置自动从 `llm` 模块复用
 
-> agent.yaml中的任意一个配置，都可以使用命令行传入新的值, 也支持从同名（大小写不敏感）环境变量中读取，例如`--llm.modelscope_api_key xxx-xxx`。
+> agent.yaml 中的任意一个配置，都可以使用命令行传入新的值，也支持从同名（大小写不敏感）环境变量中读取，例如 `--llm.modelscope_api_key xxx-xxx`。
+
+### 知识搜索快速使用
+
+通过 `--knowledge_search_paths` 参数，可以快速启用基于本地文档的知识搜索：
+
+```bash
+# 使用默认 agent.yaml 配置，自动复用 LLM 设置
+ms-agent run --query "如何实现用户认证？" --knowledge_search_paths "./src,./docs"
+
+# 指定配置文件
+ms-agent run --config /path/to/agent.yaml --query "你的问题" --knowledge_search_paths "/path/to/docs"
+```
+
+LLM 相关参数（api_key, base_url, model）会自动从配置文件的 `llm` 模块继承，无需重复配置。
+如果需要在 `knowledge_search` 模块中使用独立的 LLM 配置，可以在 yaml 中显式配置 `knowledge_search.llm_api_key` 等参数。

examples/knowledge_search/agent.yaml.example

@@ -0,0 +1,86 @@
+# Sirchmunk Knowledge Search 配置示例
+# Sirchmunk Knowledge Search Configuration Example
+
+# 在您的 agent.yaml 或 workflow.yaml 中添加以下配置：
+
+llm:
+  service: modelscope
+  model: Qwen/Qwen3-235B-A22B-Instruct-2507
+  modelscope_api_key: <your-api-key>
+  modelscope_base_url: https://api-inference.modelscope.cn/v1
+
+generation_config:
+  temperature: 0.3
+  top_k: 20
+  stream: true
+
+# Knowledge Search 配置（可选）
+# 用于在本地代码库中搜索相关信息
+knowledge_search:
+  # 必选：要搜索的路径列表
+  paths:
+    - ./src
+    - ./docs
+
+  # 可选：sirchmunk 工作目录，用于缓存
+  work_path: ./.sirchmunk
+
+  # 可选：LLM 配置（如不配置则使用上面 llm 的配置）
+  llm_api_key: <your-api-key>
+  llm_base_url: https://api.openai.com/v1
+  llm_model_name: gpt-4o-mini
+
+  # 可选：Embedding 模型
+  embedding_model: text-embedding-3-small
+
+  # 可选：聚类相似度阈值
+  cluster_sim_threshold: 0.85
+
+  # 可选：聚类 TopK
+  cluster_sim_top_k: 3
+
+  # 可选：是否重用之前的知识
+  reuse_knowledge: true
+
+  # 可选：搜索模式 (DEEP, FAST, FILENAME_ONLY)
+  mode: FAST
+
+  # 可选：最大循环次数
+  max_loops: 10
+
+  # 可选：最大 token 预算
+  max_token_budget: 128000
+
+prompt:
+  system: |
+    You are an assistant that helps me complete tasks.
+
+max_chat_round: 9999
+
+# 使用说明：
+# 1. 配置 knowledge_search 后，LLMAgent 会在处理用户请求时自动搜索本地代码库
+# 2. 搜索结果会自动添加到 user message 的 search_result 和 searching_detail 字段
+# 3. search_result 包含搜索到的相关文档，会作为上下文提供给 LLM
+# 4. searching_detail 包含搜索日志和元数据，可用于前端展示
+#
+# Python 使用示例：
+# ```python
+# from ms_agent import LLMAgent
+# from ms_agent.config import Config
+#
+# config = Config.from_task('path/to/agent.yaml')
+# agent = LLMAgent(config=config)
+# result = await agent.run('如何实现用户认证功能？')
+#
+# # 获取搜索详情（用于前端展示）
+# for msg in result:
+#     if msg.role == 'user':
+#         print(f"Search logs: {msg.searching_detail}")
+#         print(f"Search results: {msg.search_result}")
+# ```
+#
+# CLI 测试命令：
+# export LLM_API_KEY="your-api-key"
+# export LLM_BASE_URL="https://api.openai.com/v1"
+# export LLM_MODEL_NAME="gpt-4o-mini"
+# python tests/knowledge_search/test_cli.py --query "你的问题"