Spacedock: A Lightweight Framework for Converting Markdown Directories into AI Agent Workflows

Spacedock is an innovative open-source tool with the core concept of "Documents as Workflows". It can automatically convert Markdown file directories into structured AI agent workflows, achieving seamless integration of knowledge management and execution automation, and providing individuals and teams with a new AI-driven way of working. It does not require users to learn new workflow definition languages or write complex configurations; users only need to organize content according to natural document habits to generate executable workflows.

In modern work environments, a large number of knowledge documents in Markdown format (such as project plans, operation manuals, etc.) have been accumulated, but these static documents are disconnected from dynamic work execution, leading to low efficiency of manual operations, high risk of step omissions, and lagging knowledge updates. The rise of AI agents provides a possibility to solve this problem, and Spacedock is the realization of this vision—it allows AI not only to "read" documents but also to "understand" processes and "execute" operations.

Core Concepts

The core concept of Spacedock is "Documents as Workflows"—well-structured Markdown documents imply process structures (heading levels define phase steps, list items describe operations, code blocks contain executable commands, etc.).

Three-Stage Working Principle

1. Document Parsing and Structure Extraction: Scan the Markdown directory, identify hierarchical structures, process steps, executable code blocks, variable parameters, conditional branches, and dependencies, and map them to the workflow concept model.
2. Workflow Construction: Convert the parsed structure into an internal workflow representation that includes start/end nodes, sequential/parallel steps, conditional judgments, human nodes, tool integration points, etc., supporting sub-workflows, dynamic branches, and error handling.
3. Agent Execution: The AI agent executes steps according to the workflow, calls external tools, handles exceptions, requests human confirmation, records results, and dynamically adjusts subsequent steps based on feedback. It has understanding capabilities rather than running as a mechanical script.

To enable Spacedock to parse documents correctly, lightweight markup conventions are defined:

• Step Markers: Ordered lists are executed sequentially by default. Special markers such as [并行] (execute simultaneously), [条件:表达式] (execute when the condition is met), [循环] (repeat until exit condition is met).
• Executable Code: Code blocks are distinguished by language markers (e.g., bash for executing commands, python for passing to the interpreter, http for converting to requests, prompt for AI processing).
• Variable Definitions: {{变量名}} references variables, [输入:变量名] gets user input, [输出:变量名] marks step outputs.
• Human Nodes: [确认] requires human confirmation, [选择:选项列表] requires selection, [输入] requires manual input of information.

Spacedock is suitable for various scenarios:

1. Operation and Maintenance Manuals: Convert process documents such as deployment updates and troubleshooting into executable workflows. The agent executes automatically and pauses when human decision-making is needed.
2. Project Management Processes: Convert project management process documents into automated workflows, integrate APIs to automatically create tasks, update kanban boards, and send notifications.
3. Content Publishing Pipelines: Define complete publishing processes. The agent automatically performs format checks, image optimization, SEO analysis, and publishes to various platforms automatically after review.
4. Data Analysis Reports: Document and automate data extraction, cleaning, analysis, and visualization steps to generate complete reports.

Key technical choices of Spacedock:

• File System First: Workflows are defined as ordinary Markdown files, which can be maintained with text editors and version-controlled with Git, lowering the adoption threshold.
• Zero-Configuration Startup: No complex configuration, database, or service deployment is required. Just point to a Markdown directory to start working, suitable for individuals and small teams.
• Extensible Plugin System: Supports adding tool support, integrating third-party services, customizing parsing rules, and extending agent capabilities. Plugins can be written in multiple languages.
• Local First and Privacy Protection: Runs locally by default, processes data on the user's machine to protect sensitive information, and supports optional synchronization mechanisms.

Current Limitations

1. Document Structure Dependence: The effect depends on the quality of the Markdown document structure; messy documents may not be parsed correctly (a quality check tool is provided).
2. Complex Logic Expression: Expressing complex business logic with document markers is clumsy; embedding code snippets is supported for supplementation.
3. Error Recovery Capability: The execution error recovery strategy is basic.

Future Directions

Plans to add more intelligent error handling and recovery mechanisms.

Spacedock represents a new paradigm of document-centric AI-driven workflows, seamlessly integrating knowledge management and execution automation, and turning documents into executable living systems. For individuals, it improves efficiency and allows focus on creative work; for teams, it precipitates knowledge and ensures consistent quality. It lowers the threshold for AI applications, allowing more people to enjoy AI efficiency improvements without becoming AI experts. As AI agent capabilities improve, such tools will become more important.