[WIP] Create architecture framework and development guide for GroundPA-Toolkit

[Copilot]

• Explore repository structure and identify existing docs/code locations to extend
• Inspect available lint/build/test commands for baseline validation
• Run baseline checks before making changes (lint/build/test scope appropriate for doc+scaffold additions)
• Add docs/v2-reference/ architecture reference documents (bilingual, with design intent and Cherry Studio code paths)
• Add GroundPA-Toolkit scaffold under src/ with required interfaces and initial implementations
• Add development policy docs (DEVELOPMENT.md, DEPRECATION_POLICY.md) and update CONTRIBUTING.md minimally
• Add/adjust focused tests if relevant to changed code paths
• Run targeted validation commands after changes
• Run final parallel validation and summarize results

Original prompt

为 GroundPA-Toolkit 创建基于 Cherry Studio v2 的完整架构框架和开发指南

背景

基于对 Cherry Studio v2 重构的深度研究，为 GroundPA-Toolkit 项目创建一套完整的架构参考、代码框架和开发指南。

GroundPA-Toolkit 是 .NET 智能体项目，采用"自研核心 + MCP 扩展"架构。从 Cherry Studio v2 的设计中提取最佳实践，包括：

• Agent / Knowledge Base 统一设计（[Feature]: V2 — unify Assistant and Agent surfaces with pluggable Agent runtime CherryHQ/cherry-studio#15396, [Feature]: Agent-Native Knowledge Library & File Manager CherryHQ/cherry-studio#14896）
• 数据层重构（Redux → Cache/Preference/DataApi/SQLite）
• 迁移系统（v2 migrators、schema 收尾、ID 重映射）
• 运行时/生命周期统一管理
• deprecated 政策和渐进式迁移策略

需要创建的主要内容

1. 架构参考文档（docs/v2-reference/）

• CHERRY_STUDIO_V2_LESSONS.md - v2 核心设计决策提取
• ARCHITECTURE.md - GroundPA v2 整体架构设计
• DATA_LAYER_DESIGN.md - 数据层分工（自研核心 + MCP）
• AGENT_RUNTIME_DESIGN.md - Agent 运行时和知识库原生化
• MIGRATION_STRATEGY.md - v1 → v2 迁移框架
• LIFECYCLE_DESIGN.md - 服务生命周期管理
• BEST_PRACTICES.md - 从 Cherry Studio 学到的最佳实践

2. 代码结构框架

完整的项目目录结构和关键文件创建：

src/
├── Core/
│   ├── Agent/                    # Agent 核心运行时
│   ├── Knowledge/               # 知识库原生能力
│   ├── Data/                    # 数据层（Cache/Preference/DataStore）
│   ├── Lifecycle/              # 服务生命周期
│   ├── Migration/              # v1→v2 迁移框架
│   └── Constants/
├── Extensions/                 # MCP 扩展点
│   ├── IMCPProvider.cs
│   ├── MCPRuntimeAdapter.cs
│   └── Samples/
├── UI/                        # UI 框架（预留，对标 @cherrystudio/ui）
└── Tests/                     # 测试框架

3. 关键接口和基类

• IAgent.cs / IAgentRuntime.cs - Agent 接口定义
• IKnowledgeBase.cs / IKnowledgeAccessor.cs - 知识库接口
• IDataStore.cs - 统一数据存储接口
• IService.cs / IServiceRegistry.cs - 生命周期管理
• IMigrator.cs / MigrationEngine.cs - 数据迁移框架
• IMCPProvider.cs - MCP 扩展点

4. 初始实现

• ServiceRegistry.cs - 服务注册和依赖管理
• AgentRuntime.cs - Agent 运行时核心
• DataStoreFactory.cs - 数据存储工厂
• MigrationEngine.cs - 迁移引擎框架
• MCPRuntimeAdapter.cs - MCP 适配器

5. 开发规范

• DEVELOPMENT.md - 开发约定（参考 CLAUDE.md）
• CONTRIBUTING.md - 贡献指南
• DEPRECATION_POLICY.md - 弃用政策

具体要求

1. 文档：中英文混合，关键概念标注英文
2. 设计意图：每份文档/接口都要说明"为什么这样设计"
3. 参考链接：包含 Cherry Studio 的真实代码路径
4. 代码注释：预留 TODO、扩展点、设计决策说明
5. 完整性：框架应该可以直接指导后续开发

Cherry Studio 关键参考

• 数据层迁移：src/main/data/migration/v2/
• Agent 设计：src/main/data/migration/v2/migrators/README-AssistantMigrator.md
• 知识库：v2-refactor-temp/docs/knowledge/
• 生命周期：docs/references/lifecycle/
• UI 包：packages/ui/
• 开发规范：CLAUDE.md

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: 只看这两个v2 refactor
Agent / Knowledge Base

Assistant: 我已经帮你筛到 “v2 refactor / Agent / Knowledge Base” 这个方向了，但这一步工具返回的是可渲染的 issue 列表引用，不是直接文本结果。

你接下来最省事的方式

如果你愿意，我可以继续做下面任意一种：

1. 把这两组里对应的 issue 逐条整理成“人话版”

   • 每个 issue 讲它在解决什么
   • 跟 v2 的关系是什么
   • 你该优先看哪个

2. 把这些 issue 直接归纳成开发路线图

   • Agent 入口
   • Knowledge Base 原生化
   • 数据/运行时/UI 的重构边界

3. 继续往下拉 PR

   • 看这些 issue 最终是怎么落到代码里的
   • 直接帮你定位到源码目录

如果你要，我下一条就直接帮你做 “这两个方向的 issue 清单 + 每个 issue 的一句话解释”。

User: 把这两组里对应的 issue 逐条整理，最后要一份“人话版”的报告，给我开发路线图，看这些 issue 最终是怎么落到代码里的，括号里写上源码位置

Assistant: 下面这份我按你要的方式整理：只看 v2 refactor 里跟 Agent / Knowledge Base 相关的 issue 主题，然后把它们落到代码位置，给你一份能直接用来跟进开发的“人话版报告”。

先说一句实话：
我这次拿到的是 issue 主题集合 + 代码落点，不是每个 issue 的完整正文，所以我会按仓库里已经能确认的实现线索来帮你归类，不乱猜。

---

Cherry Studio v2：Agent / Knowledge Base 方向“人话版”报告

你可以先记住一句话

这条线不是在“加一个 Agent 功能”，而是在把 Agent 和知识库从老系统里拆出来，变成一套能迁移、能运行、能扩展的新底座。

换成人话就是：

• 以前像是“聊天页外挂一个 Agent”
• 现在要变成“Agent 是主角，知识库是它天然能用的能力”
• 同时还要把老数据、老 ID、老数据库、老知识库，安全搬到新结构里

---

一、这两组 issue 其实在做什么

我把它们拆成 4 条主线：

1）Agent 不再是一个“附属功能”，而是独立业务域

你可以理解为：

以前的 Agent 更像聊天页面里的一种模式；
v2 想把它变成单独的数据域 + 单独的运行域 + 单独的迁移域。

代码落点

• src/main/data/migration/v2/migrators/AgentsMigrator.ts
• src/main/data/migration/v2/migrators/remapAgentPrefixIds.ts
• src/main/data/migration/v2/migrators/mappings/AssistantMappings.ts
• src/renderer/services/db/AgentMessageDataSource.ts
• src/renderer/services/db/DbService.ts

人话解释

这说明团队在做三件事：

1. 把旧 Agent 数据迁到新表
2. 把老 ID / 老前缀统一改成新的 UUID 体系
3. 把 Agent 消息读取方式从旧栈切到新的数据源

也就是说，Agent 不是 UI 上多了个按钮，而是从底层开始独立了。

---

2）Knowledge Base 不是外挂，而是 V2 里要“原生生长”的对象

你可以理解为：

以前知识库像一个“额外挂载件”；
现在知识库要变成Agent 运行时天然能用的数据资产。

代码落点

• src/main/data/migration/v2/migrators/KnowledgeMigrator.ts
• src/main/data/migration/v2/migrators/__tests__/KnowledgeMigrator.test.ts
• v2-refactor-temp/docs/knowledge/knowledge-schema.md
• src/renderer/store/knowledge.ts

人话解释

这里最关键的不是“把知识库搬过去”，而是：

• 要确保知识库在 V2 里能被正确理解
• 尤其是向量库、维度、条目、目录结构这些东西
• 有些旧数据不能硬塞，要么跳过，要么标警告

这说明他们对知识库不是“兼容一下就完事”，而是把它当成新架构里必须严肃处理的核心资产。

---

3）迁移不是简单搬表，而是“数据语义重建”

你可以理解为：

不是把数据复制过去就行，
而是要重新判断：这个数据在 V2 里应该长什么样。

代码落点

• src/main/data/migration/v2/migrators/ChatMigrator.ts
• src/main/data/migration/v2/migrators/README-AssistantMigrator.md
• src/main/data/migration/v2/migrators/mappings/AgentsDbMappings.ts
• src/main/data/migration/v2/migrators/mappings/__tests__/AgentsDbMappings.test.ts...

This pull request was created from Copilot chat.