任务上下文管家 statedock/statedock-plugins

StateDock 插件

智能体来来去去。任务始终都在。

为 StateDock 准备的共享技能和轻量插件包：保存计划、恢复任务上下文、跨编码工具记录进度。所有包都连接现有的 StateDock Remote MCP 服务。本仓库只包含客户端说明和打包内容。

0.1.1 版为任务领取和完成流程加入了结构化 Git Code Reference 指引。Codex 本地市场安装和带认证的远程连接均已验证。DeepSeek Harness 和 ChatGPT 在 0.1.0 的分发版本仍是已发布/已提交的版本；更新后的 0.1.1 包已在本地准备好，尚未发布或重新提交。

你能做什么

| 技能 | 用途 | 边界 |
| statedock-plan | 把暂缓的想法保存为 PLAN，或保留其讨论和决策 | 不启动实现 |
| statedock-pickup | 恢复任务上下文；获得授权时明确认领一个已分配的 READY 任务 | 返回上下文，完成一次领取后即停止 |
| statedock-update | 记录提供的进度、阻塞项，或已验证的完成交接 | 不执行所报告的工作 |

插件不执行任务代码、不启动智能体、不运行后台轮询、不调度工作、不编排智能体。你的编码宿主按你的指令执行实现。把任务设为 READY 不会唤醒智能体。

示例请求：

- “保存一个计划，为这个项目添加导出支持。不要开始执行。”
- “恢复 SD-000123 的上下文，不要改变其状态。”
- “认领一个分配给我身份的 READY 任务，并显示其上下文。不要实现它。”
- “把这些已验证的结果记录为 SD-000123 的交接。”

技能在写入前会验证所连接的实例和仓库的项目绑定。它们使用实时工具 schema，缺少所需工具或绑定时即停止。服务器记录和附件提供上下文；它们不授予新的执行权限。

在 Codex 中安装

要求：支持插件的 Codex 客户端、Git，以及访问 StateDock 的权限。不需要本地 StateDock 服务器。Node.js 仅在开发和打包时需要。

克隆本仓库，然后注册其本地市场：

git clone https://github.com/statedock/statedock-plugins.git
cd statedock-plugins
codex plugin marketplace add "$PWD"
codex plugin add statedock@statedock-local
codex plugin list --json

已检入的 .agents/plugins/marketplace.json 直接指向 core/，即维护中的可移植插件源。此本地安装无需构建，也无需手动复制缓存。重启 Codex 并打开新聊天，检查三个技能是否都可用。

如果 codex 不在你的 PATH 中，请使用已安装命令行工具的完整可执行文件路径。在此测试的 macOS 安装上：

CODEX_BIN="/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex"
"$CODEX_BIN" plugin marketplace add "$PWD"
"$CODEX_BIN" plugin add statedock@statedock-local

这个应用路径因安装环境而异。手动配置 marketplace 和独立 MCP 替代方案，见安装详情。本仓库尚未发布到公开插件 marketplace。

Codex 身份验证

插件内置的 Remote MCP 连接默认走宿主的 OAuth 流程。安装插件，Codex 提示时授权 StateDock，然后开一个新会话。除非你确实想要一套独立的基于 token 的配置，否则不要用第二个连接替换它。

如果要用 StateDock token 建立独立的 Codex MCP 连接，Codex 可以替你加上 bearer 方案。把环境变量安全地设好，然后配置它的名称，而不是 token 本身：

codex mcp add statedock --url https://statedock.dev/mcp --bearer-token-env-var STATEDOCK_TOKEN

连接前，在宿主的安全环境中设置 STATEDOCK_TOKEN；它的值保持为原始 token，不要加 Bearer 前缀。最终请求头是 Authorization: Bearer <token>。在 Codex 连接界面里，Bearer token env var 字段填 STATEDOCK_TOKEN（变量名），不是 Authorization，也不是 token 值。如果宿主提供的是通用的自定义请求头字段，则 Key 填 Authorization，Value 填 Bearer <token>。绝不要提交真实 token，也不要把它粘贴到共享文件里。OAuth 和手动配置的 bearer token 是两种可选的验证方式。

验证身份并检查连接

内置的服务配置是：

Endpoint: https://statedock.dev/mcp
Transport: streamable-http (Agent Plugins format)

宿主提示时，在它的连接界面里完成 OAuth。测试期间保留已有的授权；新的插件连接可能仍需要单独同意。装了插件并不代表验证已经完成。

先从这个只读请求开始：

调用 StateDock get_instance_info，报告 publicOrigin、mcpUrl 和 transport。不要创建或认领任何任务。

预期结果：

{
"publicOrigin": "https://statedock.dev",
"mcpUrl": "https://statedock.dev/mcp",
"transport": "remote"
}

然后确认项目 UUID 及其仓库路径。要完成 READY 领取，凭证必须绑定到目标 StateDock Agent Identity。插件名或 token 标签不能确立身份。

绝不要提交 token，也不要在聊天里发送。OAuth 凭证留在宿主中。如果要另建独立的 Codex 连接，配置模板 展示了 OAuth 或安全提供环境变量的做法。避免配置重复的 StateDock 连接；使用前先查看每个连接的实例信息。

平台介绍与安装

StateDock 在支持共享 Agent Plugins 包的主机上提供同样的三个工作流：保存延后的计划、恢复任务上下文、记录进度或经过验证的交接。这个集成只负责存储和恢复任务状态；它不运行代码、不启动智能体、不调度任务，也不编排智能体。可安装性和审核状态因平台而异：

| 平台 | 集成提供什么 | 当前分发方式和安装路径 |
| Codex | 共享的 plan、pickup、update 技能，外加 StateDock Remote MCP。 | 用上面的命令从本仓库的本地 marketplace 安装。已在隔离的 Codex 命令行配置档中验证过。它不是 Codex Marketplace 的公开上架条目。 |
| ChatGPT app | 同样的共享技能，以及经过身份验证的 StateDock MCP 连接。 | 0.1.0 版本已提交审核。审核通过并发布后，就能在 ChatGPT 插件目录里找到它；0.1.1 已在本地准备好，但尚未重新提交。 |
| Cursor | 共享的 Agent Plugins 包，不含 Cursor 专属的服务代码。 | 仓库的 marketplace 元数据和本地测试说明都已就位。真实的 Cursor 安装和 Marketplace 上架仍需验证；参见 Cursor 指南和提交说明。 |
| DeepSeek Harness | 原生 Cordis Bundle，内含共享技能；可选 MCP 组件在显式启用后可连接 StateDock。 | @statedock/dsh-plugin@0.1.0 已发布到 npm。用 dsh plugin --profile web add @statedock/dsh-plugin@0.1.0 安装，或改用 --profile desktop。参见 Harness 指南。 |
| Google Antigravity | 原生插件 manifest 和远程 MCP 配置，与共享技能一起打包。 | 适配器在本仓库的 adapters/antigravity/ 下。按下面的说明在本地构建并安装。要进入 Marketplace 需要 Google 另行审核。 |
| Claude Code | 计划中的原生 manifest 和 MCP 配置，围绕共享技能展开。 | 仅有调研笔记；目前还没有可安装的 Claude Code 包。 |
| OpenCode | 计划中的原生 MCP 连接和共享技能。 | 仅有调研笔记；目前还没有可安装的 OpenCode 包。 |

Google Antigravity

Antigravity 适配器的 About 文案是：“Save plans, restore task context, and record progress with StateDock.” 语言：English（插件描述、README 和打包的技能说明）。Google 文档中的 plugin.json schema 只接受插件名称和描述，拒绝额外字段，所以语言信息应放在 About/上架文案里，而不是 manifest 里。

要从仓库根目录构建可安装的插件文件夹和 ZIP：

npm ci --ignore-scripts
npm run build:antigravity
npm run pack:antigravity
构建会把插件文件夹打印在 dist/antigravity-/statedock 下；ZIP 和 SHA-256 文件写到 artifacts/ 下。在 Antigravity 命令行里，安装构建打印出的那个文件夹：

agy plugin install /absolute/path/to/dist/antigravity-.../statedock
agy plugin list

或者启动交互式命令行，使用 /plugin，然后选择 Install from local directory。如果只想装到某个工作区，手动把构建出的 statedock 文件夹复制到 <workspace>/.agents/plugins/；如果要装到所有工作区，用 ~/.gemini/config/plugins/。在 Antigravity 应用里，打开 Customizations → Installed 查看已安装的插件。这些本地安装方式由 Google 提供文档；它们并不代表插件已经上架 Google Marketplace。参见 Antigravity 适配器指南。

插件连接 https://statedock.dev/mcp。先完成宿主支持的身份验证流程，然后确认 get_instance_info 报告 publicOrigin=https://statedock.dev、mcpUrl=https://statedock.dev/mcp，并且走的是远程传输，之后才能使用 StateDock 任务工作流。不要在 mcp_config.json 里添加 token。

DeepSeek Harness

Harness 适配器暴露 StateDock 共享的规划、上下文接续和进度交接技能。它可选的原生 MCP 组件默认关闭，这样当 Harness 已经有通过身份验证的 StateDock 服务器时，不会建立重复连接。安装已发布的包：

dsh plugin --profile web add @statedock/dsh-plugin@0.1.0
Or install into the desktop profile:
dsh plugin --profile desktop add @statedock/dsh-plugin@0.1.0

本地的 0.1.1 包尚未发布。身份验证、可选的 MCP 配置和验证方法，参见 Harness 适配器指南。

ChatGPT 应用和 Cursor

ChatGPT 应用包正在等待审核；在 OpenAI 批准并发布之前，用户无法从公开目录安装。Cursor 的仓库 marketplace 元数据已经包含在内，但我们不声称已完成 marketplace 上架或已验证 Cursor 安装。当前的门槛参见上面链接的平台提交说明。

Claude Code 和 OpenCode 目前只有调研笔记。还不要把它们的适配器目录当作安装包使用。

Cursor Marketplace 申请

根目录的 .cursor-plugin/marketplace.json 把 core/ 里同一个可移植插件暴露出来，供仓库发现。品牌 logo 已提交在 core/assets/ 下。参见提交字段与剩余验收检查。Marketplace 材料正在准备中；实际的 Cursor 安装和 marketplace 批准尚未验证。

已发布和已提交的上架信息

- DeepSeek Harness： @statedock/dsh-plugin 0.1.0 已发布，适配 Harness 0.2.0-rc.2；更新版 0.1.1 已在本地准备好，但尚未发布。项目在官方 Show Your Plugins 讨论帖中做了介绍。精选目录的投稿材料已备好，等仓库年龄要求满足后就提交。
- ChatGPT 应用： 版本 0.1.0 已提交 OpenAI 审核；更新版 0.1.1 的打包材料已在本地准备好，但尚未重新提交。批准和发布仍在等待中。
- Codex： 可以把这个 GitHub 仓库当作本地市场来安装。这不是 Codex Marketplace 的上架条目。
- Cursor： Marketplace 投稿材料正在准备；安装和批准都还没验证。

可移植格式兼容并不保证在每个客户端上都能安装、认证或按预期工作流运行。官方来源与平台准入条件区分了有文档记录的能力和实际测试结果。

开发与打包

需要 Node.js 22+ 和系统 tar：

npm ci --ignore-scripts
npm run validate
npm test
npm run build
npm run pack
npm run pack:zip

可选的集成检查：

npm run verify:codex
npm run verify:endpoint

- validate 检查随仓库附带的官方 JSON Schema、技能元数据、预期端点、包清单和可能的凭据。
- validate:antigravity 检查原生 Antigravity manifest、远程 MCP 端点和共享技能清单；build:antigravity 生成可安装的文件夹，pack:antigravity 生成带 SHA-256 的 ZIP。这些都不会发布或提交到 Google 的 Marketplace。
- test 覆盖无效 manifest、原生与可移植传输混淆、凭据、错误端点、符号链接、意外的运行时文件和归档完整性。
- build 输出一个全新的 dist/build-/statedock 文件夹。每次构建都保留已有输出。
- pack 把 .tgz 和 SHA-256 文件写入 artifacts/。用基于文件夹的安装器之前，先解压它。这不是 Codex ZIP 上传，也不是 npm 发布。
- verify:codex 安装到临时 Codex home，校验缓存内容，不会改动你平时的配置或凭据。
- verify:endpoint 只探测公开的 OAuth discovery；不会执行需要认证的操作。

生成的核心包包含两个 manifest、三个技能、品牌 logo、LICENSE 和 README。pack:zip 生成的 ZIP 把插件文件放在归档根目录，供 OpenAI 上传。单独的 Antigravity 适配器包含它的原生 manifest、MCP 配置、三个技能、LICENSE 和平台 README。构建依赖、配置模板、服务端代码和凭据都被排除在外。这些脚本从不 push、deploy 或 publish。

core/ Shared portable manifests and Skills
.agents/plugins/ Codex local marketplace
.cursor-plugin/ Cursor 仓库市场 core/assets/ 共享发布方品牌 logo adapters/ Harness Bundle 源码及其他平台调研 adapters/antigravity/ Google Antigravity 原生插件源码与安装指南 schemas/ 官方 Agent Plugins 1.0.0 schema 快照 templates/ 独立安全连接示例 scripts/ 校验、构建、打包与集成检查 test/ 包边界与完整性测试 docs/ 安装、MCP 契约与验证证据

只需改一次 core/，然后重新构建各发行版本。不要把生成的副本当作独立源码维护。更新已安装的插件时，通过你的宿主刷新或重装，并核对缓存版本与技能内容。

DeepSeek Harness

运行 npm run build:harness，为经过测试的 0.2.0-rc.2 宿主生成原生 @statedock/dsh-plugin tgz。默认安装会复用已有的已认证 StateDock 连接。可选的环境变量 token 连接在显式启用前处于关闭状态。参见安装与验证。

验证与后续步骤

2026-10-14，七个包测试、全部三项技能格式检查、Codex 安装与公开 OAuth 发现均通过。依赖审计报告零漏洞。服务端一处实例上报 bug 已修复并部署；两个已有的已认证连接现在都能上报预期的远程实例。其中一个连接使用 bearer token；应用连接器另行授权。新插件的完整端到端计划、领取、更新验收尚待完成。

后续里程碑：

1. 完成新插件的已认证工作流验收，包括显式领取行为与错误处理。
2. 测试 Cursor，然后只在 Claude Code、DeepSeek Harness 和 OpenCode 需要的地方添加原生适配。保留共享源码内容。
3. 添加发布自动化与市场提交材料。发布需要另行授权；仓库分发不等于市场批准。

参见验证证据与 MCP 契约。

许可证

MIT 适用于本仓库的客户端说明与打包。StateDock 的托管商业服务、认证、计费与用户数据不包含在内。本许可证不授予访问托管服务或其他用户记录的权限。