cdspec 0.1.0

package/templates/standards-backend/references//350/256/276/350/256/241/346/250/241/345/274/217/350/220/275/345/234/260/346/211/213/345/206/214.md

@@ -0,0 +1,395 @@
+# 常用设计模式落地手册（实现示例版）
+
+## 目录
+1. [使用说明](#1-使用说明)
+2. [Adapter（适配器）](#2-adapter适配器)
+3. [Strategy（策略）](#3-strategy策略)
+4. [Factory（工厂）](#4-factory工厂)
+5. [Chain Of Responsibility（责任链）](#5-chain-of-responsibility责任链)
+6. [Template Method（模板方法）](#6-template-method模板方法)
+7. [Singleton（单例）](#7-singleton单例)
+8. [评审清单（模式维度）](#8-评审清单模式维度)
+
+## 1. 使用说明
+1. 每个模式都提供可直接复用的完整最小实现。
+2. 代码注释统一使用中文，重点解释“做什么、为什么这样做”。
+3. 示例优先体现分层边界和扩展点，避免过度抽象。
+
+## 2. Adapter（适配器）
+### 2.1 场景
+1. 领域接口稳定，但遗留系统接口不一致。
+2. 需要隔离三方字段，避免污染主业务流程。
+
+### 2.2 完整示例
+```java
+import java.util.List;
+import java.util.Objects;
+
+// 领域侧稳定接口：上层只依赖它，不感知遗留系统细节
+interface ReceiptDomainService {
+    void applyActuals(List<ReceiptItem> items);
+}
+
+// 领域参数对象
+record ReceiptItem(String materialId, int actualDelta) {}
+
+// 遗留系统客户端（不可改）
+class LegacyReceiptClient {
+    public void apply(String code, int qty) {
+        System.out.println("legacy apply -> code=" + code + ", qty=" + qty);
+    }
+}
+
+// 适配器：把领域调用转换成遗留系统调用
+class ReceiptAdapter implements ReceiptDomainService {
+
+    private final LegacyReceiptClient legacyClient;
+
+    ReceiptAdapter(LegacyReceiptClient legacyClient) {
+        this.legacyClient = legacyClient;
+    }
+
+    @Override
+    public void applyActuals(List<ReceiptItem> items) {
+        // 防御式校验：空集合直接返回，避免无意义调用
+        if (Objects.isNull(items) || items.isEmpty()) {
+            return;
+        }
+        // 统一在适配器内做协议转换，主流程不感知转换细节
+        for (ReceiptItem item : items) {
+            legacyClient.apply(item.materialId(), item.actualDelta());
+        }
+    }
+}
+
+class AdapterDemo {
+    public static void main(String[] args) {
+        // 上层只认领域接口，具体适配实现可替换
+        ReceiptDomainService service = new ReceiptAdapter(new LegacyReceiptClient());
+        service.applyActuals(List.of(new ReceiptItem("M-001", 3), new ReceiptItem("M-002", -1)));
+    }
+}
+```
+
+## 3. Strategy（策略）
+### 3.1 场景
+1. 不同租户/客户/工厂存在差异规则。
+2. 规则会持续增加，不能靠 `if-else` 堆叠。
+
+### 3.2 完整示例
+```java
+import java.math.BigDecimal;
+import java.util.List;
+
+// 运费计算上下文
+record FreightContext(String tenantId, BigDecimal amount) {}
+
+// 策略接口：只暴露当前场景真正需要的行为
+interface FreightStrategy {
+    boolean supports(String tenantId);
+    BigDecimal calculate(FreightContext context);
+}
+
+// 默认策略：兜底实现
+class DefaultFreightStrategy implements FreightStrategy {
+    @Override
+    public boolean supports(String tenantId) {
+        return true;
+    }
+
+    @Override
+    public BigDecimal calculate(FreightContext context) {
+        return context.amount().multiply(new BigDecimal("0.05"));
+    }
+}
+
+// VIP 策略：差异化规则
+class VipFreightStrategy implements FreightStrategy {
+    @Override
+    public boolean supports(String tenantId) {
+        return "VIP".equalsIgnoreCase(tenantId);
+    }
+
+    @Override
+    public BigDecimal calculate(FreightContext context) {
+        return context.amount().multiply(new BigDecimal("0.02"));
+    }
+}
+
+// 应用服务：通过策略列表选择实现，去除硬编码分支
+class FreightService {
+
+    private final List<FreightStrategy> strategies;
+
+    FreightService(List<FreightStrategy> strategies) {
+        this.strategies = strategies;
+    }
+
+    public BigDecimal quote(FreightContext context) {
+        return strategies.stream()
+                .filter(s -> s.supports(context.tenantId()))
+                .findFirst()
+                .orElseThrow(() -> new IllegalStateException("未匹配到运费策略"))
+                .calculate(context);
+    }
+}
+
+class StrategyDemo {
+    public static void main(String[] args) {
+        // 顺序很关键：先放专用策略，再放默认策略
+        FreightService service = new FreightService(List.of(new VipFreightStrategy(), new DefaultFreightStrategy()));
+        System.out.println(service.quote(new FreightContext("VIP", new BigDecimal("1000"))));
+    }
+}
+```
+
+## 4. Factory（工厂）
+### 4.1 场景
+1. 按类型/编码选择处理器。
+2. 创建逻辑集中管理，调用方不关心具体实现。
+
+### 4.2 完整示例
+```java
+import java.util.Map;
+import java.util.Objects;
+
+// 导出处理器抽象
+interface ExportHandler {
+    String type();
+    byte[] export(String payload);
+}
+
+// CSV 实现
+class CsvExportHandler implements ExportHandler {
+    @Override
+    public String type() {
+        return "CSV";
+    }
+
+    @Override
+    public byte[] export(String payload) {
+        return ("csv," + payload).getBytes();
+    }
+}
+
+// PDF 实现
+class PdfExportHandler implements ExportHandler {
+    @Override
+    public String type() {
+        return "PDF";
+    }
+
+    @Override
+    public byte[] export(String payload) {
+        return ("pdf," + payload).getBytes();
+    }
+}
+
+// 工厂：负责按类型分发实现，调用方无需 new 具体类
+class ExportHandlerFactory {
+
+    private final Map<String, ExportHandler> handlerMap;
+
+    ExportHandlerFactory(Map<String, ExportHandler> handlerMap) {
+        this.handlerMap = handlerMap;
+    }
+
+    public ExportHandler resolve(String type) {
+        ExportHandler handler = handlerMap.get(type);
+        if (Objects.isNull(handler)) {
+            throw new IllegalArgumentException("不支持的导出类型: " + type);
+        }
+        return handler;
+    }
+}
+
+class FactoryDemo {
+    public static void main(String[] args) {
+        ExportHandlerFactory factory = new ExportHandlerFactory(Map.of(
+                "CSV", new CsvExportHandler(),
+                "PDF", new PdfExportHandler()
+        ));
+
+        // 调用方只给类型，工厂返回实现
+        byte[] bytes = factory.resolve("CSV").export("orderNo=SO-1001");
+        System.out.println(new String(bytes));
+    }
+}
+```
+
+## 5. Chain Of Responsibility（责任链）
+### 5.1 场景
+1. 多步骤校验/过滤，任一步失败就短路。
+2. 节点可插拔，顺序可组合。
+
+### 5.2 完整示例
+```java
+import java.util.Objects;
+
+// 提交参数
+record SubmitReq(String operator, String orderNo, boolean hasPermission) {}
+
+// 校验结果对象
+record CheckResult(boolean passed, String message) {
+    static CheckResult pass() { return new CheckResult(true, "OK"); }
+    static CheckResult fail(String msg) { return new CheckResult(false, msg); }
+}
+
+// 抽象责任链节点
+abstract class AbstractCheckHandler {
+
+    private AbstractCheckHandler next;
+
+    // 组装链：返回 next 便于链式调用
+    public AbstractCheckHandler next(AbstractCheckHandler nextHandler) {
+        this.next = nextHandler;
+        return nextHandler;
+    }
+
+    // 固定执行流程：先校验自己，通过后再走下一个
+    public final CheckResult handle(SubmitReq req) {
+        CheckResult result = doCheck(req);
+        if (!result.passed()) {
+            return result;
+        }
+        return Objects.isNull(next) ? CheckResult.pass() : next.handle(req);
+    }
+
+    // 子类仅实现当前节点规则
+    protected abstract CheckResult doCheck(SubmitReq req);
+}
+
+// 必填校验节点
+class RequiredFieldHandler extends AbstractCheckHandler {
+    @Override
+    protected CheckResult doCheck(SubmitReq req) {
+        if (Objects.isNull(req.orderNo()) || req.orderNo().isBlank()) {
+            return CheckResult.fail("单号不能为空");
+        }
+        return CheckResult.pass();
+    }
+}
+
+// 权限校验节点
+class PermissionHandler extends AbstractCheckHandler {
+    @Override
+    protected CheckResult doCheck(SubmitReq req) {
+        return req.hasPermission() ? CheckResult.pass() : CheckResult.fail("无提交权限");
+    }
+}
+
+class ChainDemo {
+    public static void main(String[] args) {
+        AbstractCheckHandler head = new RequiredFieldHandler();
+        head.next(new PermissionHandler());
+
+        CheckResult ok = head.handle(new SubmitReq("u1", "SO-1001", true));
+        CheckResult fail = head.handle(new SubmitReq("u2", "", true));
+        System.out.println(ok.message());
+        System.out.println(fail.message());
+    }
+}
+```
+
+## 6. Template Method（模板方法）
+### 6.1 场景
+1. 主流程固定，局部步骤允许差异化实现。
+2. 需要统一前置校验、主执行、后置处理。
+
+### 6.2 完整示例
+```java
+import java.time.LocalDateTime;
+
+// 提交命令
+record SubmitCmd(String orderNo, String operator) {}
+
+// 模板抽象类
+abstract class AbstractOrderSubmitTemplate {
+
+    // 模板方法：流程骨架固定，禁止子类改顺序
+    public final void submit(SubmitCmd cmd) {
+        validate(cmd);
+        preProcess(cmd);
+        doSubmit(cmd);
+        postProcess(cmd);
+    }
+
+    // 默认校验逻辑，可被子类增强
+    protected void validate(SubmitCmd cmd) {
+        if (cmd.orderNo() == null || cmd.orderNo().isBlank()) {
+            throw new IllegalArgumentException("单号不能为空");
+        }
+    }
+
+    // 默认前置处理
+    protected void preProcess(SubmitCmd cmd) {
+        System.out.println("前置处理: " + cmd.orderNo());
+    }
+
+    // 核心业务步骤，必须由子类实现
+    protected abstract void doSubmit(SubmitCmd cmd);
+
+    // 默认后置处理
+    protected void postProcess(SubmitCmd cmd) {
+        System.out.println("后置处理: " + LocalDateTime.now());
+    }
+}
+
+// 具体模板实现
+class PurchaseOrderSubmitTemplate extends AbstractOrderSubmitTemplate {
+    @Override
+    protected void doSubmit(SubmitCmd cmd) {
+        System.out.println("提交采购单: " + cmd.orderNo() + ", operator=" + cmd.operator());
+    }
+}
+
+class TemplateDemo {
+    public static void main(String[] args) {
+        AbstractOrderSubmitTemplate template = new PurchaseOrderSubmitTemplate();
+        template.submit(new SubmitCmd("PO-2001", "zhangsan"));
+    }
+}
+```
+
+## 7. Singleton（单例）
+### 7.1 场景
+1. 纯工具对象、全局唯一实例。
+2. 要求懒加载且线程安全。
+
+### 7.2 完整示例
+```java
+public final class BizSequenceGenerator {
+
+    // 可变状态由 synchronized 方法保护
+    private long seq = 0L;
+
+    // 私有构造，禁止外部 new
+    private BizSequenceGenerator() {}
+
+    // 静态内部类：JVM 保证延迟加载与线程安全
+    private static class Holder {
+        private static final BizSequenceGenerator INSTANCE = new BizSequenceGenerator();
+    }
+
+    public static BizSequenceGenerator getInstance() {
+        return Holder.INSTANCE;
+    }
+
+    public synchronized long next() {
+        return ++seq;
+    }
+
+    public static void main(String[] args) {
+        BizSequenceGenerator generator = BizSequenceGenerator.getInstance();
+        System.out.println(generator.next());
+        System.out.println(generator.next());
+    }
+}
+```
+
+## 8. 评审清单（模式维度）
+1. 是否真正消除了主流程中的硬编码分支。
+2. 新增实现类时是否无需修改核心流程。
+3. 是否定义了默认实现和异常分支。
+4. 是否保持“接口小、实现清晰、调用简单”。
+5. 是否避免了无意义抽象层和空实现。

package/tests/skill.test.ts

@@ -0,0 +1,191 @@
+import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { addSkill, initSkills, listSkills } from "../src/skill-core/service.js";
+
+async function seedSkillRepo(): Promise<string> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-skill-"));
+  const skillDir = path.join(root, ".codex", "demo-skill");
+  await mkdir(path.join(skillDir, "agents"), { recursive: true });
+  await mkdir(path.join(skillDir, "references"), { recursive: true });
+
+  await writeFile(
+    path.join(skillDir, "SKILL.md"),
+    [
+      "---",
+      "name: demo-skill",
+      "description: demo description",
+      "---",
+      "",
+      "# Demo Skill",
+      "",
+      "body"
+    ].join("\n"),
+    "utf8"
+  );
+  await writeFile(path.join(skillDir, "agents", "openai.yaml"), "x: 1\n", "utf8");
+  await writeFile(path.join(skillDir, "references", "readme.md"), "ref\n", "utf8");
+  return root;
+}
+
+describe("skill service", () => {
+  it("lists valid skills", async () => {
+    const root = await seedSkillRepo();
+    const names = await listSkills(root);
+    expect(names).toEqual(["demo-skill"]);
+  });
+
+  it("exports skill to all targets", async () => {
+    const root = await seedSkillRepo();
+    await addSkill(root, "demo-skill", "all", false);
+
+    const codexSkill = await readFile(
+      path.join(root, ".codex", "skills", "demo-skill", "SKILL.md"),
+      "utf8"
+    );
+    const claudecodeMeta = await readFile(
+      path.join(root, ".claude", "skills", "demo-skill", "claudecode.skill.json"),
+      "utf8"
+    );
+    const iflowMeta = await readFile(
+      path.join(root, ".iflow", "skills", "demo-skill", "iflow.skill.yaml"),
+      "utf8"
+    );
+
+    expect(codexSkill).toContain("name: demo-skill");
+    expect(claudecodeMeta).toContain('"name": "demo-skill"');
+    expect(iflowMeta).toContain('name: "demo-skill"');
+  });
+
+  it("rejects conflict without force", async () => {
+    const root = await seedSkillRepo();
+    await addSkill(root, "demo-skill", "codex", false);
+    await expect(addSkill(root, "demo-skill", "codex", false)).rejects.toThrow(
+      /Use --force/
+    );
+  });
+
+  it("supports ifow alias", async () => {
+    const root = await seedSkillRepo();
+    await addSkill(root, "demo-skill", "ifow", false);
+    const iflowMeta = await readFile(
+      path.join(root, ".iflow", "skills", "demo-skill", "iflow.skill.yaml"),
+      "utf8"
+    );
+    expect(iflowMeta).toContain('entry: "prompt.md"');
+  });
+
+  it("generates agent config files on init", async () => {
+    const root = await seedSkillRepo();
+    const files = await initSkills(root, "codex,ifow", false);
+    expect(files.some((file) => file.endsWith(path.join(".codex", "AGENTS.md")))).toBe(true);
+    expect(files.some((file) => file.endsWith(path.join(".iflow", "IFLOW.md")))).toBe(true);
+    expect(files.some((file) => file.endsWith(path.join("AGENTS.md")))).toBe(true);
+
+    const agents = await readFile(path.join(root, ".codex", "AGENTS.md"), "utf8");
+    const iflow = await readFile(path.join(root, ".iflow", "IFLOW.md"), "utf8");
+    expect(agents).toContain("demo-skill");
+    expect(iflow).toContain("/cd-demo-skill -> demo-skill");
+    const command = await readFile(path.join(root, ".codex", "prompts", "cd-demo-skill.md"), "utf8");
+    expect(command).toContain("skill: demo-skill");
+  });
+
+  it("creates default skill when .codex is empty", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-empty-"));
+    const files = await initSkills(root, "codex", false);
+    expect(files.some((file) => file.endsWith(path.join(".codex", "AGENTS.md")))).toBe(true);
+    expect(files.some((file) => file.endsWith(path.join("AGENTS.md")))).toBe(true);
+    const exported = await readFile(
+      path.join(root, ".codex", "skills", "openspec-core", "SKILL.md"),
+      "utf8"
+    );
+    await expect(readFile(path.join(root, ".cdspec", "seed-skills", "openspec-core", "SKILL.md"), "utf8")).rejects.toThrow();
+    await expect(readFile(path.join(root, ".codex", "openspec-core", "SKILL.md"), "utf8")).rejects.toThrow();
+    expect(exported).toContain("OpenSpec Core Skill");
+  });
+
+  it("supports configurable agent output paths", async () => {
+    const root = await seedSkillRepo();
+    await writeFile(
+      path.join(root, "cdspec.config.yaml"),
+      [
+        "commandBindings:",
+        "  - id: plan",
+        "    skill: demo-skill",
+        "    description: Plan workflow",
+        "agents:",
+        "  codex:",
+        "    rootDir: .codex",
+        "    commandsDir: prompts",
+        "    commandFilePattern: custom-{id}.md",
+        "    slashPattern: /custom-{id}",
+        "    guideFile: AGENTS.md",
+        "  claudecode:",
+        "    rootDir: .claude",
+        "    commandsDir: commands/opsx",
+        "    commandFilePattern: \"{id}.md\"",
+        "    slashPattern: /opsx:{id}",
+        "    guideFile: CLAUDE.md",
+        "    guideAtProjectRoot: true",
+        "  iflow:",
+        "    rootDir: .iflow",
+        "    commandsDir: commands",
+        "    commandFilePattern: opsx-{id}.md",
+        "    slashPattern: /opsx-{id}",
+        "    guideFile: IFLOW.md"
+      ].join("\n"),
+      "utf8"
+    );
+
+    await addSkill(root, "demo-skill", "codex", false);
+    const exported = await readFile(path.join(root, ".codex", "skills", "demo-skill", "SKILL.md"), "utf8");
+    expect(exported).toContain("name: demo-skill");
+  });
+
+  it("binds commands to template-derived skill when no .codex skills exist", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-template-bind-"));
+    await mkdir(path.join(root, "templates"), { recursive: true });
+    await writeFile(
+      path.join(root, "templates", "frontend_develop_standard.md"),
+      "# Frontend Develop Standard\n\nTemplate body",
+      "utf8"
+    );
+    await initSkills(root, "codex", false);
+
+    const exported = await readFile(
+      path.join(root, ".codex", "skills", "frontend-develop-standard", "SKILL.md"),
+      "utf8"
+    );
+    expect(exported).toContain("name: frontend-develop-standard");
+
+    const prompt = await readFile(path.join(root, ".codex", "prompts", "cd-frontend-develop-standard.md"), "utf8");
+    expect(prompt).toContain("skill: frontend-develop-standard");
+  });
+
+  it("prioritizes templates over existing .codex skills for init binding", async () => {
+    const root = await seedSkillRepo();
+    await mkdir(path.join(root, "templates"), { recursive: true });
+    await writeFile(path.join(root, "templates", "my_template.md"), "# My Template\n", "utf8");
+
+    await initSkills(root, "codex", true);
+    const prompt = await readFile(path.join(root, ".codex", "prompts", "cd-my-template.md"), "utf8");
+    expect(prompt).toContain("skill: my-template");
+    const exported = await readFile(path.join(root, ".codex", "skills", "my-template", "SKILL.md"), "utf8");
+    expect(exported).toContain("name: my-template");
+  });
+
+  it("uses full skill name for command ids", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-fullname-"));
+    await mkdir(path.join(root, "templates", "design-doc", "agents"), { recursive: true });
+    await writeFile(
+      path.join(root, "templates", "design-doc", "SKILL.md"),
+      ["---", "name: design-doc", "description: d", "---", "", "# d"].join("\n"),
+      "utf8"
+    );
+    await writeFile(path.join(root, "templates", "design-doc", "agents", "openai.yaml"), "x: 1\n");
+    await initSkills(root, "codex", false);
+    const prompt = await readFile(path.join(root, ".codex", "prompts", "cd-design-doc.md"), "utf8");
+    expect(prompt).toContain("skill: design-doc");
+  });
+});

package/tests/task.test.ts

@@ -0,0 +1,55 @@
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { archiveTaskById, splitTasks, updateTask } from "../src/task-core/service.js";
+import { loadTask } from "../src/task-core/storage.js";
+
+describe("task workflow", () => {
+  it("splits markdown into tasks and creates index", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-task-"));
+    const source = path.join(root, "input.md");
+    await writeFile(
+      source,
+      ["# Feature", "", "## Backend", "- API schema", "## Frontend", "- Build page"].join(
+        "\n"
+      ),
+      "utf8"
+    );
+
+    const count = await splitTasks(root, "input.md", "Root Task");
+    expect(count).toBe(2);
+
+    const index = await readFile(path.join(root, ".cdspec", "tasks", "index.md"), "utf8");
+    expect(index).toContain("## todo");
+  });
+
+  it("enforces status transitions and archive done tasks", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-task-"));
+    const source = path.join(root, "plan.md");
+    await writeFile(source, "- one\n", "utf8");
+    await splitTasks(root, "plan.md", "Task Plan");
+
+    const ids = await extractTaskIds(root);
+    const id = ids[0];
+
+    await expect(archiveTaskById(root, id)).rejects.toThrow(/must be done/);
+
+    await expect(updateTask(root, id, "done")).rejects.toThrow(/Invalid status transition/);
+    await updateTask(root, id, "in_progress");
+    await updateTask(root, id, "done");
+    await archiveTaskById(root, id);
+
+    const task = await loadTask(root, id);
+    expect(task).toBeNull();
+    const archive = await readFile(path.join(root, ".cdspec", "archive", `${id}.md`), "utf8");
+    expect(archive).toContain("archived_at");
+  });
+});
+
+async function extractTaskIds(root: string): Promise<string[]> {
+  const index = await readFile(path.join(root, ".cdspec", "tasks", "index.md"), "utf8");
+  const ids = [...index.matchAll(/\[([a-f0-9]{10})\]/g)].map((match) => match[1]);
+  return ids;
+}
+

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["tests/**/*.test.ts"]
+  }
+});
+