feiguazhitou-mcp-cli 0.1.0

package/dist/agent-guide.js

@@ -0,0 +1,278 @@
+import { CATALOG_STALE_AFTER_MS, COMMAND_NAME, DEFAULT_ENDPOINT, DEFAULT_TIMEOUT_MS, ENV, MAX_TIMEOUT_MS, RECOMMENDED_RPA_TIMEOUT_MS, } from "./constants.js";
+import { outputLanguage, t } from "./i18n.js";
+export const DESCRIBE_PROTOCOL = "feiguazhitou-mcp-cli.describe/v1";
+export const DESCRIBE_PROTOCOL_VERSION = 1;
+function commandDocument() {
+    const timeoutAppliesTo = outputLanguage() === "zh"
+        ? ["MCP schema 发现", "MCPorter 生成", "生成的 MCPorter 工具调用"]
+        : ["MCP schema discovery", "MCPorter generation", "generated MCPorter tool call"];
+    return {
+        protocol: DESCRIBE_PROTOCOL,
+        protocolVersion: DESCRIBE_PROTOCOL_VERSION,
+        role: t("单实例飞瓜智投 MCP 启动器与已生成工具目录。", "Single-instance Feiguazhitou MCP launcher and generated tool catalog."),
+        runtimeEnvironment: {
+            required: [],
+            optional: [ENV.endpoint, ENV.apiKey, ENV.headers, ENV.autoApprove, ENV.token, ENV.timeout, ENV.dataDirectory, ENV.language],
+            defaults: { endpoint: DEFAULT_ENDPOINT },
+            credentialRule: t("环境变量值只在运行时使用。Agent 默认使用 config set header HEADER --value-stdin 将用户提供的单个 Header 保存到本机未加密凭据文件；用户要求不保存时，Agent 改为 config unset header 与 config set header-env。实际 Header 值不会写入普通配置、目录、生成产物或命令输出。", "Environment variable values are runtime-only. By default, an Agent uses config set header HEADER --value-stdin to save one user-provided Header in a local unencrypted credential file. When the user opts out, the Agent uses config unset header and config set header-env instead. Actual Header values never enter ordinary config, catalogs, generated artifacts, or command output."),
+        },
+        configuration: {
+            endpoint: {
+                command: `${COMMAND_NAME} config set endpoint URL`,
+                rule: t("Agent 从用户选定的 MCP server 中识别当前 CLI 可用的 endpoint 后，单独设置 endpoint。", "After identifying the endpoint supported by the current CLI from the user-selected MCP server, the Agent sets the endpoint separately."),
+            },
+            header: {
+                persistentCommand: `${COMMAND_NAME} config set header HEADER --value-stdin`,
+                inputRule: t("Header 值必须只通过标准输入提供，不能出现在命令行参数中。", "A Header value must be supplied only through standard input, never in a command-line argument."),
+                defaultPersistence: true,
+                defaultRule: t("用户未选择时，Agent 默认逐个保存配置中的 Header。CLI 会报告本机未加密保存；支持 POSIX 权限的系统会限制为当前用户读写。", "When the user has not chosen otherwise, the Agent saves each configured Header by default. The CLI reports local unencrypted storage; systems with POSIX permissions restrict it to the current user."),
+                runtimeOnlyRule: t("用户要求不保存时，Agent 对每个 Header 先执行 config unset header HEADER，再执行 config set header-env HEADER ENV_VAR；实际值只放在后续 CLI 进程的环境变量中。", "When the user opts out, for each Header the Agent first runs config unset header HEADER, then config set header-env HEADER ENV_VAR; the actual value exists only in the environment of later CLI processes."),
+            },
+            approvalMetadata: {
+                environmentVariable: ENV.autoApprove,
+                rule: t("若用户配置包含 autoApprove，Agent 将原始 JSON 数组放入 FEIGUAZHITOU_CLI_AUTO_APPROVE 的后续 CLI 进程环境。它只标记本地目录，不会发送给 MCP，也不替代高影响操作的明确授权。", "When the user configuration contains autoApprove, the Agent puts its raw JSON array in FEIGUAZHITOU_CLI_AUTO_APPROVE for later CLI processes. It only annotates the local catalog, is never sent to MCP, and does not replace explicit authorization for high-impact actions."),
+            },
+            standardMcpConfigReference: {
+                purpose: t("用户提供的 mcpServers JSON 只供 Agent 理解并逐项配置 CLI；CLI 不接收、不解析整份 MCP 配置，也不会替 Agent 做字段映射。", "A user-provided mcpServers JSON document is only for an Agent to understand and configure the CLI one setting at a time. The CLI does not accept or parse the complete MCP configuration and does not map fields for the Agent."),
+                selectionRule: t("存在多个 server 时，Agent 依据用户指定的目标选择；不确定时先询问，不猜测。", "When multiple servers exist, the Agent selects the user-designated target; when uncertain, it asks rather than guessing."),
+                forwardCompatibilityRule: t("此说明不是字段白名单。Agent 根据 describe 中当前 CLI 的配置契约识别可映射字段；未知或未来字段保留为参考，不应被拒绝、删除或臆造映射。", "This guide is not a field allowlist. The Agent identifies mappable fields from the current CLI contract in describe; unknown or future fields remain reference information and must not be rejected, discarded, or given an invented mapping."),
+                workflow: [
+                    t("先读取 describe，再理解用户配置。", "Read describe, then interpret the user configuration."),
+                    t("逐项执行 endpoint、Header 与可选 autoApprove 的对应 CLI 配置或环境变量设置。", "Apply the corresponding CLI configuration or environment setting for endpoint, Headers, and optional autoApprove one item at a time."),
+                    t("完成配置后显式执行 refresh，再读取 tools list。", "After configuration is complete, explicitly run refresh, then read tools list."),
+                ],
+            },
+        },
+        transport: {
+            mode: "cli-only",
+            directMcpAccess: "prohibited",
+            callerRule: t(`调用方不得直接连接本机 MCP endpoint 或通过其他 MCP client 调用工具；只能使用 ${COMMAND_NAME} 的规范命令。`, `Callers must not connect to the local MCP endpoint directly or invoke tools through another MCP client; use only canonical ${COMMAND_NAME} commands.`),
+            internalRule: t("CLI 会在内部连接 MCP；该限制仅适用于 CLI 的调用方。", "The CLI connects to MCP internally; this restriction applies only to callers of the CLI."),
+        },
+        timeout: {
+            environmentVariable: ENV.timeout,
+            defaultMs: DEFAULT_TIMEOUT_MS,
+            recommendedLongRunningMs: RECOMMENDED_RPA_TIMEOUT_MS,
+            minimumMs: 1,
+            maximumMs: MAX_TIMEOUT_MS,
+            appliesTo: timeoutAppliesTo,
+            refreshRule: t("生成产物会记录生成时的默认超时。每次 run 都会传入当前超时，因此修改超时后立即生效，不需要 refresh。", "Generated artifacts record their generation-time default timeout. Every run receives the current timeout, so a timeout change takes effect immediately without refresh."),
+            executionRule: t("启动器不会重试工具调用。若生成命令在 --output json 模式下失败且没有 stdout（例如超时），启动器返回 JSON 错误文档，并在 error.details.stderr 中逐字保留生成命令的原始错误。", "The launcher does not retry tool calls. If a generated command fails without stdout in --output json mode (for example, a timeout), the launcher returns a JSON error document and preserves the generated command's raw error verbatim in error.details.stderr."),
+            longRunningRule: t(`默认值已为 ${RECOMMENDED_RPA_TIMEOUT_MS}ms；需要其他等待上限时，config set timeout 会在下一次 run 中生效。`, `The default is already ${RECOMMENDED_RPA_TIMEOUT_MS}ms; config set timeout takes effect on the next run when a different limit is needed.`),
+            bootstrapCommand: t("describe 仅在本地执行，不会连接 MCP。", "describe is local-only and does not contact MCP."),
+        },
+        approval: {
+            environmentVariable: ENV.autoApprove,
+            format: t("MCP 原始工具名或生成 command 名组成的 JSON 数组。", "JSON array of raw MCP tool names or generated command names."),
+            catalogField: "tools[].autoApproved",
+            scope: t("仅为客户端运行时元数据。它不会作为 HTTP Header 发送，也不会授予服务端权限。", "Client-side runtime metadata only. It is not sent as an HTTP header and does not grant server-side permission."),
+            executionRule: t("run 没有交互式批准提示；执行 CLI 命令始终是明确的本地操作。", "run has no interactive approval prompt; invoking a CLI command remains an explicit local action."),
+        },
+        errors: {
+            protocol: "feiguazhitou-mcp-cli.error/v1",
+            useJsonOutput: t("传入 --output json，可将启动器失败以及没有 stdout 的生成命令失败作为 JSON 错误文档返回。", "Pass --output json to receive launcher failures and zero-stdout generated-command failures as JSON error documents."),
+            toolFailureExit: t("MCP 标准 isError:true、飞瓜 ok:false 或非零 BaseResp.StatusCode 会保留 MCP 输出并以退出码 1 结束。", "MCP isError:true, Feiguazhitou ok:false, and non-zero BaseResp.StatusCode preserve MCP output and end with exit code 1."),
+            generatedCommandFailure: t("生成命令非零退出且没有 stdout 时，返回 COMMAND_FAILED；error.details 包含 source、exitCode，以及原始 stderr。", "When a generated command exits nonzero without stdout, the CLI returns COMMAND_FAILED; error.details contains source, exitCode, and the raw stderr."),
+            recoverableCodes: {
+                ARTIFACT_MISSING: t("执行 refresh 后，再重试 tools list/show 或 run。", "Run refresh, then retry tools list/show or run."),
+                ARTIFACT_REFRESH_REQUIRED: t("HTTP Header 名称或生成 CLI 的失败退出码策略与产物不一致，请执行 refresh。", "Run refresh because the HTTP header names or generated CLI failure-exit policy differ from the artifact."),
+                TOOL_NOT_FOUND: t("执行 tools list，并从当前目录选择 command。", "Run tools list and choose a current command."),
+            },
+        },
+        discovery: {
+            workflow: [
+                {
+                    step: 1,
+                    command: [COMMAND_NAME, "describe", "--output", "json"],
+                    purpose: t("读取本地命令契约。该命令离线执行，不连接 MCP。", "Read the local command contract. This command is offline and does not contact MCP."),
+                },
+                {
+                    step: 2,
+                    command: [COMMAND_NAME, "tools", "list", "--output", "json"],
+                    purpose: t("读取本地缓存的工具目录，不连接 MCP。", "Read the local cached tool catalog without contacting MCP."),
+                    onError: t("当 error.code 为 ARTIFACT_MISSING 时，先执行第 3 步再重试。", "When error.code is ARTIFACT_MISSING, run step 3 before retrying."),
+                },
+                {
+                    step: 3,
+                    command: [COMMAND_NAME, "refresh", "--output", "json"],
+                    purpose: t("显式发现实时 MCP schema，并生成或更新本地产物。", "Explicitly discover the live MCP schema and generate or update the local artifact."),
+                },
+                {
+                    step: 4,
+                    command: [COMMAND_NAME, "tools", "show", "NAME", "--output", "json"],
+                    purpose: t("读取精确的输入 schema。NAME 接受 MCP 工具名或生成 command 名。", "Read an exact input schema. NAME accepts an MCP tool name or generated command name."),
+                },
+                {
+                    step: 5,
+                    command: [COMMAND_NAME, "skills", "show", "feiguazhitou-mcp-cli"],
+                    purpose: t("在执行工具前加载安装、配置和安全工作流指南。", "Load installation, configuration, and safe workflow guidance before executing tools."),
+                },
+            ],
+            commands: {
+                config: `${COMMAND_NAME} config set endpoint URL | config set header HEADER --value-stdin | config set header-env HEADER ENV_VAR`,
+                describe: `${COMMAND_NAME} describe [--output json|markdown]`,
+                refresh: `${COMMAND_NAME} refresh [--force] [--output json|text]`,
+                toolsList: `${COMMAND_NAME} tools list [--refresh] [--force] [--output json|text]`,
+                toolsShow: `${COMMAND_NAME} tools show NAME [--refresh] [--force] [--output json|markdown]`,
+                run: `${COMMAND_NAME} run COMMAND --raw '<JSON matching inputSchema>' --output json`,
+                skill: `${COMMAND_NAME} skills show feiguazhitou-mcp-cli`,
+            },
+        },
+        execution: {
+            commandPattern: `${COMMAND_NAME} run GENERATED_COMMAND --raw '<JSON matching inputSchema>' --output json`,
+            rawInput: {
+                inline: `${COMMAND_NAME} run GENERATED_COMMAND --raw '<JSON matching inputSchema>' --output json`,
+                file: `${COMMAND_NAME} run GENERATED_COMMAND --raw @INPUT.json --output json`,
+                standardInput: `cat INPUT.json | ${COMMAND_NAME} run GENERATED_COMMAND --raw - --output json`,
+            },
+            transportRule: t("禁止直连本机 MCP；所有工具调用必须通过 feiguazhitou-mcp-cli run。", "Direct local MCP access is prohibited; every tool invocation must go through feiguazhitou-mcp-cli run."),
+            concurrencyRule: t("飞瓜本机 MCP 按单会话使用。不要并发执行 run、refresh 或 doctor；必须等待上一条会连接 MCP 的命令完全结束后，再执行下一条。CLI 不会自动排队。", "Use the local Feiguazhitou MCP as a single session. Do not run run, refresh, or doctor concurrently; wait for each MCP-connecting command to finish before starting the next one. The CLI does not queue concurrent calls automatically."),
+            toolNameMapping: t("MCP 工具名使用下划线；生成的 command 用连字符替换下划线。", "MCP tool names use underscores; generated commands replace underscores with hyphens."),
+            refreshRule: t("run 不会隐式发现 schema。产物缺失、Header 名称变更或生成 CLI 策略更新时，请显式执行 refresh；仅修改超时不需要 refresh。", "run never performs implicit schema discovery. Refresh explicitly when an artifact is missing, header names changed, or the generated CLI policy changes; a timeout-only change does not require refresh."),
+            failureExitRule: t("工具响应会原样输出；当 MCP 标准 isError:true、飞瓜 ok:false 或非零 BaseResp.StatusCode 表示失败时，退出码为 1。", "Tool responses are printed unchanged; exit code is 1 when MCP isError:true, Feiguazhitou ok:false, or non-zero BaseResp.StatusCode indicates failure."),
+            generatedFailureRule: t("若生成命令在产生 MCP 响应前失败，且请求了 --output json，stdout 会返回 COMMAND_FAILED 错误文档；原始生成命令 stderr 位于 error.details.stderr。", "If a generated command fails before producing an MCP response and --output json was requested, stdout returns a COMMAND_FAILED error document; the raw generated-command stderr is in error.details.stderr."),
+        },
+        catalog: {
+            staleAfterMs: CATALOG_STALE_AFTER_MS,
+            staleRule: t("tools list/show 仅提示目录超过 7 天未检查，不会自动联网或 refresh。", "tools list/show only warn when the catalog has not been checked for over 7 days; they never connect or refresh automatically."),
+        },
+        safety: [
+            t("执行不熟悉的生成 command 前，先使用 tools list 和 tools show。", "Use tools list and tools show before executing an unfamiliar generated command."),
+            t("将返回的账号、订单、直播和分析数据视为敏感信息；不要持久化到本地配置、产物、Skill 或日志。", "Treat returned account, order, live-stream, and analytics data as sensitive; do not persist it in local config, artifacts, Skills, or logs."),
+            t("调用当前或未来可能修改账号状态、发布内容、删除数据或触发外部操作的工具前，须取得明确授权。", "Obtain explicit authorization before invoking a current or future tool that can change account state, publish content, delete data, or trigger external actions."),
+        ],
+    };
+}
+export function describeDocument() {
+    return commandDocument();
+}
+function guideMarkdown() {
+    if (outputLanguage() === "zh") {
+        return `# ${COMMAND_NAME} 命令指南
+
+将此 CLI 用作单个本地飞瓜智投 MCP 连接的发现优先接口。生成工具不会硬编码在启动器中。
+
+## 强制调用边界
+
+Agent、脚本和其他调用方不得直接连接本机 MCP endpoint，也不得通过其他 MCP client 调用工具。所有工具调用必须通过
+\`${COMMAND_NAME} run COMMAND ...\` 发起。CLI 会在内部连接 MCP；此约束不影响 CLI 自己的正常工作。
+
+## 串行调用要求
+
+飞瓜本机 MCP 按单会话使用。不要并发执行 \`run\`、\`refresh\` 或 \`doctor\`；必须等待上一条会连接 MCP 的命令完全结束后，再执行下一条。CLI 不会自动排队。
+
+## 从标准 MCP JSON 初始化
+
+用户在对话中提供的 \`mcpServers\` JSON 只供 Agent 理解并逐项配置 CLI。CLI 不读取或解析整份 JSON，也不代替 Agent 做字段映射。Agent 先执行 \`${COMMAND_NAME} describe --output json\`，再根据当前契约和用户指定的 server 逐项配置；多个 server 无法确定目标时先询问，不猜测。
+
+当前 CLI 需要 endpoint 时，Agent 从已选 server 中取对应地址，并执行：
+
+\`${COMMAND_NAME} config set endpoint URL\`
+
+对用户配置中的每个 Header，用户没有要求不保存时，Agent 默认逐个执行 \`${COMMAND_NAME} config set header HEADER --value-stdin\`，只经标准输入提供该 Header 值，绝不把值放到命令行参数中。该命令会保存到本机未加密凭据文件；支持 POSIX 权限的系统会限制为当前用户读写，Agent 必须告知用户。用户要求不保存时，Agent 对每个 Header 执行 \`${COMMAND_NAME} config unset header HEADER\` 和 \`${COMMAND_NAME} config set header-env HEADER ENV_VAR\`，并让实际值只存在于后续 CLI 进程的环境变量中。
+
+用户配置若有 \`autoApprove\`，Agent 将其原始 JSON 数组设置为后续 CLI 进程的 \`${ENV.autoApprove}\`。它只标记本地工具目录，不会发送给 MCP，也不替代高影响操作的明确授权。额外或未来新增字段不是错误：此说明不是字段白名单，Agent 应保留其参考意义，并仅在当前 \`describe\` 已定义映射时才配置；不能自行臆造映射或删除字段。
+
+逐项配置完成后，Agent 显式执行 \`${COMMAND_NAME} refresh --output json\`，再读取 \`${COMMAND_NAME} tools list --output json\`，按当前 schema 使用 \`tools show\` 和 \`run\`。整个过程只能使用 CLI，不能直连原始配置中的 MCP URL。
+
+## 1. 阅读本地契约
+
+\`${COMMAND_NAME} describe --output json\`
+
+该命令仅在本地执行，不会连接 MCP。JSON 响应说明规范命令、错误协议、环境变量、超时规则和安全约束。
+
+## 2. 读取缓存工具，必要时显式刷新
+
+\`${COMMAND_NAME} tools list --output json\`
+
+该命令读取已激活的本地目录。若返回 \`ARTIFACT_MISSING\`，执行：
+
+\`${COMMAND_NAME} refresh --output json\`
+
+仅在明确需要实时 schema 检查时使用 \`tools list --refresh\`。如果本地目录超过 7 天未检查，\`tools list\` 和 \`tools show\` 会提示刷新建议，但不会自动联网。
+
+## 3. 调用前读取一个工具
+
+\`${COMMAND_NAME} tools show NAME --output json\`
+
+\`NAME\` 可以是带下划线的 MCP 工具名，也可以是带连字符的生成 command。响应包含精确的 \`inputSchema\` 和 \`--raw\` 调用模板。复杂 JSON 既可以内联传 \`--raw '<json>'\`，也可以传 \`--raw @INPUT.json\`，或用 \`cat INPUT.json | ... --raw -\` 从标准输入读取。
+
+## 4. 阅读工作流 Skill
+
+\`${COMMAND_NAME} skills show feiguazhitou-mcp-cli\`
+
+该 Skill 说明本地客户端设置、凭据、刷新规则、敏感数据处理和诊断步骤，不固定 MCP 工具清单。
+
+## 5. 执行并检查结果
+
+\`${COMMAND_NAME} run GENERATED_COMMAND --raw '<JSON matching inputSchema>' --output json\`
+
+默认超时为 \`${DEFAULT_TIMEOUT_MS}\`ms。需要其他等待上限时，执行 \`${COMMAND_NAME} config set timeout MILLISECONDS\`；新值会在下一次 \`run\` 中直接生效，无需 refresh。环境变量只影响当前进程；需要长期使用时，使用 \`config set timeout\` 保存该值。artifact 会保留生成时的默认超时，\`artifact.currentTimeoutMatches: false\` 只表示默认值不同；\`run\` 始终使用当前超时。需要保留原 MCP 客户端批准元数据时，将 \`${ENV.autoApprove}\` 设为 MCP 原始工具名或生成 command 名的 JSON 数组；匹配的目录项会显示 \`autoApproved: true\`。工具调用仅发送一次；第三方错误和超时错误不会被重试或由启动器改写。MCP 标准 \`isError:true\`、飞瓜 \`ok:false\` 或非零 \`BaseResp.StatusCode\` 时，原 MCP 输出保持不变，但进程以退出码 1 结束。
+`;
+    }
+    return `# ${COMMAND_NAME} Command Guide
+
+Use this CLI as a discovery-first interface for one local Feiguazhitou MCP connection. Generated tools are not hard-coded into the launcher.
+
+## Mandatory Transport Boundary
+
+Agents, scripts, and other callers must not connect to the local MCP endpoint directly or invoke tools through another MCP client. Every tool call must use
+\`${COMMAND_NAME} run COMMAND ...\`. The CLI connects to MCP internally; this restriction does not affect the CLI itself.
+
+## Serial Invocation Requirement
+
+Use the local Feiguazhitou MCP as a single session. Do not run \`run\`, \`refresh\`, or \`doctor\` concurrently; wait for each MCP-connecting command to finish before starting the next one. The CLI does not queue concurrent calls automatically.
+
+## Initialize from a Standard MCP JSON Document
+
+An \`mcpServers\` JSON document that a user provides in a conversation exists only for the Agent to understand and configure the CLI one setting at a time. The CLI neither reads nor parses the complete JSON document, and it does not map fields for the Agent. The Agent first runs \`${COMMAND_NAME} describe --output json\`, then uses the current contract and the user-selected server to configure each setting. If multiple servers are present and the target is unclear, ask instead of guessing.
+
+When the current CLI needs an endpoint, the Agent identifies the corresponding address in the selected server and runs:
+
+\`${COMMAND_NAME} config set endpoint URL\`
+
+For every Header in the user configuration, unless the user opted out of persistence, the Agent runs \`${COMMAND_NAME} config set header HEADER --value-stdin\` one Header at a time. Supply the Header value only through standard input, never as a command-line argument. The command saves it in a local unencrypted credential file; systems with POSIX permissions restrict it to the current user, and the Agent must tell the user. When the user opts out, for each Header run \`${COMMAND_NAME} config unset header HEADER\` and \`${COMMAND_NAME} config set header-env HEADER ENV_VAR\`, and keep the actual value only in the environment of later CLI processes.
+
+When the user configuration includes \`autoApprove\`, the Agent places its raw JSON array in \`${ENV.autoApprove}\` for later CLI processes. It only annotates the local tool catalog, is never sent to MCP, and does not replace explicit authorization for high-impact actions. Additional or future fields are not errors: this guide is not a field allowlist. Preserve them as reference information and configure them only when the current \`describe\` contract defines a mapping; never invent a mapping or discard a field.
+
+After individual configuration is complete, the Agent explicitly runs \`${COMMAND_NAME} refresh --output json\`, then reads \`${COMMAND_NAME} tools list --output json\` and uses \`tools show\` and \`run\` against the current schema. The whole workflow remains CLI-only; never connect directly to the source MCP URL.
+
+## 1. Read the local contract
+
+\`${COMMAND_NAME} describe --output json\`
+
+This command is local-only and does not contact MCP. Its JSON response identifies the canonical commands, error protocol, environment variable names, timeout rules, and safety constraints.
+
+## 2. Read cached tools, then refresh explicitly when needed
+
+\`${COMMAND_NAME} tools list --output json\`
+
+This reads the activated local catalog without contacting MCP. When it returns \`ARTIFACT_MISSING\`, run:
+
+\`${COMMAND_NAME} refresh --output json\`
+
+Use \`tools list --refresh\` only when a live schema check is deliberately required. When the local catalog has not been checked for over 7 days, \`tools list\` and \`tools show\` show a refresh hint but never connect automatically.
+
+## 3. Read one tool before invoking it
+
+\`${COMMAND_NAME} tools show NAME --output json\`
+
+\`NAME\` can be the MCP tool name with underscores or the generated command with hyphens. The response includes the exact \`inputSchema\` and a \`--raw\` invocation template. Complex JSON can be inline with \`--raw '<json>'\`, read with \`--raw @INPUT.json\`, or provided through \`cat INPUT.json | ... --raw -\`.
+
+## 4. Read the workflow Skill
+
+\`${COMMAND_NAME} skills show feiguazhitou-mcp-cli\`
+
+The Skill explains local-client setup, credentials, refresh rules, sensitive-data handling, and diagnostic steps without fixing the MCP tool list.
+
+## 5. Execute and inspect results
+
+\`${COMMAND_NAME} run GENERATED_COMMAND --raw '<JSON matching inputSchema>' --output json\`
+
+The default timeout is \`${DEFAULT_TIMEOUT_MS}\`ms. To use a different limit, run \`${COMMAND_NAME} config set timeout MILLISECONDS\`; the new value takes effect on the next \`run\` without refresh. Set \`${ENV.timeout}\` to an integer from \`1\` to \`${MAX_TIMEOUT_MS}\` when a different MCP timeout is needed; the environment variable applies only to the current process. An \`artifact.currentTimeoutMatches: false\` value only means the generation-time default differs; \`run\` always uses the current timeout. Set \`${ENV.autoApprove}\` to a JSON array of raw MCP tool names or generated command names when an orchestrator needs the original MCP client approval metadata; matching catalog entries expose \`autoApproved: true\`. Tool calls are sent once; third-party errors and timeout errors are returned without retry or launcher-side rewriting. MCP \`isError:true\`, Feiguazhitou \`ok:false\`, and non-zero \`BaseResp.StatusCode\` preserve MCP output but end the process with exit code 1.
+`;
+}
+export function describeMarkdown() {
+    return guideMarkdown();
+}
+//# sourceMappingURL=agent-guide.js.map

package/dist/agent-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.js","sourceRoot":"","sources":["../src/agent-guide.ts"],"names":[],"mappings":"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"}

package/dist/cli-error.js

@@ -0,0 +1,30 @@
+export const CLI_ERROR_PROTOCOL = "feiguazhitou-mcp-cli.error/v1";
+export const CLI_ERROR_PROTOCOL_VERSION = 1;
+export class CliError extends Error {
+    code;
+    remediation;
+    details;
+    constructor(code, message, remediation, details) {
+        super(message);
+        this.code = code;
+        this.remediation = remediation;
+        this.details = details;
+        this.name = "CliError";
+    }
+}
+export function errorDocument(error) {
+    const cliError = error instanceof CliError
+        ? error
+        : new CliError("COMMAND_FAILED", error instanceof Error ? error.message : String(error));
+    return {
+        protocol: CLI_ERROR_PROTOCOL,
+        protocolVersion: CLI_ERROR_PROTOCOL_VERSION,
+        error: {
+            code: cliError.code,
+            message: cliError.message,
+            ...(cliError.remediation ? { remediation: cliError.remediation } : {}),
+            ...(cliError.details ? { details: cliError.details } : {}),
+        },
+    };
+}
+//# sourceMappingURL=cli-error.js.map

package/dist/cli-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-error.js","sourceRoot":"","sources":["../src/cli-error.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAClE,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAU5C,MAAM,OAAO,QAAS,SAAQ,KAAK;IAEf;IAEA;IACA;IAJlB,YACkB,IAAkB,EAClC,OAAe,EACC,WAAoB,EACpB,OAAiC;QAEjD,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,SAAI,GAAJ,IAAI,CAAc;QAElB,gBAAW,GAAX,WAAW,CAAS;QACpB,YAAO,GAAP,OAAO,CAA0B;QAGjD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,QAAQ,GAAG,KAAK,YAAY,QAAQ;QACxC,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,QAAQ,CAAC,gBAAgB,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3F,OAAO;QACL,QAAQ,EAAE,kBAAkB;QAC5B,eAAe,EAAE,0BAA0B;QAC3C,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D;KACF,CAAC;AACJ,CAAC"}