H-337: add local Captain acceptance fixture (#63)

* H-337: add local Captain acceptance fixture * fix(H-337): close acceptance fixture review gaps * fix(H-337): reject non-string skill metadata --------- Co-authored-by: Rogee <rogee@ipao.vip>
2026-08-20 20:05:40 +08:00
parent 60ad320e8d
commit abb1bed424
12 changed files with 818 additions and 19 deletions
@@ -61,6 +61,48 @@ Example settings value (the key remains a separate `.env` variable):
 {"chat":{"provider":"openai_compatible","base_url":"https://provider.example.com/v1","model":"gpt-5.6-luna"},"embedding":{"mode":"reuse_chat_credentials","provider":"openai_compatible","base_url":"https://provider.example.com/v1","model":"text-embedding-3-small","dimensions":1536},"generation":{"temperature":0.7,"max_tokens":2048},"request":{"timeout_seconds":60,"max_retries":2}}
 ```

+## Local Captain acceptance fixture
+
+The acceptance overlay uses a deterministic, OpenAI-compatible local service;
+the configured key is a non-secret sentinel. The same service exposes the
+container-reachable knowledge URL `http://captain-fixture:8080/knowledge`.
+
+```bash
+docker compose -f compose.yaml -f compose.acceptance.yaml up -d --build
+GANBING_SOURCE=/path/to/read-only-assets ./scripts/preflight_acceptance.sh
+```
+
+Fixture scenarios are selected by the UI message text:
+
+- normal text: successful chat
+- `[fixture:fail]`: persistent HTTP 503
+- `[fixture:retry] unique-id`: one HTTP 503 followed by success on provider retry
+- `[fixture:embedding-fail]` and `[fixture:embedding-retry] unique-id`: matching embedding paths
+- `[fixture:skill]`: activate the first bound Skill and read its first reference
+
+For the disabled path, clear the Copilot provider in SuperAdmin and confirm the
+Playground unavailable response. Restore by saving the same fixture URL/model
+and sentinel key shown in `compose.acceptance.yaml`; a normal message must then
+succeed. Use a new suffix for each retry scenario, since retries are counted by
+the exact request body. The preflight rejects persisted database settings that
+would silently override the fixture.
+
+To prepare the authorized SKILL/SOUL assets without touching their source:
+
+```bash
+GANBING_SOURCE=/path/to/read-only-assets \
+  ./scripts/stage_captain_assets.sh /private/path/gochat-captain-stage
+```
+
+In Captain UI, create `ganbing-local-acceptance`, paste
+`captain-skill/instructions.md`, add only files under
+`captain-skill/references/` using their filename stem as `reference_key`, then
+publish and add it to the test assistant. Paste `assistant-instructions.md`
+into the assistant's Additional instructions field. Files under `quarantine/`
+exceed the current 8 KB per-request Skill runtime budget when combined with the
+Skill instructions; do not import them without a content-owner-approved split.
+The staging script never truncates or rewrites source content.
+
 ## Useful Commands

 ```bash