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

知识库
人工智能
AI 安全治理

【免费下载链接】CL4R1T4S

LEAKED 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, don't 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>）、Shell（<SHELL>）、操作系统版本、以及驱动当前会话的模型名。文档中一处副本显示模型为builtin:zai-coding-plan/GLM-5.3——即模型通过"内置插件"方式注册，而非硬编码在提示词正文中，这保持了提示词的跨模型可移植性。

4.2 上下文管理与自主行动原则

# Context management段（Prompts.md）定义了长会话下的行为准则：

会话变长时，上下文会被摘要压缩，压缩摘要与剩余未压缩内容一起进入下一个上下文窗口，Agent 无需提前收尾或中途交接；
掌握足够信息就行动：不重新推导已确立的事实，不重议用户已做的决定，不叙述不会采纳的选项；
自主运行：用户并非实时观看，中途提问会阻塞工作。对于源于原始请求且可逆的动作，直接执行；只为破坏性动作或真正的范围变更而停止；
例外情形：当用户在描述问题、提问或思考而非请求变更时，交付物是评估结论——报告发现并停止，不擅自应用修复；
收尾检查：结束回合前检查最后一段，如果它是计划、分析、问题或承诺（"我会…""完成后告诉我"），就用工具调用完成它——包括出错后的重试与自行收集缺失信息；只有在任务完成或被只有用户能提供的输入阻塞时才结束回合；
状态变更前的证据校验：运行改变系统状态的命令（重启、删除、配置修改）之前，先核对证据是否真正支持该动作——一个模式匹配到已知失败模式的信号，可能另有原因。

这套准则的实质，是把"何时动手、何时停下"从模糊直觉变成可执行的判定规则，显著减少 Agent 的无效往返。

4.3 会话标题生成与 Web 搜索工具

提示词还内置了两个特殊任务的子提示词（Prompts.md）：会话标题生成——将用户消息意图压缩为 3～7 词、使用用户主要语言、保留专有名词与 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`	用户给出的工作方式指导	纠正与确认，必须包含 why
`project`	项目进行中的状态	目标、约束、截止日期（相对日期转为绝对日期）
`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`/`pptx`	DOCX/PDF/PPTX 的创建、编辑、分析
技能创作与诊断	`skill-creator:skill-creator`	从零编写/迭代 SKILL.md
`zcode-guide:diagnosing-*`系列	诊断 ZCode 客户端的命令、钩子、MCP、插件、技能、扩展资源配置问题

6.3 关键技能要点（来自 Skills.md）

ZAI/ZCode/Skills.md 收录了这些技能的完整加载内容，其中三个技能的工程细节极具参考价值：

control-browser（浏览器自动化）：以 Node REPL MCP 的js工具为驱动，每次调用都运行在全新的 JavaScript 内核中（变量、模块缓存不持久），因此每次调用都必须重新执行 bootstrap——从ZCODE_PLUGIN_ROOT（兼容回退CLAUDE_PLUGIN_ROOT）解析插件根目录，经pathToFileURL加载browser-client.mjs，再调用setupBrowserRuntime。后端类型为iab（应用内浏览器）、extension（Chrome 扩展）、cdp（CLI 托管的无头 Chromium），通过agent.browsers.list()作为可用性事实来源。核心工作流是"定位（tab list）→ 验证（domSnapshot）→ 精确操作（getByRole/getByText 等惰性定位器）→ 廉价观察"，并明确禁止用evaluate()探测选择器、禁止截图与快照双开浪费。

web-gui-tester（GUI 黑盒测试）：确立五大核心原则——纯 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_files）；Task则是 Claude Code 兼容别名，映射到Agent工具。

从工程视角看，这份工具契约回答了三个问题：有哪些能力可用（工具清单）、每个能力允许做什么（权限与副作用声明）、结果如何回流（输出 Schema 与结果预算）。三者共同构成 Agent 能力的可审计边界。

八、对 Agent 系统提示词工程设计的启示

把 ZCode 提示词作为一个整体样本，可以提炼出六条可复用的设计原则：

分层组织，职责单一：身份与安全边界 → 运行契约（Harness）→ 沟通协议 → 会话/上下文 → 记忆 → 技能 → 工具，每一层只解决一类问题，便于维护与增量演进。
安全边界前置且意图化：安全段放在身份之后，用"授权上下文"而非一刀切禁令来管理双重用途工具，兼顾合规与能力。
沟通协议显式化：结论先行、面向协作者写作、可读性优先——把高质量的协作体验写成规则，而不是依赖模型的"悟性"。
记忆与代码解耦、索引与正文分离：文件化记忆 + MEMORY.md 单行索引，既持久又省上下文，并辅以"先验证后推荐"的防过期机制。
技能与工具元数据化：技能以 SKILL.md 文件携带领域方法论，工具以 JSON Schema 携带权限与副作用声明，使能力可枚举、可审计、可授权。
自主与确认的平衡：可逆动作直接执行、不可逆动作先确认、评估类问题只给结论——用规则而非每次提问来管理 Agent 的主动性。