gamealgo-cli 0.3.5 → 0.3.7

package/README.md

@@ -29,6 +29,8 @@ gamealgo help
 gamealgo help report publish
 gamealgo docs
 gamealgo docs sdk-integration
+gamealgo docs reports --list --json
+gamealgo docs reports --section report-query
 gamealgo listapi
 gamealgo docs api GameAlgo.Init --platform lua
 ```

package/dist/client.js

@@ -133,6 +133,21 @@ export class GameAlgoAdminClient {
     async getScriptVersion(name, versionId) {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/scripts/${encodeURIComponent(name)}/versions/${encodeURIComponent(versionId)}`);
     }
+    async listDynamicConfigs() {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs`);
+    }
+    async getDynamicConfig(key) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}`);
+    }
+    async putDynamicConfig(key, body) {
+        return await this.put(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}`, body);
+    }
+    async queueDynamicConfigRun(key) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}/run`, {});
+    }
+    async listDynamicConfigRuns(key, limit = 50) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}/runs?limit=${encodeURIComponent(String(limit))}`);
+    }
     async getReportPack() {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/report-pack`);
     }
@@ -173,6 +188,15 @@ export class GameAlgoAdminClient {
     async deprecateEventCatalog(eventType) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/deprecate`, {});
     }
+    async blockEventCatalog(eventType, reason) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/block`, { reason });
+    }
+    async activateEventCatalog(eventType, reason, confirmEventType) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/activate`, {
+            reason,
+            confirmEventType,
+        });
+    }
     async getIntegrationPlan(environment, platform) {
         const params = new URLSearchParams({ environment, platform });
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/integration/plan?${params.toString()}`);

package/dist/commands/dynamic-config.js

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { parseFlags } from "../args.js";
+import { printResult } from "../output.js";
+import { contentTypeForFileName, objectValue, readJsonFile, sanitizeRemoteFileName } from "../resources.js";
+import { announceTargetGame } from "../target.js";
+import { optionalString } from "../utils.js";
+export async function handleDynamicConfig(client, args, global) {
+    const sub = args.shift();
+    if (sub === "list") {
+        parseFlags(args);
+        await printResult(await client.listDynamicConfigs(), global);
+        return;
+    }
+    if (sub === "get") {
+        const key = args.shift();
+        if (!key)
+            throw new Error("usage: gamealgo dynamic-config get <key>");
+        parseFlags(args);
+        await printResult(await client.getDynamicConfig(key), global);
+        return;
+    }
+    if (sub === "runs") {
+        const key = args.shift();
+        if (!key)
+            throw new Error("usage: gamealgo dynamic-config runs <key> [--limit 50]");
+        const flags = parseFlags(args);
+        await printResult(await client.listDynamicConfigRuns(key, Number(flags.limit || 50)), global);
+        return;
+    }
+    if (sub === "run") {
+        const key = args.shift();
+        if (!key)
+            throw new Error("usage: gamealgo dynamic-config run <key>");
+        parseFlags(args);
+        await announceTargetGame(client);
+        await printResult(await client.queueDynamicConfigRun(key), global);
+        return;
+    }
+    if (sub === "publish") {
+        const definitionPath = args.shift();
+        if (!definitionPath) {
+            throw new Error("usage: gamealgo dynamic-config publish <definition.json> [--script transform.js] [--message text]");
+        }
+        const flags = parseFlags(args);
+        const definition = objectValue(await readJsonFile(definitionPath));
+        if (!definition)
+            throw new Error("dynamic config definition must be a JSON object");
+        const key = optionalString(definition.key);
+        if (!key)
+            throw new Error("dynamic config definition.key is required");
+        const body = { ...definition };
+        delete body.key;
+        const scriptPath = optionalString(flags.script);
+        await announceTargetGame(client);
+        if (scriptPath) {
+            const scriptName = sanitizeRemoteFileName(optionalString(definition.scriptName) || basename(scriptPath));
+            const content = await readFile(scriptPath, "utf8");
+            const created = await client.createScriptVersion(scriptName, content, contentTypeForFileName(scriptName), optionalString(flags.message));
+            body.scriptVersionId = created.scriptVersion.versionId;
+        }
+        delete body.scriptName;
+        if (!optionalString(body.scriptVersionId)) {
+            throw new Error("definition.scriptVersionId or --script is required");
+        }
+        const response = await client.putDynamicConfig(key, body);
+        await printResult({ ok: true, ...response }, global);
+        return;
+    }
+    throw new Error("usage: gamealgo dynamic-config <list|get|publish|run|runs>");
+}

package/dist/commands/events.js

@@ -41,8 +41,32 @@ export async function handleEvents(client, args, global) {
         await writeEventCatalogOutput(await client.deprecateEventCatalog(eventType), flags, global);
         return;
     }
+    if (sub === "block") {
+        const eventType = args.shift();
+        const reason = optionalString(flags.reason);
+        if (!eventType || args.length || !reason)
+            throw new Error("usage: gamealgo events block <eventType> --reason <reason> [--yes]");
+        if (!flags.yes && !(await confirm(`Block event ${eventType}? New occurrences will be dropped before Kafka.`)))
+            throw new Error("Cancelled");
+        await announceTargetGame(client);
+        await writeEventCatalogOutput(await client.blockEventCatalog(eventType, reason), flags, global);
+        return;
+    }
+    if (sub === "activate") {
+        const eventType = args.shift();
+        const reason = optionalString(flags.reason);
+        const confirmation = optionalString(flags.confirm);
+        if (!eventType || args.length || !reason || !confirmation) {
+            throw new Error("usage: gamealgo events activate <eventType> --reason <reason> --confirm <eventType>");
+        }
+        if (confirmation !== eventType)
+            throw new Error("--confirm must exactly match eventType");
+        await announceTargetGame(client);
+        await writeEventCatalogOutput(await client.activateEventCatalog(eventType, reason, confirmation), flags, global);
+        return;
+    }
     if (sub !== "count")
-        throw new Error("usage: gamealgo events <list|get|apply|deprecate|count>");
+        throw new Error("usage: gamealgo events <list|get|apply|deprecate|block|activate|count>");
     const timeoutMs = reportTimeoutMs(flags);
     const startedAt = Date.now();
     const stopProgress = startProgress("Querying event counts", timeoutMs);

package/dist/commands/report.js

@@ -1,5 +1,7 @@
+import { extname, join } from "node:path";
 import { parseFlags, parseSelectorFlags } from "../args.js";
 import { formatDuration, printResult, reportTimeoutMs, startProgress, withCliMeta } from "../output.js";
+import { reportDashboardCsv, reportDashboardCsvExports } from "../report-csv.js";
 import { objectValue, readJsonFile, writeTextFile } from "../resources.js";
 import { announceTargetGame } from "../target.js";
 import { optionalString } from "../utils.js";
@@ -43,7 +45,7 @@ export async function handleReport(client, args, global) {
         const startDate = String(flags.from || flags.start || flags.startDate || "");
         const endDate = String(flags.to || flags.end || flags.endDate || "");
         if (!startDate || !endDate)
-            throw new Error("usage: gamealgo report result --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v]");
+            throw new Error("usage: gamealgo report result --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v] [--format json|csv] [--out file-or-directory]");
         const timeoutMs = reportTimeoutMs(flags);
         const platform = await resolveCliReportPlatform(client, flags.platform, selectors.platform, startDate, endDate);
         const startedAt = Date.now();
@@ -70,17 +72,7 @@ export async function handleReport(client, args, global) {
         const elapsedMs = Date.now() - startedAt;
         const outputValue = withCliMeta(response, { elapsedMs, timeoutMs });
         process.stderr.write(`Report query finished in ${formatDuration(elapsedMs)}.\n`);
-        if (flags.out) {
-            await writeTextFile(String(flags.out), JSON.stringify(outputValue, null, 2) + "\n");
-            await printResult({
-                ok: true,
-                out: String(flags.out),
-                results: Array.isArray(outputValue.results) ? outputValue.results.length : 0,
-                elapsedMs,
-            }, global);
-            return;
-        }
-        await printResult(outputValue, global);
+        await writeReportQueryOutput(outputValue, flags, global, elapsedMs);
         return;
     }
     if (sub === "preview") {
@@ -90,7 +82,7 @@ export async function handleReport(client, args, global) {
         const startDate = String(flags.from || flags.start || flags.startDate || "");
         const endDate = String(flags.to || flags.end || flags.endDate || "");
         if (!filePath || !startDate || !endDate) {
-            throw new Error("usage: gamealgo report preview --pack report-pack.json --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v]");
+            throw new Error("usage: gamealgo report preview --pack report-pack.json --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v] [--format json|csv] [--out file-or-directory]");
         }
         const content = await readJsonFile(filePath);
         const timeoutMs = reportTimeoutMs(flags);
@@ -119,20 +111,106 @@ export async function handleReport(client, args, global) {
         const elapsedMs = Date.now() - startedAt;
         const outputValue = withCliMeta(response, { elapsedMs, timeoutMs });
         process.stderr.write(`Report preview finished in ${formatDuration(elapsedMs)}.\n`);
-        if (flags.out) {
-            await writeTextFile(String(flags.out), JSON.stringify(outputValue, null, 2) + "\n");
-            await printResult({
+        await writeReportQueryOutput(outputValue, flags, global, elapsedMs);
+        return;
+    }
+    throw new Error("usage: gamealgo report <pull|validate|publish|manifest|result|preview>");
+}
+export function reportOutputFormat(value) {
+    if (value === undefined || value === null || value === "")
+        return "json";
+    if (typeof value !== "string")
+        throw new Error("--format requires json or csv");
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "json" || normalized === "csv")
+        return normalized;
+    throw new Error("--format must be json or csv");
+}
+async function writeReportQueryOutput(outputValue, flags, global, elapsedMs) {
+    const format = reportOutputFormat(flags.format);
+    const out = optionalString(flags.out);
+    if (flags.out === true)
+        throw new Error("--out requires a file path");
+    if (format === "csv") {
+        if (!out && global.json)
+            throw new Error("--format csv cannot be combined with --json unless --out is provided");
+        if (out) {
+            const exports = reportDashboardCsvExports(outputValue);
+            const files = reportCsvOutputFiles(exports, out);
+            for (const file of files) {
+                warnTruncatedCsv(file.exported);
+                await writeTextFile(file.out, file.exported.content);
+            }
+            const first = files[0];
+            const summary = files.length === 1 ? {
                 ok: true,
-                out: String(flags.out),
-                results: Array.isArray(outputValue.results) ? outputValue.results.length : 0,
+                out: first.out,
+                format,
+                reportId: first.exported.reportId,
+                chartId: first.exported.chartId,
+                chartTitle: first.exported.chartTitle,
+                rows: first.exported.rowCount,
+                columns: first.exported.columns.length,
+                truncated: first.exported.truncated,
                 elapsedMs,
-            }, global);
+            } : {
+                ok: true,
+                out,
+                format,
+                results: files.length,
+                files: files.map((file) => ({
+                    out: file.out,
+                    reportId: file.exported.reportId,
+                    chartId: file.exported.chartId,
+                    chartTitle: file.exported.chartTitle,
+                    rows: file.exported.rowCount,
+                    columns: file.exported.columns.length,
+                    truncated: file.exported.truncated,
+                })),
+                elapsedMs,
+            };
+            await printResult(summary, global);
             return;
         }
-        await printResult(outputValue, global);
+        const exported = reportDashboardCsv(outputValue);
+        warnTruncatedCsv(exported);
+        process.stdout.write(exported.content);
         return;
     }
-    throw new Error("usage: gamealgo report <pull|validate|publish|manifest|result|preview>");
+    if (out) {
+        await writeTextFile(out, JSON.stringify(outputValue, null, 2) + "\n");
+        await printResult({
+            ok: true,
+            out,
+            results: Array.isArray(outputValue.results) ? outputValue.results.length : 0,
+            elapsedMs,
+        }, global);
+        return;
+    }
+    await printResult(outputValue, global);
+}
+function reportCsvOutputFiles(exports, out) {
+    if (exports.length === 1)
+        return [{ out, exported: exports[0] }];
+    if (extname(out).toLowerCase() === ".csv") {
+        throw new Error(`CSV export matched ${exports.length} charts; use --chart-id to select one chart or pass a directory to --out`);
+    }
+    return exports.map((exported, index) => ({
+        out: join(out, `${String(index + 1).padStart(2, "0")}-${reportCsvBaseName(exported, index)}.csv`),
+        exported,
+    }));
+}
+function reportCsvBaseName(exported, index) {
+    const candidate = exported.chartId || exported.reportId || `report-${index + 1}`;
+    return candidate
+        .replace(/[^A-Za-z0-9_.-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        || `report-${index + 1}`;
+}
+function warnTruncatedCsv(exported) {
+    if (!exported.truncated)
+        return;
+    process.stderr.write(`Warning: CSV contains a truncated report result${exported.rowLimit ? ` (limit ${exported.rowLimit})` : ""}.\n`);
 }
 export async function resolveCliReportPlatform(client, flagValue, selectorValue, startDate, endDate) {
     const flagPlatform = optionalCliReportPlatform(flagValue, "--platform");

package/dist/docs.js

@@ -257,8 +257,17 @@ export async function handleDocs(args, global) {
     const flags = parseFlags(args);
     const topicId = String(args.shift() || "").trim();
     const apiQuery = topicId === "api" ? args.join(" ").trim() : "";
+    const listSections = flags.list === true || flags.toc === true;
+    const sectionId = optionalDocsSectionId(flags.section);
+    if (listSections && sectionId)
+        throw new Error("--list and --section cannot be used together");
+    if (flags.open && (listSections || sectionId))
+        throw new Error("--open cannot be combined with --list or --section");
+    if (topicId === "api" && (listSections || sectionId)) {
+        throw new Error("gamealgo docs api uses its own function list; --list and --section only apply to documentation topics");
+    }
     if (topicId !== "api" && args.length) {
-        throw new Error("usage: gamealgo docs [topic] [--open] [--json] [--host <admin-url>]");
+        throw new Error("usage: gamealgo docs [topic] [--list | --section <section-id>] [--open] [--json] [--host <admin-url>]");
     }
     const saved = await loadConfig();
     const host = normalizeHost(global.host || saved?.host || "");
@@ -307,6 +316,28 @@ export async function handleDocs(args, global) {
             console.error("Warning: using cached documentation index because the Admin host could not be reached");
         return;
     }
+    if (listSections) {
+        if (!topic.sections.length)
+            throw new Error(`Documentation topic ${topic.id} does not publish addressable sections`);
+        if (global.json) {
+            await printResult({
+                ok: true,
+                version: manifest.version,
+                updatedAt: manifest.updatedAt,
+                topic: topic.id,
+                title: topic.title,
+                cached: loaded.cached,
+                webUrl,
+                rawUrl: docsRawUrl(host, topic.file),
+                sections: topic.sections,
+            }, global);
+            return;
+        }
+        printDocsSectionIndex(topic, manifest, topic.sections);
+        if (loaded.cached)
+            console.error("Warning: using cached documentation index because the Admin host could not be reached");
+        return;
+    }
     const document = await loadDocsDocument(host, manifest, topic, loaded.cached);
     if (topicId === "api") {
         await printDocsApiResult({
@@ -321,6 +352,34 @@ export async function handleDocs(args, global) {
         });
         return;
     }
+    if (sectionId) {
+        const section = topic.sections.find((item) => item.id === sectionId);
+        if (!section) {
+            const available = topic.sections.map((item) => item.id);
+            const suffix = available.length ? ` Available sections: ${available.join(", ")}` : "";
+            throw new Error(`Unknown documentation section: ${topic.id}/${sectionId}.${suffix}`);
+        }
+        const content = extractDocsSection(document.content, section);
+        if (global.json) {
+            await printResult({
+                ok: true,
+                version: manifest.version,
+                updatedAt: manifest.updatedAt,
+                topic: topic.id,
+                title: topic.title,
+                section,
+                cached: document.cached,
+                webUrl,
+                rawUrl: docsRawUrl(host, topic.file),
+                content,
+            }, global);
+            return;
+        }
+        console.log(content.trimEnd());
+        if (document.cached)
+            console.error("Warning: using cached documentation because the Admin host could not be reached");
+        return;
+    }
     if (global.json) {
         await printResult({
             ok: true,
@@ -340,6 +399,62 @@ export async function handleDocs(args, global) {
     if (document.cached)
         console.error("Warning: using cached documentation because the Admin host could not be reached");
 }
+export function optionalDocsSectionId(value) {
+    if (value === undefined || value === false || value === "")
+        return undefined;
+    if (value === true)
+        throw new Error("--section requires a section id");
+    const sectionId = String(value).trim();
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(sectionId)) {
+        throw new Error("--section must use a stable lowercase section id");
+    }
+    return sectionId;
+}
+export function extractDocsSection(content, section) {
+    const lines = content.split(/\r?\n/);
+    const headingLines = markdownHeadingLines(lines);
+    const matches = headingLines.filter((item) => (item.level === section.level
+        && normalizeDocsSectionTitle(item.title) === normalizeDocsSectionTitle(section.title)));
+    if (!matches.length)
+        throw new Error(`Documentation section heading not found: ${section.id} (${section.title})`);
+    if (matches.length > 1)
+        throw new Error(`Documentation section heading is ambiguous: ${section.id} (${section.title})`);
+    const startLine = matches[0].line;
+    const endLine = headingLines.find((item) => item.line > startLine && item.level <= section.level)?.line ?? lines.length;
+    return lines.slice(startLine, endLine).join("\n").trimEnd();
+}
+function normalizeDocsSectionTitle(value) {
+    return stripInlineMarkdown(value).replace(/\s+/g, " ").trim();
+}
+function markdownHeadingLines(lines) {
+    const headings = [];
+    let fence = "";
+    for (let line = 0; line < lines.length; line += 1) {
+        const fenceMatch = lines[line].match(/^\s{0,3}(```+|~~~+)/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1][0];
+            if (!fence)
+                fence = marker;
+            else if (fence === marker)
+                fence = "";
+            continue;
+        }
+        if (fence)
+            continue;
+        const heading = lines[line].match(/^(#{1,6})[ \t]+(.+?)\s*$/);
+        if (heading)
+            headings.push({ line, level: heading[1].length, title: heading[2] });
+    }
+    return headings;
+}
+export function printDocsSectionIndex(topic, manifest, sections) {
+    console.log(`${topic.title}章节 ${manifest.version}${manifest.updatedAt ? ` (${manifest.updatedAt})` : ""}`);
+    for (const section of sections) {
+        const indent = "  ".repeat(Math.max(1, section.level - 1));
+        console.log(`\n${indent}${section.id}\n${indent}  ${section.title}${section.summary ? `：${section.summary}` : ""}`);
+    }
+    console.log(`\n读取章节: gamealgo docs ${topic.id} --section <section-id>`);
+}
 export function parseDocsApiPlatform(value) {
     if (value === undefined || value === false || value === "")
         return undefined;
@@ -556,6 +671,7 @@ export function parseDocsManifest(text) {
             group: String(topic.group || "其他"),
             file,
             hidden: topic.hidden === true,
+            sections: parseDocsManifestSections(topic.sections, id),
         };
     });
     const ids = new Set(topics.map((topic) => topic.id));
@@ -572,6 +688,43 @@ export function parseDocsManifest(text) {
         topics,
     };
 }
+function parseDocsManifestSections(value, topicId) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`Documentation topic ${topicId} sections must be an array`);
+    const sections = [];
+    const parents = [];
+    const ids = new Set();
+    for (const item of value) {
+        const section = objectValue(item);
+        const id = optionalString(section?.id);
+        const title = optionalString(section?.title);
+        const summary = optionalString(section?.summary);
+        const level = Number(section?.level);
+        if (!id || !/^[a-z][a-z0-9-]{0,63}$/.test(id) || !title || !summary || !Number.isInteger(level) || level < 2 || level > 6) {
+            throw new Error(`Documentation topic ${topicId} contains an invalid section: ${id || "unknown"}`);
+        }
+        if (ids.has(id))
+            throw new Error(`Documentation topic ${topicId} contains duplicate section id: ${id}`);
+        ids.add(id);
+        while (parents.length && parents[parents.length - 1].level >= level)
+            parents.pop();
+        if (level > 2 && (!parents.length || level > parents[parents.length - 1].level + 1)) {
+            throw new Error(`Documentation topic ${topicId} section ${id} has no valid parent`);
+        }
+        const parsed = {
+            id,
+            title,
+            summary,
+            level,
+            ...(parents.length ? { parentId: parents[parents.length - 1].id } : {}),
+        };
+        sections.push(parsed);
+        parents.push(parsed);
+    }
+    return sections;
+}
 export function docsWebUrl(host, topicId) {
     const url = new URL(`${normalizeHost(host)}/dashboard/docs/`);
     if (topicId)

package/dist/main.js

@@ -12,6 +12,7 @@ import { handleFileResource } from "./commands/resources.js";
 import { handleSkill } from "./commands/skill.js";
 import { loadPackageMetadata } from "./config.js";
 import { handleDocs, handleHelp } from "./docs.js";
+import { handleDynamicConfig } from "./commands/dynamic-config.js";
 import { printResult } from "./output.js";
 export async function main() {
     const args = process.argv.slice(2);
@@ -76,6 +77,10 @@ export async function main() {
             await handleFileResource(client, args, global, "config");
             return;
         }
+        if (command === "dynamic-config") {
+            await handleDynamicConfig(client, args, global);
+            return;
+        }
         if (command === "report") {
             await handleReport(client, args, global);
             return;

package/dist/report-csv.js

@@ -0,0 +1,87 @@
+export function reportDashboardCsv(value) {
+    const exports = reportDashboardCsvExports(value);
+    if (exports.length !== 1) {
+        throw new Error(`CSV output to stdout or one file requires exactly one matching chart, but the query returned ${exports.length}`);
+    }
+    return exports[0];
+}
+export function reportDashboardCsvExports(value) {
+    const dashboard = recordValue(value);
+    const results = Array.isArray(dashboard?.results) ? dashboard.results : [];
+    if (!results.length)
+        throw new Error("CSV export did not receive any matching chart results");
+    return results.map(reportResultCsv);
+}
+function reportResultCsv(value) {
+    const result = recordValue(value);
+    if (!result)
+        throw new Error("CSV export received an invalid report result");
+    if (typeof result.error === "string" && result.error.trim()) {
+        throw new Error(`cannot export failed report result: ${result.error.trim()}`);
+    }
+    const rows = Array.isArray(result.rows)
+        ? result.rows.map((row) => recordValue(row) || {})
+        : [];
+    const declaredColumns = Array.isArray(result.columns)
+        ? result.columns.filter((column) => typeof column === "string" && Boolean(column.trim()))
+        : [];
+    const columns = uniqueStrings(declaredColumns.length ? declaredColumns : rows.flatMap((row) => Object.keys(row)));
+    if (!columns.length) {
+        throw new Error("CSV export result is not ready because the Server returned no columns; retry with --refresh or wait for the background refresh");
+    }
+    const lines = [
+        columns.map(csvCell).join(","),
+        ...rows.map((row) => columns.map((column) => csvCell(row[column])).join(",")),
+    ];
+    const chart = recordValue(result.chart);
+    const rowLimit = positiveIntegerOrUndefined(result.rowLimit);
+    return {
+        content: `\uFEFF${lines.join("\r\n")}\r\n`,
+        columns,
+        rowCount: rows.length,
+        reportId: optionalString(result.reportId),
+        chartId: optionalString(chart?.id),
+        chartTitle: optionalString(chart?.title),
+        truncated: result.truncated === true,
+        ...(rowLimit ? { rowLimit } : {}),
+    };
+}
+export function csvCell(value) {
+    let text;
+    if (value === null || value === undefined)
+        text = "";
+    else if (typeof value === "string")
+        text = protectSpreadsheetFormula(value);
+    else if (typeof value === "number")
+        text = Number.isFinite(value) ? String(value) : "";
+    else if (typeof value === "boolean" || typeof value === "bigint")
+        text = String(value);
+    else {
+        try {
+            text = JSON.stringify(value) ?? "";
+        }
+        catch {
+            text = String(value);
+        }
+    }
+    if (/[",\r\n]/.test(text) || /^\s|\s$/.test(text))
+        return `"${text.replaceAll('"', '""')}"`;
+    return text;
+}
+function protectSpreadsheetFormula(value) {
+    return /^\s*[=+\-@]/.test(value) ? `'${value}` : value;
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function positiveIntegerOrUndefined(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "repository": {
     "type": "git",

package/skills/gamealgo/SKILL.md

@@ -22,7 +22,7 @@ When the user asks what GameAlgo can do, asks for ongoing iteration, or names a
 1. Run `gamealgo optimize list --json` to load the complete current task catalog from the Server.
 2. Treat the result as an unranked capability catalog. Do not claim that a task is recommended or ready until its prerequisites have been checked against the current game.
 3. Once the user selects a task, or their request clearly identifies one, run `gamealgo optimize get <task-id> --json`.
-4. Read each topic named in the task's `docs` field with `gamealgo docs <topic>` before implementation.
+4. For each topic named in the task's `docs` field, run `gamealgo docs <topic> --list --json`, then read the sections relevant to the selected task with `gamealgo docs <topic> --section <section-id>` before implementation.
 5. Follow the returned `agentSteps` and use `deliverables` as the completion checklist.
 
 Do not run every catalog task in sequence. Complete the selected task and report unmet prerequisites instead of manufacturing missing data.
@@ -31,14 +31,16 @@ Do not run every catalog task in sequence. Complete the selected task and report
 
 Classify the requested work by the actions it requires, not only by the user's task title. Before implementation or interpreting results, load every applicable source below from the current Server:
 
-- SDK installation, identity, lifecycle, telemetry, attribution, advertising, or purchase work: run `gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --json`, then read `gamealgo docs sdk-integration`.
+Use each topic's section list as the router. Read the whole topic only when the task genuinely spans most of it; when that is necessary, load one full topic per tool call. If any tool marks documentation output as truncated, treat it as incomplete, retrieve the missing sections, and do not infer that unseen guidance is absent or switch workflows based on the partial output.
+
+- SDK installation, identity, lifecycle, telemetry, attribution, advertising, or purchase work: run `gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --json`, then list the `sdk-integration` sections and read the relevant shared and platform-specific sections.
 - Calling or changing a concrete public SDK function: additionally run `gamealgo docs api <function> --platform <platform>` for each affected function. Never infer one platform's API from another.
 - Adding or changing events: additionally run `gamealgo events list --days 30 --json` before defining fields or names.
-- Reading, creating, changing, previewing, or publishing Report Packs, charts, report SQL, or business metrics: read `gamealgo docs reports` before interpreting data or editing definitions.
-- Creating or changing remote configuration, strategies, experiments, variants, objectives, rollout, or assessment: read `gamealgo docs experiments`; also load the integration plan and exact API documentation when client code changes.
+- Querying an existing dashboard or report: read `gamealgo docs reports --section report-query` plus the section that defines the relevant metric or template. Creating, changing, previewing, or publishing Report Packs, charts, report SQL, or business metrics: list the `reports` sections and read every section affected by the change before interpreting data or editing definitions.
+- Creating or changing remote configuration, dynamic config pipelines, strategies, experiments, variants, objectives, rollout, or assessment: list the `experiments` sections and read every section affected by the change; also load the integration plan and exact API documentation when client code changes.
 - Adjust or marketing attribution work: load the selected optimization task when one applies, read every topic in its `docs`, and load the integration plan and exact identifier/attribution APIs for the target platform.
 
-If work crosses domains, combine their requirements. For example, an advertising event used by an experiment report requires the integration plan, event inventory, SDK API documentation, report documentation, and experiment documentation. Read a topic once per turn unless the task expands or the Server documentation version changes.
+If work crosses domains, combine their requirements. For example, an advertising event used by an experiment report requires the integration plan, event inventory, SDK API documentation, relevant report sections, and relevant experiment sections. Read a section once per turn unless the task expands or the Server documentation version changes.
 
 For initial integration or business dashboard work, standard dashboards are only the baseline. During the initial integration, inspect the actual game loop and define a separate game-specific new-user flow dashboard with meaningful milestones and drop-off diagnostics. Add required milestone telemetry and event catalog fields in the same integration instead of waiting for production volume. Validate the pipeline with test data; label business conclusions as awaiting data when production samples are immature, but do not omit the dashboard design.
 
@@ -51,6 +53,18 @@ For initial integration or business dashboard work, standard dashboards are only
 5. Before publishing reports, remote configuration, scripts, strategies, experiments, rollout changes, or other externally visible mutations, show the relevant diff and impact unless the user has already explicitly authorized that exact operation.
 6. After execution, verify with real configuration retrieval, accepted non-debug events, report results, or experiment state as appropriate. A code diff or successful request alone is not business verification.
 
+## Keep Production Analysis Off The Developer Workstation
+
+For production telemetry investigations, execute partition-scale scans and aggregations with managed Alibaba Cloud compute such as DataWorks/MaxCompute or Kyuubi/Spark, and return only the small aggregated result needed for diagnosis.
+
+The built-in domestic Data Bridge Paimon backend is not a distributed SQL pushdown engine: PyPaimon plans Paimon splits, reads OSS data into an Arrow table inside the Bridge pod, and only then executes the SQL with DuckDB. The current runner also does not translate SQL predicates into `read_builder.with_filter(...)`, so SQL `dt`, `game`, or `platform` filters do not guarantee Paimon split pruning. Do not use this backend for production raw/enriched partition scans or describe it as Paimon aggregating inside the storage service. Limit it to tightly bounded summary-table reads or emergency diagnostics until the query path is backed by managed compute.
+
+- Never use the local PyPaimon/DuckDB launcher to calculate production counts, DAU, hourly volume, event coverage, or source-to-enriched reconciliation. That launcher materializes selected Paimon partition data on the local machine even when the submitted SQL contains only aggregates.
+- Do not pull production detail rows or whole partitions to the local workspace and aggregate them afterward.
+- Put partition filters, game filters, grouping, distinct counts, joins, and same-elapsed-window comparisons in the SQL sent to the managed query engine, and verify its execution plan actually prunes partitions and columns.
+- Local Paimon access is limited to catalog/schema/partition metadata and a deliberately tiny `LIMIT` sample when the schema cannot otherwise be established.
+- If no managed query path is available, stop and give the developer a bounded SQL query to run. Do not silently fall back to a local or Bridge-Pod partition scan.
+
 Reading documentation does not grant permission to mutate production. CLI and Server validation, scopes, project binding, and explicit approval requirements still apply.
 
 ## Integration Details
@@ -67,6 +81,39 @@ Reuse events with the same business meaning, register new fields with their real
 
 For every game, prefer stable, human-readable Chinese values for business dimensions that will appear directly in report legends, axes, selectors, or tables. This includes values such as level or stage type, game mode, placement, item name, and business outcome or failure reason. Keep event names, field names, IDs, SQL aliases, and protocol-defined enums in their required technical format. Do not rename values already used by a live game solely to translate them, because that would split one historical dimension into multiple report values.
 
+## Bound Custom Event Volume
+
+Before adding or changing a custom event, prefer a protocol-standard event or an existing custom event with the same meaning. Keep the event type stable and put variable values in payload fields; never generate event types from item IDs, levels, timestamps, user input, or other runtime values.
+
+Inspect every call site for render/update loops, timers, polling, transport retries, duplicate lifecycle callbacks, and re-entrant listeners. State the trigger boundary and estimate the maximum calls per user, session, context, and active user-day. Use the game's active-user estimate to describe the expected daily volume when it is available.
+
+- Standard SDK semantic events are governed by their protocol semantics. Do not disguise custom telemetry as a standard event to bypass safeguards.
+- The SDK limits custom events to 1,000 occurrences per `context × eventType`, 5,000 total occurrences per context, and 100 distinct custom event types per context.
+- A custom event with an unbounded trigger or an expected rate above 1,000 calls per context requires explicit developer review before implementation. Explain the expected volume, storage and processing impact, and the guard that makes the trigger bounded.
+- Never add client-side retries around `track`, rename an event after rejection, remove its custom-event prefix, declare it standard, raise a safety limit, or call a lower-level transport to bypass a quota.
+- Treat an SDK `event_guard` diagnostic as evidence of a telemetry bug or unexpectedly high-frequency design. Find and fix the emission path before asking to change a limit.
+
+Before delivery, report the estimated bound, normal-flow tests, the limiting loop or callback, and behavior once the local quota is reached.
+
+## Treat Dynamic Config As A Production Publisher
+
+A dynamic config pipeline is Server-side automation that turns aggregated Report Pack inputs into a live config file. It does not authorize SDK changes, detailed production-data downloads, or live publication by itself.
+
+- Define bounded aggregate inputs with Report Pack syntax. Keep filters, joins, aggregation, and data reduction in the managed query rather than passing event detail to JavaScript.
+- Keep transforms synchronous and deterministic. They may use only the supplied datasets, previous output, and scheduled metadata; never depend on network, filesystem, environment variables, wall-clock APIs, randomness, async functions, or Promise output.
+- The output file name and content type belong to the reviewed pipeline definition. The script may return only file content and JSON diagnostics.
+- Before publishing or materially updating an active pipeline, show the target game, input reports and windows, complete script diff, output file and content type, schedule, expected behavior, failure behavior, and user-facing or operational risks. Obtain explicit approval for that exact publication unless the user already gave it after seeing those details.
+- Prefer a disabled pipeline or a local script test while details are still under discussion. After an authorized publish, trigger one run, inspect the persisted run result and generated file version, and confirm that an unchanged second run is hash-deduplicated before treating the automation as verified.
+- Do not raise the 1 MiB script/input/output caps, the 5,000-row per-dataset cap, the 5-second execution cap, or the minimum 60-minute schedule to bypass a failing design. Reduce data in the Report Pack or simplify the transform.
+
+Use `gamealgo dynamic-config list|get|publish|run|runs` for lifecycle operations. Dynamic config output continues through the ordinary SDK config-file delivery mechanism, so do not change client SDK code merely to consume a generated file that already uses the existing config API.
+
+## Respect Blocked Events
+
+A blocked event is a persistent ingestion safety state. You may inspect its diagnostics, analyze data read-only, fix the client call site, and run local validation, but you must not reactivate it, register an equivalent replacement event, declare it standard, switch credentials, call a lower-level transport, or otherwise bypass the block without fresh explicit approval. Applying ordinary catalog metadata must not reactivate a blocked or deprecated event.
+
+Before asking to reactivate an event, tell the developer why it was blocked, the faulty call path, the implemented fix, the previous and expected event rate per context and active user-day, the validation performed, and the remaining risk. Only an unambiguous instruction given after that disclosure authorizes the exact `blocked` to `active` transition. Use the dedicated CLI activation command with its required reason and exact event-name confirmation, then verify both the catalog state and newly observed event health. Do not edit the database or repeatedly reactivate an event that becomes blocked again without a new diagnosis and approval.
+
 ## Initialize At The Earliest Safe Lifecycle Point
 
 Initialize GameAlgo at the beginning of the earliest runtime lifecycle hook where its minimal required dependencies are available. Do not place it after save loading, scene creation, asset loading, UI construction, ad initialization, or a broad game-module bootstrap merely for organizational convenience. Any unhandled failure before the call would otherwise exclude an opened user from telemetry, and an SDK initialization watchdog cannot report a failure when the SDK was never started.
@@ -98,6 +145,23 @@ When client code implements an experiment or remote Strategy, define a stable, t
 
 Before delivery, inspect changed client code for Variant or assignment-identity access and verify none of it reaches business conditionals. Test active control and treatment configs, missing configuration, and the post-promotion shape where the Variant becomes `default` while the promoted config remains active; unchanged parameters must produce unchanged game behavior regardless of the Variant name.
 
+## Require Explicit Approval Before Publishing Experiments
+
+Treat publishing a live experiment as a two-step workflow. Before approval, limit work to read-only analysis, experiment ideas, and local drafts. Do not publish an experiment-specific Strategy or Strategy version, create or start a Run, allocate traffic, or otherwise mutate live experiment state.
+
+Before asking for approval, tell the developer:
+
+- the target game and environment, eligible audience, and exclusions;
+- the hypothesis, primary metric, and decision criterion;
+- the exact control and treatment differences, including parameter values or scripts;
+- the traffic allocation and planned duration, sample size, or review checkpoint;
+- the expected benefit and realistic product, revenue, retention, user-experience, and technical risks that apply; and
+- the stop-loss conditions and rollback or cancellation plan.
+
+Then explicitly ask whether to publish that exact experiment. Only an unambiguous confirmation given after this disclosure authorizes publication. Earlier broad instructions such as “优化一下”, “做个实验”, or “按你判断”, and authorization for code, report, or configuration work do not authorize publishing an experiment. If a material detail changes after approval—including the target game, audience, variants, parameters or scripts, traffic, duration, objective, decision criterion, or risk profile—disclose the change and obtain fresh approval before publishing.
+
+After an authorized publication, retrieve and report the actual Strategy and Run IDs, status, scope, and rollback path. Do not silently create another experiment, Run, round, or rollout. A direct request to pause, cancel, or roll back an existing experiment is sufficient authority for that protective action and must not be blocked by this publication gate.
+
 ## Protect D0 Monetization In Maker Experiments
 
 For TapTap Maker and other Maker games, do not autonomously design, create, or start an experiment that removes all ads from a user's first local day, delays the first ad until D1 or later, or otherwise moves the game's core D0 ad inventory to a later day. Many Maker games lose a large share of users before D1, so this is a direct D0 revenue-risk decision rather than an ordinary ad-timing adjustment. A broad request to optimize ads is not approval for this design.