/byted-ark-evolve

name: byted-ark-evolve
description: >
  Agent self-evolution system. Collects signals from user feedback,
  stores execution trajectories (golden + correction pairs), analyzes
  patterns, proposes mutations to workspace files, and generates HTML reports.
  Trigger with "/evolve" or when the user asks to improve agent behavior.
  Also use when the user says "remember this pattern", "don't do X again",
  or "that was a good approach, save it".
metadata:
  version: "0.3.1"
  author: "volcengine/modelark"
  tags: "evolution meta-skill self-evolving"

Evolution Skill

Agent 自进化系统。进化单位是整个 Agent（Identity + Context + Protocol + Capability + Runtime）。

核心原则

1. **Quality > Reliability > Efficiency > Cost** — 不允许牺牲质量换效率 2. **帕累托约束** — 任何 mutation 如果导致某个维度退化，BLOCK 并请用户决策 3. **写入即生效** — 用户确认变更后写入 workspace 文件，下次 session 即可加载新配置 4. **先对齐再执行** — 进化方案必须先呈现给用户确认

数据安全与权限边界

• **本地存储**：所有运行时数据(信号、轨迹、变异、报告)写入用户本地 `~/.{*claw*}/workspace/evolution-data/`，不上传任何外部服务。
• **无外网调用**：脚本不发起 HTTP/socket 请求(可代码层验证：无 `requests` / `urllib` / `http.client` / `socket` 等导入用于网络通信)。
• **变更前置确认**：mutation 写入 workspace 文件前，必须由用户在对话中显式接受提案；用户未接受前不会修改任何文件。
• **作用范围**：写入仅限 `~/.{*claw*}/workspace/` 目录及其子目录；不访问 `/etc/`、`~/.ssh/`、`~/.aws/` 等敏感路径。
• **可审计**：每次 apply 通过 git commit 留痕，用户可随时 `git log` 查看完整变更历史。
• **可追溯**：每条 mutation 在 SQLite DB 中保留 source(evolution / user-direct / snapshot-diff)、决策状态、时间戳。
• **可禁用**：删除 `evolution-data/` 目录或卸载 skill 即完全停止；删除 `~/.{*claw*}/workspace/` 不会影响其他 skill。

数据目录

> **Runtime 适配**：workspace 根路径自动探测 `~/.{*claw*}/workspace/`(优先 `.arkclaw` → `.openclaw` → 其他含 `claw` 的目录),也可用 `CLAW_WORKSPACE` 环境变量显式指定。新装默认创建在 `~/.arkclaw/workspace/`。

evolution-data/
├── file-registry.json    ← 初始化扫描结果
├── evolution.db          ← SQLite（信号、变异、轨迹）
├── snapshot.json         ← Workspace 文件 hash 快照（兜底变更检测）
├── trajectories/
│   ├── golden/           ← 正确执行轨迹
│   └── corrections/      ← 错误→修正对
├── dashboard.html        ← Dashboard 页面（dashboard-render.py 自动生成）
└── reports/
    ├── evolution-*.json  ← 进化报告数据（JSON）
    └── evolution-*.html  ← 进化报告页面（渲染后）

References（按需读取，不随 session 加载）

| 文件 | 内容 | 何时读取 | |------|------|---------| | `references/layer-model.md` | 5 层模型 + 归因规则 | 进化分析时 | | `references/pareto-rules.md` | 帕累托约束 + 验证标准 | 进化分析时 | | `references/file-semantic-map.md` | 已知文件→层/语义/风险映射 | 初始化 + 归因时 | | `references/init-rules.md` | 状态判定规则 + 占位符列表 | 初始化时 | | `references/signal-types.md` | 信号识别规则 + 示例 | 信号收集时 | | `references/trajectory-templates.md` | 轨迹存储格式 + 示例 | 轨迹写入时 | | `references/evolution-steps.md` | 进化分析详细流程（Step 0-7） | /evolve 执行时 | | `references/onboarding.md` | 新手引导内容 | 首次安装时 | | `references/report-schema-example.json` | 报告 JSON 数据格式示例 | 生成报告时 | | `references/dashboard-schema-example.json` | Dashboard JSON 数据格式示例 | 生成 Dashboard 时 |

---

零、初始化（/evolve init）

首次安装或 Agent 版本变化时执行。

触发条件：

• `evolution-data/` 不存在
• `file-registry.json` 中 `agent_version` 与当前不一致

首次安装流程（建议连贯执行）

**Step A — 新手引导（纯展示，无需用户确认）**

检测到首次安装时，建议直接展示以下引导内容(无需额外询问"是否要看引导")：

> **欢迎使用进化系统** > > 这个系统让我能从你的反馈中学习。简单来说： > - 你日常的纠正、建议会被自动记录 > - 攒够一定数量后，我会分析这些反馈并提出改进方案 > - **所有改动必须经你确认才会执行** > > **可用命令** > > | 命令 | 说明 | > |------|------| > | `/evolve` | 手动触发一次进化分析 | > | `/evolve init` | 重新初始化 | > | `/evolve scan` | 扫描历史对话提取反馈 | > | `/evolve dashboard` | 生成进化 Dashboard | > | `/evolve help` | 查看完整引导 | > > 现在开始初始化扫描——扫描完成后，你还可以选择扫描历史对话来加速学习。

展示完毕后建议进入 Step B,无需用户额外确认。

详细引导内容（用户说 `/evolve help` 时展示完整版）：读取 `references/onboarding.md`

**Step B — 初始化扫描（涉及文件写入，需用户确认）**

python skills/byted-ark-evolve/scripts/workspace-init.py

1. 全量扫描 workspace（排除 .git/ node_modules/ __pycache__/ evolution-data/） 2. 按 `references/init-rules.md` 判定每个文件状态（evolvable / user-owned / skill-owned / needs_review） 3. 按 `references/file-semantic-map.md` 标注已知文件语义，未知文件标 needs_review 4. 生成 `evolution-data/file-registry.json` 5. 如果 DB 不存在，执行 `db-init.py` 6. 输出摘要

needs_review 文件：进化分析时由 Agent 读取并补分类，写回 registry。

**Step C — 历史对话扫描（可选，需用户确认）**

Step B 完成后，提供历史对话扫描选项：

# 先估算成本
python skills/byted-ark-evolve/scripts/scan-history.py estimate --days 7
python skills/byted-ark-evolve/scripts/scan-history.py estimate --days 30

展示给用户：

> 检测到 N 段历史对话。是否要扫描过去的对话来提取已有的反馈信号？ > 这可以让进化系统从你已有的使用习惯开始学习，而非从零开始。 > > 1. 扫描最近 7 天（N 段对话，预计消耗 ~X tokens，约 $Y） > 2. 扫描最近 30 天（N 段对话，预计消耗 ~X tokens，约 $Y） > 3. 跳过，从零开始 > > 你也可以随时用 `/evolve scan` 手动触发。

用户选择后：

# 提取对话内容
python skills/byted-ark-evolve/scripts/scan-history.py extract --days 7

Agent 逐段对话读取，按 `references/signal-types.md` 规则识别信号，调用 `signal-record.py` 记录（标记 `context` 为 `history-scan`）。

完成后展示摘要："从 X 段对话中提取了 Y 条反馈（N 条纠正、M 条建议…）"

如果用户选择跳过，直接结束初始化。

---

〇、User-Direct 变更追踪

用户直接指令 Agent 修改 workspace 文件时，自动记录到 evolution.db。

**追踪层 A（可选 Hook）**：用户启用 PostToolUse Hook 后，监听 Edit/Write 事件，目标在 workspace 内则记录 `source='user-direct'`(Hook 仅观察执行结果，不阻断工具调用)。 **追踪层 B（快照兜底）**：进化分析启动时对比 `snapshot.json`，捕获 Hook 漏掉的变更（手动编辑、Bash 写入等），记录为 `source='snapshot-diff'`。

Mutation source 三种值：

• `evolution` — 进化分析产生（走 proposed→approved→applied 流程）
• `user-direct` — Hook 实时捕获（跳过 proposed/approved，直接 applied）
• `snapshot-diff` — 快照对比发现（缺失意图，仅标注"检测到变更"）

---

一、信号收集

在日常对话中，识别用户反馈信号并记录到 SQLite。

信号类型：correction / negative / positive / suggestion / preference / clarification Layer 归因：identity / context / protocol / capability / runtime

详细识别规则和示例：读取 `references/signal-types.md`

记录：

python skills/byted-ark-evolve/scripts/signal-record.py \
  --type correction --layer protocol --severity high \
  --text "用户原话" --context "当时在做什么"

当用户说"记住这个"、"以后别这样"等,建议及时记录为信号。

---

二、轨迹存储

两种轨迹：

• **Golden**：做对了 → `evolution-data/trajectories/golden/`
• **Correction**：做错了→修正 → `evolution-data/trajectories/corrections/`

存储格式和模板：读取 `references/trajectory-templates.md`

执行任务前，检索相关 correction trajectory，主动复述修正要点。

---

三、Gate 检查

python skills/byted-ark-evolve/scripts/gate-check.py

自动触发条件（满足任一）：

• ≥5 条 correction/negative/clarification 信号
• ≥3 条 high severity 信号
• 同一 layer ≥3 条信号
• ≥7 天无进化且有新信号

约束：24