feat(skills): 独立维护智能体生命周期操作说明 (#90)

## 中文

### 变更
- 新增 `clone-agent` 内置 Skill，覆盖私有数据复制和团队分发边界
- 将 Smart routing、reasoning、头像和确认流程迁入 action-specific Skills
- 修正 `update-agent` 与当前 ManageAgent 白名单的漂移
- 保持所有市场 Skill 按需加载，并加入 builtin 清单

### 验证
- `uv run --quiet scripts/i18n/test_validate_i18n.py`
- `uv run --quiet scripts/i18n/validate-i18n.py`
- `uv run --quiet scripts/i18n/translate.py --check`
- 公共信息边界检查通过

## English

### Changes
- Add the built-in `clone-agent` Skill for private-data copy and
team-distribution boundaries
- Move Smart routing, reasoning, avatar, and confirmation workflows into
action-specific Skills
- Align `update-agent` with the current ManageAgent configuration
whitelist
- Keep every marketplace Skill on-demand and add the new Skill to the
built-in manifest

### Verification
- `uv run --quiet scripts/i18n/test_validate_i18n.py`
- `uv run --quiet scripts/i18n/validate-i18n.py`
- `uv run --quiet scripts/i18n/translate.py --check`
- Public information boundary review passed

skills/update-agent/SKILL.md

@@ -3,7 +3,7 @@ name: update-agent
 description: >-
   安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent
   行为、安装/卸载技能、调整配置、回滚变更或修订规则。
-version: 3.1.3
+version: 3.2.0
 type: meta
 risk_level: low
 status: enabled
@@ -14,7 +14,7 @@ tags:
   - meta
 metadata:
   author: desirecore
-  updated_at: '2026-07-19'
+  updated_at: '2026-08-25'
   i18n:
     default_locale: en-US
     source_locale: zh-CN
@@ -27,7 +27,7 @@ metadata:
       description: >-
         安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent 行为、安装/卸载技能、调整配置、回滚变更或修订规则。
       body: ./SKILL.zh-CN.md
-      source_hash: sha256:d33f63306685168e
+      source_hash: sha256:6ba1c3ba7a6dd36e
       translated_by: human
     en-US:
       name: Update Agent
@@ -35,9 +35,8 @@ metadata:
       description: >-
         Safely update an existing Agent's config, persona, principles, skills, and memory, producing reviewable diffs that are applied and committed only after confirmation. Use when the user asks to modify Agent behavior, install/uninstall skills, adjust config, roll back changes, or revise rules.
       body: ./SKILL.md
-      source_hash: sha256:d33f63306685168e
-      translated_by: ai:claude-fable-5
-      translated_at: '2026-07-19'
+      source_hash: sha256:6ba1c3ba7a6dd36e
+      translated_by: human
 market:
   icon: >-
     <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
@@ -81,7 +80,9 @@ Structured fields always go through `ManageAgent(action='update')` (whitelist +
 | --- | --- | --- |
 | 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) |
+| Default reasoning/retry config | `ManageAgent(update, config={llm:{...}})` | agent.json (med) |
+| Declarative avatar | `ManageAgent(update, config={avatar:{...}})` | agent.json (low) |
+| Image avatar | `ManageAgent(update, avatarImage={...})` | avatar (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) |
@@ -123,12 +124,14 @@ Do not call the HTTP API (unreachable under instance auth), do not operate git d
 
 **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:
+Fields and constraints: `name` (1–50 chars), `description` (≤200), `config.llm` / `config.avatar` (shallow-merge deltas), `avatarImage`, `smartRouting`, and `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…')
+ManageAgent(action='update', id='<agent-id>', config={ llm: { reasoning: "high" } })
+ManageAgent(action='update', id='<agent-id>', avatarImage={ source: "dc-media://<mediaId>" })
 ```
 
 **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.
@@ -137,7 +140,10 @@ 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's `L1.role` / `personality` (string array) / `communication_style`; principles' `L1.must_do` / `must_not` (string arrays) / `priority`; plus top-level `L0` / `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**: `config` accepts only `llm`; `mcp_servers` / `tool_permissions` / `version` / `id` etc. are rejected with the field named — such runtime config does not go through ManageAgent; tell the user it currently needs the corresponding mechanism.
+- **config whitelist**: `config` accepts only `llm` and `avatar`. `config.llm` currently exposes `reasoning`, `thinkingBudgets`, and `maxRetryDelayMs`; `config.avatar` exposes only `char` and `color`. `mcp_servers`, `tool_permissions`, `version`, `id`, and other fields are rejected with the field named.
+- **model governance**: concrete `model`, `provider`, `providerId`, and Smart/fixed selection are governed only by the human model selector and cannot be changed through ManageAgent. Adjust Smart workload, required capabilities, and reasoning intent through `smartRouting`.
+- **reasoning levels**: natural-language requests such as “deepest/highest/max it out” normally map to `xhigh`; use `max` only when explicitly requested and supported. `auto` is an explicit value; use `config.llm.reasoning=null` when the user wants to restore the global default.
+- **avatars**: character/color settings use `config.avatar`; image avatars use `avatarImage.source`, accepting a current-turn media ID or a PNG/JPEG/WebP file inside the working directory. URLs and base64 are rejected. `avatarImage.remove=true` removes the image and falls back to the declarative avatar.
 - **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.**
 

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

@@ -20,7 +20,9 @@
 | --- | --- | --- |
 | 改名（显示名称） | `ManageAgent(update, name=...)` | agent.json（中） |
 | 改简介 | `ManageAgent(update, description=...)` | agent.json（低） |
-| LLM 配置（模型/温度） | `ManageAgent(update, config={llm:{...}})` | 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/`（低/中） |
@@ -62,12 +64,14 @@
 
 **路径 A · 结构化字段 → ManageAgent（强制；禁止直接 Write `agent.json` / `persona.md` / `principles.md`）**
 
-字段与约束：`name`（1–50 字符）、`description`（≤200）、`config.llm`（增量浅合并，**config 仅允许 llm**）、`persona` / `principles`（结构化对象 `{L0, L1:{...}, L2}` 或 markdown 字符串）。调用：
+字段与约束：`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 校验，非法配置不落盘。
@@ -76,7 +80,10 @@ ManageAgent(action='update', id='<agent-id>', principles='…完整 markdown…'
 
 - **改前先读**：先 `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，向用户说明暂需经对应机制处理。
+- **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 时声称已改名。**