fix(cli): cap compact structured output

Author: ysyneu

internal/cli/alert_event.go

@@ -90,6 +90,9 @@ func newAlertEventListCmd() *cobra.Command {
 					if err != nil {
 						return err
 					}
+					if err := boundProjectedOutput(proj, compactListOutputLimit); err != nil {
+						return err
+					}
 					return ctx.PrintList(proj, nil, len(result.Items), page, int(result.Total))
 				}
 
@@ -106,7 +109,7 @@ func newAlertEventListCmd() *cobra.Command {
 	cmd.Flags().StringVar(&until, "until", "now", "End time")
 	cmd.Flags().IntVar(&limit, "limit", 20, "Max results")
 	cmd.Flags().IntVar(&page, "page", 1, "Page number")
-	cmd.Flags().StringVar(&fields, "fields", "", "Comma-separated fields to project in json/toon output (e.g. event_id,alert_id,event_severity,event_status,event_time,title); ignored in table mode. Defaults to these compact event fields.")
+	cmd.Flags().StringVar(&fields, "fields", "", "Comma-separated fields to project in json/toon output (e.g. event_id,alert_id,event_severity,event_status,event_time,title); ignored in table mode. Defaults to these compact event fields. Long strings are truncated as needed to keep structured output below 16 KiB.")
 
 	return cmd
 }

internal/cli/fieldproject.go

@@ -5,6 +5,12 @@ import (
 	"reflect"
 	"sort"
 	"strings"
+	"unicode/utf8"
+)
+
+const (
+	compactListOutputLimit   = 16 * 1024
+	compactDetailOutputLimit = 8 * 1024
 )
 
 // projectFields reduces each struct element of items to a map containing only
@@ -63,6 +69,89 @@ func projectFields(items any, fields []string) ([]map[string]any, error) {
 	return out, nil
 }
 
+// boundProjectedOutput keeps the new agent-oriented projections below their
+// command budget without changing the selected keys. Short values remain byte
+// identical; when retained strings alone would overflow the actual JSON/TOON
+// encoding, they are shortened fairly and marked with "...". If keys and
+// non-string values alone exceed the budget, the command fails with a small
+// error instead of emitting an oversized payload.
+func boundProjectedOutput(data any, maxBytes int) error {
+	var rows []map[string]any
+	switch value := data.(type) {
+	case map[string]any:
+		rows = []map[string]any{value}
+	case []map[string]any:
+		rows = value
+	default:
+		return fmt.Errorf("internal error: unsupported projected output %T", data)
+	}
+
+	encoded, err := marshalStructured(data)
+	if err != nil {
+		return err
+	}
+	if len(encoded)+1 < maxBytes {
+		return nil
+	}
+
+	stringCount := 0
+	for _, row := range rows {
+		for _, value := range row {
+			if _, ok := value.(string); ok {
+				stringCount++
+			}
+		}
+	}
+	if stringCount == 0 {
+		return fmt.Errorf("structured projection exceeds %d-byte limit; request fewer rows or fields", maxBytes)
+	}
+
+	fieldLimit := maxBytes / stringCount
+	for {
+		for _, row := range rows {
+			for key, value := range row {
+				if text, ok := value.(string); ok {
+					row[key] = truncateUTF8Bytes(text, fieldLimit)
+				}
+			}
+		}
+
+		encoded, err = marshalStructured(data)
+		if err != nil {
+			return err
+		}
+		if len(encoded)+1 < maxBytes {
+			return nil
+		}
+		if fieldLimit == 0 {
+			return fmt.Errorf("structured projection exceeds %d-byte limit; request fewer rows or fields", maxBytes)
+		}
+		fieldLimit /= 2
+	}
+}
+
+func truncateUTF8Bytes(value string, maxBytes int) string {
+	if len(value) <= maxBytes {
+		return value
+	}
+	if maxBytes <= 0 {
+		return ""
+	}
+	if maxBytes <= 3 {
+		end := maxBytes
+		for end > 0 && !utf8.ValidString(value[:end]) {
+			end--
+		}
+		return value[:end]
+	}
+
+	end := maxBytes - 3
+	for end > 0 && !utf8.ValidString(value[:end]) {
+		end--
+	}
+	return value[:end] + "..."
+}
+
 // jsonTagIndex maps each exported field's json tag name (leading component, sans
 // `,omitempty`) to its index in the struct. Fields tagged `json:"-"`, untagged
 // fields, and embedded/anonymous fields are skipped — only declared, named,

internal/cli/fieldproject_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"strings"
 	"testing"
+	"unicode/utf8"
 
 	"github.com/spf13/cobra"
 )
@@ -28,6 +29,48 @@ func incidentRow() map[string]any {
 	}
 }
 
+func TestBoundProjectedOutputCapsStructuredFormats(t *testing.T) {
+	for _, format := range []string{"json", "toon"} {
+		t.Run(format, func(t *testing.T) {
+			saveAndResetGlobals(t)
+			flagOutputFormat = format
+			rows := []map[string]any{{
+				"incident_id": "inc-1",
+				"title":       strings.Repeat("数据库故障", 2000),
+			}}
+
+			if err := boundProjectedOutput(rows, 512); err != nil {
+				t.Fatalf("bound projected output: %v", err)
+			}
+			encoded, err := marshalStructured(rows)
+			if err != nil {
+				t.Fatalf("marshal bounded output: %v", err)
+			}
+			if len(encoded)+1 >= 512 {
+				t.Fatalf("bounded %s output is %d bytes, want <512", format, len(encoded)+1)
+			}
+			title := rows[0]["title"].(string)
+			if !utf8.ValidString(title) || !strings.HasSuffix(title, "...") {
+				t.Fatalf("truncated title = %q, want valid UTF-8 with marker", title)
+			}
+		})
+	}
+}
+
+func TestBoundProjectedOutputRejectsIrreducibleMetadata(t *testing.T) {
+	saveAndResetGlobals(t)
+	flagOutputFormat = "json"
+	rows := make([]map[string]any, 200)
+	for i := range rows {
+		rows[i] = map[string]any{"count": i}
+	}
+
+	err := boundProjectedOutput(rows, 512)
+	if err == nil || !strings.Contains(err.Error(), "request fewer rows or fields") {
+		t.Fatalf("irreducible output error = %v, want bounded guidance", err)
+	}
+}
+
 func alertRow() map[string]any {
 	return map[string]any{
 		"alert_id":       "al-1",
@@ -249,7 +292,8 @@ func TestIncidentSimilarStructuredProjection(t *testing.T) {
 		row["close_time"] = 1712000060
 		row["ack_time"] = 1712000030
 		row["alert_cnt"] = 3
-		row["root_cause"] = "disk exhaustion"
+		row["title"] = strings.Repeat("very long incident title ", 2000)
+		row["root_cause"] = strings.Repeat("disk exhaustion details ", 2000)
 		row["score"] = 0.9
 		row["description"] = strings.Repeat("large description ", 100)
 		row["images"] = []map[string]any{{"src": strings.Repeat("https://example.test/image/", 100)}}
@@ -295,6 +339,9 @@ func TestIncidentDetailFieldsProjection(t *testing.T) {
 	row := incidentRow()
 	row["description"] = strings.Repeat("large description ", 500)
 	row["images"] = []map[string]any{{"src": strings.Repeat("https://example.test/image/", 100)}}
+	row["ai_summary"] = strings.Repeat("long AI summary ", 4000)
+	row["root_cause"] = strings.Repeat("long root cause ", 4000)
+	row["resolution"] = strings.Repeat("long resolution ", 4000)
 	stub.data = row
 
 	fields := []string{"incident_id", "title", "incident_severity", "progress", "ai_summary", "root_cause", "resolution", "alert_cnt", "start_time", "channel_id"}
@@ -334,7 +381,7 @@ func TestAlertEventListStructuredProjection(t *testing.T) {
 			"event_severity": "Warning",
 			"event_status":   "Triggered",
 			"event_time":     1712000000,
-			"title":          "CPU high",
+			"title":          strings.Repeat("very long alert event title ", 2000),
 			"description":    strings.Repeat("large description ", 100),
 			"labels":         map[string]any{"host": "web-01"},
 			"images":         []map[string]any{{"src": strings.Repeat("https://example.test/image/", 100)}},

internal/cli/incident.go

@@ -600,6 +600,9 @@ func newIncidentSimilarCmd() *cobra.Command {
 					if err != nil {
 						return err
 					}
+					if err := boundProjectedOutput(proj, compactListOutputLimit); err != nil {
+						return err
+					}
 					return ctx.Printer.Print(proj, nil)
 				}
 
@@ -609,7 +612,7 @@ func newIncidentSimilarCmd() *cobra.Command {
 	}
 
 	cmd.Flags().IntVar(&limit, "limit", 5, "Max results")
-	cmd.Flags().StringVar(&fields, "fields", "", "Comma-separated fields to project in json/toon output (e.g. incident_id,title,incident_severity,progress,start_time); ignored in table mode. Defaults to a compact incident summary.")
+	cmd.Flags().StringVar(&fields, "fields", "", "Comma-separated fields to project in json/toon output (e.g. incident_id,title,incident_severity,progress,start_time); ignored in table mode. Defaults to a compact incident summary. Long strings are truncated as needed to keep structured output below 16 KiB.")
 	return cmd
 }
 
@@ -1353,6 +1356,9 @@ func newIncidentDetailCmd() *cobra.Command {
 						if err != nil {
 							return err
 						}
+						if err := boundProjectedOutput(proj[0], compactDetailOutputLimit); err != nil {
+							return err
+						}
 						return ctx.Printer.Print(proj[0], nil)
 					}
 					return ctx.Printer.Print(result, nil)
@@ -1363,7 +1369,7 @@ func newIncidentDetailCmd() *cobra.Command {
 			})
 		},
 	}
-	cmd.Flags().StringVar(&fields, "fields", "", "Comma-separated fields to project in json/toon output (e.g. incident_id,title,incident_severity,progress,root_cause); ignored in table mode. Omit for full detail.")
+	cmd.Flags().StringVar(&fields, "fields", "", "Comma-separated fields to project in json/toon output (e.g. incident_id,title,incident_severity,progress,root_cause); ignored in table mode. Projected strings are truncated as needed to keep output below 8 KiB; omit --fields for full detail.")
 	return cmd
 }
 

skills/flashduty/reference/alert.md

@@ -38,6 +38,8 @@ fduty alert feed <alert-id> --output-format toon
 fduty alert-event list --channel <channel-id> --since 1h --limit 30 --output-format toon
 ```
 
+Structured `alert-event list` output stays below 16 KiB. A trailing `...` means a long retained string was shortened.
+
 ## Hot flow — merge noisy alerts into an existing incident
 
 ```bash

skills/flashduty/reference/incident.md

@@ -63,6 +63,8 @@ fduty incident comment <incident-id> --comment "Root cause identified: DB failov
 fduty incident resolve <incident-id> --root-cause "DB primary failover delay" --resolution "Failover completed; latency normal."
 ```
 
+Projected `similar` lists stay below 16 KiB, and projected `detail --fields` output stays below 8 KiB. A trailing `...` means a long retained string was shortened; omit `--fields` only when the full unbounded detail is explicitly required.
+
 ## Hot flow — full fault analysis (read-only summary)
 
 When asked to **summarize / analyze** an incident — 详情 + 关联告警 + 变更 + 时间线 + 相似故障 + 复盘 — `incident detail` does **not** contain the alerts / timeline / similar / post-mortem / change data; each is its own command. **Your first action must be the bundled script** — do not hand-pick one or two commands and write the rest from memory. One call fetches all six aspects: