market/skills/update-agent/SKILL.zh-CN.md

update-agent 技能

L0：一句话摘要

通过自然语言对话，安全地修改 Agent 的配置、人格、规则和技能。

L1：概述

元技能：识别修改意图 → 生成可审阅 diff → 用户确认 → 应用（结构化字段走 ManageAgent、自由文件走 Read/Write）→ 回执。用于调整沟通风格、增改行为规则、安装/卸载技能、批量升级配置等。agent 目录由 git 管理版本、历史可追溯，支持回滚。价值在工具给不了的部分：diff 预览确认、两路径编排、版本回滚；结构化字段经 ManageAgent 白名单 + schema 校验，非法配置不落盘。

L2：详细规范

更新类型与两条路径

结构化字段一律经 ManageAgent(action='update')（白名单 + 校验 + 合并语义）；记忆/技能/工具等自由格式文件用 Read/Write 直接编辑：

用户意图	手段	目标（风险）
改名（显示名称）	ManageAgent(update, name=...)	agent.json（中）
改简介	ManageAgent(update, description=...)	agent.json（低）
默认推理与重试配置	ManageAgent(update, config={llm:{...}})	agent.json（中）
声明头像	ManageAgent(update, config={avatar:{...}})	agent.json（低）
图片头像	ManageAgent(update, avatarImage={...})	avatar（中）
性格/风格	ManageAgent(update, persona=... 或 markdown)	persona.md（中）
行为规则	ManageAgent(update, principles=... 或 markdown)	principles.md（高）
安装/卸载技能	Read/Write	skills/（低/中）
添加记忆	Read/Write	memory/（低）
修改工具配置	Read/Write	tools/（高，注意受保护路径）

流程：意图识别 → 变更分析 → diff 生成 → 用户确认 → 应用 → 回执。

阶段 1：意图识别

触发（任一）：用户说"修改/更新/调整你的…"、"你以后要…/记住这个规则…"、"安装/卸载这个技能…"，或描述对当前行为的不满并期望改变。识别更新类型与目标范围。

阶段 2：变更分析

评估影响范围（哪些文件/行为）、依赖与冲突，并定风险等级 → 对应确认强度：

• 低（记忆条目等非核心）：简单确认
• 中（persona / 普通 principles）：展示 diff 后确认
• 高（核心 principles / 工具权限）：详细说明 + diff + 确认
• 受保护（触及受保护路径）：阻断，需 owner 权限

阶段 3：diff 生成

生成变更前后 diff 展示给用户（只展示实际改动），例如：

# persona.md → ## 沟通风格
- 友好、随和、轻松幽默
+ 专业、严谨、适度幽默

阶段 4：用户确认

展示 diff 预览（影响文件、风险等级、影响说明 + diff），请用户确认「应用 / 取消 / 修改」；选"修改"进入微调后再确认。（工具层对更新他人/核心体另有强制确认，见阶段 5。）

阶段 5：变更应用

不要调 HTTP API（实例鉴权后不可达），不要直接操作 git（后端自动提交）。按目标分两路：

路径 A · 结构化字段 → ManageAgent（强制；禁止直接 Write agent.json / persona.md / principles.md）

字段与约束：name（1–50 字符）、description（≤200）、config.llm / config.avatar（增量浅合并）、avatarImage、smartRouting、persona / principles（结构化对象 {L0, L1:{...}, L2} 或 markdown 字符串）。调用：

ManageAgent(action='update', id='<agent-id>', name='新名称')
ManageAgent(action='update', id='<agent-id>', persona={ L1: { personality: ["专业","严谨"] } })
ManageAgent(action='update', id='<agent-id>', principles='…完整 markdown…')
ManageAgent(action='update', id='<agent-id>', config={ llm: { reasoning: "high" } })
ManageAgent(action='update', id='<agent-id>', avatarImage={ source: "dc-media://<mediaId>" })

合并语义：结构化 persona/principles 为字段级合并（省略字段保留原值，如只传 L1.personality 不会清掉 L0/role）；markdown 字符串为整体替换（整篇重写）；config.llm 为增量浅合并。合并结果整体过 schema 校验，非法配置不落盘。

要点：

• 改前先读：先 ManageAgent(action='get', id) 取现值，用于生成 diff、校对字段名。结构化字段名固定：persona 的 L1.role / personality（字符串数组）/ communication_style，principles 的 L1.must_do / must_not（字符串数组）/ priority，加顶层 L0 / L2。
• 确认与边界：更新自身免二次确认；更新其他智能体触发用户确认（与本技能 diff 确认叠加）；核心智能体（desirecore / core）拒绝更新。
• config 白名单：config 只接受 llm 与 avatar。config.llm 当前开放 reasoning、thinkingBudgets、maxRetryDelayMs；config.avatar 只开放 char 与 color。mcp_servers / tool_permissions / version / id 等会被拒并指明字段名。
• 模型治理：具体 model、provider、providerId 与 Smart/fixed 模式只由人类模型选择器管理，不能通过 ManageAgent 修改。Smart Agent 的量级、能力与推理意图用 smartRouting 更新。
• 推理档位：用户说“最深/最高/拉满”通常对应 xhigh；只有明确点名 max 且模型支持时才用 max。auto 是显式值；用户要求恢复全局默认时传 config.llm.reasoning=null 清除字段。
• 头像：字符与色系走 config.avatar；图片走 avatarImage.source，接受本轮媒体 ID 或工作目录内 PNG/JPEG/WebP，不接受 URL/base64。avatarImage.remove=true 删除图片头像并回落到字符头像。
• 部分写入失败：工具精确报告已生效/失败字段，仅重试失败字段，不整体重发。
• 改名一次调用完成：用户要改显示名称时直接 ManageAgent(action='update', id, name='Y')（写 agent.json 并刷新列表），如需人格文档标题同步可同轮追加 persona 更新。绝不在未实际调用 ManageAgent 时声称已改名。

路径 B · 自由格式文件 → Read/Write（memory/ / skills/ / tools/，根 ${DESIRECORE_ROOT}/agents/<agentId>/）：先 Read 现值，再 Write/Edit，写后重读确认。编辑前对照 _protected-paths.yaml，触及受保护路径应阻断并提示需 owner 权限。写入后后端文件监控自动 git 提交，无需手动 git。

阶段 6：回执

以用户友好方式呈现变更摘要（不暴露内部路径/技术细节），并告知可随时说"撤销刚才的修改"回滚。

版本回滚

触发：用户说"撤销/回滚/恢复原来的设置"。流程：

1. Agent 目录下 git log --oneline -10 看历史、git show <commit>:<file> 取目标版本内容，展示给用户确认。
2. 确认后按类型回写：结构化字段（persona/principles、agent.json 的 name/description/llm）→ ManageAgent(action='update', ...)（persona/principles 以 markdown 字符串整体替换为历史内容）；自由文件（memory/skills）→ Write 直接写回。
3. 展示 diff 确认回滚成功。

（git 仅用于读历史，回写一律走上述两路径，不要用 git 命令直接改工作区文件。）

背景与错误处理

• AgentFS 结构、受保护路径详见 _agentfs-background.md 与 _protected-paths.yaml。
• 工具报错时：config 非白名单字段 / schema 校验失败 / 核心体拒绝 → 按工具提示修正或告知用户；受保护路径 → 阻断并提示需 owner；回滚版本不存在 → 列出可用版本请用户重选。