dsh-git-push 0.0.0-stage → 2.8.4
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 +30 -0
- package/.gitignore +39 -0
- package/LICENSE +21 -0
- package/README.md +1482 -2
- package/cli.mjs +360 -0
- package/cordis.patch.yml +14 -0
- package/lib/ARCHITECTURE.md +34 -0
- package/lib/BUGFIX-NOTES-2026-09-14.md +278 -0
- package/lib/app/apply.js +275 -0
- package/lib/app/audit-api.js +158 -0
- package/lib/app/command-registry.js +262 -0
- package/lib/app/constants.js +16 -0
- package/lib/app/handlers/account.js +166 -0
- package/lib/app/handlers/clone.js +168 -0
- package/lib/app/handlers/http-constants.js +9 -0
- package/lib/app/handlers/identity-rewrite.js +94 -0
- package/lib/app/handlers/meta.js +175 -0
- package/lib/app/handlers/npm.js +169 -0
- package/lib/app/handlers/repo-actions.js +143 -0
- package/lib/app/handlers/repos.js +231 -0
- package/lib/app/handlers/settings.js +62 -0
- package/lib/app/host-doc-checks.js +25 -0
- package/lib/app/http-handlers.js +131 -0
- package/lib/app/index.js +30 -0
- package/lib/app/inject-text.js +191 -0
- package/lib/app/scan-root.js +23 -0
- package/lib/app/schema.js +150 -0
- package/lib/app/settings-bridge.js +167 -0
- package/lib/app/slash-commands.js +395 -0
- package/lib/app/slot-stats.js +35 -0
- package/lib/app/tool-call.js +662 -0
- package/lib/app/tools.js +40 -0
- package/lib/ast/brace.js +105 -0
- package/lib/ast/callgraph.js +135 -0
- package/lib/ast/code-lines.js +114 -0
- package/lib/ast/consts.js +12 -0
- package/lib/ast/control-flow.js +461 -0
- package/lib/ast/credential.js +199 -0
- package/lib/ast/dataflow.js +274 -0
- package/lib/ast/dup-code.js +165 -0
- package/lib/ast/index.js +36 -0
- package/lib/ast/io-risk-const.js +95 -0
- package/lib/ast/io-risk-fn.js +208 -0
- package/lib/ast/io-risk-loop.js +308 -0
- package/lib/ast/io-risk.js +314 -0
- package/lib/ast/lang.js +156 -0
- package/lib/ast/line-count.js +52 -0
- package/lib/ast/magic-number.js +272 -0
- package/lib/ast/naming.js +284 -0
- package/lib/ast/perf.js +472 -0
- package/lib/ast/scope.js +241 -0
- package/lib/ast/shell.js +131 -0
- package/lib/ast/size.js +378 -0
- package/lib/ast/symbol-index.js +399 -0
- package/lib/ast/tokenizer.js +341 -0
- package/lib/audit/analysis-coverage.js +98 -0
- package/lib/audit/audit-file.js +182 -0
- package/lib/audit/checks.js +17 -0
- package/lib/audit/client-entry.js +93 -0
- package/lib/audit/collector.js +477 -0
- package/lib/audit/ext-runner.js +80 -0
- package/lib/audit/file-context.js +138 -0
- package/lib/audit/finding.js +50 -0
- package/lib/audit/gitignore-match.js +113 -0
- package/lib/audit/glob.js +63 -0
- package/lib/audit/history-report.js +100 -0
- package/lib/audit/history.js +126 -0
- package/lib/audit/ignore-blind.js +101 -0
- package/lib/audit/index.js +33 -0
- package/lib/audit/orchestrate.js +476 -0
- package/lib/audit/public.js +24 -0
- package/lib/audit/repo-level.js +30 -0
- package/lib/audit/report-yaml.js +86 -0
- package/lib/audit/slot.js +65 -0
- package/lib/audit-defaults.js +18 -0
- package/lib/audit-rules/audit-rules-comment.yml +247 -0
- package/lib/audit-rules/audit-rules-cpp.yml +22 -0
- package/lib/audit-rules/audit-rules-docs.yml +32 -0
- package/lib/audit-rules/audit-rules-dsh.yml +162 -0
- package/lib/audit-rules/audit-rules-filehealth.yml +42 -0
- package/lib/audit-rules/audit-rules-folder.yml +99 -0
- package/lib/audit-rules/audit-rules-frontend.yml +335 -0
- package/lib/audit-rules/audit-rules-go.yml +22 -0
- package/lib/audit-rules/audit-rules-i18n.yml +45 -0
- package/lib/audit-rules/audit-rules-java.yml +105 -0
- package/lib/audit-rules/audit-rules-nodejs.yml +647 -0
- package/lib/audit-rules/audit-rules-npm.yml +187 -0
- package/lib/audit-rules/audit-rules-paths.yml +92 -0
- package/lib/audit-rules/audit-rules-performance.yml +207 -0
- package/lib/audit-rules/audit-rules-php.yml +22 -0
- package/lib/audit-rules/audit-rules-private.yml +24 -0
- package/lib/audit-rules/audit-rules-python.yml +106 -0
- package/lib/audit-rules/audit-rules-robustness.yml +27 -0
- package/lib/audit-rules/audit-rules-rust.yml +22 -0
- package/lib/audit-rules/audit-rules-structure.yml +159 -0
- package/lib/audit-rules/audit-rules-swift.yml +22 -0
- package/lib/audit-rules/audit-rules-template.yml +108 -0
- package/lib/checks/button-bind.js +276 -0
- package/lib/checks/common.js +170 -0
- package/lib/checks/credential-file.js +43 -0
- package/lib/checks/dataflow.js +40 -0
- package/lib/checks/dispatch.js +112 -0
- package/lib/checks/dup-code.js +69 -0
- package/lib/checks/dup-const.js +232 -0
- package/lib/checks/file-health.js +150 -0
- package/lib/checks/filter.js +131 -0
- package/lib/checks/folder.js +173 -0
- package/lib/checks/hardcoded-path.js +98 -0
- package/lib/checks/index.js +46 -0
- package/lib/checks/io.js +66 -0
- package/lib/checks/magic-number.js +42 -0
- package/lib/checks/npm-json.js +273 -0
- package/lib/checks/private.js +63 -0
- package/lib/checks/regex.js +256 -0
- package/lib/checks/semantic.js +134 -0
- package/lib/checks/structural.js +274 -0
- package/lib/cli/commands-account.mjs +107 -0
- package/lib/cli/commands-audit.mjs +144 -0
- package/lib/cli/commands-doc.mjs +127 -0
- package/lib/cli/commands-vcs.mjs +175 -0
- package/lib/client/index.js +162 -0
- package/lib/client-parts/00-loader.js +33 -0
- package/lib/client-parts/01-const.js +207 -0
- package/lib/client-parts/02-utils.js +62 -0
- package/lib/client-parts/03-icons.js +12 -0
- package/lib/client-parts/10-account.js +83 -0
- package/lib/client-parts/11-browser.js +95 -0
- package/lib/client-parts/20-repo.js +374 -0
- package/lib/client-parts/21-audit.js +301 -0
- package/lib/client-parts/22-settings.js +146 -0
- package/lib/client-parts/23-npm.js +383 -0
- package/lib/client-parts/30-page.js +56 -0
- package/lib/client-parts/40-controller.js +1092 -0
- package/lib/client-parts/41-actions.js +279 -0
- package/lib/client-parts/99-apply.js +72 -0
- package/lib/client.js +3195 -0
- package/lib/commit-push.js +144 -0
- package/lib/context/index.js +363 -0
- package/lib/core/atomic-json.js +98 -0
- package/lib/core/config.js +40 -0
- package/lib/core/credentials.js +274 -0
- package/lib/core/endpoints.js +109 -0
- package/lib/core/exec.js +162 -0
- package/lib/exempt/index.js +292 -0
- package/lib/fs/edit-after-read.js +103 -0
- package/lib/fsx.js +87 -0
- package/lib/git/account-status.js +140 -0
- package/lib/git/account.js +233 -0
- package/lib/git/api.js +136 -0
- package/lib/git/atomic-json.js +6 -0
- package/lib/git/browse.js +38 -0
- package/lib/git/clone-download.js +397 -0
- package/lib/git/clone-history-mode.js +143 -0
- package/lib/git/clone-history.js +175 -0
- package/lib/git/clone-jobs.js +250 -0
- package/lib/git/clone-replay-io.js +172 -0
- package/lib/git/clone-replay.js +275 -0
- package/lib/git/clone.js +445 -0
- package/lib/git/cloud.js +46 -0
- package/lib/git/commit-message.js +141 -0
- package/lib/git/config.js +6 -0
- package/lib/git/cred-env.js +88 -0
- package/lib/git/credentials.js +6 -0
- package/lib/git/endpoints.js +6 -0
- package/lib/git/exec.js +6 -0
- package/lib/git/identity-rewrite.js +297 -0
- package/lib/git/identity.js +150 -0
- package/lib/git/ignore.js +69 -0
- package/lib/git/index.js +41 -0
- package/lib/git/module-splitter.js +47 -0
- package/lib/git/post-push.js +101 -0
- package/lib/git/push-diagnose.js +142 -0
- package/lib/git/push.js +470 -0
- package/lib/git/remote-resolve.js +146 -0
- package/lib/git/remote.js +128 -0
- package/lib/git/repo-index.js +512 -0
- package/lib/git/repos.js +235 -0
- package/lib/git/scan-runner.js +159 -0
- package/lib/git/sensitive.js +134 -0
- package/lib/git/transport.js +430 -0
- package/lib/git/visibility.js +35 -0
- package/lib/git/wrapped-git.js +68 -0
- package/lib/http/index.js +170 -0
- package/lib/index.js +24 -0
- package/lib/link-check/index.js +187 -0
- package/lib/npm/account.js +64 -0
- package/lib/npm/install.js +211 -0
- package/lib/npm/npmrc.js +56 -0
- package/lib/npm/publish.js +167 -0
- package/lib/npm/registry.js +147 -0
- package/lib/plugin/auto-detect.js +92 -0
- package/lib/plugin/auto-push.js +154 -0
- package/lib/plugin/index.js +250 -0
- package/lib/readme-templates/readme.yml +38 -0
- package/lib/rule/compilers/credential.js +62 -0
- package/lib/rule/compilers/dataflow.js +38 -0
- package/lib/rule/compilers/file-health.js +75 -0
- package/lib/rule/compilers/frontend.js +86 -0
- package/lib/rule/compilers/func.js +35 -0
- package/lib/rule/compilers/helpers.js +71 -0
- package/lib/rule/compilers/index.js +29 -0
- package/lib/rule/compilers/link-semantic.js +45 -0
- package/lib/rule/compilers/list-kinds.js +12 -0
- package/lib/rule/compilers/numeric-kinds.js +66 -0
- package/lib/rule/compilers/regex.js +78 -0
- package/lib/rule/compilers/structure.js +80 -0
- package/lib/rule/compilers.js +17 -0
- package/lib/rule/homoglyph.js +45 -0
- package/lib/rule/loader.js +270 -0
- package/lib/rule/registry.js +115 -0
- package/lib/rule/scope.js +67 -0
- package/lib/score/docs-score.js +166 -0
- package/lib/score/index.js +140 -0
- package/lib/self/index.js +193 -0
- package/lib/skip-dirs.js +64 -0
- package/lib/tool-probes.json +50 -0
- package/lib/user-requirements.json +14 -0
- package/lib/vendor/js-yaml/LICENSE +21 -0
- package/lib/vendor/js-yaml/js-yaml.mjs +3073 -0
- package/package.json +95 -4
- package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
- package/scripts/audit-ext/_example-readme-present.mjs +34 -0
- package/scripts/audit-ext/variable-min-length.mjs +102 -0
- package/scripts/audit-runner.mjs +35 -0
- package/scripts/audit-runtime-check.mjs +129 -0
- package/scripts/browser-page-probe.mjs +271 -0
- package/scripts/build-client.mjs +119 -0
- package/scripts/check.mjs +88 -0
- package/scripts/clean-date-comments.py +102 -0
- package/scripts/doc-drift.mjs +200 -0
- package/scripts/doc-func.mjs +212 -0
- package/scripts/doc-tree.mjs +456 -0
- package/scripts/doc-version.mjs +220 -0
- package/scripts/frontend-preview-check.mjs +124 -0
- package/scripts/hot-path-probe-cjs.cjs +71 -0
- package/scripts/hot-path-probe-fs-shim.mjs +28 -0
- package/scripts/hot-path-probe-fsp-shim.mjs +31 -0
- package/scripts/hot-path-probe.mjs +153 -0
- package/scripts/module-splitter.py +800 -0
- package/scripts/platform-scan.mjs +168 -0
- package/scripts/preview-gen.mjs +489 -0
- package/scripts/preview-local-runner.mjs +55 -0
- package/scripts/preview-server-direct.mjs +116 -0
- package/scripts/preview-server.mjs +305 -0
- package/scripts/preview-slot-data.mjs +123 -0
- package/scripts/probe-recheck.mjs +47 -0
- package/scripts/readme-gen.mjs +268 -0
- package/scripts/rename-locator.mjs +97 -0
- package/scripts/rule-switch.mjs +97 -0
- package/scripts/rules-solo-audit.mjs +173 -0
- package/scripts/scan-file-io.mjs +713 -0
- package/scripts/scan-hardcoded-paths.mjs +125 -0
- package/scripts/scan-repos.mjs +167 -0
- package/scripts/scan-version.mjs +122 -0
- package/scripts/scrub-user-wording.mjs +420 -0
- package/scripts/symbol-index.mjs +85 -0
- package/scripts/sync-plugin-install.mjs +223 -0
- package/scripts/sync-plugin.mjs +279 -0
- package/scripts/verify-prestep.mjs +100 -0
- package/skills/dev/audit-rule-authoring.md +58 -0
- package/skills/dev/dsh-git-push.md +323 -0
- package/skills/dev/git-push-live-fix.md +45 -0
- package/skills/dsh-repo-index.md +35 -0
- package/skills/guide/guide-audit.md +167 -0
- package/skills/guide/guide-cli-scripts.md +104 -0
- package/skills/guide/guide-clone-repos.md +173 -0
- package/skills/guide/guide-commit-push.md +156 -0
- package/skills/guide/guide-inject-ui.md +166 -0
- package/skills/guide/guide-slash-completion.md +118 -0
- package/skills/workflow/README.md +21 -0
- package/skills/workflow/git-commit-discipline.md +68 -0
- package/skills/workflow/git-project-startup.md +85 -0
- package/skills/workflow/git-rebuild-process.md +57 -0
- package/skills/workflow/github-operations.md +91 -0
- package/skills/workflow/readme-sync-git-md.md +28 -0
- package/skills/workflow/task-completion-report.md +73 -0
- package/skills/workflow/tool-json-add-ask.md +35 -0
- package/skills/workflow/versioning-rule.md +211 -0
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dsh-git-push
|
|
3
|
+
description: dsh-git-push 插件开发与使用手册:工具参数/返回、HTTP 路由与鉴权、设置项、规则包与豁免、源码定位。处理插件用法与改插件类请求时加载。
|
|
4
|
+
whenToUse: 查工具参数细节、排查插件报错、改插件源码(定位到文件与函数)时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# dsh-git-push 插件手册
|
|
10
|
+
|
|
11
|
+
> 定位:把「扫描仓库 → 审计门禁 → 一键 commit+push」固化为代码管道(零 token、确定性)。
|
|
12
|
+
> 本手册是使用说明;正常情况优先直接调用插件工具。
|
|
13
|
+
|
|
14
|
+
## 一、17 个工具
|
|
15
|
+
|
|
16
|
+
| 工具 | 参数 | 说明 |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| `git_scan` | `root?`, `paths?`, `extraReposFile?` | 扫描全部 git 仓库 → 分支/remote/未提交变更数/最近活动 |
|
|
19
|
+
| `git_commit_push` | `repo`(必填), `message`(必填), `push?`, `dryRun?`, `audit?`(默认 true), `requirementsConfirmed?` | **先审计** → `git add -A` → commit → push;审计有 blocker 时拦截 |
|
|
20
|
+
| `code_audit` | `repo`, `scope?`, `llm?`, `ruleset?`, `weights?` | 审计仓库:L0 静态检查 + 10 维度质量评分;`scope=full` 全量;`ruleset` 指向自定规则目录(整体替换规则包);**审计固定走完整流程**(正则初筛 + AST 语义检查,无强度档位);`weights` JSON 覆盖权重 |
|
|
21
|
+
| `git_clone` | `target`(必填), `dest?`, `branch?` | 经 `api.github.com` Git Data API 克隆(不跟随 302、不直连 codeload) |
|
|
22
|
+
| `git_remote_create` | `repo`, `visibility?`(默认 private), `dryRun?` | 按目录名建远程仓库并设 origin(走 api.github.com) |
|
|
23
|
+
| `git_set_visibility` | `repo`, `visibility`(必填) | 切换仓库公开/私有(改 public 前先确认无凭据泄露) |
|
|
24
|
+
| `link_check` | `repo?`, `paths?` | 检查文档链接:404/403→-3、DNS→-2、超时/5xx→-1;只 warning,永不 blocker |
|
|
25
|
+
| `io_scan` | `repo?`, `writeOnly?` | I/O 风险扫描(AST 四级分级 high/medium/low/safe,与审计 io-risk 同标准) |
|
|
26
|
+
| `git_clone_preview` | `target`, `branch?` | clone 预演(不落盘,报告将拉取什么) |
|
|
27
|
+
| `edit_after_read` | `path`/`file_path`, `old`/`old_string`, `new`/`new_string`, `all?` | 读改合一编辑(读后文件被改动则拒绝;old 默认必须唯一匹配;字面匹配不做正则解释) |
|
|
28
|
+
| `git_identity_rewrite` | `paths?`, `root?`, `dryRun?`, `push?` | 提交身份历史改写(默认 dryRun 只报告;真改写先建备份引用 + 自检,通过才 force-with-lease) |
|
|
29
|
+
| `module_splitter` | `command`, `file`/`plan`, `dryRun?` | 巨型单文件拆分:analyze(先看依赖)→ split → verify(校验导出一致) |
|
|
30
|
+
| `git_account_check` | `token?`, `sshPub?` | 校验 GitHub 账号与凭据(登录态/用户名/公钥数/套餐;token 不传自动解析) |
|
|
31
|
+
| `git_cred_env` | — | 输出凭据环境变量前缀(SSH `GIT_SSH_COMMAND` / HTTPS `GIT_ASKPASS`,不含明文) |
|
|
32
|
+
| `git_gen_ssh_key` | `email`(必填), `force?` | 生成 SSH 密钥对(写入插件配置目录;私钥不出本机,公钥整行回传) |
|
|
33
|
+
| `git_sluice` | `args`(必填) | git 命令透传(凭据自动注入;返回 status + stdout/stderr 原文) |
|
|
34
|
+
| `git_api` | `path?`, `method?`, `query?`, `body?` | **直接调用本插件 28 条 HTTP API**(内部走 `handleHttp` 同一条代码路径,不另写实现);不传 `path` 则列出全部接口 |
|
|
35
|
+
|
|
36
|
+
典型流程:`git_scan` 看改动 → `code_audit` 自查 → `git_commit_push`(审计通过才推)。
|
|
37
|
+
|
|
38
|
+
分支:**没有改动、或只想把「本地领先远端」的已提交内容推上去** ⇒ 直接调 `git_commit_push`,不必先审计/先 commit:
|
|
39
|
+
零改动返回 `ok:true + committed:false`(job 状态 completed,不是失败),领先提交照常推送(`pushed:true`)。
|
|
40
|
+
|
|
41
|
+
## 二、审计规则包(YAML 槽位)
|
|
42
|
+
|
|
43
|
+
- **位置**:`lib/audit-rules/audit-rules-<槽位名>.yml`
|
|
44
|
+
- **槽位全动态**:**放一个 yml 进目录就自动成为槽位**,删除即失效,无需改代码
|
|
45
|
+
- **排序偏好**:`lib/rule/loader.js` 的 `SLOT_ORDER_HINT` 只决定加载顺序,不决定「有哪些槽位」
|
|
46
|
+
- **环境变量**:`DSH_GIT_PUSH_RULE_SLOTS=nodejs,docs` 可临时指定(脱离 DSH 时用)
|
|
47
|
+
- **template**:`audit-rules-template.yml` 是空模板,默认不加载(供自定义参照)
|
|
48
|
+
|
|
49
|
+
已建槽位:`nodejs`(代码规则)、`docs`(链接与文档规则)。
|
|
50
|
+
|
|
51
|
+
### 规则字段 → 编译函数(加字段 = 加函数 + 注册一行)
|
|
52
|
+
|
|
53
|
+
`lib/rule/registry.js` 的 `compileRule` 是统一入口,**永不需要修改**。新增一种规则类型只需:
|
|
54
|
+
|
|
55
|
+
1. 在 yml 里加字段(如 `max_lines: 50`)
|
|
56
|
+
2. 在 `lib/rule/compilers.js` 写一个编译函数
|
|
57
|
+
3. `registerCompiler(kind, detect, compile)` 注册一行
|
|
58
|
+
|
|
59
|
+
`detect` 是认领条件(看 id 前缀或字段存在性),注册表有序匹配。
|
|
60
|
+
|
|
61
|
+
### 支持的规则字段
|
|
62
|
+
|
|
63
|
+
| 字段 | kind | 含义 |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| `pattern` / `patterns` + id 前缀 `secret-` | `[FUNC]` | 凭据正则(大小写不敏感,驼峰/大写不漏检) |
|
|
66
|
+
| id 前缀 `credfile-` / `path_pattern` | `credential-file` | 凭据类文件路径 |
|
|
67
|
+
| id 前缀 `credref-` | `credential-ref` | 凭据引用模式 |
|
|
68
|
+
| `max_lines` | `func-lines` | 单函数行数上限 |
|
|
69
|
+
| `max_lines`(文件级) | `max-lines` | 单文件行数上限 |
|
|
70
|
+
| `min_length` | `min-length` | 命名最短长度 |
|
|
71
|
+
| `max_complexity` | `max-complexity` | 圈复杂度上限 |
|
|
72
|
+
| `max_depth` | `max-depth` | 嵌套深度上限 |
|
|
73
|
+
| `min_occurrences` | `repeated-string` / `min-occurrences` | 重复硬编码串/数值 |
|
|
74
|
+
| `path_pattern`(非 credfile) | `path-regex` | 文件路径正则 |
|
|
75
|
+
| `pattern`(普通) | `regex` | 通用正则 |
|
|
76
|
+
| `kind: link-check` | `link-check` | 链接有效性 |
|
|
77
|
+
| `semantic` | `semantic` | 语义提示(需人工确认,notice 级) |
|
|
78
|
+
|
|
79
|
+
**severity 上限规则**:yml 里声明的 `severity` 是上限——规则写 warning,检查器就不会把它升为 blocker。
|
|
80
|
+
|
|
81
|
+
## 三、豁免标记(dsh-skip-*)
|
|
82
|
+
|
|
83
|
+
写注释即可豁免,**位置决定范围**:
|
|
84
|
+
|
|
85
|
+
| 标记 | 豁免什么 | 位置语义 |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| `dsh-skip-sensitive` | 凭据/敏感信息(`[FUNC]`/credential-*) | 文件头前 3 行=整文件;行尾=本行 |
|
|
88
|
+
| `dsh-skip-func-length` | 函数过长 | 文件头=整文件;函数定义行=该函数 |
|
|
89
|
+
| `dsh-skip-residue` | 残留注释措辞 | 文件头=整文件;行尾=本行 |
|
|
90
|
+
| `dsh-skip-quality` | 质量类(命名/复杂度/嵌套/重复串) | 文件头=整文件 |
|
|
91
|
+
| `dsh-skip-size` | 文件过大 | 只能写文件头(文件大小是整文件属性) |
|
|
92
|
+
|
|
93
|
+
豁免**只免扫描告警,不免审计门禁本身**——不放行任何凭据入库。
|
|
94
|
+
|
|
95
|
+
## 四、质量评分
|
|
96
|
+
|
|
97
|
+
10 维度加权(合计 100):可读性 15 / 可维护性 15 / 健壮性 15 / 安全性 18 / 性能 10 / 测试覆盖 10 / 可观测性 5 / 可部署性 5 / 文档 4 / 开发者体验 3。
|
|
98
|
+
|
|
99
|
+
分档:A ≥ 85,B ≥ 70,C ≥ 55,其余 D。问题按 `dimensions` 归属到维度后扣分。
|
|
100
|
+
|
|
101
|
+
## 五、HTTP API 鉴权
|
|
102
|
+
|
|
103
|
+
- **写方法**(POST/PUT/PATCH/DELETE)必须带 `Origin` 头,且需与 Host 同源;缺失或跨域 → 403
|
|
104
|
+
- **破坏性操作**(重建历史/切可见性/删仓)需 body 带 `confirm: true`,否则 400
|
|
105
|
+
- **body > 5 MB** → 413
|
|
106
|
+
- GET/OPTIONS 免鉴权(只读探测)
|
|
107
|
+
|
|
108
|
+
## 六、独立运行(脱离 DSH)
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
node cli.mjs version # 版本
|
|
112
|
+
node cli.mjs ruleset # 编译规则包并输出统计
|
|
113
|
+
node cli.mjs scan # 扫描仓库
|
|
114
|
+
node cli.mjs audit . --full # 全量审计(--full 全量,默认只扫变动)
|
|
115
|
+
node cli.mjs link-check # 链接检查
|
|
116
|
+
node cli.mjs self-check # 自身完整性
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`package.json` 的 `bin.git-sluice` 指向 `cli.mjs`。
|
|
120
|
+
|
|
121
|
+
## 七、安装与客户端 UI(官方 CLI + 2026-09-12 修复实录)
|
|
122
|
+
|
|
123
|
+
### 7.1 安装(三种来源:本地 link / 打包 tgz / GitHub 源)
|
|
124
|
+
|
|
125
|
+
⚠️ **2026-10-12 实测:`dsh plugin --profile <名> add …` 会挂死且零输出**(两次都以 timeout 结束、
|
|
126
|
+
日志为空)⇒ 下面的命令**改在 profile 目录里直跑 pnpm**(`dsh plugin` 的设计就是把参数转发给 profile 的
|
|
127
|
+
pnpm,两者本应等价,但转发这条路当前不可用):
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
export DSH_HOME="<你的 DSH 实例 .dsh 目录>"
|
|
131
|
+
cd "$DSH_HOME/profiles/web"
|
|
132
|
+
|
|
133
|
+
# ① 开发期:本地 link(改码重启即生效)
|
|
134
|
+
pnpm add link:/绝对/路径/dsh-git-push
|
|
135
|
+
|
|
136
|
+
# ② 实体安装(唯一实体是 .tgz;pnpm 的目录源都是软链)
|
|
137
|
+
pnpm remove dsh-git-push && rm -f node_modules/dsh-git-push
|
|
138
|
+
cd <源码> && pnpm pack --pack-destination /tmp/
|
|
139
|
+
cd "$DSH_HOME/profiles/web" && pnpm add /tmp/dsh-git-push-<版本>.tgz
|
|
140
|
+
|
|
141
|
+
# ③ 从 GitHub 源装(公开仓库匿名可装;远端暂无 tag ⇒ 用 commit 固定版本)
|
|
142
|
+
pnpm add github:EIGHTfs/dsh-git-push#<commit>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**GitHub 源的两条前置条件(2026-10-12 实测,缺一即失败)**:
|
|
146
|
+
|
|
147
|
+
1. **本机要有 `npm`** —— pnpm 构建 git 来源的包时会在临时目录执行 `npm install`;缺 npm 报
|
|
148
|
+
`ERR_PNPM_PREPARE_PACKAGE` + `spawn ENOENT: npm: command not found`。
|
|
149
|
+
(本机已装:npm 10.9.2 解包到 `<APP>/lib/node_modules/npm`,链到
|
|
150
|
+
`/var/packages/DeepSeekHarness-NAS/target/.local/bin/npm` —— `/usr/local/bin` 不可写。)
|
|
151
|
+
2. **pnpm 11 默认禁止 git 源依赖执行构建脚本**(供应链策略),而本插件**有 `prepare`/`prepack`**
|
|
152
|
+
(构建不入库的 `lib/client.js`)⇒ 必须先在 profile 的 `pnpm-workspace.yaml` 放行:
|
|
153
|
+
|
|
154
|
+
```yaml
|
|
155
|
+
allowBuilds:
|
|
156
|
+
dsh-git-push@https://codeload.github.com/EIGHTfs/dsh-git-push/tar.gz/<commit>: true
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
否则报 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`;key 里带 commit 哈希 ⇒ 换版本/换提交要同步改这一行。
|
|
160
|
+
|
|
161
|
+
装完三步:profile `package.json` 的 `dsh.profile.bundles` 登记插件名 → 本插件 `cordis.patch.yml`
|
|
162
|
+
顶层 `- insert:` 新建 loader 行 → 重启宿主并在日志确认 `loaded`。
|
|
163
|
+
验证:`ls -la node_modules/dsh-git-push`(drwx=实体,lrwx=软链)+ `--dump-config` 应有
|
|
164
|
+
`id: dsh-git-push / enabled: true`(重启门禁见 dsh-restart-gate)。
|
|
165
|
+
|
|
166
|
+
### 7.2 客户端 UI 修复实录(2026-09-12)
|
|
167
|
+
|
|
168
|
+
**症状**:设置侧边栏有「Git 提交推送」入口,但点击无内容;插件配置无卡片。排查确认两个根因 + 一个隐藏坑:
|
|
169
|
+
|
|
170
|
+
1. **根因① Host 缺 `settings.register`**——官方契约:配置卡 = Host 注册命名空间 ∩ client 卡片 key 的交集。Host 没 `settingsCtx.settings.register('git-push', Config)` 时交集为空 → 不出卡。修复:apply() 里 `ctx.inject(['settings'])` + `settings.register('git-push', Config, { base: defaultConfig() })` + `scope.watch` 同步。
|
|
171
|
+
2. **根因② `scope.use()` 不存在**——官方 `SettingsScope` 契约只有 `getSnapshot()/subscribe()/set()/mutate()/unset()`,无 `use()`。v2 曾误用 `scope.use()` → 渲染 TypeError → 侧边栏空白。修复:uSES 桥 `useSyncExternalStore(scope.subscribe, () => scope.getSnapshot())` 读 `snap.value`。
|
|
172
|
+
3. **隐藏坑:pnpm 目录源=软链**——用户「重启后还是不行」→ 要求重装。实测 `add 目录` / `add file:目录` 装出来都是软链;`.tgz` 才是实体。重装为实体后正常。
|
|
173
|
+
|
|
174
|
+
**最终修复 = 客户端重构(Controller + hooks + 独立 section 页)**:
|
|
175
|
+
- client.js 换用 v1 验证过的实现:`GitPushCardController`(scope 订阅 → `store.createSnapshotStore(project())` → publish)+ `inject()` 返回 `{ hooks: { gitPushCard: store }, edit/toggle/save... }`(槽系统把 store 转成 `useGitPushCard` hook 注入卡片)
|
|
176
|
+
- `settings.section` 用**独立 `GitPushSectionPage`**(平铺 UI:登录只读 + 高级设置即时保存),不复用折叠卡(复用是反模式)
|
|
177
|
+
- `settings.plugin.item`:`key: SETTINGS_NS`('git-push')+ `inject: () => card.inject()`
|
|
178
|
+
- Host Config 合并 v1 全量字段(githubToken/sshPub/injectFullSkill/hardcodeFullScan/injectRepoIndexFull/customIgnorePatterns/yamlCheckMode/auditRuleWeights/qualityWeights/ruleSlotMeta)+ 保留 v2 特有字段
|
|
179
|
+
- 双语设计取消:去 en 表 + locale 依赖,只留中文
|
|
180
|
+
- 测试适配 v1 结构(jsx-runtime 断言反转、Controller 默认值、槽系统 hooks 模拟渲染);fallback schema 补 dict/any
|
|
181
|
+
|
|
182
|
+
**验证**:`npm test` 430 全绿;真实 React 元素树卡片+section 均构建成功;GUI 实测设置侧边栏出现「Git 提交推送」。
|
|
183
|
+
|
|
184
|
+
### 7.3 客户端 UI 三选项卡重写(2026-09-12)
|
|
185
|
+
|
|
186
|
+
**用户决策**:删设置配置卡(`settings.plugin.item`),只保留侧边栏独立页(`settings.section`),页面重写为**三个大选项卡**(对齐插件市场 .tabs/.tab/.on,参考 skill 记分板):
|
|
187
|
+
|
|
188
|
+
1. **账号信息**(纯展示):`GET /api/git-push/account-check` → GitHub 登录态/用户名/公钥指纹/套餐,`block` 文本直接展示。
|
|
189
|
+
2. **审计**:① 审计开关(`auditEnabled`,settingsScope.set 即时保存)② 审计权重 10 维度(可读性/可维护性/健壮性/安全性/性能/测试覆盖/可观测性/可部署性/文档/开发者体验,默认合计 100;改即写 `weightOverrides` JSON)③ 规则包列表(`GET /api/git-push/rule-slots` 动态发现;↑↓ 调次序写 `auditRuleOrder`(下覆盖上);单击展开 → `GET /api/git-push/rule-detail?slot=<名>` 显示拦截/警告/通过数量统计 + 规则表格(规则名/简介/级别/作者))。
|
|
190
|
+
3. **设置**:GitHub token(写 `githubToken`)+ SSH 公钥(写 `sshPub`)+ 邮箱 + 一键生成(`POST /api/git-push/gen-ssh-key`,公钥填入 SSH 框并复制剪贴板)。
|
|
191
|
+
|
|
192
|
+
**配套后端**:
|
|
193
|
+
- `GET /api/git-push/rule-slots`:meta 增加 `author`(读 yml metadata)。
|
|
194
|
+
- `GET /api/git-push/rule-detail?slot=<名>`:读单个 `audit-rules-<名>.yml` 的 rules 数组 → `{ meta, stats: { blocker, warning, pass, total }, rules: [{ id, name, category, severity, description, author }] }`。拦截=blocker|error,警告=warning,通过=其余(含无 severity)。
|
|
195
|
+
|
|
196
|
+
**结构要点**:
|
|
197
|
+
- 纯中文:删 zh/en 键值对字典,文案硬编码中文(产品设计)。
|
|
198
|
+
- 只注册 `settings.section`;`settings.plugin.item` 已删除(`clientModuleInfo().slots` 同步为 `['settings.section']`)。
|
|
199
|
+
- Controller 命名 `dshgp_*` 前缀防 combo 撞名;组件 `dshgp_AccountTab` / `dshgp_AuditTab` / `dshgp_SettingsTab` + `dshgp_GitPushPage` 装配。
|
|
200
|
+
- 文件顶层零声明 + `load` 顶部(client-modules 聚合 bundle 兼容),详见 7.2 形态铁律。
|
|
201
|
+
- 测试适配:`clientModuleInfo().slots` 断言删 plugin.item;`审计相关开关默认关` 改断言 `this.auditEnabled = false`;CSS 变量名 `dshgp_css`。
|
|
202
|
+
|
|
203
|
+
**验证**:`npm test` 430 全绿;combo 拼接解析通过;apply 只注册 section(plugin.item=0)。
|
|
204
|
+
|
|
205
|
+
## 八、常见问题
|
|
206
|
+
|
|
207
|
+
| 现象 | 原因 / 处理 |
|
|
208
|
+
|---|---|
|
|
209
|
+
| 设置了侧边栏没有「Git 提交推送」 | ① `--dump-config` 确认插件节点 enabled: true;② client.js 不得调用 `scope.use()`(官方 SettingsScope 无此方法,渲染 TypeError 致空白);③ Host 必须 `settings.register('git-push', Config)`(配置卡=交集);见 7.2 |
|
|
210
|
+
| 规则改了不生效 | 槽位是动态发现,确认 yml 文件名是 `audit-rules-<名>.yml` 且放在 `lib/audit-rules/` |
|
|
211
|
+
| 新规则被更宽的规则抢走 | 注册表**有序匹配**,宽泛的 detect(如 `regex`)要排在专用 detect 之后,或把 detect 条件写精确 |
|
|
212
|
+
| 审计报「0 blocker 0 warning 但 total > 0」 | error 级问题也计入拦截级;看 findings 的 severity 字段 |
|
|
213
|
+
| 豁免写了没用 | 标记必须在前 3 行(整文件豁免)或写在**命中那一行**(行级豁免) |
|
|
214
|
+
| 链接检查报错 | 链接问题只 warning 不拦截;flaky 域名(github 等)网络错误扣分 ×0.2 |
|
|
215
|
+
|
|
216
|
+
## 九、文档组织(分体式,2026-09-29)
|
|
217
|
+
|
|
218
|
+
> 本插件维护文档统一 **分体式**:版本记录、文件树、函数列表等**不直接写进 README**,各自存独立文档,README 只放链接引用。配套检查工具已适配。
|
|
219
|
+
|
|
220
|
+
### 9.1 文档存哪(doc- 前缀三兄弟统一)
|
|
221
|
+
|
|
222
|
+
| 文档 | 位置 | 维护脚本 | 标记块 |
|
|
223
|
+
|---|---|---|---|
|
|
224
|
+
| 版本记录(changelog) | `docs/CHANGELOG.md` | `scripts/doc-version.mjs`(gen/apply/check) | `dshgp-version` |
|
|
225
|
+
| 函数列表 | `docs/FUNCTIONS.md` | `scripts/doc-func.mjs`(gen/apply/check) | `dshgp-functions` |
|
|
226
|
+
| 文件目录树 | README「目录结构」节 或 docs/ 带块 md | `scripts/doc-tree.mjs`(gen/apply/check/sync,原 tree-doc) | `dshgp-tree` |
|
|
227
|
+
| README.md | 只放「功能总览 + 用法 + 上述文档的链接引用」 | AI/human | — |
|
|
228
|
+
|
|
229
|
+
**约定**:README 不直接内嵌长文档(版本表/文件树/函数列表),改为「## 分体式文档」节链接引用。三脚本命令统一 `gen`(打印)/ `apply`(写宿主,自动探测带标记块的 md)/ `check`(查漂移);宿主探测复用公共函数 `findMarkedHostMd(root, marker)`(优先 README,README 无标记块时扫描 .md 找含块文件)。
|
|
230
|
+
|
|
231
|
+
### 9.2 README 生成(已抽独立脚本,非插件工具)
|
|
232
|
+
|
|
233
|
+
`git_gen_readme` 插件工具已于 2026-09-29 移除,改为**独立脚本**:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
node scripts/readme-gen.mjs <repoPath> [--write <path>] [--template <path>]
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
- 只打印不写 → 不传 `--write`;`--write README.md` 才落盘
|
|
240
|
+
- `--template` 指定自定义模板(缺省 `lib/readme-templates/readme.yml`);占位符 `{{name}} {{description}} {{version}} {{toc}} {{versionTable}}`
|
|
241
|
+
- 插件不再内置生成能力,push.js 的「仓库无 README」提示引用此脚本
|
|
242
|
+
|
|
243
|
+
### 9.3 doc-tree 自动探测 md(2026-09-29)
|
|
244
|
+
|
|
245
|
+
`doc-tree apply/sync/check`(原 tree-doc)不再死认 `README.md`,自动探测宿主 md:
|
|
246
|
+
|
|
247
|
+
- `--readme <路径>` 显式指定 → 直接用(向后兼容)
|
|
248
|
+
- 缺省:优先 README.md;README 无 `dshgp-tree` 标记块时,扫描根下 `.md`(排除 `.git/node_modules/.trash/.dsh`),找第一个含标记块文件作宿主
|
|
249
|
+
- 都无标记块 → 回退 README.md(apply 提示先插标记)
|
|
250
|
+
|
|
251
|
+
**适用**:文件树写 `docs/文件树.md` 后,`doc-tree apply` 自动写到它,README 链接引用。
|
|
252
|
+
|
|
253
|
+
### 9.4 版本检查适配
|
|
254
|
+
|
|
255
|
+
`scripts/scan-version` 已适配多 md——版本记录在 `docs/CHANGELOG.md` 等带块 md 而非 README 也能探测,三处一致校验不再死绑 README.md。
|
|
256
|
+
|
|
257
|
+
### 9.5 旧体系废弃(2026-09-29)
|
|
258
|
+
|
|
259
|
+
旧函数文档体系(`functions_index` 插件工具 + `scripts/func-index.js` + `scripts/functions-doc.mjs` + `docs/函数/*.md` + `functions-index.json`)已**整体废弃删除**,由 `doc-func.mjs` 取代(单文件 `docs/FUNCTIONS.md` 带标记块,不再每文件一个 md)。审计分体检查(appendSplitDocsCheck)对 `dshgp-version` / `dshgp-functions` 宿主 md 做存在性校验。
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## 附录 A、工具参数与返回(原「功能说明书」并入)
|
|
264
|
+
|
|
265
|
+
> 本节原为独立 skill `dsh-git-push-functions`,按同类合并并入本手册。架构:**10 总入口**(规则/审计/git/自身/侧边栏/评分/豁免/上下文/HTTP/测试),每个入口一个 `lib/` 子目录。
|
|
266
|
+
|
|
267
|
+
| 工具 | 参数(必填加粗) | 返回 / 实现 |
|
|
268
|
+
|------|------------------|-------------|
|
|
269
|
+
| `git_scan` | `root?`、`paths?`(逗号分隔额外仓库)、`extraReposFile?`(每行一个,`#` 注释,实时读) | 各仓库分支/remote/未提交数/最近活动;`lib/git/index.js` `scanRepos` |
|
|
270
|
+
| `git_commit_push` | **`repo`**、**`message`**、`audit`(默认 true)、`push`(默认 true)、`dryRun`(false)、`force`、`requirementsConfirmed`、`paths?` | 审计 → 敏感文件加 .gitignore → add → commit → push;push 前 fetch 检查 ahead/behind,远端领先不推;`commitAndPush` |
|
|
271
|
+
| `code_audit` | **`repo`**、`scope`(`full`/缺省=仅变动,非 git 目录退化全量)、`llm?`、`ruleset?`(自定规则目录=整体替换)、`weights?`(JSON 覆盖) | blocker/warning 清单 + quality 0-100(A/B/C/D);`auditWithScope`/`auditFull`/`auditChanged` |
|
|
272
|
+
| `git_clone` | **`target`**、`dest?`(非空目录拒绝防覆盖)、`branch?` | 只走 api.github.com Git Data API(`git/trees`+`git/blobs`),不跟随 302、不直连 codeload;`cloneViaApi` |
|
|
273
|
+
| `git_remote_create` | **`repo`**、`visibility?`(默认 private)、`dryRun?` | 同名存在则复用,否则创建并把 origin 指向 API 地址;`ensureRemoteRepo` |
|
|
274
|
+
| `git_set_visibility` | **`repo`**、**`visibility`** | `PATCH /repos/{owner}/{repo}` 的 private 字段;改 public 前须确认无凭据暴露;`setVisibility` |
|
|
275
|
+
| `link_check` | `path?`(缺省 workspaceRoot) | 分级扣分(404/403 −3、DNS −2、超时/5xx −1,flaky 域名 ×0.2);**只 warning 永不 blocker**;并发 10;`checkLinks`/`probeLinks` |
|
|
276
|
+
| `git_gen_readme` | **`repo`**、`writePath?`(缺省只返回内容) | 模板优先级:插件 `template/README.md` > 内置 `readme.yml` > 代码兜底;版本表由 `git log --reverse` 聚合;`genReadme` |
|
|
277
|
+
|
|
278
|
+
**接线层**(`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"]` 自动发现)。
|
|
279
|
+
|
|
280
|
+
## 附录 B、HTTP API 与鉴权
|
|
281
|
+
|
|
282
|
+
| 方法 | 路由 | 说明 |
|
|
283
|
+
|------|------|------|
|
|
284
|
+
| GET | `/api/git-push/scan` | 扫描仓库 |
|
|
285
|
+
| POST | `/api/git-push/audit` | 审计(`{repo, scope?, llm?}`) |
|
|
286
|
+
| POST | `/api/git-push/commit` | 提交推送(`{repo, message, push?, confirm?}`) |
|
|
287
|
+
| POST | `/api/git-push/clone`、`/repo-clone` | 克隆(`/repo-clone` 走后台任务,返回 202 + jobId) |
|
|
288
|
+
| POST | `/api/git-push/remote-create` | 建仓 |
|
|
289
|
+
| POST | `/api/git-push/visibility` | 切可见性(需 `confirm: true`) |
|
|
290
|
+
| POST | `/api/git-push/rebuild-history` | 重建历史(需 `confirm: true`) |
|
|
291
|
+
| GET | `/api/git-push/link-check`、`/clone-progress`、`/clone-logs`、`/account-status`、`/api-quota` | 只读查询 |
|
|
292
|
+
|
|
293
|
+
鉴权(`lib/http/index.js` `authPipeline`):① 写方法必须带同源 `Origin`(缺 → 403,跨域 → 403);② 破坏性操作需 body `confirm: true`(否则 400);③ body > 5 MB → 413;④ GET/OPTIONS 免鉴权。
|
|
294
|
+
|
|
295
|
+
## 附录 C、设置项与三处同源
|
|
296
|
+
|
|
297
|
+
- 设置项:`auditEnabled`(默认 false)、`auditScanScope`(diff|full)、`maxScanFiles`、`weightOverrides`、`pushMethod`、`pushGate`、`maxCloneFileMB`、`cloneConcurrency` 等
|
|
298
|
+
- **三处同源**(新增项必须三处同加,`test-client.mjs` 断言一致性):`lib/index.js` 的 `Config`(服务端 schema)+ `lib/client/index.js` 的 `SETTINGS_SCHEMA` + `client.js` 的 `SCHEMA`/`zh`
|
|
299
|
+
- 审计固定完整流程(无强度档位):正则/黑名单/凭据/路径/同步 IO/空 catch + AST 语义检查(func-lines / 复杂度 / 嵌套深度 / 文件行数 / 重复串 / 语义 / 凭据文件 / 命名长度)
|
|
300
|
+
- 自定规则包:目录里每个 `audit-rules-<名>.yml` 即一个槽位,放文件即生效、删文件即移除;指向空目录会装载 0 条规则(`errors` 有记录),不静默沿用内置包
|
|
301
|
+
|
|
302
|
+
## 附录 D、规则包 / 豁免 / 评分(源码定位)
|
|
303
|
+
|
|
304
|
+
| 模块 | 关键实现 |
|
|
305
|
+
|------|----------|
|
|
306
|
+
| `lib/rule/` | `loader.js` `discoverRuleSlots` / `resolveSlotOrder` / `loadRuleFiles`(合并多槽位,返回 `{ok, merged, order, files, errors}`);`registry.js` `compileRule`(统一入口,永不修改)+ `registerCompiler`(扩展点,**有序匹配**:宽泛 detect 必须排在专用之后);`compilers.js` 各 kind 实现,`safeRe()` 默认大小写不敏感 |
|
|
307
|
+
| `lib/exempt/` | `EXEMPT_MARKERS` 注册 `dsh-skip-*`(含可豁免 kind 与是否行级);`CATEGORY_EXEMPT` + `isCategoryExempt()` 处理文件类别豁免(test/、scripts/ 的 console-log / sync-fs / 空 catch);`exemptForFinding()` 单条判定 |
|
|
308
|
+
| `lib/audit/` | `index.js` `makeFinding`/`summarize`/`auditFile`/`auditFull`/`auditChanged`/`auditWithScope`;`checks.js` `runChecks` 按 kind 分发 + `checkPrivateFiles`;`glob.js` 零依赖 glob→RegExp;`collector.js` `collectTextFiles`(gitignore 感知)/`collectChangedFiles` |
|
|
309
|
+
| `lib/score/` | `ast.js` `tokenize` + 各 AST 检查器;`index.js` `DEFAULT_WEIGHTS`(10 维度合计 100)/`countByDimension`/`scoreQuality` |
|
|
310
|
+
| `lib/self/` + `cli.mjs` | `VERSION` 是版本号单一事实源(`scripts/scan-version.mjs` 校验);`cli.mjs` 子命令 version/ruleset/scan/audit/link-check/readme-template/yaml-template/self-check;CLI 选项白名单与 HELP 文本由 `self-check` 机器比对 |
|
|
311
|
+
|
|
312
|
+
## 附录 E、坑速查(补充)
|
|
313
|
+
|
|
314
|
+
| 现象 | 原因 / 处理 |
|
|
315
|
+
|------|-------------|
|
|
316
|
+
| 插件改动刷新看不到 | 真实加载源是 `<profile>/local-plugins/<插件名>`,只同步 `node_modules/` 无效;用 `scripts/sync-plugin.mjs --write` 同步两处(多 profile 时加 `--profile <名>`) |
|
|
317
|
+
| 改插件代码必须重启才生效 | 免重启热重载要同时满足两条:① profile 的 `cordis.patch.yml` 里 `id: hmr` 显式配 `base` + `root`(默认 `root: []` = module roots are opt-in,一个模块目录都不 watch);② 插件本体在 `local-plugins/`(`node_modules/**` 被默认 `ignored` 整棵剪枝,想只放行其下某插件的否定写法无效)。`sync-plugin.mjs` 会直接报告该插件能否热重载,`--fix` 可修部署形态(改完形态需重启一次让解析路径生效) |
|
|
318
|
+
| 规则不生效 | 槽位动态发现,确认文件名 `audit-rules-<名>.yml` 且在 `lib/audit-rules/` |
|
|
319
|
+
| 统计数字矛盾(0 blocker 0 warning 但 total > 0) | error 级计入拦截级,看 findings 的 `severity` |
|
|
320
|
+
| 豁免写了没用 | 整文件豁免须在前 3 行;行级豁免须写在命中行 |
|
|
321
|
+
| 函数/复杂度被报为 blocker | 规则 `severity` 是上限,检查器不越级;报 blocker 说明 yml 里写的就是 error/blocker |
|
|
322
|
+
| 克隆大文件反复失败 | 失败项的分片必须保留(`.dsh-parts`)才能跨轮 Range 续传;同轮清理分片会让大文件永远从 0 重来 |
|
|
323
|
+
| 建了远端但推送报「远端查不到分支 master(API 404 / ls-remote 无该分支)」 | `git_remote_create` 旧版把 origin 写成 **REST API 端点**(`https://api.github.com/repos/<o>/<r>` ✗ 那不是 git remote)⇒ `git push/fetch origin` 必然失败。2026-10-09 已修(`lib/git/remote.js`):origin 统一写 `https://github.com/<o>/<r>`,并**自愈**——仓库已存在但 origin 仍是 API 形态时 `set-url` 改回;返回体新增 `originAction`(`add`/`repair`/`keep`)。旧仓库手工修:`git remote set-url origin ssh://git@ssh.github.com:443/<o>/<r>.git` 再 `git push -u origin master`(凭据用插件 `id_rsa` + `-p 443`)。⚠️ `lib/git/clone.js` 仍写 API 形态 origin(设计如此,插件自身推送不受影响,但 `git push origin` 会失败) |
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: git-push-live-fix
|
|
3
|
+
description: 用 dsh-git-push 插件时发现问题必须当场提出并改插件,禁止默默手搓 git 绕过。处理插件工具不好用类请求时加载。
|
|
4
|
+
whenToUse: 正在用 dsh-git-push 工具、返回与参数/文档不符、只能手搓 git 才完成任务、准备绕过插件时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 用 git-push 发现问题要当场改(git-push-live-fix)
|
|
10
|
+
|
|
11
|
+
> 核心一句话:**插件不好用就当场说、当场改,不要默默手搓 git 把任务糊过去。**
|
|
12
|
+
|
|
13
|
+
## 一、规则
|
|
14
|
+
|
|
15
|
+
| 场景 | 必须做 | 禁止 |
|
|
16
|
+
|------|--------|------|
|
|
17
|
+
| 工具返回与参数/文档不符 | 先写明:哪个工具、哪个参数、实际做了什么 | 假装成功 |
|
|
18
|
+
| 只能靠手搓 `git` 才完成任务 | 视为插件 bug:改实现(`lib/git/`)、工具描述(`lib/app/tools.js`)、README 与本仓 skill | 只在本任务绕过、不改插件 |
|
|
19
|
+
| 参数存在但没接线(如声明了 `force` 却不推远端) | 补接线 + 补回归测试 | 继续传这个空参数 |
|
|
20
|
+
| 破坏性操作只改了本地、远端仍是旧历史 | 说明缺口;已授权则补强制推 | 回报「已重建」但远端还是旧提交 |
|
|
21
|
+
|
|
22
|
+
改插件属于 **bugfix-auto-authority**:直接修,修完告知「现象 / 改动位置 / 验证状态」。功能与新需求仍先确认。
|
|
23
|
+
|
|
24
|
+
## 二、历史反面教材
|
|
25
|
+
|
|
26
|
+
| 事故 | 教训 |
|
|
27
|
+
|------|------|
|
|
28
|
+
| 重建历史时把 `package.json` 版本改成 1.0.0 | 「版本不变、覆盖旧提交」= 只重建历史,不动版本号 |
|
|
29
|
+
| `force: true` 不推远端 | 工具描述写「强制推送」就必须真的 force push;只打 backup tag 不算 |
|
|
30
|
+
| 用 `git rm -rf .git` 想重建仓库 | 从索引删路径 ≠ 重建仓库;正确姿势是 `checkout --orphan` 并保留 remote / backup tag |
|
|
31
|
+
| `pushViaApi` 写死 `force: false` | 非快进更新必失败;force 场景必须允许 `force: true` |
|
|
32
|
+
|
|
33
|
+
## 三、流程
|
|
34
|
+
|
|
35
|
+
1. 先用插件工具,不要一上来手搓
|
|
36
|
+
2. 对不上预期 → 立刻在回复里写明 **插件问题**(工具名 + 参数 + 实际行为)
|
|
37
|
+
3. 改插件实现 + 回归测试 + README 版本表 + 本仓 skill
|
|
38
|
+
4. 用修好的逻辑把原任务做完(宿主未重启时,本回合手搓收尾 + 插件下一轮生效)
|
|
39
|
+
5. 插件仓库本身也要 commit + push
|
|
40
|
+
|
|
41
|
+
## 四、相关
|
|
42
|
+
|
|
43
|
+
- `skills/dsh-git-push.md`:插件手册
|
|
44
|
+
- `skills/dsh-git-push-functions.md`:各工具参数与返回
|
|
45
|
+
- 通用约定:`bugfix-auto-authority`(bug 直接修)、`plugin-priority`(优先用插件)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dsh-repo-index
|
|
3
|
+
description: 本机 DSH 插件/项目源码索引(权威 JSON):位置、字段、用法与存放规则。处理查仓库地址或恢复源码类请求时加载。
|
|
4
|
+
whenToUse: 需要恢复/克隆某个插件源码、确认某项目仓库地址与可见性、本地插件目录丢失需重建、写文档要引用源码位置时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# DSH 插件/项目源码索引(dsh-repo-index)
|
|
10
|
+
|
|
11
|
+
> 核心一句话:**仓库地址与源码位置的唯一权威是 JSON 索引,不是 md 表格、更不是各处复制的地址。**
|
|
12
|
+
|
|
13
|
+
## 一、权威文件
|
|
14
|
+
|
|
15
|
+
插件配置目录下的 `git-push/dsh-repo-index.json`(解析顺序:`DSH_HOME/git-push/` → `~/.dsh/git-push/`)
|
|
16
|
+
|
|
17
|
+
| 事实 | 说明 |
|
|
18
|
+
|------|------|
|
|
19
|
+
| md 表格 | 已废弃,不要用 |
|
|
20
|
+
| 旧位置 | 同级仓 `dsh-git-push-User/<owner>/dsh-repo-index.json` 已废除(索引与凭据收敛到插件自持) |
|
|
21
|
+
| 入 git | 不入库(插件配置目录整体不入库) |
|
|
22
|
+
| 注入 | 会话默认只注入该文件名;开启「注入 repo-index JSON 全文」才注入正文 |
|
|
23
|
+
| 生成 | 由插件生成,不要手改;「推送后自动重写」尚未实现,读既有 JSON 即可 |
|
|
24
|
+
|
|
25
|
+
## 二、怎么用
|
|
26
|
+
|
|
27
|
+
1. 读 JSON 的 `repos[]`:`name` / `repoUrl` / `visibility` / `cloneCmd` / `skills`
|
|
28
|
+
2. 公开与私有统一走 `git_clone`(走 GitHub API,不直连 github.com)
|
|
29
|
+
3. 其他 skill 写源码位置只写「见 dsh-repo-index」,不复制地址
|
|
30
|
+
|
|
31
|
+
## 三、相关
|
|
32
|
+
|
|
33
|
+
- 生成实现:`lib/git/repo-index.js`
|
|
34
|
+
- 注入开关:设置 → 插件配置 →「注入 repo-index JSON 全文」(`injectRepoIndexFull`)
|
|
35
|
+
- 存放规则:本 skill 权威位置是插件项目 `skills/`;`.dsh/skills/` 是加载副本(部署时同步),不要直接改副本
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: guide-audit
|
|
3
|
+
description: dsh-git-push 代码审计:三个入口、审计范围、10 维度评分、规则包槽位、豁免机制、严重级与报告聚合。处理代码审计/质量评分类请求时加载。
|
|
4
|
+
whenToUse: 要审计仓库、看质量分与问题明细、加停审计规则、豁免误报、查审计 API 时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 代码审计(guide-audit)
|
|
10
|
+
|
|
11
|
+
> 三条入口(工具 / HTTP API / CLI)跑同一套「静态初筛 + AST 语义审计」,输出 10 维度质量分与问题明细。
|
|
12
|
+
|
|
13
|
+
## 一、规则(场景 → 必须做的)
|
|
14
|
+
|
|
15
|
+
| 场景 | 必须做的 |
|
|
16
|
+
|---|---|
|
|
17
|
+
| 要审计一个仓库 | 会话内用工具 `code_audit`;只看聚合明细用 HTTP `/api/git-push/audit`;脱离 DSH 用 `git-sluice audit` |
|
|
18
|
+
| 判断能否提交 | 门禁只认 `blocker`,命中即拦;`warning` / `notice` 只提示不拦 |
|
|
19
|
+
| 遇到误报 | 先按判定类型选已有豁免机制;结构性误报优先修审计判定,不靠注释掩盖 |
|
|
20
|
+
| 新增 / 停用规则 | 只改规则 yml(放文件即生效、删文件即移除),不改代码 |
|
|
21
|
+
| 私有仓库 | 远端可见性 `private` 时审计只报告不拦截;`public` / `unknown` 保守拦截 |
|
|
22
|
+
|
|
23
|
+
## 二、怎么做 / 命令 / 实例
|
|
24
|
+
|
|
25
|
+
### 1. 三个入口(同一套引擎,结果一致)
|
|
26
|
+
|
|
27
|
+
| 入口 | 调用方式 | 特点 |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| 工具 | `code_audit` | 默认精简输出(评分 / 各级数量 / 豁免统计 / API 指引);`includeFindings=true` 出全量 |
|
|
30
|
+
| HTTP | `GET/POST /api/git-push/audit` | 请求时聚合:分组 / 严重级过滤 / 条数截断;默认全量范围 |
|
|
31
|
+
| CLI | `git-sluice audit <目录>` | 独立运行(零第三方依赖,Node ≥18 + 本机 git),`--json` 出全量 |
|
|
32
|
+
|
|
33
|
+
### 2. 工具 `code_audit` 参数
|
|
34
|
+
|
|
35
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| `repo` | string | ✅ | 仓库根目录 |
|
|
38
|
+
| `scope` | string | — | `full`(全量)/ `diff`(变动范围);不传按变动范围;非 git 目录自动全量 |
|
|
39
|
+
| `rulesetDir` | string | — | 自定规则目录 |
|
|
40
|
+
| `includeIgnored` | boolean | — | 连 `.gitignore` 忽略的文件也扫 |
|
|
41
|
+
| `includeFindings` | boolean | — | `true` 追加全量 `findings` 与 `yaml` |
|
|
42
|
+
| `history` | boolean | — | 历史提交审计(逐提交快照全量审计并落盘报告) |
|
|
43
|
+
| `since` / `until` / `outDir` | string | — | history 起止提交(皆缺省 = 全部历史,含两端)/ 报告目录(缺省 `<仓库>/audit-history/`) |
|
|
44
|
+
|
|
45
|
+
返回字段:`ok`、`scope`、`files`、`summary{blocker,warning,notice,total}`、`quality{score,level}`、`exemptStats{types,total}`、`blocked[]`(blocker 明细)、`groupByTypes`、`slotStats`、`apiGuide`;`includeFindings=true` 追加 `findings` + `yaml`。
|
|
46
|
+
`history=true` 返回 `async:true` + `jobId`(宿主后台 job,完成自动回传)或 `result`(无 job 控制器时同步降级)。
|
|
47
|
+
|
|
48
|
+
### 3. HTTP 审计 API
|
|
49
|
+
|
|
50
|
+
`GET/POST /api/git-push/audit`(参数放 query 或 JSON body,body 覆盖 query)。
|
|
51
|
+
|
|
52
|
+
| 参数 | 默认 | 说明 |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `repo` | 配置的默认扫描根 | 缺省且推断不出 → 400 `REPO_REQUIRED` |
|
|
55
|
+
| `scope` | `full` | `full` / `diff` |
|
|
56
|
+
| `groupBy` | `rule` | 聚合维度:`rule` / `file` / `severity` / `slot`(非法值回落 `rule`) |
|
|
57
|
+
| `severity` | 不过滤 | 逗号白名单,如 `blocker,warning` |
|
|
58
|
+
| `top` | `0` | 每组最多列前 N 条,`0` = 全部 |
|
|
59
|
+
| `withFindings` / `withYaml` | `false` | `true` 时附全量 `findings` / `yaml` 报告 |
|
|
60
|
+
| `includeIgnored` / `rulesetDir` / `maxScanFiles` / `weights` | — | 同工具 / CLI 语义(`includeIgnored` 连忽略文件也扫、`weights` 覆盖权重) |
|
|
61
|
+
|
|
62
|
+
返回:`ok`、`repo`、`scope`、`files`、`summary`、`quality{score,level}`、`groups[]`(按条数降序,每组含一条 `sample`)、`total`、`filtered`、`exemptStats`、`groupByTypes`、`blocked[]`。
|
|
63
|
+
|
|
64
|
+
### 4. CLI(`git-sluice audit`)
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git-sluice audit . # 变动范围(非 git 目录自动全量)
|
|
68
|
+
git-sluice audit . --full # 全量
|
|
69
|
+
git-sluice audit . --ruleset <规则目录> # 自定规则目录
|
|
70
|
+
git-sluice audit . --weights '{"安全性":25}' # 权重覆盖 JSON
|
|
71
|
+
git-sluice audit . --include-ignored # 连 .gitignore 忽略的文件也扫
|
|
72
|
+
git-sluice audit . --json # 全量 findings + yaml
|
|
73
|
+
git-sluice audit . --history --since <提交> --until <提交> --out <目录>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
CLI 读与插件同一份配置(`$DSH_HOME/git-push/config.json`);权重优先级:显式 `--weights` > 配置 `weightOverrides` > 默认权重表。CLI 与插件用同一实现、同一配置,同一仓库同一参数结果一致。
|
|
77
|
+
|
|
78
|
+
### 5. 审计范围(full / changed / diff)
|
|
79
|
+
|
|
80
|
+
| 叫法 | 含义 |
|
|
81
|
+
|---|---|
|
|
82
|
+
| `full` | 全量扫描(非 git 目录也能查) |
|
|
83
|
+
| `diff` / `changed` | 变动范围(未提交改动);`diff` 是入口写法,内部 scope 记为 `changed`,同一实现 |
|
|
84
|
+
|
|
85
|
+
默认范围:提交前自动审计取配置 `auditScanScope`(默认 `diff`);工具不传 `scope` 按变动范围;HTTP 不传按 `full`;CLI 默认变动范围。每次审计都跑完整流程(静态初筛 + AST 语义检查),没有可调强度档位。
|
|
86
|
+
|
|
87
|
+
### 6. 规则包与槽位
|
|
88
|
+
|
|
89
|
+
- 规则目录里每个 `audit-rules-<名>.yml` = 一个槽位:放文件即生效、删文件即移除;yml 顶层 `disabled: true` = 整槽位默认不加载,`template` 槽位默认不加载。
|
|
90
|
+
- `nodejs` / `private` 是安全红线强制槽位,不可禁用。
|
|
91
|
+
- 启停方式:侧边栏「审计」选项卡规则包开关;HTTP `POST /api/git-push/toggle-rule`(body `{slot, disabled}`);脚本 `node scripts/rule-switch.mjs list|status|disable|enable <槽位>`(默认改安装版本,`--workspace` 指工作区,`--target <目录>` 任意指定)。
|
|
92
|
+
- 规则装载每次审计实时读 yml,改完立即生效、无需重启实例;规则可声明 `astConfirmKind`:正则初筛拿候选行 → AST 语义确认,减少误报。
|
|
93
|
+
|
|
94
|
+
### 7. 10 维度质量评分
|
|
95
|
+
|
|
96
|
+
| 维度 | 可读性 | 可维护性 | 健壮性 | 安全性 | 性能 | 测试覆盖 | 可观测性 | 可部署性 | 文档 | 开发者体验 |
|
|
97
|
+
|---|---|---|---|---|---|---|---|---|---|---|
|
|
98
|
+
| 默认权重 | 15 | 15 | 15 | 18 | 10 | 10 | 5 | 5 | 4 | 3 |
|
|
99
|
+
|
|
100
|
+
- 单维度:`max(0.1, 10 - k×ln(1+问题数))`,k 按维度分级(安全性衰减最快),下限 0.1 防零分塌陷。
|
|
101
|
+
- 总分:`Σ(维度分×权重)/Σ权重×10`,保留一位小数;等级 A ≥ 85、B ≥ 70、C ≥ 55、D ≥ 40,其余 E。
|
|
102
|
+
- 权重可调:侧边栏 `weightOverrides`(JSON)/ HTTP `weights` / CLI `--weights`;`scoreImpact: 0` 的纯提醒不计入评分,0 文件不评分。
|
|
103
|
+
|
|
104
|
+
### 8. 严重级(severity)与评分影响
|
|
105
|
+
|
|
106
|
+
| severity | 含义 | 门禁行为 |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `blocker` | 拦截级(`error` 归一为 blocker) | 拦截提交;private 仓库只报告不拦 |
|
|
109
|
+
| `warning` | 警告级 | 只提示 |
|
|
110
|
+
| `notice` | 提示级(`info` 归一为 notice) | 只提示 |
|
|
111
|
+
|
|
112
|
+
`scoreImpact` = 单条问题对评分的影响:`0` 纯提醒不扣分、`1` 常规、`2` 高危(如 blocker 凭据类);`summary` 汇总为 `{blocker, warning, notice, total}`。
|
|
113
|
+
|
|
114
|
+
### 9. 豁免机制
|
|
115
|
+
|
|
116
|
+
| 机制 | 位置 / 写法 | 效果 |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `.auditignore` | 仓库根,gitignore 语法 | 仓库级:声明不审计但照常入库;与 `.gitignore` 独立叠加;非 git 目录同样生效;`!` 前缀恢复 |
|
|
119
|
+
| `dsh-skip-*` 文件头注释 | 前 3 行内注释 | 整文件豁免对应拦截类型 |
|
|
120
|
+
| `dsh-skip-*` 行尾注释 | 对应行 / 函数定义行 | 单点豁免(仅 `sensitive` / `residue` / `func-length` / `complexity` / `i18n` 支持行级) |
|
|
121
|
+
| `.test` / `.samples` 空文件 | 目录内放 0 字节标记文件 | `.test` = 该目录(含子目录)整棵跳过扫描、不出任何结果;`.samples` = 照常出结果但不拦截(示例目录豁免) |
|
|
122
|
+
| 路径类别 | `test/`、`scripts/`、`cli.mjs` | 残留 / console / 同步 fs / 空 catch 等自动豁免 |
|
|
123
|
+
| 私有库 / 技能文档 | 远端 `private`;`skills/`、`rules/` 下 md | private 时私密文件与拦截降级为只报告;文档里的沟通措辞不触发沟通词规则 |
|
|
124
|
+
|
|
125
|
+
标记清单:`dsh-skip-sensitive`(凭据/私密)、`dsh-skip-size`(大文件/二进制)、`dsh-skip-func-length`(函数超长)、`dsh-skip-complexity`(圈复杂度/嵌套)、`dsh-skip-syntax`(语法 / JSON / YAML 解析)、`dsh-skip-quality`(质量评分类)、`dsh-skip-residue`(debugger / todo / console)、`dsh-skip-style`(数值风格)、`dsh-skip-i18n`(硬编码文案)。
|
|
126
|
+
|
|
127
|
+
```js
|
|
128
|
+
// dsh-skip-sensitive: 文件含 mock 凭据字面量(占位示例,非真实凭据)
|
|
129
|
+
console.log(x); // dsh-skip-residue: 本行为刻意保留的调试输出样本
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`secret-*` / `cred*` / `security/*` 类规则即使标 `disabled` 也强制加载——安全红线不可豁免。
|
|
133
|
+
|
|
134
|
+
### 10. 链接检查(link_check)
|
|
135
|
+
|
|
136
|
+
工具 `link_check`(`path` = 文件或目录,默认工作区)、CLI `git-sluice link-check <路径>`、斜杠命令 `/link-check [文件或目录]`。扫描 md / 文本内 URL 并访问验证:404 / 403 / 410 / 451 → 扣 3,DNS 失败 → 扣 2,超时 / 连接失败 / 5xx → 扣 1;只 warning,永不 blocker。配置 `linkCheckEnabled` 默认关(需要网络)。
|
|
137
|
+
|
|
138
|
+
### 11. 文档漂移检查(函数列表 / 目录树 / 版本表)
|
|
139
|
+
|
|
140
|
+
`node scripts/doc-func.mjs check`(函数列表)、`node scripts/doc-tree.mjs check`(目录树)、`node scripts/doc-version.mjs check`(版本表)分别比对宿主 md 标记块与最新内容并报漂移。三个脚本都有 `gen`(只打印)/ `apply`(覆盖标记块)/ `check`(报漂移);函数列表由 AST 真实扫描生成,避免手工维护漂移。
|
|
141
|
+
|
|
142
|
+
### 12. 报告聚合与 YAML 输出
|
|
143
|
+
|
|
144
|
+
- `groupBy` 四维度:`rule`(规则类型,默认)/ `file` / `severity` / `slot`(规则包);`groups` 按条数降序,每组带一条 `sample`;`severity` 白名单过滤 + `top` 截断(`0` = 全部),过滤后条数见 `filtered`。
|
|
145
|
+
- `exemptStats` 输出本次被豁免的类型与数量;`blocked` 直接列出 blocker 明细(文件 / 行 / 规则 / 消息);YAML 报告:HTTP `withYaml=true` → `yaml` 字段,工具 `includeFindings=true` 时含 `yaml`。
|
|
146
|
+
|
|
147
|
+
## 三、边界与坑
|
|
148
|
+
|
|
149
|
+
| 现象 | 原因 | 处理 |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| 结果里出现 `audit/scan-truncated` | 文件数超 `maxScanFiles`(默认 3000,`0` = 不限) | 调大上限或设 0;截断会优先纳入变动文件,该条 `scoreImpact: 0` 不扣分 |
|
|
152
|
+
| `quality` 为 null | 0 文件(空目录 / 0 变动) | 属正常「未评分」,不是满分 |
|
|
153
|
+
| 分数与预期差很多 | 权重被 `weightOverrides` 覆盖 | 核对侧边栏权重 / `weights` / `--weights` 三处来源 |
|
|
154
|
+
| 改了规则包不生效 | 改的是工作区文件,GUI 实际读安装版本 | 用 `scripts/rule-switch.mjs`(默认安装版本)或 `--workspace` 明确目标 |
|
|
155
|
+
| 想靠豁免消掉误报 | 豁免是逃生门,不是修误报 | 判定类误报修 AST 精筛;豁免只用于刻意样本 |
|
|
156
|
+
| 私有库被大量拦截 | 可见性探测失败按 `unknown` 保守拦截 | 确认 `origin` 指向;`private` 才只报告 |
|
|
157
|
+
| `.auditignore` 不生效 | 写法不是 gitignore 语义 | 用 gitignore 语法;`*.sh` 匹配任意层级,只根目录用 `/*.sh` |
|
|
158
|
+
| 自定规则目录参数名三端不同 | CLI 用 `--ruleset`,HTTP 用 `rulesetDir`,工具用法提示写作 `ruleset` | 以 CLI / HTTP 为准 |
|
|
159
|
+
|
|
160
|
+
## 四、配套 skill
|
|
161
|
+
|
|
162
|
+
| skill | 用途 |
|
|
163
|
+
|---|---|
|
|
164
|
+
| skills/guide/guide-commit-push.md | 提交前审计门禁、拦截与放行字段、私有库豁免 |
|
|
165
|
+
| skills/guide/guide-cli-scripts.md | 独立 CLI 与脚本(含 `git-sluice`、`rule-switch`) |
|
|
166
|
+
| skills/guide/guide-slash-completion.md | 输入框斜杠命令(`/git-audit`、`/link-check`) |
|
|
167
|
+
| skills/guide/guide-clone-repos.md | 克隆仓库与本地仓库扫描 |
|