# https://github.com/qualixar/qualixar-os 项目说明书 生成时间：2026-06-12 04:25:30 UTC ## 目录 - [项目概述与核心价值](#page-1) - [核心引擎与任务执行管道](#page-2) - [智能体系统、Forge AI 与 13 种拓扑](#page-3) - [SLM-Lite 四层记忆系统](#page-4) - [判定管道、共识与质量保障](#page-5) - [协议、传输与框架适配器](#page-6) - [仪表盘、CLI 与市场](#page-7) - [部署、配置、安全与模型路由](#page-8) ## 项目概述与核心价值 ### 相关页面 相关主题：[核心引擎与任务执行管道](#page-2), [智能体系统、Forge AI 与 13 种拓扑](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md) - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [src/cli/templates/template-catalog.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-catalog.ts) - [src/cli/templates/template-scaffolder.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-scaffolder.ts) - [src/cli/cli-new-command.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/cli-new-command.ts) - [src/cli/wizard/wizard-steps.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/wizard/wizard-steps.ts) - [packages/create-qos/src/mcp-config.ts](https://github.com/qualixar/qualixar-os/blob/main/packages/create-qos/src/mcp-config.ts) - [claude-code-plugin/README.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md) - [claude-code-plugin/agents/qos-forge-architect.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-forge-architect.md) - [claude-code-plugin/agents/qos-research-agent.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-research-agent.md) - [claude-code-plugin/agents/qos-quality-judge.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-quality-judge.md)
# 项目概述与核心价值 ## 一、项目定位与设计愿景 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 集成通道。 ```mermaid graph TD A[开发者入口
CLI / Dashboard / IDE Plugin] --> B[任务编排层
Forge + 13 Topologies] B --> C[智能体执行层
Agents + Tools + Memory] C --> D[质量保障层
Judge Pipeline + Strategy Memory] B --> E[协议层
MCP + A2A + HTTP + WebSocket] C --> F[数据层
better-sqlite3 / 49 tables] G[市场层
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 命令参考](docs/cli/overview.md) - [仪表盘功能（24 个标签）](docs/dashboard/) - [协议文档（MCP + A2A）](docs/protocols/) - [Providers（15 家供应商）](docs/providers/) - [Frameworks（4 个原生适配器）](docs/frameworks/) - [Claude CLI 集成](docs/claude-cli/) - [IDE 集成指南](docs/ide-integration/) --- ## 核心引擎与任务执行管道 ### 相关页面 相关主题：[项目概述与核心价值](#page-1), [智能体系统、Forge AI 与 13 种拓扑](#page-3), [部署、配置、安全与模型路由](#page-8)
相关源码文件 以下源码文件用于生成本页说明： - [src/engine/orchestrator.ts](https://github.com/qualixar/qualixar-os/blob/main/src/engine/orchestrator.ts) - [src/engine/orchestrator-types.ts](https://github.com/qualixar/qualixar-os/blob/main/src/engine/orchestrator-types.ts) - [src/engine/auto-orchestrator.ts](https://github.com/qualixar/qualixar-os/blob/main/src/engine/auto-orchestrator.ts) - [src/engine/degradation.ts](https://github.com/qualixar/qualixar-os/blob/main/src/engine/degradation.ts) - [src/engine/budget-gate.ts](https://github.com/qualixar/qualixar-os/blob/main/src/engine/budget-gate.ts) - [src/engine/mode-engine.ts](https://github.com/qualixar/qualixar-os/blob/main/src/engine/mode-engine.ts) - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [src/cli/templates/template-catalog.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-catalog.ts) - [src/cli/templates/template-scaffolder.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-scaffolder.ts) - [src/cli/cli-new-command.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/cli-new-command.ts) - [src/cli/wizard/wizard-steps.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/wizard/wizard-steps.ts) - [claude-code-plugin/agents/qos-quality-judge.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-quality-judge.md) - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md)
# 核心引擎与任务执行管道 ## 概述 核心引擎是 Qualixar OS 中负责"接收任务 → 设计团队 → 调度执行 → 质量裁决 → 安全降级"的中央子系统，位于 CLI / HTTP API 与具体智能体实现之间。用户通过 `qos run ` 或 `POST /api/tasks` 提交任务后，引擎自动调用 Forge 设计多智能体团队，再由 Orchestrator 按选定拓扑（topology）调度各 agent 执行，最后由 Judge 给出质量结论，全程由 BudgetGate 与 Degradation 监控预算与故障。Qualixar OS 文档将这一端到端流程描述为"one sentence, full team"。 资料来源：[README.md:120-155]() ## 任务执行流水线 下面这张流程图描绘了从用户输入到最终交付物的完整数据通路： ```mermaid flowchart LR A[用户 CLI 或 REST API] --> B[Mode Engine
模式解析] B --> C[Forge
团队设计] C --> D[Orchestrator
按 topology 调度] D --> E[Agent 执行] E --> F{Judge
质量裁决} 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` | `src/engine/mode-engine.ts` | 解析运行模式（standard / power / deep 等），把模式参数注入 Forge 请求 | | `Orchestrator` | `src/engine/orchestrator.ts` | 按 topology 调度 agent，维护任务状态机并向 `EventBus` 发送事件 | | `OrchestratorTypes` | `src/engine/orchestrator-types.ts` | 定义 Orchestrator 的输入/输出、状态枚举、回调签名 | | `AutoOrchestrator` | `src/engine/auto-orchestrator.ts` | 在调用方未指定 topology 时，由 Forge 结果自动推导执行计划 | | `BudgetGate` | `src/engine/budget-gate.ts` | 监控 token 与成本累计，超阈值时熔断或强制降级 | | `Degradation` | `src/engine/degradation.ts` | 提供 fallback 策略：切换模型、缩减 prompt、转入 Hybrid 本地执行 | `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 ` 命令的处理器，把上述流程串到 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 与多智能体设计](./forge-multi-agent.md) - [质量评判体系](./quality-judges.md) - [CLI 命令参考](./cli/overview.md) - [Claude Code 插件](./claude-code-plugin.md) - [协议与拓扑](./protocols.md) --- ## 智能体系统、Forge AI 与 13 种拓扑 ### 相关页面 相关主题：[核心引擎与任务执行管道](#page-2), [SLM-Lite 四层记忆系统](#page-4), [判定管道、共识与质量保障](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [src/agents/forge-memory-guard.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge-memory-guard.ts) - [src/cli/templates/template-catalog.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-catalog.ts) - [src/cli/templates/template-scaffolder.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-scaffolder.ts) - [src/cli/cli-new-command.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/cli-new-command.ts) - [claude-code-plugin/README.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md) - [claude-code-plugin/agents/qos-research-agent.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-research-agent.md) - [packages/qos-claude-code/package.json](https://github.com/qualixar/qualixar-os/blob/main/packages/qos-claude-code/package.json) - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md)
# 智能体系统、Forge AI 与 13 种拓扑 ## 概览与定位 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 中可被源码佐证的拓扑家族： | 拓扑族 | 典型代表 | 适用场景 | 资料来源 | |---|---|---|---| | Sequential | Chain、Forest | 流水线式单链或多树并行 | [README.md]() | | Iterative | Circular、Mixture-of-Agents | 迭代精炼、Best-of-N 集成 | [README.md]() | | Engineering | Maker（Build → Test → Ship） | 工程化交付流程 | [README.md]() | | Hybrid | Local ↔ Cloud Split | 含 7 阶段 PII 路由的混合执行 | [README.md]() | | Debate | Reviewer vs Devil's Advocate + Judge | 多智能体代码评审 | [claude-code-plugin/README.md]() | 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]()。 ```mermaid 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](docs/cli/overview.md) - 协议层（MCP + A2A）：[docs/protocols/](docs/protocols/) - 内存与质量评估：[docs/memory/](docs/memory/)、[docs/quality/](docs/quality/) - Claude Code 集成：[docs/claude-cli/](docs/claude-cli/) --- ## SLM-Lite 四层记忆系统 ### 相关页面 相关主题：[智能体系统、Forge AI 与 13 种拓扑](#page-3), [判定管道、共识与质量保障](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md) - [src/agents/forge-memory-guard.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge-memory-guard.ts) - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [src/cli/templates/template-catalog.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-catalog.ts) - [src/cli/wizard/wizard-steps.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/wizard/wizard-steps.ts)
# SLM-Lite 四层记忆系统 ## 概述与定位 SLM-Lite（SuperLocalMemory 的轻量化集成）是 Qualixar OS 的内置长期记忆子系统，为多智能体运行提供跨会话的状态保持、上下文检索与行为回溯能力。README 描述其为"4 层认知记忆，配合信息几何检索与隐私优先的本地存储"，并将其与 [arXiv:2604.04514](https://arxiv.org/abs/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 在仓库内体现为三类职责，分别由不同模块承担： | 职责 | 承担模块 | 关键产物 | |------|---------|---------| | 跨任务模式保留 | `ForgeMemoryGuard` | `PreservedPattern` 快照写入 `forge_preserved_patterns` | | 团队设计持久化 | `Forge` / `team-design` | `TeamDesign` 写入 `forge_designs` | | 模板默认启用 | 模板目录 | `config.yaml` 中 `memory.backend: sqlite` | ### 1. 模式保留（Pattern Preservation） `ForgeMemoryGuard.preserveBeforeRedesign()` 在激进重设计（radical redesign）触发前执行，扫描既有 `forge_designs` 中高分模式并归档至 `forge_preserved_patterns`。这避免了拓扑变更时丢失已被证伪/验证的智能体组合。资料来源：[src/agents/forge-memory-guard.ts:24-70]() ```typescript // 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]() ## 数据流概览 ```mermaid 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 后端记忆： ```yaml 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]() ## 已知失败模式与缓解 | 失败模式 | 触发条件 | 缓解机制 | |---------|---------|---------| | 激进重设计丢失高分模式 | 多次重设计后 `forge_designs` 轮换 | `ForgeMemoryGuard.preserveBeforeRedesign` 提前归档 | | LLM 输出 JSON 截断 | 模型超长响应 | `jsonrepair` + `partial-json` 双解析（[src/agents/forge.ts:40-60]()） | | 模板覆盖现有文件 | 用户在已有目录运行 `qos new` | 脚手架 `overwrite: false`，由调用方决定是否覆盖（[src/cli/templates/template-scaffolder.ts:40-50]()） | ## 关联研究 | QOS 组件 | 支撑研究 | |---------|---------| | SLM-Lite 记忆 | [SuperLocalMemory arXiv:2604.04514](https://arxiv.org/abs/2604.04514) | | Judge 流水线 | [AgentAssert arXiv:2602.22302](https://arxiv.org/abs/2602.22302) | 资料来源：[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` 字段的占位符替换 --- ## 判定管道、共识与质量保障 ### 相关页面 相关主题：[智能体系统、Forge AI 与 13 种拓扑](#page-3), [SLM-Lite 四层记忆系统](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [src/agents/forge-memory-guard.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge-memory-guard.ts) - [claude-code-plugin/agents/qos-quality-judge.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-quality-judge.md) - [claude-code-plugin/agents/qos-forge-architect.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-forge-architect.md) - [claude-code-plugin/README.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md) - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md)
# 判定管道、共识与质量保障 ## 系统概述与定位 Qualixar OS 的判定管道（Judge Pipeline）、共识（Consensus）与质量保障（Quality Assurance）子系统是一个面向 AI 智能体执行结果的多层级治理框架。该体系并非单一模块，而是由运行时的 Forge 评分机制、Claude Code 插件中的判定子代理、以及质量门控钩子共同组成。 在架构层面，[src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) 显示，`TeamDesignStore`、`StrategyRecommendation` 与 `StrategyScorer` 协同工作：评分器输出分数后，由策略记忆保留高分模式，以便未来相似任务复用。 为防止激进重构清空历史经验，[src/agents/forge-memory-guard.ts](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/README.md) ## 共识策略与漂移控制 为应对多判官输出分歧，仓库同时维护**显式共识阈值**与**隐式漂移监测**两类机制。Forge 评分器（`StrategyScorer`）在评分低于阈值时触发 `redesign()`，而 Memory Guard 则以"分数 + 拓扑 + 代理角色"三要素聚合保留模式，避免重复尝试已知失败路径。 在 Claude Code 插件侧，[claude-code-plugin/agents/qos-forge-architect.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-forge-architect.md) 明确指出拓扑选择依赖于任务依赖结构：顺序依赖采用 Sequential/DAG，独立子任务采用 Parallel，需达成一致采用 Debate/MoA。这种"拓扑即共识协议"的设计将质量保障内嵌于拓扑选择，而非事后追加。 下表总结三类质量保障层面的责任边界： | 阶段 | 责任组件 | 关键产出 | |------|---------|---------| | 团队设计 | Forge + StrategyScorer | `TeamDesign` 与分数 | | 执行守门 | `TaskCreated` / `TeammateIdle` 钩子 | 验证通过 / 升级 | | 结果评判 | `qos-quality-judge` 与 Debate 拓扑 | 0–10 加权分 + 裁决 | | 长期记忆 | `forge-memory-guard` | `PreservedPattern` 档案 | ## 与 Claude Code 插件的集成 Claude Code 插件将上述能力下沉为可被 Claude 直接调用的代理与技能。[claude-code-plugin/README.md](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md) ## See Also - [Forge 团队设计与策略记忆](forge-team-design.md) - [Claude Code 插件代理定义](claude-code-plugin-agents.md) - [执行拓扑（13 种）参考手册](execution-topologies.md) - [质量契约与可靠性测试](reliability-contracts.md) --- ## 协议、传输与框架适配器 ### 相关页面 相关主题：[核心引擎与任务执行管道](#page-2), [仪表盘、CLI 与市场](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [src/channels/mcp-server.ts](https://github.com/qualixar/qualixar-os/blob/main/src/channels/mcp-server.ts) - [src/compatibility/a2a-client.ts](https://github.com/qualixar/qualixar-os/blob/main/src/compatibility/a2a-client.ts) - [src/compatibility/a2a-server.ts](https://github.com/qualixar/qualixar-os/blob/main/src/compatibility/a2a-server.ts) - [src/compatibility/converter.ts](https://github.com/qualixar/qualixar-os/blob/main/src/compatibility/converter.ts) - [src/compatibility/openclaw-reader.ts](https://github.com/qualixar/qualixar-os/blob/main/src/compatibility/openclaw-reader.ts) - [src/compatibility/nemoclaw-reader.ts](https://github.com/qualixar/qualixar-os/blob/main/src/compatibility/nemoclaw-reader.ts) - [packages/create-qos/src/mcp-config.ts](https://github.com/qualixar/qualixar-os/blob/main/packages/create-qos/src/mcp-config.ts) - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md) - [claude-code-plugin/README.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md)
# 协议、传输与框架适配器 ## 概述与设计目标 Qualixar OS 是一个面向 AI Agent 的运行时平台，其对外交互通过一组**协议通道**与**框架适配器**完成。README.md 将 `MCP`、`A2A`、`HTTP`、`WebSocket`、`CLI` 五种传输并列声明为核心协议栈 ([README.md](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md))： ```bash 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](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md))。 与 MCP 配套的客户端配置由 `packages/create-qos/src/mcp-config.ts` 提供。其核心策略是 **"合并而非覆盖"**：读取已有 MCP 配置文件后追加 Qualixar OS 条目，写回前自动备份 `.bak`。支持的 IDE 枚举如下： | IDE | 配置文件位置 | |-----|-------------| | claude-code | `~/.claude.json` | | cursor | `.cursor/mcp.json`（项目级） | | cursor-global | `~/.cursor/mcp.json` | | windsurf | `~/.codeium/windsurf/mcp_config.json` | | vscode | 见 `getConfigPath()` | | antigravity | 见 `getConfigPath()` | ([packages/create-qos/src/mcp-config.ts](https://github.com/qualixar/qualixar-os/blob/main/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](https://github.com/qualixar/qualixar-os/blob/main/README.md))）。A2A 与 MCP 的差异在于：A2A 面向"Agent 对 Agent"的长时间会话协商，MCP 面向"模型对工具"的工具调用；二者通过 `converter.ts` 共享统一的内部消息表示，避免在通道层重复建模。 ## 框架兼容性与适配器 `src/compatibility/converter.ts` 作为格式转换中枢，将 MCP、A2A、HTTP、WebSocket 四种入站协议以及不同框架的 Agent 定义归一化为 Qos 内部数据结构（团队设计 `TeamDesign`、任务 `QosTask`、消息 `Message` 等），再分发到核心运行时。 ```mermaid flowchart LR subgraph Inbound["入站协议"] MCP["MCP Server
channels/mcp-server.ts"] A2A["A2A Server
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
(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](https://github.com/qualixar/qualixar-os/blob/main/README.md))。它们读取外部框架序列化格式后调用 `converter.ts` 转为 Qos `TeamDesign`，使历史 Agent 资产可被纳入新一轮任务调度。配合 CLI 的 `qos import ` 与 `qos export `（README CLI 表格列出）形成"导入—运行—导出"闭环 ([README.md](https://github.com/qualixar/qualixar-os/blob/main/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/](https://github.com/qualixar/qualixar-os/tree/main/docs/dashboard) - CLI 命令参考：[docs/cli/](https://github.com/qualixar/qualixar-os/tree/main/docs/cli) - 框架 reader 与 adapter：[docs/frameworks/](https://github.com/qualixar/qualixar-os/tree/main/docs/frameworks) - Claude CLI 集成：[docs/claude-cli/](https://github.com/qualixar/qualixar-os/tree/main/docs/claude-cli) --- ## 仪表盘、CLI 与市场 ### 相关页面 相关主题：[协议、传输与框架适配器](#page-6), [部署、配置、安全与模型路由](#page-8)
相关源码文件 以下源码文件用于生成本页说明： - [src/cli/cli-new-command.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/cli-new-command.ts) - [src/cli/templates/template-catalog.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-catalog.ts) - [src/cli/templates/template-scaffolder.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-scaffolder.ts) - [src/cli/wizard/wizard-steps.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/wizard/wizard-steps.ts) - [packages/create-qos/src/installer.ts](https://github.com/qualixar/qualixar-os/blob/main/packages/create-qos/src/installer.ts) - [packages/create-qos/src/mcp-config.ts](https://github.com/qualixar/qualixar-os/blob/main/packages/create-qos/src/mcp-config.ts) - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md) - [claude-code-plugin/agents/qos-forge-architect.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/agents/qos-forge-architect.md)
# 仪表盘、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 ` 通过 `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]() ## 体系结构 ```mermaid flowchart LR User[用户] CLI["qos CLI
25 命令"] Dash["Web 仪表盘
24 标签页"] Mkt["市场
6 类目 / 18 插件"] Wiz["安装器/向导
Quick/Advanced/Manual"] Tpl["模板目录
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](docs/cli/overview.md) — CLI 完整参考 - [docs/dashboard/](docs/dashboard/) — 24 个标签页详细文档 - [docs/protocols/](docs/protocols/) — MCP 与 A2A 协议 - [docs/providers/](docs/providers/) — 15 家 LLM 提供商 - [docs/getting-started.md](docs/getting-started.md) — 入门指南 --- ## 部署、配置、安全与模型路由 ### 相关页面 相关主题：[核心引擎与任务执行管道](#page-2), [仪表盘、CLI 与市场](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [src/cli/templates/template-catalog.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-catalog.ts) - [src/cli/templates/template-scaffolder.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/templates/template-scaffolder.ts) - [src/cli/cli-new-command.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/cli-new-command.ts) - [src/cli/wizard/wizard-steps.ts](https://github.com/qualixar/qualixar-os/blob/main/src/cli/wizard/wizard-steps.ts) - [src/agents/forge.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge.ts) - [src/agents/forge-memory-guard.ts](https://github.com/qualixar/qualixar-os/blob/main/src/agents/forge-memory-guard.ts) - [claude-code-plugin/README.md](https://github.com/qualixar/qualixar-os/blob/main/claude-code-plugin/README.md) - [README.md](https://github.com/qualixar/qualixar-os/blob/main/README.md)
# 部署、配置、安全与模型路由 ## 概述 Qualixar OS 提供四种相互衔接的运行时机制，用于把项目真正落到磁盘上并安全地运行：模板驱动的项目脚手架（scaffolding）、向导式的配置收集（wizard）、默认安全策略以及模型路由层。CLI 的 `qos new` 命令从内置模板目录中挑选模板，替换占位符后写出真实文件；向导系统按照 Quick / Advanced / Manual 三种模式收集用户偏好并生成 `WizardResult`；Forge 在运行时根据这些配置动态设计代理团队，并在重新设计前通过记忆守卫保留高价值模式；模型路由层则决定调用哪一个 LLM 提供商与模型。整个流程围绕"零配置可用、可观测、可审计"的目标构建 资料来源：[README.md]()。 ## 部署：基于模板的项目脚手架 部署一个新项目从 `qos new ` 开始。该命令调用 `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` 中包含三个会被替换的占位符： | 占位符 | 替换来源 | 说明 | |---|---|---| | `{{PROJECT_NAME}}` | 目标目录基名 | 来自脚手架解析后的路径 | | `{{PROVIDER}}` | `WizardResult.provider` | 主 LLM 提供商标识 | | `{{MODEL}}` | `WizardResult.model` | 主模型标识 | `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]()。 ```mermaid 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 '' 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 团队设计](forge-team-design.md) - [模板与脚手架](templates-and-scaffolding.md) - [Claude Code 插件集成](claude-code-plugin.md) - [CLI 命令参考](cli-reference.md) --- --- ## Doramagic 踩坑日志 项目：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