chore(docs): Batch 1-4 仓库治理——安全脱敏、别名替换、配置修正、API同步、文档修复

Batch 1 (CRITICAL): 生产 IP 随 deployment-record.md 移出至 .ops/，OIDC client ID 脱敏
Batch 2 (HIGH): hk1/hk2/us1/us2 别名全局替换为通用术语，.env.example 变量名修正，
  config.yaml Redis 端口 6380→6379，dev-start 脚本 Hub 端口修正，
  dev-up migrate 死代码移除，config.docker.yaml dev-secret 清空，
  Makefile benchmark/govulncheck 修正
Batch 3 (API): OpenAPI 幽灵端点标记 planned/deprecated，HTTP 方法 PATCH→PUT 修正，
  4 个 Hub 路由路径 x-deprecated，events.md 补 9 个未记录事件类型，
  标记 planned/defined-not-emitted 事件
Batch 4 (Docs): 5 个死链修复，reference/INDEX.md 标注过期，
  docs/archive/INDEX.md 补齐编目，项目计数 21→25 统一，孤儿文件编目

Co-Authored-By: Claude <noreply@anthropic.com>

Author: DeliciousBuding

.env.example

@@ -60,17 +60,29 @@ AGENTHUB_TOKENDANCE_ID_ALLOWED_REDIRECT_URIS=http://127.0.0.1/callback,http://lo
 # ─────────────────────────────────────────────
 
 # ── Edge Server ─────────────────────────────
+# Listen address (default: 127.0.0.1:3210)
+# AGENTHUB_ADDR=127.0.0.1:3210
+
+# Default agent name registered on this edge
+# AGENTHUB_AGENT_DEFAULT=claude
+
+# Default model for agents spawned by this edge
+# AGENTHUB_AGENT_MODEL=claude-sonnet-4-20250514
+
+# Shared secret for edge-to-hub authentication
+# AGENTHUB_EDGE_AUTH_TOKEN=
+
 # Claude Code CLI 路径（Windows 示例）
-# CLAUDE_CODE_PATH=C:\Users\<user>\.local\bin\claude.exe
+# AGENTHUB_CLAUDE_CODE_PATH=C:\Users\<user>\.local\bin\claude.exe
 # macOS/Linux 示例
-# CLAUDE_CODE_PATH=/usr/local/bin/claude
+# AGENTHUB_CLAUDE_CODE_PATH=/usr/local/bin/claude
 
 # OpenCode CLI 路径
-# OPENCODE_PATH=opencode
+# AGENTHUB_OPENCODE_PATH=opencode
 
 # Codex CLI 路径
-# CODEX_PATH=codex
+# AGENTHUB_CODEX_PATH=codex
 
 # ── Desktop ─────────────────────────────────
 # VITE_EDGE_URL=http://127.0.0.1:3210
-# VITE_HUB_URL=http://127.0.0.1:4210
+# VITE_HUB_URL=http://127.0.0.1:8080

.gitignore

@@ -78,7 +78,7 @@ yarn-error.log*
 *.backup
 *.sql.gz
 
-# AgentHub deployment state (hk2 production)
+# AgentHub deployment state (production)
 hub-server/deployments/.env.production
 hub-server/deployments/.env
 hub-server/deployments/backups/

Makefile

@@ -30,7 +30,7 @@ test-hub-full:
 
 bench:
 	cd edge-server && go test -bench=. -benchmem ./internal/events/
-	cd hub-server && go test -bench=. -benchmem ./internal/middleware/
+	cd hub-server && go test -bench=. -benchmem ./internal/service/
 
 # ── Lint ─────────────────────────────────────────
 
@@ -49,8 +49,8 @@ coverage:
 sec:
 	cd edge-server && gosec ./...
 	cd hub-server && gosec ./...
-	govulncheck ./edge-server/...
-	govulncheck ./hub-server/...
+	cd edge-server && govulncheck ./...
+	cd hub-server && govulncheck ./...
 
 # ── All checks (CI pipeline) ─────────────────────
 

api/events.md

@@ -110,34 +110,36 @@ Runner stdout/stderr 不要一行一帧直接刷给 UI。
 | type | 阶段 | 说明 |
 |---|---|---|
 | `project.created` | P0 | 项目创建或注册 |
-| `project.updated` | P0 | 项目元数据更新 |
-| `conversation.created` | P1 | 会话创建 |
-| `conversation.member.added` | P1 | 会话成员加入 |
+| `project.updated` | P0 | 项目元数据更新 (planned) |
+| `conversation.created` | P1 | 会话创建 (planned) |
+| `conversation.member.added` | P1 | 会话成员加入 (planned) |
 | `thread.created` | P0 | Thread 创建 |
 | `thread.updated` | P0 | Thread 状态或标题更新 |
-| `thread.forked` | P1 | Thread 分支创建 |
+| `thread.deleted` | P0 | Thread 删除 |
+| `thread.forked` | P1 | Thread 分支创建 (planned) |
 | `message.created` | P0 | 消息创建 |
 | `message.delta` | P0 | Agent 消息流式增量 |
 | `item.created` | P0 | Thread Item 创建 |
-| `item.updated` | P0 | Thread Item 状态更新 |
+| `item.updated` | P0 | Thread Item 状态更新 (planned) |
 
 ### Execution / Runtime
 
 | type | 阶段 | 说明 |
 |---|---|---|
-| `runner.online` | P0 | Runtime/target compatibility event: legacy Runner 在线 |
-| `runner.offline` | P0 | Runtime/target compatibility event: legacy Runner 离线 |
+| `runner.online` | P0 | Runtime/target compatibility event: legacy Runner 在线 (planned) |
+| `runner.offline` | P0 | Runtime/target compatibility event: legacy Runner 离线 (planned) |
 | `run.queued` | P0 | AgentRun 已排队 |
 | `run.started` | P0 | AgentRun 已启动 |
-| `run.output` | P0 | 单条 stdout/stderr 输出 |
+| `run.output` | P0 | 单条 stdout/stderr 输出 (planned — 当前仅 `run.output.batch` 已实现) |
 | `run.output.batch` | P0 | 批量 stdout/stderr 输出 |
-| `run.status.changed` | P0 | AgentRun 状态变化 |
-| `approval.requested` | P0 | 请求用户审批 |
-| `approval.decided` | P0 | 用户已审批 |
-| `artifact.created` | P0 | 产物创建 |
-| `artifact.updated` | P1 | 产物元数据更新 |
-| `preview.ready` | P0 | 预览可用 |
-| `preview.stopped` | P1 | 预览停止 |
+| `run.status.changed` | P0 | AgentRun 状态变化 (planned) |
+| `run.persistence_error` | P0 | 持久化错误，payload: `{ runId, error }` |
+| `approval.requested` | P0 | 请求用户审批 (planned) |
+| `approval.decided` | P0 | 用户已审批 (planned) |
+| `artifact.created` | P0 | 产物创建 (planned) |
+| `artifact.updated` | P1 | 产物元数据更新 (planned) |
+| `preview.ready` | P0 | 预览可用 (planned) |
+| `preview.stopped` | P1 | 预览停止 (planned) |
 | `run.finished` | P0 | AgentRun 正常结束 |
 | `run.failed` | P0 | AgentRun 失败 |
 | `run.cancelled` | P1 | AgentRun 已取消（已实现，补文档） |
@@ -153,9 +155,16 @@ Runner stdout/stderr 不要一行一帧直接刷给 UI。
 | `run.agent.compact_boundary` | P1 | 上下文压缩边界 |
 | `run.agent.api_retry` | P1 | API 重试通知 |
 | `run.agent.task_started` | P1 | 子代理任务启动 |
+| `run.agent.task_dispatched` | P1 | 子代理任务已派发 |
 | `run.agent.task_progress` | P1 | 子代理任务进度 |
 | `run.agent.task_notification` | P1 | 子代理任务完成/失败 |
+| `run.agent.sub_agents_complete` | P1 | 所有子代理执行完毕，payload: `{ parentId, childCount, allComplete }` |
 | `run.agent.session_state_changed` | P1 | 会话状态变更（idle/running/requires_action） |
+| `run.agent.status_change` | P1 | Agent 适配器状态变更 |
+| `run.agent.session_metrics` | P1 | 会话度量信息 |
+| `run.agent.context_usage` | P1 | 上下文使用量报告 |
+| `run.agent.context_warning` | P1 | 上下文容量警告 |
+| `run.agent.context_compaction` | P1 | 上下文压缩通知 |
 | `run.agent.hook_started` | P1 | Hook 执行开始 |
 | `run.agent.hook_progress` | P1 | Hook 执行输出 |
 | `run.agent.hook_response` | P1 | Hook 执行完成 |
@@ -294,11 +303,11 @@ Hub 使用扁平帧格式（与 Edge 的 EventEnvelope 不同）：
 
 | type | 说明 |
 |------|------|
-| `session.created` | 会话创建，payload: `{ session_id, type, name, owner_id, members[] }` |
-| `session.dissolved` | 群解散，payload: `{ session_id }` |
-| `session.member_joined` | 成员加入，payload: `{ session_id, member_id, member_type }` |
-| `session.member_left` | 成员离开，payload: `{ session_id, member_id }` |
-| `session.info_updated` | 会话信息变更，payload: `{ session_id, changes{} }` |
+| `session.created` | 会话创建 (defined, not yet emitted)，payload: `{ session_id, type, name, owner_id, members[] }` |
+| `session.dissolved` | 群解散 (defined, not yet emitted)，payload: `{ session_id }` |
+| `session.member_joined` | 成员加入 (defined, not yet emitted)，payload: `{ session_id, member_id, member_type }` |
+| `session.member_left` | 成员离开 (defined, not yet emitted)，payload: `{ session_id, member_id }` |
+| `session.info_updated` | 会话信息变更 (defined, not yet emitted)，payload: `{ session_id, changes{} }` |
 
 #### Device 事件（Hub→Client）
 

api/openapi.yaml

@@ -30,7 +30,7 @@ servers:
   - url: http://localhost:8080
     description: Local Hub Server
   - url: http://api.hub.vectorcontrol.tech
-    description: Production Hub Server (hk2)
+    description: Production Hub Server
 tags:
   - name: Foundation
     description: Health, capability and event stream handshake.
@@ -42,6 +42,44 @@ tags:
     description: Auth, user, contact, group, device, edge, sync, relay and cloud APIs.
 
 paths:
+  # ═══════════════════════════════════════════════════════════
+  # Edge Server — Implementation Status
+  #
+  # IMPLEMENTED: /v1/health, /v1/events, /v1/projects (GET/POST),
+  #   /v1/projects/{projectId} (GET only), /v1/threads (GET/POST),
+  #   /v1/threads/{threadId} (GET/PATCH/DELETE), /v1/threads/{threadId}/items,
+  #   /v1/threads/{threadId}/messages, /v1/items/{itemId},
+  #   /v1/runners (GET only), /v1/agents, /v1/runs (GET/POST),
+  #   /v1/runs/{runId} (GET), /v1/runs/{runId}:cancel,
+  #   /v1/metrics, /v1/agent-instances (GET only),
+  #   /v1/permissions/decide
+  #
+  # PLANNED (documented but not yet implemented):
+  #   PATCH/DELETE /v1/projects/{projectId},
+  #   GET/PATCH /v1/projects/{projectId}/memory,
+  #   GET/POST /v1/conversations,
+  #   GET/PATCH /v1/conversations/{conversationId},
+  #   POST /v1/conversations/{conversationId}:archive,
+  #   GET/POST /v1/conversations/{conversationId}/members,
+  #   DELETE /v1/conversations/{conversationId}/members/{memberId},
+  #   POST /v1/threads/{threadId}:archive,
+  #   POST /v1/threads/{threadId}:fork,
+  #   GET /v1/runners/{runnerId},
+  #   POST /v1/runners/{runnerId}:ping,
+  #   POST /v1/runners/{runnerId}:drain,
+  #   POST /v1/runs/{runId}:interrupt,
+  #   POST /v1/runs/{runId}:resume,
+  #   POST /v1/runs/{runId}:retry,
+  #   GET /v1/runs/{runId}/items,
+  #   GET /v1/runs/{runId}/logs,
+  #   GET /v1/runs/{runId}/diff,
+  #   GET/POST /v1/approvals and nested,
+  #   GET/POST /v1/artifacts and nested,
+  #   GET/POST /v1/previews and nested,
+  #   GET /v1/workspaces/{workspaceId} and nested,
+  #   POST /v1/agent-instances
+  # ═══════════════════════════════════════════════════════════
+
   /v1/health:
     get:
       tags: [Foundation]
@@ -1319,7 +1357,7 @@ paths:
           $ref: "#/components/responses/Ok"
 
   /client/contacts/{userId}/remark:
-    patch:
+    put:
       tags: [HubSyncRelay]
       operationId: hubUpdateRemark
       summary: Update contact remark.
@@ -1594,6 +1632,8 @@ paths:
       tags: [HubSyncRelay]
       operationId: hubRecallMessage
       summary: Recall (delete) a message.
+      x-deprecated: true
+      description: Deprecated session-scoped path. Use `POST /client/messages/{id}:recall` instead.
       x-agenthub-status: implemented
       x-agenthub-owner: Hub
       security: [{ bearerAuth: [] }]
@@ -1612,6 +1652,8 @@ paths:
       tags: [HubSyncRelay]
       operationId: hubPinMessage
       summary: Pin a message.
+      x-deprecated: true
+      description: Deprecated session-scoped path. Use `POST /client/messages/{id}:pin` instead.
       x-agenthub-status: implemented
       x-agenthub-owner: Hub
       security: [{ bearerAuth: [] }]
@@ -1630,6 +1672,8 @@ paths:
       tags: [HubSyncRelay]
       operationId: hubUnpinMessage
       summary: Unpin a message.
+      x-deprecated: true
+      description: Deprecated session-scoped path. Use `DELETE /client/messages/{id}/pin` instead.
       x-agenthub-status: implemented
       x-agenthub-owner: Hub
       security: [{ bearerAuth: [] }]
@@ -1648,6 +1692,8 @@ paths:
       tags: [HubSyncRelay]
       operationId: hubMarkMessageRead
       summary: Mark a message as read.
+      x-deprecated: true
+      description: Deprecated. No corresponding route exists in Hub router.
       x-agenthub-status: implemented
       x-agenthub-owner: Hub
       security: [{ bearerAuth: [] }]
@@ -1950,7 +1996,7 @@ paths:
       responses:
         "200":
           $ref: "#/components/responses/Ok"
-    patch:
+    put:
       tags: [HubSyncRelay]
       operationId: hubUpdateCustomAgent
       summary: Update a custom agent.
@@ -4143,8 +4189,7 @@ components:
         device_id:
           type: string
           format: uuid
-          description: Bound Hub desktop device id. Current target-bound dispatch requires an owner-owned desktop device; remote/cloud routing remains future work.
-          description: Stable Hub device UUID; must match the callback request.
+          description: Stable Hub device UUID; must match the callback request. Current target-bound dispatch requires an owner-owned desktop device; remote/cloud routing remains future work.
         redirect_uri:
           type: string
           format: uri

app/web/README.md

@@ -114,4 +114,4 @@ git diff --check
 - 根入口：[../../README.md](../../README.md)
 - API 契约：[../../api/README.md](../../api/README.md)
 - Shared 包：[../shared/README.md](../shared/README.md)
-- 系统架构：[../../docs/system-architecture.md](../../docs/system-architecture.md)
+- 系统架构：[../../docs/architecture/system-architecture.md](../../docs/architecture/system-architecture.md)

docs/architecture/implementation-guide.md

@@ -242,7 +242,7 @@ version / id / seq / type / scope / sentAt / payload
 - Agent 生成的代码由对应开发者负责审查、测试和解释。
 - 首次克隆后运行 `.\scripts\setup.ps1` 启用本地 hooks；需要参考仓库时运行 `.\scripts\setup.ps1 -Reference core`。
 - 并行开发使用 `.worktrees/`，具体规则见 `AGENTS.md`。
-- 客户端后续以 `docs/roadmap.md`、`docs/roadmaps/client.md` 和 `docs/handoff/STATE.md` 为当前入口；`docs/operations/client-roadmap.md` 仅保留为客户端方向轻量索引，`docs/operations/client-handoff.md` 是历史快照，不作为默认接手指南。
+- 客户端后续以 `docs/roadmap.md`、`docs/roadmaps/client.md` 和 `docs/handoff/STATE.md` 为当前入口；`docs/operations/client-roadmap.md` 仅保留为客户端方向轻量索引，`docs/archive/client-handoff.md` 是历史快照，不作为默认接手指南。
 
 PR 说明按影响选择填写：
 

docs/archive/INDEX.md

@@ -55,6 +55,10 @@
 | `client-handoff.md` | 历史交接 | 2026-05-22 历史快照，引用已废弃的 `runner/` 目录、旧分支名 `feat/client-dev`、旧 PR #26。当前客户端接手入口为 `docs/handoff/STATE.md`。 |
 | `desktop-shell-layout-progress-2026-05-25.md` | 进度记录 | Desktop shell 布局进度快照。已完成项已合入 `docs/roadmap.md` batch B，8 项后续 TODO 已提取到群聊评论。 |
 | `PLAN-adapt-trump-ui.md` | 历史计划 | 旧 `worktree-adapt-trump-ui` 工作计划。涉及从 Trump 5 页面 UI 提取共享组件、工程规范、测试框架和 WebUI 集成。相关代号已过期，当前以主文档、roadmap 和 handoff 状态为准。 |
+| `RESEARCH-SUMMARY-2026-05-24.md` | 研究交付 | 研究交付封面备忘录，汇总调研成果和参考来源。 |
+| `desktop-frontend-handoff.md` | 历史交接 | React 渲染循环修复交接文档，记录无限重渲染根因和修复方案。 |
+| `branches/` | 历史归档 | 历史分支归档（14 个文件），包含已合入或废弃的功能分支快照。 |
+| `review-archive/` | 审计归档 | 已归档的代码审查报告。 |
 
 ### 可参考原则 - 需要按新术语重解释
 

docs/archive/build-specs/backend/01-protocol.md

@@ -627,7 +627,7 @@ type DiffArtifact struct {
 	Additions    int          `json:"additions"`
 	Deletions    int          `json:"deletions"`
 	FileDiffs    []FileDiff   `json:"fileDiffs"`
-	AgentID      string       `json:"agentId"`       // 参考 cross-analysis-im-ux.md："Generated by [Edge:us1] Claude"
+	AgentID      string       `json:"agentId"`       // 参考 cross-analysis-im-ux.md："Generated by [Edge:edge-01] Claude"
 	ToolCallID   string       `json:"toolCallId"`    // 参考 cross-analysis-im-ux.md：追溯到 tool_use
 	CanApply     bool         `json:"canApply"`      // 参考 cross-analysis-sandbox-tools.md：WorkspaceProvider.ApplyPatch
 	CanDiscard   bool         `json:"canDiscard"`    // 参考 cross-analysis-sandbox-tools.md：WorkspaceProvider.Discard

docs/archive/build-specs/backend/07-observability.md

@@ -70,7 +70,7 @@ func NewLogger(format string, level slog.Level, attrs ...slog.Attr) *slog.Logger
 
 **生产 JSON**：
 ```json
-{"time":"2026-05-21T10:00:00.000Z","level":"INFO","msg":"run started","run_id":"abc123","agent":"claude-code","model":"claude-sonnet-4-6","service":"runner","edge_id":"us1"}
+{"time":"2026-05-21T10:00:00.000Z","level":"INFO","msg":"run started","run_id":"abc123","agent":"claude-code","model":"claude-sonnet-4-6","service":"runner","edge_id":"edge-01"}
 ```
 
 **本地 Text**：