feat: AI 优先的 search 增强与结构化输出 (v0.4.0)

- search: 新增 --name、-f/--field、-o/--output、--summary、--limit、--offset、--sort
- search: 非 TTY 自动输出 json-compact，便于 AI 解析
- search: -f secret.* 自动解锁 secrets
- add: 支持 -o json/json-compact 输出
- add: 重构为 AddArgs 结构体
- 全局: 各子命令 after_help 补充典型值示例
- output.rs: OutputMode 枚举 + TTY 检测
- 文档: README/AGENTS 面向 AI 的用法，连接串改为 <host>:<port>

Made-with: Cursor

src/commands/search.rs

@@ -1,36 +1,51 @@
 use anyhow::Result;
+use serde_json::{Value, json};
 use sqlx::PgPool;
 
 use crate::models::Secret;
+use crate::output::OutputMode;
 
-pub async fn run(
-    pool: &PgPool,
-    namespace: Option<&str>,
-    kind: Option<&str>,
-    tag: Option<&str>,
-    query: Option<&str>,
-    show_secrets: bool,
-) -> Result<()> {
+pub struct SearchArgs<'a> {
+    pub namespace: Option<&'a str>,
+    pub kind: Option<&'a str>,
+    pub name: Option<&'a str>,
+    pub tag: Option<&'a str>,
+    pub query: Option<&'a str>,
+    pub show_secrets: bool,
+    pub fields: &'a [String],
+    pub summary: bool,
+    pub limit: u32,
+    pub offset: u32,
+    pub sort: &'a str,
+    pub output: OutputMode,
+}
+
+pub async fn run(pool: &PgPool, args: SearchArgs<'_>) -> Result<()> {
     let mut conditions: Vec<String> = Vec::new();
     let mut idx: i32 = 1;
 
-    if namespace.is_some() {
+    if args.namespace.is_some() {
         conditions.push(format!("namespace = ${}", idx));
         idx += 1;
     }
-    if kind.is_some() {
+    if args.kind.is_some() {
         conditions.push(format!("kind = ${}", idx));
         idx += 1;
     }
-    if tag.is_some() {
+    if args.name.is_some() {
+        conditions.push(format!("name = ${}", idx));
+        idx += 1;
+    }
+    if args.tag.is_some() {
         conditions.push(format!("tags @> ARRAY[${}]", idx));
         idx += 1;
     }
-    if query.is_some() {
+    if args.query.is_some() {
         conditions.push(format!(
             "(name ILIKE ${i} OR namespace ILIKE ${i} OR kind ILIKE ${i} OR metadata::text ILIKE ${i} OR EXISTS (SELECT 1 FROM unnest(tags) t WHERE t ILIKE ${i}))",
             i = idx
         ));
+        idx += 1;
     }
 
     let where_clause = if conditions.is_empty() {
@@ -39,49 +54,166 @@ pub async fn run(
         format!("WHERE {}", conditions.join(" AND "))
     };
 
+    let order = match args.sort {
+        "updated" => "updated_at DESC",
+        "created" => "created_at DESC",
+        _ => "namespace, kind, name",
+    };
+
     let sql = format!(
-        "SELECT * FROM secrets {} ORDER BY namespace, kind, name",
-        where_clause
+        "SELECT * FROM secrets {} ORDER BY {} LIMIT ${} OFFSET ${}",
+        where_clause,
+        order,
+        idx,
+        idx + 1
     );
 
     tracing::debug!(sql, "executing search query");
 
     let mut q = sqlx::query_as::<_, Secret>(&sql);
-    if let Some(v) = namespace {
+    if let Some(v) = args.namespace {
         q = q.bind(v);
     }
-    if let Some(v) = kind {
+    if let Some(v) = args.kind {
         q = q.bind(v);
     }
-    if let Some(v) = tag {
+    if let Some(v) = args.name {
         q = q.bind(v);
     }
-    if let Some(v) = query {
+    if let Some(v) = args.tag {
+        q = q.bind(v);
+    }
+    if let Some(v) = args.query {
         q = q.bind(format!("%{}%", v));
     }
+    q = q.bind(args.limit as i64).bind(args.offset as i64);
 
     let rows = q.fetch_all(pool).await?;
 
-    if rows.is_empty() {
-        println!("No records found.");
-        return Ok(());
+    // -f/--field: extract specific field values directly
+    if !args.fields.is_empty() {
+        return print_fields(&rows, args.fields);
     }
 
-    for row in &rows {
-        println!("[{}/{}] {}", row.namespace, row.kind, row.name,);
-        println!("  id:       {}", row.id);
+    match args.output {
+        OutputMode::Json | OutputMode::JsonCompact => {
+            let arr: Vec<Value> = rows
+                .iter()
+                .map(|r| to_json(r, args.show_secrets, args.summary))
+                .collect();
+            let out = if args.output == OutputMode::Json {
+                serde_json::to_string_pretty(&arr)?
+            } else {
+                serde_json::to_string(&arr)?
+            };
+            println!("{}", out);
+        }
+        OutputMode::Env => {
+            if rows.len() > 1 {
+                anyhow::bail!(
+                    "env output requires exactly one record; got {}. Add more filters.",
+                    rows.len()
+                );
+            }
+            if let Some(row) = rows.first() {
+                print_env(row, args.show_secrets)?;
+            } else {
+                eprintln!("No records found.");
+            }
+        }
+        OutputMode::Text => {
+            if rows.is_empty() {
+                println!("No records found.");
+                return Ok(());
+            }
+            for row in &rows {
+                print_text(row, args.show_secrets, args.summary)?;
+            }
+            println!("{} record(s) found.", rows.len());
+            if rows.len() == args.limit as usize {
+                println!(
+                    "  (showing up to {}; use --offset {} to see more)",
+                    args.limit,
+                    args.offset + args.limit
+                );
+            }
+        }
+    }
 
+    Ok(())
+}
+
+fn to_json(row: &Secret, show_secrets: bool, summary: bool) -> Value {
+    if summary {
+        let desc = row
+            .metadata
+            .get("desc")
+            .or_else(|| row.metadata.get("url"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        return json!({
+            "namespace": row.namespace,
+            "kind": row.kind,
+            "name": row.name,
+            "tags": row.tags,
+            "desc": desc,
+            "updated_at": row.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+        });
+    }
+
+    let secrets_val = if show_secrets {
+        row.encrypted.clone()
+    } else {
+        let keys: Vec<&str> = row
+            .encrypted
+            .as_object()
+            .map(|m| m.keys().map(|k| k.as_str()).collect())
+            .unwrap_or_default();
+        json!({"_hidden_keys": keys})
+    };
+
+    json!({
+        "id": row.id,
+        "namespace": row.namespace,
+        "kind": row.kind,
+        "name": row.name,
+        "tags": row.tags,
+        "metadata": row.metadata,
+        "secrets": secrets_val,
+        "created_at": row.created_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+        "updated_at": row.updated_at.format("%Y-%m-%dT%H:%M:%SZ").to_string(),
+    })
+}
+
+fn print_text(row: &Secret, show_secrets: bool, summary: bool) -> Result<()> {
+    println!("[{}/{}] {}", row.namespace, row.kind, row.name);
+    if summary {
+        let desc = row
+            .metadata
+            .get("desc")
+            .or_else(|| row.metadata.get("url"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("-");
+        if !row.tags.is_empty() {
+            println!("  tags:    [{}]", row.tags.join(", "));
+        }
+        println!("  desc:    {}", desc);
+        println!(
+            "  updated: {}",
+            row.updated_at.format("%Y-%m-%d %H:%M:%S UTC")
+        );
+    } else {
+        println!("  id:       {}", row.id);
         if !row.tags.is_empty() {
             println!("  tags:     [{}]", row.tags.join(", "));
         }
-
         if row.metadata.as_object().is_some_and(|m| !m.is_empty()) {
             println!(
                 "  metadata: {}",
                 serde_json::to_string_pretty(&row.metadata)?
             );
         }
-
         if show_secrets {
             println!(
                 "  secrets:  {}",
@@ -100,13 +232,73 @@ pub async fn run(
                 );
             }
         }
-
         println!(
             "  created:  {}",
             row.created_at.format("%Y-%m-%d %H:%M:%S UTC")
         );
-        println!();
     }
-    println!("{} record(s) found.", rows.len());
+    println!();
     Ok(())
 }
+
+fn print_env(row: &Secret, show_secrets: bool) -> Result<()> {
+    let prefix = row.name.to_uppercase().replace(['-', '.'], "_");
+    if let Some(meta) = row.metadata.as_object() {
+        for (k, v) in meta {
+            let key = format!("{}_{}", prefix, k.to_uppercase().replace('-', "_"));
+            println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
+        }
+    }
+    if show_secrets && let Some(enc) = row.encrypted.as_object() {
+        for (k, v) in enc {
+            let key = format!("{}_{}", prefix, k.to_uppercase().replace('-', "_"));
+            println!("{}={}", key, v.as_str().unwrap_or(&v.to_string()));
+        }
+    }
+    Ok(())
+}
+
+/// Extract one or more field paths like `metadata.url` or `secret.token`.
+fn print_fields(rows: &[Secret], fields: &[String]) -> Result<()> {
+    for row in rows {
+        for field in fields {
+            let val = extract_field(row, field)?;
+            println!("{}", val);
+        }
+    }
+    Ok(())
+}
+
+fn extract_field(row: &Secret, field: &str) -> Result<String> {
+    let (section, key) = field.split_once('.').ok_or_else(|| {
+        anyhow::anyhow!(
+            "Invalid field path '{}'. Use metadata.<key> or secret.<key>",
+            field
+        )
+    })?;
+
+    let obj = match section {
+        "metadata" | "meta" => &row.metadata,
+        "secret" | "secrets" | "encrypted" => &row.encrypted,
+        other => anyhow::bail!(
+            "Unknown field section '{}'. Use 'metadata' or 'secret'",
+            other
+        ),
+    };
+
+    obj.get(key)
+        .and_then(|v| {
+            v.as_str()
+                .map(|s| s.to_string())
+                .or_else(|| Some(v.to_string()))
+        })
+        .ok_or_else(|| {
+            anyhow::anyhow!(
+                "Field '{}' not found in record [{}/{}/{}]",
+                field,
+                row.namespace,
+                row.kind,
+                row.name
+            )
+        })
+}