# 社会体系建模多Agent系统 (Social System Modeling Multi-Agent Framework)
## 简介
一个轻量级的多Agent协作框架,用于从基础假设推演出完整的社会体系模型。通过7个专业Agent(Systems/Econ/Socio/Governance/Culture/Risk/Validation)的协同分析,生成结构化、可验证的社会体系模型。
**核心特性**:
- 🔬 **7个专业Agent**: 覆盖系统思维、经济学、社会学、治理学、文化学、风险分析和验证
- 🔄 **6步工作流**: 假设验证→并行推演→冲突对齐→决策合成→证据校验→迭代收敛
- ⚡ **轻量级实现**: TypeScript + Bun,可被Claude/AI直接调用
- 🛠️ **MCP协议支持**: 标准Model Context Protocol,可与Claude Desktop无缝集成
- 📊 **结构化输出**: 9层架构模型(总体结构/工作流/制度/治理/文化/创新/风险/指标/优化)
## 快速开始
### 安装
```bash
# 克隆项目
git clone <repository-url>
cd SocialGuessSkills
# 安装依赖
bun install
# 安装Biome
bun add -d biome
```
### 配置Biome
1. 初始化Biome配置:
```bash
biome init
```
2. 编辑生成的`biome.json`文件以适配项目需求:
```json
{
"$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
"formatter": {
"enabled": true,
"indentStyle": "space",
"lineWidth": 100
},
"linter": {
"enabled": true,
"rules": {
"recommended": true,
"correctness": {},
"style": {}
}
},
"javascript": {
"formatter": {
"quoteStyle": "single"
}
}
}
```
3. 运行Biome检查:
```bash
biome check
```
### 运行示例
```bash
# 运行端到端示例(社区治理模型)
bun run examples/run-example.ts
```
**预期输出**:
- 迭代次数: 2
- 置信度: 0.79
- Agent输出数量: 7(每个Agent都会生成分析)
- 冲突数量: 7(逻辑矛盾、优先级冲突、风险叠加)
### 运行配置（环境变量）
默认使用模拟输出，可通过环境变量切换真实 LLM 与失败策略：
- `LLM_PROVIDER`: `auto` | `anthropic` | `mock`（默认 `auto`）
- `ANTHROPIC_API_KEY`: 使用 Anthropic 时必填
- `LLM_MODEL`: 模型名称（默认 `claude-3-5-sonnet-20241022`）
- `LLM_MAX_TOKENS`: 最大输出 token（默认 `4096`）
- `LLM_TIMEOUT_MS`: LLM 超时毫秒数（默认 `60000`）
- `AGENT_MOCK_MODE`: 强制 mock（`true`/`false`，默认 `false`）
- `FAIL_ON_CRITICAL`: 关键 Agent 失败时中断流程（默认 `true`）
- `CRITICAL_AGENTS`: 关键 Agent 列表（默认 `risk,governance,systems`）
### MCP集成(推荐)
**在Claude Desktop中配置**:
1. 编辑 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"social-modeling": {
"command": "bun",
"args": ["run", "/absolute/path/to/src/server.ts"]
}
}
}
```
2. 重启Claude Desktop
3. 在Claude中使用:
```
请帮我分析:1000人社区,资源有限,如何建立稳定合作的社会体系?
```
Claude会自动调用MCP Server,生成完整的社会体系模型。
**📖 详细集成指南**: 查看 [docs/MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md) 了解：
- Claude Desktop完整配置步骤
- OpenCode CLI集成状态
- 故障排除指南
- 更多使用示例和Prompt模板
## 使用示例
### 1. 完整推演(reasoning tool)
**输入**:
```json
{
"hypothesis": {
"assumptions": [
"1000人社区,资源有限(粮食、住房、工具)",
"协作可提升总产出30%",
"无外部干预,孤立环境"
],
"constraints": [
"通信成本:当面交流免费,间接传播有衰减",
"信息不完全:个体只知道邻近50人的状态"
],
"goals": [
"保证所有人基本生存(食物、住所)",
"建立可持续的资源生产与分配机制",
"冲突解决机制可执行"
]
},
"maxIterations": 3
}
```
**输出**: 完整的社会体系模型,包含:
- 7个Agent的分析(结论/依据/风险/建议/可证伪点)
- 检测到的冲突(类型/描述/严重性/解决方案)
- 9层结构化模型(总体结构/工作流/制度/治理/文化/创新/风险/指标/优化)
- 元数据(迭代次数/置信度/生成时间)
### 2. 单Agent查询(query_agent tool)
**输入**:
```json
{
"agentType": "risk",
"hypothesis": {
"assumptions": ["资源稀缺", "有限理性"],
"constraints": [],
"goals": ["稳定秩序"]
}
}
```
**输出**: Risk Agent的专业分析,聚焦于脆弱性、极端情境和韧性策略。
### 3. 模型验证(validate_model tool)
**输入**:
```json
{
"modelJson": "{...完整的模型JSON字符串...}"
}
```
**输出**: 验证结果,包含:
- isValid: 是否通过验证
- checks: 详细检查项(hasAllAgents, hasStructure, hasHypothesis等)
- issues: 发现的问题列表
- warnings: 警告信息(如冲突过多、置信度较低)
## 架构概览
```
┌─────────────────────────────────────────────────────┐
│ 用户输入假设 │
│ (assumptions/constraints/goals) │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 1. 假设验证 (Systems Agent) │
│ - 检查结构完整性,识别关键变量 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 2. 并行Agent推演 (7个Agent) │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌───────┐ │
│ │Systems │ │ Econ │ │ Socio │ │Govern │ │
│ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │
│ └────────┘ └────────┘ └────────┘ └───────┘ │
│ ┌────────┐ ┌────────┐ │
│ │Culture │ │ Risk │ │
│ │ Agent │ │ Agent │ │
│ └────────┘ └────────┘ │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 3. 冲突对齐 (Risk Agent主导) │
│ - 检测逻辑矛盾、优先级冲突、风险叠加 │
│ - 标记需要重推的Agent │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 4. 决策合成 (Governance Agent主导) │
│ - 应用决策合成规则:分层加权、冲突优先级 │
│ - 提取9层结构化模型 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 5. 证据校验 (Validation Agent) │
│ - 可证伪假设检验、历史案例对比、反事实推理 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 6. 迭代收敛 (如有冲突,回到步骤2) │
│ - 最大迭代次数: 3次(可配置) │
│ - 终止条件: 无新冲突 或 达到最大迭代 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 最终社会体系模型 │
│ - Agent输出(7个) │
│ - 冲突列表 │
│ - 9层结构化模型 │
│ - 元数据(迭代/置信度/时间) │
└─────────────────────────────────────────────────────┘
```
## API参考
### Tool 1: reasoning
完整推演流程,从假设到完整模型。
**输入**:
```json
{
"hypothesis": {
"assumptions": ["假设1", "假设2"],
"constraints": ["约束1", "约束2"],
"goals": ["目标1", "目标2"]
},
"maxIterations": 3
}
```
**输出**:
```json
{
"hypothesis": {...},
"agentOutputs": [...],
"conflicts": [...],
"structure": {
"overall": {...},
"workflow": {...},
"institutions": {...},
"governance": {...},
"culture": {...},
"innovation": {...},
"risks": {...},
"metrics": {...},
"optimization": {...}
},
"metadata": {
"iterations": 2,
"confidence": 0.79,
"generatedAt": "2026-02-03T14:30:00Z"
}
}
```
### Tool 2: query_agent
单独查询某个Agent的分析。
**输入**:
```json
{
"agentType": "systems|econ|socio|governance|culture|risk|validation",
"hypothesis": {...}
}
```
**输出**: 单个Agent的完整分析(结论/依据/风险/建议/可证伪点)
### Tool 3: validate_model
验证已有模型的一致性。
**输入**:
```json
{
"modelJson": "{...模型JSON字符串...}"
}
```
**输出**:
```json
{
"isValid": true,
"checks": {
"hasAllAgents": true,
"hasStructure": true,
"hasHypothesis": true,
"hasMetadata": true,
"agentTypesAreValid": true
},
"issues": [],
"warnings": []
}
```
## 扩展指南
### 自定义Agent Prompt
1. 编辑 `src/agents/prompts/{agent}-agent.md`
2. 遵循统一格式:
- `## 角色定义`
- `## 核心职责`
- `## 分析框架`
- `## 输出格式` (CRITICAL)
- `## 关键约束`
3. 修改后无需重启,AI会自动加载最新Prompt
### 添加新的Agent类型
1. 在 `src/types.ts` 中添加新的AgentType
2. 创建 `src/agents/prompts/{new-agent}-agent.md`
3. 在 `src/agents/agent-factory.ts` 的`createAllAgents()`中注册
4. 添加对应的测试用例
### 自定义冲突检测规则
在 `src/workflow/conflict-resolver.ts` 中添加新的检测函数:
```typescript
function detectCustomConflict(outputs: AgentOutput[]): Conflict[] {
const conflicts: Conflict[] = [];
// 你的检测逻辑
return conflicts;
}
```
然后在`detectConflicts()`中调用新函数。
## 项目结构
```
SocialGuessSkills/
├── src/
│ ├── agents/
│ │ ├── prompts/ # 7个Agent的Prompt模板
│ │ ├── agent-factory.ts # Agent工厂
│ │ └── agent-executor.ts # Agent执行器
│ ├── workflow/
│ │ ├── orchestrator.ts # 工作流编排器
│ │ └── conflict-resolver.ts # 冲突检测
│ ├── types.ts # 核心类型定义
│ ├── server.ts # MCP Server入口
│ └── __tests__/ # 测试用例
├── examples/
│ ├── community-governance.json # 示例输入
│ └── run-example.ts # 示例执行脚本
├── package.json
├── tsconfig.json
└── README.md
```
## 测试
运行所有测试:
```bash
bun test
```
测试覆盖:
- Agent Prompt文件完整性
- Agent工厂与执行
- 冲突检测(3种规则)
- 工作流编排器(6步流程)
- 端到端示例
- 执行时间基准(<60秒)
## 贡献
欢迎贡献!请遵循:
1. Fork项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request
**提交规范**:
- `feat:` 新功能
- `fix:` Bug修复
- `docs:` 文档更新
- `refactor:` 代码重构
- `test:` 测试相关
## 许可证
MIT
## 联系方式
- 问题反馈: GitHub Issues
- 讨论交流: GitHub Discussions
