@archsight/aios 1.0.1 → 1.2.0

package/docs/PUBLIC_DISCOVERY.md

@@ -0,0 +1,193 @@
+# 公共发现与上架清单
+
+本文件记录 ArchSight AIOS 要被公共 skill 生态发现时，项目内需要提供的稳定入口。
+
+结论：公共发现不是单一市场自动收录。AIOS 需要同时满足三类机制：
+
+1. 本地自动发现：宿主扫描 `SKILL.md`、`skills/`、`.agents/skills/`、`.claude/skills/` 或 extension/plugin 目录。
+2. 可分发安装：通过 GitHub、npm/npx、Antigravity/agy、Gemini extension 兼容入口、Claude marketplace、WorkBuddy、`skills.sh` / `npx skills` 安装。
+3. 公共检索：依赖 GitHub topics、manifest、标准目录、README 关键词、release、安装量、star 和主动提交。
+
+## 项目内入口
+
+| 入口 | 文件 | 目的 |
+| --- | --- | --- |
+| 标准 skills 目录 | `skills/` | 让 `skills.sh`、`npx skills`、Antigravity/agy、Gemini extension 和其他标准 skill 索引器直接看到 `aios-*` Skill。 |
+| Gemini extension manifest | `gemini-extension.json` | 保留 Gemini CLI extension 兼容入口和 Gallery / 第三方索引 manifest。 |
+| Claude marketplace manifest | `.claude-plugin/marketplace.json` | 允许 Claude Code 用户通过 marketplace 方式发现本项目。 |
+| Claude plugin manifest | `.claude-plugin/plugin.json` | 描述插件元数据，并把插件 skills 指向 `./skills/`。 |
+| WorkBuddy adapter | `adapters/workbuddy/README.md` | 说明如何把 `aios-*` Skill 安装到 `~/.workbuddy/skills/`。 |
+| npm metadata | `package.json` | 提供英文检索关键词、分发文件清单和 `validate:skills` 校验入口。 |
+| 发现校验脚本 | `scripts/validate-skills.mjs` | 校验 manifest、skill frontmatter、跨 host manifest 和 npm metadata 是否一致。 |
+
+## GitHub About 建议
+
+这些内容需要在 GitHub 仓库页面右侧 About 区手动设置，不能只靠代码文件完成。
+
+策略：默认展示中文，紧跟一段英文检索短语。中文用户能直接看懂项目定位，英文用户和索引器也能通过 `building-industry AI agent skills`、`project evidence work`、`BIM`、`IFC`、`GraphRAG`、`code review` 等词命中。
+
+Description：
+
+```text
+面向建筑行业知识工作从业者与 AI 研发团队的 Skills、Workflow 与多 Agent 工具包 / Building-industry AI agent skills for BIM, IFC, RAG, GraphRAG, project evidence work, code review, and runtime governance.
+```
+
+Website：
+
+```text
+https://github.com/ArchSightLabs/archsight-aios
+```
+
+Topics：
+
+```text
+agent-skills
+building-ai
+construction-ai
+aec
+bim
+ifc
+building-code
+graphrag
+mcp
+codex
+claude-code
+gemini-cli-extension
+antigravity
+architecture-review
+code-review
+design-review
+runtime-design
+structural-engineering
+tender-review
+construction-management
+```
+
+Pinned README 搜索摘要可使用：
+
+```text
+默认中文输出，保留英文检索能力：building-industry AI, project evidence work, BIM, IFC, building code, RAG, GraphRAG, MCP, architecture review, code review, runtime governance, structural review, construction management.
+```
+
+## 公共安装命令
+
+`skills.sh` / Vercel skills CLI：
+
+```powershell
+npx skills add ArchSightLabs/archsight-aios --list
+npx skills add ArchSightLabs/archsight-aios --skill aios-arch --global
+```
+
+Codex：
+
+```powershell
+npx @archsight/aios install --target codex --scope user
+```
+
+Antigravity / agy：
+
+```powershell
+npx @archsight/aios install --target antigravity --scope user
+```
+
+Gemini CLI extension 兼容入口：
+
+```powershell
+gemini extensions install https://github.com/ArchSightLabs/archsight-aios
+```
+
+Gemini 用户级支持资产：
+
+```powershell
+npx @archsight/aios install --target gemini --scope user
+```
+
+WorkBuddy：
+
+```powershell
+npx @archsight/aios install --target workbuddy --scope user
+```
+
+Claude Code marketplace：
+
+```text
+/plugin marketplace add ArchSightLabs/archsight-aios
+/plugin install archsight-aios@archsight
+```
+
+## 对外搜索词
+
+README、release、npm、GitHub topics 和 launch post 应优先覆盖这些关键词：
+
+```text
+agent skills
+AI agent skills
+Codex skills
+Claude Code skills
+Gemini CLI extension
+Antigravity CLI
+construction AI
+building AI
+building-industry AI
+AEC AI
+project evidence work
+BIM
+IFC
+building code
+building code review
+smart drawing review
+architecture review
+technical design review
+code review
+runtime design
+runtime governance
+MCP
+GraphRAG
+RAG
+structural review
+construction daily
+tender review
+contract evidence chain
+```
+
+## find-skills / skills.sh 索引请求模板
+
+如果 `npx skills find` 搜不到本项目，可向对应社区或仓库提交索引请求：
+
+```text
+Repository: https://github.com/ArchSightLabs/archsight-aios
+Package: @archsight/aios
+License: Apache-2.0
+Supported agents: Codex, Claude Code, Antigravity/agy, Gemini CLI, WorkBuddy, OpenCode, Hermes
+Canonical skill path: skills/
+Install command: npx skills add ArchSightLabs/archsight-aios --list
+NPM install command: npx @archsight/aios install --target all --scope user
+Representative skills: aios-arch, aios-design, aios-plan, aios-exec, aios-review, aios-knowledge, aios-structural, aios-runtime, aios-commercial-tender, aios-construction-daily
+Keywords: agent skills, construction AI, BIM, IFC, building code, GraphRAG, architecture review, design review, code review, runtime design, MCP, structural review, tender review, construction management
+```
+
+## 发布前检查
+
+每次发版前至少验证：
+
+```powershell
+npm run validate:skills
+npx skills add . --list
+npm test
+```
+
+如果本机安装了对应 CLI，再验证：
+
+```powershell
+gemini extensions validate .
+claude plugin validate .
+```
+
+## 参考
+
+- Codex Agent Skills: https://developers.openai.com/codex/skills
+- OpenAI skills catalog: https://github.com/openai/skills
+- Claude Code plugin marketplace: https://code.claude.com/docs/en/plugin-marketplaces
+- Claude Code plugin reference: https://code.claude.com/docs/en/plugins-reference
+- Gemini CLI extension releasing: https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/releasing.md
+- Vercel skills CLI discovery: https://github.com/vercel-labs/skills

package/docs/quickstart.md

@@ -23,7 +23,8 @@ npx @archsight/aios doctor
 Windows PowerShell 示例：
 
 ```powershell
-cd C:\Work\YourProject
+$projectPath = "<你的业务项目绝对路径>"
+cd $projectPath
 npx @archsight/aios init
 ```
 

package/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "archsight-aios",
+  "version": "1.2.0",
+  "description": "面向建筑行业知识工作从业者与 AI 研发团队的 Skills、Workflow 与多 Agent 工具包 / Building-industry AI agent skills for BIM, IFC, RAG, GraphRAG, project evidence work, code review, and runtime governance.",
+  "contextFileName": "GEMINI.md"
+}

package/governance/README.md

@@ -8,8 +8,11 @@
 - [AI Review Policy](ai-review-policy.md)
 - [Security Policy](security-policy.md)
 - [Agent Boundary Policy](agent-boundary.md)
+- [Capability-Backed Arbitration Protocol](arbitration-protocol.md)
 - [Delivery Policy](delivery-policy.md)
 - [Context Policy](context-policy.md)
 - [Memory Policy](memory-policy.md)
 
 治理目标是防止 agent 乱调用、prompt 泄露、上下文爆炸、AI 瞎改代码、权限失控和未经评审的自动交付。
+
+多 Agent 产生逻辑冲突时，优先按 `arbitration-protocol.md` 的证据等级处理：确定性工具、项目事实和结构化知识优先于 Agent 自然语言判断；涉及生产授权、法规合规最终结论、结构安全结论和商业范围取舍时升级给人类负责人。

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,7 +1,7 @@
 {
   "name": "@archsight/aios",
-  "version": "1.0.1",
-  "description": "面向建筑 AI 研发的规则、Skill、Workflow 与多 Agent 项目接入工具包。",
+  "version": "1.2.0",
+  "description": "面向建筑行业知识工作从业者与 AI 研发团队的 Skills、Workflow 与多 Agent 工具包 / Building-industry AI agent skills for BIM, IFC, RAG, GraphRAG, project evidence work, code review, and runtime governance.",
   "type": "module",
   "homepage": "https://github.com/ArchSightLabs/archsight-aios#readme",
   "repository": {
@@ -11,34 +11,52 @@
   "bugs": {
     "url": "https://github.com/ArchSightLabs/archsight-aios/issues"
   },
-  "keywords": [
-    "ai",
-    "agents",
-    "architecture",
-    "bim",
-    "ifc",
-    "rag",
-    "graphrag",
-    "construction",
-    "codex",
-    "antigravity",
-    "claude-code"
-  ],
+  "keywords": [
+    "ai",
+    "agents",
+    "architecture",
+    "bim",
+    "ifc",
+    "rag",
+    "graphrag",
+    "construction",
+    "construction-ai",
+    "building-ai",
+    "aec",
+    "building-code",
+    "project-evidence-work",
+    "agent-skills",
+    "ai-agent",
+    "codex",
+    "gemini-cli",
+    "antigravity",
+    "claude-code",
+    "workbuddy",
+    "skills-sh",
+    "mcp",
+    "runtime-governance",
+    "architecture-review",
+    "code-review",
+    "design-review"
+  ],
   "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"
-  },
+  "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",
+    "validate:skills": "node ./scripts/validate-skills.mjs",
+    "test": "node ./tests/cli.test.mjs"
+  },
   "engines": {
     "node": ">=18"
   },
-  "files": [
-    "bin/",
-    "skills/",
+  "files": [
+    "bin/",
+    "scripts/",
+    "adapters/",
+    "skills/",
     "workflows/",
     "templates/",
     "runtime/",
@@ -52,11 +70,14 @@
     "standards/",
     "infra/",
     "prompts/",
-    "vision/",
-    "docs/",
-    "LICENSE",
-    "CHANGELOG.md",
-    "CONTRIBUTING.md",
+    "vision/",
+    "docs/",
+    ".claude-plugin/",
+    "gemini-extension.json",
+    "LICENSE",
+    "CHANGELOG.md",
+    "RELEASE_NOTES.md",
+    "CONTRIBUTING.md",
     "SECURITY.md",
     "CODE_OF_CONDUCT.md",
     "README.md",
@@ -65,5 +86,5 @@
     "CLAUDE.md",
     "GEMINI.md"
   ],
-  "license": "MIT"
-}
+  "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

@@ -26,10 +26,10 @@
 | 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、刚度矩阵、荷载分析 | 不在未验证公式时输出工程结论 |
+| 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、用户分层、商业化路径 | 不替代工程验收 |
@@ -48,11 +48,28 @@
 - AI 行业情报和开源趋势先走 Mercury。
 - 产品范围、MVP 和商业化路径先走 Janus。
 - AIOS 是建筑行业增强层；普通非建筑任务不强行套用 BIM、IFC、规范、审图或工程证据链假设，优先使用宿主工具的通用能力。
-- 是否启用行业增强，先看项目 profile、`.ai/project-context.md`、README 和当前任务事实。
-
----
-
-## 四、成本控制
+- 是否启用行业增强，先看项目 profile、`.ai/project-context.md`、README 和当前任务事实。
+
+---
+
+## 四、仲裁与 Capability 证据
+
+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`。
+
+---
+
+## 五、成本控制
 
 - 简单分类、摘要、文档整理优先低成本模型。
 - 架构、审查、安全、复杂调试使用高能力模型。
@@ -61,7 +78,7 @@
 
 ---
 
-## 五、上下文控制
+## 六、上下文控制
 
 - 每个 Agent 只接收完成任务所需的最小上下文。
 - 不把完整仓库、完整聊天记录或无关文档直接塞给执行型 Agent。
@@ -70,7 +87,7 @@
 
 ---
 
-## 六、升级规则
+## 七、升级规则
 
 需要升级到 Atlas：
 
@@ -86,9 +103,16 @@
 - 涉及依赖升级。
 - 涉及 AI 自动生成大段代码。
 
-需要升级到 Mason：
-
-- 涉及多模块协同。
-- 涉及 CI/CD。
-- 涉及交付顺序。
-- 涉及团队 workflow。
+需要升级到 Mason：
+
+- 涉及多模块协同。
+- 涉及 CI/CD。
+- 涉及交付顺序。
+- 涉及团队 workflow。
+
+需要升级到 Euclid：
+
+- 涉及结构力学建模。
+- 涉及荷载、边界条件、截面参数或 FEM。
+- 涉及结构计算工具链输入输出。
+- 涉及结构计算结果解释，但缺少确定性求解器证据。