# 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*