Sandcastle — 企业组织架构 Agent 沙盘演练系统

不是剧本杀模拟器，是组织决策的压力测试仪。

让 AI Agent 代替真实的人，提前在沙盘里把利益冲突暴露出来。PM 在 kickoff 会议之前就知道哪里会吵起来。

---

核心设计

Agent 模拟的是"约束条件"，不是"语气寒暄"
Master Agent 是"冲突提取器"，不是"和事佬"
输出是 GitHub Code Review 风格的结构化报告

Round 1: State_0
  → Constraint Engine → Violations[]（纯Python，确定性）
  → Sub Agents（LLM）→ Proposals[]（带偏见的变更提案）
  → StateMutator → State_1（新状态）
  ↓
收敛：连续3轮没有任何新提案 → REPORT

---

安装

pip install -e .
# 或
pip install -e ".[dev]"

---

快速开始

1. 运行排雷沙盘

sandcastle run --scenario scenarios/pm-kickoff

2. 输出报告

sandcastle run --scenario scenarios/pm-kickoff --output report.md

3. Docker 离线运行

docker-compose up
docker-compose exec sandcastle sandcastle run --scenario scenarios/pm-kickoff

---

场景格式

scenarios/
  pm-kickoff/
    scenario.yaml          # 场景描述
    agents.yaml            # 子 Agent 配置（角色、bias、关注约束）
    constraints.yaml       # 约束规则定义
    data/
      snapshot.yaml        # 初始状态快照

编写你的第一个约束

# constraints.yaml
constraints:
  - id: margin_floor
    description: 毛利率不得低于20%红线
    severity: critical
    context_schema:
      gross_margin: null
    expr: "ctx['gross_margin'] >= 0.20"

编写 Agent bias

# agents.yaml
finance:
  role: 财务总监
  bias:
    - 毛利红线
    - 成本压缩
    - 风险规避
  constraints_i_care_about:
    - margin_floor
    - budget_ceiling

---

环境变量

变量	默认值	说明
LLM_MODE	openai	local=强制 Ollama，openai=允许云端
OLLAMA_BASE_URL	http://localhost:11434	Ollama 地址
OLLAMA_MODEL	llama3.2	Ollama 模型
OPENAI_API_KEY	—	OpenAI API Key
ANTHROPIC_API_KEY	—	Anthropic API Key

---

架构

sandbox_engine/     — 纯Python确定性核心（无LLM依赖）
  evaluate.py       ConstraintEvaluator + Constraint + Violation
  state.py          State + StateMutator + Proposal
  convergence.py     ConvergenceChecker（连续3轮无新Proposal→收敛）
  reporting.py      ReportGenerator + ConflictReport

sandbox_llm/       — LLM路由层
  router.py         LLMRouter + LLM_MODE=local 数据主权守卫

sandbox_agents/   — 子Agent（State Mutator角色）
  base.py           BaseAgent（LLMRefusalError→优雅降级）
  roles.py          DesignerAgent / SupplyChainAgent / FinanceAgent

sandbox_cli/       — CLI入口
  simulation.py     推演主循环
  loader.py         YAML场景加载器

---

License

MIT