@moon791017/neo-skills 1.0.30 → 1.0.33

package/README.md

@@ -63,7 +63,10 @@
 ### 10. 需求釐清助手
 *   **需求釐清**：系統化引導用戶釐清模糊需求，並將其轉化為結構化的規格文件（背景、功能、約束、驗收標準）。
 
-### 11. 安全守衛 (Security Guard)
+### 11. AI 開發流程健檢
+*   **AI 助手開發治理 (`skills/neo-agent-harness`)**：檢查專案規則、測試、CI、審查流程與安全防護是否足夠清楚，協助 AI 助手更穩定、更安全地參與開發。
+
+### 12. 安全守衛 (Security Guard)
 *   **主動防護 (`secret-guard.ts`)**：作為 CLI 的中介軟體 (Hook)，自動攔截並掃描所有工具執行的參數。若偵測到敏感資訊（如環境設定檔、私鑰、雲端憑證等）將強制阻擋執行，防止機密外洩。
 
 ## 📂 系統架構
@@ -215,6 +218,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | **全方位程式碼審查** | `幫我 code review 剛才的修改` |
 | **生成 C# Interface** | `幫我針對這個 class 產生介面` |
 | **技術解析與架構洞察** | `分析這個專案的架構` |
+| **AI 開發流程健檢** | `幫我檢查這個專案怎麼讓 AI 助手開發得更穩、更安全` |
 
 ## 🛠 開發指南
 

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "neo-skills",
   "description": "A universal capability extension for Gemini CLI",
-  "version": "0.56.0",
+  "version": "0.57.1",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.30",
+  "version": "1.0.33",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",
@@ -20,7 +20,6 @@
     "dist",
     "bin",
     "skills",
-    "commands",
     "gemini-extension.json",
     "GEMINI.md"
   ],

package/skills/neo-agent-harness/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: neo-agent-harness
+description: 分析專案的 AI agent harnessability，設計 feedforward guides、feedback sensors、驗證流程與人類決策點，用於提升 agent 輔助開發品質。
+---
+
+# Agent Harness Architect Skill
+
+## Trigger On
+- The user asks to design or improve an AI agent development workflow.
+- The user wants coding agents to be more reliable, safer, or easier to supervise.
+- The user asks for AGENTS.md, skills, tests, CI, hooks, review loops, or project rules to be planned together.
+- The task is about harness engineering, agent harnessability, feedback loops, or "humans on the loop".
+
+## Core Principle
+Treat agent-assisted development as a controlled engineering system. Do not only improve prompts; design the guides, sensors, verification steps, and human decision points that let agents work with higher confidence.
+
+Use this skill for planning first. Do not modify files unless the user explicitly asks for implementation after the harness plan is clear.
+
+## Perceive
+1. Inspect the repository before asking questions:
+   - Project instructions: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`.
+   - Skill or prompt assets: `skills/`, `.codex/skills/`, `.claude/skills/`, `.github/skills/`.
+   - Validation commands: `package.json`, `pyproject.toml`, `Makefile`, CI workflow files, build scripts.
+   - Safety and governance: hooks, linters, formatters, secret scanners, dependency scanners.
+   - Existing documentation: README, architecture docs, ADRs, testing docs, contribution docs.
+2. Identify the project type, primary languages, current test surface, CI status, and release/deploy path.
+3. Separate discoverable repository facts from product or team preferences that require user confirmation.
+
+## Reason
+Analyze the project through these dimensions:
+
+1. **Feedforward guides**
+   - What should the agent know before editing?
+   - Examples: project rules, coding style, architecture boundaries, task decomposition, testing strategy, domain vocabulary, safe file ownership.
+2. **Feedback sensors**
+   - What can check the agent's work after each change?
+   - Examples: typecheck, tests, lint, build, static analysis, security checks, architecture tests, review agents, smoke tests.
+3. **Control type**
+   - Prefer computational controls for fast deterministic checks.
+   - Use inferential controls for semantic review, architecture judgment, test-quality review, and risk assessment.
+4. **Regulation category**
+   - Maintainability: readability, duplication, complexity, style, testability.
+   - Architecture fitness: module boundaries, performance, observability, security, deployability.
+   - Behaviour: requirements, acceptance criteria, user journeys, fixtures, manual test points.
+5. **Human role**
+   - Move human effort from repeated low-level correction to high-value decisions: scope, product fit, risk acceptance, architectural tradeoffs, and harness evolution.
+
+For detailed patterns and examples, read [reference/harness-patterns.md](reference/harness-patterns.md) when the task needs a full harness design, maturity model, or improvement roadmap. For the complete source article synthesis behind this skill, read [reference/agent-harness-engineering.md](reference/agent-harness-engineering.md) only when deeper conceptual background is needed.
+
+## Act
+Output in Traditional Chinese (Taiwan). Use this structure:
+
+### 1. 現況盤點
+- Summarize the repository facts discovered.
+- Mention the current guides, sensors, and missing signals.
+
+### 2. Harnessability 評估
+- Rate the current harnessability as `低`, `中`, or `高`.
+- Explain the rating with concrete evidence from the repository.
+
+### 3. Feedforward Guides 設計
+- List the rules, docs, skills, templates, or examples agents should receive before work starts.
+- Mark each item as existing, needs update, or missing.
+
+### 4. Feedback Sensors 設計
+- List fast local checks, CI checks, security checks, semantic reviews, and manual checks.
+- Distinguish computational from inferential checks.
+
+### 5. 開發前改善清單
+- Prioritize improvements as P0, P1, and P2.
+- P0 must focus on changes that reduce repeated agent mistakes or prevent high-risk failures.
+
+### 6. 人類決策點
+- State where humans should stay on the loop.
+- Identify decisions that should not be delegated fully to agents.
+
+### 7. 驗證方式
+- Provide exact commands or review steps when discoverable.
+- If a command is unknown, state the missing fact instead of inventing one.
+
+## Constraints
+- Do not treat AI-generated tests as sufficient proof of behaviour correctness.
+- Do not replace deterministic tooling with LLM judgment when a fast tool can check the same thing.
+- Do not recommend broad automation before the project has reliable local validation commands.
+- Do not propose fully autonomous changes for security, compliance, production deploys, or product-scope decisions.
+- Keep the output actionable and tied to repository evidence.

package/skills/neo-agent-harness/reference/agent-harness-engineering.md

@@ -0,0 +1,343 @@
+# Agent Harness Engineering and the Role of Humans in the Software Engineering Loop
+
+> This document is a summary and integration of two articles from Martin Fowler's website, focusing on practical explanations rather than word-for-word translation.
+
+## Original Sources
+
+- [Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)  
+  Author: Birgitta Boeckeler, Published: 2026-04-02
+- [Humans and Agents in Software Engineering Loops](https://martinfowler.com/articles/exploring-gen-ai/humans-and-agents.html)  
+  Author: Kief Morris, Published: 2026-03-04
+
+## One-sentence Summary
+
+The focus of AI coding agents is not just "letting the model write code," but establishing a working system (harness) for the agent to guide, check, correct, and continuously improve. Humans should not just review line-by-line at the lowest level, nor should they exit completely; instead, they should stand above the loop, designing and maintaining the agent's harness to ensure reliable software output in a controlled environment.
+
+## Core Background
+
+LLM coding agents can generate code quickly, but they have several inherent limitations:
+
+- Output is not entirely predictable.
+- They may not understand the full business context.
+- They have limited grasp of existing code, team conventions, architectural constraints, and product trade-offs.
+- They are prone to iterating in the wrong direction, wasting tokens, time, and review costs.
+
+Therefore, the key to improving agent performance is not just switching to a stronger model, but designing the environment in which it works. This environment includes specifications, documentation, templates, tests, linting, architectural checks, review agents, CI pipelines, observability data, and human decision-making processes. This entire external control system is the "harness" discussed in the articles.
+
+## What is a Harness?
+
+In a broad sense, an agent can be understood as:
+
+```text
+Agent = Model + Harness
+```
+
+In the context of coding agents, the model is the LLM responsible for reasoning and generation; the harness is the working system wrapped around the model. It may include:
+
+- System prompts, project rules, AGENTS.md, skills, and how-to guides.
+- Code retrieval, language servers, CLI tools, and MCP servers.
+- Tests, type checks, linting, static analysis, and architectural rules.
+- AI code reviews, LLM judges, and semantic checks.
+- CI/CD pipelines, production telemetry, and user journey data.
+
+A good harness has two goals:
+
+- Increase the probability of the agent getting it right the first time.
+- Enable the agent to self-correct more issues based on feedback before reaching humans.
+
+In other words, the value of a harness is to reduce the human review burden while improving system quality.
+
+## Feedforward and Feedback
+
+Harness controls can be divided into two categories.
+
+### Feedforward: Guidance Before Action
+
+Feedforward controls provide direction before the agent starts working, aiming to prevent errors. Examples include:
+
+- Coding convention documents.
+- Architectural principles.
+- Task breakdown methods.
+- Project bootstrap guides.
+- API usage specifications.
+- Technical decision records (ADRs).
+- Templates and scaffolds.
+- Codemods or fixed refactoring tools.
+
+The effect of feedforward is to increase the probability that the agent produces correct results from the start.
+
+### Feedback: Sensing and Correction After Action
+
+Feedback controls provide signals after the agent performs an action, allowing it to check and self-correct. Examples include:
+
+- Unit and integration tests.
+- Type checkers.
+- Linters.
+- Architecture fitness tests.
+- Coverage or mutation testing.
+- Semgrep or security scans.
+- AI review agents.
+- Browser smoke tests.
+- Production logs, SLOs, error rates, and latency.
+
+The effect of feedback is to ensure the agent is not just "constrained by rules" but knows whether its output is actually effective.
+
+Without feedback, the agent might repeat the same mistakes; without feedforward, the team won't know if the rules are actually having an effect. A good harness requires both.
+
+## Computational and Inferential
+
+The articles also divide guides and sensors into two execution types.
+
+### Computational Controls
+
+Computational controls are deterministic, fast, and cheap machine checks, usually executed by the CPU. Examples include:
+
+- Type checks.
+- Unit tests.
+- Linting.
+- Static analysis.
+- Structural tests.
+- Codemods.
+- Dependency checks.
+
+The advantages of these controls are stability, low cost, and repeatability, making them suitable for execution before every change, commit, or in the CI pipeline.
+
+### Inferential Controls
+
+Inferential controls are AI or LLM-based checks that require semantic judgment. Examples include:
+
+- AI code reviews.
+- LLM-as-a-judge.
+- Commentary on architectural soundness.
+- Commentary on test quality.
+- Detection of duplicate logic or over-engineering.
+- Inferring potential issues from logs.
+
+These controls can handle problems that traditional tools find difficult, but they are more expensive, slower, and less stable. They are suitable for high-value, high-risk, or late-stage checks, rather than replacing all deterministic checks.
+
+## Three Types of Harnesses
+
+### 1. Maintainability Harness
+
+The maintainability harness is used to maintain internal code quality. This is currently the easiest type to implement because existing tools are very mature.
+
+Issues covered include:
+
+- Duplicate code.
+- Excessive complexity.
+- Missing tests.
+- Inconsistent naming or formatting.
+- Violated architectural boundaries.
+- Style guide violations.
+
+Computational sensors are very effective for these issues. Inferential sensors can complement them at the semantic level, such as detecting "logic that looks different but is actually duplicate," "tests that exist but don't verify the core point," or "fixes that are too brute-force or over-engineered."
+
+However, a maintainability harness cannot fully solve requirement misunderstandings, incorrect diagnoses, or scope creep. These still require clearer specifications and human judgment.
+
+### 2. Architecture Fitness Harness
+
+The architecture fitness harness is used to maintain architectural characteristics and system quality attributes. Examples include:
+
+- Module boundaries.
+- Consistency in API design.
+- Performance requirements.
+- Observability standards.
+- Security and compliance requirements.
+- Deployment and operational constraints.
+
+Its feedforward might be architectural documents, ADRs, logging standards, or performance budgets; feedback might be architecture tests, performance tests, contract tests, observability reviews, or deployment checks.
+
+The focus of this harness is to translate "what our system looks like" into rules that an agent can read, follow, and be checked against by tools.
+
+### 3. Behaviour Harness
+
+The behavior harness is used to confirm that software functional behavior meets requirements. This is currently the most difficult type.
+
+Common practices include:
+
+- Feedforward: Providing the agent with functional specifications, user stories, and acceptance criteria.
+- Feedback: Letting the agent generate and execute tests, supplemented by coverage, mutation testing, or manual testing.
+
+The problem is that AI-generated tests themselves are not necessarily trustworthy. Tests might only verify implementation details rather than actual requirements. The articles mention "approved fixtures" as a pattern that can improve test quality in some scenarios, but it's not a universal solution for all systems.
+
+Therefore, functional correctness remains the area that most needs human product judgment and high-quality specifications.
+
+## Harnessability: Not All Systems Are Equally Easy to Harness
+
+Whether a codebase can be stably operated by an agent depends on whether it possesses enough structural clues.
+
+Systems that are easier to harness usually have:
+
+- Strongly typed languages and strict type checking.
+- Clear module boundaries.
+- Consistent frameworks and directory structures.
+- Automatable tests.
+- Clear coding conventions.
+- Architectural rules checkable by tools.
+
+Systems that are harder to harness usually have:
+
+- High technical debt.
+- Too many implicit rules.
+- Vague architectural boundaries.
+- Insufficient tests.
+- A requirement for significant tribal knowledge.
+- Highly mixed frameworks and styles.
+
+This means greenfield projects can be designed for harnessability from day one, while legacy projects need to add structure, tests, and rules before safely increasing agent autonomy.
+
+## Harness Templates
+
+Large organizations often have several common types of services, such as:
+
+- CRUD business services.
+- Event processors.
+- Data dashboards.
+- API gateways.
+- Batch jobs.
+
+If these types already have service templates, they can evolve into harness templates. That is, each service type comes built-in with:
+
+- Standard directory structure.
+- Tech stack and dependencies.
+- Generation and modification guides.
+- Test templates.
+- Architectural rules.
+- CI pipelines.
+- Security and observability checks.
+- Agent review guides.
+
+This narrows the space in which the agent can arbitrarily generate, making control more feasible. The downside is that the template itself requires version management, synchronization, and governance; otherwise, projects will gradually diverge from the upstream standard.
+
+## Three Human Positions in the Loop
+
+The second article provides another important model: where should humans stand in the loop?
+
+### Humans Outside the Loop
+
+This leaves humans in the "why loop" and lets the agent handle the "how loop." Humans only describe the desired result, and the agent decides how to construct the software.
+
+This approach is close to what's often called "vibe coding." Its appeal lies in speed and minimal intervention, but the risk is that internal quality, maintainability, cost, security, and compliance may spiral out of control.
+
+The articles remind us: we care about internal quality not because code is sacred, but because internal quality affects external outcomes. A chaotic codebase makes agents slower, more likely to get lost, and harder to modify reliably.
+
+### Humans In the Loop
+
+This keeps humans in the lowest-level coding loop, reviewing the agent's code line-by-line.
+
+This approach leverages human experience and judgment, especially when the agent gets stuck, misunderstands, or repeatedly fixes things incorrectly. The problem is that humans become the bottleneck. Agents generate code much faster than humans can review it line-by-line. If all quality assurance relies on manual review, the efficiency gains of AI are neutralized.
+
+### Humans On the Loop
+
+The articles advocate for "humans on the loop": humans do not control the agent line-by-line, nor do they exit completely; instead, they design, manage, and improve the agent's work loop.
+
+The difference can be understood as:
+
+- In the loop: Seeing an incorrect agent output and fixing it directly, or telling the agent to fix that specific output.
+- On the loop: Seeing an incorrect agent output and going back to modify the harness so that future similar outputs are more likely to be correct.
+
+This turns every error into an opportunity to improve the system, rather than just fixing a one-off problem.
+
+## Agentic Flywheel
+
+A more advanced state is the "agentic flywheel": humans not only ask the agent to build features but also ask it to analyze the harness's effectiveness and propose improvements.
+
+Implementation can start simply:
+
+1. Let the agent read tests, CI results, and review findings.
+2. Ask the agent to identify failure patterns and recurring issues.
+3. Have the agent suggest adding or modifying rules, tests, documentation, linting, or pipelines.
+4. Humans review these suggestions before assigning the agent to implement them.
+5. As trust increases, let the agent flag risks, costs, and benefits for its suggestions.
+6. Gradually automate low-risk, high-confidence improvements.
+
+Such a flywheel doesn't aim for a one-time "it mostly works," but rather makes the system progressively more capable of self-checking, self-correcting, and self-improving.
+
+## Practical Implications for Engineering Teams
+
+### 1. Don't Understand AI Engineering Only as Prompting Skills
+
+Prompts are important, but long-term reliability comes from the entire work system. Teams should view AGENTS.md, skills, specification documents, tests, linting, CI, review processes, and production feedback as a single harness rather than fragmented tools.
+
+### 2. Prioritize Moving Cheap, Stable, and Deterministic Checks Upstream
+
+Problems that can be solved with deterministic tooling should not be prioritized for LLM judgment. Type checks, linting, unit tests, formatting, and architectural rules should run as early as possible, ideally during the agent's self-correction phase.
+
+### 3. Focus Human Attention on High-Value Judgments
+
+The most valuable place for humans is not reading every line of code, but judging:
+
+- Whether requirements are clear.
+- Whether the product direction is correct.
+- Whether architectural trade-offs are reasonable.
+- Whether risks are acceptable.
+- Which technical debts are intentional and which are out of control.
+- How the harness should evolve.
+
+### 4. Turn Recurring Errors into Harness Improvements
+
+If an agent makes the same mistake multiple times, it shouldn't just be fixed each time it happens. Instead, ask:
+
+- Is a feedforward document missing?
+- Do tests need to be added?
+- Can a lint rule or static analysis be added?
+- Does AGENTS.md or a skill need to be updated?
+- Does a project-specific review checklist need to be created?
+- Can manual knowledge be turned into an automated check?
+
+### 5. Be Cautious About Functional Behavior
+
+Functional correctness is the hardest to automate fully. AI-generated tests cannot be equated directly with trustworthy acceptance. Important features still need clear specifications, acceptance criteria, manual exploratory testing, and, when necessary, domain expert reviews.
+
+## Checklist for Building a Coding Agent Harness
+
+### Phase 1: Establishing Basic Controllability
+
+- Create or update AGENTS.md, explaining project rules, workflows, testing methods, and security limits.
+- Ensure the project has one-click commands for install, test, and build.
+- Set up type checking, linting, formatting, and unit tests.
+- Document common task workflows in how-to guides or skills.
+- Ensure the agent clearly knows which files can be modified and which should not be changed manually.
+
+### Phase 2: Strengthening the Feedback Loop
+
+- Automatically execute fast tests and type checks after agent modifications.
+- Provide clear correction guidance for common failure messages.
+- Add architectural boundary checks or dependency rules.
+- Add contract tests or approval tests for important modules.
+- Feed CI results back into the agent's correction process.
+
+### Phase 3: Adding Semantic-Level Checks
+
+- Establish a code review skill or checklist.
+- Create specialized review processes for architecture, security, performance, and test quality.
+- Let AI reviews find high-risk issues first, rather than replacing all manual reviews.
+- Periodically review false positives and false negatives from AI reviews.
+
+### Phase 4: Establishing the Harness Improvement Loop
+
+- Collect common error patterns from the agent.
+- Turn recurring errors into rules, tests, documentation, or tools.
+- Periodically check that AGENTS.md, skills, CI, and linting are consistent with each other.
+- Have the agent suggest harness improvements based on CI, reviews, and production data.
+- Flag risks, costs, benefits, and automation levels for improvement suggestions.
+
+## Observations Applicable to This Project
+
+This repository itself is a collection of skills and agent work rules, making it highly suitable for management from a harness engineering perspective.
+
+Consider the following directions:
+
+- Treat each skill as a feedforward guide: it tells the agent how to act in a specific task.
+- Treat `test/*.test.js`, `bun run typecheck`, and `bun run build` as computational feedback sensors.
+- Treat `src/hooks/secret-guard.ts` and `hooks/hooks.json` as part of the security and governance harness.
+- In the future, add specialized checks for skill quality, such as SKILL.md structure, required sections, valid reference paths, and template consistency.
+- Establish a "skill review checklist" to assist in checking if instructions are clear, too broad, or in conflict with other skills using inferential review.
+
+## Most Important Conclusion
+
+The reliability of an AI agent is not produced naturally by model capability alone; it is formed by the combination of the model, context, tools, checks, feedback, and human governance.
+
+The human role should not be simplified into two extremes: either exiting completely or guarding every line. A more sustainable approach is to stand above the loop, continuously designing and improving the system in which the agent works.
+
+For teams actually delivering products, harness engineering will become a core engineering capability: gradually transforming human experience, team conventions, architectural judgment, and quality standards into a work environment that an agent can follow, execute, check, and continuously improve.

package/skills/neo-agent-harness/reference/harness-patterns.md

@@ -0,0 +1,180 @@
+# Agent Harness Patterns
+
+Use this reference when designing a complete agent harness plan or roadmap.
+
+## Core Model
+
+An agent harness is the system around the model that guides, checks, and improves agent work.
+
+```text
+Agent = Model + Harness
+```
+
+For coding agents, the useful outer harness includes:
+
+- Project instructions and task workflows.
+- Skills, templates, examples, and architectural rules.
+- Local verification commands and CI stages.
+- Hooks, linters, static analysis, and security checks.
+- AI review, architecture review, test-quality review, and human decision points.
+- Production feedback such as logs, SLOs, user journeys, and support signals.
+
+The goal is not full human removal. The goal is to reduce repeated review toil and direct human attention to product, risk, architecture, and tradeoff decisions.
+
+## Feedforward Guides
+
+Feedforward guides shape agent output before it acts.
+
+Common examples:
+
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot instructions.
+- Coding standards and style references.
+- Architecture docs, ADRs, dependency rules, module maps.
+- Task-specific skills and how-to guides.
+- Service templates, scaffolds, fixtures, and examples.
+- API docs, domain vocabulary, data contracts, and non-functional requirements.
+
+Good feedforward guides are:
+
+- Specific enough to prevent repeated mistakes.
+- Short enough to be loaded often.
+- Close to the code they govern.
+- Kept in sync with tests, CI, and review expectations.
+
+## Feedback Sensors
+
+Feedback sensors observe work after the agent acts and provide correction signals.
+
+Fast computational sensors:
+
+- Typecheck.
+- Unit tests and focused integration tests.
+- Lint and format checks.
+- Build checks.
+- Static analysis.
+- Dependency and secret scanning.
+- Architecture boundary tests.
+
+Slower or inferential sensors:
+
+- AI code review.
+- Architecture review.
+- Test-quality review.
+- Security reasoning review.
+- Log and incident analysis.
+- Behaviour or UX review against user journeys.
+
+Prefer fast deterministic sensors during local development. Reserve inferential sensors for semantic judgment, riskier changes, and later review stages.
+
+## Regulation Categories
+
+### Maintainability Harness
+
+Purpose: keep the codebase easy for humans and agents to understand and change.
+
+Signals:
+
+- Duplicate code.
+- Excessive complexity.
+- Naming or style drift.
+- Missing or weak tests.
+- Hard-to-review diffs.
+- Over-engineered or brute-force fixes.
+
+Useful controls:
+
+- Format, lint, typecheck, tests.
+- Complexity and dependency analysis.
+- Code review skill.
+- Refactoring guides and examples.
+
+### Architecture Fitness Harness
+
+Purpose: keep the system aligned with its intended structure and quality attributes.
+
+Signals:
+
+- Module boundary violations.
+- API inconsistency.
+- Performance regression.
+- Observability gaps.
+- Security or compliance drift.
+- Deployment fragility.
+
+Useful controls:
+
+- Architecture docs and ADRs.
+- Fitness functions and structural tests.
+- Contract tests.
+- Performance budgets.
+- Logging and tracing standards.
+- CI gates for risky paths.
+
+### Behaviour Harness
+
+Purpose: verify that the product does what stakeholders need.
+
+Signals:
+
+- Ambiguous requirements.
+- Tests that only mirror implementation.
+- Missing acceptance criteria.
+- Broken user journeys.
+- Manual test steps that are not captured.
+
+Useful controls:
+
+- User stories with acceptance criteria.
+- Approved fixtures or golden examples where appropriate.
+- End-to-end smoke tests for critical flows.
+- Domain expert review for high-impact behaviour.
+- Manual exploration checklist when automation is weak.
+
+Do not assume AI-generated tests prove behaviour correctness. Behaviour harnesses need clear human intent and high-quality examples.
+
+## Harnessability Assessment
+
+Rate harnessability by evidence:
+
+- **High**: clear structure, strong typing, reliable tests, CI, documented rules, repeatable build, clear ownership.
+- **Medium**: some tests and rules exist, but coverage, architecture docs, or validation commands are incomplete.
+- **Low**: weak tests, unclear structure, hidden conventions, inconsistent frameworks, no reliable local checks, or high technical debt.
+
+Common improvement sequence:
+
+1. Make setup, test, typecheck, and build commands explicit.
+2. Document project rules in the agent instruction file.
+3. Add fast computational checks before adding AI review.
+4. Add architecture or domain-specific sensors for repeated failures.
+5. Add inferential review for semantic quality and risk.
+6. Feed recurring failures back into guides, tests, hooks, or skills.
+
+## Maturity Roadmap
+
+### Level 1: Basic Control
+
+- Agent can find project rules.
+- Local validation commands are documented.
+- Secret and destructive-action rules are clear.
+- Human reviews all significant changes.
+
+### Level 2: Fast Self-Correction
+
+- Agent runs focused tests, typecheck, lint, and build after changes.
+- Failure messages are actionable.
+- Repeated mistakes become guides or checks.
+- CI repeats the local quality gates.
+
+### Level 3: Architecture-Aware Development
+
+- Agent understands module boundaries and service topology.
+- Architecture fitness checks catch drift.
+- Review process checks performance, observability, and deployability.
+- Templates encode common project shapes.
+
+### Level 4: Harness Improvement Loop
+
+- Agent reviews CI, review comments, and incidents to propose harness improvements.
+- Humans prioritize and approve harness changes.
+- Low-risk improvements can be automated after repeated success.
+- Harness quality itself is reviewed regularly.

package/skills/neo-dotnet-tag-helper/SKILL.md

@@ -1,4 +1,3 @@
-# skills/neo-dotnet-tag-helper/SKILL.md
 ---
 name: neo-dotnet-tag-helper
 version: "1.0.0"

package/skills/neo-dotnet-tag-helper/reference/coding-style.md

@@ -1,6 +1,6 @@
 # .NET Tag Helper Coding Style & Advanced Patterns
 
-This guide defines advanced coding styles and implementation patterns for ASP.NET Core Tag Helpers, specifically targeting complex UI components, extending built-in behaviors, and frontend asset management mechanisms.
+This guide defines advanced coding styles and implementation patterns for ASP.NET Core Tag Helpers, specifically targeting complex UI components, extending built-in behaviors, and frontend asset management mechanisms. **When developing Tag Helpers, developers MUST refer to the implementation patterns in the Example section (Section 3) to ensure adherence to these standards.**
 
 ## 1. Inheriting and Extending Built-in Tag Helpers
 
@@ -11,7 +11,101 @@ When you need to customize standard form elements (e.g., `<select>`), you should
 - You must explicitly set `output.TagName`; otherwise, the browser will output tags with custom names (e.g., `<select-ai-agent>`).
 - Call `await base.ProcessAsync(context, output)` to allow the base class to handle native attribute binding.
 
-### Example: Extending a Dropdown
+## 2. Mandatory Custom Tag Helper Properties & Asset Management
+
+To ensure consistency, performance, and maintainability across all custom UI components, every custom Tag Helper MUST implement the following properties and logic.
+
+### 2.1 Mandatory Properties
+
+1.  **`asp-for` (Model Binding)**: 
+    Support strong typing by including a `ModelExpression` property. This is crucial for retrieving model metadata (Name, Id, Value, Validation) and generating safe HTML identifiers.
+    ```csharp
+    [HtmlAttributeName("asp-for")]
+    public ModelExpression For { get; set; } = null!;
+    ```
+
+2.  **CSS Class Handling (UI Class)**: 
+    Tag Helpers must provide a default CSS class. If the user provides a custom class in the HTML tag:
+    - If the user class is identical to the default, maintain the default.
+    - If the user class is different, **append** it to the default class (ensure a space separator).
+    
+    ```csharp
+    [HtmlAttributeName("class")]
+    public string? CssClass { get; set; }
+
+    protected void ProcessCssClass(TagHelperOutput output, string defaultClass)
+    {
+        if (string.IsNullOrEmpty(CssClass))
+        {
+            output.Attributes.SetAttribute("class", defaultClass);
+        }
+        else if (CssClass.Trim() == defaultClass)
+        {
+            output.Attributes.SetAttribute("class", defaultClass);
+        }
+        else
+        {
+            output.Attributes.SetAttribute("class", $"{defaultClass} {CssClass.Trim()}");
+        }
+    }
+    ```
+
+3.  **`AutoLoadAssets` (Asset Management)**: 
+    Include a boolean property to control automatic resource loading, defaulting to `true`.
+    ```csharp
+    /// <summary>
+    /// Whether to automatically load corresponding JS and CSS. Default is true.
+    /// </summary>
+    [HtmlAttributeName("auto-load-assets")]
+    public bool AutoLoadAssets { get; set; } = true;
+    ```
+
+### 2.2 Inheritance and Composition Standards
+
+1.  **Independent Tag Helpers**: Any standalone custom Tag Helper representing a single UI control (e.g., a specialized dropdown) MUST inherit from the corresponding built-in ASP.NET Core Tag Helper (e.g., `SelectTagHelper`, `InputTagHelper`, `RadioTagHelper`). This leverages framework-standard model binding and validation logic.
+
+2.  **Composite Tag Helpers**: For components aggregating multiple elements (e.g., a search form):
+    - **Internal Elements**: MUST be implemented using built-in C# UI Tag Helpers to ensure they benefit from standard ASP.NET Core features.
+    - **Outer Container (`div-class`)**: MUST allow users to pass a custom CSS class via a `div-class` attribute.
+    - **CSS Consistency**: The handling of `div-class` MUST strictly follow the rules defined in **Section 2.1.2 (CSS Class Handling)**, ensuring the default container class is preserved or appended to, rather than simply overwritten.
+
+### 2.3 Mandatory Asset Loading Pattern
+
+When `AutoLoadAssets` is `true`, the Tag Helper must register its resources using the following standard pattern:
+
+- **Version Management**: Always use `IFileVersionProvider.AddFileVersionToPath` to ensure browser cache busting.
+- **De-duplication & Injection**: Use `HttpContext.AddStyle` and `HttpContext.AddScript` (see Section 3 for implementation) to ensure assets are only rendered once per page.
+
+```csharp
+public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
+{
+    // ... UI Generation Logic ...
+
+    if (AutoLoadAssets)
+    {
+        var httpContext = ViewContext.HttpContext;
+        var requestPathBase = httpContext.Request.PathBase;
+
+        // 1. Resolve Path with Version
+        string cssPath = "/css/components/my-component.css";
+        string versionedCss = _fileVersionProvider.AddFileVersionToPath(requestPathBase, cssPath);
+        
+        string jsPath = "/js/components/my-component.js";
+        string versionedJs = _fileVersionProvider.AddFileVersionToPath(requestPathBase, jsPath);
+
+        // 2. Register via Context Extensions (renders in designated Layout blocks)
+        httpContext.AddStyle($"<link rel=\"stylesheet\" href=\"{versionedCss}\" />", "MyComponentKey");
+        httpContext.AddScript($"<script src=\"{versionedJs}\"></script>", "MyComponentKey");
+    }
+}
+```
+
+
+
+## 3 Example
+
+### Extending a Dropdown
+
 ```csharp
 using Microsoft.AspNetCore.Mvc.Rendering;
 using Microsoft.AspNetCore.Mvc.ViewFeatures;
@@ -176,19 +270,22 @@ namespace [YourNamespace].TagHelpers
         }
     }
 }
+```
 
----
-
-## 2. Composite Complex UI Components and Model Binding
+### Composite Complex UI Components and Model Binding
 
 For complex UIs containing multiple elements (like a complete search form), you should use `TagBuilder` to compose the DOM structure. Using `ModelExpression` allows you to accurately bind Tag Helper attributes to ViewModel properties, retrieve the exact field name (`.Name`) for the frontend, and integrate backend permission validation logic.
 
-### Example: Composite Search Bar
-```csharp
+``` csharp
+
     /// <summary>
     /// Composite AI Report Search TagHelper.
     /// A UI component integrating date range, business unit, submission unit, inspection report menu, and search button.
     /// </summary>
+    /// <summary>
+    /// 組合式 AI 報告搜尋 TagHelper
+    /// 整合了日期範圍、檢驗單位、送檢單位、檢驗報告選單與查詢按鈕的 UI 組件
+    /// </summary>
     [HtmlTargetElement("combo-ai-report-search")]
     public class ComboAIReportSearchTagHelper : TagHelper
     {
@@ -210,66 +307,72 @@ For complex UIs containing multiple elements (like a complete search form), you
         }
 
         /// <summary>
-        /// Whether to automatically load corresponding JS and CSS, default is true.
-        /// If set to true, TagHelper automatically inserts related resource tags after the component, ensuring they load only once per request.
+        /// 是否自動載入對應的 JS 與 CSS，預設為 true
+        /// 若設定為 true，TagHelper 會自動在組件後方插入相關資源標籤，並確保單次請求僅載入一次
         /// </summary>
         [HtmlAttributeName("auto-load-assets")]
         public bool AutoLoadAssets { get; set; } = true;
 
-        #region Model Binding Attributes (Supports custom ID and Name)
+        #region Model Binding Attributes (支援自定義 ID 與 Name)
         /// <summary>
-        /// Model expression bound to start date
+        /// 繫結開始日期的模型表達式
         /// </summary>
         [HtmlAttributeName("asp-for-sdate")]
         public ModelExpression ForSDate { get; set; }
 
         /// <summary>
-        /// Model expression bound to end date
+        /// 繫結結束日期的模型表達式
         /// </summary>
         [HtmlAttributeName("asp-for-edate")]
         public ModelExpression ForEDate { get; set; }
 
         /// <summary>
-        /// Model expression bound to business unit
+        /// 繫結檢驗單位的模型表達式
         /// </summary>
         [HtmlAttributeName("asp-for-bu")]
         public ModelExpression ForBusinessUnit { get; set; }
 
         /// <summary>
-        /// Model expression bound to submission unit (HISNo)
+        /// 繫結送檢單位的模型表達式
         /// </summary>
         [HtmlAttributeName("asp-for-hisno")]
         public ModelExpression ForHISNo { get; set; }
 
         /// <summary>
-        /// Model expression bound to inspection report
+        /// 繫結檢驗報告的模型表達式
         /// </summary>
         [HtmlAttributeName("asp-for-report")]
         public ModelExpression ForAIReport { get; set; }
         #endregion
 
-        #region Class Attributes (Supports CSS customization)
+        #region Class Attributes (支援 CSS 客製化)
         [HtmlAttributeName("sdate-class")]
-        public string SDateClass { get; set; } = "form-control";
+        public string SDateClass { get; set; } = "sdate-li77"; // form-control 要預設有
 
         [HtmlAttributeName("edate-class")]
-        public string EDateClass { get; set; } = "form-control";
+        public string EDateClass { get; set; } = "edate-li77"; // form-control 要預設有
 
         [HtmlAttributeName("bu-class")]
-        public string BusinessUnitClass { get; set; } = "form-control";
+        public string BusinessUnitClass { get; set; } = "bu-li77"; // form-control 要預設有
 
         [HtmlAttributeName("hisno-class")]
-        public string HISNoClass { get; set; } = "form-control";
+        public string HISNoClass { get; set; } = "hisno-li77"; // form-control 要預設有
 
         [HtmlAttributeName("report-class")]
-        public string AIReportClass { get; set; } = "form-control";
+        public string AIReportClass { get; set; } = "ai-report-li77"; // form-control 要預設有
 
         [HtmlAttributeName("btn-class")]
-        public string BtnClass { get; set; } = "btn btn-primary";
+        public string BtnClass { get; set; } = "ai-btn-search-li77"; // btn btn-primary 要預設有
+
+        /// <summary>
+        /// 外層容器的 CSS Class。預設為 ai-report-search-container-li77
+        /// </summary>
+        [HtmlAttributeName("div-class")]
+        public string ContainerClass { get; set; } = "ai-report-search-container-li77";
         #endregion
 
         /// <summary>
-        /// Gets the current ViewContext to access HttpContext and other information
+        /// 取得目前的 ViewContext 以存取 HttpContext 等資訊
         /// </summary>
         [HtmlAttributeNotBound]
         [ViewContext]
@@ -281,89 +384,94 @@ For complex UIs containing multiple elements (like a complete search form), you
             var currentDT = _commonService.GetCurrentDateTime();
             var isSuperAdmin = currentUser.IsSuperAdminRole;
 
-            // Set outer container
+            // 設定外層容器
             output.TagName = "div";
             output.TagMode = TagMode.StartTagAndEndTag;
-            output.Attributes.SetAttribute("class", "ai-report-search-container");
 
-            // Generate IDs for menus and buttons (using CreateSanitizedId ensures IDs are safe for frontend selectors)
-            string sDateId = TagBuilder.CreateSanitizedId(ForSDate.Name, "_");
-            string eDateId = TagBuilder.CreateSanitizedId(ForEDate.Name, "_");
-            string buId = ForBusinessUnit != null ? TagBuilder.CreateSanitizedId(ForBusinessUnit.Name, "_") : "Search_BusinessUnit";
-            string hisNoId = TagBuilder.CreateSanitizedId(ForHISNo.Name, "_");
-            string reportId = TagBuilder.CreateSanitizedId(ForAIReport.Name, "_");
-            string btnId = "btnSearchAIReport";
+            // 處理自訂容器 Class，如果使用者自訂了，則把自訂的加在前面，並且保留預設的以便 JS 定位
+            string finalContainerClass = ContainerClass == "ai-report-search-container-li77"
+                ? "ai-report-search-container-li77"
+                : $"{ContainerClass} ai-report-search-container-li77";
+
+            output.Attributes.SetAttribute("class", finalContainerClass);
+
+            // 產生日選單與按鈕的 ID (一律使用 TagBuilder.CreateSanitizedId 產生)
+            string sDateId = TagBuilder.CreateSanitizedId(ForSDate?.Name ?? "Search_SDate", "_");
+            string eDateId = TagBuilder.CreateSanitizedId(ForEDate?.Name ?? "Search_EDate", "_");
+            string buId = TagBuilder.CreateSanitizedId(ForBusinessUnit?.Name ?? "Search_BusinessUnit", "_");
+            string hisNoId = TagBuilder.CreateSanitizedId(ForHISNo?.Name ?? "Search_HISNo", "_");
+            string reportId = TagBuilder.CreateSanitizedId(ForAIReport?.Name ?? "Search_AIReport", "_");
+
+            // 處理內層元素的 CSS Class，確保基底 class (form-control / btn btn-primary) 加上自定義或預設的 class
+            string finalSDateClass = SDateClass == "sdate-li77" ? "form-control sdate-li77" : $"form-control {SDateClass} sdate-li77";
+            string finalEDateClass = EDateClass == "edate-li77" ? "form-control edate-li77" : $"form-control {EDateClass} edate-li77";
+            string finalBUClass = BusinessUnitClass == "bu-li77" ? "form-control bu-li77" : $"form-control {BusinessUnitClass} bu-li77";
+            string finalHISNoClass = HISNoClass == "hisno-li77" ? "form-control hisno-li77" : $"form-control {HISNoClass} hisno-li77";
+            string finalReportClass = AIReportClass == "ai-report-li77" ? "form-control ai-report-li77" : $"form-control {AIReportClass} ai-report-li77";
+            string finalBtnClass = BtnClass == "ai-btn-search-li77" ? "btn btn-primary ai-btn-search-li77" : $"btn btn-primary {BtnClass} ai-btn-search-li77";
 
             var inputGroup = new TagBuilder("div");
             inputGroup.AddCssClass("input-group");
 
-            // 1. Start date (generate label and input)
-            inputGroup.InnerHtml.AppendHtml(CreateSpan("Date"));
-            inputGroup.InnerHtml.AppendHtml(CreateInput(sDateId, "date", SDateClass, DateTime.Now.ToString("yyyy-MM-dd"), "Start Date"));
+            // 1. 開始日期
+            inputGroup.InnerHtml.AppendHtml(CreateSpan("日期"));
+            inputGroup.InnerHtml.AppendHtml(await CreateUIAsync(ForSDate, "date", finalSDateClass, DateTime.Now.ToString("yyyy-MM-dd"), "開始日期", sDateId));
 
-            // 2. End date
-            inputGroup.InnerHtml.AppendHtml(CreateSpan("To"));
-            inputGroup.InnerHtml.AppendHtml(CreateInput(eDateId, "date", EDateClass, DateTime.Now.ToString("yyyy-MM-dd"), "End Date"));
+            // 2. 結束日期
+            inputGroup.InnerHtml.AppendHtml(CreateSpan("至"));
+            inputGroup.InnerHtml.AppendHtml(await CreateUIAsync(ForEDate, "date", finalEDateClass, DateTime.Now.ToString("yyyy-MM-dd"), "結束日期", eDateId));
 
-            // 3. Business Unit (Visible to Super Admin only)
+            // 3. 檢驗單位 (僅超級管理員可見)
             if (isSuperAdmin)
             {
-                inputGroup.InnerHtml.AppendHtml(CreateSpan("Business Unit"));
-                inputGroup.InnerHtml.AppendHtml(CreateSelect(buId, BusinessUnitClass));
+                inputGroup.InnerHtml.AppendHtml(CreateSpan("檢驗單位"));
+                inputGroup.InnerHtml.AppendHtml(await CreateUIAsync(ForBusinessUnit, null, finalBUClass, null, null, buId));
             }
 
-            // 4. Submission Unit (Automatically filtered or initialized based on permissions)
-            inputGroup.InnerHtml.AppendHtml(CreateSpan("Submission Unit"));
-            var hisNoSelect = CreateSelect(hisNoId, HISNoClass);
+            // 4. 送檢單位 (依權限自動過濾或初始化)
+            inputGroup.InnerHtml.AppendHtml(CreateSpan("送檢單位"));
+            
+            List<SelectListItem> hisNoOptions = new List<SelectListItem>();
             if (!isSuperAdmin)
             {
-                // Non-Super Admin: Pre-fetch authorized organization list and populate dropdown
+                // 非超級管理員：預先從資料庫抓取授權的組織清單
+                hisNoOptions.Add(new SelectListItem { Text = "", Value = "" });
                 var options = await GetAllowListOptionsAsync(currentUser.UserID, currentDT);
-                hisNoSelect.InnerHtml.AppendHtml("<option></option>");
-                foreach (var opt in options)
-                {
-                    var optionTag = new TagBuilder("option");
-                    optionTag.Attributes.Add("value", opt.Value);
-                    optionTag.InnerHtml.Append(opt.Text);
-                    hisNoSelect.InnerHtml.AppendHtml(optionTag);
-                }
+                hisNoOptions.AddRange(options);
             }
-            inputGroup.InnerHtml.AppendHtml(hisNoSelect);
+            inputGroup.InnerHtml.AppendHtml(await CreateUIAsync(ForHISNo, null, finalHISNoClass, null, null, hisNoId, hisNoOptions));
 
-            // 5. Inspection Report (Default empty, populated asynchronously by JS via API)
-            inputGroup.InnerHtml.AppendHtml(CreateSpan("Inspection Report"));
-            var reportSelect = CreateSelect(reportId, AIReportClass);
-            reportSelect.InnerHtml.AppendHtml("<option></option>");
-            inputGroup.InnerHtml.AppendHtml(reportSelect);
+            // 5. 檢驗報告 (預設為空，由 JS 透過 API 非同步填充)
+            inputGroup.InnerHtml.AppendHtml(CreateSpan("檢驗報告"));
+            var reportOptions = new List<SelectListItem> { new SelectListItem { Text = "", Value = "" } };
+            inputGroup.InnerHtml.AppendHtml(await CreateUIAsync(ForAIReport, null, finalReportClass, null, null, reportId, reportOptions));
 
-            // 6. Search Button
+            // 6. 查詢按鈕
             var btn = new TagBuilder("button");
             btn.Attributes.Add("type", "button");
-            btn.Attributes.Add("id", btnId);
-            btn.AddCssClass(BtnClass);
-            btn.InnerHtml.AppendHtml("<i class='fa fa-search'></i> Search");
+            btn.AddCssClass(finalBtnClass);
+            btn.InnerHtml.AppendHtml("<i class='fa fa-search'></i> 查詢");
             inputGroup.InnerHtml.AppendHtml(btn);
 
             output.Content.SetHtmlContent(inputGroup);
 
-            // Auto-load assets (integrates with project's existing asset collector pattern)
+            // 自動載入資產
             if (AutoLoadAssets)
             {
                 var httpContext = ViewContext.HttpContext;
                 
-                // 1. Load CSS (Pushed to Layout's RenderStyles for processing)
-                string cssPath = "[your-css-path]";
+                string cssPath = "/css/AIAnalysis/ComboAIReportSearch.css";
                 string vCssPath = _fileVersionProvider.AddFileVersionToPath(httpContext.Request.PathBase, cssPath);
                 httpContext.AddStyle($"<link rel=\"stylesheet\" href=\"{vCssPath}\" />", "ComboAIReportSearch");
 
-                // 2. Load JS (Pushed to Layout's RenderScripts for processing)
-                string jsPath = "[your-js-path]";
+                string jsPath = "/js/AIAnalysis/ComboAIReportSearch.js";
                 string vJsPath = _fileVersionProvider.AddFileVersionToPath(httpContext.Request.PathBase, jsPath);
                 httpContext.AddScript($"<script src=\"{vJsPath}\"></script>", "ComboAIReportSearch");
             }
         }
 
-        #region Helper Methods (Used to generate TagBuilder elements)
+        #region Helper Methods
+
         private TagBuilder CreateSpan(string text)
         {
             var span = new TagBuilder("span");
@@ -372,30 +480,105 @@ For complex UIs containing multiple elements (like a complete search form), you
             return span;
         }
 
-        private TagBuilder CreateInput(string id, string type, string className, string value, string title)
+        /// <summary>
+        /// 通用 UI 產生方法，根據是否有 ModelExpression 選擇產生方式
+        /// </summary>
+        private async Task<IHtmlContent> CreateUIAsync(ModelExpression @for, string type, string className, string value, string title, string sanitizedId, IEnumerable<SelectListItem> items = null)
+        {
+            // 如果有 ModelExpression，使用原生 TagHelper 物件
+            if (@for != null)
+            {
+                if (string.IsNullOrEmpty(type)) // Select
+                {
+                    return await CreateSelectTagHelperAsync(@for, className, sanitizedId, items);
+                }
+                else // Input
+                {
+                    return await CreateInputTagHelperAsync(@for, type, className, value, title, sanitizedId);
+                }
+            }
+
+            // 如果沒有 ModelExpression，使用 IHtmlGenerator 直接產生 (模擬 TagHelper 行為)
+            if (string.IsNullOrEmpty(type)) // Select
+            {
+                var select = _generator.GenerateSelect(
+                    ViewContext,
+                    null,
+                    sanitizedId,
+                    sanitizedId,
+                    items ?? new List<SelectListItem>(),
+                    false,
+                    new { @class = className, id = sanitizedId });
+                return select;
+            }
+            else // Input
+            {
+                var input = _generator.GenerateTextBox(
+                    ViewContext,
+                    null,
+                    sanitizedId,
+                    value,
+                    null,
+                    new { @class = className, id = sanitizedId, type = type, title = title });
+                return input;
+            }
+        }
+
+        /// <summary>
+        /// 使用 InputTagHelper 產生輸入框
+        /// </summary>
+        private async Task<IHtmlContent> CreateInputTagHelperAsync(ModelExpression @for, string type, string className, string value, string title, string sanitizedId)
         {
-            var input = new TagBuilder("input");
-            input.Attributes.Add("type", type);
-            input.Attributes.Add("id", id);
-            input.Attributes.Add("name", id);
-            input.Attributes.Add("value", value);
-            input.Attributes.Add("title", title);
-            input.AddCssClass(className);
-            return input;
+            var inputTagHelper = new InputTagHelper(_generator)
+            {
+                For = @for,
+                InputTypeName = type,
+                ViewContext = this.ViewContext
+            };
+
+            var output = new TagHelperOutput(
+                "input",
+                new TagHelperAttributeList(),
+                (useCachedResult, encoder) => Task.FromResult<TagHelperContent>(new DefaultTagHelperContent())
+            );
+
+            output.Attributes.SetAttribute("id", sanitizedId);
+            if (!string.IsNullOrEmpty(className)) output.Attributes.SetAttribute("class", className);
+            if (!string.IsNullOrEmpty(value)) output.Attributes.SetAttribute("value", value);
+            if (!string.IsNullOrEmpty(title)) output.Attributes.SetAttribute("title", title);
+
+            await inputTagHelper.ProcessAsync(new TagHelperContext(new TagHelperAttributeList(), new Dictionary<object, object>(), Guid.NewGuid().ToString()), output);
+            return output;
         }
 
-        private TagBuilder CreateSelect(string id, string className)
+        /// <summary>
+        /// 使用 SelectTagHelper 產生下拉選單
+        /// </summary>
+        private async Task<IHtmlContent> CreateSelectTagHelperAsync(ModelExpression @for, string className, string sanitizedId, IEnumerable<SelectListItem> items = null)
         {
-            var select = new TagBuilder("select");
-            select.Attributes.Add("id", id);
-            select.Attributes.Add("name", id);
-            select.AddCssClass(className);
-            return select;
+            var selectTagHelper = new SelectTagHelper(_generator)
+            {
+                For = @for,
+                Items = items ?? new List<SelectListItem>(),
+                ViewContext = this.ViewContext
+            };
+
+            var output = new TagHelperOutput(
+                "select",
+                new TagHelperAttributeList(),
+                (useCachedResult, encoder) => Task.FromResult<TagHelperContent>(new DefaultTagHelperContent())
+            );
+
+            output.Attributes.SetAttribute("id", sanitizedId);
+            if (!string.IsNullOrEmpty(className)) output.Attributes.SetAttribute("class", className);
+
+            await selectTagHelper.ProcessAsync(new TagHelperContext(new TagHelperAttributeList(), new Dictionary<object, object>(), Guid.NewGuid().ToString()), output);
+            return output;
         }
         #endregion
 
         /// <summary>
-        /// Gets the list of all authorized submission organizations for the current user
+        /// 獲取當前使用者被授權的所有送檢機構列表
         /// </summary>
         private async Task<List<SelectListItem>> GetAllowListOptionsAsync(string userId, DateTime currentDT)
         {
@@ -403,18 +586,18 @@ For complex UIs containing multiple elements (like a complete search form), you
             return authOrgs.Select(x => new SelectListItem
             {
                 Value = x.HisNo,
-                Text = $"[{x.HisNo}] {x.OrgName}"
+                Text = $"【{x.HisNo}】 {x.OrgName}"
             }).ToList();
         }
     }
 
----
+```
+
 
-## 3. Automatic Frontend Asset Loading and Deduplication (Asset Management)
+### Automatic Frontend Asset Loading and Deduplication (Asset Management)
 
 When a Tag Helper depends on specific JavaScript or CSS, developers must ensure that these resources are not loaded multiple times if the tag is used repeatedly on the same page. It is recommended to implement an asset collector pattern by extending `HttpContext.Items`.
 
-### Example: Asset Deduplication Extension Methods
 
 ```csharp
 public static partial class HtmlExtension
@@ -492,83 +675,4 @@ public static partial class HtmlExtension
 
 ---
 
-## 4. Mandatory Custom Tag Helper Properties & Asset Management
-
-To ensure consistency, performance, and maintainability across all custom UI components, every custom Tag Helper MUST implement the following properties and logic.
-
-### 4.1 Mandatory Properties
-
-1.  **`asp-for` (Model Binding)**: 
-    Support strong typing by including a `ModelExpression` property. This is crucial for retrieving model metadata (Name, Id, Value, Validation) and generating safe HTML identifiers.
-    ```csharp
-    [HtmlAttributeName("asp-for")]
-    public ModelExpression For { get; set; } = null!;
-    ```
-
-2.  **CSS Class Handling (UI Class)**: 
-    Tag Helpers must provide a default CSS class. If the user provides a custom class in the HTML tag:
-    - If the user class is identical to the default, maintain the default.
-    - If the user class is different, **append** it to the default class (ensure a space separator).
-    
-    ```csharp
-    [HtmlAttributeName("class")]
-    public string? CssClass { get; set; }
 
-    protected void ProcessCssClass(TagHelperOutput output, string defaultClass)
-    {
-        if (string.IsNullOrEmpty(CssClass))
-        {
-            output.Attributes.SetAttribute("class", defaultClass);
-        }
-        else if (CssClass.Trim() == defaultClass)
-        {
-            output.Attributes.SetAttribute("class", defaultClass);
-        }
-        else
-        {
-            output.Attributes.SetAttribute("class", $"{defaultClass} {CssClass.Trim()}");
-        }
-    }
-    ```
-
-3.  **`AutoLoadAssets` (Asset Management)**: 
-    Include a boolean property to control automatic resource loading, defaulting to `true`.
-    ```csharp
-    /// <summary>
-    /// Whether to automatically load corresponding JS and CSS. Default is true.
-    /// </summary>
-    [HtmlAttributeName("auto-load-assets")]
-    public bool AutoLoadAssets { get; set; } = true;
-    ```
-
-### 4.2 Mandatory Asset Loading Pattern
-
-When `AutoLoadAssets` is `true`, the Tag Helper must register its resources using the following standard pattern:
-
-- **Version Management**: Always use `IFileVersionProvider.AddFileVersionToPath` to ensure browser cache busting.
-- **De-duplication & Injection**: Use `HttpContext.AddStyle` and `HttpContext.AddScript` (see Section 3 for implementation) to ensure assets are only rendered once per page.
-
-```csharp
-public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
-{
-    // ... UI Generation Logic ...
-
-    if (AutoLoadAssets)
-    {
-        var httpContext = ViewContext.HttpContext;
-        var requestPathBase = httpContext.Request.PathBase;
-
-        // 1. Resolve Path with Version
-        string cssPath = "/css/components/my-component.css";
-        string versionedCss = _fileVersionProvider.AddFileVersionToPath(requestPathBase, cssPath);
-        
-        string jsPath = "/js/components/my-component.js";
-        string versionedJs = _fileVersionProvider.AddFileVersionToPath(requestPathBase, jsPath);
-
-        // 2. Register via Context Extensions (renders in designated Layout blocks)
-        httpContext.AddStyle($"<link rel=\"stylesheet\" href=\"{versionedCss}\" />", "MyComponentKey");
-        httpContext.AddScript($"<script src=\"{versionedJs}\"></script>", "MyComponentKey");
-    }
-}
-```
-```