@co0ontty/wand 4.94.0 → 4.95.0

package/skills/wand-system/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: wand-system
+description: 操作 Wand 工作台的系统能力：查询员工和工作区，创建员工会话，查看或续接指定历史会话，创建、查看、暂停和取消定时任务。用户要求延迟检查、两小时后复查、选择员工执行、异常时唤起原会话等自动化流程时使用。
+license: MIT
+compatibility: 本机 Wand 服务、Node.js、已安装的 wand-system skill，以及用户允许的命令执行权限。
+---
+
+# Wand 系统操作
+
+先读本技能的 `references/operations.md`，再执行。所有相对路径都相对此技能目录解析。
+调用入口（把占位路径替换为实际技能路径）：
+
+```sh
+node /absolute/path/to/wand-system/scripts/wand.mjs employee:list
+node /absolute/path/to/wand-system/scripts/wand.mjs workspace:list
+node /absolute/path/to/wand-system/scripts/wand.mjs session:current
+```
+
+助手记为下文的 **HELPER**。通过命令工具使用，不是要求用户自己运行。
+入口在安装时绑定本机 Wand CLI 和配置路径；运行时不需要读取、显示或传递密码。
+
+## 安全与真实性
+
+- 本技能不授予命令执行、管理权限、费用、删除、发布或操作系统权限；没有工具权限就说明限制，不绕过限制。
+- 这些命令复用本地所有者 CLI 的既有认证，不是“仅当前员工”的沙盒凭据。仅在已授权操作的本机 Wand 使用，不读其他员工知识、私聊或无关历史，不读取/打印配置文件、登录密码、token 或环境凭据。员工列表是公开定义，不是员工知识库。
+- 创建会话会在指定员工身份下执行，可能产生模型费用与真实副作用。按职责、可用候选、已有权限和费用约束选员工；不修改员工权限/模型，不静默改成付费候选。歧义时询问。
+- 以 API 返回的 ID、nextRunAt、revision、执行记录及检查证据为准。创建成功不等于执行完成，accepted 不等于检查通过；不靠状态文案关键词判断业务恢复。
+- 网络断开、超时、5xx/408/409、响应解析失败均可能已接受；不盲目重建计划或再次唤起。定时任务保留相同 requestId 查询核对；会话操作读取原 ID/消息后核对，无法确认就报告未知。
+- 仅支持当前 Wand 管理的结构化历史会话精确续接。不能拿 provider 原生 ID 替代 Wand ID，不能把新建空白会话说成恢复原会话。PTY 或已删除历史明确报告不支持/不可用。
+
+## 标准执行顺序
+
+1. 确认目标、授权、期望结果、工作区与时间；尽量从当前上下文获取，不重复追问已清楚的信息。
+2. 查询员工/工作区，使用稳定 ID；需要延迟唤起时先确定原会话 ID，并用 session:read 核对目录与身份。
+3. 按参考文档调用对应写操作，记录 requestId 和返回 ID。一次计划只创建一次。
+4. 回读结果，向用户简述执行员工、绝对执行时间/时区、检查标准和异常后的目标，不输出敏感信息。
+
+## 场景：两小时后检查，仍异常则恢复当前会话
+
+用户示例：“创建一次性定时任务，2h 后看看是不是正常了；不正常再把现在这个会话恢复。”
+
+这是 **检查任务 + 条件续接**，不是延迟无条件重放旧消息。
+
+- 先获得当前 Wand 会话 ID（session:current 或可信当前会话上下文）；不按最新一条/标题/时间推断。把 ID 固定写入计划提示词，未来检查会话自己的 session:current 不是原会话。
+- 从本轮问题明确“正常”的客观标准与可执行只读检查（目标服务、API、日志/测试入口、预期值）。没有这些信息时只问缺项，不编造。
+- 以当前时间加两小时生成带时区的 ISO runAt，使用 kind=once；明确主机及 Wand 服务需要运行。禁止 shell sleep、crontab 或新建另一个服务代替 Wand 调度。
+- 选择适合诊断且具有所需工具权限的员工。把原会话、工作区、检查步骤、通过标准、异常分支、证据及授权范围完整写入 prompt，不依赖未来员工记得今天的对话。
+- 检查正常：留下证据与结论后结束，不唤起原会话。
+- 有明确证据仍异常：先读取固定原会话，确认没有正在执行、排队或审批阻塞；执行一次 session:resume，input 包含计划 ID/检查证据/原问题/明确的继续要求。此操作沿用原会话身份和上下文；检查员工不会冒用原员工。
+- 无法检查、权限不足、状态未知或原会话忙：如实报告，不把“查不到”当作异常并发新一轮；除非用户明确授权将这种情况也作为续接条件。检查器自身崩溃或无法启动时，单靠 prompt 不能保证补偿唤起，须报告定时执行失败，不声称有服务端自动 on-failure 钩子。
+- 原会话接受续接后，回读状态并结束本次检查；不循环唤起、不另建重复计划、不擅自停止它或扩大修复范围。
+
+计划 prompt 可按下列结构填写（替换所有占位信息）：
+
+```text
+这是一次性复查，不是重复执行原始工作。
+原 Wand 会话 ID：<固定ID>；工作区：<workspaceId与目录>。
+原问题：<问题与已做修改>。
+只读检查：<准确步骤/目标>。
+正常标准：<可核实的预期结果>。
+正常则保留检查证据后结束。
+明确仍异常才读取上述固定会话；若空闲且无审批/队列，
+使用 wand-system 的 session:resume 续接一次，
+输入“这是<计划标识>的两小时复查。检查证据：…；仍异常，请沿用本会话历史继续处理<授权范围>。”
+如无法检查、原会话忙/不存在或请求结果未知，报告阻塞，不重复提交。
+不修改权限、发布、删除数据或创建更多计划。
+```
+
+具体 JSON 和命令见 `references/operations.md`。

package/skills/wand-system/references/operations.md

@@ -0,0 +1,100 @@
+# 操作契约
+
+以下 HELPER 表示 `node <此技能绝对路径>/scripts/wand.mjs`，不是字面命令。
+所有输出是 JSON，失败退出非零；所有写入用 `--stdin` 输入 JSON 对象，不把用户文字拼成可执行 shell。
+替换示例 ID、日期与检查内容；示例本身不是执行授权。
+
+## 查询与选择
+
+| 命令 | 返回 / 语义 |
+| --- | --- |
+| HELPER employee:list | {employees:[…]}，默认不含归档员工；按 id/name/duty/agents 选适合员工，不读取知识 |
+| HELPER employee:list --include-archived | 含归档定义，归档员工不能创建执行 |
+| HELPER workspace:list | 工作区数组；核对 id/name/cwd，不使用猜测目录 |
+| HELPER session:current | 当前执行环境绑定的 {sessionId}，非凭据；未绑定会报错 |
+| HELPER session:list | 会话列表，可能含其他任务，只定位已授权目标 |
+| HELPER session:read <wand-session-id> | 指定会话详情/消息，核对 sessionKind/employeeId/cwd/status/structuredState/queuedMessages |
+| HELPER session:wait <id> --timeout 900 | 有界等待；不将空闲等同业务成功，仍需核对最后一轮结果 |
+| HELPER schedule:list | {tasks:[…]}，不含已取消 |
+| HELPER schedule:list --include-cancelled | 包含取消记录 |
+| HELPER schedule:read <id> | {task,runs}，最近50条执行含 sessionId、接收及实际执行状态 |
+
+## 创建员工会话
+
+```sh
+HELPER session:create --stdin <<'JSON'
+{"employeeId":"e_实际员工ID","workspaceId":"实际项目ID","cwd":"/实际项目绝对目录","prompt":"已获授权的明确任务"}
+JSON
+```
+
+返回会话快照，记录 id。使用员工保存的角色、候选、引擎与权限；不能通过此命令覆盖模型或 mode。
+省略 prompt 只创建空白会话，不启动业务；有 prompt 则立即接受执行，不等待整轮结束。
+cwd 与 workspaceId 应来自同一真实工作区；省略 cwd 时会使用服务默认目录，不要误以为 workspaceId 自动切目录。
+创建会话接口不承诺幂等；未知送达先查列表/历史，不直接重建。
+
+## 续接指定结构化历史会话
+
+```sh
+HELPER session:resume 原Wand会话ID --stdin <<'JSON'
+{"input":"两小时复查证据：<具体结果>。仍不符合<标准>，请沿用本会话已有历史继续处理<已授权范围>。"}
+JSON
+```
+
+不是 PTY resume，也不创建另一个新会话。命令先回读目标，只接受精确 ID 的结构化会话；
+目标运行中、等待审批或有排队消息时拒绝，不停止、不插队。已归档的空闲结构化会话先取消归档，再经原输入入口继续。
+沿用原身份、历史与 provider 恢复机制；历史文件缺失等错误可能在启动后出现，响应仅证明接受，回读核对。
+没有跨请求事务/永久幂等保证，不用此命令做并发锁；已接受、超时或结果未知后不盲目重复。
+
+## 创建定时任务
+
+```sh
+HELPER schedule:create --stdin <<'JSON'
+{
+  "requestId":"check-20300101-100000-a1",
+  "title":"两小时后复查异常",
+  "employeeId":"e_实际检查员工ID",
+  "workspaceId":"实际项目ID",
+  "prompt":"完整复查步骤、正常标准、固定原会话ID、正常/异常/未知分支与授权范围",
+  "schedule":{"kind":"once","runAt":"2030-01-01T18:00:00+08:00"}
+}
+JSON
+```
+
+requestId 必须为8–80位 ASCII 字母/数字/下划线/冒号/连字符；每项新计划使用唯一标识（可用 UUID），相同请求保留原值。
+runAt 必须在未来并带明确时区。两小时后用当前时间加 2*60*60*1000 算出真实 ISO，不照抄示例。
+返回 {task}，记录 task.id、revision、nextRunAt；回读 schedule:read 核实。
+同一 requestId + 原始内容幂等；同 ID 换内容会409。若响应丢失，按同 requestId 推导/查询原任务而不是换 ID。
+任务ID推导：`sched_` + SHA-256(requestId) 的前32位十六进制。可用本机 Node crypto 计算后 schedule:read 核对原始字段。
+requestId 并非认证凭据，但不要把用户隐私塞进标识。
+
+重复计划：
+- 每天：`{"kind":"daily","time":"09:00","timeZone":"Asia/Shanghai"}`
+- 每周：`{"kind":"weekly","time":"09:00","timeZone":"Asia/Shanghai","weekday":1}`（0周日…6周六）
+- 用户只要求一次检查时绝不能擅自改成每天/每周。
+
+绑定 workspaceId 后每次在该项目当时的目录执行，不可用就失败，不退到其他目录。
+未绑定项目则使用服务默认目录，交付须说明。到点新建检查员工执行会话，原会话仅在满足条件时由检查员工续接。
+关闭浏览器不影响调度；主机/服务必须运行，默认约15秒检查一次，不能承诺准确到秒。
+服务恢复时过期单次任务补跑一次；同计划未结束不并发重跑；未知接收不自动重发。
+
+## 更新、暂停、恢复、取消计划
+
+先 schedule:read 获取当前 revision，不能覆盖别人更新。
+
+```sh
+HELPER schedule:update 实际计划ID --stdin <<'JSON'
+{"revision":1,"enabled":false}
+JSON
+```
+
+- 恢复：`{"revision":2,"enabled":true}`。已过期单次需同时提供新的未来 schedule。
+- 改时间/员工/提示词/项目：revision 加对应字段；其他字段保留。
+- 取消：`{"revision":3,"cancelled":true}`；只在用户要求取消时执行。
+- 409先重新读取，不盲目覆盖；取消后不能恢复，历史保留。
+- 暂停/取消只阻止未来调度，不中断已开始的检查或原会话。
+
+## 无法执行时
+
+不读管理员密码、不改员工配置、不换引擎、不改系统定时器、不自动重启 Wand。
+提示 skill 未安装时由已授权的本机 CLI 执行 `wand system:skills`；安装只增加发现入口，不改变任何会话的工具开关或 Skills 白名单。
+新会话/资源刷新后可发现；被显式限定资源的会话需用户在原设置里选择该技能，不能绕过选择。

package/skills/wand-system/scripts/wand.mjs

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+
+const args = process.argv.slice(2);
+const allowed = new Set([
+  "employee:list", "workspace:list", "session:current", "session:list", "session:read",
+  "session:create", "session:resume", "session:wait", "schedule:list", "schedule:read",
+  "schedule:create", "schedule:update",
+]);
+try {
+  if (!allowed.has(args[0]) || args.some(arg => ["--config", "-c"].includes(arg))) {
+    throw new Error("仅支持 wand-system 文档列出的操作，不能覆盖绑定的配置。");
+  }
+  if (args[0] === "session:current") {
+    if (args.length !== 1 || !process.env.WAND_SESSION_ID) throw new Error("当前执行环境未绑定会话 ID；请从 Wand 当前会话详情取得精确 ID，不按标题猜测。");
+    process.stdout.write(JSON.stringify({ sessionId: process.env.WAND_SESSION_ID }) + "\n");
+  } else {
+    const runtime = JSON.parse(await readFile(new URL("../.runtime.json", import.meta.url), "utf8"));
+    if (![runtime.node, runtime.cli, runtime.config].every(value => typeof value === "string" && isAbsolute(value))) {
+      throw new Error("技能运行路径无效，请用可信 Wand CLI 重新运行 system:skills。");
+    }
+    const child = spawn(runtime.node, [
+      ...(runtime.loader ? ["--import", runtime.loader] : []),
+      runtime.cli, ...args, "--config", runtime.config,
+    ], { stdio: "inherit" });
+    child.on("error", () => { process.stderr.write("wand-system: CLI 无法启动，请重新安装技能。\n"); process.exitCode = 1; });
+    child.on("exit", (code, signal) => { process.exitCode = code ?? (signal ? 1 : 0); });
+    for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => child.kill(signal));
+  }
+} catch (error) {
+  process.stderr.write(`wand-system: ${error.code === "ENOENT" ? "请先运行 wand system:skills 安装技能。" : error.message}\n`);
+  process.exitCode = 1;
+}