MINARA新增分析 Playbook
使用聚焦的分析框架擴展機構模式、Roundtable 模板或深度研究
Minara 已於 2026 年 5 月退役獨立的 Scenario Registry。不要再創建 SCENARIO_* 定義文件、修改場景目錄或增加 SCENARIO_LEARNING 開關。用戶意圖路由現在由技能負責，保留下來的分析 Playbook 直接服務於機構模式和深度研究。
選擇正確的擴展面
| 目標 | 擴展位置 |
|---|---|
| 將一類用戶請求路由到現有工具 | 內置技能 |
| 為機構角色提供可複用的分析框架 | apps/agent/src/tools/institution/playbooks/index.ts |
| 新增內置 Agent、階段或 Roundtable 模板 | apps/agent/src/tools/institution/builder-templates.ts |
| 擴展深度研究中的資料收集與綜合方法 | apps/agent/src/skills/builtin/deep-research/references/scenarios.md |
| 讓單個用戶編排自定義多 Agent 流程 | 使用 Roundtable Builder，無需修改源碼 |
新增機構 Playbook
機構 Playbook 為一個或多個角色提供分析內容。請使用穩定、帶命名空間的 ID，例如 institution.playbook.stock_quality，並將其加入 INSTITUTION_PLAYBOOKS。
"institution.playbook.stock_quality": {
id: "institution.playbook.stock_quality",
description: "Evaluate earnings quality, reinvestment, and balance-sheet resilience.",
body: `1. Verify the latest filing period and data freshness.
2. Compare cash conversion, margins, and invested-capital returns.
3. Identify the strongest disconfirming evidence.
4. State the conditions that would invalidate the conclusion.`,
},每個正文都要能夠獨立理解。請明確所需證據、衝突證據如何改變結論，以及實時數據缺失時如何降級。不要重複系統提示中已經存在的通用安全、引用和語言規則。
只有內置角色需要默認加載該 Playbook 時，才在 apps/agent/src/tools/institution/roles.ts 中添加映射。資產類別特有的映射放在 playbookIdsForRole() 中。測試會檢查所有被引用的 ID 是否真實存在。
可調整的數值使用帶安全默認值的方法論佔位符：
Treat beta above `{{methodology:stock_beta_high_corr_threshold|default:0.8}}`
as market-sensitive.不要把可複用的投資規則埋在冗長 Playbook 中。請將它移入方法論系統，再通過佔位符或 methodology_lookup 引用。
新增內置 Roundtable 模板
Roundtable Builder 支持五種階段：context、parallel、debate、synthesis 和 final。內置 Agent、階段和完整 Roundtable 模板位於 builder-templates.ts，共享類型來自 @minara/types。
驗證器強制執行以下規則：
- 整條流程中的階段 ID 與 Agent ID 不得重複；
- 辯論階段至少包含兩個 Agent；
- 綜合和最終階段必須恰好有一位管理者；
- 整條流程必須恰好有一個最終階段，且該階段位於最後；
- 循環次數、工具調用、超時和輸出 Token 不得超過聲明範圍。
修改模板時，需要同步更新 Agent 測試與 Web UI Builder 測試。用戶創建的模板通過 Builder Store 持久化，不應提交到源碼。
擴展深度研究
深度研究的六步外層契約位於 deep-research/SKILL.md。主題特有的資料收集和分析方法寫入 references/scenarios.md。內容應聚焦來源選擇、證據質量、比較邏輯和最終綜合的結構。
如果 Playbook 需要新能力，請先新增並測試工具，將它加入技能的 tool_names，再更新參考文件。來源或憑據不可用時，Playbook 必須如實降級。
驗證貢獻
pnpm --filter @minara/agent exec vitest run tests/unit/tools/institution.test.ts
pnpm --filter @minara/agent exec vitest run tests/unit/tools/institution-builder.test.ts
pnpm --filter @minara/agent typecheck修改深度研究時，還應運行對應的技能和報告流程測試。若改動影響公共行為，請同步更新四種語言的機構模式或深度研究文檔。