区分工具目录和项目目录

以下示例与示意结果由本站编写，用于说明方法，不是模型实测结果。

使用场景

已安装的品牌工具代码在 tools/brand/，要读取 shop项目的docs/brand-guidelines.md并生成assets/design-tokens.json。若切换到工具目录运行，依赖cwd的脚本可能把项目数据读写到安装包。

具体做法

记录工具根与项目根，检查辅助程序的输入输出解析契约和可信来源。将脚本相对路径解析成工具根下的完整路径，保持cwd为shop项目根；若工具支持显式项目参数则按其契约传入。执行前列出实际输入输出绝对路径，先预览并检查既有令牌来源；有冲突时处理项目的替换意图，不能用force掩盖。执行后核对产物所在项目及日志。

反例

同步shop品牌令牌：先cd到tools/brand，再运行scripts/sync-brand-to-tokens.cjs。缺文件就新建，检测冲突就加force。

改进写法

同步shop品牌令牌前确认辅助程序可信及路径契约。使用工具根解析脚本完整路径，cwd保持shop根；列出品牌文档与令牌的解析位置，先预览已有来源。冲突时报告需处理的具体文件，获得替换范围后才写入；核对实际产物位置。

为什么这样改

代码安装位置与数据工作位置承担不同角色。把它们显式分开能避免cwd变化悄悄改变输入和输出；预览路径还能暴露工具自己向上寻找项目根的行为。

如何验证

教学记录应显示script位于tools/brand、cwd位于shop，input和output都位于shop。缺少品牌文档时应报错；存在令牌来源时应显示冲突，而不是在工具包内补建项目文件。检查安装目录前后哈希以发现意外写入。

适用边界

不同脚本可能以cwd、参数、配置文件位置或向上搜索结果为基准，不能把一个脚本契约套给所有工具。根分离不是权限或路径隔离；符号链接、相对输出和子进程还需检查。预览与force选项均不授予任意覆盖权限。