EN 한국어 日本語中文

← 入门 · INTRO 整体结构 · REFERENCE

inho-team · qe-framework · v6.5.0

QE Framework
系统架构图

Query & Execute — 将与 AI 的所有交互简化为两个动作，在其间插入 Plan → Spec → Execute → Verify 流程和 SIVS 质量关口的 Claude Code 插件。

SKILLS ···· 165
AGENTS ···· 21
CODING EXPERTS ···· 71
LICENSE ···· MIT

USER SAYS

"要做什么"
"帮我做那个"

→

CONTEXTFolder Memory

QUALITYSIVS Loop

LIBRARY165 Skills

→

YOU GET

精准的 Query
已验证的 Result

PSE Chain — 用户工作流

4-STEP PIPELINE

用户流程 4 个阶段——无论大项目还是单个 bug 都用同样的流程。每个阶段都有默认模型，但可通过 /Qsivs-config 自由更改。Qplan 判定为 Micro 规模时，跳过路线图直接自动转交给 /Qgs——用户无需判断规模。

STEP 01 / PLAN

Plan

/Qplan

制定路线图、阶段和需求。整理要构建什么的结构化阶段。

→

STEP 02 / SPEC

Spec

/Qgs

生成 TASK_REQUEST + VERIFY_CHECKLIST。优化为"精准 Query"的阶段。

→

STEP 03 / EXECUTE

Execute

/Qatomic-run

用 Haiku Teammates 执行并行 Wave。顺序执行使用 /Qrun-task 作为备选。

→

STEP 04 / VERIFY

Verify

/Qcode-run-task

Test → Review → Fix 质量循环。重复直到通过。

💡 每个阶段的 引擎(Claude / Codex)和模型可通过 /Qsivs-config 自由更改——默认值如上所示，但任何阶段都可替换为不同引擎或模型。

Layer Architecture — 6 层堆栈

SYSTEM STRUCTURE

框架由 6 个层组成。越往上(User)越是用户可见区域，越往下(Engine Bridge)越是执行基础。层间通信仅通过工件(文件)。

框架清晰地分为 6 个层。越往上(User)越是用户可见区域，越往下(Engine Bridge)越是执行基础。每层各司其职，仅与相邻层通过 工件(文件)通信。

LAYER 01 · INTERFACE
User Interface用户直接调用的入口点。斜杠命令(/Qplan, /Qgs…)和 PSE Chain 用户流程。提示上下文、CLAUDE.md、会话输入属于此层。
CLAUDE.md · prompts · /Q* commands
LAYER 02 · SKILLS
Skill Library165+ 个自包含的技能定义。每个技能是包含 Role / Workflow / Handoff 的 Markdown。用户命令路由到技能建立执行计划，但实现委托给代理。
skills/**/SKILL.md
LAYER 03 · AGENTS
Agent Fleet21 个后台代理(E*)。Teammate(Haiku)、Executor(Sonnet)、Supervisor(Sonnet/Opus)的 3 层职责分离。技能委托的实际执行主体。
agents/E*.md
LAYER 04 · HOOKS
Hook System确定性控制层。自动响应 SessionStart、PreToolUse、PostToolUse、Stop 等事件，执行上下文注入、权限关口、状态同步。独立于 LLM 判断的基于规则的关口。
hooks/scripts/*.mjs
LAYER 05 · STATE
State & MemoryUnified State(.qe/state/unified-state.json)单一真实源 + Folder-Aware Context(.qe/context/)。所有钩子和代理共享一个版本的状态，防止竞态条件。
.qe/state/ · .qe/context/ · .qe/tasks/
LAYER 06 · ENGINE
Engine BridgeSIVS 阶段级引擎路由抽象。Claude 为默认，可选通过 codex-plugin-cc 委托 Codex。无外部 SDK(OpenAI/Gemini)直接调用——依赖隔离。
scripts/lib/codex_bridge.mjs

# 层间通信通过工件——即使技能调用代理也通过文件/状态
# 钩子不直接修改任何层，仅写入状态层(确定性)

SIVS Loop & 三大支柱

QUALITY GATE + SUPPORT SYSTEMS

SIVS 是在 PSE 流程内运行的质量关口。Spec → Implement → Verify → Supervise 4 个阶段。Verify(做了吗?)和 Supervise(做得好吗?)是不同的。失败时通过 REMEDIATION 重新进入循环(最多 3 次)。

SIVS Loop — 质量关口

INSIDE STEPS 03 & 04

Spec

Implement

Verify

Supervise

→ PASS
完成 (Done)

→ FAIL
Remediate → Spec 重试

# 核心:Supervise 阶段是独立引擎时规避"自我评分"问题
# 每个阶段可自由在 Claude / Codex 间路由

核心原则

"Work without a spec is guesswork.
A spec without implementation is intent.
Implementation without verification is hope.
Verification without supervision is confirmation bias."

SPEC → IMPLEMENT

TASK_REQUEST 成为实现的合约。没有合约的执行无法验证。

VERIFY ≠ SUPERVISE

Verify 是"做了吗?"(是/否)，Supervise 是"做得好吗?"(安全性、质量、文档专业评估)。

REMEDIATE

失败时不是即时修复，而是创建新 spec(REMEDIATION_REQUEST)重新进入循环。最多 3 次。

CROSS-PHASE

Phase N 完成前重新验证 Phase 1~N-1 的关键 VERIFY 项。防止回归的关口。

PILLAR 01

Context Memory Manager

按文件夹分割上下文，仅加载与工作目录匹配的内容。分散在 .qe/context/ 下而非单一 CLAUDE.md。

节省上下文 token

PILLAR 02

SIVS Loop Engine

Spec → Implement → Verify → Supervise。多引擎路由防止自我评分，Supervisor 判定 PASS/FAIL。

Claude ↔ Codex 独立路由

PILLAR 03

Skills & Agents Library

165 Skills (Q*, M*, coding-experts) + 21 Agents (E*). 상황에 맞게 주입되는 전문 지식 + 실행 주체.

165 skills · 21 agents · 71 experts

Design Philosophies — 5 大公理

FOUNDATIONAL AXIOMS

所有技能、代理、钩子遵循的 5 大公理 + 5 项义务。核心:"token 浪费是漂移"、"并行优先，顺序是备选"、"禁止无 spec 执行"。

除 SIVS 循环外，贯穿整个框架的 5 项公理。所有技能、代理、钩子如果违反这些公理，将通过 Ttune 进行校正。

AXIOM 01

Efficiency = Accuracy

Token 浪费不仅是成本，更是漂移的根源。不必要的 I/O、重复读取会分散模型注意力，导致错误判断。

应用:ContextMemo · Semantic Compression · 140k/170k 压缩关口

AXIOM 02

Parallel-First

两个任务之间无数据依赖则默认并行。顺序仅是明确依赖时的备选。翻转默认值才能减少往返时间。

应用:Haiku Wave · 多 UUID Qrun-task · 并发 Test+Review

AXIOM 03

Spec-First

无 spec 的执行是猜测。请求不明确时，先创建 TASK_REQUEST 再执行。即使紧急请求也要求最小合约。

应用:Qplan → Qgs 强制顺序 · Pre-execution Gate

AXIOM 04

Minimal Change

仅修改请求范围。禁止"整理"周围代码的重构。bug 修复只修复，一次任务只一个目标。

应用:Qcommit 原子分割 · 审阅者边界审计

AXIOM 05

Evidence-Based

不猜测。不确定时读文件验证。不是"应该有"而是"第 42 行有"。内存、缓存声称也要与现状对比。

应用:grep·Read 预先检查 · VERIFY_CHECKLIST 是/否严格判定

▸ MANDATORY OBLIGATIONS (5) — 展开

Respect the spec — 禁止无 TASK_REQUEST 执行。无则先生成。
Do not skip verification — VERIFY_CHECKLIST 未完成时禁止 complete。
Parallel first — 无依赖的两个任务必须并行。
Remediation is a new spec — 禁止临时修复，生成 REMEDIATION_REQUEST。
The loop is the product — 功能、技能、代理是手段，spec→实现→验证循环是目的。

Multi-Engine Routing

/Qsivs-config

SIVS 4 个阶段各自可独立分配给 Claude 或 Codex。规避同一引擎评分自己结果的"自我评估偏差"。默认都是 Claude。

为 SIVS 的各阶段(Spec/Implement/Verify/Supervise)独立分配 Claude 或 Codex。规避同一引擎评分自己结果的问题。

SPEC

Claude

or Codex

IMPLEMENT

Codex

or Claude

VERIFY

Claude

or Codex

SUPERVISE

Codex

or Claude

$ /Qsivs-config implement codex --effort high
$ /Qsivs-config set --all claude # 恢复默认值

Folder-Aware Context Memory

.qe/context/

项目上下文按文件夹分割存储。仅自动加载与工作目录匹配的文件——相比单一 CLAUDE.md 方式节省上下文 token（因项目而异，见 BENCHMARK.md）。

# 工作位置: src/frontend/components/Button.tsx
.qe/context/
├── _registry.json      # 文件夹 ↔ 上下文映射
├── root.md             # 始终加载(项目全局规则)
├── frontend.md          # ✔ src/frontend/** 匹配 → 加载
├── backend.md           # ✘ 跳过
└── scripts.md           # ✘ 跳过
结果 → 减少上下文 token 使用（因项目而异）

Skill Library — 165 Skills

Q* + M* + coding-experts

165+ 个技能分为 12 个类别。PSE Core、Meta、PM、Docs/Writing、Coding Experts(71 位)、QA/Testing、Data/Analysis 等。每个技能遵循 frontmatter + Role + Workflow + Handoff 的 4 部分标准。

Backend

Django, FastAPI, Spring, Rails, NestJS…

Frontend

React, Vue, Next.js, Flutter, Angular…

Languages

Python, Rust, Go, TS, Kotlin, Swift…

Infra

K8s, Terraform, AWS, CI/CD, SRE…

Quality

Code review, security, debugging, E2E…

Data/ML

RAG, fine-tuning, ML pipelines, Spark…

Core Q-Skills · 主要命令

/Qinit 初始化
/Qplan 计划
/Qgs Spec生成
/Qatomic-run 并行执行
/Qrun-task 顺序执行
/Qcode-run-task 验证
/Qcontext 上下文
/Qsivs-config 路由
/Qrefresh 刷新
/Qmemory 内存
/Qcompact 压缩
/Qcommit 提交
/Qbranch 分支
/Qarchive 归档
/Qmap-codebase 映射
/Qpm-prd PRD
/Qpm-roadmap 路线图
/Qpm-okr OKR
/Qfact-checker 检查
/Qdocx 문서
/Qpptx 幻灯片
/Qxlsx 表格
/Qfind-skills 搜索
/Qhelp 帮助

SKILL CATEGORIES — 12 个集群

165+ 个技能按角色分为 12 个类别。每个类别对应一个用户意图模式，IntentGate 按意图→类别→技能路径路由。

① PSE Core

用户工作流 4 个阶段——规划、spec、执行、验证的框架。

/Qplan · /Qgs · /Qatomic-run · /Qcode-run-task

② Meta (M*)

管理框架本身——版本、技能生成、审计、测试。

/Mbump · /Mcreate-skill · /Mqe-audit · /Mtest-skill

③ PM / Strategy

产品战略文档——PRD、OKR、路线图、回顾、GTM。

/Qpm-prd · /Qpm-okr · /Qpm-roadmap · /Qpm-retro

④ Docs / Writing

文档、电子邮件、论文、演示文稿的编写和打磨。

/Qdocx · /Qpptx · /Qwriting-clearly · /Qdoc-comment

⑤ Coding Experts

语言、框架级最佳实践 71 位专家(Java、Go、Rust…)。

Qjava-specialist · Qreact · Qfastapi · Qkotlin…

⑥ QA / Testing

测试计划、场景、回归、安全、视觉 QA。

/Qqa-test-planner · /Qscenario-test · /Qvisual-qa

⑦ Data / Analysis

数据探索、统计、财务分析、DB 架构设计。

/Qdata-analysis · /Qfinance-analyst · /Qdatabase-schema-designer

⑧ Research / Content

深度研究、事实验证、来源验证、内容编写。

Edeep-researcher · /Qfact-checker · /Qsource-verifier

⑨ Dev Env / Integration

MCP 配置、Chrome、Stitch、Codex 集成、Secret 管理。

/Qmcp-setup · /Qchrome · /Qstitch-cli · /Qsecret

⑩ Browser / UI

浏览器自动化、UI 设计、风格审计、视觉重设计。

/Qagent-browser · /Qfrontend-design · /Qdesign-audit

⑪ Academic / Thesis

论文写作、评论回复、研究计划、研讨会准备。

/Qgrad-paper-write · /Qgrad-paper-review · /Qgrad-research-plan

⑫ Utility / Flow

会话管理、上下文、移交、整理、自动化循环。

/Qcompact · /Qresume · /Qcommit · /Qcron · /Qutopia ⚠

SKILL COMPOSITION

一个 SKILL.md 是什么样的

所有技能都遵循相同的 4 部分结构。正因为这个标准，才能用 /Mcreate-skill 自动生成新技能，路由和执行引擎能以相同模式处理任何技能。

第 01 部分 — FRONTMATTER (YAML)

---
name: Qexample
description: 一行描述。当用户说"keyword1"、"keyword2"时使用。
recommendedModel: sonnet         # haiku | sonnet | opus
invocation_trigger: 何时调用。典型用户表述。
---

第 02 部分 — ROLE(一段话)

# Skill Name

## Role
You are [X]. Your job is to [Y]. [Z constraint].
Match the [action] to the [context], not the other way around.

第 03 部分 — WORKFLOW(步骤)

## Workflow

### Step 1: [Discovery / Context Acquisition]
- 读什么及决定什么

### Step 2: [Draft / Execute]
- 实际工作(文件创建、分析、重命名等)

### Step 3: [Verification / Approval]
- 用 AskUserQuestion 获取用户确认(必需)

### Step N: [Handoff]
- 转交给下一个技能的标准格式

第 04 部分 — HANDOFF(响应最后一块)

Phase {X}: {PhaseName} — Complete

Roadmap
  [x] Phase 1: {Name1}
  [>] Phase {X+1}: {NextName}

PSE: [x] Plan [x] Spec [x] Execute [x] Complete

下一步: /Qgs Phase {X+1}: {短别名}

# 无 Handoff 则技能执行失败——用户无法进入下一步
# 仅允许短别名，禁止复制 Phase 完整描述(feedback_handoff_brevity 规则)

Agent Fleet & Model Tiering

21 AGENTS · 3 TIERS

21 个后台代理(E* 前缀) + 3 个模型层级——Haiku(快速、并行)、Sonnet(均衡、实现)、Opus(深度、战略)。Delegation Enforcer 钩子自动注入合适模型。

Agent Fleet · E* Agents (21)

Etask-executor — 执行复杂检查清单
Eqa-orchestrator — 测试、评审、修复循环
Esupervision-orchestrator — 领域监督官路由
Ecode-reviewer — 代码审查
Ecode-test-engineer — 测试编写
Ecommit-executor — 无 AI 痕迹的提交
Erefresh-executor — 项目分析、上下文刷新
Edeep-researcher — 多源研究
Esecurity-officer — diff 安全审计
Ecompact-executor — 上下文窗口管理
Epm-planner — PRD、路线图、文档
+ 10 more — 归档、分析、转交…

TIER 01 · FAST

Haiku

简单、并行任务

Wave Teammates
归档 / 数据刷新

TIER 02 · BALANCED

Sonnet

代码实现

Etask-executor
Ecode-reviewer

TIER 03 · DEEP

Opus

战略、架构

/Qplan
Edeep-researcher

# Delegation Enforcer 作为 pre-tool-use 钩子自动注入正确的模型
# Token 压力时:140k → 触发 Ecompact-executor，170k → 强制压缩

Hook System — 确定性控制层

DETERMINISTIC CONTROL

9 种事件钩子(SessionStart、PreToolUse、PostToolUse、Stop 等)提供独立于 LLM 判断的关口——以确定性方式处理上下文注入、权限检查、状态同步、压缩触发。

Hook 是 Claude 生命周期的确定性执行点——如果提示是"建议"，Hook 就是"强制"。

模型路由——Delegation Enforcer 自动为每个代理注入 recommendedModel
阻止重复 I/O——ContextMemo 防止重新读取同一文件
自动压缩——140k token 时触发 Ecompact，170k 时强制
流程持续性——Stop 时保存 task 状态，重启时继续

会话生命周期

▶ SessionStart

QE: 加载 _registry.json
注入文件夹上下文

│

↺ Main Loop

(参考右侧详情)

│

📦 PreCompact

QE: 140k → Ecompact
170k → 强制压缩

│

⏹ SessionEnd

QE: 工作记录 / 归档

主对话循环

📝 HOOK

UserPromptSubmit

接收用户提示 · 可注入预处理

↓

Claude 판단

生成答案或决定调用 Tool

↓

🔁 TOOL EXECUTION LOOP · 每次使用 Tool 时重复

① HOOK

PreToolUse

Delegation Enforcer · ContextMemo · Security Gate

↓

② RUN

Tool 실행

Bash · Edit · Write · Read · Grep · Task

↓

③ HOOK

PostToolUse

审计日志 · 自动格式化 · Lint

↺ 结果返回到 Claude 上下文 → 如需更多则从 ① 开始重复

↓

🛑 HOOK

Stop

Persistent Mode 阻止流程中断

EXIT CODE 协议

exit 0

成功——继续进行。
如果 stdout 中有 JSON，将其解析用于 allow / additionalContext 注入。

exit 2

确定性阻止。
将 stderr 消息返回给 Claude。ContextMemo 阻止重复读取时使用此方式。

exit N

其他错误——非阻止。
仅在 verbose 模式下显示 stderr，执行继续。

# Hooks run with user permissions
# No sandbox — 脚本需小心

QE Framework 特殊钩子 · 每个点发生的事

钩子名称	事件	动作	结果
Delegation Enforcer	PreToolUse	自动注入与任务类型相匹配的模型(Haiku / Sonnet / Opus)。例:/Qplan 用 Opus，Wave Teammate 用 Haiku。	inject · exit 0
ContextMemo	PreToolUse (Read)	已读的文件重复读取时在钩子级阻止。防止 token 浪费。	BLOCK · exit 2
Folder Context Loader	SessionStart	匹配工作目录与 .qe/context/_registry.json，仅注入 root.md + 对应文件夹上下文。	inject ctx · exit 0
Auto-compaction Trigger	PreCompact	达到 140k token 时自动调用 Ecompact-executor，超过 170k 时强制压缩。	spawn agent
Persistent Mode	Stop	PSE Chain 进行中时阻止 Claude 中途停止响应。强制执行到 SIVS Loop 结束。	BLOCK · exit 2
Commit Trace Cleaner	PreToolUse (Bash: git commit)	与 Ecommit-executor 协同——移除提交信息中的 AI 痕迹，检查规约遵守。	allow / deny
Context Refresh Guard	PostToolUse (Edit/Write)	文件修改后检查相应文件夹上下文的陈旧度，必要时触发 /Qrefresh。	trigger
Security Gate	PreToolUse (Bash)	rm -rf /、force push to main、curl \| sh 等危险模式的硬阻止。	BLOCK · exit 2

End-to-End Flow — 一次查询的运行路径

USER QUERY → FINAL RESPONSE

一次用户查询如何通过框架的 6 个层的全路径快照——从提示接收到最终响应，一眼看出何时哪个钩子、技能、代理参与。

从用户输入一行到收到验证的响应，Context、Hook、PSE Chain、SIVS Loop 实际如何按顺序互锁运行的流程图。分支(◆)处路径分开，失败时回环到之前的步骤。

主要阶段

钩子参与

上下文状态

分支 / 判定

━ 实线:执行 · ┄ 虚线:参考/回环

💡 图表中"默认 Opus/Sonnet/Haiku"仅为默认——各 PSE 阶段的引擎(Claude/Codex)和模型可通过 /Qsivs-config 随时重新路由。

flowchart TD USER["👤 USER
修复 bug"]:::terminal H_PROMPT["UserPromptSubmit 钩子"]:::hook H_SESSION["SessionStart 钩子"]:::hook H_PRE["PreToolUse 钩子
· Delegation Enforcer
· ContextMemo
· Security Gate"]:::hook H_POST["PostToolUse 钩子
· 审计日志 · 自动格式"]:::hook H_COMPACT["PreCompact 钩子"]:::hook H_STOP["Stop 钩子"]:::hook H_END["SessionEnd 钩子"]:::hook C_CTX["文件夹上下文
root.md + folder.md
仅加载匹配的上下文"]:::ctx C_MEMO["读取文件缓存"]:::ctx C_TOKEN["Token 使用监控"]:::ctx SUBMIT["接收提示"]:::main CTXLOAD["Folder Context Loader
匹配工作文件夹加载"]:::main CLAUDE["开始 Claude 处理"]:::main PLAN["① Plan · /Qplan
默认 Opus"]:::main SPEC["② Spec · /Qgs
默认 Sonnet"]:::main EXEC["③ Execute · /Qatomic-run
默认 Haiku Wave"]:::main VERIFY["④ Verify · /Qcode-run-task
默认 Sonnet"]:::main TCALL["发生 Tool Call
Bash · Edit · Write · Read"]:::main CHECK{"重复安全风险
需要阻止?"}:::decision BLOCK["exit 2 BLOCK
返回原因给 Claude"]:::block TEXEC["执行 Tool"]:::main POSTLOG["处理结果
审计日志 · 格式"]:::main SIVS{"SIVS 判定"}:::decision TOKEN{"Token 阈值?"}:::decision COMPACT["Ecompact-executor
自动压缩执行"]:::main STOP{"Stop 尝试
流程进行中?"}:::decision PERSIST["Persistent Mode 阻止"]:::block ARCHIVE["会话归档
保存上下文"]:::main RESULT["✅ 已验证响应
Bug 修复 + 测试 + 审查完成"]:::terminal USER --> SUBMIT H_PROMPT -.-> SUBMIT SUBMIT --> CTXLOAD H_SESSION -.-> CTXLOAD C_CTX -.-> CTXLOAD CTXLOAD --> CLAUDE CLAUDE --> PLAN PLAN --> SPEC SPEC --> EXEC EXEC -->|需要 Tool| TCALL H_PRE -.-> TCALL C_MEMO -.-> CHECK TCALL --> CHECK CHECK -->|是阻止| BLOCK CHECK -->|否通过| TEXEC TEXEC --> POSTLOG H_POST -.-> POSTLOG POSTLOG -.->|下一个 Tool Call| TCALL POSTLOG --> VERIFY BLOCK --> VERIFY VERIFY --> SIVS SIVS -->|失败 Remediate| SPEC SIVS -->|通过| TOKEN C_TOKEN -.-> TOKEN TOKEN -->|140k 以上自动| COMPACT TOKEN -->|170k 以上强制| COMPACT TOKEN -->|140k 以下| STOP H_COMPACT -.-> COMPACT COMPACT --> STOP H_STOP -.-> STOP STOP -->|进行中| PERSIST PERSIST -.->|继续执行| EXEC STOP -->|完成| ARCHIVE H_END -.-> ARCHIVE ARCHIVE --> RESULT classDef main fill:#18212d,stroke:#3a4a60,stroke-width:1px,color:#dce4ef classDef hook fill:#2a1d08,stroke:#fbbf24,stroke-width:1px,color:#fbbf24 classDef ctx fill:#0a1e2a,stroke:#7dd3fc,stroke-width:1px,color:#7dd3fc classDef decision fill:#2a0e20,stroke:#f472b6,stroke-width:1.5px,color:#f472b6 classDef terminal fill:#0a2a1d,stroke:#6ee7b7,stroke-width:2px,color:#6ee7b7 classDef block fill:#2a0e14,stroke:#fb7185,stroke-width:1px,color:#fb7185

上下文

按文件夹选择加载
读取文件缓存
Token 自动压缩

钩子 (7)

SessionStart · End
Pre·PostToolUse
PreCompact · Stop

流程

Plan → Spec
Execute → Verify
(+ Inner Tool Loop)

判定 (4)

Tool 阻止
SIVS 通过/失败
Token 阈值 · Stop