CI Diet

English · 한국어 · 简体中文 · हिन्दी · Español · Français

状态： alpha；[email protected] 已发布到 npm。当前源码树在现有契约、分析引擎、补丁引擎、CLI、DSH 工具、设置页面和自包含 HTML 报告之外，新增了 设置 → CI Diet Reports 审查页面。审查页面已在之前的提交中通过真实浏览器 E2E。一次性默认值迁移另行在 DSH 0.2.1-rc.2 的 configEditor、SettingsForms 和 Loader 运行时中验证，并不表示这次重新验证了浏览器页面渲染。DSH 插件现在默认开启 preflight、历史网络访问和本地应用。

DSH 默认值和迁移。 新配置档默认启用 preflightEnabled、networkEnabled、localApplyEnabled 以及 CD001、CD002、CD004、CD006、CD008。锁定配置档迁移会记录 defaultsRevision: 2。已经迁移到修订版 1 的配置档会保留之后选择的开关和规则。状态路径、保留期限、配额和现有数值型账户输入均会保留。除非主动启用，CD003 和 CD005 保持关闭。金额估算会自动使用两项账户输入；留空表示未知，显式填写 0 是有效的。以前启用过计费的配置档在省略某个值时，会保留其零默认值。

CI Diet 用于查找可能被浪费的 GitHub Actions 工作，保留每个发现背后的证据，并预览供人审查的小型 workflow 修改。

只安装本工具不会节省 runner 分钟。 支持的 DSH 部署命令会在运行前自动检查节省候选项；workflow 修改只有在审查和批准后才会应用。DSH 插件没有批准、apply 或 revert 工具，preflight 本身不会修改文件。设置页面保存工具配置并显示主机提供的会话级报告和计划，不会自行优化 workflow。已批准的本地写入默认开启，但应用仍需单独的 digest 批准。任何发现都不能保证降低成本。

preflightEnabled 默认为开启。在带 workdir 参数的受支持 stateless DSH bash tool 中，literal git push、npm|pnpm|bun publish、wrangler deploy 或 npm|pnpm|bun run deploy 执行前会做一次离线检查。它会把 npm CD006、仅 PR workflow 缺少 concurrency、以及未显式设置下载缓存的 Bun frozen install 作为候选项提示审查。存在候选项时，第一次命令不会执行；模型审查这些项目后重试同一命令即可放行。preflight 本身不会联网，也不会自动修改文件；应用 plan 仍需要人工批准。持久 shell 和复杂 shell wrapper 无法可靠识别，preflight 会跳过。节省量尚未测量，因此不声称节省。

功能

静态扫描读取目标检出目录中的 workflow YAML。可选的历史同步通过只读 gh api 调用收集最近的运行。每项发现都带有证据级别（observed、inferred 或 static）以及各维度的采集 coverage。

规则	查找内容	可能的 plan
CD001	被较新提交取代的 PR 运行	concurrency 编辑
CD002	重叠的触发器	仅解释
CD003	仅文档变更仍执行重型检查	仅解释，默认关闭
CD004	过大的矩阵	仅解释
CD005	缺少 timeout-minutes 的 job	timeout 编辑，默认关闭
CD006	npm / pnpm / Bun	CD006
CD008	过长的 artifact 保留时间	保留时间编辑

CD001 针对因出现较新提交而重叠、已被取代的 PR 运行。CD005 为异常运行设置上限，不会缩短正常 job 的运行时间。CD008 改变 artifact 的存储保留时间，与 runner 分钟无关。CD003 和 CD005 在通过质量门槛前默认关闭。

CD006 还支持经过验证的 npm/pnpm 配置，以及使用 oven-sh/setup-bun@v2、随后执行 bun install --frozen-lockfile 并且采用受跟踪的文本文件 bun.lock 的 Bun 作业。Bun 会增加一个下载缓存步骤；安装和测试仍会运行。缓存恢复/保存的开销可能超过其收益。请参阅当前缓存防护和一个实测示例。下面的 npm 示例展示了其中一种受支持的配置。

安装与升级

CLI 需要 Node ^22.19.0 || >=24.0.0。插件支持 DSH >=0.2.1-rc.2 <0.3.0-0 和 >=0.2.2-rc.1 <0.3.0-0。版本 0.3.1 已在 DSH 0.2.1-rc.2 上验证；不支持 DSH 0.3.0。

npm install --global [email protected]
ci-diet --version

如果不希望全局安装，请把命令名 ci-diet 替换为 npx [email protected]，例如 npx [email protected] report --cwd .。

dsh plugin --profile web add [email protected]
dsh --profile web

安装后会注册插件工具、设置页面和 设置 → CI Diet Reports 审查页面。插件的 preflight、网络访问和本地应用默认开启。安装和启动不会调用 gh、收集历史、执行扫描或修改 workflow。

npm install --global dsh-ci-diet@latest
dsh plugin --profile web add dsh-ci-diet@latest

更新插件后重启 DSH。使用 dsh plugin --profile web list、ci-diet --version 或 npx dsh-ci-diet@latest --version 核对已安装版本。

首次扫描与历史报告

在要检查的仓库中运行这些命令。--cwd . 表示该仓库；--cwd 也可以接受其他路径，相对路径从实际生效的工作目录解析。第一个命令离线执行。历史采集需要单独、明确地允许网络访问。

ci-diet scan --cwd .
gh auth status
ci-diet sync --cwd . --network
ci-diet report --cwd .
ci-diet report --cwd . --format html --out report.html

scan 在没有网络的情况下输出静态报告；--json 或 --out FILE 可以写出该输出，但 CLI scan 不会把报告保存到状态存储。report 需要 CLI sync、插件 ci_diet_scan 或插件 ci_diet_sync 已保存的报告。在下面的纯 CLI 流程中，sync 会保存报告，随后 HTML 选项生成一个自包含文件。历史同步要求安装并认证 gh，且 gh 能读取该仓库的 Actions 运行和 job。sync --network 是 CLI 的网络启用方式，不需要 GitHub 写权限。历史不完整时仍会生成并保存报告，并标出覆盖不完整的维度。插件的离线 ci_diet_scan 会保存报告，因此可以直接在其后运行 ci_diet_report。

DSH 插件的网络访问默认开启，因此只要 gh 已安装并认证，就可以运行 ci_diet_sync。该开关只允许这个工具调用 gh；安装、启动和保存设置本身不会收集历史。要阻止插件联网，请在 设置 → CI Diet 中关闭 允许网络访问，然后选择 保存更改。该页面设置只作用于插件工具，不会开启 CLI 的 --network 参数。静态扫描和报告无需网络。设置页面本身不会执行优化。

清晰的聊天请求应写明执行顺序和审查边界。请把示例绝对路径换成自己的仓库路径：

以 cwd C:\work\my-repo 运行 ci_diet_scan，再用同一个 cwd 运行 ci_diet_sync 和 ci_diet_report。如果 gh 未认证或我关闭了网络访问，就在扫描后停止。如果用 ci_diet_plan 预览补丁，只显示编辑内容。不要批准、apply、revert、提交、推送或部署任何内容。

插件预览不会保存 plan。响应中的 nextCommand 会通过 CLI 重新创建 plan，使其持久保存并进入人工批准流程。

离线 npm 缓存 plan（CD006）

CD006 不需要运行历史。它匹配仓库根目录下的 job：actions/checkout 没有用户 with 选项，紧接其后恰好有一个未启用缓存的 actions/setup-node@v3 或 @v4 步骤，再下一步的 run 正好是 npm ci。根目录的 package.json 和 package-lock.json 必须是已提交的普通 JSON 文件。plan 只向 setup-node 添加 cache: npm 和 cache-dependency-path: package-lock.json，不改变 Node、action 版本、npm ci、测试或本地缓存。

ci-diet plan --cwd . --rule CD006 --workflow .github/workflows/ci.yml --job test --step 1
ci-diet plans --cwd . --plan PLAN_ID

--step 是 setup-node 步骤从 0 开始的索引；示例假设 checkout 是 0、setup-node 是 1。CLI plan 在内存中执行这次静态扫描，无需先 sync 就能保存 plan，并保留最新已保存的报告。插件 ci_diet_plan 仍需要已保存的报告，所以先运行 ci_diet_scan。审批和适用沿用下面的现有命令。plan 和 attestation 会在规划阶段保存；人工批准 plan 并运行 apply 之前，不会修改任何 workflow 文件。

CLI 命令参考

ci-diet scan --cwd .
ci-diet sync --cwd . --network
ci-diet sync --cwd . --network --repo OWNER/REPO --days 7
ci-diet report --cwd .
ci-diet report --cwd . --format json
ci-diet report --cwd . --format html --out report.html
ci-diet diagnose --cwd .
ci-diet prune
ci-diet changes --cwd .
ci-diet plans --cwd . --plan PLAN_ID
ci-diet report --cwd . --lang ko

scan 检查 workflow 文件。sync 仅在指定 --network 时读取历史；--repo 明确选择 OWNER/REPO，--days 在配置范围内调整回溯时间。report 输出文本、JSON 或 HTML，--out 相对于 --cwd 写入。diagnose 根据已保存历史解释 job 名称匹配和 coverage；加上 --require-complete 后，数据不完整会以退出码 3 结束。prune 按状态存储设置删除过期报告、plan 和缓存项。changes 列出已经应用的修改，plans 重新显示已保存的 plan。--config FILE 可为任意命令合并部分 JSON 配置。

审查、批准、apply 与 revert

成功的 CLI plan 会显示提议的 diff、类似 p_... 的真实 plan id，以及由 plan digest 最后 12 个字符组成的 confirmation。创建 plan 时会拒绝过期证据和其他不安全的写入；找不到 workflow 可能是用法错误并以退出码 1 结束。如果查看已保存 plan 时工作区或 workflow 消失，plans --plan 会隐藏 diff、保留 plan JSON、要求重新创建 plan，并以退出码 3 结束。workflow 字节与保存的源哈希不一致时也是如此。批准前请再次检查 diff 和 plan。

ci-diet plan --cwd . --rule CD001 --workflow .github/workflows/ci.yml --claims ci-only,replace-safe
ci-diet plans --cwd . --plan PLAN_ID
ci-diet approve --cwd . --plan PLAN_ID --confirm CONFIRMATION
ci-diet apply --cwd . --plan PLAN_ID
ci-diet revert --cwd . --change CHANGE_ID

把 PLAN_ID 换成 plan 输出的 id，把 CONFIRMATION 换成 digest 的最后 12 个字符，把 CHANGE_ID 换成 apply 输出的 id。每个值都作为字面参数传入，不要输入尖括号。approve 创建一次性批准，apply 只改写一个 workflow 文件中计划好的字节范围，revert 恢复该变更的备份。检查结果 diff，并按需运行仓库检查。CI Diet 不会提交、推送、部署、运行 workflow、修改分支保护或删除 artifact。

对于符合条件的仅 PR CI，CD001 示例中的 ci-only 和 replace-safe 是人工 attestation。它们表示操作者已经审查取消运行的语义，不是绕过开关。CD005 需要测量得到的 --job 和 --minutes；CD008 需要 --job、目标 step 从 0 开始的数字 --step 数组索引以及 artifact claims。CD006 需要 --job 和 setup-node/setup-bun 步骤从 0 开始的 --step 索引，不需要 claims。两个步骤规则中的数字 step 都是数组索引，不是步骤名称令牌。

状态与限制

CLI 和插件共享默认状态目录：Windows 上为 %LOCALAPPDATA%\CI-Diet\profiles\default，其他平台为 ~/.local/state/ci-diet/profiles/default。插件里的 stateDir 覆盖会形成独立存储；在 CLI 的 plan、approve、apply、revert 中都要用 --state-dir 传入同一个绝对路径。CLI 的相对 --state-dir 从实际生效的 --cwd 解析。现有状态不会在不同目录间自动迁移。

Web 客户端有设置页面和 CI Diet Reports 审查页面。报告、批准、apply 和 revert 控件已在之前的提交中通过真实浏览器 E2E。默认值迁移则在 DSH 0.2.1-rc.2 运行时中，使用 configEditor、SettingsForms、Loader 和临时 profile 单独验证：legacy false 会保存为 true，之后显式保存的 false 在重启后仍保持关闭。这不是新的浏览器渲染验证。批准和应用会从该页面发送给主机，localApplyEnabled 默认开启。插件工具不执行批准或应用。plan 会对一个现有 workflow 文件做字节范围编辑，不支持的结构会被拒绝。历史或 workflow 归属信息不完整时，发现可能有误或缺失，其他系统可能拥有更准确的账单数据。请把报告作为审查证据，并在 GitHub 中单独确认效果。

成本与证据

字段	含义
observedRunnerSeconds	采集运行中记录的 runner 时间
modeledRoundedMinutes	为建模按 job 向上取整的分钟数
listPriceUsd	按报告内嵌的定价快照计算的费用
actualBilledUsd	在能够证明实际账单前始终为 null

报告会嵌入定价快照和内容哈希，以便以后复现数字。它不会声称自动节省。HTML 报告只包含内联 CSS，没有脚本或外部请求。

语言

DSH 设置 UI、CLI 消息、HTML 报告和这六份 README 支持英语、韩语、简体中文、印地语、西班牙语和法语。详细规范仅提供英语。选择顺序为 --lang、DSH locale、LC_ALL/LC_MESSAGES/LANG、英语。CLI 语言代码是 en、ko、zh-Hans、hi、es、fr；把示例命令中的 ko 换成所需代码。地区标签按语言解析。报告以英语保存，显示时再翻译。规则 id、错误代码、枚举值、路径、哈希和数字保持原文。HTML 的 lang 属性跟随所选 locale。DSH 工具描述在加载插件时固定，因此更改 DSH 语言偏好后需要重新加载。

开发

bun install
node scripts/test-core.mjs
node scripts/gen-types.mjs --check
node scripts/sync-contracts.mjs --check
bun run typecheck
bun run lint
bun run test:docs

使用 Node 运行测试，以保持发布入口与 Node 兼容。Bun 仅用于依赖管理。

发布

推送与 package.json 一致的标签会启动 .github/workflows/publish.yml。下面的两个参数中，把字面 VERSION 换成新版本；0.3.1 已经发布，不要再次创建该标签。

git tag vVERSION
git push origin vVERSION

工作流会比较标签与 package.json、运行发布检查、拒绝已存在的 npm 版本，并通过 GitHub OIDC 使用 npm trusted publishing 发布。trusted publisher 必须指定 publish.yml。

目录结构

src/core        workflow parsing, rules, savings, patch engine
src/adapters    GitHub, git, storage
src/client      Web Settings and review UI
src/dsh         host plugin and bundle code
src/cli         command-line entry
src/shared      i18n and shared helpers
contracts       JSON Schemas from the frozen design pack
examples        sample records and evaluation vectors
docs/spec       normative specification
scripts         contract and documentation checks
tests/unit      fast checks that need no network

文档

详细规范、规则、成本、补丁、存储和决策文档均使用英语。规范索引是 docs/spec/README.md。另见规则、成本模型、补丁模型、存储与错误、决策、测量、插件与 CLI 指南以及契约来源。

许可证

MIT