Back to Details

detool

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Remove incidental tool coupling from artifacts that claim to outlive the stack that wrote them.
从那些声称能比生成它们的技术栈更持久的工件中，移除偶然的工具耦合。

Goal

目标

A durable artifact should stay true and actionable when the agent, harness, operating system, vendor, model, or toolchain changes. 
detool
finds stack-specific nouns in portable content and rewrites them to the underlying mechanism without deleting the action they enabled.
The point is portability, not vagueness. A reader should still know what to inspect, run, measure, compare, or verify after the rewrite.
当Agent、工具框架、操作系统、供应商、模型或工具链发生变化时，持久化工件仍应保持准确且可执行。
detool
会在可移植内容中查找特定技术栈的专有名词，并将其重写为对应的底层机制，同时保留原有的可执行操作。
核心目标是可移植性，而非模糊化。重写后，读者仍应清楚知道需要检查、运行、测量、比较或验证的内容。

Workflow

工作流程

  1. Read the target artifact end to end.
  2. Role before edit: classify the whole artifact, or each section if mixed, as durable/portable content, provenance/operational record, or a claim about a named tool.
  3. Sweep durable content for incidental coupling: harness paths, vendor CLIs and flags, model or product brands used as mechanisms, tool-specific environment variables, quotas, UI steps, cache homes, session files, and version-pinned behavior stated as timeless truth.
  4. Mechanism not euphemism: replace each durable-content hit with the neutral mechanism that preserves the action. If neutral wording would lose the action, keep the concrete detail as an example of the mechanism instead of pretending it generalizes.
  5. Keep provenance and operational content concrete. Build records, capsules, benchmark logs, install guides, runbooks, tool-targeted how-tos, command transcripts, and exact reproduction steps are supposed to name the stack that produced them.
  6. Keep comparative and tool-subject claims concrete. If the sentence is about a named tool, vendor, model, bug, prior-art source, or measured limit, the name is the subject, not incidental coupling.
  7. Re-read as a reader on a different stack: the artifact should still be true, portable, and executable where it promised action.
  8. Report what was neutralized, what was deliberately kept, and the role judgment behind each keep.
  1. 完整读取目标工件。
  2. 编辑前先定义角色：将整个工件（若内容混合则按章节）分类为持久化/可移植内容、来源/操作记录，或是针对特定工具的声明。
  3. 扫描持久化内容中的偶然耦合项：工具框架路径、供应商CLI及参数、被当作机制使用的模型或产品品牌、工具特定的环境变量、配额、UI操作步骤、缓存目录、会话文件，以及被描述为永恒真理的版本固定行为。
  4. 使用机制而非委婉表述：将持久化内容中的每个耦合项替换为能保留操作的中性机制。若中性表述会丢失操作细节，则保留具体信息作为该机制的示例，而非强行泛化。
  5. 保留来源和操作内容的具体性。构建记录、封装包、基准测试日志、安装指南、运行手册、针对特定工具的操作教程、命令执行记录以及精确的复现步骤，应明确记录生成它们的技术栈信息。
  6. 保留对比性和针对工具主体的声明的具体性。如果语句是关于特定工具、供应商、模型、Bug、现有技术来源或已测量的限制，那么这些名称是语句的主体，而非偶然耦合项。
  7. 以使用不同技术栈的读者视角重新阅读：工件仍应保持准确、可移植，且在承诺可执行的场景下能够正常运行。
  8. 报告哪些内容被中性化处理、哪些内容被刻意保留，以及每项保留决策背后的角色判断依据。

Rules

规则

  • Role before edit. Never scrub before deciding whether the text is portable content, provenance, operational instruction, or a tool-subject claim.
  • Mechanism, not euphemism. "Use the session execution log and sum usage records" is a mechanism; "check the logs" is a euphemism that loses the work.
  • Preserve actionable detail. Abstract only the coupling, not the procedure, evidence, comparison, or constraint.
  • Keep provenance and operational records exact. Concrete paths, commands, flags, versions, products, and UI steps stay when they record what happened or explain how to drive a specific tool.
  • Keep comparative/tool-subject names. A bug report about a CLI, a benchmark against a model, a prior-art citation, or a vendor-specific limit keeps the named subject.
  • A pass that finds no incidental coupling changes nothing.
  • Mutate with edit-safety: assert each target exists and report a MISS instead of silently no-oping; edit unicode-safe; replace per occurrence, never by blanket sweep; script large structural moves.
  • 编辑前先定义角色。在确定文本属于可移植内容、来源信息、操作说明还是针对工具主体的声明之前，切勿随意清理内容。
  • 使用机制而非委婉表述。“使用会话执行日志并汇总使用记录”是一种机制；“查看日志”则是会丢失具体操作的委婉表述。
  • 保留可执行细节。仅抽象耦合项，而非流程、证据、对比或约束条件。
  • 保留来源和操作记录的精确性。当内容记录已发生的操作或解释如何使用特定工具时，具体路径、命令、参数、版本、产品和UI步骤应予以保留。
  • 保留对比性/工具主体的名称。关于某个CLI的Bug报告、针对某个模型的基准测试、现有技术引用或供应商特定限制的内容，应保留对应的主体名称。
  • 若未发现任何偶然耦合项，则不做任何修改。
  • 以安全编辑的方式修改：确认每个目标项存在，若不存在则报告MISS而非静默无操作；支持Unicode安全编辑；按出现次数逐一替换，而非批量全局替换；通过脚本处理大型结构调整。

Verification

验证

Before finishing, confirm:
  1. Every changed hit was in durable or portable content.
  2. Every rewrite preserved the actionable mechanism.
  3. Every kept tool noun is provenance, operational instruction, or the subject of its claim.
  4. The report names neutralized couplings, deliberate keeps, and any judgment calls.
完成处理前，确认以下事项：
  1. 所有修改的内容均属于持久化或可移植内容。
  2. 每一处重写都保留了可执行的机制。
  3. 所有保留的工具名词均属于来源信息、操作说明或声明的主体。
  4. 报告中列出了被中性化的耦合项、刻意保留的内容以及所有判断决策。