Xun¶

Xun 是一个轻量级的 LLM 智能体运行时：核心只有不到 5000 行 Python（src/xun/*.py），同时自带工具、命令、显示层、扩展系统与多种会话入口，可以直接拿来跑，也可以只取其中的部件。

from xun import setup_agent, interactive_session

def weather(city: str) -> str:
    """Query the weather for a given city."""
    return f"Sunny in {city}"

agent = setup_agent(tools=[weather])
interactive_session(agent, task="What is the weather in Paris?")

主要功能¶

能力	说明	详见
执行循环与结构化输出	多轮工具调用直到收敛；可用 pydantic 模型约束最终输出	结构化输出
函数即工具	普通函数 + 类型注解 + docstring 即成为工具，33 个内置工具覆盖文件系统、命令、浏览器、检索与诊断	工具设置
显示层	同一套事件流可输出到控制台、Web 或自定义显示	显示扩展
子智能体	内置派生策略与后台派生工具，父智能体可并行派发任务	子智能体派生
会话压缩	先回收旧工具结果，仍超限再转摘要，两级降级	Config
生命周期钩子	17 个可编辑参数的钩子点，可接管执行	Hooks
链式取消	父智能体取消自动级联到子智能体	链式取消
会话入口	`xun` / `xuns` / `xunc` / `xunx` / `xune` 五种入口	内置会话入口
扩展系统	放进 `$XUN_HOME/extensions/` 的文件在每个智能体初始化时自动生效	插件开发指南

应用场景¶

命令行助手：xun 在当前目录里交互式干活，读写文件、跑命令、开浏览器。
自托管 Web 服务：xuns 提供带文件面板的浏览器界面；xunc 把它关进 Docker 容器；xunx 用一个网关服务多个用户。
嵌入自己的程序：直接用 Agent API 编排一次调用、批量任务或自定义工具链，不引入任何入口层。
不改主程序的能力扩展：MCP、Skills、用量统计等都以扩展形式提供，核心保持不变。

设计特点¶

同步 API。 智能体的瓶颈在模型调用本身，异步只增加心智负担；框架内部仍用线程与信号量并发，调用方写的是从上到下一行的代码。
类型状态（Type-State）。 Agent 以生命周期状态为类型参数，Uninit 上无法调用 execute()， Final 上无法再改提示词——这类错误在静态检查阶段就被拦下。见生命周期。
事件驱动的显示层。 智能体不 print，只发事件；显示端负责渲染与人机交互，因此同一个智能体可以安静地跑在脚本里，也可以推到浏览器里。
配置一次，处处继承。 全局 config.json 载入后按智能体克隆；派生子智能体时可选择共享工作区、显示层与取消链。
扩展即受信代码。 扩展在导入时以完整进程权限执行，像 shell 的 rc 文件一样简单直接，加载失败只告警不阻断启动。

结构总览¶

flowchart TD
    subgraph entry["会话入口"]
        CLI["xun / xuns"]
        BOX["xunc / xunx"]
        EXT["xune"]
    end

    subgraph core["核心 Agent"]
        CONV["Conversation 会话与系统提示"]
        TB["ToolBox 工具箱"]
        DISP["Display 显示层"]
        CFG["AgentConfig 配置"]
        HK["Hooks 钩子"]
        ST["AgentState 状态容器"]
    end

    LLM["OpenAI 兼容模型服务"]

    entry --> core
    core --> LLM
    LLM --> core
    TB --> TOOLS["内置工具 / 自定义函数"]
    DISP --> OUT["控制台 / Web / 自定义"]
    EXT -."初始化时注入".-> core

扩展不改动入口程序，只在每个智能体 initialize() 时往核心对象上挂载工具、命令、钩子与提示词段落。

文档结构¶

安装：pip、源码、Docker 三条路径。
内置会话入口：五个命令的参数与适用场景。
API 文档：初始化、配置、生命周期、显示、结构化工具等接口。
插件开发指南：扩展与 API 的分工、加载机制、扩展点。
更新日志。

看代码更快

仓库根目录的 demo.ipynb 用十个小节跑通了本文档 API 部分的全部要点， README.md 则是最短的上手指引。