feat: skills i18n 改造（schemaVersion 1.1，零向后兼容） (#1)

* feat: skills i18n 改造 — schemaVersion 1.1，零向后兼容把 21 个 skills + 1 个 agent + manifest/categories 全量迁移到 schemaVersion 1.1 的 i18n 结构，配套 CI AI 翻译流水线（GitHub Models）与本地工具链。 ## 关键变更 ### 数据结构（破坏性，schemaVersion 1.0 → 1.1） - SKILL.md: 顶层 name 改为 ASCII slug（== 目录名，符合 agentskills.io 规范）；中文显示名/short_desc/description 全部迁入 metadata.i18n.<locale> - agents/<id>/agent.json: shortDesc/fullDesc/tags/persona.{role,traits} 迁入 i18n.<locale>；changelog[].changes 改为 { <locale>: string[] } 对象 - categories.json: 每个分类的 label/description 迁入 i18n.<locale>，顶层只剩 color/icon - manifest.json: 加 supportedLocales / defaultLocale；顶层 description 迁入 i18n.<locale> ### Body 文件结构 - 根 SKILL.md = frontmatter + default_locale (en-US) body - SKILL.<locale>.md = 各 locale 的 markdown body（首行  自校验） ### 工具链（scripts/i18n/） - glossary.json: zh→en 术语表 + do_not_translate 白名单 - schema/skill-frontmatter.schema.json: i18n frontmatter JSON Schema - validate-i18n.py: 8 条校验规则（name 合规 / locale 完整性 / hash 一致性等） - translate.py: GitHub Models / Anthropic 双 backend，sha256 增量翻译 - migrate.py: 一次性迁移脚本（旧格式 → i18n 结构） ### CI（.github/workflows/） - i18n-validate.yml: PR 触发跑 validate + translate --check - i18n-translate.yml: PR 触发用 GitHub Models（默认 openai/gpt-5-mini）翻译缺失 locale，自动追加 commit；可切到 ANTHROPIC_API_KEY 走 Claude ### 文档 - docs/I18N.md: 作者贡献指南（schema 说明 / 提交流程 / 常见问题） - README.md: 加多语言段落 ## 验证 - uv run scripts/i18n/validate-i18n.py: OK，49 文件 0 错误 - uv run scripts/i18n/translate.py --check: 0 stale locale - 21 skills 标题数 zh-CN == en-US 严格对齐（最大 66=66） - skills-ref 规范校验：全部通过（顶层 name ASCII slug + description 单字段） Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(i18n): 修复 PR #1 review 反馈的 6 项问题 - schema: translated_by 正则放宽为 ^(human|ai:[A-Za-z0-9._:/-]+)$，接受 'ai:github:openai/gpt-5-mini' 这类 backend:model 形式（CI 翻译输出格式） - README + docs/I18N.md: 修正"CI 用 Claude API"误导描述，正确说明默认是 GitHub Models（openai/gpt-5-mini）+ GITHUB_TOKEN，可选切到 Anthropic - skills/minimax-tts/SKILL.md & SKILL.zh-CN.md: 删除多余的 ``` 闭合，避免 Markdown 后续渲染错乱 - skills/docx/SKILL.md: 翻译时丢失的 • Unicode escape 示例已恢复，与 zh-CN 版本对齐 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-06 08:10:48 +08:00 · 2026-05-05 00:26:33 +08:00
parent 1c107a9344
commit 1f7c8b9673
59 changed files with 10533 additions and 2014 deletions
--- a/skills/update-agent/SKILL.md
+++ b/skills/update-agent/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: 更新智能体
+name: update-agent
 description: >-
  安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent
  行为、安装/卸载技能、调整配置、回滚变更或修订规则。
@@ -15,6 +15,29 @@ tags:
 metadata:
  author: desirecore
  updated_at: '2026-03-17'
+  i18n:
+    default_locale: en-US
+    source_locale: zh-CN
+    locales:
+      - zh-CN
+      - en-US
+    zh-CN:
+      name: 更新智能体
+      short_desc: 安全更新智能体配置、人格、规则与技能，支持 diff 预览与版本回滚
+      description: >-
+        安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent 行为、安装/卸载技能、调整配置、回滚变更或修订规则。
+      body: ./SKILL.zh-CN.md
+      source_hash: sha256:a0fecd84f92204bd
+      translated_by: human
+    en-US:
+      name: Update Agent
+      short_desc: Safely update Agent config, persona, principles, and skills, with diff preview and version rollback
+      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:a0fecd84f92204bd
+      translated_by: ai:claude-opus-4-7
+      translated_at: '2026-05-03'
 market:
  icon: >-
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
@@ -29,7 +52,6 @@ market:
    16.53.92-.38m.01-2.3-.92-.38m1.5-1.24-.38-.92m0
    5.54-.38.92m2.3.01.38-.92m.3-4.84-.38-.92m1.24 1.5.92-.38m0 2.3.92.38"
    stroke="#AF52DE" stroke-width="1.3" stroke-linecap="round"/></svg>
-  short_desc: 安全更新智能体配置、人格、规则与技能，支持 diff 预览与版本回滚
  category: productivity
  maintainer:
    name: DesireCore Official
@@ -38,45 +60,45 @@ market:
  channel: latest
 ---

-# update-agent 技能
+# update-agent skill

-## L0：一句话摘要
+## L0: One-Sentence Summary

-通过自然语言对话，安全地修改 Agent 的配置、人格、规则和技能。
+Safely modify an Agent's config, persona, rules, and skills through natural-language conversation.

-## L1：概述与使用场景
+## L1: Overview and Use Cases

-### 能力描述
+### Capability Description

-update-agent 是一个**元技能（Meta-Skill）**，允许用户通过对话方式修改 Agent 的各项配置。所有修改都会生成可审阅的 diff 补丁，经用户确认后才会应用，并支持版本回滚。
+update-agent is a **Meta-Skill** that lets users modify various Agent configurations through conversation. All modifications produce reviewable diff patches that are applied only after user confirmation, with rollback support.

-### 使用场景
+### Use Cases

- 用户想要调整 Agent 的沟通风格（"说话再正式一点"）
- 需要添加新的行为规则（"以后遇到敏感话题要先提醒我"）
- 安装或卸载技能包（"学会写合同吧"）
- 批量更新多项配置（"全面升级一下你的能力"）
+- The user wants to adjust the Agent's communication style ("speak more formally")
+- Add new behavioral rules ("from now on, warn me before discussing sensitive topics")
+- Install or uninstall skill packages ("learn how to write contracts")
+- Batch-update multiple settings ("upgrade all your capabilities")

-### 核心价值
+### Core Value

- **安全可控**：所有变更需用户确认，支持回滚
- **透明可见**：变更以 diff 形式展示，清晰明了
- **版本管理**：通过 Git 管理版本，可追溯历史
+- **Safe and controllable**: All changes require user confirmation, with rollback support
+- **Transparent and visible**: Changes are presented as diffs, clear and obvious
+- **Version management**: Versions are managed via Git, with traceable history

-## L2：详细规范
+## L2: Detailed Specification

-### 支持的更新类型
+### Supported Update Types

-| 更新类型        | 目标文件        | 风险等级 | 示例                 |
-| --------------- | --------------- | -------- | -------------------- |
-| Persona 更新    | `persona.md`    | 中       | 修改沟通风格、价值观 |
-| Principles 更新 | `principles.md` | 高       | 添加/修改行为规则    |
-| Skills 安装     | `skills/`       | 中       | 添加新技能包         |
-| Skills 卸载     | `skills/`       | 低       | 移除技能包           |
-| Memory 更新     | `memory/`       | 低       | 添加知识条目         |
-| Tools 配置      | `tools/`        | 高       | 修改工具权限         |
+| Update Type        | Target File     | Risk Level | Example                                |
+| ------------------ | --------------- | ---------- | -------------------------------------- |
+| Persona update     | `persona.md`    | Medium     | Modify communication style, values     |
+| Principles update  | `principles.md` | High       | Add/modify behavioral rules            |
+| Skills install     | `skills/`       | Medium     | Add new skill package                  |
+| Skills uninstall   | `skills/`       | Low        | Remove skill package                   |
+| Memory update      | `memory/`       | Low        | Add knowledge entry                    |
+| Tools config       | `tools/`        | High       | Modify tool permissions                |

-### 对话流程
+### Conversation Flow

 ```
 ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
@@ -89,40 +111,40 @@ update-agent 是一个**元技能（Meta-Skill）**，允许用户通过对话
 └──────────────┘     └──────────────┘     └──────────────┘
 ```

-### 阶段 1：意图识别
+### Stage 1: Intent Recognition

-**触发条件**（任一满足）：
+**Trigger conditions** (any one is sufficient):

- 用户说"修改你的..."、"更新你的..."、"调整一下..."
- 用户说"你以后要..."、"记住这个规则..."
- 用户说"安装/卸载这个技能..."
- 用户描述对当前行为的不满并期望改变
+- The user says "modify your...", "update your...", "adjust the..."
+- The user says "from now on you should...", "remember this rule..."
+- The user says "install/uninstall this skill..."
+- The user describes dissatisfaction with current behavior and expects a change

-**输出**：识别更新类型和目标范围。
+**Output**: Identify the update type and target scope.

-### 阶段 2：变更分析
+### Stage 2: Change Analysis

-**分析维度**：
+**Analysis dimensions**:

-| 维度     | 说明                     |
-| -------- | ------------------------ |
-| 影响范围 | 影响哪些文件、哪些行为   |
-| 风险等级 | 低/中/高（见风险分级表） |
-| 依赖检查 | 是否影响其他配置         |
-| 冲突检测 | 是否与现有规则冲突       |
+| Dimension           | Description                                  |
+| ------------------- | -------------------------------------------- |
+| Scope of impact     | Which files and behaviors are affected       |
+| Risk level          | Low/Medium/High (see risk classification)    |
+| Dependency check    | Whether other configs are affected           |
+| Conflict detection  | Whether it conflicts with existing rules     |

-**风险分级表**：
+**Risk classification table**:

-| 风险等级 | 条件                           | 确认要求               |
-| -------- | ------------------------------ | ---------------------- |
-| 低       | 仅影响非核心配置（如记忆条目） | 简单确认               |
-| 中       | 影响 persona 或普通 principles | 展示 diff 后确认       |
-| 高       | 影响核心 principles 或工具权限 | 详细说明 + diff + 确认 |
-| 受保护   | 触及受保护路径                 | 阻断，需 owner 权限    |
+| Risk Level  | Conditions                                       | Confirmation Requirement              |
+| ----------- | ------------------------------------------------ | ------------------------------------- |
+| Low         | Affects only non-core config (e.g. memory entry) | Simple confirmation                   |
+| Medium      | Affects persona or normal principles             | Show diff, then confirm               |
+| High        | Affects core principles or tool permissions      | Detailed explanation + diff + confirm |
+| Protected   | Touches a protected path                         | Block; requires owner permission      |

-### 阶段 3：Diff 生成
+### Stage 3: Diff Generation

-**Diff 格式示例**：
+**Diff format example**:

 ```diff
 # persona.md
@@ -137,7 +159,7 @@ update-agent 是一个**元技能（Meta-Skill）**，允许用户通过对话
  保持不变...
 ```

-**Diff 元数据**：
+**Diff metadata**:

 ```yaml
 diff_metadata:
@@ -149,9 +171,9 @@ diff_metadata:
  estimated_impact: '沟通风格会变得更正式'
 ```

-### 阶段 4：用户确认
+### Stage 4: User Confirmation

-**确认界面**：
+**Confirmation interface**:

 ```
 变更预览
@@ -168,44 +190,44 @@ diff_metadata:
 [应用] [取消] [修改]
 ```

-**确认选项**：
+**Confirmation options**:

- **应用**：执行变更
- **取消**：放弃变更
- **修改**：进入编辑模式微调
+- **Apply**: Execute the change
+- **Cancel**: Discard the change
+- **Modify**: Enter edit mode for fine-tuning

-### 阶段 5：变更应用
+### Stage 5: Apply Changes

-通过 AgentFS 直接读写文件完成变更。**不要调用 HTTP API，不要直接操作 Git**（版本管理由后端自动处理）。
+Apply the change by reading and writing files directly through AgentFS. **Do not call HTTP APIs, and do not operate Git directly** (version management is handled automatically by the backend).

-**AgentFS 根目录**：`~/.desirecore/agents/<agentId>/`
+**AgentFS root directory**: `~/.desirecore/agents/<agentId>/`

-**读取文件**：使用 `cat` 命令读取目标文件当前内容。
+**Read file**: Use the `cat` command to read the current contents of the target file.

-**写入文件**：使用文本编辑工具直接写入目标文件。写入后重新读取文件确认内容正确。
+**Write file**: Use a text-editing tool to write directly to the target file. After writing, re-read the file to verify the contents are correct.

-**注意**：直接写入文件后，后端文件监控会自动检测变更并触发 Git 提交，无需手动执行 git 命令。
+**Note**: After writing the file directly, the backend file watcher automatically detects the change and triggers a Git commit; no manual git command is required.

-### 阶段 6：回执生成
+### Stage 6: Receipt Generation

-创建成功后，以用户友好的方式呈现回执（不要暴露内部路径或技术细节）：
+After a successful change, present a user-friendly receipt (do not expose internal paths or technical details):

-> 已更新「法律顾问小助手」的沟通风格。
+> Updated the communication style of "Legal Advisor Assistant".
 >
-> **变更摘要**：沟通风格从"友好随和"调整为"专业严谨"
+> **Change summary**: Communication style adjusted from "friendly and casual" to "professional and rigorous"
 >
-> 如果不满意，可以随时说"撤销刚才的修改"来回滚。
+> If you're not satisfied, you can say "undo the previous change" anytime to roll back.

-### 特殊操作：版本回滚
+### Special Operation: Version Rollback

-**触发条件**：用户说"撤销刚才的修改"、"回滚到之前的版本"、"恢复原来的设置"
+**Trigger conditions**: The user says "undo the previous change", "roll back to the previous version", "restore the original settings"

-**回滚流程**：
+**Rollback flow**:

-1. 在 Agent 目录下执行 `git log --oneline -10` 查看最近的版本历史
-2. 使用 `git show <commit>:<file>` 获取目标版本的文件内容，展示给用户确认
-3. 用户确认后，将目标版本内容写入对应文件
-4. 展示变更 diff，确认回滚成功
+1. Run `git log --oneline -10` in the Agent directory to view recent version history
+2. Use `git show <commit>:<file>` to fetch the file contents of the target version, and present them to the user for confirmation
+3. After user confirmation, write the target version's contents to the corresponding file
+4. Show the change diff and confirm rollback success

 ```bash
 # 查看版本历史
@@ -216,50 +238,50 @@ git log --oneline -10
 git show <commit>:persona.md
 ```

-### 背景知识
+### Background Knowledge

-> AgentFS 仓库结构与受保护路径详见 `_agentfs-background.md` 和 `_protected-paths.yaml`。
+> AgentFS repository structure and protected paths are detailed in `_agentfs-background.md` and `_protected-paths.yaml`.

-**更新操作对照表**：
+**Update operation reference table**:

-| 用户意图       | 目标文件        | AgentFS 路径                                   |
-| -------------- | --------------- | ---------------------------------------------- |
-| 修改性格/风格  | `persona.md`    | `~/.desirecore/agents/<agentId>/persona.md`    |
-| 修改行为规则   | `principles.md` | `~/.desirecore/agents/<agentId>/principles.md` |
-| 安装/卸载技能  | `skills/`       | `~/.desirecore/agents/<agentId>/skills/`       |
-| 修改工具配置   | `tools/`        | `~/.desirecore/agents/<agentId>/tools/`        |
-| 添加记忆       | `memory/`       | `~/.desirecore/agents/<agentId>/memory/`       |
-| 修改运行时配置 | `agent.json`    | `~/.desirecore/agents/<agentId>/agent.json`    |
+| User Intent                  | Target File     | AgentFS Path                                   |
+| ---------------------------- | --------------- | ---------------------------------------------- |
+| Modify personality/style     | `persona.md`    | `~/.desirecore/agents/<agentId>/persona.md`    |
+| Modify behavioral rules      | `principles.md` | `~/.desirecore/agents/<agentId>/principles.md` |
+| Install/uninstall skills     | `skills/`       | `~/.desirecore/agents/<agentId>/skills/`       |
+| Modify tools config          | `tools/`        | `~/.desirecore/agents/<agentId>/tools/`        |
+| Add memory                   | `memory/`       | `~/.desirecore/agents/<agentId>/memory/`       |
+| Modify runtime config        | `agent.json`    | `~/.desirecore/agents/<agentId>/agent.json`    |

-### 错误处理
+### Error Handling

-| 错误场景           | 处理方式                               |
-| ------------------ | -------------------------------------- |
-| 尝试修改受保护路径 | 阻断操作，提示需要 owner 权限          |
-| 文件不存在         | Agent 或目标文件不存在，提示用户检查   |
-| 权限不足           | 文件系统权限错误，提示用户检查目录权限 |
-| 回滚版本不存在     | 列出可用版本，请用户重新选择           |
+| Error Scenario                      | Handling                                                 |
+| ----------------------------------- | -------------------------------------------------------- |
+| Attempt to modify a protected path  | Block the operation; prompt that owner permission is required |
+| File does not exist                 | The Agent or target file does not exist; ask user to check |
+| Insufficient permission             | Filesystem permission error; ask user to check directory permissions |
+| Rollback target version not found   | List available versions and ask the user to reselect     |

-### 权限要求
+### Permission Requirements

-| 操作                        | 所需角色      |
-| --------------------------- | ------------- |
-| 更新 persona                | owner, member |
-| 更新 principles（普通规则） | owner, member |
-| 更新 principles（安全红线） | owner         |
-| 安装/卸载 skills            | owner, member |
-| 修改 tools 权限             | owner         |
-| 版本回滚                    | owner         |
+| Operation                              | Required Role  |
+| -------------------------------------- | -------------- |
+| Update persona                         | owner, member  |
+| Update principles (normal rules)       | owner, member  |
+| Update principles (safety red lines)   | owner          |
+| Install/uninstall skills               | owner, member  |
+| Modify tools permissions               | owner          |
+| Version rollback                       | owner          |

 ---

-## 附录：更新示例
+## Appendix: Update Examples

-### Persona 修改示例
+### Persona Modification Example

-**用户输入**："说话再正式一点，不要太随意"
+**User input**: "Speak a bit more formally, not too casual"

-**操作流程**：
+**Operation flow**:

 ```bash
 # 1. 读取当前 persona.md
@@ -287,13 +309,13 @@ cat ~/.desirecore/agents/legal-assistant/persona.md

 ---

-### Principles 更新示例
+### Principles Update Example

-### 添加新规则
+### Add New Rule

-**用户输入**："以后遇到法律问题，先提醒我找专业律师"
+**User input**: "From now on, when there's a legal issue, remind me to consult a professional lawyer"

-**生成的 Diff**：
+**Generated diff**:

 ```diff
 # principles.md
@@ -308,11 +330,11 @@ cat ~/.desirecore/agents/legal-assistant/persona.md
  ...
 ```

-### 修改现有规则
+### Modify Existing Rule

-**用户输入**："不要每次都提醒我，太啰嗦了"
+**User input**: "Don't remind me every time, it's too verbose"

-**生成的 Diff**：
+**Generated diff**:

 ```diff
 # principles.md
--- a/skills/update-agent/SKILL.zh-CN.md
+++ b/skills/update-agent/SKILL.zh-CN.md
@@ -0,0 +1,286 @@
+<!-- locale: zh-CN -->
+
+# update-agent 技能
+
+## L0：一句话摘要
+
+通过自然语言对话，安全地修改 Agent 的配置、人格、规则和技能。
+
+## L1：概述与使用场景
+
+### 能力描述
+
+update-agent 是一个**元技能（Meta-Skill）**，允许用户通过对话方式修改 Agent 的各项配置。所有修改都会生成可审阅的 diff 补丁，经用户确认后才会应用，并支持版本回滚。
+
+### 使用场景
+
+- 用户想要调整 Agent 的沟通风格（"说话再正式一点"）
+- 需要添加新的行为规则（"以后遇到敏感话题要先提醒我"）
+- 安装或卸载技能包（"学会写合同吧"）
+- 批量更新多项配置（"全面升级一下你的能力"）
+
+### 核心价值
+
+- **安全可控**：所有变更需用户确认，支持回滚
+- **透明可见**：变更以 diff 形式展示，清晰明了
+- **版本管理**：通过 Git 管理版本，可追溯历史
+
+## L2：详细规范
+
+### 支持的更新类型
+
+| 更新类型        | 目标文件        | 风险等级 | 示例                 |
+| --------------- | --------------- | -------- | -------------------- |
+| Persona 更新    | `persona.md`    | 中       | 修改沟通风格、价值观 |
+| Principles 更新 | `principles.md` | 高       | 添加/修改行为规则    |
+| Skills 安装     | `skills/`       | 中       | 添加新技能包         |
+| Skills 卸载     | `skills/`       | 低       | 移除技能包           |
+| Memory 更新     | `memory/`       | 低       | 添加知识条目         |
+| Tools 配置      | `tools/`        | 高       | 修改工具权限         |
+
+### 对话流程
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   意图识别    │ ──→ │   变更分析    │ ──→ │   Diff 生成   │
+└──────────────┘     └──────────────┘     └──────────────┘
+                                                  │
+                                                  ↓
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   回执生成    │ ←── │   变更应用    │ ←── │   用户确认    │
+└──────────────┘     └──────────────┘     └──────────────┘
+```
+
+### 阶段 1：意图识别
+
+**触发条件**（任一满足）：
+
+- 用户说"修改你的..."、"更新你的..."、"调整一下..."
+- 用户说"你以后要..."、"记住这个规则..."
+- 用户说"安装/卸载这个技能..."
+- 用户描述对当前行为的不满并期望改变
+
+**输出**：识别更新类型和目标范围。
+
+### 阶段 2：变更分析
+
+**分析维度**：
+
+| 维度     | 说明                     |
+| -------- | ------------------------ |
+| 影响范围 | 影响哪些文件、哪些行为   |
+| 风险等级 | 低/中/高（见风险分级表） |
+| 依赖检查 | 是否影响其他配置         |
+| 冲突检测 | 是否与现有规则冲突       |
+
+**风险分级表**：
+
+| 风险等级 | 条件                           | 确认要求               |
+| -------- | ------------------------------ | ---------------------- |
+| 低       | 仅影响非核心配置（如记忆条目） | 简单确认               |
+| 中       | 影响 persona 或普通 principles | 展示 diff 后确认       |
+| 高       | 影响核心 principles 或工具权限 | 详细说明 + diff + 确认 |
+| 受保护   | 触及受保护路径                 | 阻断，需 owner 权限    |
+
+### 阶段 3：Diff 生成
+
+**Diff 格式示例**：
+
+```diff
+# persona.md
+
+## 沟通风格
+
+- 友好、随和、轻松幽默
+ 专业、严谨、适度幽默
+
+## 决策偏好
+
+  保持不变...
+```
+
+**Diff 元数据**：
+
+```yaml
+diff_metadata:
+  files_affected: 1
+  lines_added: 1
+  lines_removed: 1
+  risk_level: medium
+  reversible: true
+  estimated_impact: '沟通风格会变得更正式'
+```
+
+### 阶段 4：用户确认
+
+**确认界面**：
+
+```
+变更预览
+
+影响文件: persona.md
+风险等级: 中
+影响说明: 沟通风格会从"友好随和"变为"专业严谨"
+
+--- 变更内容 ---
+[展示 diff]
+----------------
+
+请确认是否应用此变更？
+[应用] [取消] [修改]
+```
+
+**确认选项**：
+
+- **应用**：执行变更
+- **取消**：放弃变更
+- **修改**：进入编辑模式微调
+
+### 阶段 5：变更应用
+
+通过 AgentFS 直接读写文件完成变更。**不要调用 HTTP API，不要直接操作 Git**（版本管理由后端自动处理）。
+
+**AgentFS 根目录**：`~/.desirecore/agents/<agentId>/`
+
+**读取文件**：使用 `cat` 命令读取目标文件当前内容。
+
+**写入文件**：使用文本编辑工具直接写入目标文件。写入后重新读取文件确认内容正确。
+
+**注意**：直接写入文件后，后端文件监控会自动检测变更并触发 Git 提交，无需手动执行 git 命令。
+
+### 阶段 6：回执生成
+
+创建成功后，以用户友好的方式呈现回执（不要暴露内部路径或技术细节）：
+
+> 已更新「法律顾问小助手」的沟通风格。
+>
+> **变更摘要**：沟通风格从"友好随和"调整为"专业严谨"
+>
+> 如果不满意，可以随时说"撤销刚才的修改"来回滚。
+
+### 特殊操作：版本回滚
+
+**触发条件**：用户说"撤销刚才的修改"、"回滚到之前的版本"、"恢复原来的设置"
+
+**回滚流程**：
+
+1. 在 Agent 目录下执行 `git log --oneline -10` 查看最近的版本历史
+2. 使用 `git show <commit>:<file>` 获取目标版本的文件内容，展示给用户确认
+3. 用户确认后，将目标版本内容写入对应文件
+4. 展示变更 diff，确认回滚成功
+
+```bash
+# 查看版本历史
+cd ~/.desirecore/agents/<agentId>
+git log --oneline -10
+
+# 查看某个版本的文件内容
+git show <commit>:persona.md
+```
+
+### 背景知识
+
+> AgentFS 仓库结构与受保护路径详见 `_agentfs-background.md` 和 `_protected-paths.yaml`。
+
+**更新操作对照表**：
+
+| 用户意图       | 目标文件        | AgentFS 路径                                   |
+| -------------- | --------------- | ---------------------------------------------- |
+| 修改性格/风格  | `persona.md`    | `~/.desirecore/agents/<agentId>/persona.md`    |
+| 修改行为规则   | `principles.md` | `~/.desirecore/agents/<agentId>/principles.md` |
+| 安装/卸载技能  | `skills/`       | `~/.desirecore/agents/<agentId>/skills/`       |
+| 修改工具配置   | `tools/`        | `~/.desirecore/agents/<agentId>/tools/`        |
+| 添加记忆       | `memory/`       | `~/.desirecore/agents/<agentId>/memory/`       |
+| 修改运行时配置 | `agent.json`    | `~/.desirecore/agents/<agentId>/agent.json`    |
+
+### 错误处理
+
+| 错误场景           | 处理方式                               |
+| ------------------ | -------------------------------------- |
+| 尝试修改受保护路径 | 阻断操作，提示需要 owner 权限          |
+| 文件不存在         | Agent 或目标文件不存在，提示用户检查   |
+| 权限不足           | 文件系统权限错误，提示用户检查目录权限 |
+| 回滚版本不存在     | 列出可用版本，请用户重新选择           |
+
+### 权限要求
+
+| 操作                        | 所需角色      |
+| --------------------------- | ------------- |
+| 更新 persona                | owner, member |
+| 更新 principles（普通规则） | owner, member |
+| 更新 principles（安全红线） | owner         |
+| 安装/卸载 skills            | owner, member |
+| 修改 tools 权限             | owner         |
+| 版本回滚                    | owner         |
+
+---
+
+## 附录：更新示例
+
+### Persona 修改示例
+
+**用户输入**："说话再正式一点，不要太随意"
+
+**操作流程**：
+
+```bash
+# 1. 读取当前 persona.md
+cat ~/.desirecore/agents/legal-assistant/persona.md
+
+# 输出示例:
+# # 法律顾问小助手
+# ## L0
+# 专业的法律咨询助手
+# ## L1
+# ### Role
+# 法律顾问
+# ### Personality
+# 友好、随和
+# ### Communication Style
+# 轻松幽默
+
+# 2. 分析需要修改的部分，生成 diff 展示给用户确认
+
+# 3. 用户确认后，直接编辑文件，将 Personality 和 Communication Style 修改为目标值
+
+# 4. 验证写入结果
+cat ~/.desirecore/agents/legal-assistant/persona.md
+```
+
+---
+
+### Principles 更新示例
+
+### 添加新规则
+
+**用户输入**："以后遇到法律问题，先提醒我找专业律师"
+
+**生成的 Diff**：
+
+```diff
+# principles.md
+
+## 必须做
+
+  - 始终保持礼貌和尊重
+  - 不确定时主动询问
+ - 遇到法律相关问题时，提醒用户咨询专业律师
+
+## 绝不做
+  ...
+```
+
+### 修改现有规则
+
+**用户输入**："不要每次都提醒我，太啰嗦了"
+
+**生成的 Diff**：
+
+```diff
+# principles.md
+
+## 必须做
+
+- - 每次回答后都提醒用户检查内容
+ - 仅在重要决策时提醒用户检查内容
+```