gamealgo-cli 0.3.5 → 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.5",
+  "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.