▄███▄     小铁 XiaoTie v2.1
 █ ⚙ █    状态机 Agent · tree-sitter RepoMap · OS 沙箱
 ▀███▀

支持深度思考、流式输出、多工具并行执行、状态机实时展示。

5 层架构: 交互层 → 编排层 (状态机) → 认知层 → 工具层 → 基础层

分层密钥解析: System Keyring → 环境变量 → 配置 Fallback

Lint → Test (4 Python 版本) → Security Scan → Performance Gate

• ✅ AgentRuntime 接入 CLI/TUI 主流程 — 替代旧 Agent 类，旧 API 标记 deprecated
• ✅ ContextEngine + RepoMap 接入 AgentRuntime — LLM 调用前自动组装 token 预算上下文
• ✅ SecretManager 接入配置加载 — Config.load() 自动解析 ${secret:...} / ${env:...} 占位符
• ✅ /secret 命令注册 — 交互模式中直接管理密钥
• ✅ 核心模块覆盖率 ≥ 90% — runtime 97%, executor 90%, secrets 91%, context_engine 90%

• Agent 执行循环 (状态机 + 传统模式兼容)
• 流式输出、深度思考 (thinking mode)
• 会话管理、Token 自动摘要
• 并行工具执行、优雅取消 (Ctrl+C)
• TUI 模式 (Textual) 含首次运行引导向导、非交互模式 (JSON 输出)
• MCP 协议支持 (连接外部 MCP 服务器)
• 插件系统、自定义命令
• 多 LLM 支持 (Anthropic / OpenAI / GLM / Gemini / DeepSeek / Qwen / MiniMax)
• 多 Agent 协调 (Coordinator / Expert / Executor / Supervisor 角色)
• 记忆系统 (短期/长期/情景/语义/工作记忆)
• 语义搜索 (chromadb 向量存储)

20+ 内置工具:

git clone https://github.com/LeoLin990405/xiaotie.git
cd xiaotie

# 基础安装
pip install -e .

# 安装所有功能
pip install -e ".[all]"

# 或按需安装
pip install -e ".[tui]"        # TUI 界面 (含首次运行向导)
pip install -e ".[repomap]"    # tree-sitter 代码导航
pip install -e ".[secrets]"    # keyring 密钥管理
pip install -e ".[search]"     # 语义搜索

推荐方式: 使用 keyring (安全)

# 存储密钥到系统 keyring
xiaotie secret set api_key
# 输入你的 API Key

# 在 config.yaml 中引用
# api_key: ${secret:api_key}

快速方式: 环境变量

export XIAOTIE_API_KEY="your-key"
# 或
export ZHIPU_API_KEY="your-key"

TUI 首次运行向导 (最简单)

pip install -e ".[tui]"
xiaotie --tui
# 引导向导会自动收集 API Key、模型、Provider 并生成配置

# 交互式
xiaotie

# TUI 模式
xiaotie --tui

# 非交互模式
xiaotie -p "帮我分析这段代码" -f json

# 安静模式
xiaotie -p "帮我重构这个函数" -q

graph TB
    subgraph "L5 交互层"
        CLI["CLI (Rich)"]
        TUI["TUI (Textual)"]
        SDK["Python SDK"]
    end

    subgraph "L4 编排层"
        RT["AgentRuntime (状态机)"]
        TE["ToolExecutor"]
        RH["ResponseHandler"]
    end

    subgraph "L3 认知层"
        CTX["ContextEngine (Token 预算)"]
        RM["RepoMapEngine (tree-sitter + PageRank)"]
    end

    subgraph "L2 工具层"
        TOOLS["工具注册表 (20+ 工具)"]
        MCP["MCP Gateway"]
        PERM["权限管理"]
    end

    subgraph "L1 基础层"
        LLM["LLM 客户端 (多 Provider)"]
        SB["SandboxManager (OS 沙箱)"]
        SM["SecretManager (密钥管理)"]
        DB["SQLite 存储"]
    end

    CLI --> RT
    TUI --> RT
    SDK --> RT
    RT --> TE
    RT --> RH
    RT --> CTX
    RT --> RM
    TE --> TOOLS
    TE --> MCP
    TE --> PERM
    TOOLS --> SB
    RH --> LLM
    LLM --> SM

IDLE ──→ THINKING ──→ ACTING ──→ OBSERVING ──→ REFLECTING ──→ THINKING
  ↑         │                                        │            (循环)
  │         └── 无工具调用 ──→ IDLE (完成)             └── 取消 ──→ IDLE
  └──────────────────────────────────────────────────────────────────┘

# API 配置 (推荐使用 ${secret:...} 而非明文)
api_key: ${secret:api_key}
api_base: https://open.bigmodel.cn/api/coding/paas/v4
model: GLM-4.7
provider: openai  # 使用 OpenAI 兼容协议

# Agent 配置
max_steps: 50
workspace_dir: ./workspace

# 重试
retry:
  enabled: true
  max_retries: 3
  initial_delay: 1.0

# 工具
tools:
  enable_file_tools: true
  enable_bash: true

# MCP 配置
mcp:
  enabled: false
  servers:
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      enabled: true

配置文件占位符语法:

api_key: ${secret:api_key}         # 从 keyring/环境变量解析
github_token: ${env:GITHUB_TOKEN}  # 仅从环境变量解析

• 工具调用前进行风险评估 (low/medium/high)
• 低风险自动批准，高风险需要交互确认
• 敏感输出自动脱敏 (AWS Key, GitHub Token, 私钥等)
• 所有工具调用记录审计日志

import asyncio
from xiaotie.agent import AgentRuntime, AgentConfig
from xiaotie.llm import LLMClient
from xiaotie.tools import ReadTool, WriteTool, BashTool

async def main():
    llm = LLMClient(
        api_key="your-key",
        api_base="https://api.anthropic.com",
        model="claude-sonnet-4-20250514",
        provider="anthropic",
    )
    config = AgentConfig(max_steps=30, parallel_tools=True)
    tools = [ReadTool(workspace_dir="."), WriteTool(workspace_dir="."), BashTool()]

    runtime = AgentRuntime(llm, system_prompt="你是小铁", tools=tools, config=config)

    # 可选: 集成 ContextEngine 和 RepoMap
    from xiaotie.context_engine import ContextEngine
    from xiaotie.repomap_v2 import RepoMapEngine
    runtime.set_context_engine(ContextEngine(token_budget=100_000))
    runtime.set_repomap_engine(RepoMapEngine(workspace_dir="."))

    result = await runtime.run("帮我创建一个 hello.py")
    print(result)
    print(runtime.get_stats())

asyncio.run(main())

from xiaotie.agent import Agent  # ⚠️ 将在 v3.0 移除
from xiaotie.llm import LLMClient
from xiaotie.tools import ReadTool, WriteTool, BashTool

agent = Agent(
    llm_client=LLMClient(...),
    system_prompt="你是小铁",
    tools=[ReadTool(), WriteTool(), BashTool()],
    stream=True,
    parallel_tools=True,
)
result = await agent.run("你好")

git clone https://github.com/LeoLin990405/xiaotie.git
cd xiaotie
pip install -e ".[dev,all]"

# 安装 pre-commit hooks
pre-commit install

make test            # 运行测试
make lint            # 代码检查
make format          # 格式化
make security-scan   # 安全扫描
make benchmark       # 性能基准
make ci-local        # 本地完整 CI

GitHub Actions 工作流:

欢迎贡献! 请遵循以下步骤:

1. Fork 本仓库
2. 创建特性分支: git checkout -b feature/amazing-feature
3. 安装开发依赖: pip install -e ".[dev,all]"
4. 编写代码并添加测试
5. 运行本地 CI: make ci-local
6. 提交更改: git commit -m "feat: add amazing feature"
7. 推送分支: git push origin feature/amazing-feature
8. 创建 Pull Request

• 使用 ruff 进行代码检查和格式化
• 新功能必须附带单元测试
• 保持 API 向后兼容
• 安全敏感代码必须通过 bandit 扫描

• Memory 系统接入 Agent 循环 (记忆自动存取)
• 语义搜索自动集成为内置工具
• 跨会话对话持久化
• Web UI 前端
• 更多 MCP 服务器预置

• 多 Agent 协作自动编排
• RAG 管线内置
• 视觉模型原生支持 (截图理解)
• VS Code / JetBrains 插件

• MiniMax-AI/Mini-Agent - 核心架构灵感
• Aider - RepoMap、命令系统设计
• Claude Code - 状态机 Agent、OS 沙箱、ContextEngine
• Open Interpreter - 流式处理模式
• MCP Python SDK - MCP 协议集成

MIT