Merge pull request #114 from tarosky/fix/ai-overview-literal-newline

Fix: AI Overview の回答でリテラル改行 `\n` がそのまま表示される問題を修正

Author: fumikito

app/Hametuha/Hamelp/Services/FaqSearchService.php

@@ -122,7 +122,7 @@ public function generate_overview( string $query, array $history = [] ) {
 		if ( null === $data ) {
 			// JSON parse failed: treat response as plain text.
 			return [
-				'answer'    => $response,
+				'answer'    => self::normalize_answer_text( $response ),
 				'sources'   => [],
 				'cited_ids' => [],
 			];
@@ -143,7 +143,7 @@ public function generate_overview( string $query, array $history = [] ) {
 		}
 
 		return [
-			'answer'    => $data['answer'],
+			'answer'    => self::normalize_answer_text( (string) $data['answer'] ),
 			'sources'   => $sources,
 			'cited_ids' => wp_list_pluck( $sources, 'id' ),
 		];
@@ -212,6 +212,34 @@ public static function decode_json_response( string $response ): ?array {
 		return $data;
 	}
 
+	/**
+	 * Normalize literal escape sequences in answer text into real characters.
+	 *
+	 * Some models double-escape newlines in their structured JSON output, so a
+	 * single `json_decode()` leaves the two-character sequence `\n` (backslash +
+	 * n) in the answer instead of a real line break. The frontend renderer only
+	 * understands real newline characters, so those literals leak into the
+	 * rendered answer as raw text. This converts the common literal sequences
+	 * back into the real characters they represent.
+	 *
+	 * A `strtr()` map is used so replacement is single-pass and order-independent
+	 * (the longer `\r\n` sequence is matched before the shorter `\r`/`\n`).
+	 *
+	 * @param string $text Answer text possibly containing literal escape sequences.
+	 * @return string Text with literal `\r\n`, `\n`, `\r` and `\t` converted.
+	 */
+	public static function normalize_answer_text( string $text ): string {
+		return strtr(
+			$text,
+			[
+				'\\r\\n' => "\n",
+				'\\n'    => "\n",
+				'\\r'    => "\n",
+				'\\t'    => "\t",
+			]
+		);
+	}
+
 	/**
 	 * Resolve cited FAQ IDs into source link data.
 	 *

tests/test-ai-overview.php

@@ -130,6 +130,98 @@ public function test_empty_history() {
 		$this->assertSame( [], $this->service->prepare_history( [] ) );
 	}
 
+	/**
+	 * Literal newline escape sequences are converted to real characters.
+	 */
+	public function test_normalize_answer_text_literal_newline() {
+		$this->assertSame(
+			"line1\nline2",
+			FaqSearchService::normalize_answer_text( 'line1\nline2' )
+		);
+	}
+
+	/**
+	 * Literal double newlines (paragraph breaks) are converted.
+	 */
+	public function test_normalize_answer_text_literal_double_newline() {
+		$this->assertSame(
+			"para1\n\npara2",
+			FaqSearchService::normalize_answer_text( 'para1\n\npara2' )
+		);
+	}
+
+	/**
+	 * A literal CRLF sequence collapses to a single real newline.
+	 */
+	public function test_normalize_answer_text_literal_crlf() {
+		$this->assertSame(
+			"line1\nline2",
+			FaqSearchService::normalize_answer_text( 'line1\r\nline2' )
+		);
+	}
+
+	/**
+	 * A literal tab sequence is converted to a real tab.
+	 */
+	public function test_normalize_answer_text_literal_tab() {
+		$this->assertSame(
+			"a\tb",
+			FaqSearchService::normalize_answer_text( 'a\tb' )
+		);
+	}
+
+	/**
+	 * Real newline characters are left intact.
+	 */
+	public function test_normalize_answer_text_real_newline_untouched() {
+		$this->assertSame(
+			"line1\nline2",
+			FaqSearchService::normalize_answer_text( "line1\nline2" )
+		);
+	}
+
+	/**
+	 * Plain text without escape sequences is returned unchanged.
+	 */
+	public function test_normalize_answer_text_plain_unchanged() {
+		$this->assertSame(
+			'Just a plain answer.',
+			FaqSearchService::normalize_answer_text( 'Just a plain answer.' )
+		);
+	}
+
+	/**
+	 * A standalone literal carriage return (no following n) becomes one real newline.
+	 */
+	public function test_normalize_answer_text_literal_lone_cr() {
+		$this->assertSame(
+			"line1\nline2",
+			FaqSearchService::normalize_answer_text( 'line1\rline2' )
+		);
+	}
+
+	/**
+	 * A real newline and a literal escape sequence in the same string both
+	 * end up as real newlines, with the pre-existing real newline untouched.
+	 */
+	public function test_normalize_answer_text_mixed_real_and_literal_newline() {
+		$this->assertSame(
+			"line1\nline2\nline3",
+			FaqSearchService::normalize_answer_text( "line1\nline2" . '\n' . 'line3' )
+		);
+	}
+
+	/**
+	 * Normalization is idempotent: running it on already-normalized output
+	 * produces the same result as a single pass.
+	 */
+	public function test_normalize_answer_text_idempotent() {
+		$input = 'a\r\nb\tc' . "\n" . 'd';
+		$once  = FaqSearchService::normalize_answer_text( $input );
+		$twice = FaqSearchService::normalize_answer_text( $once );
+		$this->assertSame( $once, $twice );
+	}
+
 	/**
 	 * The AI Overview mode defaults to conversation and honors option/filter.
 	 */