@zmice/zc 0.1.0 → 0.2.0

package/vendor/packages/toolkit/src/content/commands/simplify/meta.yaml

@@ -0,0 +1,19 @@
+kind: command
+name: simplify
+title: 简化
+description: 分析代码并进行简化重构，降低复杂度，提升可读性和可维护性。
+tier: recommended
+audience: default
+stability: stable
+requires:
+  - skill:code-simplification
+suggests:
+  - command:quality-review
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: toolkit-original
+  strategy: curated
+  notes: 本仓库整理的命令入口，用于将底层能力稳定暴露给用户。

package/vendor/packages/toolkit/src/content/commands/spec/body.md

@@ -0,0 +1,32 @@
+调用 `spec-driven-development`，先把问题定义清楚，再开始写代码。
+
+## 核心动作
+
+1. 理解用户目标、用户对象、核心功能和约束
+2. 列出显式假设，并等待确认
+3. 定义可测试的验收标准，优先用 Given-When-Then
+4. 编写结构化技术规格：目标、边界、约束、验证方式
+5. 记录不确定项，禁止带着模糊前提直接进入实现
+
+## 相关原则
+
+- 先澄清假设，再写规格
+- 范围边界必须显式，不用自然语言暗示
+- 规格阶段只产出定义，不直接写实现代码
+
+## 使用方式
+
+在 `/spec` 后描述需求，我会分析上下文并输出结构化技术规格。
+
+### 示例
+
+```
+# 需求还不清晰
+/spec 我想做一个数据同步模块，从 A 系统定时拉取数据到 B 系统
+
+# 功能需求较明确
+/spec 实现文件上传功能，支持图片和 PDF，最大 10MB，存储到 MinIO
+
+# 审查现有 PRD
+/spec 分析这个 PRD 文档，找出技术实现的歧义点和风险点
+```

package/vendor/packages/toolkit/src/content/commands/spec/meta.yaml

@@ -0,0 +1,23 @@
+kind: command
+name: spec
+title: 规格
+description: 先澄清需求与假设，再为给定的功能或场景编写结构化技术规格说明。
+tier: core
+audience: default
+stability: stable
+requires:
+  - skill:spec-driven-development
+suggests:
+  - skill:brainstorming-and-design
+  - command:task-plan
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: spec-driven-development
+  origin_path: skills/spec-driven-development/SKILL.md
+  origin_id: skill:spec-driven-development
+  notes: 对应 define/spec 阶段入口，并做中文命令说明收敛

package/vendor/packages/toolkit/src/content/commands/task-plan/body.md

@@ -0,0 +1,32 @@
+调用 `planning-and-task-breakdown`，只做计划，不直接写代码。
+
+## 核心动作
+
+1. 读取规格和相关代码，识别依赖图
+2. 用垂直切片拆任务，保证每项都可工作、可测试
+3. 控制改动半径，默认保持小任务、小文件面
+4. 标注依赖、上下文、风险和验证步骤
+5. 明确可并行项，并等待计划确认后再进入实现
+
+## 相关原则
+
+- 计划要服务实现，不做形式化拆分
+- 每个任务都必须能独立验证
+- 先控制复杂度，再谈并行
+
+## 使用方式
+
+在 `/task-plan` 后提供 Spec 或需求描述，我会拆解为可执行的原子任务列表。
+
+### 示例
+
+```
+# 基于 spec 拆解
+/task-plan 按照 spec.md 的要求拆解文件上传功能的任务
+
+# 直接描述需求
+/task-plan 拆解用户权限管理模块：RBAC 模型、角色分配、菜单权限、数据权限
+
+# 大型重构
+/task-plan 规划单体应用拆微服务的任务，优先拆分用户模块和订单模块
+```

package/vendor/packages/toolkit/src/content/commands/task-plan/meta.yaml

@@ -0,0 +1,23 @@
+kind: command
+name: task-plan
+title: 计划
+description: 将需求或 Spec 拆解为可执行的原子任务列表，并标注依赖、上下文和验证步骤。
+tier: core
+audience: default
+stability: stable
+requires:
+  - skill:planning-and-task-breakdown
+suggests:
+  - skill:multi-perspective-review
+  - command:build
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: planning-and-task-breakdown
+  origin_path: skills/planning-and-task-breakdown/SKILL.md
+  origin_id: skill:planning-and-task-breakdown
+  notes: 延续上游 plan 入口语义，并按本仓库任务拆解规范重写

package/vendor/packages/toolkit/src/content/commands/ui/body.md

@@ -0,0 +1,24 @@
+调用 frontend-ui-engineering 技能。构建生产质量的用户界面。
+
+1. 组件设计 — Props/State/Event，单一职责，易于测试
+2. 样式实现 — CSS/Tailwind/CSS-in-JS，样式与逻辑分离
+3. 响应式布局 — 多端适配方案
+4. 可访问性（a11y） — ARIA、键盘导航、WCAG 2.1 AA 合规
+5. 交互细节 — 动画、过渡、加载状态、错误状态
+
+## 使用方式
+
+在 `/ui` 后描述你的 UI 需求（组件、页面、交互），我将提供设计方案和实现代码。
+
+### 示例
+
+```
+# 组件开发
+/ui 实现一个可复用的数据表格组件，支持排序、筛选、分页
+
+# 页面布局
+/ui 实现响应式的 Dashboard 布局，左侧导航 + 右侧内容区
+
+# 交互优化
+/ui 优化表单提交体验，加上实时验证、加载状态和错误提示
+```

package/vendor/packages/toolkit/src/content/commands/ui/meta.yaml

@@ -0,0 +1,20 @@
+kind: command
+name: ui
+title: 界面
+description: 前端 UI 开发辅助，涵盖组件设计、样式实现、响应式布局和可访问性。
+tier: recommended
+audience: default
+stability: stable
+requires:
+  - skill:frontend-ui-engineering
+suggests:
+  - command:qa
+  - skill:browser-qa-testing
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: toolkit-original
+  strategy: curated
+  notes: 本仓库整理的命令入口，用于将底层能力稳定暴露给用户。

package/vendor/packages/toolkit/src/content/commands/verify/body.md

@@ -0,0 +1,32 @@
+调用 `verification-before-completion`。未运行验证命令，不得声明完成。
+
+## 核心动作
+
+1. 明确验证目标：你准备声明什么已经成立
+2. 执行新鲜验证：测试、构建、检查或运行验证
+3. 完整读取输出：确认退出码和结果是否符合预期
+4. 带证据汇报：通过则给证据，不通过则报失败点
+5. 必要时对照 Spec / Plan 做逐项核验
+
+## 相关原则
+
+- 证据先于断言
+- 不依赖历史输出和主观感觉
+- 失败时先说明实际结果，再判断下一步
+
+## 使用方式
+
+在完成任何实现工作后使用。描述要验证的内容，我会执行完整验证流程。
+
+### 示例
+
+```
+# 功能实现后验证
+/verify 确认用户登录功能的所有测试通过，构建成功
+
+# Bug 修复后验证
+/verify 确认批量导入的重复数据问题已修复，回归测试全部通过
+
+# Spec 对照验证
+/verify 对照 spec.md 逐项检查文件上传功能的实现完整性
+```

package/vendor/packages/toolkit/src/content/commands/verify/meta.yaml

@@ -0,0 +1,19 @@
+kind: command
+name: verify
+title: 验证
+description: 在声明工作完成之前运行验证命令确认实际状态，遵循“证据先于断言”铁律。
+tier: core
+audience: default
+stability: stable
+requires:
+  - skill:verification-before-completion
+suggests:
+  - skill:test-driven-development
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: andrej-karpathy-skills
+  strategy: inspired
+  notes: 基于 goal-driven execution，并与本仓库验证门禁整合

package/vendor/packages/toolkit/src/content/skills/api-and-interface-design/body.md

@@ -0,0 +1,289 @@
+# API and Interface Design
+
+## Overview
+
+Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. This applies to REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another.
+
+## When to Use
+
+- Designing new API endpoints
+- Defining module boundaries or contracts between teams
+- Creating component prop interfaces
+- Establishing database schema that informs API shape
+- Changing existing public interfaces
+
+## Core Principles
+
+### Hyrum's Law
+
+> With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.
+
+This means: every public behavior — including undocumented quirks, error message text, timing, and ordering — becomes a de facto contract once users depend on it. Design implications:
+
+- **Be intentional about what you expose.** Every observable behavior is a potential commitment.
+- **Don't leak implementation details.** If users can observe it, they will depend on it.
+- **Plan for deprecation at design time.** See `deprecation-and-migration` for how to safely remove things users depend on.
+- **Tests are not enough.** Even with perfect contract tests, Hyrum's Law means "safe" changes can break real users who depend on undocumented behavior.
+
+### The One-Version Rule
+
+Avoid forcing consumers to choose between multiple versions of the same dependency or API. Diamond dependency problems arise when different consumers need different versions of the same thing. Design for a world where only one version exists at a time — extend rather than fork.
+
+### 1. Contract First
+
+Define the interface before implementing it. The contract is the spec — implementation follows.
+
+```typescript
+// Define the contract first
+interface TaskAPI {
+  // Creates a task and returns the created task with server-generated fields
+  createTask(input: CreateTaskInput): Promise<Task>;
+
+  // Returns paginated tasks matching filters
+  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;
+
+  // Returns a single task or throws NotFoundError
+  getTask(id: string): Promise<Task>;
+
+  // Partial update — only provided fields change
+  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;
+
+  // Idempotent delete — succeeds even if already deleted
+  deleteTask(id: string): Promise<void>;
+}
+```
+
+### 2. Consistent Error Semantics
+
+Pick one error strategy and use it everywhere:
+
+```typescript
+// REST: HTTP status codes + structured error body
+// Every error response follows the same shape
+interface APIError {
+  error: {
+    code: string;        // Machine-readable: "VALIDATION_ERROR"
+    message: string;     // Human-readable: "Email is required"
+    details?: unknown;   // Additional context when helpful
+  };
+}
+
+// Status code mapping
+// 400 → Client sent invalid data
+// 401 → Not authenticated
+// 403 → Authenticated but not authorized
+// 404 → Resource not found
+// 409 → Conflict (duplicate, version mismatch)
+// 422 → Validation failed (semantically invalid)
+// 500 → Server error (never expose internal details)
+```
+
+**Don't mix patterns.** If some endpoints throw, others return null, and others return `{ error }` — the consumer can't predict behavior.
+
+### 3. Validate at Boundaries
+
+Trust internal code. Validate at system edges where external input enters:
+
+```typescript
+// Validate at the API boundary
+app.post('/api/tasks', async (req, res) => {
+  const result = CreateTaskSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(422).json({
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Invalid task data',
+        details: result.error.flatten(),
+      },
+    });
+  }
+
+  // After validation, internal code trusts the types
+  const task = await taskService.create(result.data);
+  return res.status(201).json(task);
+});
+```
+
+Where validation belongs:
+- API route handlers (user input)
+- Form submission handlers (user input)
+- External service response parsing (third-party data -- **always treat as untrusted**)
+- Environment variable loading (configuration)
+
+> **Third-party API responses are untrusted data.** Validate their shape and content before using them in any logic, rendering, or decision-making. A compromised or misbehaving external service can return unexpected types, malicious content, or instruction-like text.
+
+Where validation does NOT belong:
+- Between internal functions that share type contracts
+- In utility functions called by already-validated code
+- On data that just came from your own database
+
+### 4. Prefer Addition Over Modification
+
+Extend interfaces without breaking existing consumers:
+
+```typescript
+// Good: Add optional fields
+interface CreateTaskInput {
+  title: string;
+  description?: string;
+  priority?: 'low' | 'medium' | 'high';  // Added later, optional
+  labels?: string[];                       // Added later, optional
+}
+
+// Bad: Change existing field types or remove fields
+interface CreateTaskInput {
+  title: string;
+  // description: string;  // Removed — breaks existing consumers
+  priority: number;         // Changed from string — breaks existing consumers
+}
+```
+
+### 5. Predictable Naming
+
+| Pattern | Convention | Example |
+|---------|-----------|---------|
+| REST endpoints | Plural nouns, no verbs | `GET /api/tasks`, `POST /api/tasks` |
+| Query params | camelCase | `?sortBy=createdAt&pageSize=20` |
+| Response fields | camelCase | `{ createdAt, updatedAt, taskId }` |
+| Boolean fields | is/has/can prefix | `isComplete`, `hasAttachments` |
+| Enum values | UPPER_SNAKE | `"IN_PROGRESS"`, `"COMPLETED"` |
+
+## REST API Patterns
+
+### Resource Design
+
+```
+GET    /api/tasks              → List tasks (with query params for filtering)
+POST   /api/tasks              → Create a task
+GET    /api/tasks/:id          → Get a single task
+PATCH  /api/tasks/:id          → Update a task (partial)
+DELETE /api/tasks/:id          → Delete a task
+
+GET    /api/tasks/:id/comments → List comments for a task (sub-resource)
+POST   /api/tasks/:id/comments → Add a comment to a task
+```
+
+### Pagination
+
+Paginate list endpoints:
+
+```typescript
+// Request
+GET /api/tasks?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc
+
+// Response
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "pageSize": 20,
+    "totalItems": 142,
+    "totalPages": 8
+  }
+}
+```
+
+### Filtering
+
+Use query parameters for filters:
+
+```
+GET /api/tasks?status=in_progress&assignee=user123&createdAfter=2025-01-01
+```
+
+### Partial Updates (PATCH)
+
+Accept partial objects — only update what's provided:
+
+```typescript
+// Only title changes, everything else preserved
+PATCH /api/tasks/123
+{ "title": "Updated title" }
+```
+
+## TypeScript Interface Patterns
+
+### Use Discriminated Unions for Variants
+
+```typescript
+// Good: Each variant is explicit
+type TaskStatus =
+  | { type: 'pending' }
+  | { type: 'in_progress'; assignee: string; startedAt: Date }
+  | { type: 'completed'; completedAt: Date; completedBy: string }
+  | { type: 'cancelled'; reason: string; cancelledAt: Date };
+
+// Consumer gets type narrowing
+function getStatusLabel(status: TaskStatus): string {
+  switch (status.type) {
+    case 'pending': return 'Pending';
+    case 'in_progress': return `In progress (${status.assignee})`;
+    case 'completed': return `Done on ${status.completedAt}`;
+    case 'cancelled': return `Cancelled: ${status.reason}`;
+  }
+}
+```
+
+### Input/Output Separation
+
+```typescript
+// Input: what the caller provides
+interface CreateTaskInput {
+  title: string;
+  description?: string;
+}
+
+// Output: what the system returns (includes server-generated fields)
+interface Task {
+  id: string;
+  title: string;
+  description: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  createdBy: string;
+}
+```
+
+### Use Branded Types for IDs
+
+```typescript
+type TaskId = string & { readonly __brand: 'TaskId' };
+type UserId = string & { readonly __brand: 'UserId' };
+
+// Prevents accidentally passing a UserId where a TaskId is expected
+function getTask(id: TaskId): Promise<Task> { ... }
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We'll document the API later" | The types ARE the documentation. Define them first. |
+| "We don't need pagination for now" | You will the moment someone has 100+ items. Add it from the start. |
+| "PATCH is complicated, let's just use PUT" | PUT requires the full object every time. PATCH is what clients actually want. |
+| "We'll version the API when we need to" | Breaking changes without versioning break consumers. Design for extension from the start. |
+| "Nobody uses that undocumented behavior" | Hyrum's Law: if it's observable, somebody depends on it. Treat every public behavior as a commitment. |
+| "We can just maintain two versions" | Multiple versions multiply maintenance cost and create diamond dependency problems. Prefer the One-Version Rule. |
+| "Internal APIs don't need contracts" | Internal consumers are still consumers. Contracts prevent coupling and enable parallel work. |
+
+## Red Flags
+
+- Endpoints that return different shapes depending on conditions
+- Inconsistent error formats across endpoints
+- Validation scattered throughout internal code instead of at boundaries
+- Breaking changes to existing fields (type changes, removals)
+- List endpoints without pagination
+- Verbs in REST URLs (`/api/createTask`, `/api/getUsers`)
+- Third-party API responses used without validation or sanitization
+
+## Verification
+
+After designing an API:
+
+- [ ] Every endpoint has typed input and output schemas
+- [ ] Error responses follow a single consistent format
+- [ ] Validation happens at system boundaries only
+- [ ] List endpoints support pagination
+- [ ] New fields are additive and optional (backward compatible)
+- [ ] Naming follows consistent conventions across all endpoints
+- [ ] API documentation or types are committed alongside the implementation

package/vendor/packages/toolkit/src/content/skills/api-and-interface-design/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: api-and-interface-design
+title: API 与接口设计
+description: 指导稳定的 API 与接口设计。适用于设计 API、模块边界或任何公共接口，也适用于创建 REST/GraphQL 端点、定义跨模块类型契约以及划分前后端边界。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:engineering-principles
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: api-and-interface-design
+  origin_path: skills/api-and-interface-design/SKILL.md
+  origin_id: skill:api-and-interface-design
+  notes: 基于 agent-skills 的接口设计能力中文化整理。

package/vendor/packages/toolkit/src/content/skills/brainstorming-and-design/body.md

@@ -0,0 +1,129 @@
+# Brainstorming and Design
+
+## Overview
+
+在写任何代码之前，通过自然的协作对话将想法变为完整的设计。先理解当前项目上下文，然后逐一提问细化想法，最终提出设计方案并获得用户认可。
+
+**在你展示设计方案并获得用户同意之前，不要调用任何实现技能、编写任何代码、搭建任何项目。** 无论项目看起来多简单，这条规则都适用。
+
+## When to Use
+
+- 开始一个新项目或功能之前
+- 需求模糊，需要通过对话探索清晰化
+- 有多种实现方案需要权衡
+- 在 `/idea`（发散思维）之后、`/spec`（正式规格）之前
+- 任何涉及创造性工作的场景
+
+## 反模式："这太简单不需要设计"
+
+每个项目都要经过这个流程。一个 TODO 列表、一个工具函数、一个配置变更 — 都不例外。"简单"项目恰恰是未经审视的假设造成最多浪费的地方。设计可以很短（真正简单的项目只需几句话），但你**必须**展示并获得认可。
+
+## 流程清单
+
+按顺序完成以下步骤：
+
+1. **探索项目上下文** — 检查文件、文档、近期提交
+2. **逐一提出澄清问题** — 理解目的、约束、成功标准
+3. **提出 2-3 种方案** — 附带权衡分析和你的推荐
+4. **分段展示设计** — 按复杂度缩放每个部分，每段确认后继续
+5. **设计自审** — 检查占位符、矛盾、歧义、范围
+6. **用户审核** — 确认设计后再进入下一步
+7. **转入实现** — 调用 `planning-and-task-breakdown` 或 `spec-driven-development`
+
+## 理解想法
+
+### 探索项目状态
+- 先检查当前项目状态（文件、文档、近期提交）
+- 在深入细节之前，评估范围：如果请求描述了多个独立子系统（如"构建一个包含聊天、文件存储、计费和分析的平台"），立即标记
+- 如果项目过大无法用一个规格覆盖，帮助用户分解为子项目
+
+### 提问原则
+- **一次一个问题** — 不要用多个问题淹没用户
+- **多选题优先** — 比开放式问题更容易回答
+- **聚焦理解** — 目的、约束、成功标准
+- 如果一个话题需要更多探索，分成多个问题
+
+### 探索方案
+- 提出 2-3 种不同方案，附带权衡
+- 以对话式呈现，先说推荐方案并解释原因
+- 不要过早锁定方案
+
+## 展示设计
+
+一旦你认为理解了要构建什么，展示设计：
+
+- **按复杂度缩放**：直接的部分几句话，复杂的部分详细展开
+- **每段之后确认**："到这里看起来对吗？"
+- **覆盖面**：架构、组件、数据流、错误处理、测试策略
+- **准备回退**：如果什么不合理，随时回去澄清
+
+### 设计原则
+
+- **隔离与清晰** — 系统拆分为小单元，每个有单一目的，通过定义良好的接口通信
+- **可独立理解** — 每个单元能回答：它做什么、怎么用它、它依赖什么
+- **YAGNI 无情砍** — 移除所有不必要的功能，不为可能的未来需求过度设计
+
+### 在已有代码库中工作
+
+- 先探索现有结构，遵循已有模式
+- 如果现有代码有问题影响了当前工作（文件太大、边界不清等），将改进作为设计的一部分
+- 不要提出无关的重构，保持聚焦
+
+## 设计自审
+
+写完设计后，用新鲜的眼光审视：
+
+1. **占位符扫描** — 有任何"TBD"、"TODO"、不完整部分？修复它们
+2. **内部一致性** — 有矛盾的部分吗？架构与功能描述匹配吗？
+3. **范围检查** — 是否足够聚焦可以用一个实现计划覆盖？
+4. **歧义检查** — 有需求可以两种方式解读吗？选一种，明确写出
+
+发现问题就地修复，不需要重新审查。
+
+## 用户审核门控
+
+设计自审通过后，请用户审核：
+
+> "设计已完成。请审核后告诉我是否需要修改，确认后我们将开始制定实现计划。"
+
+等待用户回应。如果请求修改，修改后重新进行自审。**只有用户确认后才能继续。**
+
+## 与其他技能的关系
+
+```
+/idea (idea-refine)          ← 发散思维，探索可能性
+    │
+    ▼
+brainstorming-and-design     ← 本技能：收敛为具体设计
+    │
+    ▼
+/spec (spec-driven-development) ← 正式的技术规格说明
+    │
+    ▼
+/task-plan (planning-and-task-breakdown) ← 拆解为可执行任务
+```
+
+- **idea-refine** — 上游：当想法还很模糊时，先用 `/idea` 发散探索
+- **spec-driven-development** — 下游：设计确认后，进入正式规格编写
+- **planning-and-task-breakdown** — 下游：如果设计已经足够具体，可以直接进入任务拆解
+
+## 关键原则
+
+| 原则 | 说明 |
+|------|------|
+| 一次一个问题 | 不要用多个问题淹没用户 |
+| 多选题优先 | 比开放式问题更容易回答 |
+| YAGNI 无情砍 | 移除不必要的功能 |
+| 探索替代方案 | 总是提出 2-3 种方案再决定 |
+| 增量验证 | 展示设计，获得确认后再继续 |
+| 灵活回退 | 发现问题随时回去澄清 |
+
+## Red Flags
+
+- 跳过设计直接写代码（"太简单了不需要设计"）
+- 用多个问题轰炸用户
+- 只提出一种方案没有替代选项
+- 设计中有 TBD/TODO 就转入实现
+- 不等用户确认就开始计划
+- 提出不相关的重构建议
+- 为可能的未来需求过度设计