evolve

name	evolve
description	读取 memex 发来的变更通知（GitHub issue 或本地文档），自动分析本 wiki 中需要更新的内容并应用变更。最常见场景：memex 完成架构调整后向各子 wiki 推送同步通知，/evolve 在子 wiki 中执行变更并提交。

/evolve — 自动应用 memex 变更通知

用途

memex 主库完成某项架构变更后，会向各子 wiki 创建通知 issue（如路径重命名、术语更新、规范调整）。在子 wiki 中运行 /evolve 即可自动读取通知、扫描受影响内容、应用变更并提交。

也可用于读取任意本地文档中的变更指令并执行。

---

参数形式

参数	含义
/evolve	无参数：自动查找本 repo GitHub issues 中最新的未关闭 memex 通知（标题含 [通知] 或 [memex]）
/evolve <N>	本 repo 的 issue #N
/evolve <URL>	任意 GitHub issue URL（跨 repo 也支持）
/evolve <文件路径>	读取本地 .md 文件中的变更指令

---

执行流程

Step 0 — 识别当前 wiki 环境

# 获取当前 wiki 名（用于过滤和日志）
WIKI_NAME=$(basename $(git rev-parse --show-toplevel))
WIKI_ROOT=$(git rev-parse --show-toplevel)
WIKI_REMOTE=$(git remote get-url origin 2>/dev/null)

记录：wiki=$WIKI_NAME，后续所有操作均在此目录下执行。

---

Step 1 — 读取变更通知

无参数时：自动发现

gh issue list --repo "$CURRENT_REPO" --state open \
  --json number,title,createdAt \
  | python3 -c "
import json, sys
issues = json.load(sys.stdin)
notify = [i for i in issues if '[通知]' in i['title'] or '[memex]' in i['title']]
if not notify:
    print('NO_NOTIFY')
else:
    notify.sort(key=lambda x: x['number'])
    print(notify[0]['number'])
"

若无待处理通知，输出"当前无待处理 memex 通知 issue"，结束。

参数为 issue 编号或 URL：

# 编号：gh issue view <N> --repo <当前 repo>
# URL：gh issue view <URL>

提取 issue 正文全文。

参数为本地文件：

直接 Read 文件内容。

---

Step 2 — 解析变更指令

从通知正文中提取结构化变更：

2-A 路径重命名

识别形如：

`旧路径/` → `新路径/`
旧路径/ → 新路径/
old/path/ → new/path/

构建重命名映射表：[(旧路径, 新路径), ...]

2-B 文本替换

识别形如：

旧术语 → 新术语
`旧字符串` → `新字符串`
s/旧/新/g

构建替换规则列表：[(旧, 新), ...]

2-C 文件操作

识别需要新增/删除/移动的文件（如 git mv、创建新文件、追加内容等）。

2-D 排除范围

识别通知中声明的"保留原文"文件（如历史 RFC 文件），加入排除列表。

若无法从通知提取任何结构化变更，在屏幕说明"无法解析明确的变更指令"，展示通知原文摘要，询问用户手动确认变更内容后继续。

---

Step 3 — 扫描影响范围

对当前 wiki 执行 dry-run 扫描，找出所有受影响文件：

# 扫描文本替换影响范围
for (旧, 新) in 替换规则:
    grep -rn "旧" . --include="*.md" --include="*.py" --include="*.sh" \
      --include="*.json" --include="*.yaml" | grep -v ".git"

输出预览（必须在应用前展示）：

=== /evolve 变更预览 ===
Wiki: <wiki_name>
来源: issue #N / <文件路径>

【路径重命名】
  skills/atomic/ → skills/gene/（影响 N 个文件）

【文本替换】
  "原子动作" → "基因"（N 处，X 个文件）
  "skills/atomic/" → "skills/gene/"（N 处，X 个文件）

【排除文件】
  ref/rfc/rfc-<wiki>-000X-*.md（历史文件，保留原文）

【受影响文件列表（前 10）】
  - BIRTH.md（3 处）
  - wiki/scripts/assign_pn.py（1 处）
  ...

确认应用以上变更？(y/n)

等待用户确认后继续。若影响范围为 0，告知"本 wiki 无需更新"，结束。

---

Step 4 — 应用变更

按以下顺序执行：

4-A git mv（路径重命名）

# 仅当本 wiki 存在旧路径时执行
for (旧路径, 新路径) in 重命名映射:
    if [ -e "旧路径" ]; then
        git mv "旧路径" "新路径"
    fi

4-B 全局文本替换

# 排除 .git/ 和声明保留的文件
受影响文件列表 | xargs sed -i 替换规则...

替换顺序：先长串、再短串（避免前缀冲突）。

4-C 特殊操作

按通知中的额外指令执行（如向某节追加内容、更新字段值等）。

每步完成后输出进度：✅ 完成：<操作描述>

---

Step 5 — 验证

# 验证旧术语/路径已清零（排除历史文件）
for (旧, 新) in 替换规则:
    count=$(grep -rn "旧" . --include="*.md" --include="*.py" \
      | grep -v ".git" | grep -v 排除文件 | wc -l)
    if [ $count -gt 0 ]; then
        echo "⚠️ 仍有 $count 处未替换，列出位置"
    fi

若有残留，列出文件和行号，询问用户是否手动处理后继续。

---

Step 6 — 写执行报告

在 logs/evolve/ 下写入本次执行的报告文件。

文件路径：logs/evolve/YYYY-MM-DD-<来源slug>.md

• 日期取执行当日
• <来源slug>：issue 编号（如 issue-1）或文件名去扩展名（如 migration-notes）

报告格式：

# evolve 执行报告：<通知标题>

- **日期**: YYYY-MM-DD
- **Wiki**: <wiki_name>
- **来源**: <issue URL 或文件路径>
- **执行结果**: success | partial | skipped

---

## 变更摘要

| 类型 | 内容 | 处数 | 文件数 |
|------|------|------|--------|
| 路径重命名 | `旧路径/` → `新路径/` | — | N |
| 文本替换 | "旧术语" → "新术语" | N | N |
| ... | | | |

## 受影响文件

- `BIRTH.md`（3 处）
- `wiki/scripts/assign_pn.py`（1 处）

## 验证结果

- [x] "旧术语" 残留：0 处
- [x] `旧路径/` 残留：0 处

## 残留问题（若有）

> 若验证步骤发现有残留，在此列出文件和行号。若无，此节删除。

## Commit

`<commit SHA>`

## 备注

> 可选：记录执行中遇到的特殊情况、人工干预、跳过原因等。

结果码说明：

• success：所有变更完整应用，验证清零
• partial：有残留或跳过部分变更（须填写"残留问题"节）
• skipped：本 wiki 无需更新（影响范围为 0）

---

Step 7 — 提交

git add <所有变更文件> logs/evolve/YYYY-MM-DD-<来源slug>.md
bash wiki/scripts/skill_commit.sh -m "evolve: 同步 memex 变更——<通知标题简述>

来源: <issue URL 或文件路径>
变更: <1-2 句话描述>
日志: logs/evolve/YYYY-MM-DD-<来源slug>.md

Co-Authored-By: Claude Sonnet 4.6 <[e-mail]>"

---

Step 8 — 回应通知（可选）

若变更来源为 GitHub issue，在 issue 留回复：

✅ <wiki_name> 已同步（commit: <SHA>）

变更摘要：
- BIRTH.md：3 处路径引用更新
- wiki/scripts/assign_pn.py：注释更新

执行报告：logs/evolve/YYYY-MM-DD-<来源slug>.md

若通知 issue 来自本 wiki repo，询问用户是否关闭该 issue。

---

铁律

• Step 3 的预览是强制的：在用户确认前绝不写入任何文件
• 不写入 memex：当前 wiki 非 memex 时，绝不修改 $MEMEX_ROOT 下任何文件
• 历史文件保留：RFC 历史文件（ref/rfc/rfc-*-000*.md）默认加入排除列表，除非通知明确说明要更改
• 范围最小化：只替换通知明确指定的内容，不做超出范围的"顺手"修改
• 无结构化指令时停止：无法从通知中解析出明确的变更规则时，展示原文并等待用户指示，不猜测

---

典型场景示例

场景 A：memex 路径重命名通知

memex 在 aima repo 创建 issue："skills/atomic/ → skills/gene/ 路径变更"

在 aima 中运行：

/evolve 1

执行流程：

1. 读取 issue #1
2. 解析：路径重命名 skills/atomic/ → skills/gene/，文本替换"原子动作"→"基因"
3. 扫描：BIRTH.md（3处），assign_pn.py（1处）
4. 展示预览，确认
5. 应用替换，验证，提交
6. 在 issue #1 留回复

场景 B：本地变更文档

/evolve ref/spec/migration-notes.md

读取本地迁移文档，按其中的变更指令在当前 wiki 执行。

场景 C：跨 repo issue

/evolve https://github.com/baojie/memex/issues/58

直接读取 memex repo 的 issue，解析并在当前 wiki 应用相关变更。