添加中文文档
This commit is contained in:
139
docs/zh/migration-dev.md
Normal file
139
docs/zh/migration-dev.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# v1 → v2 迁移 — 开发指南
|
||||
|
||||
如何测试、开发和调试迁移流程。
|
||||
|
||||
## 快速入门
|
||||
|
||||
```bash
|
||||
# 完整周期：重置 → 迁移 → Claude 完成
|
||||
bash migrate-v2-reset.sh && bash migrate-v2.sh
|
||||
```
|
||||
|
||||
## 架构
|
||||
|
||||
两部分迁移：
|
||||
|
||||
1. **`migrate-v2.sh`**——确定性 bash 脚本。处理前提条件、DB 种子、文件拷贝、频道安装、容器构建、服务切换。写入 `logs/setup-migration/handoff.json`，然后 `exec` 到 Claude 中。
|
||||
|
||||
2. **`/migrate-from-v1` 技能**——由 Claude 驱动。读取交接文件，种子 owner/roles，清理 CLAUDE.local.md，验证容器配置，移植 fork 定制。
|
||||
|
||||
## 文件布局
|
||||
|
||||
```
|
||||
migrate-v2.sh # 入口点
|
||||
migrate-v2-reset.sh # 清除 v2 状态以重新测试
|
||||
setup/migrate-v2/
|
||||
env.ts # 阶段 1a：合并 .env
|
||||
db.ts # 阶段 1b：种子 v2 DB
|
||||
groups.ts # 阶段 1c：拷贝 group 目录 + container.json
|
||||
sessions.ts # 阶段 1d：拷贝 session 并设置续接
|
||||
tasks.ts # 阶段 1e：移植计划任务
|
||||
channel-auth.ts # 阶段 2b：拷贝频道认证状态
|
||||
select-channels.ts # 阶段 2a：clack 多选
|
||||
switchover-prompt.ts # 服务切换提示
|
||||
setup/migrate-v2/shared.ts # 共享辅助函数（JID 解析、触发器映射等）
|
||||
.claude/skills/migrate-from-v1/ # Claude 技能
|
||||
logs/setup-migration/handoff.json # 由 migrate-v2.sh 写入，由技能读取
|
||||
logs/migrate-steps/*.log # 每个步骤的原始输出
|
||||
```
|
||||
|
||||
## 开发循环
|
||||
|
||||
```bash
|
||||
# 重置 v2 到干净状态（保留 node_modules）
|
||||
bash migrate-v2-reset.sh
|
||||
|
||||
# 以非交互式频道选择运行迁移
|
||||
NANOCLAW_CHANNELS="telegram" bash migrate-v2.sh
|
||||
|
||||
# 或以交互方式运行（clack 多选）
|
||||
bash migrate-v2.sh
|
||||
```
|
||||
|
||||
`migrate-v2-reset.sh` 清除：`data/`、`logs/`、`.env`、`groups/`（恢复 git 跟踪的）、`container/skills/`（恢复 git 跟踪的）、`src/channels/`（恢复 git 跟踪的）。
|
||||
|
||||
它**不**清除 `node_modules/`（重新安装成本高昂）。
|
||||
|
||||
## 测试单个步骤
|
||||
|
||||
每个步骤是一个独立的 TypeScript 文件：
|
||||
|
||||
```bash
|
||||
# 运行单个步骤（在 pnpm install 之后）
|
||||
pnpm exec tsx setup/migrate-v2/env.ts /path/to/v1
|
||||
pnpm exec tsx setup/migrate-v2/db.ts /path/to/v1
|
||||
pnpm exec tsx setup/migrate-v2/groups.ts /path/to/v1
|
||||
pnpm exec tsx setup/migrate-v2/sessions.ts /path/to/v1
|
||||
pnpm exec tsx setup/migrate-v2/tasks.ts /path/to/v1
|
||||
pnpm exec tsx setup/migrate-v2/channel-auth.ts /path/to/v1 telegram discord
|
||||
```
|
||||
|
||||
每个步骤向 stdout 打印 `OK:<details>`、`SKIPPED:<reason>` 或错误。成功/跳过时退出 0，失败时退出非零值。
|
||||
|
||||
## 调试
|
||||
|
||||
### 检查已迁移的内容
|
||||
|
||||
```bash
|
||||
# Agent groups
|
||||
sqlite3 data/v2.db "SELECT * FROM agent_groups"
|
||||
|
||||
# Messaging groups + 连线
|
||||
sqlite3 data/v2.db "SELECT mg.id, mg.channel_type, mg.platform_id, mg.unknown_sender_policy, mga.engage_mode, mga.engage_pattern FROM messaging_groups mg JOIN messaging_group_agents mga ON mga.messaging_group_id = mg.id"
|
||||
|
||||
# Sessions
|
||||
sqlite3 data/v2.db "SELECT * FROM sessions"
|
||||
|
||||
# 用户和角色
|
||||
sqlite3 data/v2.db "SELECT * FROM users"
|
||||
sqlite3 data/v2.db "SELECT * FROM user_roles"
|
||||
|
||||
# Session 续接（哪个 Claude Code session 将被恢复）
|
||||
AG_ID=$(sqlite3 data/v2.db "SELECT id FROM agent_groups LIMIT 1")
|
||||
SESS_ID=$(sqlite3 data/v2.db "SELECT id FROM sessions LIMIT 1")
|
||||
sqlite3 data/v2-sessions/$AG_ID/$SESS_ID/outbound.db "SELECT * FROM session_state"
|
||||
|
||||
# 计划任务
|
||||
sqlite3 data/v2-sessions/$AG_ID/$SESS_ID/inbound.db "SELECT id, kind, recurrence, status FROM messages_in WHERE kind='task'"
|
||||
```
|
||||
|
||||
### 检查交接文件
|
||||
|
||||
```bash
|
||||
python3 -m json.tool logs/setup-migration/handoff.json
|
||||
```
|
||||
|
||||
### 常见问题
|
||||
|
||||
**切换后 bot 不响应：**
|
||||
1. 检查两个服务都没有运行：`systemctl --user list-units 'nanoclaw*'`
|
||||
2. 检查错误日志：`tail logs/nanoclaw.error.log`
|
||||
3. 检查发送者策略：`sqlite3 data/v2.db "SELECT unknown_sender_policy FROM messaging_groups"`——在 owner 被种子之前必须是 `public`
|
||||
4. 检查触发模式：`sqlite3 data/v2.db "SELECT engage_mode, engage_pattern FROM messaging_group_agents"`——应为 `pattern` / `.` 用于响应所有内容
|
||||
|
||||
**Session 未从 v1 续接：**
|
||||
1. 检查是否设置了续接：见上方的"Session 续接"查询
|
||||
2. 检查 JSONL 是否在正确路径下：`ls data/v2-sessions/<ag_id>/.claude-shared/projects/-workspace-agent/`
|
||||
3. v1 session JSONL 应从 `-workspace-group/` 拷贝到 `-workspace-agent/`（v2 容器 CWD 为 `/workspace/agent`）
|
||||
|
||||
**服务切换回退不起作用：**
|
||||
1. v2 服务名称为 `nanoclaw-v2-<hash>`——找到它：`systemctl --user list-units 'nanoclaw*'`
|
||||
2. 手动停止：`systemctl --user stop <unit> && systemctl --user disable <unit>`
|
||||
3. 重启 v1：`systemctl --user start nanoclaw`
|
||||
|
||||
### 步骤日志
|
||||
|
||||
每个步骤将原始输出写入 `logs/migrate-steps/<step>.log`。当某个步骤失败时读取这些日志：
|
||||
|
||||
```bash
|
||||
cat logs/migrate-steps/1b-db.log
|
||||
cat logs/migrate-steps/1d-sessions.log
|
||||
```
|
||||
|
||||
## 关键决策
|
||||
|
||||
- `unknown_sender_policy` 在迁移期间设置为 `public`，以便 bot 立即响应。`/migrate-from-v1` 技能在种子 owner 后收紧此设置。
|
||||
- v1 中 `requires_trigger=0` 优先于非空的 `trigger_pattern`——它意味着"响应所有内容"。
|
||||
- v1 `container_config.additionalMounts` 直接写入 v2 `container.json`（相同格式）。
|
||||
- v1 Claude Code session 从 `-workspace-group/` 拷贝到 `-workspace-agent/`，session ID 以 `continuation:claude` 写入 `outbound.db`，以便 agent-runner 恢复同一对话。
|
||||
- 结尾的 `exec claude "/migrate-from-v1"` 替换了 bash 进程——`write_handoff` 在 `exec` 之前显式调用，因为 EXIT 陷阱不会在 `exec` 时触发。
|
||||
Reference in New Issue
Block a user