【整合】 框架使用规则

hooks/Hook共享层.md

@@ -1,89 +1,59 @@
-# Hook 共享层
+# 共享检查
 
-> 本目录存放 UnityAI / StrayFog 框架知识库共享的 hook 脚本和规则。
->
-> 各 AI 工具自己的私有目录只放适配器，不重复维护 hook 逻辑。
+`hooks/` 提供只读工作流检查和提交信息检查。脚本不自动修改代码、资源或文档。
 
----
-
-## 脚本清单
-
-| 脚本 | 用途 |
-|---|---|
-| [archive-check.ps1](archive-check.ps1) | 读取 git diff 中变更的 `.md` 文件，解析 `## 文档关联` 表，输出需要同步检查的关联文档 |
-| [sync-doc-associations.ps1](sync-doc-associations.ps1) | Python 脚本的 PowerShell 包装器 |
-| [sync_doc_associations.py](sync_doc_associations.py) | 在关联文档中追加变更提醒（只追加、不覆盖，执行后需 review） |
-| [commit-check.ps1](commit-check.ps1) | 提交前检查：推断变更文件所属模块，校验提交信息格式 |
-| [commit-module-mappings.json](commit-module-mappings.json) | `commit-check.ps1` 使用的目录-模块映射配置 |
-
----
-
-## 归档检查
-
-所有任务结束后都应执行归档检查，判断是否需要同步更新长期文档。
+## 工作流检查
 
 ```powershell
-# PowerShell
-.\docs\hooks\archive-check.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File hooks/workflow-check.ps1 `
+  [-UnityProjectRoot <path>] [-DocsRoot <path>]
 ```
 
-该脚本只输出建议，不会自动修改任何文档。最终是否更新关联文档，需要用户确认。
+项目定位顺序：
 
----
+1. `-UnityProjectRoot`
+2. `UNITY_PROJECT_ROOT`
+3. 当前目录本身是 Unity 项目
+4. UnityAI 同级唯一 Unity 项目
+5. 未找到时只检查文档仓库
 
-## 文档关联同步
+检查内容：
 
-如需在关联文档中自动留下变更提醒，可运行：
+- UnityAI 与 Unity 项目的 tracked、staged、unstaged 和 untracked 文件。
+- 中文路径和未跟踪 Markdown。
+- ESF/General 源码与 CopyTo 生成目标是否同时变化。
+- 改动路径对应的建议构建、Unity 和平台验证。
+- 可能需要复核的模块文档。
+- 本次修改 Markdown 中的相对链接。
 
-```powershell
-.\docs\hooks\sync-doc-associations.ps1
-```
-
-该脚本只追加、不覆盖，执行后必须 review。
-
----
+`archive-check.ps1` 是兼容包装，新接入统一调用 `workflow-check.ps1`。
 
 ## 提交检查
 
-提交前可运行：
-
 ```powershell
-.\docs\hooks\commit-check.ps1 -Message "[entity][docs]: 补充实体池说明"
+powershell -NoProfile -ExecutionPolicy Bypass -File hooks/commit-check.ps1 `
+  -RepositoryRoot <path> `
+  -Message "[模块][类型]: 描述"
 ```
 
-检查项包括：
+脚本优先检查 staged 文件；没有 staged 文件时检查整个工作树。支持 UnityAI 和目标 Unity 项目，路径映射维护在 `commit-module-mappings.json`。
 
-- 提交信息是否符合 `[模块][类型]: 描述` 格式
-- 变更文件是否能映射到已知模块
-- 模块映射配置来自 [commit-module-mappings.json](commit-module-mappings.json)
+允许类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
 
----
+提交和推送仍然只在用户明确要求时执行。检查通过不代表可以自动提交。
 
-## 触发方式
+## 维护规则
 
-| 触发方式 | 命令/路径 | 说明 |
-|---|---|---|
-| Codex Stop hook | `.codex/hooks/archive-reminder.ps1` | 若已配置，每次任务结束自动调用 `hooks/archive-check.ps1` |
-| Claude Code 手动 | 直接运行脚本 | 任务结束时手动调用 `hooks/archive-check.ps1` |
-| 手动脚本 | `hooks/archive-check.ps1` | 直接运行 PowerShell 脚本 |
-
----
-
-## 新增 Hook 时
-
-1. 把脚本放入 `hooks/`。
-2. 在本文件中登记。
-3. 在 [ai/AI接入入口.md](../ai/AI接入入口.md) 中说明触发方式。
-4. 如果涉及提交信息格式，同步更新 [rules/40-工作流清单.md](../rules/40-工作流清单.md)。
-
----
+- 新增稳定模块路径时更新工作流与提交映射。
+- 脚本保持 Windows PowerShell 5.1 可运行，不依赖写入仓库的缓存。
+- 脚本只输出建议；源码边界警告不自动回退任何文件。
+- 新增检查后补无改动、中文路径、无 Unity 工程和双仓库场景验证。
 
 ## 文档关联
 
-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用 hook 共享层 |
-| [rules/项目规则入口.md](../rules/项目规则入口.md) | 规则入口索引归档触发机制 |
-| [rules/40-工作流清单.md](../rules/40-工作流清单.md) | 提交前检查与工作流清单互相引用 |
+| [工作流清单](../rules/40-工作流清单.md) | 检查对应的任务阶段 |
+| [文档同步规则](../rules/50-文档同步规则.md) | 文档影响判断 |
+| [开发规则](../rules/20-开发规则.md) | 源码与生成代码约束 |
+| [AI 接入入口](../ai/AI接入入口.md) | AI 工具调用入口 |