feat: per-request prompt_traits injection layer (#17)

* feat(core): add PromptTrait + extend Event::UserMessage with prompt_traits

* feat(prompt): render 【附加指引】 section from prompt_traits

* refactor(handlers): import PromptTrait + comment GiftHandler &[] rationale

* feat(routes): add PromptTraitDto + validate_prompt_traits

* feat(routes): thread prompt_traits through /message + /message_async with tracing

* test(routes): integration tests for prompt_traits validation

* chore(openapi): regenerate snapshot for prompt_traits

* docs(api): document prompt_traits on /message + /message_async

* docs: add prompt-traits reference (EN + ZH)

* docs(readme): mention prompt_traits on message routes

* chore: cargo fmt

* fix(validate): reject U+2028/2029 + trim text before length check

Author: enriquephl

README.md

@@ -194,6 +194,9 @@ Highlights:
 - `GET  /comp/user/{user_id}/profile` — current `companion_insights` and `training_level`.
 - `POST /comp/chat/{session_id}/event/gift` — apply an out-of-band gift event and affinity delta.
 - `GET  /comp/chat/{session_id}/gifts` — list gift events for a session.
+- `POST /comp/chat/{session_id}/message` and `/message_async` accept an optional
+  `prompt_traits` field for per-request system-prompt injection — see
+  [docs/prompt-traits.md](docs/prompt-traits.md).
 - `GET  /comp/affinity/{session_id}` — debug-only live affinity vector, enabled by `EXPOSE_AFFINITY_DEBUG=true`.
 
 The `AuthValidator` trait is pluggable if you use a different identity provider.
@@ -228,7 +231,16 @@ If you are building a different product, the reusable part is the affinity + mem
 
 ## Content note
 
-The example personas under `examples/personas/` are written as adult character-chat examples. They can flirt and express desire when the relationship state reaches that point, while still refusing disrespectful or boundary-crossing behavior. If your product needs a SFW default, replace those persona files before deploying.
+The example personas under `examples/personas/` are written as adult
+character-chat examples. They can flirt and express desire when the
+relationship state reaches that point, while still refusing disrespectful or
+boundary-crossing behavior. If your product needs a SFW default, replace
+those persona files before deploying.
+
+Per-request behaviour can be further modulated via the
+[`prompt_traits`](docs/prompt-traits.md) field on the message routes —
+the engine treats the supplied text as opaque, so the policy of what
+those traits encode lives entirely in your frontend / middleware.
 
 ## Contributing
 

README.zh.md

@@ -154,6 +154,9 @@ Server 默認監聽 `0.0.0.0:8080`。Scalar API docs 在 `/docs`，OpenAPI JSON
 - `GET  /comp/user/{user_id}/profile`——讀取目前的 `companion_insights` 和 `training_level`。
 - `POST /comp/chat/{session_id}/event/gift`——套用外部 gift event 與 affinity delta。
 - `GET  /comp/chat/{session_id}/gifts`——列出某個 session 的 gift events。
+- `POST /comp/chat/{session_id}/message` 與 `/message_async` 接受可選的
+  `prompt_traits` 欄位，用於 per-request system-prompt 注入——詳見
+  [docs/prompt-traits.md](docs/prompt-traits.md)。
 - `GET  /comp/affinity/{session_id}`——debug-only 即時 affinity vector，由 `EXPOSE_AFFINITY_DEBUG=true` 開啟。
 
 如果你不用 Supabase，可以實現 `AuthValidator` trait 接自己的 identity provider。
@@ -187,6 +190,11 @@ Server 默認監聽 `0.0.0.0:8080`。Scalar API docs 在 `/docs`，OpenAPI JSON
 
 `examples/personas/` 裡的人格是成人 character-chat 示例。當 relationship state 走到相應位置，它們可以調情、表達慾望；同時仍會拒絕不尊重或越界的要求。如果你的產品需要 SFW default，部署前請替換這些 persona files。
 
+每一輪的行為還可以透過 message routes 上的
+[`prompt_traits`](docs/prompt-traits.md) 欄位再調整——engine 把傳入的文字
+當成 opaque string 處理，這些 traits 實際代表什麼策略，完全交給你的
+frontend / middleware 決定。
+
 ## 貢獻
 
 請先閱讀 [`CONTRIBUTING.md`](CONTRIBUTING.md)。所有貢獻者首次提 PR 時都需要透過 cla-assistant.io 接受 [`CLA`](CLA.md)。

crates/eros-engine-core/src/pde.rs

@@ -206,6 +206,7 @@ mod tests {
         Event::UserMessage {
             content: content.into(),
             message_id: Uuid::new_v4(),
+            prompt_traits: Vec::new(),
         }
     }
 

crates/eros-engine-core/src/types.rs

@@ -7,11 +7,32 @@ use uuid::Uuid;
 use crate::affinity::{Affinity, AffinityDeltas};
 use crate::persona::CompanionPersona;
 
+/// A caller-supplied system-prompt fragment. The engine treats `text` as
+/// opaque — it is inserted verbatim under the `【附加指引】` section of
+/// the persona system prompt. `tag` is for logging/observability only and
+/// is constrained to `[a-z0-9_]{1,32}` by the HTTP layer.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PromptTrait {
+    pub tag: String,
+    pub text: String,
+}
+
 /// Events that drive the engine pipeline.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum Event {
-    UserMessage { content: String, message_id: Uuid },
-    Gift { gift_id: Uuid, amount: i64 },
+    UserMessage {
+        content: String,
+        message_id: Uuid,
+        /// Optional caller-supplied prompt traits. Empty for clients that
+        /// don't send the field — preserves the legacy system-prompt output
+        /// byte-for-byte.
+        #[serde(default)]
+        prompt_traits: Vec<PromptTrait>,
+    },
+    Gift {
+        gift_id: Uuid,
+        amount: i64,
+    },
     ProactiveTrigger,
     AppOpen,
 }
@@ -68,3 +89,31 @@ pub struct DecisionInput {
     pub persona: CompanionPersona,
     pub signals: ConversationSignals,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn event_user_message_defaults_prompt_traits_to_empty_vec() {
+        let raw = r#"{"UserMessage":{"content":"hi","message_id":"00000000-0000-0000-0000-000000000001"}}"#;
+        let ev: Event = serde_json::from_str(raw).expect("legacy body deserialises");
+        match ev {
+            Event::UserMessage { prompt_traits, .. } => {
+                assert!(prompt_traits.is_empty(), "missing field must default to []");
+            }
+            _ => panic!("expected UserMessage"),
+        }
+    }
+
+    #[test]
+    fn prompt_trait_round_trips_through_serde() {
+        let t = PromptTrait {
+            tag: "nsfw_boost".into(),
+            text: "be more daring".into(),
+        };
+        let json = serde_json::to_string(&t).unwrap();
+        let back: PromptTrait = serde_json::from_str(&json).unwrap();
+        assert_eq!(back, t);
+    }
+}

crates/eros-engine-server/openapi.json

@@ -1193,6 +1193,24 @@
           }
         }
       },
+      "PromptTraitDto": {
+        "type": "object",
+        "description": "Caller-supplied prompt-injection fragment. See `docs/prompt-traits.md`.",
+        "required": [
+          "tag",
+          "text"
+        ],
+        "properties": {
+          "tag": {
+            "type": "string",
+            "description": "ASCII identifier, regex `^[a-z0-9_]{1,32}$`. Used for logging."
+          },
+          "text": {
+            "type": "string",
+            "description": "Verbatim text inserted under `【附加指引】` in the system prompt.\n1 ≤ chars ≤ 2000 after trim."
+          }
+        }
+      },
       "SendMessageRequest": {
         "type": "object",
         "required": [
@@ -1201,6 +1219,16 @@
         "properties": {
           "message": {
             "type": "string"
+          },
+          "prompt_traits": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/PromptTraitDto"
+            },
+            "description": "Optional caller-supplied prompt-injection fragments. See\n`docs/prompt-traits.md`. Missing field → empty list."
           }
         }
       },

crates/eros-engine-server/src/pipeline/handlers.rs

@@ -22,7 +22,7 @@ use sqlx::PgPool;
 use uuid::Uuid;
 
 use eros_engine_core::affinity::AffinityDeltas;
-use eros_engine_core::types::{ActionPlan, DecisionInput, Event};
+use eros_engine_core::types::{ActionPlan, DecisionInput, Event, PromptTrait};
 use eros_engine_llm::openrouter::{ChatMessage, ChatRequest};
 use eros_engine_store::chat::ChatRepo;
 use eros_engine_store::insight::InsightRepo;
@@ -355,6 +355,11 @@ impl<'a> ActionHandler for ReplyHandler<'a> {
         // Reply path never has pending gifts — those flow through GiftHandler.
         let pending_gifts: Vec<PendingGift> = vec![];
 
+        let prompt_traits: &[PromptTrait] = match &input.event {
+            Event::UserMessage { prompt_traits, .. } => prompt_traits.as_slice(),
+            _ => &[],
+        };
+
         let system_prompt = build_prompt(
             &input.persona,
             &profile_groups,
@@ -364,6 +369,7 @@ impl<'a> ActionHandler for ReplyHandler<'a> {
             tip_personality,
             plan.reply_style,
             &plan.context_hints,
+            prompt_traits,
         );
 
         Ok(Some(assemble_chat_request(
@@ -461,6 +467,7 @@ impl<'a> ActionHandler for GiftHandler<'a> {
             .as_deref()
             .unwrap_or("normal");
 
+        // Gift path: prompt_traits flow only from UserMessage; ignore for gift reactions.
         let system_prompt = build_prompt(
             &input.persona,
             &profile_groups,
@@ -470,6 +477,7 @@ impl<'a> ActionHandler for GiftHandler<'a> {
             tip_personality,
             plan.reply_style,
             &plan.context_hints,
+            &[],
         );
 
         Ok(Some(assemble_chat_request(

crates/eros-engine-server/src/pipeline/mod.rs

@@ -73,6 +73,18 @@ pub async fn run(
         plan.reply_style,
     );
 
+    if let Event::UserMessage { prompt_traits, .. } = &event {
+        if !prompt_traits.is_empty() {
+            let tags: Vec<&str> = prompt_traits.iter().map(|t| t.tag.as_str()).collect();
+            tracing::info!(
+                session = %session_id,
+                traits_count = prompt_traits.len(),
+                trait_tags = ?tags,
+                "engine: prompt_traits applied"
+            );
+        }
+    }
+
     // 7. Dispatch to handler. The Gift branch passes `plan.affinity_deltas`
     // through; T11 will replace this with deltas supplied directly by the
     // `/comp/chat/{id}/event/gift` route's request body, since the OSS

crates/eros-engine-server/src/prompt.rs

@@ -27,6 +27,7 @@ use chrono::{Timelike, Utc};
 
 use eros_engine_core::affinity::Affinity;
 use eros_engine_core::persona::CompanionPersona;
+use eros_engine_core::types::PromptTrait;
 use eros_engine_core::types::ReplyStyle;
 
 /// A pending gift/tip that the prompt builder must surface to the LLM.
@@ -216,6 +217,7 @@ pub fn build_prompt(
     tip_personality: &str,
     style: ReplyStyle,
     hints: &[String],
+    prompt_traits: &[PromptTrait],
 ) -> String {
     let name = persona.genome.name.as_str();
     let age = meta_i32(persona, "age")
@@ -229,6 +231,17 @@ pub fn build_prompt(
     let topics_str =
         meta_string_array_joined(persona, "topics").unwrap_or_else(|| "日常生活、感情观".into());
 
+    let traits_section = if prompt_traits.is_empty() {
+        String::new()
+    } else {
+        let bullets = prompt_traits
+            .iter()
+            .map(|t| format!("- {}", t.text))
+            .collect::<Vec<_>>()
+            .join("\n");
+        format!("\n\n【附加指引】\n{bullets}")
+    };
+
     let non_empty_groups: Vec<&(String, Vec<String>)> = profile_groups
         .iter()
         .filter(|(_, items)| !items.is_empty())
@@ -294,7 +307,7 @@ pub fn build_prompt(
          \n\
          【说话风格】{speech_style}\n\
          【口癖/习惯】{quirks_str}\n\
-         【擅长话题】{topics_str}\n\
+         【擅长话题】{topics_str}{traits_section}\n\
          \n\
          【今日情境】\n{tc}\n\
          \n\
@@ -436,6 +449,122 @@ pub fn extract_structured_insights_prompt(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use uuid::Uuid;
+
+    fn fixture_persona() -> CompanionPersona {
+        use eros_engine_core::persona::{PersonaGenome, PersonaInstance};
+        let uid = Uuid::nil();
+        CompanionPersona {
+            instance_id: uid,
+            genome: PersonaGenome {
+                id: uid,
+                name: "Aria".into(),
+                system_prompt: "p".into(),
+                tip_personality: Some("normal".into()),
+                avatar_url: None,
+                art_metadata: serde_json::json!({
+                    "age": 24,
+                    "mbti": "INFP",
+                    "backstory": "back",
+                    "speech_style": "soft",
+                    "quirks": ["q1"],
+                    "topics": ["t1"]
+                }),
+                is_active: true,
+            },
+            instance: PersonaInstance {
+                id: uid,
+                genome_id: uid,
+                owner_uid: uid,
+                status: "active".into(),
+            },
+        }
+    }
+
+    #[test]
+    fn build_prompt_with_empty_traits_omits_section_and_preserves_layout() {
+        let p = build_prompt(
+            &fixture_persona(),
+            &[],
+            &[],
+            None,
+            &[],
+            "normal",
+            ReplyStyle::Neutral,
+            &[],
+            &[],
+        );
+        assert!(
+            !p.contains("【附加指引】"),
+            "empty traits must not render section"
+        );
+        // Byte-level invariant proving "byte-for-byte identical to legacy"
+        // for the empty-traits case: topics → time-context joins with the
+        // pre-existing `\n\n` separator, no leftover whitespace from the
+        // new `{traits_section}` placeholder.
+        assert!(
+            p.contains("【擅长话题】t1\n\n【今日情境】"),
+            "topics → time-context separator must be exactly '\\n\\n'"
+        );
+    }
+
+    #[test]
+    fn build_prompt_renders_traits_as_bullets_under_label() {
+        let traits = vec![
+            PromptTrait {
+                tag: "nsfw_boost".into(),
+                text: "be more daring".into(),
+            },
+            PromptTrait {
+                tag: "politics_open".into(),
+                text: "discuss politics openly".into(),
+            },
+        ];
+        let p = build_prompt(
+            &fixture_persona(),
+            &[],
+            &[],
+            None,
+            &[],
+            "normal",
+            ReplyStyle::Neutral,
+            &[],
+            &traits,
+        );
+        assert!(p.contains("【附加指引】"), "section header present");
+        assert!(p.contains("- be more daring"));
+        assert!(p.contains("- discuss politics openly"));
+        // Ordering preserved.
+        let i1 = p.find("be more daring").unwrap();
+        let i2 = p.find("discuss politics openly").unwrap();
+        assert!(i1 < i2, "traits render in input order");
+    }
+
+    #[test]
+    fn build_prompt_section_sits_between_topics_and_time_context() {
+        let traits = vec![PromptTrait {
+            tag: "x".into(),
+            text: "trait body".into(),
+        }];
+        let p = build_prompt(
+            &fixture_persona(),
+            &[],
+            &[],
+            None,
+            &[],
+            "normal",
+            ReplyStyle::Neutral,
+            &[],
+            &traits,
+        );
+        let topics_idx = p.find("【擅长话题】").expect("topics header");
+        let traits_idx = p.find("【附加指引】").expect("traits header");
+        let time_idx = p.find("【今日情境】").expect("time-context header");
+        assert!(
+            topics_idx < traits_idx && traits_idx < time_idx,
+            "order: 擅长话题 → 附加指引 → 今日情境"
+        );
+    }
 
     #[test]
     fn test_style_directive_for_all_styles() {