open-gitagent/gitagent
GitHub: open-gitagent/gitagent
一个通用型 git-native AI Agent 框架，将 Agent 的身份、记忆、规则和工具全部定义为受 git 版本控制的文件。
Stars: 539 | Forks: 114
Gitagent
一个通用的 git-native 多模态持续学习 AI Agent (TinyHuman)
你的 agent 生存于一个 git repo 中 —— 身份、规则、记忆、工具和技能都是受版本控制的文件。
安装 •
快速开始 •
SDK •
架构 •
工具 •
Hooks •
技能 •
插件
## 为什么选择 Gitagent？
大多数 agent 框架将配置视为散布在应用程序各处的代码。Gitagent 颠覆了这一点 —— **你的 agent 就是一个 git 仓库**：
- **`agent.yaml`** — 模型、工具、运行时配置
- **`SOUL.md`** — 个性与身份
- **`RULES.md`** — 行为约束
- **`memory/`** — 拥有完整历史的 git 提交记录
- **`tools/`** — 声明式 YAML 工具定义
- **`skills/`** — 可组合的技能模块
- **`hooks/`** — 生命周期 Hooks（脚本或编程方式）
Fork 一个 agent。Branch 一个个性。用 `git log` 查看 agent 的记忆。Diff 它的规则。这就是 **agents as repos**。
## 一键安装
复制，粘贴，运行。就这么简单 —— 无需 clone，无需手动设置。安装程序会处理一切：
```
bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh?$(date +%s)")
```
这将会：
- 通过 npm 全局安装 gitagent
- 引导你完成 API key 设置（快速或高级模式）
- 在你的浏览器中启动语音 UI，地址为 `http://localhost:3333`
### 或者手动安装：
```
# Slim CLI + SDK (recommended in sandboxed/CI environments where supply-chain
# scanners reject larger bundles)
npm install -g @open-gitagent/gitagent
# Add voice mode + web UI (the same web UI install.sh launches at :3333)
npm install -g @open-gitagent/voice
```
`install.sh` 默认会安装两个包。在执行 curl-bash 命令之前设置 `GITAGENT_SLIM=1` 可以跳过语音安装。
## 从 1.x 迁移到 2.0
语音模式现在位于 `@open-gitagent/voice` 中。原因是：作为单个 bundle，该包被一些供应链扫描工具拦截，因为其标记了 3,800 行的 `dist/voice/ui.html` 和未使用的 `baileys` 依赖。将语音功能拆分出去使精简核心 tarball 包从 ~180 kB 降至 ~85 kB，并彻底消除了扫描工具的触发。
```
# If you were on v1.x and used voice:
npm install -g @open-gitagent/gitagent@latest @open-gitagent/voice
# If you only use the SDK / non-voice CLI:
npm install -g @open-gitagent/gitagent@latest
```
`gitagent` 命令和 `@open-gitagent/gitagent` SDK 的导出保持不变。
`gitagent --voice` 会动态加载 `@open-gitagent/voice`；如果未安装该包，它将打印一行安装提示并正常退出。
## 快速开始
**一行代码运行你的第一个 agent：**
```
export OPENAI_API_KEY="sk-..."
gitagent --dir ~/my-project "Explain this project and suggest improvements"
```
就这样。Gitagent 会在首次运行时自动搭建一切 —— `agent.yaml`、`SOUL.md`、`memory/` —— 并让你直接进入该 agent。
### 本地仓库模式
Clone 一个 GitHub 仓库，在其上运行一个 agent，自动提交并推送到一个 session branch：
```
gitagent --repo https://github.com/org/repo --pat ghp_xxx "Fix the login bug"
```
恢复一个现有的会话：
```
gitagent --repo https://github.com/org/repo --pat ghp_xxx --session gitagent/session-a1b2c3d4 "Continue"
```
Token 可以来自环境变量，而不是使用 `--pat`：
```
export GITHUB_TOKEN=ghp_xxx
gitagent --repo https://github.com/org/repo "Add unit tests"
```
### CLI 选项
| 标志 | 简写 | 描述 |
|---|---|---|
| `--dir
` | `-d` | Agent 目录（默认：cwd） |
| `--repo ` | `-r` | 要 clone 并在其上工作的 GitHub 仓库 URL |
| `--pat ` | | GitHub PAT（或设置 `GITHUB_TOKEN` / `GIT_TOKEN`） |
| `--session ` | | 恢复一个现有的会话 branch |
| `--model ` | `-m` | 覆盖模型（例如 `anthropic:claude-sonnet-4-5-20250929`） |
| `--sandbox` | `-s` | 在 sandbox VM 中运行 |
| `--prompt ` | `-p` | 单次提示（跳过 REPL） |
| `--env ` | `-e` | 环境配置 |
### SDK
```
import { query } from "gitagent";
// Simple query
for await (const msg of query({
prompt: "List all TypeScript files and summarize them",
dir: "./my-agent",
model: "openai:gpt-4o-mini",
})) {
if (msg.type === "delta") process.stdout.write(msg.content);
if (msg.type === "assistant") console.log("\n\nDone.");
}
// Local repo mode via SDK
for await (const msg of query({
prompt: "Fix the login bug",
model: "openai:gpt-4o-mini",
repo: {
url: "https://github.com/org/repo",
token: process.env.GITHUB_TOKEN!,
},
})) {
if (msg.type === "delta") process.stdout.write(msg.content);
}
```
## SDK
SDK 提供了一个用于操作 Gitagent agent 的编程接口。它借鉴了 [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk) 的模式，但**在进程内（in-process）**运行 —— 没有 subprocess，没有 IPC。
### `query(options): Query`
返回一个 `AsyncGenerator`，用于流式传输 agent 事件。
```
import { query } from "gitagent";
for await (const msg of query({
prompt: "Refactor the auth module",
dir: "/path/to/agent",
model: "anthropic:claude-sonnet-4-5-20250929",
})) {
switch (msg.type) {
case "delta": // streaming text chunk
process.stdout.write(msg.content);
break;
case "assistant": // complete response
console.log(`\nTokens: ${msg.usage?.totalTokens}`);
break;
case "tool_use": // tool invocation
console.log(`Tool: ${msg.toolName}(${JSON.stringify(msg.args)})`);
break;
case "tool_result": // tool output
console.log(`Result: ${msg.content}`);
break;
case "system": // lifecycle events & errors
console.log(`[${msg.subtype}] ${msg.content}`);
break;
}
}
```
### `tool(name, description, schema, handler): GCToolDefinition`
定义 agent 可以调用的自定义工具：
```
import { query, tool } from "gitagent";
const search = tool(
"search_docs",
"Search the documentation",
{
properties: {
query: { type: "string", description: "Search query" },
limit: { type: "number", description: "Max results" },
},
required: ["query"],
},
async (args) => {
const results = await mySearchEngine(args.query, args.limit ?? 10);
return { text: JSON.stringify(results), details: { count: results.length } };
},
);
for await (const msg of query({
prompt: "Find docs about authentication",
tools: [search],
})) {
// agent can now call search_docs
}
```
### Hooks
用于门控、日志记录和控制的编程式生命周期 Hooks：
```
for await (const msg of query({
prompt: "Deploy the service",
hooks: {
preToolUse: async (ctx) => {
// Block dangerous operations
if (ctx.toolName === "cli" && ctx.args.command?.includes("rm -rf"))
return { action: "block", reason: "Destructive command blocked" };
// Modify arguments
if (ctx.toolName === "write" && !ctx.args.path.startsWith("/safe/"))
return { action: "modify", args: { ...ctx.args, path: `/safe/${ctx.args.path}` } };
return { action: "allow" };
},
onError: async (ctx) => {
console.error(`Agent error: ${ctx.error}`);
},
},
})) {
// ...
}
```
### QueryOptions 参考
| 选项 | 类型 | 描述 |
|---|---|---|
| `prompt` | `string \| AsyncIterable` | 用户提示或多轮对话流 |
| `dir` | `string` | Agent 目录（默认：`cwd`） |
| `model` | `string` | `"provider:model-id"` |
| `env` | `string` | 环境配置（`config/.yaml`） |
| `systemPrompt` | `string` | 覆盖已发现的系统提示 |
| `systemPromptSuffix` | `string` | 追加到已发现的系统提示末尾 |
| `tools` | `GCToolDefinition[]` | 额外的工具 |
| `replaceBuiltinTools` | `boolean` | 跳过 cli/read/write/memory |
| `allowedTools` | `string[]` | 工具名称允许列表 |
| `disallowedTools` | `string[]` | 工具名称拒绝列表 |
| `repo` | `LocalRepoOptions` | Clone 一个 GitHub 仓库并在一个会话 branch 上工作 |
| `sandbox` | `SandboxOptions \| boolean` | 在 sandbox VM 中运行（与 `repo` 互斥） |
| `hooks` | `GCHooks` | 编程式生命周期 Hooks |
| `maxTurns` | `number` | 最大 agent 轮数 |
| `abortController` | `AbortController` | 取消信号 |
| `constraints` | `object` | `temperature`, `maxTokens`, `topP`, `topK` |
### 消息类型
| 类型 | 描述 | 关键字段 |
|---|---|---|
| `delta` | 流式文本/思考块 | `deltaType`, `content` |
| `assistant` | 完整的 LLM 响应 | `content`, `model`, `usage`, `stopReason` |
| `tool_use` | 工具调用 | `toolName`, `args`, `toolCallId` |
| `tool_result` | 工具输出 | `content`, `isError`, `toolCallId` |
| `system` | 生命周期事件 | `subtype`, `content`, `metadata` |
| `user` | 用户消息（多轮对话） | `content` |
## 架构
```
my-agent/
├── agent.yaml # Model, tools, runtime config
├── SOUL.md # Agent identity & personality
├── RULES.md # Behavioral rules & constraints
├── DUTIES.md # Role-specific responsibilities
├── memory/
│ └── MEMORY.md # Git-committed agent memory
├── tools/
│ └── *.yaml # Declarative tool definitions
├── skills/
│ └── /
│ ├── SKILL.md # Skill instructions (YAML frontmatter)
│ └── scripts/ # Skill scripts
├── workflows/
│ └── *.yaml|*.md # Multi-step workflow definitions
├── agents/
│ └── / # Sub-agent definitions
├── plugins/
│ └── / # Local plugins (plugin.yaml + tools/hooks/skills)
├── hooks/
│ └── hooks.yaml # Lifecycle hook scripts
├── knowledge/
│ └── index.yaml # Knowledge base entries
├── config/
│ ├── default.yaml # Default environment config
│ └── .yaml # Environment overrides
├── examples/
│ └── *.md # Few-shot examples
└── compliance/
└── *.yaml # Compliance & audit config
```
### Agent 清单 (`agent.yaml`)
```
spec_version: "0.1.0"
name: my-agent
version: 1.0.0
description: An agent that does things
model:
preferred: "anthropic:claude-sonnet-4-5-20250929"
fallback: ["openai:gpt-4o"]
constraints:
temperature: 0.7
max_tokens: 4096
tools: [cli, read, write, memory]
runtime:
max_turns: 50
timeout: 120
# Optional
extends: "https://github.com/org/base-agent.git"
skills: [code-review, deploy]
delegation:
mode: auto
compliance:
risk_level: medium
human_in_the_loop: true
```
## 工具
### 内置工具
| 工具 | 描述 |
|---|---|
| `cli` | 执行 shell 命令 |
| `read` | 分页读取文件 |
| `write` | 写入/创建文件 |
| `memory` | 加载/保存 git 提交的记忆 |
### 声明式工具
将工具定义为 `tools/` 目录下的 YAML：
```
# tools/search.yaml
name: search
description: Search the codebase
input_schema:
properties:
query:
type: string
description: Search query
path:
type: string
description: Directory to search
required: [query]
implementation:
script: search.sh
runtime: sh
```
脚本通过 stdin 接收 JSON 格式的参数，并通过 stdout 返回输出。
## Hooks
`hooks/hooks.yaml` 中的基于脚本的 Hooks：
```
hooks:
on_session_start:
- script: validate-env.sh
description: Check environment is ready
pre_tool_use:
- script: audit-tools.sh
description: Log and gate tool usage
post_response:
- script: notify.sh
on_error:
- script: alert.sh
```
Hook 脚本通过 stdin 接收 JSON 格式的 context，并返回：
```
{ "action": "allow" }
{ "action": "block", "reason": "Not permitted" }
{ "action": "modify", "args": { "modified": "args" } }
```
## 技能
技能是位于 `skills//` 中的可组合指令模块：
```
skills/
code-review/
SKILL.md
scripts/
lint.sh
```
```
---
name: code-review
description: Review code for quality and security
---
# Code Review
When reviewing code:
1. Check for security vulnerabilities
2. Verify error handling
3. Run the lint script for style checks
```
通过 CLI 调用：`/skill:code-review Review the auth module`
## 插件
插件是可重用的扩展，可以提供工具、Hooks、技能、提示和记忆层。它们遵循相同的 git-native 理念 —— 一个插件就是一个包含 `plugin.yaml` 清单的目录。
### CLI 命令
```
# Install from git URL
gitagent plugin install https://github.com/org/my-plugin.git
# Install from local path
gitagent plugin install ./path/to/plugin
# Install with options
gitagent plugin install --name custom-name --force --no-enable
# List all discovered plugins
gitagent plugin list
# Enable / disable
gitagent plugin enable my-plugin
gitagent plugin disable my-plugin
# Remove
gitagent plugin remove my-plugin
# Scaffold a new plugin
gitagent plugin init my-plugin
```
| 标志 | 描述 |
|---|---|
| `--name ` | 自定义插件名称（默认：从源派生） |
| `--force` | 即使已存在也重新安装 |
| `--no-enable` | 安装但不自动启用 |
### 插件清单 (`plugin.yaml`)
```
id: my-plugin # Required, kebab-case
name: My Plugin
version: 0.1.0
description: What this plugin does
author: Your Name
license: MIT
engine: ">=0.3.0" # Min gitagent version
provides:
tools: true # Load tools from tools/*.yaml
skills: true # Load skills from skills/
prompt: prompt.md # Inject into system prompt
hooks:
pre_tool_use:
- script: hooks/audit.sh
description: Audit tool calls
config:
properties:
api_key:
type: string
description: API key
env: MY_API_KEY # Env var fallback
timeout:
type: number
default: 30
required: [api_key]
entry: index.ts # Optional programmatic entry point
```
### `agent.yaml` 中的插件配置
```
plugins:
my-plugin:
enabled: true
source: https://github.com/org/my-plugin.git # Auto-install on load
version: main # Git branch/tag
config:
api_key: "${MY_API_KEY}" # Supports env interpolation
timeout: 60
```
配置解析优先级：`agent.yaml config` > `env var` > `manifest default`。
### 发现顺序
插件按以下顺序发现（首个匹配项生效）：
1. **本地** — `/plugins//`
2. **全局** — `~/.gitagent/plugins//`
3. **已安装** — `/.gitagent/plugins//`
### 编程式插件
在其清单中包含 `entry` 字段的插件将获得完整的 API：
```
// index.ts
import type { GitagentPluginApi } from "gitagent";
export async function register(api: GitagentPluginApi) {
// Register a tool
api.registerTool({
name: "search_docs",
description: "Search documentation",
inputSchema: {
properties: { query: { type: "string" } },
required: ["query"],
},
handler: async (args) => {
const results = await search(args.query);
return { text: JSON.stringify(results) };
},
});
// Register a lifecycle hook
api.registerHook("pre_tool_use", async (ctx) => {
api.logger.info(`Tool called: ${ctx.tool}`);
return { action: "allow" };
});
// Add to system prompt
api.addPrompt("Always check docs before answering questions.");
// Register a memory layer
api.registerMemoryLayer({
name: "docs-cache",
path: "memory/docs-cache.md",
description: "Cached documentation lookups",
});
}
```
**可用的 API 方法：**
| 方法 | 描述 |
|---|---|
| `registerTool(def)` | 注册一个 agent 可调用的工具 |
| `registerHook(event, handler)` | 注册一个生命周期 Hook（`on_session_start`, `pre_tool_use`, `post_response`, `on_error`） |
| `addPrompt(text)` | 将文本追加到系统提示中 |
| `registerMemoryLayer(layer)` | 注册一个记忆层 |
| `logger.info/warn/error(msg)` | 带前缀的日志记录（`[plugin:id]`） |
| `pluginId` | 插件标识符 |
| `pluginDir` | 插件目录的绝对路径 |
| `config` | 解析后的配置值 |
### 插件结构
```
my-plugin/
├── plugin.yaml # Manifest (required)
├── tools/ # Declarative tool definitions
│ └── *.yaml
├── hooks/ # Hook scripts
├── skills/ # Skill modules
├── prompt.md # System prompt addition
└── index.ts # Programmatic entry point
```
## 多模型支持
Gitagent 与 [pi-ai](https://github.com/badlogic/pi-mono/tree/main/packages/ai) 支持的任何 LLM 提供商配合使用：
```
# agent.yaml
model:
preferred: "anthropic:claude-sonnet-4-5-20250929"
fallback:
- "openai:gpt-4o"
- "google:gemini-2.0-flash"
```
支持的提供商：`anthropic`、`openai`、`google`、`xai`、`groq`、`mistral` 等。
## 继承与组合
Agent 可以扩展基础 agent：
```
# agent.yaml
extends: "https://github.com/org/base-agent.git"
# Dependencies
dependencies:
- name: shared-tools
source: "https://github.com/org/shared-tools.git"
version: main
mount: tools
# Sub-agents
delegation:
mode: auto
```
## 合规与审计
内置合规性验证和审计日志记录：
```
# agent.yaml
compliance:
risk_level: high
human_in_the_loop: true
data_classification: confidential
regulatory_frameworks: [SOC2, GDPR]
recordkeeping:
audit_logging: true
retention_days: 90
```
审计日志将写入 `.gitagent/audit.jsonl`，包含完整的工具调用追踪。
## 遥测
Gitagent 内置了 OpenTelemetry 监测功能。设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 即可开启遥测；如果不设置，运行时开销为零。
三层信号：
1. **HTTP 级别** — `@opentelemetry/instrumentation-undici` 自动修补 `fetch`/`undici`，因此每一次 LLM 提供商调用（Anthropic, OpenAI, Google, …）都会获得一个包含 URL、状态码和时间的客户端 span。
2. **`gen_ai.chat` spans** — 在每次 assistant `message_end` 时发出。携带 `gen_ai.system`、`gen_ai.request.model`、`gen_ai.usage.input_tokens`、`gen_ai.usage.output_tokens`、`gen_ai.response.finish_reasons` 和 `gitagent.cost_usd`。Span/metric 内容绝不包含提示或补全文本。
3. **`gitagent.tool.execute` spans** — 封装每次工具调用，包含 `tool.name`、`tool.call_id`、`tool.status`（`ok`/`error`），以及失败时的 `tool.error_message`。
一个根 `gitagent.agent.session` span 在 agent 构建时打开，并在所有退出路径（成功、Hook 拦截、SIGINT、错误）上关闭。
### CLI 用法
只需设置 endpoint —— 不需要 `--import` 标志，不需要额外的安装步骤：
```
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent -p "your prompt"
```
当设置了 endpoint 时，遥测会自动启用；未设置时则禁用。如果要在设置了 endpoint 的情况下强制禁用，请传入 `GITAGENT_OTEL_ENABLED=false`。
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP/HTTP collector 基础 URL（例如 `http://localhost:4318`）。设置后，遥测将自动启用。 | （未设置 → 遥测关闭） |
| `GITAGENT_OTEL_ENABLED` | 设置为 `false` 可在设置了 endpoint 的情况下也禁用遥测 | （未设置 = 自动） |
| `OTEL_SERVICE_NAME` | 资源 `service.name` | `gitagent` |
|OTEL_SERVICE_VERSION` | 资源 `service.version` | （未设置） |
| `OTEL_EXPORTER_OTLP_HEADERS` | 逗号分隔的 key=value 对，无引号（例如 `Authorization=Bearer xyz,x-tenant=abc`） | （未设置） |
| `OTEL_TRACES_EXPORTER` | 设置为 `console` 可将 spans 打印到 stdout —— 无需 collector | （未设置） |
### SDK 用法
对于以编程方式嵌入的开发者，请显式调用 `initTelemetry` —— 你可以控制初始化发生的时机：
```
import { initTelemetry, shutdownTelemetry, query } from "gitagent";
await initTelemetry({ serviceName: "my-app" });
for await (const msg of query({ prompt: "hello", model: "anthropic:claude-4-6-sonnet-latest" })) {
// …
}
await shutdownTelemetry();
```
当不以编程方式提供时，`OTEL_EXPORTER_OTLP_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_HEADERS` 会被 OTLP exporter 自动读取。仅当需要在代码中覆盖基于环境变量的配置时，才传入 `exporterEndpoint` / `headers`。
### 发出的 spans
| 名称 | 类型 | 关键属性 |
|------|------|----------------|
| `gitagent.agent.session` | INTERNAL | `gitagent.entry` (`sdk` / `cli`), `gitagent.cost_usd`, `gitagent.session.duration_ms` |
| `gitagent.tool.execute` | INTERNAL | `tool.name`, `tool.call_id`, `tool.status`, `tool.error_message` |
| `gen_ai.chat` | CLIENT | `gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.response.finish_reasons`, `gitagent.cost_usd` |
| `HTTP …` | CLIENT | URL, 状态码, 持续时间（自动来自 `instrumentation-undici`） |
### 发出的指标
| 名称 | 类型 | 描述 |
|------|------|-------------|
| `gitagent.tool.calls` | counter | 工具执行次数，按 `tool.name` 标记 |
| `gitagent.tool.duration_ms` | histogram | 工具执行持续时间 |
| `gitagent.session.duration_ms` | histogram | 会话持续时间 |
| `gitagent.session.cost_usd` | counter (USD) | 累计会话成本 |
| `gen_ai.client.token.usage` | counter | Token 使用情况，按 `gen_ai.system`, `gen_ai.request.model`, `gen_ai.token.type` 标记 |
| `gen_ai.client.operation.duration` | histogram | LLM 调用持续时间 |
### 控制台快速开始（无需 collector）
将 spans 直接打印到 stdout —— 对本地调试非常有用：
```
OTEL_TRACES_EXPORTER=console gitagent -p "test"
```
### 本地 Jaeger 快速开始
```
docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 gitagent -p "test"
# Open http://localhost:16686 → service "gitagent"
```
## 贡献
欢迎提交贡献！请查阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解指南。
## ❓ 常见问题
### 通用
**什么是 Gitagent？**
GitAgent（原名 Gitclaw）是一个 git-native 的 AI agent 框架，其中 agent 本身就是一个 git 仓库。身份、规则、记忆、工具和技能都是受版本控制的文件，从而实现了“agents as repos”的范式。
**Gitagent 与其他 agent 框架有何不同？**
与那些将配置散布在应用程序代码中的框架不同，Gitagent 让 agent 本身成为一个 git 仓库：
- Fork 一个 agent → 继承个性、规则、工具
- Branch → 创建备用个性版本
- `git log` → 查看 agent 的记忆演变
- Diff → 追踪随时间变化的规则
**什么是“agents as repos”概念？**
你的 agent 生存于一个包含结构化文件的 git 仓库中：
- `agent.yaml` — 模型、工具、运行时配置
- `SOUL.md` — 个性与身份
- `RULES.md` — 行为约束
- `memory/` — 拥有完整历史的 git 提交记忆
- `tools/` — 声明式 YAML 工具定义
- `skills/` — 可组合的技能模块
- `hooks/` — 生命周期 Hooks
### 安装与设置
**有什么系统要求？**
Node.js 18+（或推荐 20+）、npm 和 git。通过 `npm install -g @open-gitagent/gitagent` 全局安装（精简版 CLI + SDK）。添加 `@open-gitagent/voice` 以获取语音模式和 Web UI。
**我该如何设置 API key？**
运行安装程序以进行引导式设置：
```
bash <(curl -fsSL "https://raw.githubusercontent.com/open-gitagent/gitagent/main/install.sh")
```
或者手动设置：
```
export OPENAI_API_KEY="sk-..."
```
**支持哪些 LLM 提供商？**
- OpenAI (GPT-4o, GPT-4o-mini 等)
- Anthropic (通过原生 SDK 支持 Claude 模型)
- 任何兼容 OpenAI 的提供商
使用 `--model` 标志进行覆盖：`gitagent --model anthropic:claude-sonnet-4-5-20250929`
### 核心概念
**什么是 SDK，我该如何使用它？**
SDK 通过 `query()` 函数提供编程访问权限，该函数流式传输 agent 事件：
```
import { query } from "gitagent";
for await (const msg of query({ prompt: "hello", model: "openai:gpt-4o-mini" })) {
if (msg.type === "delta") process.stdout.write(msg.content);
}
```
**本地仓库模式会话是如何工作的？**
Clone 一个 GitHub 仓库，在其上运行 agent，并自动提交到一个 session branch：
```
gitagent --repo https://github.com/org/repo --pat ghp_xxx "Fix the bug"
```
恢复会话：`gitagent --repo URL --session gitagent/session-xxx "Continue"`
**有哪些可用的 Hooks？**
Hooks 是位于 `hooks/` 目录中的生命周期脚本或编程处理程序。它们在工具执行、会话开始/结束或记忆更新等 agent 事件发生时触发。
### 开发
**我该如何创建自定义工具？**
使用声明式 YAML 格式在 `tools/` 目录中定义工具。每个工具需指定名称、描述、参数和执行逻辑。
**我该如何添加技能？**
在 `skills/` 目录中创建技能模块。技能是可组合的，可以从已安装的包中导入，也可以在本地定义。
**有哪些遥测选项可用？**
用于系统可观测性的 OpenTelemetry 集成：
- 设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 以自动启用
- 使用 `OTEL_TRACES_EXPORTER=console` 进行本地调试
- 使用 Docker 快速开始 Jaeger
### 故障排除
**为什么我的 agent 没有响应？**
- 检查是否设置了 API key（`OPENAI_API_KEY` 或类似变量）
- 验证与 LLM 提供商的网络连接
- 使用 `--verbose` 标志获取详细日志
- 检查 `agent.yaml` 模型配置
**我该如何调试 agent 行为？**
- 使用控制台 exporter：`OTEL_TRACES_EXPORTER=console gitagent -p "test"`
- 在 Jaeger 中检查 spans：`docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one`
- 检查 `memory/` 目录以获取 agent 状态
**我可以在哪里获得帮助？**
- GitHub Issues：https://github.com/open-gitagent/gitagent/issues
- 示例：请参阅 README SDK 部分和 CLI 选项
- 贡献：请参阅 CONTRIBUTING.md 了解指南
## 许可证
本项目基于 [MIT License](./LICENSE) 授权。标签：Git, MITM代理, Petitpotam, TypeScript, 多模态, 安全可观测性, 安全插件, 开发框架, 暗色界面, 版本控制, 自动化攻击