Agent Skill 的路径治理：把 14 处硬编码绝对路径收敛成一个配置项

一、问题不是“改个路径”，是“把重构交给概率”

把一个多智能体面试系统（LEADER 调度总控 + 通用聊天官 + 技术面试官 + HR 面试官 + 人才测评专员）搬到华为云 AI 开发者空间时，碰到一个很典型的工程问题：仓库里的 Skills 目录，知识库与日志路径全部写死成 Windows 本地绝对路径 D:\zhishiku\...，一共 14 处，散落在 5 个 SKILL.md 里。

云上环境是 Linux，只能换成 /var/interview_Lab。于是部署说明只能写成“让 Agent 全仓替换路径，再用 grep 对账”。这意味着同一个部署动作，在不同机器上成功率不一样。

二、这类隐患的三个特征

1. 静默降级，不报错

路径不存在时，多数 Agent 的 read 工具只会返回空内容，不会抛异常。结果就是面试照常跑完，但每个 Agent 手里的“公司介绍”是空的，生成的问题模板化、评分维度缺参系。用户看到的是一个“能跑但答得不对”的系统，排查成本极高。

2. 升级冲突

路径是直接改在 SKILL.md 正文里的。上游一发新版，本地 14 处改动就要手工重做一遍；多人协作时谁改过哪几处，diff 里根本看不出来。

3. 无法回归验证

grep -rn "D:\\" Skills/ 只能证明“没有 Windows 路径了”，证明不了“每个 Agent 拿到的路径都是对的”。数量对上了，语义不一定对上。

三、改造思路：把“位置”从“知识”里抽出来

核心一句话：Skill 里不应该出现机器的物理位置。 分三层收敛：

1. 单一事实源：新建 config.yaml，只此一处写根目录；
2. 引用而非拼接：SKILL.md 里只写逻辑名（如 kb.company_profile），由加载器解析成真实路径；
3. 启动前 precheck：缺文件就当场报错，不让它跑到面试中途才暴露。

四、配置层写法

profile: cloud-linux   # 或 local-windows

roots:
  cloud-linux:
    kb: /var/interview_Lab
    log: /var/interview_Log
  local-windows:
    kb: D:\zhishiku
    log: D:\interview_Log

knowledge:
  company_profile: kb/公司介绍.pdf
  jd_template:     kb/官方招聘简章.pdf
  tech_bank:       kb/标准化岗位面试题库.pdf
  hr_bank:         kb/HR综合通用面试题库.pdf

加载器只负责把逻辑名解成绝对路径：

def resolve(name: str, cfg: dict) -> Path:
    root = Path(cfg["roots"][cfg["profile"]]["kb"])
    return root / cfg["knowledge"][name]

这样切环境只需要改 profile 一行，5 个 SKILL.md 一个字都不用动，和上游同步也不会冲突。

五、precheck：让错误在入口处就爆

REQUIRED = ["company_profile", "jd_template", "tech_bank", "hr_bank"]

def precheck(cfg):
    missing = [n for n in REQUIRED if not resolve(n, cfg).is_file()]
    if missing:
        raise RuntimeError(
            f"知识库缺文件：{', '.join(missing)}；"
            f"当前 profile={cfg['profile']}，根目录={cfg['roots'][cfg['profile']]['kb']}"
        )

关键是错误信息要带 profile 和实际根目录——这一条能省掉大部分“在我机器上是好的”类排查。

六、迁移清单

把存量项目从硬编码拉回来，按这个顺序做不踩坑：

1. 全仓 grep -rn 出所有绝对路径，先数清楚有多少处、分布在几个文件；
2. 把所有“路径字面量”归类成逻辑名，能兼容的直接改用逻辑名；
3. 新增 config.yaml 与解析函数，先用默认值跑通一个 Agent；
4. 5 个 SKILL.md 逐个改引用，每改一个跑一次 precheck；
5. 在 README 的部署步骤里加上“选 profile”这一行，删掉“批量替换路径”整段；
6. 最后用新克隆的仓库加空知识库目录跑一次，确认报错信息可读。

七、小结

多智能体系统真正难的不是 Prompt 写得好不好，而是边界清晰不清晰。知识库在哪、日志写哪里，本质是部署边界，不是 Prompt 的一部分。把边界收进配置层之后，SKILL.md 才是可分发、可升级、可回归的工程产物。路径治理看着很小，但它是 Agent 工程从“能演示”走向“能交付”过程中，性价比最高的一步改造。