# @adlc/flail-detector 中文文档

规范地址：https://npmcn.com/package/%40adlc/flail-detector/

版本：1\.12\.0
npm 元数据更新时间：2026-10-10T03:04:33.281Z
中文译文更新时间：2026-11-05T23:53:17.805Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adlc/flail-detector
原文对照：https://npmcn.com/package/%40adlc/flail-detector/?lang=original
项目主页：https://github.com/voodootikigod/adlc/tree/main/packages/flail-detector#readme
源码仓库：https://github.com/voodootikigod/adlc

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：36.3 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-06-13T21:12:15.446Z
- 最新版本发布：2026-10-10T03:04:32.755Z
- 近 30 天下载量：8821（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Session-log flail analysis - 建筑剂的机械双击规则(C6/P4主管).

## 安装

```sh
npm install @adlc/flail-detector
```

也可以使用：`pnpm add @adlc/flail-detector`、`yarn add @adlc/flail-detector`、`bun add @adlc/flail-detector`

## README

# flail 检测器

Session-log flail analysis——机械双击规则. ADLC 阶段 **C6/P4主管**。 。 。 .

监视一个用于 flail 签名的构建会话日志 。 触发:发布判决 `flail`,打印一个推荐块,然后2号出口,这样CI就可以打开了。 满 有决定力,没有LLM呼叫.

## 使用量

```
flail-detector <log-file> [--scope <glob>...] [--max-repeat <n>] [--max-bytes <n>] [--spent-tokens <n>] [--budget <n>] [--record] [--ticket <id>] [--json]
```

### 参数

| 参数 | 说明 |
| --- | --- |
| `<log-file>` | 会话日志文件分析路径( 需要) |

### 旗帜

| 旗帜 | 默认 | 说明 |
| --- | --- | --- |
| `--scope <glob>` | _(无)_ | 已声明的镜光图案( 可重复) 。 当给出时,在工具日志行中找到的文件路径会被标记为: **侵犯范围**。 。 。 . |
| `--max-repeat <n>` | `2` | 触发 **重复错误** 当一个正态错误签名出现qqn次时发出信号. |
| `--max-bytes <n>` | _(无限制)_ | 触发 **大小** 当日志文件超过n字节时发出信号. |
| `--spent-tokens <n>` | _(无)_ | 计算出该票的支出(例如: `adlc spend --ticket <id> --json`) (中文(简体) ). 必须用 `--budget`。 。 。 . |
| `--budget <n>` | _(无)_ | 罚单已经宣布为象征性预算(`ticket.budget`,或 `model-router`' 所排放的平板电脑' `budget`) (中文(简体) ). 触发 **预算** 信号 `--spent-tokens` 超过它。 必须用 `--spent-tokens` - 要么单独是使用错误. |
| `--record` | 关 | 在一清二楚的判决中 `flail-check` 条目为 `.adlc/manifest.jsonl` (ADLC P4证据——见 `@adlc/runner`) (中文(简体) ). 从不写 `flail` 判决,从不 `could-not-analyze` 结果(问题622). |
| `--ticket <id>` | _(无)_ | 进入录制清单的票 可选记录为: `null` 在省略时,与 `rails-guard --record`。 。 。 . |
| `--json` | 关 | 用于管弦乐手的机器可读JSON输出. |
| `--help` | —— 说 | 打印帮助并退出 0. |

## 退出代码

| 代码 | 含义 |
| --- | --- |
| `0` | 门口通过——没有检测到闪光信号(清洁) |
| `1` | 操作错误——文件未找到,参数差,或 **`could-not-analyze`**:该日志没有任何分析(没有非空行). 从来没有过关——任何记录,即使有 `--record`。 。 。 . |
| `2` | 门失败——触发了一个或多个发光信号 |

## 信号

### 1\. 重复错误

匹配线条 `/error|exception|failed|cannot|ENOENT/i` 已正常化 (小写; 条形数字、 二进制字符串、 引用字符串、 绝对路径), 然后按单个签名计算。 正在发生的任何签名 `--max-repeat` 时间触发这个信号.

**正常化** 确保 `Error: cannot find module "lodash" at line 42` 财务报告和审定财务报表 `Error: cannot find module "express" at line 99` 崩溃到相同的 签名 – 错误类型是最重要的,而不是不同的操作.

### 2\. 范围侵犯

只有活动时 `--scope` 给出。 从普通路径取出的文件 工具日志模式 :

-   `Writing <path>`
-   `Editing <path>`
-   `Created <path>`
-   `"file_path":"<path>"` (JSON工具-日志格式)

带有路径的动词( :`Writing`, (中文(简体) ), `Editing`, (中文(简体) ), `Created`)必须打开行,在缩进和日志前缀后可选择:时间戳(`12:03:01 Writing <path>`页:1`[INFO] Editing <path>`),或大写级别名称(`WARN Created <path>`) (中文(简体) ). 动词在其它任何地方都是流传而无路可走,所以工具结果如: `File created successfully at: <path>` 未读取为写入 `successfully`。 。 。 .

任何不匹配至少一条路径 `--scope` glob是一种违反.

### 3\. 编辑-编辑

在QQ 3 写入/编辑日志行中出现相同的文件路径( 不管 哪个动词——写、编辑或创建)。 表示代理是循环 重回同一文件.

### 4\. 规模

何时 `--max-bytes` 如果日志文件字节数超过 阈值.

### 5\. 预算

当两者 `--spent-tokens` 财务报告和审定财务报表 `--budget` ,如果测量到 支出超过票面上宣布的上限——ADLC.md C6's "token system past" 门票预算"触发。 两个数字都来自日志本身: `flail-detector` 不测量符号,它只比较两个数字 电话供应。 与 `adlc spend` 测量边和 `model-router`已发射 `budget` (或机票自己申报) `budget` 字段)。 只给两个旗帜中的一个是使用错误 (exit 1) 而不是沉默的无声.

## 输入处理

如果日志中一半以上的非空行解析为 JSON 对象,则 文件被视为 **贾森勒**: 键的字符串值 `content`, (中文(简体) ), `text`,以及 `message` 递归取出并输入信号探测器。 全体 其他文件作为 **纯文本**,一次一行。 (笑声).

## 产出

可读( 默认) :

```
flail-detector: FLAIL
  bytes: 361
  signals:
    repeated-error (1 signature(s)):
      [2x] error: cannot resolve module at line in
    scope-violation (1 path(s) outside scope):
      /etc/hosts
    edit-churn (1 file(s) edited >= 3 times):
      [3x] src/index.ts

  recommendation:
    Kill the session. Append these dead-ends to the ticket: error: cannot resolve module at line in
```

机器可读取(`--json`:

```json
{
  "verdict": "flail",
  "signals": [...],
  "bytes": 361,
  "recommendation": "Kill the session. Append these dead-ends to the ticket: ..."
}
```

当日志无所分析时——它是空的或只有空白的—— 判决是 `could-not-analyze` 且退出代码为 1,而非 0 :

```json
{
  "verdict": "could-not-analyze",
  "reasons": ["log has no non-empty lines (empty or whitespace-only file)"],
  "bytes": 0,
  "signals": []
}
```

在文本模式下,结果印数相同 `flail-detector: could not analyze — <reasons>` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请说 这是业务成果,从来不是通行证:主管指向一个日志 从未写过的路径不能有绿色P4门 `--record` 写入否 `flail-check` 条目(问题622).

范围故意不属于本决定的范围: 完全没有写作 主管,比如 `@adlc/fleet` 传票 `--scope` 在每次咨询中——所以对有行但无可提取文件路径的日志进行分析 通常情况下(重复的 -- -- 过火、大小和预算信号仍在起火;范围信号) 根本没什么可标注的). 解决了从真实日志中提取路径不足的问题 第623期的论文.

## 实例

```bash
# Analyze a plain-text session log
flail-detector session.log

# Enforce scope (write/edit must stay inside src/ or test/)
flail-detector session.log --scope 'src/**' --scope 'test/**'

# Raise the error-repeat threshold to 3
flail-detector session.log --max-repeat 3

# Flag oversized logs (e.g. > 1 MB context)
flail-detector session.log --max-bytes 1048576

# Flag token spend past the ticket's declared budget
flail-detector session.log --spent-tokens 85000 --budget 50000

# JSON for orchestrators
flail-detector session.log --json

# Record P4 evidence on a clean pass (adlc run p4 requires this)
flail-detector session.log --scope 'src/**' --record --ticket T42
```

## ADLC 阶段

**C6/P4主管.** 机械地编码出两击再生规则. 设计原理见ADLC.md §C6.

打算在每次施工后由P4主管援引。 打开 `flail` (第2出):杀死会话,将死端的签名附入罚单,并 再生新鲜。 第二起触发:升级为P2——罚单错了,不是 探员.

## 与兄弟姐妹工具的关系

-   **护栏(C5)**: 执行 git diffs 上被冻结的栏杆; 显示器 监视实时会话记录 用于行为漂移 .
-   **协商一致(C7)**: fallail 后引用的扇出固定策略 已确认; flail-deactor 是触发它的上游门.
-   **死前(C2)**\- 上游风险分析 风险在运行时间实现.

## 核心差距

无。 此工具只使用 `parseArgs`, (中文(简体) ), `opError`, (中文(简体) ), `printJson`, (中文(简体) ), `sha256`, (中文(简体) ), `pass`, (中文(简体) ), `gateFail`,以及 `globMatch` 从 `@adlc/core`没有LLM,没有git. `--record` 这是 一个分类账写这个工具,通过 `@adlc/gate-manifest`是因为 `appendManifestEntry`,镜像 `rails-guard`是因为 `--record` (问题106)- 没有它, `adlc run p4`是因为 `flail-check` 永远无法满足要求 以任何有记录的流量表示.

## 常见问题

### @adlc/flail-detector 是什么？

Session-log flail analysis - 建筑剂的机械双击规则\(C6/P4主管\)\.

### 如何安装 @adlc/flail-detector？

在项目目录运行 npm install @adlc/flail-detector，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 flail-detector，可以用 npx flail-detector 直接运行。

### @adlc/flail-detector 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adlc\_\_flail-detector 是否存在。

### @adlc/flail-detector 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adlc/flail-detector 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @adlc/flail-detector 可以商用吗？

@adlc/flail-detector 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adlc/flail-detector 的下载量有多少？

根据 npm 官方下载统计，@adlc/flail-detector 在 2026/10/05 – 2026/11/03 这 30 天内被下载 8,821 次，日均约 294 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adlc/flail-detector 还在维护吗？

最新版本 1\.12\.0 发布于 2026/10/10（27 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/06/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。