CangLu Knowledge Base

流程拆解

6分钟阅读

流程拆解

learn 索引 | 主题索引

本文拆 Khoj 自动化的两条核心链路，所有依据均来自 khoj-ai/khoj 仓库实际源码（master 分支），引用时给出文件与行号，方便回查。

图清单

1. 对话创建自动化的链路

1.1 时序图

sequenceDiagram
    participant U as 用户
    participant Chat as Chat 接口
    participant LLM as LLM
    participant SQ as schedule_query
    participant SA as schedule_automation
    participant DB as 数据库
    participant APS as APScheduler

    U->>Chat: 自然语言任务描述
    Chat->>SQ: 转交解析
    SQ->>LLM: crontime_prompt 提示
    LLM-->>SQ: cron + query + subject
    SQ-->>Chat: 结构化结果
    Chat->>SA: 创建调度
    SA->>DB: 持久化任务
    SA->>APS: 注册 CronTrigger
    APS-->>U: 任务创建成功

1.2 关键代码锚点

  • src/khoj/processor/conversation/prompts.py:1033 crontime_prompt
    • 这段 prompt 让 LLM 把”每天早上看新闻”这类自然语言转成 {"crontime": "0 9 * * *", "query": "...", "subject": "..."}
  • src/khoj/routers/helpers.py:610 def schedule_query(...)
    • 调用 LLM 解析自然语言
  • src/khoj/routers/helpers.py:2625 aschedule_query 异步版本
  • src/khoj/routers/api_automation.py POST /api/automations
    • REST 接口直接编程式创建（绕开对话）

1.3 关键设计点

  • LLM 当 cron 编译器：用户不需要懂 0 9 * * *，说”每天早上”就行
  • subject 自动生成：LLM 同时给出任务标题用于推送邮件主题
  • 会话隔离：每个自动化任务关联一个独立 Conversation Session，避免污染主对话上下文

2. 自动化任务到点执行的链路

2.1 时序图

sequenceDiagram
    participant APS as APScheduler
    participant SC as scheduled_chat
    participant DB as 数据库
    participant Chat as Chat 接口
    participant Agent as Agent 推理
    participant Tools as 11 个工具
    participant FMT as format_automation_response
    participant Mail as send_task_email

    APS->>SC: 触发回调
    SC->>DB: 校验上次跑的时间
    Note over SC,DB: 6 小时内跑过则跳过
    SC->>Chat: 内部 HTTP 自调用 /api/chat
    Chat->>Agent: 进入推理
    Agent->>Tools: 自主调度若干工具
    Tools-->>Agent: 返回数据
    Agent-->>Chat: 综合输出
    Chat-->>SC: ai_response
    SC->>FMT: 格式化为 newsletter
    FMT-->>SC: formatted_response
    SC->>Mail: 发送邮件

2.2 关键代码锚点

  • src/khoj/routers/helpers.py 内 scheduled_chat() 函数
    • 任务到点的真正回调
    • 6 小时去重保护：if (now - last_run_time) < 6h: skip
  • src/khoj/routers/helpers.py 内的内部 HTTP 自调用
    • 拼出 url = f"{scheme}://{netloc}/api/chat" 然后 requests.post
    • 关键：定时执行 = 用同一个 chat 接口跑一次”自动化标记的对话”
  • src/khoj/utils/helpers.py:415 class ConversationCommand
    • 声明了 11 个内置工具枚举

2.3 关键设计点

  • 执行 = 重放对话：到点后不是跑死板的 SQL/API，是把保存的 query 当成一句普通话再扔给 chat 接口
  • AI 自主决策：Agent 根据 query 自由组合 SearchWeb / ReadWebpage / Research / Notes / Code，没人写死路径
  • 6 小时硬保护：避免多副本部署或重启时同任务被跑两遍

3. 任务执行后的通知判断与推送

3.1 流程图

flowchart TD
    Run[任务跑完] --> SN[should_notify LLM 判断]
    SN -->|Yes 值得通知| FMT[格式化为 newsletter]
    SN -->|No 不值得| Skip[静默跳过]
    FMT --> CH[选推送渠道]
    CH -->|Resend 已启用| Resend[Resend SaaS 发邮件]
    CH -->|Resend 未启用| SMTP[本地 SMTP]
    CH -->|Twilio 已配置| WA[WhatsApp]
    CH -->|Phone 已配置| Phone[Phone]

3.2 关键代码锚点

  • src/khoj/routers/helpers.py:format_automation_response
    • 用 automation_format_prompt 让 LLM 重写成 newsletter 风格
  • src/khoj/routers/helpers.py:should_notify
    • 用 to_notify_or_not prompt 让 LLM 判断是否通知，返回 {"decision": "Yes/No", "reason": "..."}
  • src/khoj/routers/email.py 内 send_task_email
    • 优先 Resend，回退 SMTP

3.3 关键设计点

  • 二次价值过滤：避免每天准点收到一堆”今日 GitHub Trending 没有新东西”的废邮件
  • 统一格式器：邮件正文经 LLM 重新组织，比直接贴 raw response 友好得多
  • 失败兜底：should_notify 报错时默认还是推送（不至于因 LLM 抽风丢消息）

4. 与已有工具的协作思路

flowchart TD
    subgraph Khoj 主场
        T1[网络/Notion 主题简报]
        T2[每日总结/周报]
    end

    subgraph ActivePieces 主场
        A1[邮箱新邮件]
        A2[外部 webhook]
        A3[国内 IM 推送]
    end

    subgraph OpenClaw 主场
        O1[微信/QQ 双向陪聊]
    end

    Khoj 主场 -.邮件中转.-> A3
    A1 --webhook调用--> Khoj 主场

要点：

  • Khoj 推到中转邮箱、AP 中继到飞书/钉钉/企微：补齐 Khoj 国内 IM 短板
  • AP 收到事件后调 Khoj REST API 创建一次性任务：让事件驱动也能享 Khoj 的 AI 自主采集
  • 三件套不是替代关系，是”输入差 / 大脑差 / 输出差”上的分工

具体配置示例与 cron 模板见 速查清单。

关系图谱