From ddd2d2cbd824489ab68d40a1f8c7c541e0261657 Mon Sep 17 00:00:00 2001 From: eaiadmin Date: Thu, 17 Sep 2026 23:38:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AF=B9=E8=B1=A1=E5=91=BD=E5=90=8D?= =?UTF-8?q?=E8=A7=84=E8=8C=83=20AR09=20=E4=B8=8E=E6=A0=87=E5=87=86?= =?UTF-8?q?=E5=8C=96=E8=AE=A8=E8=AE=BA=E6=96=87=E6=A1=A3=E5=85=A5=E5=BA=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/02_Architecture/AR09_Object_Naming_Standard.md（规范性文件，非设计稿）： 十节结构 —— 原理 / 判据 / 对象术语表 / 五层命名规范 / 命名模式库 / 如何检查（人工五问 + 6 个机器守卫）/ 如何修复（迁移顺序 + 改名六步法）/ 现状问题登记（逐条带 file:line）/ 反例库 / 修订记录。 核心判断：名称即契约，改名前先查已靠名字建立的协议表 - 02_Architecture/README.md 登记 AR09，并说明其规范性定位（约束新增代码， 与 TOP_CODING_RULES.md 的 G03 配套），与 AR01–AR08 设计稿区别 - 收入本轮讨论与调研文档：对象命名标准化清单、对象标准化与解耦总则、 六层架构与三对象建设重点阶段性复盘、目录结构化迁移说明、 AionUi 对照分析两篇 Co-Authored-By: Claude Code --- .../AR09_Object_Naming_Standard.md | 482 +++++++++++++ docs/02_Architecture/README.md | 2 + ...9-17_六层架构与三对象建设重点阶段性复盘.md | 267 +++++++ docs/2026-09-17_对象命名标准化清单.md | 549 ++++++++++++++ ...nUi助手到pj0235三层映射表与首个样板方案.md | 182 +++++ .../AionUi源码深度扫描与办公智能体架构对比.md | 681 ++++++++++++++++++ docs/对象标准化与解耦总则.md | 345 +++++++++ docs/目录结构化迁移说明-专员技能应用.md | 147 ++++ 8 files changed, 2655 insertions(+) create mode 100644 docs/02_Architecture/AR09_Object_Naming_Standard.md create mode 100644 docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md create mode 100644 docs/2026-09-17_对象命名标准化清单.md create mode 100644 docs/AionUi助手到pj0235三层映射表与首个样板方案.md create mode 100644 docs/AionUi源码深度扫描与办公智能体架构对比.md create mode 100644 docs/对象标准化与解耦总则.md create mode 100644 docs/目录结构化迁移说明-专员技能应用.md diff --git a/docs/02_Architecture/AR09_Object_Naming_Standard.md b/docs/02_Architecture/AR09_Object_Naming_Standard.md new file mode 100644 index 0000000..fae9f9e --- /dev/null +++ b/docs/02_Architecture/AR09_Object_Naming_Standard.md @@ -0,0 +1,482 @@ +# AR09 对象命名规范（Object Naming Standard） + +> **版本**：V1.0 +> **日期**：2026-09-17 +> **性质**：规范性文件（normative）。「必须 / 禁止」是硬约束，「应当」是默认做法，「建议」可依场景取舍。 +> **与 TOP_CODING_RULES.md 的关系**：G03（变量命名锚定）给的是四条底线；本文件是它的展开与可执行化。 +> **冲突时以 TOP_CODING_RULES.md 为准**，本文件不得放宽 G03。 +> **适用范围**：后端 Go、数据库、API、前端 Vue、注释与文档。 +> **读者**：写代码的人 + 执行命名清理的 AI。 + +--- + +## 一、原理：为什么命名值得单独立一份规范 + +### 1.1 命名是唯一零成本的文档 + +注释会过期，文档会失联，只有名字跟着每一次调用出现在读者眼前。 +一个名字读错，读者付出的不是"多看一眼"，而是**先建立错误的心智模型，再用后续所有代码去纠正它**。 + +### 1.2 名称即契约 + +大多数命名失误只是难读，但有一类会**静默断链**：当某个标识符是靠名字派生、靠名字配对、靠名字跨进程传递时，改名就等于改协议，而编译器与测试都不会拦。 + +本项目已经存在的这类协议： + +| 靠名字建立的协议 | 位置 | 改名后果 | +|---|---|---| +| `action_key` 由 `action_title`（中文）派生，前后端靠它配对 | `specialistFlow.js` 的 `findLatestRun` | 改文案 → 配对静默失效，UI 永远显示"未执行" | +| 路由 query 参数 `specialist/skill/prompt` | `appCatalog.js` → `SmartAssistantPage.vue` | 写读不同名 → 参数被静默丢弃（见 §8.1） | +| 专员 / 技能的 `key` | `specialist.key`、`skill_definition.key`、`ValidSkillKeys` | 改 key → 任务挂载、技能绑定、种子数据全部对不上 | +| 种子数据的 key | `seedSpecialistRuleFiles` 等 | 拼错 → 启动时只能靠显式校验挡住，否则静默漏种 | + +**所以：改名前必须先问"这个名字有没有被别人当协议用"。** 这是本文件第七节的由来。 + +### 1.3 认知债会复利 + +一个失真的名字不会自己消失。它会被复制（新代码照着写）、被引用（更多地方依赖这个错名）、被解释（文档里加一段"注意这里其实是指……"）。 +三个月后，改它的成本是今天的十倍。**失真名字的唯一低成本修复窗口，是它刚被写下的那一刻。** + +### 1.4 命名错误逃得过编译器和测试 + +拼写错误的变量名编译不过，语义错误的名字编译得过。 +`const app = specialistCatalog.getByKey(key)` 一切正常，只是每个读它的人都要在脑子里纠正一次。 +**这类错误没有任何自动化工具能替你发现——除非专门写一个（见第六节）。** + +### 1.5 所以要在"新增"那道口子上拦 + +追改历史代码性价比低。命名规范的绝大部分价值，发生在**新代码被写下的那五秒钟**：选名字时对照一次术语表。 + +--- + +## 二、判据：一个名字好不好，用这五条量 + +| 判据 | 含义 | 反例 | +|---|---|---| +| **准确性** | 名字指向的对象，和它实际装的东西是同一个 | `businessApps` 装的是专员 | +| **唯一性** | 一个概念全项目只有一个名字；一个名字只指一个概念 | `contract-review` 既是专员 key 又是技能 key | +| **一致性** | 同类东西的写法统一（`ID` 就永远 `ID`） | `UserID` 与 `mediaId` 并存 | +| **可检索性** | 能被 grep 精确找到 | `id`、`data`、`res`、`info` | +| **稳定性** | 不会因为阶段变化而变成谎言 | `newUser`、`tempData`、`userList2` | + +### 冲突时的优先级 + +```text +外部标准 > 一致性 > 准确性 > 书写简短 +``` + +- **外部标准最高**：第三方规范定义的字段名（金蝶的 `FCustId`、OOXML 的 `sldId`、HTTP 头）**必须按字符照抄**，不许"美化"。美化等于自建一层翻译，且翻译层迟早漏项。 +- **一致性高于准确性**：`ID` 和 `Id` 哪个更好看无关紧要，全项目只能有一个。两种写法并存时，读代码的人每次都要停下确认"这是同一个东西吗"。 +- **准确性高于简短**：宁可名字长一点，也不要让人误判对象边界。 + +--- + +## 三、对象术语表 + +### 3.1 正式术语（必须使用） + +| 对象 | 正式名 | 代码落点 | 说明 | +|---|---|---|---| +| 专员 | `specialist` | `model/specialist.go` | 可挂载到任务的数字员工 | +| 技能 | `skill` | `model/skill_definition.go` | 任务级能力定义 | +| 应用 | `app` | `model/app_definition.go` | 长程任务运行壳 | +| 连接器 | `connector` | `internal/connector/*` | 外部系统接入 | +| 动作 | `action` | `model/action_definition.go` | 技能调用的底层执行单元 | +| 任务 | `task` | `model/worker_task.go` | 工作实例容器 | + +### 3.2 兼容术语（限制使用，禁止扩散） + +| 历史词 | 现状 | 允许出现的位置 | 禁止 | +|---|---|---|---| +| `role` | 旧心智残留 | 无。已无正式对象叫 role | 不得用于新变量、新文件名、新字段 | +| `assistant` | 只指"默认通用助手"这一件事 | `assistant.js`（默认聊天接口）、`smart-assistant`（默认技能 key）、`general-assistant`（默认专员 key） | 不得用来指代专员、技能或对象类型 | +| `capability` | 泛能力总称 | 仅限口语与文档泛指 | 不得充当对象级文件名或字段名 | +| `businessApps` | 历史静态变量，装的是专员 | 现有代码 | 禁止新增引用；建议整块删除（见 §8） | +| `availableSkills` | 静态 fallback 技能源 | 现有代码 | 禁止新增引用；建议改名 `staticSkillCatalog` | +| `worker` | 任务执行子系统前缀 | `worker_task` / `worker_run` / `worker_artifact` / `/api/worker/*` / `workerRuntime.js` | **待拍板**（见 §3.4） | + +### 3.3 共名冲突登记 + +同一个字符串同时是两个对象的标识符 —— 这是既成事实，不强行改，但要靠注释和测试守住，**并且不再新增**： + +| 字符串 | 身份一 | 身份二 | +|---|---|---| +| `contract-review` | 专员 key | 技能 key | +| `report-generation` | 专员 key | 技能 key | + +处理要求： +1. `model/skill_keys.go` 必须保留说明注释（已有）。 +2. 任何"按 key 查对象"的代码，必须写明查的是哪一类，不允许出现 `getByKey(key)` 这种不区分对象类型的调用。 +3. `skill_keys_test.go` 那种"前后端 key 集合双向对齐"的测试必须保留 —— 它是这两个身份不互相污染的唯一保障。 + +### 3.4 待拍板：`worker` 这个命名空间 + +现状：`/api/worker/tasks`、`model/worker_task.go`、`worker_run.go`、`worker_artifact.go`、`api/worker.js`、`store/workerRuntime.js`。 + +`worker` 不在正式术语表里，但已经形成一整套一致的前缀。两个选择： + +- **A. 收编为正式术语**：定义为"任务执行子系统"，写进 §3.1。成本为零，立刻合法。 +- **B. 重命名**：把 `worker_*` 收敛为 `task_*`。语义更准，但要动表名、API 路径、前端模块，成本高。 + +**建议 A**。理由：它已经自洽，且不与任何人抢名字；真正会误导的是 §8 里那些"名实相反"的（`businessApps` 装专员、`capability` 装 skill），而不是一个自洽的子系统前缀。 + +--- + +## 四、分层规范 + +### 4.1 后端 Go + +| 项 | 规范 | 禁止 | +|---|---|---| +| 类型名 | `CamelCase`，对象名 + 用途后缀：`Specialist`、`SkillDefinition`、`WorkerTask` | `Data`、`Info`、`Manager`、`Helper` 这类空词 | +| 字段名 | `CamelCase` | 业务字段用 `Id`/`Data`/`Res` 这类模糊名 | +| **`ID` 写法** | **一律 `ID`**：`UserID`、`TaskID`、`RouteID`、`AIRouteID` | `UserId`、`mediaId`、`sourceId` | +| json tag | **一律 snake_case**：`json:"specialist_key"` | `json:"skillKey"`、`json:"createdAt"` | +| 外部标准字段 | 原样保留，并在字段注释里写明来源系统 | 美化、改大小写、加前缀 | +| 常量 | `CamelCase`，同族常量同前缀 | 裸数字、魔法字符串 | +| 接收器 | 与类型同义的单字母或短名（`s`、`req`） | 无意义的 `this`、`obj` | + +**允许的例外（白名单，只有这些）**： + +- 第三方 API 字段：`FCustId`、`FUseOrgId`、`FStockId` 等 ERP 字段 +- 文档格式规范属性：OOXML 的 `sldId`、`styleId` + +例外必须在字段旁注明来源，否则下一个人会以为是漂移。 + +### 4.2 数据库 + +| 项 | 规范 | +|---|---| +| 表名 | 单数 snake_case：`specialist`、`skill_definition`、`worker_task` | +| 列名 | snake_case，与 Go 字段的 json tag 一致 | +| 外键 | `<对象>_id`：`specialist_id`、`task_id` | +| 时间 | `<动词>_at`：`created_at`、`finished_at` | +| JSON 列 | 后缀 `_json`，并在字段注释写明结构（如 `allowed_skills` 存的是字符串数组） | +| 布尔列 | 语义正向：`enabled`、`pinned`；禁止 `not_xxx` | +| 改名 | **`AutoMigrate` 不会改列名**，必须手写迁移（P06.1） | + +### 4.3 API + +| 项 | 规范 | 现状 | +|---|---|---| +| 路径 | 复数资源：`/api/specialists`、`/api/skills`、`/api/apps` | ✅ 已一致，保持不回退 | +| 路径参数 | snake_case：`/api/knowledge/audit/{source_id}` | ❌ 现在是 `{sourceId}`、`{recordId}` | +| query 参数 | snake_case，且**跨层同名** | ❌ 见 §8.1 | +| 入口协议 | 对象入口 query 必须**定义在一处常量**，写读都引它 | ❌ 现在两边各写各的 | + +**入口协议强制要求**：任何"从 A 页面带参数打开 B 页面"的协议，参数名必须是**共享常量**，不允许两边各写字符串字面量。这是 §8.1 事故的直接教训。 + +### 4.4 前端 + +| 项 | 规范 | +|---|---| +| 文件名 | store：`<对象>Catalog.js`（如 `specialistCatalog.js` / `skillCatalog.js` / `appCatalog.js`）；API：`<对象>.js`（如 `specialist.js` / `worker.js`） | +| catalog store 模板 | `normalize` → `hydrate` → `getByKey` / `getByPath`（`specialistCatalog.js` 为标准范本） | +| computed | `currentPresentation`，对象名必须准确 | +| 局部变量 | **必须与对象一致**。`const app = specialistCatalog.getByKey()` 是禁止的 | +| 布尔 | `is` / `has` / `can`，禁止否定式 | +| 容器 | 单个 `item`，集合 `items`，映射 `Map`，列表 `List` | + +### 4.5 注释与文档 + +- 历史兼容字段必须在注释里写明"历史兼容 / 待迁移"，否则会被当成正式命名复制。 +- 文档里的文件引用**用相对路径**，禁止 `file:///home/<某人的用户名>/...` 这类绝对路径 —— 别人 clone 下来全是死链（违反 G18）。 + +--- + +## 五、命名模式库（做法） + +### 5.1 后缀表 + +| 后缀 | 含义 | 例 | +|---|---|---| +| `_id` | 主键 | `task_id` | +| `_key` | 业务标识（字符串，可读） | `specialist_key`、`action_key` | +| `_at` | 时间点 | `finished_at` | +| `_count` | 计数 | `retry_count` | +| `_json` | 存 JSON 的文本列 | `allowed_skills`、`input_json` | +| `_ms` / `_bytes` | **单位必须进名字** | `timeout_ms`、`size_bytes` | + +**单位不写进名字是隐性 bug 源**：`timeout` 是秒还是毫秒？读的人只能翻实现。 + +### 5.2 布尔 + +`is` / `has` / `can` / `should` + 正向语义。禁止 `flag`、`status`（名词当布尔用）、`notXxx`（双重否定）。 + +### 5.3 容器 + +`item`（单） / `items`（集） / `xxxMap`（映射） / `xxxList`（有序）。让读者不点进定义就知道能不能 `.map()`。 + +### 5.4 函数动词表 + +同一件事只用一个动词，禁止同义混用： + +| 动词 | 职责 | 禁止替代 | +|---|---|---| +| `normalize` | 把外部来的数据整理成内部统一形状 | `format` / `convert` / `adapt` | +| `hydrate` | 把目录/缓存数据装进运行时 | `load` / `init` | +| `resolve` | 按规则算出一个结果（可能多来源） | `get` / `find` | +| `load` | 从存储读 | `fetch` / `read` | +| `build` | 组装（无 IO） | `create` / `make` | +| `ensure` | 没有就补上（幂等） | `check` / `init` | +| `apply` | 把某份数据/规则作用到目标上（幂等） | `update` / `set` | +| `parse` | 字符串 → 结构 | `decode` / `read` | + +### 5.5 禁止词表 + +作为**业务标识符**禁止使用（框架/标准库要求时除外）： + +`id`、`data`、`info`、`res`、`req`（局部除外）、`tmp`、`temp`、`obj`、`item`（无上下文时）、`list`（无前缀时）、`util`、`common`、`helper`、`manager`、`handler`（无对象前缀时）、`flag`、`value` + +理由：不是难看，是**搜不到**。grep 出几百条结果等于没有结果（G03 的最小长度约束就是这个意思）。 + +### 5.6 缩写表 + +只有下表内的缩写允许使用，其余一律写全： + +| 允许 | 全称 | +|---|---| +| `ID` | identifier | +| `URL` | uniform resource locator | +| `API` | application programming interface | +| `JSON` | JavaScript object notation | +| `AI` | artificial intelligence | +| `OCR` | optical character recognition | +| `PPT` / `PDF` | 文件格式 | +| `req` / `res` | 仅限 HTTP 处理函数的局部变量 | + +禁止：`usr`、`mgr`、`svc`、`num`、`str`、`val`。（HTTP 处理函数的局部 `req` / `res`、Go 的 `ctx`、局部配置 `cfg` 属公认短名，不算违规。） + +--- + +## 六、如何检查 + +### 6.1 人工五问（写名字时问自己，review 时问作者） + +1. 这个名字指的是**哪个对象**？能一句话说出它是 specialist / skill / app / connector / action / task 中的哪一个吗？ +2. 换个人读，会不会理解成**另一个对象**？ +3. 全项目 grep 一下，**是不是只有这一种写法**？ +4. 改它会不会断掉**靠名字派生的协议**（§1.2 的表）？ +5. 它是**外部标准**吗？是 → 按字符照抄，一个字都不许动。 + +### 6.2 机器守卫（建议落成一个 Go test，与 `skill_keys_test.go` 同一位置） + +已有先例：`model/skill_keys_test.go` 读 `frontend/src/config/workbench.js`，把前端技能 key 与后端 `ValidSkillKeys`（22 个）双向对齐。 +**命名守卫照这个模式写**，每条都要带白名单，否则会被误报淹没： + +| # | 查什么 | 正则 | 白名单 | +|---|---|---|---| +| A | Go 里 `Id` 写法 | `\b[A-Za-z]+Id\b` | ERP 字段（`FCustId` 等）、OOXML（`sldId`、`styleId`） | +| B | camelCase json tag | `json:"[a-z]+[A-Z]` | 无 | +| C | camelCase 路径参数 | `\{[a-z]+[A-Z][A-Za-z]*\}` | 无 | +| D | 禁用词当业务标识符 | 按 §5.5 词表 | 框架约定（`req` 局部） | +| E | 前端 skill key ↔ 后端 `ValidSkillKeys` | 已有的 `skill_keys_test.go` | — | +| F | 入口协议写读对称 | 见下 | — | + +**守卫 F 的做法**（最重要，也最难自动化）： +入口协议不要靠扫描源码配对，而是**把参数名提成共享常量**（如 `frontend/src/config/objectEntry.js` 导出 `ENTRY_PARAMS = { specialist: 'app_specialist', ... }`），写端读端都引它。 +这样 F 就从"看不见的约定"变成了"编译器能查的引用"，守卫 F 也就不需要了 —— **能用结构消除的检查，不要用扫描去补**。 + +### 6.3 跨层对齐检查 + +任何"同一份清单在前后端各写一遍"的东西，都必须有双向对齐测试： + +- 技能 key：前端 `availableSkills` ↔ 后端 `ValidSkillKeys` ✅ 已有 +- 专员 key：前端静态目录 ↔ 后端种子数据 ⬜ 建议补 +- 入口协议参数名：⬜ 建议补（提到共享常量后自然消解） + +### 6.4 检查结果的严重性分级 + +| 级别 | 判据 | 处理 | +|---|---|---| +| **P0** | 名字不一致导致**功能已断**（写读不同名、配对失效） | 当 bug 修，立即 | +| **P1** | 跨层漂移，会被新代码复制（json tag、路径参数、失真局部变量） | 本迭代内 | +| **P2** | 名字带旧词但语义尚可推断（`RoleKind`、`currentRolePresentation`） | 排期做，别急 | +| **P3** | 死代码 / 无人引用的历史变量 | **先判生死，再决定改名还是删除** | + +**注意 P3 的陷阱**：给一份没人读的静态数据改名，等于给它续命。 +先确认引用数，是 0 就删（见 §8.9）。 + +--- + +## 七、如何修复 + +### 7.1 迁移顺序：由内到外，最后才碰数据库 + +```text +① 局部变量 +② 前端协议 / 入口参数 +③ 文件名 +④ 字段名 / 数据库列名 +``` + +理由： +- ① 影响面最小、可读性收益最直接、无跨进程风险。 +- ② 优先于 ③ —— 协议不统一会**持续产生新的分叉**，不先堵住，你改完还会被新代码重新搞乱。 +- ④ 放最后：牵动数据库，而 SQLite 的列改名 `AutoMigrate` 不管，必须手写迁移，风险最高、回滚最难（G05：大规模操作前先备份）。 + +### 7.2 改名六步法 + +1. **定名**：对照 §3 术语表 + §5 模式库，写下新名字，并回答 §6.1 的五问。 +2. **查引用**：`grep -rn "<旧名>"`，范围必须包含 + - 源码 / 模板 / 样式 + - **字符串字面量**（路由、query key、事件名、localStorage key） + - **JSON tag、SQL 语句、迁移脚本** + - 配置、种子数据、测试、e2e、文档、注释 +3. **判协议**：这个旧名是否出现在 §1.2 那张表里？是 → 这不是改名，是改协议，写下来通知所有相关方（含前端）。 +4. **一次改完**：不留双写法。兼容层是唯一例外，且**必须带删除条件**（"等 X 上线后删除"），否则兼容层会永久化。 +5. **验证**（按 G04，不靠感觉）： + - `go build ./...` + `go test ./...` exit 0 + - `npm run build` exit 0 + - **真起 dev server，在浏览器里走一遍受影响路径** —— 编译通过不代表功能没断（§8.1 就是编译全绿但功能已断） +6. **提交**：一次提交只装一件事（G14）；提交信息写**为什么改名**，不只写改了什么。 + +### 7.3 会静默断链的改名（动手前必读） + +| 改名对象 | 为什么危险 | 必须同时检查 | +|---|---|---| +| `action_key` / `action_title` | key 由中文标题派生，前后端靠名字配对 | `specialistFlow.js` 的 `findLatestRun`；任何改文案的地方 | +| 路由 query 参数 | 写端读端是两处独立字面量，编译不报错 | 全链路 grep，或改成共享常量 | +| 专员 / 技能的 `key` | 任务挂载、技能绑定、审计日志全按 key 存 | `worker_task.specialist_key`、`ai_call_log.specialist_key`、种子数据 | +| 种子数据的 key | 拼错或改名 → 与库中现有记录对不上 | 启动时校验（`applySpecialistRuleFiles` 已有） | +| 外键列名 | 老库有数据，改列名要迁移 | 手写迁移 + 备份 + 副本验证（P06.1/P06.7） | + +**判断口诀**：这个名字如果在**两个不同的进程/两次运行之间**传递过，它就是协议，不是名字。 + +### 7.4 各级的具体做法 + +**① 局部变量** +直接改，改完读一遍上下文确认没有同名遮蔽（shadowing）。 + +**② 前端协议 / 入口参数** +不要只是"改一致"，而是**提成共享常量**： +```js +// frontend/src/config/objectEntry.js +export const ENTRY_PARAMS = { + specialist: 'app_specialist', + skill: 'app_skill', + prompt: 'app_prompt', +} +``` +写端 `params.set(ENTRY_PARAMS.specialist, ...)`，读端 `route.query[ENTRY_PARAMS.specialist]`。 +这样下一个参数不会再各写各的。 + +**③ 文件名** +- 只改名：`git mv`，保持历史可追溯。 +- 一文件两职责：先拆文件，再改名，**同时改注册点**（`router.go` 等）。只拆一半会留下一个名实仍不符的残文件，比不改更糟。 + +**④ 字段名 / 列名** +1. 先备份（`data/backups/` 内置 `VACUUM INTO`，D24）。 +2. **在库副本上验证**新列/新列名能被正确读写（P06.1）。 +3. 写一次性迁移；老列在确认无引用前不删。 +4. 同步改 json tag、前端读取点、文档字段表。 +5. 改完立即跑一遍 P06.2 的做法：**探测脚本用完即删**，别留成断言"升级前状态"的测试。 + +### 7.5 回滚与提交 + +- 一次提交一件事：改名与功能改动**不要混在一个提交里**（否则回滚会带走功能）。 +- 改名列必须写明"旧名 → 新名"，方便 `git log --follow` 与后来人搜索。 +- 如果改名波及数据库，提交信息里写明迁移步骤与验证结果。 + +--- + +## 八、本项目现状（2026-09-17 实测） + +> 以下每条都在代码里核实过，标了行号。级别按 §6.4。 + +### 8.1 【P0｜功能已断】对象入口协议写读不对称 + +- **写端**：[appCatalog.js:140-142](../../eai_agentplatform/frontend/src/store/appCatalog.js#L140-L142) 拼 `specialist` / `skill` / `prompt` +- **读端**：`SmartAssistantPage.vue:603`、`604`、`619` 读 `app_specialist` / `app_skill` / `app_prompt` +- **全仓库核实**：没有任何地方读不带前缀的，也没有任何地方写带前缀的 +- **后果**：从能力目录点应用进工作台，预置的专员 / 技能 / 提示词**三个参数全部被静默丢弃**，不报错。用户看到的是"点进去还是空的" +- **注意**：这是 bug，不是风格问题。按 §7.4② 提成共享常量一起修 + +### 8.2 【P1】camelCase json tag + +`my_app_center.go:36-41` 六处：`installState`、`skillKey`、`createdAt`、`iconText`、`coverTone`、`isCustomApp`，是全站 snake_case 体系里仅有的例外，且集中在同一个结构体。 +→ 改 snake_case，前端同步。 + +### 8.3 【P1】URL 路径参数 camelCase + +`api/knowledge.go:97` 的 `{sourceId}`、`api/exam.go:975` 的 `{recordId}`。 +→ 改 snake_case（`{source_id}`、`{record_id}`），同步前端调用处。 + +### 8.4 【P1】局部变量失真 + +`SmartAssistantPage.vue:314`：`const app = specialistCatalog.getByKey(key)` —— 拿到的是专员，却叫 `app`。 +注：它所在的 computed 名字是对的（`currentSpecialistPresentation`，`kind: 'specialist'`），失真仅限这一个局部变量。 +→ 改 `specialist`。**P1 原因：它会被后续代码照抄。** + +### 8.5 【P2】`role` 心智残留 + +`SmartAssistantPage.vue:354` 的 `currentRolePresentation`，把 assistant / specialist / skill 三类收在一个 role 概念下。 +→ 收敛为 `currentObjectPresentation`，或按 §3.1 拆成三份。 + +### 8.6 【P2】`RoleKind` 字段名带旧词 + +`model/skill_definition.go:13`：`RoleKind`，注释 `assistant / specialist / skill`。 + +- **澄清**：这个字段本身不是垃圾，语义是"这条定义属于哪类对象"（`skill_definition` 表同时装 assistant / specialist / skill 三类记录）。问题只在名字里的 `role` 让人误读成"角色"。 +- **改名方向**：`object_kind`（准确）。 +- **成本提醒**：改字段名要同时动 ① 数据库列 `role_kind` ② json tag ③ 前端读取点。SQLite 改列名 `AutoMigrate` 不管，得手写迁移。 +- **建议**：**默认方案是保留字段名，在注释与文档里标注语义**；真要改，按 §7.4④ 走完整流程，不要顺手改。 + +### 8.7 【P2】`capability_definition.go` 名实不符 + +`internal/api/capability_definition.go` 实际装了两套东西：`skillDefinitionReq` 5 个 handler + `actionDefinitionReq` 5 个 handler（共 15 个函数）。 + +- **不能只改名为 `skill_definition.go`** —— action 的 handler 还在里面，改完名实仍然不符。 +- **两个正确方案**：① 拆成 `skill_definition.go` + `action_definition.go`，**同时改 `router.go` 注册**；② 不拆，改名 `skill_and_action_definition.go`。 +- **要害**：`capability` 不是正式对象，让它当文件名会持续制造一个不存在的一级概念。 + +### 8.8 【P1】`worker` 命名空间待拍板 + +`/api/worker/tasks`、`worker_task.go`、`worker_run.go`、`worker_artifact.go`、`api/worker.js`、`store/workerRuntime.js`。 +→ 见 §3.4，建议收编为正式术语，成本为零。 + +### 8.9 【P3】`businessApps` 疑似死代码 —— 建议删，不建议改名 + +- **定义**：`config/workbench.js:1434`，内容是**专员目录**（第一条即 `contract-review` 合同审查专员，带 `tier` / `workerType` / `roleCard`），名字与内容相反 +- **引用情况**：模块外**零引用**；仅 `workbench.js` 内部 6 处自用（`2232` 按 legacy 路由查、`2236` 按 tier 筛、`2240` 数量、`2244` 可升级数、`2252-2253` dw/adw 统计） +- **建议**：先确认那几个统计入口是否还有页面在用 → 没有就**整块删除**；有就随使用者一起迁到 `specialistCatalog` +- **不要**改名成 `staticSpecialistCatalog` —— 那等于给一份没人读的静态副本续命 + +### 8.10 【P3】`availableSkills` 静态 fallback + +`config/workbench.js:105`，22 条技能定义，被 4 处用于兜底：`store/skillCatalog.js:4`、`components/chat/PlusMenu.vue:183`、`config/projectTemplates.js:19`、`components/chat/CurrentObjectChip.vue:55`。 +→ 确认 `skillCatalog` 覆盖完整后，改名 `staticSkillCatalog`（语义准确），或一并删除。 + +### 8.11 【已守住，勿回退】 + +- 后端对象 API 命名已清楚：`/api/specialists`、`/api/skills`、`/api/apps`、`/api/actions`（`router.go:43-50`） +- 前端 catalog store 命名已规范：`specialistCatalog.js`（`normalizeSpecialist` / `getByKey` / `getByPath`）是标准范本 +- 技能 key 前后端对齐测试已有（`model/skill_keys_test.go`，22 个 key） + +--- + +## 九、反例库（真实事故） + +| 症状 | 根因 | 正确做法 | +|---|---|---| +| 从应用目录点进去，工作台是空的（专员/技能/提示词都没带上） | 写端读端各写一套 query 字面量，编译不报错 | 参数名提成共享常量（§7.4②） | +| `const app = specialistCatalog.getByKey()` 读起来像在查应用 | 局部变量照抄了旧的"应用"心智 | 变量名必须与对象一致 | +| `businessApps` 里装的全是专员 | 历史命名未随对象迁移 | 名实不符时优先删，其次改名 | +| `capability_definition.go` 里装的是 skill 和 action | 中间态概念被固化成了文件名 | 让已经消失的概念从文件名里消失 | +| `RoleKind` 字段名比模型名旧一代 | 模型改名了，字段没跟上 | 一套迁移要改到底，不能只改外层 | +| 改了任务步骤的中文文案，UI 就永远显示"未执行" | `action_key` 由中文标题派生，名字成了协议 | 能不派生就不派生；非派生不可就加配对检查 | +| `contract-review` 查出来两条不同对象的记录 | 同一字符串被两个对象共用 | 共名要登记 + 用测试守住 | +| 差点把 ERP 的 `FCustId` "美化"成 `FCustId`→`CustID` | 误以为一致性高于一切 | 外部标准优先级最高，照抄 | +| 文档里写 `file:///home/<用户名>/...` 链接 | 本机可点，他人全断 | 文档引用一律相对路径 | + +--- + +## 十、修订记录 + +| 版本 | 日期 | 变更 | +|---|---|---| +| V1.0 | 2026-09-17 | 首版。原理 / 判据 / 术语表 / 分层规范 / 模式库 / 检查 / 修复 / 现状 / 反例库 | + +--- + +*注：本文件是命名问题的最高依据，与 `TOP_CODING_RULES.md` 配套使用。术语表（§3）变更属于架构级决策，改前先更新 `PROJECT_STATE.md` 的已拍板决策表。* diff --git a/docs/02_Architecture/README.md b/docs/02_Architecture/README.md index a5769a0..99ae799 100644 --- a/docs/02_Architecture/README.md +++ b/docs/02_Architecture/README.md @@ -7,6 +7,7 @@ > `AR05`–`AR08` 是 2026-09-16 / 17 的工作台设计稿，**不属于 V1.1 快照**，其中 `AR08` 为部分被取代稿，取用前先读其文首补注。 > 当前产品导航与工作台口径，请以 `docs/01_System_Overall/SY22_Role_Skill_App_Unified_Task_Architecture.md` 为准： > `新建任务 / 项目 / 专员·技能·APP·连接器 / 长程APP / 知识库 / 后台管理 / 我的` +> **`AR09` 是规范性文件（对象命名规范），不是设计稿。** 它约束新增代码的命名，并登记了当前已核实的命名问题与修复流程；与 `TOP_CODING_RULES.md` 的 G03 配套使用。 ## 文件清单 @@ -21,3 +22,4 @@ | `AR06_Skill_Packaging_Specification.md` | 技能文件规范（技能 = 定义文件 + 执行器 + 结果组件，不以独立页面存在） | | `AR07_Architecture_Alignment_Audit.md` | 架构对齐确认与本轮修复范围（收敛两套并行模型的确认记录） | | `AR08_Role_Interaction_Design.md` | AI 角色与工具统一交互设计（**部分被取代**：不跳页结论已采纳，「数字技术员」对象已废弃，见文首补注） | +| `AR09_Object_Naming_Standard.md` | 对象命名规范（**规范性文件**：原理 / 判据 / 术语表 / 分层规范 / 检查守卫 / 修复流程 / 现状问题登记 / 反例库） | diff --git a/docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md b/docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md new file mode 100644 index 0000000..09dde1b --- /dev/null +++ b/docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md @@ -0,0 +1,267 @@ +# 六层架构与三对象建设重点阶段性复盘 + +> 日期：2026-09-17 +> 性质：对前序讨论的客观复盘，不替代既有总架构文档 +> 关联文档： +> - `docs/01_System_Overall/SY21_Unified_Role_Skill_Action_Architecture.md` +> - `docs/01_System_Overall/SY22_Role_Skill_App_Unified_Task_Architecture.md` +> - `docs/对象标准化与解耦总则.md` + +--- + +## 一、这份复盘要解决什么 + +前序讨论中，围绕以下问题进行了多轮来回： + +- 现有六层架构是否还成立 +- 专员 / 技能 / 应用三个对象应不应该成为当前建设重点 +- 当前是否需要优先补绑定关系 +- AionUi 的经验应该学到什么程度 + +这份复盘的目标不是重写总架构， +而是把前面讨论中哪些判断成立、哪些判断说过头了，正式收口。 + +--- + +## 二、已经确认成立的判断 + +### 1. 当前系统确实处于“后端有对象表，前端曾长期存在静态目录”的混合态 + +这个判断成立。 + +虽然近期已经持续推进目录解耦， +但从整体历史包袱和代码结构看， +系统前期确实存在： + +- 后端有对象模型和接口 +- 前端以静态配置驱动大量真实目录 + +这也是后续做对象标准化与目录统一的现实起点。 + +### 2. “先强对象，再补关系”是当前阶段更合理的优先级 + +这个判断成立。 + +原因不是关系层不重要， +而是当前对象成熟度还没有达到“复杂关系优先”的阶段： + +- 专员还没有形成强编排能力 +- 技能还没有强壮到值得被大量稳定复用 +- 应用当前更像产品化入口，而不是复杂能力编排器 + +因此，当前更合理的顺序是： + +```text +先把专员、技能、应用各自做强 +再在成熟度足够时补关系层 +``` + +### 3. AionUi 最值得学习的是对象资产化，而不是总架构替换 + +这个判断成立。 + +当前对 AionUi 的借鉴边界应明确为： + +- 学它的助手/员工对象化 +- 学它的规则资产化 +- 学它的技能包思维 +- 学它的运行态工作台思维 + +不应盲目学习： + +- Electron 外壳 +- 个人工具导向产品形态 +- 创意娱乐类助手堆叠 +- 过度端侧逻辑 + +--- + +## 三、前序讨论中说过头的地方 + +### 1. 不能因为三个对象重要，就推导出“应该改总架构” + +这个推导证据不足。 + +三个对象重要，说明： + +- 第五层对象层需要做强 +- 第六层运行治理层需要做实 + +但这并不自动构成“六层架构应被替代”的理由。 + +要否定既有总架构，至少应出现下列情况之一： + +1. 层级职责定义错误 +2. 多层长期重叠、互相冲突 +3. 关键对象在原架构中无法安放 +4. 原架构直接阻碍产品落地 + +截至本次复盘，没有充分证据表明六层架构已满足上述否定条件。 + +### 2. “当前建设重点”不能被误说成“主架构发生替换” + +更准确的表达应为： + +**六层架构不变，当前建设重点落在第五层对象层与第六层运行治理层。** + +也就是说： + +- 这是架构内聚焦 +- 不是架构替换 + +--- + +## 四、关于六层架构的最终判断 + +## 4.1 六层架构继续成立 + +`SY21` 与 `SY22` 形成的六层总架构继续有效： + +1. 外部连接层 +2. 本体与语义上下文层 +3. 总线与编排层 +4. 能力层 +5. 对象层 +6. 工作台与运行治理层 + +特别是 `SY22` 已经明确把第五层升级为： + +```text +对象层（Expert / Skill / App） +``` + +这说明六层架构本身已经能够容纳“专员 / 技能 / 应用”三类核心对象， +并不存在“对象出现后就装不下”的结构性问题。 + +## 4.2 六层架构仍然有意义 + +六层架构的意义在于它仍然能解释整个平台为什么成立： + +- 外部系统如何接入 +- 语义和对象如何统一 +- 能力如何分层 +- 任务如何运行 +- 治理如何落地 + +因此它仍应继续作为： + +- 平台总架构 +- 长期演进底图 +- 文档与治理总语言 + +而不是被轻易推翻。 + +## 4.3 当前不需要改架构，当前需要做的是在原架构内把重点层做强 + +当前最合理的做法不是改层数， +而是继续在既有六层框架内推进： + +- 第五层：对象标准化、对象独立化、对象目录统一 +- 第六层：任务容器、状态、产物、留痕、项目运行统一 + +第一到第四层仍然成立， +但当前不应继续投入过多抽象设计精力。 + +--- + +## 五、关于三个对象的当前建设重点 + +### 1. 专员 + +当前优先级应放在： + +- 身份稳定 +- 规则稳定 +- 开场与引导稳定 +- 能承接任务 + +而不是强求它现在就大量调技能。 + +### 2. 技能 + +当前优先级应放在： + +- 单独拿出来就有价值 +- 输入输出稳定 +- 结果可靠 +- 产物真实可用 + +技能不够强时，专员大量调用技能只会放大不稳定性。 + +### 3. 应用 + +当前优先级应放在： + +- 成为真正可用的产品化入口 +- 拥有清晰主界面 +- 承载状态、结果和留痕 +- 直接解决某类工作场景 + +当前不应为了结构完整性而要求 App 过早承担复杂编排职责。 + +--- + +## 六、关于绑定关系的阶段性判断 + +绑定关系仍然重要， +但对当前阶段而言， +它不是最高优先级。 + +更准确的判断是： + +- 长期看，关系层必须存在 +- 当前看，优先级低于对象本身做强 + +因此当前应坚持： + +```text +先强对象，再补关系 +先做成立，再做复杂协作 +``` + +等到以下信号稳定出现时，再提高关系层优先级： + +- 一个专员稳定复用多种技能 +- 一个技能被多个专员反复复用 +- 一个应用需要切换默认专员或能力组合 +- 后台出现真实的配置、运营和灰度需求 + +--- + +## 七、与 AionUi 的客观比较 + +当前更准确的比较结论是： + +- 我们的六层底座和企业化治理能力，比 AionUi 更完整 +- AionUi 在上层对象资产化、规则资产化、技能包化方面更成熟 + +因此： + +- 不需要因为学习 AionUi 而推翻现有六层总架构 +- 需要借鉴 AionUi 的，是第五层对象层如何做成真正产品资产 + +换句话说： + +**AionUi 更值得学习的是“对象如何做强”，不是“总架构如何重画”。** + +--- + +## 八、本次复盘后的正式结论 + +本次复盘后，正式收敛为以下判断： + +1. 六层架构继续成立，当前没有充分证据否定它 +2. 当前不改总架构，而是在原架构内强化重点层 +3. 当前重点是第五层对象层与第六层运行治理层 +4. 专员 / 技能 / 应用应先各自独立做强 +5. 绑定关系重要，但不是当前第一优先级 +6. 学习 AionUi，应重点学习对象资产化，不应机械替换总架构 + +最终可统一表述为： + +```text +六层架构不变； +当前优化重点放在第五层对象层与第六层运行治理层； +先把专员、技能、应用各自做强， +再在成熟度足够时补关系层和更复杂的协作编排。 +``` diff --git a/docs/2026-09-17_对象命名标准化清单.md b/docs/2026-09-17_对象命名标准化清单.md new file mode 100644 index 0000000..6e52fea --- /dev/null +++ b/docs/2026-09-17_对象命名标准化清单.md @@ -0,0 +1,549 @@ +# 对象命名标准化清单 + +> 日期：2026-09-17 +> 性质：代码目录、文件名、变量名、函数名的对象命名标准化清单 +> 关联文档： +> - `docs/对象标准化与解耦总则.md` +> - `docs/2026-09-17_六层架构与三对象建设重点阶段性复盘.md` + +--- + +## 一、结论 + +当前代码目录整体上已经开始围绕对象收口， +但命名层面仍然处于**新旧术语混用**的过渡态。 + +最准确的判断是： + +- **目录结构基本清楚** +- **对象落点已经清楚** +- **命名标准还不统一** +- **旧词残留仍在持续污染对象边界** + +当前最主要的问题不是“找不到代码在哪”， +而是： + +**看名字时，仍然经常不知道它到底指的是专员、技能、应用、默认助手，还是历史遗留概念。** + +--- + +## 二、当前对象落点是否清楚 + +### 1. 后端主模型落点是清楚的 + +- 专员：`backend-go/internal/model/specialist.go` +- 技能：`backend-go/internal/model/skill_definition.go` +- 应用：`backend-go/internal/model/app_definition.go` +- 连接器：`backend-go/internal/connector/*` + +其中三大对象模型命名基本准确： + +- [specialist.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/specialist.go) +- [skill_definition.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/skill_definition.go#L5-L32) +- [app_definition.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/app_definition.go#L5-L38) + +### 2. 前端 catalog store 方向也是清楚的 + +- `specialistCatalog` +- `skillCatalog` +- `appCatalog` + +对应文件： + +- [specialistCatalog.js](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/specialistCatalog.js#L17-L88) +- [skillCatalog.js](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/skillCatalog.js) +- [appCatalog.js](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/appCatalog.js#L22-L155) + +这一层说明：**对象目录化方向是正确的。** + +--- + +## 三、当前命名不清晰的主要问题 + +## 3.1 旧术语和新术语混用 + +当前代码中同时混着： + +- `role` +- `assistant` +- `specialist` +- `skill` +- `app` +- `worker` +- `capability` + +这会导致以下问题： + +1. 同一个对象被多个词指代 +2. 同一个词被多个对象复用 +3. 页面层很容易把对象边界重新写乱 + +### 典型例子 + +技能模型已经叫 `SkillDefinition`， +但字段仍叫 `RoleKind`： +[skill_definition.go:L5-L25](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/skill_definition.go#L5-L25) + +这说明： + +- 模型名是新的 +- 字段语义还是旧的 + +这类命名会误导人以为 `role` 仍然是正式一级对象。 + +## 3.2 文件名与真实职责不完全一致 + +最典型的是： + +- [capability_definition.go](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/api/capability_definition.go#L1-L120) + +这个文件名叫 `capability_definition`， +但里面做的是： + +- `skillDefinitionReq` +- `actionDefinitionReq` +- `ListSkillDefinitions` + +问题不只是不好看， +而是它在语义上制造了一个模糊的一级概念：`capability`。 + +当前系统正式对象语言应是： + +- `specialist` +- `skill` +- `app` +- `connector` +- `action`（底层） + +不应再让 `capability` 作为主要文件名继续扩散。 + +## 3.3 历史静态目录变量名不准 + +最典型的旧变量在： +[workbench.js:L99-L105](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/config/workbench.js#L99-L105) +[workbench.js:L1434-L1443](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/config/workbench.js#L1434-L1443) + +包括： + +- `availableSkills` +- `businessApps` +- `connectors` + +其中问题最大的是： + +- `businessApps` 实际装的是专员目录，不是应用目录 +- `availableSkills` 现在更像静态 fallback，不是正式生产技能目录 + +所以这些名字会把开发者带偏。 + +## 3.4 页面局部变量有失真 + +例如： +[SmartAssistantPage.vue:L311-L334](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/views/workbench/SmartAssistantPage.vue#L311-L334) + +这里： + +```js +const app = specialistCatalog.getByKey(key) +``` + +拿到的是专员对象，却命名成 `app`。 + +这类局部变量不会影响编译， +但会持续破坏对象认知。 + +## 3.5 路由参数协议不统一 + +应用目录里拼路由时使用： +[appCatalog.js:L135-L145](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/appCatalog.js#L135-L145) + +- `specialist` +- `skill` +- `prompt` + +但工作台页面读取的是： +[SmartAssistantPage.vue:L602-L626](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/views/workbench/SmartAssistantPage.vue#L602-L626) + +- `app_specialist` +- `app_skill` +- `app_prompt` + +这已经不是风格差异， +而是**入口协议不统一**。 + +## 3.6 默认助手概念没有完全收口 + +当前存在： + +- API 文件名：`assistant.js` +- 默认技能 key：`smart-assistant` +- 默认专员 key：`general-assistant` + +见： + +- [assistant.js:L1-L3](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/api/assistant.js#L1-L3) +- [workerRuntime.js:L17-L21](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/workerRuntime.js#L17-L21) + +这说明“assistant”当前同时在承担： + +- 默认聊天接口名 +- 默认技能语义 +- 默认专员语义 + +需要明确边界，不然以后越做越乱。 + +--- + +## 四、标准命名原则 + +## 4.1 正式对象术语 + +对外和对内统一如下： + +- 专员：`specialist` +- 技能：`skill` +- 应用：`app` +- 连接器：`connector` +- 动作：`action` + +## 4.2 非正式或历史兼容词的处理原则 + +以下词允许保留在历史兼容层， +但**不再继续扩散为新的正式命名**： + +- `role` +- `businessApps` +- `availableSkills` +- `capability`（除非明确表示“泛能力总称”，不能再充当对象级文件名） +- `assistant`（除非明确指聊天接口或默认助手） + +## 4.3 命名优先级 + +命名时遵守： + +```text +对象准确性 > 历史兼容性 > 书写简短 +``` + +意思是： + +- 宁可名字长一点 +- 也不要再用会误导对象边界的旧词 + +--- + +## 五、标准化建议 + +## 5.1 P0：立即统一入口协议和最容易误导人的命名 + +### A. 统一应用入口 query 参数 + +当前应统一为一套， +不要一边写 `specialist/skill/prompt`， +一边读 `app_specialist/app_skill/app_prompt`。 + +建议二选一，但必须全链路统一。 + +推荐统一成： + +- `app_specialist` +- `app_skill` +- `app_prompt` + +原因： + +- 一眼能看出这是“应用带入工作台”的预置参数 +- 不会和普通页面 query 混淆 + +### B. 修正页面里的失真变量名 + +例如： + +- `const app = specialistCatalog.getByKey(...)` + +应改成： + +- `const specialist = ...` + +这类改动优先级很高， +因为它们会直接影响后续开发者理解对象边界。 + +### C. 停止新增 `businessApps` / `availableSkills` 这类旧变量名 + +现有代码可暂时保留兼容， +但后续新增代码禁止继续使用这些命名。 + +--- + +## 5.2 P1：统一文件名与对象职责 + +### A. `capability_definition.go` + +当前建议拆或改名： + +方案 1： +- `skill_definition.go` +- `action_definition.go` + +方案 2： +- 保留文件不拆，但改名为 `skill_and_action_definition.go` + +不建议继续用： + +- `capability_definition.go` + +因为它已经不能准确表达该文件实际职责。 + +### B. `assistant.js` + +当前如果它只是默认聊天接口， +建议更明确地表达为： + +- `smartAssistant.js` +或 +- `assistantChat.js` + +而不是继续模糊地叫 `assistant.js`。 + +--- + +## 5.3 P1：统一 store 与 fallback 的命名语义 + +### A. `availableSkills` + +如果继续保留作为静态补丁源， +建议改名为： + +- `staticSkillCatalog` +或 +- `legacySkillCatalog` + +不要再叫： + +- `availableSkills` + +因为现在真正“可用技能目录”已经是后端 + `skillCatalog`。 + +### B. `businessApps` + +如果继续保留作为专员静态兼容源， +建议改名为： + +- `staticSpecialistCatalog` +或 +- `legacySpecialistCatalog` + +不要再叫： + +- `businessApps` + +因为它和 `app` 已经明确冲突。 + +--- + +## 5.4 P2：统一字段语义 + +### A. `RoleKind` + +当前字段： +[skill_definition.go:L13](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/model/skill_definition.go#L13) + +建议后续迁移为更准确的名字，例如： + +- `object_kind` +或 +- `owner_kind` + +如果业务语义是“这个技能归属于哪类对象”。 + +如果短期不迁字段， +至少要在文档中明确： + +- `RoleKind` 是历史兼容字段 +- 不再代表正式 `role` 概念 + +### B. `assistant` 的语义边界 + +需要明确规定： + +- `assistant` 只用于默认通用助手的聊天接口语义 +- `specialist` 才是正式对象名 + +否则会继续出现： + +- 默认助手既像 skill 又像 specialist +- 页面里又再抽象成 role + +--- + +## 六、按文件的具体清单 + +## 6.1 后端 + +### `backend-go/internal/model/skill_definition.go` + +问题： + +- `RoleKind` 仍带旧语义 + +建议： + +- 文档先标记为历史兼容字段 +- 后续统一迁移为更准确字段名 + +### `backend-go/internal/api/capability_definition.go` + +问题： + +- 文件名与实际职责不匹配 +- `capability` 不是当前正式对象主词 + +建议： + +- 重命名或拆分 + +### `backend-go/internal/api/router.go` + +优点： + +- `/api/specialists` +- `/api/skills` +- `/api/apps` +- `/api/connectors` + +这层命名已经较清楚： +[router.go:L39-L49](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/backend-go/internal/api/router.go#L39-L49) + +建议： + +- 保持这层对象 API 命名不再回退 + +## 6.2 前端 + +### `frontend/src/config/workbench.js` + +问题： + +- 是历史静态大杂烩 +- `businessApps` 命名错误 +- `availableSkills` 命名已过时 + +建议： + +- 不再作为生产目录源 +- 继续降级为静态 fallback +- 变量名按对象真实语义重命名 + +### `frontend/src/views/workbench/SmartAssistantPage.vue` + +问题： + +- 局部变量名存在失真 +- `currentRolePresentation` 仍有旧 `role` 心智残留 + +建议： + +- 局部变量全部改成对象准确名 +- 将 `role presentation` 逐步收敛为 `currentObjectPresentation` + 或明确区分： + - `currentSpecialistPresentation` + - `currentSkillPresentation` + - `defaultAssistantPresentation` + +### `frontend/src/api/assistant.js` + +问题： + +- 文件名语义太宽 + +建议： + +- 仅在确认其职责是“默认助手聊天接口”后保留 +- 否则改名为更准确的接口文件名 + +### `frontend/src/store/appCatalog.js` + +优点： + +- `normalizeRemoteApp` +- `normalizeCustomApp` +- `resolveOpenRoute` + +这套命名整体清楚： +[appCatalog.js:L22-L145](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/appCatalog.js#L22-L145) + +问题： + +- 路由 query 命名与工作台读取不一致 + +建议： + +- 先统一 query 协议 + +### `frontend/src/store/specialistCatalog.js` + +优点： + +- 命名整体比较准确 +- `normalizeSpecialist / getByKey / getByPath` 清楚 + +见： +[specialistCatalog.js:L17-L87](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/eai_agentplatform/frontend/src/store/specialistCatalog.js#L17-L87) + +建议： + +- 继续作为专员目录的标准写法模板 + +--- + +## 七、执行顺序 + +建议按下面顺序做命名清理： + +1. **统一入口协议** + - app query 参数统一 + +2. **清理页面级失真变量** + - 特别是 `SmartAssistantPage.vue` + - `CurrentObjectChip.vue` + - `PlusMenu.vue` + +3. **清理历史静态变量名** + - `businessApps` + - `availableSkills` + +4. **清理文件名级旧词** + - `capability_definition.go` + - `assistant.js` + +5. **最后处理字段迁移** + - 如 `RoleKind` + +这样做的原因是： + +- 先收敛入口协议，避免继续产生新分叉 +- 再清局部变量，马上提升可读性 +- 最后再碰数据库字段，避免一次性改太重 + +--- + +## 八、最终判断 + +当前代码不是“命名完全混乱”， +而是： + +**目录已经开始清楚，但命名标准还没有真正收口。** + +最核心的问题不是技术能力， +而是术语迁移还没做完。 + +后续只要坚持： + +```text +对象名必须准确 +旧词只做兼容 +页面变量不得歪曲对象语义 +路由 / API / store 使用同一套对象协议 +``` + +这套代码的可读性会明显上一个台阶。 diff --git a/docs/AionUi助手到pj0235三层映射表与首个样板方案.md b/docs/AionUi助手到pj0235三层映射表与首个样板方案.md new file mode 100644 index 0000000..95b0ab8 --- /dev/null +++ b/docs/AionUi助手到pj0235三层映射表与首个样板方案.md @@ -0,0 +1,182 @@ +# AionUi 助手到 pj0235 三层映射表与首个样板方案 + +> 目标：不是继续泛读，而是把 AionUi 的助手体系拆成 pj0235 可落地的三层结构： +> +> - `专员`：负责任务理解、规则约束、流程编排 +> - `技能`：负责真正执行与产物生成 +> - `应用`：给用户一键即用的成品入口 + +--- + +## 一、迁移原则 + +1. **不学 Electron 壳** + 只学 AionUi 的助手封装方法、技能包方法、交付闭环方法。 + +2. **优先办公生产力** + 绘画、故事、3D 游戏、社交发布类全部后置。 + +3. **先做一个样板，再批量复制** + 第一个样板选 `汇报 PPT`，因为它最能验证： + - 应用入口 + - 专员规则 + - 技能执行 + - 产物沉淀 + - 项目复用 + +--- + +## 二、AionUi 21 个助手 -> pj0235 三层映射 + +| AionUi 助手 | AionUi 类型判断 | pj0235 专员映射 | pj0235 技能映射 | pj0235 应用映射 | 优先级 | 备注 | +|---|---|---|---|---|---|---| +| Cowork | 通用任务编排 | 通用助手 / 流程推进专员 | smart-assistant | 开场工作台 | 高 | 保留为总入口，不单独产品化 | +| PPT Creator | 办公交付 | **汇报专员** | ppt-generation | **汇报 PPT** | **高** | 第一优先样板 | +| Morph PPT | 演示增强 | 汇报专员 | ppt-generation | 汇报 PPT | 中 | 可作为二阶段增强 | +| 3D Morph PPT | 演示增强 | 汇报专员 | ppt-generation | 汇报 PPT | 低 | 当前办公价值不高 | +| Pitch Deck Creator | 商务演示 | 售前方案专员 / 汇报专员 | ppt-generation + proposal-summary | 售前汇报 | 高 | 和汇报 PPT 共骨架 | +| Dashboard Creator | 数据展示 | 报告生成专员 | table-cleanup / ppt-generation | 数据看板汇报 | 中 | 适合第二批 | +| Word Creator | 办公交付 | 报告生成专员 | longform-writing | 方案 / 报告写作 | 高 | 第二个建议样板 | +| Word Form Creator | 表单模板 | 报告生成专员 / 流程推进专员 | longform-writing | 表单模板 | 中 | 可在 Word 样板后复制 | +| Excel Creator | 数据整理 | 报告生成专员 | table-cleanup | 表格整理 | 高 | 第三个建议样板 | +| Academic Paper | 长文结构化 | 报告生成专员 | longform-writing | 长文写作 | 中 | 偏长文，不是最先做 | +| Financial Model Creator | 数据模型 | 报告生成专员 | table-cleanup | 数据分析 | 中 | 适合财务线后补 | +| Beautiful Mermaid | 结构表达 | 汇报专员 / 方案专员 | mind-map | 思维导图 | 中 | 已有基础能力 | +| Planning with Files | 文件驱动规划 | 流程推进专员 | project-planning | 项目规划 | 高 | 很适合你当前项目制工作台 | +| AionUi Butler | 系统内管家 | 通用助手 | smart-assistant | 无 | 低 | 更偏产品自运维 | +| OpenClaw Setup Expert | 环境配置 | 无 | 无 | 无 | 低 | 当前不做 | +| HUMAN 3.0 Coach | 人类教练 / 反思 | 流程推进专员 | progress-report | 项目复盘 | 低 | 不做第一批 | +| UI/UX Pro Max | 设计创作 | 无 | 无 | 无 | 低 | 不属于办公主线 | +| 3D Game | 创作娱乐 | 无 | 无 | 无 | 低 | 排除 | +| Social Job Publisher | 社交发布 | 公众号助手 | longform-writing / copy-proofreading | 内容发布 | 低 | 不是当前重点 | +| moltbook | 内容/创意类 | 公众号助手 | longform-writing | 内容应用 | 低 | 不是当前重点 | +| Story Roleplay | 娱乐/角色扮演 | 无 | 无 | 无 | 低 | 排除 | + +--- + +## 三、推荐的第一批可迁移办公骨架 + +### 第一梯队 + +1. **汇报 PPT** +2. **方案 / 报告写作** +3. **表格整理** +4. **项目规划** +5. **方案摘要** + +### 第二梯队 + +1. 思维导图 +2. 表单模板 +3. 数据看板汇报 +4. 长文写作 + +### 后置 + +1. 创意类 +2. 娱乐类 +3. 社交发布类 +4. 系统配置类 + +--- + +## 四、首个样板为什么选“汇报 PPT” + +原因很直接： + +1. **最像 AionUi 的强项** +2. **最容易体现办公交付价值** +3. **最适合拉通“专员 + 技能 + 应用”三层结构** +4. **后续能平滑复制到 Pitch Deck、方案汇报、培训课件** + +--- + +## 五、首个样板的目标形态 + +### 应用层 + +- 名称：`汇报 PPT` +- 用户入口：应用广场直接打开 +- 默认行为： + - 自动切到工作台 + - 自动挂上 `汇报专员` + - 自动挂上 `ppt-generation` + - 自动带入默认提示词 + +### 专员层 + +- 名称：`汇报专员` +- 职责： + - 理解汇报目标 + - 压缩材料 + - 规划页数 + - 组织每页要点 + - 收口讲稿备注 + +### 技能层 + +- 主技能：`ppt-generation` +- 辅助技能： + - `proposal-summary` + - `mind-map` + - `progress-report` + +--- + +## 六、这次已落地的样板改动 + +本轮直接落代码，完成了下面几件事： + +1. 新增 `汇报专员` + - 前端目录卡片 + - 后端种子数据 + - 岗位说明书规则 + - 绑定技能清单 + +2. 把现有 `PPT 生成` 成品应用升格为 `汇报 PPT` + - 增加默认专员绑定 + - 保留默认技能绑定 + - 优化默认提示词和文案 + +3. 让应用入口支持同时挂载 + - `app_specialist` + - `app_skill` + - `app_prompt` + +4. 增加项目模板 + - `汇报 PPT` + - 便于后续直接复制第二个、第三个样板 + +--- + +## 七、后续复制模板 + +接下来要做第二个、第三个时，不要再重新想结构，直接照这个模板复制： + +1. 新增一个专员 +2. 绑定 2-4 个技能 +3. 新增一个成品应用 +4. 配一个项目模板 +5. 让应用入口默认带上专员、技能、提示词 + +建议顺序： + +1. `方案 / 报告写作` +2. `表格整理` +3. `项目规划` +4. `方案摘要` + +--- + +## 八、结论 + +这一轮的目标不是“把 AionUi 学完”，而是把它拆成可以直接复用的产品方法。 + +现在路线已经明确： + +- **AionUi 学的是助手/技能封装法** +- **pj0235 落的是专员/技能/应用三层结构** +- **第一个样板已经确定为：汇报 PPT** + +下一轮继续扩，不再需要重做架构判断，直接按样板复制即可。 + diff --git a/docs/AionUi源码深度扫描与办公智能体架构对比.md b/docs/AionUi源码深度扫描与办公智能体架构对比.md new file mode 100644 index 0000000..594a793 --- /dev/null +++ b/docs/AionUi源码深度扫描与办公智能体架构对比.md @@ -0,0 +1,681 @@ +# AionUi 源码深度扫描与办公智能体架构对比 + +> 扫描对象：`/home/eaiadmin/eaifiles/codebase/AionUi` +> +> 关联资产：`/home/eaiadmin/eaifiles/codebase/AionCore-assets/crates/aionui-app/assets` +> +> 参考对标：`/home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform-ubu/docs/微趣MyGPT调研与办公智能体架构对比.md` + +--- + +## 一、结论 + +**AionUi 不是简单的 Electron 桌面壳了，但它依然不是 MyGPT 那种政企成品。** + +更准确地说： + +```text +AionUi = 强助手包装 + 强技能包 + 强 Office 交付 + 弱企业底座 +博昇 pj0235 = 强企业底座 + 中等场景化 + 正在补办公交付 +MyGPT = 强企业成品化 + 强办公场景 + 强私有化销售形态 +``` + +我的源码实读后的核心判断是： + +1. **之前把 AionUi 理解成“桌面玩具”已经偏旧了。** + 它现在实际是一个 **桌面优先、但已经长出 WebUI、独立 Web CLI、移动端、远程渠道、多 Agent 团队模式** 的 AI 工作台。 + +2. **但它仍然不是政企办公平台。** + 它更像一个 **个人/小团队的 AI Cowork 工作台**，不是 MyGPT 那种“私有化一体机 + 多用户权限 + 行业交付”的标准产品。 + +3. **AionUi 最值得学的不是技术栈，而是“助手如何封装成产品”。** + 它把一个助手拆成： + - 助手目录元数据 + - Markdown 规则 + - 绑定技能 + - 默认模型/权限/MCP + - 可预览的最终交付物 + +4. **对 pj0235 最有价值的是三层结构，不是 Electron。** + 最该学的是： + - `Assistant/Expert` 规则层 + - `Skill` 工具层 + - `Application` 成品入口层 + +一句话总结： + +**AionUi 该学“怎么把 AI 员工做成可复用的产品单元”；MyGPT 该学“怎么把这些单元卖成政企标准化办公平台”；pj0235 不该倒回 Electron，而该在现有 Go/Web 底座上吸收这两者。** + +--- + +## 二、这次扫描看了什么 + +这次不是只看 README，而是把几类关键源码都扫了一遍： + +- **产品入口与技术栈** + - `AionUi/package.json` + - `AionUi/readme.md` + - `AionUi/packages/web-host/package.json` + - `AionUi/packages/web-cli/package.json` + - `AionUi/mobile/package.json` + +- **助手目录与规则** + - `AionCore-assets/crates/aionui-app/assets/builtin-assistants/assistants.json` + - `AionCore-assets/crates/aionui-app/assets/builtin-assistants/rules/*.md` + +- **技能目录** + - `AionCore-assets/crates/aionui-app/assets/builtin-skills/*` + - 包括 `auto-inject/*` 子技能 + +- **桌面端助手/技能装载与数据结构** + - `AionUi/packages/desktop/src/common/types/agent/assistantTypes.ts` + - `AionUi/packages/desktop/src/process/utils/initStorage.ts` + - `AionUi/packages/desktop/src/renderer/pages/settings/SkillsSettings/SkillsHubSettings.tsx` + +- **团队模式 / 定时任务 / 预览 / 浏览器 / 远程** + - `AionUi/packages/desktop/src/process/services/database/schema.ts` + - `AionUi/packages/desktop/src/process/services/database/migrations.ts` + - `AionUi/packages/desktop/src/process/utils/runBackendMigrations.ts` + - `AionUi/packages/desktop/src/renderer/pages/conversation/Preview/README.cn.md` + - `AionUi/packages/web-host/src/index.ts` + - `AionUi/packages/web-cli/src/index.ts` + - `AionUi/scripts/webui.ts` + +--- + +## 三、纠正一个旧判断 + +之前那份对比稿里有一句： + +> “内置技能只有 5 个：pptx / docx / pdf / xlsx / mermaid” + +**这个说法现在已经不够准确。** + +按这次源码扫描，`builtin-skills` 顶层目录已经有 **22 个**： + +- `aionui-troubleshooting` +- `aionui-webui-public` +- `aionui-webui-setup` +- `auto-inject` +- `mermaid` +- `moltbook` +- `morph-ppt` +- `morph-ppt-3d` +- `officecli-academic-paper` +- `officecli-data-dashboard` +- `officecli-docx` +- `officecli-financial-model` +- `officecli-pitch-deck` +- `officecli-pptx` +- `officecli-word-form` +- `officecli-xlsx` +- `openclaw-setup` +- `pdf` +- `story-roleplay` +- `weixin-file-send` +- `xiaohongshu-recruiter` +- `x-recruiter` + +而且 `auto-inject` 下面还至少包含这些系统级子技能： + +- `skill-creator` +- `officecli` +- `cron` +- `aionui-config` +- `conversation-create` +- `session-message` + +所以更准确的说法应该是： + +**AionUi 最核心的显式通用技能，仍然集中在 OfficeCLI/PDF/Mermaid 这条线上；但完整源码资产里的技能体系，已经明显比“5 个技能”厚得多。** + +--- + +## 四、AionUi 现在到底是什么形态 + +### 1. 它仍然是桌面优先 + +主仓库依然是： + +- Electron +- React 19 +- TypeScript +- Bun +- Arco Design +- better-sqlite3 + +这一点没有变，桌面端仍然是主入口。 + +### 2. 但它已经不只是桌面端 + +源码里已经清楚分成： + +- `packages/desktop`：Electron 主产品 +- `packages/web-host`：WebUI Host，负责拉起后端和静态站点 +- `packages/web-cli`：独立 Web 运行时 CLI +- `mobile/`：Expo / React Native 移动端 + +也就是说，它的真实形态更接近： + +```text +桌面端主产品 + + 独立 WebUI + + 独立 Web CLI + + 移动端 + + IM 渠道远程接入 +``` + +所以如果现在再简单说它是“Electron 桌面壳”，就失真了。 + +### 3. 它后端不是 Node 业务后端，而是 AionCore 二进制 + +这里有个很关键的点： + +- `AionUi/package.json` 里钉住了 `aioncoreVersion: v0.2.2` +- `scripts/prepareAioncore.js` +- `scripts/resolveAioncoreVersion.js` + +说明桌面壳之外，**真正的能力核心已经下沉到 AionCore 后端二进制**。 + +也就是说它不是“前端非常厚，后端几乎没有”，而是： + +```text +AionUi 前端壳 + AionCore 能力后端 + AionCore 资产目录 +``` + +这个结构比“纯 Electron 玩具”要成熟很多。 + +--- + +## 五、AionUi 的 21 个助手到底是什么 + +`assistants.json` 明确给出了 21 个内置助手。 + +### 1. 办公交付型助手 + +这一批是最值得 pj0235 学的： + +1. `Word Creator` +2. `PPT Creator` +3. `Excel Creator` +4. `Word Form Creator` +5. `Morph PPT` +6. `3D Morph PPT` +7. `Pitch Deck Creator` +8. `Dashboard Creator` +9. `Academic Paper` +10. `Financial Model Creator` +11. `Beautiful Mermaid` + +它们的共同特点是： + +- **目标非常清晰** +- **交付物非常明确** +- **不是闲聊型助手，而是“产物型助手”** + +也就是： + +```text +输入需求 -> 调用技能 -> 生成 .pptx / .docx / .xlsx / 图表 +``` + +这正是办公生产力平台最有价值的那条线。 + +### 2. 通用协作 / 系统型助手 + +这一批更像方法层和系统层： + +1. `Cowork` +2. `Planning with Files` +3. `AionUi Butler` +4. `OpenClaw Setup Expert` +5. `HUMAN 3.0 Coach` + +其中最值得学的是前三个： + +- `Cowork`：通用任务执行器 +- `Planning with Files`：持久化 markdown 规划法 +- `AionUi Butler`：产品内管家 + +### 3. 创意 / 社交 / 娱乐型助手 + +这批对你当前办公对标价值不大： + +1. `3D Game` +2. `UI/UX Pro Max` +3. `Social Job Publisher` +4. `moltbook` +5. `Story Roleplay` + +所以如果是对标微趣办公平台，这部分可以基本不学或后置。 + +--- + +## 六、AionUi 的“员工”不是写死按钮，而是可装配对象 + +从 `assistantTypes.ts` 和 `assistants.json` 看，AionUi 的助手本质不是一个写死页面，而是一个可装配数据对象： + +- `id` +- `name` +- `description` +- `agent` +- `enabled_skills` +- `custom_skill_names` +- `disabled_builtin_skills` +- `prompts` +- `defaults` +- `preferences` +- `rules` + +这意味着一个助手本质上是： + +```text +助手 = 角色元数据 + 规则文件 + 技能绑定 + 默认运行配置 +``` + +这是它最值得学的地方。 + +### 助手规则怎么存 + +规则文件不是硬编码在前端组件里，而是： + +- 目录在 `builtin-assistants/rules/*.md` +- 运行时由后端目录和 SQLite 目录统一管理 +- `initStorage.ts` 里已经明确写了： + - built-in assistant 和 built-in skill 由 backend 负责 + - 不再从 renderer 资源里同步 + +也就是说： + +**AionUi 的助手，本质上是“数据化角色 + Markdown 规则”。** + +这非常适合迁移到 pj0235。 + +--- + +## 七、AionUi 的技能体系，已经是产品骨架 + +### 1. 显式技能 + +用户可感知、可挂载的主要技能包括： + +- `officecli-pptx` +- `officecli-docx` +- `officecli-xlsx` +- `officecli-word-form` +- `officecli-pitch-deck` +- `officecli-data-dashboard` +- `officecli-academic-paper` +- `officecli-financial-model` +- `morph-ppt` +- `morph-ppt-3d` +- `mermaid` +- `pdf` +- `story-roleplay` +- `moltbook` +- `openclaw-setup` +- 招聘发布类技能等 + +### 2. 自动注入技能 + +这一层很关键，因为它代表 **系统级能力并不一定通过前台显式勾选出现**。 + +源码里可以看到自动注入技能承担了这些事： + +- `officecli`：通用 Office 操作基础能力 +- `cron`：定时任务 +- `skill-creator`：技能创建器 +- `aionui-config`：修改 AionUi 自己 +- `conversation-create`：创建新会话 +- `session-message`：跨会话通信 + +这说明 AionUi 的技能并不只是“做文档”的工具包，它已经变成： + +```text +办公技能 + 系统技能 + 会话编排技能 +``` + +### 3. 技能不是说明书，而是可执行工作包 + +从这些 `SKILL.md` 能看到一个很明显的产品思路： + +- 不是一句“你会做 PPT” +- 而是把工作流写清楚 +- 必要时附带脚本、参考资料、模板 +- 强调什么时候触发、怎么执行、失败怎么处理 + +也就是说它的技能不是 UI 标签，而是真正的 **可落地操作包**。 + +--- + +## 八、AionUi 助手和技能是怎么绑定的 + +`assistants.json` 里每个助手都带 `enabled_skills`。 + +几个典型映射如下： + +- `Word Creator -> officecli-docx` +- `PPT Creator -> officecli-pptx` +- `Excel Creator -> officecli-xlsx` +- `Word Form Creator -> officecli-word-form` +- `Pitch Deck Creator -> officecli-pitch-deck` +- `Dashboard Creator -> officecli-data-dashboard` +- `Academic Paper -> officecli-academic-paper` +- `Financial Model Creator -> officecli-financial-model` +- `Morph PPT -> morph-ppt` +- `3D Morph PPT -> morph-ppt-3d + morph-ppt` +- `Beautiful Mermaid -> mermaid` +- `Story Roleplay -> story-roleplay` +- `Social Job Publisher -> xiaohongshu-recruiter + x-recruiter` +- `AionUi Butler -> aionui-config + aionui-troubleshooting + aionui-webui-public` + +这个结构特别重要，因为它说明： + +**AionUi 的“员工”不是直接把所有能力塞进 prompt，而是通过技能挂载来缩小能力边界。** + +这对你现在的项目非常有参考价值： + +```text +专员 = 负责任务理解与编排 +技能 = 负责真正执行 +应用 = 负责给用户一键入口 +``` + +--- + +## 九、AionUi 其实已经有“团队模式”而不是单助手模式 + +这也是旧认识里容易低估的地方。 + +从数据库 schema 和 migrations 可以直接看到： + +- `teams` +- `mailbox` +- `team_tasks` + +也就是说它的 Team Mode 不是 PPT 里的概念，而是真有落库结构： + +- 团队表 +- 代理邮箱 +- 团队任务板 + +数据库字段也很直白： + +- `lead_agent_id` +- `to_agent_id` +- `from_agent_id` +- `subject` +- `status` +- `blocked_by` +- `blocks` + +这说明它的团队协作机制不是“前端上摆几个头像”，而是已经走到了： + +```text +Leader + -> 发任务 + -> 队友并行执行 + -> 邮箱回传结果 + -> 任务板追踪 +``` + +这块比我们原先理解的 AionUi 要更成熟。 + +--- + +## 十、它还有定时任务、远程访问、预览和内置浏览器 + +### 1. 定时任务是实装的 + +`cron_jobs` 表字段很完整： + +- `schedule_kind` +- `schedule_value` +- `schedule_tz` +- `payload_message` +- `conversation_id` +- `next_run_at` +- `last_run_at` +- `last_error` + +说明这不是“以后可能做”，而是完整的已落地能力。 + +### 2. 预览面板比普通聊天产品强很多 + +Preview 模块文档和目录显示，它支持： + +- Markdown +- 代码 +- 图片 +- Diff +- PDF +- Word +- Excel +- PPT +- HTML + +而且不是单纯查看，还支持： + +- 多 Tab +- 实时流式更新 +- 分屏编辑 +- 快捷键保存 +- 脏检测 +- 滚动同步 + +这对“办公交付型 Agent”非常重要，因为它让用户看得见产物迭代。 + +### 3. AionUi 还有内置浏览器 MCP + +`runBackendMigrations.ts` 里直接写了内置 browser MCP： + +> Control AionUi's built-in browser (the side preview panel) + +这意味着它的网页操作不是完全依赖外部浏览器，而是和侧边预览面板打通了。 + +### 4. 远程访问已经成体系 + +源码里明确支持： + +- WebUI Host +- 独立 `aionui-web` CLI +- Telegram +- Lark / 飞书 +- DingTalk +- Weixin +- Slack +- Discord + +再加上 `mobile/` 目录，AionUi 的交付边界已经比“本地桌面软件”宽很多。 + +--- + +## 十一、但它依然离 MyGPT 很远 + +虽然 AionUi 比我们之前以为的更厚，但它依然和 MyGPT 不是一类产品。 + +### AionUi 强在哪 + +1. **助手包装很强** +2. **技能包体系很强** +3. **Office 文件交付很强** +4. **多 Agent 协作很强** +5. **远程/跨端能力很活** + +### AionUi 弱在哪 + +1. **没有看到成熟的政企知识库/RAG 产品层** +2. **没有看到 MyGPT 式办公场景成品化深度** +3. **没有看到政企组织/权限/RBAC 那种交付级治理** +4. **没有 MyGPT 那种“私有化一体机”标准售卖形态** +5. **行业垂直办公包明显不足** + +所以它更像： + +```text +强个人工作台 +强 AI 助手容器 +强文档交付器 +弱企业办公平台 +``` + +--- + +## 十二、AionUi vs pj0235 vs MyGPT + +| 维度 | AionUi | 博昇 pj0235 | MyGPT | +|---|---|---|---| +| 产品形态 | 桌面优先 + WebUI + Web CLI + Mobile | Web 企业系统 | Web 一体机 | +| 前端 | React + Electron + Arco | Vue3 + Element Plus | 未公开 | +| 后端 | AionCore 二进制 + SQLite | Go + Gin + GORM + SQLite | 未公开 | +| 助手体系 | **很强**，21 个内置助手 + 规则 Markdown | 有基础，但产品化还在补 | 强 | +| 技能体系 | **很强**，Skill 包 + auto-inject | 正在成型 | 强 | +| Office 交付 | **很强**，OfficeCLI 路线成熟 | 正在补齐 | 强 | +| 预览链路 | **很强**，多格式实时预览 | 中等 | 强 | +| 团队多 Agent | **有实装** | 有任务平台，但不是这个范式 | 未公开 | +| 知识库/RAG | 未见强产品层 | **强** | **强** | +| 组织/权限/治理 | 弱 | **强于 AionUi** | 强 | +| 政企私有化售卖形态 | 弱 | 中 | **强** | +| 行业办公场景成品化 | 中 | 中 | **强** | + +一句话判断： + +**AionUi 在“AI 员工怎么做”上很强；pj0235 在“企业系统怎么交付”上更强；MyGPT 在“办公产品怎么卖成标准化政企成品”上最强。** + +--- + +## 十三、对 pj0235 最值得抄的 6 件事 + +### 1. 抄“助手对象模型” + +把专员做成： + +- 名称 +- 简介 +- 规则 +- 默认技能 +- 默认连接器/MCP +- 默认模型 +- 默认权限 + +而不是仅仅一个目录卡片。 + +### 2. 抄“规则文件化” + +把复杂办公专员的工作逻辑写成 Markdown 规则，而不是只塞到后端 prompt 模板里。 + +最适合迁移的就是： + +- PPT +- Word +- Excel +- 合同/表单 +- 方案汇报 +- 长文写作 +- 项目规划 + +### 3. 抄“技能包”而不是“功能按钮” + +把技能做成： + +- `SKILL.md` +- 脚本 +- 参考资料 +- 模板 + +这样你的技能才会变成真正的“可执行能力单元”。 + +### 4. 抄“专员绑定技能”的结构 + +不是每个专员都能做所有事，而是： + +- 汇报专员绑定 PPT / Mermaid / Word +- 合同专员绑定 PDF / Word / 比对 +- 会议专员绑定转写 / 摘要 / PPT +- 数据专员绑定 Excel / 图表 / 报表 + +### 5. 抄“产物预览链路” + +这一点很关键。 + +办公智能体不是只要会说，而是要让用户： + +- 看到产物 +- 快速改产物 +- 多格式预览 +- 保持文件在工作流中流动 + +### 6. 抄“系统级隐藏技能” + +`auto-inject` 这层特别值得学。 + +对 pj0235 来说，可以对应成： + +- 项目创建 +- 会话创建 +- 文档汇总 +- 项目内跨任务消息 +- 自动归档 +- 定时执行 + +这些不一定要前台显式出现，但应该成为系统内的底层能力。 + +--- + +## 十四、如果只看办公生产力，AionUi 该优先学哪一批 + +如果目标是对标微趣，而不是做娱乐型 AIGC，那我建议优先学这 10 个： + +1. `Word Creator` +2. `PPT Creator` +3. `Excel Creator` +4. `Word Form Creator` +5. `Pitch Deck Creator` +6. `Dashboard Creator` +7. `Academic Paper` +8. `Financial Model Creator` +9. `Morph PPT` +10. `Planning with Files` + +这 10 个基本能组成一套很强的办公产能骨架： + +- 文档生成 +- 表格分析 +- 演示汇报 +- 表单模板 +- 方案包装 +- 长文写作 +- 计划执行 + +而这些正好和你现在要补的办公生产力方向高度一致。 + +--- + +## 十五、最终判断 + +最终我会这样给 AionUi 定位： + +```text +AionUi 不是 MyGPT，也不是博昇现有 Web 平台。 + +它本质上是： +一个以助手规则和技能包为核心的 AI 工作台操作层。 +``` + +所以对 pj0235 最正确的学习姿势不是： + +- 学 Electron +- 学它的界面长相 +- 学它的个人工具调性 + +而是学这三件事： + +1. **助手怎么产品化** +2. **技能怎么封装成包** +3. **产物怎么形成闭环** + +最后一句话： + +**博昇不该变成 AionUi。** +**博昇应该成为：有 AionUi 助手/技能包装能力的企业级 Web MyGPT。** + diff --git a/docs/对象标准化与解耦总则.md b/docs/对象标准化与解耦总则.md new file mode 100644 index 0000000..9c5af8d --- /dev/null +++ b/docs/对象标准化与解耦总则.md @@ -0,0 +1,345 @@ +# 对象标准化与解耦总则 + +## 一、目标 + +这个项目后续不再围绕“某个页面怎么写”来扩能力， +而是围绕三类核心对象做长期演进： + +- **专员** +- **技能** +- **应用** + +目标不是把功能堆起来，而是把这三类对象做成： + +```text +定义稳定 ++ 关系清晰 ++ 数据源唯一 ++ 前后端解耦 +``` + +--- + +## 二、统一结构 + +三类对象以后都按同一种思路建模： + +```text +对象定义 + 绑定关系 + 运行态数据 +``` + +### 1. 对象定义 + +定义“这个对象是什么”。 + +必须由后端保存，前端只能消费，不能再本地拼真数据。 + +对象定义至少要包含这几类字段： + +- `key` +- `label` +- `display_code` +- `eailogic_code` +- `tier` +- `worker_type` +- `source` +- `summary` +- `state` +- `sort_order` + +如果是面向用户展示的对象，还要有： + +- `badge / market_tag` +- `color` +- `icon_text` +- `cover_tone` + +### 2. 绑定关系 + +定义“它和谁有关系”。 + +以后不要再把绑定关系散在 prompt、seed 文本和前端配置里。 + +关系必须可显式表达，比如： + +- 专员绑定哪些技能 +- 应用默认挂哪个专员 +- 应用默认挂哪些技能 +- 对象能打开到哪个入口 + +### 3. 运行态数据 + +定义“这次执行过程中发生了什么”。 + +这层和目录定义分开，不能混。 + +例如： + +- 当前任务挂了哪个专员 +- 当前会话挂了哪个技能 +- 当前用户收藏了哪个应用 +- 最近使用了哪些应用 +- 任务执行过程产出了什么文件 + +--- + +## 三、三层职责 + +### 1. 专员 + +专员只负责： + +- 理解任务 +- 拆解步骤 +- 决定何时调用技能 +- 决定输出的协作方式 + +专员不是技能，也不是应用入口。 + +专员的本质是： + +```text +规则层 / 编排层 / 协作层 +``` + +### 2. 技能 + +技能只负责： + +- 执行动作 +- 接收输入 +- 产生结果 +- 输出产物 + +技能不负责“扮演谁”，也不负责“对外怎么卖”。 + +技能的本质是： + +```text +执行层 / 工具层 +``` + +### 3. 应用 + +应用只负责： + +- 面向用户提供一键入口 +- 预装默认专员 +- 预装默认技能 +- 预装默认提示词 + +应用不应该承载规则本体，也不应该直接替代技能。 + +应用的本质是： + +```text +产品化入口层 +``` + +--- + +## 四、解耦原则 + +### 原则 1：后端是唯一目录源 + +以后目录对象必须以后端表为准。 + +前端只能做： + +- 请求 +- 归一化 +- 渲染 + +前端不能再承担： + +- 正式编号生成规则 +- 正式目录维护 +- 对象真数据拼装 + +### 原则 2：页面不能成为数据源 + +目录页、详情页、加号菜单、聊天胶囊都只能消费 store， +不能各自再维护一份对象数组。 + +### 原则 3：配置文件不能充当生产目录 + +配置文件最多只允许承担： + +- fallback +- 样式增强 +- 本地 demo + +不能承担： + +- 生产目录 +- 正式编号 +- 主入口映射 + +### 原则 4：对象定义和用户态分离 + +全局对象属于系统目录。 + +用户收藏、最近使用、自定义应用，属于用户态。 + +这两层必须分开： + +```text +系统目录 != 用户偏好 != 运行态挂载 +``` + +### 原则 5：编号必须系统化 + +编号不是前端算出来的临时 UI 字符串， +而是正式对象属性。 + +统一规则： + +- 专员：`专 / EAI-S-` +- 技能：`能 / EAI-K-` +- 应用：`应 / EAI-A-` +- 连接器：`连 / EAI-C-` + +--- + +## 五、标准对象视图 + +前端消费对象时，应尽量收敛到统一视图，而不是每类对象各起一套随意字段。 + +建议统一成： + +```text +CatalogObjectView +- key +- type +- label +- displayCode +- logicCode +- badge +- tier +- workerType +- summary +- color +- iconText +- coverTone +- openRoute +- state +- sortOrder +``` + +扩展字段可以挂在各自域内，但公共展示层尽量对齐。 + +--- + +## 六、绑定关系标准 + +后面不再继续把绑定关系藏在自由文本里。 + +应该逐步补成显式关系： + +- `specialist_skill_binding` +- `app_specialist_binding` +- `app_skill_binding` +- `specialist_connector_binding` + +最终应该形成： + +```text +对象定义表 ++ 对象关系表 ++ 运行态任务表 +``` + +而不是： + +```text +对象定义表 ++ seed 里一段字符串 ++ 前端里一段数组 ++ prompt 里再提一次 +``` + +--- + +## 七、后续开发规则 + +以后新增一个专员、技能、应用，顺序必须是： + +1. 先定义它属于哪一层 +2. 再写后端对象定义 +3. 再补绑定关系 +4. 最后前端消费目录 + +禁止反过来： + +1. 先在前端做个入口 +2. 再在页面里写死配置 +3. 最后再考虑后端有没有这对象 + +--- + +## 八、当前项目的正确方向 + +这个项目后续最重要的不是再多做几个按钮， +而是把平台真正推进到： + +```text +专员层 ++ 技能层 ++ 应用层 ++ 连接器层 +``` + +四层稳定分离、统一建模、统一编号、统一目录源。 + +这样后面不管是对标 AionUi、MyGPT，还是继续扩办公生产力能力， +都不会再陷入“每扩一个能力，就前后端各写一遍”的结构性债务。 + +--- + +## 九、当前阶段判断 + +虽然长期结构上仍然需要关系层， +但**当前阶段不要把“复杂绑定关系”当成第一优先级**。 + +原因不是这个逻辑不成立， +而是当前对象成熟度还没有到那一步： + +- 专员还没有形成稳定、强编排能力 +- 技能还没有强壮到值得被专员大量调用 +- 应用当前更像产品化入口，而不是复杂能力编排器 + +所以当前更符合实际的推进顺序是： + +### 1. 先把对象本身做强 + +- 专员先做成稳定对象：有身份、有规则、有入口、能承接任务 +- 技能先做成强能力：单独使用就有价值，输入输出稳定，结果可靠 +- 应用先做成强入口：打开就能用，能直接产出，不强求复杂编排 + +### 2. 暂时不为了“结构漂亮”提前过度设计关系层 + +现阶段不要把大量精力投到： + +- 专员大量调用技能 +- 应用绑定复杂技能树 +- 为了理论完整性提前拆很多关系表 + +如果对象本身不强，关系层只会变成空架子。 + +### 3. 关系层仍然重要，但属于下一阶段 + +当下面几件事开始稳定出现时，再提高关系层优先级： + +- 一个专员开始稳定复用多种技能 +- 一个技能被多个专员反复复用 +- 一个应用需要切默认专员或默认能力组合 +- 后台出现真实的配置、运营和灰度需求 + +所以当前项目的阶段性原则是： + +```text +先强对象，再补关系 +先做成立，再做复杂协作 +``` + +这条判断优先级高于“结构看起来够不够完整”。 diff --git a/docs/目录结构化迁移说明-专员技能应用.md b/docs/目录结构化迁移说明-专员技能应用.md new file mode 100644 index 0000000..9c380a5 --- /dev/null +++ b/docs/目录结构化迁移说明-专员技能应用.md @@ -0,0 +1,147 @@ +# 目录结构化迁移说明：专员 / 技能 / 应用 + +## 一、当前结论 + +目录主数据源已经从前端静态配置，切到了后端定义表 + 前端统一目录 store。 + +现在的三层关系是： + +- **专员**：后端 `specialist` 表 +- **技能**：后端 `skill_definition` 表 +- **应用**：后端 `app_definition` 表 + +前端不再把这些对象的主目录写死在页面里，而是通过统一 store 消费： + +- `frontend/src/store/specialistCatalog.js` +- `frontend/src/store/skillCatalog.js` +- `frontend/src/store/appCatalog.js` + +--- + +## 二、后端结构 + +### 1. 专员 + +- 表：`specialist` +- 模型：`backend-go/internal/model/specialist.go` +- 公开接口： + - `GET /api/specialists` + - `GET /api/specialists/by-key/:key` + +### 2. 技能 + +- 表：`skill_definition` +- 模型：`backend-go/internal/model/skill_definition.go` +- 公开接口： + - `GET /api/skills` + - `GET /api/skills/by-key/:key` + +### 3. 应用 + +- 表：`app_definition` +- 模型：`backend-go/internal/model/app_definition.go` +- 公开接口： + - `GET /api/apps` + - `GET /api/apps/by-key/:key` + +### 4. 管理端维护接口 + +管理员现在可以直接维护三类目录： + +- `POST/PUT/DELETE /api/specialists` +- `POST/PUT/DELETE /api/skills` +- `POST/PUT/DELETE /api/apps` + +--- + +## 三、前端结构 + +### 1. 统一目录 store + +- 专员：`specialistCatalog` +- 技能：`skillCatalog` +- 应用：`appCatalog` + +页面和组件只负责渲染与交互，不再作为真目录源。 + +### 2. 应用目录的合并规则 + +`appCatalog` 现在由两部分组成： + +1. 后端返回的全局应用定义 `app_definition` +2. 当前用户自己的 `customApps` + +合并顺序： + +```text +全局应用定义 + 当前用户自定义应用 +``` + +自定义应用不再在 `appCenter` 里自己生成正式编号， +而是在 `appCatalog` 合并时，按照当前全局应用数量动态补： + +- `display_code` +- `eailogic_code` + +这样应用编号不会再依赖静态常量。 + +--- + +## 四、已经移除的旧模式 + +以下模式已经不再作为生产目录源： + +- `frontend/src/config/productizedApps.js` +- 页面内手写 `baseCatalogApps` +- 页面内手写 `productizedApps + customApps` 拼装 +- `appCenter` 基于静态总数常量生成应用编号 + +其中 `productizedApps.js` 已删除。 + +--- + +## 五、当前剩余约束 + +虽然主目录已经结构化，但仍有两类“过渡型依赖”存在： + +### 1. 技能展示增强字段 + +`skillCatalog` 仍会参考前端静态技能定义补充： + +- `roleCard` +- `workflowSchema` +- `artifactSchema` +- `capabilityTags` + +原因是后端 `skill_definition` 目前还没有完整覆盖这些前端展示字段。 + +### 2. 专员规则与技能绑定 + +专员本身已经后端化，但规则正文与绑定关系仍主要通过后端 seed 初始化： + +- `seed_specialist_rules.go` + +这已经比“前端写死”前进很多，但下一阶段仍可继续拆成更显式的关系表。 + +--- + +## 六、下一步建议 + +如果继续往“彻底结构化”推进，建议按这个顺序： + +1. 给应用补 `app_specialist_binding / app_skill_binding` +2. 给专员补显式 `specialist_skill_binding` +3. 把技能的展示增强字段也收回后端 manifest +4. 后台管理页增加应用定义管理界面 + +这样最终会形成统一模式： + +```text +对象定义表 + 绑定关系表 + 前端统一目录 store +``` + +而不是： + +```text +后端有表，但前端继续靠配置文件拼目录 +```