agent-rule-cli 0.1.0

package/agent-rules-templates/README.md

@@ -0,0 +1,60 @@
+# Agent Rules Generator Architecture
+
+## Goals
+
+- Shared rules are canonical cross-project constraints and are copied without project-specific mutation.
+- Project rules are generated from repository facts and explicit policy answers.
+- Every generated fact is traceable, classifiable, and time-bounded.
+- Missing information produces partial configuration, not invented certainty.
+- The generator runs on Node.js 12 or newer and has no third-party runtime dependencies.
+
+## Layers
+
+1. `shared/*.md`: canonical enterprise rules.
+2. Repository scanner: technology-agnostic evidence collection.
+3. `project-facts.json`: machine-readable facts, evidence, confidence, answers, and module coverage.
+4. `project-*.md`: human-readable project facts and policy rules.
+5. `project-index.md`: routing and computed module status.
+6. `project-custom.md`: manually maintained rules that the generator never overwrites.
+
+When `project-facts.json` already exists, repository facts are rescanned while prior `user-confirmed` answers are preserved as wizard defaults.
+
+## Fact Statuses
+
+- `confirmed`: directly proven by repository files, configuration, or Git metadata.
+- `user-confirmed`: explicitly confirmed during the interactive wizard.
+- `inferred`: recommended default or structural inference that still needs validation.
+- `undefined`: no reliable answer is available.
+
+## Module Statuses
+
+- `configured`: the coverage catalog is structurally complete.
+- `partial`: at least one required item is inferred or undefined.
+- `ignored`: the user explicitly skipped the module.
+- `unconfigured`: no module decision or reliable data exists.
+
+Each module also reports strategy configuration, repository-fact confirmation, and business-contract confirmation separately. Structural coverage does not claim that business semantics are correct.
+
+## Extension Rules
+
+- Add scanners only when evidence can be tied to a file, command, or repository metadata.
+- Do not turn current implementation behavior into desired policy automatically.
+- Do not infer protected branches from the current branch alone.
+- Do not claim a command exists unless project configuration or an ecosystem-standard toolchain proves it.
+- Keep project-specific answers out of shared templates.
+
+## Verification
+
+Run:
+
+```bash
+npx agent-rule-cli --verify
+```
+
+CI can require completeness with:
+
+```bash
+npx agent-rule-cli --verify --strict
+```
+
+Verification checks JSON schema, duplicate IDs, legal statuses, coverage catalog alignment, shared template hashes, evidence content hashes, generated artifact hashes, current branch drift, partial modules, and fact age.

package/agent-rules-templates/shared/shared-api-error-handling.md

@@ -0,0 +1,42 @@
+# 通用 API 与错误处理规则
+
+本文件描述跨项目 API 和错误处理原则。具体请求库、入口文件、错误对象和认证流程由项目级规则定义。
+
+## 1. 请求入口
+
+- API 调用应优先经过项目统一请求封装或领域服务层。
+- 页面代码不得重复实现 base URL、认证头、响应解析和全局错误提示。
+- 请求参数和响应数据应遵守项目的数据契约与类型规范。
+
+## 2. 错误分类
+
+- 至少区分网络错误、超时、认证失效、权限不足、业务错误、服务端异常和解析错误。
+- 规则必须区分“当前实现事实”和“目标处理策略”；现有缺陷不得因为被扫描到而升级为推荐规则。
+- 错误处理必须保留足够上下文，同时避免泄露敏感信息。
+- 状态码、业务码和枚举值应按项目规定的类型比较，不依赖模糊相等或隐式转换。
+
+## 3. 错误展示
+
+- 默认错误展示机制由项目级规则定义。
+- 页面 `catch` 可停止 loading、回滚局部状态、处理明确错误码和注册后置动作。
+- 页面不得重复展示已经由统一请求层展示的同一错误。
+- 不得吞掉错误后继续执行成功流程。
+
+## 4. 静默与自定义错误
+
+- 静默请求必须通过明确配置启用，并说明适用场景。
+- 登录、权限、支付、提交、保存、删除等关键请求不得默认静默失败。
+- 自定义错误文案、错误码映射和确认后回调应使用项目统一机制。
+
+## 5. 认证和权限
+
+- 认证失效时应按项目规则清理凭证、用户状态、权限、缓存和持久化数据。
+- 认证失效与权限不足必须区分处理。
+- 多个并发认证失败应避免重复提示、重复清理和重复跳转。
+- 提示、确认、关闭、遮罩取消和自动关闭后的行为必须明确。
+
+## 6. 并发与生命周期
+
+- 重试、轮询、请求取消、组件卸载和过期响应必须有明确策略。
+- 提交、支付、保存、删除等操作应考虑防重复触发。
+- 高风险流程应保留必要且脱敏的错误日志和诊断信息。

package/agent-rules-templates/shared/shared-code-quality.md

@@ -0,0 +1,36 @@
+# 通用代码质量规则
+
+本文件只描述跨项目通用原则。当前项目的目录、技术栈、数据契约和例外说明必须写入 `project-*` 文件。
+
+## 1. 修改范围
+
+- 优先理解现有实现，再做最小且完整的修改。
+- 不修改与当前任务无关的代码，不顺手重构无关模块。
+- 不回滚用户已有改动；遇到相关改动时应兼容处理。
+- 新增实现应优先遵循项目现有架构、命名、目录、依赖和抽象方式。
+
+## 2. 复用与抽象
+
+- 新增业务判断、数据转换、状态映射、表单校验、流程编排或复用 UI 前，应按项目索引检查已有资产。
+- 只有在消除真实复杂度、稳定重复或符合现有架构时才新增抽象。
+- 不为尚未出现的未来需求、跨项目复用或理论完整性提前设计复杂结构。
+- 共享封装必须有稳定语义和明确归属；一次性逻辑优先留在最低作用域。
+
+## 3. 数据契约
+
+- 项目级规则必须说明是否要求 DTO、model、mapper、normalizer、adapter 或 view model。
+- 未定义数据契约策略时，不得自行发明字段含义、默认值、状态枚举或类型转换。
+- 外部数据进入业务层时，应关注缺失字段、未知枚举、类型漂移、空值和兼容性。
+- 金额、时间、权限、状态码等高风险数据不得依赖隐式类型转换。
+
+## 4. 控制流与异步
+
+- 错误路径、取消路径、重复触发和组件卸载必须被纳入实现考虑。
+- 避免隐藏副作用、过深嵌套、重复状态和无法追踪的跨层写入。
+- 异步流程应保证成功、失败、取消和过期响应不会互相覆盖。
+
+## 5. 注释与临时方案
+
+- 注释解释业务原因、约束、兼容背景和非显然流程，不复述代码。
+- 临时方案必须说明触发条件、风险、清理条件或后续替换方向。
+- 复杂业务规则应进入项目业务规则文档，不能只存在于代码注释或聊天记录。

package/agent-rules-templates/shared/shared-git-delivery.md

@@ -0,0 +1,33 @@
+# 通用 Git 与交付规则
+
+本文件描述跨项目 Git 安全底线。分支名、提交格式、验证命令和发布流程由项目级规则定义。
+
+## 1. 工作区
+
+- 不得回滚、覆盖或删除用户已有改动，除非用户明确要求。
+- 遇到无关改动时，只处理当前任务相关文件。
+- 遇到相关改动时，应理解并兼容，不假定工作区是干净的。
+
+## 2. 分支
+
+- 不得直接在项目受保护分支提交，除非用户本轮明确授权。
+- 当前分支、默认分支候选和远端 HEAD 不等于受保护分支；受保护分支必须来自仓库策略或用户明确确认。
+- 新需求、修复、重构、文档和实验性改动应遵守项目分支命名规范。
+- 创建或切换分支前应确认不会丢失现有改动。
+
+## 3. 提交
+
+- 提交内容应聚焦当前任务，不混入无关文件。
+- 提交信息应准确描述变更，不伪造验证或影响范围。
+- WIP、squash 和提交整理遵守项目级规则。
+- 提交前执行项目要求的最小验证。
+
+## 4. PR 与交付
+
+- PR 标题、描述、截图、录屏、风险和验证说明遵守项目级规则。
+- 未执行的验证、已知限制和剩余风险必须明确说明。
+- 不提交本地环境文件、依赖缓存、敏感配置和无关构建产物。
+
+## 5. 高风险操作
+
+- 强制推送、重写历史、删除分支、清空工作区、发布、打 tag 和远程推送必须获得用户明确授权。

package/agent-rules-templates/shared/shared-project-requirements-check.md

@@ -0,0 +1,90 @@
+# 项目规则适配检查
+
+本文件用于检查 shared 通用规则依赖的 project 级答案是否已补齐，不记录当前项目答案。方括号中的 requirement ID 必须与生成器 coverage catalog 一致。
+
+## 执行要求
+
+- 已覆盖：所需事实均为 `confirmed`、`user-confirmed` 或 `not-applicable`。
+- 部分覆盖：至少一项为 `inferred`、`undefined` 或缺失。
+- 已忽略：用户明确跳过模块。
+
+## 1. 架构与目录
+
+- [architecture.identity] 项目身份、业务描述、类型和技术栈。
+- [architecture.directories] 页面、共享、API、状态和资源目录边界。
+- [architecture.newDirectories] 新增目录与模块边界。
+- [architecture.language] 默认输出和文档语言。
+
+## 2. 代码质量
+
+- [code.dataContract] 数据契约、新模块和存量治理策略。
+- [code.modelPlacement] 类型、模型、mapper、normalizer、adapter 位置。
+- [code.indexMaintenance] 代码资产、复用候选和业务域地图维护。
+- [code.encapsulation] 页面私有、领域共享和项目共享边界。
+- [code.crossProject] 跨项目包和共享库策略。
+- [code.documentation] 注释、临时方案和复杂业务规则文档化。
+
+## 3. UI
+
+- [ui.stack] 组件库、主题、样式和输入来源。
+- [ui.components] 组件目录、资产清单和共享准入。
+- [ui.layoutFeedback] 布局、浮层、加载和交互反馈。
+- [ui.forms] 表单、破坏性操作和失败保留。
+- [ui.presentation] 文案、响应式、可访问性、视觉变量、图标和验收。
+
+## 4. API 与错误处理
+
+- [api.entryConfig] 统一请求入口、API 目录和基础请求配置。
+- [api.errorModel] 错误对象、错误分类和状态码类型。
+- [api.displayCatch] 默认展示和 catch 职责。
+- [api.silentCustom] 静默请求、自定义错误和后置回调。
+- [api.auth] 认证失效、权限不足、清理和并发保护。
+- [api.lifecycle] 重试、轮询、取消、过期响应和防重复提交。
+- [api.logging] 错误日志、可观测性和脱敏。
+
+## 5. 状态与数据流
+
+- [state.solution] 状态管理方案和作用域边界。
+- [state.authority] 唯一事实源和服务端权威数据。
+- [state.transform] 接口转换、派生数据和枚举标准化。
+- [state.persistence] 持久化、版本、失效、清理和账号隔离。
+- [state.transfer] 跨页面传递和 URL 参数边界。
+- [state.asyncUi] 异步一致性和 UI 数据阶段。
+
+## 6. 安全与性能
+
+- [security.credentials] 凭证、会话、清理和敏感字段。
+- [security.exposure] URL、日志、错误、埋点、截图和提交记录限制。
+- [security.permissions] 权限入口和前后端权限边界。
+- [security.paths] 部署路径、资源前缀、外链、下载和回调校验。
+- [security.dynamicContent] 上传、富文本、Markdown、动态 HTML 和预览。
+- [security.performance] 关键路径、性能预算、列表和大资源。
+- [security.cacheConcurrency] 并发、轮询、高频事件、缓存和降级。
+
+## 7. 测试、Git 与交付
+
+- [git.protected] 受保护分支和禁止直接提交范围。
+- [git.branches] 需求、修复、重构和实验分支命名。
+- [git.commits] 提交格式、语言、WIP 和整理。
+- [git.delivery] PR、CI、发布、tag 和推送边界。
+- [git.safety] 禁止提交文件和高风险 Git 授权。
+- [testing.strategy] 单元、集成、E2E、lint、类型和构建策略。
+- [testing.risk] 风险分级和最小验证范围。
+- [testing.flows] 核心业务链路和必须更新测试的场景。
+- [testing.manual] 手动回归、UI 验证和环境不可用处理。
+- [testing.boundaries] 关键数据、边界场景和剩余风险记录。
+
+## 8. 业务规则
+
+- [business.source] 权威业务规则来源。
+- [business.domains] 业务域入口和代码地图。
+- [business.risk] 高风险业务域和流程。
+- [business.enums] 状态、枚举、权限码和状态码来源。
+
+## 9. 事实治理与防过期
+
+- 每条事实必须记录状态、来源、证据和最后核验日期。
+- 模块状态必须由本检查表覆盖率计算。
+- 校验器必须检查 schema、重复 ID、非法状态、证据哈希、产物哈希、coverage、模板漂移和过期时间。
+- 人工补充规则必须写入 `project-custom.md`，生成器不得覆盖。
+- 未定义事项先检查指定入口和既有模式，仅在新增业务语义、证据冲突、高风险或不可逆选择时询问。

package/agent-rules-templates/shared/shared-security-performance.md

@@ -0,0 +1,36 @@
+# 通用安全与性能规则
+
+本文件描述跨项目安全与性能底线。凭证、路径、白名单、预算和关键链路由项目级规则定义。
+
+## 1. 凭证与敏感信息
+
+- token、session、密钥、证件号、手机号、邮箱、地址、支付信息、生产账号和内部配置默认视为敏感信息。
+- 敏感信息不得出现在 URL、日志、错误提示、埋点、截图、提交记录和公开文档中。
+- 日志和诊断信息应脱敏，不记录完整凭证和高风险业务数据。
+- 退出登录、认证失效、账号切换和权限变化时应清理相关状态、缓存和持久化数据。
+
+## 2. 权限
+
+- 前端权限只做展示和交互控制，不能替代后端鉴权。
+- 权限判断应有统一入口，避免页面各自解释权限码。
+- 权限不足与认证失效必须区分。
+
+## 3. 路径与跳转
+
+- 路由前缀、部署子路径、静态资源和 CDN 前缀应由统一配置构建。
+- 外部跳转、下载地址、重定向目标和 callback URL 应校验可信来源。
+- 第三方登录、支付、SSO、消息回调和深链不得直接拼接未经验证的用户输入。
+
+## 4. 输入与动态内容
+
+- 用户输入应按使用上下文进行校验、转义和净化。
+- 富文本、Markdown、动态 HTML、上传、预览和下载应定义类型、大小、来源和安全策略。
+- 文件名、路径和 MIME 类型不能作为唯一可信依据。
+
+## 5. 性能
+
+- 项目级规则应定义关键页面、关键交互和性能预算；未定义时至少避免明显退化。
+- 避免重复请求、无限轮询、无清理订阅、大数据一次性渲染和主线程长时间阻塞。
+- 搜索、筛选和高频事件应考虑节流、去抖、批处理或取消。
+- 列表、图片、视频、报表、导出和大文件应采用与数据规模匹配的加载策略。
+- 缓存必须定义失效、刷新、账号隔离和权限隔离。

package/agent-rules-templates/shared/shared-state-data-flow.md

@@ -0,0 +1,38 @@
+# 通用状态与数据流规则
+
+本文件描述跨项目状态原则。状态管理库、目录、事实源和持久化方式由项目级规则定义。
+
+## 1. 状态归属
+
+- 状态应放在满足需求的最低作用域：组件、页面、领域、全局、服务端缓存、持久化。
+- 临时 UI 状态、表单中间值、大型原始响应和敏感数据不应默认进入全局状态。
+- 同一业务数据应有明确唯一事实源，避免多份可写副本。
+
+## 2. 服务端数据
+
+- 服务端权威数据不得仅以前端缓存作为事实源。
+- 接口响应进入状态前，应按项目规则完成必要的提取、标准化和类型处理。
+- 金额、时间、权限、订单、支付、配置和流程状态应明确权威来源。
+
+## 3. 派生数据
+
+- 可计算数据优先通过 selector、computed、mapper 或 view model 派生，不重复存储。
+- 状态码、权限码、类型码和枚举值进入业务层前应标准化。
+- 未定义映射规则时不得猜测未知值含义。
+
+## 4. 持久化
+
+- 持久化状态应定义存储位置、版本、失效、兼容和账号隔离策略。
+- 退出登录、认证失效、账号切换、权限变化、流程完成和环境切换时应清理相关状态。
+- 敏感数据不得因方便而进入不合适的持久化介质。
+
+## 5. 跨页面传递
+
+- 路由参数、全局状态、上下文、缓存和服务端查询应按数据生命周期选择。
+- URL 不应承载 token、隐私、支付信息、复杂对象或大型 payload。
+
+## 6. 异步一致性
+
+- 应处理过期响应、并发覆盖、组件卸载、上下文切换和重复请求。
+- 复杂流程应定义恢复、取消、完成、失败和过期状态。
+- loading、empty、error、success 应与真实数据阶段一致。

package/agent-rules-templates/shared/shared-testing-quality-gates.md

@@ -0,0 +1,32 @@
+# 通用测试与质量门禁规则
+
+本文件描述跨项目验证原则。测试体系、命令、风险示例和核心链路由项目级规则定义。
+
+## 1. 风险驱动
+
+- 验证范围应与变更风险和影响面匹配。
+- 低风险至少检查 diff 和静态内容。
+- 中风险应覆盖相关页面、模块、接口或状态流程。
+- 高风险应覆盖核心业务链路、异常分支和可恢复性。
+
+## 2. 自动化测试
+
+- 项目有测试体系时，新增或修改关键逻辑应更新相应测试。
+- 项目没有测试体系时，不为了单次修改强行引入新框架。
+- 无法编写自动化测试时，使用项目定义的替代验证方式。
+
+## 3. 验证维度
+
+- 按项目需要执行 lint、类型检查、单元测试、集成测试、E2E 和构建。
+- 带 `--fix`、`--write` 或等价参数的命令会修改文件，必须与纯检查命令区分，不能作为只读质量门禁描述。
+- UI 变更应关注响应式、加载态、空态、错误态、禁用态和异常内容。
+- 数据边界应关注空值、缺失字段、未知枚举、权限不足、重复提交和异常响应。
+
+## 4. 高风险场景
+
+- 登录、权限、金额、支付、订单、发票、提交、删除、状态流转、路由、数据同步、全局请求封装和状态清理。
+
+## 5. 交付记录
+
+- 手动回归至少记录环境、步骤、输入、预期、实际结果和是否通过。
+- 验证失败、跳过验证、环境不可用和剩余风险必须在交付说明中记录。

package/agent-rules-templates/shared/shared-ui-rules.md

@@ -0,0 +1,40 @@
+# 通用 UI 规则
+
+本文件描述跨项目 UI 原则。组件库、样式方案、设计系统、断点和视觉规范由项目级规则定义。
+
+## 1. 输入优先级
+
+- 优先遵循需求文档、设计稿、设计系统、UX 规范和项目既有页面模式。
+- 输入来源冲突时，按项目索引中的规则优先级处理。
+- 需求缺少体验细节时，只做最小一致性补全，不擅自改变业务流程和产品语义。
+
+## 2. 组件与布局
+
+- 优先复用项目既有组件、布局、图标、主题变量和状态表达。
+- 页面私有组件与项目共享组件必须遵守项目目录边界。
+- 固定区域、滚动区域、弹窗、抽屉、浮层和底部操作区应有明确布局责任。
+- 文本、按钮、表格、表单和动态内容不得产生不可理解的重叠或布局跳动。
+
+## 3. 交互反馈
+
+- 首次加载、局部加载、分页加载、提交中、后台刷新应使用不同且合适的反馈。
+- 操作触发后应及时表达 loading、disabled、selected、success、error 或 empty 状态。
+- 重复点击、重复提交和异步返回期间应防止产生重复副作用。
+- 破坏性、不可逆或高风险操作应提供明确确认。
+
+## 4. 表单
+
+- 表单应定义字段限制、默认值、回填、校验时机和错误提示。
+- 提交失败后，除项目规则另有说明，应保留用户输入和可恢复状态。
+- 前端校验不能替代服务端校验。
+
+## 5. 文案与可访问性
+
+- 文案、术语、日期、金额和单位遵循项目规则和业务来源。
+- 可交互元素应有明确语义、可辨识状态和合理点击区域。
+- 弹窗、表单和键盘操作应关注焦点管理、对比度和禁用态。
+
+## 6. 验证
+
+- UI 变更应按影响范围验证目标设备、关键断点、加载态、空态、错误态和异常长文本。
+- 无法进行视觉或真机验证时，应在交付说明中记录未覆盖范围。

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "agent-rule-cli",
+  "version": "0.1.0",
+  "description": "交互式扫描项目并生成可追溯的 AI Agent 项目规则",
+  "keywords": [
+    "agent",
+    "ai",
+    "rules",
+    "agents-md",
+    "cli"
+  ],
+  "bin": {
+    "agent-rule-cli": "agent-rules-init.cjs"
+  },
+  "files": [
+    "agent-rules-init.cjs",
+    "agent-rules-templates"
+  ],
+  "scripts": {
+    "start": "node agent-rules-init.cjs",
+    "test": "node agent-rules-init.cjs --help",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}