OpenJarvis Code Assistant 实战指南：用 Orchestrator Agent 在本机完成写代码、调试与重构-开发者社区

【免费下载链接】OpenJarvis

Personal AI, On Personal Devices

项目地址：https://gitcode.com/gh_mirrors/op/OpenJarvis

本文是一份基于 OpenJarvis 官方 Code Assistant 预设的实战指南，讲解如何在本机构建一个具备代码执行、文件读写与 Shell 访问能力的编程助手 Agent。读完本文，你将掌握jarvis init --preset code-assistant的一键初始化流程、jarvis ask/jarvis chat的核心用法、config.toml中每一项关键配置的作用，以及 Orchestrator Agent 在底层如何通过"多轮工具调用循环"完成从需求到最终答案的完整推理链。

什么是 Code Assistant 预设

Code Assistant 是 OpenJarvis 内置的一类orchestrator（编排）型 Agent 预设：它同时具备代码执行、文件 I/O 和 Shell 访问能力，可以编写脚本、阅读并解释代码、运行测试、修复 Bug、执行 Shell 命令——且这一切都发生在你自己的机器上，数据不离开本地。

对应预设配置文件位于仓库的 configs/openjarvis/examples/code-assistant.toml。它与chat-simple.toml、deep-research.toml、full-system-access.toml等一同构成 OpenJarvis 的"开箱即用预设"体系，让用户在几分钟内按场景部署不同能力的 Agent。

其工作模式可以概括为：用户提出问题 → 编排 Agent 制定计划 → 按需调用工具（写文件、跑代码、执行 Shell）→ 观察结果 → 继续迭代 → 输出最终答案。

快速开始（约 5 分钟）

1. 安装并初始化

git clone https://github.com/open-jarvis/OpenJarvis.git cd OpenJarvis uv sync --extra dev jarvis init --preset code-assistant --force

上述命令会为 Code Assistant 生成一份预配置的~/.openjarvis/config.toml。--preset参数在 src/openjarvis/cli/init_cmd.py 中实现：当指定 preset 时，初始化命令会直接从examples目录找到对应的code-assistant.toml并复制为默认配置文件（如果目标配置已存在，会提示需要使用--force确认覆盖）。也就是说，仓库中的示例文件就是你本地得到的真实配置，二者完全一致。

2. 通过 Ollama 启动本地 LLM

# 安装 Ollama: https://ollama.com ollama pull qwen3.5:9b

Code Assistant 预设默认的推理引擎是 Ollama（engine.default = "ollama"），默认模型为qwen3.5:9b。9B 参数量级的模型足以覆盖多数单文件任务，且能在消费级硬件上流畅运行。

3. 提出一个编程问题

jarvis ask "Write a Python script that reads a CSV file and prints the top 5 rows"

编排 Agent 会规划实现思路、编写代码，并在你批准后实际执行它。

CLI 命令速查

# 提出编程问题（该配置下默认使用 orchestrator agent） jarvis ask "Write a Python script that parses JSON from stdin" # 阅读并解释既有代码 jarvis ask "Read main.py and explain the architecture" # 修复 Bug jarvis ask "Find and fix the bug in test_utils.py" # 运行测试 jarvis ask "Run the test suite and summarize any failures" # 显式指定 Agent 与工具 jarvis ask --agent orchestrator --tools code_interpreter "Calculate the first 20 Fibonacci numbers" # 交互式聊天，适合迭代式编码 jarvis chat

jarvis ask：一次性提问，适合明确的单一任务。
jarvis chat：进入多轮交互模式，Agent 会在执行潜在破坏性命令前请求你的确认（详见下文"安全说明"）。
--agent与--tools：用于临时覆盖配置中的默认 agent 与工具集合。例如--agent sandboxed --tools code_interpreter可以把代码执行放到 Docker/Podman 容器中运行。

配置参考

预设生成的~/.openjarvis/config.toml内容如下（与仓库中的 configs/openjarvis/examples/code-assistant.toml 完全一致）：

[engine] default = "ollama" [intelligence] default_model = "qwen3.5:9b" # default_model = "qwen3.5:35b" # Better for complex code tasks [agent] default_agent = "orchestrator" # Multi-turn with tool selection max_turns = 10 [tools] enabled = ["code_interpreter", "file_read", "file_write", "shell_exec", "web_search", "think", "calculator"]

关键配置项

配置项	默认值	说明
`engine.default`	`ollama`	推理引擎。Code Assistant 预设默认使用本地 Ollama，无需云端 API Key。
`intelligence.default_model`	`qwen3.5:9b`	代码生成所用模型。复杂任务（重构、多文件修改）建议换成`qwen3.5:35b`。
`agent.default_agent`	`orchestrator`	多轮 Agent，迭代选择工具直至得出答案。
`agent.max_turns`	`10`	最大工具调用轮数。多步骤任务可适当调大。
`tools.enabled`	7 个工具	`code_interpreter`（执行 Python）、`file_read`、`file_write`、`shell_exec`（运行 Shell 命令）、`web_search`、`think`、`calculator`。

max_turns直接对应 OrchestratorAgent 的核心循环参数。在 src/openjarvis/agents/orchestrator.py 中，类级默认值_default_max_turns = 10与配置文件保持一致；当达到最大轮数仍未给出最终答案时，Agent 会返回"Maximum turns reached without a final answer"并附上已执行工具的结果与 token 消耗统计。

工具详解

工具	作用
`code_interpreter`	在沙箱化环境中执行 Python 代码并返回输出。
`file_read`	带路径校验地读取文件，Agent 可借此查看源码、配置与日志。
`file_write`	写入或修改文件，Agent 可创建脚本、修补代码、写配置文件。
`shell_exec`	运行 Shell 命令（如`git status`、`pytest`、`ls`）。
`web_search`	搜索网络，获取文档、Stack Overflow 答案等。
`think`	内部推理草稿板，用于规划多步骤解决方案。
`calculator`	计算数学表达式。

Orchestrator Agent 的工作原理

Code Assistant 的核心引擎是orchestrator类型 Agent。在 src/openjarvis/agents/orchestrator.py 中，它以装饰器@AgentRegistry.register("orchestrator")注册到 Agent 注册表，实现了一个经典的工具调用循环（tool-calling loop）：

将消息与工具定义一起发送给推理引擎；
若响应包含tool_calls，逐个执行工具并把结果追加回消息上下文，进入下一轮；
若响应不再包含tool_calls，则将内容作为最终答案返回；
轮数达到max_turns后强制终止。

它支持两种运行模式：

function_calling（默认）：使用 OpenAI 格式的工具定义，解析引擎返回的tool_calls，并在收到多个工具调用时默认并行执行（parallel_tools = True）。
structured：使用THOUGHT: / TOOL: / INPUT: / FINAL_ANSWER:的文本协议（类似 ReAct），这一格式与 SFT/GRPO 训练流水线保持一致，使 Orchestrator 成为一种可训练的 Agent 类型。

此外，OrchestratorAgent 还内置了两道防护机制：

governance 钩子（before_tool_call）：每次工具调用前可注入策略检查，未通过审批的调用会被拒绝并返回[Governance]说明，且校验失败时会"失败关闭"（fail closed），不允许未授权调用执行；
loop guard（循环防护）：用于压缩过长的上下文，并在调用前后检查是否存在无效循环，被判定为阻塞的调用会返回Loop guard: <reason>。

工具底层实现与安全边界

code_interpreter：AST 校验 + 子进程资源限制

Code Assistant 最常用的工具code_interpreter在 src/openjarvis/tools/code_interpreter.py 中实现。它并非简单地执行eval，而是先对用户代码做AST（抽象语法树）校验，将eval、exec、compile、__import__、open、getattr等危险调用列入拒绝名单，再在隔离的子进程中以python -I -B -S参数启动（隔离用户环境、不写字节码缓存、不自动导入 site-packages），并在 POSIX 系统上通过preexec_fn施加 CPU、地址空间等资源限制。其默认执行超时为30 秒，超时即终止，因此长时间运行的脚本会被自动切断。

shell_exec：带超时上限的命令执行

shell_exec在 src/openjarvis/tools/shell_exec.py 中实现，默认超时 60 秒，且存在硬性最大超时上限（_MAX_TIMEOUT），任何请求都会被钳制在该上限内；命令执行结果会附带实际使用的timeout_used字段，超时后返回 "Command timed out after N seconds."。

注意：shell_exec以你启动jarvis时的当前用户上下文运行，工作目录默认是启动命令所在的目录。如果要在别的目录执行，需要在提示词里写cd /path && command，或直接从项目目录启动jarvis。

沙箱隔离：sandboxed agent

当需要更强隔离时，可用jarvis ask --agent sandboxed --tools code_interpreter "..."。沙箱化 Agent 会把代码执行放入 Docker/Podman 容器中运行，相关实现位于 src/openjarvis/sandbox/runner.py 及 src/openjarvis/tools/code_interpreter_docker.py，适合处理不可信代码或需要隔离文件系统的场景。

典型任务示例

# 编写新脚本 jarvis ask "Write a Python script that converts YAML to JSON" # 解释既有代码 jarvis ask "Read src/openjarvis/core/events.py and explain the EventBus pattern" # 调试失败的测试 jarvis ask "Run pytest tests/test_memory.py -v and fix any failures" # 重构代码 jarvis ask "Read utils.py and refactor the parse_config function to use dataclasses" # 生成测试 jarvis ask "Read src/openjarvis/tools/calculator.py and write unit tests for it" # Shell 类任务 jarvis ask "Find all Python files larger than 100KB in this repo"

安全说明

shell_exec和code_interpreter会在你的机器上执行真实命令，使用前务必了解以下边界：

shell_exec以当前用户身份运行命令，可以读、写、删除文件。不要在包含敏感数据的目录上不加审查地运行 Agent，应检查其每次工具调用。
code_interpreter会执行 Python 代码，能够访问你的 Python 环境与已安装的第三方包（尽管默认以-S模式隔离启动，仍应视为可执行环境）。
在交互模式（jarvis chat）下，Agent 在执行为潜在破坏性命令前会请求你的确认。
需要更强隔离时，使用沙箱化 Agent：jarvis ask --agent sandboxed --tools code_interpreter "..."，它将在 Docker/Podman 容器内运行。

故障排查

报错 "Tool not found: code_interpreter"确认config.toml的tools.enabled列表中包含code_interpreter。预设默认已启用，若你手动改过配置请核对。

Agent 循环无进展任务复杂时可调大max_turns，或换用更大的模型（如qwen3.5:35b）。9B 模型能应对大多数单文件任务，多文件重构通常需要更多参数量的模型。

Shell 命令执行失败shell_exec相对于启动jarvis的目录运行命令。需要在其他目录执行时，在提示词里写cd /path && command，或直接从项目目录启动jarvis。

Web 搜索不工作需以uv sync --extra tools-search安装搜索相关依赖，并设置TAVILY_API_KEY环境变量。

代码执行卡住code_interpreter有默认超时（30 秒），长时间运行的脚本会被终止。建议把大任务拆成小步骤。

小结

Code Assistant 是 OpenJarvis 开箱即用的本地编程助手方案：一条jarvis init --preset code-assistant --force命令即可获得编排式 Agent、7 个开箱工具和本地 Ollama 推理的完整组合。它的价值不仅在于命令便利，更在于 Orchestrator 的"计划—执行—观察—迭代"循环、内置的 governance 与 loop guard 防护，以及code_interpreter的 AST 校验与资源限制等源码级安全设计。更多编排 Agent 的机制细节可参考 docs/architecture/agents.md 与 docs/architecture/engine.md。