leileiya1/Nova-agent

# Nova Agent Nova Agent 是一个本地优先的命令行 coding agent。 它的目标不是只做一个“能聊天的模型壳”，而是让 Agent 在终端里具备接近实际开发工作的能力： - 读取和搜索项目文件 - 修改文件并展示彩色 diff - 运行命令和测试 - 基于审批策略控制高风险工具 - 动态加载 Skills - 动态加载外部 MCP - 以 CLI 形式持续交互，而不是一次性脚本 当前项目偏 Windows 终端体验，交互上已经包含： - 欢迎页和状态卡片 - 思考/执行中的加载面板 - `Esc` 取消当前请求 - 文件改动预览 - 人工审批面板 - 会话保存与恢复 ## 1. 项目结构 核心目录如下： Nova-agent/ ├─ src/ │ ├─ main.py # CLI 启动入口 │ ├─ cli/ │ │ ├─ app.py # 主循环、交互、审批、改动预览 │ │ ├─ commands.py # /help /env /skills /mcp 等命令 │ │ ├─ runtime.py # Agent 构建、工具挂载、prompt 注入 │ │ ├─ state.py # 会话状态与保存/加载 │ │ └─ ui.py # 所有终端面板和样式 │ ├─ core/ │ │ ├─ model_factory.py # 模型创建 │ │ └─ extension_loader.py # Skills/MCP/扩展配置加载 │ ├─ prompt/ │ │ ├─ system_prompt.md │ │ └─ human_prompt.md │ └─ tools/ │ └─ agent_toolbox.py # 核心工具箱 ├─ test/ # 自动化测试 ├─ .env.example # 系统环境变量示例 └─ .nova-extensions.json.example ## 2. 运行前准备 ### 2.1 Python 版本 建议使用： - Python 3.11 或 3.12 ### 2.2 安装依赖 当前仓库没有提供 `pyproject.toml` 或 `requirements.txt`，可以先手动安装项目已使用到的核心依赖： pip install langchain langchain-core langgraph langchain-openai python-dotenv httpx pytest 如果你已经在自己的虚拟环境中安装过这些包，可以直接跳过。 ### 2.3 推荐使用虚拟环境 Windows PowerShell： python -m venv .venv .venv\Scripts\Activate.ps1 然后再执行依赖安装命令。 ## 3. 模型配置 Nova Agent 启动和实际调用模型时，会检查以下环境变量： - `LLM_API_KEY` - `LLM_BASE_URL` - `LLM_MODEL_NAME` - `LLM_TEMPERATURE` 可选，默认 `0.7` ### 3.1 最推荐的做法：使用系统环境变量 模型访问配置现在只认系统环境变量。 项目根目录中的 [.env.example](/D:/Project/JavaProject/Nova-agent/.env.example) 只保留作为变量名参考，不再作为运行时配置来源。 如果你希望在整台机器上统一使用一套模型配置，请直接设置系统环境变量。 Windows 示例： setx LLM_API_KEY "your_api_key" setx LLM_BASE_URL "https://your-base-url" setx LLM_MODEL_NAME "your_model_name" 设置后重新打开一个终端窗口再运行 CLI。 说明： - 模型访问配置只认系统环境变量 - CLI 自身默认项单独保存在 `~/.nova/.setting.json` ### 3.2 检查配置是否生效 启动 CLI 后执行： /env 你会看到： - 当前模型名 - `LLM_API_KEY` 是否已配置 - `LLM_BASE_URL` 是否已配置 - 如果缺失，会显示 Windows `setx` 示例 ### 3.4 安全提醒 - 不要把真实 API Key 提交到 Git - 不要把真实 API Key 提交到 Git - 推荐始终通过系统环境变量管理模型配置 ## 4. 启动方式 最直接的启动方式： python src/main.py ### 4.1 常用启动参数 支持的核心参数如下： python src/main.py ^ --workspace D:/Project/JavaProject/Nova-agent ^ --context "当前重点处理 tools 和 prompt" ^ --model claude-sonnet-4-5-20250929-thinking ^ --thread-id demo-thread ^ --change-preview inline ^ --change-preview-details collapse ^ --change-preview-scope current ^ --mcp-mode auto ^ --skills on 参数说明： - `--workspace` - 指定当前工作区目录 - `--context` - 注入额外上下文说明 - `--model` - 指定模型名，优先于默认值 - `--thread-id` - 指定当前会话线程 ID - `--auto-approve` - 直接自动放行所有工具调用，不再请求人工审批 - `--change-preview` - `inline` 或 `off` - `--change-preview-details` - `expand` 或 `collapse` - `--change-preview-scope` - `current` 或 `all` - `--mcp-mode` - `off`、`auto`、`all` 或某个外部模块 key - `--skills` - `on` 或 `off` - `--no-color` - 关闭终端颜色 ### 4.2 两个最常用的启动示例 安全模式： python src/main.py 全自动放行： python src/main.py --auto-approve ## 5. CLI 使用方式 启动后就是一个持续对话的终端界面。你可以直接输入自然语言任务，例如： 帮我分析当前项目结构 请修改 tools 目录下的实现并运行测试 请查看当前 git diff ### 5.1 多行输入 如果一条请求很长，可以在每行末尾输入 `\` 继续下一行： 请帮我做下面几件事 \ 先分析项目结构 \ 再告诉我下一步怎么重构 ### 5.2 中断当前请求 当 Agent 正在思考或执行时： - 可以按 `Esc` 取消当前运行 适合长任务、误触发、或者你想马上换一个请求的时候使用。 ## 6. 内置命令 Nova Agent 支持一组 CLI 内部命令。 ### 6.1 帮助和状态 - `/help` - 查看所有命令 - `/env` - 查看模型环境变量状态 - `/tools` - 查看工具组 - `/extensions` - 查看当前 Skills / MCP 发现情况 - `/history` - 查看最近会话历史 - `/summary` - 查看最近上下文摘要 - `/clear` - 清屏并重绘欢迎页 ### 6.2 模型和上下文 - `/model` - 查看当前模型 - `/model ` - 切换当前模型 - `/context` - 查看当前上下文 - `/context ` - 更新上下文 - `/workspace` - 查看当前工作区 - `/workspace ` - 切换工作区 ### 6.3 审批控制 - `/approval` - 查看当前审批模式和审批策略 - `/approval safe` - 切回安全模式 - `/approval auto` - 切到自动放行模式 ### 6.4 改动预览 - `/changes` - 查看当前改动预览配置 - `/changes expand` - 默认展开 diff - `/changes collapse` - 默认折叠 diff - `/changes toggle` - 切换展开/折叠 - `/changes current` - 仅查看当前文件 - `/changes all` - 查看全部文件 ### 6.5 工具结果展示 - `/toolview` - 查看当前工具结果展示模式 - `/toolview expand` - 展开工具结果 - `/toolview collapse` - 折叠工具结果 - `/toolview toggle` - 切换模式 ### 6.6 Skills / MCP - `/skills` - 查看发现到的 skills - `/skills on` - 开启 skills - `/skills off` - 关闭 skills - `/mcp` - 查看当前 MCP 模式 - `/mcp off` - 关闭 MCP - `/mcp auto` - 自动按请求装载 MCP - `/mcp all` - 加载全部外部 MCP - `/mcp ` - 仅加载指定 MCP 模块 ### 6.7 会话保存和加载 - `/save` - 保存到默认会话文件 - `/save ` - 保存到指定文件 - `/load` - 从默认会话文件恢复 - `/load ` - 从指定文件恢复 默认会话文件： - `~/.nova/sessions///nova-session.json` ### 6.8 退出 以下任意一条都可以退出： - `exit` - `quit` - `q` - `:q` ## 7. Agent 工具能力 工具统一收口在： - [agent_toolbox.py](/D:/Project/JavaProject/Nova-agent/src/tools/agent_toolbox.py) 目前按工具组组织。 ### 7.1 `core` - `list_directory` - `path_exists` - `fuzzy_search_file` - `search_in_files` - `read_file` - `read_files_batch` ### 7.2 `edit` - `write_file` - `make_directory` - `delete_file` - `delete_directory` ### 7.3 `execute` - `run_shell_command` - `run_tests` ### 7.4 `git` - `git_status` - `git_diff` ### 7.5 `external` - `web_search` - `get_weather` ## 8. 审批机制 Nova Agent 已接入人工审批中间件。 默认思路是： - 低风险工具自动放行 - 高风险工具人工确认 ### 8.1 默认自动放行 通常包括： - 文件读取 - 目录查看 - 内容搜索 - Git 状态/差异查看 - 外部信息查询 ### 8.2 默认需要审批 通常包括： - 写文件 - 建目录 - 删文件 - 删目录 - 执行 shell - 运行测试 ### 8.3 审批时可做什么 审批弹窗里通常支持： - `Approve` - `Edit` - `Reject` 其中 `Edit` 支持对参数做引导式修改，不要求用户手写 JSON。 ### 8.4 全局放行 如果你非常确定当前任务不需要人工审批，可以在启动时加： python src/main.py --auto-approve ## 9. Skills 使用方式 Skills 的设计目标是： 让不懂 JSON 的用户，也能直接通过文件夹和 Markdown 给 Agent 增加局部能力。 ### 9.1 默认扫描路径 程序会自动扫描： - `skills//` - `.nova/skills//` - `~/.nova/skills//` - `~/.codex/skills//`（兼容旧位置） ### 9.2 一个 skill 怎么组织 推荐结构： skills/ review-helper/ SKILL.md patterns.md post-helper/ README.md examples.md ### 9.3 读取规则 一个 skill 目录里可以放多个 Markdown 文件，程序会优先读取： - `SKILL.md` - `README.md` - 其他 `*.md` 最终会按顺序合并成一份技能上下文。 ### 9.4 怎么触发某个 skill 你可以在请求里显式写 skill 名，例如： 请使用 review-helper 帮我审查这次改动 或者： 请使用 post-helper 帮我生成帖子草稿 ### 9.5 查看当前发现到的 skills /skills 你会看到： - 技能名称 - 读取了哪些 Markdown 文件 - 每个技能的摘要说明 ## 10. MCP 配置方式 MCP 现在走“外部配置 + 动态装载”模式。 ### 10.1 配置文件 示例文件： - [.nova-extensions.json.example](/D:/Project/JavaProject/Nova-agent/.nova-extensions.json.example) 实际使用时，复制为： - `~/.nova/.extensions.json` ### 10.2 支持的类型 目前支持 3 类外部 MCP： - `python_file` - `command` - `http` ### 10.3 示例：`python_file` { "mcp": { "mode": "auto", "external": [ { "key": "custom_docs", "enabled": true, "type": "python_file", "path": "./external_mcp/custom_docs_tools.py", "keywords": ["docs", "文档", "知识库"] } ] } } ### 10.4 示例：`command` { "mcp": { "mode": "auto", "external": [ { "key": "shell_bridge", "enabled": true, "type": "command", "command": "python", "args": ["./external_mcp/command_bridge.py"], "cwd": ".", "timeout": 30, "keywords": ["shell", "命令桥接"], "tools": [ { "name": "echo", "description": "Call an external command bridge tool with a text payload." } ] } ] } } ### 10.5 示例：`http` { "mcp": { "mode": "auto", "external": [ { "key": "http_bridge", "enabled": true, "type": "http", "url": "http://127.0.0.1:8081/invoke", "method": "POST", "headers": { "Authorization": "Bearer " }, "timeout": 30, "keywords": ["search", "搜索文档"], "tools": [ { "name": "search_docs", "description": "Call an external HTTP bridge tool with a text payload." } ] } ] } } ### 10.6 `mode` 的含义 - `off` - 不加载 MCP - `auto` - 根据用户请求和 `keywords` 自动选择 - `all` - 加载所有外部 MCP - `` - 只加载指定模块 ### 10.7 如何查看 MCP 是否生效 启动后执行： /extensions 和： /mcp ## 11. Prompt 维护方式 Prompt 已经拆到 Markdown 文件里，便于维护： - [system_prompt.md](/D:/Project/JavaProject/Nova-agent/src/prompt/system_prompt.md) - [human_prompt.md](/D:/Project/JavaProject/Nova-agent/src/prompt/human_prompt.md) 建议： - 改系统行为，改 `system_prompt.md` - 改用户任务模板，改 `human_prompt.md` - 不要再把长 prompt 硬编码回 Python 文件 ## 12. 文件改动预览 当 Agent 修改文件时，会展示单独的 `Changes` 面板。 特点： - 新增内容用绿色 - 删除内容用红色 - 支持 `created / modified / deleted` 角标 - 支持自动折叠大 diff - 支持只看当前文件或全部文件 ### 12.1 运行时切换 /changes /changes expand /changes collapse /changes current /changes all ## 13. 会话状态 CLI 会维护当前会话状态，包括： - 当前 workspace - 当前 context - 当前 model - 审批模式 - skills / mcp 模式 - 改动预览设置 - 最近历史 ### 13.1 保存 /save ### 13.2 加载 /load ### 13.3 默认文件 - `~/.nova/sessions///nova-session.json` ## 14. 常见使用流程 ### 14.1 第一次启动 1. 配置系统环境变量 2. 确认 `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL_NAME` 已生效 3. 运行 `python src/main.py` 4. 执行 `/env` 检查环境 5. 执行 `/skills` 和 `/extensions` 看扩展是否加载 6. 开始输入自然语言任务 ### 14.2 用它改代码 1. 启动 CLI 2. 输入“帮我分析当前项目结构” 3. 再输入“请修改某某文件并运行测试” 4. 审批需要确认的高风险操作 5. 查看 `Changes` 面板 6. 再输入“请查看当前 git diff” ### 14.3 用本地 skills 扩展能力 1. 创建 `skills/review-helper/SKILL.md` 2. 写入你的规则 3. 启动 CLI 4. 输入“请使用 review-helper 帮我审查这次改动” ### 14.4 用外部 MCP 扩展能力 1. 参考 `.nova-extensions.json.example` 创建 `~/.nova/.extensions.json` 2. 添加你的 MCP 配置 3. 启动 CLI 4. 执行 `/extensions` 5. 执行 `/mcp` 6. 输入一个能命中 `keywords` 的请求 ## 15. 自动化测试 运行测试： pytest -q 语法检查： python -m py_compile src/main.py src/cli/app.py src/cli/commands.py src/cli/runtime.py src/cli/state.py src/cli/ui.py src/core/extension_loader.py src/core/model_factory.py src/tools/agent_toolbox.py test/main_test.py test/file_test.py ## 16. 常见问题 ### 16.1 `/env` 显示缺配置，但我明明配了 排查顺序： 1. 先确认你是在当前工作区下运行 2. 执行 `/env` 3. 确认系统环境变量名是不是： - `LLM_API_KEY` - `LLM_BASE_URL` - `LLM_MODEL_NAME` 4. 设置完成后重新打开一个新的终端窗口 ### 16.2 为什么有些操作会要求审批 因为这类操作风险更高，比如： - 覆盖文件 - 删除文件或目录 - 执行 shell - 运行测试 这是设计使然，不是故障。 ### 16.3 为什么 skills 没生效 先检查： - skill 目录是不是在默认扫描路径下 - skill 目录里是否有 `SKILL.md` 或 `README.md` - 你是否在请求里明确提到了 skill 名 - `/skills` 是否能看到该 skill ### 16.4 为什么 MCP 没加载 先检查： - `~/.nova/.extensions.json` 是否存在 - `enabled` 是否为 `true` - `mcp.mode` 是否合适 - `/extensions` 是否能看到对应模块 - 请求里是否命中了 `keywords` ## 17. 当前建议 如果你准备继续把这个项目做成长期使用的智能体，建议按下面顺序迭代： 1. 补一份依赖清单，例如 `requirements.txt` 或 `pyproject.toml` 2. 给外部 MCP 单独写一份 `EXTENSIONS.md` 3. 给环境配置单独写一份 `ENVIRONMENT.md` 4. 对审批策略和 `~/.nova/.policy.json` 再补一份专门文档 5. 最后再考虑分发、安装脚本和自动升级 ## 18. Electron 集成 如果你准备把当前 CLI 集成到 Electron 桌面应用中，查看： - [ELECTRON_INTEGRATION.md](/D:/Project/JavaProject/Nova-agent/ELECTRON_INTEGRATION.md) 文档中已经包含： - CLI 当前提供的核心能力 - Electron 如何调用 CLI - 常用命令与自然语言任务示例 - 用户级 `.nova` 目录结构 - `thread_id` 规则 - Windows 打包路线 如果你只是想最快跑起来，最短路径就是： 1. 配系统环境变量 2. `python src/main.py` 3. `/env` 4. `/skills` 5. 开始提需求

标签：AI 编程, CLI 工具, Coding Agent, LangChain, LLM 应用, MCP, Python, SOC Prime, Windows 终端, 人工智能, 代码生成, 会话管理, 命令行助手, 大模型集成, 安全规则引擎, 工作流自动化, 工具调用, 开发工具, 开源框架, 持续集成, 文件操作, 文档结构分析, 无后门, 本地优先, 渗透测试工具, 用户模式Hook绕过, 终端用户界面, 网络调试, 自动化, 轻量级, 逆向工具