一、项目定位与设计愿景

Qualixar OS 定位为"面向 AI Agent 的通用操作系统（Universal OS for AI Agents）"，目标是成为多智能体协同运行的基础设施。它不是单一框架，而是把"团队设计、记忆、评判、工具市场、协议互联"等子系统整合在一个运行时中。仓库内的 README.md 将其描述为"由七个产品、七篇同行评审论文共同支撑"的开放平台，强调每一个主要组件都有学术研究作为底座（资料来源：README.md）。

产品许可采用 FSL-1.1-ALv2（功能源代码许可证）：发布两年后自动转 Apache License 2.0，禁止以此为基础构建竞品服务。这一选择兼顾了"商业可持续"与"防止搭便车"两种诉求（资料来源：README.md）。

二、核心能力与差异化特性

Qualixar OS 的差异化可以从四个层面概括：

1. 13 种执行拓扑：覆盖 Sequential、Parallel、Hierarchical、Star、Debate、MoA、Maker、Circular、Forest 等模式，并包含一个 Hybrid 本地↔云端分流拓扑，通过 7 阶段算法结合关键字与正则进行 PII 识别，将敏感数据路由到本地 Ollama 模型，其余任务下发到云端。README 将其称为"业内首批内置 PII 感知路由的智能体运行时"（资料来源：README.md）。
2. Forge 智能团队设计器：src/agents/forge.ts 顶部注释明确其属于 Phase 4，职责是"设计团队、管理模板库、在失败时重新设计"。claude-code-plugin/agents/qos-forge-architect.md 进一步说明：用户用一句自然语言描述任务，Forge 自动选择拓扑、分配子智能体的模型与工具，并输出执行流图与成本估算。
3. 多 Judge 评判管道：在 claude-code-plugin/agents/qos-quality-judge.md 中，质量评估由可靠性指数 Theta、SPRT 统计认证、合约化测试三类方法共同支撑，输出包括正确性、安全性、性能、可维护性等加权评分。
4. 混合协议互联：MCP（Model Context Protocol）与 A2A（Agent-to-Agent）双协议并存，REST 端点 27+，并通过 WebSocket 流式输出对话（资料来源：README.md）。

三、平台架构概览

下图以组件视角展示 Qualixar OS 的分层结构。核心是运行时与数据层，外层是开发者可触达的命令行、仪表盘、协议与 IDE 集成通道。

graph TD
  A[开发者入口<br/>CLI / Dashboard / IDE Plugin] --> B[任务编排层<br/>Forge + 13 Topologies]
  B --> C[智能体执行层<br/>Agents + Tools + Memory]
  C --> D[质量保障层<br/>Judge Pipeline + Strategy Memory]
  B --> E[协议层<br/>MCP + A2A + HTTP + WebSocket]
  C --> F[数据层<br/>better-sqlite3 / 49 tables]
  G[市场层<br/>Marketplace / 18 内置插件] --> C

CLI 部分由 src/cli/cli-new-command.ts 暴露 qos new 等命令，结合 src/cli/wizard/wizard-steps.ts 中的 Quick（9 步）/ Advanced（21 步）/ Manual（3 步）三种引导模式落地（资料来源：src/cli/cli-new-command.ts、src/cli/wizard/wizard-steps.ts）。IDE 集成则由 packages/create-qos/src/mcp-config.ts 提供，支持 Claude Code、Cursor、Windsurf、VSCode、Antigravity 五种编辑器（资料来源：packages/create-qos/src/mcp-config.ts）。

四、生态体系与适用场景

Qualixar OS 是"Qualixar AI Agent Reliability Platform"七件套之一，配套产品包括 SuperLocalMemory、SLM Mesh、SLM MCP Hub、AgentAssay、AgentAssert、SkillFortify 等，覆盖记忆、协同、评测、合约测试等可靠性支柱（资料来源：README.md）。

内置的 5 个项目模板（研究助手、代码助手、客服、数据管道等）由 src/cli/templates/template-catalog.ts 提供，并经 src/cli/templates/template-scaffolder.ts 替换 {{PROJECT_NAME}}、{{PROVIDER}}、{{MODEL}} 等占位符后落地为可运行工程（资料来源：src/cli/templates/template-catalog.ts、src/cli/templates/template-scaffolder.ts）。Claude Code 插件目录 claude-code-plugin/README.md 则把同样的能力封装为 /qos-forge、/qos-marketplace 等斜杠命令、四个 Skills，以及 qos_task、qos_agents、qos_quality 等 MCP 工具，使 Claude Code 用户可在 IDE 内一键调用。

技术栈方面，运行时为 Node.js 22+ 与 TypeScript 5.7，HTTP 框架使用 Hono，仪表盘为 React 19 + Vite，测试套件 Vitest 覆盖 2,936 用例（资料来源：README.md）。典型使用流程为 qos serve --dashboard --port 3000 启动服务，再通过 qos run "..." 提交任务，由 Forge 自动设计团队并执行。

See Also

• CLI 命令参考
• 仪表盘功能（24 个标签）
• 协议文档（MCP + A2A）
• Providers（15 家供应商）
• Frameworks（4 个原生适配器）
• Claude CLI 集成
• IDE 集成指南

概述

核心引擎是 Qualixar OS 中负责"接收任务 → 设计团队 → 调度执行 → 质量裁决 → 安全降级"的中央子系统，位于 CLI / HTTP API 与具体智能体实现之间。用户通过 qos run <prompt> 或 POST /api/tasks 提交任务后，引擎自动调用 Forge 设计多智能体团队，再由 Orchestrator 按选定拓扑（topology）调度各 agent 执行，最后由 Judge 给出质量结论，全程由 BudgetGate 与 Degradation 监控预算与故障。Qualixar OS 文档将这一端到端流程描述为"one sentence, full team"。

资料来源：README.md:120-155

任务执行流水线

下面这张流程图描绘了从用户输入到最终交付物的完整数据通路：

flowchart LR
    A[用户 CLI 或 REST API] --> B[Mode Engine<br/>模式解析]
    B --> C[Forge<br/>团队设计]
    C --> D[Orchestrator<br/>按 topology 调度]
    D --> E[Agent 执行]
    E --> F{Judge<br/>质量裁决}
    F -->|PASS| G[交付结果]
    F -->|FAIL| H[BudgetGate / Degradation]
    H --> D

各阶段职责如下：

1. 入口与模式选择：qos run 或 /api/tasks 接收 prompt 后，由 ModeEngine（src/engine/mode-engine.ts）解析运行深度（standard / deep / power 等）并下发给下游组件。
2. Forge 团队设计：Phase 4 的 Forge（src/agents/forge.ts）输出 TeamDesign，包含 agents、topology、judgeProfile 等字段。当首轮设计失败时，Forge 会依次尝试 ADAPT_DESIGN_PROMPT、REFINE_DESIGN_PROMPT、RADICAL_REDESIGN_PROMPT 进行团队重设计。
3. Orchestrator 调度：Orchestrator 与 AutoOrchestrator 依据 topology（Sequential、Parallel、Hierarchical、Debate、Star、Forest、Circular、Mixture-of-Agents、Maker、Hybrid 等 13 种）编排 agent 的执行顺序与依赖。
4. Judge 评审：qos-quality-judge 从 Correctness、Completeness、Security、Performance、Maintainability、Test Coverage 等维度打分，输出 PASS / CONDITIONAL_PASS / FAIL。
5. 降级回路：若 Judge 判定失败或 BudgetGate 触发阈值，Degradation 决定回退、缩减模型或转入 Hybrid 拓扑的本地侧执行。

资料来源：src/agents/forge.ts:1-40、src/agents/forge.ts:60-120、claude-code-plugin/agents/qos-quality-judge.md:1-30、README.md:130-155

核心引擎组件

ModeEngine 由 forge.ts 直接导入并作为依赖注入（ModeEngine 出现在 forge.ts 的 import 列表中），确认了引擎与团队设计器之间的耦合关系。

资料来源：src/agents/forge.ts:10-25、src/engine/orchestrator.ts、src/engine/budget-gate.ts、src/engine/degradation.ts

模板与 Wizard 引导

CLI 首次启动时，引擎会经由 Wizard 引导用户完成配置。wizard-steps.ts 定义了三种模式：Quick（9 步）、Advanced（21 步）、Manual（3 步），依次确定 provider、model、topology、budget 等关键参数。用户也可以跳过 Wizard，直接选用内置模板——template-catalog.ts 当前注册的 5 种模板分别为 research-agent、code-assistant、customer-support-agent、data-pipeline 等，每个模板携带 requiredProviders、tools、topology、postInstructions 等元数据。template-scaffolder.ts 负责把模板文件中的 {{PROJECT_NAME}}、{{PROVIDER}}、{{MODEL}} 占位符替换为实际值并写入磁盘；该实现遵循 HR-8（占位符而非硬编码）与 HR-13（永不删除已存在文件）两条硬性规则。cli-new-command.ts 则是 qos new <project> 命令的处理器，把上述流程串到 CLI 入口。

资料来源：src/cli/wizard/wizard-steps.ts:1-50、src/cli/templates/template-catalog.ts:1-80、src/cli/templates/template-scaffolder.ts:1-40、src/cli/cli-new-command.ts:1-30

常见故障模式

• Forge 输出非合法 JSON：forge.ts 同时引入 jsonrepair 与 partial-json 两个库，对 LLM 输出做渐进式修复；若仍无法解析，则升级到 RADICAL_REDESIGN_PROMPT 触发全新设计。
• 预算超支：BudgetGate 在累计成本超过阈值时立即停止后续 agent 调用，并把任务标记为 budget_exceeded，提示用户通过 qos cost 复核账单。
• 智能体异常：Orchestrator 把异常封装为事件发送至 EventBus，由 Degradation 决定是否回退到本地 Ollama 模型或切换至更便宜的云端模型。
• Judge 不通过：qos-quality-judge 在 CONDITIONAL_PASS 时仍输出 Required Improvements 列表，供下一轮 Forge refine 使用。

资料来源：src/agents/forge.ts:60-120、src/engine/budget-gate.ts、src/engine/degradation.ts

See Also

• Forge 与多智能体设计
• 质量评判体系
• CLI 命令参考
• Claude Code 插件
• 协议与拓扑

概览与定位

Qualixar OS 将自己定位为「AI 智能体通用操作系统」，其核心承诺是：用户输入一句自然语言任务，系统即可自动组建一支多智能体团队并完成执行。整套能力由三个互相支撑的子系统组成——智能体运行时、Forge AI 团队设计师、以及 13 种执行拓扑。运行时负责把单一智能体实例化、调度、挂起与恢复；Forge 负责在任务到来时「设计」团队——挑选拓扑、分配角色、配置工具、设置预算；拓扑则决定团队成员之间如何通信、谁先谁后、何时并行。资料来源：README.md。

这种分层让 Qualixar OS 与传统单 Agent 框架产生根本差异：开发者不再需要为每个任务手写 YAML 配置，也无需预先声明角色与拓扑。Forge 会依据任务类型、所需工具与历史经验动态决策，并在失败时触发「重设计」流程。资料来源：src/agents/forge.ts。

Forge AI 团队设计师

Forge 是 Phase 4 模块，承担「AI 团队设计」职责。其内部依赖 ModelRouter（模型路由）、StrategyMemory（策略记忆）、StrategyScorer（策略打分器）、ModeEngine（模式引擎）、TeamDesignStore（团队设计存储）以及 EventBus（事件总线），在接收到 ForgeRequest 后产出一份 TeamDesign。资料来源：src/agents/forge.ts:1-30。

TeamDesign 包含任务 ID、提示词、模式（QosMode）、代理角色清单（AgentRole[]）、特性开关（FeatureGates）以及可选的 ForgeJudgeProfile。Forge 通过 jsonrepair 与 partial-json 两个库来容忍大模型返回的残缺 JSON，保证设计结果可被稳定解析。资料来源：src/agents/forge.ts:30-40。

为避免「重设计」过程中丢失过往成功经验，系统引入了 Forge Memory Guard：每次激进重设计前，preserveBeforeRedesign 会扫描 forge_designs 表，将高分区间的部分设计归档到 forge_preserved_patterns 表，从而在拓扑切换时仍可回溯。资料来源：src/agents/forge-memory-guard.ts:1-25。

13 种执行拓扑

Qualixar OS 文档宣称内置 13 种执行拓扑，覆盖从简单顺序到复杂混合的全部场景。下表整合 README 中可被源码佐证的拓扑家族：

Hybrid 拓扑值得一提：它通过关键字与正则的 7 阶段算法检测 PII，敏感工作路由到本地 Ollama，剩余部分卸载到云端。README 声称这是「同类运行时中首批内置 PII 感知本地/云路由」的实现。资料来源：README.md。

模板系统与 Claude Code 集成

为了让新用户零配置上手，Phase 19 引入了项目模板目录 TEMPLATE_CATALOG。每个 TemplateDefinition 描述一组要落盘的文件及其 content（含 {{PROJECT_NAME}}、{{PROVIDER}}、{{MODEL}} 占位符）。TemplateScaffolderImpl.scaffold 负责解析模板、替换占位符并写入磁盘。资料来源：src/cli/templates/template-catalog.ts:1-40 与 src/cli/templates/template-scaffolder.ts:1-25。

已内置 5 种模板，其中两类在源码中可见：

• Research Agent —— 配置 web_search、fetch_url、read_file、write_file、rag_query 工具链，启用 4 层记忆与 SQLite 后端，并附 postInstructions 引导用户放置文档、执行 qos run。资料来源：src/cli/templates/template-catalog.ts:1-40。
• Code Assistant —— 启用 code_review 工具与 execute_command，用于文件读写、Shell 执行和自动化评审。资料来源：src/cli/templates/template-catalog.ts:25-40。

handleNewCommand 负责交互流程：列出模板、让用户选择、调用 scaffolder.scaffold。它显式遵守两条硬规则——HR-8（模板文件使用占位符而非硬编码值）、HR-13（绝不删除已存在文件）。资料来源：src/cli/cli-new-command.ts:1-30。

在 Claude Code 侧，qos-claude-code 包以插件形式暴露相同能力：技能 qos-forge-design 直接调用 Forge 设计团队，/qos-forge 与 /qos-marketplace 提供快捷命令，6 个预构建子代理（如 qos-forge-architect、qos-quality-judge）可在 Agent Teams 中被调度。资料来源：claude-code-plugin/README.md 与 packages/qos-claude-code/package.json。

flowchart LR
    A[用户 Prompt] --> B[Forge AI]
    B --> C{挑选拓扑}
    C -->|顺序| D[Chain]
    C -->|混合| E[Hybrid Local/Cloud]
    C -->|辩论| F[Debate + Judge]
    D --> G[Agent Runtime]
    E --> G
    F --> G
    G --> H[模板 / 工具市场]
    H --> I[质量闸门 + 成本追踪]

常见失败模式

1. 激进重设计丢失经验——已通过 forge-memory-guard.ts 的归档机制缓解。资料来源：src/agents/forge-memory-guard.ts:1-25。
2. 模板占位符未替换——template-scaffolder 强制替换 {{PROJECT_NAME}} 等三处占位符，HR-8 禁止硬编码。资料来源：src/cli/cli-new-command.ts:1-30。
3. 覆盖已有文件——TemplateDefinition.files[].overwrite=false 默认为安全模式，HR-13 禁止删除。资料来源：src/cli/templates/template-catalog.ts:1-40。
4. PII 误路由——Hybrid 拓扑使用 7 阶段关键字+正则检测，敏感字段默认留在本地 Ollama。资料来源：README.md。

See Also

• 仪表盘 24 标签与 CLI 25 命令：docs/cli/overview.md
• 协议层（MCP + A2A）：docs/protocols/
• 内存与质量评估：docs/memory/、docs/quality/
• Claude Code 集成：docs/claude-cli/

概述与定位

SLM-Lite（SuperLocalMemory 的轻量化集成）是 Qualixar OS 的内置长期记忆子系统，为多智能体运行提供跨会话的状态保持、上下文检索与行为回溯能力。README 描述其为"4 层认知记忆，配合信息几何检索与隐私优先的本地存储"，并将其与 arXiv:2604.04514 论文研究相对应。资料来源：README.md:90-95

在系统栈中，SLM-Lite 处于数据库与质量控制层之间：Forge 在重新设计团队时通过 forge_designs 与 forge_preserved_patterns 表写入与回溯记忆模式；模板脚手架与向导步骤则将"启用记忆（memory.enabled: true）"作为 Quick/Advanced 模式的默认配置，从而保证项目启动即可获得记忆能力。资料来源：src/agents/forge-memory-guard.ts:1-35、src/cli/templates/template-catalog.ts:36-42、src/cli/wizard/wizard-steps.ts:20-40

核心职责

SLM-Lite 在仓库内体现为三类职责，分别由不同模块承担：

1. 模式保留（Pattern Preservation）

ForgeMemoryGuard.preserveBeforeRedesign() 在激进重设计（radical redesign）触发前执行，扫描既有 forge_designs 中高分模式并归档至 forge_preserved_patterns。这避免了拓扑变更时丢失已被证伪/验证的智能体组合。资料来源：src/agents/forge-memory-guard.ts:24-70

// src/agents/forge-memory-guard.ts
export interface PreservedPattern {
  readonly id: string;
  readonly sourceDesignId: string;
  readonly taskType: string;
  readonly topology: string;
  readonly agentRoles: readonly string[];
  readonly score: number;
  readonly reason: string;
  readonly preservedAt: string;
}

2. 团队设计回放

Forge 模块通过 jsonrepair + partial-json 双解析器从 LLM 响应中抽取团队设计 JSON，并调用 createTeamDesignStore() 写入 forge_designs。该机制使 SLM-Lite 能够为同一 taskType 复用既有高分解，避免每次都从零设计。资料来源：src/agents/forge.ts:1-60

数据流概览

flowchart LR
    A[用户提示] --> B[Forge 检索相似 taskType]
    B --> C{是否存在高分设计?}
    C -- 是 --> D[adapt 既有设计]
    C -- 否 --> E[从零设计新团队]
    D --> F[执行任务]
    E --> F
    F --> G[judge 评分]
    G --> H[写入 forge_designs]
    H --> I{分数低?}
    I -- 是 --> J[radical redesign]
    J --> K[ForgeMemoryGuard.preserveBeforeRedesign]
    K --> L[归档至 forge_preserved_patterns]

资料来源：src/agents/forge-memory-guard.ts:24-70、src/agents/forge.ts:30-90

模板与默认配置

内置模板（Research Agent、Code Assistant、Customer Support、Data Pipeline 等）均在 config.yaml 中默认开启 SQLite 后端记忆：

memory:
  enabled: true
  backend: sqlite

模板脚手架器（TemplateScaffolderImpl）将这些字段以占位符形式生成，并在 scaffold() 中替换 {{PROJECT_NAME}}、{{PROVIDER}}、{{MODEL}} 后写入目标目录。资料来源：src/cli/templates/template-catalog.ts:36-90、src/cli/templates/template-scaffolder.ts:25-55

已知失败模式与缓解

关联研究

资料来源：README.md:85-110

See Also

• docs/memory/ —— 记忆系统完整参考（详见 README 文档索引）
• src/agents/forge.ts —— 团队设计与记忆回放入口
• src/agents/forge-memory-guard.ts —— 重设计前的模式归档
• src/cli/templates/template-scaffolder.ts —— 模板中 memory 字段的占位符替换

系统概述与定位

Qualixar OS 的判定管道（Judge Pipeline）、共识（Consensus）与质量保障（Quality Assurance）子系统是一个面向 AI 智能体执行结果的多层级治理框架。该体系并非单一模块，而是由运行时的 Forge 评分机制、Claude Code 插件中的判定子代理、以及质量门控钩子共同组成。

在架构层面，src/agents/forge.ts 引入了 ForgeJudgeProfile、StrategyScorer 与 StrategyMemory 三个关键类型，表明在团队设计阶段即已嵌入质量评分与策略记忆能力。Forge 的 redesign() 方法会调用 forge-memory-guard，在激进重构前保留高分区案，防止"灾难性遗忘"（catastrophic forgetting）。

子系统在仓库 README 中被定位为"AI 智能体可靠性工程"的基础设施，与 SuperLocalMemory、AgentAssay、SLM Mesh 等共同构成可靠性矩阵。质量保障因此横跨执行前（合同校验）、执行中（监控钩子）与执行后（多判官共识）三个时间维度。

核心组件与运行机制

1. Forge 评分与策略记忆

Forge 子系统负责设计多智能体团队，其内部署了评分引擎对每一次团队设计打分。设计文档 src/agents/forge.ts 显示，TeamDesignStore、StrategyRecommendation 与 StrategyScorer 协同工作：评分器输出分数后，由策略记忆保留高分模式，以便未来相似任务复用。

为防止激进重构清空历史经验，src/agents/forge-memory-guard.ts 实现了 preserveBeforeRedesign()：扫描 forge_designs 表中高分设计，迁移至 forge_preserved_patterns 表。PreservedPattern 记录包含源设计 ID、拓扑、代理角色、分数与保留原因，从而形成长期可追溯的质量档案。

2. 多判官共识（Debate Topology）

README 描述的 qos-code-review 技能采用辩论拓扑：由审查者与魔鬼代言人两个判官并行评审，再由超级判官汇总输出。在 Claude Code 插件的 claude-code-plugin/agents/qos-quality-judge.md 中，判官按七个维度量化打分：Correctness、Completeness、Security、Performance、Maintainability、Test Coverage 与整体加权平均，并据此输出 PASS / CONDITIONAL_PASS / FAIL 三态裁决。

3. 质量门控钩子

README 列出的三项钩子 — TeammateIdle、TaskCreated、TaskCompleted — 在 Claude Code Agent Teams 流水线中强制执行质量契约：

• TeammateIdle 检测空闲代理并重新分配或升级；
• TaskCreated 在执行前验证任务结构、预算与拓扑；
• TaskCompleted 在结果落定前运行判官流水线。

资料来源：README.md

共识策略与漂移控制

为应对多判官输出分歧，仓库同时维护显式共识阈值与隐式漂移监测两类机制。Forge 评分器（StrategyScorer）在评分低于阈值时触发 redesign()，而 Memory Guard 则以"分数 + 拓扑 + 代理角色"三要素聚合保留模式，避免重复尝试已知失败路径。

在 Claude Code 插件侧，claude-code-plugin/agents/qos-forge-architect.md 明确指出拓扑选择依赖于任务依赖结构：顺序依赖采用 Sequential/DAG，独立子任务采用 Parallel，需达成一致采用 Debate/MoA。这种"拓扑即共识协议"的设计将质量保障内嵌于拓扑选择，而非事后追加。

下表总结三类质量保障层面的责任边界：

与 Claude Code 插件的集成

Claude Code 插件将上述能力下沉为可被 Claude 直接调用的代理与技能。claude-code-plugin/README.md 列出 6 个预构建代理，其中 qos-quality-judge（opus）与 qos-code-reviewer（sonnet）专门承担判官职责；qos-forge-architect（opus）负责拓扑设计。

插件同时提供 MCP 服务端点（qos_quality），将判官结果与记忆搜索暴露给 Claude Code 会话。开发者可在 Claude Code 中通过 /qos-forge、/qos-status 等命令触发质量保障流程，无需直接调用 CLI。

资料来源：claude-code-plugin/README.md

See Also

• Forge 团队设计与策略记忆
• Claude Code 插件代理定义
• 执行拓扑（13 种）参考手册
• 质量契约与可靠性测试

概述与设计目标

Qualixar OS 是一个面向 AI Agent 的运行时平台，其对外交互通过一组协议通道与框架适配器完成。README.md 将 MCP、A2A、HTTP、WebSocket、CLI 五种传输并列声明为核心协议栈 (README.md)。在这些传输之上，src/compatibility/ 子树承担异构框架互操作职责，由 converter.ts 提供统一的格式翻译层，并由 openclaw-reader.ts、nemoclaw-reader.ts 等 reader 实现把外部 Agent 框架的产物导入到 Qos 的内部数据模型。src/channels/mcp-server.ts 与 src/compatibility/a2a-{client,server}.ts 则分别把平台能力暴露为标准化的对外端点。

整体目标是：任何主流 Agent 协议都能"接入"Qualixar，Qualixar 也能"被调用"到任何主流 Agent 协议——这一点在 README 声明的 17 个框架适配器与 4 个原生 reader 上得到体现 (README.md)。

MCP 协议集成

src/channels/mcp-server.ts 将 Qualixar OS 暴露为 Model Context Protocol 服务器，使 Claude Code、Cursor 等兼容 MCP 的 IDE 可以直接发现并调用平台能力。在 Claude Code 插件中可通过如下命令一键注册 (claude-code-plugin/README.md)：

claude mcp add qualixar-os -- npx qualixar-os --mcp

注册后客户端即可使用 qos_task、qos_agents、qos_system、qos_context、qos_quality、qos_workspace 六组命名空间工具，对应任务生命周期、Agent 拓扑、系统配置、工作区、质检与文件管理 (claude-code-plugin/README.md)。

与 MCP 配套的客户端配置由 packages/create-qos/src/mcp-config.ts 提供。其核心策略是 "合并而非覆盖"：读取已有 MCP 配置文件后追加 Qualixar OS 条目，写回前自动备份 .bak。支持的 IDE 枚举如下：

(packages/create-qos/src/mcp-config.ts) 注释中明确指出："Claude Code 支持是相对于 Mastra 的竞争优势"。

A2A 协议与互操作

src/compatibility/a2a-server.ts 实现 Agent-to-Agent 服务端，使外部 Agent 可通过 HTTP 发现并调用 Qos 内任一 Agent；a2a-client.ts 则负责反向调用。服务发现端点遵循 A2A 规范，部署在 /.well-known/agent-card（README API 表格明确列出 GET /.well-known/agent-card 为 A2A discovery 端点 (README.md)）。A2A 与 MCP 的差异在于：A2A 面向"Agent 对 Agent"的长时间会话协商，MCP 面向"模型对工具"的工具调用；二者通过 converter.ts 共享统一的内部消息表示，避免在通道层重复建模。

框架兼容性与适配器

src/compatibility/converter.ts 作为格式转换中枢，将 MCP、A2A、HTTP、WebSocket 四种入站协议以及不同框架的 Agent 定义归一化为 Qos 内部数据结构（团队设计 TeamDesign、任务 QosTask、消息 Message 等），再分发到核心运行时。

flowchart LR
  subgraph Inbound["入站协议"]
    MCP["MCP Server<br/>channels/mcp-server.ts"]
    A2A["A2A Server<br/>a2a-server.ts"]
    HTTP["HTTP API (Hono)"]
    WS["WebSocket"]
  end
  subgraph Convert["统一转换层"]
    CV["converter.ts"]
  end
  subgraph Readers["框架 reader"]
    OC["openclaw-reader.ts"]
    NC["nemoclaw-reader.ts"]
    OTH["... 其他 reader"]
  end
  CORE["Qos Core Runtime<br/>(Forge / Agents / Judges)"]
  MCP --> CV
  A2A --> CV
  HTTP --> CV
  WS --> CV
  OC --> CV
  NC --> CV
  OTH --> CV
  CV --> CORE

openclaw-reader.ts 与 nemoclaw-reader.ts 是 Qos 导入外部框架产物 的两条原生 reader（README 文档树 docs/frameworks/ 列出了 4 个原生 reader 与额外 adapter）(README.md)。它们读取外部框架序列化格式后调用 converter.ts 转为 Qos TeamDesign，使历史 Agent 资产可被纳入新一轮任务调度。配合 CLI 的 qos import <path> 与 qos export <agentId>（README CLI 表格列出）形成"导入—运行—导出"闭环 (README.md)。

常见失败模式

1. MCP 注册失败：mcp-config.ts 在覆盖前会备份原配置，但若磁盘权限不足或 .bak 已存在且只读，写入会抛错——此时需手工清理 .bak。
2. A2A 端点 404：服务发现依赖 /.well-known/agent-card 路径，部署在反向代理后时需保证子路径未被改写。
3. Reader 版本不匹配：openclaw-reader.ts 与 nemoclaw-reader.ts 假定外部框架具有稳定 schema；框架升级后需同步 reader 解析逻辑，否则 converter.ts 会收到不完整字段。

See Also

• 仪表盘与运行时：docs/dashboard/
• CLI 命令参考：docs/cli/
• 框架 reader 与 adapter：docs/frameworks/
• Claude CLI 集成：docs/claude-cli/

概述

Qualixar OS 通过三层界面让用户与多智能体运行时协作：CLI（命令行）作为底层入口，Web 仪表盘提供 24 个标签页的可视化面板，市场（Marketplace）支持一键工具安装。CLI 暴露 25 条命令覆盖服务器、任务、设计、代理、导入导出、配置、内存、诊断与设置；仪表盘基于 React 19 + Vite 构建；市场按 6 大类目组织工具并通过 MCP 协议接入多款 IDE。三者通过共享的 Forge 设计师、模板目录与向导流程连接起来。

资料来源：README.md

CLI 命令行界面

CLI 是用户与系统交互的基础入口。qos 命令按功能分为 10 大类、共 25 条子命令，涵盖从启动服务器到诊断调试的完整生命周期：服务器（qos serve、qos dashboard、qos mcp）；任务（qos run、qos status、qos output、qos pause、qos resume、qos cancel）；设计（qos forge、qos models）；代理（qos agents、qos judges）；导入导出（qos import、qos export）；配置（qos config）；内存（qos memory）；诊断（qos cost、qos doctor、qos version）；设置（qos init、qos new）；通用（qos cmd、qos cmd-list、qos dispatch）。

资料来源：README.md

新项目脚手架

qos new <project> 通过 handleNewCommand 触发模板选择流程，调用 createTemplateScaffolder() 从目录加载 5 个内置模板（研究代理、代码助手、客户支持、数据管道等），并以交互式选择方式让用户挑选模板。overwrite: false 与 HR-13 规则保证不会删除已有文件。

资料来源：src/cli/cli-new-command.ts:30-60、src/cli/templates/template-catalog.ts:30-160

模板与占位符

TEMPLATE_CATALOG 集中定义 5 个项目模板，每个模板以 TemplateDefinition 类型描述 files、requiredProviders、tools、topology、postInstructions 等字段。文件内容使用三种占位符：{{PROJECT_NAME}} 替换为目标目录名，{{PROVIDER}} 与 {{MODEL}} 来自向导结果。TemplateScaffolderImpl.scaffold 步骤为：查找模板 → 解析绝对路径 → 替换占位符 → 写入文件。

资料来源：src/cli/templates/template-catalog.ts:1-160、src/cli/templates/template-scaffolder.ts:30-50

向导与安装器

向导系统提供三种模式：Quick（9 步）、Advanced（21 步）、Manual（3 步）。WIZARD_STEPS 数组按 modes 字段过滤出对应步骤，包含模式选择、Provider 选择、API Key、通道、执行模式、配置、MCP、Doctor、结束语等环节。packages/create-qos/src/installer.ts 中的 runInstaller 串联 9 步流程，每一步通过 p.isCancel() 处理 SIGINT 优雅退出；runDoctor 验证 Node.js ≥ 22.0.0 与 API Key 格式。

资料来源：src/cli/wizard/wizard-steps.ts:1-50、packages/create-qos/src/installer.ts:30-90

Web 仪表盘

仪表盘由 React 19 + Vite 渲染，包含 24 个标签页，可视化任务、代理、判决、成本、工具目录与市场浏览等视图。启动方式有两种：qos serve --dashboard --port 3000 一并启动服务器与仪表盘；qos dashboard 单独打开 Web 面板。仪表盘与 27+ REST 端点以及 WebSocket 流协同工作，支持任务提交、代理监控、即时聊天与 A2A 发现。

资料来源：README.md

市场与 MCP 集成

市场（Marketplace）提供 6 大工具类目：Web & Data、Code & Dev、Communication、Knowledge、Creative、Enterprise。18 个内置插件随产品一起发布，社区插件通过 qos-registry 全局注册表分发；qos cmd marketplace.install 可从 CLI 一键安装。mcp-config.ts 支持 6 款 IDE 的 MCP 配置文件写入（claude-code、cursor、cursor-global、windsurf、vscode、antigravity），写入策略为"合并而非覆盖"：先读取现有配置，加入 Qualixar OS 条目后再写回，并在修改前备份为 .bak。

资料来源：README.md、packages/create-qos/src/mcp-config.ts:1-80

Forge 设计师（桥接组件）

Forge 是仪表盘与 CLI 共享的 AI 团队设计师，在 qos forge 与 Dashboard Forge 标签页均可调用。src/agents/forge.ts 导出 ForgeRequest、TeamDesign 等核心类型，通过 JSON 提示词生成、修正或激进重设计代理团队，并依据 12 种拓扑结构（Sequential、Parallel、DAG、Debate、Hierarchical、Star、Forest、Circular、Mixture-of-Agents、Maker、Hybrid 等）分配角色与工具。

资料来源：src/agents/forge.ts:1-60、claude-code-plugin/agents/qos-forge-architect.md:1-30

体系结构

flowchart LR
  User[用户]
  CLI["qos CLI<br/>25 命令"]
  Dash["Web 仪表盘<br/>24 标签页"]
  Mkt["市场<br/>6 类目 / 18 插件"]
  Wiz["安装器/向导<br/>Quick/Advanced/Manual"]
  Tpl["模板目录<br/>5 内置"]
  Forge[Forge 设计师]
  Runtime[多智能体运行时]
  IDE["IDE MCP 客户端"]

  User --> CLI
  User --> Dash
  CLI --> Wiz
  CLI --> Tpl
  Wiz --> Tpl
  Tpl --> Runtime
  Dash --> Forge
  CLI --> Forge
  Forge --> Runtime
  CLI --> Mkt
  Mkt --> Runtime
  IDE -. MCP .-> Runtime

资料来源：src/cli/cli-new-command.ts、src/cli/wizard/wizard-steps.ts、packages/create-qos/src/installer.ts、src/agents/forge.ts

常见失败模式

• 模板 ID 未找到：scaffold 抛出 Template '${templateId}' not found 异常，由 handleNewCommand 捕获。
• Node 版本不满足：runDoctor 检测到 Node < 22.0.0 时立即停止，并输出红色错误信息。
• SIGINT 中断：@clack/prompts 的 isCancel() 在每一步都会检查，触发 process.exit(0) 优雅退出。
• MCP 配置文件已存在：mcp-config.ts 始终先 copyFileSync 备份为 .bak，再合并写入，避免覆盖用户原有 IDE 配置。

资料来源：src/cli/templates/template-scaffolder.ts:35-45、packages/create-qos/src/installer.ts:50-80、packages/create-qos/src/mcp-config.ts:1-40

See Also

• docs/cli/overview.md — CLI 完整参考
• docs/dashboard/ — 24 个标签页详细文档
• docs/protocols/ — MCP 与 A2A 协议
• docs/providers/ — 15 家 LLM 提供商
• docs/getting-started.md — 入门指南

概述

Qualixar OS 提供四种相互衔接的运行时机制，用于把项目真正落到磁盘上并安全地运行：模板驱动的项目脚手架（scaffolding）、向导式的配置收集（wizard）、默认安全策略以及模型路由层。CLI 的 qos new 命令从内置模板目录中挑选模板，替换占位符后写出真实文件；向导系统按照 Quick / Advanced / Manual 三种模式收集用户偏好并生成 WizardResult；Forge 在运行时根据这些配置动态设计代理团队，并在重新设计前通过记忆守卫保留高价值模式；模型路由层则决定调用哪一个 LLM 提供商与模型。整个流程围绕"零配置可用、可观测、可审计"的目标构建 资料来源：README.md。

部署：基于模板的项目脚手架

部署一个新项目从 qos new <project> 开始。该命令调用 handleNewCommand，由 createTemplateScaffolder() 返回脚手架实例，并展示 scaffolder.list() 返回的 TEMPLATE_CATALOG 中的所有模板 资料来源：src/cli/cli-new-command.ts。

TEMPLATE_CATALOG 是一个只读数组，每个 TemplateDefinition 包含 id、name、description、tagline 和 files[] 字段 资料来源：src/cli/templates/template-catalog.ts。内置模板至少包括 research-agent（研究代理）和 code-assistant（代码助手）等覆盖常见工作流的项目。每个文件的 content 中包含三个会被替换的占位符：

TemplateScaffolderImpl.scaffold() 的实现流程是：先在 TEMPLATE_CATALOG 中按 templateId 查找模板，找不到则抛错；然后调用 resolve(projectDir) 解析为绝对路径；最后遍历 template.files，逐文件创建目录并 writeFileSync 写出内容 资料来源：src/cli/templates/template-scaffolder.ts。

配置：向导驱动的三层模式

Wizard 系统是配置的入口。WIZARD_STEPS 是一个只读的 WizardStep[] 数组，每个步骤包含 id、modes（包含哪些模式触发）、promptType（select / input / confirm）、message、defaultValue 与 choices 字段 资料来源：src/cli/wizard/wizard-steps.ts。

三种模式对应不同的步骤深度：

• Quick：9 步，覆盖最小可用配置（提供商、模型、API Key 环境变量名）。
• Advanced：21 步，展开到工具集、信道、安全、内存后端等高级字段。
• Manual：3 步，直接进入 config.yaml 编辑器模式，由专家自行编写配置。

以 code-assistant 模板为例，config.yaml 展示出完整的运行参数：provider.primary + provider.model + provider.apiKeyEnv、memory.enabled + memory.backend、tools、channels.dashboard.port、security.containerIsolation + security.allowedPaths + security.deniedCommands 等 资料来源：src/cli/templates/template-catalog.ts。

flowchart LR
    A[用户 qos new] --> B[handleNewCommand]
    B --> C[TEMPLATE_CATALOG]
    C --> D[TemplateScaffolder]
    D --> E[替换占位符]
    E --> F[写入 config.yaml]
    F --> G[Qualixar OS 运行时]
    G --> H[Forge 设计团队]
    H --> I[模型路由调用 LLM]

安全：默认拒绝式策略

安全策略以"白名单路径 + 黑名单命令 + 容器隔离"三层叠加的形式体现在模板生成的 config.yaml 中 资料来源：src/cli/templates/template-catalog.ts。例如：

• security.containerIsolation: true：默认启用容器隔离以约束副作用。
• security.allowedPaths：限定代理可访问的相对路径（通常为 ./）。
• security.deniedCommands：硬编码拒绝危险命令（如 rm -）。

Claude Code 插件侧还提供 Audit log（审计日志）与 Cost tracker（成本追踪）两个 Hook，用于合规追溯与预算告警 资料来源：claude-code-plugin/README.md。

qos doctor 命令在 CLI 参考中归类于"诊断"分组，用于在部署前检查运行时健康度（包括配置完整性、提供商连通性、安全策略是否生效等） 资料来源：README.md。

模型路由与运行时整合

虽然模型路由器（ModelRouter）的完整源码未在本批文件中提供，但 ForgeRequest、TeamDesign、AgentRole 等类型表明 Forge 在设计团队时会显式选择 provider.primary 与 model 并通过 ModelRouter 发出请求 资料来源：src/agents/forge.ts。

部署层与路由层的衔接路径如下：模板写入的 config.yaml 被运行时解析，provider.primary / provider.model 成为默认路由目标；当 WizardResult 指定了不同提供商时，scaffolder 用 {{PROVIDER}} 与 {{MODEL}} 占位符把这些值落到文件中，从而无需手写即可把运行时指向 Anthropic、OpenAI、Google 或本地 Ollama 资料来源：src/cli/templates/template-catalog.ts。

Forge 记忆守卫：路由重设计的安全网

ForgeMemoryGuard 在 Forge 执行激进重设计（radical redesign）前调用 preserveBeforeRedesign(taskType, currentDesignId)：扫描 forge_designs 表找出高评分设计，复制到 forge_preserved_patterns 表以避免灾难性遗忘。返回值是 readonly PreservedPattern[]，每条记录包含 sourceDesignId、taskType、topology、agentRoles、score 与 preservedAt 资料来源：src/agents/forge-memory-guard.ts。这是路由层之上的"经验层"，保证高价值设计即使被覆盖也能被检索与复用。

常见失败模式

• 找不到模板：scaffold() 在 templateId 不匹配时抛出 Template '<id>' not found 异常 资料来源：src/cli/templates/template-scaffolder.ts。
• 目录已存在：默认不覆盖（overwrite: false），符合 HR-13 "永不删除现有文件" 原则 资料来源：src/cli/cli-new-command.ts。
• 占位符未替换：所有模板文件必须保持 {{PROJECT_NAME}} / {{PROVIDER}} / {{MODEL}} 三个占位符，违反 HR-8 规则会导致生成的 config.yaml 含字面占位符 资料来源：src/cli/templates/template-catalog.ts。

See Also

• Forge 团队设计
• 模板与脚手架
• Claude Code 插件集成
• CLI 命令参考

Pitfall Log / 踩坑日志

项目：qualixar/qualixar-os

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1201841278 | https://github.com/qualixar/qualixar-os | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1201841278 | https://github.com/qualixar/qualixar-os | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1201841278 | https://github.com/qualixar/qualixar-os | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1201841278 | https://github.com/qualixar/qualixar-os | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1201841278 | https://github.com/qualixar/qualixar-os | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1201841278 | https://github.com/qualixar/qualixar-os | release_recency=unknown