Codesteward Review

了解你的代码图的 Agentic 代码审查。
把控每一次合并。管理每一个分支。支持自托管。

codesteward.ai · Category stack · Helm · 企业版说明

Node ≥ 22 · pnpm 9 · TypeScript ESM · Apache-2.0

## 为什么选择 Codesteward 大多数 AI 审查工具只是粗略浏览一下 diff 然后进行猜测。**Codesteward** 基于**结构化代码图**（调用链、依赖关系、权限路径）运行多 agent 审查，因此审查结果是基于代码库的实际运行方式的。 | | **Gate** | **Stewardship** | |--|----------|-----------------| | **何时** | PR / MR 创建、推送，或 `@codesteward review` | 长期分支与路径 | | **范围** | 专注于 Diff 的单元 | 包 / 路径 / 树批量 | | **输出** | 内联审查、检查运行、结论 | 持久化的审查结果生命周期 | | **策略** | 来自 **base** 分支的 `STEWARD.md` + 路径规则 | 相同模型 | 统一的审查结果 schema。统一的策略模型。支持多 provider 的 LLM。提供产品 UI、CLI、GitHub Action 以及可扩展的 worker。 ## 核心亮点 - **Graph 感知的 agent** — 专家级 agent 使用 Codesteward Graph (MCP) 来理解结构，而不仅是 patch - **双模式** — 在一个平台上同时实现 PR gate 与持续的分支管理 - **可扩展的身份验证** — Keycloak OIDC (SPA PKCE)；API 验证 JWT（无需粘性会话） - **多租户组织** — 成员、连接器、策略、学习、SCIM 路径 `/scim/v2/orgs/{slug}` - **学习循环** — 👍/👎、驳回、组织记忆 → 让下一次审查更安静 - **多 SCM** — GitHub App/webhooks、GitLab、Bitbucket、Azure DevOps、Gitea - **横向扩展** — API/UI 无状态；worker × 并发专家 agent；可选的队列 broker + KEDA - **自托管** — 你的云环境，你的模型，你的密钥 ## 架构 ``` ┌──────────────┐ SPA OIDC (PKCE) ┌─────────────────┐ │ UI :8080 │ ───────────────► │ Keycloak IdP │ │ React │ ◄── access_token ─│ MFA / federated│ └──────┬───────┘ └─────────────────┘ │ Bearer JWT ▼ ┌──────────────┐ enqueue ┌──────────────────────────────┐ │ API :8081 │ ───────────► │ Postgres jobs (default SoT) │ │ Hono │ │ + optional NATS/Rabbit/Pulsar│ └──────┬───────┘ └──────────────┬───────────────┘ │ sessions / findings │ claim ▼ ▼ ┌──────────────┐ ┌─────────────────┐ │ Postgres │ │ Workers (HPA / │ │ product SoT │ │ KEDA optional) │ └──────────────┘ └────────┬────────┘ │ ┌──────────────────────────────┼────────────────────────┐ ▼ ▼ ▼ Codesteward Graph MCP Model router Sandbox / Prove GraphQLite · Neo4j · Janus OpenAI · Anthropic · xAI local · docker · k8s ``` | 层级 | 职责 | |-------|------| | **UI** | 产品界面；浏览器持有 OIDC token | | **API** | 验证 JWT / API key；将审查任务入队；处理 webhooks | | **Worker** | Orchestrator、专家 agent、judge、SCM 发布 | | **Graph** | 通过 MCP 提供的结构化智能 | | **Queue** | 默认使用 Postgres；可选的 broker 用于 KEDA 深度扩展 | ## 快速开始 ### Category stack（推荐的演示方式） 完整技术栈：Postgres、Graph MCP、API、worker、UI、Keycloak。 ``` export OPENAI_API_KEY=sk-... # or compatible provider pnpm install && pnpm -r run build pnpm compose:category # UI → http://localhost:8080 # API → http://localhost:8081 # IdP → http://localhost:8083 (Keycloak console 的管理员凭据为 admin / admin) ``` 通过平台 IdP（Codesteward 主题的 Keycloak）登录。 演示应用用户（realm 种子数据）：`admin@demo.com` / `DemoAdmin.123`。 ``` pnpm compose:category:down ``` ### 本地包（开发） ``` pnpm install && pnpm -r run build # 可选的持久化状态 export DATABASE_URL=postgres://steward:steward@localhost:5432/codesteward pnpm migrate export MODEL_PROVIDER=openai-compatible OPENAI_API_KEY=sk-... pnpm dev:api # :8081 pnpm dev:worker pnpm dev:ui # :8080 ``` ### CLI ``` pnpm stew -- doctor full pnpm stew -- review -p . -r codesteward --tier thorough --depth thorough pnpm stew -- steward -p . -r codesteward pnpm stew -- findings export --sarif -s pnpm stew -- ask "What does a review unit cover?" ``` ### GitHub Action ``` - uses: ./actions/review-action with: risk-tier: full publish: "true" fail-on: high sarif-output: codesteward.sarif env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} ``` ## 产品能力 ### 审查流水线 专家 agent（正确性、安全性、性能、测试、规则等） → 可选的论述（深入） → 验证器 → judge → 噪音过滤器 → gate 结论 → SCM 发布（内联评论 + 检查运行）。 ### 策略 - **`STEWARD.md`** — 严重性底线、nit、跳过 glob、验证标准 - **`.codesteward/rules/**/*.md`** — 基于路径范围的指导 - 始终从 **base / 默认分支** 加载，而不仅是 PR head ### Webhooks 与提及 ``` # GitHub App webhook # https:///v1/webhooks/github # 在 PR 评论上（默认提及 token）： @codesteward review ``` 使用 `STEW_MENTION_TOKEN` 进行覆盖。事件包括：`pull_request` (opened / synchronize / reopened / ready_for_review) 以及用于提及的 `issue_comment`。 ### 身份与组织 - **Keycloak** 作为多租户身份的单一事实来源（SoT）（分组 `/orgs/{slug}`，角色 `steward-admin|reviewer|viewer`） - SPA OIDC 登录；API 通过 JWKS 验证 access token - 组织 slug 根据名称自动生成；**每个租户唯一**（冲突时返回 409） - SCIM：`/scim/v2/orgs/{orgId|slug}`，支持按组织区分的 bearer token ### 学习 对审查结果给出 👍/👎 反应，设置误报 / 暂不修复 — 组织记忆将反馈给下一次审查的 prompt。支持导出 SARIF 以供 GHAS / 其他工具使用。 ### 扩展性 | 关注点 | 方案 | |---------|----------| | 更多并发审查 | 扩展 **workers**（每个任务 `STEW_MAX_CONCURRENT` 个专家 agent） | | 更多 HTTP 请求 / webhooks | 扩展 **API**（JWT 身份验证是无状态的） | | 更多 UI 流量 | 扩展 **UI**（静态 nginx） | | 队列深度自动扩缩容 | 可选的 `STEW_QUEUE_BROKER=nats\|rabbitmq\|pulsar` + KEDA | ``` # 最小配置：仅使用 Postgres 处理 jobs DATABASE_URL=postgres://... # 可选混合模式（PG 作为 SoT + broker 用于 KEDA） STEW_QUEUE_BROKER=rabbitmq RABBITMQ_URL=amqp://... # Helm workers helm upgrade --install codesteward ./deploy/helm/codesteward \ --set worker.hpa.maxReplicas=20 \ --set worker.maxConcurrent=8 ``` Compose brokers：`deploy/compose/docker-compose.queue.yml`（配置 `rabbitmq` / `nats`）。 ## Monorepo ``` packages/ core · model-router · graph-client · policy · findings learning · db · sandbox · scm · agents · webhooks api · cli · mcp-server · ui services/worker # job consumer actions/review-action # GitHub Action deploy/compose # demo + category + keycloak + queue deploy/helm/codesteward # production chart + HPA / KEDA docs/ # enterprise notes & session audit ``` | 脚本 | 用途 | |--------|---------| | `pnpm build` | 构建所有包 | | `pnpm compose:category` | 完整的产品演示技术栈 | | `pnpm dev:api` / `dev:worker` / `dev:ui` | 本地服务界面 | | `pnpm stew -- …` | CLI | | `pnpm migrate` | Postgres 数据库迁移 | ## 配置草图 ``` # Graph GRAPH_MOCK=0 GRAPH_MCP_URL=http://localhost:3000/sse # or /mcp depending on transport # Models MODEL_PROVIDER=openai-compatible MODEL_NAME=gpt-4.1-mini OPENAI_API_KEY= # STEW_MODEL_JUDGE=… STEW_MODEL_CHEAP=… # Auth（category stack 会为 Keycloak 设置这些） STEW_IDENTITY_MODE=keycloak OIDC_ISSUER=http://keycloak:8083/realms/codesteward OIDC_PUBLIC_ISSUER=http://localhost:8083/realms/codesteward OIDC_CLIENT_ID=codesteward-ui # Webhooks（实时 GitHub 需要公网 URL） STEW_WEBHOOK_PUBLIC_URL=https://your-tunnel.example GITHUB_WEBHOOK_SECRET=... STEW_MENTION_TOKEN=@codesteward ``` 有关完整模板，请参见 [`.env.example`](.env.example)。 ## Graph 后端 | 后端 | 用途 | 说明 | |---------|-----|--------| | **GraphQLite** | 笔记本电脑 / 演示 | 内置 SQLite graph | | **Neo4j** | 生产环境默认 | `deploy/compose/docker-compose.neo4j.yml` | | **JanusGraph** | 大规模场景 | Apache-2.0 路径 | | **Mock** | CI | `GRAPH_MOCK=1` | ## 状态 这是一个自托管的双模式审查平台，提供产品 UI、Keycloak 身份验证、多租户组织、webhooks 以及横向扩展的 worker。托管式多租户 SaaS 的打包工作是正在进行的产品迭代。 仓库内更多阅读： - [`docs/ENTERPRISE_GAPS.md`](docs/ENTERPRISE_GAPS.md) — 企业级差距与难点边界 - [`docs/ENTERPRISE_SESSION_AUDIT.md`](docs/ENTERPRISE_SESSION_AUDIT.md) — 会话 / 审计说明 - [`deploy/helm/codesteward/README.md`](deploy/helm/codesteward/README.md) — 生产环境 chart ## 许可证 本项目基于 **Apache License, Version 2.0** ([`LICENSE`](LICENSE)) 授权。 版权与归属详情记录在 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE) 中 — 本 README 中不再赘述。 Codesteward Graph（作为依赖项或服务使用时）单独按 Apache-2.0 分发。

治理 · 验证 · 演进

标签：AI智能体, GNU通用公共许可证, MITM代理, Node.js, SOC Prime, 代码审查, 开发工具, 自动化攻击, 自托管, 请求拦截, 错误基检测, 静态代码分析