Agent Zero Tiny Local 配置文件深度解析：为小型本地模型定制的行动优先提示词契约-平芜编程栈

Agent Zero Tiny Local 配置文件深度解析：为小型本地模型定制的行动优先提示词契约

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

导读

Agent Zero 框架内置了名为Tiny Local的 Agent Profile，专门用于驱动 Ollama、LM Studio、Qwen 等小型本地聊天模型。由于参数量小、指令遵循能力有限，这类模型在默认 Agent 配置下容易"只说不做"——反复输出解释、状态承诺或可见推理文本，而不是真正调用工具。Tiny Local 通过一套纯提示词（prompt-only）的极简 JSON 工具调用契约，把"行动优先"（action-first）行为固化到系统提示词层面，同时与框架核心执行逻辑完全隔离。读完本文，你将掌握 Tiny Local 配置的完整文件结构、每个提示词文件的所有权边界、其本地契约的设计取舍，以及如何通过测试与命令验证该配置的正确性。

一、Tiny Local 配置的定位与设计目标

Tiny Local 是 Agent Zero 中随仓库分发的 Agent Profile 之一。其元数据定义在 agent.yaml 中：

title: Tiny Local description: Action-first profile for small local models that need a minimal tool-call contract. context: Use this agent when running small local chat models through Ollama, LM Studio, or similar providers and the model tends to explain actions instead of calling tools.

从 AGENTS.md 中的 Purpose 声明可以看出，它的定位有两点核心：

**拥有（Own）**随仓库捆绑的 Tiny Local 配置，服务对象是小型/本地聊天模型；
将本地模型的行为约束完全保持在提示词层面，与框架核心执行逻辑隔离（"Keep local-model behavior prompt-only and isolated from core framework execution"）。

这意味着 Tiny Local 不是通过修改 Python 执行代码来"修补"本地模型，而是把全部纠偏手段收敛在提示词文本中。这种设计让框架核心保持单一、可维护，同时让每个 Profile 可以独立演进其行为契约。

二、文件结构与所有权边界

Tiny Local 的配置由 1 个元数据文件、1 个契约文件组和 7 个提示词文件组成。其所有权划分在 AGENTS.md 的 Ownership 一节中有严格声明：

文件	所有权职责
agent.yaml	配置元数据，负责 Profile 的发现（discovery）与切换（profile switching）
prompts/agent.system.main.communication.md	本地模型的通信契约（communication contract）
prompts/agent.system.main.solving.md	本地模型的问题求解契约，并压制继承自默认 Profile 的可见推理（visible reasoning）要求
prompts/fw.msg_repeat.md	当框架拒绝重复的助手消息时，Tiny Local 专属的恢复指令
prompts/agent.system.tools.md	工具列表包装器，以及工具列表之后的最终输出形态提醒
prompts/agent.system.tool.*.md 等	Tiny Local 专属的工具示例，规避继承示例中携带的推理字段与重复写入行为

这种"一文件一职责"的划分与测试test_tiny_local_profile_is_discoverable相互印证：测试通过 helpers/subagents.py 中的get_all_agents_list()扫描所有 Agent 根目录，断言profiles["tiny-local"] == "Tiny Local"（见 tests/test_default_prompt_budget.py）。从源码结构看，Profile 的发现机制会按usr/projects/、usr/agents、plugins/、默认目录的优先级合并同名 Profile，因此 Tiny Local 也可以被用户或项目级配置覆盖。

三、本地契约（Local Contracts）详解

这是 AGENTS.md 中最核心的技术约束，共 6 条，逐条展开如下。

3.1 保留 Agent Zero 标准工具调用形态：`tool_name`+`tool_args`

Tiny Local 不发明新的工具协议，而是严格继承框架的 JSON 工具调用形态。在 prompts/agent.system.main.communication.md 中明确要求：

Your visible assistant message must be exactly one valid JSON object. Use exactly these top-level fields:"tool_name"and"tool_args".

即每次助手可见消息必须恰好是一个合法 JSON 对象，且只能包含这两个顶层字段。这一约束也同步写入了 prompts/agent.system.tools.md：

Every tool request must be exactly one JSON object with only these top-level fields: - `tool_name` - `tool_args`

3.2 不引入任何运行时修补（runtime patching）

AGENTS.md 明确禁止在此配置中添加四类运行时行为：

parser repair（解析器修复）；
duplicate suppression runtime（重复消息抑制运行时）；
model transport（模型传输层）；
text-editor runtime behavior（文本编辑器运行时行为）。

换言之，重复消息的处理、JSON 容错等能力一律不允许下沉到 Python 运行时，只能通过 Profile 提示词收紧。这保证了核心执行路径不被本地模型兼容性"污染"，也让测试可以纯文本断言 Profile 行为。

3.3 重复消息处理只通过 Profile 提示词收紧

当模型重复发送同一条 JSON 工具请求时，框架会注入 prompts/fw.msg_repeat.md 的恢复指令。其核心要求是：必须做出不同的动作，而不是原样重发。指令给出了 6 个可执行的替代方向：

工作未完成 → 为下一步调用真实工具；
之前的 JSON 用了response但仍有工作 → 替换为下一个真实工具调用；
文件写入/补丁已成功 → 读取该文件或用观察到的结果作答；
命令已运行 → 检查其输出或运行不同的下一步命令；
用户只说proceed/continue→ 用下一个真实工具调用继续；
无不同动作可行 → 用response简短报告阻塞原因。

通信契约中同样强调："If the framework warns that your prior message was malformed, repeated, or reasoning-only, output a corrected JSON tool request immediately without explaining the warning."（收到格式错误/重复/纯推理警告时，立即输出修正后的 JSON 工具请求，不要解释警告。）

3.4 提示词保持短小，适配小模型

"Keep prompt text short enough for small local models to follow" 是 Tiny Local 的硬性约束。小参数模型的上下文窗口与指令遵循能力有限，因此 Tiny Local 的各提示词文件刻意精简——例如code_exe工具说明只有约 20 行，response工具说明不足 15 行，fw.msg_repeat.md也压缩到 11 行。相比默认 Profile 的庞大提示词表面，Tiny Local 的目标是"足够小，模型能逐字遵守"。

3.5 续接词（proceed/continue）＝执行指令，而非状态回复

这是行动优先配置中最反直觉、也最关键的一条契约。AGENTS.md 规定：

Treat continuation requests such asproceedorcontinueas commands to execute the next unfinished step, not as prompts for another status response.

通信契约中给出了触发词清单："proceed"、"continue"、"go ahead"、"do it"、"excellent proceed" 等。一旦模型已声明下一步但尚未完成，用户说出这些词时，模型必须立即调用下一个合适的工具，而不是回复"我将开始…""我会继续…"这类承诺性文本。求解契约 prompts/agent.system.main.solving.md 用更严格的措辞重申：

Continuation words such as "proceed", "continue", "go ahead", "do it", and "excellent proceed" mean execute the next unfinished step. Do not respond by saying you will begin, continue, start, proceed, or investigate. Use a real tool call unless the task is already complete or blocked.

3.6 禁止用户专属信息

AGENTS.md 要求配置内不得包含用户特定的提供商名称、API 密钥、本地路径或密钥（secrets）。这是可移植性的底线——Tiny Local 提示词可以被任何用户、任何本地模型直接复用，而不会泄露环境信息。

四、行动优先的提示词体系：从通信到求解到工具

4.1 通信契约：一条"只说 JSON"的硬约束

prompts/agent.system.main.communication.md 是整个配置的入口，定义了模型与框架之间唯一的交互协议：

直接以用户名义行动（"Act on the user's behalf"），不要解释用户如何自己操作；
可见消息必须是一个合法 JSON 对象；
禁止 markdown 围栏（fences）、JSON 前后的散文、隐藏推理、分析、思考或标题；
只能选择系统提示词中列出的工具，禁止发明read、write、terminal、multi等泛化名称；
面向用户的最终答复统一走response工具，且仅在"工作完成、受阻、或用户仅确认已完成工作"时使用。

它给出的最终答复形态示例为：

{"tool_name":"response","tool_args":{"text":"Answer briefly."}}

同时，该文件末尾通过{{ include "agent.system.main.communication_additions.md" }}引入了全局通信补充说明（见 prompts/agent.system.main.communication_additions.md），其中定义了[PROTOCOL]/[EXTRAS]消息标记、工具名必须逐字复制（含behaviour_adjustment这类拼写）以及§§include(abs_path)替换机制等通用协议。

4.2 求解契约：压制继承的可见推理要求

prompts/agent.system.main.solving.md 承担双重职责：一是定义行动优先的问题求解流程，二是显式压制从默认 Profile 继承下来的thoughts（思考）、headline（标题）、分析、计划等可见推理字段。测试对此有精确断言："explain each step in thoughts" not in solving_prompt。

该文件规定的工作流是：

简单问题 → 直接用response工具回答；
需要 shell、文件、浏览器等能力 → 立即选择列表中的合适工具；
每轮保持一个工具调用，除非parallel工具确实有用；
先检查输出再决定下一个调用；
绝不从超时输出或仍在运行的命令推断成功；
工具结果成功后，不重复相同的工具调用；
收到重复消息警告后，不重复相同的状态回复或工具请求，而是选择下一个不同的可执行动作或报告阻塞；
完成时用response给出简短结果。

4.3 工具包装器与 Tiny Local 输出规则

prompts/agent.system.tools.md 在{{tools}}占位符位置注入实际工具列表，并在末尾追加 "Tiny Local Output Rule"：

Some inherited tool examples may showthoughtsorheadline. Ignore that shape for this profile. Do not includethoughts,headline, analysis, markdown fences, or prose outside the JSON object.

这条规则是"继承抑制"机制的关键：默认 Profile 的工具示例往往带thoughts/headline字段，Tiny Local 明确宣布忽略这些继承形态。这也是测试test_tiny_local_profile_prompt_is_action_first_json_contract中断言"headline" not in code_prompt等三条的依据。

4.4 三个典型工具的 Tiny Local 专属示例

配置文件提供了三个工具的本地化示例，均不带推理字段：

code_execution_tool（agent.system.tool.code_exe.md）：运行终端、Python 或 Node.js 命令。参数包括runtime（terminal/python/nodejs/output）、code、session（默认0）、reset（true/false）。其规则强调：用runtime=output轮询运行中的任务；会话卡死时以相同session+reset=true重调；统计文件数优先find而非ls（以处理隐藏文件与类型过滤）。

{"tool_name":"code_execution_tool","tool_args":{"runtime":"terminal","session":0,"reset":false,"code":"ls -1 /tmp | wc -l"}}

response（agent.system.tool.response.md）：仅用于任务完成、受阻或无需工具时。明确禁止在存在未完成下一步的情况下用它回应proceed/continue类请求。

{"tool_name":"response","tool_args":{"text":"There are 24 files in /tmp."}}

text_editor（agent.system.tool.text_editor.md）：读写或修补 Markdown 与纯文本文件。action支持read/write/patch；open_in_canvas仅在用户明确要求打开 Canvas/Editor 时置true；写入或修补成功后不要重复同一调用。示例使用了/a0/usr/workdir/TODO.md这一典型 workdir 路径：

{"tool_name":"text_editor","tool_args":{"action":"write","path":"/a0/usr/workdir/TODO.md","content":"# TODO\n- [ ] First item\n","open_in_canvas":true}}

五、验证方式：渲染与回归测试

AGENTS.md 的 Verification 一节给出了两条可执行的验证路径：

渲染系统提示词：在修改通信提示词之后，重新渲染tiny-local的完整系统提示词，人工核对最终文本形态；
运行回归测试：执行pytest tests/test_default_prompt_budget.py。

该测试文件是 Tiny Local 行为契约的机器可读版本，核心断言包括：

test_tiny_local_profile_prompt_is_action_first_json_contract：逐条断言通信契约中的关键语句（如 "You are Agent Zero. Act on the user's behalf."、'Use exactly these top-level fields:"tool_name"and"tool_args".'）、求解契约中的续接词规则、重复消息恢复指令，以及所有工具示例中不含"headline"；
test_tiny_local_profile_is_discoverable：断言 Profile 可通过get_all_agents_list()发现，且 label 为 "Tiny Local"；
test_rendered_profiles_strip_json_fences：以tiny-local等 5 个 Profile 为参数，断言渲染后的系统提示词中不含~~~json与```json围栏（渲染阶段会通过files.remove_code_fences移除 JSON 围栏，见 helpers/files.py）；
test_default_agent0_prompt_budget_and_guardrails：验证默认 Profile 提示词预算（约 10000 token 以内），间接保障各 Profile 提示词膨胀可控。

测试还通过_build_system_text(profile, rendered=True)走AgentContext+prepare_prompt的完整渲染管线（见 tests/test_default_prompt_budget.py），意味着这些断言验证的是"模板经过{{include}}展开、{{tools}}注入后的真实系统提示词"，而非原始模板文本。

六、维护与扩展指南

AGENTS.md 的 Work Guidance 明确了后续维护该 Profile 时应遵循的两条原则：

提示词优先，少建文件：收紧行为时优先调整现有提示词的措辞，而不是新建文件；唯一例外是"替换继承的工具示例以适配本地模型"（例如为某个工具提供 Tiny Local 专属的无推理示例版本）；
保持通用性：配置必须持续适用于 Ollama、LM Studio、Qwen 及其他同类本地模型，不要引入特定提供商的专有行为。

结合 Ownership 一节还可以看出，每个提示词文件的所有者是明确的：通信契约归agent.system.main.communication.md，求解契约归agent.system.main.solving.md，重复消息恢复归fw.msg_repeat.md，工具包装与输出形态归agent.system.tools.md与agent.system.tool.*.md。修改某一类行为时，应当只在对应文件内改动，保持所有权边界清晰。

七、总结

Tiny Local 是 Agent Zero 面向小型本地模型场景的一套"最小可行行动契约"：它以tool_name+tool_args的单一 JSON 形态统一了工具调用协议，通过"续接词即执行指令"消灭了状态式空回复，通过显式压制继承推理字段解决了小模型提示词预算与格式漂移问题，并通过"纯提示词、零运行时修补"的隔离原则保证了框架核心的稳定性。其所有权划分、本地契约、验证测试构成了一个完整、可回归、可移植的 Agent Profile 工程范本——如果你正在用 Ollama 或 LM Studio 驱动 Agent Zero，并遇到"模型总在解释而不动手"的问题，Tiny Local 就是开箱即用的答案。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Agent Zero Tiny Local 配置文件深度解析：为小型本地模型定制的行动优先提示词契约