@guanlin4924/devflow-pi 0.1.68 → 0.1.69

package/package.json

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

package/plugins/devflow-core/skills/workflow-project-context/SKILL.md

@@ -7,6 +7,8 @@ description: "Use when a project needs database-backed initialization, repositor
 
 Initialize project context only. Do not create requirements, approved API contracts, prototypes, roadmaps, commits, tags, repositories, or workflow state.
 
+This skill is the project-context interface wrapper. Prefer using it from a delegated sub-agent when the user asks to initialize, refresh, query, compare, or diagnose project context. The sub-agent owns interface selection, tool-call argument construction, evidence collection, and result packaging. The parent agent should receive a compact result pack instead of hand-building low-level `devflow_project_context` calls.
+
 ## Authority and ownership
 
 The control database under the product data directory is the only machine authority for initialization. `.devflow/project.json` locates project identity. Workspaces, scan configurations, input snapshots, runs, facts, evidence, index references, current pointers, document jobs, and authority revisions are stored through `devflow_project_context`.
@@ -15,6 +17,91 @@ Never determine current initialization state from Markdown, file mtimes, or dupl
 
 Human-readable files are projections. Existing unmanaged files are preserved; the generator writes a `.devflow-pending` sibling when it cannot prove that the current file is its previous output.
 
+## External contract usage
+
+Before choosing a tool action, inspect the generated external contract when it exists:
+
+```text
+.planning/interface-index.json
+.planning/knowledge-index.json
+.context/knowledge/interfaces/
+```
+
+`.planning/interface-index.json` is the machine-readable contract for external AI/tool callers. It lists callable interfaces, actions, request shapes, response shapes, read/write boundaries, and approval tier. `.context/knowledge/interfaces/` is the human-readable projection of the same contract. `.planning/knowledge-index.json` connects interface nodes, source documents, knowledge pages, code facts, and reserved BUG/FIX/INCIDENT/LESSON nodes.
+
+If the contract files do not exist yet, use the rules in this skill to run initialization and then report that the interface contract was created. If they exist, do not invent action shapes from memory; follow the contract unless it conflicts with this skill's safety rules.
+
+## Delegated agent usage
+
+Use a delegated sub-agent for non-trivial project-context work:
+
+- initialize or refresh a project;
+- query APIs, pages, models, toolchain, requirements, knowledge, or BUG/FIX nodes;
+- compare snapshots after code or documentation changes;
+- refresh after a BUG fix;
+- diagnose failed or partial initialization;
+- rebuild documents from an existing snapshot.
+
+The delegated sub-agent must:
+
+1. read `.planning/interface-index.json` when available;
+2. choose the narrowest safe action;
+3. call `devflow_project_context` or `devflow_skill_script` only through the documented action shape;
+4. read `.planning/knowledge-index.json` and `.planning/code-index/` only when needed for evidence;
+5. return a result pack to the parent agent.
+
+The parent agent should not directly compose multi-step initialization calls unless the task is a simple status read or the delegated agent path is unavailable.
+
+## Supported intents and action selection
+
+| Intent | Preferred action sequence | Notes |
+|---|---|---|
+| `initialize-project` | `workspaces` → `config` → `scan` → `project-context-db-validate` | Full mode by default; static only; no workflow state mutation. |
+| `query-facts` | `query` | Requires a fixed `snapshotId`; follow pagination. |
+| `query-api` | `query(kind="api")` plus code-index readback when implementation detail is needed | Do not scan just to answer from an existing fresh snapshot. |
+| `query-knowledge` | read `knowledge-index.json` and relevant `.context/knowledge/*` | Use `query` only for machine facts. |
+| `query-bug-knowledge` | read reserved/actual BUG/FIX/INCIDENT/LESSON nodes, then query/diff if code facts are needed | Do not invent BUG records. |
+| `refresh-after-code-change` | `scan` → optional `diff` | Use a new request ID. Compare old and new snapshots when impact is requested. |
+| `refresh-after-bug-fix` | verify BUG/FIX/LESSON docs if present → `scan` → optional `diff` | `scan` refreshes facts; it does not fix the bug. |
+| `regenerate-docs` | `generate-docs` | Use when the snapshot is still valid and only projections need rebuilding. |
+| `compare-snapshots` | `diff` | Incompatible configs are not deletion evidence. |
+| `diagnose-initialization` | `run-status` → `query`/`config`/`workspaces` as needed | Report exact failing stage and recovery option. |
+
+High-risk maintenance actions (`restore`, `switch-authority`, `backup`, `recover`, `cancel`) require an explicit user request or a clearly scoped recovery task. Never run them as part of ordinary query or explanation.
+
+## Result pack contract
+
+Every delegated project-context result must return this structure in prose or JSON-like Markdown:
+
+```text
+## Conclusion
+- concise answer or initialization status
+
+## Actions Used
+- interface/action names and whether each was read or exec
+
+## Snapshot
+- runId
+- snapshotId
+- codeIndexGeneration
+- sourceSnapshot
+- interfaceContract: .planning/interface-index.json if used
+
+## Evidence
+- facts, knowledge pages, code facts, document paths, or diagnostics used
+
+## Changes / Impact
+- changed facts or documents when diff/refresh was requested
+
+## Gaps
+- missing evidence, unsupported adapters, stale index, conflicts, or manual files preserved as .devflow-pending
+
+## Recommended Next Action
+- query, diff, generate-docs, scan, human review, or no action
+```
+
+The result pack must distinguish observed machine facts from draft knowledge, historical imports, model candidates, and human-confirmed content.
+
 ## Modes
 
 - Full mode is the default. It performs bounded static fact collection and builds, validates, and audits an immutable code-index generation before the context snapshot becomes current.

package/src/constants.ts

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

package/src/project-documents.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 
-import { InitializationStore } from "./initialization-store.ts";
+import { FACT_KINDS, InitializationStore } from "./initialization-store.ts";
 import type { ProjectContext } from "./project-context.ts";
 
 export interface LowTierDocumentOrganizer {
@@ -18,6 +18,35 @@ type Fact = { kind: string; repository: string; objectKey: string; value: Record
 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[] };
+type KnowledgePageType = "source-summary" | "entity" | "concept" | "requirement" | "synthesis" | "bug-report" | "bug-fix" | "incident" | "lesson";
+type KnowledgePage = {
+  id: string;
+  path: string;
+  type: KnowledgePageType;
+  title: string;
+  status: "draft" | "inbox";
+  sourceRefs: string[];
+  relatedRequirements: string[];
+  relatedCodeFacts: string[];
+  confidence: "high" | "medium" | "low";
+};
+type IndexedDocumentScope = "project" | "requirement" | "knowledge";
+type InterfaceContract = {
+  id: string;
+  name: string;
+  kind: "tool" | "skill" | "cli" | "artifact";
+  path: string;
+  purpose: string;
+  approval: "read" | "exec" | "none";
+  actions: Array<{
+    name: string;
+    purpose: string;
+    request: Record<string, unknown>;
+    response: Record<string, unknown>;
+    writes: string[];
+    reads: string[];
+  }>;
+};
 const TEMPLATE_VERSION = "project-context-v2";
 const KNOWLEDGE_DOCUMENT_TYPES = [
   "requirements",
@@ -153,6 +182,54 @@ function sourcesFor(type: KnowledgeDocumentType, knowledge: DocumentKnowledge, s
     .map(classification => ({ classification, source: knowledge.sources.find(source => source.id === classification.sourceDocumentId)! }))
     .filter(item => Boolean(item.source));
 }
+function factRef(fact: Fact): string {
+  if (fact.kind === "api") return `api_route:${String(fact.value.method ?? "UNKNOWN").toUpperCase()}:${apiPath(fact)}`;
+  return `${fact.kind}:${fact.repository}:${fact.objectKey}`;
+}
+function relatedCodeFactsForSource(source: SourceDocument, classification: DocumentClassification, facts: Fact[]): string[] {
+  const haystack = `${source.path}\n${source.title}\n${source.headings.join("\n")}\n${source.excerpt}`.toLowerCase();
+  const candidates = facts.filter(fact => {
+    const values = Object.values(fact.value).filter(value => typeof value === "string" || typeof value === "number").map(String);
+    return values.some(value => {
+      const token = value.toLowerCase();
+      return token.length >= 3 && (haystack.includes(token) || token.includes(slug(source.title).replaceAll("-", "")));
+    });
+  });
+  const fallback = classification.documentType === "api" ? facts.filter(fact => fact.kind === "api")
+    : classification.documentType === "frontend-tech" || classification.documentType === "product-design" ? facts.filter(fact => fact.kind === "page")
+      : classification.documentType === "backend-tech" || classification.documentType === "architecture" ? facts.filter(fact => ["api", "data_model", "integration"].includes(fact.kind))
+        : [];
+  return [...new Set([...candidates, ...fallback].slice(0, 12).map(factRef))];
+}
+function extractKnowledgeNames(source: SourceDocument): Array<{ kind: "entity" | "concept"; title: string; confidence: "medium" | "low" }> {
+  const names = new Map<string, { kind: "entity" | "concept"; title: string; confidence: "medium" | "low" }>();
+  const text = `${source.title}\n${source.headings.join("\n")}\n${source.excerpt}`;
+  for (const match of text.matchAll(/(?:用户|管理员|客户|商户|运营|后台|前台|服务|系统|订单|资源|内容|权限|支付|审核|任务|消息|通知|接口|页面|角色|数据|模型|流程)/g)) {
+    const title = match[0];
+    const kind: "entity" | "concept" = /用户|管理员|客户|商户|运营|服务|系统|订单|资源|内容|任务|消息|通知|角色|数据|模型/.test(title) ? "entity" : "concept";
+    names.set(`${kind}:${title}`, { kind, title, confidence: "low" });
+  }
+  for (const heading of source.headings.slice(0, 8)) {
+    const clean = heading.replace(/[：:：].*$/, "").trim();
+    if (clean.length >= 2 && clean.length <= 32) names.set(`concept:${clean}`, { kind: "concept", title: clean, confidence: "medium" });
+  }
+  return [...names.values()].slice(0, 40);
+}
+function sourcePageId(source: SourceDocument): string { return `source-${source.id.toLowerCase()}`; }
+function knowledgePagePath(type: KnowledgePageType, titleOrId: string): string {
+  const folder = ({
+    "source-summary": "sources",
+    entity: "entities",
+    concept: "concepts",
+    requirement: "requirements",
+    synthesis: "synthesis",
+    "bug-report": "bugs",
+    "bug-fix": "fixes",
+    incident: "incidents",
+    lesson: "lessons",
+  } satisfies Record<KnowledgePageType, string>)[type];
+  return `.context/knowledge/${folder}/${slug(titleOrId)}.md`;
+}
 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("；")]));
@@ -317,6 +394,539 @@ function inboxRequirementBody(context: ProjectContext, source: SourceDocument, c
   ];
 }
 
+function buildKnowledgePages(knowledge: DocumentKnowledge, facts: Fact[]): KnowledgePage[] {
+  const pages = new Map<string, KnowledgePage>();
+  for (const source of knowledge.sources) {
+    const classification = knowledge.classifications.find(item => item.sourceDocumentId === source.id);
+    const requirementId = classification?.requirementId ? classification.requirementId : classification?.scope === "requirement" ? source.id : undefined;
+    const sourceRef = sourcePageId(source);
+    const relatedCodeFacts = classification ? relatedCodeFactsForSource(source, classification, facts) : [];
+    pages.set(sourceRef, {
+      id: sourceRef,
+      path: knowledgePagePath("source-summary", sourceRef),
+      type: "source-summary",
+      title: source.title,
+      status: classification?.scope === "requirement" && classification.confidence !== "exact" ? "inbox" : "draft",
+      sourceRefs: [source.path],
+      relatedRequirements: requirementId ? [requirementId] : [],
+      relatedCodeFacts,
+      confidence: classification?.confidence === "exact" ? "high" : classification?.confidence === "inferred" ? "medium" : "low",
+    });
+    if (classification?.scope === "requirement") {
+      const id = requirementId ?? `REQ-${source.id}`;
+      pages.set(`requirement-${slug(id)}`, {
+        id: `requirement-${slug(id)}`,
+        path: knowledgePagePath("requirement", id),
+        type: "requirement",
+        title: classification.requirementTitle ?? source.title,
+        status: classification.confidence === "exact" ? "draft" : "inbox",
+        sourceRefs: [sourceRef],
+        relatedRequirements: [id],
+        relatedCodeFacts,
+        confidence: classification.confidence === "exact" ? "high" : "medium",
+      });
+    }
+    for (const extracted of extractKnowledgeNames(source)) {
+      const id = `${extracted.kind}-${slug(extracted.title)}`;
+      const existing = pages.get(id);
+      pages.set(id, {
+        id,
+        path: knowledgePagePath(extracted.kind, extracted.title),
+        type: extracted.kind,
+        title: extracted.title,
+        status: "draft",
+        sourceRefs: [...new Set([...(existing?.sourceRefs ?? []), sourceRef])],
+        relatedRequirements: [...new Set([...(existing?.relatedRequirements ?? []), ...(requirementId ? [requirementId] : [])])],
+        relatedCodeFacts: [...new Set([...(existing?.relatedCodeFacts ?? []), ...relatedCodeFacts])].slice(0, 20),
+        confidence: existing?.confidence === "medium" || extracted.confidence === "medium" ? "medium" : "low",
+      });
+    }
+  }
+  const allSourceRefs = [...new Set([...pages.values()].flatMap(page => page.sourceRefs).filter(ref => ref.startsWith("source-")))];
+  pages.set("synthesis-project-overview", {
+    id: "synthesis-project-overview",
+    path: ".context/knowledge/synthesis/project-overview.md",
+    type: "synthesis",
+    title: "项目知识总览",
+    status: "draft",
+    sourceRefs: allSourceRefs,
+    relatedRequirements: [...new Set([...pages.values()].flatMap(page => page.relatedRequirements))].slice(0, 100),
+    relatedCodeFacts: [...new Set([...pages.values()].flatMap(page => page.relatedCodeFacts))].slice(0, 100),
+    confidence: "medium",
+  });
+  return [...pages.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function renderKnowledgePage(context: ProjectContext, page: KnowledgePage, sourceByRef: Map<string, SourceDocument>, snapshotId: string, generation?: string): string {
+  const sourceRows = page.sourceRefs.map(ref => {
+    const source = sourceByRef.get(ref);
+    return source ? [ref, source.path, source.title] : [ref, ref, "外部或原始来源"];
+  });
+  const overview = page.type === "source-summary"
+    ? "本页是原始资料的结构化摘要，用于替代直接对原始长文档做向量召回。"
+    : page.type === "synthesis"
+      ? "本页综合多个来源与代码事实，作为项目级知识入口。"
+      : "本页沉淀初始化阶段识别出的项目知识单元，人工确认前保持草稿状态。";
+  const sourceSummary = page.sourceRefs.map(ref => sourceByRef.get(ref)?.excerpt).filter(Boolean).slice(0, 5).join("\n\n");
+  return `${frontmatter({
+    type: page.type,
+    id: page.id,
+    title: page.title,
+    status: page.status,
+    project: context.manifest.name,
+    source_refs: page.sourceRefs,
+    related_requirements: page.relatedRequirements,
+    related_code_facts: page.relatedCodeFacts,
+    confidence: page.confidence,
+    source_snapshot: snapshotId,
+    code_index_generation: generation,
+    managed: true,
+  })}# ${page.title}
+
+## Overview
+
+${overview}
+
+${sourceSummary ? `## Key Claims\n\n${sourceSummary.split(/[。；;\n]+/).map(item => item.trim()).filter(Boolean).slice(0, 12).map(item => `- ${item}`).join("\n")}\n\n` : ""}## Relationships
+
+${page.relatedRequirements.length ? `- 关联需求：${page.relatedRequirements.join("、")}` : "- 关联需求：未确认"}
+${page.relatedCodeFacts.length ? `- 关联代码事实：${page.relatedCodeFacts.slice(0, 20).join("、")}` : "- 关联代码事实：未确认"}
+
+## Sources
+
+${sourceRows.length ? table(["引用", "路径", "标题"], sourceRows) : "未绑定来源。"}
+
+## Maintenance
+
+- 状态：${page.status}
+- 置信度：${page.confidence}
+- 初始化快照：${snapshotId}
+- 代码索引 generation：${generation ?? "未生成或已跳过"}
+  `;
+}
+
+function bugKnowledgeTemplates(context: ProjectContext, snapshotId: string, generation?: string): Array<{ targetPath: string; body: string }> {
+  const common = { project: context.manifest.name, status: "template", source_snapshot: snapshotId, code_index_generation: generation, managed: true };
+  return [
+    {
+      targetPath: ".context/knowledge/bugs/_template.md",
+      body: `${frontmatter({ ...common, type: "bug-report", id: "BUG-TEMPLATE", title: "BUG 模板", source_refs: [], related_requirements: [], related_code_facts: [], related_fixes: [], regression_tests: [], confidence: "manual" })}# BUG 模板
+
+## Symptom
+
+- 用户或系统观察到的异常现象。
+
+## Impact
+
+- 影响范围、严重程度、受影响角色或能力。
+
+## Reproduction
+
+1. 复现步骤待补充。
+
+## Root Cause
+
+- 根因待确认；不能只凭猜测填写为 confirmed。
+
+## Evidence
+
+- 日志、截图、报错、source_refs、related_code_facts。
+
+## Fix Link
+
+- 关联 FIX 记录。
+
+## Regression
+
+- 回归测试、验证命令或人工验证证据。
+`,
+    },
+    {
+      targetPath: ".context/knowledge/fixes/_template.md",
+      body: `${frontmatter({ ...common, type: "bug-fix", id: "FIX-TEMPLATE", title: "FIX 模板", bug_refs: [], changed_code_facts: [], regression_tests: [], confidence: "manual" })}# FIX 模板
+
+## Change Summary
+
+- 修复动作摘要。
+
+## Why This Fix
+
+- 为什么选择这个修复方式，替代方案和风险是什么。
+
+## Files Changed
+
+- 关联文件或 changed_code_facts。
+
+## Regression Coverage
+
+- 新增或复用的回归测试。
+
+## Remaining Risk
+
+- 尚未覆盖或需观察的风险。
+`,
+    },
+    {
+      targetPath: ".context/knowledge/incidents/_template.md",
+      body: `${frontmatter({ ...common, type: "incident", id: "INC-TEMPLATE", title: "INCIDENT 模板", related_bugs: [], related_fixes: [], related_code_facts: [], confidence: "manual" })}# INCIDENT 模板
+
+## Timeline
+
+- 发现、止血、修复、恢复的时间线。
+
+## User Impact
+
+- 用户影响和业务影响。
+
+## Root Cause
+
+- 事故根因和促成因素。
+
+## Mitigation
+
+- 临时缓解措施和永久修复。
+
+## Follow-ups
+
+- 后续行动、负责人和验证方式。
+`,
+    },
+    {
+      targetPath: ".context/knowledge/lessons/_template.md",
+      body: `${frontmatter({ ...common, type: "lesson", id: "LESSON-TEMPLATE", title: "LESSON 模板", related_bugs: [], related_fixes: [], related_code_facts: [], confidence: "manual" })}# LESSON 模板
+
+## Lesson
+
+- 可复用经验或规则。
+
+## Applies To
+
+- 适用模块、能力、需求或技术边界。
+
+## Check Rule
+
+- 下次如何检查同类问题。
+
+## Evidence
+
+- 关联 BUG、FIX、事故或代码事实。
+`,
+    },
+  ];
+}
+
+function initializationInterfaceContracts(): InterfaceContract[] {
+  return [
+    {
+      id: "tool-devflow-project-context",
+      name: "devflow_project_context",
+      kind: "tool",
+      path: "xd://devflow_project_context",
+      purpose: "项目初始化控制面：扫描、查询、刷新、恢复、导入导出和权威切换。",
+      approval: "exec",
+      actions: [
+        {
+          name: "scan",
+          purpose: "执行项目初始化扫描并发布上下文快照。",
+          request: { action: "scan", mode: "full|fast", repositories: [{ name: "app", path: ".", role: "frontend|backend|shared|other" }], requiredKinds: FACT_KINDS, documentMode: "template|none", requestId: "stable-id" },
+          response: { runId: "uuid", snapshotId: "uuid", completeness: "complete|partial", diagnostics: [], documents: [{ targetPath: ".context/project/api.md", status: "complete|conflict|failed" }] },
+          reads: ["source tree", ".devflow/project.json"],
+          writes: ["control.db", ".planning/code-index/", ".planning/document-index.json", ".planning/knowledge-index.json", ".context/", ".planning/PROJECT.md"],
+        },
+        {
+          name: "query",
+          purpose: "按固定 snapshot 查询初始化事实。",
+          request: { action: "query", snapshotId: "uuid", kind: "api|page|data_model|...", repository: "optional", after: "cursor", limit: 100 },
+          response: { snapshot: {}, facts: [], truncated: false, nextCursor: null },
+          reads: ["control.db"],
+          writes: [],
+        },
+        {
+          name: "diff",
+          purpose: "比较两个明确快照，返回可比变化。",
+          request: { action: "diff", fromSnapshotId: "uuid", toSnapshotId: "uuid" },
+          response: { comparable: true, added: [], changed: [], removed: [], unavailable: [] },
+          reads: ["control.db"],
+          writes: [],
+        },
+        {
+          name: "generate-docs",
+          purpose: "针对已发布快照重试生成文档投影。",
+          request: { action: "generate-docs", snapshotId: "uuid" },
+          response: [{ targetPath: ".context/project/api.md", status: "complete|conflict|failed", outputPath: "path" }],
+          reads: ["control.db", ".planning/code-index/", "source documents"],
+          writes: [".context/", ".planning/document-index.json", ".planning/knowledge-index.json"],
+        },
+        {
+          name: "config",
+          purpose: "读取当前工作区的初始化扫描配置。",
+          request: { action: "config", workspaceId: "optional" },
+          response: { mode: "full|fast", repositories: [], requiredKinds: FACT_KINDS },
+          reads: ["control.db"],
+          writes: [],
+        },
+        {
+          name: "workspaces",
+          purpose: "列出当前项目已登记的工作区。",
+          request: { action: "workspaces" },
+          response: [{ id: "uuid", root: "path", active: true }],
+          reads: ["control.db"],
+          writes: [],
+        },
+        {
+          name: "rebind-workspace",
+          purpose: "将当前项目根重新绑定到指定 workspaceId。",
+          request: { action: "rebind-workspace", workspaceId: "uuid" },
+          response: { id: "uuid", root: "path", active: true },
+          reads: ["control.db", ".devflow/project.json"],
+          writes: ["control.db"],
+        },
+        {
+          name: "run-status",
+          purpose: "读取初始化 run 的状态和发布快照。",
+          request: { action: "run-status", runId: "uuid" },
+          response: { id: "uuid", status: "preparing|collecting|validating|finished|failed|cancelled", publishedSnapshotId: "uuid|null", error: "string|null" },
+          reads: ["control.db"],
+          writes: [],
+        },
+        {
+          name: "cancel",
+          purpose: "取消仍处于可写状态的初始化 run。",
+          request: { action: "cancel", runId: "uuid" },
+          response: { runId: "uuid", cancelled: true },
+          reads: ["control.db"],
+          writes: ["control.db"],
+        },
+        {
+          name: "recover",
+          purpose: "恢复租约过期但未结束的初始化 run。",
+          request: { action: "recover", runId: "uuid" },
+          response: { runId: "uuid", leaseToken: "opaque-token" },
+          reads: ["control.db"],
+          writes: ["control.db"],
+        },
+        {
+          name: "import-legacy",
+          purpose: "把旧版初始化产物导入数据库控制面。",
+          request: { action: "import-legacy", sources: [".planning/PROJECT.md"], requestId: "stable-id" },
+          response: { runId: "uuid", snapshotId: "uuid", imports: [] },
+          reads: ["legacy initialization files"],
+          writes: ["control.db"],
+        },
+        {
+          name: "export",
+          purpose: "把指定初始化快照导出为兼容文件。",
+          request: { action: "export", snapshotId: "uuid", targetPath: ".planning/project-context-export.json" },
+          response: { path: "path", contentHash: "sha256:..." },
+          reads: ["control.db"],
+          writes: ["targetPath"],
+        },
+        {
+          name: "authority",
+          purpose: "读取当前初始化权威来源和修订号。",
+          request: { action: "authority" },
+          response: { authority: "legacy|shadow|database", revision: 0 },
+          reads: ["control.db"],
+          writes: [],
+        },
+        {
+          name: "switch-authority",
+          purpose: "按期望 revision 切换初始化权威来源。",
+          request: { action: "switch-authority", authority: "legacy|shadow|database", expectedRevision: 0, compatibilityExport: "optional" },
+          response: { status: "action-specific", revision: "number when applicable" },
+          reads: ["control.db"],
+          writes: ["control.db", "compatibilityExport when requested"],
+        },
+        {
+          name: "backup",
+          purpose: "备份初始化控制数据库和内容状态。",
+          request: { action: "backup", targetPath: ".planning/backups/initialization.db" },
+          response: { backup: "absolute-path" },
+          reads: ["control.db", "managed initialization documents"],
+          writes: ["targetPath", "targetPath.manifest.json"],
+        },
+        {
+          name: "restore",
+          purpose: "从已验证备份恢复初始化控制数据库。",
+          request: { action: "restore", targetPath: ".planning/backups/initialization.db" },
+          response: { restored: true, database: "control.db" },
+          reads: ["targetPath", "targetPath.manifest.json"],
+          writes: ["control.db"],
+        },
+      ],
+    },
+    {
+      id: "tool-devflow-skill-script",
+      name: "devflow_skill_script",
+      kind: "tool",
+      path: "xd://devflow_skill_script",
+      purpose: "执行 allowlisted 的确定性 skill 脚本，初始化主要使用数据库校验。",
+      approval: "exec",
+      actions: [
+        {
+          name: "project-context-db-validate",
+          purpose: "校验初始化控制数据库、run、workspace、project 和快照关系。",
+          request: { script: "project-context-db-validate", args: ["--database", "<control.db>", "--project-id", "<project-id>", "--workspace-id", "<workspace-id>", "--run-id", "<run-id>"] },
+          response: { ok: true, diagnostics: [] },
+          reads: ["control.db"],
+          writes: [],
+        },
+      ],
+    },
+    {
+      id: "skill-workflow-project-context",
+      name: "skill://workflow-project-context",
+      kind: "skill",
+      path: "plugins/devflow-core/skills/workflow-project-context/SKILL.md",
+      purpose: "项目上下文接口包装 skill：供委托子 agent 选择 action、调用初始化 contract、整理证据包并返回给父 agent。",
+      approval: "none",
+      actions: [
+        {
+          name: "delegated-project-context-task",
+          purpose: "由子 agent 根据用户意图读取 interface-index/knowledge-index，调用 devflow_project_context 或 devflow_skill_script，并返回 result pack。",
+          request: {
+            intent: "initialize-project|refresh-after-code-change|refresh-after-bug-fix|query-facts|query-knowledge|query-api|query-bug-knowledge|compare-snapshots|regenerate-docs|diagnose-initialization",
+            snapshotId: "optional fixed snapshot",
+            repositories: "optional confirmed project repositories",
+            question: "parent-agent request",
+          },
+          response: {
+            conclusion: "concise answer or initialization status",
+            actionsUsed: [],
+            snapshot: { runId: "uuid|null", snapshotId: "uuid|null", codeIndexGeneration: "generation|null", sourceSnapshot: "uuid|null" },
+            evidence: [],
+            changesOrImpact: [],
+            gaps: [],
+            recommendedNextAction: "query|diff|generate-docs|scan|human-review|none",
+          },
+          reads: [".planning/interface-index.json", ".planning/knowledge-index.json", ".planning/code-index/", ".context/knowledge/", "control interfaces"],
+          writes: ["initialization projections through tools only"],
+        },
+      ],
+    },
+    {
+      id: "skill-workflow-code-index",
+      name: "skill://workflow-code-index",
+      kind: "skill",
+      path: "plugins/devflow-intel/skills/workflow-code-index/SKILL.md",
+      purpose: "代码事实索引生命周期：scan、validate、audit、query。",
+      approval: "exec",
+      actions: [
+        {
+          name: "scan/validate/audit/query",
+          purpose: "生成并查询 .planning/code-index/ 机器代码事实。",
+          request: { action: "scan|validate|audit|query", index: ".planning/code-index", root: "." },
+          response: { generation: "uuid", files: "jsonl", symbols: "jsonl", relations: "jsonl", diagnostics: "jsonl" },
+          reads: ["source tree"],
+          writes: [".planning/code-index/"],
+        },
+      ],
+    },
+    {
+      id: "cli-devflow-pi-init",
+      name: "devflow-pi init --scan",
+      kind: "cli",
+      path: "src/cli.ts",
+      purpose: "命令行初始化入口，创建项目身份并可触发 scan。",
+      approval: "exec",
+      actions: [
+        {
+          name: "init",
+          purpose: "创建 .devflow/project.json，输出 projectId/workspaceId/database/planning，可选执行 scan。",
+          request: { argv: ["devflow-pi", "init", "<project>", "--scan", "--request-id", "<id>"] },
+          response: { projectId: "uuid", workspaceId: "uuid", database: "control.db", initializationRun: "uuid", contextSnapshot: "uuid" },
+          reads: ["project path"],
+          writes: [".devflow/project.json", "control.db", "initialization projections when --scan"],
+        },
+      ],
+    },
+    {
+      id: "artifact-knowledge-index",
+      name: ".planning/knowledge-index.json",
+      kind: "artifact",
+      path: ".planning/knowledge-index.json",
+      purpose: "知识页、来源文档、需求、代码事实和预留 BUG 节点的桥接索引。",
+      approval: "read",
+      actions: [
+        {
+          name: "read",
+          purpose: "让 LLM 或工具快速发现知识层节点和绑定关系。",
+          request: { path: ".planning/knowledge-index.json" },
+          response: { schemaVersion: 1, bundleRoot: ".context/knowledge", pages: [], reservedBugKnowledgeNodes: [] },
+          reads: [".planning/knowledge-index.json"],
+          writes: [],
+        },
+      ],
+    },
+  ];
+}
+
+function renderInterfaceContract(context: ProjectContext, contract: InterfaceContract, snapshotId: string, generation?: string): string {
+  return `${frontmatter({ type: "interface-contract", id: contract.id, title: contract.name, interface_kind: contract.kind, project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${contract.name}
+
+## Purpose
+
+${contract.purpose}
+
+## Endpoint
+
+- 类型：${contract.kind}
+- 入口：\`${contract.path}\`
+- 权限：${contract.approval}
+
+## Actions
+
+${contract.actions.map(action => `### ${action.name}
+
+${action.purpose}
+
+#### Request
+
+\`\`\`json
+${JSON.stringify(action.request, null, 2)}
+\`\`\`
+
+#### Response
+
+\`\`\`json
+${JSON.stringify(action.response, null, 2)}
+\`\`\`
+
+#### Reads
+
+${action.reads.map(item => `- ${item}`).join("\n") || "- 无"}
+
+#### Writes
+
+${action.writes.map(item => `- ${item}`).join("\n") || "- 无"}
+`).join("\n")}
+`;
+}
+
+function renderInterfaceOutputs(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }): { outputs: Array<{ targetPath: string; body: string }>; contracts: InterfaceContract[] } {
+  const snapshotId = String(snapshot.id ?? "");
+  const generation = codeIndexGeneration(snapshot);
+  const contracts = initializationInterfaceContracts();
+  const outputs: Array<{ targetPath: string; body: string }> = [];
+  outputs.push({ targetPath: ".context/knowledge/interfaces/index.md", body: `${frontmatter({ type: "interface-index", title: "初始化接口目录", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 初始化接口目录\n\n${contracts.map(contract => `- [${contract.name}](./${slug(contract.id)}.md) — ${contract.purpose}`).join("\n")}\n` });
+  for (const contract of contracts) outputs.push({ targetPath: `.context/knowledge/interfaces/${slug(contract.id)}.md`, body: renderInterfaceContract(context, contract, snapshotId, generation) });
+  return { outputs, contracts };
+}
+
+function renderOpenWikiKnowledge(context: ProjectContext, facts: Fact[], snapshot: { id?: unknown; indexRef?: unknown }, knowledge: DocumentKnowledge): { outputs: Array<{ targetPath: string; body: string }>; pages: KnowledgePage[] } {
+  const snapshotId = String(snapshot.id ?? "");
+  const generation = codeIndexGeneration(snapshot);
+  const pages = buildKnowledgePages(knowledge, facts);
+  const sourceByRef = new Map(knowledge.sources.map(source => [sourcePageId(source), source] as const));
+  const outputs: Array<{ targetPath: string; body: string }> = [];
+  outputs.push({ targetPath: ".context/knowledge/index.md", body: `${frontmatter({ type: "knowledge-bundle-index", title: `${context.manifest.name} Knowledge`, project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${context.manifest.name} Knowledge\n\n## Sources\n\n${pages.filter(page => page.type === "source-summary").map(page => `- [${page.title}](./sources/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Entities\n\n${pages.filter(page => page.type === "entity").map(page => `- [${page.title}](./entities/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Concepts\n\n${pages.filter(page => page.type === "concept").map(page => `- [${page.title}](./concepts/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Requirements\n\n${pages.filter(page => page.type === "requirement").map(page => `- [${page.title}](./requirements/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Synthesis\n\n${pages.filter(page => page.type === "synthesis").map(page => `- [${page.title}](./synthesis/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Bugs / Fixes / Incidents / Lessons\n\n- [BUG 模板](./bugs/_template.md)\n- [FIX 模板](./fixes/_template.md)\n- [INCIDENT 模板](./incidents/_template.md)\n- [LESSON 模板](./lessons/_template.md)\n` });
+  outputs.push({ targetPath: ".context/knowledge/log.md", body: `${frontmatter({ type: "knowledge-log", title: "Knowledge Operation Log", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# Knowledge Operation Log\n\n- 初始化生成 OpenWiki 风格知识层。\n- 原始文档保持在项目原位置，source-summary 记录摘要和引用。\n- 代码事实来自 \`.planning/code-index/\`，桥接关系写入 \`.planning/knowledge-index.json\`。\n` });
+  outputs.push({ targetPath: ".context/knowledge/raw/README.md", body: `${frontmatter({ type: "raw-source-readme", title: "Raw Source Policy", project: context.manifest.name, status: "draft", managed: true })}# Raw Source Policy\n\n本目录保留给后续需要复制或归档的原始资料。当前初始化默认不复制原文，只在 source-summary 中记录原路径和内容哈希，避免制造第二份权威原文。\n` });
+  outputs.push(...bugKnowledgeTemplates(context, snapshotId, generation));
+  for (const page of pages) outputs.push({ targetPath: page.path, body: renderKnowledgePage(context, page, sourceByRef, snapshotId, generation) });
+  return { outputs, pages };
+}
+
 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);
@@ -333,7 +943,7 @@ function renderKnowledgeDocuments(context: ProjectContext, facts: Fact[], intro:
   return outputs;
 }
 
-function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, outputs: Array<{ targetPath: string }>, knowledge: DocumentKnowledge): { targetPath: string; body: string } {
+function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, outputs: Array<{ targetPath: string }>, knowledge: DocumentKnowledge, pages: KnowledgePage[]): { targetPath: string; body: string } {
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   const documents = outputs
@@ -341,8 +951,10 @@ function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown;
     .map(output => {
       const parts = output.targetPath.split("/");
       const file = parts.at(-1) ?? "";
-      const scope = parts[1] === "project" ? "project" : parts[1] === "requirements" ? "requirement" : "project";
+      const scope: IndexedDocumentScope = parts[1] === "project" ? "project" : parts[1] === "requirements" ? "requirement" : parts[1] === "knowledge" ? "knowledge" : "project";
       const type = output.targetPath === ".context/index.md" ? "knowledge-index"
+        : output.targetPath === ".context/knowledge/index.md" ? "knowledge-bundle-index"
+          : scope === "knowledge" ? `knowledge-${parts[2] === "log.md" ? "log" : parts[2] ?? "page"}`
         : scope === "project" ? `project-${file.replace(/\.md$/, "")}`
           : `requirement-${file.replace(/^requirement\.md$/, "requirements").replace(/\.md$/, "")}`;
       return {
@@ -366,11 +978,79 @@ function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown;
       codeIndexGeneration: generation ?? null,
       sourceDocuments: knowledge.sources,
       classifications: knowledge.classifications,
+      knowledgePages: pages.map(page => ({ id: page.id, path: page.path, type: page.type, status: page.status, sourceRefs: page.sourceRefs, relatedRequirements: page.relatedRequirements, relatedCodeFacts: page.relatedCodeFacts, confidence: page.confidence })),
       documents,
     }, null, 2)}\n`,
   };
 }
 
+function renderKnowledgeIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, knowledge: DocumentKnowledge, pages: KnowledgePage[], interfaces: InterfaceContract[]): { targetPath: string; body: string } {
+  const snapshotId = String(snapshot.id ?? "");
+  const generation = codeIndexGeneration(snapshot);
+  return {
+    targetPath: ".planning/knowledge-index.json",
+    body: `${JSON.stringify({
+      schemaVersion: 1,
+      project: context.manifest.name,
+      projectId: context.manifest.projectId,
+      sourceSnapshot: snapshotId,
+      codeIndexGeneration: generation ?? null,
+      bundleRoot: ".context/knowledge",
+      sourceDocuments: knowledge.sources,
+      classifications: knowledge.classifications,
+      pages: pages.map(page => ({
+        id: page.id,
+        path: page.path,
+        type: page.type,
+        title: page.title,
+        status: page.status,
+        sourceRefs: page.sourceRefs,
+        relatedRequirements: page.relatedRequirements,
+        relatedCodeFacts: page.relatedCodeFacts,
+        confidence: page.confidence,
+      })),
+      reservedBugKnowledgeNodes: [
+        { id: "BUG-TEMPLATE", path: ".context/knowledge/bugs/_template.md", type: "bug-report", purpose: "问题现象、影响、复现、根因和回归绑定模板" },
+        { id: "FIX-TEMPLATE", path: ".context/knowledge/fixes/_template.md", type: "bug-fix", purpose: "修复动作、变更原因、变更文件和回归覆盖模板" },
+        { id: "INC-TEMPLATE", path: ".context/knowledge/incidents/_template.md", type: "incident", purpose: "事故时间线、影响、缓解和后续行动模板" },
+        { id: "LESSON-TEMPLATE", path: ".context/knowledge/lessons/_template.md", type: "lesson", purpose: "可复用排障经验和检查规则模板" },
+      ],
+      interfaces: interfaces.map(item => ({ id: item.id, name: item.name, kind: item.kind, path: item.path, purpose: item.purpose, approval: item.approval, actions: item.actions.map(action => action.name) })),
+    }, null, 2)}\n`,
+  };
+}
+
+function renderInterfaceIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, interfaces: InterfaceContract[]): { targetPath: string; body: string } {
+  const snapshotId = String(snapshot.id ?? "");
+  const generation = codeIndexGeneration(snapshot);
+  return {
+    targetPath: ".planning/interface-index.json",
+    body: `${JSON.stringify({
+      schemaVersion: 1,
+      project: context.manifest.name,
+      projectId: context.manifest.projectId,
+      sourceSnapshot: snapshotId,
+      codeIndexGeneration: generation ?? null,
+      interfaces: interfaces.map(contract => ({
+        id: contract.id,
+        name: contract.name,
+        kind: contract.kind,
+        path: contract.path,
+        purpose: contract.purpose,
+        approval: contract.approval,
+        actions: contract.actions.map(action => ({
+          name: action.name,
+          purpose: action.purpose,
+          request: action.request,
+          response: action.response,
+          reads: action.reads,
+          writes: action.writes,
+        })),
+      })),
+    }, null, 2)}\n`,
+  };
+}
+
 export async function generateProjectDocuments(context: ProjectContext, snapshotId: string, options: { mode: DocumentGenerationMode; organizer?: LowTierDocumentOrganizer }): Promise<DocumentGenerationResult[]> {
   const store = await InitializationStore.open(context);
   try {
@@ -389,8 +1069,12 @@ export async function generateProjectDocuments(context: ProjectContext, snapshot
     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 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 openWiki = renderOpenWikiKnowledge(context, facts, snapshotMeta, knowledge);
+    const interfaces = renderInterfaceOutputs(context, snapshotMeta);
+    const outputs = [...renderDocuments(context, facts, organized.text, collections), ...renderKnowledgeDocuments(context, facts, organized.text, snapshotMeta, knowledge), ...openWiki.outputs, ...interfaces.outputs];
+    outputs.push(renderDocumentIndex(context, snapshotMeta, outputs, knowledge, openWiki.pages));
+    outputs.push(renderKnowledgeIndex(context, snapshotMeta, knowledge, openWiki.pages, interfaces.contracts));
+    outputs.push(renderInterfaceIndex(context, snapshotMeta, interfaces.contracts));
     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) });