CodeCortexLoop

一条命令，七位领域专家，可自我进化的 Playbook。

面向 AI 编码工具的「写完代码后」流水线：正确性 → 安全 → 测试 → 错误处理 → 性能 → 精简 → 清理 —— 配套健康分、HTML 看板、handoff 接力、双语 Playbook、基线棘轮与 CI 集成。

核心能力

一键安装

curl -fsSL https://raw.githubusercontent.com/whitequeen306/code-cortex-loop/main/scripts/install-remote.sh | bash -s cursor

Windows（PowerShell）：

irm https://raw.githubusercontent.com/whitequeen306/code-cortex-loop/main/scripts/install-remote.ps1 | iex; Install-CodeCortexLoop -Tool cursor

将 cursor 换成 claude | qoder | trae | opencode | codex | all。安装后重启工具，在聊天里输入 /cortexloop。

本地 clone 安装：

git clone https://github.com/whitequeen306/code-cortex-loop.git
cd code-cortex-loop
.\scripts\install.ps1 -Tool cursor   # macOS/Linux: ./scripts/install.sh cursor

我适不适合用？（三个问题）

任意一条答 否 → 大概率不需要（这很正常）：

和现成方案比

不是 SaaS，是 harness + 零依赖脚本，让现有 AI 工具像一支有流程的审查团队。

怎么工作

flowchart LR
  pre["分析前查 Playbook"] --> orch["Orchestrator 指挥"]
  orch --> e1["专家1 正确性"]
  e1 --> e2["专家2 安全"]
  e2 --> e7["…专家7"]
  e7 --> score["汇总 + 健康分"]
  score --> out{"Report / Direct / CI"}
  out -->|Direct| fix["修复 + 复验"]
  fix --> reflect["反思 → Playbook"]
  reflect -.-> pre

• Orchestrator（主会话）：定 scope、按序委派专家、汇总 handoff、打分；禁止自己 inline 做 pass 分析
• 领域专家（每 pass 一个独立子 agent）：只负责本领域，写类别报告 + handoff JSON，供下游专家阅读
  • Cursor / Claude Code / OpenCode：通过 Task 工具启动（OpenCode 需配置 permission.task）
  • Qoder：通过内置 Agent 工具委派 ~/.qoder/agents/ 中的自定义智能体（阻塞、独立上下文）
  • Trae：在 SOLO 模式下由 SOLO Coder 按顺序委派 ~/.trae/agents/ 中的 7 个自定义智能体
• 分析串行、修复串行（Direct 模式下每组修复后跑测试）

七专家固定顺序

合约与边界：passes/README.md · Handoff Schema：schemas/pass-handoff.schema.json

三种工作模式

命令一览

跑完会得到什么

report.json 写出后自动跑后处理（badge、看板、历史、PR 评论体）。也可手动：

node scripts/validate-handoffs.mjs
node scripts/run-summary.mjs --out=docs/cortexloop/run-summary.md
node scripts/make-dashboard.mjs docs/cortexloop/report.json

健康分（0–100）

按未解决问题扣分，Direct 模式展示 修复前 → 修复后：

每条计入分数的 finding 须含 Evidence + Confidence；低置信猜测不进计分，只进 Open Questions。

Playbook 自我进化

v2.2 核心：记忆是召回（去哪查），不是权威（该信什么） —— 命中只提示优先排查区，修法每次重新推导验证。

# 分析前（默认仅 verified）
node scripts/playbook.mjs query --category=security,errorHandling --lang=js --global-merge

# Direct 复验成功后
node scripts/playbook.mjs record .cortexloop/reflection.json

# CI/人工确认或负反馈
node scripts/playbook.mjs feedback --signature=<sig> --outcome=external_verified --evidence="ci: run 123"

详见 docs/GUIDE.md#自我进化learning-loop 与 rules/learning-loop.mdc。

工具支持

未配置子 agent 或用户确认时才会退化为单会话 fallback。OpenCode 与 Cursor 共用 Task 流程。各工具差异：adapters/。

ZCode（智谱 Z.ai ADE）是独立产品，与 Trae 不同，当前未适配 CodeCortexLoop。

Qoder 快速上手

1. 安装：.\scripts\install-qoder.ps1（或 ./scripts/install.sh qoder），重启 Qoder
2. 确认 ~/.qoder/agents/ 下有 7 个专家（code-reviewer.md 等）
3. 在 Agent 模式聊天中运行 /cortexloop；主会话须启用 Agent 工具
4. Bootstrap 应显示 ✅ Qoder native subagent mode；orchestrator 按 pass 顺序委派 7 专家
5. 若 Agent 工具不可用，可手动按顺序调用 /code-reviewer → … → /cleanup-curator

详见 adapters/qoder/README.md。

Trae 快速上手（SOLO 模式）

1. 安装：.\scripts\install-trae.ps1（国内版目录为 .trae-cn），重启 Trae
2. 切换到 SOLO 模式（左上角模式切换）
3. 在 SOLO Coder 设置中启用 7 个自定义智能体（来自 ~/.trae/agents/）
4. 运行 /cortexloop；Bootstrap 应显示 ✅ Trae partial subagent mode
5. SOLO Coder 按 pass 顺序委派专家；每步写 report + handoff JSON

普通 IDE 聊天（非 SOLO）会退化为单会话。详见 adapters/trae/README.md。

Codex 快速上手（显式 spawn）

1. 安装：.\scripts\install-codex.ps1（或 ./scripts/install.sh codex），重启 Codex
2. 将 ~/.codex/codex.cortexloop.example.toml 的 [agents] 合并进 config.toml（max_depth = 1）
3. 确认 ~/.codex/agents/ 下有 7 个 .toml 专家
4. 合并 AGENTS.cortexloop.md 到项目或用户的 AGENTS.md
5. 运行 /prompts:cortexloop 或明确要求：按 pass 顺序逐个 spawn 子 agent；Bootstrap 应显示 ✅ Codex partial subagent mode
6. CLI 可用 /agent 查看子 agent 线程

Codex 不会自动 spawn——必须在 prompt 里写清顺序。详见 adapters/codex/README.md。

OpenCode 快速上手

1. 安装：.\scripts\install-opencode.ps1，重启 OpenCode
2. 将 ~/.config/opencode/opencode.cortexloop.example.json 中的 permission.task 合并进你的 opencode.json
3. 确认 ~/.config/opencode/agents/ 下 7 个专家含 mode: subagent
4. 用 Build 主 agent 运行 /cortexloop → Bootstrap 应显示 OpenCode Task 模式
5. 若 Task 被权限拒绝，可手动 @code-reviewer → … → @cleanup-curator

详见 adapters/opencode/README.md。

项目配置（可选）

cp cortexloop.config.example.json cortexloop.config.json
cp .cortexloopignore.example .cortexloopignore

cortexloop.config.json 可覆盖 preset、scope、启用哪些 pass、CI 阈值、Playbook 路径等。行内抑制：// cortexloop-ignore CL-001。

CI / GitHub Actions

第 1 步：你的 AI 工具产出 docs/cortexloop/report.json（例如 /cortexloop-pre-pr --ci）。

第 2 步：仓库根目录的复合 Action：

name: CodeCortexLoop
on: [pull_request]

jobs:
  gate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      # - run: your-ai-cli /cortexloop-pre-pr --ci
      - uses: whitequeen306/[email protected]
        with:
          report-path: docs/cortexloop/report.json
          max-high: '0'
          comment: 'true'

老项目债太多？先 /cortexloop-baseline 接受基线，再 ci-gate --baseline 只拦新增 Critical/High。完整示例：.github/workflows/cortexloop-example.yml。

真实项目案例：LianYu-PC

在 Vue 3 + Spring Boot 全栈项目上跑 /cortexloop-deep Report 模式（2026-06-22，整库扫描）。上图展示 Report 诊断 → Direct 修复示意 的先后对比；完整 81 条明细见标准看板。

* Direct 右侧为示意得分（非完整七专家复验）；LianYu-PC 原项目有 08-reflection.md 记录修复，完整复验待重跑。

典型发现： 验证码表达式泄露 · SSE 错误仍持久化 · 前端轮询静默失败 · 认证/SSE 核心路径零测试

产物为 Report 模式拷贝，不含 LianYu-PC 源码，未修改原项目。
想查看此项目： github.com/whitequeen306/LianYuPC

教学用 Demo

examples/demo-app/ — 故意写满 bug 的小项目，适合第一次试 /cortexloop。

性能预算

* 约 500 行 scope、Cursor/Claude；详细方法 →

后处理脚本（badge/看板/历史）：中位数 ~416ms（实测，无 LLM）。

文档索引

仓库结构

commands/     # /cortexloop 系列 slash command
passes/       # 七专家串行合约
agents/       # 领域专家 persona
skills/       # cortexloop-expert-core（公共）+ 各领域 depth skill + reflect
rules/        # workflow、learning-loop、refactor-safety …
scripts/      # ci-gate、playbook、看板、showcase、安装脚本（零 npm 依赖）
schemas/      # report、config、handoff JSON schema
examples/     # demo-app + lianyu-pc（真实大项目 Report）
action.yml    # GitHub 复合 Action

许可证

MIT —— 见 LICENSE