OpenSenseNova/SenseNova-Skills / skills/sn-proactive-agent
sn-proactive-agent
Verified安装、启动和使用 Proactive Agent,记录项目进展并在合适时机提醒下一步。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| references/connectors/hermes.md | markdown | 7.5 KB |
| references/connectors/openclaw.md | markdown | 5.1 KB |
| references/install/macos.md | markdown | 3.6 KB |
| references/install/overview.md | markdown | 10.6 KB |
| references/install/windows.md | markdown | 5.7 KB |
references/install/overview.md
View on GitHub# 安装与运行
本文件是 Agent 的共用执行流程。系统差异分别见 [macOS](macos.md) 和
[Windows](windows.md),对话接入见 [Hermes](../connectors/hermes.md) 或 [OpenClaw](../connectors/openclaw.md)。
只读咨询不触发安装;执行变更前,确认用户已授权相应范围。
## 安装对象与版本
- **Skill**:由 Harness 的 Skill 管理机制安装完整的 `sn-proactive-agent/` 目录,必须包含 `SKILL.md` 和 `references/`,不能只复制入口文件。
- **运行包**:通过 `pipx` 安装 Core、Web 和 Connector 资源。
- **用户数据**:保存在用户 Home 下的 `.sn-proactive-agent/`,不进入安装包。
目标运行包版本为 `0.1.4`,支持 Hermes 和 OpenClaw;从
[GitHub Releases](https://github.com/OpenSenseNova/SenseNova-Skills-ProactiveAgent/releases) 下载并校验指定版本。
Hermes 提供安装与 Session 能力探测,OpenClaw 使用独立 Gateway 插件并按真实对话验收。
已发布的 `v0.1.2` 保持旧包名 `proactive-memory-service`,不改写旧 Tag 或附件,
也不把旧包当成新名称安装失败后的替代。
安装前确认 `v0.1.4` 已发布、不是草稿,并包含以下文件:
- `sn_proactive_agent-0.1.4-py3-none-any.whl`:运行包。
- `sn-proactive-agent-openclaw-0.1.4.tgz`:OpenClaw 接入时使用的插件。
- `SHA256SUMS`:发布文件的 SHA-256 校验值。
Release 不存在、无访问权限或校验失败时停止,报告具体原因,不改用 `main`、旧包或猜测地址。
发布前只可在用户明确要求本地验收时安装本地构建、已校验的 wheel,不执行下面的 Release 下载。
发布后,Skill 源码应位于同一 Tag 下的 `skills/sn-proactive-agent/`;按 Harness 的机制安装完整目录,
不把运行包安装当成 Skill 已安装。预发布与安装检查通过,也不代表所有 Harness 或操作系统已完成验收。
## 1. 检查与授权
先确认操作系统、Shell、Harness 版本、Python 3.11 或更高、pipx、现有服务与端口占用。
Windows 必须先区分原生 PowerShell 与 WSL,保证服务和 Harness 处于同一运行环境。
按相应系统文档准备依赖并设置 `SNPA_PYTHON`,再继续第 2 步;之后的执行顺序由本文件统一组织。
向用户说明下载来源、会修改的 Connector 配置、服务地址和数据目录。
若当前请求已明确授权这些操作,按该范围执行;缺少授权时先询问。
缺少 Python、pipx 或 Harness 时说明缺项,不静默安装新的包管理器或其他 Agent 产品。
不要读取或输出凭据;模型配置由用户在 Harness 提供的配置入口完成。
## 2. 安装运行包
**先确认 Release 状态和附件,再下载。**
已有 GitHub CLI 且账号具有仓库读取权限时,先执行版本检查;确认 Release 与附件存在后,
才在本次下载的空目录中执行下载命令:
```text
gh release view v0.1.4 --repo OpenSenseNova/SenseNova-Skills-ProactiveAgent --json tagName,isDraft,isPrerelease,assets
gh release download v0.1.4 --repo OpenSenseNova/SenseNova-Skills-ProactiveAgent --pattern sn_proactive_agent-0.1.4-py3-none-any.whl --pattern SHA256SUMS
```
不要使用 `--clobber` 覆盖现有文件,也不要把访问令牌写到命令或 URL 中。没有 GitHub CLI 时,
可以让有权限的用户从上述 Release 页面下载相同文件;不因此自动安装新的工具或修改仓库可见性。
用当前系统的 SHA-256 工具核对 wheel 与 `SHA256SUMS` 中同名文件的记录,必须一致才继续。
校验值应来自同一个已确认的 Release;它用于发现内容变化或下载损坏,不替代来源与权限检查。
使用系统说明中已经检查的 `SNPA_PYTHON` 解释器,并把 `SNPA_PACKAGE` 设置为已校验
wheel 的绝对路径。下面是 POSIX Shell 与 PowerShell 通用的单行命令;
两个变量必须在当前终端中已设置且非空,换终端后需要重新设置:
```text
pipx install --python "$SNPA_PYTHON" "$SNPA_PACKAGE"
```
如果已经安装,先确认版本与来源,再判断是否需要升级,不强制覆盖现有环境。
安装后检查:
```text
sn-proactive-agent --version
sn-proactive-agent --help
sn-proactive-agent doctor --help
sn-proactive-agent doctor --json
```
命令不存在时按系统说明检查 PATH;缺少所需子命令时停止接入并报告版本不兼容,
不要拼接源码路径冒充安装包入口。新增检查的 JSON 包含 `scope` 和每项 `status`:
| 检查结果 | 含义 |
|---|---|
| `scope: runtime` | 仅检查运行包、Python、数据目录及显式指定的健康接口 |
| `scope: hermes` | 额外检查指定 Hermes 实例;传入服务地址与 Session ID 后检查该在线窗口的实际回流 |
| `passed` / `failed` / `unverified` | 已通过 / 已发现问题 / 尚无足够证据 |
必需项失败或未验证时,命令返回非零退出码。基础检查通过不等于模型调用或完整接入通过。
若旧包没有这些字段、`setup --hermes-root` 或 `doctor --session-id`,报告为“缺少新版接入检查”,
停止自动接入;可以在用户同意下仅启动 Web 查看已有记录。
## 3. 配置 Connector
按实际 Harness 读取 [Hermes](../connectors/hermes.md) 或 [OpenClaw](../connectors/openclaw.md)。
本步执行对应文件的“接入前提”和“安装 Connector”。Hermes 安装器只对显式指定且兼容的源码
进行备份、接线和构建;OpenClaw 通过其插件管理器安装,无需修改 Harness 源码。
前提不满足时停在这里,不手动强行打补丁或重装 Harness 来绕过。
配置完成后继续第 4 步;仅安装观测资源的环境不能按完整接入验收。
## 4. 启动 Web 并检查
当前使用前台服务。仅接入 Hermes 时,在单独终端执行:
```text
sn-proactive-agent serve --web-only
```
接入 OpenClaw(包括同时接入两个 Harness)时,改用下列启动方式;Gateway 地址须与实际实例一致,不要同时启动两个 Core 服务:
```text
sn-proactive-agent serve --web-only --openclaw-gateway-url http://127.0.0.1:18789
```
按 [OpenClaw 启动与启用监听说明](../connectors/openclaw.md#启动与启用监听)配置 Gateway 鉴权,
并在 Web 设置中启用 OpenClaw。只监听 OpenClaw 时可关闭 Hermes 监听;这不会移除后台 Hermes CLI 依赖。
在另一个终端检查服务:
```text
sn-proactive-agent doctor --url http://127.0.0.1:8080 --json
```
然后打开 <http://127.0.0.1:8080/>。如果使用了自定义端口或数据目录,检查、浏览器和
Connector 必须指向同一个实际服务地址,不能遇到占用就停止不明进程。
`--web-only` 关闭终端内建议展示,但不取消对话采集和获批续跑。
当前 Core 的语义工作器使用 Hermes CLI,即使监听 OpenClaw,也需要安装并配置可用的 Hermes 模型。
仅作为后台工作器时不需要安装 Hermes Connector。没有可用的 Hermes 模型时,网页可能仍能显示已有记录;这不代表新对话能够被整理。
没有兼容桥接时只报告 Web 可用,不尝试接受建议来证明接入成功。
## 5. 对话与原 Session 续跑验收
Web 可用且接入前提已满足后,执行对应 Connector 说明中的真实对话验收:
[Hermes](../connectors/hermes.md#真实对话验收) 或 [OpenClaw](../connectors/openclaw.md#真实对话验收)。需要用户同意使用的输入和模型服务,
检查完整 QA、状态更新、Web 决策、获批后原 Session 执行和结果回流。
向用户分别报告安装版本、Harness、Web 地址、数据目录,以及安装、启动、对话采集和续跑各自的验证结果。
## 停止、升级与卸载
这些操作只在用户要求时执行,并先确认当前服务归属以及是否还有正在处理的对话或获批动作。
- **停止**:在本次启动服务的终端按 `Ctrl+C`;若由其他进程管理器启动,使用该实例对应的停止方式。当前命令没有配置开机自启,不把终端前台运行称为常驻服务。
- **升级**:先核对现有环境与来源,确认已验证的目标版本。已安装续跑桥时,先按 Connector 说明恢复旧桥,再更换运行包。下载新版本 Release 的 wheel 并核对该版本校验值,再使用第 2 步命令,把 `SNPA_PACKAGE` 换成新 wheel 并增加 `--force`。固定版本链接不会自动变成新版本,不用移动旧 Tag 或覆盖旧安装包实现升级。保留已检查的 `--python`;原环境有注入包或自定义选项时先确认保留方式,不直接覆盖。
```text
pipx list --json
pipx install --help
```
不使用无版本限制的 `pipx upgrade` 作为固定版本升级方案。完成后重新核对
`--version` 和 `doctor` 输出,再按 Connector 说明刷新已复制的资源、重启并复验。
只更新 pipx 包不会刷新已复制到 Harness 的 Hook、插件或已构建的续跑桥。
`--python` 与 `--force` 的参数含义见 [pipx 官方参考](https://pipx.pypa.io/stable/reference/cli.html)。
- **卸载**:先按 Connector 说明清理接入,再卸载运行包;若用户也要求移除 Skill,使用 Harness 的管理机制单独移除说明文件。
```text
pipx uninstall sn-proactive-agent
```
默认保留实际数据目录的全部用户数据,包括沿用的 `.proactive-memory/`;只有用户明确要求删除数据时,才另行确认目标后处理。
遇到 Connector 清理残留,应报告尚未清理的内容,不宣称完整卸载成功。
### 从旧名称升级
旧包与新包是不同的安装标识,不使用 `--force` 把改名伪装成普通原地升级。
先停止旧服务,用旧包的 `proactive-memory-service uninstall` 清理原 Connector
(有桥接时传入原 `--hermes-root`,自定义配置时传入原 `--hermes-home`),
确认旧接线已恢复,再卸载旧运行包、安装新 wheel 并重新接入。
安装器发现旧 Hook、插件或未恢复的桥接时会停止,不会并行安装导致重复上报。
当前新包的 `uninstall` 只管理新名称的组件,不能替代旧包的卸载命令。
新用户默认使用 `.sn-proactive-agent/`;若新目录不存在且已有 `.proactive-memory/`,自动沿用旧数据。
两者都存在时默认选新目录,不自动合并,可用 `--data-root` 明确选择。
旧 `PROACTIVE_MEMORY_*` 环境变量仍可读;`SN_PROACTIVE_AGENT_*` 同名设置优先,命令行参数优先于环境变量。
## 开发验收
只有用户明确要求在源码仓库验收时,才使用源码入口。不要为解决正式安装问题而悄悄改用
本机仓库路径。开发验收与安装包验收分别记录;本文件重组不代表新增操作系统已通过测试。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |