docs: consolidate runnable examples and publish v0.1.1 guides

examples/tasks/README.md

@@ -0,0 +1,30 @@
+# 任务提交与幂等
+
+同一请求提交两次，查询任务和直接来源，再按版本取消。
+
+## 准备
+
+- Go 1.27.1、当前版本 Orbit；服务启动和初始化见[仓库 README](../../README.md#快速开始)。
+- 任务提交、读取、取消权限；不需要 Worker。
+- [示例总索引](../README.md)提供统一初始化和权限说明；完整字段、失败处理见[详细手册](../../docs/sdk/README.md)。
+
+## 运行
+
+以下命令从仓库根目录执行；凭据路径替换为实际初始化输出。
+
+```sh
+cd examples
+export ORBIT_URL=http://127.0.0.1:8080
+export ORBIT_CREDENTIALS_FILE="$PWD/../.local/development.credentials.json"
+go run ./tasks
+```
+
+## 结果核对
+
+duplicate=true；source_kind=DIRECT；final_state=CANCELLED。具体 ID 和统计值以本次运行为准。程序会核对上述关键条件，失败时打印错误并以非零状态退出。
+
+## 接入自己的项目
+
+阅读[main.go](main.go)中的客户端创建、请求及错误处理。业务项目通过 `go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.1` 引入 SDK，无需导入本示例包。
+
+示例运行会写入真实平台数据，应使用专用测试应用/队列。正常结束保留历史和审计；重复演示通常创建新身份，不能当作上次失败操作的恢复。真实业务应在第一次请求前持久化操作身份，网络结果不明时沿原身份核对。

examples/tasks/main.go

@@ -0,0 +1,98 @@
+// tasks 演示受理、重复提交、查询、分页与取消；此示例不启动业务 Worker。
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"time"
+
+	orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+func run() error {
+	token, queue := os.Getenv("ORBIT_TOKEN"), os.Getenv("ORBIT_QUEUE_ID")
+	if path := os.Getenv("ORBIT_CREDENTIALS_FILE"); path != "" {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return fmt.Errorf("read private credentials: %w", err)
+		}
+		var credentials struct {
+			Token   string `json:"token"`
+			QueueID string `json:"queue_id"`
+		}
+		if err := json.Unmarshal(raw, &credentials); err != nil {
+			return fmt.Errorf("invalid credentials file")
+		}
+		if token == "" {
+			token = credentials.Token
+		}
+		if queue == "" {
+			queue = credentials.QueueID
+		}
+	}
+	client, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: token})
+	if err != nil {
+		return err
+	}
+	if queue == "" {
+		return fmt.Errorf("ORBIT_QUEUE_ID is required")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	var operation [16]byte
+	if _, err := rand.Read(operation[:]); err != nil {
+		return err
+	}
+	key := "example-" + hex.EncodeToString(operation[:])
+	// 生产接入应先在业务库保存稳定键；本示例的两次请求共用同一个键。
+	in := orbit.SubmitTaskRequest{QueueID: queue, Handler: "file.convert", HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"source_ref":"example/input.txt","format":"pdf","sequence":9007199254740993}`)}
+	first, err := client.SubmitTask(ctx, key, in)
+	if err != nil {
+		return err
+	}
+	again, err := client.SubmitTask(ctx, key, in)
+	if err != nil {
+		return err
+	}
+	if first.Task.ID != again.Task.ID || !again.Deduplicated {
+		return fmt.Errorf("duplicate submission did not return the original task")
+	}
+	current, err := client.GetTask(ctx, first.Task.ID)
+	if err != nil {
+		return err
+	}
+	page, err := client.ListTasks(ctx, orbit.ListTasksRequest{QueueID: queue, Limit: 10})
+	if err != nil {
+		return err
+	}
+	cancelled, err := client.CancelTask(ctx, current.ID, key+"-cancel", orbit.CancelTaskRequest{Reason: "finish task acceptance example", ExpectedRevision: current.Revision})
+	if err != nil {
+		return err
+	}
+	// 仅历史兼容性 smoke 使用 ORBIT_SKIP_SOURCE；正常示例验证当前来源接口。
+	if os.Getenv("ORBIT_SKIP_SOURCE") == "" {
+		origin, err := client.GetTaskSource(ctx, current.ID)
+		if err != nil {
+			return err
+		}
+		if origin.Kind != "DIRECT" {
+			return fmt.Errorf("expected direct task source")
+		}
+		fmt.Printf("source_kind=%s\n", origin.Kind)
+	}
+	fmt.Printf("task=%s duplicate=%t listed=%d final_state=%s revision=%d\n", current.ID, again.Deduplicated, len(page.Items), cancelled.Task.State, cancelled.Task.Revision)
+	if cancelled.Task.State != orbit.TaskCancelled {
+		return fmt.Errorf("expected CANCELLED")
+	}
+	return nil
+}