# 运行手册

> 新版 Muse（agent-example 单用户作者工作台）的日常运行、备份与排障入口。能力状态与边界见文末。

## 1. 系统组成

| 组件 | 位置 | 说明 |
|---|---|---|
| 作者工作台服务 | 本机 `muse 服务`（uvicorn 127.0.0.1:8080） | 唯一正式写入口；静态工作台随资源包发布 |
| 正式内容库 | infra（100.64.0.8:5433）PG 实例，库 `muse_migration_1fe755ea37684f9d926f3a0cb3e9c7f2` | 作品/章/正文/规则/样例权威；用途角色 muse_app/eval/maint 隔离 |
| 资源包 | `src/muse/资源/`（构建身份见 `工具/环境预检.py`） | 角色/操作/提示词/工作台前端 |
| 应用配置 | `配置/应用.example.toml`（实例在迁移目录 `新目标-01/应用.toml`） | 数据库受控引用、资源身份、HTTP、文件目录 |

## 2. 启动与停止

```bash
# 启动（配置路径按实际实例）
cd <配置所在目录>
nohup <重写工作树>/.venv/bin/python -m muse 服务 <配置>.toml > 服务日志.log 2>&1 &

# 健康
curl -s http://127.0.0.1:8080/health   # {"status":"alive"}
curl -s http://127.0.0.1:8080/ready    # 含数据库连通

# 停止
pkill -f "muse 服务"
```

浏览器访问 `http://127.0.0.1:8080`，用配置的口令文件登录（作者 ID 见配置）。

## 3. 备份与恢复

```bash
# 完整备份（含核对）
muse 数据维护 备份 <配置> --输出 <目录>
# 恢复到新空库
muse 数据维护 恢复 <配置> --备份 <目录> --目标 <新库配置>
```

服务器级备份：infra 容器原生 pg_dump（见迁移记录 `W29/回合开发/infra真实迁移/`）。

## 4. 资源与代码更新

改代码/技能/提示词后：`工具/构建资源包.py` 重建 → `工具/环境预检.py` 取新 resource_build_id → 更新应用配置 `发布身份` → 重启服务。

## 5. 排障

| 症状 | 处置 |
|---|---|
| 长连接被掐（Tailscale 空闲断连） | 连接串须含 `keepalives=1 keepalives_idle=15 keepalives_interval=5 keepalives_count=3`（守卫白名单已含） |
| 写请求 SCOPE_DENIED | 缺 Origin 头或来源不在 `允许来源`；浏览器正常访问即自带 |
| 工作台 404 资源不存在 | 资源包未随新身份重建/配置身份过期，按第 4 节处理 |
| 连接被拒 target_denied | 端点/参数/角色不属于获准实例；检查连接串与允许实例记录 |

## 6. 当前能力状态与边界（2026-09-15）

- 内容批次已迁移收口：15 作品（8 参考 + 7 作者）、11,786 章、11,782 块、26 规则、107 样例，台账 23,716 全核对；旧确认态未自动恢复，由作者在工作台重新确认。
- 129 项功能全部有实现与自动验证（`功能覆盖.json`）；真实模型调用（评委验证）暂缓待端点接入，其余为离线/隔离 PG/浏览器验证。
- 旧实现已按处置清单退出（web/app.py 旧工作台、旧树 300+ 条目）；替代目标未迁移的约 180 条旧条目留存树内待后续替代迁移后清理。