sanguo_moziplus_v2/docs/research/path-hardcode-research.md

# 路径硬编码调研报告

> 调研时间：2026-06-06
> 源码位置：`~/.sanguo_projects/sanguo_moziplus_v2/src/`

## 调研结论

### 4 处硬编码精确位置

| # | 文件 | 行号 | 硬编码路径 | 建议环境变量 |
|---|------|------|-----------|-------------|
| 1 | `blackboard/registry.py` | 264 | `Path.home() / ".openclaw" / "sanguo_projects"` | `SANGUO_PROJECTS_DIR` |
| 2 | `daemon/spawner.py` | 1177 | `Path.home() / ".openclaw" / "agents" / agent_id / "sessions" / "sessions.json"` | `OPENCLAW_HOME` |
| 3 | `daemon/spawner.py` | 1261 | 同上 | `OPENCLAW_HOME` |
| 4 | `api/blackboard_routes.py` | 161 | `Path.home() / ".openclaw" / "openclaw.json"` | `OPENCLAW_HOME` |

### 修复优先级和风险评估

| 优先级 | 位置 | 风险 | 理由 |
|--------|------|------|------|
| **P1** | registry.py:264 | 低 | 只需改 1 行，方法已支持 `scan_dir` 参数，fallback 简单 |
| **P1** | blackboard_routes.py:161 | 低 | 只需改 1 行，纯读取操作 |
| **P2** | spawner.py:1177,1261 | 中 | 2 处相同路径，且有测试覆盖（通过 mock），需确保 mock 不依赖硬编码路径 |

**总体风险：低**。4 处修改均为简单路径替换，不影响逻辑，且设计文档已规划好环境变量名。

---

## 现有环境变量模式

源码中已有的环境变量用法：

| 环境变量 | 位置 | 用途 | 默认值 |
|---------|------|------|--------|
| `BLACKBOARD_ROOT` | `utils.py:19` | 项目数据根目录 | `{src}/../data/` 或 `config/default.yaml` 的 `data_root` |
| `MOZI_SKILL_PATH` | `daemon/bootstrap.py:41` | 技能文件搜索路径 | `~/.sanguo_projects/sanguo_mozi/skills` |

### 命名规范

```python
# utils.py — 优先级链：环境变量 > config 文件 > 默认值
root = os.environ.get("BLACKBOARD_ROOT")

# bootstrap.py — os.environ.get + fallback
SKILL_BASE_PATH = os.environ.get(
    "MOZI_SKILL_PATH",
    os.path.expanduser("~/.sanguo_projects/sanguo_mozi/skills")
)
```

**规范总结**：
- 全大写蛇形命名
- 使用 `os.environ.get("VAR_NAME", fallback)` 模式
- 测试中通过 `os.environ["VAR"] = ...` 设置，`del os.environ["VAR"]` 清理
- 已有 `BLACKBOARD_ROOT` 用于数据根目录，不应复用（语义不同）

---

## 逐项分析

### 1. registry.py:264 — SANGUO_PROJECTS_DIR

**精确位置**：`src/blackboard/registry.py` 第 264 行

**上下文代码**（方法：`discover_sanguo_projects`，行 262-296）：

```python
def discover_sanguo_projects(self, scan_dir: Optional[Path] = None) -> List[str]:
    """扫描 sanguo_projects 开发目录，自动注册正式项目"""
    scan_dir = scan_dir or Path.home() / ".openclaw" / "sanguo_projects"  # ← 第264行
    discovered = []

    if not scan_dir.exists():
        return discovered

    conn = self._connect()
    try:
        for child in sorted(scan_dir.iterdir()):
            if not child.is_dir():
                continue
            if not child.name.startswith("sanguo_"):
                continue
            # ... 自动注册到 blackboard.db
```

**使用场景**：
- **启动时**自动扫描 `~/.openclaw/sanguo_projects/` 目录，将 `sanguo_*` 子目录注册为正式项目
- 被 `main.py:118` 在启动时调用：`registry.discover_sanguo_projects()`
- 仅扫描一次，不涉及运行时高频访问

**默认值**：`~/.openclaw/sanguo_projects`
**Fallback**：`Path.home() / ".openclaw" / "sanguo_projects"`（保持现有行为）

**影响范围**：
- 直接引用：1 处（registry.py:264）
- 调用方：1 处（main.py:118），但调用时不传参数，走默认路径
- 数据库中注册的 `source="sanguo_projects_scan"` 标记会被使用（前端判断项目是否可删除）
- **测试覆盖**：无直接测试（`test_registry.py` 存在但需确认是否覆盖此方法）

**修复方案**：
```python
scan_dir = scan_dir or Path(os.environ.get(
    "SANGUO_PROJECTS_DIR",
    str(Path.home() / ".openclaw" / "sanguo_projects")
))
```

**需改文件**：`src/blackboard/registry.py`（1 处）

---

### 2. spawner.py:1177 — OPENCLAW_HOME（第一处）

**精确位置**：`src/daemon/spawner.py` 第 1177 行

**上下文代码**（静态方法：`_revive_session`，行 1175-1200）：

```python
@staticmethod
def _revive_session(agent_id: str) -> bool:
    """假死复活术:修改 sessions.json status 从 running 改为 idle"""
    sessions_path = Path.home() / ".openclaw" / "agents" / agent_id / "sessions" / "sessions.json"  # ← 第1177行
    if not sessions_path.exists():
        return False
    try:
        with open(sessions_path) as f:
            sessions = json.load(f)
        main_key = f"agent:{agent_id}:main"
        main_session = sessions.get(main_key, {})
        if main_session.get("status") != "running":
            return False
        main_session["status"] = "idle"
        sessions[main_key] = main_session
        with open(sessions_path, "w") as f:
            json.dump(sessions, f, indent=2)
        logger.info("Revived %s: sessions.json status changed running→idle", agent_id)
        # 清理残留 lock 文件
        sf = main_session.get("sessionFile", "")
        if sf:
            lock_path = Path(sf + ".lock")
            if lock_path.exists():
                lock_path.unlink()
    except Exception:
        return False
    return True
```

**使用场景**：
- **Spawner Phase 0 健康检查**时，发现 agent 会话状态为 `running` 但实际已死，将其重置为 `idle`
- 运维级操作，非高频调用

---

### 3. spawner.py:1261 — OPENCLAW_HOME（第二处）

**精确位置**：`src/daemon/spawner.py` 第 1261 行

**上下文代码**（静态方法：`_check_session_state`，行 1254-1290）：

```python
@staticmethod
def _check_session_state(agent_id: str) -> dict:
    """检查 sessions.json 和 lock 状态"""
    result = {"status": "unknown", "lock_pid": None, "lock_pid_alive": False, "recent_compact": False}
    sessions_path = Path.home() / ".openclaw" / "agents" / agent_id / "sessions" / "sessions.json"  # ← 第1261行
    if not sessions_path.exists():
        return result
    try:
        with open(sessions_path) as f:
            sessions = json.load(f)
        main_key = f"agent:{agent_id}:main"
        main_session = sessions.get(main_key, {})
        result["status"] = main_session.get("status", "unknown")
        # 检查 lock ...
```

**使用场景**：
- **每个 tick** 检查所有 agent 的会话状态（status + lock）
- 高频调用（默认每 30 秒一次 tick）
- 返回值被 `_revive_session` 和其他调度逻辑使用

**两处 spawner.py 共享相同的路径模式**：`Path.home() / ".openclaw" / "agents" / agent_id / "sessions" / "sessions.json"`

**默认值**：`Path.home() / ".openclaw"`
**Fallback**：`Path.home() / ".openclaw"`

**影响范围**：
- 直接引用：2 处（spawner.py:1177, spawner.py:1261）
- 调用方：Spawner 主循环（`_phase0_health_check`）
- **测试覆盖**：有！`test_spawner.py` 大量 mock 了 `_check_session_state` 和 `_revive_session`，但这些 mock 直接替换了整个方法，**不依赖路径硬编码**，因此修复后测试无需改动

**修复方案**：
```python
# 抽取为辅助函数或模块级常量
_OPENCLAW_HOME = Path(os.environ.get("OPENCLAW_HOME", str(Path.home() / ".openclaw")))

# 使用处
sessions_path = _OPENCLAW_HOME / "agents" / agent_id / "sessions" / "sessions.json"
```

**需改文件**：`src/daemon/spawner.py`（2 处 + 1 处常量定义）

---

### 4. blackboard_routes.py:161 — OPENCLAW_HOME

**精确位置**：`src/api/blackboard_routes.py` 第 161 行

**上下文代码**（函数：`_generate_title`，行 147-186）：

```python
async def _generate_title(description: str) -> str | None:
    """调用 LLM 生成简短标题"""
    if not description or len(description) < 5:
        return None
    try:
        from openai import OpenAI
        import json as _json
        base_url = "https://open.bigmodel.cn/api/paas/v4"
        api_key = ""
        model = "glm-4-flash"
        oc_cfg = Path.home() / ".openclaw" / "openclaw.json"  # ← 第161行
        if oc_cfg.exists():
            with open(oc_cfg) as f:
                cfg = _json.load(f)
            zhipu = cfg.get("models", {}).get("providers", {}).get("zhipu", {})
            if zhipu.get("baseUrl"):
                base_url = zhipu["baseUrl"]
            if zhipu.get("apiKey"):
                api_key = zhipu["apiKey"]
        if not api_key:
            return None  # 没配 API key 就跳过
        # ... 调用 OpenAI API 生成标题
```

**使用场景**：
- 创建任务时，如果未提供 title，调用 LLM 自动生成简短标题
- 读取 `~/.openclaw/openclaw.json` 获取 zhipu API 配置
- 非关键路径：即使文件不存在或读取失败，也会 graceful fallback（返回 None，使用默认标题）

**默认值**：`Path.home() / ".openclaw"`
**Fallback**：`Path.home() / ".openclaw"`

**影响范围**：
- 直接引用：1 处（blackboard_routes.py:161）
- 调用方：`create_task` API 路由
- **测试覆盖**：无直接测试（integration test 存在但未覆盖 `_generate_title`）

**修复方案**：
```python
_OPENCLAW_HOME = Path(os.environ.get("OPENCLAW_HOME", str(Path.home() / ".openclaw")))
oc_cfg = _OPENCLAW_HOME / "openclaw.json"
```

**需改文件**：`src/api/blackboard_routes.py`（1 处 + 1 处常量定义）

---

## 额外发现

### 1. bootstrap.py:42 — 已使用环境变量模式（可作为参考）

```python
SKILL_BASE_PATH = os.environ.get(
    "MOZI_SKILL_PATH",
    os.path.expanduser("~/.sanguo_projects/sanguo_mozi/skills")
)
```

这是**类属性级别的环境变量**，但存在一个问题：它在类加载时就确定了值，运行时修改环境变量不会生效。建议 `_OPENCLAW_HOME` 等也采用相同方式（在模块加载时确定），保持一致性。

### 2. utils.py — BLACKBOARD_ROOT 已有完整优先级链

```python
def get_data_root() -> Path:
    root = os.environ.get("BLACKBOARD_ROOT")
    if root:
        return Path(root)
    # ... config/default.yaml → 相对路径 fallback
```

这是最完善的实现，有 3 级 fallback。本次 4 处硬编码不需要这么复杂，简单的 `os.environ.get(var, default)` 即可。

### 3. 无其他路径硬编码

除了已知的 4 处，源码中 `.openclaw` 路径的引用仅出现在：
- 前端代码（`frontend/dist/` 和 `frontend/src/`）— 无需修改
- 测试代码 — 使用 `BLACKBOARD_ROOT` 临时目录隔离
- 文档 — 描述性引用

### 4. 无 `OPENCLAW_HOME` 或 `SANGUO_PROJECTS_DIR` 的现有定义

源码中未定义这两个环境变量，不会冲突。

---

## 统一修复方案

### 环境变量设计

| 环境变量 | 默认值 | 影响文件 | 说明 |
|---------|--------|---------|------|
| `OPENCLAW_HOME` | `~/.openclaw` | spawner.py (×2), blackboard_routes.py (×1) | OpenClaw 配置根目录 |
| `SANGUO_PROJECTS_DIR` | `~/.openclaw/sanguo_projects` | registry.py (×1) | 三国项目开发目录 |

### 实现方式

**方案 A（推荐）：各文件内模块级常量**

```python
# spawner.py 顶部
_OPENCLAW_HOME = Path(os.environ.get("OPENCLAW_HOME", str(Path.home() / ".openclaw")))

# 使用处
sessions_path = _OPENCLAW_HOME / "agents" / agent_id / "sessions" / "sessions.json"
```

```python
# blackboard_routes.py 顶部
_OPENCLAW_HOME = Path(os.environ.get("OPENCLAW_HOME", str(Path.home() / ".openclaw")))

# 使用处
oc_cfg = _OPENCLAW_HOME / "openclaw.json"
```

```python
# registry.py 内方法
scan_dir = scan_dir or Path(os.environ.get(
    "SANGUO_PROJECTS_DIR",
    str(Path.home() / ".openclaw" / "sanguo_projects")
))
```

**优点**：
- 与 `MOZI_SKILL_PATH`（bootstrap.py）模式一致
- 模块加载时确定，性能无开销
- 改动最小，每个文件加 1 行常量 + 替换路径

**方案 B（过度设计）：集中到 utils.py**

将 `OPENCLAW_HOME` 和 `SANGUO_PROJECTS_DIR` 都定义在 `utils.py`，其他文件 import。不推荐，因为引入不必要的依赖关系。

### 需要改的文件清单

1. `src/blackboard/registry.py` — 第 264 行（1 处）
2. `src/daemon/spawner.py` — 顶部加常量 + 第 1177 行 + 第 1261 行（3 处）
3. `src/api/blackboard_routes.py` — 顶部加常量 + 第 161 行（2 处）

### 测试适配

- **test_spawner.py**：不需要改动。测试通过 lambda/mock 替换整个 `_check_session_state` 和 `_revive_session`，不依赖实际路径。
- **test_registry.py**：如需测试 `SANGUO_PROJECTS_DIR` 环境变量，可添加新测试用例，通过 `os.environ` 设置临时目录验证。
- **integration tests**：已通过 `BLACKBOARD_ROOT` 隔离，不受影响。
- **建议新增**：为 `OPENCLAW_HOME` 和 `SANGUO_PROJECTS_DIR` 各添加一个单元测试，验证环境变量覆盖生效。

### Fallback 逻辑

所有 4 处统一使用：
```python
os.environ.get("VAR_NAME", str(Path.home() / ".openclaw" / "..."))
```

不设置环境变量时行为与现在完全一致，零破坏性。