amsokol/ai-devsecops-cursor
GitHub: amsokol/ai-devsecops-cursor
基于 Cursor Agent SDK 的 DevSecOps Agent 运行器，通过 agent-gate 和 agent-maintain 实现自动化 PR 审查与主干分支维护。
Stars: 1 | Forks: 0
# ai-devsecops-cursor
基于 [Cursor Agent SDK](https://cursor.com) 构建的可扩展 **DevSecOps agent**：
能力 × 范围 × 行为，组合成各种场景。
| 入口点 | 场景 | 角色 |
| ---------------- | --------------- | ---------------------------------------------------------------- |
| `agent-gate` | `pr_gate` | PR → `main`：审查 / 阻止 / 批准（**不处理** Issues 或修复 PR） |
| `agent-maintain` | `main_maintain` | 默认分支：处理 Issues、修复 PR、进行协调 |
设计文档：[`agent/DESIGN.md`](agent/DESIGN.md)。
## 设置
```
cd ai-devsecops-cursor
uv sync
# 请参阅下方的 Credentials。
export CURSOR_API_KEY="cursor_..."
export AGENT_GATE_MODEL="composer-2.5"
export AGENT_MAINTAIN_MODEL="composer-2.5"
# export AGENT_GATE_GH_TOKEN="ghp_..." # classic `repo`，可选（解析 threads）
# export GH_TOKEN="..." # 仅限本地 `gh`；CI 使用 github.token
# export AGENT_SCM=github # 默认值；针对 GitLab 时使用 gitlab
```
编辑 `targets.yaml`，使 `path` 指向本地检出目录（默认同级
`../app-tauri-react-shadcn-ui`）。该文件**仅限本地使用**。
源代码管理是可插拔的（`agent.scm`）：使用 `--scm github|gitlab` 或 `AGENT_SCM`。
特定平台的 CLI/token 描述会被注入到 prompt 中；位于
`.cursor/agent/` 下的产品策略保持平台中立（`library/gate/change-review.md`）。
## CI
| 事件 | 任务 | 命令 |
| ------------------------------------------------ | -------------------------- | ------------------------------------------------------- |
| `pull_request` (打开/同步/重新打开) | **Agent gate (PR 审查)** | `agent-gate` ship |
| 人工 PR 评论 (对话或审查线程) | **Agent gate (PR 审查)** | `agent-gate` ship (取消该 PR 正在进行的运行) |
| `push` 到 `main` | **Agent maintain (主干)** | `agent-maintain` ship |
手动运行：Actions → **agent-gate** 或 **agent-maintain** (`dry-run` | `ship`)。
Gate 并发：每个 PR 一次运行 (`cancel-in-progress: true`)。Bot 评论不会
触发 gate（避免循环）。
### 凭据
使用一个**共享的** Cursor API key。审查 / Issues / 修复 PR 通过
特定于作业的 `github.token` 以 **`github-actions[bot]`** 身份运行（与第一个 bot
版本相同）。可选的 **Tokens (classic)** PAT 仅用于 `github.token` 无法完成的操作——
切勿将 Fine-grained PAT 用作 `GH_TOKEN`（这会以你的个人
用户身份发布）。
#### 身份
| 操作 | GitHub 上的显示身份 |
| ------ | --------------------- |
| Gate 审查、APPROVE、request-changes、评论 | `github-actions[bot]` (`GH_TOKEN=${{ github.token }}`) |
| Maintain Issues、修复 PR、推送 | `github-actions[bot]` (`GH_TOKEN=${{ github.token }}`) |
| Gate `resolveReviewThread` (GraphQL) | 设置时需要 classic PAT `AGENT_GATE_GH_TOKEN` |
`GITHUB_TOKEN` 的权限在每个工作流中受到限制（`permissions:` 块）——这就是
gate 和 maintain 在不使用个人 PAT 的情况下保持最小权限的方式：
| 工作流 | `permissions` |
| -------- | ------------- |
| agent-gate | `contents: read`, `pull-requests: write` |
| agent-maintain | `contents: write`, `pull-requests: write`, `issues: write` |
同时启用 **Settings → Actions → General → Workflow permissions**：
- ✅ 允许 GitHub Actions 创建和批准 pull request
#### 分支规则集（合并权限）
Gate 和 maintain 均以 `github-actions[bot]` 身份发布。GitHub **无法**
APPROVE 由同一个 bot 创建的 PR（由 maintain 修复跟踪）。在
`main` 分支上配置规则集如下：
| 规则 | 值 |
| ---- | ----- |
| 必须的状态检查 | Gate 作业名称，例如 `Agent gate (PR 审查)` (严格) |
| 必须的批准审查 | **0** |
| 要求对话已解决 | **开启**（可选但推荐） |
当 gate **检查变绿**（exit 0）时合并。**不要**要求 APPROVE
事件。详情：技能库 `scm/github.md`。
#### Secrets 和变量
| 名称 | 种类 | 是否必需 | 使用者 | 权限 / 备注 |
| ---- | ---- | -------- | ------- | -------------- |
| `CURSOR_API_KEY` | secret | 是 | gate + maintain | Cursor 用户 API key ([Dashboard → Integrations](https://cursor.com/dashboard)) |
| `AGENT_GATE_MODEL` | variable | 是 | gate | 模型 ID，例如 `composer-2.5` |
| `AGENT_MAINTAIN_MODEL` | variable | 是 | maintain | 模型 ID（可与 gate 不同） |
| `AGENT_GATE_GH_TOKEN` | secret | 否* | 仅 gate | **Token (classic)**，范围 **`repo`**。仅用于 GraphQL `resolveReviewThread`。审查仍以 `github-actions[bot]` 身份发布。 |
| `AGENT_RUNNER_REF` | variable | 否 | 仅产品 CI | 锁定此 runner：**release tag**（例如 `v0.3.0`）。产品不得浮动在 `main` 上。 |
\*推荐：如果没有它，gate 可能无法解析审查线程。
**不要**将个人的 Fine-grained PAT 存储为 `GH_TOKEN`。删除任何
曾用作主要平台认证的 `AGENT_MAINTAIN_GH_TOKEN` —— maintain 仅使用
`github.token`。
```
# 必填
gh secret set CURSOR_API_KEY
# 用于 gate thread 解析的 optional classic PAT（scope: repo）
gh secret set AGENT_GATE_GH_TOKEN
# models
gh variable set AGENT_GATE_MODEL --body "composer-2.5"
gh variable set AGENT_MAINTAIN_MODEL --body "composer-2.5"
# 如果已将其设置为 primary identity，请移除 personal PAT
gh secret delete AGENT_MAINTAIN_GH_TOKEN 2>/dev/null || true
# products：固定 runner release（而非 main）
gh variable set AGENT_RUNNER_REF --body "v0.3.0"
```
本地：
```
export CURSOR_API_KEY="cursor_..."
export AGENT_GATE_MODEL="composer-2.5"
export AGENT_MAINTAIN_MODEL="composer-2.5"
# export AGENT_GATE_GH_TOKEN="ghp_..." # classic，可选
# export GH_TOKEN="..." # 用于本地 gh；CI 使用 github.token
```
## 版本和发布
产品在 CI 中通过 `git clone --branch "$AGENT_RUNNER_REF"` 安装此 runner。
将 **`AGENT_RUNNER_REF` 锁定到 release tag**（例如 `v0.3.0`），而不是 `main`。
当主版本号为 **0** 时（在 [`pyproject.toml`](pyproject.toml) 中为 `0.x.y`
且 tag 为 `v0.x.y`）：
| 部分 | 时机 |
| ------- | ---- |
| **x** | **破坏**向后兼容性（CLI 标志、退出代码、场景 YAML 契约、必需的 env / 身份规则） |
| **y** | **保持**向后兼容性 —— bug 修复**或**增量行为 |
当我们达到 **1.0.0** 时，切换到经典的 SemVer (MAJOR / MINOR / PATCH)。
**流程（针对每批更改手动执行）：**
1. 将工作合并到 `main`（PR + CI 变绿）。在发布 PR 之前，将
[`CHANGELOG.md`](CHANGELOG.md) 保留在 `Unreleased` 下。
2. 创建 PR，将 `Unreleased` 移至 **新版本部分**（在
`Unreleased` 下方插入新版本），并在需要时更新 `pyproject.toml` 中的
`version`。
3. 合并后，打 tag 并发布 GitHub Release：
```
git tag -a v0.3.0 -m "v0.3.0"
git push origin v0.3.0
gh release create v0.3.0 --title "v0.3.0" --notes-file <(sed -n '/## 0.3.0/,/^## /p' CHANGELOG.md | sed '$d')
```
**升级产品：**
```
# Repo variable（首选）
gh variable set AGENT_RUNNER_REF --body "v0.3.0"
# 当变量未设置时，Workflows 默认使用相同的 tag：
# RUNNER_REF: ${{ vars.AGENT_RUNNER_REF || 'v0.3.0' }}
```
当目录发生更改时，还需在产品中更新 skills 子模块的锁定版本
（独立的发布流：[ai-devsecops-skills](https://github.com/amsokol/ai-devsecops-skills)）。
## Gate (PR)
```
# Cursor Agent plan（无 GitHub mutate；被 block 时不 exit 5）
export AGENT_GATE_MODEL=composer-2.5
uv run agent-gate --target app-tauri-react-shadcn-ui --pr 37 --dry-run
# Ship（发布 review；AGENT_SIGNAL: block 时 exit 5）
uv run agent-gate --target app-tauri-react-shadcn-ui --pr 37
```
退出代码：`5` = `AGENT_SIGNAL: block`，`3` = policy-violation，`4` = critical-unfixed。
## Maintain (主干)
```
export AGENT_MAINTAIN_MODEL=composer-2.5
uv run agent-maintain --target app-tauri-react-shadcn-ui --dry-run
uv run agent-maintain --target app-tauri-react-shadcn-ui
```
## 技能库
共享目录：[ai-devsecops-skills](https://github.com/amsokol/ai-devsecops-skills)
（位于 `.cursor/agent/library` 的 git submodule）。产品仓库在
`.cursor/agent/` 中保留一个轻量级的 **overlay**
（`POLICY.md`，`verify.md`，`quarantine.md` 持续时间）。**无
symlinks。** **不要复制**整个目录。
库中的生态系统：`python-uv`，`npm`，`cargo`，`go-modules`，`bazel`，
`bsr`（每个技术栈对应一个 topic 文件）。当目录发生更改时更新 submodule SHA。
Bootstrap：`.cursor/agent/library/products/starter/`。
## 扩展
1. 在 [ai-devsecops-skills](https://github.com/amsokol/ai-devsecops-skills) 中添加或改进 skills。
2. 在产品中升级 submodule；在 overlay `POLICY.md` 中启用相应的生态系统。
3. 需要时在场景 YAML（`agent/scenarios/`）中列出新的能力。
未来示例：包含 `release` / `environment` 范围的 `deployment` 场景。
## 产品策略（`.cursor/agent/` —— 运行时的事实来源）
```
.cursor/agent/
POLICY.md # overlay: enabled ecosystems, hotspots, library links
verify.md # product commands
quarantine.md # duration N (approach in library/policy/)
library/ # git submodule → ai-devsecops-skills
```
Python runner 是轻量级的（CLI、凭据、场景 YAML、SDK、signal→exit）。
**所有流程和判断都存在于 library submodule + overlay 中。**
标签：Cursor SDK, DevSecOps, LNA, 上游代理, 代码审查, 自动化运维, 逆向工具