pactive 0.0.2-alpha.1 → 0.0.4-alpha.1

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
@@ -193,16 +194,81 @@ function textResult(text: string, details?: Record<string, unknown>): PactiveToo
 	return details ? { content: [{ type: "text", text }], details } : { content: [{ type: "text", text }] };
 }
 
-const STATUS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const STATUS_PARAMETERS = {
+	type: "object",
+	properties: { assistant: { type: "string", description: "只读：助理名或 id；不传 = 全部助理概览" } },
+	additionalProperties: false,
+};
+const ASSISTANTS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const FLEET_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
 const SCHEDULE_PARAMETERS = {
 	type: "object",
 	properties: {
 		prompt: { type: "string", description: "任务正文（到点注入给会话的内容）" },
 		when: { type: "string", description: "触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601 / every 1h" },
+		assistant: { type: "string", description: "记在哪个助理名下（名字或 id）；不传 = 默认助理" },
 	},
 	required: ["prompt"],
 	additionalProperties: false,
 };
+const CONFIG_PARAMETERS = {
+	type: "object",
+	properties: {
+		key: { type: "string", description: "配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.* / globalGuard.hourlyLimit）" },
+		value: { type: "string", description: "想改成的新值；给了就只返回 `pactive config set <key> <value> --confirm`，不落盘" },
+		kind: { type: "string", description: "提议哪种写操作：assistant.add | assistant.remove | assistant.enable（只返回命令，不落盘）" },
+		name: { type: "string", description: "kind=assistant.* 时要操作的助理名或 id（缺 id 时用名字）" },
+	},
+	additionalProperties: false,
+};
+
+/** One assistant as the model needs to see it: switch, pending work, next action. */
+function assistantView(core: any, state: any, record: any): Record<string, unknown> {
+	const all = core.schedule?.list ? core.schedule.list(state, record.assistantId) : [];
+	const active = (Array.isArray(all) ? all : []).filter((t: any) => t && t.active !== false);
+	const dueAt = active.map((t: any) => t.dueAt).filter((n: unknown) => Number.isFinite(n));
+	return {
+		assistantId: record.assistantId,
+		name: record.name,
+		title: record.title,
+		enabled: record.enabled === true,
+		role: record.role ?? "",
+		tasks: active.length,
+		nextDueAt: dueAt.length > 0 ? Math.min(...dueAt) : null,
+		lastFiredAt: record.lastFiredAt ?? 0,
+		firedCount: record.firedCount ?? 0,
+		policy: record.policy ?? {},
+	};
+}
+
+function assistantOverview(core: any, state: any): any[] {
+	const list = core.assistants?.list ? core.assistants.list(state) : [];
+	return list.map((record: any) => assistantView(core, state, record));
+}
+
+/**
+ * I66: the model only *proposes* — every assistant write comes back as one copy-pasteable
+ * command whose `--confirm` a human has to type. Nothing here writes.
+ */
+function assistCommandFor(kind: string, name: string, value: string, fleet: any[]): { ok: boolean; command?: string; reason?: string } {
+	const known = fleet.map((a) => a.name);
+	if (kind === "assistant.add") {
+		if (name === "") return { ok: false, reason: "kind=assistant.add 需要 name" };
+		if (known.includes(name)) return { ok: false, reason: `助理已经存在（${name}），已有：${known.join(", ")}` };
+		return { ok: true, command: `pactive assistant add ${name} --confirm` };
+	}
+	if (kind === "assistant.remove" || kind === "assistant.enable") {
+		if (name === "") return { ok: false, reason: `kind=${kind} 需要 name` };
+		const hit = fleet.find((a) => a.name === name || a.assistantId === name);
+		if (!hit) return { ok: false, reason: `未知助理（${name}）；已有：${known.join(", ") || "(none yet)"}` };
+		if (kind === "assistant.enable") {
+			const on = value === "" ? !hit.enabled : value === "true" || value === "1" || value === "on";
+			return { ok: true, command: `pactive assistant ${on ? "enable" : "disable"} ${hit.name} --confirm` };
+		}
+		return { ok: true, command: `pactive assistant rm ${hit.name} --confirm` };
+	}
+	return { ok: false, reason: `未知 kind（${kind}）；支持 assistant.add / assistant.remove / assistant.enable` };
+}
 
 /** Mark an activity kind; never throws. */
 async function markActivity(kind: "user" | "agent" | "session-start" | "session-end" | "tool"): Promise<void> {
@@ -237,28 +303,59 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		name: "pactive_status",
 		label: "Pactive Status",
 		description:
-			"Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+			"当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」「盯盘那个助理怎么样了」时用。" +
+			"→ 读空闲判定、reason、护栏闸门与任务数；给 assistant 看该助理，不给看全部助理概览。只读，不落盘。",
 		parameters: STATUS_PARAMETERS,
-		async execute() {
+		async execute(_toolCallId: string, params: Record<string, any>) {
 			try {
 				const core = await loadCore();
 				const now = Date.now();
 				const paths = core.resolvePaths(HOST_KIND, process.env);
 				const state = (await readState(core, paths)) ?? core.defaultState();
+				const globalGuard = state.globalGuard ?? null;
+				const activity = core.getActivity ? core.getActivity(state) : null;
+				const requested = typeof params?.assistant === "string" ? params.assistant.trim() : "";
+				if (requested !== "") {
+					const record = core.assistants?.resolve ? core.assistants.resolve(state, requested) : null;
+					if (!record) {
+						const names = assistantOverview(core, state).map((a) => a.name);
+						return textResult(
+							`pactive_status 失败：未知助理（${requested}）；已知：${names.join(", ") || "(none yet)"}`,
+							{ error: true },
+						);
+					}
+					const idle = core.evaluateIdle
+						? core.evaluateIdle(state, now, {}, record.assistantId)
+						: { idle: false, reason: "requires-action" };
+					const guard = core.checkGuard
+						? core.checkGuard(state, now, record.assistantId)
+						: { pass: false, reason: "requires-action" };
+					return textResult(
+						JSON.stringify(
+							{ host: HOST_KIND, now, assistant: assistantView(core, state, record), idle, guard, globalGuard, activity },
+							null,
+							2,
+						),
+						{ host: HOST_KIND },
+					);
+				}
 				const idle = core.evaluateIdle
 					? core.evaluateIdle(state, now, state.policy ?? {})
 					: { idle: false, reason: "requires-action" };
 				const guard = core.checkGuard ? core.checkGuard(state, now) : { pass: false, reason: "requires-action" };
 				const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
-				const activity = core.getActivity ? core.getActivity(state) : null;
+				const fleet = assistantOverview(core, state);
 				return textResult(
 					JSON.stringify(
 						{
 							host: HOST_KIND,
 							now,
 							enabled: state.idle?.enabled ?? false,
+							assistants: fleet,
+							assistantCount: fleet.length,
 							idle,
 							guard,
+							globalGuard,
 							tasks: Array.isArray(tasks) ? tasks.length : 0,
 							activity,
 						},
@@ -273,10 +370,56 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "pactive_assistants",
+		label: "Pactive Assistants",
+		description:
+			"当用户问「我有几个助理」「有哪些助理」「盯盘助理开着吗」「各自下次什么时候动作」时用。" +
+			"→ 列出全部助理的名称、开关、任务数、下次到期与触发次数。只读，不落盘。",
+		parameters: ASSISTANTS_PARAMETERS,
+		async execute() {
+			try {
+				const core = await loadCore();
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const fleet = assistantOverview(core, state);
+				return textResult(JSON.stringify({ ok: true, count: fleet.length, assistants: fleet }, null, 2), {
+					count: fleet.length,
+				});
+			} catch (err) {
+				return textResult(`pactive_assistants 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "pactive_fleet",
+		label: "Pactive Fleet",
+		description:
+			"当用户问「我有几个助理在跑」「盯盘那个助理在哪个 pane」「助理的窗口还活着吗」「上次主动投递送达了吗」时用。" +
+			"→ 读助理 ↔ herdr pane 绑定、agent 状态与最近一次投递；pane 状态来自 herdr，未观测到就写 unobserved。只读，不落盘。",
+		parameters: FLEET_PARAMETERS,
+		async execute() {
+			try {
+				const core = await loadCore();
+				const fleetView = await import(new URL("../src/hosts/herdr/fleet-view.mjs", import.meta.url).href);
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const payload = fleetView.fleetPayload(core, state, paths, process.env);
+				return textResult(JSON.stringify(payload, null, 2), { count: payload.count });
+			} catch (err) {
+				return textResult(`pactive_fleet 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+
 	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；assistant 不填就记在默认助理名下。" +
+			"会写盘，需要人工确认（只在用户明确要求时调用）。",
 		parameters: SCHEDULE_PARAMETERS,
 		async execute(_toolCallId: string, params: Record<string, any>) {
 			try {
@@ -289,22 +432,40 @@ export default function activate(pi: PactiveExtensionAPI): void {
 				}
 				const core = await loadCore();
 				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const requested = typeof params?.assistant === "string" ? params.assistant.trim() : "";
+				let assistantId: string | null = null;
+				if (requested !== "") {
+					const before = (await readState(core, paths)) ?? core.defaultState();
+					const record = core.assistants?.resolve ? core.assistants.resolve(before, requested) : null;
+					if (!record) {
+						const names = assistantOverview(core, before).map((a) => a.name);
+						return textResult(
+							`pactive_schedule 失败：未知助理（${requested}）；已知：${names.join(", ") || "(none yet)"}`,
+							{ error: true },
+						);
+					}
+					assistantId = record.assistantId;
+				}
 				const next = await mutateState(core, paths, (state) => {
+					const targetId =
+						assistantId ??
+						(core.assistants?.ensureDefault ? core.assistants.ensureDefault(state).assistantId : null);
 					const out = core.schedule.add(
 						state,
-						{ ...spec, prompt, content: prompt, owner: state.identity?.agentId },
+						{ ...spec, prompt, content: prompt, owner: state.identity?.agentId, assistantId: targetId },
 						now,
 					);
 					if (out && typeof out === "object" && out.state) return out.state;
 					return out && Array.isArray(out.tasks) ? out : state;
 				});
-				const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
+				const tasks = core.schedule?.list ? core.schedule.list(next, assistantId ?? undefined) : (next.tasks ?? []);
 				const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
 				return textResult(
 					JSON.stringify(
 						{
 							ok: true,
 							taskId: created?.id ?? created?.taskId ?? null,
+							assistantId: created?.assistantId ?? assistantId,
 							dueAt: created?.dueAt ?? spec.at ?? null,
 							kind: spec.kind,
 							when: spec.when,
@@ -321,6 +482,83 @@ 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 / I66).
+				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();
+				const kind = typeof params?.kind === "string" ? params.kind.trim() : "";
+				const name = typeof params?.name === "string" ? params.name.trim() : "";
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const fleet = assistantOverview(core, state);
+
+				if (kind !== "") {
+					const command = assistCommandFor(kind, name, rawValue, fleet);
+					if (!command.ok) return textResult(`pactive_config 失败：${command.reason}`, { error: true });
+					return textResult(
+						JSON.stringify(
+							{
+								ok: false,
+								wrote: false,
+								reason: "need_human_confirmation",
+								command: command.command,
+								kind,
+								before: { assistants: fleet.length, names: fleet.map((a) => a.name) },
+								hint: "不要自己改状态文件；把 command 原样给用户，等他执行后下一轮用 pactive_assistants 复核。",
+							},
+							null,
+							2,
+						),
+						{ needHumanConfirmation: true },
+					);
+				}
+
+				if (key !== "" && !known.includes(key)) {
+					return textResult(`pactive_config 失败：未知配置键（${key}）；已知：${known.join(", ")}`, { error: true });
+				}
+				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, assistants: fleet.length }, 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,44 @@
 ---
 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` 就照实说**还没送到** |
+| 「我有几个助理？」「盯盘助理开着吗？」 | 调 `pactive_assistants`（只读）；要单个详情调 `pactive_status` `{assistant}` |
+| 「再给我加一个盯盘的助理」「把巡检关掉」 | **不写**：调 `pactive_config` `{kind:"assistant.add"\|"assistant.remove"\|"assistant.enable", name}` 拿命令 |
+| 「10 分钟后提醒我看盘片」并且有多个助理 | 调 `pactive_schedule` `{prompt, when, assistant}`，把任务记到指定助理名下 |
+
+## 写请求的三步（硬规则）
+
+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 +47,12 @@ pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定
   没触发时先看 `reason`，不要猜。
 - **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
 - **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
-- **配置是人工闸门**：`config` 只能由人用 CLI `--confirm` 改；模型/MCP 侧改配置一律得到
-  `need_human_confirmation`，且配置不变。
+- **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
+- **助理是一等对象**（I61–I66）：`assistantId` 形如 `盯盘#<短哈希>`；建/删/开关都走 `pactive assistant … --confirm`；
+  新建助理默认 `enabled=false`（装上不等于打扰）；删助理会连带删掉它的任务，**不留孤儿**；重命名不改 id。
+- **按助理隔离 + 全局闸门**：每个助理各有一份计数/冷却，A 的冷却压不住 B；但全局每小时总投递有上限（默认 24），
+  超限时每个助理都记 `reason=global-limit`，不会静默丢。
+- **`tick` 是最小驱动**：`pactive tick` 跑一轮「到期任务 + 空闲判定」，可投递项落 ledger（`delivered` / `blocked`+reason）。
 - **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
 
 ## `when` 语法
@@ -40,8 +60,25 @@ 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> [--assistant <名字>] [--confirm]
+pactive tasks [--assistant <名字>]                  # id / 类型 / 下次到期 / 归属
+pactive cancel <taskId> [--confirm]
+pactive tick [--assistant <名字>]                   # 跑一轮：到期任务 + 空闲判定 → ledger
+pactive assistant add <name> [--title …] [--role …] [--scope <glob>] --confirm
+pactive assistant ls | show <name|id>               # 只读
+pactive assistant enable|disable <name|id> --confirm
+pactive assistant rename <name|id> <newName> --confirm
+pactive assistant rm <name|id> --confirm            # 连带删它的任务
+```

package/skills/pactive/SKILL.md

@@ -1,28 +1,44 @@
 ---
 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` 就照实说**还没送到** |
+| 「我有几个助理？」「盯盘助理开着吗？」 | 调 `pactive_assistants`（只读）；要单个详情调 `pactive_status` `{assistant}` |
+| 「再给我加一个盯盘的助理」「把巡检关掉」 | **不写**：调 `pactive_config` `{kind:"assistant.add"\|"assistant.remove"\|"assistant.enable", name}` 拿命令 |
+| 「10 分钟后提醒我看盘片」并且有多个助理 | 调 `pactive_schedule` `{prompt, when, assistant}`，把任务记到指定助理名下 |
+
+## 写请求的三步（硬规则）
+
+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 +47,12 @@ pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定
   没触发时先看 `reason`，不要猜。
 - **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
 - **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
-- **配置是人工闸门**：`config` 只能由人用 CLI `--confirm` 改；模型/MCP 侧改配置一律得到
-  `need_human_confirmation`，且配置不变。
+- **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
+- **助理是一等对象**（I61–I66）：`assistantId` 形如 `盯盘#<短哈希>`；建/删/开关都走 `pactive assistant … --confirm`；
+  新建助理默认 `enabled=false`（装上不等于打扰）；删助理会连带删掉它的任务，**不留孤儿**；重命名不改 id。
+- **按助理隔离 + 全局闸门**：每个助理各有一份计数/冷却，A 的冷却压不住 B；但全局每小时总投递有上限（默认 24），
+  超限时每个助理都记 `reason=global-limit`，不会静默丢。
+- **`tick` 是最小驱动**：`pactive tick` 跑一轮「到期任务 + 空闲判定」，可投递项落 ledger（`delivered` / `blocked`+reason）。
 - **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
 
 ## `when` 语法
@@ -40,8 +60,25 @@ 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> [--assistant <名字>] [--confirm]
+pactive tasks [--assistant <名字>]                  # id / 类型 / 下次到期 / 归属
+pactive cancel <taskId> [--confirm]
+pactive tick [--assistant <名字>]                   # 跑一轮：到期任务 + 空闲判定 → ledger
+pactive assistant add <name> [--title …] [--role …] [--scope <glob>] --confirm
+pactive assistant ls | show <name|id>               # 只读
+pactive assistant enable|disable <name|id> --confirm
+pactive assistant rename <name|id> <newName> --confirm
+pactive assistant rm <name|id> --confirm            # 连带删它的任务
+```