@pigcloud/skills 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -1,71 +1,34 @@
-# Pig Skills CHANGELOG
-
-> 鐗堟湰鍙樻洿璁板綍锛岄伒寰?Semantic Versioning
-
----
-
-## [1.1.1] - 2026-06-18
-
-### Changed
-- Made postinstall client-aware so it can auto-install into the detected client(s) from `INIT_CWD`.
-- Kept Codex as the only client with a real command pack so `/spec-refinement` remains the executable entry instead of a fake alias.
-- Extended `pig-skills auto` to install the matching client folders for Codex, Claude Code, Trae, Cursor, Copilot, and Windsurf.
-- Clarified in the README and usage docs that only Codex gets `/spec-refinement`-style command files, while other clients receive skills and rules.
-- Unified the usage guides around the same client-detection and knowledge-capture model.
-
-## [1.1.0] - 2026-06-18
-
-### Changed
-- 閲嶆瀯 skill 浣撶郴璇存槑锛屾寜褰撳墠 13 涓?skill 閲嶆柊姊崇悊 README 鍜屼娇鐢ㄦ柟寮?
-- 琛ュ厖缁熶竴鏍￠獙鍏ュ彛 `validate-skills.js`锛屽苟澧炲姞 Windows / macOS / Linux 澹?
-- 灏嗕究鎼?Python 绾冲叆浠撳簱鍐咃紝閬垮厤渚濊禆绯荤粺鐜
-- 缁熶竴 `spec-refinement`銆乣knowledge-capture`銆乣workflow-router` 绛夐珮棰?skill 鐨勮瘑鍒笌闂ㄧ琛ㄨ揪
-- 鏀剁缉 skill frontmatter锛屾寜瀹樻柟 validator 瑙勮寖淇濈暀鏈€灏忓瓧娈?
-- 灏?`handover` 鍚堝苟杩?`knowledge-capture`锛屽垹闄ょ嫭绔嬩氦鎺?skill
-
-### Added
-- `validate-skills.js`
-- `validate-skills.cmd`
-- `validate-skills.sh`
-- `.tools/python.cmd`
-- `.tools/python.sh`
-
-## [1.0.0] - 2024-01-20
-
-### Added
-- 鍒濆鍙戝竷锛屽寘鍚?12 涓鏋剁粦瀹氭妧鑳?
-- OpenSpec 鏍囧噯鍖栬鑼?
-- 涓夊眰娓愯繘寮忓姞杞芥満鍒?
-- 璺ㄥ伐鍏峰吋瀹规敮鎸侊紙Trae/Cursor/Claude Code/Copilot/Windsurf锛?
-- CLI 宸ュ叿锛坧ig-skills 鍛戒护锛?
-
-### Skills
-- **Core**: workflow-router, technical-design, feature-build, code-review
-- **Analysis**: spec-refinement, domain-modeling
-- **Integration**: api-contract-docs, test-design
-- **Collaboration**: knowledge-capture
-- **Infrastructure**: project-bootstrap, environment-deploy
-
-### Core Bindings
-- Controller 鈫?Service 鈫?Mapper 鍒嗗眰
-- MpRealDelEntity / MpLogicDelEntity 鍩虹被
-- Result<T> 缁熶竴杩斿洖
-- BizException 寮傚父浣撶郴
-- Lambda 鏌ヨ琛ㄨ揪寮?
-
----
-
-## 璁″垝鏇存柊
-
-### [1.2.0] - TBD
-- 鎶€鑳芥ā鏉垮彲瑙嗗寲
-- 鎶€鑳界粍鍚堢紪鎺掑櫒
-- 鏇村妗嗘灦鐗瑰畾瑙勫垯
-
-### [2.0.0] - TBD
-- 鎶€鑳藉彂甯冨钩鍙?
-- 鎶€鑳借闃呮満鍒?
-- 澶氭鏋舵敮鎸?
-
-
-
+# Pig Skills Changelog
+
+> 版本变更记录，遵循 Semantic Versioning。
+
+## [1.1.1] - 2026-06-18
+
+- 调整 postinstall，让它能根据当前客户端自动安装到对应工作区。
+- 保持 Codex 的命令包入口可用，让 `/spec-refinement` 仍然是可执行入口。
+- 扩展 `pig-skills auto`，支持 Codex、Claude Code、Trae、Cursor、Copilot 和 Windsurf。
+- 在 README 和使用文档中统一说明：不同客户端共享同一套 skills 和 rules，但命令入口不同。
+- 统一客户端检测、知识沉淀和交付说明。
+
+## [1.1.0] - 2026-06-18
+
+- 重构技能体系说明，按当前 13 个 skill 重新整理 README 和使用方式。
+- 补充统一校验入口 `validate-skills.js`，并增加 Windows / macOS / Linux 支持。
+- 将便携 Python 纳入仓库内，避免依赖系统环境。
+- 统一 `spec-refinement`、`knowledge-capture`、`workflow-router` 等高频 skill 的识别与门禁表达。
+- 收缩 skill frontmatter，按官方 validator 规范保留最小字段。
+- 将 `handover` 合并入 `knowledge-capture`，删除独立交接 skill。
+
+## [1.0.6] - 2026-06-23
+
+- 将包名迁移为 `@pigcloud/skills`。
+- 统一 Codex、Trae、Claude Code 的安装和更新说明。
+- 收拢技能命名，让名称更直观、更容易理解。
+
+## [1.0.5] - 2026-06-18
+
+- 初始发布，包含 12 个框架绑定技能。
+- 建立 OpenSpec 标准化说明。
+- 引入三层渐进式加载机制。
+- 支持 Trae / Cursor / Claude Code / Copilot / Windsurf 等工具。
+- 提供 `pig-skills` CLI 工具。

package/README.md

@@ -1,76 +1,54 @@
-# @pigcloud/skills
-
-> 涓€涓潰鍚戜骇鍝併€佺爺鍙戙€佹祴璇曞崗浣滅殑 AI 鎶€鑳藉寘銆俙skills/` 璐熻矗浠诲姟杈圭晫涓庝氦鎺ワ紝`rules/` 璐熻矗瑙勫垯绾︽潫涓庢牎楠岋紝`workflow-router` 璐熻矗闃舵璺敱锛宍CI / Test / Evidence` 璐熻矗浜や粯闂幆銆?
-
-## 杩欏绯荤粺鍋氫粈涔?
-
-- 鍏堣矾鐢憋紝鍐嶆墽琛?
-- 鍏堢害鏉燂紝鍐嶇敓鎴?
-- 鍏堝鐢紝鍐嶆敼鍐?
-- 鍏堥獙璇侊紝鍐嶇粨璁?
-
-## 鏍稿績灞?
-
-1. `workflow-router`锛氳瘑鍒换鍔＄被鍨嬪苟閫夋嫨涓嬩竴闃舵
-2. `skills/`锛氬彲澶嶇敤鐨勮兘鍔涙ā鍧?
-3. `rules/`锛氶」鐩害鏉熴€佽竟鐣屽拰纭牎楠?
-4. `CI / Test / Evidence`锛氬彲楠岃瘉鐨勪氦浠橀棬绂?
-
-## 甯哥敤鍏ュ彛
-
-- 瑙勬牸婢勬竻锛歚spec-refinement`
-- 闃舵璺敱锛歚workflow-router`
-- 璁捐涓庡疄鐜帮細`technical-design` / `feature-build`
-- 瀹℃煡涓庨獙璇侊細`code-review` / `security-audit` / `performance-audit`
-- 浜嬪疄鎶藉彇锛歚business-fact-extraction`
-- 鐭ヨ瘑娌夋穩锛歚knowledge-capture`
-
-## 瀹夎
-
-```bash
-npm install -g @pigcloud/skills
-```
-
-## 瀹㈡埛绔帴鍏?
-
-- Codex锛氳 [docs/CODEX-APP-GUIDE.md](docs/CODEX-APP-GUIDE.md)
-- Trae锛氳 [docs/TRAE-GUIDE.md](docs/TRAE-GUIDE.md)
-- Claude Code锛氳 [docs/CLAUDE-CODE-GUIDE.md](docs/CLAUDE-CODE-GUIDE.md)
-- 缁熶竴瀹夎鎸囧崡锛氳 [docs/client-installation-guide.md](docs/client-installation-guide.md)
-
-## 娌荤悊姒傝
-
-- 绯荤粺鎬昏锛氳 [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
-- 鎶€鑳芥墿灞曟寚鍗楋細瑙?[docs/skills-extension-guide.md](docs/skills-extension-guide.md)
-
-## 鏍￠獙
-
-```bash
-node validate-skills.js
-node scripts/validate-skill-shapes.js
-node scripts/validate-rules.js
-node scripts/validate-skill-stop-rules.js
-node scripts/validate-skill-replay-signals.js
-node self-test-skills.js
-```
-
-## 鐩綍璇存槑
-
-- `skills/`锛氭妧鑳芥鏂?
-- `skills/references/`锛氱紪鍐欐爣鍑嗐€佸弬鑰冪煩闃点€佸姞杞芥槧灏?
-- `rules/`锛氳鍒欏叆鍙ｄ笌瑙勫垯鍖?
-- `docs/`锛氬畨瑁呫€佹不鐞嗗拰宸ヤ綔娴佽鏄?
-- `bin/`锛欳LI銆佽嚜鍔ㄥ畨瑁呫€乸ostinstall
-
-## 鍏ュ彛鏂囨。
-
-- [AGENTS.md](AGENTS.md)
-- [docs/README.md](docs/README.md)
-- [docs/client-installation-guide.md](docs/client-installation-guide.md)
-- [docs/agent-governance-overview.md](docs/agent-governance-overview.md)
-- [docs/skills-extension-guide.md](docs/skills-extension-guide.md)
-- [skills/references/skill-authoring-standard.md](skills/references/skill-authoring-standard.md)
-- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
-- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)
-
-
+# @pigcloud/skills
+
+> 一个面向产品、研发、测试协作的 AI 技能包。`skills/` 负责任务边界与交接，`rules/` 负责规则约束与校验，`workflow-router` 负责阶段路由，`CI / Test / Evidence` 负责交付闭环。
+
+## 这套系统做什么
+
+- 先路由，再执行
+- 先约束，再生成
+- 先复用，再改造
+- 先验证，再结论
+
+## 核心层
+
+1. `workflow-router`：识别任务类型并选择下一阶段
+2. `skills/`：可复用的能力模块
+3. `rules/`：项目约束、边界和硬校验
+4. `CI / Test / Evidence`：可验证的交付门槛
+
+## 常用入口
+
+- 规格细化：`spec-refinement`
+- 阶段路由：`workflow-router`
+- 设计与实现：`technical-design` / `feature-build`
+- 审查与验证：`code-review` / `security-audit` / `performance-audit`
+- 事实提取：`business-fact-extraction`
+
+## 安装
+
+```bash
+npm install -g @pigcloud/skills
+```
+
+安装后可使用 `pig-skills` CLI。
+
+## 目录说明
+
+- `skills/`：技能定义与交接边界
+- `skills/references/`：编写标准、参考矩阵、加载映射
+- `rules/`：规则入口与规则覆盖层
+- `docs/`：安装、治理和工作流说明
+- `bin/`：CLI 与自动安装逻辑
+
+## 客户端安装指南
+
+具体的 Codex、Trae、Claude Code 安装方式见 [docs/client-installation-guide.md](docs/client-installation-guide.md)。
+
+## 相关文档
+
+- [README.en.md](README.en.md)
+- [docs/README.md](docs/README.md)
+- [docs/client-installation-guide.md](docs/client-installation-guide.md)
+- [skills/references/skill-reference-matrix.md](skills/references/skill-reference-matrix.md)
+- [skills/references/rule-loading-map.md](skills/references/rule-loading-map.md)
+- [rules/index.md](rules/index.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pigcloud/skills",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "面向 Codex、Trae 和 Claude Code 的 AI 技能包，提供共享技能、规则约束、工作流路由和 Pig Cloud 专属覆盖层。",
   "author": "Pig Skills Maintainers",
   "license": "MIT",

package/rules/coding/implementation.md

@@ -1,31 +1,26 @@
-# Coding Implementation Rules
-
-## 榛樿鍋氭硶
-
-- Implement only the confirmed scope.
-- Keep the change small, reviewable, and verifiable.
-- Preserve the agreed boundary while coding.
-- Prefer one implementation path over speculative alternatives unless the task explicitly asks for options.
-
-## 绂佸尯
-
-- Do not rewrite the spec-refinement while implementing.
-- Do not widen the scope because implementation is difficult.
-- Do not skip validation.
-- Do not bundle unrelated cleanup into the same change unless it reduces risk.
-
-## 妫€鏌?
-
-- Does the code stay within scope?
-- Can the result be validated locally?
-- Is the implementation easy to review in one pass?
-- Would the diff still make sense if the task title were removed?
-
-## 鍥炴斁淇″彿
-
-- Trigger when the request is about delivery, refactor, or code changes.
-
-## References
-
-- `coding/index.md`
-
+# Coding Implementation Rules
+
+## 默认做法
+
+- Implement only the confirmed scope.
+- Keep the change small, reviewable, and verifiable.
+- Preserve the agreed boundary while coding.
+- Prefer one implementation path over speculative alternatives unless the task explicitly asks for options.
+
+## 禁区
+
+- Do not rewrite the spec-refinement while implementing.
+- Do not widen the scope because implementation is difficult.
+- Do not skip validation.
+- Do not bundle unrelated cleanup into the same change unless it reduces risk.
+
+## 检查
+
+- Does the code stay within scope?
+- Can the result be validated locally?
+- Is the implementation easy to review in one pass?
+- Would the diff still make sense if the task title were removed?
+
+## 回放信号
+
+- Trigger when the task is about implementing a confirmed change.

package/rules/product/project-context.md

@@ -1,30 +1,29 @@
-# Project Context Rules
-
-## 榛樿鍋氭硶
-
-- Capture what the current project already guarantees before rewriting the requirement.
-- Separate product intent, existing project facts, and assumptions.
-- Prefer current repo docs, release notes, and existing behavior over memory.
-- Record conflicts when product demand does not match current project facts.
-
-## 绂佸尯
-
-- Do not turn implementation details into product requirements.
-- Do not ignore existing project facts when they are available.
-- Do not hide conflicts behind vague wording.
-
-## 妫€鏌?
-
-- Are product intent and project facts separated?
-- Are conflicts and open questions explicit?
+# Project Context Rules
+
+## 项目上下文规则
+
+- Capture what the current project already guarantees before rewriting the requirement.
+- Separate product intent, existing project facts, and assumptions.
+- Prefer current repo docs, release notes, and existing behavior over memory.
+- Record conflicts when product demand does not match current project facts.
+
+## 禁区
+
+- Do not turn implementation details into product requirements.
+- Do not ignore existing project facts when they are available.
+- Do not hide conflicts behind vague wording.
+
+## 检查项
+
+- Are product intent and project facts separated?
+- Are conflicts and open questions explicit?
 - Does the output still work for spec-refinement?
-- Is the project context based on current evidence?
-
-## 鍥炴斁淇″彿
-
-- Trigger when the task needs product understanding aligned with the current project state.
-
-## References
-
-- `product/index.md`
-
+- Is the project context based on current evidence?
+
+## 触发信号
+
+- Trigger when the task needs product understanding aligned with the current project state.
+
+## References
+
+- `product/index.md`

package/skills/code-review/references/template-review.md

@@ -1,214 +1,39 @@
-# 代码评审报告模板
-
-> 用于 code-review Skill 输出的标准格式
-
----
-
-## 模板内容
-
-```markdown
-# 代码评审报告
-
-## 评审概要
-
-| 字段 | 内容 |
-|------|------|
-| 评审时间 | {datetime} |
-| 评审文件数 | {count} |
-| 变更行数 | +{add} / -{del} |
-| 评审耗时 | {duration} |
-| 规则覆盖率 | {coverage}% |
-| Rubric 评分 | {score}/10 |
-
----
-
-## 问题列表
-
-### P0 问题（阻断性 - 必须修复）
-
-#### 问题 #1
-
-| 字段 | 内容 |
-|------|------|
-| 文件 | `{filePath}` |
-| 行号 | {lineNumber} |
-| 规则 | {ruleId}: {ruleName} |
-| 类型 | MUST / NEVER |
-| 问题 | {问题描述} |
-| 代码 | `{问题代码片段}` |
-| 修复 | `{修复建议}` |
-| 依据 | [规则定义](references/rules.md#{ruleId}) |
-
----
-
-### P1 问题（严重 - 必须修复）
-
-#### 问题 #2
-
-| 字段 | 内容 |
-|------|------|
-| 文件 | `{filePath}` |
-| 行号 | {lineNumber} |
-| 规则 | {ruleId}: {ruleName} |
-| 类型 | MUST / NEVER |
-| 问题 | {问题描述} |
-| 代码 | `{问题代码片段}` |
-| 修复 | `{修复建议}` |
-| 依据 | [规则定义](references/rules.md#{ruleId}) |
-
----
-
-### P2 问题（最佳实践 - 建议修复）
-
-#### 问题 #3
-
-| 字段 | 内容 |
-|------|------|
-| 文件 | `{filePath}` |
-| 行号 | {lineNumber} |
-| 规则 | {ruleId}: {ruleName} |
-| 问题 | {问题描述} |
-| 修复 | `{修复建议}` |
-
----
-
-### P3 问题（建议改进）
-
-#### 问题 #4
-
-| 字段 | 内容 |
-|------|------|
-| 文件 | `{filePath}` |
-| 规则 | {ruleId}: {ruleName} |
-| 问题 | {问题描述} |
-| 建议 | `{改进建议}` |
-
----
-
-## 跨模块影响分析
-
-### 变更文件
-
-| 文件 | 类型 | 模块 |
-|------|------|------|
-| `{filePath}` | 新增 / 修改 / 删除 | `{module}` |
-
-### 影响模块
-
-| 模块 | 影响类型 | 变更内容 | 建议 |
-|------|----------|----------|------|
-| `{module}` | API变更 / 依赖变更 / 数据变更 | `{content}` | `{suggestion}` |
-
-### 依赖关系图
-
-```
-{moduleA} → {moduleB} → {moduleC}
-    ↓
-{moduleD}
-```
-
----
-
-## 安全检查结果
-
-| 维度 | 结果 | 问题数 | 详情 |
-|------|------|--------|------|
-| 硬编码 | ✅ / ⚠️ | {count} | {details} |
-| 日志 | ✅ / ⚠️ | {count} | {details} |
-| SQL注入 | ✅ / ⚠️ | {count} | {details} |
-| XSS | ✅ / ⚠️ | {count} | {details} |
-
----
-
-## 性能检查结果
-
-| 维度 | 结果 | 问题数 | 详情 |
-|------|------|--------|------|
-| N+1查询 | ✅ / ⚠️ | {count} | {details} |
-| Left-fuzzy LIKE | ✅ / ⚠️ | {count} | {details} |
-| 批量操作 | ✅ / ⚠️ | {count} | {details} |
-
----
-
-## Rubric 自检结果
-
-| 规则 | 结果 | 说明 |
-|------|------|------|
-| R1: 渐进式加载 | ✅ / ⚠️ | {message} |
-| R2: 规则覆盖率 | ✅ / ⚠️ | {coverage}% |
-| R3: 位置准确性 | ✅ / ⚠️ | 偏差 {diff} 行 |
-| R4: 可解释性 | ✅ / ⚠️ | {coverage}% |
-| R5: 问题分级 | ✅ / ⚠️ | {message} |
-| R6: 跨模块影响 | ✅ / ⚠️ | {message} |
-| R7: 输出格式 | ✅ / ⚠️ | {message} |
-| R8: 确认节点 | ✅ / ⚠️ | {message} |
-| R9: Pre-Delivery | ✅ / ⚠️ | {message} |
-| R10: 反 Slop | ✅ / ⚠️ | {message} |
-
----
-
-## 评审结论
-
-| 结论 | 条件 | 当前状态 |
-|------|------|----------|
-| ✅ 通过 | 0 个 P0/P1 问题 | {status} |
-| ⚠️ 需修改后通过 | 有 P0/P1 问题，修复后重新评审 | {status} |
-| ❌ 不通过 | >5 个 P0 问题 | {status} |
-
----
-
-## 下一步建议
-
-1. {修复建议1}
-2. {修复建议2}
-3. 执行 `mvn compile -q` 验证编译
-4. 执行 `mvn test -q` 验证测试
-5. 重新提交评审
-
----
-
-## 评审人
-
-| 字段 | 内容 |
-|------|------|
-| 评审工具 | pig-skills code-review v{version} |
-| 评审模型 | {model} |
-| Rubric 评分 | {score}/10 |
-
----
-
-*报告生成时间: {timestamp}*
-```
-
----
-
-## 使用说明
-
-### 填充变量
-
-| 变量 | 来源 |
-|------|------|
-| `{datetime}` | 当前时间 |
-| `{count}` | Git diff 文件数 |
-| `{add}` / `{del}` | Git diff 行数统计 |
-| `{duration}` | 评审耗时 |
-| `{coverage}` | lint 脚本计算 |
-| `{score}` | Rubric 自检结果 |
-| `{filePath}` | 变更文件路径 |
-| `{lineNumber}` | lint 脚本定位 |
-| `{ruleId}` | 规则ID（MUST-001 等） |
-| `{ruleName}` | 规则名称 |
-| `{module}` | 模块名称（包路径） |
-
-### 输出位置
-
-```
-.agents/specs/REVIEW-{timestamp}.md
-```
-
-### 命名规则
-
-```
-REVIEW-{YYYYMMDD}-{HHMMSS}.md
-例如: REVIEW-20260616-143000.md
-```
+# 代码审查报告模板
+
+> 代码审查结果的标准输出格式，用于保持结论清晰、可复核、可归档。
+
+---
+
+## 基本信息
+
+| 字段 | 说明 |
+|------|------|
+| 审查时间 | {datetime} |
+| 审查对象 | {repo / branch / pr} |
+| 审查人 | {reviewer} |
+| 审查范围 | {diff / files / modules} |
+
+## 结论摘要
+
+- 总体结论：{pass / pass with comments / fail}
+- 风险等级：{low / medium / high}
+- 是否建议合并：{yes / no}
+
+## 发现项
+
+| 等级 | 文件 | 问题 | 建议 |
+|------|------|------|------|
+| P0 | {file} | {issue} | {fix} |
+| P1 | {file} | {issue} | {fix} |
+| P2 | {file} | {issue} | {fix} |
+
+## 验证信息
+
+- 已运行的检查：{lint / test / manual check}
+- 未覆盖的风险：{gaps}
+- 需要补充的证据：{evidence}
+
+## 备注
+
+- 如果没有发现问题，也要明确说明“未发现阻断项”。
+- 如果有假设，要明确标注假设来源。

package/skills/domain-modeling/references/distillation-checklist.md

@@ -1,152 +1,44 @@
-# 蒸馏质量验收检查清单
-
-> 用于验证蒸馏产物是否符合规范
-
----
-
-## 静态检查清单
-
-### 目录结构检查
-
-- [ ] `distilled/` 目录存在
-- [ ] `README.md` 存在且内容完整
-- [ ] `00-overview.md` 存在且包含"给 AI 的关键约定"
-- [ ] `01-glossary.md` 存在
-- [ ] `domain/_index.md` 存在
-- [ ] `domain/<对象>.md` 每个核心对象一个文件
-- [ ] `api/_index.md` 存在且包含典型编排
-- [ ] `api/<域>/<用例>.md` 每个用例一个文件
-- [ ] `reference/schema/*.md` 字段级 Schema
-- [ ] `reference/enums.md` 存在
-- [ ] `reference/error-codes.md` 存在
-- [ ] `reference/model-code-conflicts.md` 存在
-- [ ] `requirements/_index.md` 存在
-
----
-
-### 领域对象检查
-
-- [ ] 每个对象有"一句话定义"
-- [ ] 每个对象有"业务语义"段落
-- [ ] 每个对象有"生命周期/状态"段落
-- [ ] 每个对象有"关键属性"表（语义级）
-- [ ] 每个对象有"组合/关系"说明
-- [ ] 每个对象有"核心业务规则"段落
-- [ ] 每条规则有执行方标注（【服务端强制】/【调用方需预判】等）
-- [ ] 每个对象有"相关能力"链接
-- [ ] 每个对象有"明细索引"
-
----
-
-### API 接口检查
-
-- [ ] 每个接口有"业务场景"说明
-- [ ] 每个接口有"能力边界"说明（做什么/不做什么）
-- [ ] 每个接口有"输入"表（参数/类型/必填/说明/约束）
-- [ ] 每个接口有"输出"表（字段/说明）
-- [ ] 每个接口有"关键规则"段落
-- [ ] 每条规则有执行方标注
-- [ ] 每个接口有"涉及的数据对象"链接
-- [ ] 每个接口有"可能的错误"表
-- [ ] 每个接口有"调用示例"（真实可用）
-- [ ] 每个接口有"写权限分级"
-
----
-
-### 明细层检查
-
-- [ ] Schema 表有"对应领域属性/API字段"列
-- [ ] 枚举表有 ✅/⚠️ 标记
-- [ ] 错误码表有"AI 应如何向用户解释"列
-- [ ] 冲突清单有"本体/需求"、"代码"、"AI 影响"三列
-
----
-
-### 交叉引用检查
-
-- [ ] 所有链接使用 `[[slug]]` 格式
-- [ ] 对象↔接口↔Schema 三者互相链接
-- [ ] 无明显断链（链接目标不存在但未标记"待补")
-
----
-
-### 命名规范检查
-
-- [ ] 文件名使用小写 kebab-case
-- [ ] API 字段沿用代码实际返回的命名
-- [ ] 枚举值使用业务实际值（含中文）
-
----
-
-## 动态验证清单
-
-### 读/查询场景
-
-| 测试 | 验证内容 | 结果 |
-|------|----------|------|
-| 名称→ID 解析 | AI 能正确调用主数据接口解析名称 | ✅/❌ |
-| 查询参数 | AI 能正确构造查询参数 | ✅/❌ |
-| 结果解读 | AI 能正确解读返回结果 | ✅/❌ |
-
-### 写/录入场景
-
-| 测试 | 验证内容 | 结果 |
-|------|----------|------|
-| 必填字段 | AI 能识别必填字段并提示用户 | ✅/❌ |
-| 用例编排 | AI 能按正确顺序调用接口 | ✅/❌ |
-| 服务端维护字段 | AI 不传入服务端维护字段 | ✅/❌ |
-| 回显确认 | 写操作前回显给用户确认 | ✅/❌ |
-
-### 统计场景
-
-| 测试 | 验证内容 | 结果 |
-|------|----------|------|
-| 口径理解 | AI 能正确理解统计接口口径 | ✅/❌ |
-| 参数构造 | AI 能正确构造统计参数 | ✅/❌ |
-
-### 规则反例场景
-
-| 测试 | 验证内容 | 结果 |
-|------|----------|------|
-| 规则预判 | AI 能预判违反规则的错误 | ✅/❌ |
-| 错误解释 | AI 能根据 error-codes.md 解释错误 | ✅/❌ |
-
----
-
-## 验证结论
-
-| 检查项 | 通过数 | 总数 | 通过率 |
-|--------|--------|------|--------|
-| 目录结构 | | 13 | |
-| 领域对象 | | 9 | |
-| API 接口 | | 10 | |
-| 明细层 | | 4 | |
-| 交叉引用 | | 3 | |
-| 命名规范 | | 3 | |
-| 动态验证 | | 12 | |
-
-**总通过率要求**: >= 90%
-
----
-
-## 验证记录
-
-| 日期 | 验证人 | 通过率 | 备注 |
-|------|--------|--------|------|
-| | | | |
-
----
-
-## 发现的问题
-
-1. 
-2. 
-3. 
-
----
-
-## 修复计划
-
-| 问题 | 修复方案 | 状态 |
-|------|----------|------|
-| | | 待修复/已修复 |
+# 领域提炼检查清单
+
+> 用于检查领域建模提炼结果是否满足规范、是否可交接、是否可复用。
+
+---
+
+## 目录结构
+
+- [ ] `distilled/` 目录已创建
+- [ ] `README.md` 已说明提炼目标
+- [ ] `00-overview.md` 已说明 AI 的关键约束
+- [ ] `01-glossary.md` 已收录术语
+- [ ] `domain/_index.md` 已建立索引
+- [ ] `domain/<name>.md` 每个核心域有独立文件
+- [ ] `api/_index.md` 已建立接口索引
+- [ ] `api/<group>/<name>.md` 每个接口组都有独立文件
+- [ ] `reference/schema/*.md` 字段级 Schema 已整理
+- [ ] `reference/enums.md` 枚举已整理
+
+## 内容检查
+
+- [ ] 领域边界已明确
+- [ ] 核心概念已抽取
+- [ ] 术语表与代码命名一致
+- [ ] 当前事实与推断已区分
+- [ ] 关键不变量已记录
+
+## 证据检查
+
+- [ ] 每个结论都有代码、文档或会议纪要支撑
+- [ ] 关键例子可追溯到原始来源
+- [ ] 没有把猜测写成事实
+
+## 交接检查
+
+- [ ] 输出可以交给 `spec-refinement`
+- [ ] 输出可以交给 `technical-design`
+- [ ] 输出可以交给 `knowledge-capture`
+- [ ] 文件命名遵守 kebab-case
+
+## 备注
+
+- 如果某个目录暂时没有内容，也要在索引里明确说明。
+- 如果有未确认项，单独列在“待确认”区域，不要隐藏。

package/skills/feature-build/references/comment-specification.md

@@ -1,102 +1,89 @@
-# 娉ㄩ噴瑙勮寖
-
-> 浠ｇ爜娉ㄩ噴鏍囧噯锛岀敤浜庝繚鎸佸彲璇绘€у拰鍙淮鎶ゆ€с€傝繖閲屽彧淇濈暀娉ㄩ噴瀵嗗害銆佹ā鏉垮拰妫€鏌ラ」锛涘叿浣撲笟鍔?鍒嗗眰鍩虹嚎浼樺厛寮曠敤 [rules/overlays/pig-cloud.md](/D:/work/java/pig-skills/rules/overlays/pig-cloud.md) 鍙婂叾瀛愯鍒欍€?
-## Class Comment
-
-### 蹇呰鍐呭
-
-| 鍐呭 | 璇存槑 |
-|------|------|
-| 绫昏鏄?| 涓€鍙ヨ瘽鎻忚堪鑱岃矗 |
-| 浣滆€?| 鍒涘缓鑰?|
-| 鏃ユ湡 | 鍒涘缓鏃ユ湡 |
-| 鐗堟湰 | 鍙€?|
-
-### 妯℃澘
-
-```java
-/**
- * 璁㈠崟鏈嶅姟瀹炵幇绫伙紝澶勭悊璁㈠崟鐩稿叧涓氬姟閫昏緫
- *
- * @author zhangsan
- * @date 2026-06-16
- */
-@Service
-@RequiredArgsConstructor
-public class OrderServiceImpl implements OrderService {
-}
-```
-
-## Method Comment
-
-### 蹇呰鍐呭
-
-| 鍐呭 | 璇存槑 |
-|------|------|
-| 鏂规硶璇存槑 | 涓€鍙ヨ瘽鎻忚堪鍔熻兘 |
-| 鍙傛暟璇存槑 | 姣忎釜鍙傛暟鐨勫惈涔?|
-| 杩斿洖璇存槑 | 杩斿洖鍊煎惈涔?|
-| 寮傚父璇存槑 | 鍙兘鎶涘嚭鐨勫紓甯?|
-| 鍓嶇疆鏉′欢 | 鎵ц鍓嶉渶瑕佹弧瓒崇殑鏉′欢 |
-| 鍚庣疆鏉′欢 | 鎵ц鍚庣殑鐘舵€佸彉鍖?|
-
-### 妯℃澘
-
-```java
-/**
- * 鍒涘缓璁㈠崟锛屾牎楠屽簱瀛樺苟鐢熸垚璁㈠崟璁板綍
- *
- * @param dto 璁㈠崟鍒涘缓璇锋眰DTO
- * @return 璁㈠崟ID
- * @throws BusinessException 搴撳瓨涓嶈冻鏃舵姏鍑?
- */
-public Result<Long> create(OrderCreateDTO dto) {
-}
-```
-
-## Logic Comment
-
-### 閫傜敤鍦烘櫙
-
-- 澶氭潯浠跺垽鏂?- 鐘舵€佹祦杞?- 澶嶆潅璁＄畻
-- 澶栭儴璋冪敤
-- 鏁版嵁杞崲
-- 鍒嗛〉/鎵归噺閫昏緫
-
-### 瑙勫垯
-
-- 鐢?`Step 1/2/3` 鏍囪娴佺▼
-- 鍙В閲婁笟鍔℃剰鍥撅紝涓嶈В閲婃樉鑰屾槗瑙佺殑璇硶
-- 澶嶆潅閫昏緫蹇呴』鐣欎笅鑳界湅鎳傜殑涓婁笅鏂?
-## External Call Comment
-
-### 蹇呰鍐呭
-
-- 璋冪敤鐩殑
-- 璋冪敤鎺ュ彛
-- 浼犲叆鍙傛暟
-- 棰勬湡杩斿洖
-- 寮傚父澶勭悊
-
-### 绀轰緥
-
-```java
-// 杩滅▼璋冪敤锛氭煡璇㈢敤鎴蜂俊鎭紝鐢ㄤ簬璁㈠崟鍒涘缓鍓嶆牎楠?UserDTO user = userApi.findById(dto.getUserId()).assertSucceed();
-```
-
-## Comment Density
-
-| 灞傜骇 | 寤鸿瀵嗗害 |
-|------|---------|
-| Entity | 绫绘敞閲?+ 瀛楁娉ㄩ噴 |
-| DTO/VO | 绫绘敞閲?+ 瀛楁娉ㄩ噴 |
-| Mapper | 绫绘敞閲婂嵆鍙?|
-| Service | 绫绘敞閲?+ 鏂规硶娉ㄩ噴 + 閫昏緫娉ㄩ噴 |
-| Controller | 绫绘敞閲?+ 鏂规硶娉ㄩ噴 |
-| Convert | 绫绘敞閲婂嵆鍙?|
-
-## Anti-rationalization
-
-- 浠ｇ爜寰堟竻妤氾紝涓嶉渶瑕佹敞閲?- 娉ㄩ噴浼氳繃鏃讹紝鎵€浠ヤ笉鍐?- 浠ュ悗鍐嶈ˉ娉ㄩ噴
-- IDE 鍙互鑷姩鐢熸垚灏卞浜?
-
+# 注释规范
+
+> 代码注释标准，用于保持可读性和可维护性。这里只保留注释密度、模板和检查项；具体业务分层基线优先引用 `rules/overlays/pig-cloud.md` 及其子规则。
+
+## Class Comment
+
+### 必要内容
+
+| 内容 | 说明 |
+|------|------|
+| 类说明 | 一句话描述职责 |
+| 作者 | 创建者 |
+| 日期 | 创建日期 |
+| 版本 | 可选 |
+
+### 模板
+
+```java
+/**
+ * 用户服务。
+ *
+ * <p>负责用户查询、创建与基础校验。</p>
+ */
+```
+
+## Method Comment
+
+### 必要内容
+
+| 内容 | 说明 |
+|------|------|
+| 方法说明 | 方法做什么 |
+| 参数说明 | 每个参数的含义 |
+| 返回说明 | 返回值含义 |
+| 异常说明 | 可能抛出的异常 |
+| 前置条件 | 调用前要满足什么 |
+| 后置条件 | 执行后的状态变化 |
+
+### 模板
+
+```java
+/**
+ * 根据用户 ID 查询用户信息。
+ *
+ * @param userId 用户 ID
+ * @return 用户信息
+ * @throws BusinessException 用户不存在时抛出
+ */
+```
+
+## Inline Comment
+
+### 使用场景
+
+- 多条件判断
+- 状态流转
+- 复杂计算
+- 需要解释意图但代码本身又不适合再拆函数的地方
+
+### 规则
+
+- 注释要解释“为什么”，不要重复“是什么”。
+- 复杂逻辑必须留下能看懂的上下文。
+- 用短句说明约束、边界和原因。
+
+## 示例
+
+```java
+// 远程调用：查询用户信息，用于订单创建前校验
+UserDTO user = userApi.findById(dto.getUserId()).assertSucceed();
+```
+
+## 注释密度
+
+| 场景 | 建议 |
+|------|------|
+| Entity | 类注释 + 字段注释 |
+| DTO/VO | 类注释 + 字段注释 |
+| Mapper | 类注释即可 |
+| Service | 类注释 + 方法注释 + 逻辑注释 |
+| Controller | 类注释 + 方法注释 |
+| Convert | 类注释即可 |
+
+## 不建议
+
+- 代码很清楚，不需要注释。
+- 注释会过时，所以不注释。
+- 以后再补注释。
+- IDE 自动生成就够了。