muran-cli

v0.4.5

Published

2 days ago

Sigmob CLI

0High
0Medium
0Low

yuqing.gao

Sigmob Monetization CLI 开发指南

JSON-only 业务命令（0.3.0）

本节面向 CLI 开发者。业务输入解析集中在 src/lib/request-input.ts；BaseCommand 在创建客户端前加载已安装 Spec 的 request_schema 并校验。规则缺失或不兼容时明确失败。

路径限制：--data-file 与 --channel-context-file 仅接受当前工作目录（CWD）内的文件；跨目录文件请通过管道传入 --data-file -。

字段规则维护在 ai-spec/apis/**/*.json 的 request_schema，使用 JSON Schema draft-07；不要重新添加业务 flags。
聚合管理参数以官方接口文档为依据，不从旧 flags 或现有示例反推。Schema 应包含嵌套必填和条件约束；保留扩展字段不等于省略已知规则。
契约测试使用独立文档用例：test/unit/lib/aggregation-contract.test.ts；test/regression/json-input.py 验证同一请求在 validate、dry-run 和 Mock 执行中的一致性，不能仅用 Schema 验证自身示例。
编辑字段必须按契约区分“省略”和 null，例如 auto_refresh_interval:null 表示关闭自动刷新。组合创建只保留手写结果处理，输入校验统一交给 Schema。
聚合分页使用 src/sdk/request-pagination.ts 共享解析器，供 SDK 与 validate 复用；新增聚合分页路由时同步登记 API ID。完整命令入口与功能回归见 test/regression/all-commands.py。
完整规则与待确认项见请求契约核对表；不要将渠道关联条件或未核实的 Sigmob 字段硬编码成统一必填。
创建和编辑分别声明必填规则；additionalProperties 默认允许新增业务字段，认证保留字段由公共层禁止覆盖。
普通写命令复用 JsonWriteCommand，预览和发送使用同一份请求；组合创建仍手写结果处理。
codegen 生成已登记的查询及 JSON 写命令骨架和双输入示例，不生成业务字段清单。
已有接口新增普通字段或必填规则时，更新 Spec 和请求数据即可；新增命令、编码或特殊业务流程仍需要发布 CLI。
每个 API 的 examples 同时维护文件和内联 JSON 示例；写操作示例加 --dry-run。注释、说明和提示使用中文。
schema api 展示 requestSchema；validate 与实际执行共用校验规则，不需要业务凭证。
CLI 0.3.0 与 AI Spec 0.5.0 必须协调发布；不要只发 CLI 而仍提供旧 Spec。
本次未迁移输出协议，也不改变原有服务端响应解析与业务错误分类。

验证：npm run codegen、npm run build、npm test、python3 ai-spec/scripts/check_all.py。修改 Spec 或 Skill 后运行 python3 ai-spec/scripts/update_spec_files.py 更新文件哈希。

示例门禁：test/unit/commands/json-examples.test.ts 检查全部业务命令的帮助示例与 Spec 一致，并解析使用指南、Skill 与现行编写规范中的命令，校验内联 JSON 和写操作 --dry-run。

本地联调优先使用 npm run cli -- <命令和参数>，自动构建当前代码并加载仓库 ai-spec/（见下方开发设置）。已有构建时也可使用 node ./bin/run.js，但需自行设置 SIGMOB_SPEC_DIR 才会加载本地 Spec。直接运行 sigmob-monetization-cli 可能仍指向旧版全局安装；构建源码不会更新全局包。若初始化提示仍出现 --start / --end / --group-by，先检查 command -v sigmob-monetization-cli 和 sigmob-monetization-cli --version，再按需重新安装 CLI；不要据旧版输出回改现行 JSON 示例。

本文面向 CLI 开发和维护人员，说明本地开发、架构约束、验证与发布流程。安装、账号配置和命令使用请阅读 CLI 使用指南；详细实现见技术设计。

1. 项目简介

sigmob-monetization-cli 是面向 Sigmob 与 ToBid 变现业务的管理 CLI，覆盖报表查询和广告资源管理。

基于 oclif v4、TypeScript 5.7+ 和 ESM 构建
运行环境要求 Node.js >= 20
支持 ToBid 报表 API 与 Sigmob 管理 API

当前 package.json 中的包名 muran-cli 仅用于临时测试；正式 CLI 全局命令名统一为 sigmob-monetization-cli。

2. 环境要求

| 工具 | 版本要求 | |------|----------| | Node.js | >= 20 | | npm | >= 8 |

3. 开发设置

git clone REPOSITORY_URL
cd tobid-cli
npm ci
npm run build    # 清理 dist、编译、重写别名并生成命令清单
# 可选：npm link，将本地版本注册为全局命令（会影响全局同名入口）

安装后可以通过 sigmob-monetization-cli welcome 再次查看能力总览。

全局安装的 postinstall 在非 CI 环境中始终输出完整能力 banner：交互式终端向 stdout 输出彩色内容，AI 代理等非 TTY subprocess 向 stderr 输出无色内容。CI 环境及本地 npm install 保持静默。

无需全局链接，也可以直接运行构建产物：

node bin/run.js --help

3.1 本地 CLI 与 AI Spec 联调

在仓库根目录运行，无需全局安装或手动设置环境变量：

# 不传命令时显示帮助
npm run cli

# 查询应用（真实业务接口）
npm run cli -- sigmob app list

# 输出 JSON
npm run cli -- sigmob app list --format json

# 预览写操作，不执行创建
npm run cli -- tobid placement create --data '{"name":"示例插屏广告位","app_id":1875,"ad_type":4}' --dry-run

# 仅校验参数，不调用业务接口
npm run cli -- validate tobid.placement.create --data '{"name":"示例插屏广告位","app_id":1875,"ad_type":4}' --format json

# 脚本读取 JSON 时，关闭 npm 的入口提示；构建日志写入 stderr
npm run --silent cli -- validate S1 --format json

此入口每次先构建当前仓库代码（含命令清单），构建失败则停止，再从临时副本启动 CLI，退出后清理副本。报表仍使用 https://report.sigmob.com，管理接口使用 https://testdash.sigmob.com，请使用测试账号。源码和正式 dist 保持生产域名；直接运行 node ./bin/run.js 仍使用生产域名。自动使用仓库 ai-spec/，跳过自动 Spec 同步、隐式安装和后台更新通知；不替换全局 CLI 或用户目录中的 current，不自动注册 Skill。首次使用前需安装项目依赖（npm ci）。修改代码或 Spec 后直接重新执行即可。

本地指代码和 Spec，不是 Mock 环境。 业务命令仍读取现有凭证、访问真实服务；写操作测试请先使用 --dry-run。 init / update spec / skills install 等显式管理命令仍会执行对应安装或配置操作。 JSON 参数校验和最低 CLI 版本检查保持生效。本地 Spec 不经过发布 ZIP 的哈希验证，仅应使用受信任的文件。

已有构建、希望跳过重建时，也可单次指定本地 Spec：

SIGMOB_SPEC_DIR="$PWD/ai-spec" node ./bin/run.js sigmob app list

SIGMOB_SPEC_DIR 支持绝对路径及相对于工作目录的路径。目录无效时直接报错，不回退到已安装 Spec；取消该变量即可恢复默认加载方式。

4. 目录结构

src/
├── base/                    # 命令基类：BaseCommand, ReadCommand, WriteCommand
├── commands/                # CLI 命令（auth/config/tobid/sigmob/...）
├── config/                  # 凭证、配置与更新检查
│   ├── auto-spec-sync.ts    # AI Spec 定时自动同步、失败重试与锁
│   ├── update-notifier.ts   # CLI 新版本的 24 小时非阻塞通知
│   └── ...                  # 凭证、设置、时钟偏差等配置
├── lib/
│   ├── schema-loader.ts     # 已安装 AI Spec 加载与兼容性检查
│   ├── request-input.ts     # 原生 JSON 输入与运行时请求校验
│   └── types.ts             # Schema 与结构化输出类型
├── renderer/                # 输出渲染器 (table/json/csv)
├── sdk/                     # HTTP 客户端、签名器、限流、分页
├── skills/                  # Skill 管理器与 registration.ts 链接登记/同步
├── spec-manager/            # AI Spec 包下载、校验与安装
└── utils/                   # 日志、审计工具
scripts/
├── codegen.ts               # Schema 驱动命令生成器
├── local-cli.mjs            # 本地构建与测试环境 CLI 运行
├── test-domains.mjs         # 开发运行与测试打包共用的域名替换
└── pack-test.mjs            # 内部测试包打包
ai-spec/                     # 仅用于开发和 codegen 构建，不随 npm 包发布
test/
├── unit/                    # Vitest 单元测试
└── regression/              # 隔离 HOME、假凭证与封闭 HTTP Mock 的 CLI 回归
docs/                        # 问题核验报告；test-evidence-* 执行证据目录已忽略

5. 技术架构

双凭证系统：ToBid 凭证用于报表 API（report.sigmob.com），Sigmob 凭证用于管理 API（mmapi.sigmob.com）。
命令基类层级：BaseCommand 提供通用能力；ReadCommand 负责分页和输出；WriteCommand 负责 dry-run、确认和审计。
Schema 驱动：仓库 ai-spec/ 中的 JSON Schema 用于开发和 codegen；运行时参数校验读取用户目录中按需安装的 Spec。
路径别名：@/ 映射到 src/，构建时由 tsc-alias 重写为 Node.js ESM 可加载的相对路径。

5.1 AI Spec 按需下载机制

npm 包不内置 AI Spec。init 显式安装 Spec；只有需要调用后端 API、继承 BaseCommand 的业务命令会定期自动同步新发布的 Spec，并在缺少 Spec 时尝试首次安装。schema、validate 等不依赖远端数据的命令继承 CliCommand，保持离线可用，不触发 Spec 自动下载或首次 Skill 自动注册。下载失败会告警，并尝试使用已有 Spec；没有可用 Schema 时可降级继续执行，但不跳过凭证检查或已有 Spec 的兼容性检查。update spec 是 Schema 与 Skill 内容的统一更新入口，无需重新安装 CLI。首次下载或更新成功后，CLI 默认将当前 Spec 的 Skill 自动链接到公共入口和检测到的 Agent 目录。SchemaLoader 仅从用户目录中的 installed Spec 读取，不再提供随包回退。

CLI 更新检查从当前安装包的 package.json.name 获取 npm 包名，并查询 npm 官方 registry 的 latest：测试包为 muran-cli，正式包为 sigmob-monetization-cli。该查询不读取本机 .npmrc，也不自动安装 CLI。

AI Spec 更新继续读取 OSS Manifest。为兼容现有发布链，Manifest 保留双节点结构，但其中 cli 节点不再用于 CLI 更新判断：

{
  "schema_version": "...",
  "cli": { "version": "...", "url": "...", "sha256": "...", "min_node_version": "..." },
  "ai_spec": { "version": "...", "url": "...", "sha256": "...", "min_cli_version": "...", "notes": "..." }
}

Spec 安装安全与目录布局

首次下载、初始化和显式更新共用安装校验：要求包级 SHA256、逐文件哈希、有效索引、匹配的包版本及受支持的格式（当前为 V2），并验证最低 CLI 版本。
指定版本读取 sha256.txt（支持摘要及 sha256sum 的摘要加文件名格式）；缺少或损坏校验信息时停止安装，--force 也不会跳过校验。
每次安装写入独立的 ~/.sigmob-monetization-cli/specs/<version>_<installation-id>/，验证完成后通过原子替换 current 软链激活。旧 <version>/ 目录仍兼容，旧安装暂不自动删除；同版本重装不会覆盖旧内容。
暂存目录按调用隔离，提交阶段使用 specs/.install.lock 互斥。并发安装失败的一方需稍后重试；若进程被强制终止留下锁，先查看其中的 owner.json 并确认没有安装进程运行，再移除残留锁。正常成功或失败会清理暂存文件和锁。
更新后运行时缓存会清空。现有进程已加载的数据不会被强制刷新；尚未固定版本的跨文件读取仍可能跨越一次更新。

5.2 AI Spec 自动同步

npm 只升级 CLI。执行需要调用后端 API、继承 BaseCommand 的业务命令时，CLI 每小时最多检查一次 OSS AI Spec；因此同一 CLI 版本也能无须手动操作地获取独立发布的新 Spec。没有本地 Spec 时会立即尝试首次安装。schema、validate 等继承 CliCommand 的本地命令不参与自动同步，以确保离线可用。只下载整个 Spec 包，Skill 不单独下载、不提供 skills update。

首次自动安装 Skill

有更新时校验 SHA256、包结构和最低 CLI 版本后原子切换 current，然后维护已登记的 Skill 链接；注册记录不存在时，自动执行一次幂等的用户级 Skill 安装。本地版本更高时不会自动降级。
同一小时内不重复 manifest 检查；即使仍在检查间隔内，注册记录被删除也会补齐首次 Skill 自动安装。手动 update spec 成功也记录检查时间。
自动同步失败不记录成功，保留可用的本地 Spec，下一小时内不重复尝试；Skill 自动安装失败仅告警，不阻塞 Spec 安装、更新或业务命令。
自动安装仅写公共入口和 agents.json 中检测到且允许自动安装的 Agent 用户目录；不扫描未登记项目，也不恢复项目级安装。Cursor 的 auto_install:false 保持跳过，仍可显式使用 skills install --agent cursor。
--help、版本、诊断、初始化、认证配置、技能管理和显式更新命令不触发周期升级检查。schema、validate 等 CliCommand 本地命令也不触发 Spec 自动下载；部分其他 BaseCommand 命令仍可复用缺失 Spec 时的首次安装逻辑。卸载、状态、列表和清理命令不隐式下载 Spec。
CI 为任意非空值时关闭 Skill 自动安装。设置 SIGMOB_NO_AUTO_SKILL_INSTALL=1，或在 ~/.sigmob-monetization-cli/config.yaml 中配置 auto_skill_install: false，也可关闭自动写入 Agent 目录；显式 skills install 不受影响。
设置 SIGMOB_NO_AUTO_SPEC_UPDATE=1 可关闭升级自动同步及缺失 Spec 的隐式下载；SIGMOB_NO_UPDATE_CHECK=1 同时关闭后台版本通知和升级自动同步。自动 manifest 检查超时 5 秒、下载超时 15 秒，日志写到 stderr。

SIGMOB_NO_AUTO_SPEC_UPDATE=1 sigmob-monetization-cli sigmob app list
SIGMOB_NO_AUTO_SKILL_INSTALL=1 sigmob-monetization-cli auth whoami
sigmob-monetization-cli update spec          # 包含 Skill 内容更新和链接维护
sigmob-monetization-cli update spec --check  # 只检查，不修改注册或同步状态

同步状态与注册记录分别存储在 CLI 数据目录中的 cache/auto-spec-sync.json 和 skills/registrations.json。并发修改使用目录锁；异常退出残留锁时，先确认没有同步任务运行，再按错误提示移除对应锁目录。

Skill 孤儿链接清理

skills prune 不依赖 registrations.json，而是读取 agents.json 并物理扫描已检测到的 Agent candidate_dirs。它只识别指向本 CLI Spec 目录的符号链接，报告当前 Spec 已移除的 Skill 或不可达目标。默认和 --dry-run 都只预览；只有 --yes 才删除，二者不能同时使用。--agent 可限定 Agent，--format json 提供结构化报告。

sigmob-monetization-cli skills prune
sigmob-monetization-cli skills prune --yes
sigmob-monetization-cli skills prune --agent qoderwork
sigmob-monetization-cli skills prune --dry-run --format json

5.3 CLI 新版本非阻塞通知

普通命令启动后会以 fire-and-forget 模式检查 npm 中的 CLI 新版本，cache/cli-update-check.json 将请求节流为每 24 小时最多一次。发现比当前版本更高的版本时，只提示 npm install -g <package>@latest，绝不自动安装；相同可用版本只提示一次。AI Spec 不在这里提示，改由上一节的自动同步静默安装。update self 始终直接检查 npm，不受该缓存限制。update、update self、update spec、version、doctor、init、completion 命令会跳过自动通知。在 CI 或离线环境中可设置 SIGMOB_NO_UPDATE_CHECK=1 跳过自动通知及 Spec 自动同步。

5.4 V2 Schema 运行时校验

Spec 0.4.0 的 apis 使用 { "path": "tobid/app/list", "schema": "apis/tobid/app/list.json" }，运行时仍兼容旧字符串引用。src/lib/spec-manifest.ts 为安装器、SchemaLoader 和 codegen 提供统一解析与安全路径检查。8 个聚合管理查询、4 个报表及 21 个 JSON 写命令已启用 codegen；sigmob app list 和 tobid adsource combo-create 保持手写。参见 Spec 缺失文件修复记录。

BaseCommand.init() 会先按命令类型和环境开关尝试同步 AI Spec；声明 schemaId 的命令随后自动加载 Schema 并校验 flags。参数不符合 Schema 时抛出 ValidationError 并以退出码 2 结束；CLI 与 Spec 不兼容时抛出 CompatibilityError 并以退出码 8 结束；找不到 Schema 或遇到非兼容性加载错误时降级为无校验，避免阻断原有命令。

5.5 JSON 结构化输出

只读业务查询使用 --format json 时，成功响应采用以下 envelope；已知业务错误（SigmobError）采用错误 envelope：

{ "ok": true, "data": {}, "_meta": {} }

{ "ok": false, "error": { "type": "...", "code": 2, "message": "..." } }

错误对象可按类型附带 apiCode、missingParams、invalidParams、suggestions、retryAfterMs 等字段，便于脚本和 AI Agent 解析。并非所有命令或 oclif 参数解析错误都采用同一 envelope：

schema api R1 --format json 输出单个完整 Schema 对象。
config get <key> --format json 输出配置值本身，保留其 JSON 类型；未设置的键当前输出 null，退出码为 0。
auth login --format json 输出 { "ok": true, "data": { "profile": "...", "saved": true } }。
auth test --format json 输出探测结果数组；应同时检查进程退出码，不能只依赖 JSON 是否可解析。

`welcome --json` 能力摘要

welcome --json 只向 stdout 输出一个 JSON 文档，字段采用 snake_case，稳定契约如下；spec.version 与 spec.installed_at 在未安装 Spec 时为 null，后续版本只新增字段，不删除现有字段：

{
  "cli": { "name": "muran-cli", "version": "0.4.2", "bin": "/absolute/path" },
  "spec": { "version": "0.6.3", "installed_at": "/absolute/spec/current" },
  "profile": { "name": "default", "env": "prod" },
  "capabilities": [{ "group": "tobid.report", "label": "报表", "commands": ["tobid.report.overview"] }],
  "env_notices": [{ "level": "warn", "key": "NODE_TLS_REJECT_UNAUTHORIZED", "message": "TLS 证书校验已禁用" }],
  "skills": { "installed_agents": ["qoderwork"], "has_registrations": true },
  "next_steps": [{ "label": "查看命令列表", "command": "sigmob-monetization-cli schema api" }]
}

5.6 凭证预检引导

声明 credentialType 的业务命令会在执行前自动检查凭证完整性。凭证缺失时，TTY 环境会启动交互式配置引导；非交互式环境会给出 auth init 或 auth login 的处理提示并退出。

5.7 查询分页与日期参数

| 参数 | 当前行为 | |------|----------| | --page-size <n> | 每页条数，默认 100，必须为正的安全整数；接口实际范围仍以对应 API 契约为准 | | --page-all | 对报表命令启用自动分页；默认只请求单页 | | --page-limit <n> | 跨页总条数上限；报表命令指定此项也会启用分页，无需同时传 --page-all；0 返回空结果、不发起业务数据请求 | | --limit <n> | 仅截断最终输出，不减少已经发出的分页请求；0 保持“不限制”语义 | | --page-delay <ms> | 分页等待毫秒数，默认 0，范围 0–2147483647；聚合管理列表也会应用此参数 |

--limit 与 --page-limit 不接受负数或不安全整数。ToBid 聚合管理列表目前由 SDK 自动遍历分页，与报表默认单页的行为不同；Sigmob 应用列表没有分页遍历能力，但仍应用输出条数上限。

报表校验真实日期和先后顺序；小时报表还接受 YYYY-MM-DD HH:00:00 整点格式。综合/留存报表最多 30 天，小时/DAU 最多 3 天；纯日期包含首尾日期，整点按实际间隔计算。小时报表每页最多 5000 条，其他报表最多 2000 条，聚合分页最多 100 条。报表文档的最小页大小表格与示例冲突，暂保留正整数小页输入，不据此保证线上支持。报表广告类型分组使用 ad_type。

6. 构建命令

| 命令 | 说明 | |------|------| | npm run cli -- <命令和参数> | 自动构建，使用测试域名与本地 AI Spec 运行临时副本；不传命令时显示帮助 | | npm run build | 清理 dist、编译 TypeScript、重写路径别名并生成命令清单；任一步失败即失败 | | npm run codegen | 根据 Schema 生成 12 个查询及 21 个 JSON 写命令 | | npm test | 检查源码、测试及脚本的 TypeScript 类型，再运行 Vitest | | npm test -- --coverage | 同上，并生成覆盖率报告 | | npm run pack:test | 构建并生成内部测试 .tgz，不发布 npm |

日常使用 cli、build、test 和 pack:test 即可。仅修改生成规则时运行 codegen；prepack / postpack 是 npm 自动调用的 README 处理钩子，无需手动执行。

6.1 回归验证

修改代码后，先构建再运行离线 CLI 回归；npm test 不会自动执行 Python 回归脚本。Python 脚本需要 Python 3，PTY 检查仅适用于 macOS/Linux。

npm run build
npm test
python3 test/regression/regression.py
python3 test/regression/spec-install.py
python3 test/regression/codegen.py
python3 test/regression/auth-pty.py
python3 test/regression/skills.py

regression.py：命令、输出、凭证与分页回归，断言数以当次输出为准，行为观察项不算通过断言。
spec-install.py：真实 ZIP 安装链路，覆盖首装、强制重装、不重复下载、全部 API 的 ID/命令路径查询、doctor 及哈希失败保留旧安装。
codegen.py：在临时目录中验证新旧 API 索引生成相同的 33 个命令，验证重复生成一致、禁用跳过、两条手写命令保护、写命令风险与分页契约及路径穿越拒绝。
current-spec.test.ts：直接读取仓库 Spec，验证每个引用文件和哈希，并对齐管理 Schema 与实际 CLI flags，防止漏提交文件后只通过 Mock 测试。
auth-pty.py：真实终端提问顺序、Secret Key 掩码及保存后五项凭证值检查，防止输入错位。
skills.py：真实 CLI 的用户/项目安装、链接修复、Spec 更新、卸载保持与版本同步回归。
脚本使用临时 HOME、假凭证和封闭 fetch Mock，不调用线上业务 API。回归通过不等于线上 API 契约已验证。
AI Spec 数据层修改还需在安装了 ai-spec/scripts/requirements.txt 的 Python 环境中运行 python ai-spec/scripts/check_all.py。
docs/test-evidence-*/ 是已被 Git 忽略的本地执行证据；test/ 中的可重复测试应提交版本控制。

6.2 当前 review 已知限制（2026-09-15）

以下问题尚未修复，不应把现有测试全绿视为它们已通过验证：

auth test 在解析 JSON 后才判断 HTTP 状态：401/403 的非 JSON 错误页会退出 1 而不是 3；HTTP 429 当前退出 6 而不是 5；HTTP 200 返回 null 会被误分为网络错误（4）。自动化暂不可完全依赖这些边界场景的错误分类。
回归 mock-fetch.mjs 未解析留存报表的 POST URL-encoded 表单，分页参数会回落到默认值。需要修正 Mock 并补充留存报表请求页码、页大小和结果不重复断言，才能验证该路径。

7. 修改代码时必须保持的约束

凭证与 Profile

交互顺序固定为 Sigmob 流量变现平台用户名 → ToBid Public Key → ToBid Secret Key → Sigmob Public Key → Sigmob Secret Key，五项全部必填，Secret Key 使用掩码输入。
auth init 负责交互式配置；auth login 非交互式接收全部五项，不允许只更新一组凭证；init 组合环境检查、凭证配置、Spec 安装与用户级 Skill 安装。
Profile 选择优先级为显式 --profile / -p > SIGMOB_PROFILE > 配置 default_profile > default。显式空字符串、纯空格必须报错，不能静默回退。
凭证错误不能跨 Profile 回退；凭证环境变量仍可覆盖选中 Profile 的对应字段。修改解析逻辑时必须覆盖这两层优先级。
保存凭证不等于认证成功，认证验证由 auth test 执行。初始化部分失败必须明确告知，不得误报全部成功。

Skill 生命周期

Skill 内容来自 OSS AI Spec，不进入 npm 包，不使用 npm 安装钩子下载，也不提供独立 skills update。
init 默认安装全部用户级 Skill；skills install 使用公共目录加 agents.json 中检测到的 Agent 入口。--agent 可显式选择目标；--scope project 只使用明确配置的项目级路径，不猜测未知目录。
src/skills/agents.ts 校验适配配置、探测父配置目录、按目标路径去重。缺少 skills 子目录不代表 Agent 未安装；探测和文件链接有效不能宣称 Agent 已加载。Cursor 默认跳过，QoderWork 未配置项目级路径。
链接指向 ~/.sigmob-monetization-cli/specs/current/skills/<name>；registration.ts 记录安装范围及全部/指定名称的选择。
全部安装跟随 Spec 新增、删除和改名；指定名称安装不猜测替代项。同步只维护登记过的范围，不扫描所有项目，不重建已删除项目。
skills uninstall 仅移除所选范围内本工具管理的链接和登记，不删除 Spec 源文件、用户自建目录或其他范围的安装；后续更新不恢复主动卸载项。
同名外部目录或链接不得覆盖；明确安装可以接管指向当前 Spec 的旧链接并登记，其他未登记旧链接只做诊断。更新不重新探测新 Agent；卸载从已保存目标选择，不依赖最新适配表。
Codex 与公共入口按目录去重。共享同一物理入口的消费者不能单独停用，卸载必须提示影响范围。
必须先验证 Spec 索引及声明的 Skill 目录，再执行移除判断，不能把损坏/缺失 Spec 当作“所有 Skill 已删除”。

命令变更检查清单

确认变更应落在命令、基类、SDK 还是 Schema；生成命令优先修改生成源，避免生成后丢失手工改动。
补齐成功、非法参数、空结果、错误分类及非交互行为的测试；认证与安装测试使用临时 HOME，不覆盖真实配置。
涉及输出时检查 stdout/stderr 分离；涉及写操作时保持 dry-run、确认和审计行为。
更新使用者可见行为到 .npm-readme.md，更新架构决策到 TECHNICAL-DESIGN.md；README 只保留开发入口和关键约束，不重复完整命令手册。
修改 ai-spec/ 时先阅读 AGENT.md 与 AI Spec 编写规范，更新文件哈希并执行数据层校验。

8. 退出码

| 码 | 含义 | |---:|------| | 0 | 成功 | | 1 | 通用错误 | | 2 | 参数校验失败（ValidationError） | | 3 | 认证/签名失败 | | 4 | 网络错误（NetworkError） | | 5 | 限流 | | 6 | API 业务错误 | | 7 | 部分成功 | | 8 | Spec 不兼容（CompatibilityError） | | 9 | 更新失败（UpdateError） |

8.1 退出码（Exit Codes）

tobid-cli 使用语义化退出码；用户可据此快速定位问题，Agent 也可依据退出码自动决定继续、修正、重试或请求人工介入。

| 退出码 | 语义 | 触发场景（简要） | 建议处理方式 | | ---: | --- | --- | --- | | 0 | 成功 | 命令正常完成 | 继续后续流程 | | 1 | 内部错误 / 解析失败 | SDK 响应解析失败、未分类异常、运行环境不满足或 Skill 安装告警 | 检查环境版本与日志；不要自动重试写入 | | 2 | 参数 / 用法错误 | 请求 JSON 缺少必填字段、值非法，或命令、flag、arg 解析失败 | 补全或修正参数后重试 | | 3 | 凭证 / 签名错误 | Profile 缺少凭证、密钥不匹配，或服务端返回认证失败 | 运行 auth init / auth test；不要自动重试 | | 4 | 网络错误 | DNS 解析失败、连接超时或重试耗尽 | 检查网络后重试 | | 5 | 限流 | HTTP 429 或报表 API 返回限流业务码 | 等待错误信息中的 retryAfterMs 后重试 | | 6 | API 业务错误 | 服务端返回非零业务码、批量操作全部失败或 preflight 不通过 | 检查请求参数与业务逻辑；写入前先回读核实，不要盲目重试 | | 7 | 批量部分失败 | 批量操作中部分项成功、部分项失败 | 解析 rawData 逐项结果，仅重试失败项 | | 8 | 兼容性 / 契约不完整 | CLI 版本低于 Spec 最低要求，或请求契约缺少必要字段 | 升级 CLI 或补充契约字段 | | 9 | 更新失败 | CLI 自身或 Spec 更新过程出错 | 检查网络和 npm 状态后手动重试 | | 10 | 需要确认 | 非交互或 JSON 模式下执行写操作但未提供 --yes | 优先使用 --dry-run；取得用户明确授权后再添加 --yes |

Agent 决策指引

可重试：退出码 4 在网络恢复后重试；退出码 5 必须优先遵守 retryAfterMs，缺失时再采用退避等待。
不可直接重试但可自动修复：退出码 2 可根据参数错误补全输入；退出码 7 必须先解析 rawData，仅补偿失败项，不能重放整个批次。
需用户介入：退出码 3 需要用户配置或验证凭证；退出码 8 需要升级 CLI 或补充契约；退出码 9 需要人工检查更新环境；退出码 10 只有在用户明确授权后才能附加 --yes，预览应使用 --dry-run。
终止并诊断：退出码 1 需要检查环境和日志；退出码 6 需要核实业务条件与写入结果。两者都不应盲目自动重试写入。
成功继续：退出码 0 表示命令完成，可进入下一步。

Bash / zsh 分支示例

sigmob-monetization-cli tobid placement list --data '{"app_id":1875}' --format json
exit_code=$?

case "$exit_code" in
  0) echo "成功，继续后续流程" ;;
  2) echo "修正参数后重试" ;;
  4) echo "网络恢复后重试" ;;
  5) echo "读取错误 JSON 中的 retryAfterMs，等待后重试" ;;
  7) echo "解析 rawData，仅重试失败项" ;;
  10) echo "先请求用户授权；仅预览时改用 --dry-run" ;;
  3|8|9) echo "暂停并请求用户介入" ;;
  1|6) echo "终止自动执行并进行人工诊断" ;;
  *) echo "未知退出码：$exit_code，停止执行" ;;
esac

9. 打包与发布

CLI 通过 npm 发布，AI Spec 通过 OSS 独立发布，版本互不绑定。npm 包的 files 为 bin、dist、oclif.manifest.json；仓库 ai-spec/ 用于开发、codegen 和独立 Spec 发布，不随 npm 包分发。

两份 README 的职责

| 文件 | 读者 | 内容 | | --- | --- | --- | | README.md | CLI 开发/维护人员 | 开发环境、源码结构、实现约束、测试和发布 | | .npm-readme.md | CLI 使用者 | 安装、初始化、凭证、多账号、命令、更新和排障 |

prepack 先备份开发版 README 到 .readme-dev-backup，再用 .npm-readme.md 替换包内 README；postpack 恢复开发版。因此 npm 包页面展示使用指南，不展示仓库开发指南。若打包中断，先检查备份与两份文档，避免提交临时替换后的 README。

发布检查清单

完成上文构建、单元测试、类型检查和 CLI 回归；不要只运行 npm test。
按变更选择一种版本升级级别：npm version patch、npm version minor 或 npm version major。这些命令会创建版本提交和 tag，先确认工作区与发布分支。
执行 npm run build；确认 oclif.manifest.json 正确生成（清单生成失败会直接让构建失败）。
执行 npm pack，检查 tarball 文件清单、包内 README、可执行入口和命令发现；确认不包含 AI Spec、凭证或本地测试证据，并在隔离环境做包级 smoke test。
确认 .npm-readme.md 中安装包名与 package.json.name 一致，开发版 README 已恢复，再按发布流程执行 npm publish。

update self 只检查 npm 最新版本并提示安装命令，不自动安装 CLI；update 检查 CLI 版本并更新 Spec。不要把它们描述为 npm 自更新实现。

0.2.8 报告回归与手写写命令

adsource combo-create 保持手写，禁止 codegen 覆盖。写命令先规范化和校验输入，再确认/审计/执行；子类不得自行输出 JSON。test/regression/write-safety.py 覆盖目标保护、批量输入、combo 单文档输出、HTTP/网络分类、CSV 和配置变更输出，支持 CLI_PACKAGE_ROOT 对 npm 产物复测。详见 2026-09-16 报告核验。

Codegen 模板边界

当前 4 个独立模板覆盖 33 条命令：报表读取 4 条、聚合分页读取 6 条、聚合单对象读取 2 条、JSON 写命令 21 条。入口为 scripts/codegen.ts，模板位于 scripts/codegen/templates/。scripts/codegen/registry.ts 明确记录命令、SDK 方法、基类和风险等级契约；unsupportedCommands 仅保留 sigmob app list 与 tobid adsource combo-create 两条手写命令，禁止生成覆盖，不新增 Sigmob 列表模板。未知配置不使用兜底模板。详细对应关系与验收规则见 Codegen 模板与接口支持清单。

内部测试安装包

API 域名由安装包固定，不支持命令行参数、配置文件或运行时环境变量覆盖。auth status 可查看当前包的固定域名；凭证读写只处理两套凭证，不再保留域名配置字段。

正式包：报表 https://report.sigmob.com，管理 https://mmapi.sigmob.com。
测试包：报表 https://report.sigmob.com，管理为 https://testdash.sigmob.com。

维护者在仓库执行：

npm run pack:test

脚本先构建正式代码，再在临时副本中替换管理域名，生成 tmp/<包名>-<版本>+test.tgz。不修改源码及正式 dist 的域名；测试包设置 private: true 防止误发布，并停止查询公开 npm 的 CLI 更新。将 .tgz 通过公司内部渠道分发，不发布到公开 npm。

测试人员安装（以当前包名和版本为例）：

npm install -g ./muran-cli-0.3.0+test.tgz
sigmob-monetization-cli auth status

为保持简单，测试包沿用正式包名、命令和配置目录，安装时会替换同名的全局正式包；测试时请用独立 Profile（例如 --profile qa）和专用测试账号。报表域名与正式环境共用，报表认证仍需该服务认可的凭证。结束后可安装公开正式包恢复（当前包名为 muran-cli，后续改名后使用新包名）：

npm install -g muran-cli@latest

Agent 测试沿用 sigmob-monetization-cli 命令；请直接使用已安装的测试包，不执行 npx muran-cli 或从公开 npm 重新安装。测试版本使用 +test 构建元数据，不降低 AI Spec 最低版本兼容性。

测试包和 npm run cli 的 auth test 仅检测测试管理服务（包括时钟检测），不请求报表服务，也不校验 ToBid 报表凭证；正式包仍检测报表和管理两项。此规则不改变报表业务命令的域名。

Sigmob 应用原生参数（v4 文档）

创建应用的基础必填字段为 name/platform/isonline/viewmode/app_source。Android/HarmonyOS还需package，未上线iOS需bundleId；已上线应用需商店链接，已上线Android/HarmonyOS还需商店ID和分类；HarmonyOS创建需19字符的ohos_app_id。

sigmob-monetization-cli sigmob app create --data '{"name":"示例应用","platform":2,"isonline":0,"viewmode":1,"app_source":3,"package":"com.example.app"}' --dry-run
sigmob-monetization-cli sigmob app update --data '{"id":123,"name":"新的应用名称","platform":2,"isonline":0,"viewmode":1,"package":"com.example.app"}' --dry-run
sigmob-monetization-cli sigmob app list --data '{"id":123,"check":[2],"page":"1,100"}'

更新使用 id，不是 app_id；旧 app_name/os/bundle/download_url/keyword 不再作为有效原生字段。更新时提供正确platform可校验平台相关必填条件，但审核通过禁止编辑、已上线不能退回未上线仍需核实服务端状态。该文档的form/GET传输与现有SDK有差异，本次只对齐参数契约，不宣称完成传输迁移或线上验证。

渠道参数分层校验（CLI 0.3.1 / Spec 0.5.1）

广告网络账号、媒体应用配置和广告源使用不同层级的渠道规则。详见设计与使用说明，官方来源为聚合管理API第4章。运行时只读本地Spec，不实时抓取文档。schema channel <channel_id> <scope> --format json 可按需查看字段和完整性状态；部分规则会阻止真实写入，请勿把基本校验或dry-run成功视为渠道参数已齐全。

执行与校验（公共框架一期，待发布）

schema api / schema channel / validate 使用本地 Spec，不自动下载、检查更新或读取业务凭证；缺 Spec 时先运行 update spec。
正式写命令内置同源校验和已实现的只读前置检查，不要求先单独执行 validate/dry-run。JSON 或非交互写入需要在取得具体授权后使用 --yes。
--dry-run 校验、读取必要依赖并预览，不调用写接口；--yes 不覆盖它。渠道契约不完整时预览标记 executable:false，真实执行仍阻断。
错误保留 {ok:false,error}：字段错误退出2、凭证3、前置条件6、契约缺口8、缺确认10；日志走stderr。
Skill先读取目标契约并集中收集缺参，普通已授权操作直接执行；删除/批量保留预览确认。预览/取消不是成功，提交后仍按领域流程回读。

验证及未覆盖项见公共框架一期验收。