@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10
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/dist/backup.js +106 -4
- package/dist/bridges.d.ts +26 -0
- package/dist/bridges.js +96 -0
- package/dist/gate-ledger.d.ts +30 -0
- package/dist/gate-ledger.js +99 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2 -0
- package/dist/library-edit.d.ts +57 -5
- package/dist/library-edit.js +216 -11
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/migrations.js +1 -1
- package/dist/models.d.ts +74 -0
- package/dist/models.js +67 -1
- package/dist/packaged.d.ts +122 -0
- package/dist/packaged.js +125 -0
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +6 -6
- package/dist/providers.d.ts +4 -5
- package/dist/providers.js +26 -5
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/task-rows.d.ts +5 -0
- package/dist/task-rows.js +1 -1
- package/dist/tasks.d.ts +23 -4
- package/dist/tasks.js +103 -9
- package/dist/types.d.ts +3 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/user-settings.d.ts +2 -0
- package/dist/user-settings.js +40 -1
- package/dist/user-worktree.d.ts +29 -0
- package/dist/user-worktree.js +242 -0
- package/dist/validation.d.ts +1 -0
- package/dist/validation.js +35 -13
- package/package.json +34 -2
- package/src/backup.js +106 -5
- package/src/bridges.js +113 -0
- package/src/gate-ledger.js +125 -0
- package/src/index.js +1 -0
- package/src/library-edit.js +227 -12
- package/src/library.js +96 -6
- package/src/migrations.js +1 -1
- package/src/models.js +87 -1
- package/src/packaged.js +207 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +7 -7
- package/src/providers.js +23 -7
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/task-rows.js +1 -1
- package/src/tasks.d.ts +23 -4
- package/src/tasks.js +137 -10
- package/src/types.d.ts +3 -0
- package/src/upgrade.js +54 -6
- package/src/user-settings.d.ts +2 -0
- package/src/user-settings.js +51 -1
- package/src/user-worktree.js +259 -0
- package/src/validation.d.ts +1 -0
- package/src/validation.js +43 -14
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -141
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +34 -0
- package/templates/skills/curate/SKILL.md +36 -0
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Component và state
|
|
2
|
+
|
|
3
|
+
Đọc khi chia component, chọn chỗ đặt state, hoặc xử lý form.
|
|
4
|
+
|
|
5
|
+
Ví dụ dùng thuật ngữ React; cùng ý tưởng đó map sang Vue (props, emits, refs, computed,
|
|
6
|
+
composable) và Svelte (props, store, rune hoặc câu lệnh reactive). Hãy theo
|
|
7
|
+
pattern và bố trí file đang có của dự án.
|
|
8
|
+
|
|
9
|
+
## Cấu trúc component
|
|
10
|
+
|
|
11
|
+
- Một component, một việc. Chia khi một phần có state riêng, được dùng lại, hoặc làm
|
|
12
|
+
component cha khó đọc; không chia chỉ để file ngắn đi.
|
|
13
|
+
- Tách container tải dữ liệu khỏi component trình bày khi dự án làm vậy;
|
|
14
|
+
component trình bày nhận props và dễ test.
|
|
15
|
+
- Props chảy xuống, event chảy lên. Đặt tên callback theo ý định (`onSubmit`,
|
|
16
|
+
`onSelect`), không theo tên event của DOM.
|
|
17
|
+
- Ưu tiên composition (children, slot) hơn là nhiều props boolean bật tắt layout.
|
|
18
|
+
- Giữ component thuần khi render: không fetch, không subscribe, không thay đổi dữ liệu trong
|
|
19
|
+
thân render; dùng cơ chế effect hoặc lifecycle của framework.
|
|
20
|
+
- Dùng key ổn định từ ID của dữ liệu trong danh sách, không bao giờ dùng chỉ số mảng cho danh sách xếp lại được.
|
|
21
|
+
- Chỉ bóc logic dùng lại ra thành hook hoặc composable khi đã có chỗ dùng thứ hai.
|
|
22
|
+
|
|
23
|
+
## State nằm ở đâu
|
|
24
|
+
|
|
25
|
+
Chọn chỗ ở hẹp nhất mà vẫn chạy được:
|
|
26
|
+
|
|
27
|
+
| Loại | Chỗ ở |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| Giá trị chỉ một component dùng | state cục bộ của component |
|
|
30
|
+
| Giá trị dùng chung giữa các component cùng cấp | đưa lên component cha gần nhất |
|
|
31
|
+
| Giá trị suy ra được từ state hay props khác | tính nó ra; đừng lưu lại |
|
|
32
|
+
| Dữ liệu từ server | cache lấy dữ liệu của dự án, không phải state toàn cục |
|
|
33
|
+
| Đáng nằm trên URL (filter, tab, trang, ID đang chọn) | tham số route hoặc query string |
|
|
34
|
+
| Dữ liệu nhập trong form | state của form (cục bộ hoặc thư viện form của dự án) |
|
|
35
|
+
| Thực sự dùng toàn app (theme, session, locale) | context hoặc store của dự án |
|
|
36
|
+
|
|
37
|
+
- State bị trùng lặp sẽ lệch nhau. Nếu hai chỗ giữ cùng một sự thật, hãy giữ một nguồn và
|
|
38
|
+
suy ra chỗ kia.
|
|
39
|
+
- Tránh đồng bộ state bằng effect (`useEffect` copy props vào state); hãy suy ra
|
|
40
|
+
trong lúc render hoặc reset bằng key.
|
|
41
|
+
- Context render lại mọi consumer khi đổi; hãy tách context hoặc dùng store nếu một
|
|
42
|
+
giá trị đổi liên tục được dùng chung rộng khắp.
|
|
43
|
+
- Đặt lên URL những state đáng sống sót qua lần tải lại hoặc đáng chia sẻ được.
|
|
44
|
+
- Không thêm thư viện store toàn cục mà không có quyết định của chủ sở hữu.
|
|
45
|
+
|
|
46
|
+
## Effect và lifecycle
|
|
47
|
+
|
|
48
|
+
- Dùng effect để đồng bộ với thứ gì bên ngoài (subscription, timer, DOM
|
|
49
|
+
API), không để tính giá trị hay phản ứng với event của người dùng.
|
|
50
|
+
- Mọi subscription, listener, timer, hay observer đều phải được dọn.
|
|
51
|
+
- Xử lý việc effect bị gọi hai lần ở strict mode khi dev: effect phải an toàn khi chạy,
|
|
52
|
+
dọn, rồi chạy lại.
|
|
53
|
+
|
|
54
|
+
## Form
|
|
55
|
+
|
|
56
|
+
- Dùng cách làm form của dự án (form native, input có kiểm soát, hoặc thư viện form
|
|
57
|
+
của nó) một cách nhất quán.
|
|
58
|
+
- Mọi input đều có nhãn. Hiện lỗi validate ngay cạnh field và tóm tắt lại
|
|
59
|
+
khi submit; chuyển focus tới lỗi đầu tiên.
|
|
60
|
+
- Validate ở client để phản hồi nhanh; server vẫn là nơi có thẩm quyền.
|
|
61
|
+
- Vô hiệu hóa hoặc chặn hành động submit khi đang chờ để tránh submit hai lần;
|
|
62
|
+
hiện tiến trình.
|
|
63
|
+
- Giữ lại dữ liệu đã nhập khi submit thất bại.
|
|
64
|
+
- Coi phản hồi validate của server là nguồn của các lỗi theo field.
|
|
65
|
+
|
|
66
|
+
## Kiểu và hợp đồng
|
|
67
|
+
|
|
68
|
+
- Khai kiểu cho props và event bằng hệ kiểu của dự án (TypeScript, PropTypes, hoặc
|
|
69
|
+
kiểu riêng của framework).
|
|
70
|
+
- Chỉ chia sẻ kiểu của phản hồi API với backend qua cơ chế đang có của dự án
|
|
71
|
+
(kiểu được sinh ra, package dùng chung); không copy tay những kiểu rồi sẽ lệch nhau.
|
|
72
|
+
- Thu hẹp dữ liệu có thể null ngay tại biên để component nhận được giá trị đầy đủ hoặc một
|
|
73
|
+
trạng thái rỗng tường minh.
|
|
74
|
+
|
|
75
|
+
## Styling
|
|
76
|
+
|
|
77
|
+
- Dùng hệ thống styling của dự án (CSS module, utility class, CSS-in-JS, style có
|
|
78
|
+
phạm vi) và các design token. Không trộn thêm cách thứ hai.
|
|
79
|
+
- Tránh giá trị thần kỳ viết thẳng cho khoảng cách và màu khi đã có token.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Lấy dữ liệu
|
|
2
|
+
|
|
3
|
+
Đọc khi tải, cache, thay đổi, hoặc làm mới dữ liệu server, hoặc khi xử lý tranh chấp.
|
|
4
|
+
|
|
5
|
+
Dùng cơ chế đang có của dự án: loader hay server component của framework, một thư viện
|
|
6
|
+
query-cache (TanStack Query, SWR, Apollo, RTK Query là các ví dụ), hoặc fetch thuần
|
|
7
|
+
gói trong một client dùng chung. Không thêm cơ chế thứ hai.
|
|
8
|
+
|
|
9
|
+
## Mọi request đều có bốn trạng thái
|
|
10
|
+
|
|
11
|
+
- Loading: hiện skeleton hoặc spinner có kích thước như nội dung cuối để tránh dịch
|
|
12
|
+
layout. Với lần tải nhanh, hoãn chỉ báo một chút để nó không nháy.
|
|
13
|
+
- Lỗi: hiện một thông báo có ích và một hành động thử lại. Phân biệt "không tìm thấy",
|
|
14
|
+
"không được phép", "offline", và "lỗi server" khi API cho phép. Không hiện object
|
|
15
|
+
lỗi thô hay stack trace.
|
|
16
|
+
- Rỗng: một trạng thái riêng kèm hướng dẫn hoặc một hành động, không phải một vùng trắng.
|
|
17
|
+
- Thành công: render dữ liệu; giữ dữ liệu trước đó hiển thị trong lúc làm mới ở nền thay vì
|
|
18
|
+
nháy trở về trạng thái loading.
|
|
19
|
+
|
|
20
|
+
Cũng hãy tính tới dữ liệu một phần (một số mục bị lỗi) và dữ liệu cũ (hiện ra trong lúc
|
|
21
|
+
đang làm mới).
|
|
22
|
+
|
|
23
|
+
## Fetch ở đâu
|
|
24
|
+
|
|
25
|
+
- Ưu tiên tải ở cấp route hoặc phía server khi framework hỗ trợ, để dữ liệu
|
|
26
|
+
bắt đầu tải cùng lúc với điều hướng và tránh được thác nước request.
|
|
27
|
+
- Khởi động các request độc lập song song; không xâu chúng lại trong các component lồng nhau
|
|
28
|
+
trừ khi cái này phụ thuộc cái kia.
|
|
29
|
+
- Không fetch trong lúc render. Ở client component hãy dùng thư viện cache hoặc một effect
|
|
30
|
+
có dọn dẹp.
|
|
31
|
+
- Giữ API client trong một module: base URL, header hay cookie auth, parse JSON,
|
|
32
|
+
và chuẩn hóa lỗi.
|
|
33
|
+
|
|
34
|
+
## Cache
|
|
35
|
+
|
|
36
|
+
- Đặt key cho dữ liệu cache theo mọi thứ ảnh hưởng tới phản hồi (tài nguyên, ID, filter,
|
|
37
|
+
trang, người dùng hay tenant).
|
|
38
|
+
- Quyết định độ tươi cho từng tài nguyên: dữ liệu được coi là tươi trong bao lâu, và khi nào fetch lại
|
|
39
|
+
(khi focus, khi kết nối lại, theo chu kỳ, hoặc khi vô hiệu tường minh).
|
|
40
|
+
- Vô hiệu hoặc cập nhật các key bị ảnh hưởng sau một mutation; không để danh sách còn cũ
|
|
41
|
+
sau khi tạo hay xóa.
|
|
42
|
+
- Xóa cache riêng của người dùng khi logout hoặc đổi tài khoản.
|
|
43
|
+
- Tôn trọng các header cache HTTP mà backend đã đặt; không cache những phản hồi mang tính
|
|
44
|
+
cá nhân vào cache dùng chung.
|
|
45
|
+
|
|
46
|
+
## Tranh chấp (race condition)
|
|
47
|
+
|
|
48
|
+
- Một phản hồi đến trước nhưng chậm hơn không được ghi đè lên phản hồi mới hơn. Hãy hủy request
|
|
49
|
+
trước đó (AbortController hoặc cơ chế hủy của thư viện) hoặc bỏ qua kết quả có key
|
|
50
|
+
không còn khớp với dữ liệu nhập hiện tại.
|
|
51
|
+
- Debounce việc tìm kiếm khi đang gõ và hủy các request đang bay khi có dữ liệu nhập mới.
|
|
52
|
+
- Bỏ qua kết quả sau khi unmount; dọn subscription và abort các request đang bay.
|
|
53
|
+
- Chặn việc submit mutation hai lần: vô hiệu hóa khi đang chờ, và gửi một
|
|
54
|
+
idempotency key nếu API hỗ trợ.
|
|
55
|
+
|
|
56
|
+
## Mutation
|
|
57
|
+
|
|
58
|
+
- Hiện trạng thái đang chờ trên chính control đã khởi động mutation đó.
|
|
59
|
+
- Chỉ cập nhật lạc quan khi thất bại là hiếm và đảo lại được; hoàn tác khi lỗi
|
|
60
|
+
và nói cho người dùng biết.
|
|
61
|
+
- Khi server trả lỗi validate, hãy map chúng về từng field.
|
|
62
|
+
- Sau khi thành công, cập nhật hoặc vô hiệu cache, rồi chuyển focus hoặc thông báo
|
|
63
|
+
kết quả cho công nghệ trợ giúp.
|
|
64
|
+
|
|
65
|
+
## Lỗi và thử lại
|
|
66
|
+
|
|
67
|
+
- Chỉ tự động thử lại các lần đọc idempotent, với giới hạn nhỏ và có backoff. Không
|
|
68
|
+
tự động thử lại mutation trừ khi chúng idempotent.
|
|
69
|
+
- Xử lý 401 ở một chỗ duy nhất (refresh hoặc chuyển tới trang login theo quy ước của dự án).
|
|
70
|
+
- Dùng error boundary hoặc route lỗi của framework cho những lỗi bất ngờ, để một
|
|
71
|
+
widget vỡ không làm trắng cả trang.
|
|
72
|
+
- Báo lỗi qua hệ thống giám sát đang có của dự án, không kèm dữ liệu cá nhân hay
|
|
73
|
+
token.
|
|
74
|
+
|
|
75
|
+
## Bảo mật
|
|
76
|
+
|
|
77
|
+
- Không bao giờ nhúng secret hay API key riêng vào code client; hãy đi qua
|
|
78
|
+
backend.
|
|
79
|
+
- Chỉ gửi thông tin đăng nhập tới các origin của chính dự án.
|
|
80
|
+
- Không tin các kiểm tra phía client về phân quyền; server mới là nơi thực thi.
|
|
81
|
+
|
|
82
|
+
## Ghi chú về test
|
|
83
|
+
|
|
84
|
+
- Mock mạng ở tầng HTTP (công cụ mock request của dự án) chứ không
|
|
85
|
+
mock phần bên trong của thư viện cache.
|
|
86
|
+
- Test cả bốn trạng thái và một tình huống chậm-rồi-nhanh cho các input tìm kiếm.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Framework, render, và routing
|
|
2
|
+
|
|
3
|
+
Đọc khi chọn SSR, SSG, hay CSR, server hay client component, hoặc chỗ đặt
|
|
4
|
+
routing.
|
|
5
|
+
|
|
6
|
+
Quy ước của framework đổi giữa các bản major. Hãy xác định đúng framework
|
|
7
|
+
và phiên bản từ `package.json` và lockfile, theo quy ước của chính
|
|
8
|
+
phiên bản đó, và xem tài liệu chính thức của nó (hoặc tài liệu và type của package đã
|
|
9
|
+
cài) trước khi dựa vào một API. Nếu dự án trộn quy ước cũ và mới (ví
|
|
10
|
+
dụ vừa pages router vừa app router), hãy theo cái đang dùng ở vùng bạn
|
|
11
|
+
đang sửa và không tự ý chuyển đổi nó.
|
|
12
|
+
|
|
13
|
+
## Các chế độ render
|
|
14
|
+
|
|
15
|
+
| Chế độ | Render ở đâu | Phù hợp cho | Cái giá |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| CSR (phía client) | trong browser | màn hình dạng app sau khi đăng nhập | first paint chậm hơn, SEO tùy crawler |
|
|
18
|
+
| SSR (mỗi request) | trên server mỗi request | nội dung cá nhân hóa hay tươi mới, SEO | tốn server, có độ trễ mỗi request |
|
|
19
|
+
| SSG (lúc build) | một lần khi build | nội dung ổn định, tài liệu, marketing | phải build lại hoặc revalidate để cập nhật |
|
|
20
|
+
| Static tăng dần / có revalidate | khi build, làm mới theo chu kỳ hay theo trigger | nội dung phần lớn tĩnh nhưng có đổi | có khoảng thời gian dữ liệu cũ |
|
|
21
|
+
| Streaming / một phần | server stream từng phần khi sẵn sàng | phần chậm trên bộ khung nhanh | trạng thái loading phức tạp hơn |
|
|
22
|
+
|
|
23
|
+
- Theo đúng chế độ mà các route xung quanh đang dùng, trừ khi brief yêu cầu đổi.
|
|
24
|
+
- Đổi chế độ render của một route ảnh hưởng tới cache, hosting, và SEO; hãy chuyển
|
|
25
|
+
quyết định đó lên trên.
|
|
26
|
+
|
|
27
|
+
## Server component và client component
|
|
28
|
+
|
|
29
|
+
Áp dụng cho framework có tách server/client (React Server Component trong
|
|
30
|
+
app router của Next.js và tương tự; khái niệm tương đương ở Nuxt, SvelteKit, island của Astro).
|
|
31
|
+
|
|
32
|
+
- Server component: fetch dữ liệu, đọc config chỉ có ở server, render markup tĩnh,
|
|
33
|
+
không gửi JS của component. Chúng không dùng được state client, effect, hay API browser.
|
|
34
|
+
- Client component: tính tương tác, state, effect, API browser. Đánh dấu chúng theo
|
|
35
|
+
cách framework yêu cầu (ví dụ chỉ thị `"use client"`) ở vị trí càng thấp trong cây càng
|
|
36
|
+
tốt, để phần lớn markup vẫn được render ở server.
|
|
37
|
+
- Props truyền từ server sang client phải serialize được; không truyền hàm hay
|
|
38
|
+
instance của class.
|
|
39
|
+
- Không bao giờ import module chỉ dành cho server (client database, secret) vào code client.
|
|
40
|
+
Dùng cơ chế chặn server-only của framework nếu nó có.
|
|
41
|
+
- Server action hay form action là endpoint công khai: hãy validate dữ liệu nhập và kiểm tra
|
|
42
|
+
phân quyền trong chúng như với bất kỳ API nào.
|
|
43
|
+
|
|
44
|
+
## Hydration
|
|
45
|
+
|
|
46
|
+
- Server và client phải render ra cùng một markup ban đầu. Tránh dùng khi render các thứ như
|
|
47
|
+
`Date.now()`, giá trị ngẫu nhiên, `window`, hay định dạng phụ thuộc locale mà không có
|
|
48
|
+
dữ liệu nhập ổn định.
|
|
49
|
+
- Đọc các giá trị chỉ có ở browser sau khi mount, hoặc chỉ render chúng ở client qua
|
|
50
|
+
cơ chế của framework.
|
|
51
|
+
- Coi cảnh báo hydration là bug.
|
|
52
|
+
|
|
53
|
+
## Quy ước routing
|
|
54
|
+
|
|
55
|
+
- Theo hệ thống routing của dự án: dựa trên file (Next.js, Nuxt, SvelteKit, Remix
|
|
56
|
+
hay React Router ở chế độ framework) hoặc dựa trên config (React Router, Vue Router).
|
|
57
|
+
- Đặt phần tải dữ liệu ở nơi framework mong đợi (loader, server component,
|
|
58
|
+
hàm `load`, route guard) để tránh thác nước request ở client.
|
|
59
|
+
- Dùng component link của framework cho điều hướng nội bộ, để prefetch và
|
|
60
|
+
chuyển trang ở client hoạt động.
|
|
61
|
+
- Dùng cơ chế xử lý loading, lỗi, và không-tìm-thấy ở cấp route mà framework cung cấp.
|
|
62
|
+
- Giữ state thuộc URL (filter, phân trang, tab) trong tham số hoặc query string.
|
|
63
|
+
- Bảo vệ route ở server (middleware, loader) chứ không chỉ ở UI; chỉ redirect
|
|
64
|
+
ở client thì không bảo vệ được dữ liệu.
|
|
65
|
+
|
|
66
|
+
## Môi trường và config
|
|
67
|
+
|
|
68
|
+
- Biến env công khai (tiền tố như `NEXT_PUBLIC_` hay `VITE_`) được nhúng vào
|
|
69
|
+
bundle client; không bao giờ đặt secret vào chúng.
|
|
70
|
+
- Tôn trọng dạng output build của dự án (static export, Node server, edge runtime);
|
|
71
|
+
API lúc chạy khác nhau giữa chúng.
|
|
72
|
+
|
|
73
|
+
## Khi không chắc
|
|
74
|
+
|
|
75
|
+
- Tìm route đang có gần nhất làm cùng loại việc đó và làm theo nó.
|
|
76
|
+
- Nếu tài liệu của phiên bản đã cài trái với ký ức hay với ví dụ, hãy theo tài liệu
|
|
77
|
+
và ghi lại khác biệt đó trong handoff.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Hiệu năng frontend
|
|
2
|
+
|
|
3
|
+
Đọc khi một màn hình chậm, bundle phình ra, hoặc ảnh và danh sách quá nặng.
|
|
4
|
+
|
|
5
|
+
Đo trước, rồi đổi một thứ, rồi đo lại trong cùng điều kiện
|
|
6
|
+
(cùng chế độ build, cùng thiết bị hay cấu hình giới hạn, cùng lượng dữ liệu). Bản build dev
|
|
7
|
+
chậm hơn và nhiễu hơn bản production; muốn khẳng định điều gì thì hãy profile bản production.
|
|
8
|
+
|
|
9
|
+
## Đo cái gì
|
|
10
|
+
|
|
11
|
+
- Core Web Vitals cho trải nghiệm trang: Largest Contentful Paint (tải),
|
|
12
|
+
Interaction to Next Paint (độ đáp ứng), Cumulative Layout Shift (độ ổn định).
|
|
13
|
+
Dùng công cụ đang có của dự án (Lighthouse, panel performance của browser, một dashboard
|
|
14
|
+
RUM) và báo lại điều kiện đo.
|
|
15
|
+
- Chi phí render: profiler của framework (React DevTools Profiler, Vue DevTools) để
|
|
16
|
+
thấy component nào render, bao nhiêu lần, và mất bao lâu.
|
|
17
|
+
- Kích thước bundle: công cụ phân tích hoặc output thống kê của build cho các route bị ảnh hưởng.
|
|
18
|
+
- Mạng: biểu đồ thác nước của route; tìm những request nối tiếp nhau và payload lớn.
|
|
19
|
+
|
|
20
|
+
Dùng ngân sách mà dự án đã định ra. Đừng tự nghĩ ra một ngưỡng cố định; hãy báo
|
|
21
|
+
các con số trước và sau.
|
|
22
|
+
|
|
23
|
+
## Chi phí render
|
|
24
|
+
|
|
25
|
+
- Trước hết hãy bỏ những việc không cần: state đặt quá cao làm render lại cả vùng rộng,
|
|
26
|
+
dữ liệu suy ra bị tính lại trong lúc render trên dữ liệu nhập lớn, effect đặt state ở
|
|
27
|
+
mỗi lần render, và giá trị context bị tạo lại mỗi lần render.
|
|
28
|
+
- Đưa state xuống đúng chỗ nó được dùng, hoặc chia component ra để state đổi nhanh
|
|
29
|
+
chỉ render lại một nhánh nhỏ.
|
|
30
|
+
- Chỉ ghi nhớ (`memo`, `useMemo`, `useCallback`, giá trị computed) ở nơi
|
|
31
|
+
profiler cho thấy một chi phí đo được, hoặc ở nơi compiler hay luật lint của dự án
|
|
32
|
+
đã xử lý giúp. Ghi nhớ mà không đo thì thêm phức tạp và có thể che bug do
|
|
33
|
+
phụ thuộc đã cũ.
|
|
34
|
+
- Virtual hóa danh sách dài (hàng trăm dòng hoặc hơn) theo cách đang có của
|
|
35
|
+
dự án; phân trang khi chưa đáng để virtual hóa.
|
|
36
|
+
- Chỉ đưa phần tính toán nặng ra khỏi luồng chính (một web worker) khi đã đo.
|
|
37
|
+
- Hoãn các cập nhật không gấp bằng API transition hay lập lịch của framework khi
|
|
38
|
+
gõ chữ thấy có cảm giác trễ.
|
|
39
|
+
|
|
40
|
+
## Bundle và tải
|
|
41
|
+
|
|
42
|
+
- Chia theo route; lazy-load những component nặng, ít dùng (editor, biểu đồ, bản đồ)
|
|
43
|
+
đặt sau tương tác hoặc view thực sự cần chúng.
|
|
44
|
+
- Kiểm tra một phụ thuộc mới tốn bao nhiêu trước khi đề xuất nó; ưu tiên API của nền tảng và
|
|
45
|
+
các phụ thuộc đang có. Thêm một cái là quyết định của chủ sở hữu.
|
|
46
|
+
- Chỉ import những gì bạn dùng; tránh import kiểu barrel làm mất tác dụng tree shaking khi
|
|
47
|
+
bundler xử lý chúng không tốt.
|
|
48
|
+
- Đừng vô tình gửi code chỉ dành cho server, file dữ liệu lớn, hay source map
|
|
49
|
+
xuống client.
|
|
50
|
+
- Preload các tài nguyên quan trọng (ảnh LCP, font chính) khi số đo cho thấy có
|
|
51
|
+
độ trễ; đừng preload mọi thứ.
|
|
52
|
+
- Render ở server hay sinh tĩnh giúp cải thiện first paint cho các trang nội dung; xem
|
|
53
|
+
frameworks.md.
|
|
54
|
+
|
|
55
|
+
## Ảnh và media
|
|
56
|
+
|
|
57
|
+
- Phục vụ ảnh đã đúng kích thước, đã nén, ở các định dạng hiện đại, qua pipeline hay
|
|
58
|
+
component ảnh của dự án.
|
|
59
|
+
- Luôn đặt width và height (hoặc tỉ lệ khung) để tránh dịch layout.
|
|
60
|
+
- Lazy-load các ảnh nằm dưới màn hình đầu; không lazy-load ảnh LCP.
|
|
61
|
+
- Dùng `srcset` và `sizes` responsive để màn hình nhỏ tải file nhỏ.
|
|
62
|
+
- Ưu tiên CSS hoặc SVG cho icon và hình đơn giản.
|
|
63
|
+
|
|
64
|
+
## Độ ổn định layout và độ đáp ứng
|
|
65
|
+
|
|
66
|
+
- Dành sẵn chỗ cho nội dung bất đồng bộ, quảng cáo, và nội dung nhúng.
|
|
67
|
+
- Tránh chèn nội dung lên phía trên nội dung đang có sau khi tải xong.
|
|
68
|
+
- Tải font với một chiến lược hiển thị tránh chữ vô hình, dùng thiết lập font
|
|
69
|
+
của dự án.
|
|
70
|
+
- Giữ các handler nhập liệu ngắn gọn; chia nhỏ task dài; tránh giật layout (đọc
|
|
71
|
+
layout rồi ghi style trong một vòng lặp).
|
|
72
|
+
|
|
73
|
+
## Báo cáo
|
|
74
|
+
|
|
75
|
+
- Nêu rõ chỉ số, công cụ, chế độ build, thiết bị hay cấu hình giới hạn, lượng dữ liệu, và
|
|
76
|
+
giá trị trước và sau.
|
|
77
|
+
- Nếu một thay đổi không làm chỉ số đo được nhúc nhích, hãy hoàn tác nó chứ đừng giữ lại
|
|
78
|
+
cho chắc.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcp-integration
|
|
3
|
+
description: "Thiết kế, xây dựng, test và nối server cùng client Model Context Protocol: tên tool, schema, description và lỗi, transport stdio hay streamable HTTP, auth cho server từ xa, và cấu hình ALP. Dùng khi tạo hoặc sửa một MCP server, hoặc khi nối một server vào một agent. Không dùng cho thiết kế REST API nói chung (việc backend) hay việc chọn skill."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# MCP server và client
|
|
7
|
+
|
|
8
|
+
## Khi nào dùng
|
|
9
|
+
|
|
10
|
+
- Thiết kế hoặc đổi các tool, resource hay prompt mà một MCP server phơi ra.
|
|
11
|
+
- Hiện thực một server hay client bằng MCP SDK chính thức của ngôn ngữ dự án.
|
|
12
|
+
- Chọn transport (stdio hay streamable HTTP) hoặc thêm auth cho một server từ xa.
|
|
13
|
+
- Test một server bằng tay hoặc bằng test tự động.
|
|
14
|
+
- Làm cho một server đang có khả dụng với các agent ALP.
|
|
15
|
+
|
|
16
|
+
## Không dùng cho
|
|
17
|
+
|
|
18
|
+
- Thiết kế một API HTTP hay RPC thuần, không có lớp MCP.
|
|
19
|
+
- Dùng tool của một MCP server đã cấu hình sẵn trong công việc thường ngày.
|
|
20
|
+
- Deploy một server từ xa hay cấp phát hosting cho nó: việc đó cần được cho phép tường minh
|
|
21
|
+
(xem devops).
|
|
22
|
+
|
|
23
|
+
## Điều kiện tiên quyết
|
|
24
|
+
|
|
25
|
+
- Đọc ALP.md cùng các manifest, lockfile và code MCP hiện có của dự án. Dùng MCP SDK chính thức
|
|
26
|
+
của ngôn ngữ dự án ở đúng version đã pin; đọc tài liệu của version đó trước khi dựa vào một
|
|
27
|
+
API, vì bề mặt SDK thay đổi giữa các bản phát hành.
|
|
28
|
+
- Biết ai gọi server (những agent nào, local hay từ xa) và nó được chạm vào những gì
|
|
29
|
+
(file, mạng, tài khoản). Các quyết định còn thiếu thì chuyển lên.
|
|
30
|
+
|
|
31
|
+
## Quy trình
|
|
32
|
+
|
|
33
|
+
1. Định nghĩa công việc: những task của người dùng mà server mở ra, các hệ thống nó vươn tới,
|
|
34
|
+
và mỗi thao tác là đọc, ghi hay xóa. Ưu tiên ít tool mang hình dạng task hơn là ảnh phản
|
|
35
|
+
chiếu mọi endpoint.
|
|
36
|
+
2. Thiết kế tool: tên, description, input schema, output, annotation và hành vi lỗi. Hãy soát
|
|
37
|
+
cả bộ như một model sẽ thấy nó: chỉ từ tên và description, nó chọn được đúng tool không?
|
|
38
|
+
3. Chọn transport. stdio cho một process local được khởi chạy theo từng client; streamable HTTP
|
|
39
|
+
cho một service dùng chung hoặc từ xa. Server từ xa cần auth và kiểm tra origin.
|
|
40
|
+
4. Hiện thực bằng SDK: khởi tạo, khai báo capability, handler có validate input, timeout, phân
|
|
41
|
+
trang cho danh sách lớn, log ra stderr (đừng bao giờ ra stdout khi dùng stdio).
|
|
42
|
+
5. Test: kiểm tra protocol bằng tay, test tự động gọi từng tool qua một client, các ca lỗi
|
|
43
|
+
và ca biên, rồi `alp mcp test <name>` sau khi đã cấu hình.
|
|
44
|
+
6. Nối vào ALP (bên dưới), khai tên nó trong các agent cần nó, và xác nhận agent thấy được các
|
|
45
|
+
tool.
|
|
46
|
+
7. Handoff: tool đã thêm hay đổi, schema, transport, mục config, lệnh test và kết quả,
|
|
47
|
+
và mọi secret mà owner phải cung cấp.
|
|
48
|
+
|
|
49
|
+
## Nối một server vào ALP
|
|
50
|
+
|
|
51
|
+
- Một server một file: `mcp/<name>.json` trong library của người dùng (`~/.alp`) hoặc
|
|
52
|
+
`.alp/mcp/` của dự án. Dạng của nó là một mục `.mcp.json`:
|
|
53
|
+
`{ "command", "args", "env", "cwd" }` cho stdio, hoặc `{ "url", "headers" }` cho HTTP.
|
|
54
|
+
Một `cwd` tương đối thì tương đối với thư mục của file.
|
|
55
|
+
- Tạo nó bằng `alp mcp add <name> --command C --arg A [--env K=V] [--cwd D]` hoặc
|
|
56
|
+
`alp mcp add <name> --url U [--header K=V]`; thêm `--project` cho lớp dự án.
|
|
57
|
+
- Một agent dùng nó bằng cách khai tên nó trong `agent.json`: `"mcp": ["<name>"]`. Một agent
|
|
58
|
+
library chỉ khai được server của library; một agent dự án khai được cả server dự án và server
|
|
59
|
+
library. Một tên cũng có mặt trong `.mcp.json` của chính agent là một lỗi.
|
|
60
|
+
- `alp mcp test <name>` khởi động server, liệt kê các tool của nó rồi dừng nó.
|
|
61
|
+
`alp mcp show <name>` cho thấy mục nào đang áp dụng và nó đến từ đâu.
|
|
62
|
+
|
|
63
|
+
## Ràng buộc
|
|
64
|
+
|
|
65
|
+
- Theo stack, SDK và quy ước hiện có của dự án trước đã. Không thêm dependency,
|
|
66
|
+
service hay tài nguyên cloud mà không có quyết định của owner. Không tự cài.
|
|
67
|
+
- Đừng bao giờ đặt secret vào file được commit, kể cả `.alp/mcp/*.json` trong một repository.
|
|
68
|
+
Giá trị trong `env` và `headers` được dùng đúng như viết, nên hãy giữ các mục chứa secret
|
|
69
|
+
trong library của người dùng, hoặc để server đọc một credential mà owner cung cấp ngoài
|
|
70
|
+
repository. Đừng đọc hay in các secret đang có.
|
|
71
|
+
- Đừng bao giờ deploy, đổi hạ tầng, hay chạm vào hệ thống hoặc credential production mà không
|
|
72
|
+
được cho phép tường minh.
|
|
73
|
+
- Tool nào ghi, xóa hay tiêu tiền thì phải nói rõ điều đó trong description và annotation của
|
|
74
|
+
nó, và nên hỗ trợ một bước dry run hoặc xác nhận ở nơi SDK và client cho phép.
|
|
75
|
+
- Agent chỉ đọc thì thiết kế và review; chúng không sửa code hay config ALP.
|
|
76
|
+
|
|
77
|
+
## Kiểm chứng
|
|
78
|
+
|
|
79
|
+
- Mọi tool đều có tên rõ ràng, một description nói khi nào dùng nó, một input schema nghiêm
|
|
80
|
+
ngặt và các lỗi đã ghi tài liệu; tool phá hủy được đánh dấu.
|
|
81
|
+
- Test tự động gọi từng tool qua một SDK client và phủ thành công, input không hợp lệ và một
|
|
82
|
+
thất bại ở phía dưới.
|
|
83
|
+
- Một server stdio không in gì ngoài message protocol lên stdout.
|
|
84
|
+
- `alp mcp test <name>` liệt kê đúng các tool mong đợi.
|
|
85
|
+
|
|
86
|
+
## Xử lý khi thất bại
|
|
87
|
+
|
|
88
|
+
- `alp mcp test` không khởi động được: chạy trực tiếp lệnh đã cấu hình, kiểm tra `cwd`, đường
|
|
89
|
+
dẫn interpreter và việc làm bẩn stdout; báo lỗi chính xác.
|
|
90
|
+
- Tool thiếu hoặc bị đổi tên: so danh sách tool của server với config của agent và
|
|
91
|
+
kiểm tra xem có tên server trùng nhau giữa các lớp không.
|
|
92
|
+
- Không có auth: dừng ở một test local không cần auth mà chạy được và báo credential mà
|
|
93
|
+
owner phải cung cấp; đừng bao giờ dán token vào chat hay file.
|
|
94
|
+
- API của SDK khác với ví dụ: tin tài liệu và source của version đã cài; ghi lại version đó.
|
|
95
|
+
|
|
96
|
+
## Tài liệu tham khảo
|
|
97
|
+
|
|
98
|
+
- [references/tool-design.md](references/tool-design.md) — đọc khi đặt tên tool, viết description và schema, hay định nghĩa lỗi ở bước 2.
|
|
99
|
+
- [references/server-implementation.md](references/server-implementation.md) — đọc khi chọn transport, thêm auth, hay hiện thực lifecycle, logging, timeout và phân trang ở bước 3-4.
|
|
100
|
+
- [references/testing.md](references/testing.md) — đọc khi test một server bằng tay hoặc tự động ở bước 5.
|
package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Hiện thực MCP server
|
|
2
|
+
|
|
3
|
+
Đọc khi chọn transport, thêm auth cho một server từ xa, hoặc khi hiện thực lifecycle,
|
|
4
|
+
logging, timeout và phân trang.
|
|
5
|
+
|
|
6
|
+
## Dùng SDK chính thức
|
|
7
|
+
|
|
8
|
+
- Dùng MCP SDK chính thức của ngôn ngữ dự án ở đúng version đã pin. Hãy kiểm tra tài liệu và
|
|
9
|
+
changelog của version đó: lớp transport, helper đăng ký và kiểu kết quả khác nhau
|
|
10
|
+
giữa các bản phát hành và các bản sửa đổi protocol.
|
|
11
|
+
- Thêm SDK, nâng version nó, hay thêm một web framework cho HTTP là một quyết định về
|
|
12
|
+
dependency của owner. Đừng tự cài gì cả.
|
|
13
|
+
- Để SDK lo việc đóng khung JSON-RPC, khởi tạo và thương lượng version protocol. Đừng
|
|
14
|
+
tự viết protocol bằng tay.
|
|
15
|
+
|
|
16
|
+
## Transport
|
|
17
|
+
|
|
18
|
+
| | stdio | Streamable HTTP |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| Process | Client khởi chạy server làm process con | Service chạy lâu, nhiều client |
|
|
21
|
+
| Phù hợp | Tool local, truy cập file hay CLI local theo từng người dùng | Service dùng chung hay từ xa, tích hợp được host |
|
|
22
|
+
| Message | JSON-RPC phân cách bằng dòng mới trên stdin/stdout | JSON-RPC qua HTTP POST tới một endpoint; response là JSON hoặc một stream SSE |
|
|
23
|
+
| Auth | Thừa hưởng môi trường của người dùng | Bắt buộc với mọi thứ không phải local |
|
|
24
|
+
| Config ALP | `{ "command", "args", "env", "cwd" }` | `{ "url", "headers" }` |
|
|
25
|
+
|
|
26
|
+
- Transport HTTP+SSE cũ đã deprecated; chỉ hỗ trợ nó nếu một client đang có cần nó.
|
|
27
|
+
- stdio: stdout chỉ chở message protocol. Mọi lần print lạc, banner, progress bar hay cảnh báo
|
|
28
|
+
của library trên stdout đều làm hỏng stream. Hãy gửi log ra stderr.
|
|
29
|
+
- Streamable HTTP: validate header `Origin` để chặn DNS rebinding, bind server chỉ dùng local
|
|
30
|
+
vào `127.0.0.1` thay vì mọi interface, và xử lý session ID như SDK ghi trong tài liệu.
|
|
31
|
+
Giữ đường dẫn endpoint ổn định; client lưu lại URL.
|
|
32
|
+
|
|
33
|
+
## Lifecycle
|
|
34
|
+
|
|
35
|
+
1. Khởi tạo: client gửi version protocol và capability của nó; server đáp lại bằng version,
|
|
36
|
+
capability (tool, resource, prompt, logging) và thông tin server (tên, version) của mình.
|
|
37
|
+
2. Notification initialized; hoạt động bình thường bắt đầu. Đừng gửi request trước đó.
|
|
38
|
+
3. Hoạt động: xử lý `tools/list`, `tools/call` và mọi capability khác đã khai báo. Chỉ phát
|
|
39
|
+
notification `list_changed` nếu đã khai báo và bộ tool thật sự thay đổi.
|
|
40
|
+
4. Dừng: với stdio, thoát gọn khi stdin đóng; với HTTP, giải phóng trạng thái session.
|
|
41
|
+
Flush log, đóng các kết nối lên upstream và các process con.
|
|
42
|
+
|
|
43
|
+
- Khởi động nhanh. Hoãn việc chậm (kết nối lên upstream, nạp index) tới lần dùng đầu để
|
|
44
|
+
`tools/list` đáp nhanh; client và `alp mcp test` sẽ timeout khi khởi động chậm.
|
|
45
|
+
- Fail ngay khi khởi động kèm một message rõ ràng trên stderr nếu thiếu cấu hình bắt buộc.
|
|
46
|
+
|
|
47
|
+
## Cấu hình và secret
|
|
48
|
+
|
|
49
|
+
- Đọc cấu hình từ biến môi trường hoặc tham số; ghi tài liệu cho từng cái.
|
|
50
|
+
- Đừng bao giờ commit secret. ALP truyền giá trị `env` và `headers` đúng như viết, nên một
|
|
51
|
+
`.alp/mcp/<name>.json` ở mức dự án không được chứa token. Hãy giữ các mục chứa secret trong
|
|
52
|
+
library của người dùng, hoặc để owner cung cấp credential ngoài repository.
|
|
53
|
+
- Đừng bao giờ log secret hay toàn bộ body request có thể chứa chúng.
|
|
54
|
+
|
|
55
|
+
## Auth cho server từ xa
|
|
56
|
+
|
|
57
|
+
- Theo phần authorization của đặc tả MCP ứng với bản sửa đổi protocol đang dùng (dựa trên OAuth
|
|
58
|
+
2.1, kèm metadata về protected resource). Dùng helper auth của SDK hay của framework thay vì
|
|
59
|
+
tự parse token.
|
|
60
|
+
- Validate token ở mọi request: issuer, audience (token phải được phát cho server này),
|
|
61
|
+
hạn dùng và scope. Từ chối token phát cho service khác.
|
|
62
|
+
- Đừng chuyển token của client sang các API upstream; hãy lấy credential upstream riêng.
|
|
63
|
+
- Map scope sang tool; kiểm tra authorization theo từng lời gọi tool, không chỉ lúc kết nối.
|
|
64
|
+
- Giới hạn tần suất theo từng client và trả một lỗi rõ ràng khi chạm giới hạn.
|
|
65
|
+
- Hosting, DNS, chứng chỉ và thiết lập identity provider là các thay đổi hạ tầng, cần
|
|
66
|
+
được cho phép tường minh.
|
|
67
|
+
|
|
68
|
+
## Timeout, hủy và tiến độ
|
|
69
|
+
|
|
70
|
+
- Đặt cho mọi lời gọi upstream một timeout ngắn hơn timeout request của client, và trả về một
|
|
71
|
+
lỗi tool có nêu tên timeout đó.
|
|
72
|
+
- Tôn trọng notification hủy: dừng việc và giải phóng tài nguyên.
|
|
73
|
+
- Với thao tác dài, báo tiến độ nếu client đã gửi một progress token, hoặc tách thành
|
|
74
|
+
tool start và tool status.
|
|
75
|
+
- Giới hạn mức đồng thời để bảo vệ các service upstream.
|
|
76
|
+
|
|
77
|
+
## Phân trang và kích thước
|
|
78
|
+
|
|
79
|
+
- Các thao tác liệt kê (`tools/list`, `resources/list`, và các tool kiểu liệt kê) dùng cursor
|
|
80
|
+
mờ: trả `nextCursor` khi còn kết quả; nhận `cursor` ở lời gọi tiếp theo.
|
|
81
|
+
- Cursor là chuỗi mờ; đừng để client phụ thuộc vào định dạng của chúng.
|
|
82
|
+
- Chặn kích thước kết quả. Blob lớn thuộc về resource hay file được tham chiếu bằng URI, không
|
|
83
|
+
nằm trong text.
|
|
84
|
+
|
|
85
|
+
## Logging
|
|
86
|
+
|
|
87
|
+
- stderr cho server stdio; dòng có cấu trúc (level, thời gian, tool, thời lượng, loại lỗi).
|
|
88
|
+
- Có thể hiện thực thêm capability logging của protocol để client nhận được message log.
|
|
89
|
+
- Log tên tool, thời lượng và kết quả cho mỗi lời gọi; bỏ các giá trị tham số có thể nhạy cảm.
|
|
90
|
+
|
|
91
|
+
## Phía client
|
|
92
|
+
|
|
93
|
+
- Khi viết một client, hãy dùng cùng SDK: kết nối một transport, khởi tạo, liệt kê tool, gọi
|
|
94
|
+
tool, xử lý kết quả `isError` tách riêng khỏi lỗi protocol, và đóng session.
|
|
95
|
+
- Chỉ cache danh sách tool cho tới khi có notification `list_changed` hoặc khi kết nối lại.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Test một MCP server
|
|
2
|
+
|
|
3
|
+
Đọc khi kiểm tra một server bằng tay, viết test tự động cho các tool của nó, hoặc xác nhận nó
|
|
4
|
+
chạy được bên trong ALP.
|
|
5
|
+
|
|
6
|
+
## Thứ tự
|
|
7
|
+
|
|
8
|
+
1. Unit test cho logic nằm sau từng tool, không qua protocol.
|
|
9
|
+
2. Test protocol: một SDK client kết nối tới server qua transport in-memory hoặc stdio.
|
|
10
|
+
3. Soi bằng tay danh sách tool và vài lời gọi.
|
|
11
|
+
4. Kiểm tra trong ALP bằng `alp mcp test <name>` và một lần chạy agent có dùng một tool.
|
|
12
|
+
|
|
13
|
+
Chạy lệnh test hiện có của dự án; thêm test trong framework và cách bố trí của nó.
|
|
14
|
+
|
|
15
|
+
## Kiểm tra bằng tay (kiểu inspector)
|
|
16
|
+
|
|
17
|
+
Chỉ dùng một MCP inspector tương tác nếu dự án hay owner đã có sẵn một cái;
|
|
18
|
+
lấy một cái qua package runner là tải code về và cần owner phê duyệt. Nếu không,
|
|
19
|
+
một script SDK client ngắn trong scratch space cũng làm được đúng việc đó.
|
|
20
|
+
|
|
21
|
+
Hãy kiểm tra:
|
|
22
|
+
|
|
23
|
+
- Khởi tạo thành công; tên server, version và các capability đã khai báo là đúng.
|
|
24
|
+
- `tools/list` trả về mọi tool mong đợi kèm description, input schema và annotation.
|
|
25
|
+
- Mỗi tool: một lời gọi hợp lệ, một lời gọi thiếu field bắt buộc, một lời gọi sai kiểu,
|
|
26
|
+
một lời gọi làm phát sinh thất bại ở phía dưới (không tìm thấy, bị từ chối quyền).
|
|
27
|
+
- Kết quả lỗi là lỗi tool với message hành động được, không phải crash hay lỗi protocol.
|
|
28
|
+
- Danh sách lớn có phân trang: `nextCursor` xuất hiện, trang sau khác trang trước, trang cuối
|
|
29
|
+
không có nó.
|
|
30
|
+
- stdio: chạy trực tiếp lệnh của server và xác nhận không có gì ngoài JSON-RPC trên stdout
|
|
31
|
+
(banner khởi động và cảnh báo phải ra stderr).
|
|
32
|
+
- HTTP: request không có auth hợp lệ bị từ chối; `Origin` sai bị từ chối; server
|
|
33
|
+
không lắng nghe trên mọi interface khi nó được định chỉ dùng local.
|
|
34
|
+
|
|
35
|
+
## Test tự động
|
|
36
|
+
|
|
37
|
+
- Khởi động server in-process bằng transport in-memory của SDK khi có, hoặc spawn
|
|
38
|
+
lệnh stdio; kết nối một SDK client; gọi các tool qua client đó.
|
|
39
|
+
- Assert theo cấu trúc, không theo câu chữ chính xác: tên tool, field bắt buộc trong schema,
|
|
40
|
+
field kết quả, cờ `isError` và loại lỗi.
|
|
41
|
+
- Snapshot danh sách tool (tên, tham số bắt buộc, annotation) để việc đổi tên hay đổi schema
|
|
42
|
+
vô tình làm fail một test. Hãy cập nhật snapshot một cách có chủ đích.
|
|
43
|
+
- Thay các service upstream bằng fake ở biên HTTP hoặc biên client; đừng gọi API production
|
|
44
|
+
hay dùng credential thật trong test.
|
|
45
|
+
- Phủ cả timeout và hủy bằng một upstream giả có trễ.
|
|
46
|
+
- Với tool phá hủy, hãy test đường dry-run và test rằng đường thật đòi đúng input mong đợi.
|
|
47
|
+
- Dọn các process con và file tạm trong teardown; một process server bị rò làm CI treo.
|
|
48
|
+
|
|
49
|
+
Khung test tối thiểu:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
setup: start server (in-memory or spawn), create client, initialize
|
|
53
|
+
test: tools/list contains expected names and required params
|
|
54
|
+
test: call get_item {id: known} -> result with id, no isError
|
|
55
|
+
test: call get_item {id: missing} -> isError, message mentions not found
|
|
56
|
+
test: call get_item {} -> invalid input error
|
|
57
|
+
test: list_items paginates with cursor
|
|
58
|
+
teardown: close client, stop server
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Kiểm tra bên trong ALP
|
|
62
|
+
|
|
63
|
+
- Cấu hình server: `alp mcp add <name> --command C --arg A` (stdio) hoặc
|
|
64
|
+
`alp mcp add <name> --url U --header K=V` (HTTP); thêm `--project` cho lớp dự án.
|
|
65
|
+
- `alp mcp test <name>` khởi động server, in tên, version và danh sách tool của nó, rồi dừng
|
|
66
|
+
nó. Fail ở đây thường nghĩa là sai lệnh hay sai `cwd`, thiếu biến môi trường, làm bẩn stdout,
|
|
67
|
+
hoặc khởi động chậm.
|
|
68
|
+
- `alp mcp show <name>` xác nhận mục của lớp nào đang áp dụng.
|
|
69
|
+
- Khai tên server trong `agent.json` của agent (`"mcp": ["<name>"]`) và chạy một task ngắn có
|
|
70
|
+
dùng một tool chỉ đọc; xác nhận lời gọi và kết quả trong log của session.
|
|
71
|
+
- Đừng bao giờ đặt token thật vào một config được commit để làm một test pass; hãy báo
|
|
72
|
+
credential còn thiếu.
|
|
73
|
+
|
|
74
|
+
## Cần báo lại những gì
|
|
75
|
+
|
|
76
|
+
Các lệnh đã chạy và output của chúng (lệnh test, `alp mcp test`), các tool đã kiểm chứng, các
|
|
77
|
+
ca chưa phủ và lý do (ví dụ: không có credential cho API từ xa), và mọi thay đổi schema ảnh
|
|
78
|
+
hưởng tới các agent đang có.
|