kb-skills/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-03-13

Pattern Overview

Overall: Multi-skill workflow orchestration with skill-based modular architecture

Key Characteristics:

• Skill-based modular design: Each skill is an independent module with its own SKILL.md specification
• Pipeline workflow pattern: Sequential processing stages orchestrated by kb-workflow
• Stateful session management: tmux-based persistent sessions for GSD-OpenClaw
• Platform abstraction: Unified interfaces for multiple content platforms (Bilibili, Zhihu, YouTube, etc.)

Layers

Skill Definition Layer:

• Purpose: Define skill capabilities, triggers, and execution steps
• Location: kb-*/SKILL.md, gsd-openclaw/skill/SKILL.md
• Contains: Markdown documents with YAML frontmatter and structured workflows
• Depends on: Nothing (declarative)
• Used by: AI agents that execute skills

Core Implementation Layer:

• Purpose: Implement actual functionality for each skill
• Location: kb-*/*.py, gsd-openclaw/src/gsd_openclaw/*.py
• Contains: Python modules with CLI entry points and core logic
• Depends on: External APIs, platform SDKs, AI providers
• Used by: Skill orchestration layer

Orchestration Layer:

• Purpose: Coordinate multiple skills in workflows
• Location: kb-workflow/kb_workflow.py
• Contains: Workflow coordination utilities, directory management, Git integration
• Depends on: All skill modules
• Used by: Main agent executing workflows

Session Management Layer:

• Purpose: Manage persistent tmux sessions for long-running operations
• Location: gsd-openclaw/src/gsd_openclaw/tmux_session.py
• Contains: TmuxSessionManager, session lifecycle management
• Depends on: libtmux, StateManager, WorkspaceManager
• Used by: GSD command orchestration

State Persistence Layer:

• Purpose: Provide crash-safe state checkpointing
• Location: gsd-openclaw/src/gsd_openclaw/state_manager.py
• Contains: StateManager, atomic save/load with backup rotation
• Depends on: File system only
• Used by: TmuxSessionManager, workspace management

Data Flow

Content Processing Pipeline:

1. URL Input → kb-link-parser extracts platform, type, and ID
2. Metadata Extraction → Platform-specific skill (kb-*-metadata) fetches metadata
3. Content Download → Platform-specific skill (kb-*-content) downloads content
4. Speech Recognition → kb-whisper/kb-funasr transcribes audio (if needed)
5. Deep Analysis → kb-deep-analyzer generates AI-powered analysis report
6. Archive → kb-workflow archives to Git-managed directory

GSD Session Flow:

1. /gsd:* command received
2. TmuxSessionManager.create_session() or resume_session()
3. State persisted via StateManager.save()
4. Command executed in tmux session
5. Output captured and formatted via FeishuResponseFormatter

State Management:

• State stored in ~/gsd-workspaces/{project}/.gsd/state.json
• Atomic writes via temp file + rename
• Automatic backup rotation (state.json → state.json.bak)

Key Abstractions

Skill:

• Purpose: Represents an independent capability unit
• Examples: kb-link-parser/link-parser.py, kb-deep-analyzer/deep_analyzer.py
• Pattern: CLI-based with JSON output, defined by SKILL.md specification

TmuxSession:

• Purpose: Represents a managed tmux session for project isolation
• Examples: gsd-openclaw/src/gsd_openclaw/tmux_session.py
• Pattern: Dataclass with session_id, project_name, tmux_session_name

Workspace:

• Purpose: Isolated directory structure per project
• Examples: gsd-openclaw/src/gsd_openclaw/workspace.py
• Pattern: Defined subdirectories (.gsd/, code/, io-logs/)

AnalysisResult:

• Purpose: Structured output from deep analysis
• Examples: kb-deep-analyzer/deep_analyzer.py
• Pattern: Dataclass with summary, main_topics, key_insights, tags

Entry Points

CLI Entry Points:

• Location: kb-*/*.py with if __name__ == '__main__': main()
• Triggers: Command-line invocation with argparse
• Responsibilities: Parse arguments, invoke core logic, output JSON

gsd-ocl CLI:

• Location: gsd-openclaw/src/gsd_openclaw/cli.py
• Triggers: gsd-ocl create|list|destroy|resume|cleanup
• Responsibilities: Session lifecycle management

Skill Trigger:

• Location: SKILL.md frontmatter with name and description
• Triggers: AI agent pattern matching on user messages
• Responsibilities: Define when and how to invoke the skill

Error Handling

Strategy: Fail-fast with structured JSON error output

Patterns:

• All CLI tools output JSON with success: true/false field
• Error responses include error and detail fields
• Deep analysis failure terminates entire workflow (per kb-workflow/SKILL.md)
• State manager uses backup fallback on corruption

Error Response Format:

{
  "success": false,
  "error": "Error description",
  "detail": "Additional context"
}

Cross-Cutting Concerns

Logging: Console output with [ModuleName] prefixes (e.g., [DeepAnalyzer], [AI Client])

Validation:

• Environment variable checks before workflow execution (kb-workflow/SKILL.md)
• Required field validation in StateManager.load()
• Platform/type validation in link parser

Authentication:

• Platform cookies via environment variables (BILIBILI_COOKIE, ZHIHU_COOKIE)
• AI API keys via environment variables (AI_API_KEY, HF_TOKEN)
• Git credentials via environment variables (KB_GIT_USER, KB_GIT_EMAIL)

Configuration:

• Environment variables loaded from ~/.kb_env
• Path configuration via environment variables (KB_BASE_PATH, KB_ARCHIVE_PATH, KB_GIT_ROOT)

---

Architecture analysis: 2026-03-13