@archsight/aios 1.0.0 → 1.1.0

package/governance/arbitration-protocol.md

@@ -0,0 +1,153 @@
+# Capability-Backed Arbitration Protocol
+
+状态：治理基线草案  
+适用范围：ArchSight AIOS 多 Agent 冲突仲裁、工具证据裁决和人工升级
+
+---
+
+## 一、目标
+
+本协议把 AIOS 的多 Agent 协作从“角色意见协商”升级为“证据驱动仲裁”。
+
+核心原则：
+
+> Agent 可以提出 Claim，但不能只凭自然语言推理裁决事实。事实裁决必须回到项目证据、结构化知识、确定性工具或人工授权。
+
+适用场景：
+
+- Atlas、Mason、Vitruvius、Argus、Daedalus、Euclid 等 Agent 对方案产生逻辑冲突。
+- 架构建议、工程计划、规范语义、结构计算、安全审查或 Runtime 权限之间存在互相阻断。
+- AIOS 需要决定继续执行、回滚、重新评审、收缩范围或升级给人类负责人。
+
+---
+
+## 二、证据优先级
+
+仲裁时按以下优先级裁决。低层级证据不能推翻高层级证据，除非高层级证据本身被标记为无效、过期或不适用。
+
+| 等级 | 证据 | 说明 |
+| --- | --- | --- |
+| L0 | 人类硬约束 | 预算、交付窗口、生产授权、法律责任、商业取舍、签章和最终发布许可。 |
+| L1 | 确定性工具返回值 | 测试、构建、lint、schema 校验、安全扫描、结构求解器、规范检查 API。 |
+| L2 | 项目事实 | 当前代码、配置、接口契约、数据库迁移、部署脚本、CI、ADR、运行日志。 |
+| L3 | 结构化知识库 | GraphRAG、规范条文、版本关系、地区 / 专业适用条件、来源页码和质量状态。 |
+| L4 | 专项 Agent 判断 | Atlas 的架构判断、Mason 的交付判断、Vitruvius 的领域判断、Euclid 的建模判断。 |
+| L5 | LLM 自然语言推理 | 只能作为假设、解释或建议，不能单独作为阻断或放行依据。 |
+
+工具结果优先，但不得盲信工具结果。L1/L3 证据必须带有输入、版本、适用条件和执行状态；缺失时只能进入 `Need verify`。
+
+---
+
+## 三、Claim 契约
+
+Agent 之间发生冲突时，不能只输出“我不同意”。每个参与方必须把意见转成 Claim：
+
+```text
+Claim:
+  id:
+  owner_agent:
+  type: architecture | delivery | domain_semantics | structural | security | runtime | business
+  statement:
+  evidence_level: L0 | L1 | L2 | L3 | L4 | L5
+  evidence:
+  assumptions:
+  need_verify:
+  blocking: true | false
+  severity: P0 | P1 | P2
+  requested_action: proceed | revise | reduce | stop | human_escalation
+```
+
+Claim 必须明确区分事实、判断、假设和待验证项。没有证据的 Claim 默认不具备阻断权。
+
+---
+
+## 四、冲突分类与主裁决依据
+
+| 冲突类型 | 主裁决依据 | 默认处理 |
+| --- | --- | --- |
+| 架构冲突 | Atlas + L2 项目事实 + L1 验证工具 | 回到 `architecture-review`。 |
+| 交付冲突 | Mason + CI / 测试 / 依赖图 | 收缩范围、重排计划或回到任务拆解。 |
+| 行业语义冲突 | Vitruvius + 规范工具 + 结构化知识库 | 不满足适用条件时阻断执行。 |
+| 结构计算冲突 | Euclid + Solver / 数值校验 + 单位和边界条件 | 缺少输入或工具失败时不得输出确定结论。 |
+| 安全 / 权限冲突 | Argus + 安全扫描 + 权限策略 | 默认阻断，除非人工明确批准。 |
+| Runtime 冲突 | Daedalus + Capability 权限 + 上下文策略 | 降权、隔离或重新设计工具调用边界。 |
+| 商业 / 范围冲突 | Janus / CEO + L0 人类目标 | 人工裁决或明确阶段性取舍。 |
+
+---
+
+## 五、状态机
+
+```text
+proposed
+  -> evidence_required
+  -> tool_check
+  -> accepted
+  -> planned
+  -> executed
+  -> reviewed
+  -> completed
+```
+
+异常路径：
+
+```text
+tool_check -> rejected -> revise
+tool_check -> need_verify -> hold
+reviewed -> rejected -> revise
+any -> human_escalation
+```
+
+阻断规则：
+
+- L1 工具返回 `fail` 且适用条件有效时，必须阻断后续执行或放行。
+- L3 规范 / 知识证据缺少版本、来源或适用条件时，不能自动判定合规。
+- L4 Agent 判断只能触发复核、重评或工具调用，不能独立推翻 L1/L2/L3。
+- L0 人类授权可以覆盖执行路线，但不能把未验证事实改写成已验证事实。
+
+---
+
+## 六、人工升级条件
+
+以下情况必须升级给人类负责人或项目指定审批人：
+
+- 核心技术栈替换。
+- 生产数据模型迁移。
+- Runtime 权限扩大。
+- 多 Agent 自动执行权限放开。
+- 自动发布到生产。
+- 法规合规最终判定、结构安全结论或工程签章。
+- 商业范围、预算、交付窗口和停损信号的最终取舍。
+
+人工裁决也必须记录证据和约束，不能只记录“老板同意”。
+
+---
+
+## 七、Decision Ledger
+
+每次仲裁必须沉淀为可复核记录。最小字段：
+
+```text
+Decision:
+  id:
+  date:
+  conflict:
+  claims:
+  evidence:
+  tool_results:
+  decision: proceed | revise | reduce | stop | escalate
+  rejected:
+  owner:
+  follow_up:
+```
+
+Decision Ledger 可以写入 ADR、memory、PR 描述、issue 或项目 `.ai/` 目录，具体位置由项目接入规则决定。
+
+---
+
+## 八、落地要求
+
+- Workflow 输出必须包含 `Claim / Evidence / Tool Result / Decision`。
+- Skill 需要声明可用 Capability、权限边界和证据契约。
+- Runtime Adapter 只负责调用工具和回传证据，不替代 Agent 判断。
+- 工具调用失败时必须暴露失败原因、输入摘要和可恢复路径。
+- 没有 Capability 实现时，必须标为 `declared-interface` 或 `Need verify`，不得伪造工具结果。

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "@archsight/aios",
-  "version": "1.0.0",
-  "description": "面向建筑 AI 研发的规则、Skill、Workflow 与多 Agent 项目接入工具包。",
-  "type": "module",
-  "homepage": "https://github.com/ArchSightLabs/archsight-aios#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ArchSightLabs/archsight-aios.git"
-  },
-  "bugs": {
-    "url": "https://github.com/ArchSightLabs/archsight-aios/issues"
-  },
-  "keywords": [
-    "ai",
-    "agents",
-    "architecture",
-    "bim",
-    "ifc",
-    "rag",
-    "graphrag",
-    "construction",
-    "codex",
-    "antigravity",
-    "claude-code"
-  ],
-  "bin": {
-    "archsight-aios": "./bin/archsight-aios.mjs"
-  },
-  "scripts": {
-    "doctor": "node ./bin/archsight-aios.mjs doctor",
-    "install:user": "node ./bin/archsight-aios.mjs install --target all --scope user",
-    "smoke:project": "node ./bin/archsight-aios.mjs validate --temp",
-    "test": "node ./tests/cli.test.mjs"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "bin/",
-    "skills/",
-    "workflows/",
-    "templates/",
-    "runtime/",
-    "agents/",
-    "governance/",
-    "delivery/",
-    "memory/",
-    "knowledge/",
-    "rag/",
-    "graph/",
-    "standards/",
-    "infra/",
-    "prompts/",
-    "vision/",
-    "docs/",
-    "LICENSE",
-    "CHANGELOG.md",
-    "CONTRIBUTING.md",
-    "SECURITY.md",
-    "CODE_OF_CONDUCT.md",
-    "README.md",
-    "AI_CODING_RULES.md",
-    "AGENTS.md",
-    "CLAUDE.md",
-    "GEMINI.md"
-  ],
-  "license": "MIT"
+{
+  "name": "@archsight/aios",
+  "version": "1.1.0",
+  "description": "面向建筑 AI 研发的规则、Skill、Workflow 与多 Agent 项目接入工具包。",
+  "type": "module",
+  "homepage": "https://github.com/ArchSightLabs/archsight-aios#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchSightLabs/archsight-aios.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ArchSightLabs/archsight-aios/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "architecture",
+    "bim",
+    "ifc",
+    "rag",
+    "graphrag",
+    "construction",
+    "codex",
+    "antigravity",
+    "claude-code"
+  ],
+  "bin": {
+    "archsight-aios": "./bin/archsight-aios.mjs"
+  },
+  "scripts": {
+    "doctor": "node ./bin/archsight-aios.mjs doctor",
+    "install:user": "node ./bin/archsight-aios.mjs install --target all --scope user",
+    "smoke:project": "node ./bin/archsight-aios.mjs validate --temp",
+    "test": "node ./tests/cli.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "workflows/",
+    "templates/",
+    "runtime/",
+    "agents/",
+    "governance/",
+    "delivery/",
+    "memory/",
+    "knowledge/",
+    "rag/",
+    "graph/",
+    "standards/",
+    "infra/",
+    "prompts/",
+    "vision/",
+    "docs/",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "README.md",
+    "AI_CODING_RULES.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md"
+  ],
+  "license": "Apache-2.0"
 }

package/runtime/README.md

@@ -6,6 +6,9 @@
 
 - [Agent Routing](agent-routing.md)
 - [Skill Routing](skill-routing.md)
+- [Capability Registry](capability-registry.json)
+- [Capability Registry Schema](capability-registry.schema.json)
+- [Capability Adapters](capability-adapters.json)
 - [Hermes 运行线](hermes/)（可选企业适配器）
 - 权限边界
 - 工具调用策略
@@ -20,3 +23,7 @@
 - 运行时 Adapter 只负责入口、调度、权限和回传证据。
 - 项目工作区中的代码、测试、构建和 `.ai/` 上下文始终是工程事实来源。
 - 不得因为启用了某个 Adapter，就把 Hermes、飞书或建筑行业背景写成所有项目的默认事实。
+- Capability 是 Agent 可调用或要求的外部证据接口；Adapter 可以实现 Capability，但不得把未执行的工具结果伪装成已验证事实。
+- 本地 stdio MCP 阶段先使用 Capability Registry 的 `ownerAgents` 和 `allowedSkills` 做权限边界；传统 API Key、mTLS、租户隔离等远程鉴权留给 HTTP / SSE / Gateway Adapter 阶段。
+- `archsight-aios capability:call` 是最小本地调用闭环：校验 Agent / Skill 权限，校验输入 schema，调用 MCP Tool，校验输出证据契约，再给出仲裁 Decision。
+- 多 Agent 冲突时，Runtime 应回传 `Claim / Evidence / Tool Result / Decision`，供治理层按 `governance/arbitration-protocol.md` 仲裁。

package/runtime/agent-routing.md

@@ -1,92 +1,118 @@
-# Agent Routing
-
-状态：治理基线  
-适用范围：ArchSight AIOS 的多 Agent / 多模型调度
-
----
-
-## 一、目标
-
-统一 Agent 到模型、工具和任务类型的路由，控制成本、上下文、权限和输出质量。
-
-没有统一路由会导致：
-
-- 成本失控。
-- 上下文失控。
-- 多 Agent 职责重叠。
-- 模型能力与任务不匹配。
-- 执行型 Agent 越权修改。
-
----
-
-## 二、默认路由表
-
-| Agent | 中文定位 | 默认模型族 | 主要任务 | 禁止事项 |
-| --- | --- | --- | --- | --- |
-| Atlas | 总架构师 | GPT | 架构设计、技术路线、边界治理、复杂 tradeoff | 不直接大规模写代码 |
-| Mason | 工程总工 | Gemini / GPT | 任务拆解、工程组织、CI/CD、交付计划 | 不越过审查直接发布 |
-| Argus | 代码审查官 | Claude / GPT | Code Review、安全、性能、技术债、Prompt 注入风险 | 不做无关风格挑刺 |
+# Agent Routing
+
+状态：治理基线  
+适用范围：ArchSight AIOS 的多 Agent / 多模型调度
+
+---
+
+## 一、目标
+
+统一 Agent 到模型、工具和任务类型的路由，控制成本、上下文、权限和输出质量。
+
+没有统一路由会导致：
+
+- 成本失控。
+- 上下文失控。
+- 多 Agent 职责重叠。
+- 模型能力与任务不匹配。
+- 执行型 Agent 越权修改。
+
+---
+
+## 二、默认路由表
+
+| Agent | 中文定位 | 默认模型族 | 主要任务 | 禁止事项 |
+| --- | --- | --- | --- | --- |
+| Atlas | 总架构师 | GPT | 架构设计、技术路线、边界治理、复杂 tradeoff | 不直接大规模写代码 |
+| Mason | 工程总工 | Gemini / GPT | 任务拆解、工程组织、CI/CD、交付计划 | 不越过审查直接发布 |
+| Argus | 代码审查官 | Claude / GPT | Code Review、安全、性能、技术债、Prompt 注入风险 | 不做无关风格挑刺 |
 | Vitruvius | 建筑数字化专家 | GPT / 行业知识模型 | BIM、IFC、规范、审图、行业知识结构化 | 不替代结构计算求解 |
 | Daedalus | AI 研发工程师 | GPT / Codex | RAG、GraphRAG、MCP、Tool Calling、Agent Runtime | 不擅自扩大工具权限 |
 | Hephaestus | 受控执行官 | Codex | 代码修改、脚本执行、自动化测试、文档生成 | 不擅自加功能或重构 |
 | Euclid | 结构力学专家 | GPT / 数值计算模型 | 梁系、桁架、FEM、刚度矩阵、荷载分析 | 不在未验证公式时输出工程结论 |
-| Athena | 知识治理官 | GPT | 标准治理、版本管理、知识图谱治理、条文差异 | 不直接改运行系统 |
-| Mercury | AI 情报官 | DeepSeek / 搜索增强模型 | AI 情报、GitHub 趋势、MCP 生态、开源分析 | 不把未验证资讯当事实 |
-| Janus | 产品策略官 | GPT / Gemini | MVP、SaaS、用户分层、商业化路径 | 不替代工程验收 |
+| Athena | 知识治理官 | GPT | 标准治理、版本管理、知识图谱治理、条文差异 | 不直接改运行系统 |
+| Mercury | AI 情报官 | DeepSeek / 搜索增强模型 | AI 情报、GitHub 趋势、MCP 生态、开源分析 | 不把未验证资讯当事实 |
+| Janus | 产品策略官 | GPT / Gemini | MVP、SaaS、用户分层、商业化路径 | 不替代工程验收 |
+
+---
+
+## 三、路由原则
+
+- 架构问题先走 Atlas。
+- 建筑行业软件 / 系统深度评价、立项、定位、商业目标和范围取舍先走 Janus。
+- 工程拆解和交付组织先走 Mason。
+- 代码质量、安全和风险审查先走 Argus。
+- 建筑行业知识问题先走 Vitruvius。
+- RAG、MCP、Agent Runtime 问题先走 Daedalus。
+- 具体代码执行和脚本执行先走 Hephaestus。
+- AI 行业情报和开源趋势先走 Mercury。
+- 产品范围、MVP 和商业化路径先走 Janus。
+- AIOS 是建筑行业增强层；普通非建筑任务不强行套用 BIM、IFC、规范、审图或工程证据链假设，优先使用宿主工具的通用能力。
+- 是否启用行业增强，先看项目 profile、`.ai/project-context.md`、README 和当前任务事实。
 
 ---
 
-## 三、路由原则
+## 四、仲裁与 Capability 证据
 
-- 架构问题先走 Atlas。
-- 立项、定位、商业目标和范围取舍先走 Janus。
-- 工程拆解和交付组织先走 Mason。
-- 代码质量、安全和风险审查先走 Argus。
-- 建筑行业知识问题先走 Vitruvius。
-- RAG、MCP、Agent Runtime 问题先走 Daedalus。
-- 具体代码执行和脚本执行先走 Hephaestus。
-- AI 行业情报和开源趋势先走 Mercury。
-- 产品范围、MVP 和商业化路径先走 Janus。
+Agent 之间的冲突不按“谁的模型更强”裁决，而按 `governance/arbitration-protocol.md` 的证据等级裁决。
 
----
+证据优先级摘要：
 
-## 四、成本控制
+1. 人类硬约束和授权。
+2. 确定性工具返回值，例如测试、构建、schema 校验、安全扫描、规范检查和求解器。
+3. 当前项目事实，例如代码、配置、契约、迁移、部署和 CI。
+4. 结构化知识库，例如规范条文、版本、适用地区、来源页码和质量状态。
+5. 专项 Agent 判断。
+6. LLM 自然语言推理。
 
-- 简单分类、摘要、文档整理优先低成本模型。
-- 架构、审查、安全、复杂调试使用高能力模型。
-- 大上下文任务必须先压缩输入，再路由给高成本模型。
-- 执行型任务必须限制工具权限和改动范围。
+Runtime 可通过 `runtime/capability-registry.json` 声明 Capability。Agent 提出阻断或放行结论时，应输出 `Claim / Evidence / Tool Result / Decision`；没有工具实现或证据缺失时，只能标注 `Need verify`。
 
 ---
 
-## 五、上下文控制
-
-- 每个 Agent 只接收完成任务所需的最小上下文。
-- 不把完整仓库、完整聊天记录或无关文档直接塞给执行型 Agent。
-- 长期记忆必须经过整理后进入任务上下文。
-- 路由决策和关键取舍应写入 memory 或决策记录。
-
----
-
-## 六、升级规则
-
-需要升级到 Atlas：
-
-- 涉及服务边界。
-- 涉及数据模型。
-- 涉及长期架构。
-- 涉及模型或 runtime 重大调整。
-
-需要升级到 Argus：
-
-- 涉及权限、安全、Prompt 注入。
-- 涉及生产发布。
-- 涉及依赖升级。
-- 涉及 AI 自动生成大段代码。
-
+## 五、成本控制
+
+- 简单分类、摘要、文档整理优先低成本模型。
+- 架构、审查、安全、复杂调试使用高能力模型。
+- 大上下文任务必须先压缩输入，再路由给高成本模型。
+- 执行型任务必须限制工具权限和改动范围。
+
+---
+
+## 六、上下文控制
+
+- 每个 Agent 只接收完成任务所需的最小上下文。
+- 不把完整仓库、完整聊天记录或无关文档直接塞给执行型 Agent。
+- 长期记忆必须经过整理后进入任务上下文。
+- 路由决策和关键取舍应写入 memory 或决策记录。
+
+---
+
+## 七、升级规则
+
+需要升级到 Atlas：
+
+- 涉及服务边界。
+- 涉及数据模型。
+- 涉及长期架构。
+- 涉及模型或 runtime 重大调整。
+
+需要升级到 Argus：
+
+- 涉及权限、安全、Prompt 注入。
+- 涉及生产发布。
+- 涉及依赖升级。
+- 涉及 AI 自动生成大段代码。
+
 需要升级到 Mason：
 
 - 涉及多模块协同。
 - 涉及 CI/CD。
 - 涉及交付顺序。
 - 涉及团队 workflow。
+
+需要升级到 Euclid：
+
+- 涉及结构力学建模。
+- 涉及荷载、边界条件、截面参数或 FEM。
+- 涉及结构计算工具链输入输出。
+- 涉及结构计算结果解释，但缺少确定性求解器证据。