tca-skill

本 Skill 用于在本地运行 TCA 代码分析，输出 HTML/JSON 报告，并可在扫描后基于报告进行自动修复。

触发条件

满足以下任一条件即可触发本 Skill：

• 对话触发词：用户输入包含下列关键词或类似语义
• "执行代码分析" / "帮我进行 TCA 代码分析"
• "代码扫描 / 安全扫描 / 漏洞检测"
• "检查这个项目的安全问题"
• "扫描代码漏洞 / 敏感信息 / 依赖风险"
• "扫描并修复 / 扫描后自动修复 / fix issues / 扫描并尝试修复"
• 范围限定触发：对话中出现"只扫描 xxx / 仅扫描 xxx / 不要扫描 xxx / 排除 xxx / 忽略 xxx"等范围控制语句时，需在触发扫描前设置 PLUGIN_WHITE_PATHS / PLUGIN_IGNORE_PATHS
• 修复触发：对话中出现"扫描并修复 / 扫描后自动修复 / fix issues / 扫描并尝试修复"时，扫描完成后必须按"执行步骤 - 步骤 6"中的修复流程处理

前置检查

执行扫描前仅需确认一项硬性条件：

1. Python 版本检查（必须）：执行 python3 --version，要求 ≥ 3.6（脚本以 Python 3 实现，无此版本则无法启动）

> 其余环境（Docker 是否安装/运行、git / git lfs 是否就绪、macOS Apple Silicon 是否需要 Rosetta、操作系统类型与架构）均由 scripts/tca_scan.py 启动时自动检测、自动选择执行模式（Docker 优先，不可用则回退二进制）并打印对应安装/启动指引，AI 无需手动预检；遇到具体报错再参考下文「错误处理」章节处理即可。

执行步骤

按下列顺序执行，避免跳步：

步骤 1：解析用户意图

• 识别是「仅扫描」还是「扫描并修复」
• 从对话中提取扫描范围（白名单 / 黑名单）

步骤 2：设置环境变量

根据用户需求设置以下环境变量：

过滤参数格式约定：路径需相对 PLUGIN_SOURCE_DIR，支持 * 通配符，多个条目用英文逗号分隔。

范围识别规则：
- "只扫描 / 仅扫描 / 只扫" → 写入 PLUGIN_WHITE_PATHS
- "不扫描 / 不要扫 / 排除 / 忽略" → 写入 PLUGIN_IGNORE_PATHS

步骤 3：执行扫描脚本

运行：

python3 scripts/tca_scan.py

脚本会自动选择执行方式：
- Docker 模式（优先）：检测到 Docker 可用且运行正常时，使用容器化执行
- 二进制模式（备选）：Docker 不可用时，所有平台都支持本地二进制执行

步骤 4：等待扫描完成并校验产物

检查 ${PLUGIN_SOURCE_DIR}/tca_report/ 目录下是否生成：
- HTML 报告：index.html
- JSON 报告：tca_report.json
- 扫描状态：scan_status.json（如存在，用于确认扫描是否成功）

步骤 5：汇总扫描结果

向用户输出报告路径与问题数量概览。

步骤 6（可选）：扫描后自动修复

仅在用户触发「扫描并修复」类指令时执行，按以下四步处理：

6.1 读取报告
读取 ${PLUGIN_SOURCE_DIR}/tca_report/tca_report.json，解析其中的问题列表。

6.2 问题分级

6.3 执行修复
- 对「✅ 自动修复」类：直接修改代码，每修完一个文件立即展示该文件 diff，再继续下一个
- 对「⚠️ 确认修复」类：展示修复方案，明确询问用户是否确认修复，收到确认后再修改
- 对「❌ 仅报告」类：列出问题和建议，告知需人工处理

6.4 输出修复摘要

## 修复摘要

- ✅ 已自动修复：X 个问题（列出文件和问题描述）
- ⚠️ 待确认修复：X 个问题（列出文件和问题描述）
- ❌ 需人工处理：X 个问题（列出文件和问题描述）

修复阶段注意事项：
- 修复前不需要备份文件，用户可通过 Git 回滚
- 若某个问题无法确定安全的修复方式，归入「❌ 仅报告」，不要猜测性修改
- 硬编码密钥修复时，将密钥值替换为 os.environ.get("KEY_NAME") 或对应语言的环境变量读取方式，并在文件顶部补充必要的 import

示例

示例 1：扫描当前目录

用户对话："执行代码分析"

执行命令：

python3 scripts/tca_scan.py

输出：报告生成在 ./tca_report/index.html 与 ./tca_report/tca_report.json

示例 2：扫描指定目录

用户对话："帮我扫描 /workspace/myproj 这个项目"

执行命令：

PLUGIN_SOURCE_DIR=/workspace/myproj python3 scripts/tca_scan.py

示例 3：仅扫描某些文件 / 目录

用户对话："只扫描 test.py 文件" / "只扫描 src 和 test 目录"

执行命令：

# 仅扫描单文件
export PLUGIN_WHITE_PATHS="test.py"
python3 scripts/tca_scan.py

# 仅扫描多目录
export PLUGIN_WHITE_PATHS="src/*,test/*"
python3 scripts/tca_scan.py

示例 4：排除某些文件 / 目录

用户对话："不要扫描 demo.py" / "不要扫描 lib、bin 目录"

执行命令：

export PLUGIN_IGNORE_PATHS="demo.py"
# 或
export PLUGIN_IGNORE_PATHS="lib/*,bin/*"
python3 scripts/tca_scan.py

示例 5：白名单 + 黑名单组合

用户对话："只扫描 src 和 test，但排除 lib 和 bin"

执行命令：

export PLUGIN_SOURCE_DIR=.
export PLUGIN_WHITE_PATHS="src/*,test/*"
export PLUGIN_IGNORE_PATHS="lib/*,bin/*"
python3 scripts/tca_scan.py

示例 6：扫描并自动修复

用户对话："扫描并修复" / "fix issues"

执行流程：
1. 执行 python3 scripts/tca_scan.py
2. 读取 tca_report/tca_report.json
3. 按「✅ 自动修复 / ⚠️ 确认修复 / ❌ 仅报告」三档分级处理
4. 输出修复摘要

错误处理

执行过程中可能遇到的典型错误及处理方式：

通用原则：
- 任何阶段失败，应输出明确的错误信息与下一步建议，不要静默忽略
- 修复阶段遇到不确定的问题，归入「❌ 仅报告」，不做猜测性修改
- 同一错误重试不超过 3 次，仍失败则停止并向用户报告
- 报告可能包含命中代码片段与路径，提醒用户妥善保存、避免外泄
- 修复硬编码密钥时，确认真实密钥未被提交到版本控制