# NanoClaw v1 → v2 — 变更内容

NanoClaw v1（你一直在运行的 `~/nanoclaw` 检出）与 v2（本次重写）之间的宏观差异。这不是迁移指南——那是 `bash migrate-v2.sh` 和 `/migrate-from-v1` 技能的角色。本文档是**词汇表**：当某些东西被移动或重命名时，在这里找到它。

在接触迁移代码或将定制向前移植之前，请阅读本文档。

---

## 一句话总结

v1 是一个 Node 进程，带有一个 SQLite 文件和原生频道适配器。v2 是一个生成每个 session（会话）Docker 容器的宿主机，将状态拆分到中央库 + 每个 session 的 DB 对中，通过显式实体模型路由，并将频道作为技能从兄弟分支安装。

---

## 实体模型——最大的变化

**v1：** 一张扁平的 `registered_groups(jid, name, folder, trigger_pattern, requires_trigger, is_main, channel_name)` 表。一个 group 目录是 agent 身份的单位。一个聊天（JID）连接到恰好一个目录，`trigger_pattern` 是路由器应用于每条入站消息的不透明正则表达式。

**v2：** 三张表，中间有一个有意的多对多关系：

```
agent_groups  ─┐
                ├─ messaging_group_agents ─┬─ messaging_groups
                │   (engage_mode,          │   (channel_type,
                │    engage_pattern,       │    platform_id,
                │    sender_scope,         │    unknown_sender_policy)
                │    ignored_message_policy,
                │    session_mode, priority)
```

后果：

- **一个 agent 可以在多个聊天上应答，一个聊天可以扇出到多个 agent。** v1 两者都做不到。
- **没有 `is_main` 标志。** 权限现在通过 `user_roles`（owner/admin，全局或限定范围）显式化。见下文。
- **没有 `trigger_pattern` 正则表达式。** 替换为四个正交列。自动迁移和 `/migrate-from-v1` 技能使用的映射规则：
  - v1 `trigger_pattern` 非空 → v2 `engage_mode='pattern'`、`engage_pattern = <the regex>`
  - v1 `requires_trigger=0` 或 pattern 为 `.`/`.*` → v2 `engage_mode='pattern'`、`engage_pattern='.'`（"始终"变体）
  - 无 pattern 且需要触发器 → v2 `engage_mode='mention'`
  - `sender_scope` 和 `ignored_message_policy` 是新的；默认值 `all` / `drop`
- **JID 分解。** v1 的 `jid` 列存储 `dc:12345` / `tg:67890`。v2 将其拆分为 `channel_type` + `platform_id`。具体来说：`dc:12345` 变为 `channel_type='discord'`、`platform_id='discord:12345'`。前缀别名（`dc` → `discord`、`tg` → `telegram`、`wa` → `whatsapp`）在 `setup/migrate-v2/shared.ts` 中。
- **v1 中 `channel_name` 不可靠。** 许多行的该列为空；实际频道只能从 JID 前缀猜测。v2 的 `channel_type` 始终是显式的。

---

## 中央库 vs. Session DB

**v1：** 一个 SQLite 文件位于 `store/messages.db`。每个聊天、消息、注册 group、计划任务和 session 都存在那里。宿主机和任何 agent 进程都打开同一个文件。

**v2：** 三种 DB 形态。

1. `data/v2.db`——**中央库**。所有非 per-session 的东西：users、roles、agent groups、messaging groups、连线、pending approvals、user DMs、schema 迁移。
2. `data/v2-sessions/<session_id>/inbound.db`——**宿主机写入，容器读取**。`messages_in`、路由、destinations、pending questions、processing_ack。计划任务存于此处（见"调度"）。
3. `data/v2-sessions/<session_id>/outbound.db`——**容器写入，宿主机读取**。`messages_out`、session_state。

每个文件有且仅有一个写入者。无跨挂载锁竞争。心跳是对 `/workspace/.heartbeat` 的文件 touch，而非 DB 更新。宿主机使用偶数 `seq` 号，容器使用奇数。

消息历史（v1 `messages` 表、v1 `chats` 表）**不被迁移**。迁移将运行上重要的状态向前复制（agent、频道、连线、计划任务、group 目录），留下聊天日志。

---

## 调度

**v1：** 在 `store/messages.db` 中有专门的 `scheduled_tasks` 表，拥有自己的列（`schedule_type`、`schedule_value`、`next_run`、`last_run`、`context_mode`、`script`、`status`）。一个独立的类似 cron 的调度进程从中读取。

**v2：** 计划任务是 session `inbound.db` 中带有 `kind='task'` 的 **`messages_in` 行**。相关列：
- `process_after`（ISO8601）——宿主机 sweep 在 `datetime(process_after) <= datetime('now')` 时唤醒容器
- `recurrence`——cron 字符串；`NULL` = 单次执行
- `series_id`——将重复事件分组；首次插入时设置为 task id
- `status`——`pending` | `processing` | `completed` | `failed` | `paused`

公共 API 是 `src/modules/scheduling/db.ts` 中的 `insertTask()`。重复执行通过 `cron-parser` 在用户时区计算（见 `src/modules/scheduling/recurrence.ts`）。迁移将 v1 的 `schedule_type`+`schedule_value` 对映射为单个 cron 字符串，然后调用 `insertTask()`。

任务可以在 session 唤醒之前存在——宿主机 sweep 在首次到期时创建/唤醒容器。

---

## 凭据

**v1：** `.env`——明文环境变量。`DISCORD_BOT_TOKEN`、`ANTHROPIC_API_KEY` 等。宿主机直接读取它们并传递给任何需要它们的代码。

**v2：** OneCLI Agent Vault。一个位于 `http://127.0.0.1:10254` 的独立本地服务持有秘密。Agent 被*限定*到特定秘密，vault 在批准后将它们注入到离开容器的 API 请求中。容器永远看不到原始秘密值。

注意：自动创建的 agent 默认为 `selective` 秘密模式——没有附加秘密，即使匹配的秘密存在于 vault 中。关于修复方案（`onecli agents set-secret-mode --mode all`），见根 CLAUDE.md 中"auto-created agents start in selective secret mode"部分。

**自动迁移做了什么：** 将每个 v1 `.env` 键逐字复制到 v2 `.env`，永不覆盖现有的 v2 键。OneCLI vault 迁移是一个单独的步骤，由 `/init-onecli` 技能处理，该技能知道如何从 `.env` 中拉取。

---

## 频道适配器

**v1：** 在 `src/channels/` 中导入的原生适配器（例如直接使用 `discord.js`）。安装一个频道意味着编辑代码、添加依赖并设置环境变量。

**v2：** 频道适配器存在于兄弟 `channels` 分支上。每个 `/add-<channel>` 技能：
1. `git fetch origin channels`
2. `git show channels:src/channels/<name>.ts > src/channels/<name>.ts`
3. 将 `import './<name>.js';` 追加到 `src/channels/index.ts`
4. `pnpm install @chat-adapter/<name>@<pinned>`
5. `pnpm run build`

幂等——重新运行为无操作。固定版本保持供应链诚信。自动迁移检测 v1 中哪些频道已被连接（通过不同的 `channel_name` / JID 前缀），并为每个频道运行匹配的 `setup/install-<channel>.sh`。v1 中没有 v2 技能的频道（目前少见，随着 v2 的完善将更常见）被记录在交接文件中，由 `/migrate-from-v1` 技能向用户提出。

**`.env` 之外的频道认证。** 某些频道在磁盘上存储 session 状态（Baileys WhatsApp 密钥库、Matrix 同步状态、iMessage tokens）。`channel-auth` 步骤有一个按频道的注册表（`setup/migrate-v2/shared.ts: CHANNEL_AUTH_REGISTRY`），知道除了 env 键之外还要复制哪些文件 glob。

---

## 权限——从隐式到显式

**v1：** `registered_groups.is_main = 1` 标记一个 group 为特权级别。没有 `users` 表。权限是约定而非强制执行。

**v2：** 显式表。
- `users(id = "<channel_type>:<handle>", kind, display_name)`——每个消息平台标识符一行
- `user_roles(user_id, role ∈ {owner, admin}, agent_group_id nullable, granted_by, granted_at)`——owner 始终全局；admin 可以是全局或限定范围
- `agent_group_members(user_id, agent_group_id, ...)`——用于 `sender_scope='known'` 关卡的"已知"成员资格

Owner 在 `/migrate-from-v1` 技能的访谈阶段（"哪个 handle 是你？"）被种子。自动迁移不会猜测——v1 没有这方面的真源。

**默认访问——"任何人都可以与 bot 通话" vs "仅已知用户"。** v1 隐式存储（通过触发器 regex + `is_main`）。v2 通过 `messaging_groups.unknown_sender_policy ∈ {'strict', 'request_approval', 'public'}` 暴露它。技能询问用户 v1 以哪种模式运行，并相应地翻转已迁移的 messaging group。

---

## 磁盘上的 Group 目录

**v1：** `groups/<folder>/CLAUDE.md` 和可选的 `logs/`。`CLAUDE.md` 是一个纯指令文件，group 特定。

**v2：** 每个 group 仍然位于 `groups/<folder>/`，但形态更丰富：
- `CLAUDE.md`——**在容器启动时组合**，来自 `.claude-shared.md`（到全局的 symlink）+ `.claude-fragments/*.md`（模块片段）+ `CLAUDE.local.md`。**不要直接编辑 `CLAUDE.md`。**
- `CLAUDE.local.md`——每个 group 的内容。迁移将 v1 的旧 `CLAUDE.md` 写到这里。
- `container.json`——可选的每个 group 的容器配置（apt 依赖、env、挂载）。v1 的 `registered_groups.container_config` JSON 接近但不完全相同——迁移将 v1 的 payload 存储在 `groups/<folder>/.v1-container-config.json` 中供技能协调，而不是静默映射。
- `.claude-fragments/` 和 `.claude-shared.md` 在宿主机首次接触到该 group 时由 `initGroupFilesystem()` 安装，因此迁移只需写入 `CLAUDE.local.md`，将脚手架工作留给宿主机。

---

## 宿主机进程 vs. 容器

**v1：** 单个 Node 进程。"Agent"与路由器是同一个进程。

**v2：** 顶层的 Node 宿主机，每个 session 一个 Bun 运行时的 Docker 容器。它们仅通过两个 session DB 通信。无共享模块，无 IPC，无 stdin 管道。如果你编写了从 agent 进入宿主机内部（或反之）的自定义代码，那个接口已不复存在——移植它是 `/migrate-from-v1` 技能的话题，而非机械复制。

锁文件：宿主机使用 `pnpm-lock.yaml`，agent-runner 使用 `bun.lock`。宿主机侧 `minimumReleaseAge: 4320`（3 天供应链等待）；agent-runner 没有发布年龄限制。

---

## 自我修改和 MCP 工具

**v1：** 如果你添加了 MCP 服务器或自我修改管道，通常是直接编辑长期运行的进程。

**v2：**
- MCP 服务器通过 `container/agent-runner/src/mcp-tools/*.ts` 注册并按 session 加载。还有 `install_packages` 和 `add_mcp_server` 自我修改工具，在重建容器镜像之前经过管理员审批流程（`src/modules/self-mod/apply.ts`）。
- 你在 v1 中编写的自定义 MCP 工具可以清晰地映射到 v2 的工具注册表，但导入路径、运行时（Bun vs Node）和 SQL 辅助函数差异（`bun:sqlite` 使用 `$name` 前缀的参数）可能需要调整。技能将引导你完成这些。

---

## 已消失或无法映射的内容

- **`scheduled_tasks` 作为一个单独的表的模式**——已移入 session `inbound.db` 的 `kind='task'` 下。迁移移植活跃行；非活跃/已完成的行导出到 `logs/setup-migration/inactive-tasks.json` 供参考。
- **`messages` / `chats` 表（聊天历史）**——不迁移。如需要，保留在 v1 检出中。
- **`router_state`（键/值）**——不迁移。v2 状态存于上述显式表中。
- **`sessions`（v1 group→session_id）**——v1 session 不映射；v2 session 以 `(agent_group_id, messaging_group_id, thread_id)` 为键并按需创建。
- **对旧 `store/messages.db` 的原始访问**——v1 DB 被保留在原位且不被触碰。如果迁移出错可以重新运行（对于 agent/频道/连线，迁移子步是幂等的；目录使用 rsync 语义）。

---

## 迁移范围——代码所在位置

- `migrate-v2.sh`——入口点：从 v2 检出运行 `bash migrate-v2.sh`。
- `setup/migrate-v2/*.ts`——各个迁移步骤（env、db、groups、sessions、tasks、channel-auth、select-channels、switchover-prompt）。
- `setup/migrate-v2/shared.ts`——JID 解析、触发器映射、频道认证注册表。
- `logs/setup-migration/handoff.json`——由 `migrate-v2.sh` 写入，由 `/migrate-from-v1` 技能读取。
- `logs/migrate-steps/*.log`——每个步骤的原始 stdout。
- `.claude/skills/migrate-from-v1/SKILL.md`——用于 owner 种子、CLAUDE.md 清理、容器配置验证、fork 移植的 Claude 技能。
- `migrate-v2-reset.sh`——开发辅助工具，清除 v2 状态以重新测试。
- 完整开发指南见 [docs/migration-dev.md](migration-dev.md)。