dsh-jenkins-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byzhao999
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# dsh-jenkins-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Jenkins integration for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): **a live build-progress panel in the Web GUI's right sidebar**, plus a set of model-facing Jenkins tools.
+
+Once installed you stop switching to the Jenkins page to watch a build: the jobs you follow become cards in the sidebar with a live progress bar, a notice when a build finishes, and — when a build fails — one button that hands the failure to the model for a diagnosis.
+
+![The Jenkins panel: a running build's card with live stage progress, an unstable build, and failed builds offering rebuild and hand-to-AI](https://raw.githubusercontent.com/Endless-zby/dsh-jenkins-plugin/main/doc/panel-favorites-2.png)
+
+## Install
+
+Installing from npm is recommended — the package ships prebuilt code and needs no build permission:
+
+```sh
+dsh plugin --profile web add dsh-jenkins-plugin
+```
+
+Restart `dsh web`, open **Settings → Jenkins**, add an instance (URL, account, password/API token) and save; the **Jenkins** panel then appears in the right sidebar.
+
+![The Jenkins entry on the Web sidebar's start page](https://raw.githubusercontent.com/Endless-zby/dsh-jenkins-plugin/main/doc/settings-instances-1.png)
+
+Other sources:
+
+```sh
+# tarball (offline or internal distribution)
+dsh plugin --profile web add ./dsh-jenkins-plugin-0.1.0.tgz
+
+# git sources: the profile must allow the prepare script to build (pnpm ≥10 blocks it by default)
+dsh plugin --profile web add github:<owner>/dsh-jenkins-plugin
+```
+
+A git install fetches **sources, not built artifacts**, so the profile's `pnpm-workspace.yaml` has to allow its prepare script:
+
+```yaml
+allowBuilds:
+  dsh-jenkins-plugin: true
+```
+
+That is permission for this package's code to run on your machine at install time, outside any sandbox the agent runs in — only allow sources you trust, and pin a commit (`github:<owner>/dsh-jenkins-plugin#<sha>`). Use npm or a tarball to avoid the step entirely.
+
+## What you get
+
+**The panel** (the **Jenkins** tab in the right sidebar) has two modules:
+
+- **Following** — one card per followed job: state dot, build number, outcome tag, **live progress bar**, the running stage's name, the change description of the current build, and the Maven project version when the controller reports one. Cards are fed by an SSE stream, not by a polling page.
+- **All jobs** — collapsed by default; ☆/★ at the end of each row follows or unfollows it.
+
+Clicking a job or a card drills down without ever leaving the panel: build history (paged) → build detail (stage bar, embedded console log, test summary, change set, artifacts). Downloading an artifact is the only action that opens a Jenkins page.
+
+**Writes** happen in the panel as *button → inline confirmation → run → result in place*:
+
+| Action | Notes |
+|---|---|
+| Trigger a build | parameterized jobs get a `KEY=VALUE` box |
+| Rebuild | offered only for failed builds; **reuses the failed build's parameters** |
+| Abort | `allowCancel` is off by default; enable it to use the button |
+| Hand to AI | offered only for failed builds; sends the failed log tail, stages and change set to the current session's model, and the answer appears in the conversation |
+
+Jobs on `denyJobs` are refused whatever the switches say, and **not a single request reaches Jenkins**.
+
+**Tools the model can call on its own:**
+
+| Tool | Purpose |
+|---|---|
+| `jenkins_jobs` | list jobs and their status, optionally with recent build history |
+| `jenkins_build_status` | one build's result, duration, Pipeline stages, change set, test summary |
+| `jenkins_log` | console log, tail by default, continue from `next_offset` |
+| `jenkins_workspace` | a build's workspace directory or artifact list (workspace reads need the Jenkins Workspace API plugin) |
+| `jenkins_build` | trigger or cancel a build — the only write tool; `denyJobs`/`allow.*` first, then operator approval |
+
+**Multiple instances**: the settings page holds several Jenkins controllers and probes each one with "test connection" before saving (if any row fails, the whole save is rejected with zero writes). The panel footer switches instances and marks the current one in green. The instance list and the followed jobs live in `$DSH_HOME/jenkins.json`.
+
+**Completion notices**: a followed job's finished build is announced once through the platform's own background-job mechanism; the same build is never announced twice.
+
+## Permissions and risks
+
+Please take these as read before installing:
+
+- **Network**: requests go only to the Jenkins addresses you configure. Nothing else is contacted.
+- **Credentials**: Basic auth; the password/API token is stored and resolved through **DSH's own credentials service** (`tokenRef` names a credential reference). The plugin's own `jenkins.json` holds only URLs, accounts and credential names — **no passwords** — and credentials never appear in tool output, the panel, or logs.
+- **Writes**: it can trigger and cancel builds. `allowTrigger` defaults to on, `allowCancel` to off, and `denyJobs` hard-blocks specific jobs (including whole folders). Model-side calls additionally require approval; a panel click uses inline confirmation plus the same policy check.
+- **Build logs enter the model's context**: "hand to AI" and the model's own `jenkins_log` calls send **console log content to the model as part of the prompt**. Jenkins logs are **untrusted input** — they can contain arbitrary text, including instructions aimed at the model — so treat them that way. Only the last 16 KiB of a failed build's log is sent by default (`analyzeLogBytes`).
+- **Local state**: `$DSH_HOME/jenkins.json` (instance list plus followed jobs) and DSH credentials (passwords).
+- The plugin never triggers a build by itself: only your click or an explicit model call does.
+
+## Compatibility
+
+- **Harness**: built and verified against `0.1.6-alpha.2` (both `engines.dsh` and the peer dependencies pin that version).
+- **Node**: matches the harness, `^22.19.0 || >=24.0.0`.
+- **Surface**: the panel is a Web GUI surface (`dsh web`), verified on the Web composition.
+- **Jenkins**: verified against a real **Jenkins 2.176.2** (FreeStyle and Maven jobs, an instance with 777 jobs). Several honest degradations:
+  - **Pipeline stages** need Blue Ocean's `wfapi` endpoints; on a controller without Pipeline jobs the stage list is empty and the card falls back to an elapsed-time estimate — that is "the controller reported no stages", not a broken panel.
+  - **Workspace reads** need the Jenkins Workspace API plugin; without it `jenkins_workspace` says so instead of pretending.
+  - **Maven versions** come from `mavenArtifacts/api/json`, which only Maven jobs answer — and on a real 2.176.2 it is usually produced when the build *ends*, so a running Maven build's card may have no version. When there is none, nothing is shown; a version is never guessed.
+  - **Artifacts carry no size**: Jenkins' `tree` query cannot fetch artifact sizes.
+- **Not finished yet**: `notifyWakeOnFailure` (wake the model when a build fails) and `uiAutoOpenOnTrigger` (open the panel on trigger) are accepted but **not active**; `maxTrackedBuilds` is advisory only — the followed list is the user's own choice, so nothing is hard-capped.
+
+## Configuration
+
+Static configuration is only the **fallback layer**: instances configured in the settings page win, and static configuration applies when no panel settings exist (as an instance with id `config`). `baseUrl`/`username` may be left empty — that is exactly the "configure everything in the panel" setup.
+
+![The Jenkins settings page: several instances, test-connection result, save](https://raw.githubusercontent.com/Endless-zby/dsh-jenkins-plugin/main/doc/settings-instances.png)
+
+```yaml
+- id: jenkins
+  name: dsh-jenkins-plugin
+  config:
+    baseUrl: https://ci.example.com/jenkins
+    username: ci-bot
+    tokenRef: JENKINS_TOKEN
+    denyJobs: ['infra/*']
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `baseUrl` | empty | Jenkins root URL; empty means panel settings only |
+| `username` | empty | login name paired with the token |
+| `tokenRef` | `JENKINS_TOKEN` | credential reference holding the API token; resolved per call, so a rotation applies without a restart |
+| `settingsFile` | `jenkins.json` | panel settings file: an absolute path, or a name under the harness home |
+| `tlsMode` | `verify` | `verify` validates the certificate; `allowSelfSigned` accepts an untrusted one |
+| `tlsCaFile` | — | PEM bundle used to validate the certificate under `verify` |
+| `timeoutMs` | `15000` | bound on one HTTP request |
+| `crumbMode` | `auto` | `auto` fetches a CSRF crumb before mutating requests; `off` skips it |
+| `denyJobs` | `[]` | job paths that may never be triggered or cancelled; `folder/*` matches a folder |
+| `allowTrigger` | `true` | whether triggering builds is allowed |
+| `allowCancel` | `false` | whether cancelling builds is allowed |
+| `progressIntervalMs` | `3000` | stage polling interval for tracked builds |
+| `logIntervalMs` | `1500` | console-log polling interval for the build the panel shows |
+| `idleBackoffMaxMs` | `30000` | upper bound of the idle backoff |
+| `queueTimeoutMs` | `300000` | how long a build may stay queued before it reports a timeout |
+| `maxTrackedBuilds` | `5` | advisory cap on tracked builds (not enforced) |
+| `retainMs` | `600000` | how long a finished build stays in the tracking table |
+| `historyCount` | `10` | default build-history rows (max 50) |
+| `maxLogBytes` | `262144` | byte cap on one console-log **response** |
+| `logReadBytes` | `8388608` | byte window read from the controller per log call |
+| `maxListingBytes` | `4194304` | byte cap on one response of the recursive job walk |
+| `maxWorkspaceEntries` | `500` | entry cap on one workspace directory listing |
+| `maxReadFileBytes` | `1048576` | byte cap on one workspace file read |
+| `notifyOnComplete` | `true` | announce a followed build when it finishes |
+| `notifyWakeOnFailure` | `false` | wake the model on failure (**not active yet**) |
+| `allowAnalyze` | `true` | allow handing a failed build to the model |
+| `analyzeLogBytes` | `16384` | log-tail bytes handed to the model |
+| `uiAutoOpenOnTrigger` | `true` | open the panel on trigger (**not active yet**) |
+
+`maxLogBytes` and `logReadBytes` are two different things because real Jenkins **ignores `?start=`**: the read window has to be far larger than a page, or the "tail" you get back is really the head of the log. That is why this plugin reads a window and slices locally.
+
+## Development
+
+```sh
+npm install          # runs prepare (= build) once
+npm run typecheck
+npm test             # 235 assertions, no test framework: every tests/*.ts runs on its own
+npm run build        # tsc (Host half) + esbuild (browser half → lib/client.js)
+npm run check        # test + secret scan + packed-payload audit
+```
+
+The browser half is bundled into the client module system's lazy factory (`window.__ModuleLoader__.load({ id, factory })`): React, Cordis and the static UI libraries stay external and resolve through the injected `require`, everything else is inlined — so the package has no runtime dependency beyond the platform baseline.
+
+`tests/stub-jenkins.ts` is a zero-dependency stub Jenkins (`node tests/stub-jenkins.ts`) with stages, a failing build, a parameterized Maven job, write endpoints and a queue delay; it exercises the panel's live path and write path without touching a real controller.
+
+Three gates run before a release (and are what CI should run):
+
+```sh
+npm run check:secrets   # credential shapes in everything a commit would carry (private hostnames / user paths warn only)
+npm run check:payload   # reads npm pack's manifest: artifacts present, no src/ or internal notes shipped
+npm pack                # produce the tarball, install it into a clean profile, then publish
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,170 @@
+# dsh-jenkins-plugin
+
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 Jenkins 插件：**Web GUI 右侧栏里的实时构建面板**，加上一组面向模型的 Jenkins 工具。
+
+装完之后，你不再需要为了看一次构建进度而切到 Jenkins 页面：关注的 job 变成侧栏里的卡片，进度条实时走，构建结束发通知，失败了一键交给模型分析原因。
+
+![Jenkins 面板：正在跑的构建卡片带实时阶段进度、不稳定构建、失败构建的「重新构建 / 交给 AI 分析」](https://raw.githubusercontent.com/Endless-zby/dsh-jenkins-plugin/main/doc/panel-favorites-2.png)
+
+## 安装
+
+推荐从 npm 安装（预构建产物，不需要任何构建授权）：
+
+```sh
+dsh plugin --profile web add dsh-jenkins-plugin
+```
+
+装完重启 `dsh web`，打开**设置 → Jenkins** 填一个实例（地址 + 账号 + 密码/API token），Save 之后右栏就会出现 **Jenkins** 面板。
+
+![Web 侧栏开始页上的 Jenkins 入口](https://raw.githubusercontent.com/Endless-zby/dsh-jenkins-plugin/main/doc/settings-instances-1.png)
+
+其他安装来源：
+
+```sh
+# tarball（离线/内部分发）
+dsh plugin --profile web add ./dsh-jenkins-plugin-0.1.0.tgz
+
+# git 源码：需要授权 allowBuilds 让 prepare 脚本构建（pnpm ≥10 默认拒绝）
+dsh plugin --profile web add github:<owner>/dsh-jenkins-plugin
+```
+
+git 安装拉的是**源码而不是产物**，所以必须在 profile 的 `pnpm-workspace.yaml` 里允许它的准备脚本：
+
+```yaml
+allowBuilds:
+  dsh-jenkins-plugin: true
+```
+
+那等于允许本包代码在安装时于你机器上执行，请只对可信源码授权并锁定 commit（`github:<owner>/dsh-jenkins-plugin#<sha>`）。想省掉这一步就用 npm 或 tarball。
+
+## 你会得到什么
+
+**右栏面板**（侧栏右侧的 **Jenkins** 页签）分两个模块：
+
+- **我关注的** —— 每个关注的 job 一张卡片：状态点、构建号、状态标签、**实时进度条**、当前阶段名、本次构建的变更说明、Maven 项目的版本号（构建结束后可取到时）。卡片直接来自 SSE 推送，不是轮询页面。
+- **所有 job** —— 默认折叠，展开后每行末尾的 ☆/★ 一键关注。
+
+点 job 或卡片继续下钻，全程不跳出面板：构建历史（可翻页）→ 构建详情（阶段条、内嵌控制台日志、测试摘要、变更集、产物列表）。产物下载是唯一会打开 Jenkins 页面的动作。
+
+**写操作**都在面板内完成，并且是「按钮 → 行内二次确认 → 执行 → 就地显示结果」：
+
+| 动作 | 说明 |
+|---|---|
+| 触发构建 | 参数化 job 有参数输入框（每行 `KEY=VALUE`） |
+| 重新构建 | 只对失败的构建出现，**沿用上次构建的参数** |
+| 中止构建 | `allowCancel` 默认关闭，开启后可用 |
+| 交给 AI 分析 | 只对失败的构建出现，把失败日志尾部 + 阶段 + 变更集交给当前会话的模型，答案直接出现在对话里 |
+
+`denyJobs` 里的 job 无论开关怎么设都拒绝，且**一个请求都不会发到 Jenkins**。
+
+**给模型用的工具**（模型可以自己调用，不必你手点）：
+
+| 工具 | 作用 |
+|---|---|
+| `jenkins_jobs` | 列 job 与状态，可选带最近构建历史 |
+| `jenkins_build_status` | 一个构建的结果、耗时、Pipeline 阶段、变更集、测试摘要 |
+| `jenkins_log` | 控制台日志，默认取尾部，可按 `next_offset` 续读 |
+| `jenkins_workspace` | 构建的工作空间目录或产物列表（读工作空间需要 Jenkins Workspace API 插件） |
+| `jenkins_build` | 触发或中止构建（唯一的写工具；先过 `denyJobs`/`allow.*`，再要求操作者审批） |
+
+**多实例**：设置页里可以配多个 Jenkins，逐个「测试连接」通过才允许保存（任何一行连不上则整次保存被拒、零写入）；面板底部可切换实例，当前实例用绿色标出。多实例的实例清单和关注列表存在 `$DSH_HOME/jenkins.json`。
+
+**完成通知**：关注的 job 一有构建结束就用平台的后台作业机制发一次通知，同一次构建只通知一次。
+
+## 权限与风险
+
+装之前请如实了解这个插件会做什么：
+
+- **网络**：只向你配置的 Jenkins 地址发请求，没有别的外联。
+- **凭据**：Basic 认证，密码/API token 通过 **DSH 自己的 credentials 服务**存取（`tokenRef` 指向一个凭据引用）。**插件自己的 `jenkins.json` 里只有地址、账号和凭据名，没有密码**，密码也不会出现在工具输出、面板或日志里。
+- **写操作**：可以触发和中止构建。`allowTrigger` 默认开、`allowCancel` 默认关，`denyJobs` 可以硬封指定 job（含整个目录）。模型侧调用还要额外经过审批；面板上的点击是行内二次确认 + 同一份策略判定。
+- **日志会进入模型上下文**：「交给 AI 分析」和模型自己调 `jenkins_log` 时，**构建日志的内容会作为提示词的一部分送给模型**。Jenkins 日志属于**不可信输入**——它可能包含任意文本（包括试图操纵模型的指令），请按此对待；默认只送失败日志的最后 16 KiB（`analyzeLogBytes`）。
+- **本地状态**：`$DSH_HOME/jenkins.json`（实例清单 + 关注列表）、DSH credentials（密码）。
+- 插件自己不会触发任何构建：只有你点按钮或模型显式调用才会。
+
+## 兼容性
+
+- **Harness**：针对 `0.1.6-alpha.2` 构建并验证（`package.json` 的 `engines.dsh` 与 peerDependencies 都钉在这个版本）。
+- **Node**：与 harness 一致，`^22.19.0 || >=24.0.0`。
+- **载体**：面板是 Web GUI 的界面（`dsh web`），在 Web 组合上验证过。
+- **Jenkins**：在 **Jenkins 2.176.2** 上实测（FreeStyle 与 Maven job，777 个 job 的实例）。几条如实降级：
+  - **Pipeline 阶段**需要 Blue Ocean 的 `wfapi` 端点；2.176.2 且没有 Pipeline job 时阶段列表为空，面板会退化成按耗时估算的进度条——这是"控制器没给阶段"，不是面板坏了。
+  - **读工作空间**需要 Jenkins Workspace API 插件；缺失时 `jenkins_workspace` 会如实说明该 Jenkins 不支持。
+  - **Maven 版本号**取自 `mavenArtifacts/api/json`，只有 Maven job 有，且真实 2.176.2 上通常在构建**结束后**才产生，所以正在跑的 Maven 构建卡片上可能没有版本号（拿不到就不显示，绝不猜）。
+  - **产物没有大小**：Jenkins 的 `tree` 查询取不到 artifact size。
+- **已知未完成**：`notifyWakeOnFailure`（失败时唤醒模型）与 `uiAutoOpenOnTrigger`（触发后自动展开面板）两个配置项已接受但**尚未生效**；`maxTrackedBuilds` 只是建议值，不硬性限制跟踪数量（关注列表是用户自己挑的）。
+
+## 配置
+
+静态配置只是**回退层**：面板设置页里配的实例优先，静态配置在没有面板设置时生效（实例 id 为 `config`）。`baseUrl`/`username` 可以留空——那正是"全部在面板里配"的用法。
+
+![Jenkins 设置页：多个实例、测试连接结果、保存](https://raw.githubusercontent.com/Endless-zby/dsh-jenkins-plugin/main/doc/settings-instances.png)
+
+```yaml
+- id: jenkins
+  name: dsh-jenkins-plugin
+  config:
+    baseUrl: https://ci.example.com/jenkins
+    username: ci-bot
+    tokenRef: JENKINS_TOKEN
+    denyJobs: ['infra/*']
+```
+
+| 字段 | 默认 | 含义 |
+|---|---|---|
+| `baseUrl` | 空 | Jenkins 根地址；留空表示只用面板设置 |
+| `username` | 空 | 与 token 配对的登录名 |
+| `tokenRef` | `JENKINS_TOKEN` | 存放 API token 的凭据引用；每次调用现取，支持热轮换 |
+| `settingsFile` | `jenkins.json` | 面板设置文件：绝对路径，或 harness home 下的文件名 |
+| `tlsMode` | `verify` | `verify` 校验证书；`allowSelfSigned` 接受不受信任的证书 |
+| `tlsCaFile` | — | `verify` 模式下用于校验的自签 CA PEM |
+| `timeoutMs` | `15000` | 单个 HTTP 请求的上限 |
+| `crumbMode` | `auto` | `auto` 在写请求前取 CSRF crumb；`off` 跳过 |
+| `denyJobs` | `[]` | 永不允许触发/中止的 job 路径；`folder/*` 匹配整个目录 |
+| `allowTrigger` | `true` | 是否允许触发构建 |
+| `allowCancel` | `false` | 是否允许中止构建 |
+| `progressIntervalMs` | `3000` | 跟踪构建的阶段轮询间隔 |
+| `logIntervalMs` | `1500` | 面板展示的构建的日志轮询间隔 |
+| `idleBackoffMaxMs` | `30000` | 没有进展时的退避上限 |
+| `queueTimeoutMs` | `300000` | 排队超过多久就报超时 |
+| `maxTrackedBuilds` | `5` | 跟踪表的建议上限（不强制） |
+| `retainMs` | `600000` | 已结束构建留在跟踪表里的时长 |
+| `historyCount` | `10` | 构建历史默认条数（最大 50） |
+| `maxLogBytes` | `262144` | 单次控制台日志**返回**的字节上限 |
+| `logReadBytes` | `8388608` | 单次从控制器**读取**的日志字节窗口 |
+| `maxListingBytes` | `4194304` | 递归列 job 时单次响应的字节上限 |
+| `maxWorkspaceEntries` | `500` | 单次工作空间目录列出的条目上限 |
+| `maxReadFileBytes` | `1048576` | 单个工作空间文件的读取上限 |
+| `notifyOnComplete` | `true` | 关注的构建结束时是否发通知 |
+| `notifyWakeOnFailure` | `false` | 失败时唤醒模型（**尚未生效**） |
+| `allowAnalyze` | `true` | 是否允许把失败构建交给模型分析 |
+| `analyzeLogBytes` | `16384` | 交给模型分析的日志尾部字节数 |
+| `uiAutoOpenOnTrigger` | `true` | 触发后自动展开面板（**尚未生效**） |
+
+`maxLogBytes` 和 `logReadBytes` 是两件事，因为真实 Jenkins 会**忽略 `?start=`**：读取窗口必须显著大于页大小，否则拿到的"尾巴"其实是日志开头。这也是本插件按窗口读取、本地切片的原因。
+
+## 开发
+
+```sh
+npm install          # 会跑一次 prepare（=构建）
+npm run typecheck
+npm test             # 235 项断言，无测试框架：每个 tests/*.ts 都是可直接运行的脚本
+npm run build        # tsc（Host 半）+ esbuild（浏览器半 → lib/client.js）
+npm run check        # test + 密钥扫描 + 打包内容审计
+```
+
+浏览器半被构建成客户端模块系统的懒加载工厂（`window.__ModuleLoader__.load({ id, factory })`），React / Cordis / 静态 UI 库保持 external 并通过注入的 `require` 解析，其余全部内联——平台基线模块之外没有运行时依赖。
+
+`tests/stub-jenkins.ts` 是一个零依赖的 stub Jenkins（`node tests/stub-jenkins.ts`），带阶段、失败构建、参数化 Maven job、写端点与队列延迟，用来验证面板的实时链路和写路径而不碰真实控制器。
+
+发布前的三道闸（CI 也是这三条）：
+
+```sh
+npm run check:secrets   # 扫"提交会带上的文件"里的凭据形状（内网主机名/个人路径只告警）
+npm run check:payload   # 读 npm pack 的清单：产物齐不齐、有没有把 src/ 或内部笔记打进去
+npm pack                # 出 tarball，先在一个干净 profile 上装一遍再 publish
+```
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-jenkins-plugin bundle layer.
+#
+# The row is inserted with the plugin's shape; a profile's own cordis.patch.yml
+# can override this row by id, and the user's patch layer wins over this file.
+- insert:
+    - id: jenkins
+      name: dsh-jenkins-plugin

package/lib/analyze.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Asking the model to explain a failed build.
+ *
+ * The panel's "hand it to the AI" button is one HTTP call and then a model turn,
+ * which costs tokens, so what goes into that turn is the whole design: a bounded
+ * tail of the console log, the facts the panel already knows (which build, which
+ * stage failed, what commits it carried), and an instruction narrow enough that
+ * the answer is a diagnosis and a fix rather than a summary of the log.
+ *
+ * The prompt is built here, as a pure function, because "what exactly did we send
+ * the model" is the part worth asserting — the route around it is plumbing.
+ * @module dsh-jenkins-plugin/analyze
+ */
+import type { JenkinsBuildDetail, JenkinsChange, JenkinsLogPage } from './jenkins/types.js';
+/** What the panel knows about the failed build when it hands it over. */
+export interface FailureContext {
+    /** Job path, as `folder/sub/job`. */
+    jobPath: string;
+    /** Build number. */
+    buildNumber: number;
+    /** Terminal outcome, which the caller has already established is a failure. */
+    outcome: string;
+    /** Instance name, so the model can name it back if it needs to. */
+    instanceName?: string;
+    /** The stage Jenkins reported as failed, when the job is a Pipeline. */
+    failedStage?: string;
+    /** What triggered the build, when Jenkins reported it. */
+    cause?: string;
+    /** Commits the build carried, newest first. */
+    changes?: readonly JenkinsChange[];
+    /** The console log, already sliced to the tail by the caller. */
+    log: string;
+    /** Size of the whole log in bytes, when Jenkins stated it. */
+    totalBytes?: number;
+    /** Whether {@link log} is only the tail of a longer log. */
+    truncated: boolean;
+}
+/**
+ * The key one build's analysis is reserved under.
+ *
+ * Used to refuse a second hand-off of the same build while the first is still
+ * being prepared, so a double click cannot buy two model turns.
+ * @param sessionId - the session the answer will appear in.
+ * @param jobPath - job path.
+ * @param buildNumber - build number.
+ * @returns the reservation key.
+ */
+export declare function analysisKey(sessionId: string, jobPath: string, buildNumber: number): string;
+/**
+ * The two reads one hand-off needs.
+ *
+ * Narrowed to exactly what is used, so the hand-off can be driven by a fake in a
+ * test without standing up a controller.
+ */
+export interface AnalyzeReads {
+    /**
+     * One build's detail — outcome, stages, commits.
+     * @param jobPath - folder path of the job.
+     * @param selector - build number.
+     * @param options - byte bound.
+     * @returns the detail.
+     */
+    buildDetail(jobPath: string, selector: string, options: {
+        maxBytes: number;
+    }): Promise<JenkinsBuildDetail>;
+    /**
+     * A page of the build's console log.
+     * @param jobPath - folder path of the job.
+     * @param selector - build number.
+     * @param offset - byte offset; zero means "the tail", which is what a failure
+     *   analysis wants.
+     * @param maxBytes - byte cap on the returned page.
+     * @returns the page.
+     */
+    consoleLog(jobPath: string, selector: string, offset: number, maxBytes: number): Promise<JenkinsLogPage>;
+}
+/** What a completed hand-off reports back to whoever clicked. */
+export interface HandOff {
+    /** The build that was handed over. */
+    buildNumber: number;
+    /** Its outcome, as Jenkins reported it. */
+    outcome: string;
+    /** Bytes of log actually handed to the model. */
+    logBytes: number;
+    /** Size of the whole log, when Jenkins stated it. */
+    totalBytes?: number;
+    /** Whether only the tail was handed over. */
+    truncated: boolean;
+    /** Characters of prompt queued in the session. */
+    promptChars: number;
+}
+/**
+ * Read a failed build and queue one prompt about it.
+ *
+ * The log is read as the **tail**: the failing lines are at the end, and the
+ * request is bounded so a hundred-megabyte log cannot turn into a hundred
+ * megabytes of context. Everything else rides along from the same read the panel
+ * already makes, so one click costs two Jenkins requests and one model turn.
+ * @param input.client - the Jenkins reads.
+ * @param input.jobPath - job path.
+ * @param input.buildNumber - the failed build.
+ * @param input.logBytes - byte cap on the log handed over.
+ * @param input.followup - queues the prompt in the calling session.
+ * @param input.instanceName - instance name, for the prompt's context.
+ * @returns what was handed over.
+ */
+export declare function handOverFailure(input: {
+    client: AnalyzeReads;
+    jobPath: string;
+    buildNumber: number;
+    logBytes: number;
+    followup: (prompt: string) => void;
+    instanceName?: string;
+}): Promise<HandOff>;
+/**
+ * Build the prompt that asks the model to diagnose one failed build.
+ *
+ * The instruction is deliberately strict about the shape of the answer: a cause
+ * with the log line that shows it, then one to three concrete fixes. Without that
+ * the model tends to restate the log or hand back generic advice, which is the
+ * one thing a person who has already read the log does not need.
+ * @param context - the build, its commits, and the log tail.
+ * @returns the message text to hand to a model turn.
+ */
+export declare function failurePrompt(context: FailureContext): string;

package/lib/analyze.js

@@ -0,0 +1,112 @@
+/**
+ * Asking the model to explain a failed build.
+ *
+ * The panel's "hand it to the AI" button is one HTTP call and then a model turn,
+ * which costs tokens, so what goes into that turn is the whole design: a bounded
+ * tail of the console log, the facts the panel already knows (which build, which
+ * stage failed, what commits it carried), and an instruction narrow enough that
+ * the answer is a diagnosis and a fix rather than a summary of the log.
+ *
+ * The prompt is built here, as a pure function, because "what exactly did we send
+ * the model" is the part worth asserting — the route around it is plumbing.
+ * @module dsh-jenkins-plugin/analyze
+ */
+/** How many commits the prompt names before it stops listing them. */
+const COMMITS_IN_PROMPT = 5;
+/** How many characters of one commit message the prompt keeps. */
+const COMMIT_MESSAGE_CHARS = 120;
+/**
+ * The key one build's analysis is reserved under.
+ *
+ * Used to refuse a second hand-off of the same build while the first is still
+ * being prepared, so a double click cannot buy two model turns.
+ * @param sessionId - the session the answer will appear in.
+ * @param jobPath - job path.
+ * @param buildNumber - build number.
+ * @returns the reservation key.
+ */
+export function analysisKey(sessionId, jobPath, buildNumber) {
+    return `${sessionId}/${jobPath}#${buildNumber}`;
+}
+/**
+ * Read a failed build and queue one prompt about it.
+ *
+ * The log is read as the **tail**: the failing lines are at the end, and the
+ * request is bounded so a hundred-megabyte log cannot turn into a hundred
+ * megabytes of context. Everything else rides along from the same read the panel
+ * already makes, so one click costs two Jenkins requests and one model turn.
+ * @param input.client - the Jenkins reads.
+ * @param input.jobPath - job path.
+ * @param input.buildNumber - the failed build.
+ * @param input.logBytes - byte cap on the log handed over.
+ * @param input.followup - queues the prompt in the calling session.
+ * @param input.instanceName - instance name, for the prompt's context.
+ * @returns what was handed over.
+ */
+export async function handOverFailure(input) {
+    const detail = await input.client.buildDetail(input.jobPath, String(input.buildNumber), {
+        // The detail read is capped independently of the log: a job with thousands of
+        // commits must not turn a diagnosis into a history dump.
+        maxBytes: Math.max(input.logBytes, 65_536),
+    });
+    const page = await input.client.consoleLog(input.jobPath, String(input.buildNumber), 0, input.logBytes);
+    const failedStage = detail.stages.find(stage => stage.status === 'FAILED')?.name;
+    const prompt = failurePrompt({
+        jobPath: input.jobPath,
+        buildNumber: detail.number,
+        outcome: detail.outcome,
+        ...input.instanceName === undefined ? {} : { instanceName: input.instanceName },
+        ...failedStage === undefined ? {} : { failedStage },
+        ...detail.cause === undefined ? {} : { cause: detail.cause },
+        ...detail.changes.length === 0 ? {} : { changes: detail.changes },
+        log: page.text,
+        ...page.totalSize === undefined ? {} : { totalBytes: page.totalSize },
+        truncated: page.truncated,
+    });
+    input.followup(prompt);
+    return {
+        buildNumber: detail.number,
+        outcome: detail.outcome,
+        logBytes: Buffer.byteLength(page.text, 'utf8'),
+        ...page.totalSize === undefined ? {} : { totalBytes: page.totalSize },
+        truncated: page.truncated,
+        promptChars: prompt.length,
+    };
+}
+/**
+ * Build the prompt that asks the model to diagnose one failed build.
+ *
+ * The instruction is deliberately strict about the shape of the answer: a cause
+ * with the log line that shows it, then one to three concrete fixes. Without that
+ * the model tends to restate the log or hand back generic advice, which is the
+ * one thing a person who has already read the log does not need.
+ * @param context - the build, its commits, and the log tail.
+ * @returns the message text to hand to a model turn.
+ */
+export function failurePrompt(context) {
+    const commits = (context.changes ?? []).slice(0, COMMITS_IN_PROMPT);
+    const lines = [
+        'Jenkins 构建失败。请分析失败原因，并给出最简洁的修复指引。',
+        '',
+        `任务：${context.jobPath} 构建 #${context.buildNumber}`,
+        `结果：${context.outcome}`,
+    ];
+    if (context.instanceName !== undefined && context.instanceName.length > 0) {
+        lines.push(`实例：${context.instanceName}`);
+    }
+    lines.push(`失败阶段：${context.failedStage ?? '未报告（该 job 不是 Pipeline，或 Jenkins 没给出阶段）'}`);
+    if (context.cause !== undefined && context.cause.length > 0) {
+        lines.push(`触发原因：${context.cause}`);
+    }
+    if (commits.length > 0) {
+        lines.push('本次构建的提交：');
+        for (const change of commits) {
+            const first = change.message.split('\n')[0]?.trim() ?? '';
+            const message = first.length > COMMIT_MESSAGE_CHARS ? `${first.slice(0, COMMIT_MESSAGE_CHARS)}…` : first;
+            lines.push(`- ${change.commitId.slice(0, 7)} ${message}${change.author.length === 0 ? '' : ` (${change.author})`}`);
+        }
+    }
+    const size = context.totalBytes === undefined ? '未知' : `${context.totalBytes} 字节`;
+    lines.push('', `下面是构建日志的尾部${context.truncated ? `（日志共 ${size}，只给了最后一段）` : ''}：`, '```', context.log.trimEnd(), '```', '', '请按这个顺序回答，不要复述日志：', '1. 最可能的失败原因（一句话），并指出日志里支撑它的关键行。', '2. 最简洁的修复指引（1-3 条，具体到改哪里/做什么）。', '3. 如果这段日志不足以判断，直接说要哪一段，或用 jenkins_log（可加 tail_lines，最多 2000 行）拉取更多；', '   需要时还有 jenkins_build_status 和 jenkins_workspace 可用。', '不要给与日志无关的通用建议，不要猜测日志里没有依据的东西。');
+    return lines.join('\n');
+}

package/lib/client/Builds.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The panel's drill-down: one job's build history, and one build's detail.
+ *
+ * Everything here is rendered inside the plugin's own panel — no view sends the
+ * browser to the Jenkins UI. The single exception is an artifact's download
+ * link, because a binary is not something a panel should inline.
+ * @module dsh-jenkins-plugin/client/Builds
+ */
+import type { ReactNode } from 'react';
+import type { JenkinsKey } from './locales.js';
+/** Copy binder for this plugin's namespace. */
+type Translate = (key: JenkinsKey, params?: Record<string, unknown>) => string;
+/**
+ * The job view: build history with paging.
+ * @param props - copy binder, instance id, job path, back navigation, and build opening.
+ * @returns the history view.
+ */
+export declare function JobView({ t, instanceId, jobPath, onBack, onOpenBuild }: {
+    t: Translate;
+    instanceId: string;
+    jobPath: string;
+    onBack: () => void;
+    onOpenBuild: (build: number) => void;
+}): ReactNode;
+/**
+ * The build view: header, progress, stages, log, and result area.
+ * @param props - copy binder, instance id, job path, build selector, and back navigation.
+ * @returns the build detail view.
+ */
+export declare function BuildView({ t, instanceId, jobPath, build, onBack }: {
+    t: Translate;
+    instanceId: string;
+    jobPath: string;
+    build: string;
+    onBack: () => void;
+}): ReactNode;
+export {};