Biến một cái tên khách hàng thành đề xuất bán hàng hoàn chỉnhTurn a client name into a complete sales proposal
technext-sales-proposal là một Agent Skill: đưa vào tên công ty, website hoặc một brief ngắn, nhận về một website đề xuất song ngữ (VI/EN) tự chứa — phủ cả ba dòng dịch vụ Odoo ERP, AI Solutions và Social Media Marketing.technext-sales-proposal is an Agent Skill: give it a company name, a website, or a short brief, and it returns one self-contained bilingual (VI/EN) proposal website — covering all three TechNext service lines: Odoo ERP, AI Solutions, and Social Media Marketing.
Khái niệm chínhKey concepts
SKILL.md dạy agent cách làm một việc cụ thể.A folder containing SKILL.md that teaches an agent how to do one specific job.<slug>-checkpoint.json ghi phase nào đã xong, để lần chạy sau resume thay vì làm lại từ đầu.<slug>-checkpoint.json records which phases are done, so a later run resumes instead of rebuilding from scratch.source-auditor (chạy 2 lần — sau phase 0.9 và sau Phase 1) và mechanical-validator phải PASS mới được đi tiếp.A real blocking gate, not an FYI: source-auditor (it runs twice — after phase 0.9 and after Phase 1) and mechanical-validator must pass before the pipeline continues.Đầu ra của một lần chạyWhat one run produces
| Sản phẩmArtefact | Nội dungWhat it is |
|---|---|
| *-proposal.html | Một file HTML duy nhất, toàn bộ CSS/JS/chart inline, mở được qua file:// khi không có mạng.One HTML file with all CSS/JS/charts inlined; opens over file:// with no network. |
| *-findings.json | Dữ liệu nghiên cứu + nguồn, dạng máy đọc được; validator đối chiếu với phần thân bài.Machine-readable research + sources; the validator cross-checks it against the document body. |
| *-cost-report.csv | Chi phí thật theo từng task, lấy từ log phiên của agent.Real per-task cost, read from the agent's own session logs. |
| manifest/icons/sw.js | Bộ PWA đi kèm để mở đề xuất như một app cài được.A companion PWA bundle so the proposal installs like an app. |
Điều skill cố ý không làmWhat the skill deliberately won't do
- Không bịa số. Số không đọc được thì ghi
null+ lý do, không ghi0như thể là dữ liệu thật.No invented numbers. A metric it could not read is written asnullplus a reason — never as0pretending to be data. - Không dùng CDN. Đề xuất giao cho khách phải mở được khi offline.No CDN. A proposal handed to a client must open while offline.
- Không cần API key trả tiền. Định danh doanh nghiệp dùng GLEIF, Wikidata, Companies House, OpenCorporates, SEC EDGAR — đều miễn phí.No paid API keys. Entity lookups use GLEIF, Wikidata, Companies House, OpenCorporates and SEC EDGAR — all free.
- Không vượt tường chặn. Login wall hay Cloudflare thì ghi nhận là nguồn không truy cập được, không tìm cách lách.No bypassing walls. A login wall or Cloudflare means the source is recorded as unreachable, not circumvented.
LICENSE. Repo chỉ chia sẻ cho cộng tác viên được nêu tên.Proprietary software. See LICENSE. The repository is shared with named collaborators only.Chạy nhanhQuick start
Từ repo trống đến đề xuất đầu tiên, không cần API key.From a clean clone to a first proposal, with no API keys.
Cần gìRequirements
| CầnNeed | Vì saoWhy |
|---|---|
| Agent hỗ trợ Agent SkillsAn agent that supports Agent Skills | Claude Code, Codex, OpenCode, GitHub Copilot CLI, Gemini CLI.Claude Code, Codex, OpenCode, GitHub Copilot CLI, Gemini CLI. |
| Python 3.9+ | Validator, bind-check, stitch fragment, báo cáo chi phí. Chỉ dùng thư viện chuẩn.Validation, citation binding, fragment stitching, cost reporting. Standard library only. |
| Node.js 18+ tuỳ chọnoptional | npx ccusage để tính chi phí. Thiếu thì chỉ mất phần báo cáo chi phí.npx ccusage for per-task cost. Without it, only the cost report is skipped. |
| InternetInternet access | Nghiên cứu khách hàng qua Jina Reader (r.jina.ai, không cần key).Client research via Jina Reader (r.jina.ai, no API key). |
Cài đặtInstall
Clone repo ra cạnh (không phải bên trong) thư mục skills của agent, rồi chạy installer:Clone the repo next to — not inside — your agent's skills directory, then run the installer:
git clone https://github.com/aidev3-web/technext-sales-proposal.git
powershell -ExecutionPolicy Bypass -File install.ps1 # Windows
./install.sh # macOS / Linux
Installer tạo liên kết cho skill gốc + 10 sub-skill vào thư mục skills bạn chọn, vì pipeline gọi sub-skill theo tên nên chúng phải tự tìm thấy được. Thư mục thật đang tồn tại sẽ không bị ghi đè — chỉ báo và bỏ qua.The installer links the orchestrator skill plus its 10 sub-skills into the skills directory you choose, because the pipeline dispatches sub-skills by name — they must be discoverable on their own. An existing real folder is never overwritten; it is reported and skipped.
-Destination <path>— chọn thư mục skills; bỏ trống thì installer liệt kê các thư mục nó tìm thấy.pick the skills directory; if omitted the installer lists the ones it finds.-Copy— copy file thay vì tạo liên kết (khi junction/symlink không dùng được).copy files instead of linking (when junctions/symlinks aren't available).-SkipSubSkills/-DryRun— chỉ cài skill gốc / xem trước mà không đụng gì.orchestrator only / preview without touching anything.
Máy mới tinh, chưa có repo: copy nội dung BOOTSTRAP-PROMPT.md đưa cho agent — agent tự cài vào chính nó rồi tự kiểm tra lại.On a fresh machine with no clone yet: hand the contents of BOOTSTRAP-PROMPT.md to the agent — it installs the skill into itself and verifies the result.
Cách chạyHow to run
Chỉ cần nói bằng ngôn ngữ tự nhiên:Just ask in plain language:
làm sales proposal cho <tên khách hàng>
nghiên cứu khách hàng <công ty> rồi làm đề xuất
research <company> + <website> and build a proposal
Mọi sản phẩm của lần chạy được ghi vào _runs/<client-slug>/ — một thư mục cho mỗi khách, để chạy lại giữa chừng vẫn resume được.Every artefact from a run lands in _runs/<client-slug>/ — one folder per client, so an interrupted run can resume.
Trước khi bắt đầuBefore you start
Luồng chạyWorkflow
Đây là cơ chế đang chạy thật, không phải kế hoạch: 1 orchestrator điều phối 4 nhóm nghiên cứu song song, 10 sub-skill, 5 agent definition, và ba cổng chặn nằm trước lúc giao bài.This is the mechanism that actually runs, not a plan: 1 orchestrator driving 4 parallel research groups, 10 sub-skills, 5 agent definitions, and three hard gates placed before anything is delivered.
Đầu vào → hộp đen → đầu raInput → black box → output
Quy trình cần gì để bắt đầuWhat the pipeline needs to start
Chỉ cần mục đầu tiên là đã chạy được.The first item alone is enough to run.
-
Tên hoặc website khách hàngClient name or websiteYêu cầu tối thiểu — "làm sales proposal cho X".The minimum — "build a proposal for X".
-
Ghi chú cuộc gọi khám pháDiscovery-call notes tuỳ chọnoptionalCàng nhiều bối cảnh, phần khuyến nghị càng sát.More context makes the recommendations sharper.
-
Checkpoint JSONCheckpoint JSON tuỳ chọnoptionalCó thì lần chạy sau chỉ chạy lại đúng phần cần.With it, a later run re-runs only what is needed.
Bên trong chạy gìWhat runs inside
Người dùng không nhìn thấy phần này, nhưng nó quyết định chất lượng đầu ra.The user never sees this part, yet it decides the quality of the output.
Người dùng nhận được gìWhat the user receives
Năm sản phẩm bàn giao, mỗi cái gắn với phase đã tạo ra nó.Five deliverables, each tied to the phase that produced it.
HTMLĐề xuất bán hàng song ngữBilingual sales proposal
Một file tự chứa — 40 section, 18 chart, 4 sơ đồ; mở được khi offline.One self-contained file — 40 sections, 18 charts, 4 diagrams; opens offline.
JSONCơ sở dữ liệu phát hiệnFindings database
Claim / section / nguồn / hạng A–D, đã xác nhận — sẵn sàng nạp vào Odoo CRM.Claim / section / source / grade A–D, verified — ready to load into Odoo CRM.
CSVChi phí thật theo từng taskReal per-task cost
Sinh bởi ccusage, một dòng một task.Produced by ccusage, one row per task.
PWABộ file PWA đi kèmCompanion PWA bundle
manifest.webmanifest + service worker + 2 icon — cài được như một app.manifest.webmanifest + service worker + 2 icons — installs like an app.
HTMLBảng điều khiển chi phíCost dashboard
Dựng một lần, nạp nhiều *-cost-report.csv để xem bảng gộp.Built once, loads many *-cost-report.csv files into one merged table.
Sáu giai đoạn, đi từ trên xuốngSix stages, read top to bottom
Mỗi giai đoạn là một dòng: số phase, việc xảy ra, rồi các node tham gia. Ô màu đỏ là cổng chặn — không qua được thì pipeline dừng.Each stage is one row: the phase numbers, what happens, then the nodes involved. Red boxes are hard gates — the pipeline stops if one fails.
-
0
Nhận briefIntakePhase 0
Người dùng đưa tên khách hoặc website; orchestrator chốt slug và mở checkpoint cho lần chạy này.The user supplies a client name or website; the orchestrator fixes the slug and opens the checkpoint for this run.
TriggerTên khách / website / briefClient name / website / brief 0orchestratorChốt slug, mở checkpointFixes slug, opens checkpoint -
0.5
Xác minh & quétVerify & scanPhase 0.5 – 0.7
Chốt đúng pháp nhân trước khi tốn công nghiên cứu, rồi quét site một lần và cache toàn bộ URL liên quan để cả pipeline đọc lại.Pin the legal entity before research spends effort, then scan the site once and cache every related URL for the whole pipeline to reuse.
0.5company-verifierGLEIF + Wikidata 0.6officers-lookupSổ đăng ký công khaiPublic registries 0.7web-osint-scannerQuét site + pre-fetch URLScans site + pre-fetches URLs web-scan.json+ captures/ dùng chung+ captures/ shared downstream -
0.9
Nghiên cứu đối thủCompetitor researchPhase 0.9
Mỗi đối thủ một worker riêng, chạy song song, với budget cứng. Kết quả phải qua cổng 1 trước khi Phase 1 được phép chạy.One worker per competitor, running in parallel, on a hard budget. The output must clear gate 1 before Phase 1 is allowed to run.
0.9competitor-research-worker1 worker / đối thủ, ≤8 fetch, ≤8 phút1 worker / competitor, ≤8 fetches, ≤8 min bind_check.py --factsCổng 1 · chặn trước Phase 1Gate 1 · blocks before Phase 1 -
1
Nghiên cứu fan-outResearch fan-outPhase 1
Bốn nhóm chạy song song, mỗi nhóm tự viết section và chart của mình, đọc từ
captures/thay vì fetch lại trang.Four groups run in parallel, each writing its own sections and charts, reading fromcaptures/instead of re-fetching pages.due-diligence13 section ops-tech3 section delivery-growth5 section tools-documents11 section -
2
Viết & soát nguồnWrite & auditPhase 2 – 2.6
Viết phần mở đầu, rồi tới cổng 2 — cổng soát nguồn. Chưa PASS thì không được ráp trang.Write the front matter, then gate 2 — the source audit. Nothing is assembled before it passes.
2front-matter-writerMở đầu + 3 bài pitchFront matter + 3 pitches source-auditorCổng 2 · chặn việc viếtGate 2 · blocks writing 2.6chart-data-analystChốt số cho 18 chart + 4 sơ đồFixes numbers for 18 charts + 4 diagrams -
3
Ráp trang & kiểm traAssemble & validatePhase 3 – 4
Ráp section vào template, rồi hai lớp kiểm tra cuối trước khi giao: máy kiểm cấu trúc, người đọc kiểm nội dung.Sections are dropped into the template, then two final checks before delivery: a machine checks structure, a person-style read checks content.
3assemblerRáp section vào templateDrops sections into the template mechanical-validatorCổng 3 · 14 checkGate 3 · 14 checks 4bjudgment-reviewerĐọc như ngườiReads it like a person ccusageĐo chi phí từng taskMeasures per-task cost proposal.html+ findings.json + cost CSV + PWA+ findings.json + cost CSV + PWA
Bốn cơ chế làm nó nhanh và đáng tinFour mechanisms that make it fast and trustworthy
captures/; các nhóm đọc cache thay vì fetch lại — cắt hẳn hàng chục phút.The client's site is scanned once and every related URL lands in captures/; groups read the cache instead of re-fetching — removing tens of minutes.
source-auditor soát từng trích dẫn và gộp nguồn trùng gốc, judgment-reviewer đọc bằng mắt người.A machine checks structure (14 checks), source-auditor re-checks every citation and collapses duplicate origins, and judgment-reviewer reads it like a person.
Ba cổng chặnThe 3 hard gates
Cổng chặn nghĩa là pipeline dừng, không phải chỉ ghi chú lại rồi đi tiếp.A hard gate means the pipeline stops, not that it takes a note and moves on.
Một đoạn trích sai ở đây sẽ chảy vào hai section cùng lúc (Group A và Group C), nên nó bị chặn ngay sau Phase 0.9 thay vì để phát hiện muộn.A bad excerpt here would land in two sections at once (Group A and Group C), so it is stopped right after Phase 0.9 instead of being caught late.
bind_check.py xác nhận từng đoạn trích thật sự nằm trên trang được dẫn; mọi phát hiện phải được gắn nguồn, gắn nhãn .assess, hoặc trả về cho nhóm sở hữu sửa. Chưa PASS thì không được viết hay ráp trang.bind_check.py confirms every excerpt really appears on the page it cites; each finding must be properly sourced, tagged .assess, or sent back to its owning group to fix. Nothing is written or assembled before it passes.
Chạy validate-proposal.py với 14 check đếm được — manifest chart, markup trích dẫn, placeholder, tính nhất quán với findings.json, không CDN, và chart có thật sự vẽ được hay không.Runs validate-proposal.py's 14 countable checks — chart manifest, citation markup, leftovers, findings.json consistency, no CDN, and whether the charts actually paint.
Chi tiết 12 phaseThe 12 phases in detail
| PhasePhase | Ai làmOwner | Sản phẩmArtefact |
|---|---|---|
| 0 Nhận briefIntake | orchestrator | tên khách + slugclient name + slug |
| 0.5 Xác minh pháp nhânCompany verification | company-verifier | company-identity.json |
| 0.6 Tra ban lãnh đạoOfficers lookup | officers-lookup | officers.json |
| 0.7 Quét web/OSINTWeb/OSINT scan | web-osint-scanner | web-scan.json + captures/ |
| 0.9 Nghiên cứu đối thủCompetitor research | competitor-research-worker ×N | competitor-research/*.json |
| 1 Nghiên cứu fan-outResearch fan-out | 4 research agents | p1-group{A..D}.html |
| 2 Phần mở đầuFront matter | front-matter-writer | p2-frontmatter.html |
| 2.5 Soát nguồnSource audit | source-auditor | audited-findings.json |
| 2.6 Dữ liệu chartChart data | chart-data-analyst | chart-manifest.json |
| 3 Ráp trangAssembly | assembler | <slug>-proposal.html |
| 4a Kiểm tra máyMechanical validation | mechanical-validator | 14 check, exit code14 checks, exit code |
| 4b Review phán đoán + chi phíJudgment review + cost | judgment-reviewer | *-cost-report.csv |
= có cổng chặn. checkpoint-manager chạy xuyên suốt: quyết định phase nào cần chạy lại và ghi lại tiến độ sau mỗi phase. = carries a hard gate. checkpoint-manager runs throughout: it decides which phases need to re-run and records progress after each one.
Quy tắc chi phíCost rule
Mỗi task tách riêng ghi session_id của chính nó. Task chạy ngay trong session của orchestrator (Phase 0.5, 0.7, 2, 2.5, 2.6, 3, 4) ghi shared_session: true — nhờ vậy chi phí của chúng không bị mất, và dashboard không báo sai là "thiếu dòng chi phí".A separately dispatched task records its own session_id. Tasks that run inline in the orchestrator's session (Phases 0.5, 0.7, 2, 2.5, 2.6, 3, 4) record shared_session: true — so their cost is not dropped, and the dashboard no longer flags them as having a missing row.
Công cụTools
Skill gốc không tự làm hết — nó gọi 10 sub-skill và 5 agent definition, mỗi thứ một việc.The orchestrator does not do the work itself — it dispatches 10 sub-skills and 5 agent definitions, one job each.
10 sub-skillThe 10 sub-skills
| Sub-skillSub-skill | Việc nó làmWhat it does |
|---|---|
| company-verifier | Chốt đúng pháp nhân trước khi tốn công nghiên cứu: tên pháp lý, domain chính thức, quốc gia, còn hoạt động không — qua API LEI miễn phí của GLEIF, bổ sung Wikidata.Pins the exact legal entity before research spends effort: legal name, official domain, country, active status — via GLEIF's free LEI API, supplemented by Wikidata. |
| officers-lookup | Tra giám đốc/ban lãnh đạo/người sáng lập từ sổ đăng ký công khai (Companies House, OpenCorporates, SEC EDGAR) — ghi officers.json để agent nghiên cứu không phải đoán tên người.Resolves directors/officers/founders from official public registries (Companies House, OpenCorporates, SEC EDGAR) — writes officers.json so research agents never guess a named person. |
| web-osint-scanner | Đọc website khách từ đầu đến cuối qua Jina Reader, trích mọi link liên quan (social, review, báo chí, đối tác), rồi pre-fetch một lần cho cả pipeline.Reads the client's site end to end via Jina Reader, extracts every related link (social, review, press, partner), then pre-fetches once for the whole pipeline. |
| checkpoint-manager | Quyết định phase/group/section nào thật sự cần chạy, và đọc/ghi file checkpoint để lần chạy sau resume thay vì làm lại.Decides which phase/group/section actually needs to run, and reads/writes the checkpoint file so a later run resumes instead of rebuilding. |
| source-auditor | Cổng chặn cứng: soát lại toàn bộ findings của 4 nhóm, chạy bind-check miễn phí, gộp nguồn trùng một gốc, chấm lại độ tin cậy.A hard gate: re-checks all four groups' findings, runs the free bind-check, collapses sources that trace to one origin, and re-grades confidence. |
| chart-data-analyst | Một chỗ duy nhất quyết định số cho cả 18 chart + 4 diagram, thay vì mỗi nhóm tự bịa giá trị riêng.One place decides the numbers for all 18 charts + 4 diagrams, instead of each group inventing its own values. |
| front-matter-writer | Viết Overview, Executive Summary, Recommendations và 3 bài pitch giải pháp trực tiếp từ digest của 4 nhóm — không cần thêm nghiên cứu.Writes Overview, Executive Summary, Recommendations and the 3 solution pitches straight from the four groups' digests — no extra research. |
| assembler | Trích đúng khối <section> từ file preview của từng nhóm và đặt vào bản template mới, theo đúng thứ tự sidebar cố định.Extracts the finished <section> blocks from each group's preview file and drops them into a fresh template copy, in fixed sidebar order. |
| mechanical-validator | Chạy validate-proposal.py — 14 check đếm được, có exit code.Runs validate-proposal.py — 14 countable checks with an exit code. |
| judgment-reviewer | Soát bằng phán đoán: spot-check trích dẫn, phản biện kiến trúc/lộ trình/khuyến nghị, phát hiện section mỏng — rồi báo cáo chi phí thật theo từng task.Judgment-based pass: citation spot-check, devil's-advocate review of architecture/roadmap/recommendations, thin-section detection — then the real per-task cost report. |
Agent definitionAgent definitions
| AgentAgent | Phụ tráchResponsible for |
|---|---|
| research-due-diligence-agent | Due Diligence + Strategic Analysis (13 section)Due Diligence + Strategic Analysis (13 sections) |
| research-ops-tech-agent | Operations (3 section)Operations (3 sections) |
| research-delivery-growth-agent | Competitive Intel + Growth (5 section)Competitive Intel + Growth (5 sections) |
| tools-documents-agent | Tools & Documents (11 section)Tools & Documents (11 sections) |
| competitor-research-worker | Một đối thủ mỗi worker, có budget cứng: ≤8 lần fetch, ≤8 phút.One competitor per worker, with a hard budget: ≤8 fetches, ≤8 minutes. |
tools: và model: — đó là quy ước của Claude Code. Với agent khác, phần dùng được là nội dung của file (nghiên cứu gì, sở hữu section/chart nào, trả về gì); hãy diễn đạt lại tool/model bằng cơ chế của agent đó. Nếu agent không có khái niệm sub-agent, chạy tuần tự 4 nhóm và ghi rõ trong checkpoint rằng lần chạy này không fan-out.Portability note. The 5 agent definition files use tools: and model: frontmatter — Claude Code's own convention. Under another agent, the portable part is the file's body (what to research, which sections/charts it owns, what to return); re-express the tool/model choice with that agent's own mechanism. If the agent has no sub-agent concept, run the 4 groups in sequence and state clearly in the checkpoint that the run did not fan out.ScriptScripts
| FileFile | ViệcJob |
|---|---|
| assets/validate-proposal.py | 14 check cơ học, exit code 0/1. Cần 2 tham số: file HTML và findings.json.14 mechanical checks, exit code 0/1. Takes two arguments: the HTML file and findings.json. |
| skills/source-auditor/assets/bind_check.py | Xác nhận đoạn trích thật sự có trên trang nguồn; có chế độ --facts và --from-cache.Confirms an excerpt really appears on its source page; supports --facts and --from-cache modes. |
| assets/stitch_group.py | Ghép fragment của một nhóm vào template thành trang preview mở được trong browser — không cần đưa cả template ~250KB vào context của agent.Stitches one group's fragments into the template as a browser-openable preview page — without putting the whole ~250KB template into an agent's context. |
| skills/judgment-reviewer/assets/ccusage_to_csv.py | Sinh báo cáo chi phí CSV từ log phiên; gộp các task chia sẻ session thành một dòng nhãn shared-session:.Produces the CSV cost report from session logs; groups tasks that share a session into one shared-session: row. |
| skills/judgment-reviewer/assets/cost-dashboard.html | Một file HTML dựng một lần, nạp nhiều file *-cost-report.csv và hiển thị bảng gộp kèm tổng.A single HTML file, built once, that loads any number of *-cost-report.csv files and shows a merged table with a grand total. |
| install.ps1 / install.sh | Cài skill gốc + 10 sub-skill vào thư mục skills của agent.Installs the orchestrator plus 10 sub-skills into an agent's skills directory. |
Quy trình đóng góiPackaging process
Mục tiêu: người khác và agency cài được, chạy được, và không nhìn thấy dữ liệu khách hàng thật.Goal: other people and agencies can install it, run it, and never see a real client's data.
Mục tiêuGoal
- Giao được: một repo private, cài bằng 1 lệnh, chạy trên agent bất kỳ hỗ trợ Agent Skills.Hand-off ready: one private repo, one-command install, runs on any agent that supports Agent Skills.
- Không rò dữ liệu: không tên khách thật, không
session_idthật, không output đề xuất thật trong gói.No data leakage: no real client names, no realsession_id, no real proposal outputs inside the package. - Truy vết được: mọi thay đổi đều có CHANGELOG + tag semver.Traceable: every change carries a CHANGELOG entry and a semver tag.
Các bướcSteps
- Làm sạch dữ liệu khách. Tên khách thật trong tài liệu demo được đổi thành
client-nova/client-delta/client-orchid; mộtsession_idthật bị xoá.Scrub client data. Real client names in demo documents becameclient-nova/client-delta/client-orchid; a realsession_idwas removed. - Chốt gì vào gói.
demo/(đề xuất của khách thật) và_runs/(sản phẩm mỗi lần chạy) bị loại khỏi git; file vẫn còn trên máy nhưng bị gitignore.Decide what ships.demo/(real client proposals) and_runs/(per-run artefacts) were dropped from git; the files stay on disk but are ignored. - Giấy tờ gói. Thêm
README.md,QUICKSTART.md,CHANGELOG.md,LICENSE(độc quyền).Package documents. AddedREADME.md,QUICKSTART.md,CHANGELOG.md, and a proprietaryLICENSE. - Installer.
install.ps1/install.shliên kết skill gốc + 10 sub-skill, có-Copy,-SkipSubSkills,-DryRun, và không bao giờ ghi đè thư mục thật.Installers.install.ps1/install.shlink the orchestrator plus 10 sub-skills, with-Copy,-SkipSubSkills,-DryRun, and never overwrite a real folder. - Chuẩn hoá line-ending.
.gitattributesgiữ LF trên mọi nền tảng để một checkout mới không bị đổi toàn bộ file.Line-ending hygiene..gitattributeskeeps LF on every platform so a fresh checkout does not rewrite every file. - Trung lập hoá agent. Đường dẫn riêng của Claude, hướng dẫn chỉ dùng
WebFetch, và tên model Claude-only được thay bằng câu chữ trung lập.Agent-neutral wording. Claude-only paths,WebFetch-only fetch instructions and Claude model names were replaced with tool-neutral wording. - Phát hành. CHANGELOG + tag semver, push
main+ tag, rồi mirror sang SKILL-LIB.Release. CHANGELOG entry + semver tag, pushmainand the tag, then mirror to SKILL-LIB.
Lịch sử phát hànhRelease history
| TagTag | Nội dungWhat changed |
|---|---|
| v1.0.0 | Bản đóng gói đầu tiên: README, QUICKSTART, LICENSE, installer, .gitattributes, cost dashboard, loại demo/, xoá tên khách thật.First packaged release: README, QUICKSTART, LICENSE, installers, .gitattributes, cost dashboard, demo/ dropped, real client names removed. |
| v1.0.1 | Thêm BOOTSTRAP-PROMPT.md — prompt để agent trên máy mới tự cài skill vào chính nó.Added BOOTSTRAP-PROMPT.md — a prompt that lets an agent on a new machine install the skill into itself. |
| v1.1.0 | Báo cáo chi phí phủ cả phase chạy inline (trước đó một run thật mất $0.4817 trong tổng $1.1150); brand Technext → TechNext; quy tắc ghi output vào _runs/<slug>/.Cost reporting now covers phases that run inline (a real run previously hid $0.4817 of $1.1150); brand Technext → TechNext; made the _runs/<slug>/ output rule explicit. |
| v1.1.1 | Sửa lỗi toàn bộ chart trắng. Khung chart được đưa lên <head> để luôn định nghĩa trước mọi section; sửa một lỗi cú pháp JS (+ thay vì ,); thêm check 14 — "chart có thật sự vẽ được".Fixed every chart rendering blank. The chart framework moved into <head> so it is always defined before any section; fixed a JS syntax error (+ instead of ,); added check 14 — "charts are actually wired up". |
| v1.1.2 | Sửa SKILL.md còn ghi "13 hard checks" sau khi v1.1.1 thêm check thứ 14.Corrected SKILL.md, which still said "13 hard checks" after v1.1.1 added the 14th. |
Trong gói có gìWhat's in the package
SKILL.md orchestrator map — start here
agents/ 5 sub-agent definitions
skills/ 10 sub-skills the pipeline dispatches
assets/ proposal-template.html, validate-proposal.py,
stitch_group.py, menu-structure.md, section-shell.md,
charts-and-diagrams.md, research-rules.md, PWA files
install.ps1 / install.sh install the skill + its 10 sub-skills
BOOTSTRAP-PROMPT.md self-install prompt for a fresh machine
README / QUICKSTART / CHANGELOG / LICENSE
main + 5 tag (v1.0.0 → v1.1.2)Còn thiếu — nói thẳngKnown gaps — stated plainly
| Vấn đềIssue | Ảnh hưởngImpact |
|---|---|
| Không có test và không có CINo tests and no CI | Sửa template có thể lại làm trắng 18 chart mà không ai biết — đúng loại lỗi đã xảy ra ở v1.1.1.A template edit can silently blank all 18 charts again — exactly the class of bug fixed in v1.1.1. |
| Còn đồ nội bộ trong góiInternal tooling still in the package | api/answers.js (serverless function, cần GITHUB_TOKEN), blocker/answers.json (dữ liệu test đã commit), report/* (tài liệu review nội bộ).api/answers.js (a serverless function needing GITHUB_TOKEN), blocker/answers.json (committed test data), report/* (internal review documents). |
| Validator chưa kiểm nội dung ngữ nghĩaValidator doesn't check semantics | Chưa kiểm: số trên chart có khớp dữ liệu không, cặp t-vi/t-en có đủ không, palette đã đổi chưa, sidebar có đúng thứ tự không.Not yet checked: whether chart numbers match the data, whether every string has both t-vi/t-en, whether the palette was overridden, whether the sidebar order matches. |
| Agent definition còn phụ thuộc Claude CodeAgent definitions still Claude-Code-shaped | Trên Codex/Gemini phải chạy tuần tự 4 nhóm, mất lợi thế fan-out.On Codex/Gemini the 4 groups must run in sequence, losing the fan-out advantage. |
| Chưa chạy benchmark end-to-endNo end-to-end benchmark yet | Chưa xác minh trên máy sạch chỉ có Codex.Not yet verified on a clean machine running Codex only. |
Báo cáo demo runDemo run report
Một lần chạy thật, số liệu lấy từ checkpoint và báo cáo chi phí của chính lần chạy đó.One real run, with numbers taken from that run's own checkpoint and cost report.
Thông tin runRun facts
Kết quả pipelinePipeline results
| Cổng chặnGate | Kết quảResult |
|---|---|
| Competitor facts (sau 0.9)Competitor facts (after 0.9) | PASS 36 bound / 22 partial / 0 unbound |
| Source audit (2.5)Source audit (2.5) | PASS 463 bound / 17 partial / 0 unbound / 0 unreachable — trên 480 trích dẫn |
| Mechanical validator (4a)Mechanical validator (4a) | PASS exit 0 |
| Chart vẽ được (check 14)Charts paint (check 14) | PASS 18/18 canvas có Chart instance, 0 blank |
Check 14 và con số "18/18 vẽ được" được xác minh bằng browser headless thật, không chỉ bằng regex.Check 14 and the "18/18 paint" figure were verified in a real headless browser, not just by regex.
Chi phíCost
8 task được dispatch riêng, theo casa-escondida-cost-report.csv:The 8 separately dispatched tasks, per casa-escondida-cost-report.csv:
Tổng 8 dòng: $0.6333. Nhưng con số đó chưa phải toàn bộ pipeline: 4 task chạy inline trong session orchestrator (0.5, 0.7, 2.5, 2.6) không có session_id nên không có dòng chi phí — checkpoint của chính lần chạy này ghi rõ như vậy.Those 8 rows total $0.6333. That is not the whole pipeline: 4 tasks ran inline in the orchestrator session (0.5, 0.7, 2.5, 2.6) with no session_id, so they have no cost row — the run's own checkpoint says exactly this.
shared_session: true; dashboard gộp chúng thành một dòng nhãn shared-session:. Ước tính khi tính đủ, lần chạy này rơi vào khoảng $1.1 — tức CSV cũ đã bỏ sót gần một nửa chi phí.This is exactly the bug v1.1.0 fixed. From v1.1.0 on, inline tasks record shared_session: true, and the dashboard merges them into one shared-session: row. Counting everything, this run lands around $1.1 — the old CSV hid almost half the cost.Số liệu, nhìn bằng biểu đồThe numbers, visualised
Sáu biểu đồ, sáu kỹ thuật HTML/CSS/SVG khác nhau — tất cả đều vẽ bằng CSS và SVG nội tuyến, không thư viện, không CDN, nên file vẫn mở được offline.Six charts, six different HTML/CSS/SVG techniques — all drawn with inline CSS and SVG, no libraries and no CDN, so the file still opens offline.
- phase1_groupA26.2% · $0.1659
- phase1_groupD21.5% · $0.1363
- phase1_groupC20.9% · $0.1322
- phase1_groupB16.1% · $0.1021
- competitor_altamare4.9% · $0.0308
- competitor_buceo4.2% · $0.0266
- competitor_saltitude3.6% · $0.0229
- competitor_eaglepoint2.6% · $0.0165
- Bound — trích dẫn khớp trang nguồnBound — excerpt matches its source page463
- Partial — khớp một phần, gắn nhãn
.assessPartial — partly matches, tagged.assess17 - Unbound — không tìm thấy trên trangUnbound — not found on the page0
- Tổng đã soátAudited in total480
<canvas> mà check 14 xác nhận có Chart instance thật trong browser headless — đúng lỗi "18 chart trắng" mà v1.1.1 sửa. Bốn ô gạch chéo là 4 sơ đồ, không tính vào check 14.The 18 green cells are the <canvas> elements that check 14 confirmed carry a real Chart instance in a headless browser — exactly the "18 blank charts" defect v1.1.1 fixed. The four hatched cells are the 4 diagrams, which check 14 does not cover.shared_session: true (v1.1.0) sinh ra để bịt, và cũng là lý do mọi biểu đồ chi phí ở đây đều ghi rõ "8 dòng đã ghi" chứ không nói "tổng chi phí".The run really cost around $1.1, but the CSV only records $0.6333 — nearly half the spend was invisible. That is the gap shared_session: true (v1.1.0) was built to close, and the reason every cost chart here says "8 rows recorded" rather than "total spend".Số liệu gốc phía sau sáu biểu đồThe raw numbers behind the six charts
| Hạng mụcItem | Số liệuValue | NguồnSource |
|---|---|---|
| phase1_groupA | $0.1659 | casa-escondida-cost-report.csv |
| phase1_groupB | $0.1021 | casa-escondida-cost-report.csv |
| phase1_groupC | $0.1322 | casa-escondida-cost-report.csv |
| phase1_groupD | $0.1363 | casa-escondida-cost-report.csv |
| competitor_buceo | $0.0266 | casa-escondida-cost-report.csv |
| competitor_saltitude | $0.0229 | casa-escondida-cost-report.csv |
| competitor_altamare | $0.0308 | casa-escondida-cost-report.csv |
| competitor_eaglepoint | $0.0165 | casa-escondida-cost-report.csv |
| Tổng 8 dòng đã ghiTotal of the 8 recorded rows | $0.6333 | casa-escondida-cost-report.csv |
| Ước tính khi tính đủ cả 4 task inlineEstimated including the 4 inline tasks | ~$1.1 | casa-escondida-checkpoint.json |
| Trích dẫn boundCitations bound | 463 / 480 | audited-findings.json |
| Trích dẫn partialCitations partial | 17 / 480 | audited-findings.json |
| Trích dẫn unboundCitations unbound | 0 / 480 | audited-findings.json |
| Chart vẽ đượcCharts that paint | 18 / 18 | validate-proposal.py check 14 |
| Sơ đồ (không tính vào check 14)Diagrams (not covered by check 14) | 4 | casa-escondida-proposal.html |
Sự cố & cách sửaIncidents & fixes
| Sự cốIncident | Nguyên nhân gốcRoot cause | Xử lýFix |
|---|---|---|
Toàn bộ 18 chart trắng. Đủ 18 thẻ <canvas> trong DOM nhưng không chart nào vẽ.All 18 charts blank. All 18 <canvas> elements present in the DOM, none of them painted. | Template định nghĩa regChart/mkChart trong script nằm sau mọi section, trong khi mỗi section gọi regChart(...) ngay tại chỗ — 18 lần ReferenceError. Thêm một lỗi cú pháp JS (+ thay vì ,) làm cả một khối script không chạy.The template defined regChart/mkChart in a script placed after every section, while each section called regChart(...) inline — 18 ReferenceErrors. A second JS syntax error (+ instead of ,) stopped another script block from running at all. | v1.1.1 Dời khung chart vào <head>, sửa cú pháp, thêm check 14. File giao được rebuild: 18/18 chart vẽ, 0 blank.Moved the chart framework into <head>, fixed the syntax, added check 14. The delivered file was rebuilt: 18/18 paint, 0 blank. |
| Sai số học ở bảng báo giá. Các dòng cộng lại 196 person-day / PHP 1,666,000 nhưng dòng TOTAL và mọi số suy ra đều ghi 194 / 1,649,000.Quotation arithmetic wrong. The line items summed to 196 person-days / PHP 1,666,000 but the TOTAL row and every derived figure said 194 / 1,649,000. | Lỗi tính toán khi sinh section, không cổng tự động nào bắt được vì đó là số học, không phải cấu trúc.A computation error while generating the section; no automated gate caught it because it is arithmetic, not structure. | judgment review Review phán đoán bắt được; sửa cả HTML lẫn chart-manifest.json (tranche 30/30/30/10, tỉ lệ Odoo, dữ liệu cRoi/cRevMix đều được tính lại).The judgment review caught it; both the HTML and chart-manifest.json were corrected (tranches, the Odoo share, and the cRoi/cRevMix data were all recomputed). |
Thiếu registration cho chart. Phase 2.6 phát hiện Group A có canvas nhưng không có lời gọi regChart().Missing chart registrations. Phase 2.6 found Group A had canvases but no regChart() calls. | Việc sinh chart bị làm muộn và thủ công, tách khỏi lúc viết section — đây cũng là nguồn gốc của sự cố chart trắng ở trên.Chart generation happened late and by hand, detached from writing the sections — also the origin of the blank-chart incident above. | đã vá trong runpatched in-run 12 registration còn thiếu được sinh và chèn vào đúng section.The 12 missing registrations were generated and inserted into the owning sections. |
| Báo cáo chi phí thiếu gần một nửa.Cost report missed nearly half the spend. | Task chạy inline không có session_id nên không được ghi dòng nào.Inline tasks had no session_id, so they produced no row at all. | v1.1.0 Ghi shared_session: true và gộp thành một dòng trong dashboard.Records shared_session: true and merges them into one dashboard row. |
Kết luậnVerdict
Chứng minh được: pipeline chạy hết 12 phase trên một khách thật; hai cổng nguồn chặn được lỗi trước khi vào bài (0 unbound trên 480 trích dẫn); bản giao là một file HTML tự chứa, song ngữ, 18 chart vẽ được, không CDN; chi phí đo được theo từng task.What it proves: the pipeline completes all 12 phases on a real client; the two sourcing gates catch defects before they reach the document (0 unbound across 480 citations); the deliverable is one self-contained bilingual HTML file with 18 working charts and no CDN; and cost is measurable per task.
Chưa chứng minh được: lỗi chart trắng lọt qua cả một cổng chặn và tới tay người dùng — nghĩa là cổng thứ ba kiểm tra cấu trúc nhưng chưa kiểm tra hành vi render; đúng lỗ hổng mà check 14 sinh ra để bịt. Và vì gói chưa có test/CI, một sửa đổi template trong tương lai vẫn có thể gây lại đúng lỗi đó.What it does not prove: the blank-chart defect passed through a hard gate and reached the user — meaning the third gate checked structure but not render behaviour; exactly the hole check 14 was written to close. And because the package has no tests or CI, a future template edit can reintroduce the same defect.
Đây là lý do việc ưu tiên tiếp theo là bộ test + CI, chứ không phải thêm tính năng.This is why the next priority is a test suite plus CI, not more features.
Trở ngại hiện tạiCurrent obstacles
Đây là danh sách những thứ đang chặn, không phải roadmap. Mỗi mục đều có bằng chứng đo được và một lời giải đã chạy thứ thật — không phải đề xuất trên giấy.These are the things that block us today, not a roadmap. Each one carries measured evidence and a solution that was actually test-run — not a paper proposal.
Trở ngại 1 — không đọc được review trên mạng xã hộiObstacle 1 — reviews on social platforms can't be read
Đây là vấn đề khó nhất của cả skill, và nó không nằm ở code — nó nằm ở chỗ các nền tảng không cho đọc. Review là loại dữ liệu giá trị nhất (tiếng nói thật của khách), nhưng cũng chính là loại bị khoá chặt nhất. Đã đo trực tiếp trên máy này:This is the hardest problem in the whole skill, and it is not a code problem — it is that the platforms refuse to be read. Reviews are the most valuable data we could gather (real customer voice) and also the most tightly locked. Measured directly on this machine:
| Nền tảngPlatform | Cách thửHow we tried | Kết quảResult | Đọc đượcRead |
|---|---|---|---|
| Facebook (page) | Jina Reader | trang đăng nhập, 3.9 KBlogin page, 3.9 KB | no |
| Facebook (mbasic) | Jina Reader | vẫn là trang đăng nhậpstill the login page | no |
| fetch thẳngdirect fetch | HTTP 400 | no | |
| Jina Reader | HTTP 403 | no | |
| TripAdvisor | Jina Reader | CAPTCHA | no |
| TikTok | oEmbed | HTTP 429 | no |
| .json | HTTP 403 | no | |
| g2.com | Jina Reader | HTTP 200 nhưng body rỗng + cảnh báo CAPTCHA (DataDome sau Cloudflare)HTTP 200 with an empty body + CAPTCHA warning (DataDome behind Cloudflare) | âm thầmsilently |
| Meta Ad Library | direct | HTTP 200 | yes |
| Google Maps (place) | Jina Reader | HTTP 200 nhưng chỉ có tile bản đồ — 0 reviewHTTP 200 but only map tiles — 0 reviews | no rev. |
| Brave Search | HTML | HTTP 200 — rating, số review, xếp hạng, trích đoạn nguyên vănHTTP 200 — rating, review count, ranking, verbatim excerpts | yes |
| Bing Search | HTML | HTTP 200 nhưng gần như không có kết quả hữu íchHTTP 200 but almost no useful results | no |
| DuckDuckGo (html) | HTML | HTTP 202 — trang chống botHTTP 202 — bot-detection page | no |
| Google Search | qua Jinavia Jina | “Just a moment…” Cloudflare | no |
| Wayback Machine | availability API | API báo có snapshot; tải nội dung trả 429API reports a snapshot exists; fetching content returns 429 | chập chờnflaky |
| Wayback (qua Jinavia Jina) | Jina Reader | HTTP 403 — Jina chặn domain tới 2035HTTP 403 — Jina blocks the domain until 2035 | no |
g2.com thử thêm bằng Chrome headless thật: vẫn thất bại (2,595 bytes). cf-browser-rendering của Cloudflare thì cần API key trả tiền.g2.com was also tried with a real headless Chrome: it still failed (2,595 bytes). Cloudflare's own cf-browser-rendering needs a paid API key.
Vì sao pipeline hiện tại làm nó tệ hơnWhy the current pipeline makes it worse
Phase 0.8 (web-osint-scanner) đẩy mọi URL tìm được qua Jina Reader và lưu text vào captures/<sha1>.md; captures/manifest.json chỉ có hai trường: file và fetched_at. Không có khái niệm "bị chặn". Nghĩa là một trang đăng nhập được cache y hệt một trang nội dung thật, rồi cả 4 nhóm nghiên cứu đọc lại nó như dữ liệu đã kiểm chứng. Cộng với việc một chỉ số không đọc được dễ bị ghi thành 0, ta có thể giao cho khách một con số sai thay vì một khoảng trống trung thực.Phase 0.8 (web-osint-scanner) pushes every discovered URL through Jina Reader and stores the text in captures/<sha1>.md; captures/manifest.json carries just two fields: file and fetched_at. There is no notion of "blocked". So a login page is cached exactly like a real content page, and all four research groups then read it as if it were verified data. Combined with the ease of writing 0 for a metric that could not be read, we can hand a client a wrong number instead of an honest gap.
0 cho một chỉ số không đọc được. Phải là null kèm lý do. Một chỉ số thiếu thì sửa được; một chỉ số sai thì phá cả bản đề xuất.Rule already agreed: never write 0 for a metric that could not be read. It must be null with a reason. A missing number can be fixed; a wrong number destroys the whole proposal.Lời giải — bốn lớp, đã kiểm chứng bằng thử nghiệm thậtThe solution — four layers, verified by real tests
Không phải đề xuất trên giấy: mỗi lớp dưới đây đều đã được chạy thử từ máy này, kèm kết quả đo được và cả chỗ nó hỏng.Not a paper proposal: every layer below was actually run from this machine, with measured results and the places it still breaks.
-
1
Thu hoạch từ chỉ mục tìm kiếm — chạy được ngay, không cần quyền gìHarvest from a search index — works today, needs no permissionđã chạy đượcverified working
Brave Search trả HTTP 200 và cho ngay thứ mình cần: điểm đánh giá, số lượng review, xếp hạng, và trích đoạn nguyên văn của review. Nó cũng là cách tìm ra URL gốc — trang TripAdvisor, page Facebook của khách — mà không phải mò. Nguyên tắc: không mở trang bị chặn, chỉ đọc phần mà chỉ mục công khai đã lưu sẵn.Brave Search returns HTTP 200 and hands over exactly what we need: the rating, the review count, the ranking, and verbatim review excerpts. It is also how we find the canonical URLs — the TripAdvisor page, the client's Facebook page — without guessing. The principle: never open the blocked page, only read what the public index already stored.
Chỗ hỏng đo được: Brave bắt đầu trả
429sau 2–4 truy vấn liên tiếp. Nên thiết kế phải có giãn nhịp + cache, và khi chạy thật thì dùng Brave Search API (có key, có free tier) thay vì đọc HTML.Measured failure: Brave starts returning429after 2–4 back-to-back queries. So the design needs pacing plus a cache, and in production it should use the Brave Search API (keyed, with a free tier) rather than scraping HTML. -
2
API chính thức bằng token của chính khách hàng — cửa duy nhất để có review đầy đủ và mớiOfficial APIs with the client's own token — the only door to full, current reviewscần khách cấp quyềnneeds client consent
Chỉ mục tìm kiếm cho trích đoạn; chỉ API mới cho toàn văn, đủ số lượng, và mới nhất. Meta Graph API cho ratings và feed + comment của page; Instagram Graph API cho comment; Reddit OAuth (miễn phí, chỉ cần đăng ký app); Google Business Profile API cho review Google. Đã kiểm chứng: gọi Graph API không token trả
400 OAuthException— xác nhận đây là cửa cần quyền, không phải cửa hỏng.A search index gives excerpts; only APIs give full text, complete counts, and freshness. Meta Graph API for page ratings and feed + comments; Instagram Graph API for comments; Reddit OAuth (free, just register an app); Google Business Profile API for Google reviews. Verified: calling the Graph API with no token returns400 OAuthException— confirming this is a door that needs permission, not a broken door.Việc phải làm: biến "xin token hoặc bản export" thành một bước chuẩn ở Phase 0, kèm mẫu câu hỏi sẵn. Đây là thay đổi quy trình, không phải thay đổi code.What to do: make "ask for a token or an export" a standard Phase 0 step, with a ready-made request template. That is a process change, not a code change.
-
3
Kho lưu trữ công khai — dùng được, nhưng không đáng tin để làm đường chínhPublic archives — usable, but not dependable as the main roadchập chờnflaky
Wayback có snapshot thật của trang TripAdvisor của khách (bản 2019) — API kiểm tra tồn tại chạy tốt. Nhưng tải nội dung thì hỏng: IP này bị
429sau vài chục request, và Jina chặn hẳnweb.archive.org(báo tới 2035, lý do "nghi ngờ DDoS").Wayback does hold a real snapshot of the client's TripAdvisor page (a 2019 capture) — the availability API works fine. But fetching content breaks: this IP gets429after a few dozen requests, and Jina blocksweb.archive.orgoutright (until 2035, reason: "suspected DDoS").Kết luận: giữ làm nguồn bổ sung, luôn ghi ngày chụp, và không bao giờ để nó là đường duy nhất.Conclusion: keep it as a supplementary source, always record the capture date, and never let it be the only road.
-
4
Phát hiện chặn + khai báo khoảng trốngBlock detection + declaring the gapchưa làmnot built yet
Như đã thiết kế: phân loại
login_wall/cf_challenge/datadome/rate_limit, ghiblocked_reasonvào manifest, không bao giờ ghi0. Bổ sung sau khi đo:429và403phải được ghi làrate_limit, không phải "không có dữ liệu" — vì hôm nay chính Brave, archive.org và Jina đều trả 429/403 khi bị gọi nhanh. Đây là lớp bắt buộc: không có nó, ba lớp trên có thể âm thầm biến "bị chặn" thành "bằng 0".As designed: classifylogin_wall/cf_challenge/datadome/rate_limit, writeblocked_reasoninto the manifest, never write0. Added after measuring:429and403must be recorded asrate_limit, not "no data" — because today Brave, archive.org and Jina all returned 429/403 when called quickly. This layer is mandatory: without it, the three layers above can silently turn "blocked" into "zero".
Bằng chứng — chỉ riêng lớp 1 đã lấy được gìProof — what layer 1 alone already produced
Chạy cho đúng khách trong demo run, không mở một trang bị chặn nào, chỉ đọc chỉ mục tìm kiếm công khai:Run for the exact client from the demo run, without opening a single blocked page, reading only the public search index:
Ngoài ra còn tìm ra được: page Facebook chính thức của khách (facebook.com/CasaEscondidaAnilao), URL trang TripAdvisor và URL từng review riêng, và entity Google hotels của khách. Đây đều là URL gốc để lớp 2 xin quyền đọc.It also surfaced: the client's official Facebook page (facebook.com/CasaEscondidaAnilao), the TripAdvisor page URL and individual review URLs, and the client's Google hotels entity. These are the canonical URLs layer 2 asks permission to read.
Trích đoạn review lấy được, nguyên vănReview excerpts recovered, verbatim
- “Spacious Suites, Safe Diving, Dive Shop Hot Showers! We had a great time in Casa Escondida on our …”tripadvisor.com · snippet
- “wont go wrong with choosing Casa Escondida, they have a pool for non-divers as well and an excellent lounge to watch the …”tripadvisor.com · snippet
- “Though I have heard of this resort which comes highly recommended, I only got a chance to stay in Casa Escondida last month.”tripadvisor.com · snippet
- “Can’t wait to be back! I travelled and stayed in Casa Escondida for my Open Water Course.”tripadvisor.com · snippet
- “Shirley P, 6 months ago · Casa Escondida offered a picturesque setting and a truly enjoyable experience”google hotels entity · snippet
- “There are many resorts in Anilao that charge much less and show far better hospitality.”tripadvisor.com · review tiêu cực, lấy được nhờ snippetnegative review, recovered via snippet
Điểm đáng chú ý: cả review khen lẫn review chê đều lấy được, kèm cả tên người đánh giá và mốc thời gian. Với một đề xuất bán hàng, đó chính là phần "tiếng nói khách hàng" mà trước đây pipeline phải bỏ trống.Worth noting: both positive and negative reviews came through, some with reviewer names and timestamps. For a sales proposal that is exactly the "voice of the customer" material the pipeline previously had to leave blank.
Các trở ngại còn lạiThe remaining obstacles
| Trở ngạiObstacle | Bằng chứngEvidence | Mức độSeverity | Hướng xử lýProposed fix |
|---|---|---|---|
| Không có test, không có CINo tests, no CI | Không tồn tại tests/ lẫn .github/ trong repo.Neither tests/ nor .github/ exists in the repo. |
chặn chất lượngblocks quality | Thêm tests/ + GitHub Actions chạy validate-proposal.py trên một fixture.Add tests/ plus a GitHub Action running validate-proposal.py against a fixture. |
| Validator chỉ đếm cấu trúcThe validator only counts structure | 14 check không kiểm: cặp song ngữ, số liệu chart có khớp findings, palette có bị override, thứ tự sidebar.The 14 checks cover none of: bilingual pairs, whether chart data matches findings, palette overrides, sidebar order. | chặn chất lượngblocks quality | Thêm một check cho mỗi lỗi trên — đều đếm được bằng máy.Add one check per gap — all four are mechanically countable. |
| Lắp ráp không tất địnhAssembly is non-deterministic | Cùng một pipeline có thể ra hai hình dạng HTML khác nhau giữa hai lần chạy.The same pipeline can produce two different HTML shapes across runs. | chặn chất lượngblocks quality | Chốt thứ tự section bằng dữ liệu, không bằng quyết định của agent.Pin section order in data instead of leaving it to an agent's judgement. |
| Review phán đoán không tái lập đượcJudgment review isn't reproducible | Hai người đọc có thể ra hai kết luận; bằng chứng chỉ có một lần chạy.Two readers can reach two conclusions; the evidence is a single run. | chặn chất lượngblocks quality | Checklist bắt buộc cho judgment-reviewer + ghi lại lý do từng phán đoán.A mandatory checklist for judgment-reviewer plus a written reason for each call. |
| Tool nội bộ bị đóng gói chungInternal tooling ships with the package | api/answers.js, blocker/answers.json, blocker/questions.html và report/*.html đang được git track.api/answers.js, blocker/answers.json, blocker/questions.html and report/*.html are all git-tracked. |
nợ kỹ thuậttech debt | Tách sang internal/, hoặc đánh dấu export-ignore để không vào gói gửi đối tác.Move to internal/, or mark export-ignore so they stay out of the partner-facing package. |
| Agent definition đang ở dạng của một toolAgent definitions are shaped for one tool | Định nghĩa agent theo quy ước của Claude Code; tool khác có thể không đọc được.Agent definitions follow Claude Code's conventions, which another agent may not read. | nợ kỹ thuậttech debt | Mô tả trung lập + adapter cho từng tool.Tool-neutral descriptions plus a thin adapter per tool. |
| Chưa có benchmark trên máy sạchNo benchmark on a clean machine | Mọi số liệu đến từ một lần chạy trên một máy, do chính người viết skill chạy.Every number comes from one run on one machine, driven by the skill's own author. | nợ kỹ thuậttech debt | Chạy lại trên một máy chỉ có Codex, không cài sẵn gì, và ghi lại toàn bộ chi phí.Re-run on a machine with only Codex installed and nothing pre-configured, recording the full cost. |
Việc cần làm tiếp, theo thứ tựWhat to do next, in order
- 1Đưa lớp 1 vào
web-osint-scannerPut layer 1 intoweb-osint-scannerThêm bước thu hoạch từ chỉ mục tìm kiếm (Brave), kèm giãn nhịp + cache + ghi ngày crawl. Đây là thứ chạy được ngay hôm nay, không cần xin quyền ai, và đã có bằng chứng ở trên.Add the search-index harvest step (Brave) with pacing, caching and a recorded crawl date. This is what works today, needs nobody's permission, and is already proven above.
- 2Phân loại chặn +
blocked_reasonBlock classification +blocked_reasonGồm cả luật mới:
429/403làrate_limit, không phải "không có dữ liệu". Kèm check trong validator — một chỉ số không được phép lấy từ capture bị chặn.Including the new rule:429/403meansrate_limit, not "no data". Ship with the validator check — a metric may not come from a blocked capture. - 3Bước xin token / export ở Phase 0A token / export request step in Phase 0
Đây là con đường duy nhất để có review đầy đủ và mới. Biến nó thành một bước chuẩn, kèm mẫu câu hỏi và danh sách quyền cần xin cho từng nền tảng.The only route to full, current reviews. Make it a standard step, with a request template and the exact scopes needed per platform.
- 4Test + CITests + CI
Để một sửa template sau này không tái phát lỗi chart trắng — đúng lỗi đã từng lọt qua cả ba cổng.So a future template edit can't reintroduce the blank-chart defect — the one that slipped past all three gates.
- 5Tách tool nội bộ khỏi góiSplit internal tooling out of the package
Trước khi đưa cho đối tác nào khác, để họ không nhận kèm công cụ nội bộ.Before handing this to another partner, so they don't receive our internal tools along with it.