From 1c00b8e6c8ff104397dc278e8a91198e9190bd6f Mon Sep 17 00:00:00 2001 From: Yige Date: Sat, 18 Jul 2026 23:05:18 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=99=BA=E8=83=BD=E4=BD=93=20C?= =?UTF-8?q?RUD=20=E5=9B=9B=E6=8A=80=E8=83=BD=E6=94=B9=E7=BB=8F=20ManageAge?= =?UTF-8?q?nt=20=E5=86=85=E7=BD=AE=E5=B7=A5=E5=85=B7=EF=BC=88=E5=AE=9E?= =?UTF-8?q?=E4=BE=8B=E9=89=B4=E6=9D=83=E9=80=82=E9=85=8D=EF=BC=89=20(#52)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 摘要 / Summary ### 中文 主仓库 desirecore#1225 新增 `ManageAgent` 内置工具后,智能体 CRUD 四技能从"调本机 HTTP API/curl"改写为调用该工具(实例鉴权上线后 Agent 直接访问本机 API 会 401): - **create-agent 2.5.0**:`POST /api/agents` → `ManageAgent(action='create', ...)`;补充保留标识(core/desirecore)拒创、config 仅允许 llm 白名单的错误处理 - **delete-agent 2.5.0**:`DELETE /api/agents/:id` → `action='delete'`(工具层强制用户确认);错误处理改为工具拒绝语义(核心智能体/自删/活跃状态);补团队级联说明 - **discover-agent 2.6.0**:`GET /api/agents(/:id)` → `action='list'/'get'` - **update-agent 3.1.0**:结构化字段(name/description/llm/persona/principles)改经 `action='update'`(白名单+schema 校验+字段级合并语义),自由格式文件仍 Read/Write 四技能声明 `market.required_client_version: 10.0.90`,老客户端在市场端被门控禁装。中英双语正文同步改写,i18n source_hash 已重算(validate-i18n.py 通过);manifest 1.2.10。 ### English After desirecore#1225 shipped the `ManageAgent` builtin tool, the four agent-CRUD skills are rewritten from local-HTTP-API/curl instructions to tool calls (direct local API access now returns 401 under instance auth). Each skill declares `market.required_client_version: 10.0.90` so older clients are gated from installing. Both locales are rewritten in sync and i18n source hashes recomputed (validate-i18n.py passes); manifest bumped to 1.2.10. 主仓库回填:合并后将在 desirecore 主仓库执行 `npm run sync-market` 生成新的 defaults/market.zip 并单独提 PR。 --- manifest.json | 4 +- skills/create-agent/CHANGELOG.md | 6 + skills/create-agent/SKILL.md | 110 ++++++++-------- skills/create-agent/SKILL.zh-CN.md | 70 +++++------ skills/delete-agent/CHANGELOG.md | 8 ++ skills/delete-agent/SKILL.md | 119 +++++++----------- skills/delete-agent/SKILL.zh-CN.md | 105 ++++++---------- skills/discover-agent/CHANGELOG.md | 5 + skills/discover-agent/SKILL.md | 75 +++++------ skills/discover-agent/SKILL.zh-CN.md | 70 ++++++----- skills/update-agent/CHANGELOG.md | 9 ++ skills/update-agent/SKILL.md | 182 +++++++++++++++++++-------- skills/update-agent/SKILL.zh-CN.md | 169 ++++++++++++++++++------- 13 files changed, 524 insertions(+), 408 deletions(-) diff --git a/manifest.json b/manifest.json index 6691634..0d223be 100644 --- a/manifest.json +++ b/manifest.json @@ -1,6 +1,6 @@ { "name": "DesireCore Official Market", - "version": "1.2.9", + "version": "1.2.10", "schemaVersion": "1.1.0", "supportedLocales": ["zh-CN", "en-US"], "defaultLocale": "en-US", @@ -28,7 +28,7 @@ "stats": { "totalAgents": 1, "totalSkills": 50, - "lastUpdated": "2026-07-16" + "lastUpdated": "2026-07-18" }, "features": [ "curated-index", diff --git a/skills/create-agent/CHANGELOG.md b/skills/create-agent/CHANGELOG.md index 81c6cbc..f8d6b09 100644 --- a/skills/create-agent/CHANGELOG.md +++ b/skills/create-agent/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## [2.5.0] - 2026-07-18 + +- 创建方式从 HTTP API（`POST /api/agents`）改为 `ManageAgent` 内置工具（实例鉴权上线后 Agent 不再直接访问本机 API） +- 补充保留标识（core/desirecore）拒创、config 仅允许 llm 白名单的错误处理说明 +- 声明 `required_client_version: 10.0.90` + ## [2.4.0] - 2026-02-28 - 修复响应格式文档，与实际 API 返回对齐（`{ success, agentId, agent }`） diff --git a/skills/create-agent/SKILL.md b/skills/create-agent/SKILL.md index 6ad8476..457bcf2 100644 --- a/skills/create-agent/SKILL.md +++ b/skills/create-agent/SKILL.md @@ -1,9 +1,8 @@ --- name: create-agent description: >- - 通过多轮对话收集需求，调用 HTTP API 创建新的 AgentFS v2 智能体，支持自定义 persona 和 principles。Use when - 用户要求创建新智能体、培养某领域助手、或快速基于模板生成可治理 Agent。 -version: 2.4.2 + 通过多轮对话收集需求，调用 ManageAgent 内置工具创建新的 AgentFS v2 智能体，支持自定义 persona 和 principles。Use when 用户要求创建新智能体、培养某领域助手、或快速基于模板生成可治理 Agent。 +version: 2.5.0 type: meta risk_level: low status: enabled @@ -14,7 +13,7 @@ tags: - meta metadata: author: desirecore - updated_at: '2026-02-28' + updated_at: '2026-07-18' i18n: default_locale: en-US source_locale: zh-CN @@ -25,19 +24,19 @@ metadata: name: 创建智能体 short_desc: 通过自然语言对话收集需求，一键创建专业化数字智能体 description: >- - 通过多轮对话收集需求，调用 HTTP API 创建新的 AgentFS v2 智能体，支持自定义 persona 和 principles。Use when 用户要求创建新智能体、培养某领域助手、或快速基于模板生成可治理 Agent。 + 通过多轮对话收集需求，调用 ManageAgent 内置工具创建新的 AgentFS v2 智能体，支持自定义 persona 和 principles。Use when 用户要求创建新智能体、培养某领域助手、或快速基于模板生成可治理 Agent。 body: ./SKILL.zh-CN.md - source_hash: sha256:cf21692224334fce + source_hash: sha256:43425a25973ca933 translated_by: human en-US: name: Create Agent short_desc: Collect requirements through natural-language conversation and create a specialized digital Agent in one step description: >- - Collect requirements through multi-turn conversation and call the HTTP API to create a new AgentFS v2 Agent, with customizable persona and principles. Use when the user asks to create a new Agent, raise a domain assistant, or quickly produce a governable Agent from a template. + Collect requirements through multi-turn conversation and call the ManageAgent builtin tool to create a new AgentFS v2 Agent, with customizable persona and principles. Use when the user asks to create a new Agent, raise a domain assistant, or quickly produce a governable Agent from a template. body: ./SKILL.md - source_hash: sha256:cf21692224334fce - translated_by: ai:claude-opus-4-7 - translated_at: '2026-05-03' + source_hash: sha256:43425a25973ca933 + translated_by: ai:claude-fable-5 + translated_at: '2026-07-18' market: icon: >- 准确性 > 效率" + "must_do": ["Cite statutes accurately", "Mark uncertainty", "Recommend consulting a professional lawyer"], + "must_not": ["Provide litigation representation", "Substitute for formal legal advice", "Leak user consultations"], + "priority": "User safety > Accuracy > Efficiency" } } -} +}) ``` **Minimal create** (only `name`; the rest is auto-generated): -```json -{ "name": "我的助手" } +``` +ManageAgent({ "action": "create", "name": "My Assistant" }) ``` **Basic create** (`name` + `description`; `description` auto-fills persona L0): -```json -{ "name": "法律顾问", "description": "专注合同审查" } +``` +ManageAgent({ "action": "create", "name": "Legal Advisor", "description": "Focused on contract review" }) ``` Any unprovided fields are auto-filled with sensible defaults by the system. `persona` and `principles` also accept raw markdown strings (backward compatible). -**Optional**: To specify a slug ID, generate a sensible kebab-case slug from `name` (e.g. "Legal Advisor" → "legal-advisor") and include `"id": ""` in the request body. If not specified, the system auto-generates one from `name`. +**Optional parameters**: -**Successful response** (`201 Created`): +- `id`: specify a kebab-case slug ID (e.g. "Legal Advisor" → "legal-advisor"). If not specified, the system auto-generates one from `name`. Note that `core` / `desirecore` are reserved core-agent identifiers and cannot be used (including when the slug auto-generated from `name` collides with them). +- `config`: an agent.json config delta. Only the `llm` field is allowed (model, temperature, etc.); sensitive fields such as `mcp_servers` / `tool_permissions` are rejected and must be adjusted via the settings UI after creation. -```json -{ - "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" - } -} -``` +**Successful result**: -The `agent` field in the response contains the full info of the newly created Agent and can be used directly in the receipt. +> Agent "Legal Advisor Assistant" created (ID: legal-advisor-assistant), registered and ready. It can be used directly with ManageTeam or Delegate. + +The new Agent is registered online immediately after creation—no waiting or refresh needed; the returned ID can be used directly in subsequent ManageTeam / Delegate calls. ### Stage 6: Receipt Generation @@ -294,19 +283,18 @@ After successful creation, present the receipt in a user-friendly way (do not ex ### Error Handling -| Error Code | Scenario | Handling | -| ---------- | ------------------------------------- | --------------------------------- | -| 400 | Missing `name` or invalid ID format | Ask user to check input | -| 409 | Agent ID already exists | Suggest using another name | -| 500 | Internal server error | Ask user to try again later | +| Error Scenario | Handling | +| ------------------------------------------- | ------------------------------------------- | +| Missing `name` or invalid ID format | Ask user to check input | +| Agent ID already exists | Suggest another name or an explicit `id` | +| ID hits a reserved core-agent identifier | Change the name or provide another `id` | +| `config` contains non-whitelisted fields | Retry with only the `llm` field | ### Permission Requirements -- Prefer accessing the Agent Service HTTP API via the `Bash` tool with curl -- The API base URL is already injected into the "Local API" section of the system prompt; reference it directly -- Creation requires user confirmation +- Always create via the `ManageAgent` builtin tool. **Never** call the local HTTP API, curl, or write AgentFS directories directly +- The `create` action is exempt from system approval, but this skill's conversation flow still requires showing the preview and getting user confirmation first (Stage 4) ### Dependencies -- Agent Service HTTP API (`POST /api/agents`) -- The local API URL declaration in the system prompt +- `ManageAgent` builtin tool (client ≥ 10.0.90) diff --git a/skills/create-agent/SKILL.zh-CN.md b/skills/create-agent/SKILL.zh-CN.md index e0de209..287cb27 100644 --- a/skills/create-agent/SKILL.zh-CN.md +++ b/skills/create-agent/SKILL.zh-CN.md @@ -4,13 +4,13 @@ ## L0：一句话摘要 -通过自然语言对话收集需求，调用 HTTP API 创建专业化的数字智能体。 +通过自然语言对话收集需求，调用 ManageAgent 内置工具创建专业化的数字智能体。 ## L1：概述与使用场景 ### 能力描述 -create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建其他 Agent 的能力。它通过多轮对话收集用户需求，生成 persona 和 principles 内容，调用 `POST /api/agents` 完成创建。 +create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建其他 Agent 的能力。它通过多轮对话收集用户需求，生成 persona 和 principles 内容，调用 `ManageAgent` 内置工具完成创建。 ### 使用场景 @@ -35,7 +35,7 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 │ ↓ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ 回执生成 │ ←── │ API 创建 │ ←── │ 用户确认 │ +│ 回执生成 │ ←── │ 工具创建 │ ←── │ 用户确认 │ └──────────────┘ └──────────────┘ └──────────────┘ ``` @@ -150,14 +150,13 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 4. 更新预览中的对应字段 5. 再次展示完整预览 → 重新进入确认流程 -### 阶段 5：调用 API 创建 +### 阶段 5：调用 ManageAgent 创建 -**API 端点**：`POST /api/agents` +**工具调用**（结构化格式）： -**请求体**（结构化格式）： - -```json -{ +``` +ManageAgent({ + "action": "create", "name": "法律顾问小助手", "description": "专注于合同审查和法律风险评估的数字智能体", "persona": { @@ -176,43 +175,33 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 "priority": "用户安全 > 准确性 > 效率" } } -} +}) ``` **最简创建**（只需 name，其余全部自动生成）： -```json -{ "name": "我的助手" } +``` +ManageAgent({ "action": "create", "name": "我的助手" }) ``` **基础创建**（name + description，description 自动填充 persona L0）： -```json -{ "name": "法律顾问", "description": "专注合同审查" } +``` +ManageAgent({ "action": "create", "name": "法律顾问", "description": "专注合同审查" }) ``` 所有未提供的字段由系统自动补全为合理默认值。`persona` 和 `principles` 也支持传入原始 markdown 字符串（向后兼容）。 -**可选**：如需指定 slug ID，可根据 name 生成合理的 kebab-case slug（如 "法律顾问" → "legal-advisor"），在请求体中附带 `"id": ""`。不指定时系统会自动从 name 生成。 +**可选参数**： -**成功响应** (`201 Created`)： +- `id`：指定 kebab-case slug ID（如 "法律顾问" → "legal-advisor"）。不指定时系统会自动从 name 生成。注意 `core` / `desirecore` 是核心智能体保留标识，不可使用（包括 name 自动生成命中的情况）。 +- `config`：agent.json 配置增量，仅允许 `llm` 字段（模型、温度等）；mcp_servers/tool_permissions 等敏感配置会被拒绝，需在创建后经配置界面调整。 -```json -{ - "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" - } -} -``` +**成功返回**： -响应中的 `agent` 字段包含创建后的智能体完整信息，可直接用于回执展示。 +> 智能体「法律顾问小助手」已创建 (ID: fa-lv-gu-wen-xiao-zhu-shou)，已注册可用。可直接用于 ManageTeam 组队或 Delegate 委派。 + +创建完成后智能体立即注册在线，无需等待或刷新；返回的 ID 可直接用于后续 ManageTeam / Delegate 调用。 ### 阶段 6：回执生成 @@ -234,19 +223,18 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建 ### 错误处理 -| 错误码 | 场景 | 处理方式 | -| ------ | ------------------------ | ---------------- | -| 400 | 缺少 name 或 ID 格式无效 | 提示用户检查输入 | -| 409 | Agent ID 已存在 | 建议使用其他名称 | -| 500 | 服务器内部错误 | 提示用户稍后再试 | +| 错误场景 | 处理方式 | +| -------------------------------- | ------------------------------ | +| 缺少 name 或 ID 格式无效 | 提示用户检查输入 | +| Agent ID 已存在（already exists）| 建议使用其他名称或指定其他 id | +| ID 命中核心智能体保留标识 | 更换名称或显式提供其他 id | +| config 含白名单外字段 | 仅保留 llm 字段后重试 | ### 权限要求 -- 建议优先通过 `Bash` 工具调用 curl 访问 Agent Service HTTP API 完成操作 -- API 基础地址已注入到 system prompt 的「本机 API」小节，直接引用即可 -- 创建操作需要用户确认 +- 一律通过 `ManageAgent` 内置工具完成创建，**禁止**调用本机 HTTP API、curl 或直接写 AgentFS 目录 +- create 操作免系统审批，但本技能的对话流程仍要求先向用户展示预览并获得确认（阶段 4） ### 依赖 -- Agent Service HTTP API（`POST /api/agents`） -- System prompt 中的本机 API 地址声明 +- `ManageAgent` 内置工具（客户端 ≥ 10.0.90） diff --git a/skills/delete-agent/CHANGELOG.md b/skills/delete-agent/CHANGELOG.md index e4f4af2..f1e2289 100644 --- a/skills/delete-agent/CHANGELOG.md +++ b/skills/delete-agent/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [2.5.0] - 2026-07-18 + +- HTTP API 调用改为 ManageAgent 内置工具（实例鉴权后 Agent 不再直接访问本机 API，会 401） +- 删除路径改为 `ManageAgent(action='delete', id, deleteRuns)`；列出/查详情改为 `action='list' | 'get'` +- 错误处理由 HTTP 状态码改为工具返回的拒绝语义（核心智能体/自删/活跃状态/不存在） +- 补充团队级联说明（组长删除→解散、成员删除→移除） +- 声明 required_client_version 10.0.90 + ## [2.4.0] - 2026-02-28 - 统一 frontmatter 字段顺序，与其他三个技能一致 diff --git a/skills/delete-agent/SKILL.md b/skills/delete-agent/SKILL.md index 82424e3..0658cb5 100644 --- a/skills/delete-agent/SKILL.md +++ b/skills/delete-agent/SKILL.md @@ -1,7 +1,7 @@ --- name: delete-agent description: 安全删除指定的智能体及其关联数据。删除前会验证智能体状态，支持可选地删除所有会话历史。Use when 用户需要删除不再使用的智能体。 -version: 2.4.2 +version: 2.5.0 type: meta risk_level: high status: enabled @@ -12,7 +12,7 @@ tags: - meta metadata: author: desirecore - updated_at: '2026-02-28' + updated_at: '2026-07-18' i18n: default_locale: en-US source_locale: zh-CN @@ -24,16 +24,16 @@ metadata: short_desc: 安全删除智能体及其关联数据，支持多重确认与可选历史清理 description: 安全删除指定的智能体及其关联数据。删除前会验证智能体状态，支持可选地删除所有会话历史。Use when 用户需要删除不再使用的智能体。 body: ./SKILL.zh-CN.md - source_hash: sha256:148cd72a6808741e + source_hash: sha256:6b971559e1d4ccc0 translated_by: human en-US: name: Delete Agent short_desc: Safely delete an Agent and its associated data, with multi-step confirmation and optional history cleanup description: Safely delete a specified Agent and its associated data. Verifies the Agent's state before deletion and optionally removes all session history. Use when the user needs to delete an Agent that is no longer in use. body: ./SKILL.md - source_hash: sha256:148cd72a6808741e - translated_by: ai:claude-opus-4-7 - translated_at: '2026-05-03' + source_hash: sha256:6b971559e1d4ccc0 + translated_by: ai:claude-fable-5 + translated_at: '2026-07-18' market: icon: >- `{agentServiceUrl}` is taken from the Agent Service address in the "Local API" section of the system prompt. +**Parameters**: + +- `id`: the target Agent ID (required) +- `deleteRuns`: `true` to also delete all session history; `false` (default) to keep history, can be omitted + +The tool shows a user confirmation popup before executing; once confirmed, it completes the deletion, including team cascading: a team where the target is the leader is automatically disbanded, and a target that is a member is automatically removed. ### Phase 6: Return the Operation Result -**Successful response handling**: - -```json -{ - "deleted": true, - "cleanedPaths": [ - "/Users/xxx/.desirecore/agents/legal-assistant", - "/Users/xxx/.desirecore/users/xxx/agents/legal-assistant" - ], - "deletedRunsCount": 5, - "memoryCleaned": { - "scheduler": true, - "queue": 0, - "messaging": 3, - "mcp": true - } -} -``` +**Successful receipt handling**: the tool returns the deletion result, including fields such as the cleaned paths, the number of deleted sessions, and in-memory state cleanup details. Generate the report from these. **Result report template**: @@ -213,37 +194,32 @@ Cleanup details: - Message subscriptions: 3 subscriptions canceled - MCP connection: closed - Session history: 5 records deleted +- Team cascading: the target's team has been disbanded / the target has been removed from its team (if applicable) ``` ## State Validation and Error Handling ### Pre-deletion State Check -When listing Agents in Phase 1, filter status via `GET /api/agents`: +When listing Agents in Phase 1, filter by the status returned from `ManageAgent(action='list')`: | Status | Deletable? | Phase 1 Display | | ------------------------------ | ----------- | ------------------------------ | | `offline` / `error` | ✅ Yes | Listed under "Deletable" | | `online` / `busy` / `recovery` | ❌ Stop first | Annotated "must be stopped"; not entered into the subsequent flow | -**How to stop an active Agent**: send the `agent:shutdown` event via Socket.IO: +> Agents in an active state (online/busy/recovery) are directly rejected by the delete action of `ManageAgent`. Prompt the user to stop the Agent manually in the UI, or wait until it finishes its current task before deleting. -```yaml -event: agent:shutdown -data: { 'agentId': '' } -effect: abort all active sessions → stop scheduled tasks → status becomes offline -``` +### Error Semantics Returned by the Tool -> The Agent cannot directly send Socket.IO events. If the target Agent is active, prompt the user to stop it manually in the UI, or wait until it finishes its current task before deleting. +`ManageAgent(action='delete', ...)` returns a clear error in the following cases; use them to explain the situation to the user and suggest next steps: -### API Error Codes - -| Code | Scenario | Handling | -| ------ | ---------------------------------------------------------------------------- | --------------------------------- | -| 400 | Invalid Agent ID format | Ask the user to check the Agent name | -| 404 | Agent does not exist | Inform the user the Agent has already been deleted or the ID is wrong | -| 409 | Agent is currently active (API returns `Cannot delete agent "xxx": currently online`) | Ask the user to stop the Agent in the UI first | -| 500 | Internal server error | Ask the user to try again later | +| Rejection Scenario | Trigger Condition | Handling | +| ------------------ | ------------------------------------------------------------- | ------------------------------------- | +| Core Agent rejected | The target is a core Agent (desirecore/core/bound UUID) | Inform the user that core Agents cannot be deleted | +| Self-deletion rejected | The target is the caller itself | Inform the user that an Agent cannot delete itself | +| Active state rejected | The target is in `online`/`busy`/`recovery` state | Prompt the user to stop the Agent in the UI first | +| Not found | No Agent exists for the target ID | Inform the user the Agent has already been deleted or the ID is wrong | ## Deletion Scope @@ -251,15 +227,14 @@ effect: abort all active sessions → stop scheduled tasks → status becomes of | ------------ | -------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **Always deleted** | AgentFS directory (config, persona, rules, skills, tools, memory), user preference data, in-memory state (scheduler, queue, message subscriptions, MCP connection), registry entries | Unconditional | | **Optionally deleted** | Session history, topic index | `deleteRuns=true` | +| **Team cascading** | Target is the leader → its team is disbanded; target is a member → removed from the team | Automatic | | **Preserved** | Data of other Agents, user configuration, global settings, market cache | — | ## Permission Requirements -- Prefer using the `Bash` tool to call curl against the Agent Service HTTP API to perform the operation -- The API base address is injected into the "Local API" section of the system prompt; reference it directly -- The delete operation requires explicit user confirmation (high-risk operation) +- Uses the in-process builtin tool `ManageAgent` to list, query, and delete Agents +- The delete action is a high-risk operation; the tool layer will force a user confirmation popup ## Dependencies -- Agent Service HTTP API (`DELETE /api/agents/{agentId}`) -- The Local API address declaration in the system prompt +- The in-process builtin tool `ManageAgent` (`action='list' | 'get' | 'delete'`) diff --git a/skills/delete-agent/SKILL.zh-CN.md b/skills/delete-agent/SKILL.zh-CN.md index 3b60457..05bc52f 100644 --- a/skills/delete-agent/SKILL.zh-CN.md +++ b/skills/delete-agent/SKILL.zh-CN.md @@ -10,7 +10,7 @@ ### 能力描述 -delete-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 安全删除其他智能体的能力。它会执行完整的前置检查、状态验证，并清理所有关联数据。 +delete-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 安全删除其他智能体的能力。它通过进程内内置工具 **ManageAgent** 执行完整的前置检查、状态验证，并清理所有关联数据。 ### 使用场景 @@ -21,8 +21,8 @@ delete-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 安全 ### 核心价值 -- **安全性**：多重检查确保不会误删活跃智能体 -- **完整性**：清理文件系统、内存状态、消息订阅等所有关联数据 +- **安全性**：工具层多重拒绝规则确保不会误删核心智能体、调用方自身或活跃智能体 +- **完整性**：清理文件系统、内存状态、消息订阅等所有关联数据，并处理团队级联 - **可恢复性**：默认保留会话历史，可选择是否删除 ## L2：详细规范 @@ -37,8 +37,8 @@ delete-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 安全 │ ↓ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ 返回结果 │ ←── │ 执行删除 │ ←── │ 最终确认 │ -│ 与回执 │ │ API 调用 │ │ │ +│ 返回结果 │ ←── │ 执行删除 │ ←── │ 告知会弹确认 │ +│ 与回执 │ │ ManageAgent │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ ``` @@ -48,9 +48,10 @@ delete-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 安全 **操作**： -- 调用 `GET /api/agents` 获取所有智能体列表 +- 调用 `ManageAgent(action='list')` 获取所有智能体列表 - 筛选出状态为 `offline` 或 `error` 的智能体（可安全删除） -- 标注出 `online`/`busy`/`recovery` 状态的智能体（需先停止） +- 标注出 `online`/`busy`/`recovery` 状态的智能体（需先停止，否则会被工具拒绝） +- 如需查看某个智能体的详细信息，调用 `ManageAgent(action='get', id='')` **输出示例**： @@ -95,57 +96,35 @@ delete-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 安全 **参数映射**： - 用户选择"是" → `deleteRuns=true` -- 用户选择"否" → `deleteRuns=false`（默认） +- 用户选择"否" → `deleteRuns=false`（默认，可省略） -### 阶段 4：最终确认 +### 阶段 4：告知工具级确认 -**确认摘要**： +`ManageAgent` 的 delete 动作在工具层**始终触发用户确认弹窗**，无需在技能层再重复一遍二次确认话术。但在调用前应先告知用户： ``` -请确认删除操作： -- 目标智能体：法律顾问助手 (legal-assistant) -- 删除范围：智能体 + 会话历史（如用户选择） -- 风险等级：高（不可恢复） - -确认执行删除？（是/否） +即将删除智能体 "法律顾问助手" (legal-assistant)，删除范围为智能体 + 会话历史（如用户选择）。 +系统会弹出确认窗口，请在弹窗中确认执行。 ``` -### 阶段 5：执行删除 API 调用 +### 阶段 5：执行删除（ManageAgent 工具） -**API 端点**：`DELETE /api/agents/{agentId}` +**工具调用**： -**查询参数**： - -- `deleteRuns`: `'true'` 或 `'false'` - -**请求示例**： - -```bash -curl -X DELETE "{agentServiceUrl}/api/agents/legal-assistant?deleteRuns=true" +``` +ManageAgent(action='delete', id='legal-assistant', deleteRuns=true) ``` -> `{agentServiceUrl}` 取自 system prompt「本机 API」小节中的 Agent Service 地址。 +**参数**： + +- `id`：目标智能体 ID（必填） +- `deleteRuns`：`true` 一并删除全部会话历史；`false`（默认）保留历史，可省略 + +工具会在执行前弹出用户确认；确认后完成删除，包含团队级联处理：目标是组长的团队自动解散，是成员的自动移除。 ### 阶段 6：返回操作结果 -**成功响应处理**： - -```json -{ - "deleted": true, - "cleanedPaths": [ - "/Users/xxx/.desirecore/agents/legal-assistant", - "/Users/xxx/.desirecore/users/xxx/agents/legal-assistant" - ], - "deletedRunsCount": 5, - "memoryCleaned": { - "scheduler": true, - "queue": 0, - "messaging": 3, - "mcp": true - } -} -``` +**成功回执处理**：工具返回删除结果，包含已清理路径、删除的会话数量、内存状态清理详情等字段。据此生成报告。 **结果报告模板**： @@ -158,37 +137,32 @@ curl -X DELETE "{agentServiceUrl}/api/agents/legal-assistant?deleteRuns=true" - 消息订阅：已取消 3 个订阅 - MCP 连接：已关闭 - 会话历史：已删除 5 条记录 +- 团队级联：目标所在团队已解散/已从团队移除（如涉及） ``` ## 状态验证与错误处理 ### 删除前状态检查 -在阶段 1 列出智能体时，通过 `GET /api/agents` 筛选状态： +在阶段 1 列出智能体时，通过 `ManageAgent(action='list')` 返回的状态筛选： | 状态 | 可否删除 | 阶段 1 展示方式 | | ------------------------------ | ----------- | ------------------------------ | | `offline` / `error` | ✅ 可删除 | 列入"可删除"列表 | | `online` / `busy` / `recovery` | ❌ 需先停止 | 标注"需先停止"，不进入后续流程 | -**停止活跃智能体的方式**：通过 Socket.IO 发送 `agent:shutdown` 事件： +> 活跃状态（online/busy/recovery）的智能体会被 `ManageAgent` 的 delete 动作直接拒绝。应提示用户在 UI 中手动停止该智能体，或等待其完成当前任务后再删除。 -```yaml -事件: agent:shutdown -数据: { 'agentId': '' } -效果: 中止所有活跃会话 → 停止调度任务 → 状态转为 offline -``` +### 工具返回的错误语义 -> Agent 无法直接发送 Socket.IO 事件。如果目标智能体处于活跃状态，应提示用户在 UI 中手动停止，或等待其完成当前任务后再删除。 +`ManageAgent(action='delete', ...)` 在以下情形会返回明确错误，应据此向用户解释并给出下一步建议： -### API 错误码 - -| 错误码 | 场景 | 处理方式 | -| ------ | ---------------------------------------------------------------------------- | -------------------------------- | -| 400 | Agent ID 格式无效 | 提示用户检查智能体名称 | -| 404 | 智能体不存在 | 告知用户智能体已被删除或 ID 错误 | -| 409 | 智能体处于活跃状态（API 返回 `Cannot delete agent "xxx": currently online`） | 提示用户先在 UI 中停止智能体 | -| 500 | 服务器内部错误 | 提示用户稍后再试 | +| 拒绝场景 | 触发条件 | 处理方式 | +| ---------------- | -------------------------------------------------------------- | -------------------------------------- | +| 核心智能体拒绝 | 目标为核心智能体（desirecore/core/绑定 UUID） | 告知用户核心智能体不可删除 | +| 自删拒绝 | 目标为调用方自身 | 告知用户智能体不能删除自己 | +| 活跃状态拒绝 | 目标处于 `online`/`busy`/`recovery` 状态 | 提示用户先在 UI 中停止该智能体 | +| 不存在 | 目标 ID 对应的智能体不存在 | 告知用户智能体已被删除或 ID 有误 | ## 删除范围说明 @@ -196,15 +170,14 @@ curl -X DELETE "{agentServiceUrl}/api/agents/legal-assistant?deleteRuns=true" | ------------ | -------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **始终删除** | AgentFS 目录（配置、人格、规则、技能、工具、记忆）、用户偏好数据、内存状态（调度器、队列、消息订阅、MCP 连接）、注册表条目 | 无条件 | | **可选删除** | 会话历史、话题索引 | `deleteRuns=true` | +| **团队级联** | 目标是组长 → 解散其团队；目标是成员 → 从团队移除 | 自动 | | **保留不删** | 其他智能体数据、用户配置、全局设置、市场缓存 | — | ## 权限要求 -- 建议优先通过 `Bash` 工具调用 curl 访问 Agent Service HTTP API 完成操作 -- API 基础地址已注入到 system prompt 的「本机 API」小节，直接引用即可 -- 删除操作需要用户显式确认（高风险操作） +- 通过进程内内置工具 `ManageAgent` 完成智能体的列出、查询与删除 +- delete 动作为高风险操作，工具层会强制弹出用户确认 ## 依赖 -- Agent Service HTTP API（`DELETE /api/agents/{agentId}`） -- System prompt 中的本机 API 地址声明 +- 进程内内置工具 `ManageAgent`（`action='list' | 'get' | 'delete'`） diff --git a/skills/discover-agent/CHANGELOG.md b/skills/discover-agent/CHANGELOG.md index cb9262e..09300e6 100644 --- a/skills/discover-agent/CHANGELOG.md +++ b/skills/discover-agent/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## [2.6.0] - 2026-07-18 + +- HTTP API 调用改为 ManageAgent 内置工具（实例鉴权后 Agent 不再直接访问本机 API） +- 声明 required_client_version 10.0.90 + ## [2.4.0] - 2026-02-28 - 补充"了解更多"的具体 API 实现（GET /api/agents/:id + 结构化 persona 端点） diff --git a/skills/discover-agent/SKILL.md b/skills/discover-agent/SKILL.md index 3ee2d3c..61153f2 100644 --- a/skills/discover-agent/SKILL.md +++ b/skills/discover-agent/SKILL.md @@ -1,7 +1,7 @@ --- name: discover-agent description: 根据用户需求推荐最匹配的智能体，展示候选列表并引导选择。Use when 用户描述需求但不确定该找哪个智能体帮忙，或想浏览可用的智能体。 -version: 2.5.2 +version: 2.6.0 type: procedural risk_level: low status: enabled @@ -12,7 +12,7 @@ tags: - recommendation metadata: author: desirecore - updated_at: '2026-02-28' + updated_at: '2026-07-18' i18n: default_locale: en-US source_locale: zh-CN @@ -24,7 +24,7 @@ metadata: short_desc: 根据需求描述智能推荐最匹配的智能体，引导快速选择 description: 根据用户需求推荐最匹配的智能体，展示候选列表并引导选择。Use when 用户描述需求但不确定该找哪个智能体帮忙，或想浏览可用的智能体。 body: ./SKILL.zh-CN.md - source_hash: sha256:28ecd07724adda9a + source_hash: sha256:99bddbbaea15b194 translated_by: human en-US: name: Discover Agent @@ -32,9 +32,9 @@ metadata: description: >- Recommend the best-matching Agent based on the user’s needs, show a candidate list, and guide selection. Use when the user describes a need but is unsure which Agent to ask for help, or wants to browse available Agents. body: ./SKILL.md - source_hash: sha256:4be238743dee6fc4 - translated_by: ai:openai:gpt-5.4-mini - translated_at: '2026-07-07' + source_hash: sha256:99bddbbaea15b194 + translated_by: ai:claude-fable-5 + translated_at: '2026-07-18' market: icon: >- `get` is a read-only query; no user confirmation is required and it is approval-free. If the target does not exist, it returns the error "智能体不存在: ". When presenting to the user, show key information in natural language/table format: @@ -252,10 +257,11 @@ When presenting to the user, show key information in natural language/table form | 字段 | 内容 | |------|------| -| Role positioning | 专注合同审查和法律风险评估 | -| Personality traits | 专业、严谨、审慎 | -| Skill count | 3 个 | -| Current status | 在线 | +| 描述 | 专注合同审查和法律风险评估 | +| 当前状态 | 在线 | +| 版本 | 1.2.0 | +| 技能 / 工具 | 3 个技能，5 个工具 | +| Git 仓库 | 干净（无未提交变更） | Need to talk with this Agent? ``` @@ -280,18 +286,17 @@ context_handoff: | Error scenario | Handling method | | -------------- | --------------- | -| API call failure | Prompt a network error and suggest trying again later | +| Tool call failure | Prompt the error message and suggest trying again later | | Agent list is empty | Guide the user to create the first Agent | | User description is too vague | Ask follow-up questions and provide domain options as guidance | +| Target Agent does not exist | When `get` returns "智能体不存在: ", fall back to `list` to re-confirm available Agents | | Recommended Agent has an abnormal status | Mark the status and suggest choosing another online Agent | ### Permission requirements -- Prefer using the `Bash` Tool to call curl and access the Agent Service HTTP API to complete operations -- The API base address is injected into the system prompt’s "本机 API" section, so reference it directly -- Read-only operation, no risk +- Complete Agent retrieval and detail lookup via the built-in tool `ManageAgent` +- Both `list` and `get` are read-only queries; no user confirmation is required, they are approval-free, and carry no risk ### Dependencies -- Agent Service HTTP API (`GET /api/agents`) -- The local API address declaration in the system prompt +- Built-in tool `ManageAgent` (`action='list'` to retrieve the list, `action='get'` to query details) diff --git a/skills/discover-agent/SKILL.zh-CN.md b/skills/discover-agent/SKILL.zh-CN.md index 9811df3..8183f7b 100644 --- a/skills/discover-agent/SKILL.zh-CN.md +++ b/skills/discover-agent/SKILL.zh-CN.md @@ -63,25 +63,26 @@ discover-agent 是一个**流程型技能（Procedural Skill）**，赋予 Desir ### 阶段 2：Agent 检索 -**数据源**：调用 `GET /api/agents` 获取所有已注册的智能体列表。 +**数据源**：调用 `ManageAgent(action='list')` 获取所有已注册的智能体列表。 -**API 调用**： +**工具调用**： -```bash -GET /api/agents +``` +ManageAgent(action='list') ``` -**返回数据中的关键字段**： +**返回内容**：一份紧凑列表，每行包含以下关键字段： -- `id` — 智能体唯一标识 - `name` — 智能体名称 +- `id` — 智能体唯一标识 +- `status` — 当前状态（online/busy/idle/offline） - `description` — 智能体描述 -- `skills` — 技能列表 -- `status` — 当前状态（online/offline/busy） + +> `list` 为只读查询，无需用户确认、免审批。 **过滤规则**： -- 默认只展示 `status: online` 或 `status: offline` 的智能体 +- 默认展示除 offline 之外的智能体，offline 智能体仅在无更优候选时作为补充展示 - 排除系统内部智能体（如 DesireCore 自身，除非用户显式要求） ### 阶段 3：匹配评估 @@ -169,26 +170,29 @@ GET /api/agents **用户选择后的操作**： -| 用户选择 | 后续操作 | -| ---------------- | ------------------------------------------------------------- | -| 选择了某个智能体 | 切换到该智能体的对话，传递用户需求上下文 | -| 要求了解更多 | 调用 `GET /api/agents/:id` 获取详情，展示结构化信息（见下方） | -| 不满意候选 | 引导用户细化需求或建议创建新 Agent | -| 选择"创建新的" | 调用 create-agent 技能，传递已收集的需求信息 | +| 用户选择 | 后续操作 | +| ---------------- | ----------------------------------------------------------------- | +| 选择了某个智能体 | 切换到该智能体的对话，传递用户需求上下文 | +| 要求了解更多 | 调用 `ManageAgent(action='get', id='')` 获取详情，展示结构化信息（见下方） | +| 不满意候选 | 引导用户细化需求或建议创建新 Agent | +| 选择"创建新的" | 调用 create-agent 技能，传递已收集的需求信息 | **"了解更多"的实现**： -调用 `GET /api/agents/:id` 获取详情，并可选调用结构化端点获取人格/规则： +调用 `ManageAgent(action='get', 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 } ``` +ManageAgent(action='get', id='legal-assistant') +``` + +**返回内容中的关键字段**： + +- 名称、描述、状态 +- 版本 +- 技能数 / 工具数 +- Git 仓库状态 + +> `get` 为只读查询，无需用户确认、免审批。目标不存在时返回错误「智能体不存在: 」。 向用户展示时，以自然语言/表格形式呈现关键信息： @@ -197,10 +201,11 @@ GET /api/agents/{agentId}/persona | 字段 | 内容 | |------|------| -| 角色定位 | 专注合同审查和法律风险评估 | -| 性格特征 | 专业、严谨、审慎 | -| 技能数量 | 3 个 | +| 描述 | 专注合同审查和法律风险评估 | | 当前状态 | 在线 | +| 版本 | 1.2.0 | +| 技能 / 工具 | 3 个技能，5 个工具 | +| Git 仓库 | 干净（无未提交变更） | 需要与这个智能体对话吗？ ``` @@ -225,18 +230,17 @@ context_handoff: | 错误场景 | 处理方式 | | --------------------- | -------------------------------- | -| API 调用失败 | 提示网络错误，建议稍后重试 | +| 工具调用失败 | 提示错误信息，建议稍后重试 | | Agent 列表为空 | 引导用户创建第一个智能体 | | 用户描述过于模糊 | 追问具体需求，提供领域选项引导 | +| 目标智能体不存在 | `get` 返回「智能体不存在: 」时，回退到 `list` 重新确认可用智能体 | | 推荐的 Agent 状态异常 | 标注状态，建议选择其他在线 Agent | ### 权限要求 -- 建议优先通过 `Bash` 工具调用 curl 访问 Agent Service HTTP API 完成操作 -- API 基础地址已注入到 system prompt 的「本机 API」小节，直接引用即可 -- 只读操作，无风险 +- 通过内置工具 `ManageAgent` 完成智能体检索与详情查询 +- `list` / `get` 均为只读查询，无需用户确认、免审批，无风险 ### 依赖 -- Agent Service HTTP API（`GET /api/agents`） -- System prompt 中的本机 API 地址声明 +- 内置工具 `ManageAgent`（`action='list'` 检索列表、`action='get'` 查询详情） diff --git a/skills/update-agent/CHANGELOG.md b/skills/update-agent/CHANGELOG.md index 802f408..b7aeda0 100644 --- a/skills/update-agent/CHANGELOG.md +++ b/skills/update-agent/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [3.1.0] - 2026-07-18 + +- 结构化字段（name/description/llm/persona/principles）改经进程内内置工具 **ManageAgent** 的 `update` 动作更新（白名单 + schema 校验 + 合并语义），移除对 `agent.json` / `persona.md` / `principles.md` 的直接 Write 指引 +- 补充合并语义说明：结构化 persona/principles 为字段级合并（省略字段保留原值）、markdown 字符串为整体替换、config.llm 为增量浅合并；非法配置不落盘 +- 补充确认行为：更新自身免确认、更新其他智能体触发用户确认、核心智能体（desirecore/core）拒绝更新 +- 补充错误处理：config 非白名单字段被拒、schema 校验失败、部分字段写入失败仅重试失败字段 +- 记忆、技能、工具等自由格式文件仍用 Read/Write 直接编辑（注意 `_protected-paths.yaml` 受保护路径），版本回滚按目标类型分流（结构化走 ManageAgent、自由文件直接写回） +- 声明 `required_client_version: 10.0.90` + ## [3.0.0] - 2026-03-17 - **Breaking**：从 HTTP API 迁移到 AgentFS 直接文件操作 diff --git a/skills/update-agent/SKILL.md b/skills/update-agent/SKILL.md index ffbda76..5356fa2 100644 --- a/skills/update-agent/SKILL.md +++ b/skills/update-agent/SKILL.md @@ -3,7 +3,7 @@ name: update-agent description: >- 安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent 行为、安装/卸载技能、调整配置、回滚变更或修订规则。 -version: 3.0.5 +version: 3.1.0 type: meta risk_level: low status: enabled @@ -14,7 +14,7 @@ tags: - meta metadata: author: desirecore - updated_at: '2026-03-17' + updated_at: '2026-07-18' i18n: default_locale: en-US source_locale: zh-CN @@ -27,7 +27,7 @@ metadata: description: >- 安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent 行为、安装/卸载技能、调整配置、回滚变更或修订规则。 body: ./SKILL.zh-CN.md - source_hash: sha256:a0fecd84f92204bd + source_hash: sha256:eeb2187b0f08bc47 translated_by: human en-US: name: Update Agent @@ -35,9 +35,9 @@ metadata: description: >- Safely update an existing Agent's config, persona, principles, skills, and memory, producing reviewable diffs that are applied and committed only after confirmation. Use when the user asks to modify Agent behavior, install/uninstall skills, adjust config, roll back changes, or revise rules. body: ./SKILL.md - source_hash: sha256:a920af860d6f6a19 - translated_by: human - translated_at: '2026-05-03' + source_hash: sha256:eeb2187b0f08bc47 + translated_by: ai:claude-fable-5 + translated_at: '2026-07-18' market: icon: >- **Renaming an Agent's display name — you MUST edit two files to keep them in sync.** If the user wants to change the Agent's **display name** (e.g. "rename X to Y"), use the Edit tool to update **both**: (1) the `name` field in `agent.json`, and (2) the first-line title heading (`# Name`) in `persona.md`. Editing only one leaves the display name and the persona title out of sync. **Never claim the rename is done without actually editing the files** — if no edit runs, nothing changes on disk and the Agent list will not refresh. +#### Path A: Structured fields → ManageAgent built-in tool (mandatory) + +The following fields **must** be updated through the `update` action of the in-process built-in tool `ManageAgent`. **Never** directly Write `agent.json` / `persona.md` / `principles.md`: + +| Field | Constraint | Storage location | +| ------------- | ----------------------------------------------------- | ----------------- | +| `name` | 1–50 characters | `agent.json` | +| `description` | ≤200 characters | `agent.json` | +| `config.llm` | Incremental shallow merge; **config only allows `llm`** | `agent.json` | +| `persona` | Structured object `{L0, L1:{...}, L2}` or markdown string | `persona.md` | +| `principles` | Structured object `{L0, L1:{...}, L2}` or markdown string | `principles.md` | + +**Call forms**: + +``` +ManageAgent(action='update', id='', name='New name') +ManageAgent(action='update', id='', description='One-line summary') +ManageAgent(action='update', id='', config={ llm: { model: 'xxx', temperature: 0.7 } }) +ManageAgent(action='update', id='', persona={ L1: { personality: 'professional, rigorous' } }) +ManageAgent(action='update', id='', principles='...(full markdown)...') +``` + +**Merge semantics (important)**: + +- Structured `persona` / `principles` are **field-level merges**: omitted fields retain their original values (e.g. passing only `L1.personality` will not clear L0 / role) +- A markdown string is a **whole replacement** (used to rewrite the entire document) +- `config.llm` is an **incremental shallow merge**: only the keys you pass are overwritten +- The merged `agent.json` is validated against the schema as a whole; invalid config is never written to disk + +**Confirmation behavior**: + +- Updating **yourself** requires no secondary confirmation +- Updating **another Agent** triggers user confirmation (stacked on top of this skill's diff confirmation) +- The core Agent (`desirecore` / `core`) refuses updates + +**Read before you write**: Before making a change, read the current values with `ManageAgent(action='get', id='')`, to generate the diff and verify field names (the actual field names of persona / principles follow the structure returned by `get`). + +**config allowlist**: `config` only accepts `llm`. Passing `mcp_servers` / `tool_permissions` / `version` / `id`, etc., is rejected with the field name indicated — runtime config other than `llm` does not go through ManageAgent; see "Stage 5 · Path B" and Error Handling. + +**Partial write failure**: The tool reports precisely "which fields took effect, which one failed"; on retry, **submit only the failed fields**, do not resend everything. + +> **Renaming is a single call.** When the user wants to change the **display name** (e.g. "rename X to Y"), just call `ManageAgent(action='update', id='', name='Y')` — `name` is written to `agent.json` and triggers the Agent list to refresh; no need to manually edit any other file. If the user also wants the persona document title synced, append one `persona` update in the same round. **Never claim the rename is done without actually calling ManageAgent.** + +#### Path B: Free-form files → edit directly with Read/Write + +Free-form files such as memory, skills, and tools are not in ManageAgent's scope and are still edited directly with the Read/Write tools: + +| Target | AgentFS path | +| ------------ | ------------ | +| Memory entry | `memory/` | +| Skill package | `skills/` | +| Tools config | `tools/` | **AgentFS root directory**: `${DESIRECORE_ROOT}/agents//` -**Read file**: Use the `cat` command to read the current contents of the target file. +**Read file**: Use the Read tool to read the current contents of the target file. -**Write file**: Use a text-editing tool to write directly to the target file. After writing, re-read the file to verify the contents are correct. +**Write file**: Use the Write / Edit tool to write directly to the target file. After writing, re-read the file to verify the contents are correct. -**Note**: After writing the file directly, the backend file watcher automatically detects the change and triggers a Git commit; no manual git command is required. +**Protected paths**: Before editing, cross-check `_protected-paths.yaml`; touching a protected path should be blocked with a prompt that owner permission is required. + +**Note**: After directly writing a free-form file, the backend file watcher automatically detects the change and triggers a Git commit; no manual git command is required. ### Stage 6: Receipt Generation @@ -228,9 +287,13 @@ After a successful change, present a user-friendly receipt (do not expose intern 1. Run `git log --oneline -10` in the Agent directory to view recent version history 2. Use `git show :` to fetch the file contents of the target version, and present them to the user for confirmation -3. After user confirmation, write the target version's contents to the corresponding file +3. After user confirmation, apply according to the target file type: + - **Structured fields** (`persona.md` / `principles.md` / the name/description/llm in `agent.json`) → write back with `ManageAgent(action='update', ...)` (persona / principles are **wholly replaced** with that historical content as a markdown string) + - **Free-form files** (`memory/` / `skills/`) → write back directly with the Write tool 4. Show the change diff and confirm rollback success +(`git log` / `git show` are only used to **read** history; write-back always goes through the two paths above — do not use git commands to directly rewrite working-tree files.) + ```bash # 查看版本历史 cd ${DESIRECORE_ROOT}/agents/ @@ -246,24 +309,31 @@ git show :persona.md **Update operation reference table**: -| User Intent | Target File | AgentFS Path | -| ---------------------------- | --------------- | ---------------------------------------------- | -| **Rename (display name)** | `agent.json` **+** `persona.md` | Edit BOTH: `name` in `agent.json` AND the `# Title` first line in `persona.md` | -| Modify personality/style | `persona.md` | `${DESIRECORE_ROOT}/agents//persona.md` | -| Modify behavioral rules | `principles.md` | `${DESIRECORE_ROOT}/agents//principles.md` | -| Install/uninstall skills | `skills/` | `${DESIRECORE_ROOT}/agents//skills/` | -| Modify tools config | `tools/` | `${DESIRECORE_ROOT}/agents//tools/` | -| Add memory | `memory/` | `${DESIRECORE_ROOT}/agents//memory/` | -| Modify runtime config | `agent.json` | `${DESIRECORE_ROOT}/agents//agent.json` | +| User Intent | Update Method | +| ------------------------------- | ----------------------------------------------------------------------- | +| **Rename (display name)** | `ManageAgent(action='update', id, name='...')` | +| Edit summary | `ManageAgent(action='update', id, description='...')` | +| Modify LLM config (model/temperature/etc.) | `ManageAgent(action='update', id, config={ llm: {...} })` | +| Modify personality/style | `ManageAgent(action='update', id, persona={...} or markdown)` | +| Modify behavioral rules | `ManageAgent(action='update', id, principles={...} or markdown)` | +| Install/uninstall skills | Read/Write `skills/` (`${DESIRECORE_ROOT}/agents//skills/`) | +| Add memory | Read/Write `memory/` (`${DESIRECORE_ROOT}/agents//memory/`) | +| Modify tools config | Read/Write `tools/` (`${DESIRECORE_ROOT}/agents//tools/`, mind protected paths) | + +> Runtime config in `agent.json` other than `llm` (`mcp_servers` / `tool_permissions`, etc.) is currently not in the ManageAgent allowlist, and should not be written to `agent.json` directly to bypass validation. When such a need arises, explain to the user that it must be handled through the corresponding mechanism for now. ### Error Handling -| Error Scenario | Handling | -| ----------------------------------- | -------------------------------------------------------- | -| Attempt to modify a protected path | Block the operation; prompt that owner permission is required | -| File does not exist | The Agent or target file does not exist; ask user to check | -| Insufficient permission | Filesystem permission error; ask user to check directory permissions | -| Rollback target version not found | List available versions and ask the user to reselect | +| Error Scenario | Handling | +| ------------------------------------- | ------------------------------------------------------------------- | +| `config` contains a non-allowlisted field | ManageAgent rejects it and indicates the field name; switch to the corresponding mechanism or tell the user it is not yet supported | +| Schema validation fails | Invalid config is not written to disk; fix the fields per the tool's response and retry | +| Updating the core Agent (desirecore/core) | ManageAgent refuses the update; tell the user the core Agent cannot be modified | +| Partial field write failure | The tool reports which fields took effect / failed; retry only the failed fields, do not resend everything | +| Attempt to modify a protected path (free-form file) | Block the operation; prompt that owner permission is required | +| File does not exist | The Agent or target file does not exist; ask the user to check | +| Insufficient permission | Filesystem permission error; ask the user to check directory permissions | +| Rollback target version not found | List available versions and ask the user to reselect | ### Permission Requirements @@ -286,28 +356,26 @@ git show :persona.md **Operation flow**: -```bash -# 1. 读取当前 persona.md -cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md +``` +# 1. 读取当前 persona，定位要改的字段（字段名以返回结构为准） +ManageAgent(action='get', id='legal-assistant') -# 输出示例: -# # 法律顾问小助手 -# ## L0 -# 专业的法律咨询助手 -# ## L1 -# ### Role -# 法律顾问 -# ### Personality -# 友好、随和 -# ### Communication Style -# 轻松幽默 +# 返回示例（persona 部分）: +# L0: 专业的法律咨询助手 +# L1: +# role: 法律顾问 +# personality: 友好、随和 +# communicationStyle: 轻松幽默 # 2. 分析需要修改的部分，生成 diff 展示给用户确认 -# 3. 用户确认后，直接编辑文件，将 Personality 和 Communication Style 修改为目标值 +# 3. 用户确认后，用 ManageAgent 字段级合并更新（只改这两个字段，L0/role 保留） +ManageAgent(action='update', id='legal-assistant', persona={ + L1: { personality: '专业、严谨', communicationStyle: '正式、克制' } +}) -# 4. 验证写入结果 -cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md +# 4. 复核结果 +ManageAgent(action='get', id='legal-assistant') ``` --- @@ -333,6 +401,14 @@ cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md ... ``` +**Apply after user confirmation**: First read the current principles with `ManageAgent(action='get', id)`, then replace the whole document (including the new rule) as a markdown string: + +``` +ManageAgent(action='update', id='legal-assistant', principles='...(full markdown, including the new rule)...') +``` + +(If you only change one field of the structured object, you can also use a field-level merge and pass `principles={ L1: { must: [...] } }` — the field names and structure follow what `get` returns.) + ### Modify Existing Rule **User input**: "Don't remind me every time, it's too verbose" @@ -347,3 +423,5 @@ cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md - - 每次回答后都提醒用户检查内容 + - 仅在重要决策时提醒用户检查内容 ``` + +**Apply after user confirmation**: Same as above — write the modified content back with `ManageAgent(action='update', id, principles=...)`. diff --git a/skills/update-agent/SKILL.zh-CN.md b/skills/update-agent/SKILL.zh-CN.md index 89a18bb..57a60a4 100644 --- a/skills/update-agent/SKILL.zh-CN.md +++ b/skills/update-agent/SKILL.zh-CN.md @@ -24,19 +24,24 @@ update-agent 是一个**元技能（Meta-Skill）**，允许用户通过对话 - **安全可控**：所有变更需用户确认，支持回滚 - **透明可见**：变更以 diff 形式展示，清晰明了 - **版本管理**：通过 Git 管理版本，可追溯历史 +- **校验兜底**：结构化字段（name/description/llm/persona/principles）经 ManageAgent 内置工具的白名单 + schema 校验，非法配置不会落盘 ## L2：详细规范 ### 支持的更新类型 -| 更新类型 | 目标文件 | 风险等级 | 示例 | -| --------------- | --------------- | -------- | -------------------- | -| Persona 更新 | `persona.md` | 中 | 修改沟通风格、价值观 | -| Principles 更新 | `principles.md` | 高 | 添加/修改行为规则 | -| Skills 安装 | `skills/` | 中 | 添加新技能包 | -| Skills 卸载 | `skills/` | 低 | 移除技能包 | -| Memory 更新 | `memory/` | 低 | 添加知识条目 | -| Tools 配置 | `tools/` | 高 | 修改工具权限 | +| 更新类型 | 目标 | 更新手段 | 风险等级 | 示例 | +| --------------- | --------------- | ------------------- | -------- | -------------------- | +| 名称/描述 | `agent.json` | ManageAgent update | 低/中 | 改名、改简介 | +| LLM 配置 | `agent.json`（llm） | ManageAgent update | 中 | 换模型、调温度 | +| Persona 更新 | `persona.md` | ManageAgent update | 中 | 修改沟通风格、价值观 | +| Principles 更新 | `principles.md` | ManageAgent update | 高 | 添加/修改行为规则 | +| Skills 安装 | `skills/` | Read/Write | 中 | 添加新技能包 | +| Skills 卸载 | `skills/` | Read/Write | 低 | 移除技能包 | +| Memory 更新 | `memory/` | Read/Write | 低 | 添加知识条目 | +| Tools 配置 | `tools/` | Read/Write | 高 | 修改工具权限 | + +**两条更新路径**：结构化字段（name/description/llm/persona/principles）一律经进程内内置工具 **ManageAgent** 的 `update` 动作更新（白名单 + schema 校验 + 合并语义）；记忆、技能、工具等自由格式文件仍用 Read/Write 直接编辑。详见「阶段 5：变更应用」。 ### 对话流程 @@ -138,17 +143,70 @@ diff_metadata: ### 阶段 5：变更应用 -通过 AgentFS 直接读写文件完成变更。**不要调用 HTTP API，不要直接操作 Git**（版本管理由后端自动处理）。 +变更应用分两条路径，取决于目标是**结构化字段**还是**自由格式文件**。**不要调用 HTTP API**（实例鉴权后 Agent 无法访问本机 HTTP API），**不要直接操作 Git**（版本管理由后端自动处理）。 -> **修改智能体显示名称 → 必须用 Edit 工具同时改两个文件保持一致。** 若用户要改 Agent 的**显示名称**（如"把 X 改名为 Y"），用 Edit 工具**同时**更新两处：①`agent.json` 的 `name` 字段；②`persona.md` 的首行标题（`# 名称`）。只改其中一个会导致显示名与人格文档标题脱节。**绝不要在没有实际编辑文件的情况下声称已改名**——不真正编辑文件则磁盘不变、智能体列表也不会刷新。 +#### 路径 A：结构化字段 → ManageAgent 内置工具（强制） + +以下字段**必须**通过进程内内置工具 `ManageAgent` 的 `update` 动作更新，**禁止**直接 Write `agent.json` / `persona.md` / `principles.md`： + +| 字段 | 约束 | 落地位置 | +| ------------- | -------------------------------------- | ----------------- | +| `name` | 1–50 字符 | `agent.json` | +| `description` | ≤200 字符 | `agent.json` | +| `config.llm` | 增量浅合并；**config 只允许 `llm`** | `agent.json` | +| `persona` | 结构化对象 `{L0, L1:{...}, L2}` 或 markdown 字符串 | `persona.md` | +| `principles` | 结构化对象 `{L0, L1:{...}, L2}` 或 markdown 字符串 | `principles.md` | + +**调用形式**： + +``` +ManageAgent(action='update', id='', name='新名称') +ManageAgent(action='update', id='', description='一句话简介') +ManageAgent(action='update', id='', config={ llm: { model: 'xxx', temperature: 0.7 } }) +ManageAgent(action='update', id='', persona={ L1: { personality: '专业、严谨' } }) +ManageAgent(action='update', id='', principles='...（完整 markdown）...') +``` + +**合并语义（重要）**： + +- 结构化 `persona` / `principles` 是**字段级合并**：省略的字段保留原值（如只传 `L1.personality` 不会清掉 L0 / role） +- markdown 字符串是**整体替换**（用于整篇重写） +- `config.llm` 是**增量浅合并**：只覆盖你传入的 key +- 合并后的 `agent.json` 会整体过 schema 校验，非法配置不落盘 + +**确认行为**： + +- 更新**自身**免二次确认 +- 更新**其他智能体**会触发用户确认（与本技能的 diff 确认叠加） +- 核心智能体（`desirecore` / `core`）拒绝更新 + +**改前先读**：改之前先用 `ManageAgent(action='get', id='')` 读取现值，用于生成 diff、校对字段名（persona / principles 的实际字段名以 `get` 返回的结构为准）。 + +**config 白名单**：`config` 仅接受 `llm`。传入 `mcp_servers` / `tool_permissions` / `version` / `id` 等会被拒绝并指明字段名——`llm` 以外的运行时配置不走 ManageAgent，见「阶段 5 · 路径 B」与错误处理。 + +**部分写入失败**：工具会精确报告"哪些字段已生效、哪个失败"，重试时**只提交失败字段**，不要整体重发。 + +> **改名一次调用完成。** 用户要改**显示名称**（如"把 X 改名为 Y"）时，直接 `ManageAgent(action='update', id='', name='Y')` 即可——`name` 写入 `agent.json` 并触发智能体列表刷新，无需再手动编辑任何文件。若用户希望人格文档标题也同步，可在同一轮追加一次 `persona` 更新。**绝不要在没有实际调用 ManageAgent 的情况下声称已改名。** + +#### 路径 B：自由格式文件 → Read/Write 直接编辑 + +记忆、技能、工具等**自由格式文件**不在 ManageAgent 范围，仍用 Read/Write 工具直接编辑： + +| 目标 | AgentFS 路径 | +| -------- | ------------ | +| 记忆条目 | `memory/` | +| 技能包 | `skills/` | +| 工具配置 | `tools/` | **AgentFS 根目录**：`${DESIRECORE_ROOT}/agents//` -**读取文件**：使用 `cat` 命令读取目标文件当前内容。 +**读取文件**：使用 Read 工具读取目标文件当前内容。 -**写入文件**：使用文本编辑工具直接写入目标文件。写入后重新读取文件确认内容正确。 +**写入文件**：使用 Write / Edit 工具直接写入目标文件。写入后重新读取文件确认内容正确。 -**注意**：直接写入文件后，后端文件监控会自动检测变更并触发 Git 提交，无需手动执行 git 命令。 +**受保护路径**：编辑前对照 `_protected-paths.yaml`，触及受保护路径应阻断并提示需 owner 权限。 + +**注意**：直接写入自由格式文件后，后端文件监控会自动检测变更并触发 Git 提交，无需手动执行 git 命令。 ### 阶段 6：回执生成 @@ -168,9 +226,13 @@ diff_metadata: 1. 在 Agent 目录下执行 `git log --oneline -10` 查看最近的版本历史 2. 使用 `git show :` 获取目标版本的文件内容，展示给用户确认 -3. 用户确认后，将目标版本内容写入对应文件 +3. 用户确认后，按目标文件类型应用： + - **结构化字段**（`persona.md` / `principles.md` / `agent.json` 的 name/description/llm）→ 用 `ManageAgent(action='update', ...)` 写回（persona / principles 以 markdown 字符串**整体替换**为该历史内容） + - **自由格式文件**（`memory/` / `skills/`）→ 用 Write 工具直接写回 4. 展示变更 diff，确认回滚成功 +（`git log` / `git show` 仅用于**读取**历史，回写一律走上述两条路径，不要用 git 命令直接改写工作区文件。） + ```bash # 查看版本历史 cd ${DESIRECORE_ROOT}/agents/ @@ -186,24 +248,31 @@ git show :persona.md **更新操作对照表**： -| 用户意图 | 目标文件 | AgentFS 路径 | -| -------------- | --------------- | ---------------------------------------------- | -| **改名（显示名称）** | `agent.json` **+** `persona.md` | 用 Edit 同时改：`agent.json` 的 name 字段 + `persona.md` 首行 `# 标题` | -| 修改性格/风格 | `persona.md` | `${DESIRECORE_ROOT}/agents//persona.md` | -| 修改行为规则 | `principles.md` | `${DESIRECORE_ROOT}/agents//principles.md` | -| 安装/卸载技能 | `skills/` | `${DESIRECORE_ROOT}/agents//skills/` | -| 修改工具配置 | `tools/` | `${DESIRECORE_ROOT}/agents//tools/` | -| 添加记忆 | `memory/` | `${DESIRECORE_ROOT}/agents//memory/` | -| 修改运行时配置 | `agent.json` | `${DESIRECORE_ROOT}/agents//agent.json` | +| 用户意图 | 更新手段 | +| --------------------- | ------------------------------------------------------------------------ | +| **改名（显示名称）** | `ManageAgent(action='update', id, name='...')` | +| 改简介 | `ManageAgent(action='update', id, description='...')` | +| 修改 LLM 配置（模型/温度等） | `ManageAgent(action='update', id, config={ llm: {...} })` | +| 修改性格/风格 | `ManageAgent(action='update', id, persona={...} 或 markdown)` | +| 修改行为规则 | `ManageAgent(action='update', id, principles={...} 或 markdown)` | +| 安装/卸载技能 | Read/Write `skills/`（`${DESIRECORE_ROOT}/agents//skills/`） | +| 添加记忆 | Read/Write `memory/`（`${DESIRECORE_ROOT}/agents//memory/`） | +| 修改工具配置 | Read/Write `tools/`（`${DESIRECORE_ROOT}/agents//tools/`，注意受保护路径） | + +> `agent.json` 中 `llm` 以外的运行时配置（`mcp_servers` / `tool_permissions` 等）当前不在 ManageAgent 白名单，也不应直接 Write `agent.json` 绕过校验。遇到此类需求，向用户说明暂需通过对应机制处理。 ### 错误处理 -| 错误场景 | 处理方式 | -| ------------------ | -------------------------------------- | -| 尝试修改受保护路径 | 阻断操作，提示需要 owner 权限 | -| 文件不存在 | Agent 或目标文件不存在，提示用户检查 | -| 权限不足 | 文件系统权限错误，提示用户检查目录权限 | -| 回滚版本不存在 | 列出可用版本，请用户重新选择 | +| 错误场景 | 处理方式 | +| ---------------------------- | ---------------------------------------------------------- | +| `config` 含非白名单字段 | ManageAgent 拒绝并指明字段名；改走对应机制或告知用户暂不支持 | +| schema 校验失败 | 非法配置不落盘；按工具返回修正字段后重试 | +| 更新核心智能体（desirecore/core） | ManageAgent 拒绝更新；告知用户核心智能体不可修改 | +| 部分字段写入失败 | 工具报告已生效/失败字段；仅重试失败字段，不整体重发 | +| 尝试修改受保护路径（自由文件） | 阻断操作，提示需要 owner 权限 | +| 文件不存在 | Agent 或目标文件不存在，提示用户检查 | +| 权限不足 | 文件系统权限错误，提示用户检查目录权限 | +| 回滚版本不存在 | 列出可用版本，请用户重新选择 | ### 权限要求 @@ -226,28 +295,26 @@ git show :persona.md **操作流程**： -```bash -# 1. 读取当前 persona.md -cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md +``` +# 1. 读取当前 persona，定位要改的字段（字段名以返回结构为准） +ManageAgent(action='get', id='legal-assistant') -# 输出示例: -# # 法律顾问小助手 -# ## L0 -# 专业的法律咨询助手 -# ## L1 -# ### Role -# 法律顾问 -# ### Personality -# 友好、随和 -# ### Communication Style -# 轻松幽默 +# 返回示例（persona 部分）: +# L0: 专业的法律咨询助手 +# L1: +# role: 法律顾问 +# personality: 友好、随和 +# communicationStyle: 轻松幽默 # 2. 分析需要修改的部分，生成 diff 展示给用户确认 -# 3. 用户确认后，直接编辑文件，将 Personality 和 Communication Style 修改为目标值 +# 3. 用户确认后，用 ManageAgent 字段级合并更新（只改这两个字段，L0/role 保留） +ManageAgent(action='update', id='legal-assistant', persona={ + L1: { personality: '专业、严谨', communicationStyle: '正式、克制' } +}) -# 4. 验证写入结果 -cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md +# 4. 复核结果 +ManageAgent(action='get', id='legal-assistant') ``` --- @@ -273,6 +340,14 @@ cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md ... ``` +**用户确认后应用**：先 `ManageAgent(action='get', id)` 取当前 principles，把整篇内容（含新增规则）以 markdown 字符串整体替换： + +``` +ManageAgent(action='update', id='legal-assistant', principles='...（整篇 markdown，含新增规则）...') +``` + +（若只改结构化对象的某个字段，也可用字段级合并传 `principles={ L1: { must: [...] } }`——字段名与结构以 `get` 返回为准。） + ### 修改现有规则 **用户输入**："不要每次都提醒我，太啰嗦了" @@ -287,3 +362,5 @@ cat ${DESIRECORE_ROOT}/agents/legal-assistant/persona.md - - 每次回答后都提醒用户检查内容 + - 仅在重要决策时提醒用户检查内容 ``` + +**用户确认后应用**：同上，用 `ManageAgent(action='update', id, principles=...)` 写回修改后的内容。