feat: add execution history queries and preserve bounded JSON payloads

sdk/go/history.go

@@ -0,0 +1,95 @@
+package orbit
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"strconv"
+)
+
+func historyResourcePath(ids ...string) (string, error) {
+	for _, id := range ids {
+		if !validID(id) {
+			return "", errors.New("invalid history resource id")
+		}
+	}
+	path := "/v1/tasks/" + ids[0] + "/attempts"
+	if len(ids) > 1 {
+		path += "/" + ids[1] + "/evidence"
+	}
+	if len(ids) > 2 {
+		path += "/" + ids[2]
+	}
+	return path, nil
+}
+func historyPageQuery(in HistoryPageRequest) (string, error) {
+	if in.Limit < 0 || in.Limit > 100 || len(in.Cursor) > 1024 {
+		return "", errors.New("invalid history limit or cursor")
+	}
+	q := url.Values{}
+	if in.Limit > 0 {
+		q.Set("limit", strconv.Itoa(in.Limit))
+	}
+	if in.Cursor != "" {
+		q.Set("cursor", in.Cursor)
+	}
+	if len(q) == 0 {
+		return "", nil
+	}
+	return "?" + q.Encode(), nil
+}
+
+// ListTaskAttempts 按执行代次降序读取摘要；当前查询不会授予执行权。
+func (c *Client) ListTaskAttempts(ctx context.Context, taskID string, in HistoryPageRequest) (AttemptPage, error) {
+	var out AttemptPage
+	path, err := historyResourcePath(taskID)
+	if err != nil {
+		return out, err
+	}
+	query, err := historyPageQuery(in)
+	if err != nil {
+		return out, err
+	}
+	err = c.call(ctx, "GET", path+query, "", nil, &out)
+	return out, err
+}
+
+// GetTaskAttempt 获取当前归属及已保存结果，不提供执行秘密或执行授权。
+func (c *Client) GetTaskAttempt(ctx context.Context, taskID, attemptID string) (Attempt, error) {
+	var out Attempt
+	if !validID(attemptID) {
+		return out, errors.New("invalid attempt id")
+	}
+	path, err := historyResourcePath(taskID)
+	if err != nil {
+		return out, err
+	}
+	err = c.call(ctx, "GET", path+"/"+attemptID, "", nil, &out)
+	return out, err
+}
+
+// ListAttemptEvidence 列出原先仅保存为证据的报告，不把声明结果提升为权威结果。
+func (c *Client) ListAttemptEvidence(ctx context.Context, taskID, attemptID string, in HistoryPageRequest) (AttemptEvidencePage, error) {
+	var out AttemptEvidencePage
+	path, err := historyResourcePath(taskID, attemptID)
+	if err != nil {
+		return out, err
+	}
+	query, err := historyPageQuery(in)
+	if err != nil {
+		return out, err
+	}
+	err = c.call(ctx, "GET", path+query, "", nil, &out)
+	return out, err
+}
+
+// GetAttemptEvidence 读取单条原报告正文，不改变任务或尝试的权威状态。
+func (c *Client) GetAttemptEvidence(ctx context.Context, taskID, attemptID, evidenceID string) (AttemptEvidence, error) {
+	var out AttemptEvidence
+	path, err := historyResourcePath(taskID, attemptID, evidenceID)
+	if err != nil {
+		return out, err
+	}
+	err = c.call(ctx, "GET", path, "", nil, &out)
+	return out, err
+}