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.
6.3 KiB
update-agent 技能
L0：一句话摘要
通过自然语言对话，安全地修改 Agent 的配置、人格、规则和技能。
L1：概述
元技能：识别修改意图 → 生成可审阅 diff → 用户确认 → 应用（结构化字段走 ManageAgent、自由文件走 Read/Write）→ 回执，并支持版本回滚。价值在工具给不了的部分：diff 预览确认、两路径编排、回滚；结构化字段经 ManageAgent 白名单 + schema 校验，非法配置不落盘。
L2：详细规范
更新类型与两条路径
结构化字段一律经 ManageAgent(action='update')（白名单 + 校验 + 合并语义）；记忆/技能/工具等自由格式文件用 Read/Write 直接编辑：
| 用户意图 | 手段 | 目标（风险） |
|---|---|---|
| 改名（显示名称） | ManageAgent(update, name=...) |
agent.json（中） |
| 改简介 | ManageAgent(update, description=...) |
agent.json（低） |
| LLM 配置（模型/温度） | ManageAgent(update, config={llm:{...}}) |
agent.json（中） |
| 性格/风格 | 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 仅允许 llm）、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…')
合并语义：结构化 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；mcp_servers/tool_permissions/version/id等会被拒并指明字段名——这类运行时配置不走 ManageAgent，向用户说明暂需经对应机制处理。 - 部分写入失败：工具精确报告已生效/失败字段，仅重试失败字段，不整体重发。
- 改名一次调用完成：用户要改显示名称时直接
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：回执
以用户友好方式呈现变更摘要（不暴露内部路径/技术细节），并告知可随时说"撤销刚才的修改"回滚。
版本回滚
触发：用户说"撤销/回滚/恢复原来的设置"。流程：
- Agent 目录下
git log --oneline -10看历史、git show <commit>:<file>取目标版本内容，展示给用户确认。 - 确认后按类型回写：结构化字段（persona/principles、agent.json 的 name/description/llm）→
ManageAgent(action='update', ...)（persona/principles 以 markdown 字符串整体替换为历史内容）；自由文件（memory/skills）→ Write 直接写回。 - 展示 diff 确认回滚成功。
（git 仅用于读历史，回写一律走上述两路径，不要用 git 命令直接改工作区文件。）
背景与错误处理
- AgentFS 结构、受保护路径详见
_agentfs-background.md与_protected-paths.yaml。 - 工具报错时：config 非白名单字段 / schema 校验失败 / 核心体拒绝 → 按工具提示修正或告知用户；受保护路径 → 阻断并提示需 owner；回滚版本不存在 → 列出可用版本请用户重选。