Agentia — Development skill for Claude Code

Agentia

[中文](./README.md) · [English](./README.en.md)

[](https://github.com/retrychx/agentia/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@migor/agentia) [](LICENSE)

面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。

• 安装与配置
• 快速开始
• 四类能力
• 运行时特性
• 可观测性与成本
• 集成
• API 速查
• 开发本仓库
• 延伸阅读

安装与配置

npm i @migor/agentia                 # 框架（项目依赖）
npm i -g @migor/cli                  # 命令行工具（脚手架 / 生成 / 调试）

agentia create my-app                # 脚手架（含 .env / .env.example）
$EDITOR my-app/.env                  # 填 ANTHROPIC_API_KEY（也可直接 export，真实环境变量优先）
# 可选：ANTHROPIC_BASE_URL（兼容端点）、AGENTIA_MODEL（缺省 claude-opus-5）

框架**不自动**读 `.env`：脚手架 `src/main.ts` 首行的 `loadEnvFile()` 负责把它读进 `process.env`。 真实环境变量优先（CI / docker / 命令行永远赢过文件），`loadEnvFile({ override: true })` 才反过来。

**版本**：`0.5.0`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用 `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见 [`examples/README.md`](examples/README.md) 的「依赖说明」。

**运行时**：Node ≥ 18（`engines` 唯一要求，CI 在 18/20/22 上守）。按 Node 设计并测试， **未对 Deno / edge 做验证**。唯一碰内置模块的 store 是 `SqliteTaskStore`（需 Node ≥ 22.5 的 `node:sqlite`）—— 未提供时**构造期给可读报错**，不影响包本身被导入。

快速开始

两条路线，按需选一即可（也可混用）。

路线 A：CLI 脚手架

agentia create my-app                  # 脚手架新项目（依赖 @migor/agentia）
cd my-app && npm install
agentia g tool weather                 # 生成 src/tools/weather/index.ts 并登记 src/registry.ts
agentia g subagent doc-reviewer        # 生成 src/subagents/doc-reviewer/{index.ts,system.md}
agentia g skill note-writer            # 生成 src/skills/note-writer/index.ts
agentia g prompt style-guide           # 生成 src/prompts/style-guide/{index.ts,a