chat-agent-tools-spec

Tools

langchain tool 实现

langchain tools 的写法：

@tool("$toolset_$function_name:")  # 即加入 toolset name 作为前缀
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

每个 toolset 应该对应一个独立的 python 文件。文件应该放于 /src/everlingo/tools 目录。如 /src/everlingo/tools/conf_manager.py。

/src/everlingo/tools/tools.py 应该是一个可以获取所有 tools 的注册表。为 langchain agent 提供总的 tools 列表。

def get_tools() -> list:
       return [x,y,z]
   return []

tools 调用日志

每个 tool 的调用，均需要记录日志。logging level 为 debug。内容和格式如下：

tool_name: xyz , parameters: argName1=argValue1,... , return: xyz

• logger：everlingo.tools（src/everlingo/tools/__init__.py 的 log_tool_call 装饰器），经 everlingo 父 logger propagate 到 gateway 进程的 FileHandler，写入 $workspace/logs/everlingo.log。
• 默认 level：依赖 sys_setting.logging_setting.log_level，默认 debug；用户可在 everlingo.yaml 调高到 info/warn/error，此时 debug 日志被过滤（行为预期，非 bug）。
• 装饰器位置：src/everlingo/tools/__init__.py:log_tool_call，应应用于所有 toolset 工具的每个公开函数。voice_speak 为工厂函数 make_voice_speak_tool 生成的 inner function，同样需 @log_tool_call("voice_speak")。

Toolsets(工具集)

以下包括多个 toolset(工具集)。

toolset → 后端依赖映射图（[MCP] = 经 Vault MCP Server 进程间调用；[进程内] = gateway 进程内直接调用）：

vars: {
  d2-config: {
    layout-engine: elk
    theme-id: 4
    dark-theme-id: 200
  }
}

direction: down

ca: "Chat Agent\nLLM 工具调用循环"

tools: "toolsets（src/everlingo/tools/，@log_tool_call 全量装饰）" {
  conf_manager: "conf_manager\nget_schema / get_config（只读）"
  clock_t: "clock\nget_datetime"
  user_doc: "user_doc\nuser_doc_get / user_doc_set"
  voice: "voice\nvoice_speak（立即返回 voice scheduled）"
  vault_mcp: "vault_mcp\nsearch / read / ls / find / grep（只读 ×5）"
  rme: "request_memory_extraction\ndrafts 累积，立即返回"
  mwa: "memory_writer_action\ndelete / edit（阻塞等待）"
  csiv: "copy_session_image_to_vault\n返回 markdown 相对路径"
}

yaml: "everlingo.yaml\neverlingo.example.yaml" { shape: page }
sysclock: "系统时钟（Shanghai timezone）"
usermd: "memory/USER.md（workspace 下）" { shape: page }
tts: "EdgeTTSProvider\nedge-tts 合成 mp3" { shape: cloud }
sound: "channel.send_sound\n后台线程 fire-and-forget"
mcpsrv: "Vault MCP Server\nIndexer 进程 FastMCP\nStreamable HTTP"
queue: "MemoryWriterAgent 队列" { shape: cylinder }
wact: "Writer execute_action_async\ndaemon thread 串行"
imgstore: "ImageStore" { shape: cylinder }
assets: "vault {md}.assets/ 目录\nEXIF/PNG 溯源元数据" { shape: cylinder }
logfile: "logs/everlingo.log（workspace 下）" { shape: page }

ca -> tools: "LLM 按意图选择工具"

tools.conf_manager -> yaml: "[进程内] 只读读取"
tools.clock_t -> sysclock: "[进程内] now()"
tools.user_doc -> usermd: "[进程内] 读 / 整体覆盖写\n成功后 bump_prompt_version"
tools.voice -> tts: "[进程内] synthesize(text, fmt=mp3)"
tts -> sound: "[进程内] 异步调度发送语音"
tools.vault_mcp -> mcpsrv: "[MCP] 长连接 Stream\nCHAT_AGENT_WANTED_TOOLS 子集" { style.stroke: "#4C9EF0"; style.stroke-width: 2 }
tools.rme -> queue: "[进程内] invoke() 末尾统一入队（异步）"
tools.mwa -> wact: "[进程内] 同步 Future 回传（30s 超时）"
tools.csiv -> imgstore: "[进程内] read_bytes(src_sha)"
imgstore -> assets: "save_vault_image 写入\n显式 src_resource_sha256"
tools -> logfile: "[进程内] debug 调用日志"