synapse-hub 0.0.0-stage → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/failure-analyst.md +47 -0
- package/.agents/agents/live-explorer.md +41 -0
- package/.agents/agents/orchestrator.md +43 -0
- package/.agents/agents/pom-crafter.md +81 -0
- package/.agents/agents/quality-gatekeeper.md +47 -0
- package/.agents/agents/test-runner.md +43 -0
- package/.agents/rules/context-engineering.md +88 -0
- package/.agents/rules/git-push-protocol.md +101 -0
- package/.agents/rules/graphify.md +14 -0
- package/.agents/rules/lessons-learned.md +23 -0
- package/.agents/rules/mandatory-playwright-live.md +29 -0
- package/.agents/rules/skill-precedence.md +42 -0
- package/.agents/rules/systematic-debugging.md +99 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +239 -0
- package/.agents/skills/antigravity-test-sentinel/SKILL.md +64 -0
- package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
- package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +70 -0
- package/.agents/skills/architecture-decision-records/SKILL.md +441 -0
- package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +72 -0
- package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +214 -0
- package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
- package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
- package/.agents/skills/clean-pom-crafter/SKILL.md +75 -0
- package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
- package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
- package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
- package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +879 -0
- package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
- package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
- package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
- package/.agents/skills/failure-autopsy-and-healing/SKILL.md +54 -0
- package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
- package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
- package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +98 -0
- package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
- package/.agents/skills/github-actions-templates/SKILL.md +334 -0
- package/.agents/skills/graphify-impact-analyzer/SKILL.md +78 -0
- package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
- package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
- package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
- package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
- package/.agents/skills/lam-script-generator/SKILL.md +83 -0
- package/.agents/skills/playwright-live-interaction/SKILL.md +86 -0
- package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
- package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
- package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
- package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
- package/.agents/skills/security-dast-sentinel/SKILL.md +176 -0
- package/.agents/skills/self-healing-locator/SKILL.md +73 -0
- package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
- package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
- package/.agents/skills/visual-regression-sentinel/SKILL.md +62 -0
- package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
- package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
- package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
- package/.agents/templates/completion_report.md +57 -0
- package/.agents/workflows/graphify.md +10 -0
- package/.agents/workflows/test-impact.md +15 -0
- package/.agents/workflows/verify.md +34 -0
- package/AGENTS.md +115 -0
- package/README.md +537 -2
- package/bin/agent-qa.js +90 -0
- package/package.json +59 -4
- package/skills_manifest.json +262 -0
- package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +97 -0
- package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
- package/tools/TOOLS_RUNBOOK.md +298 -0
- package/tools/agent_canary.py +501 -0
- package/tools/analyze_project.py +242 -0
- package/tools/api_drift_sentinel.py +208 -0
- package/tools/auto_heal.py +189 -0
- package/tools/browser_helpers.js +593 -0
- package/tools/bug_reporter.py +224 -0
- package/tools/cache_resolver.py +846 -0
- package/tools/check_env.py +288 -0
- package/tools/ci_healing_hook.py +128 -0
- package/tools/cli.py +402 -0
- package/tools/config_decoupler.py +253 -0
- package/tools/db_sandbox.py +341 -0
- package/tools/distill_log.py +152 -0
- package/tools/e2e_flow_prober.ps1 +65 -0
- package/tools/flaky_detector.py +222 -0
- package/tools/fuzz_payloads.py +197 -0
- package/tools/generate_allure_report.ps1 +30 -0
- package/tools/generate_api_matrix.py +193 -0
- package/tools/generate_tc_from_story.py +182 -0
- package/tools/generate_test_reports.ps1 +135 -0
- package/tools/git_pre_commit_guard.py +203 -0
- package/tools/heal_pr_automator.py +195 -0
- package/tools/heuristic_locator_matcher.py +202 -0
- package/tools/infer_linter.py +238 -0
- package/tools/lint_ai_docs.py +254 -0
- package/tools/lookup_tc.py +165 -0
- package/tools/lookup_xpath.py +167 -0
- package/tools/matrix_sharder.py +146 -0
- package/tools/mcp_excel_server.ps1 +251 -0
- package/tools/mcp_server.py +490 -0
- package/tools/micro_mutator.py +309 -0
- package/tools/network_mock_shield.py +170 -0
- package/tools/omni_emitter.py +500 -0
- package/tools/omni_parser.py +435 -0
- package/tools/omni_transpiler.py +168 -0
- package/tools/pinpoint_failure.py +88 -0
- package/tools/project_state.py +169 -0
- package/tools/repo_map.json +12 -0
- package/tools/repo_map.py +277 -0
- package/tools/repo_map.txt +7 -0
- package/tools/safety_firewall.py +245 -0
- package/tools/setup_project.py +265 -0
- package/tools/smart_visual_masker.py +134 -0
- package/tools/test_impact.py +321 -0
- package/tools/tms_sync_bridge.py +342 -0
- package/tools/trace_data_flow.py +240 -0
- package/tools/traffic_session_converter.py +256 -0
- package/tools/universal_ir.py +480 -0
- package/tools/validate_groovy_scripts.py +173 -0
- package/tools/verify_all.py +496 -0
- package/tools/verify_all.sh +4 -0
- package/tools/visual_diff_canvas.py +142 -0
- package/tools/visual_som_helper.py +425 -0
- package/tools/wcag_audit.py +214 -0
package/README.md
CHANGED
|
@@ -1,3 +1,538 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 🧠 Synapse Hub — Trung Tâm Trí Tuệ & Mạng Lưới Kỹ Năng Cho AI Agent
|
|
2
|
+
|
|
3
|
+
[🇻🇳 Tiếng Việt](#-synapse-hub--trung-tâm-trí-tuệ--mạng-lưới-kỹ-năng-cho-ai-agent) | [🇬🇧 English Edition](#-english-edition)
|
|
4
|
+
|
|
5
|
+
> **Bộ não trí tuệ dùng chung và mạng lưới kỹ năng tự hành, tăng cường năng lực cho các trợ lý AI (Google Antigravity, Cursor, Windsurf, Claude Code) trên mọi hệ sinh thái kiểm thử tự động.**
|
|
6
|
+
> **Tác giả:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))
|
|
7
|
+
> **Phiên bản Hub:** `v2.0.1` | **Quy mô:** 27 Kỹ năng chuẩn hóa, 6 Vai trò AI Swarm, 7 Quy tắc cốt lõi, 20+ Công cụ tự động.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 🌟 1. Tổng quan & Mục đích Kiến trúc
|
|
12
|
+
|
|
13
|
+
**Synapse Hub** là tầng trí tuệ đa tác tử tách rời (**Decoupled Shared Intelligence Core**), đóng vai trò như một **"Bộ não dùng chung"**, tách biệt hoàn toàn khỏi mã nguồn của từng dự án cụ thể. Dự án trang bị cho AI agents đội ngũ Sub-Agent QC chuyên biệt (Multi-Agent Swarm), quy trình tự chữa lành (Self-Healing), khả năng thấu hiểu mã nguồn cấp độ AST và các cổng chất lượng nghiêm ngặt (Quality Gates)—cho phép tự động hóa kiểm thử chuẩn xác tuyệt đối trên mọi codebase mà không làm bẩn repository mục tiêu.
|
|
14
|
+
|
|
15
|
+
```mermaid
|
|
16
|
+
flowchart TD
|
|
17
|
+
subgraph Hub["🧠 Synapse Hub (Intelligence Core v2.0.1)"]
|
|
18
|
+
Skills[".agents/skills/ (27 Skills)"]
|
|
19
|
+
Agents[".agents/agents/ (6 Specialized Roles)"]
|
|
20
|
+
Rules[".agents/rules/ (7 Core Rules)"]
|
|
21
|
+
Tools["tools/ (20+ Universal Python Tools)"]
|
|
22
|
+
Workflows[".agents/workflows/"]
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
subgraph ChatSession["💬 AI Agent Workspace / Chat Session"]
|
|
26
|
+
Hub -->|Mount/Add Workspace| ChatSession
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
subgraph Projects["📁 Các Dự Án Mục Tiêu (Target Projects)"]
|
|
30
|
+
ProjectA["Dự án A<br/>(PROJECT_AI_GUIDE.md + Source Code)"]
|
|
31
|
+
ProjectB["Dự án B<br/>(PROJECT_AI_GUIDE.md + Test Code)"]
|
|
32
|
+
ProjectC["Dự án C<br/>(PROJECT_AI_GUIDE.md + App Code)"]
|
|
33
|
+
Other["Dự án khác..."]
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
ProjectA -->|Mount Workspace| ChatSession
|
|
37
|
+
ProjectB -.->|Mount Workspace| ChatSession
|
|
38
|
+
ProjectC -.->|Mount Workspace| ChatSession
|
|
39
|
+
Other -.->|Mount Workspace| ChatSession
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### 💎 Lợi Ích Đột Phá Khi Sử Dụng Synapse Hub:
|
|
43
|
+
|
|
44
|
+
#### 1. 🧠 Khả Năng Suy Nghĩ Có Chiều Sâu (System-2 Reasoning & Cognitive Forcing)
|
|
45
|
+
* **Xóa bỏ chế độ "Autocomplete vô thức":** Khi đối mặt với lỗi kiểm thử hoặc yêu cầu viết test mới, AI không tự tiện sinh code ngẫu nhiên theo trực giác mà bị **ép buộc đi qua quy trình tư duy 4 bước (Cognitive Forcing Pipeline)**:
|
|
46
|
+
1. *Trích xuất bất biến (Invariants):* Điều gì bắt buộc không bao giờ được phép xảy ra?
|
|
47
|
+
2. *Giả định phản nghiệm (Popper Falsification):* Đặt ra 3 kịch bản lập trình viên làm hàm chạy sai nhưng test ngây ngô vẫn pass (False Negatives).
|
|
48
|
+
3. *Tự phản biện (Self-Debate):* Tự chứng minh tại sao assertion chuẩn bị viết sẽ bắt chết cả 3 kịch bản lỗi trên.
|
|
49
|
+
4. *Sinh code phòng vệ:* Chỉ xuất mã khi đã vượt qua 3 tầng lập luận.
|
|
50
|
+
* **Tự đối kháng Red-Team vs Blue-Team:** Tự động tiêm đột biến AST (`tools/micro_mutator.py`) vào code kiểm thử để kiểm tra xem test suite có thực sự bắt được bug thật hay không. Bắt buộc **Điểm đột biến (Mutation Score) $\ge 80\%$** mới cho phép hoàn thành tác vụ.
|
|
51
|
+
|
|
52
|
+
#### 2. ⚡ Siêu Tiết Kiệm Token (Cắt Giảm 85% – 95% Chi Phí Context)
|
|
53
|
+
* **Log Distillation (Giảm 95% token log):** Công cụ `tools/distill_log.py` tự động lọc sạch 95% log rác dài lê thê của CLI/Gradle/Playwright, chỉ giữ lại đúng ~10 dòng chứa dòng lỗi và exception (< 50 tokens) thay vì ném 3.000 dòng log làm loãng context.
|
|
54
|
+
* **AST Repo Mapping (Giảm 90% token đọc file):** Công cụ `tools/repo_map.py` nén 500+ method signatures vào đúng một bản đồ tóm tắt < 600 tokens. AI nắm toàn bộ hàm và class mà **không bao giờ phải mở đọc cả file 4.000 dòng** gây nổ context window ("Context Window Blowout").
|
|
55
|
+
* **Compact AOM (Giảm 90% token HTML):** Không bao giờ dump cả trang HTML DOM 50.000 dòng vào prompt; công cụ trích xuất cây Accessibility Object Model (AOM) tương tác dưới 500 tokens.
|
|
56
|
+
* **Zero-Token SQLite Memory Cache:** Ghi nhận và tra cứu kinh nghiệm sửa bug qua cơ sở dữ liệu SQLite ngoại tuyến (`~/.agent_memory/global_cache.db`) bằng thuật toán vector cosine similarity với chi phí **0 token context**.
|
|
57
|
+
* **Chống suy thoái ngữ cảnh ("Context Rot" & "Lost-in-the-Middle"):** Đảm bảo AI luôn duy trì sự minh mẫn, không bao giờ bị ảo giác hay quên logic nghiệp vụ ngay cả trong các phiên làm việc dài trên 100.000 tokens.
|
|
58
|
+
|
|
59
|
+
#### 3. 📊 So Sánh Hiệu Năng Thực Tế:
|
|
60
|
+
|
|
61
|
+
| Tiêu chí đánh giá | Cách làm thông thường (Naive AI Prompting) | Khi sử dụng Synapse Hub 🧠 |
|
|
62
|
+
| :--- | :---: | :---: |
|
|
63
|
+
| **Token tiêu thụ / mỗi lần fix lỗi** | 15.000 – 40.000 tokens *(đọc cả file lớn, dump cả log)* | **300 – 800 tokens (Tiết kiệm > 90%)** |
|
|
64
|
+
| **Tỷ lệ Fake-Pass (Test pass ảo, 0 assert)** | 30% – 50% *(AI có xu hướng nuốt lỗi để báo PASS)* | **0% (Chặn đứng bởi Truth Anchor & 8 DoD Gates)** |
|
|
65
|
+
| **Trí nhớ sửa lỗi xuyên phiên (Cross-Session)** | Quên sạch ngay khi mở tab chat mới | **Bền vững qua SQLite Central Cache (0 token)** |
|
|
66
|
+
| **Hiện tượng quên ngữ cảnh (Context Rot)** | Xảy ra nhanh chóng sau 40k – 60k tokens | **Miễn nhiễm nhờ 3 tầng Progressive Disclosure** |
|
|
67
|
+
| **Thời gian tự phục hồi lỗi (MTTR)** | 5 – 15 phút mò mẫm thử nghiệm | **< 1 giây (Tra cứu kinh nghiệm có sẵn)** |
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 🚀 2. Cách Sử Dụng (NPM / npx & Workspace Mount)
|
|
72
|
+
|
|
73
|
+
[](https://www.npmjs.com/package/synapse-hub)
|
|
74
|
+
[](https://www.npmjs.com/package/synapse-hub)
|
|
75
|
+
[](https://github.com/TeeVee998/Synapse-Hub/blob/main/package.json)
|
|
76
|
+
|
|
77
|
+
### Cách A: Sử dụng tức thì qua NPM Registry (Khuyên dùng)
|
|
78
|
+
Gói chính thức đã được phát hành toàn cầu tại **[npmjs.com/package/synapse-hub](https://www.npmjs.com/package/synapse-hub)**. Bạn có thể sử dụng ngay mà không cần clone mã nguồn:
|
|
79
|
+
|
|
80
|
+
#### 1. Thực thi tức thì không cần cài đặt (`npx`):
|
|
81
|
+
Tại thư mục gốc của bất kỳ dự án nào, thực thi trực tiếp:
|
|
82
|
+
```bash
|
|
83
|
+
# Khởi tạo tự động 1-Click (sinh PROJECT_AI_GUIDE.md, cài pre-push hook, trích xuất AST repo map)
|
|
84
|
+
npx synapse-hub setup
|
|
85
|
+
|
|
86
|
+
# Chạy kiểm định 8 Cổng Chất Lượng (DoD Quality Gates)
|
|
87
|
+
npx synapse-hub verify
|
|
88
|
+
|
|
89
|
+
# Đánh giá sức khỏe toàn diện dự án (5-in-1 Project Health Report)
|
|
90
|
+
npx synapse-hub analyze
|
|
91
|
+
|
|
92
|
+
# Quét phát hiện mã giả, assertion rỗng (Fake-Pass AST Sentinel)
|
|
93
|
+
npx synapse-hub lint
|
|
94
|
+
```
|
|
95
|
+
> 💡 **Mẹo:** Bạn cũng có thể dùng lệnh gọi rút gọn: `npx synapse setup` hoặc `npx synapse verify`.
|
|
96
|
+
|
|
97
|
+
#### 2. Cài đặt cố định vào dự án (DevDependency):
|
|
98
|
+
```bash
|
|
99
|
+
npm install -D synapse-hub
|
|
100
|
+
```
|
|
101
|
+
Sau đó có thể khai báo vào `scripts` trong file `package.json` của dự án mục tiêu:
|
|
102
|
+
```json
|
|
103
|
+
"scripts": {
|
|
104
|
+
"qa:verify": "synapse-hub verify",
|
|
105
|
+
"qa:analyze": "synapse-hub analyze"
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
#### 3. Cài đặt toàn cục (Global CLI):
|
|
110
|
+
Để sử dụng công cụ ở bất cứ đâu trên máy tính:
|
|
111
|
+
```bash
|
|
112
|
+
npm install -g synapse-hub
|
|
113
|
+
|
|
114
|
+
# Sử dụng trực tiếp:
|
|
115
|
+
synapse-hub verify
|
|
116
|
+
synapse setup
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Cách B: Mở phiên làm việc đa thư mục (Multi-Root Workspace)
|
|
120
|
+
Trong IDE (Google Antigravity / VS Code / Cursor):
|
|
121
|
+
1. Mở thư mục dự án mục tiêu của bạn.
|
|
122
|
+
2. Thêm thư mục `Synapse-Hub` vào Workspace (`File` -> `Add Folder to Workspace...`).
|
|
123
|
+
|
|
124
|
+
### Bước 2: Khởi tạo hướng dẫn dự án (`PROJECT_AI_GUIDE.md`)
|
|
125
|
+
Copy file mẫu từ `templates/PROJECT_AI_GUIDE_TEMPLATE.md` vào thư mục gốc của dự án mục tiêu, đổi tên thành `PROJECT_AI_GUIDE.md` và điền thông tin cụ thể:
|
|
126
|
+
- URL môi trường test/staging.
|
|
127
|
+
- Tài khoản và cơ chế đăng nhập.
|
|
128
|
+
- Cấu trúc thư mục mã nguồn.
|
|
129
|
+
- Lệnh chạy test headless và công nghệ sử dụng.
|
|
130
|
+
- **Dữ liệu tra cứu nhanh:** Khai báo đường dẫn `testcases.json` và `selectors.json` (hoặc đặt biến môi trường `TC_DATA_FILE` / `XPATH_DATA_FILE`) để công cụ `tools/lookup_tc.py` và `tools/lookup_xpath.py` nạp đúng dữ liệu của dự án.
|
|
131
|
+
|
|
132
|
+
### Bước 3: Cài đặt tự động (One-Click Bootstrap)
|
|
133
|
+
Chạy script cài đặt môi trường và phụ thuộc:
|
|
134
|
+
```powershell
|
|
135
|
+
# Windows PowerShell
|
|
136
|
+
./scripts/install.ps1
|
|
137
|
+
|
|
138
|
+
# Linux / macOS
|
|
139
|
+
./scripts/setup.sh
|
|
140
|
+
```
|
|
141
|
+
Script bootstrap sẽ tự động thiết lập `.venv`, cài dependencies, chạy lint kiểm tra 30 skills, và **khởi tạo nạp seed giải pháp ban đầu** cho SQLite Central Agent Memory (`~/.agent_memory/global_cache.db`).
|
|
142
|
+
|
|
143
|
+
> 💡 **Khởi tạo SQLite Memory trên CI/CD & Docker sạch:**
|
|
144
|
+
> Trên agent runner CI hoặc container Docker mới tinh, chạy lệnh sau để cấp quyền và khởi tạo bộ nhớ 0-token:
|
|
145
|
+
> ```bash
|
|
146
|
+
> agent-qa heal init
|
|
147
|
+
> # hoặc chạy trực tiếp:
|
|
148
|
+
> python tools/cache_resolver.py init
|
|
149
|
+
> ```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 👥 3. Hệ Thống Multi-Agent Swarm (6 Vai Trò Chuyên Biệt)
|
|
154
|
+
|
|
155
|
+
Hub phân chia năng lực rõ ràng cho 6 vai trò Agent, mỗi Agent được gán sẵn các Skills và Tools tương ứng:
|
|
156
|
+
|
|
157
|
+
| Vai Trò Agent | Trách Nhiệm Cốt Lõi | Skills Được Gán | Tools Đi Kèm |
|
|
158
|
+
| :--- | :--- | :--- | :--- |
|
|
159
|
+
| **`orchestrator`** | Trưởng nhóm điều phối, bootstrap dự án, audit sức khỏe, neo state. | `agent-orchestration-multi-agent-optimize`, `graphify-impact-analyzer`, `architecture-decision-records` | `tools/setup_project.py`, `tools/analyze_project.py`, `tools/project_state.py`, `tools/repo_map.py`, `tools/test_impact.py`, `tools/mcp_server.py` |
|
|
160
|
+
| **`live-explorer`** | Thám sát live DOM/AOM qua Playwright, chặn click phá hoại. | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel`, `auth-session-and-cookie-manager` | `tools/safety_firewall.py`, `tools/lookup_xpath.py`, `tools/visual_diff_canvas.py`, `tools/browser_helpers.js` |
|
|
161
|
+
| **`pom-crafter`** | Kỹ sư Clean POM, kiểm tra API drift, sinh test từ User Story. | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator`, `api-spec-to-e2e-matrix`, `file-and-report-validator`, `db-state-verifier-and-seeder` | `tools/generate_tc_from_story.py`, `tools/generate_api_matrix.py`, `tools/api_drift_sentinel.py`, `tools/repo_map.py` |
|
|
162
|
+
| **`test-runner`** | Quản lý chạy test headless CLI, chia tải thời gian chạy trên CI. | `katalon-cli-runner`, `e2e-testing-patterns`, `bats-testing-patterns`, `auth-session-and-cookie-manager`, `flaky-test-sentinel-and-quarantine` | `tools/matrix_sharder.py`, `tools/distill_log.py`, `tools/pinpoint_failure.py`, `tools/flaky_detector.py` |
|
|
163
|
+
| **`failure-analyst`**| Tự động chẩn đoán lỗi, tính điểm tin cậy & tự tạo PR đối soát. | `failure-autopsy-and-healing`, `self-healing-locator`, `file-and-report-validator` | `tools/auto_heal.py`, `tools/heal_pr_automator.py`, `tools/pinpoint_failure.py`, `tools/cache_resolver.py` |
|
|
164
|
+
| **`quality-gatekeeper`**| Gác cổng chất lượng 7 Gates DoD, quét Fake-Pass, bơm mutant. | `antigravity-test-sentinel`, `code-refactoring-refactor-clean`, `wcag-audit-patterns`, `web-vitals-and-performance-profiler`, `db-state-verifier-and-seeder`, `security-dast-sentinel` | `tools/verify_all.py`, `tools/infer_linter.py`, `tools/micro_mutator.py`, `tools/trace_data_flow.py`, `tools/wcag_audit.py`, `tools/lint_ai_docs.py` |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 📦 4. Danh Mục 27 Kỹ Năng Chuẩn Hóa (.agents/skills/)
|
|
169
|
+
|
|
170
|
+
| STT | Tên Kỹ Năng (Skill) | Phạm Vi Hoạt Động Cốt Lõi |
|
|
171
|
+
|:---:|---|---|
|
|
172
|
+
| 1 | `agent-orchestration-multi-agent-optimize` | Tối ưu hóa điều phối multi-agent, phân bổ tải và giám sát chi phí token. |
|
|
173
|
+
| 2 | `antigravity-test-sentinel` | Gác cổng Verification-First, khóa hoàn thành task nếu test chưa pass exit code 0. |
|
|
174
|
+
| 3 | `api-network-mocking-interception` | Chặn bắt, mock lưu lượng HTTP/GraphQL và kiểm thử độ bền mạng (Chaos/Resilience). |
|
|
175
|
+
| 4 | `api-spec-to-e2e-matrix` | Phân tích OpenAPI/Swagger để sinh ma trận kiểm thử tương đương, biên và lỗi. |
|
|
176
|
+
| 5 | `architecture-decision-records` | Soạn thảo và quản lý hồ sơ quyết định kiến trúc kỹ thuật (ADR). |
|
|
177
|
+
| 6 | `auth-session-and-cookie-manager` | Quản lý phiên đăng nhập, JWT tokens, storageState cho đăng nhập 0-giây. |
|
|
178
|
+
| 7 | `backend-load-and-stress-patterns` | Kiểm thử tải và stress backend với k6 & Locust, giám sát ngưỡng SLA P95/P99. |
|
|
179
|
+
| 8 | `bats-testing-patterns` | Kiểm thử tự động Shell Scripts, CI/CD pipelines, mock binary CLI và exit code. |
|
|
180
|
+
| 9 | `clean-pom-crafter` | Chuẩn hóa Clean Page Object Model, Flat Architecture, Dynamic `uniqueCode`. |
|
|
181
|
+
| 10 | `code-refactoring-refactor-clean` | Tái cấu trúc code chuyên sâu, khử code smells, nợ kỹ thuật và chuẩn SOLID. |
|
|
182
|
+
| 11 | `db-state-verifier-and-seeder` | Kiểm tra trạng thái DB trực tiếp (PostgreSQL, MySQL, MongoDB, Redis) và seed fixture. |
|
|
183
|
+
| 12 | `e2e-testing-patterns` | Kiến trúc E2E đa trình duyệt (Playwright/Cypress), Typed POM, sharding song song. |
|
|
184
|
+
| 13 | `failure-autopsy-and-healing` | Khám nghiệm tử thi lỗi cấp vĩ mô từ JUnit XML, Allure report và ảnh chụp lỗi. |
|
|
185
|
+
| 14 | `file-and-report-validator` | Kiểm định nội dung file tải về/tải lên (Excel .xlsx, CSV stream, PDF text/layout). |
|
|
186
|
+
| 15 | `flaky-test-sentinel-and-quarantine` | Phát hiện, chấm điểm và cô lập kiểm thử chập chờn (flaky test) vào vùng cách ly. |
|
|
187
|
+
| 16 | `github-actions-templates` | Mẫu pipeline CI/CD GitHub Actions chuẩn sản xuất và sharded testing. |
|
|
188
|
+
| 17 | `graphify-impact-analyzer` | Phân tích đồ thị tri thức AST Knowledge Graph và khoanh vùng ảnh hưởng thay đổi. |
|
|
189
|
+
| 18 | `katalon-cli-runner` | Điều phối thực thi headless KRE CLI, Community mode và dọn dẹp zombie driver. |
|
|
190
|
+
| 19 | `lam-script-generator` | Large Action Model, chuyển đổi User Story sang 100% test script không token replay. |
|
|
191
|
+
| 20 | `playwright-live-interaction` | Thám sát trực tiếp live DOM/AOM qua Playwright MCP, kiểm tra hit-rate < 200ms. |
|
|
192
|
+
| 21 | `security-dast-sentinel` | Kiểm thử bảo mật động DAST, rà soát OWASP Top 10, HTTP Headers, BOLA/IDOR. |
|
|
193
|
+
| 22 | `self-healing-locator` | Tự phục hồi locator vi mô bằng cây Semantic Accessibility (AOM), Role > Label > TestId. |
|
|
194
|
+
| 23 | `synthetic-test-data-generator` | Tự động sinh dữ liệu kiểm thử biên (BVT), chống SQLi/XSS, đa ngôn ngữ, tọa độ GIS. |
|
|
195
|
+
| 24 | `token-and-context-optimizer` | Tối ưu token, lọc log rác, chống suy thoái ngữ cảnh (Lost-in-the-Middle) và scratchpad đĩa. |
|
|
196
|
+
| 25 | `visual-regression-sentinel` | So sánh giao diện mức pixel và SSIM, hỗ trợ dynamic masking chống flaky test. |
|
|
197
|
+
| 26 | `wcag-audit-patterns` | Kiểm toán tiếp cận web WCAG 2.2 Level A/AA tự động qua AST và `@axe-core`. |
|
|
198
|
+
| 27 | `web-vitals-and-performance-profiler` | Đo lường Core Web Vitals (LCP, CLS, TTFB) và giám sát API endpoint chậm qua CDP. |
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## 📜 5. Danh Mục 7 Quy Tắc Cốt Lõi (.agents/rules/)
|
|
203
|
+
|
|
204
|
+
1. **`context-engineering.md`**: Giao thức lọc log thừa (Observation Masking), khai báo lười (Lazy Loading) và tối ưu hóa KV-Cache.
|
|
205
|
+
2. **`git-push-protocol.md`**: Giao thức Git Push chuẩn hóa cho dự án mục tiêu (Clean SCM by Architecture, loại bỏ hoàn toàn nhu cầu dual-remote/smart-push nhờ tách repo độc lập).
|
|
206
|
+
3. **`graphify.md`**: Điều hướng đồ thị tri thức mã nguồn AST thay vì đọc toàn văn mã nguồn lớn.
|
|
207
|
+
4. **`lessons-learned.md`**: Danh sách bài học kinh nghiệm và anti-patterns (giới hạn cứng < 40 dòng).
|
|
208
|
+
5. **`mandatory-playwright-live.md`**: Quy chuẩn chạy headless Full HD 1920x1080 và khảo sát live DOM trước khi codify.
|
|
209
|
+
6. **`skill-precedence.md`**: Thứ tự ưu tiên kỹ năng cục bộ, chống xung đột trigger với plugin bên ngoài.
|
|
210
|
+
7. **`systematic-debugging.md`**: Kỷ luật điều tra lỗi có căn cứ, cấm đoán mò và verify-first (7 Quality Gates).
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 🛠️ 6. Sổ Tay Công Cụ Tự Động Hóa (tools/ & scripts/)
|
|
215
|
+
|
|
216
|
+
Chi tiết đầy đủ xem tại [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md):
|
|
217
|
+
|
|
218
|
+
- `tools/verify_all.py`: Cổng thẩm định 7 Gates DoD (UTF-8, No XPaths, UniqueCode, Clean POM).
|
|
219
|
+
- `tools/infer_linter.py`: Phân tích tĩnh AST phát hiện fake-pass (0 assertion) và khối try-catch nuốt lỗi.
|
|
220
|
+
- `tools/test_impact.py`: Phân tích git diff và khoanh vùng chính xác test cases bị ảnh hưởng.
|
|
221
|
+
- `tools/cache_resolver.py`: Quản lý bộ nhớ đệm lỗi SQLite trung tâm (`~/.agent_memory/global_cache.db`).
|
|
222
|
+
- `tools/distill_log.py`: Lọc bỏ 95% log thừa từ CLI/Gradle/KRE, giữ lại stacktrace và file pointer.
|
|
223
|
+
- `tools/agent_canary.py`: Hệ thống tiêm 8 vector lỗi tự động đánh giá sức phục hồi của Agent (MTTR).
|
|
224
|
+
- `tools/repo_map.py`: Trích xuất bản đồ cấu trúc hàm và Page Class siêu nén (~500 tokens).
|
|
225
|
+
- `tools/visual_diff_canvas.py`: So sánh pixel/SSIM cho màn hình GIS/Canvas không có DOM.
|
|
226
|
+
- `tools/wcag_audit.py`: Quét kiểm toán tự động các tiêu chí tiếp cận WCAG 2.2 Level A/AA.
|
|
227
|
+
- `tools/generate_api_matrix.py`: Tự động sinh ma trận kiểm thử Positive/Boundary/Negative từ Swagger.
|
|
228
|
+
- `tools/generate_tc_from_story.py`: Large Action Model parser sinh khung Clean POM từ User Story.
|
|
229
|
+
- `tools/trace_data_flow.py`: Kiểm tra luồng dữ liệu kiểm thử, phát hiện rác dữ liệu DB (Orphan Data).
|
|
230
|
+
- `scripts/install.ps1` & `scripts/setup.sh`: Script cài đặt 1-click tự động khởi tạo môi trường Hub.
|
|
231
|
+
- `scripts/lint_skills.ps1`: Linter kiểm tra tính toàn vẹn 30 skills và metadata manifest.
|
|
232
|
+
- `pyproject.toml` & `tools/cli.py`: Đóng gói chuẩn PEP 621 cho lệnh CLI toàn cầu `agent-qa`.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## 📚 7. Tài Liệu Kỹ Thuật Mở Rộng & CLI Package (docs/)
|
|
237
|
+
|
|
238
|
+
1. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Kiến trúc Hub/Spoke, mô hình 4 tầng kỹ năng, và ma trận phối hợp 6 Subagent Swarm.
|
|
239
|
+
2. **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)**: Quy chuẩn đóng góp, nguyên tắc sáng tạo skill mới và quy trình kiểm định toàn vẹn.
|
|
240
|
+
3. **[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)**: Cẩm nang tra cứu toàn bộ tham số lệnh của công cụ dòng lệnh `agent-qa`.
|
|
241
|
+
|
|
242
|
+
### Cài đặt nhanh CLI Package:
|
|
243
|
+
```bash
|
|
244
|
+
pip install -e .
|
|
245
|
+
agent-qa --help
|
|
246
|
+
agent-qa verify
|
|
247
|
+
agent-qa lint
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## 🤝 8. Nguồn Cảm Hứng & Lời Cảm Ơn (Acknowledgments & Inspirations)
|
|
253
|
+
|
|
254
|
+
Dự án **Synapse Hub** được tổng hợp, kế thừa và phát triển dựa trên tinh thần mã nguồn mở và những ý tưởng đột phá từ các kho lưu trữ xuất sắc của cộng đồng kỹ nghệ phần mềm & AI:
|
|
255
|
+
|
|
256
|
+
| Dự án & Tác giả | Nguồn cảm hứng & Đóng góp kiến trúc trong Synapse Hub |
|
|
257
|
+
| :--- | :--- |
|
|
258
|
+
| **[muratcankoylan/Agent-Skills-for-Context-Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)** | Nguyên lý Context Engineering, Observation Masking và kỹ thuật tối ưu hóa sự chú ý của LLM. |
|
|
259
|
+
| **[alexgreensh/token-optimizer](https://github.com/alexgreensh/token-optimizer)** | Cơ chế cô đọng log CLI/Gradle (95% distillation) và tối ưu hóa KV-Cache. |
|
|
260
|
+
| **[obra/superpowers](https://github.com/obra/superpowers)** *(Jesse Vincent)* | Kỷ luật gỡ lỗi dựa trên bằng chứng (Systematic Debugging), Cognitive Forcing và cơ chế Red-Team vs Blue-Team. |
|
|
261
|
+
| **[Aider-AI/aider](https://github.com/Aider-AI/aider)** *(Paul Gauthier)* | Kỹ thuật trích xuất AST bản đồ mã nguồn thu gọn (`tools/repo_map.py`) dưới 600 tokens. |
|
|
262
|
+
| **[lavague-ai/LaVague](https://github.com/lavague-ai/LaVague)** | Mô hình Large Action Model (LAM), tự động biên dịch User Story thành kịch bản kiểm thử Clean POM. |
|
|
263
|
+
| **[facebook/infer](https://github.com/facebook/infer)** *(Meta Infer)* | Linter phân tích tĩnh AST (`tools/infer_linter.py`) phát hiện test giả lập (Fake-Pass) và try-catch nuốt lỗi. |
|
|
264
|
+
| **[microsoft/playwright](https://github.com/microsoft/playwright)** | Tương tác live DOM/AOM sub-200ms, điều hướng headless và mô phỏng network resilience. |
|
|
265
|
+
| **[dequelabs/axe-core](https://github.com/dequelabs/axe-core)** | Quy chuẩn kiểm toán tự động các tiêu chí khả năng tiếp cận WCAG 2.2 Level A/AA. |
|
|
266
|
+
| **[bats-core/bats-core](https://github.com/bats-core/bats-core)** | Chuẩn kiểm thử tự động Bash Automated Testing System cho kịch bản shell/CLI. |
|
|
267
|
+
| **[npryce/adr-tools](https://github.com/npryce/adr-tools)** | Quy chuẩn ghi nhận và lưu vết quyết định kiến trúc phần mềm (ADRs). |
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
# 🌐 English Edition
|
|
272
|
+
|
|
273
|
+
# 🧠 Synapse Hub — AI Agent Intelligence Core & Skill Network
|
|
274
|
+
|
|
275
|
+
> **The shared intelligence core and autonomous skill hub empowering AI coding assistants (Google Antigravity / Cursor / Windsurf / Claude Code) across automated testing suites.**
|
|
276
|
+
> **Author:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))
|
|
277
|
+
> **Hub Version:** `v2.0.1` (Semantic Versioning) | **Integrity Index:** 27 Skills, 6 Agent Swarm Roles, 7 Core Rules, 20+ Python Tools.
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## 🌟 1. Overview & Architectural Purpose
|
|
282
|
+
|
|
283
|
+
**Synapse Hub** serves as a **Decoupled Shared Intelligence Core**, acting as an external neural brain completely isolated from target projects' codebases. It equips AI agents with specialized swarm roles, self-healing execution protocols, AST-level code intelligence, and strict Quality Gates—enabling zero-leakage, truth-anchored test automation across any polyglot codebase without polluting target repositories.
|
|
284
|
+
|
|
285
|
+
```mermaid
|
|
286
|
+
flowchart TD
|
|
287
|
+
subgraph Hub["🧠 Synapse Hub (Intelligence Core v2.0.1)"]
|
|
288
|
+
Skills[".agents/skills/ (27 Skills)"]
|
|
289
|
+
Agents[".agents/agents/ (6 Specialized Roles)"]
|
|
290
|
+
Rules[".agents/rules/ (7 Core Rules)"]
|
|
291
|
+
Tools["tools/ (20+ Universal Python Tools)"]
|
|
292
|
+
Workflows[".agents/workflows/"]
|
|
293
|
+
end
|
|
294
|
+
|
|
295
|
+
subgraph ChatSession["💬 AI Agent Workspace / Chat Session"]
|
|
296
|
+
Hub -->|Mount/Add Workspace| ChatSession
|
|
297
|
+
end
|
|
298
|
+
|
|
299
|
+
subgraph Projects["📁 Target Projects"]
|
|
300
|
+
ProjectA["Project A<br/>(PROJECT_AI_GUIDE.md + Source Code)"]
|
|
301
|
+
ProjectB["Project B<br/>(PROJECT_AI_GUIDE.md + Test Code)"]
|
|
302
|
+
ProjectC["Project C<br/>(PROJECT_AI_GUIDE.md + App Code)"]
|
|
303
|
+
Other["Other Projects..."]
|
|
304
|
+
end
|
|
305
|
+
|
|
306
|
+
ProjectA -->|Mount Workspace| ChatSession
|
|
307
|
+
ProjectB -.->|Mount Workspace| ChatSession
|
|
308
|
+
ProjectC -.->|Mount Workspace| ChatSession
|
|
309
|
+
Other -.->|Mount Workspace| ChatSession
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
### 💎 Breakthrough Architectural Benefits:
|
|
313
|
+
|
|
314
|
+
#### 1. 🧠 Deep System-2 Reasoning & Cognitive Forcing
|
|
315
|
+
* **Eliminates "Unconscious Autocomplete":** When diagnosing failures or generating tests, the AI agent is strictly barred from speculative guesswork and **forced through a 4-step System-2 reasoning pipeline**:
|
|
316
|
+
1. *Boundary & Invariant Extraction:* What must never happen under any circumstance?
|
|
317
|
+
2. *Popper Falsification Hypotheses:* Formulate 3 distinct code mutation scenarios where a naive test passes while the software is broken (False Negatives).
|
|
318
|
+
3. *Self-Debate:* Formulate concrete proof showing why the prospective assertion will definitively catch all 3 defect vectors.
|
|
319
|
+
4. *Defensive Code Synthesis:* Emit code only after passing all 3 analytical gates.
|
|
320
|
+
* **Adversarial Red-Team vs. Blue-Team Self-Play:** Automatically injects AST micro-mutants (`tools/micro_mutator.py`) into test suites to verify fault detection power, requiring **Mutation Score $\ge 80\%$** before task approval.
|
|
321
|
+
|
|
322
|
+
#### 2. ⚡ Radical Token Optimization (85% – 95% Context Cost Reduction)
|
|
323
|
+
* **Log Distillation (95% Token Savings):** `tools/distill_log.py` automatically purges 95% of verbose CLI/Gradle/Playwright stdout, preserving only ~10 lines of root-cause exceptions and pointers (< 50 tokens) instead of dumping 3,000 noise lines.
|
|
324
|
+
* **AST Repo Mapping (90% Code Reading Savings):** `tools/repo_map.py` compresses 500+ method signatures into a clean AST map (< 600 tokens). Agents discover classes and helpers without ever reading 4,000-line source files (preventing "Context Window Blowouts").
|
|
325
|
+
* **Compact AOM (90% HTML Savings):** Replaces raw 50,000-line HTML DOM dumps with compact Accessible Object Model (AOM) subtrees (< 500 tokens).
|
|
326
|
+
* **Zero-Token Episodic SQLite Memory:** Errors and healing patches are recorded and resolved offline in `~/.agent_memory/global_cache.db` via cosine similarity at **0 context tokens**.
|
|
327
|
+
* **Anti-Degradation ("Context Rot" & "Lost-in-the-Middle"):** Preserves model reasoning sharpness and prevents hallucinations even during long sessions exceeding 100,000 tokens.
|
|
328
|
+
|
|
329
|
+
#### 3. 📊 Quantitative Performance Benchmark:
|
|
330
|
+
|
|
331
|
+
| Evaluation Metric | Naive AI Coding Prompting | With Synapse Hub 🧠 |
|
|
332
|
+
| :--- | :---: | :---: |
|
|
333
|
+
| **Tokens Consumed per Bug Fix** | 15,000 – 40,000 tokens *(dumps entire classes & logs)* | **300 – 800 tokens (> 90% Savings)** |
|
|
334
|
+
| **Fake-Pass Rate (0 asserts, false passes)** | 30% – 50% *(LLMs tend to relax asserts)* | **0% (Locked by Truth Anchor & 8 DoD Gates)** |
|
|
335
|
+
| **Cross-Session Fix Memory** | 100% forgotten upon new chat session | **Persistent via SQLite Central Cache (0 token)** |
|
|
336
|
+
| **Context Rot / Lost-in-the-Middle** | High degradation after 40k – 60k tokens | **Immune via 3-Tier Progressive Disclosure** |
|
|
337
|
+
| **Mean Time-to-Heal (MTTR)** | 5 – 15 minutes of trial-and-error | **< 1 second (Direct cache resolution)** |
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## 🚀 2. Getting Started & Usage (NPM / npx & Workspace Mount)
|
|
342
|
+
|
|
343
|
+
[](https://www.npmjs.com/package/synapse-hub)
|
|
344
|
+
[](https://www.npmjs.com/package/synapse-hub)
|
|
345
|
+
[](https://github.com/TeeVee998/Synapse-Hub/blob/main/package.json)
|
|
346
|
+
|
|
347
|
+
### Method A: Instant Execution via NPM Registry (Recommended)
|
|
348
|
+
The package is officially published at **[npmjs.com/package/synapse-hub](https://www.npmjs.com/package/synapse-hub)**. Execute directly without cloning:
|
|
349
|
+
|
|
350
|
+
#### 1. Zero-Install Execution (`npx`):
|
|
351
|
+
Run from any target project directory:
|
|
352
|
+
```bash
|
|
353
|
+
# 1-Click Project Bootstrap (generates PROJECT_AI_GUIDE.md, installs pre-push hook, extracts AST repo map)
|
|
354
|
+
npx synapse-hub setup
|
|
355
|
+
|
|
356
|
+
# Run 8 Quality Gates DoD Verification
|
|
357
|
+
npx synapse-hub verify
|
|
358
|
+
|
|
359
|
+
# Comprehensive 5-in-1 Project Health Audit
|
|
360
|
+
npx synapse-hub analyze
|
|
361
|
+
|
|
362
|
+
# Static Defect & Fake-Pass Sentinel scan
|
|
363
|
+
npx synapse-hub lint
|
|
364
|
+
```
|
|
365
|
+
> 💡 **Tip:** You can also use the shorthand alias: `npx synapse setup` or `npx synapse verify`.
|
|
366
|
+
|
|
367
|
+
#### 2. Project-Local Installation (DevDependency):
|
|
368
|
+
```bash
|
|
369
|
+
npm install -D synapse-hub
|
|
370
|
+
```
|
|
371
|
+
Configure custom lifecycle scripts in your target project's `package.json`:
|
|
372
|
+
```json
|
|
373
|
+
"scripts": {
|
|
374
|
+
"qa:verify": "synapse-hub verify",
|
|
375
|
+
"qa:analyze": "synapse-hub analyze"
|
|
376
|
+
}
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
#### 3. Global CLI Installation:
|
|
380
|
+
To use `synapse-hub` anywhere on your terminal:
|
|
381
|
+
```bash
|
|
382
|
+
npm install -g synapse-hub
|
|
383
|
+
|
|
384
|
+
# Direct invocation:
|
|
385
|
+
synapse-hub verify
|
|
386
|
+
synapse setup
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### Method B: Multi-Root Workspace Mounting
|
|
390
|
+
Within your AI IDE (Google Antigravity / VS Code / Cursor):
|
|
391
|
+
1. Open your target project folder.
|
|
392
|
+
2. Add the `Synapse-Hub` directory to your workspace (`File` -> `Add Folder to Workspace...`).
|
|
393
|
+
|
|
394
|
+
### Step 2: Initialize Project AI Guide (`PROJECT_AI_GUIDE.md`)
|
|
395
|
+
Copy `templates/PROJECT_AI_GUIDE_TEMPLATE.md` to target project root, rename to `PROJECT_AI_GUIDE.md`, and configure:
|
|
396
|
+
- Test/staging environment URLs.
|
|
397
|
+
- Credentials and authentication strategies.
|
|
398
|
+
- Source code directory structure.
|
|
399
|
+
- Headless execution commands and technology stack.
|
|
400
|
+
- **Fast-Lookup Registers:** Point `testcases.json` and `selectors.json` (or set `TC_DATA_FILE` / `XPATH_DATA_FILE` env vars) for instant zero-token query via `tools/lookup_tc.py` and `tools/lookup_xpath.py`.
|
|
401
|
+
|
|
402
|
+
### Step 3: One-Click Environment Bootstrap
|
|
403
|
+
Execute the automated bootstrap script:
|
|
404
|
+
```powershell
|
|
405
|
+
# Windows PowerShell
|
|
406
|
+
./scripts/install.ps1
|
|
407
|
+
|
|
408
|
+
# Linux / macOS
|
|
409
|
+
./scripts/setup.sh
|
|
410
|
+
```
|
|
411
|
+
The bootstrap script automatically configures `.venv`, installs dependencies, lints skills, and seeds initial solutions into the Central SQLite Agent Memory (`~/.agent_memory/global_cache.db`).
|
|
412
|
+
|
|
413
|
+
> 💡 **Initializing SQLite Memory on Clean CI/CD & Docker:**
|
|
414
|
+
> In fresh CI runners or Docker containers, initialize zero-token memory cache via:
|
|
415
|
+
> ```bash
|
|
416
|
+
> agent-qa heal init
|
|
417
|
+
> # or run directly:
|
|
418
|
+
> python tools/cache_resolver.py init
|
|
419
|
+
> ```
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## 👥 3. Multi-Agent Swarm System (6 Specialized Roles)
|
|
424
|
+
|
|
425
|
+
Synapse Hub clearly partitions capabilities across 6 specialized AI roles, pre-configured with dedicated skills and tools:
|
|
426
|
+
|
|
427
|
+
| Agent Role | Core Responsibility | Assigned Skills | Included Tools |
|
|
428
|
+
| :--- | :--- | :--- | :--- |
|
|
429
|
+
| **`orchestrator`** | Lead coordinator, project bootstrapping, health auditing, state anchoring. | `agent-orchestration-multi-agent-optimize`, `graphify-impact-analyzer`, `architecture-decision-records` | `tools/setup_project.py`, `tools/analyze_project.py`, `tools/project_state.py`, `tools/repo_map.py`, `tools/test_impact.py`, `tools/mcp_server.py` |
|
|
430
|
+
| **`live-explorer`** | Live DOM/AOM probing via Playwright MCP, destructive click firewall. | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel`, `auth-session-and-cookie-manager` | `tools/safety_firewall.py`, `tools/lookup_xpath.py`, `tools/visual_diff_canvas.py`, `tools/browser_helpers.js` |
|
|
431
|
+
| **`pom-crafter`** | Clean POM engineer, API drift detection, User Story to test generation. | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator`, `api-spec-to-e2e-matrix`, `file-and-report-validator`, `db-state-verifier-and-seeder` | `tools/generate_tc_from_story.py`, `tools/generate_api_matrix.py`, `tools/api_drift_sentinel.py`, `tools/repo_map.py` |
|
|
432
|
+
| **`test-runner`** | Headless CLI suite manager, CI parallel sharding and log distillation. | `katalon-cli-runner`, `e2e-testing-patterns`, `bats-testing-patterns`, `auth-session-and-cookie-manager`, `flaky-test-sentinel-and-quarantine` | `tools/matrix_sharder.py`, `tools/distill_log.py`, `tools/pinpoint_failure.py`, `tools/flaky_detector.py` |
|
|
433
|
+
| **`failure-analyst`**| Automated closed-loop failure triage, MTTR scoring, self-healing PR drafting. | `failure-autopsy-and-healing`, `self-healing-locator`, `file-and-report-validator` | `tools/auto_heal.py`, `tools/heal_pr_automator.py`, `tools/pinpoint_failure.py`, `tools/cache_resolver.py` |
|
|
434
|
+
| **`quality-gatekeeper`**| Enforces 8 Quality Gates DoD, scans fake passes, runs AST mutation testing. | `antigravity-test-sentinel`, `code-refactoring-refactor-clean`, `wcag-audit-patterns`, `web-vitals-and-performance-profiler`, `db-state-verifier-and-seeder`, `security-dast-sentinel` | `tools/verify_all.py`, `tools/infer_linter.py`, `tools/micro_mutator.py`, `tools/trace_data_flow.py`, `tools/wcag_audit.py`, `tools/lint_ai_docs.py` |
|
|
435
|
+
|
|
436
|
+
---
|
|
437
|
+
|
|
438
|
+
## 📦 4. Standardized 27 Skills Catalog (.agents/skills/)
|
|
439
|
+
|
|
440
|
+
| # | Skill Name | Core Operational Scope |
|
|
441
|
+
|:---:|---|---|
|
|
442
|
+
| 1 | `agent-orchestration-multi-agent-optimize` | Multi-agent coordination profiling, workload distribution, and token cost budgeting. |
|
|
443
|
+
| 2 | `antigravity-test-sentinel` | Verification-First sentinel, locking task completion until exit code 0 is proven. |
|
|
444
|
+
| 3 | `api-network-mocking-interception` | HTTP/GraphQL request interception, route stubbing, and chaos network resilience testing. |
|
|
445
|
+
| 4 | `api-spec-to-e2e-matrix` | Transforms OpenAPI/Swagger specifications into equivalence, boundary, and error test matrices. |
|
|
446
|
+
| 5 | `architecture-decision-records` | Documents and maintains technical Architecture Decision Records (ADR). |
|
|
447
|
+
| 6 | `auth-session-and-cookie-manager` | Manages sessions, JWT tokens, and storageState for zero-second authentications. |
|
|
448
|
+
| 7 | `backend-load-and-stress-patterns` | Backend load/stress testing via k6 & Locust with P95/P99 SLA threshold assertions. |
|
|
449
|
+
| 8 | `bats-testing-patterns` | Automated testing for Shell scripts, CI/CD pipelines, CLI mocks, and exit codes. |
|
|
450
|
+
| 9 | `clean-pom-crafter` | Clean Page Object Model standards, Flat Architecture, and dynamic `uniqueCode` test data. |
|
|
451
|
+
| 10 | `code-refactoring-refactor-clean` | Clean code refactoring, code smells elimination, technical debt remediation, and SOLID. |
|
|
452
|
+
| 11 | `db-state-verifier-and-seeder` | Direct DB state assertions (PostgreSQL, MySQL, MongoDB, Redis) and isolated fixtures. |
|
|
453
|
+
| 12 | `e2e-testing-patterns` | Multi-browser E2E testing architecture (Playwright/Cypress), Typed POM, parallel sharding. |
|
|
454
|
+
| 13 | `failure-autopsy-and-healing` | Automated failure triage from JUnit XML, Allure reports, and visual error screenshots. |
|
|
455
|
+
| 14 | `file-and-report-validator` | Verifies uploaded/downloaded files (Excel .xlsx, streaming CSV, PDF text/layout). |
|
|
456
|
+
| 15 | `flaky-test-sentinel-and-quarantine` | Flaky test detection, flakiness index scoring, and quarantine isolation governance. |
|
|
457
|
+
| 16 | `github-actions-templates` | Production-ready GitHub Actions CI/CD workflows and sharded testing matrix. |
|
|
458
|
+
| 17 | `graphify-impact-analyzer` | AST Knowledge Graph navigation and zero-waste test impact analysis. |
|
|
459
|
+
| 18 | `katalon-cli-runner` | Headless KRE CLI execution coordinator, licensing fallback, and zombie driver cleanup. |
|
|
460
|
+
| 19 | `lam-script-generator` | Large Action Model generator compiling User Stories into 100% test scripts with zero replay. |
|
|
461
|
+
| 20 | `playwright-live-interaction` | Real-time DOM/AOM probing via Playwright MCP with sub-200ms selector verification. |
|
|
462
|
+
| 21 | `security-dast-sentinel` | Dynamic Application Security Testing (DAST), OWASP Top 10, Security Headers, BOLA/IDOR. |
|
|
463
|
+
| 22 | `self-healing-locator` | Micro-locator self-healing via Accessibility Tree (AOM), Role > Label > TestId hierarchy. |
|
|
464
|
+
| 23 | `synthetic-test-data-generator` | Robust synthetic boundary test data generation (BVT, anti-injection, multilingual, GIS). |
|
|
465
|
+
| 24 | `token-and-context-optimizer` | Context engineering, 95% log distillation, anti-degradation, and disk scratchpads. |
|
|
466
|
+
| 25 | `visual-regression-sentinel` | Pixel-level and SSIM visual regression testing with dynamic masking. |
|
|
467
|
+
| 26 | `wcag-audit-patterns` | Automated WCAG 2.2 Level A/AA accessibility auditing via AST and `@axe-core`. |
|
|
468
|
+
| 27 | `web-vitals-and-performance-profiler` | Core Web Vitals (LCP, CLS, TTFB) profiling and slow API endpoint detection via CDP. |
|
|
469
|
+
|
|
470
|
+
---
|
|
471
|
+
|
|
472
|
+
## 📜 5. 7 Core Rules Catalog (.agents/rules/)
|
|
473
|
+
|
|
474
|
+
1. **`context-engineering.md`**: Observation masking, lazy progressive disclosure, and KV-cache optimization.
|
|
475
|
+
2. **`git-push-protocol.md`**: Clean git push protocol (decoupled architecture guarantees zero AI leakage).
|
|
476
|
+
3. **`graphify.md`**: Navigating the AST knowledge graph over reading entire large source files.
|
|
477
|
+
4. **`lessons-learned.md`**: Episodic anti-pattern blacklist (strictly capped under 40 lines).
|
|
478
|
+
5. **`mandatory-playwright-live.md`**: Mandatory headless Full HD 1920x1080 and live DOM probing before codifying.
|
|
479
|
+
6. **`skill-precedence.md`**: Tier-1 local skill precedence resolving external plugin collisions.
|
|
480
|
+
7. **`systematic-debugging.md`**: Evidence-first debugging discipline; zero guessing; 8 Quality Gates DoD.
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## 🛠️ 6. Automated Tools Runbook (tools/ & scripts/)
|
|
485
|
+
|
|
486
|
+
For full details, refer to [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md):
|
|
487
|
+
|
|
488
|
+
- `tools/verify_all.py`: 8 Quality Gates DoD verification (UTF-8, No XPaths, UniqueCode, Clean POM).
|
|
489
|
+
- `tools/infer_linter.py`: Static AST analysis detecting fake passes (zero asserts) and empty catch blocks.
|
|
490
|
+
- `tools/test_impact.py`: Scopes affected test cases based on git diffs.
|
|
491
|
+
- `tools/cache_resolver.py`: Manages the central SQLite error memory cache (`~/.agent_memory/global_cache.db`).
|
|
492
|
+
- `tools/distill_log.py`: Filters 95% noise from CLI/Gradle/KRE logs, preserving stacktraces and pointers.
|
|
493
|
+
- `tools/agent_canary.py`: Injects 8 failure vectors to benchmark MTTR and autonomous recovery rate.
|
|
494
|
+
- `tools/repo_map.py`: Extracts a compressed method and Page Class map (~500 tokens).
|
|
495
|
+
- `tools/visual_diff_canvas.py`: Pixel/SSIM comparison for canvas/GIS interfaces lacking standard DOM.
|
|
496
|
+
- `tools/wcag_audit.py`: Automated scanning for WCAG 2.2 Level A/AA criteria.
|
|
497
|
+
- `tools/generate_api_matrix.py`: Generates positive, boundary, and negative test matrices from Swagger/OpenAPI.
|
|
498
|
+
- `tools/generate_tc_from_story.py`: Large Action Model parser generating Clean POM skeletons from stories.
|
|
499
|
+
- `tools/trace_data_flow.py`: Taint analysis tracking test data flow and preventing database orphan junk.
|
|
500
|
+
- `scripts/install.ps1` & `scripts/setup.sh`: 1-click bootstrap scripts setting up the hub environment.
|
|
501
|
+
- `scripts/lint_skills.ps1`: Linter verifying skill integrity and metadata manifest.
|
|
502
|
+
- `pyproject.toml` & `tools/cli.py`: PEP 621 packaging for the global `agent-qa` CLI.
|
|
503
|
+
|
|
504
|
+
---
|
|
505
|
+
|
|
506
|
+
## 📚 7. Extended Technical Documentation & CLI Package (docs/)
|
|
507
|
+
|
|
508
|
+
1. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Hub/Spoke architecture, 4-tier skill model, and 6-agent swarm coordination.
|
|
509
|
+
2. **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)**: Contribution standards, new skill authoring principles, and verification pipelines.
|
|
510
|
+
3. **[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)**: Comprehensive command-line reference for the `agent-qa` CLI.
|
|
511
|
+
|
|
512
|
+
### Quick CLI Installation:
|
|
513
|
+
```bash
|
|
514
|
+
pip install -e .
|
|
515
|
+
agent-qa --help
|
|
516
|
+
agent-qa verify
|
|
517
|
+
agent-qa lint
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
---
|
|
521
|
+
|
|
522
|
+
## 🤝 8. Acknowledgments & Upstream Inspirations
|
|
523
|
+
|
|
524
|
+
**Synapse Hub** synthesizes, adapts, and builds upon groundbreaking methodologies and architectures from the global open-source and AI engineering community:
|
|
525
|
+
|
|
526
|
+
| Project & Author | Architectural Inspiration in Synapse Hub |
|
|
527
|
+
| :--- | :--- |
|
|
528
|
+
| **[muratcankoylan/Agent-Skills-for-Context-Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)** | Context Engineering foundations, observation masking, and LLM attention budget optimization. |
|
|
529
|
+
| **[alexgreensh/token-optimizer](https://github.com/alexgreensh/token-optimizer)** | Token-efficient reasoning, 95% log distillation, and KV-cache serialization protocols. |
|
|
530
|
+
| **[obra/superpowers](https://github.com/obra/superpowers)** *(Jesse Vincent)* | Systematic evidence-based debugging, cognitive forcing functions, and Red-Team vs Blue-Team verification. |
|
|
531
|
+
| **[Aider-AI/aider](https://github.com/Aider-AI/aider)** *(Paul Gauthier)* | Ultra-compact AST repository mapping algorithm (`tools/repo_map.py`) fitting 500+ signatures in < 600 tokens. |
|
|
532
|
+
| **[lavague-ai/LaVague](https://github.com/lavague-ai/LaVague)** | Large Action Model (LAM) concept compiling natural language stories into deterministic Clean POM scripts. |
|
|
533
|
+
| **[facebook/infer](https://github.com/facebook/infer)** *(Meta Infer)* | Static AST defect sentinel (`tools/infer_linter.py`) catching swallowed exceptions and 0-assertion fake passes. |
|
|
534
|
+
| **[microsoft/playwright](https://github.com/microsoft/playwright)** | Sub-200ms headless live DOM/AOM probing, route stubbing, and anti-flake network shielding. |
|
|
535
|
+
| **[dequelabs/axe-core](https://github.com/dequelabs/axe-core)** | Automated accessibility rule heuristics inspiring WCAG 2.2 Level A/AA AST auditing. |
|
|
536
|
+
| **[bats-core/bats-core](https://github.com/bats-core/bats-core)** | Bash Automated Testing System patterns for CI/CD pipelines and cross-platform CLI verification. |
|
|
537
|
+
| **[npryce/adr-tools](https://github.com/npryce/adr-tools)** | Architecture Decision Record (ADR) conventions and lifecycle workflows. |
|
|
2
538
|
|
|
3
|
-
This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
|
package/bin/agent-qa.js
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Enterprise Synapse-Hub NPM Launcher
|
|
4
|
+
* ====================================
|
|
5
|
+
* Dispatches CLI subcommands to the underlying Python Standard Library engine (tools/cli.py).
|
|
6
|
+
* Provides cross-platform zero-install execution via `npx synapse-hub <command>`.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const { spawn, execSync } = require('child_process');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
const fs = require('fs');
|
|
12
|
+
|
|
13
|
+
const REPO_ROOT = path.resolve(__dirname, '..');
|
|
14
|
+
const CLI_PATH = path.join(REPO_ROOT, 'tools', 'cli.py');
|
|
15
|
+
|
|
16
|
+
// ANSI Color Helpers
|
|
17
|
+
const RED = '\x1b[91m';
|
|
18
|
+
const GREEN = '\x1b[92m';
|
|
19
|
+
const YELLOW = '\x1b[93m';
|
|
20
|
+
const CYAN = '\x1b[96m';
|
|
21
|
+
const BOLD = '\x1b[1m';
|
|
22
|
+
const RESET = '\x1b[0m';
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Resolves the available Python 3 executable across Windows, macOS, and Linux.
|
|
26
|
+
*/
|
|
27
|
+
function resolvePython() {
|
|
28
|
+
const candidates = process.platform === 'win32'
|
|
29
|
+
? ['python', 'py', 'python3']
|
|
30
|
+
: ['python3', 'python'];
|
|
31
|
+
|
|
32
|
+
for (const cmd of candidates) {
|
|
33
|
+
try {
|
|
34
|
+
const output = execSync(`${cmd} --version`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
|
|
35
|
+
const match = output.match(/Python\s+(\d+)\.(\d+)/i);
|
|
36
|
+
if (match) {
|
|
37
|
+
const major = parseInt(match[1], 10);
|
|
38
|
+
const minor = parseInt(match[2], 10);
|
|
39
|
+
if (major > 3 || (major === 3 && minor >= 9)) {
|
|
40
|
+
return { command: cmd, version: output };
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
} catch (e) {
|
|
44
|
+
// Continue checking next candidate
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function main() {
|
|
51
|
+
const python = resolvePython();
|
|
52
|
+
|
|
53
|
+
if (!python) {
|
|
54
|
+
console.error(`\n${BOLD}${RED}[ERROR] Python 3.9+ is required to execute synapse-hub tools.${RESET}`);
|
|
55
|
+
console.error(`Neither ${CYAN}python3${RESET} nor ${CYAN}python${RESET} (>= 3.9) was found on your PATH.`);
|
|
56
|
+
console.error(`👉 Please install Python from: ${BOLD}https://www.python.org/downloads/${RESET}\n`);
|
|
57
|
+
process.exit(1);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
if (!fs.existsSync(CLI_PATH)) {
|
|
61
|
+
console.error(`\n${BOLD}${RED}[ERROR] Core CLI engine not found at: ${CLI_PATH}${RESET}\n`);
|
|
62
|
+
process.exit(1);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const args = [CLI_PATH, ...process.argv.slice(2)];
|
|
66
|
+
|
|
67
|
+
// Spawn child Python process inheriting standard IO
|
|
68
|
+
const child = spawn(python.command, args, {
|
|
69
|
+
stdio: 'inherit',
|
|
70
|
+
env: { ...process.env, AGENT_QA_INVOKER: 'npm' }
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
child.on('error', (err) => {
|
|
74
|
+
console.error(`\n${BOLD}${RED}[ERROR] Failed to start synapse-hub CLI:${RESET}`, err.message);
|
|
75
|
+
process.exit(1);
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
child.on('exit', (code, signal) => {
|
|
79
|
+
if (signal) {
|
|
80
|
+
process.kill(process.pid, signal);
|
|
81
|
+
} else {
|
|
82
|
+
process.exit(code ?? 0);
|
|
83
|
+
}
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
process.on('SIGINT', () => child.kill('SIGINT'));
|
|
87
|
+
process.on('SIGTERM', () => child.kill('SIGTERM'));
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
main();
|