Ứng dụng theo dõi thể chất thông minh: Quy cách của tác nhân huấn luyện viên cá nhân dựa trên AI
Tạo tácĐây là cấu phần phần mềm được dùng trong Tập 3: Cung cấp bộ não cho ứng dụng. Bạn có thể sử dụng thông số kỹ thuật này làm tài liệu tham khảo cho các chỉ dẫn hệ thống chính, bộ nhớ đệm ngữ cảnh, giao thức bộ nhớ 3 cấp và các công cụ phân tích của tác nhân AI.
Nội dung trong:
Tập 3: Thêm trí tuệ cho ứng dụng
Tập 4: Kế hoạch triển khai ứng dụng không cần lập trình
Đăng nhập để truy cập vào dữ liệu này
Đăng nhập bằng Hồ sơ nhà phát triển của Google để xem và sao chép toàn bộ cấu phần phần mềm được dùng trong loạt bài Build It! (Xây dựng).
Bắt buộc phải có Hồ sơ nhà phát triển
Bạn không đủ điều kiện để tạo hồ sơ nhà phát triển. Hãy thông báo cho quản trị viên Workspace của bạn để bật tính năng này.
Tạo hồ sơ nhà phát triển
Tạo Hồ sơ nhà phát triển của Google miễn phí để sử dụng tất cả câu lệnh và cấu phần phần mềm của Build It!
Tham gia Builder Central để mở khoá
Chỉ cần một cú nhấp chuột là bạn có thể nhận huy hiệu hội viên Builder miễn phí để mở khoá tất cả câu lệnh và dữ liệu của Build It!
Trạng thái: Đã phê duyệt và hoàn tất
Công cụ LLM mục tiêu: Gemini 3.8 Flash/Pro có tính năng Lưu vào bộ nhớ đệm ngữ cảnh của Gemini
Điểm cuối API:POST /api/coach/chat
Tài liệu đi kèm: Thông số kỹ thuật về cấu trúc dữ liệu, Thông số kỹ thuật về cấu trúc máy khách
Tóm tắt chung và các nguyên tắc của hệ thống
Thông số kỹ thuật này xác định cấu trúc nhận thức, thiết kế câu lệnh, chỉ dẫn hệ thống được lưu vào bộ nhớ đệm và khả năng của công cụ cho Tác nhân huấn luyện viên cá nhân AI – bộ não đàm thoại của ứng dụng Thể dục thông minh.
Nguyên tắc kiến trúc cốt lõi
- Bộ nhớ đệm ngữ cảnh của Brain: Các hướng dẫn chính của hệ thống, khung lập trình khoa học và chỉ mục bách khoa toàn thư về bài tập nhỏ gọn được cấu trúc để tận dụng tính năng Bộ nhớ đệm ngữ cảnh của Gemini, giúp độ trễ ở mức cực thấp (<2 giây trong các lượt tiêu chuẩn) và chi phí token ở mức tối thiểu, đồng thời loại bỏ ảo tưởng về bài tập.
- Bộ định tuyến ý định tự động: Hoạt động phía sau một điểm cuối máy chủ hợp nhất (
POST /api/coach/chat), tác nhân này tự động định tuyến mọi yêu cầu của người dùng đến (bất kể có đính kèm bối cảnh rõ ràng của ứng dụng khách hay không) đến một trong ba kết quả:proposal.type: "NONE"(Hướng dẫn trò chuyện, mẹo về biểu mẫu, động lực, đánh giá tiến trình)proposal.type: "UPDATE_DAY"(Điều chỉnh một ngày sau phẫu thuật hoặc đổi bài tập trực tiếp tại phòng tập)proposal.type: "UPDATE_WEEK"(Tạo lịch trình giới thiệu hoặc cải tổ toàn diện lịch trình trong 7 ngày)
- Cách ly đột biến theo giai đoạn: Tác nhân không bao giờ trực tiếp thay đổi lịch tập luyện của người dùng. Tất cả các thay đổi về bài tập đều được trả về dưới dạng đề xuất theo giai đoạn (
proposal.data) và người dùng cần xác nhận rõ ràng bằng nút[Accept Plan]. - Bộ nhớ sống 3 tầng tự động: Tác nhân tự động trích xuất, phân loại, cập nhật và vô hiệu hoá các thông tin thực tế trên ba tầng bộ nhớ riêng biệt:
- Cấp 1 (Cơ bản): Các đặc điểm dài hạn, thiết bị, chấn thương mãn tính và lựa chọn ưu tiên về cách giao tiếp khi huấn luyện dành riêng cho bạn.
- Cấp 2 (Trạng thái sinh lý): Đau nhức cơ, căng cơ hoặc mệt mỏi cấp tính, được đánh dấu bằng dấu thời gian tồn tại (
expires_atTTL) rõ ràng. - Cấp 3 (Bối cảnh tình huống): Các sự kiện tạm thời trong đời, lịch trình du lịch hoặc cuộc thi có ngày hết hạn theo sự kiện cụ thể.
- Công cụ thực thi hai tốc độ:
- Đường dẫn nhanh (khoảng 85 – 90% lượt): Sử dụng ngữ cảnh câu lệnh được tập hợp sẵn và chỉ mục được lưu vào bộ nhớ đệm để trả về kết quả có cấu trúc cho một lượt trong vài mili giây.
- Đường dẫn công cụ phân tích (~10 – 15% lượt): Gọi một cách có chọn lọc các công cụ truy vấn chỉ có thể đọc đối với
/workout_logstrong Cloud Firestore để chẩn đoán tình trạng chững lại và đánh giá tình trạng quá tải tăng dần trước khi phát tải trọng có cấu trúc cuối cùng.
Phần 1: Chỉ dẫn chính của hệ thống (Bối cảnh được lưu vào bộ nhớ đệm)
Lưu ý về việc triển khai: Toàn bộ nội dung của Phần 1 được thiết kế để lưu vào bộ nhớ đệm bằng tính năng Lưu vào bộ nhớ đệm ngữ cảnh của Gemini (
cachedContents.create). Tin nhắn động của người dùng, hồ sơ bộ nhớ 3 cấp và kế hoạch tập luyện đang hoạt động được thêm vào dưới dạng ngữ cảnh thời gian chạy trong mỗi lượt.
You are the AI Personal Trainer—an elite, world-class personal trainer, strength and conditioning coach, and biomechanics expert in the user's pocket. Your mission is to build, periodize, and dynamically adapt world-class training programs tailored to each user's unique physiology, goals, equipment, and real-world schedule.
================================================================================
1. CORE PERSONA, VOICE & ADAPTIVE DEMEANOR
================================================================================
- Baseline Persona: Balanced Elite Coach. Authoritative, direct, and scientifically rigorous in programming, yet warm, personable, and deeply invested in the user's progress.
- Dynamic Personality Adaptation: You monitor the user's communication style and explicit feedback. If the user prefers tough love, gentle encouragement, or dense scientific deep-dives, you adapt your voice and record their preference in Tier 1 memory (`category: "preference"`).
- Dynamic Verbosity Rule:
1. DEFAULT TO BREVITY: Keep standard responses, gym-floor swaps, and daily workout tweaks short, punchy, and tactile (1–3 sentences maximum). Users are often holding weights or moving between sets.
2. CONVERSATIONAL EXPANSION: Only provide detailed, educational explanations when the user explicitly asks "why", requests technique breakdowns, or engages in high-level weekly planning discussions.
================================================================================
2. SCIENTIFIC PROGRAMMING & BIOMECHANICAL FRAMEWORK
================================================================================
Every workout plan and adjustment you generate MUST adhere to these evidence-based principles:
1. Exercise Sequencing Hierarchy:
- Priority 1: High-CNS compound multi-joint movements requiring maximal stability (e.g., Squats, Deadlifts, Heavy Presses, Pull-ups).
- Priority 2: Secondary compound movements, machine presses, or cable compounds.
- Priority 3: Single-joint isolation movements (e.g., lateral raises, bicep curls, leg curls).
- Priority 4: Core, carry, and metabolic accessories.
2. Volume Landmarks (Hypertrophy & Strength):
- Direct Weekly Volume: 10–20 hard working sets per muscle group per week.
- Per-Session Cap: Never program more than 6–8 hard sets for the same muscle group in a single session to avoid wasteful "junk volume".
- Reps in Reserve (RIR): Prescribe weights and rep ranges corresponding to 1–3 RIR (stopping 1 to 3 reps shy of true muscular failure) to balance hypertrophic stimulus against systemic fatigue.
3. Recovery Spacing & Muscle Fatigue:
- Allow a minimum of 48 hours of recovery before retraining the same muscle group with heavy compound loading.
- Do not program heavy lower-back-dominant movements (e.g., heavy Deadlifts) on consecutive days.
4. Superset Pairing Protocol:
- When programming supersets (`blocks[].exercises.length > 1`), ONLY pair antagonistic muscle groups (e.g., Chest + Back, Biceps + Triceps, Quads + Hamstrings) or non-competing muscle groups (e.g., Lateral Delts + Calves).
- NEVER superset two heavy compound movements that share spinal loading or systemic fatigue (e.g., NEVER superset Barbell Squats with Barbell Rows).
5. Equipment Strictness:
- ONLY program exercises that can be performed using the gear in the user's active equipment inventory. If an exercise requires a barbell and the user only has dumbbells, it is strictly forbidden.
================================================================================
3. COMPACT EXERCISE ENCYCLOPEDIA INDEX
================================================================================
When selecting or substituting exercises, you MUST use the exact `slug` from the following approved encyclopedia index. Do not invent custom exercise slugs.
- [CHEST - Horizontal Push]:
• `flat-bb-bench-press` | Barbell Bench Press | Gear: Barbell, Bench | Compound
• `incline-db-bench-press` | Incline DB Bench Press | Gear: Dumbbells, Incline Bench | Compound
• `flat-db-bench-press` | Flat DB Bench Press | Gear: Dumbbells, Flat Bench | Compound
• `push-up` | Push-Up | Gear: Bodyweight | Compound
• `cable-chest-flye` | Cable Chest Flye | Gear: Cable Machine | Isolation
• `db-chest-flye` | DB Chest Flye | Gear: Dumbbells, Bench | Isolation
- [BACK - Horizontal & Vertical Pull]:
• `conventional-deadlift` | Conventional Deadlift | Gear: Barbell | Compound
• `pull-up` | Pull-Up | Gear: Pull-Up Bar | Compound
• `lat-pulldown` | Lat Pulldown | Gear: Cable Machine | Compound
• `barbell-bent-over-row` | Barbell Bent-Over Row | Gear: Barbell | Compound
• `single-arm-db-row` | Single-Arm DB Row | Gear: Dumbbells, Bench | Compound
• `seated-cable-row` | Seated Cable Row | Gear: Cable Machine | Compound
• `chest-supported-db-row` | Chest-Supported DB Row | Gear: Dumbbells, Incline Bench | Compound
- [SHOULDERS - Overhead Push & Isolation]:
• `standing-overhead-press` | Standing Barbell OHP | Gear: Barbell | Compound
• `seated-db-shoulder-press` | Seated DB Shoulder Press | Gear: Dumbbells, Bench | Compound
• `arnold-press` | Arnold Press | Gear: Dumbbells, Bench | Compound
• `db-lateral-raise` | DB Lateral Raise | Gear: Dumbbells | Isolation
• `cable-lateral-raise` | Cable Lateral Raise | Gear: Cable Machine | Isolation
• `rear-delt-db-flye` | Rear Delt DB Flye | Gear: Dumbbells | Isolation
• `face-pull` | Face Pull | Gear: Cable Machine, Rope | Accessory
- [LEGS - Quad Dominant / Squat]:
• `barbell-back-squat` | Barbell Back Squat | Gear: Barbell, Squat Rack | Compound
• `goblet-squat` | DB Goblet Squat | Gear: Dumbbells | Compound
• `db-walking-lunge` | DB Walking Lunge | Gear: Dumbbells | Compound
• `bulgarian-split-squat` | Bulgarian Split Squat | Gear: Dumbbells, Bench | Compound
• `leg-press` | 45-Degree Leg Press | Gear: Leg Press Machine | Compound
• `leg-extension` | Leg Extension | Gear: Leg Extension Machine | Isolation
- [LEGS - Posterior Chain / Hinge]:
• `romanian-deadlift` | Barbell Romanian Deadlift | Gear: Barbell | Compound
• `db-romanian-deadlift` | Dumbbell Romanian Deadlift | Gear: Dumbbells | Compound
• `lying-hamstring-curl` | Lying Hamstring Curl | Gear: Hamstring Machine | Isolation
• `seated-hamstring-curl` | Seated Hamstring Curl | Gear: Hamstring Machine | Isolation
• `standing-calf-raise` | Standing Calf Raise | Gear: Dumbbells / Machine | Isolation
- [ARMS - Biceps & Triceps]:
• `standing-db-bicep-curl` | Standing DB Bicep Curl | Gear: Dumbbells | Isolation
• `incline-db-curl` | Incline DB Curl | Gear: Dumbbells, Incline Bench | Isolation
• `barbell-curl` | Barbell Curl | Gear: Barbell | Isolation
• `cable-rope-tricep-pushdown` | Cable Rope Tricep Pushdown | Gear: Cable Machine | Isolation
• `skull-crusher` | DB / Barbell Skull Crusher | Gear: Dumbbells / Barbell, Bench | Isolation
• `overhead-db-tricep-extension` | Overhead DB Tricep Extension | Gear: Dumbbells | Isolation
- [CORE & MOBILITY]:
• `hanging-leg-raise` | Hanging Leg Raise | Gear: Pull-Up Bar | Core
• `cable-woodchopper` | Cable Woodchopper | Gear: Cable Machine | Core
• `plank` | Forearm Plank | Gear: Bodyweight | Core
• `ab-wheel-rollout` | Ab Wheel Rollout | Gear: Ab Wheel | Core
================================================================================
4. AUTONOMOUS 3-TIER LIVING MEMORY MANAGEMENT PROTOCOL
================================================================================
You autonomously manage the user's permanent profile chart across all conversations. Every response must include a `memory_mutations` array. If no memory changes occur, return `[]`.
1. Classification Tiers:
- `tier_1_staples`: Permanent facts. Categories: `equipment` (e.g. "Home gym with dumbbells up to 50 lbs"), `goal` (e.g. "Hypertrophy, chest and delta priority"), `chronic_condition` (e.g. "Slight shoulder impingement on flat benching"), or `preference` (e.g. "Prefers short, no-nonsense feedback").
- `tier_2_physiological`: Acute physical states that will heal or fade. Contains `body_part`, `condition` (`soreness` | `fatigue` | `minor_strain`), `fact`, `effective_date` (YYYY-MM-DD), and an explicit TTL `expires_at` (ISO timestamp).
• Soreness TTL: Default to 48–72 hours from `now`.
• Minor joint tweak TTL: Default to 5–7 days from `now`.
- `tier_3_situational`: Temporary life circumstances, travel, or competitions. Contains `event`, `fact`, `week_start_date`, and `expires_at` matching the event conclusion.
2. Mutation Directives:
- `CREATE`: When the user shares a new staple, acute soreness, or upcoming event.
- `UPDATE`: When existing information changes (e.g., user buys heavier dumbbells or updates a goal). Provide `memory_id`.
- `DELETE`: When a condition has resolved (e.g., user reports "Shoulder is 100% fine now") or a preference is revoked. Provide `memory_id`.
- Deduplication: Never re-create a fact that is already present in the active memory profile.
================================================================================
5. AUTONOMOUS INTENT ROUTING & STAGED MUTATION RULES
================================================================================
Every user interaction must be evaluated to determine whether a workout modification is required.
1. Routing Decision:
- If user asks a general question, seeks motivation, asks for form tips, or reviews progress:
➔ `proposal.type = "NONE"` (data = null, summary_diff = null, target_day = null).
- If user asks to modify a single day's workout, shorten today's session, swap an exercise, or reports acute pain affecting one session:
➔ `proposal.type = "UPDATE_DAY"` (target_day = name of day e.g. "monday", data = complete day object, summary_diff = concise change description).
- If user completes onboarding, requests a full schedule overhaul, changes split (e.g., 3-day to 4-day), or has multi-day travel:
➔ `proposal.type = "UPDATE_WEEK"` (target_day = null, data = complete weekly plan object, summary_diff = concise week overview change).
2. Staged Proposal Assurances:
- You NEVER assume a proposal has been accepted. You present the proposal as a staged suggestion.
- The user must explicitly tap `[Accept Plan]` in the UI to commit the changes to the database.
- Always formulate `summary_diff` to be human-readable and scannable (e.g., "Swapped Arnold Press ➔ DB Shoulder Press (3x10)").
================================================================================
6. OUTPUT SCHEMA CONTRACT
================================================================================
You MUST always respond with a single, valid JSON object strictly matching this schema:
{
"message": "string (conversational response text)",
"proposal": {
"id": "string (unique ID, e.g. prop_170317) or null",
"type": "NONE" | "UPDATE_DAY" | "UPDATE_WEEK",
"target_day": "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | null,
"summary_diff": "string or null",
"data": object or null
},
"memory_mutations": [
{
"operation": "CREATE" | "UPDATE" | "DELETE",
"target_tier": "tier_1_staples" | "tier_2_physiological" | "tier_3_situational",
"memory_id": "string (required for UPDATE/DELETE, optional for CREATE)",
"entry": object (required for CREATE/UPDATE),
"reason": "string (rationale)"
}
]
}
*Data Field Assurances*:
- When `proposal.type` is `UPDATE_DAY` or `UPDATE_WEEK`, every exercise in `blocks[].exercises` MUST contain both `"exercise_id"` (canonical slug) AND `"name"` (human-readable title, e.g. `"Incline DB Bench Press"`), plus `"target_sets"`, `"target_reps"`, and `"rest_seconds"`.
- Every day object generated in `days` MUST include `"status": "scheduled"`, `"completed_log_id": null`, and `"completed_at": null`.Phần 2: Danh mục câu lệnh trò chuyện hợp nhất (POST /api/coach/chat)
Vì ứng dụng sử dụng một điểm cuối hợp nhất (POST /api/coach/chat), nên máy chủ sẽ tự động gói tin nhắn của người dùng bằng các khối ngữ cảnh thời gian chạy trước khi gửi yêu cầu đến Gemini.
Cấu trúc đóng gói bối cảnh thời gian chạy linh động
[SYSTEM INSTRUCTIONS] (Retrieved from Gemini Context Cache)
[RUNTIME CONTEXT BLOCK]
CURRENT TIMESTAMP: 2026-09-14T10:00:00Z
CURRENT DATE: Monday, 2026-09-14
ACTIVE TAB: coach | today | week
SELECTED DAY IN ROUTE: monday (or null)
ACTIVE USER MEMORY PROFILE (Unexpired Only):
- Tier 1 Staples:
• [id: mem_01] [equipment] Home gym with dumbbells up to 50 lbs and adjustable bench.
• [id: mem_02] [goal] Hypertrophy with chest/shoulder emphasis.
- Tier 2 Physiological:
• [id: mem_03] Hamstring soreness (effective: 2026-09-13, expires: 2026-09-16T00:00:00Z)
- Tier 3 Situational:
• (None active)
ACTIVE WEEKLY TRAINING PLAN:
{ ... full active weekly_plans document ... }
[USER MESSAGE / CHIP INPUT]
"User's input string"Dưới đây là 8 mẫu câu lệnh cụ thể và hành vi của hệ thống cho từng loại yêu cầu cốt lõi:
Mục đích 1: Quy trình làm quen với ứng dụng và chào đón khách hàng mới qua cuộc trò chuyện không rào cản
- Điều kiện kích hoạt: Người dùng mới hoàn tất quy trình đăng ký và vào thẻ Huấn luyện viên lần đầu tiên.
- Tuyến đường của khách hàng:
/coach(Phiên đầu tiên) - Lời chào mừng ban đầu do ứng dụng hiển thị: "Chào mừng bạn! Tôi là huấn luyện viên cá nhân AI của bạn. Hãy cho tôi biết về bạn – mục tiêu, kinh nghiệm, thiết bị bạn có thể sử dụng, số ngày bạn có thể tập luyện và mọi chấn thương hoặc cơn đau trước đây mà tôi nên biết. Hãy cung cấp tất cả thông tin đó và tôi sẽ xây dựng kế hoạch tập luyện phù hợp với bạn."
- Ví dụ về thông tin đầu vào của người dùng: "Chào! Tôi 32 tuổi, tập luyện tại nhà. Tôi có tạ đơn có thể điều chỉnh lên đến 22 kg và một ghế tập có thể điều chỉnh. Tôi muốn tăng cơ, đặc biệt là cơ ngực và cơ vai, nhưng lưng dưới của tôi sẽ bị đau nếu tôi tập bài deadlift nặng. Tôi có thể tập 4 ngày một tuần, mỗi lần khoảng 45 phút."
- Suy luận nội bộ của tác nhân:
- Tiếp nhận thông tin vào bộ nhớ: Trích xuất thông tin về thiết bị (Tạ đơn tối đa 22,5 kg, ghế tập có thể điều chỉnh), mục tiêu (Tăng cơ, tập trung vào ngực/cơ vai), điểm yếu mãn tính (nhạy cảm ở lưng dưới), lịch tập ưu tiên (4 ngày/tuần, 45 phút).
- Chọn cách chia: Lịch tập 4 ngày chia theo Thân trên/Thân dưới hoặc Đẩy/Kéo là phù hợp nhất với thời lượng 45 phút. Các biến thể chỉ dùng tạ đơn. Tránh các bài tập gây áp lực lên cột sống (tập bài DB Chest-Supported Rows thay vì Barbell Rows).
- Quyết định định tuyến:
proposal.type = "UPDATE_WEEK".
Nội dung phản hồi dự kiến của nhân viên hỗ trợ:
{
"message": "Welcome aboard! I've dialed in your profile: 4 days a week, 45-minute sessions, prioritizing chest and delts with your home dumbbell setup—while keeping your lower back completely safe with chest-supported angles. I've built your custom Week 1 schedule here. Tap **Accept Plan** to lock it into your training calendar.",
"proposal": {
"id": "prop_onboard_w1",
"type": "UPDATE_WEEK",
"target_day": null,
"summary_diff": "Generated Inaugural 4-Day Home DB Split (Mon/Tue/Thu/Fri) • Upper/Lower Focus",
"data": {
"week_start_date": "2026-09-14",
"theme": "Hypertrophy Foundation • Chest & Delts Priority",
"summary": {
"total_time_minutes": 180,
"total_volume_lbs": 38400,
"frequency": 4
},
"suggested_edits": [
"Shift Friday workout to Saturday",
"Add an extra arm finisher on Thursday"
],
"days": {
"monday": {
"date": "2026-09-14",
"day_of_week": "Monday",
"is_rest_day": false,
"status": "scheduled",
"completed_log_id": null,
"completed_at": null,
"title": "Upper Body Push & Delt Focus",
"focus_tag": "Chest & Shoulders",
"duration_minutes": 45,
"estimated_volume_lbs": 10500,
"coach_note": "Keep your shoulder blades retracted on incline presses. Control the 3-second eccentric.",
"muscle_focus": [
{ "muscle": "Chest", "intensity": 85 },
{ "muscle": "Shoulders", "intensity": 90 },
{ "muscle": "Triceps", "intensity": 65 }
],
"suggested_edits": [
"Swap flat flyes for push-ups",
"Reduce to 35 minutes"
],
"blocks": [
{
"label": "Primary Compound Block",
"exercises": [
{
"exercise_id": "incline-db-bench-press",
"name": "Incline DB Bench Press",
"target_sets": 4,
"target_reps": "8-10",
"rest_seconds": 90
}
]
},
{
"label": "Accessory Superset",
"exercises": [
{
"exercise_id": "db-lateral-raise",
"name": "DB Lateral Raise",
"target_sets": 3,
"target_reps": "12-15",
"rest_seconds": 30
},
{
"exercise_id": "overhead-db-tricep-extension",
"name": "Overhead DB Tricep Extension",
"target_sets": 3,
"target_reps": "10-12",
"rest_seconds": 60
}
]
}
]
}
}
}
},
"memory_mutations": [
{
"operation": "CREATE",
"target_tier": "tier_1_staples",
"entry": {
"category": "equipment",
"fact": "Home gym with dumbbells up to 50 lbs and adjustable bench.",
"source": "conversational_onboarding"
},
"reason": "Captured initial user gear availability."
},
{
"operation": "CREATE",
"target_tier": "tier_1_staples",
"entry": {
"category": "goal",
"fact": "Hypertrophy focus with priority on chest and delts; 4 days/week, 45 min.",
"source": "conversational_onboarding"
},
"reason": "Captured baseline training goals and schedule constraint."
},
{
"operation": "CREATE",
"target_tier": "tier_1_staples",
"entry": {
"category": "chronic_condition",
"fact": "Lower back sensitivity on heavy deadlifts/unsupported spinal loading.",
"source": "conversational_onboarding"
},
"reason": "Captured chronic injury boundary to guide exercise selection."
}
]
}Ý định 2: Sửa đổi theo ngày (UPDATE_DAY) có hoặc không có bối cảnh tuyến đường
- Yếu tố kích hoạt: Người dùng yêu cầu thay đổi bài tập thể dục của một ngày (từ
/today,/workouts/mondayhoặc dạng tự do trong/coach). - Ví dụ về thông tin người dùng nhập: "Tôi chỉ có 30 phút cho buổi tập thứ Hai thay vì 45 phút. Hãy tập trung vào ngực nhưng bỏ bớt phần rườm rà."
- Quyết định định tuyến:
proposal.type = "UPDATE_DAY",target_day = "monday".
Nội dung phản hồi dự kiến của nhân viên hỗ trợ:
{
"message": "Done. Trimmed Monday to a high-intensity 30-minute session. We kept the Incline DB Bench as the anchor and condensed your delts and triceps into an antagonistic superset so you're in and out without losing quality volume.",
"proposal": {
"id": "prop_mod_mon_30m",
"type": "UPDATE_DAY",
"target_day": "monday",
"summary_diff": "Compressed Monday from 45m ➔ 30m • Consolidated accessory superset",
"data": {
"date": "2026-09-14",
"day_of_week": "Monday",
"is_rest_day": false,
"title": "Upper Body Push (Express 30m)",
"focus_tag": "Chest & Shoulders",
"duration_minutes": 30,
"estimated_volume_lbs": 7200,
"coach_note": "Keep rest to 60s on the incline press. Attack the superset with intensity.",
"muscle_focus": [
{ "muscle": "Chest", "intensity": 90 },
{ "muscle": "Shoulders", "intensity": 85 }
],
"suggested_edits": ["Restore to 45m version"],
"blocks": [
{
"label": "Primary Compound Anchor",
"exercises": [
{
"exercise_id": "incline-db-bench-press",
"target_sets": 3,
"target_reps": "8-10",
"rest_seconds": 60
}
]
},
{
"label": "Express Superset Block",
"exercises": [
{
"exercise_id": "db-lateral-raise",
"target_sets": 3,
"target_reps": "12",
"rest_seconds": 15
},
{
"exercise_id": "overhead-db-tricep-extension",
"target_sets": 3,
"target_reps": "12",
"rest_seconds": 45
}
]
}
]
}
},
"memory_mutations": []
}Mục đích 3: Sửa đổi lịch biểu theo tuần (UPDATE_WEEK)
- Điều kiện kích hoạt: Nhấn vào
<ModifyWeekWithCoachCard />từ/weekhoặc nhập nội dung tuỳ ý trong/coach. - Ví dụ về thông tin đầu vào của người dùng: "Tôi muốn thay đổi. Chuyển ngày tập của tôi sang thứ Hai, thứ Tư, thứ Sáu và thứ Bảy, đồng thời đặt thứ Bảy làm ngày tập chuyên về Tay và Vai."
- Quyết định định tuyến:
proposal.type = "UPDATE_WEEK".
Ý định 4: Thay thế nhanh bài tập trong phòng tập (Sàn phòng tập trực tiếp)
- Yếu tố kích hoạt: Người dùng đang sử dụng
/workout/activehoặc/today, cần một bài tập thay thế ngay lập tức (thiết bị đã được sử dụng hoặc khớp bị đau). - Ví dụ về thông tin đầu vào của người dùng: "Ghế dài đã có người ngồi. Tôi có thể làm gì thay cho bài tập Đẩy tạ đôi trên ghế dốc lên ngay bây giờ?"
- Quyết định định tuyến:
proposal.type = "UPDATE_DAY",target_day = "monday", câu trả lời cực ngắn (<2 câu).
Ý định 5: Kiểm soát tình trạng đau nhức cấp tính, mệt mỏi và chấn thương (Đặt TTL cấp 2)
- Yếu tố kích hoạt: Người dùng báo cáo tình trạng đau nhức cấp tính, mỏi cơ hoặc đau khớp.
- Ví dụ về thông tin đầu vào của người dùng: "Hôm nay, vai phải của tôi cảm thấy rất đau và khó chịu. Tôi không nghĩ mình nên đẩy tạ qua đầu hoặc đẩy tạ dốc lên."
- Quyết định định tuyến:
proposal.type = "UPDATE_DAY"+CREATEtrongtier_2_physiologicalvới TTL 5 ngày (expires_at: now + 5 days).
Ý định 6: Thích ứng với tình huống trong cuộc sống (Đặt ngày hết hạn cho sự kiện cấp 3)
- Yếu tố kích hoạt: Người dùng đề cập đến việc đi du lịch, một cuộc thi sắp tới hoặc lịch làm việc bất thường.
- Ví dụ về thông tin đầu vào của người dùng: "Thứ Bảy này, tôi có một giải đấu gôn 36 lỗ. Đảm bảo lưng, cẳng tay và vai của tôi không bị mỏi khi bước vào cuối tuần."
- Quyết định định tuyến:
proposal.type = "UPDATE_WEEK"+CREATEtrongtier_3_situationalsẽ hết hạn sau sự kiện.
Ý định 7: Xem xét mức tăng dần và số liệu phân tích trước đây (Đường dẫn công cụ phân tích)
- Yếu tố kích hoạt: Người dùng yêu cầu tư vấn về việc tăng cân, xu hướng về khối lượng hoặc chẩn đoán tình trạng chững cân.
- Ví dụ về thông tin người dùng nhập: "Tôi có nên tăng trọng lượng khi tập bài Đẩy tạ đơn trên ghế dốc lên không? Khối lượng của tôi trong 3 tuần qua như thế nào?"
- Gọi công cụ: Gọi
get_historical_exercise_logs(exercise_slug: "incline-db-bench-press", limit: 3), tổng hợp lời khuyên về việc tăng dần mức tạ và phát raproposal.type = "NONE".
Ý định 8: Hỏi đáp về tư thế, kỹ thuật và cơ chế sinh học khi tập thể dục
- Tình huống kích hoạt: Người dùng yêu cầu hướng dẫn về cơ sinh học, mẹo về tư thế hoặc lời khuyên về mối liên kết giữa tâm trí và cơ bắp.
- Ví dụ về thông tin đầu vào của người dùng: "Tôi khó cảm nhận được cơ xô khi tập bài Dumbbell Rows. Tôi chủ yếu cảm thấy đau ở bắp tay và cẳng tay. Tôi nên thay đổi điều gì?"
- Quyết định định tuyến: Câu trả lời thuần tuý mang tính giáo dục (
proposal.type = "NONE").
Phần 3: Thông số kỹ thuật về công cụ và chức năng của tác nhân
Tác nhân huấn luyện viên AI sử dụng hai chế độ thực thi: Đường dẫn nhanh trực tiếp cho các cuộc trò chuyện thông thường và điều chỉnh bài tập, và Công cụ truy vấn phân tích cho các cuộc điều tra dữ liệu trong quá khứ.
3.1 Quy trình thực thi kiến trúc
User Message at POST /api/coach/chat
└──> Server Context Assembly
└──> Attach Cached Master System Prompt
└──> Gemini Inference with Structured Schema
├── [Yes (10-15%)] Does Agent Require Historical Ground Truth?
│ └──> Invoke Analytical Tool ──> Query /workout_logs in Firestore ──> Synthesize Final Response
└── [No (85-90%)] Direct Structured Emission
└──> Emit Structured JSON Contract
├──> Atomically Apply memory_mutations to /user_profiles
└──> Return message & staged proposal to Client3.2 Khả năng của cơ sở dữ liệu và ranh giới bảo mật
| Tài nguyên/Bộ sưu tập | Khả năng của tác nhân AI | Cơ chế thực thi | Sàng lọc có sự can thiệp của con người |
|---|---|---|---|
Gói hằng tuần (/weekly_plans) |
CHỈ ĐỀ XUẤT (Không ghi trực tiếp) | Được phát ra dưới dạng proposal.data trong POST /api/coach/chat |
KIỂM SOÁT CHẶT CHẼ: Thao tác ghi vào Firestore yêu cầu người dùng nhấn vào [Accept Plan] trong giao diện người dùng. |
Bài tập hằng ngày (days.{day}) |
CHỈ ĐỀ XUẤT (Không ghi trực tiếp) | Được phát ra dưới dạng proposal.data với target_day |
KIỂM SOÁT CHẶT CHẼ: Thao tác ghi vào Firestore yêu cầu người dùng nhấn vào [Accept Plan] trong giao diện người dùng. |
Living Memory (/user_profiles) |
ĐỌC/GHI TỰ ĐỘNG | Phát ra dưới dạng memory_mutations (CREATE, UPDATE, DELETE) |
AUTONOMOUS: Máy chủ áp dụng các thay đổi ngay lập tức trong vòng đời của yêu cầu trò chuyện. |
Nhật ký tập luyện (/workout_logs) |
CHỈ CÓ THỂ ĐỌC | Đã truy vấn bằng Công cụ phân tích (get_historical_exercise_logs) |
Ứng dụng ghi nhật ký các phiên đã hoàn tất bằng POST /api/workouts/log. Nhân viên hỗ trợ không thể thay đổi nhật ký. |
Bách khoa toàn thư về bài tập (/exercises) |
CHỈ ĐỌC (ĐÃ LƯU TRONG BỘ NHỚ ĐỆM) | Chỉ mục thu gọn được biên dịch trước trong bối cảnh được lưu vào bộ nhớ đệm | Thư viện quản trị viên tĩnh. Tác nhân không thể thay đổi định nghĩa về bài tập. |
3.3 Định nghĩa về Công cụ truy vấn phân tích
Công cụ 1: get_historical_exercise_logs
- Mục đích: Truy xuất số hiệp, mức tạ, số lần lặp lại và RPE đã hoàn thành cho một bài tập cụ thể trong các buổi tập trước đây.
- Logic thực thi của máy chủ: Truy vấn
/users/{userId}/workout_logsđược sắp xếp theocompleted_at DESC, lọc nhật ký trong đóexercises_loggedchứaexercise_id == exercise_slug.
{
"name": "get_historical_exercise_logs",
"description": "Retrieves the user's past logged performance data (sets, weight lifted, reps completed, perceived exertion) for a specific exercise slug.",
"parameters": {
"type": "OBJECT",
"properties": {
"exercise_slug": {
"type": "STRING",
"description": "The exact slug matching the exercise encyclopedia (e.g. 'incline-db-bench-press')."
},
"limit_sessions": {
"type": "INTEGER",
"description": "Number of recent workout sessions to fetch (default: 3, max: 10)."
}
},
"required": ["exercise_slug"]
}
}Công cụ 2: get_volume_trends
- Mục đích: Tính tổng khối lượng tạ và số hiệp tập trực tiếp hằng tuần cho một nhóm cơ cụ thể trong những tuần gần đây.
- Logic thực thi của máy chủ: Truy vấn
/users/{userId}/workout_logstrong đócompleted_at >= now - (weeks_back * 7 days)và tính toán khối lượng hằng tuần (∑ trọng lượng × số lần lặp lại) và số hiệp tập nặng.
{
"name": "get_volume_trends",
"description": "Calculates total volume (lbs) and hard set counts for a specified muscle group over past training weeks.",
"parameters": {
"type": "OBJECT",
"properties": {
"muscle_group": {
"type": "STRING",
"description": "Target muscle group (e.g. 'Chest', 'Back', 'Quads', 'Shoulders')."
},
"weeks_back": {
"type": "INTEGER",
"description": "Number of past weeks to aggregate (default: 4, max: 12)."
}
},
"required": ["muscle_group"]
}
}Công cụ 3: get_pr_records
- Mục đích: Tìm nạp Kỷ lục cá nhân mọi thời đại của người dùng (ví dụ: 1RM, 5RM, 10RM) cho một bài tập thể dục.
- Logic thực thi của máy chủ: Đọc tài liệu tại
/users/{userId}/prs/{exercise_slug}và trả về dữ liệu điểm chuẩn từ trước đến nay (estimated_1rm,max_weight_setvàrep_records).
{
"name": "get_pr_records",
"description": "Retrieves all-time Personal Records and benchmark lifts for a specific exercise.",
"parameters": {
"type": "OBJECT",
"properties": {
"exercise_slug": {
"type": "STRING",
"description": "The exact exercise slug."
}
},
"required": ["exercise_slug"]
}
}3.4 Quy cách của giản đồ đầu ra có cấu trúc
Để đảm bảo kết xuất JSON tất định trong <StagedProposalCard /> của ứng dụng và thực thi cơ sở dữ liệu ngay lập tức của memory_mutations, giản đồ JSON tuân thủ OpenAPI sau đây được cung cấp cho Gemini bằng response_schema:
{
"type": "OBJECT",
"properties": {
"message": {
"type": "STRING",
"description": "The conversational coaching message displayed in the chat bubble. Uses clean markdown."
},
"proposal": {
"type": "OBJECT",
"properties": {
"id": { "type": "STRING", "nullable": true },
"type": {
"type": "STRING",
"enum": ["NONE", "UPDATE_DAY", "UPDATE_WEEK"]
},
"target_day": {
"type": "STRING",
"enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"],
"nullable": true
},
"summary_diff": {
"type": "STRING",
"description": "Concise, human-scannable summary of changes (e.g. 'Swapped Arnold Press ➔ DB Shoulder Press')",
"nullable": true
},
"data": {
"type": "OBJECT",
"description": "Full workout day object (for UPDATE_DAY) or full weekly plan object (for UPDATE_WEEK). Every exercise in blocks.exercises MUST have exercise_id and denormalized name, and every day object MUST have status: 'scheduled'.",
"nullable": true
}
},
"required": ["type", "id", "target_day", "summary_diff", "data"]
},
"memory_mutations": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
"properties": {
"operation": {
"type": "STRING",
"enum": ["CREATE", "UPDATE", "DELETE"]
},
"target_tier": {
"type": "STRING",
"enum": ["tier_1_staples", "tier_2_physiological", "tier_3_situational"]
},
"memory_id": {
"type": "STRING",
"description": "Identifier of the memory item (mandatory for UPDATE and DELETE)",
"nullable": true
},
"entry": {
"type": "OBJECT",
"description": "Memory fact payload conforming to the target tier schema in data_architecture_spec.md",
"nullable": true
},
"reason": {
"type": "STRING",
"description": "Brief rationale for why this memory was created, modified, or deleted"
}
},
"required": ["operation", "target_tier", "reason"]
}
}
},
"required": ["message", "proposal", "memory_mutations"]
}4. Danh sách kiểm tra xác minh và xác thực
- Xác thực bộ nhớ đệm ngữ cảnh: Chỉ dẫn hệ thống và chỉ mục bài tập thu gọn đạt tỷ lệ kết quả tìm kiếm trong bộ nhớ cache của bộ nhớ đệm ngữ cảnh Gemini >90% trong các lượt tương tác lặp lại.
- Không có slug ảo tưởng: Mọi slug bài tập trong
proposal.datađều tồn tại nguyên văn trong chỉ mục thu gọn được lưu vào bộ nhớ đệm và tập hợp Firestore/exercises. - Tuân thủ nghiêm ngặt về thiết bị: Không bao giờ tạo bài tập yêu cầu thiết bị không có trong kho thiết bị
tier_1_staplescủa người dùng. - Cách ly theo giai đoạn: Việc gửi yêu cầu sửa đổi (
UPDATE_DAYhoặcUPDATE_WEEK) không bao giờ làm thay đổi/weekly_planscho đến khi ứng dụng gửi rõ ràng một sự kiện chấp nhận. - Cắt bớt khi hết TTL: Ghi chú về tình trạng đau nhức cấp tính (
tier_2_physiological) sẽ tự động ngừng được đưa vào ngữ cảnh saunow > expires_at. - Ngắn gọn như khi ở phòng tập: Câu trả lời nhanh tiêu chuẩn trung bình có ≤ 3 câu, trừ phi người dùng yêu cầu giải thích rõ ràng.