Merge pull request #7 from AckerlyLau/main

Fix #6 and improvements in NodeTemplate/Docs

Author: AckerlyLau

README.md

@@ -28,6 +28,93 @@ Key capabilities:
 - **Visualization and observability:** **MASFactory Visualizer** provides topology preview, runtime tracing, and human-in-the-loop interaction.
 - **Context protocol (`ContextBlock`):** organize Memory / RAG / MCP context sources in a structured way, with automatic injection and on-demand retrieval.
 
+## 🧭 Why Choose MASFactory
+
+As multi-agent systems grow more capable, orchestration is still largely stuck in the age of manual assembly: either teams hand-write workflow code, or they drag and configure nodes one by one on a canvas. With Vibe Graphing, MASFactory aims to free people from tedious orchestration work: express the intent in natural language, let AI draft the collaboration structure, keep refining it with human corrections and confirmations, and finally compile the result into an executable graph workflow.
+
+<p align="center">
+  <img
+    src="docs/src/public/imgs/readme/vibegraphing_diagram_en.png"
+    alt="Vibe Graphing pipeline from intent to executable workflow"
+    width="780"
+  />
+</p>
+
+This shifts human effort away from low-level wiring and repetitive configuration, and back toward designing the multi-agent system itself.
+
+Viewed more directly, today's multi-agent development frameworks roughly fall into the following categories:
+
+| Platform Type | Representative Products | Positioning | Support for Multi-Agent Systems |
+| --- | --- | --- | --- |
+| **Code frameworks** | `MASFactory`, ChatDev2(DevAll), LangGraph, AutoGen | Build complex multi-agent systems | Still highly dependent on handwritten code and engineering implementation |
+| **Low-code workflow platforms** | `MASFactory`, ChatDev2(DevAll), Coze, Dify | Lower the barrier to building multi-agent systems with low-code workflows | Difficult to support deep customization and complex topologies for advanced systems |
+| **Vibe Graphing orchestration frameworks** | `MASFactory` | Rapidly design and iterate multi-agent systems with lower human cost | Humans do not need to spend much effort on coding or dragging nodes, only on clearly describing needs and refining the design through dialogue |
+
+## 🏗️ System Architecture
+
+MASFactory adopts the widely used graph-centric approach to multi-agent orchestration and abstracts the system into four layers:
+
+<p align="center">
+  <img
+    src="docs/src/public/imgs/readme/framework.png"
+    alt="MASFactory framework layers"
+    width="860"
+  />
+</p>
+
+- **Graph skeleton layer:** `Node` and `Edge` are the lowest-level abstractions, using graph structure to represent collaboration relationships, dependencies, and message flow among agents.
+- **Component layer:** this layer further packages `Node` and `Edge` into reusable collaboration units, so developers do not need to assemble workflows from scratch every time and can instead build multi-agent systems like reusable blocks:
+
+> - `Agent` is the most basic execution unit: an agent node with roles, instructions, tools, Memory, RAG, and related capabilities, responsible for concrete analysis, generation, and tool-use tasks.
+>
+> - `Graph` packages multiple nodes as a nestable subgraph, allowing complex workflows to be designed hierarchically and reused locally. A single phase can itself become a node inside a larger graph.
+>
+> - `Loop` handles iterative tasks such as repeated discussion, continuous revision, or testing until success. It turns "repeat execution until a condition is met" into a standard component.
+>
+> - `Switch` supports branching and dynamic routing. It can switch execution paths based on explicit conditions or use model capabilities to decide where messages should go, enabling more flexible collaboration topologies.
+>
+> - `Human` brings human-in-the-loop steps such as confirmation, conversational input, file review, and editing into the graph, so the system is not limited to fully automated execution and can involve people at key stages.
+>
+> - `ComposedGraph` and `NodeTemplate` provide two additional reuse mechanisms on top of the components above. The former focuses on "declare a structure first, then instantiate and assemble it," while the latter packages common collaboration structures into reusable components. MASFactory includes built-in graph patterns such as `InstructorAssistantGraph` and `BrainstormingGraph` for out-of-the-box use.
+
+  **Protocol layer:** through `Message Adapter` and `Context Adapter`, MASFactory unifies communication protocols together with Memory, RAG, MCP, and related context capabilities, making it easier to integrate external frameworks into the system.
+
+- **Interaction layer:** MASFactory supports three development paradigms:
+
+ > - Natural-language workflow construction based on `Vibe Graphing`, reducing the human cost of system development.
+ > - Two code-centric styles, `Declarative` and `Imperative`, for developers who want more flexible control over workflow authoring.
+ > - Manual workflow design through `MASFactory Visualizer`, preserving familiar low-code drag-and-drop habits.
+
+MASFactory's advantage is not that it offers yet another way to build workflows, but that it unifies code authoring, visual editing, and natural-language-driven orchestration inside the same system. Developers can write workflows by hand, assemble them visually, or let AI draft the structure first and then compile it into an executable multi-agent workflow. These three modes are not isolated from one another; they can coexist inside the same project.
+
+## 🎬 Flexible Combination of Three Development Modes with Unified Runtime Tracing
+
+Whether you start from code, drag-and-drop editing, or Vibe Graphing, the resulting graph structure can enter the same Visualizer for preview, tracing, and human intervention.
+
+### Coding with Graph Preview
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/coding.gif" alt="Code preview in MASFactory Visualizer" width="860" />
+</p>
+
+### Drag-and-Drop Design
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/drag.gif" alt="Drag and drop workflow design" width="860" />
+</p>
+
+### Vibe Graphing Interaction
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/vibe_2.gif" alt="Vibe Graphing interaction" width="860" />
+</p>
+
+### Runtime Monitoring
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/monitor.gif" alt="Runtime monitoring and tracing" width="860" />
+</p>
+
 ## ⚡ Quick Start
 
 ### 1) Install MASFactory (PyPI)

README.zh.md

@@ -27,6 +27,91 @@
 - **可视化与可观测：** 配套 **MASFactory Visualizer** 提供拓扑预览、运行追踪与人机交互能力。
 - **上下文协议（ContextBlock）：** 以结构化方式组织 Memory / RAG / MCP 等上下文源，支持自动注入与按需检索。
 
+## 🧭 为什么选择 MASFactory
+
+随着多智能体能力快速增强，系统编排却仍停留在手工编排的时代：要么手写工作流代码，要么在画布里逐个节点拖拽配置。MASFactory 希望通过 Vibe Graphing, 把人类从繁复的编排工作中解放出来：先用自然语言表达意图，让 AI 起草协作结构，再由人持续纠正和确认，最后把结果编译成可执行图工作流。
+
+<p align="center">
+  <img
+    src="docs/src/public/imgs/readme/vibegraphing_diagram.png"
+    alt="Vibe Graphing 从意图到可执行工作流"
+    width="780"
+  />
+</p>
+
+这样一来，人类的开发重点就从低层连线和重复配置，转移到了多智能体的设计本身。
+
+如果用更直观的方式来看今天的多智能体开发工具，大致可以分成下面几类：
+
+| 平台类型                   | 代表产品                                           | 定位                                     | 对多智能体的支持                                             |
+| -------------------------- | -------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
+| **代码框架**               | `MASFactory`、ChatDev2(DevAll)、LangGraph、AutoGen | 构建复杂多智能体系统                     | 高度依赖手写代码与工程实现                                   |
+| **低代码工作流平台**       | `MASFactory`、ChatDev2(DevAll)、Coze、Dify         | 低门槛低代码开发多智能体系统             | 难以支撑复杂多智能体系统的深度定制与复杂拓扑                 |
+| **Vibe Graphing 编排框架** | `MASFactory`                                       | 低人力成本实现多智能体系统快速设计和迭代 | 人类无需付出过多的开发、拖拽的操作，只需要将自己的需求描述清楚，并在对话中细化设计细节。 |
+
+## 🏗️ 系统框架图
+MASFactory采用业界常用的以Graph为中心的多智能体编排方法，将系统抽象为4层：
+<p align="center">
+  <img
+    src="docs/src/public/imgs/readme/framework.png"
+    alt="MASFactory 框架分层"
+    width="860"
+  />
+</p>
+- **图骨架层**：以 `Node` 和 `Edge` 作为最底层抽象，用图结构表达多智能体之间的协作关系、依赖关系和消息流动
+- **组件层**：组件层的作用，是把底层的 `Node`、`Edge` 进一步封装成可复用的协作单元，让开发者不必每次都从最底层手工拼装工作流，而是可以像搭积木一样组织多智能体系统：
+
+> - `Agent` 是最基础的执行单元，对应一个具备角色、指令、工具、Memory、RAG 等能力的智能体节点，负责完成具体分析、生成、调用等任务。
+>
+> - `Graph` 用于把多个节点封装成可嵌套的子图，让复杂流程可以分层设计、局部复用，也让“一个阶段”本身还能继续作为“另一个更大图里的节点”。
+>
+> - `Loop` 用于处理多轮迭代型任务，例如反复讨论、持续修订、测试直到通过等场景，本质上把“重复执行直到满足条件”为止的控制逻辑做成了标准组件。
+>
+> - `Switch` 用于做分支判断和动态路由，可以按照显式条件切换执行路径，也可以结合模型能力决定消息应该流向哪个节点，从而支持更灵活的协作拓扑。
+>
+> - `Human` 则把人工确认、对话输入、文件审阅与编辑等 Human-in-the-loop 环节纳入图中，使多智能体系统不再是纯自动流程，而是能够在关键步骤引入人类参与。
+>
+> - `ComposedGraph`和`NodeTemplate` 是MASFactory 在上述组件的基础之上进一步提供了两套复用能力组件，前者负责“先声明模板、后实例化装配”，后者负责把常见协作结构直接封装成可复用组件。MASFactory内置了常用的图结构(`InstructorAssistantGraph`、`BrainstormingGraph`等)，方便用户开箱即用。
+
+  **协议层**：通过 `Message Adapter` 与 `Context Adapter`，统一处理通信协议以及 Memory、RAG、MCP 等上下文能力，方便用户接入相关框架增强自己的多智能体系统。
+
+- **交互层**：MASFactory同时提供三类开发范式：
+
+ > - 基于`Vibe Graphing`的自然语言交互构造智能体工作流，降低系统开发的人力开支。
+ > - 基于`声明式`、`命令式`的两种代码开发方式，可以更加灵活自由地编写工作流。
+ > - 通过 `MASFactory Visualizer`以拖拽的方式手动设计工作流，兼容大家的低代码开发习惯。 
+
+MASFactory 的优势并不在于“再提供一种工作流搭建方式”，而在于它把代码开发、可视化编辑和自然语言驱动编排统一进了同一套系统。开发者既可以自己写，也可以自己拖拽，还可以先让 AI 起草系统结构，再编译成可运行的多智能体工作流——以上三中方式并不是相互割裂独立的，而是可以在同一个项目中同时使用。
+
+## 🎬 三种开发方式自由组合，并提供统一的运行时追踪
+
+无论你先写代码、先拖拽，还是先做 Vibe Graphing，对应的图结构都能进入同一个 Visualizer 里做预览、追踪和人工介入。
+
+### 代码编写与图结构实时预览
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/coding.gif" alt="MASFactory Visualizer 代码预览" width="860" />
+</p>
+
+### 拖拽式设计
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/drag.gif" alt="拖拽式工作流设计" width="860" />
+</p>
+
+### Vibe Graphing 交互
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/vibe_2.gif" alt="Vibe Graphing 交互式构图" width="860" />
+</p>
+
+### 运行时监测
+
+<p align="center">
+  <img src="docs/src/public/imgs/readme/monitor.gif" alt="运行时监测与追踪" width="860" />
+</p>
+
+
 ## ⚡ 快速开始
 
 ### 1) 安装 MASFactory（PyPI）

docs/src/examples/agents.md

@@ -30,7 +30,7 @@ model = OpenAIModel(
 agent = SingleAgent(
     name="demo_single",
     model=model,
-    instructions="Reply in JSON with field {answer}.",
+    instructions="Reply in JSON with an 'answer' field.",
     prompt_template="Question: {query}",
 )
 

docs/src/guide/context_adapters.md

@@ -289,7 +289,7 @@ from datetime import datetime, timezone
 from masfactory import Agent, SimpleKeywordRetriever
 
 def get_utc_now() -> str:
-    \"\"\"Get current UTC time in ISO format.\"\"\"
+    """Get current UTC time in ISO format."""
     return datetime.now(timezone.utc).isoformat()
 
 retriever = SimpleKeywordRetriever({"doc": "..."}, passive=False, active=True)

docs/src/guide/node_template.md

@@ -164,8 +164,24 @@ from masfactory.core.node_template import template_defaults_for, template_overri
 Phase = NodeTemplate(
     Loop,
     nodes=[
-        ("assistant", NodeTemplate(Agent)),
-        ("instructor", NodeTemplate(Agent)),
+        (
+            "assistant",
+            NodeTemplate(
+                Agent,
+                model=object(),  # build() example only
+                instructions="You are the Assistant.",
+                prompt_template="{workspace}",
+            ),
+        ),
+        (
+            "instructor",
+            NodeTemplate(
+                Agent,
+                model=object(),  # build() example only
+                instructions="You are the Instructor.",
+                prompt_template="{workspace}",
+            ),
+        ),
     ],
     edges=[
         ("CONTROLLER", "assistant", {"workspace": ""}),

docs/src/progressive/chatdev_declarative.md

@@ -17,6 +17,8 @@ Start from the minimal phase:
 
 `ENTRY → instructor → assistant → EXIT`
 
+To keep `user_demand` transparent, `ENTRY` also passes it directly to `assistant`.
+
 In this structure, `Assistant` produces a draft/result, and `Instructor` provides guidance to converge the output.
 
 <ThemedDiagram
@@ -58,7 +60,8 @@ Assistant = NodeTemplate(
 )
 
 # 3) Assemble the graph with nodes/edges:
-#    ENTRY → instructor → assistant → EXIT
+#    Main flow: ENTRY → instructor → assistant → EXIT
+#    Plus a direct ENTRY → assistant edge to pass user_demand transparently.
 #    Note: `Edge.keys` defines the message field contract. `Agent.output_keys` is aggregated from outgoing edges.
 g = RootGraph(
     name="p1_workflow_decl",
@@ -68,6 +71,7 @@ g = RootGraph(
     ],
     edges=[
         ("ENTRY", "instructor", {"user_demand": "user demand"}),
+        ("ENTRY", "assistant", {"user_demand": "user demand"}),
         ("instructor", "assistant", {"instructor_guidance": "Instructor guidance"}),
         ("assistant", "EXIT", {"assistant_response": "Assistant response"}),
     ],
@@ -84,7 +88,7 @@ print(out["assistant_response"])
 ## Step 2 — Multi-turn collaboration with Loop (edge messages)
 
 Step 1 runs only once. In practice, a phase usually needs multiple turns to converge.  
-Here we introduce `Loop` and place the `Instructor → Assistant` link inside the loop body. Each turn, fields are carried by edge keys.
+Here we introduce `Loop` and place the `Instructor → Assistant` link inside the loop body. To keep `user_demand` transparent, `CONTROLLER` also passes it directly to `assistant` each turn.
 
 <ThemedDiagram
   light="/imgs/tutorial/chatdev-lite/prog-04-loop-edge-en-light.svg"
@@ -137,6 +141,7 @@ DialogLoop = NodeTemplate(
     edges=[
         # Loop does not use ENTRY/EXIT; it uses CONTROLLER as the scheduling endpoint.
         ("CONTROLLER", "instructor", {"user_demand": "user demand", "assistant_response": "previous Assistant response"}),
+        ("CONTROLLER", "assistant", {"user_demand": "user demand"}),
         ("instructor", "assistant", {"instructor_guidance": "Instructor guidance"}),
         ("assistant", "CONTROLLER", {"assistant_response": "Assistant response"}),
     ],
@@ -641,4 +646,3 @@ print("done, manual bytes:", len(str(out_attrs.get("manual", ""))))
 - This chapter is designed for quickly learning MASFactory’s declarative paradigm, so it omits some implementation details of ChatDev.
   For complete reproductions, refer to: [ChatDev-Lite](https://github.com/BUPT-GAMMA/MASFactory/tree/main/applications/chatdev_lite) or [ChatDev](https://github.com/BUPT-GAMMA/MASFactory/tree/main/applications/chatdev).
 :::
-

docs/src/progressive/chatdev_imperative.md

@@ -17,6 +17,8 @@ Start from:
 
 `ENTRY → instructor → assistant → EXIT`
 
+To keep `user_demand` transparent, `ENTRY` also passes it directly to `assistant`.
+
 <ThemedDiagram
   light="/imgs/tutorial/chatdev-lite/prog-01-workflow-en-light.svg"
   dark="/imgs/tutorial/chatdev-lite/prog-01-workflow-en-dark.svg"
@@ -58,6 +60,7 @@ assistant = g.create_node(
 )
 
 g.edge_from_entry(instructor, {"user_demand": "user demand"})
+g.edge_from_entry(assistant, {"user_demand": "user demand"})
 g.create_edge(instructor, assistant, {"instructor_guidance": "Instructor guidance"})
 g.edge_to_exit(assistant, {"assistant_response": "Assistant response"})
 
@@ -72,7 +75,7 @@ print(out["assistant_response"])
 ## Step 2 — Multi-turn collaboration with Loop (edge messages)
 
 Wrap Step 1 into a loop to support multi-turn convergence.  
-To demonstrate horizontal passing, we keep using edge keys inside the loop and iterate via `assistant_response` ↔ `instructor_guidance`.
+To demonstrate horizontal passing, we keep using edge keys inside the loop and iterate via `assistant_response` ↔ `instructor_guidance`, while `CONTROLLER` keeps passing `user_demand` directly to `assistant`.
 
 <ThemedDiagram
   light="/imgs/tutorial/chatdev-lite/prog-04-loop-edge-en-light.svg"
@@ -125,6 +128,7 @@ instructor = dialog.create_node(
 )
 
 dialog.edge_from_controller(instructor, {"user_demand": "user demand", "assistant_response": "previous Assistant response"})
+dialog.edge_from_controller(assistant, {"user_demand": "user demand"})
 dialog.create_edge(instructor, assistant, {"instructor_guidance": "Instructor guidance"})
 dialog.edge_to_controller(assistant, {"assistant_response": "Assistant response"})
 
@@ -580,4 +584,3 @@ print("done, manual bytes:", len(str(out_attrs.get("manual", ""))))
 - This chapter is designed for quickly learning MASFactory’s imperative paradigm, so it omits some implementation details of ChatDev.
   For complete reproductions, refer to: [ChatDev-Lite](https://github.com/BUPT-GAMMA/MASFactory/tree/main/applications/chatdev_lite) or [ChatDev](https://github.com/BUPT-GAMMA/MASFactory/tree/main/applications/chatdev).
 :::
-