byted-ark-evolve

Files (41)

• LICENSE
• README.md
• SKILL.md
• dashboard-schema-example.json · references/
• evolution-steps.md · references/
• file-semantic-map.md · references/
• gene-contract.md · references/
• gene-library.json · references/
• init-rules.md · references/
• layer-model.md · references/
• onboarding.md · references/
• pareto-rules.md · references/
• pending-proposal-lifecycle.md · references/
• report-schema-example.json · references/
• signal-types.md · references/
• trajectory-templates.md · references/
• _workspace.py · scripts/
• apply-proposal.py · scripts/
• dashboard-render.py · scripts/
• dashboard-template.html · scripts/
• db-init.py · scripts/
• db-migrate-source.py · scripts/
• db-migrate-v031.py · scripts/
• detect-signal.py · scripts/
• gate-check.py · scripts/
• gene.py · scripts/
• orchestrator.py · scripts/
• pending-evolution.py · scripts/
• query.py · scripts/
• report-gen.py · scripts/
• report-render.py · scripts/
• scan-history.py · scripts/
• signal-record.py · scripts/
• snapshot.py · scripts/
• track-change.py · scripts/
• trajectory-skill-check.py · scripts/
• workspace-init.py · scripts/
• README.md · test-conversations/
• conversation-1-research-before-asking.md · test-conversations/
• conversation-2-memory-access-boundary.md · test-conversations/
• conversation-3-report-usability.md · test-conversations/

SKILL.md (first lines)

# 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 — 初始化扫描（涉及文件写入，需用户确认）**

```bash
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 完成后，提供历史对话扫描选项：

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

展示给用户：

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples