SAGE Wrapper

SAGE - 智能 Agent 指引引擎

SAGE 是一款本地优先的命令封装工具，适用于 AI 编码 Agent。它会在你的设备上保留完整的终端输出，为 Agent 发送清晰、精简的摘要，并跟踪证明指标，而不会上传原始日志。

可将它与 Claude Code、Codex、Cursor、Windsurf、OpenCode、Cline、自定义 Agent、CI 脚本以及常规终端工作流搭配使用。

从这里开始：安装 SAGE，运行一次 sage run -- python -m pytest，然后使用任意 AI Agent

为保障软件包注册表安全，安装软件包时不会执行其他操作。安装后，运行一次 sage install，即可为受支持的本地 AI Agent 启用 SAGE。

PyPI / pip

pip install psycgod-sage
# or
python -m pip install --upgrade psycgod-sage
sage install
sage run -- python -m pytest

npm / npx

npm install -g psycgod-sage
npx -y psycgod-sage install
npx -y psycgod-sage run -- npm test

安装后，重启所有已打开的 AI Agent 会话。新会话应会自动读取 SAGE 指令，并通过 SAGE 执行终端命令。

重启 AI Agent 后可使用的提示词示例：

Please help me with my general book in this folder.

也支持自然语言快捷指令：

sage pytest
sage npm test
sage git status

这些指令会被视为：

sage run -- pytest
sage run -- npm test
sage run -- git status

SAGE 的功能

步骤	结果
sage install	在本地激活本机，修复全局和项目级 Agent 指令，并验证激活状态
sage run -- <command>	运行命令，在本地保存原始输出，并返回简洁实用的摘要
Agent 记忆/钩子	告知受支持的 AI Agent，在处理嘈杂的终端任务时使用 SAGE
本地数据库	在用户设备上保存命令历史、压缩证明和重试上下文
本地证明	在用户设备上保存命令和压缩指标

SAGE 不会自动启用 MCP。对于需要使用 MCP 的用户，MCP 是可选且需要手动启用的。

记录的本地指标

截至 2026-08-01 的最新统计数据：

指标	数值
SAGE 遥测命令事件	27,892
处理的 Token 数	799.5M
节省的 Token 数	783.7M
压缩率	98.02%
预估节省金额	$16,261.90
命令成功率	88.3%
过去 7 天的 PyPI 下载量	632
过去 7 天的 npm 下载量	362
过去 14 天的 GitHub 克隆次数	574

优势

AI 编码 Agent 会因重复日志、失败的测试输出、安装噪声、堆栈跟踪和构建输出而消耗上下文。SAGE 位于命令和 Agent 之间。

不使用 SAGE	使用 SAGE
Agent 会看到完整且嘈杂的终端输出	Agent 会看到有用的摘要
上下文很快耗尽	上下文可以维持更久
重复失败会浪费 Token	错误会被归类并解释
原始日志可能进入提示词	原始日志保留在本地
难以证明节省效果	SAGE 会记录证明指标

分发渠道

渠道	软件包	状态
PyPI	psycgod-sage	官方 Python 软件包
npm / npx	psycgod-sage	Python 核心实现的 Node 启动器
MCP Registry	io.github.PsYcGoD/sage	可选/手动启用的 MCP 条目
Glama	PsYcGoD/sage	可选/手动添加的托管 MCP 列表

npm 软件包会委托给 Python 实现，因此两种安装方式使用相同的本地数据库、遥测规则、压缩功能和命令行为。

常用命令

sage install                       # Activate this machine and AI-agent instructions
sage doctor --activation           # Verify activation
npx -y psycgod-sage doctor --activation
sage run -- <command>              # Wrap any command
sage run --cwd /project -- <command> # Explicit workspace for host integrations
sage pytest                        # Shortcut for: sage run -- pytest
sage npm test                      # Shortcut for: sage run -- npm test
sage git status                    # Shortcut for: sage run -- git status
sage context stats                 # Token savings summary
sage context report                # Full compression report
sage history --limit 10            # Recent command history
sage explain --failed              # Explain the latest failed command
sage suggest --failed              # Suggest the next fix
sage fix --apply                   # Try an automatic fix
sage ml setup                      # Optional ML V2 dependencies
sage mcp install                   # Optional/manual MCP config
sage dashboard start               # Local dashboard

隐私模式

模式	需要登录？	发送数据？	哪些内容会离开本机？
仅本地	否	否	无
调试遥测	可选	仅在选择加入后	已脱敏的诊断摘要

SAGE 的设计原则是：除非用户主动启用需要发送数据的功能，否则提示词、源代码、凭据、原始命令输出和项目文件都会保留在本地。

已知限制

限制	处理方法
已打开的 AI Agent 会话可能不会重新加载新指令	运行 sage install 后，重启 Claude/Codex/Cursor/Windsurf/OpenCode
受限的宿主应用可能会禁用 shell 工具	SAGE 无法启用宿主应用已屏蔽的工具
宿主在错误的文件夹中启动 shell	使用 sage run --cwd <project> -- <command>，或设置 SAGE_WORKSPACE_CWD
npm/PyPI 安装无法安全地自动运行激活	安装软件包后运行一次 sage install
在某些 stdio Agent 会话中，MCP 可能会断开连接	默认使用常规的 sage run -- <command>；仅在需要时手动启用 MCP
软件包安装按设计为被动操作	运行 sage install 后才会真正激活

演示

流程	预览
PyPI 安装
npm 安装
sage run --
CLI 运行

链接

• PyPI：pypi.org/project/psycgod-sage
• npm：npmjs.com/package/psycgod-sage

许可证

MIT。请参阅 LICENSE。