Yige
74be106952
## 摘要 / Summary ### 中文 #56 的复盘修正。上一轮"强改写压缩"把四技能 L1 的**技术属性、使用场景与交互示范当套话一刀切**，造成实质信息丢失（承诺"意图全保留"但未做到）。本 PR 补回： - **create**：`创建仓库符合 AgentFS v2 规范、git 管理版本（可治理/可追溯）`定位；`基础创建`形态（name+description，description 自动填充 persona L0）；需求收集的**引导问题示例**（"起什么名字？/主要负责什么？"…）；企业部署/开发者原型使用场景。 - **update**：`agent 目录 git 管理版本、历史可追溯`定位 + 使用场景。 - **discover**：使用场景（浏览/新用户/找替代）+ `语义匹配而非关键词搜索`。 - **delete**：使用场景（清理/测试/释放存储）。 根因：L1 混着实质技术属性与营销套话、使用场景是触发判据、引导问题是交互示范，不该按"只留独有信息"一刀切。补回后仍保留结构性压缩（zh 正文合计仍降 ~64%）。版本 create 2.5.2 / update 3.1.3 / delete 2.5.2 / discover 2.6.2，manifest 1.2.13，中英双份同步、重算 source_hash（validate-i18n 通过）。 ### English Post-mortem fix for #56. The previous aggressive compression treated the skills' L1 technical attributes, use cases, and interaction demos as boilerplate and cut them in a blanket way, dropping substantive information (the "all intent preserved" claim wasn't fully met). This PR restores: create's AgentFS-v2 / git-version-management positioning, the "basic create" form (name+description auto-filling persona L0), the requirement-gathering prompt questions, and enterprise/developer use cases; update's git-versioned/traceable positioning and use cases; discover's use cases and "semantic match, not keyword search"; delete's use cases. Root cause: L1 mixed real technical attributes with marketing boilerplate, use cases are trigger cues, and prompt questions are interaction demos — none should have been blanket-cut. Structural compression is retained (zh bodies still ~64% smaller). Versions bumped, manifest 1.2.13, both locales synced, source hashes recomputed (validate-i18n passes).
9.8 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.3 | 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. Use it to adjust communication style, add/change behavior rules, install/uninstall skills, or batch-upgrade config. The agent directory is version-managed by git with a traceable history, so rollback is supported. Its value is what the tool can't give: diff preview confirmation, two-path orchestration, version 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.