pi-shepherd 0.1.2 → 0.2.0

package/rules.json

@@ -20,7 +20,7 @@
 				"flags": ""
 			}
 		],
-		"reason": "编辑了 Python 文件，必须：1) 运行 ruff check <file> 做格式检查；2) 跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
+		"reason": "编辑了 Python 文件，必须：1) 运行 ruff check <file> 做格式检查；2) 验证测试——迭代场景用 fast 档 `uv run python scripts/run_test_gate.py --fast`（按 diff 只跑受影响子项目，分钟级反馈）；change 收尾/宣称「全量测试通过」SHALL 跑全量 `uv run python scripts/run_test_gate.py`（fast 凭证 .test-gate-fast-state.json 不属于全量绿证据）。",
 		"enabled": true
 	},
 	{
@@ -34,7 +34,7 @@
 				"pattern": "(>>|>|tee|sed\\s+-i|cp\\s|mv\\s).*settings\\.json|settings\\.json\\s*(>>|>)"
 			}
 		],
-		"reason": "直接编辑 settings.json 曾导致配置丢失（119行变3行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
+		"reason": "直接编辑 settings.json 曾导致配置丢失（119行变3行）。必须使用 settings_patch 工具（自动备份+文件锁+校验），或 settings_rollback 回滚。",
 		"enabled": true
 	},
 	{
@@ -50,7 +50,7 @@
 			}
 		],
 		"reason": "编辑了 Rust 文件，必须：1) 运行 cargo clippy 做格式和 lint 检查；2) 跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
-		"enabled": true
+		"enabled": false
 	},
 	{
 		"comment": "[TypeScript] 编辑/写入后必须跑测试",
@@ -68,26 +68,33 @@
 		"enabled": true
 	},
 	{
-		"comment": "收尾规则 — agent_end 时提醒 commit + 记忆 + 总结，commit 必须带 session ID",
+		"comment": "[arch] 会话结束前检查 git 状态（已停用：多会话并行时仓库级 git_dirty 误伤其他会话任务，收尾检查移入 opsx-archive 归档流程）",
 		"hook": "agent_end",
+		"check": "",
 		"action": "notify",
-		"check": "has_edits",
-		"reason": "⚠️  shepherd: 检测到文件编辑，执行收尾工作：\n1️⃣ **Git commit**：如有未提交的 git 改动 → git add + git commit。**⚠️ commit message 末尾必须加 `session:${PI_SESSION_ID}`** — 这是硬性要求，不是建议。session ID 用于会话分析和 roadmap 追踪，缺少会导致无法追溯。格式示例：`feat: xxx session:019e71c9-b340-7fae-a330-98d837e72099`\n2️⃣ **记忆更新**：如有值得记住的知识 → memory_update\n3️⃣ **会话总结**：简要总结本次会话做了什么",
-		"stopReason": [
-			"stop"
+		"reason": "Git 检测到未提交或未跟踪的文件。收尾时请确认：\n1. git add + commit（必须带 session ID）\n2. 如有重要决策/发现 → 更新记忆文件",
+		"enabled": false,
+		"subagent": false,
+		"conditions": [
+			{
+				"builtin": "git_dirty"
+			},
+			{
+				"builtin": "git_untracked"
+			}
 		],
-		"enabled": true
+		"conditionLogic": "or"
 	},
 	{
-		"comment": "[memory] git commit 后提醒更新记忆",
+		"comment": "[memory] git commit 后提醒更新记忆（已停用：记忆更新检查移入 opsx-archive 归档流程收口）",
 		"hook": "tool_result",
 		"tool": "bash",
 		"pattern": "git\\s+commit",
 		"action": "steer",
-		"reason": "📝 刚执行了 git commit。检查本轮是否有值得跨会话保留的知识（架构决策、踩坑教训、结论），如果有 → 用 memory_update 工具写入。用法：①先调 memory_index 看已有文件，判断重复/合并/新建；②调 memory_update(fileName, content, scope) 一步写入文件+更新索引。fileName 格式：topic--kw1,kw2,kw3.md。scope：L1=跨项目通用，L2=项目级（默认）。单文件不超 200 行。如果没有新知识则忽略。",
+		"reason": "📝 刚执行了 git commit。请检查：**记忆更新** — 是否有值得跨会话保留的知识（架构决策、踩坑教训、结论），如果有 → 用 memory_update 写入。用法：①先调 memory_index 看已有文件；②调 memory_update(fileName, content, scope) 一步写入。fileName 格式：topic--kw1,kw2,kw3.md。scope：L1=跨项目通用，L2=项目级（默认）。单文件不超 200 行。如不需要则忽略。",
 		"subagent": false,
 		"requireSuccess": true,
-		"enabled": true
+		"enabled": false
 	},
 	{
 		"comment": "[arch] enforce-read-over-bash-cat：bash 中 cat|head/tail 读文件时强制用 read 工具",
@@ -118,7 +125,7 @@
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
+				"pattern": "extensions[/\\\\].*\\.ts$"
 			}
 		],
 		"action": "steer",
@@ -134,7 +141,7 @@
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
+				"pattern": "extensions[/\\\\].*\\.ts$"
 			}
 		],
 		"action": "steer",
@@ -204,7 +211,7 @@
 		"action": "notify",
 		"pattern": ".",
 		"flags": "s",
-		"reason": "推荐用 code-graph 替代 grep 搜代码——code-graph 理解 AST 语义，能按符号名、调用链、引用关系精准定位，比 grep 逐行匹配快得多且不漏不误报。选工具方法：①模糊搜索 → semantic_code_search（默认首选）；②精确符号名 → get_ast_node；③引用追踪 → find_references；④调用链 → get_call_graph；⑤模块结构 → module_overview。grep 仅适合搜字面量字符串（TODO、配置值、错误消息）。如果当前搜索的就是字面量字符串则忽略此提醒。如果目标目录没有被 code-graph 索引（搜索返回空结果），调用 setup_codegraph({ directory: \"目标目录路径\" }) 一键建索引。",
+		"reason": "推荐用 code-graph 替代 grep 搜代码——理解 AST 语义，按符号名、调用链、引用关系精准定位。选工具：①模糊搜索 → semantic_code_search；②精确符号 → get_ast_node；③引用 → find_references；④调用链 → get_call_graph；⑤模块结构 → module_overview。grep 仅适合字面量（TODO、配置值），搜字面量则忽略此提醒。\n\n**涉及字段血缘/数据链路类任务？** → 使用 field-lineage 技能。\n\n**code-graph 故障排查：**\n- **搜不到东西？** → 可能是目标目录没索引。用 `code_graph_project_map()` 查看当前索引范围，不在范围内就调 `setup_codegraph({ directory: \"目标目录绝对路径\" })` 一键建索引（创建软链接+增量索引，即时可搜）。\n- **路径报错 `must be relative`？** → path 参数必须用相对路径（相对于 CWD），不能用绝对路径。\n- **刚改了代码搜不到？** → 索引可能过期，调 `setup_codegraph({ directory: \"项目路径\" })` 重建索引（已索引目录重复调用有效，增量更新）。\n- **确实没有结果** → 忽略以上提醒，可能是符号确实不存在。",
 		"requiresTools": [
 			"code_graph_semantic_code_search"
 		],
@@ -217,7 +224,7 @@
 		"action": "notify",
 		"pattern": "\\b(grep|rg)\\b.*\\.(py|rs|ts|js|toml)(?=[\\s'\"|)]|$)",
 		"flags": "",
-		"reason": "💡 bash grep 搜代码文件不如用 pi 内置 grep 工具或 code-graph MCP 工具——code-graph 理解 AST 语义，能精准匹配符号名和调用关系。选工具：①模糊搜索 → semantic_code_search；②精确符号 → get_ast_node；③引用追踪 → find_references；④调用链 → get_call_graph。如果搜的是字面量字符串（TODO、配置值）则忽略。如果目标目录没有被 code-graph 索引，调用 setup_codegraph({ directory: \"目标目录路径\" }) 一键建索引。",
+		"reason": "💡 bash grep 搜代码文件不如用 pi 内置 grep 工具或 code-graph MCP 工具——code-graph 理解 AST 语义，能精准匹配符号名和调用关系。选工具：①模糊搜索 → semantic_code_search；②精确符号 → get_ast_node；③引用追踪 → find_references；④调用链 → get_call_graph。如果搜的是字面量字符串（TODO、配置值）则忽略。\n\n**code-graph 故障排查：**\n- **搜不到东西？** → 可能是目标目录没索引。用 `code_graph_project_map()` 查看当前索引范围，不在范围内就调 `setup_codegraph({ directory: \"目标目录绝对路径\" })` 一键建索引。\n- **路径报错？** → path 参数必须用相对路径（相对于 CWD），不能用绝对路径。\n- **刚改了代码搜不到？** → 调 `setup_codegraph({ directory: \"项目路径\" })` 重建索引。",
 		"enabled": true
 	},
 	{
@@ -231,7 +238,7 @@
 				"pattern": "\\.(ts|js|py|rs)$"
 			}
 		],
-		"reason": "💡 搜代码文件推荐用 code-graph。如果 code-graph 返回空结果，可能是目标目录没有被索引。调用 setup_codegraph({ directory: \"目标目录路径\" }) 一键建索引（软链接+增量索引，当前会话即刻可搜）。用法参考 code-graph 技能：semantic_code_search（模糊搜索）、get_ast_node（精确符号）、get_call_graph（调用链）、module_overview（模块结构）。",
+		"reason": "💡 搜代码文件推荐用 code-graph。如果 code-graph 搜不到，排查步骤：\n1. `code_graph_project_map()` 查看当前索引了哪些目录\n2. 不在范围内 → `setup_codegraph({ directory: \"目标目录绝对路径\" })` 建索引\n3. 路径报错 → 用相对路径，不用绝对路径\n4. 刚改过代码 → `setup_codegraph({ directory: \"项目路径\" })` 重建索引\n用法：semantic_code_search（模糊搜索）、get_ast_node（精确符号）、get_call_graph（调用链）、module_overview（模块结构）。",
 		"enabled": true
 	},
 	{
@@ -275,7 +282,7 @@
 			}
 		],
 		"reason": "⛔ 禁止直接编辑 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接改 JSON 会绕过这些机制导致数据不一致。",
-		"enabled": true
+		"enabled": false
 	},
 	{
 		"comment": "[roadmap] 禁止通过 bash/python 脚本直接读写 roadmap JSON — 必须用 roadmap 工具",
@@ -289,44 +296,200 @@
 			}
 		],
 		"reason": "⛔ 禁止通过 bash/python 脚本直接读写 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接碰底层 JSON 会绕过这些机制导致数据不一致。",
+		"enabled": false
+	},
+	{
+		"action": "block",
+		"comment": "[settings] 禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"conditions": [
+			{
+				"field": "command",
+				"pattern": "^(?!.*\\b(git|grep|find|ls|cat|head|tail|diff|test|python3.*json\\.load)\\b).*settings\\.json",
+				"flags": "s"
+			}
+		],
+		"hook": "tool_call",
+		"message": "⛔ 禁止通过 bash 修改 settings.json！使用 settings_patch 工具安全修改（支持全局 scope='global' 和项目级 scope='project'），或 settings_rollback 回滚。",
+		"reason": "禁止通过 bash 直接写入 settings.json（如 echo > / sed -i / python 写入），但允许 git 操作（status/diff/reset/checkout/restore/add/rm/log）和只读命令（grep/find/ls/cat/head/tail/diff/test/python3 解析读取）。必须使用 settings_patch 工具。",
+		"tool": "bash",
+		"enabled": false
+	},
+	{
+		"comment": "[git] commit 成功后提醒 push",
+		"reason": "项目已有远程仓库 origin，commit 后应同步推送避免本地积压",
+		"trigger": "bash",
+		"event": "tool_result",
+		"condition": "bash command contains 'git commit' and exit code is 0",
+		"action": "notify",
+		"message": "commit 成功。检查是否有远程仓库（git remote），有的话立即 git push 同步到远程。"
+	},
+	{
+		"comment": "[arch] 编辑 YAML 规则后提醒同步安全网",
+		"hook": "tool_result",
+		"tool": "edit|write",
+		"action": "steer",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "docs[/\\\\]agent[/\\\\]api[/\\\\].*\\.yaml$"
+			}
+		],
+		"reason": "📝 架构 artifacts YAML 已变更！请执行以下闭环步骤：\n1. python scripts/govern_sync.py --preview（预览安全网变化）\n2. python scripts/govern_sync.py --apply（应用更新）\n3. python scripts/govern_check.py（验证闭环完整性）",
+		"enabled": false,
+		"subagent": false
+	},
+	{
+		"comment": "[quality] 大量代码编辑后提醒运行治理检查",
+		"hook": "tool_result",
+		"tool": "edit|write",
+		"action": "notify",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "src[/\\\\].*\\.rs$"
+			}
+		],
+		"reason": "📝 编辑了源码。请确认：\n1. cargo clippy --all-targets -- -D warnings\n2. cargo test\n3. bash scripts/check_arch.sh（架构合规）\n4. python scripts/govern_check.py（治理健康度）",
+		"enabled": false,
+		"subagent": false
+	},
+	{
+		"comment": "[roadmap] 读计划文件时提醒标记 task 为 doing",
+		"hook": "tool_result",
+		"tool": "read",
+		"action": "steer",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "\\.pi[/\\\\]plans[/\\\\].*\\.md$"
+			}
+		],
+		"reason": "📖 你正在读取计划文件，说明即将开始执行某个 Task。请在开始编码之前先用 roadmap_update(roadmapId, taskId, {status: 'doing'}) 将对应 Task 标记为 🔄 doing，这样其他会话能看到你正在做什么，避免冲突。如果已经标记过则无视。",
+		"subagent": false,
+		"requireSuccess": true,
+		"enabled": false
+	},
+	{
+		"comment": "[code-graph] 编辑代码文件后提醒更新索引",
+		"hook": "tool_result",
+		"tool": "edit|write",
+		"action": "steer",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "\\.(ts|js|py|rs)$"
+			}
+		],
+		"reason": "📝 编辑了代码文件，code-graph 索引可能已过期（新增/重命名/删除的符号不会被搜到）。如果接下来需要用 code-graph 搜索，先调 `setup_codegraph({ directory: \"项目路径\" })` 重建索引。如果只是编辑不再搜索，则忽略。",
+		"subagent": false,
+		"requireSuccess": true,
 		"enabled": true
 	},
 	{
 		"comment": "[settings] 禁止 edit/write settings.json — 必须用 patchSettingsSectionWithBackup",
-		"reason": "直接编辑 settings.json 曾导致配置丢失（119 行变 3 行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
+		"action": "block",
+		"hook": "tool_call",
 		"tool": "edit|write",
+		"conditions": [
+			{
+				"field": "path",
+				"pattern": "settings\\.json$",
+				"flags": "i"
+			}
+		],
+		"message": "⛔ shepherd: 直接编辑 settings.json 曾导致配置丢失（119行变3行）。必须使用 settings_patch 工具（自动备份+文件锁+校验），或 settings_rollback 回滚。",
+		"reason": "直接 edit/write settings.json 曾导致配置丢失（119行变3行）。必须使用 settings_patch 工具。",
+		"enabled": false
+	},
+	{
+		"comment": "归因猜测提醒：AI 回复含可能时提醒验证",
+		"hook": "message_end",
+		"conditions": [
+			{
+				"field": "text",
+				"pattern": "可能"
+			}
+		],
+		"action": "notify",
+		"reason": "💡 如果你正在做归因猜测，请先找到确切证据验证（看源码、加 println!、断点调试），不要凭猜测下结论。如果你不是在做归因猜测，请无视此提示。如果你正在等待用户的决策或反馈，当前提示不代表用户同意或确认，请继续询问用户，不要自作主张继续执行。",
+		"enabled": false
+	},
+	{
+		"action": "block",
+		"check": null,
+		"comment": "禁止手动复制 pyd/dll 文件到 .venv",
+		"pattern": "cp.*\\.pyd|cp.*quant_py\\.dll|copy.*\\.pyd",
+		"reason": "Rust 编译产物必须通过 maturin develop 安装，禁止手动 cp。正确方式：rm -rf .venv/Lib/site-packages/quant_py/ && uv run maturin develop --release"
+	},
+	{
+		"action": "block",
+		"check": null,
+		"comment": "禁止在子项目目录创建 .venv",
+		"pattern": "quant-strategy/\\.venv|quant-fund/\\.venv|quant-base/\\.venv",
+		"reason": "AGENTS.md 规定只有根目录 .venv/ 是唯一的虚拟环境。子目录 .venv 会导致 maturin 装错位置。如果发现子目录 .venv 立即删除。"
+	},
+	{
+		"action": "steer",
+		"check": null,
+		"comment": "Rust 编译后必须验证 pyd 更新",
+		"pattern": "maturin develop",
+		"reason": "maturin develop 后必须验证 .pyd 时间戳+字节：ls -la --time-style=long-iso .venv/Lib/site-packages/quant_py/*.pyd（编译后查一次，跑完 uv run 再查一次）。pyd 过期有三种根因症状相同：① 目录错（必须根目录+uv run maturin develop）；② uv run 按 uv.lock 同步把新 pyd 覆盖回旧产物（字节 3066880→2920960 实证，须 --no-sync）；③ 改完 Rust 忘重编译。时间戳没更新 → rm -rf .venv/Lib/site-packages/quant_py/ 再重跑 maturin develop（禁止手动 cp pyd）。详见记忆 rust-comprehensive。"
+	},
+	{
+		"comment": "[shepherd] 禁止直接 edit/write rules.json — 必须用 shepherd_rules 工具",
 		"hook": "tool_call",
+		"tool": "edit|write",
 		"action": "block",
-		"message": "⛔ 禁止直接 edit settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
 		"conditions": [
 			{
 				"field": "path",
-				"pattern": "settings\\.json$|settings\\.json\\.bak"
+				"pattern": "shepherd/rules\\.json$"
 			}
-		]
+		],
+		"reason": "⛔ 禁止直接编辑 rules.json！请用 shepherd_rules 工具操作（自动备份+校验+回滚）：\nlist: shepherd_rules(action='list') — 列出所有规则\nadd: shepherd_rules(action='add', rule={...}) — 添加规则\nupdate: shepherd_rules(action='update', index=N, changes={...}) — 更新规则\ndelete: shepherd_rules(action='delete', index=N) — 删除规则\n直接改 JSON 会绕过安全机制（备份/校验/去重检测/签名覆盖）。",
+		"enabled": true
 	},
 	{
 		"action": "block",
-		"comment": "[settings] 禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"comment": "[shepherd] 禁止通过 bash/python 脚本直接读写 rules.json — 必须用 shepherd_rules 工具",
 		"conditions": [
 			{
 				"field": "command",
-				"pattern": "^(?!.*\\b(git|grep|find|ls|cat|head|tail|diff|test|python3.*json\\.load)\\b).*settings\\.json",
-				"flags": "s"
+				"pattern": "(rules\\.json[\\s\\S]*(open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat))|((open\\(|json\\.load|json\\.dump|write|sed|awk|jq|cat)[\\s\\S]*rules\\.json)"
 			}
 		],
+		"enabled": true,
 		"hook": "tool_call",
-		"message": "⛔ 禁止通过 bash 修改 settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
-		"reason": "禁止通过 bash 直接写入 settings.json（如 echo > / sed -i / python 写入），但允许 git 操作（status/diff/reset/checkout/restore/add/rm/log）和只读命令（grep/find/ls/cat/head/tail/diff/test/python3 解析读取）",
+		"reason": "⛔ 禁止通过脚本绕过直接读写 rules.json！请用 shepherd_rules 工具操作（自动备份+校验+回滚+去重检测）。",
 		"tool": "bash"
 	},
 	{
-		"comment": "[git] commit 成功后提醒 push",
-		"reason": "项目已有远程仓库 origin，commit 后应同步推送避免本地积压",
-		"trigger": "bash",
-		"event": "tool_result",
-		"condition": "bash command contains 'git commit' and exit code is 0",
+		"comment": "[code-graph] module_overview 返回空结果时提醒检查路径前缀",
+		"hook": "tool_result",
+		"tool": "code_graph_module_overview",
+		"conditions": [
+			{
+				"field": "result",
+				"pattern": "0 active \\+ 0 inactive"
+			}
+		],
 		"action": "notify",
-		"message": "commit 成功。检查是否有远程仓库（git remote），有的话立即 git push 同步到远程。"
+		"message": "⚠️ code-graph 返回空结果。如果是通过 setup_codegraph 索引的外部目录，请用路径 _codegraph_links/<name> 而不是裸名。例如: code_graph_module_overview(path='_codegraph_links/pi-intercom')",
+		"reason": "AI 常误用裸名调用 module_overview（如 path='pi-intercom'），但软链接目录在索引中的路径前缀是 _codegraph_links/"
+	},
+	{
+		"action": "steer",
+		"check": null,
+		"comment": "纯查询优先走 ro_query 助手（锁感知只读）",
+		"flags": "",
+		"pattern": "DataStore\\s*\\(\\s*\\)",
+		"reason": "检测到内联 DataStore() 默认（RW）构造做纯查询——历史撞锁事故高发模式（会话 a89c 连续撞锁 2 次）。纯查询请改用锁感知助手：uv run python quant-base/scripts/ro_query.py --sql \"...\"（RO+限时重试+持锁 PID 诊断+查完即关，支持 --db 指定 live.duckdb）。若确需 RW 写操作或 DataStore.reader() 网络服务场景，继续即可。"
+	},
+	{
+		"action": "steer",
+		"comment": "compact-skill-reminder",
+		"enabled": true,
+		"hook": "session_compact",
+		"reason": "上下文刚被压缩：此前 read 过的 SKILL.md 技能正文已随历史摘要化挥发。system prompt 里的技能索引（名字/描述/路径）仍在——若当前任务涉及某技能，请重新 read 其 SKILL.md 获取操作指引。"
 	}
 ]

package/shepherd/compaction.ts

@@ -0,0 +1,76 @@
+/**
+ * session_compact hook 处理逻辑
+ *
+ * pi 会话压缩完成后（manual /compact、threshold 阈值、overflow 溢出恢复），
+ * 按 `hook: "session_compact"` 规则注入提醒（典型用途：技能正文已随压缩
+ * 挥发，提示 AI 需要时重读 SKILL.md）。
+ *
+ * 注入走 ephemeral 管线（pushWarning → 缓冲区 → before_provider_request
+ * drainHints 消费即焚）。不 sendMessage(triggerTurn)：三种 reason 的压缩
+ * 之后均必然存在下一个 provider request（overflow→willRetry 自动重试；
+ * manual/threshold→用户下一条消息）。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { pushWarning } from "./ephemeral.js";
+import {
+	isSubagent,
+	type LoadRulesOptions,
+	loadRules,
+	ruleMatches,
+} from "./rules.js";
+import type { ToolState } from "./tool-hooks.js";
+import { toolsAvailable } from "./tool-hooks.js";
+
+/**
+ * 注册 session_compact 事件处理。
+ *
+ * 触发语义：一次压缩事件 = 一次真实挥发 = 一次提醒（不做每会话一次的
+ * _fired 去重——与 message_end 的"每轮一次"语义刻意不同）。
+ */
+export function registerSessionCompact(
+	pi: ExtensionAPI,
+	state: ToolState,
+	rulesDir?: string,
+	rulesOptions?: LoadRulesOptions,
+): void {
+	pi.on("session_compact", async (event, _ctx) => {
+		const rules = loadRules(rulesDir, rulesOptions).filter(
+			(r) => r.hook === "session_compact",
+		);
+		if (rules.length === 0) return;
+
+		// 匹配目标：reason 为压缩触发源（manual/threshold/overflow）
+		const reason: string = event.reason ?? "";
+		const targets = {
+			text: "",
+			path: "",
+			command: "",
+			glob: "",
+			result: "",
+			reason,
+		};
+
+		for (const rule of rules) {
+			// 跳过禁用规则
+			if (rule.enabled === false) continue;
+			// 子代理控制：默认跳过，显式 subagent: true 才在子代理触发
+			if (isSubagent() && rule.subagent !== true) continue;
+			// 工具依赖检查
+			if (!toolsAvailable(rule, pi, state)) continue;
+
+			// 条件匹配：conditions 模式（field 可为 reason 等）；
+			// 单条件 pattern 模式匹配 reason（向后兼容风格）；
+			// 都没有 = 无条件触发
+			if (rule.conditions && rule.conditions.length > 0) {
+				if (!ruleMatches(rule, targets, undefined)) continue;
+			} else if (rule.pattern) {
+				const re = rule._compiled ?? new RegExp(rule.pattern, rule.flags || "");
+				if (!re.test(reason)) continue;
+			}
+
+			// steer/notify 统一走 pushWarning（即焚注入）
+			pushWarning(rule.reason, rule.comment);
+		}
+	});
+}

package/shepherd/conditions.ts

@@ -0,0 +1,98 @@
+import { hasGitUntracked, isGitDirty } from "./git";
+
+/** 内置条件类型：不依赖正则，直接检查环境状态 */
+export type ConditionBuiltin =
+	| "git_dirty" // git 有已跟踪文件的未提交改动（M/A/D/R）
+	| "git_untracked" // git 有未跟踪文件（??）
+	| "git_uncommitted" // 旧 check 字段迁移兼容：dirty || untracked
+	| "has_edits" // 本轮调用过 edit/write
+	| "not_question_ending" // AI 最后一条消息不以问句结尾（用于抑制"等待回复"场景的 agent_end 提醒）
+	| "always"; // 始终匹配
+
+/** 内置条件匹配上下文 */
+export interface BuiltinContext {
+	hasEdits?: boolean;
+	gitDirty?: boolean;
+	gitUntracked?: boolean;
+	lastAssistantText?: string;
+}
+
+/**
+ * 宽松检测 AI 消息是否包含问句/确认模式（等待用户回复）
+ *
+ * 策略：全文搜索，只要出现任何问句模式就返回 true（宁可多跳，不误打扰用户）
+ * 排除代码块和引用块内的内容，避免误判技术文本中的 ? 运算符等
+ */
+export function isQuestionEnding(text: string): boolean {
+	if (!text) return false;
+
+	// 去除代码块（```...```），避免 ?. 可选链、?: 三元等误判
+	const noCodeBlocks = text.replace(/```[\s\S]*?```/g, "");
+	// 去除行内代码（`...`）
+	const noInlineCode = noCodeBlocks.replace(/`[^`]+`/g, "");
+	// 宽松方案：保留所有行（含引用块），不做过滤
+	const prose = noInlineCode;
+
+	if (!prose.trim()) return false;
+
+	// 1. 中英文问号出现在行末或句末（后面可能跟空格/换行/标点）
+	if (/[？?][\s]*(?:[\n]|$|[。.!,，、；;:：)）\]])/m.test(prose)) return true;
+	// 独立问号结尾
+	if (/[？?]\s*$/m.test(prose)) return true;
+
+	// 2. 中文疑问语气词结尾（非代码上下文）
+	// "呢/吗/吧/嘛/么/啦/呗" 出现在句末
+	if (/(?:呢|吗|吧|嘛|么|啦|呗)\s*[？?。.!！,，、；;:\s]*$/m.test(prose)) return true;
+
+	// 3. 选择/确认类句式（全文搜索）
+	const confirmPatterns = [
+		/要不要/,
+		/你觉得/,
+		/你想/,
+		/确认(?:一下)?/,
+		/可以吗/,
+		/行不行/,
+		/好不好/,
+		/是不是/,
+		/还是说/,
+		/还是先/,
+		/先(?:讨论|确认|看看)/,
+		/等(?:你|你(?:的)?回复)/,
+		/你(?:还)?(?:有|有没有)/,
+		/(?:你|您)(?:觉得|想|希望|倾向|偏好)/,
+		/请(?:确认|回复|告诉)/,
+		/你来(?:决定|选|定)/,
+		/直接改还是/,
+	];
+	for (const p of confirmPatterns) {
+		if (p.test(prose)) return true;
+	}
+
+	return false;
+}
+
+/** 判断单个内置条件是否满足 */
+export function matchBuiltinCondition(
+	builtin: ConditionBuiltin,
+	ctx: BuiltinContext,
+): boolean {
+	switch (builtin) {
+		case "always":
+			return true;
+		case "has_edits":
+			return !!ctx.hasEdits;
+		case "git_dirty":
+			return (ctx.gitDirty ?? isGitDirty()) === true;
+		case "git_untracked":
+			return (ctx.gitUntracked ?? hasGitUntracked()) === true;
+		case "git_uncommitted": {
+			// 旧 check 字段迁移兼容：git_uncommitted = dirty || untracked
+			const dirty = ctx.gitDirty !== undefined ? ctx.gitDirty : isGitDirty();
+			const untracked =
+				ctx.gitUntracked !== undefined ? ctx.gitUntracked : hasGitUntracked();
+			return dirty || untracked;
+		}
+		case "not_question_ending":
+			return !isQuestionEnding(ctx.lastAssistantText ?? "");
+	}
+}

package/shepherd/ephemeral.ts

@@ -1,52 +1,55 @@
-/**
- * Shepherd 专用提示缓冲区
- *
- * shepherd 规则触发的 steer/notify 提示通过 pushWarning 推入，
- * 由共享的 ephemeral 注入机制在 before_provider_request 时发送。
- * 提示只对当前请求生效，不写入 session 历史。
- */
-
-/** 替换 ${ENV_VAR} 格式的环境变量 */
-function expandEnvVars(text: string): string {
-	return text.replace(/\$\{(\w+)\}/g, (_match, name: string) => process.env[name] ?? `\${${name}}`);
-}
-
-/** 推入一条 shepherd 提示（自动加 ⚠️ shepherd: 前缀） */
-export function pushWarning(reason: string, label?: string): void {
-	// shepherd 前缀用于通知气泡识别，注入时由 injectHints 统一处理
-	pushShepherdHint(expandEnvVars(reason), label);
-}
-
-/** 生成通知气泡用的摘要（优先用规则名列表，fallback 截断 reason） */
-export function notifySummary(text: string, labels?: string[]): string {
-	// 优先使用规则名（comment）列表
-	if (labels && labels.length > 0) {
-		const joined = labels.join("、");
-		return joined.length > 120 ? joined.slice(0, 117) + "..." : joined;
-	}
-	// fallback：截取第一个 --- 之前的内容
-	const idx = text.indexOf("\n---");
-	if (idx > 0) return text.slice(0, idx);
-	if (text.length > 120) return text.slice(0, 117) + "...";
-	return text;
-}
-
-// ── 内部：shepherd 前缀推入共享缓冲区 ──
-
-import { pushHint as _pushShared, hasHints } from "./ephemeral-shared.js";
-
-const SHEPHERD_PREFIX = "⚠️ shepherd: ";
-
-function pushShepherdHint(reason: string, label?: string): void {
-	_pushShared(`${SHEPHERD_PREFIX}${reason}`, label);
-}
-
-/** 推入规则格式错误提示（加 ❌ 前缀区别于普通 warning） */
-export function pushRuleError(msg: string): void {
-	_pushShared(`❌ shepherd 规则格式错误: ${msg}`);
-}
-
-/** shepherd 是否有待发送的提示 */
-export function hasWarnings(): boolean {
-	return hasHints();
-}
+/**
+ * Shepherd 专用提示缓冲区
+ *
+ * shepherd 规则触发的 steer/notify 提示通过 pushWarning 推入，
+ * 由共享的 ephemeral 注入机制在 before_provider_request 时发送。
+ * 提示只对当前请求生效，不写入 session 历史。
+ */
+
+/** 替换 ${ENV_VAR} 格式的环境变量 */
+function expandEnvVars(text: string): string {
+	return text.replace(
+		/\$\{(\w+)\}/g,
+		(_match, name: string) => process.env[name] ?? `\${${name}}`,
+	);
+}
+
+/** 推入一条 shepherd 提示（自动加 ⚠️ shepherd: 前缀） */
+export function pushWarning(reason: string, label?: string): void {
+	// shepherd 前缀用于通知气泡识别，注入时由 injectHints 统一处理
+	pushShepherdHint(expandEnvVars(reason), label);
+}
+
+/** 生成通知气泡用的摘要（优先用规则名列表，fallback 截断 reason） */
+export function notifySummary(text: string, labels?: string[]): string {
+	// 优先使用规则名（comment）列表
+	if (labels && labels.length > 0) {
+		const joined = labels.join("、");
+		return joined.length > 120 ? `${joined.slice(0, 117)}...` : joined;
+	}
+	// fallback：截取第一个 --- 之前的内容
+	const idx = text.indexOf("\n---");
+	if (idx > 0) return text.slice(0, idx);
+	if (text.length > 120) return `${text.slice(0, 117)}...`;
+	return text;
+}
+
+// ── 内部：shepherd 前缀推入共享缓冲区 ──
+
+import { pushHint as _pushShared, hasHints } from "./ephemeral-shared.js";
+
+const SHEPHERD_PREFIX = "⚠️ shepherd: ";
+
+function pushShepherdHint(reason: string, label?: string): void {
+	_pushShared(`${SHEPHERD_PREFIX}${reason}`, label);
+}
+
+/** 推入规则格式错误提示（加 ❌ 前缀区别于普通 warning） */
+export function pushRuleError(msg: string): void {
+	_pushShared(`❌ shepherd 规则格式错误: ${msg}`);
+}
+
+/** shepherd 是否有待发送的提示 */
+export function hasWarnings(): boolean {
+	return hasHints();
+}