产品需求文档（PRD）

1 目标

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

2 背景与动机

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

3 范围

在范围内（MVP）

• 一个MCP工具：systems_thinking_writer（每次PUT/POST完整JSON）
• 验证与差距检测（硬结构检查）
• 最新文档的原子持久性（内存到Postgres JSONB）
• HTTP流传输（FastMCP默认）
• 基本可观测性（请求日志，健康端点）

不在范围内（后MVP）

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

4 角色与用例

角色	工作任务
LLM代理	迭代构建完整的系统模型；持续重试直到验证通过
系统分析师	获取当前的JSON文档用于可视化或手动审查
DevOps	部署并监控MCP服务

5 功能需求

5.1 工具定义

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

5.2 端点行为

方法	路径	正文	响应
POST	/model	JSON文档	验证结果及存储文档副本
GET	/model	–	最新的存储文档

服务器在每次成功的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": "常数/参数", "is_applicable": false }, … ],
  "interventions": [ { "target_leverage_id": 4, "proposal": "…", "expected_effect": "…", "confidence": 0.7 } ]
}

7 架构和技术栈

• 运行时：Node 20+ 与 TypeScript
• 框架：FastMCP（HTTP流传输）
• 验证：Zod（模式复用于提示和运行时）
• 持久化：内存映射 → 每晚刷新到Postgres（JSONB）
• 容器：具有多阶段构建的Dockerfile（tsc编译然后dist运行）
• 可观测性：pino日志，/healthz端点用于k8s存活/就绪性

组件图（文本）

客户端代理 → FastMCP工具 → Zod验证器 → 内存缓存 → Postgres
                                   ↑
                        缺陷检测逻辑

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

使用以下简化的指导语句作为systems_thinking_writer工具描述，以便AI知道何时以及如何使用该工具：

何时使用 – 当你需要一个结构化的、梅多斯风格的复杂情况快照，其中明确存在相互作用的部分和反馈（如城市交通、产品采用、气候政策）时调用此工具。

字段含义

• boundary.purpose – 系统的“为什么”。从观察的行为中推断，而不是修辞。 fileciteturn3file4L20-L30
• elements & interconnections – 名词及其物理/信息链接。 fileciteturn3file9L38-L41
• stocks & flows – 积累及其变化率。 fileciteturn3file3L9-L22
• loops – 平衡（B）减弱变化；强化（R）放大。 fileciteturn3file11L12-L19
• leverage_points – 梅多斯的12个干预杠杆，从参数（12）到范式转变（2）和“超越范式”（1）。 fileciteturn3file2L34-L38

如何识别一个系统 A) 存在部分，并且 B) 它们相互影响，并且 C) 它们产生不同于每个部分单独行为的独特行为，并且 D) 该行为随时间持续。 fileciteturn3file1L18-L25

推荐填写路径

1. 目的与边界 – 各自一句话。
2. 元素列表 – 只有名词。
3. 互连 – 因果、流量或信息链接。
4. 库存与流量 – 声明可测量的存储，然后是流入/流出管道。
5. 反馈循环 – 标记每个循环为B或R；引用涉及的库存。
6. 杠杆点 – 勾选适用的ID（1-12）。
7. 干预措施 – 可选提案，针对杠杆ID。

持续迭代直到服务器返回complete: true。

---

9 扩展系统思维参考（团队专用）

快速访问备忘录，这样我们就不必每冲刺重新扫描梅多斯。

概念	一句话	快速合理性检查
元素	系统中的有形或无形部分	能否指出来？如果是，那就是一个元素。
互连	物理流动或信息信号	改变A是否会在没有外部影响的情况下改变B？
目的/功能	系统产生的稳定模式	观察行为，而不是使命陈述。
库存	过去流动的记忆（浴缸水、金钱）	单位必须随着时间累积。
流量	改变库存的速率（流入/流出）	具有时单位。
平衡循环（B）	目标寻求稳定器	如果差异随时间缩小，那就是B。
强化循环（R）	自我放大增长/衰减	指数趋势；注意翻倍时间。
延迟	原因与效果之间的间隔	寻找振荡或过度反应。
层次结构	具有自己的目的的嵌套子系统	较低层级紧密耦合，较高层级松散。
韧性	吸收冲击并保持目的的能力	多样性、缓冲、模块化松弛增加它。
杠杆点ID 12 → 1	参数 → 反馈强度 → 信息流 → 规则 → 自组织 → 目的 → 范式 → 超越范式	数字越高越容易调整，数字越低越强大但文化上更难。

字段深入探讨

• boundary.scope_in / scope_out – 明确表述；模糊会导致模型蔓延。
• elements – 优先催化行动者（出现在许多循环中的那些）。
• interconnections.type – 因果（实线箭头），流量（管道），信息（虚线）。
• stocks – 检查每个是否有至少一个流入或流出；否则它是惰性的。
• flows.rate_expr – 保持人类可读（0.1 * 需求）。解析器待定。
• loops – 使用动词短语加极性命名循环（销售再投资R）。
• leverage_points – 如果is_applicable=true但没有干预措施，则发出警告。

快速诊断问题

1. 哪个库存意外地变化最快？为什么？
2. 当前哪个循环主导行为？
3. 最大的信息延迟在哪里？
4. 哪个杠杆点需要最少的政治资本来推动？

“仅凭了解元素，无法得知系统的运行。” fileciteturn3file14L1-L4