skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
zeyiji.com172 installs

zeyiji-shared

zeyiji-cli 共享规则:CLI 安装、认证、输出契约、退出码与安全规则。所有 zeyiji-* 技能的前置依赖。

How do I install this agent skill?

npx skills add https://zeyiji.com --skill zeyiji-shared
view source ↗

Is this agent skill safe to install?

No partner audit is available yet. Read the source before installing.

What does this agent skill do?

zeyiji-cli 共享规则

所有 zeyiji-* 技能共享的底座:安装、认证、输出契约、退出码、通用规则。这些内容只写一次,域技能不再重复。

CRITICAL — 向用户交付任何业务数据前 MUST 遵循 references/presentation-contract.md。CLI 的 JSON/表格是 Agent 的执行输入,不是用户答复模板。

Bootstrap

任务开始前执行一次,自动完成,无需用户手动操作:

zeyiji-cli version      # 不存在 → npx @zeyiji/cli@latest install(需要 Node.js >= 16)
zeyiji-cli auth status  # 未登录/已过期 → 走下面「认证」

两者都正常就直接执行用户任务,不要重复登录。

认证

  1. 未登录时,在后台任务 / 长超时调用中运行 zeyiji-cli auth login:它会输出授权链接并阻塞等待,用户点一次「授权」即完成,token 自动保存到配置文件,后续命令与新终端直接可用。
  2. 只需告诉用户「请打开授权链接完成授权」;不要让用户复制 token,也不要让用户自己敲命令。
  3. 浏览器打不开(远程 / 无桌面 / 代理拦截 127.0.0.1):从输出里取出授权链接发给用户,让用户在自己的浏览器中打开完成授权。不要反复执行 login,那不是登录失败的重试信号。
  4. 除登录命令自身的输出外,不要把 token 回显到回复或日志。

输出契约

  • stdout 只放数据(JSON);进度、警告、提示都走 stderr。
  • 默认 -o json;需要稳定解析时用 --jq 在进程内过滤,不要用 findstr/grep 管道(Windows 中文会乱码)。
  • 只读查询且结果直接给用户看时优先用 -o table;需要继续取 ID/做后续命令时才解析 JSON。无论哪种输出,最终答复都必须经过业务语义映射。
  • 判断成功用退出码 0;失败读 stderr 的 error.type / error.subtype / error.hint 决策下一步。
  • 命令输出可能带 _notice(二进制或 skills 落后):立即执行 zeyiji-cli update,更新完成后才交付结果;不要询问用户,也不要向用户报告 notice 内容(更新本身失败除外)。需要稳定 JSON 给脚本读时可用 ZEYIJI_CLI_NO_UPDATE_NOTIFIER=1 ZEYIJI_CLI_NO_SKILLS_NOTIFIER=1 抑制。

退出码与恢复动作

exittype含义Agent 动作
0—成功交付结果
1api / unknown后端/未分类错误按 hint 处理,不盲目重试
2validation参数非法或前置条件不满足(含对象不存在)按 hint 改参数或先满足前置
3authenticationtoken 缺失/无效重新 auth login
4authorization角色权限不足不要重试或换参数硬试,提示用户改用对应管理员角色
5internalCLI 内部错误附 hint 简要告知用户
6config配置缺失/非法按 hint 修正配置
10confirmation高风险确认门禁见下节协议

高风险操作协议(exit 10)

risk: high-risk-write 的命令不带 --yes 时会以退出码 10 退出,stderr 返回结构化 JSON(error.type=confirmation、error.subtype=confirmation_required,含 action / risk / hint)。

  1. 识别:exit 10 + confirmation_required 不是普通错误,不要放弃。
  2. 问用户:展示 action、risk 和关键参数,明确告知「高风险不可逆」,等用户显式同意。
  3. 重试:用户同意后,把 --yes 追加到原始命令末尾重试。
  4. 拒绝:终止流程,不要改写参数绕过门禁。
  5. 禁止:看到 exit 10 就静默加 --yes 重试;把 confirmation 当网络错误或权限错误处理。
  6. 想先让用户 review 危险请求:加 --dry-run,它不触发门禁,会打印完整请求。

zeyiji-cli <command> --help 末尾的 Risk: 行标注风险等级:read / write / high-risk-write。

全局选项

选项说明
-o, --output json|table|raw输出格式(默认 json)
--jq <expr>进程内过滤 JSON 输出
--dry-run只打印请求内容,不执行
-v, --verbose请求/响应详情输出到 stderr

通用规则

  • 写操作前确认用户意图;能用 --dry-run 的先预览。
  • ID 必须查询获得:分类、职业、等级等 ID 不能编造,用 zeyiji-cli api GET <path> --jq ... 查询后使用。
  • 对外只用业务名称:禁止在最终答复中出现后端字段名、JSON 路径、数字枚举、null/空串判断或内部开关值。枚举按前端文案翻译,对象用名称而非 ID;只有用户需要定位/确认操作时才附带「直播 ID」「课程 ID」等业务标识。
  • 完整不等于全量罗列:标题、公告、警告原因等用户内容必须原样保留,不截断、不改写;但只汇报与问题相关的信息,不倾倒全部字段、空值和权限提示。
  • 敏感信息默认静默:推流码、token、手机号等字段除非用户明确要求且当前角色有权查看,否则不展示,也不要主动说明“已隐藏/未返回/为空”。
  • 文件字段传本地路径:--cover-image、--video、--introduce-url、章节 JSON 里的 videoUrl 等传本地文件路径,CLI 自动上传并回填 URL(大小限制见命令 --help 或对应 reference)。jpg/jpeg/png 会自动走后端压缩上传:file upload 按公有/私有选项选择接口,课程封面/节封面/课程内直播封面走公有压缩,图片课件走私有压缩;其余文件、富文本图片和独立直播封面保持原有上传链路。
  • 不得擅自修改用户上传的图片:所有上传图片(封面、图文配图、课件图片等)一律按用户原图上传。未经用户明确要求,禁止裁剪、缩放、改宽高比、转格式、压缩、加水印或替换内容。用户图片比例各不相同,普通比例差异直接使用,不要提示;只有比例严重不合理(如极端长宽比、明显会破坏版式)时才说明问题并询问是否调整。不得先改后报。CLI 对 jpg/jpeg/png 的自动压缩上传是既定链路,Agent 不得另行预处理;文件超出硬限制时先报错原因并询问用户,用户同意后才能压缩。
  • 富文本字段(课程图文介绍、直播简介等):MUST 先读 references/richtext-html-template.md;内容必须是 wangEditor v5 兼容 HTML,禁止 Markdown。
  • 价格单位:用户说的金额是「元」,CLI 参数单位是「分」,传参时 ×100(返佣固定金额同理)。
  • 角色准入:后台管理类命令(如 live *)仅管理员可用。执行前 zeyiji-cli auth status 确认角色;exit 4 不重试,具体矩阵见各领域 SKILL.md。

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/zeyiji.com/zeyiji-shared">View zeyiji-shared on skillZs</a>