create-yss-spec 3.0.0 → 3.1.0

package/template/.cursor/skills/yss-source-index/SKILL.md

@@ -1,63 +0,0 @@
----
-name: yss-source-index
-description: Use when YSS backend component source or frontend UI documentation changes and skill source indexes need refreshing.
----
-
-# yss-source-index
-
-Use this maintenance skill to keep YSS skills grounded in current source and documentation.
-
-中文说明：这个技能用于维护 YSS skills 的“源码索引”。后端组件库或前端文档入口变化后，运行脚本刷新引用文件。
-
-## Source Location Policy
-
-- Backend component source is environment-specific. Use `references/source-location.md` before trusting any generated path.
-- Preferred explicit setting: `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice`.
-- Frontend YSS UI components: `http://192.168.164.27:3200/components`
-- Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
-- Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
-
-## Refresh Workflow
-
-Run:
-
-```bash
-export YSS_SKILLS_ROOT="/path/to/.agents/skills"
-export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
-node "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.mjs"
-```
-
-Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
-
-The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
-
-中文说明：脚本不会复制大段源码，只会生成可追踪的文档路径、模块路径和关键 Java 入口类，方便 Agent 后续精准读取。
-
-If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
-
-## Output Contract
-
-Generated source indexes should contain:
-
-- source root and generated timestamp
-- exact source Git commit and worktree state
-- component directories and documentation files
-- Maven modules
-- key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
-- recommended next reads for Agent when performing implementation or troubleshooting
-
-Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
-
-## Freshness Gate
-
-Before exact class/config/security guidance, compare the index `Source commit` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD`. A mismatch or `dirty` indexed state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. Historical path hints may still be used only to locate current source.
-
-中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
-
-## After Refresh
-
-Validate the migrated Node helper with:
-
-```bash
-node --test "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.test.mjs"
-```

package/template/.cursor/skills/yss-source-index/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "YSS Source Index"
-  short_description: "Refresh YSS skill source indexes"
-  default_prompt: "Refresh YSS skill indexes from yss-cloud-microservice and YSS UI docs."

package/template/.cursor/skills/yss-source-index/references/source-map-config.md

@@ -1,30 +0,0 @@
-# YSS Source Index Mapping
-
-The refresh script maps component source path hints to skill references. These paths are relative to the detected or configured `YSS_SOURCE_ROOT`; they are not guaranteed to exist in every workspace.
-
-中文说明：这个文件记录“哪个组件源码目录生成到哪个 skill 的引用索引”，方便你以后维护映射关系。
-
-| Skill | Backend source path hints |
-| --- | --- |
-| `yss-cache` | `yss-microservice-components/yss-component-cache-parent` |
-| `yss-mybatis` | `yss-microservice-components/yss-component-persistence` |
-| `yss-dto` | `yss-microservice-components/yss-component-dto` |
-| `yss-audit-log` | `yss-microservice-components/yss-component-audit-log` |
-| `yss-excel-mvc` | `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter` |
-| `yss-distributed-id` | `yss-microservice-components/yss-component-distributed-id`, `yss-microservice-components/yss-component-leaf` |
-| `yss-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
-| `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
-| `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
-| `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |
-| `yss-exception` | `yss-microservice-components/yss-component-exception` |
-
-Frontend docs are written to these skills:
-
-| Skill | Frontend references |
-| --- | --- |
-| `yss-ui` | components, hooks, skills docs |
-| `yss-components` | components docs |
-| `yss-hook` | hooks docs |
-| `yss-page-module-development` | components and hooks docs |
-| `yss-use-table-height` | hooks docs |
-| `yss-use-tree-height` | hooks docs |

package/template/.cursor/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-import { execFileSync } from "node:child_process";
-import { access, mkdir, readdir, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
-const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
-const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
-const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
-const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
-const exists=async p=>{try{await access(p);return true}catch{return false}};
-async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
-const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
-function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
-async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
-function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
-async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
-export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` to reproduce or refresh.`,``,`This file is generated by \`yss-source-index/scripts/refresh-yss-skill-index.mjs\`. Do not hand-edit generated sections.`,``,`Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using \`YSS_SOURCE_ROOT\`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
- if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
- return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
-async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
-if(process.argv[1]===fileURLToPath(import.meta.url))await main();

package/template/.gemini/settings.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "yss-ui": {
-      "command": "npx",
-      "args": ["-y", "@yss-ui/mcp"]
-    }
-  }
-}

package/template/.hermes/skills/alibaba-java-code-style/SKILL.md

@@ -1,51 +0,0 @@
----
-name: alibaba-java-code-style
-description: Apply Alibaba Java Development Manual conventions when implementing, refactoring, or reviewing Java/JVM code, Spring-style services, MyBatis/ORM mappings, SQL, Maven dependencies, unit tests, exception/logging behavior, security checks, and design documentation. Use when the user asks for Java code规范, 阿里规范, P3C-style review, Java code style, or compliance with Alibaba Java coding guidelines.
----
-
-# Alibaba Java Code Style
-
-This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into execution rules for Codex. Treat rules marked mandatory as review blockers unless the repository's own `AGENTS.md`, security constraints, or existing framework conventions explicitly require a different pattern.
-
-## Workflow
-
-1. Identify the touched surface:
-   - Java source, naming, constants, OOP, collections, concurrency, control flow, comments: read `references/java-programming.md`.
-   - Exceptions, logging, unit tests, or security: read `references/reliability-test-security.md`.
-   - MySQL, ORM/MyBatis, Maven dependencies, layering, server/JVM settings, or design artifacts: read `references/database-engineering-design.md`.
-2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
-3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
-4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
-5. If a rule touches a project safety boundary such as auth, payment, encryption, raw SQL, database migration scripts, or public base library API changes, produce a draft or `TODO-HUMAN-REVIEW` rather than silently finalizing risky code.
-
-## Core Priorities
-
-- Keep names readable, English, and consistent with Java layer conventions.
-- Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
-- Make logs useful without wasting CPU, disk, or alert budget.
-- Keep unit tests automatic, independent, repeatable, and close to public behavior.
-- Bind SQL parameters, define explicit ORM mappings, and never rely on string-concatenated SQL.
-- Preserve layering: web/controller code validates and adapts; service/manager code owns business orchestration; DAO/repository code owns persistence.
-
-## Review Checklist
-
-- Naming and formatting are consistent: camel case, constants, package names, braces, spacing, line length, UTF-8/Unix line endings.
-- POJO, DTO, DO, VO, Query, enum, interface, implementation, and test names follow the expected suffixes and boolean naming rules.
-- `equals`, `hashCode`, wrapper comparisons, `toString`, `serialVersionUID`, constructors, access modifiers, and getters/setters avoid known pitfalls.
-- Collection code avoids unsafe `subList`, `Arrays.asList`, raw `toArray`, foreach removal, null-unsafe maps, and invalid comparators.
-- Thread code uses named thread pools, avoids `Executors` factories in production code, and handles locking order, date formatting, and scheduled tasks safely.
-- Exceptions are handled at the right layer, logged once with context and stack, and never swallowed or used for normal control flow.
-- Tests use assertions, avoid external dependence, live under `src/test/java`, and cover boundaries, correct cases, design cases, and error cases.
-- Security-sensitive inputs are validated, authorized, escaped, CSRF-protected, rate-limited, and never concatenated into SQL.
-- MySQL DDL/SQL/ORM code uses explicit fields, mappings, indexes, timestamps, `#{}`
-  parameter binding, and avoids dangerous cascades, stored procedures, `select *`, and uncontrolled pagination.
-
-## Source
-
-Based on the user-provided PDF: `阿里巴巴 Java 开发手册` version 1.4.0, Alibaba Group technical team, update date 2018-05-20.
-
-## 阶段 7 执行结果
-
-- 消费当前合同版本、changed files 和 verification results，只审查合同允许范围。
-- 必须把 mandatory violation 返回为 `violation`，并提供文件/位置/规则证据；高风险项保留 `TODO-HUMAN-REVIEW`。
-- 按统一 `YSS Skill Execution Result` 返回审查证据、偏离和新增安全/SQL/公共 API 影响，不得仅输出“符合规范”。

package/template/.hermes/skills/alibaba-java-code-style/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Alibaba Java Code Style"
-  short_description: "Apply Alibaba Java development guidelines"
-  default_prompt: "Use $alibaba-java-code-style to implement or review Java code against Alibaba Java development conventions."

package/template/.hermes/skills/alibaba-java-code-style/references/database-engineering-design.md

@@ -1,147 +0,0 @@
-# Database, Engineering, And Design Rules
-
-Use this reference for MySQL DDL/SQL, ORM mappings, Maven/library dependency rules, application layering, server/JVM settings, and design artifacts.
-
-## MySQL Table Design
-
-Mandatory:
-
-- Boolean database fields must be named `is_xxx` and use `unsigned tinyint`, where `1` means yes and `0` means no. POJO boolean fields must not use `is` prefix, so define explicit ORM mappings.
-- Table and field names must be lowercase letters or digits. Do not start with digits, use uppercase, or use patterns such as `level_3_name`.
-- Table names must be singular.
-- Do not use MySQL reserved words such as `desc`, `range`, `match`, or `delayed`.
-- Index names: primary key `pk_字段名`, unique index `uk_字段名`, normal index `idx_字段名`.
-- Use `decimal` for decimals. Do not use `float` or `double` for precise stored values.
-- Use `char` for nearly fixed-length strings.
-- `varchar` length must not exceed 5000. For longer content, use `text` in a separate table keyed by the primary key to avoid hurting other index efficiency.
-- Every table must include `id`, `gmt_create`, and `gmt_modified`. `id` is `bigint unsigned` primary key with auto-increment step 1 for single tables; timestamps are `datetime`.
-
-Recommended/reference:
-
-- Prefer table names like `业务名称_表作用`.
-- Keep database name aligned with application name where possible.
-- Update field comments when field meaning or status values change.
-- Redundant fields are allowed for performance only when consistency is considered, the value is not frequently changed, and the field is not long `varchar` or `text`.
-- Consider sharding only when a single table exceeds about 5 million rows or 2 GB, or when projections clearly require it.
-- Choose compact unsigned integer types where domain ranges allow.
-
-## Indexes
-
-Mandatory:
-
-- Business-unique fields must have unique indexes, even when uniqueness is also checked in application code.
-- Do not join more than 3 tables. Join column types must be exactly consistent and associated columns must have indexes.
-- When indexing `varchar`, specify an index length based on real selectivity instead of indexing the whole field.
-- Page search must not use left fuzzy or full fuzzy queries such as `%keyword` or `%keyword%`; use a search engine when needed.
-
-Recommended/reference:
-
-- For `order by`, align the ordered field with the last part of the composite index where possible, such as `where a=? and b=? order by c` with index `a_b_c`.
-- Use covering indexes to avoid table lookups where suitable.
-- For deep pagination, use delayed join/subquery techniques to locate IDs first, or cap total pages.
-- SQL optimization target: at least `range`, preferably `ref`, best `const`.
-- Put the most selective equality column on the left side of composite indexes. When mixed with range conditions, place equality conditions first.
-- Avoid implicit type conversion, which can invalidate indexes.
-- Avoid both extremes: indexing every query and resisting necessary indexes such as unique indexes.
-
-## SQL And ORM
-
-Mandatory:
-
-- Use `count(*)` for row counts, not `count(column)` or `count(constant)`.
-- Know `count(distinct col)` ignores nulls; `sum(col)` over all-null rows returns null, so guard against NPE.
-- Use `ISNULL()` or the project-standard equivalent to test nulls; direct equality comparisons with null do not behave as true/false.
-- In pagination code, return immediately when count is 0 instead of running the page query.
-- Do not use foreign keys or cascades; model those relationships in application logic for distributed/high-concurrency systems.
-- Do not use stored procedures in application code.
-- For data correction, especially delete/update, select first and confirm before mutating.
-- In queries, never use `*`; explicitly list required fields.
-- POJO boolean fields must not use `is` prefix, while database fields must use `is_`; define explicit result mappings.
-- Do not rely on `resultClass` for ORM returns. Define `resultMap` or equivalent explicit mappings.
-- MyBatis/iBATIS XML parameters must use `#{}`. Do not use `${}` for user-controlled values because it risks SQL injection.
-- Do not return raw `HashMap`/`Hashtable` as query results; use typed objects.
-- Every update to a table record must update `gmt_modified` to the current time.
-
-Recommended/reference:
-
-- Avoid large `IN` lists; keep them under about 1000 items if unavoidable.
-- For internationalized storage, use UTF-8; use `utf8mb4` when storing emoji.
-- Avoid `TRUNCATE TABLE` in application code; it has no transaction and does not trigger delete behavior.
-- Do not create a large all-fields update API. Update only changed target fields to reduce mistakes, binlog size, and work.
-- Do not overuse `@Transactional`; consider database QPS and rollback/compensation for cache, search, messages, and statistics.
-
-## Application Layering
-
-Recommended/reference:
-
-- Follow downward dependencies:
-  - Open API layer: exposes service methods as RPC/HTTP, handles gateway security and traffic controls.
-  - Terminal display layer: templates, JavaScript rendering, JSP, or mobile display.
-  - Web layer: forwarding, access control, basic parameter validation, and simple non-reused business handling.
-  - Service layer: concrete business logic.
-  - Manager layer: common business handling, third-party platform adaptation, service common capability extraction, cache/middleware handling, and DAO composition.
-  - DAO layer: persistence interaction with MySQL, Oracle, HBase, etc.
-  - External interfaces: other departments' RPC APIs, base platforms, or third-party HTTP APIs.
-- Exception handling by layer:
-  - DAO catches broad persistence exceptions and wraps them as `DAOException`; do not log again if the upper layer will log.
-  - Service logs exceptions with parameters and context.
-  - Manager follows DAO behavior when deployed with Service, or Service behavior when independently deployed.
-  - Web should not keep throwing to users; render friendly errors when the page cannot proceed.
-  - Open API converts exceptions to error code and message.
-- Domain model meanings:
-  - `DO`: database table object, passed upward by DAO.
-  - `DTO`: transfer object from Service/Manager outward.
-  - `BO`: business object output by Service.
-  - `AO`: application object between Web and Service, close to display and not highly reusable.
-  - `VO`: view object for Web/template rendering.
-  - `Query`: query request object. If a query has more than 2 parameters, wrap them; do not pass `Map`.
-
-## Maven And Library Dependencies
-
-Mandatory:
-
-- Use GAV conventions where applicable: `GroupId` as `com.{company/BU}.business[.subBusiness]`, `ArtifactId` as `product-module`, version as `major.minor.patch`.
-- Version meaning: major for direction/large incompatibility/architecture changes, minor for mostly compatible major features, patch for compatible bugfixes/minor features. Initial formal release should be `1.0.0`.
-- Online applications must not depend on `SNAPSHOT` versions except explicitly allowed security packages.
-- Adding/upgrading a library must preserve dependency mediation outside the intended functional change. Compare `dependency:resolve`/`dependency:tree` and exclude accidental differences.
-- Library APIs may define enum types and accept enum parameters, but should not return enum values or POJOs containing enum values across external library boundaries.
-- Define one version variable for a group of related libraries to avoid version drift.
-- Do not declare the same `GroupId` and `ArtifactId` with different versions across subprojects.
-
-Recommended/reference:
-
-- Put dependency declarations under `<dependencies>` and version mediation under `<dependencyManagement>`.
-- Avoid adding configuration items to reusable libraries unless truly necessary.
-- Library publishers should keep APIs/dependencies minimal and behavior stable/traceable.
-
-## Server And JVM
-
-Recommended/reference:
-
-- For high-concurrency servers, reduce TCP `time_wait` timeout where operations policy allows.
-- Increase maximum file descriptors for high concurrent connection counts.
-- Set `-XX:+HeapDumpOnOutOfMemoryError` so OOM events produce diagnostic dumps.
-- In production, set JVM `Xms` and `Xmx` to the same size to avoid heap resizing pressure after GC.
-- Use `forward` for internal redirects. Generate external redirect URLs through URL builder utilities to avoid inconsistent maintenance and potential security risk.
-
-## Design Rules
-
-Mandatory:
-
-- Storage schemes and base data structures must pass review and be documented before production execution. Data structure changes such as adding fields also need review.
-- If more than one user type interacts with the system and related use cases exceed 5, use a use-case diagram.
-- If a business object's states exceed 3, use a state diagram and define trigger conditions for state transitions.
-- If a feature call chain involves more than 3 objects, use a sequence diagram and define inputs/outputs at each call.
-- If model classes exceed 5 and dependencies are complex, use a class diagram.
-- If more than 2 objects collaborate and the process is complex, use an activity diagram with swimlanes where useful.
-
-Recommended/reference:
-
-- Consider exception flows and business boundaries during requirements analysis and system design.
-- Classes should follow single responsibility.
-- Prefer composition/aggregation over inheritance. If inheritance is necessary, obey Liskov substitution.
-- Depend on abstractions and interfaces where it improves extension and maintenance.
-- Design for extension and closed modification in stable business domains.
-- Extract common business behavior or public behavior into shared modules, config, classes, or methods to avoid duplicated code/config.
-- Do not treat agile as only stories plus coding plus release; keep necessary design and documentation for key decisions.
-- Design identifies hard parts, variation points, boundaries, module relations, evolution principles, and nonfunctional requirements such as security, availability, and extensibility.

package/template/.hermes/skills/alibaba-java-code-style/references/java-programming.md

@@ -1,178 +0,0 @@
-# Java Programming Rules
-
-Use this reference for Java implementation and review: naming, constants, formatting, OOP, collections, concurrency, control flow, comments, and general coding traps.
-
-## Naming
-
-Mandatory:
-
-- Do not start or end identifiers with `_` or `$`.
-- Do not mix pinyin and English; do not use Chinese identifiers. Widely recognized names such as `alibaba`, `taobao`, `youku`, and `hangzhou` are acceptable.
-- Use `UpperCamelCase` for classes, except suffix acronyms such as `DO`, `BO`, `DTO`, `VO`, `AO`, `PO`, and `UID`.
-- Use `lowerCamelCase` for methods, parameters, member variables, and local variables.
-- Use uppercase words separated by underscores for constants, with complete semantics such as `MAX_STOCK_COUNT`.
-- Name abstract classes with `Abstract` or `Base` prefixes, exception classes with `Exception` suffixes, and test classes as the tested class name plus `Test`.
-- Put brackets next to the type for arrays: `String[] args`, not `String args[]`.
-- Do not prefix POJO boolean properties with `is`; frameworks may mis-detect the property name. Map database `is_xxx` fields explicitly.
-- Package names must be lowercase, singular, dot-separated, and each segment should be one natural English word.
-- Avoid nonstandard abbreviations that hide meaning.
-
-Recommended/reference:
-
-- Prefer complete words for self-explanatory names.
-- If a module, interface, class, or method uses a design pattern, reflect the pattern in the name, such as `OrderFactory`, `LoginProxy`, or `ResourceObserver`.
-- Interface methods and fields should omit redundant `public` modifiers and include useful Javadoc.
-- For `Service` and `DAO`, expose interfaces and name implementations with `Impl`.
-- Capability interfaces may use adjective names such as `Translatable`.
-- Enum class names may end with `Enum`; enum members use uppercase underscores.
-- Layer method prefixes: `get` for one object, `list` for multiple objects, `count`, `save`/`insert`, `remove`/`delete`, and `update`.
-- Model suffixes: `xxxDO`, `xxxDTO`, `xxxVO`; do not name a class `xxxPOJO`.
-
-## Constants
-
-Mandatory:
-
-- Do not use magic values directly in code. Define named constants.
-- Use uppercase `L` for `long`/`Long` literals, never lowercase `l`.
-
-Recommended:
-
-- Do not keep every constant in one universal constant class. Group by function and scope.
-- Choose the smallest sensible reuse scope: cross-application library, application, submodule, package, or class-local `private static final`.
-- Use `enum` when values vary only within a fixed set, especially when values have attributes.
-
-## Formatting
-
-Mandatory:
-
-- For non-empty blocks, put `{` on the same line, newline after `{`, newline before `}`, and keep `} else {` on one line. Empty blocks may be `{}`.
-- Do not put spaces immediately inside parentheses. Put one space before `{`.
-- Put one space between reserved words and `(` for `if`, `for`, `while`, `switch`, and `do`.
-- Put one space around binary and ternary operators.
-- Use 4 spaces for indentation; do not use tab characters.
-- `//` comments must have exactly one space after the slashes.
-- Keep lines at or below 120 characters. When wrapping, indent the second line 4 spaces, keep operators and dots with the following line, wrap method arguments after commas, and do not break before `(`.
-- Add a space after commas in method definitions and calls.
-- Use UTF-8 and Unix line endings.
-
-Recommended:
-
-- Keep a single method under 80 lines, including signature, braces, code, comments, blank lines, and invisible characters.
-- Do not align variables by adding decorative spaces.
-- Insert one blank line between different logical or business sections; avoid multiple blank lines.
-
-## OOP And POJO
-
-Mandatory:
-
-- Access static members through the class name, not an object reference.
-- Add `@Override` to all overridden methods.
-- Use varargs only for same-type, same-meaning arguments; avoid `Object...`.
-- Do not change method signatures of externally used APIs or library APIs. Deprecate old interfaces with `@Deprecated` and document replacements.
-- Do not use deprecated classes or methods.
-- Call `equals` on constants or known non-null objects, or use `Objects.equals`.
-- Compare wrapper objects of the same type with `equals`, not `==`.
-- Use wrapper types for all POJO fields and RPC parameters/returns; prefer primitive types for local variables.
-- Do not set default values on DO/DTO/VO fields.
-- When adding fields to serializable classes, do not change `serialVersionUID` unless the change is intentionally incompatible.
-- Do not put business logic in constructors; use an init method or lifecycle hook.
-- POJO classes must implement `toString`; include `super.toString()` when extending another POJO.
-- Do not define both `isXxx()` and `getXxx()` for the same POJO property.
-
-Recommended:
-
-- Before indexing into `String.split` results, account for trailing separators.
-- Keep overloaded methods and multiple constructors adjacent.
-- Order methods as public/protected methods, private methods, then getters/setters, except overloaded groups.
-- Setter parameter names should match field names and use `this.field = field`.
-- Do not add business logic to getters or setters.
-- Use `StringBuilder.append` for string concatenation inside loops.
-- Use `final` for non-inheritable classes, non-overridable methods, immutable references, non-reassigned locals, or to avoid variable reuse confusion.
-- Be careful with `Object.clone`; default clone is shallow.
-- Minimize access scope: private constructors for non-instantiable classes, no public/default constructors in utility classes, private fields and methods unless broader access is truly required, and consider `final` for static fields.
-
-## Collections
-
-Mandatory:
-
-- If overriding `equals`, also override `hashCode`.
-- Objects stored in `Set` or used as `Map` keys must implement both `equals` and `hashCode`.
-- Do not cast `ArrayList.subList` results to `ArrayList`; it is a view.
-- Do not structurally modify the original list while iterating or changing a `subList`.
-- Convert collections to arrays with `toArray(new T[list.size()])`, not raw `toArray()`.
-- Do not call mutating methods on `Arrays.asList` results.
-- Respect PECS: `? extends T` is for producers/readers and cannot safely accept `add`; `? super T` is for consumers/writers and cannot safely provide typed `get`.
-- Do not remove/add elements inside foreach loops; use an `Iterator` and `iterator.remove()`. Lock the iterator if operations are concurrent.
-- Comparators must be symmetric, transitive, and handle equality consistently.
-
-Recommended:
-
-- Use diamond syntax or type inference where supported.
-- Specify initial collection capacity where size is known; for `HashMap`, use roughly `expectedSize / 0.75 + 1`, or default 16 when unknown.
-- Iterate maps with `entrySet` or `Map.forEach` when both key and value are needed.
-- Know map null support: `ConcurrentHashMap` and `Hashtable` reject null keys/values; `TreeMap` rejects null keys; `HashMap` allows null keys/values.
-- Use set uniqueness to de-duplicate rather than repeated `List.contains`.
-
-## Concurrency
-
-Mandatory:
-
-- Singleton acquisition and singleton methods must be thread-safe.
-- Name threads and thread pools meaningfully.
-- Provide thread resources through thread pools; do not create raw application threads casually.
-- Do not create production thread pools through `Executors`; use `ThreadPoolExecutor` so queue size, thread count, rejection policy, and resource limits are explicit.
-- Do not use static `SimpleDateFormat` without synchronization. Prefer `DateTimeFormatter`/`java.time`, `ThreadLocal`, or a safe date utility.
-- In high concurrency, minimize lock cost: prefer lock-free structures, small locked blocks, and object locks over class locks where suitable.
-- Keep a consistent lock acquisition order across resources to avoid deadlock.
-- For concurrent updates to one record, use application/cache locks or database optimistic locks with a `version` field; retry optimistic locks at least 3 times.
-- Prefer `ScheduledExecutorService` over `Timer` for multiple scheduled tasks, because one uncaught `TimerTask` exception stops other tasks.
-
-Recommended/reference:
-
-- With `CountDownLatch`, call `countDown` in `finally` or otherwise guarantee it runs even on exceptions.
-- Prefer `ThreadLocalRandom` over shared `Random`/`Math.random` in concurrent code.
-- If using double-checked locking on JDK 5+, declare the target field `volatile`.
-- `volatile` solves visibility for one writer/many readers but not compound writes; use `AtomicInteger`, `AtomicLong`, or `LongAdder` for counters.
-- Avoid unsynchronized high-concurrency `HashMap` resizing; use concurrent collections or locking.
-- Declare `ThreadLocal` fields as `static` when the per-thread value should be shared by all instances of the class.
-
-## Control Flow And Parameters
-
-Mandatory:
-
-- Every `switch` case must end with `break`, `return`, or a comment explaining fallthrough. Every `switch` must have a final `default`.
-- Always use braces for `if`, `else`, `for`, `while`, and `do`, even for one line.
-- In high-concurrency exit logic, avoid equality-only checks; prefer range checks that cannot be skipped by concurrent changes.
-- Do not exceed 3 levels of `if/else`; use guard clauses, strategy, or state pattern.
-
-Recommended:
-
-- Prefer guard clauses for exceptional branches.
-- Do not put complex expressions inside conditions. Assign them to well-named boolean variables first.
-- Move object creation, connection acquisition, unnecessary try/catch, and other expensive operations outside loops where possible.
-- Avoid negated logic when an equivalent positive condition is available.
-- Protect interface parameters, especially batch operations.
-- Validate parameters for low-frequency, expensive, high-stability, external, or sensitive-permission methods.
-- You may omit repeated validation for hot private or low-level methods only when callers have already validated and method docs state the expectation.
-
-## Comments And General Rules
-
-Mandatory:
-
-- Use Javadoc (`/** ... */`) for classes, fields, and methods. Do not use `//` as class or method API documentation.
-- Abstract methods and interface methods need Javadoc explaining purpose, parameters, returns, exceptions, and implementation notes.
-- Classes must include creator and creation date if the repository convention requires Alibaba manual compliance; otherwise follow local project header policy.
-- Place single-line comments above the code they explain. Align multi-line block comments with code.
-- Every enum value must have a comment explaining its purpose.
-- Precompile regular expressions; do not call `Pattern.compile` repeatedly inside method bodies.
-- Use `System.currentTimeMillis()` for current milliseconds, not `new Date().getTime()`. Use `System.nanoTime()` for elapsed time measurement; Java 8 may use `Instant`.
-
-Recommended/reference:
-
-- Prefer clear Chinese comments over awkward English; keep technical terms in English.
-- Update comments when changing parameters, returns, exceptions, or core logic.
-- Delete dead code. If temporarily commenting code, explain why above it.
-- Keep comments concise and focused on design intent, business meaning, and non-obvious logic.
-- Mark `TODO`/`FIXME` with owner, date, and expected handling time when possible.
-- Do not put complex logic in view templates.
-- Specify data structure capacity where possible.

package/template/.hermes/skills/alibaba-java-code-style/references/reliability-test-security.md

@@ -1,89 +0,0 @@
-# Reliability, Test, And Security Rules
-
-Use this reference for exception handling, logging, unit testing, and security-sensitive Java work.
-
-## Exception Handling
-
-Mandatory:
-
-- Do not catch avoidable runtime exceptions such as `NullPointerException` or `IndexOutOfBoundsException`; prevent them with prechecks.
-- Do not use exceptions for normal process or branch control.
-- Keep try blocks focused on unstable code. Catch specific exception types where behavior differs.
-- Never swallow caught exceptions. Handle them, translate them to user-understandable content at the outer business boundary, or rethrow.
-- In transactional code, if a caught exception requires rollback, explicitly trigger rollback according to the framework.
-- Always close resources and streams in `finally` or use try-with-resources. Handle close exceptions appropriately.
-- Do not `return` from a `finally` block.
-- Caught exception types must match thrown exceptions exactly or be an appropriate parent type.
-
-Recommended/reference:
-
-- A method may return `null`, but must document when that can happen. Callers remain responsible for NPE prevention.
-- Check common NPE sources: auto-unboxing wrapper return values, database nulls, null elements inside non-empty collections, remote calls, session reads, and chained calls such as `a.getB().getC()`.
-- Distinguish unchecked and checked exceptions. Avoid `new RuntimeException()`, `Exception`, or `Throwable` without business meaning; prefer domain-specific exceptions such as `DAOException` or `ServiceException`.
-- Public external HTTP/API interfaces should use error codes. Internal application code may throw exceptions. Cross-application RPC can prefer a result wrapper with success flag, code, and brief message.
-- Avoid duplicate code; extract common validation or behavior into methods/classes/components.
-
-## Logging
-
-Mandatory:
-
-- Use SLF4J facade APIs, not direct Log4j/Logback APIs:
-
-```java
-private static final Logger logger = LoggerFactory.getLogger(Abc.class);
-```
-
-- Keep application logs for at least 15 days when configuring retention.
-- Name extension logs as `appName_logType_logName.log`, where `logType` can be `stats`, `monitor`, `access`, etc.
-- For `trace`/`debug`/`info`, use placeholder logging or guard with `isXxxEnabled`; do not eagerly concatenate strings.
-- Avoid duplicate log printing, such as missing `additivity=false` in Log4j configuration.
-- Exception logs must include both scene/context information and stack trace. If not handled locally, throw upward.
-
-Recommended:
-
-- Production must not output debug logs. Emit info selectively.
-- Use `warn` for user input errors when no system fault occurred; reserve `error` for system logic errors, exceptions, or important failures.
-- Prefer English error messages where possible; use Chinese only when English would be unclear. Internationalized or overseas deployments require English logs/comments.
-- Before adding logs, ask whether someone will read them and what action they enable.
-
-## Unit Tests
-
-Mandatory:
-
-- Unit tests must follow AIR: Automatic, Independent, Repeatable.
-- Tests must be fully automated and non-interactive. Use assertions, not `System.out`, for verification.
-- Tests must not call each other or depend on execution order.
-- Tests must be repeatable and isolated from external environments such as network, remote services, or middleware. Inject local or mock dependencies.
-- Unit test granularity should be small: usually method-level, at most class-level.
-- Incremental code for core businesses, core applications, and core modules must pass unit tests.
-- Test code belongs under `src/test/java`, not production source directories.
-
-Recommended/reference:
-
-- Basic target: statement coverage at least 70%; core modules should reach 100% statement and branch coverage where feasible.
-- Use BCDE coverage thinking:
-  - Border: boundary values, loop boundaries, special values, special times, data ordering.
-  - Correct: valid inputs and expected outputs.
-  - Design: cases derived from design documents.
-  - Error: invalid data, exception flows, and disallowed business inputs.
-- Database tests should prepare data through programmatic insert/import, not manual pre-existing database edits.
-- Database tests should rollback automatically or mark generated data with a clear prefix.
-- Refactor untestable code instead of writing awkward tests to satisfy coverage.
-- Avoid business code that makes tests hard: heavy constructors, excessive globals/statics, too many external dependencies, and deep conditionals.
-
-## Security
-
-Mandatory:
-
-- User-owned pages or functions must perform authorization checks, including horizontal permission checks.
-- Sensitive user data must be masked before display, such as mobile numbers with hidden middle digits.
-- SQL parameters from users must use parameter binding or metadata-limited fields. Do not concatenate SQL strings.
-- Every user request parameter must be validated. Consider memory overflow, malicious `order by`, open redirect, SQL injection, deserialization injection, and ReDoS risks.
-- Do not output user data to HTML without proper filtering or escaping.
-- Forms and AJAX submissions must enforce CSRF protection.
-- Platform resources such as SMS, email, phone calls, orders, and payments must implement replay prevention, rate limits, fatigue control, or captcha as appropriate.
-
-Recommended:
-
-- User-generated content such as posts, comments, and instant messages should have anti-abuse, rate-limit, and prohibited-content controls.
-- Treat auth, payment, encryption, raw SQL, and database migration work as high-risk. If repository instructions mark them human-review-only, add `TODO-HUMAN-REVIEW` and do not present drafts as production-ready.