ARTICLE · INTELLIGENCE

战地情报 · 详情页

来自尧图项目组的一线实战观察与深度解析

ZCode 交互式编程代理系统提示词架构解析:身份、协作协议与工具契约的完整工程范式

ZCode 交互式编程代理系统提示词架构解析:身份、协作协议与工具契约的完整工程范式 知识库人工智能AI 安全治理【免费下载链接】CL4R1T4SLEAKED SYSTEM PROMPTS FOR CHATGPT, CLAUDE, GEMINI, GROK, PERPLEXITY, CURSOR, LOVABLE, REPLIT, AND MORE! - AI SYSTEMS TRANSPARENCY FOR ALL! 项目地址https://gitcode.com/gh_mirrors/cl/CL4R1T4S点击查看免费下载本文以 ZAI/ZCode/Prompts.md 为核心蓝本系统拆解 ZCode 交互式编程代理interactive coding agent系统提示词的完整设计从角色身份与安全边界到 Harness 运行契约、用户沟通协议、会话与上下文管理、持久化记忆、技能生态与工具注册表。结合 ZAI/ZCode/Skills.md 与 ZAI/ZCode/Tools.json 中的真实定义读者可以掌握一个生产级编程 Agent 的系统提示词是如何分层组织、如何约束工具行为、如何管理长期记忆并可直接将这些模式迁移到自建 Agent 的提示词工程中。一、ZCode 是谁身份层与安全边界一份 Agent 系统提示词的起点永远是我是谁、能做什么、不能做什么。ZCode 提示词的第一行就给出了朴素而明确的身份声明You are ZCode, an interactive coding agent that helps users with software engineering tasks.见 Prompts.md身份定位为交互式编程代理服务范围是软件工程任务——这决定了其后所有工具、技能和协作协议的编排方向。紧随身份之后的是安全策略Prompts.md这是全文中唯一以IMPORTANT强调的规则段体现了安全边界在系统提示词中的最高优先级应协助授权安全测试、防御性安全、CTF 挑战、教育场景应拒绝破坏性技术、DoS 攻击、大规模无差别攻击mass targeting、供应链投毒、用于恶意目的的检测规避双重用途安全工具C2 框架、凭据测试、漏洞利用开发仅在存在明确授权上下文时才能使用包括渗透测试项目、CTF 竞赛、安全研究、防御性用例。这一段落的价值在于它没有一刀切地禁止安全类工作而是建立了意图 授权上下文的判定框架让 Agent 在面对安全工具时既能提供价值又不会越界——这是当前多数 Agent 系统提示词在安全约束上的通行做法也是值得借鉴的边界设计范式。二、Harness终端、权限与工具调用的运行契约# Harness段Prompts.md定义了 Agent 与宿主运行时之间的技术契约共包含六条关键规则终端 Markdown 渲染工具调用之外的文本输出将以 GitHub 风格 Markdown 在终端中展示给用户——这要求 Agent 的输出天然具备结构化能力。权限模式permission mode所有工具都在用户选择的权限模式下运行一次被拒绝的调用意味着用户拒绝该操作——正确应对是调整策略而不是原样重试a denied call means the user declined it — adjust, dont retry verbatim。这是对越被拒绝越要重试这一反模式的明确禁止。系统回合system turns系统可能在对话中途通过 system turn 发送更新、提醒或规则修改与函数返回结果不同这些消息由系统控制属于高优先级指令。Hooks 拦截钩子hooks可能拦截工具调用Agent 应将 hook 输出视为用户反馈。工具选择优先级当专用文件/搜索工具能胜任时优先于 shell 命令相互独立的工具调用可以在同一条回复中并行发起。代码引用规范以file_path:line_number格式引用代码且该引用是可点击的——这一约定直接支撑了文章与代码的双向可追溯性。这六条规则共同刻画了一个受控但高效的执行环境Agent 的每次工具调用都经过权限过滤失败后需自适应调整同时通过并行调用与点击式引用最大化效率与可追溯性。三、与用户的沟通协议面向刚离开的队友写作# Communicating with the user段Prompts.md是全文信息密度最高的部分之一它把 Agent 的写作风格从日志式提升为协作式核心原则一你的文本输出就是用户看到的一切。用户通常看不到 Agent 的思考过程和原始工具结果因此输出应当写给一位刚离开、需要快速跟上进度的队友而不是写给自己看的日志。这要求不使用对话中临时发明的代号与缩写。核心原则二首句给出结论Lead with the outcome。任务结束后的第一句话应回答发生了什么/发现了什么也就是用户问直接说结论时想要的东西支撑细节与推理放在其后。这与技术写作中结论先行的 TLDR 文化一脉相承。核心原则三可读性比简洁更重要。提示词明确警告如果用户需要重读或追问那么任何通过简洁节省的时间都已浪费。压缩输出的正确方式是选择性——删掉不影响读者下一步行动的内容而不是把句子压缩成碎片、缩写或箭头链。核心原则四匹配问题粒度。简单问题用散文直接回答不使用标题与分节表格仅用于简短可枚举的事实解释性内容放在正文而非表格单元格对专家读者更紧凑对新手读者更多解释。代码注释纪律Prompts.md同样值得注意只写代码本身无法表达的约束绝不写这段代码来自哪里、下一行做什么、我的改动为什么正确——后者是对评审者而非读者的独白在 PR 合并的那一刻就变成了噪音。确认与忠实报告对于难以逆转或面向外部的动作如向外部服务发送内容——它可能被缓存或索引除非已获得持久授权或明确指示否则先确认删除或覆盖前先查看目标如果实际情况与描述矛盾应如实指出而不是继续操作测试失败就如实报告失败与输出跳过某一步就明确说明——done and verified 与 hedging 之间的界限被严格划清。四、会话环境与上下文管理4.1 环境注入# Environment段Prompts.md在每次会话启动时注入运行环境的元数据占位符主工作目录WORKSPACE、是否为 git 仓库、平台PLATFORM、ShellSHELL、操作系统版本、以及驱动当前会话的模型名。文档中一处副本显示模型为builtin:zai-coding-plan/GLM-5.3——即模型通过内置插件方式注册而非硬编码在提示词正文中这保持了提示词的跨模型可移植性。4.2 上下文管理与自主行动原则# Context management段Prompts.md定义了长会话下的行为准则会话变长时上下文会被摘要压缩压缩摘要与剩余未压缩内容一起进入下一个上下文窗口Agent 无需提前收尾或中途交接掌握足够信息就行动不重新推导已确立的事实不重议用户已做的决定不叙述不会采纳的选项自主运行用户并非实时观看中途提问会阻塞工作。对于源于原始请求且可逆的动作直接执行只为破坏性动作或真正的范围变更而停止例外情形当用户在描述问题、提问或思考而非请求变更时交付物是评估结论——报告发现并停止不擅自应用修复收尾检查结束回合前检查最后一段如果它是计划、分析、问题或承诺我会…完成后告诉我就用工具调用完成它——包括出错后的重试与自行收集缺失信息只有在任务完成或被只有用户能提供的输入阻塞时才结束回合状态变更前的证据校验运行改变系统状态的命令重启、删除、配置修改之前先核对证据是否真正支持该动作——一个模式匹配到已知失败模式的信号可能另有原因。这套准则的实质是把何时动手、何时停下从模糊直觉变成可执行的判定规则显著减少 Agent 的无效往返。4.3 会话标题生成与 Web 搜索工具提示词还内置了两个特殊任务的子提示词Prompts.md会话标题生成——将用户消息意图压缩为 37 词、使用用户主要语言、保留专有名词与 API 名称、以合法 JSON 对象返回{title:...}以及 Web 搜索工具的使用提示。这展示了系统提示词对元任务meta-task的显式管理标题生成这类看似琐碎的动作也需要明确的规则约束其输出格式。五、持久化记忆系统Agent 的长期知识库# Memory段Prompts.md给出了一个完整可落地的文件化记忆实现这是全文中最具可迁移性的设计存储模型每个记忆 一个文件 一条事实带 frontmatter--- name: short-kebab-case-slug description: one-line summary — 用于召回时判断相关性 metadata: type: user | feedback | project | reference --- 事实内容feedback/project 类型需附加 **Why:** 与 **How to apply:** 行 并用 [[their-name]] 链接相关记忆四种记忆类型类型含义典型内容user用户画像角色、专业度、协作偏好feedback用户给出的工作方式指导纠正与确认必须包含 whyproject项目进行中的状态目标、约束、截止日期相对日期转为绝对日期reference外部资源指针指向仓库之外的信息位置索引机制每个记忆写入后在MEMORY.md中追加一行指针- Title — hook。MEMORY.md是每次会话都会载入上下文的索引因此必须保持单行精简超 200 行会被截断。**反模式清单What NOT to save**同样关键代码模式、git 历史、调试修复配方、CLAUDE.md 中已记录的内容、临时任务细节——这些可再推导的信息一律不保存。先用旧后更新、先验证后推荐记忆命名了某个函数或文件使用前必须 grep/Read 确认其仍存在记忆快照是冻结在时间里的涉及最近/当前状态应优先读 git log 或代码。这套设计的三点启发其一记忆与代码仓库解耦本地作用域、不入版本控制避免污染项目其二用描述 hook两级索引平衡召回精度与上下文开销其三对记忆的保质期有清醒认知防止 Agent 被过期记忆误导。六、技能Skills生态slash 命令与可加载能力6.1 调用机制# Session-specific guidance段Prompts.md规定用户输入/skill-name时通过 Skill 工具调用对应技能只能使用用户可调用技能列表中列出的技能不得猜测。这保证了技能调用的可枚举性——提示词正文不会去臆造一个不存在的技能名。6.2 官方技能清单Prompts.md 中列出的可用技能Prompts.md覆盖四大能力域能力域技能职责浏览器自动化browser-use:control-browser打开、导航、检查、点击、截图、验证页面状态GUI 黑盒测试browser-use:web-gui-tester模拟真实用户操作的前端交互测试方法论文档生产document-skills:docx/pdf/pptxDOCX/PDF/PPTX 的创建、编辑、分析技能创作与诊断skill-creator:skill-creator从零编写/迭代 SKILL.mdzcode-guide:diagnosing-*系列诊断 ZCode 客户端的命令、钩子、MCP、插件、技能、扩展资源配置问题6.3 关键技能要点来自 Skills.mdZAI/ZCode/Skills.md 收录了这些技能的完整加载内容其中三个技能的工程细节极具参考价值control-browser浏览器自动化以 Node REPL MCP 的js工具为驱动每次调用都运行在全新的 JavaScript 内核中变量、模块缓存不持久因此每次调用都必须重新执行 bootstrap——从ZCODE_PLUGIN_ROOT兼容回退CLAUDE_PLUGIN_ROOT解析插件根目录经pathToFileURL加载browser-client.mjs再调用setupBrowserRuntime。后端类型为iab应用内浏览器、extensionChrome 扩展、cdpCLI 托管的无头 Chromium通过agent.browsers.list()作为可用性事实来源。核心工作流是定位tab list→ 验证domSnapshot→ 精确操作getByRole/getByText 等惰性定位器→ 廉价观察并明确禁止用evaluate()探测选择器、禁止截图与快照双开浪费。web-gui-testerGUI 黑盒测试确立五大核心原则——纯 GUI 黑盒、忠实于真实页面、测试与修复分离、代码与视觉双重交叉验证、遵循浏览器工具自身规则。测试计划按 P0 主流程、P1 交互反馈、P2 输入边界、P3 布局样式的优先级组织观察环节强制代码验证 截图视觉验证二者缺一不可每个测试点无论通过与否都必须引用对应截图作为证据。docx / pdf文档生产docx 技能要求创建文档时必须从 7 个已验证的封面配方R1–R7中选择禁止自由发挥封面代码生成后必须运行postcheck.py并修复全部 ❌ 错误。pdf 技能则按任务权重分 Light/Standard 两级路由将报告ReportLab/创意Playwright/学术Tectonic三类生产流水线与html2poster.js、html2pdf-next.js等脚本对应起来并规定了最终 PDF 必须矢量输出、禁止截图转 PDF的硬性规则。这些技能内容的共同特征是把领域方法论写成可执行的规则清单何时用、何时禁止、如何验证而非泛泛的能力描述——这正是技能工程skill engineering区别于简单工具封装的关键。七、工具契约从 JSON Schema 到权限模型ZAI/ZCode/Tools.json 以结构化的 JSON 形式记录了当前会话的完整工具契约从中可以反推出系统提示词所依赖的工具面核心工作工具Read文件读取、Edit/Write精确字符串替换与文件覆写、Bash命令执行明确禁止交互式 flag、Agent子代理、Skill技能调用、WebFetch/WebSearch联网检索、TodoRead/TodoWrite任务跟踪。子代理体系Agent提供general-purpose全工具通用代理适合复杂多步任务与Explore只读搜索代理适合广度扫描两种类型规则明确——一旦委托了搜索父代理不应重复执行子代理的最终消息作为工具结果返回父代理需转述要点而非倾倒原文。决策与规划工具EnterPlanMode/ExitPlanMode计划模式先探索、再出计划、经用户批准后实施、AskUserQuestion仅在真正需要用户决策时使用且选项需附带Recommended推荐标记与 preview 预览能力。自动化与调度CronCreate/CronUpdate/CronDelete/CronList支持持久化的定时自动化任务调度表达式使用用户本地时区的 5 字段 cron 或相对延迟delayMinutes并强调相对时间绝不由 Agent 自行换算成绝对时钟时间——因为刚刚过去的 one-shot 时间会静默滚动一整年。权限模型Tools.json 中每个工具都带有permission权限声明、readOnly只读标志、destructive破坏性标志、concurrentSafe并发安全标志、sideEffectScope副作用范围none/session与resultBudget结果预算。例如Grep声明sideEffectScope: none、风险等级 low、无需审批RespondToCoordinator声明sideEffectScope: session。这一逐工具声明权限与副作用的元数据化做法让宿主可以在运行时统一执行审批策略是系统提示词与运行时安全模型衔接的关键接口。MCP 与兼容层mcp__node_repl__js系列工具专供浏览器自动化使用明确禁止用作通用 JS 运行时或文件系统操作Glob/Grep在当前宿主中以兼容别名形式存在对应本环境的list_files/search_in_filesTask则是 Claude Code 兼容别名映射到Agent工具。从工程视角看这份工具契约回答了三个问题有哪些能力可用工具清单、每个能力允许做什么权限与副作用声明、结果如何回流输出 Schema 与结果预算。三者共同构成 Agent 能力的可审计边界。八、对 Agent 系统提示词工程设计的启示把 ZCode 提示词作为一个整体样本可以提炼出六条可复用的设计原则分层组织职责单一身份与安全边界 → 运行契约Harness→ 沟通协议 → 会话/上下文 → 记忆 → 技能 → 工具每一层只解决一类问题便于维护与增量演进。安全边界前置且意图化安全段放在身份之后用授权上下文而非一刀切禁令来管理双重用途工具兼顾合规与能力。沟通协议显式化结论先行、面向协作者写作、可读性优先——把高质量的协作体验写成规则而不是依赖模型的悟性。记忆与代码解耦、索引与正文分离文件化记忆 MEMORY.md 单行索引既持久又省上下文并辅以先验证后推荐的防过期机制。技能与工具元数据化技能以 SKILL.md 文件携带领域方法论工具以 JSON Schema 携带权限与副作用声明使能力可枚举、可审计、可授权。自主与确认的平衡可逆动作直接执行、不可逆动作先确认、评估类问题只给结论——用规则而非每次提问来管理 Agent 的主动性。附仓库内相关资源ZAI/ZCode/Prompts.mdZCode 交互式编程代理完整系统提示词本文核心蓝本ZAI/ZCode/Skills.md浏览器自动化、GUI 测试、文档生产等技能的完整加载内容ZAI/ZCode/Tools.json当前会话工具契约的 JSON 定义含权限模型与输出 SchemaREADME.md仓库定位说明——面向 AI 系统透明度与可观测性的系统提示词公开集合。赞分享知识库人工智能AI 安全治理【免费下载链接】CL4R1T4SLEAKED SYSTEM PROMPTS FOR CHATGPT, CLAUDE, GEMINI, GROK, PERPLEXITY, CURSOR, LOVABLE, REPLIT, AND MORE! - AI SYSTEMS TRANSPARENCY FOR ALL! 项目地址https://gitcode.com/gh_mirrors/cl/CL4R1T4S点击查看免费下载相关推荐CL4R1T4S 仓库中的 Cline 系统提示词全解析AI 编程代理的工具调用协议与双模式工作流设计CL4R1T4S 仓库中的 Cline 系统提示词全解析AI 编程代理的工具调用协议与双模式工作流设计 本文以开源仓库 CL4R1T4S 收录的 CLINE/知识库人工智能AI 安全治理Vundle.vim插件安全加固增强安全性的终极指南Vundle.vim插件安全加固增强安全性的终极指南 Vundle.vim作为Vim的插件管理器帮助用户轻松管理和安装各类插件。然而在享受便捷的同时插件人工智能大模型AI Agent代码智能体CLI工具调用MCP ClientsGoogle Jules 系统提示词深度拆解自主编码 Agent 的工具契约、规划工作流与提交流程Google Jules 系统提示词深度拆解自主编码 Agent 的工具契约、规划工作流与提交流程 Jules 是 Google 面向开发者提供的自主编码 A文档知识库上一篇从数据到模型Time-Series-Library数据集架构全解析下一篇如何为BrewUIHomebrew官方macOS GUI贡献代码第一个PR完整指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
RELATED READING

延伸阅读

更多一线实战笔记与深度复盘,助您持续精进