@antprofuse/saddle-islands-design 0.1.16 → 0.1.19

package/SKILL.md

@@ -5,6 +5,8 @@ description: 消费 Islands Spec 与自洽 adapt，设计后端契约、逻辑
 
 # Saddle Islands 设计
 
+开始先安装并完整阅读 `@antprofuse/saddle-workflow@latest` 的共同规则。所有 Skill 间引用统一从 npm 官方 registry 使用 `@latest`，不写死版本；记录本轮实际解析版本及摘要，同一协作批次保持一致，不在执行途中漂移。引用未发布或无法取得时明确反馈，不能静默使用本地草稿。自身 package 版本和格式版本不受此规则影响。
+
 Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill消费两层输入产出后端契约、DB和external-contract-proto。不能让业务Spec为工具格式增加技术字段。后端聚合契约与外部能力契约不是一一对应；适配语义须先确定，但profusecontract实现代码不是设计前置。
 
 ## 选择模块
@@ -24,7 +26,7 @@ Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill
 
 - 明确Spec仓库与目录、adapt位置、交付仓库与目录，仓库和目录分别记录；上下文已明确的不重复询问。adapt通常与spec、code同级，但必须检查实际存在，不猜内容。Spec、adapt都属于输入；缺失声明不能由设计Agent默认生成。
 - 后端契约另需完整业务前缀；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理念参考仍可读取其官方指南；这不是项目契约跨仓库关联。
 - 通读所选范围的Spec、adapt及相关Islands指南，检查Prototype与测试责任。元数据不可用时可做来源有据的推演，不能虚报编译、覆盖或测试通过。
 - 所选范围的adapt语义自洽后进入正式设计。缺失身份、取数能力、字段形状或业务结果语义时退回讨论，不由本Skill补齐。普通代码尚未实现不是阻塞；用户另行授权的局部草稿不宣称整体交付完成。
 - 普通消费Agent发现规范缺口应反馈维护者，不私造规则；获得Skill维护授权的设计者先给出合理设计供确认，再修通用规则，不把旧Skill能力当业务限制。
@@ -43,6 +45,14 @@ external-contract-proto覆盖adapt明确交给profusecontract的Dependency及ext
 
 三类设计完成不等于实现、测试或生产链路完成。不从TODO发明加载、同步或对外调用；不修改profusecontract后面不可控的SOFA协议。
 
+## 交给测试与实现
+
+设计交接应让下游独立得到：当前调用点和物理输入、完整结果/错误合同、来源责任、外部能力协议、持久化结构，以及尚未完成事项所影响的具体边界。真实 SOFA 或 Java 实现尚未完成不自动阻塞前端契约 Mock、后端 Invoke Mock 测试；只有影响当前协议或预期的未定语义才阻塞对应场景。
+
+前端测试消费 Spec/Prototype、adapt、backend-contract；后端测试还消费 DB 与 external-contract-proto。两者根据当前 Islands 正式责任清单分别落实可观察义务，不按设计文件数量反推覆盖。数据库实例、DDL、测试物理名映射、seed 和启动接入由测试建设承担，不塞入 `code/db/`，也不留给产品研发补测试 adapter。
+
+共享协议是唯一真源，但“一致性审查”不授权修改所有消费者。只迁移本次获授权的设计或实现目录，其他消费者差异单独报告；Mock 验收与真实下游兼容验收分别记录。删除 backend 内旧协议副本，不等于需要同步编写 Java 适配实现。
+
 ## 维护边界
 
 当前三个模块为后端契约、DB、external-contract-proto；adapt设计由并列的saddle-islands-adapt负责。版本只递增最末位0.1.x的patch，未经明确要求不升前两位。保持已批准约定，不把单个案例固化成通用设计；保留包外未批准草稿。

package/modules/backend-contract/references/backend-contract-v1.md

@@ -120,14 +120,14 @@ Visual Form 的宽泛类型不自动构成业务类型冲突：应追溯真实
 - kind: flowEntry
   flow: {board: 查询账单, entry: 开始查询}
   ingress:
-    path: example/adapt/ingress.binding.yaml
+    path: example/adapt/ingress/开始查询.binding.yaml
     domain: 示例域
     board: 查询账单
     entry: 开始查询
   inputBindings:
     账户编号:
       ingressField:
-        path: example/adapt/ingress.binding.yaml
+        path: example/adapt/ingress/开始查询.binding.yaml
         domain: 示例域
         board: 查询账单
         entry: 开始查询
@@ -284,7 +284,7 @@ cases:
 # 输入专用；仅source多一个kind，inputBindings.ingressField不带kind。
 source:
   kind: ingressField
-  path: example/adapt/ingress.binding.yaml
+  path: example/adapt/ingress/开始查询.binding.yaml
   domain: 示例域
   board: 查询账单
   entry: 开始查询

package/modules/backend-contract/references/coverage.md

@@ -10,9 +10,9 @@
 
 `coverage` 为非空数组，每项必填且只允许 `id / prototypes / tests / obligations`。id 是文件内唯一的稳定语义标识，不使用数组序号。
 
-- prototypes：Prototype 来源数组，每项必填且只允许 `repository / revision / path / selector`。
-- tests：测试来源数组，同样四个必填键。selector 为真实测试责任/case ID；脚本没有独立 ID 时用文件内唯一的完整测试名称，不自创 ID。
-- repository：实际输入仓库地址；revision：固定完整 Git commit；path：仓库根目录相对文件路径；selector：该版本内可唯一解析的页面/组件/动作/状态或测试身份。禁止仅用行号、数组下标或样例别名。可由四者生成固定版本源码链接，不额外保存漂移的 master 链接。原型与测试可在不同仓库或不同文件。
+- prototypes：Prototype 来源数组，每项必填且只允许 `path / selector`。
+- tests：测试来源数组，同样两个必填键。selector 为真实测试责任/case ID；脚本没有独立 ID 时用文件内唯一的完整测试名称，不自创 ID。
+- path：当前仓库根目录相对文件路径；selector：当前分支内可唯一解析的页面/组件/动作/状态或测试身份。所有关联只解析当前仓库当前分支，禁止跨仓库、跨分支或固定历史版本定位；不接受仓库地址、分支名或提交号等额外键。禁止仅用行号、数组下标或样例别名。
 - 每项 prototypes/tests 至少一个非空；每份后端契约两类来源都必须非空。原型独有显示责任可无 tests，测试独有边界责任可无 prototypes，但必须参与全量核对，不能人为删空掩盖已有对应来源。
 - obligations：非空数组。每项必填且只允许 `aspect / requirement / targets / explanation`。
 - aspect：封闭枚举 `input / output / constraint / frontend`。requirement 是来源中具体操作、展示或断言的准确含义；不是另造需求。explanation 说明目标如何完整支撑该责任，含必要前置事实和适用条件。
@@ -24,14 +24,10 @@
 coverage:
   - id: non_service_hours
     prototypes:
-      - repository: <原型仓库>
-        revision: <完整commit>
-        path: <原型文件>
+      - path: <原型文件>
         selector: <非服务时段分支的真实身份>
     tests:
-      - repository: <测试仓库>
-        revision: <完整commit>
-        path: <测试文件>
+      - path: <测试文件>
         selector: <非服务时段测试的真实case ID>
     obligations:
       - aspect: output
@@ -55,9 +51,9 @@ coverage:
 
 1. 从实际 Prototype 和测试责任清单取得指定范围的完整分母，不能从已经写出的后端契约反推分母。逐项辨认前置事实、动作、预期显示、断言、禁止副作用和后续交互。纯样式/导航等纯前端责任明确分类，不为覆盖它们造后端契约。
 2. 每个后端契约的 coverage 只声明本接口承担的部分。同一用例涉及多个后端契约时，各自映射其负责的操作/断言，按相同来源身份汇总后证明整条用例被支撑；不共享业务 schema，也不要求一用例一接口。
-3. 对每条关联实际推演：动作值能否形成合法 input；系统身份是否仍由系统提供；预期结果是否落到正确输出分支；字段、枚举、nullable、顺序和关联是否足够；写入/不写入及后续页面行为是否符合预期。仅验证 URL/selector/target 存在不算语义覆盖。
+3. 对每条关联实际推演：动作值能否形成合法 input；系统身份是否仍由系统提供；预期结果是否落到正确输出分支；字段、枚举、nullable、顺序和关联是否足够；写入/不写入及后续页面行为是否符合预期。仅验证 path/selector/target 存在不算语义覆盖。
 4. 反向检查各调用点、业务结果、叶字段及约束可追溯到两类基准的需求或为满足它们所必需的实体投影。系统通用信封遵守既有规范，不为其伪造业务测试。Form/Rule 来源规则保持，但不能借机自造实体、展示包装或技术字段。有限样例不定义完整枚举。
 5. 汇总所有后端契约的关联，检查输入分母的所有项。完全独立且无需后端契约的纯前端项在交付 review 中逐项说明，无需为其创建空后端契约文件；消费当前后端契约输出的后续前端项留在该文件 coverage 内。未覆盖责任和冲突在过程反馈中列明，不能把缺口写成“已覆盖”或以 fail-closed 错误替代已要求的业务结果。
-6. Prototype 或测试更新时重核对应 revision/selector 和 obligations，后端契约 schema 变化时重核 targets 和覆盖语义；不能只更新 commit 字符串。固定版本关联是追溯依据，不允许用旧版本清单宣称覆盖新的输入。
+6. Prototype 或测试更新时，在当前分支重新核对path/selector与obligations；后端契约schema变化时重核targets和覆盖语义。关联随当前分支内容共同演进，不通过固定历史快照规避输入变化。
 
 设计完备表示当前指定 Prototype 与测试用例全部得到支撑，并且字段业务来源、协议类型等契约检查成立。不是已完成生产实现、测试已运行或所有业务理论情况被穷举。来源缺失、冲突或无法定位时，不自行扩充所有 Spec 需求或补写测试来制造完备；报告并继续不受影响部分。

package/modules/db/references/db-table-v1.md

@@ -154,7 +154,7 @@ v1 只允许以下封闭类型：
 
 ## 已声明的持久访问责任
 
-accessResponsibilities记录当前输入明确的直接持久操作，不是完整后端执行计划。没有可定位的直接操作可为[]；不代表表不会被访问、没有价值或禁止实现加载。不能因此省略明确的本地持久化表。已知操作不能遗漏，未填写adapt实现不能被猜成按编码查询或同步任务。
+accessResponsibilities记录当前输入明确的直接持久操作，不是完整后端执行计划。没有可定位的直接操作可为[]；不代表表不会被访问、没有价值或禁止实现加载。不能因此省略明确的本地持久化表。已知操作不能遗漏，不凭未填写的适配内容发明查询或同步任务；入口已明确将字段映射为本地实体属性时，等值定位已有依据，不再要求额外 SQL 或查询步骤声明。唯一性、查无与多命中仍按已有合同核对，不任取首项。
 
 每项必需source/operations，可选backendContractId/atomic。source只采用当前Graph/Visual稳定身份：
 

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

@@ -5,7 +5,7 @@
 ## 输入与范围
 
 - 消费Spec、实体承载/扩展/身份、Dependency及external-contract绑定。绑定来源不同，适配协议定义要求相同；不额外包装一层转发RPC。
-- 确认目标Saddle版本及权威proto，明确业务单元实际值。默认交付code/external-contract-proto，与backend并列。旧目录迁移须获项目授权并同步双方消费路径，不保留两份真源；Skill升级不自动迁移项目。
+- 确认目标Saddle版本及权威proto，明确业务单元实际值。默认交付code/external-contract-proto，与backend并列。旧目录迁移须获项目授权，不保留两份真源；核对双方消费路径，实际修改限于本次授权范围，其他消费者迁移单列交接，不为 Mock 验收扩大到真实下游实现。Skill升级不自动迁移项目。
 - 用户未提供生成语言不是阻塞。业务方法身份与语言标识符分开，不要求backend先写代码再设计出口协议。
 - 读取已发布的共享协议，不从旧生成代码推导新规范；版本不一致先报告。不能因为仓库里同时存在puc和business_unit就兼容两套身份。
 

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

@@ -8,7 +8,7 @@
 
 默认目录为 code/external-contract-proto，与backend、backend-contract、db并列。目录树是双方共同输入，包含固定根模板和业务proto；不建聚合proto、手工proto清单、protocol子目录或版本副本。只有带正式method option的RPC进入外部函数索引。
 
-对支持同级目录的Saddle版本，backend可声明 `contract_dir "../external-contract-proto";`，相对应用Cargo.toml所在目录而非shell。构建与CI必须取得固定revision的完整契约树；根目录定位允许上行不代表proto import允许逃逸，目录不得经symlink。具体限制核对选定版本。目录外引用支持与研发Skill停止生成proto是两项独立检查，不能因前者成立就宣称后者完成。
+对支持同级目录的Saddle版本，backend可声明 `contract_dir "../external-contract-proto";`，相对应用Cargo.toml所在目录而非shell。构建与CI消费当前分支同次检出的完整契约树，执行记录可以保留实际提交和摘要用于复现，但不在业务契约中增加 revision 定位字段或另锁历史来源。根目录定位允许上行不代表proto import允许逃逸，目录不得经symlink。具体限制核对选定版本。目录外引用支持与研发Skill停止生成proto是两项独立检查，不能因前者成立就宣称后者完成。
 
 业务proto精确 import "saddle_external_function.proto";，使用 (saddle.profusecontract.external_function)，字段为 puc 与 function。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-islands-design",
-  "version": "0.1.16",
+  "version": "0.1.19",
   "description": "消费自洽 adapt 与 Islands Spec，设计后端契约、数据库表和 external-contract-proto。",
   "license": "MIT OR Apache-2.0",
   "files": ["SKILL.md", "agents", "modules", "references"],

package/references/adapt.md

@@ -4,7 +4,7 @@
 
 ## 输入结构与职责
 
-常见结构为同级spec、adapt、code；adapt含ingress.binding.yaml、entities/实体名.binding.yaml、dependencies/依赖名.binding.yaml、external-contract/名称.binding.yaml。位置以调用方指定为准，每项独立文件；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调用。声明缺失先问，不允许消费者隐含推导。
 
@@ -63,17 +63,16 @@
 
 ```yaml
 业务域: 示例域
-入口:
-  - 目标: {板块: 查询账单, 入口: 开始查询}
-    外部入参:
-      subBizType:
-        类型: string
-        可空: false
-    实体映射:
-      缴费账户: {实体: 缴费账户}
-    适配: |
-      subBizType 可映射 @费种(主键=$subBizType)
-      TODO：由用户填写其余适配逻辑。
+目标: {板块: 查询账单, 入口: 开始查询}
+外部入参:
+  subBizType:
+    类型: string
+    可空: false
+实体映射:
+  缴费账户: {实体: 缴费账户}
+适配: |
+  subBizType 可映射 @费种(主键=$subBizType)
+  TODO：由用户填写其余适配逻辑。
 ```
 
 入口描述外部字段到内部实体体系的关系，不是函数返回值。实体映射必须与Spec目标入口类型一致；集合等基数必须有输入声明，不能猜测。适配允许自然语言与上述轻量记号混合，不宣称有可执行表达式解释器。
@@ -94,6 +93,8 @@ Dependency与external-contract只在逻辑锚点上不同：前者目标指向Sp
 
 ## 来源定位
 
-本版本的path均为已指定输入仓库根目录相对路径，不是shell工作目录或URL。实体类型在业务域内解析；歧义不能按同名猜。不同来源仓库必须先明确解析上下文，不能把Spec仓库相对路径用于另一个仓库。
+本版本的path均为已指定输入仓库根目录相对路径，不是shell工作目录或URL。实体类型在业务域内解析；歧义不能按同名猜。项目关联只解析当前仓库当前分支，不承载跨仓库或跨分支定位。
+
+实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。关联随当前分支的Spec+adapt内容重新核对。
 
-实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。契约版本跟随Spec+adapt内容重新核对，不只替换commit字符串。
+入口按每个绑定一个文件交付，顶层为业务域、目标、外部入参、实体映射、适配，不使用入口数组。文件名优先为入口名.binding.yaml；同名入口冲突时以板块名限定文件名，身份仍由业务域和目标确定。仅接受新形状，迁移时同步所有path引用，不保留旧聚合文件或双读规则；保持既有适配逻辑原文。