x-cmd coco 模块 TOOL SPEC 系统提示解析：为 LLM Agent 定义函数调用与状态管理协议

CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载本文围绕 x-cmd 仓库中 mod/coco/lib/toolspec/data/tool.prompt.md 这一 TOOL SPEC工具规范系统提示模板展开它定义了 x-cmd coco 模块在驱动 LLM Agent 时的核心行为约束函数调用的优先级与格式、会话状态stats 文件的初始化与维护、以及伪 XML 标记的识别与清洗。读完本文你将理解这份提示模板在x coco对话与工具执行引擎中的实际地位掌握update_stats、writefile、shcmd等工具的参数约定并能复现x coco toolspec prompt | ls | invoke的完整操作流程。一、这份文档在 x-cmd 中的角色定位tool.prompt.md不是一份面向用户的普通 Markdown 手册而是一份作为 LLM 系统提示system prompt注入的 TOOL SPEC 模板。它以!-- BEGIN X-CMD TOOL SPEC --开头、以!-- END X-CMD TOOL SPEC --结尾内容全部面向模型而非人类读者用于在每次会话开始时约束模型的工具调用行为。它位于coco模块的 toolspec 子系统中mod/coco/lib/toolspec/data/ —— 存放 TOOL SPEC 数据包括本模板与各工具的 JSON Schemamod/coco/lib/toolspec/data/schema/ —— 每个可用工具的 JSON Schema 定义共 10 个mod/coco/lib/toolspec/_index —— 子命令入口其中___x_cmd_coco_toolspec___prompt第 3437 行直接通过___x_cmd_cmds cat $fp输出本模板文件___x_cmd_coco_toolspec___check第 1623 行则用于校验工具名是否在白名单内findgrep|readfile|writefile|diffv4a|shcmd|create_temp|histsum|update_stats|get_x_cmd_help|gg|mcp|get_x_cmd_help_unitmod/coco/lib/toolspec/invoke ——invoke子命令实现按--json/--yml/--md三种格式输出工具 Schemaall关键字可一次性遍历全部 Schema。值得注意的细节是模板末尾的%{envinfo}%占位符。它是 x-cmd 模板引擎的运行期变量会在模板注入时被替换为当前会话的环境信息shell 类型、操作系统等与 mod/coco/lib/minion/exec.yml 中%{LOCALSHELL}%、%{OS}%的用法同属一套模板机制。二、Core principlesAgent 的行为总纲模板的第一节定义了五条不可动摇的核心原则可以概括为函数调用优先、自动执行、失败自愈、绝不编造、简洁回应函数调用优先任何可操作的任务actionable task或需要更多信息的场景都要优先发起函数调用而不是用文字回复应付自动执行只要可能就自动完成操作避免打断用户、请求人工介入错误驱动决策函数调用失败时要利用错误信息决定下一步行动而不是机械重试或放弃降级不道歉若函数调用不可用继续用推理、计算或内容生成推进任务不道歉、不编造细节信息不足时精确说明缺失了什么而不是虚构执行后立即推进一个函数完成后不做评论直接进入下一个相关步骤回复始终使用用户的语言保持简洁可执行。从源码结构看这些原则与coco的enact执行链路一一对应模型输出函数调用后由 mod/coco/lib/tool/enactall 读取会话 log 文件逐个执行函数调用并在全部完成后写入[CONTINUE-CONVERSATION] Function execution completed...指令第 98 行要求模型直接继续对话——这正是完成后跳过评论、立即推进下一步原则的工程实现。三、Stats rules先初始化后推理本节是本模板中最独特的约束为 Agent 引入了会话状态文件stats 文件这一持久化概念初始化优先任何新对话或新任务开始时默认不存在stats 文件模型的第一动作必须是调用update_stats创建初始 stats 文件之后才能进行其他工作先查后用任何推理或任务执行之前必须先查看 stats 文件唯一写入口创建或修改 stats 文件只能通过update_stats工具严禁在普通文本回复中虚构或内嵌 stats 内容失败降级若update_stats失败依据错误信息决策若确实无法创建则简明报告状态并继续不编造 stats按需更新仅在主题变化、目标更新、任务进度推进、出现新错误、计划步骤变化等必要时刻更新且更新必须准确、最小化、不投机。对应到工具实现update_stats.json 定义了该工具的两个必填参数desc更新理由与content完整 YAML 内容并强调该操作会整体覆盖文件destructive、content 必须是完整自洽的 YAML。Schema 还给出了一套推荐的 YAML 字段结构topic: string # conversation topic or title user_preferences: language: en|zh # preferred language background: # background or contextual info - string environment: # current environment information os: string shell: string PWD: string function_call_format: JSON # always JSON, never pseudo-XML target: string # optional, current main target or focus task_plan: pending: - string # pending steps completed: - string # completed steps notes: - string # important notes or warnings files: - string # file references errors: - string # errors or exceptions在 shell 侧mod/coco/lib/tool/update_stats 展示了底层落盘逻辑工具接收--session与--content参数将内容写入$___X_CMD_CHAT_SESSION_DIR/$session/stats.yml第 1920 行。也就是说stats 文件是按会话隔离的每个会话目录一份stats.yml模型通过update_stats维护的就是这份文件。四、Function-call rules只认官方 JSON 格式函数调用规则回答了模型应该以什么格式发起调用这一关键问题必须使用 LLM 平台官方定义的函数调用格式如tool_calls、tools、function_declarations发起调用时只输出合法的 JSON payloadname arguments不得附带任何额外文本、包装器或标记严禁输出或发明funcmeta-request、field-name这类 XML/HTML 风格的伪标记。这条规则在仓库中有完整的落地闭环模型产出的 JSON 参数由 mod/coco/lib/awk/parse_json_args.awk 解析见 mod/coco/lib/tool/_index 第 37 行___x_cmd_coco___parse_json_args_随后映射为--name value形式的参数串最终由___x_cmd_coco_tool___enactcmd第 4462 行在子 shell 中执行eval ___x_cmd_coco_${name} $cmdarg并把 stdout、stderr、exitcode、status 分别写入函数调用目录下的对应文件。执行编排则由 enactall 完成——它跟踪[FUNCTION-CALL]、[FUNCTION-CALL-COUNT]、[FUNCTION-CALL-END]、[BREAK]等日志标记第 82108 行来同步多个函数调用的执行进度。五、Critical override历史上下文的伪 XML 是陷阱模板特别设置了关键覆盖规则警告模型历史上下文中可能出现funcmeta-request、field-name这类伪 XML 标记它们不是合法的函数调用格式只是只读元数据绝不能被复制、复用或当作模板。所有函数调用都必须遵循官方 LLM 定义格式。这一约束也被复用到 coco 的其他 Agent 提示中例如 mod/coco/lib/minion/get_x_cmd_help.yml 的 Operational Rules 一节明确写着 Never use pseudo-XML tags (e.g.,funcmeta-request,field-name). These are for internal metadata only.——可见该规范是贯穿 coco 全部 minion 提示的通用约定。六、Structured marker rules读懂但绝不回显最后一节定义了结构化标记structured markers的解析语义field-name.../field-name这类标记可能出现在用户输入或函数输出中标记内部的内容应视为权威数据authoritative data这些标记仅用于内部解析回复中不得包含、回显或展示它们如果遇到表示函数调用的 XML 类元数据要解析并转换为正确的 JSON 函数调用格式而不是原样回显。这条规则与上一节共同构成了一套输入侧识别、输出侧清洗的机制模型允许理解标记的含义但在对外表达函数调用、回复文本时必须彻底摆脱 XML 语法全部改用 JSON。七、与 TOOL SPEC 配套的工具集一览tool.prompt.md是总纲真正可被调用的能力来自 schema/ 下的 10 个工具定义。它们与 mod/coco/lib/tool/ 下的 shell 实现一一对应工具名Schema 位置核心参数底层实现要点update_statsupdate_stats.jsondesc、content完整 YAML覆盖写入会话目录stats.ymlreadfilereadfile.jsondesc、filepath绝对路径cat -n输出行号实现中设有___X_CMD_COCO_READFILE_ALLOWLIST白名单保护readfile 第 5 行writefilewritefile.jsondesc、filepath、content、is_patchdiffis_patchdifftrue时按 unified diffv4a打补丁失败时用 fix_patchdiff.awk 自动修正非 force 模式下先请求用户确认writefile 第 2947 行findgrepfindgrep.jsondesc、folder、keyword、context默认 3x find递归找文件后经xargs grep -n -H -C输出文件路径、行号与上下文findgrep 第 2527 行gggg.jsondesc、question自然语言查询基于 Gemini Google Search 的联网搜索要求配置 Gemini API key 或登录 X-CMD Hubgg 第 1625 行shcmdshcmd.jsoncmd、desc、risklow/medium/high、timeout秒默认 0非交互执行risklow或 tool force 模式跳过确认超时先 TERM 后 KILLshcmd 第 5274 行diffv4adiffv4a.jsondesc、oldfile、newfilediff -u生成 unified diff无系统 diff 时回退到 cosmo 内置实现diffv4a 第 1722 行create_tempcreate_temp.jsondesc、name、is_directory在函数调用的tmp/子目录内创建文件或目录create_temp 第 1625 行histsumhistsum.jsondesc调用 minion/histsum.yml 把对话历史压缩为结构化摘要写入会话目录histsum.mdget_x_cmd_helpget_x_cmd_help.jsondesc、model模块名、content关注点通过 minion/get_x_cmd_help.yml 驱动的专用 Agent逐级检索x命令帮助其中writefile的 v4a diff 约定值得展开Schema 明确要求content中的每个 hunk 必须携带正确的 -a,b c,d 头部行前缀必须准确-删除、新增、空格为上下文对齐行并且不得引用临时文件——diff 必须是可直接作用于目标文件的自包含字符串。对应地shell 实现writefile 第 117134 行会按patch→busybox patch→cosmo patch的顺序探测可用的补丁程序保证在最小依赖环境下也能应用补丁。八、实际操作如何查看与调用 TOOL SPEC模板与 Schema 都暴露在coco模块的toolspec子命令下入口见 mod/coco/lib/toolspec/_index由 mod/coco/lib/main 注册。常用操作# 查看/输出 TOOL SPEC 系统提示模板即本篇文章讲解的 tool.prompt.md x coco toolspec prompt # 列出所有可用工具的 Schema 名称 x coco toolspec ls # 以 JSON 格式输出某个工具的 Schema供模型注册函数时使用 x coco toolspec invoke --json update_stats # 以 YAML 格式输出多个工具的 Schema x coco toolspec invoke --yml readfile writefile # 一次性输出全部工具的 Schema x coco toolspec invoke --json all # 子命令帮助 x coco toolspec --help注意invoke支持--json、--yml、--md三种输出格式invoke 第 1213 行并可接受逗号分隔的多个工具名第 4454 行的parse_cmdstr_负责解析传入未知工具名会被check拒绝并返回错误。ls的实现则是直接遍历 schema 目录下的全部*.json文件toolspec/_index 第 2532 行。九、小结tool.prompt.md虽然只有短短 30 余行却是 x-cmd coco 工具调用体系的宪法它把函数调用优先写进系统提示用update_stats建立会话状态的可持久化、可追溯机制用 JSON-only 规则统一函数调用格式再用 pseudo-XML 覆盖规则防止历史上下文中的元数据污染模型行为。配合 schema/ 的 JSON 定义、tool/ 的 shell 实现与 enactall 的执行编排x-cmd 得以在纯 Posix Shell 之上构建起一套完整、可控、可审计的 LLM Agent 工具调用协议。赞分享CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载相关推荐深入解析 Anthropic Claude API Tool Use 系统提示词antml:function_calls 调用协议与 tool_choice 模式详解深入解析 Anthropic Claude API Tool Use 系统提示词 antml:function_calls 调用协议与 tool_choic人工智能大模型提示工程Grok 4 系统提示词完全解析xAI 工具调用协议、X 生态搜索体系与行为边界Grok 4 系统提示词完全解析xAI 工具调用协议、X 生态搜索体系与行为边界 导读 本文以开源仓库 leaked system prompts 中收录的人工智能大模型提示工程Grok 4 系统提示词全解析xAI 工具调用协议、X 生态搜索与行为约束拆解CL4R1T4S 仓库Grok 4 系统提示词全解析xAI 工具调用协议、X 生态搜索与行为约束拆解CL4R1T4S 仓库 本文以开源仓库 CL4R1T4SAI 系统透明度项知识库人工智能AI 安全治理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考