@antprofuse/saddle-skill 0.1.3 → 0.2.0-rc.20

package/references/service-0.1.1.md

@@ -1,124 +0,0 @@
-# Service 契约
-
-## 目录
-
-- [定义和实现](#定义和实现)
-- [描述和注册](#描述和注册)
-- [内部 Service 调用](#内部-service-调用)
-- [稳定错误](#稳定错误)
-- [错误模式](#错误模式)
-
-## 定义和实现
-
-为每个业务操作定义零大小契约类型、请求、响应和独立 Handler：
-
-```rust
-use saddle::{
-    CallContext,
-    service::{Service, ServiceFuture, ServiceHandler},
-};
-
-struct GetUser;
-
-impl Service for GetUser {
-    type Request = GetUserRequest;
-    type Response = GetUserResponse;
-}
-
-impl ServiceHandler<GetUser> for GetUserHandler {
-    fn call<'a>(
-        &'a self,
-        context: &'a CallContext,
-        request: GetUserRequest,
-    ) -> ServiceFuture<'a, GetUserResponse> {
-        Box::pin(async move {
-            // 只表达业务规则，并通过注入的 Saddle 能力执行调用和 I/O。
-            Ok(GetUserResponse { exists: true })
-        })
-    }
-}
-```
-
-请求和响应必须是 `Send + 'static`。通过 JSON 暴露时，请求还必须实现
-`DeserializeOwned`，响应必须实现 `Serialize`。
-
-## 描述和注册
-
-`ServiceDescriptor::new(module, service, operation)` 的三个标识必须稳定、低基数：
-
-```rust
-builder.register::<GetUser, _>(
-    ServiceDescriptor::new("user", "user", "get"),
-    GetUserHandler::new(database.clone()),
-)?;
-builder.expose_json::<GetUser>("/users/get");
-```
-
-- `module` 表示业务模块。
-- `service` 表示稳定的业务服务。
-- `operation` 表示具体操作。
-- 只对确实需要外部访问的 Service 调用 `expose_json`。
-- 由 Saddle 检查重复注册、未注册入口和依赖闭合，不要自建注册表。
-
-## 内部 Service 调用
-
-调用方依赖 `ServiceClient<目标契约>`，不得依赖目标 Handler：
-
-```rust
-struct CreateOrderHandler {
-    users: ServiceClient<GetUser>,
-}
-
-let user = self
-    .users
-    .call(context, GetUserRequest { user_id })
-    .await?;
-```
-
-在 `register_with` 工厂中解析依赖，使缺失依赖在装配阶段失败：
-
-```rust
-builder.register_with::<CreateOrder, CreateOrderHandler, _>(
-    ServiceDescriptor::new("order", "order", "create"),
-    move |services| {
-        Ok(CreateOrderHandler::new(
-            database,
-            services.client::<GetUser>()?,
-        ))
-    },
-)?;
-```
-
-不要直接构造 `ServiceClient`，也不要直接调用另一个模块的 Handler。
-
-## 稳定错误
-
-业务预期失败使用 `SaddleError`，错误码使用稳定的大写标识：
-
-```rust
-return Err(SaddleError::new(
-    ErrorKind::InvalidArgument,
-    "ORDER_AMOUNT_INVALID",
-    "order amount must be greater than zero",
-));
-```
-
-可用 `ErrorKind`：`InvalidArgument`、`NotFound`、`Conflict`、`Business`、
-`Unavailable`、`Infrastructure`、`Internal`。该枚举是非穷尽的；业务匹配时保留
-通配分支。错误消息不得包含凭据、SQL 参数、完整 payload 或内部敏感细节。
-
-## 错误模式
-
-```rust
-// 错误：绕过 Saddle 的内部调用和上下文传播。
-let response = GetUserHandler::new(database).call(context, request).await?;
-
-// 错误：0.1.1 没有这些宏。
-#[saddle::service]
-async fn create_order(...) { ... }
-
-// 错误：Service trait 位于 saddle::service。
-use saddle::{Service, ServiceHandler};
-```
-
-完整组合方式见 `assets/v1-business/src/user.rs`、`order.rs` 和 `main.rs`。

package/references/validation-0.1.1.md

@@ -1,50 +0,0 @@
-# 验证
-
-## 编译
-
-在 Saddle 仓库执行：
-
-```bash
-cargo +1.85.0 fmt --manifest-path examples/v1-business/Cargo.toml -- --check
-cargo +1.85.0 check --locked --manifest-path examples/v1-business/Cargo.toml
-cargo check --locked --manifest-path examples/v1-business/Cargo.toml
-cargo tree --locked --manifest-path examples/v1-business/Cargo.toml \
-  -p saddle-framework@0.1.1
-gates/check-business-boundaries.sh examples/v1-business/Cargo.toml
-```
-
-对安装后的 Skill，将路径替换为 `assets/v1-business/Cargo.toml`。
-
-## 依赖边界
-
-确认业务清单只直接声明精确版本 Saddle 门面和批准的序列化/纯计算依赖。依赖树中
-出现 Tokio、Axum 或 sqlx 作为 Saddle 的传递依赖是正常的；业务 `Cargo.toml`
-直接声明或业务源码直接使用它们才是旁路。
-
-## 当前事实
-
-- Rust 1.85 和当前工具链可编译 `assets/v1-business`。
-- 所有 Saddle 组件解析为 0.1.1。
-- 示例覆盖 Service 注册与 HTTP/JSON 暴露、内部 `ServiceClient`、托管 DB、
-  单层事务、稳定错误和领域事件。
-- 示例已在 MariaDB 10.11 上完成真实 HTTP 验证：正常订单同时提交 `orders` 和
-  `order_audit`；让第二条写入失败后返回 `db.query_failed`，第一条写入被回滚。
-- 示例实测 `InvalidArgument` 映射为 HTTP 400、`Business` 映射为 HTTP 422、
-  DB 基础设施错误映射为 HTTP 500；响应头和错误体携带同一个 trace ID。
-- 32 位十六进制 `x-saddle-trace-id` 被继承；无效值由框架替换。日志中的外部入口、
-  内部 Service、DB、事务和领域事件共享 trace，并记录 commit 或 rollback。
-
-这些 HTTP 和日志结论是 `saddle-framework 0.1.1` 配合本示例的验证基线。升级制品后
-必须重新运行，不能把示例观测外推为未发布版本的承诺。
-
-## MariaDB 部署前提
-
-0.1.1 会校验数据库入站包上限。MariaDB 的 `max_allowed_packet` 大于框架允许值时，
-示例启动返回 `db.invalid_config`；本次以 8 MiB 配置验证通过。部署前显式确认：
-
-```sql
-SELECT @@global.max_allowed_packet;
-```
-
-不要为了通过启动检查提高该值；生产配置应由部署环境按 0.1.1 的 8 MiB 结果边界
-统一设置。

package/scripts/check-business-boundaries.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-exec python3 "$script_dir/check_business_boundaries.py" "$@"

package/scripts/check_business_boundaries.py

@@ -1,356 +0,0 @@
-#!/usr/bin/env python3
-"""Conservative, closed-policy gate for Saddle V1 business crates."""
-
-from __future__ import annotations
-
-import re
-import os
-import subprocess
-import sys
-import tempfile
-import tomllib
-from pathlib import Path
-
-
-ALLOWED_DEPENDENCIES = {"saddle-framework", "serde"}
-ALLOWED_TOP_LEVEL = {"package", "dependencies", "workspace"}
-ALLOWED_PACKAGE_KEYS = {"name", "version", "edition", "rust-version", "publish"}
-FORBIDDEN_MANIFEST_KEYS = {
-    "lib", "bin", "example", "test", "bench", "target",
-    "build-dependencies", "dev-dependencies",
-}
-SOURCE_RULES = {
-    "THREAD": [r"\bstd\s*::\s*thread\b"],
-    "RUNTIME": [
-        r"\btokio\s*::\s*runtime\b", r"\basync_std\s*::\s*task\s*::\s*block_on\b",
-        r"\bsmol\s*::\s*block_on\b",
-    ],
-    "TASK": [
-        r"\btokio\s*::\s*(?:task\s*::\s*)?spawn\b", r"\bspawn_blocking\b",
-        r"\basync_std\s*::\s*task\s*::\s*spawn\b", r"\bsmol\s*::\s*spawn\b",
-    ],
-    "WEB": [
-        r"\baxum\s*::", r"\bhyper\s*::", r"\bactix_web\s*::", r"\bwarp\s*::",
-        r"\bpoem\s*::", r"\brocket\s*::",
-    ],
-    "DB": [
-        r"\bsqlx\s*::", r"\bdiesel\s*::", r"\bsea_orm\s*::",
-        r"\b(?:MySql|Pg|Sqlite)Pool\b",
-    ],
-    "OBSERVABILITY": [r"\btracing_subscriber\b", r"\blog4rs\b", r"\benv_logger\b"],
-    "IO": [
-        r"\bstd\s*::\s*fs\b", r"\bstd\s*::\s*process\b",
-        r"\bstd\s*::\s*io\s*::\s*(?:stdin|stdout|stderr|Read|Write|BufRead)\b",
-        r"\bstd\s*::\s*net\s*::\s*(?:TcpStream|TcpListener|UdpSocket)\b",
-        r"\b(?:reqwest|ureq|surf|isahc|curl|tonic|tarpc|lapin|rdkafka|nats|redis)\s*::",
-    ],
-}
-
-
-class Gate:
-    def __init__(self, manifest: Path) -> None:
-        self.manifest = manifest.resolve()
-        self.root = self.manifest.parent
-        self.failures = 0
-
-    def report(self, rule: str, detail: str) -> None:
-        print(f"SADDLE_GATE {rule} {detail}", file=sys.stderr)
-        self.failures += 1
-
-    def check_manifest(self, data: dict) -> None:
-        for key in data.keys() - ALLOWED_TOP_LEVEL:
-            rule = "DEPENDENCY" if key in {"patch", "replace"} else "MANIFEST"
-            self.report(rule, f"{self.manifest}: 不允许 Cargo 顶层配置 [{key}]")
-        for key in FORBIDDEN_MANIFEST_KEYS & data.keys():
-            self.report("TARGET", f"{self.manifest}: 不允许 [{key}] 或自定义/附加 Cargo target")
-
-        package = data.get("package")
-        if not isinstance(package, dict):
-            self.report("MANIFEST", f"{self.manifest}: 缺少 [package]")
-        else:
-            for key in package.keys() - ALLOWED_PACKAGE_KEYS:
-                rule = "BUILD" if key in {"build", "links"} else "TARGET"
-                self.report(rule, f"{self.manifest}: 不允许 package.{key}")
-
-        workspace = data.get("workspace")
-        if workspace not in ({}, None):
-            self.report("MANIFEST", f"{self.manifest}: [workspace] 不得包含配置")
-
-        dependencies = data.get("dependencies")
-        if not isinstance(dependencies, dict):
-            self.report("DEPENDENCY", f"{self.manifest}: 缺少 [dependencies]")
-            return
-
-        for name, spec in dependencies.items():
-            if name not in ALLOWED_DEPENDENCIES:
-                self.report("DEPENDENCY", f"{self.manifest}: 未批准的直接依赖 {name}")
-                continue
-            if name == "saddle-framework":
-                if isinstance(spec, dict) and spec.get("version") == "=0.1.1":
-                    self.report("DEPENDENCY", f"{self.manifest}: saddle-framework 禁止 path/git/registry/package 等依赖来源")
-                elif spec != "=0.1.1":
-                    self.report("SADDLE_VERSION", f'{self.manifest}: 必须为 saddle-framework = "=0.1.1"')
-            elif name == "serde":
-                valid = (
-                    isinstance(spec, dict)
-                    and spec.get("version") == "1"
-                    and set(spec) <= {"version", "features"}
-                    and spec.get("features") == ["derive"]
-                )
-                if not valid:
-                    self.report("DEPENDENCY", f'{self.manifest}: serde 仅允许 version="1", features=["derive"]')
-
-        if "saddle-framework" not in dependencies:
-            self.report("SADDLE_VERSION", f'{self.manifest}: 必须直接依赖 saddle-framework = "=0.1.1"')
-
-    def check_layout(self) -> list[Path]:
-        main = self.root / "src" / "main.rs"
-        if not main.is_file():
-            self.report("ENTRY", f"{main}: 必须使用默认二进制入口 src/main.rs")
-
-        forbidden = [self.root / "build.rs", self.root / "src" / "lib.rs"]
-        forbidden.extend((self.root / "src" / "bin").glob("*.rs") if (self.root / "src" / "bin").is_dir() else [])
-        for path in forbidden:
-            if path.exists():
-                self.report("TARGET", f"{path}: 不允许额外 target 或 build script")
-
-        if (self.root / ".cargo").exists():
-            self.report("DEPENDENCY", f"{self.root / '.cargo'}: 不允许项目级 Cargo source/config 覆盖")
-
-        source_dir = self.root / "src"
-        return sorted(source_dir.rglob("*.rs")) if source_dir.is_dir() else []
-
-    def check_sources(self, sources: list[Path]) -> None:
-        stripped: dict[Path, str] = {}
-        for path in sources:
-            text = strip_rust_non_code(path.read_text(encoding="utf-8"))
-            stripped[path] = text
-            self.check_closed_source(path, text)
-            for rule, patterns in SOURCE_RULES.items():
-                if any(re.search(pattern, text) for pattern in patterns):
-                    self.report(rule, f"{path}: 命中禁止能力")
-
-        main_count = sum(len(re.findall(r"\bfn\s+main\s*\(", text)) for text in stripped.values())
-        if main_count != 1:
-            self.report("ENTRY", f"{self.root / 'src'}: 必须且只能定义一个 fn main，实际为 {main_count}")
-
-        main_path = self.root / "src" / "main.rs"
-        main_text = stripped.get(main_path, "")
-        body = function_body(main_text, "main")
-        normalized_main = re.sub(r"\s+", "", main_text)
-        if "use::saddle::Saddle;" not in normalized_main:
-            self.report("ENTRY", f"{main_path}: 必须以 use ::saddle::Saddle 绑定发布 facade")
-        saddle_occurrences = sum(
-            len(re.findall(r"\bSaddle\b", source_text))
-            for source_text in stripped.values()
-        )
-        if saddle_occurrences != 2:
-            self.report("ENTRY", f"{self.root / 'src'}: Saddle 标识只能用于 facade 导入和唯一启动调用")
-        if body is not None and re.search(r"\buse\s+", body):
-            self.report("ENTRY", f"{main_path}: fn main/块作用域内禁止 use 与名称遮蔽")
-        if body is None or len(re.findall(r"\bSaddle\s*::\s*run\s*\(", body)) != 1:
-            self.report("ENTRY", f"{main_path}: fn main 函数体必须调用 Saddle::run")
-        elif not call_is_tail_expression(body, "Saddle", "run"):
-            self.report("ENTRY", f"{main_path}: Saddle::run 必须是 fn main 的唯一尾部启动调用")
-
-    def check_closed_source(self, path: Path, text: str) -> None:
-        if re.search(r"\bmacro_rules\s*!|\bmacro\s+[A-Za-z_]", text):
-            self.report("MACRO", f"{path}: 禁止业务定义声明式或过程宏")
-        for macro_name in re.findall(r"\b([A-Za-z_][A-Za-z0-9_]*)\s*!\s*[\(\{\[]", text):
-            self.report("MACRO", f"{path}: 未批准的宏调用 {macro_name}!")
-
-        for attribute in re.findall(r"#\s*\[\s*([^\]]+)\]", text, re.S):
-            compact = re.sub(r"\s+", "", attribute)
-            derive = re.fullmatch(r"derive\(([^)]+)\)", compact)
-            names = set(derive.group(1).split(",")) if derive else set()
-            if not derive or not names or not names <= {"Deserialize", "Serialize"}:
-                self.report("ATTRIBUTE", f"{path}: 仅允许 serde Deserialize/Serialize derive")
-
-        if re.search(r"\b(?:include|include_str|include_bytes)\s*!", text) or re.search(r"#\s*\[\s*path\s*=", text):
-            self.report("SOURCE", f"{path}: 禁止 include!/外部 path 源码注入")
-        if re.search(r"\bextern\s+crate\b", text):
-            self.report("SOURCE", f"{path}: 禁止 extern crate/别名注入")
-        if re.search(r"\bunsafe\b|\bextern\s*\"|\b(?:global_asm|asm)\s*!|#\s*\[\s*(?:link|no_mangle)", text):
-            self.report("SOURCE", f"{path}: 禁止 unsafe、FFI、汇编或链接注入")
-
-        for statement in re.findall(r"\buse\s+[^;]+;", text, re.S):
-            compact = re.sub(r"\s+", "", statement)
-            if re.search(r"\bas\b", statement):
-                self.report("SOURCE", f"{path}: use 不允许 as 别名")
-            if compact.startswith("use::std::"):
-                if compact != "use::std::net::{IpAddr,Ipv4Addr,SocketAddr};":
-                    self.report("IO", f"{path}: 未批准的 ::std 导入")
-            elif compact.startswith(("use::saddle::", "use::serde::")):
-                pass
-            elif compact.startswith(("usecrate::", "useself::", "usesuper::")):
-                pass
-            elif compact.startswith(("usestd::", "usesaddle::", "useserde::")):
-                self.report("SOURCE", f"{path}: 外部 crate 必须使用不可遮蔽的绝对路径")
-
-        allowed_std = re.sub(
-            r"use\s*::\s*std\s*::\s*net\s*::\s*\{\s*IpAddr\s*,\s*Ipv4Addr\s*,\s*SocketAddr\s*\}\s*;",
-            "",
-            text,
-        )
-        allowed_std = re.sub(r"::\s*std\s*::\s*env\s*::\s*var\b", "", allowed_std)
-        if re.search(r"(?<!:)\bstd\s*::|::\s*std\s*::", allowed_std):
-            self.report("IO", f"{path}: 仅允许约定的 std 地址类型和部署环境变量读取")
-        if re.search(r"(?<!:)\b(?:saddle|serde)\s*::", text):
-            self.report("SOURCE", f"{path}: saddle/serde 必须从绝对 external-prelude 路径导入")
-        for root in re.findall(r"(?<![:\w])::\s*([A-Za-z_][A-Za-z0-9_]*)\s*::", text):
-            if root not in {"saddle", "serde", "std"}:
-                self.report("SOURCE", f"{path}: 未批准的绝对 crate 路径 ::{root}")
-
-    def check_compiler(self) -> None:
-        lock = self.root / "Cargo.lock"
-        if not lock.is_file():
-            self.report("COMPILER", f"{lock}: 缺少锁文件，无法验证真实依赖解析")
-            return
-        with tempfile.TemporaryDirectory(prefix="saddle-gate-") as target:
-            environment = os.environ.copy()
-            environment["CARGO_TARGET_DIR"] = target
-            result = subprocess.run(
-                ["cargo", "check", "--locked", "--quiet", "--manifest-path", str(self.manifest)],
-                env=environment,
-                capture_output=True,
-                text=True,
-                check=False,
-            )
-        if result.returncode:
-            detail = result.stderr.strip().splitlines()[-1] if result.stderr.strip() else "cargo check 失败"
-            self.report("COMPILER", f"{self.manifest}: {detail}")
-
-
-def strip_rust_non_code(text: str) -> str:
-    """Replace comments and literals with spaces while preserving newlines."""
-    out = list(text)
-    i = 0
-    block_depth = 0
-    while i < len(text):
-        if block_depth:
-            if text.startswith("/*", i):
-                out[i:i + 2] = "  "
-                block_depth += 1
-                i += 2
-            elif text.startswith("*/", i):
-                out[i:i + 2] = "  "
-                block_depth -= 1
-                i += 2
-            else:
-                if text[i] != "\n":
-                    out[i] = " "
-                i += 1
-            continue
-        if text.startswith("//", i):
-            end = text.find("\n", i)
-            end = len(text) if end < 0 else end
-            out[i:end] = " " * (end - i)
-            i = end
-            continue
-        if text.startswith("/*", i):
-            out[i:i + 2] = "  "
-            block_depth = 1
-            i += 2
-            continue
-        raw = re.match(r"(?:b)?r(#{0,255})\"", text[i:])
-        if raw:
-            marker = '"' + raw.group(1)
-            start = i
-            i += raw.end()
-            end = text.find(marker, i)
-            i = len(text) if end < 0 else end + len(marker)
-            for j in range(start, i):
-                if text[j] != "\n":
-                    out[j] = " "
-            continue
-        char = re.match(r"(?:b)?'(?:\\(?:u\{[0-9A-Fa-f_]+\}|.)|[^\\'\n])'", text[i:])
-        if char:
-            end = i + char.end()
-            out[i:end] = " " * (end - i)
-            i = end
-            continue
-        prefix = 1 if text.startswith('b"', i) else 0
-        quote_at = i + prefix
-        if quote_at < len(text) and text[quote_at] == '"':
-            quote = '"'
-            start = i
-            i = quote_at + 1
-            while i < len(text):
-                if text[i] == "\\":
-                    i += 2
-                elif text[i] == quote:
-                    i += 1
-                    break
-                else:
-                    i += 1
-            for j in range(start, min(i, len(text))):
-                if text[j] != "\n":
-                    out[j] = " "
-            continue
-        i += 1
-    return "".join(out)
-
-
-def function_body(text: str, name: str) -> str | None:
-    match = re.search(rf"\bfn\s+{re.escape(name)}\s*\([^)]*\)[^{{;]*\{{", text, re.S)
-    if not match:
-        return None
-    start = match.end() - 1
-    depth = 0
-    for index in range(start, len(text)):
-        if text[index] == "{":
-            depth += 1
-        elif text[index] == "}":
-            depth -= 1
-            if depth == 0:
-                return text[start + 1:index]
-    return None
-
-
-def call_is_tail_expression(body: str, type_name: str, method: str) -> bool:
-    match = re.search(
-        rf"\b{re.escape(type_name)}\s*::\s*{re.escape(method)}\s*\(",
-        body,
-    )
-    if not match:
-        return False
-    opening = body.find("(", match.start())
-    depth = 0
-    for index in range(opening, len(body)):
-        if body[index] == "(":
-            depth += 1
-        elif body[index] == ")":
-            depth -= 1
-            if depth == 0:
-                return not body[index + 1:].strip()
-    return False
-
-
-def main() -> int:
-    if len(sys.argv) != 2:
-        print(f"用法: {sys.argv[0]} <业务 Cargo.toml>", file=sys.stderr)
-        return 2
-    manifest = Path(sys.argv[1])
-    if not manifest.is_file():
-        print(f"SADDLE_GATE MANIFEST {manifest}: 文件不存在", file=sys.stderr)
-        return 2
-    try:
-        data = tomllib.loads(manifest.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, tomllib.TOMLDecodeError) as error:
-        print(f"SADDLE_GATE MANIFEST {manifest}: {error}", file=sys.stderr)
-        return 2
-
-    gate = Gate(manifest)
-    gate.check_manifest(data)
-    gate.check_sources(gate.check_layout())
-    if not gate.failures:
-        gate.check_compiler()
-    if gate.failures:
-        print(f"SADDLE_GATE rejected: {gate.failures} violation(s)", file=sys.stderr)
-        return 1
-    print(f"SADDLE_GATE passed: {gate.manifest}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())