aitable-workflow-cli 0.1.28 → 0.1.29-beta.1790736949347

package/templates/ai-native-sdlc/lib/artifacts.ts

@@ -0,0 +1,126 @@
+/**
+ * 变更工件的路径与命名只在这里定义一次。
+ * 各阶段 recipe 通过这些函数拼装 prompt 指引、产出物标注与 CR 描述，
+ * 需要调整产物名称或目录结构时只改本文件。
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export type ArtifactStage = "prd" | "spec" | "coding" | "review";
+
+const ARTIFACT_FILES: Record<ArtifactStage, string> = {
+  prd: "01-prd.md",
+  spec: "02-spec.md",
+  coding: "03-coding.md",
+  review: "04-review.md",
+};
+
+/** 变更工件的登记表，键为工件文件名。 */
+export type ArtifactManifest = Record<string, { summary: string }>;
+
+const MANIFEST_FILE = ".artifacts.json";
+
+/** Agent 未自写概要时的兜底登记，避免工件存在却漏登记。 */
+const ARTIFACT_SUMMARIES: Record<ArtifactStage, string> = {
+  prd: "PRD：需求、验收标准与依赖，供 Dev 制定实施计划",
+  spec: "技术方案：选中/未选中仓库及理由、改动文件、风险与测试命令",
+  coding: "编码工件：各仓库改动、真实测试命令与输出、CI 证据",
+  review: "评审结论：真实测试与 CI 证据、CR 评论处理结果",
+};
+
+/** 变更工件目录相对仓库根，如 `changes/CHG-xxx`。 */
+export function changeDir(id: string): string {
+  return `changes/${id}`;
+}
+
+/** 阶段工件文件名，如 `01-prd.md`；用于「产出物」标注。 */
+export function artifactName(stage: ArtifactStage): string {
+  return ARTIFACT_FILES[stage];
+}
+
+/** 阶段工件相对仓库根的路径，如 `changes/CHG-xxx/01-prd.md`；用于 prompt 指引与 CR 描述。 */
+export function artifactPath(stage: ArtifactStage, id: string): string {
+  return `${changeDir(id)}/${ARTIFACT_FILES[stage]}`;
+}
+
+/** 阶段工件在某 worktree 内的绝对路径，如 `<worktree>/changes/CHG-xxx/01-prd.md`。 */
+export function artifactAbsPath(
+  stage: ArtifactStage,
+  worktreeDir: string,
+  id: string,
+): string {
+  return `${worktreeDir}/${artifactPath(stage, id)}`;
+}
+
+/**
+ * git.ensureWorktree 返回的 dir 自 2026-09-24 路径归一重构后是「项目根相对路径」
+ * （见 packages/core/src/toolkit/git/git-adapter.ts 的 relativeDir，为跨机器可移植而设计）。
+ * 裸 fs 读写按 process.cwd() 解析（≠ 项目根），coding agent 的 cwd 是角色工作区（也≠ 项目根），
+ * 两者都需要真实绝对路径才能命中同一份文件；`git.*` / `coding.run` toolkit 自己会按项目根
+ * 再解析一次，不需要这层转换，只有直接拼路径的场景（fs 读写 + prompt 文本）必须先用本函数换算。
+ */
+export function resolveWorktreeDir(configDir: string, dir: string): string {
+  return path.resolve(configDir, dir);
+}
+
+/** manifest 相对仓库根的路径，如 `changes/CHG-xxx/.artifacts.json`。 */
+export function manifestPath(id: string): string {
+  return `${changeDir(id)}/${MANIFEST_FILE}`;
+}
+
+/** manifest 在某 worktree 内的绝对路径。 */
+export function manifestAbsPath(worktreeDir: string, id: string): string {
+  return `${worktreeDir}/${manifestPath(id)}`;
+}
+
+/** 读取登记表；文件缺失或内容不是合法登记表时返回空表，不抛错。 */
+export function readArtifactManifest(
+  worktreeDir: string,
+  id: string,
+): ArtifactManifest {
+  const absPath = manifestAbsPath(worktreeDir, id);
+  if (!existsSync(absPath)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(absPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return Object.fromEntries(
+      Object.entries(parsed).filter(
+        (entry): entry is [string, { summary: string }] => {
+          const value = entry[1] as { summary?: unknown } | null;
+          return typeof value?.summary === "string";
+        },
+      ),
+    );
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 兜底登记：Agent 已自写概要时保留原文，只在工件存在而条目缺失时补写兜底概要。
+ * 工件不存在（未选中仓库）不登记，否则下游会把未产出的仓库当成已产出。
+ */
+export function ensureArtifactManifest(
+  worktreeDir: string,
+  id: string,
+  stage: ArtifactStage,
+): boolean {
+  if (!existsSync(artifactAbsPath(stage, worktreeDir, id))) return false;
+  const manifest = readArtifactManifest(worktreeDir, id);
+  const name = artifactName(stage);
+  if (manifest[name]) return false;
+  manifest[name] = { summary: ARTIFACT_SUMMARIES[stage] };
+  writeFileSync(
+    manifestAbsPath(worktreeDir, id),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8",
+  );
+  return true;
+}
+
+/** 阶段专用分支名；当前仅技术方案评审需要独立分支。 */
+export function stageBranchName(stage: ArtifactStage, id: string): string {
+  const filename = artifactName(stage);
+  const suffix = filename.replace(/\.md$/, "").replace(/^0/, "");
+  return `${id}-${suffix}`;
+}

package/templates/ai-native-sdlc/lib/recipe-config.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+const repositoryCommandConfig = z.object({
+  bin: z.string().min(1),
+  args: z.array(z.string()),
+  timeout_ms: z.number().int().positive().optional(),
+}).strict();
+
+/** 仓库只在 profile YAML anchor 中定义一次，steps 通过 alias 获得此完整结构。 */
+export const repositoryConfig = z.object({
+  url: z.string().min(1),
+  default_branch: z.string().min(1).optional(),
+  commands: z.array(repositoryCommandConfig).optional(),
+}).strict();
+
+export type RepositoryConfig = z.infer<typeof repositoryConfig>;
+
+export const pmStageConfig = z.object({
+  pm_repository: repositoryConfig,
+});
+
+/** PRD 需要理解当前业务逻辑，但业务仓库不是 PM 的工件写入目标。 */
+export const prdStageConfig = pmStageConfig.extend({
+  business_repositories: z.array(repositoryConfig).min(1),
+});
+
+export const devStageConfig = z.object({
+  dev_repositories: z.array(repositoryConfig).min(1),
+});
+
+/** 技术方案阶段还需读取 PM 仓库 worktree 中已合并的 PRD。 */
+export const planStageConfig = devStageConfig.extend({
+  pm_repository: repositoryConfig,
+});