aillom/casa

# C.A.S.A — Context、Architecture、Stack 与 Automation **一个用于受控 vibe coding 的 agent 原生工程控制平面与 AI 编码 agent 框架。** [Português](README.pt-BR.md) | [Español](README.es.md) C.A.S.A 是一个 agent 原生的工程控制平面，专为使用 AI 编码 agent 来构建、治理和现代化软件的团队而设计。 它不是一个框架、提示词包、编码 agent 或可视化工作流构建器。C.A.S.A 是让编码 agent 在真实软件系统中变得可用的架构层：结构化的 context、架构边界、可复用的能力、基于任务的执行、风险治理以及基于证据的验证。 它也可以被描述为一个 **AI 编码 agent 框架**：一个仓库原生的层，为 agent 提供 context、命令、适配器、策略、任务和验证门，让它们能够减少猜测，并更多地进行基于证据的操作。 目标很简单：保持 vibe coding 的速度，同时不丧失工程控制力。 ## 核心原则 **为 agent 设计。为人类治理。为遗留系统进化。** **一次编写。处处适应。始终验证。** ## 为什么存在 C.A.S.A AI 编码 agent 行动迅速，但如果没有架构，它们会放大常见的工程问题： - 重复的模式 - 架构漂移 - 过时的文档 - 缺失的测试与契约 - 不安全的自动化 - 无法复用的特定工具指令 - 遗留系统中优先重写的行为 - 没有明确事实来源的生成文件 C.A.S.A 将临时的 agent 工作转化为受控的软件交付。 ## 工作原理 C.A.S.A 将稳定的项目知识与特定于 agent 的指令分离开来，并在此基础上增加了基于任务的执行。 ``` .casa Core -> specs -> policies -> standards -> skills -> workflows -> context maps -> governance sensors -> quality gates -> mission templates -> context capsules Adapter generation -> Codex skills -> Cursor rules -> Claude memory and agents -> Devin knowledge -> Copilot instructions -> Antigravity rules and workflows -> Windsurf rules -> Trae context -> Kilo Code instructions -> generic agent guides ``` 规则是：**在 `.casa` 中编写一次，处处适应。** 结果是：**每次任务都以证据结束。** ## 你将获得什么 - **Context**：`AGENTS.md`、规范、策略、仓库映射、领域映射和生成的 agent 指南。 - **Architecture**：边界、依赖方向、API 契约、所有权和现代化路径。 - **Stack**：针对前端、后端、数据库、DevOps、测试和文档的可替换技术栈指南。 - **Stack Composition**：用于 Web、移动端、桌面端、后端、数据库、管理后台、安全和 AI 提供商的受控安装包。 - **Terminal Harness**：用于从终端创建软件的配方、模板、历史记录和引导命令。 - **Skill Marketplace**：通过 commit 锁定来搜索、检查、审计和安装 GitHub skills。 - **Automation**：健康检查、生成的适配器同步检查、CI 门、传感器、安全扫描和漂移检测。 - **Governance**：风险级别、受保护路径、安全策略、权限和审查期望。 - **Modernization**：发现、基线测定、接缝、绞杀者迁移和退役手册。 - **Mission Control**：任务、待办事项、移交、风险门、agent 运行和证据。 - **Quality Gates**：针对架构、安全性、API 契约、UI 质量和遗留安全性的版本化检查。 ## 控制平面模块 C.A.S.A 2.1 由以下几个模块组成： 1. Kernel 2. Context Fabric 3. Capability Layer 4. Mission Control 5. Protocol Layer 6. Governance Engine 7. Modernization Layer 8. Adapter Layer 9. Evidence Ledger 10. Quality Gates ## 支持的 Agent 表面 C.A.S.A 旨在跨 IDE 和编码 agent 工作，而不是将项目锁定在一个产品中。 | 表面 | C.A.S.A 示例 | | --- | --- | | 通用 agents | `AGENTS.md` | | Codex | `.codex/skills/*/SKILL.md` | | Cursor | `.cursor/rules/*.mdc` | | Claude Code | `CLAUDE.md`, `.claude/settings.json`, `.claude/agents/*.md` | | Devin | `knowledge/*.md` | | GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | | Antigravity | `.agents/rules/*.md`, `.agents/workflows/*.md` | | Windsurf | `.windsurf/rules/*.md` | | Trae | `AGENTS.md`, `.agents/*.md`, `.trae/mcp.json` | | Kilo Code | `AGENTS.md`, `CONTEXT.md`, `kilo.jsonc` | | Continue | `.continue/rules/*.md` | | 通用 CLI agents | `AGENT-GUIDE.md` | | 通用网页聊天 | `casa-system-prompt.md` | | 感知 MCP 的 agents | `casa-mcp` stdio server, `context-card.md` | 请从 [docs/agent-ide-examples.md](docs/agent-ide-examples.md) 和 [examples/ide-adapters](examples/ide-adapters) 开始。 ## 快速开始 ### 新项目 ``` mkdir my-app cd my-app npx @aillomai/casa init --mode greenfield ./casa doctor ./casa mission new first-feature --title "First Feature" --mode greenfield ``` ### 现有项目 在你现有仓库的根目录下： ``` cd existing-app npx @aillomai/casa init --mode brownfield ./casa doctor ./casa mission new legacy-discovery --title "Legacy Discovery" --mode brownfield ``` 仅在当你有意要覆盖现有 C.A.S.A 文件时才使用 `--force`。 ### 本仓库 ``` npm ci ./casa check ``` C.A.S.A 提供了一个小型的本地 CLI： ``` ./casa init ../my-app --mode greenfield ./casa doctor ./casa check ./casa verify ./casa spec new auth-login --title "Auth Login" ./casa commands ./casa generate adapters ./casa generate adapters --check ./casa compose --preset ai-fullstack --openrouter --model openai/gpt-5.2 ./casa stack list ./casa stack add frontend:react-app security:web-baseline ./casa guide --goal "build and deploy a SaaS" ./casa recipe plan create-web-saas --name "Customer Portal" ./casa skill search stripe ./casa template list ./casa history list ./casa ai configure openrouter --model openai/gpt-5.2 ./casa mission new invoice-dashboard --title "Invoice Dashboard" --mode greenfield ./casa capsule list ./casa gate list ``` npm 包通过 `npx @aillomai/casa ...` 暴露相同的接口。 初始化后的项目还会获得一个本地 `./casa` 快捷方式和 `.casa/commands.md`。 发布说明位于 [docs/publishing.md](docs/publishing.md)。 ## 日常工作流 1. 首先编辑 C.A.S.A Core 文件，通常在 `.casa` 下。 2. 通过受控的 spec 循环来推进新功能：先运行 `./casa spec new`，然后是 `plan`、`tasks`、`implement`。 3. 当行为发生变化时，更新 specs、策略、文档或示例。 4. 在更改影响 agent 适配器的 Core 文件后，运行 `./casa generate adapters`。 5. 在安装新的应用程序依赖项之前，使用 `./casa compose` 或 `./casa stack add`。 6. 在审查之前运行 `./casa verify --changed` 以执行治理传感器。 7. 在开启或合并 PR 之前运行 `./casa check`。 8. 不要直接编辑生成的适配器文件。 生成的输出包括： - `.codex/skills` - `.cursor/rules` - `.agents/casa-agent-guide.md` - `.casa/generated` ## 采用模式 ### Greenfield 在新项目中从第一天起就使用 C.A.S.A： - 在实现之前编写 specs - 在共享 endpoints 之前定义 API 契约 - 尽早添加测试和 CI 门 - 从单一事实来源生成特定于 agent 的指南 从 [templates/greenfield-next-nest-postgres](templates/greenfield-next-nest-postgres) 开始。 ### Brownfield 将 C.A.S.A 作为覆盖层安装到现有系统上，而无需强制重写： - 在更改之前进行发现 - 映射模块、依赖项、runtime 和风险 - 添加特性化测试或冒烟测试 - 在重构之前创建接缝 - 通过绞杀者模式或逐抽象分支模式进行增量迁移 从 [templates/brownfield-overlay](templates/brownfield-overlay) 开始。 ### 混合模式 在在线产品中选择性地使用 C.A.S.A： - 从受保护路径和策略开始 - 首先只映射高风险或高变动的区域 - 围绕新工作添加 specs - 为你的团队已经在使用的 agents 生成适配器 ## 仓库映射 - `AGENTS.md`：针对编码 agent 的简短通用指令。 - `casa.manifest.yaml`：方法元数据、启用的适配器、治理要求和受保护路径。 - `.casa/kernel`：原则、标准、策略和风险模型的事实来源。 - `.casa/context`：仓库映射、架构映射、领域映射、runtime 映射和遗留清单。 - `.casa/context-capsules`：用于常见工程任务的可复用、范围受限的 context 包。 - `.casa/capabilities`：skills、subagents 和 workflows。 - `.casa/mission-control`：任务、证据、移交、capsule 和风险门模板。 - `.casa/runtime/missions`：可选的持久化任务记录。 - `.casa/protocols`：与 AGENTS.md、Agent Skills、MCP、A2A、OpenAPI 和 AsyncAPI 的对齐。 - `.casa/adapters`：支持的各种 agent 表面的适配器说明。 - `.casa/generated`：生成的适配器包和索引。 - `.casa/specs`：可复用的规范模板。 - `.casa/modernization`：brownfield 发现、基线测定、接缝、绞杀者模式和退役手册。 - `.casa/governance`：权限、受保护文件、危险操作、传感器、评估和审计指南。 - `.casa/quality-gates`：用于任务和 PR 的版本化质量检查。 - `.casa/registry`：skills、agents、适配器、workflows 和策略的索引。 - `.casa/registry/stacks.json`：用于前端、后端、数据库、安全、移动端、桌面端、管理后台和 AI 的受控技术栈包。 - `.casa/registry/recipes.json`：用于软件创建、安全、数据库、AI 和部署 workflows 的预构建终端配方。 - `.casa/registry/skill-marketplace.json`：用于远程 skills 的受信任市场设置。 - `.casa/registry/skills.lock.json`：锁定的外部 skill 安装。 - `.casa/cockpit`：未来的可视化控制平面 IA 和屏幕定义。 - `.codex`, `.cursor`, `.agents`：生成的特定工具输出。 - `templates`：用于 greenfield 和 brownfield 采用的起始结构。 - `examples`：实际使用示例。 - `examples/ide-adapters`：Codex、Cursor、Claude、Devin、Copilot、Antigravity、Windsurf、Trae、Kilo Code 和通用 agents 的示例。 - `docs`：简洁的人类可读文档。 ## 治理 C.A.S.A 期望工作是根据风险进行范围界定、审查和验证的。 - **低风险**：正常验证。 - **中等风险**：建议审查人参与，并在相关时提供测试和契约。 - **高风险**：需人工批准、回滚计划和相关传感器。 - **严重风险**：双人审查和事件级别的变更规划。 受保护路径在 `casa.manifest.yaml` 中声明。策略详情位于 `.casa/kernel/policies`，操作规则位于 `.casa/governance`。 ## 规范与传感器 规范是功能事实的来源。使用 `.casa/specs/templates` 中的模板来编写： - greenfield 功能 - API endpoints - 安全敏感功能 - brownfield 现代化 传感器定义了完成前预期的验证： - lint - typecheck - tests - OpenAPI diff - migration risk - dependency risk - security scan `./casa doctor` 会检查最低限度的 C.A.S.A 结构、策略、规范、context 映射、传感器、mission-control 文件、context capsules、quality gates、注册表和生成的适配器是否存在且保持同步。在这个源代码仓库中，它还会验证 IDE 示例。 ## 示例与文档 - [C.A.S.A 作为 vibe coding 架构](docs/vibe-coding-architecture.md) - [C.A.S.A CLI](docs/cli.md) - [C.A.S.A harness](docs/harness.md) - [Skill marketplace](docs/skill-marketplace.md) - [Stack composition](docs/stack-composition.md) - [发布到 npm](docs/publishing.md) - [Agent 和 IDE 示例](docs/agent-ide-examples.md) - [C.A.S.A cockpit IA](.casa/cockpit/information-architecture.md) - [Greenfield 模式](docs/greenfield-mode.md) - [Brownfield 模式](docs/brownfield-mode.md) - [IDE 适配器示例](examples/ide-adapters) - [发票仪表板示例](examples/invoice-dashboard) - [遗留系统现代化示例](examples/legacy-modernization) ## 手册 长篇公开草案包含在 `CASA_Agent_Native_Architecture_Manual.pdf` 中。 ## 状态 C.A.S.A 处于早期开发阶段。当前仓库包含方法核心、治理文件、初始适配器、示例、模板和本地验证脚本。 ## 许可证 Apache-2.0。详见 [LICENSE](LICENSE)。

标签：AI编程代理, MITM代理, SOC Prime, 上下文管理, 开发工具, 数据管道, 文档结构分析, 暗色界面, 架构治理, 自定义脚本, 软件工程