@guanlin4924/devflow-pi 0.1.65 → 0.1.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.65";
+export const PRODUCT_VERSION = "0.1.66";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/project-documents.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
 
 import { InitializationStore } from "./initialization-store.ts";
 import type { ProjectContext } from "./project-context.ts";
@@ -14,6 +15,9 @@ export type DocumentGenerationMode = "low-tier-model" | "template";
 export type DocumentGenerationResult = { targetPath: string; status: "complete" | "conflict" | "failed"; outputPath?: string; error?: string };
 
 type Fact = { kind: string; repository: string; objectKey: string; value: Record<string, unknown>; evidenceLevel: string };
+type SourceDocument = { id: string; path: string; contentHash: string; title: string; headings: string[]; excerpt: string };
+type DocumentClassification = { sourceDocumentId: string; scope: "project" | "requirement" | "unknown"; documentType: KnowledgeDocumentType | "unknown"; requirementId?: string; requirementTitle?: string; confidence: "exact" | "inferred" | "heuristic"; reasons: string[] };
+type DocumentKnowledge = { sources: SourceDocument[]; classifications: DocumentClassification[] };
 const TEMPLATE_VERSION = "project-context-v2";
 const KNOWLEDGE_DOCUMENT_TYPES = [
   "requirements",
@@ -69,6 +73,90 @@ function codeIndexGeneration(snapshot: { indexRef?: unknown }): string | undefin
   const indexRef = snapshot.indexRef as Record<string, unknown> | undefined;
   return typeof indexRef?.generation === "string" ? indexRef.generation : undefined;
 }
+function slug(value: string): string {
+  return value.trim().toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-|-$/g, "").slice(0, 48) || "document";
+}
+function titleFromMarkdown(relativePath: string, content: string): string {
+  const heading = content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  return heading || path.basename(relativePath).replace(/\.[^.]+$/, "");
+}
+function headingsFromMarkdown(content: string): string[] {
+  return [...content.matchAll(/^#{1,4}\s+(.+)$/gm)].map(match => match[1].trim()).slice(0, 40);
+}
+function excerpt(content: string): string {
+  return content.replace(/^---[\s\S]*?---\s*/m, "").replace(/\s+/g, " ").trim().slice(0, 500);
+}
+function classifyDocument(document: SourceDocument): DocumentClassification {
+  const haystack = `${document.path}\n${document.title}\n${document.headings.join("\n")}\n${document.excerpt}`.toLowerCase();
+  const reasons: string[] = [];
+  const hit = (type: KnowledgeDocumentType, patterns: RegExp[]) => {
+    const matched = patterns.find(pattern => pattern.test(haystack));
+    if (!matched) return false;
+    reasons.push(`${type}:${matched.source}`);
+    return true;
+  };
+  let documentType: KnowledgeDocumentType | "unknown" = "unknown";
+  if (hit("api", [/\bapi\b/, /接口/, /openapi/, /swagger/])) documentType = "api";
+  else if (hit("test-cases", [/test[-_ ]?case/, /测试/, /用例/, /验收/, /acceptance/])) documentType = "test-cases";
+  else if (hit("frontend-tech", [/frontend/, /前端/, /\bh5\b/, /admin/, /react|vue|vite|router|组件/])) documentType = "frontend-tech";
+  else if (hit("backend-tech", [/backend/, /后端/, /server/, /服务端/, /handler|service|repository|gorm|gin/])) documentType = "backend-tech";
+  else if (hit("architecture", [/architecture/, /架构/, /系统设计/, /数据流/, /部署/])) documentType = "architecture";
+  else if (hit("product-design", [/product[-_ ]?design/, /交互/, /产品设计/, /原型/, /页面设计/, /wireframe/])) documentType = "product-design";
+  else if (hit("requirements", [/requirement/, /\bprd\b/, /需求/, /feature/, /用户故事/])) documentType = "requirements";
+  const requirementMatch = haystack.match(/\b(req[-_ ]?\d{1,5})\b/i) ?? haystack.match(/需求[\s：:]*([a-z0-9_-]{2,40})/i);
+  const requirementId = requirementMatch?.[1]?.toUpperCase().replace(/[_ ]/g, "-");
+  const pathLooksRequirement = /(^|\/)(features?|requirements?|需求|prd)(\/|$)/i.test(document.path) || Boolean(requirementId);
+  return {
+    sourceDocumentId: document.id,
+    scope: documentType === "unknown" ? "unknown" : pathLooksRequirement ? "requirement" : "project",
+    documentType,
+    requirementId,
+    requirementTitle: requirementId ? document.title : undefined,
+    confidence: requirementId ? "exact" : documentType === "unknown" ? "heuristic" : pathLooksRequirement ? "inferred" : "heuristic",
+    reasons: reasons.length ? reasons : ["no strong classifier match"],
+  };
+}
+function shouldInspectDocument(relativePath: string): boolean {
+  if (!/\.(?:md|mdx|txt|adoc|rst|yaml|yml|json)$/i.test(relativePath)) return false;
+  if (/^(?:\.git|node_modules|dist|build|coverage|vendor|target)\//.test(relativePath)) return false;
+  if (/^\.planning\/code-index\//.test(relativePath)) return false;
+  if (/^\.context\/requirements\/_template\//.test(relativePath)) return false;
+  return /^(?:README|docs\/|features\/|requirements\/|\.context\/|\.planning\/requirements\/|\.planning\/features\/|test-environment-guide|skit\/docs\/|text\/)/i.test(relativePath);
+}
+async function discoverSourceDocuments(root: string): Promise<DocumentKnowledge> {
+  const documents: SourceDocument[] = [];
+  async function walk(directory: string, relative = ""): Promise<void> {
+    let entries;
+    try { entries = await readdir(path.join(directory, relative), { withFileTypes: true }); } catch { return; }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const child = path.join(relative, entry.name).replaceAll("\\", "/");
+      if (entry.isDirectory()) {
+        if (/^(?:\.git|node_modules|dist|build|coverage|vendor|target)(\/|$)/.test(child)) continue;
+        await walk(directory, child); continue;
+      }
+      if (!entry.isFile() || !shouldInspectDocument(child)) continue;
+      const absolute = path.join(directory, child);
+      const info = await stat(absolute);
+      if (info.size > 512 * 1024) continue;
+      const content = await readFile(absolute, "utf8");
+      const contentHash = sha(content);
+      documents.push({ id: `DOC-${String(documents.length + 1).padStart(4, "0")}`, path: child, contentHash, title: titleFromMarkdown(child, content), headings: headingsFromMarkdown(content), excerpt: excerpt(content) });
+    }
+  }
+  await walk(root);
+  const sources = documents.slice(0, 500);
+  return { sources, classifications: sources.map(classifyDocument) };
+}
+function sourcesFor(type: KnowledgeDocumentType, knowledge: DocumentKnowledge, scope?: "project" | "requirement"): Array<{ source: SourceDocument; classification: DocumentClassification }> {
+  return knowledge.classifications
+    .filter(classification => classification.documentType === type && (!scope || classification.scope === scope))
+    .map(classification => ({ classification, source: knowledge.sources.find(source => source.id === classification.sourceDocumentId)! }))
+    .filter(item => Boolean(item.source));
+}
+function sourceTable(items: Array<{ source: SourceDocument; classification: DocumentClassification }>): string {
+  if (!items.length) return "未发现可归类的已有文档。";
+  return table(["来源", "标题", "置信度", "理由"], items.map(item => [item.source.path, item.source.title, item.classification.confidence, item.classification.reasons.join("；")]));
+}
 
 async function narrative(context: ProjectContext, document: string, facts: Fact[], mode: DocumentGenerationMode, organizer?: LowTierDocumentOrganizer): Promise<{ text: string; modelRole?: string }> {
   const knownFacts = facts.slice(0, 80).map(fact => `${fact.kind}: ${Object.values(fact.value).filter(value => typeof value === "string" || typeof value === "number").slice(0, 3).join(" / ")}`);
@@ -113,7 +201,7 @@ function renderDocuments(context: ProjectContext, facts: Fact[], intro: string,
   return outputs;
 }
 
-function projectKnowledgeBody(context: ProjectContext, type: KnowledgeDocumentType, facts: Fact[], intro: string, snapshotId: string, generation?: string): string {
+function projectKnowledgeBody(context: ProjectContext, type: KnowledgeDocumentType, facts: Fact[], intro: string, snapshotId: string, knowledge: DocumentKnowledge, generation?: string): string {
   const apis = facts.filter(fact => fact.kind === "api");
   const pages = facts.filter(fact => fact.kind === "page");
   const models = facts.filter(fact => fact.kind === "data_model");
@@ -131,6 +219,10 @@ function projectKnowledgeBody(context: ProjectContext, type: KnowledgeDocumentTy
     managed: true,
   });
   const evidence = [
+    "",
+    "## 已发现资料",
+    "",
+    sourceTable(sourcesFor(type, knowledge, "project")),
     "",
     "## 证据绑定",
     "",
@@ -150,7 +242,7 @@ function projectKnowledgeBody(context: ProjectContext, type: KnowledgeDocumentTy
 
 function requirementTemplateBody(context: ProjectContext, type: KnowledgeDocumentType, snapshotId: string, generation?: string): string {
   const header = frontmatter({
-    type: `requirement-${type}`,
+    type: type === "requirements" ? "requirement-spec" : `requirement-${type}`,
     scope: "requirement",
     project: context.manifest.name,
     requirement_id: "REQ-TEMPLATE",
@@ -164,19 +256,35 @@ function requirementTemplateBody(context: ProjectContext, type: KnowledgeDocumen
   return `${header}# ${documentTitle(type)}\n\n本文件是需求级文档模板。创建具体需求时复制到 \`.context/requirements/REQ-xxx-短名/${type === "requirements" ? "requirement" : type}.md\`，并把 frontmatter 中的 \`requirement_id\`、\`status\`、关联路径和 API 补全。\n\n## 当前结论\n\n- 待补充。\n\n## 证据与约束\n\n- 初始化快照：${snapshotId}\n- 代码索引 generation：${generation ?? "未生成或已跳过"}\n- 需求级内容必须引用项目级文档和实际源码证据，不能只凭推断确认。\n\n## 待补充\n\n- 背景与目标\n- 范围与非目标\n- 设计决策\n- 验收条件\n`;
 }
 
-function renderKnowledgeDocuments(context: ProjectContext, facts: Fact[], intro: string, snapshot: { id?: unknown; indexRef?: unknown }): Array<{ targetPath: string; body: string }> {
+function inboxRequirementBody(context: ProjectContext, source: SourceDocument, classification: DocumentClassification, snapshotId: string, generation?: string): Array<{ targetPath: string; body: string }> {
+  const requirementId = classification.requirementId ?? source.id;
+  const folder = `${requirementId}-${slug(source.title)}`;
+  const base = `.context/requirements/_inbox/${folder}`;
+  const documentType = classification.documentType === "unknown" ? "requirements" : classification.documentType;
+  const body = `${frontmatter({ type: documentType === "requirements" ? "requirement-spec" : `requirement-${documentType}`, scope: "requirement", project: context.manifest.name, requirement_id: requirementId, status: "inbox", source_snapshot: snapshotId, code_index_generation: generation, source_documents: [source.path], managed: true })}# ${source.title}\n\n本文档由初始化阶段从已有资料归档而来，尚未确认是否为正式需求。\n\n## 来源摘要\n\n${source.excerpt || "无可用摘要。"}\n\n## 来源文档\n\n${table(["来源", "标题", "内容哈希"], [[source.path, source.title, source.contentHash]])}\n\n## 归类信息\n\n- 类型：${classification.documentType}\n- 置信度：${classification.confidence}\n- 理由：${classification.reasons.join("；")}\n\n## 待确认\n\n- 是否转为正式 REQ 编号\n- 是否拆分为多个需求\n- 是否补齐产品、技术、API 与用例文档\n`;
+  return [
+    { targetPath: `${base}/index.md`, body },
+    { targetPath: `${base}/${documentType === "requirements" ? "requirement" : documentType}.md`, body },
+  ];
+}
+
+function renderKnowledgeDocuments(context: ProjectContext, facts: Fact[], intro: string, snapshot: { id?: unknown; indexRef?: unknown }, knowledge: DocumentKnowledge): Array<{ targetPath: string; body: string }> {
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   const outputs: Array<{ targetPath: string; body: string }> = [];
   outputs.push({ targetPath: ".context/index.md", body: `${frontmatter({ type: "knowledge-index", scope: "project", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${context.manifest.name} 项目知识库\n\n## 项目级文档\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](/project/${type}.md)`).join("\n")}\n\n## 需求级文档\n\n- 新需求使用 [.context/requirements/_template/index.md](/requirements/_template/index.md) 作为文档包模板。\n\n## 机器索引\n\n- 文档索引：\`.planning/document-index.json\`\n- 代码索引：\`.planning/code-index/\`\n` });
   outputs.push({ targetPath: ".context/project/index.md", body: `${frontmatter({ type: "project-document-index", scope: "project", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 项目级文档\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](./${type}.md)`).join("\n")}\n` });
-  for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.context/project/${type}.md`, body: projectKnowledgeBody(context, type, facts, intro, snapshotId, generation) });
+  for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.context/project/${type}.md`, body: projectKnowledgeBody(context, type, facts, intro, snapshotId, knowledge, generation) });
   outputs.push({ targetPath: ".context/requirements/_template/index.md", body: `${frontmatter({ type: "requirement-document-index", scope: "requirement", project: context.manifest.name, requirement_id: "REQ-TEMPLATE", status: "template", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 需求级文档模板\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](./${type === "requirements" ? "requirement" : type}.md)`).join("\n")}\n` });
   for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.context/requirements/_template/${type === "requirements" ? "requirement" : type}.md`, body: requirementTemplateBody(context, type, snapshotId, generation) });
+  for (const item of knowledge.classifications.filter(item => item.scope === "requirement" && item.confidence !== "exact").slice(0, 100)) {
+    const source = knowledge.sources.find(source => source.id === item.sourceDocumentId);
+    if (source) outputs.push(...inboxRequirementBody(context, source, item, snapshotId, generation));
+  }
   return outputs;
 }
 
-function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, outputs: Array<{ targetPath: string }>): { targetPath: string; body: string } {
+function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, outputs: Array<{ targetPath: string }>, knowledge: DocumentKnowledge): { targetPath: string; body: string } {
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   const documents = outputs
@@ -193,7 +301,7 @@ function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown;
         type,
         scope,
         requirementId: scope === "requirement" ? (parts[2] === "_template" ? "REQ-TEMPLATE" : parts[2]) : undefined,
-        status: parts.includes("_template") ? "template" : "draft",
+        status: parts.includes("_template") ? "template" : parts.includes("_inbox") ? "inbox" : "draft",
         managed: true,
         sourceSnapshot: snapshotId,
         codeIndexGeneration: generation ?? null,
@@ -201,7 +309,16 @@ function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown;
     });
   return {
     targetPath: ".planning/document-index.json",
-    body: `${JSON.stringify({ schemaVersion: 1, project: context.manifest.name, projectId: context.manifest.projectId, sourceSnapshot: snapshotId, codeIndexGeneration: generation ?? null, documents }, null, 2)}\n`,
+    body: `${JSON.stringify({
+      schemaVersion: 2,
+      project: context.manifest.name,
+      projectId: context.manifest.projectId,
+      sourceSnapshot: snapshotId,
+      codeIndexGeneration: generation ?? null,
+      sourceDocuments: knowledge.sources,
+      classifications: knowledge.classifications,
+      documents,
+    }, null, 2)}\n`,
   };
 }
 
@@ -222,8 +339,9 @@ export async function generateProjectDocuments(context: ProjectContext, snapshot
     try { organized = await narrative(context, "project-initialization", facts, options.mode, options.organizer); }
     catch (error) { store.failDocumentJob(batchJob, error instanceof Error ? error.message : String(error)); throw error; }
     const snapshotMeta = (store.queryContext({ snapshotId, limit: 1 }) as { snapshot: { id?: unknown; indexRef?: unknown } }).snapshot;
-    const outputs = [...renderDocuments(context, facts, organized.text, collections), ...renderKnowledgeDocuments(context, facts, organized.text, snapshotMeta)];
-    outputs.push(renderDocumentIndex(context, snapshotMeta, outputs));
+    const knowledge = await discoverSourceDocuments(context.root);
+    const outputs = [...renderDocuments(context, facts, organized.text, collections), ...renderKnowledgeDocuments(context, facts, organized.text, snapshotMeta, knowledge)];
+    outputs.push(renderDocumentIndex(context, snapshotMeta, outputs, knowledge));
     const results: DocumentGenerationResult[] = [];
     for (const output of outputs) {
       const job = store.createDocumentJob(snapshotId, { targetPath: output.targetPath, ownership: "generated", templateVersion: TEMPLATE_VERSION, modelRole: organized.modelRole, input: facts.map(fact => fact.objectKey) });