补齐三个成功响应缺失的 meta 信封；信封实现抽为公共（docs/05 §3.3）

"缺 meta"很容易被误判成"有"：X-Trace-ID 是**响应头**（中间件加），和 body 里的
meta.trace_id 是两件事；错误响应一直有 meta（异常处理器统一加），漏的只有成功路径。

核到三个端点在把 service 的内部结构直接当响应体返回：

- GET /conversations/{session_id}/messages → 裸 {"data": [...]}，meta 整个缺失，
  游标也没地方放（§3.3 要求列表的 data 为纯数组、next_cursor/has_more 进 meta）
- POST /conversation-messages/{id}/feedback → 同样没有 meta
- GET /knowledge-references/{token} → 直接返回资源对象

改动：

- 新增 app/api/views/envelope.py，把 envelope / list_envelope 抽成一份公共实现，
  风控链路改为复用它 —— 同一份契约写两遍的结果就是其中一处漏了 meta。
- ConversationService.messages 改为返回内部结构 {items, next_cursor, has_more}，
  用 limit + 1 判断 has_more：只看"取满没取满"会把恰好等于 limit 的最后一页说成
  还有下一页。next_cursor 取本页最后一条的 message_id —— 游标语义是"取更旧的一页"，
  天然可续，集成测试本来就是这么翻页的。
- Controller 统一套信封，data 仍是数组、字段名不变，前端不需要改。

测试：新增 tests/unit/api/test_response_envelope.py，断言 set(body) == {"data","meta"}
（多或少一个顶层字段都会红），并覆盖 has_more / next_cursor / trace_id；
另更新两处既有断言（limit 20→21、feedback 返回裸对象）。

门禁：ruff 干净 / mypy 138 文件 / 696 unit+contract / 33 integration。

tests/unit/api/test_response_envelope.py

@@ -0,0 +1,119 @@
+"""成功响应的统一信封（`docs/05` §3.3）。
+
+§3.3 规定成功响应是 `{data, meta}`，列表的 `data` 为**纯数组**、`next_cursor` 与
+`has_more` 放在 `meta` 里，并且明确「业务接口不得增加其他顶层字段」。
+
+此前有三个端点漏了这件事，它们都是"service 直接把内部结构当响应体返回"：
+
+- `GET /conversations/{session_id}/messages` → 裸 `{"data": [...]}`，`meta` 整个缺失，
+  游标也没有地方放；
+- `POST /conversation-messages/{id}/feedback` → 同样没有 `meta`；
+- `GET /knowledge-references/{token}` → 直接返回资源对象。
+
+注意"缺 meta"很容易被误判成"有"：`X-Trace-ID` 是**响应头**（由中间件加），和 body 里的
+`meta.trace_id` 是两件事；错误响应一直有 `meta`（异常处理器统一加），只有成功路径漏了。
+所以这里断言的是 `set(body)`，多一个或少一个顶层字段都会红。
+"""
+
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api.controllers import conversations as conversations_controller
+from app.api.controllers import knowledge as knowledge_controller
+from app.api.dependencies.auth import build_request_context
+from app.api.dependencies.database import get_session
+from app.core.contracts import RequestContext
+from app.main import create_app
+
+TRACE = "trace-envelope"
+
+
+async def resolve_context() -> RequestContext:
+    return RequestContext(
+        user_id="9001",
+        trace_id=TRACE,
+        permissions=("conversation:create", "conversation:feedback", "knowledge:reference:read"),
+    )
+
+
+class StubConversationService:
+    def __init__(self, _session: Any) -> None:
+        pass
+
+    async def messages(
+        self, _session_id: str, _context: RequestContext, _limit: int, before: int | None = None
+    ) -> dict[str, Any]:
+        del before
+        return {
+            "items": [
+                {
+                    "message_id": "11",
+                    "role": "user",
+                    "content": "稳健型",
+                    "created_at": "2026-09-10T00:00:00Z",
+                }
+            ],
+            "next_cursor": "11",
+            "has_more": True,
+        }
+
+    async def feedback(
+        self,
+        _message_id: int,
+        _context: RequestContext,
+        _rating: int,
+        _feedback_type: str | None,
+        _feedback_content: str | None,
+    ) -> dict[str, Any]:
+        return {"feedback_no": "fb-1", "status": "open"}
+
+
+class StubKnowledgeService:
+    async def resolve(self, _context: RequestContext, _token: str) -> dict[str, Any]:
+        return {"knowledge_id": 7, "title": "个人投资者适当性管理指南"}
+
+
+def envelope_client(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+    monkeypatch.setattr(
+        conversations_controller, "ConversationService", StubConversationService
+    )
+    monkeypatch.setattr(knowledge_controller, "KnowledgeReferenceService", StubKnowledgeService)
+    application = create_app()
+    application.dependency_overrides[build_request_context] = resolve_context
+    application.dependency_overrides[get_session] = lambda: None
+    return TestClient(application)
+
+
+def test_message_list_puts_cursor_in_meta(monkeypatch: pytest.MonkeyPatch) -> None:
+    with envelope_client(monkeypatch) as http:
+        response = http.get("/api/v1/conversations/session-1/messages", params={"limit": 20})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert set(body) == {"data", "meta"}
+    assert isinstance(body["data"], list)
+    assert body["data"][0]["message_id"] == "11"
+    assert body["meta"] == {"trace_id": TRACE, "next_cursor": "11", "has_more": True}
+
+
+def test_feedback_success_response_has_meta(monkeypatch: pytest.MonkeyPatch) -> None:
+    with envelope_client(monkeypatch) as http:
+        response = http.post("/api/v1/conversation-messages/11/feedback", json={"rating": 1})
+
+    assert response.status_code == 201
+    body = response.json()
+    assert set(body) == {"data", "meta"}
+    assert body["data"] == {"feedback_no": "fb-1", "status": "open"}
+    assert body["meta"] == {"trace_id": TRACE}
+
+
+def test_knowledge_reference_success_response_has_meta(monkeypatch: pytest.MonkeyPatch) -> None:
+    with envelope_client(monkeypatch) as http:
+        response = http.get(f"/api/v1/knowledge-references/{'a' * 20}")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert set(body) == {"data", "meta"}
+    assert body["meta"] == {"trace_id": TRACE}

tests/unit/service/test_conversation_service.py

@@ -108,14 +108,20 @@ async def test_messages_are_scoped_to_current_user(monkeypatch: pytest.MonkeyPat
 
     # user_id 必须透传：Repository 靠它做归属过滤，漏传就等于不限范围。
     assert captured["user_id"] == 9001
-    assert captured["limit"] == 20
+    # 21 = limit + 1：service 多取一行判断"还有没有更旧的"，用来填 §3.3 的 has_more。
+    # 只看"取满没取满"会把恰好等于 limit 的最后一页说成还有下一页。
+    assert captured["limit"] == 21
     assert captured["session_id"] == "session-1"
     # 不带游标时必须传 None，行为与加游标前一致（取最新一页）。
     assert captured["before"] is None
-    assert result["data"] == [
+    # service 返回内部结构，Controller 用 list_envelope 拆成 {data, meta}（§3.3）。
+    # 一行数据小于 limit，所以没有下一页。
+    assert result["items"] == [
         {"message_id": "11", "role": "user", "content": "稳健型",
          "created_at": NOW.isoformat() + "Z"}
     ]
+    assert result["has_more"] is False
+    assert result["next_cursor"] is None
 
 
 async def test_messages_forward_cursor_to_repository(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -156,7 +162,7 @@ async def test_feedback_writes_feedback_and_audit_with_trace_id(
 
     result = await ConversationService(session).feedback(11, CONTEXT, 1, "rating", "很有帮助")
 
-    assert result["data"]["status"] == "open"
+    assert result["status"] == "open"
     kinds = [type(item).__name__ for item in session.added]
     assert kinds == ["ConversationFeedback", "InteractionAudit"]
     audit = session.added[1]