cdspec 0.1.0

package/src/task-core/storage.ts

@@ -0,0 +1,177 @@
+import { readFile, rm, writeFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, pathExists } from "../utils/fs.js";
+import { parseFrontmatter, stringifyFrontmatter } from "../utils/frontmatter.js";
+import { ArchiveRecord, TaskItem, TaskStatus } from "./types.js";
+
+const ROOT_DIR = ".cdspec";
+const TASKS_DIR = "tasks";
+const ARCHIVE_DIR = "archive";
+
+export function taskDir(cwd: string): string {
+  return path.join(cwd, ROOT_DIR, TASKS_DIR);
+}
+
+export function archiveDir(cwd: string): string {
+  return path.join(cwd, ROOT_DIR, ARCHIVE_DIR);
+}
+
+export async function initTaskWorkspace(cwd: string): Promise<void> {
+  await ensureDir(taskDir(cwd));
+  await ensureDir(archiveDir(cwd));
+}
+
+export async function saveTask(cwd: string, task: TaskItem): Promise<void> {
+  await initTaskWorkspace(cwd);
+  const targetFile = path.join(taskDir(cwd), `${task.id}.md`);
+  const body = `# ${task.title}\n\n- status: ${task.status}\n- source: ${task.source}\n`;
+  const content = stringifyFrontmatter(
+    {
+      id: task.id,
+      title: task.title,
+      status: task.status,
+      source: task.source,
+      created_at: task.createdAt,
+      updated_at: task.updatedAt
+    },
+    body
+  );
+  await writeFile(targetFile, content, "utf8");
+}
+
+export async function loadTask(cwd: string, id: string): Promise<TaskItem | null> {
+  const file = path.join(taskDir(cwd), `${id}.md`);
+  if (!(await pathExists(file))) return null;
+  const raw = await readFile(file, "utf8");
+  const parsed = parseFrontmatter(raw);
+  return {
+    id: parsed.attributes.id,
+    title: parsed.attributes.title,
+    status: parseStatus(parsed.attributes.status),
+    source: parsed.attributes.source,
+    createdAt: parsed.attributes.created_at,
+    updatedAt: parsed.attributes.updated_at
+  };
+}
+
+export async function updateTaskStatus(
+  cwd: string,
+  id: string,
+  next: TaskStatus
+): Promise<TaskItem> {
+  const current = await loadTask(cwd, id);
+  if (!current) {
+    throw new Error(`Task "${id}" not found.`);
+  }
+  if (!canTransition(current.status, next)) {
+    throw new Error(`Invalid status transition: ${current.status} -> ${next}.`);
+  }
+  const updated: TaskItem = {
+    ...current,
+    status: next,
+    updatedAt: new Date().toISOString()
+  };
+  await saveTask(cwd, updated);
+  return updated;
+}
+
+export async function archiveTask(cwd: string, id: string): Promise<ArchiveRecord> {
+  const current = await loadTask(cwd, id);
+  if (!current) {
+    throw new Error(`Task "${id}" not found.`);
+  }
+  if (current.status !== "done") {
+    throw new Error(`Task "${id}" must be done before archive.`);
+  }
+
+  const archived: ArchiveRecord = {
+    ...current,
+    archivedAt: new Date().toISOString()
+  };
+  const sourceFile = path.join(taskDir(cwd), `${id}.md`);
+  const archiveFile = path.join(archiveDir(cwd), `${id}.md`);
+  const body = `# ${archived.title}\n\nArchived from ${sourceFile.replaceAll("\\", "/")}.\n`;
+  const content = stringifyFrontmatter(
+    {
+      id: archived.id,
+      title: archived.title,
+      status: archived.status,
+      source: archived.source,
+      created_at: archived.createdAt,
+      updated_at: archived.updatedAt,
+      archived_at: archived.archivedAt
+    },
+    body
+  );
+  await writeFile(archiveFile, content, "utf8");
+  await rm(sourceFile, { force: true });
+  return archived;
+}
+
+export async function refreshTaskIndex(cwd: string): Promise<void> {
+  await initTaskWorkspace(cwd);
+  const tasks = await loadByDir(taskDir(cwd));
+  const grouped = {
+    todo: tasks.filter((task) => task.status === "todo"),
+    in_progress: tasks.filter((task) => task.status === "in_progress"),
+    done: tasks.filter((task) => task.status === "done")
+  };
+  const lines = [
+    "# Task Index",
+    "",
+    "## todo",
+    ...grouped.todo.map((task) => `- [${task.id}] ${task.title}`),
+    "",
+    "## in_progress",
+    ...grouped.in_progress.map((task) => `- [${task.id}] ${task.title}`),
+    "",
+    "## done",
+    ...grouped.done.map((task) => `- [${task.id}] ${task.title}`),
+    ""
+  ];
+  await writeFile(path.join(taskDir(cwd), "index.md"), lines.join("\n"), "utf8");
+}
+
+export async function refreshArchiveIndex(cwd: string): Promise<void> {
+  await initTaskWorkspace(cwd);
+  const records = await loadByDir(archiveDir(cwd));
+  const lines = [
+    "# Archive Index",
+    "",
+    ...records.map((record) => `- [${record.id}] ${record.title}`),
+    ""
+  ];
+  await writeFile(path.join(archiveDir(cwd), "index.md"), lines.join("\n"), "utf8");
+}
+
+async function loadByDir(dirPath: string): Promise<TaskItem[]> {
+  if (!(await pathExists(dirPath))) return [];
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  const result: TaskItem[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name === "index.md") continue;
+    const raw = await readFile(path.join(dirPath, entry.name), "utf8");
+    const parsed = parseFrontmatter(raw);
+    result.push({
+      id: parsed.attributes.id,
+      title: parsed.attributes.title,
+      status: parseStatus(parsed.attributes.status),
+      source: parsed.attributes.source,
+      createdAt: parsed.attributes.created_at,
+      updatedAt: parsed.attributes.updated_at
+    });
+  }
+  return result;
+}
+
+function parseStatus(input: string): TaskStatus {
+  if (input === "todo" || input === "in_progress" || input === "done") return input;
+  return "todo";
+}
+
+function canTransition(current: TaskStatus, next: TaskStatus): boolean {
+  if (current === next) return true;
+  if (current === "todo" && next === "in_progress") return true;
+  if (current === "in_progress" && next === "done") return true;
+  return false;
+}

package/src/task-core/types.ts

@@ -0,0 +1,15 @@
+export type TaskStatus = "todo" | "in_progress" | "done";
+
+export interface TaskItem {
+  id: string;
+  title: string;
+  status: TaskStatus;
+  source: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ArchiveRecord extends TaskItem {
+  archivedAt: string;
+}
+

package/src/types/yaml.d.ts

@@ -0,0 +1,4 @@
+declare module "yaml" {
+  export function parse(input: string): unknown;
+}
+

package/src/utils/frontmatter.ts

@@ -0,0 +1,55 @@
+export interface FrontmatterResult {
+  attributes: Record<string, string>;
+  body: string;
+}
+
+export function parseFrontmatter(content: string): FrontmatterResult {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { attributes: {}, body: normalized };
+  }
+
+  const endIndex = normalized.indexOf("\n---\n", 4);
+  if (endIndex === -1) {
+    return { attributes: {}, body: normalized };
+  }
+
+  const header = normalized.slice(4, endIndex);
+  const body = normalized.slice(endIndex + 5);
+  const attributes: Record<string, string> = {};
+
+  for (const rawLine of header.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const idx = line.indexOf(":");
+    if (idx <= 0) continue;
+
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    value = stripQuotes(value);
+    attributes[key] = value;
+  }
+
+  return { attributes, body };
+}
+
+export function stringifyFrontmatter(
+  attributes: Record<string, string>,
+  body: string
+): string {
+  const lines = Object.entries(attributes).map(([key, value]) => {
+    const escaped = value.replace(/"/g, '\\"');
+    return `${key}: "${escaped}"`;
+  });
+  return `---\n${lines.join("\n")}\n---\n\n${body.trimEnd()}\n`;
+}
+
+function stripQuotes(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}

package/src/utils/fs.ts

@@ -0,0 +1,41 @@
+import { mkdir, readdir, rm, stat, copyFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function pathExists(target: string): Promise<boolean> {
+  try {
+    await stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function emptyDir(dirPath: string): Promise<void> {
+  await rm(dirPath, { recursive: true, force: true });
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function copyDir(srcDir: string, dstDir: string): Promise<void> {
+  await ensureDir(dstDir);
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const dstPath = path.join(dstDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, dstPath);
+      continue;
+    }
+    await copyFile(srcPath, dstPath);
+  }
+}
+
+export async function listDirs(dirPath: string): Promise<string[]> {
+  if (!(await pathExists(dirPath))) return [];
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+

package/templates/design-doc/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: design-doc
+description: 管理业务详细设计文档的全生命周期：首次基线、增量 feature 文档、归档合并。适用于首次开发与迭代改造，避免小改动频繁新建基线版本文件，同时保留 feature 变更历史。
+---
+
+# 详细设计文档规范
+
+## 何时使用
+当用户要做以下事情时使用本技能：
+1. 首次建立某业务的详细设计基线文档。
+2. 在既有业务上做增量改造，需要单独写 feature 设计文档。
+3. 需求上线后把 feature 合并回基线，并保留 feature 历史。
+
+## 目标
+1. 基线文档始终保持“当前真实设计”。
+2. feature 文档只描述“增量变化”，避免重复拷贝全量内容。
+3. 小改动默认不新建基线版本文件，直接更新基线。
+4. 归档后既能追溯 feature 历史，也能一眼看到当前基线。
+
+## 目录规范（硬约束）
+以 `docs/<业务>/` 为根目录，固定结构如下（必须遵守）：
+
+```text
+docs/<业务>/
+  baseline-<业务>.md
+  feature/
+    feature-YYYYMMDD-<slug>.md
+  archive-log.md
+```
+
+说明：
+1. `baseline-<业务>.md`：唯一基线文档，持续维护。
+2. `feature/*.md`：每个迭代一个 feature 文档。
+3. `archive-log.md`：记录每个 feature 的归档时间、归档人、合并摘要。
+4. 同一个业务只允许一个目录，例如“生产订单”只能落在 `docs/生产订单/`。
+5. 本技能产出的业务文档禁止写到 `docs/` 根目录或其他目录。
+6. 同一个业务目录下只允许一个基线文件：`baseline-<业务>.md`。
+
+## 路径保障规则（部门推广版）
+1. 当用户指定某业务时，先确定业务目录：`docs/<业务>/`。
+2. 若目录不存在：创建目录及标准骨架（baseline、feature、archive-log）。
+3. 若目录已存在：只允许在该目录内新增/修改，不得跨目录写入。
+4. 若发现同业务多份 baseline（如 `baseline-<业务>-v2.md` 与 `baseline-<业务>.md` 并存）：
+   - 默认停止写入并先与用户确认；
+   - 仅在用户明确同意“里程碑双基线”时继续。
+5. feature 文件必须写到 `docs/<业务>/feature/feature-YYYYMMDD-<slug>.md`。
+6. 归档日志必须写到 `docs/<业务>/archive-log.md`。
+
+## 标准流程
+
+### A. 首次开发（建立基线）
+1. 创建 `baseline-<业务>.md`，按基线模板填写。
+2. 创建 `archive-log.md`，初始化为空日志。
+3. 若已有历史文档，先整理为一份“可读、可执行”的基线后再进入增量模式。
+
+基线模板见：`references/基线模板.md`
+基线示例见：`references/生产工单基线示例.md`
+
+### B. 增量开发（创建 feature）
+1. 新建 `feature/feature-YYYYMMDD-<slug>.md`。
+2. 只写变更内容，不重复整份基线。
+3. 每个变更项都要指向基线对应章节（例如：`baseline-生产工单.md#2.1`）。
+4. feature 文档至少覆盖：数据库变化、接口变化、关键方法伪代码变化。
+
+feature 模板见：`references/增量需求模板.md`
+
+### C. 归档合并（上线后执行）
+1. 将 feature 中已验收内容合并到 `baseline-<业务>.md`。
+2. 在 feature 文档头部更新归档元数据：`status=archived`、`merged_to`、`merged_at`。
+3. 向 `archive-log.md` 追加一条归档记录。
+4. feature 文件保留，不删除。
+
+归档清单见：`references/归档检查清单.md`
+
+## 版本与变更策略
+1. 小改动：直接改 `baseline-<业务>.md`，不新建基线版本文件。
+2. 中改动：走 feature -> 合并归档流程。
+3. 大改动（架构重构/跨域重排）：允许打里程碑版本（如 `baseline-<业务>-v2.md`），但需在 `archive-log.md` 记录原因。
+
+## 执行约束
+1. 任何改动先更新文档，再推进代码。
+2. 接口定义优先使用 `jsonc` 代码块示例，避免重复维护表格。
+3. 索引策略保持克制：优先关联 ID 索引，避免无效堆叠。
+4. 文档中的英文方法名与代码方法名必须一一对应。
+5. 文档不写个人本地绝对路径（如 `/Users/...`），代码来源仅写仓库/模块名称。
+6. 文档不强绑定“单控制器基线”，接口按业务路由分组展示即可。
+7. `archive-log.md` 的“合并人”必须使用真实 `git config user.name`。
+8. 写入前必须先做目录校验，校验通过后再落文档（可执行 `scripts/validate_doc_layout.sh <业务>`）。
+
+## 输出要求（对 AI）
+1. 当用户要求“增量改造”时，默认生成 feature 文档，不复制全量基线。
+2. 当用户要求“归档”时，默认执行：
+   - 更新 baseline
+   - 更新 feature 状态
+   - 追加 archive-log
+3. 默认不新建新的基线版本文件，除非用户明确要求“里程碑重置基线”。
+4. 生成文档时先对齐 `references/生产工单基线示例.md` 的表达风格，再落模板内容。
+5. 每次执行后必须明确输出本次写入的目标路径清单（至少 baseline/feature/archive-log 之一）。
+6. 若路径不符合 `docs/<业务>/` 规则，必须先纠正路径再执行，不得直接写入。

package/templates/design-doc/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "详细设计文档规范"
+  short_description: "管理业务详细设计文档全生命周期：基线、feature、归档"
+  default_prompt: "使用 $design-doc-lifecycle 按目录约束完成详细设计文档的基线建立、增量 feature 文档编写与归档合并。"

package/templates/design-doc/references//345/237/272/347/272/277/346/250/241/346/235/277.md

@@ -0,0 +1,46 @@
+# <业务>详细设计（基线）
+
+> 目录约束：本文件必须位于 `docs/<业务>/baseline-<业务>.md`，且同业务目录下仅此一份 baseline。
+
+## 1. 文档信息
+- 业务：<业务>
+- 状态：active
+- 最后更新：<YYYY-MM-DD>
+
+## 2. 数据库设计
+### 2.1 核心表字段
+- 表A（字段、类型、非空、默认值、字典key、说明）
+- 表B（字段、类型、非空、默认值、字典key、说明）
+
+### 2.2 索引与约束
+- 只保留必要索引，优先关联ID索引。
+
+### 2.3 字典项说明
+- key -> values
+
+## 3. 关键前后端接口定义（JSON 示例）
+### 3.1 <接口名>
+入参示例：
+```jsonc
+{
+  "fieldA": "value" // 说明
+}
+```
+出参示例：
+```jsonc
+{
+  "success": true,
+  "result": {
+    "fieldB": "value" // 说明
+  }
+}
+```
+
+## 4. 关键方法清单
+- 中文动作 -> 英文方法名 -> 签名
+
+## 5. 关键方法伪代码
+### 5.1 <methodName>（<中文动作>）
+```text
+# 关键流程伪代码（中文注释）
+```

package/templates/design-doc/references//345/242/236/351/207/217/351/234/200/346/261/202/346/250/241/346/235/277.md

@@ -0,0 +1,32 @@
+# <业务>增量设计（feature）
+
+> 目录约束：本文件必须位于 `docs/<业务>/feature/feature-YYYYMMDD-<slug>.md`。
+
+## 1. 元数据
+- feature_key: feature-<YYYYMMDD>-<slug>
+- status: draft
+- baseline: docs/<业务>/baseline-<业务>.md
+- created_at: <YYYY-MM-DD>
+- merged_to: <归档后填写>
+- merged_at: <归档后填写>
+
+## 2. 变更背景
+- 为什么要改。
+
+## 3. 数据库增量
+- 基线章节引用：<如 baseline-xxx.md#2.1>
+- 新增/修改/删除字段与索引。
+
+## 4. 接口增量（JSON 示例）
+- 基线章节引用：<如 baseline-xxx.md#3.1>
+- 只写变化接口。
+
+## 5. 方法增量
+- 基线章节引用：<如 baseline-xxx.md#5.2>
+- 只写变化的方法签名与伪代码。
+
+## 6. 合并清单（归档前打勾）
+- [ ] 已合并数据库变化到基线
+- [ ] 已合并接口变化到基线
+- [ ] 已合并方法变化到基线
+- [ ] 已更新 feature 状态为 archived

package/templates/design-doc/references//345/275/222/346/241/243/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,15 @@
+# 归档操作清单
+
+0. 先执行目录校验：`scripts/validate_doc_layout.sh <业务>`。
+1. 打开目标 feature 文档，确认状态为 `draft` 且已验收。
+2. 按 feature 内容逐项合并到基线文档。
+3. 更新 feature 元数据：
+- `status: archived`
+- `merged_to: docs/<业务>/baseline-<业务>.md`
+- `merged_at: <YYYY-MM-DD>`
+4. 在 `archive-log.md` 追加记录：
+- feature_key
+- 合并日期
+- 合并人（取 `git config user.name`）
+- 摘要（数据库/接口/方法）
+5. 自检：基线是否已包含所有变更，feature 是否保留原文。