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

package/docs/architecture-guidelines.md

@@ -0,0 +1,52 @@
+# 架构原则
+
+目标是让维护者可以局部理解并安全修改系统，不为目录对称或未来假设增加机制。产品边界见[总体方案](design-proposal.md)，当前差距见[代码导航](technical-design.md)。
+
+## 职责与依赖
+
+| 责任 | 所有者 |
+| --- | --- |
+| 输入、输出、schema、错误契约和调用适配 | 工具 |
+| 业务决定、授权、状态转换、副作用顺序及恢复策略 | 服务 |
+| 严格读写、事务、索引和持久化健康状态 | 存储 |
+| MCP/ACP、进程及操作系统协议 | 接入 |
+| 依赖装配、运行实例及生命周期 | 应用入口 |
+| 普通领域数据，不含业务行为或 SDK 对象 | 模型 |
+| 展示与收集操作，通过服务执行 | Web 控制台 |
+
+服务只接收普通数据和窄能力，不依赖 SDK 上下文、HTTP 对象、UI 或完整进程对象。接入实现服务所需能力，由入口装配；存储不反向依赖服务或协议。禁止循环依赖、隐藏的全局可变状态和服务定位器。
+
+当前仍是扁平 MVP，不要求立即按层建目录。修改受影响职责时连同边界收敛，并保持行为测试；不做纯目录搬迁，不加空目录、无人使用的接口、转发层或动态插件平台。依赖边界检查应在分层落实后引入，不能提前声称已有。
+
+## 执行与持久性
+
+- 复用 SDK 模型循环；只有协调员推进既定 DAG，不再增加规划器或并行节点调度器。
+- Task、Run、模型会话、ACP Session 和外部业务记录各有责任主体，不能互相代替。
+- 先可靠保存接收或派发意图，再触发外部工作。业务幂等不能证明外部副作用只发生一次。
+- 只有明确接受的执行端交付才能解锁依赖；模型判断不能替代领域证据。
+- 未收到结果不等于没有执行。中断或结果不明时阻止新派发，包括模型新发起的调用；不自动重试、切换 Agent 或创建新身份重放。
+- 截止时间限制新执行开始，执行超时是另一规则。客户端断开不取消任务；取消不回滚外部操作。
+- 资源有明确所有者，关闭幂等，关闭后拒绝操作。先停止新派发，再处理活动执行、网络与存储，最后释放所有权。
+- 目录锁、事务、worker 监督和服务管理器解决不同问题，不等于跨机一致性、无孤儿进程或工具沙箱。
+
+## 权限与敏感数据
+
+- 执行端声明能力、管理员授权、真实验证证据分别表达，不能相互推导。
+- 只有管理员注册的执行端可启动。命令、凭据和能力端点属于管理员；任务可选择现有绝对工作空间，但路径校验不是授权或沙箱。
+- 授权须在可控制的实际操作入口检查。沿用执行端原生授权，额外 ACP 审批请求一律拒绝；`unattendedApproved` 不能证明所有原生工具已受控。
+- Prompt、角色、技能、工具标题、协议成功和人工事实回复都不授予权限。取消、恢复和跨 Agent 传递不能扩大授权。
+- 无人值守执行不等待交互审批；授权不充分或元数据不足时拒绝，不退回更宽权限或自动永久允许。
+- MCP token、管理员 token、协调模型与执行端凭据分开；执行端继承用户原生环境前过滤服务私密变量，不有意记录秘密。Agent 输出和协调日志仍可能敏感。
+- 优先使用执行端原生配置，不读取其私有业务存储格式，不将特定领域规则塞进平台。
+
+## 存储与发布
+
+使用本项目版本，不复制其他项目的存储标记。调研阶段不保留兼容层、额外版本计数或旧执行引擎；单节点和多节点共用 Task API。
+
+新库初始化与既有数据升级分开。严格加载支持的契约，损坏或未知数据拒绝使用。普通启动不静默迁移、猜测修复或删除历史。
+
+实际转换应是独立离线操作：声明源与目标格式、停止服务并取得排他所有权、备份、转换后验证、支持显式接续。不通过重放外部请求或重建工作空间修复记录，不引入文件哈希验证。
+
+## 开发与文档
+
+测试方法、命令和文档维护规则统一见 [AGENTS.md](../AGENTS.md)。需求、当前实现和验证证据分别维护；具体字段和流程链接到代码，不在多份文档中重复。

package/docs/deployment.md

@@ -0,0 +1,115 @@
+# 安装与运行
+
+支持 Linux 和 macOS，要求 Node.js **22.19+** 与 npm。安装包包含运行产物，不需要源码或 TypeScript。发布状态和平台证据见[验证说明](validation.md)，发布操作见[发布说明](release.md)。
+
+## 安装与交互配置
+
+```bash
+npm install -g @realqiyan/agent-task
+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`。自定义 `--home` 后，后续命令也传同一路径。setup 输出私有文件路径和控制台地址，**不打印 token**。
+
+## 数据目录与配置
+
+初始 `dataDir` 是安装目录下的 `data/`。运行配置、私有环境文件、任务和协调会话记录、结果及服务文件日志均位于当前 `dataDir`。配置契约见 [config.ts](../src/config.ts)，路径选择与新目录准备见 [startup.ts](../src/startup.ts)。
+
+安装目录保留固定的 `launch.json` 定位文件、安装清单、组件及启动器控制资源；它不是另一份运行配置。这个固定入口让原有 CLI、systemd 和 launchd 注册在更换数据目录后仍能找到服务。npm 包、用户工作空间和执行端原生配置不随 `dataDir` 移动。
+
+在 Web 修改数据目录后，下次启动只在目标目录准备已保存的配置和私有环境，并切换定位文件；**不复制任务、会话、结果或日志，不删除旧目录**。目标已有不同启动文件时拒绝覆盖；须停服核对并显式准备目标，不自动合并或修复。新目录没有旧任务，不能把切换目录当成故障恢复或重放许可。
+
+1. 运行 `agent-task start`，打开输出的本机控制台地址。用本地编辑器读取当前 `dataDir/environment.json` 的 `AGENT_TASK_ADMIN_TOKEN`，在连接表单输入。不要把 token 放进 URL、命令行、Git、截图或日志。
+2. 在[控制台](web-console.md)配置协调模型、单独保存模型密钥及注册执行端。未配置协调模型时可管理服务，但不能接收可执行任务。
+3. 按执行端官方方式准备原生认证及权限：[Pi](https://github.com/earendil-works/pi/tree/v1.3.0/packages/coding-agent/docs)、[Codex ACP](https://github.com/agentclientprotocol/codex-acp#readme)、[Claude ACP](https://github.com/zed-industries/claude-agent-acp)、[OpenCode](https://opencode.ai/docs/acp/)。后台服务与原生登录须使用同一 OS 用户及相应 HOME/配置目录。
+4. 审核原生工具、沙箱、凭据和结果文件读取权限后，再明确批准无人值守执行。注册只选类型，不配置命令、参数、环境变量清单或 ACP 工具白名单；系统映射见 [executor-runtime.ts](../src/executor-runtime.ts)。额外 ACP 审批请求被拒绝，不自动批准。
+
+服务和协调员的秘密只从私有环境文件加载，不回退到 shell 模型密钥。执行端沿用启动上下文中的用户原生环境，但排除私有文件变量、服务/管理员令牌、协调员凭据及同值别名。不要把执行端原生凭据放入服务的私有环境文件。后台管理器的环境未必等于交互式 shell；启动器不执行 shell 启动脚本，也不导入原生认证文件。隔离实现见 [environment.ts](../src/environment.ts)、[executor-runtime.ts](../src/executor-runtime.ts)。这不是同一 OS 用户下的沙箱。
+
+显式握手检查：
+
+```bash
+agent-task setup --check --probe
+```
+
+这只做 ACP initialize，不验证模型认证、任务成功或原生工具权限。普通 Pi CLI 不是 ACP server，须配合 pi-acp。自行安装的受支持适配器也可使用，只要在服务的原生 PATH 中；无需填写绝对可执行文件路径。
+
+## 前台、重启与健康检查
+
+```bash
+agent-task start
+# 另一个终端：
+agent-task status
+agent-task restart
+```
+
+Ctrl-C 关闭前台启动器及其运行进程。`restart` 和 Web 的“重启并检查可用性”使用同一启动器：先停止新派发、关闭活动执行并释放数据所有权，再用已保存配置创建新进程。前台终端和后台服务管理器继续监督启动器，不需另开一个脱离监督的进程。
+
+只有新实例通过带 MCP token 的健康检查才返回成功，并给出新实例标识及地址。端口变化或自动分配端口时，以返回地址为准；Web 不通过链接传递管理员令牌，须重新连接。
+
+重启会关闭 ACP 会话，不保证等待人工回复的运行能无损继续。结果不明的执行保持阻断，不自动重试、重放或改派执行端。请求超时不代表重启没发生，先用 `agent-task status` 核对；不要盲目重复操作。
+
+启动失败不会回滚配置或重放工作。查看当前 `dataDir/service.log`；确认没有运行实例持有数据后，修正私有文件，再显式 `agent-task restart`。启动器也已退出时，用原启动方式重新启动。后台管理器的“进程活动”不等于 HTTP 服务可用，以认证健康检查为准。
+
+源码开发者执行 `npm ci --ignore-scripts && npm run build` 后，可用 `npm run setup -- ...` 和 `npm start -- --home ...`；npm 安装用户不需要构建。内部 `dist/main.js` 不是独立的重启入口。
+
+## 后台运行
+
+先停止前台实例，再注册并启动用户服务：
+
+```bash
+agent-task service install
+agent-task status
+agent-task restart
+```
+
+重复安装不会覆盖配置或批准执行端。同名但内容不同的服务文件会被拒绝覆盖。每个 OS 用户只管理一个同名服务。
+
+Linux 需要可连接的 systemd 用户管理器：
+
+```bash
+systemctl --user status agent-task.service
+systemctl --user stop 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 restart
+agent-task service remove
+```
+
+LaunchAgent 不是系统 LaunchDaemon，不保证用户注销后运行，也不等同于 Linux cgroup。两平台都不保证休眠或关机期间准点执行。服务文件日志由启动器写入当前数据目录；systemd journal 是操作系统另行管理的日志。
+
+## 更新与卸载
+
+重复 setup 保留配置和授权。中断安装只能显式 `agent-task setup --resume`；所有权或清单不明时停止核查，不删除数据修复。
+
+调研阶段不保证旧数据兼容，也不提供普通启动迁移。更新前停服并备份安装目录和当前数据目录。更换 Node、npm prefix 或安装目录前先移除服务注册；不要在运行时删除应用包。
+
+```bash
+agent-task service remove             # 仅停止并移除服务注册
+agent-task uninstall                  # 再移除本安装拥有的 ACP 组件
+npm uninstall -g @realqiyan/agent-task # 最后由 npm 移除应用包
+```
+
+卸载可重复运行，保留配置、凭据、日志、任务历史、工作空间及未入清单文件，不操作全局执行端和原生认证。卸载不是凭据撤销或数据销毁，停服也不能回滚外部操作。实现见 [uninstall.mjs](../scripts/uninstall.mjs)。

package/docs/design-proposal.md

@@ -0,0 +1,55 @@
+# 智能任务总体方案
+
+本文保留产品目标和架构取舍。实现入口见[代码导航](technical-design.md)，实际证据见[验证说明](validation.md)。
+
+## 产品目标
+
+- 调用方通过 MCP 提交整体目标、DAG 和每节点的 ACP 执行端指派，支持立即、定时及周期执行。
+- 任务不依赖发起客户端持续在线，保留执行、交付、失败和缺少用户事实的记录。
+- 协调员推进既定 DAG、解释中间结果、处理澄清并组织交付；领域分析和工具操作交给执行端。
+- 缺少用户事实时可持久等待，回复后续接原运行，不丢失已接受工作。
+- 提供本机 Web 控制台，管理配置、查看任务，并只控制任务的未来触发；配置保存后通过 Web 或 CLI 重启生效，支持前台及托管服务；切换数据目录不搬迁或删除旧历史。
+
+Pi Agent、Codex、Claude、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 发布
+
+npm 包为 [@realqiyan/agent-task](https://www.npmjs.com/package/@realqiyan/agent-task)，发布账号 **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.2.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.2`）。包尚不存在时，应确认账号允许首次创建此名称；认证/权限失败须停止，不能换账号或跳过验证。
+
+发布命令明确传 `--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.2.tgz --ignore-scripts \
+  --access public --tag latest --registry=https://registry.npmjs.org
+npm view @realqiyan/agent-task@0.0.1-rc.2 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)、[launcher.ts](../src/launcher.ts)、[lock.ts](../src/lock.ts) | [restart.test.mjs](../tests/restart.test.mjs)、[service.test.mjs](../tests/service.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)、[executor-runtime.ts](../src/executor-runtime.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)、[startup.ts](../src/startup.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,108 @@
+# 验证导航与证据边界
+
+**三节点 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/请求类型边界、有限任务写入、密钥不回显或进入日志，以及 Web/CLI 重启后的配置差异和目录切换不复制历史。[重启用例](../tests/restart.test.mjs)验证前台 CLI、固定端口进程更换、绑定失败不能报成功，以及持久化的不确定派发在重复重启后仍被阻断。实际任务记录来自业务服务，不使用假模型输出。
+
+[配置用例](../tests/settings.test.mjs)验证私有文件边界、旧编辑拒绝、显式凭据环境、端点与密钥引用分离、服务令牌别名不能作为模型凭据、失败时保留文件，以及关闭后拒绝操作。这些用例不构成断电、磁盘满或目录同步失败窗口的完整证据。
+
+尚未完成真实浏览器交互、CSP 执行和跨浏览器缓存/自动填充验收。需在浏览器核对：不可信任务文本不执行脚本或加载外链；离开、刷新和退出后无令牌残留；配置草稿不被轮询覆盖；密钥保存与配置保存的提示明确。HTTP 头检查不能替代这些验证，也不证明模型认证或 ACP 执行成功。
+
+### 本次启动与注册调整
+
+Linux x64、Node 24.15.0：35 项基础测试、TypeScript 检查及 npm 包清单门禁通过。使用本次本地 tarball 执行 `node scripts/verify-install.mjs realqiyan-agent-task-0.0.1-rc.1.tgz --service`，前台和真实 systemd 用户服务的 Web/CLI 重启、认证健康检查、后台数据目录/端口/token 变量名切换及卸载保留数据均通过。未调用模型或启动 ACP 任务，未发现验证凭据进入捕获输出。报告：`/tmp/agent-task-npm-8kUj45/report.json`。
+
+本次尚未在 macOS 复验 launchd，历史 macOS 安装证据不代表新启动器已验收。四类执行端的固定命令映射和凭据过滤有本地契约测试；Claude 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 的 npm 安装、LaunchAgent 启停及卸载保留数据已在 GitHub macOS ARM64 runner 验证，见下文。原生认证与权限、真实任务、终端关闭/用户注销后的存续，以及执行端取消和进程清理仍未验收；CI 服务启动不能替代这些证据。
+
+## npm 发布候选验证
+
+2026-10-22，`realqiyan` 已将 **[@realqiyan/agent-task@0.0.1-rc.1](https://www.npmjs.com/package/@realqiyan/agent-task/v/0.0.1-rc.1)** 发布到 npmjs。匿名 registry 查询确认版本、发布账号、MIT 许可证及 `latest=0.0.1-rc.1`。本次经授权从本机发布，没有 GitHub provenance。包内文档是打包时快照，后续证据以[仓库中的最新记录](https://github.com/realqiyan/agent-task/blob/master/docs/validation.md#npm-发布候选验证)为准。
+
+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 先验收 scoped tarball，再从 npmjs 按 `npm install -g @realqiyan/agent-task` 的默认版本选择全局安装到独立临时 prefix；没有指定版本或使用本地 tarball 替代 registry 安装。禁用 lifecycle scripts，不使用项目源码或 TypeScript。前台启动、Web HTTP 配置保存/重启、真实 systemd 用户服务及带认证的健康检查均通过。
+- 重复 setup 保留 token；重复卸载保留配置、凭据、任务库和工作空间。显式注册的执行端仍未授权，没有 ACP 工作或模型调用。捕获的命令、前台输出及用户服务日志未出现验证用凭据，测试服务已移除。
+- tarball 预验收使用 npm 镜像依赖；发布后验收固定使用 `https://registry.npmjs.org/`，通过独立空 npm 配置文件进行匿名安装。复用 npm 下载缓存，没有复制项目 node_modules；不构成空缓存下载时延的保证。
+
+Linux 22.19.0 的发布后 registry 安装报告：`/tmp/agent-task-npm-uM8FT5/report.json`；scoped tarball 预验收报告：`/tmp/agent-task-npm-Zgkggc/report.json`。临时目录包含验证专用随机凭据和空业务库，不上传或打包；报告仅含结果。Node 22.19.0 会输出内置 SQLite 的 experimental warning，这不是认证错误。
+
+同日，[GitHub Validate 运行 39813423968](https://github.com/realqiyan/agent-task/actions/runs/39813423968)在提交 `461a1b0` 上全部通过：Node 22.19.0/24.x 检查、基础测试、构建及包清单门禁；Ubuntu x64 与 macOS ARM64 的 Node 22.19.0 安装任务均不 checkout 源码，使用 CI tarball 完成前台、Web HTTP 配置、真实 systemd/LaunchAgent、认证健康检查和卸载保留数据验收。报告确认输出无验证凭据，没有模型或 ACP 工作。macOS 的证据来自 hosted runner，不包括 Intel Mac、交互式终端/浏览器、休眠或用户注销场景。
+
+[受控发布工作流](../.github/workflows/publish.yml)已推送，但发布 Environment 审核和 npm 发布 secret 尚未配置，发布作业没有实际执行；本机首发和 Validate 通过不等于 Actions 发布已经验收。
+
+操作和发布条件见[部署说明](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,40 @@
+# 本机 Web 控制台
+
+控制台与 MCP 共用 HTTP 服务，只监听 `127.0.0.1`。访问 `http://127.0.0.1:<port>/admin/`，不要改用 LAN 地址、反向代理或公网转发。
+
+## 启用与连接
+
+新安装由 `agent-task setup`（[实现](../scripts/setup.mjs)）在当前 `dataDir/environment.json` 中生成独立的 `AGENT_TASK_ADMIN_TOKEN`。用本地编辑器读取该字段并在连接表单输入；它不是 MCP token，不能放进 URL、命令参数、截图或日志。
+
+已有文件不会由 setup 补写或覆盖。缺少管理员令牌时，管理接口关闭。需要启用时先停服，用本地密码管理器生成独立随机令牌，离线加入该字段；令牌约束见 [environment.ts](../src/environment.ts)。不要复用服务或模型密钥。
+
+前台和托管服务使用同一固定启动入口，见[部署说明](deployment.md)。配置和环境文件须属于当前用户、权限为 `0600`，所在目录须为规范绝对路径、权限为 `0700`，不接受符号链接。环境文件仅在运行进程启动时加载。文件格式见 [environment.ts](../src/environment.ts)。
+
+令牌仅保留在页面内存中；退出、离开或刷新后重新连接。不设置 Cookie，不写浏览器持久存储。配置和密钥文件仍是本地明文，须按凭据保护；此方案不隔离同一 OS 用户的其他进程或恶意浏览器扩展。
+
+## 操作范围
+
+- 任务列表、固定 DAG、运行历史、节点进度、已接受交付、错误和问题只读。触发计划结束不等于运行成功，原始输出不等于交付。
+- 任务写操作仅复用 `task_update`，暂停、恢复或取消未来触发。不停止当前运行，不补跑错过的触发，不回答问题或修改 DAG。
+- 数据目录、监听端口、MCP token 环境变量名、执行端注册和协调模型可编辑，下次启动生效。修改 token 变量名保留令牌值，不在页面回显。
+- 执行端只选择 pi、codex、claude 或 opencode，保留 ID、默认工作空间和无人值守审核，并可填写备注。启动方式由系统决定；原生认证和权限继续用官方工具管理。没有命令、参数、环境变量清单、结果目录或 ACP 工具白名单配置。
+
+页面与接口入口见 [web.ts](../src/web.ts)、[页面模块](../src/web/)，任务契约见 [task-contract.ts](../src/task-contract.ts)。提供受管理员认证保护的重启入口；没有通用 MCP 代理、文件浏览器或下载接口。固定结果目录不授予整个 dataDir 的读取能力。
+
+## 保存与重启
+
+1. 密钥只显示是否设置，原值不回显。不提交即保留；替换和删除必须明确操作。先保存新密钥，再保存引用它的配置。新凭据命名和受保护变量见 [settings.ts](../src/settings.ts)。
+2. 配置先校验并预览影响，再确认保存。校验不调用模型或启动 ACP，不能证明认证、原生权限或实际执行成功。修改执行端类型、ID 或工作空间后，页面要求重新明确批准无人值守执行；仅修改备注不改变授权。
+3. 配置与密钥分别原子替换，不是跨文件事务。更换模型端点须使用新的凭据引用，避免中途重启将新密钥交给旧端点。旧凭据不自动清理。
+4. 保存不热更新。检查活动运行及待回答运行后，点击“重启并检查可用性”或执行 `agent-task restart`；两者均支持前台和 systemd／launchd 托管实例。目录切换、原生环境来源及故障处理见[部署说明](deployment.md)。
+5. 只有新进程通过认证健康检查才显示成功。页面清除令牌并给出新地址，重新连接后核对运行配置。请求未确认时先用 CLI status 核查，不删除历史、自动回滚或重放执行来修复。
+
+待回答运行也可能持有 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.2",
+  "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 bin/agent-task.mjs start",
+    "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"
+  }
+}