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

Codebase Structure

Analysis Date: 2026-03-13

Directory Layout

/home/starmen1265/work/kb-skills/
├── .claude/                    # Claude Code configuration
├── .gitea/                     # Gitea CI/CD workflows
├── .planning/                  # Planning documents
│   ├── codebase/               # Codebase analysis docs
│   └── research/               # Research documents
├── gsd/                        # GSD (Get Shit Done) framework - Node.js
│   ├── agents/                 # Agent definitions
│   ├── bin/                    # Installation scripts
│   ├── commands/               # Slash command definitions
│   ├── docs/                   # Documentation
│   ├── get-shit-done/          # Core GSD implementation
│   │   ├── bin/                # GSD tools
│   │   ├── templates/          # Document templates
│   │   ├── workflows/          # Workflow definitions
│   │   └── references/         # Reference documentation
│   ├── hooks/                  # Git hooks
│   └── scripts/                # Build/test scripts
├── gsd-openclaw/               # GSD-OpenClaw bridge - Python
│   ├── src/gsd_openclaw/       # Source package
│   │   └── prompts/            # Prompt templates
│   ├── tests/                  # Test files
│   ├── skill/                  # Skill definition
│   └── .planning/              # Phase planning docs
├── kb-bilibili-content/        # Bilibili content download skill
├── kb-bilibili-metadata/       # Bilibili metadata extraction skill
├── kb-deep-analyzer/           # AI deep analysis skill
├── kb-funasr/                  # FunASR speech recognition skill
├── kb-link-parser/             # Multi-platform URL parser skill
├── kb-ocr-processor/           # OCR text extraction skill
├── kb-whisper/                 # Whisper speech recognition skill
├── kb-whisper-diarization/     # Whisper + speaker diarization skill
├── kb-workflow/                # Knowledge base workflow orchestrator
├── kb-zhihu-content/           # Zhihu content download skill
├── kb-zhihu-metadata/          # Zhihu metadata extraction skill
├── todo-manager/               # Todo management skill
└── README.md                   # Project overview

Directory Purposes

kb- Skill Directories:*

• Purpose: Independent skill modules for content processing
• Contains: Python implementation, SKILL.md specification, optional .env.example
• Key files: *.py (implementation), SKILL.md (specification)

gsd/ Directory:

• Purpose: Node.js-based GSD framework for project management
• Contains: Commands, agents, templates, workflows
• Key files: package.json, commands/gsd/*.md, get-shit-done/bin/gsd-tools.cjs

gsd-openclaw/ Directory:

• Purpose: Python bridge between GSD and OpenClaw chat interface
• Contains: Session management, state persistence, response formatting
• Key files: src/gsd_openclaw/cli.py, src/gsd_openclaw/tmux_session.py

gsd-openclaw/src/gsd_openclaw/ Directory:

• Purpose: Core Python package for GSD-OpenClaw
• Contains: CLI, session management, workspace management, state persistence
• Key files: cli.py, tmux_session.py, workspace.py, state_manager.py

gsd-openclaw/skill/ Directory:

• Purpose: Skill definition for GSD-OpenClaw
• Contains: SKILL.md that defines how the skill triggers and works

Key File Locations

Entry Points:

• kb-workflow/kb_workflow.py: Knowledge base workflow orchestrator CLI
• kb-deep-analyzer/deep_analyzer.py: AI deep analysis CLI
• kb-link-parser/link-parser.py: URL parsing CLI
• gsd-openclaw/src/gsd_openclaw/cli.py: GSD-OpenClaw session management CLI

Configuration:

• ~/.kb_env: Environment variables for knowledge base (loaded by kb-workflow)
• gsd-openclaw/pyproject.toml: Python package configuration
• gsd/package.json: Node.js package configuration

Core Logic:

• gsd-openclaw/src/gsd_openclaw/tmux_session.py: Tmux session lifecycle
• gsd-openclaw/src/gsd_openclaw/state_manager.py: State persistence with backup
• gsd-openclaw/src/gsd_openclaw/workspace.py: Project workspace management
• kb-deep-analyzer/ai_client.py: Multi-provider AI client

Testing:

• gsd-openclaw/tests/test_*.py: pytest test files

Naming Conventions

Skill Directories:

• Pattern: kb-{platform}-{function} or kb-{function}
• Examples: kb-bilibili-metadata, kb-deep-analyzer, kb-whisper

Python Files:

• Pattern: {platform}_{function}.py or {function}.py
• Examples: bilibili_metadata.py, deep_analyzer.py, link_parser.py
• Note: Some use hyphens in filename (e.g., link-parser.py)

Output Files:

• Pattern: {platform}_{id}.{type}.json
• Examples: bilibili_BVxxx.meta.json, bilibili_BVxxx.link.json

Skill Specifications:

• Pattern: SKILL.md in each skill directory
• Format: YAML frontmatter + Markdown body

Where to Add New Code

New Content Platform Skill:

• Create directory: kb-{platform}-{function}/
• Add implementation: kb-{platform}-{function}/{platform}_{function}.py
• Add specification: kb-{platform}-{function}/SKILL.md
• Update kb-link-parser/link-parser.py to recognize platform URLs
• Update kb-workflow/SKILL.md to include new skill in workflow

New Processing Tool Skill:

• Create directory: kb-{function}/
• Add implementation: kb-{function}/{function}.py
• Add specification: kb-{function}/SKILL.md
• Integrate with kb-workflow/SKILL.md if part of main pipeline

New GSD Command:

• Create command definition: gsd/commands/gsd/{command-name}.md
• Add agent if needed: gsd/agents/gsd-{agent-name}.md
• Update CLI in gsd-openclaw/src/gsd_openclaw/cli.py if needed

New Session Management Feature:

• Primary code: gsd-openclaw/src/gsd_openclaw/tmux_session.py
• Tests: gsd-openclaw/tests/test_tmux_session.py
• State handling: gsd-openclaw/src/gsd_openclaw/state_manager.py

New AI Provider:

• Add method to kb-deep-analyzer/ai_client.py SimpleAIClient class
• Pattern: _call_{provider}(self, prompt, max_tokens, api_key, model, base_url)
• Update kb-deep-analyzer/deep_analyzer.py generate() method

Special Directories

gsd-openclaw/.venv:

• Purpose: Python virtual environment
• Generated: Yes (uv/pip)
• Committed: No

gsd-openclaw/.pytest_cache:

• Purpose: pytest cache
• Generated: Yes
• Committed: No

gsd/.git:

• Purpose: Separate git repository for GSD submodule
• Contains: Full GSD framework history
• Committed: As submodule reference

pycache/:

• Purpose: Python bytecode cache
• Generated: Yes
• Committed: No

Workspace Directory (~/gsd-workspaces/):

• Purpose: Project workspaces for GSD sessions
• Structure: {project}/.gsd/state.json, {project}/code/, {project}/io-logs/
• Generated: At runtime
• Committed: No (runtime data)

Knowledge Base Directory (~/work/knowledge-base/):

• Purpose: Working directory for content processing
• Structure: pending/, metadata/, content/downloads/, analyzed/
• Generated: At runtime via kb_workflow.py ensure_directories()
• Committed: No (runtime data)

Archive Directory (~/work/zq/30.资源/AI分析/):

• Purpose: Final archive location for analysis reports
• Structure: YYYY-MM-DD/{platform}_{id}.md
• Generated: At runtime
• Committed: Yes (via Git in archive workflow)

---

Structure analysis: 2026-03-13