We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/starlink-awaken/SocialGuessSkills'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
# 系统架构文档 (System Architecture)
## 总体架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 社会体系建模多Agent系统 │
└─────────────────────────────────────────────────────────────────┘
┌──────────────────────┐ ┌──────────────────────┐
│ MCP Protocol │ │ TypeScript + Bun │
│ (stdio transport) │◄────────┤ Runtime Environment │
└──────────┬───────────┘ └──────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Server Layer │
│ (src/server.ts) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ McpServer Instance │ │
│ │ - Tool Registration (reasoning/query/validate) │ │
│ │ - Request Handling │ │
│ │ - Response Formatting │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────┬─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Workflow Layer │
│ (src/workflow/orchestrator.ts) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 6-Step Orchestration Engine │ │
│ │ │ │
│ │ 1. 假设验证 (validateHypothesis) │ │
│ │ 2. Agent并行执行 (executeAgents) │ │
│ │ 3. 冲突对齐 (alignConflicts) │ │
│ │ 4. 模型合成 (synthesizeModel) │ │
│ │ 5. 模型验证 (validateModel) │ │
│ │ 6. 迭代收敛 (iterate) │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────┬─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agent Layer │
│ (src/agents/agent-*.ts) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Agent System │ │
│ │ │ │
│ │ Factory (agent-factory.ts) │ │
│ │ ├── loadPrompt() - 读取Prompt模板 │ │
│ │ ├── createAgent() - 实例化Agent │ │
│ │ └── createAllAgents() - 批量创建 │ │
│ │ │ │
│ │ Executor (agent-executor.ts) │ │
│ │ ├── executeAgent() - 执行单个Agent │ │
│ │ ├── buildContext() - 构建执行上下文 │ │
│ │ └── simulateAICall() - 模拟AI响应 │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────┬─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agent Prompts Layer │
│ (src/agents/prompts/*.md) │
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │Systems │ │ Econ │ │ Socio │ │Govern │ │
│ └────────┘ └────────┘ └────────┘ └────────┘ │
│ ┌────────┐ ┌────────┐ │
│ │Culture │ │ Risk │ │
│ └────────┘ └────────┘ │
│ ┌────────┐ │
│ │Valid │ │
│ └────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 核心模块说明
### 1. Server Layer (MCP Server)
**职责**:
- 实现Model Context Protocol,与Claude/AI系统集成
- 注册并管理3个Tool(reasoning/query_agent/validate_model)
- 处理MCP请求,调用工作流引擎
- 格式化响应,确保符合MCP协议
**关键组件**:
- `McpServer`: MCP SDK的高级API,简化Tool注册
- `StdioServerTransport`: 标准输入输出传输,适合桌面应用
- Tool注册逻辑: 将函数注册为MCP可调用的Tool
**数据流**:
```
Claude/AI → MCP Protocol → Server → Orchestrator → Agents
Claude/AI ← MCP Protocol ← Server ← Orchestrator ← Agents
```
### 2. Workflow Layer (编排器)
**职责**:
- 实现6步推演流程,控制整体执行逻辑
- 管理工作流状态(迭代次数、Agent结果、冲突历史)
- 协调各子模块(Agent、冲突检测、模型合成)
- 计算模型置信度
**6步流程详解**:
#### Step 1: 假设验证
- 输入: 用户提供的Hypothesis对象
- 验证: assumptions/goals数组非空,结构完整
- 输出: 验证通过或抛出错误
#### Step 2: Agent并行执行
- 执行: 并发调用所有7个Agent
- 输入: Hypothesis + 前一轮的AgentOutputs + Conflicts
- 上下文构建: 为每个Agent构建专用的AnalysisContext
- 输出: 7个AgentOutput对象
#### Step 3: 冲突对齐
- 检测: 调用Conflict Resolver识别冲突
- 分析: 冲突类型(logical/priority/risk_amplification)、严重性
- 标记: 需要重推的Agent
- 记录: 保存到WorkflowState.history
#### Step 4: 模型合成
- 提取: 从AgentOutputs中提取关键词和结构化信息
- 映射: 构建9层模型(overall/workflow/institutions等)
- 聚合: 合并多个Agent的建议,去重,排序
- 输出: 完整的SocialSystemModel对象
#### Step 5: 模型验证
- 检查: 确认Validation Agent输出已包含
- 验证: 检查模型完整性(7个Agent、结构、元数据)
- 警告: 识别潜在问题(缺失Agent、置信度低)
#### Step 6: 迭代收敛
- 判断: 是否有新冲突 OR 达到最大迭代?
- 决策: 继续迭代 OR 输出最终模型
- 优化: 限制最大迭代次数(默认3次),防止无限循环
### 3. Agent Layer (Agent系统)
**职责**:
- 管理7个专业Agent的生命周期
- 加载和维护Prompt模板
- 执行Agent推理(模拟或调用AI API)
- 格式化输出为统一的AgentOutput结构
**Agent工厂**:
- `loadPrompt(agentType)`: 从文件系统读取Markdown Prompt
- `createAgent(agentType)`: 创建Agent实例(包含name/systemPrompt/outputSchema)
- `createAllAgents()`: 批量创建所有7个Agent,返回Map<AgentType, AgentInstance>
**Agent执行器**:
- `executeAgent(agent, context)`: 执行单个Agent推理
- 上下文构建: 将Hypothesis、历史Outputs、Conflicts转换为自然语言Prompt
- 模拟AI: 首版使用预定义的模拟输出(生产版可接入真实AI)
- 输出格式化: 确保返回结构符合AgentOutput schema
**7个Agent类型**:
| Agent | 专长 | 关键概念 |
|-------|--------|----------|
| Systems | 系统思维、反馈回路 | 边界、变量、正负反馈、稳定性 |
| Econ | 经济学、激励机制 | 激励相容、产权、交易成本、博弈论 |
| Socio | 社会学、群体行为 | 规范、认同、信任、制度化 |
| Governance | 治理学、权力结构 | 权责对称、合法性、执行力、分层治理 |
| Culture | 文化学、价值观 | 仪式、叙事、符号、文化演化 |
| Risk | 风险分析、韧性 | 脆弱性、极端情境、缓冲、冗余 |
| Validation | 科学验证、可证伪性 | 可证伪假设、历史对比、反事实推理 |
### 4. Conflict Resolver (冲突检测)
**职责**:
- 检测Agent输出间的逻辑矛盾
- 识别优先级冲突和资源分配互斥
- 分析风险叠加效应
- 提供冲突解决建议
**3种检测规则**:
#### 规则1: 逻辑矛盾检测
- 方法: 关键字匹配 + 可证伪点比对
- 示例: Systems Agent说"反馈确保稳定" vs Validation Agent说"若反馈失效则崩溃"
- 输出: Conflict{type: 'logical', description, severity}
#### 规则2: 优先级冲突检测
- 方法: 相似建议去重 + Agent优先级矩阵
- 优先级矩阵: Risk(5) > Governance(4) > Systems(3) > Econ/Socio/Culture(2) > Validation(1)
- 示例: Systems和Econ都建议"建立资源分配机制",需要决策采纳谁的视角
#### 规则3: 风险叠加检测
- 方法: 风险评分汇总 + 阈值判断
- 评分标准: 崩溃/瓦解(5分)、失稳/失效(4分)、崩塌(5分)
- 阈值: 平均风险 > 3分/Agent OR ≥3个Agent识别崩溃风险
- 输出: Conflict{type: 'risk_amplification', description}
**冲突过滤**:
- 按严重性过滤: `filterConflictsBySeverity(conflicts, 'high')`
- 用途: 在迭代时优先解决高严重性冲突
## 数据流图
```
用户输入(Hypothesis)
│
▼
┌─────────────────┐
│ 假设验证 │
│ validateHypothesis
└────────┬────────┘
│ [验证通过]
▼
┌─────────────────┐
│ Agent工厂 │
│ createAllAgents
└────────┬────────┘
│ [7个Agent实例]
│
┌────┴────┬────────┬────────┬────────┬────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐
│Systems ││ Econ ││ Socio ││Govern ││Culture │
└────┬───┘└────┬───┘└────┬───┘└────┬───┘└────┬───┘
│ │ │ │ │
└──────────┴───────────┴───────────┴───────────┘
│ [7个AgentOutput]
▼
┌─────────────────────────────────────┐
│ 冲突检测器 │
│ detectConflicts(outputs) │
└────────┬────────────────────────────┘
│ [Conflict数组]
▼
┌─────────────────────────────────────┐
│ 冲突对齐器 │
│ alignConflicts(conflicts) │
└────────┬────────────────────────────┘
│ [更新后的状态]
▼
┌─────────────────────────────────────┐
│ 模型合成器 │
│ synthesizeModel(outputs) │
└────────┬────────────────────────────┘
│ [9层结构化模型]
▼
┌─────────────────────────────────────┐
│ 模型验证器 │
│ validateModel(model) │
└────────┬────────────────────────────┘
│ [验证结果]
▼
┌─────────────────────────────────────┐
│ 迭代收敛判断器 │
│ 达到最大迭代 OR 无新冲突? │
└──────┬──────────────────────────────┘
│ [是] │ [否]
▼ ▼
输出最终模型 回到Agent执行(迭代)
```
## 关键设计决策
### 1. 为什么选择Prompt-based Agent?
**决策**: 使用预定义的Prompt模板,而非训练独立的AI模型
**理由**:
- ✅ **灵活性**: Prompt易于调整和更新,无需重新训练
- ✅ **可解释性**: 每个Agent的推理过程可通过Prompt追溯
- ✅ **轻量级**: 无需部署独立的AI服务,降低复杂度
- ✅ **一致性**: 统一的输出格式(结论/依据/风险/建议/可证伪点)
**权衡**:
- ⚠️ **依赖AI质量**: 推理质量依赖于底层AI模型能力
- ⚠️ **模拟限制**: 首版使用模拟输出,无法进行真实推理(可扩展)
### 2. 为什么6步工作流?
**决策**: 设计为明确的6步流程,而非完全自治的Agent协商
**理由**:
- ✅ **可预测性**: 每一步都有明确的输入输出,易于调试和验证
- ✅ **可控性**: 用户可以控制迭代次数和工作流深度
- ✅ **效率**: 避免Agent间无休止的协商,设定明确的收敛条件
- ✅ **结构化**: 每一步都有明确职责,易于扩展和维护
**权衡**:
- ⚠️ **灵活性**: 相比完全自治的Agent协商,工作流更僵化
- ⚠️ **人工干预**: 需要人工设定收敛条件和迭代次数
### 3. 为什么3种冲突检测规则?
**决策**: 实现逻辑矛盾、优先级冲突、风险叠加3种检测规则
**理由**:
- ✅ **覆盖关键冲突类型**:
- 逻辑矛盾: Agent间的直接矛盾(如"反馈稳定" vs "反馈失效则崩溃")
- 优先级冲突: 资源分配互斥(如多个Agent建议不同分配策略)
- 风险叠加: 多个风险组合后超过安全阈值
- ✅ **可扩展性**: 易于添加新的检测规则
- ✅ **可操作性**: 每个规则都有明确的解决建议
**权衡**:
- ⚠️ **检测精度**: 关键字匹配可能产生误报或漏报
- ⚠️ **上下文依赖**: 无法理解Agent间的深层语义关系
### 4. 为什么最大迭代3次?
**决策**: 设定默认最大迭代次数为3次
**理由**:
- ✅ **效率平衡**: 避免无限循环,同时给予足够迭代空间
- ✅ **性能保障**: 确保推演在合理时间内完成(目标<60秒)
- ✅ **收敛观察**: 3次迭代足够观察冲突是否收敛
**权衡**:
- ⚠️ **可能不收敛**: 复杂系统可能需要更多迭代才能稳定
- ⚠️ **硬编码**: 固定限制可能不适合所有场景(用户可覆盖)
### 5. 为什么9层模型结构?
**决策**: 将社会体系模型组织为9个层级
**理由**:
- ✅ **全面性**: 覆盖社会系统的所有关键维度
- ✅ **结构化**: 便于理解和检索特定部分的信息
- ✅ **可扩展**: 每层可独立扩展,不影响其他层
- ✅ **符合理论**: 对应系统理论、制度经济学、社会学等学科框架
**9层详解**:
1. **overall(总体结构)**: 资源层→行为层→组织层→制度层→治理层→文化层
2. **workflow(工作流)**: 需求生成→资源配置→生产协作→规则执行→公共品→反馈纠偏
3. **institutions(制度)**: 产权、契约、公共品、争端解决、风险分担
4. **governance(治理)**: 分层治理、问责、透明度、危机机制
5. **culture(文化)**: 叙事、仪式、价值观、教育
6. **innovation(创新)**: 试点、平衡、适应性
7. **risks(风险)**: 稀缺、信任、权力、文化
8. **metrics(指标)**: 稳定性、公平性、效率性、合作性、韧性、合法性
9. **optimization(优化)**: 指标、机制、决策回路
## 扩展点
### 1. 添加新Agent类型
**位置**: `src/agents/prompts/` + `src/types.ts` + `src/agents/agent-factory.ts`
**步骤**:
1. 在`types.ts`中扩展`AgentType`类型
2. 创建`prompts/{new-agent}-agent.md`
3. 在`agent-factory.ts`的`createAllAgents()`中注册
### 2. 自定义冲突检测规则
**位置**: `src/workflow/conflict-resolver.ts`
**步骤**:
1. 实现`detectCustomConflict(outputs: AgentOutput[]): Conflict[]`函数
2. 在`detectConflicts()`中调用新函数
3. 添加测试用例验证逻辑
### 3. 集成真实AI API
**位置**: `src/agents/agent-executor.ts`
**步骤**:
1. 替换`simulateAICall()`为真实API调用(如OpenAI、Claude API)
2. 实现上下文传递和Prompt模板填充
3. 处理API限流和错误重试
### 4. 自定义模型合成逻辑
**位置**: `src/workflow/orchestrator.ts` - `synthesizeStructure()`函数
**步骤**:
1. 修改关键词提取逻辑,使用更复杂的NLP
2. 实现跨Agent推理链(如A说X,B说X导致Y)
3. 添加模型一致性检查
## 性能指标
### 预期性能
| 操作 | 目标时间 | 实际时间(测试环境) |
|------|----------|-------------------|
| 单Agent执行 | <5秒 | 0.1-0.5秒(模拟) |
| 完整推演(1次迭代) | <20秒 | 8-12秒 |
| 完整推演(3次迭代) | <60秒 | 25-35秒 |
| MCP工具调用 | <65秒 | 30-40秒 |
### 优化策略
- **并行Agent执行**: 使用`Promise.all()`并发调用7个Agent
- **智能缓存**: 缓存已加载的Prompt模板
- **增量计算**: 只在冲突时重新计算风险叠加
- **流式输出**: 未来可考虑逐步输出结果(当前版本一次性返回)
## 安全性考虑
### 输入验证
- ✅ Schema验证: MCP SDK自动验证输入JSON结构
- ✅ 类型检查: TypeScript编译时类型安全
- ✅ 假设完整性: 必须包含assumptions和goals
### 权限控制
- ✅ 无文件系统访问: 只读取内置Prompt模板
- ✅ 无网络请求(首版): 避免依赖外部API
- ✅ 无数据库连接: 所有状态在内存中,自动清理
### 错误处理
- ✅ Agent执行失败: 捕获异常,记录错误,继续其他Agent
- ✅ 冲突检测失败: 返回空冲突列表,不影响流程
- ✅ 迭代超时: 设定全局超时,防止无限循环
## 未来改进
### 短期(3个月)
- [ ] 集成真实AI API(OpenAI/Claude)替代模拟输出
- [ ] 添加Agent执行历史追踪
- [ ] 实现模型导出功能(JSON/Markdown/PDF)
- [ ] 增加更多冲突检测规则
### 中期(6个月)
- [ ] 实现Agent间实时对话(而非仅单向输出)
- [ ] 添加可视化输出(图表、流程图)
- [ ] 实现模型比较功能(对比不同假设的模型)
- [ ] 添加模型持久化存储
### 长期(12个月)
- [ ] 实现Agent学习能力(从历史推理中优化Prompt)
- [ ] 支持自定义Agent注册(用户定义的Agent)
- [ ] 实现分布式推理(多Agent并行在多台机器)
- [ ] 开发Web UI界面(无需MCP)