sn-proactive-agent

Proactive Agent

本 Skill 是 Agent 的操作说明，运行代码通过独立的 Python 安装包获取。

服务整理多轮对话中的项目进展，发现值得推进的事情时在 Web 工作台提出建议；

用户接受后，由对应 Connector 交回原 Session 继续执行。

按任务读取说明

• 询问原理、状态或已有记录时，只做相关的只读检查，不因加载 Skill 就安装、改配置或启动服务。
• 用户要求安装、启动、升级或卸载时，先读 [通用流程](references/install/overview.md)，再按实际运行环境读取一份系统说明。
• 配置对话接入时，只读取当前 Harness 对应的 Connector 说明，不加载其他平台的资料。

| 条件 | 读取文件 |

|---|---|

| 安装、运行与维护服务 | [install/overview.md](references/install/overview.md) |

| macOS | [install/macos.md](references/install/macos.md) |

| Windows PowerShell 或 WSL | [install/windows.md](references/install/windows.md) |

| Hermes 接入 | [connectors/hermes.md](references/connectors/hermes.md) |

install/ 负责操作系统、依赖和服务生命周期；connectors/ 负责 Harness

配置、对话采集与获批续跑。当前安装入口只支持 Hermes；其他 Harness 不能直接套用

Hermes 的命令。当前工作区为改名后的 0.1.3 未发布候选版，可安装指定 Hermes 基线的 Web-only 续跑桥，

会检查源码兼容性、备份并构建；不覆盖未知版本或本地改动。固定版本与 GitHub Release

下载前置检查见通用流程；新名称的 GitHub Release 尚未发布，也未发布到 PyPI。安装包验收不等于真实接入验收。

Windows 说明是安装参考，不代表完整接入已验收。

命名与命令

• 本 Skill 的目录和文件名使用英文；除标准入口 SKILL.md 外，使用小写与连字符。
• 示例命令、参数、变量名和命令块中的注释统一使用英文，中文解释放在命令块外。
• 保留程序原有的命令名称，不翻译参数。用户真实路径即使含中文，也应按原名正确引用，不为符合示例命名而改动用户文件。

运行边界

• 安装 Skill 与安装运行包是两件事；pipx 不会把 Skill 安装到 Harness，也不会自动启动服务。
• 区分运行包、安装文件、目标窗口在线与真实回流检查。doctor --session-id 读取指定窗口的实际证据，不主动发消息；unverified 不等于通过，旧包缺少检查能力也不能视为接入成功。
• 当前使用 Web 展示建议、接受或忽略、项目进展与日报；服务按 serve --web-only 启动，不启用终端内的重复建议界面。
• Connector 自动上报完整 QA 和新一轮输入信号；Core 负责归属、状态更新和提醒判断。
• 建议不是授权。用户接受后，只通过 Connector 续跑原 Session；读取 Skill 的 Agent 不应另外提交同一动作，造成重复执行。
• 执行结果由 Connector 带 source_suggestion_id 回流；本轮更新状态，不连续生成下一条建议。
• 不代替后台服务直接编辑 project.md、item.md、events.md 或 runtime.jsonl。
• 不读取、打印或复制 API Key、.env 或其他凭据。

查看记录

数据默认放在当前用户 Home 下的 .sn-proactive-agent/，不是安装包或源码目录。

可用 --data-root 或 SN_PROACTIVE_AGENT_DATA_ROOT 覆盖。首次有明确长期目标的

完整对话后，服务按归属创建 Project / Item，用户不需要手工建项目；一次性问题可仅记录在运行日志中。

升级用户若已有 .proactive-memory/ 且新目录不存在，自动沿用旧目录，不搬迁或合并。

旧 PROACTIVE_MEMORY_ 环境变量可继续读取，同名的新 SN_PROACTIVE_AGENT_ 设置优先。

以下路径相对于数据根目录：

• projects/<project-id>/project.md：项目概述和 Item 索引。
• projects/<project-id>/items/<item-id>/item.md：事项最新状态。
• projects/<project-id>/items/<item-id>/events.md：相关 QA 与状态变化，用于溯源。
• runtime.jsonl：对话接收、归属、提醒或静默原因、用户决定、执行结果与日报记录，用于恢复、去重和审计。

Web 读取这些记录的 JSON 展示结果，不直接修改源文件。建议区域保持简短；

详细判断依据保存在运行记录中，按需检查。