byted-ark-evolve

Evolution Skill

Agent self-evolution system. The unit of evolution is the entire Agent (Identity + Context + Protocol + Capability + Runtime).

Core Principles

1. Quality > Reliability > Efficiency > Cost — Do not sacrifice quality for efficiency
2. Pareto constraint — If any mutation causes a regression in some dimension, BLOCK and ask the user to decide
3. Write takes effect immediately — After the user confirms the change, write it to the workspace file; the new configuration will be loaded on the next session
4. Align first, then execute — The evolution plan must first be presented to the user for confirmation

Data Security and Permission Boundaries

• Local storage: All runtime data (signals, trajectories, mutations, reports) is written to the user's local ~/.{*claw*}/workspace/evolution-data/, and is not uploaded to any external service.
• No external network calls: The scripts do not initiate HTTP/socket requests (verifiable at the code level: no requests / urllib / http.client / socket or similar imports used for network communication).
• Pre-change confirmation: Before a mutation is written to a workspace file, the user must explicitly accept the proposal in the conversation; no files will be modified before the user accepts.
• Scope: Writes are limited to the ~/.{*claw*}/workspace/ directory and its subdirectories; sensitive paths such as /etc/、~/.ssh/、~/.aws/ are not accessed.
• Auditable: Each apply leaves a trace via git commit, so the user can at any time use git log to view the complete change history.
• Traceable: Each mutation retains source (evolution / user-direct / snapshot-diff), decision status, and timestamp in the SQLite DB.
• Disableable: Deleting the evolution-data/ directory or uninstalling the skill stops it completely; deleting ~/.{*claw*}/workspace/ will not affect other skills.

Data Directory

Runtime adaptation: The workspace root path automatically detects ~/.{*claw*}/workspace/(preferring .arkclaw → .openclaw → other directories containing claw ), and can also be explicitly specified with the CLAW_WORKSPACE environment variable. New installations are created by default in ~/.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 (read on demand, not loaded with the session)

File	Content	When to read
references/layer-model.md	5-layer model + attribution rules	During evolution analysis
references/pareto-rules.md	Pareto constraint + validation criteria	During evolution analysis
references/file-semantic-map.md	Known file → layer/semantics/risk mapping	During initialization + attribution
references/init-rules.md	State determination rules + placeholder list	During initialization
references/signal-types.md	Signal recognition rules + examples	During signal collection
references/trajectory-templates.md	Trajectory storage format + examples	During trajectory writing
references/evolution-steps.md	Detailed evolution analysis flow (Step 0-7)	During /evolve execution
references/onboarding.md	Beginner onboarding content	During first installation
references/report-schema-example.json	Report JSON data format example	When generating a report
references/dashboard-schema-example.json	Dashboard JSON data format example	When generating the Dashboard

---

Zero, Initialization (/evolve init)

Executed on first installation or when the Agent version changes.

Trigger conditions:

• evolution-data/ does not exist
• file-registry.json in agent_version is inconsistent with the current one

First-time installation flow (recommended to execute consecutively)

Step A — New user guide (purely display, no user confirmation required)

When a first-time installation is detected, it is recommended to directly display the following guide content (no need to additionally ask "do you want to see the guide"):

Welcome to the Evolution System

This system lets me learn from your feedback. Simply put:

• Your everyday corrections and suggestions will be automatically recorded
• Once enough have accumulated, I will analyze this feedback and propose improvement plans
• All changes must be confirmed by you before they are executed

Available commands

Command	Description
/evolve	Manually trigger an evolution analysis
/evolve init	Reinitialize
/evolve scan	Scan historical conversations to extract feedback
/evolve dashboard	Generate the evolution Dashboard
/evolve help	View the complete guide

Now starting the initialization scan—after the scan is complete, you can also choose to scan historical conversations to accelerate learning.

After displaying, it is recommended to proceed to Step B, with no additional user confirmation required.

Detailed guide content (display the full version when the user says /evolve help ): read references/onboarding.md

Step B — Initialization scan (involves file writes, requires user confirmation)

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

1. Full scan of the workspace (excluding .git/ node_modules/ pycache/ evolution-data/）
2. Determine each file's status according to references/init-rules.md (evolvable / user-owned / skill-owned / needs_review)
3. Annotate known file semantics according to references/file-semantic-map.md , and mark unknown files as needs_review
4. Generate evolution-data/file-registry.json
5. If the DB does not exist, execute db-init.py
6. Output summary

needs_review files: during evolution analysis, the Agent reads them and supplements the classification, then writes them back to the registry.

Step C — Historical conversation scan (optional, requires user confirmation)

After Step B is complete, provide the historical conversation scan option:

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

Display to the user:

Detected N historical conversations. Do you want to scan past conversations to extract existing feedback signals? This lets the evolution system start learning from your existing usage habits, rather than starting from zero.

1. Scan the last 7 days (N conversations, estimated consumption ~X tokens, about $Y)
2. Scan the last 30 days (N conversations, estimated consumption ~X tokens, about $Y)
3. Skip, start from zero

You can also use /evolve scan at any time to trigger it manually.

After the user selects:

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

The Agent reads the conversations segment by segment, identifies signals according to the references/signal-types.md rules, and calls signal-record.py to record them (marking context as history-scan）。

After completion, display a summary: "Extracted Y feedback items from X conversations (N corrections, M suggestions…)"

If the user chooses to skip, end initialization directly.

---

0. User-Direct change tracking

When the user directly instructs the Agent to modify workspace files, automatically record it to evolution.db.

Tracking layer A (optional Hook): after the user enables the PostToolUse Hook, listen for Edit/Write events, and if the target is within the workspace, record source='user-direct'(the Hook only observes execution results and does not block tool calls). Tracking layer B (snapshot fallback): when evolution analysis starts, compare snapshot.json, capture changes missed by the Hook (manual edits, Bash writes, etc.), and record them as source='snapshot-diff'。

Three values of Mutation source:

• evolution — Generated by evolution analysis (goes through the proposed→approved→applied flow)
• user-direct — Captured by Hook in real time (skips proposed/approved, goes directly to applied)
• snapshot-diff — Discovered by snapshot comparison (missing intent, only marked as "change detected")

---

1. Signal Collection

In daily conversations, identify user feedback signals and record them to SQLite.

Signal types: correction / negative / positive / suggestion / preference / clarification Layer attribution: identity / context / protocol / capability / runtime

Detailed identification rules and examples: read references/signal-types.md

Record:

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

When the user says "remember this", "don't do this again", etc., it is recommended to record it as a signal promptly.

---

2. Trajectory Storage

Two kinds of trajectories:

• Golden: did it right → evolution-data/trajectories/golden/
• Correction: did it wrong → correction → evolution-data/trajectories/corrections/

Storage format and templates: read references/trajectory-templates.md

Before executing a task, retrieve the relevant correction trajectory and proactively restate the correction points.

---

3. Gate Check

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

Automatic trigger conditions (any one met):

• ≥5 correction/negative/clarification signals
• ≥3 high severity signals
• ≥3 signals in the same layer
• ≥7 days without evolution and there are new signals

Constraints: 24h cooldown + saturation detection. Manual trigger:/evolve skips Gate.

---

4. Evolution Analysis (/evolve)

Recommended process: all evolution changes are executed through the orchestrator pipeline to ensure DB state and changes are traceable.

• It is not recommended for the agent to directly modify workspace files after analyzing signals on its own
• It is not recommended to skip the DB recording step (Python sqlite3 is a standard library built-in module, no additional tools required)
• Standard process：orchestrator.py timer-review → generate proposal JSON → ingest_outputs write to DB → user confirmation → apply-proposal apply changes
• Reason: bypassing DB recording will result in no data in the Dashboard, untraceable changes, and a broken verification process

Orchestration commands

# /evolve 手动触发（跳过 Gate，≥1 信号即可，完整 7 步）：
python skills/byted-ark-evolve/scripts/orchestrator.py timer-review --skip-gate --worker-mode agent

# Gate 自动触发（阈值达标时）：
python skills/byted-ark-evolve/scripts/orchestrator.py timer-review --worker-mode agent

# session 开始时自动检查：
python skills/byted-ark-evolve/scripts/orchestrator.py session-start

# 用户确认提案后应用：
python skills/byted-ark-evolve/scripts/orchestrator.py apply-proposal --group <proposal_group_id>

Notes:

• --worker-mode agent: actually calls openclaw agent --local to complete review worker analysis
• --worker-mode mock: used for stable local testing, does not depend on model calls
• The orchestrator will generate pending-evolution.json / daily-digest.json, but DB is still the primary source of state

Gene Integration (v0.3.1, local static library)

Gene is the standardized template library for mutation. This version ships the static library with the skill package references/gene-library.json，No cloud calls。

Boundaries:

• Gene Is not an analyzer, not responsible for root cause attribution
• Gene Is not an executor, does not directly modify any files
• Gene Is not a local rule matcher, local scripts are not responsible for determining gene relevance

Division of responsibilities:

• Agent / subagent: reads signals, logs, and trajectories, completes attribution analysis
• Gene static library: provides mutation template candidates (id / summary / pattern_key / rule_text)
• Evolution skill: orchestrates load → Agent judges gene candidates → generates mutation → user confirmation → execute

When to call Gene

The following scenarios must enter the Gene flow:

1. /evolve After manual triggering, enter Step 2.5 Gene candidate screening after Step 2 attribution is complete
2. After auto-evolution triggering, enter Step 2.5 before mutation design
3. When the user says "remember this pattern / do it this way next time", prioritize browsing the gene library to determine whether a reusable template already exists

Gene commands

python skills/byted-ark-evolve/scripts/gene.py --list
python skills/byted-ark-evolve/scripts/gene.py --show <gene_id>
python skills/byted-ark-evolve/scripts/gene.py --summary

Rules:

• The library is released with the skill version (updates require upgrading the skill version), there is no --fetch command
• In Step 2.5, the Agent reads the signal + attribution + gene content and determines "which gene solutions, if applied in advance, could prevent the current negative feedback or error from happening again"
• In Step 3, the Agent generates a mutation proposal based on the selected gene template

Detailed flow (Steps 0-7, including Step 2.5 Gene candidate screening): read references/evolution-steps.md

Overview: snapshot Diff → scan signals → trajectory clustering (Skill candidate detection) → attribution analysis → Gene candidate screening (static library + Agent judgment) → design Mutation → user confirmation → assemble JSON + render report/Dashboard → output evolution summary → mark as processed → update snapshot

Trajectory → Skill emergence (Step 1.5)

During evolution analysis, automatically detect extractable patterns in trajectories:

• Same type of Golden trajectories ≥3 → suggest extracting as an independent skill
• Same cause of Correction trajectories ≥2 → suggest adding a guard rule

Flow: detect → present candidates to the user → user confirmation → call skill-creator to generate. If the user has not installed skill-creator, prompt to install it.

User confirmation interaction specification

After designing the mutation,the proposal must first be presented to the user for confirmation; no writes may be executed before confirmation。

Display format (list item by item):

### 进化方案（共 N 条变更）

1. 📝 [AGENTS.md] — 新增「中文编码规范」
   - 层归因：Protocol
   - 变更类型：追加（user-owned 文件，仅允许追加）
   - 帕累托检查：✅ 通过
   - 摘要：在末尾新增 section，规定中文 API 调用使用 Python

2. 📝 [SOUL.md] — 修改「任务执行流程」
   - 层归因：Identity
   - 变更类型：修改（evolvable 文件）
   - 帕累托检查：✅ 通过
   - Before: 「直接执行用户指令」
   - After:  「先检索相关 correction，再执行」

以上 N 条变更是否执行？你可以：
- 全部接受
- 全部拒绝
- 逐条选择（如"接受 1，拒绝 2"）

Key rules:

• Each mutation must list the target file, change type, and Pareto result
• user-owned files are specially marked as "append-only"
• Before the user explicitly replies, do not execute any write operation
• Rejected mutations are marked as rejected, and the record is retained

Evolution completion summary

After the report is generated, directly output a passage in the conversationnatural language summary(not a file path, but a summary the user can directly understand):

本次进化处理了 X 条反馈，产生 Y 条待处理提案/变更：
- [AGENTS.md] 新增了「中文编码规范」— 因为你 4 次提到不要用 curl 发中文
- [SOUL.md] 调整了任务执行流程 — 增加了执行前检索修正记录的步骤

被拒绝：W 条
完整报告：evolution-data/reports/evolution-<date>.html

下一步：当你再次遇到相关场景时，我会观察这些改进是否生效。

Rules:

• Use natural language, not terminology (do not say mutation / signal / layer)
• For each change, explain "what was changed" + "why it was changed"
• Inform the report path, but do not use the path as the main output
• Mention the follow-up verification plan

For attribution, refer to references/layer-model.md + evolution-data/file-registry.json For writing, refer to file-registry.json write_policy in (evolvable→section-edit / user-owned→append-only) For Pareto checks, refer to references/pareto-rules.md

Report generation flow (template method)

1. Assemble the report data as JSON (refer to references/report-schema-example.json）
2. write evolution-data/reports/evolution-<date>.json
3. call python scripts/report-render.py <json> --output <html> to render HTML
4. (optional) assemble Dashboard JSON (refer to references/dashboard-schema-example.json）→ dashboard-render.py

The Agent is only responsible for filling in pure data JSON; the Python script is responsible for all conditional rendering logic (such as: whether there are rejected changes, whether it is saturated, display of high-severity signals, etc.).

---

Pending Proposal Lifecycle (v0.2.2)

pending-evolution.json The positioning ofis a pending proposal queue for humans to view, not a "dedicated reminder for the next morning."

Rules:

• The nighttime timer review only generates proposals and does not automatically apply
• As long as the proposal is still valid and has not been handled by the user, any subsequent session_start should be able to display it again
• Display state and decision state are separated:pending -> presented -> accepted/rejected/stale/superseded
• pending-evolution.json / daily-digest.json is the export layer;the DB is the primary source of state

Recommended command:

python skills/byted-ark-evolve/scripts/pending-evolution.py export
python skills/byted-ark-evolve/scripts/pending-evolution.py show
python skills/byted-ark-evolve/scripts/pending-evolution.py present --group <proposal_group_id>
python skills/byted-ark-evolve/scripts/pending-evolution.py decide --group <proposal_group_id> --decision accepted
python skills/byted-ark-evolve/scripts/pending-evolution.py stale --older-than-hours 72

V. Verification

Verification status: pending verification → observed → verified / recurred / partially effective

Status description:

• Pending verification: just proposed, waiting to be verified in real scenarios
• Observed: initially passed once, but cannot be fully trusted
• Verified: no recurrence across ≥3 sessions, confirming behavior change
• Recurred: violated again after verification, needs reinforcement
• Partially effective: effective in some scenarios, not covered in others

Detailed rules and credit weights: read references/pareto-rules.md verification standard section

---

VI. Quick Commands

User says	Agent does
/evolve	Execute orchestrator.py timer-review --skip-gate --worker-mode agent, complete 7-step evolution (≥1 signal is enough, not subject to Gate threshold and cooldown restrictions)
/evolve init	Execute on first installation: initialization scan + generate file registry
/evolve scan	Scan historical conversations and extract existing feedback signals
/evolve detect	Batch detect signal candidates in historical conversations (scan-history.py detect）
/evolve dashboard	Generate and open Dashboard (dashboard-render.py → evolution-data/dashboard.html）
/evolve help	Display beginner guidance (read references/onboarding.md）
"Remember this pattern"	Record a positive signal as a positive reference for subsequent evolution analysis
"Don't do this from now on"	Record a correction signal, marking behavior that needs improvement
"Evolution status"	Quick view:query.py dashboard(text); full page: assemble JSON → dashboard-render.py（HTML）
"gene list / gene overview"	Call gene.py --list / gene.py --summary
"Evolution report"	Assemble JSON (refer to references/report-schema-example.json）→ report-render.py

---

VII. Query Tools

python skills/byted-ark-evolve/scripts/query.py dashboard          # Dashboard
python skills/byted-ark-evolve/scripts/query.py signals --unprocessed  # 未处理信号
python skills/byted-ark-evolve/scripts/query.py signals --layer protocol  # 按层
python skills/byted-ark-evolve/scripts/query.py mutations --status pending  # 变异
python skills/byted-ark-evolve/scripts/query.py mutations --source user-direct  # 用户直接变更
python skills/byted-ark-evolve/scripts/query.py trajectories       # 轨迹统计
python skills/byted-ark-evolve/scripts/query.py gene-matches       # 最近一次 gene 候选筛选结果

# 信号候选检测（v0.2.9 新增）
python skills/byted-ark-evolve/scripts/scan-history.py detect --days 7            # 检测近 7 天对话中的信号候选
python skills/byted-ark-evolve/scripts/scan-history.py detect --min-confidence high  # 仅高置信候选

Apply Closed Loop (v0.2.4)

After the user accepts a proposal, it is recommended to complete the application through the following command to ensure git commit / snapshot / dashboard are updated synchronously.

python skills/byted-ark-evolve/scripts/apply-proposal.py --group <proposal_group_id>

This command automatically completes all closed-loop operations:

1. Apply the mutations under that group to the target file
2. Execute git commit (one commit per proposal_group)
3. Call snapshot save
4. Write review/result back to the DB
5. Regenerate dashboard.html

It can also be called through the orchestrator (same effect):

python skills/byted-ark-evolve/scripts/orchestrator.py apply-proposal --group <proposal_group_id>

Dashboard Fixed Template (v0.2.5+)

Dashboard adoptstemplate and data separationArchitecture, ensuring the styles are fixed and unaffected by the model.

Architecture

File	Responsibility	Update Method
scripts/dashboard-template.html	Fixed HTML/CSS/JS template	Manual iteration by developers only
scripts/dashboard-render.py	Query DB + references/gene-library.json → JSON → inject into template	Automatically called by orchestrator
evolution-data/dashboard.html	Final output, opened by the user in a browser	Automatically generated on each pipeline run

Usage

# 手动生成
python skills/byted-ark-evolve/scripts/dashboard-render.py --db evolution-data/evolution.db --data-dir evolution-data/

# 自动生成（timer-review / apply-proposal 完成后自动触发）

Three Tabs

• Overview: Global statistics, trend charts, change verification, layer distribution
• Activity: Date picker + single evolution report details (source feedback, change diff, status)
• Genes: Gene table + accordion expansion of related changes