@nathan33/nao-skill 0.1.0

package/.agents/skills/backend-ddd-details.md

@@ -0,0 +1,108 @@
+---
+description: 按需技能——后端 DDD 代码骨架、事务、事件、命名、误区
+---
+
+# 后端 DDD 详细规范
+
+## 等级差异
+
+| 维度 | L1 | L2 | L3 |
+| :--- | :--- | :--- | :--- |
+| 事务 | `db.Begin()` | `context` 传事务句柄 + 闭包 | L2 + Saga/Outbox |
+| 领域事件 | 不强制 | 内存总线（事务后同步） | MQ + Outbox（至少一次） |
+| 并发 | DB 锁 | 聚合根乐观锁 Version | L2 + 分布式锁 |
+
+## 代码骨架
+
+```go
+// domain/order/order.go（零外部依赖）
+var ErrCanceled = errors.New("already canceled")
+type Order struct { ID string; Status Status; Version int64 }
+func (o *Order) Cancel() error {
+    if o.Status == Canceled { return ErrCanceled }
+    o.Status = Canceled
+    return nil
+}
+
+// domain/order/repository.go
+type Repository interface {
+    FindByID(ctx context.Context, id string) (*Order, error)
+    Save(ctx context.Context, order *Order) error
+}
+
+// infrastructure/repository/order_repo.go
+type GormRepo struct { db *gorm.DB }
+func (r *GormRepo) Save(ctx context.Context, o *Order) error {
+    return r.db.WithContext(ctx).Model(o).Where("version=?", o.Version).Updates(...).Error
+}
+
+// application/order/service.go（编排，无业务规则）
+type Service struct { repo order.Repository; events EventPublisher }
+func (s *Service) Cancel(ctx context.Context, id string) error {
+    o, _ := s.repo.FindByID(ctx, id)
+    if err := o.Cancel(); err != nil { return err }
+    return s.repo.Save(ctx, o)
+}
+
+// interfaces/http/order_handler.go
+func (h *Handler) Cancel(c *gin.Context) {
+    var req CancelReq
+    if err := c.ShouldBindJSON(&req); err != nil { ... }
+    if err := h.svc.Cancel(c.Request.Context(), req.ID); err != nil { mapError(c, err); return }
+    c.Status(204)
+}
+
+// cmd/api/main.go
+db := gorm.Open(...)
+repo := &repo.GormOrderRepo{db: db}
+svc := &order.Service{repo: repo}
+handler := &http.OrderHandler{svc: svc}
+```
+
+## 事务策略
+
+- 应用层闭包：`repo.Transaction(ctx, func(txRepo Repo) error { ... })`
+- 或 `context` 传 `*sql.Tx`，应用层控制边界
+- **禁止**：Interface/Domain 层管事务
+
+## 查询与读模型
+
+- 写模型走聚合根，强一致
+- 读模型（复杂列表/报表）：应用层定义 `XxxQuery`，Infra 直接执行优化 SQL/视图，返回只读 DTO，**绕过聚合根**
+- 禁止：为列表加载整个聚合根及子实体
+
+## 错误处理
+
+- Domain 哨兵：`var ErrOrderCanceled = errors.New("order already canceled")`
+- Interface 映射：`ErrNotFound`→404 / `ErrConflict`→409 / `ErrInvalid`→400
+- 禁止：透传 `sql.ErrNoRows`
+
+## 领域事件
+
+- 发布时机：事务提交后
+- L3：Outbox 表 + 扫表重发（至少一次）
+- 消费端：按业务唯一键幂等
+
+## 配置与可观测
+
+- `viper` 或环境变量（12-factor），集中 `Config` 结构体
+- 通过 `context` 传 `trace_id`；I/O 记录耗时与错误
+- 禁 `log.Fatal` 非 main 包
+
+## 并发与乐观锁
+
+- 聚合根 `Version int64`
+- `UPDATE orders SET status=?, version=version+1 WHERE id=? AND version=?`
+- 影响行数为 0 → `ErrOptimisticLock` → 应用层重试或 409
+- 禁止：无版本字段的"先查再改"
+
+## 测试
+
+Domain：`go test` 纯单测；Application：mock 仓储；Infra：集成 + testcontainers
+
+## 误区
+
+- DDD ≠ 微服务（可用于单体 L1/L2）
+- 只对核心域做 DDD（辅助功能用事务脚本）
+- 默认不引入 Event Sourcing / CQRS
+- 乐观锁 + 重试足以应对 99% 并发

package/.agents/skills/codegraph.md

@@ -0,0 +1,52 @@
+---
+description: 按需技能——CodeGraph 代码定位（替代 grep 全文扫描，省 token）
+---
+
+# CodeGraph 代码定位
+
+> 用图谱精确命中符号/调用链/影响面，**替代"grep 全文 + cat 大文件"**——上下文只进相关代码块。
+> 不可用时降级到 `grep -rn` + 行段读取（见文末）。
+
+## 何时用（对比 grep）
+
+| 场景 | 首选 | 理由 |
+| :--- | :--- | :--- |
+| 定位函数/类型/符号定义 | `codegraph query` | 语义精确，一次命中 |
+| 理解某任务涉及哪些代码 | `codegraph context "<任务>"` | 一次返回相关符号+代码块，无需多轮 grep+cat |
+| 追踪调用链 / 改动影响面 | `callers` / `callees` / `impact` | 图谱遍历，替代手动读 N 个文件 |
+| 找受影响的测试 | `codegraph affected` | 一步到位 |
+| 文件名/配置/字符串/文档 | `grep -rn` | 更快更直接，不绕道 |
+
+## Token 纪律（省的是上下文累积）
+
+- **一次 `context` 拿全，不再 grep+cat 同一段代码**——codegraph 已给出精确代码块，直接使用。
+- 输出过大用 `-n <num>` 限符号数；只看结构用 `--no-code`。
+- 文件模式用 `node --file <f> --offset <n> --limit <m>` 只读需要的行段，**禁止 cat 全文**。
+- 大任务拆成多个子问题分别 `context`，不做一次超大查询。
+- 拿到的代码块不重复读取（同一内容第二次进上下文 = 重复计费）。
+
+## 命令速查
+
+- `codegraph status` — 索引健康检查（无索引 → `codegraph init`；有改动 → `codegraph sync`）
+- `codegraph query "<符号>"` — 精确定位符号
+- `codegraph context "<任务描述>"` — 任务上下文：相关符号 + 关系 + 代码块
+- `codegraph node <符号>` — 符号源码 + caller/callee 调用链
+- `codegraph node --file <f> --offset <n> --limit <m>` — 读文件行段（带行号）
+- `codegraph callers <符号>` / `codegraph callees <符号>` — 调用追踪
+- `codegraph impact <符号>` — 改动影响分析（**修改前必跑**）
+- `codegraph affected <文件...>` — 受影响的测试文件
+- `codegraph files` — 项目文件结构
+
+## 工作区与索引维护
+
+- 索引是**项目级**的：在对应 repo 目录跑（fleet 会话 cwd 即 repo）；跨仓库用 `-p <路径>`。
+- 写完代码跑一次 `codegraph sync` 保持索引新鲜（提交前）。
+- 首次进入新 repo：`codegraph status` → 无索引则 `codegraph init`（一次性成本，之后只 `sync`）。
+
+## 降级（codegraph 不可用 / 无结果）
+
+1. 无 `.codegraph/` → 先 `codegraph sync`；仍失败则 `codegraph init`（慢则放弃）。
+2. 查询无结果 → 换关键词再试一次 → 仍无 → 回退。
+3. **回退 grep**：`grep -rn "<关键词>" --include=<扩展名> <目录>` 定位，再用
+   `sed -n '<起>,<止>p' <文件>` 读精确行段；**禁止 cat 全文**。
+4. 非代码内容（配置/字符串/文档）直接 grep，不绕道。

package/.agents/skills/commit.md

@@ -0,0 +1,68 @@
+---
+description: 按需技能——Git 提交规范（仅在执行 git commit 前读取）
+---
+
+# Git 提交规范
+
+## 触发时机
+
+仅在执行 `git commit` 前读取本文件；其他时候不加载。
+
+## 流程
+
+1. `git diff --cached` 与 `git diff --cached --stat` 查看暂存变更
+2. `git log --oneline -10` 参考近期提交风格
+3. 按格式编写提交消息，执行 `git commit -m "消息"`
+
+## 消息格式
+
+```text
+<type>(<scope>): 简短描述（≤50字符）
+
+变更点：
+
+- 具体变更1
+- 具体变更2
+
+其他（可选）：
+
+- 依赖/配置/构建等非功能变更
+```
+
+## 类型（可扩展）
+
+- feat   新增功能
+- fix    修复缺陷
+- chore  构建/依赖/配置等杂项
+- change 其他（重构、性能等）
+- 扩展：refactor（重构）、docs（文档）、test（测试）、style（样式）等
+
+## 规则
+
+- 变更点列出主要逻辑或用户可见变动，描述具体
+- 其他仅放配置文件、依赖版本（注明旧→新版本号）等
+- 避免重复，已列变更点的不再写其他
+- 版本示例：`升级 dayjs 从 1.10.7 到 1.11.5`
+
+## 示例
+
+```text
+feat(calendar): 日期时间选择器显示当前选中值
+
+变更点：
+
+- 时间面板不再显示 NaN
+- 日期面板显示当前选中日期
+- 日期时间面板显示当前选中日期时间
+
+其他：
+
+- 升级 dayjs 从 1.10.7 到 1.11.5
+```
+
+## 注意事项
+
+- 提交前确保所有变更已暂存
+- 尽量拆分逻辑独立的提交
+- 使用中文，简洁准确
+- 禁止提交未测试或含调试代码的变更

package/.agents/skills/frontend-ddd-details.md

@@ -0,0 +1,95 @@
+---
+description: 按需技能——前端 DDD 骨架、场景速决、命名、误区
+---
+
+# 前端 DDD 详细规范
+
+## 标准骨架
+
+```ts
+// Domain 实体
+class Task {
+  complete() {
+    if (overdue) throw new DomainError()
+    this.status = 'done'
+  }
+}
+
+// 用例（依赖接口）
+class UseCase {
+  constructor(repo, gateway) {}
+  async exec(id) {
+    const e = await repo.find(id)
+    e.complete()
+    await repo.save(e)
+    this.gateway.update(e)
+  }
+}
+
+// DI 组装点（Composable/Hook）
+function useX() {
+  const store = useStore()
+  const uc = new UseCase(new HttpRepo(), store)
+  return { ... }
+}
+
+// Mapper（Infra 层）
+class Mapper {
+  static toEntity(dto): Entity
+  static toDto(entity): Dto
+}
+```
+
+## 场景速决
+
+- **路由**：Views 仅透传 `params` 给 Hook；禁 `onMounted` 直接调 API/用例
+- **筛选/分页**：属 UI 状态（UI Store/局部），传纯 DTO 给用例；禁传 `ref` 响应式对象
+- **表单**：UI 只做轻校验（必填/格式）；复杂规则放实体 `validate()`；UI 捕获 `DomainError` 映射回表单
+- **错误**：用例统一转 `DomainError`/`InfraError`；UI 通过 `useErrorHandler` 映射 Toast（禁 `alert`）
+- **WebSocket**：消息 → 领域事件 → `SyncUseCase` → 更新 Store；禁 `socket.on` 直改 Store
+- **API 类型生成（OpenAPI）**：生成的 DTO 仅限 Infra，必须经 Mapper 转实体进 Domain
+- **性能**：Store 存 Map/Record；组件用 Selector 取子集；禁全量解构 Store
+
+## 命名
+
+`I{Entity}Repository` / `{Entity}HttpRepo` / `{Entity}UseCase` / `{Entity}Dto` + `Mapper` / `useXxx`
+
+## UI/UX 落地（通用，不绑定具体组件库）
+
+> 两个单一事实来源：**Design Tokens**（视觉）+ **UX Playbook**（交互）。
+> 组件只允许消费令牌与 playbook 约定，硬编码/自造即违规。
+
+### 单一事实来源
+
+- **Design Tokens**：`tokens.css`，命名空间 `--<prefix>-*`（颜色/间距/圆角/阴影/字号/动效）。任何情形下都是视觉唯一来源。
+- **UX Playbook**：`ux-playbook.md`——用户想要的 UX 的可执行定义：页面四态（加载/空/错误/成功）、反馈模式（Toast/确认/骨架屏）、空态文案、表单校验时机、加载位置、键盘导航。**落地代码的唯一交互依据，不临场发明**。
+
+### 按技术栈落地
+
+| 情形 | 令牌 | UX | 组件 |
+| :--- | :--- | :--- | :--- |
+| 组件库+主题（NueUI+shadlike） | 用库令牌（如 `--nue-*`），缺口补 tokens.css | 用库语义组件/属性 | 库原语优先，不新造 |
+| 组件库无主题 | 自建 tokens.css，对齐/覆盖库变量 | 用库语义组件/属性 | 库原语优先 |
+| 纯手写 | **必建** tokens.css | **必建** ux-playbook.md | 自建基础组件按 playbook |
+
+### 红线（任何情形）
+
+- 组件/样式禁裸色值（`#fff`/`rgba(...)`）、禁无令牌的魔法尺寸/圆角/阴影——一律 `var(--<prefix>-*)`；仅 tokens.css 允许定义令牌。
+- 新 UI 用既有原语/基础组件组装；页面不另起风格。
+- 四态与反馈模式严格按 UX Playbook；交互变更须 PM/用户确认。
+- 交付前：`bash "$NAO_SKILLS/.agents/scripts/ui-tokens-check.sh" <repo>`（进 CI 则自动拦截）。
+
+### 模板
+
+- `tokens.css` 骨架 + `ux-playbook.md` 骨架：`@.agents/templates/frontend-ui/`（复制到项目按需裁剪）。
+
+## 测试
+
+Domain：Vitest 纯单测；Application：Mock 端口；Infra：MSW；Pres：VTU/Testing-Library
+
+## 误区
+
+- DDD ≠ 重框架；规模不到 L1 用 DDD 反是负担
+- 把业务规则写进 store 或组件
+- 让 DTO 直接进 Domain
+- 让 Store 调多个仓储做编排（应下沉 UseCase）

package/.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: frontend-design
+description: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
+license: Complete terms in LICENSE.txt (anthropics/skills)
+source: https://github.com/anthropics/skills/tree/main/skills/frontend-design
+updated: 2026-09-21
+---
+
+# Frontend Design
+
+Approach this as the design lead at a design studio known for giving every client a distinct visual identity that is not mistaken for anyone else's. This client has already rejected proposals that felt cliché or templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take aesthetic risk if justified.
+
+## Ground your designs in the subject matter
+
+If the brief does not identify what the product or subject matter is, identify it yourself before designing, and confirm with the client. You can come up with one concrete subject, the design's audience, and the design's primary job, as a proposal. If there's any information in your memory about the client's preferences or context about what they're building, use that as a hint. The subject's industry, subject matter, materials, and vernacular are where distinctive visual choices come from — a design for a toy for girls aged 8–11 will be very aesthetically different from a dashboard for financial analysts. Build with the brief's real content and subject matter throughout.
+
+## Design principles
+
+For web designs, the hero is the first thing viewers will see. Open with the most characteristic thing in the subject's world, in the form that is most appropriate: a headline, an image, an animation, a live demo, an interactive moment, or other treatments. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the default treatment, so only use it if that's truly the best option.
+
+Typography carries the personality of the page. You don't need a different typeface for display or headline text and body content: use one family or two, and if two, make them clearly distinct.
+
+Choose your typefaces deliberately, not the default families you would reach for on any other project, and set a clear type scale following the default guidance of The Elements of Typographic Style with intentional weights, widths, and spacing. When type is used as a headline or visual element, use the type treatment itself as an active part of the design, not a neutral delivery vehicle for the content.
+
+Default to line lengths of less than 80 characters. Serif typefaces can have slightly longer line lengths; give serif body text slightly more line-height than a sans-serif.
+
+Avoid these default typographic treatments; they are the commonest tells of a generated page:
+- Accenting just a single word or phrase in a headline, like putting one word in italic/bold or a different color.
+- Using all caps for labels.
+- Adding unnecessary typographic labels above content.
+
+Visual structure is information. Structural devices like outlines, borders, numbering, eyebrows, dividers, labels, etc., encode useful information about the content rather than decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence — like a stepped process or a timeline. Before adding numbered markers, check the content really is a sequence.
+
+Use non-user-triggered motion sparingly and deliberately, only to draw attention. A single orchestrated moment — one page-load sequence or one reveal — lands better than scattered effects; fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as AI-generated. Motion that answers a person's action (opening, expanding, confirming) is welcome when it shows what changed.
+
+Consider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy and placeholder content. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.
+
+## Process: plan, review against the brief, build, critique
+
+For calibration, AI-generated design right now clusters around some traits:
+1. a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta or warm-clay accent (often near #D97757 — Anthropic's own Claude-interaction accent, so on a user's brief it reads as a tell);
+2. a near-black background with a single bright acid-green or vermilion accent;
+3. a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns;
+4. the SaaS-card kit: content chopped into identical rounded cards, one border-radius on everything regardless of hierarchy, the same soft grey shadow (rgba(0,0,0,.1)) under each, and gradient washes as decoration;
+5. template chrome that appears whatever the subject: a tracked-out ALL-CAPS eyebrow label above every heading; meta strings joined with middle dots ('A · B · C'); labels built as 'WORD — fragment' with a spaced em dash; tinted near-black (#0B0B0B, #111) standing in for black; a monospace face for small data labels; a '→' appended to link and button text.
+
+All traits are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. As with a hired human designer, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.
+
+Work in two passes. First, brainstorm a short design plan based on the client's design brief: create a compact token system with color, type, layout, and principles.
+- Color: describe the core base palette as 4–6 named hex values.
+- Type: the typefaces and their roles.
+- Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Include alignment guidance; should the content be left aligned, center aligned, justified?
+- Principles: the high-level guidance for what makes this page unique.
+
+Then review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan.
+
+When writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and an element-based selector like .cta). This can happen often with padding/margin between sections.
+
+## Restraint and self-critique
+
+Spend your boldness in one place. Let one element be the memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected, visually accessible, harmonious color palettes. Critique your own work as you build, taking screenshots to review if your environment supports it — a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creatives have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.
+
+## More on writing in design
+
+Words appear in a design for one reason: to make it easier to understand and use. They are design content, not decoration. Bring the same intentionality and minimalism to copywriting that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.
+
+Write from the end user's perspective. Name things by what users will understand in simple language, not by how the system is built. A user manages notifications, not webhook config. Describe what something is or does in plain terms rather than selling it. Being specific and legible to new users is always better than being clever.
+
+Use active voice as default. A CTA says exactly what happens when it is used: "Save changes," not "Submit." An action keeps the same name through the whole flow, so the button that says "Publish" produces a toast that says "Published." The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.
+
+Treat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.
+
+Keep the tone conversational: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each written element do exactly one job.

package/.agents/skills/pm-grill.md

@@ -0,0 +1,26 @@
+---
+description: 按需技能——苏格拉底式澄清（grill-me）
+---
+
+# grill-me 澄清清单
+
+需求模糊时**必须**触发，逐层追问直至澄清，澄清前不得写 PRD。
+
+## 五层追问
+
+1. **目标用户**：谁？画像？规模？
+2. **使用场景**：什么时候？什么触发？频率？
+3. **核心流程**：主路径步骤？关键角色？
+4. **边界/异常**：不做什么？异常如何处理？权限？
+5. **成功标准**：如何度量成功？指标？验收？
+
+## 输出
+
+- 待澄清清单（编号 + 问题 + 影响）
+- 澄清后回填 PRD 对应模块
+
+## 反模式
+
+- 猜测补全
+- 一次问完所有问题（应逐层推进，先主干后枝节）
+- 澄清未完成就开始写方案

package/.agents/skills/pm-rice.md

@@ -0,0 +1,36 @@
+---
+description: 按需技能——优先级决策（战略筛子 / MoSCoW / RICE / Kano）
+---
+
+# 优先级决策框架
+
+顺序：**战略筛子 → MoSCoW → RICE → Kano**
+
+## 战略筛子（任一否决即淘汰/推迟）
+
+1. 是否直接贡献本季北极星/OKR？（否 → 淘汰）
+2. 是否构建竞品难复制的壁垒？（1–5 分，<3 慎重）
+3. 不做是否 3 个月内造成用户流失/营收下降？（是 → Must）
+
+## MoSCoW
+
+- **Must** 必须做 / **Should** 应该做 / **Could** 可以做 / **Won't** 不会做
+
+## RICE
+
+| 维度 | 说明 |
+| :--- | :--- |
+| Reach | 影响用户数/交易量 |
+| Impact | 影响程度（3/2/1/0.5） |
+| Confidence | 信心度（100%/80%/50%） |
+| Effort | 总人月/人天 |
+
+**公式**：RICE = (Reach × Impact × Confidence) / Effort
+
+## Kano
+
+体验类需求用 Kano 判断是否小成本加入。
+
+## 输出要求
+
+PRD 必带：战略筛子结论 + RICE 打分表（可追溯）。

package/.agents/skills/test-design.md

@@ -0,0 +1,52 @@
+---
+description: 按需技能——用例设计、缺陷管理、性能安全、DDD 分层对齐
+---
+
+# 测试设计详细规范
+
+## 用例设计方法
+
+- **等价类划分**：有效/无效各取代表值
+- **边界值分析**：上点/内点/离点（如金额 0/1/上限/上限+1）
+- **判定表**：多条件组合（权限 × 状态 × 输入）
+- **场景法**：主路径 + 异常 + 边界
+- **错误推测**：并发、超时、断网、重复提交、空值、超长输入
+
+## DDD 分层对齐表
+
+| 层 | 测试方式 | 覆盖内容 |
+| :--- | :--- | :--- |
+| domain | 纯单测（Vitest / `go test`） | 实体规则、状态流转、不变量、VO |
+| application | mock 仓储/端口 | UseCase 编排顺序、端口调用、异常传播 |
+| infrastructure | MSW / 集成（内存/真实 DB） | Mapper 双向、HTTP 映射、乐观锁冲突 |
+| presentation | VTU / Testing Library | 组件渲染与交互 |
+| E2E | Playwright / Cypress | 关键路径、跨模块流程 |
+
+## 缺陷管理
+
+- 生命周期：New → Open → Fixed → Verify → Closed / Reopen
+- 严重度：致命 / 严重 / 一般 / 轻微
+- 优先级：P0 / P1 / P2 / P3
+- 报告要素：标题、环境版本、复现步骤、预期 vs 实际、日志/截图、影响范围
+- 不 Verify 不关闭；Reopen 有依据
+
+## 自动化与 CI/CD
+
+- 测试左移：早参与需求/用例评审
+- 分层自动化：单测/集成每提交必跑；E2E 关键路径 + 发布前冒烟
+- 门禁：单测通过率、覆盖率阈值、冒烟用例作为准入
+- 可维护性：Page Object / 组件封装；稳定优先于数量
+- AI 生成用例：可用于补覆盖，**必须人工评审**后入库
+
+## 性能与安全（按需）
+
+- 性能：并发、响应时间、吞吐、资源；压测类型（负载/压力/稳定性）；基线如 P95<500ms
+- 安全：越权、注入、XSS、敏感数据泄露、接口鉴权；按要求启用渗透/扫描
+
+## 误区
+
+- 测试 = 点点点 → 是策略 + 用例工程 + 风险量化
+- 用例越多越好 → 覆盖有效性优先
+- 自动化万能 → 探索性测试发现未知问题
+- 质量只由测试负责 → 产品/研发/测试共同责任
+- 无缺陷 = 质量好 → 可能覆盖不足

package/.agents/templates/AGENTS.md.example

@@ -0,0 +1,37 @@
+# AGENTS.md — <项目名> 项目上下文
+
+> **本模板仅用于新建**。项目已有非空 AGENTS.md 时，按 PM 卡 §七「接入已有 AGENTS.md」合并规则处理：
+> 保留原文 + 末尾追加 `## nao 舰队接入（日期）` 区块，不覆盖、不新建遮蔽文件。
+>
+> pi 自动加载本文件进所有会话上下文；**保持精简**（<120 行），只放项目级内容。
+> 角色级/团队级内容留在 nao-skills（roles.yaml / common / checklists），这里只写「在哪里」。
+> 维护人：PM（见 PM 卡 §七）。
+
+## 项目属性
+
+- **仓库结构**：<顶层目录一句话，如 前端 packages/presentation-*，后端独立 repo nao-todo-server>
+- **技术栈**：<框架/语言/关键版本>
+- **命令**：
+  - 构建/启动：`<cmd>`
+  - 测试：`<cmd>`
+  - lint/格式：`<cmd>`
+  - 代码索引同步：`codegraph sync`（如已配）
+- **环境**：<关键环境变量 / 运行方式 / 数据依赖>
+
+## 项目约束（红线）
+
+- <领域约束 1，如：任务状态流转只走领域实体方法>
+- <命令纪律，如：禁 cat 全文读代码，用 CodeGraph 或 sed 行段>
+- <依赖限制 / 禁止事项>
+
+## 与 nao 机制衔接
+
+- **CodeGraph**：本仓库 `.codegraph/` 索引；写完代码 `codegraph sync` 保持新鲜。
+- **UI/UX**：Design Tokens 在 `<src/styles/tokens.css>`；UX Playbook 在 `<docs/ux-playbook.md>`；硬编码色值禁入（`ui-tokens-check.sh` 兜底）。
+- **交付核对**：交付前读取 `@.agents/checklists/<role>.md`（完整红线 + 清单）。
+
+## 指针（勿复制内容）
+
+- 团队级协议/角色清单：`$NAO_SKILLS/.agents/common/` + `.agents/roles.yaml`
+- 角色卡：`$NAO_SKILLS/.agents/prompts/`
+- 按需技能：`$NAO_SKILLS/.agents/skills/`

package/.agents/templates/frontend-ui/tokens.css.example

@@ -0,0 +1,74 @@
+/* ============================================================================
+ * Design Tokens — 复制为 src/styles/tokens.css，按需裁剪。
+ * 命名：--<prefix>-*（语义命名，非产品色名）；组件内一律 var(--<prefix>-*)。
+ * 暗色/主题切换：在 :root 之外用媒体查询或 [data-theme] 覆盖令牌值即可。
+ * ========================================================================== */
+:root {
+  /* 颜色（语义） */
+  --color-bg: #ffffff;
+  --color-surface: #f5f5f5;
+  --color-surface-hover: #ececec;
+  --color-border: #e0e0e0;
+  --color-text: #1a1a1a;
+  --color-text-muted: #666666;
+  --color-text-disabled: #999999;
+
+  --color-primary: #3b82f6;
+  --color-primary-hover: #2563eb;
+  --color-primary-text: #ffffff;
+  --color-danger: #ef4444;
+  --color-success: #10b981;
+  --color-warning: #d4a72c;
+
+  /* 间距（4px 基准） */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+
+  /* 圆角 */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-full: 999px;
+
+  /* 阴影 */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
+  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
+
+  /* 字号层级 */
+  --text-xs: 12px;
+  --text-sm: 14px;
+  --text-md: 16px;
+  --text-lg: 20px;
+  --text-xl: 24px;
+
+  /* 动效 */
+  --dur-fast: 120ms;
+  --dur-base: 200ms;
+  --ease-base: ease;
+
+  /* 布局 */
+  --header-h: 56px;
+  --sidebar-w: 240px;
+  --content-max-w: 1080px;
+  --gap-page: var(--space-6);
+  --gap-card: var(--space-4);
+}
+
+/* 暗色模式：仅覆盖令牌值，组件零改动 */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #121212;
+    --color-surface: #1e1e1e;
+    --color-surface-hover: #262626;
+    --color-border: #333333;
+    --color-text: #f2f2f2;
+    --color-text-muted: #a0a0a0;
+    --color-text-disabled: #666666;
+  }
+}

package/.agents/templates/frontend-ui/ux-playbook.md.example

@@ -0,0 +1,36 @@
+# UX Playbook（交互单一事实来源）
+
+> 这是"用户想要的 UX"的可执行定义。落地 UI 时的**唯一交互依据**，不临场发明。
+> 与用户/PM 确认后定稿；变更须经 PM 确认。rd-fe 交付前按此核对。
+
+## 页面四态（每个可加载模块必须覆盖）
+
+| 状态 | 表现 | 位置 |
+| :--- | :--- | :--- |
+| 加载 | 骨架屏（列表/卡片）或按钮 loading；首次整页加载用骨架 | 内容区 |
+| 空态 | 图标 + 主文案 + 行动按钮（如"去创建"） | 内容区居中 |
+| 错误 | 行内错误或全局错误条 + 重试按钮；文案含可操作建议 | 就近展示 |
+| 成功 | 轻量 Toast（默认 2s），不打断 | 顶部居中/右下 |
+
+## 反馈模式
+
+- **危险操作**（删除/清空/退出）：二次确认 Dialog，按钮「确认删除 / 取消」。
+- **提交**：按钮 loading；成功后跳转或 Toast；失败就地显示错误。
+- **表单校验**：失焦即时校验，错误就地显示；提交时全量校验；提交中防重复。
+- **异步刷新**：静默刷新失败不弹框，用角标/状态条提示可重试。
+
+## 导航与键盘
+
+- 列表支持键盘上下选择；Dialog 支持 Esc 关闭 + Focus 陷阱。
+- 移动端底部操作条；桌面侧栏导航；详情页返回保留滚动位置。
+- 长列表虚拟滚动；加载更多用"加载中"占位而非跳动。
+
+## 文案
+
+- 空态/错误用**主动语态 + 下一步**（"还没有任务，点这里新建"），禁被动"发生错误"。
+- 按钮动词化（"保存""删除"）；禁用灰色 + 说明原因。
+
+## 一致性
+
+- 同一含义只用一种反馈方式（如删除永远是确认 Dialog，不混 Toast）。
+- 新交互进本 Playbook，不进代码注释。