autocrew 0.3.4 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autocrew",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "One-person content studio powered by AI — from trending topics to published posts",
   "type": "module",
   "license": "MIT",

package/src/cli/commands/versions.ts

@@ -14,11 +14,14 @@ export const cmd: CommandDef = {
 
     // Try pipeline project first (draft versions from meta.yaml)
     try {
-      const pipelineResult = await runner.execute("autocrew_pipeline_ops", {
-        action: "status",
-      });
-      // Search for project in pipeline stages
-      const { getProjectMeta } = await import("../../storage/pipeline-store.js");
+      const { getProjectMeta, syncUntrackedChanges } = await import("../../storage/pipeline-store.js");
+
+      // Auto-detect manual edits to draft.md before reading versions
+      const syncResult = await syncUntrackedChanges(id);
+      if (syncResult.synced) {
+        console.log(`  (detected external edit: ${syncResult.reason})`);
+      }
+
       const meta = await getProjectMeta(id);
       if (meta) {
         console.log(`Draft versions for "${meta.title}":`);

package/src/e2e.test.ts

@@ -181,6 +181,49 @@ describe("E2E: Topic Management", () => {
   });
 });
 
+describe("E2E: Draft Action (content generation)", () => {
+  it("draft returns writing context and instructions for a topic", async () => {
+    const result = await runner.execute("autocrew_content", {
+      action: "draft",
+      topic_title: "vibe-coding 实践者的真实工作流",
+      platform: "xiaohongshu",
+    });
+    expect(result.ok).toBe(true);
+    expect(result.action).toBe("draft");
+
+    // Should return topic info
+    expect((result.topic as any).title).toBe("vibe-coding 实践者的真实工作流");
+    expect((result.topic as any).platform).toBe("xiaohongshu");
+
+    // Should return creator context
+    expect(result.creatorContext).toBeDefined();
+
+    // Should return writing instructions with Operating System principles
+    const instructions = result.writingInstructions as string;
+    expect(instructions).toContain("EMPATHY FIRST");
+    expect(instructions).toContain("THEIR WORDS, NOT YOURS");
+    expect(instructions).toContain("SHOW THE MOVIE");
+    expect(instructions).toContain("TENSION IS OXYGEN");
+    expect(instructions).toContain("THE CREATOR IS THE PROOF");
+    expect(instructions).toContain("TWO-PHASE CREATION");
+    expect(instructions).toContain("PHASE A");
+    expect(instructions).toContain("PHASE B");
+
+    // Should return next action guidance
+    expect((result.nextAction as any).tool).toBe("autocrew_content");
+    expect((result.nextAction as any).action).toBe("save");
+  });
+
+  it("draft fails without topic_title", async () => {
+    const result = await runner.execute("autocrew_content", {
+      action: "draft",
+      platform: "xiaohongshu",
+    });
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("topic_title");
+  });
+});
+
 describe("E2E: Topic → Start → Content (cross-system)", () => {
   it("topic created via autocrew_topic can be started via pipeline_ops", async () => {
     // Create topic via local-store (autocrew_topic)

package/src/storage/pipeline-store.test.ts

@@ -30,6 +30,7 @@ import {
   listWikiPages,
   regenerateWikiIndex,
   appendWikiLog,
+  syncUntrackedChanges,
   type IntelItem,
   type TopicCandidate,
   type WikiPage,
@@ -471,3 +472,66 @@ describe("Wiki Storage", () => {
     expect(lines[1]).toContain("[update]");
   });
 });
+
+// ─── Untracked Changes Detection ────────────────────────────────────────────
+
+describe("syncUntrackedChanges", () => {
+  it("detects manually edited draft.md and registers version", async () => {
+    await saveTopic(makeTopic({ title: "手动编辑测试" }), testDir);
+    await startProject("手动编辑测试", testDir);
+
+    const projectName = slugify("手动编辑测试");
+    const projectDir = path.join(stagePath("drafting", testDir), projectName);
+
+    // Simulate a manual edit: write new content to draft.md directly
+    // Wait >1s so mtime exceeds the 1-second detection threshold
+    await new Promise((r) => setTimeout(r, 1200));
+    await fs.writeFile(
+      path.join(projectDir, "draft.md"),
+      "# 手动编辑测试\n\n这是手动编辑的内容，不是通过 autocrew 工具写入的。包含足够长的文本来触发版本检测。",
+      "utf-8",
+    );
+
+    // Sync should detect the change
+    const result = await syncUntrackedChanges(projectName, testDir);
+    expect(result.synced).toBe(true);
+    expect(result.reason).toContain("external edit");
+
+    // Meta should now have a version entry
+    const meta = await getProjectMeta(projectName, testDir);
+    expect(meta!.versions.length).toBe(1);
+    expect(meta!.versions[0].note).toBe("detected external edit");
+  });
+
+  it("creates meta.yaml when only draft.md exists", async () => {
+    await initPipeline(testDir);
+    const projectDir = path.join(stagePath("drafting", testDir), "orphan-project");
+    await fs.mkdir(projectDir, { recursive: true });
+
+    // Write draft.md without meta.yaml (simulates manual file copy)
+    await fs.writeFile(
+      path.join(projectDir, "draft.md"),
+      "# 孤儿项目\n\n这个项目的 draft.md 是手动复制进来的，没有 meta.yaml。",
+      "utf-8",
+    );
+
+    const result = await syncUntrackedChanges("orphan-project", testDir);
+    expect(result.synced).toBe(true);
+    expect(result.reason).toContain("meta.yaml created");
+
+    // meta.yaml should now exist
+    const meta = await getProjectMeta("orphan-project", testDir);
+    expect(meta).not.toBeNull();
+    expect(meta!.title).toBe("孤儿项目");
+  });
+
+  it("skips when draft.md has not changed", async () => {
+    await saveTopic(makeTopic({ title: "无变更测试" }), testDir);
+    await startProject("无变更测试", testDir);
+
+    const projectName = slugify("无变更测试");
+    const result = await syncUntrackedChanges(projectName, testDir);
+    expect(result.synced).toBe(false);
+    expect(result.reason).toContain("up to date");
+  });
+});

package/src/storage/pipeline-store.ts

@@ -948,6 +948,106 @@ export async function getProjectMeta(
   return readMeta(found.dir);
 }
 
+/**
+ * Detect if draft.md has been modified outside of AutoCrew tools
+ * (e.g., manually edited, copied in). If so, auto-register the change
+ * into meta.yaml so version tracking stays accurate.
+ *
+ * Returns true if an untracked change was detected and registered.
+ */
+export async function syncUntrackedChanges(
+  name: string,
+  dataDir?: string,
+): Promise<{ synced: boolean; reason?: string }> {
+  const found = await findProject(name, dataDir);
+  if (!found) return { synced: false, reason: "project not found" };
+
+  const draftPath = path.join(found.dir, "draft.md");
+  const metaPath = path.join(found.dir, "meta.yaml");
+
+  // Check if draft.md exists
+  let draftStat;
+  try {
+    draftStat = await fs.stat(draftPath);
+  } catch {
+    return { synced: false, reason: "draft.md not found" };
+  }
+
+  // Check if meta.yaml exists — if not, create one from draft.md
+  let meta: ProjectMeta;
+  try {
+    meta = await readMeta(found.dir);
+  } catch {
+    // meta.yaml missing — create from scratch based on draft.md
+    const draftContent = await fs.readFile(draftPath, "utf-8");
+    const titleMatch = draftContent.match(/^#\s+(.+)/m);
+    const now = new Date().toISOString();
+    meta = {
+      title: titleMatch?.[1]?.trim() || name,
+      domain: "",
+      format: "article",
+      createdAt: now,
+      sourceTopic: "",
+      intelRefs: [],
+      versions: [],
+      current: "draft.md",
+      history: [{ stage: found.stage, entered: now }],
+      platforms: [],
+    };
+    await writeMeta(found.dir, meta);
+    return { synced: true, reason: "meta.yaml created from existing draft.md" };
+  }
+
+  // Compare draft.md mtime against meta.yaml's updatedAt or last version timestamp
+  const draftMtime = draftStat.mtime;
+  const lastKnownTime = meta.versions.length > 0
+    ? new Date(meta.versions[meta.versions.length - 1].createdAt)
+    : meta.createdAt
+      ? new Date(meta.createdAt)
+      : new Date(0);
+
+  // If draft.md is newer than the last tracked version by more than 5 seconds,
+  // there was an untracked edit
+  if (draftMtime.getTime() - lastKnownTime.getTime() > 1000) {
+    // Read current draft content and register as a new version
+    const draftContent = await fs.readFile(draftPath, "utf-8");
+
+    // Only register if draft has substantial content
+    if (draftContent.trim().length < 10) {
+      return { synced: false, reason: "draft.md is too short to register" };
+    }
+
+    // Archive the current state if there's something to archive
+    const versionNum = meta.versions.length + 1;
+    const archiveFilename = `draft-v${versionNum}.md`;
+
+    // If this is the first version and draft has content, just register it
+    // (no need to archive — there's nothing to archive from)
+    if (meta.versions.length > 0) {
+      // There's existing version history — this is a new edit on top
+      // Archive current to draft-vN.md before we record the new state
+      // (but we don't overwrite draft.md — the user already wrote it)
+      await fs.writeFile(
+        path.join(found.dir, archiveFilename),
+        draftContent,
+        "utf-8",
+      );
+    }
+
+    meta.versions.push({
+      file: meta.versions.length > 0 ? archiveFilename : "draft.md",
+      createdAt: draftMtime.toISOString(),
+      note: "detected external edit",
+    });
+    meta.current = "draft.md";
+    await writeMeta(found.dir, meta);
+
+    return { synced: true, reason: `registered external edit as version ${versionNum}` };
+  }
+
+  return { synced: false, reason: "draft.md is up to date with meta.yaml" };
+}
+
 export async function listProjects(
   stage: PipelineStage,
   dataDir?: string,

package/src/tools/content-save.ts

@@ -31,14 +31,17 @@ const ALL_STATUSES = [
 ] as const;
 
 export const contentSaveSchema = Type.Object({
-  action: Type.Unsafe<"save" | "list" | "get" | "update" | "transition" | "create_variant" | "siblings" | "allowed_transitions">({
+  action: Type.Unsafe<"save" | "list" | "get" | "update" | "transition" | "create_variant" | "siblings" | "allowed_transitions" | "draft">({
     type: "string",
-    enum: ["save", "list", "get", "update", "transition", "create_variant", "siblings", "allowed_transitions"],
+    enum: ["save", "list", "get", "update", "transition", "create_variant", "siblings", "allowed_transitions", "draft"],
     description:
-      "Action: 'save' new content, 'list' all, 'get' by id, 'update' existing, " +
-      "'transition' change status via state machine, 'create_variant' create platform variant from topic, " +
-      "'siblings' list sibling content, 'allowed_transitions' show valid next statuses.",
+      "Action: 'draft' GENERATE a content draft (provide topic_title + platform, returns writing context + instructions), " +
+      "'save' persist content, 'list' all, 'get' by id, 'update' existing, " +
+      "'transition' change status, 'create_variant' platform variant, " +
+      "'siblings' list siblings, 'allowed_transitions' valid next statuses.",
   }),
+  topic_title: Type.Optional(Type.String({ description: "Topic title for draft action — what to write about" })),
+  topic_description: Type.Optional(Type.String({ description: "Topic description/angle for draft action" })),
   id: Type.Optional(Type.String({ description: "Content id (for get/update/transition/siblings/allowed_transitions)" })),
   title: Type.Optional(Type.String({ description: "Content title" })),
   body: Type.Optional(Type.String({ description: "Content body (markdown)" })),
@@ -78,20 +81,137 @@ export const contentSaveSchema = Type.Object({
   )),
 });
 
+async function executeDraft(params: Record<string, unknown>) {
+  const dataDir = (params._dataDir as string) || undefined;
+  const topicTitle = (params.topic_title as string) || (params.title as string) || "";
+  const topicDescription = (params.topic_description as string) || "";
+  const platform = (params.platform as string) || "xiaohongshu";
+
+  if (!topicTitle) {
+    return { ok: false, error: "topic_title is required for draft action. What should the content be about?" };
+  }
+
+  const effectiveDataDir = dataDir || path.join(process.env.HOME ?? "~", ".autocrew");
+
+  // Load creator context
+  let style = "";
+  let profile: Record<string, unknown> = {};
+  let methodology = "";
+
+  try {
+    style = await fs.readFile(path.join(effectiveDataDir, "STYLE.md"), "utf-8");
+  } catch { /* no style file */ }
+
+  try {
+    const raw = await fs.readFile(path.join(effectiveDataDir, "creator-profile.json"), "utf-8");
+    profile = JSON.parse(raw);
+  } catch { /* no profile */ }
+
+  try {
+    // Load HAMLETDEER methodology summary (not the full 562 lines — key principles only)
+    const full = await fs.readFile(path.join(effectiveDataDir, "..", "AutoCrew", "HAMLETDEER.md"), "utf-8");
+    // Extract the HKRR + Clock Theory sections
+    const hkrrMatch = full.match(/### The HKRR Framework[\s\S]*?(?=###\s|---)/);
+    const clockMatch = full.match(/### The Clock Theory[\s\S]*?(?=###\s|---)/);
+    methodology = [hkrrMatch?.[0] || "", clockMatch?.[0] || ""].filter(Boolean).join("\n\n");
+  } catch {
+    // HAMLETDEER not found at expected path — use embedded summary
+    methodology = `HKRR Framework: H(Happiness), K(Knowledge), R(Resonance), R(Rhythm). Short-form: pick ONE. Long-form: combine all.
+Clock Theory: Bang moments at 12:00(hook), 3:00(escalation), 6:00(payload), 9:00(climax). Every position must have energy.`;
+  }
+
+  // Load wiki knowledge if available
+  let wikiContext = "";
+  try {
+    const { listWikiPages, slugify: wikiSlugify } = await import("../storage/pipeline-store.js");
+    const pages = await listWikiPages(dataDir);
+    const relevant = pages.filter((p) =>
+      topicTitle.toLowerCase().includes(p.title.toLowerCase()) ||
+      p.aliases.some((a) => topicTitle.toLowerCase().includes(a.toLowerCase())),
+    );
+    if (relevant.length > 0) {
+      wikiContext = relevant.map((p) => `## Wiki: ${p.title}\n${p.body}`).join("\n\n");
+    }
+  } catch { /* wiki not available */ }
+
+  return {
+    ok: true,
+    action: "draft",
+    topic: { title: topicTitle, description: topicDescription, platform },
+    creatorContext: {
+      industry: profile.industry || "",
+      platforms: profile.platforms || [],
+      expressionPersona: profile.expressionPersona || "",
+      styleBoundaries: profile.styleBoundaries || { never: [], always: [] },
+      audiencePersona: profile.audiencePersona || null,
+    },
+    style: style || "(no style file — write in natural conversational Chinese)",
+    methodology,
+    wikiContext: wikiContext || "(no wiki knowledge available yet)",
+    writingInstructions: `
+You are now writing a content draft for Chinese social media. Follow these instructions EXACTLY.
+
+## THE OPERATING SYSTEM — 5 Principles (override everything else)
+
+1. EMPATHY FIRST — You are sitting across from ONE person (the audiencePersona). They are scrolling, half-distracted. Every sentence must earn their next 3 seconds. If a sentence triggers no curiosity, recognition, surprise, or relief — delete it.
+
+2. THEIR WORDS, NOT YOURS — Every word must pass: would the reader say this to a friend over coffee? If no, replace it. No jargon, no abstractions, no "smart" words the reader wouldn't use.
+
+3. SHOW THE MOVIE — Abstractions are invisible. Stories are visible. Every claim needs a scene: a face, a number, a moment. "She built a product in 3 weeks, alone" > "AI improves efficiency."
+
+4. TENSION IS OXYGEN — Every paragraph must either OPEN a question or CLOSE one. No paragraph should just "sit there" as information. When energy drops, inject a question, contradiction, or surprise.
+
+5. THE CREATOR IS THE PROOF — The creator's own experience is the strongest evidence. Lead with "I did X" before "Company Y did Z." Vulnerability > authority.
+
+## TWO-PHASE CREATION
+
+PHASE A — Build the skeleton FIRST (do not write prose yet):
+- A1: Core thesis in ONE sentence (an opinion, not a topic)
+- A2: Argument structure (thesis → evidence → twist → action)
+- A3: Clock Theory — plan 4 bang moments (12:00 hook, 3:00 escalation, 6:00 payload, 9:00 climax)
+- A4: HKRR — choose dominant dimension
+- A5: Place 2-3 micro-retention techniques
+
+Present the skeleton to the user. Wait for confirmation. Then:
+
+PHASE B — Write the full draft based on the skeleton.
+- Fear short, not long. Every case study deserves full detail.
+- After each clock section, simulate the reader's reaction.
+- Ground every factual claim in real sources.
+
+## AFTER WRITING
+
+Call autocrew_content action="save" with the full body text, title, platform, and hypothesis.
+Do NOT use the Write tool to create draft.md directly.
+`,
+    nextAction: {
+      tool: "autocrew_content",
+      action: "save",
+      description: "After generating the draft, save it with action='save' providing title, body, platform, hypothesis.",
+    },
+  };
+}
+
 export async function executeContentSave(params: Record<string, unknown>) {
   const action = (params.action as string) || "save";
   const dataDir = (params._dataDir as string) || undefined;
 
+  if (action === "draft") {
+    return executeDraft(params);
+  }
+
   if (action === "list") {
     const contents = await listContents(dataDir);
 
     // Also list pipeline drafting projects (these may not exist in legacy contents/)
     const pipelineProjects: Array<{ slug: string; title: string; stage: string; current: string }> = [];
     try {
-      const { listProjects, getProjectMeta, stagePath } = await import("../storage/pipeline-store.js");
+      const { listProjects, getProjectMeta, syncUntrackedChanges } = await import("../storage/pipeline-store.js");
       for (const stage of ["drafting", "production", "published"] as const) {
         const slugs = await listProjects(stage, dataDir);
         for (const slug of slugs) {
+          // Auto-detect manual edits before reading meta
+          try { await syncUntrackedChanges(slug, dataDir); } catch { /* ignore */ }
           const meta = await getProjectMeta(slug, dataDir);
           if (meta) {
             pipelineProjects.push({

package/src/tools/registry.ts

@@ -47,11 +47,11 @@ export function registerAllTools(runner: ToolRunner): void {
     name: "autocrew_content",
     label: "AutoCrew Content",
     description:
-      "Content creation and lifecycle management. THIS IS THE PRIMARY CONTENT CREATION TOOL. " +
-      "To create content: use action='save' with title and body (the full draft text). " +
-      "The tool handles pipeline project creation, version tracking, and auto-humanization. " +
-      "Workflow: 1) Research with autocrew_intel, 2) Write the full draft body, " +
-      "3) Save with autocrew_content action='save' (title, body, platform, hypothesis, tags). " +
+      "Content creation and lifecycle management. " +
+      "CONTENT CREATION WORKFLOW: " +
+      "Step 1: action='draft' with topic_title + platform → returns creator style, methodology, writing instructions, and wiki knowledge. " +
+      "Step 2: Generate the draft body following the returned instructions (two-phase: skeleton first, then prose). " +
+      "Step 3: action='save' with title + body + platform + hypothesis → persists to pipeline with version tracking + auto-humanization. " +
       "Other actions: list, get, update, transition, create_variant, siblings, allowed_transitions.",
     parameters: contentSaveSchema,
     execute: executeContentSave,