diff --git a/README.md b/README.md index 2675310..f1c4c43 100644 --- a/README.md +++ b/README.md @@ -9,25 +9,34 @@ LLM chat interfaces. Paste LLM-generated tool calls (in XML format), review and audit dangerous operations, and manage sessions with full history tracking -- all running locally on your machine. -> **Version**: 0.5.0 | **Python**: >=3.14 +> **Version**: 0.6.0 | **Python**: >=3.14 --- ## Features -- **TUI Console** -- Four-tab Textual interface: RichLog, Tool Calls, Audit, - Statistics -- **12 Built-in Tools** -- File system exploration, search, editing, Git - integration +- **TUI Console** -- Multi-tab Textual interface: RichLog, Tool Calls, Audit, + Statistics, Environment Config, Skill Config +- **14 Built-in Tools** -- File system exploration, search, editing, Git + integration, Shell execution, Skill system +- **Agent System** -- Support Agent configuration via YAML frontmatter for + different roles and permission workflows +- **Skill System** -- Dynamically load and execute custom Shell scripts as + extension tools - **Safe Editing** -- Two-phase commit for write/edit operations with diff preview and manual approval - **Git Integration** -- Whitelist-based Git command execution with safety filters +- **Gitignore Support** -- Automatically parse and apply `.gitignore` file rules + to search and file operations +- **Sensitive File Protection** -- Automatically block access to `.env`, + `*.pem`, `id_rsa` and other sensitive files - **Session Management** -- Automatic session tracking, rename, delete, and switch - **Tool Usage Analytics** -- Per-session and global tool call statistics with ranking -- **Audit System** -- Pending write/edit snapshots with approve/reject workflow +- **Audit System** -- Pending write/edit/Shell snapshots with approve/reject + workflow - **Result Caching** -- Auto-copy results to clipboard with configurable expiration - **Multi-window Launch** -- Spawn new ManualAid windows for different @@ -84,15 +93,17 @@ tabs. ## Console Interface -The TUI is built with [Textual](https://textual.textualize.io/) and has four +The TUI is built with [Textual](https://textual.textualize.io/) and has six tabs: -| Tab | Purpose | -| ---------- | ---------------------------------------------------- | -| RichLog | General log output and messages | -| Tool Calls | Collapsible tool execution results | -| Audit | Pending write/edit operations awaiting approval | -| Statistics | Session summaries, tool rankings, session management | +| Tab | Purpose | +| ------------------ | ----------------------------------------------------- | +| RichLog | General log output and messages | +| Tool Calls | Collapsible tool execution results | +| Audit | Pending write/edit/Shell operations awaiting approval | +| Statistics | Session summaries, tool rankings, session management | +| Environment Config | Environment variable and configuration management | +| Skill Config | Custom skill script management and configuration | ### Keyboard Shortcuts @@ -111,13 +122,14 @@ tabs: | `/help` | `/h` / `/?` | Show help text | | `/cls` | | Clear the log display | | `/workspace` | `/ws` | Generate a system prompt containing workspace information and tool definitions. | +| `/agent` | | List, switch, copy, or reset agent configurations | | `/new` | | Launch new ManualAid window | --- ## Available Tools -ManualAid registers 12 tools for LLM use via XML function calls: +ManualAid registers 14 tools for LLM use via XML function calls: ### Query Tools (read-only) @@ -140,9 +152,16 @@ ManualAid registers 12 tools for LLM use via XML function calls: ### Dangerous Tools (require audit approval) -| Tool | Description | -| ----- | ------------------------------------- | -| `git` | Whitelist-based Git command execution | +| Tool | Description | +| ------- | ------------------------------------------ | +| `git` | Whitelist-based Git command execution | +| `shell` | Execute Shell commands (requires approval) | + +### Extension Tools + +| Tool | Description | +| ------- | ------------------------------------------------------- | +| `skill` | Dynamically load and execute custom Shell script skills | > Tool calls use XML format. See `/help` in the console for syntax examples. @@ -150,12 +169,14 @@ ManualAid registers 12 tools for LLM use via XML function calls: ## Audit Workflow -Write and edit operations go through a two-phase safety workflow: +Write, edit, and Shell command operations go through a two-phase safety +workflow: -1. **Preview** -- The tool computes a diff and stores a snapshot with - `PENDING_AUDIT` status -2. **Review** -- Switch to the Audit tab to review the diff -3. **Decide** -- Click Approve to commit the change, or Reject to discard it +1. **Preview** -- The tool computes a diff or command content and stores a + snapshot with `PENDING_AUDIT` status +2. **Review** -- Switch to the Audit tab to review the diff or command details +3. **Decide** -- Click Approve to commit the change/execute command, or Reject + to discard it Git commands that are not in the safe list (`status`, `diff`, `log`, `show`) also require audit approval before execution. diff --git a/README_ZH.md b/README_ZH.md index 3479c05..965e5d7 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -8,19 +8,26 @@ ManualAid 提供了一个基于 Textual 的 TUI 控制台,在剪贴板和 LLM 聊天界面之间架起桥梁. 粘贴 LLM 生成的工具调用(XML 格式),审查和审计危险操作,并通过完整的历史追踪管理会话 -- 一切都在本地运行. -> **版本**: 0.5.0 | **Python**: >=3.14 +> **版本**: 0.6.0 | **Python**: >=3.14 --- ## 功能特性 -- **TUI 控制台** -- 四个标签页的 Textual 界面:RichLog、工具调用、审计、统计 -- **12 个内置工具** -- 文件系统探索、搜索、编辑、Git 集成 +- **TUI 控制台** + -- 多标签页的 Textual 界面:RichLog、工具调用、审计、统计、环境配置、Skill 配置 +- **14 个内置工具** + -- 文件系统探索、搜索、编辑、Git 集成、Shell 执行、Skill 系统 +- **Agent 系统** -- 支持通过 YAML + frontmatter 定义 Agent 配置,实现不同角色和权限的工作流 +- **Skill 系统** -- 动态加载和执行自定义 Shell 脚本作为扩展工具 - **安全编辑** -- 写入/编辑操作采用两阶段提交,包含 diff 预览和人工审批 - **Git 集成** -- 基于白名单的 Git 命令执行,带有安全过滤 +- **Gitignore 支持** -- 自动解析和应用 `.gitignore` 文件规则到搜索和文件操作 +- **敏感文件保护** -- 自动拦截对 `.env`、`*.pem`、`id_rsa` 等敏感文件的访问 - **会话管理** -- 自动会话追踪,支持重命名、删除和切换 - **工具使用分析** -- 按会话和全局的工具调用统计及排名 -- **审计系统** -- 待处理的写入/编辑快照,支持批准/拒绝工作流 +- **审计系统** -- 待处理的写入/编辑/Shell 快照,支持批准/拒绝工作流 - **结果缓存** -- 自动将结果复制到剪贴板,可配置过期时间 - **多窗口启动** -- 为不同工作区生成新的 ManualAid 窗口 - **跨平台** -- 支持 Windows、macOS 和 Linux(后两个没测试) @@ -72,14 +79,16 @@ python main.py -p /path/to/your/project ## 控制台界面 -TUI 基于 [Textual](https://textual.textualize.io/) 构建,包含四个标签页: +TUI 基于 [Textual](https://textual.textualize.io/) 构建,包含六个标签页: -| 标签页 | 用途 | -| -------- | ---------------------------- | -| RichLog | 通用日志输出和消息 | -| 工具调用 | 可折叠的工具执行结果 | -| 审计 | 等待审批的写入/编辑操作 | -| 统计 | 会话摘要、工具排名、会话管理 | +| 标签页 | 用途 | +| ---------- | ------------------------------ | +| RichLog | 通用日志输出和消息 | +| 工具调用 | 可折叠的工具执行结果 | +| 审计 | 等待审批的写入/编辑/Shell 操作 | +| 统计 | 会话摘要、工具排名、会话管理 | +| 环境配置 | 环境变量和配置项管理 | +| Skill 配置 | 自定义技能脚本管理和配置 | ### 键盘快捷键 @@ -98,13 +107,14 @@ TUI 基于 [Textual](https://textual.textualize.io/) 构建,包含四个标签 | `/help` | `/h` / `/?` | 显示帮助文本 | | `/cls` | | 清除日志显示 | | `/workspace` | `/ws` | 生成包含工作区信息, 工具定义的系统提示词 | +| `/agent` | | 列出、切换、复制或重置 Agent 配置 | | `/new` | `/n` | 启动新的 ManualAid 窗口 | --- ## 可用工具 -ManualAid 注册了 12 个工具供 LLM 通过 XML 函数调用使用: +ManualAid 注册了 14 个工具供 LLM 通过 XML 函数调用使用: ### 查询工具(只读) @@ -127,9 +137,16 @@ ManualAid 注册了 12 个工具供 LLM 通过 XML 函数调用使用: ### 危险工具(需审计审批) -| 工具 | 描述 | -| ----- | ------------------------- | -| `git` | 基于白名单的 Git 命令执行 | +| 工具 | 描述 | +| ------- | --------------------------- | +| `git` | 基于白名单的 Git 命令执行 | +| `shell` | 执行 Shell 命令(需审核通过) | + +### 扩展工具 + +| 工具 | 描述 | +| ------- | ----------------------------------- | +| `skill` | 动态加载和执行自定义 Shell 脚本技能 | > 工具调用使用 XML 格式. 在控制台中使用 `/help` 查看语法示例. @@ -137,11 +154,11 @@ ManualAid 注册了 12 个工具供 LLM 通过 XML 函数调用使用: ## 审计工作流 -写入和编辑操作经过两阶段安全流程: +写入、编辑和 Shell 命令操作经过两阶段安全流程: -1. **预览** -- 工具计算 diff 并存储状态为 `PENDING_AUDIT` 的快照 -2. **审查** -- 切换到审计标签页审查 diff -3. **决定** -- 点击批准提交更改,或点击拒绝放弃更改 +1. **预览** -- 工具计算 diff 或命令内容并存储状态为 `PENDING_AUDIT` 的快照 +2. **审查** -- 切换到审计标签页审查 diff 或命令详情 +3. **决定** -- 点击批准提交更改/执行命令,或点击拒绝放弃操作 不在安全列表(`status`、`diff`、`log`、`show`)中的 Git 命令也需在执行前通过审计审批. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 70e2416..8616e1f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,76 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.6.0] - 2026-05-08 + +### Added + +- **Agent System**: Introduced Agent configuration management with YAML + frontmatter support for defining system prompts, constraints, and permissions. + Implemented `AgentManager` singleton pattern supporting Agent loading, + switching, and persistence + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **Skill System**: Added Skill management functionality supporting dynamic + loading and execution of custom Shell scripts as extension tools. Includes + `SkillManager`, `skill_tool`, and related TUI configuration interface + ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **Shell Tool**: New `shell` tool for executing Shell commands with safety + auditing ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **Path Validation Enhancement**: Introduced `ExclusionManager` class to unify + performance exclusion (.gitignore rules) and security exclusion (sensitive + file blocking). Added `SensitiveFileError` exception to directly block access + to `.env`, `*.pem`, `id_rsa` and other sensitive files + ([#151](https://github.com/SunYanbox/ManualAid/issues/151)). +- **Gitignore Support**: New `GitignoreLoader` module to parse `.gitignore` + files and apply exclusion rules to search and file operation tools + ([#151](https://github.com/SunYanbox/ManualAid/issues/151)). +- **Binary Detection Extension**: Extended binary file detector to support Godot + project formats (.godot, .gd, .gd.uid, .tscn) and compilation artifacts (.pdb, + .pyd, .o) ([#151](https://github.com/SunYanbox/ManualAid/issues/154)). +- **Search Tool Binary Filtering**: Integrated binary file detection mechanism + in `regex_search` and `exact_search` tools to automatically skip binary files + ([#154](https://github.com/SunYanbox/ManualAid/issues/154)). +- **Agent Command**: New `/agent` command supporting listing agents, switching + current agent, copying agent configuration, and resetting default agent + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **Config Manager**: New `ConfigManager` class for unified environment variable + configuration management + ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **Audit Committer**: New `AuditCommitter` class to handle audit system commit + logic ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **TUI Configuration Tabs**: New environment configuration and skill + configuration tabs providing graphical configuration interface + ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **Shell Result Tab**: New shell execution result tab displaying command output + ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). + +### Changed + +- **System Prompt Refactor**: Refactored system prompt assembly logic to support + Agent-based dynamic overrides. Explicitly defined prompt assembly order: Role + → Constraints → Agent Directive → Tool Rules → Tool Definitions → Workflow → + Workspace Context → Augmentation → Extensions + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **Tool Permission Filtering**: `/ws` command now filters tool definitions + based on current Agent's tool permission whitelist + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **Path Exclusion Logic Refactor**: Removed `PermissionManager` class and + integrated sensitive file rules into `ExclusionManager`. Simplified search and + traversal logic with unified `ExclusionManager` for path filtering + ([#151](https://github.com/SunYanbox/ManualAid/issues/151)). +- **TUI Startup Initialization**: TUI now automatically initializes default + agent on startup ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **Database Extension**: Extended database manager to support Agent and Skill + related data persistence + ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). + +### Fixed + +- **Git Tool Output Preservation**: Fixed issue where Git commands returning + non-zero exit code but still producing stdout (e.g., `git diff --exit-code`) + would discard stdout entirely. Now always preserves stdout even when + returncode != 0 ([#150](https://github.com/SunYanbox/ManualAid/issues/150)). + ## [0.5.0] - 2026-05-05 ### Added @@ -251,6 +321,7 @@ and this project adheres to _Initial release features and history._ +[0.6.0]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.6.0 [0.5.0]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.5.0 [0.4.1]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.4.1 [0.4.0]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.4.0 diff --git a/docs/CHANGELOG_ZH.md b/docs/CHANGELOG_ZH.md index 1540562..591644f 100644 --- a/docs/CHANGELOG_ZH.md +++ b/docs/CHANGELOG_ZH.md @@ -8,6 +8,59 @@ [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/). 并采用 [语义化版本](https://semver.org/lang/Chinese/). +## [0.6.0] - 2026-05-08 + +### 新增 + +- **Agent 系统**: 引入 Agent 配置管理功能,支持通过 YAML + frontmatter 定义 Agent 的系统提示词、约束和权限. 实现了 `AgentManager` + 单例模式, 支持 Agent 的加载、切换和持久化 ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **Skill 系统**: 添加 Skill 管理功能,支持动态加载和执行自定义 Shell 脚本作为扩展工具. 包含 + `SkillManager`、`skill_tool` + 和相关的 TUI 配置界面 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **Shell 工具**: 新增 `shell` + 工具,支持执行 Shell 命令并进行安全审核 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **路径验证增强**: 引入 `ExclusionManager` + 类,统一管理性能排除(.gitignore 规则)和安全排除(敏感文件拦截). 新增 + `SensitiveFileError` 异常, 直接禁止访问 `.env`、`*.pem`、`id_rsa` + 等敏感文件 ([#151](https://github.com/SunYanbox/ManualAid/issues/151)). +- **Gitignore 支持**: 新增 `GitignoreLoader` 模块,支持解析 `.gitignore` + 文件并应用排除规则到搜索和文件操作工具 ([#151](https://github.com/SunYanbox/ManualAid/issues/151)). +- **二进制文件检测扩展**: 扩展二进制文件检测器以支持 Godot 项目格式(.godot、.gd、.gd.uid、.tscn)和编译产物(.pdb、.pyd、.o) + ([#151](https://github.com/SunYanbox/ManualAid/issues/154)). +- **搜索工具二进制文件过滤**: 在 `regex_search` 和 `exact_search` + 工具中集成二进制文件检测机制,自动跳过二进制文件 ([#154](https://github.com/SunYanbox/ManualAid/issues/154)). +- **Agent 命令**: 新增 `/agent` + 命令,支持列出 Agent、切换当前 Agent、复制 Agent 配置和重置默认 Agent + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **配置管理器**: 新增 `ConfigManager` + 类,统一管理环境变量配置 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **审计提交器**: 新增 `AuditCommitter` + 类,处理审计系统的提交逻辑 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **TUI 配置标签页**: 新增环境配置和 Skill 配置标签页,提供图形化配置界面 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). +- **Shell 结果标签页**: 新增 Shell 执行结果标签页,展示命令输出 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). + +### 更改 + +- **系统提示词重构**: 重构系统提示词组装逻辑,支持基于 Agent 配置的动态覆盖. 明确定义提示词组装顺序:Role + → Constraints → Agent Directive → Tool Rules → Tool Definitions → Workflow + →Workspace Context → Augmentation → Extensions + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **工具权限过滤**: `/ws` + 命令现在根据当前 Agent 的工具权限白名单过滤工具定义 ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **路径排除逻辑重构**: 移除 `PermissionManager` 类,整合敏感文件规则至 + `ExclusionManager`. 简化搜索与遍历逻辑,统一使用 `ExclusionManager` + 进行路径过滤 ([#151](https://github.com/SunYanbox/ManualAid/issues/151)). +- **TUI 启动初始化**: TUI 启动时自动初始化默认 Agent + ([#149](https://github.com/SunYanbox/ManualAid/issues/149)). +- **数据库扩展**: 扩展数据库管理器,支持 Agent 和 Skill 相关数据的持久化 ([#155](https://github.com/SunYanbox/ManualAid/issues/155)). + +### 修复 + +- **Git 工具输出保留**: 修复当 Git 命令返回非零退出码但仍有标准输出时(如 + `git diff --exit-code`),之前的代码会完全丢弃 stdout 的问题. 现在总是保留 stdout,即使 returncode + != 0 ([#150](https://github.com/SunYanbox/ManualAid/issues/150)). + ## [0.5.0] - 2026-05-05 ### 新增 @@ -198,6 +251,7 @@ _初始发布的功能和历史记录._ +[0.6.0]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.6.0 [0.5.0]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.5.0 [0.4.1]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.4.1 [0.4.0]: https://github.com/SunYanbox/ManualAid/releases/tag/v0.4.0 diff --git a/pyproject.toml b/pyproject.toml index ed36fd5..c099493 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "ManualAid" -version = "0.5.0" +version = "0.6.0" description = "" requires-python = ">=3.14" dependencies = [ diff --git a/src/constants/__init__.py b/src/constants/__init__.py index 3d18726..906d362 100644 --- a/src/constants/__init__.py +++ b/src/constants/__init__.py @@ -1 +1 @@ -__version__ = "0.5.0" +__version__ = "0.6.0"