@antprofuse/saddle-skill 0.1.2 → 0.1.3

package/assets/v1-business/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "saddle-v1-business"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+publish = false
+
+[dependencies]
+saddle-framework = "=0.1.1"
+serde = { version = "1", features = ["derive"] }
+
+[workspace]

package/assets/v1-business/schema.sql

@@ -0,0 +1,18 @@
+CREATE TABLE users (
+    id BIGINT UNSIGNED NOT NULL PRIMARY KEY
+);
+
+CREATE TABLE orders (
+    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+    user_id BIGINT UNSIGNED NOT NULL,
+    amount_cents BIGINT UNSIGNED NOT NULL,
+    CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES users (id)
+);
+
+CREATE TABLE order_audit (
+    order_id BIGINT UNSIGNED NOT NULL PRIMARY KEY,
+    event_name VARCHAR(64) NOT NULL,
+    CONSTRAINT order_audit_order_fk FOREIGN KEY (order_id) REFERENCES orders (id)
+);
+
+INSERT INTO users (id) VALUES (1);

package/assets/v1-business/src/main.rs

@@ -0,0 +1,42 @@
+mod order;
+mod user;
+
+use ::std::net::{IpAddr, Ipv4Addr, SocketAddr};
+
+use ::saddle::Saddle;
+use ::saddle::{SaddleConfig, service::ServiceDescriptor};
+use order::{CreateOrder, CreateOrderHandler};
+use user::{GetUser, GetUserHandler};
+
+fn main() -> ::saddle::Result<()> {
+    let database_url = ::std::env::var("SADDLE_DATABASE_URL")
+        .expect("SADDLE_DATABASE_URL must be set by deployment configuration");
+    let config = SaddleConfig::new(
+        "commerce",
+        database_url,
+        SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 8080),
+    );
+
+    Saddle::run(config, |builder| {
+        let database = builder.database();
+
+        builder.register::<GetUser, _>(
+            ServiceDescriptor::new("user", "user", "get"),
+            GetUserHandler::new(database.clone()),
+        )?;
+        builder.expose_json::<GetUser>("/users/get");
+
+        builder.register_with::<CreateOrder, CreateOrderHandler, _>(
+            ServiceDescriptor::new("order", "order", "create"),
+            move |services| {
+                Ok(CreateOrderHandler::new(
+                    database,
+                    services.client::<GetUser>()?,
+                ))
+            },
+        )?;
+        builder.expose_json::<CreateOrder>("/orders/create");
+
+        Ok(())
+    })
+}

package/assets/v1-business/src/order.rs

@@ -0,0 +1,118 @@
+use ::saddle::{
+    CallContext, ErrorKind, SaddleError,
+    db::{Database, Statement},
+    obs::{self, DomainEvent, DomainEventError},
+    service::{Service, ServiceClient, ServiceFuture, ServiceHandler},
+};
+use ::serde::{Deserialize, Serialize};
+
+use crate::user::{GetUser, GetUserRequest};
+
+pub struct CreateOrder;
+
+#[derive(Deserialize)]
+pub struct CreateOrderRequest {
+    pub user_id: u64,
+    pub amount_cents: u64,
+}
+
+#[derive(Serialize)]
+pub struct CreateOrderResponse {
+    pub order_id: u64,
+}
+
+impl Service for CreateOrder {
+    type Request = CreateOrderRequest;
+    type Response = CreateOrderResponse;
+}
+
+pub struct CreateOrderHandler {
+    database: Database,
+    users: ServiceClient<GetUser>,
+}
+
+impl CreateOrderHandler {
+    pub fn new(database: Database, users: ServiceClient<GetUser>) -> Self {
+        Self { database, users }
+    }
+}
+
+impl ServiceHandler<CreateOrder> for CreateOrderHandler {
+    fn call<'a>(
+        &'a self,
+        context: &'a CallContext,
+        request: CreateOrderRequest,
+    ) -> ServiceFuture<'a, CreateOrderResponse> {
+        Box::pin(async move {
+            if request.amount_cents == 0 {
+                return Err(SaddleError::new(
+                    ErrorKind::InvalidArgument,
+                    "ORDER_AMOUNT_INVALID",
+                    "order amount must be greater than zero",
+                ));
+            }
+
+            let user = self
+                .users
+                .call(
+                    context,
+                    GetUserRequest {
+                        user_id: request.user_id,
+                    },
+                )
+                .await?;
+            if !user.exists {
+                return Err(SaddleError::new(
+                    ErrorKind::Business,
+                    "ORDER_USER_NOT_FOUND",
+                    "the order user does not exist",
+                ));
+            }
+
+            let user_id = request.user_id;
+            let amount_cents = request.amount_cents;
+            let order_id = self
+                .database
+                .transaction(context, "orders.create", move |transaction| {
+                    Box::pin(async move {
+                        let statement = Statement::new(
+                            "orders.insert",
+                            "INSERT INTO orders (user_id, amount_cents) VALUES (?, ?)",
+                        )?
+                        .bind(user_id)?
+                        .bind(amount_cents)?;
+                        let order_id = transaction.write(statement).await?.last_insert_id();
+
+                        let audit = Statement::new(
+                            "order_audit.insert",
+                            "INSERT INTO order_audit (order_id, event_name) VALUES (?, ?)",
+                        )?
+                        .bind(order_id)?
+                        .bind("order.created")?;
+                        transaction.write(audit).await?;
+
+                        Ok(order_id)
+                    })
+                })
+                .await?;
+
+            let event = DomainEvent::new("order.created")
+                .map_err(domain_event_error)?
+                .field("order_id", order_id)
+                .map_err(domain_event_error)?
+                .field("user_id", user_id)
+                .map_err(domain_event_error)?;
+            obs::record(context, event)?;
+
+            Ok(CreateOrderResponse { order_id })
+        })
+    }
+}
+
+fn domain_event_error(error: DomainEventError) -> SaddleError {
+    SaddleError::new(
+        ErrorKind::Internal,
+        "DOMAIN_EVENT_INVALID",
+        error.to_string(),
+    )
+}

package/assets/v1-business/src/user.rs

@@ -0,0 +1,54 @@
+use ::saddle::{
+    CallContext,
+    db::{Database, Statement},
+    service::{Service, ServiceFuture, ServiceHandler},
+};
+use ::serde::{Deserialize, Serialize};
+
+pub struct GetUser;
+
+#[derive(Deserialize)]
+pub struct GetUserRequest {
+    pub user_id: u64,
+}
+
+#[derive(Serialize)]
+pub struct GetUserResponse {
+    pub exists: bool,
+}
+
+impl Service for GetUser {
+    type Request = GetUserRequest;
+    type Response = GetUserResponse;
+}
+
+pub struct GetUserHandler {
+    database: Database,
+}
+
+impl GetUserHandler {
+    pub fn new(database: Database) -> Self {
+        Self { database }
+    }
+}
+
+impl ServiceHandler<GetUser> for GetUserHandler {
+    fn call<'a>(
+        &'a self,
+        context: &'a CallContext,
+        request: GetUserRequest,
+    ) -> ServiceFuture<'a, GetUserResponse> {
+        Box::pin(async move {
+            let statement = Statement::new(
+                "users.find_by_id",
+                "SELECT id FROM users WHERE id = ? LIMIT 1",
+            )?
+            .bind(request.user_id)?;
+            let user = self.database.query_optional(context, statement).await?;
+
+            Ok(GetUserResponse {
+                exists: user.is_some(),
+            })
+        })
+    }
+}

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@antprofuse/saddle-skill",
-  "version": "0.1.2",
-  "description": "面向 AI Coding 的 Saddle 0.1.1 Service 中文研发契约。",
+  "version": "0.1.3",
+  "description": "面向 AI Coding 的 Saddle V1 中文研发契约，基于 saddle-framework 0.1.1。",
   "license": "MIT OR Apache-2.0",
   "files": [
     "SKILL.md",
     "LICENSE-APACHE",
     "LICENSE-MIT",
     "agents",
-    "references"
+    "assets",
+    "references",
+    "scripts"
   ],
   "publishConfig": {
     "access": "public",

package/references/db-0.1.1.md

@@ -0,0 +1,96 @@
+# DB 与事务
+
+## 获取能力
+
+数据库连接池由 Saddle 创建。业务只能从 `SaddleBuilder::database()` 获取可克隆的
+`Database` 句柄，并把它注入 Handler：
+
+```rust
+let database = builder.database();
+let handler = GetUserHandler::new(database.clone());
+```
+
+不存在业务可用的 `Database::connect`、pool 构造、关闭或底层 sqlx transaction API。
+
+## 参数化语句
+
+始终用 `Statement` 和 `bind` 传参：
+
+```rust
+let statement = Statement::new(
+    "users.find_by_id",
+    "SELECT id FROM users WHERE id = ? LIMIT 1",
+)?
+.bind(user_id)?;
+
+let row = database.query_optional(context, statement).await?;
+```
+
+- operation 必须是稳定、低基数名称，例如 `users.find_by_id`，不能包含 SQL 或业务 ID。
+- 不拼接 SQL 参数。
+- 可绑定 `Null`、`bool`、`i64`、`u64`、`f64`、字符串和字节。
+- 使用 `query_optional` 查询零或一行，`query_all` 查询多行，`write` 执行写入。
+- 使用 `DbRow` 的强类型读取方法；可空列使用对应 `optional_*` 方法。
+- `WriteResult` 提供 `rows_affected()` 和 `last_insert_id()`。
+
+## 单层事务
+
+```rust
+let order_id = database
+    .transaction(context, "orders.create", move |transaction| {
+        Box::pin(async move {
+            let order = Statement::new(
+                "orders.insert",
+                "INSERT INTO orders (user_id, amount_cents) VALUES (?, ?)",
+            )?
+            .bind(user_id)?
+            .bind(amount_cents)?;
+            let order_id = transaction.write(order).await?.last_insert_id();
+
+            let audit = Statement::new(
+                "order_audit.insert",
+                "INSERT INTO order_audit (order_id, event_name) VALUES (?, ?)",
+            )?
+            .bind(order_id)?
+            .bind("order.created")?;
+            transaction.write(audit).await?;
+
+            Ok(order_id)
+        })
+    })
+    .await?;
+```
+
+- 闭包返回 `Ok` 时由 Saddle 提交，返回 `Err` 时由 Saddle 回滚。
+- 事务内只用传入的 `&mut Transaction` 查询和写入。
+- `Transaction` 没有 begin、commit、rollback、嵌套事务或 savepoint API。
+- 事务闭包的 future 与 `Transaction` 借用绑定，不能捕获外层 `&CallContext`。
+- 需要记录领域事件时，先让事务返回业务结果，再在提交成功后使用原上下文记录。
+- 随包示例用两条关联写入验证原子性：第二条失败时第一条不会留在 `orders`。
+
+## 资源边界
+
+0.1.1 发布 API 固定了以下上限：SQL 65,536 字节、参数 256 个、单参数和单字段
+各 1 MiB、参数总计 2 MiB、查询 10,000 行、结果总计 8 MiB。不要通过分片拼装、
+循环小查询或其他方式规避这些限制；应缩小业务查询。
+
+MariaDB 还需确保服务端 `max_allowed_packet` 不高于 8 MiB；0.1.1 会在启动时拒绝
+更宽松的入站配置，返回 `db.invalid_config`。
+
+## 错误模式
+
+```rust
+// 错误：字符串拼接参数。
+Statement::new("users.find", format!("SELECT * FROM users WHERE id = {user_id}"))?;
+
+// 错误：业务创建连接池或底层事务。
+sqlx::MySqlPool::connect(url).await?;
+
+// 错误：事务闭包捕获外层上下文，0.1.1 生命周期不允许。
+database.transaction(context, "orders.create", |transaction| {
+    Box::pin(async move {
+        obs::record(context, event)?;
+        Ok(())
+    })
+}).await?;
+```

package/references/gates-0.1.1.md

@@ -0,0 +1,77 @@
+# 业务边界门禁
+
+执行随 Skill 发布的门禁：
+
+```bash
+scripts/check-business-boundaries.sh path/to/Cargo.toml
+```
+
+交付前同时检查 Cargo 依赖和业务源码。扫描命中后先判断是否位于注释、文档或测试
+反例中；生产业务代码命中则必须移除或交由控制 workspace 审核。
+
+## 依赖
+
+业务 crate 必须直接依赖：
+
+```toml
+saddle-framework = "=0.1.1"
+```
+
+禁止直接依赖以下基础设施类别：
+
+- `tokio`、`async-std` 等 runtime/task
+- `axum`、`hyper`、`actix-web` 等 Web Server
+- `sqlx`、数据库驱动或连接池
+- `tracing-subscriber`
+- HTTP/RPC、文件、进程和消息客户端
+
+0.1.1 门禁采用封闭 allowlist：除精确 Saddle 门面外，仅批准
+`serde = { version = "1", features = ["derive"] }`。需要新增纯计算依赖时，先由
+控制 workspace 审核并更新门禁，不能在业务清单中自行加入。依赖别名、target
+dependency、build/dev dependency、path/git/registry 来源和自定义 Cargo target
+一律拒绝。
+
+## 源码
+
+业务生产代码不得出现：
+
+```text
+std::thread
+tokio::runtime
+tokio::spawn
+spawn_blocking
+axum::Router
+hyper::Server
+sqlx::Pool
+sqlx::Transaction
+tracing_subscriber
+reqwest
+std::fs
+std::process
+```
+
+门禁要求外部 crate 使用不可被本地模块遮蔽的绝对路径，例如
+`use ::saddle::Saddle;`。它拒绝 import alias、`include!`/`#[path]`、unsafe/FFI/汇编、
+未批准的绝对 crate 路径和额外编译输入。业务不得定义宏，所有 `name!(...)` bang
+宏调用均拒绝；属性只允许来自已批准 serde 的 Deserialize/Serialize derive。这样
+能力判定不依赖猜测宏展开结果。标准库只批准示例使用的地址类型与部署环境变量读取。
+随后执行 `cargo check --locked`，确认锁定依赖和真实入口可编译。
+
+默认 `src/main.rs` 必须有且只有一个真实 `fn main`，并由该函数体调用从
+`::saddle::Saddle` 导入的 `Saddle::run`；不接受字符串或本地同名类型伪造、
+自定义入口、额外 binary/library 或 build script。整个源码树中的 `Saddle` 标识
+只能出现于该绝对导入与唯一调用；main/块作用域禁止 `use`，`Saddle::run` 必须是
+main 的尾部启动表达式，避免跨模块或局部名称遮蔽。
+
+还要人工确认：
+
+- 只有一个 `main`，且入口调用 `Saddle::run`。
+- 所有外部入口都对应已注册的 Service。
+- 内部模块调用使用 `ServiceClient`。
+- DB 句柄来自 `SaddleBuilder::database()`。
+- 所有 SQL 使用 `Statement` 参数绑定。
+- 所有事务只通过 `Database::transaction`。
+- 所有领域事件有界且不包含敏感 payload。
+
+不要用别名、间接封装或字符串拆分绕过门禁。门禁发现确实需要的新通用能力时，
+提交 Saddle 公共 API 缺口，不要在业务项目中放行旁路。

package/references/observability-0.1.1.md

@@ -0,0 +1,69 @@
+# 错误、日志与 Trace
+
+## 自动链路
+
+Saddle 为外部入口创建或继承 `CallContext`，内部 Service 和 DB 调用接收父上下文。
+业务只需把 Handler 收到的 `context` 原样传入 Saddle API，不要初始化 subscriber、
+创建 span 或手工传播 Trace。
+
+框架日志与 Trace 属于自动能力。业务不要重复记录入口、出口、耗时、DB 成功失败或
+事务提交回滚等流程日志，只记录真正有领域含义的事件。
+
+## 领域事件
+
+```rust
+let event = DomainEvent::new("order.created")
+    .map_err(domain_event_error)?
+    .field("order_id", order_id)
+    .map_err(domain_event_error)?
+    .field("user_id", user_id)
+    .map_err(domain_event_error)?;
+obs::record(context, event)?;
+```
+
+- 事件名和字段名使用稳定、低基数标识。
+- 字段只支持字符串、有符号整数、无符号整数和布尔值。
+- 默认级别是框架定义值；需要时用 `level(EventLevel::...)` 设置。
+- 不写完整请求、响应、SQL、SQL 参数、凭据、令牌或任意对象调试文本。
+- `DomainEventError` 与 `SaddleError` 是不同错误；显式转换为不泄露敏感信息的
+  稳定框架错误。
+- 事务成功事件在 `Database::transaction(...).await?` 返回后记录，避免把回滚操作
+  误记为成功，也避免捕获事务闭包不允许的外层上下文引用。
+
+```rust
+fn domain_event_error(error: DomainEventError) -> SaddleError {
+    SaddleError::new(
+        ErrorKind::Internal,
+        "DOMAIN_EVENT_INVALID",
+        error.to_string(),
+    )
+}
+```
+
+## 错误语义
+
+- 输入格式或范围错误：`InvalidArgument`
+- 资源不存在：`NotFound`
+- 状态冲突：`Conflict`
+- 预期业务拒绝：`Business`
+- 临时不可用：`Unavailable`
+- 基础设施失败：由 Saddle DB/Service 能力转换；业务不要泄露底层错误
+- 不应发生的契约错误：`Internal`
+
+随包示例在 0.1.1 上的可执行验收基线为：`InvalidArgument` 返回 HTTP 400，
+`Business` 返回 HTTP 422，DB 基础设施错误返回 HTTP 500；错误体只暴露稳定 code
+和 trace ID。升级 Saddle 制品后重新验证映射，不自行实现 HTTP 错误转换。
+
+## 错误模式
+
+```rust
+// 错误：自行初始化框架日志。
+tracing_subscriber::fmt().init();
+
+// 错误：高基数事件名和敏感 payload。
+DomainEvent::new(format!("order.created.{order_id}"))?
+    .field("request", format!("{request:?}"))?;
+
+// 错误：伪造或替换 Trace 上下文。
+let context = CallContext::new(...);
+```

package/references/overview-0.1.1.md

@@ -0,0 +1,73 @@
+# Saddle V1 总览
+
+## 应用模型
+
+- 一个 Cargo 大库就是一个应用、一个构建单元和一个部署进程。
+- 用户、订单等是同一大库中的业务模块，不是独立部署服务。
+- 业务只定义 Service 契约、Handler、业务规则、内部调用和数据访问意图。
+- Saddle 统一拥有进程入口、async runtime、HTTP/JSON 入口、数据库连接池、
+  事务边界、调用上下文、结构化日志和 Trace。
+
+推荐目录：
+
+```text
+src/
+├── main.rs       # 唯一启动与装配入口
+├── user.rs       # 用户契约与 Handler
+└── order.rs      # 订单契约与 Handler
+```
+
+## 依赖
+
+```toml
+[package]
+edition = "2024"
+rust-version = "1.85"
+
+[dependencies]
+saddle-framework = "=0.1.1"
+serde = { version = "1", features = ["derive"] }
+```
+
+Cargo 包名是 `saddle-framework`，Rust 库名是 `saddle`。0.1.x 尚无兼容承诺，
+必须精确固定版本。
+
+## 固定装配
+
+```rust
+let database_url = std::env::var("SADDLE_DATABASE_URL")
+    .expect("SADDLE_DATABASE_URL must be set by deployment configuration");
+let config = SaddleConfig::new("commerce", database_url, listen);
+
+Saddle::run(config, |builder| {
+    let database = builder.database();
+    // 注册内部和外部 Service。
+    Ok(())
+})
+```
+
+`SaddleConfig` 只表达应用标识、数据库地址和监听地址这些部署事实，不能用于选择
+另一套 runtime、传输、数据库驱动或日志实现。
+
+## 已验证闭环
+
+`assets/v1-business` 基于 crates.io 0.1.1 编译，覆盖：
+
+```text
+HTTP/JSON 创建订单
+  -> CreateOrder Service
+  -> ServiceClient<GetUser>
+  -> Database::query_optional
+  -> Database::transaction
+  -> Transaction::write
+  -> 提交后记录 order.created 领域事件
+```
+
+示例只证明公共 API、依赖闭合和 Rust 生命周期成立。实际运行仍要求可访问的
+MySQL/MariaDB 数据源和可绑定的监听地址。
+
+## 0.1.1 非能力
+
+不要生成定时任务、后台常驻任务、消息消费、外部 HTTP/RPC 客户端、文件 I/O、
+多数据库抽象、嵌套事务、savepoint、分布式事务、通用 `spawn`、Metrics、
+跨进程 Service 调用、服务发现、限流、重试或熔断代码。

package/references/runtime-0.1.1.md

@@ -0,0 +1,54 @@
+# Runtime 与进程生命周期
+
+## 正确模型
+
+- 只定义一个同步 `main`，返回 `saddle::Result<()>`。
+- 只通过 `Saddle::run` 创建并运行应用。
+- 在 `Saddle::run` 的配置闭包中完成 Service 注册和入口暴露。
+- Handler 通过 `ServiceFuture` 返回 async 业务执行。
+- 将进程启动、监听、信号处理和关闭收敛交给 Saddle。
+
+```rust
+fn main() -> saddle::Result<()> {
+    let config = SaddleConfig::new(application, database_url, listen);
+    Saddle::run(config, |builder| {
+        // 只装配业务 Service。
+        Ok(())
+    })
+}
+```
+
+0.1.1 没有业务可调用的 runtime、thread 或通用 task 创建 API。不要为了并行或
+后台执行而增加 Tokio 直接依赖；当前 V1 业务执行必须留在 Service 调用链中。
+
+## 上下文
+
+每个 Handler 接收框架创建的 `&CallContext`。将同一个引用传给：
+
+- `ServiceClient::call`
+- `Database::query_all`、`query_optional`、`write`、`transaction`
+- `obs::record`
+
+不要手工创建或替换外部请求的上下文，也不要自行传播 Trace ID。业务可以读取
+application、module、service、operation、trace_id 和 span_id，用于必要的业务判断
+或低敏领域字段，但不要将完整上下文序列化到响应或日志。
+
+## 错误模式
+
+```rust
+// 错误：业务拥有 runtime。
+#[tokio::main]
+async fn main() {}
+
+// 错误：脱离 Saddle 请求生命周期。
+tokio::spawn(async move { /* ... */ });
+
+// 错误：真实线程和阻塞等待。
+std::thread::spawn(|| {});
+std::thread::sleep(duration);
+
+// 错误：业务自行提供 HTTP 服务。
+axum::Router::new();
+```
+
+业务需要 V1 未提供的后台或并发执行模型时，提交公共能力需求，不要建立旁路。