187 lines
7.4 KiB
Markdown
187 lines
7.4 KiB
Markdown
# 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*
|