@archsight/aios 1.0.0

package/docs/ai-team-os-repository-architecture.md

@@ -0,0 +1,459 @@
+# AI Team OS 仓库架构
+
+> ArchSightLabs AI 研发组织操作系统的仓库治理蓝图
+
+状态：规划基线  
+版本：0.1  
+日期：2026-05-07  
+维护方：ArchSightLabs
+
+---
+
+## 文档定位
+
+本文件定义 `archsight-aios` 仓库本身如何组织和治理 AI 研发资产。
+
+它回答的问题是：
+
+- 目录应该怎么分层。
+- Agent、Workflow、Prompt、Skill、Runtime、Knowledge 等资产分别放在哪里。
+- 仓库如何支撑 Hermes / OpenClaw / 飞书机器人等运行实例。
+- 如何避免 prompt、agent、workflow 和 runtime 配置碎片化。
+
+本文件不负责详细定义每个 Agent 的角色分工。Agent 组织结构和角色职责以 [AI Engineering Squad 计划](ai-engineering-squad-plan.md) 为准。
+
+---
+
+## 一、定位升级
+
+如果本仓库只是存放 prompt、agent 配置和一些技能包，长期价值会很有限。
+
+这些资产如果缺少治理结构，会很快碎片化：
+
+- prompt 没有版本和评估，容易腐化。
+- agent 没有职责边界，容易互相污染。
+- skill 没有工具约束和验收标准，容易变成不可复用脚本。
+- runtime 没有路由和权限策略，成本与风险会失控。
+- knowledge 没有结构化入口，无法演进为 GraphRAG 和知识图谱资产。
+
+因此，本仓库应定位为：
+
+> AI 研发组织操作系统（AI Team OS）
+
+也就是由 ArchSightLabs 发起、可被多项目复用的 AI 团队治理中心。
+
+它管理的不是单个聊天机器人，而是建筑行业 AI 研发基础设施：
+
+- 多模型协同
+- 多 Agent 协同
+- 行业知识工程
+- AI Coding Workflow
+- 企业平台研发
+- 行业智能体
+- GraphRAG
+- 受控执行环境
+
+---
+
+## 二、管理范围
+
+| 维度 | 内容 |
+| --- | --- |
+| Agent 定义 | 角色、职责、边界、输入输出、不该做什么 |
+| Workflow | 协作流程、角色编排、验收路径 |
+| Skills | 能力插件、工具清单、示例、约束 |
+| Prompt 体系 | 系统 Prompt、规则、版本、评估、失效案例 |
+| Knowledge | BIM、IFC、规范、招采、结构、审查规则 |
+| Runtime | Hermes / OpenClaw 配置、权限、路由、模型策略 |
+| Governance | 工程治理、安全治理、上下文治理、记忆治理 |
+| Memory | 长期记忆、项目记忆、角色记忆、决策记录 |
+| Experiments | 实验设计、对比验证、模型能力评估 |
+| Standards | 行业标准、企业标准、审查条文、数据标准 |
+| Delivery | AI 生成、Review、测试、发布、回滚、风险控制 |
+| Infra | ECS、Docker、Nginx、OSS、数据库、向量库等基础设施 |
+
+---
+
+## 三、核心目录结构
+
+```text
+archsight-aios/
+│
+├── README.md
+├── AI_CODING_RULES.md
+├── vision/
+├── agents/
+├── workflows/
+├── runtime/
+├── prompts/
+├── skills/
+├── memory/
+├── governance/
+├── standards/
+├── knowledge/
+├── rag/
+├── graph/
+├── delivery/
+├── experiments/
+├── templates/
+├── docs/
+└── infra/
+```
+
+---
+
+## 四、目录职责
+
+### 1. `vision/`
+
+保存项目的长期方向、阶段目标和路线图。
+
+典型内容：
+
+- AI Team OS 愿景
+- ArchSight AI 研发基础设施路线
+- 阶段性目标
+- 战略取舍记录
+
+### 2. `agents/`
+
+Agent 组织定义层。
+
+每个 Agent 不应只保存 prompt，而应保存完整职责契约：
+
+```text
+agents/
+├── atlas/
+│   ├── role.md
+│   ├── system-prompt.md
+│   ├── responsibilities.md
+│   ├── workflow.md
+│   └── constraints.md
+├── mason/
+├── argus/
+├── vitruvius/
+├── daedalus/
+└── hephaestus/
+```
+
+每个 Agent 至少应定义：
+
+- 职责
+- 边界
+- 输入
+- 输出
+- 禁止事项
+- 参与哪些 workflow
+- 使用哪些模型或工具
+
+### 3. `workflows/`
+
+多 Agent 协作流程层，是本仓库的核心资产之一。
+
+典型内容：
+
+- `feature-development.md`
+- `bug-fixing.md`
+- `architecture-review.md`
+- `frontend-generation.md`
+- `rag-pipeline.md`
+- `spec-driven-development.md`
+
+例如 bug fixing 流程可以定义为：
+
+```text
+Argus -> Atlas -> Mason -> Hephaestus -> Argus
+```
+
+并明确：
+
+- 谁发现问题
+- 谁分析根因
+- 谁判断架构影响
+- 谁拆解任务
+- 谁执行修复
+- 谁验收
+
+### 4. `runtime/`
+
+Hermes / OpenClaw 运行治理层。
+
+典型结构：
+
+```text
+runtime/
+├── hermes/
+│   ├── feishu.md
+│   ├── cron-jobs.md
+│   ├── memory-strategy.md
+│   ├── routing.md
+│   ├── permissions.md
+│   └── model-routing.md
+├── openclaw/
+└── gateway/
+```
+
+重点管理：
+
+- 模型路由
+- 权限边界
+- 工具调用策略
+- 记忆策略
+- 飞书集成
+- 定时任务
+- 成本控制
+- agent 调度策略
+
+模型路由示例：
+
+| Agent | 默认模型 | 说明 |
+| --- | --- | --- |
+| Atlas | GPT 系列 | 复杂架构、长期规划、tradeoff |
+| Mason | Gemini / GPT 系列 | 任务组织、工程拆解、研发流程 |
+| Argus | Claude / GPT 系列 | 代码审查、安全和质量分析 |
+| Vitruvius | GPT / 行业知识模型 | BIM、IFC、规范、审图逻辑 |
+| Daedalus | GPT / Codex 系列 | Agent Runtime、RAG、MCP、Tool Calling |
+| Hephaestus | Codex / 执行型模型 | 代码修改、脚本执行、自动化交付 |
+| Mercury | DeepSeek / 搜索增强模型 | 情报、趋势、开源项目分析 |
+
+### 5. `prompts/`
+
+Prompt 资产化目录。
+
+建议结构：
+
+```text
+prompts/
+├── architecture/
+├── frontend/
+├── review/
+├── rag/
+├── graph/
+├── coding/
+├── delivery/
+└── standards/
+```
+
+每个 prompt 应记录：
+
+- 适用范围
+- 版本
+- 输入格式
+- 输出格式
+- 评估方式
+- 已知失效案例
+- 禁止使用场景
+
+### 6. `skills/`
+
+可复用能力插件目录。
+
+建议结构：
+
+```text
+skills/
+├── frontend-design/
+├── react-admin/
+├── graph-rag/
+├── bim-review/
+├── code-review/
+├── postgres/
+└── spec-kit/
+```
+
+每个 skill 应包含：
+
+```text
+skill/
+├── README.md
+├── workflow.md
+├── tools.md
+├── prompts.md
+├── examples/
+└── constraints.md
+```
+
+重点不是写一句 prompt，而是把能力沉淀为可重复执行、可验证、可治理的工作单元。
+
+### 7. `knowledge/`
+
+建筑行业知识操作系统。
+
+建议结构：
+
+```text
+knowledge/
+├── bim/
+├── ifc/
+├── standards/
+├── procurement/
+├── engineering/
+├── structure/
+└── regulations/
+```
+
+未来应支持：
+
+- 自动切 chunk
+- 自动抽取实体和关系
+- 自动构建 GraphRAG
+- 自动构建知识图谱
+- 规范条文结构化
+- 审查规则生成
+
+### 8. `governance/`
+
+AI 工程治理目录。
+
+建议内容：
+
+```text
+governance/
+├── coding-rules.md
+├── ai-review-policy.md
+├── security-policy.md
+├── agent-boundary.md
+├── delivery-policy.md
+├── context-policy.md
+└── memory-policy.md
+```
+
+治理重点：
+
+- 防止 agent 乱调用工具
+- 防止 prompt 泄露
+- 防止上下文爆炸
+- 防止 AI 瞎改代码
+- 防止权限失控
+- 防止未经评审的自动交付
+
+### 9. `delivery/`
+
+受控交付目录。
+
+建议结构：
+
+```text
+delivery/
+├── frontend/
+├── backend/
+├── architecture/
+├── review/
+├── release/
+└── checklists/
+```
+
+重点管理：
+
+- 发布清单
+- Review 流程
+- AI 生成代码检查
+- 自动测试
+- 自动修复
+- 人工确认
+- 回滚策略
+- 风险控制
+
+### 10. `infra/`
+
+AI 研发基础设施目录。
+
+建议结构：
+
+```text
+infra/
+├── ecs/
+├── docker/
+├── nginx/
+├── proxy/
+├── feishu/
+├── oss/
+├── postgres/
+├── neo4j/
+└── vector-db/
+```
+
+重点管理：
+
+- 阿里云 ECS
+- Hermes
+- 飞书集成
+- OpenClaw
+- 多模型接入
+- OSS
+- PostgreSQL
+- Neo4j
+- 向量数据库
+- GraphRAG 基础设施
+
+---
+
+## 五、当前最应该做的事情
+
+### 第一优先级：明确 AIOS 核心治理结构
+
+将仓库从 `archsight-ai-team` 升级为 `archsight-aios` 的内容结构，重点治理：
+
+- runtime
+- workflow
+- governance
+- delivery
+- memory
+
+这些是 AI 研发组织操作系统的骨架。
+
+### 第二优先级：建立统一 Workflow
+
+包括：
+
+- feature 开发
+- bug 修复
+- review
+- release
+- frontend 生成
+
+每个 workflow 都应明确角色路由、输入、输出、验收标准和回滚策略。
+
+### 第三优先级：建立统一 Agent Routing
+
+示例：
+
+| Agent | 默认模型 |
+| --- | --- |
+| Atlas | GPT |
+| Mason | Gemini |
+| Argus | Claude |
+| Mercury | DeepSeek |
+
+如果没有统一路由，成本、上下文和执行权限会失控。
+
+### 边界说明：业务项目 `.ai/`
+
+`.ai/` 是具体业务项目的项目级 AI 治理目录，不属于 `archsight-aios` 根仓库自身的运行目录。
+
+本仓库当前不创建 `.ai/`，只维护可被其他项目继承的统一规范、workflow、routing、governance、delivery 和 memory 规则。
+
+---
+
+## 六、长期方向
+
+本仓库服务的长期方向不是：
+
+- 再做一个聊天机器人
+- 再接一个模型
+- 再试一个 Agent
+
+而是：
+
+> 建筑行业 AI 研发基础设施
+
+核心组成：
+
+- 行业知识层
+- Agent 组织层
+- Workflow 层
+- Runtime 层
+- 受控交付层
+- AI 治理层
+
+这个方向比单纯做一个 SaaS 更底层，也更有长期战略价值。

package/docs/business-expert-guide.md

@@ -0,0 +1,67 @@
+# 业务专家如何参与 ArchSight AIOS 项目
+
+本文面向建筑、设计、施工、审图、造价、招采、规范研究和项目管理专家。你不需要会写代码，也不需要理解所有 Agent 或 Workflow，只需要帮助团队把业务判断讲清楚、把依据留完整。
+
+## 你负责提供什么
+
+业务专家最重要的贡献不是写 prompt，而是提供可验证的业务材料：
+
+| 材料 | 示例 |
+| --- | --- |
+| 规范和标准 | 条文编号、版本、适用地区、适用专业、生效状态。 |
+| 工程样例 | 图纸、BIM 模型、现场图片、缺陷案例、审查记录。 |
+| 术语口径 | 构件、空间、专业、工序、缺陷、等级、验收项的定义。 |
+| 判断规则 | 什么情况下通过、什么情况下不通过、哪些情况需要人工复核。 |
+| 反例 | 容易误判的图纸、图片、模型、条文或业务场景。 |
+| 验收标准 | 输出必须包含什么证据、什么结论不能自动给出。 |
+
+## AIOS 帮你做什么
+
+AIOS 不是替代专家判断，而是把专家判断变成可复用、可审查、可迭代的项目规则。
+
+它可以帮助团队：
+
+- 把规范条文拆成对象、条件、判定、例外和证据。
+- 把 BIM / IFC / Revit / CAD 概念整理成实体、属性和关系。
+- 把施工视觉 AI 的检测结果区分为模型输出、规则推断和人工确认。
+- 为 RAG / GraphRAG 知识库生成评估问题、不可回答问题和来源要求。
+- 为 AI 编码任务补充行业边界，避免把模型推断当成工程结论。
+
+## 你怎么验收
+
+验收 AIOS 产出的业务内容时，重点看五件事：
+
+1. 来源是否清楚：是否写明规范、版本、条文、样例或人工经验来源。
+2. 适用条件是否清楚：是否说明地区、专业、阶段、项目类型和例外情况。
+3. 结论边界是否清楚：是否区分规范原文、工程经验、模型推断和人工确认。
+4. 失败场景是否清楚：是否列出低置信度、遮挡、缺失信息、冲突条文等情况。
+5. 复核点是否清楚：是否标明哪些结论必须由专家或工程负责人确认。
+
+## 推荐工作方式
+
+从一个小范围开始，不要一开始覆盖整个行业知识库。
+
+建议顺序：
+
+1. 选一个具体主题，例如“地下室焊缝检测”“防火分区审查”“IFC 构件分类”。
+2. 准备 5 到 20 个真实样例，包括正确样例和错误样例。
+3. 写清楚术语、判断口径、通过条件和人工复核点。
+4. 让工程团队使用 `archsight-aios init --profile <name>` 接入项目规则。
+5. 根据 AI 输出的错误和遗漏，补充反例、规则和评估问题。
+
+## 不应让 AIOS 做什么
+
+- 不让 AIOS 在缺少规范来源时给出确定合规结论。
+- 不让 AIOS 替代注册工程师、审图机构或项目责任人的最终判断。
+- 不把模型检测结果直接当成工程质量结论。
+- 不把内部资料、未授权图纸、个人信息或涉密项目数据放进公开仓库。
+
+## 常见项目类型
+
+| 项目 | 推荐 profile |
+| --- | --- |
+| BIM / IFC / Revit / CAD 平台 | `bim-platform` |
+| 施工现场图像、视频、缺陷检测 | `construction-vision` |
+| 建筑规范知识库、RAG、GraphRAG | `rag-knowledge` |
+
+业务专家只需要关注 `.ai/project-context.md`、`.ai/profiles/*.md` 和评估样例是否真实、准确、可复核。工程师负责把这些材料接入代码、脚本、测试和发布流程。

package/docs/glossary.md

@@ -0,0 +1,65 @@
+# 术语表
+
+## AIOS
+
+ArchSight AIOS 是一套 AI 规则、Agent、Skill、Workflow 和运行治理工具包。它由 ArchSightLabs 提供，当前重点覆盖建筑行业和工程软件场景，但通用底座可用于其他项目。
+
+## Agent
+
+Agent 是一个内部角色标签，例如建筑数字化专家、代码审查官、AI 研发工程师。Agent 定义职责、边界、输入和输出。普通使用者通常不需要记住 Agent 名字，也不需要手动指定 Agent；AIOS 会根据任务类型、profile、Skill 和 Workflow 做路由。
+
+## Skill
+
+Skill 是可重复执行的能力单元，例如架构评审、交付计划、代码审查、BIM 领域建模。Skill 更接近“怎么做事”。
+
+## Workflow
+
+Workflow 是多步骤工作流，说明一个任务从输入、执行、检查到交付应该怎么流转。
+
+## Profile
+
+Profile 是某类业务项目的补充规则。当前包括：
+
+- `bim-platform`
+- `construction-vision`
+- `rag-knowledge`
+
+## `.ai/`
+
+业务项目中的 AI 规则目录。它保存项目事实、AIOS 补充规则、Agent 路由、Skills、Workflows 和行业 profile。
+
+## `AGENTS.md`
+
+Codex 等 Agent 工具读取的项目入口文件。它告诉 AI 在当前项目中应该先看哪些规则。
+
+## `CLAUDE.md`
+
+Claude Code 读取的项目入口文件。
+
+## `GEMINI.md`
+
+Gemini 读取的项目入口文件。
+
+## `AI_CODING_RULES.md`
+
+项目通用 AI 编码规则。它是项目自己的规则主体，AIOS 不应该随意覆盖它。
+
+## RAG
+
+Retrieval-Augmented Generation，检索增强生成。模型回答前先检索知识源，再基于证据回答。
+
+## GraphRAG
+
+结合知识图谱的 RAG。它不仅检索文本片段，也利用实体、关系、来源和版本信息帮助回答。
+
+## Hermes
+
+可选运行时 Adapter，用于登记和同步运行时 Agent prompt。当前 CLI 只提供校验和 dry-run，不直接执行外部 API 同步；未启用 Hermes 的项目不需要依赖它。
+
+## 业务专家
+
+负责规范、工程语义、样例、判断口径、复核点和验收标准的人，不要求会写代码。
+
+## 人工复核点
+
+AI 不能直接给最终结论、必须由专家或责任人确认的事项。

package/docs/quickstart.md

@@ -0,0 +1,88 @@
+# 快速上手
+
+本文给第一次使用 ArchSight AIOS 的用户。默认你已经安装 Node.js 18 或更高版本。
+
+## 1. 安装到当前用户
+
+```bash
+npx @archsight/aios install --target all --scope user
+```
+
+这一步会把 ArchSight AIOS 的 Skills、Workflows、Runtime 和模板同步到当前用户目录，让 Codex、Gemini、Antigravity 等工具可以读取。
+
+## 2. 检查安装
+
+```bash
+npx @archsight/aios doctor
+```
+
+看到 `Doctor passed.` 表示安装路径、manifest、skills、workflows 和用户级规则入口都能被找到。
+
+## 3. 进入你的业务项目
+
+Windows PowerShell 示例：
+
+```powershell
+cd C:\Work\YourProject
+npx @archsight/aios init
+```
+
+macOS / Linux 示例：
+
+```bash
+cd /work/your-project
+npx @archsight/aios init
+```
+
+`init` 不指定 `--cwd` 时默认使用当前目录。已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 或 `AI_CODING_RULES.md` 的项目不会被覆盖。
+
+## 4. 选择行业 profile
+
+如果项目属于特定类型，可以叠加 profile：
+
+```bash
+npx @archsight/aios init --profile bim-platform
+npx @archsight/aios init --profile construction-vision
+npx @archsight/aios init --profile rag-knowledge
+```
+
+## 5. 检查项目生成结果
+
+业务项目中通常会出现：
+
+```text
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+AI_CODING_RULES.md
+.ai/
+```
+
+`.ai/` 是项目 AI 规则目录。不同 AI 工具会通过根目录入口文件读取这些规则。
+
+## 6. 本地源码开发验证
+
+如果你是从本仓库源码运行：
+
+```bash
+npm run install:user
+npm run doctor
+npm run smoke:project
+npm test
+```
+
+## 常见问题
+
+### 我不是开发人员，需要运行这些命令吗？
+
+通常不需要。业务专家可以先阅读 `docs/business-expert-guide.md`，把规范、样例、判断口径和人工复核点准备好，由工程团队执行初始化命令。
+
+### `init` 会覆盖我项目里的规则吗？
+
+不会。默认模式只创建缺失文件，并在合适的入口文件中追加或刷新 ArchSight AIOS 托管块。
+
+### 我应该用哪个 profile？
+
+- BIM / Revit / CAD / IFC 平台：`bim-platform`
+- 施工视觉 AI、检测、分割、深度估计：`construction-vision`
+- 规范知识库、RAG、GraphRAG：`rag-knowledge`

package/governance/README.md

@@ -0,0 +1,15 @@
+# Governance
+
+`governance/` 保存 AI 工程治理规则。
+
+推荐优先建立：
+
+- [AI 编码规范（公共）](coding-rules.md)
+- [AI Review Policy](ai-review-policy.md)
+- [Security Policy](security-policy.md)
+- [Agent Boundary Policy](agent-boundary.md)
+- [Delivery Policy](delivery-policy.md)
+- [Context Policy](context-policy.md)
+- [Memory Policy](memory-policy.md)
+
+治理目标是防止 agent 乱调用、prompt 泄露、上下文爆炸、AI 瞎改代码、权限失控和未经评审的自动交付。