@wkgeo/cli 2.0.3 → 2.2.0
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/CHANGELOG.md +19 -2
- package/README.md +7 -7
- package/SKILL.md +1038 -1038
- package/lib/api.mjs +351 -351
- package/lib/args.mjs +235 -235
- package/lib/build.mjs +1047 -0
- package/lib/cms.mjs +328 -328
- package/lib/commands/auth.mjs +1280 -1280
- package/lib/commands/data.mjs +694 -694
- package/lib/commands/index.mjs +17 -1
- package/lib/commands/init.mjs +111 -111
- package/lib/commands/orders.mjs +691 -691
- package/lib/commands/site.mjs +82 -0
- package/lib/commands/siteops.mjs +382 -0
- package/lib/commands/sites.mjs +968 -801
- package/lib/commands/spec.mjs +72 -72
- package/lib/commands/template.mjs +1484 -1484
- package/lib/config.mjs +57 -4
- package/lib/errors.mjs +446 -336
- package/lib/manifest-apply.mjs +1650 -1650
- package/lib/manifest-schema.json +480 -480
- package/lib/manifest.mjs +1106 -1106
- package/lib/runtime.mjs +798 -654
- package/lib/site-create.mjs +537 -537
- package/lib/site-credentials.mjs +157 -0
- package/lib/site-meta.mjs +474 -0
- package/lib/site-publish.mjs +410 -0
- package/lib/site-spec.mjs +302 -302
- package/lib/site-template.mjs +405 -0
- package/lib/template-gen.mjs +1354 -1354
- package/lib/template-publish.mjs +696 -696
- package/lib/templates-sync.mjs +676 -644
- package/lib/workspace-sync.mjs +386 -0
- package/package.json +56 -56
- package/spec/SITE-SPEC.md +198 -198
package/lib/site-spec.mjs
CHANGED
|
@@ -1,302 +1,302 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* 建站规范(SITE-SPEC)读取层 —— **唯一主源 = 包内 `spec/SITE-SPEC.md`**。
|
|
3
|
-
*
|
|
4
|
-
* ## 为什么要有这一层
|
|
5
|
-
* 规范只有一份文件,但出口有三个:
|
|
6
|
-
* ① `wkgeo spec`(人 / 本地 CLI 里的 agent 主动跑);
|
|
7
|
-
* ② `wkgeo init` 把「给 AI 的精简版」写进项目的 AGENTS.md / CLAUDE.md / .cursorrules /
|
|
8
|
-
* .github/copilot-instructions.md(**agent 启动时自己读**,这才是"自动读到"的入口);
|
|
9
|
-
* ③ `wkgeo-site-spec` skill(DSH 本机 / 云端沙箱加载)。
|
|
10
|
-
* 三个出口**不能各写一份**(一定会漂移),所以:
|
|
11
|
-
* * ②③ 的内容都从这份 markdown 里**切出来 / 生成**;
|
|
12
|
-
* * 口径标记写在 markdown 里(`<!-- wkgeo:site-spec:agents:begin -->` … `end`),
|
|
13
|
-
* 这里只做"按标记切",不在这里复制规则文本。
|
|
14
|
-
*
|
|
15
|
-
* ## 路径解析(与 `skill.mjs` 同一个坑)
|
|
16
|
-
* `import.meta.url` = `<包根>/lib/site-spec.mjs` ⇒ 往上一级是包根,再进 `spec/`。
|
|
17
|
-
* **绝不能**用 `process.cwd()`:AI 端几乎总在别的目录里跑,npx 更是如此。
|
|
18
|
-
*/
|
|
19
|
-
|
|
20
|
-
import fs from 'node:fs';
|
|
21
|
-
import path from 'node:path';
|
|
22
|
-
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
23
|
-
|
|
24
|
-
import { CliError, EXIT, UsageError } from './errors.mjs';
|
|
25
|
-
|
|
26
|
-
/** 包根下的 `spec/SITE-SPEC.md` */
|
|
27
|
-
export const SPEC_URL = new URL('../spec/SITE-SPEC.md', import.meta.url);
|
|
28
|
-
|
|
29
|
-
/** 「给 AI 的精简版」在 markdown 里的起止标记(改标记 = 三处一起变,别只改一边) */
|
|
30
|
-
export const BRIEF_BEGIN = '<!-- wkgeo:site-spec:agents:begin -->';
|
|
31
|
-
export const BRIEF_END = '<!-- wkgeo:site-spec:agents:end -->';
|
|
32
|
-
|
|
33
|
-
/** 写进项目文件的那一段也用同一对标记包起来(重复跑靠它原地替换,不重复追加) */
|
|
34
|
-
export const BLOCK_BEGIN = '<!-- wkgeo:site-spec:begin -->';
|
|
35
|
-
export const BLOCK_END = '<!-- wkgeo:site-spec:end -->';
|
|
36
|
-
|
|
37
|
-
/** 沙箱任务提示词里那几行的标记(云端 AI 读不到本地文件,只能靠提示词 + 镜像里的 skill) */
|
|
38
|
-
export const PROMPT_BEGIN = '<!-- wkgeo:site-spec:prompt:begin -->';
|
|
39
|
-
export const PROMPT_END = '<!-- wkgeo:site-spec:prompt:end -->';
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* 四个约定文件 —— 覆盖主流 coding agent 的"启动即读"文件。
|
|
43
|
-
*
|
|
44
|
-
* ⚠️ CLI **不判断**调用者是哪个 agent(`process.env` 里没有可靠特征,用户在任意 shell 里跑、
|
|
45
|
-
* 或被别的工具当子进程调,都会误判)。所以默认**全写**,用 `--agents` 让用户自己挑。
|
|
46
|
-
*/
|
|
47
|
-
export const AGENT_FILES = Object.freeze([
|
|
48
|
-
Object.freeze({
|
|
49
|
-
key: 'agents',
|
|
50
|
-
path: 'AGENTS.md',
|
|
51
|
-
label: 'DSH / Codex / 通用 AGENTS.md',
|
|
52
|
-
aliases: ['agents', 'agents.md', 'codex', 'dsh'],
|
|
53
|
-
}),
|
|
54
|
-
Object.freeze({
|
|
55
|
-
key: 'claude',
|
|
56
|
-
path: 'CLAUDE.md',
|
|
57
|
-
label: 'Claude Code CLAUDE.md',
|
|
58
|
-
aliases: ['claude', 'claude.md', 'claude-code'],
|
|
59
|
-
}),
|
|
60
|
-
Object.freeze({
|
|
61
|
-
key: 'cursor',
|
|
62
|
-
path: '.cursorrules',
|
|
63
|
-
label: 'Cursor .cursorrules',
|
|
64
|
-
aliases: ['cursor', '.cursorrules'],
|
|
65
|
-
}),
|
|
66
|
-
Object.freeze({
|
|
67
|
-
key: 'copilot',
|
|
68
|
-
path: '.github/copilot-instructions.md',
|
|
69
|
-
label: 'GitHub Copilot 指令文件',
|
|
70
|
-
aliases: ['copilot', 'github', 'copilot-instructions'],
|
|
71
|
-
}),
|
|
72
|
-
]);
|
|
73
|
-
|
|
74
|
-
/**
|
|
75
|
-
* 读主源 markdown。
|
|
76
|
-
*
|
|
77
|
-
* @param {URL|string} [src] 默认包内 `spec/SITE-SPEC.md`(单测可指到别处)
|
|
78
|
-
* @returns {{path:string, markdown:string, bytes:number, lines:number}}
|
|
79
|
-
* @throws {CliError} 文件缺失 ⇒ `kind="missing_spec"`、exit 1、带中文 hint(不打堆栈)
|
|
80
|
-
*/
|
|
81
|
-
export function readSpecMarkdown(src = SPEC_URL) {
|
|
82
|
-
const url = src instanceof URL ? src : pathToFileURL(String(src));
|
|
83
|
-
let filePath = String(url);
|
|
84
|
-
try {
|
|
85
|
-
filePath = fileURLToPath(url);
|
|
86
|
-
} catch {
|
|
87
|
-
/* 非 file: URL 时退回原样展示,别为展示路径把命令搞崩 */
|
|
88
|
-
}
|
|
89
|
-
try {
|
|
90
|
-
const markdown = fs.readFileSync(url, 'utf8');
|
|
91
|
-
return {
|
|
92
|
-
path: filePath,
|
|
93
|
-
markdown,
|
|
94
|
-
bytes: Buffer.byteLength(markdown, 'utf8'),
|
|
95
|
-
lines: markdown.split('\n').length,
|
|
96
|
-
};
|
|
97
|
-
} catch (e) {
|
|
98
|
-
const why = (e && e.code) || '读取失败';
|
|
99
|
-
throw new CliError(`当前安装包里没有建站规范(spec/SITE-SPEC.md):${filePath}(${why})`, {
|
|
100
|
-
kind: 'missing_spec',
|
|
101
|
-
code: (e && e.code) || null,
|
|
102
|
-
exitCode: EXIT.ERROR,
|
|
103
|
-
hint:
|
|
104
|
-
'这不是命令用错了:多半是开发目录里只拷了 lib/、或分发包缺了 files 白名单里的 spec/。' +
|
|
105
|
-
'可改用官方包 `npx -y @wkgeo/cli@latest spec`,或直接看仓库里的 cli/spec/SITE-SPEC.md',
|
|
106
|
-
cause: e,
|
|
107
|
-
});
|
|
108
|
-
}
|
|
109
|
-
}
|
|
110
|
-
|
|
111
|
-
/**
|
|
112
|
-
* 从全文里切出两个标记之间的正文(通用:精简版 / 沙箱提示词精要都走它)。
|
|
113
|
-
*
|
|
114
|
-
* @param {string} markdown
|
|
115
|
-
* @param {string} begin 起标记
|
|
116
|
-
* @param {string} end 止标记
|
|
117
|
-
* @param {string} what 报错时怎么称呼这一段(中文)
|
|
118
|
-
* @returns {string} 已去首尾空行、末尾带一个换行
|
|
119
|
-
* @throws {CliError} 标记缺失 / 顺序颠倒 / 空段 ⇒ 直接报错(宁可炸,也别写一份空规范出去)
|
|
120
|
-
*/
|
|
121
|
-
export function extractSection(markdown, begin, end, what = '规范段落') {
|
|
122
|
-
const text = String(markdown || '');
|
|
123
|
-
const start = text.indexOf(begin);
|
|
124
|
-
const stop = text.indexOf(end);
|
|
125
|
-
if (start === -1 || stop === -1 || stop < start) {
|
|
126
|
-
throw new CliError(`建站规范里找不到${what}的标记(begin/end),无法生成`, {
|
|
127
|
-
kind: 'spec_marker_missing',
|
|
128
|
-
exitCode: EXIT.ERROR,
|
|
129
|
-
hint: `规范里必须有 ${begin} 与 ${end} 两行,且 begin 在 end 之前`,
|
|
130
|
-
});
|
|
131
|
-
}
|
|
132
|
-
const body = text
|
|
133
|
-
.slice(start + begin.length, stop)
|
|
134
|
-
.replace(/^\r?\n/, '')
|
|
135
|
-
.replace(/\s+$/, '');
|
|
136
|
-
if (!body.trim()) {
|
|
137
|
-
throw new CliError(`${what}的标记之间是空的,拒绝写出去`, {
|
|
138
|
-
kind: 'spec_marker_empty',
|
|
139
|
-
exitCode: EXIT.ERROR,
|
|
140
|
-
});
|
|
141
|
-
}
|
|
142
|
-
return body + '\n';
|
|
143
|
-
}
|
|
144
|
-
|
|
145
|
-
/**
|
|
146
|
-
* 「给 AI 的精简版」—— 写进项目四个约定文件的那一段。
|
|
147
|
-
*
|
|
148
|
-
* @param {string} markdown
|
|
149
|
-
* @returns {string}
|
|
150
|
-
*/
|
|
151
|
-
export function extractAgentsBrief(markdown) {
|
|
152
|
-
return extractSection(markdown, BRIEF_BEGIN, BRIEF_END, '「给 AI 的精简版」');
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
/**
|
|
156
|
-
* 沙箱任务提示词里的精要(云端 AI 看不到本地文件,只能靠提示词 + 镜像里的 skill)。
|
|
157
|
-
*
|
|
158
|
-
* @param {string} markdown
|
|
159
|
-
* @returns {string}
|
|
160
|
-
*/
|
|
161
|
-
export function extractPromptBrief(markdown) {
|
|
162
|
-
return extractSection(markdown, PROMPT_BEGIN, PROMPT_END, '「沙箱提示词精要」');
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
/**
|
|
166
|
-
* 解析 `--agents` 的取值。
|
|
167
|
-
*
|
|
168
|
-
* `all`(默认) = 四个都写;`none` = 一个都不写;
|
|
169
|
-
* 其它 = 逗号 / 空格分隔的点名:认 key(`agents` / `claude` / `cursor` / `copilot`)、
|
|
170
|
-
* 认文件名(`AGENTS.md` / `CLAUDE.md` / `.cursorrules` / `.github/copilot-instructions.md`)、
|
|
171
|
-
* 也认简写(`codex` / `dsh` / `github`)。
|
|
172
|
-
*
|
|
173
|
-
* @param {string|boolean|undefined} value
|
|
174
|
-
* @returns {Array<typeof AGENT_FILES[number]>}
|
|
175
|
-
* @throws {UsageError} 认不出来的名字 ⇒ 列出可用值(别静默忽略)
|
|
176
|
-
*/
|
|
177
|
-
export function resolveAgentFiles(value) {
|
|
178
|
-
const raw = value === undefined || value === null || value === true ? 'all' : String(value).trim();
|
|
179
|
-
if (!raw || raw.toLowerCase() === 'all') return [...AGENT_FILES];
|
|
180
|
-
if (raw.toLowerCase() === 'none') return [];
|
|
181
|
-
const wanted = raw
|
|
182
|
-
.split(/[,\s]+/)
|
|
183
|
-
.map((one) => one.trim())
|
|
184
|
-
.filter(Boolean);
|
|
185
|
-
const out = [];
|
|
186
|
-
const unknown = [];
|
|
187
|
-
for (const name of wanted) {
|
|
188
|
-
const lower = name.toLowerCase().replace(/\\/g, '/');
|
|
189
|
-
const hit = AGENT_FILES.find(
|
|
190
|
-
(one) => one.key === lower || one.path.toLowerCase() === lower || one.aliases.includes(lower),
|
|
191
|
-
);
|
|
192
|
-
if (!hit) {
|
|
193
|
-
unknown.push(name);
|
|
194
|
-
continue;
|
|
195
|
-
}
|
|
196
|
-
if (!out.includes(hit)) out.push(hit);
|
|
197
|
-
}
|
|
198
|
-
if (unknown.length) {
|
|
199
|
-
const usable = AGENT_FILES.map((one) => `${one.key}(${one.path})`).join(' / ');
|
|
200
|
-
throw new UsageError(`--agents 不认识:${unknown.join(', ')}\n可用:all / none / ${usable}`);
|
|
201
|
-
}
|
|
202
|
-
return out;
|
|
203
|
-
}
|
|
204
|
-
|
|
205
|
-
/** 现有文件用的换行符(Windows 项目里多半是 CRLF,插入段跟着走,别混出两种) */
|
|
206
|
-
function eolOf(text) {
|
|
207
|
-
return String(text || '').includes('\r\n') ? '\r\n' : '\n';
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
/** 把块里的 `\n` 换成目标换行符 */
|
|
211
|
-
function withEol(block, eol) {
|
|
212
|
-
return eol === '\n' ? block : block.split('\n').join(eol);
|
|
213
|
-
}
|
|
214
|
-
|
|
215
|
-
/**
|
|
216
|
-
* 把「精简版」并进一份已有文件的内容 —— **纯函数**(单测直接对拍)。
|
|
217
|
-
*
|
|
218
|
-
* 四种结果:
|
|
219
|
-
* * `created` 文件原本不存在 / 空 ⇒ 直接就是这一段;
|
|
220
|
-
* * `replaced` 已有我们那一段(begin/end 都在)⇒ **原地替换**(改规范后重跑不会重复追加);
|
|
221
|
-
* * `appended` 文件有内容但没有我们的标记 ⇒ **只在末尾追加**,用户写的一个字不动;
|
|
222
|
-
* * `unchanged` 算出来的全文与原来一字节不差 ⇒ 不写盘(幂等)。
|
|
223
|
-
*
|
|
224
|
-
* @param {string|null} existing 已有内容(null = 文件不存在)
|
|
225
|
-
* @param {string} brief 「给 AI 的精简版」正文(末尾带换行)
|
|
226
|
-
* @returns {{content:string, action:'created'|'replaced'|'appended'|'unchanged'}}
|
|
227
|
-
*/
|
|
228
|
-
export function upsertBriefBlock(existing, brief) {
|
|
229
|
-
const body = String(brief || '').replace(/\s+$/, '');
|
|
230
|
-
const block = `${BLOCK_BEGIN}\n${body}\n${BLOCK_END}`;
|
|
231
|
-
if (existing === null || existing === undefined || !String(existing).trim()) {
|
|
232
|
-
const content = `${block}\n`;
|
|
233
|
-
return { content, action: 'created' };
|
|
234
|
-
}
|
|
235
|
-
const text = String(existing);
|
|
236
|
-
const eol = eolOf(text);
|
|
237
|
-
const marker = withEol(block, eol);
|
|
238
|
-
const start = text.indexOf(BLOCK_BEGIN);
|
|
239
|
-
const end = text.indexOf(BLOCK_END, start === -1 ? 0 : start);
|
|
240
|
-
if (start !== -1 && end !== -1) {
|
|
241
|
-
const after = text.slice(end + BLOCK_END.length);
|
|
242
|
-
const next = text.slice(0, start) + marker + after;
|
|
243
|
-
return { content: next, action: next === text ? 'unchanged' : 'replaced' };
|
|
244
|
-
}
|
|
245
|
-
/* 没有我们的标记 ⇒ 追加到末尾;文件末尾没换行就先补一个,段间留一个空行 */
|
|
246
|
-
const base = text.endsWith('\n') ? text : text + eol;
|
|
247
|
-
const next = `${base}${eol}${marker}${eol}`;
|
|
248
|
-
return { content: next, action: 'appended' };
|
|
249
|
-
}
|
|
250
|
-
|
|
251
|
-
/**
|
|
252
|
-
* 规划「四个约定文件各要写成什么」—— **不写盘**(dry-run 与真写共用同一份计划)。
|
|
253
|
-
*
|
|
254
|
-
* @param {{dir?:string, markdown:string, files?:Array, exists?:Function, readFile?:Function}} input
|
|
255
|
-
* @returns {Array<{key,path,action,absPath,content,reason}>}
|
|
256
|
-
*/
|
|
257
|
-
export function planAgentFiles(input = {}) {
|
|
258
|
-
const dir = path.resolve(String(input.dir || process.cwd()));
|
|
259
|
-
const files = Array.isArray(input.files) ? input.files : [...AGENT_FILES];
|
|
260
|
-
const brief = extractAgentsBrief(input.markdown);
|
|
261
|
-
const read = input.readFile || ((p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null));
|
|
262
|
-
const rows = [];
|
|
263
|
-
for (const one of files) {
|
|
264
|
-
const absPath = path.join(dir, one.path.split('/').join(path.sep));
|
|
265
|
-
const existing = read(absPath);
|
|
266
|
-
const { content, action } = upsertBriefBlock(existing, brief);
|
|
267
|
-
rows.push({
|
|
268
|
-
key: one.key,
|
|
269
|
-
path: one.path,
|
|
270
|
-
label: one.label,
|
|
271
|
-
absPath,
|
|
272
|
-
action,
|
|
273
|
-
content,
|
|
274
|
-
existed: existing !== null && existing !== undefined,
|
|
275
|
-
});
|
|
276
|
-
}
|
|
277
|
-
return rows;
|
|
278
|
-
}
|
|
279
|
-
|
|
280
|
-
/**
|
|
281
|
-
* 落盘(只写 `action !== 'unchanged'` 的行)。
|
|
282
|
-
*
|
|
283
|
-
* @param {Array} plan `planAgentFiles()` 的结果
|
|
284
|
-
* @param {{mkdir?:Function, writeFile?:Function}} [io] 单测注入点
|
|
285
|
-
* @returns {{written:string[], skipped:string[]}}
|
|
286
|
-
*/
|
|
287
|
-
export function writeAgentFiles(plan, io = {}) {
|
|
288
|
-
const mkdir = io.mkdir || ((p) => fs.mkdirSync(p, { recursive: true }));
|
|
289
|
-
const writeFile = io.writeFile || ((p, c) => fs.writeFileSync(p, c, 'utf8'));
|
|
290
|
-
const written = [];
|
|
291
|
-
const skipped = [];
|
|
292
|
-
for (const row of plan) {
|
|
293
|
-
if (row.action === 'unchanged') {
|
|
294
|
-
skipped.push(row.path);
|
|
295
|
-
continue;
|
|
296
|
-
}
|
|
297
|
-
mkdir(path.dirname(row.absPath));
|
|
298
|
-
writeFile(row.absPath, row.content);
|
|
299
|
-
written.push(row.path);
|
|
300
|
-
}
|
|
301
|
-
return { written, skipped };
|
|
302
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* 建站规范(SITE-SPEC)读取层 —— **唯一主源 = 包内 `spec/SITE-SPEC.md`**。
|
|
3
|
+
*
|
|
4
|
+
* ## 为什么要有这一层
|
|
5
|
+
* 规范只有一份文件,但出口有三个:
|
|
6
|
+
* ① `wkgeo spec`(人 / 本地 CLI 里的 agent 主动跑);
|
|
7
|
+
* ② `wkgeo init` 把「给 AI 的精简版」写进项目的 AGENTS.md / CLAUDE.md / .cursorrules /
|
|
8
|
+
* .github/copilot-instructions.md(**agent 启动时自己读**,这才是"自动读到"的入口);
|
|
9
|
+
* ③ `wkgeo-site-spec` skill(DSH 本机 / 云端沙箱加载)。
|
|
10
|
+
* 三个出口**不能各写一份**(一定会漂移),所以:
|
|
11
|
+
* * ②③ 的内容都从这份 markdown 里**切出来 / 生成**;
|
|
12
|
+
* * 口径标记写在 markdown 里(`<!-- wkgeo:site-spec:agents:begin -->` … `end`),
|
|
13
|
+
* 这里只做"按标记切",不在这里复制规则文本。
|
|
14
|
+
*
|
|
15
|
+
* ## 路径解析(与 `skill.mjs` 同一个坑)
|
|
16
|
+
* `import.meta.url` = `<包根>/lib/site-spec.mjs` ⇒ 往上一级是包根,再进 `spec/`。
|
|
17
|
+
* **绝不能**用 `process.cwd()`:AI 端几乎总在别的目录里跑,npx 更是如此。
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import fs from 'node:fs';
|
|
21
|
+
import path from 'node:path';
|
|
22
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
23
|
+
|
|
24
|
+
import { CliError, EXIT, UsageError } from './errors.mjs';
|
|
25
|
+
|
|
26
|
+
/** 包根下的 `spec/SITE-SPEC.md` */
|
|
27
|
+
export const SPEC_URL = new URL('../spec/SITE-SPEC.md', import.meta.url);
|
|
28
|
+
|
|
29
|
+
/** 「给 AI 的精简版」在 markdown 里的起止标记(改标记 = 三处一起变,别只改一边) */
|
|
30
|
+
export const BRIEF_BEGIN = '<!-- wkgeo:site-spec:agents:begin -->';
|
|
31
|
+
export const BRIEF_END = '<!-- wkgeo:site-spec:agents:end -->';
|
|
32
|
+
|
|
33
|
+
/** 写进项目文件的那一段也用同一对标记包起来(重复跑靠它原地替换,不重复追加) */
|
|
34
|
+
export const BLOCK_BEGIN = '<!-- wkgeo:site-spec:begin -->';
|
|
35
|
+
export const BLOCK_END = '<!-- wkgeo:site-spec:end -->';
|
|
36
|
+
|
|
37
|
+
/** 沙箱任务提示词里那几行的标记(云端 AI 读不到本地文件,只能靠提示词 + 镜像里的 skill) */
|
|
38
|
+
export const PROMPT_BEGIN = '<!-- wkgeo:site-spec:prompt:begin -->';
|
|
39
|
+
export const PROMPT_END = '<!-- wkgeo:site-spec:prompt:end -->';
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* 四个约定文件 —— 覆盖主流 coding agent 的"启动即读"文件。
|
|
43
|
+
*
|
|
44
|
+
* ⚠️ CLI **不判断**调用者是哪个 agent(`process.env` 里没有可靠特征,用户在任意 shell 里跑、
|
|
45
|
+
* 或被别的工具当子进程调,都会误判)。所以默认**全写**,用 `--agents` 让用户自己挑。
|
|
46
|
+
*/
|
|
47
|
+
export const AGENT_FILES = Object.freeze([
|
|
48
|
+
Object.freeze({
|
|
49
|
+
key: 'agents',
|
|
50
|
+
path: 'AGENTS.md',
|
|
51
|
+
label: 'DSH / Codex / 通用 AGENTS.md',
|
|
52
|
+
aliases: ['agents', 'agents.md', 'codex', 'dsh'],
|
|
53
|
+
}),
|
|
54
|
+
Object.freeze({
|
|
55
|
+
key: 'claude',
|
|
56
|
+
path: 'CLAUDE.md',
|
|
57
|
+
label: 'Claude Code CLAUDE.md',
|
|
58
|
+
aliases: ['claude', 'claude.md', 'claude-code'],
|
|
59
|
+
}),
|
|
60
|
+
Object.freeze({
|
|
61
|
+
key: 'cursor',
|
|
62
|
+
path: '.cursorrules',
|
|
63
|
+
label: 'Cursor .cursorrules',
|
|
64
|
+
aliases: ['cursor', '.cursorrules'],
|
|
65
|
+
}),
|
|
66
|
+
Object.freeze({
|
|
67
|
+
key: 'copilot',
|
|
68
|
+
path: '.github/copilot-instructions.md',
|
|
69
|
+
label: 'GitHub Copilot 指令文件',
|
|
70
|
+
aliases: ['copilot', 'github', 'copilot-instructions'],
|
|
71
|
+
}),
|
|
72
|
+
]);
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* 读主源 markdown。
|
|
76
|
+
*
|
|
77
|
+
* @param {URL|string} [src] 默认包内 `spec/SITE-SPEC.md`(单测可指到别处)
|
|
78
|
+
* @returns {{path:string, markdown:string, bytes:number, lines:number}}
|
|
79
|
+
* @throws {CliError} 文件缺失 ⇒ `kind="missing_spec"`、exit 1、带中文 hint(不打堆栈)
|
|
80
|
+
*/
|
|
81
|
+
export function readSpecMarkdown(src = SPEC_URL) {
|
|
82
|
+
const url = src instanceof URL ? src : pathToFileURL(String(src));
|
|
83
|
+
let filePath = String(url);
|
|
84
|
+
try {
|
|
85
|
+
filePath = fileURLToPath(url);
|
|
86
|
+
} catch {
|
|
87
|
+
/* 非 file: URL 时退回原样展示,别为展示路径把命令搞崩 */
|
|
88
|
+
}
|
|
89
|
+
try {
|
|
90
|
+
const markdown = fs.readFileSync(url, 'utf8');
|
|
91
|
+
return {
|
|
92
|
+
path: filePath,
|
|
93
|
+
markdown,
|
|
94
|
+
bytes: Buffer.byteLength(markdown, 'utf8'),
|
|
95
|
+
lines: markdown.split('\n').length,
|
|
96
|
+
};
|
|
97
|
+
} catch (e) {
|
|
98
|
+
const why = (e && e.code) || '读取失败';
|
|
99
|
+
throw new CliError(`当前安装包里没有建站规范(spec/SITE-SPEC.md):${filePath}(${why})`, {
|
|
100
|
+
kind: 'missing_spec',
|
|
101
|
+
code: (e && e.code) || null,
|
|
102
|
+
exitCode: EXIT.ERROR,
|
|
103
|
+
hint:
|
|
104
|
+
'这不是命令用错了:多半是开发目录里只拷了 lib/、或分发包缺了 files 白名单里的 spec/。' +
|
|
105
|
+
'可改用官方包 `npx -y @wkgeo/cli@latest spec`,或直接看仓库里的 cli/spec/SITE-SPEC.md',
|
|
106
|
+
cause: e,
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* 从全文里切出两个标记之间的正文(通用:精简版 / 沙箱提示词精要都走它)。
|
|
113
|
+
*
|
|
114
|
+
* @param {string} markdown
|
|
115
|
+
* @param {string} begin 起标记
|
|
116
|
+
* @param {string} end 止标记
|
|
117
|
+
* @param {string} what 报错时怎么称呼这一段(中文)
|
|
118
|
+
* @returns {string} 已去首尾空行、末尾带一个换行
|
|
119
|
+
* @throws {CliError} 标记缺失 / 顺序颠倒 / 空段 ⇒ 直接报错(宁可炸,也别写一份空规范出去)
|
|
120
|
+
*/
|
|
121
|
+
export function extractSection(markdown, begin, end, what = '规范段落') {
|
|
122
|
+
const text = String(markdown || '');
|
|
123
|
+
const start = text.indexOf(begin);
|
|
124
|
+
const stop = text.indexOf(end);
|
|
125
|
+
if (start === -1 || stop === -1 || stop < start) {
|
|
126
|
+
throw new CliError(`建站规范里找不到${what}的标记(begin/end),无法生成`, {
|
|
127
|
+
kind: 'spec_marker_missing',
|
|
128
|
+
exitCode: EXIT.ERROR,
|
|
129
|
+
hint: `规范里必须有 ${begin} 与 ${end} 两行,且 begin 在 end 之前`,
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
const body = text
|
|
133
|
+
.slice(start + begin.length, stop)
|
|
134
|
+
.replace(/^\r?\n/, '')
|
|
135
|
+
.replace(/\s+$/, '');
|
|
136
|
+
if (!body.trim()) {
|
|
137
|
+
throw new CliError(`${what}的标记之间是空的,拒绝写出去`, {
|
|
138
|
+
kind: 'spec_marker_empty',
|
|
139
|
+
exitCode: EXIT.ERROR,
|
|
140
|
+
});
|
|
141
|
+
}
|
|
142
|
+
return body + '\n';
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* 「给 AI 的精简版」—— 写进项目四个约定文件的那一段。
|
|
147
|
+
*
|
|
148
|
+
* @param {string} markdown
|
|
149
|
+
* @returns {string}
|
|
150
|
+
*/
|
|
151
|
+
export function extractAgentsBrief(markdown) {
|
|
152
|
+
return extractSection(markdown, BRIEF_BEGIN, BRIEF_END, '「给 AI 的精简版」');
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* 沙箱任务提示词里的精要(云端 AI 看不到本地文件,只能靠提示词 + 镜像里的 skill)。
|
|
157
|
+
*
|
|
158
|
+
* @param {string} markdown
|
|
159
|
+
* @returns {string}
|
|
160
|
+
*/
|
|
161
|
+
export function extractPromptBrief(markdown) {
|
|
162
|
+
return extractSection(markdown, PROMPT_BEGIN, PROMPT_END, '「沙箱提示词精要」');
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* 解析 `--agents` 的取值。
|
|
167
|
+
*
|
|
168
|
+
* `all`(默认) = 四个都写;`none` = 一个都不写;
|
|
169
|
+
* 其它 = 逗号 / 空格分隔的点名:认 key(`agents` / `claude` / `cursor` / `copilot`)、
|
|
170
|
+
* 认文件名(`AGENTS.md` / `CLAUDE.md` / `.cursorrules` / `.github/copilot-instructions.md`)、
|
|
171
|
+
* 也认简写(`codex` / `dsh` / `github`)。
|
|
172
|
+
*
|
|
173
|
+
* @param {string|boolean|undefined} value
|
|
174
|
+
* @returns {Array<typeof AGENT_FILES[number]>}
|
|
175
|
+
* @throws {UsageError} 认不出来的名字 ⇒ 列出可用值(别静默忽略)
|
|
176
|
+
*/
|
|
177
|
+
export function resolveAgentFiles(value) {
|
|
178
|
+
const raw = value === undefined || value === null || value === true ? 'all' : String(value).trim();
|
|
179
|
+
if (!raw || raw.toLowerCase() === 'all') return [...AGENT_FILES];
|
|
180
|
+
if (raw.toLowerCase() === 'none') return [];
|
|
181
|
+
const wanted = raw
|
|
182
|
+
.split(/[,\s]+/)
|
|
183
|
+
.map((one) => one.trim())
|
|
184
|
+
.filter(Boolean);
|
|
185
|
+
const out = [];
|
|
186
|
+
const unknown = [];
|
|
187
|
+
for (const name of wanted) {
|
|
188
|
+
const lower = name.toLowerCase().replace(/\\/g, '/');
|
|
189
|
+
const hit = AGENT_FILES.find(
|
|
190
|
+
(one) => one.key === lower || one.path.toLowerCase() === lower || one.aliases.includes(lower),
|
|
191
|
+
);
|
|
192
|
+
if (!hit) {
|
|
193
|
+
unknown.push(name);
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
if (!out.includes(hit)) out.push(hit);
|
|
197
|
+
}
|
|
198
|
+
if (unknown.length) {
|
|
199
|
+
const usable = AGENT_FILES.map((one) => `${one.key}(${one.path})`).join(' / ');
|
|
200
|
+
throw new UsageError(`--agents 不认识:${unknown.join(', ')}\n可用:all / none / ${usable}`);
|
|
201
|
+
}
|
|
202
|
+
return out;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/** 现有文件用的换行符(Windows 项目里多半是 CRLF,插入段跟着走,别混出两种) */
|
|
206
|
+
function eolOf(text) {
|
|
207
|
+
return String(text || '').includes('\r\n') ? '\r\n' : '\n';
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** 把块里的 `\n` 换成目标换行符 */
|
|
211
|
+
function withEol(block, eol) {
|
|
212
|
+
return eol === '\n' ? block : block.split('\n').join(eol);
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* 把「精简版」并进一份已有文件的内容 —— **纯函数**(单测直接对拍)。
|
|
217
|
+
*
|
|
218
|
+
* 四种结果:
|
|
219
|
+
* * `created` 文件原本不存在 / 空 ⇒ 直接就是这一段;
|
|
220
|
+
* * `replaced` 已有我们那一段(begin/end 都在)⇒ **原地替换**(改规范后重跑不会重复追加);
|
|
221
|
+
* * `appended` 文件有内容但没有我们的标记 ⇒ **只在末尾追加**,用户写的一个字不动;
|
|
222
|
+
* * `unchanged` 算出来的全文与原来一字节不差 ⇒ 不写盘(幂等)。
|
|
223
|
+
*
|
|
224
|
+
* @param {string|null} existing 已有内容(null = 文件不存在)
|
|
225
|
+
* @param {string} brief 「给 AI 的精简版」正文(末尾带换行)
|
|
226
|
+
* @returns {{content:string, action:'created'|'replaced'|'appended'|'unchanged'}}
|
|
227
|
+
*/
|
|
228
|
+
export function upsertBriefBlock(existing, brief) {
|
|
229
|
+
const body = String(brief || '').replace(/\s+$/, '');
|
|
230
|
+
const block = `${BLOCK_BEGIN}\n${body}\n${BLOCK_END}`;
|
|
231
|
+
if (existing === null || existing === undefined || !String(existing).trim()) {
|
|
232
|
+
const content = `${block}\n`;
|
|
233
|
+
return { content, action: 'created' };
|
|
234
|
+
}
|
|
235
|
+
const text = String(existing);
|
|
236
|
+
const eol = eolOf(text);
|
|
237
|
+
const marker = withEol(block, eol);
|
|
238
|
+
const start = text.indexOf(BLOCK_BEGIN);
|
|
239
|
+
const end = text.indexOf(BLOCK_END, start === -1 ? 0 : start);
|
|
240
|
+
if (start !== -1 && end !== -1) {
|
|
241
|
+
const after = text.slice(end + BLOCK_END.length);
|
|
242
|
+
const next = text.slice(0, start) + marker + after;
|
|
243
|
+
return { content: next, action: next === text ? 'unchanged' : 'replaced' };
|
|
244
|
+
}
|
|
245
|
+
/* 没有我们的标记 ⇒ 追加到末尾;文件末尾没换行就先补一个,段间留一个空行 */
|
|
246
|
+
const base = text.endsWith('\n') ? text : text + eol;
|
|
247
|
+
const next = `${base}${eol}${marker}${eol}`;
|
|
248
|
+
return { content: next, action: 'appended' };
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* 规划「四个约定文件各要写成什么」—— **不写盘**(dry-run 与真写共用同一份计划)。
|
|
253
|
+
*
|
|
254
|
+
* @param {{dir?:string, markdown:string, files?:Array, exists?:Function, readFile?:Function}} input
|
|
255
|
+
* @returns {Array<{key,path,action,absPath,content,reason}>}
|
|
256
|
+
*/
|
|
257
|
+
export function planAgentFiles(input = {}) {
|
|
258
|
+
const dir = path.resolve(String(input.dir || process.cwd()));
|
|
259
|
+
const files = Array.isArray(input.files) ? input.files : [...AGENT_FILES];
|
|
260
|
+
const brief = extractAgentsBrief(input.markdown);
|
|
261
|
+
const read = input.readFile || ((p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null));
|
|
262
|
+
const rows = [];
|
|
263
|
+
for (const one of files) {
|
|
264
|
+
const absPath = path.join(dir, one.path.split('/').join(path.sep));
|
|
265
|
+
const existing = read(absPath);
|
|
266
|
+
const { content, action } = upsertBriefBlock(existing, brief);
|
|
267
|
+
rows.push({
|
|
268
|
+
key: one.key,
|
|
269
|
+
path: one.path,
|
|
270
|
+
label: one.label,
|
|
271
|
+
absPath,
|
|
272
|
+
action,
|
|
273
|
+
content,
|
|
274
|
+
existed: existing !== null && existing !== undefined,
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
return rows;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* 落盘(只写 `action !== 'unchanged'` 的行)。
|
|
282
|
+
*
|
|
283
|
+
* @param {Array} plan `planAgentFiles()` 的结果
|
|
284
|
+
* @param {{mkdir?:Function, writeFile?:Function}} [io] 单测注入点
|
|
285
|
+
* @returns {{written:string[], skipped:string[]}}
|
|
286
|
+
*/
|
|
287
|
+
export function writeAgentFiles(plan, io = {}) {
|
|
288
|
+
const mkdir = io.mkdir || ((p) => fs.mkdirSync(p, { recursive: true }));
|
|
289
|
+
const writeFile = io.writeFile || ((p, c) => fs.writeFileSync(p, c, 'utf8'));
|
|
290
|
+
const written = [];
|
|
291
|
+
const skipped = [];
|
|
292
|
+
for (const row of plan) {
|
|
293
|
+
if (row.action === 'unchanged') {
|
|
294
|
+
skipped.push(row.path);
|
|
295
|
+
continue;
|
|
296
|
+
}
|
|
297
|
+
mkdir(path.dirname(row.absPath));
|
|
298
|
+
writeFile(row.absPath, row.content);
|
|
299
|
+
written.push(row.path);
|
|
300
|
+
}
|
|
301
|
+
return { written, skipped };
|
|
302
|
+
}
|