用途
SAGE（Smart Agent Guidance Engine）是一个本地优先（local-first）的命令包装器，专为 AI 编程代理设计。AI 编程代理在处理重复日志、失败的测试输出、安装噪声、堆栈跟踪和构建刷屏时，会大量消耗上下文（context）。SAGE 位于命令与代理之间，把完整的终端输出留在用户机器上，只向代理发送一份干净、压缩后的摘要，并跟踪可验证的节省指标，且不上传原始日志。
主要能力
- 压缩终端输出，减少发送给 AI 代理的上下文噪声，从而节省 AI 编程 token。
- 将完整终端输出保留在本地，原始日志不上传。
- 跟踪真实的节省指标（proof metrics）。
- 提供本地记录的指标（Recorded Local Metrics）。
- 支持自然快捷方式（Natural shortcuts），这些快捷方式会被按特定方式处理。
- 不自动启用 MCP；MCP 为可选且需手动配置，供有需要的用户使用。
- npm 包委托给 Python 实现，因此两种安装路径使用相同的本地数据库、遥测规则、压缩逻辑和命令行为。
使用方式
- 安装 SAGE。包安装本身是被动的（出于包注册表安全考虑）。
- 安装后运行一次
sage install，为受支持的本地 AI 代理激活 SAGE。 - 使用一次
sage run -- python -m pytest。 - 之后即可使用任意 AI 代理。
- 安装后，重启任何已打开的 AI 代理会话。新会话应自动读取 SAGE 指令，并将终端命令路由到 SAGE。
重启 AI 代理后，可使用示例提示词（Example prompt）以及自然快捷方式。
注意：如果不使用 SAGE 运行 install 或 PYTEST，SAGE 不会在本地环境中激活。
适用场景
可与 Claude Code、Codex、Cursor、Windsurf、OpenCode、Cline、自定义代理、CI 脚本以及普通终端工作流配合使用。
隐私与数据
SAGE 的设计目标是：除非用户主动启用需要发送数据的功能，否则提示词、源代码、凭据、原始命令输出和项目文件都保留在本地。
安装来源
- PyPI：pypi.org/project/psycgod-sage
- npm：npmjs.com/package/psycgod-sage
限制
仓库中列出了已知限制（Known Limitations），但资料未提供具体内容。MCP 不会自动启用，需要用户手动配置。SAGE 不会在未运行 install 或 PYTEST 的本地环境中自动激活。
许可
MIT。详见 LICENSE。
