From 535a5d5654d8e02aab36b00d85418c6f270c05a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=86=B0=E6=9C=94?= <565183519@qq.com> Date: Mon, 13 Jul 2026 20:25:40 +0800 Subject: [PATCH] docs: restore Tolaria desktop product architecture --- ARCHITECTURE.md | 3 + apps/README.md | 3 + architecture/README.md | 2 + architecture/TOLARIA-DESKTOP-ARCHITECTURE.md | 133 +++++++++++++++++++ 4 files changed, 141 insertions(+) create mode 100644 architecture/TOLARIA-DESKTOP-ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4514ce4..11dabba 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -28,3 +28,6 @@ Tolaria / 光湖 App 展示 2. `RECEIPT`：实际完成内容、证据、限制与未完成项。 3. `DECISION`：由谁确认了什么，以及适用范围。 4. `VIEW`：Tolaria/光湖 App 如何将仓库事实呈现给人类。 + +桌面产品的正式架构基线见 +[`architecture/TOLARIA-DESKTOP-ARCHITECTURE.md`](architecture/TOLARIA-DESKTOP-ARCHITECTURE.md)。 diff --git a/apps/README.md b/apps/README.md index 27ac724..424bb4a 100644 --- a/apps/README.md +++ b/apps/README.md @@ -3,3 +3,6 @@ 此目录用于人类可见的光湖 App 与 Tolaria 侧界面扩展。 第一版只实现工单、状态和回执的可视化闭环。 + +Tolaria / 光湖 App 的产品边界、授权模型和版本路线见 +[`../architecture/TOLARIA-DESKTOP-ARCHITECTURE.md`](../architecture/TOLARIA-DESKTOP-ARCHITECTURE.md)。 diff --git a/architecture/README.md b/architecture/README.md index 2a63dbb..864c3e5 100644 --- a/architecture/README.md +++ b/architecture/README.md @@ -1,5 +1,7 @@ # 光湖研发元系统架构 +产品架构基线：[`TOLARIA-DESKTOP-ARCHITECTURE.md`](TOLARIA-DESKTOP-ARCHITECTURE.md)。 + ## 主路径 ```text diff --git a/architecture/TOLARIA-DESKTOP-ARCHITECTURE.md b/architecture/TOLARIA-DESKTOP-ARCHITECTURE.md new file mode 100644 index 0000000..fc874ac --- /dev/null +++ b/architecture/TOLARIA-DESKTOP-ARCHITECTURE.md @@ -0,0 +1,133 @@ +# Tolaria / 光湖 App · 开源产品架构 v0.1 + +> 状态：产品架构基线 +> +> 适用仓库：HoloLake Platform +> +> 产品定位：光湖自己的开源人类协作桌面端 + +## 1. 产品边界 + +Tolaria（桌面显示名：光湖）是人类进入光湖产品能力的界面，不是服务器控制台、人格记忆仓库或第二套事实源。 + +它让不写代码的人完成一条可追溯闭环：用自然语言提出任务、看清计划与风险、确认或拒绝、查看结果与历史。 + +```text +人类 + ↓ 自然语言、确认、查看 +Tolaria / 光湖 App + ↓ 工单与查询 +HoloLake Platform（正式事实） + ↓ 受控处理请求 +服务 / Agent 适配层 + ↓ 受限动作、验证、回执 +HoloLake Platform + ↓ 状态与结果视图 +Tolaria / 光湖 App +``` + +## 2. 已确认的桌面端事实 + +| 项 | 当前事实 | +| --- | --- | +| 平台 | macOS Apple Silicon 原生应用 | +| Bundle ID | `com.guanghu.desktop` | +| 当前版本 | `0.1.0` | +| 深链接 | `tolaria://`、`guanghu://` | +| 本地能力 | 可连接用户配置的本地模型服务器，用于 AI 对话 | +| 产品类别 | Productivity | + +以上是从现有应用包元数据恢复的事实；不推定其尚未验证的网络接口、账户体系或服务器权限。 + +## 3. 目标组件 + +| 组件 | 责任 | 不负责 | +| --- | --- | --- | +| Desktop Shell | 对话、工单、授权卡片、状态和回执的人类视图 | 保存服务器密钥、执行任意 shell | +| Local Connector | 与用户明确配置的本地模型/本机能力通信 | 静默收集本机数据 | +| Platform Repository | WorkOrder、Decision、Receipt、模块状态的可审计事实源 | 存放 token、密码或私钥 | +| Integration Gateway | 校验输入、创建受限请求、同步状态 | 把仓库文本直接变成命令 | +| Agent Runtime | 生成计划、调用允许的能力、写回回执 | 自行扩大权限或绕过授权 | +| Enterprise Lighthouse | 多人审批、一次性工单、授权与审计协调 | 保存各目标服务器的根密钥 | + +## 4. 第一期开源闭环 + +```text +1. 人类在光湖 App 输入“我想做什么”。 +2. App 创建 WORKORDER 草案：目标、范围、风险、验收条件。 +3. Agent 返回可读计划；App 展示，不执行。 +4. 涉及现实影响时，App 显示明确授权卡片。 +5. 获批后，Gateway 只调用该工单允许的动作。 +6. 执行端写入 RECEIPT：实际动作、证据、结果、限制、时间。 +7. App 从仓库/受控 API 读取回执并展示；人类可验收或关闭工单。 +``` + +v0.1 的最小页面： + +- 任务首页：创建与查看 WORKORDER； +- 计划页：范围、风险、依赖和待授权项； +- 授权页：批准、拒绝、过期与多人审批状态； +- 回执页：结果、证据、未完成项与历史； +- 设置页：本地模型连接、仓库连接状态、隐私说明。 + +## 5. 授权与安全边界 + +```text +语言/历史资料 → 只能提供上下文 +自然语言请求 → 只能创建工单草案 +已确认工单 → 只可调用明确允许的动作 +执行结果 → 必须形成回执 +``` + +- 任何服务器操作必须有目标、动作范围、过期时间、授权主体与回执。 +- App、仓库、日志和截图不得保存 token、密码、验证码或私钥。 +- 本地模型连接默认是用户显式配置的本机连接；未经确认不得上传对话、本地文件或凭证。 +- 紧急人工入口与日常审批分离；日常流程不要求人类记忆 token。 +- 工单或广播不能自动成为现实执行命令。 + +## 6. 数据模型 + +| 对象 | 最小字段 | +| --- | --- | +| WORKORDER | 编号、请求摘要、目标、范围、风险、状态、验收条件 | +| DECISION | 编号、工单、授权人、决定、适用范围、过期时间 | +| RECEIPT | 编号、工单、实际动作、执行者、证据、结果、限制、时间 | +| VIEW | 视图编号、数据来源、展示状态、最后同步时间 | + +仓库为正式可审计事实源；App 可缓存展示数据，但缓存不得成为独立真相。 + +## 7. 开源边界与里程碑 + +### v0.1 · 可演示闭环 + +- macOS App 展示工单、计划、授权状态与回执； +- 只接一个受控的演示动作； +- 深链接打开指定工单或回执； +- 本地模型连接仅用于生成计划，不自动执行。 + +### v0.2 · 多人协作 + +- 企业灯塔审批适配； +- 多人、时限、一次性授权； +- 模块注册与项目状态视图。 + +### v1.0 · 可发布产品 + +- 跨平台桌面端； +- 稳定插件/API 契约； +- 可导出审计记录； +- 文档化的自托管与升级路径。 + +## 8. 与现有仓库的映射 + +```text +apps/ 人类可见界面与 UI 扩展 +integrations/ Tolaria、仓库、Agent 适配 +services/ 受控后台服务和 API +workorders/ 协作请求 +receipts/ 执行与验证回执 +architecture/ 本文与产品边界 +standards/ 已确认标准 +``` + +> Tolaria 是产品入口；HoloLake Platform 是研发与事实主仓；世界门户与个人历史仓不直接承担产品运行职责。