# Ageniti Agent Bootstrap

如果你是一个本地 coding agent，准备开始使用 Ageniti SDK，请先读这份文件。

你的职责是从 clone 开始自己完成初始化。除非被权限或环境限制卡住，否则不要反过来要求用户手动 clone 仓库。

## 工作范围

- 重点关注 Ageniti SDK 包本身。
- 如果仓库里存在 `ageniti/` 目录，把它视为 package root。
- 除非用户明确要求，否则忽略 `website/`。

## 从 Clone 开始

1. 先 clone 仓库：

```text
git clone https://github.com/Ageniti/ageniti.git
```

2. 判断 package root：

- 如果 clone 下来的仓库根目录本身就是 SDK 包，就直接使用仓库根目录。
- 如果仓库里有 `ageniti/package.json`，就把 `ageniti/` 当作 package root。
- package root 指包含 SDK 源码、文档、测试和 `AGENTS.md` 的目录。

3. 进入 package root 后，按这个顺序阅读：

- `AGENTS.md`
- `docs/getting-started.md`
- `docs/api.md`
- `docs/skill.md`

4. 在 package root 安装依赖：

```text
npm install
```

5. 在动手之前，先查看包脚本和可用命令。

## Ageniti 是什么

Ageniti 是让应用能力可被 Agent、自动化系统和外部工具调用的 action 基础原语层。核心模型是：

```text
existing app capability
  -> action contract
  -> shared runtime
  -> multiple external surfaces
```

## 主要 Surface

这个 SDK 主要会把应用能力暴露到这些入口：

- CLI（支持 `--ndjson` 实时流式输出、`--idempotency-key`、`--timeout-ms`）
- HTTP（细粒度状态码、Content-Type 校验、body 大小上限）
- MCP（stdio 自动识别 Content-Length 与 newline framing）
- OpenAI-compatible tools
- OpenAI Responses tools
- AI SDK tools
- JSON automation
- 类型化 client（进程内或 HTTP，`@ageniti/core/client`）
- 本地 dev console
- React invocation（`@ageniti/core/react-hooks` 提供 `useAction` 状态机 hook）

## 核心原语

- Action contract（`defineAction`）—— 输入/输出 schema、副作用、权限、run。
- 外部 schema 互操作 —— `defineAction({ input: zodSchema })` 通过 duck typing 直接接受 Zod 和 Standard Schema v1。
- 批量注册 —— `defineActions`、`actionFromHandler`、`actionsFromHandlers`，把已有 handler 记录批量包装。
- 流式事件 —— `runtime.stream(name, input)` 返回 async iterable，按顺序 yield `log` / `progress` / `artifact` / `result` 事件，任何消费者都能订阅。
- 类型化 client + codegen —— `createClient` 用 Proxy 调用 action，`generateClientTypes` 输出 `.d.ts` 让消费方拥有完整 IDE 自动补全。
- 测试工具 —— `createTestRuntime`、`expectOk`、`expectError`、`collectStream`、`stubAction`。
- Runtime 控制 —— idempotency key（LRU 上限）、单 action 并发限制、每次 retry attempt 独立 cancel、用于埋点的 hooks、logs/artifact metadata/error message 的脱敏。

## 工作规则

- 把 action contract 当作 source of truth。
- 给 CLI、MCP、HTTP 和 build 使用的 package entry 必须保持 Node-safe。
- 不要从外部 surface 直接调用 `action.run()`。
- 遵守 visibility、permissions、confirmation、side effects 和 supported surfaces。
- 把生成出来的 manifest、schema、`publicMetadata` 和 `GUIDE.md` 视为公开 contract。
- 内部细节放在 `metadata`，不要放进 `publicMetadata`。

## 第一批建议执行的命令

在 package root 里：

```text
npm install
npm test
```

然后再按任务需要使用这些命令：

```text
ageniti doctor
ageniti init host-openai
task-app docs
task-app build
task-app mcp --stdio
```

## 完成标准

你已经清楚：

- 这个 SDK 暴露什么
- package root 的结构是什么
- 哪些文档定义了公开 contract
- 当前任务应该从哪些命令开始

如果还需要更细的说明，继续阅读 package root 下的 `AGENTS.md`。