@captain_z/zsk

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

先用哪个命令

| 目标 | 命令 | 说明 | | --- | --- | --- | | 给当前 AI 工具安装 core skills | npx @captain_z/zsk add | 交互选择 target、bundle、冲突策略 | | 在 CI 或脚本里安装 | npx @captain_z/zsk add zsk-sdlc --target=<dir> --yes | 非 TTY 必须显式给 target 和 yes | | 初始化业务项目知识工作区 | npx @captain_z/zsk init | 创建最小 .zsk/ 工作区，并把 .zsk/ 加入 .gitignore | | 准备或同步项目资源 | npx @captain_z/zsk prepare draft && npx @captain_z/zsk prepare plan && npx @captain_z/zsk prepare sync --all | 先审查资源建议，再选择性同步 raw snapshots 和 readiness matrix | | 检查知识工作区 | npx @captain_z/zsk check | 校验配置、路径泄漏、Playwright 边界、证据位置和 Documentation Feedback | | 只浏览可安装内容 | npx @captain_z/zsk list | 输出 bundle 和 skill 清单 |

安装完成后，真实工作流由 LLM skills 执行：不知道该用哪个 skill 时从 zsk:dispatch 进入，让 OMX 按 ZSK workflow 调度；只需要恢复下一合法阶段时用 zsk:flow；也可以手动指定 zsk:prepare、zsk:spec、zsk:coding 等阶段。

入口

# 装（默认命令）：向导自适应新装 / 刷新 / 追加
npx @captain_z/zsk            # 等同 `zsk add`
npx @captain_z/zsk add
npx @captain_z/zsk install    # add 的别名；更贴近 npm/CI 语义

# 移除
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 issue update -m <module-id> --id BUG-0001-api-gap --status Verified
npx @captain_z/zsk prepare draft
npx @captain_z/zsk prepare plan
npx @captain_z/zsk prepare sync --consumer=review --dry-run
npx @captain_z/zsk prepare sync --all
npx @captain_z/zsk prep    # legacy alias: prepare run
npx @captain_z/zsk check

命令一览

| 命令 | 作用 | 默认 UX | | --- | --- | --- | | add [<pattern>...] | 装 / 刷新 / 追加。target 空 → 新装；有 manifest → 自动进刷新岔路 | 自适应 clack 向导，两级多选 | | install [<pattern>...] | add 的别名；支持同样的 target、bundle、format 和冲突策略 | 非交互 / CI 更直观 | | remove [<pattern>...] | rm | 从有 zsk-manifest.json 的目录移除；手改文件自动备份 | 多选 + 强确认 | | list [--bundle=<n>] [--json] | 浏览 bundle / skill 清单 | 非交互 | | init | 脚手架最小 .zsk/{docs,modules,raws,templates}、.zsk/config.yaml、.zsk/CONTEXT.md、团队与工作策略；issues/evidence/plans/playwright 按需创建 | 非破坏性，默认跳过已存在文件 | | config setup | 指导 AI/人工填写 SRS、PRD、Figma、API、测试用例等资源来源 | 非交互提示 | | config check | 校验 .zsk/config.yaml 与 .zsk/modules/{module}/module.yaml | 非交互 | | module init -m <id> | 从 package 模板生成 .zsk/modules/{module} 主文档 | 非交互 | | issue create -m <id> | 从 package 模板生成 issue 目录、issue.md、assets/index.md、debug-logs/index.md，并刷新模块/全局索引 | 非交互 | | issue update -m <id> --id <issue-dir> --status <s> | 更新具体 issue 状态，并刷新 .zsk/issues/{module}/index.md 与 .zsk/issues/index.md | 非交互 | | prepare inventory / scan | 扫描仓库资源并写入 deterministic inventory artifact | 非交互 | | prepare draft | 生成可审查的 config draft 和 source promotion suggestions，不采集资源 | 非交互 | | prepare plan | 写入 acquisition plan、blocked-source 和 correspondence evidence | 非交互 | | prepare sync [--source\|--resource\|--lane\|--consumer\|--all] | 选择性同步已确认来源到 .zsk/raws/**，并更新 raw manifest / readiness evidence | 非交互 | | prepare auth / auth-check | 生成或检查 Playwright storageState 登录材料，不在输出中泄漏 secret | 非交互 | | prep | legacy alias for prepare run；保留给旧流程 | 非交互 | | check | 校验配置、测试资产映射、路径泄漏、Playwright/auth 边界、docs 证据边界和 Documentation Feedback 记录 | 非交互 | | doctor / lint | 校验（Phase 4 实现） | stub |

项目知识工作区命令

zsk init
zsk config setup
zsk config check
zsk module init -m <module-id>
zsk issue create -m <module-id> --title "<short title>"
zsk prepare draft
zsk prepare plan
zsk prepare sync --consumer=review --dry-run
zsk prepare sync --all
zsk check

职责边界：

• ZSK CLI：初始化模板、JSON Schema 配置提示、确定性路径和结构校验；prepare 只做可审查计划、选择性同步、raw manifest 和 readiness evidence。
• Workflow：决定阶段顺序、strictness、gates、角色/人员投入、签字和多角度 review 是否启用。
• AI skills：只关心本 skill 的职责、非目标、输入/输出、质量评分、证据、风险和 bounded ReAct 修复；缺少 workflow-owned 资料时记录为风险、N/A 或 confidence gap，而不是把 sibling skill 变成硬前置。

推荐顺序：

init -> config setup -> config check -> module init -> prepare draft/plan -> prepare sync -> check
                                      -> issue create / issue update（按需）

生成结构：

.zsk/
├── config.yaml
├── CONTEXT.md
├── team.yaml
├── work.yaml
├── docs/
│   ├── PROJECT-CONFIG.md
│   └── SYSTEM-SPEC.md
├── modules/
├── raws/
├── templates/
├── issues/       # 按需
├── evidence/     # 按需
├── playwright/   # 按需
└── plans/        # 按需

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

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

zsk prepare draft / zsk prepare plan 是只读准备步骤，输出可审查的配置草稿、资源提升建议和采集计划。zsk prepare sync 再按选择器同步资源：--source=<id>、--resource=repo-context|docs|decision-records|issue-tracker|external-docs、--lane=product|backend|design|ux|qa、--consumer=proposal|spec|design|coding|review|prepare 或 --all。未选资源标记为 skipped；失败资源标记 failed 并保留影响和重试命令；已成功 snapshot 不会被单个失败抹掉。zsk prep 仍保留为 legacy alias，等同于一次性 prepare run。

zsk check 会跑确定性检查：配置是否有效、.zsk/raws/prepare/qa/testing 下的测试资产是否映射到模块、截图/debug log/trace 是否误放在 docs 或模块主文档目录、auth state 是否泄漏到 .zsk/playwright/{module}/.auth 之外、ZSK Plan 是否误写到 root plans 或 .omx/plans、Playwright spec 是否包含 TODO / test.skip / test.fixme，以及阶段文档是否有 Documentation Feedback 或明确的 no-update rationale。root .raws/.issues/.playwright 和 root ZSK-managed docs 泄漏始终失败；--strict 只是兼容 flag。

测试用例是一等资产：原始 QA/验收/发布测试用例可以是线上资源或本地文件，也可以快照到 {paths.raws}；模块派生 test plan 和自动化映射放 .zsk/playwright/{module}，模块主文档放 .zsk/modules/{module}。AI coding 必须先从这些测试资产写或更新测试，再实现，并在 review/verify 中检查测试断言是否真的覆盖预期行为，避免 fake green。

每个 skill/stage 完成后必须满足 harness completion contract：模块主文档写入 .zsk/modules/{module}，计划写入 .zsk/plans，actionable issue 写入 .zsk/issues，可复用证据写入 .zsk/evidence，Playwright 资产和运行产物写入 .zsk/playwright/{module}。确认解决后，再把未覆盖或描述不足的行为反哺到 .zsk/docs/SYSTEM-SPEC.md、模块 spec/design/tasks 或记录 no-update rationale。

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:*mok*） | | --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 | 打印计划，不落盘 | | --format <layout> | flat（默认）或 claude-plugin；plugin 模式生成 .claude-plugin/plugin.json、commands/ 和 skills/ |

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 profile 到全局
npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --on-conflict=backup --yes

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

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

# Claude plugin 本地目录（同类结构也可由仓库根 .claude-plugin marketplace 通过 /plugin 安装）
npx @captain_z/zsk install zsk-sdlc --target=./.claude-plugin --format=claude-plugin --yes

# 追加单颗 core skill
npx @captain_z/zsk add zsk:smoke --target=~/.claude/skills

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

# 预览
npx @captain_z/zsk add zsk-frontend --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:smoke' --skill='zsk:defect' --yes

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

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": "zsk-sdlc",
  "skills": [
    {
      "name": "zsk:spec",
      "version": "0.2.0",
      "sha256": "…",
      "relPath": "zsk-spec/SKILL.md",
      "files": [
        { "relPath": "zsk-spec/SKILL.md", "sha256": "…" },
        { "relPath": "zsk-spec/harness/THIS_SKILL.md", "sha256": "…" },
        { "relPath": "zsk-spec/harness/profiles/sdlc.yaml", "sha256": "…" }
      ]
    }
  ]
}

• sha256 → SKILL.md digest，保留 v1 兼容
• files[] → skill 目录内所有受管文件 digest；用于检测 harness/profile/resource 手改
• 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 zsk-sdlc --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。