dsh-git-push 0.0.0-stage → 2.8.6
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 +1486 -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 +266 -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 +192 -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 +672 -0
- package/lib/app/tools.js +34 -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 +215 -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 +137 -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 +148 -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 +476 -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 +171 -0
- package/lib/npm/registry.js +168 -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 +196 -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/cpu-sample.mjs +188 -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,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: guide-cli-scripts
|
|
3
|
+
description: dsh-git-push 功能说明:命令行与脚本(git-sluice CLI、随插件脚本清单与退出码)。处理命令行与脚本类请求时加载。
|
|
4
|
+
whenToUse: 要在终端直接用插件能力(审计/提交/扫描/索引),或问脚本都有哪些、怎么调时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 命令行与独立脚本(guide-cli-scripts)
|
|
10
|
+
|
|
11
|
+
> 一句话定位:**同一套引擎的两个脱离宿主入口**——`git-sluice` 是完整 CLI(审计/提交/扫描/索引),`scripts/` 下是一批可单独执行的小工具。
|
|
12
|
+
|
|
13
|
+
## 一、独立 CLI:git-sluice
|
|
14
|
+
|
|
15
|
+
脱离 DSH 独立运行(零第三方依赖,仅需 Node ≥18 与本机 git)。装在 PATH 里后直接敲:
|
|
16
|
+
|
|
17
|
+
| 子命令 | 作用 | 关键参数 |
|
|
18
|
+
|--------|------|----------|
|
|
19
|
+
| `version` | 查看版本 | — |
|
|
20
|
+
| `ruleset [槽位...]` | 编译规则包并输出统计 | 槽位名(可多个) |
|
|
21
|
+
| `scan <root>` | 全量扫描目录(非 git 目录也能查) | `--depth N` |
|
|
22
|
+
| `repos <root>` | 扫描本地 git 仓库(尊重 `.gitignore`,被忽略目录整棵跳过) | `--depth N`、`--max N`、`--json` |
|
|
23
|
+
| `index <root>` | 重建仓库索引 `dsh-repo-index.json` | `--owner <账号>`、`--depth N`、`--max N`、`--offline`、`--json` |
|
|
24
|
+
| `audit <root>` | 审计并输出质量评分与 findings | `--full`、`--level quick\|standard\|deep`、`--ruleset <目录>`、`--weights <JSON>`、`--include-ignored`、`--json` |
|
|
25
|
+
| `commit <repo>` | 提交(可选推送) | `-m <msg>`、`--push`/`--no-push`、`--dry-run`、`--force`、`--req-confirm`、`--json` |
|
|
26
|
+
| `link-check <路径>` | 检查 md/文本里的链接有效性(只 warning) | — |
|
|
27
|
+
| `yaml-template` | 输出规则 yml 模板 | — |
|
|
28
|
+
| `readme-template` | 输出 README 模板 | — |
|
|
29
|
+
| `self-check` | 版本一致性 + HELP 与参数解析机器比对 | — |
|
|
30
|
+
|
|
31
|
+
### 「功能一致、结果一致」的硬约定
|
|
32
|
+
|
|
33
|
+
CLI 是同一引擎的独立入口,**不另写一份逻辑**:
|
|
34
|
+
|
|
35
|
+
- **同一实现**:`repos` → 插件本地扫描同一函数;`index` → 索引维护同一函数;`audit`/`scan` → 审计编排同一入口
|
|
36
|
+
- **同一配置**:读**同一份**插件配置(`<DSH 配置目录>/git-push/config.json`),因此文件上限、规则包顺序、禁用槽位、权重覆盖全部生效
|
|
37
|
+
- **同一优先级**:显式 `--weights` > 配置里的权重覆盖 > 默认权重表
|
|
38
|
+
- **结果可对齐**:同一仓库同一参数下,CLI 的 `audit . --full` 与插件的 `code_audit{repo, scope:'full'}` 输出应一致(评分、summary、findings 条数)
|
|
39
|
+
|
|
40
|
+
### 例子
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
git-sluice version
|
|
44
|
+
git-sluice audit . --full --json
|
|
45
|
+
git-sluice repos /path/to/workspace --max 50 --json
|
|
46
|
+
git-sluice index /path/to/workspace --owner EIGHTfs --offline
|
|
47
|
+
git-sluice commit /path/to/repo -m "fix: 修正 xx" --no-push
|
|
48
|
+
git-sluice self-check
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 二、随插件发布的独立脚本
|
|
52
|
+
|
|
53
|
+
脚本**不注册插件入口**(不进工具/API/设置项),只作为可执行脚本供 AI 或人手动调用;随插件发布,安装副本目录里同样能跑。
|
|
54
|
+
|
|
55
|
+
### 使用者可直接用
|
|
56
|
+
|
|
57
|
+
| 脚本 | 作用 | 用法要点 |
|
|
58
|
+
|------|------|----------|
|
|
59
|
+
| `scripts/rule-switch.mjs` | 手动启停安装版本的规则槽位(与侧边栏 UI 启停同一套实现) | `node scripts/rule-switch.mjs <status\|enable\|disable> <槽位>` |
|
|
60
|
+
| `scripts/scrub-user-wording.mjs` | 清洗代码注释里的沟通残留措辞(只警告不改、逐条确认、每文件 `.bak`) | `node scripts/scrub-user-wording.mjs <路径...> [--apply [--yes]]`;`--repo <仓库>` 只处理未提交 diff |
|
|
61
|
+
| `scripts/audit-runtime-check.mjs` | 三层审计的 L3 运行时检测:动态 import 后清空再访问,抓静态查不出的 bug | `node scripts/audit-runtime-check.mjs <js 文件> [--obj 名]`;`--all <目录>` |
|
|
62
|
+
| `scripts/scan-file-io.mjs` | 扫描脚本里的文件读写调用与路径,标四级风险(与审计 `robustness/io-risk` 同标准) | `node scripts/scan-file-io.mjs <路径> [--write]` |
|
|
63
|
+
| `scripts/scan-repos.mjs` | 扫描本地 git 仓库清单 | `node scripts/scan-repos.mjs --root <root> --owner <owner> [--depth 10] [--max 200]` |
|
|
64
|
+
| `scripts/audit-runner.mjs` | 跑 `scripts/audit-ext/` 下全部审计扩展 | `node scripts/audit-runner.mjs <仓库>` |
|
|
65
|
+
|
|
66
|
+
### 开发者维护用
|
|
67
|
+
|
|
68
|
+
| 脚本 | 作用 |
|
|
69
|
+
|------|------|
|
|
70
|
+
| `scripts/check.mjs` | 语法检查(递归查 lib 与 CLI 入口) |
|
|
71
|
+
| `scripts/scan-version.mjs` | 版本一致性校验(三处版本号是否同步) |
|
|
72
|
+
| `scripts/doc-func.mjs` / `doc-tree.mjs` / `doc-version.mjs` | 函数列表 / 目录树 / 版本记录 三份文档与代码同步(`check` 查漂移、`apply` 写回) |
|
|
73
|
+
| `scripts/readme-gen.mjs` | README 生成 |
|
|
74
|
+
| `scripts/preview-gen.mjs`(默认生成 / `--data-only` 只更数据段 / `check` 漂移门禁 / `--watch` 监听) / `scripts/preview-server.mjs`(默认反代真后端 / `--direct` 直连插件 / `--local` 免重启) | 界面预览页生成与漂移门禁、本地真实后端测试服务 |
|
|
75
|
+
| `scripts/browser-page-probe.mjs` | 无头浏览器探针:读页面真实渲染文本 + 抓前端运行时错误(零硬编码路径,自动探测环境) |
|
|
76
|
+
| `scripts/sync-plugin.mjs` | 双副本同步(工作区 ↔ 安装副本)+ 部署形态与免重启热重载自检:`--profile <名>` 指定 profile(多 profile 必给)、`--fix` 按目标形态修正(local-plugins 真实目录 + node_modules 相对软链) |
|
|
77
|
+
| `scripts/sync-plugin-install.mjs` | 安装形态 / HMR 自检的实现模块(`sync-plugin.mjs` 引用,非独立入口) |
|
|
78
|
+
| `scripts/verify-prestep.mjs` | 上下文注入自检(真实触发 pre-step 校验注入内容) |
|
|
79
|
+
| `scripts/rename-locator.mjs` | 变量重命名位置定位(按作用域聚合) |
|
|
80
|
+
| `scripts/rules-solo-audit.mjs` | 单条 yml 规则的控制变量评估 |
|
|
81
|
+
| `scripts/probe-recheck.mjs` | 「重新检测」按钮链路实测探针(联网) |
|
|
82
|
+
|
|
83
|
+
## 三、退出码语义(脚本约定)
|
|
84
|
+
|
|
85
|
+
| 退出码 | 含义 |
|
|
86
|
+
|--------|------|
|
|
87
|
+
| 0 | 成功 / 无命中 |
|
|
88
|
+
| 1 | 失败 / 有命中(如运行时检测抓到 bug、语法检查失败) |
|
|
89
|
+
| 2 | dry-run 有命中(措辞清洗)/ 无法检测(运行时检测) |
|
|
90
|
+
| 3 | 非交互环境未带 `--yes`,拒绝写盘 |
|
|
91
|
+
|
|
92
|
+
## 四、边界与坑
|
|
93
|
+
|
|
94
|
+
- CLI 与插件**读同一份配置**:改设置会同时影响两边;排查「CLI 与插件结果不一致」时先比配置
|
|
95
|
+
- 措辞清洗**只改注释段**(词法感知,字符串里的措辞不动),md 会跳过 ``` 围栏代码块;private 仓库的工作留痕措辞通常**不需要**清洗
|
|
96
|
+
- 运行时检测只能测模块**导出**的入口,内部闭包需测试钩子;依赖被测文件能安全 import
|
|
97
|
+
- 文档同步类脚本(`doc-*`)是**维护动作**:改了代码/提交后要跑 `apply`,否则漂移检查会报
|
|
98
|
+
- 脚本路径一律相对插件根;安装副本目录里同样按此相对路径执行
|
|
99
|
+
|
|
100
|
+
## 五、相关功能
|
|
101
|
+
|
|
102
|
+
- 审计规则、评分、豁免细节 → `guide/guide-audit`
|
|
103
|
+
- 提交推送门禁与返回字段 → `guide/guide-commit-push`
|
|
104
|
+
- 仓库索引与克隆 → `guide/guide-clone-repos`
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: guide-clone-repos
|
|
3
|
+
description: dsh-git-push 功能说明:克隆与仓库(预览、进度、断点续传、扫描、建远端、可见性)。处理克隆与仓库管理类请求时加载。
|
|
4
|
+
whenToUse: 要克隆仓库、查克隆进度/中止、扫描本地仓库、建远端或改可见性、查账号与配额时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 克隆与仓库管理(guide-clone-repos)
|
|
10
|
+
|
|
11
|
+
> 一句话定位:把「从 GitHub 拿代码」和「本机仓库台账」做成一整套工具 + 后台接口——克隆走 GitHub Git Data API(不直连 github.com),大仓库放后台跑、进度可轮询、断了能续传、少文件如实报告。
|
|
12
|
+
|
|
13
|
+
## 一、这个功能能干什么
|
|
14
|
+
|
|
15
|
+
| 能力 | 说明 |
|
|
16
|
+
|---|---|
|
|
17
|
+
| 克隆仓库 | `git_clone` 按 `owner/repo` 或 URL 拉整仓到目标目录,末尾自动 `git init` + `git add -A` + 建初始提交,并把 `origin` 指向 `api.github.com/repos/<owner>/<repo>` |
|
|
18
|
+
| 克隆预演 | `git_clone_preview` 只读远端文件树,报告「将下载几个文件/多少字节、会跳过哪些超大文件」,**不下载、不落盘** |
|
|
19
|
+
| 后台 job | 工具侧注册宿主官方后台 job(立即返回 jobId,用 `job_output`/`job_list`/`job_kill` 查/停);HTTP 侧 `/repo-clone` 立即返回 202 + jobId,用 `/clone-progress` 轮询 |
|
|
20
|
+
| 断点续传 | 分片目录 `.dsh-parts` 内按 blob sha 存 `<sha>.part`,中断后按 `Range` 续传;已下完的成品按长度直接复用,不重下 |
|
|
21
|
+
| 体积守卫 | 单文件超过阈值(默认 10MB,HTTP 端可配 `maxCloneFileMB`,0=不限)直接跳过并**如实回传**,不静默少文件 |
|
|
22
|
+
| 本地仓库扫描 | `git_scan` 逐层下钻列仓库:分支 / 远端(脱敏)/ 未提交数 / 最近提交 / 领先落后 |
|
|
23
|
+
| 远端仓库管理 | `git_remote_create` 建仓(默认 private,已存在则复用并设 origin);`git_set_visibility` 切 public/private |
|
|
24
|
+
| 账号与配额 | 账号状态(离线读快照)/ 在线校验 / API 配额查询(`/rate_limit`,不消耗配额) |
|
|
25
|
+
| 仓库索引 | 推送成功、云端加载、本地扫描时维护 `dsh-repo-index.json`;本地仓库列表据此标注每个仓库的 GitHub 归属 |
|
|
26
|
+
|
|
27
|
+
## 二、怎么用(工具 + HTTP 接口参数表与返回字段)
|
|
28
|
+
|
|
29
|
+
### 2.1 工具 `git_clone`
|
|
30
|
+
|
|
31
|
+
| 参数 | 类型 | 必填 | 默认 | 说明 |
|
|
32
|
+
|---|---|---|---|---|
|
|
33
|
+
| `target` | string | ✅ | — | `owner/repo` 或完整 GitHub URL |
|
|
34
|
+
| `dest` | string | — | 省略时落到「进程当前工作目录/<仓库名>」 | **目标目录本身**(不是父目录);目录已存在且非空会拒绝覆盖 |
|
|
35
|
+
| `branch` | string | — | 仓库默认分支 | 分支名 |
|
|
36
|
+
|
|
37
|
+
即时返回:
|
|
38
|
+
|
|
39
|
+
| 字段 | 说明 |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `ok` | 是否受理 |
|
|
42
|
+
| `async` | `true` = 已注册后台 job;`false` = 同步执行完(宿主无 job 控制器时) |
|
|
43
|
+
| `jobId` | 后台 job id(如 `git-clone-1`) |
|
|
44
|
+
| `jobFallback` | `true` = 已降级同步执行,结果在 `result` |
|
|
45
|
+
| `result` | 同步执行时的克隆结果(字段同 job 完成输出) |
|
|
46
|
+
| `hint` | 查询提示文案 |
|
|
47
|
+
|
|
48
|
+
job 完成输出(JSON 字符串):成功 `{ok,owner,repo,branch,commitSha,dest,files,total,method:"api",skipped[],skippedCount,modePreserved,metadataSupported}`;失败 `{ok:false,error,cause,retriable,files,total,failed:[{path,status,reason}],failedCount,skipped[],skippedCount,kept:true,resumable:true}`。
|
|
49
|
+
|
|
50
|
+
### 2.2 工具 `git_clone_preview`
|
|
51
|
+
|
|
52
|
+
参数 `target`(必填)、`branch`。返回 `{ok,owner,repo,branch,totalFiles,downloadCount,downloadBytes,skipped[],skippedCount,skippedBytes,maxFileMB,empty}`——`empty:true` 表示文件全被体积阈值跳过(会得到一个空目录,要强提示)。
|
|
53
|
+
|
|
54
|
+
### 2.3 HTTP 接口
|
|
55
|
+
|
|
56
|
+
| 接口 | 方法 | 请求体 | 状态码 | 返回关键字段 |
|
|
57
|
+
|---|---|---|---|---|
|
|
58
|
+
| `/api/git-push/repo-clone` | POST | `{target, dir, confirm:true}` | 202 / 400 / 409 | 202 `{ok,async:true,jobId,target,dest,totalFiles,totalBytes,hint}`;400 缺 target/dir/解析失败/预演失败;409 已有克隆在跑 `{cause:"busy",retriable:false,running}` |
|
|
59
|
+
| `/api/git-push/clone-preview` | POST | `{target, maxFileMB?}` | 200 / 400 | 同 2.2 的预演结果;进程内缓存 60 秒 |
|
|
60
|
+
| `/api/git-push/clone-progress` | GET/POST | `{consume?}` | 200 | `{ok,state:"running"\|"done"\|"idle", progress?, result?}`;`consume:true` 取走终态后清空 |
|
|
61
|
+
| `/api/git-push/clone-logs` | GET/POST | `{limit?}` | 200 | `{ok,logs:[{at,event,...}]}`,默认 200 条(环形缓冲上限 200) |
|
|
62
|
+
| `/api/git-push/clone-abort` | POST | — | 200 | `{ok,aborted:true\|false}` |
|
|
63
|
+
| `/api/git-push/account-status` | GET | — | 200 | 离线快照 `{ok,offline:true,loggedIn,username,tokenConfigured,sshConfigured,tokenStatus,sshStatus,checkedAt,apiQuota,block}` |
|
|
64
|
+
| `/api/git-push/account-check` | POST | `{githubToken?,sshPub?,checkSsh?}` | 200 | 在线校验并写快照 `{ok,loggedIn,username,name,profileUrl,publicRepos,plan,tokenStatus,sshStatus,apiQuota,block,statusUpdated,status}` |
|
|
65
|
+
| `/api/git-push/api-quota` | GET | `?refresh=1` | 200 | `{ok,core{limit,remaining,resetAt},search,graphql,codeSearch,fetchedAt,cached,statusUpdated}` |
|
|
66
|
+
|
|
67
|
+
- `progress` 字段:`target/dest/phase/done/totalFiles/transferred/totalBytes/failed/elapsedMs/stalledMs/percent`(`percent` 按字节算、上限 99;`phase` 取值 `downloading` → `done`)。
|
|
68
|
+
- `result`(终态):`{ok,error,finishedAt,…终态进度快照}`。
|
|
69
|
+
- `/repo-clone` 属破坏性端点,body 必须显式带 `confirm:true`,否则 400 `NEED_CONFIRM`。
|
|
70
|
+
- 账号状态查询:`/account-status` 是**离线读** json 快照(秒级、不联网),`/account-check` 才联网校验并回写快照;登录判定为 `token 有效 || ssh 有效`。
|
|
71
|
+
|
|
72
|
+
### 2.4 仓库扫描与远端管理
|
|
73
|
+
|
|
74
|
+
- `git_scan`:参数 `root`(省略时用配置 `defaultScanRoot`,未配置则自动识别 DSH 家根)、`paths`(额外仓库路径,逗号分隔)、`extraReposFile`(清单文件,每行一个路径、`#` 注释)。返回 `{ok,root,count,paths,extraReposFile,repos[]}`;`repos` 项字段 `name/path/branch/remote(脱敏)/changed/lastCommit/hasRemote/upstream/ahead/behind`。扫描跳过 `node_modules`、隐藏目录、被 `.gitignore` 忽略的目录,depth 20、最多 200 个仓库。
|
|
75
|
+
- `git_remote_create`:参数 `repo`(本地仓库路径,必填)、`visibility`(`public|private`,默认 `private`)、`dryRun`。三种返回:已存在 `{ok:true,exists:true,owner,name,visibility,reason:"已存在同名仓库"}`;预演 `{ok:true,dryRun:true,wouldCreate:true,owner,name,visibility}`;新建 `{ok:true,created:true,owner,name,visibility,origin}`。
|
|
76
|
+
- `git_set_visibility`:参数 `repo`(本地仓库路径)、`visibility`(`public|private`,必填)。从本地 `origin` 解析 owner/repo,返回 `{ok,owner,repo,visibility,to}`;需要 token。
|
|
77
|
+
|
|
78
|
+
## 三、可直接复制的例子(真实调用 + 预期结果)
|
|
79
|
+
|
|
80
|
+
**① 先预演,再克隆(工具)**
|
|
81
|
+
|
|
82
|
+
```js
|
|
83
|
+
git_clone_preview({ target: "EIGHTfs/dsh-git-push" })
|
|
84
|
+
// → { ok:true, branch:"master", totalFiles:312, downloadCount:310, downloadBytes:1234567,
|
|
85
|
+
// skipped:[{ path:"assets/demo.mp4", size:52428800, sha:"…" }], skippedCount:2, skippedBytes:52428800, maxFileMB:10, empty:false }
|
|
86
|
+
|
|
87
|
+
git_clone({ target: "EIGHTfs/dsh-git-push", dest: "<目标目录>", branch: "master" })
|
|
88
|
+
// → { ok:true, async:true, jobId:"git-clone-1", hint:"已注册宿主后台 job…" }
|
|
89
|
+
// job 完成后:{ ok:true, owner:"EIGHTfs", repo:"dsh-git-push", branch:"master", commitSha:"…",
|
|
90
|
+
// dest:"<目标目录>", files:310, total:312, method:"api", skippedCount:2, modePreserved:true }
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**② HTTP 后台克隆 + 轮询进度 + 取终态**
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
curl -s -X POST "$BASE/api/git-push/repo-clone" -H 'content-type: application/json' \
|
|
97
|
+
-d '{"target":"EIGHTfs/dsh-git-push","dir":"<父目录>","confirm":true}'
|
|
98
|
+
# → 202 {"ok":true,"async":true,"jobId":"clone-1a2b3c","dest":"<父目录>/dsh-git-push","totalFiles":312,"totalBytes":153800000}
|
|
99
|
+
|
|
100
|
+
curl -s -X POST "$BASE/api/git-push/clone-progress" -d '{}'
|
|
101
|
+
# → {"ok":true,"state":"running","progress":{"phase":"downloading","done":120,"totalFiles":310,
|
|
102
|
+
# "transferred":73400320,"totalBytes":153800000,"failed":0,"percent":47,"stalledMs":820,"elapsedMs":41000}}
|
|
103
|
+
|
|
104
|
+
curl -s -X POST "$BASE/api/git-push/clone-progress" -d '{"consume":true}'
|
|
105
|
+
# → {"ok":true,"state":"done","result":{"ok":true,"finishedAt":…,"dest":"…"}}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**③ 中止 / 看克隆日志 / 查配额**
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
curl -s -X POST "$BASE/api/git-push/clone-abort" -d '{}' # → {"ok":true,"aborted":true}
|
|
112
|
+
curl -s -X POST "$BASE/api/git-push/clone-logs" -d '{"limit":20}' # → {"ok":true,"logs":[{"at":"…","event":"start",…}]}
|
|
113
|
+
curl -s "$BASE/api/git-push/api-quota?refresh=1" # → {"ok":true,"core":{"limit":5000,"remaining":4821,"resetAt":"…"}}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**④ 扫仓库 / 建远端 / 改可见性**
|
|
117
|
+
|
|
118
|
+
```js
|
|
119
|
+
git_scan({ root: "<扫描根>", paths: "<额外仓库路径>" })
|
|
120
|
+
git_remote_create({ repo: "<本地仓库路径>", dryRun: true }) // 先预演:只探测,不建
|
|
121
|
+
git_remote_create({ repo: "<本地仓库路径>", visibility: "private" })
|
|
122
|
+
git_set_visibility({ repo: "<本地仓库路径>", visibility: "private" })
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## 四、断点续传与失败重试(怎么判断进度、失败怎么办)
|
|
126
|
+
|
|
127
|
+
**判断进度**:`percent` 按已传字节算(总量未知时退回文件数);`stalledMs` = 距上次**有字节增长**的毫秒数,用来判「卡死」——比绝对超时合理(大文件传得慢但进度在涨不算卡死)。`phase` 只有 `downloading` → `done`。
|
|
128
|
+
|
|
129
|
+
**续传三层机制**:
|
|
130
|
+
|
|
131
|
+
1. **分片**:每个文件先写 `.dsh-parts/<sha>.part`,长度校验通过才原子 rename 到最终路径——最终路径上不会出现半截文件。
|
|
132
|
+
2. **Range 续传**:`.part` 存在且小于远端 size → 请求带 `Range: bytes=<已有字节>-`;远端回 206 就追加写,回 200(忽略 Range / 文件已变)就清空重下。
|
|
133
|
+
3. **成品复用**:最终路径文件长度 == 远端 size → 直接判成功,不再重下。
|
|
134
|
+
|
|
135
|
+
**失败保留与自愈**:有失败项时**保留** `.dsh-parts`(下轮继续续传),只有全部成功才清分片目录;克隆失败**不删目录**,返回 `kept:true` / `resumable:true`,已下好的文件全部留着。再次克隆时,目录内有进行中标记 `.dsh-git-push-cloning` 且没有有效 HEAD(或目录里只剩 `.dsh-parts`)→ 判为上次残留,自动续传,不会撞「目录非空」拒绝。
|
|
136
|
+
|
|
137
|
+
**失败成因决定要不要重试**(看返回的 `cause` / `retriable`):
|
|
138
|
+
|
|
139
|
+
| `cause` | 触发 | `retriable` | 怎么办 |
|
|
140
|
+
|---|---|---|---|
|
|
141
|
+
| `auth` | 401 | ❌ | 换 token / 确认该仓库权限 |
|
|
142
|
+
| `notfound` | 404 | ❌ | 确认 owner/repo 是否正确、token 是否可见该仓库 |
|
|
143
|
+
| `ratelimit` | 403 / 429 | ✅ | 等限流窗口过去再试 |
|
|
144
|
+
| `server` | 5xx | ✅ | 稍后重试 |
|
|
145
|
+
| `network` | status 0(超时 / 断网) | ✅ | 直接重试(分片会续传) |
|
|
146
|
+
| `disk` | 本地写盘 / 软链失败 | ✅ | 查目标目录权限与磁盘空间 |
|
|
147
|
+
|
|
148
|
+
**双通道**:常态先走 `api.github.com`(稳定,但忽略 Range),需要续传(已有分片)或 api 失败时退 `raw.githubusercontent.com`(支持 Range,并发不稳)——首个成功即用,全失败才报错。分片以 sha 命名,sha 变了自然换文件,不会把新旧内容拼成损坏文件。
|
|
149
|
+
|
|
150
|
+
## 五、边界与坑
|
|
151
|
+
|
|
152
|
+
| 现象 | 原因 | 处理 |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| 409 `cause:"busy"` | 同一时刻只允许一个克隆任务(内存态单任务,不区分目标目录) | 等当前任务结束,或先调 `/clone-abort` |
|
|
155
|
+
| 400 `NEED_CONFIRM` | `/repo-clone` 是破坏性端点,body 没带 `confirm:true` | 补 `confirm:true` |
|
|
156
|
+
| 400 目标目录已存在且非空 | 目录不是本插件的失败残留(无进行中标记) | 换目录,或自行清空后重试 |
|
|
157
|
+
| 拒绝克隆到既有 git 仓库内 | 目标目录落在某仓库工作树里,末尾 `git init/add/commit` 会写进父仓库历史 | 换到仓库外的目录 |
|
|
158
|
+
| 克隆成功但可执行位没保住 | 目标文件系统(CIFS)不支持元数据 | 看返回 `modePreserved:false` / `metadataSupported:false`,属如实回报不是失败 |
|
|
159
|
+
| 少文件 | 单文件超过体积阈值被跳过 | 看 `skipped` / `skippedCount`;要全量就调大阈值或设 0(**HTTP 端读配置 `maxCloneFileMB`/`cloneConcurrency`;`git_clone` 工具固定用默认 10MB、并发 6**) |
|
|
160
|
+
| 进度查不到 | 进度是内存态,随进程存亡,进程重启即丢 | 重启后重新发起克隆(已下文件与分片仍会续传) |
|
|
161
|
+
| `skipped` / `failed` 列表不全 | 返回列表有上限(跳过 50 条、失败 20 条) | 用 `skippedCount` / `failedCount` 判断真实规模 |
|
|
162
|
+
| `origin` 是 `api.github.com/repos/...` | 走 Git Data API 建仓,origin 写 API 地址(插件凭据通道用) | 属正常;用 `git_sluice` 执行 git 命令时凭据自动注入 |
|
|
163
|
+
| 账号状态显示未配置但推送正常 | `/account-status` 是**离线读**的旧快照 | 调 `/account-check` 在线校验,或点侧边栏「重新检测」 |
|
|
164
|
+
|
|
165
|
+
## 六、相关功能
|
|
166
|
+
|
|
167
|
+
| 功能 | 关系 |
|
|
168
|
+
|---|---|
|
|
169
|
+
| `git_commit_push` | 克隆完成后的提交推送(审计门禁 + 凭据注入);推送成功会重建仓库索引 |
|
|
170
|
+
| `git_sluice` | 在克隆下来的仓库里执行 log/diff/branch 等 git 命令(凭据自动注入) |
|
|
171
|
+
| `git_account_check` / `git_cred_env` | 克隆私有库前先确认 token/SSH 可用;外部命令取凭据环境前缀 |
|
|
172
|
+
| `dsh-repo-index.json` | 仓库索引(权威源码索引,存插件配置目录 `DSH_HOME/git-push/`):记录每个项目的仓库地址、可见性、恢复命令 `cloneCmd`、skills 与本地 `path`,`version` 恒为 1、`generatedAt` 每次刷新;源码丢失时按它 `git_clone` 恢复,本地列表据此标注仓库归属 |
|
|
173
|
+
| 侧边栏「账号信息 → 仓库管理」 | 本地子选项卡按索引标注归属并可 `push`;云端子选项卡「加载仓库列表」选目录后走同一套后台克隆 |
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: guide-commit-push
|
|
3
|
+
description: dsh-git-push 功能说明:提交推送(凭据、提交前门禁、自动推送、返回字段)。处理提交推送类请求时加载。
|
|
4
|
+
whenToUse: 要提交/推送代码、查凭据放哪、被门禁拦住要放行、或想开任务完成自动推送时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 提交推送(guide-commit-push)
|
|
10
|
+
|
|
11
|
+
> 一句话定位:把「审计门禁 → add/commit → 推送」固化成一次工具调用,凭据由插件托管,AI 不必手敲 git 命令。
|
|
12
|
+
|
|
13
|
+
## 一、这个功能能干什么
|
|
14
|
+
|
|
15
|
+
| 能力 | 说明 |
|
|
16
|
+
|---|---|
|
|
17
|
+
| 一键提交推送 | `git_commit_push` 一条调用完成 add + commit + push(默认全量暂存,也可只暂存指定路径) |
|
|
18
|
+
| 提交前审计门禁 | 先跑代码审计,命中 blocker 立即拦截、**不执行任何 git 操作**;warning/notice 只提示不拦 |
|
|
19
|
+
| 凭据托管 | GitHub token 与 SSH 公钥统一存在插件配置目录,推送时自动注入,无需手动配 git 凭据 |
|
|
20
|
+
| 推送通道 | `ssh`(默认,推本地 HEAD,远端 sha 与本地一致)/ `api`(Git Data API 重建提交)/ `auto`(有私钥走 ssh,否则 api) |
|
|
21
|
+
| 后台任务 | commit+push 注册为宿主官方后台 job,工具立即返回 `jobId`;宿主无 job 控制器时同步执行保底 |
|
|
22
|
+
| 门禁开关 | `requirementsConfirmed`(开发者要求核对)、`pushConfirmed`(推送门禁放行)、`force`(强推)、`dryRun`(只预演) |
|
|
23
|
+
| 任务完成自动推送 | 开关开启后,AI 回合结束的回复里含指定完成文案,自动对目标仓库走同一套门禁提交推送 |
|
|
24
|
+
| 私有库豁免 | 远端可见性 = private 时,审计只报告不拦截;敏感文件只扫描报告、不改写忽略配置 |
|
|
25
|
+
|
|
26
|
+
## 二、怎么用
|
|
27
|
+
|
|
28
|
+
### 参数表(工具 `git_commit_push`)
|
|
29
|
+
|
|
30
|
+
| 参数 | 类型 | 必填 | 默认 | 说明 |
|
|
31
|
+
|---|---|---|---|---|
|
|
32
|
+
| `repo` | string | ✅ | — | 本地 git 仓库根目录路径 |
|
|
33
|
+
| `message` | string | ✅ | — | commit message;空/纯空白直接拒绝 |
|
|
34
|
+
| `push` | boolean | — | `true` | `false` = 只提交不推送 |
|
|
35
|
+
| `audit` | boolean | — | 取配置 `auditEnabled`(默认关) | `true` 强制审计、`false` 跳过本次审计 |
|
|
36
|
+
| `dryRun` | boolean | — | `false` | 只预演:跑门禁与流程、不写盘、不 commit、不 push |
|
|
37
|
+
| `force` | boolean | — | `false` | 强推覆盖远端历史(SSH 用 `--force`;API 通道重建提交、不挂旧 parent) |
|
|
38
|
+
| `ignorePatterns` | string | — | 空 | 追加进 `.gitignore` 的自定义忽略项(逗号/换行分隔,幂等) |
|
|
39
|
+
| `requirementsConfirmed` | boolean | — | `false` | 开发者要求清单已逐条核对达标才置 `true`,否则被拦 |
|
|
40
|
+
| `pushConfirmed` | boolean | — | `false` | 推送门禁(配置 `pushGate`)开启时,推必须显式放行 |
|
|
41
|
+
| `paths` | string | — | 空 | 精确 add 路径(逗号分隔,相对仓库);空 = 全量暂存 |
|
|
42
|
+
|
|
43
|
+
### 返回字段(即时返回)
|
|
44
|
+
|
|
45
|
+
| 字段 | 说明 |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `ok` | 调用是否被受理/成功;被门禁拦截时为 `false` |
|
|
48
|
+
| `async` | `true` = 已注册后台 job(结果完成会自动回传);`false` = 同步执行完 |
|
|
49
|
+
| `jobId` | 后台任务 id(如 `git-push-1`),可用宿主 `job_output` / `job_list` / `job_kill` 查询或中止 |
|
|
50
|
+
| `jobFallback` | `true` = 宿主后台 job 不可用,已自动降级为同步执行(结果就在 `result`) |
|
|
51
|
+
| `audit` | 审计摘要(`summary` 各级数量 / `quality` 评分 / `blocked` 拦截明细 / `privateExempt` 私有库豁免标记);未开审计时为 `null` |
|
|
52
|
+
| `hint` | 查询提示文案 |
|
|
53
|
+
| `error` / `blocked` / `code` | 失败或拦截说明;`code` 取值 `USER_REQUIREMENTS`、`PUSH_GATE` |
|
|
54
|
+
|
|
55
|
+
### 返回字段(最终结果 `result`——后台 job 完成输出,或同步执行直接返回)
|
|
56
|
+
|
|
57
|
+
| 字段 | 说明 |
|
|
58
|
+
|---|---|
|
|
59
|
+
| `result.commitSha` | 本次提交的 sha(无变更/预演时可能没有) |
|
|
60
|
+
| `result.pushed` | 是否真的推送到远端 |
|
|
61
|
+
| `result.committed` | 是否产生了新提交(无变更跳过时为 `false`) |
|
|
62
|
+
| `result.push.method` | 实际走的通道:`ssh` / `api` / `ssh-fallback` |
|
|
63
|
+
| `result.push.owner` / `repo` / `branch` | 推送目标(从 origin 解析) |
|
|
64
|
+
| `result.push.fallbackReason` | 主通道失败回落另一通道的原因 |
|
|
65
|
+
| `result.push.remoteRef` / `auxRemote` | 本地远端跟踪引用更新结果 / 辅助 SSH remote(`github-ssh`)就绪情况 |
|
|
66
|
+
| `result.autoTag` | 推送成功后对 `dsh-` 前缀项目按 `package.json` 版本自动打 tag 的结果 |
|
|
67
|
+
| `result.remoteHeads` | 远端该分支最近 3 条提交(核对远端真实状态用) |
|
|
68
|
+
| `result.indexUpdated` | `true` = 推送成功后本地仓库索引已重建 |
|
|
69
|
+
| `result.steps` | 逐步痕迹:`预检` / `敏感文件 .gitignore` / `private-exempt(...)` / `add` / `commit` / `push` / `pushed-via-ssh` 等 |
|
|
70
|
+
| `result.message` / `error` | 跳过原因(如「无变更,跳过提交」)或失败原因 |
|
|
71
|
+
|
|
72
|
+
## 三、可直接复制的例子
|
|
73
|
+
|
|
74
|
+
**① 标准提交推送**(要求清单存在时必须带核对标记)
|
|
75
|
+
|
|
76
|
+
```js
|
|
77
|
+
git_commit_push({ repo: "<仓库路径>", message: "feat: 新增 XX 能力", requirementsConfirmed: true })
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
预期:`{ ok:true, async:true, jobId:"git-push-1", audit:{ summary:{...}, quality:{...} } }`;job 完成后输出 `{ ok:true, commitSha:"a1b2c3d…", pushed:true, push:{ method:"ssh", branch:"master" }, indexUpdated:true }`。
|
|
81
|
+
|
|
82
|
+
**② 只提交不推送 / 先预演 / 只提交指定文件**
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
git_commit_push({ repo: "<仓库路径>", message: "docs: 更新说明", push: false, requirementsConfirmed: true })
|
|
86
|
+
git_commit_push({ repo: "<仓库路径>", message: "feat: 试跑", dryRun: true })
|
|
87
|
+
// 零改动也照样调用:没有新提交时同样返回 ok:true(committed:false),
|
|
88
|
+
// 而「本地领先远端」的已提交内容会照常推上去 —— 不要因为「没东西可提交」改去手敲 git
|
|
89
|
+
git_commit_push({ repo: "<仓库路径>", message: "(零改动时用不到)", requirementsConfirmed: true })
|
|
90
|
+
git_commit_push({ repo: "<仓库路径>", message: "fix: 修正解析", paths: "src/parser.js,README.md", requirementsConfirmed: true })
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
预演预期:`{ ok:true, async:true, jobId:"git-push-2" }`,完成后 `{ ok:true, dryRun:true, steps:["预检","commit","push"] }`(无任何写入)。
|
|
94
|
+
|
|
95
|
+
**③ 推送门禁已开启时显式放行 / 强推**
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
git_commit_push({ repo: "<仓库路径>", message: "chore: 同步", requirementsConfirmed: true, pushConfirmed: true })
|
|
99
|
+
git_commit_push({ repo: "<仓库路径>", message: "chore: 重写历史后同步", force: true, requirementsConfirmed: true, pushConfirmed: true })
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**④ 被拦后的典型返回**
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{ "ok": false, "blocked": true, "error": "审计拦截:2 个 blocker → src/a.js:12(凭据硬编码);docs/b.md:3(沟通措辞残留)" }
|
|
106
|
+
{ "ok": false, "blocked": true, "code": "USER_REQUIREMENTS", "error": "开发者特殊要求未核对:…" }
|
|
107
|
+
{ "ok": false, "blocked": true, "code": "PUSH_GATE", "commitSha": "a1b2c3d…", "push": { "pushed": false, "reason": "push-gate" } }
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## 四、边界与坑
|
|
111
|
+
|
|
112
|
+
| 现象 | 原因 | 处理 |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| `ok:false, blocked:true`(审计拦截) | 审计命中 blocker(凭据硬编码、语法错误、沟通措辞等) | 先按 `audit.blocked` 列表修文件,再重调;`public`/`unknown` 可见性一律保守拦截 |
|
|
115
|
+
| 返回 `code:"USER_REQUIREMENTS"` | 存在开发者要求清单,但未带 `requirementsConfirmed:true` | 逐条核对达标后置 `true` 重调 |
|
|
116
|
+
| 返回 `code:"PUSH_GATE"` | 配置 `pushGate` 已开启,未带 `pushConfirmed:true` | 确认要推时带 `pushConfirmed:true` 重调(**可沿用本次 commit,不会重复提交**) |
|
|
117
|
+
| `非 git 仓库` / `commit message 必填` | `repo` 下无 `.git`,或 `message` 为空 | 先确认仓库路径、补 message |
|
|
118
|
+
| `HEAD 处于 detached 状态` | 当前在游离 HEAD 上 | 先 `git checkout <分支>` 再提交 |
|
|
119
|
+
| 推送失败且 `push.diverged:true` | 远端已分叉(non-fast-forward) | **不会静默回落 API**:先 fetch 整合远端;确认要覆盖再带 `force:true` |
|
|
120
|
+
| `pushed:false` + `reason:"远端已是最新,无新提交可推送(正常,不是错误)"` | 远端内容与本地一致(内容级短路) | **正常成功路径**(job 状态 `completed`):`ok:true`,不是失败 |
|
|
121
|
+
| `committed:false` + `message:"无变更:工作区无改动,无需提交(正常,不是错误)"` | 工作区干净、没有新提交 | **正常成功路径**(job 状态 `completed`);若本地领先远端,仍会继续推送(此时 `pushed:true` 且 `committed:false`) |
|
|
122
|
+
| 工作区干净 + `push:true` + 远端已最新 | 既无新提交、也无可推内容 | `ok:true` + `committed:false` + `pushed:false`,job detail「无变更:工作区无改动,未产生新提交」——**都不是错误**,不要因此改去手敲 git |
|
|
123
|
+
| 返回 `jobFallback:true` | 宿主后台 job 控制器不可用/不服务当前会话 | 已自动同步执行,直接看 `result`,无需再查 job |
|
|
124
|
+
| `push.method:"api"` + `fallbackReason` | SSH 无可用私钥或 SSH 推送失败,回落 API | 远端 sha 与本地不同属正常;要远端 sha 一致就配好 SSH 私钥 |
|
|
125
|
+
| 私有库仍报敏感文件 | 扫描是**只报告**,不改 `.gitignore`、不解除跟踪 | 按报告自行决定移除或转私有 |
|
|
126
|
+
| 私有库审计不拦 | 远端可见性 = `private` → 审计只报告不拦截(返回 `privateExempt`) | 转公开前必须先把私密文件清掉 |
|
|
127
|
+
|
|
128
|
+
**凭据管理要点**
|
|
129
|
+
|
|
130
|
+
- 存放位置:插件配置目录 `<配置目录>/config.json`(即 `DSH_HOME/git-push/config.json`,无 `DSH_HOME` 时退到 `HOME/.dsh/git-push/`)。
|
|
131
|
+
- token 存 `githubToken` 键(`ghp_` / `github_pat_` 开头,0600);SSH **公钥**存 `sshPub` 键;SSH **私钥**是文件 `<配置目录>/id_rsa`(也支持 `id_ed25519` / `id_ecdsa`),不进 json。
|
|
132
|
+
- token 解析优先级:显式传入 → 环境变量 `DSH_GIT_PUSH_TOKEN` / `GITHUB_TOKEN` → 显式指定的文件 / 仓库内 `.git-push-token` → `config.json` 的 `githubToken`。
|
|
133
|
+
- SSH 私钥优先级:`id_rsa` → `id_ed25519` → `id_ecdsa`;推送时**逐把尝试**,直到某把能推(未登记到 GitHub 的那把会跳过)。
|
|
134
|
+
- 脱敏值(含 `…` / `****`)会被拒绝写入,防止把回显的打码串覆盖成真凭据。
|
|
135
|
+
- 推送通道与推送门禁在插件设置里改:`pushMethod`(`ssh` 默认 / `api` / `auto`)、`pushGate`(默认关)。
|
|
136
|
+
|
|
137
|
+
**任务完成自动推送**
|
|
138
|
+
|
|
139
|
+
- 开关 `autoPushEnabled`(**默认关**);触发文本 `autoPushTriggerText`(默认 `✅任务完成`,支持正则如 `✅(任务完成|已解答)`);范围 `autoPushScope`(`session` 默认=仅会话 cwd 所在仓库 / `all`=工作区全部有变更仓库);提交信息 `autoPushMessage`(默认 `chore(ai): 任务完成自动提交`)。
|
|
140
|
+
- 触发时机:AI 回合结束(`turn/end`)→ 提取最后一条回复 → 命中触发文本才推送;`❌` / `⚠️ 未完成` 等不触发,无完成标记不触发。
|
|
141
|
+
- 走的是**同一套门禁**:强制审计 + 自动带要求核对标记与推送放行;并发闸(同时只跑一个)+ 同回合去重 + 防抖。
|
|
142
|
+
- 开关关闭时完全不动作;会话目录不在任何 git 仓库内时报「无推送目标」而不推。
|
|
143
|
+
|
|
144
|
+
## 五、相关功能
|
|
145
|
+
|
|
146
|
+
| 功能 | 关系 |
|
|
147
|
+
|---|---|
|
|
148
|
+
| `git_scan` | 先扫「哪个仓库有未提交/未推送」,再决定提交哪个 |
|
|
149
|
+
| `code_audit` | 独立审计(可 `scope:"full"`、`includeFindings`、历史提交审计),提交前自查用 |
|
|
150
|
+
| `git_account_check` | 校验 token/SSH 是否有效、以谁的身份推;改凭据前后用 |
|
|
151
|
+
| `git_cred_env` | 输出凭据环境变量前缀(不含明文),外部 git 命令粘贴使用 |
|
|
152
|
+
| `git_remote_create` | 仓库还没远端时先建远端并设 origin(默认 private) |
|
|
153
|
+
| `git_set_visibility` | 切换 public/private;改 public 前先确认无私密内容 |
|
|
154
|
+
| `git_clone` | 从 GitHub 克隆仓库(Git Data API,不直连 github.com) |
|
|
155
|
+
| `git_sluice` | 浅包装 git 透传(log/diff/branch/tag 等只读或低频命令),凭据自动注入 |
|
|
156
|
+
| CLI | `git-sluice commit <仓库> -m "msg"` 与工具同源(审计门禁一致);CLI 默认只提交,加 `--push` 才推 |
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: guide-inject-ui
|
|
3
|
+
description: dsh-git-push 注入与界面:注入内容与开关、侧边栏三选项卡配置项、账号卡与仓库列表读取时机、预览页。处理注入与界面类请求时加载。
|
|
4
|
+
whenToUse: 要弄清插件往系统提示词/上下文注入了什么、开关怎么影响、侧边栏配置项含义、账号与仓库列表何时刷新、预览页怎么看时。
|
|
5
|
+
updated: 2026-10-02
|
|
6
|
+
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 注入与界面(guide-inject-ui)
|
|
10
|
+
|
|
11
|
+
> 一句话定位:插件往 AI 看到的提示词/上下文里注入什么、侧边栏每个开关什么意思、这些数据从哪读、预览页怎么接真实后端。
|
|
12
|
+
|
|
13
|
+
## 一、规则(场景 → 必须做的)
|
|
14
|
+
|
|
15
|
+
| 场景 | 必须做的 |
|
|
16
|
+
|---|---|
|
|
17
|
+
| 判断「AI 为什么看得到/看不到插件功能」 | 先看总开关「注入系统提示词/上下文」;它同时门控两条通道(系统提示词 + 上下文),关掉后两条都不注入 |
|
|
18
|
+
| 确认某个注入段是否生效 | 按生效条件逐项核对,不能只看总开关:要求清单段还要「提交前自动审计」+「↳ 注入开发者要求清单」同时开 |
|
|
19
|
+
| 改插件配置/开关 | 只改插件私有 `config.json`(侧边栏保存即写它);不要写公共 `settings.yaml` |
|
|
20
|
+
| 看界面上的真实数据 | 用 `assets/start.sh` 起预览反代(默认真实后端),不要只看静态 HTML 文件 |
|
|
21
|
+
| 刷新账号信息 / 本地仓库列表 | 只在三种时机读取;不轮询、不监听索引文件,页面切 tab 不会刷新 |
|
|
22
|
+
| 改了前端界面代码 | 先重新生成预览页(`node scripts/preview-gen.mjs`)再看,否则看的是旧界面 |
|
|
23
|
+
|
|
24
|
+
## 二、怎么做 / 命令 / 实例
|
|
25
|
+
|
|
26
|
+
### 2.1 两条通道、四个段
|
|
27
|
+
|
|
28
|
+
| 通道 | 段名 | 顺序 | 注入内容 | 生效条件 |
|
|
29
|
+
|---|---|---|---|---|
|
|
30
|
+
| 系统提示词 | `dsh-git-push-usage` | 990 | 10 个工具各做什么、参数要点、凭据由插件托管、调用纪律 | 注入总开关 |
|
|
31
|
+
| 系统提示词 | `dsh-git-push-readme-check` | 991 | 提交前必须核对仓库 README(功能表/版本记录/用法) | 注入总开关 |
|
|
32
|
+
| 系统提示词 | `dsh-git-push-requirements` | 992 | 开发者特殊要求清单正文(逐条编号) | 注入总开关 + 提交前自动审计 + ↳ 注入开发者要求清单 |
|
|
33
|
+
| 上下文 | 环境注入(`【dsh-git-push 环境注入】`) | — | cwd、项目 git 根、skills 总入口、工作区根 + 子目录、工具实测路径 | 注入总开关;每个 agent 首次 step 注入一次 |
|
|
34
|
+
|
|
35
|
+
- 系统提示词三段**每步**都带;环境段体积小,只**每个 agent 首次 step 注入一次**(作为一条 user 消息追加)。
|
|
36
|
+
- 功能用法段正文可用 `config.json` 的 `injectUsageText`(字符串,或数组按行拼接)覆盖默认文本。
|
|
37
|
+
|
|
38
|
+
### 2.2 环境段实际注入长这样(目录级,只给路径不给正文)
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
【dsh-git-push 环境注入】
|
|
42
|
+
- 当前工作目录 cwd:<会话工作区>
|
|
43
|
+
- 运行主机:<主机名>(<本机IP> / 多网卡全列)
|
|
44
|
+
- 项目实际目录(git 根):<git 顶层>
|
|
45
|
+
- skills 目录:<项目根>/skills(存在:true/false)
|
|
46
|
+
- 工作区根目录:<工作区根>
|
|
47
|
+
- 工作区子目录:assets / docs / lib / scripts / skills / test
|
|
48
|
+
- 工具:git=/… / node=/… / python3=/… / curl=/…(实测探测结果)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- skills 段**只给总入口一行**(路径 + 是否存在),不列 skill 文件清单、不注入 skill 正文。
|
|
52
|
+
- 工作区子目录跳过 `.git` / `node_modules` / `dist` / `build` 与隐藏目录。
|
|
53
|
+
- 工具路径由 `which`(Windows 走 `where`)实测,结果同时落盘配置目录的 `tools.json`;探测失败降级为静态清单,注入不中断。
|
|
54
|
+
- 主机名探测异常时「运行主机」行整行省略,注入不中断。
|
|
55
|
+
|
|
56
|
+
### 2.3 关闭开关的行为
|
|
57
|
+
|
|
58
|
+
| 操作 | 结果 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| 关掉「注入系统提示词/上下文」 | 四个段全部返回空串(段仍注册、内容为空);AI 看不到功能用法与环境目录,但插件工具照常可用 |
|
|
61
|
+
| 关掉「提交前自动审计」 | 要求清单段不注入(子开关勾选保留、该行置灰) |
|
|
62
|
+
| 再打开总开关 | 清掉环境注入缓存,下一轮装配即按新状态生效,无需重启实例 |
|
|
63
|
+
|
|
64
|
+
### 2.4 侧边栏设置(设置 → 侧边栏 → Git 提交推送,三选项卡)
|
|
65
|
+
|
|
66
|
+
**选项卡一:账号信息**
|
|
67
|
+
|
|
68
|
+
| 区块 | 内容与行为 |
|
|
69
|
+
|---|---|
|
|
70
|
+
| 账号卡片 | 渐变面板 + GitHub 图标 + 状态徽标:已连接 / 检测中 / 未连接;下方是后端生成的凭据块 |
|
|
71
|
+
| 凭据块 | Token 行尾带 API 配额剩余(如 `(配额剩余5000/h)`,查 GitHub 配额接口不消耗配额;打开页面自动刷新,后端 60s 缓存);Token 与 SSH 可以是不同账号,不同账号时提示「推送走 SSH 通道」 |
|
|
72
|
+
| `⟳ 重新检测` | 在线校验 token/SSH 后写 `account-status.json`,再离线读回 |
|
|
73
|
+
| 仓库管理卡片 | 本地 / 云端 两子选项卡 |
|
|
74
|
+
|
|
75
|
+
- **本地**:默认扫描根 = DSH 家根(动态推导);可手填路径或用 📂 目录选择器;输入框路径与扫描路径都记住(刷新后恢复)。列表显示 路径 / 分支 · 远端子状态 / 未提交数 / 最近提交 + 索引登记;只显示登录同作者的仓库;有远端且「有未推送提交」(领先数 >0 或状态未知)即可点 `push`(工作树脏不影响),点击后行内绿/红反馈。`扫描` = 独立进程后台离线扫描,每登记一个仓库就追加进列表(不整页重读),扫描中按钮禁用。
|
|
76
|
+
- **云端**:`加载仓库列表` 用 token 拉账号名下全部仓库(按最近更新),显示 名称 / 私有·公开 / 默认分支 / 最近更新;行尾 `clone` 弹目录选择器选目标目录后克隆(走 Git Data API,服务端后台跑、进度轮询、刷新后自动接回)。克隆设置:单文件上限(默认 10 MB,0=不限)、并发数(默认 6,1~16)。
|
|
77
|
+
|
|
78
|
+
**选项卡二:审计**
|
|
79
|
+
|
|
80
|
+
| 配置项 | 默认值 | 含义 |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| 提交前自动审计 | 关 | 开启后 `git_commit_push` 提交前自动跑静态检查 + 10 维度评分,有 blocker 拦截提交 |
|
|
83
|
+
| 审计扫描范围 | diff | 单击切换:diff(只审本次变动)/ full(全量) |
|
|
84
|
+
| ↳ 注入开发者要求清单到系统提示词 | 关 | 勾选即生效(不必等门禁拦截再回读清单);审计关闭时置灰、勾选保留 |
|
|
85
|
+
| 注入系统提示词/上下文 | 开 | 注入总开关,同时门控系统提示词三段与上下文环境段 |
|
|
86
|
+
| 代码禁用户沟通词 | 开 | comment 规则包启停;注释/文档出现沟通残留措辞 → blocker 拦截提交 |
|
|
87
|
+
| 全量扫描文件上限 | 3000 | 0=不限;超限按「变动文件优先」截断,弱机防卡死 |
|
|
88
|
+
| 审计权重(10 维度) | 合计 100 | 改即写回权重覆盖 JSON,保存后下次审计生效 |
|
|
89
|
+
| 规则包列表 | — | ↑↓ 调次序(后加载覆盖先加载);单击整行启用/禁用(启用=绿底、禁用=红底);三列数字是该包内拦截级/警告级/提示级的规则条数;nodejs/private 安全红线不可禁用 |
|
|
90
|
+
|
|
91
|
+
**选项卡三:设置**
|
|
92
|
+
|
|
93
|
+
| 配置项 | 说明 |
|
|
94
|
+
|---|---|
|
|
95
|
+
| GitHub token | `ghp_` / `github_pat_` 开头;保存写 `config.json`(0600),不回传明文、页面不留存 |
|
|
96
|
+
| SSH 公钥 | `ssh-ed25519` / `ssh-rsa` 整行,与 token 同份配置、互不覆盖 |
|
|
97
|
+
| SSH 邮箱 + 一键生成并复制 | 按邮箱生成密钥对(私钥不出本机,公钥整行回填并复制) |
|
|
98
|
+
| 推送通道 | ssh(默认,只走 SSH 私钥)/ token(先走 Git Data API,失败回落 SSH)/ auto(先 ssh 再回落 token);远端分叉时不静默回落 |
|
|
99
|
+
| 推送门禁 | 默认关;开启后 push 必须显式带 `pushConfirmed: true`,否则拦截(commit 不受影响) |
|
|
100
|
+
| 自动推送(✅任务完成) | 默认关;开启后 AI 回复含触发文本即自动 commit+push(复用审计门禁,不裸提交) |
|
|
101
|
+
| 自动推送触发文本 | 默认 `✅任务完成`,可写正则如 `✅(任务完成|已解答)` |
|
|
102
|
+
| 自动推送范围 | session(默认,仅会话 cwd 所在仓库)/ all(workspace 全部有变更仓库) |
|
|
103
|
+
|
|
104
|
+
### 2.5 账号信息卡 / 本地仓库列表:读取时机
|
|
105
|
+
|
|
106
|
+
只在三种时机读取;读取一律纯离线读 json(秒级),联网只在需要时单独触发:
|
|
107
|
+
|
|
108
|
+
| 时机 | 账号信息 | 本地仓库列表 |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| 插件启动(侧边栏加载) | 离线读 `account-status.json` | 离线读 `dsh-repo-index.json` |
|
|
111
|
+
| 云端 push 完成后 | 离线读(push 时已在线更新 json) | 离线读(push 时已重建索引) |
|
|
112
|
+
| 手动刷新 | `重新检测` = 在线校验写 json,再离线读回 | `扫描` = 独立进程后台离线扫描,逐条追加 |
|
|
113
|
+
|
|
114
|
+
登录判定为「或」:SSH 或 token 任一有效即视为已登录,用户名取有效者。
|
|
115
|
+
|
|
116
|
+
### 2.6 界面预览页(assets/preview.html,真实后端数据)
|
|
117
|
+
|
|
118
|
+
预览页由 `scripts/preview-gen.mjs` 生成(内联真实前端代码,只垫片宿主环境),界面与真实插件一致;用 `assets/start.sh` 起本地反代服务访问:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
./assets/start.sh start [--port 31000] # 默认 30999;端口被别的项目占用时用 --port 错开
|
|
122
|
+
./assets/start.sh status / restart / stop
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
- 访问 `http://<本机IP>:30999`(默认端口)。反代把 `/api/git-push/*` 全部转发到真实 DSH 后端(默认 `http://<本机IP>:30800`),并自动完成 token 认证——账号信息 / 本地仓库 / 云端仓库 / 规则包 / 审计结果 / 设置全部来自真实后端,读取与写入都真实。
|
|
126
|
+
- 指定后端或直接跑:`node scripts/preview-server.mjs --port 30999 --dsh http://<本机IP>:30800 --token <launch-token>`(同一入口还有 `--direct` 直连插件 handleHttp、`--local` 每请求 fork 子进程跑工作区最新代码);token 解析顺序:`--token` > 环境变量 `DSH_PREVIEW_TOKEN` > 解析 `dsh-proxy.log` 兜底。
|
|
127
|
+
- 离线调试:URL 加 `?mock=1` 切内置假数据(改动只留页面内、不写文件);跨后端实测:URL 加 `?backend=http://<本机IP>:端口`。
|
|
128
|
+
- 全部可点:三选项卡切换、审计开关、注入系统提示词开关、注入要求清单子开关(含置灰联动)、规则包启停与调序、权重编辑、token/SSH 保存、邮箱一键生成 SSH 并回填。
|
|
129
|
+
- 健康检查 `GET /preview-ping`;PID 落 `dsh-git-push.pid`(插件根);日志 `assets/preview-server.log`(超 10 MB 轮转)。
|
|
130
|
+
- 改了前端代码后同步预览:`node scripts/preview-gen.mjs`。
|
|
131
|
+
|
|
132
|
+
### 2.7 配置持久化位置
|
|
133
|
+
|
|
134
|
+
设置项以插件配置 schema 为单一事实源;持久化真源是**插件私有目录**(`$DSH_HOME/git-push/`,无 `DSH_HOME` 时回退 `~/.dsh/git-push/`),**不写公共 settings.yaml**:
|
|
135
|
+
|
|
136
|
+
| 文件 | 内容 |
|
|
137
|
+
|---|---|
|
|
138
|
+
| `config.json` | 全部设置与凭据真源(0600):开关、扫描范围、文件上限、权重覆盖、规则包顺序、推送通道/门禁、自动推送、`githubToken`、`sshPub`,以及可选的 `injectUsageText` |
|
|
139
|
+
| `account-status.json` | 账号快照:登录名、是否登录、token/SSH 各自有效性与校验时间 |
|
|
140
|
+
| `dsh-repo-index.json` | 仓库索引:本地/云端仓库的归属、可见性、路径、默认分支、领先/落后等(自动生成,请勿手改) |
|
|
141
|
+
| `scan-live.json` | 本地扫描进度:`version` / 已发现仓库 / 是否完成 |
|
|
142
|
+
| `tools.json` | 工具探测结果(工具名 → 本机实测路径) |
|
|
143
|
+
| `settings-ui.log` | 侧边栏每次保存设置的追加日志(凭据值打码) |
|
|
144
|
+
| `requirements.json` | 开发者要求清单外挂覆盖(存在则优先于插件内置清单) |
|
|
145
|
+
| `id_rsa` 等 | SSH 私钥文件(token/公钥在 config.json,私钥仍是文件) |
|
|
146
|
+
|
|
147
|
+
## 三、边界与坑
|
|
148
|
+
|
|
149
|
+
- 关掉注入总开关后段仍注册、只是内容为空——不要用「段存在」判断注入是否生效。
|
|
150
|
+
- 环境段走上下文注入、不在系统提示词里;只注入目录/路径级信息,不注入 skill 正文、不列 skill 文件清单(正文交给 AI 按需读)。
|
|
151
|
+
- 「注入全部 skill 正文」「注入仓库索引全文」两个开关已移除,不提供全量正文注入档位。
|
|
152
|
+
- 环境注入是**每个 agent 首次 step 一次**,不是每步;缓存按会话工作目录分别缓存。
|
|
153
|
+
- 设置不写公共 settings.yaml:经反代访问时前端设置持久化会退化成内存(刷新即丢),且多实例共享配置目录会抢同一把写锁——插件配置自管到私有 `config.json`。
|
|
154
|
+
- 账号信息与仓库列表不轮询、不监听索引文件;页面内切 tab 不会反复刷新。
|
|
155
|
+
- 本地列表默认只显示登录同作者的仓库;无登录态时不过滤。
|
|
156
|
+
- 预览页默认接真实后端;`?mock=1` 是假数据,只用于离线看样式,不能用来验证真实数据流。
|
|
157
|
+
- 预览端口默认 30999,被别的项目占用时用 `--port` 错开;改了前端代码必须重新生成预览页,否则看的是旧界面。
|
|
158
|
+
|
|
159
|
+
## 四、配套 skill
|
|
160
|
+
|
|
161
|
+
- `skills/guide/guide-commit-push.md` —— 提交推送门禁、工具参数与返回字段
|
|
162
|
+
- `skills/guide/guide-audit.md` —— 审计规则、10 维度评分与豁免机制
|
|
163
|
+
- `skills/guide/guide-clone-repos.md` —— 克隆与仓库索引联动
|
|
164
|
+
- `skills/guide/guide-slash-completion.md` —— 用户输入框斜杠命令
|
|
165
|
+
- `skills/guide/guide-cli-scripts.md` —— 命令行与随插件脚本
|
|
166
|
+
- `skills/dsh-git-push.md` —— 插件总览与快速上手
|