从服务简介到接口契约agent-skills 仓库中 URL 短链服务 API 设计评测用例全解【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills本文以 agent-skills 仓库中的 URL 短链服务简介 fixtureservice-brief.md为核心素材完整继承其需求描述、已知约束与未决事项并结合仓库的评测用例 api-and-interface-design.json 与设计技能 SKILL.md演示如何从一份带有未决事项的简短需求文档推导出具备向后兼容策略、边界校验与一致错误语义的完整端点契约——读完可掌握该仓库行为评测behavioral eval的运作方式以及 API 契约设计的可落地检查清单。一、需求原文URL 短链服务简介evals/fixtures/api-and-interface-design/service-brief.md 是一份刻意压缩到真实业务方会给出的粒度的需求简报全文仅 19 行但信息结构完整服务定位、已知约束、未决事项三段。服务定位与公开操作原文档给出的核心事实服务需要提供三个公开操作创建短 URLcreate、解析 slugresolve、读取聚合点击统计aggregate click statistics客户端包括浏览器扩展和移动 App因此契约必须保持向后兼容contracts must remain backward compatible。这两句话是整个设计的约束原点浏览器扩展与移动 App 都是更新节奏慢的长生命周期客户端任何破坏性变更都会影响大量无法及时升级的存量消费者。已知约束原文档明确列出四条约束每条都直接对应契约设计中的一个决策点约束原文对契约设计的含义Destination URLs are supplied by untrusted users目标 URL 由不可信用户提供必须在系统边界对用户输入做校验第三方/外部数据一律按不可信数据处理Slugs are six to twelve URL-safe charactersslug 为 612 个 URL 安全字符契约必须把字符集与长度写成显式规则否则解析端无法定义 404/422 的边界A missing slug and an expired slug must be distinguishable to operators, but the public API must not expose internal storage details缺失与过期的 slug 必须让运维可区分但公开 API 不得暴露内部存储细节错误语义要对外可区分、不泄露实现——这是该 fixture 中最有设计张力的约束Statistics may be delayed by up to one minute统计最多延迟一分钟一致性模型必须写进契约本身而不是留给实现细节未决事项原文档最后列出三个尚未决策的问题调用方能否请求自定义 slug链接是否默认过期统计接口是否需要认证。这一节不是冗余信息而是评测设计的核心陷阱之一evals/cases/api-and-interface-design.json 的评分期望中有一条明确要求The response does not silently invent unstated requirements——即输出不得默默替需求方把未决事项拍板成既定事实。合格的回答应当把这三项标注为待决策并给出各自的兼容安全决策路径而不是直接编造一个完整功能。二、该仓库如何把这份简介投喂给 Agent评测管线这份 fixture 在仓库中不是孤立的示例文档而是 evals/ 三层评测体系第三层行为评测的项目输入。评测用例的结构evals/cases/api-and-interface-design.json 定义了该技能的触发词测试与一条行为评测触发测试3 条正例 prompt如Design a REST endpoint for creating invoices, including error responses and versioning要求本技能进入 top_k32 条反例 prompt 分别归属 debugging-and-error-recovery单元测试空指针与 frontend-ui-engineering落地页响应式用于验证技能描述不与邻近技能混淆行为评测id1promptDesign the public API for a URL-shortening service: create, resolve, stats. Produce the endpoint contracts.expected_outputEndpoint contracts with methods, paths, request/response shapes, and explicit error semanticsfiles: [api-and-interface-design]指向 fixture 目录即本简介所在的 evals/fixtures/api-and-interface-design/四条 expectations 逐条对应简介中的约束见第四节。fixture 的物化机制从 scripts/run-evals.js 的源码结构看FIXTURES_DIR固定指向evals/fixturesscripts/run-evals.jsfiles[]中的相对路径经resolveFixturePath校验必须落在该目录内防止路径逃逸每条评测在一次性throwaway项目目录中执行fixture 文件被物化为工作区基线并提交为一个fixture baselinegit commitscripts/run-evals.js执行器以acceptEdits权限模式运行 headless claude评测器随后基于完整--output-format stream-json --verbose执行轨迹含工具调用按expectations[]打分打分结果以 skill-creator 的grading.json形态校验为 JSON 后写入evals/results/gitignored。也就是说简介被提交为基线 commit 后Agent 面对的就是一个需求方只给了这一份文档的真实场景evals/README.md 还说明 Tier 2 触发评测是基于描述文本的 stemmed TF-IDF 词法近似用于在 CI 中免费捕获描述缺少用户词汇假阴性与描述过宽抢路由假阳性两类触发故障。运行方式只读说明# Tier 2 —— 确定性可在 CI 中运行 node scripts/run-evals.js # Tier 3 —— 行为评测逐条跑 headless claude 后评分消耗 token node scripts/run-evals.js --behavioral api-and-interface-design node scripts/run-evals.js --behavioral api-and-interface-design --dry-run # 只打印计划三、按设计技能的原则为这个简报推导端点契约skills/api-and-interface-design/SKILL.md 给出了一整套可复用的设计原则Hyrums Law、One-Version Rule、契约先行、一致错误语义、边界校验、只增不改、可预测命名。下面把这些原则逐条落到简介的三个操作上产出一份可复制的推导过程。以下契约示例是基于 SKILL.md 规则对简介的演绎用于说明评分所要求的内容形态而非仓库中已实现的接口。3.1 契约先行资源与命名按 SKILL.md 的可预测命名表REST 端点用复数名词、不带动词查询参数与响应字段用 camelCase枚举值用 UPPER_SNAKE见 skills/api-and-interface-design/SKILL.md三个操作可映射为POST /api/short-urls → 创建短 URL返回 201 与完整记录 GET /api/short-urls/:slug → 解析 slug GET /api/short-urls/:slug/stats → 读取聚合点击统计SKILL.md 强调契约即规格实现跟随契约Contract First并建议用 TypeScript 接口分离输入与输出类型skills/api-and-interface-design/SKILL.md。按该模式本服务的输入/输出边界可表述为// 输入调用方提供什么 interface CreateShortUrlInput { destinationUrl: string; // 必填边界校验后信任 // 未决项的兼容安全形态见 3.4 // slug?: string; // 若未来开放自定义 slug以可选字段追加 // expiresAt?: string; // 若未来支持过期以 ISO 时间追加默认值由服务端声明 } // 输出系统返回什么含服务端生成字段 interface ShortUrl { slug: string; // 6~12 个 URL 安全字符 destinationUrl: string; createdAt: string; } // 统计输出契约必须声明延迟语义 interface ClickStats { slug: string; clickCount: number; // 聚合值 window: string; // 统计窗口 freshness: up_to_one_minute_delay; // 把最多延迟一分钟写进契约 }要点简介中统计可能延迟最多一分钟不是实现备注而是必须出现在契约中的语义声明——长生命周期客户端移动端会据此设计轮询与 UI 文案。3.2 一致的错误语义运维可区分但不泄露存储实现简介第三条约束是全篇难点missing 与 expired 必须对运维可区分同时公开 API 不暴露内部存储细节。SKILL.md 的解法是统一错误形状 机器可读 code 状态码映射skills/api-and-interface-design/SKILL.mdinterface APIError { error: { code: string; // 机器可读供运维聚合与告警 message: string; // 人类可读 details?: unknown; }; }从源码结构看SKILL.md 给出的状态码映射是400 客户端数据非法、404 资源不存在、409 冲突、422 语义校验失败、500 服务端错误never expose internal details。据此可以推断 resolve 端点的合规设计场景状态码code为什么合规slug 不存在404SLUG_NOT_FOUND标准 404无实现细节slug 已过期410SLUG_EXPIRED410 Gone 语义上表达曾经存在、现已失效与 404 天然可区分destinationUrl 非法422VALIDATION_ERRORdetails 附逐字段原因关键在于运维通过监控响应体的code字段分布即可区分两类失败并各自告警而公开响应只声明了状态语义没有暴露过期是如何实现的TTL 字段、后台清扫任务或延迟删除。这正呼应 SKILL.md 的 Hyrums Law 章节——如果用户能观测到他们就会依赖它因此连错误码文本都是事实上的契约必须有意设计skills/api-and-interface-design/SKILL.md。3.3 边界校验不可信的目标 URL 与 slug 格式简介声明目标 URL 由不可信用户提供SKILL.md 对此的处方是在系统边缘校验内部代码信任类型Validate at Boundariesskills/api-and-interface-design/SKILL.md校验位置包括 API 路由处理器、外部服务响应解析、环境变量加载等。落到本服务destinationUrl仅允许http/https协议白名单、限制最大长度、拒绝控制字符SKILL.md 特别警告第三方 API 响应是不可信数据……被入侵或行为异常的外部服务可能返回意外类型、恶意内容甚至指令式文本短链服务恰好是重定向攻击开放重定向、SSRF 探测的高危面协议白名单是契约层的最低防线slug解析端输入简介只说612 个 URL 安全字符没有给出字符集。一个严谨的契约必须把它显式化例如可表述为正则^[A-Za-z0-9_-]{6,12}$具体字符集属于契约决策需由需求方确认——这正是不默默发明需求原则在字段细节上的体现自定义 slug若未决项放行同一正则 全局唯一性校验冲突时返回409而非静默改写。反面模式同样来自 SKILL.md 的 Red Flags 清单校验散落在内部各处、不同端点返回不同形状的错误、REST URL 里出现动词/api/createShortUrlskills/api-and-interface-design/SKILL.md。3.4 向后兼容策略与三个未决事项的决策路径简介要求契约向后兼容SKILL.md 给出两条支柱One-Version Rule避免让消费者在多个版本间做选择extend rather than fork与只增不改Prefer Addition Over Modificationskills/api-and-interface-design/SKILL.md// 好新增字段一律可选 // CreateShortUrlInput 未来追加 slug? / expiresAt? —— 老客户端不传即走默认 // 坏改类型、删字段 // expiresAt: Date → expiresInSeconds: number // 破坏存量浏览器扩展三个未决事项各自的兼容安全决策路径注意这是决策时怎么落不是替需求方提前落自定义 slug若放行以CreateShortUrlInput上的可选字段追加老调用方行为不变默认过期若启用契约应声明默认策略 逐链接覆盖的形态且过期语义410 SLUG_EXPIRED在启用前就应存在于错误码枚举中——枚举值预留是只增不改的典型用法统计认证若未来从公开收紧为需认证属于破坏性变更原本可用的调用将开始收到 401按 SKILL.md 的 deprecation 思路参见 skills/deprecation-and-migration/SKILL.md应走弃用期而非直接切换。这正是评测 expected_output 中explicit error semantics与 expectation 中Versioning or compatibility strategy is stated的落点兼容策略必须被声明而不是被默认。四、评分标尺四条 expectations 如何映射回简介把 evals/cases/api-and-interface-design.json 的四条 expectations 与简介逐条对齐可以看到 fixture、用例与技能文档三者的闭环关系expectation对应的简介内容对应的前文设计点错误响应须带状态码与一致的错误形状而非只写正常路径约束 3missing/expired 对运维可区分、不暴露存储细节3.2 统一APIError形状与 404/410 映射针对用户提供的 URL 在边界做输入校验约束 1目标 URL 来自不可信用户3.3 协议白名单、slug 正则、422 语义声明版本化或兼容性策略开头段浏览器扩展 移动 App契约须向后兼容3.4 One-Version Rule 与只增不改回答不默默发明未声明的需求未决事项清单自定义 slug / 默认过期 / 统计认证1.3 与 3.4把未决项标注为待决策并给出兼容安全路径最后一条 expectation 是行为评测区别于检查代码能不能跑的关键它评分的是Agent 是否尊重了需求文档的边界——简介特意留出三个未决问题就是在测试模型会不会好心办坏事地把未决项直接实现掉。五、小结与延伸阅读这份 19 行的服务简介是 agent-skills 仓库用真实项目输入评测技能行为思路的一个缩影fixture 提供约束与陷阱evals/cases/api-and-interface-design.json 定义 prompt 与可核验的评分项skills/api-and-interface-design/SKILL.md 提供设计原则与红旗清单scripts/run-evals.js 与 evals/README.md 则把整个过程变成可重复、CI 可运行的评测管线。对读者而言可复用的是三层东西一是未决事项显式化的需求文档写法二是从约束到契约的推导顺序命名 → 错误语义 → 边界校验 → 兼容策略三是 SKILL.md 末尾的 Verification 检查清单skills/api-and-interface-design/SKILL.md可作为任何公开接口设计完成后的自查表。进一步阅读建议evals/README.md三层评测体系与运行方式、skills/deprecation-and-migration/SKILL.md已发布行为的退役流程、references/definition-of-done.md完成度标准。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
