Systems Thinking

产品要求文件（PRD）

1目标

交付a 系统思维MCP服务器 它允许AI代理通过HTTP提交完整的系统思维表示（单个JSON文档）。服务器验证结构，原子地持久化最新版本，并返回验证间隙，以便代理可以迭代，直到文档完成。

2背景和动机

顺序思维服务器证明，强制LLM通过严格的I/O契约可以提高推理质量。我们将相同的模式应用于Donella Meadows风格的系统分析，使代理能够以最小的服务器逻辑推理边界、库存/流量、反馈循环和杠杆点。

3范围

范围内（MVP）

• 一个MCP工具： systems_thinking_writer （每次发送完整的JSON）
• 验证和间隙检测（硬结构检查）
• 最新文档的原子持久性（内存中）→ Postgres JSONB）
• HTTP流传输（FastMCP默认）
• 基本可观察性（请求日志、健康端点）

超出范围（MVP后）

• 软警告/启发式（例如，过多的强化循环）
• 细粒度PATCH更新
• 多文档分支或版本历史导航
• 基于角色的读/写权限模型

4个角色和用例

5功能要求

5.1工具定义

• 名字: systems_thinking_writer
• 输入：符合Zod模式的完整JSON文档
• 输出: { complete: boolean, missing_fields: string[], inconsistency_warnings: string[] }
• 合同：如果JSON模式失败，则拒绝（HTTP 422）；否则返回验证数组。 complete === true 仅当两个数组都为空时。

5.2端点行为

_服务器在每次成功POST时覆盖现有文档。_

5.3验证规则（MVP）

• 每 flow.from_stock & flow.to_stock 必须匹配 stocks.id
• 循环只能引用已声明的元素
• 如果 leverage_point.is_applicable === true 必须至少有一个匹配项 intervention.target_leverage_id

6数据模型（节略）

{
  "version": "1.0.0",
  "system_name": "string",
  "boundary": { "purpose": "string", "scope_in": [""], "scope_out": [""] },
  "elements": ["string"],
  "interconnections": [ { "from": "", "to": "", "type": "causal|flow|info" } ],
  "stocks": [ { "id": "", "unit": "", "description": "" } ],
  "flows":  [ { "id": "", "from_stock": "", "to_stock": "", "rate_expr": "" } ],
  "loops": {
    "balancing":   [ { "id": "", "description": "" } ],
    "reinforcing": [ { "id": "", "description": "" } ]
  },
  "leverage_points": [ { "id": 12, "label": "Constants / parameters", "is_applicable": false }, … ],
  "interventions": [ { "target_leverage_id": 4, "proposal": "…", "expected_effect": "…", "confidence": 0.7 } ]
}

7建筑与技术栈

• 运行时：节点20+，带 TypeScript
• 框架: FastMCP （HTTP流传输）
• 验证: 萨德 （模式重复用于提示和运行时）
• 持久性：内存映射→ 夜间冲洗至 Postgres （JSONB）
• 容器：具有多阶段构建的Dockerfile（tsc编译然后dist-run）
• 可观测性：皮诺原木， /healthz k8s活性/准备就绪终点

组件图（文本）

Client Agent → FastMCP Tool → Zod Validator → InMemoryCache → Postgres
                                   ↑
                        Gap‑Detection Logic

8系统思维教程（工具提示种子）

请逐字使用以下简明指南 systems_thinking_writer 工具描述 所以AI知道 _当_ 和 _如何_ 使用该工具：

何时使用 –当您需要一个结构化的、Meadows风格的复杂情况快照时，可以随时调用此工具，该快照明显包含相互作用的部分和反馈（例如城市交通、产品采用、气候政策）。 田地意味着什么 - 边界.目的 系统的 _为什么_根据观察到的行为推断，而不是修辞。 菲力西转弯3档4L20-L30 - 元件和互连 –名词及其物理/信息链接。 菲力西转弯3档9L38-L41 - 库存和流量 –累积和改变它们的速率。 菲力西转弯3L9-L22 - 循环 –平衡（B）抑制变化；增强（R）放大。 菲力西转弯3档11L12-L19 - 杠杆_点 Meadows的12个干预杠杆，从参数（12）到范式转变（2）和 _超越范式_ (1). 菲力西转弯3档2L34-L38 如何识别系统 A） 部件存在， 和 B） 它们相互影响， 和 C） 它们创造了与每个部分不同的行为， 和 D） 这种行为会随着时间的推移而持续下去。 菲力西转弯3档1L18-L25 推荐填写路径 1. 目的和边界 每人一句话。 1. 元素列表 -只有名词。 1. 互连 –因果关系、流程或信息链接。 1. 库存和流量 -申报可测量的库存，然后申报流入/流出管道。 1. 反馈环 –标记每个循环B或R；参考涉及股票。 1. 杠杆点 –勾选适用的ID（1‑12）。 1. 干预措施 –针对杠杆ID的可选提案。

继续迭代，直到服务器返回 complete: true.

______________________________________________________________________

9扩展系统思维参考（仅供团队使用）

快速访问备忘单，这样我们就不必每次冲刺都重新扫描Meadows。

逐场深潜

• 范围内/范围外 –明确；模糊性会滋生模型蠕变。
• 元素 –优先考虑催化因素（出现在许多循环中的因素）。
• 互连类型 – causal （实线箭头）， flow （管道）， info （虚线）。
• 股票 –检查每个至少有一个流入 _或_ 外流；否则它是惰性的。
• flows.rate_expr –保持可读性(0.1 * demand).解析器待定。
• 循环 –带有动词短语+极性的名称循环(Sales Reinvest R).
• 杠杆_点 –如果 is_applicable=true 但警告说，没有干预。

快速诊断问题

1. 什么股票出乎意料地变化最快？为什么？
2. 哪个循环目前主导着行为？
3. 最大的信息延迟在哪里？
4. 哪个杠杆点需要 _最少_ 政治资本推动？

“仅仅通过了解元素无法了解系统的行为。”菲力西转弯3档14L1-L4

______________________________________________________________________