agent-desktop/docs/secondary-dev/BRANDING_ABSTRACTION.md

# PineAgents 品牌抽离方案（Branding Abstraction）

> 目标：把散落在 271 个 Python + 147 个前端文件里的品牌字符串，**收敛到单一配置层**。做到「改品牌只改一处」，并最大限度降低与上游 QwenPaw rebase 时的冲突。
> 现状：`constant.py` 里品牌已部分集中（`PROJECT_NAME`、`WORKING_DIR`、env 前缀），但仍有大量硬编码散落在 cli / routers / providers / 前端。

---

## 1. 设计原则

1. **单一事实源（Single Source of Truth）**：所有持久化标识、前缀、展示名集中在一个 `Branding` 配置对象。
2. **三前缀回退**：环境变量支持 `PINEAGENTS_`（主）→ `QWENPAW_` → `COPAW_`（遗留）逐级回退，保证旧部署/旧环境变量不被破坏。
3. **持久化标识与展示名分离**：数据目录、keyring、消息 tag 等持久化标识可独立于展示名配置（避免改展示名影响旧数据）。
4. **不破坏上游合并路径**：新增独立模块，尽量少改 `constant.py` 既有语义；上游改动通过「读 Branding 而非字面量」自然落地。

---

## 2. 目标结构

### 2.1 新增模块 `src/pineagents/branding.py`

```python
# -*- coding: utf-8 -*-
"""PineAgents 品牌与命名配置 —— 单一事实源。

改造/二次开发时：改这里，不要改散落在各文件的字面量。
"""

from __future__ import annotations
from dataclasses import dataclass, field
from pathlib import Path


@dataclass(frozen=True)
class Branding:
    # ---- 展示名（可安全全量改名）----
    project_name: str = "PineAgents"          # 产品名（原 QwenPaw）
    cli_name: str = "pineagents"              # CLI 命令（原 qwenpaw/copaw）
    package_name: str = "pineagents"          # Python 包名
    env_prefix: str = "PINEAGENTS_"           # 环境变量主前缀
    version: str = "2.1.0b1"

    # ---- 持久化标识（改名需迁移，见第 3 节）----
    working_dir_name: str = ".qwenpaw"        # 数据目录（保守：沿用）
    keyring_account: str = "qwenpaw"          # 钥匙串主密钥账号（沿用）
    message_tag_key: str = "qwenpaw_tag"      # 消息元数据 tag（沿用）
    message_client_id_key: str = "qwenpaw_client_message_id"
    builtin_qa_agent_id: str = "QwenPaw_QA_Agent_0.2"

    # ---- 兼容前缀（逐级回退）----
    legacy_prefixes: tuple[str, ...] = ("QWENPAW_", "COPAW_")

    # ---- 依赖主前缀派生出的 env key 前缀列表（供测试/检查用）----
    env_keys: tuple[str, ...] = (
        "WORKING_DIR", "SECRET_DIR", "KEYRING_ACCOUNT", "LOG_LEVEL",
    )


BRAND = Branding()
```

### 2.2 改造 `constant.py` 的 `_get_env`（三前缀回退）

把现有的 `QWENPAW_` → `COPAW_` 两级回退，扩展为 `PINEAGENTS_` → `QWENPAW_` → `COPAW_` 三级：

```python
def _get_env(key, default=""):
    if key in os.environ:
        return os.environ[key]
    if key.startswith(BRAND.env_prefix):
        for legacy in BRAND.legacy_prefixes:
            legacy_key = legacy + key[len(BRAND.env_prefix):]
            if legacy_key in os.environ:
                return os.environ[legacy_key]
    return default
```

### 2.3 收敛关键常量（`constant.py` 改为读 `BRAND`）

```python
PROJECT_NAME = BRAND.project_name
QWENPAW_MESSAGE_TAG_KEY = BRAND.message_tag_key          # 保留别名避免大改
QWENPAW_CLIENT_MESSAGE_ID_KEY = BRAND.message_client_id_key
BUILTIN_QA_AGENT_ID = BRAND.builtin_qa_agent_id
```

> 说明：`QWENPAW_MESSAGE_TAG_KEY` 等**别名保留原名**，只是值改由 `BRAND` 提供。这样内部引用无需改动，持久化值也不变（沿用 `qwenpaw_tag`），仅品牌展示名切换为 PineAgents。

---

## 3. 持久化标识处理矩阵

| 标识 | 决策 | 理由 |
|------|------|------|
| 数据目录 `~/.qwenpaw` | **沿用**（不改） | 避免旧数据不可见；如需改，配 `working_dir_name` 并加迁移 |
| 钥匙串账号 | **沿用** | 改则主密钥失配、无法解密旧密钥 |
| 消息 tag | **沿用** | 旧消息上的 tag 需继续可读 |
| 内置 Agent ID | **沿用** | 旧会话归属需对上 |
| env 前缀 | **新增 `PINEAGENTS_` 为主** | 新部署用新前缀；旧变量靠回退仍生效 |

**结论**：PineAgents 默认「展示名全改、持久化标识沿用」，实现零迁移平滑改造。

---

## 4. 前端抽离（`console/`）

前端同样收敛到一个品牌常量文件，例如 `console/src/constants/branding.ts`：

```ts
export const BRAND = {
  name: "PineAgents",
  cli: "pineagents",
  docBase: "https://<你的文档域名>/",
  // ...
} as const;
```

- 所有组件（`layouts/`、`locales/`、`pages/**`）改读 `BRAND.name`，替换字面量 `"QwenPaw"` / `"qwenpaw"`。
- `console/index.html` 的 `<title>` 与 favicon、`console/package.json` 的 name 直接改为 PineAgents。

---

## 5. 打包与部署入口

- `pyproject.toml`：`name="pineagents"`，`[project.scripts] pineagents = "pineagents.cli.main:cli"`（保留 `qwenpaw`/`copaw` 作为兼容别名可选），coverage source、package-data 同步。
- `docker-compose.yml` / `deploy/` / `scripts/`：镜像名、容器卷名、启动命令改 `pineagents`。
- 包目录改名 `src/pineagents` → `src/pineagents`（或保留目录名、仅内部标识改名，视同步策略二选一，见第 6 节）。

---

## 6. 同步策略：目录改名 or 不改？

两条路，按上游同步频率取舍：

| 方案 | 做法 | 优点 | 缺点 |
|------|------|------|------|
| **A. 目录改名** `src/pineagents/` | 一劳永逸品牌干净 | 产物、import 全干净 | 每次 rebase 上游 271 个文件路径全变，冲突巨大 |
| **B. 目录沿用** `src/pineagents/` | 包名/import 保留 qwenpaw，仅展示层改 PineAgents | rebase 冲突最小 | import 里仍带 qwenpaw 字样 |

**建议**：PineAgents 走「Fork + 上游同步」，选 **方案 B**（目录沿用 `src/pineagents/`、import 保留），只把**展示层 + 配置 + 打包入口**切到 PineAgents。这样 rebase 上游时只处理少量展示层文件。若将来决定彻底冻结上游，再一次性迁移到 `src/pineagents/`。

---

## 7. 分步落地

1. 新增 `src/pineagents/branding.py`（`Branding` 配置对象）。
2. `constant.py`：`PROJECT_NAME` 等改读 `BRAND`；`_get_env` 改三前缀回退。
3. 前端新增 `console/src/constants/branding.ts`，替换关键展示名。
4. `pyproject.toml` / `docker-compose.yml` / `deploy/`：打包与部署入口切 `pineagents`。
5. 替换 `console/public` 品牌素材（logo/favicon/启动图）。
6. 关闭/替换遥测上报。
7. 运行 `tests/` 与 e2e 回归，确认持久化标识未破坏。