task-intelligence - problem-catalog
2026/10/9 5:19:31
网站建设
项目流程
各领域的问题目录
技能与编排器
| 问题 | 频率 | 预防性解决方案 |
|---|
| SKILL.md 中的 YAML 无效 | 高 | python -c "import yaml; yaml.safe_load(open('SKILL.md').read())" |
YAML 中name或description重复 | 中 | 在文件中 Grep^name:— 应只有 1 处出现 |
| skill-installer 静默失败 | 中 | 使用--force并读取完整输出 |
| scan_registry.py 对 sets/dicts 的 bug | 低 | 通过 JSON 手动更新注册表 |
| 技能在 .claude 中但不在 skills/ 中 | 中 | 始终通过 skill-installer 安装，不要手动复制 |
API 与集成
| 问题 | 频率 | 预防性解决方案 |
|---|
| Token/API 密钥过期 | 高 | 执行前检查有效性 |
| 达到速率限制 | 中 | 实现带指数退避的重试 |
| 端点变更（破坏性更改） | 低 | 固定 API 版本，先检查变更日志 |
| webhook 中 HMAC-SHA256 无效 | 中 | 上线前用示例 payload 测试 |
| 硬编码凭据被提交 | 低但关键 | 强制.env+ 配置.gitignore |
文件与路径
| 问题 | 频率 | 预防性解决方案 |
|---|
| 路径不存在 | 高 | 任何操作前使用os.path.exists() |
| 权限被拒 | 中 | 使用os.access(path, os.W_OK)检查 |
| 编码错误（带重音的 pt-BR） | 高 | 始终显式使用open(f, encoding='utf-8') |
| ZIP 损坏 | 低 | 生成后使用zipfile.is_zipfile()验证 |
| 文件被其他进程占用 | 低 | 使用with显式关闭句柄 |
生态系统的 ZIP 与构建
| 问题 | 频率 | 预防性解决方案 |
|---|
| ecosystem-completo.zip 过期 | 高 | 每新增一个技能后运行 build_ecosystem.py |
| 技能编号乱序 | 中 | 分配编号前检查总数 |
| ZIP 过大（>50MB） | 低 | 排除pycache、.pyc、node_modules |
Git
| 问题 | 频率 | 预防性解决方案 |
|---|
| 提交到错误的分支 | 高 | 提交前执行git branch --show-current |
| 未提交的更改丢失 | 中 | 破坏性操作前执行git status |
| 合并冲突 | 中 | push 前执行git pull --rebase |
| 推送机密 | 低但关键 | commit 前执行git diff --staged |
Python / 脚本
| 问题 | 频率 | 预防性解决方案 |
|---|
| ModuleNotFoundError | 高 | 先执行pip install -r requirements.txt |
| Python 2 与 3 | 低 | 显式使用python3 |
| 子进程无超时 | 中 | 始终使用subprocess.run(..., timeout=30) |
| JSON 解码错误 | 中 | 显式处理json.JSONDecodeError |
| UnicodeDecodeError | 高 | 在文件中使用encoding='utf-8', errors='replace' |