Agentic LLM Workflow：本地优先的 AI 编码助手，赋予大模型完整的工具调用能力

Agentic LLM Workflow 是一个终端交互式 AI 编码助手，通过工具调用机制让本地部署的大模型获得文件操作、Git 管理、网络搜索等完整能力，支持多种权限配置和沙箱隔离，适合注重隐私和可控性的开发场景。

项目定位与设计哲学\n\nAgentic LLM Workflow 是一个面向开发者的本地 AI 编码助手，其核心设计理念是"本地优先、工具原生"。与依赖云端服务的编码助手不同，该项目完全运行在用户终端，无需浏览器或云端 IDE，所有数据保留在本地，满足对隐私和可控性有严格要求的开发场景。\n\n项目的核心创新在于将大模型从"文本生成器"转变为"工具使用者"。通过结构化的工具调用机制，模型可以主动读取文件、编辑代码、执行 Git 命令、搜索网络信息，并基于执行结果进行下一步决策，形成真正的自主工作流。\n\n## 核心特性解析\n\n### 本地优先架构\n\n项目采用完全本地化的设计：\n- 无云端依赖：所有计算在本地完成，无需上传代码到第三方服务\n- 终端原生：基于终端的交互界面，符合开发者使用习惯\n- 工作区沙箱：文件访问限制在声明的工作目录内，防止越权访问\n- 隐私保护：代码和敏感信息不会离开本地机器\n\n这种设计特别适合处理敏感代码、私有项目或在网络受限环境中工作。\n\n### 丰富的工具集\n\n项目为模型提供了六大类工具，覆盖开发工作的主要场景：\n\n#### 文件系统工具\n支持完整的文件操作能力：\n- 读取文件内容（支持代码高亮和语法分析）\n- 写入和修改文件（支持补丁应用和文本替换）\n- 目录遍历和文件搜索\n- 文件移动、删除、创建目录等操作\n\n#### Git 集成工具\n提供本地和远程 Git 操作：\n- 本地操作：status、diff、log、commit、branch、stash 等\n- 远程操作：push、pull、fetch、clone、remote 管理\n- GitHub API 调用：issue、PR、release 等操作\n\n#### 网络搜索与获取\n- Web 搜索：通过 Serper API 进行网页、新闻、图片搜索\n- URL 获取：直接读取指定网页内容\n\n#### 系统工具\n- 执行任意命令\n- 查看进程信息\n- 查询环境变量\n- 运行诊断检查\n\n#### 视觉支持\n- 附加工作区图片到对话，支持多模态模型分析\n\n#### 文件监控\n- 自动检测工作区变更并触发后续 Agent 回合\n\n### 权限配置与安全保障\n\n项目提供了三级权限配置，平衡灵活性和安全性：\n\n#### Strict 模式（默认）\n- 读取和原地编辑自由允许\n- 破坏性操作（删除文件、Git commit/push、运行命令）需要显式确认\n- 适合日常开发使用\n\n#### Dev 模式\n与 Strict 模式相同，保留未来扩展空间\n\n#### CI 模式\n- 完全禁止所有修改操作\n- 仅允许读取和查询类工具\n- 适合自动化流水线使用\n\n此外，项目还提供 /yolo 命令可临时禁用确认提示（仅在隔离环境使用），/safe 命令恢复安全模式。\n\n## 技术架构\n\n项目采用模块化架构，主要组件包括：\n\n### Agent 层\n- runner.py：AgentRunner，驱动对话轮次和工具调用循环\n- executor.py：ToolExecutor，分发工具调用并处理审批流程\n- state.py：SessionState，管理消息历史和上下文跟踪\n- watch/：FileWatchService，工作区变更检测\n\n### LLM 客户端层\n- client.py：LLMClient，支持 OpenAI 兼容的聊天补全接口\n- stream.py：流式响应处理\n- vision.py：Base64 图片编码，支持多模态对话\n\n### 工具层\n- registry.py：工具注册和沙箱隔离\n- fs/：文件系统工具实现\n- git/：Git 工具实现\n- web/：网络搜索和 URL 获取\n- system.py：系统命令执行\n\n### UI 层\n- 基于 Rich 库的终端美化输出\n- 支持 Markdown 渲染和代码高亮\n- 流式输出显示\n\n## 使用场景与示例\n\n### 场景一：代码审查与重构\n\n开发者可以要求 Agent 分析代码库并执行重构：\n\n> 分析 tools/fs/read.py 中的所有公共函数\n> 为 read_json 函数添加文档字符串\n> 运行 tests/ 目录下的测试并修复失败项\n> git commit -m \"docs: 为 fs/read 工具添加文档字符串\"\n\n\nAgent 会按顺序执行：读取文件、分析代码、编辑文件、运行测试、提交更改。\n\n### 场景二：依赖分析与升级\n\n\n> 检查项目的依赖项是否有安全漏洞\n> 搜索最新版本的依赖推荐\n> 更新 requirements.txt 中的版本号\n> 运行测试验证兼容性\n\n\n### 场景三：自动化文档生成\n\n\n> 读取所有 Python 模块的 docstring\n> 生成 API 文档草稿\n> 将文档写入 docs/api.md\n\n\n## 支持的模型与配置\n\n项目支持任何 OpenAI 兼容的 LLM 端点，包括：\n- llama.cpp 本地服务器\n- Ollama\n- LM Studio\n- vLLM\n- 云端 OpenAI 兼容 API\n\n默认配置针对 Gemma 4 31B 优化，但可通过命令行或配置文件切换模型：\nbash\npython main.py --model qwen2.5-coder:32b\n\n\n配置支持环境变量注入，敏感信息（API 密钥）可通过 .env 文件管理，避免硬编码。\n\n## 交互式命令\n\n项目提供了丰富的 slash 命令，提升交互效率：\n\n| 命令 | 功能 |\n|------|------|\n| /help | 显示所有命令 |\n| /tools | 列出所有可用工具 |\n| /context | 显示上下文窗口使用情况 |\n| /workspace [path] | 查看或切换工作区 |\n| /compact | 压缩对话历史 |\n| /clear | 重置对话 |\n| /model [name] | 列出或切换模型 |\n| /profile | 切换权限配置 |\n| /yolo | 禁用确认提示 |\n| /safe | 恢复安全模式 |\n| /save/load | 保存/加载对话 |\n| /export | 导出对话到 Markdown |\n| /watch | 管理文件监控 |\n| /image | 附加图片到对话 |\n| /task | 注入结构化任务清单 |\n| /plan | 注入规划模式消息 |\n| /exit | 退出 |\n\n## 与 MCP 的关系\n\n项目明确提到支持 MCP（Model Context Protocol），这是 Anthropic 推出的开放协议，用于标准化模型与外部工具的交互。通过 MCP，Agentic LLM Workflow 可以接入更广泛的工具生态，实现与数据库、API、文件系统等外部资源的深度集成。\n\n## 适用人群与场景\n\n该项目特别适合：\n\n- 隐私敏感开发者：代码不能上传云端，需要在本地处理\n- 企业内网环境：无法访问外部 AI 服务\n- 定制化需求：需要精细控制 Agent 行为和权限\n- 学习研究：理解 Agent 架构和工具调用机制\n- 自动化脚本：CI/CD 流程中的代码分析和处理\n\n## 局限性与注意事项\n\n- 当前未指定开源许可证，使用时需注意法律风险\n- 依赖外部 API（如 Serper）进行网络搜索，需要单独配置密钥\n- 本地模型性能受硬件限制，复杂任务可能需要较长时间\n- 工具调用准确性取决于模型能力，建议人工审核重要修改\n\n## 总结与展望\n\nAgentic LLM Workflow 代表了本地 AI 助手的发展方向：在保持数据隐私的同时，赋予模型完整的工具使用能力。其模块化架构、丰富的工具集和灵活的权限配置，使其成为开发者探索 AI Agent 应用的实用工具。\n\n随着本地大模型能力的持续提升和 MCP 生态的成熟，这类本地优先的 Agent 工具将在隐私敏感场景和企业内网环境中发挥越来越重要的作用。

项目定位与设计哲学\n\nAgentic LLM Workflow 是一个面向开发者的本地 AI 编码助手，其核心设计理念是"本地优先、工具原生"。与依赖云端服务的编码助手不同，该项目完全运行在用户终端，无需浏览器或云端 IDE，所有数据保留在本地，满足对隐私和可控性有严格要求的开发场景。\n\n项目的核心创新在于将大模型从"文本生成器"转变为"工具使用者"。通过结构化的工具调用机制，模型可以主动读取文件、编辑代码、执行 Git 命令、搜索网络信息，并基于执行结果进行下一步决策，形成真正的自主工作流。\n\n核心特性解析\n\n本地优先架构\n\n项目采用完全本地化的设计：\n- 无云端依赖：所有计算在本地完成，无需上传代码到第三方服务\n- 终端原生：基于终端的交互界面，符合开发者使用习惯\n- 工作区沙箱：文件访问限制在声明的工作目录内，防止越权访问\n- 隐私保护：代码和敏感信息不会离开本地机器\n\n这种设计特别适合处理敏感代码、私有项目或在网络受限环境中工作。\n\n丰富的工具集\n\n项目为模型提供了六大类工具，覆盖开发工作的主要场景：\n\n文件系统工具\n支持完整的文件操作能力：\n- 读取文件内容（支持代码高亮和语法分析）\n- 写入和修改文件（支持补丁应用和文本替换）\n- 目录遍历和文件搜索\n- 文件移动、删除、创建目录等操作\n\nGit 集成工具\n提供本地和远程 Git 操作：\n- 本地操作：status、diff、log、commit、branch、stash 等\n- 远程操作：push、pull、fetch、clone、remote 管理\n- GitHub API 调用：issue、PR、release 等操作\n\n网络搜索与获取\n- Web 搜索：通过 Serper API 进行网页、新闻、图片搜索\n- URL 获取：直接读取指定网页内容\n\n系统工具\n- 执行任意命令\n- 查看进程信息\n- 查询环境变量\n- 运行诊断检查\n\n视觉支持\n- 附加工作区图片到对话，支持多模态模型分析\n\n文件监控\n- 自动检测工作区变更并触发后续 Agent 回合\n\n权限配置与安全保障\n\n项目提供了三级权限配置，平衡灵活性和安全性：\n\nStrict 模式（默认）\n- 读取和原地编辑自由允许\n- 破坏性操作（删除文件、Git commit/push、运行命令）需要显式确认\n- 适合日常开发使用\n\nDev 模式\n与 Strict 模式相同，保留未来扩展空间\n\nCI 模式\n- 完全禁止所有修改操作\n- 仅允许读取和查询类工具\n- 适合自动化流水线使用\n\n此外，项目还提供 /yolo 命令可临时禁用确认提示（仅在隔离环境使用），/safe 命令恢复安全模式。\n\n技术架构\n\n项目采用模块化架构，主要组件包括：\n\nAgent 层\n- runner.py：AgentRunner，驱动对话轮次和工具调用循环\n- executor.py：ToolExecutor，分发工具调用并处理审批流程\n- state.py：SessionState，管理消息历史和上下文跟踪\n- watch/：FileWatchService，工作区变更检测\n\nLLM 客户端层\n- client.py：LLMClient，支持 OpenAI 兼容的聊天补全接口\n- stream.py：流式响应处理\n- vision.py：Base64 图片编码，支持多模态对话\n\n工具层\n- registry.py：工具注册和沙箱隔离\n- fs/：文件系统工具实现\n- git/：Git 工具实现\n- web/：网络搜索和 URL 获取\n- system.py：系统命令执行\n\nUI 层\n- 基于 Rich 库的终端美化输出\n- 支持 Markdown 渲染和代码高亮\n- 流式输出显示\n\n使用场景与示例\n\n场景一：代码审查与重构\n\n开发者可以要求 Agent 分析代码库并执行重构：\n\n> 分析 tools/fs/read.py 中的所有公共函数\n> 为 read_json 函数添加文档字符串\n> 运行 tests/ 目录下的测试并修复失败项\n> git commit -m \"docs: 为 fs/read 工具添加文档字符串\"\n\n\nAgent 会按顺序执行：读取文件、分析代码、编辑文件、运行测试、提交更改。\n\n场景二：依赖分析与升级\n\n\n> 检查项目的依赖项是否有安全漏洞\n> 搜索最新版本的依赖推荐\n> 更新 requirements.txt 中的版本号\n> 运行测试验证兼容性\n\n\n场景三：自动化文档生成\n\n\n> 读取所有 Python 模块的 docstring\n> 生成 API 文档草稿\n> 将文档写入 docs/api.md\n\n\n支持的模型与配置\n\n项目支持任何 OpenAI 兼容的 LLM 端点，包括：\n- llama.cpp 本地服务器\n- Ollama\n- LM Studio\n- vLLM\n- 云端 OpenAI 兼容 API\n\n默认配置针对 Gemma 4 31B 优化，但可通过命令行或配置文件切换模型：\nbash\npython main.py --model qwen2.5-coder:32b\n\n\n配置支持环境变量注入，敏感信息（API 密钥）可通过 .env 文件管理，避免硬编码。\n\n交互式命令\n\n项目提供了丰富的 slash 命令，提升交互效率：\n\n| 命令 | 功能 |\n|------|------|\n| /help | 显示所有命令 |\n| /tools | 列出所有可用工具 |\n| /context | 显示上下文窗口使用情况 |\n| /workspace [path] | 查看或切换工作区 |\n| /compact | 压缩对话历史 |\n| /clear | 重置对话 |\n| /model [name] | 列出或切换模型 |\n| /profile | 切换权限配置 |\n| /yolo | 禁用确认提示 |\n| /safe | 恢复安全模式 |\n| /save/load | 保存/加载对话 |\n| /export | 导出对话到 Markdown |\n| /watch | 管理文件监控 |\n| /image | 附加图片到对话 |\n| /task | 注入结构化任务清单 |\n| /plan | 注入规划模式消息 |\n| /exit | 退出 |\n\n与 MCP 的关系\n\n项目明确提到支持 MCP（Model Context Protocol），这是 Anthropic 推出的开放协议，用于标准化模型与外部工具的交互。通过 MCP，Agentic LLM Workflow 可以接入更广泛的工具生态，实现与数据库、API、文件系统等外部资源的深度集成。\n\n适用人群与场景\n\n该项目特别适合：\n\n- 隐私敏感开发者：代码不能上传云端，需要在本地处理\n- 企业内网环境：无法访问外部 AI 服务\n- 定制化需求：需要精细控制 Agent 行为和权限\n- 学习研究：理解 Agent 架构和工具调用机制\n- 自动化脚本：CI/CD 流程中的代码分析和处理\n\n局限性与注意事项\n\n- 当前未指定开源许可证，使用时需注意法律风险\n- 依赖外部 API（如 Serper）进行网络搜索，需要单独配置密钥\n- 本地模型性能受硬件限制，复杂任务可能需要较长时间\n- 工具调用准确性取决于模型能力，建议人工审核重要修改\n\n总结与展望\n\nAgentic LLM Workflow 代表了本地 AI 助手的发展方向：在保持数据隐私的同时，赋予模型完整的工具使用能力。其模块化架构、丰富的工具集和灵活的权限配置，使其成为开发者探索 AI Agent 应用的实用工具。\n\n随着本地大模型能力的持续提升和 MCP 生态的成熟，这类本地优先的 Agent 工具将在隐私敏感场景和企业内网环境中发挥越来越重要的作用。