docs(claude): 完善原生插件诊断与验收说明

README.md

@@ -12,7 +12,7 @@
 | --- | --- | --- |
 | Codex | 已实现，v0.2.0 | Windows；读取知识、编写/保存草稿、预览 |
 | Cursor | 本地插件；CLI 真实写动作通过 | Windows；技能、草稿创建/保存/预览 |
-| Claude Code | 原生插件安装和真实 MCP 连接通过 | 尚未完成模型写动作验收 |
+| Claude Code | 原生插件，v0.2.1 | v0.2.0 公开市场安装和真实 MCP 连接通过；模型写动作待验收 |
 | VS Code / Copilot、Gemini CLI | 配置安装器 | 默认 Windows 用户配置；尚未完成各客户端写动作验收 |
 
 需要使用设置 → Agent 中带「启用 MCP」入口、并包含默认技能包发现修复的 Quicker 新构建。Release 支持已实现，待包含这些变更的正式版发布；已发布旧版没有该入口时仍不可用。本次已验证 Debug 的草稿编写与预览，Release 配置内核测试和正式前端构建通过，正式安装包端到端仍待验收，详见[兼容性说明](docs/兼容性.md)。
@@ -46,7 +46,21 @@ claude plugin marketplace add QuickerOrg/quicker-agent-integrations
 claude plugin install quicker@quicker-agent-integrations --scope user
 ```
 
-执行 `/reload-plugins` 或重启 Claude Code，再用 `/mcp` 检查 Quicker。已通过 Claude Code 2.1.263 官方清单校验、本地市场安装和真实 MCP 连接检查；本机没有 Claude 登录状态，尚未完成模型写动作验收。
+启用 Quicker 设置 → Agent 中的 MCP 与允许写入，在 Claude Code 执行 `/reload-plugins` 或新开会话，再用 `/mcp` 检查 Quicker。首次连接需要在 Quicker 中确认 `claude-quicker-plugin` 客户端。
+
+安装、MCP 连接和模型登录需要分别检查：
+
+```powershell
+claude plugin list --json
+claude mcp list
+claude auth status
+```
+
+已通过 Claude Code 2.1.263 官方清单校验、v0.2.0 公开市场安装和真实 MCP 连接检查。`Connected` 不表示模型已登录；若尚未登录，启动 `claude` 并执行 `/login`，或按组织配置完成认证，然后请求：
+
+> 用 Quicker 写一个动作，显示“来自 Claude Code”，保存到暂存区并打开预览，不运行。
+
+Quicker 原生插件可与官方 [codex-plugin-cc](https://github.com/openai/codex-plugin-cc) 同时安装，前者直接提供 Quicker 工具，后者从 Claude Code 委托 Codex 审查或处理代码。两者不互为依赖，Codex 登录不能代替 Claude 登录。更新、连接超时处理及验收范围见[Claude Code 安装和诊断](docs/客户端安装.md#claude-code-安装和诊断)。
 
 ## VS Code / Copilot 与 Gemini CLI
 

docs/兼容性.md

@@ -18,14 +18,14 @@
 | 正式前端构建 | 2026-09-07：生产前端构建与产物审计通过 |
 | 正式安装包端到端 | 尚未执行正式 MSI / 混淆 Release 的完整验收；不将内核测试或 Debug 草稿验收视为正式安装包已验证 |
 | Cursor CLI | 2026-09-07：2026.08.11-e8db854；v0.2.0 本地安装包技能加载、实时知识发现、4 步动作创建/保存/预览通过。IDE 3.7.12 的插件设置界面重载尚未单独操作验收 |
-| Claude Code | 2026-09-07：2.1.263；v0.2.0 插件与市场通过官方 validator，在隔离配置中原生安装并 enabled=true；mcp list 连接真实 Quicker 成功。无 Claude 登录状态，未验证模型写动作 |
+| Claude Code | 2026-09-07：2.1.263；v0.2.0 插件与市场通过官方 validator，隔离安装及真实用户配置下的公开市场安装成功；识别 write-action 技能与 MCP，mcp list 连接真实 Quicker 成功。模型调用因未登录退出，未验证 Claude 模型写动作 |
 | VS Code / Gemini CLI | v0.2.0 默认用户配置安装/更新/卸载和隔离传输通过；尚未完成实际客户端写动作验收 |
 
 ## 版本记录
 
 每个平台使用自己的插件 manifest 版本。发布记录应包含平台版本、Quicker 版本或构建、操作系统、插件版本与实测结果。尚未实测的最低版本写为未知，不猜测兼容范围。
 
-当前各安装包版本为 `0.2.0`，通过 GitHub 市场分发。旧个人市场原型使用的 `+codex.<时间戳>` 后缀只用于刷新开发缓存，不代表跨平台发布版本。
+当前 Claude Code 安装包版本为 `0.2.1`，补齐安装、认证、诊断与共存指引，MCP 运行配置和共享转接与 `0.2.0` 相同；其他安装包仍为 `0.2.0`。各平台分发方式见[客户端安装](客户端安装.md)。旧个人市场原型使用的 `+codex.<时间戳>` 后缀只用于刷新开发缓存，不代表跨平台发布版本。
 
 `0.1.1` 修复 `0.1.0` 安装成功但 MCP 无法启动的问题：当前 Codex legacy MCP 加载器不会展开参数中的 `${PLUGIN_ROOT}`，现改用 `cwd: "."` 与包内相对脚本路径。旧版用户按 README 的市场升级与重新安装步骤更新。隔离 HTTP fixture 用于传输回归，真实 Quicker 验收证据见下。
 
@@ -60,10 +60,24 @@ Quicker MCP 服务报告版本为 `2.3.0`，但本次使用包含默认技能包
 
 Cursor CLI 从安装器生成的 `%USERPROFILE%/.cursor/plugins/local/quicker` 加载插件，读取 write-action skill 与服务端 action-source。生成“Cursor MCP 验收 · 文本摘要”，4 步完成参数文本修剪、字符数、非空行数和消息框摘要；校验保存到暂存区，quicker_preview 返回对应设计器。实际过程先出现 CLI print 模式自动拒绝；在专用测试目录授权需要的 Quicker 工具后成功，Quicker 权限和批准方式未修改。第一次源文本转义不当由 Cursor 读回发现并修正，保存结果 saved=true。动作未运行，因此这里不声称运行时统计已验收。
 
-Quicker 使用 d921319283 的 Debug 构建，MCP 启用、允许写入、sandbox_confirm。新插件没有伪装已授权客户端；Client 参数分别发出 cursor-quicker-plugin / claude-quicker-plugin。所有原始日志只留本机，不提交个人配置或 token。
+Quicker 使用包含 MCP 与默认技能包发现修复的本地 Debug 构建，MCP 启用、允许写入、sandbox_confirm。新插件没有伪装已授权客户端；Client 参数分别发出 cursor-quicker-plugin / claude-quicker-plugin。所有原始日志只留本机，不提交个人配置或 token。
 
 Claude Code 初次 npm 包缺少可选原生二进制；安装对应 Windows x64 2.1.263 包后官方校验、安装和 MCP 健康检查成功。首次默认 30 秒连接超时，使用该客户端 MCP_TIMEOUT=180000 复验 Connected；该变量只用于验收进程，没有修改全局权限或客户端配置。首次连接应留意 Quicker 的同意窗口。
 
 第二轮 Cursor CLI 不传 --plugin-dir，仍自动发现安装器写入的本地插件。打开同一暂存动作，修改说明，保存 editVersion=4，读回说明一致并再次预览；actionId 与 slot 保持一致，没有新建或覆盖正式动作。更新后的安装包 `-Check` 返回 enabled/allowWrites/portReachable=true，无 token 内容。
 
 0.2.0 最终 Windows 测试：23 项通过（16 项传输回归 + 7 项包/安装验证），覆盖两种原生插件启动参数、客户端标识、中文/空格用户目录、重复安装/更新/卸载、已有配置保留、外来同名项与本地修改拒绝、JSONC 原文不改写。
+
+## Claude Code 公开安装复验
+
+2026-09-07，Claude Code 2.1.263 在真实用户配置下从公开 GitHub 市场安装 Quicker 0.2.0，插件详情识别 write-action 技能与 quicker MCP。`claude mcp list` 对 `plugin:quicker:quicker` 返回 `Connected`，启动参数使用 `-Client claude`。
+
+按已安装包的 `.mcp.json` 展开 `CLAUDE_PLUGIN_ROOT` 并启动原装转接后，真实 Quicker 初始化报告 `quicker 2.3.0`，发现 18 个工具；`skill_load(action-source)` 与 `steps.resolve('sys:notify')` 返回运行时知识及真实 schema，完整 content 与 attachedRules 保留。此项验证的是已安装包传输，不是 Claude 模型工具调用。
+
+继续通过该已安装包转接完成测试草稿的 `create → write_file → save → preview`。草稿包含循环、条件、变量和表达式；首次使用 YAML flow collections 被 `validate_failed` 拒绝，按返回错误改为 block style 后在同一草稿保存成功并打开预览。未复制草稿或变更权限，未执行动作。这证明安装包可以承载实际草稿编写链路，内容由验收调用提供，不是 Claude 模型生成。
+
+同一环境中，官方 `codex@openai-codex` 1.0.6 已安装，Codex setup 的就绪与认证检查通过。Claude Code 的 `auth status` 返回 `loggedIn: false`，实际 `--print` 请求退出码为 1，返回 `Not logged in`，未产生模型调用。上述安装、连接及转接草稿验收不表示 Claude 模型创建、保存或预览动作已经通过。
+
+0.2.1 在 Windows 上的 23 项测试通过，新增启动回归将 Cursor / Claude 的完整安装包复制到含中文和空格的缓存目录，再从无关工作目录按实际 manifest 参数启动。Claude Code 2.1.263 对根市场和 Claude 插件的严格清单校验通过。这些结果不替代 Claude 的真实模型验收。
+
+本次变更使用官方 `codex-plugin-cc` 1.0.6 调用 Codex 完成只读审查，未发现本次改动引入的明确缺陷；审查同时确认清单、共享副本一致性与 Python 语法检查通过。审查环境未重跑完整测试，23 项测试结果来自本仓库的独立 Windows 验证。

docs/客户端安装.md

@@ -53,9 +53,57 @@ VS Code / Gemini 同样替换 Client。卸载只删除归属匹配且未编辑
 
 Quicker 的同意与运行审批仍然独立生效。使用显式 slot；保存草稿、覆盖原动作、运行不是同一结果。诊断 `-Check` 只验证配置及 TCP，不表示已经写动作成功。
 
+## Claude Code 安装和诊断
+
+原生市场和插件安装命令：
+
+```powershell
+claude plugin marketplace add QuickerOrg/quicker-agent-integrations
+claude plugin install quicker@quicker-agent-integrations --scope user
+```
+
+在 Quicker 设置 → Agent 启用 MCP 与允许写入，首次连接确认 `claude-quicker-plugin`。在 Claude 会话执行 `/reload-plugins` 或新开会话，用 `/mcp` 查看工具，也可分别运行以下检查：
+
+| 检查 | 命令 | 判断方式 |
+| --- | --- | --- |
+| 插件加载 | `claude plugin list --json` | `quicker@quicker-agent-integrations` 已安装、已启用，版本符合预期 |
+| MCP 连接 | `claude mcp list` | `plugin:quicker:quicker` 显示 `Connected`；查看具体状态，不能只看命令退出码 |
+| 模型认证 | `claude auth status` | 当前 Claude Code 认证可用；未登录时进入 `claude` 执行 `/login`，或按组织配置认证 |
+| 动作编写 | 在会话请求写测试草稿，或 `/quicker:write-action` 加需求 | 加载实时知识，创建、保存、读回并打开预览；默认不运行 |
+
+`Connected` 只验证 MCP 连接。未登录时 `claude --print` 仍会返回 `Not logged in`；此时没有模型写动作证据，不应重装 Quicker 插件或放宽权限。Claude 的工具调用许可、Quicker 客户端同意及动作执行审批分别生效。
+
+首次连接超时先检查 Quicker 同意窗口。冷启动或等待同意需要更长时间时，可仅在当前 PowerShell 检查过程中增加启动等待，结束后恢复原值：
+
+```powershell
+$quickerPreviousMcpTimeout = $env:MCP_TIMEOUT
+try {
+    $env:MCP_TIMEOUT = '180000'
+    claude mcp list
+    # 如需以相同启动等待进入会话，在此运行 claude。
+} finally {
+    $env:MCP_TIMEOUT = $quickerPreviousMcpTimeout
+}
+```
+
+`MCP_TIMEOUT` 由 Claude 主进程读取，单位毫秒；仅放进插件 MCP 子进程的 `env` 不会延长 Claude 的启动等待。插件转接自己的请求超时和工具调用超时属于另一个阶段。发生写入超时后，先检查草稿状态再决定是否重试。[Claude MCP 超时说明](https://code.claude.com/docs/en/mcp#managing-your-servers)
+
+更新和卸载使用原生命令；更新后执行 `/reload-plugins` 或新开会话：
+
+```powershell
+claude plugin marketplace update quicker-agent-integrations
+claude plugin update quicker@quicker-agent-integrations --scope user
+# 需要卸载时：
+claude plugin uninstall quicker@quicker-agent-integrations --scope user
+```
+
+可同时安装官方 [codex-plugin-cc](https://github.com/openai/codex-plugin-cc)，其插件名为 `codex@openai-codex`，用途是委托本机 Codex 审查或处理代码；Quicker 插件直接提供 `quicker` MCP。按官方仓库安装后，用 `/codex:setup` 检查 Codex 安装及登录，用 `/codex:review` 发起代码审查。两个插件不互相依赖，也不共享模型认证；Codex 就绪不表示 Claude 已登录。本仓库安装器不会设置自动批准或启用额外审查钩子。
+
+真实验收请按[兼容性记录](兼容性.md)区分插件安装、MCP 健康和模型写动作。不要将 `Not logged in`、Claude 工具自动拒绝与 Quicker HTTP 403 混为一类错误。
+
 ## 官方依据
 
 - [Cursor 插件清单、MCP 和本地安装](https://cursor.com/docs/reference/plugins)，[本地插件目录](https://cursor.com/docs/plugins#test-plugins-locally)，[CLI MCP 权限](https://cursor.com/docs/cli/reference/permissions)。
-- [Claude Code 插件与 MCP](https://code.claude.com/docs/en/plugins-reference)。
+- [Claude Code 插件与 MCP](https://code.claude.com/docs/en/plugins-reference)、[市场 CLI](https://code.claude.com/docs/en/plugin-marketplaces#manage-marketplaces-from-the-cli)、[认证](https://code.claude.com/docs/en/authentication)。
 - [VS Code MCP 配置](https://code.visualstudio.com/docs/agent-customization/mcp-servers)。
 - [Gemini CLI MCP 配置](https://geminicli.com/docs/tools/mcp-server/)。

plugins/quicker-claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "quicker",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "通过本机 Quicker MCP 编写、保存和预览自动化动作。",
   "author": {
     "name": "QuickerOrg"

plugins/quicker-claude/README.md

@@ -1,9 +1,43 @@
-# Quicker claude 接入包
+# Quicker Claude Code 插件
 
-Windows PowerShell 5.1 + 支持 MCP 的本机 Quicker。此目录是完整运行单元，不依赖开发检出。
+版本：0.2.1。需要 Windows PowerShell 5.1、Claude Code，以及设置 → Agent 中带「启用 MCP」入口的本机 Quicker。此目录包含完整转接与技能，运行时不依赖开发检出、Git、Python 或 Node。
 
-安装、更新、卸载和实测兼容状态见 [公开仓库](https://github.com/QuickerOrg/quicker-agent-integrations#readme) 与 [客户端安装](https://github.com/QuickerOrg/quicker-agent-integrations/blob/main/docs/客户端安装.md)。
+## 安装和开始编写
 
-启用 Quicker 设置 → Agent 中的 MCP 与允许写入，然后重新加载客户端并完成 Quicker 客户端授权。插件读取实时动作知识，默认把结果保存到暂存区；安装本身不授予执行或覆盖权限。运行时不需要 Git、Python 或 Node。
+```powershell
+claude plugin marketplace add QuickerOrg/quicker-agent-integrations
+claude plugin install quicker@quicker-agent-integrations --scope user
+```
+
+启用 Quicker 设置 → Agent 中的 MCP 与允许写入，然后在 Claude Code 执行 `/reload-plugins` 或新开会话。首次连接时，在 Quicker 中确认 `claude-quicker-plugin` 客户端；安装本身不授予执行或覆盖权限。
+
+分别检查安装、连接和模型登录：
+
+```powershell
+claude plugin list --json
+claude mcp list
+claude auth status
+```
+
+插件应为 `quicker@quicker-agent-integrations` 且已启用，MCP 应显示 `plugin:quicker:quicker` 与 `Connected`。这两项成功仍不代表 Claude 已登录；若显示未登录，启动 `claude` 并执行 `/login`，或按组织配置完成[官方认证](https://code.claude.com/docs/en/authentication)。在 `/mcp` 中检查工具后，可直接请求：
+
+> 用 Quicker 写一个动作，显示“来自 Claude Code”，保存到暂存区并打开预览，不运行。
+
+也可以在 Claude 会话执行 `/quicker:write-action` 加上需求。结果默认保存为草稿；正式保留、覆盖原动作或运行由用户要求及 Quicker 审批决定。
+
+## 更新、卸载和诊断
+
+```powershell
+claude plugin marketplace update quicker-agent-integrations
+claude plugin update quicker@quicker-agent-integrations --scope user
+```
+
+更新后执行 `/reload-plugins` 或新开会话。卸载使用 `claude plugin uninstall quicker@quicker-agent-integrations --scope user`。
+
+首次连接超时时，先查看 Quicker 的客户端同意窗口；需要更长启动等待可按[客户端安装与诊断](https://github.com/QuickerOrg/quicker-agent-integrations/blob/main/docs/客户端安装.md#claude-code-安装和诊断)临时设置 `MCP_TIMEOUT`。HTTP 403 表示 Quicker 端同意未完成；Claude 未登录或拒绝工具调用则应在 Claude 端处理。不要修改 Quicker 配置文件来授予权限。
+
+本插件直接向 Claude 提供 Quicker MCP，不依赖 `codex@openai-codex`。可同时安装官方 [codex-plugin-cc](https://github.com/openai/codex-plugin-cc)，按其说明用 `/codex:setup` 检查 Codex；Codex 登录与 Claude 登录互相独立。Quicker 写动作使用 `quicker` 工具，委托 Codex 审查代码使用 `/codex:review`。
+
+各版本真实验收范围见[兼容性说明](https://github.com/QuickerOrg/quicker-agent-integrations/blob/main/docs/兼容性.md)。
 
 传输脚本与技能由 shared/ 生成；维护时运行 scripts/sync-packages.py，不手工修改副本。

tests/test_install_clients.py

@@ -2,6 +2,7 @@
 import json
 import os
 from pathlib import Path
+import shutil
 import subprocess
 import tempfile
 import unittest
@@ -103,7 +104,8 @@ def test_each_plugin_launches_from_unrelated_directory(self):
                 try:
                     settings = self.profile / 'fixture.json'
                     settings.write_bytes(encoded({'Enabled': True, 'Port': host.port, 'Token': 'test-only-token'}))
-                    package = ROOT / 'plugins' / ('quicker-' + client)
+                    package = self.profile / '插件 缓存' / ('quicker-' + client)
+                    shutil.copytree(ROOT / 'plugins' / ('quicker-' + client), package)
                     config = json.loads((package / ('mcp.json' if client == 'cursor' else '.mcp.json')).read_text(encoding='utf-8'))['mcpServers']['quicker']
                     args = [a.replace('${' + variable + '}', str(package)) for a in config['args']]
                     host.respond(reply(1, {'tools': [], 'extra': '中文保真'}))