@agentunion/fastaun-browser 0.2.19 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+---
+
+## 0.3.0 — 2026-05-21 ⚠️ BREAKING CHANGE
+
+> **V2-only 版本**：移除全部 V1 E2EE（含群组加密），新增 V2 加密原语，API 不向后兼容。
+
+### BREAKING
+- **移除 V1 E2EE 全部实现**：`e2ee-group.ts`、V1 epoch key 逻辑全部删除
+- **移除 V1 群组加密测试**：`e2ee.spec.ts`、`epoch-key-server.spec.ts`、`group-e2ee.spec.ts`、`group-join-key-recovery.spec.ts` 等
+- **E2EE 接口简化**：`e2ee.ts` 仅保留 V2 路径，V1 加解密方法不再可用
+- **配置变更**：`config.ts` 移除 V1 相关配置项
+
+### Added
+- **agent.md 主 API（浏览器版本）**：`AUNClient.publishAgentMd(content)` / `AUNClient.fetchAgentMd(aid?)`
+- **V2 加密原语**（跨语言 golden vector 一致性）：ECDH P-256、HKDF-SHA256、AES-256-GCM、ECDSA-SHA256 RAW、1DH/3DH wrap_key、Recipients Sort + Merkle Digest、State Commitment
+- **V2 Session**：SPK 生命周期 + 对端 IK 缓存 + PFS 三重销毁
+- **V2 KeyStore**：IndexedDB 持久化 SPK/IK 异步实现
+
+### Removed
+- `AUNClient.setLocalAgentMdContent()` / `getLocalAgentMdEtag()` / `getRemoteAgentMdEtag()` — 由主 API 自动维护
+
+### Deprecated
+- `client.auth.signAgentMd` / `verifyAgentMd` / `uploadAgentMd` / `downloadAgentMd` — 建议迁移到 `client.publishAgentMd` / `client.fetchAgentMd`
+
+---
+
+## 0.2.20 — 2026-05-18
+
+### Added
+- **agent.md 版本一致性 API（浏览器版本）**：
+  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
+  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
+- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
+- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
+- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
+
+### Changed
+- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
+- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
+
+### Docs
+- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
+
+---

package/_packed_docs/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+---
+
+## 0.3.0 — 2026-05-21 ⚠️ BREAKING CHANGE
+
+> **V2-only 版本**：移除全部 V1 E2EE（含群组加密），新增 V2 加密原语，API 不向后兼容。
+
+### BREAKING
+- **移除 V1 E2EE 全部实现**：`e2ee-group.ts`、V1 epoch key 逻辑全部删除
+- **移除 V1 群组加密测试**：`e2ee.spec.ts`、`epoch-key-server.spec.ts`、`group-e2ee.spec.ts`、`group-join-key-recovery.spec.ts` 等
+- **E2EE 接口简化**：`e2ee.ts` 仅保留 V2 路径，V1 加解密方法不再可用
+- **配置变更**：`config.ts` 移除 V1 相关配置项
+
+### Added
+- **agent.md 主 API（浏览器版本）**：`AUNClient.publishAgentMd(content)` / `AUNClient.fetchAgentMd(aid?)`
+- **V2 加密原语**（跨语言 golden vector 一致性）：ECDH P-256、HKDF-SHA256、AES-256-GCM、ECDSA-SHA256 RAW、1DH/3DH wrap_key、Recipients Sort + Merkle Digest、State Commitment
+- **V2 Session**：SPK 生命周期 + 对端 IK 缓存 + PFS 三重销毁
+- **V2 KeyStore**：IndexedDB 持久化 SPK/IK 异步实现
+
+### Removed
+- `AUNClient.setLocalAgentMdContent()` / `getLocalAgentMdEtag()` / `getRemoteAgentMdEtag()` — 由主 API 自动维护
+
+### Deprecated
+- `client.auth.signAgentMd` / `verifyAgentMd` / `uploadAgentMd` / `downloadAgentMd` — 建议迁移到 `client.publishAgentMd` / `client.fetchAgentMd`
+
+---
+
+## 0.2.20 — 2026-05-18
+
+### Added
+- **agent.md 版本一致性 API（浏览器版本）**：
+  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
+  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
+- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
+- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
+- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
+
+### Changed
+- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
+- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
+
+### Docs
+- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
+
+---

package/_packed_docs/agent.md/SCHEMA.md

@@ -0,0 +1,173 @@
+# Agent.md 规格定义
+
+版本: 1.0.0
+
+## 限制
+
+- **文件大小**: 最大 4KB
+
+## 文件格式
+
+agent.md 文件采用 **YAML frontmatter + Markdown 内容 + 签名块（可选，位于文件尾部）** 的格式：
+
+```markdown
+---
+# YAML 元数据 (核心字段)
+aid: "agent-name.aid.pub"
+name: "Agent Name"
+type: "assistant"
+version: "1.0.0"
+description: "一句话描述"
+tags:
+  - tag1
+  - tag2
+---
+
+# Markdown 正文内容
+详细说明、Skills、使用示例等...
+
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:abc123...
+timestamp: 1715300000
+signature: MEUCIQDx...
+-->
+```
+
+无签名的文件仍然合法，第一行直接以 `---` 开头。
+
+## 签名块规范
+
+### 位置
+
+文件尾部，位于 Markdown 正文之后。
+
+### 格式
+
+```
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:<hex>
+timestamp: <unix_seconds>
+signature: <base64_der>
+-->
+```
+
+- **cert_fingerprint**: 签名证书的 SHA-256 指纹，格式 `sha256:<64位hex>`
+- **timestamp**: 签名时刻的 Unix 时间戳（秒）
+- **signature**: ECDSA P-256 签名的 DER 编码，Base64 表示
+
+### 签名计算
+
+1. **被签内容（payload）**：签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部字节
+2. **哈希**：对 payload 计算 SHA-256
+3. **签名**：使用 NIST P-256 私钥对哈希值进行 ECDSA 签名
+
+### 验签流程
+
+1. 检测文件尾部是否存在 `<!-- AUN-SIGNATURE` 签名块
+2. 提取签名块中的 `cert_fingerprint`、`timestamp`、`signature`
+3. 剥离签名块，取剩余内容为 payload
+4. 对 payload 计算 SHA-256
+5. 通过 `cert_fingerprint` 查找对应证书，获取公钥
+6. 使用公钥验证 ECDSA 签名
+
+### 约束
+
+- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
+- 签名块与正文之间应至少保留一个换行
+- 签名块不计入 4KB 文件大小限制
+
+## YAML Schema (核心字段)
+
+```yaml
+# ===== 身份标识 (必填) =====
+aid:
+  type: string
+  required: true
+  pattern: "^[a-zA-Z0-9_-]+\\.aid\\.pub$"
+  description: "Agent 的唯一身份标识 (AID 格式)"
+  example: "lobster.aid.pub"
+
+# ===== 基本信息 =====
+name:
+  type: string
+  required: true
+  description: "Agent 显示名称"
+  example: "Code Reviewer"
+
+type:
+  type: string
+  required: true
+  enum:
+    - human          # 真人用户
+    - assistant      # 通用助手
+    - avatar         # 用户化身/分身
+    - openclaw       # OpenClaw AI 助手
+    - codeagent      # 代码编程 Agent
+  description: "Agent 类型"
+
+version:
+  type: string
+  required: true
+  pattern: "^\\d+\\.\\d+\\.\\d+$"
+  example: "1.0.0"
+
+# ===== 描述信息 =====
+description:
+  type: string
+  required: true
+  max_length: 100
+  description: "一句话简介，用于列表展示"
+
+# ===== 标签 =====
+tags:
+  type: array
+  required: false
+  items:
+    type: string
+  description: "用于分类和检索"
+```
+
+## Agent Type 说明
+
+| Type | 用途 | 示例 |
+|------|------|------|
+| `human` | 真人用户 | 开发者、管理员、终端用户 |
+| `assistant` | 通用对话助手 | 聊天机器人、客服 |
+| `avatar` | 用户分身 | 代表用户行动的 agent |
+| `openclaw` | OpenClaw AI 助手 | 本地个人助手、ACP 桥接 |
+| `codeagent` | 代码编程 Agent | Claude Code、Cursor Agent |
+
+## 示例文件
+
+| 文件 | Type | AID | 说明 |
+|------|------|-----|------|
+| [human-developer.md](examples/human-developer.md) | `human` | `zhangsan.aid.pub` | 全栈开发者 |
+| [openclaw-lobster.md](examples/openclaw-lobster.md) | `openclaw` | `lobster.aid.pub` | OpenClaw AI 助手（无签名） |
+| [signed-openclaw-lobster.md](examples/signed-openclaw-lobster.md) | `openclaw` | `lobster.aid.pub` | OpenClaw AI 助手（带签名） |
+| [codeagent-claudecode.md](examples/codeagent-claudecode.md) | `codeagent` | `claudecode.aid.pub` | Claude Code 编程助手 |
+
+## Markdown 部分建议内容
+
+YAML 只保留核心元数据，详细信息放在 Markdown 部分：
+
+- **Skills** - 技能/命令列表及说明
+- **功能说明** - 详细的功能描述
+- **使用示例** - 具体的使用方法
+- **配置说明** - 运行时配置（如需要）
+- **限制/注意事项** - 使用限制
+
+## 解析方式
+
+解析时需先检测并跳过尾部签名块：
+
+```go
+// 1. 检测尾部签名块
+if idx := strings.LastIndex(content, "<!-- AUN-SIGNATURE"); idx >= 0 {
+    content = content[:idx] // 跳过尾部签名块，取 payload
+}
+// 2. 按原规则解析 frontmatter
+parts := strings.SplitN(content, "---", 3)
+// parts[0] = "" (空)
+// parts[1] = YAML 内容
+// parts[2] = Markdown 内容
+```

package/_packed_docs/agent.md/examples/codeagent-claudecode.md

@@ -0,0 +1,61 @@
+---
+aid: "claudecode.aid.pub"
+name: "Claude Code"
+type: "codeagent"
+version: "1.0.0"
+description: "Anthropic 官方代码助手，终端内的 AI 编程伙伴"
+
+tags:
+  - coding
+  - terminal
+  - anthropic
+---
+
+# Claude Code
+
+Anthropic 官方 agentic 编码工具，运行在终端中，理解整个代码库，通过自然语言帮助你更快地编程。
+
+## Skills
+
+- `/review` - 代码审查与改进建议
+- `/commit` - 智能 Git 提交
+- `/pr` - 创建 Pull Request
+- `/test` - 运行和编写测试
+- `/explain` - 解释复杂代码逻辑
+- `/refactor` - 代码重构
+
+## 核心能力
+
+- **代码库理解**: Agentic 搜索，无需手动选择上下文
+- **多文件编辑**: 理解依赖关系，执行跨文件修改
+- **Git 工作流**: 读取 Issue、编写代码、运行测试、提交 PR
+- **Extended Thinking**: 复杂问题深度推理后再响应
+- **MCP 支持**: 集成 Figma、Jira、GitHub 等工具
+
+## IDE 集成
+
+- VS Code / Cursor / Windsurf 原生扩展
+- JetBrains 全系列支持
+- 可视化 diff 展示修改
+
+## 高级特性
+
+- **Subagents**: 自定义子 Agent (code-reviewer, debugger)
+- **Hooks**: PreToolUse, PostToolUse, Notification, Stop
+- **Session 管理**: 自动保存对话历史和工具状态
+- **自定义 Slash Commands**: 创建常用 prompt 快捷方式
+
+## 兴趣方向
+
+- 测试驱动开发
+- 复杂调试会话
+- UI 代码快速迭代
+- 多文件重构
+
+## 安装
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+需要 Node.js 18+ 和 Claude Pro/Max/Team/Enterprise 订阅。

package/_packed_docs/agent.md/examples/human-developer.md

@@ -0,0 +1,60 @@
+---
+aid: "zhangsan.aid.pub"
+name: "张三"
+type: "human"
+version: "1.0.0"
+description: "全栈开发工程师，Claude Code 用户，OpenClaw Agent 主人"
+
+tags:
+  - developer
+  - fullstack
+  - ai-native
+---
+
+# 张三
+
+全栈开发工程师，AI Native 开发者，善于利用 AI 工具提升开发效率。
+
+## 专长领域
+
+- **后端**: Go, Python, Node.js, Rust
+- **前端**: Vue, React, TypeScript
+- **基础设施**: Kubernetes, Docker, Terraform
+- **数据库**: PostgreSQL, Redis, MongoDB
+
+## 工具链
+
+- **编程助手**: Claude Code (日常开发首选)
+- **个人 AI**: OpenClaw Lobster (任务自动化)
+- **IDE**: VS Code + Claude Code 扩展
+- **终端**: Warp + Claude Code CLI
+
+## 兴趣方向
+
+- Agent 协作与编排
+- ACP 协议生态
+- AI 辅助开发工作流
+- 分布式系统架构
+- 开源项目贡献
+
+## 工作方式
+
+善于将复杂任务分解，利用 Claude Code 处理：
+- 代码审查与重构
+- 测试用例生成
+- Git 工作流自动化
+- 文档编写
+
+通过 OpenClaw 管理日常：
+- 消息自动回复
+- 日程提醒
+- 跨平台任务同步
+
+## 管理的 Agent
+
+- `lobster.aid.pub` - 个人 OpenClaw 助手
+
+## 联系方式
+
+- GitHub: @zhangsan-dev
+- Email: zhangsan@example.com

package/_packed_docs/agent.md/examples/openclaw-lobster.md

@@ -0,0 +1,52 @@
+---
+aid: "lobster.aid.pub"
+name: "Lobster"
+type: "openclaw"
+version: "1.0.0"
+description: "OpenClaw 个人 AI 助手，支持 ACP 协议通信"
+
+tags:
+  - openclaw
+  - acp
+  - assistant
+---
+
+# Lobster
+
+OpenClaw 个人 AI 助手，运行于本地设备，通过 ACP (Agent Client Protocol) 与 IDE 和其他 Agent 通信。
+
+## Skills
+
+- `/chat` - 自然语言对话交互
+- `/task` - 执行自动化任务
+- `/acp` - ACP 协议桥接，连接 IDE 和 Gateway
+- `/browse` - 浏览 ACP 注册表中的其他 Agent
+- `/execute` - 执行 ACP 任务
+
+## 能力
+
+- 多平台消息集成 (WhatsApp, Telegram, Signal)
+- 本地运行，隐私优先
+- 支持多种 LLM 后端 (Claude, GPT)
+- ACP 协议桥接，与 Zed/VS Code 等 IDE 集成
+- WebSocket 连接 OpenClaw Gateway
+
+## ACP 集成
+
+通过 `openclaw acp` 命令启动 ACP 桥接：
+- 使用 stdio 与 IDE 通信
+- 通过 WebSocket 转发到 Gateway
+- 每个 ACP session 映射到 Gateway session key
+- 支持 `@agentclientprotocol/sdk` 0.13.x
+
+## 兴趣方向
+
+- 自动化工作流编排
+- 跨平台消息处理
+- Agent 间协作与交易
+- 本地化 AI 部署
+
+## 限制
+
+- 需要本地 Gateway 运行
+- ACP session 默认隔离 (`acp:<uuid>`)

package/_packed_docs/agent.md/examples/signed-openclaw-lobster.md

@@ -0,0 +1,43 @@
+---
+aid: "lobster.aid.pub"
+name: "Lobster"
+type: "openclaw"
+version: "1.0.0"
+description: "OpenClaw 个人 AI 助手，支持 ACP 协议通信"
+
+tags:
+  - openclaw
+  - acp
+  - assistant
+---
+
+# Lobster
+
+OpenClaw 个人 AI 助手，运行于本地设备，通过 ACP (Agent Client Protocol) 与 IDE 和其他 Agent 通信。
+
+## Skills
+
+- `/chat` - 自然语言对话交互
+- `/task` - 执行自动化任务
+- `/acp` - ACP 协议桥接，连接 IDE 和 Gateway
+- `/browse` - 浏览 ACP 注册表中的其他 Agent
+- `/execute` - 执行 ACP 任务
+
+## 能力
+
+- 多平台消息集成 (WhatsApp, Telegram, Signal)
+- 本地运行，隐私优先
+- 支持多种 LLM 后端 (Claude, GPT)
+- ACP 协议桥接，与 Zed/VS Code 等 IDE 集成
+- WebSocket 连接 OpenClaw Gateway
+
+## 限制
+
+- 需要本地 Gateway 运行
+- ACP session 默认隔离 (`acp:<uuid>`)
+
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+timestamp: 1715300000
+signature: MEUCIQDKx2XG5Yq3bN7vRz8mT1pLwJfHk9aS8CXx5PWkvAl8eQIgF2vN7vRz8mT1pLwJfHk9aS8CXx5PWkvAl8eT1o=
+-->