@captain_z/zsk

ZNorth Standard Kit CLI — npx zsk 一个命令装 / 刷新 / 移除一套 skill。

入口

# 装（默认命令）：向导自适应新装 / 刷新 / 追加
npx @captain_z/zsk            # 等同 `zsk add`
npx @captain_z/zsk add

# 移除
npx @captain_z/zsk remove

# 浏览
npx @captain_z/zsk list
npx @captain_z/zsk list --json

# 项目知识工作区（非破坏性）
npx @captain_z/zsk init
npx @captain_z/zsk config setup
npx @captain_z/zsk config check
npx @captain_z/zsk module init -m <module-id>
npx @captain_z/zsk issue create -m <module-id>
npx @captain_z/zsk prep
npx @captain_z/zsk check

命令一览

| 命令 | 作用 | 默认 UX | | --- | --- | --- | | add [<pattern>...] | 装 / 刷新 / 追加。target 空 → 新装；有 manifest → 自动进刷新岔路 | 自适应 clack 向导，两级多选 | | remove [<pattern>...] | rm | 从有 zsk-manifest.json 的目录移除；手改文件自动备份 | 多选 + 强确认 | | list [--bundle=<n>] [--json] | 浏览 bundle / skill 清单 | 非交互 | | init | 脚手架 .zsk/config.yaml + project-config.md + .raws/index.md + .raws/manifest.json + .raws/ 分类快照目录 + docs/ + .issues/ | 非破坏性，默认跳过已存在文件 | | config setup | 指导 AI/人工填写 SRS、PRD、Figma、API、测试用例等资源来源 | 非交互提示 | | config check | 校验 .zsk/config.yaml 与 docs/{module}/module.yaml | 非交互 | | module init -m <id> | 从 package 模板生成 docs/{module} | 非交互 | | issue create -m <id> | 从 package 模板生成 issue 目录、issue.md、assets/index.md、debug-logs/index.md | 非交互 | | prep | 根据配置记录 .raws/manifest.json，为 AI skills 准备上下文 | 非交互 | | check | 校验配置、测试资产映射、docs 证据边界、Documentation Feedback 记录 | 非交互 | | doctor / lint | 校验（Phase 4 实现） | stub |

项目知识工作区命令

zsk init
zsk config check
zsk prep
zsk check

职责边界：

• ZSK CLI：初始化模板、JSON Schema 配置提示、确定性路径和结构校验。
• AI skills：资源理解、模块识别、Figma/MCP 获取、Computer Use / Browser Use 验证、冲突分析、issue 编写。

生成结构：

.zsk/
└── config.yaml
project-config.md
.raws/
├── index.md
├── manifest.json
├── requirements/index.md
├── api-contracts/index.md
├── design-sources/index.md
├── design-assets/index.md
└── testing/index.md
docs/
├── SYSTEM-SPEC.md
└── _module-index.md
.issues/
└── README.md

Schemas 随 npm package 发布。zsk init / zsk module init 会用当前运行的 CLI 版本写入 versioned unpkg URL 作为编辑器补全提示；项目本地 .zsk/schemas 不参与校验。

zsk config check 做 schema 和路径边界校验：raw snapshot、模块文档、issue 和运行证据都必须落在 .zsk/config.yaml 配置的路径内。

zsk prep 读取 .zsk/config.yaml，刷新 {paths.raws}/manifest.json，记录资源来源、快照存在性、大小和 hash。.raws/index.md 是人和 AI 的统一入口，.raws 下的分类目录只是本地快照落点，线上/本地资源来源由 AI 或 zsk config setup 填入，CLI 不在这里内置 AI runtime。

zsk check 会跑确定性检查：配置是否有效、模块资源是否存在、配置 raw root 下的测试资产是否映射到模块、派生测试文档是否能追溯到事实源、截图和 debug log 是否误放在 docs root，以及阶段文档是否有 Documentation Feedback 或明确的 no-update rationale。

测试用例是一等资产：原始 QA/验收/发布测试用例可以是线上资源或本地文件，也可以快照到 {paths.raws}；模块派生场景和自动化映射放 docs/{module}/ 的 module.yaml 和测试说明。AI coding 必须先从这些测试资产写或更新测试，再实现。

每个阶段必须做 Documentation Feedback：把对话中确认的决策、约束、例外和验证结果反哺到 docs/SYSTEM-SPEC.md、模块 docs 或配置的 issue 根，否则阶段不算完成。

zsk add 向导分支

target-first → 预检 manifest
├─ 有 manifest → 刷新 / 追加 / 退出
│              ↳ 刷新：全部官方变更（跳过手改） / 含手改强刷（备份）
└─ 空 target → skill 包多选 → skill 多选
               ↳ 可同时勾选多个预设包；也可叠加自选 skill

完整 UX 见 ARCHITECTURE.md §6.4。

flag 参考

公共（add / remove）

| Flag | 作用 | | --- | --- | | --target <path> | 目标目录（支持 ~ / 绝对 / 相对）；非 TTY 必填 | | --skill <pattern> | skill 过滤器，可重复；'*' = 全部，支持 glob（zsk:a11y-*） | | --command <pattern> / --agent <pattern> / --hook <pattern> / --mcp-server <pattern> / --prompt <pattern> | 其他能力类型（语法就位，MVP 空集） | | --yes | 跳过所有 confirm；非 TTY 必填 |

add 独有

| Flag | 作用 | | --- | --- | | [<pattern>...] 位置参 | bundle 名（跳套件选择）/ zsk:<slug> / glob（跳两屏） | | --on-conflict <mode> | skip / overwrite / backup（默认 backup） | | --dry-run | 打印计划，不落盘 |

flag 预填对应步骤

| Flag 给了 | 跳过哪一步 | | --- | --- | | --target | "选择安装位置（可多选）" | | <pattern> = bundle 名 | 跳过 skill 包选择；直接按 bundle 预选 skill | | <pattern> = zsk:... / glob | 两屏都跳过，pattern 匹配即装 | | --skill='*' | 整个"装什么"两屏跳过（= 该类型全装） | | --on-conflict | "冲突策略" | | --yes | 所有 confirm；岔路 A 默认选"刷新" | | --dry-run | 执行步骤换成 diff 预览 |

典型场景

# 新装推荐套件（完全交互）
npx @captain_z/zsk add

# CI：新装 sdlc-only 到全局
npx @captain_z/zsk add sdlc-only --target=~/.claude/skills --on-conflict=backup --yes

# CI：全量刷新
npx @captain_z/zsk add --skill='*' --target=~/.claude/skills --on-conflict=backup --yes

# 追加单颗
npx @captain_z/zsk add zsk:a11y-web --target=~/.claude/skills

# glob 装一组
npx @captain_z/zsk add 'zsk:a11y-*' --target=~/.claude/skills

# 预览
npx @captain_z/zsk add frontend-project --target=~/.claude/skills --dry-run

# 刷新（已装目录，--yes 默认走 refresh）
npx @captain_z/zsk add --target=~/.claude/skills --yes

# 移除两颗
npx @captain_z/zsk remove --target=~/.claude/skills --skill='zsk:i18n' --skill='zsk:typescript' --yes

# 按 glob 移除
npx @captain_z/zsk remove --target=~/.claude/skills 'zsk:react-*'

zsk-manifest.json 契约

装机目录会生成一份 manifest，驱动后续 add/remove/doctor：

{
  "$schema": "https://zsk.codeshareman.dev/manifest.v1.json",
  "version": 1,
  "zskVersion": "0.2.0",
  "installedAt": "2026-04-19T15:30:12Z",
  "bundle": "frontend-project",
  "skills": [
    { "name": "zsk:spec", "version": "0.2.0", "sha256": "…", "relPath": "zsk-spec/SKILL.md" }
  ]
}

• sha256 → 用户手改检测（刷新/移除前提示 + 备份）
• bundle → 下次刷新默认按同 bundle 重算
• schema v1 向后兼容

非 TTY / CI 规则

| 环境 | 要求 | | --- | --- | | 非 TTY · 新装 | --yes + --target + （pattern 位置参 或 --skill=<p>） | | 非 TTY · 刷新（target 有 manifest） | --yes + --target 即可，自动识别 | | 非 TTY · 移除 | --yes + --target + pattern / --skill=<p> | | TTY + 完整 flags | 跳过所有 clack | | TTY + 部分 flags | 已给的预填跳步，未给的进 clack |

开发

pnpm -F @captain_z/zsk dev --help
pnpm -F @captain_z/zsk dev add sdlc-only --target=/tmp/t --on-conflict=backup --yes --dry-run
pnpm -F @captain_z/zsk typecheck
pnpm -F @captain_z/zsk build       # 编译到 dist/

设计文档：ARCHITECTURE.md §6。