Skip to content

v0.3.3

Choose a tag to compare

View all tags
@YunTaiHua YunTaiHua released this 28 Jul 09:27
· 242 commits to main since this release
v0.3.3
69bb830

Highlights

IllusionAgent v0.3.3 is a rebranding and stabilization release. This version completes the full migration from illusion-code to illusion-agent across all 5 layers (core build, API/user-visible strings, frontend, docs, scripts/skills/tests), introduces runtime /max-tokens control, fixes several backend crash chains (MCP McpError, Grep invalid regex, path traversal), and extracts shared logic (resolve_relative_path, run_rg_checked, MCP_TOOL_EXCEPTIONS) to eliminate tool-layer duplication.

Key Changes

  • Full Brand Migration — illusion-code → illusion-agent across build, CLI, API, frontend, docs, scripts, skills, and tests
  • Runtime max-tokens — New /max-tokens slash command with interactive selector and custom input
  • Crash Fixes — MCP McpError, Grep invalid regex, path traversal attacks, and cron daemon PID file
  • Code Deduplication — Extracted resolve_relative_path, run_rg_checked, MCP_TOOL_EXCEPTIONS into shared modules

New Features

Runtime Controls

  • /max-tokens Slash Command — New command to set max output tokens at runtime
  • Interactive Selector — /effort and /max-tokens with no args pop up a selector, supporting custom input
  • AppState + QueryEngine — Added max_tokens runtime modification support

Authentication

  • Interactive env Reuse — auth login supports interactive reuse of existing env and looping input for multiple models
  • Always New env — auth login always creates new env; add model moved to auth add-model command

MCP

  • Optional type Field — MCP config type now optional, defaults to stdio when omitted

Important Fixes

Brand Migration (illusion-code → illusion-agent)

  • Layer 1 — Core build and CLI migration
  • Layer 2 — API class rename (IllusionCodeApiError → IllusionAgentApiError), docstring and user-visible string migration
  • Layer 3 — Frontend brand name migration
  • Layer 4 — Documentation and image asset migration
  • Layer 5 — Scripts, skills, and test file brand name synchronization

Crash Chains

  • MCP McpError — Explicitly catch McpError in ReadMcpResourceTool and McpToolAdapter to prevent backend crashes
  • Grep Invalid Regex — Pre-validate regex with re.compile before calling rg, preventing RipgrepError escape
  • Path Traversal — Reject .., ~-prefixed paths in all file tools via validate_safe_path
  • Cron Daemon PID — Fixed run_cron_serve not writing PID file, causing is_scheduler_running() to always return False

Terminal UX

  • Tab Switching — Multi-question tab navigation now commits current answer before switching (equivalent to pressing Enter)
  • CustomInputModal — Unified context-window custom input flow, fixed style and focus leak
  • State Loss — Fixed state loss when switching between multi-question tabs

Backend

  • /max-tokens Endpoint — backend_host now handles /max-tokens select_request and CLI build branch
  • Test Isolation — Fixed test_max_tokens_set_number overwriting user's settings.json with test values

Refactoring

Shared Logic Extraction

  • resolve_relative_path — 4 file tools' duplicate _resolve_path replaced by paths.resolve_relative_path
  • run_rg_checked — glob_tool and grep_tool switched to non-throwing run_rg_checked
  • MCP_TOOL_EXCEPTIONS — Extracted (ValueError, McpError) constant to mcp/types.py
  • RipgrepNotFoundError — Added catch in run_rg_checked to fulfill "never raises" contract

Code Quality

  • Dead Code Removal — Deleted textual_app.py dead code and related test dependencies
  • Auto-fix — Applied 401 ruff safe auto-fixes for code style
  • Type Safety — Refined exception handling, simplified code, improved type annotations

Documentation

  • README & Introduction — Optimized slogan and project intro across 4 docs (English + Chinese)
    • Main slogan: "Where fantasy meets functionality"
    • Secondary: "The best of many worlds, refined into one intelligent agent"

CI/CD

  • Trusted Publishers — Removed scripts/publish.py (twine + token model), fully migrated to GitHub Actions Trusted Publishers
  • Lint Stability — Locked ruff version to 0.15.0 to prevent CI lint failures from new rules

Installation

pip install (Recommended)

pip install illusion-agent==0.3.3

From Source

git clone https://github.com/YunTaiHua/illusion-agent.git
cd illusion-agent
pip install .

Quick Start

illusion auth login                              # Configure API credentials
illusion                                          # Start TUI interactive session
illusion web                                      # Launch Web UI
illusion -p "Analyze the project structure"       # Print mode (non-interactive)

Documentation

中文版本

重点更新

IllusionAgent v0.3.3 是一个品牌迁移与稳定性版本。本次版本完成了 illusion-code 到 illusion-agent 的全层迁移（5 层：核心构建、API/用户可见字符串、前端、文档、脚本/skills/测试），引入了运行时 /max-tokens 控制，修复了多个后端崩溃链（MCP McpError、Grep 无效正则、路径穿越），并提取了公共逻辑（resolve_relative_path、run_rg_checked、MCP_TOOL_EXCEPTIONS）消除工具层重复代码。

关键更新

  • 全层品牌迁移 — illusion-code → illusion-agent 覆盖构建、CLI、API、前端、文档、脚本、skills、测试
  • 运行时 max-tokens — 新增 /max-tokens 斜杠指令，支持交互式选择器和自定义输入
  • 崩溃修复 — MCP McpError、Grep 无效正则、路径穿越攻击、cron 守护进程 PID 文件
  • 代码去重 — 提取 resolve_relative_path、run_rg_checked、MCP_TOOL_EXCEPTIONS 至公共模块

新功能

运行时控制

  • /max-tokens 斜杠指令 — 新增运行时设置最大输出令牌数的指令
  • 交互式选择器 — /effort 和 /max-tokens 无参数时弹出选择框，支持自定义输入
  • AppState + QueryEngine — 增加 max_tokens 运行时修改支持

认证

  • 交互式 env 复用 — auth login 支持交互式复用已有 env 和循环输入多个 model
  • 始终新建 env — auth login 始终新建 env，add model 改用 auth add-model 指令

MCP

  • type 字段可选 — MCP 配置 type 现在可选，省略时默认 stdio

重要修复

品牌迁移（illusion-code → illusion-agent）

  • 第1层 — 核心构建与 CLI 迁移
  • 第2层 — API 类名重命名（IllusionCodeApiError → IllusionAgentApiError）、docstring 和用户可见字符串迁移
  • 第3层 — 前端品牌名迁移
  • 第4层 — 文档与图片资源迁移
  • 第5层 — 脚本、skills 和测试文件品牌名同步

崩溃链

  • MCP McpError — 在 ReadMcpResourceTool 和 McpToolAdapter 中显式捕获 McpError，防止后端崩溃
  • Grep 无效正则 — 调用 rg 前用 re.compile 预校验正则，防止 RipgrepError 逃逸
  • 路径穿越 — 通过 validate_safe_path 拒绝所有文件工具中包含 ..、~ 开头的路径
  • Cron 守护进程 PID — 修复 run_cron_serve 未写入 PID 文件导致 is_scheduler_running() 始终返回 False

终端 UX

  • Tab 切换 — 多问题 tab 切换前先提交当前问题答案，等同于一次回车
  • CustomInputModal — 统一 context-window 自定义输入流程，修复样式与焦点泄漏
  • 状态丢失 — 修复多问题 tab 切换时状态丢失问题

后端

  • /max-tokens 端点 — backend_host 补充 /max-tokens select_request 与命令行构建分支
  • 测试隔离 — 修复 test_max_tokens_set_number 用测试值覆盖用户 settings.json 的问题

重构

公共逻辑提取

  • resolve_relative_path — 4 个文件工具的重复 _resolve_path 替换为 paths.resolve_relative_path
  • run_rg_checked — glob_tool 和 grep_tool 改用不抛异常的 run_rg_checked
  • MCP_TOOL_EXCEPTIONS — 提取 (ValueError, McpError) 常量至 mcp/types.py
  • RipgrepNotFoundError — run_rg_checked 新增捕获，使「不抛异常」契约成立

代码质量

  • 死代码清理 — 删除 textual_app.py 死代码及相关测试依赖
  • 自动修复 — 应用 401 项 ruff safe auto-fix 代码风格修复
  • 类型安全 — 细化异常处理、简化代码、完善类型注解

文档

  • README 与 introduction — 优化 4 个文档（中英文）的标语和项目简介
    • 主标语："幻想与实用，于此交融"（Where fantasy meets functionality）
    • 副标语："融合多个开源项目精华，构建统一智能代理"

CI/CD

  • Trusted Publishers — 删除 scripts/publish.py（twine + token 模式），全面迁移至 GitHub Actions Trusted Publishers
  • Lint 稳定性 — 锁定 ruff 版本为 0.15.0 防止 CI lint 因新版规则失败

安装

pip 安装（推荐）

pip install illusion-agent==0.3.3

从源码安装

git clone https://github.com/YunTaiHua/illusion-agent.git
cd illusion-agent
pip install .

快速开始

illusion auth login                              # 配置 API 认证
illusion                                          # 启动 TUI 交互式会话
illusion web                                      # 启动 Web 界面
illusion -p "分析项目结构"                         # Print 模式（非交互）

文档

Assets 2
Loading