# 跨平台兼容

在 macOS、Windows、Linux 或 CI 上运行或安装本 Skill 时使用本参考。

## 兼容性摘要

| 项目 | macOS | Linux | Windows |
| --- | --- | --- | --- |
| `SKILL.md` 工作流 | 支持 | 支持 | 支持 |
| `project_inventory.py` | Python 3.9+ 支持 | Python 3.9+ 支持 | Python 3.9+ 支持 |
| Python 依赖 | 仅标准库 | 仅标准库 | 仅标准库 |
| 路径处理 | `pathlib` | `pathlib` | `pathlib` |
| shell 依赖 | 脚本无依赖 | 脚本无依赖 | 脚本无依赖 |
| 生成 Markdown 路径 | POSIX 风格相对路径 | POSIX 风格相对路径 | POSIX 风格相对路径 |

脚本故意使用带 `/` 分隔符的仓库相对路径，使生成 Markdown 在跨平台、GitHub URL 和 RAG metadata 中更稳定。

## Python 调用

macOS 和 Linux 通常使用：

```sh
python3 skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
```

Windows PowerShell 通常使用：

```powershell
py -3 skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
python skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
```

CI 应优先使用明确的 Python：

```sh
python -m py_compile skills/project-knowledge-builder/scripts/project_inventory.py
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --json
```

## 命令替换

| 任务 | macOS/Linux | Windows PowerShell |
| --- | --- | --- |
| 列出文档 | `find docs/project-knowledge -type f \| sort` | `Get-ChildItem docs/project-knowledge -Recurse -File \| Sort-Object FullName` |
| 搜索占位符 | `rg -n "TODO|TBD" docs/project-knowledge` | `rg -n "TODO|TBD" docs/project-knowledge` |
| 查看 git 状态 | `git status --short` | `git status --short` |
| 删除临时输出 | `rm -rf ./kb-inventory` | `Remove-Item .\kb-inventory -Recurse -Force` |

优先使用 `rg`。如果环境中没有 `rg`，使用该平台可用的搜索工具。

## Skill 示例中应避免

- 在应支持 Windows 的命令中写死 `/tmp` 路径。
- 在面向用户的说明中只给 POSIX 命令链，例如 `cmd1 && cmd2`，而不给 PowerShell 等价方式。
- 假设 shell glob 在 zsh、bash、PowerShell、cmd 中行为一致。
- 依赖 shebang 可执行行为的 Python 用法；Windows 用户应调用 `py -3 script.py`。

## 已知限制

- Java endpoint 提取基于正则，故意保持保守。它不会完整解析常量、组合注解或继承的 controller mapping。
- SQL 表提取查找 `CREATE TABLE`；动态创建的表或其他迁移 DSL 需要人工文档化。
- 前端路由提取会扫描 route-like 字面量和 view 文件；运行时由 API 生成的路由仍需要后端菜单/权限数据或数据库导出。
- 超大仓库可能需要调整 `--max-files`，或增加忽略目录。