Pine
17 KiB
17 KiB
UPSTREAM_SYNC · 上游同步基线文档
本文件是 PineAgents（agent-desktop）与上游 QwenPaw 的同步基线、裁决规则与变更记录的活文档。 合规署名与全部修改清单见
NOTICE；本文件聚焦「如何把上游更新科学、稳健地合进来」。
1. 基线信息
| 项 | 值 |
|---|---|
| 上游仓库 | agentscope-ai/QwenPaw（Apache 2.0） |
| 基线版本 | 2.1.0b1（tag v2.1.0-beta.1 = commit 6f8e52a48c32ea06ec726834ada3e4c753e5f964） |
| 当前目标版本 | 2.2.0（tag v2.2.0 = commit ae092fdca62164b467dee998893cbc450b97d59f） |
| 本仓库 | agent-desktop（PineAgents，闭源商业软件） |
| 基线差异跨度 | v2.1.0-beta.1..v2.2.0 = 328 commits（70 feat） |
⚠️ 基线必须记录精确 commit hash，禁止只写版本字符串（
2.1.0b1这种无法唯一定位）。
2. 三层代码组织（治本规范）
任何新代码按以下分层落位，目标是「桥接层 + 自研层」几乎零冲突：
| 层 | 定位 | 规则 | 目录 |
|---|---|---|---|
| 上游区 Upstream | 跟上游同步的源码 | 只允许「采用上游 / 三向合并后以上游为主」；禁止写入云超服业务逻辑 | console/src/api、console/src/pages/Chat、console/src/pages/Settings（上游页面）、src/（后端） |
| 桥接层 Bridge | 上游与自研的扩展点 | 需要动上游行为时优先走注册表/适配器/包装组件，不改上游文件 | console/src/layouts/registry/、console/src/plugins/、console/src/bridge/（新建） |
| 自研区 Custom | 云超服独有能力 | 独立目录，零依赖上游内部实现，经桥接层挂入 | console/src/pages/portal/、pages/Operator/、pages/Communication/、pages/Agent/Workspace/、auth/、api/modules/*（自研） |
3. 同步流程（每个上游 release 的同步窗口，建议 1-2 周内）
- 拉取 tag：上游发布后锁定 commit hash，更新本文件「基线信息」。
- 三向 diff：运行
python scripts/sync-diff.py（见 §5），输出文件级分类清单。 - 分类处理：
upstream_only（仅上游改）→ 直接采用上游版本；local_only（仅本地改）→ 保留本地；both（双改）→ 按 §4 裁决规则人工三向合并；only_head（上游新增）→ 引入；only_local（本地新增）→ 保留；deleted_upstream/deleted_local→ 决策是否跟随删除/恢复。
- 特征核验：对已声明功能增量做符号级断言（如
grep card_auto_layout），确认功能真的落地。 - 回归门：
yarn build+ console 单元测试 + 后端 pytest + 关键路径 smoke（登录/聊天/文件/市场）。 - 登记归档：更新
NOTICE与本文件「变更记录」，同步独立 PR 必须引用 sync-diff 报告。
4. 双改文件裁决规则（2026-09-04 拍板）
云端逻辑以云超服为准，本地与新增功能跟随上游。
- A 桶 · 云超服为准（云端/平台业务）：登录认证、角色权限、布局与侧栏、路由注册表、门户入口、插件市场、审批、Agent/技能/环境/MCP/安全等平台能力；吸收上游纯增量，但云超服主体逻辑不被覆盖。
- B 桶 · 上游为准（本地/功能演进）：聊天、模型选择、后台任务、Token/上下文统计、Agent 统计、ReMe、技能池逻辑、插件加载、Coding/Files、Inbox（上游 Mailbox 接入）等；保留云超服必要适配。
- C 桶 · 混合（按部位拆分合并）：语言文件（云超服语言集 + 全量吸收上游 key）、Chat 入口、Inbox、AppCenter、PluginManager、ChannelDrawer、ToolCardShell 等，逐区块并合。
4.1 本次（v2.1.0b1 → v2.2.0）83 个双改文件裁决清单
A 桶 · 云超服为准（25 个）
| 文件 | 裁决理由 |
|---|---|
api/modules/auth.ts |
云超服强制登录/JWT 角色体系 |
api/modules/pawapp.ts |
云超服 pawapp 扩展 |
api/modules/pluginMarket.ts |
云超服自研插件市场 API |
api/types/channel.ts |
云超服渠道类型 + 吸收上游字段 |
components/AgentSelector/index.module.less |
云超服 Agent 选择器样式 |
components/AgentSelector/index.tsx |
云超服 Agent 选择器 |
components/ApprovalCard/ApprovalCard.module.less |
云超服审批卡 |
components/LanguageSwitcher/index.tsx |
云超服语言切换 |
components/SkillVisual/index.tsx |
云超服技能可视化 |
layouts/Header.tsx |
云超服头部 |
layouts/MainLayout/index.tsx |
云超服五大工作页布局，吸收上游新增 |
layouts/Sidebar.tsx |
云超服角色菜单为主 + 吸收上游会话分组渲染 |
layouts/index.module.less |
云超服布局样式 |
layouts/registry/builtinMenu.ts |
云超服菜单注册 + 补上游新增入口 |
layouts/registry/builtinRoutes.tsx |
云超服路由 + 补上游 Files/Hub/OS 路由 |
pages/Agent/MCP/index.module.less |
云超服 MCP 样式 |
pages/Agent/Skills/components/SkillCard.tsx |
云超服技能卡 |
pages/Login/index.tsx |
云超服登录/角色体系，吸收上游登录增强 |
pages/Settings/Environments/index.module.less |
云超服环境配置样式 |
pages/Settings/Models/index.module.less |
云超服模型样式 + 吸收上游布局 |
pages/Settings/Models/index.tsx |
云超服模型页(PineAgentsModelCards) |
pages/Settings/Security/components/FileGuardSection.tsx |
云超服文件守卫 + 吸收上游 |
plugins/hostExternals.ts |
云超服插件宿主外部依赖 |
plugins/registry/store.ts |
云超服插件注册表 + 吸收上游 |
styles/layout.css |
云超服全局布局样式 |
B 桶 · 上游为准（32 个）
| 文件 | 裁决理由 |
|---|---|
api/types/agents.ts |
上游 Agent 类型+云超服扩展 |
api/types/provider.ts |
上游 Provider 类型+云超服扩展 |
components/LoopInput/LoopModeSelector.tsx |
上游循环模式 |
components/MermaidCodeBlock/index.module.less |
上游 Mermaid 样式 |
components/SessionItem/sessionItem.module.less |
上游未读提示样式 |
pages/Agent/Config/components/ReMeLightMemoryCard.tsx |
上游 ReMe 看板 |
pages/Agent/Config/index.module.less |
上游 Agent 配置样式(ReMe) |
pages/Agent/Tools/index.tsx |
上游工具能力(上游改31行>本地4行) |
pages/Chat/ModelSelector/index.module.less |
上游模型选择器样式 |
pages/Chat/ModelSelector/index.tsx |
上游 Agent 模型路由 |
pages/Chat/components/ApprovalLevelToggle.tsx |
上游审批级别开关 |
pages/Chat/components/BackgroundTaskPanel.tsx |
上游 compact 取代云超服 collapsed |
pages/Chat/components/ChatActionGroup/index.tsx |
上游动作组 |
pages/Chat/components/ChatHeaderTitle/index.module.less |
上游标题样式 |
pages/Chat/components/ChatSenderTabsPanel.tsx |
上游后台任务 tab |
pages/Chat/components/ChatSessionDrawer/index.module.less |
上游会话抽屉样式+云超服适配 |
pages/Chat/components/ContextUsageIndicator/ContextUsageIndicator.tsx |
上游提示词缓存可观测 |
pages/Chat/components/HarnessModelSelector.tsx |
上游模型选择 |
pages/Chat/index.module.less |
上游 Chat 样式 |
pages/Chat/index.tsx |
上游大改(自动折叠/媒体下载等)+保留云超服必要适配 |
pages/Coding/FilePreview.module.less |
上游文件预览样式(随 Files 迁移) |
pages/Coding/GitPanel.module.less |
上游 Git 面板样式 |
pages/Coding/TabbedEditor.module.less |
上游编辑器样式(随 Files 迁移) |
pages/Control/CronJobs/index.tsx |
上游定时任务+云超服小改 |
pages/Settings/AgentStats/index.tsx |
上游当前视角统计 |
pages/Settings/Agents/components/AgentModal.tsx |
上游 Agent 模态 |
pages/Settings/Agents/components/AgentTable.tsx |
上游 Agent 表格 |
pages/Settings/Models/components/modals/RemoteModelManageModal.tsx |
上游统一提供商重构，保留云超服兼容 |
pages/Settings/SkillPool/useSkillPool.tsx |
上游技能自动更新逻辑+保留云超服定制 |
pages/Settings/TokenUsage/hooks/useTokenTypeConfig.ts |
上游 Token 缓存统计 |
tauri/BackendLoadingPage.tsx |
上游桌面启动页 |
utils/skill.ts |
上游技能工具 |
C 桶 · 混合（26 个）
| 文件 | 裁决理由 |
|---|---|
App.tsx |
上游大改(Hub 路由)+云超服注入 → 上游主体+保留云超服路由 |
components/Chat/ToolCards/shared/ToolCardShell.tsx |
双方同量级 → 并合 |
components/Chat/ToolCards/shared/toolCards.module.less |
双方样式并合 |
layouts/SidebarSettingsPanel.tsx |
云超服设置侧栏+上游 |
layouts/sidebarSessionList.module.less |
上游会话列表样式+云超服 |
layouts/sidebarSettingsPanel.module.less |
双方样式 |
locales/en.json |
同上 |
locales/vi.json |
同上 |
locales/zh.json |
以云超服语言集为准 + 全量吸收上游新增 key |
main.tsx |
云超服入口注入 + 补上游 Files/Hub/OS 路由 |
pages/AppCenter/AppMarket.tsx |
上游应用市场+云超服定制 → 逐区块并合 |
pages/AppCenter/index.module.less |
双方大改样式 |
pages/AppCenter/index.tsx |
上游应用中心+云超服定制 |
pages/Control/Channels/components/ChannelDrawer.tsx |
云超服 IM 渠道扩展 + 吸收上游钉钉宽屏/共享会话 |
pages/Inbox/index.module.less |
上游 Inbox 样式+云超服扩展样式 |
pages/Inbox/index.tsx |
上游 Mailbox 接入为主 + 保留云超服 Harvest 扩展 |
pages/Settings/AgentStats/index.module.less |
双方样式 |
pages/Settings/Agents/index.module.less |
双方样式 |
pages/Settings/Market/components/ResultCard.module.less |
云超服结果卡样式 |
pages/Settings/Market/index.module.less |
上游市场样式+云超服 |
pages/Settings/Market/useMarketSearch.ts |
上游市场搜索+云超服 |
pages/Settings/PluginManager/components/MarketPluginList.module.less |
上游市场列表样式 |
pages/Settings/PluginManager/components/OfficialPluginList.module.less |
双方样式 |
pages/Settings/PluginManager/index.tsx |
云超服自研市场为主体 + 吸收上游统一市场视图 |
pages/Settings/SkillPool/index.module.less |
双方样式 |
plugins/usePluginLoader.ts |
上游大改+云超服 → 上游主体+云超服适配 |
5. sync-diff 工具
# 前端 console/src 比对（本次口径）
python scripts/sync-diff.py \
--upstream "<上游仓库路径>" --base v2.1.0-beta.1 --head v2.2.0 \
--local . --subpath console/src --out <输出目录>
# 后端（上游 src/qwenpaw -> 本地 src/pineagents 改名）
python scripts/sync-diff.py --upstream "<上游>" \
--base v2.1.0-beta.1 --head v2.2.0 --local . \
--subpath src --map src/qwenpaw=src/pineagents --out <输出目录>
输出：same / upstream_only / local_only / both / only_head / only_local / removed_upstream / deleted_upstream / deleted_local 九个分类清单 + REPORT.md 汇总 + meta.json（含三方 commit 记录）。
5.1 本次 console/src 实测汇总（v2.1.0b1 → v2.2.0，不含测试文件）
| 分类 | 说明 | 数量 |
|---|---|---|
same |
一致（无需动作） | 273 |
upstream_only |
仅上游改（直接采用） | 138 |
local_only |
仅本地改（保留） | 66 |
both |
双改（人工裁决，见 §4.1） | 83 |
only_head |
上游新增（引入） | 157 |
only_local |
本地新增（保留） | 99 |
deleted_upstream |
上游已删但本地保留 | 17 |
deleted_local |
本地已删但上游保留 | 9 |
口径说明：head 取 tag
v2.2.0（稳定基线）；测试文件独立归类，不混入功能源码统计。
6. 验收门（每次同步合并）
yarn build通过- console 单元测试通过
- 后端 pytest 通过
- 关键路径 smoke：登录 / 聊天 / 文件 / 市场 / 渠道
- 高冲突文件回归快照测试（防止合并静默丢失云超服定制）
- 数据兼容：会话 / 项目目录 / 技能配置升级不丢不坏
NOTICE与本文件「变更记录」已更新
7. 变更记录
| 日期 | 上游版本 | 本次动作 | 结果 |
|---|---|---|---|
| 2026-09-04 | v2.1.0-beta.1 → v2.2.0 | 三向 diff 分析 + 83 双改裁决 + 移植计划（见 qwenpaw-移植计划与上游同步机制.html） |
完成 |
| 2026-09-04 | v2.2.0 | 阶段 0：scripts/sync-diff.py + 本文件（commit 922e20b） |
完成 |
| 2026-09-04 | v2.2.0 | 阶段 1：Files 工作区 + Coding 迁移（commit 8ecc376，89 文件） |
完成 |
| 2026-09-04 | v2.2.0 | 阶段 2：Chat 系 + B/C 桶剩余合并（commit 26e305e + 59973f6）。① ToolCardShell 采用上游基底 + 补本地 inputProgress；② ModelSelector 三 Tab 并合（默认 pineagents tab，测试需 localStorage 预设 qwenpaw_model_selector_tab=pro）；③ vite.config.ts 加 @agentscope-ai/chat/lib/DefaultCards/Audios alias（必须在 chat stub alias 之前）；④ locales 全量补齐上游新增 key；⑤ OAuthConfirmModal 采用上游防竞态重构版；⑥ AgentTable 采用上游基底（ResizeObserver 容器高度 / fixed left+right / DndContext）+ 本地 deletable 合并；⑦ 其余 B/C 桶双改文件按裁决合并。tsc 0 错误、build 通过 |
完成（见提交） |
| 2026-09-04 | v2.2.0 | 阶段 3：统计/模型/记忆层。① TokenUsage 全目录采用上游（lineChartChrome 重构：index.tsx/useDataAggregation/useModelTrendConfig/DataTables/LoadingState/SummaryCards/tokenUsageRows.ts + 测试），保留云超服配色 useTokenTypeConfig（Prompt #06acf1/Completion #00cc3d/Total #08304c）；② api/types/tokenUsage.ts 采用上游（补 cache_read_tokens/cache_write_tokens/cache_eligible_input_tokens/cache_observed_calls/agent_id）；③ Settings/Models A 桶吸收上游纯增量：apiKeyValidation.ts+test 新增复制、useProviders 补 models_syncing 每秒轮询、index.tsx 补 manageModels URL 参数（manageModels=true 打开模型管理弹窗）、providerIcon.ts 补 volcengine-cn-agentplan/mimo 图标 case+测试同步；保留云超服 pineagents Tab/主题色（ProviderConfigModal 功能等价保留本地、LocalModelManageModal/LoadingState/providerLetterIcon 已适配 var(--color-primary)）；④ api/modules/agentStats.ts 采用上游（新增 LlmToolDaily 接口+getGlobalLlmToolTrend llm-tool-trend API+dateQuery 封装）；⑤ api/modules/agent.ts 补 updateAgentRunningConfig timeout:10min+agent.test 同步；⑥ stores/agentStore.ts 保留本地（setAgents 选中态守卫云超服逻辑）；⑦ Chat 阶段 2 补漏：OAuthConfirmModal 采用上游防竞态重构版（disposedRef/startingRef 守卫+module.less 样式）、HarnessModelSelector.test 补 explicit null effort 用例；⑧ AgentStats/index.module.less 保留本地并合版（diff 仅为 prettier 格式，语义等价）。tsc 0 错误、build 通过、阶段 3 相关 87+ 测试全过 | 完成（commit 6000379） |
| 2026-09-04 | v2.2.0 | 阶段 4：渠道/市场层（commit 8e6b3ab）。① PluginManager 采用上游：useMarketPlugins（300 行：MARKET_PAGE_SIZE 分页 append / loadingMore / autoLoadBlocked / 竞态 AbortController / highlightFilter featured|trending）+ MarketPluginList.tsx（无限滚动 LoadMoreSentinel IntersectionObserver + PluginViewToggle 卡片/列表切换）+ MarketPluginList.module.less；OfficialPluginList.module.less 保留本地三处 var(--color-border) 定制 + 追加上游移动端 @media；index.module.less 三向并合（/tmp/merge_less.py）；本地 index.tsx 保留（operator 权限 gate + PageHeader，弃上游 MarketplaceHeader 依赖）；② Market 目录 8 文件采用上游（MarketPanel 新接口 { installTarget, install: MarketInstallController } / useMarketInstall 需 { selectedAgent, onSuccess?, onError? } / useMarketSearch+test / SkillIcon / ResultCard.module.less / index.module.less）；③ Channels 上游版（ChannelDrawer / channelConfig / constants）+ 定制点保留（channelIcons console=var(--color-primary)、PendingApprovalsDrawer var(--color-success)）；④ api/types/chat.ts 采用上游（ChatGroup/ChatSource/ChatGroupKind/group_id 超集）；pages/Agent/Skills/index.tsx 适配 useMarketInstall（installTarget="workspace"）；⑤ utils 补齐 chatGroups.ts + 14 个缺失工具测试 + CronJobs 测试；⑥ 测试修复：design-mock 补 Tabs 桩（上游 PluginViewToggle 依赖 antd Tabs 语义）、MarketPluginList.test 采用上游版、skill.test 品牌映射「云超服」、lazyWithRetry.test 适配本地 dev-server 运行时回退。tsc 0 错误、build 通过、阶段 4 相关 45 测试文件 427 用例全过 |
完成（见提交） |
| 2026-09-04 | v2.2.0 | 阶段 5：OS Shell（os/ 67 文件）+ Hub + Mailbox 完整引入；双改合并：usePluginLoader/pluginMarket/registry store/hostExternals/LanguageSwitcher/BackendLoadingPage/ApprovalCard/auth.ts/gate/SidebarSettingsPanel(Desktop Mode 入口)/App.tsx(OS 分支+Hub 路由)/Inbox(上游 Mailbox+保留 Harvest)/locales(os/hub/projectDirectory/inbox/account)；tsc 0 错误、build 通过、阶段 5 新增 271 测试全过 | 完成（见提交） |