refactor(repo): 扁平化仓库结构 by DeliciousBuding · Pull Request #12 · TokenDanceLab/AgentHub

DeliciousBuding · 2026-05-22T08:34:19Z

摘要

将顶层结构收敛为 docs/、app/、hub-server/、edge-server/、runner/、api/、scripts/、.agenthub/。
删除旧主线占位目录 apps/、services/、packages/、proto/、docker/，Docker 规则改为按模块就近配置。
将协议主线改为 REST JSON API + WebSocket typed events，新增 api/openapi.yaml、api/events.schema.json、api/README.md。
新增 docs/module-boundaries.md 和 docs/protocol-rest-websocket-migration-plan.md，同步 README、AGENTS 和关键 architecture/reference 文档。

验证

python -m json.tool api\events.schema.json > $null
python -c "import pathlib; s=pathlib.Path('api/openapi.yaml').read_text(encoding='utf-8'); assert s.startswith('openapi: 3.1.0'); assert '\\t' not in s; print('openapi basic check ok')"
git diff --cached --check
目录检查：新目录存在，旧目录 apps/services/packages/proto/docker 不存在

Refs #1

Copilot

Pull request overview

本 PR 将仓库从原先的 apps/ / services/ / packages/ / proto/ 分层占位结构，重构为以模块为中心的扁平目录（app/、hub-server/、edge-server/、runner/、api/ 等），并把协议主线从 proto-first 调整为 REST JSON API + WebSocket typed events，同步更新关键文档入口与参考文档的“当前主线”表述。

Changes:

扁平化仓库顶层目录，迁移/替换各模块 README，并移除旧占位目录树与相关 .gitkeep。
新增 api/ 作为协议契约入口（OpenAPI + JSON Schema），更新 docs/protocol.md 等文档以匹配新协议方向。
新增/更新模块边界与迁移计划文档，调整 reference 索引与若干 backend 参考文档的“历史参考”定位。

Reviewed changes

Copilot reviewed 50 out of 113 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
services/runner/README.md	删除旧 `services/` 结构下 Runner README（迁移到根级 `runner/`）。
services/runner/internal/workspace/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/service/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/security/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/preview/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/logs/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/executor/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/diff/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/adapters/opencode/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/adapters/codex/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/adapters/claude-code/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/runner/internal/adapters/.gitkeep	删除旧目录占位文件（移除 `services/` 树）。
services/edge-server/README.md	删除旧 `services/` 结构下 Edge README（迁移到根级 `edge-server/`）。
runner/README.md	新增根级 Runner README（中文职责/协议面/依赖说明）。
runner/internal/workspace/.gitkeep	新 Runner 目录结构占位。
runner/internal/service/.gitkeep	新 Runner 目录结构占位。
runner/internal/security/.gitkeep	新 Runner 目录结构占位。
runner/internal/preview/.gitkeep	新 Runner 目录结构占位。
runner/internal/logs/.gitkeep	新 Runner 目录结构占位。
runner/internal/executor/.gitkeep	新 Runner 目录结构占位。
runner/internal/diff/.gitkeep	新 Runner 目录结构占位。
runner/internal/adapters/opencode/.gitkeep	新 Runner 目录结构占位。
runner/internal/adapters/codex/.gitkeep	新 Runner 目录结构占位。
runner/internal/adapters/claude-code/.gitkeep	新 Runner 目录结构占位。
runner/internal/adapters/.gitkeep	新 Runner 目录结构占位。
runner/internal/.gitkeep	新 Runner 目录结构占位。
runner/cmd/.gitkeep	新 Runner 入口目录占位。
runner/.gitkeep	Runner 模块目录占位。
README.md	更新顶层目录表、启动命令与协议主线表述。
README_EN.md	同步英文 README 的目录/启动命令/协议主线表述。
proto/agenthub/v1/README.md	删除旧 proto-first “唯一协议源头”说明（协议主线迁移到 `api/`）。
packages/workspace-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/workspace-core/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/ui-kit/README.md	删除旧 `packages/` 规划文档（前端共享改为 `app/shared/`）。
packages/transport/resolver/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/transport/README.md	删除旧 `packages/transport` 说明（扁平化后改为模块内 package/契约优先）。
packages/transport/model/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/transport/client/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/transport/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/sync-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/sync-core/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/protocol/ts/generated/.gitkeep	删除旧协议生成目录占位（不再以 `packages/protocol` 为主入口）。
packages/protocol/schema/.gitkeep	删除旧协议 schema 目录占位（迁移到 `api/`）。
packages/protocol/README.md	删除旧协议包说明（proto-first 退出主线）。
packages/protocol/go/generated/.gitkeep	删除旧协议生成目录占位（迁移到 `api/`）。
packages/memory-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/im-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/artifact-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/approval-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/approval-core/.gitkeep	删除旧目录占位文件（移除 `packages/` 树）。
packages/agent-core/README.md	删除旧 `packages/` 规划文档（职责迁移到 module-boundaries）。
packages/adapters/README.md	删除旧 `packages/` 规划文档（适配层归属 runner）。
hub-server/README.md	更新 Hub README 的协议面与依赖来源（指向 `api/` / module-boundaries）。
hub-server/internal/ws-gateway/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/user/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/sync/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/store/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/runner-registry/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/relay/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/orchestrator/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/memory/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/im/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/device/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/contact/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/auth/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/artifact/.gitkeep	新 Hub 目录结构占位。
hub-server/internal/.gitkeep	新 Hub 目录结构占位。
hub-server/cmd/.gitkeep	新 Hub 入口目录占位。
hub-server/.gitkeep	Hub 模块目录占位。
edge-server/README.md	新增根级 Edge README（中文职责/协议面/依赖说明）。
edge-server/internal/sync-client/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/security/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/runner-manager/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/memory/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/local-ws/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/local-store/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/local-orchestrator/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/local-api/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/im-lite/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/hub-client/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/context-builder/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/artifact-index/.gitkeep	新 Edge 目录结构占位。
edge-server/internal/.gitkeep	新 Edge 目录结构占位。
edge-server/cmd/.gitkeep	新 Edge 入口目录占位。
edge-server/.gitkeep	Edge 模块目录占位。
docs/topology.md	更新模块边界章节以匹配扁平目录与新模块职责。
docs/reference/README.md	更新索引描述：标注参考性内容并指向 `api/` 作为主协议入口。
docs/reference/04-plan/01-research-to-implementation.md	更新调研到实现映射与目录/启动流程示例（改为 `api/` + 扁平目录）。
docs/reference/03-build/backend/16-hub-server-requirements.md	更新对齐目标引用：从 `proto/` 改为 `api/` 与 module-boundaries。
docs/reference/03-build/backend/14-scaffold-services.md	更新 scaffold 文档定位与示例路径，移除 proto/buf 必选依赖表述。
docs/reference/03-build/backend/13-protobuf-schema.md	明确 Protobuf 方案为参考，不是当前 M0 主协议入口。
docs/reference/03-build/backend/02-go-services.md	明确该文档为参考，目录示例与当前主线不一致。
docs/reference/03-build/backend/01-protocol.md	明确该文档为早期建模参考，当前主协议入口为 `api/`。
docs/protocol.md	将协议主线改为 REST + WebSocket typed events，并新增 event envelope 与错误格式说明。
docs/protocol-rest-websocket-migration-plan.md	新增迁移计划文档，列出后续补齐 OpenAPI/事件 schema 的任务。
docs/project-management.md	更新 M0 issue 表述（从“唯一协议源头”转为“API/事件契约”）。
docs/module-boundaries.md	新增模块职责边界文档，承接原 `packages/*` 规划。
docs/language-policy.md	更新文档范围与术语示例，匹配新目录与协议术语。
docs/glossary.md	更新术语：用“API 契约/事件契约/Typed Event”替代“唯一协议源头”。
docs/deepseek-handoff.md	更新 DeepSeek 文档处理范围与“不翻译”规则，匹配新目录与 event type。
docs/chinese-documentation-roadmap.md	更新中文化路线图的目标文件列表与验收表述。
docs/architecture.md	更新架构图中的路径命名与“协议轻量优先”表述。
docs/architecture-optimization.md	标注扁平化后的新目录与 `api/` 协议主线入口。
docs/agent-loop.md	将“JSON-RPC 方向”改为“REST 命令 + WebSocket 事件流”的主链路描述。
app/web/src/.gitkeep	新增 Web App 目录占位。
app/web/.gitkeep	新增 Web App 目录占位。
app/shared/.gitkeep	新增 Shared App 目录占位。
app/desktop/src-tauri/.gitkeep	新增 Desktop App 目录占位。
app/desktop/.gitkeep	新增 Desktop App 目录占位。
api/README.md	新增 API 契约入口说明（REST + WebSocket typed events）。
api/openapi.yaml	新增最小 OpenAPI 3.1 文档（REST endpoints 框架）。
api/events.schema.json	新增 WebSocket event envelope JSON Schema（枚举 type、基本字段）。
AGENTS.md	更新仓库结构与协议变更流程说明（协议改为先更新 `api/`）。

Comments suppressed due to low confidence (1)

hub-server/README.md:33

hub-server/README.md 位于仓库根级 hub-server/ 下，链接到 docs/reference/... 时不应使用 ../../，否则会跳出仓库根目录导致链接失效。建议将该相对路径改为从 hub-server/ 指向根目录下 docs/ 的正确路径（例如 ../docs/reference/...）。

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    "type": {
+      "type": "string",
+      "enum": [
+        "message.created",
+        "message.delta",
+        "run.started",
+        "run.output",
+        "run.status.changed",
+        "approval.requested",
+        "artifact.created",
+        "preview.ready",
+        "run.finished",
+        "error"
+      ]
+    },
+    "traceId": {
+      "type": "string"
+    },
+    "sentAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true
+    }


+paths:
+  /v1/projects:
+    get:
+      summary: List projects
+      responses:
+        "200":
+          description: Project list
+    post:
+      summary: Create or register a project
+      responses:
+        "201":
+          description: Project created
+  /v1/threads:
+    get:
+      summary: List threads
+      responses:
+        "200":


refactor(repo): 扁平化仓库结构

e027251

Copilot AI review requested due to automatic review settings May 22, 2026 08:34

Copilot started reviewing on behalf of DeliciousBuding May 22, 2026 08:34 View session

DeliciousBuding merged commit 09eb697 into master May 22, 2026
2 checks passed

DeliciousBuding deleted the refactor/flat-repo-structure branch May 22, 2026 08:37

Copilot AI reviewed May 22, 2026

View reviewed changes

DeliciousBuding mentioned this pull request Jun 27, 2026

[T1.1] Repo structure cleanup SPEC baseline #368

Merged

This was referenced Aug 29, 2026

[PM/客户体验] 用户可见错误面审计与改进切片清单 #2072

Closed

[Mobile] Hub-only 合规与体验差距审计（四波复盘配套） #2094

Closed

[数据库] Hub Redis 键面审计（TTL/有界性/失效路径） #2119

Closed

Navigation Menu

Uh oh!

refactor(repo): 扁平化仓库结构 - #12

refactor(repo): 扁平化仓库结构#12
DeliciousBuding merged 1 commit into
masterfrom
refactor/flat-repo-structure

DeliciousBuding commented May 22, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

DeliciousBuding commented May 22, 2026

摘要

验证

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants