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).
6.5 KiB
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（低） |
| 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；回滚版本不存在 → 列出可用版本请用户重选。