昨天，我给我的 AI 助手做了一次体检
先解释一个词：工作区。
OpenClaw 这类 AI 助手在本地电脑上有一个专属目录，相当于它的「家」。项目文件放在 projects/，日常任务放在 tasks/，资料放在 knowledge/，记忆日志放在 memory/，临时文件放在 tmp/。助手每天在这里读写，产出、记忆、知识，全都沉淀在这个目录里。
昨天中午，我给我家这个跑了一个多月的助手做了一次体检。结果不算差：没有红色违规，但有 5 条黄色警告——
tmp/临时目录里躺着 465 个超过 30 天没动过的文件；
有一个任务的目录里没有进度卡（PROGRESS.md）；
另一张进度卡少了状态说明；
knowledge/根目录散落着一份不该在那里的旧文档；
知识库缺一份索引文件。
都不是大问题。花十几分钟逐条整改，复检全绿。
但真正让我在意的不是这 5 条警告本身，而是：如果不去体检，我根本不会注意到它们。工作区变乱是一个渐进的过程，像家里的工位一样，今天乱一点、明天乱一点，直到某天想找一份文件，翻半天找不到，才意识到已经乱到无从下手了。
工作区变乱，代价是什么
有人会觉得：目录乱一点而已，又不影响干活。影响的，而且比想象中大。
历史找不到。 AI 助手的记忆不在脑子里，在文件里。任务做完了，进度记在哪？上次那个问题的处理方案，写在哪份文档里？目录一乱、进度卡一缺，这些就成了大海捞针。做过的事等于没做，攒下的经验等于没攒。
重复劳动。 助手不知道某件事以前做过，于是重新做一遍。浪费的不只是时间，还有上下文——AI 助手一次会话能处理的信息量有限，每份重复产出都在挤占真正重要的内容。
乱象会传染。 AI 助手是跟着规范走的：目录规范一旦被破坏，后面所有工具的行为都会跟着歪。一个任务目录忘了放进度卡，下一个任务就会学样；知识库没有索引，资料放进去就等于丢进黑洞——文件还在，但谁也检索不到。
一句话：工作区乱不是洁癖问题，是健康问题。人需要体检，是因为很多毛病早期没症状；AI 助手的工作区也一样，乱象在积累期悄无声息，等人注意到的时候，清理成本已经翻了几倍。
所以，需要有人定期检查。这就是今天要说的项目：xiaoyaoclaw-workspace-auditor（工作区体检），我们开源「十件套」里的第五件。
解法：给工作区配一个质检员
这个工具的定位一句话就能说清：工作区的质检员。
它只读扫描整个工作区，对照一套健康标准逐项检查，然后输出一份分级报告——🔴 红色是违规、🟡 黄色是警告、🟢 绿色是正常——每条都附修复建议。查完它把报告交给你，然后退到一边。它自己不动手修，这是设计红线，后面细说。
技术上也刻意做得轻：
零依赖：整个工具就是一个 Python 脚本（
scan_workspace.py），只用标准库，不用装任何第三方包；
纯本地：不联网、不调外部 API，你的工作区里有什么，只有你知道；
双平台：Windows 和 macOS 都能跑。
用法是一条命令：
python scripts/scan_workspace.py --root <工作区根目录> --report跑完，报告直接打在终端里。就这么简单。
五类检查，分别查什么
它体检五个方面。有意思的是，这五类正好对应十件套里的前四件——每件工具立下的规矩，由它来检查有没有被遵守：
比如目录合规查的是 initializer 立下的家规：projects/、tasks/、knowledge/ 这些标准目录在不在，根目录是不是只该放说明文件却混进了杂物。任务健康查的是 tracker 的规矩：目录即容器，每个任务目录都该有一张 PROGRESS.md 进度卡，卡片上的状态字段得合法。
这里有个设计细节值得一说：渐进式依赖，自动降级。五类检查不是绑死的——如果某个配套件套没装，对应的检查会自动跳过，并在报告里提示一句「这项需要装 xxx 才能查」，而不是报一堆假阳性吓唬你。装了几个工具，就查几项；没立过的规矩，不会拿来冤枉你。
关键设计一：分级报告，不搞一刀切
体检工具最怕什么？狼来了。
如果什么东西都报成红色违规，用户看两次就会失去信任，以后连真的红色违规也懒得管了。所以分级很重要：
🔴 违规：破坏了规则，需要处理。比如任务目录没有进度卡、标准目录缺失。
🟡 警告：建议处理，但不紧急。比如
tmp/里的超龄文件。
🟢 正常：没问题。
⏭️ 降级跳过：依赖的件套没装，这项没查。
同样是「tmp/ 里有 465 个超 30 天文件」，它报的是黄色警告而不是红色违规——因为 tmp/ 本来就是放临时文件的地方，有文件很正常，超龄只是提醒你该清一清了。要不要清、清哪些，由你决定。
阈值也可以调：--days 控制「超龄」的标准（默认 30 天），--max-file 控制大文件的警戒线（默认 50MB）。需要机器可读的结果时加 --json，方便接进自己的自动化流程。
关键设计二：只报不修，是红线不是偷懒
这个工具最特别的，可能不是它能查出什么，而是它承诺不做什么：永不修改、删除、移动任何文件。
为什么这么设计？因为破坏性操作必须由人决策。
想象一下：一个工具既能诊断、又能自动「修复」——自动删文件、自动挪目录——你省事了，但也永远要提防它判断错。删错一个目录，可能丢掉几周的记忆和产出。AI 工具的权限边界，恰恰体现在它敢不敢对自己说「不」。
所以分工是明确的：脚本只读扫描，输出报告和建议；修复动作列成清单，等你确认后自己执行，或者引导到对应的姊妹技能。比如报告说知识库有索引不到的孤儿文件，它不会自作主张去改索引，而是建议你去跑 kb-retriever 的重建脚本。
「只报不修」这四个字，就是这个工具给用户的信任状。
三步上手
Step 1：安装
clawhub install xiaoyaoclaw-workspace-auditor或者从 GitHub 手动安装：git clone https://github.com/dtsola/xiaoyaoclaw-workspace-auditor，把 SKILL.md 和 scripts/scan_workspace.py 放进你的 skills 目录。
Step 2：跑一次体检
python scripts/scan_workspace.py --root <你的工作区根目录> --reportStep 3：看报告，逐条决策
🔴 违规尽快处理，🟡 警告有空处理，每条都附了修复建议，照做即可。
想省心的话，可以把它挂进定时任务，每周自动跑一次——体检这种事，贵在定期。
写在最后
回到开头那 465 个临时文件。它们不是灾难，但如果没有体检，半年后可能是 4650 个。
AI 助手能不能长久好用，不在于起步时目录多规范，而在于乱象有没有人管。十件套里的前四件，负责把家规立好、把记忆存好、把进度记好、把资料用好；第五件 workspace-auditor 负责定期检查——这些规矩，还在不在被执行。它是这套体系里管「长期健康」的那一个：
项目是 MIT 协议，开源免费，代码在 GitHub，也可以从 ClawHub 一键安装。
如果你也在养一个 AI 助手，不妨每个月给它做一次体检。工位干净，干活才利索；工作区不乱，助手才靠得住。
dtsola — IT解决方案架构师 | 一人公司实践者
小遥项目：https://project.xiaoyaosai.com/
用户交流和反馈群
扫码加入【小遥 AI · 用户交流群】——产品反馈、使用交流、功能建议（用户专属）。
#OpenClaw #AI助手 #开源项目 #工作区管理 #效率工具 #本地优先 #Python #自动化运维 #一人公司 #人工智能
