refactor: 四个全局技能复盘优化（v2.4.0）

P0 结构性修复： - update-agent 阶段 5 统一为 HTTP API，移除所有 Git 操作示例 - create-agent 响应格式与实际 API 对齐 - delete-agent 合并"前置检查"与"错误处理" P1 一致性修复： - 统一 frontmatter 字段顺序、tags 英文化 - 提取 AgentFS 背景知识到共享 _agentfs-background.md - 受保护路径统一引用 _protected-paths.yaml P2 缺失补充： - discover-agent 补充"了解更多"API 实现 - update-agent 新增 Persona 修改示例 - create-agent 补充"修改"分支交互流程 - delete-agent 补充停止 Agent 方式 P3 精简优化： - 精简版本回滚、删除范围、匹配算法描述 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-21 13:30:48 +08:00 · 2026-02-28 22:47:09 +08:00
parent 41afa07fbe
commit 0e013567d3
9 changed files with 206 additions and 204 deletions
--- a/skills/_agentfs-background.md
+++ b/skills/_agentfs-background.md
@@ -0,0 +1,37 @@
+# AgentFS 背景知识（共享）
+
+> 此文件由 create-agent、update-agent 等元技能共享引用。
+> 以下信息仅供 Agent 内部理解，**不要向用户展示**。
+
+## AgentFS v2 仓库结构
+
+每个 Agent 的仓库遵循 AgentFS v2 扁平结构：
+
+```
+<agent_id>/
+├── 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**（敏感操作）
--- 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），所有字段可选
--- 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_id>/
-├── 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`。

 ### 错误处理

--- 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 注入
--- 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: >-
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
@@ -185,79 +183,43 @@ curl -X DELETE "{agentServiceUrl}/api/agents/legal-assistant?deleteRuns=true"
 - 会话历史：已删除 5 条记录
 ```

-## 前置检查
+## 状态验证与错误处理

-### 智能体状态验证
+### 删除前状态检查

-在调用删除 API 前，系统会自动检查：
+在阶段 1 列出智能体时，通过 `GET /api/agents` 筛选状态：

-| 状态 | 是否可删除 | 处理方式 |
-|------|-----------|--------|
-| `offline` | ✅ 是 | 直接删除 |
-| `error` | ✅ 是 | 直接删除 |
-| `online` | ❌ 否 | 返回 409 错误，提示先停止 |
-| `busy` | ❌ 否 | 返回 409 错误，提示等待完成 |
-| `recovery` | ❌ 否 | 返回 409 错误，提示等待恢复 |
+| 状态 | 可否删除 | 阶段 1 展示方式 |
+|------|---------|---------------|
+| `offline` / `error` | ✅ 可删除 | 列入"可删除"列表 |
+| `online` / `busy` / `recovery` | ❌ 需先停止 | 标注"需先停止"，不进入后续流程 |

-**API 返回 409 时的处理**：
-```
-无法删除智能体 "xxx"：当前处于 online 状态。
+**停止活跃智能体的方式**：通过 Socket.IO 发送 `agent:shutdown` 事件：

-请先停止该智能体，或等待其完成任务后再删除。
-停止命令：...
+```yaml
+事件: agent:shutdown
+数据: { "agentId": "<agent_id>" }
+效果: 中止所有活跃会话 → 停止调度任务 → 状态转为 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` |
+| **保留不删** | 其他智能体数据、用户配置、全局设置、市场缓存 | — |

 ## 权限要求

--- 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 注入
--- 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
 ```

 ### 与其他技能的协作
--- 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）说明
--- 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/<path>    → 更新指定文件内容
 ```

-3. **Git 提交**：
-```bash
-git add <affected_files>
-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 <commit_hash> --no-edit
-# 或
-git reset --soft <commit_hash>
-```
-
-### 背景知识：AgentFS 仓库结构
-
-> 以下信息仅供 Agent 内部理解，**不要向用户展示**。
-> 用于定位修改目标、排查问题、以及精细化维护。
-
-Agent 仓库遵循 AgentFS v2 扁平结构：
-
-```
-<agent_id>/
-├── 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 更新示例

 ### 添加新规则