@realqiyan/agent-task 0.0.0-stage → 0.0.1-rc.1

package/docs/deployment.md

@@ -0,0 +1,113 @@
+# 安装与运行
+
+支持 Linux 和 macOS，要求 Node.js **22.19+** 与 npm。安装包包含编译后的服务、worker、Web 资源和操作脚本，不需要源码、TypeScript 或用户自行构建。当前发布状态和平台证据见[验证说明](validation.md#npm-发布候选验证)，发布步骤见[发布说明](release.md)。
+
+## 安装与交互配置
+
+```bash
+npm install -g @realqiyan/agent-task
+agent-task --version
+agent-task setup
+agent-task start
+```
+
+使用当前用户可写的 npm prefix，不以 root 运行任务服务。若使用 nvm 等版本管理器，先选定后台服务长期使用的 Node 安装；服务记录绝对路径，移除该 Node 或全局包会使它无法启动。
+
+向导收集工作空间、可选执行端、可选协调模型及端口，并询问是否安装后台服务。默认只准备配置，不启动服务、不安装执行端、不请求密钥。取消确认不会写入配置。无终端环境必须明确提供参数：
+
+```bash
+agent-task setup --executors none --cwd /absolute/workspace --prepare-only
+# 可选：安装 Pi ACP 组件，但仍不授权执行。
+agent-task setup --home /absolute/private/agent-task \
+  --executors pi --cwd /absolute/workspace \
+  --provider deepseek --model deepseek-flash --prepare-only
+```
+
+这两个例子是不同的首次安装选择，不要用第二条覆盖已有安装。工作空间须预先存在，且位于安装目录及 npm 包之外。完整选项见 `agent-task setup --help`；执行端固定版本及平台实现见 [install-lib.mjs](../scripts/install-lib.mjs)。
+
+默认私有目录为 Linux 的 `~/.local/share/agent-task` 或 macOS 的 `~/Library/Application Support/agent-task`。setup 输出配置、凭据文件和控制台地址，**不打印 token**。使用自定义 `--home` 时，后续命令也需传同一路径。
+
+配置、凭据和任务数据不写入 npm 包目录。npm 管理应用包；setup 只管理私有目录、选定的 ACP 组件和用户服务。不要移动 npm prefix、Node 或安装目录后直接继续运行；当前不提供既有安装的自动路径重绑。
+
+## 配置与认证
+
+1. 前台运行 `agent-task start`，打开 setup 输出的本机控制台地址。用本地编辑器读取私有 `environment.json` 的 `AGENT_TASK_ADMIN_TOKEN`，在连接表单输入。不要把 token 放进 URL、命令行、Git、截图或日志。
+2. 在[控制台](web-console.md)配置协调模型、单独保存模型密钥及注册 ACP 执行端。未配置协调模型时，服务仍可启动和配置，但不能接收可执行任务。
+3. 如需安装器提供的执行端，用 setup 输出的专属路径按原生方式认证：[Pi](https://github.com/earendil-works/pi/tree/v1.3.0/packages/coding-agent/docs)、[Codex ACP](https://github.com/agentclientprotocol/codex-acp#readme)、[OpenCode](https://opencode.ai/docs/acp/)。后台服务与原生登录须使用一致的 HOME/配置目录。
+4. 停服后审核执行端原生工具、沙箱、凭据传递及结果读取范围，再由管理员明确批准 `unattendedApproved`。安装器从不登录、自动批准或扩大权限；ACP allowlist 不是完整工具授权或 OS 沙箱。
+5. 保存后手动重启。正在运行或等待人工回复的任务可能持有 ACP 会话，重启前须核查；不保证无损续接。
+
+后台和托管前台启动都只读取明确的私有环境文件，不自动继承 shell 模型密钥。MCP token、管理员 token、协调模型和执行端凭据必须分开。工作空间校验不是授权。
+
+显式执行握手检查：
+
+```bash
+agent-task setup --check --probe
+```
+
+这只执行 ACP initialize，不验证模型认证、任务成功或工具权限。普通 Pi CLI 不是 ACP server，需配合 pi-acp。已有执行端也可直接由控制台注册绝对 ACP 命令路径，不必重新安装或使用全局执行端。
+
+## 前台运行与健康检查
+
+```bash
+agent-task start
+# 另一个终端；自动从私有文件读取 MCP token，不输出凭据。
+agent-task status
+```
+
+Ctrl-C 停止前台服务。也可显式指定已有的私有文件：
+
+```bash
+agent-task start --config /absolute/private/config.json \
+  --environment /absolute/private/environment.json
+```
+
+文件权限、Web 认证与配置保存约束见[控制台说明](web-console.md)。显式文件模式不会生成安装清单；此时用自己的 MCP 客户端调用 `service_status`，不要使用依赖清单的 `agent-task status`。
+
+配置契约以 [config.example.json](../config.example.json)、[config.ts](../src/config.ts) 为准。开发者仍可 `npm ci --ignore-scripts && npm run build` 后使用 `npm start -- --config ... --environment ...`，但 npm 安装用户不需要这些步骤。
+
+## 后台运行
+
+先停止前台实例，再安装并启动后台服务：
+
+```bash
+agent-task service install
+agent-task status
+```
+
+命令在真实服务管理器中注册服务，并等待带 MCP token 的健康检查。重复安装不会覆盖配置或授权；已有同名但内容不同的服务会被拒绝覆盖。每个 OS 用户只管理一个同名服务。
+
+Linux 需要可连接的 systemd 用户管理器：
+
+```bash
+systemctl --user status agent-task.service
+systemctl --user stop agent-task.service
+systemctl --user restart agent-task.service
+journalctl --user -u agent-task.service
+```
+
+SSH/容器会话若没有用户 bus，应先配置正常用户会话；不要以 root 启动本服务。注销后运行需要管理员按策略配置 lingering，安装器不会启用。手动部署模板见 [deploy/agent-task.service.example](../deploy/agent-task.service.example)。
+
+macOS 需要已登录的图形用户会话：
+
+```bash
+launchctl print gui/$(id -u)/com.agent-task.service
+agent-task service remove
+agent-task service install
+```
+
+remove 停止并卸载服务注册，install 重新加载配置。LaunchAgent 不是系统 LaunchDaemon，不保证用户注销后运行。日志位于 setup 的私有目录内。launchd 不等同于 Linux cgroup；两平台都不保证休眠或关机期间准点执行。
+
+## 重入、更新与卸载
+
+重复 setup 保留配置和授权。中断安装只能显式 `agent-task setup --resume`；所有权、清单或服务状态不明时停止核查，不删除历史或工作空间修复。
+
+本项目仍处于调研阶段，不保证旧数据兼容。更新前阅读发行说明，停止服务并备份私有目录；普通启动不迁移既有数据。更换 Node 或 npm prefix 前先移除服务注册。不要在服务运行期间删除或覆盖应用包。
+
+```bash
+agent-task service remove   # 仅停服、移除服务注册；保留组件和数据
+agent-task uninstall        # 再移除本安装拥有的 ACP 组件
+npm uninstall -g @realqiyan/agent-task # 最后由 npm 移除应用包
+```
+
+`agent-task uninstall` 可重复运行，保留配置、凭据、日志、任务历史、工作空间和未入清单文件，不操作全局执行端及原生认证。卸载不是凭据撤销或数据销毁；停服不能回滚已发生的外部操作。实现见 [uninstall.mjs](../scripts/uninstall.mjs)。

package/docs/design-proposal.md

@@ -0,0 +1,55 @@
+# 智能任务总体方案
+
+本文保留产品目标和架构取舍。实现入口见[代码导航](technical-design.md)，实际证据见[验证说明](validation.md)。
+
+## 产品目标
+
+- 调用方通过 MCP 提交整体目标、DAG 和每节点的 ACP 执行端指派，支持立即、定时及周期执行。
+- 任务不依赖发起客户端持续在线，保留执行、交付、失败和缺少用户事实的记录。
+- 协调员推进既定 DAG、解释中间结果、处理澄清并组织交付；领域分析和工具操作交给执行端。
+- 缺少用户事实时可持久等待，回复后续接原运行，不丢失已接受工作。
+- 提供本机 Web 控制台，管理配置、查看任务，并只控制任务的未来触发；配置保存后手动重启生效。
+
+Pi Agent、Codex、OpenCode 是 ACP 集成目标，不是嵌入本服务的领域执行器。声明支持、代码实现和真实验收必须区分。
+
+## 架构选择
+
+```text
+MCP 调用方：定义 DAG、指派执行端
+                 │
+任务服务：时间计划、准入、持久事实与监督
+                 │
+pi durable：每个 TaskRun 的协调会话
+                 │ 受控业务工具
+ACP 执行端：原生会话、领域推理和工具操作
+```
+
+| 选择 | 原因 |
+| --- | --- |
+| 调用方固定 DAG，协调员只推进 | 保留调用方对计划和执行端的控制，不引入第二个规划器 |
+| 复用 durable 模型循环与检查点 | 不自写模型循环；SDK 的恢复能力仍需按实际版本验证 |
+| 确定性服务把守授权、预算和完成前提 | 模型的语义判断不能成为权限或安全边界 |
+| 业务账本与模型会话分开 | 对话和工具记录不能代替派发、交付或外部业务事实 |
+| 单节点与多节点共用 Task 模型 | 不维护两套 API、存储适配或调度器 |
+
+外层时钟只决定何时开始 TaskRun；协调员决定本轮节点派发。协议 turn 结束不等于交付完成，只有明确接受的执行端交付才能解锁依赖。
+
+交付由协调员及下游 Agent 阅读，不要求统一 JSON 或固定模板，普通文本和 Markdown 均可。验收关注内容是否满足节点目标；只有调用方明确提出格式要求时才检查格式。协议封装不规定交付正文的格式。
+
+人工回复只补充事实，不授予权限或允许重放。会话丢失、外部结果不明时停止并核对，不能用新任务或新节点绕过。其他安全与持久性要求见[架构原则](architecture-guidelines.md)。
+
+## 当前范围与暂缓能力
+
+当前是调研和 MVP 验证阶段，直接调整接口和数据结构，不维护旧版兼容或业务库版本递增；这不授权迁移或删除历史数据。
+
+暂不实现：执行中修改 DAG、自动重试或跨端故障转移、丢失 ACP 会话的重连、人工核对后强制恢复、远程执行、多租户、日历时区调度、技能同步及动态 MCP 转发。它们需要独立产品决策，不因引入 durable 自动获得。
+
+后台运行和平台限制见[部署说明](deployment.md)。[本机控制台](web-console.md)复用任务服务，使用独立管理员认证与浏览器请求边界；不提供文件下载或其他任务写操作。
+
+## 外部依据
+
+- [Pi durable](https://github.com/earendil-works/pi/tree/v1.3.0/packages/durable)
+- [ACP 会话](https://agentclientprotocol.com/protocol/v1/session-setup)、[工具与权限](https://agentclientprotocol.com/protocol/v1/tool-calls)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+
+实际依赖版本以 [package.json](../package.json) 和锁文件为准；协议说明不是验收证据。

package/docs/release.md

@@ -0,0 +1,57 @@
+# npm 发布
+
+目标包为 [@realqiyan/agent-task](https://www.npmjs.com/package/@realqiyan/agent-task)，首个候选版本 **0.0.1-rc.1**，发布账号 **realqiyan**，许可证 [MIT](../LICENSE)。该候选版有意使用 **latest**，因此默认 `npm install -g @realqiyan/agent-task` 会安装它；这不表示已达到稳定或生产可用状态。实际完成情况见[验证说明](validation.md#npm-发布候选验证)。
+
+版本、引擎、公开文件和 registry 设置以 [package.json](../package.json) 为准。[打包门禁](../scripts/pack-release.mjs)检查实际包清单；消费者安装不运行构建脚本。不要发布工作目录、私有环境、SQLite、运行日志、模型会话或测试证据。
+
+## 本地候选验收
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm test
+git diff --check
+npm run pack:release
+npm run test:install -- ./realqiyan-agent-task-0.0.1-rc.1.tgz --service
+```
+
+安装验证在独立临时目录执行真正的全局 npm 安装，禁用 lifecycle scripts，不使用项目源码或编译器；再配置、前台启动、调用 Web 配置接口、重启、运行用户服务、进行认证健康检查并卸载。验证脚本不调用模型或启动 ACP 工作。仅 `--service` 会触及真实用户服务管理器，遇到已有同名服务会拒绝，不覆盖其他安装。
+
+输出报告只包含结果和证据目录，不包含 token。临时目录权限为私有，内有验证专用随机凭据及空任务库，不上传这些目录。若只验证前台可省略 `--service`，但不能据此宣称后台已通过。基础测试中的真实 PTY 用例验证交互式向导的确认和取消；仍需人工核查目标终端体验。
+
+在 Linux 和 macOS 分别运行；平台缺失、网络失败或后台启动失败都不能被模板检查替代。平台限制见[部署说明](deployment.md#后台运行)。本地可设置 `npm_config_cache` 复用下载缓存，tarball 验证可用 `npm_config_registry` 指定依赖镜像，报告会记录其地址；`--registry` 发布后验收固定使用 npmjs。不能以复制项目的 node_modules 替代安装验证。
+
+## GitHub Actions 门禁与受控发布
+
+- [Validate](../.github/workflows/ci.yml)：PR/master 执行 TypeScript 检查、基础测试及构建；检查包清单。Linux 和 macOS 安装任务**不 checkout 项目源码**，只接收 tarball 和验收脚本，要求真实服务管理器及认证检查通过。
+- [Publish npm](../.github/workflows/publish.yml)：仅手动触发，限制 master 和账号 realqiyan，输入须匹配已验收包版本。再次执行全部门禁，再发布同一 tarball，不重建、不执行包脚本。发布后核查 latest 并执行默认全局安装验证。
+- 普通 CI 没有 npm 凭据。发布作业单独获得凭据及 provenance 所需权限。并发发布被串行化。
+
+首次启用前，由仓库管理员创建 GitHub Environment **npm**：
+1. 配置必要审核人及仅允许 master 部署。若要禁止发起人自审，需要另一个审核人。
+2. 在该 Environment 中添加 **NPM_TOKEN**，使用 realqiyan 的最小发布权限、短有效期 token，允许直接发布（publish and stage），并满足 npm 的 2FA/自动发布策略。不要放入仓库文件或普通 CI 环境。
+3. 核查分支保护及工作流修改权限。工作流中的 environment 名称本身**不自动创建审核保护**。
+4. 将代码审查后提交到 master，再在 Actions 选择 Publish npm，输入 `0.0.1-rc.1`。包尚不存在时，应确认账号允许首次创建此名称；认证/权限失败须停止，不能换账号或跳过验证。
+
+发布命令明确传 `--tag latest --access public --provenance`。provenance 依赖 GitHub OIDC，不代替 npm 发布授权。当前流程要求 Environment token 并检查 `npm whoami` 为 realqiyan；不宣称已经配置 npm trusted publishing。
+
+## 经授权的本机首次发布
+
+若由维护者明确批准在本机首次发布，须先完成同样的候选验收；这条路径没有 GitHub provenance。通过 npm 官方交互登录，不通过聊天、命令参数或 Git 传递 token：
+
+```bash
+npm login --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+# 必须确认输出 realqiyan，再发布已检查的 tarball：
+npm publish ./realqiyan-agent-task-0.0.1-rc.1.tgz --ignore-scripts \
+  --access public --tag latest --registry=https://registry.npmjs.org
+npm view @realqiyan/agent-task@0.0.1-rc.1 version license --registry=https://registry.npmjs.org
+npm view @realqiyan/agent-task dist-tags --json --registry=https://registry.npmjs.org
+node scripts/verify-install.mjs --registry --service
+```
+
+登录成功不等于发布授权已完成。若 registry 返回需要 2FA 的 E403，停止发布；维护者须在自己的终端完成发布时认证，或配置有目标包发布权限、短有效期且获准 bypass 2FA 的 granular token。不要关闭账号 2FA，不在聊天、命令参数或日志中传递一次性验证码或 token；不把本机登录凭据自动上传到 GitHub。
+
+不得把 dry-run、上传成功提示或候选包安装当成 npmjs 完成证据。应记录 registry 版本与 latest、默认安装结果、各平台报告，以及未执行的检查。发布结果不明时先查询 registry；同一版本不可覆盖，不盲目重试，也不擅自换版本。
+
+已发布候选有问题时，停止继续安装验证，保留证据并通知维护者决定弃用提示、tag 调整或新版本。不自动撤包、覆盖历史或删除用户数据。

package/docs/technical-design.md

@@ -0,0 +1,37 @@
+# 代码导航
+
+本文指向职责入口和对应测试，不复述字段、默认值、状态枚举或内部流程。目标见[总体方案](design-proposal.md)，设计要求见[架构原则](architecture-guidelines.md)。
+
+## 按问题查找
+
+| 问题 | 代码入口 | 基础验证 |
+| --- | --- | --- |
+| 服务如何装配、启动和关闭 | [main.ts](../src/main.ts)、[lock.ts](../src/lock.ts) | [service.test.mjs](../tests/service.test.mjs)、[results-admin.test.mjs](../tests/results-admin.test.mjs) |
+| MCP 有哪些工具、输入是什么 | [mcp.ts](../src/mcp.ts)、[task-contract.ts](../src/task-contract.ts) | [service.test.mjs](../tests/service.test.mjs) |
+| Task、Run、节点的数据与推进规则 | [task-model.ts](../src/task-model.ts)、[tasks.ts](../src/tasks.ts) | [tasks.test.mjs](../tests/tasks.test.mjs) |
+| 人工等待、回复及续接 | [human-input.ts](../src/human-input.ts) | [human-input.test.mjs](../tests/human-input.test.mjs) |
+| durable 工具与模型接入 | [coordinator.ts](../src/coordinator.ts)、[coordinator-provider.ts](../src/coordinator-provider.ts) | [coordinator-provider.test.mjs](../tests/coordinator-provider.test.mjs) |
+| 持久数据校验和提交 | [task-storage.ts](../src/task-storage.ts)、[coordinator-storage.ts](../src/coordinator-storage.ts) | [durable.test.mjs](../tests/durable.test.mjs)、[tasks.test.mjs](../tests/tasks.test.mjs) |
+| ACP、worker 和进程关闭 | [acp.ts](../src/acp.ts)、[node-execution.ts](../src/node-execution.ts)、[worker.ts](../src/worker.ts) | [execution.test.mjs](../tests/execution.test.mjs)、[tasks.test.mjs](../tests/tasks.test.mjs) |
+| 审批、环境与结果文件范围 | [permissions.ts](../src/permissions.ts)、[config.ts](../src/config.ts)、[results.ts](../src/results.ts) | [policy.test.mjs](../tests/policy.test.mjs)、[results-admin.test.mjs](../tests/results-admin.test.mjs) |
+| 配置、管理员注册和工作空间 | [config.ts](../src/config.ts)、[model.ts](../src/model.ts)、[admin.ts](../src/admin.ts)、[workspace.ts](../src/workspace.ts) | [config-preflight.test.mjs](../tests/config-preflight.test.mjs)、[tasks.test.mjs](../tests/tasks.test.mjs) |
+| 控制台 HTTP 边界与页面 | [web.ts](../src/web.ts)、[http-auth.ts](../src/http-auth.ts)、[页面模块](../src/web/) | [web.test.mjs](../tests/web.test.mjs) |
+| 配置和凭据的校验、保存与下次启动 | [settings.ts](../src/settings.ts)、[settings-contract.ts](../src/settings-contract.ts)、[private-files.ts](../src/private-files.ts)、[environment.ts](../src/environment.ts) | [settings.test.mjs](../tests/settings.test.mjs)、[web.test.mjs](../tests/web.test.mjs) |
+| npm 命令、安装、启动环境与卸载 | [agent-task.mjs](../bin/agent-task.mjs)、[setup-wizard.mjs](../scripts/setup-wizard.mjs)、[setup.mjs](../scripts/setup.mjs)、[install-lib.mjs](../scripts/install-lib.mjs)、[service-runner.mjs](../scripts/service-runner.mjs)、[uninstall.mjs](../scripts/uninstall.mjs) | [install.test.mjs](../tests/install.test.mjs)、[setup.test.mjs](../tests/setup.test.mjs)、[verify-install.mjs](../scripts/verify-install.mjs) |
+| npm 包清单与发布门禁 | [package.json](../package.json)、[pack-release.mjs](../scripts/pack-release.mjs)、[工作流](../.github/workflows/) | [发布说明](release.md) |
+
+配置示例见 [config.example.json](../config.example.json)，命令和依赖版本见 [package.json](../package.json)。测试只说明各自验证的风险，不能把失败进程或结构化状态测试当成真实模型成功执行。
+
+## 当前架构差距
+
+- `tasks.ts` 同时承担业务状态、时间触发和运行监督，尚未完成目标职责拆分。
+- `model.ts` 混合类型与 schema；持久 schema 复用输入契约；`results.ts` 混合路径授权与文件操作。
+- 尚无依赖边界检查器。后续按实际功能修改收敛，不为分层增加空壳。
+
+## 集成与验收入口
+
+- [probe-agent.mjs](../scripts/probe-agent.mjs)：只做 ACP initialize。
+- [单节点用例](../tests/e2e/deepseek-acp.test.mjs)、[人工回复 DAG 用例](../tests/e2e/human-dag.test.mjs)：真实模型验收。
+- [E2E harness](../tests/e2e/harness.mjs)、[Pi 验收启动器](../scripts/run-pi-human-e2e.mjs)：环境准备、服务生命周期和证据保存。
+
+操作前置条件和已验证范围见[部署说明](deployment.md)、[验证说明](validation.md)。握手、任务成功和权限隔离是不同证据。

package/docs/validation.md

@@ -0,0 +1,100 @@
+# 验证导航与证据边界
+
+**三节点 DAG 已有真实模型运行证据；最新文本交付验收未通过，原因见下文。** 项目不宣称生产可用或外部副作用 exactly-once。
+
+## 本地验证
+
+```bash
+npm run check
+npm test
+git diff --check
+```
+
+各职责的测试入口见[代码导航](technical-design.md)。基础测试使用真实本地文件、SQLite、进程和 SDK，不调用外部模型，不使用假模型或模拟 provider。失败进程和 no_model 只证明失败路径；结构化状态用例不证明模型语义判断。check 仅检查 TypeScript，不检查依赖边界。
+
+## 控制台验证
+
+[HTTP 用例](../tests/web.test.mjs)使用真实本机服务进程验证独立管理员认证、Host/Origin/请求类型边界、有限任务写入、密钥不回显或进入日志，以及保存前后和重启后的配置差异。实际任务记录来自业务服务，不使用假模型输出。
+
+[配置用例](../tests/settings.test.mjs)验证私有文件边界、旧编辑拒绝、显式凭据环境、端点与密钥引用分离、失败时保留文件，以及关闭后拒绝操作。这些用例不构成断电、磁盘满或目录同步失败窗口的完整证据。
+
+尚未完成真实浏览器交互、CSP 执行和跨浏览器缓存/自动填充验收。需在浏览器核对：不可信任务文本不执行脚本或加载外链；离开、刷新和退出后无令牌残留；配置草稿不被轮询覆盖；密钥保存与配置保存的提示明确。HTTP 头检查不能替代这些验证，也不证明模型认证或 ACP 执行成功。
+
+## 真实模型验收入口
+
+仅在获准环境显式运行，会产生模型费用；不使用个人凭据或真实交易：
+
+- 单节点：`npm run test:e2e`。需安全注入 `DEEPSEEK_API_KEY`，并将 `AGENT_TASK_E2E_EXECUTOR` 指向已审核的 ACP profile。执行端须另行准备原生认证及无领域副作用的配置，不继承协调密钥。
+- DAG 与人工回复：`npm run test:e2e:human -- --quantity 4`。需已安装 Pi、pi-acp 和获准 DeepSeek 测试凭据；数量由测试客户端提供，不冒充真人回答。
+- 真人模式：`npm run test:e2e:human -- --answer-file /absolute/private/path/quantity.txt`。使用新文件，等待旁边的 `.question.json` 出现，再写入答案。
+
+完整前置检查、参数和断言见 [E2E 用例](../tests/e2e/)、[Pi 启动器](../scripts/run-pi-human-e2e.mjs)。Pi 启动器为两端共用获准测试密钥，创建独立原生配置，只启用 read；这不是 OS 沙箱或独立账户隔离。强杀或断电不能保证临时认证清理，需管理员核查。
+
+运行证据保留在命令输出的私有目录，可能包含敏感内容；不自动删除或将一次成功推广为普遍支持。
+
+### 本机三节点验收
+
+2026-10-22，Linux x64、Node 24.15.0，使用 DeepSeek 协调员和只读 Pi ACP 执行端，此前带 JSON 格式约束的用例运行 `npm run test:e2e:human -- --quantity 4` 一次通过，约 28 秒。数量由测试客户端提供，结果为 1292，不是真人输入。
+
+该次运行验证了固定 DAG 的真实 ACP 交付、人工等待后续接同一运行、同一 ACP 会话内澄清，以及已接受上游不重放。未执行独立单节点用例、真人回答文件模式或重启/故障恢复。
+
+复核业务库、durable 记录和 Pi 原生会话后，确认只有一个 TaskRun、三个 ACP 会话和两次上游文件读取。`audit` 的工具前说明与最终 JSON 被聚合进同一轮输出，导致额外一轮格式澄清；没有重复读取上游文件。
+
+执行端启动时还留下了三次 `npm view @earendil-works/pi-coding-agent version` 记录，来源是 `pi-acp` 的版本检查，Pi 子进程的 `--offline` 未阻止该行为。日志没有查询结果，不能确认 registry 请求是否完成。服务和执行端原始 stderr、完整 ACP 通信未保留，不能据此证明整个执行栈无其他外部访问或诊断错误。
+
+测试日志：`/tmp/agent-task-pi-human-H1OKJO/test-1.log`；Pi 原生会话及 npm 日志位于同目录的 `home/`；运行证据：`/tmp/agent-task-real-e2e-O9N9RY`。临时原生认证已清空。临时文件可能被系统清理，长期留存需管理员安全归档。
+
+### 文本交付复验
+
+同日移除用例中的 JSON 格式要求和固定澄清口令，以相同命令复验一次，约 26 秒。三个节点均输出普通文本或 Markdown，轮数为 1 / 2 / 1；没有为了格式追加澄清，计算结果仍为 1292。
+
+但测试未通过：`audit` 原始输出包含必需标识，协调员接受的片段遗漏了该标识，验收理由仍声称包含它，运行被标为 `succeeded`。[三节点用例](../tests/e2e/human-dag.test.mjs)的内容断言拦住了这一遗漏，没有降低断言或重跑。此结果说明文本传递可执行，但不能把运行成功状态当成完整交付的证据；已补充摘录完整性指令，尚待真实模型复验。交付格式原则见[总体方案](design-proposal.md#架构选择)。
+
+测试日志：`/tmp/agent-task-pi-human-K8huNN/test-1.log`；运行证据：`/tmp/agent-task-real-e2e-XgRgeo`。旧记录保留，临时原生认证已清空。
+
+## 恢复保证的边界
+
+早期 durable 研究曾在真实 SQLite/文件/SIGKILL 实验中观察到：外部文件写入后、结果提交前崩溃，恢复检查点再次执行了未做幂等保护的写入。这不是 ACP 恢复验收，而是检查点不保证外部副作用 exactly-once 的证据。
+
+## 部署验证
+
+Linux x64、Node 24.15.0 的本机记录：
+
+- 专属目录安装、重复安装、真实 systemd 用户服务及带 token 的 MCP 健康检查通过。
+- Pi 1.3.0 + pi-acp 0.0.34、codex-acp 2.2.2、OpenCode 1.19.3 在独立无认证 HOME 下均通过 initialize；没有发送 session/new 或模型任务，也未自动批准执行端。
+- 经 MCP 保存并暂停未来任务，两次卸载后保留任务记录、配置、环境、工作空间和未入清单文件；服务已移除。
+- 首次安装实验遭遇磁盘满并损坏实验清单；未删除任务数据修复。修正后在新的专属目录完成上述部署复验，不构成业务运行时磁盘满恢复的证据。
+
+证据目录：`/tmp/agent-task-deploy-verified`、`/tmp/agent-task-deploy-final`；工作空间：`/tmp/agent-task-deploy-workspace`；空认证 HOME：`/tmp/agent-task-deploy-native-home`。临时文件可能被系统清理，长期留存需管理员安全归档。
+
+macOS 已有 launchd 实现，但没有安装、后台运行、任务执行或卸载的实机证据。待验收重点是原生认证与权限、关闭终端后的任务存续、取消及进程清理、重复卸载的数据保留；模板生成和 Linux 测试不能替代。
+
+## npm 发布候选验证
+
+2026-10-22，候选包 `@realqiyan/agent-task@0.0.1-rc.1`。本节记录打包前验收；发布后结果以[仓库中的最新记录](https://github.com/realqiyan/agent-task/blob/master/docs/validation.md#npm-发布候选验证)及 npmjs 查询为准，不以包内文档判断实时 registry 状态。发布前已确认 npm 账号为 `realqiyan`；不能把本地打包或 publish dry-run 当作发布完成。
+
+npm 因包名保护拒绝了未加 scope 的 `agent-task`：名称被判定与 `agent-base` 过于相似。维护者已明确批准使用 `@realqiyan/agent-task`，安装命令随之改为 `npm install -g @realqiyan/agent-task`，CLI 仍为 `agent-task`。未关闭账号 2FA，也未上传本机凭据。
+
+本次 Linux x64 证据：
+
+- Node 22.19.0 和 24.15.0 的 TypeScript 检查、33 项基础测试及构建均通过；真实 PTY 用例验证 setup 的确认/取消、生成独立 token 和不输出凭据。
+- [包清单门禁](../scripts/pack-release.mjs)通过：仅包含预编译 JS、Web 资源、明确列出的操作脚本、示例及公开文档；不包含源码、开发工具、凭据文件、运行数据库或本地记录。
+- Node 22.19.0 从 tarball 全局安装到独立临时 prefix，禁止 lifecycle scripts，不使用项目源码或 TypeScript。前台启动、Web HTTP 配置保存/重启、真实 systemd 用户服务及带认证的健康检查通过。
+- 重复 setup 保留 token；重复卸载保留配置、凭据、任务库和工作空间。显式注册的执行端仍未授权，没有 ACP 工作或模型调用。捕获的命令、前台输出及用户服务日志未出现验证用凭据，测试服务已移除。
+- 依赖安装使用 `https://registry.npmmirror.com` 和 npm 下载缓存。npmjs 直连安装曾分别在 5 分钟、15 分钟限时内未完成依赖下载；不据此推断包损坏，也不宣称官方 registry 安装已通过。
+
+完整 Linux 22.19.0 报告：`/tmp/agent-task-0.0.1-rc.1-linux-node22-report.json`。Linux 24.15.0 的独立前台验收报告：`/tmp/agent-task-npm-CrtOcO/report.json`（未测试后台）。临时目录包含验证专用随机凭据和空业务库，不上传或打包；报告仅含结果。Node 22.19.0 会输出内置 SQLite 的 experimental warning，这不是认证错误。
+
+已添加 [CI](../.github/workflows/ci.yml) 和[受控发布工作流](../.github/workflows/publish.yml)，但本次尚未提交/推送工作流、在 GitHub 执行、配置发布 Environment 审核或注入 npm 发布凭据。工作流定义不是实际运行证据。macOS LaunchAgent、真实浏览器交互、默认 `npm install -g @realqiyan/agent-task` 及 npmjs 目标版本仍待验收；不得标记完成。
+
+操作和发布条件见[部署说明](deployment.md)、[发布说明](release.md)。此前源码安装的历史部署证据不替代本次 npm 候选包验收。
+
+## 尚未验证
+
+- 独立单节点用例在当前接口上的真实模型复验、复杂任务的语义验收、并行分支与汇合、不同执行端之间的交付。
+- 各执行端原生权限、认证续期、沙箱、技能/MCP 发现及文件访问；其他模型和 OpenAI 兼容端点的协议差异。
+- 真实模型崩溃窗口、重复收费和预算行为；人工等待期间保留真实 ACP 会话的续答、并发回复、长时间等待及重启。
+- 系统级强杀、断电、业务库磁盘满、Linux 注销/重启与 cgroup 清理，以及 macOS 部署和监督。
+- SDK 升级、历史数据转换，以及执行中修改计划等当前未开放能力。
+
+实现和操作入口见[代码导航](technical-design.md)、[部署说明](deployment.md)。

package/docs/web-console.md

@@ -0,0 +1,46 @@
+# 本机 Web 控制台
+
+控制台与 MCP 共用 HTTP 服务，只监听 `127.0.0.1`。访问 `http://127.0.0.1:<port>/admin/`，不要改用 LAN 地址、反向代理或公网转发。
+
+## 启用与连接
+
+新安装由 `agent-task setup`（[实现](../scripts/setup.mjs)） 在私有 `environment.json` 中生成独立的 `AGENT_TASK_ADMIN_TOKEN`。用本地编辑器读取该字段并在连接表单输入；它不是 MCP token，不能放进 URL、命令参数、截图或日志。
+
+已有文件不会由 setup 补写或覆盖。缺少管理员令牌时，管理接口关闭。需要启用时先停服，用本地密码管理器生成独立随机令牌，离线加入该字段；令牌约束见 [main.ts](../src/main.ts)。不要复用服务或模型密钥。
+
+托管服务已绑定配置和环境文件。手动部署使用：
+
+```bash
+agent-task start --config /absolute/private/config.json \
+  --environment /absolute/private/environment.json
+```
+
+两个文件须属于当前用户、权限为 `0600`，所在目录须为规范绝对路径、权限为 `0700`，不接受符号链接。环境文件仅在进程启动时加载；显式文件模式不回退到 shell 凭据。文件格式和基础环境来源见 [environment.ts](../src/environment.ts)、[install-lib.mjs](../scripts/install-lib.mjs)。
+
+令牌仅保留在页面内存中；退出、离开或刷新后重新连接。不设置 Cookie，不写浏览器持久存储。配置和密钥文件仍是本地明文，须按凭据保护；此方案不隔离同一 OS 用户的其他进程或恶意浏览器扩展。
+
+## 操作范围
+
+- 任务列表、固定 DAG、运行历史、节点进度、已接受交付、错误和问题只读。触发计划结束不等于运行成功，原始输出不等于交付。
+- 任务写操作仅复用 `task_update`，暂停、恢复或取消未来触发。不停止当前运行，不补跑错过的触发，不回答问题或修改 DAG。
+- 注册信息、ACP 权限和协调模型配置可编辑；数据目录、监听端口和服务认证配置只读。执行端原生认证及权限继续使用其官方工具。
+
+页面与接口入口见 [web.ts](../src/web.ts)、[页面模块](../src/web/)，任务契约见 [task-contract.ts](../src/task-contract.ts)。没有通用 MCP 代理、文件浏览器或重启接口。
+
+## 保存与重启
+
+1. 密钥只显示是否设置，原值不回显。不提交即保留；替换和删除必须明确操作。先保存新密钥，再保存引用它的配置。新凭据命名和受保护变量见 [settings.ts](../src/settings.ts)。
+2. 配置先校验并预览影响，再确认保存。校验不调用模型或启动 ACP，不能证明认证、原生权限或实际执行成功。修改执行端字段后，页面要求重新明确批准无人值守执行。
+3. 配置与密钥分别原子替换，不是跨文件事务。更换模型端点须使用新的凭据引用，避免中途重启将新密钥交给旧端点。旧凭据不自动清理。
+4. 保存不更新当前进程的配置、权限或环境。检查活动运行及待回答运行后，按[后台管理](deployment.md#后台管理)手动重启；故障后的自动拉起也会读取已保存值。
+5. 重启后重新连接并核对运行配置。启动失败须从终端修正私有文件；提交结果不确定时停止继续保存并停服核查。不删除历史、自动回滚或重放执行来修复。
+
+待回答运行也可能持有 ACP 会话，重启不保证无损续接。执行端注册信息与任务快照不一致时，旧任务的派发会被拒绝；页面显示受影响任务，但不改写快照、DAG 或执行端指派。需要新任务时由 MCP 调用方处理。
+
+多个页面的旧编辑会被拒绝，不做自动合并。离线编辑配置须先停服。校验与保存职责见 [settings.ts](../src/settings.ts)、[settings-contract.ts](../src/settings-contract.ts)、[private-files.ts](../src/private-files.ts)。
+
+## 安全与验收
+
+管理接口使用独立 Bearer 认证、严格 Host/Origin 检查及 JSON 写请求，不开放 CORS；MCP 不接受控制台令牌或浏览器 Origin。页面以纯文本展示不可信内容，不渲染模型 HTML 或 Markdown，不自动加载外链。密钥不进入 API 读取结果或服务日志，Agent 输出仍可能敏感。
+
+证据与未验证边界统一见[验证说明](validation.md#控制台验证)。

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@realqiyan/agent-task",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-rc.1",
+  "license": "MIT",
+  "author": "realqiyan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realqiyan/agent-task.git"
+  },
+  "homepage": "https://github.com/realqiyan/agent-task#readme",
+  "bugs": "https://github.com/realqiyan/agent-task/issues",
+  "bin": {
+    "agent-task": "bin/agent-task.mjs"
+  },
+  "files": [
+    "bin/agent-task.mjs",
+    "dist/**/*.js",
+    "dist/web/*.html",
+    "dist/web/*.css",
+    "scripts/setup.mjs",
+    "scripts/setup-wizard.mjs",
+    "scripts/install-lib.mjs",
+    "scripts/service-runner.mjs",
+    "scripts/uninstall.mjs",
+    "scripts/probe-agent.mjs",
+    "scripts/mcp-call.mjs",
+    "docs/*.md",
+    "deploy/*.example",
+    "config.example.json",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "os": ["linux", "darwin"],
+  "type": "module",
+  "description": "Durable intelligent task coordination over MCP with ACP executors",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "rm -rf dist && tsc && node scripts/copy-web.mjs",
+    "test": "npm run build && node --test --test-concurrency=1 tests/*.test.mjs",
+    "test:e2e": "npm run build && node --test --test-concurrency=1 tests/e2e/deepseek-acp.test.mjs",
+    "test:e2e:human": "npm run build && node scripts/run-pi-human-e2e.mjs",
+    "start": "node dist/main.js",
+    "setup": "node bin/agent-task.mjs setup",
+    "prepack": "npm run build",
+    "pack:release": "node scripts/pack-release.mjs",
+    "test:install": "node scripts/verify-install.mjs",
+    "uninstall:service": "node scripts/uninstall.mjs"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "2.0.0",
+    "@earendil-works/chord": "1.3.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "express": "5.3.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "24.19.2",
+    "typescript": "5.9.3"
+  }
+}