工具太多时把所有 schema 一次性塞进上下文会让模型注意力变差。CLI 的 list 和 -h 可以把这个问题拆开。模型先看一级命令确定领域再看二级命令确定动作最后只读取目标命令的参数说明和示例。上下文更小误选工具的概率也会下降。查看可用领域domain-cli list查看某个领域下的动作domain-cli case list查看目标命令的参数、示例和边界domain-cli case diagnose -h先 dry-run看即将发出的标准请求domain-cli case diagnose --case-idCASE123 --with-detailtrue --dry-run为了让模型真的用得稳通用 flag 也要统一设计Flag 作用 设计要点–params 传查询参数 只接受 JSON object避免任意字符串透传–data 传请求体 与 --params 分开降低 GET / POST 混用–page-all 自动翻页 服务端控制最大页数–page-size 单页条数 有默认值和上限–page-limit 最大翻页数 防止模型无限拉取–dry-run 预览请求 修改类动作必须先经过确认流程–env 指定环境 默认生产环境时要更谨慎测试包可注入默认隔离环境-h/–help 查看帮助 帮助文案要写清楚“什么时候不要用”好的帮助信息不是参数字典而是决策指南。它要告诉模型这个命令解决什么问题不能解决什么问题哪些参数只有在用户明确表达时才能传。Skill Envelope把命令链收成会办事的能力CLI 解决“能力能不能被调用”Skill 解决“任务能不能被办完”。真实用户很少会说“请调用某个接口查询某个字段”。他们会说“帮我排查为什么失败”“看看这个资源能不能提交”“把符合条件的项整理出来”。这些请求背后往往不是一条命令而是一段流程。Skill 的职责就是把命令链、判断逻辑、确认点和输出格式封起来mermaid-05.png图Skill 负责把命令链、判断逻辑、确认点和输出格式收成任务能力。一个成熟的 Skill 至少要写清楚这些内容模块 要写清楚什么适用场景 用户用什么说法会触发这个能力可用命令 允许调用哪些 CLI禁止调用哪些 CLI参数取舍 哪些参数必须来自用户哪些来自上下文哪些不能由模型编风险动作 哪些步骤需要二次确认确认文案怎么写输出格式 返回表格、诊断结论、下一步建议还是执行结果失败处理 权限不足、资源不存在、下游失败时怎么解释这样封装后业务团队交付给 Agent 的就不是一堆接口而是一组可复用、可治理、可升级的能力。测试门禁先验证会拦再谈上线很多团队测试 CLI 时只看“能不能调通”。这不够。对 Agent 可调用能力来说更重要的是确认它会在该拦的地方拦住。上线前至少要跑四类检查检查项 要验证什么框架校验 命令注册、参数类型、帮助信息、输出裁剪是否符合配置登录态失败 缺失或过期身份是否被拒绝垂直越权 没有功能权限的身份是否无法调用水平越权 A 资源上下文是否无法访问 B 资源dry-run 写操作是否能先生成可读的执行预览审计日志 每次调用是否能追到命令、参数摘要、身份、环境和结果本地模拟也有价值但它只能解决“能否快速调试”的问题。真正的安全边界要在接近真实的环境里验证因为身份、权限和资源隔离往往只有在完整链路里才会暴露问题。构建和发布也建议拆出环境本地构建并生成命令树make build TARGETinternal打测试包默认连到隔离环境make package TARGETinternal CHANNELtest DEFAULT_ENVsandbox只在测试验证完成后发布正式包make publish TARGETinternal CHANNELrelease版本管理要非常克制。只要命令行为、参数含义或输出结构发生变化就应该有可追踪的版本记录如果某个命令仍在灰度最好显式关闭或只在测试包里暴露。结语别把 Agent 接口做成一次性脚手架
工具太多时把所有 schema 一次性塞进上下文会让模型注意力变差。CLI 的 list 和 -h 可以把这个问题拆开。模型先看一级命令确定领域再看二级命令确定动作最后只读取目标命令的参数说明和示例。上下文更小误选工具的概率也会下降。查看可用领域domain-cli list查看某个领域下的动作domain-cli case list查看目标命令的参数、示例和边界domain-cli case diagnose -h先 dry-run看即将发出的标准请求domain-cli case diagnose --case-idCASE123 --with-detailtrue --dry-run为了让模型真的用得稳通用 flag 也要统一设计Flag 作用 设计要点–params 传查询参数 只接受 JSON object避免任意字符串透传–data 传请求体 与 --params 分开降低 GET / POST 混用–page-all 自动翻页 服务端控制最大页数–page-size 单页条数 有默认值和上限–page-limit 最大翻页数 防止模型无限拉取–dry-run 预览请求 修改类动作必须先经过确认流程–env 指定环境 默认生产环境时要更谨慎测试包可注入默认隔离环境-h/–help 查看帮助 帮助文案要写清楚“什么时候不要用”好的帮助信息不是参数字典而是决策指南。它要告诉模型这个命令解决什么问题不能解决什么问题哪些参数只有在用户明确表达时才能传。Skill Envelope把命令链收成会办事的能力CLI 解决“能力能不能被调用”Skill 解决“任务能不能被办完”。真实用户很少会说“请调用某个接口查询某个字段”。他们会说“帮我排查为什么失败”“看看这个资源能不能提交”“把符合条件的项整理出来”。这些请求背后往往不是一条命令而是一段流程。Skill 的职责就是把命令链、判断逻辑、确认点和输出格式封起来mermaid-05.png图Skill 负责把命令链、判断逻辑、确认点和输出格式收成任务能力。一个成熟的 Skill 至少要写清楚这些内容模块 要写清楚什么适用场景 用户用什么说法会触发这个能力可用命令 允许调用哪些 CLI禁止调用哪些 CLI参数取舍 哪些参数必须来自用户哪些来自上下文哪些不能由模型编风险动作 哪些步骤需要二次确认确认文案怎么写输出格式 返回表格、诊断结论、下一步建议还是执行结果失败处理 权限不足、资源不存在、下游失败时怎么解释这样封装后业务团队交付给 Agent 的就不是一堆接口而是一组可复用、可治理、可升级的能力。测试门禁先验证会拦再谈上线很多团队测试 CLI 时只看“能不能调通”。这不够。对 Agent 可调用能力来说更重要的是确认它会在该拦的地方拦住。上线前至少要跑四类检查检查项 要验证什么框架校验 命令注册、参数类型、帮助信息、输出裁剪是否符合配置登录态失败 缺失或过期身份是否被拒绝垂直越权 没有功能权限的身份是否无法调用水平越权 A 资源上下文是否无法访问 B 资源dry-run 写操作是否能先生成可读的执行预览审计日志 每次调用是否能追到命令、参数摘要、身份、环境和结果本地模拟也有价值但它只能解决“能否快速调试”的问题。真正的安全边界要在接近真实的环境里验证因为身份、权限和资源隔离往往只有在完整链路里才会暴露问题。构建和发布也建议拆出环境本地构建并生成命令树make build TARGETinternal打测试包默认连到隔离环境make package TARGETinternal CHANNELtest DEFAULT_ENVsandbox只在测试验证完成后发布正式包make publish TARGETinternal CHANNELrelease版本管理要非常克制。只要命令行为、参数含义或输出结构发生变化就应该有可追踪的版本记录如果某个命令仍在灰度最好显式关闭或只在测试包里暴露。结语别把 Agent 接口做成一次性脚手架
