@realqiyan/agent-task 0.1.0-rc.4 → 0.1.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +2 -1
  2. package/bin/agent-task.mjs +4 -1
  3. package/docs/deployment.md +4 -0
  4. package/docs/host-integrations.md +132 -0
  5. package/docs/release.md +16 -1
  6. package/docs/technical-design.md +2 -0
  7. package/docs/validation.md +17 -3
  8. package/package.json +3 -1
  9. package/scripts/install-lib.mjs +1 -1
  10. package/scripts/setup.mjs +34 -6
package/README.md CHANGED
@@ -9,6 +9,7 @@
9
9
  | 目的 | 入口 |
10
10
  | --- | --- |
11
11
  | 安装、配置、运行 | [部署说明](docs/deployment.md) |
12
+ | Pi、Claude Code、Codex 接入包与 using-agent-task 使用引导 | [宿主接入](docs/host-integrations.md) |
12
13
  | 本机控制台、配置保存与 Web/CLI 重启 | [控制台说明](docs/web-console.md) |
13
14
  | 命令行配置、凭据和任务管理 | [CLI 说明](docs/cli.md) |
14
15
  | 理解产品目标和架构选择 | [总体方案](docs/design-proposal.md) |
@@ -34,7 +35,7 @@ agent-task status
34
35
  agent-task restart
35
36
  ```
36
37
 
37
- setup 确认本机配置；MCP 连接自动启动或复用独立后台，宿主退出后后台继续运行。首次使用须安装至少一种原生执行 CLI 并准备其认证。完整接入配置、执行端准备与服务管理见[部署说明](docs/deployment.md)。
38
+ setup 确认本机配置；MCP 连接自动启动或复用独立后台，宿主退出后后台继续运行。首次使用须安装至少一种原生执行 CLI 并准备其认证。Pi、Claude Code 和 Codex 可先安装[接入包](docs/host-integrations.md)，再通过 `using-agent-task` 引导安装服务、完成 setup 和使用现有 MCP 工具。执行端准备与服务管理见[部署说明](docs/deployment.md)。
38
39
 
39
40
  任务由 `task_create` 提交固定 DAG，每个节点选择已就绪执行端。显式工作目录优先，否则 stdio 入口补入自己的启动目录；直接 HTTP 调用必须提供目录。具体契约见 [task-contract.ts](src/protocol/task-contract.ts)，管理工具见 [mcp.ts](src/protocol/mcp.ts)。Prompt、人工回复和工作空间选择都不授予工具权限。
40
41
 
package/bin/agent-task.mjs CHANGED
@@ -55,6 +55,9 @@ try {
55
55
  }
56
56
  }
57
57
  } catch (error) {
58
- console.error(process.argv.includes("--json") ? JSON.stringify({ error: error.message }) : error.message);
58
+ const message = process.argv[2] === "mcp"
59
+ ? error.message + "\nFor installation, setup or connection troubleshooting, use using-agent-task: Pi /skill:using-agent-task; Claude Code /agent-task:using-agent-task; Codex $using-agent-task. Do not reinstall or replay work without checking the cause."
60
+ : error.message;
61
+ console.error(process.argv.includes("--json") ? JSON.stringify({ error: message }) : message);
59
62
  process.exitCode = 1;
60
63
  }
package/docs/deployment.md CHANGED
@@ -27,6 +27,8 @@ agent-task setup --home /absolute/private/agent-task \
27
27
 
28
28
  ## MCP 接入与工作目录
29
29
 
30
+ Pi、Claude Code 和 Codex 可使用[可安装接入包](host-integrations.md)先安装使用引导，再经确认安装服务、完成 setup 和宿主配置。以下是其他宿主或手工配置的通用入口。
31
+
30
32
  在宿主的 MCP 配置中添加命令，例如采用 `mcpServers` 格式的宿主：
31
33
 
32
34
  ```json
@@ -86,6 +88,8 @@ Web 访问 `status` 返回地址同源的 `/admin/`，连接与令牌保护见[
86
88
 
87
89
  修改数据目录后，下次启动只准备目标配置和私有环境，并切换定位文件；不复制任务、会话、结果或日志，不删除旧目录。目标已有不同启动文件时拒绝覆盖，须停服核对并显式准备目标。新目录没有旧任务，目录切换不是恢复或重放许可。
88
90
 
91
+ `agent-task setup --check --json`（自定义安装附加相同 `--home`）只读检查初始化状态，不启动后台、不写锁或修复文件。它不验证模型登录、执行端授权或实时 MCP 健康；摘要契约见 [setup](../scripts/setup.mjs)。
92
+
89
93
  重复 setup 保留已有配置。初始化中断后须显式执行 `setup --resume`，它只接续已保存且一致的初始化文件；缺少凭据或所有权不明时停止核查，不猜测修复。更新前停止后台并备份安装目录和数据目录。调研阶段不保证旧配置或数据兼容，普通启动不迁移历史。
90
94
 
91
95
  源码开发者执行 `npm ci --ignore-scripts && npm run build` 后，可用 `node bin/agent-task.mjs setup`、`node bin/agent-task.mjs mcp` 或 `npm start -- --home ...`。内部 `dist/application/main.js` 不是独立的重启入口。
package/docs/host-integrations.md ADDED
@@ -0,0 +1,132 @@
1
+ # Pi、Claude Code 与 Codex 接入包
2
+
3
+ **先安装接入包，再由 `using-agent-task` 引导安装、初始化和使用服务。** 插件名仍为 `agent-task`。skill 只指导使用现有 CLI/MCP，不增加任务 API、执行器或业务规则。
4
+
5
+ 入口：[共享包](../plugin/)、[使用引导](../plugin/skills/using-agent-task/SKILL.md)、[Claude marketplace](../.claude-plugin/marketplace.json)、[Codex marketplace](../.agents/plugins/marketplace.json)。
6
+
7
+ Agent Task 支持 Linux/macOS、Node.js 22.19+ 与 npm。Pi 需要 1.4.0+ 的原生 MCP；Claude Code 需要插件支持；Codex CLI 需要 `plugin marketplace add` 和 `plugin add`。不承诺 Codex IDE、云端或其他同名插件系统可用。核验版本与限制见[验证说明](validation.md#宿主接入包)。
8
+
9
+ ## 一个仓库、两个 npm 包
10
+
11
+ 服务与插件在同一仓库开发，分别打包。服务包 `@realqiyan/agent-task` 提供 CLI 和运行依赖；插件包 `@realqiyan/agent-task-plugin` 仅包含宿主接入资产，不依赖服务或 SDK，没有 npm 安装 hook。**不要用 `pi install npm:@realqiyan/agent-task` 安装插件。** 服务发行包不再携带插件副本。
12
+
13
+ 源码 marketplace 固定选择已审查的插件包版本，不跟随 npm latest。以下 npm 入口须在新包和对应 marketplace 发布后使用；当前改名不等于已发布，状态与限制见[验证说明](validation.md#宿主接入包)。不存在第二个分发仓库。
14
+
15
+ ### Pi
16
+
17
+ ```bash
18
+ pi install npm:@realqiyan/agent-task-plugin
19
+ ```
20
+
21
+ 需要项目作用域时附加 `--local`。启动 Pi（已有会话先 `/reload`），调用 `/skill:using-agent-task`。插件安装 skill 和只读检查扩展；首次引导在 setup 完成并取得确认后用原生 `pi mcp add` 注册连接。MCP 注册的作用域须单独选择，不替换已有同名连接。
22
+
23
+ ### Claude Code
24
+
25
+ 通过清单 URL 获取索引，不克隆服务仓库：
26
+
27
+ ```bash
28
+ claude plugin marketplace add https://raw.githubusercontent.com/realqiyan/agent-task/master/.claude-plugin/marketplace.json
29
+ claude plugin install agent-task@agent-task --scope user
30
+ ```
31
+
32
+ marketplace 的 npm 来源让宿主下载插件包。需要项目级声明时选择 `--scope project`。新会话调用 `/agent-task:using-agent-task`。插件已声明 MCP，不要重复 `claude mcp add`。
33
+
34
+ ### Codex CLI
35
+
36
+ 稀疏检出同仓的索引，然后从 npm 安装插件：
37
+
38
+ ```bash
39
+ codex plugin marketplace add realqiyan/agent-task --sparse .agents/plugins
40
+ codex plugin add agent-task@agent-task
41
+ ```
42
+
43
+ 稀疏检出避免展开整个服务源码树，但不承诺完全不下载 Git 元数据或根目录文件。也可使用本地 marketplace 索引目录，无需 Git 克隆。新会话调用 `$using-agent-task`，或在 `/skills` 选择它。原生 onboarding 指向同一 skill；检查提醒需要先在 `/hooks` 中审查信任。
44
+
45
+ ### 服务与项目边界
46
+
47
+ Claude/Codex 都由宿主通过 npm 获取插件，不是运行 `npm install -g` 后就自动注册。服务未安装或 setup 未完成时 MCP 失败是预期行为，skill 仍可使用；初始化后重开会话或在宿主 MCP 界面重连。`codex mcp list` 的静态配置不是连接成功证据。
48
+
49
+ 插件通过 PATH 调用独立服务 `agent-task mcp`，不运行插件缓存里的服务源码。多个 workspace 的本地插件可共用服务；`--local` 或项目级安装只控制宿主配置，不隔离服务数据。需要独立后台时显式配置不同 `--home`。删除项目插件不删除服务或任务历史。
50
+
51
+ 安装接入资产不需要服务凭据；让模型执行 skill 需要宿主自身的模型认证。引导仍须先取得确认，才能安装服务或改配置。
52
+
53
+ ## 未发布资产的本地验收
54
+
55
+ 不需要服务的 npm ci、build、link 或 setup。仓库根目录执行：
56
+
57
+ ```bash
58
+ AGENT_TASK_SOURCE="$(pwd -P)"
59
+ pi install "$AGENT_TASK_SOURCE/plugin"
60
+
61
+ # Claude/Codex：生成只含插件及本地索引的独立临时快照
62
+ MARKETPLACE="$(node scripts/create-plugin-marketplace.mjs)"
63
+ claude plugin marketplace add "$MARKETPLACE"
64
+ claude plugin install agent-task@agent-task-dev --scope user
65
+ codex plugin marketplace add "$MARKETPLACE"
66
+ codex plugin add agent-task@agent-task-dev
67
+ ```
68
+
69
+ 只执行需要的宿主命令。生成器不安装依赖、不改宿主配置；本地 marketplace 名为 `agent-task-dev`，与正式源区分。保留快照目录直到移除注册，修改源码后重新生成并更新注册；不要同时启用正式插件与开发插件，以免重复 MCP 连接。根目录的正式 marketplace 指向 npm，直接注册仓库不会加载尚未发布的 `plugin/` 改动。
70
+
71
+ ## 启动提醒与检查边界
72
+
73
+ 接入包的检查独立于 MCP 连接：Pi 在会话启动时显示通知并加入简短模型上下文；Claude Code/Codex 的同步 `SessionStart` hook 返回用户可见的 `systemMessage` 和模型上下文。异常提示给出对应的 `using-agent-task` 入口，状态正常时保持安静；不会自动调用模型或执行安装。
74
+
75
+ 检查复用服务的 `agent-task setup --check --json`，不解析私有配置。该服务命令只在自己的进程内校验初始化和凭据文件，返回不含路径、密钥或原始异常的摘要；不创建目录/SQLite 锁、不修复文件、不启动服务、联网或发现执行端。检查有时间与输出限制，失败不会阻塞整个宿主会话。未安装、初始化未完成、配置异常、协调模型未配置和检查本身失败分别提示；无法启动命令也可能是 PATH 或 Node 问题，不等于应当重装。
76
+
77
+ 这是安装状态检查，**不是实时 MCP 健康检查**。后台停止不等于未初始化；端口冲突、执行端准备和连接错误仍需查看宿主 MCP 状态。服务 MCP 启动失败的 stderr 也附带 skill 入口，但 stderr 不保证直接展示给用户。对不支持此只读命令的服务版本只报告检查失败，不回退到可能写锁的旧检查路径。
78
+
79
+ 检查默认使用宿主 PATH 的 `agent-task` 和默认 home。自定义 MCP 命令/home 时，在启动宿主的环境中同步设置以下非敏感变量：
80
+
81
+ ```bash
82
+ export AGENT_TASK_PREFLIGHT_COMMAND=/absolute/bin/agent-task
83
+ export AGENT_TASK_PREFLIGHT_HOME=/absolute/private/agent-task
84
+ ```
85
+
86
+ 这些变量**只选择检查目标，不修改 MCP 连接**，也不推断或改写宿主配置。已关闭插件 MCP、改用远程连接或不需要此提示时，可在宿主原生设置中禁用该 hook/扩展，保留 skill。
87
+
88
+ Codex 插件 hook 必须先在 `/hooks` 中审查并信任；安装插件不自动授权 hook。Claude Code/Pi 也须允许插件 hook/扩展运行。禁用、未信任或 Node 无法启动时，不能保证出现自定义提示，仍可显式调用上述 skill。不要通过绕过信任或扩大权限来消除提示。程序入口见 [preflight](../plugin/scripts/preflight.mjs)、[Pi 扩展](../plugin/pi-extension.js)、[hook 入口](../plugin/scripts/session-start.mjs)。
89
+
90
+ ## 引导如何安装服务
91
+
92
+ 调用 skill 后先检查已有命令、Node/npm、安装目录和连接配置。服务确实缺失时，宿主说明安装影响，取得用户确认，然后通过自身 shell 工具执行：
93
+
94
+ ```bash
95
+ npm install -g @realqiyan/agent-task
96
+ ```
97
+
98
+ 这不是安装插件时静默执行，也不是每次连接运行 `npx`。已有安装不自动升级，PATH 问题不重复安装；权限不足时停止并给出用户终端操作，不使用 sudo 或扩大宿主权限。
99
+
100
+ 随后引导用户在自己的终端执行 `agent-task setup`，让凭据通过隐藏输入收集。用户明确选择非交互初始化时，可由宿主执行已确认的参数和私有凭据文件方式，但不将秘密放入会话或命令参数。setup 和执行端准备的服务规则由[部署说明](deployment.md)维护。
101
+
102
+ ## 使用与验收
103
+
104
+ 引导按需读取包内参考文件，复制到插件缓存或独立安装后不依赖仓库文档：
105
+
106
+ - [安装与连接](../plugin/skills/using-agent-task/references/installation.md)：setup、原生 MCP 注册、自定义 home/绝对命令路径和连接验证。
107
+ - [日常使用](../plugin/skills/using-agent-task/references/tasks.md)：通过现有 MCP 提交固定 DAG、查看运行与交付、回答事实问题、区分未来触发控制和当前运行取消。
108
+ - [排障](../plugin/skills/using-agent-task/references/troubleshooting.md)：区分安装、连接、配置、适配器准备和执行结果不明，不盲目重试。
109
+
110
+ 安装验收只需宿主显示已连接，并成功调用 `executor_list({})`、`task_list({})`。Pi 默认通过原生 codemode/tool search 发现工具；使用实际宿主命名空间。不为验收创建任务或执行付费模型/领域工作。连接成功、执行端 ready、原生授权和真实交付是不同证据。
111
+
112
+ 创建任务建议明确给出目标项目的绝对 `workspace`，不把插件缓存目录当成工作目录。MCP token 不写入插件配置，事实回复不授予权限。自定义 home 时，setup、MCP 和后续 CLI 命令必须使用同一目录；Claude/Codex 先禁用插件自带 MCP 项再添加手工连接，不能同时保留两条有效连接。
113
+
114
+ ## 更新与移除
115
+
116
+ 接入包与服务使用同一项目版本，但分别安装。正式 marketplace 固定插件版本，更新时须刷新索引再使用宿主的插件更新入口；开发快照不会自动同步源码。接入包更新不升级服务、不执行 setup、不迁移数据；更新服务前按[部署说明](deployment.md#数据目录与管理)停服并备份。使用宿主原生 package/marketplace 更新入口刷新接入资产，再重开会话。
117
+
118
+ - Pi 本地安装：`pi remove "$AGENT_TASK_SOURCE/plugin"`；npm 安装：`pi remove npm:@realqiyan/agent-task-plugin`。另用 `pi mcp remove agent-task` 移除引导注册的 MCP 连接。
119
+ - Claude Code：`claude plugin uninstall agent-task@agent-task`。
120
+ - Codex：`codex plugin remove agent-task@agent-task`。
121
+ - 本地开发插件使用同一移除命令，但标识为 `agent-task@agent-task-dev`；不再使用时另行移除 `agent-task-dev` marketplace 注册。
122
+ - 另行添加的手工 MCP 连接需单独移除。
123
+
124
+ 原先注册旧 npm 插件包的用户须审查后显式移除旧包声明、再安装新包；不要同时加载两份。若误把服务包通过 `pi install` 注册为插件，只移除该 Pi 声明，不自动卸载独立服务或删除数据。
125
+
126
+ 宿主退出或卸载插件不停止已提交任务。`agent-task status` 查看共享后台，`agent-task stop` 显式停止；先核对活动工作，自定义安装附加相同 `--home`。卸载接入包不删除服务、历史、工作空间或原生执行端配置。
127
+
128
+ ## 原生机制依据
129
+
130
+ - Pi：[packages](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/packages.md)、[MCP](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/mcp.md)。
131
+ - Claude Code：[marketplace](https://code.claude.com/docs/en/plugin-marketplaces)、[插件清单](https://code.claude.com/docs/en/plugins-reference)。
132
+ - Codex：[插件包与 marketplace](https://developers.openai.com/plugins/build/plugins)。使用已核验 CLI 支持的 `.codex-plugin/plugin.json`，不依赖 Claude 清单回退。
package/docs/release.md CHANGED
@@ -24,6 +24,21 @@ npm run test:install -- "./realqiyan-agent-task-$VERSION.tgz"
24
24
 
25
25
  npm 接收发布后可能仍在处理包。[发布后验收](../scripts/verify-install.mjs)有限等待公开 `latest` 指向目标版本，再执行默认全局安装；等待只读取 registry。超时先核对版本状态，不重复上传。
26
26
 
27
+ ## 独立接入包
28
+
29
+ [轻量包](../plugin/package.json)为 `@realqiyan/agent-task-plugin`，使用同一项目版本，不依赖服务或 SDK，不运行安装脚本。它允许先安装 `using-agent-task`，再经用户确认安装服务；不是服务的替代安装。Claude Code/Codex 的正式 marketplace 也从该 npm 包获取插件；服务发行包不携带插件副本。未发布资产使用[本地快照](host-integrations.md#未发布资产的本地验收)。
30
+
31
+ ```bash
32
+ npm run pack:plugin
33
+ # 产物：realqiyan-agent-task-plugin-<项目版本>.tgz
34
+ ```
35
+
36
+ [独立包门禁](../scripts/pack-plugin.mjs)检查版本、无执行/依赖字段和实际包清单；不需要构建服务。[接入测试](../tests/host-integrations.test.mjs)使用临时目录和空 npm 缓存离线安装真实 tarball。发布前还须通过本文的项目检查，并用对应宿主验收引导发现与连接，不能将 skill 文本当成模型已执行的证据。
37
+
38
+ CI 分别生成服务与插件候选产物；当前 GitHub 发布工作流只上传服务包，**不会自动发布独立接入包**。接入包需单独授权发布，先核对同名目标版本未占用及 npm 账号/权限，再发布已检查的 `realqiyan-agent-task-plugin-<版本>.tgz`，明确使用 `--ignore-scripts --access public --tag latest --registry=https://registry.npmjs.org`。不要为新包擅自复用服务包的 Trusted Publisher 授权或绕过登录/2FA。发布后核查该包的 registry 版本和 latest，并在隔离宿主配置中验证 `pi install npm:@realqiyan/agent-task-plugin`；实际已发布版本与验收边界见[验证说明](validation.md#宿主接入包)。
39
+
40
+ 插件首次改名不沿用旧包发布权限。发布时先完成全部门禁，在明确授权后发布新插件包并验证公开 registry 与宿主安装，再推送引用它的 marketplace；不要让正式索引指向尚不可下载的版本。服务 tag 的发布流程保持独立。旧包不自动撤销、弃用或重发，宿主配置也不自动迁移。
41
+
27
42
  ## GitHub Actions 门禁与受控发布
28
43
 
29
44
  - [Validate](../.github/workflows/ci.yml)：PR/master 或手动触发时在 Ubuntu 执行 TypeScript 与依赖边界检查、基础测试及构建；检查包清单。安装任务**不 checkout 项目源码**，只接收 tarball 和验收脚本，在当前 Linux runner 验证启动、重启及认证检查。常规 CI 使用 Linux runner，不能据此推断 macOS 验证结果。
@@ -32,7 +47,7 @@ npm 接收发布后可能仍在处理包。[发布后验收](../scripts/verify-i
32
47
 
33
48
  ### 通过 tag 发布
34
49
 
35
- 1. 核对 npm 中目标版本尚未发布。用 `npm version <新版本> --no-git-tag-version --ignore-scripts` 同步包版本和锁文件；完成上述候选验收后，提交并推送到 master。
50
+ 1. 核对 npm 中目标版本尚未发布。用 `npm version <新版本> --no-git-tag-version --ignore-scripts` 同步包版本和锁文件，并将 `plugin/package.json`、`plugin/.claude-plugin/plugin.json`、`plugin/.codex-plugin/plugin.json` 的版本，以及两个 marketplace 的 npm 来源版本设为同一值；`pack:plugin` 拒绝不一致。完成上述候选验收后，提交并推送到 master。
36
51
  2. 给已验收的提交打版本 tag，并单独推送该 tag：
37
52
 
38
53
  ```bash
package/docs/technical-design.md CHANGED
@@ -24,6 +24,8 @@
24
24
  | 装配、启动、关闭与重启 | [main](../src/application/main.ts)、[MCP 后台启动](../src/application/mcp-entry.ts)、[业务运行实例](../src/application/task-runtime.ts)、[launcher](../src/application/launcher.ts)、[启动准备](../src/application/startup.ts) | [stdio.test.mjs](../tests/stdio.test.mjs)、[restart.test.mjs](../tests/restart.test.mjs)、[service.test.mjs](../tests/service.test.mjs) |
25
25
  | 安装与发布 | [命令入口](../bin/agent-task.mjs)、[setup](../scripts/setup.mjs)、[安装库](../scripts/install-lib.mjs)、[包门禁](../scripts/pack-release.mjs)、[发布准入](../scripts/check-release.mjs)、[工作流](../.github/workflows/) | [install.test.mjs](../tests/install.test.mjs)、[setup.test.mjs](../tests/setup.test.mjs)、[release.test.mjs](../tests/release.test.mjs)、[发布说明](release.md) |
26
26
 
27
+ 宿主安装资产位于 [plugin](../plugin/)，包含原生插件清单、MCP 连接声明、`using-agent-task` 使用引导和只读启动检查，不进入服务运行时依赖图。检查通过 CLI 摘要复用 setup 校验；[检查测试](../tests/host-preflight.test.mjs)验证无写入、故障分类和凭据不回显。[独立包门禁](../scripts/pack-plugin.mjs)不构建或安装服务；[接入测试](../tests/host-integrations.test.mjs)验证无服务依赖的离线安装、清单契约和真实 stdio 工具调用；宿主原生流程见[接入说明](host-integrations.md)。
28
+
27
29
  ## 依赖与一致性边界
28
30
 
29
31
  依赖方向由[架构原则](architecture-guidelines.md#职责与依赖)定义，[依赖检查器](../scripts/check-boundaries.mjs)随 `npm run check` 执行。模块分类、允许引用及 Run 写入口检查以该脚本为准；新增文件须明确归属。
package/docs/validation.md CHANGED
@@ -14,6 +14,20 @@ git diff --check
14
14
 
15
15
  [MCP 服务测试](../tests/service.test.mjs)通过真实 HTTP 和 SDK 校验器检查输入/输出契约、成功与失败响应及列表查询。契约不使用数组形式的 `type`，可空字段仍必填并接受 `null`；实现见 [mcp-contract.ts](../src/protocol/mcp-contract.ts)。这不替代曾报告契约警告的客户端复验，其名称和版本尚未提供。
16
16
 
17
+ ## 宿主接入包
18
+
19
+ `0.1.0-rc.4` 基线上的接入资产，Linux x64、Node 24.15.0，在无个人凭据的隔离 HOME/宿主配置中验证：未安装服务时，Pi 1.4.0、Claude Code 2.1.302、Codex CLI 0.164.0 均可安装本地接入包并发现 `using-agent-task`。随后用本地构建服务完成 setup，Pi 工具发现、Claude MCP 健康连接、Codex app-server 连接及 `executor_list`、`task_list` 调用通过。证据：`/tmp/agent-task-native-hosts-TvywpQ/report.json`、同目录 `codex-runtime.json`。这是本地资产验证，不表示已发布到 npm 或远端 marketplace。
20
+
21
+ 同一环境中，Pi RPC 发出缺少命令的通知并保留模型上下文，未触发模型运行（`pi-preflight.jsonl`）；Claude headless 原生 SessionStart 执行并返回用户提示和上下文（`claude-hook.jsonl`，MCP 被显式关闭以验证独立性）。Codex 发现同步 hook 且无清单错误，但标记为未信任；未绕过审查执行。
22
+
23
+ [接入测试](../tests/host-integrations.test.mjs)从真实 tarball、空 npm 缓存离线安装独立接入包，并通过真实 setup、stdio 与官方 MCP SDK 调用上述只读工具。[启动检查测试](../tests/host-preflight.test.mjs)检查配置缺失/损坏、失败进程、输出限制与取消、无目录/锁写入及私密值不回显；hook 故障输出不阻塞会话，正常状态不输出通知。[插件包门禁](../scripts/pack-plugin.mjs)检查实际包包含 hook、扩展、清单和 skill，并验证两个 npm marketplace 的版本；[服务包门禁](../scripts/pack-release.mjs)拒绝混入插件资产。原生宿主不是基础测试依赖。
24
+
25
+ 旧名 `@realqiyan/agent-task-hosts@0.1.0-rc.5` 曾完成 npm 发布及 Pi 默认安装、skill 发现和启动通知验证；本机发布，无 GitHub provenance。证据：`/tmp/agent-task-rc5-pi-registry-VbshgS/report.json`。维护者已主动删除旧包；该历史验收不代表当前可安装性，不恢复旧名发布。
26
+
27
+ 新名 `@realqiyan/agent-task-plugin` 尚未发布。Linux、Claude Code 2.1.302/Codex CLI 0.164.0 的隔离配置中，两者都识别 npm 来源并尝试 registry 下载；使用旧包的探针因 404 停止，未证明 npm 插件安装成功。生成的本地插件快照在两种宿主安装成功；不涉及模型或用户 hook 信任。证据：`/tmp/agent-task-npm-source-nNH1U9/report.json`、同目录 `local-report.json`。发布新包后仍须核验清单 URL/稀疏索引入口、npm 下载、skill/hook/MCP 加载；这些未验证条件不因本地安装通过而消失。
28
+
29
+ 未执行三种宿主的模型驱动安装/setup/日常使用会话、Pi/Claude 模型侧工具调用、真实 TUI 告警展示、Codex 用户信任后的 hook 调用、macOS 接入或自定义 home 的宿主 UI 禁用流程。探针不运行模型或 ACP 领域工作；可发现的真实失败程序只提供连接前置条件，不证明执行端能完成任务。操作入口见[宿主接入](host-integrations.md)。
30
+
17
31
  ## 控制台验证
18
32
 
19
33
  [Web/CLI](../tests/web.test.mjs)、[配置](../tests/settings.test.mjs)和[重启](../tests/restart.test.mjs)测试覆盖真实本机服务的管理互通、旧编辑拒绝、凭据隔离、浏览器请求边界、配置生效与目录切换，以及重启后不确定派发仍被阻断。配置文件测试不构成断电、磁盘满或目录同步失败窗口的完整证据。
@@ -64,11 +78,11 @@ Linux x64、Node 24.15.0 的隔离环境证据：
64
78
 
65
79
  | 范围 | 结论 | 证据 |
66
80
  | --- | --- | --- |
67
- | `0.1.0-rc.2`，提交 `7ffed5c` | Node 22.19.0/24.x 基础检查、包门禁、Linux 独立安装、GitHub OIDC 发布及 npmjs 默认安装验收通过；公开包有 provenance | [发布运行](https://github.com/realqiyan/agent-task/actions/runs/40067373860)、[npm 版本](https://www.npmjs.com/package/@realqiyan/agent-task/v/0.1.0-rc.2) |
68
- | 同版本，Linux x64、Node 24.15.0 | 从 npmjs 默认安装到独立 prefix，通过前台、Web/CLI 重启、stdio 后台、断开后健康及 stop 检查；捕获输出未发现验证凭据 | `/tmp/agent-task-npm-qiT8oy/report.json` |
81
+ | `0.1.0-rc.5`，提交 `0ef200f` | Node 22.19.0/24.x 基础检查、包门禁、Linux 独立安装、GitHub OIDC 发布及 npmjs 默认安装验收通过；公开包有 provenance，latest 指向该版本 | [发布运行](https://github.com/realqiyan/agent-task/actions/runs/40104773771)、[npm 版本](https://www.npmjs.com/package/@realqiyan/agent-task/v/0.1.0-rc.5) |
82
+ | 同版本，Linux x64、Node 24.15.0 | 从 npmjs 默认安装到独立 prefix，通过前台、Web/CLI 重启、stdio 后台、断开后健康及 stop 检查；捕获输出未发现验证凭据 | `/tmp/agent-task-npm-PmUzGG/report.json` |
69
83
  | `0.0.1-rc.2`，提交 `48549ea`，历史平台证据 | Ubuntu x64 与 macOS ARM64 hosted runner 在 Node 22.19.0 下使用 CI tarball、无源码完成安装、前台、重启及认证检查 | [Validate 运行](https://github.com/realqiyan/agent-task/actions/runs/39829900075) |
70
84
 
71
- `0.1.0-rc.2` 的发布验收未执行 macOS、浏览器或真实模型/ACP 任务；旧 macOS 证据不覆盖当前版本、Intel Mac、休眠或用户注销。安装检查使用真实失败程序提供可发现路径，不证明成功 ACP 执行。PTY 能力不可用时测试明确跳过，跳过不是通过。
85
+ `0.1.0-rc.5` 的发布验收未执行 macOS、浏览器或真实模型/ACP 任务；旧 macOS 证据不覆盖当前版本、Intel Mac、休眠或用户注销。安装检查使用真实失败程序提供可发现路径，不证明成功 ACP 执行。PTY 能力不可用时测试明确跳过，跳过不是通过。
72
86
 
73
87
  上述发布状态是验收时的事实，不是实时 registry 查询；包内文档是发布提交的快照。
74
88
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@realqiyan/agent-task",
3
- "version": "0.1.0-rc.4",
3
+ "version": "0.1.0-rc.6",
4
4
  "license": "MIT",
5
5
  "author": "realqiyan",
6
6
  "repository": {
@@ -53,6 +53,8 @@
53
53
  "setup": "node bin/agent-task.mjs setup",
54
54
  "prepack": "npm run build",
55
55
  "pack:release": "node scripts/pack-release.mjs",
56
+ "plugin:local": "node scripts/create-plugin-marketplace.mjs",
57
+ "pack:plugin": "node scripts/pack-plugin.mjs",
56
58
  "test:install": "node scripts/verify-install.mjs"
57
59
  },
58
60
  "dependencies": {
package/scripts/install-lib.mjs CHANGED
@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
7
7
  export const packageRoot = realpathSync(fileURLToPath(new URL("..", import.meta.url)));
8
8
 
9
9
  export function argumentsFor(argv) {
10
- const flags = new Set(["check", "resume", "help", "yes", "generate-tokens"]), options = {};
10
+ const flags = new Set(["check", "json", "resume", "help", "yes", "generate-tokens"]), options = {};
11
11
  for (let i = 0; i < argv.length; i++) {
12
12
  const key = argv[i].replace(/^--/, "");
13
13
  if (!argv[i].startsWith("--") || key in options) throw new Error("Invalid or repeated option");
package/scripts/setup.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { existsSync, mkdirSync, realpathSync, lstatSync } from "node:fs";
2
+ import { existsSync, mkdirSync, realpathSync, lstatSync, writeSync } from "node:fs";
3
3
  import { join, isAbsolute } from "node:path";
4
4
  import { homedir } from "node:os";
5
5
  import { randomBytes } from "node:crypto";
@@ -16,20 +16,48 @@ let unlock;
16
16
  try {
17
17
  const options = argumentsFor(process.argv.slice(2));
18
18
  if (options.help) {
19
- console.log("Usage: agent-task setup [--home ABSOLUTE_PRIVATE_DIR]\nNew installation: confirm directories, port, tokens and coordinator in the terminal.\nNoninteractive: --home DIR --data-dir DIR --port NUMBER --generate-tokens|--credentials-file PRIVATE_JSON --yes [--provider openai|anthropic|deepseek|openai-compatible --model ID]\nCompatible provider: --base-url URL --api openai-completions|openai-responses --api-key-env NAME --context-window NUMBER --max-tokens NUMBER\nExisting installation: --check | --resume. Secrets are read from a private JSON file or hidden terminal input, never command arguments. No executor installation during setup.");
19
+ console.log("Usage: agent-task setup [--home ABSOLUTE_PRIVATE_DIR]\nNew installation: confirm directories, port, tokens and coordinator in the terminal.\nNoninteractive: --home DIR --data-dir DIR --port NUMBER --generate-tokens|--credentials-file PRIVATE_JSON --yes [--provider openai|anthropic|deepseek|openai-compatible --model ID]\nCompatible provider: --base-url URL --api openai-completions|openai-responses --api-key-env NAME --context-window NUMBER --max-tokens NUMBER\nExisting installation: --check [--json] (read-only) | --resume. Secrets are read from a private JSON file or hidden terminal input, never command arguments. No executor installation during setup.");
20
20
  process.exit(0);
21
21
  }
22
+ if (options.json && !options.check) throw new Error("--json is only supported with setup --check");
22
23
  let root = installRoot(options);
23
- if (!existsSync(join(root, "installation.json")) && !options.check && !options.resume && !options.yes) {
24
+ if (options.check) {
25
+ if (Object.keys(options).some(key => !["home", "check", "json"].includes(key))) throw new Error("Use setup --check with only optional --json and --home");
26
+ // This branch never creates a directory, opens SQLite, starts a service or repairs files.
27
+ let report;
28
+ try {
29
+ let present = true;
30
+ try { lstatSync(join(root, "installation.json")); }
31
+ catch (error) { if (error.code === "ENOENT") present = false; else throw error; }
32
+ if (!present) {
33
+ report = { configuration: existsSync(join(root, "launch.json")) ? "invalid" : "missing" };
34
+ } else {
35
+ const manifest = readManifest(root);
36
+ if (manifest.phase === "initializing") report = { configuration: "incomplete" };
37
+ else {
38
+ if (manifest.phase !== "ready" || !existsSync(join(packageRoot, "dist/application/main.js"))) throw new Error("Invalid installation");
39
+ const paths = startupPaths(root), config = loadConfig(paths.configPath), environment = readEnvironment(paths.environmentPath);
40
+ validateServiceEnvironment(config, environment);
41
+ report = { configuration: "valid", coordinatorConfigured: Boolean(config.coordinator && environment[coordinatorCredentialEnv(config.coordinator)]) };
42
+ }
43
+ }
44
+ } catch {
45
+ // Do not serialize exceptions: schema/parser errors can include private values.
46
+ report = { configuration: "invalid" };
47
+ }
48
+ writeSync(1, JSON.stringify(report) + "\n");
49
+ process.exit(report.configuration === "valid" ? 0 : 1);
50
+ }
51
+ if (!existsSync(join(root, "installation.json")) && !options.resume && !options.yes) {
24
52
  await setupWizard(options, root); root = installRoot(options);
25
53
  }
26
54
  let manifest, initialEnvironment;
27
55
  if (existsSync(join(root, "installation.json"))) {
28
56
  manifest = readManifest(root);
29
- if (Object.keys(options).some(key => !["home", "check", "resume"].includes(key))) throw new Error("Installation exists; use configuration commands instead of initialization flags");
57
+ if (Object.keys(options).some(key => !["home", "resume"].includes(key))) throw new Error("Installation exists; use configuration commands instead of initialization flags");
30
58
  if (manifest.phase !== "ready" && !options.resume) throw new Error("Incomplete initialization; inspect private files and use --resume explicitly");
31
59
  } else {
32
- if (options.check || options.resume) throw new Error("No installation to check/resume");
60
+ if (options.resume) throw new Error("No installation to resume");
33
61
  if (!options.yes || !options.home || !options["data-dir"] || options.port === undefined ||
34
62
  (!options["generate-tokens"] && !options["credentials-file"])) throw new Error("Confirm initialization with --home, --data-dir, --port, --generate-tokens/--credentials-file and --yes");
35
63
  const dataDir = installRoot({ home: options["data-dir"] });
@@ -84,7 +112,7 @@ try {
84
112
  validateServiceEnvironment(config, readEnvironment(paths.environmentPath));
85
113
  console.log(JSON.stringify({ configuration: "valid", coordinator: config.coordinator ? "configured; authentication not verified" : "not configured",
86
114
  configPath: paths.configPath, credentialsPath: paths.environmentPath, executorDiscovery: "on MCP connection" }, null, 2));
87
- if (!options.check) console.log("Add agent-task with args [mcp] to your MCP client (include --home for a custom installation). Token values are not printed. Use agent-task start for foreground management.");
115
+ console.log("Add agent-task with args [mcp] to your MCP client (include --home for a custom installation). Token values are not printed. Use agent-task start for foreground management.");
88
116
  } catch (error) {
89
117
  console.error(error.name === "ZodError" ? "Invalid initialization configuration; check provider, model, directories and port" : error.message);
90
118
  process.exitCode = 1;