Quy trình phát hành — phiên bản, ghi chú, di trú SDK/spec, feature flags, rollback

1. Vì sao quy trình phát hành cho ChatGPT App phức tạp hơn deploy thông thường

Ở phần trước của mô-đun, chúng ta đã bàn về cách quan sát chất lượng và độ ổn định của App (log, metric, SLO). Giờ hãy xem làm sao tổ chức chính quy trình phát hành để các metric đó không sụp đổ mỗi lần deploy.

Trong ứng dụng web thông thường mọi thứ khá đơn giản: bạn triển khai phiên bản mới của backend và frontend — người dùng tải lại trang và chuyển sang phiên bản mới. Nếu có gì hỏng, thường chỉ cần rollback deploy.

Với ChatGPT App, stack tinh vi hơn. Tối thiểu bạn có bốn lớp sống theo những “vòng đời” khác nhau:

• Manifest và schema của công cụ (MCP tools / OpenAPI);
• Hạ tầng: ứng dụng Next.js và máy chủ MCP/Agents/ACP;
• System‑prompt và các prompt khác;
• Dữ liệu: product feed, thiết lập, config.

Vấn đề là mô hình sống trong “thế giới tinh thần” riêng. Ngữ cảnh chat có thể kéo dài hàng giờ hoặc nhiều ngày. Manifest và mô tả tools được nạp và cache phía OpenAI và không cập nhật tức thời trong mọi cuộc hội thoại đang tồn tại. Nếu bạn thay đổi chữ ký công cụ (ví dụ xóa một trường khỏi input‑schema), thì trong các cuộc chat cũ, mô hình vẫn gửi payload cũ, còn backend mới của bạn sẽ từ chối nó. Hệ quả — lỗi 400, phản hồi lạ trong chat và người dùng rất buồn.

Vì vậy, trong thế giới ChatGPT App, “phát hành” không chỉ là “triển khai một Docker mới”. Đây là sự thay đổi được phối hợp của nhiều lớp, với quản trị phiên bản cẩn thận, feature flags và khả năng rollback.

2. Ma trận phiên bản: cần gắn phiên bản cho những gì

Hữu ích là không chỉ nhìn vào “phiên bản App 1.3”, mà nhìn vào ma trận phiên bản theo từng lớp. Với GiftGenius thì xấp xỉ như sau.

giftgenius-app 1.4.2

tools-schema v1.7

prompt v3.1

feed v2, acp v1.3

Lưu ý, đây là các trục khác nhau. Bạn có thể phát hành phiên bản ứng dụng 1.4.2 trong đó schema của tools vẫn là v1.7, còn prompt chuyển sang v3.2. Điều này nên hiển thị trong log; như vậy sau này dễ truy ra vì sao sau prompt v3.2 tự nhiên tỉ lệ chuyển đổi checkout lại giảm.

Với mã, thuận tiện dùng semver (SemVer): MAJOR.MINOR.PATCH. MAJOR — thay đổi phá vỡ, MINOR — tính năng mới không phá vỡ, PATCH — sửa lỗi. Với các phiên bản giao diện (schema, prompt) logic tương tự: MAJOR báo hiệu breaking change.

Nên tách riêng phiên bản giao diện của tools. Với LLM điều này tối quan trọng: nếu bạn thay đổi hợp đồng công cụ, còn mô hình “nghĩ” hợp đồng vẫn như cũ, là bắt đầu rắc rối. Chính sách thường là: trong bản MINOR chỉ thêm trường tùy chọn mới, không đổi tên/không xóa trường cũ; breaking change — chỉ qua một công cụ mới, ví dụ suggest_gifts_v2.

Giờ khi đã tách các lớp theo phiên bản, hãy xem các phiên bản đó “sống” thế nào trong vòng đời phát hành — từ dev đến prod.

3. Luồng phát hành cơ bản cho GiftGenius

Trước hết, thống nhất về các giai đoạn. Có lẽ bạn đã có các môi trường (từ mô-đun về deploy), nhưng giờ nhìn chúng qua lăng kính phát hành.

Thường tách ra:

• dev — phát triển cục bộ, Dev Mode trong ChatGPT, tunnel;
• staging — giống prod tối đa: cùng loại cơ sở dữ liệu, cùng loại MCP/ACP, nhưng dữ liệu thử và thanh toán sandbox;
• prod — môi trường chạy thật, nơi gắn với ChatGPT App sản phẩm / listing trên Store.

Quy trình có thể như sau:

flowchart TD
  A[Dev: nhánh feature/*] --> B[PR → main]
  B --> C[CI: unit + contract + lint]
  C --> D[Deploy to Staging]
  D --> E[Smoke/E2E + kiểm thử thủ công]
  E --> F[Deploy to Prod]
  F --> G[Quan sát qua metric và log]

Ở mỗi bước chúng ta thêm “cầu chì”. Trong môi trường dev, lập trình viên có thể làm mọi thứ, nhưng mỗi lần merge vào main sẽ kích hoạt CI chạy unit/contract test. Nếu ổn — tự động triển khai lên staging. Ở staging chạy một bộ E2E/smoke ngắn: ví dụ một luồng chọn quà đầy đủ và “giả lập” checkout với cổng thanh toán thử.

Chỉ sau đó mới bấm nút deploy lên prod. Tốt nhất — kèm đánh dấu phiên bản và liên kết tới CHANGELOG. Ở prod vẫn tiếp tục theo dõi p95, error‑rate và metric kinh doanh (tỉ lệ chuyển đổi từ khuyến nghị sang checkout). Nếu sau phát hành có thứ gì sụt — cần có kế hoạch rollback rõ ràng, sẽ bàn bên dưới.

4. Release notes và changelog: cần ghi gì

Nếu không có ghi chú phát hành, sau một tháng bạn sẽ nhìn đồ thị: “vì sao 3 tuần trước p95 checkout của chúng ta tăng gấp đôi?” và trả lời: “không biết, nhưng chúng ta có một bản phát hành lớn”. Không phải chiến lược hay.

Thường có ít nhất hai loại ghi chú.

Changelog nội bộ — kỹ thuật. Dành cho dev, SRE và mọi người xem mã. Ghi rõ có tính năng nào, lỗi nào đã sửa, có breaking changes hay không. Có thể theo tiêu chuẩn Keep a Changelog: các mục Added, Changed, Fixed, Removed.

Release notes bên ngoài — ghi chú dễ đọc cho người dùng và cho Store. Không cần viết “migrate MCP SDK 0.4 → 0.5”; tốt hơn là “Thêm gợi ý cho dịp lễ Thanksgiving”, “Sửa một lỗi hiếm khiến một số món quà không được thêm vào giỏ”.

Ví dụ một đoạn CHANGELOG.md cho GiftGenius:

## [1.4.0] - 2025-11-20
### Added
- Tool mới `suggest_gifts_v2` với hỗ trợ thẻ sở thích.
- A/B test system-prompt mới (flag: GG_PROMPT_V3).

### Changed
- Cải thiện xử lý lỗi ACP checkout (thông điệp thân thiện hơn).

### Fixed
- Sửa lỗi khiến sản phẩm không có ảnh bị ẩn khỏi danh sách gợi ý.

Hữu ích khi lưu kèm phiên bản của prompt ở đâu đó: chỉ cần hash commit của tệp system‑prompt để sau này có thể nhớ: “à, sau prompt b3f9c2d người dùng bấm “Mua” ít hơn”.

5. Di trú SDK và đặc tả: sống trong hệ sinh thái thay đổi nhanh

Hệ sinh thái quanh Apps SDK, MCP và Agents phát triển nhanh: phiên bản SDK mới, thay đổi giao thức MCP, cập nhật ACP, v.v. Điều này tốt (nhiều khả năng mới) nhưng cũng đau: dễ hỏng nhanh.

Pin phiên bản và “không cập nhật đúng ngày phát hành”

Khuyến nghị đơn giản đầu tiên: cố định phiên bản phụ thuộc. Không dùng ^0.4.0, mà là 0.4.0. Với SDK hay thay đổi API (MCP/Agents/Apps SDK) điều này đặc biệt quan trọng. Tôi từng xem các nghiên cứu về chủ đề này, trong đó nhấn mạnh hiện tượng “SDK fatigue” — mệt mỏi vì cập nhật không tương thích liên tục, đặc biệt với những ai để phiên bản trôi nổi (kiểu ^0.4.0) và một ngày đẹp trời dính cả đống lỗi sau khi chạy npm install.

Ví dụ nhỏ:

// package.json (đoạn)
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "0.4.2",
    "@openai/applications-sdk": "0.3.1"
  }
}

Khuyến nghị thứ hai: đừng dồn cả tính năng kinh doanh và di trú SDK lớn vào cùng một bản phát hành. Nếu cần cập nhật MCP SDK từ 0.3.x lên 0.4.x, tốt nhất làm một bản kỹ thuật riêng: đầu tiên nâng SDK, chạy test và ổn định, rồi mới tới luồng checkout mới.

Chiến lược di trú SDK

Thường một kế hoạch hợp lý như sau:

Trong môi trường dev tạo một nhánh riêng upgrade/mcp-sdk-0.4. Cập nhật phụ thuộc, chỉnh mã, chạy toàn bộ unit/contract test, chạy thử luồng chính của GiftGenius qua Dev Mode.

Sau đó triển khai nhánh này lên một URL staging riêng và chạy E2E/smoke. Có thể làm test tải nhẹ: 50–100 lần gọi suggest_gifts liên tiếp.

Nếu ổn — merge vào main, triển khai lên staging chính, chạy smoke thêm lần nữa rồi mới lên prod.

Nếu không — bạn có rollback rõ ràng: đơn giản là không merge nhánh này hoặc hoàn tác nó. Đó là ý nghĩa của việc tách di trú SDK khỏi các bản phát hành sản phẩm.

Di trú schema của tools và API

Phần khó chịu nhất là thay đổi giao diện: mô hình không biết về điều đó tức thời. Các nghiên cứu nhấn mạnh quy tắc quan trọng: “Mở rộng, đừng phá vỡ” (additive‑only). Nếu cần thêm vào suggest_gifts tham số mới interests: string[], hãy để nó là tùy chọn, không bắt buộc; các kịch bản cũ vẫn hoạt động.

Ví dụ tiến hóa Zod schema cho dữ liệu đầu vào:

// v1
const suggestGiftsInputV1 = z.object({
  recipientName: z.string(),
  budget: z.number()
});

// v1.1 (thêm trường tùy chọn)
const suggestGiftsInputV1_1 = suggestGiftsInputV1.extend({
  interests: z.array(z.string()).optional(),
  occasion: z.string().optional()
});

Lưu ý: chúng ta không động vào trường hiện có, chỉ mở rộng thêm.

Nếu thực sự cần phá vỡ hợp đồng (ví dụ thay budget bằng minBudget + maxBudget), tốt hơn tạo công cụ mới suggest_gifts_v2 và nêu trong mô tả rằng đây là bản cải tiến. API cũ có thể giữ ở trạng thái deprecated và dần tắt khi chắc chắn mô hình và người dùng đã chuyển sang.

Di trú dữ liệu: product feed và ACP

Chúng ta đã nói về di trú SDK và schema tools. Product feed — cũng là một hợp đồng. Nếu bạn thay đổi định dạng SKU, đơn vị tiền, bản địa hóa, cần làm điều đó có phối hợp: cập nhật cả schema feed, xử lý trong MCP/ACP và các bộ tiền xử lý. Tài liệu về commerce cho ChatGPT App lưu ý rằng các lỗi trong feed (trường hỏng, trùng lặp, giá lạ) có thể giết chất lượng gợi ý ngay cả khi mã hoàn hảo.

Cách làm điển hình:

1. Trước hết thêm trường mới vào schema feed dưới dạng tùy chọn và dạy GiftGenius dùng chúng nếu có.
2. Sau đó cập nhật pipeline xây feed để nó bắt đầu điền các trường này.
3. Chạy validator feed (contract test cho dữ liệu) và chỉ sau đó mới bắt đầu phụ thuộc vào các trường này trong logic.

6. Feature flags: tách deploy khỏi release

Feature flags — một trong những công cụ sống còn trong thế giới ChatGPT App. Ý tưởng chính: bạn deploy mã, nhưng không nhất thiết bật ngay chức năng mới. Ban đầu nó “sống dưới cờ” — chỉ bật cho dev, hoặc cho 1% người dùng, hoặc tắt hẳn.

Điều này đặc biệt quan trọng khi:

• bạn tung thuật toán gợi ý mới;
• bạn thay system‑prompt (có thể thay đổi mạnh hành vi mô hình);
• bạn kết nối công cụ đắt hoặc chậm;
• bạn thử nghiệm luồng checkout mới.

Cờ đơn giản qua biến môi trường

Ở mức tối thiểu có thể làm cờ qua biến môi trường:

// lib/features.ts
export const isNewRecoEnabled =
  process.env.NEXT_PUBLIC_GG_NEW_RECO === "1";

Sau đó trong mã của công cụ MCP bạn có thể dùng như sau:

if (isNewRecoEnabled) {
  return runNewRecoAlgorithm(input);
}
return runOldRecoAlgorithm(input);

Ưu điểm — đơn giản. Nhược điểm — khó chuyển cờ ở runtime: cần deploy môi trường mới hoặc ít nhất khởi tạo lại.

Helper tập trung có kèm ngữ cảnh

Cách “trưởng thành” hơn — có một helper tập trung, xét không chỉ các cờ toàn cục mà cả ngữ cảnh người dùng (tenant, phân khúc, nhóm A/B).

// lib/featureFlags.ts
type Feature = "new-reco" | "checkout-v2";

type Context = { userId: string; tenantId?: string };

export function isFeatureEnabled(
  feature: Feature,
  ctx: Context
): boolean {
  // có thể có logic: env, DB, dịch vụ cờ bên ngoài
  if (feature === "new-reco") {
    return process.env.GG_NEW_RECO === "1";
  }
  return false;
}

Trong MCP‑handler:

const enabled = isFeatureEnabled("new-reco", { userId });
const result = enabled
  ? await runNewReco(input)
  : await runOldReco(input);

Nếu sau này bạn tích hợp dịch vụ cờ bên ngoài (LaunchDarkly, Statsig, v.v.), chỉ cần đổi cài đặt isFeatureEnabled, không phải toàn bộ mã.

Các kịch bản ví dụ cho GiftGenius

A/B test system‑prompt. Bạn tạo PROMPT_V2 và bật nó cho 10% người dùng có tenantId trong danh sách nhất định. Lúc này công cụ MCP và widget không thay đổi, còn bạn so sánh tỉ lệ chuyển đổi.

Kill‑switch cho công cụ đắt đỏ. Giả sử bạn có một công cụ thực hiện truy vấn ngoài phức tạp (ví dụ đến một mô hình ML gợi ý tốn kém). Nếu dịch vụ bên ngoài này bắt đầu lỗi hoặc đội chi phí, bạn muốn tắt nó trong một giây mà không dừng GiftGenius. Feature flag là cách đơn giản nhất.

Rollout dần dần cho checkout mới. Bạn bật Checkout v2 trước cho nhân viên công ty và vài khách hàng tin cậy. Nếu metric ổn — mở rộng phạm vi cho đến khi bật cho tất cả.

7. Rollback: cách quay lại nhanh khi mọi thứ đang cháy

Ngay cả khi test và cờ đều hoàn hảo, vẫn sẽ có lúc hỏng. Quan trọng là có chiến lược rõ ràng: bạn làm gì trong 5–15 phút đầu tiên sau khi thấy lỗi tăng vọt hoặc metric tụt.

Rollback mã nhanh

Nếu vấn đề là lỗi kỹ thuật thuần túy (NPE, sai biến, URL dịch vụ ngoài không đúng), thường chỉ cần rollback deployment về bản trước. Ví dụ, trên Vercel có rollback tức thời về deployment trước đó.

Nhiệm vụ của bạn — luôn biết deployment nào tương ứng với phiên bản nào và cách rollback nó. Lý tưởng là mô tả trong README cho on‑call: “nếu sau bản 1.4.0 mọi thứ cháy, rollback về deployment X”.

Đòn bẩy nhanh thứ hai — feature flags. Nếu chỉ có tính năng mới (checkout-v2) hỏng, tắt nó bằng cờ sẽ dễ hơn là rollback cả bản phát hành.

Thay đổi nguy hiểm: manifest và schema

Với manifest và schema thì phức tạp hơn. Nếu bạn đưa lên Store manifest mới có schema sai và đã được OpenAI duyệt, rollback có thể mất vài ngày. Lý do đơn giản: mỗi thay đổi manifest cũng phải qua review của OpenAI. Phân tích ở các Store khác nhau nói thẳng rằng thay đổi manifest và schema là bản phát hành “nguy hiểm”, cần chuẩn bị và kiểm thử đặc biệt cẩn thận.

Vì vậy tốt nhất tách ra:

• phát hành an toàn: thay đổi mã MCP/Next.js, chỉnh prompt, tính năng mới ẩn sau cờ;
• phát hành nguy hiểm: thay đổi danh sách công cụ, schema input/output, hợp đồng ACP.

Các bản “nguy hiểm” nên rollout riêng, với kiểm tra bổ sung và có thể chỉ qua Dev Mode và app staging (không công bố lên Store) trước.

Rollback dữ liệu và feed

Với dữ liệu còn khó hơn (và đau hơn). Nếu bạn di trú product feed sang schema mới và đồng thời xóa trường cũ, việc quay lại không phải lúc nào cũng đơn giản. Vì vậy, di trú dữ liệu cần idempotent và có thể đảo ngược: hoặc giữ bản sao cũ, hoặc di trú hai bước (trước hết nhân đôi dữ liệu, sau đó chuyển hướng đọc).

Cách đơn giản — giữ song song trường cũ và mới một thời gian và cho phép chuyển đổi giữa chúng qua feature flag. Nếu có gì hỏng — chỉ cần quay về cách đọc cũ.

8. Thiết kế tối thiểu cho quy trình phát hành của GiftGenius

Hãy ghép tất cả những gì đã nói (phiên bản, di trú SDK, feature flags, rollback) thành một kịch bản thực tế.

Giả sử bạn chuẩn bị phát hành 1.4.0, trong đó:

• thêm công cụ mới suggest_gifts_v2 với input mở rộng;
• bật system‑prompt mới cho một phần người dùng;
• cập nhật MCP SDK từ 0.3 → 0.4;
• thay đổi định dạng product feed (thêm trường tags).

Kế hoạch hợp lý sẽ như sau.

Trước tiên là bản kỹ thuật riêng 1.3.1: cập nhật MCP SDK + chỉnh mã tối thiểu, không đổi schema và tính năng. Chạy CI, staging, smoke test. Nếu ổn định — chạy vài ngày.

Sau đó tạo nhánh feature/reco-v2. Ở đó bạn thêm suggest_gifts_v2 như công cụ mới (giữ suggest_gifts cũ). Input schema của nó chỉ mở rộng theo hướng thêm trường tùy chọn. Chuẩn bị system‑prompt mới nhưng bọc dưới cờ GG_PROMPT_V3. Trong ACP/feed thêm trường tags dưới dạng không bắt buộc và xử lý đọc sao cho khi thiếu trường này mọi thứ vẫn hoạt động.

Trong CI thêm vài contract test mới: suggest_gifts_v2 nhận được cả payload cũ và mới, feed có tags là hợp lệ, nhưng bản ghi cũ không có tags cũng không làm hỏng máy chủ.

Sau khi merge vào main:

• CI chạy unit/contract;
• trên staging chạy 1–2 kịch bản E2E qua công cụ mới;
• bật prompt và công cụ mới chỉ cho tenant thử nghiệm thông qua feature flag.

Theo dõi metric: p95 của công cụ, error‑rate, tỉ lệ chuyển đổi checkout. Nếu ổn — mở rộng cờ cho nhiều người dùng hơn. Và chỉ sau đó, khi đã chắc chắn ổn định, mới cập nhật manifest cho Store (nếu cần) và mô tả quảng bá ứng dụng.

Nếu ở đâu đó mọi thứ hỏng — bạn biết cách quay lại: hoặc tắt cờ bằng tay, hoặc rollback deployment, hoặc trong trường hợp xấu nhất, quay lại phiên bản manifest (nhưng đây là tình huống nên tránh).

9. Những lỗi thường gặp trong quy trình phát hành ChatGPT App

Lỗi số 1: chỉ có một “phiên bản App” trừu tượng thay vì ma trận phiên bản.
Khi bạn chỉ có “GiftGenius v1.4”, nhưng không lưu đâu phiên bản schema của tools, prompt và product feed, bạn sẽ không trả lời được câu hỏi: “sau thay đổi nào thì checkout sụt?” Hãy tách phiên bản theo lớp và log chúng trong log có cấu trúc.

Lỗi số 2: breaking changes trong tools mà không có tên/phiên bản mới.
Đau nhất: đổi tên trường trong input schema hoặc xóa nó mà không đổi tên công cụ. Trong chat cũ mô hình vẫn gửi payload cũ, backend trả 400, GPT bắt đầu “ảo tưởng” trong phản hồi, người dùng không hiểu gì. Mọi thay đổi phá vỡ hãy làm qua công cụ mới (foo_v2) hoặc phiên bản API mới, và giữ giao diện cũ trong giai đoạn chuyển tiếp.

Lỗi số 3: cập nhật SDK “trên đường” tới tính năng.
Kinh điển: bạn thêm tính năng kinh doanh mới và tiện tay nâng @modelcontextprotocol/sdk từ 0.3 lên 0.5 “cho mới”. Kết quả: khi hỏng, không rõ do mã mới, schema mới hay SDK mới. Nên di trú SDK bằng các bản kỹ thuật riêng, với kế hoạch test rõ ràng và khả năng rollback.

Lỗi số 4: thiếu feature flags và kill‑switch tức thì.
Triển khai thuật toán gợi ý mới cho 100% người dùng — thú vị cho đến khi nó cho kết quả lạ hoặc làm sập dịch vụ ngoài. Không có feature flag, đòn bẩy duy nhất là rollback toàn bộ bản phát hành, có thể ảnh hưởng tới cả chục cải tiến vô hại. Hãy làm ít nhất cờ đơn giản qua env hoặc cấu hình nhỏ.

Lỗi số 5: kỳ vọng vào cập nhật manifest “tức thì”.
Hiểu lầm phổ biến — nghĩ rằng vừa đổi tools hoặc openapi.yaml là mô hình ngay lập tức biết schema mới. Thực tế manifest và mô tả tools được cache, và trong chat đang mở có thể sống lâu. Bỏ qua thực tế này dẫn tới bug khó hiểu: chat mới hoạt động, chat cũ thì sập. Hãy lên kế hoạch thay đổi schema với nhận thức này và thử qua Dev Mode và staging trước khi đưa lên Store.

Lỗi số 6: thiếu kế hoạch rollback rõ ràng và tài liệu phát hành.
Nếu không ai trong nhóm trả lời được “làm sao rollback trong 5 phút?”, “chúng ta sẽ rollback về phiên bản nào?”, “làm sao quay lại schema feed cũ?” — coi như không có rollback. On‑call cần một kịch bản ngắn nhưng cụ thể: bấm nút nào, đổi biến nào và xem ở đâu để chắc rollback đã hiệu lực.

Lỗi số 7: phát hành “câm lặng” không có release notes và liên kết tới metric.
Phát hành không có changelog nào — nghĩa là vài tháng nữa sẽ phải đoán mò. Khi p95 bất ngờ tăng, còn tỉ lệ chuyển đổi giảm, bạn sẽ đoán: “lúc đó đã thay đổi gì nhỉ?” Thói quen viết ít nhất ghi chú phát hành tối thiểu và gắn chúng với ngày deploy và phiên bản giúp không chỉ đánh giá chất lượng mà cả đời sống của cả nhóm.