@antprofuse/saddle-islands-design 0.1.15 → 0.1.17

package/SKILL.md

@@ -24,7 +24,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能力当业务限制。

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/external-contract-proto/design.md

@@ -16,7 +16,7 @@
 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模型、类名、重试或容量默认值。
+6. 按实际选定版本的method option绑定身份，核对puc+function规则，puc值由业务确定。deadline、trace/LDC及技术异常走框架边界，下游所需用户ID是明确的业务request字段，不是通用context。字段由adapt确定，不照搬SOFA模型、类名、重试或容量默认值。
 7. 编译同一份proto及权威imports，检查descriptor中函数身份、request/result、字段号和presence。对已有契约比较descriptor及bytes hash；不得复用已删字段号、改变既有字段含义或让两端各自演化。
 
 ## 交付门槛

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

@@ -1,6 +1,6 @@
 # 运行时协议依据
 
-已核对基线为npm包 `@antprofuse/saddle-skill@0.3.15`，不是本地未同步源码。使用项目明确的目标版本，不默认升级运行时。执行前取得精确版本包，完整阅读 references/external-function-contracts.md、references/consumer-start.md、references/validation.md 和两个固定模板。包不可取得时反馈，不手写替代。安装位置不要求在业务目录。
+默认使用npm官方registry的 `@antprofuse/saddle-skill@latest`，不在本Skill写死Saddle版本。执行时查询latest并安装，记录实际解析版本及摘要，本轮统一消费该版本，不在执行途中漂移。用户明确指定版本时遵从用户；既有项目运行时与最新版不一致时报告迁移差异，不擅自改Cargo依赖。完整阅读实包的SKILL.md、references/external-function-contracts.md、references/consumer-start.md、references/validation.md和两个固定模板；实包与本地旧资料冲突以选定实包为准，协议变化先反馈。包不可取得时不手写替代。安装位置不要求在业务目录。
 
 ## 固定模板和共享目录
 
@@ -8,6 +8,8 @@
 
 默认目录为 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是两项独立检查，不能因前者成立就宣称后者完成。
+
 业务proto精确 import "saddle_external_function.proto";，使用 (saddle.profusecontract.external_function)，字段为 puc 与 function。
 
 - puc是固定字段名，其值是项目确认的业务单元，不固定为字符串puc；例如bill可以按确认填bill。

package/package.json

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

package/references/adapt.md

@@ -94,6 +94,6 @@ Dependency与external-contract只在逻辑锚点上不同：前者目标指向Sp
 
 ## 来源定位
 
-本版本的path均为已指定输入仓库根目录相对路径，不是shell工作目录或URL。实体类型在业务域内解析；歧义不能按同名猜。不同来源仓库必须先明确解析上下文，不能把Spec仓库相对路径用于另一个仓库。
+本版本的path均为已指定输入仓库根目录相对路径，不是shell工作目录或URL。实体类型在业务域内解析；歧义不能按同名猜。项目关联只解析当前仓库当前分支，不承载跨仓库或跨分支定位。
 
-实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。契约版本跟随Spec+adapt内容重新核对，不只替换commit字符串。
+实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。关联随当前分支的Spec+adapt内容重新核对。