@antprofuse/saddle-islands-design 0.1.14 → 0.1.15

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: saddle-islands-design
-description: 消费 Islands Spec 与 adapt，设计 Saddle 后端服务契约和逻辑数据库表，可独立或联合设计并审查一致性。不修改业务Spec或猜填适配逻辑，不实现业务代码、外部RPC或数据库部署。
+description: 消费 Islands Spec 与自洽 adapt，设计后端契约、逻辑数据库表及 Saddle与profusecontract的external-contract-proto，可独立或联合设计并审查边界一致性。不猜填适配逻辑，不实现业务代码或部署。
 ---
 
 # Saddle Islands 设计
 
-Spec定义抽象业务，adapt补充落地输入，后端契约与DB是输出。先推导自洽的设计，再以格式准确承载；不能让业务Spec为工具格式增加技术字段。后端契约不是Dependency出口协议，profusecontract实现不是本模块前置。
+Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill消费两层输入产出后端契约、DB和external-contract-proto。不能让业务Spec为工具格式增加技术字段。后端聚合契约与外部能力契约不是一一对应；适配语义须先确定，但profusecontract实现代码不是设计前置。
 
 ## 选择模块
 
@@ -15,17 +15,18 @@ Spec定义抽象业务，adapt补充落地输入，后端契约与DB是输出。
 | --- | --- | --- |
 | 后端契约 | [设计流程](modules/backend-contract/design.md)、[格式](modules/backend-contract/references/backend-contract-v1.md)、[覆盖规则](modules/backend-contract/references/coverage.md) | `*.backend-contract.yaml` |
 | DB | [设计流程](modules/db/design.md)、[表格式](modules/db/references/db-table-v1.md) | `*.table.yaml` |
-| 联合设计 | 上述两组 | 独立文件，做跨层复核 |
+| external-contract-proto | [外部协议设计](modules/external-contract-proto/design.md)、[运行时边界](modules/external-contract-proto/references/runtime.md) | 共同消费的业务 `.proto` |
+| 联合设计 | 所选模块的完整参考 | 独立交付，做跨层复核 |
 
 有来源问题时读对应模块findings参考；模板在模块assets。一个Skill、一个版本，模块不是另一个安装包。
 
 ## 输入与协作
 
 - 明确Spec仓库与目录、adapt位置、交付仓库与目录，仓库和目录分别记录；上下文已明确的不重复询问。adapt通常与spec、code同级，但必须检查实际存在，不猜内容。Spec、adapt都属于输入；缺失声明不能由设计Agent默认生成。
-- 后端契约另需完整业务前缀；DB不需要。输出建议分别为code/backend-contract、code/db，以用户指定为准。不要求实现语言、生成配置、外部RPC合同作为额外输入。
+- 后端契约另需完整业务前缀；DB不需要。默认交付code/backend-contract、code/db、code/external-contract-proto，与backend并列，以用户指定为准。外部协议还需目标Saddle协议版本及业务单元实际值，已有输入足够时不重复询问，不从MobileGW前缀猜业务单元。不要求先提供生成代码或SOFA物理合同替代adapt。
 - 记录实际输入分支及commit。无版本约束时读取远程默认分支，不猜master/main；Islands默认参考仓库为https://code.alipay.com/profuse/islands。工具不可访问或不兼容不等于Spec业务缺失。
 - 通读所选范围的Spec、adapt及相关Islands指南，检查Prototype与测试责任。元数据不可用时可做来源有据的推演，不能虚报编译、覆盖或测试通过。
-- 逐项讨论真正影响设计的歧义，不以推测补业务事实。已授权完整设计时继续不受影响部分，不要求所有适配实现先完成。
+- 所选范围的adapt语义自洽后进入正式设计。缺失身份、取数能力、字段形状或业务结果语义时退回讨论，不由本Skill补齐。普通代码尚未实现不是阻塞；用户另行授权的局部草稿不宣称整体交付完成。
 - 普通消费Agent发现规范缺口应反馈维护者，不私造规则；获得Skill维护授权的设计者先给出合理设计供确认，再修通用规则，不把旧Skill能力当业务限制。
 - Findings只记录Spec业务缺失或矛盾；adapt待定项、规范缺口、消费者迁移问题分别说明，不倒逼Spec改成物理流程。
 - 交付目录仅放有效契约，不放过程记录、检查脚本或findings。用户授权替换时清掉本范围旧设计文件，不并存冲突真源；不越权删除实现代码，也不宣称消费者自动兼容。
@@ -38,8 +39,10 @@ Spec定义抽象业务，adapt补充落地输入，后端契约与DB是输出。
 
 共同核对完整实体属性（Spec+adapt扩展）、实例归属、身份方式、金额单位和可空性。关联跟随目标身份，不能统一假设uid。DB宽松存储约束不能放宽后端契约成功结果；后端结果投影不要求复制全部数据库列。
 
-两类设计完成不等于适配实现、前后端测试或生产链路完成。具体绑定内容由用户或其授权的实现者填写，不从TODO发明加载、同步或对外调用。
+external-contract-proto覆盖adapt明确交给profusecontract的Dependency及external-contract，字段类型引用应解析为具体传输字段；不能因为类型相同就猜某个实例的值。正常调用与组装由backend研发依据业务和绑定完成，不要求额外编排配置。跨层核对空值、精度、单位和失败语义，不把前端JSON信封复制到外部函数result。
+
+三类设计完成不等于实现、测试或生产链路完成。不从TODO发明加载、同步或对外调用；不修改profusecontract后面不可控的SOFA协议。
 
 ## 维护边界
 
-目前仅后端契约与DB两个模块。新增模块须确认职责，不提前预建。版本默认只递增0.1.x的patch。保持已批准的约定，清理失效规则，避免把单个业务案例固化成通用设计。保留包外未批准草稿，不混入发布。
+当前三个模块为后端契约、DB、external-contract-proto；adapt设计由并列的saddle-islands-adapt负责。版本只递增最末位0.1.x的patch，未经明确要求不升前两位。保持已批准约定，不把单个案例固化成通用设计；保留包外未批准草稿。

package/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Saddle Islands Design"
-  short_description: "消费 Islands Spec 与 adapt，统一设计后端契约与逻辑数据库表"
+  short_description: "消费自洽 adapt 与 Spec，设计后端契约、数据库及外部协议"

package/modules/backend-contract/design.md

@@ -20,4 +20,4 @@
 - 字段省略不等于null，零金额不等于空结果，查询失败不等于无业务数据。展示文案、时间格式化和页面组织归前端。
 - 一般按Prototype+测试所需字段投影；用户确认简单实体字段扩展保留倾向时可保留，但注明来源与扩展理由，不声称页面已消费，不据此暴露敏感或内部路由事实。
 - 技术错误与非技术失败边界必须互斥。未定义业务结果可按用户确认隔离并记录问题，不借错误码硬补已要求的业务语义。
-- adapt的具体转换TODO不是自动阻塞；只对真正依赖它且无法唯一确定的字段或结果反馈。设计可完成不代表链路实现完成。
+- 正式设计要求本范围adapt语义自洽；未写代码不阻塞，TODO仍决定数据来源或结果含义则先反馈。局部草稿不等于正式交付。能力已经明确时，正常调用组装属于backend研发，不要求另交编排程序。

package/modules/external-contract-proto/design.md

@@ -0,0 +1,33 @@
+# External Contract Proto 设计
+
+先完整阅读[运行时边界](references/runtime.md)。本模块将自洽adapt的外部能力转成Saddle与profusecontract共同遵守的业务protobuf契约，不定义SOFA协议，也不把前端综合查询原样复制为出口函数。
+
+## 输入与范围
+
+- 消费Spec、实体承载/扩展/身份、Dependency及external-contract绑定。绑定来源不同，适配协议定义要求相同；不额外包装一层转发RPC。
+- 确认目标Saddle版本及权威proto，明确业务单元实际值。默认交付code/external-contract-proto，与backend并列。旧目录迁移须获项目授权并同步双方消费路径，不保留两份真源；Skill升级不自动迁移项目。
+- 用户未提供生成语言不是阻塞。业务方法身份与语言标识符分开，不要求backend先写代码再设计出口协议。
+- 读取已发布的共享协议，不从旧生成代码推导新规范；版本不一致先报告。不能因为仓库里同时存在puc和business_unit就兼容两套身份。
+
+## 设计过程
+
+1. 列出本范围明确由profusecontract承载的能力及其真实绑定目标。核对实体外部承载的名称唯一性，避免重复生成同一函数。
+2. 逐输入、输出解析实体字段类型，包括adapt扩展和身份。记录绑定文件、业务域、能力、字段路径及对应proto字段，采用proto注释保存设计关联，不增加线上来源字段或自造protobuf extension。
+3. 用具体具名request/result及必要嵌套message表达已确定的输入输出。proto需要合法标识符，中文业务名称与实体字段通过注释保留关联；同类型不是同实例，不扩展成整实体快照。
+4. 核对字段presence、空串/零、空集合、无对象、业务失败和技术异常。proto3默认值不是业务默认，不能让缺失悄悄成为0或空字符串。按目标runtime支持的presence能力表达；输入没有决定的对象整体可空或联合结构先退回讨论。
+5. 保留金额精度、日期与时刻语义、枚举及合法范围。不得默认double、按DB分存储反推外部金额单位、按前端JSON格式推断外部编码。协议编码存在多个可行选择而影响跨端正确性时，提供具体候选让用户确认再固化。
+6. 按目标method option绑定身份，0.3.15采用puc+function，puc值由业务确定。deadline、trace/LDC及技术异常走框架边界，下游所需用户ID是明确的业务request字段，不是通用context。字段由adapt确定，不照搬SOFA模型、类名、重试或容量默认值。
+7. 编译同一份proto及权威imports，检查descriptor中函数身份、request/result、字段号和presence。对已有契约比较descriptor及bytes hash；不得复用已删字段号、改变既有字段含义或让两端各自演化。
+
+## 交付门槛
+
+- 每个生成字段可解析到adapt字段及有效实体定义，不丢字段，不凭SOFA响应增字段。
+- 每个绑定要求的结果形状都可表达；资料缺失与调用失败不合并。部分成功策略来自adapt，不由proto设计决定。
+- request/result封闭可有界，静态上限须明确，不填任意常量，也不靠“以后实现决定”声称已可交接。未决定的边界条件报告，不声称已通过运行期验证。
+- 输出唯一契约树：原样固定根模板及业务proto。模板由目标Saddle提供，不修改为业务私有版本。生成代码、部署、SOFA实现、conformance脚本不属于本模块交付。
+- 交接记录proto相对路径、原始bytes SHA-256、package/service/rpc及业务身份，记录输入和runtime版本；过程检查放协作记录，不为了日志在交付目录建第二套协议清单。
+- proto编译成功、两端生成成功、conformance通过和真实联调分别举证；没执行的不要宣称通过。语义或目标runtime未明确只能给候选草稿，不能发布可直接研发的正式协议。
+
+## 与其他设计复核
+
+后端综合契约可以汇总多个外部函数；DB只有明确本地承载实体的表。非持久化返回值不建表，外部函数不要求前端额外传内部身份。各边界允许不同编码，但转换必须可准确实现且语义有依据。backend负责按需求调用与组装，不由本模块生成调用顺序或隐式加载计划。

package/modules/external-contract-proto/references/runtime.md

@@ -0,0 +1,34 @@
+# 运行时协议依据
+
+已核对基线为npm包 `@antprofuse/saddle-skill@0.3.15`，不是本地未同步源码。使用项目明确的目标版本，不默认升级运行时。执行前取得精确版本包，完整阅读 references/external-function-contracts.md、references/consumer-start.md、references/validation.md 和两个固定模板。包不可取得时反馈，不手写替代。安装位置不要求在业务目录。
+
+## 固定模板和共享目录
+
+包内 assets/saddle_external_function.proto 与 assets/saddle_call_context.proto 由Saddle拥有定义权。design将其原样写入唯一contract_dir根部，不改名、不改bytes、不另造extension。本Skill不维护第二份模板。
+
+默认目录为 code/external-contract-proto，与backend、backend-contract、db并列。目录树是双方共同输入，包含固定根模板和业务proto；不建聚合proto、手工proto清单、protocol子目录或版本副本。只有带正式method option的RPC进入外部函数索引。
+
+业务proto精确 import "saddle_external_function.proto";，使用 (saddle.profusecontract.external_function)，字段为 puc 与 function。
+
+- puc是固定字段名，其值是项目确认的业务单元，不固定为字符串puc；例如bill可以按确认填bill。
+- backend DSL business_unit与option的puc值逐字一致，不把option字段改名business_unit。
+- function保留adapt契约原名，可中文；package/service/rpc合法技术名字不替代业务身份。
+- 不支持alias、fallback、动态函数或多版本路由。
+
+网络仍走固定ProfuseContractBoundary/Invoke unary，业务service/rpc不要求新增同名网络端点。
+
+## 上下文和数据
+
+技术context只自动传播trace/rpc、LDC和deadline，绝无通用user_id。下游需要用户ID时，adapt明确具体业务输入，proto显式声明，backend从可信入站上下文赋值；不向小程序索要，不默认复制，也不一律禁止下游业务身份字段。
+
+技术异常由框架TechnicalFailure承载，不进入业务result，不复制前端响应信封。前端信封与backend错误策略是另一层；发现不一致先报告，不在接管proto时静默修改其他模块。
+
+request/result具名、封闭且可有界；禁止Any、开放map、任意JSON和裸bytes业务对象。字符串、bytes、集合、嵌套须有明确静态上限；不填任意容量默认值，未明确不能宣称已可供Saddle实现。框架payload bytes不授权业务绕过schema。
+
+## 职责迁移与验收
+
+design负责定义并冻结完整契约树。Saddle消费它，负责编译期递归扫描/import闭合、option-only索引、强类型生成、functions/uses及正式Gate。用户另安排Saddle团队移除重复定义职责并支持backend外引用；本Skill升级不表示旧Gate和项目配置自动兼容，须由该团队版本和验收证明。
+
+核对presence区分缺失与空串/0、空对象与空集合、枚举未知值、整数范围及金额精度。复杂adapt形状未定先退回讨论，不靠proto创造语义。金额/日期无权威编码时先给具体候选确认。
+
+protoc编译、两端conformance和真实联调分别举证，不把可解析冒充可实现。固定模板须逐字一致。不要混入本地旧资料的business_unit option、不同import路径或下游通用用户context。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antprofuse/saddle-islands-design",
-  "version": "0.1.14",
-  "description": "消费 Islands Spec 与 adapt，统一设计 Saddle 后端服务契约与逻辑数据库表。",
+  "version": "0.1.15",
+  "description": "消费自洽 adapt 与 Islands Spec，设计后端契约、数据库表和 external-contract-proto。",
   "license": "MIT OR Apache-2.0",
   "files": ["SKILL.md", "agents", "modules", "references"],
   "publishConfig": {

package/references/adapt.md

@@ -1,10 +1,10 @@
 # adapt输入与身份规则
 
-两模块共用。adapt是Spec到code之间的明确设计输入，不是Islands运行时语法，也不是Saddle表列名映射。读取它不表示已实现转换或编译器已支持。
+三模块共用。adapt是Spec到code之间的明确设计输入，不是Islands运行时语法，也不是Saddle表列名映射。读取它不表示已实现转换或编译器已支持。设计模块消费已经自洽的adapt，不接管适配事实的发明。
 
 ## 输入结构与职责
 
-常见结构为同级spec、adapt、code；adapt含ingress.binding.yaml、entities/实体名.binding.yaml、dependencies/依赖名.binding.yaml。位置以调用方指定为准，每个实体、每个Dependency独立文件；ingress以目标板块和入口定位条目。不把Islands旧physical.yaml与adapt自动合并，也不由同名猜优先级。发现同范围冲突先反馈。
+常见结构为同级spec、adapt、code；adapt含ingress.binding.yaml、entities/实体名.binding.yaml、dependencies/依赖名.binding.yaml、external-contract/名称.binding.yaml。位置以调用方指定为准，每项独立文件；ingress以目标板块和入口定位条目。不把Islands旧physical.yaml与adapt自动合并，也不由同名猜优先级。发现同范围冲突先反馈。
 
 所有实体都应有显式承载及身份声明。承载与身份属于adapt，不要求Spec理想实体写external、技术主键或外部编码。没有实际写操作不代表不建表；一次对象属性读取也不代表DB或RPC调用。声明缺失先问，不允许消费者隐含推导。
 
@@ -80,11 +80,17 @@
 
 后端契约请求字段只能来自实体属性（含扩展）或ingress外部入参。字段允许向后传递而不归属实体属性；必须保留来源含义和类型，不因为后端需要就新增客户端参数。非null不隐含trim、空串拒绝、缺省值或其他校验政策。系统可信身份不进入业务请求或context段。
 
-TODO只影响它真正决定的内容。若只缺具体加载实现而请求、结果可确定，继续设计；若缺失会决定字段、实例归属、合法结果或持久化结构，先反馈，不拿“并行”当作猜填许可。
+进入正式设计前区分：普通代码未写不影响语义自洽；TODO仍决定字段、取数依据、身份、合法结果或持久化结构则输入未闭合，须反馈。用户授权局部草稿时可做已确定部分，不当作正式完整交付。
 
 ## Dependency边界
 
-每份Dependency绑定指向正式依赖，输入与返回显式声明实体类型及来源约束；返回集合使用实体+集合声明，空值仅在来源明确时允许。其实现可由用户留TODO。非持久化对象可仅作为Dependency实参，不代表存在该实体自己的外部CRUD。Dependency实现、profusecontract协议及调用细节不写入后端契约或表结构。
+Dependency与external-contract只在逻辑锚点上不同：前者目标指向Spec依赖，后者可由实体的外部承载名称引用。两者使用字段级输入、输出及长文本逻辑，不沿用整实体输入/返回的旧接口形状，也不要求前者必须再调用后者。
+
+字段的`类型: 实体名.字段名`是数据类型引用，不是来源或取值路径；解析Spec属性、adapt扩展及已声明的`实体名.主键`，不能重复一个可能冲突的基础类型，也不能从该引用推导实例关联。复杂结构必须由输入契约自身明确；缺失时退回adapt确认，不由design发明组合语义。
+
+实体可声明`外部承载: [{名称: 查询资料}]`，精确引用同业务域external-contract；不重复输出映射，缺失或重名应报告。它声明能力，不触发自动加载。非持久化对象仅作为实参不代表存在外部CRUD。后端代码根据Spec消费需要和契约使用能力，外部取数资料不足才是盲区，尚未写组装代码不是。
+
+后端契约可以聚合多个结果；profusecontract能力按职责划分，不机械一一对应。逻辑或实体绑定明确需要的外部能力进入external-contract-proto，具体SOFA调用逻辑不混入后端契约、表或proto。
 
 ## 来源定位