SocialGuessSkills

БесплатноHosted

A multi-agent framework that models complex social systems through a coordinated workflow of seven specialized agents covering areas like economics, governance,

автор: starlink-awaken

GitHub

Описание

A multi-agent framework that models complex social systems through a coordinated workflow of seven specialized agents covering areas like economics, governance, and risk. It enables users to generate structured, verifiable social system models from basic assumptions using the Model Context Protocol.

README

简介

一个轻量级的多Agent协作框架,用于从基础假设推演出完整的社会体系模型。通过7个专业Agent(Systems/Econ/Socio/Governance/Culture/Risk/Validation)的协同分析,生成结构化、可验证的社会体系模型。

核心特性:

🔬 7个专业Agent: 覆盖系统思维、经济学、社会学、治理学、文化学、风险分析和验证
🔄 6步工作流: 假设验证→并行推演→冲突对齐→决策合成→证据校验→迭代收敛
⚡ 轻量级实现: TypeScript + Bun,可被Claude/AI直接调用
🛠️ MCP协议支持: 标准Model Context Protocol,可与Claude Desktop无缝集成
📊 结构化输出: 9层架构模型(总体结构/工作流/制度/治理/文化/创新/风险/指标/优化)

快速开始

安装

# 克隆项目
git clone <repository-url>
cd SocialGuessSkills

# 安装依赖
bun install

# 安装Biome
bun add -d biome

配置Biome

初始化Biome配置:

biome init

编辑生成的biome.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"
    }
  }
}

运行Biome检查:

biome check

运行示例

# 运行端到端示例(社区治理模型)
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中配置:

编辑 claude_desktop_config.json:

{
  "mcpServers": {
    "social-modeling": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/src/server.ts"]
    }
  }
}

重启Claude Desktop
在Claude中使用:

请帮我分析:1000人社区,资源有限,如何建立稳定合作的社会体系?

Claude会自动调用MCP Server,生成完整的社会体系模型。

📖 详细集成指南: 查看 docs/MCP_INTEGRATION.md 了解：

Claude Desktop完整配置步骤
OpenCode CLI集成状态
故障排除指南
更多使用示例和Prompt模板

使用示例

1. 完整推演(reasoning tool)

输入:

{
  "hypothesis": {
    "assumptions": [
      "1000人社区,资源有限(粮食、住房、工具)",
      "协作可提升总产出30%",
      "无外部干预,孤立环境"
    ],
    "constraints": [
      "通信成本:当面交流免费,间接传播有衰减",
      "信息不完全:个体只知道邻近50人的状态"
    ],
    "goals": [
      "保证所有人基本生存(食物、住所)",
      "建立可持续的资源生产与分配机制",
      "冲突解决机制可执行"
    ]
  },
  "maxIterations": 3
}

输出: 完整的社会体系模型,包含:

7个Agent的分析(结论/依据/风险/建议/可证伪点)
检测到的冲突(类型/描述/严重性/解决方案)
9层结构化模型(总体结构/工作流/制度/治理/文化/创新/风险/指标/优化)
元数据(迭代次数/置信度/生成时间)

2. 单Agent查询(query_agent tool)

输入:

{
  "agentType": "risk",
  "hypothesis": {
    "assumptions": ["资源稀缺", "有限理性"],
    "constraints": [],
    "goals": ["稳定秩序"]
  }
}

输出: Risk Agent的专业分析,聚焦于脆弱性、极端情境和韧性策略。

3. 模型验证(validate_model tool)

输入:

{
  "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

完整推演流程,从假设到完整模型。

输入:

{
  "hypothesis": {
    "assumptions": ["假设1", "假设2"],
    "constraints": ["约束1", "约束2"],
    "goals": ["目标1", "目标2"]
  },
  "maxIterations": 3
}

输出:

{
  "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的分析。

输入:

{
  "agentType": "systems|econ|socio|governance|culture|risk|validation",
  "hypothesis": {...}
}

输出: 单个Agent的完整分析(结论/依据/风险/建议/可证伪点)

Tool 3: validate_model

验证已有模型的一致性。

输入:

{
  "modelJson": "{...模型JSON字符串...}"
}

输出:

{
  "isValid": true,
  "checks": {
    "hasAllAgents": true,
    "hasStructure": true,
    "hasHypothesis": true,
    "hasMetadata": true,
    "agentTypesAreValid": true
  },
  "issues": [],
  "warnings": []
}

扩展指南

自定义Agent Prompt

编辑 src/agents/prompts/{agent}-agent.md
遵循统一格式:
- ## 角色定义
- ## 核心职责
- ## 分析框架
- ## 输出格式 (CRITICAL)
- ## 关键约束
修改后无需重启,AI会自动加载最新Prompt

添加新的Agent类型

在 src/types.ts 中添加新的AgentType
创建 src/agents/prompts/{new-agent}-agent.md
在 src/agents/agent-factory.ts 的createAllAgents()中注册
添加对应的测试用例

自定义冲突检测规则

在 src/workflow/conflict-resolver.ts 中添加新的检测函数:

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

测试

运行所有测试:

bun test

测试覆盖:

Agent Prompt文件完整性
Agent工厂与执行
冲突检测(3种规则)
工作流编排器(6步流程)
端到端示例
执行时间基准(<60秒)

贡献

欢迎贡献!请遵循:

Fork项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'feat: Add AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建Pull Request

提交规范:

feat: 新功能
fix: Bug修复
docs: 文档更新
refactor: 代码重构
test: 测试相关

许可证

MIT

联系方式

问题反馈: GitHub Issues
讨论交流: GitHub Discussions

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "socialguessskills": {
      "command": "npx",
      "args": []
    }
  }
}

SocialGuessSkills

Описание

README

简介

快速开始

安装

配置Biome

运行示例

运行配置（环境变量）

MCP集成(推荐)

使用示例

1. 完整推演(reasoning tool)

2. 单Agent查询(query_agent tool)

3. 模型验证(validate_model tool)

架构概览

API参考

Tool 1: reasoning

Tool 2: query_agent

Tool 3: validate_model

扩展指南

自定义Agent Prompt

添加新的Agent类型

自定义冲突检测规则

项目结构

测试

贡献

许可证

联系方式

Как установить

Похожие MCP

Fetch

AWS KB Retrieval

Spring AI MCP Server

llm-analysis-assistant

Command Palette

SocialGuessSkills

Описание

README

简介

快速开始

安装

配置Biome

运行示例

运行配置（环境变量）

MCP集成(推荐)

使用示例

1. 完整推演(reasoning tool)

2. 单Agent查询(query_agent tool)

3. 模型验证(validate_model tool)

架构概览

API参考

Tool 1: reasoning

Tool 2: query_agent

Tool 3: validate_model

扩展指南

自定义Agent Prompt

添加新的Agent类型

自定义冲突检测规则

项目结构

测试

贡献

许可证

联系方式

Как установить

Похожие MCP

Fetch

AWS KB Retrieval

Spring AI MCP Server

llm-analysis-assistant