@captain_z/zsk 1.4.2 → 1.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +2 -1
  2. package/dist/commands/project-init.js +5 -2
  3. package/dist/commands/project-init.js.map +1 -1
  4. package/package.json +2 -2
  5. package/templates/project-init/project-config.md +152 -0
package/README.md CHANGED
@@ -33,7 +33,7 @@ npx @captain_z/zsk check
33
33
  | `add [<pattern>...]` | 装 / 刷新 / 追加。target 空 → 新装；有 manifest → 自动进刷新岔路 | 自适应 clack 向导，两级多选 |
34
34
  | `remove [<pattern>...]` \| `rm` | 从有 `zsk-manifest.json` 的目录移除；手改文件自动备份 | 多选 + 强确认 |
35
35
  | `list [--bundle=<n>] [--json]` | 浏览 bundle / skill 清单 | 非交互 |
36
- | `init` | 脚手架 `.zsk/config.yaml` + `.raws/index.md` + `.raws/manifest.json` + `.raws/` 分类快照目录 + `docs/` + `.issues/` | 非破坏性，默认跳过已存在文件 |
36
+ | `init` | 脚手架 `.zsk/config.yaml` + `project-config.md` + `.raws/index.md` + `.raws/manifest.json` + `.raws/` 分类快照目录 + `docs/` + `.issues/` | 非破坏性，默认跳过已存在文件 |
37
37
  | `config setup` | 指导 AI/人工填写 SRS、PRD、Figma、API、测试用例等资源来源 | 非交互提示 |
38
38
  | `config check` | 校验 `.zsk/config.yaml` 与 `docs/{module}/module.yaml` | 非交互 |
39
39
  | `module init -m <id>` | 从 package 模板生成 `docs/{module}` | 非交互 |
@@ -61,6 +61,7 @@ zsk check
61
61
  ```text
62
62
  .zsk/
63
63
  └── config.yaml
64
+ project-config.md
64
65
  .raws/
65
66
  ├── index.md
66
67
  ├── manifest.json
package/dist/commands/project-init.js CHANGED
@@ -17,11 +17,13 @@ export async function run(opts = {}) {
17
17
  log.info(`目标：${pc.cyan(target)}`);
18
18
  }
19
19
  const existingConfig = await fileExists(join(target, ".zsk", "config.yaml"));
20
+ const existingProjectConfig = await fileExists(join(target, "project-config.md"));
20
21
  const existingRaws = await fileExists(join(target, ".raws"));
21
22
  const existingIssues = await fileExists(join(target, ".issues"));
22
23
  const existingDocs = await fileExists(join(target, "docs"));
23
24
  const summaryPre = [
24
25
  `.zsk/config.yaml: ${existingConfig ? pc.yellow("已存在（跳过）") : pc.green("将创建")}`,
26
+ `project-config.md: ${existingProjectConfig ? pc.yellow("已存在（跳过）") : pc.green("将创建")}`,
25
27
  `.raws/: ${existingRaws ? pc.yellow("已存在（跳过内部文件）") : pc.green("将创建")}`,
26
28
  `.issues/: ${existingIssues ? pc.yellow("已存在（跳过内部文件）") : pc.green("将创建")}`,
27
29
  `docs/: ${existingDocs ? pc.yellow("已存在（跳过内部文件）") : pc.green("将创建")}`,
@@ -56,8 +58,9 @@ export async function run(opts = {}) {
56
58
  "",
57
59
  `${pc.bold("下一步：")}`,
58
60
  `1. 编辑 ${pc.cyan(".zsk/config.yaml")}，把 ${pc.yellow("<project-name>")} 改成项目名`,
59
- `2. 把 SRS / PRD / Figma / Modao / API / 测试用例来源交给 AI，或运行 ${pc.cyan("zsk config setup")} 辅助填写 sources`,
60
- `3. 跑 ${pc.cyan("zsk prep")} 准备上下文；需要模块时运行 ${pc.cyan("zsk module init -m <module-id>")}`,
61
+ `2. 编辑 ${pc.cyan("project-config.md")}，补齐项目技术栈、脚本、资源入口和 AI 查表锚点`,
62
+ `3. 把 SRS / PRD / Figma / Modao / API / 测试用例来源交给 AI，或运行 ${pc.cyan("zsk config setup")} 辅助填写 sources`,
63
+ `4. 跑 ${pc.cyan("zsk prep")} 准备上下文；需要模块时运行 ${pc.cyan("zsk module init -m <module-id>")}`,
61
64
  ].join("\n");
62
65
  if (interactive) {
63
66
  note(summary + nextSteps, "bootstrap 摘要");
package/dist/commands/project-init.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"project-init.js","sourceRoot":"","sources":["../../src/commands/project-init.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wEAAwE;AACxE,8BAA8B;AAC9B,EAAE;AACF,oDAAoD;AAEpD,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,OAA2B,EAAE;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;IAE9B,IAAI,WAAW,EAAE,CAAC;QAChB,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAC7E,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7D,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACjE,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE5D,MAAM,UAAU,GAAG;QACjB,qBAAqB,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QAC9E,oBAAoB,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QAC/E,oBAAoB,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACjF,oBAAoB,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;KAChF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACvB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,KAAK,CAAC,KAAK,CAAC,CAAC;YACb,OAAO;QACT,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAE1B,MAAM,cAAc,GAAG,MAAM,kBAAkB,EAAE,CAAC;IAClD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE;QAC5D,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;QAClC,SAAS,EAAE;YACT,WAAW,EAAE,cAAc;YAC3B,qBAAqB,EAAE,SAAS,CAAC,cAAc,EAAE,wBAAwB,CAAC;YAC1E,qBAAqB,EAAE,SAAS,CAAC,cAAc,EAAE,oBAAoB,CAAC;SACvE;KACF,CAAC,CAAC;IAEH,CAAC,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IAEvB,MAAM,OAAO,GAAG;QACd,QAAQ,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK;QAClC,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,EAAE;KACpE;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,SAAS,GAAG;QAChB,EAAE;QACF,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;QACpB,SAAS,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ;QAC7E,0DAA0D,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,eAAe;QACpG,QAAQ,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,IAAI,CAAC,gCAAgC,CAAC,EAAE;KACzF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC,OAAO,GAAG,SAAS,EAAE,cAAc,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"project-init.js","sourceRoot":"","sources":["../../src/commands/project-init.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@captain_z/zsk",
3
- "version": "1.4.2",
3
+ "version": "1.4.3",
4
4
  "description": "ZNorth Standard Kit — CLI installer for zsk skill bundles (npx @captain_z/zsk add)",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -20,7 +20,7 @@
20
20
  "commander": "^12.1.0",
21
21
  "picocolors": "^1.1.1",
22
22
  "yaml": "^2.7.0",
23
- "@captain_z/zsk-skills": "1.4.2"
23
+ "@captain_z/zsk-skills": "1.4.3"
24
24
  },
25
25
  "devDependencies": {
26
26
  "@types/node": "^22.10.0",
package/templates/project-init/project-config.md ADDED
@@ -0,0 +1,152 @@
1
+ ---
2
+ meta:
3
+ project_name: "<project-name>"
4
+ project_type: "<project-type>"
5
+ project_role: "<project-role>"
6
+ created: "<YYYY-MM-DD>"
7
+ maintainers: []
8
+
9
+ config:
10
+ machine_config: ".zsk/config.yaml"
11
+ system_spec: "docs/SYSTEM-SPEC.md"
12
+
13
+ paths:
14
+ raws_root: ".raws"
15
+ raws_index: ".raws/index.md"
16
+ raws_manifest: ".raws/manifest.json"
17
+ requirements_index: ".raws/requirements/index.md"
18
+ api_contracts_index: ".raws/api-contracts/index.md"
19
+ design_sources_index: ".raws/design-sources/index.md"
20
+ design_assets_index: ".raws/design-assets/index.md"
21
+ testing_index: ".raws/testing/index.md"
22
+ docs_root: "docs"
23
+ module_index: "docs/_module-index.md"
24
+ issues_root: ".issues"
25
+ issues_index: ".issues/README.md"
26
+
27
+ source_registry:
28
+ canonical: ".zsk/config.yaml#sources"
29
+ local_snapshot_root: ".raws"
30
+ generated_manifest: ".raws/manifest.json"
31
+
32
+ modules:
33
+ root: "docs"
34
+ index: "docs/_module-index.md"
35
+ module_config: "docs/{module}/module.yaml"
36
+ module_docs: "docs/{module}/proposal.md | spec.md | design.md | tasks.md | verification.md"
37
+ module_issues: ".issues/{module}"
38
+
39
+ scripts:
40
+ install: "<install command>"
41
+ dev: "<dev command>"
42
+ build: "<build command>"
43
+ lint: "<lint command>"
44
+ type_check: "<typecheck command>"
45
+ test: "<test command>"
46
+ format: "<format command>"
47
+
48
+ stack:
49
+ framework: "<framework>"
50
+ language: "<language>"
51
+ language_strict: true
52
+ build_tool: "<build-tool>"
53
+ css: "<css-stack>"
54
+ ui_lib: "<ui-library>"
55
+ test_framework: "<test-framework>"
56
+
57
+ quality:
58
+ documentation_feedback_required: true
59
+ runtime_evidence_root: ".issues"
60
+ raw_snapshot_root: ".raws"
61
+ docs_runtime_artifacts_forbidden: true
62
+
63
+ examples:
64
+ module_id: "sample-module"
65
+ issue_id: "BUG-0001"
66
+ ---
67
+
68
+ # Project Config — <project-name>
69
+
70
+ > **定位**：项目级 AI 配置与机械查表锚点。
71
+ > **维护方式**：与 [docs/SYSTEM-SPEC.md](./docs/SYSTEM-SPEC.md) 和 [.zsk/config.yaml](./.zsk/config.yaml) 同步维护。
72
+ > **适用范围**：`.zsk/`、`.raws/`、`docs/`、`.issues/` 和项目代码。
73
+ > **当前结论**：本文件面向人和 AI；机器校验以 `.zsk/config.yaml` 为准。
74
+
75
+ ---
76
+
77
+ ## 1. 配置入口
78
+
79
+ | 文件 | 定位 | 维护方式 |
80
+ |---|---|---|
81
+ | `.zsk/config.yaml` | 机器可读配置：路径、sources、tools、module root | 由 AI/人工编辑，`zsk config check` 校验 |
82
+ | `project-config.md` | 人读项目配置：技术栈、脚本、路径、约束查表 | 与系统规约同步维护 |
83
+ | `docs/SYSTEM-SPEC.md` | 项目级规则、事实源优先级、质量门禁 | 稳定约束变更时更新 |
84
+
85
+ ## 2. 资源入口
86
+
87
+ | 资源 | 统一入口 | 机器索引 / 配置 | 说明 |
88
+ |---|---|---|---|
89
+ | Raw facts | `.raws/index.md` | `.raws/manifest.json` | 上游事实与本地快照导航 |
90
+ | Requirements | `.raws/requirements/index.md` | `.zsk/config.yaml#sources` | SRS、PRD、验收说明 |
91
+ | API contracts | `.raws/api-contracts/index.md` | `.zsk/config.yaml#sources` | OpenAPI、后端仓库、接口契约 |
92
+ | Design sources | `.raws/design-sources/index.md` | `.zsk/config.yaml#sources` | Figma、Modao、MCP、设计交付源 |
93
+ | Design assets | `.raws/design-assets/index.md` | `.zsk/config.yaml#sources` | token、图片、图标、截图、静态设计资产 |
94
+ | Testing assets | `.raws/testing/index.md` | `.zsk/config.yaml#sources` + `docs/{module}/module.yaml` | QA、验收、发布测试用例 |
95
+ | Issues / evidence | `.issues/README.md` | `.zsk/config.yaml#paths.issues` | bug、截图、日志、复测证据 |
96
+
97
+ ## 3. `.raws` / `docs` / `.issues` 边界
98
+
99
+ | 目录 | 存放内容 | 不应存放 |
100
+ |---|---|---|
101
+ | `.raws/` | 上游事实、外部资源快照、原始测试资产 | 本地运行截图、debug log、失败验证证据 |
102
+ | `docs/` | 模块 proposal/spec/design/tasks/verification、系统规约 | 运行时证据、HAR、控制台日志 |
103
+ | `.issues/` | 本地缺陷、验证证据、截图、debug log、复测记录 | 上游 SRS/API/Figma 原文快照 |
104
+
105
+ ## 4. Module 文档如何引用资源
106
+
107
+ 模块文档优先通过相对路径引用资源：
108
+
109
+ ```md
110
+ > 原始需求：`.raws/requirements/{file}`
111
+ > API 契约：`.raws/api-contracts/{service}/contracts/{contract}.md`
112
+ > 设计来源：`.raws/design-sources/{module}/`
113
+ > 设计资产：`.raws/design-assets/{module}/`
114
+ > 测试资产：`.raws/testing/{case-file}`
115
+ > 本地问题：`.issues/{module}/BUG-0001-short-slug/issue.md`
116
+ ```
117
+
118
+ 模块级映射写入 `docs/{module}/module.yaml`，项目级来源写入 `.zsk/config.yaml#sources`。
119
+
120
+ ## 5. Coding 约束查表
121
+
122
+ | 维度 | 当前项目值 | 说明 |
123
+ |---|---|---|
124
+ | Framework | `<framework>` | 从项目实际依赖填写 |
125
+ | Language | `<language>` | TypeScript / Java / Go / etc. |
126
+ | Build | `<build command>` | 与 package manager 保持一致 |
127
+ | Test | `<test command>` | CI 和本地验收都应可复用 |
128
+ | UI / Runtime verification | `computer_use / browser_use` | 具体工具以 `.zsk/config.yaml#tools` 为准 |
129
+
130
+ ## 6. 冲突处理顺序
131
+
132
+ 1. 用户明确指令 / 仓库 `AGENTS.md`
133
+ 2. `docs/SYSTEM-SPEC.md`
134
+ 3. `project-config.md`
135
+ 4. `.zsk/config.yaml`
136
+ 5. `.raws/` 中的上游事实源
137
+ 6. `docs/{module}/proposal.md|spec.md|design.md|tasks.md`
138
+ 7. 通用 skills / 模板
139
+
140
+ 如果两个上游事实源冲突，不要静默选择。应在 `.issues/{module}/` 记录冲突，并在模块 `spec.md` 或 `design.md` 的 Documentation Feedback 中写明处理结果。
141
+
142
+ ## 7. 维护清单
143
+
144
+ 项目硬约束新增或调整时，至少同步检查：
145
+
146
+ - [ ] `.zsk/config.yaml`
147
+ - [ ] `project-config.md`
148
+ - [ ] `docs/SYSTEM-SPEC.md`
149
+ - [ ] `.raws/index.md` 与相关分类 `index.md`
150
+ - [ ] 受影响模块的 `docs/{module}/module.yaml`
151
+ - [ ] 受影响模块的 `docs/{module}/spec.md` / `design.md`
152
+ - [ ] 必要时新增或更新 `.issues/{module}/BUG-xxxx/issue.md`