# OpenQuantum ## 任务范围、授权与完成 本文件补充全局工作偏好，适用于本仓库；子目录规则只约束其覆盖路径。下文的 Agent、Tool、Skill、 Model 等要求描述 OpenQuantum 产品架构，不要求仓库维护任务都启动产品运行链或科研流程。 - 解释、审查、诊断和方案讨论不自动授权修改代码、配置或运行状态。按请求提供结论、证据和建议； 用户同时明确要求修复、优化文件或实施时，执行相应修改。 - 对已授权且范围明确的实施，完成必要修改、适度验证和结果交付，不停在计划或等候重复确认。 只有缺少会实质影响结果的信息，或下一步超出授权范围时才询问；等待时继续不依赖该决定的工作。 - 发现附带问题或文档与实现不一致时，说明偏差和影响。只有完成当前任务确实需要且在授权范围内时才修复； 文档中的待办、里程碑和“应修复”不是独立的执行授权。 - 修改前检查相关工作树和暂存区差异，保留已有及并发改动。工作树不干净本身不是停工条件； 若同一区域的改动无法安全分离，暂停该区域的写入或提交，说明需要用户决定的具体重叠。 - 仓库实施沿用全局的独立本地提交偏好，只暂存本任务文件或片段；用户明确要求仅留工作树改动或不提交时除外。 提交前核对暂存范围。交付说明实际修改、验证结果和提交状态；受阻时明确剩余项，不把准备当成完成。 - 部署、发布、push、改写历史、向他人发送消息、删除重要数据或其他破坏性操作须有明确授权； 已有授权覆盖当前动作时不重复询问。修改、测试或 Skill 指令本身不扩大这些权限。 - 外部模型请求、数据外发、依赖安装和真实硬件操作，按当前任务授权与相应能力边界执行； 命令列在本文件中不等于授权运行。保留现有模型路由，不为审查或交叉验证擅自切换 Provider 或模型。 - 仅在用户指定或任务符合适用条件时使用 Skill；目录共置或文档示例不代表自动启用。 领域工作流留在对应 Skill，不作为所有仓库任务的前置步骤。完整计划、多模型、子 agent 和后台流程 不作为日常任务的默认要求；只有用户或适用规则明确要求时，才将其作为完成条件。 ## 按任务读取规则和文档 - 首次进行本项目的架构或实现工作时，先读 `docs/README.md` 的架构总览和权威导航；之后按任务读取相关契约， 不因引用链遍历全部文档或 Skills。同一任务中已经读取且未变化的内容不反复读取。 - 涉及架构基线、发布验收或当前风险时，读取 `docs/architecture/ARCHITECTURE_AUDIT.md` 的相关部分； 其中的日期化结论不能替代当前验证。 - 存在 `CURRENT.md` 时，按全局规则先读其权威来源链接，并按任务读取相关内容；只有本次工作改变其记录的 交接状态、结论或导航时才同步入口。一般说明或规则文字调整不自动触发里程碑更新或既有验收任务。 - 新增或修改扩展时，按职责查阅 `docs/architecture/EXTENSION_MODEL.md` 和 `CONTRIBUTING.md` 的适用路径； 验证与独立领域审阅要求仅在对应改动触发时适用，不套用到所有任务。 ## 产品与架构基线 OpenQuantum 是一个科研 Agent 操作平台。DeepSeek Harness 负责通用 Agent Runtime，量子计算、 性质预测、案例咨询和通用问答等产品能力由 Agent Preset 组合独立的 Harness Skill 与 Tool Provider； Tool 可以由原生 Tool Plugin 注册，或由 MCP Server 暴露后经 Harness MCP Client 注册，必要时再调用 OpenQuantum Scientific Validator。只有 Tool hook 等 Agent 生命周期行为才在同一 Preset 组合受信任的 agent-scoped Host Plugin。 DeepSeek Harness 的“一切皆 Plugin”是运行时装配原则：可组合模块统一通过 Cordis Plugin row 注入、注册 Interface 并随 scope 回收。Skill、Tool、MCP Server、Validator 等是职责对象；它们说明模块负责什么， 不与 Cordis Plugin 这一装配机制竞争。 ## 四个职责面 下面四项用于判断规则归属，不表示一条 `UI → Harness → 量子扩展 → Model` 的线性调用链： 1. UI：直接使用 Harness 原生 Web UI；浏览器展示通过 Harness Client Plugin、Slot 和 Harness RPC 扩展， 品牌壳由 deployment-scoped Host Plugin 使用 `tapIndex` 注入，OpenQuantum 特有设置经 Bounded Host Route 委托 Application Interface。 2. Harness：Session、Turn、Step、Goal、Job、事件日志、工具调度、审批、沙箱和持久化。 3. 量子扩展内容：Harness Skill 保存领域工作流和 Prompt；Tool 是 Agent 唯一调用的执行原语；Harness MCP Client 是 Tool Provider，MCP Server 通过协议暴露 Tool；Scientific Validator 产生科学 observations， Acceptance Profile 定义规则，只有 central Acceptance Builder 推导验收。 4. Model：Provider route、模型能力元数据、协议适配、鉴权引用、超时和可用性探测。 不要新增独立的 OpenQuantum domain/platform Runtime。通用执行机制放 Harness；领域指令放原生 `SKILL.md`，确定性执行放 Tool implementation，可强制规则放 Validator 或可信 Host Plugin；领域工作流与 科学规则不散落在 Client Plugin 或 Provider 配置里。相关源码可以为维护 locality 共置在 `.agents/skills//`，但共置不表示 Harness 会自动绑定或启动这些模块。 ## 扩展对象不可混用 - **Cordis Plugin**：DSH 的统一装配与生命周期单元；按具体职责承载 Skill Provider、Tool Provider、 Harness MCP Client、Model Adapter、Host 或 Client 扩展，不能成为无边界的业务容器。 - **Skill**：告诉 Agent 何时、为何和怎样做；不执行代码、不启动 MCP Server、不持有凭据。 - **Tool**：Agent 可调用的原子动作；必须声明有界 schema、错误语义和副作用。 - **Tool Provider**：在 Harness 侧把 Tool 注册进 Registry；典型实现是原生 Tool Plugin 或 Harness MCP Client。 - **MCP Server**：通过协议暴露一个或多个 Tool；Agent 调用 MCP-exposed Tool，而不是“调用 MCP”。 - **Harness MCP Client**：连接 MCP Server，并把其 Tool 注册进 Harness Tool Registry。 - **Bounded Host Route**：只做请求边界与响应格式，然后委托 Application Interface；不复制业务规则。 - **Application Interface**：统一拥有用例命令、状态转换、并发和安全规则，可被多个产品入口复用。 - **External API**：Tool implementation 使用的下游网络合同；UI 和 Skill 不直接调用。 - **Scientific Validator**：从结构化证据产生 observations；Acceptance Profile 定义规则，只有 central Acceptance Builder 推导最终 Acceptance。 - **Eval / Benchmark**：开发、CI 和发布期证据，不进入用户请求的运行链。 - **Agent Preset**：组合 Skill Provider、Tool Provider、Agent 策略，以及确有需要的 agent-scoped Host Plugin；不保存模型 Provider Route。 - **Deployment/Home Patch**：组合 Provider Route、默认模型、默认 Agent Preset、deployment-scoped Host Plugin 与 Client Plugin。 ## 扩展选择原则 - Skill 与 Tool 是正交对象：知识/工作流可以只有 Skill，原子动作可以只有 Tool；只有 Skill 确实增加选择、步骤或解释规则时才组合两者，不要求同名或一一绑定。 - 进程内、同语言且无需隔离的确定性动作默认由原生 Tool Provider 注册；只有独立进程、跨语言、远程部署或明确隔离边界才使用 MCP Server + Harness MCP Client。 - Agent 只看到完成用户意图所需的最小深 Tool surface；运行时检查、内部分步函数和可由主动作返回的元数据不单独暴露为 Tool。 - Tool 副作用按一次完整调用的最大可能影响声明。首次调用会下载、安装或写入工作区时，不能标成 `read-only`；若要恢复只读语义，必须把 setup 变成显式、独立且可审计的动作。 - Skill 可以指导 Agent 编排 Harness 已有的通用 Tool；实际调用由 Agent 经 Harness 执行，Skill 本身不执行动作。不要仅为让能力“拥有一个 Tool”而再包装 bash、浏览、文件或审批 Tool。能力策略应记录这些依赖和副作用，只有出现稳定业务合同或安全边界时才增加专用 Tool。 - External API Adapter、Validator、eval 和 benchmark 不因为“统一”而包装成 MCP；先按职责判断，再选择 Cordis Plugin 装配方式。 描述 OpenQuantum 架构时，不用 `MCP/Tool`、`Validator/eval` 或 `Skill Validator` 混称不同职责； 接口按实际归属写为 Harness RPC、Bounded Host Route、Application Interface、External API 或 Model Provider API。 讨论运行时装配时写 `Cordis Plugin`；讨论具体职责时写明 Skill Provider、Tool Provider、Harness MCP Client、 Model Adapter、Host 或 Client Plugin 角色和 scope；上下文已明确时可简称。保留代码标识符、外部正式名称和 引用原文，不为术语规范扩大无关改写。完整定义和选择规则见 `docs/architecture/EXTENSION_MODEL.md`。 ## 不变量 - UI 不直接调用 Model Provider、MCP Server、External API 或 Skill 文件系统。 - Harness 中 Session、Turn、Goal、Job 的执行状态以 Session event log 为唯一事实源；配置存在或 UI 展示不能代替执行记录。 仓库修改、测试和 Git 状态分别以实际文件、检查输出和 Git 证据为准；科学验收按下一条规则判断。 - 运行完成和科学验收是两个状态；Acceptance Profile 只定义规则，只有 central Acceptance Builder 汇聚 Validator observations 和来源链推导出状态后，才能宣称科学验收通过。 - API Key 不得进入源码、日志、Artifact、Git diff 或提交。 - Provider 配置只引用环境变量名；真实密钥留在忽略的 `.env` 或 credential store。 - 新增研究能力按职责选择 Skill-only、Tool-only 或 Skill + Tool；仅有知识或工作流时可复用已有通用 Tool， 新增执行动作才注册相应 Tool Provider；有独立科学检查需求时增加 Validator，需要最终科学验收时再接入 Acceptance Profile、证据物化与 central Acceptance Builder。Agent Preset 独立组合所需 Skill Provider、 Tool Provider；只有 Harness hook 确实需要时才声明 agent-scoped Host Plugin。 使用 Validator 时由 Tool 或 Materializer 显式调用；涉及 hook 时由可信 Host Plugin 拥有， 内部 Scientific Result Adapter 只做 capability 映射。 - 不修改 `node_modules` 中的 DeepSeek Harness 实现；通过 Cordis patch 和 preset 扩展。 ## 代码位置 - `runtime/openquantum`：Harness patch、preset、模型 route、品牌和原生 Client Plugin。 - `src/settings/server`：项目 Skill、MCP Server 连接与凭据引用的受控设置实现。 - `.agents/skills`：Harness 原生 Skill 指令，以及为维护 locality 可选共置的领域资源；连接 MCP Server 的 Harness MCP Client 仍需在 Agent Preset 中独立声明。 - `docs/architecture`：架构决策和边界。 ## 常用命令 以下是按任务选择的入口，不是每次修改都要运行的清单；执行仍遵循上文授权边界。 - `npm run dev`：启动 OpenQuantum Harness Web Host 和原生 Web UI。 - `npm run harness:dev`：以自定义参数启动同一个 Harness Host。 - `npm run harness:config`：展开并检查 Harness 组合配置。 - `npm run models:probe -- --provider openquantum-public`：验证模型目录、文本生成和工具调用。 - `npm run capability:diagnostics:test`：验证平台诊断能力包和评分规则。 - `npm run check`：运行 lint、能力声明一致性检查、平台/科学测试并验证 Harness 组合配置。 ## 实现规则 - 使用清晰的原生 ESM、明确数据结构和 2 空格缩进。 - 新增能力或改变跨模块行为时，先明确受影响的核心对象、状态、事件和不变量，再选择实现落点； 局部修复沿用已确定的模型和模式，不为流程完整性重新设计架构。 - 按改动选择验证：纯文档或规则调整检查差异、链接和指令一致性；代码或配置修改运行最相关的检查， 保留适用贡献路径要求的合同、失败路径、集成测试和领域审阅。涉及广泛影响、发布验收或明确要求时再运行全仓检查。 - 相关检查通过且已授权目标完成后收口；只有新改动、失败或未解决风险才扩大或重复验证。 失败时先判断与本次改动的关系：修复授权范围内的问题；无关失败或外部条件受阻则如实报告影响和未验证项， 不擅自扩修，也不将未通过写成通过。