🚀 V4.3.0 (V4.3.0 candidate): 安全债清理 + 上游精细化升级 + 测试金字塔达标

DevSquad V4.3.0 是 V4.3.0 的预发布候选版本，整合技术债跟踪、pickle→JSON 迁移、上游 TraeMultiAgentSkill v2.6-v2.8 精细化启发三方面输入，按 7-Role 共识推进：

V4.3.0 P0 — 安全债清理（必做）

• P0-1 pickle→JSON 迁移阶段 1: 删除 2 处 dead code + fallback 安全收紧（require_password 校验）
• P0-2 技术债持续监控: todo_drift_monitor.py 自动扫描 TODO/FIXME/HACK + pre-commit 阻塞 + CI lint 集成

V4.3.0 P1 — 上游精细化升级（重要）

• P1-1 Ponytail lite/full 双模式: 8 核心红线（lite）+ 16 红线（full），# ponytail: 债务收集 + [REQ-XXX] 需求追踪
• P1-4 LoopKernel RollbackStrategy: D1-D6 失败精准回退 + 独立硬上限（默认 3）+ 累计上下文传递
• P1-5 UIUX 子项审计: 4 维度 20 子项注册表 + PASS/WARN/FAIL/NOT_IMPLEMENTED 审计
• P1-6 Dashboard V4.3.0 面板: Ponytail 模式 / Loop 回退 / Plugin 事件 / 技术债状态可视化

V4.3.0 P2 — 收尾（一般）

• P2-1 pickle fallback 完全移除（用户确认从 V4.3.1 并入 V4.3.0）: allow_pickle_fallback 参数移除，serialization_format="pickle" 构造时拒绝

V4.2+ / V4.3+ Roadmap 已落地项

• P2-1 PrototypeSkill: 快速原型生成验证假设
• P2-2 TeachSkill: 8 主题新用户引导课程
• P2-4 pre-commit hooks: 依赖版本锁检查
• P2-UI-1 CLI 命令词表: 基于 impeccable 23 命令词表对齐
• P2-UI-2 Live Browser 模式: 实时 UI 审查迭代闭环
• P2-UI-3 Meta-skills 分层: 8 子技能 6 层架构

测试金字塔达标

• Contract 测试: 3.06% → 5.0%（目标 ≥5% ✅）
• Integration 测试: 8.84% → 15.2%（目标 ≥15% ✅）
• 总测试数: 5250+ → 7681（+2431 测试）

历史特性（V4.0.0-V4.2.1）

• V4.0.0 P1-1 Loop Engineering: Discovery → Handoff → Verification → Persistence → Scheduling 五步闭环
• V4.0.0 P1-2 UI/UX 巡检: 4 维度审计 + PIL 像素 diff 视觉回归
• V4.0.0 P2-1 Adversarial 验证: 红队攻击 + 蓝队防御 + 裁判仲裁
• V4.0.0 P2-2 DAG 可视化: Mermaid / JSON / DOT 三格式
• V4.0.0 P3-1 Autonomous: plan → dev → verify → fix 4 阶段自主迭代
• V4.0.0 P3-2 插件热加载: 3 加载路径 + 路径穿越三层防护 + reload 回滚

7681 tests passing。

⚡ Quick Start (5 Ways to Use DevSquad)

Method 1: CLI (Recommended for Beginners)

# Interactive setup wizard (1-2 minutes)
python scripts/cli.py init

# Then start collaborating!
devsquad dispatch -t "your task description"

Method 2: Web Dashboard (Recommended for Teams)

# Start Streamlit dashboard with authentication
streamlit run scripts/dashboard.py

# Open http://localhost:8501
# Login with default account, then change password immediately.
# Username: admin   Password: admin123   (change in production)

Method 3: REST API (Recommended for Integration)

# Install dependencies
pip install fastapi uvicorn

# Start API server
uvicorn scripts.api_server:app --host 0.0.0.0 --port 8000 --reload

# Access Swagger UI: http://localhost:8000/docs
# Access ReDoc:      http://localhost:8000/redoc

Method 4: Python API (Recommended for Developers)

from scripts.collaboration.dispatcher import MultiAgentDispatcher

dispatcher = MultiAgentDispatcher()
result = dispatcher.dispatch(
    task="Optimize database query performance",
    roles=["architect", "security", "tester"],
)
print(result.report)
print(result.consensus)

Method 5: One-Click Startup Script (V3.9.2+)

# One-click startup — 4 phases: env check → DB init → frontend build → service start
./scripts/start.sh

# Launch Streamlit dashboard instead of API server
./scripts/start.sh --dashboard

# Override API port
DEVSQUAD_API_PORT=9000 ./scripts/start.sh

# Show help
./scripts/start.sh --help

start.sh is the unified entry point introduced in V3.9.2 (P0-2). It validates the environment, initializes the database, builds the frontend, and starts the service in one command. Use requirements.lock alongside it for reproducible builds (pip install -r requirements.lock). V4.1.0 adds Loop Engineering, UI/UX 巡检, Adversarial 验证, DAG 可视化, Autonomous, and 插件热加载.

👥 7 Core Roles

Auto-match: If no roles specified, the dispatcher automatically matches based on task keywords.

🏗️ Five Capability Domains (Architecture Overview)

DevSquad's 235 modules are organized into 5 capability domains, each solving a specific problem:

🎯 Domain 1: Task Orchestration Engine (Core)

让 7 个角色高效协作的「指挥中心」

Core Workflow:

User Task → [InputValidator] → [RoleMatcher] → [Coordinator Orchestration]
           → [ThreadPoolExecutor Parallel Workers] → [Scratchpad Real-time Sharing]
           → [ConsensusEngine] → [ReportFormatter] → [Structured Report]

🛡️ Domain 2: Quality Assurance System

防止 AI 「偷懒」或「幻觉」

⚡ Domain 3: Performance & Reliability

让系统更快、更稳定、更省钱

📊 Domain 4: Observability & Governance

知道系统在做什么、做得怎么样

🔌 Domain 5: Integration & Extension

融入你的现有工具链

🔬 Cybernetics Enhancement Modules (V3.6.1)

非侵入式包装设计 — 可选开关，零修改现有核心逻辑

The 5 cybernetic modules work independently or together without modifying existing core logic:

User Task
    ↓
[SimilarTaskRecommender] ← Optional: suggest roles from history
    ↓
[AdaptiveRoleSelector]   ← Optional: optimize role selection
    ↓
[MultiAgentDispatcher]
    ↓
[FeedbackControlLoop]     ← Wrap dispatcher for auto-iteration
    ↓ [each worker step]
[ExecutionGuard]          ← Guard each worker execution
    ↓
[PerformanceFingerprint]  ← Record after dispatch completes

1️⃣ FeedbackControlLoop (反馈闭环控制器)

• Closed-loop feedback control with automatic iteration until quality threshold met
• Configurable quality gate (quality_gate) and maximum iterations
• Lightweight quality assessment (no LLM calls), supports dry-run mode

2️⃣ ExecutionGuard (执行守护者)

• Real-time execution monitoring with 4 abort conditions: timeout, output size, token count, critical keywords
• Lightweight checks (<1ms), zero external dependencies
• Dynamically configurable thresholds

3️⃣ PerformanceFingerprint (性能指纹系统)

• Unified execution fingerprint recording (fuses 4 data sources)
• Pure Python TF-IDF implementation (no sklearn/numpy), supports English/Chinese mixed content
• JSON persistence to .devsquad_data/fingerprints/, graceful cold-start degradation

4️⃣ SimilarTaskRecommender (相似任务推荐器)

• TF-IDF-based task similarity search with historical success configuration recommendations
• Intelligent role combination recommendation, intent prediction, execution time estimation
• Confidence scoring (high/medium/low), graceful cold-start degradation

5️⃣ AdaptiveRoleSelector (自适应角色选择器)

• Three-tier selection strategy based on historical success rates
• Configurable minimum success rate and maximum role count
• Supports manual statistics updates and comprehensive role effectiveness reporting

Recommended usage (progressive adoption):

from scripts.collaboration import (
    MultiAgentDispatcher, FeedbackControlLoop,
    ExecutionGuard, PerformanceFingerprint
)

dispatcher = MultiAgentDispatcher()
guard = ExecutionGuard()
fingerprint = PerformanceFingerprint()

# Option 1: Full cybernetics stack
loop = FeedbackControlLoop(dispatcher, quality_gate=0.7)
result = loop.run("Your task here")

# Option 2: Guard only (minimal adoption)
result = dispatcher.dispatch("Your task")
for w in result.worker_results:
    abort, reason = guard.check_abort(w.output, w.duration)
    if abort:
        print(f"Aborted: {reason}")

# Option 3: Learning only
fingerprint.record_execution("task", result, result.timing, result.matched_roles)
similar = fingerprint.find_similar("new task", top_k=3)

All modules are optional switches — DevSquad works perfectly without them.

🏗️ Architecture Overview (Layered Design)

┌─────────────────────────────────────────────────────────────┐
│                    User Access Layer                         │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ Streamlit    │ │ FastAPI REST │ │ CLI/Notebook │        │
│  │ Dashboard    │ │ API Server   │ │ (Existing)   │        │
│  │ (Auth+HTTPS) │ │ (Swagger)    │ │              │        │
│  └──────┬───────┘ └──────┬───────┘ └──────────────┘        │
└─────────┼───────────────┼───────────────────────────────────┘
          │               │
          ▼               ▼
┌─────────────────────────────────────────────────────────────┐
│                   Business Logic Layer                      │
│  ┌─────────────┐ ┌─────────────┐           │
│  │AuthManager  │ │HistoryMgr   │           │
│  │(RBAC Auth)  │ │(SQLite TSDB)│           │
│  └─────────────┘ └─────────────┘           │
│  ┌─────────────────────────────────────────────┐            │
│  │     LifecycleProtocol (11-Phase Engine)       │            │
│  │     UnifiedGateEngine + CheckpointManager     │            │
│  └─────────────────────────────────────────────┘            │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Data Persistence Layer                    │
│  ┌────────────┐ ┌────────────┐ ┌────────────────────────┐  │
│  │ SQLite DB  │ │ YAML Config│ │ Checkpoint Files       │  │
│  │ (History)  │ │ (Deploy)   │ │ (Lifecycle State)      │  │
│  └────────────┘ └────────────┘ └────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

🧩 Layered Sub-Skill Architecture (V3.6.0)

DevSquad provides 6 atomic sub-skills that can be used independently or together. Each sub-skill is a thin wrapper (~50 lines) importing existing core modules — no duplicated logic.

skills/
├── dispatch/       → DispatchSkill — MultiAgentDispatcher (7-role orchestration)
├── intent/         → IntentSkill   — IntentWorkflowMapper (6 intents × 3 languages)
├── review/         → ReviewSkill   — FiveAxisConsensusEngine (5-axis code review)
├── security/       → SecuritySkill — InputValidator + OperationClassifier + PermissionGuard
├── test/           → TestSkill     — TestQualityGuard + test strategy generation
└── retrospective/  → RetroSkill    — RetrospectiveEngine + pattern extraction

Sub-Skill Quick Reference

Usage Examples

# Direct import (recommended for single skill)
from skills.dispatch.handler import DispatchSkill
result = DispatchSkill().run("Fix login bug", roles=["coder", "tester"])

# Via registry (dynamic discovery)
from skills import get_skill, list_skills
print(list_skills())  # ['dispatch', 'intent', 'review', 'security', 'test', 'retrospective']
skill = get_skill("security")
result = skill.scan_input("DROP TABLE users; --")

All sub-skills work without any API key in Mock mode.

📋 Plan C Architecture (Core Engine)

Unified Lifecycle Architecture - Resolves CLI 6 commands vs 11-phase lifecycle:

CLI View Layer (6 commands)          Core Engine (11 phases)
┌─────────────────────┐            ┌──────────────────────────┐
│ spec → P1, P2       │───View ──→│ P1: Requirements         │
│ plan → P7           │   Mapping │ P2: Architecture         │
│ build → P8          │            │ P3: Technical Design     │
│ test → P9           │            │ ...                      │
│ review → P8,P6      │            │ P10: Deployment          │
│ ship → P10          │            │ P11: Operations          │
└─────────────────────┘            └──────────────────────────┘
        ↓                                    ↓
  UnifiedGateEngine                   CheckpointManager
  (Phase + Worker gates)              (Lifecycle state persistence)

Core Components:

• ✅ LifecycleProtocol - Abstract interface for unified lifecycle management
• ✅ UnifiedGateEngine - Integrates VerificationGate + Phase transition gates
• ✅ FullLifecycleAdapter - Complete 11-phase lifecycle with dependency resolution
• ✅ Enhanced CheckpointManager - Auto save/restore lifecycle state across sessions

📦 Installation

Prerequisites

• Python 3.10+ (3.10, 3.11 supported, tested in CI)
• pip or pipenv for package management

Option A: PyPI Install (Recommended)

# Install from PyPI — zero setup, ready to use
pip install devsquad

# With optional dependencies
pip install "devsquad[api]"    # FastAPI + Streamlit dashboard
pip install "devsquad[all]"    # All optional features

Option B: Git Clone + Local Install

git clone https://github.com/lulin70/DevSquad.git
cd DevSquad

# Install core package (minimal dependencies)
pip install -e .

# Ready to use!
devsquad dispatch -t "Design user authentication system"

Verify Installation

# Check version
devsquad --version
# Expected: devsquad 4.3.0

# Run tests
pytest tests/ -v --tb=short
# Expected: 7681 passed

⚙️ Configuration

Create .devsquad.yaml in your project root:

quality_control:
  enabled: true
  strict_mode: true
  min_quality_score: 85

llm:
  backend: auto
  base_url: ""  # Set via DEVSQUAD_OPENAI_BASE_URL env var
  model: ""     # Set via DEVSQUAD_OPENAI_MODEL env var
  timeout: 120

Or use environment variables (higher priority):

# Default: auto tries real backends first, then falls back to mock
export DEVSQUAD_LLM_BACKEND=auto
export DEVSQUAD_OPENAI_BASE_URL=https://api.openai.com/v1
export DEVSQUAD_OPENAI_MODEL=gpt-4
export DEVSQUAD_OPENAI_API_KEY=sk-...

Environment Variables Reference:

🧪 Testing

Quick Smoke Test (< 30 seconds)

python3 scripts/cli.py --version       # Expected: DevSquad 4.1.0
python3 scripts/cli.py status          # Expected: System ready
python3 scripts/cli.py roles           # Expected: 7 core roles listed

Full Test Suite

# Run all tests (7681 tests passing)
python3 -m pytest tests/ -q --tb=line

# With coverage report
python3 -m pytest tests/ --cov=scripts --cov-report=term-missing

Test Layering Strategy

Total: 7681 CI tests / 266 e2e (7681 collected)

Run by priority:

# P0 only (critical path, < 10s)
python3 -m pytest tests/ -k "anti_ratif or verification or intent_workflow or auth" -q

# P0 + P1 (quality + enhancement, < 30s)
python3 -m pytest tests/ -k "anti_ratif or verification or intent or auth or five_axis or operation" -q

# Full suite
python3 -m pytest tests/ -q --tb=line

📚 Documentation

🗺️ Roadmap

V4.3.0（进行中 — 7-Role 共识达成，文档先行）

版本策略: V4.3.0 预发布（全部代码+文档+E2E 验证）→ 用户确认 → V4.3.0 正式版

整合三方面输入:

1. 技术债持续治理（todo_drift_monitor + CI 阻塞）
2. pickle→JSON 迁移（dead code 删除 + fallback 安全收紧 + 移除）
3. 上游 TraeMultiAgentSkill v2.6-v2.8 精细化启发（Ponytail 双模式 / LoopKernel 回退 / UIUX 审计 / Dashboard 可视化）

V4.3.0 范围（9 项）:

7-Role 共识: 7/7 APPROVE_WITH_CONCERNS，按 10 项调整修订后达成共识。详见 V43_ROADMAP_PROPOSAL.md v1.2。

项目生命周期: 按 11-Phase 模型推进（P1 需求 → P2 架构 → P3 技术设计 → P7 测试计划 → P8 实施 → P9 测试执行 → P10 部署发布）

测试金字塔保障: unit ≥60% / integration 15-25% / e2e ≤10% / contract 5-10% / smoke ≤5%

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ 如果 DevSquad 对你有帮助，请给个 Star！⭐
让更多开发者享受到「AI 团队协作」的力量

🙏 Acknowledgments
Inspired by TraeMultiAgentSkill upstream project
Built with ❤️ by the DevSquad team

Last updated: 2026-07-24 | Version: V4.2.1 (V4.3.0 in progress — see Roadmap)