2026-09-22 17:46:56 +08:00
|
|
|
|
# 多系统智能体平台 · 重构分支
|
|
|
|
|
|
|
|
|
|
|
|
> 本分支**从零开始**，不继承原仓库的提交历史。
|
|
|
|
|
|
|
|
|
|
|
|
## 这是什么
|
|
|
|
|
|
|
|
|
|
|
|
原 `main` 是「APS 产品 + 内嵌智能体层」的混合实现。本次重构把它拆成两件事：
|
|
|
|
|
|
|
|
|
|
|
|
- **平台**：客户端 + 平台服务 + Core + 引擎适配 + Provider 契约。从零重写，TypeScript / Node。
|
|
|
|
|
|
- **APS**：作为独立业务系统，以现有代码搬迁适配（Python），通过 Provider 契约接入平台。
|
|
|
|
|
|
|
|
|
|
|
|
## 分支约定
|
|
|
|
|
|
|
|
|
|
|
|
| 分支 | 用途 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `rewrite/platform`（本分支） | 重构实现；提交历史从首个提交开始 |
|
|
|
|
|
|
| `main` | 原实现，只读参考；切换前另存为 `legacy/main` 并设为只读 |
|
|
|
|
|
|
|
|
|
|
|
|
- 旧代码参考用 `git show main:<path>`，或另开 worktree 检出 `main`。
|
|
|
|
|
|
- 移植旧逻辑时在提交信息里写明来源，例如 `移植自 main:server/aps_domain/flex.py`——孤儿历史下 `git blame` 追不到来源。
|
|
|
|
|
|
- 切换时以本分支强推覆盖 `main`（`--force-with-lease`）；切换前必须先把 `main` 备份为 `legacy/main`。
|
|
|
|
|
|
|
|
|
|
|
|
## 设计文档
|
|
|
|
|
|
|
2026-09-23 19:37:16 +08:00
|
|
|
|
| 文档 | 位置 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| 架构设计 | `docs/architecture.md` |
|
|
|
|
|
|
| 实施设计 | `docs/implementation.md` |
|
|
|
|
|
|
| 架构决策记录 | `docs/adr/` |
|
|
|
|
|
|
| 术语与边界一页纸 | `docs/glossary.md` |
|
|
|
|
|
|
| A0-G 评审材料与结论 | `docs/review/` |
|
|
|
|
|
|
| 能力描述规范 | `docs/spec/capability-description.md` |
|
|
|
|
|
|
| 问法评测集 | `docs/eval/` |
|
|
|
|
|
|
|
|
|
|
|
|
两份设计文档由飞书文档导入（A0-G 评审快照，2026-09-23）。**导入后以仓库版本为准**，改动走提交与 ADR 流程。
|
2026-09-22 17:46:56 +08:00
|
|
|
|
|
2026-09-23 19:29:57 +08:00
|
|
|
|
## 目录与包
|
|
|
|
|
|
|
|
|
|
|
|
一个 pnpm monorepo，四个一级目录（架构设计第 2 节）：
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
contracts/ @aps/contracts 共享契约（只有类型，无运行时依赖）
|
|
|
|
|
|
server/ @aps/server 平台服务：entry / app / agent / core / workflows
|
|
|
|
|
|
server/provider-sdk/ @aps/provider-sdk 业务系统接入平台的契约与契约测试
|
|
|
|
|
|
providers/aps/ @aps/provider-aps APS 适配器（ERP / EMS 同构）
|
|
|
|
|
|
client/app/ @aps/client-app 界面：对话、工作区、审批
|
|
|
|
|
|
client/desktop/ @aps/desktop Electron 壳：窗口、本地守护、离线升级
|
|
|
|
|
|
docs/ 架构、ADR、规范与评测集
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
依赖方向（A1.2 接入 CI 检查）：
|
2026-09-22 17:46:56 +08:00
|
|
|
|
|
|
|
|
|
|
```
|
2026-09-23 19:29:57 +08:00
|
|
|
|
contracts ← provider-sdk ← server ← client
|
|
|
|
|
|
↑
|
|
|
|
|
|
providers/*
|
2026-09-22 17:46:56 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-09-23 19:29:57 +08:00
|
|
|
|
## 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pnpm install # 需要 Node >= 22.19.0
|
|
|
|
|
|
pnpm typecheck # 等价于 tsc -b，按项目引用顺序构建全部包
|
2026-09-24 15:41:01 +08:00
|
|
|
|
pnpm verify # 完整门禁：typecheck + lint + 依赖方向 + 跨库 + 能力描述 + 测试
|
|
|
|
|
|
pnpm dev # 一键启动：平台服务(5199) + 客户端 dev server(5173)
|
|
|
|
|
|
pnpm start # 构建全部后由平台服务单端口托管（浏览器打开 http://127.0.0.1:5199）
|
|
|
|
|
|
pnpm dev:server # 只起平台服务
|
2026-09-23 19:29:57 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-09-24 15:09:37 +08:00
|
|
|
|
服务端起来后可访问：`/v1/health`、`/v1/me`、`/v1/projects`、`/v1/capabilities`、`/v1/sessions`。
|
|
|
|
|
|
未接入任何业务系统时能力清单为空——这是正确行为（ADR-0009：未接入时平台也要能正常启动）。
|
|
|
|
|
|
|
2026-09-23 19:29:57 +08:00
|
|
|
|
## 开发约定
|
|
|
|
|
|
|
|
|
|
|
|
| 约定 | 出处 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| 能力命名与描述七要素 | `docs/spec/capability-description.md` |
|
|
|
|
|
|
| 问法评测集与门槛 | `docs/eval/README.md` |
|
|
|
|
|
|
| 数据存储写法（整数毫秒、应用侧主键、JSONB/TEXT） | `docs/adr/0007-storage-and-consistency.md` |
|
|
|
|
|
|
| 架构决策记录 | `docs/adr/`（写完不改，改结论就新写一份） |
|
