desloppify

Desloppify

1. 你的工作

诚实地将严格评分最大化。你的主要循环：扫描 → 规划 → 执行 → 重新扫描。遵循扫描输出中的给 Agent 的说明——不要用自己的分析取而代之。

不要偷懒。 大型重构和细致的小修复都要全力以赴。如果需要修改 20 个文件，就修改 20 个文件。如果只需改一行，就改这一行。任务无分大小——要彻底修复，而不是敷衍了事。

2. 工作流

分三个阶段循环执行。

单体仓库和多项目目录

如果工作区包含多个程序（例如位于同级目录的前端和后端），请分别扫描每个程序——不要扫描父目录：

desloppify --lang typescript scan --path ./frontend
desloppify --lang python scan --path ./backend

每个 --path 目标都应是一个独立完整的项目。扫描包含多个程序的父目录会混合状态和路径上下文，导致结果不可靠。

阶段 1：扫描和审查——了解代码库

desloppify scan --path .       # analyse the codebase
desloppify status              # check scores — are we at target?

扫描后，务必运行 desloppify next——它会明确告诉你接下来要按什么顺序做什么。不要自行解读扫描输出，也不要询问用户该做什么。只需运行 next 并遵循其说明。

扫描会告知你是否需要审查主观维度。遵循其中的说明。要手动触发审查：

desloppify review --prepare    # then follow your runner's review workflow

阶段 2：规划——决定要处理什么

审查完成后，next 呈现的执行队列中会出现分诊阶段和计划创建阶段。按顺序完成——next 会说明每个阶段需要在 --report 中提供什么：

desloppify next                                        # shows the next execution workflow step
desloppify plan triage --stage observe --report "themes and root causes..."
desloppify plan triage --stage reflect --report "comparison against completed work..."
desloppify plan triage --stage organize --report "summary of priorities..."
desloppify plan triage --complete --strategy "execution plan..."

自动分诊：使用 desloppify plan triage --run-stages --runner codex（Codex）、--runner claude（Claude）或 --runner rovodev（Rovo Dev）。选项：--only-stages、--dry-run、--stage-timeout-seconds。

然后整理队列。计划决定了 next 提供的所有内容——next 是执行队列，不是完整待办列表。不要跳过这一步。

desloppify plan                          # see the living plan details
desloppify plan queue                    # compact execution queue view
desloppify plan reorder <pat> top        # reorder — what unblocks the most?
desloppify plan cluster create <name>    # group related issues to batch-fix
desloppify plan focus <cluster>          # scope next to one cluster
desloppify plan skip <pat>              # defer — hide from next

阶段 3：执行——完成队列中的所有任务

信任计划并执行。不要在队列执行过程中重新扫描——先完成队列。

先创建分支。 创建专用分支——切勿直接向 main 提交健康度修复：

git checkout -b desloppify/code-health    # or desloppify/<focus-area>
desloppify config set commit_pr 42        # link a PR for auto-updated descriptions

循环：

# 1. Get the next item from the execution queue
desloppify next

# 2. Fix the issue in code

# 3. Resolve it (next shows the exact command including required attestation)

# 4. When you have a logical batch, commit and record
git add <files> && git commit -m "desloppify: fix 3 deferred_import findings"
desloppify plan commit-log record      # moves findings uncommitted → committed, updates PR

# 5. Push periodically
git push -u origin desloppify/code-health

# 6. Repeat until the queue is empty

修复后评分可能暂时下降——级联效应很正常，继续处理。 如果 next 建议使用自动修复工具，先运行 desloppify autofix <fixer> --dry-run 预览，然后再应用。

队列清空后，返回阶段 1。 届时会发现新问题，级联效应会消退，优先级也会发生变化。这就是循环。

3. 参考

关键概念

• 层级：T1 自动修复 → T2 快速手动处理 → T3 判断后处理 → T4 大型重构。
• 自动聚类：next 会自动将相关发现分组。使用 next --cluster <name> 深入查看。
• 区域：生产代码/脚本（计分）、测试/配置/生成文件/供应商代码（不计分）。使用 zone set 修复。
• Wontfix 成本：会扩大宽松评分与严格评分之间的差距。差距扩大时，应重新审视过去的决定。

评分

总评分 = 25% 机械评分 + 75% 主观评分。

• 机械评分（25%）：自动检测的问题——重复、死代码、代码异味、未使用的导入、安全问题。通过修改代码并重新扫描来修复。
• 主观评分（75%）：设计质量审查——命名、错误处理、抽象、清晰度。审查前为 0%。需要审查时，扫描会提示你。
• 严格评分是首要目标：wontfix 项目仍计为未解决。总评分与严格评分之间的差距就是你的 wontfix 欠账。
• 评分类型：总评分（宽松）、严格评分（wontfix 计入）、客观评分（仅机械评分）、已验证评分（仅计入已确认的修复）。

评审

获取主观评分的四种方式：

• 本地运行器（Codex）：desloppify review --run-batches --runner codex --parallel --scan-after-import — 自动端到端完成。
• 本地运行器（Claude）：desloppify review --prepare → 启动并行子 Agent → desloppify review --import merged.json — 详情请参阅技能文档覆盖文件。
• 本地运行器（Rovo Dev）：desloppify review --run-batches --runner rovodev --parallel --scan-after-import — 通过 acli rovodev run 子进程自动端到端完成。
• 云端／外部：desloppify review --external-start --external-runner claude → 按照会话模板操作 → --external-submit。
• 手动方式：desloppify review --prepare → 按维度评审 → desloppify review --import file.json。

批次输出与导入文件名： 子 Agent 的单个批次输出必须命名为 batch-N.raw.txt（纯文本／JSON 内容，扩展名为 .raw.txt）。--import merged.json 或 --import findings.json 中的 .json 文件名指最终合并的导入文件，而非单个批次输出。批次输出不得使用 .json 扩展名。

子 Agent 并行数限制： 不要一次性启动所有评审批次。请分成较小的批次启动子 Agent，通常每批并发 3-5 个 Agent，并等待当前批次完成后再启动下一批。如果 Agent 返回空结果、不完整结果或类似速率限制的结果，请缩小批次规模，仅重试失败的批次。一次启动 20 个以上的子 Agent 可能会耗尽 API 配额，导致没有可用的评审输出。

• 先导入，再修复 — 导入会创建受跟踪的状态条目，以便进行关联。
• 与目标匹配的评分会触发自动重置，以防止刷分。请使用 Agent 覆盖文档中所述的盲评工作流（例如 docs/CLAUDE.md、docs/HERMES.md）。
• 即使是中等评分（60-80），也能大幅改善整体健康度。
• 过时的维度会自动显示在 next 中 — 只需按照队列处理。

诚信规则： 评分只能依据证据 — 不得参考先前的聊天上下文、评分历史或目标阈值锚定。当证据不明确时，给出较低分数并说明不确定性。评估每个请求的维度；不得遗漏任何维度。

评审输出格式

为评审导入返回机器可读的 JSON。对于 --external-submit，请包含生成模板中的 session：

{
  "session": {
    "id": "<session_id_from_template>",
    "token": "<session_hmac_from_template>"
  },
  "assessments": {
    "<dimension_from_query>": 0
  },
  "findings": [
    {
      "dimension": "<dimension_from_query>",
      "identifier": "short_id",
      "summary": "one-line defect summary",
      "related_files": ["relative/path/to/file.py"],
      "evidence": ["specific code observation"],
      "suggestion": "concrete fix recommendation",
      "confidence": "high|medium|low"
    }
  ]
}

findings 必须与 query.system_prompt 完全一致（包括 related_files、evidence 和 suggestion）。未发现缺陷时使用 "findings": []。导入采用失败即关闭策略：除非传入 --allow-partial，否则无效的 findings 会导致导入中止。评估分数会根据可信的内部或云端会话导入自动应用。仍支持旧版 --attested-external。

导入方式

• 稳健的会话流程（推荐）：desloppify review --external-start --external-runner claude → 使用生成的提示词／模板 → 运行显示的 --external-submit 命令。
• 持久化评分导入（旧版）：desloppify review --import findings.json --attested-external --attest "I validated this review was completed without awareness of overall score and is unbiased."
• 仅 findings 的备用方式：desloppify review --import findings.json

评审 Agent 提示词

支持 Agent 定义的运行器（Cursor、Copilot、Gemini）可以创建专用的评审 Agent。请使用此系统提示词：

You are a code quality reviewer. You will be given a codebase path, a set of
dimensions to score, and what each dimension means. Read the code, score each
dimension 0-100 from evidence only, and return JSON in the required format.
Do not anchor to target thresholds. When evidence is mixed, score lower and
explain uncertainty.

有关 Agent 配置格式，请参阅下文中对应编辑器的覆盖部分。

计划命令

desloppify plan reorder <cluster> top       # move all cluster members at once
desloppify plan reorder <a> <b> top        # mix clusters + findings in one reorder
desloppify plan reorder <pat> before -t X  # position relative to another item/cluster
desloppify plan cluster reorder a,b top    # reorder multiple clusters as one block
desloppify plan resolve <pat>              # mark complete
desloppify plan reopen <pat>               # reopen
desloppify backlog                          # broader non-execution backlog

提交跟踪

desloppify plan commit-log                      # see uncommitted + committed status
desloppify plan commit-log record               # record HEAD commit, update PR description
desloppify plan commit-log record --note "why"  # with rationale
desloppify plan commit-log record --only "smells::*"  # record specific findings only
desloppify plan commit-log history              # show commit records
desloppify plan commit-log pr                   # preview PR body markdown
desloppify config set commit_tracking_enabled false  # disable guidance

将 findings 设为 fixed 后，该工具会显示未提交的工作、已提交的历史记录以及建议的提交消息。在外部完成提交后，运行 record，将 findings 从未提交移至已提交，并自动更新关联的 PR 描述。

Agent 指令

指令是在生命周期阶段转换时显示给 Agent 的消息——可用于切换模型、设置约束或提供特定上下文的说明。

desloppify directives                     # show all configured directives
desloppify directives set execute "Switch to claude-sonnet-4-6. Focus on speed."
desloppify directives set triage "Switch to claude-opus-4-6. Read carefully."
desloppify directives set review "Use blind packet. Do not anchor on previous scores."
desloppify directives unset execute       # remove a directive

可用阶段：execute、review、triage、workflow、scan（以及 review_initial、triage_postflight 等细粒度变体）。

快速参考

desloppify next --count 5                         # top 5 execution items
desloppify next --cluster <name>                  # drill into a cluster
desloppify backlog --count 5                      # top 5 backlog items outside execution
desloppify show <pattern>                         # filter by file/detector/ID
desloppify show --status open                     # all open findings
desloppify plan skip --permanent "<id>" --note "reason" --attest "..." # accept debt
desloppify exclude <path>                         # exclude a directory from scanning
desloppify config show                            # show all config including excludes
desloppify scan --path . --reset-subjective       # reset subjective baseline to 0

4. 在上游修复工具问题

如果 desloppify 本身似乎存在错误或前后不一致——例如 bug、检测错误、崩溃或输出令人困惑——请修复问题并提交 PR。如果无法确信能修好，请改为提交 issue。

修复并提交 PR（首选）

将工具仓库克隆到临时目录，在那里进行修复，并在推送前验证修复对你正在扫描的项目有效。

git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify-fix
cd /tmp/desloppify-fix
git checkout -b fix/<short-description>

完成更改后，运行测试套件，并针对原项目验证修复：

python -m pytest desloppify/tests/ -q
python -m desloppify scan --path <project-root>   # the project you were scanning

确认效果良好后，推送更改并提交 PR：

git add <files> && git commit -m "fix: <what and why>"
git push -u origin fix/<short-description>
gh pr create --title "fix: <short description>" --body "$(cat <<'EOF'
## Problem
<what went wrong — include the command and output>

## Fix
<what you changed and why>
EOF
)"

完成后清理：rm -rf /tmp/desloppify-fix

提交 issue（备用方案）

如果修复方案不明确，或更改需要讨论，请前往 https://github.com/peteromallet/desloppify/issues 提交 issue，并提供最简复现信息：命令、路径、预期输出和实际输出。

前提条件

command -v desloppify >/dev/null 2>&1 && echo "desloppify: installed" || echo "NOT INSTALLED — run: uvx --from git+https://github.com/peteromallet/desloppify.git desloppify"

如果无法使用 uvx：pip install desloppify[full] && desloppify setup