Skip to content

PITFALLS.md

Latest commit

 

History

History
134 lines (93 loc) · 4.33 KB

PITFALLS.md

File metadata and controls

134 lines (93 loc) · 4.33 KB
Raw

t3d plugin — pitfalls

跨项目通用的"做 X 时容易踩 Y"经验。 只放 generalizable 的——单项目特定经验请放该项目的 .claude/PITFALLS.md。

新增条目来源标注 session id + 日期；如果有多次复现，列出所有。

由 t3d-sinkin skill 的 Section 4 协助积累；条目须经用户确认后才写入。

Shell / scripting

pkill -f <pattern> 会杀掉自己的 shell

pkill -f 匹配整个命令行 argv。当父 shell 的命令行里恰好包含 <pattern> （例如这条 pkill 命令本身），它会把父 shell 也连带杀掉，返回 exit 144。

症状：跑 pkill -f uvicorn 后整个 Bash 输出 Exit 144，但 server 还在。

修复：用 pgrep -x <name> 精确匹配名字 + 显式 kill <pid>：

for pid in $(pgrep -x uvicorn); do kill "$pid"; done
  • Source: session 1763c182…, 2026-06-18

LLM / token semantics

Anthropic input_tokens 字段不包含 cache_*

Anthropic Messages API 的 usage.input_tokens 只算"未命中 cache 的新输入"， 不包含 cache_read_input_tokens 和 cache_creation_input_tokens。

踩坑表现：仪表盘把 input_tokens 显示为 "Input"，用户看到几十 K 但 cache 几十 M，怀疑数字坏了——其实是字段语义陷阱。

修复：

  • UI 标签用 "Total Input" = input + cache_read + cache_write，给 "uncached input" 单独显示子项

  • Cache hit rate 公式分母应是 input + cache_read + cache_write，不是 input + cache_read（漏掉 cache_write 会算出 ~100%）

  • Source: session 1763c182…, 2026-06-17（连续 3 轮"数字不对"反馈才定位）

Claude Code plugin development

hooks.json 顶层结构需要 "hooks" wrapper

.claude/settings.json 的 hook 块和 plugin 的 hooks/hooks.json 长得像， 但后者外层必须再包一层 {"hooks": {...}}。否则 claude plugin validate 报：

hooks: Invalid input: expected record, received undefined

修复：plugin 用：

{ "hooks": { "PreToolUse": [...], "PostToolUse": [...] } }

而 settings.json 是平铺的 { "PreToolUse": [...], ... }（少一层）。

  • Source: session 1763c182…, 2026-06-18

claude plugin update 在 local-marketplace 模式下可能失败

如果 marketplace source 是本地路径，发布新版本后 claude plugin update <name> 有时报 Plugin not found——本质是缓存没更新。

修复：

claude plugin marketplace update <marketplace-name>
claude plugin uninstall <plugin>
claude plugin install <plugin>
  • Source: session 1763c182…, 2026-06-18

Plugin 源 / 路径迁移后，活着的 Claude session 还报老路径错

切换 plugin source（如 local dir → github.com/owner/repo）或者把 plugin 文件夹搬家后，当前正在运行的 Claude session 会继续报旧路径：

Plugin directory does not exist: /old/path/to/plugin
(plugin@old-marketplace — run /plugin to reinstall)

原因：plugin 注册表是在 session 启动时 加载进内存的，运行中不会重读 disk。 即使你 claude plugin marketplace remove / add 把 disk 的 settings.json 改干净了， 当前 session 仍在用快照状态。

永久修复：退出 Claude session 再重开（新 session 读取新 settings）。

当前 session 救急（如果你不想中断）：用 symlink 把旧路径指到新路径：

ln -snf /new/path/to/plugin /old/path/to/plugin
ln -snf ~/.claude/plugins/cache/<new-marketplace>/<plugin>/<ver> \
        ~/.claude/plugins/cache/<old-marketplace>/<plugin>/<ver>

重启后 symlink 不再被引用，可删可留。

  • Source: session 1763c182…, 2026-06-21（在把 t3d 从 tddd-marketplace 迁到 coolsocket/t3d 时栽了两次）

DDD / TDD 实践

Hooks 抓不到"已有的"违规

PreToolUse hook 只在新 Edit/Write 时拦截。已经存在于代码里的违规 （跨 context import、Domain 层 import 外部包等）需要靠 sinkin Section 2 扫一遍。

  • Source: t3d-sinkin Section 2 设计反思

模板（新增条目用）

### <一行标题：行为 / 现象>

<2-4 行：踩了什么 / 为什么会踩 / 怎么避免>

**修复**：
\`\`\`
<最小可复现 + 修复 snippet>
\`\`\`

- _Source: session <8 char id>…, YYYY-MM-DD（如多次复现，列全）_