内容
# 实践智慧
**LLM 辅助工作的实践智慧。**
Phronesis（φρόνησις）是一种领域中立的 RETE 规则引擎，旨在为非确定性 AI 代理提供持久、确定的治理。它解决了在长时间 LLM 会话中出现的“上下文漂移”问题，当项目特定的指导（例如 `CLAUDE.md`）随着上下文窗口的填充和自动压缩的触发而慢慢消失。
Phronesis 中的规则存储在磁盘上，在执行动作时由轻量级钩子进行评估，并且在 token 九百万和 token 八百中触发相同的规则。
## 前提
Anthropic 的 Claude Code、OpenAI Codex、Google 的 Gemini CLI 等 LLM 环境共享一个共同的模式：它们在会话开始时加载项目级别的指导。随着会话的继续，该窗口被代码、输出和对话所填充。在第三个小时，您最需要的指令可能是在 token 八百中仔细阅读的。
**Phronesis 将强制执行从对话中完全分离出来。** 规则存储在 `.phronesis/rules.json` 中，在每次工具调用时由钩子重新读取，并在上下文窗口之外触发。由于它们一开始就没有加载到上下文中，因此不能被压缩掉。
## 子系统
除了语法规则包之外，三个基础子系统将强制执行扩展到编辑的模式匹配之外。
**置信度评分** ([SPEC-confidence-scoring](docs/specs/SPEC-confidence-scoring.md)) 通过声明式工具链定义读取构建、测试和已知错误信号：Cargo 作为内置工具，而 `.phronesis/toolchains.json` 可以扩展或覆盖其他工具链的注册表。通用解析器将匹配的命令结果转换为中立信号，并按置信度范围控制 `git commit` — 三个基础信号表示“这是真的”，而不是三个语法检查。通过编写 `.phronesis/confidence.json` 可以选择加入；`confidence` 包提供提交门控规则，而 `phr-mcp confidence` 报告当前范围。
**旅程事实** ([SPEC-journey-facts](docs/specs/SPEC-journey-facts.md)) 在 `.phronesis/journey/` 下保持一个持久的每次调用日志，并允许项目定义的标记器在 `.phronesis/journey.json` 中标记执行的工具调用。`journey_*` 聚合事实（出现、计数、看到、从上次、不同）在 `c`/`m`/`h`/`d`/`s` 窗口上允许规则匹配跨调用的时间模式 — 会话中的身份验证变化、最近五次调用中的 SQL、构建陈旧性 — 而无需任何内存累积。表面：`phr-mcp journey` 和 `get_journey` MCP 工具。
**可扩展谓词** ([SPEC-extensible-predicates](docs/specs/SPEC-extensible-predicates.md)) 允许项目 Rhai 提供者在 `.phronesis/predicates/` 下从规范的钩子事件中派生新的、验证的 LHS 事实。多文件操作在每个文件 `event.file_path` 评估之前公开一次操作的 `event.files` 更改集视图。MCP 工具可以测试和管理提供者，允许代理在添加消耗它的规则之前添加新的谓词词汇。
## 工作空间
- **`phronesis`** ([`crates/phronesis`](crates/phronesis)) — 核心库：高性能、领域中立的 RETE 规则引擎（Alpha/Beta 网络、P 状态、连接共享）具有后果/演员/来源原始数据类型。
- **`phronesis-mcp`** ([`crates/phronesis-mcp`](crates/phronesis-mcp)) — MCP 服务器，托管 Claude Code、Codex 和 Gemini CLI 钩子后面的引擎。构建 `phr-mcp` 二进制文件。
- **`phronesis-rhai`** ([`crates/phronesis-rhai`](crates/phronesis-rhai)) — 用于 `__script__` 保护条件和可扩展谓词提供者的沙盒 [Rhai](https://rhai.rs) 评估器。MCP 二进制文件默认启用它。
## 文档
在 GitHub Pages 上渲染： **[awaterma.github.io/phronesis](https://awaterma.github.io/phronesis/)**
- [**基于循环的代理编程**](docs/loop-programming-guide.md) — 指导迭代提出/行动/观察循环的指南，以防止它在长时间会话中漂移。
- [**解释器**](https://awaterma.github.io/phronesis/explainer.html) — 关于引擎、RETE 算法和设计意图的长篇技术论文。 ([源代码](docs/explainer.html))
- [**目录**](https://awaterma.github.io/phronesis/catalogue.html) — 具有理由和示例的启动规则（Rust、LLM 行为、安全）的视觉参考。 ([源代码](docs/catalogue.html))
- [**命令参考**](crates/phronesis-mcp/CLAUDE.md) — 完整的 CLI 界面和钩子线路详细信息。
- [**规格**](docs/specs/) — 架构路线图和技术债务管理计划。
## 快速入门
```sh
# 1. 安装二进制文件
cargo install --path crates/phronesis-mcp
# 2. 注册为全局 MCP 服务器
phr-mcp install
# 3. 在您的项目中初始化 Phronesis
cd /your/project && phr-mcp init --packs llm,rust,confidence,journey
```
Codex 使用生成的项目本地 `.codex/hooks.json` 和 `.codex/config.toml`。使用 `/hooks` 审查新的或更改的钩子；Phronesis 不会绕过 Codex 的信任流程。
## 血统
该引擎是 RETE 算法（Forgy，1982）的现代 Rust 实现。它是从高性能游戏逻辑系统提取并重新用于 LLM 代理治理。
亚里士多德将 **认识** （理论知识）与 **实践智慧** （实践智慧）区分开来。实践智慧是知道在此刻、此时此刻该怎么做的一种审慎美德。该项目旨在保护现代 AI 交互的“消退”边界中的这种智慧。
## 许可证
MIT。参见 [`LICENSE`](LICENSE)。
