pactive 0.0.2-alpha.1 → 0.0.3-alpha.1

package/README.md

@@ -44,7 +44,8 @@ pactive dsh                             # dsh --profile pactive（只写 pactive
   `pi.skills` → `pi/skills/pactive`）；`pi install pactive` 依赖该字段。
 - 宿主退出码 / 信号原样透传（信号 → 128+n）。
 - **stdout 纯净**：Pactive 自身的回执、诊断、进度一律走 stderr，
-  stdout 只承载被启动宿主的输出，以及 `--print-plan` / `doctor --json` 的机器可读结果。
+  stdout 只承载被启动宿主的输出，以及显式请求的机器可读结果（`--print-plan`、
+  `doctor --json`、`config/tasks --json`、`--help`——`--help | head -8` 要可 grep）。
 
 ### 2.2 其它子命令
 
@@ -55,6 +56,11 @@ pactive dsh                             # dsh --profile pactive（只写 pactive
 | `pactive --print-plan <host>` | 打印注入计划 JSON（零写盘） | 0（未知宿主 2） |
 | `pactive doctor [--json]` | 宿主 / 版本 / 注入模式 / 状态根 / 权限 / 残留 | 0（有 FAIL 段则 1） |
 | `pactive install <host>` / `pactive uninstall <host>` | 幂等安装 / 卸载 | 0（有残留则 1） |
+| `pactive config get [<key>] [--json]` | 只读：当前值与默认值（白名单 7 个 key） | 0（未知 key 2） |
+| `pactive config set <key> <value> --confirm` | 写配置；**缺 `--confirm` 就零写盘** | 0（缺 confirm 2、未知 key 2、值非法 2） |
+| `pactive schedule "<prompt>" --when <when>` | 登记定时任务（`10m` / `18:30` / ISO / `every 1h`） | 0（when 无法解析 2） |
+| `pactive tasks [--json]` | 列出任务：id / 类型 / 下次到期 / 归属 / 正文 | 0 |
+| `pactive cancel <taskId>` | 取消一条任务 | 0（未知 id 1） |
 | `pactive <未知宿主>` | 列出 pi / opcteam / dsh 到 stderr | 2 |
 | 宿主二进制缺失 | 提示安装 + `PACTIVE_<HOST>_BIN` 覆盖 | 127 |
 

package/bin/pactive.mjs

@@ -18,13 +18,24 @@ const PKG_ROOT = path.resolve(CLI_DIR, '..');
 const FALLBACK_VERSION = '0.0.2-alpha.1';
 const STALE_LOCK_MS = 30 * 60 * 1000;
 
-function usage(io) {
-  io.write(`pactive — proactive companion for Pi / OPCteam / DSH
+function usage(out) {
+  out.write(`pactive — 主动助手：默认全部用自然语言操作，命令只是"可复制的一行"
 
-Usage:
+你可以直接对助手说：
+  「我现在闲不闲？」                      → 看空闲判定与 reason
+  「10 分钟后提醒我喝水」                 → 登记定时任务
+  「主动提醒开启了吗？」                  → 看开关状态
+  「帮我开启主动提醒」                    → 给出可复制命令（人工确认后才生效）
+
+命令（高级/运维）：
   pactive <host> [args...]        run a host with pactive injected (stdio inherited)
   pactive --print-plan <host>     print the launch plan as JSON (no side effects)
   pactive doctor [--json]         diagnose hosts, state root and permissions (read-only)
+  pactive config get [<key>]      print current values and defaults (read-only)
+  pactive config set <key> <value> --confirm   write one config key (human gate)
+  pactive schedule "<prompt>" --when <when>    register a timed task (10m / 18:30 / ISO / every 1h)
+  pactive tasks [--json]          list scheduled tasks (id / kind / due / owner)
+  pactive cancel <taskId>         cancel one task
   pactive install <host>          register pactive with a host (idempotent)
   pactive uninstall <host>        unregister pactive and remove pactive state residue
   pactive --version | -v          print the pactive version
@@ -222,6 +233,268 @@ async function doctorReport(env) {
   };
 }
 
+// ─────────────────── 自然语言面向的子命令（契约 §2.1 / I57–I60） ───────────────────
+//
+// 这里是**唯一的人工闸门**：写配置必须显式 --confirm，缺了就 exit 2 且零写盘。
+// stdout 只放 --json，人类可读文本一律走 stderr（沿用 I37）。
+
+const CONFIRM_REFUSAL = 'pactive: refusing to write without --confirm (human gate)';
+const HOST_KIND = 'pi'; // the state root is host-agnostic; 'pi' keeps doctor/CLI on one spelling.
+function parseDurationMs(text) {
+  const m = /^(\d+)\s*(s|sec|secs|m|min|mins|h|hour|hours|d|day|days)$/i.exec(String(text ?? '').trim());
+  if (!m) return null;
+  const unit = m[2].toLowerCase();
+  const factor = unit.startsWith('s') ? 1000 : unit.startsWith('m') ? 60000 : unit.startsWith('h') ? 3600000 : 86400000;
+  return Number(m[1]) * factor;
+}
+
+/** `10m` / `18:30` / ISO 8601 / `every 1h` → a spec that `core.schedule.add` accepts directly. */
+function parseWhen(when, now = Date.now()) {
+  const text = String(when ?? '').trim();
+  if (text === '') return { kind: 'in', when: '10m', delayMs: 10 * 60000 };
+  const every = /^every\s+(.+)$/i.exec(text);
+  if (every) {
+    const everyMs = parseDurationMs(every[1]);
+    if (everyMs === null || everyMs <= 0) return null;
+    return { kind: 'every', when: text, everyMs };
+  }
+  const delayMs = parseDurationMs(text);
+  if (delayMs !== null) return { kind: 'in', when: text, delayMs };
+  const clock = /^(\d{1,2}):(\d{2})$/.exec(text);
+  if (clock) {
+    const at = new Date(now);
+    at.setHours(Number(clock[1]), Number(clock[2]), 0, 0);
+    if (at.getTime() <= now) at.setDate(at.getDate() + 1);
+    return { kind: 'at', when: text, at: at.getTime() };
+  }
+  const iso = Date.parse(text);
+  if (!Number.isNaN(iso)) return { kind: 'at', when: text, at: iso };
+  return null;
+}
+
+/** Pull `--name <value>` / `--name=<value>` out of args. */
+function takeOption(args, name) {
+  const rest = [];
+  let value = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === name) {
+      value = args[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith(`${name}=`)) {
+      value = arg.slice(name.length + 1);
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { value, args: rest };
+}
+
+/** JSON on stdout, human lines on stderr — never both for the same payload. */
+function emit(io, asJson, payload, humanLines) {
+  if (asJson) io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else for (const line of humanLines) io.stderr.write(`${line}\n`);
+  return 0;
+}
+
+function configKeys(core) {
+  const described = core.config.describe();
+  return { described, keys: Object.keys(described.defaults) };
+}
+
+function coerceValue(spec, raw) {
+  const text = String(raw).trim();
+  if (spec.type === 'boolean') {
+    if (text === 'true') return { ok: true, value: true };
+    if (text === 'false') return { ok: true, value: false };
+    return { ok: false, reason: 'expected true|false' };
+  }
+  if (spec.type === 'number') {
+    const n = Number(text);
+    if (text === '' || !Number.isFinite(n)) return { ok: false, reason: 'expected a number' };
+    if (typeof spec.min === 'number' && n < spec.min) return { ok: false, reason: `expected >= ${spec.min}` };
+    return { ok: true, value: n };
+  }
+  if (spec.type === 'string|null') {
+    if (text === '' || text.toLowerCase() === 'null' || text.toLowerCase() === 'none') return { ok: true, value: null };
+    return { ok: true, value: text };
+  }
+  return { ok: false, reason: `unsupported type ${spec.type}` };
+}
+
+async function configGetCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const keys = args.filter((a) => a !== '--json');
+  const core = await loadCore();
+  const { described, keys: known } = configKeys(core);
+  if (keys.length > 1) {
+    io.stderr.write('pactive: usage: pactive config get [<key>] [--json]\n');
+    return 2;
+  }
+  const key = keys[0];
+  if (key !== undefined && !known.includes(key)) {
+    io.stderr.write(`pactive: unknown config key '${key}'\npactive: known keys: ${known.join(', ')}\n`);
+    return 2;
+  }
+  const state = core.loadState(core.resolvePaths(HOST_KIND, env));
+  const targets = key === undefined ? known : [key];
+  const values = targets.map((k) => ({
+    key: k,
+    value: core.config.get(state, k),
+    default: described.defaults[k],
+    humanGated: described.schema[k].humanGated === true,
+  }));
+  const payload = key === undefined ? { values } : values[0];
+  // Single key → the bare value on its own line (so `config get idle.enabled | grep -qx false` works),
+  // then the default; the full key list keeps one "key = value" line each.
+  const human = key === undefined
+    ? values.map(
+      (v) => `${v.key} = ${JSON.stringify(v.value)}${JSON.stringify(v.value) === JSON.stringify(v.default) ? ' (default)' : ''}`,
+    )
+    : [`${JSON.stringify(values[0].value)}`, `${key} (default: ${JSON.stringify(values[0].default)})`];
+  return emit(io, asJson, payload, human);
+}
+
+async function configSetCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const rest = args.filter((a) => a !== '--json' && a !== '--confirm');
+  const [key, raw] = rest;
+  const core = await loadCore();
+  const { described, keys: known } = configKeys(core);
+
+  // Validity first (a usage error must not read as "gate refused"), then the gate.
+  if (key === undefined || raw === undefined || rest.length > 2) {
+    io.stderr.write('pactive: usage: pactive config set <key> <value> --confirm\n');
+    return 2;
+  }
+  if (!known.includes(key)) {
+    io.stderr.write(`pactive: unknown config key '${key}'\npactive: known keys: ${known.join(', ')}\n`);
+    return 2;
+  }
+  if (!confirm) {
+    io.stderr.write(`${CONFIRM_REFUSAL}\n`);
+    io.stderr.write(`pactive: re-run with --confirm: pactive config set ${key} ${raw} --confirm\n`);
+    return 2;
+  }
+  const coerced = coerceValue(described.schema[key], raw);
+  if (!coerced.ok) {
+    io.stderr.write(`pactive: invalid value for ${key}: ${coerced.reason}\n`);
+    return 2;
+  }
+
+  const paths = core.resolvePaths(HOST_KIND, env);
+  let applied = null;
+  await core.mutateState(paths, (state) => {
+    applied = core.config.setHumanGated(state, key, coerced.value, { confirm: true });
+    if (!applied.ok) throw new PactiveError(`config refused: ${applied.reason}`, { code: 'CONFIG_REFUSED', exitCode: 1 });
+    return state;
+  });
+  return emit(
+    io,
+    asJson,
+    { ok: true, key, value: coerced.value, stateFile: paths.stateFile },
+    [`${key} = ${JSON.stringify(coerced.value)}`, `pactive: wrote ${paths.stateFile}`],
+  );
+}
+
+async function scheduleCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const taken = takeOption(args.filter((a) => a !== '--json' && a !== '--confirm'), '--when');
+  const prompt = taken.args.join(' ').trim();
+  if (prompt === '') {
+    io.stderr.write('pactive: usage: pactive schedule "<prompt>" --when <when> [--confirm]\n');
+    return 2;
+  }
+  const now = Date.now();
+  const spec = parseWhen(taken.value ?? '10m', now);
+  if (!spec) {
+    io.stderr.write(`pactive: cannot parse --when '${taken.value}' (try 10m / 18:30 / ISO 8601 / every 1h)\n`);
+    return 2;
+  }
+  const core = await loadCore();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const next = await core.mutateState(paths, (state) => {
+    core.schedule.add(state, { ...spec, prompt, content: prompt, owner: state.identity?.agentId }, now);
+    return state;
+  });
+  const list = core.schedule.list(next);
+  const created = list[list.length - 1] ?? null;
+  return emit(
+    io,
+    asJson,
+    {
+      ok: true,
+      confirmed: confirm,
+      taskId: created?.id ?? null,
+      dueAt: created?.dueAt ?? null,
+      kind: spec.kind,
+      when: spec.when,
+      tasks: list.length,
+    },
+    [
+      `pactive: registered ${created?.id ?? '?'} (${spec.when} → ${new Date(created?.dueAt ?? now).toISOString()})`,
+      `prompt: ${prompt}`,
+    ],
+  );
+}
+
+async function tasksCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const core = await loadCore();
+  const state = core.loadState(core.resolvePaths(HOST_KIND, env));
+  const list = core.schedule.list(state);
+  const rows = list.map((t) => ({
+    id: t.id,
+    kind: t.kind,
+    dueAt: t.dueAt,
+    due: new Date(t.dueAt).toISOString(),
+    owner: t.owner ?? '',
+    active: t.active !== false,
+    prompt: t.prompt ?? '',
+  }));
+  return emit(
+    io,
+    asJson,
+    { count: rows.length, tasks: rows },
+    rows.length === 0
+      ? ['pactive: no scheduled tasks']
+      : rows.map(
+        (r) => `[${r.id}] ${r.kind} ${r.due} owner=${r.owner || '-'} ${r.active ? 'active' : 'inactive'}${r.prompt ? ` — ${r.prompt}` : ''}`,
+      ),
+  );
+}
+
+async function cancelCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  const confirm = args.includes('--confirm');
+  const id = args.filter((a) => a !== '--json' && a !== '--confirm')[0];
+  if (id === undefined) {
+    io.stderr.write('pactive: usage: pactive cancel <taskId> [--confirm]\n');
+    return 2;
+  }
+  const core = await loadCore();
+  const paths = core.resolvePaths(HOST_KIND, env);
+  const before = core.schedule.list(core.loadState(paths));
+  if (!before.some((t) => t.id === id)) {
+    io.stderr.write(`pactive: unknown task id '${id}'\n`);
+    return 1;
+  }
+  const next = await core.mutateState(paths, (state) => {
+    core.schedule.cancel(state, id);
+    return state;
+  });
+  return emit(
+    io,
+    asJson,
+    { ok: true, confirmed: confirm, cancelled: id, tasks: core.schedule.list(next).length },
+    [`pactive: cancelled ${id} (${core.schedule.list(next).length} left)`],
+  );
+}
+
 function printPlan(args, env, io) {
   const host = args[0];
   if (!host) {
@@ -396,12 +669,20 @@ export async function main(argv, env = process.env, io = { stdout: process.stdou
       return 0;
     case '--help':
     case '-h':
-      usage(io.stderr);
+      // Explicit help goes to stdout: it is the requested output, not host noise
+      // (I37 protects the stdout of a *spawned host*; `--help | head -8` must be greppable).
+      usage(io.stdout);
       return 0;
     case '--print-plan':
       return printPlan(rest, env, io);
     case 'doctor':
       return doctorCmd(rest, env, io);
+    case 'config':
+      return rest[0] === 'set' ? configSetCmd(rest.slice(1), env, io) : configGetCmd(rest[0] === 'get' ? rest.slice(1) : rest, env, io);
+    case 'schedule':
+    case 'tasks':
+    case 'cancel':
+      return { schedule: scheduleCmd, tasks: tasksCmd, cancel: cancelCmd }[cmd](rest, env, io);
     case 'install':
       return installCmd(rest, env, io, 'install');
     case 'uninstall':

package/commands/pactive.md

@@ -22,6 +22,7 @@ mcp__plugin_pactive_pactive__<tool>
 - `mcp__plugin_pactive_pactive__pactive_schedule`
 - `mcp__plugin_pactive_pactive__pactive_tell`
 - `mcp__plugin_pactive_pactive__pactive_history`
+- `mcp__plugin_pactive_pactive__pactive_config`（只读；要改配置时只返回可复制命令）
 
 裸名（`pactive_status`）不一定能被 ToolSearch 发现；若命名空间工具没加载，用
 `select:mcp__plugin_pactive_pactive__pactive_status` 搜一次。
@@ -36,11 +37,13 @@ mcp__plugin_pactive_pactive__<tool>
 | 每小时 | `pactive_schedule` `when:"every 1h"` |
 | 告诉另一个会话 | `pactive_tell` `to` `body`（可选 `kind:"ask"`） |
 | 最近发生过什么 | `pactive_history` `limit` |
+| 开关 / 阈值 / 安静时间是多少 | `pactive_config` `key`（只读，报当前值与默认值） |
+| 帮我开启主动提醒 / 改阈值 | `pactive_config` `key` `value` → 只拿到 `pactive config set … --confirm`，交给用户执行 |
 
 ## 硬规则
 
 1. **不要替用户改配置**：pactive 的开关与配置是人工闸门（CLI `--confirm`）。用户要求改配置时，
-   告诉他用 `pactive config set … --confirm`，不要自行绕过。
+   告诉他用 `pactive config set … --confirm`，不要自行绕过；用户执行后下一轮用 `pactive_status` 复核。
 2. **回执如实转述**：`queued` 就是**还没送到**（对端离线），不要说成已送达。
 3. **默认不打扰**：空闲触发默认关闭；用户没明确要「空闲自动推进」时，不要假设它已开启。
 4. **只报新事实**：状态类输出要给出 `idle.reason` 与护栏结论，不要泛泛说「一切正常」。

package/dsh/index.js

@@ -66,6 +66,14 @@ async function markControlReturned(ctx) {
 }
 
 const STATUS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const CONFIG_PARAMETERS = {
+  type: "object",
+  properties: {
+    key: { type: "string", description: "配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.*）" },
+    value: { type: "string", description: "想改成的新值；给了就只返回 `pactive config set <key> <value> --confirm`，不落盘" },
+  },
+  additionalProperties: false,
+};
 const SCHEDULE_PARAMETERS = {
   type: "object",
   properties: {
@@ -89,7 +97,8 @@ export function apply(ctx, config) {
     ctx.tools.register({
       name: "pactive_status",
       description:
-        "Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+        "当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」时用。" +
+        "→ 读当前空闲判定、reason、护栏四闸门、任务数与最近活动。只读，不落盘。",
       parameters: STATUS_PARAMETERS,
       async execute(args = {}) {
         try {
@@ -121,7 +130,10 @@ export function apply(ctx, config) {
 
     ctx.tools.register({
       name: "pactive_schedule",
-      description: "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+      description:
+        "当用户说「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」时用。" +
+        "→ 登记一条定时任务并立即落盘；when 支持 10m / 18:30 / ISO 8601 / every 1h。" +
+        "会写盘，需要人工确认（只在用户明确要求时调用）。",
       parameters: SCHEDULE_PARAMETERS,
       async execute(args = {}) {
         try {
@@ -155,6 +167,46 @@ export function apply(ctx, config) {
         }
       },
     });
+
+    // Read-only by construction: a write request returns the command, never a write (contract §2.3).
+    ctx.tools.register({
+      name: "pactive_config",
+      description:
+        "当用户问「主动提醒的开关开着吗」「阈值是多少」「安静时间是几点」「帮我把主动提醒打开」时用。" +
+        "→ 读配置值与默认值；要改配置时只返回一条需要人工确认的可复制命令。只读，不落盘。",
+      parameters: CONFIG_PARAMETERS,
+      async execute(args = {}) {
+        try {
+          const core = await loadCore();
+          const described = core.config?.describe ? core.config.describe() : { schema: {}, defaults: {} };
+          const known = Object.keys(described.defaults);
+          const key = typeof args.key === "string" ? args.key.trim() : "";
+          const rawValue = args.value === undefined || args.value === null ? "" : String(args.value).trim();
+          if (key !== "" && !known.includes(key)) {
+            return { ok: false, error: `未知配置键（${key}）；已知：${known.join(", ")}` };
+          }
+          const paths = core.resolvePaths(HOST_KIND, process.env);
+          const state = (await readState(core, paths)) ?? core.defaultState();
+          const values = (key === "" ? known : [key]).map((k) => ({
+            key: k,
+            value: core.config?.get ? core.config.get(state, k) : null,
+            default: described.defaults[k] ?? null,
+            humanGated: described.schema?.[k]?.humanGated === true,
+          }));
+          if (rawValue === "") return { ok: true, readOnly: true, wrote: false, values };
+          return {
+            ok: false,
+            wrote: false,
+            reason: "need_human_confirmation",
+            command: `pactive config set ${key} ${rawValue} --confirm`,
+            hint: "不要自己改状态文件；把 command 原样给用户，等他执行后下一轮用 pactive_status 复核。",
+            values,
+          };
+        } catch (err) {
+          return { ok: false, error: errorText(err) };
+        }
+      },
+    });
   };
 
   const registerCommands = () => {

package/mcp/tools/definitions.mjs

@@ -35,13 +35,29 @@ export const TOOL_DEFINITIONS = [
   {
     name: "pactive_status",
     description:
-      "Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+      "当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」时用。" +
+      "→ 读当前空闲判定、reason、护栏四闸门、任务数与最近活动。只读，不落盘。",
     inputSchema: obj({}, []),
   },
+  {
+    name: "pactive_config",
+    description:
+      "当用户问「主动提醒的开关开着吗」「阈值是多少」「安静时间是几点」「帮我把主动提醒打开」时用。" +
+      "→ 读配置值与默认值；要改配置时只返回一条需要人工确认的可复制命令。只读，不落盘。",
+    inputSchema: obj(
+      {
+        key: str("配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.*）"),
+        value: str("想改成的新值；给了就只返回 `pactive config set <key> <value> --confirm`，不落盘"),
+      },
+      [],
+    ),
+  },
   {
     name: "pactive_schedule",
     description:
-      "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+      "当用户说「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」时用。" +
+      "→ 登记一条定时任务并立即落盘；when 支持 10m / 18:30 / ISO 8601 / every 1h。" +
+      "会写盘，需要人工确认（只在用户明确要求时调用）。",
     inputSchema: obj(
       {
         prompt: str("任务正文（到点注入给会话的内容）"),
@@ -53,7 +69,9 @@ export const TOOL_DEFINITIONS = [
   {
     name: "pactive_tell",
     description:
-      "给同机另一个会话投递一条消息。对端离线时进入 outbox 排队，不伪装成功。",
+      "当用户说「告诉另一个会话我有空」「问一下隔壁 agent 跑完了吗」时用。" +
+      "→ 给同机另一个会话投递消息；对端离线时进入 outbox 排队，不伪装成功。" +
+      "会写盘，需要人工确认（只在用户明确要求时调用）。",
     inputSchema: obj(
       {
         to: str("目标会话的 agentId 或名字"),
@@ -65,7 +83,9 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: "pactive_history",
-    description: "读取 Pactive 事件账本尾部（触发→投递→回应→结账），用于追溯主动行为。",
+    description:
+      "当用户问「刚才那几次主动提醒都发生了什么」「有没有真的触发过」时用。" +
+      "→ 读事件账本尾部（触发→投递→回应→结账）。只读。",
     inputSchema: obj({ limit: { type: "integer", description: "返回条数，默认 20" } }, []),
   },
 ];
@@ -117,6 +137,37 @@ export async function runTool(name, args = {}, options = {}) {
         });
       }
 
+      case "pactive_config": {
+        // Read-only. A write request never lands: the model gets a copy-pasteable command
+        // whose --confirm only a human can type (contract §2.3 / I59).
+        const described = core.config?.describe ? core.config.describe() : { schema: {}, defaults: {}, humanGatedKeys: [] };
+        const known = Object.keys(described.defaults);
+        const key = typeof args.key === "string" ? args.key.trim() : "";
+        const rawValue = args.value === undefined || args.value === null ? "" : String(args.value).trim();
+        if (key !== "" && !known.includes(key)) {
+          return json(`ERROR INVALID_ARGUMENT: 未知配置键（${key}）；已知：${known.join(", ")}`, true);
+        }
+        const state = (await readState(core, paths)) ?? core.defaultState();
+        const values = (key === "" ? known : [key]).map((k) => ({
+          key: k,
+          value: core.config?.get ? core.config.get(state, k) : null,
+          default: described.defaults[k] ?? null,
+          humanGated: described.schema?.[k]?.humanGated === true,
+        }));
+        if (rawValue === "") {
+          return json({ ok: true, readOnly: true, wrote: false, values, stateFile: paths.stateFile });
+        }
+        return json({
+          ok: false,
+          readOnly: false,
+          wrote: false,
+          reason: "need_human_confirmation",
+          command: `pactive config set ${key} ${rawValue} --confirm`,
+          hint: "不要自己改状态文件；把 command 原样给用户，等他执行后下一轮用 pactive_status 复核。",
+          values,
+        });
+      }
+
       case "pactive_schedule": {
         const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
         if (prompt === "") return json("ERROR INVALID_ARGUMENT: prompt 必填", true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pactive",
-  "version": "0.0.2-alpha.1",
+  "version": "0.0.3-alpha.1",
   "description": "Pactive：跨 Pi / OPCteam / DSH 的主动能力运行时（idle 判定默认关闭、人工闸门、事件账本）。专有软件：使用条款见包内 LICENSE（发行物含 Pi 扩展源码 pi/extension.ts）。",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/pi/extension.ts

@@ -2,7 +2,8 @@
  * Pactive — Pi extension (the single shipped entry (Pi loads this .ts directly via jiti; there is no dist copy)).
  *
  * Surface:
- *   - tools: `pactive_status`, `pactive_schedule`
+ *   - tools: `pactive_status`, `pactive_schedule`, `pactive_config` (read-only: proposes a
+ *     `pactive config set … --confirm` command instead of writing — contract §2.3 / I59)
  *   - command: `/pactive status|tasks|schedule <when> <prompt>|help`
  *   - events: session_start / input / agent_start / tool_execution_start /
  *     message_end / agent_settled / session_shutdown → activity + control tracking
@@ -203,6 +204,14 @@ const SCHEDULE_PARAMETERS = {
 	required: ["prompt"],
 	additionalProperties: false,
 };
+const CONFIG_PARAMETERS = {
+	type: "object",
+	properties: {
+		key: { type: "string", description: "配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.*）" },
+		value: { type: "string", description: "想改成的新值；给了就只返回 `pactive config set <key> <value> --confirm`，不落盘" },
+	},
+	additionalProperties: false,
+};
 
 /** Mark an activity kind; never throws. */
 async function markActivity(kind: "user" | "agent" | "session-start" | "session-end" | "tool"): Promise<void> {
@@ -237,7 +246,8 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		name: "pactive_status",
 		label: "Pactive Status",
 		description:
-			"Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+			"当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」时用。" +
+			"→ 读当前空闲判定、reason、护栏四闸门、任务数与最近活动。只读，不落盘。",
 		parameters: STATUS_PARAMETERS,
 		async execute() {
 			try {
@@ -276,7 +286,10 @@ export default function activate(pi: PactiveExtensionAPI): void {
 	pi.registerTool({
 		name: "pactive_schedule",
 		label: "Pactive Schedule",
-		description: "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+		description:
+			"当用户说「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」时用。" +
+			"→ 登记一条定时任务并立即落盘；when 支持 10m / 18:30 / ISO 8601 / every 1h。" +
+			"会写盘，需要人工确认（只在用户明确要求时调用）。",
 		parameters: SCHEDULE_PARAMETERS,
 		async execute(_toolCallId: string, params: Record<string, any>) {
 			try {
@@ -321,6 +334,55 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "pactive_config",
+		label: "Pactive Config",
+		description:
+			"当用户问「主动提醒的开关开着吗」「阈值是多少」「安静时间是几点」「帮我把主动提醒打开」时用。" +
+			"→ 读配置值与默认值；要改配置时只返回一条需要人工确认的可复制命令。只读，不落盘。",
+		parameters: CONFIG_PARAMETERS,
+		async execute(_toolCallId: string, params: Record<string, any>) {
+			try {
+				// Read-only by construction: a write request returns the command, never a write (contract §2.3).
+				const core = await loadCore();
+				const described = core.config?.describe ? core.config.describe() : { schema: {}, defaults: {} };
+				const known: string[] = Object.keys(described.defaults);
+				const key = typeof params?.key === "string" ? params.key.trim() : "";
+				const rawValue = params?.value === undefined || params?.value === null ? "" : String(params.value).trim();
+				if (key !== "" && !known.includes(key)) {
+					return textResult(`pactive_config 失败：未知配置键（${key}）；已知：${known.join(", ")}`, { error: true });
+				}
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const values = (key === "" ? known : [key]).map((k: string) => ({
+					key: k,
+					value: core.config?.get ? core.config.get(state, k) : null,
+					default: described.defaults[k] ?? null,
+					humanGated: described.schema?.[k]?.humanGated === true,
+				}));
+				if (rawValue === "") {
+					return textResult(JSON.stringify({ ok: true, readOnly: true, wrote: false, values }, null, 2), { readOnly: true });
+				}
+				return textResult(
+					JSON.stringify(
+						{
+							ok: false,
+							wrote: false,
+							reason: "need_human_confirmation",
+							command: `pactive config set ${key} ${rawValue} --confirm`,
+							hint: "不要自己改状态文件；把 command 原样给用户，等他执行后下一轮用 pactive_status 复核。",
+							values,
+						},
+						null,
+						2,
+					),
+					{ needHumanConfirmation: true },
+				);
+			} catch (err) {
+				return textResult(`pactive_config 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
 	pi.registerCommand("pactive", {
 		description: "Pactive：status | tasks | schedule <when> <prompt> | help",
 		async handler(args: string, ctx: PactiveUiContext) {

package/pi/skills/pactive/SKILL.md

@@ -1,28 +1,41 @@
 ---
 name: pactive
 description: >-
-  Correct usage of the pactive proactive-assistant extension (tools pactive_status / pactive_schedule /
-  pactive_tell / pactive_history and the "/pactive" command family). Use when the task involves checking
-  whether the idle trigger fired or why it did not, scheduling work for later (one-shot or
-  repeating), reading the pactive event ledger, or sending a message to another session on the same
-  machine. Covers the semantics traps (queued is not delivered, idle is disabled by default,
-  human-gated config needs CLI --confirm, the Stop hook blocks at most once per turn) and the
-  "when" syntax (10m / 18:30 / ISO 8601 / every 1h).
+  用自然语言操作 pactive（主动提醒 / 定时任务 / 跨会话消息 / 事件账本）。用户说「我现在闲不闲」
+  「10 分钟后提醒我喝水」「帮我开启主动提醒」「刚才主动提醒都发生了什么」时加载本技能。
+  写操作一律不静默落盘：给出可复制命令 `pactive config set … --confirm`，用户执行后下一轮用
+  `pactive_status` / `pactive_config` 复核；含 reason 枚举、「when」语法与排障。
 ---
 
-# pactive：怎么正确用它
+# pactive：用户会怎么说，你就怎么做
 
-pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定时任务**、**跨会话消息**与**事件账本**。
+**默认全部用自然语言。** 用户不会说「把 `idle.enabled` 置为 true」，他会说「帮我开启主动提醒」。
+你的工作是把这句话翻译成**一次只读查询**，或**一条可复制的命令**——不是替他改状态文件。
 
-## 工具与命令
+## 用户会怎么说 → 你做什么
 
-| 入口 | 作用 |
+| 用户说 | 你做什么 |
 |---|---|
-| `pactive_status` / `/pactive status` | 空闲判定与 `reason`、护栏四闸门、定时任务数、最近活动（只读） |
-| `pactive_schedule` / `/pactive schedule <when> <prompt>` | 登记一个定时任务（真正落盘，重启后仍在） |
-| `pactive_tell <to> <body>` | 给同机另一个会话投递消息（离线时排队，不伪装成功） |
-| `pactive_history [n]` | 读事件账本尾部：触发 → 投递 → 回应 → 结账 |
-| `/pactive tasks` | 列出待触发的定时任务 |
+| 「我现在闲不闲？」「为什么没触发？」 | 调 `pactive_status`，读 `idle.reason` 与护栏结论，照实解释 |
+| 「主动提醒开启了吗？」「阈值是多少？」 | 调 `pactive_config`（只读），报当前值与默认值 |
+| 「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」 | 调 `pactive_schedule` `{prompt, when}`（用户已明确要求，会写盘） |
+| 「帮我开启主动提醒」「把阈值改成一小时」 | **不写**：调 `pactive_config` 拿命令，把**一条**命令交给用户 |
+| 「把那个定时任务取消」 | **不写**：给出 `pactive cancel <taskId> --confirm`，让用户自己执行 |
+| 「刚才主动提醒都发生了什么？」 | 调 `pactive_history`，只报可核验的事实（时间戳 + 事件种类） |
+| 「告诉另一个会话我有空」 | 调 `pactive_tell` `{to, body}`；回执是 `queued` 就照实说**还没送到** |
+
+## 写请求的三步（硬规则）
+
+1. **不静默写状态。** 开关、阈值、取消任务一律不由你落盘：不要改 `state.json`，不要绕过 `--confirm`。
+   模型侧改配置只会得到 `need_human_confirmation`，这是设计，不是故障。
+2. **给一条可直接复制的命令。** 只给一条，不要列一堆选项：
+   ```
+   pactive config set idle.enabled true --confirm
+   pactive cancel <taskId> --confirm
+   ```
+   同时说明它会写盘、写到哪里（默认 `~/.pactive/state.json`，可用 `PACTIVE_STATE_DIR` 覆盖）。
+3. **下一轮复核。** 用户说「好了/执行了」之后，再调 `pactive_status`（或 `pactive_config`）确认真的生效，
+   然后回报实测值。**没复核就说「已开启」等于撒谎。**
 
 ## 关键语义（别踩）
 
@@ -31,8 +44,7 @@ pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定
   没触发时先看 `reason`，不要猜。
 - **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
 - **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
-- **配置是人工闸门**：`config` 只能由人用 CLI `--confirm` 改；模型/MCP 侧改配置一律得到
-  `need_human_confirmation`，且配置不变。
+- **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
 - **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
 
 ## `when` 语法
@@ -40,8 +52,19 @@ pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定
 `10m` / `2h` / `30s`（相对时长）、`18:30`（当天时刻，已过则顺延到明天）、
 ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
 
-## 排障
+## 排障（先查，再说话）
 
-- 状态面板里 `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
+- `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
 - 任务登记了但没触发 → 先看 `pactive_history` 里有没有 `triggered` 记录；没有说明调度器没跑到。
 - 消息一直是 `queued` → 对端不在线；看 `pactive_status` 的 peers。
+- 「没记录」只说明**没有证据**，不等于「没问题」——照实这么说。
+
+## 命令面（给人用的，你只在需要时引用）
+
+```
+pactive config get [<key>]                          # 只读：当前值与默认值
+pactive config set <key> <value> --confirm          # 写；缺 --confirm → exit 2 且零写盘
+pactive schedule "<prompt>" --when <when> [--confirm]
+pactive tasks                                       # id / 类型 / 下次到期 / 归属
+pactive cancel <taskId> [--confirm]
+```

package/skills/pactive/SKILL.md

@@ -1,28 +1,41 @@
 ---
 name: pactive
 description: >-
-  Correct usage of the pactive proactive-assistant extension (tools pactive_status / pactive_schedule /
-  pactive_tell / pactive_history and the "/pactive" command family). Use when the task involves checking
-  whether the idle trigger fired or why it did not, scheduling work for later (one-shot or
-  repeating), reading the pactive event ledger, or sending a message to another session on the same
-  machine. Covers the semantics traps (queued is not delivered, idle is disabled by default,
-  human-gated config needs CLI --confirm, the Stop hook blocks at most once per turn) and the
-  "when" syntax (10m / 18:30 / ISO 8601 / every 1h).
+  用自然语言操作 pactive（主动提醒 / 定时任务 / 跨会话消息 / 事件账本）。用户说「我现在闲不闲」
+  「10 分钟后提醒我喝水」「帮我开启主动提醒」「刚才主动提醒都发生了什么」时加载本技能。
+  写操作一律不静默落盘：给出可复制命令 `pactive config set … --confirm`，用户执行后下一轮用
+  `pactive_status` / `pactive_config` 复核；含 reason 枚举、「when」语法与排障。
 ---
 
-# pactive：怎么正确用它
+# pactive：用户会怎么说，你就怎么做
 
-pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定时任务**、**跨会话消息**与**事件账本**。
+**默认全部用自然语言。** 用户不会说「把 `idle.enabled` 置为 true」，他会说「帮我开启主动提醒」。
+你的工作是把这句话翻译成**一次只读查询**，或**一条可复制的命令**——不是替他改状态文件。
 
-## 工具与命令
+## 用户会怎么说 → 你做什么
 
-| 入口 | 作用 |
+| 用户说 | 你做什么 |
 |---|---|
-| `pactive_status` / `/pactive status` | 空闲判定与 `reason`、护栏四闸门、定时任务数、最近活动（只读） |
-| `pactive_schedule` / `/pactive schedule <when> <prompt>` | 登记一个定时任务（真正落盘，重启后仍在） |
-| `pactive_tell <to> <body>` | 给同机另一个会话投递消息（离线时排队，不伪装成功） |
-| `pactive_history [n]` | 读事件账本尾部：触发 → 投递 → 回应 → 结账 |
-| `/pactive tasks` | 列出待触发的定时任务 |
+| 「我现在闲不闲？」「为什么没触发？」 | 调 `pactive_status`，读 `idle.reason` 与护栏结论，照实解释 |
+| 「主动提醒开启了吗？」「阈值是多少？」 | 调 `pactive_config`（只读），报当前值与默认值 |
+| 「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」 | 调 `pactive_schedule` `{prompt, when}`（用户已明确要求，会写盘） |
+| 「帮我开启主动提醒」「把阈值改成一小时」 | **不写**：调 `pactive_config` 拿命令，把**一条**命令交给用户 |
+| 「把那个定时任务取消」 | **不写**：给出 `pactive cancel <taskId> --confirm`，让用户自己执行 |
+| 「刚才主动提醒都发生了什么？」 | 调 `pactive_history`，只报可核验的事实（时间戳 + 事件种类） |
+| 「告诉另一个会话我有空」 | 调 `pactive_tell` `{to, body}`；回执是 `queued` 就照实说**还没送到** |
+
+## 写请求的三步（硬规则）
+
+1. **不静默写状态。** 开关、阈值、取消任务一律不由你落盘：不要改 `state.json`，不要绕过 `--confirm`。
+   模型侧改配置只会得到 `need_human_confirmation`，这是设计，不是故障。
+2. **给一条可直接复制的命令。** 只给一条，不要列一堆选项：
+   ```
+   pactive config set idle.enabled true --confirm
+   pactive cancel <taskId> --confirm
+   ```
+   同时说明它会写盘、写到哪里（默认 `~/.pactive/state.json`，可用 `PACTIVE_STATE_DIR` 覆盖）。
+3. **下一轮复核。** 用户说「好了/执行了」之后，再调 `pactive_status`（或 `pactive_config`）确认真的生效，
+   然后回报实测值。**没复核就说「已开启」等于撒谎。**
 
 ## 关键语义（别踩）
 
@@ -31,8 +44,7 @@ pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定
   没触发时先看 `reason`，不要猜。
 - **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
 - **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
-- **配置是人工闸门**：`config` 只能由人用 CLI `--confirm` 改；模型/MCP 侧改配置一律得到
-  `need_human_confirmation`，且配置不变。
+- **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
 - **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
 
 ## `when` 语法
@@ -40,8 +52,19 @@ pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定
 `10m` / `2h` / `30s`（相对时长）、`18:30`（当天时刻，已过则顺延到明天）、
 ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
 
-## 排障
+## 排障（先查，再说话）
 
-- 状态面板里 `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
+- `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
 - 任务登记了但没触发 → 先看 `pactive_history` 里有没有 `triggered` 记录；没有说明调度器没跑到。
 - 消息一直是 `queued` → 对端不在线；看 `pactive_status` 的 peers。
+- 「没记录」只说明**没有证据**，不等于「没问题」——照实这么说。
+
+## 命令面（给人用的，你只在需要时引用）
+
+```
+pactive config get [<key>]                          # 只读：当前值与默认值
+pactive config set <key> <value> --confirm          # 写；缺 --confirm → exit 2 且零写盘
+pactive schedule "<prompt>" --when <when> [--confirm]
+pactive tasks                                       # id / 类型 / 下次到期 / 归属
+pactive cancel <taskId> [--confirm]
+```

package/src/core/scheduler.mjs

@@ -28,10 +28,12 @@ export const schedule = {
       if (everyMs <= 0) throw pactiveError('TASK_INTERVAL_REQUIRED', 'an "every" task needs a positive interval');
       dueAt = ts + everyMs;
     } else {
+      // A relative delay may arrive either as a duration (delayMs/afterMs/ms) or already
+      // resolved to an absolute time (spec.at — what every host-surface parseWhen produces).
       const delay = Number.isFinite(spec.delayMs) ? spec.delayMs
         : Number.isFinite(spec.afterMs) ? spec.afterMs
-          : Number.isFinite(spec.ms) ? spec.ms : 0;
-      dueAt = ts + delay;
+          : Number.isFinite(spec.ms) ? spec.ms : null;
+      dueAt = delay === null && Number.isFinite(spec.at) ? spec.at : ts + (delay ?? 0);
     }
 
     const owner = spec.owner ?? state.identity?.ownerKey ?? '';
@@ -48,6 +50,8 @@ export const schedule = {
       everyMs,
       label: spec.label ?? null,
       payload: spec.payload ?? null,
+      // The prompt is what the trigger injects later; dropping it registers an empty reminder.
+      prompt: spec.prompt ?? spec.content ?? null,
       createdAt: ts,
       lastRunAt: 0,
       active: true,