mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-07-23 06:03:45 +08:00
perf(skills): 智能体 CRUD 四技能提示词改写压缩（功能不变，~65%） (#56)
## 摘要 / 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.
This commit is contained in:
GitHub
@@ -1,5 +1,9 @@
|
||||
# Changelog
|
||||
|
||||
## [3.1.2] - 2026-07-19
|
||||
|
||||
- 提示词改写压缩，功能不变——与 ManageAgent 工具契约重复的说明、装饰框图、重复表改写融入流程，示例就地精简；不外置、不净删，意图全保留。
|
||||
|
||||
## [3.1.1] - 2026-07-18
|
||||
|
||||
- 修正示例字段名：`communicationStyle` → `communication_style`、`must` → `must_do`；`personality` 示例改为字符串数组
|
||||
|
||||
@@ -3,7 +3,7 @@ name: update-agent
|
||||
description: >-
|
||||
安全更新现有智能体的配置、人格、原则、技能与记忆，输出可审阅 diff 并在确认后应用与提交。Use when 用户要求修改 Agent
|
||||
行为、安装/卸载技能、调整配置、回滚变更或修订规则。
|
||||
version: 3.1.1
|
||||
version: 3.1.2
|
||||
type: meta
|
||||
risk_level: low
|
||||
status: enabled
|
||||
@@ -14,7 +14,7 @@ tags:
|
||||
- meta
|
||||
metadata:
|
||||
author: desirecore
|
||||
updated_at: '2026-07-18'
|
||||
updated_at: '2026-07-19'
|
||||
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:15eafc7363a40986
|
||||
source_hash: sha256:ceab26ea93a41898
|
||||
translated_by: human
|
||||
en-US:
|
||||
name: Update Agent
|
||||
@@ -35,9 +35,9 @@ 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:15eafc7363a40986
|
||||
source_hash: sha256:ceab26ea93a41898
|
||||
translated_by: ai:claude-fable-5
|
||||
translated_at: '2026-07-18'
|
||||
translated_at: '2026-07-19'
|
||||
market:
|
||||
icon: >-
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
|
||||
@@ -65,369 +65,99 @@ market:
|
||||
|
||||
## L0: One-Sentence Summary
|
||||
|
||||
Safely modify an Agent's config, persona, rules, and skills through natural-language conversation.
|
||||
Safely modify an Agent's configuration, persona, rules, and skills through natural-language conversation.
|
||||
|
||||
## L1: Overview and Use Cases
|
||||
## L1: Overview
|
||||
|
||||
### Capability Description
|
||||
Meta-skill: recognize the edit intent → generate a reviewable diff → user confirmation → apply (structured fields via ManageAgent, free-form files via Read/Write) → receipt, with version rollback. Its value is what the tool can't give: diff preview confirmation, two-path orchestration, rollback; structured fields go through ManageAgent's whitelist + schema validation so invalid config never lands.
|
||||
|
||||
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.
|
||||
## L2: Detailed Spec
|
||||
|
||||
### Use Cases
|
||||
### Update Types and the Two Paths
|
||||
|
||||
- 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")
|
||||
Structured fields always go through `ManageAgent(action='update')` (whitelist + validation + merge semantics); free-form files (memory/skills/tools) are edited directly with Read/Write:
|
||||
|
||||
### Core Value
|
||||
| User intent | Means | Target (risk) |
|
||||
| --- | --- | --- |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| Add memory | Read/Write | `memory/` (low) |
|
||||
| Change tool config | Read/Write | `tools/` (high, watch protected paths) |
|
||||
|
||||
- **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
|
||||
- **Validation backstop**: Structured fields (name/description/llm/persona/principles) go through the ManageAgent built-in tool's allowlist + schema validation; invalid config is never written to disk
|
||||
|
||||
## L2: Detailed Specification
|
||||
|
||||
### Supported Update Types
|
||||
|
||||
| Update Type | Target | Update Method | Risk Level | Example |
|
||||
| ----------------- | ------------------- | ------------------- | ---------- | ---------------------------------- |
|
||||
| Name/Description | `agent.json` | ManageAgent update | Low/Medium | Rename, edit summary |
|
||||
| LLM config | `agent.json` (llm) | ManageAgent update | Medium | Switch model, adjust temperature |
|
||||
| Persona update | `persona.md` | ManageAgent update | Medium | Modify communication style, values |
|
||||
| Principles update | `principles.md` | ManageAgent update | High | Add/modify behavioral rules |
|
||||
| Skills install | `skills/` | Read/Write | Medium | Add new skill package |
|
||||
| Skills uninstall | `skills/` | Read/Write | Low | Remove skill package |
|
||||
| Memory update | `memory/` | Read/Write | Low | Add knowledge entry |
|
||||
| Tools config | `tools/` | Read/Write | High | Modify tool permissions |
|
||||
|
||||
**Two update paths**: Structured fields (name/description/llm/persona/principles) are always updated through the `update` action of the in-process built-in tool **ManageAgent** (allowlist + schema validation + merge semantics); free-form files such as memory, skills, and tools are still edited directly with Read/Write. See "Stage 5: Apply Changes".
|
||||
|
||||
### Conversation Flow
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ 意图识别 │ ──→ │ 变更分析 │ ──→ │ Diff 生成 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ 回执生成 │ ←── │ 变更应用 │ ←── │ 用户确认 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
Flow: intent recognition → change analysis → diff generation → user confirmation → apply → receipt.
|
||||
|
||||
### 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.
|
||||
Trigger (any): user says "modify/update/adjust your …", "from now on you should… / remember this rule…", "install/uninstall this skill…", or describes dissatisfaction with current behavior and wants change. Identify the update type and target scope.
|
||||
|
||||
### Stage 2: Change Analysis
|
||||
|
||||
**Analysis dimensions**:
|
||||
Assess impact (which files/behaviors), dependencies, and conflicts, and set a risk level → matching confirmation strength:
|
||||
|
||||
| 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**:
|
||||
|
||||
| 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 |
|
||||
- Low (non-core, e.g. memory entries): simple confirmation
|
||||
- Medium (persona / ordinary principles): show diff, then confirm
|
||||
- High (core principles / tool permissions): detailed explanation + diff + confirm
|
||||
- Protected (touches a protected path): block, requires owner permission
|
||||
|
||||
### Stage 3: Diff Generation
|
||||
|
||||
**Diff format example**:
|
||||
Generate a before/after diff for the user (show only the actual change), e.g.:
|
||||
|
||||
```diff
|
||||
# persona.md
|
||||
|
||||
## 沟通风格
|
||||
|
||||
- 友好、随和、轻松幽默
|
||||
+ 专业、严谨、适度幽默
|
||||
|
||||
## 决策偏好
|
||||
|
||||
保持不变...
|
||||
```
|
||||
|
||||
**Diff metadata**:
|
||||
|
||||
```yaml
|
||||
diff_metadata:
|
||||
files_affected: 1
|
||||
lines_added: 1
|
||||
lines_removed: 1
|
||||
risk_level: medium
|
||||
reversible: true
|
||||
estimated_impact: '沟通风格会变得更正式'
|
||||
# persona.md → ## Communication style
|
||||
- friendly, easygoing, light humor
|
||||
+ professional, rigorous, measured humor
|
||||
```
|
||||
|
||||
### Stage 4: User Confirmation
|
||||
|
||||
**Confirmation interface**:
|
||||
|
||||
```
|
||||
变更预览
|
||||
|
||||
影响文件: persona.md
|
||||
风险等级: 中
|
||||
影响说明: 沟通风格会从"友好随和"变为"专业严谨"
|
||||
|
||||
--- 变更内容 ---
|
||||
[展示 diff]
|
||||
----------------
|
||||
|
||||
请确认是否应用此变更？
|
||||
[应用] [取消] [修改]
|
||||
```
|
||||
|
||||
**Confirmation options**:
|
||||
|
||||
- **Apply**: Execute the change
|
||||
- **Cancel**: Discard the change
|
||||
- **Modify**: Enter edit mode for fine-tuning
|
||||
Show the diff preview (affected file, risk level, impact note + diff) and ask the user to confirm "Apply / Cancel / Modify"; "Modify" enters fine-tuning then re-confirms. (The tool layer also enforces confirmation for updating other/core agents; see Stage 5.)
|
||||
|
||||
### Stage 5: Apply Changes
|
||||
|
||||
Applying a change takes one of two paths, depending on whether the target is a **structured field** or a **free-form file**. **Do not call HTTP APIs** (after instance authentication, the Agent cannot reach the machine's local HTTP API), and **do not operate Git directly** (version management is handled automatically by the backend).
|
||||
Do not call the HTTP API (unreachable under instance auth), do not operate git directly (the backend auto-commits). Split by target into two paths:
|
||||
|
||||
#### Path A: Structured fields → ManageAgent built-in tool (mandatory)
|
||||
**Path A · Structured fields → ManageAgent (mandatory; never Write `agent.json` / `persona.md` / `principles.md` directly)**
|
||||
|
||||
The following fields **must** be updated through the `update` action of the in-process built-in tool `ManageAgent`. **Never** directly Write `agent.json` / `persona.md` / `principles.md`:
|
||||
|
||||
| Field | Constraint | Storage location |
|
||||
| ------------- | ----------------------------------------------------- | ----------------- |
|
||||
| `name` | 1–50 characters | `agent.json` |
|
||||
| `description` | ≤200 characters | `agent.json` |
|
||||
| `config.llm` | Incremental shallow merge; **config only allows `llm`** | `agent.json` |
|
||||
| `persona` | Structured object `{L0, L1:{...}, L2}` or markdown string | `persona.md` |
|
||||
| `principles` | Structured object `{L0, L1:{...}, L2}` or markdown string | `principles.md` |
|
||||
|
||||
**Call forms**:
|
||||
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:
|
||||
|
||||
```
|
||||
ManageAgent(action='update', id='<agent-id>', name='New name')
|
||||
ManageAgent(action='update', id='<agent-id>', description='One-line summary')
|
||||
ManageAgent(action='update', id='<agent-id>', config={ llm: { model: 'xxx', temperature: 0.7 } })
|
||||
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>', name='New Name')
|
||||
ManageAgent(action='update', id='<agent-id>', persona={ L1: { personality: ["professional","rigorous"] } })
|
||||
ManageAgent(action='update', id='<agent-id>', principles='…full markdown…')
|
||||
```
|
||||
|
||||
**Merge semantics (important)**:
|
||||
**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.
|
||||
|
||||
- Structured `persona` / `principles` are **field-level merges**: omitted fields retain their original values (e.g. passing only `L1.personality` will not clear L0 / role)
|
||||
- A markdown string is a **whole replacement** (used to rewrite the entire document)
|
||||
- `config.llm` is an **incremental shallow merge**: only the keys you pass are overwritten
|
||||
- The merged `agent.json` is validated against the schema as a whole; invalid config is never written to disk
|
||||
Key points:
|
||||
|
||||
**Confirmation behavior**:
|
||||
- **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.
|
||||
- **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.**
|
||||
|
||||
- Updating **yourself** requires no secondary confirmation
|
||||
- Updating **another Agent** triggers user confirmation (stacked on top of this skill's diff confirmation)
|
||||
- The core Agent (`desirecore` / `core`) refuses updates
|
||||
**Path B · Free-form files → Read/Write** (`memory/` / `skills/` / `tools/`, root `${DESIRECORE_ROOT}/agents/<agentId>/`): Read current values, then Write/Edit, re-read after writing to confirm. Before editing, check `_protected-paths.yaml`; touching a protected path should be blocked with an owner-permission notice. After writing, the backend file watcher auto-commits — no manual git.
|
||||
|
||||
**Read before you write**: Before making a change, read the current values with `ManageAgent(action='get', id='<agent-id>')`, to generate the diff and verify field names (the actual field names of persona / principles follow the structure returned by `get`).
|
||||
### Stage 6: Receipt
|
||||
|
||||
**config allowlist**: `config` only accepts `llm`. Passing `mcp_servers` / `tool_permissions` / `version` / `id`, etc., is rejected with the field name indicated — runtime config other than `llm` does not go through ManageAgent; see "Stage 5 · Path B" and Error Handling.
|
||||
Present the change summary in a user-friendly way (no internal paths / technical details), and note the user can say "undo the last change" to roll back anytime.
|
||||
|
||||
**Partial write failure**: The tool reports precisely "which fields took effect, which one failed"; on retry, **submit only the failed fields**, do not resend everything.
|
||||
### Version Rollback
|
||||
|
||||
> **Renaming is a single call.** When the user wants to change the **display name** (e.g. "rename X to Y"), just call `ManageAgent(action='update', id='<agent-id>', name='Y')` — `name` is written to `agent.json` and triggers the Agent list to refresh; no need to manually edit any other file. If the user also wants the persona document title synced, append one `persona` update in the same round. **Never claim the rename is done without actually calling ManageAgent.**
|
||||
Trigger: user says "undo / roll back / restore the previous settings". Flow:
|
||||
|
||||
#### Path B: Free-form files → edit directly with Read/Write
|
||||
1. In the Agent directory, `git log --oneline -10` for history and `git show <commit>:<file>` for the target version content; show it to the user to confirm.
|
||||
2. After confirmation, write back by type: structured fields (persona/principles, agent.json name/description/llm) → `ManageAgent(action='update', ...)` (persona/principles as a markdown string, **full replacement** with the historical content); free-form files (memory/skills) → Write directly.
|
||||
3. Show the diff to confirm the rollback.
|
||||
|
||||
Free-form files such as memory, skills, and tools are not in ManageAgent's scope and are still edited directly with the Read/Write tools:
|
||||
(git is only for **reading** history; write-back always goes through the two paths above — never rewrite working-tree files with git commands.)
|
||||
|
||||
| Target | AgentFS path |
|
||||
| ------------ | ------------ |
|
||||
| Memory entry | `memory/` |
|
||||
| Skill package | `skills/` |
|
||||
| Tools config | `tools/` |
|
||||
### Background and Error Handling
|
||||
|
||||
**AgentFS root directory**: `${DESIRECORE_ROOT}/agents/<agentId>/`
|
||||
|
||||
**Read file**: Use the Read tool to read the current contents of the target file.
|
||||
|
||||
**Write file**: Use the Write / Edit tool to write directly to the target file. After writing, re-read the file to verify the contents are correct.
|
||||
|
||||
**Protected paths**: Before editing, cross-check `_protected-paths.yaml`; touching a protected path should be blocked with a prompt that owner permission is required.
|
||||
|
||||
**Note**: After directly writing a free-form file, the backend file watcher automatically detects the change and triggers a Git commit; no manual git command is required.
|
||||
|
||||
### 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. 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, apply according to the target file type:
|
||||
- **Structured fields** (`persona.md` / `principles.md` / the name/description/llm in `agent.json`) → write back with `ManageAgent(action='update', ...)` (persona / principles are **wholly replaced** with that historical content as a markdown string)
|
||||
- **Free-form files** (`memory/` / `skills/`) → write back directly with the Write tool
|
||||
4. Show the change diff and confirm rollback success
|
||||
|
||||
(`git log` / `git show` are only used to **read** history; write-back always goes through the two paths above — do not use git commands to directly rewrite working-tree files.)
|
||||
|
||||
```bash
|
||||
# 查看版本历史
|
||||
cd ${DESIRECORE_ROOT}/agents/<agentId>
|
||||
git log --oneline -10
|
||||
|
||||
# 查看某个版本的文件内容
|
||||
git show <commit>:persona.md
|
||||
```
|
||||
|
||||
### Background Knowledge
|
||||
|
||||
> AgentFS repository structure and protected paths are detailed in `_agentfs-background.md` and `_protected-paths.yaml`.
|
||||
|
||||
**Update operation reference table**:
|
||||
|
||||
| User Intent | Update Method |
|
||||
| ------------------------------- | ----------------------------------------------------------------------- |
|
||||
| **Rename (display name)** | `ManageAgent(action='update', id, name='...')` |
|
||||
| Edit summary | `ManageAgent(action='update', id, description='...')` |
|
||||
| Modify LLM config (model/temperature/etc.) | `ManageAgent(action='update', id, config={ llm: {...} })` |
|
||||
| Modify personality/style | `ManageAgent(action='update', id, persona={...} or markdown)` |
|
||||
| Modify behavioral rules | `ManageAgent(action='update', id, principles={...} or markdown)` |
|
||||
| Install/uninstall skills | Read/Write `skills/` (`${DESIRECORE_ROOT}/agents/<agentId>/skills/`) |
|
||||
| Add memory | Read/Write `memory/` (`${DESIRECORE_ROOT}/agents/<agentId>/memory/`) |
|
||||
| Modify tools config | Read/Write `tools/` (`${DESIRECORE_ROOT}/agents/<agentId>/tools/`, mind protected paths) |
|
||||
|
||||
> Runtime config in `agent.json` other than `llm` (`mcp_servers` / `tool_permissions`, etc.) is currently not in the ManageAgent allowlist, and should not be written to `agent.json` directly to bypass validation. When such a need arises, explain to the user that it must be handled through the corresponding mechanism for now.
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Error Scenario | Handling |
|
||||
| ------------------------------------- | ------------------------------------------------------------------- |
|
||||
| `config` contains a non-allowlisted field | ManageAgent rejects it and indicates the field name; switch to the corresponding mechanism or tell the user it is not yet supported |
|
||||
| Schema validation fails | Invalid config is not written to disk; fix the fields per the tool's response and retry |
|
||||
| Updating the core Agent (desirecore/core) | ManageAgent refuses the update; tell the user the core Agent cannot be modified |
|
||||
| Partial field write failure | The tool reports which fields took effect / failed; retry only the failed fields, do not resend everything |
|
||||
| Attempt to modify a protected path (free-form file) | Block the operation; prompt that owner permission is required |
|
||||
| File does not exist | The Agent or target file does not exist; ask the user to check |
|
||||
| Insufficient permission | Filesystem permission error; ask the user to check directory permissions |
|
||||
| Rollback target version not found | List available versions and ask the user to reselect |
|
||||
|
||||
### Permission Requirements
|
||||
|
||||
| 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 Modification Example
|
||||
|
||||
**User input**: "Speak a bit more formally, not too casual"
|
||||
|
||||
**Operation flow**:
|
||||
|
||||
```
|
||||
# 1. 读取当前 persona，定位要改的字段（字段名以返回结构为准）
|
||||
ManageAgent(action='get', id='legal-assistant')
|
||||
|
||||
# 返回中的 "## persona.md" 段落即当前 persona 原文（L0/L1/L2 分层 markdown），例如:
|
||||
# ## persona.md
|
||||
# # L0
|
||||
# 专业的法律咨询助手
|
||||
# # L1
|
||||
# ## role
|
||||
# 法律顾问
|
||||
# ## personality
|
||||
# - 友好
|
||||
# - 随和
|
||||
# ## communication_style
|
||||
# 轻松幽默
|
||||
|
||||
# 2. 分析需要修改的部分，生成 diff 展示给用户确认
|
||||
|
||||
# 3. 用户确认后，用 ManageAgent 字段级合并更新（只改这两个字段，L0/role 保留）
|
||||
ManageAgent(action='update', id='legal-assistant', persona={
|
||||
L1: { personality: ["专业", "严谨"], communication_style: '正式、克制' }
|
||||
})
|
||||
|
||||
# 4. 复核结果
|
||||
ManageAgent(action='get', id='legal-assistant')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Principles Update Example
|
||||
|
||||
### Add New Rule
|
||||
|
||||
**User input**: "From now on, when there's a legal issue, remind me to consult a professional lawyer"
|
||||
|
||||
**Generated diff**:
|
||||
|
||||
```diff
|
||||
# principles.md
|
||||
|
||||
## 必须做
|
||||
|
||||
- 始终保持礼貌和尊重
|
||||
- 不确定时主动询问
|
||||
+ - 遇到法律相关问题时，提醒用户咨询专业律师
|
||||
|
||||
## 绝不做
|
||||
...
|
||||
```
|
||||
|
||||
**Apply after user confirmation**: First read the current principles with `ManageAgent(action='get', id)`, then replace the whole document (including the new rule) as a markdown string:
|
||||
|
||||
```
|
||||
ManageAgent(action='update', id='legal-assistant', principles='...(full markdown, including the new rule)...')
|
||||
```
|
||||
|
||||
(To change just one structured field, you can also pass a field-level merge such as `principles={ L1: { must_do: [...] } }`. The structured field names are fixed: persona uses `L1.role` / `L1.personality` (string array) / `L1.communication_style`; principles uses `L1.must_do` / `L1.must_not` (both string arrays) / `L1.priority`; plus top-level `L0` / `L2` strings.)
|
||||
|
||||
### Modify Existing Rule
|
||||
|
||||
**User input**: "Don't remind me every time, it's too verbose"
|
||||
|
||||
**Generated diff**:
|
||||
|
||||
```diff
|
||||
# principles.md
|
||||
|
||||
## 必须做
|
||||
|
||||
- - 每次回答后都提醒用户检查内容
|
||||
+ - 仅在重要决策时提醒用户检查内容
|
||||
```
|
||||
|
||||
**Apply after user confirmation**: Same as above — write the modified content back with `ManageAgent(action='update', id, principles=...)`.
|
||||
- AgentFS structure and protected paths: see `_agentfs-background.md` and `_protected-paths.yaml`.
|
||||
- On tool errors: non-whitelisted config field / schema validation failure / core-agent refusal → fix per the tool's hint or inform the user; protected path → block with an owner-permission notice; rollback version not found → list available versions and ask the user to reselect.
|
||||
|
||||
@@ -6,367 +6,97 @@
|
||||
|
||||
通过自然语言对话，安全地修改 Agent 的配置、人格、规则和技能。
|
||||
|
||||
## L1：概述与使用场景
|
||||
## L1：概述
|
||||
|
||||
### 能力描述
|
||||
|
||||
update-agent 是一个**元技能（Meta-Skill）**，允许用户通过对话方式修改 Agent 的各项配置。所有修改都会生成可审阅的 diff 补丁，经用户确认后才会应用，并支持版本回滚。
|
||||
|
||||
### 使用场景
|
||||
|
||||
- 用户想要调整 Agent 的沟通风格（"说话再正式一点"）
|
||||
- 需要添加新的行为规则（"以后遇到敏感话题要先提醒我"）
|
||||
- 安装或卸载技能包（"学会写合同吧"）
|
||||
- 批量更新多项配置（"全面升级一下你的能力"）
|
||||
|
||||
### 核心价值
|
||||
|
||||
- **安全可控**：所有变更需用户确认，支持回滚
|
||||
- **透明可见**：变更以 diff 形式展示，清晰明了
|
||||
- **版本管理**：通过 Git 管理版本，可追溯历史
|
||||
- **校验兜底**：结构化字段（name/description/llm/persona/principles）经 ManageAgent 内置工具的白名单 + schema 校验，非法配置不会落盘
|
||||
元技能：识别修改意图 → 生成可审阅 diff → 用户确认 → 应用（结构化字段走 ManageAgent、自由文件走 Read/Write）→ 回执，并支持版本回滚。价值在工具给不了的部分：diff 预览确认、两路径编排、回滚；结构化字段经 ManageAgent 白名单 + schema 校验，非法配置不落盘。
|
||||
|
||||
## L2：详细规范
|
||||
|
||||
### 支持的更新类型
|
||||
### 更新类型与两条路径
|
||||
|
||||
| 更新类型 | 目标 | 更新手段 | 风险等级 | 示例 |
|
||||
| --------------- | --------------- | ------------------- | -------- | -------------------- |
|
||||
| 名称/描述 | `agent.json` | ManageAgent update | 低/中 | 改名、改简介 |
|
||||
| LLM 配置 | `agent.json`（llm） | ManageAgent update | 中 | 换模型、调温度 |
|
||||
| Persona 更新 | `persona.md` | ManageAgent update | 中 | 修改沟通风格、价值观 |
|
||||
| Principles 更新 | `principles.md` | ManageAgent update | 高 | 添加/修改行为规则 |
|
||||
| Skills 安装 | `skills/` | Read/Write | 中 | 添加新技能包 |
|
||||
| Skills 卸载 | `skills/` | Read/Write | 低 | 移除技能包 |
|
||||
| Memory 更新 | `memory/` | Read/Write | 低 | 添加知识条目 |
|
||||
| Tools 配置 | `tools/` | Read/Write | 高 | 修改工具权限 |
|
||||
结构化字段一律经 `ManageAgent(action='update')`（白名单 + 校验 + 合并语义）；记忆/技能/工具等自由格式文件用 Read/Write 直接编辑：
|
||||
|
||||
**两条更新路径**：结构化字段（name/description/llm/persona/principles）一律经进程内内置工具 **ManageAgent** 的 `update` 动作更新（白名单 + schema 校验 + 合并语义）；记忆、技能、工具等自由格式文件仍用 Read/Write 直接编辑。详见「阶段 5：变更应用」。
|
||||
| 用户意图 | 手段 | 目标（风险） |
|
||||
| --- | --- | --- |
|
||||
| 改名（显示名称） | `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 生成 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ 回执生成 │ ←── │ 变更应用 │ ←── │ 用户确认 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
流程：意图识别 → 变更分析 → diff 生成 → 用户确认 → 应用 → 回执。
|
||||
|
||||
### 阶段 1：意图识别
|
||||
|
||||
**触发条件**（任一满足）：
|
||||
|
||||
- 用户说"修改你的..."、"更新你的..."、"调整一下..."
|
||||
- 用户说"你以后要..."、"记住这个规则..."
|
||||
- 用户说"安装/卸载这个技能..."
|
||||
- 用户描述对当前行为的不满并期望改变
|
||||
|
||||
**输出**：识别更新类型和目标范围。
|
||||
触发（任一）：用户说"修改/更新/调整你的…"、"你以后要…/记住这个规则…"、"安装/卸载这个技能…"，或描述对当前行为的不满并期望改变。识别更新类型与目标范围。
|
||||
|
||||
### 阶段 2：变更分析
|
||||
|
||||
**分析维度**：
|
||||
评估影响范围（哪些文件/行为）、依赖与冲突，并定风险等级 → 对应确认强度：
|
||||
|
||||
| 维度 | 说明 |
|
||||
| -------- | ------------------------ |
|
||||
| 影响范围 | 影响哪些文件、哪些行为 |
|
||||
| 风险等级 | 低/中/高（见风险分级表） |
|
||||
| 依赖检查 | 是否影响其他配置 |
|
||||
| 冲突检测 | 是否与现有规则冲突 |
|
||||
- 低（记忆条目等非核心）：简单确认
|
||||
- 中（persona / 普通 principles）：展示 diff 后确认
|
||||
- 高（核心 principles / 工具权限）：详细说明 + diff + 确认
|
||||
- 受保护（触及受保护路径）：阻断，需 owner 权限
|
||||
|
||||
**风险分级表**：
|
||||
### 阶段 3：diff 生成
|
||||
|
||||
| 风险等级 | 条件 | 确认要求 |
|
||||
| -------- | ------------------------------ | ---------------------- |
|
||||
| 低 | 仅影响非核心配置（如记忆条目） | 简单确认 |
|
||||
| 中 | 影响 persona 或普通 principles | 展示 diff 后确认 |
|
||||
| 高 | 影响核心 principles 或工具权限 | 详细说明 + diff + 确认 |
|
||||
| 受保护 | 触及受保护路径 | 阻断，需 owner 权限 |
|
||||
|
||||
### 阶段 3：Diff 生成
|
||||
|
||||
**Diff 格式示例**：
|
||||
生成变更前后 diff 展示给用户（只展示实际改动），例如：
|
||||
|
||||
```diff
|
||||
# persona.md
|
||||
|
||||
## 沟通风格
|
||||
|
||||
# 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]
|
||||
----------------
|
||||
|
||||
请确认是否应用此变更？
|
||||
[应用] [取消] [修改]
|
||||
```
|
||||
|
||||
**确认选项**：
|
||||
|
||||
- **应用**：执行变更
|
||||
- **取消**：放弃变更
|
||||
- **修改**：进入编辑模式微调
|
||||
展示 diff 预览（影响文件、风险等级、影响说明 + diff），请用户确认「应用 / 取消 / 修改」；选"修改"进入微调后再确认。（工具层对更新他人/核心体另有强制确认，见阶段 5。）
|
||||
|
||||
### 阶段 5：变更应用
|
||||
|
||||
变更应用分两条路径，取决于目标是**结构化字段**还是**自由格式文件**。**不要调用 HTTP API**（实例鉴权后 Agent 无法访问本机 HTTP API），**不要直接操作 Git**（版本管理由后端自动处理）。
|
||||
不要调 HTTP API（实例鉴权后不可达），不要直接操作 git（后端自动提交）。按目标分两路：
|
||||
|
||||
#### 路径 A：结构化字段 → ManageAgent 内置工具（强制）
|
||||
**路径 A · 结构化字段 → ManageAgent（强制；禁止直接 Write `agent.json` / `persona.md` / `principles.md`）**
|
||||
|
||||
以下字段**必须**通过进程内内置工具 `ManageAgent` 的 `update` 动作更新，**禁止**直接 Write `agent.json` / `persona.md` / `principles.md`：
|
||||
|
||||
| 字段 | 约束 | 落地位置 |
|
||||
| ------------- | -------------------------------------- | ----------------- |
|
||||
| `name` | 1–50 字符 | `agent.json` |
|
||||
| `description` | ≤200 字符 | `agent.json` |
|
||||
| `config.llm` | 增量浅合并；**config 只允许 `llm`** | `agent.json` |
|
||||
| `persona` | 结构化对象 `{L0, L1:{...}, L2}` 或 markdown 字符串 | `persona.md` |
|
||||
| `principles` | 结构化对象 `{L0, L1:{...}, L2}` 或 markdown 字符串 | `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>', description='一句话简介')
|
||||
ManageAgent(action='update', id='<agent-id>', config={ llm: { model: 'xxx', temperature: 0.7 } })
|
||||
ManageAgent(action='update', id='<agent-id>', persona={ L1: { personality: ["专业", "严谨"] } })
|
||||
ManageAgent(action='update', id='<agent-id>', principles='...（完整 markdown）...')
|
||||
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 校验，非法配置不落盘。
|
||||
|
||||
- 结构化 `persona` / `principles` 是**字段级合并**：省略的字段保留原值（如只传 `L1.personality` 不会清掉 L0 / role）
|
||||
- markdown 字符串是**整体替换**（用于整篇重写）
|
||||
- `config.llm` 是**增量浅合并**：只覆盖你传入的 key
|
||||
- 合并后的 `agent.json` 会整体过 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 时声称已改名。**
|
||||
|
||||
- 更新**自身**免二次确认
|
||||
- 更新**其他智能体**会触发用户确认（与本技能的 diff 确认叠加）
|
||||
- 核心智能体（`desirecore` / `core`）拒绝更新
|
||||
**路径 B · 自由格式文件 → Read/Write**（`memory/` / `skills/` / `tools/`，根 `${DESIRECORE_ROOT}/agents/<agentId>/`）：先 Read 现值，再 Write/Edit，写后重读确认。编辑前对照 `_protected-paths.yaml`，触及受保护路径应阻断并提示需 owner 权限。写入后后端文件监控自动 git 提交，无需手动 git。
|
||||
|
||||
**改前先读**：改之前先用 `ManageAgent(action='get', id='<agent-id>')` 读取现值，用于生成 diff、校对字段名（persona / principles 的实际字段名以 `get` 返回的结构为准）。
|
||||
### 阶段 6：回执
|
||||
|
||||
**config 白名单**：`config` 仅接受 `llm`。传入 `mcp_servers` / `tool_permissions` / `version` / `id` 等会被拒绝并指明字段名——`llm` 以外的运行时配置不走 ManageAgent，见「阶段 5 · 路径 B」与错误处理。
|
||||
以用户友好方式呈现变更摘要（不暴露内部路径/技术细节），并告知可随时说"撤销刚才的修改"回滚。
|
||||
|
||||
**部分写入失败**：工具会精确报告"哪些字段已生效、哪个失败"，重试时**只提交失败字段**，不要整体重发。
|
||||
### 版本回滚
|
||||
|
||||
> **改名一次调用完成。** 用户要改**显示名称**（如"把 X 改名为 Y"）时，直接 `ManageAgent(action='update', id='<agent-id>', name='Y')` 即可——`name` 写入 `agent.json` 并触发智能体列表刷新，无需再手动编辑任何文件。若用户希望人格文档标题也同步，可在同一轮追加一次 `persona` 更新。**绝不要在没有实际调用 ManageAgent 的情况下声称已改名。**
|
||||
触发：用户说"撤销/回滚/恢复原来的设置"。流程：
|
||||
|
||||
#### 路径 B：自由格式文件 → Read/Write 直接编辑
|
||||
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 确认回滚成功。
|
||||
|
||||
记忆、技能、工具等**自由格式文件**不在 ManageAgent 范围，仍用 Read/Write 工具直接编辑：
|
||||
（git 仅用于**读**历史，回写一律走上述两路径，不要用 git 命令直接改工作区文件。）
|
||||
|
||||
| 目标 | AgentFS 路径 |
|
||||
| -------- | ------------ |
|
||||
| 记忆条目 | `memory/` |
|
||||
| 技能包 | `skills/` |
|
||||
| 工具配置 | `tools/` |
|
||||
### 背景与错误处理
|
||||
|
||||
**AgentFS 根目录**：`${DESIRECORE_ROOT}/agents/<agentId>/`
|
||||
|
||||
**读取文件**：使用 Read 工具读取目标文件当前内容。
|
||||
|
||||
**写入文件**：使用 Write / Edit 工具直接写入目标文件。写入后重新读取文件确认内容正确。
|
||||
|
||||
**受保护路径**：编辑前对照 `_protected-paths.yaml`，触及受保护路径应阻断并提示需 owner 权限。
|
||||
|
||||
**注意**：直接写入自由格式文件后，后端文件监控会自动检测变更并触发 Git 提交，无需手动执行 git 命令。
|
||||
|
||||
### 阶段 6：回执生成
|
||||
|
||||
创建成功后，以用户友好的方式呈现回执（不要暴露内部路径或技术细节）：
|
||||
|
||||
> 已更新「法律顾问小助手」的沟通风格。
|
||||
>
|
||||
> **变更摘要**：沟通风格从"友好随和"调整为"专业严谨"
|
||||
>
|
||||
> 如果不满意，可以随时说"撤销刚才的修改"来回滚。
|
||||
|
||||
### 特殊操作：版本回滚
|
||||
|
||||
**触发条件**：用户说"撤销刚才的修改"、"回滚到之前的版本"、"恢复原来的设置"
|
||||
|
||||
**回滚流程**：
|
||||
|
||||
1. 在 Agent 目录下执行 `git log --oneline -10` 查看最近的版本历史
|
||||
2. 使用 `git show <commit>:<file>` 获取目标版本的文件内容，展示给用户确认
|
||||
3. 用户确认后，按目标文件类型应用：
|
||||
- **结构化字段**（`persona.md` / `principles.md` / `agent.json` 的 name/description/llm）→ 用 `ManageAgent(action='update', ...)` 写回（persona / principles 以 markdown 字符串**整体替换**为该历史内容）
|
||||
- **自由格式文件**（`memory/` / `skills/`）→ 用 Write 工具直接写回
|
||||
4. 展示变更 diff，确认回滚成功
|
||||
|
||||
（`git log` / `git show` 仅用于**读取**历史，回写一律走上述两条路径，不要用 git 命令直接改写工作区文件。）
|
||||
|
||||
```bash
|
||||
# 查看版本历史
|
||||
cd ${DESIRECORE_ROOT}/agents/<agentId>
|
||||
git log --oneline -10
|
||||
|
||||
# 查看某个版本的文件内容
|
||||
git show <commit>:persona.md
|
||||
```
|
||||
|
||||
### 背景知识
|
||||
|
||||
> AgentFS 仓库结构与受保护路径详见 `_agentfs-background.md` 和 `_protected-paths.yaml`。
|
||||
|
||||
**更新操作对照表**：
|
||||
|
||||
| 用户意图 | 更新手段 |
|
||||
| --------------------- | ------------------------------------------------------------------------ |
|
||||
| **改名（显示名称）** | `ManageAgent(action='update', id, name='...')` |
|
||||
| 改简介 | `ManageAgent(action='update', id, description='...')` |
|
||||
| 修改 LLM 配置（模型/温度等） | `ManageAgent(action='update', id, config={ llm: {...} })` |
|
||||
| 修改性格/风格 | `ManageAgent(action='update', id, persona={...} 或 markdown)` |
|
||||
| 修改行为规则 | `ManageAgent(action='update', id, principles={...} 或 markdown)` |
|
||||
| 安装/卸载技能 | Read/Write `skills/`（`${DESIRECORE_ROOT}/agents/<agentId>/skills/`） |
|
||||
| 添加记忆 | Read/Write `memory/`（`${DESIRECORE_ROOT}/agents/<agentId>/memory/`） |
|
||||
| 修改工具配置 | Read/Write `tools/`（`${DESIRECORE_ROOT}/agents/<agentId>/tools/`，注意受保护路径） |
|
||||
|
||||
> `agent.json` 中 `llm` 以外的运行时配置（`mcp_servers` / `tool_permissions` 等）当前不在 ManageAgent 白名单，也不应直接 Write `agent.json` 绕过校验。遇到此类需求，向用户说明暂需通过对应机制处理。
|
||||
|
||||
### 错误处理
|
||||
|
||||
| 错误场景 | 处理方式 |
|
||||
| ---------------------------- | ---------------------------------------------------------- |
|
||||
| `config` 含非白名单字段 | ManageAgent 拒绝并指明字段名；改走对应机制或告知用户暂不支持 |
|
||||
| schema 校验失败 | 非法配置不落盘；按工具返回修正字段后重试 |
|
||||
| 更新核心智能体（desirecore/core） | ManageAgent 拒绝更新；告知用户核心智能体不可修改 |
|
||||
| 部分字段写入失败 | 工具报告已生效/失败字段；仅重试失败字段，不整体重发 |
|
||||
| 尝试修改受保护路径（自由文件） | 阻断操作，提示需要 owner 权限 |
|
||||
| 文件不存在 | Agent 或目标文件不存在，提示用户检查 |
|
||||
| 权限不足 | 文件系统权限错误，提示用户检查目录权限 |
|
||||
| 回滚版本不存在 | 列出可用版本，请用户重新选择 |
|
||||
|
||||
### 权限要求
|
||||
|
||||
| 操作 | 所需角色 |
|
||||
| --------------------------- | ------------- |
|
||||
| 更新 persona | owner, member |
|
||||
| 更新 principles（普通规则） | owner, member |
|
||||
| 更新 principles（安全红线） | owner |
|
||||
| 安装/卸载 skills | owner, member |
|
||||
| 修改 tools 权限 | owner |
|
||||
| 版本回滚 | owner |
|
||||
|
||||
---
|
||||
|
||||
## 附录：更新示例
|
||||
|
||||
### Persona 修改示例
|
||||
|
||||
**用户输入**："说话再正式一点，不要太随意"
|
||||
|
||||
**操作流程**：
|
||||
|
||||
```
|
||||
# 1. 读取当前 persona，定位要改的字段（字段名以返回结构为准）
|
||||
ManageAgent(action='get', id='legal-assistant')
|
||||
|
||||
# 返回中的 "## persona.md" 段落即当前 persona 原文（L0/L1/L2 分层 markdown），例如:
|
||||
# ## persona.md
|
||||
# # L0
|
||||
# 专业的法律咨询助手
|
||||
# # L1
|
||||
# ## role
|
||||
# 法律顾问
|
||||
# ## personality
|
||||
# - 友好
|
||||
# - 随和
|
||||
# ## communication_style
|
||||
# 轻松幽默
|
||||
|
||||
# 2. 分析需要修改的部分，生成 diff 展示给用户确认
|
||||
|
||||
# 3. 用户确认后，用 ManageAgent 字段级合并更新（只改这两个字段，L0/role 保留）
|
||||
ManageAgent(action='update', id='legal-assistant', persona={
|
||||
L1: { personality: ["专业", "严谨"], communication_style: '正式、克制' }
|
||||
})
|
||||
|
||||
# 4. 复核结果
|
||||
ManageAgent(action='get', id='legal-assistant')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Principles 更新示例
|
||||
|
||||
### 添加新规则
|
||||
|
||||
**用户输入**："以后遇到法律问题，先提醒我找专业律师"
|
||||
|
||||
**生成的 Diff**：
|
||||
|
||||
```diff
|
||||
# principles.md
|
||||
|
||||
## 必须做
|
||||
|
||||
- 始终保持礼貌和尊重
|
||||
- 不确定时主动询问
|
||||
+ - 遇到法律相关问题时，提醒用户咨询专业律师
|
||||
|
||||
## 绝不做
|
||||
...
|
||||
```
|
||||
|
||||
**用户确认后应用**：先 `ManageAgent(action='get', id)` 取当前 principles，把整篇内容（含新增规则）以 markdown 字符串整体替换：
|
||||
|
||||
```
|
||||
ManageAgent(action='update', id='legal-assistant', principles='...（整篇 markdown，含新增规则）...')
|
||||
```
|
||||
|
||||
（若只改结构化对象的某个字段，也可用字段级合并传 `principles={ L1: { must_do: [...] } }`。结构化字段名固定为：persona 的 `L1.role` / `L1.personality`（字符串数组）/ `L1.communication_style`，principles 的 `L1.must_do` / `L1.must_not`（均为字符串数组）/ `L1.priority`，另有顶层 `L0` / `L2` 字符串。）
|
||||
|
||||
### 修改现有规则
|
||||
|
||||
**用户输入**："不要每次都提醒我，太啰嗦了"
|
||||
|
||||
**生成的 Diff**：
|
||||
|
||||
```diff
|
||||
# principles.md
|
||||
|
||||
## 必须做
|
||||
|
||||
- - 每次回答后都提醒用户检查内容
|
||||
+ - 仅在重要决策时提醒用户检查内容
|
||||
```
|
||||
|
||||
**用户确认后应用**：同上，用 `ManageAgent(action='update', id, principles=...)` 写回修改后的内容。
|
||||
- AgentFS 结构、受保护路径详见 `_agentfs-background.md` 与 `_protected-paths.yaml`。
|
||||
- 工具报错时：config 非白名单字段 / schema 校验失败 / 核心体拒绝 → 按工具提示修正或告知用户；受保护路径 → 阻断并提示需 owner；回滚版本不存在 → 列出可用版本请用户重选。
|
||||
|
||||
Reference in New Issue
Block a user