env-tool-log

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Env Tool Log

复用工具规则和本机环境信息，记录可复用的失败原因与已验证修复。 shell 与内置工具都适用；会话首次使用时查看相关经验，之后复用已读规则。

Reuse tool rules and local environment information while recording reusable failure causes and verified fixes. This applies to both shell and built-in tools. On a tool's first use in a session, review the relevant experience; reuse rules already read thereafter.

使用流程

Usage Workflow

首次检查
- 会话首次使用某工具前，读取共享
```
lessons.md
```
  的对应工具章节；无相关记录则正常使用。范围包括 shell、文件读取、搜索、补丁编辑、浏览器与 MCP。
- shell 命令另查相关命令规则；内置工具按自身 schema 和已确认经验调用，不强行套用 shell 规则。
- 读取索引与维护日志不递归触发首次检查；切换环境或出现意外错误时重新核对相关经验。
- 按命令或错误关键词执行
```
fail_log.py query "关键词" --all --limit 5
```
  ；同时看 OPEN 的未决问题与 FIXED 的解决方法，不把无关命中当作当前原因。
- 仅查看相关工具的环境快照；缺失、过期或环境变化时按快照规则重新探测。
执行与复用
- 同一会话复用已确认的路径、版本和规则，环境未变化时不重复读取或探测。
- 数据目录沿用已配置的
```
ENV_TOOL_LOG_DIR
```
  ，未配置时使用默认目录。权限受限需临时覆盖时，说明原因、原目录和替代目录；后续调用保持一致。
- 读取日志或快照失败不阻断无关工作，不静默换目录重新积累记录。
失败与闭环
- 可复用的工具、参数或环境失败及时记录稳定签名、已知原因和修复方案。同类错误复用原签名，更新次数、最近时间和当前状态，不因复发新增记录。签名使用工具与稳定错误特征，不包含动态路径、时间戳或运单号；不同原因不按模糊文本合并。原因未确认时保留为空或标明待确认，不把猜测写成事实。
- 修复重试通过后，对同一签名执行
```
mark-fixed
```
  ，写入已验证的方法。仅有候选方案或局部验证时保留 OPEN，并说明验证范围。关闭不删除预防规则；复发时保留上次已验证方法并标明待复核，确认后原位修正。
- ```
add
```
  与
```
mark-fixed
```
  自动更新按工具分类的经验索引，手工正文保留；原因、修复方法或适用范围变化时更新原条目，不逐轮追加同类教训。
- 预期的 TDD 红灯、正常搜索无匹配和业务断言失败留在任务验证中；工具无法正常执行测试时，才记录对应工具故障。
- 日志脚本自身失败时直接修正调用，不递归调用自身登记故障；仍不可用时在任务中说明缺口，不让记录流程阻断已授权工作。

Initial Check
- Before using a tool for the first time in a session, read the corresponding tool section of the shared
```
lessons.md
```
  ; if there are no relevant records, use the tool normally. The scope includes shell, file reading, search, patch editing, browser, and MCP.
- For shell commands, also consult the relevant command rules; invoke built-in tools according to their own schemas and confirmed experience rather than forcing shell rules onto them.
- Reading the index and maintaining the log do not recursively trigger the initial check. When switching environments or encountering unexpected errors, recheck the relevant experience.
- Run
```
fail_log.py query "keyword" --all --limit 5
```
  using command or error keywords; review both OPEN unresolved issues and FIXED solutions, and do not treat unrelated matches as the current cause.
- View only the environment snapshot for the relevant tool. If it is missing, stale, or the environment has changed, probe it again according to the snapshot rules.
Execution and Reuse
- Reuse confirmed paths, versions, and rules within the same session. If the environment has not changed, do not repeat reads or probes.
- Continue using the configured
```
ENV_TOOL_LOG_DIR
```
  data directory, or the default directory when it is not configured. If permissions require a temporary override, explain the reason, the original directory, and the alternative directory; keep subsequent calls consistent.
- A failure to read logs or snapshots must not block unrelated work. Do not silently switch directories and accumulate records elsewhere.
Failures and Closure
- Promptly record stable signatures, known causes, and solutions for reusable tool, parameter, or environment failures.
- Reuse the original signature for the same error class. Update the occurrence count, most recent time, and current status rather than adding a new record for each recurrence.
- A signature should use the tool and stable error characteristics, excluding dynamic paths, timestamps, and waybill or order numbers. Do not merge different causes based on vague text similarity.
- Leave the cause empty or mark it as pending confirmation when it is unknown. Do not present a guess as fact.
- After a fix passes a retry, run
```
mark-fixed
```
  for the same signature and record the verified method.
- Keep the issue OPEN when there is only a candidate solution or partial validation, and describe the validation scope.
- Closing an issue does not delete its preventive rules. When it recurs, retain the previously verified method, mark it as pending review, and correct it in place after confirmation.
- ```
add
```
  and
```
mark-fixed
```
  automatically update the tool-categorized lessons index while preserving manually written content. When the cause, solution, or applicable scope changes, update the original entry rather than appending a new lesson for each round.
- Keep expected TDD red lights, normal searches with no matches, and business assertion failures in task validation. Record a corresponding tool failure only when a tool cannot execute tests normally.
- If the logging script itself fails, correct the invocation directly rather than recursively invoking it to register the failure. If it remains unavailable, document the gap in the task and do not let the logging process block authorized work.

数据与脚本

Data and Scripts

默认数据目录为

~/.my-skills/env-tool-log/

，由同一用户下的各 harness 共用，显式配置的

ENV_TOOL_LOG_DIR

优先。客户端记录来源由

from

字段区分；手工调用

add

时按当前客户端传入

--from codex/cc/pi

，不把默认来源当作自动识别。

检测到旧版

.codex

数据时，仅向 stderr 提示旧目录与当前目录，不自动搬移、合并或读取。迁移前可通过环境变量明确沿用旧目录；确认迁移后，所有 harness 应统一使用新目录。旧目录处理见迁移说明。本机快照、日志和教训不入库、不随技能分发；不得写入凭据或敏感地址。

经验索引：
```
lessons.md
```
按工具列出稳定签名、触发条件与当前做法；关联日志中的同一签名。完整索引不按最近几条截断；hooks 注入的摘要不能代替相关章节。
失败日志：
```
scripts/fail_log.py
```
提供记录、查询、关闭、归档和教训生成；参数、分类与客户端 hooks 见数据与使用。
环境快照：
```
scripts/snapshot_env.py
```
按需探测工具路径和版本；刷新时机与字段见环境快照。
客户端 hooks：Claude Code 安装脚本按需使用，不自动安装或修改客户端配置。自动捕获的记录仍需核对是否为预期失败，并在实际修复后闭环。

The default data directory is

~/.my-skills/env-tool-log/

, shared by all harnesses running under the same user. An explicitly configured

ENV_TOOL_LOG_DIR

takes precedence. The

from

field distinguishes client record sources; when manually running

add

, pass the current client with

--from codex/cc/pi

instead of treating the default source as automatically detected.

When legacy

.codex

data is detected, print the old and current directories only to stderr. Do not automatically move, merge, or read the data. Before migration, an environment variable can explicitly retain use of the old directory. After migration is confirmed, all harnesses should consistently use the new directory. See the migration instructions for handling the old directory.

Local snapshots, logs, and lessons must not be committed to the repository or distributed with the skill, and must not contain credentials or sensitive addresses.

Lessons Index:
```
lessons.md
```
lists stable signatures, trigger conditions, and current practices by tool, linked to records with the same signature in the logs. Do not truncate the complete index to only the most recent entries, and do not let summaries injected by hooks replace the relevant sections.
Failure Log:
```
scripts/fail_log.py
```
supports recording, querying, closing, archiving, and generating lessons. See Data and Usage for parameters, categories, and client hooks.
Environment Snapshots:
```
scripts/snapshot_env.py
```
probes tool paths and versions on demand. See Environment Snapshots for refresh timing and fields.
Client Hooks: The Claude Code installation script uses them as needed and does not automatically install them or modify client configuration. Automatically captured records still require confirmation that the failure was expected and must be closed after the actual fix.

跨 harness 接入

Cross-Harness Integration

在各 harness 支持的全局指令入口放入以下约定，具体文件名由客户端决定。 skill 文件与共享数据本身不保证新会话自动加载；hooks 仅作为可选的读取入口。

使用 shell 或内置工具前，会话首次使用该工具时读取共享 env-tool-log 经验索引的相关章节；已读取且环境未变化时复用。意外工具错误使用稳定签名登记，同类错误原位更新；修复验证后关闭记录并保留预防规则。

Place the following convention in the global instruction entry supported by each harness; the exact filename is determined by the client. The skill file and shared data do not by themselves guarantee automatic loading in new sessions; hooks serve only as optional read entry points.

Before using the shell or a built-in tool, read the relevant section of the shared env-tool-log lessons index on the tool's first use in the session. Reuse it after it has been read if the environment has not changed. Register unexpected tool errors using a stable signature, update the same error class in place, close records after fixes are verified, and retain preventive rules.