让 Agent 会干活不难难的是让它干得安全、可控、有迹可循。prompt 约束是软的Agent 一旦自信起来就会绕过真正的安全边界要靠工程架构来保障。01MCP、Skills、Hooks 三者的关系MCP 为 Agent 接入平台能力——以 tools 的形式让 Agent 按接口定义发送请求、调用后端。但单个工具调用凑不成完整流程。工具之间如何协作、按什么顺序串联需要 Skills 来编排——Skills 与业务紧密绑定定义先做什么、再做什么、失败怎么办。即便有了流程Agent 在调用时仍会出问题参数一多就丢字段复杂嵌套就误填偶尔还擅自调用高风险工具造成意外伤害。Hooks 正是在 Agent 发起工具调用以及 Skills 内脚本执行时进行规则拦截保障安全运行同时记录审计日志让每次调用有迹可循。02MCP 设计Agent需要一个应用市场2.1 MCP 协议是怎么回事MCPModel Context Protocol协议中Server 暴露给 Client 三种核心原语Tools、Resources、Prompts。要理解 Agent 插件怎么设计先要理解这三种原语在 Agent 运行时分别是如何被加载和使用的。Tools启动时批量注册注入 system promptAgent 启动时CodeBuddy 框架向所有已配置的 MCP Server 发送tools/list请求拿到完整的工具清单。每个工具是一个结构体name工具名、description功能描述、inputSchema参数的 JSON Schema。这些定义会被注入到 LLM 的 system prompt 中——LLM 看到的不是函数指针而是一段文本描述“你可以调用workflow_create它接受name必填, string、spaceId必填, int64……”Resources惰性拉取Agent 按需查询Resources 不像 Tools 那样启动时一次性拉取。它们的加载是惰性的——Agent 在对话中根据需求主动发起resources/read请求。比如 MCP Server 暴露了 150 张数据表作为 Resourcesstarrocks://tables/...的 URI。Agent 不会在启动时把所有表的 schema 都拿到而是等用户说查一下 ODS 层的员工表有哪些字段时才去请求对应的 Resource URI拿到字段名、类型、注释。这套按需加载机制避免了启动时的通信风暴也避免了 system prompt 被大量无用信息填满。PromptsServer 端预定义的提示词模板Prompts 是 MCP Server 上预定义的、可参数化的提示词模板。Agent 通过prompts/list查看可用模板通过prompts/get获取具体模板并填入参数。与 Tools 不同Prompts 没有副作用纯粹是帮助 Agent 更好地理解在特定场景下该怎么做。三种原语的多维对比维度ToolsResourcesPrompts数据流向双向参数入 → 结果出单向Server → Client只读单向Server → Client读写读写只读只读加载策略启动时批量注册注入 system prompt惰性按需拉取可缓存惰性按需获取可缓存适合场景CRUD、部署、启停等需要动手的操作表 schema、数据字典、配置文档等大量结构化参考数据需要标准化引导的重复性任务核心优势唯一能修改外部状态的通道量大不占 prompt 空间按需加载可复用、可参数化保持行为一致不适合纯信息查询用 Resource 更高效实时计算任务应走 Tool动态决策模板会限制推理灵活性实战中用好这三种类型的原语能够提高agent调用效率和token的使用效率。MCP协议计划在2026年7月28日发布一次重大更新当前为候选版主要是从原来的有状态连接变成无状态连接这对后续高性能的MCP集成是一次重大的进步MCP逐渐会成为Agent更坚实的基础设施。具体的内容可以参考这个博客。https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/2.2 自建 MCP Server 的经历最初方案是自建一个 Spring Boot MCP Server——在 Agent 和 DES 后端之间架一套中间代理Agent → MCP → des-mcp-server → REST → DES Backend。自建的好处是自由度极高——工具注册策略、参数校验逻辑、错误处理方式都可以自己控制比如可以按业务域灵活分级部署工具。但真正上手之后两个核心问题逐渐暴露架构取舍如果新建一套 AiController 并直接调用 Service 层来绕过原 Controller那么原 Controller 上设计的 AOP 切面、并发控制、异常处理等逻辑全部需要在新 AiController 中重做一遍——不是简单的调用转发而是整套横切关注点的二次实现。部署运维MCP Server 作为一套独立的 Java 服务构建、部署、监控、扩缩容都需要额外维护——它和服务本身不在同一个交付单元里版本同步、依赖管理、线上排错都多了一层。这些本质上不是做不出来的问题而是值不值得单独维护一个中间代理层的问题。正是这个判断让我们把目光转向了部门内已有的基础设施。2.3 选择 SA-MarketSA-Market 是部门内已有的 MCP 市场原生支持将 REST API 自动注册为 MCP 工具——上传 Swagger/OpenAPI 规范后也支持 MCP Json平台自动解析出 tool schema无需写一行 MCP 适配代码。架构上同样是一层路由Agent → MCP 协议 → SA-Market → REST → DES Backend但省掉了自建中间服务的所有维护成本。这更像是应用市场能够有一个中心化的平台路由分发各个项目接入的能力集中管理和维护。对比自建方案SA-Market 省掉了两块最大的开销不用自建中间服务2.2 中提到的架构取舍和部署运维问题直接不存在了——不用纠结 AiController 的复用策略也不用维护独立 Java 服务的构建部署链路不用手写适配代码Tool 的 inputSchema 和后端接口入参之间的耦合是绕不开的——自建方案里这份映射靠人工维护SA-Market 则是上传一份 OpenAPI/JSON 规范平台自动解析出 MCP 工具定义省去了手写和维护映射逻辑的工作03Skills 设计Mermaid一言以蔽之3.1 多步骤操作的编排困境MCP 工具就位后一个完整的业务流程往往要调用多个工具而且工具的使用有顺序依赖和注意事项。比如部署一个工作流导入 JSON → 保存草稿 → 调试运行 → 修复问题 → 更新 → 发布上线这不是一个单步 MCP 调用而是 5-6 个步骤组成的有向无环图。如果靠 LLM 自由发挥来编排会出现跳步没调试就直接发布上线带着 bug 跑乱序先 publish 再 save draft —— 状态机冲突遗漏错误处理debug_run 失败了不知道怎么修卡在半路MCP 工具层解决了能调用什么但没有解决怎么组合调用才是正确的——这个编排问题需要 Skills 层来解决。3.2 Mermaid SOP用流程图替代文字步骤列表但是SOP 类型的 Skill 一旦步骤长、分叉多纯文本写下来既冗长又难理解。引入 Mermaid 后几行就能描述一个分支复杂的完整流程。以deploy-workflowSkill 为例它的 mermaid SOP 大致结构是相比于纯文本的步骤列表Mermaid 的视觉表达让 Agent 能更准确地理解哪些步骤是顺序依赖的A→B→C哪里有条件分支成功→继续失败→诊断修复失败后的回退路径是什么回到上一步重试虽然没有进行量化实验对照但实际使用效果可以感觉到Agent 跳步、乱序的问题显著减少因为Mermaid能够在有限的篇幅传达高密度的信息。3.3 强制走链规则除了 SOP 编排Skills 层还有一条硬约束某些 MCP 写工具必须先走完对应 Skill 才能调用。例如调用workflow_importtool 前必须先走des-generatorskill —— 确保 JSON 是标准化流程生成的、经过字段校验的调用dqc_rule_createtool 前必须先走dqc-workflow-generatorskill →create-dqcskill —— 确保规则参数完整、合规这条规则在context.md中定义为行为规范约束Agent 在执行写操作前会检查依赖链并引导用户先走 Skill 流程。它不依赖 Hook 层的代码拦截Hook 层负责的是安全分级而是在 Agent 的推理层面建立先走流程、后调工具的纪律。04Hooks 设计All you need is 强而有力的脚本如果说 MCP 层解决能操作什么、Skills 层解决怎么正确操作那么 Hooks 层解决的是最后一个、也是最关键的问题Agent 被允许怎么操作——安全边界在哪里。4.1 Hook 的运行原理MCP 调用链路中的检查点Hook 不是嵌入 Agent 对话流程中的 prompt 规则而是插件框架在 MCP 工具调用链路里注入的同步拦截点。Agent 构造完 tool call 后、框架实际发起调用之前引擎暂停执行流将 tool_name 和 tool_input 序列化后交给 Hook 脚本裁决。脚本执行校验逻辑后返回结构化控制字段continue 决定放行或拦截permissionDecision 决定是否弹出确认框modifiedInput 用于补全缺失参数等等。引擎根据这些字段执行最终动作放行、弹窗确认、或直接拒绝。Agent 无法绕开因为 tool call 到实际执行的路径被框架独占Hook 是这条路径上的唯一道闸。des-agent-plugin这里主要使用了三种事件类型PreToolUse调用前拦截、PostToolUse调用后审计、SessionStart会话开始注入。Hook触发时机文件代码量职责PreToolUse调用 MCP 工具之前pre_tool_guard.py~60KB安全拦截 参数校验 字段补全PostToolUseMCP 工具调用完成后post_tool_audit.py~40KB审计记录 产出物管理 经验闭环SessionStart每次对话开始时session_start.py~15KB注入上下文、偏好、最近操作4.2 四级安全分级拦截点就位后接下来要定义规则什么操作该拦截、什么该放行。设计上采用了渐进式安全分级而不是二元的允许/拒绝——从静默放行到硬阻断四个梯度覆盖了查询、审计、写操作、不可逆删除全部场景4.3 9 步安全流水线从规则加载到放行pre_tool_guard.py的内部逻辑是一条 9 步流水线每一步都是独立可测试的模块新增规则只需在rules.json中追加配置段无需修改pre_tool_guard.py的主体逻辑。4.4 Tier 条件链与 Body Check4.4.1 Tier 条件链一种条件性字段校验模型Tier 是这里定义的一种条件性字段校验层。一个 tier 包含一组字段声明required必填非空 /nullable必填可空和一个可选的触发条件。条件支持三种操作符eq精确相等含布尔/字符串类型兼容、contains数组包含、not_empty非空触发。多个 tier 串联形成 condition-chain——tier0 无条件必检tier1 在某字段满足条件时追加校验tier2 又依赖 tier1 的结果……链条深度随业务复杂度递增。以 DQC 任务为例tier触发条件requirednullabletier0无条件必检datasourceId,isSr,databaseName,tableName,dqcRuleCodesdescriptiontier1isAlert truealertConfigType,isMergeAlert↳tier2,isAlertDeduplication↳tier3—tier2isMergeAlert truealertConfigIds—tier3isAlertDeduplication truededuplicationRange—isMergeAlert 和 isAlertDeduplication 经 tier1 校验通过后分别下探为 tier2 和 tier3 的触发条件。执行逻辑tiers 数组按序遍历当前 tier 的 condition 满足 → 追加校验该 tier 的字段不满足 → 跳过。没有 condition 的 tier如 tier0无条件必检。链条深度随业务复杂度递增DQC 任务 4 层STARROCKS_SQL/JDBC_SQL 2-3 层body_check 的写工具通常 2-3 层。Step 5body_check和 Step 6task_type共用这套 tier 抽象但校验对象不同body_check 校验请求体顶层字段扁平结构task_type 校验的是taskDefinitions[].taskProperties——三层嵌套的键值对数组[{prop: xxx, value: yyy}]。如果硬塞进 body_check 的通用逻辑校验层级会过深、代码复杂度爆炸。因此 taskProperties 被单独拆出为task_type_field_checks段 独立的_check_task_properties函数但内部复用同一套 condition-chain 求值器_matches_tier_condition_check_tier_fields。4.4.2 两种格式覆盖 14 个写工具4.1 中定义的 condition-chain 抽象在这里同样适用body_check 的 tier 链通常 2-3 层比 task_type 的 4 层浅。不同的 API 参数结构不同同一套校验逻辑无法适配所有场景因此设计了两种格式tiers 格式14 个工具——分层条件校验覆盖所有需要字段校验的写工具。每个工具的校验定义包含_get_tool关联查询工具和tiers数组。每个 tier 有三层语义required必填且非空。缺失或空值直接拦截——如workflow_update的taskDefinitions缺失会导致画布无节点、publish 失败。nullable必填但可为空。字段必须存在值可以为空数组或空字符串——如alertChannels可为空数组表示无告警。condition条件触发。当某字段满足条件时追加额外必填校验——如选了TIMEOUT告警渠道时timeout字段变为必填非空。_get_tool机制是 tiers 格式的关键在Agent调用传入了不完整字段会返回提示信息调用关联的 get 工具如workflow_update关联workflow_get拉取当前对象的现有状态用于对比避免 Agent 用残缺参数覆盖完整数据。_array_check 格式——批量操作元素级校验作为 tiers 的补充。dqc_rule_batch_create这类批量工具不仅要校验数组非空还要对数组中每个元素内部用 tiers 逻辑逐条校验。_array_check定义了field数组字段名和item_tiers每个元素的 tier 校验规则相当于把 tiers 格式嵌套进数组遍历。这个工具同时也有 tiers 格式定义——_array_check 是在 tiers 基础上的额外补充。两种格式不是并列关系而是叠加关系14 个工具都有 tiers 格式其中dqc_rule_batch_create额外叠加 _array_check 做数组遍历。这种设计避免了写一个万能校验引擎的过度抽象——tiers 解决结构化参数的条件校验_array_check 解决批量操作的逐元素校验各司其职。05多平台设计设计规则在哪里生效5.1 双平台实战演示DES 插件需要覆盖两类用户CodeBuddy IDE 用户iMate 用户des-agent-plugin在这两个平台的 Hook 脚本实现语言不同Python vs JavaScript但需要一致的安全规则和行为规范。第四章从代码层面拆解了 Hook 引擎的 9 步流水线和 tier 条件链。下面从各平台的实际运行效果来展示拦截和校验在真实对话中长什么样CodeBuddy IDE以下是发布工作流的场景在用户提到发布工作流时会加载deploy-workflow Skill发布前会向用户确认当前工作流的信息和状态。用户确认继续后会进入到下一个阶段这里的workflow_save_draft是保存草稿但是其中集成了对工作流的合法性校验在Skill中定义了在发布前需要执行校验的步骤。在agent调用工具的时候如果传入的请求体字段不满足hook中约束的字段规则会执行deny拒绝掉本次调用并返回所缺少的字段。agent会根据提示信息重新发起一次调用字段满足后会调起hook弹窗。用户确认后会按照Skill中定义好的mermaid流程图进入到下一阶段这里是在流程图的节点中声明在调试阶段需要询问用户是否需要调试这里是要求Agent调用AskUserQuestion工具这样就能够出现如图的弹窗供用户选择。iMate 平台在iMate平台的网页版和企微机器人实现了同样的插件机制这里展示的是hook弹窗。这里因为iMate在调度mcp的时候使用的是mcporter调用的命令的形式和CodeBuddy不完全一致在hook脚本中进行调用匹配的逻辑上做了一些适配。这里是企微机器人的场景。5.2 Symlink 单源管理要适配多平台又想要在同一个仓库中维护管理插件解决思路是 Monorepo Symlinkdes-agent-plugin/├── shared/ ← 唯一的配置源│ ├── rules.json (18段, 28KB)│ ├── rules-error-patterns.json (错误模式库)│ └── context.md (Agent行为规范)│├── plugins/des-platform/ ← CodeBuddy IDE 插件│ └── hooks/│ ├── rules.json ──⛓── ../../shared/rules.json (symlink)│ ├── rules-error-patterns.json ──⛓── ../../shared/... (symlink)│ └── context.md ──⛓── ../../shared/context.md (symlink)│└── platforms/imate/ ← iMate/OpenClaw 插件 └── src/ ├── rules/rules.json ──⛓── ../../../shared/rules.json (symlink) ├── rules/rules-error-patterns.json ──⛓── ../../../... (symlink) └── config/context.md ──⛓── ../../../shared/context.md (symlink)5.3 Symlink 是怎么工作的流程很简单如果仓库中已经构建好了软链接那么git clone获取仓库——Linux/macOS 下 git 原生保留 symlinkclone 后自动生效Windows 需开启开发者模式并设置git config core.symlinks true若上述条件不满足如 Windows 未配置需要运行提前写好的脚本init-platforms.sh执行 6 条ln -sf命令重建 symlink如果软链接实在无法构建脚本中还有直接复制过去的fallback之后修改shared/rules.json→ symlink 自动跟随 → 双平台同时生效对代码本身来说symlink 是透明的Python 侧common.py:load_rules()用os.path.dirname(__file__)相对路径读取文件系统自动解析为shared/下的实际文件JS 侧import rules from ../rules/rules.json中 Node.js 的模块解析自动跟随 symlink06多平台设计设计规则在哪里生效6.1 rules.json18 段配置的完整体系所有安全规则、字段校验、DDL 模式、环境映射全部外化到rules.json中——不在pre_tool_guard.py中硬编码任何规则。18 段配置的结构从简单到复杂渐进#段名内容复杂度0version配置版本号低1des_serversMCP URL → 环境名称映射低2blocked5 个不可逆删除工具低3warned31 个高风险写工具中4dangerous_scripts3 个高危 Python 脚本低5dangerous_ddl_patterns8 种 DDL 危险语句检测高6audit40 个静默审计工具中7experience_ttl_days经验闭环 TTL30天低8querydata_tools12 个分页查询工具低9diagnostic_tools6 个诊断工具低10recent_categories9 条记忆分类映射中11failure_tips5 条失败重试指引中12body_check_tools14 工具字段完整性tiers _array_check 叠加高13body_check_ask_user_guides弹窗引导文案低14task_property_check_tools6 个 taskProperties 校验工具中15task_type_field_checks4 种 TaskType 分层 tier高16auto_fill_fields自动补全默认值低17diff_tools3 个差异对比工具低这里的外化相当于将配置文件和代码逻辑进行解耦便于长期维护。以上的规则配置这里只是给出一个参考的实践方式具体还可以有更多的发挥空间。6.2 Agent Plugin Factory从做插件到做做插件的工具在完成 DES 插件之后我们考虑把设计和开发经验固化为一个元工具Agent Plugin Factory——给一个 Swagger/OpenAPI 规范自动生成完整的平台 Agent 插件。目前这套流程还在开发验证阶段因为不同的系统的具体情况不一样这里提供一种可参考的方法论具体的实施和测试环节需要根据具体的情况再进行一些适配上的工作。四阶段流水线Swagger/OpenAPI ↓Stage 1: Parse — parse_swagger.py 解析所有 API endpoint提取 path/method/params/schema ↓Stage 2: Classify — classify_tools.py 按 HTTP 方法自动安全分级: DELETE / delete → blocked POST / create|update|import → warned GET / list|get|query → audit 其他 → pass-through ↓Stage 3: Detect — detect_querydata.py 检测哪些接口返回 list/rows标记为 querydata_tools ↓Stage 4: Generate ├─ generate_all.py: SA-Market JSON 脚本生成 三层校验语法/语义/集成 ├─ AI Agent 理解需求并填充 config.yaml → Jinja2 模板引擎渲染 17 文件一键生成 └─ 输出: CodeBuddy 插件 (.mcp.json hooks context.md 8 Skills) iMate 插件 (openclaw.plugin.json JS Hooks) SA-Market 注册文件这里设想着不再只为 DES 这一个平台解决问题而是把如何给任意 API 服务生成安全可控的 Agent 插件的方法论固化为工具成为能够高自动化将项目转化为集成MCP、Skills、Hooks的Agent插件。07总结回头看这四层设计每一层解决的是 Agent 操作平台的不同维度问题MCP 层定义能操作什么——72 个工具4 个环境统一1 份 Swagger 规范即注册。经验与其自建中间代理不如用好已有的基础设施。Skills 层定义怎么操作才对——8 个 SkillMermaid SOP 可视化强制走链。经验让 Agent 按规矩办事比让它更聪明更可靠。Hooks 层定义被允许怎么操作——四级分级9 步流水线18 段外化规则170KB 拦截逻辑。经验安全边界不靠 prompt 保证靠工程架构保障。多平台层定义规则在哪生效——6 个 symlink双平台原生 170KB73KB不改代码就能同步规则。经验不做抽象层用文件系统级的一致性保证逻辑一致。这四层叠在一起构建了一个让 Agent 有能力、有规矩、有底线、有一致性的操作框架。今天的模型能力已经跃过了一道门槛理解意图、生成代码、自主推理不再是瓶颈。但模型不会自动解决工程问题安全边界在哪里、操作流程怎么规范、规则怎么在多平台同步。对于Coding Agent的工程化有人说会是这样的发展链路Prompt Engineering - Context Engineering - Harness Engineering - Loop Engineering - Graph Engineering但是我在想这里所设计的工程也是人类的集体的智慧围绕着大模型搭建起的护栏那么对于 Agent 本身我们能否使其涌现出群体的智慧我们是否知道 Agent 知道多少Agent 自己本身是否知道自己知道多少我们到底应该如何定义 Agent 呢这里也许还需要着长期的探索。这里给大家精心整理了一份全面的AI大模型学习资源包括AI大模型全套学习路线图从入门到实战、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等资料免费分享扫码免费领取全部内容1. 成长路线图学习规划要学习一门新的技术作为新手一定要先学习成长路线图方向不对努力白费。这里我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。2. 大模型经典PDF书籍书籍和学习文档资料是学习大模型过程中必不可少的我们精选了一系列深入探讨大模型技术的书籍和学习文档它们由领域内的顶尖专家撰写内容全面、深入、详尽为你学习大模型提供坚实的理论基础。书籍含电子版PDF3. 大模型视频教程对于很多自学或者没有基础的同学来说书籍这些纯文字类的学习教材会觉得比较晦涩难以理解因此我们提供了丰富的大模型视频教程以动态、形象的方式展示技术概念帮助你更快、更轻松地掌握核心知识。4. 2026行业报告行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估以了解哪些行业更适合引入大模型的技术和应用以及在哪些方面可以发挥大模型的优势。5. 大模型项目实战学以致用当你的理论知识积累到一定程度就需要通过项目实战在实际操作中检验和巩固你所学到的知识同时为你找工作和职业发展打下坚实的基础。6. 大模型面试题面试不仅是技术的较量更需要充分的准备。在你已经掌握了大模型技术之后就需要开始准备面试我们将提供精心整理的大模型面试题库涵盖当前面试中可能遇到的各种技术问题让你在面试中游刃有余。7. 资料领取全套内容免费抱走学 AI 不用再找第二份不管你是 0 基础想入门 AI 大模型还是有基础想冲刺大厂、了解行业趋势这份资料都能满足你现在只需按照提示操作就能免费领取扫码免费领取全部内容