chore: import upstream snapshot with attribution

docs/user_guide/zh/modules/tooling/function.md

@@ -0,0 +1,80 @@
+# Function Tooling 配置指南
+
+`FunctionToolConfig` 允许 Agent 节点调用仓库中的 Python 函数。相关代码位于 `entity/configs/tooling.py`、`utils/function_catalog.py` 以及 `functions/function_calling/`。
+
+## 1. 配置字段
+| 字段 | 说明 |
+| --- | --- |
+| `tools` | 列表，元素为 `FunctionToolEntryConfig`。每个条目至少包含 `name`。|
+| `timeout` | 单次工具执行的超时时间（秒）。|
+
+`FunctionToolEntryConfig` 字段：
+- `name`：函数名，来自 `functions/function_calling/` 文件的顶级函数。
+
+### 函数列表展示与 `module_name:All`
+- UI 下拉列表会将每个函数展示为 `module_name:function_name`。`module_name` 等于函数文件相对于 `functions/function_calling/` 的路径（去掉 `.py`，子目录使用 `/` 连接），便于快速定位语义相关模块。
+- 每个模块顶部都会自动插入 `module_name:All` 选项，并且所有模块的 `All` 条目按照字典序排在列表最前。选择该项时会在解析阶段展开为该模块下的所有函数，顺序同样遵循字典序。
+- `module_name:All` 只能批量引入函数，禁止同时填写 `description`、`parameters` 或 `auto_fill` 等覆盖字段；若需要自定义，请展开后针对具体函数单独配置。
+- 函数与模块都采用全局字典序排列，使长列表更易检索；YAML 中仍然以真实函数名落盘，`module_name:All` 仅作为输入辅助。
+
+## 2. 函数目录要求
+- 路径：`functions/function_calling/`（可通过 `MAC_FUNCTIONS_DIR` 覆盖）。
+- 每个函数：
+  - 必须位于模块顶层。
+  - 使用 Python 类型注解；若需枚举或描述，可使用 `typing.Annotated[..., ParamMeta(...)]`。
+  - 不允许以 `_` 开头的参数暴露给 Agent；`*_args`、`**kwargs` 会被过滤。
+  - 可以通过 docstring 的首段提供描述（自动截断为 600 字符）。
+- `utils/function_catalog.py` 会在启动时生成 JSON Schema，并向前端/CLI 暴露。
+
+## 3. 上下文注入
+执行器会对被调用的函数提供 `_context` 关键字参数，包含：
+| 键 | 值 |
+| --- | --- |
+| `attachment_store` | `utils.attachments.AttachmentStore` 实例，可查询/注册附件。|
+| `python_workspace_root` | 当前 Session 的 `code_workspace/`。|
+| `graph_directory` | Session 根目录，可推导相对路径。|
+| `human_prompt` | `utils.human_prompt.HumanPromptService`，可调用 `request()` 触发人工反馈。|
+| 其他 | 视运行环境扩展，例如 `session_id`、`node_id`。|
+
+函数可声明 `_context: dict | None = None` 并自行解析（参考 `functions/function_calling/file.py` 中的 `FileToolContext`，还可参考 `functions/function_calling/user.py`）。
+
+## 4. 示例：文件读取工具
+```python
+from typing import Annotated
+from utils.function_catalog import ParamMeta
+
+
+def read_text_file(
+    path: Annotated[str, ParamMeta(description="workspace 相对路径")],
+    *,
+    encoding: str = "utf-8",
+    _context: dict | None = None,
+) -> str:
+    ctx = FileToolContext(_context)
+    target = ctx.resolve_under_workspace(path)
+    return target.read_text(encoding=encoding)
+```
+在 YAML 中引用：
+```yaml
+nodes:
+  - id: summarize
+    type: agent
+    config:
+      tooling:
+        type: function
+        config:
+          tools:
+            - name: describe_available_files
+            - name: read_text_file
+```
+
+## 5. 扩展流程
+1. 在 `functions/function_calling/` 新建模块或函数。
+2. 使用类型注解 + `ParamMeta` 描述参数；如需禁止自动 Schema，可设置 `auto_fill: false` 并提供手写 `parameters`。
+3. 若函数依赖额外第三方库，可在仓库 `requirements.txt`/`pyproject.toml` 中声明，或在函数内调用 `install_python_packages`（同目录提供）动态安装。
+4. 运行 `python -m tools.export_design_template ...` 以刷新前端枚举。
+
+## 6. 调试与排错
+- 若前端/CLI 报告 “function 'xxx' not found”，检查函数名称与文件是否位于 `MAC_FUNCTIONS_DIR`（默认 `functions/function_calling/`）。
+- `function_catalog` 加载失败时，`FunctionToolEntryConfig.field_specs()` 会在描述中提示错误，请先修复函数语法或依赖。
+- 工具运行超时会向 Agent 返回异常文本；可通过 `timeout` 扩大限额，或在函数内部自行捕获并返回友好错误。