# PineAgents 修改说明（Notice of Modifications）

> 本文档记录 PineAgents 相对上游开源项目 **QwenPaw**（[agentscope-ai/QwenPaw](https://github.com/agentscope-ai/QwenPaw)，Apache License 2.0）的全部修改，满足 Apache 2.0 对衍生作品的署名与修改记录要求，并作为本仓库修改溯源依据。
>
> 约定：**「上游」** = QwenPaw 开源基线；**「本仓库」** = PineAgents 二次开发结果。

---

## 0. 基线信息

| 项 | 值 |
|----|-----|
| 上游项目 | QwenPaw（Apache 2.0，原始 LICENSE 见 `LICENSE_QwenPaw`） |
| 上游基线版本 | 2.1.0b1 |
| 本产品 | PineAgents（闭源商业软件，自有 LICENSE 见 `LICENSE`） |
| 本仓库源 | infoepoch_lan |
| 开发路线 | Fork 改名 + 与上游同步 |

---

## 1. 品牌与许可变更

| # | 改动 | 说明 |
|---|------|------|
| 1 | `LICENSE` → `LICENSE_QwenPaw` | 保留上游 Apache 2.0 授权原文及署名，仅改名 |
| 2 | 新增 `LICENSE` | PineAgents 自有闭源商业许可（模板，待法务审核） |
| 3 | 新增本文档 `NOTICE.md` | 记录全部修改，满足 Apache 2.0 署名要求 |
| 4 | 品牌名 `QwenPaw` → `PineAgents` | 产品名、CLI、前端标题、文档等展示层 |
| 5 | 新增 `docs/secondary-dev/` | 二次开发文档（品牌盘点、抽离方案、本说明） |

---

## 2. 代码与配置修改记录

> 按抽离方案（`docs/secondary-dev/BRANDING_ABSTRACTION.md`）执行。**持久化标识（数据目录、keyring、消息 tag、Agent ID）默认沿用，避免破坏旧数据；仅展示层与配置入口切换品牌。**

| # | 文件/模块 | 改动 | 是否影响上游合并 |
|---|-----------|------|:---:|
| 1 | `src/pineagents/constant.py` | `PROJECT_NAME` 读 `BRAND`；`_get_env` 升级为三前缀回退（PINEAGENTS_→QWENPAW_→COPAW_） | 中 |
| 2 | `src/pineagents/branding.py`（新增） | 品牌单一事实源 `Branding` 配置对象 | 低 |
| 3 | `pyproject.toml` | `[project.scripts]` 新增 `pineagents` 命令入口 | 低 |
| 4 | `docker-compose.yml`、`deploy/`、`scripts/` | 镜像名、启动命令切 `pineagents` | 中 |
| 5 | `console/src/constants/branding.ts`（新增） | 前端品牌常量 | 低 |
| 6 | `console/index.html`、`package.json`、`public/` 素材 | 标题、favicon、logo 替换 | 低 |
| 7 | 遥测上报 | 默认关闭/替换为自有遥测 | 低 |

### 2.1 已落地改动明细（含提交 hash）

| # | 文件 | 具体改动 | 兼容性 |
|---|------|----------|:---:|
| 1 | `src/pineagents/branding.py` | 新增 `Branding` dataclass + `BRAND` 实例：`project_name="PineAgents"`、`cli_name="pineagents"`、`env_prefix="PINEAGENTS_"`，持久化标识沿用上游值 | 新增文件，零影响 |
| 2 | `src/pineagents/constant.py` | 导入 `BRAND`；`PROJECT_NAME` → `BRAND.project_name`；`_get_env` 先精确命中、再按 PINEAGENTS_→QWENPAW_→COPAW_ 回退 | 精确命中优先，既有 QWENPAW_/COPAW_ 行为不变 |
| 3 | `pyproject.toml` | `[project.scripts]` 增加 `pineagents = "qwenpaw.cli.main:cli"`（保留 `qwenpaw`/`copaw`） | 纯新增入口 |
| 4 | `console/index.html` | `<title>` → `PineAgents Console` | 展示文案 |
| 5 | `console/package.json` | `name` → `pineagents-console` | 元数据 |
| 6 | `console/src/layouts/Header.tsx` | logo `alt` → `PineAgents` | 展示文案 |
| 7 | `console/src/pages/Login/index.tsx` | logo `alt` → `PineAgents` | 展示文案 |
| 8 | `console/src/pages/Chat/index.tsx` | 欢迎昵称 fallback → `"PineAgents"` | 展示文案 |
| 9 | `console/src/pages/Chat/OptionsPanel/defaultConfig.ts` | 面板标题 → `"Work with PineAgents"` | 展示文案（保留 `prefix:"qwenpaw"` 功能键） |
| 10 | `console/src/pages/Settings/Agents/components/AgentTable.tsx` | 原生 Agent 标签 → `PineAgents · …` | 展示文案 |
| 11 | `console/src/pages/Settings/Agents/components/AgentTable.test.tsx` | 断言 `/QwenPaw/` → `/PineAgents/` | 测试同步 |
| 12 | `console/src/pages/Settings/Market/components/SkillIcon.tsx` | 展示映射值 → `"PineAgents"`（保留键 `qwenpaw`） | 展示文案 |
| 13 | `console/src/utils/skill.ts` | 展示映射值 → `"PineAgents"`（保留键 `qwenpaw`） | 展示文案 |

### 2.2 文档重组

| # | 改动 | 说明 |
|---|------|------|
| 1 | 新增根 `README.md` | PineAgents 标准文档（目录作用、架构流程、安装、启动、构建、测试、二次开发） |
| 2 | 新增 `old_docs/` | 归档原上游文档（`README*`、`CONTRIBUTING*`、`RELEASING*` 共 9 个文件，git mv 保留历史） |
| 3 | 根目录保留 | `SECURITY.md`（通用安全策略）、`LICENSE`、`LICENSE_QwenPaw`、`NOTICE` |

> 说明：仅改**无歧义展示层**。功能性标识（`window.QwenPaw` 插件 API、localStorage 键、API 路径、`qwenpaw-local` provider id、真实安装命令、FAQ 解析正则、`~/.qwenpaw` 路径）**均保留不动**，改动会破坏功能。

> 其余项（4-7）为待办，落地后补充实际行号与 commit hash。

### 2.3 彻底改名与部署/遥测（自维护，不再上游同步）

| # | 文件 | 具体改动 | 说明 |
|---|------|----------|:---:|
| 1 | `src/qwenpaw/` → `src/pineagents/` | 包目录彻底改名，全部 `import/from qwenpaw` → `pineagents`（476 处 import + 201 处字符串模块路径） | 包名、CLI、动态 import 全改 |
| 2 | `pyproject.toml` | `name="pineagents"`、scripts 指向 `pineagents.cli.main`、coverage/package-data/version attr 同步 | 打包 |
| 3 | `src/pineagents/branding.py` | `package_name="pineagents"`；新增 `telemetry_enabled=False` | 品牌/遥测 |
| 4 | `src/pineagents/utils/telemetry.py` | `is_telemetry_opted_out` 恒 True；`collect_and_upload_telemetry` no-op | 闭源默认关闭遥测 |
| 5 | `docker-compose.yml` | 镜像/卷/容器/服务名 → `pineagents` | 部署 |
| 6 | `deploy/Dockerfile`、`deploy/entrypoint.sh` | 品牌文案 + `pineagents init`；保留 `QWENPAW_*` 环境变量（兼容回退） | 部署 |
| 7 | `scripts/`（install/pack/build_*） | 命令、`-m qwenpaw`、`src/qwenpaw` 路径 → `pineagents` | 打包脚本 |
| 8 | `scripts/pack-tauri/pineagents.spec` | 模块/数据路径/collect_submodules → `pineagents`；**保留内部产物名 `qwenpaw-backend`**（Tauri Rust/NSIS 深度引用） | 打包 |
| 9 | `.github/`、`Makefile`、`.gitignore`、`e2e/` | `src/qwenpaw` 路径、`-m qwenpaw` → `pineagents` | CI/测试 |
| 10 | 持久化标识 | **保留** `QWENPAW_` 环境变量、`~/.qwenpaw`、`qwenpaw_tag`、`qwenpaw-local` provider id（避免破坏旧数据） | 兼容 |

### 2.4 前端剩余展示文案与品牌素材

| # | 文件 | 具体改动 | 说明 |
|---|------|----------|:---:|
| 1 | `console/src/locales/*.json`（7 语言） | 产品名 `QwenPaw` → `PineAgents`；安装 extra `qwenpaw[...]` → `pineagents[...]`；**保留 `~/.qwenpaw/` 路径** | 展示 + 安装命令 |
| 2 | `console/src/layouts/constants.ts` | FAQ 标题 `QwenPaw如何更新`→`PineAgents`；CLI 命令 `qwenpaw update/app`→`pineagents` | 展示/命令 |
| 3 | `console/src/layouts/Header.tsx` | FAQ 解析正则 `### QwenPaw如何更新`→`PineAgents`（与标题联动） | 功能联动 |
| 4 | `console/src/pages/AppCenter/AppMarket.tsx` | 兼容弹窗文案 `QwenPaw`→`PineAgents` | 展示 |
| 5 | `console/public/logo-light.svg` / `logo-dark.svg` / `pineagents-icon.svg`（新增） | SVG 技能生成松树+智能体节点品牌图（含 512 图标），校验 PASS | 品牌素材 |
| 6 | `console/index.html` | favicon → `/pineagents-icon.svg` | 素材 |
| 7 | `console/src/pages/Chat/index.tsx`、`src/tauri/BackendLoadingPage.tsx` | 头像/加载页 → `/pineagents-icon.svg`；删除旧 `qwenpaw.png` | 素材 |
| 8 | 保留 | `qwenpawBack.png`（装饰背景）、`window.QwenPaw` 插件 API、`qwenpaw-compat-labels` 字段、`GITHUB_URL` | 功能性/协议保留 |

### 2.5 强制登录（pine/123456，经演示 FastAPI）

| # | 文件 | 具体改动 | 说明 |
|---|------|----------|:---:|
| 1 | `pineagents-demo/app/main.py`（同级目录） | 新增 `/auth/login`（校验 pine/123456，返回 token + 昵称/账号/公司/房间/头像/公司头像）、`/auth/status`、`/auth/verify`、`/auth/register` | 演示接口（按规则放演示 FastAPI） |
| 2 | `src/pineagents/constant.py` | 新增 `DEMO_API_BASE_URL`（`PINEAGENTS_DEMO_BASE_URL`，默认 http://127.0.0.1:8090） | 配置 |
| 3 | `src/pineagents/app/routers/auth.py` | login/register/status/verify 等改为用 `httpx.AsyncClient`（`trust_env=False`）转发到演示 FastAPI，保留响应模型；`LoginResponse` 增加资料字段透传 | 本项目后端仅转发，不实现认证逻辑 |
| 4 | `console/src/api/modules/auth.ts` | `LoginResponse` 类型增加 nickname/account/company/room/avatar/company_avatar | 前端类型 |

> 登录强制由前端 `AuthGuard` 实现；项目后端 AuthMiddleware 保持关闭（不设 `QWENPAW_AUTH_ENABLED`），避免用本地 auth 校验 demo token 导致 401。

### 2.6 账户管理（资料渲染 + 编辑 + 修改密码）

| # | 文件 | 具体改动 | 说明 |
|---|------|----------|:---:|
| 1 | `pineagents-demo/app/main.py` | 资料/密码改为可变；新增 `/auth/update-profile`（改资料+改密，校验旧密码）、`/auth/me`（返回当前资料） | 演示接口 |
| 2 | `src/pineagents/app/routers/auth.py` | `UpdateProfileRequest` 增加资料字段；update-profile 转发并返回完整资料；新增 `/me` 转发 | 本项目后端转发 |
| 3 | `console/src/api/modules/auth.ts` | 新增 `UserProfile`/`UpdateProfilePayload` 类型、`me`、`updateProfile(payload)`；`authHeaders()` 统一带 token | 前端 API |
| 4 | `console/src/api/config.ts` | 新增 `setStoredUser`/`getStoredUser`（资料存 localStorage） | 前端存储 |
| 5 | `console/src/pages/Login/index.tsx` | 登录成功后 `setStoredUser(res)` 存资料 | 前端 |
| 6 | `console/src/pages/Settings/Account/index.tsx`（新增） | 账户管理页：渲染头像/昵称/账号/公司/房间 + 资料编辑表单 + 修改密码表单 | 前端页面 |
| 7 | `console/src/layouts/registry/builtinRoutes.tsx`、`builtinMenu.ts` | 注册 `/account` 路由与设置菜单「账户管理」项（`SparkAccountManagementLine` 图标） | 前端路由/菜单 |

---

## 3. 内部逻辑重设计记录

> 本章记录基于上游的**逻辑/架构级**改动（非纯品牌文案）。当前为规划占位，随重设计逐步填充。

| # | 模块 | 原逻辑 | 新逻辑 | 状态 |
|---|------|--------|--------|:---:|
| 1 | `agents/react_agent.py` | 上游决策循环 | （待定，见 BRANDING_ABSTRACTION / 后续设计） | 规划 |
| 2 | `runtime/` | 上游编排 | （待定） | 规划 |
| 3 | `governance/` | 上游权限模型 | （待定） | 规划 |

---

## 4. 使用与同步指引

1. 本仓库为 **Fork + 上游同步** 模式：合并上游 QwenPaw 时，优先解决「环境变量前缀」与「持久化标识」两处冲突。
2. 任何基于上游的改动，必须在本文件登记，再提交代码（见 `docs/secondary-dev/BRANDING_ABSTRACTION.md` 第 7 节落地步骤）。
3. 本文件为 Apache 2.0 要求的 NOTICE 载体，**不可删除**。
