@wkgeo/cli 2.0.1 → 2.0.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.
- package/README.md +21 -0
- package/SKILL.md +23 -0
- package/lib/api.mjs +4 -1
- package/lib/commands/index.mjs +18 -0
- package/lib/commands/init.mjs +111 -0
- package/lib/commands/orders.mjs +245 -24
- package/lib/commands/spec.mjs +72 -0
- package/lib/manifest-apply.mjs +52 -2
- package/lib/site-spec.mjs +302 -0
- package/lib/template-gen.mjs +109 -2
- package/package.json +2 -1
- package/spec/SITE-SPEC.md +198 -0
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# 云站建站规范(SITE-SPEC)
|
|
2
|
+
|
|
3
|
+
> **这是唯一主源。** 下面三处都从这份文件生成 / 摘取,不另写一份:
|
|
4
|
+
>
|
|
5
|
+
> | 出口 | 谁读 | 怎么拿 |
|
|
6
|
+
> |---|---|---|
|
|
7
|
+
> | `AGENTS.md` / `CLAUDE.md` / `.cursorrules` / `.github/copilot-instructions.md` | 本地 coding agent(DSH / Codex / Claude Code / Cursor / Copilot)**启动时自动读** | `wkgeo init --confirm` 把「给 AI 的精简版」那一节写进项目(带标记、可重复跑) |
|
|
8
|
+
> | `wkgeo spec` | 本地 CLI 里的 agent / 人 | `wkgeo spec` 打印全文;`wkgeo spec --agents` 只打印精简版 |
|
|
9
|
+
> | `wkgeo-site-spec` skill | 支持 skill 的环境(DSH 本机、**云端沙箱**) | skill 文件由 `node cli/scripts/gen-site-spec.mjs` 从本文件生成 |
|
|
10
|
+
>
|
|
11
|
+
> 改规则**只改本文件**,再跑生成器;`node cli/scripts/gen-site-spec.mjs --check` 在三处不同步时 exit 1。
|
|
12
|
+
>
|
|
13
|
+
> 图例:**✅ 已实现**(命令/服务端真有这条行为,给了代码出处)| **🚧 实现中**(规则已定,代码在别的单里,写明单名)——
|
|
14
|
+
> 实现中的条目**不要当既有行为依赖**。
|
|
15
|
+
|
|
16
|
+
<!-- wkgeo:site-spec:agents:begin -->
|
|
17
|
+
## 建站规范(wkgeo 云站 · 精简版)
|
|
18
|
+
|
|
19
|
+
用 `wkgeo` 建站 / 改栏目 / 做模板时按这 8 条做。完整版 + 代码出处:`wkgeo spec`。
|
|
20
|
+
|
|
21
|
+
1. **栏目类型只有三种**:`channel`(频道页)/ `list`(列表页)/ `page`(单页)。`content apply` 清单里写 `type`:单页 `single`(落库 = `page`)、列表 `list`、频道 `channel`;子栏目继承父类型;首页(`slug=home`)固定 `channel`。
|
|
22
|
+
2. **每个栏目一份独立模板文件**:`pages/c-<slug>.html`(同名撞了自动 `-2` / `-3`)。内容可以从默认档复制(与 `pages/index.html` / `pages/page.html` 逐字节相同),但**文件必须独立** —— 改一个栏目只改它自己那份。默认档只作兜底,不是默认做法。*(生成侧实现中)*
|
|
23
|
+
3. **绑定字段是 `cms_category.template_path`**:`wkgeo categories bind-template <栏目> pages/c-<slug>.html`(清单里写 `categories[].templateFile`)。
|
|
24
|
+
4. **`target_type` 必须与栏目 kind 兼容**:`page`→`single_page|article`;`list`→`list|list+category`;`channel`→`channel|list|list+category`。不兼容就别提交 `template_path`(留空走兜底),否则渲染出半张页。
|
|
25
|
+
5. **兜底(保险,不是默认做法)**:栏目没绑模板时按 kind 自动挑 —— `list`/`channel` → `pages/index.html`,`page` → `pages/page.html`,内容页 → `pages/content.html`。
|
|
26
|
+
6. **首页版块已有同名栏目 ⇒ 只做跳转**:`wkgeo categories save <版块> --link-category <目标栏目ID>`,不要再建一个自己维护内容的同名版块。*(自动识别/自动设置实现中)*
|
|
27
|
+
7. **图标**:必须写 iconify 名(如 `mdi:home-outline`),同一个站内**不能全一样**;不选时由系统分配不重复的默认图标。*(自动分配实现中)*
|
|
28
|
+
8. **改完必须验收**:`wkgeo content check --site <站点ID>`(契约 ↔ 库 ↔ 前台)exit 0;`wkgeo preview` 逐屏看过再 `publish`。
|
|
29
|
+
|
|
30
|
+
> 实现中的几条(第 2、6、7 条的自动部分)见 `wkgeo spec` 末尾「规则状态」,别当既有行为依赖。
|
|
31
|
+
<!-- wkgeo:site-spec:agents:end -->
|
|
32
|
+
|
|
33
|
+
## 0. 先认命令:规范怎么拿、怎么落到项目里
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
wkgeo spec # 打印本规范全文(纯文本 markdown,重定向即可存文件)
|
|
37
|
+
wkgeo spec --agents # 只打印「给 AI 的精简版」那一节(= wkgeo init 写进约定文件的内容)
|
|
38
|
+
wkgeo spec --json # 标准信封:{ok,command:"spec",data:{path,bytes,lines,markdown}}
|
|
39
|
+
wkgeo init --confirm # 把精简版写进项目的四个约定文件(默认 dry-run,只打计划)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`wkgeo spec` 与 `wkgeo skill` 一样:**默认输出纯 markdown,即使输出到管道也不套 JSON**(否则重定向得到一坨转义 JSON);只有显式 `--json` 才是信封。不需要登录、不发网络请求。
|
|
43
|
+
|
|
44
|
+
`wkgeo init` 写四个文件(默认全写):`AGENTS.md`(DSH / Codex / 通用)、`CLAUDE.md`(Claude Code)、`.cursorrules`(Cursor)、`.github/copilot-instructions.md`(GitHub Copilot)。
|
|
45
|
+
|
|
46
|
+
- 写入内容用 `<!-- wkgeo:site-spec:begin -->` … `<!-- wkgeo:site-spec:end -->` 包起来;
|
|
47
|
+
- 文件不存在 ⇒ 新建;**已有内容 ⇒ 只在文件末尾追加我们自己这一段**(用户自己写的部分一字不动);
|
|
48
|
+
- 已有我们这一段 ⇒ **原地替换**(改规范后重跑不会重复追加);内容没变 ⇒ 记 `unchanged`,不写盘;
|
|
49
|
+
- `--agents none` 一个都不写;`--agents=AGENTS.md,CLAUDE.md` 只写点名的(也认 `cursor` / `copilot` 简写)。
|
|
50
|
+
|
|
51
|
+
> ⚠️ CLI **不猜**是谁在调它。`wkgeo init` 把四份都写掉,是因为「注入」这件事不是 CLI 干的:agent 启动时自己读约定文件,CLI 只能把文件放到它该在的位置。
|
|
52
|
+
|
|
53
|
+
## 1. 栏目(Category)
|
|
54
|
+
|
|
55
|
+
- **类型只有三种**:`channel` 频道页 / `list` 列表页 / `page` 单页。服务端判据 `COLUMN_KINDS`(`aliyun/fc/_shared/template-binding-contract.js:52`),CLI 参数 `--kind channel|list|page`(`cli/lib/commands/cms.mjs:440`)。**没有第四种**。
|
|
56
|
+
- **两套词表别混**(同一个东西的三个名字):
|
|
57
|
+
|
|
58
|
+
| 场景 | 怎么写 | 出处 |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| 服务端 `kind` / CLI `--kind` | `channel` / `list` / `page` | `template-binding-contract.js:52` |
|
|
61
|
+
| `content apply` 清单 `categories[].type` | `channel` / `list` / **`single`**(= `page`) | `cli/lib/manifest-schema.json:168-175` |
|
|
62
|
+
| 模板页 `target_type` | `channel` / `list` / `list+category` / `single_page` / `article` | `template-binding-contract.js:62` |
|
|
63
|
+
|
|
64
|
+
`type: "single"` 落库成 `kind: "page"`,映射由 `aliyun/fc/wkgeo-site-builder/fn/src/site-mapping-contract.mjs:149-151` **一处**决定,别在别处再写一套。
|
|
65
|
+
- **子栏目继承父类型**;**首页锁定频道**:`slug=home` 的 `kind` 由服务端固定为 `channel`(`wkgeo categories create` 的 notes 里有写)。
|
|
66
|
+
- **单页栏目自带一条只能编辑、不能新建/删除的内容**;要再加一页 = 给它加子栏目(`cli/lib/commands/cms.mjs:482`)。
|
|
67
|
+
- 一个栏目**是否进前台导航**由 `in_menu` 决定:首页版块 / 隐藏栏目一律 `in_menu=false`(`wkgeo categories update <栏目> --no-in-menu`)。
|
|
68
|
+
|
|
69
|
+
## 2. 模板(Template)
|
|
70
|
+
|
|
71
|
+
### 2.1 每个栏目一个独立 html(规范做法)
|
|
72
|
+
|
|
73
|
+
- 路径规则:**`pages/c-<slug>.html`**。`<slug>` = 栏目 slug 小写、非字母数字换成 `-`、折叠连续 `-`、去掉首尾 `-`;空 slug 用 `cat-<4位hash>`;撞名自动加 `-2` / `-3`(实现:`perCategoryPagePath()` / `planPerCategoryPages()`,`aliyun/fc/_shared/template-binding-contract.js:698-814`)。
|
|
74
|
+
- **内容可以从默认档复制**(`pages/index.html` / `pages/page.html`),复制出来的文件与默认档**逐字节相同**也完全可以;**但文件必须独立**。
|
|
75
|
+
- 为什么:老板 2026-11-21 ——「哪怕一样的,也复制一个模板绑定当前的栏目,这样就方便后期修改」。**改一个栏目 = 只改它自己那个文件**,不牵连别的栏目。
|
|
76
|
+
- 模板里**已经有** `pages/c-<slug>.html` ⇒ 不动它(`action:'keep'`,保留客户改过的版本);没有 ⇒ 从该栏目当前用的页面复制一份(`action:'copy'`)。
|
|
77
|
+
- 这条规则的**生成侧**(`wkgeo template init` 脚手架、建站时默认模板播种)**🚧 实现中**,见 §7 状态表。绑定侧的字段与命令**已实现**(见 2.2)。
|
|
78
|
+
|
|
79
|
+
### 2.2 绑定:`cms_category.template_path`
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
wkgeo categories bind-template <栏目ID|slug|path> pages/c-about.html # 绑
|
|
83
|
+
wkgeo categories bind-template <栏目> --clear # 解绑 → 回自动档
|
|
84
|
+
wkgeo categories save <栏目> --template-path pages/c-about.html # 等价写法
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- 落库字段就是 `cms_category.template_path`(`cli/lib/commands/cms.mjs:433`、`:462`)。
|
|
88
|
+
- `content apply` 清单里写 `categories[].templateFile`(如 `pages/c-about.html`);apply **先按契约试算一遍**,不合法就**不提交 `template_path`**(回落自动档)并回一条 `⚠`(`cli/lib/manifest-apply.mjs:410-417`、`:615`、`:776`)。
|
|
89
|
+
- 绑的文件必须是**本站模板里真实存在的 .html**,否则后端 400(`template_path` 校验)。
|
|
90
|
+
|
|
91
|
+
### 2.3 `target_type` 对照表(唯一判据)
|
|
92
|
+
|
|
93
|
+
`target_type` 是**模板页**声明的"这一页是什么形态",必须与**栏目 kind** 兼容:
|
|
94
|
+
|
|
95
|
+
| 栏目 kind | 允许绑的 `target_type` | 常见页 |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `page` 单页 | `single_page`、`article` | 关于我们 / 联系我们 / 服务条款 |
|
|
98
|
+
| `list` 列表 | `list`、`list+category` | 新闻列表 / 产品列表 |
|
|
99
|
+
| `channel` 频道 | `channel`、`list`、`list+category` | 首页 / 产品中心总览 |
|
|
100
|
+
|
|
101
|
+
- 判据唯一实现:`KIND_TARGETS`(`aliyun/fc/_shared/template-binding-contract.js:73-77`)。**反过来一律拒**:列表版式绑到单页栏目是最常见的错绑(渲染出空列表 + 半张页)。
|
|
102
|
+
- 模板页**没声明** `target_type` 时不拦,按文件名推断:`index`→`list`、`content`/`article`→`article`、`about`/`contact`/`page`/`single`…→`single_page`(`:149-152`、`:237`)。
|
|
103
|
+
- `single_page` / `article` 默认要求栏目有 `richtext` 字段(`DEFAULT_REQUIRED_FIELDS`,`:85-91`);缺字段也会被判不通过。
|
|
104
|
+
|
|
105
|
+
### 2.4 兜底:栏目没绑时按 kind 自动挑(保险,不是默认做法)
|
|
106
|
+
|
|
107
|
+
| 栏目 kind | 自动档页面 |
|
|
108
|
+
|---|---|
|
|
109
|
+
| `list` | `pages/index.html` |
|
|
110
|
+
| `channel` | `pages/index.html` |
|
|
111
|
+
| `page` | `pages/page.html` |
|
|
112
|
+
| 内容页(content) | `pages/content.html` |
|
|
113
|
+
|
|
114
|
+
出处:`AUTO_PAGE_BY_KIND`(`template-binding-contract.js:125-130`)。自动绑定还会按 `AUTO_PAGE_CANDIDATES`(`:136-140`)依次试第一个**通过校验**的页;一个都不合法 ⇒ 留空、由渲染期兜底,并记一条 warn。
|
|
115
|
+
|
|
116
|
+
> 兜底是**保险丝**:新站 / 老站没来得及逐栏目建页时不能白屏。**规范做法永远是 2.1 的独立文件**。
|
|
117
|
+
|
|
118
|
+
## 3. 首页版块(Home blocks)
|
|
119
|
+
|
|
120
|
+
- 「首页版块」= 首页栏目下 `in_menu=false` 的栏目,**一块一个栏目、一块一个 id**(老板 2026-11-09 / 11-13 口径;`cli/lib/manifest-apply.mjs:656-686` 的 `inMenu` 反推规则)。
|
|
121
|
+
- **某个主题已经有同名栏目 ⇒ 首页版块只做跳转,不要再建一个自己维护内容的版块**:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
wkgeo categories save <首页版块栏目> --link-category <目标栏目ID>
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
字段 `link_category_id`、命令参数 `--link-category` 都已实现(`cli/lib/commands/cms.mjs:419`、`:445`;服务端 `aliyun/fc/_shared/content-actions.js:1541-1633`)。给了它 = 点这个版块直接跳到目标栏目**当前的** path(渲染期以 id 为准,目标栏目改路径也跟着走)。
|
|
128
|
+
- 只有**主题不重复**(本站确实没有对应栏目)时,首页版块才可以自己维护内容。
|
|
129
|
+
- 🚧 「按名字自动认出同名栏目、自动写 `link_category_id`」**实现中**(`category-icon-and-home-link`);现在需要**显式传 `--link-category`**。
|
|
130
|
+
|
|
131
|
+
## 4. 图标(Icon)
|
|
132
|
+
|
|
133
|
+
- **只认 iconify 名**:`前缀:名字`,如 `mdi:home-outline`(正则校验在服务端 `aliyun/fc/_shared/content-actions.js:1717`);写错**不报错、只是那一位空白** ⇒ 必须用真实存在的图标名。
|
|
134
|
+
- 设置:`wkgeo categories save <栏目> --icon mdi:home-outline`。
|
|
135
|
+
- **同一个站内图标不能全一样**(是什么无所谓,全一样不对)。
|
|
136
|
+
- 🚧 「不选时由系统分配**不重复**的默认图标」**实现中**(`category-icon-and-home-link`);现在不传 `--icon` 时前台回落到统一兜底图标 `mdi:folder-outline`(`content-actions.js:612`)。
|
|
137
|
+
|
|
138
|
+
## 5. 命令对照(做这几件事只走这些命令)
|
|
139
|
+
|
|
140
|
+
| 要做的事 | 命令 |
|
|
141
|
+
|---|---|
|
|
142
|
+
| 打印本规范 | `wkgeo spec`(精简版 `--agents`) |
|
|
143
|
+
| 把规范落到项目(自动注入给 agent) | `wkgeo init --confirm` |
|
|
144
|
+
| 看栏目树 / 单个栏目 | `wkgeo categories list` / `wkgeo categories get <栏目>` |
|
|
145
|
+
| 新建 / 改栏目(含图标、跳转、绑模板) | `wkgeo categories save [栏目] --name … --kind … --icon … --link-category … --template-path …` |
|
|
146
|
+
| 只绑模板 | `wkgeo categories bind-template <栏目> <文件.html>`(`--clear` 解绑) |
|
|
147
|
+
| 整站落库(栏目/字段/素材/内容/单页/导航) | `wkgeo content apply --file site-manifest.json`(默认 dry-run,`--confirm` 才写) |
|
|
148
|
+
| 按模板栏目填内容 | `wkgeo content fill --manifest manifest.json`(同上) |
|
|
149
|
+
| 契约 ↔ 库 ↔ 前台自检 | `wkgeo content check --site <站点ID>` |
|
|
150
|
+
| 拉 / 推模板文件 | `wkgeo templates pull` / `wkgeo templates push --confirm` |
|
|
151
|
+
| 预览 / 发布 | `wkgeo preview --site <ID>` / `wkgeo publish --site <ID> --confirm` |
|
|
152
|
+
|
|
153
|
+
## 6. 验收(不跑不算做完)
|
|
154
|
+
|
|
155
|
+
1. `wkgeo content apply … ` 先 **dry-run**,计划与老板对过再 `--confirm`;复跑必须全 `skipped`(幂等)。
|
|
156
|
+
2. `wkgeo content check --site <ID>` **exit 0**(四种硬问题:类型不符 / 必填缺字段 / 库多出字段 / 栏目缺列)。
|
|
157
|
+
3. `wkgeo preview` 逐屏看:首页 + 每个栏目列表页 + 至少一条详情页 + 每个单页。
|
|
158
|
+
4. 发布后短域首页与栏目页 **HTTP 200**(`curl -sS -o /dev/null -w "%{http_code}" https://<短域>/`)。
|
|
159
|
+
5. 模板线另加:`wkgeo template validate <目录>` exit 0、`template verify` 像素 ≥95%、`template score` 达标。
|
|
160
|
+
|
|
161
|
+
## 7. 规则状态(哪些真的生效了)
|
|
162
|
+
|
|
163
|
+
| 规则 | 状态 | 证据 / 单名 |
|
|
164
|
+
|---|---|---|
|
|
165
|
+
| 栏目类型只有 `channel`/`list`/`page` | ✅ | `template-binding-contract.js:52`;`cms.mjs:440` |
|
|
166
|
+
| 清单 `type: single` → `kind: page` | ✅ | `site-mapping-contract.mjs:149-151` |
|
|
167
|
+
| 子栏目继承父类型 / 首页锁 channel | ✅ | `content-actions.js:1887-1889`(二级及以下只能继承);`cms.mjs:483`(首页锁 channel) |
|
|
168
|
+
| 绑定字段 `template_path` + `bind-template` / `--template-path` | ✅ | `cms.mjs:433`、`:625`;`manifest-apply.mjs:776` |
|
|
169
|
+
| `target_type` 与 kind 兼容校验 | ✅ | `template-binding-contract.js:73-77`、`:471-477` |
|
|
170
|
+
| 没绑时按 kind 自动兜底 | ✅ | `template-binding-contract.js:125-130` |
|
|
171
|
+
| 首页版块 `link_category_id` 跳转(字段 + 命令 + 渲染) | ✅ | `content-actions.js:1541-1633`;`cms.mjs:419` |
|
|
172
|
+
| 图标必须是合法 iconify 名 | ✅ | `content-actions.js:1710-1720` |
|
|
173
|
+
| **每个栏目一份独立 `pages/c-<slug>.html`(脚手架 / 建站播种)** | 🚧 实现中 | `per-category-template-20261121`;契约与 CLI 代码已在工作区(`template-binding-contract.js:698-814`、`cli/lib/template-gen.mjs`),未验收未发布 |
|
|
174
|
+
| **首页版块按同名栏目自动写 `link_category_id`** | 🚧 实现中 | `category-icon-and-home-link` |
|
|
175
|
+
| **不选图标时系统分配不重复的默认图标** | 🚧 实现中 | `category-icon-and-home-link`;现状统一回落 `mdi:folder-outline` |
|
|
176
|
+
|
|
177
|
+
> 实现中的三条**不要**当既有行为依赖;等对应单验收后再把 §2.1 / §3 / §4 的"实现中"字样去掉(改这一份 + 重跑生成器即可)。
|
|
178
|
+
|
|
179
|
+
## 8. 沙箱任务提示词里的精要(自动摘取,别手改)
|
|
180
|
+
|
|
181
|
+
云端沙箱里的 AI 拿不到本地文件,只能看到任务提示词 + 镜像/启动时放进去的 skill。
|
|
182
|
+
所以这里留一段**极短**的精要,由 `cli/scripts/gen-site-spec.mjs` 摘进 `wkgeo-agent-task` 的提示词;
|
|
183
|
+
与 skill 正文同源(改上面规则时这段跟着一起改)。
|
|
184
|
+
|
|
185
|
+
<!-- wkgeo:site-spec:prompt:begin -->
|
|
186
|
+
【建站规范(沙箱内已放 skill:wkgeo-site-spec,开工前先加载)】
|
|
187
|
+
- 栏目类型只有 channel / list / page 三种;子栏目继承父类型,首页固定 channel。
|
|
188
|
+
- 每个栏目一份独立模板 pages/c-<slug>.html(可从默认档复制,但文件必须独立);绑定字段 template_path。
|
|
189
|
+
- 模板页 target_type 必须与栏目 kind 兼容:page→single_page|article;list→list|list+category;channel→channel|list|list+category。
|
|
190
|
+
- 首页版块已有同名栏目 ⇒ 只做跳转(link_category_id),别再建一个自己维护内容的同名版块。
|
|
191
|
+
- 图标用 iconify 名(如 mdi:home-outline),同一个站内不能全一样。
|
|
192
|
+
- 栏目没绑模板时按 kind 兜底:list/channel→pages/index.html,page→pages/page.html。
|
|
193
|
+
(完整规范:本地跑 `wkgeo spec`;沙箱内加载 skill `wkgeo-site-spec`)
|
|
194
|
+
<!-- wkgeo:site-spec:prompt:end -->
|
|
195
|
+
|
|
196
|
+
## 9. 变更记录
|
|
197
|
+
|
|
198
|
+
- 2026-11-21:首版。三处同源(`wkgeo spec` / `wkgeo init` 写的约定文件 / `wkgeo-site-spec` skill),规则逐条标 ✅ / 🚧。
|