# 安装与运行 codexqa

[English](GETTING_STARTED.md)

面向搜索引擎的 HTML 文档：[openqa.cn](https://openqa.cn/)。本页是 GitHub 源文。

在 Cursor、Claude Code、Codex 或 OpenClaw 上一次只装一个 skill。本页以 [`codexqa-defect-analyzer`](../skills/codexqa-defect-analyzer/README.zh-CN.md) 为例，因为它有可冒烟的 CLI。同一条命令也可以加 `--skill codexqa-skill-router`、`--skill codexqa-code-analyzer`、`--skill codexqa-change-analysis`、`--skill codexqa-code-wiki`、`--skill codexqa-rootcause-analyzer`、`--skill codexqa-code-reviewer`、`--skill codexqa-requirement-analyzer`、`--skill codexqa-testcase-generator`、`--skill codexqa-testdata-generator`、`--skill codexqa-jev-browser`。不确定装哪个时优先 [`codexqa-skill-router`](../skills/codexqa-skill-router/README.zh-CN.md)——它能匹配并按需拉取干活 skill。`codexqa-code-analyzer`、`codexqa-change-analysis`、`codexqa-code-wiki`、`codexqa-rootcause-analyzer` 与 `codexqa-code-reviewer` 使用单独的 `codexqa` 符号图 CLI；`codexqa-defect-analyzer` 由 Python 编排，实图同样使用该 CLI；`codexqa-skill-router` 的发现/按需安装需要 Python 3.10+；`codexqa-jev-browser` 用自带的 TypeScript CLI 驱动 Playwright Chromium。

每个 skill 要交的材料不一样（[FAQ](FAQ.zh-CN.md#每个-skill-要我交什么)）。跑完长什么样见 [README · 所有技能SKILL概览](../README.zh-CN.md#所有技能SKILL概览)。

## 环境要求

需要 Node.js、npm/npx、Git，以及能够读取 skill 文件并执行命令的 Coding Agent。`codexqa-code-analyzer`、`codexqa-change-analysis` 和 `codexqa-code-wiki` 要求 Node.js 18 或更高版本；`codexqa-jev-browser` 要求 Node.js 20 或更高版本。`codexqa-testcase-generator` 要求 Python 3.10+（经该 skill 的 `scripts/tcg-python` 调用）。`codexqa-defect-analyzer` 的 Python 流水线在本地与 CI 以 Python 3.11 验证；部分历史 TypeScript 冒烟仍可能需要：

```bash
python3 --version   # 3.10+；codexqa-defect-analyzer / codexqa-testcase-generator 推荐 3.11
export NODE_OPTIONS=--experimental-strip-types
node --version
npx --version
git --version
```

这个环境变量要设在**实际执行 Agent CLI 命令的那个 shell** 里。桌面版 Agent 不一定继承你另开的终端的环境。如果某条 `.ts` 命令报 `ERR_UNKNOWN_FILE_EXTENSION`，就去查那条命令用的 Node 版本和环境。上面的写法会覆盖已有的 `NODE_OPTIONS`，需要保留的选项请自己拼上。

分析过程可能尝试安装 Semgrep（Python/pip 或 Homebrew）和 GitNexus（npm/pnpm）。打包测试还需要 Bash、rsync、zip 和 unzip。联网与数据行为见 [FAQ](FAQ.zh-CN.md)。

## 从 GitHub 安装

```bash
npx skills add openqa-cn/codexqa --skill codexqa-defect-analyzer
```

按提示选择 Agent。默认安装范围是当前项目。为 Codex 跨项目安装：

```bash
npx skills add openqa-cn/codexqa --skill codexqa-defect-analyzer --agent codex --global
```

想要复制而不是软链到 Agent 目录，加 `--copy`。安装位置由第三方 `skills` 安装器决定，看它的输出找已安装目录。**装得上不等于在那个 Agent 上能跑完整分析。**

## 本地验证

推送前，先不安装、只列出本地可用的 skill：

```bash
npx skills add . --list
```

要把当前 checkout 装上，在仓库根目录运行：

```bash
npx skills add . --skill codexqa-defect-analyzer --agent codex --copy
```

只做 CLI 冒烟，不需要模型也不需要私有平台：

```bash
python3 skills/codexqa-defect-analyzer/scripts/run_scan.py --help
(cd skills/codexqa-defect-analyzer && npm test)
```

冒烟套件验证样例计划加载、任务创建和材料缺失时的处理。里面的 `acme` 仓库地址是样例数据，这个测试不会去克隆它们。想看一组「正常实现 + 预置缺陷」的对照，跑[边界案例](../examples/checkout-boundary/README.md)。

## 启动审查

安装后新建会话。给出可访问的仓库 URL 和分支，以及你能提供的需求或测试用例。可以直接这么说：

> 用 codexqa-defect-analyzer 审查我的仓库 REPOSITORY_URL，分支 BRANCH_NAME。对照这些需求检查改动实现：REQUIREMENTS。每个疑似缺陷给出代码位置、触发条件和依据。

把大写占位符换成真实内容。流程跑通的话，你会拿到一个任务、若干分析记录和一个报告链接。接受报告前，先确认有没有服务没跑完、工具不可用。疑似发现一律留给人复核，不是自动合并决定。

## 更新与卸载

用第三方安装器自己的帮助确认当前可用选项：

```bash
npx skills --help
npx skills list
npx skills update
npx skills remove codexqa-defect-analyzer --agent codex
```

全局安装在支持的地方加 `--global`。更新或删除已安装目录前，先备份配置和任务数据。默认 skill 把数据存在自己的安装目录里，**更新不能当备份手段用**。

## 其他已发布 skill

```bash
npx skills add openqa-cn/codexqa --skill codexqa-code-analyzer
npx skills add openqa-cn/codexqa --skill codexqa-change-analysis
npx skills add openqa-cn/codexqa --skill codexqa-code-wiki
npm install -g @openqa-cn/codexqa

npx skills add openqa-cn/codexqa --skill codexqa-skill-router
npx skills add openqa-cn/codexqa --skill codexqa-rootcause-analyzer
npx skills add openqa-cn/codexqa --skill codexqa-code-reviewer
npx skills add openqa-cn/codexqa --skill codexqa-requirement-analyzer
npx skills add openqa-cn/codexqa --skill codexqa-testcase-generator
npx skills add openqa-cn/codexqa --skill codexqa-testdata-generator
npx skills add openqa-cn/codexqa --skill codexqa-jev-browser
```

`codexqa-code-analyzer`、`codexqa-change-analysis`、`codexqa-code-wiki`、`codexqa-rootcause-analyzer`、`codexqa-code-reviewer`、`codexqa-defect-analyzer` 与 `codexqa-skill-router` Skill 发布在本仓库中；`@openqa-cn/codexqa` 是单独分发的闭源本地代码分析引擎，索引和会话写在 `~/.codexqa/`。详见 [`codexqa-code-analyzer` 已知边界](../skills/codexqa-code-analyzer/KNOWN_LIMITATIONS.zh-CN.md)、[`codexqa-change-analysis` 已知边界](../skills/codexqa-change-analysis/KNOWN_LIMITATIONS.zh-CN.md)、[`codexqa-code-wiki` 已知边界](../skills/codexqa-code-wiki/KNOWN_LIMITATIONS.zh-CN.md)、[`codexqa-rootcause-analyzer` 已知边界](../skills/codexqa-rootcause-analyzer/KNOWN_LIMITATIONS.zh-CN.md)、[`codexqa-code-reviewer` 已知边界](../skills/codexqa-code-reviewer/KNOWN_LIMITATIONS.zh-CN.md)、[`codexqa-defect-analyzer` 已知边界](../skills/codexqa-defect-analyzer/KNOWN_LIMITATIONS.zh-CN.md) 和 [`codexqa-skill-router` 已知边界](../skills/codexqa-skill-router/KNOWN_LIMITATIONS.zh-CN.md)。

只做 `codexqa-code-analyzer` / `codexqa-code-wiki` 冒烟时不需要模型：给本地 checkout 建索引，再查看摘要。

```bash
codexqa --help
codexqa index /path/to/repo
codexqa stats /path/to/repo
codexqa wiki inputs /path/to/repo --kind architecture --limit 8
```

`--help` 应列出 CLI 命令；成功的 `stats` 应显示已索引的文件、符号和语言。审变更时要用 `--diff-base <ref>` 重新建索引；没有 diff 基线时，符号的变更状态都是 `default`，没有可审的变更集。`wiki inputs` 应打出社区 / digest JSON，不调模型。

安装后新建 Agent 会话并指向该 skill。输入各不相同：

- `codexqa-skill-router` 需要待路由的用户请求（以及 Python 3.10+）。它对照内置/现场目录匹配，并可运行 `ensure_skill.py` 把干活 skill 拉到路由旁边。见其 [README](../skills/codexqa-skill-router/README.zh-CN.md)。
- `codexqa-code-analyzer` 需要本地仓库。审变更时用 `origin/main` 等基线建索引；索引写在 `~/.codexqa/`。见其 [README](../skills/codexqa-code-analyzer/README.zh-CN.md)。
- `codexqa-change-analysis` 需要本地仓库和一个 git 基线（如 `origin/main`）。它在仓库根目录写一份 HTML 变更影响报告，并为未覆盖的点新增测试文件，不改已有测试。见其 [README](../skills/codexqa-change-analysis/README.zh-CN.md)。
- `codexqa-code-wiki` 需要本地仓库；它的 `brief` 步骤会自动建索引。产出是一页 HTML 架构 Wiki，不审变更。见其 [README](../skills/codexqa-code-wiki/README.zh-CN.md)。
- `codexqa-rootcause-analyzer` 需要异常证据（堆栈 / 日志 / dump），外加 git 地址、本地目录、文件，或已打开的工作区。见其 [README](../skills/codexqa-rootcause-analyzer/README.zh-CN.md)。
- `codexqa-defect-analyzer` 需要对 diff / 仓库 / 上传 / 粘贴做代码风险扫描。见其 [README](../skills/codexqa-defect-analyzer/README.zh-CN.md)。
- `codexqa-code-reviewer` 需要本地 checkout、`PATH` 上的 `codexqa` + `jq`，以及（PR 模式）`--diff-base`。见 [codexqa-code-reviewer README](../skills/codexqa-code-reviewer/README.zh-CN.md)。
- `codexqa-requirement-analyzer` 需要需求文档，不要交仓库。见 [README · 你要交什么](../skills/codexqa-requirement-analyzer/README.zh-CN.md#你要交什么)。
- `codexqa-testcase-generator` 需要本地需求材料（文件、目录、粘贴，或本轮 HTTPS 文档 URL）。可选知识目录 / Git URL。Exec 后产物在 `testcase/cases/` 与 `testdesign/testcase_generation_report.html`。冒烟：在 skill 目录执行 `./scripts/tcg-python scripts/close_stage.py --self-check`（以及 `check_run_gate.py` / `generate_case_report.py --self-check`）。见其 [README](../skills/codexqa-testcase-generator/README.zh-CN.md)。
- `codexqa-testdata-generator` 需要造数请求、用例或 API 来源，**不要**丢被测源码当输入。见其 [README · 你要交什么](../skills/codexqa-testdata-generator/README.zh-CN.md#你要交什么)。
- `codexqa-jev-browser` 需要一份 UI 用例（YAML / Markdown / API），或一句自然语言目标加 URL。先在 skill 目录执行 `npm install`；现场 `auto` / `generate --goal` 还需要在 `.env` 里配置模型密钥。见其 [README](../skills/codexqa-jev-browser/README.zh-CN.md)。

对各 skill 可以直接说的话：[仓库 README · 快速开始](../README.zh-CN.md#快速开始)。

原理索引：[各 skill 的工作原理](HOW_IT_WORKS.zh-CN.md)。各 skill 要交什么：[FAQ](FAQ.zh-CN.md#每个-skill-要我交什么)。

## 排错

| 现象 | 查什么 |
| --- | --- |
| 从 GitHub 装不到这个 skill | skill 必须已提交并推送到被安装的那个仓库 |
| Agent 找不到这个 skill | 选中的 Agent、项目 / 全局安装范围，以及是否需要新开会话 |
| 报 `.ts` 扩展名无法识别 | 该命令的 Node 版本和 TypeScript stripping 环境 |
| 没有检测计划 | 补上仓库 / 分支和业务材料；降级加载成功不等于材料够 |
| 静态分析或调用图不可用 | 工具安装结果、PATH、权限和网络 |
| 找不到 `codexqa` 或图查询为空 | 安装 `@openqa-cn/codexqa`、检查 PATH、确认仓库已建索引；审变更时要加 `--diff-base`。`codexqa-code-wiki` 直接跑它的 `scripts/wiki.mjs brief`，会自动建索引并导出 |
| 本地报告链接打不开 | 直接用浏览器打开返回的 HTML 文件 |

求助时请附上 commit、Node 版本、操作系统、Agent 及版本、命令和脱敏后的报错。不要上传源码或含私有数据的任务目录。