dsh-git-push 2.10.4 → 2.12.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/.auditignore +2 -4
- package/README.md +78 -1483
- package/lib/app/audit-api.js +2 -0
- package/lib/app/inject-text.js +0 -1
- package/lib/app/repo-ownership.js +65 -0
- package/lib/app/tool-call.js +6 -2
- package/lib/ast/io-risk-loop.js +1 -1
- package/lib/ast/tokenizer.js +76 -1
- package/lib/ast/treesitter.js +78 -14
- package/lib/audit/audit-file.js +15 -1
- package/lib/audit/collector.js +9 -1
- package/lib/audit/finding.js +8 -1
- package/lib/audit/orchestrate.js +1 -0
- package/lib/audit/ownership.js +46 -0
- package/lib/audit/report-yaml.js +5 -1
- package/lib/audit-rules/audit-rules-comment.yml +0 -68
- package/lib/audit-rules/audit-rules-csharp.yml +82 -0
- package/lib/audit-rules/audit-rules-structure.yml +2 -3
- package/lib/cli/commands-audit.mjs +3 -0
- package/lib/git/push.js +1 -1
- package/lib/rule/loader.js +5 -1
- package/lib/self/index.js +1 -1
- package/lib/skip-dirs.js +6 -3
- package/package.json +6 -1
- package/scripts/bump-version.mjs +163 -0
- package/scripts/doc-tree.mjs +4 -2
- package/scripts/doc-version.mjs +4 -4
- package/scripts/{readme-gen.mjs → version-source.mjs} +8 -153
- package/skills/dev/dsh-git-push.md +3 -11
- package/skills/guide/guide-cli-scripts.md +0 -2
- package/assets/tree-sitter/LICENSE +0 -21
- package/assets/tree-sitter/README.md +0 -69
- package/assets/tree-sitter/VERSIONS.txt +0 -1
- package/assets/tree-sitter/tree-sitter-javascript.wasm +0 -0
- package/assets/tree-sitter/tree-sitter-python.wasm +0 -0
- package/assets/tree-sitter/tree-sitter-typescript.wasm +0 -0
- package/assets/tree-sitter/tree-sitter.js +0 -3980
- package/assets/tree-sitter/tree-sitter.wasm +0 -0
- package/lib/readme-templates/readme.yml +0 -38
- package/lib/vendor/js-yaml/LICENSE +0 -21
- package/lib/vendor/js-yaml/js-yaml.mjs +0 -3073
- package/scripts/scrub-user-wording.mjs +0 -420
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# ============================================================
|
|
2
|
+
# C# 代码审计规则集(首版 · 语言专项)
|
|
3
|
+
# 版本:0.1.0
|
|
4
|
+
# 适用:C# 项目(.cs)
|
|
5
|
+
# 描述:本槽位首版规则。选型依据是真实 C# 语料上的**两档计数**(正则初筛命中 / 精筛后命中),
|
|
6
|
+
# 只收「精筛后仍是真命中且形态可静态确认」的项;靠正则数量堆砌的候选一律不收。
|
|
7
|
+
# 未收清单与理由见 docs/2026-10-29-多语言AST接通实测记录.MD「M3-B 收规则与不收清单」。
|
|
8
|
+
# 口径:exts 只认 .cs;astConfirm 走 token 级行列判定(注释/字符串里的同名文本不算代码)。
|
|
9
|
+
# ============================================================
|
|
10
|
+
|
|
11
|
+
metadata:
|
|
12
|
+
name: "C# 审计规则集(首版 · 语言专项)"
|
|
13
|
+
version: "0.1.0"
|
|
14
|
+
language: "csharp"
|
|
15
|
+
author: "DeepSeek"
|
|
16
|
+
description: "C# 项目语言专用规则(首版:throw ex / 抛通用 Exception / 显式 GC.Collect / lock(this|typeof))"
|
|
17
|
+
last_updated: "2026-10-29"
|
|
18
|
+
|
|
19
|
+
rules:
|
|
20
|
+
# ----- 1. 健壮性 -----
|
|
21
|
+
|
|
22
|
+
- id: csharp/throw-ex
|
|
23
|
+
name: "C# 重抛异常不要用 throw ex"
|
|
24
|
+
category: "robustness"
|
|
25
|
+
severity: "warning"
|
|
26
|
+
dimensions: ["健壮性"]
|
|
27
|
+
description: "`throw ex;` 会把异常栈重置到当前行,原始抛出点丢失;应写 `throw;` 保留栈,或包成带 innerException 的新异常"
|
|
28
|
+
# astConfirm + astConfirmSpan:行级 + **列级**双重判定。
|
|
29
|
+
# 只写 astConfirm 时按「行」判,`const string S = "throw ex;";` 这种行仍是代码行 ⇒ 字符串里的文本会被报出来;
|
|
30
|
+
# 加 astConfirmSpan 后按命中列判(有语法树时用 c_sharp 树,无树时回退 token 列级),才算真排除。
|
|
31
|
+
astConfirm: true
|
|
32
|
+
astConfirmSpan: true
|
|
33
|
+
patterns:
|
|
34
|
+
- "\\bthrow\\s+[A-Za-z_]\\w*\\s*;"
|
|
35
|
+
exts: ["cs"]
|
|
36
|
+
exclude_paths:
|
|
37
|
+
- "test/"
|
|
38
|
+
- "tests/"
|
|
39
|
+
- "examples/"
|
|
40
|
+
- "example/"
|
|
41
|
+
fixable: false
|
|
42
|
+
|
|
43
|
+
- id: csharp/generic-exception
|
|
44
|
+
name: "C# 不要抛通用 Exception"
|
|
45
|
+
category: "robustness"
|
|
46
|
+
severity: "warning"
|
|
47
|
+
dimensions: ["健壮性"]
|
|
48
|
+
description: "抛 `System.Exception` 让调用方无法按类型区分处置,且容易与框架异常混淆;应抛具体异常类型(ArgumentException/InvalidOperationException 或自定义异常)"
|
|
49
|
+
# 只匹配直接 new 通用 Exception 的形态:new ArgumentException(...) 等子类不在命中范围
|
|
50
|
+
# astConfirmSpan:同 throw-ex,字符串/注释里的示例文本按列级排除
|
|
51
|
+
astConfirm: true
|
|
52
|
+
astConfirmSpan: true
|
|
53
|
+
patterns:
|
|
54
|
+
- "throw\\s+new\\s+(?:System\\s*\\.\\s*)?Exception\\s*\\("
|
|
55
|
+
exts: ["cs"]
|
|
56
|
+
exclude_paths:
|
|
57
|
+
- "test/"
|
|
58
|
+
- "tests/"
|
|
59
|
+
- "examples/"
|
|
60
|
+
- "example/"
|
|
61
|
+
fixable: false
|
|
62
|
+
|
|
63
|
+
# ----- 3. 并发安全 -----
|
|
64
|
+
|
|
65
|
+
- id: csharp/lock-on-self-or-type
|
|
66
|
+
name: "C# 不要在 this / typeof(T) 上加锁"
|
|
67
|
+
category: "robustness"
|
|
68
|
+
severity: "warning"
|
|
69
|
+
dimensions: ["健壮性"]
|
|
70
|
+
description: "锁 this 或 typeof(T) 会和外部代码共享同一把锁(外部也能锁同一个对象/类型),易造成死锁与不可控争用;应使用私有 readonly 锁对象"
|
|
71
|
+
astConfirm: true
|
|
72
|
+
astConfirmSpan: true
|
|
73
|
+
patterns:
|
|
74
|
+
- "lock\\s*\\(\\s*this\\s*\\)"
|
|
75
|
+
- "lock\\s*\\(\\s*typeof\\s*\\("
|
|
76
|
+
exts: ["cs"]
|
|
77
|
+
exclude_paths:
|
|
78
|
+
- "test/"
|
|
79
|
+
- "tests/"
|
|
80
|
+
- "examples/"
|
|
81
|
+
- "example/"
|
|
82
|
+
fixable: false
|
|
@@ -31,7 +31,7 @@ decisions:
|
|
|
31
31
|
reason: "现有 docs/(复数)已建立索引习惯,改名纯成本;新增目录一律单数,存量 docs/ 作为历史约定保留"
|
|
32
32
|
- item: "script/ config/ dist/ log/"
|
|
33
33
|
keep: false
|
|
34
|
-
reason: "无构建步骤(源码即产物);配置走 settings 机制 + lib/ 内 yml 规则数据(audit-rules/
|
|
34
|
+
reason: "无构建步骤(源码即产物);配置走 settings 机制 + lib/ 内 yml 规则数据(audit-rules/ 同源部署,不抽顶层)"
|
|
35
35
|
- item: "skills/"
|
|
36
36
|
keep: true
|
|
37
37
|
reason: "DSH 插件特性:注入给 AI 的手册(dsh-git-push.md / dsh-git-push-functions.md / git-workflow-gitpush/),通用规范未覆盖"
|
|
@@ -46,7 +46,7 @@ principles:
|
|
|
46
46
|
- "一致性优先于花哨:同类文件放同目录,同目录命名风格统一"
|
|
47
47
|
- "统一单数:所有功能目录用单数(tool/、test/、doc/、lib/),不用复数(tools/、tests/、docs/、libs/)"
|
|
48
48
|
- "工具与源码同库:cli.mjs 根级 + lib/plugin-tools.js 注册 agent 工具,不建空 tool/ 目录"
|
|
49
|
-
- "规则数据随代码:audit-rules/*.yml
|
|
49
|
+
- "规则数据随代码:audit-rules/*.yml 放 lib/ 子目录(files 白名单 + 相对路径解析依赖)"
|
|
50
50
|
- "最小可用:不预设未来需求,目录按需添加"
|
|
51
51
|
|
|
52
52
|
# ============================================================
|
|
@@ -86,7 +86,6 @@ directory_roles:
|
|
|
86
86
|
- "audit.js - 审计引擎(L0 静态 + 规则执行)"
|
|
87
87
|
- "rule-packs.js - YAML 规则装载/编译"
|
|
88
88
|
- "audit-rules/ - 规则数据(nodejs/frontend/comment/dsh/npm/version/template/private/structure)"
|
|
89
|
-
- "readme-templates/ - README 模板 yml"
|
|
90
89
|
- "plugin-*.js - 装配层(host 等价:工具注册/HTTP/设置/审计服务接线)"
|
|
91
90
|
- "client.js viewer.js- 客户端 UI(DSH 命名空间内)"
|
|
92
91
|
dependencies: "模块间单向依赖、无环(拆分时保证);装配层依赖业务模块,业务模块不依赖装配层"
|
|
@@ -15,6 +15,7 @@ import { readSettings, applySettingsToCfg } from '../app/settings-bridge.js';
|
|
|
15
15
|
import { defaultConfig } from '../client/index.js';
|
|
16
16
|
import { access } from 'node:fs/promises';
|
|
17
17
|
import { join } from 'node:path';
|
|
18
|
+
import { probeRepoOwnership } from '../app/repo-ownership.js';
|
|
18
19
|
|
|
19
20
|
/** 审计 full 扫描 findings 打印条数上限(防刷屏)。 */
|
|
20
21
|
const AUDIT_PRINT_LIMIT = 20;
|
|
@@ -78,6 +79,7 @@ async function runHistoryAuditCmd(root, flags) {
|
|
|
78
79
|
const cfg = cliPluginConfig();
|
|
79
80
|
const { runHistoryAudit } = await import('../audit/history.js');
|
|
80
81
|
const opts = pluginEqualAuditOpts(cfg, flags, { scope: 'full' });
|
|
82
|
+
opts.ownership = probeRepoOwnership(root); // 与插件工具同参:隐私规则只对自有仓库生效
|
|
81
83
|
const weights = pluginEqualWeights(cfg, flags);
|
|
82
84
|
const r = await runHistoryAudit(root || '.', {
|
|
83
85
|
since: flags.since, until: flags.until, outDir: flags.out,
|
|
@@ -96,6 +98,7 @@ async function runStandardAudit(root, flags) {
|
|
|
96
98
|
const cfg = cliPluginConfig();
|
|
97
99
|
const full = flags.full === true || !(await pathExists(join(root || '.', '.git')));
|
|
98
100
|
const opts = pluginEqualAuditOpts(cfg, flags, { scope: full ? 'full' : 'diff' });
|
|
101
|
+
opts.ownership = probeRepoOwnership(root); // 与插件工具同参:隐私规则只对自有仓库生效
|
|
99
102
|
const weights = pluginEqualWeights(cfg, flags);
|
|
100
103
|
const auditResult = full ? await auditFull(root, opts) : await auditWithScope(root, opts);
|
|
101
104
|
const quality = scoreQuality(auditResult.findings, weights, { files: auditResult.files });
|
package/lib/git/push.js
CHANGED
|
@@ -426,7 +426,7 @@ export function readmeCheckHint(repoPath) {
|
|
|
426
426
|
const hasReadme = ['README.md', 'readme.md', 'README', 'readme'].some((n) => existsSync(join(repoPath, n)));
|
|
427
427
|
return hasReadme
|
|
428
428
|
? { needed: true, hasReadme: true, hint: '提交前核对 README:功能表/版本记录/用法与本次改动一致,过时先改 README 再提交' }
|
|
429
|
-
: { needed: true, hasReadme: false, hint: '仓库无 README
|
|
429
|
+
: { needed: true, hasReadme: false, hint: '仓库无 README,提交前先补(按 README 使用手册规范手工撰写)' };
|
|
430
430
|
}
|
|
431
431
|
|
|
432
432
|
/**
|
package/lib/rule/loader.js
CHANGED
|
@@ -9,7 +9,11 @@ import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs';
|
|
|
9
9
|
import { normalizeScopeRules } from './scope.js';
|
|
10
10
|
import { join, dirname } from 'node:path';
|
|
11
11
|
import { fileURLToPath } from 'node:url';
|
|
12
|
-
|
|
12
|
+
// js-yaml 走 npm 依赖(仓库内不保存副本)。
|
|
13
|
+
// 这里**故意用静态 import**:规则加载是启动关键路径,依赖没装上就应当在模块加载期
|
|
14
|
+
// 抛 ERR_MODULE_NOT_FOUND(错误里带包名,够响亮),而不是被 try/catch 吞成「0 条规则」
|
|
15
|
+
// 继续跑——静默无规则比启动失败更危险(口径见 docs/2026-10-28-弃零依赖引入npm与AST优先规则方案.MD D5)。
|
|
16
|
+
import { load as yamlLoad } from 'js-yaml';
|
|
13
17
|
|
|
14
18
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
15
19
|
export const RULE_YAML_DIR = join(__dirname, '..', 'audit-rules');
|
package/lib/self/index.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
11
|
|
|
12
|
-
export const VERSION = '2.
|
|
12
|
+
export const VERSION = '2.12.3'; // 2.12.3:M4 移除 vendored 包袱:删除 assets/tree-sitter(3.7MB,含 runtime js+wasm 与 3 个语法)与 lib/vendor/js-yaml(108KB),运行时统一走 npm 依赖;配套删掉已成死代码的迁移期兜底、把「vendored 运行时已落库」断言改为「npm 包可解析且版本锁定 0.25.10」、订正三处指向已删路径的注释与 .auditignore 条目。发布体积 1.4MB/6.5MB/291 → 911.4kB/2.6MB/281。。历史:2.12.2:M3:新建 audit-rules-csharp.yml,按实证口径收 3 条 C# 规则(throw-ex 4/4、generic-exception 38→37、lock-on-self-or-type 2/2,全走 astConfirm+astConfirmSpan 列级精筛);评估后不收 11 项并记入文档(含第一版误收又撤回的 GC.Collect)。语料 findings 453→496、blocker 不变。另修文档计数口径:澄清 168 条为声明数、默认实际加载 164 条(i18n 槽位 disabled、template 槽位需显式开启)。。。2.12.1:修 C# 插值串被当硬编码文本(M3 前置阻塞):tokenizer 识别 $\"…\" / $@\"…\" / @$\"…\" 为插值串、产出 tmpl(与 JS 模板串同口径),洞内按花括号深度判定并跳过嵌套字符串,避免在洞内引号处截断;@\"…\"(verbatim 不插值)仍为 str 照常统计。实测 C# 语料 no-repeated-hardcoded-literals 41→31(少掉的 10 条全是插值表达式,如 {musicId}.csv、<error: {ex.Message}>),4 条纯字面量真命中(Change Joint Limits / Open File / Position Weight / Mouse X)仍报;本仓库自身审计 889 条与改前完全一致(JS 侧零回归)。新增 test-repeated-strings-cs.mjs(5 例,回退 tokenizer 即 3 红)。。
|
|
13
13
|
// 实测后果:该目录有 package.json ⇒ npm 去打包整棵 DSH 树、输出 2.1MB > spawnSync 默认 maxBuffer 1MB ⇒ ENOBUFS(npm_publish 的体检与真发全部失败);
|
|
14
14
|
// 该目录没有 package.json 时报 ENOENT。现 publish 的两个调用点显式传 cwd=目标包目录,并给 runNpm 加 16MB maxBuffer。
|
|
15
15
|
// 2.8.3:文案修正——「零改动 / 无新提交」明确为**正常成功路径**(注入用法、工具描述、README、skill 同批改),并修 job 输出自相矛盾(cleanSkipCommit 路径补 committed:false,不再显示「已提交,未推送」)
|
package/lib/skip-dirs.js
CHANGED
|
@@ -10,13 +10,16 @@
|
|
|
10
10
|
* 白名单(gitignore negation)不受影响:collector walk 对「被忽略目录」按前缀跳过,
|
|
11
11
|
* 但 gitignore 白名单恢复的目录仍会进入(黑名单初筛 + 白名单补充)。
|
|
12
12
|
*
|
|
13
|
-
* 消费方:lib/audit/collector.js(审计文件收集)、lib/git/sensitive.js
|
|
14
|
-
* scripts/scrub-user-wording.mjs(沟通措辞清洗)。
|
|
13
|
+
* 消费方:lib/audit/collector.js(审计文件收集)、lib/git/sensitive.js(敏感扫描)。
|
|
15
14
|
*/
|
|
16
15
|
import { existsSync, readFileSync, readdirSync } from 'node:fs';
|
|
17
16
|
import { join, dirname } from 'node:path';
|
|
18
17
|
import { fileURLToPath } from 'node:url';
|
|
19
|
-
|
|
18
|
+
// js-yaml 走 npm 依赖(仓库内不保存副本)。
|
|
19
|
+
// 这里**故意用静态 import**:规则加载是启动关键路径,依赖没装上就应当在模块加载期
|
|
20
|
+
// 抛 ERR_MODULE_NOT_FOUND(错误里带包名,够响亮),而不是被 try/catch 吞成「0 条规则」
|
|
21
|
+
// 继续跑——静默无规则比启动失败更危险(口径见 docs/2026-10-28-弃零依赖引入npm与AST优先规则方案.MD D5)。
|
|
22
|
+
import { load as yamlLoad } from 'js-yaml';
|
|
20
23
|
|
|
21
24
|
/** 硬编码基线:只许这两个(勿改)。 */
|
|
22
25
|
export const SKIP_DIRS = new Set(['node_modules', '.git']);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-git-push",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.12.3",
|
|
4
4
|
"description": "DSH git 自动提交推送插件——统一函数入口架构(规则/审计/git/自身/侧边栏/评分/豁免/上下文/HTTP/测试十大总入口)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -92,5 +92,10 @@
|
|
|
92
92
|
"check": "node scripts/check.mjs",
|
|
93
93
|
"scan-version": "node scripts/scan-version.mjs",
|
|
94
94
|
"check:drift": "node scripts/doc-drift.mjs"
|
|
95
|
+
},
|
|
96
|
+
"dependencies": {
|
|
97
|
+
"js-yaml": "4.1.0",
|
|
98
|
+
"tree-sitter-wasms": "0.1.13",
|
|
99
|
+
"web-tree-sitter": "0.25.10"
|
|
95
100
|
}
|
|
96
101
|
}
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* dsh-git-push — 一键版本升版(bump-version)
|
|
4
|
+
*
|
|
5
|
+
* 为什么要有这个脚本:版本号散在三处手工同步,每次发版都要手改
|
|
6
|
+
* ① `package.json` 的 version
|
|
7
|
+
* ② `lib/self/index.js` 的 `export const VERSION = '<v>'; // <v>:说明。历史:…`
|
|
8
|
+
* ③ `docs/releases.json` 新增一条 `<v>: "说明"`
|
|
9
|
+
* 少改一处就会被 doc-version / version-drift 门禁判为漂移,而这两处还各带长文本
|
|
10
|
+
* (VERSION 行还挂着历史链),手改既慢又容易写坏引号、破坏 JSON。
|
|
11
|
+
* 第 4 处(README 版本表 / CHANGELOG)已由 doc-version.mjs 从上面两处生成,无需手改。
|
|
12
|
+
*
|
|
13
|
+
* 用法:
|
|
14
|
+
* node scripts/bump-version.mjs --message "本次做了什么" # 预览(默认 dry-run)
|
|
15
|
+
* node scripts/bump-version.mjs --message "…" --apply # 真写盘
|
|
16
|
+
* node scripts/bump-version.mjs --to 2.11.0 --message "…" --apply # 指定版本(默认 patch +1)
|
|
17
|
+
* node scripts/bump-version.mjs --message-file /tmp/msg.txt --apply
|
|
18
|
+
*
|
|
19
|
+
* 约定:
|
|
20
|
+
* · **默认 dry-run**——只打印将要改动的三处(旧值 → 新值),不落盘;确认无误再加 --apply。
|
|
21
|
+
* (与 npm_publish / install-plugin 同口径:有副作用的动作先看预览再执行)
|
|
22
|
+
* · `--message` 必填:发版说明不能凭空生成,属于「人写内容」,脚本只负责把它同步到三处。
|
|
23
|
+
* · VERSION 行的历史链保留最近 2 个版本摘要,避免注释无限变长(沿用既有风格)。
|
|
24
|
+
* · 写完自动重生成版本文档(doc-version apply / doc-func apply / doc-tree sync+apply),
|
|
25
|
+
* 因为版本号一变,CHANGELOG 与函数索引必须跟着走,否则门禁立刻报漂移。
|
|
26
|
+
*/
|
|
27
|
+
import { readFileSync, writeFileSync } from 'node:fs';
|
|
28
|
+
import { join, dirname } from 'node:path';
|
|
29
|
+
import { fileURLToPath } from 'node:url';
|
|
30
|
+
import { execFileSync } from 'node:child_process';
|
|
31
|
+
|
|
32
|
+
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
|
|
33
|
+
const PKG = join(ROOT, 'package.json');
|
|
34
|
+
const SELF = join(ROOT, 'lib', 'self', 'index.js');
|
|
35
|
+
const RELEASES = join(ROOT, 'docs', 'releases.json');
|
|
36
|
+
|
|
37
|
+
/** 解析命令行参数(只认 --flag value 与布尔 --apply)。 */
|
|
38
|
+
function parseArgs(argv) {
|
|
39
|
+
const out = { apply: false, to: '', message: '', messageFile: '' };
|
|
40
|
+
for (let i = 0; i < argv.length; i++) {
|
|
41
|
+
const a = argv[i];
|
|
42
|
+
if (a === '--apply') { out.apply = true; continue; }
|
|
43
|
+
if (a === '--message' || a === '-m') { out.message = argv[++i] || ''; continue; }
|
|
44
|
+
if (a === '--message-file') { out.messageFile = argv[++i] || ''; continue; }
|
|
45
|
+
if (a === '--to') { out.to = argv[++i] || ''; continue; }
|
|
46
|
+
}
|
|
47
|
+
return out;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const fail = (msg) => { console.error('✗ ' + msg); process.exit(1); };
|
|
51
|
+
|
|
52
|
+
/** 语义化版本比较:a < b 返回负。只支持 x.y.z。 */
|
|
53
|
+
function cmpVer(a, b) {
|
|
54
|
+
const pa = String(a).split('.').map(Number);
|
|
55
|
+
const pb = String(b).split('.').map(Number);
|
|
56
|
+
for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
|
|
57
|
+
return 0;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** patch +1:默认每次提交升第三位(version-discipline 的既有口径)。 */
|
|
61
|
+
function bumpPatch(v) {
|
|
62
|
+
const [x, y, z] = String(v).split('.').map(Number);
|
|
63
|
+
return `${x}.${y}.${(z || 0) + 1}`;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function readJson(p) {
|
|
67
|
+
try { return JSON.parse(readFileSync(p, 'utf8')); } catch (e) { fail(`${p} 解析失败:${e.message}`); }
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* 拼新的 VERSION 行。
|
|
72
|
+
* 旧注释形如:`2.10.4:本次说明。历史:2.10.3:更早说明。` → 把「本次说明」降级进历史链,
|
|
73
|
+
* 只保留最近 2 条,避免每版都把整串历史再抄一遍(实测 2.9.x 之后该行已接近不可读)。
|
|
74
|
+
*/
|
|
75
|
+
function buildVersionLine(oldLine, newVer, oldVer, message) {
|
|
76
|
+
const m = /export const VERSION = '([^']+)';\s*\/\/(.*)$/.exec(oldLine);
|
|
77
|
+
const oldComment = m ? m[2].trim() : '';
|
|
78
|
+
// 旧版本的「本次说明」= 历史链之前的那一段
|
|
79
|
+
const histIdx = oldComment.indexOf('历史:');
|
|
80
|
+
const oldMain = (histIdx >= 0 ? oldComment.slice(0, histIdx) : oldComment).replace(/^[\d.]+\s*[::]\s*/, '').trim();
|
|
81
|
+
const oldHist = histIdx >= 0 ? oldComment.slice(histIdx + '历史:'.length).trim() : '';
|
|
82
|
+
// 历史链:新压入的旧版摘要 + 原有最近 1 条
|
|
83
|
+
const prev = oldMain ? [`${oldVer}:${oldMain}`] : [];
|
|
84
|
+
const kept = oldHist ? oldHist.split(/。\s*(?=[\d.]+:)/).slice(0, 1).map((s) => s.replace(/。$/, '')) : [];
|
|
85
|
+
const chain = [...prev, ...kept].join('。');
|
|
86
|
+
const comment = `${newVer}:${message}。` + (chain ? `历史:${chain}。` : '');
|
|
87
|
+
return `export const VERSION = '${newVer}'; // ${comment}`;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const args = parseArgs(process.argv.slice(2));
|
|
91
|
+
const pkg = readJson(PKG);
|
|
92
|
+
const cur = String(pkg.version || '');
|
|
93
|
+
const target = args.to || bumpPatch(cur);
|
|
94
|
+
let message = args.message;
|
|
95
|
+
if (args.messageFile) {
|
|
96
|
+
try { message = readFileSync(args.messageFile, 'utf8').trim(); } catch (e) { fail(`--message-file 读取失败:${e.message}`); }
|
|
97
|
+
}
|
|
98
|
+
if (!/^\d+\.\d+\.\d+$/.test(target)) fail(`版本号必须为 x.y.z:${target}`);
|
|
99
|
+
if (cmpVer(target, cur) <= 0) fail(`目标版本 ${target} 必须大于当前 ${cur}`);
|
|
100
|
+
if (!message) fail('缺少 --message(发版说明需人写;或从 --message-file 读取)');
|
|
101
|
+
|
|
102
|
+
const releases = readJson(RELEASES);
|
|
103
|
+
if (releases[target]) fail(`docs/releases.json 已存在 ${target} 条目(不要重复升版)`);
|
|
104
|
+
|
|
105
|
+
const selfSrc = readFileSync(SELF, 'utf8');
|
|
106
|
+
const selfLines = selfSrc.split('\n');
|
|
107
|
+
const vi = selfLines.findIndex((l) => /^export const VERSION = '/.test(l));
|
|
108
|
+
if (vi < 0) fail('lib/self/index.js 未找到 VERSION 行');
|
|
109
|
+
const oldLine = selfLines[vi];
|
|
110
|
+
const newLine = buildVersionLine(oldLine, target, cur, message);
|
|
111
|
+
|
|
112
|
+
// ── 预览(默认 dry-run)
|
|
113
|
+
console.log(`升版:${cur} → ${target}${args.apply ? '(--apply 真写盘)' : '(dry-run,未写盘)'}`);
|
|
114
|
+
console.log('\n① package.json');
|
|
115
|
+
console.log(` - "version": "${cur}"`);
|
|
116
|
+
console.log(` + "version": "${target}"`);
|
|
117
|
+
console.log('\n② lib/self/index.js(VERSION 行)');
|
|
118
|
+
console.log(` - ${oldLine.slice(0, 90)}…`);
|
|
119
|
+
console.log(` + ${newLine.slice(0, 90)}…`);
|
|
120
|
+
console.log('\n③ docs/releases.json');
|
|
121
|
+
console.log(` + "${target}": "${message.slice(0, 70)}${message.length > 70 ? '…' : ''}"`);
|
|
122
|
+
console.log('\n④ 随后自动重生成:docs/CHANGELOG.md(doc-version)、docs/FUNCTIONS.md(doc-func)、tree-doc.json(doc-tree)');
|
|
123
|
+
|
|
124
|
+
if (!args.apply) {
|
|
125
|
+
console.log('\n确认无误后追加 --apply 才会写盘。');
|
|
126
|
+
process.exit(0);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// ── 写盘
|
|
130
|
+
// 注意:本仓库在 CIFS 挂载上,write/edit 工具会因 chmod 报 EPERM;脚本用 fs 直接写
|
|
131
|
+
// 普通文件(不触发 chmod),这正是把它脚本化的额外收益。
|
|
132
|
+
const newPkgText = readFileSync(PKG, 'utf8').replace(
|
|
133
|
+
/("version"\s*:\s*")[^"]+(")/,
|
|
134
|
+
`$1${target}$2`,
|
|
135
|
+
);
|
|
136
|
+
if (newPkgText === readFileSync(PKG, 'utf8')) fail('package.json 的 version 未替换成功(正则未命中)');
|
|
137
|
+
writeFileSync(PKG, newPkgText);
|
|
138
|
+
|
|
139
|
+
selfLines[vi] = newLine;
|
|
140
|
+
writeFileSync(SELF, selfLines.join('\n'));
|
|
141
|
+
|
|
142
|
+
const merged = { ...releases };
|
|
143
|
+
merged[target] = message;
|
|
144
|
+
// 按语义化版本排序,保持文件可读(原文件即按版本升序)
|
|
145
|
+
const sorted = {};
|
|
146
|
+
for (const k of Object.keys(merged).sort(cmpVer)) sorted[k] = merged[k];
|
|
147
|
+
writeFileSync(RELEASES, JSON.stringify(sorted, null, 2) + '\n');
|
|
148
|
+
|
|
149
|
+
console.log('\n✔ 三处已写入,重生成派生文档…');
|
|
150
|
+
for (const cmd of [
|
|
151
|
+
['scripts/doc-version.mjs', ['apply']],
|
|
152
|
+
['scripts/doc-func.mjs', ['apply']],
|
|
153
|
+
['scripts/doc-tree.mjs', ['sync']],
|
|
154
|
+
['scripts/doc-tree.mjs', ['apply']],
|
|
155
|
+
]) {
|
|
156
|
+
try {
|
|
157
|
+
execFileSync(process.execPath, [join(ROOT, cmd[0]), ...cmd[1]], { cwd: ROOT, stdio: 'pipe', encoding: 'utf8' });
|
|
158
|
+
console.log(` ✔ ${cmd[0]} ${cmd[1].join(' ')}`);
|
|
159
|
+
} catch (e) {
|
|
160
|
+
console.error(` ✗ ${cmd[0]} 失败:${String(e?.stdout || e?.stderr || e).split('\n')[0]}`);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
console.log(`\n完成:${cur} → ${target}。请跑 node scripts/doc-version.mjs check 与全量回归确认门禁绿。`);
|
package/scripts/doc-tree.mjs
CHANGED
|
@@ -300,8 +300,10 @@ function applyBlock(text, newTree) {
|
|
|
300
300
|
|
|
301
301
|
/* ───────────────────────── check:漂移对比 ───────────────────────── */
|
|
302
302
|
|
|
303
|
-
export function checkDrift({ readmePath =
|
|
304
|
-
|
|
303
|
+
export function checkDrift({ readmePath = '', root = ROOT } = {}) {
|
|
304
|
+
// 树宿主可迁移(README 拆出后落到 docs/ 下带标记块的 md)⇒ 与 apply 同用 resolveTargetMd
|
|
305
|
+
// 自动探测,而不是写死 README。显式传 readmePath 时行为不变。
|
|
306
|
+
const text = readReadme(resolveTargetMd(root, readmePath));
|
|
305
307
|
const block = findBlock(text);
|
|
306
308
|
const real = buildTreeText(gitLsFiles(root), loadMapping(root), basename(root));
|
|
307
309
|
const map = loadMapping(root);
|
package/scripts/doc-version.mjs
CHANGED
|
@@ -6,9 +6,9 @@
|
|
|
6
6
|
* 分体式文档三兄弟之一(doc-tree 文件树 / doc-func 函数列表 / doc-version 版本列表)。
|
|
7
7
|
* 版本表数据源 = `docs/releases.json`(每版一行说明)+ 版本真源文件(package.json 等)
|
|
8
8
|
* + `version-metrics.json`(可选量化记录);**不读 git log**(2026-10-16 改,原因见
|
|
9
|
-
*
|
|
9
|
+
* version-source.mjs 的 buildReadmeVersionTable 注释)。
|
|
10
10
|
* 写入宿主 md(README 有 dshgp-version 标记块用 README,否则 docs/ 带块 md)。
|
|
11
|
-
* 复用
|
|
11
|
+
* 复用 version-source.mjs 的 buildReadmeVersionTable(版本聚合逻辑单一事实源)。
|
|
12
12
|
*
|
|
13
13
|
* 用法:
|
|
14
14
|
* node scripts/doc-version.mjs gen [--root <项目根>] # 打印版本表文本
|
|
@@ -19,7 +19,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs';
|
|
|
19
19
|
import { join, resolve, relative, basename, dirname } from 'node:path';
|
|
20
20
|
import { fileURLToPath } from 'node:url';
|
|
21
21
|
import { findMarkedHostMd } from './doc-tree.mjs';
|
|
22
|
-
import { buildReadmeVersionTable, detectVersionSource, projectVersionOf, readReleases, VERSION_SOURCES } from './
|
|
22
|
+
import { buildReadmeVersionTable, detectVersionSource, projectVersionOf, readReleases, VERSION_SOURCES } from './version-source.mjs';
|
|
23
23
|
|
|
24
24
|
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
25
25
|
const MARKER = 'dshgp-version';
|
|
@@ -27,7 +27,7 @@ const MARK_START = `<!-- ${MARKER}:start -->`;
|
|
|
27
27
|
const MARK_END = `<!-- ${MARKER}:end -->`;
|
|
28
28
|
|
|
29
29
|
/**
|
|
30
|
-
*
|
|
30
|
+
* 版本源探测与读取**在 scripts/version-source.mjs**(版本表生成与版本源同源,避免两处各写一份)。
|
|
31
31
|
* 这里只做再导出,保持旧调用方的 import 路径不变。
|
|
32
32
|
*
|
|
33
33
|
* ⚠️ 2026-10-16 起:版本表**不再读 git log**(`detectVersionSource` 不再回退 'git-log')——
|
|
@@ -1,65 +1,16 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
1
|
/**
|
|
3
|
-
*
|
|
2
|
+
* 版本源探测与版本表聚合(供 doc-version 门禁生成 CHANGELOG/README 版本表使用)。
|
|
4
3
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* 来历:原先与 README 模板渲染混在 scripts/readme-gen.mjs 里;README 生成能力已作废(README 改由
|
|
5
|
+
* readme-spec 手工维护、不再按模板渲染),故把**仍在关键路径上**的版本源逻辑单独拆出,
|
|
6
|
+
* 模板渲染/TOC/genReadme 一并删除,避免死代码继续挂在门禁脚本的依赖链上。
|
|
7
7
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* 缺省只打印生成内容(README 模板文本),--write 才落盘。
|
|
11
|
-
*
|
|
12
|
-
* 模板优先级:--template 指定 > <repo>/template/README.md > 本脚本附带的 readme.yml > 内置兜底。
|
|
8
|
+
* 纯读取:只读 package.json 等版本文件、docs/releases.json、version-metrics.json,
|
|
9
|
+
* 不写盘、不改仓库(写入由 doc-version.mjs 负责)。
|
|
13
10
|
*/
|
|
14
|
-
import { existsSync, readFileSync
|
|
15
|
-
import {
|
|
16
|
-
import { fileURLToPath } from 'node:url';
|
|
11
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
12
|
+
import { join } from 'node:path';
|
|
17
13
|
import { spawnSync } from 'node:child_process';
|
|
18
|
-
import { load as yamlLoad } from '../lib/vendor/js-yaml/js-yaml.mjs';
|
|
19
|
-
|
|
20
|
-
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
21
|
-
/** 插件根(scripts/readme-gen.mjs → ../../) */
|
|
22
|
-
const PLUGIN_ROOT = join(__dirname, '..');
|
|
23
|
-
/** yml 模板目录(复用插件 lib/readme-templates,脚本相对路径 = ../lib/readme-templates) */
|
|
24
|
-
const README_TEMPLATE_YML_DIR = join(__dirname, '..', 'lib', 'readme-templates');
|
|
25
|
-
|
|
26
|
-
/** 内置兜底模板 */
|
|
27
|
-
const DEFAULT_README_TEMPLATE = `# {{name}}
|
|
28
|
-
|
|
29
|
-
> {{description}}
|
|
30
|
-
|
|
31
|
-
## 目录
|
|
32
|
-
|
|
33
|
-
{{toc}}
|
|
34
|
-
|
|
35
|
-
## 架构设计
|
|
36
|
-
|
|
37
|
-
<!-- INSERT: 项目核心架构说明(分层/组件/模块/关键设计决策) -->
|
|
38
|
-
|
|
39
|
-
## 文件目录结构及作用
|
|
40
|
-
|
|
41
|
-
<!-- INSERT: 关键文件/目录清单 + 每项作用说明 -->
|
|
42
|
-
|
|
43
|
-
## 启动脚本
|
|
44
|
-
|
|
45
|
-
<!-- INSERT: start.sh 用法:start / stop / restart / status,含端口与环境要求 -->
|
|
46
|
-
|
|
47
|
-
## API 总览
|
|
48
|
-
|
|
49
|
-
<!-- INSERT: | 方法 | 路径 | 说明 | -->
|
|
50
|
-
|
|
51
|
-
## 版本列表
|
|
52
|
-
|
|
53
|
-
{{versionTable}}
|
|
54
|
-
|
|
55
|
-
## 注意事项
|
|
56
|
-
|
|
57
|
-
<!-- INSERT: 踩过的坑、边界条件、依赖环境要求、已知限制 -->
|
|
58
|
-
|
|
59
|
-
## 开发计划 / 疑难杂症
|
|
60
|
-
|
|
61
|
-
<!-- INSERT: 待办功能、已知问题、未解决的技术难题 -->
|
|
62
|
-
`;
|
|
63
14
|
|
|
64
15
|
/** runGit 精简单机版(git log 取提交标题,供版本表聚合)。 */
|
|
65
16
|
function runGit(args, { cwd = '' } = {}) {
|
|
@@ -72,61 +23,6 @@ function runGit(args, { cwd = '' } = {}) {
|
|
|
72
23
|
}
|
|
73
24
|
|
|
74
25
|
/** 渲染 yml 模板({ header, sections })→ markdown 模板文本(占位符原样保留)。 */
|
|
75
|
-
export function renderReadmeTemplateYml(data) {
|
|
76
|
-
const rawHeader = data?.header;
|
|
77
|
-
const header = (typeof rawHeader === 'string' ? rawHeader
|
|
78
|
-
: (rawHeader && typeof rawHeader === 'object') ? [rawHeader.title, rawHeader.intro].filter(Boolean).join('\n\n')
|
|
79
|
-
: '').trim();
|
|
80
|
-
const sections = Array.isArray(data?.sections) ? data.sections : [];
|
|
81
|
-
const parts = [];
|
|
82
|
-
if (header) parts.push(header);
|
|
83
|
-
for (const s of sections) {
|
|
84
|
-
const title = String(s?.title || '').trim();
|
|
85
|
-
if (!title) continue;
|
|
86
|
-
parts.push(`## ${title}\n\n${String(s?.body ?? '')}`);
|
|
87
|
-
}
|
|
88
|
-
return parts.join('\n\n') + '\n';
|
|
89
|
-
}
|
|
90
|
-
|
|
91
|
-
/** 装载 yml 模板(templates/*.yml 首个可用),失败返回 null。 */
|
|
92
|
-
export function loadReadmeTemplateYml(dir = README_TEMPLATE_YML_DIR) {
|
|
93
|
-
let names = [];
|
|
94
|
-
try { names = readdirSync(dir); } catch { return null; }
|
|
95
|
-
const file = names.filter((f) => /\.ya?ml$/i.test(f)).sort()[0];
|
|
96
|
-
if (!file) return null;
|
|
97
|
-
const full = join(dir, file);
|
|
98
|
-
try {
|
|
99
|
-
const parsedYml = yamlLoad(readFileSync(full, 'utf8'));
|
|
100
|
-
if (!parsedYml || typeof parsedYml !== 'object') return null;
|
|
101
|
-
return { file: full, data: parsedYml, template: renderReadmeTemplateYml(parsedYml) };
|
|
102
|
-
} catch { return null; }
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
/** 解析 README 模板:显式模板 > <repo>/template/README.md > yml > 内置兜底。 */
|
|
106
|
-
export function resolveReadmeTemplate({ repoPath = '', explicit = '' } = {}) {
|
|
107
|
-
if (explicit) {
|
|
108
|
-
try { const t = readFileSync(explicit, 'utf8'); if (t.trim()) return { source: explicit, template: t }; } catch { /* 忽略 */ }
|
|
109
|
-
}
|
|
110
|
-
for (const cand of [join(repoPath, 'template', 'README.md')]) {
|
|
111
|
-
try { if (existsSync(cand)) { const t = readFileSync(cand, 'utf8'); if (t.trim()) return { source: cand, template: t }; } } catch { /* 忽略 */ }
|
|
112
|
-
}
|
|
113
|
-
const yml = loadReadmeTemplateYml();
|
|
114
|
-
if (yml) return { source: yml.file, template: yml.template, yml: yml.data };
|
|
115
|
-
return { source: 'builtin', template: DEFAULT_README_TEMPLATE };
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
/** 从模板自动生成目录(## 标题 → 锚点,'目录' 不列)。 */
|
|
119
|
-
export function tocFromTemplate(template) {
|
|
120
|
-
const titles = [];
|
|
121
|
-
for (const line of String(template || '').split('\n')) {
|
|
122
|
-
const match = line.match(/^##\s+(.+?)\s*$/);
|
|
123
|
-
if (!match) continue;
|
|
124
|
-
const t = match[1].trim();
|
|
125
|
-
if (t === '目录') continue;
|
|
126
|
-
titles.push(t);
|
|
127
|
-
}
|
|
128
|
-
return titles.map((t) => `- [${t}](#${t})`).join('\n');
|
|
129
|
-
}
|
|
130
26
|
|
|
131
27
|
const VERSION_RE = /\bv?(\d+)\.(\d+)\.(\d+)\b/;
|
|
132
28
|
|
|
@@ -275,44 +171,3 @@ export function buildReadmeVersionTable(repoPath) {
|
|
|
275
171
|
}
|
|
276
172
|
|
|
277
173
|
/** 生成 README 文本(不落盘)。 */
|
|
278
|
-
export function genReadme({ repoPath, template = '' } = {}) {
|
|
279
|
-
let name = '项目名', description = '一句话简介', version = null;
|
|
280
|
-
try {
|
|
281
|
-
const pkg = JSON.parse(readFileSync(join(repoPath, 'package.json'), 'utf8'));
|
|
282
|
-
if (pkg.name) name = pkg.name;
|
|
283
|
-
if (pkg.description) description = pkg.description;
|
|
284
|
-
if (pkg.version) version = pkg.version;
|
|
285
|
-
} catch { /* 非 npm 用默认 */ }
|
|
286
|
-
const vtable = toString(buildReadmeVersionTable(repoPath));
|
|
287
|
-
const { source, template: tpl } = resolveReadmeTemplate({ repoPath, template });
|
|
288
|
-
const toc = tocFromTemplate(tpl);
|
|
289
|
-
const content = tpl
|
|
290
|
-
.replaceAll('{{name}}', name).replaceAll('{{description}}', description)
|
|
291
|
-
.replaceAll('{{version}}', version || '').replaceAll('{{toc}}', toc)
|
|
292
|
-
.replaceAll('{{versionTable}}', vtable);
|
|
293
|
-
return { ok: true, content, name, description, version, templateSource: source, versionTable: buildReadmeVersionTable(repoPath), toc };
|
|
294
|
-
}
|
|
295
|
-
|
|
296
|
-
function toString(arr) { return Array.isArray(arr) ? arr.join('\n') : String(arr || ''); }
|
|
297
|
-
|
|
298
|
-
function main(argv) {
|
|
299
|
-
const args = [...argv];
|
|
300
|
-
const repoPath = args.find((a) => !a.startsWith('--'));
|
|
301
|
-
const writeIdx = args.indexOf('--write');
|
|
302
|
-
const writePath = writeIdx >= 0 ? args[writeIdx + 1] : '';
|
|
303
|
-
const tplIdx = args.indexOf('--template');
|
|
304
|
-
const template = tplIdx >= 0 ? args[tplIdx + 1] : '';
|
|
305
|
-
if (!repoPath) { console.error('用法: node scripts/readme-gen.mjs <repoPath> [--write <path>] [--template <path>]'); process.exit(1); }
|
|
306
|
-
const r = genReadme({ repoPath, template });
|
|
307
|
-
if (!r.ok) { console.error(r.error); process.exit(1); }
|
|
308
|
-
if (writePath) { try { writeFileSync(writePath, r.content, 'utf8'); console.error(`已生成: ${writePath}(模板:${r.templateSource})`); } catch (e) { console.error('写入失败:', e?.message); process.exit(1); } }
|
|
309
|
-
else process.stdout.write(r.content);
|
|
310
|
-
}
|
|
311
|
-
|
|
312
|
-
// 仅作为 CLI 直接运行时执行 main;作为模块 import 供测试时不自动跑(用 import.meta 判断是否入口)
|
|
313
|
-
if (process.argv[1] && import.meta.url && String(import.meta.url).startsWith('file:')) {
|
|
314
|
-
try {
|
|
315
|
-
const entry = fileURLToPath(import.meta.url);
|
|
316
|
-
if (entry === String(process.argv[1])) main(process.argv.slice(2));
|
|
317
|
-
} catch { /* 非 file url 不做入口判断 */ }
|
|
318
|
-
}
|
|
@@ -227,17 +227,10 @@ pnpm add github:EIGHTfs/dsh-git-push#<commit>
|
|
|
227
227
|
|
|
228
228
|
**约定**:README 不直接内嵌长文档(版本表/文件树/函数列表),改为「## 分体式文档」节链接引用。三脚本命令统一 `gen`(打印)/ `apply`(写宿主,自动探测带标记块的 md)/ `check`(查漂移);宿主探测复用公共函数 `findMarkedHostMd(root, marker)`(优先 README,README 无标记块时扫描 .md 找含块文件)。
|
|
229
229
|
|
|
230
|
-
### 9.2 README
|
|
230
|
+
### 9.2 README 生成(能力已下线)
|
|
231
231
|
|
|
232
|
-
`git_gen_readme`
|
|
233
|
-
|
|
234
|
-
```bash
|
|
235
|
-
node scripts/readme-gen.mjs <repoPath> [--write <path>] [--template <path>]
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
- 只打印不写 → 不传 `--write`;`--write README.md` 才落盘
|
|
239
|
-
- `--template` 指定自定义模板(缺省 `lib/readme-templates/readme.yml`);占位符 `{{name}} {{description}} {{version}} {{toc}} {{versionTable}}`
|
|
240
|
-
- 插件不再内置生成能力,push.js 的「仓库无 README」提示引用此脚本
|
|
232
|
+
`git_gen_readme` 工具与模板渲染脚本均已移除:README 由使用手册规范手工维护,不再按模板生成。
|
|
233
|
+
「仓库无 README」之类的提示保留,但不再指向任何生成脚本。
|
|
241
234
|
|
|
242
235
|
### 9.3 doc-tree 自动探测 md(2026-09-29)
|
|
243
236
|
|
|
@@ -272,7 +265,6 @@ node scripts/readme-gen.mjs <repoPath> [--write <path>] [--template <path>]
|
|
|
272
265
|
| `git_remote_create` | **`repo`**、`visibility?`(默认 private)、`dryRun?` | 同名存在则复用,否则创建并把 origin 指向 API 地址;`ensureRemoteRepo` |
|
|
273
266
|
| `git_set_visibility` | **`repo`**、**`visibility`** | `PATCH /repos/{owner}/{repo}` 的 private 字段;改 public 前须确认无凭据暴露;`setVisibility` |
|
|
274
267
|
| `link_check` | `path?`(缺省 workspaceRoot) | 分级扣分(404/403 −3、DNS −2、超时/5xx −1,flaky 域名 ×0.2);**只 warning 永不 blocker**;并发 10;`checkLinks`/`probeLinks` |
|
|
275
|
-
| `git_gen_readme` | **`repo`**、`writePath?`(缺省只返回内容) | 模板优先级:插件 `template/README.md` > 内置 `readme.yml` > 代码兜底;版本表由 `git log --reverse` 聚合;`genReadme` |
|
|
276
268
|
|
|
277
269
|
**接线层**(`lib/plugin/index.js`,Host 侧四段真实 API):工具 `ctx.inject(['tools'])` → `register(defineTool(spec))`(`output.render` **必须返回块数组**);提示词注入 `inject(['systemPrompt'])` → `section({name, order, text})`;HTTP `inject(['webServer'])` → `register({kind:'prefix', path, handler})`;客户端**不在此注册**(由 package.json `dsh.client` + `exports["./client"]` 自动发现)。
|
|
278
270
|
|