调查揭示：近半数LG智能电视应用暗藏代理SDK，将客厅变为流量跳板

分类：前沿阅读() 评论(0)

一项最新调查揭露了智能电视生态系统中的严重隐私隐患。Spur Intelligence Labs 对 LG 和三星电视平台的 6,038 个应用进行了深度扫描，结果令人震惊：共发现 2,058 个应用内置了住宅代理 SDK，其中 LG webOS 平台的应用受影响比例高达近 50%。这些看似无害的屏幕保护程序、时钟或贪吃蛇游戏，实际上将用户的家庭宽带连接出售给了第三方网络，用于转发匿名互联网流量。研究人员指出，由于缺乏电池续航焦虑和复杂的后台审计机制，智能电视已成为充当“代理节点”的理想设备。为了在不打扰用户展示广告的情况下获利，开发者集成了 Bright Data、Honeygain（已被 Oxylabs 收购）和 Massive 等厂商的 SDK。用户在安装时只需点击一次模糊的同意按钮，其设备便会长期充当流量中继站。更令人担忧的是安全风险。这些代理应用运行在家庭局域网内，部分 SDK 代码解析显示其具备连接任意主机和端口的能力。虽然部分厂商声称过滤了内网 IP，但技术分析表明这种隔离并不稳固。恶意攻击者可能利用这一通道，反向穿透用户的家庭网络，进而攻击路由器、NAS 或摄像头等设备。相比之下，亚马逊和 Roku 已明确禁止此类软件，而 LG 和三星尚未制定明确的限制政策，留下了巨大的监管空白。

事件分析

从技术架构来看，此次事件暴露了 IoT 设备在安全边界定义上的脆弱性。智能电视作为家庭网络的核心节点，长期处于在线状态且缺乏用户侧的流量监控，使其成为劣质流量变现的最佳载体。此类应用通过捆绑 SDK，将原本用于内容消费的“最后一公里”带宽转化为“住宅代理”资源，这是一种典型的“僵尸化”利用。关键风险在于局域网（LAN）穿透。尽管 Bright Data 等厂商声称具备内网 IP 黑名单（如 192.168.x.x 等），但代码分析显示 Massive 和 Honeygain 的部分版本并未强制执行此类隔离。一旦代理服务商的流量过滤失效或遭到恶意客户利用，电视便从外网流量中继节点变为内网渗透的跳板，直接威胁智能家居环境的安全。在产业监管层面，亚马逊和 Roku 的严厉态度证明了该类软件具备恶意属性，而 LG 和三星的监管滞后导致了灰色地带的野蛮生长。未来，随着网络安全法规的完善，平台方必须承担起更严格的代码审计责任，防止此类将用户设备作为“服务器”使用的商业模式泛滥。

💡 核心观点：智能电视沦为隐蔽的流量“矿机”，平台监管缺位让家庭网络内网面临穿透风险。

原文链接：Hacker News

C code80.ai · AI 编码 API 聚合 Claude / GPT 多模型统一接入,稳定不限速,按量计费,几行配置接入 Claude Code。了解一下 ›

抢沙发

评论前必须登录！

立即登录注册

易安作者

长期关注 AI Agent、软件工程、自动化工作流与个人生产力系统。喜欢把复杂技术拆成普通人也能上手的实践教程,也记录自己在工具链、编程、内容创作和知识管理上的真实折腾。

分享 AI 工具、Agent 工作流与提示词工程的实战经验
记录从想法到产品、从代码到上线的完整实践过程
关注普通人如何用 AI 放大能力,而不是被工具牵着走

阅读作者的全部文章 ›

文章目录

前沿哨所

Agent Skill 跨工具复用: 目录结构、版本管理与团队共享
TL;DR: 多工具时代, skill 不该各管各的

如果你同时在用 Claude Code、Codex、openclaw、hermes 这类 agent 工具, 大概率已经踩进同一个坑: 同一套”让 agent 怎么提交代码””怎么写 commit message””怎么发布到 WordPress”的知识, 被你在四个工具里各写了一遍。改一处, 另外三处忘了同步; 半年后想不起来哪个版本是最新的; 换台机器又得手动拷一遍。

这不是工具的问题, 是你把 skill 当成了”每个工具的私有配置”, 而不是”独立于工具存在的工程资产”。

一句话结论: agent skill 本质是纯文本 + 脚本目录, 天然适合用 git 管理、用软链或子模块在多工具间共享一份源、用语义化版本号追踪演进。 把这三件事做对, 你维护的就从”四份会漂移的副本”变成”一份可 diff、可回滚、可团队协作的真相源”。

下面按这个顺序拆: 先讲清楚 skill 到底是什么、为什么能跨工具复用; 再给标准化目录结构; 然后是一份源多工具复用的几种接法; 接着是 git 版本管理与变更记录; 最后是跨工具迁移的差异点和团队协作流程。

读之前如果你对 agent 工具本身还没选定, 可以先看 Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选和 Codex vs Cursor 额度对比: 价格、限制与选型建议, 把工具盘子定下来再谈复用更有意义。

一、Agent Skill 的本质: 为什么它能跨工具

1.1 Skill 不是插件, 是”可被加载的专业知识包”

很多人第一次接触 skill, 会下意识把它类比成浏览器插件或者 IDE 扩展——一个绑死在某个宿主里、调一套私有 API 的二进制。这个类比会把你带偏。

以 Claude Code 的 Skill 范式为例, 一个 skill 的核心就是一个文件夹, 里面放一份 SKILL.md。这份 markdown 顶部有 YAML frontmatter, 只需要两个字段就能跑起来:
```
---
name: commit
description: 用规范化的 conventional commit 信息创建提交。当用户要求提交代码、写 commit message、整理变更时触发。
---

# Commit Skill

## 何时使用
当工作区有未提交改动, 且用户要求"提交""commit""存一下"时。

## 步骤
1. 运行 `git status` 和 `git diff` 看清改了什么
2. 按 conventional commit 规范归类: feat / fix / docs / chore ...
3. 生成简洁的标题 + 必要的正文
4. 提交前用 `git diff --staged` 复核
```
注意它的形态: 没有一行宿主专属代码, 全是自然语言 + shell 命令。 这正是它能跨工具的根本原因——它描述的是”做这件事的方法”, 而方法本身不依赖某个特定 agent 的运行时。

1.2 渐进式加载: description 是检索入口, 不是装饰

Claude Code 的 skill 有一个关键机制叫渐进式披露 (progressive disclosure): 系统启动时, 并不会把每个 skill 的全文塞进上下文, 而是只加载 name 和 description 两个字段。模型根据当前任务语义匹配到某个 description, 才会去读那份 SKILL.md 的正文; 正文里再引用 references/ 或 scripts/ 时, 又是按需加载。

这套机制对”复用”有两个直接含义:
- description 写得好不好, 决定了 skill 能不能被正确触发。 它不是文档摘要, 是检索关键词。要把”什么时候用我”写清楚, 把用户可能说的触发词都覆盖到。
- 正文和资源按需加载, 意味着一个 skill 可以很厚而不污染上下文。 你可以把长 checklist、模板、参考表都塞进 references/, 平时不占 token, 用到才拉。
这种”薄入口 + 厚实现”的思路, 和 agent 工程里反复出现的一个判断是同构的: 复杂度应该沉淀进可复用的资产, 而不是困在一次性对话里。关于 harness 和 skill 谁轻谁重的取舍, Agent Harness 不是要安装的软件包和 Loop Engineering 是 Harness 的局部命名讲得比较透, 值得对照着读。

1.3 为什么”纯文本 + 脚本目录”是可迁移的最大公约数

再看 Codex、openclaw、hermes。它们各自的扩展机制在字段名、加载方式上肯定有差异——Codex 有自己的指令文件与自定义提示约定; openclaw、hermes 这类工具有各自的组织方式。但把它们抽象一层就会发现, 几乎所有 agent 工具的”能力扩展”都落在同一个最大公约数上:

一段告诉 agent 怎么做某件事的自然语言提示, 加上一组它可以调用的脚本/命令。

以 hermes 这类偏调度型的 agent 为例, 它的 skill 通常也是走 prompt 描述 + 脚本目录的组织方式; openclaw 这类工具同理。字段叫什么、放在哪个目录、用什么格式声明触发条件, 这些是表层差异; 而”提示 + 脚本”这个内核是共享的。

这就是跨工具复用在工程上成立的前提: 你维护的真相源应该是这个内核, 而把各工具的表层差异留给一层薄薄的适配。下面所有方法论都建立在这个判断上。

二、标准化目录结构: 一份 skill 长什么样

复用的第一步是约定结构。如果每个 skill 的内部布局都不一样, 后面的软链、迁移、版本管理都无从下手。下面是一套被验证可用的标准布局——它向 Claude Code 的 skill 约定看齐, 同时刻意保持”任何工具都能消费”的中立性:
```
skills/
├── commit/
│   ├── SKILL.md            # 入口: frontmatter(name/description) + 正文
│   ├── references/         # 按需加载的厚资料: 规范表、模板、checklist
│   │   └── conventional-commit-spec.md
│   └── scripts/            # 可执行脚本, 被正文引用
│       └── gen-message.sh
├── blog-publish/
│   ├── SKILL.md
│   ├── references/
│   │   ├── seo-title-rules.md
│   │   └── frontmatter-template.md
│   ├── scripts/
│   │   ├── build-images.py
│   │   └── publish.sh
│   └── assets/             # 静态资源: 模板图、样式片段
│       └── poster-base.svg
└── code-review/
    ├── SKILL.md
    └── references/
        └── review-checklist.md
```
几条约定值得明确:
1. 一个 skill 一个目录, 目录名即 skill 名, 和 frontmatter 里的 name 保持一致。这样工具扫描目录就能建立索引。
2. SKILL.md 是唯一入口, 正文尽量短, 把”何时用 / 怎么用 / 边界”讲清楚即可。详细规则下沉到 references/。
3. scripts/ 放确定性逻辑。 agent 擅长决策, 不擅长精确执行重复步骤。能用脚本固化的(改文件名、调 API、跑校验), 就别让模型每次现写。这点和”把 agent 当决策者、把确定性留给代码”的工程直觉一致, 构建 Agent 和写软件, 是两种工程对这个边界有专门的讨论。
4. references/ 是按需加载区。 越厚越好, 因为平时不占上下文。SEO 清单、品牌规范、API 字段表, 都该放这里。
5. assets/ 放二进制或静态模板, 和会频繁 diff 的文本分开, 避免污染 git 历史。
这套结构的好处是关注点分离: 决策(SKILL.md)、知识(references)、执行(scripts)、资源(assets)各居其位。换工具时, 你迁移的是整个目录, 而不是从一坨混在一起的配置里抠。

三、一份 skill 源, 多工具复用

结构定了, 接下来是核心问题: 同一个 skill, 怎么让 Claude Code、Codex、openclaw、hermes 都能用上, 而只维护一份源?

核心原则只有一句: 真相源 (source of truth) 唯一, 各工具的目录是它的投影。 不要在每个工具的配置目录里各放一份会各自演化的副本。下面是三种接法, 从轻到重。

3.1 方案 A: 软链接 (symlink)——最轻, 适合单人多工具

把所有 skill 集中放在一个独立仓库, 比如 ~/agent-skills/。然后在每个工具期望的目录位置, 用软链指过去:
```
# 真相源
~/agent-skills/skills/commit/
~/agent-skills/skills/blog-publish/

# 各工具消费点, 全部软链到同一份源
ln -s ~/agent-skills/skills  ~/.claude/skills
ln -s ~/agent-skills/skills  ~/.codex/skills
ln -s ~/agent-skills/skills  ~/.config/openclaw/skills
```
改一处, 处处生效, 因为它们物理上就是同一份文件。优点是零同步成本、改完立即可见; 缺点是软链对某些工具的扫描器不一定友好(有的工具不跟随符号链接), 跨机器要重新建链, Windows 下软链权限也更麻烦。

适用场景: 单人、同一台开发机、多个工具。这是收益最高、成本最低的起点。本站把自营分站统一管理时也用过类似”一份源 + 多处指向”的思路。

3.2 方案 B: git submodule——适合多仓库、需要钉版本

如果 skill 要被多个项目仓库引用, 而且你希望每个项目能钉在某个 skill 版本上(不被上游改动随时影响), 用 git submodule:
```
# 在项目仓库里把 skill 仓库挂为子模块
cd my-project
git submodule add [email protected]:me/agent-skills.git .agent/skills

# 各工具再软链到子模块目录, 或工具直接读这个路径
ln -s ../.agent/skills .claude/skills

# 升级时显式拉取并锁定到新 commit
cd .agent/skills && git pull origin main && cd -
git add .agent/skills && git commit -m "chore: bump skills to latest"
```
submodule 的关键价值是版本锁定: 子模块在父仓库里记录的是一个确定的 commit hash。这意味着 A 项目可以用 skill 的 v1.2, B 项目还停在 v1.0, 互不干扰, 升级是一次显式的、可在 PR 里 review 的动作。代价是 submodule 的心智负担确实存在(忘记 --recurse-submodules、游离 HEAD 等老问题), 团队得统一约定。

3.3 方案 C: 同步脚本——工具不认软链时的兜底

有些工具就是不跟随软链, 或者要求 skill 必须是真实文件。这时用一个幂等的同步脚本, 把真相源拷贝到各工具目录:
```
#!/usr/bin/env bash
# sync-skills.sh —— 把真相源同步到各工具消费目录
set -euo pipefail
SRC="$HOME/agent-skills/skills"

for dst in 
  "$HOME/.claude/skills" 
  "$HOME/.codex/skills" 
  "$HOME/.config/openclaw/skills"
do
  mkdir -p "$dst"
  rsync -a --delete "$SRC/" "$dst/"   # --delete 保证目标和源一致, 不留孤儿
  echo "synced -> $dst"
done
```
rsync --delete 保证目标目录和源完全一致, 不会留下已删 skill 的残骸。把这个脚本挂到 git 的 post-merge hook 或一条手动命令上, 每次更新源后跑一次即可。它比软链笨, 但最通用——任何工具都吃真实文件。

三种方案不互斥: 常用工具走软链, 个别挑食的工具用同步脚本补齐, 跨项目引用上 submodule。判断标准就一条——永远只有一份会被编辑的源, 其余都是它的只读投影。 这和”不要重复造轮子、把基础设施收敛成一份”的工程主张是一回事, 告别重复造轮子: 为什么 AI Agent 创业不应自研基础设施把这个取舍讲到了创业层面。

四、版本管理: 用 git 把 skill 当代码养

skill 是纯文本, 这意味着它能享受软件工程几十年积累的全部版本管理红利。别浪费这个优势。

4.1 skill 仓库本身就该是个 git 仓库

最基本的一步: ~/agent-skills/ 初始化成 git 仓库, 推到远端。这样你立刻获得三件事——历史可追溯(谁在什么时候改了哪条规则)、可回滚(某次改动让 skill 触发变差, 一个 git revert 回去)、可 diff(改动一目了然, 因为全是文本)。

这正是”纯文本 + git”组合的核心价值。对比一下: 如果你的 skill 是埋在某个工具 GUI 里的配置项, 上面这三件事一件都做不到。

4.2 语义化版本: 给 skill 打 tag

当 skill 开始被多个项目、多个人引用时, 引入语义化版本 (SemVer) 就有意义了。约定:
- MAJOR (2.0.0): 破坏性变更。比如改了 skill 的触发语义、删了某个被脚本依赖的字段、调整了输出格式, 老的调用方需要适配。
- MINOR (1.3.0): 向后兼容地加能力。新增一个 reference、扩展触发词、加一个可选脚本。
- PATCH (1.2.1): 修字。typo、措辞优化、修一个脚本 bug, 不改行为契约。
打 tag 的操作:
```
git tag -a v1.3.0 -m "blog-publish: 新增 SEO 标题硬规则 reference"
git push origin v1.3.0
```
submodule 引用时, 就可以钉到 v1.3.0 这个 tag 而非游动的 main, 升级变成”从 v1.3.0 到 v1.4.0″这种可读、可评审的动作。

4.3 CHANGELOG: 让”为什么这么改”留痕

git 历史记录了”改了什么”, 但”为什么改、改了之后触发效果有没有变好”需要单独留痕。在 skill 仓库根放一份 CHANGELOG.md:
```
# Changelog

## [1.3.0] - 2026-06-26
### Added
- blog-publish: 接入 SEO 标题硬规则 reference, 标题生成前强制过清单
### Changed
- commit: description 补充"存一下""归档"等触发词, 提升命中率

## [1.2.1] - 2026-06-20
### Fixed
- code-review: 修正 checklist 里一处误导性表述
```
这件事在 agent 语境下尤其重要。skill 的好坏不像普通代码那样有确定的单元测试, 它的”对不对”体现在触发是否准、产出是否稳。 你改一版 description, 触发率可能上去也可能下去, 这本质是个需要观测的反馈过程。把每次改动和它的意图记下来, 才能在效果回退时定位是哪一次改坏的。

关于”agent 的效果如何度量”这件事本身就是门学问, LLM 评测的下一步是一张二维矩阵和 Prompt Learning 的两个反馈圈提供了两套可以直接借用的视角: 前者讲怎么把评测组织成可读的矩阵, 后者讲提示迭代的反馈闭环, 都能套到”skill 改完怎么验证”上。

五、跨工具迁移: 差异点在哪里, 怎么处理

把内核标准化之后, 真正的工作量在处理各工具的表层差异。这里列出迁移时最常踩的几类差异和应对。

5.1 frontmatter / 元数据格式差异

不同工具对”这个 skill 叫什么、什么时候触发”的声明方式不一定相同。Claude Code 用 SKILL.md 顶部的 YAML frontmatter(name + description); 其他工具可能用别的文件名、别的字段、甚至别的格式。

应对: 真相源用一套最表达力强的格式(推荐 Claude Code 的 frontmatter 约定), 迁移时用一个小转换脚本生成各工具要的形态。 不要反过来——不要为了迁就某个工具的弱格式, 把真相源也阉割了。

5.2 触发机制差异: 自动检索 vs 显式调用

这是最容易出问题的一类差异。有的工具像 Claude Code 那样靠 description 语义自动匹配触发 skill; 有的工具需要用户显式调用(比如打一个斜杠命令)。

这两种机制对 description 的要求完全不同:
– 自动匹配的工具, description 要写得像”检索关键词”, 把所有可能的触发说法都覆盖。
– 显式调用的工具, description 更像”帮助文档”, 用户已经知道要调它了。

应对: 把 description 写成自动匹配友好的版本(信息量大的那种总是兼容显式调用), 在迁移到显式调用工具时不需要改。反过来则会丢信息。

5.3 脚本运行环境差异

scripts/ 里的脚本依赖的解释器、环境变量、工作目录, 在不同工具下不一定一致。一个在 Claude Code 下 cwd 在项目根的脚本, 换个工具可能 cwd 在别处。

应对三原则:
– 脚本内部一律用绝对路径或相对脚本自身定位, 不假设 cwd。
– 依赖通过环境变量注入, 不硬编码。尤其涉及密钥时, 走 bootstrap 读取, 绝不写死在脚本里。
– 跨工具差异用一层适配 wrapper 吸收, 别让核心脚本里长出 if 工具==X 的分支。三个以上分支就是设计出问题的信号。

跨模型/跨 SDK 调用时还有一类隐蔽差异是错误格式不统一, 同一个失败在不同链路下报得五花八门, AI_ProviderSpecificError 报错定位与修复: AI SDK 排错是一个具体的踩坑样本, 迁移脚本前扫一眼能省时间。

5.4 能力边界差异

不是每个工具都给 skill 同等的权限。有的能跑任意 shell, 有的沙箱限制严格; 有的能联网, 有的不行。一个重度依赖 shell 的 skill 迁到受限工具里可能直接哑火。

应对: 在 SKILL.md 里显式声明这个 skill 的依赖前提(需要 shell、需要网络、需要某个 CLI 已安装)。迁移时先核对目标工具是否满足, 不满足就降级或标记为不可用, 而不是让它在运行时静默失败。

六、团队共享: 从个人资产到协作流程

单人复用解决”我自己别重复劳动”; 团队共享要解决”全队用同一套规范, 且改动可控”。

6.1 集中仓库 + PR 流程

把 skill 仓库放团队可访问的 git 远端, 任何人改 skill 都走 branch + PR + review。这件事的价值在于: skill 是会直接影响 agent 行为的”准代码”, 一个人随手改了 commit skill 的规范, 全队的提交风格就变了。让它走 review, 和 review 代码同等对待。
```
git checkout -b feat/blog-skill-seo-rules
# 改 skills/blog-publish/references/seo-title-rules.md
git add . && git commit -m "feat(blog-publish): 加入 SEO 标题硬规则"
git push origin feat/blog-skill-seo-rules
# 开 PR, 团队 review 触发效果与措辞后合并
```
6.2 安全审查: skill 也是攻击面

这一点必须单独强调。skill 里有 scripts/, 有命令, 有时还有凭据读取逻辑。一个被污染的 skill, 等于让 agent 在你机器上跑了一段你没仔细看的脚本。 团队共享放大了这个风险——一个人引入恶意或粗心的 skill, 影响全队。

所以 skill 仓库的安全要求不能靠”感觉没问题”:
– 脚本不硬编码密钥, 走 bootstrap / 环境变量。
– review 时重点看 scripts/ 里有没有外发数据、有没有读敏感文件、有没有往临时目录写可执行文件。
– 来源不明的第三方 skill, 先在隔离环境跑过再进主仓。

“安全要的是证明而不是感觉”这个判断对 skill 同样成立, 安全不是氛围, 是证明讲的虽然是 prompt 安全, 但”不能靠语义过滤器兜底, 要靠可验证的约束”这个内核, 直接适用于 skill 脚本审查。

6.3 文档即接口: README + 触发词索引

团队规模上来后, 别人不知道你这有哪些 skill、什么时候该用哪个。在仓库根维护一份索引, 列出每个 skill 的 name、description 摘要、依赖前提、维护人。这本质是把”文档即接口”落到实处: 一份能驱动别人正确调用 skill 的索引, 才算把这套资产建模完整了。

6.4 复用的边界: 不是所有东西都该做成共享 skill

最后一条反向提醒: 不要把什么都做成团队级 skill。高度个人化的工作习惯、一次性的探索脚本, 留在个人层就好。团队仓库里只放真正需要全队一致的东西(提交规范、发布流程、安全 checklist)。skill 太多太杂, 反而增加 description 之间的语义干扰, 让自动触发的工具选错。关于”什么该沉淀、什么该丢”, 选型层面的 AI Agent 框架全景: LangChain/LangGraph/n8n/Dify 等选型指南给了一个可类比的取舍框架: 先定决策维度, 再决定收口到哪一层。

七、相关阅读

把这套方法论放进更大的 agent 工程图景里, 下面几篇可以接着读:
- Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 —— 先把工具盘子定下来。
- Agent Harness 不是要安装的软件包 —— harness 与 skill 的边界划分。
- 构建 Agent 和写软件, 是两种工程 —— 为什么 skill 要把决策和确定性执行分开。
- 把 Agent 送上生产: RAG、工程、安全、评测 —— skill 只是生产化拼图的一块。
- 开源 AI Agent 调试器 HALO: 利用 RLM 技术实现本地化闭环优化 —— skill 改完后怎么观测闭环效果。
- AI 信源指南: 收录 Karpathy、Sam Altman 等百余位顶级专家的 X 平台关注清单 —— 跟进 agent 工具演进的信息源。
如果你是从零搭 agent 开发能力, 技术社区热议: AI Agent 开发的学习路径与资源盘点适合作为更靠前的入门索引。

八、FAQ

Q1: skill 用 markdown 写, 不会因为太”软”而不可靠吗?

可靠性不来自格式的”硬”, 来自结构和验证。把确定性逻辑沉到 scripts/(那部分是真代码, 可测), 把决策留给 SKILL.md(那部分本来就该是自然语言)。再配上 git 历史和 CHANGELOG, 你对每次改动的效果有迹可循。这比埋在 GUI 里、改了无从追溯的”硬配置”可靠得多。

Q2: 我只用一个工具, 还有必要搞这套吗?

值得做的是其中两件: git 版本化和标准化目录。这两件即使单工具、单人也立刻回本——你获得了回滚能力和清晰结构。软链/子模块/同步脚本那部分是多工具才需要的, 单工具可以先不碰, 等你哪天加第二个工具时再补, 成本也不高。

Q3: openclaw、hermes 这类工具的 skill 格式和 Claude Code 不一样, 怎么共享?

共享的是内核(提示 + 脚本目录), 不是表层格式。真相源用表达力最强的格式(推荐 Claude Code 的 frontmatter 约定)写一份, 各工具的具体格式用一层转换/适配脚本生成。具体差异在哪、怎么吸收, 见第五节”跨工具迁移”。核心是: 永远不要为了迁就某个工具的弱格式去阉割真相源。

Q4: 软链、子模块、同步脚本, 到底用哪个?

按场景: 单人单机多工具用软链(最轻); 跨项目引用、要钉版本用子模块(可锁 commit); 工具不认软链时用同步脚本(最通用)。三者可以混用, 唯一的铁律是——只有一份会被编辑的源, 其余都是只读投影。

Q5: 团队里怎么防止有人引入有问题的 skill?

把 skill 仓库当代码仓库管: 改动走 PR + review, 重点审 scripts/ 里的命令(有没有外发数据、读敏感文件、写可执行文件到临时目录), 密钥一律走 bootstrap 不硬编码, 第三方来源先隔离环境跑过再进主仓。详见第六节 6.2。

九、结语

agent 工具会一直增加, 这是确定趋势。如果你的 skill 跟着工具走, 每多一个工具就多一份要手动同步的副本, 维护成本是线性甚至超线性增长的。

换个建模方式: 把 skill 当成独立于工具存在的工程资产——纯文本、可 diff、git 版本化、一份源多处投影。这样每多一个工具, 增加的只是一条软链或一段适配, 边际成本趋近于零。

落地就三步, 今天就能起: 第一, 把散在各工具里的 skill 收进一个 git 仓库, 按标准目录结构摆好; 第二, 选软链或同步脚本, 让各工具指向这一份源; 第三, 给重要 skill 打上 tag、补上 CHANGELOG。从”四份会漂移的副本”到”一份可维护、可审计、可共享的真相源”, 差的不是工具, 是把它当资产来养的这套习惯。
6小时前
从“模型坍塌”到“人类退化”：开发者反思 AI 对创造力的侵蚀

近日，一位开发者在技术社区 V2EX 发文，表达了在整理旧时代 Git 仓库时对当前技术环境的反思。该开发者通过对比过去充满“青涩文笔”和“大开脑洞”的原创内容，与如今遇到任务首先寻求 AI 生成或润色的习惯，指出了 AI 依赖带来的认知惰性。文章引入了人工智能领域的“模型坍塌”（Model Collapse）概念作为核心隐喻，即 AI 模型若仅使用自身生成的合成数据进行再训练，会导致智力不可逆地退化。作者进一步提出了一个令人深思的假设：当人类越来越习惯于消费 AI 生成的内容，甚至让 AI 替代思考时，人类自身的智力水平是否会像模型一样遭遇“污染”和下降？尽管该开发者承认已无法脱离 AI 工具生活，但这一观点揭示了在 AI 生成内容（AIGC）泛滥的背景下，原创思维能力的萎缩风险，特别是对于出生在 AI 时代的“原住民”而言，如何在享受工具便利的同时保持大脑的独立运转与创造力，已成为一个不容忽视的社会性技术议题。

事件分析

此事件反映了技术社区对生成式 AI 深度介入创造性工作后的副作用进行的一次元思考。从技术原理上讲，这对应了机器学习中关于数据分布偏移与“模型坍塌”的讨论：当训练数据被合成数据污染，模型对长尾分布和真实复杂逻辑的理解能力会大幅衰减。映射到人类认知层面，若开发者将核心的架构设计与逻辑推演完全外包给 AI 编程工具，大脑神经网络因缺乏高强度、试错性的深度思考训练，可能导致逻辑构建能力的生理性退化。此外，如果互联网未来的内容增量主要由 AI 生成并回流给人类学习，这种闭环的“回音室效应”不仅限制了人类的视野上限，更可能导致未来数据集源头枯竭，即缺乏高质量的人类真实反馈数据，进而反向制约下一代大模型的演进潜力。

💡 核心观点：当人类思维习惯退化为对 AI 产出的二次校对，创造力与逻辑能力的“模型坍塌”或许将成为技术进步的隐性代价。

原文链接：V2EX 分享发现

10小时前
AI编程实战：非开发人员利用 Claude 耗时 10 天开发出首个 macOS 应用

一位没有编程背景的设计师在 V2EX 分享了其利用 AI 技术耗时 10 天开发人生中第一款 macOS 应用的经历。该开发者受 PopClip 启发，希望拥有一款支持纵向模式和图标模式的工具，因此在 Claude 和 Codex 的辅助下完成了这一项目。开发过程分为三个核心步骤：首先是需求整理，通过草图和文档明确功能与界面布局，并咨询技术专家确认可行性；其次是版本构建，强调需向 AI 清晰描述核心需求以防止其随意更改逻辑，特别是在实现 Look Up 功能时需避免 AI 滥用默认方案；最后是打包测试，利用 GIF 录制 Bug 并喂给 AI 进行修复，期间还借助了 OpenPUA 等开源项目辅助。目前该应用已在 macOS 27.0 Beta 环境下打包测试，支持 macOS 13.0 及以上版本，开发者表示未来考虑加入 AI 结合功能后开源。这一案例生动展示了 Claude 等大模型在赋能非技术人员进行软件开发方面的显著潜力。

事件分析

此事件是“AI编程”从概念走向实用化的典型案例，标志着软件开发门槛正在经历结构性降低。Claude 等大模型在代码生成与逻辑理解上的表现，已足以支撑非技术人员完成包含 UI 布局、交互逻辑及本地功能调用的原生 macOS 应用开发。技术层面上，该案例突出了“提示词工程”与“视觉反馈”在 AI 辅助开发中的重要性，通过 GIF 录制问题并喂给模型修复的方式，有效解决了文本描述偏差导致的理解瓶颈。产业层面，这预示着软件开发职能的模糊化，设计师与产品经理正逐渐具备独立交付软件产品的能力，未来的工具链将更加侧重于自然语言交互与多模态反馈，而非传统的语法记忆。这有助于推动“公民开发者”群体在桌面端应用领域的爆发，加速软件创意的落地速度。

💡 核心观点：Claude 等大模型正在将软件开发从“手艺活”转化为“逻辑描述”，设计师等非技术人员正成为新的应用创造者。

原文链接：V2EX 分享发现

10小时前

1M 上下文已经可用: Claude、Gemini 与编程 Agent 怎么选

有人在搜索框里反复打”1m 上下文已经全量可用”。这背后不是想读一篇科普，而是一个很具体的工程疑问：我现在用的模型，到底是不是已经能吃下 100 万 token 的上下文？如果能，我该不该把整个仓库、整本手册、整批日志一股脑塞进去？

先把结论给你：1M（100 万 token）上下文确实已经在主流前沿模型上”可用”，但”可用”不等于”该这么用”。 它真正改变的不是某个跑分，而是一类原本做不到的任务现在能一次性做完了——比如让一个 Agent 同时看懂跨十几个文件的调用链。代价同样真实：费用随 token 几乎线性上涨、首字延迟变长、还有一个工程师最容易踩的坑——长上下文衰减（模型在超长上下文里”中间遗忘”、检索质量下降）。

这篇从工程师视角，把 1M 上下文在 Claude、Gemini、编程 Agent 三条线的可用性、成本和适用场景一次盘清楚。

一、TL;DR：1M 上下文到底意味着什么

100 万 token 大概是多少

token 不等于字。粗略地说，1M token 对应的量级是：几十万到上百万字的中文文本，或者一个中等规模代码仓库的绝大部分源码，或者几百页 PDF 的全文。换句话说，你第一次可以把”整本书 / 整个项目”作为一个整体喂给模型，而不是切片喂。

这就是它的核心价值：从”分块处理 + 人工拼接”变成”一次性全局理解”。在它之前，处理长文档要靠分段摘要、向量检索、滑动窗口这些工程手段绕；现在某些任务可以直接绕过这些中间层。

一句话工程判断

能用：截至目前，几家头部模型（Claude、Gemini 的部分版本）都提供了接近或达到 1M token 的上下文窗口，部分以 beta / 特定方案的形式开放。
别滥用：窗口大小是”上限”，不是”建议值”。把 100 万 token 全填满，意味着每次请求都在为可能用不到的内容付费，同时把模型推向它检索能力最弱的区间。
真正的工程问题：不是”能塞多少”，而是”该塞哪些、怎么组织、什么时候换成检索”。

如果你正在为”用哪个模型 / Agent”纠结，可以先看这两篇横评打底：Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选和 GLM-5.2 vs GPT-5.5: 架构、Agent 与部署取舍对比，里面对各家的定位有更细的拆解。

二、各家可用性盘点（定性，不报精确数字）

先声明：各家官方上限、单价、beta 政策一直在变，下面只做定性取舍，不把精确数值当权威事实，确切数字请以你下单时的控制台为准。

Claude：长上下文检索质量是强项

Claude 这条线最被工程师认可的，是它在长上下文里的指令遵循和检索稳定性——把关键信息埋在很长的上下文中段，它相对不容易”漏读”。它的 1M 级窗口目前更多以特定层级 / beta 通道开放，定位偏向”需要一次性吃下大量代码或文档、且对准确度敏感”的场景。

实际体感上，很多人是冲着 Claude Code 的工程闭环来的。关于它和 Codex 的对比体验，开发者实测：Claude Code 效率超越 Codex，AI编程迈向”零门槛”自然交互和遭遇GPT降智后转向Claude：开发者实测MCP协议打造”自举”式开发闭环都有第一手记录。

Gemini：超长窗口铺得最早、最广

Gemini 系列是较早把”百万级上下文”作为主打卖点推开的，部分版本对外宣称的上限甚至更高。它的优势在于长文档、长视频、多模态混合的大批量摄入——一次塞进海量原始资料，让模型自己提取结构化信息。社区里有个很典型的用法：HN热帖：利用 Gemini 提取数据，绘制 Mini PC 性价比”帕累托前沿”，本质就是把成千上万条杂乱规格喂进大窗口做一次性归纳。

编程 Agent / Codex：窗口大小≠Agent 好用

这一层最容易被误解。编程 Agent 的实际”可用上下文”，往往不等于底层模型的窗口上限。 Codex、Cursor、Claude Code 这类工具会在你和模型之间做一层上下文管理：它们不会傻乎乎把整库代码塞满窗口，而是按需读文件、做摘要、压缩历史。

所以横向选 Agent 时，窗口大小只是其中一个变量，更关键的是它的上下文调度策略、额度和稳定性。这几篇可以连起来看：Codex vs Cursor 额度对比: 价格、限制与选型建议、深度解析 Cursor Composer 2.5：从”套壳”争议到拥有工作流数据的巨头护城河，以及开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹——最后这篇讨论的”配置/上下文怎么模块化管理”，恰恰是大窗口时代的核心工程问题。

定性对比一张表

维度	Claude	Gemini	编程 Agent（Codex/Cursor/Claude Code）
长上下文检索稳定性	强项，中段不易漏读	容量大，超长时检索质量需实测	取决于其上下文调度，而非底层窗口
超大窗口铺开程度	特定层级 / beta	较早、较广，部分版本上限更高	不直接暴露满窗，按需读取
最适合的活	准确度敏感的大代码/长文档	海量原始资料一次性归纳、多模态	多文件改动、跨文件调用链理解
工程师该看的关键指标	检索准确率 + 价格	容量 + 衰减表现	上下文管理策略 + 额度 + 稳定性

注：表中均为定性判断。涉及具体跑分时，社区/公开讨论里说法不一，请按你自己的真实任务做小样本实测，不要照搬别人的 benchmark 结论。

三、真实成本与”长上下文衰减”陷阱

这一节是全文重点，也是”1m 已经可用”这条搜索词背后最该被回答的部分——因为很多人以为可用就等于免费午餐。

成本：token 几乎是线性涨的

绝大多数 API 按输入 + 输出 token 计费。这意味着：你往上下文里多塞一倍内容，输入成本大致就翻一倍。 把窗口从几万 token 拉到接近 1M，单次请求成本可能是几十倍的差距。如果这是一个高频调用的 Agent 循环，账单会非常吓人。

关于成本如何反过来决定架构选型，LLM时代的软件生存法则：SaaS自建与购买的成本临界点分析把成本临界点量化得很清楚；订阅额度层面的真实痛点可以看开发者热议AI订阅痛点：对比GPT Pro与Claude的额度与安全性。如果你在用中转 / 聚合方案压成本，AnyRouter 实测：模型路由、API 兼容与价格稳定性也值得参考。

延迟：窗口越满，首字越慢

上下文越长，模型预填充（prefill）要处理的 token 越多，首字延迟会明显上升。对交互式编程 Agent 来说，每次都灌满窗口，体感就是”问一句要等很久”，开发循环被拖垮。

缓解手段是 prompt caching（提示缓存）：把不变的大块前缀（如系统提示、整库代码）缓存住，后续请求复用，既省钱又省延迟。这是用好大窗口的关键工程技巧——不是少塞，而是让重复部分不重复计费。

衰减：lost in the middle，长上下文的”中间遗忘”

这是最隐蔽的坑。研究和大量实践都观察到一个现象：当关键信息位于超长上下文的中间位置时，模型的检索准确率会下降，业内常称为 “lost in the middle”（中间遗忘）。也就是说，你把 100 万 token 填满，模型未必真的”看清”了每一个角落——开头和结尾它记得牢，中段容易糊。

这带来一个反直觉的结论：有时候塞得更多，效果反而更差。 因为你引入了大量噪声，稀释了真正相关的信号，还把关键内容推到了模型最不擅长的检索区间。

举个具体的例子。假设你要让模型基于一份内部规范回答问题，规范一共三十页。做法一：把三十页全文连同其它二十份无关文档一起塞进窗口，凑到几十万 token；做法二：只把这三十页规范放进去，其它不放。直觉上做法一”信息更全”，但实际上做法一往往更差——真正相关的三十页被淹没在无关内容里，又恰好落在容易被忽略的中段，模型抓不住重点；而做法二上下文干净、相关密度高，答得反而更准、更便宜、也更快。这就是”精确投喂”为什么经常打败”应塞尽塞”。同样的道理放到代码上也成立：与其把整个 monorepo 灌进去，不如先定位到真正相关的那几个模块再交给模型。

经验法则（按你的任务实测校准，不是绝对值）：
  上下文长度 ↑  →  单次成本 ↑（近线性）
                →  首字延迟 ↑
                →  中段检索准确率 ↓（lost in the middle）

结论：上下文是有成本的资源，要"精确投喂"，不是"能塞就塞"。

本地小模型在这点上更敏感——窗口、量化精度、显存三者互相挤压。想看这层取舍，Qwen3.6 27B vs Step3.7 IQ4_XS: 本地大模型量化精度实测给了一张很实在的选型矩阵。

四、什么场景该用大窗口、什么场景用 RAG 更划算

把上面的成本和衰减放在一起，决策其实就清晰了：大窗口和 RAG（检索增强）不是二选一的对立，而是按任务形态分工。

适合直接用大窗口

需要全局连贯理解：跨多文件的代码重构、读懂一份逻辑环环相扣的长合同、分析一份首尾呼应的研究报告。这类任务一旦切片就丢失全局关系，大窗口是刚需。
一次性、低频的大批量摄入：把一整批原始资料喂进去做一次归纳总结，跑完就走，不进入高频循环。
多文件 Agent 任务：让 Agent 同时持有十几个相关文件，理解它们之间的调用关系再动手改。十年代码荒后的技术重构：创业老兵实测 Claude 与国产模型的多 Agent 协同差异就是这种”多文件 + 多 Agent 协同”的实战样本。

适合用 RAG / 检索

海量、低相关密度的知识库：你有几百万字文档，但每次查询只用到其中很小一部分。把全部塞进窗口，等于为 99% 用不到的内容付费，还触发中间遗忘。这时候先检索召回相关片段、再喂给模型才是对的。
高频、对成本敏感的循环：客服、问答这类每天上万次调用的场景，必须把每次请求的 token 压到最小。
需要可溯源、可更新的事实：RAG 能给出引用来源，知识更新只要更新检索库，不用重灌上下文。

决策表

你的情况	优先方案	理由
单次任务，内容强相关、需全局理解	大窗口	切片会丢关系，一次性看完最准
知识库巨大，单次只用一小部分	RAG 检索	省钱、避开中间遗忘
高频调用、成本敏感	RAG + 缓存	token 压到最小才扛得住账单
多文件代码改动、跨文件依赖	大窗口（Agent 调度）	Agent 按需读取，兼顾全局与成本
需要引用来源、知识常更新	RAG	可溯源、可增量更新

实务里最常见的其实是混合：用 RAG 把候选范围缩到几万 token，再交给具备大窗口的模型做精读和综合。两边的长处都要。

五、对编程 Agent / Claude Code / Codex 的影响

对写代码的人来说，1M 上下文最大的意义不是”能读完整库”，而是改变了 Agent 维持项目记忆的方式。

整库理解成为可能，但 Agent 仍在做减法

理论上大窗口能让 Agent 一次看懂整个仓库。但前面说过，真把整库塞满既贵又触发衰减。所以成熟的编程 Agent 走的是“大窗口能力 + 智能上下文管理”的组合：底层有大窗口托底，上层仍然按需读文件、做摘要、压缩历史对话。窗口大小给了它”必要时能展开”的余地，而不是”每次都展开”的负担。

上下文管理 = 长项目的真正分水岭

长项目里，模型每次重新打开仓库都要”恢复现场”。从哪里恢复、恢复多少，决定了它还认不认得这套代码。Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换把这个问题讲透了：原型阶段可以”想到哪写到哪”，但项目一长，必须靠规格（spec）和结构化的上下文来锚定，光靠塞大窗口救不回来。

配置和上下文怎么模块化组织，也直接影响 Agent 的可维护性——开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹讨论的就是这件事。而当 Agent 的会话状态丢失时会有多痛，Codex CLI MCP 服务器 logout 吞 session: 复现与修复是一个具体到根因的案例。

多 Agent 协同会放大上下文成本

当你从单 Agent 走向多 Agent，每个 Agent 都持有自己的上下文，总 token 消耗是叠加的。企业实战案例：多Agent系统重构人力资源招聘流程能看到：Agent 越多、文档越复杂，上下文管理越是成败关键。任务对齐和拆解做得好，才不会让每个 Agent 都去灌满窗口，清华博士开源 COMPASS 司南生态更新：Task-Clarifier 升级，强化 Agent 任务对齐能力走的就是这个方向。

给工程师的落地建议

# 用大窗口前，先问自己三个问题：
# 1. 这些内容真的都"强相关"吗？还是能先检索缩范围？
# 2. 这是单次任务，还是会进高频循环？（循环就别灌满）
# 3. 不变的大前缀，有没有用上 prompt caching 复用？

# 实操顺序建议：
#   RAG 召回  →  组织成最小必要上下文  →  缓存稳定前缀  →  交给大窗口模型精读

六、相关阅读

Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选：选 Agent 的横评底盘，窗口只是其中一维。
GLM-5.2 vs GPT-5.5: 架构、Agent 与部署取舍对比：架构层面的取舍，理解各家定位差异。
豆包 AI 优缺点实测: 对比 ChatGPT、Claude 与 Kimi：同一批任务横评四家，看长文本处理差异。
LLM时代的软件生存法则：SaaS自建与购买的成本临界点分析：成本临界点量化，决定你该不该上大窗口。
Codex macOS code_sign_clone 占几十 GB 磁盘: 真相与清理：用 Codex 时另一个容易被忽略的工程坑。

七、FAQ

Q1：1M 上下文现在是不是所有人都能用上？
要分清”模型支持”和”你的账号 / 套餐能用”。前沿模型在技术上已经提供接近或达到 1M 的窗口，但是否对你开放，取决于你用的版本、层级、是否在 beta 名单内。最稳妥的办法是去你下单的控制台看当前上限，别照搬别人的截图。

Q2：把整个项目塞进 1M 窗口，模型就能完全读懂吗？
不能想当然。受 “lost in the middle”（中间遗忘）影响，塞得越满，中段信息越容易被忽略。整库代码更推荐交给具备上下文调度的编程 Agent，由它按需读取，而不是你手动一次性灌满。

Q3：大窗口和 RAG 到底选哪个？
看任务。内容强相关、需全局理解、单次低频 → 大窗口；知识库巨大但单次只用一小部分、高频、成本敏感 → RAG。现实里最常见的是两者混合：先检索缩范围，再用大窗口精读。

Q4：用 1M 上下文会不会很贵？
会。token 近似线性计费，灌满窗口的单次成本可能是常规请求的几十倍，进入高频循环后账单很可观。务必用 prompt caching 复用稳定前缀，并只投喂强相关内容。

Q5：长上下文会让回答变慢吗？
会。上下文越长，预填充处理的 token 越多，首字延迟上升。交互式编程场景尤其敏感，缓存 + 精确投喂是必要的优化。

八、结语

1M 上下文确实已经可用，但它是一种有成本的资源，不是免费容量。真正的工程能力，体现在你知道什么时候该展开整库、什么时候该退回 RAG 检索——精确投喂，而不是能塞就塞。

1天前

CLAUDE.md 怎么写: 提升 Claude Code 准确率的最小有效配置
社区里流传一句很有冲击力的话：某个项目把 Claude Code 的「准确率从 41% 升到 89%」，靠的只是改了一个 CLAUDE.md。这个数字来自热点原帖的说法，没有公开的评测方法和样本量，我们不把它当作实测基准。但它指向的那件事是真的，而且每个用 Claude Code 写过几天代码的人都体感得到：同一个模型、同一个仓库，给不给项目说明，输出质量差出一个档。

这篇文章不复述那个跑分故事，而是把它背后的工程问题讲透——CLAUDE.md 到底凭什么影响准确率，一个有效的 CLAUDE.md 该包含哪些块、删掉哪些块，根目录和子目录怎么分层，以及大多数人写它时会踩的几个坑。文末给一份可以直接拿走改的模板骨架。

为什么一个文本文件能改变准确率

TL;DR

CLAUDE.md 是 Claude Code 在每次会话启动时自动读入、拼进系统上下文的项目说明文件。它不是文档，是接口——你用它把「这个项目的真实约束」喂给模型，模型据此决定怎么写代码、跑什么命令、碰什么不能碰。写得准、写得短，模型就少猜；写得乱、写得长，模型的注意力被稀释，反而更容易跑偏。提升准确率的核心不是「写更多」，而是「写对的那几条，并且保持它不过期」。

机理：这其实是一道上下文工程题

要理解 CLAUDE.md 为什么有用，得先承认一个事实：大模型对你的项目一无所知。它不知道你的构建命令是 pnpm build 还是 make，不知道你这个仓库里 utils/ 已经废弃、新代码要写进 lib/，不知道你团队约定「不准在 /tmp 留 .php」。没有这些信息时，模型只能靠先验去补——也就是从训练语料里见过的「大多数项目长什么样」来猜你的项目。猜对了是运气，猜错了就是你要返工的那一段。

CLAUDE.md 做的事，是把模型从「靠先验猜」拉到「靠现场事实推」。这正是上下文工程的核心命题：模型的能力上限由权重决定，但单次任务的发挥由你喂进上下文的信息决定。同一个 Claude，在一个有清晰 CLAUDE.md 的仓库里像个熟悉代码库的同事，在一个空仓库里像个第一天入职、谁也没给他讲过规矩的外包。

这里有个容易被忽略的反向效应：上下文不是越多越好。模型的注意力是有限资源，你塞进 CLAUDE.md 的每一个字都在和真正重要的约束抢注意力。一份 600 行、把环境变量、历史决策、未来规划全堆进去的 CLAUDE.md，效果往往不如一份 80 行、只讲清楚「项目结构 + 关键命令 + 三条红线」的精简版。这就是为什么这篇文章反复强调最小有效——目标是信噪比，不是信息量。

如果你对「模型重新打开仓库时从哪里恢复记忆」这件事感兴趣，Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换把长项目的上下文恢复问题讲得更系统，CLAUDE.md 正是其中最便宜的一环。

一个有效的 CLAUDE.md 该有哪些块

下面逐块拆。每一块都给「为什么需要」和「示例写法」，但请记住：不是每个项目都要全装上，按你仓库的实际复杂度取舍。

块一：项目是什么（一两句话定位）

模型需要先知道它在跟什么打交道。一句话说清楚这是个什么项目、用什么技术栈、解决什么问题。不要写市场宣传语，写工程事实。
```
## 项目
基于 Next.js 14 (App Router) + TypeScript 的内容站。
数据源是本地 Markdown，构建期静态生成。无后端数据库。
```
这三行的价值在于：模型从此知道「这里没有数据库」，就不会给你写出连 Prisma 的代码。

块二：项目结构（只标关键目录，不复述文件树）

不要把 tree 的输出贴进来——那是噪音。只标注那些「模型必须知道、否则会写错位置」的目录约定。
```
## 结构
- `lib/`：核心逻辑，新代码写这里
- `utils/`：已废弃，不要往里加东西
- `content/`：Markdown 内容源，构建期读取
- `app/api/`：路由处理，每个文件一个 endpoint
```
注意「utils/ 已废弃」这种负向约定往往比正向说明更值钱，因为它消除了模型一个最常见的错误猜测。

块三：关键命令（构建、测试、lint）

模型经常需要自己跑命令验证改动。如果你不告诉它命令是什么，它会去猜——猜 npm test 结果你用的是 vitest，猜 npm run build 结果你用的是 pnpm。把这几条钉死：
```
## 命令
- 装依赖：`pnpm install`
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`
- 测试：`pnpm test`（vitest）
- 类型检查：`pnpm typecheck`
```
这一块对「让模型自己验证」的工作流尤其关键。模型能自己跑测试、读报错、再修，这条闭环的起点就是它知道该跑什么命令。

块四：代码风格与约定

不要把整个 ESLint 配置抄进来——那有 lint 工具管。这里写的是工具检查不出来、但你团队真在乎的约定。
```
## 约定
- 组件用函数式 + hooks，不写 class 组件
- 异步用 async/await，不用 .then 链
- 错误处理：API 层统一 try/catch，不在组件里裸 fetch
- 文案中文用全角标点，代码注释用中文
```
块五：做什么 / 不做什么（红线）

这是整份文件里密度最高的一块，也是最能拉准确率的一块。把那些「做错了代价很大、回滚很贵」的边界明确列出来。
```
## 红线
- 不要改 `config/legacy.ts`，那是兼容层，动它会炸老用户
- 不要在未问的情况下升级主版本依赖
- 提交信息用 conventional commits 格式
- 数据库迁移必须可回滚，不写不可逆的 DROP
```
这一块的写法直接决定了模型会不会闯祸。红线越具体，模型越不容易在你没盯着的时候做出难以挽回的操作。关于「用流程规范约束 AI 行为」，开发者反击”自私”的 AI 滥用：用表情符号暗号与流程规范对抗 LLM 垃圾内容提供了一个更激进的社区视角，本质上和这里的「红线」是同一类思路。

块六：按需加载的子文档索引

CLAUDE.md 本身要短，但有些信息（数据库 schema、复杂模块的设计文档、踩坑记录）确实需要存在。解法是索引而非内联：在主文件里只放一行指针，告诉模型「需要时去读哪个文件」。
```
## 关键文档（按需加载）
- `docs/db-schema.md`：数据表结构，涉及数据层任务时读
- `docs/auth-flow.md`：鉴权流程，改登录相关时读
- `docs/deploy.md`：部署流程与回滚步骤，发布前读
```
这样主文件保持精简，详细信息又不丢失。模型会在判断任务相关时主动去读那些子文档，而不是一上来就被几千字的 schema 占满上下文。

目录约定与分层：根 CLAUDE.md 不是唯一一份

很多人不知道 CLAUDE.md 可以分层。Claude Code 不只读根目录那一份，它会沿着你当前工作的目录路径，把沿途的 CLAUDE.md 都纳入上下文。这给了你一个很自然的「就近说明」机制。

根目录 CLAUDE.md：全局约定

放整个仓库都适用的东西：技术栈、全局命令、跨模块的红线、团队风格。这一份要尽量稳定，不该频繁改动。

子目录 CLAUDE.md：局部上下文

在一个有独立约定的子目录里放一份局部 CLAUDE.md。比如你的 packages/web/ 和 packages/cli/ 用不同的测试框架、不同的发布流程，就各放一份，写各自的局部规则。模型在 packages/web/ 下干活时，自然带上 web 包的上下文，不会被 cli 包的规则干扰。

这种分层的好处是信息局部性：每一份文件只对它管辖的范围负责，既避免了根文件无限膨胀，也避免了模型在写 A 模块时被 B 模块的无关信息分心。这其实和「模块化管理配置」是同一个工程直觉——社区里关于配置组织方式的讨论一直没停，开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹就是一例，分层 CLAUDE.md 是 Claude Code 自带的、最轻量的模块化手段。

如果你同时在用多个 AI 编程工具，配置分散是个真问题。社区已经有人在做聚合管理，比如聚合管理AI编程客户端配置，开源工具SMRmanager v0.2发布和早一点的开源神器 SMRmanager：一键统一管理 Claude、Cursor 等 AI 编程工具配置，思路是把多工具的配置集中起来。不过对单一 Claude Code 项目来说，先把分层 CLAUDE.md 写好，收益更直接。

一份可复用的模板骨架

下面是一个可以直接拿走改的根目录 CLAUDE.md 模板。它是示例/参考写法，不是官方规范——Claude Code 对 CLAUDE.md 的内容没有强制 schema，你完全可以增删块。保持它在 100 行以内，是这份模板想传达的纪律。
```
# CLAUDE.md

## 项目
<一两句话：什么项目、什么栈、解决什么问题、有没有后端/数据库>

## 结构
- `src/`：<职责>
- `<已废弃目录>/`：不要往里加东西
- `<内容/配置目录>/`：<构建期还是运行时用>

## 命令
- 装依赖：`<cmd>`
- 开发：`<cmd>`（端口 <port>）
- 构建：`<cmd>`
- 测试：`<cmd>`（<框架>）
- lint / 类型检查：`<cmd>`

## 约定
- <工具检查不出、但团队在乎的风格 1>
- <约定 2>
- <约定 3>

## 红线（做错代价大、回滚贵）
- 不要改 `<敏感文件>`，原因：<...>
- 未经确认不要 <危险操作>
- 提交信息用 <格式>
- <可回滚要求>

## 关键文档（按需加载）
- `docs/<x>.md`：<什么时候读>
- `docs/<y>.md`：<什么时候读>
```
子目录 CLAUDE.md 更短，通常只需要「局部命令 + 局部约定 + 局部红线」三块，全局信息靠根文件继承，不要重复。

值得强调的是：模板是起点不是终点。第一版写出来后，真正让它变准的是迭代——你每次发现模型又跑偏了，就回头问「CLAUDE.md 里缺了哪条说明，导致它这么猜」，把那条补上。几轮之后，这份文件会收敛成你这个项目专属的、密度极高的说明书。这个「发现偏差 → 补一条 → 收敛」的循环，和工程团队用 AI 重写核心模块时的迭代方式是相通的，PostHog 工程实录：利用 AI 重写核心 SQL 解析器，性能暴增 454 倍里那种长会话、反复校准的打法，靠的也是把项目约束持续喂准。

常见反模式：好心办坏事的三种写法

CLAUDE.md 写坏比不写还糟，因为坏的说明会主动误导模型。下面三种是最高频的。

反模式一：写成一本书

最常见的错误，是把 CLAUDE.md 当成项目 wiki，恨不得把架构演进史、所有环境变量、每个模块的详细设计全塞进去。结果是几百行的文件，模型读完，真正重要的「红线」被埋在第 300 行，注意力早就分散了。

修法：主文件砍到 100 行以内，详细内容拆进 docs/ 用「按需加载索引」引用。问自己一个问题：这条信息，是「模型每次都得知道」还是「模型偶尔才用到」？前者留在主文件，后者进子文档。

反模式二：堆无关信息

往 CLAUDE.md 里塞模型其实用不上、或者别的工具已经管了的东西。比如把整份 .eslintrc 抄进来（lint 工具会执行，模型不需要读）、把 package.json 的依赖列表复述一遍（模型自己会看 package.json）、写一堆「我们是一个充满激情的团队」之类的废话。

修法：每一行都过一遍「删掉它，模型会写错吗？」如果不会，就删。CLAUDE.md 的每个字都该是「不写就会出错」的信息。

反模式三：过期不更新

这是最隐蔽、危害最大的一种。你三个月前写「测试用 jest」，后来全仓库迁到了 vitest，但 CLAUDE.md 没改。现在模型每次都按 jest 的 API 给你写测试——它不是猜错的，是被你主动喂错的。过期的 CLAUDE.md 比没有 CLAUDE.md 更危险，因为它带着权威感误导。

修法：把 CLAUDE.md 当代码维护。目录结构变了、命令变了、约定变了，第一时间同步改。最好在团队约定里写一条：「改动构建/测试/目录结构的 PR，必须同步更新 CLAUDE.md」。让它和代码一起进版本控制、一起 review。

这种「配置漂移导致行为异常」的麻烦，在 Claude Code 的使用反馈里并不少见。当然有些波动并不是 CLAUDE.md 的锅，比如解决 Claude Code 性能波动难题：用户推测降智与服务器 Session 路由强相关讨论的是服务端的不确定性。排查输出质量问题时，先确认是「你喂的上下文有问题」还是「服务端确实在抖」，别把所有锅都甩给 CLAUDE.md，也别忽略它。

把 CLAUDE.md 放进更大的工作流

CLAUDE.md 不是孤立的。它和你怎么选工具、怎么编排多智能体、怎么管额度，共同决定了 AI 编程的最终体验。

如果你还在选编程 Agent，Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选和 AI编程工具现状：从IDE到CLI，开发者如何在Cursor与Claude间抉择这两篇能帮你定位——但无论选哪个 CLI 类工具，「给项目写一份精炼的说明文件」这个动作都是通用的，只是文件名不同。

进阶玩法是多智能体协作，开发者构建多智能体协作流：用GPT Pro指挥Claude Code与Codex 展示了用一个模型指挥另一个模型干活的编排方式，这种场景下每个执行节点都需要清晰的项目上下文，CLAUDE.md 的价值被进一步放大。而遭遇GPT降智后转向Claude：开发者实测MCP协议打造”自举”式开发闭环则把 MCP 协议和开发闭环串了起来，CLAUDE.md 在这种闭环里承担的就是「让每一轮都从正确的项目认知出发」。

成本侧也别忽视。上下文写得精炼，本身就是省 token——一份臃肿的 CLAUDE.md 每次会话都要重新读一遍，长期看是实打实的额度消耗。关于额度，社区最近讨论很多，比如 Claude Code 实战：20篇顶会文献瞬间总结，Opus 额度告急引发成本担忧和频繁触发限流？开发者反馈 Claude Code 会话额度疑似大幅收紧，精简上下文虽然不能根治限流，但能让你每一份额度花得更值。

相关阅读
- Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换——CLAUDE.md 是长项目上下文恢复的最便宜一环，这篇讲清楚什么时候该上规格。
- Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选——选定工具，再谈配置。
- 深度解析 Cursor Composer 2.5：从”套壳”争议到拥有工作流数据的巨头护城河——理解工作流数据为什么是护城河，会让你更重视本地上下文资产。
- AI编程新范式：2026 Vibe Coding全栈实战训练营，整合Cursor与Claude Code——把工具整合进完整工作流的实战视角。
FAQ

Q：CLAUDE.md 要放在哪里，Claude Code 会自动读吗？
A：放在项目根目录，文件名就是 CLAUDE.md。Claude Code 在会话启动时会自动读取并拼入上下文，无需手动指定。子目录里也可以放，模型在该目录下工作时会一并纳入。

Q：CLAUDE.md 越详细越好吗？
A：不是。它和真正重要的约束抢模型注意力，过长反而稀释效果。目标是「最小有效」——只写不写就会出错的信息，详细内容拆进 docs/ 按需加载。一般主文件控制在 100 行以内。

Q：那个「41% 到 89%」的准确率提升是真的吗？
A：这是社区热点原帖的说法，没有公开的评测方法、样本量和复现步骤，不能当作权威基准。但「写好项目说明文件能显著改善输出质量」这个方向是站得住的，具体能提升多少取决于你的项目和写法。

Q：CLAUDE.md 和 MCP、子 agent 这些是什么关系？
A：是互补的不同层。CLAUDE.md 解决「模型该知道这个项目的什么」，MCP 解决「模型能调用什么外部能力」，子 agent 解决「复杂任务怎么拆分编排」。先把 CLAUDE.md 写好，它是成本最低、收益最直接的一层。

Q：团队协作时 CLAUDE.md 要进版本控制吗？
A：要。把它当代码维护，进 Git、一起 review，约定「改构建/测试/目录的 PR 必须同步更新它」。过期的 CLAUDE.md 会主动误导模型，比没有还糟。

结语

CLAUDE.md 不是文档，是接口：你把项目的真实约束写准、写短、并保持它不过期，模型就从「靠先验猜」切到「靠现场推」。提升准确率的关键从来不是写更多，而是写对那几条。先给你的项目补一份 80 行的精简版，剩下的交给迭代。
1天前
Codex 磁盘占用异常: 失控写盘的根因与排查清理
“Codex 会把磁盘给烧了吗?” 这句听上去夸张的吐槽，背后其实是一个很现实的问题: 当你把一个能自己读写文件、跑命令、装依赖、起容器的自主编程 agent 放到本地长时间运行，它确实有可能在你不注意的时候把磁盘占用悄悄推到几十 GB 量级，严重时直接把分区写满，导致系统卡顿、构建失败、甚至别的服务跟着崩。

“烧磁盘” 当然不是字面意义上把 SSD 物理烧坏——现代固态盘的写入寿命远没有那么脆弱。真正的风险是磁盘空间被异常占满，以及在极端循环下产生的高频无意义写入。这篇文章用一次复盘的方式，把这类 agent 吃满磁盘的真实机理、复现思路、排查命令和预防边界讲清楚，给所有在本地跑 Codex、Claude Code、Cursor 这类工具的人一份可以直接照做的 checklist。

TL;DR: 先给结论
- 不会烧坏硬件，但会写满分区。自主编程 agent 的本质是”能写盘的循环”，循环失控就是磁盘异常的根因。
- 占用通常不在你的项目目录里，而是藏在缓存、日志、临时文件、容器镜像、会话快照这些”看不见的角落”。
- 排查的第一原则是 先量后猜: 用 df -h 看分区，用 du -sh 和 ncdu 定位大目录，不要凭感觉删文件。
- 预防的核心是给 agent 划边界: 审批模式、沙箱隔离、资源限额、定时清理，四件套缺一不可。
- 大多数”吃满磁盘”事故，根因是没设上限的自动循环 + 没人看的后台任务，而不是工具本身有 bug。
如果你正在排查一个具体的占用问题，可以直接跳到下面的复现与排查章节。如果你想从根上避免，重点看修复与预防。

现象: 它是怎么一步步把盘吃满的

先描述一类典型场景，便于对号入座。

你让 Codex 帮你完成一个稍微复杂点的任务，比如”把这个项目重构成 monorepo，顺便把测试补全”。这种任务天然需要 agent 反复读写文件、安装依赖、跑构建、看输出、再修正。一切看上去正常，直到某个时刻你发现:
- IDE 开始卡，保存文件变慢
- 终端报 No space left on device
- Docker 拉镜像失败，提示磁盘不足
- git status 慢得离谱，或者干脆报错
这时候 df -h 一看，根分区或者 home 分区已经红了。问题是: 你的项目源码加起来可能也就几百 MB，那几十 GB 到底去哪了?

这就是这类事故最反直觉的地方——占用的大头几乎从不在你盯着的地方。它分散在一堆你平时根本不会打开的目录里，而 agent 在自动循环里把它们一点点喂大了。理解这一点，比记住任何具体命令都重要。

换个角度看，人类开发者和 agent 在磁盘行为上有一个本质差异: 人写代码是”目标导向、用完即走”，装一次依赖、构建一次、清理收工; agent 则是”过程留痕、反复试错”，它把每一次尝试的中间状态都落到盘上，因为它需要这些状态来观察和修正。这个机制让它强大，也让它成了磁盘消耗的放大器。所以排查它的占用，思路不能照搬人类经验里”项目目录最大”的直觉，而要专门盯那些”过程态”产物聚集的角落。

根因: 为什么自主编程 agent 容易吃满磁盘

要复盘，先得理解机理。这类 agent 吃磁盘不是单一原因，而是几条路径叠加。下面逐条拆。

一、失控的文件生成与重试循环

这是最危险、也最容易被低估的一类。Agent 的工作模式是”生成—执行—观察—修正”的闭环。正常情况下这个闭环会收敛，但在某些条件下它会发散:
- 任务目标定义不清，agent 反复重写同一批文件，每次都留下中间产物
- 某个命令一直失败，agent 不断重试，每次重试都生成新的日志、新的临时文件
- agent 误判”需要更多数据”，开始批量下载、生成、导出，没有上限
这种循环一旦没有外部约束，写盘速度可以很快，几小时内膨胀到数十 GB 并不夸张，具体取决于运行时长和单次写入的体量。它的可怕之处在于”看上去一切正常”——agent 没有报错、没有卡死，只是安静地一遍遍重写，而每一遍都比上一遍多留下一点垃圾。等你察觉时，往往已经是分区报红的时刻。这也是为什么社区里反复强调任务边界——关于把任务拆清楚、何时该写规格的讨论，可以看 Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换，规格不清正是循环发散的温床。一个被定义模糊的目标，等于给 agent 发了一张”无限重试”的通行证。

二、缓存膨胀: 包管理器与构建系统

第二大头是缓存。Agent 在帮你装依赖、跑构建时，会大量触发包管理器和构建工具的缓存写入，而这些缓存默认是只增不减的:
- npm / pnpm / yarn 的全局缓存(~/.npm、~/.local/share/pnpm 等)
- pip / uv 的 wheel 缓存(~/.cache/pip)
- cargo、go、gradle、maven 的下载与编译缓存
- 各类构建中间产物(node_modules、target、build、dist)
人类开发者一个项目装一次依赖就完事，但 agent 在试错过程中可能反复切换分支、重装依赖、清了又装，缓存因此被放大好几倍。当 agent 同时维护多个仓库时，这个问题更突出——多仓库场景下缓存和产物的爆炸式增长，多仓库开发的AI困境: 如何实现从设计稿到多库代码的全链路自动化里也提到过类似的工程复杂度。

三、日志与会话历史: 看不见的稳定增长

第三条路径增长不快，但持续且隐蔽:
- agent 自己的运行日志、调试日志
- 每一次会话、每一轮对话的上下文快照、历史记录
- 工具调用的 trace、token 计量、请求/响应留档
单条日志可能就几 KB，但 agent 是高频调用的，几万次调用累积下来体量很可观。尤其是开了 verbose / debug 模式后，日志体量可能翻几倍。如果你在做批量任务——比如像 Claude Code 实战: 20篇顶会文献瞬间总结那种成规模的处理——日志和上下文留档的增量就更明显。顺带一提，盯着 token 消耗的同时也该顺手看一眼盘，很多人只盯额度不看磁盘，这是个盲区，相关的额度监控思路可参考开源工具: 开发者推出 Windows 版 Codex 额度监测应用。

四、容器与沙箱镜像堆积

如果你让 agent 在容器或沙箱里跑——这本身是个好习惯——那要警惕镜像和卷的堆积。Docker 这类运行时的悬空镜像(dangling image)、停止但未删除的容器、匿名卷、构建缓存层，全都占盘，而且默认不会自动回收:
- 反复 build 产生大量中间镜像层
- 跑完没清理的临时容器
- 匿名卷(anonymous volume)残留数据
一个中等规模项目反复构建,Docker 相关占用涨到两位数 GB 是常态。这恰恰是用沙箱换来安全的代价——隔离越彻底，留下的”壳”越多。关于在隔离环境里跑 agent 的配置思路，打造专属 AI 渗透测试助手: 详解 Codex CTF 模式配置与工作流给了一个把 Codex 关进受控环境的实例。

五、误装、误下载与”善意的”批量操作

最后一类是 agent 的”好心办坏事”。它在尝试解决问题时，可能:
- 下载了体积巨大的数据集 / 模型权重 / 二进制
- 把整个依赖树装进项目本地而非全局
- 生成了大量它认为”有用”的样例、fixture、mock 数据
这类操作单看每一步都合理，合在一起就是磁盘黑洞。它和工具本身的稳定性无关，更多是 agent 自主性的副作用——而当工具同时出现”降智”或异常重试时，副作用会被放大，社区对这种性能波动的讨论可见开发者反馈主流 AI 编程工具性能降智，寻找 Claude Code 及 Codex 替代方案。

复现与排查: 命令照着敲

理解了机理，排查就有方向了。核心原则一句话: 先量后猜，从大到小。下面是一套通用流程，命令都是标准 shell 工具，不依赖任何 Codex 专属子命令。

第一步: 看整体，分区还剩多少

任何磁盘排查都从这一步开始。先确认是哪个分区满了:
```
# 看所有挂载点的占用，-h 人类可读
df -h

# 只看根分区和 home，关注 Use% 列
df -h / /home

# 如果是 inode 被占满(海量小文件场景)，Use% 看着不满但仍报 No space
df -i
```
注意第三条: 如果 agent 生成了海量小文件(典型是失控循环留下的碎片)，可能空间没满但 inode 先耗尽，照样报 No space left on device。这是个经典陷阱。

第二步: 定位大目录，从根往下挖

确定了是哪个分区，接下来从该分区的根开始逐层下钻，找出占用大头:
```
# 列出当前目录下各子目录的总大小，按可读单位
du -sh ./* 2>/dev/null

# 更实用: 排序，把最大的几个揪出来
du -h --max-depth=1 . 2>/dev/null | sort -rh | head -20

# 直接锁定家目录里的隐藏缓存(大头常在这)
du -sh ~/.cache ~/.npm ~/.local 2>/dev/null
```
如果系统里有 ncdu，强烈推荐用它，比反复敲 du 直观得多——可以交互式进出目录，按大小排序，当场删:
```
# 没装就先装(任选其一)
# brew install ncdu   /   apt install ncdu

# 扫描整个家目录，交互式浏览
ncdu ~

# 扫描指定分区
ncdu /
```
第三步: 锁定缓存、日志、临时文件

根据前面的根因分析，重点检查这几类目录:
```
# 包管理器缓存
du -sh ~/.npm ~/.cache/pip ~/.cargo ~/Library/Caches 2>/dev/null

# 项目内的构建产物(在项目根跑)
du -sh node_modules target build dist .next .turbo 2>/dev/null

# 系统临时目录
du -sh /tmp /var/tmp 2>/dev/null

# 找出最近被频繁写入的大文件(1GB 以上)
find ~ -type f -size +1G 2>/dev/null -exec ls -lh {} ;
```
最后那条 find 很关键: 它能直接把”谁是那个几十 GB 的胖子”揪出来。配合 -mmin -60(最近 60 分钟修改)还能判断是不是当前正在跑的 agent 写的。

第四步: 容器和镜像占用

如果用了 Docker，单独查一遍:
```
# 看 Docker 各类对象的占用总览
docker system df

# 详细到每个镜像/容器/卷
docker system df -v
```
docker system df 会清楚告诉你镜像、容器、卷、构建缓存各占多少，以及有多少是”可回收”(reclaimable)的。

第五步: 实时盯着它写

如果 agent 还在跑，你怀疑它正在疯狂写盘，可以实时观察:
```
# 每 2 秒刷新一次某目录的大小，看它涨不涨
watch -n 2 'du -sh ~/.cache 2>/dev/null'

# 看哪个进程在猛写磁盘(Linux，需要 root)
sudo iotop -o

# macOS 下用 fs_usage 跟踪文件系统调用
sudo fs_usage -w -f filesys | grep -i codex
```
看到写入速率异常、目标目录持续膨胀，基本就能确认是失控循环了。这时候第一动作是停掉 agent，而不是急着删文件——边删边写是白费功夫，你删掉的空间它转头又写回来，还可能因为文件被占用而引发更难解释的报错。先按下暂停键，让现场静止下来，再从容排查，这是所有线上故障排查的通用纪律，对 agent 同样适用。

修复与预防: 给 agent 划清边界

排查是止血，预防才是治本。这类问题的根治思路只有一句: 不要让一个能写盘的循环在没有边界的情况下自由奔跑。具体落到四个层面。

一、清理: 安全地把空间拿回来

确认了大头之后，按”可再生 / 不可再生”分类清理。缓存、构建产物、悬空镜像都是可再生的，删了顶多下次重新生成，可以放心清:
```
# 包管理器缓存(都能安全清，会自动重建)
npm cache clean --force
pip cache purge
# pnpm store prune / yarn cache clean / cargo cache 同理

# Docker: 清掉悬空镜像、停止的容器、未用网络和构建缓存
docker system prune
# 更狠(连未被引用的卷也清，确认数据不要再用)
docker system prune -a --volumes

# 手动删项目构建产物
rm -rf node_modules dist build .next
```
铁律: 删之前一定先用前面的命令确认目录内容是可再生的。不要对着 du 的输出无脑 rm -rf，尤其别碰 ~/.config、~/.ssh、数据库目录、还有你不认识的 dotfile。

二、边界: 审批模式与沙箱隔离

这是最有效的预防手段。这类 agent 通常都提供审批 / 确认模式——让它在执行写文件、删文件、跑命令前先问你一句。在做不熟悉或体量大的任务时，把自动批准关掉、改成手动确认，能拦下绝大多数失控操作。

更进一步是沙箱隔离: 把 agent 关进容器或受限环境里跑，给它一个独立的、容量有上限的工作目录。这样即使它写疯了，炸的也是沙箱，不会波及主系统。如何在隔离环境里跑 agent，可以参考前面提到的 Codex CTF 模式配置与工作流，思路是通用的。多工具统一管理配置、把边界设置固化下来，开源工具 SMRmanager: 一键统一管理 Claude、Cursor 等 AI 编程工具配置是个可参考的方向。

三、限额: 给磁盘上硬上限

光靠 agent 自觉不够，系统层面也该设硬限制，这样无论循环多失控都有天花板:
```
# 方案 A: 用独立分区/卷给 agent 的工作目录，容量物理隔离

# 方案 B: Docker 跑 agent 时限制容器可写层和卷大小
docker run --storage-opt size=10G ...   # 视存储驱动支持情况

# 方案 C: Linux 上用 quota 给某个用户/目录设磁盘配额
# 方案 D: 临时目录挂 tmpfs 并限制大小，写满即报错而非吃光真实磁盘
```
核心是: 宁可让它因为超限而报错失败，也别让它把整个磁盘吃光。报错你能立刻发现并修，磁盘吃光是连锁灾难。

四、监控: 不要等到报错才发现

最后，加一层主动监控。最简单的是一个定时检查脚本，磁盘超过阈值就告警:
```
# 一个极简的磁盘水位告警，可挂 cron 每 10 分钟跑一次
USAGE=$(df / | awk 'NR==2 {print $5}' | tr -d '%')
if [ "$USAGE" -gt 85 ]; then
  echo "磁盘告警: 根分区已用 ${USAGE}%" # 接入你的通知渠道
fi
```
把它和你已有的资源监控放一起。很多人已经在盯 token 和额度消耗了——比如实测分享: Codex55 省 Token 配置方案和实测避坑: 阿里云 Token Plan 难以支撑 AI 编程，3小时消耗 50% 额度都在讲怎么把消耗控制住——磁盘水位完全可以挂进同一套看板，多盯一个指标而已。

相关阅读

如果你在系统性地搭建本地 AI 编程工作流，这几篇能帮你把”边界”和”选型”想得更清楚:
- 选型上先搞清楚各家 agent 的脾气和额度逻辑: Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选，以及聚焦额度成本的 Codex vs Cursor 额度对比: 价格、限制与选型建议。
- 想了解多个 agent 协同时的复杂度(协同越多，写盘和缓存的来源也越杂): 开发者构建多智能体协作流: 用 GPT Pro 指挥 Claude Code 与 Codex。
- 遇到 agent 运行中断、会话异常这类”过程态”故障，排查思路和本文同源(先复现、再定位、后修复): Codex CLI MCP 服务器 logout 吞 session: 复现与修复。
- 报错定位的通用方法论可以横向迁移: AI_ProviderSpecificError 报错定位与修复: AI SDK 排错。
- 工具配置散乱本身就是隐患来源，统一管理的讨论: 开发者吐槽 Claude Code 配置混乱: pi 的模块化管理被指更胜一筹。
FAQ

Q1: Codex 真的会把硬盘”烧坏”吗?

不会。”烧”是个比喻，指的是磁盘空间被异常占满，以及极端循环下的高频写入。现代 SSD 的写入寿命很高，正常使用一个失控的 agent 跑几天，远达不到损耗硬件的程度。真正要担心的是分区写满引发的系统故障，而不是物理损坏。

Q2: 我的项目目录就几百 MB，那几十 GB 到底在哪?

大概率在你不会主动打开的地方: 包管理器缓存(~/.cache、~/.npm)、Docker 镜像和卷、agent 的日志与会话历史、/tmp 临时文件、构建中间产物。用 ncdu ~ 或 du -h --max-depth=1 / | sort -rh 从根往下挖，几分钟就能定位。

Q3: 清理缓存和镜像会不会丢数据 / 弄坏环境?

缓存、悬空镜像、构建产物都是可再生资源，删了下次自动重建，不会丢业务数据。但 docker system prune -a --volumes 里的 --volumes 会删未引用的卷，如果你有数据存在匿名卷里要先确认。原则: 只清你能解释清楚”删了会重建”的东西。

Q4: 怎么从根上避免再次发生?

四件套: 大任务开手动审批模式、把 agent 关进沙箱/独立分区、给磁盘设硬配额(超限报错而非吃光)、挂一个磁盘水位告警。本质是给”会写盘的循环”加上外部边界，别指望 agent 自己收敛。

Q5: agent 正在疯狂写盘，我该先删文件还是先停它?

先停 agent。边删边写是白费力气，而且在它还在跑的时候删它正在用的文件可能引发更怪的错误。停掉之后再按”看占用 → 定位 → 清理”的顺序慢慢来。

结语

把 Codex 这类 agent 想象成一个不知疲倦、但也不知节制的实习生: 你给方向，它给产出，但它不会自己关水龙头。磁盘占用异常从来不是某个工具的 bug，而是”自主写盘”这件事本身的代价。划好边界、设好上限、留个监控，它就是利器; 放任不管，它就替你把盘喂满。
1天前

事件分析

相关推荐

抢沙发

评论前必须登录！

置顶推荐

前沿哨所

Agent Skill 跨工具复用: 目录结构、版本管理与团队共享

TL;DR: 多工具时代, skill 不该各管各的

一、Agent Skill 的本质: 为什么它能跨工具

1.1 Skill 不是插件, 是”可被加载的专业知识包”

1.2 渐进式加载: description 是检索入口, 不是装饰

1.3 为什么”纯文本 + 脚本目录”是可迁移的最大公约数

二、标准化目录结构: 一份 skill 长什么样

三、一份 skill 源, 多工具复用

3.1 方案 A: 软链接 (symlink)——最轻, 适合单人多工具

3.2 方案 B: git submodule——适合多仓库、需要钉版本

3.3 方案 C: 同步脚本——工具不认软链时的兜底

四、版本管理: 用 git 把 skill 当代码养

4.1 skill 仓库本身就该是个 git 仓库

4.2 语义化版本: 给 skill 打 tag

4.3 CHANGELOG: 让”为什么这么改”留痕

五、跨工具迁移: 差异点在哪里, 怎么处理

5.1 frontmatter / 元数据格式差异

5.2 触发机制差异: 自动检索 vs 显式调用

5.3 脚本运行环境差异

5.4 能力边界差异

六、团队共享: 从个人资产到协作流程

6.1 集中仓库 + PR 流程

6.2 安全审查: skill 也是攻击面

6.3 文档即接口: README + 触发词索引

6.4 复用的边界: 不是所有东西都该做成共享 skill

七、相关阅读

八、FAQ

Q1: skill 用 markdown 写, 不会因为太”软”而不可靠吗?

Q2: 我只用一个工具, 还有必要搞这套吗?

Q3: openclaw、hermes 这类工具的 skill 格式和 Claude Code 不一样, 怎么共享?

Q4: 软链、子模块、同步脚本, 到底用哪个?

Q5: 团队里怎么防止有人引入有问题的 skill?

九、结语

从“模型坍塌”到“人类退化”：开发者反思 AI 对创造力的侵蚀

事件分析

AI编程实战：非开发人员利用 Claude 耗时 10 天开发出首个 macOS 应用

事件分析

1M 上下文已经可用: Claude、Gemini 与编程 Agent 怎么选

一、TL;DR：1M 上下文到底意味着什么

100 万 token 大概是多少

一句话工程判断

二、各家可用性盘点（定性，不报精确数字）

Claude：长上下文检索质量是强项

Gemini：超长窗口铺得最早、最广

编程 Agent / Codex：窗口大小≠Agent 好用

定性对比一张表

三、真实成本与”长上下文衰减”陷阱

成本：token 几乎是线性涨的

延迟：窗口越满，首字越慢

衰减：lost in the middle，长上下文的”中间遗忘”

四、什么场景该用大窗口、什么场景用 RAG 更划算

适合直接用大窗口

适合用 RAG / 检索

决策表

五、对编程 Agent / Claude Code / Codex 的影响

整库理解成为可能，但 Agent 仍在做减法

上下文管理 = 长项目的真正分水岭

多 Agent 协同会放大上下文成本

给工程师的落地建议

六、相关阅读

七、FAQ

八、结语

CLAUDE.md 怎么写: 提升 Claude Code 准确率的最小有效配置

为什么一个文本文件能改变准确率

TL;DR

机理：这其实是一道上下文工程题

一个有效的 CLAUDE.md 该有哪些块

块一：项目是什么（一两句话定位）

块二：项目结构（只标关键目录，不复述文件树）

块三：关键命令（构建、测试、lint）

块四：代码风格与约定

块五：做什么 / 不做什么（红线）

块六：按需加载的子文档索引

目录约定与分层：根 CLAUDE.md 不是唯一一份