📄️ 🏗️ 系统架构
本文档详细介绍 Wegent 平台的系统架构、组件设计和技术栈。
📄️ 💻 开发环境搭建
本文档详细介绍如何在本地环境搭建 Wegent 开发环境。
📄️ Dynamic Context（动态上下文注入）
背景
📄️ 测试框架文档
本文档介绍 Wegent 项目的单元测试框架设置。
📄️ 📋 CRD 架构
本文档为开发者提供 Wegent CRD（自定义资源定义）架构的详细技术参考，帮助理解内部结构和实现细节。
📄️ Skill 开发指南
本文档提供 Skill 系统的技术实现细节，包括架构、Provider 开发和 API 参考。
📄️ 协作模式开发指南
本文档提供协作模式的详细配置示例、实战案例和技术实现细节。
📄️ MCP 工具重构指南
English | 简体中文
📄️ 外部知识库 MCP
English | 简体中文
📄️ 技能传递链路
本文描述 Wegent 在不同执行场景中的技能选择、解析、传递与消费方式，重点说明为什么技能相关逻辑必须由 backend 统一收敛，以及 sandbox / 本地设备为什么不能只依赖技能名称。
📄️ 外部知识源
English | 简体中文
📄️ 知识库索引保护
背景
📄️ 实体权限扩展
本文档介绍 Wegent 的统一资源分享权限架构，涵盖当前授权机制、权限处理逻辑、扩展架构设计，以及如何通过 IExternalEntityResolver 接入内部定制化授权系统。
📄️ 网页抓取服务
适用范围
📄️ 对外暴露能力指南
本文档介绍 Wegent 项目中对外暴露功能能力的标准方式，以 Knowledge Base MCP 实现为例，说明如何让你的功能被 AI Agent 调用。
📄️ 本地设备架构
本文档介绍本地设备支持的技术架构，包括通信协议、心跳机制和安全设计。
📄️ 预执行钩子
预执行钩子允许您在 Executor 执行任务之前运行自定义脚本。这对于自定义初始化、安全检查、环境设置或与外部系统集成非常有用。
📄️ 本地运行时任务
Wework 的本地运行时任务用于展示和继续用户已经在设备上创建的 Codex 或 Claude Code 工作。它不再把这些工作导入中心库的 TaskResource 或 Subtask，也不再依赖 Backend projects 表生成侧栏列表。列表来自在线设备 executor 返回的运行时线程，并在前端展示为两类：
📄️ Issue 未读状态
Issue 未读属于当前用户，由服务端持久化在现有 Issue 元数据中。读取不会修改 Issue 的版本或更新时间，也不需要表结构迁移。
📄️ 运行时清理
运行时清理接口用于手动清理长时间无更新的执行环境。它只删除运行时 Pod/容器，不删除 Backend 中的 Task 记录和历史消息。
📄️ 本地设备命令 RPC
本地设备命令 RPC 允许 Backend 向指定在线 local executor 设备下发一条预配置的本机 shell 命令，并等待命令完成后拿到结果。该能力用于运维检查、工作区诊断和后端主动探测，不参与 Task/Subtask 生命周期，也不会产生聊天消息。
📄️ Wework AI 分支名生成
Wework 的分支选择器可以根据当前输入内容或任务标题生成 Git 分支名。生成模型复用“友好任务标题”的模型配置；未配置或配置模型暂不可用时，使用当前任务模型。
📄️ Connector Apps 架构与部署
Connector Apps 让 Wework 在不修改 Codex 源码、也不依赖 ChatGPT 登录的前提下连接组织内部系统。上游既可以是 MCP Server，也可以是普通 HTTP API。系统把“App”拆成三个独立职责：Wegent Admin 管理定义、可见范围和固定请求头，Wegent Backend 读取 kinds 中的 ConnectorApp 资源并适配上游协议，Executor 向 Codex 统一暴露本地 MCP。Wework 不提供 Connector 设置页面，只在连接 Wegent 云端后同步可用能力。
📄️ 全局能力同步
全局能力同步允许 Backend 将用户启用的 Skill、Plugin 和 MCP 下发到在线 local executor 设备。Project task 可以复用这些本机能力，非 Project task 继续使用任务级 .claude 配置目录，保持隔离。
📄️ 交互表单 Defer 流程
本文档说明 interactiveformquestion MCP 工具的标准渲染和恢复流程。该流程用于让 Agent 在执行过程中向用户展示结构化表单，并在用户提交后通过后续消息继续执行。
📄️ 沙箱工作区归档
沙箱工作区归档用于在 Sandbox runtime 被 24 小时空闲清理删除前保存文件状态，并在同一 Task 后续重新对话时恢复到新建的 Sandbox runtime。该机制复用现有 executor Pod 工作区归档链路，executor 与 sandbox 都使用 home/ 和 workspace/ 两个归档根目录，并通过 runtime_type 选择运行时 home 路径。
📄️ Wework 消息滚动验证
共享聊天区域使用正常 DOM 坐标：顶部 scrollTop = 0，底部 scrollTop = max(0, scrollHeight - clientHeight)。桌面工作台、临时会话和网页 Issue 会话复用相同实现。短会话从顶部排列，多余空间留在消息与底部输入框之间；内容超出可用高度后，按跟随或阅读状态处理滚动。滚动条使用同一真实范围。
📄️ 外部 OAuth 2.0 接入指南
English | 简体中文
📄️ 任务运行态状态机
背景
📄️ Chat Shell 优雅退出
Chat Shell 的 /v1/responses 是长连接流式接口。Kubernetes 终止 Pod 时，必须先停止新流量，再等待已有流结束，否则用户会看到中断的 SSE 响应。
📄️ Chat Shell 派发连接与诊断
HTTP 模式下，Backend 通过 OpenAI Responses SDK 调用 Chat Shell 的
📄️ Rust MySQL 数据库迁移
Rust Backend 在启动后台消费者和 HTTP 服务前准备数据库，仅支持 MySQL。
📄️ 用户运行时配置
English | 简体中文
📄️ Wework 遥测与产品分析
Wework 将产品使用分析、桌面错误诊断和服务端可观测性分开处理：
📄️ Rust 认证兼容性
Rust 已接管的 API 以对应 Python 认证依赖为兼容性标准。路由归属仍由活动路由配置决定；
📄️ 插件与智能应用埋点
本文定义插件和智能工作台事件的采集范围、成功边界与验证要求。
📄️ QuickCard 输入预设
概述
📄️ Wework 分身遥测
分身复用 Wework 统一遥测客户端、接收地址、字段策略和用户开关，默认不附带用户身份。详见 遥测配置。
📄️ Wework Smart App 跨域 iframe 与区域截图
本文说明 Smart App 在 Wework 中嵌入跨域页面并把局部截图交给插件的通用架构。
📄️ Chat Shell 上下文治理
概述
📄️ 共享技能目录
Wework 提供“技能”设置页，用于把本地 Claude 和 Codex 的个人技能目录统一到 ~/.agents/skills。该能力面向在线 Claude Code 本地设备，通过本地设备命令 RPC 执行，不在浏览器端直接访问文件系统。
📄️ Chat Shell 附件上下文管理（预览与按需读取）
如果需要先了解三阶段整体脉络、设计取舍和实现边界，先看
📄️ 云项目协作架构
UI 与交互实现以 /Users/hongyu9/Downloads/wework-delivery-v4-TODO.pen 为当前 V4 设计源，不根据本文重新推导页面布局。
📄️ 云端协作领域模型
本文定义 Wework 与 Wegent 共用的云端协作概念。目标是让产品只暴露一套
📄️ 协作空间存储模型
本文定义协作空间功能的数据落地方式。目标是在不建立第二套资源系统的前提下，
📄️ Wework 本地项目与智能体执行
本地项目由 Wework 存储和驱动，不依赖 Wegent Backend。项目、Issue、评论、
📄️ Wework 协作执行与授权
项目智能体绑定、智能体资源所有者、任务指派人和执行设备所有者是不同身份。
📄️ Wework 执行状态与历史展示：2026-09-17 调查
下文先记录修复前的调查：只读取运行数据并做隔离对照，当时产品代码保持回滚后的状态；未恢复历史数据、未替换执行器、未重启用户进程。下文区分已证实的原因和仍待验证的界面表现。
📄️ 协作权限架构与不可破坏的规则
空间决定管理范围，项目默认继承空间成员，资源通过明确授权参与项目。所有列表和操作使用同一套服务端权限判定。本文是经用户确认的产品契约；测试验证这些规则，不能为了通过测试而降低规则。
📄️ 协作模板
Wework 从“协作 → 模板”发现模板，Wegent 从能力商店的协作模板分类进入。
📄️ 项目成员设置界面
成员页使用紧凑的中性设置布局，分别呈现身份、职责与能力、角色与来源、操作。每个成员行保持四个单元格，避免继承来源增加网格列数而使角色和按钮错位。
📄️ 设备产物规则：撤回自动迁移及版本兼容边界
公共 Ghost/default/wegent-wework 的提示词自动更新已经撤回。本功能不要求改写生产数据库的 Ghost，也不通过迁移回滚管理员配置。
📄️ Wework 我的分身
连接企业服务端后，首次主分身引导、新建个人角色或云端项目分身默认选择可用云设备或远程设备（优先设备的默认标记），两者均不可用时默认本机。创建表单允许显式改选本机或其他设备；切换时沿用未保存修改确认。首次打开时优先保留已配置的本地档案；未保存的默认占位角色不视为已有配置。显式选择的云设备按企业地址和账号记住，设备离线不切换旧档案。开始编辑后设备清单变化不自动切换运行位置。保存和对话复用目标 Executor 的现有 Runtime 通道。未连接企业服务端及本地项目保持现有执行方式，不增加插件、提供方设置或云主机创建。
📄️ Rust 库与构建边界
Backend 和 Executor 分别编译、测试和发布，保留各自的 Cargo 锁文件。共享源码通过本地路径依赖复用，不依赖另一个应用的二进制，也不建立全仓 Cargo workspace。
📄️ Wework 渐进式能力加载
Wework 默认使用 Codex 原生 Code Mode。内置工具与 MCP 工具保留原生注册、执行、权限和结果处理，通过 ALL_TOOLS 的名称与描述按需发现。模型请求中的 exec 保留执行接口与发现说明，不预先附带整个嵌套工具目录；发现结果提供实际调用签名。明确设置为 direct 的自定义模型仍按其设置执行。
📄️ Wework 长会话与运行时响应性
任务控制、任务目录和历史正文承担不同职责。长会话可以包含数千次工具执行，
📄️ Wework DSH 连接扩展点
连接是 Wework Core DSH 插件的一种能力。Codex 插件协议保持不变；Wework 连接插件可以依赖已有 Codex 插件，也可以自行访问外部系统。采集、分页和格式转换由代码执行，模型只参与角色内的工作整理和处理。
📄️ Runtime 会话的一致性
Wework 的会话内容归共享会话 Store 所有。任务是否运行、Goal 是否继续和输入框草稿是独立状态，不能用展示消息是否存在来推断历史损坏，也不能在面板里维护另一份可写的会话。
📄️ 🛠️ 开发者指南
English | 简体中文
📄️ 数据库迁移指南
本指南介绍如何使用 Alembic 管理 Wegent 后端应用的数据库迁移。
📄️ OpenTelemetry Setup Guide
This guide explains how to set up and configure OpenTelemetry for distributed tracing and metrics in Wegent.
📄️ 响应式开发指南
概述