Yige
d52e61e041
## 摘要 / Summary ### 中文 四个智能体管理技能（create/update/delete/discover-agent）改用 `ManageAgent` 内置工具后，正文与工具契约大量重叠——ManageAgent 的 description + params 已**常驻每次 query 的上下文**，声明了五个 action 语义、参数约束、权限硬边界、错误语义、字段级合并、确认行为、list/get 返回格式；技能正文里再复述即冗余。本次对四技能做**强改写·语境融合**压缩： - 与工具契约重复的说明（参数/权限/错误码/确认行为/成功返回话术）**改写融入对应流程步骤**（如错误处理表 → 阶段一句、确认行为 → 阶段一句），不再照抄、不再表格化。 - 装饰性 ASCII 流程框图 → 一行文字流程；update 内部两张重复更新表 → 合并；YAML 元数据块（diff_metadata/context_handoff）融入流程；冗长示例（create 三份 JSON、update 附录 4 示例、discover ASCII 卡片）就地精简为代表示意。 - **不外置 references、不净删除任何内容**：所有决策/领域/交互意图完整保留——领域匹配表、persona/principles 的 L0/L1/L2 生成规范、update 两路径分流与字段级合并 vs 整体替换、防幻觉改名、回滚流程、discover 需求维度与无匹配衔接 create 等核心一字未丢。 zh 正文合计 **26542 → 9196 字符（降 ~65%）**；中英双份同步改写、逐段对齐，重算 i18n source_hash（validate-i18n 通过）。版本 create 2.5.1 / update 3.1.2 / delete 2.5.1 / discover 2.6.1，manifest 1.2.12。 ### English After the four agent-management skills adopted the `ManageAgent` builtin tool, their bodies heavily duplicated the tool contract — ManageAgent's description + params are **resident in every query's context** (action semantics, param constraints, permission hard-boundaries, error semantics, field-level merge, confirmation behavior, list/get return formats). This PR compresses all four via **aggressive rewrite + contextual fusion**: contract-duplicating text is rewritten into the relevant flow steps (not copied, not tabularized), decorative ASCII flow boxes become one-line text, update's two duplicate tables are merged, YAML metadata blocks are folded in, and long examples are trimmed in place to representative sketches. **No references externalization, no net deletion** — every decision/domain/interaction intent is preserved (domain matching table, persona/principles L0/L1/L2 generation spec, update's two-path split and field-level-merge-vs-full-replace, anti-hallucination rename, rollback flow, discover's need dimensions and create hand-off). zh bodies total **26542 → 9196 chars (~65% down)**; both locales rewritten and aligned, i18n source hashes recomputed (validate-i18n passes). Versions bumped, manifest 1.2.12.
9.6 KiB
name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market
| name | description | version | type | risk_level | status | disable-model-invocation | tags | metadata | market | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| update-agent | 安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent 行为、安装/卸载技能、调整配置、回滚变更或修订规则。 | 3.1.2 | meta | low | enabled | true |
|
|
|
update-agent skill
L0: One-Sentence Summary
Safely modify an Agent's configuration, persona, rules, and skills through natural-language conversation.
L1: Overview
Meta-skill: recognize the edit intent → generate a reviewable diff → user confirmation → apply (structured fields via ManageAgent, free-form files via Read/Write) → receipt, with version rollback. Its value is what the tool can't give: diff preview confirmation, two-path orchestration, rollback; structured fields go through ManageAgent's whitelist + schema validation so invalid config never lands.
L2: Detailed Spec
Update Types and the Two Paths
Structured fields always go through ManageAgent(action='update') (whitelist + validation + merge semantics); free-form files (memory/skills/tools) are edited directly with Read/Write:
| User intent | Means | Target (risk) |
|---|---|---|
| Rename (display name) | ManageAgent(update, name=...) |
agent.json (med) |
| Change description | ManageAgent(update, description=...) |
agent.json (low) |
| LLM config (model/temperature) | ManageAgent(update, config={llm:{...}}) |
agent.json (med) |
| Personality/style | ManageAgent(update, persona=... or markdown) |
persona.md (med) |
| Behavior rules | ManageAgent(update, principles=... or markdown) |
principles.md (high) |
| Install/uninstall skill | Read/Write | skills/ (low/med) |
| Add memory | Read/Write | memory/ (low) |
| Change tool config | Read/Write | tools/ (high, watch protected paths) |
Flow: intent recognition → change analysis → diff generation → user confirmation → apply → receipt.
Stage 1: Intent Recognition
Trigger (any): user says "modify/update/adjust your …", "from now on you should… / remember this rule…", "install/uninstall this skill…", or describes dissatisfaction with current behavior and wants change. Identify the update type and target scope.
Stage 2: Change Analysis
Assess impact (which files/behaviors), dependencies, and conflicts, and set a risk level → matching confirmation strength:
- Low (non-core, e.g. memory entries): simple confirmation
- Medium (persona / ordinary principles): show diff, then confirm
- High (core principles / tool permissions): detailed explanation + diff + confirm
- Protected (touches a protected path): block, requires owner permission
Stage 3: Diff Generation
Generate a before/after diff for the user (show only the actual change), e.g.:
# persona.md → ## Communication style
- friendly, easygoing, light humor
+ professional, rigorous, measured humor
Stage 4: User Confirmation
Show the diff preview (affected file, risk level, impact note + diff) and ask the user to confirm "Apply / Cancel / Modify"; "Modify" enters fine-tuning then re-confirms. (The tool layer also enforces confirmation for updating other/core agents; see Stage 5.)
Stage 5: Apply Changes
Do not call the HTTP API (unreachable under instance auth), do not operate git directly (the backend auto-commits). Split by target into two paths:
Path A · Structured fields → ManageAgent (mandatory; never Write agent.json / persona.md / principles.md directly)
Fields and constraints: name (1–50 chars), description (≤200), config.llm (shallow-merge delta, config allows llm only), persona / principles (structured object {L0, L1:{...}, L2} or markdown string). Calls:
ManageAgent(action='update', id='<agent-id>', name='New Name')
ManageAgent(action='update', id='<agent-id>', persona={ L1: { personality: ["professional","rigorous"] } })
ManageAgent(action='update', id='<agent-id>', principles='…full markdown…')
Merge semantics: structured persona/principles are field-level merges (omitted fields keep their original values — passing only L1.personality won't clear L0/role); a markdown string is a full replacement (whole-file rewrite); config.llm is a shallow-merge delta. The merged result is validated against the whole schema; invalid config never lands.
Key points:
- Read before write: first
ManageAgent(action='get', id)to fetch current values, for diff generation and field-name checking. Structured field names are fixed: persona'sL1.role/personality(string array) /communication_style; principles'L1.must_do/must_not(string arrays) /priority; plus top-levelL0/L2. - Confirmation and boundaries: updating self skips the extra confirmation; updating another agent triggers user confirmation (on top of this skill's diff confirmation); the core agent (
desirecore/core) is refused. - config whitelist:
configaccepts onlyllm;mcp_servers/tool_permissions/version/idetc. are rejected with the field named — such runtime config does not go through ManageAgent; tell the user it currently needs the corresponding mechanism. - Partial write failure: the tool reports exactly which fields landed / which failed; retry only the failed fields, don't resend everything.
- Rename in one call: to change the display name, call
ManageAgent(action='update', id, name='Y')directly (writes agent.json and refreshes the list); if the persona doc title should match, append a persona update in the same turn. Never claim a rename happened without actually calling ManageAgent.
Path B · Free-form files → Read/Write (memory/ / skills/ / tools/, root ${DESIRECORE_ROOT}/agents/<agentId>/): Read current values, then Write/Edit, re-read after writing to confirm. Before editing, check _protected-paths.yaml; touching a protected path should be blocked with an owner-permission notice. After writing, the backend file watcher auto-commits — no manual git.
Stage 6: Receipt
Present the change summary in a user-friendly way (no internal paths / technical details), and note the user can say "undo the last change" to roll back anytime.
Version Rollback
Trigger: user says "undo / roll back / restore the previous settings". Flow:
- In the Agent directory,
git log --oneline -10for history andgit show <commit>:<file>for the target version content; show it to the user to confirm. - After confirmation, write back by type: structured fields (persona/principles, agent.json name/description/llm) →
ManageAgent(action='update', ...)(persona/principles as a markdown string, full replacement with the historical content); free-form files (memory/skills) → Write directly. - Show the diff to confirm the rollback.
(git is only for reading history; write-back always goes through the two paths above — never rewrite working-tree files with git commands.)
Background and Error Handling
- AgentFS structure and protected paths: see
_agentfs-background.mdand_protected-paths.yaml. - On tool errors: non-whitelisted config field / schema validation failure / core-agent refusal → fix per the tool's hint or inform the user; protected path → block with an owner-permission notice; rollback version not found → list available versions and ask the user to reselect.