pactive 0.0.0-stage → 0.0.1-alpha.1

package/.opcteam-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acti",
+  "version": "0.0.1-alpha.1",
+  "description": "Acti 主动机制：空闲判定、定时任务与跨会话消息（hooks + MCP）。",
+  "author": { "name": "pk09" },
+  "mcpServers": {
+    "acti": {
+      "command": "node",
+      "args": ["${OPCTEAM_PLUGIN_ROOT}/mcp/server.mjs"]
+    }
+  }
+}

package/BREAKING-CHANGES.md

@@ -0,0 +1,39 @@
+# Breaking Changes
+
+本文件记录 Acti 的**破坏性变更**。
+
+## 协议版本：`acti/1`
+
+事件协议（ledger 事件、注入载荷、回执）的版本标识为 `acti/1`。
+
+**规则：只加不改。**
+
+- **可以**：新增事件类型、新增可选字段、新增枚举值（且旧消费方对未知值必须安全降级）。
+- **不可以**：重命名 / 删除已发布的字段或事件名、改变字段语义、收紧已发布字段的可接受取值范围、
+  改变已发布字段的必填性。
+- 若某次变更无法在「只加不改」下表达，则必须**提升协议版本**（如 `acti/2`），
+  并在本文件顶部新增一节说明迁移路径；旧版本**继续可用**，不删除、不 unpublish。
+
+## 变更记录格式
+
+每个版本一节，最新在上：
+
+```markdown
+## <version> — <YYYY-MM-DD>
+
+### 破坏性
+
+- <变更点>：<旧行为> → <新行为>
+  - 迁移：<用户/集成方需要做什么>
+```
+
+## 未发布
+
+当前版本 `0.0.1-alpha.1` 尚未发布，暂无已发布的破坏性变更记录。
+
+## 0.0.1-alpha.1 — 2026-11-05（尚未发布）
+
+### 破坏性
+
+- 无。这是 `acti/1` 的首个版本，协议形状由
+  `docs/team/task-cards/ACTI-CONTRACT.md` 冻结；冻结之后只增不改。

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 z-agents contributors. All rights reserved.
+
+This software and its source code are proprietary and confidential. No rights
+are granted to use, copy, modify, merge, publish, distribute, sublicense,
+sell, or create derivative works of this software, in whole or in part, without
+prior written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# Acti
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+跨宿主的**主动能力运行时**：在宿主（Pi / OPCteam / DSH）之外统一判定「该不该主动说话」，
+把触发、投递、回应、结账写进一条 append-only 事件账本，并提供 CLI / doctor / 定时任务 / 跨会话消息。
+
+> **状态：v0.0.1-alpha.1（预发布）。** 本文只描述**契约层面**的接口。
+> 每一项能力后都标注了**当前实际验证到哪一步**——绝大多数条目当前为「未验证」。
+> 本文档不构成「已支持」的声明；请以「宿主兼容矩阵」与「未验证项」两节为准。
+
+---
+
+## 1. 安装
+
+```bash
+# 从 npm（alpha 标签；首次发布前该命令会 404）
+npm i -g pactive   # 命令：pactive 或 acti
+
+# 从本地 tarball
+npm pack
+npm i -g --prefix /tmp/acti-prefix ./pactive-0.0.1-alpha.1.tgz
+```
+
+运行环境：**Node.js ≥ 22.19.0**（`engines.node`）。
+
+安装后提供单个可执行文件 `acti`。本包**不含**源码仓库中的测试目录（`files` 白名单不含 `tests/`），
+测试与门禁脚本仅存在于源码仓库。
+
+包元数据见 `package.json`：除设计 §10 列出的字段外，另加了 `pi`（Pi 宿主加载扩展/技能所需）、
+`license` / `description` / `repository`（npm 发布所需）——均为**新增**，不改动契约字段的取值。
+
+---
+
+## 2. 用法
+
+### 2.1 启动宿主（带 Acti 注入参数）
+
+```bash
+acti pi        -p "继续处理积压任务"    # pi --extension <pkg>/pi/extension.ts --skill <pkg>/pi/skills/acti
+acti opcteam  -p "继续处理积压任务"    # opcteam --plugin-dir <pkg>
+acti dsh                            # dsh --profile acti（只写 acti 专用 profile）
+```
+- 注入参数在前，用户参数原样追加。
+- Pi 宿主通过包内 `pi` 字段声明扩展与技能（`pi.extensions` → `pi/extension.ts`，
+  `pi.skills` → `pi/skills/acti`）；`pi install acti` 依赖该字段。
+- 宿主退出码 / 信号原样透传（信号 → 128+n）。
+- **stdout 纯净**：Acti 自身的回执、诊断、进度一律走 stderr，
+  stdout 只承载被启动宿主的输出，以及 `--print-plan` / `doctor --json` 的机器可读结果。
+
+### 2.2 其它子命令
+
+| 命令 | 行为 | 退出码 |
+|---|---|---|
+| `acti --version` / `-v` | 打印版本号 | 0 |
+| `acti --help` / `-h` | 列出三个宿主、子命令、环境变量 | 0 |
+| `acti --print-plan <host>` | 打印注入计划 JSON（零写盘） | 0（未知宿主 2） |
+| `acti doctor [--json]` | 宿主 / 版本 / 注入模式 / 状态根 / 权限 / 残留 | 0（有 FAIL 段则 1） |
+| `acti install <host>` / `acti uninstall <host>` | 幂等安装 / 卸载 | 0（有残留则 1） |
+| `acti <未知宿主>` | 列出 pi / opcteam / dsh 到 stderr | 2 |
+| 宿主二进制缺失 | 提示安装 + `ACTI_<HOST>_BIN` 覆盖 | 127 |
+
+### 2.3 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `ACTI_STATE_DIR` | 状态根覆盖（默认按宿主约定解析） |
+| `ACTI_HOME` | 包根覆盖（测试用） |
+| `ACTI_PI_BIN` / `ACTI_OPCTEAM_BIN` / `ACTI_DSH_BIN` | 宿主二进制路径覆盖 |
+
+---
+
+## 3. 宿主兼容矩阵
+
+「验证到哪一步」一列只写**本仓库当场实测过的步骤**，没做过的写「未验证」。
+
+| 宿主 | 本机版本 | 注入方式 | 当前验证到哪一步 |
+|---|---|---|---|
+| Pi | 1.4.0（`pi --version` 实测） | `pi --extension <pkg>/pi/extension.ts --skill <pkg>/pi/skills/acti` | **已验证**：扩展真实加载 + `session_start` 触发 + `/acti status` 在真实 Pi 里输出状态行（`acti pi -p "/acti status"` → `[acti] ... idle=false reason=disabled`，exit 0）。**未验证**：TUI 交互模式下的命令可见性、`--skill` 技能是否被检索到 |
+| OPCteam | 1.1.6-test（`opcteam --version` 实测） | `opcteam --plugin-dir <pkg>`（包根即插件根） | **已验证**：`opcteam plugin validate <pkg>` → ✔ Validation passed；`opcteam plugin list` 显示 `acti@inline`；真实会话里 `/acti:acti status` 能被识别，MCP 工具 `mcp__plugin_acti_acti__acti_status` 已注册并被权限闸门拦下（`-p` 非交互下的预期行为）。**未验证**：人工批准后工具真正执行、hooks 在真实会话中的作用 |
+| DSH | 0.2.1-rc.5（`dsh --version` 实测） | `dsh plugin --profile acti add <pkg>` → `dsh --profile acti` | **已验证**：`acti install dsh` 写入专用 profile（`profiles/acti/package.json` 的 `dsh.profile.bundles` 含 `acti`），`dsh --profile acti --dump-config` 输出中出现 `acti`（7 处）。**未验证**：真实 GUI / TUI 会话里工具与命令的可用性 |
+
+三宿主共同的端到端冒烟（`acti pi -p` / `acti opcteam -p` / `acti dsh --dump-config` 能看到 Acti 工具/命令）
+**尚未执行**，因此本文不声称任何宿主「已支持」。
+
+ACP 通道（第四个 adapter）**本期不实现**，仅留接口 stub 与文档口径，不在 CLI 表面内。
+
+---
+
+## 4. 默认不打扰
+
+Acti 的默认状态是**不主动说话**：
+
+- `idle.enabled = false`（空闲触发默认关闭）。引擎在、开关关。
+- 打开 idle 必须走**人工闸门**：只有 CLI 带 `--confirm` 才能改；
+  MCP / 模型调用只能得到 `need_human_confirmation`，配置不变。
+- 空闲判定是四要素合取，缺一不触发：控制权已交回（Stop 后）、当前不忙、
+  超过空闲阈值、四道护栏（静默时段 / 每小时上限 / 最小间隔 / 冷却）全部放行。
+- Acti 自己的注入**不刷新**活动基线；同一活动纪元最多触发一次。
+- 动作集默认只允许 `prompt`；`agent-inline` / `agent-process` 默认关闭。
+
+---
+
+## 5. 安全声明
+
+- **不读凭据**：不读取 `*_API_KEY` 等凭据；状态与日志只写白名单字段
+  （`agentId` / `hostKind` / `cause` / `reason` / `state` / `ts`）。子进程不继承凭据环境变量。
+- **不联网、不自更新**：启动与诊断不发起网络请求，包内不引入自动更新机制。
+- **权限**：状态目录 0700、状态文件 0600；权限不合要求时显式报错，不静默降级。
+- **默认零持久化**：Pi / OPCteam 默认只在会话内注入，不写用户 settings；
+  DSH 只写专用 `acti` profile，**不改**用户默认 profile。
+- **可卸载**：`acti uninstall <host>` 幂等，残留可枚举，残留非 0 即失败退出。
+- 发行物含 Pi 扩展源码（`pi/extension.ts`），使用条款见包内 `LICENSE`；使用条款见包内 `LICENSE`（专有许可）。
+
+---
+
+## 6. 未验证项
+
+以下条目**尚未取得证据**，任何「可用 / 已支持」的说法都不成立：
+
+1. Pi 1.4.0：扩展加载/事件/命令已验证；**TUI 交互模式**下命令可见性与 skill 检索未验证。
+2. DSH Cordis bundle 在真实 GUI / 会话下的行为 —— 只计划验到 `--dump-config` 与工具注册。
+3. OPCteam：validate/list/命令发现/MCP 注册已验证；**人工批准后工具真正执行**与 hooks 实战效果未验证。
+4. 三宿主真实端到端冒烟（`acti pi -p` / `acti opcteam -p` / `acti dsh --dump-config`）。
+5. npm 安装链：`npm pack` → `npm i -g --prefix <prefix> ./acti-*.tgz` → `acti --version` → `acti doctor` 通过。
+6. npm 发布与回滚链路（`npm publish --tag alpha` / `npm view acti version` / `npm deprecate`）。
+7. Windows（Node spawn / 路径差异）—— 未在任何 Windows 机器验证。
+8. ACP 通道（I51–I56）—— 全部未实现、未探针。
+9. 空闲唤醒在 headless 下能否产生第二回合（B12 边界）。
+10. 卸载残留枚举为 0 的实测（`装两次 → 卸两次 → 残留 0`）。
+11. 安全项：假 key 不落地、目录/文件权限、子进程 env 过滤 —— 依赖 `tests/security` 用例，当前未落盘。
+
+---
+
+## 7. 协议与破坏性变更
+
+- 事件协议版本：`acti/1`。**只加不改**——已发布的字段不重命名、不删除、不改语义。
+- 破坏性变更记录见 [`BREAKING-CHANGES.md`](./BREAKING-CHANGES.md)。
+- 内部 API（`src/core` 导出名、宿主 adapter 签名）以
+  `docs/team/task-cards/ACTI-CONTRACT.md` 为冻结契约，改名即破坏并行。
+
+---
+
+## 8. 源码仓库与门禁
+
+```bash
+# 独立性门禁（依赖 / 源码 import / npm pack 产物 三层扫旧包名）
+bash scripts/quality/acti-independence-gate.sh
+bash scripts/quality/acti-independence-gate.sh --self-test   # 自测：造命中 → 断言红 → 清理 → 绿
+
+# 聚合门禁（S1 core / S2 cli+hosts / S3 pack 单测+白名单+入口存在性 / S4 独立性 / S5 security / S6 文档机检+自测+数字对齐 / S7 结论行）
+bash scripts/quality/acti-gate.sh
+bash scripts/quality/acti-gate.sh S3      # 单段可跑
+```
+
+独立性的含义：Acti **不依赖**旧的 `pi-proactive` / `opcteam-proactive` / `dsh-proactive` / `mcp-proactive` 包，
+三层机检保证这一点（依赖声明 / 源码 import / 打包产物文件名）。
+
+## 9. 本仓库目录（发行包 = 仓库根）
+
+本仓同时放着历史产物与新产品，**npm 包只由 `files` 白名单取内容**，不会把历史目录打进包：
+
+| 路径 | 是什么 | 进 npm 包 |
+|---|---|---|
+| `bin/ src/ pi/ hooks/ mcp/ dsh/ commands/ agents/ skills/ .opcteam-plugin/` | **Acti 本体**（本新产品） | ✅ |
+| `tests/` | 测试（core/cli/hosts/pack） | ❌ |
+| `scripts/quality/acti-*.sh` `scripts/quality/acti-proactive-probe.mjs` | 门禁与验收探针 | ❌ |
+| `docs/acti/` | 需求与设计真源（不变量 I1–I56、方案、功能清单、可视化设计、详细设计） | ❌ |
+| `docs/project/` `docs/team/` `docs/review/` | 过程资产（里程碑/排期/回执/任务卡/评审） | ❌ |
+| `pi-proactive/ dsh-proactive/ opcteam-proactive/ mcp-proactive/` | **旧四个包**（仅行为参考，Acti 不依赖） | ❌ |
+| `dist/` `marketplace/` `runtime/` | 历史交付制品与分发入口 | ❌ |
+
+判据：`npm pack --dry-run --json | grep -c '"path"'` → 42（当前），且不含 `tests/`，由 `scripts/quality/acti-gate.sh` S3 段机检。

package/agents/acti-observer.md

@@ -0,0 +1,35 @@
+---
+name: acti-observer
+description: 观察 acti 的空闲判定与主动触发是否真的发生，只报可核验的事实
+tools:
+  - Read
+  - Grep
+  - Glob
+model: inherit
+permissionMode: default
+maxTurns: 8
+---
+
+你是 acti 的观察 agent：负责回答「主动机制到底有没有按预期工作」。
+
+## 任务
+
+1. 读 `acti_status`（或 `acti history`）拿到**当前**的空闲判定、`reason`、护栏结论与事件账本尾部。
+2. 对照用户的期望回答：**触发了吗？为什么没触发？**
+3. 只报告**新事实**：具体的事件、具体的时间戳、具体的 `reason`，不要重复用户已知内容。
+
+## 边界
+
+1. **只读**：不修改用户文件，不改配置，不取消任务，不发送跨会话消息。
+   改配置是人工闸门（CLI `--confirm`），观察 agent 一律不做。
+2. **不把 `queued` 说成已送达**，不把「没记录」说成「没问题」——「没记录」只说明**没有证据**。
+3. **不触发主动行为**：观察归观察，别自己把空闲开关打开。
+4. 没有发现需要处理的事项时，明确说「没有发现需要处理的事项」，并列出你查过的路径。
+
+## 输出格式
+
+```
+结论：触发 / 未触发（reason=<枚举值>）
+证据：<事件时间戳 + 事件种类，或「账本里没有 triggered 记录」>
+建议：<一条可执行动作，或「无需动作」>
+```