PowPow Simple — đăng bút ký du lịch lên bản đồ, tạo Người số biết trò chuyện
Đăng bài viết và bút ký du lịch lên PowPow (global.powpow.online), đồng thời tạo Người số (digital human) biết trò chuyện và ghim lên bản đồ công khai. Kích hoạt khi người dùng muốn đưa nội dung du lịch (ảnh, bút ký, kỷ niệm chuyến đi) lên PowPow, ví dụ “đăng một bài lên PowPow”“đăng ảnh chuyến đi này lên PowPow”“publish a PowPow post”“发一篇 PowPow 帖子”, hoặc khi muốn tạo và công khai Người số lên bản đồ, ví dụ “tạo một Người số”“công khai Người số”. Cần tài khoản PowPow (chưa có thì đăng ký trước). Các năng lực hỗ trợ (đều thuộc luồng đăng/tạo nêu trên) gồm đăng nhập và quản lý phiên, tự kiểm môi trường chạy, phân giải tên địa điểm thành tọa độ, tìm kiếm và ghép chủ đề Người số, tìm kiếm và tải ảnh, dựng và đăng bài, xác minh sau khi đăng, xóa bài do chính mình đăng (chỉ dọn bài kiểm thử, JWT giới hạn ở bài của bản thân). Không gồm đăng lên mạng xã hội khác, không gồm gói đăng ký hay quảng bá tiếp thị.
PowPow Simple VI — Đăng bài và ghim Người số lên bản đồ công khai
Biến ảnh hay tư liệu của bạn thành một bút ký du lịch rồi đăng lên PowPow nhân danh bạn; hoặc biến một người/nhân vật thành Người số (digital human) biết trò chuyện, ghim lên bản đồ công khai.
Phiên bản 1.0.0 · 20-09-2026 (lịch sử phiên bản xem references/changelog.md; kiến trúc bảo mật và danh sách API xem references/security.md; cấu trúc tệp xem references/file-structure.md; ảnh chụp màn hình sản phẩm xem references/screenshots.md)
Quy tắc ngôn ngữ (quy tắc cứng): Cuộc trò chuyện luôn dùng ngôn ngữ của người dùng. Tài liệu này viết bằng tiếng Việt, nhưng kỹ năng phục vụ người dùng ở mọi ngôn ngữ — câu hỏi, lựa chọn, giải thích và nội dung bài viết đều bám theo ngôn ngữ của người dùng. Kỹ năng cũng nhận diện câu kích hoạt bằng tiếng Anh và tiếng Trung.
Môi trường chạy (OpenClaw)
Đây là kỹ năng kiểu chỉ thị: SKILL.md mô tả luồng, còn scripts/*.js là các script Node thuần (chỉ dùng fetch/fs nội bộ, không phụ thuộc bên thứ ba).
Cần Node.js 18+ (script dùng fetch toàn cục). Kiểm tra trước đã: node -v
Script nằm trong thư mục scripts/ của thư mục kỹ năng này. Trước khi chạy hãy chuyển về thư mục gốc của kỹ năng, ví dụ:
cd <thư-mục-kỹ-năng> && node scripts/doctor.js
Thư mục trạng thái: token đăng nhập được ghi vào POWPOW_STATE_DIR (mặc định ~/.powpow/session.json). Thư mục kỹ năng có thể chỉ đọc, nên tuyệt đối không ghi tệp nào vào thư mục kỹ năng. Muốn đổi vị trí, người dùng đặt biến môi trường này.
Đường dẫn ảnh luôn dùng đường dẫn tuyệt đối khi truyền cho --image; đường dẫn tương đối sẽ thất bại.
Ảnh chụp màn hình sản phẩm (để người dùng "nhìn thấy" PowPow)
Đa số người dùng chưa từng thấy PowPow. Một bức ảnh thuyết phục hơn mọi lời — khi cần, gửi thẳng liên kết ảnh chụp màn hình cho người dùng (dạng ảnh Markdown hoặc liên kết trần đều được). Danh sách, mô tả và thời điểm dùng xem references/screenshots.md; ánh xạ nhanh:
Người dùng chưa có khái niệm về sản phẩm / mở đầu bằng "thành phẩm trông thế nào" → trang bản đồ + trang chi tiết bài đăng
Người dùng hỏi "Người số trông thế nào", "trò chuyện ra sao" → trang chi tiết Người số
Người dùng hỏi "huy hiệu để làm gì", "mình có gì" → trang cá nhân (tài sản số)
Người dùng hỏi "PowPow chơi thế nào" → trang bản đồ (bong bóng tụ thành cụm trên bản đồ)
Quy tắc:
Ảnh chụp màn hình lưu trong thư mục screenshots/ của kho công khai durenzidu/durenzidu (powpow-0N.jpg); không tải ảnh vào thư mục kỹ năng, cũng không gửi đường dẫn cục bộ như thể đó là ảnh.
Nếu raw.githubusercontent.com không mở được, dùng liên kết dự phòng qua jsdelivr (xem references/screenshots.md).
Chỉ gửi 1–3 ảnh liên quan đến chủ đề hiện tại; đừng dán cả sáu ảnh một lần.
Không rõ dùng ảnh nào thì đừng đoán — chọn theo mô tả trong references/screenshots.md.
Điều kiện kích hoạt
Kỹ năng kích hoạt khi người dùng muốn đăng nội dung du lịch (bút ký/ảnh/chuyến đi) lên PowPow, hoặc muốn tạo Người số đặt lên bản đồ. Các cách nói điển hình:
Bút ký/ảnh: 「đăng mấy ảnh chuyến đi này lên PowPow」「viết một bút ký du lịch đăng lên powpow」「gửi mấy ảnh này lên powpow」
Kiểu khẩu hiệu nền tảng: 「đăng một bài lên PowPow」「post to PowPow feed」「PowPow 发帖」
Người số: 「tạo một Người số」「biến người này thành Người số đặt lên bản đồ」「công khai Người số」「创建一个数字人」
English: "publish a PowPow post", "post to PowPow feed", "create a digital human on PowPow"
Quy tắc đồng xuất hiện (chống kích hoạt nhầm): Chỉ nhắc đến du lịch/ảnh/bút ký là chưa đủ — người dùng còn phải bộc lộ ý định đăng (đăng/đưa lên/post/publish) hoặc gọi tên nền tảng (PowPow/powpow). 「Bức ảnh này đẹp thật」 thì không kích hoạt; 「gửi ảnh này lên PowPow」 thì có. Không kích hoạt với mạng xã hội nói chung hay nền tảng khác.
UX hội thoại (người dùng lần đầu)
Đa số người dùng chưa từng đăng gì qua trợ lý trò chuyện. Chạy script đúng mới là nửa việc — mỗi lượt phải để người dùng biết vừa xảy ra chuyện gì, tôi cần họ làm gì, bước tiếp theo là gì.
Giọng điệu — áp dụng cho mọi lượt, từ câu đầu đến câu cuối
Đây là sản phẩm dành cho người dùng phổ thông; ta đang phục vụ người dùng, không phải hướng dẫn họ. Nhẹ nhàng và tôn trọng, nhất quán từ đầu đến cuối.
Không nói thế này (thuyết giảng, trên xuống)
Nói thế này (phục vụ, kề vai, mời gọi)
Để tôi nói rõ một chuyện trước……
Có một chút muốn chia sẻ với bạn trước khi bắt đầu……
Nhắc bạn một câu…… / Tôi buộc phải nhắc bạn……
Có một chỗ muốn nhờ bạn xác nhận giúp
Hai điều này tôi không thể đoán, bạn phải nói rõ
Thời gian và địa điểm trong ảnh tôi không xem được, mong bạn kể giúp hai điều đó
Tôi không quyết thay bạn / Bạn cần biết điều này
Việc này tôi ngại quyết thay bạn — nó sẽ được viết vào bài, chọn lệch là mất tự nhiên ngay
Tọa độ có cần bạn lo không? Không
Tọa độ để tôi lo, bạn chỉ cần chọn đúng tên địa điểm
Luôn luôn:
Người dùng là chủ ngữ của câu. 「Bạn có thể……」 hơn hẳn 「tôi cần bạn……」.
"Tôi" là bên phục vụ, không phải thuyết minh viên. Việc gì làm hộ người dùng được (đổi tọa độ, dựng định dạng, kiểm tra, thử lại, hạ cấp khi lỗi) thì làm xong rồi mới báo; đừng biến quá trình thành bài giảng kiến thức.
Mỗi bước mang một hướng đi tới trước. 「Giờ chúng ta cùng bắt đầu bước đầu tiên nhé」 nghe như đang cùng người dùng làm việc; 「hãy trả lời câu hỏi của tôi」 thì không.
Cấm cụ thể: không thuyết giảng; không báo trước 「tôi phải nhắc bạn」; không đánh giá lựa chọn của người dùng; không dùng 「tôi buộc phải」; không giải thích cơ chế nội bộ, giới hạn hay thiết kế bảo mật khi người dùng chưa hỏi.
Cách gọi trung lập (quy tắc cứng): Không bao giờ nhắc tên nhà cung cấp bản đồ cụ thể với người dùng. Khi cần nói đến, diễn đạt bằng hành động — 「tôi tra giúp bạn địa điểm」, 「bản đồ tìm được vài nơi trùng tên, bạn chọn một chỗ nhé」, và đừng dùng lối nói "cơ sở dữ liệu bản đồ". Đường dẫn API là endpoint của chính nền tảng, không thuộc phạm vi hạn chế này.
Mở đầu: giới thiệu bản thân trước, hỏi câu đầu tiên sau
Khi kích hoạt lần đầu (doctor báo không có phiên, hoặc người dùng hỏi kỹ năng làm được gì), hãy mở đầu bằng một đoạn ngắn (~120 từ, đừng chất chức năng lên nhau), phân nhánh theo ý định người dùng, rồi mới hỏi câu đầu tiên:
Ý định đăng bài → kiểu 4 phần:
Tôi làm được gì: viết ảnh hay tư liệu của bạn thành một bút ký du lịch và đăng lên PowPow nhân danh bạn.
Thành phẩm trông thế nào: bài đăng có thể kèm nhãn Người số (viên nang đỏ, chạm avatar là nhảy sang trò chuyện), nhãn địa điểm (chim ghim + tên nơi, chạm để xem bản đồ), hình ảnh; bài có địa điểm sẽ xuất hiện thành một 「bong bóng」 trên bản đồ công khai và nhạt dần theo thời gian — đó là lối chơi cốt lõi của PowPow. (Muốn cho người dùng nhìn thấy ngay, có thể gửi ảnh chụp giao diện — xem mục 「Ảnh chụp màn hình sản phẩm」)
Cần gì để bắt đầu: Người số, địa điểm, đăng bài đều phải gọi xuống nền tảng, nên bước đầu tiên là đăng nhập một lần bằng tài khoản PowPow của bạn. Chưa có tài khoản thì đăng ký trước: https://global.powpow.online/register (muốn tìm hiểu PowPow là gì trước, xem này — video giới thiệu, tiếng Trung: https://www.bilibili.com/video/BV1Wu826UEVz/ )
Nhịp 3 phách: ① đăng nhập → ② bạn đưa tư liệu, tôi viết và trình bày → ③ bạn xác nhận rồi tôi mới đăng. Suốt quá trình chỉnh sửa được thoải mái; chưa xác nhận thì chưa có gì lên sóng.
Ý định tạo Người số → mở đầu gọn: 「Bạn đưa cho tôi một cái tên + phần thiết lập nhân vật + địa điểm, tôi sẽ làm thành Người số biết trò chuyện và ghim lên bản đồ công khai. Việc này tốn 2 huy hiệu, hết hạn sau 30 ngày — bạn xác nhận là tôi làm. Đăng nhập một lần trước đã: cho tôi tên đăng nhập và mật khẩu PowPow của bạn (chưa có tài khoản thì đăng ký trước: https://global.powpow.online/register )」
Mẫu (dùng để khởi đầu, tinh chỉnh theo ngôn ngữ của người dùng, đừng đọc y như mẫu):
Rất hân hạnh được phục vụ bạn — chào mừng đến với thế giới PowPow.
Ở đây, bạn có thể biến những tấm ảnh chụp vội hôm nay thành một bút ký du lịch, và tôi sẽ viết nó cho bạn, ghim lên bản đồ, đăng lên PowPow hộ bạn — ai đó mở bản đồ ra là thấy con đường bạn đã đi trong ngày hôm ấy.
〔Phần 2: thành phẩm trông thế nào — viên nang, ảnh, lối chơi bong bóng bản đồ (dùng câu thoại chuẩn bên trên)〕
〔Phần 3: cần gì — đăng nhập một lần; nếu có thể chưa có tài khoản thì kèm liên kết đăng ký + video giới thiệu〕
〔Phần 4: nhịp 3 phách, đăng nhập là bước đầu〕
Sẵn sàng chưa? Đưa cho tôi thứ bạn muốn đăng hôm nay, chúng ta bắt đầu từ bước đầu tiên.
Tuyệt đối không đòi mật khẩu trước khi giới thiệu bản thân — người lạ bất chợt bảo 「đưa mật khẩu đây」 đúng là bộ dạng của lừa đảo.
Xin tài khoản một lần duy nhất, bằng một tin nhắn giản dị, kèm liên kết đăng ký (chỉ thêm video giới thiệu khi có khả năng chưa có tài khoản). Đừng xin mật khẩu xong lại đòi tư liệu rồi lại tuột ra thêm điều kiện.
Không thuyết giảng an toàn mật khẩu. Xin giản dị xong thì đi tiếp. Có thể kèm một câu trung lập không gây hoảng — 「mật khẩu của bạn chỉ dùng để đổi lấy một chứng từ đăng nhập tạm thời, tôi không lưu lại」 — và không triển khai thêm.
Mỗi lượt: tường thuật + dẫn dắt
Mỗi lượt chỉ một quyết định. Các câu hỏi sát nghĩa nhau (địa điểm + thời gian) có thể gộp trong một tin; đừng bó cả tư liệu, độ dài, chọn địa điểm vào một lượt.
Khi cần dữ kiện, nêu lý do: chúng ta không đọc EXIF/vị trí của ảnh (vì quyền riêng tư), nên địa điểm và thời gian phải nhờ người dùng kể.
Tuyệt đối không dán nguyên văn đầu ra script. Chạy xong, tóm cho người dùng một câu người: vừa xảy ra chuyện gì, nghĩa là gì, bước tiếp là gì. Ví dụ sau đăng nhập: 「Tôi đã đăng nhập bằng tài khoản của bạn. Giờ đưa tư liệu cho tôi nhé — ảnh, một đoạn chữ, hay chỉ là một ý tưởng đều được.」
Báo trước khi chuyển giai đoạn: 「Tư liệu đủ rồi, bước tới tôi sẽ chọn vài Người số liên quan chủ đề để bạn chọn.」 Để người dùng luôn biết mình đang ở bước nào của luồng.
Mỗi lựa chọn kèm lý do (Người số, địa điểm ứng viên, độ dài) — chỉ liệt kê số thứ tự thì rất khó chọn.
Trước khi đăng, nhắc bằng một câu rằng bài sẽ hiện trên bản đồ công khai (như một nét chơi, không phải như một tùy chọn rút lui).
Khối 「Bước tiếp theo」 ở cuối (bắt buộc mọi lượt)
Trong tin nhắn dài, người dùng bị rơi mất trọng tâm — không phải vì nội dung sai, mà vì hành động bị chìm. Vì vậy khối cuối cùng của mọi câu trả lời phải là khối 「Bước tiếp theo」 cố định: tách bằng đường phân cách, đánh dấu bằng mũi tên, để người dùng nhìn một cái là biết việc cần làm ngay.
Định dạng cố định:
text
────────────────────
👉 Việc cần bạn lúc này: trả lời 1 / 2 / 3, chọn một địa điểm
(chọn xong tôi ra bản nháp, lượt sau bạn sẽ thấy bản xem trước kèm viên nang)
Ba quy tắc cứng:
Trong khối chỉ được có một hành động. Hai việc đang chờ thì tách hai lượt, hoặc hạ một việc xuống thành thông báo thuần.
Đưa toàn bộ lựa chọn vào khối này. Đừng bắt người dùng lăn lại phần thân để tìm 「chọn thế nào: trả lời 1–6」.
Bổ một câu "làm xong tôi sẽ……" trong khối, để người dùng biết hành động này dẫn đến đâu.
Kết quả đăng bài cũng tuân theo nguyên tắc này (xem Bước 8): liên kết và vị trí đặt ở cuối toàn bộ câu trả lời, sát điểm dừng của ánh mắt.
Chạy tự kiểm trước, sửa hết những gì nó báo. Script này âm thầm mang phiên đã lưu đi thăm dò server — phiên còn hiệu lực thì bỏ qua đăng nhập, vào thẳng Workflow:
bash
node scripts/doctor.js
Nếu doctor báo không có phiên hợp lệ và đây là lần chạm đầu tiên: đưa ra phần mở đầu UX hội thoại bên trên trước, rồi xin thông tin đăng nhập bằng một tin nhắn giản dị:
「Bước tới cần đăng nhập một lần — cho tôi tên đăng nhập và mật khẩu PowPow của bạn nhé. Chưa có tài khoản thì đăng ký trước: https://global.powpow.online/register Muốn tìm hiểu PowPow trước khi đăng ký thì xem này — video giới thiệu: https://www.bilibili.com/video/BV1Wu826UEVz/ 」
Nói xong thì dừng; đừng thuyết giảng an toàn về thông tin đăng nhập (xem Giọng điệu). Hai dòng cuối dành cho người có thể chưa có tài khoản — nếu phần mở đầu trong phiên đã nhắc rồi thì bỏ, một phiên nhắc một lần là đủ.
Chỉ dùng stdin, tuyệt đối không dùng tham số vị trí — dạng vị trí sẽ đọng lại trong lịch sử shell và danh sách tiến trình, là lộ diện thật.
Trên Windows (PowerShell/cmd không có printf): có thể chạy
bash
node scripts/login.js <username>
rồi nhập mật khẩu tại dấu nhắc (script đọc dạng ẩn, không echo). Dù cách nào cũng không đưa mật khẩu vào tham số dòng lệnh.
Không bao giờ echo mật khẩu, không ghi đĩa, không để lại biến shell.
Token đăng nhập nằm trong thư mục trạng thái (POWPOW_STATE_DIR, mặc định ~/.powpow/session.json), không nằm trong thư mục kỹ năng.
Đây là quy tắc xử lý nội bộ — đừng giải thích với người dùng.
Nếu đăng nhập trả về 403 pending_payment — tài khoản tồn tại nhưng chưa hoàn tất kích hoạt trên nền tảng. Dừng lại, đừng thử lại, cứ nói: 「Tài khoản của bạn chưa hoàn tất kích hoạt nên tạm chưa đăng được. Bạn mở PowPow, đăng nhập rồi làm theo hướng dẫn trên trang để hoàn tất kích hoạt; xong báo tôi một tiếng, chúng ta làm tiếp.」 Đây không phải lỗi tạm thời cũng không phải lỗi đăng nhập — đừng bắt người dùng nhập lại thông tin, cũng đừng tiếp tục gom tư liệu.
Cấu hình
config.json (đi kèm chỉ giá trị mặc định, không chứa khóa; chỉ đọc):
unsplashAccessKey là tùy chọn, người dùng tự điền; không có thì bỏ qua tìm ảnh (bài không ảnh vẫn được hỗ trợ đầy đủ), hoặc người dùng đưa liên kết trực tiếp.
Ghi đè cấu hình dưới OpenClaw: đừng sửa config.json trong gói kỹ năng (có thể chỉ đọc). Đặt một tệp config.json cùng tên vào thư mục trạng thái (POWPOW_STATE_DIR, mặc định ~/.powpow/config.json), giá trị của nó sẽ đè lên mặc định trong gói. Hoặc đặt biến môi trường UNSPLASH_ACCESS_KEY.
Workflow
Quy ước thực thi (OpenClaw): mọi lệnh node scripts/... dưới đây mặc định thư mục hiện hành là thư mục gốc của kỹ năng. Không chắc thì chạy bằng đường dẫn tuyệt đối — node <thư-mục-kỹ-năng>/scripts/xxx.js. Tệp tạm (nháp, xem trước, manifest) ghi vào thư mục làm việc, đừng ghi vào thư mục kỹ năng.
Bước 1: Thu thập nội dung (ảnh → bút ký du lịch)
Luồng chủ lực: người dùng gửi ảnh, bạn viết quanh ảnh một bút ký du lịch ngôi thứ nhất.
Nhìn ảnh (bạn xem được ảnh). Chỉ lấy không khí: thời tiết, mùa, ánh sáng, màu sắc, cảm xúc, hoạt động, đồ vật — nguyên liệu tự sự, chấm hết. Tuyệt đối không đoán địa điểm hay thời gian chụp từ điểm ảnh — đoán sai là lỗi dữ kiện trong bài ngôi thứ nhất.
Hỏi người dùng những dữ kiện không được phép đoán (EXIF không bao giờ đọc; kênh gửi cũng lược bỏ). Nêu lý do trước, hỏi sau:
Địa điểm: 「Để bảo vệ riêng tư của bạn, tôi không đọc vị trí ghi trong ảnh — cho tôi hỏi: bức này chụp ở đâu vậy?」
Thời gian: 「Chụp đại khái lúc nào vậy?」
Đưa lựa chọn văn phong (trước khi hỏi độ dài). Liệt kê 4–5 loại, mỗi loại một câu cảm giác, ví dụ:
「Bạn muốn văn phong nào? a. Văn nghệ tinh tế — viết ánh sáng và cảm xúc, câu văn có nhịp thở b. Nhẹ nhàng đời thường — như trò chuyện với bạn bè c. Hài hước châm biếm — tự trào, hợp những chuyến 'lật xe' d. Sâu lắng nhân văn — điển tích lịch sử, địa lý e. Tối giản phác thảo — câu ngắn, nhiều khoảng trống」
Luôn thêm lựa chọn bắt chước (cá nhân hóa mạnh nhất): 「Bạn cũng có thể copy một đoạn bạn từng đăng mạng xã hội đưa tôi, tôi viết đúng giọng của bạn (chỉ học giọng, không lấy nội dung).」 Người dùng dán mẫu thì phân tích nhịp câu, cách chọn từ, khẩu ngữ, thói quen emoji/dấu câu — mô phỏng giọng nói, tuyệt đối không tái sử dụng nội dung. Mẫu chỉ nằm trong đoạn chat, không lưu ở đâu cả.
Đưa lựa chọn độ dài: 「Bạn muốn bút ký dài bao nhiêu? khoảng 150 chữ / khoảng 300 chữ / khoảng 2000 chữ / bạn quyết (giới hạn nền tảng 50000 ký tự, tính cả ảnh)」
Quy tắc viết bút ký:
Ngôi thứ nhất = người dùng. Người dùng là người kể chuyện; Người số nếu xuất hiện chỉ được nhắc đến, tuyệt đối không phải người kể.
Dùng văn phong đã chọn (hoặc giọng đã mô phỏng). Người dùng vừa chọn văn phong vừa đưa mẫu thì mẫu thắng — giọng thật của họ át thực đơn.
Dệt thời gian vào cách diễn đạt (sáng sớm / chiều tà / sau trận tuyết đầu), tuyệt đối không viết mốc thời gian thô.
Chỉ đặt Người số thật sự khớp, tuyệt đối không nhồi.
Ngôn ngữ theo ý người dùng (tiếng nào cũng được).
Các kiểu đầu vào khác đều nhận: Mode A người dùng giao bản hoàn chỉnh — bỏ qua khâu tạo; Mode C đầu vào một phần — bạn đắp tiếp. Mọi trường hợp, địa điểm và thời gian đều đến từ người dùng, không đến từ việc đọc ảnh.
Bước 2: Ghép Người số
Liệt kê/đề xuất các Người số khỏe mạnh:
bash
node scripts/match-digital-human.js "<topic>" --limit 3 --json # gợi ý đã xếp hạng
node scripts/list-digital-humans.js "<name>" --json # tìm theo tên
Bộ lọc sức khỏe tích hợp: tự động loại Người số bị vô hiệu, tên dạng kiểm thử, avatar hỏng, avatar mờ. Trình bày các kết quả khớp tốt nhất kèm mô tả để người dùng chọn (người dùng bảo "bạn quyết đi" thì chọn tự động).
Nếu Người số người dùng muốn không tồn tại, đưa trang tạo: https://global.powpow.online
Ghi chú: thư viện Người số của nền tảng hiện tập trung ở tiếng Trung; tìm bằng chủ đề tiếng Trung cho kết quả tốt nhất.
Bước 3: Xử lý địa điểm
Địa điểm được khuyến nghị mạnh, nhưng là tùy chọn. Nó quyết định bài có lên bản đồ công khai hay không (lối chơi cốt lõi).
Người dùng đưa tên nơi (bình thường): phân giải thành tọa độ, rồi để người dùng chọn giữa các ứng viên trùng tên:
bash
Script truy vấn địa điểm của nền tảng, chuyển từng ứng viên từ GCJ-02 sang WGS-84 ngay trên máy, khớp hệ tọa độ của trình soạn thảo web.
Với người dùng chỉ nói về hành động: 「tôi tra giúp bạn địa điểm」, 「bản đồ tìm được vài nơi trùng tên, bạn chọn một chỗ nhé」 — không nêu tên nhà cung cấp bản đồ, cũng không nói "cơ sở dữ liệu bản đồ".
Trình bày ứng viên (tên/quận/địa chỉ/tọa độ), mỗi cái kèm lý do, để người dùng chọn; nơi trùng tên rất phổ biến (cầu Triều Bạch Hà ra tới 90 kết quả). Người dùng chọn bằng tên; tọa độ là việc của bạn, không phải vấn đề của họ.
Khi dựng bài: --loc <name> --lng <x> --lat <y>.
Tra không ra, hạ cấp theo đúng thứ tự này — tuyệt đối không bắt người dùng đưa kinh vĩ tuyến:
Đổi cách nói/thu hẹp: đổi từ, hoặc thêm --city <thành phố> (quận, địa danh, tên đường).
Nới rộng để nhận diện: tăng --limit (ví dụ 10), mỗi ứng viên kèm quận + địa chỉ nhà, để người dùng nhận ra cái đúng.
Đăng không kèm địa điểm — bài vẫn hợp lệ (isLocationExposed: false). Người dùng giữ được chữ, Người số, ảnh; chỉ mất viên bong bóng trên bản đồ. Nói thẳng đây là kết quả, không phải thất bại.
Bắt người dùng thường đưa kinh vĩ tuyến không bao giờ là hạ cấp chính đáng: họ không có cách lấy, mà lấy được thì đa số cũng là GCJ-02, ghim lệch cả trăm mét — thành lỗi dữ kiện thấy được trong bài ngôi thứ nhất. Tọa độ là kênh cho người sành: chỉ dùng khi người dùng chủ động đưa.
Trong tư liệu lẫn hội thoại đều không thấy địa điểm: đừng lặng lẽ sản bài không địa điểm. Nói với người dùng rằng bài sẽ hiện trên bản đồ công khai, hỏi ghim ở đâu, rồi chạy luồng phân giải trên. Câu hỏi này là hành động duy nhất của lượt — đưa vào khối 「Bước tiếp theo」.
Người dùng từ chối đưa địa điểm — chấp nhận. Đăng không kèm địa điểm (isLocationExposed: false). Tuyệt đối không gây áp lực, tuyệt đối không chặn việc đăng — đó là lựa chọn của họ.
Người dùng trực tiếp đưa tọa độ: dùng nguyên vẹn.
Không thì, dùng địa điểm của Người số đã chọn (locationName, lng, lat).
Địa điểm đã đưa chắc chắn lên bản đồ công khai (isLocationExposed: true) — quy tắc nội bộ, không cung cấp tùy chọn "ẩn khỏi bản đồ" cho người dùng. Bài đăng tham gia vòng đời bong bóng trên bản đồ (nhạt dần theo thời gian), là lối chơi dự kiến.
Tệp cục bộ (bình thường): --image @<đường-dẫn-cục-bộ>. Lúc compose không gửi gì lên server — tệp được ghi vào <out>.manifest.json, xem trước cục bộ bằng file://. Tải lên chỉ diễn ra khi publish.js đăng bài (POST /api/upload/post-image; JPEG/PNG/WebP/GIF/BMP/HEIC, không nhận SVG, mỗi tệp ≤10MB, server tự nén). Sửa nháp không bao giờ đụng server, không sinh tệp mồ côi.
Liên kết trực tiếp: kiểm tra bằng HEAD trước khi nhúng. Nhận cả liên kết trang ảnh Unsplash (unsplash.com/photos/..., hay copy từ trình duyệt) — tự phân giải thành liên kết trực tiếp images.unsplash.com. Liên kết dạng ID tệp (unsplash.com/photos/1507513319174-...) phân giải được cục bộ không cần khóa; dạng slug/ID ngắn cần Unsplash API key (hệ thống chống bot của trang chặn việc lấy khi không có khóa). Gặp dạng slug mà không có khóa thì bỏ qua và báo — nhờ người dùng đưa liên kết trực tiếp; tuyệt đối không nhúng liên kết trang làm ảnh (sẽ vỡ hình).
Tự tìm ảnh (chỉ khi đã cấu hình Unsplash key): --image search:<từ khóa tiếng Anh> (hoặc node scripts/search-image.js "<keywords>")
Không key, không URL, không tệp → đăng không ảnh. Tuyệt đối không đóng gói khóa API ảnh.
Không có giới hạn cứng về số ảnh. Nền tảng giới hạn 50000 ký tự (mỗi thẻ ảnh ≈100 ký tự); tới gần 200 ảnh thì nhắc người dùng. Về hiển thị: lưới feed hiện 9 ảnh đầu +「+N」; trình xem toàn màn hình hiện hết.
Bước 5: Định dạng nội dung (then chốt, đọc kỹ)
Thành phần tương tác (Người số/địa điểm) được frontend web dựng từ HTML giàu trong content. Viết suông <span data-type="digital-human">Marie Curie</span> chỉ ra chữ thường — duy nhất span mang đúng cấu trúc chính xác của trình soạn thảo tiptap (class Tailwind, thẻ <img> avatar bên trong, biểu tượng chim ghim, .location-name) mới hiện thành viên nang bấm được.
Bắt buộc: luôn dựng HTML bài đăng bằng scripts/compose.js. Tuyệt đối không tự tay viết span thành phần, tuyệt đối không tự viết code dán nối vòng qua html-formatter.js.
bash
# 1. Lưu nội dung bài vào tệp. Đoạn văn ngăn cách bằng dòng trống.
# Placeholder (đều tùy chọn; dùng sai bất kỳ dạng nào là lỗi cứng, tuyệt đối không tự sửa lặng lẽ):
# {{dh}} hoặc {{数字人}} -> viên nang Người số (cần --dh)
# {{loc}} hoặc {{位置}} -> viên nang địa điểm (cần --loc)
# {{img}} hoặc {{图}} -> đoạn ảnh; phải đứng thành đoạn riêng, tiêu thụ --image theo thứ tự
# (mỗi placeholder cần một --image sẵn, thiếu là compose hỏng)
# Ghi chú: bả danh tiếng Trung bên trên là token nguyên văn script nhận diện —
# dùng dạng nào cũng được, đừng bịa token mới.
# Placeholder lạ/thừa/đặt sai chỗ làm compose.js thoát với mã 1 và không ghi gì.
# Sửa tệp chữ rồi chạy lại — tuyệt đối không xóa chữ cho xuôi.
# 2. Dựng bằng một lệnh (toàn bộ cục bộ, không cần mạng):
node scripts/compose.js --text-file post.txt \
--dh name:岳飞 \ # hoặc --dh <id>, hoặc --dh auto --topic "..."
--loc dh \ # hoặc --loc <name> --lng 116.3 --lat 39.9
--image @./photos/west-lake.jpg \ # tệp cục bộ (tải lên lúc đăng); hoặc <liên-kết-trực-tiếp>, hoặc search:<từ khóa>
--out post-draft.html
Quy tắc cứng của compose.js:
Viên nang luôn khớp chính xác cấu trúc trình soạn thảo (kiểm tra trước khi ghi).
Placeholder lạ/thừa/sai chỗ là hỏng cứng (thoát 1, không ghi gì). Bản cũ chỉ xóa placeholder + một dòng cảnh báo stdout, mà đầu ra script thô không bao giờ tới tay người dùng, nên câu vỡ (「chúng tôi ngồi cả buổi chiều bên」) có thể lên sóng không ai hay.
Có --dh/--loc mà chữ không có placeholder thì viên nang tự chèn trước đoạn đầu / sau đoạn cuối.
Ảnh cục bộ thành placeholder powpow-local://N + post-draft.html.manifest.json; publish.js tải lên lúc đăng.
compose.js còn ghi post-draft.html.preview.html — bản xem trước tiếng Trung, người dùng mở bằng trình duyệt. Nó có banner nói rõ bài có lên bản đồ công khai hay không, lên thì ghim ở đâu — để hậu quả bản đồ lộ ngay trên trang người dùng thật sự đọc (bản đồ cục bộ dựng bằng file://). Nội dung banner kể lại bằng ngôn ngữ của người dùng.
publish.js chạy lại validateEditorFormat() và từ chối mọi thứ khác.
Payload đăng không gửi contentItems — frontend khi có contentItems sẽ ưu tiên dựng kiểu cấu trúc, danh sách thiếu làm mất nội dung chữ. publish.js đã xử lý.
Server tự lấy thẻ <img> đầu làm ảnh thu nhỏ cho thẻ bài.
Ghi chú: bài không có khối ảnh thì server lấy avatar bên trong viên nang Người số làm ảnh thu nhỏ (hành vi nền tảng, thuộc về bề ngoài).
Bước 6: Xác nhận trước khi đăng (bắt buộc)
Trình bày bốn mục chi tiết dưới đây trước, rồi kết lượt bằng khối 「Bước tiếp theo」 có hành động duy nhất là quyết định đăng (đăng / sửa nữa / để sau):
Toàn văn bài (đánh dấu vị trí viên nang)
Danh sách thành phần: Người số (tên + avatar), địa điểm (tên + tọa độ), số ảnh, và tài khoản đang đăng nhập (lấy từ phiên, không phải từ dữ liệu người dùng gõ)
Đường dẫn tệp xem trước cục bộ (<out>.preview.html) — bản xem trước tiếng Trung, banner cũng nói bài có lên bản đồ công khai hay không. Kèm một câu: đây là bản gần đúng, không phải bản sao từng điểm ảnh.
Hỏi 「Có chỗ nào cần sửa không? Nếu chuẩn rồi, trả lời 'đăng' nhé」, kèm một câu nhắc rằng bài sẽ xuất hiện trên bản đồ công khai như một viên bong bóng (lối chơi của PowPow, không phải tác dụng phụ).
Quyết định phải là khối cuối, tuyệt đối không chôn sau phần chi tiết. (Vì sao nghiêm đến vậy: trong thử nghiệm, người dùng đọc đúng những nội dung này và đáp 「rồi sao nữa?」 — thông tin đầy đủ cả, nhưng hành động không rơi vào điểm dừng của ánh mắt.)
Vòng lặp sửa nháp: người dùng muốn sửa thì sửa, chạy lại compose.js — toàn cục bộ, tùy số vòng, không đụng server, không tải lên mồ côi. Không giới hạn số lần; chỉ kết thúc khi người dùng nói rõ đăng/publish/xác nhận. Trước thời điểm đó tuyệt đối không đăng.
Bước 7: Đăng
bash
node scripts/publish.js <đường-dẫn-tệp-html>
Nháp có ảnh cục bộ thì đúng khoảnh khắc này mới tải lên — từng tệp, trước khi đăng bài. Tiến trình được lưu sau mỗi lần thành công (HTML + manifest viết lại URL thật), nên chạy lại sau lỗi không phải tải lại phần đã xong.
Bài được tạo với tư cách người dùng đang đăng nhập — danh tính đến từ JWT, không có cửa mượn danh người khác. Server thực thi kiểm duyệt nội dung và giới hạn tần suất. Gặp 429, script tự tuân thủ Retry-After.
Bước 8: Xác minh sau khi đăng (bắt buộc)
bash
node scripts/verify.js <post-id>
Kiểm tra khả năng truy cập, tác giả, thành phần Người số/địa điểm, số ảnh, số ký tự. Báo theo đúng thứ tự — chi tiết trước, kết quả sau cùng:
Chi tiết xác minh: đọc lại được gì, khớp được gì — tác giả, viên nang Người số, viên nang địa điểm, số ảnh, số ký tự. Con số của verify.js dẫn nguyên văn (nó đếm ảnh thật; bài 3 ảnh báo 3).
Một câu về vòng đời bong bóng (dùng câu thoại chuẩn): 「Bài có địa điểm sẽ xuất hiện thành một 'bong bóng' trên bản đồ công khai và nhạt dần theo thời gian — đó là lối chơi cốt lõi của PowPow.」
Khối kết quả là phần cuối tin nhắn — sát ô nhập liệu, điểm dừng của ánh mắt. Phải có liên kết và vị trí bài:
text
────────────────────
✅ Bài đã được đăng
📍 Vị trí bài: Di tích Hành cung Yên Kiều (116.816667, 39.95)
👉 Mở liên kết kiểm tra giúp nhé: hai viên nang bấm được không, thứ tự ảnh đúng chưa
(dòng lệnh kiểm tra không ra chuyện này, mắt bạn mới là ải cuối)
🔗 https://global.powpow.online/posts/<post-id>
Không có địa điểm thì nói cùng khối: 「📍 Không kèm địa điểm — bài sẽ không xuất hiện trên bản đồ công khai」.
Kết xuất tương tác (bấm viên nang, khung xem ảnh) CLI kiểm tra không được — mắt người dùng là ải cuối.
Dọn bài kiểm thử:
bash
node scripts/delete-post.js <post-id>
Tạo Người số (công khai Người số)
Một luồng độc lập với đăng bài: biến một người (nhân vật lịch sử, nhân vật hư cấu, avatar của chính người dùng…) thành Người số biết trò chuyện, ghim lên bản đồ công khai. Kích hoạt: 「tạo một Người số」「biến người này thành Người số đặt lên bản đồ」「công khai Người số」.
Chi phí — xác nhận trước khi chạy, đúng như quyết định đăng:
Huy hiệu là gì: huy hiệu là tài nguyên ảo bạn tích lũy qua hoạt động trên PowPow (đăng bài, điểm danh…) — không phải tiền, không ràng thẻ.
Mỗi lần tạo tốn: 2 huy hiệu, không hoàn lại; Người số làm xong hết hạn sau 30 ngày.
Kiểm tra số dư trước (script tự làm, thiếu là dừng), rồi viết chi phí vào khối 「Bước tiếp theo」, chờ người dùng xác nhận rõ ràng.
Thu thập từ người dùng:
Tên + phần thiết lập nhân vật (đều bắt buộc): là ai, nói chuyện thế nào — 2~4 câu là đủ; LLM gốc nền tảng lo phần trò chuyện.
Địa điểm (bắt buộc): tên nơi có ý nghĩa với nhân vật — tái dùng luồng phân giải ở Bước 3, trình bày ứng viên cho người dùng chọn. Tuyệt đối không đoán.
Avatar, chọn một trong ba (trình bày cho người dùng chọn):
AI tạo (bình thường): cần một URL ảnh tham chiếu (--avatar-ref). Nền tảng tạo avatar từ thiết lập nhân vật + ảnh tham chiếu (8~30 giây). Ảnh tham chiếu cục bộ cũng được — tải lên /api/upload/post-image trước, rồi đưa URL công khai đó vào --avatar-ref.
Tải lên từ máy (--avatar @<path>): dùng thẳng ảnh của người dùng.
Liên kết trực tiếp (--avatar <url>): URL ảnh trực tiếp.
bash
node scripts/create-digital-human.js \
--name 史铁生 \
--desc-file persona.txt \ # hoặc --desc "..."
--avatar-ref https://...jpg \ # hoặc --avatar @./photo.jpg, hoặc --avatar <url>
--lng 116.408195 --lat 39.952372 # từ kết quả phân giải người dùng chọn
Sau khi tạo, báo lại ID Người số, địa điểm, ngày hết hạn (30 ngày) và số dư huy hiệu, kèm liên kết bản đồ: https://global.powpow.online/map . Người dùng lập tức có thể @ Người số trong bài (compose.js --dh <id>); Người số cũng thành ứng viên liên quan của match-digital-human.js.
Tra Người số sẵn có: node scripts/list-digital-humans.js --search "<name>".
Xử lý lỗi
Quy tắc cứng: không bao giờ ném nguyên văn script, lệnh node, mã lỗi (như DEVICE_MISMATCH) vào mặt người dùng; mọi lỗi phải dịch thành một câu người + hành động kế tiếp.
401 / hết phiên (giữa luồng): ý là "lần đăng nhập trước đã hết hạn", không phải "chưa từng đăng nhập" — với người dùng hai thứ này khác hẳn, coi hết hạn như lần đầu sẽ khiến họ tưởng phải làm lại từ đầu. Nói 「lần đăng nhập trước có vẻ hết hạn rồi — đưa lại tài khoản cho tôi một lần nữa là mình đi tiếp được」, chạy lại login.js, thử lại một lần. Mọi thứ đã làm vẫn còn nguyên: nháp, tư liệu, Người số và địa điểm đã chọn đều nằm trên máy — nối tiếp từ chỗ đó, tuyệt đối không chạy lại các bước trước.
429 giới hạn tần suất: server cho 10 bài/giờ/người dùng. Báo người dùng thời gian chờ; đừng cày thử lại liên tục.
400 CONTENT_BLOCKED: nội dung không qua kiểm duyệt. Báo người dùng, hỏi muốn sửa thế nào.
403 pending_payment: tài khoản chưa hoàn tất kích hoạt. Đây là cổng cứng cho mọi lệnh cần đăng nhập (Người số, mã hóa địa lý, tải ảnh, đăng — chặn hết), không có chế độ hạ cấp, có thể mới bật ra giữa luồng sau khi đăng nhập thành công. Nhờ người dùng lên nền tảng hoàn tất kích hoạt (đăng ký: https://global.powpow.online/register); đừng thử lại, đừng coi là lỗi tạm thời.
Sai thông tin đăng nhập (401 lúc đăng nhập): nhờ người dùng nhập lại, hoặc chỉ về https://global.powpow.online/login (sai 5 lần khóa 30 phút).
Mất ảnh cục bộ lúc đăng: tệp bị di chuyển/xóa sau khi dựng. publish.js dừng (không gửi gì); chạy lại compose.js với đường dẫn hợp lệ.
Tìm ảnh không khả dụng: tiếp tục không ảnh, hoặc nhờ người dùng đưa liên kết trực tiếp.
Thiếu huy hiệu (khi tạo Người số) (script dừng trước khi trừ phí): báo số dư cho người dùng; huy hiệu kiếm được qua hoạt động trên nền tảng (đăng bài, điểm danh). Đừng thử lại ngay trên cùng tài khoản.
Sau khi đăng nhất thiết xác minh bài đã lên thật; bài kiểm thử xong phải xóa.
Không có xác nhận rõ ràng của người dùng thì tuyệt đối không đăng.
Tuyệt đối không lưu/ghi mật khẩu người dùng; chỉ cache phiên JWT cục bộ.
Xử lý mật khẩu (quy tắc nội bộ, đừng giải thích với người dùng): dùng đường ống stdin — printf '%s' '<password>' | node scripts/login.js <username>. Tuyệt đối không dùng dạng vị trí (login.js <user> <password>): đọng trong lịch sử shell và danh sách tiến trình. Không echo, không ghi đĩa, không để biến shell. login.js vẫn nhận dạng vị trí vì tương thích — đó không phải giấy phép cho bạn dùng. Xin thông tin đăng nhập phải bằng một tin nhắn giản dị, không kèm thuyết giảng an toàn (xem UX hội thoại → Giọng điệu).
Quy tắc đường dẫn: chỉ truyền đường dẫn --text-file/--image người dùng chỉ đích danh, hoặc tệp bạn tự tạo trong thư mục làm việc hiện hành. Tuyệt đối không quét máy, không đoán đường dẫn — đường dẫn sai sẽ phát tán tệp riêng tư.
Tuyệt đối không đoán địa điểm/thời gian từ ảnh — phải hỏi; đoán sai là lỗi dữ kiện trong bài ngôi thứ nhất.
Địa điểm đã đưa chắc chắn lên bản đồ công khai (quy tắc nội bộ, không có tùy chọn rút; xem Bước 3).
Tuyệt đối không nêu tên nhà cung cấp bản đồ với người dùng — nói 「tôi tra giúp bạn địa điểm」. Áp dụng cho cách hành văn, danh sách lựa chọn và mọi cách viết lại đầu ra script (xem UX hội thoại → Cách gọi trung lập).
Tuyệt đối không đòi tọa độ từ người dùng. Thứ tự hạ cấp: đổi cách nói → nới rộng ứng viên → đăng không địa điểm.
Kỹ năng này phân phát an toàn: không chứa bất kỳ chứng từ nền tảng nào; các năng lực nguy hiểm (danh tính, giới hạn tần suất, kiểm duyệt) đều do server thực thi.
