mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Merge feature/framework-improvements into integration
## Merged Changes ### From framework-improvements: - ✅ framework_docs → knowledge_base rename (complete) - ✅ Installation failures fix (docstring + dependencies) - ✅ MCP URL fix (agiletec-inc) - ✅ README translation workflow - ✅ CLAUDE.md with UV rules ### From integration (preserved): - ✅ PM Agent improvements (dynamic token calculation) - ✅ PM modules relocation - ✅ Docs cleanup ## Conflict Resolution Strategy **Installer & Components**: Adopted framework-improvements - Reason: knowledge_base rename + installation fixes are critical **PM Agent**: Preserved integration version - Reason: Latest improvements (dynamic token, modular architecture) ## Result Integration branch now contains: - All installation fixes from PR #447 - Latest PM Agent improvements - Unified MCP gateway (airis-mcp-gateway) - Complete knowledge_base migration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
96
.github/workflows/translation-sync.yml
vendored
Normal file
96
.github/workflows/translation-sync.yml
vendored
Normal file
@@ -0,0 +1,96 @@
|
||||
name: Auto-translate README
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master, main]
|
||||
paths:
|
||||
- 'README.md'
|
||||
pull_request:
|
||||
paths:
|
||||
- 'README.md'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
translate:
|
||||
name: Translate README to Multiple Languages
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Translate README to Chinese
|
||||
uses: 3ru/gpt-translate@v1.1.11
|
||||
with:
|
||||
apikey: ${{ secrets.OPENAI_API_KEY }}
|
||||
inputFiles: 'README.md'
|
||||
outputFiles: 'README-zh.md'
|
||||
targetLanguage: 'Simplified Chinese'
|
||||
|
||||
- name: Translate README to Japanese
|
||||
uses: 3ru/gpt-translate@v1.1.11
|
||||
with:
|
||||
apikey: ${{ secrets.OPENAI_API_KEY }}
|
||||
inputFiles: 'README.md'
|
||||
outputFiles: 'README-ja.md'
|
||||
targetLanguage: 'Japanese'
|
||||
|
||||
- name: Check for changes
|
||||
id: check_changes
|
||||
run: |
|
||||
if git diff --quiet HEAD -- README-zh.md README-ja.md; then
|
||||
echo "No translation changes detected"
|
||||
echo "has_changes=false" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "Translation changes detected"
|
||||
echo "has_changes=true" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
|
||||
- name: Commit translations
|
||||
if: steps.check_changes.outputs.has_changes == 'true'
|
||||
run: |
|
||||
git config --local user.email "github-actions[bot]@users.noreply.github.com"
|
||||
git config --local user.name "github-actions[bot]"
|
||||
git add README-zh.md README-ja.md
|
||||
git commit -m "chore: auto-translate README to ZH/JA
|
||||
|
||||
🤖 Generated with [GPT-Translate](https://github.com/3ru/gpt-translate)
|
||||
|
||||
Co-Authored-By: GitHub Actions <noreply@github.com>"
|
||||
|
||||
- name: Push changes
|
||||
if: steps.check_changes.outputs.has_changes == 'true' && github.event_name == 'push'
|
||||
uses: ad-m/github-push-action@master
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
branch: ${{ github.ref }}
|
||||
|
||||
- name: Create Pull Request
|
||||
if: steps.check_changes.outputs.has_changes == 'true' && github.event_name == 'pull_request'
|
||||
uses: peter-evans/create-pull-request@v6
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
commit-message: "chore: auto-translate README to ZH/JA"
|
||||
title: "🌐 Auto-translate README updates"
|
||||
body: |
|
||||
## 🤖 Automated Translation Update
|
||||
|
||||
This PR contains automated translations of README.md updates.
|
||||
|
||||
**Changes:**
|
||||
- ✅ README-zh.md (Simplified Chinese)
|
||||
- ✅ README-ja.md (Japanese)
|
||||
|
||||
**Translation powered by:**
|
||||
- [GPT-Translate](https://github.com/3ru/gpt-translate)
|
||||
- OpenAI GPT-4
|
||||
|
||||
Please review the translations for accuracy before merging.
|
||||
branch: chore/auto-translate-readme
|
||||
delete-branch: true
|
||||
134
CLAUDE.md
Normal file
134
CLAUDE.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Project-specific instructions for Claude Code when working with SuperClaude Framework.
|
||||
|
||||
## 🐍 Python Environment Rules
|
||||
|
||||
**CRITICAL**: This project uses **UV** for all Python operations.
|
||||
|
||||
### Required Commands
|
||||
|
||||
```bash
|
||||
# ❌ WRONG - Never use these
|
||||
python -m pytest
|
||||
pip install package
|
||||
python script.py
|
||||
|
||||
# ✅ CORRECT - Always use UV
|
||||
uv run pytest
|
||||
uv pip install package
|
||||
uv run python script.py
|
||||
```
|
||||
|
||||
### Why UV?
|
||||
|
||||
- **Fast**: 10-100x faster than pip
|
||||
- **Reliable**: Lock file ensures reproducibility
|
||||
- **Clean**: No system Python pollution
|
||||
- **Standard**: Project convention for consistency
|
||||
|
||||
### Common Operations
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
uv run pytest tests/ -v
|
||||
|
||||
# Install dependencies
|
||||
uv pip install -r requirements.txt
|
||||
|
||||
# Run specific script
|
||||
uv run python scripts/analyze_workflow_metrics.py
|
||||
|
||||
# Create virtual environment (if needed)
|
||||
uv venv
|
||||
```
|
||||
|
||||
### Integration with Docker
|
||||
|
||||
When using Docker for development:
|
||||
```bash
|
||||
# Inside Docker container
|
||||
docker compose exec workspace uv run pytest
|
||||
```
|
||||
|
||||
## 📂 Project Structure
|
||||
|
||||
```
|
||||
SuperClaude_Framework/
|
||||
├── superclaude/ # Framework source
|
||||
│ ├── commands/ # Slash commands
|
||||
│ ├── agents/ # Agent personas
|
||||
│ ├── modes/ # Behavior modes
|
||||
│ ├── framework/ # Core principles/rules/flags
|
||||
│ ├── business/ # Business analysis patterns
|
||||
│ └── research/ # Research configurations
|
||||
├── setup/ # Installation system
|
||||
│ ├── components/ # Installable components
|
||||
│ │ ├── knowledge_base.py # Framework knowledge
|
||||
│ │ ├── behavior_modes.py # Mode definitions
|
||||
│ │ ├── agent_personas.py # Agent definitions
|
||||
│ │ ├── slash_commands.py # Command registration
|
||||
│ │ └── mcp_integration.py # External tool integration
|
||||
│ └── core/ # Installation logic
|
||||
└── tests/ # Test suite
|
||||
```
|
||||
|
||||
## 🔧 Development Workflow
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
uv run pytest
|
||||
|
||||
# Specific test file
|
||||
uv run pytest tests/test_cli_smoke.py -v
|
||||
|
||||
# With coverage
|
||||
uv run pytest --cov=superclaude --cov-report=html
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Linting (if configured)
|
||||
uv run ruff check .
|
||||
|
||||
# Type checking (if configured)
|
||||
uv run mypy superclaude/
|
||||
|
||||
# Formatting (if configured)
|
||||
uv run ruff format .
|
||||
```
|
||||
|
||||
## 📦 Component Architecture
|
||||
|
||||
SuperClaude uses **Responsibility-Driven Design**. Each component has a single, clear responsibility:
|
||||
|
||||
- **knowledge_base**: Framework knowledge initialization
|
||||
- **behavior_modes**: Execution mode definitions
|
||||
- **agent_personas**: AI agent personality definitions
|
||||
- **slash_commands**: CLI command registration
|
||||
- **mcp_integration**: External tool integration
|
||||
|
||||
## 🚀 Contributing
|
||||
|
||||
When making changes:
|
||||
|
||||
1. Create feature branch: `git checkout -b feature/your-feature`
|
||||
2. Make changes with tests: `uv run pytest`
|
||||
3. Commit with conventional commits: `git commit -m "feat: description"`
|
||||
4. Push and create PR: Small, reviewable PRs preferred
|
||||
|
||||
## 📝 Documentation
|
||||
|
||||
- Root documents: `PLANNING.md`, `KNOWLEDGE.md`, `TASK.md`
|
||||
- User guides: `docs/user-guide/`
|
||||
- Development docs: `docs/Development/`
|
||||
- Research reports: `docs/research/`
|
||||
|
||||
## 🔗 Related
|
||||
|
||||
- Global rules: `~/.claude/CLAUDE.md` (workspace-level)
|
||||
- MCP servers: Unified gateway via `airis-mcp-gateway`
|
||||
- Framework docs: Auto-installed to `~/.claude/superclaude/`
|
||||
34
README-ja.md
34
README-ja.md
@@ -261,6 +261,38 @@ pip install --break-system-packages SuperClaude
|
||||
|
||||
<div align="center">
|
||||
|
||||
## 🔬 **深層リサーチ機能**
|
||||
|
||||
SuperClaude v4.2は、自律的、適応的、知的なWeb調査を可能にする包括的な深層リサーチ機能を導入しました。
|
||||
|
||||
### 🎯 **適応型計画**
|
||||
3つのインテリジェント戦略：**計画優先**（明確なクエリの直接実行）、**意図計画**（曖昧なリクエストの明確化）、**統合**（協調的な計画改善、デフォルト）
|
||||
|
||||
### 🔄 **マルチホップ推論**
|
||||
最大5回の反復検索：エンティティ拡張、概念深化、時系列進行、因果チェーン
|
||||
|
||||
### 📊 **品質スコアリング**
|
||||
信頼性ベースの検証：情報源の信頼性評価(0.0-1.0)、カバレッジ完全性追跡、統合一貫性評価
|
||||
|
||||
### 🧠 **ケースベース学習**
|
||||
クロスセッション・インテリジェンス：パターン認識と再利用、戦略最適化、成功したクエリ保存
|
||||
|
||||
### **リサーチコマンド使用法**
|
||||
|
||||
```bash
|
||||
/sc:research "AI最新動向 2024"
|
||||
/sc:research "量子コンピューティング" --depth exhaustive
|
||||
```
|
||||
|
||||
### **統合ツール・オーケストレーション**
|
||||
複数ツールのインテリジェント調整：**Tavily MCP**（Web検索）、**Playwright MCP**（コンテンツ抽出）、**Sequential MCP**（推論合成）、**Serena MCP**（メモリ永続化）、**Context7 MCP**（技術ドキュメント）
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## 📚 **ドキュメント**
|
||||
|
||||
### **🇯🇵 SuperClaude完全日本語ガイド**
|
||||
@@ -317,7 +349,7 @@ pip install --break-system-packages SuperClaude
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
- ✨ [**ベストプラクティス**](docs/reference/quick-start-practices.md)
|
||||
- ✨ [**ベストプラクティス**](docs/getting-started/quick-start.md)
|
||||
*プロのコツとパターン*
|
||||
|
||||
- 📓 [**サンプル集**](docs/reference/examples-cookbook.md)
|
||||
|
||||
34
README-zh.md
34
README-zh.md
@@ -261,6 +261,38 @@ pip install --break-system-packages SuperClaude
|
||||
|
||||
<div align="center">
|
||||
|
||||
## 🔬 **深度研究能力**
|
||||
|
||||
SuperClaude v4.2引入了全面的深度研究能力，实现自主、自适应和智能的网络研究。
|
||||
|
||||
### 🎯 **自适应规划**
|
||||
三种智能策略：**规划优先**（直接执行）、**意图规划**（澄清模糊请求）、**统一规划**（协作细化，默认）
|
||||
|
||||
### 🔄 **多跳推理**
|
||||
最多5次迭代搜索：实体扩展、概念深化、时序进展、因果链
|
||||
|
||||
### 📊 **质量评分**
|
||||
基于置信度的验证：来源可信度评估(0.0-1.0)、覆盖完整性跟踪、综合连贯性评估
|
||||
|
||||
### 🧠 **案例学习**
|
||||
跨会话智能：模式识别和重用、策略优化、成功查询保存
|
||||
|
||||
### **研究命令使用**
|
||||
|
||||
```bash
|
||||
/sc:research "AI最新发展 2024"
|
||||
/sc:research "量子计算突破" --depth exhaustive
|
||||
```
|
||||
|
||||
### **集成工具编排**
|
||||
智能协调多个工具：**Tavily MCP**（网页搜索）、**Playwright MCP**（内容提取）、**Sequential MCP**（推理合成）、**Serena MCP**（记忆持久化）、**Context7 MCP**（技术文档）
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## 📚 **Documentation**
|
||||
|
||||
### **Complete Guide to SuperClaude**
|
||||
@@ -317,7 +349,7 @@ pip install --break-system-packages SuperClaude
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
- ✨ [**最佳实践**](docs/reference/quick-start-practices.md)
|
||||
- ✨ [**最佳实践**](docs/getting-started/quick-start.md)
|
||||
*专业技巧和模式*
|
||||
|
||||
- 📓 [**示例手册**](docs/reference/examples-cookbook.md)
|
||||
|
||||
183
docs/Development/translation-workflow.md
Normal file
183
docs/Development/translation-workflow.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# README Auto-Translation Workflow
|
||||
|
||||
## 概要
|
||||
|
||||
SuperClaudeは **GPT-Translate** を使用して、READMEの自動翻訳を実現しています。
|
||||
|
||||
## 🎯 仕組み
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[README.md更新] --> B[GitHub Actions起動]
|
||||
B --> C[GPT-4で翻訳]
|
||||
C --> D[README-zh.md]
|
||||
C --> E[README-ja.md]
|
||||
D --> F[自動コミット]
|
||||
E --> F
|
||||
F --> G[PR作成 or Push]
|
||||
```
|
||||
|
||||
## 🔧 セットアップ
|
||||
|
||||
### 1. OpenAI APIキーの設定
|
||||
|
||||
GitHub リポジトリの Settings → Secrets → Actions で以下を追加:
|
||||
|
||||
```
|
||||
Name: OPENAI_API_KEY
|
||||
Value: sk-proj-xxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
### 2. ワークフローの動作
|
||||
|
||||
**自動起動トリガー:**
|
||||
- `README.md` が更新されたとき (master/mainブランチ)
|
||||
- Pull Requestで `README.md` が変更されたとき
|
||||
- 手動実行 (workflow_dispatch)
|
||||
|
||||
**動作:**
|
||||
1. README.md を GPT-4 で翻訳
|
||||
2. README-zh.md (簡体字中国語) を生成
|
||||
3. README-ja.md (日本語) を生成
|
||||
4. 変更があれば自動コミット
|
||||
5. masterブランチなら直接Push、PRなら新規PR作成
|
||||
|
||||
## 📊 コスト見積もり
|
||||
|
||||
| ファイルサイズ | GPT-4 Token数 | 推定コスト |
|
||||
|:-------------:|:-------------:|:----------:|
|
||||
| 5KB README | ~3,000 tokens | ~$0.03 |
|
||||
| 10KB README | ~6,000 tokens | ~$0.06 |
|
||||
| 20KB README | ~12,000 tokens| ~$0.12 |
|
||||
|
||||
**月間コスト見積もり:**
|
||||
- README更新頻度: 月10回
|
||||
- 1回あたり: $0.06 (2言語翻訳)
|
||||
- **月額: 約$0.60 (¥90)**
|
||||
|
||||
## 🛡️ セキュリティ
|
||||
|
||||
**APIキー保護:**
|
||||
- GitHub Secrets で暗号化保存
|
||||
- ワークフローログには表示されない
|
||||
- Pull Requestからはforkでアクセス不可
|
||||
|
||||
**権限管理:**
|
||||
```yaml
|
||||
permissions:
|
||||
contents: write # 翻訳ファイルのコミット用
|
||||
pull-requests: write # PR作成用
|
||||
```
|
||||
|
||||
## 🔄 使用方法
|
||||
|
||||
### 自動翻訳 (推奨)
|
||||
|
||||
README.mdを更新してコミット・プッシュするだけ:
|
||||
|
||||
```bash
|
||||
# README.md を編集
|
||||
vim README.md
|
||||
|
||||
# コミット
|
||||
git add README.md
|
||||
git commit -m "docs: update README"
|
||||
git push origin main
|
||||
|
||||
# → GitHub Actionsが自動的に翻訳を実行
|
||||
```
|
||||
|
||||
### 手動実行
|
||||
|
||||
GitHub UI から:
|
||||
1. Actions タブを開く
|
||||
2. "Auto-translate README" を選択
|
||||
3. "Run workflow" をクリック
|
||||
|
||||
### ローカルテスト
|
||||
|
||||
翻訳品質を事前確認する場合:
|
||||
|
||||
```bash
|
||||
# GPT-Translateをローカルで実行
|
||||
npm install -g gpt-translate
|
||||
export OPENAI_API_KEY="sk-proj-xxxxx"
|
||||
|
||||
gpt-translate --input README.md --output README-zh.md --lang "Simplified Chinese"
|
||||
gpt-translate --input README.md --output README-ja.md --lang "Japanese"
|
||||
```
|
||||
|
||||
## 📝 翻訳品質チェック
|
||||
|
||||
**自動翻訳後の確認ポイント:**
|
||||
|
||||
1. **技術用語の正確性**
|
||||
- フレームワーク名、コマンド名が正しいか
|
||||
- コードブロックが保持されているか
|
||||
|
||||
2. **マークダウン構造**
|
||||
- 見出しレベルが一致しているか
|
||||
- リンクが正しく変換されているか
|
||||
|
||||
3. **ニュアンス**
|
||||
- 文脈に合った翻訳か
|
||||
- 自然な表現か
|
||||
|
||||
**修正が必要な場合:**
|
||||
- 自動翻訳後に手動で微調整
|
||||
- 次回の翻訳時にその修正が維持されるよう考慮
|
||||
|
||||
## 🚫 トラブルシューティング
|
||||
|
||||
### エラー: "OPENAI_API_KEY not found"
|
||||
|
||||
**原因:** GitHub Secretsが設定されていない
|
||||
|
||||
**解決策:**
|
||||
```bash
|
||||
# リポジトリ設定を確認
|
||||
Settings → Secrets and variables → Actions → New repository secret
|
||||
```
|
||||
|
||||
### エラー: "Translation failed"
|
||||
|
||||
**原因:** OpenAI API レート制限
|
||||
|
||||
**解決策:**
|
||||
- 数分待ってから再実行
|
||||
- API使用量を確認: https://platform.openai.com/usage
|
||||
|
||||
### 翻訳品質が低い
|
||||
|
||||
**原因:** プロンプトが最適化されていない
|
||||
|
||||
**改善策:**
|
||||
```yaml
|
||||
# .github/workflows/translation-sync.yml
|
||||
with:
|
||||
apikey: ${{ secrets.OPENAI_API_KEY }}
|
||||
inputFiles: 'README.md'
|
||||
outputFiles: 'README-zh.md'
|
||||
targetLanguage: 'Simplified Chinese'
|
||||
prompt: 'Translate this technical documentation accurately, preserving all code blocks and technical terms.'
|
||||
```
|
||||
|
||||
## 🔗 関連リンク
|
||||
|
||||
- [GPT-Translate GitHub](https://github.com/3ru/gpt-translate)
|
||||
- [OpenAI API Documentation](https://platform.openai.com/docs)
|
||||
- [GitHub Actions Documentation](https://docs.github.com/actions)
|
||||
|
||||
## 📊 翻訳統計
|
||||
|
||||
現在の翻訳実績は GitHub Actions の Workflows タブから確認できます:
|
||||
|
||||
```
|
||||
Repository → Actions → Auto-translate README → 実行履歴
|
||||
```
|
||||
|
||||
**確認できる情報:**
|
||||
- 翻訳実行回数
|
||||
- 成功/失敗率
|
||||
- 実行時間
|
||||
- 翻訳されたファイルサイズ
|
||||
@@ -138,7 +138,7 @@ def get_components_to_install(
|
||||
# Explicit components specified
|
||||
if args.components:
|
||||
if "all" in args.components:
|
||||
components = ["framework_docs", "commands", "agents", "modes", "mcp"]
|
||||
components = ["knowledge_base", "commands", "agents", "modes", "mcp"]
|
||||
else:
|
||||
components = args.components
|
||||
|
||||
@@ -302,7 +302,7 @@ def select_framework_components(
|
||||
|
||||
try:
|
||||
# Framework components (excluding MCP-related ones)
|
||||
framework_components = ["framework_docs", "modes", "commands", "agents"]
|
||||
framework_components = ["knowledge_base", "modes", "commands", "agents"]
|
||||
|
||||
# Create component menu
|
||||
component_options = []
|
||||
@@ -334,9 +334,9 @@ def select_framework_components(
|
||||
selections = menu.display()
|
||||
|
||||
if not selections:
|
||||
# Default to framework_docs if nothing selected
|
||||
logger.info("No components selected, defaulting to framework_docs")
|
||||
selected_components = ["framework_docs"]
|
||||
# Default to knowledge_base if nothing selected
|
||||
logger.info("No components selected, defaulting to knowledge_base")
|
||||
selected_components = ["knowledge_base"]
|
||||
else:
|
||||
selected_components = []
|
||||
all_components = framework_components
|
||||
@@ -354,7 +354,7 @@ def select_framework_components(
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error in framework component selection: {e}")
|
||||
return ["framework_docs"] # Fallback to framework_docs
|
||||
return ["knowledge_base"] # Fallback to knowledge_base
|
||||
|
||||
|
||||
def interactive_component_selection(
|
||||
|
||||
@@ -1,15 +1,24 @@
|
||||
"""Component implementations for SuperClaude installation system"""
|
||||
"""
|
||||
Component Directory
|
||||
|
||||
from .framework_docs import FrameworkDocsComponent
|
||||
from .commands import CommandsComponent
|
||||
from .mcp import MCPComponent
|
||||
from .agents import AgentsComponent
|
||||
from .modes import ModesComponent
|
||||
Each module defines an installable responsibility unit:
|
||||
- knowledge_base: Framework knowledge initialization
|
||||
- behavior_modes: Execution mode definitions
|
||||
- agent_personas: AI agent personality definitions
|
||||
- slash_commands: CLI command registration
|
||||
- mcp_integration: External tool integration via MCP
|
||||
"""
|
||||
|
||||
from .knowledge_base import KnowledgeBaseComponent
|
||||
from .behavior_modes import BehaviorModesComponent
|
||||
from .agent_personas import AgentPersonasComponent
|
||||
from .slash_commands import SlashCommandsComponent
|
||||
from .mcp_integration import MCPIntegrationComponent
|
||||
|
||||
__all__ = [
|
||||
"FrameworkDocsComponent",
|
||||
"CommandsComponent",
|
||||
"MCPComponent",
|
||||
"AgentsComponent",
|
||||
"ModesComponent",
|
||||
"KnowledgeBaseComponent",
|
||||
"BehaviorModesComponent",
|
||||
"AgentPersonasComponent",
|
||||
"SlashCommandsComponent",
|
||||
"MCPIntegrationComponent",
|
||||
]
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
"""
|
||||
Agents component for SuperClaude specialized AI agents installation
|
||||
Agent Personas Component
|
||||
|
||||
Responsibility: Defines AI agent personalities and role-based behaviors.
|
||||
Provides specialized personas for different task types.
|
||||
"""
|
||||
|
||||
from typing import Dict, List, Tuple, Optional, Any
|
||||
@@ -9,7 +12,7 @@ from ..core.base import Component
|
||||
from setup import __version__
|
||||
|
||||
|
||||
class AgentsComponent(Component):
|
||||
class AgentPersonasComponent(Component):
|
||||
"""SuperClaude specialized AI agents component"""
|
||||
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
@@ -133,7 +136,7 @@ class AgentsComponent(Component):
|
||||
|
||||
def get_dependencies(self) -> List[str]:
|
||||
"""Get component dependencies"""
|
||||
return ["framework_docs"]
|
||||
return ["knowledge_base"]
|
||||
|
||||
def update(self, config: Dict[str, Any]) -> bool:
|
||||
"""
|
||||
@@ -1,5 +1,8 @@
|
||||
"""
|
||||
Modes component for SuperClaude behavioral modes
|
||||
Behavior Modes Component
|
||||
|
||||
Responsibility: Defines and manages execution modes for Claude behavior.
|
||||
Controls how Claude responds to different contexts and user intent.
|
||||
"""
|
||||
|
||||
from typing import Dict, List, Tuple, Optional, Any
|
||||
@@ -10,7 +13,7 @@ from setup import __version__
|
||||
from ..services.claude_md import CLAUDEMdService
|
||||
|
||||
|
||||
class ModesComponent(Component):
|
||||
class BehaviorModesComponent(Component):
|
||||
"""SuperClaude behavioral modes component"""
|
||||
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
@@ -149,7 +152,7 @@ class ModesComponent(Component):
|
||||
|
||||
def get_dependencies(self) -> List[str]:
|
||||
"""Get dependencies"""
|
||||
return ["framework_docs"]
|
||||
return ["knowledge_base"]
|
||||
|
||||
def update(self, config: Dict[str, Any]) -> bool:
|
||||
"""
|
||||
418
setup/components/knowledge_base.py
Normal file
418
setup/components/knowledge_base.py
Normal file
@@ -0,0 +1,418 @@
|
||||
"""
|
||||
Knowledge Base Component for SuperClaude
|
||||
|
||||
Responsibility: Provides structured knowledge initialization for the framework.
|
||||
Manages framework knowledge documents (principles, rules, flags, research config, business patterns).
|
||||
These files form the foundation of Claude's understanding of the SuperClaude framework.
|
||||
"""
|
||||
|
||||
from typing import Dict, List, Tuple, Optional, Any
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
|
||||
from ..core.base import Component
|
||||
from ..services.claude_md import CLAUDEMdService
|
||||
from setup import __version__
|
||||
|
||||
|
||||
class KnowledgeBaseComponent(Component):
|
||||
"""
|
||||
Knowledge Base Component
|
||||
|
||||
Responsibility: Initialize and maintain SuperClaude's knowledge base.
|
||||
Installs framework knowledge documents that guide Claude's behavior and decision-making.
|
||||
"""
|
||||
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
"""Initialize knowledge base component"""
|
||||
super().__init__(install_dir)
|
||||
|
||||
def get_metadata(self) -> Dict[str, str]:
|
||||
"""Get component metadata"""
|
||||
return {
|
||||
"name": "knowledge_base",
|
||||
"version": __version__,
|
||||
"description": "SuperClaude knowledge base (principles, rules, flags, patterns)",
|
||||
"category": "knowledge",
|
||||
}
|
||||
|
||||
def is_reinstallable(self) -> bool:
|
||||
"""
|
||||
Framework docs should always be updated to latest version.
|
||||
SuperClaude-related documentation should always overwrite existing files.
|
||||
"""
|
||||
return True
|
||||
|
||||
def validate_prerequisites(
|
||||
self, installSubPath: Optional[Path] = None
|
||||
) -> Tuple[bool, List[str]]:
|
||||
"""
|
||||
Check prerequisites for framework docs component (multi-directory support)
|
||||
|
||||
Returns:
|
||||
Tuple of (success: bool, error_messages: List[str])
|
||||
"""
|
||||
from ..utils.security import SecurityValidator
|
||||
|
||||
errors = []
|
||||
|
||||
# Check if all source directories exist
|
||||
for source_dir in self._get_source_dirs():
|
||||
if not source_dir.exists():
|
||||
errors.append(f"Source directory not found: {source_dir}")
|
||||
|
||||
# Check if all required framework files exist
|
||||
missing_files = []
|
||||
for source, _ in self.get_files_to_install():
|
||||
if not source.exists():
|
||||
missing_files.append(str(source.relative_to(Path(__file__).parent.parent.parent / "superclaude")))
|
||||
|
||||
if missing_files:
|
||||
errors.append(f"Missing component files: {missing_files}")
|
||||
|
||||
# Check write permissions to install directory
|
||||
has_perms, missing = SecurityValidator.check_permissions(
|
||||
self.install_dir, {"write"}
|
||||
)
|
||||
if not has_perms:
|
||||
errors.append(f"No write permissions to {self.install_dir}: {missing}")
|
||||
|
||||
# Validate installation target
|
||||
is_safe, validation_errors = SecurityValidator.validate_installation_target(
|
||||
self.install_component_subdir
|
||||
)
|
||||
if not is_safe:
|
||||
errors.extend(validation_errors)
|
||||
|
||||
# Validate files individually (each file with its own source dir)
|
||||
for source, target in self.get_files_to_install():
|
||||
# Get the appropriate base source directory for this file
|
||||
source_parent = source.parent
|
||||
|
||||
# Validate source path
|
||||
is_safe, msg = SecurityValidator.validate_path(source, source_parent)
|
||||
if not is_safe:
|
||||
errors.append(f"Invalid source path {source}: {msg}")
|
||||
|
||||
# Validate target path
|
||||
is_safe, msg = SecurityValidator.validate_path(target, self.install_component_subdir)
|
||||
if not is_safe:
|
||||
errors.append(f"Invalid target path {target}: {msg}")
|
||||
|
||||
# Validate file extension
|
||||
is_allowed, msg = SecurityValidator.validate_file_extension(source)
|
||||
if not is_allowed:
|
||||
errors.append(f"File {source}: {msg}")
|
||||
|
||||
if not self.file_manager.ensure_directory(self.install_component_subdir):
|
||||
errors.append(
|
||||
f"Could not create install directory: {self.install_component_subdir}"
|
||||
)
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
def get_metadata_modifications(self) -> Dict[str, Any]:
|
||||
"""Get metadata modifications for SuperClaude"""
|
||||
return {
|
||||
"framework": {
|
||||
"version": __version__,
|
||||
"name": "superclaude",
|
||||
"description": "AI-enhanced development framework for Claude Code",
|
||||
"installation_type": "global",
|
||||
"components": ["knowledge_base"],
|
||||
},
|
||||
"superclaude": {
|
||||
"enabled": True,
|
||||
"version": __version__,
|
||||
"profile": "default",
|
||||
"auto_update": False,
|
||||
},
|
||||
}
|
||||
|
||||
def _install(self, config: Dict[str, Any]) -> bool:
|
||||
"""Install knowledge base component"""
|
||||
self.logger.info("Installing SuperClaude knowledge base...")
|
||||
|
||||
return super()._install(config)
|
||||
|
||||
def _post_install(self) -> bool:
|
||||
# Create or update metadata
|
||||
try:
|
||||
metadata_mods = self.get_metadata_modifications()
|
||||
self.settings_manager.update_metadata(metadata_mods)
|
||||
self.logger.info("Updated metadata with framework configuration")
|
||||
|
||||
# Add component registration to metadata (with file list for sync)
|
||||
self.settings_manager.add_component_registration(
|
||||
"knowledge_base",
|
||||
{
|
||||
"version": __version__,
|
||||
"category": "documentation",
|
||||
"files_count": len(self.component_files),
|
||||
"files": list(self.component_files), # Track for sync/deletion
|
||||
},
|
||||
)
|
||||
|
||||
self.logger.info("Updated metadata with knowledge base component registration")
|
||||
|
||||
# Migrate any existing SuperClaude data from settings.json
|
||||
if self.settings_manager.migrate_superclaude_data():
|
||||
self.logger.info(
|
||||
"Migrated existing SuperClaude data from settings.json"
|
||||
)
|
||||
except Exception as e:
|
||||
self.logger.error(f"Failed to update metadata: {e}")
|
||||
return False
|
||||
|
||||
# Create additional directories for other components
|
||||
additional_dirs = ["commands", "backups", "logs"]
|
||||
for dirname in additional_dirs:
|
||||
dir_path = self.install_dir / dirname
|
||||
if not self.file_manager.ensure_directory(dir_path):
|
||||
self.logger.warning(f"Could not create directory: {dir_path}")
|
||||
|
||||
# Update CLAUDE.md with framework documentation imports
|
||||
try:
|
||||
manager = CLAUDEMdService(self.install_dir)
|
||||
manager.add_imports(self.component_files, category="Framework Documentation")
|
||||
self.logger.info("Updated CLAUDE.md with framework documentation imports")
|
||||
except Exception as e:
|
||||
self.logger.warning(
|
||||
f"Failed to update CLAUDE.md with framework documentation imports: {e}"
|
||||
)
|
||||
# Don't fail the whole installation for this
|
||||
|
||||
return True
|
||||
|
||||
def uninstall(self) -> bool:
|
||||
"""Uninstall knowledge base component"""
|
||||
try:
|
||||
self.logger.info("Uninstalling SuperClaude knowledge base component...")
|
||||
|
||||
# Remove framework files
|
||||
removed_count = 0
|
||||
for filename in self.component_files:
|
||||
file_path = self.install_component_subdir / filename
|
||||
if self.file_manager.remove_file(file_path):
|
||||
removed_count += 1
|
||||
self.logger.debug(f"Removed {filename}")
|
||||
else:
|
||||
self.logger.warning(f"Could not remove {filename}")
|
||||
|
||||
# Update metadata to remove knowledge base component
|
||||
try:
|
||||
if self.settings_manager.is_component_installed("knowledge_base"):
|
||||
self.settings_manager.remove_component_registration("knowledge_base")
|
||||
metadata_mods = self.get_metadata_modifications()
|
||||
metadata = self.settings_manager.load_metadata()
|
||||
for key in metadata_mods.keys():
|
||||
if key in metadata:
|
||||
del metadata[key]
|
||||
|
||||
self.settings_manager.save_metadata(metadata)
|
||||
self.logger.info("Removed knowledge base component from metadata")
|
||||
except Exception as e:
|
||||
self.logger.warning(f"Could not update metadata: {e}")
|
||||
|
||||
self.logger.success(
|
||||
f"Framework docs component uninstalled ({removed_count} files removed)"
|
||||
)
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
self.logger.exception(f"Unexpected error during knowledge base uninstallation: {e}")
|
||||
return False
|
||||
|
||||
def get_dependencies(self) -> List[str]:
|
||||
"""Get component dependencies (knowledge base has none)"""
|
||||
return []
|
||||
|
||||
def update(self, config: Dict[str, Any]) -> bool:
|
||||
"""
|
||||
Sync knowledge base component (overwrite + delete obsolete files).
|
||||
No backup needed - SuperClaude source files are always authoritative.
|
||||
"""
|
||||
try:
|
||||
self.logger.info("Syncing SuperClaude knowledge base component...")
|
||||
|
||||
# Get previously installed files from metadata
|
||||
metadata = self.settings_manager.load_metadata()
|
||||
previous_files = set(
|
||||
metadata.get("components", {})
|
||||
.get("knowledge_base", {})
|
||||
.get("files", [])
|
||||
)
|
||||
|
||||
# Get current files from source
|
||||
current_files = set(self.component_files)
|
||||
|
||||
# Files to delete (were installed before, but no longer in source)
|
||||
files_to_delete = previous_files - current_files
|
||||
|
||||
# Delete obsolete files
|
||||
deleted_count = 0
|
||||
for filename in files_to_delete:
|
||||
file_path = self.install_component_subdir / filename
|
||||
if file_path.exists():
|
||||
try:
|
||||
file_path.unlink()
|
||||
deleted_count += 1
|
||||
self.logger.info(f"Deleted obsolete file: {filename}")
|
||||
except Exception as e:
|
||||
self.logger.warning(f"Could not delete {filename}: {e}")
|
||||
|
||||
# Install/overwrite current files (no backup)
|
||||
success = self.install(config)
|
||||
|
||||
if success:
|
||||
# Update metadata with current file list
|
||||
self.settings_manager.add_component_registration(
|
||||
"knowledge_base",
|
||||
{
|
||||
"version": __version__,
|
||||
"category": "documentation",
|
||||
"files_count": len(current_files),
|
||||
"files": list(current_files), # Track installed files
|
||||
},
|
||||
)
|
||||
|
||||
self.logger.success(
|
||||
f"Framework docs synced: {len(current_files)} files, {deleted_count} obsolete files removed"
|
||||
)
|
||||
else:
|
||||
self.logger.error("Framework docs sync failed")
|
||||
|
||||
return success
|
||||
|
||||
except Exception as e:
|
||||
self.logger.exception(f"Unexpected error during knowledge base sync: {e}")
|
||||
return False
|
||||
|
||||
def validate_installation(self) -> Tuple[bool, List[str]]:
|
||||
"""Validate knowledge base component installation"""
|
||||
errors = []
|
||||
|
||||
# Check if all framework files exist
|
||||
for filename in self.component_files:
|
||||
file_path = self.install_component_subdir / filename
|
||||
if not file_path.exists():
|
||||
errors.append(f"Missing framework file: {filename}")
|
||||
elif not file_path.is_file():
|
||||
errors.append(f"Framework file is not a regular file: {filename}")
|
||||
|
||||
# Check metadata registration
|
||||
if not self.settings_manager.is_component_installed("knowledge_base"):
|
||||
errors.append("Knowledge base component not registered in metadata")
|
||||
else:
|
||||
# Check version matches
|
||||
installed_version = self.settings_manager.get_component_version("knowledge_base")
|
||||
expected_version = self.get_metadata()["version"]
|
||||
if installed_version != expected_version:
|
||||
errors.append(
|
||||
f"Version mismatch: installed {installed_version}, expected {expected_version}"
|
||||
)
|
||||
|
||||
# Check metadata structure
|
||||
try:
|
||||
framework_config = self.settings_manager.get_metadata_setting("framework")
|
||||
if not framework_config:
|
||||
errors.append("Missing framework configuration in metadata")
|
||||
else:
|
||||
required_keys = ["version", "name", "description"]
|
||||
for key in required_keys:
|
||||
if key not in framework_config:
|
||||
errors.append(f"Missing framework.{key} in metadata")
|
||||
except Exception as e:
|
||||
errors.append(f"Could not validate metadata: {e}")
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
def _get_source_dirs(self):
|
||||
"""Get source directories for framework documentation files"""
|
||||
# Assume we're in superclaude/setup/components/framework_docs.py
|
||||
# Framework files are organized in superclaude/{framework,business,research}
|
||||
project_root = Path(__file__).parent.parent.parent
|
||||
return [
|
||||
project_root / "superclaude" / "framework",
|
||||
project_root / "superclaude" / "business",
|
||||
project_root / "superclaude" / "research",
|
||||
]
|
||||
|
||||
def _get_source_dir(self):
|
||||
"""Get source directory (compatibility method, returns first directory)"""
|
||||
dirs = self._get_source_dirs()
|
||||
return dirs[0] if dirs else None
|
||||
|
||||
def _discover_component_files(self) -> List[str]:
|
||||
"""
|
||||
Discover framework .md files across multiple directories
|
||||
|
||||
Returns:
|
||||
List of relative paths (e.g., ['framework/flags.md', 'business/examples.md'])
|
||||
"""
|
||||
all_files = []
|
||||
project_root = Path(__file__).parent.parent.parent / "superclaude"
|
||||
|
||||
for source_dir in self._get_source_dirs():
|
||||
if not source_dir.exists():
|
||||
self.logger.warning(f"Source directory not found: {source_dir}")
|
||||
continue
|
||||
|
||||
# Get directory name relative to superclaude/
|
||||
dir_name = source_dir.relative_to(project_root)
|
||||
|
||||
# Discover .md files in this directory
|
||||
files = self._discover_files_in_directory(
|
||||
source_dir,
|
||||
extension=".md",
|
||||
exclude_patterns=["README.md", "CHANGELOG.md", "LICENSE.md"],
|
||||
)
|
||||
|
||||
# Add directory prefix to each file
|
||||
for file in files:
|
||||
all_files.append(str(dir_name / file))
|
||||
|
||||
return all_files
|
||||
|
||||
def get_files_to_install(self) -> List[Tuple[Path, Path]]:
|
||||
"""
|
||||
Return list of files to install from multiple source directories
|
||||
|
||||
Returns:
|
||||
List of tuples (source_path, target_path)
|
||||
"""
|
||||
files = []
|
||||
project_root = Path(__file__).parent.parent.parent / "superclaude"
|
||||
|
||||
for relative_path in self.component_files:
|
||||
source = project_root / relative_path
|
||||
# Install to superclaude/ subdirectory structure
|
||||
target = self.install_component_subdir / relative_path
|
||||
files.append((source, target))
|
||||
|
||||
return files
|
||||
|
||||
def get_size_estimate(self) -> int:
|
||||
"""Get estimated installation size"""
|
||||
total_size = 0
|
||||
|
||||
for source, _ in self.get_files_to_install():
|
||||
if source.exists():
|
||||
total_size += source.stat().st_size
|
||||
|
||||
# Add overhead for settings.json and directories
|
||||
total_size += 10240 # ~10KB overhead
|
||||
|
||||
return total_size
|
||||
|
||||
def get_installation_summary(self) -> Dict[str, Any]:
|
||||
"""Get installation summary"""
|
||||
return {
|
||||
"component": self.get_metadata()["name"],
|
||||
"version": self.get_metadata()["version"],
|
||||
"files_installed": len(self.component_files),
|
||||
"framework_files": self.component_files,
|
||||
"estimated_size": self.get_size_estimate(),
|
||||
"install_directory": str(self.install_dir),
|
||||
"dependencies": self.get_dependencies(),
|
||||
}
|
||||
@@ -1,5 +1,8 @@
|
||||
"""
|
||||
MCP component for MCP server integration
|
||||
MCP Integration Component
|
||||
|
||||
Responsibility: Integrates Model Context Protocol for external tool access.
|
||||
Manages connections to specialized MCP servers and capabilities.
|
||||
"""
|
||||
|
||||
import os
|
||||
@@ -15,7 +18,7 @@ from setup import __version__
|
||||
from ..core.base import Component
|
||||
|
||||
|
||||
class MCPComponent(Component):
|
||||
class MCPIntegrationComponent(Component):
|
||||
"""MCP servers integration component"""
|
||||
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
@@ -941,7 +944,7 @@ class MCPComponent(Component):
|
||||
|
||||
def get_dependencies(self) -> List[str]:
|
||||
"""Get dependencies"""
|
||||
return ["framework_docs"]
|
||||
return ["knowledge_base"]
|
||||
|
||||
def update(self, config: Dict[str, Any]) -> bool:
|
||||
"""Update MCP component"""
|
||||
@@ -1,5 +1,8 @@
|
||||
"""
|
||||
Commands component for SuperClaude slash command definitions
|
||||
Slash Commands Component
|
||||
|
||||
Responsibility: Registers and manages slash commands for CLI interactions.
|
||||
Provides custom command definitions and execution logic.
|
||||
"""
|
||||
|
||||
from typing import Dict, List, Tuple, Optional, Any
|
||||
@@ -9,7 +12,7 @@ from ..core.base import Component
|
||||
from setup import __version__
|
||||
|
||||
|
||||
class CommandsComponent(Component):
|
||||
class SlashCommandsComponent(Component):
|
||||
"""SuperClaude slash commands component"""
|
||||
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
@@ -180,7 +183,7 @@ class CommandsComponent(Component):
|
||||
|
||||
def get_dependencies(self) -> List[str]:
|
||||
"""Get dependencies"""
|
||||
return ["framework_docs"]
|
||||
return ["knowledge_base"]
|
||||
|
||||
def update(self, config: Dict[str, Any]) -> bool:
|
||||
"""
|
||||
@@ -149,7 +149,7 @@ class Installer:
|
||||
|
||||
# Framework components are ALWAYS updated to latest version
|
||||
# These are SuperClaude implementation files, not user configurations
|
||||
framework_components = {'framework_docs', 'agents', 'commands', 'modes', 'core', 'mcp'}
|
||||
framework_components = {'knowledge_base', 'agents', 'commands', 'modes', 'core', 'mcp'}
|
||||
|
||||
if component_name in framework_components:
|
||||
# Always update framework components to latest version
|
||||
|
||||
@@ -149,7 +149,7 @@ def _run_installation(
|
||||
verbose=verbose,
|
||||
quiet=False,
|
||||
yes=True, # Always non-interactive
|
||||
components=["framework_docs", "modes", "commands", "agents"], # Full install (mcp integrated into airis-mcp-gateway)
|
||||
components=["knowledge_base", "modes", "commands", "agents"], # Full install (mcp integrated into airis-mcp-gateway)
|
||||
no_backup=False,
|
||||
list_components=False,
|
||||
diagnose=False,
|
||||
|
||||
Reference in New Issue
Block a user