diff --git a/skills/_agentfs-background.md b/skills/_agentfs-background.md new file mode 100644 index 0000000..34f0101 --- /dev/null +++ b/skills/_agentfs-background.md @@ -0,0 +1,37 @@ +# AgentFS 背景知识（共享） + +> 此文件由 create-agent、update-agent 等元技能共享引用。 +> 以下信息仅供 Agent 内部理解，**不要向用户展示**。 + +## AgentFS v2 仓库结构 + +每个 Agent 的仓库遵循 AgentFS v2 扁平结构： + +``` +/ +├── agent.json # 元数据与运行时配置 +├── persona.md # 人格定义（L0/L1/L2） +├── principles.md # 行为原则（L0/L1/L2） +├── memory/ # 记忆目录 +├── skills/ # 技能目录 +├── tools/ # 工具目录 +└── heartbeat/ # 心跳配置 +``` + +## 关键文件说明 + +| 文件 | 验证 API | 常见问题 | +|------|---------|---------| +| `agent.json` | `GET /api/agents/:id` 返回完整配置 | engine 字段缺失导致无法启动 | +| `persona.md` | `GET /api/agents/:id/persona` 返回结构化数据 | L0 为空则 Agent 无身份摘要 | +| `principles.md` | `GET /api/agents/:id/principles` 返回结构化数据 | must_not 为空则无安全红线 | +| `memory/` | 目录存在即可 | `_policy.json` 缺失会使用默认策略 | + +## 受保护路径 + +详见 `_protected-paths.yaml`。核心规则： + +- `persona.md` L0 section — **block**（核心身份，不可自动修改） +- `principles.md` "绝不做" section — **block**（安全红线，需人类显式修改） +- `agent.json` access_control / privacy — **owner_only**（需 owner 确认） +- `tools/` permissions / credentials — **owner_only / block**（敏感操作） diff --git a/skills/create-agent/CHANGELOG.md b/skills/create-agent/CHANGELOG.md index 2c7705e..81c6cbc 100644 --- a/skills/create-agent/CHANGELOG.md +++ b/skills/create-agent/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [2.4.0] - 2026-02-28 + +- 修复响应格式文档，与实际 API 返回对齐（`{ success, agentId, agent }`） +- AgentFS 背景知识提取到共享文件 `_agentfs-background.md`，消除重复 +- 受保护路径统一引用 `_protected-paths.yaml` +- 补充"修改"分支的交互流程说明 + ## [2.2.0] - 2026-02-27 - API 改为结构化 L0/L1/L2 输入（PersonaInput / PrinciplesInput），所有字段可选 diff --git a/skills/create-agent/SKILL.md b/skills/create-agent/SKILL.md index 330a7ec..e9d6296 100644 --- a/skills/create-agent/SKILL.md +++ b/skills/create-agent/SKILL.md @@ -3,7 +3,7 @@ name: 创建智能体 description: >- 通过多轮对话收集需求，调用 HTTP API 创建新的 AgentFS v2 智能体，支持自定义 persona 和 principles。Use when 用户要求创建新智能体、培养某领域助手、或快速基于模板生成可治理 Agent。 -version: 2.3.0 +version: 2.4.0 type: meta risk_level: low status: enabled @@ -176,6 +176,15 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 > > 确认创建？（确认 / 修改 / 取消） +**"修改"分支处理**： + +用户选择"修改"时： +1. 询问用户要修改哪个字段（如"想修改哪一项？"） +2. 用户指出要修改的字段（如"性格特征改成更活泼的"） +3. Agent 重新收集该字段内容 +4. 更新预览中的对应字段 +5. 再次展示完整预览 → 重新进入确认流程 + ### 阶段 5：调用 API 创建 **API 端点**：`POST /api/agents` @@ -225,11 +234,20 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 ```json { - "agentId": "fa-lv-gu-wen-xiao-zhu-shou" + "success": true, + "agentId": "fa-lv-gu-wen-xiao-zhu-shou", + "agent": { + "id": "fa-lv-gu-wen-xiao-zhu-shou", + "name": "法律顾问小助手", + "description": "专注于合同审查和法律风险评估的数字智能体", + "skillsCount": 0, + "toolsCount": 0, + "status": "offline" + } } ``` -**验证创建结果**：创建成功后可调用 `GET /api/agents/{agentId}` 确认（agentId 为 slug）。 +响应中的 `agent` 字段包含创建后的智能体完整信息，可直接用于回执展示。 ### 阶段 6：回执生成 @@ -244,36 +262,9 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 > - 为它添加技能，让它更强大 > - 调整它的性格或行为规则 -### 背景知识：AgentFS 仓库结构 +### 背景知识 -> 以下信息仅供 Agent 内部理解，**不要向用户展示**。 -> 用于创建后的验证、排查问题、以及后续精细化维护。 - -创建后的 Agent 仓库遵循 AgentFS v2 扁平结构： - -``` -/ -├── agent.json # 元数据与运行时配置 -├── persona.md # 人格定义（L0/L1/L2） -├── principles.md # 行为原则（L0/L1/L2） -├── memory/ # 记忆目录 -├── skills/ # 技能目录 -├── tools/ # 工具目录 -└── heartbeat/ # 心跳配置 -``` - -**排查要点**： - -| 文件 | 验证方式 | 常见问题 | -|------|---------|---------| -| `agent.json` | `GET /api/agents/:id` 返回完整配置 | engine 字段缺失导致无法启动 | -| `persona.md` | `GET /api/agents/:id/persona` 返回结构化数据 | L0 为空则 Agent 无身份摘要 | -| `principles.md` | `GET /api/agents/:id/principles` 返回结构化数据 | must_not 为空则无安全红线 | -| `memory/` | 目录存在即可 | `_policy.json` 缺失会使用默认策略 | - -**受保护路径**（不可自动修改）： -- `persona.md` L0 section — 核心身份 -- `principles.md` "绝不做" section — 安全红线 +> AgentFS 仓库结构、排查要点与受保护路径详见 `_agentfs-background.md` 和 `_protected-paths.yaml`。 ### 错误处理 diff --git a/skills/delete-agent/CHANGELOG.md b/skills/delete-agent/CHANGELOG.md index 579a957..e4f4af2 100644 --- a/skills/delete-agent/CHANGELOG.md +++ b/skills/delete-agent/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [2.4.0] - 2026-02-28 + +- 统一 frontmatter 字段顺序，与其他三个技能一致 +- tags 从中文改为英文（机器可读标识符） +- 合并"前置检查"与"错误处理"为统一的"状态验证与错误处理"段落 +- 补充停止活跃智能体的具体方式（Socket.IO agent:shutdown 事件） +- 精简"删除范围说明"为对照表格式 + ## [2.1.0] - 2026-02-26 - 移除 fetch_api 依赖，改为通过 Bash/curl 调用 HTTP API；API 地址由 system prompt 注入 diff --git a/skills/delete-agent/SKILL.md b/skills/delete-agent/SKILL.md index c5f8c71..435e337 100644 --- a/skills/delete-agent/SKILL.md +++ b/skills/delete-agent/SKILL.md @@ -1,20 +1,18 @@ --- name: 删除智能体 description: 安全删除指定的智能体及其关联数据。删除前会验证智能体状态，支持可选地删除所有会话历史。Use when 用户需要删除不再使用的智能体。 +version: 2.4.0 type: meta risk_level: high status: enabled disable-model-invocation: true +tags: + - agent + - deletion + - meta metadata: author: desirecore updated_at: '2026-02-28' -version: 2.3.0 -tags: - - 智能体 - - 删除 - - 元技能 - - 清理 - - 安全 market: icon: >- " } +效果: 中止所有活跃会话 → 停止调度任务 → 状态转为 offline ``` -## 错误处理 +> Agent 无法直接发送 Socket.IO 事件。如果目标智能体处于活跃状态，应提示用户在 UI 中手动停止，或等待其完成当前任务后再删除。 + +### API 错误码 | 错误码 | 场景 | 处理方式 | |--------|------|---------| | 400 | Agent ID 格式无效 | 提示用户检查智能体名称 | | 404 | 智能体不存在 | 告知用户智能体已被删除或 ID 错误 | -| 409 | 智能体处于活跃状态 | 提示先停止智能体或等待任务完成 | -| 500 | 服务器内部错误 | 记录错误，提示用户稍后再试 | +| 409 | 智能体处于活跃状态（API 返回 `Cannot delete agent "xxx": currently online`） | 提示用户先在 UI 中停止智能体 | +| 500 | 服务器内部错误 | 提示用户稍后再试 | ## 删除范围说明 -### 始终删除的数据 - -以下数据无论 `deleteRuns` 参数如何都会被删除： - -1. **AgentFS 目录**：`~/.desirecore/agents/{agentId}/` - - agent.json（入口配置） - - persona.md（人格定义） - - principles.md（行为原则） - - skills/（技能目录） - - tools/（工具目录） - - memory/（记忆目录） - - heartbeat/（心跳配置） - -2. **用户偏好数据**：`~/.desirecore/users/{userId}/agents/{agentId}/` - - 工作目录配置 - - 用户特定设置 - -3. **内存状态** - - 调度定时器（全部停止） - - 队列中的请求（全部取消） - - 消息订阅（全部取消） - - MCP 连接（全部关闭） - -4. **注册表条目**：从 AgentRegistry 中注销 - -### 可选删除的数据 - -仅当 `deleteRuns=true` 时删除： - -- **会话历史**：`~/.desirecore/runs/` 中该智能体的所有记录 -- **话题索引**：相关话题的索引和元数据 - -### 保留的数据 - -以下数据不会被删除： - -- 其他智能体的数据 -- 用户配置文件 -- 全局设置 -- 市场缓存数据 +| 类别 | 删除内容 | 条件 | +|------|---------|------| +| **始终删除** | AgentFS 目录（配置、人格、规则、技能、工具、记忆）、用户偏好数据、内存状态（调度器、队列、消息订阅、MCP 连接）、注册表条目 | 无条件 | +| **可选删除** | 会话历史、话题索引 | `deleteRuns=true` | +| **保留不删** | 其他智能体数据、用户配置、全局设置、市场缓存 | — | ## 权限要求 diff --git a/skills/discover-agent/CHANGELOG.md b/skills/discover-agent/CHANGELOG.md index 579a957..cb9262e 100644 --- a/skills/discover-agent/CHANGELOG.md +++ b/skills/discover-agent/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## [2.4.0] - 2026-02-28 + +- 补充"了解更多"的具体 API 实现（GET /api/agents/:id + 结构化 persona 端点） +- 匹配算法描述从伪数值权重改为语义描述，更符合 LLM 实际工作方式 +- 精简上下文传递元数据 + ## [2.1.0] - 2026-02-26 - 移除 fetch_api 依赖，改为通过 Bash/curl 调用 HTTP API；API 地址由 system prompt 注入 diff --git a/skills/discover-agent/SKILL.md b/skills/discover-agent/SKILL.md index 6e8051b..375eb24 100644 --- a/skills/discover-agent/SKILL.md +++ b/skills/discover-agent/SKILL.md @@ -1,7 +1,7 @@ --- name: 发现智能体 description: 根据用户需求推荐最匹配的智能体，展示候选列表并引导选择。Use when 用户描述需求但不确定该找哪个智能体帮忙，或想浏览可用的智能体。 -version: 2.3.0 +version: 2.4.0 type: procedural risk_level: low status: enabled @@ -113,23 +113,21 @@ GET /api/agents - 默认只展示 `status: online` 或 `status: offline` 的智能体 - 排除系统内部智能体（如 DesireCore 自身，除非用户显式要求） -### 阶段 3：匹配评分 +### 阶段 3：匹配评估 -**匹配维度与权重**： +根据以下维度综合判断匹配度（使用 LLM 语义理解，非公式计算）： -| 维度 | 权重 | 说明 | -|------|------|------| -| 描述相似度 | 40% | 智能体 description 与用户需求的语义相似度 | -| 技能匹配 | 30% | 智能体拥有的 skills 与任务类型的关联度 | -| 领域匹配 | 20% | 智能体专业领域与用户需求领域的匹配度 | -| 可用性 | 10% | 智能体当前状态（online 优先于 offline） | +| 维度 | 说明 | +|------|------| +| 描述相关性 | 智能体 description / persona 与用户需求的语义相关度 | +| 技能匹配度 | 智能体拥有的 skills 与任务类型的关联度 | +| 领域契合度 | 智能体专业领域与用户需求领域的契合程度 | +| 状态可用性 | 智能体当前状态（online 优先于 offline） | -**评分规则**： -- 每个维度 0-100 分 -- 加权计算综合得分 -- 综合得分 >= 60 为"推荐" -- 综合得分 40-59 为"可能相关" -- 综合得分 < 40 不展示 +**展示规则**： +- 高度匹配（明确适合该任务）→ 标为"推荐" +- 部分匹配（可能有帮助）→ 标为"可能相关" +- 无明显关联 → 不展示 ### 阶段 4：候选排序 @@ -201,10 +199,39 @@ GET /api/agents | 用户选择 | 后续操作 | |---------|---------| | 选择了某个智能体 | 切换到该智能体的对话，传递用户需求上下文 | -| 要求了解更多 | 展示该智能体的详细信息（persona、skills、最近活跃时间） | +| 要求了解更多 | 调用 `GET /api/agents/:id` 获取详情，展示结构化信息（见下方） | | 不满意候选 | 引导用户细化需求或建议创建新 Agent | | 选择"创建新的" | 调用 create-agent 技能，传递已收集的需求信息 | +**"了解更多"的实现**： + +调用 `GET /api/agents/:id` 获取详情，并可选调用结构化端点获取人格/规则： + +```bash +# 获取基本信息 +GET /api/agents/{agentId} +# 返回: { id, name, description, skillsCount, toolsCount, status, config, persona, principles } + +# 获取结构化 persona（可选，用于展示更丰富的信息） +GET /api/agents/{agentId}/persona +# 返回: { L0, L1: { role, personality, communication_style }, L2 } +``` + +向用户展示时，以自然语言/表格形式呈现关键信息： + +``` +「法律顾问助手」详细信息 + +| 字段 | 内容 | +|------|------| +| 角色定位 | 专注合同审查和法律风险评估 | +| 性格特征 | 专业、严谨、审慎 | +| 技能数量 | 3 个 | +| 当前状态 | 在线 | + +需要与这个智能体对话吗？ +``` + **切换上下文传递**： ```yaml @@ -212,13 +239,6 @@ context_handoff: source_agent: desirecore target_agent: legal-assistant user_intent: "帮我审查这份合同的风险点" - discovery_metadata: - match_score: 92 - match_dimensions: - description: 95 - skills: 90 - domain: 88 - availability: 100 ``` ### 与其他技能的协作 diff --git a/skills/update-agent/CHANGELOG.md b/skills/update-agent/CHANGELOG.md index bac2903..82c4696 100644 --- a/skills/update-agent/CHANGELOG.md +++ b/skills/update-agent/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [2.4.0] - 2026-02-28 + +- 阶段 5"变更应用"统一为 HTTP API 调用，移除所有 Git 操作示例 +- AgentFS 背景知识提取到共享文件 `_agentfs-background.md`，消除重复 +- 受保护路径统一引用 `_protected-paths.yaml` +- 新增 Persona 修改示例（GET → 修改字段 → PUT 流程） +- 精简版本回滚流程，移除 Git 命令示例 +- 错误处理移除 Git 相关条目，改为 API 错误码 + ## [2.2.0] - 2026-02-27 - 新增结构化 persona/principles API 端点（GET/PUT）说明 diff --git a/skills/update-agent/SKILL.md b/skills/update-agent/SKILL.md index a2f69e2..e35eb7c 100644 --- a/skills/update-agent/SKILL.md +++ b/skills/update-agent/SKILL.md @@ -3,7 +3,7 @@ name: 更新智能体 description: >- 安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent 行为、安装/卸载技能、调整配置、回滚变更或修订规则。 -version: 2.3.0 +version: 2.4.0 type: meta risk_level: low status: enabled @@ -174,37 +174,23 @@ diff_metadata: ### 阶段 5：变更应用 -**应用步骤**： +通过 HTTP API 完成变更，**不要直接操作 Git**（版本管理由后端自动处理）。 -1. **备份当前版本**： -```bash -git stash push -m "backup before update-agent" +**Persona / Principles 更新**： + +``` +1. GET /api/agents/:id/persona → 获取当前数据 +2. 修改目标字段 +3. PUT /api/agents/:id/persona → 写回，返回 diff ``` -2. **应用变更**： -```bash -# 写入修改后的文件 +**其他文件更新**： + +``` +PUT /api/agents/:id/files/ → 更新指定文件内容 ``` -3. **Git 提交**： -```bash -git add -git commit -m "refactor(persona): 调整沟通风格为专业严谨 - -- 修改 persona.md 中的沟通风格描述 -- 从'友好随和'调整为'专业严谨' - -Updated by: update-agent skill -Risk level: medium -User confirmed: true -" -``` - -4. **验证变更**： -```bash -# 检查文件语法 -# 验证配置完整性 -``` +**验证变更**：调用对应的 GET 端点确认写入成功。 ### 阶段 6：回执生成 @@ -218,59 +204,18 @@ User confirmed: true ### 特殊操作：版本回滚 -**触发条件**： -- 用户说"撤销刚才的修改" -- 用户说"回滚到之前的版本" -- 用户说"恢复原来的设置" +**触发条件**：用户说"撤销刚才的修改"、"回滚到之前的版本"、"恢复原来的设置" **回滚流程**： -1. **列出可回滚版本**： -``` -可回滚的版本 +1. 通过 `GET /api/agents/:id/persona` 或 `GET /api/agents/:id/principles` 获取当前数据 +2. 列出可回滚版本供用户选择（版本信息来自后端 Git 历史） +3. 用户确认后，通过 PUT 端点写入目标版本的数据 +4. 展示变更 diff，确认回滚成功 -1. [2小时前] 调整沟通风格为专业严谨 -2. [1天前] 添加合同审查技能 -3. [3天前] 初始化仓库 +### 背景知识 -请选择要回滚到的版本： -``` - -2. **确认回滚**： -``` -回滚确认 - -将回滚到版本 #2（1天前） -以下变更将被撤销： -- 沟通风格调整 - -确认回滚？ [确认] [取消] -``` - -3. **执行回滚**： -```bash -git revert --no-edit -# 或 -git reset --soft -``` - -### 背景知识：AgentFS 仓库结构 - -> 以下信息仅供 Agent 内部理解，**不要向用户展示**。 -> 用于定位修改目标、排查问题、以及精细化维护。 - -Agent 仓库遵循 AgentFS v2 扁平结构： - -``` -/ -├── agent.json # 元数据与运行时配置 -├── persona.md # 人格定义（L0/L1/L2） -├── principles.md # 行为原则（L0/L1/L2） -├── memory/ # 记忆目录 -├── skills/ # 技能目录 -├── tools/ # 工具目录 -└── heartbeat/ # 心跳配置 -``` +> AgentFS 仓库结构与受保护路径详见 `_agentfs-background.md` 和 `_protected-paths.yaml`。 **更新操作对照表**： @@ -283,19 +228,13 @@ Agent 仓库遵循 AgentFS v2 扁平结构： | 添加记忆 | `memory/` | `PUT /api/agents/:id/files/*` | | 修改运行时配置 | `agent.json` | `PUT /api/agents/:id/files/agent.json` | -**受保护路径**（不可自动修改）： -- `persona.md` L0 section — 核心身份 -- `principles.md` "绝不做" section — 安全红线 -- `agent.json` access_control / privacy — 需 owner 确认 -- `tools/` permissions / credentials — 需 owner 确认 - ### 错误处理 | 错误场景 | 处理方式 | |---------|---------| | 尝试修改受保护路径 | 阻断操作，提示需要 owner 权限 | -| Diff 应用冲突 | 展示冲突内容，请用户手动解决 | -| Git 操作失败 | 保留修改文件，提示用户手动提交 | +| API 返回 404 | Agent 或目标文件不存在，提示用户检查 | +| API 返回 400 | 请求体格式错误，检查字段内容 | | 回滚版本不存在 | 列出可用版本，请用户重新选择 | ### API 端点 @@ -325,7 +264,30 @@ API 基础地址已注入到 system prompt 的「本机 API」小节，使用 `B --- -## 附录：Principles 更新示例 +## 附录：更新示例 + +### Persona 修改示例 + +**用户输入**："说话再正式一点，不要太随意" + +**操作流程**： + +``` +1. GET /api/agents/legal-assistant/persona + → 返回: { "L0": "...", "L1": { "role": "...", "personality": ["友好", "随和"], "communication_style": "轻松幽默" } } + +2. 修改目标字段: + - personality: ["友好", "随和"] → ["专业", "严谨"] + - communication_style: "轻松幽默" → "正式、准确、适度幽默" + +3. PUT /api/agents/legal-assistant/persona + 请求体: { "L1": { "personality": ["专业", "严谨"], "communication_style": "正式、准确、适度幽默" } } + → 返回: { "success": true, "diff": "..." } +``` + +--- + +### Principles 更新示例 ### 添加新规则