gamealgo-cli 0.3.4 → 0.3.6

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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, 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.
 
@@ -67,6 +69,26 @@ 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.
 
+## 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.
+
+Wait only for dependencies GameAlgo actually needs, such as the platform runtime, client key, or a required stable identity. If richer gameplay context becomes available later, separate early SDK initialization from later context binding and business-event emission instead of delaying the SDK. Keep initialization non-blocking, isolate and log its synchronous exceptions without blocking the game, and do not silently discard an outer protected-call error.
+
+Before delivery, inspect the complete startup path rather than only the SDK wrapper. Verify that deliberate failures in later save, resource, scene, or UI initialization still occur after GameAlgo initialization has started and can produce either a successful initialization log or the configured initialization-failure diagnostic.
+
+## Always Track Maker Ad Close Callbacks
+
+For TapTap Maker `ShowRewardVideoAd`, entering the registered `onClose` callback is the platform's effective-exposure boundary. Call `TrackAd` unconditionally and exactly once whenever `onClose` runs.
+
+- Never gate `TrackAd` on `result.success`, any return or error code, `result.msg` / `result.message`, a custom failure classification, or whether a `trackId` was extracted.
+- Use `result.success` only to decide whether the game grants the reward. Other result fields may enrich diagnostics but must not suppress `TrackAd`.
+- If `trackId` is missing, still call `TrackAd` and also emit a missing-track diagnostic when available.
+- Do not infer that an `onClose` result was a pre-display failure. Only a thrown or rejected ad request, or a distinct failure callback that occurs without entering `onClose`, may skip `TrackAd`.
+- Keep a per-request guard so duplicate `onClose` delivery cannot produce duplicate `ad_view` events.
+
+Before delivery, inspect every Maker ad wrapper and test the `success=true`, `success=false`, non-success return-code, missing-trackId, and duplicate-callback cases. Each `onClose` case must produce exactly one `TrackAd`; only reward granting varies with `success`.
+
 ## Keep Experiment Identity Out Of Game Logic
 
 When client code implements an experiment or remote Strategy, define a stable, typed parameter contract first, including each parameter's meaning, type, valid values or unit, and local fallback. Drive game behavior only from those config parameters or from a validated script payload. Variants provide different parameter values; they are not feature flags.