本文へ移動
cccskills
無料GitHub で公開

sanguo-event-review-loop

Sanguo event review loop with LangGraph Studio visualization. Use for: 三國事件審核、generic event candidates、battle candidates、event review MCQ、accepted/rejected events、promote events、LangGraph Studio、human-in-the-loop、事件候選可視化、chunk -> extract -> validate -> review -> publish。

eaglhuang/3klife
インストール方法を見る

含まれるファイル（1）

  • SKILL.md9.9 KB

SKILL.md（原文）

インストールする前に、エージェントに与えられる指示の中身を確認できます。

Sanguo Event Review Loop

這個 skill 用來把「事件候選」固定納入可重複的人類審核循環，避免 generic-battle-candidates.jsonl 或未來的通用事件候選檔被產出後遺忘。

Unity 對照：這像資料版 AssetPostprocessor + Inspector。Extractor 先 import raw text 產生 candidate assets；validator 像 import validation；人類 review 像在 Inspector 裡確認、修欄位或拒絕；publish 才會把 accepted event 寫進正式 runtime asset。

When to Use

  • 使用者提到 event review、事件審核、事件候選、generic event candidates、battle candidates、accepted events、rejected events、promote event。
  • 使用者想把 generic-battle-candidates.jsonl 或未來 generic-event-candidates.jsonl 轉成選擇題給人類審。
  • 使用者想用 LangGraph Studio 看 chunk -> extract -> validate -> review -> publish 的狀態流轉。
  • 使用者想確認「哪個 chunk 被提案、為什麼進 review、哪個 validator 擋下來、人類改了什麼、恢復後是否正確 publish」。

Core Files

目前已存在：

  • Event extractor: server/npc-brain/pipelines/sanguo-rag/extract_event_candidates.py
  • Gold seed registry: server/npc-brain/pipelines/sanguo-rag/gold_seed_registry.py
  • Ready events: artifacts/data-pipeline/sanguo-rag/extracted/events/events.jsonl
  • Event review report: artifacts/data-pipeline/sanguo-rag/extracted/events/events-review.md
  • Generic battle candidates: artifacts/data-pipeline/sanguo-rag/extracted/events/generic-battle-candidates.jsonl
  • Generic battle review report: artifacts/data-pipeline/sanguo-rag/extracted/events/generic-battle-candidates-review.md
  • Event summary: artifacts/data-pipeline/sanguo-rag/extracted/events/events-summary.json

建議新增：

  • Review choices: artifacts/data-pipeline/sanguo-rag/extracted/events/event-review-choices.md
  • Answers template: artifacts/data-pipeline/sanguo-rag/extracted/events/event-review-answers.todo.json
  • Applied decisions: server/npc-brain/pipelines/sanguo-rag/config/event-review-decisions.json
  • Accepted queue: artifacts/data-pipeline/sanguo-rag/extracted/events/accepted-events.jsonl
  • Rejected queue: artifacts/data-pipeline/sanguo-rag/extracted/events/rejected-events.jsonl
  • Pending queue: artifacts/data-pipeline/sanguo-rag/extracted/events/pending-events.jsonl

建議新增腳本：

  • server/npc-brain/pipelines/sanguo-rag/generate_event_review_choices.py
  • server/npc-brain/pipelines/sanguo-rag/apply_event_review_answers.py
  • server/npc-brain/pipelines/sanguo-rag/run_event_review_loop.py
  • Optional LangGraph local graph: server/npc-brain/pipelines/sanguo-rag/langgraph_event_review.py

Decision Semantics

事件審核選項固定如下：

  • A accept: 接受候選為正式事件。必須能通過 schema gate，且 sourceRefs、generalIds、summary 可信。
  • B accept-with-edits: 接受但需要修改欄位。answers 必須提供 edits，例如 eventKey、summary、location、relationshipEdges、moodTags。
  • C merge: 與既有事件合併。answers 必須提供 mergeIntoEventId 或 mergeIntoEventKey。
  • D reject: 拒絕為噪音或錯誤事件。answers 必須提供 reason。
  • E defer: 暫緩，需要更多 research 或等待 LLM proposer。保留在 pending queue。

不得把 needs-review 候選直接寫進正式 events.jsonl。只有 A/B/C 經 schema gate 通過後才可 publish。

Standard Procedure

1. Pre-flight

  1. 讀 docs/keep.summary.md。
  2. 若會修改 .md / .json / .py，讀 encoding-touched-guard 並在收工前跑 encoding check。
  3. 先確認正式 ready events 與 review-only candidates 的數量：
$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/extract_event_candidates.py --overwrite

2. Generate MCQ Review Pack

若 genericBattleCandidateCount > 0 或未來 genericEventCandidateCount > 0，必須產出人類可審的選擇題檔：

$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/generate_event_review_choices.py --top 20

快速 preview 優先用本地 agent-reviewer，不要用 qwen 判斷；每步 30 秒 timeout：

$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/run_knowledge_growth_round.py \
  --round-id wenyan-preview-r1 \
  --candidates artifacts/data-pipeline/sanguo-rag/extracted/events/generic-battle-candidates.jsonl \
  --max-generals 5 \
  --top-per-general 2 \
  --reviewer-preset agent \
  --reviewer-provider agent-reviewer \
  --step-timeout-seconds 30 \
  --overwrite

女性高互動候選應指定女性本人，避免 cohort 被男性參與者稀釋：

$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/run_knowledge_growth_round.py \
  --round-id wenyan-preview-female-focus \
  --candidates artifacts/data-pipeline/sanguo-rag/extracted/events/female-interaction-candidates.jsonl \
  --general-id sun-shang-xiang \
  --general-id wu-guo-tai \
  --general-id zhu-rong-furen \
  --general-id cai-shi \
  --general-id diao-chan \
  --top-per-general 3 \
  --reviewer-preset agent \
  --reviewer-provider agent-reviewer \
  --step-timeout-seconds 30 \
  --overwrite

Generic battle preview 的 B 不一定是失敗：如果 focus general 只是盟主、統籌者、旁觀者或 scene participant，但 strong relationship edge 發生在其他人之間，應保守留 B，不要為了提高 A 率放寬 focus edge gate。

輸出必須包含：

  • candidate id / event key
  • source refs
  • source quote
  • proposed event type
  • proposed participants
  • proposed summary
  • validator warnings
  • A/B/C/D/E 選項
  • answers todo JSON 對應 key

3. Human Review

優先使用文件式 MCQ，避免口頭審核散落在對話中：

artifacts/data-pipeline/sanguo-rag/extracted/events/event-review-choices.md
artifacts/data-pipeline/sanguo-rag/extracted/events/event-review-answers.todo.json

若使用者要求即時互動，可以用 vscode_askQuestions 一題一題問，但最後仍要回寫 answers / decisions 檔。

4. Apply Answers

套用人工答案：

$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/apply_event_review_answers.py

套用後必須更新：

  • event-review-decisions.json
  • accepted-events.jsonl
  • rejected-events.jsonl
  • pending-events.jsonl

5. Publish Accepted Events

只有 accepted events 通過 schema gate 後，才可併入正式 events.jsonl 或下一版 canonical events source。publish 後必須重跑：

$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/build_keyword_options.py --general-id zhang-fei --overwrite
$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/build_persona_cards.py --overwrite
$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/build_api_readiness_index.py --general-id zhang-fei --overwrite
$HOME/.venv/3klife-etl/bin/python server/npc-brain/pipelines/sanguo-rag/validate_llm_extraction_trial.py --overwrite

6. Verify

至少跑：

$HOME/.venv/3klife-etl/bin/python -m py_compile \
  server/npc-brain/pipelines/sanguo-rag/extract_event_candidates.py \
  server/npc-brain/pipelines/sanguo-rag/generate_event_review_choices.py \
  server/npc-brain/pipelines/sanguo-rag/apply_event_review_answers.py \
  server/npc-brain/pipelines/sanguo-rag/run_event_review_loop.py

如果 service fixture 有變，再跑：

cd server/npc-brain
PYTHONPATH=. $HOME/.venv/3klife-etl/bin/python -m app.smoke_test
PYTHONPATH=. $HOME/.venv/3klife-etl/bin/python -m app.http_smoke_test
PYTHONPATH=. $HOME/.venv/3klife-etl/bin/python -m app.cocos_flow_smoke_test

LangGraph Studio Role

LangGraph Studio 適合作為「事件審核流程的可視化開發工具」，不是 deterministic ETL 的替代品。

推薦 graph 節點：

load_chunks
  -> propose_event_candidates
  -> validate_candidate_schema
  -> route_by_confidence
  -> human_review_interrupt
  -> apply_human_edits
  -> publish_accepted_events
  -> rebuild_downstream_artifacts
  -> verify_runtime_smoke

State 建議包含：

{
  "runId": "event-review-2026-04-29-r1",
  "candidateId": "romance.generic-battle.001-p15",
  "sourceRefs": ["001#p15"],
  "sourceQuote": "...",
  "proposedEvent": {},
  "validatorWarnings": [],
  "humanDecision": null,
  "humanEdits": {},
  "publishResult": null,
  "downstreamChecks": []
}

Studio 要看的不是漂亮圖，而是每個節點的狀態差異：

  • 哪個 chunk 被提案。
  • 為什麼進 review。
  • 哪個 validator 擋下來。
  • 人類改了什麼欄位。
  • resume 後是否正確 publish。
  • publish 後 keyword / persona / API 是否重建成功。

LangGraph Adoption Policy

分階段採用：

  1. 先保留 Python + Pydantic + JSONL / Markdown MCQ 作為 canonical pipeline。
  2. 再用 LangGraph local graph 包裝同一條流程，方便 Studio debug。
  3. Studio 只用於開發期可視化、human-in-the-loop、狀態回放。
  4. LangGraph Cloud / LangSmith Deployment 等 schema 與本地流程穩定後再評估，不作為 MVP 前置依賴。

Stop Condition

停止一輪事件審核時，必須回報：

  • ready event count
  • generic candidate count
  • generated review question count
  • accepted / rejected / pending / deferred count
  • 是否重建 keyword / persona / API
  • 是否通過 LLM trial 與 smoke tests

如果只完成設計或 skill 更新，也要明確說明尚未產生 MCQ 腳本或尚未套用人類答案。

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

ログインしてレビューを書く

同じリポジトリのスキル

概要と使いどころ

3kweb-check

無料

Deterministic external-evidence web validation workflow for Sanguo ETL/RAG. USE FOR: 外部證據網站檢查、來源健康度、allowlist 驗證、來源 seed 覆蓋、3kweb-check、external evidence source health、fetch/parse/hash first、LLM reviewer second。

日本語の概要は準備中です。原文の説明を表示しています。

eaglhuang/3klife32026年10月13日 更新

ai-role-router

無料

Use when the user asks to switch AI role/mode/persona or uses role-trigger words such as Captain, Coordinator, 寫文章, 寫文章模式, 文章模式, 技術文章, 部落格, 出版, 預覽. Routes the request to Project Captain, Publishing Director, or Article Writing Mode, loads the matching keep memory when available, and applies the role's workflow without excessive roleplay.

日本語の概要は準備中です。原文の説明を表示しています。

eaglhuang/3klife32026年10月13日 更新

article-writing-mode

無料

Write or revise AI-learning-notes article pages in "寫文章模式" when the user asks for articles, technical articles, blog posts, bilingual versions, article formatting consistency, shared article-base alignment, responsive layout, summary/TOC decisions, contrast, or publishing-flow compatibility.

日本語の概要は準備中です。原文の説明を表示しています。

eaglhuang/3klife32026年10月13日 更新

atm-atom-map-refactor

無料

Plan ATM framework refactors by preserving atom/map semantics before splitting large governance modules.

日本語の概要は準備中です。原文の説明を表示しています。

eaglhuang/3klife32026年10月13日 更新

atm-captain-dispatch-standard

無料

Captain 派工規範與決策手冊。當 AI 進入隊長模式或進行派工/派任務語境時，遵照這套標準，產出可供人類直接轉貼、高度結構化、符合 token 經濟且能動態適應可用 Roster 的派工單。

日本語の概要は準備中です。原文の説明を表示しています。

eaglhuang/3klife32026年10月13日 更新

atm-create

無料

Create and register an atom through the provisioning facade.

日本語の概要は準備中です。原文の説明を表示しています。

eaglhuang/3klife32026年10月13日 更新

eaglhuang のスキルをすべて見る

このスキルの問題を報告する