docs: map existing codebase

2026-03-13 14:55:43 +08:00
parent 1d7957aab4
commit a8669ec0a3
5 changed files with 790 additions and 0 deletions
@@ -0,0 +1,154 @@
+# 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:**
+```json
+{
+  "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*