Skip to content

babynata/groupflow-deerflow

BranchesTags

Repository files navigation

GroupFlow for DeerFlow 2.0

DeerFlow 的 group-level shared memory / project workspace 扩展层，用来让长周期多 Agent 工作可观察、可恢复、可复用。

中文 | English

项目概览

DeerFlow 2.0 已经具备 sub-agents、memory、sandbox 执行、skills、MCP/tool 集成等长任务 Agent 系统基础能力。但真实项目型任务通常不是单个 agent 一次性完成的，而是由 Research、Product、Architect、Reviewer 等多个 agent 协作推进。

GroupFlow 为这类 DeerFlow 工作提供一个外接的组级状态层，记录：

  • group 当前知道什么
  • 已经做过哪些决定
  • 哪些文件被读取或修改
  • 哪些产物已经生成
  • 任务暂停后应该从哪里恢复

GroupFlow 不替代 DeerFlow，也不替代 sub-agent 私有 context。它补充的是 group-level shared memory、file state ledger、decision log、timeline、MCP-style tools、DeerFlow adapter、JSON persistence 和 timeline replay。

Demo

启动本地 workspace 后，可以查看 Project / Group / Sub-agent 三层结构，以及 Group Memory、Agent Board、Artifacts、File State Ledger 和 Timeline。

GroupFlow workspace running at http://127.0.0.1:4173

当前 workspace 支持：

  • 查看 group memory summary
  • 查看 DeerFlow-style agent board
  • 过滤执行 timeline
  • 追踪 artifact 和 file state
  • 模拟 Run next step
  • 执行 Resume group
  • 执行 Compact memory
  • 执行 Refresh files

核心能力

  • Group Memory：保存 group 级 objective、constraints、findings、decisions 和 open questions。
  • File State Ledger：记录 DeerFlow 运行中读取、修改或产出的文件状态。
  • Execution Timeline：把 agent、tool、file、pause、resume 等事件串成可回放时间线。
  • MCP-style Tools：提供 get_group_context、append_finding、record_decision、update_file_state 等工具接口。
  • DeerFlow Adapter：把 DeerFlow host events 映射为 GroupFlow runtime 状态更新。
  • Python Sidecar：支持运行期 HTTP tool server，也支持导入 DeerFlow RunEventStore JSONL。
  • JSON Persistence and Replay：支持本地状态保存、checkpoint 和 timeline replay。
  • Local Workspace UI：提供静态本地工作台，用于工程评估和集成演示。

快速开始

环境要求

  • Node.js 18+
  • npm
  • Python 3.10+

GroupFlow 当前没有外部 npm package 依赖。

安装

git clone https://github.com/babynata/groupflow-deerflow.git
cd groupflow-deerflow

启动本地 workspace

npm run serve

默认地址：

http://127.0.0.1:4173

验证当前能力

npm run validate

使用方式

使用 Core Runtime

import { createGroupMemoryRuntime } from "./src/core/group-memory-runtime.js";

const groupFlow = createGroupMemoryRuntime();

groupFlow.createProject({ id: "project", name: "Project" });
groupFlow.createGroup({
  id: "group",
  projectId: "project",
  objective: "Run DeerFlow work with shared group state."
});

const context = groupFlow.getGroupContext("group", {
  forAgentId: "researcher"
});

使用 MCP-style Tools

import { createGroupFlowToolServer } from "./src/mcp/tool-server.js";

const tools = createGroupFlowToolServer(groupFlow);

tools.callTool("append_finding", {
  groupId: "group",
  finding: {
    agentId: "researcher",
    content: "GroupFlow stores shared findings outside private agent context."
  }
});

使用 DeerFlow Adapter

import { createDeerFlowAdapter } from "./src/adapters/deerflow-adapter.js";

const adapter = createDeerFlowAdapter(groupFlow);

adapter.handleEvent({
  type: "agent_started",
  groupId: "group",
  agentId: "researcher"
});

Adapter 支持的 host events：

  • task_created
  • agent_started
  • subagent_result
  • tool_called
  • file_read
  • file_written
  • run_paused
  • run_resumed

导入 DeerFlow RunEventStore JSONL

如果已有 DeerFlow 运行记录，可以用 Python sidecar 读取 RunEventStore JSONL，并生成 GroupFlow 状态文件：

PYTHONPATH=python python3 -m groupflow_deerflow ingest \
  --run .deer-flow/threads/{thread_id}/runs/{run_id}.jsonl \
  --out .groupflow

输出目录包含：

  • state.json
  • timeline.json
  • file-ledger.json
  • artifacts.json
  • summary.json

运行 HTTP tool sidecar

如果希望 DeerFlow 在运行中调用 GroupFlow，可以启动本地 HTTP tool server：

PYTHONPATH=python python3 -m groupflow_deerflow server \
  --state .groupflow/state.json \
  --port 8765

调用示例：

curl -X POST http://127.0.0.1:8765/tools/get_group_context \
  -H "Content-Type: application/json" \
  -d '{"groupId":"group","options":{"forAgentId":"researcher"}}'

Python client 示例：

from groupflow_deerflow.client import GroupFlowClient

groupflow = GroupFlowClient("http://127.0.0.1:8765")
context = groupflow.call_tool("get_group_context", {
    "groupId": "group",
    "options": {"forAgentId": "researcher"},
})

工作机制

DeerFlow run events / tool calls
        |
        v
DeerFlow Adapter or Python Sidecar
        |
        v
GroupFlow Core Runtime
        |
        +--> Group Memory
        +--> File State Ledger
        +--> Decision Log
        +--> Execution Timeline
        +--> Artifacts
        |
        v
Workspace UI / JSON Storage / Replay

推荐集成流程：

  1. DeerFlow 接收一个长周期项目型任务。
  2. DeerFlow planner 创建或选择一个 GroupFlow group。
  3. 每次 sub-agent 运行前，DeerFlow 调用 get_group_context 获取 group 级上下文。
  4. sub-agent 使用私有 context 和 group context 执行任务。
  5. agent 产出 finding、decision、file state 或 timeline event。
  6. GroupFlow 更新共享状态，并为后续恢复提供 compact summary。

项目结构

.
├── app.js                         # Local workspace UI logic
├── index.html                     # Local workspace entry
├── styles.css                     # Workspace styles
├── src/
│   ├── adapters/                  # DeerFlow event mapping
│   ├── core/                      # Group memory runtime
│   ├── fixtures/                  # Seed data and real DeerFlow fixtures
│   ├── mcp/                       # MCP-style tool server
│   ├── replay/                    # Timeline replay
│   └── storage/                   # JSON storage
├── python/groupflow_deerflow/     # Python sidecar, CLI, client, server
├── scripts/                       # Validation and local server scripts
└── docs/                          # Design, integration, security, readiness docs

验证方式

运行全量验证：

npm run validate

也可以单独验证：

npm run validate:workspace
npm run validate:lifecycle
npm run validate:mcp
npm run validate:adapter
npm run validate:deerflow-events
npm run validate:storage
npm run validate:replay
npm run validate:python

验证覆盖：

  • workspace state behavior
  • Core Runtime lifecycle
  • MCP-style tool lifecycle
  • DeerFlow adapter host event mapping
  • DeerFlow RunEventStore JSONL transform
  • JSON storage save/load
  • checkpoint creation
  • timeline replay
  • Python sidecar behavior

Roadmap

  • 补充公开截图和更完整的 workspace walkthrough。
  • 将 Python sidecar 的运行期接入示例扩展成 DeerFlow 项目集成指南。
  • 明确未来 official MCP transport 的边界。
  • 增加 schema migration 和更严格的 runtime validation。
  • 探索多 group 状态复用和项目级记忆沉淀。

当前限制

  • 当前适合本地工程评估和 adapter-level validation，不是 hosted multi-user service。
  • Runtime state 默认在内存中，除非显式通过 JSON storage 保存。
  • 没有并发写入控制。
  • 没有 schema migration layer。
  • MCP-style tool server 是 protocol-shaped，不声明 official MCP SDK transport compatibility。
  • DeerFlow adapter 验证的是事件映射边界，不是 live DeerFlow repository integration。
  • Workspace 是静态本地界面，不包含认证、分享或部署能力。

常见问题

npm run serve 后打不开页面

确认终端输出地址，默认是：

http://127.0.0.1:4173

如果端口被占用，可以指定其他端口：

PORT=4180 npm run serve

npm run validate 中 Python sidecar 校验失败

确认本机可以使用 python3，并且从项目根目录运行命令：

python3 --version
npm run validate:python

DeerFlow JSONL 导入后没有 file ledger

GroupFlow 只在 DeerFlow 记录中明确出现 tool call、artifact 或文件路径时写入 File State Ledger。它不会从 workspace 路径推断文件产物。

贡献方式

欢迎围绕 DeerFlow integration、MCP transport、state replay、workspace UX 和 production readiness 提交 issue 或 PR。

建议贡献前先阅读：

  • docs/deerflow-integration.md
  • docs/api.md
  • docs/known-limitations.md
  • docs/production-readiness.md
  • docs/security.md

License

This project is licensed under the terms in LICENSE.

English

GroupFlow is a group-level shared memory and project workspace extension layer for DeerFlow. It helps long-running multi-agent work become inspectable, resumable, and reusable.

中文 | English

Overview

DeerFlow 2.0 already provides the core primitives for long-running agent work: sub-agents, memory, sandboxed execution, skills, and MCP/tool integration. Real project-style work, however, is rarely completed by one agent in one session. It usually involves several agents working together, such as Research, Product, Architect, and Reviewer agents.

GroupFlow adds an external group-level state layer for this kind of DeerFlow work. It records:

  • what the group currently knows
  • which decisions have been made
  • which files were read or changed
  • which artifacts have been produced
  • where an interrupted run should resume

GroupFlow does not replace DeerFlow or sub-agent private context. It adds group-level shared memory, a file state ledger, a decision log, a timeline, MCP-style tools, a DeerFlow adapter, JSON persistence, and timeline replay.

Demo

After starting the local workspace, you can inspect the Project / Group / Sub-agent structure, Group Memory, Agent Board, Artifacts, File State Ledger, and Timeline.

GroupFlow workspace running at http://127.0.0.1:4173

The current workspace supports:

  • inspecting the group memory summary
  • viewing a DeerFlow-style agent board
  • filtering the execution timeline
  • tracking artifacts and file state
  • simulating Run next step
  • running Resume group
  • running Compact memory
  • running Refresh files

Features

  • Group Memory: stores group-level objective, constraints, findings, decisions, and open questions.
  • File State Ledger: tracks files read, changed, or produced during DeerFlow runs.
  • Execution Timeline: records agent, tool, file, pause, and resume events for replay.
  • MCP-style Tools: exposes tools such as get_group_context, append_finding, record_decision, and update_file_state.
  • DeerFlow Adapter: maps DeerFlow host events into GroupFlow runtime state updates.
  • Python Sidecar: supports both a runtime HTTP tool server and DeerFlow RunEventStore JSONL ingestion.
  • JSON Persistence and Replay: supports local state saves, checkpoints, and timeline replay.
  • Local Workspace UI: provides a static workspace for engineering evaluation and integration walkthroughs.

Quick Start

Requirements

  • Node.js 18+
  • npm
  • Python 3.10+

GroupFlow currently has no external npm package dependencies.

Installation

git clone https://github.com/babynata/groupflow-deerflow.git
cd groupflow-deerflow

Start the local workspace

npm run serve

Default URL:

http://127.0.0.1:4173

Validate current capabilities

npm run validate

Usage

Use the Core Runtime

import { createGroupMemoryRuntime } from "./src/core/group-memory-runtime.js";

const groupFlow = createGroupMemoryRuntime();

groupFlow.createProject({ id: "project", name: "Project" });
groupFlow.createGroup({
  id: "group",
  projectId: "project",
  objective: "Run DeerFlow work with shared group state."
});

const context = groupFlow.getGroupContext("group", {
  forAgentId: "researcher"
});

Use MCP-style Tools

import { createGroupFlowToolServer } from "./src/mcp/tool-server.js";

const tools = createGroupFlowToolServer(groupFlow);

tools.callTool("append_finding", {
  groupId: "group",
  finding: {
    agentId: "researcher",
    content: "GroupFlow stores shared findings outside private agent context."
  }
});

Use the DeerFlow Adapter

import { createDeerFlowAdapter } from "./src/adapters/deerflow-adapter.js";

const adapter = createDeerFlowAdapter(groupFlow);

adapter.handleEvent({
  type: "agent_started",
  groupId: "group",
  agentId: "researcher"
});

Supported host events:

  • task_created
  • agent_started
  • subagent_result
  • tool_called
  • file_read
  • file_written
  • run_paused
  • run_resumed

Ingest DeerFlow RunEventStore JSONL

If you already have DeerFlow run records, use the Python sidecar to ingest a RunEventStore JSONL file and write GroupFlow state files:

PYTHONPATH=python python3 -m groupflow_deerflow ingest \
  --run .deer-flow/threads/{thread_id}/runs/{run_id}.jsonl \
  --out .groupflow

The output directory contains:

  • state.json
  • timeline.json
  • file-ledger.json
  • artifacts.json
  • summary.json

Run the HTTP tool sidecar

If DeerFlow should call GroupFlow during execution, start the local HTTP tool server:

PYTHONPATH=python python3 -m groupflow_deerflow server \
  --state .groupflow/state.json \
  --port 8765

Tool call example:

curl -X POST http://127.0.0.1:8765/tools/get_group_context \
  -H "Content-Type: application/json" \
  -d '{"groupId":"group","options":{"forAgentId":"researcher"}}'

Python client example:

from groupflow_deerflow.client import GroupFlowClient

groupflow = GroupFlowClient("http://127.0.0.1:8765")
context = groupflow.call_tool("get_group_context", {
    "groupId": "group",
    "options": {"forAgentId": "researcher"},
})

How It Works

DeerFlow run events / tool calls
        |
        v
DeerFlow Adapter or Python Sidecar
        |
        v
GroupFlow Core Runtime
        |
        +--> Group Memory
        +--> File State Ledger
        +--> Decision Log
        +--> Execution Timeline
        +--> Artifacts
        |
        v
Workspace UI / JSON Storage / Replay

Recommended integration flow:

  1. DeerFlow receives a long-running project-style task.
  2. The DeerFlow planner creates or selects a GroupFlow group.
  3. Before each sub-agent run, DeerFlow calls get_group_context for group-level context.
  4. The sub-agent runs with private context plus group context.
  5. The agent writes findings, decisions, file state, or timeline events.
  6. GroupFlow updates shared state and provides a compact summary for later resume.

Project Structure

.
├── app.js                         # Local workspace UI logic
├── index.html                     # Local workspace entry
├── styles.css                     # Workspace styles
├── src/
│   ├── adapters/                  # DeerFlow event mapping
│   ├── core/                      # Group memory runtime
│   ├── fixtures/                  # Seed data and real DeerFlow fixtures
│   ├── mcp/                       # MCP-style tool server
│   ├── replay/                    # Timeline replay
│   └── storage/                   # JSON storage
├── python/groupflow_deerflow/     # Python sidecar, CLI, client, server
├── scripts/                       # Validation and local server scripts
└── docs/                          # Design, integration, security, readiness docs

Testing

Run the full validation suite:

npm run validate

Or validate individual layers:

npm run validate:workspace
npm run validate:lifecycle
npm run validate:mcp
npm run validate:adapter
npm run validate:deerflow-events
npm run validate:storage
npm run validate:replay
npm run validate:python

The validation suite covers:

  • workspace state behavior
  • Core Runtime lifecycle
  • MCP-style tool lifecycle
  • DeerFlow adapter host event mapping
  • DeerFlow RunEventStore JSONL transform
  • JSON storage save/load
  • checkpoint creation
  • timeline replay
  • Python sidecar behavior

Roadmap

  • Add public screenshots and a fuller workspace walkthrough.
  • Expand the Python sidecar examples into a DeerFlow project integration guide.
  • Clarify the future official MCP transport boundary.
  • Add schema migration and stricter runtime validation.
  • Explore multi-group state reuse and project-level memory.

Limitations

  • GroupFlow is suitable for local engineering evaluation and adapter-level validation, not as a hosted multi-user service.
  • Runtime state is in memory by default unless explicitly saved through JSON storage.
  • There is no concurrency control for simultaneous writers.
  • There is no schema migration layer.
  • The MCP-style tool server is protocol-shaped and does not claim official MCP SDK transport compatibility.
  • The DeerFlow adapter validates the event mapping boundary, not a live DeerFlow repository integration.
  • The workspace is a static local interface without authentication, sharing, or deployment features.

Troubleshooting

The workspace does not open after npm run serve

Check the URL printed in the terminal. The default is:

http://127.0.0.1:4173

If the port is already in use, set another port:

PORT=4180 npm run serve

Python sidecar validation fails during npm run validate

Confirm that python3 is available and run the command from the project root:

python3 --version
npm run validate:python

DeerFlow JSONL ingestion does not create file ledger entries

GroupFlow writes File State Ledger entries only when the DeerFlow records include explicit tool calls, artifacts, or file paths. It does not infer generated files from workspace paths.

Contributing

Contributions around DeerFlow integration, MCP transport, state replay, workspace UX, and production readiness are welcome.

Recommended reading before contributing:

  • docs/deerflow-integration.md
  • docs/api.md
  • docs/known-limitations.md
  • docs/production-readiness.md
  • docs/security.md

License

This project is licensed under the terms in LICENSE.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages