From 8cd71f99468d9893960156452fb839b7ce99a0b5 Mon Sep 17 00:00:00 2001
From: Max <shadow.iqka@qq.com>
Date: Fri, 12 Dec 2025 10:41:46 +0800
Subject: [PATCH] Enhance DESIGN.md to clarify citation formatting and output
 structure

- Added detailed guidelines for citation output format, including HTML link attributes for reference integration.
- Introduced examples demonstrating the correct usage of citation links in LLM outputs, improving clarity for developers.
- Updated documentation to ensure consistency in citation practices across the search module, aiding in the integration of references.
---
 agent/search/DESIGN.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/agent/search/DESIGN.md b/agent/search/DESIGN.md
index 0019a1b9..3b7c01bd 100644
--- a/agent/search/DESIGN.md
+++ b/agent/search/DESIGN.md
@@ -1235,14 +1235,50 @@ URL: https://news.example.com/apple-iphone-15
 
 ```
 You have access to reference data in <references> tags. Each <ref> has:
-- id: Citation identifier (use #ref:{id} to cite)
+- id: Citation identifier
 - type: Data type (web/kb/db)
 - weight: Relevance weight (1.0=highest priority, 0.6=lowest)
 - source: Origin (user=user-provided, hook=assistant-searched, auto=auto-searched)
 
-Prioritize higher-weight references when answering. Cite using: #ref:{id}
+Prioritize higher-weight references when answering.
+
+When citing a reference, use this exact HTML format:
+<a class="ref" data-ref-id="{id}" data-ref-type="{type}" href="#ref:{id}">[{id}]</a>
+
+Example: According to the product data<a class="ref" data-ref-id="ref_001" data-ref-type="db" href="#ref:ref_001">[ref_001]</a>, the price is $999.
 ```
 
+**Citation Output Format:**
+
+LLM outputs citations as HTML links that can be parsed and rendered by frontend:
+
+```html
+<!-- LLM output example -->
+The iPhone 15 Pro<a
+  class="ref"
+  data-ref-id="ref_001"
+  data-ref-type="db"
+  href="#ref:ref_001"
+  >[ref_001]</a
+>
+features the A17 Pro chip<a
+  class="ref"
+  data-ref-id="ref_002"
+  data-ref-type="kb"
+  href="#ref:ref_002"
+  >[ref_002]</a
+>.
+```
+
+**Citation Link Attributes:**
+
+| Attribute       | Description             | Example                 |
+| --------------- | ----------------------- | ----------------------- |
+| `class`         | Fixed class for styling | `"ref"`                 |
+| `data-ref-id`   | Reference ID            | `"ref_001"`             |
+| `data-ref-type` | Data type               | `"db"`, `"kb"`, `"web"` |
+| `href`          | Anchor link             | `"#ref:ref_001"`        |
+
 **Conversion Examples:**
 
 | Module  | Input                              | Output Reference                               |