插件市场用户指南

Tether 建立在 Cordis 插件架构之上——一切皆插件。从 v0.21 起，Tether 引入官方插件市场（Plugin Market），以源码工程为基本单位统一管理内置能力与外部扩展包。用户可在市场中分类浏览全部插件、按组合行逐行启停、修改强类型配置、获取公开源码，并支持对可定制插件一键生成本地插件项目，交由 AI 辅助定制、验证与安装，随时能够一键恢复内置原版。

1. 市场入口与界面外壳

• 进入市场：点击 Web UI 左上角的 Tether 品牌标志与名称按钮 即可打开插件市场。
  • 在侧栏展开状态下，点击品牌按钮直接切换到插件市场，处于市场页时品牌按钮呈高亮选中态；
  • 在侧栏折叠（Rail）状态下，品牌标识仍作为展开侧栏的开关；
  • 原侧栏中的「插件」与「开发者」两个独立入口已全面退役并移除。
• 页面外壳：
  • 顶部操作区提供刷新按钮，以及用于通过 nuget: 或 path: 安装外部包的「添加插件」向导；
  • 主体区域由插件市场接管，提供分类导航、状态筛选、实时搜索与卡片目录。

2. 分类浏览与状态筛选

生产环境已注册展示元数据提供者（Tether.Bundles.PluginMarketMetadata），将所有能力程序集与插件包划分为 8 大领域分类（按展示顺序排列）：

1. 工具（Tools）：终端工具（Tether.Terminal.Tools）、Shell 工具（Tether.Shell.Tools）、文件工具（Tether.Fs.Tools）、网页工具（Tether.Web.Tools）、语言服务器工具（Tether.Lsp.Tools）与 LSP stdio 通信（Tether.Lsp.Stdio）、后台任务工具（Tether.Jobs.Tools）、代码运行时工具（Tether.PtcRuntime.Tools）、Office 转 PDF 工具（Tether.OfficeToPdf）、Wasm 工具（Tether.Wasm.Tools）、文件搜索（Tether.Fs.Search）等；
2. 模型与服务商（Models）：模型服务商多 provider 客户端与重试路由（Tether.Llm.Providers）、DeepSeek 思考链扩展运行时/HTTP 扩展/文件管理/插件清单（Tether.Llm.DeepSeek.*）、NyxID 认证与 HTTP 服务（Tether.NyxId.*）等；
3. 会话与上下文（Session）：会话标题（Tether.Session.Title）、回合大纲（Tether.Session.TurnOutline）、会话统计（Tether.Session.Stats）、会话查询（Tether.Session.Query）、会话检查点（Tether.Session.Checkpoint）、会话遥测（Tether.Session.Telemetry）、DeepSeek 会话日志（Tether.Session.Log.DeepSeek）、会话历史压缩与图片卸载压缩（Tether.Compaction.*）、技能（Tether.Skill）、长程目标与目标回合驱动（Tether.Goal.*）、执行反馈（Tether.Feedback）等；
4. 编排与自动化（Orchestration）：Subagent 编排与跨会话桥接（Tether.Subagent.*）、Agent Teams 协同（Tether.AgentTeams）、声明式工作流引擎与模板定义（Tether.Workflow.*）、Webhook 触发（Tether.Webhook）、后台任务管理（Tether.Jobs.Local）等；
5. 界面（Ui）：用量面板（Tether.Usage.Web）、技能库页面/集成/本地库（Tether.Skill.Library.*）、Cordis 控制台（Tether.Web.CordisConsole）、Web 客户端模块（Tether.Web.ClientModules）等；
6. 安全与沙箱（Security）：本地操作系统沙箱隔绝（Tether.Sandbox.Local）、权限预设与授权判定（Tether.Authorization）；
7. 扩展（Extensions）：宿主扩展接入点（Tether.Extensions）、MCP 客户端（Tether.Mcp）、生命周期钩子（Tether.Hooks）、用量数据源与用量运行时（Tether.Usage.*）；随源码分发的外部插件包（extensions/*）以及第三方安装包；
8. 系统（System）：底层存储（Tether.Storage.Json/Sqlite）、组合规格与动态 Patch（Tether.Composition）、插件包管理器（Tether.PluginPackages）等核心设施。

[!NOTE]

• 未登记条目归属：未显式登记元数据的内置程序集默认归入「系统」，外部插件包缺省归入「扩展」；
• 系统分类默认折叠：「系统」分类在左侧导航中默认折叠收起，提供折叠切换按钮（▸ 展开 / ▾ 收起），该分类绝大多数属于不可定制的基础设施。

在市场顶部提供快速检索与过滤工具：

• 状态筛选：支持快速切换查看 全部 · 已定制 · 运行中 · 已停用 · 失败；
• 实时搜索：输入关键字可实时按插件名称、标识与描述过滤；
• 响应式视口适配：当屏幕宽度小于 768px（移动端或窄屏）时，左侧分类导航自动转换为顶部的横向滚动芯片（Chips），保证在各种设备上的浏览体验。

3. 卡片徽标、状态与主动作

市场中的每一张卡片代表一个源码工程（程序集或插件包）。卡片清晰呈现来源、运行状态与可用操作：

来源徽标 (Origin)

• 内置（builtin）：Tether 核心随包自带的内置程序集；
• 扩展（extension）：官方仓库 extensions/ 提供的外部插件包；
• 第三方（package）：用户通过 NuGet 或本地路径安装的外部插件包；
• 本地（local）：用户从模板新建的本地插件；
• 已定制 vX（customized）：当且仅当该条目已安装定制版本（project.installedVersion 存在，如 1.0.0-local.1）时呈现，标注当前运行的是安装后的定制替换版本；
• 带界面（hasClient）：标注该插件注册了浏览器前端 UI 模块；
• 权限要求：若当前会话预设不含完全访问权限，标注「需要完全访问」提示。

运行状态点 (Status)

运行状态由条目所包含的组合行（Rows）汇总计算（PluginMarketCatalogProjection.ComputeStatusRollup）：

• 未安装（notInstalled）：组合行数量为 0（尚未安装进当前 profile）；
• 失败（failed）：至少有一行包含失败信息或处于错误相位（rows.Any(r => r.Failure != null || r.Phase == "failed")）；
• 已停用（disabled）：启用的行数量为 0（所有行均已被用户手动停用）；
• 运行中（running）：所有组合行均已启用且无失败（enabledCount == rows.Count）；
• 部分运行（partial）：介于启用与停用之间（部分行启用、部分行停用）。

卡片 Tooltip 与主动作按钮

• 不可定制原因 Tooltip：当条目不可定制（customizable == false）且附带原因码时，卡片原生 title 属性会浮现格式化后的不可定制原因（例如「系统受保护核心行，不可替换」、「存在其他宿主程序集反向引用，替换会破坏类型身份」等）；
• 定制：适用于被判定为可定制（customizable）且本地尚无工程的条目。点击打开定制确认框；
• 获取源码：适用于不可定制但公开源码可用的条目。点击打开只读研究项目确认框；
• 打开项目：当本地已存在对应项目目录（entry.project != null）时，主按钮切换为 打开项目，点击直接切换到该项目工作区并开启新会话。若工作区注册表条目此前被手动删除但本地目录仍存在，系统会自动重新登记进工作区注册表并恢复显示名；
• 恢复原版：当条目运行着定制版本（project.installedVersion 存在）时，在详情页提供该操作。

4. 插件详情页

点击任意插件卡片即可展开完整详情页：

• 概述与元数据：展示程序集名/包 ID、所属分类、详细功能介绍以及是否包含前端界面；
• 组合行（Rows）逐行管理：
  • 以表格逐行列出该工程向 Cordis 贡献的所有组合行；
  • 提供单行独立的启用/停用开关；
  • 实时显示底层 Fiber 相位（pending、loading、active、failed、unloading；停用行无相位）；
  • 若某行属于系统核心安全保护集（PluginProtection），将明确标注受保护原因并禁止停用；
  • 顶部提供「全部启用/停用」批量按钮，操作时自动跳过受保护行；
• 配置（Config）按组合行管理：
  • 深度集成专属原生配置卡：对于终端、Agent 循环、Subagent 与网页搜索四大核心能力，无缝在详情页内渲染对应的原生配置卡；
  • 组合行级 Schema 配置表单：若条目包含一个或多个带配置项的组合行（hasConfig == true），详情页按组合行分别渲染独立的配置表单块（若有多行则明确显示各行名称与行 ID），基于强类型的 Schema 表单呈现配置项，修改后带 baseRevision 进行 CAS 乐观并发保存；
  • 若条目没有任何可配置行，界面如实显示「该插件没有可配置项」；
• 源码信息与校验状态：
  • 明确标出源码公开仓库（eanzhao-os/tether-plugins）、上游 Git Ref（发行版为对应版本 Tag，如 tether-v0.21.0；开发版为 main）、工程在仓库内的相对路径；
  • 源码内容摘要（SHA-256 Digest）与校验：
    • 已校验：当前宿主为发行版，内嵌了权威索引 plugins.index.json，下载的源码内容摘要与内嵌索引逐字节比对完全一致；
    • 源码未校验：当前运行的是本地源码编译的开发版宿主（未嵌入发行索引），源码从公开仓库 main 分支拉取，界面如实提示「源码未校验，可能和运行版本不一致」；
• 不可定制原因展示：若条目不可定制，详细展示触发的判定规则与代码（如 shared-types、protected、internals 等）；
• 底部操作区：根据插件状态提供「启用/停用全部」、「定制 / 打开项目」、「恢复原版」（针对已定制插件）与「卸载」（针对第三方包）。

5. 动作语义与确认框说明的四件事

市场中的核心交互均秉承透明、诚实与安全的原则。

各动作行为定义

确认框必须说明的四件事

在点击「定制」或「获取源码」时，系统会弹出确认模态框，向用户明确告知以下四件事：

1. 下载来源：展示远端源码仓库与下载地址（如 https://github.com/eanzhao-os/tether-plugins）；
2. 目标目录：展示本地落盘的规范化绝对路径，路径来源于服务端快照的 projectsRoot（配置来源为 settings 的 plugin-market.projectsRoot，缺省为 ~/.tether/plugin-projects，拼接 <slug>；客户端禁止自行指定 projectsRoot 或 ref；界面明确提示「如遇重名将自动追加 -2 等后缀」）；
3. 执行特权提示：明确标注**「编译和安装会以当前用户权限执行插件代码」**——树外插件在进程内加载，享有与宿主同等的系统权限；
4. 工具链要求：
   • 若带前端界面（hasClient == true）：说明编译需要 .NET SDK 10.x、Node.js ≥ 22.19 与 pnpm；
   • 若为纯后端插件（hasClient == false）：说明编译仅需要 .NET SDK 10.x；
   • 如实呈现本机工具链探测结果。

[!NOTE]

• 若条目被判定为不可定制，确认框将以醒目警告标注**「只读研究项目，不能安装」**并附带具体原因；
• 若当前会话的权限预设非 danger-full-access（完全访问），确认框会提示用户：「当前会话预设不含完全访问（danger-full-access）权限，创建后需在会话中切换预设方可编译或安装」。

6. 工具链要求与探测提示

在插件项目中编译与安装定制插件需要本地开发工具链支持：

• 后端 C# 编译：需要 .NET SDK 10.x（通过 dotnet --list-sdks 严格探测是否存在 10.x SDK）；
• 前端 TS/React 编译（仅限带界面的插件）：需要 Node.js ≥ 22.19（通过 node -v 探测）与 pnpm（通过 pnpm -v 探测）。

诚实探测原则：

• 市场顶部与定制确认框会自动探测本机工具链；
• 若检测到工具链缺失，界面会展示警告提示（例如：⚠ 未检测到 .NET SDK 10：可以浏览和下载源码，定制版无法编译）；
• Tether 绝不会在后台未经授权自动下载或安装任何全局 SDK 或运行时环境。缺失工具链不影响用户浏览市场、阅读文档或下载只读源码；需要编译定制包时，由用户根据自身操作系统自行安装配置。

7. 权限要求：danger-full-access

会话权限预设（IPermissionPresets）包含 read-only、workspace-write 与 danger-full-access 三种标准预设。本地插件的编译（dotnet build）、打包与安装涉及本地进程启动与磁盘写入：

• 项目内 AI 在调用 plugin_project 工具执行 build、install 或 uninstall 动作时，当前会话预设必须为 danger-full-access（完全访问）；
• Fail-closed 权限阻断：若会话处于受限预设（如 read-only 或 workspace-write）或沙箱策略状态缺失，工具将直接拒绝执行并返回 PERMISSION_REQUIRED 错误，绝非一次性提权审批弹窗；
• 解决方式：用户只需在会话聊天界面右下角的权限预设下拉菜单中，将预设切换为 danger-full-access 即可，切勿盲目重复尝试。

8. 出错恢复与隔离保证

Tether 的架构设计保证：用户负责定制代码的逻辑与编译，Tether 负责如实回报结果且绝不拖垮宿主。

1. 市场一键恢复原版

若定制的插件在运行中出现逻辑错误或非预期行为，用户无需借助 AI，随时可以在市场详情页点击 「恢复原版」。宿主将卸载定制包并原位恢复内置插件。本地项目文件完整保留在磁盘上，方便继续排查修复。

2. 启动失败隔离保证

即使定制包存在严重缺陷导致程序集加载失败或插件 ApplyAsync 阶段抛出未捕获异常，Tether 启动流程与包管理器也会自动隔离该失败包：将该包记录为失败并跳过挂载，被替换的内置行自动恢复活跃。宿主绝不会因为某个定制插件出错而无法启动，用户始终可以正常进入 Web 界面恢复原版或查看失败日志。

3. 命令行终极兜底

若遇到极端异常或希望在无浏览器环境下完全重置，可在终端中执行：

# 卸载指定定制包并恢复内置原版（默认针对 local profile，交互式确认）
tether plugin remove custom.<slug>

# 免交互确认卸载指定 profile 的定制包
tether plugin remove custom.<slug> --profile web --yes

离线状态下执行卸载后，重启宿主即可恢复为纯净的内置组合。

9. 源码下载安全与网络限制

插件市场从公开仓库下载源码归档时受到严格的安全沙箱与资源配额约束：

• 域名白名单与安全传输：强制使用 HTTPS 协议，仅允许从 codeload.github.com 与 github.com 下载源码；
• 重定向限制：最多允许 5 跳重定向，且每跳重定向的目标主机均严格复核白名单；
• 归档大小与解压配额：
  • 源码压缩包大小上限为 64 MiB（MaximumArchiveBytes）；
  • 解压后展开总容量上限为 64 MiB；
  • 单个解压文件大小上限为 8 MiB；
  • 归档内文件总数上限为 1024 个，解压目录深度上限为 32 层；
• 下载超时：默认流式下载超时为 120 秒；
• 安全检查与错误码：
  • SOURCE_UNAVAILABLE：网络错误、404、重定向超限、非白名单主机或连接超时；
  • SOURCE_DIGEST_MISMATCH：下载内容的整树确定性摘要与嵌入索引不符；
  • SOURCE_TOO_LARGE：归档总大小或单文件大小超出上限；
  • UNSAFE_ARCHIVE_ENTRY：压缩包包含绝对路径、路径穿越（../）、符号链接、硬链接或特殊设备文件；
• 运维级回环测试覆盖：支持环境变量 TETHER_PLUGIN_MARKET_SOURCE_ARCHIVE_URL 覆盖源码归档下载地址，但严格限制仅允许本地回环地址（127.0.0.1、::1、localhost），且协议必须为 HTTP 或 HTTPS；非回环地址或非法 URI 启动直接抛出 InvalidOperationException 阻断。

10. 侧栏工作区的三种图标识别

当插件源码落地为本地项目后，Tether 宿主会自动推导工作区类型（WorkspaceView.kind），并在侧栏渲染对应的专属图标：

1. 对话工作区（default）：保留的默认工作区，显示新对话气泡图标；
2. 普通文件夹工作区：用户自主添加的普通代码目录，显示常规文件夹图标；
3. 插件项目工作区（plugin）：检测到项目根目录下存在 .tether/plugin-project.json 标记，自动渲染专属的风车插件图标，悬停卡片会显示「插件项目 · <显示名>」。

无论是在市场中点击「定制/打开项目」进入，还是用户手动在侧栏「添加工作区」选中插件项目目录，均能精准识别并呈现插件图标。

11. 旧版数据迁移声明

[!IMPORTANT] Tether 处于 Pre-release 阶段，基础设施演进优先于向下兼容。v0.19 试验性的插件工作台（Plugin Workbench）与开发者模式已完全退役：

• 历史路径 ~/.tether/plugin-workbench/ 下的旧草稿与快照数据不做自动迁移；
• 若您在旧版中留有草稿代码并希望保留，请手动将文件从该目录拷贝出来，作为普通工作区文件夹打开或作为新插件项目的源码参考。

下一步