fyjjuk/FerdoNAN

# FerdoNAN - 多 Agent AI 个人助手 **版本：** 2.5.0（slash 命令，UI 重构） **状态：** 生产稳定 | **架构：** 六边形 + 插件化 ## 概述 FerdoNAN 是一个模块化的 AI 助手 framework，基于专业化的 agent 设计，遵循**低耦合**和**高内聚**原则。每个 agent 使用自己的 LLM、安全配置和能力运行，而核心（`core/`）则提供编排、路由、执行和多层安全服务。 **v2.5.0 新特性：** - slash 命令（`/help`, `/exit`, `/agent list`, `/agent switch`, `/config show`, `/clear`） - UI 重构：在 `ui/cli_commands.py` 中提供可复用的命令 - Agent 选择器重命名为 `ui/agent_selector.py` - SemVer 版本管理系统（`VERSION` 文件） ## 高层架构 ``` flowchart LR CLI[CLI Interface] --> ENGINE[FerdoNANEngine] ENGINE --> PIPELINE[Pipeline Processor] PIPELINE --> ROUTER[Intent Router] PIPELINE --> EXECUTOR[Executor Registry] EXECUTOR --> LLM[LLM Providers] EXECUTOR --> RAG[RAG Engine] ENGINE --> INGRESS[Ingress Filter] ENGINE --> EGRESS[Egress Filter] ENGINE --> GATEKEEPER[Gatekeeper] ROUTER --> AGENTS[Specialized Agents] RAG --> MARKITDOWN[MarkItDown Parser] CLI --> THEMES[UI Themes] CLI --> ASCII[ASCII Studio] CLI --> CMDS[CLI Commands] ``` ## 项目结构 (v2.5.0) ``` ferdonan/ ├── agents/ # Agentes especializados │ ├── narrador_dnd/ # Director de juego D&D │ │ ├── resources/ # Recursos inmutables (libros, reglas) │ │ ├── workspace/ # Datos dinámicos (personajes, inventarios) │ │ ├── tools/ # Herramientas propias del agente │ │ └── routes/ # Rutas YAML │ ├── spotify_player/ # Control de Spotify │ └── dev_assistant/ # Asistente de desarrollo ├── core/ # Motor principal │ ├── engine.py # Estado e inicialización │ ├── pipeline.py # Pipeline de procesamiento │ ├── factory.py # Creación de componentes │ ├── llm_factory.py # Creación de clientes LLM │ ├── interfaces.py # Protocolos y ABCs │ └── i18n/ # Sistema de localización ├── security/ # Firewalls y seguridad │ ├── filters/ # Ingress, egress, semantic │ ├── auth/ # Gatekeeper, audit │ └── rate_limiter.py ├── services/ # Servicios core │ ├── executor/ # Ejecutores (cognitive, script, stage_runner) │ ├── router/ # Enrutamiento (keyword, embedding, hybrid, LLM) │ ├── sanitizer/ # Limpieza de inputs │ ├── llm_providers/ # Ollama, Gemini, Groq, Local │ └── rag/ # RAG modular con MarkItDown ├── ui/ # Interfaz de usuario │ ├── agent_selector.py # Selector de agentes │ ├── cli_commands.py # Comandos slash reutilizables │ ├── console/ # Renderer con temas ANSI │ ├── ascii/ # Banners, boxes, tables, spinners │ └── themes/ # Temas YAML (refero, cyberpunk) ├── libs/ # Biblioteca de recursos (ejemplos) │ └── routes/ # Rutas de ejemplo por versión ├── models/ # Modelos de datos Pydantic ├── tests/ # Pruebas unitarias (44+ tests) ├── locales/ # Diccionarios i18n (en, es) ├── VERSION # Versión SemVer del proyecto └── docs/ # Documentación Sphinx ``` ## CLI 命令 | 命令 | 描述 | |---|---| | `/help` | 显示帮助 | | `/exit` 或 `/quit` | 退出助手 | | `/agent list` | 列出所有可用的 agent | | `/agent switch <名称>` | 切换到指定的 agent | | `/config show` | 显示当前配置 | | `/clear` | 清除屏幕 | 你也可以输入 `salir`、`exit` 或 `quit` 来退出。 ## 主要特性 ### 核心与 Agent - 专业化 Agent：通过 YAML 配置，语义路由，持久化记忆 - 多 LLM：Ollama（本地），Gemini（Google），Groq（LPU），Local（自定义） - Stages 系统：使用不同提供商的 LLM 进行链式调用 ### 高级 RAG (MarkItDown) - 智能 Parser：支持 PDF, DOCX, XLSX, PPTX, HTML, 图像 (OCR), URL - Parser 注册表：通过 `@register_parser` 装饰器进行扩展 ### UI 与用户体验 - 视觉主题：可通过 YAML 配置（颜色、徽章、表情符号） - CLI 命令：完整的 slash 命令系统 - 持久化历史记录：命令在多次会话间保存 - ASCII Studio：横幅、装饰框、表格、加载动画 ### 开发者助手 (Spec-Kit) - GitHub integration：列出 repos、PRs、issues；创建 PRs/issues - Code review：风格分析，检测 TODOs/FIXMEs ### 安全性 - 多层防火墙：Ingress（正则表达式），Egress（黑名单），语义（敏感词） - Gatekeeper：带超时的人工审批 - Rate Limiting：基于用户的滑动窗口 ## 使用 Docker 演示 ``` git clone https://github.com/fyjjuk/FerdoNAN cd FerdoNAN docker-compose -f docker-compose.demo.yml up # 在另一个 terminal： docker exec -it ferdonan-ollama ollama pull phi3:mini docker exec -it ferdonan-ollama ollama pull llama3.2:3b ``` ## 本地安装 ``` git clone https://github.com/fyjjuk/FerdoNAN cd FerdoNAN python -m venv venv source venv/bin/activate pip install -r requirements.txt ollama serve # En otra terminal python main.py ``` ## 单元测试 ``` pytest tests/ -v ``` ## 可扩展性 ### 创建新 Agent ``` mkdir -p agents/mi_agente/{routes,tools,workspace,resources} # 创建 agents/mi_agente/config.yaml # 创建 agents/mi_agente/routes/mi_ruta.yaml ``` ### 添加新的 slash 命令 编辑 `ui/cli_commands.py` 并在 `process_slash_command()` 函数中添加你的命令。 ## 技术文档 ``` cd docs/build/html python -m http.server 8000 # 打开 http://localhost:8000 ``` ## 许可证 MIT ## 致谢 - [Repomix](https://github.com/yamadashy/repomix) - AI 代码打包工具 - [ChromaDB](https://www.trychroma.com/) - 向量数据库 - [MarkItDown](https://github.com/microsoft/markitdown) - 文档转换工具 - [PyGithub](https://pygithub.readthedocs.io/) - GitHub API

标签：AI助手, AI风险缓解, RAG, 人工智能, 多智能体, 插件化架构, 用户模式Hook绕过, 请求拦截, 逆向工具