| name | file-organization-governance |
| description | 自动检测和改善代码库的文件组织结构，确保代码具有清晰的模块化和分层架构。使用模块化分割（按功能领域）和分层抽象（按职责分层）的双重策略，在每次代码修改后自动运行检测，或在目录文件数超过阈值时触发。 |
文件组织治理
概述
使用此技能自动检测和改善代码库的文件组织结构，确保代码具有清晰的模块化和分层架构。该技能采用双重组织策略：按功能领域模块化分割和按职责分层抽象。
这里要特别明确：
“目录结构规范”不是只指这一份 skill 文本。
对本项目而言，目录结构规范系统至少包含以下几部分：
-
高层结构模型
- owner:
collapsible-feature-root-architecture
- 负责回答：当前作用域是
L1、L2、L3、还是其他明确协议；当前目录是否应保持 single feature root；何时允许 features/、shared/、platforms/
-
文件角色落位规则
- owner:
role-first-file-organization
- 负责回答：文件先按什么角色建模；角色文件应落到哪个职责目录；任何 scope root 哪些文件属于边界文件，哪些不应直接挂在根下
-
文件与目录命名规则
- owner:
file-naming-convention
- 负责回答：文件后缀、目录命名、角色后缀、
kebab-case 等命名层约束
-
目录治理执行入口
- owner:
file-organization-governance（本 skill）
- 负责回答：什么时候触发目录治理；如何扫描、识别、分组、提出重构动作；需要联动哪些其他结构规则
-
可执行治理脚本
- owner:
scripts/governance/*
- 尤其包括：
scripts/governance/module-structure/*scripts/governance/checks/structure/lint-new-code-flat-directories.mjsscripts/governance/checks/structure/lint-new-code-file-role-boundaries.mjsscripts/governance/checks/structure/lint-new-code-frozen-directories.mjsscripts/governance/checks/naming/lint-new-code-directory-names.mjs
- 负责把部分目录结构规范变成可运行的自动检查
-
目录结构协议 / contract 数据
- owner:
module-structure.config.json 与 scripts/governance/module-structure/module-structure-contracts.mjs
- 负责回答：某个 package / app 当前声明采用什么结构协议、允许哪些根目录、允许哪些根文件、共享层如何建模
目录结构协议是固定白名单，不是可自由扩展的命名空间。当前只能从脚本测试中批准的协议名单里选择；白名单必须自上而下对齐高层结构规范。若高层规范已定义某个结构等级但脚本未实现，应优先视为脚本漏实现并补齐，而不是说该结构不受支持。任何新增高层未定义的新协议都必须先得到用户明确同意，再同步修改脚本白名单、协议定义、高层结构说明和相关 contract。禁止为了绕开现有结构冲突而新增开放型、冻结型、显式白名单型或换名过渡协议。
Protocol flat role 目录允许使用 __tests__/ 与 tests/ 作为测试专用子容器；新增测试默认优先放入 __tests__/，tests/ 主要保留给既有历史测试和迁移过渡；生产实现仍应作为直接文件回到对应的 feature、role 或 shared 边界。
这里还要明确一条对应原则：
高层目录规范、脚本协议、workspace contract 引用必须一一对应。
- 不允许只在
module-structure-contracts.mjs 里新增或放宽一个 protocol，却没有同步把它对应到高层结构规范
- 不允许高层 skill 已经声明某个结构类别，但脚本层没有对应 protocol / 检查语义
- 不允许
module-structure.config.json 引用一个协议名，而该协议在高层规范里没有 owner、适用边界和约束说明
- 不允许 AI 自行发明新 protocol；若现有结构与固定协议冲突，必须把冲突作为治理债务暴露，而不是新增协议掩盖
- 发现高层规范与脚本协议不一致时，必须自上而下判断真实意图；若高层规范已经成立，优先修脚本和 contract，而不是让脚本反向定义规范
- 新增或修改 protocol 时，必须同时检查：
collapsible-feature-root-architecturerole-first-file-organizationscripts/governance/module-structure/*- 相关
module-structure.config.json
- 若这几层没有同步完成，就不应视为目录结构规范已经落地
这里再加一条仓库级硬规则：
每个 workspace 根默认都必须显式声明 module-structure.config.json。
- 适用范围包括
apps/*、packages/*、packages/extensions/*、packages/ncp-packages/*、workers/* 等实际 workspace 根
- 不允许继续依赖“因为没声明 contract，所以脚本没管到”的灰区
- 若某个 workspace 结构暂时还不适合复用现有 protocol，也必须先声明一个显式 contract（可为 legacy 或新的 protocol），而不是裸奔
因此，当用户说“调整目录结构规范”时，默认不能只改这一份 skill，而要检查：
- 结构模型 skill 是否要改
- 角色落位 skill 是否要改
- 命名 skill 是否要改
scripts/governance/* 是否已有对应自动化检查- module-structure contract / protocol 是否要同步更新
- workspace 根缺失
module-structure.config.json 的检查是否也要同步更新
如果最终只改了其中一层，必须明确说明为什么其他层不适用。
这里的 scope root 包括但不限于：
- package / app 根
- feature root
- 子 feature root
- command root
- platform root
- kernel contribution root
shared/lib/<module>/ 这类显式模块根
默认原则统一为：
root 保边界，角色文件回角色目录。
contributions/ 是 kernel / runtime 级 package 可使用的旁路能力结构角色，不属于普通 app/frontend 的默认骨架。若某个 package contract 开放 contributions/，治理脚本应按 contributions/<name>/index.ts 唯一入口与内部角色子目录来约束；contribution 内部可以继续使用 contributions/<child>/index.ts 隔离局部分支能力，但嵌套 contribution 也必须遵循唯一入口和角色子目录规则，避免 contribution 内部变成新的平铺杂物目录。
对于前端展示层项目，再额外加一条强约束：
presenters/、managers/、stores/ 必须真实存在，不是可选建议。
- 如果该项目属于前端
L1 单根作用域，它们默认应出现在该作用域根下
- 如果该项目属于前端
L3 / 多 feature 作用域，它们可以落在 app/、feature root 或平台作用域内，但不能整体缺席
- 不允许只靠
service 或 provider 文件名去“代替” presenter / manager / store 这三个 owner
使用时机
在以下情况触发此技能：
- 每次代码修改后自动运行检测
- 用户主动请求代码组织审查
- 目录文件数量超过阈值（>15个文件）
- 检测到混合关注点的目录
- 当需要重构混乱的目录结构时
- 在新项目初始化或大型重构期间
工作流程
- 扫描分析：扫描目标目录的文件数量和组织结构
- 问题识别：识别需要重构的目录（文件过多或混合关注点）
- 语义分组：根据文件命名模式建议模块化分组
- 分层建议：对大型模块（>8个文件）建议分层架构
- 规则对齐：检查本次问题主要属于结构模型、角色落位、命名规则、自动化脚本还是 protocol contract
- 脚本联动检查：若规则变化会影响自动治理结果，检查
scripts/governance/* 与相关测试/contract 是否也要同步更新
- 生成计划：生成重构计划和迁移步骤
- 执行重构：在安全情况下自动执行重构
方法论
模块化分割
按功能领域将代码分割到不同的模块。以下是一些常见示例，可根据实际项目需求调整：
- service（服务相关）
- plugin（插件相关）
- config（配置相关）
- channel（通道相关）
- diagnostic（诊断相关）
- security（安全相关）
- remote（远程访问相关）
- ncp（NCP相关）
- agent（代理相关）
注意：以上仅为示例，实际项目应根据具体业务领域和功能进行模块划分。
分层抽象
在大型模块内部按职责分层。以下是一些常见示例，可根据实际项目需求调整：
- controllers/（控制器层）
- services/（服务层）
- utils/（工具层）
- types/（类型定义层）
- hooks/（钩子层）
- components/（组件层）
注意：以上仅为示例，实际项目应根据具体架构模式和职责进行分层。
平铺职责目录硬约束：
hooks/ 与 services/、utils/、stores/ 一样，应被视为平铺职责目录；hooks/ 下禁止再出现子目录，只允许直接 hook 文件。lib/ 应被视为模块容器目录；lib/ 下只能出现模块子目录，不能直接放文件。共享能力应先落到 lib/<module>/，再由该模块目录的 index.ts / index.tsx 暴露公共出口。
操作步骤
-
运行检测脚本分析目录结构：
node .agents/skills/file-organization-governance/scripts/enhanced-check-organization.js [目录路径]
-
根据输出建议确定重构方案
-
如需自动重构，使用重构脚本
决策规则
- 当单个目录文件数 > 15 时，触发模块化建议
- 当单个模块文件数 > 8 时，建议分层结构
- 保持模块和层的职责单一
- 优先按功能模块组织，再考虑内部分层
- 避免过度分层造成导航困难
- 根据项目实际情况灵活调整模块和分层策略
- 若目标目录是
hooks/，禁止用再套一层子目录来“分类”
- 若目标目录是
lib/，优先创建模块目录而不是直接堆文件
当请求涉及“修改目录结构规范”而不是单次目录整理时，额外执行：
- 判断变更属于下列哪一类：
- 结构模型变化
- 角色落位变化
- 命名变化
- 自动化检查变化
- protocol contract 变化
- 搜索
scripts/governance/* 是否已有对应检查在执行这条规则
- 若已有脚本在执行该规则，不得只改 skill 文本；必须同步修改脚本或明确说明不适用原因
- 若结构协议会变，检查对应
module-structure.config.json / protocol contract 是否也应同步调整
- 若需要新增 protocol，先停止并取得用户明确同意；获批后再同步脚本白名单、协议定义、高层 skill、设计文档与相关 contract
- 最终明确说明：本次改动更新了目录结构规范系统中的哪些部分，哪些部分未动以及原因
参考
