# geeeekexplorer/kkbot architecture

> Architecture diagram of the GitHub repository geeeekexplorer/kkbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geeeekexplorer/kkbot
- Repository: https://github.com/geeeekexplorer/kkbot

## Overview

##### What this project is (type + purpose)

**kkbot is a single-process “agent bot” that connects to Feishu (Lark) via a WebSocket channel, receives chat events, and—when triggered—runs an LLM-driven agent loop that can call tools (shell, file I/O, web search/fetch, memory) and then replies back into Feishu.**

It’s not a typical multi-service web app; architecturally it’s closer to:
- a **CLI-managed daemon** (started via `kkbot start`)
- that hosts **an event-driven bot runtime**
- that orchestrates **LLM calls + tool execution**
- persisting state to a **local workspace** (not a DB service)

##### Read the file tree as architecture hints

From the tree + README:

- `kkbot/main.py`: **CLI entrypoint** (`kkbot init`, `kkbot start`)
- `kkbot/config.py`: config loading + paths (notably `~/.kkbot/config.json` and workspace dirs)
- `kkbot/feishu.py`: **Feishu WebSocket channel** (ingress events + egress replies)
- `kkbot/agent.py`: **core agent loop** + tool execution + web tools
- `kkbot/llm.py`: **OpenAI-compatible LLM provider** (HTTP API calls)
- `kkbot/session.py`: session + memory management (chat context, `MEMORY.md`)
- `kkbot/tools.py`: tool definitions / dispatcher (shell, files, memory, web, restart)
- `skills/*.md`: “skill injection” into system prompt at startup

##### `agent.py` starts handling
- loads/uses **system prompt** (config)
- includes **skills** (`skills/*.md`)
- loads **memory** from `session.py` / `MEMORY.md`
- includes relevant chat history/session context
##### If tool call returned
- **`tools.py` dispatch** to tool:
- `shell` → OS shell
- `read_file/write_file/patch_file` → filesystem
- `save_memory/recall_memory` → `MEMORY.md`
- `web_search` → Brave API
- `web_fetch` → website HTTP fetch + extraction
- `restart_self` → process restart mechanism
- tool result → back to **agent.py**
- agent continues loop (bounded by `max_tool_rounds`)

##### Event-driven ingress
- kkbot is reactive: **Feishu events drive computation**.
- Only responds in group chat when **@-mentioned**, plus DMs.

##### Prompt assembly pipeline
Explicitly show prompt inputs:
- System prompt (config)
- Skills (markdown)
- Memory (long-term `MEMORY.md`)
- Session history (recent messages)

##### Tool execution loop
- LLM output can request tools
- Tools can mutate local state (files, memory) and retrieve external info (web)
- Agent repeats until final response or tool-round limit hit

##### Persistence is filesystem-based
- No database service; the “DB” is essentially `MEMORY.md` + workspace files.

##### “Don’t overthink”: how to split into “as many components as possible” without noise

A practical decomposition that stays accurate:

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0 — System Context
  %% =========================
  subgraph "Level 0 — System Context (External Integrations)"
    direction TB

    Operator["Operator / Developer\n(runs kkbot init/start,\nedits config/skills)"]:::external
    Feishu["Feishu (Lark) Platform\n(Group chats + DMs)"]:::external
    LLMAPI["OpenAI-compatible LLM API\n(api_base)"]:::external
    Brave["Brave Search API"]:::external
    Websites["Arbitrary Websites\n(for web_fetch)"]:::external
    OSFS["Local OS / Filesystem\n(shell + files)"]:::external

    KKBotSys["kkbot Bot Runtime\n(single-process agent bot)"]:::system
  end

  Operator -->|"start/stop+edit"| KKBotSys
  Feishu -.->|"chat_event(mention/DM)"| KKBotSys
  KKBotSys -.->|"reply_message"| Feishu
  KKBotSys -->|"prompt/completions"| LLMAPI
  KKBotSys -->|"search_query/results"| Brave
  KKBotSys -->|"url_fetch/content"| Websites
  KKBotSys <-->|"read/write/patch+shell"| OSFS

  %% ==================================
  %% Level 1 — Container / Runtime View
  %% ==================================
  subgraph "Level 1 — kkbot Process (Logical Containers in One Runtime)"
    direction TB

    subgraph "Boot & Configuration"
      direction TB
      PyProject["Project Metadata\n(pyproject.toml)"]:::doc
      Readme["Operator Docs\n(README.md)"]:::doc
      InitPkg["Package Init\n(kkbot/__init__.py)"]:::internal
      CLI["CLI / Bootstrap\n(kkbot/main.py)\ncommands: init, start"]:::internal
      Config["Config Manager\n(kkbot/config.py)\nloads config + resolves workspace paths"]:::internal
      ConfigJSON[("~/.kkbot/config.json")]:::storage
    end

    subgraph "Connectivity (Transport)"
      direction TB
      FeishuConn["Feishu Connector\n(kkbot/feishu.py)\nWebSocket channel"]:::internal
      WS["WebSocket Session\n(Feishu channel)"]:::internal2
    end

    subgraph "Orchestration (Agent Runtime)"
      direction TB
      Agent["Agent Orchestrator / Agent Loop\n(kkbot/agent.py)\nmax_tool_rounds"]:::internal
      PromptAsm["Prompt Assembly Pipeline\n(system_prompt+skills+memory+session_history)"]:::internal2
      PrefixCache["Prefix Cache Optimization\n(reuse static prompt prefix)"]:::note
      LLMClient["LLM Client\n(kkbot/llm.py)\nOpenAI-compatible HTTP"]:::internal
      SessionMem["Session & Memory Manager\n(kkbot/session.py)\ncontext + long-term memory"]:::internal
    end

    subgraph "Capabilities (Tools)"
      direction TB
      Tools["Tools Dispatcher\n(kkbot/tools.py)"]:::internal

      subgraph "Tool: OS"
        direction TB
        ToolShell["shell_exec"]:::tool
      end

      subgraph "Tool: Filesystem"
        direction TB
        ToolRead["read_file"]:::tool
        ToolWrite["write_file"]:::tool
        ToolPatch["patch_file"]:::tool
      end

      subgraph "Tool: Memory"
        direction TB
        ToolSaveMem["save_memory"]:::tool
        ToolRecallMem["recall_memory"]:::tool
      end

      subgraph "Tool: Web"
        direction TB
        ToolSearch["web_search (Brave)"]:::tool
        ToolFetch["web_fetch (URLs)"]:::tool
      end

      subgraph "Tool: Lifecycle"
        direction TB
        ToolRestart["restart_self"]:::tool
      end
    end

    subgraph "Prompt Enrichment (Skills)"
      direction TB
      SkillsDir["Skills Directory\n(skills/)"]:::internal
      SkillsFile["Skill Markdown\n(skills/*.md)"]:::internal2
    end

    subgraph "Local Persistence (Filesystem Workspace)"
      direction TB
      Workspace[("~/.kkbot/workspace/...")]:::storage
      MemoryMD[("~/.kkbot/workspace/memory/MEMORY.md")]:::storage
    end
  end

  %% Boot relationships
  PyProject -->|"defines_cli_entry"| CLI
  Readme -->|"runbook/configure"| Operator
  InitPkg -->|"package_load"| CLI

  CLI -->|"init/create"| ConfigJSON
  CLI -->|"start"| FeishuConn
  CLI -->|"load_paths"| Config
  Config -->|"read"| ConfigJSON
  Config -->|"resolve_paths"| Workspace

  %% Connectivity relationships
  FeishuConn <-->|"maintain"| WS
  Feishu -.->|"events"| WS
  WS -.->|"chat_event"| FeishuConn

  %% Runtime orchestration
  FeishuConn -.->|"dispatch_event"| Agent
  Agent -->|"build_prompt"| PromptAsm
  PromptAsm -->|"load"| SkillsDir
  SkillsDir -->|"read"| SkillsFile
  PromptAsm -->|"read/write_context"| SessionMem
  SessionMem <-->|"read/write"| MemoryMD

  PromptAsm -->|"prefix_reuse"| PrefixCache
  PrefixCache -->|"optimize_request"| LLMClient

  Agent -->|"prompt+context"| LLMClient
  LLMClient -->|"HTTP"| LLMAPI
  LLMClient -->|"completion(tool_calls/final)"| Agent

  %% Tool loop
  Agent -->|"tool_call_JSON"| Tools
  Tools -->|"invoke"| ToolShell
  Tools -->|"invoke"| ToolRead
  Tools -->|"invoke"| ToolWrite
  Tools -->|"invoke"| ToolPatch
  Tools -->|"invoke"| ToolSaveMem
  Tools -->|"invoke"| ToolRecallMem
  Tools -->|"invoke"| ToolSearch
  Tools -->|"invoke"| ToolFetch
  Tools -->|"invoke"| ToolRestart

  ToolShell <-->|"exec"| OSFS
  ToolRead <-->|"read"| OSFS
  ToolWrite <-->|"write"| OSFS
  ToolPatch <-->|"patch"| OSFS

  ToolRead <-->|"workspace_files"| Workspace
  ToolWrite <-->|"workspace_files"| Workspace
  ToolPatch <-->|"workspace_files"| Workspace

  ToolSaveMem <-->|"append"| MemoryMD
  ToolRecallMem -->|"recall"| MemoryMD

  ToolSearch -->|"query/results"| Brave
  ToolFetch -->|"GET/content"| Websites

  Tools -->|"tool_result"| Agent

  %% Reply egress
  Agent -.->|"final_reply"| FeishuConn
  FeishuConn -.->|"send_message"| Feishu

  %% =========================
  %% Level 2 — Sequence (Flow)
  %% =========================
  subgraph "Level 2 — Single Message Handling (Agent Loop Control Flow)"
    direction TB

    S1["1) User @mentions bot / DM"]:::step
    S2["2) Feishu emits WebSocket event"]:::step
    S3["3) feishu.py receives event"]:::step
    S4["4) agent.py assembles prompt\n(system+skills+memory+session)"]:::step
    S5["5) llm.py requests completion"]:::step
    S6["6) Tool call? -> tools.py dispatch\n(loop until final or max_tool_rounds)"]:::step
    S7["7) agent.py returns final answer"]:::step
    S8["8) feishu.py sends reply to Feishu"]:::step

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8
  end

  %% Tie sequence to actual components (vertical references)
  S2 -.-> WS
  S3 -.-> FeishuConn
  S4 -.-> PromptAsm
  S5 -.-> LLMClient
  S6 -.-> Tools
  S8 -.-> Feishu

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click CLI "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/main.py"
  click Config "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/config.py"
  click FeishuConn "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/feishu.py"
  click Agent "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/agent.py"
  click LLMClient "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/llm.py"
  click SessionMem "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/session.py"
  click Tools "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/tools.py"
  click SkillsFile "https://github.com/geeeekexplorer/kkbot/blob/main/skills/gh.md"
  click SkillsDir "https://github.com/geeeekexplorer/kkbot/tree/main/skills/"
  click InitPkg "https://github.com/geeeekexplorer/kkbot/blob/main/kkbot/__init__.py"
  click PyProject "https://github.com/geeeekexplorer/kkbot/blob/main/pyproject.toml"
  click Readme "https://github.com/geeeekexplorer/kkbot/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#E5E7EB,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef system fill:#111827,stroke:#0B1220,stroke-width:1px,color:#F9FAFB
  classDef internal fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0F172A
  classDef internal2 fill:#CFFAFE,stroke:#0891B2,stroke-width:1px,color:#0F172A
  classDef storage fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0F172A
  classDef tool fill:#DCFCE7,stroke:#16A34A,stroke-width:1px,color:#052E16
  classDef doc fill:#FCE7F3,stroke:#BE185D,stroke-width:1px,color:#0F172A
  classDef note fill:#FFF7ED,stroke:#C2410C,stroke-dasharray: 4 3,stroke-width:1px,color:#0F172A
  classDef step fill:#EEF2FF,stroke:#4338CA,stroke-width:1px,color:#0F172A
```
