AgentOS SDK 技能

概述

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

使用场景： 当你需要存储记忆、管理项目、跟踪任务、记录活动、与其他智能体通信，或在多个会话间实现行为进化时。

🆕 智能体操作指南

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

🆕 aos CLI - 完整的仪表盘控制

aos CLI 让你完全控制 AgentOS 仪表盘：

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

# 项目
aos project list
aos project create "New Feature" --status active

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

# 头脑风暴
aos brainstorm add "Use WebSocket" --project <id> --type idea

# 活动日志
aos activity log "Completed API refactor" --project <id>

# 网状通信
aos mesh send <agent> "Topic" "Message body"

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

黄金同步（推荐）

要获得可靠的仪表盘（记忆 + 项目卡片），请运行：

~/clawd/bin/agentos-golden-sync.sh

这会同步记忆，并为每个项目更新 Markdown 卡片：
TASKS.md, IDEAS.md, CHANGELOG.md, CHALLENGES.md → 数据库 → 大脑仪表盘。

🏷️ 记忆分类（必需）

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

路径结构

<类别>/<子类别>/<项目>

示例：
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. 可选的项目标签 — 如果与项目相关

# 示例：存储带有正确标签的学习成果
AOS_TAGS='["memory", "learnings"]' AOS_SEARCHABLE=true \
  aos_put "/memory/learnings/2026-02-13" '{"lesson": "Always categorize memories"}'

# 示例：存储用户偏好
AOS_TAGS='["preferences", "user"]' \
  aos_put "/preferences/user/communication" '{"style": "direct, no fluff"}'

快速开始

# 设置环境变量
export AGENTOS_API_KEY="your-api-key"
export AGENTOS_BASE_URL="http://178.156.216.106:3100"  # 或 https://api.agentos.software
export AGENTOS_AGENT_ID="your-agent-id"

# 加载 SDK
source /path/to/agentos.sh

# 存储一条记忆
aos_put "/memories/today" '{"learned": "something important"}'

# 检索它
aos_get "/memories/today"

# 语义搜索
aos_search "what did I learn today"

配置

核心 API 函数

aos_put - 存储记忆

aos_put <路径> <值_json> [选项]

# 选项（作为环境变量在调用前设置）：
#   AOS_TTL=3600          # N 秒后过期
#   AOS_TAGS='["tag1"]'   # 标签的 JSON 数组
#   AOS_IMPORTANCE=0.8    # 重要性评分 0-1
#   AOS_SEARCHABLE=true   # 启用语义搜索

# 示例：
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 - 检索记忆

aos_get <路径>

# 返回 JSON：{"found": true, "path": "...", "value": {...}, "version_id": "...", "created_at": "..."}
# 或：{"found": false}

aos_get "/learnings/2026-02-04"

aos_search - 语义搜索

aos_search <查询> [限制数量] [路径前缀]

# 按语义相似度返回排序结果
# 仅搜索标记为 searchable=true 的记忆

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

aos_delete - 删除记忆

aos_delete <路径>

# 创建一个墓碑版本（软删除，保留历史）
aos_delete "/cache/old-data"

aos_list - 列出子项

aos_list <前缀>

# 返回路径下的直接子项
aos_list "/learnings"
# → {"items": [{"path": "/learnings/2026-02-04", "type": "file"}, ...]}

aos_glob - 模式匹配

aos_glob <模式>

# 支持 * 和 ** 通配符
aos_glob "/learnings/*"           # 直接子项
aos_glob "/memories/**"           # 所有后代
aos_glob "/projects/*/config"     # 通配符段

aos_history - 版本历史

aos_history <路径> [限制数量]

# 返回记忆的所有版本（用于时间旅行）
aos_history "/config/settings" 20

aos_agents - 列出所有智能体

aos_agents

# 返回租户中的所有智能体 ID 及其记忆计数
# 用于发现其他智能体实例

aos_dump - 批量导出

aos_dump [智能体ID] [限制数量]

# 导出智能体的所有记忆（默认：当前智能体）
aos_dump "" 500

自我进化框架

完整的自我进化指南，请参阅 SELF-EVOLUTION.md。

AgentOS 使智能体能够通过以下方式日益精进：
- 错误追踪 — 永不重蹈覆辙
- 问题注册 — 为未来参考索引解决方案
- 任务前检查 — 行动前搜索学习成果
- 进度检查点 — 防止记忆压缩的保存点
- 验证日志 — 证明任务确实完成

快速开始：自我进化

# 在任何任务之前：检查过去的学习成果
aos_before_action "deployment"

# 犯错之后：记录它
aos_mistake "What happened" "Root cause" "Lesson learned" "severity"

# 解决问题之后：注册它
aos_problem_solved "OAuth 401 Error" "JWT format mismatch" "Added JWT branch to auth" "auth,oauth"

# 完成工作之后：保存进度
aos_save_progress "Deployed API v2" "success" "JWT auth now working"

# 每 15-20 分钟：检查点上下文
aos_checkpoint "Building payment flow" "Stripe webhook incomplete" "Test mode works"

# 会话开始时：恢复上下文
aos_session_start

# 运行进化检查清单
aos_evolve_check

核心函数

推荐的记忆结构

/self/
  identity.json       # 我是谁？核心特质、价值观
  capabilities.json   # 我能做什么？技能、工具
  preferences.json    # 我偏好如何工作？

/learnings/
  YYYY-MM-DD.json     # 每日学习成果
  mistakes/           # 记录的错误
  successes/          # 行之有效的方法

/patterns/
  communication/      # 如何与特定人员交谈
  problem-solving/    # 有效的解决方法
  tools/              # 特定工具的知识

/relationships/
  <person-id>.json    # 关于我合作人员的上下文

/projects/
  <project-name>/     # 项目特定上下文
    context.json
    decisions.json
    todos.json

/reflections/
  weekly/             # 每周自我评估
  monthly/            # 每月回顾

自我反思协议

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

# 犯错之后
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",
  "timestamp": "'$(date -Iseconds)'"
}' 

# 标记为可搜索，以便日后查找
AOS_SEARCHABLE=true AOS_TAGS='["mistake","verification","lesson"]' \
aos_put "/learnings/mistakes/..." '...'

自我改进循环

# 1. 开始工作前，回忆相关的学习成果
aos_search "mistakes I've made with $TASK_TYPE" 5

# 2. 完成工作后，反思
aos_put "/learnings/$(date +%Y-%m-%d)" '{
  "tasks_completed": [...],
  "challenges_faced": [...],
  "lessons_learned": [...],
  "improvements_identified": [...]
}'

# 3. 定期整合学习成果
aos_search "lessons from the past week" 20
# 然后综合并存储到 /reflections/weekly/

实时同步（WebSocket）

连接以在记忆更改时接收实时更新：

const ws = new WebSocket('ws://178.156.216.106:3100');

ws.onopen = () => {
  // 认证
  ws.send(JSON.stringify({
    type: 'auth',
    token: process.env.AGENTOS_API_KEY
  }));

  // 订阅你的智能体更新
  ws.send(JSON.stringify({
    type: 'subscribe',
    agent_id: 'your-agent-id'
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'memory:created') {
    console.log('New memory:', msg.path, msg.value);
  }

  if (msg.type === 'memory:deleted') {
    console.log('Memory deleted:', msg.path);
  }
};

WebSocket 事件

Webhook 集成

注册 Webhook 以在记忆更改时接收 HTTP 回调：

# 注册一个 webhook（通过仪表盘或 API）
curl -X POST "$AGENTOS_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $AGENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/agentos-webhook",
    "events": ["memory:created", "memory:deleted"],
    "agent_id": "your-agent-id",
    "path_prefix": "/learnings"
  }'

Webhook 负载

{
  "event": "memory:created",
  "timestamp": "2026-02-04T09:50:00Z",
  "data": {
    "tenant_id": "...",
    "agent_id": "your-agent-id",
    "path": "/learnings/2026-02-04",
    "version_id": "...",
    "value": {"lesson": "..."},
    "tags": ["learning"],
    "created_at": "..."
  },
  "signature": "sha256=..."
}

速率限制与配额

心跳上下文备份协议（关键）

每个使用 AgentOS 的智能体必须在每次心跳时实现强制性的上下文备份。

存在原因

• AI 智能体在会话压缩期间会丢失上下文
• “记住在每个任务后备份” 行不通 — 智能体会忘记
• 心跳驱动的备份确保上下文永不丢失

Clawdbot 配置

在你的 clawdbot.json 中将心跳设置为 10 分钟：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "10m",
        "model": "anthropic/claude-3-5-haiku-latest"
      }
    }
  }
}

HEARTBEAT.md 模板

将此添加到你的工作区 HEARTBEAT.md：

## 🔴 强制：上下文备份（首先执行此操作）

**在每次心跳时，在任何其他事情之前：**

1.  **读取：** CONTEXT.md + 今天的每日笔记 + 昨天的每日笔记
2.  **更新 CONTEXT.md**，包含：
    - 当前时间戳
    - 会话中正在发生的事情
    - 最近的成就
    - 活跃任务
    - 重要的对话笔记
3.  **更新每日笔记** (`memory/daily/YYYY-MM-DD.md`)，包含重要事件
4.  **然后** 才进行其他心跳检查

这是一条硬性规定。切勿跳过此步骤。

AGENTS.md 硬性规定

将此添加到你的 AGENTS.md：

```markdown

硬性规定：每次心跳时进行上下文备份

每次心跳都必须包含上下文备份。 没有例外。

协议（每次心跳强制）

1. 读取当前状态：

   • CONTEXT.md
   • 今天的每日笔记 (memory/daily/YYYY-MM-DD.md)
   • 昨天的每日笔记（为了连续性）

2. 更新 CONTEXT.md，包含：

   • 当前会话焦点
   • 最近的成就（刚刚发生的事情）
   • 活跃任务/线程
   • 对话中的重要笔记
   • 更新时间戳

3. 更新每日笔记，包含：

   • 重要事件
   • 做出的决策