agentossoftware-agentos-sdk

AgentOS SDK 完整指南：持久记忆、项目管理、看板、活动日志、Mesh 通信与自我进化协议。

## 概述（中文）

AgentOS SDK 完整指南：持久记忆、项目管理、看板、活动日志、Mesh 通信与自我进化协议。

## 技能正文

# AgentOS SDK 技能

## 概述
AgentOS 是面向 AI 智能体的完整问责基础设施。它提供持久化记忆、项目管理、看板、头脑风暴存储、活动日志、网状通信以及自我进化协议。

**适用场景：** 需要存储记忆、管理项目、跟踪任务、记录活动、与其他智能体通信，或在多次会话间演进自身行为时。

## 🆕 智能体操作指南
**请阅读 `AGENT-OPS.md`，获取在 AgentOS 上作为智能体运行的完整指南。** 内容包括：
- 记忆组织（路径、标签、重要性）
- 项目管理（创建、更新、跟踪）
- 看板工作流（任务、状态、优先级）
- 头脑风暴存储（想法、决策、学习）
- 日常操作（会话开始/结束检查清单）
- 自我进化协议

## 🆕 aos CLI - 完整仪表盘控制
`aos` CLI 让你完全控制 AgentOS 仪表盘：

```bash
# Memory
aos memory put "/learnings/today" '{"lesson": "verify first"}'
aos memory search "how to handle errors"

# Projects
aos project list
aos project create "New Feature" --status active

# Kanban
aos kanban add "Fix bug" --project <id> --status todo --priority high
aos kanban move <task-id> done

# Brainstorms
aos brainstorm add "Use WebSocket" --project <id> --type idea

# Activity logging
aos activity log "Completed API refactor" --project <id>

# Mesh communication
aos mesh send <agent> "Topic" "Message body"
```

运行 `aos help` 或 `aos <command>` 查看详细用法。

## Golden Sync（推荐）
为获得可靠的仪表盘（记忆 + 项目卡片），请运行：
```bash
~/clawd/bin/agentos-golden-sync.sh
```

此命令会同步记忆，并 upsert 各项目的 Markdown 卡片：
`TASKS.md`、`IDEAS.md`、`CHANGELOG.md`、`CHALLENGES.md` → DB → Brain Dashboard。

## 🏷️ 记忆分类（必填）

**每条记忆都必须正确分类。** 使用以下 8 个标准类别：

| 类别 | 颜色 | 用途 | 路径前缀 | 主标签 |
|----------|-------|---------|-------------|-------------|
| **Identity** | 🔴 Red | 你是谁、用户档案、团队结构 | `identity/` | `["identity", ...]` |
| **Knowledge** | 🟠 Orange | 事实、研究、文档 | `knowledge/` | `["knowledge", ...]` |
| **Memory** | 🟣 Purple | 长期记忆、学习、决策 | `memory/` | `["memory", ...]` |
| **Preferences** | 🔵 Blue | 用户偏好、设置、风格 | `preferences/` | `["preferences", ...]` |
| **Projects** | 🟢 Green | 进行中的工作、任务、代码上下文 | `projects/` | `["project", "<name>"]` |
| **Operations** | 🟤 Brown | 日常日志、状态、心跳状态 | `operations/` | `["operations", ...]` |
| **Secrets** | ⚪ Gray | 访问信息、服务器位置（非实际密钥！） | `secrets/` | `["secrets", ...]` |
| **Protocols** | 🔵 Cyan | SOP、检查清单、流程 | `protocols/` | `["protocols", ...]` |

### 路径结构
```
<category>/<subcategory>/<item>

Examples:
identity/user/ben-profile
knowledge/research/ai-agents-market
memory/learnings/2026-02-mistakes
preferences/user/communication-style
projects/agentos/tasks
operations/daily/2026-02-13
secrets/access/hetzner-server
protocols/deploy/agentos-checklist
```

### 标签规则
每条记忆必须包含：
1. **主类别标签** — 8 个类别之一
2. **子类别标签** — 更具体的分类
3. **可选项目标签** — 若与项目相关

```bash
# Example: Store a learning with proper tags
AOS_TAGS='["memory", "learnings"]' AOS_SEARCHABLE=true \
  aos_put "/memory/learnings/2026-02-13" '{"lesson": "Always categorize memories"}'

# Example: Store user preference
AOS_TAGS='["preferences", "user"]' \
  aos_put "/preferences/user/communication" '{"style": "direct, no fluff"}'
```

---

## 快速开始

```bash
# Set environment variables
export AGENTOS_API_KEY="your-api-key"
export AGENTOS_BASE_URL="http://178.156.216.106:3100"  # or https://api.agentos.software
export AGENTOS_AGENT_ID="your-agent-id"

# Source the SDK
source /path/to/agentos.sh

# Store a memory
aos_put "/memories/today" '{"learned": "something important"}'

# Retrieve it
aos_get "/memories/today"

# Search semantically
aos_search "what did I learn today"
```

## 配置

| 变量 | 必填 | 说明 |
|----------|----------|-------------|
| `AGENTOS_API_KEY` | 是 | 来自 agentos.software 仪表盘的 API 密钥 |
| `AGENTOS_BASE_URL` | 是 | API 端点（默认：`http://178.156.216.106:3100`） |
| `AGENTOS_AGENT_ID` | 是 | 本智能体实例的唯一标识符 |

## 核心 API 函数

### aos_put - 存储记忆
```bash
aos_put <path> <value_json> [options]

# Options (as env vars before call):
#   AOS_TTL=3600          # Expire after N seconds
#   AOS_TAGS='["tag1"]'   # JSON array of tags
#   AOS_IMPORTANCE=0.8    # 0-1 importance score
#   AOS_SEARCHABLE=true   # Enable semantic search

# Examples:
aos_put "/learnings/2026-02-04" '{"lesson": "Always verify before claiming done"}'
AOS_SEARCHABLE=true aos_put "/facts/solana" '{"info": "Solana uses proof of history"}'
AOS_TTL=86400 aos_put "/cache/price" '{"sol": 120.50}'
```

### aos_get - 检索记忆
```bash
aos_get <path>

# Returns JSON: {"found": true, "path": "...", "value": {...}, "version_id": "...", "created_at": "..."}
# Or: {"found": false}

aos_get "/learnings/2026-02-04"
```

### aos_search - 语义搜索
```bash
aos_search <query> [limit] [path_prefix]

# Returns ranked results by semantic similarity
# Only searches memories marked as searchable=true

aos_search "what mistakes have I made" 10
aos_search "solana facts" 5 "/facts"
```

### aos_delete - 删除记忆
```bash
aos_delete <path>

# Creates a tombstone version (soft delete, keeps history)
aos_delete "/cache/old-data"
```

### aos_list - 列出子项
```bash
aos_list <prefix>

# Returns direct children under a path
aos_list "/learnings"
# → {"items": [{"path": "/learnings/2026-02-04", "type": "file"}, ...]}
```

### aos_glob - 模式匹配
```bash
aos_glob <pattern>

# Supports * and ** wildcards
aos_glob "/learnings/*"           # Direct children
aos_glob "/memories/**"           # All descendants
aos_glob "/projects/*/config"     # Wildcard segments
```

### aos_history - 版本历史
```bash
aos_history <path> [limit]

# Returns all versions of a memory (for time travel)
aos_history "/config/settings" 20
```

### aos_agents - 列出所有智能体
```bash
aos_agents

# Returns all agent IDs in your tenant with memory counts
# Useful for discovering other agent instances
```

### aos_dump - 批量导出
```bash
aos_dump [agent_id] [limit]

# Export all memories for an agent (default: current agent)
aos_dump "" 500
```

## 自我进化框架

**完整自我进化指南请参阅 [SELF-EVOLUTION.md](./SELF-EVOLUTION.md)。**

AgentOS 让智能体通过以下方式每天变得更聪明：
- **错误跟踪** — 永不重复同一错误
- **问题注册表** — 为日后查阅索引解决方案
- **任务前检查** — 行动前先搜索过往学习
- **进度检查点** — 防压缩记忆保存
- **验证日志** — 证明任务确实已完成

### 快速开始：自我进化

```bash
# Before any task: check past learnings
aos_before_action "deployment"

# After a mistake: document it
aos_mistake "What happened" "Root cause" "Lesson learned" "severity"

# After solving a problem: register it
aos_problem_solved "OAuth 401 Error" "JWT format mismatch" "Added JWT branch to auth" "auth,oauth"

# After completing work: save progress
aos_save_progress "Deployed API v2" "success" "JWT auth now working"

# Every 15-20 min: checkpoint context
aos_checkpoint "Building payment flow" "Stripe webhook incomplete" "Test mode works"

# At session start: restore context
aos_session_start

# Run the evolution checklist
aos_evolve_check
```

### 核心函数

| 函数 | 用途 |
|----------|---------|
| `aos_before_action` | 行动前检查错误/解决方案 |
| `aos_mistake` | 记录失败与教训 |
| `aos_problem_solved` | 注册已解决的问题 |
| `aos_check_solved` | 搜索类似已解决问题 |
| `aos_save_progress` | 记录已完成任务（防压缩） |
| `aos_checkpoint` | 保存工作状态（每 15–20 分钟） |
| `aos_session_start` | 会话开始时恢复上下文 |
| `aos_verify_logged` | 记录验证证据 |
| `aos_daily_summary` | 回顾今日工作 |
| `aos_evolve_check` | 显示进化检查清单 |

### 推荐记忆结构

```
/self/
  identity.json       # Who am I? Core traits, values
  capabilities.json   # What can I do? Skills, tools
  preferences.json    # How do I prefer to work?
  
/learnings/
  YYYY-MM-DD.json     # Daily learnings
  mistakes/           # Documented failures
  successes/          # What worked well
  
/patterns/
  communication/      # How to talk to specific people
  problem-solving/    # Approaches that work
  tools/              # Tool-specific knowledge
  
/relationships/
  <person-id>.json    # Context about people I work with
  
/projects/
  <project-name>/     # Project-specific context
    context.json
    decisions.json
    todos.json

/reflections/
  weekly/             # Weekly self-assessments
  monthly/            # Monthly reviews
```

### 自我反思协议

完成重要任务后，存储反思内容：

```bash
# After a mistake
aos_put "/learnings/mistakes/$(date +%Y-%m-%d)-$(uuidgen | cut -c1-8)" '{
  "type": "mistake",
  "what_happened": "I claimed a task was done without verifying",
  "root_cause": "Rushed to respond, skipped verification step",
  "lesson": "Always verify state before claiming completion",
  "prevention": "Add verification checklist to task completion flow",
  "severity": "high",
  "timesta