部署自检要检查 workspace：一次路径问题的排查与 Python 实现

整理 AI 校园活动策划助手的部署说明时，我关注到一个容易误判的细节：自检命令检查的究竟是源码仓库，还是应用实际使用的 workspace？两者都有 skills、知识库和输出目录时，只看相对路径，很容易得到一个让人放心却没有覆盖部署目标的结果。

本文记录文档静态对照和一个独立 Python 小工具的实现。没有在 Windows 或真实 WorkSwarm 部署上运行验收；下面的自动化测试在 Linux 的临时目录中完成，演示报告使用明确标注的模拟数据。

一、先确认检查对象

部署通常包含两个位置：代码下载到的仓库目录，以及运行时读取配置、Skill 和知识库的 workspace。假设命令在仓库根目录执行，skills/risk-advisor/SKILL.md 存在，只能证明仓库中的文件存在；如果运行时 workspace 没有这个文件，应用仍可能无法找到对应 Skill。

对照部署指南的运行目录与 Windows 自检片段后，我把这个差异整理成了文档 Issue，包含静态复现条件与修改建议：

Windows 自检应检查 WorkSwarm workspace，而不是当前仓库目录

这类问题的排查顺序可以很简单：先确认运行配置指定的 workspace，再确定每条相对路径的基准，最后查看实际缺少的是哪个文件或目录。

二、让路径基准成为显式参数

我用 Python 标准库实现了一个独立自检工具。入口接受 --workspace，先把目标目录转成绝对路径。配置中的相对路径统一基于这个目录解析；绝对路径保留原义，不依赖启动命令所在位置。

核心思路如下，代码为本文工具的独立实现：

from pathlib import Path

def configured_path(workspace, value):
    root = Path(workspace).expanduser().resolve()
    if not isinstance(value, str) or not value.strip():
        return None
    path = Path(value).expanduser()
    return path if path.is_absolute() else root / path

target = configured_path(
    "/demo/.workswarm/agent/workspace",
    "skills/risk-advisor/SKILL.md",
)
print(target)

这里的 /demo 是演示路径，实际使用时应替换为自己的运行目录。这个函数只负责路径解析，文件是否存在还需分别用 is_file() 或 is_dir() 判断。

三、检查配置，也检查失败时的表现

工具当前检查 workspace、config.json、五个 Skill 的 SKILL.md、四个角色配置的知识库文件和输出目录。它面向校园活动策划助手的目录结构，不会自动识别任意 WorkSwarm 项目。

读取 JSON 后，还需要确认顶层是对象。合法 JSON 不一定是配置对象，例如 [] 可以成功解析，却不能直接按字典读取字段。实现中将这种情况记录为失败检查项，避免只留下一个堆栈信息。

默认输出文本；--json 便于脚本读取；只有显式传入 --html report.html 才写入静态报告。退出码为 0 表示所有已执行的路径检查通过，存在缺失项时返回 1。默认检查流程不访问网络，也不修改 WorkSwarm 配置。

四、验证最容易误判的边界

本次运行了 5 项标准库 unittest，全部通过，覆盖：

1. 检查结果与命令的当前工作目录无关。
2. 源码仓库有文件，不能掩盖目标 workspace 尚未部署。
3. 缺失单个 Skill 时能定位到该项。
4. 顶层为数组的配置形成失败结果，不抛出未处理异常。
5. HTML 报告对文件名和说明做转义。

测试创建的 PDF 文件仅用于存在性判断，没有解析 PDF 内容。报告页面也只展示路径检查结果，不验证模型 API、凭证、依赖版本或完整多智能体工作流。即使所有项目显示通过，也不能据此宣称整个应用已验收。

这次实践让我把“检查对象”和“检查范围”分开写清楚：前者决定结果是否对应实际部署，后者决定一个绿色勾选究竟能说明多少问题。工具和本文由 AI 辅助编写，测试结果与尚未覆盖的平台均如实列出。