baris2828/muda-audit

# muda 無駄 **为你的代码库进行精益浪费审计。走近现场，看清七种浪费，持续改进。** [](https://github.com/baris2828/muda-audit/actions/workflows/ci.yml) [](#muda-audits-muda) [](pyproject.toml) [](LICENSE)  丰田教会了制造业在车间现场识别七种浪费（*muda*）： 运输、库存、动作、等待、过度生产、过度加工、缺陷。 作为精益顾问，在真实工厂车间行走了六年后，我发现我所接触过的每个代码库中都存在这同样的七种模式。然而在软件行业，却从来没有人指出过它们。 `muda` 是一个 CLI 工具，它能对代码库执行一次**“现场巡视”**：它前往真实的工作场所， 不带评判地观察，将每一次观察映射为七种浪费之一，然后执行精益思想中必做的下一步——通过**帕累托分析**，向你展示最值得优先修复的关键少数浪费。 我的咨询原则是“*在自动化之前先消除*”。 这个工具正是该原则的可执行化身。 ``` ╭─────────────────────────────────────────────────╮ │ muda 無駄 · gemba walk of ./demo-shop │ │ 6 files observed · 11 findings · waste score 20 │ ╰─────────────────────────────────────────────────╯ The seven wastes ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Waste ┃ Findings ┃ Score ┃ Share ┃ Pareto ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ Defects │ 3 │ 8 │ 40% │ ██████████████████ ◀ focus │ │ Inventory │ 3 │ 5 │ 25% │ ███████████ ◀ focus │ │ Motion │ 2 │ 2 │ 10% │ ████ ◀ focus │ │ Overprocessing │ 1 │ 2 │ 10% │ ████ ◀ focus │ │ Waiting │ 1 │ 2 │ 10% │ ████ │ │ Overproduction │ 1 │ 1 │ 5% │ ██ │ └────────────────┴──────────┴───────┴───────┴─────────────────────────────┘ Pareto: the ◀ focus wastes account for ~80% of the score. Start there. ┃ fix now ┃ defects ┃ Debugger left in code ┃ src/app.py:15 ┃ ┃ fix now ┃ defects ┃ Possible hardcoded secret ┃ src/app.py:5 ┃ ┃ should fix ┃ inventory ┃ Dependency never imported ┃ requirements.txt ┃ ┃ should fix ┃ waiting ┃ Stale TODO (waiting 260d) ┃ src/app.py:4 ┃ ╭──────────────── Kaizen — built-in heuristics ────────────────╮ │ 1. Defects: Fix severity-3 items today: remove debuggers, │ │ rotate anything that looks like a committed secret … │ │ 2. Inventory: Delete what git already remembers … │ ╰──────────────────────────────────────────────────────────────╯ ``` ## 映射：车间现场 → 代码库 这个项目的核心思想是一张转换对照表。每种浪费都保留了其在制造业中的原始含义，并获得了具体、可检查的软件等价物： | 浪费 無駄 | 在车间现场 | 在你的代码库中 —— `muda` 检查的内容 | |---|---|---| | **Transport（运输）** | 在工位间搬运零件而不增加价值 | 仅用于穿梭导入/重新导出的穿透式模块 | | **Inventory（库存）** | 积压在货架上占用资金并掩盖问题的库存 | 声明了但从未导入的依赖；被注释掉的代码块 | | **Motion（动作）** | 工人来回走动寻找摆放位置不佳的工具 | 超大文件、过长函数、深度嵌套的路径 | | **Waiting（等待）** | 半成品排队等待下一个工序 | TODO/FIXME/HACK 注释 —— 通过 `git blame` 计算存在时间，越久越糟糕 | | **Overproduction（过度生产）** | 在任何实际需求产生之前提前生产 | 定义了但从未被引用的函数和类 | | **Overprocessing（过度加工）** | 在两个工位上对同一个零件进行两次加工 | 字节完全相同的重复文件 | | **Defects（缺陷）** | 流到下游的废品和返工 | 残留的调试器、裸露的 `except:`、动态 eval、硬编码的密钥 | 运行 `muda wastes` 即可在终端查看此表格。 ## 快速开始 ``` pipx install muda-audit # or: pip install muda-audit muda walk . # audit the current repo muda walk . --top 25 # show more findings muda walk . --report audit.md # Markdown report for the PR / wiki muda walk . --json audit.json # machine-readable, for dashboards muda walk . -x "*.ipynb" -x "docs/*" # exclude globs ``` 代码仓库和包名为 `muda-audit`；命令仅为 `muda`。 ## 30 秒试用 ``` python examples/build_demo.py # generates ./demo-shop — a tiny webshop full of deliberate waste muda walk demo-shop # watch the walk surface all seven wastes ``` 生成的测试工坊会有大约 8 个月前的 git 历史记录，因此 `git blame` 可以将这些标记标记为*过期的*。巡视过程会刻意忽略 `.gitignore`，因此在仓库根目录运行 `muda walk .` 也会扫到该工坊 —— 玩转完毕后，你可以直接删除 `demo-shop/`。 ## 改善层：可选的导师 发现浪费只是第一步；精益的核心在于采取对策。每次巡视后，一位**导师**会将帕累托分析结果转化为优先排序的改善建议。在同一个接口（策略模式）背后，有两个可互换的顾问： - **HeuristicSensei** —— 针对每种浪费提供精选指导，随工具自带，支持离线运行。默认选项。 - **AISensei** —— 发送匿名摘要（评分 + 主要发现，绝不会上传你的源代码文件）到 Anthropic API，以获取针对代码库的定制建议。 ``` pip install "muda-audit[ai]" # the SDK is an optional extra, never a hard dependency export ANTHROPIC_API_KEY=sk-ant-... muda walk . --ai ``` **优雅降级是一项功能，而非权宜之计：**无论没有密钥、没有 SDK、没有网络，还是调用失败——审计都会照常完成并给出启发式建议，同时告诉你原因。核心工具仅有两个依赖（`typer`，`rich`），并且绝不依赖云服务。 | 变量 | 用途 | 默认值 | |---|---|---| | `ANTHROPIC_API_KEY` | 使用 `--ai` 启用 AI 导师 | 未设置 → 使用启发式 | | `MUDA_MODEL` | 覆盖模型 | `claude-haiku-4-5-20251001` ([当前可用模型](https://docs.claude.com/en/api/overview)) | ## CI 质量门禁：拉动安灯拉绳 在丰田生产系统中，任何工人看到缺陷时都可以拉动**安灯拉绳**让生产线暂停。`--fail-on-score` 就是你的 pipeline 中那根安灯拉绳： ``` # .github/workflows/quality.yml - name: Lean waste gate run: | pip install muda-audit muda walk . --fail-on-score 25 --report muda-report.md ``` 预算由你来定：从你代码库当前的水平开始，然后逐渐收紧——这就是*改善*，即持续改进，被编码为一个 CI 数值。 ### muda 审计 muda 本代码库对自身要求极为严格。[CI](.github/workflows/ci.yml) 在每次推送时都会运行 `muda walk . --fail-on-score 0`：此代码库中的**任何**浪费都会导致流水线中断。实现这一目标意味着需要解决典型的扫描器自引用问题（浪费检测器发现了自己的检测模式）——解决方案是仅统计真实代码注释内的标记，并在测试中伪装测试字符串，这与安全扫描器使用的技术相同。 ## 架构 ``` flowchart LR A[walker.py
the gemba walk] -->|FileInfo| B{wastes/ registry} B --> C1[transport] B --> C2[inventory] B --> C3[motion] B --> C4[waiting] B --> C5[overproduction] B --> C6[overprocessing] B --> C7[defects] C1 & C2 & C3 & C4 & C5 & C6 & C7 -->|Findings| D[scoring.py
waste score + Pareto] D --> E[sensei.py
Heuristic / AI advice] D --> F[report.py] E --> F F --> G1[terminal · Rich] F --> G2[markdown] F --> G3[json] ``` 设计决策，按我做出的顺序排列： 1. **一次巡视，多个观察者。** 对代码库的遍历仅进行一次；各项检查接收不可变的 `FileInfo` 记录，不会重新读取文本内容。唯一的例外是刻意为之的：重复项检查会对文件字节进行哈希处理，而等待项检查会调用 `git blame`。 2. **注册表，而非框架。** 每种浪费都是一个实现某个 `Protocol` 的模块。第八种浪费只需一个新文件和一行导入语句——walker、scorer 和 reporters 保持不变（开闭原则）。 3. **导师的策略模式。** 启发式和 AI 顾问在 `get_advice()` 背后可互换；AI 路径在任何失败时都会降级为启发式，因此审计绝不依赖于网络。 4. **分析一次，渲染三次。** 终端、Markdown 和 JSON 视图使用相同的发现和评分结果。渲染过程绝不重新运行分析。 5. **标准库优先。** 解析使用标准库中的 `ast`、`tomllib`、`hashlib`、`subprocess`。仅有两个运行时依赖，且都仅用于呈现。 ## 诚实的局限性 `muda` 是一次现场巡视，而非法庭判决。这些检查是刻意保持保守的启发式算法：未使用依赖检测能识别常见的别名映射（`scikit-learn` → `sklearn`），但无法涵盖所有的插件系统；死代码检测会将任何文本提及视为引用，因此倾向于少报而不是多报；重复检测仅限字节完全相同。这些发现是带有严重性分级的、旨在引发改善讨论的切入点 —— 在删除前请务必自行验证。 目前在 Python 支持方面最为完善，并具备基础的 JS/TS 支持。这些检查是通过对 14 个真实世界的代码库进行实地测试校准而成的。 ## 路线图 近期目标：近似重复检测（规范化 AST 哈希）、一种仅在 PR 中审计已更改文件的 `--diff` 模式、通过 `muda.toml` 设定特定仓库的阈值，以及针对某些精益学派所增加的第八种浪费 ——“未利用的人才”即未记录的公共 API 的检查机制。 ## 关于 跨越不同行业的六年流程咨询经验。 这个工具之所以存在，是因为“七种浪费”被证明是一个通用的视角：它们既适用于车间现场，也同样适用于 `src/` 目录。 *“在自动化之前先消除。” [LinkedIn](https://www.linkedin.com/in/baris-aydin-engineering/) · [GitHub](https://github.com/baris2828) ## 许可证 [MIT](LICENSE)

标签：Blue Team, Python, 云安全监控, 动态分析, 无后门, 精益开发, 逆向工具, 静态分析