用途:指导在 asc-swift(App Store Connect CLI)中实现新功能,遵循架构优先设计、测试驱动开发(TDD)、富领域模型与 Command Affordances 模式。
主要能力与流程:
- 架构设计(强制,需用户批准):从用户心智模型出发识别领域模型与命令,绘制三层 ASCII 图并填写组件表,用 AskUserQuestion 让用户选择 Approve 或 Modify,未批准前不写代码。
- TDD 实现:先写失败测试,再写实现。顺序为领域测试→基础设施测试→命令测试。领域层包含值类型、AffordanceProviding 与 @Mockable 协议;基础设施层为 SDK 适配器,注入父 ID 并组合多次调用;命令层用 formatAgentItems 输出 {"data":[{...,"affordances":{...}}]}。
- REST 暴露(功能未通过 REST 可达即未完成):为 execute(repo:) 增加 affordanceMode 参数,在 Sources/ASCCommand/Commands/Web/Controllers/ 添加控制器,在 RESTRoutes.swift 注册路由,并确认父资源 _links 已填充。
- 文档:docs/features/<feature>/README.md(面向用户,≤200 行)、CHANGELOG 一行、运行 make docs。
关键设计规则:优先使用 structuredAffordances 作为单一事实来源,CLI 字符串与 REST _links 均自动派生,不要直接覆盖 apiLinks;REST 路由需在 RESTPathResolver.ensureInitialized() 中注册;领域模型需 Sendable、Equatable、Identifiable、Codable 并携带父 ID;仓库协议方法保持原子性,适配器内可组合多次 ASC API 调用(如 Apple include=foo 截断约 10 条时改用专用关系端点并显式 limit)。
测试规则:测试名描述用户期望,始终使用 #expect(),断言完整 JSON 字符串而非 contains,覆盖边界情况。
限制:资料未提供具体安装命令、收费信息或平台支持范围;部分内容(如 references 文件、CLAUDE.md)仅被引用,未给出完整细节。