0xjeffro/astroclaw

# AstroClaw：云原生 AI Agent **AstroClaw** 是一个*云原生* AI agent 框架。它将传统的长期运行单体进程拆分为单一职责的 serverless 组件，同时利用云平台成熟的生态系统来实现可观测性、身份验证、安全性等功能。 开箱即用，AstroClaw agents 具有*安全*、*可扩展*的特点，并且在空闲时几乎*零成本*。 整个基础设施栈被定义为代码（IaC），可以通过单个命令进行部署。 ``` 🚧 Still early alpha. ~8 weeks to beta. Things will break, and a lot more is coming. Feedback is welcome. ``` ## 前置条件 - Go 1.22+ - Docker（用于本地 PostgreSQL） - OpenAI 或 Anthropic API key ## 本地运行 ``` # 使用 Anthropic ANTHROPIC_API_KEY=sk-ant-xxx go run . # 或使用 OpenAI OPENAI_API_KEY=sk-xxx go run . ``` 临时 PostgreSQL 容器会自动启动。进程退出时数据将丢失。 要在重启后保留数据，请使用现有的数据库： ``` DATABASE_URL="postgres://user:pass@localhost:5432/astroclaw" \ ANTHROPIC_API_KEY=sk-ant-xxx go run . ``` ## 数据库 CDK 部署目前默认使用 Aurora DSQL。未来的版本将添加配置选项，以便在 DSQL 和 Aurora PostgreSQL 之间进行选择。 - **DSQL**：成本较低（真正的 serverless 按需付费，可缩减至零）。适用于大多数工作负载。 - **Aurora PostgreSQL**：完整的 PostgreSQL 功能集（JSONB 列、外键、扩展）。如果您需要向量搜索（pgvector）或其他高级查询功能，请选择此项。 ## 部署到 AWS ### 前置条件 1. 安装 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) aws --version 2. 安装 [CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting-started.html) npm install -g aws-cdk cdk --version 3. 配置 AWS credentials aws configure aws sts get-caller-identity ### 部署 我们提供了一个交互式脚本，它会引导您完成 API key 设置并自动生成运行命令： ``` ./scripts/deploy.sh ``` 或者，您可以直接运行 CDK 命令： ``` cd deploy/aws/infra npm install cdk bootstrap # one-time per account/region: creates an S3 bucket and IAM roles that CDK needs to upload assets and deploy stacks. Skip this if you've bootstrapped this account/region before. cdk deploy --parameters AnthropicApiKey= --parameters GenerateApiKey=true ``` 部署完成后，终端输出中将会打印出 API URL。 ### 运行 TUI ``` API_URL= \ REPLY_URL= \ WS_URL= \ API_KEY= \ go run ./tui/ ``` 将值替换为 `cdk deploy` 的输出。或者使用 `./scripts/deploy.sh`，它会自动生成该命令。 ### 运行 CLI（最小化，用于测试） ``` API_URL= \ REPLY_URL= \ WS_URL= \ API_KEY= \ go run main.go ``` ## 开发 - [安装或更新到最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - [AWS CDK 入门](https://docs.aws.amazon.com/cdk/v2/guide/getting-started.html) ### App 开发 App 被划分为两类，具有不同的安全边界： **System Apps**（例如 Chat、Calendar、Task） - 由项目维护者维护。 - 共享单个 Lambda 和数据库连接。 - 访问控制是在代码层面强制执行的：每个 App 只导入它自己的 `db.Queries` 包。 - 使用 `DbConnectAdmin`（完全数据库访问权限），因为代码是受信任的。 **第三方 Apps**（未来） - 由外部贡献者开发。 - 每个第三方 App 在其自己的 Lambda 中运行，并带有专用的数据库 Role，仅限访问其创建/拥有的表。 - IAM 权限：`dsql:DbConnect`（非 Admin）。 - 通过 `GRANT CONNECT TO '' WITH ` 进行数据库角色映射。 - 更多细节有待规划和讨论。 本节涵盖 System App 开发。 App 在 `apps/` 目录中开发。每个 App 都有自己的子目录（例如 `apps/chat/`），通常具有以下结构： ``` pkg/app/chat/ ├── db/ │ ├── schema.sql # table definitions for this App │ ├── queries.sql # SQL queries with sqlc annotations │ ├── db.go # generated by sqlc: Queries struct, New(), WithTx() │ ├── models.go # generated by sqlc: Go types matching table columns │ └── queries.sql.go # generated by sqlc: type-safe Go functions for each query ├── types.go # business types (Session, Message) and DB-to-domain conversion ├── service.go # business logic (NewSession, Reply, etc.) ├── utils.go # helper functions (type conversion between provider and chat) └── service_test.go # integration tests ``` ### 创建新 App 1. 创建 App 目录和 db 子目录： pkg/app//db/ 2. 在 db 目录中编写 `schema.sql`。在此处定义您的表。 3. 在 db 目录中编写 `queries.sql`。使用 [sqlc annotations](https://docs.sqlc.dev/en/latest/reference/query-annotations.html) 定义您的 SQL 查询。 4. 将 App 的 db 配置添加到项目根目录的 `sqlc.yaml` 中（以现有的 chat 条目为模板）。 5. 在 `atlas.hcl` 中的 `src` 列表下添加 App 的 schema 路径，以便 Atlas 了解新表。 6. 从项目根目录运行 `sqlc generate`。这会在您的 db 目录中自动生成 `db.go`、`models.go` 和 `queries.sql.go`。 7. 编写您的业务逻辑：`types.go`、`service.go` 等。 8. 部署前，请运行 `atlas migrate diff --env local` 为您的新表生成 migration 文件。 ### 在 schema/query 更改后生成代码 ``` sqlc generate ``` ### 部署前生成 migration 文件 ``` atlas migrate diff --env local ``` ### 运行测试 ``` go test -count=1 $(go list ./... 2>/dev/null | grep -v infra) ``` `-count=1` 禁用测试缓存。`grep -v infra` 排除了 CDK 目录，该目录下的 `node_modules` 中包含的 Go template 文件会破坏 `go test`。 测试通过 testcontainers 自动启动一个 PostgreSQL 容器。无需手动设置。 ### CDK 测试 ``` cd deploy/aws/infra npx jest ``` 如果您更改了 CDK stack，快照测试将会失败。审查 diff，然后更新快照： ``` npx jest --updateSnapshot ``` ### 销毁 要销毁所有已部署的 AWS 资源： ``` cd deploy/aws/infra cdk destroy ``` ## 致谢 AstroClaw 的设计受到了以下项目理念的启发：[openclaw](https://github.com/openclaw/openclaw)， [picoclaw](https://github.com/sipeed/picoclaw)， [opencode](https://github.com/anomalyco/opencode)，以及 [hermes-agent](https://github.com/NousResearch/hermes-agent)。 我们感谢作者们将其作品开源。

标签：AWS CDK, EVTX分析, Go语言, MITM代理, Petitpotam, Serverless, 日志审计, 测试用例, 程序破解, 请求拦截