ai-spec-dev 0.14.1 → 0.17.0

package/README.md

@@ -338,9 +338,13 @@ ai-spec init --force
 
 #### Constitution Rebase — 为什么需要定期整合
 
-`ai-spec review` 每次运行后会把审查 issue 追加到宪法 §9。长期运行后 §9 会积累大量条目（重复措辞、已修复问题、不再适用的早期教训）。宪法被注入每次 AI 调用，超过 2000 字符后会被硬截断，越积越多反而降低效果。
+`ai-spec review` 每次运行后会把审查 issue 追加到宪法 §9。长期运行后 §9 会积累大量条目（重复措辞、已修复问题、不再适用的早期教训）。宪法全文注入每次 AI 调用——内容越长，AI 对中间章节的注意力越分散，效果反而下降。当宪法超过 6,000 字符时，CLI 会自动显示警告提示整合。
 
-**建议频率**：§9 达到 8 条以上时（系统会自动提示），运行一次整合。
+**建议频率**：§9 达到 8 条以上时（系统会自动提示），或出现以下警告时，运行一次整合：
+
+```
+⚠ Constitution is long (8,432 chars). Consider running: ai-spec init --consolidate
+```
 
 ```bash
 # 预览效果（不写入）
@@ -996,7 +1000,7 @@ specs/
   ~ src/routes/client/index.ts... ✔
 ```
 
-**跨 Task 一致性保障**：每个 task 完成后，写入的 `src/api*` / `src/service*` / `src/store*` / `src/composable*` 文件会被读回并缓存；后续 task 在 prompt 中可以看到这些文件的实际导出内容，确保路由/组件层 import 使用的函数名与 API 层一致（不再出现 `getTasks` vs `getTaskList` 的跨 task 幻觉）。当前 task 创建新路由模块文件时，也会自动携带对应 `routes/index.ts` 的精确注册指令。
+**跨 Task 一致性保障**：每个 task 完成后，写入的 `src/api*` / `src/service*` / `src/store*` / `src/composable*` 文件会被读回并缓存；后续 task 的 prompt 中注入这些文件的**所有 export 声明行**（而非前 N 字符的截断），确保路由/组件层 import 使用的函数名与 API 层完全一致（不再出现 `getTasks` vs `getTaskList` 的跨 task 幻觉）。当前 task 创建新路由模块文件时，也会自动携带对应 `routes/index.ts` 的精确注册指令。
 
 **分页参数 ground-truth 注入**：`frontend-context-loader` 自动扫描 `src/apis/`（及 `src/api/`、`src/services/` 等）中现有的 API 文件，找到包含分页字段（`pageIndex`/`pageSize`/`pageNum`/`current` 等）的 interface 及对应导出函数，作为 `paginationExample` 注入 prompt，并标注 "COPY THIS EXACTLY"。生成的列表接口将与项目现有接口使用完全相同的分页参数名称和 HTTP 方法（POST body 或 GET query）。
 

package/RELEASE_LOG.md

@@ -2,6 +2,51 @@
 
 ---
 
+## [0.17.0] 2026-03-24 — 宪法全文注入 · Export 精准缓存 · 宪法长度警告
+
+### 1. 宪法全文注入（移除硬截断）
+
+**问题**：宪法在所有 prompt 中存在硬截断（`codegen`/`task-generator`/`spec-assessor`/`update` 各处分别为 1500–2000 字符），§9 最新教训恰好位于宪法末尾，最容易被截掉——工具越用越长的宪法反而越来越被忽视。
+
+**修复**（涉及 6 处）：
+- `core/code-generator.ts` — 代码生成 prompt 中的宪法注入
+- `cli/index.ts` — update 命令中的宪法注入
+- `prompts/update.prompt.ts` — update prompt 构建函数
+- `core/task-generator.ts` — task 生成 prompt
+- `core/spec-assessor.ts` — Spec 质量评估 prompt
+- `core/context-loader.ts` — 项目文件预览从 800 → 2000 字符
+
+现代模型（Claude/Gemini/Qwen3）上下文窗口充足，宪法通常 3000–8000 字符，全文注入不会造成负担，但能确保 §9 始终被 AI 读到。
+
+### 2. Generated File Cache — Export 精准提取
+
+**问题**：跨 task 一致性保障依赖 `generatedFileCache`，原实现截取每个缓存文件的前 800 字符注入后续 task prompt。对于超过 30 行的 service/api 文件，大量 export 函数名落在 800 字符之外，跨 task 函数名幻觉问题依然存在于大文件场景。
+
+**修复**（`core/code-generator.ts`）：新增 `extractExportSignatures()` 函数，从文件全文中提取**所有以 `export` 开头的声明行**，注入后续 task prompt。无论文件长度，所有导出名称完整可见；对无显式 export 的文件（CommonJS）回退到前 3000 字符。
+
+```typescript
+// Before: 取前 800 字符，大文件的 export 被截掉
+content.slice(0, 800)
+
+// After: 提取所有 export 声明行，精准且不浪费 token
+export function getUserList(...): Promise<...>
+export function createUser(...): Promise<...>
+export const updateUser = ...
+// ...全部导出，不含实现细节
+```
+
+### 3. 宪法长度警告
+
+**新增**：当宪法超过 **6,000 字符**时，`create` / `update` / workspace 各命令加载上下文后自动输出提示：
+
+```
+⚠ Constitution is long (8,432 chars). Consider running: ai-spec init --consolidate
+```
+
+设计原则：不阻断流程，纯提示性；帮助用户在宪法真正影响 AI 注意力之前主动整合，而不是等到效果已经变差才发现。
+
+---
+
 ## [0.16.0] 2026-03-24 — Spec 质量预评估 · 分层代码审查 · TDD 模式
 
 ### 1. Spec 质量预评估（`core/spec-assessor.ts`, `prompts/spec-assess.prompt.ts`）

package/cli/index.ts

@@ -86,6 +86,22 @@ async function loadConfig(dir: string): Promise<AiSpecConfig> {
   return {};
 }
 
+// ─── Constitution Length Warning ──────────────────────────────────────────────
+
+const CONSTITUTION_WARN_CHARS = 6000;
+
+function warnIfConstitutionLong(context: { constitution?: string }): void {
+  if (!context.constitution) return;
+  const len = context.constitution.length;
+  if (len > CONSTITUTION_WARN_CHARS) {
+    console.log(
+      chalk.yellow(
+        `    ⚠ Constitution is long (${len.toLocaleString()} chars). Consider running: ai-spec init --consolidate`
+      )
+    );
+  }
+}
+
 // ─── API Key Resolution ────────────────────────────────────────────────────────
 
 async function resolveApiKey(
@@ -247,6 +263,7 @@ program
     const { type: detectedRepoType } = await detectRepoType(currentDir);
     console.log(chalk.gray(`  Tech stack  : ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
     console.log(chalk.gray(`  Dependencies: ${context.dependencies.length} packages`));
+    warnIfConstitutionLong(context);
     console.log(chalk.gray(`  API files   : ${context.apiStructure.length} files`));
     if (context.schema) {
       console.log(chalk.gray(`  Prisma schema: found`));
@@ -1038,6 +1055,7 @@ async function runSingleRepoPipelineInWorkspace(opts: {
 
   console.log(chalk.gray(`    Tech stack: ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
   console.log(chalk.gray(`    Dependencies: ${context.dependencies.length} packages`));
+  warnIfConstitutionLong(context);
 
   if (!context.constitution) {
     console.log(chalk.yellow(`    Constitution: not found — auto-generating...`));
@@ -1221,6 +1239,7 @@ async function runMultiRepoPipeline(
     try {
       const loader = new ContextLoader(repoAbsPath);
       const ctx = await loader.loadProjectContext();
+      warnIfConstitutionLong(ctx);
       contexts.set(repo.name, ctx);
 
       // Load frontend context for frontend/mobile repos
@@ -1684,6 +1703,7 @@ program
     console.log(chalk.gray("  Loading project context..."));
     const loader = new ContextLoader(currentDir);
     const context = await loader.loadProjectContext();
+    warnIfConstitutionLong(context);
 
     // ── Detect repo type ──────────────────────────────────────────────────────
     const { detectRepoType: _detectRepoType } = await import("../core/workspace-loader");
@@ -1728,7 +1748,7 @@ program
 
       const specContent = await fs.readFile(result.newSpecPath, "utf-8");
       const constitutionSection = context.constitution
-        ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution.slice(0, 2000)}\n`
+        ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution}\n`
         : "";
       const dslSection = result.updatedDsl
         ? `\n=== DSL Context ===\n${JSON.stringify(result.updatedDsl, null, 2).slice(0, 3000)}\n`

package/core/code-generator.ts

@@ -38,6 +38,25 @@ function buildInstalledPackagesSection(context?: ProjectContext): string {
  * Injected before generating files that may import from those paths (e.g., route files
  * importing from API files generated in an earlier task).
  */
+/**
+ * Extract all export declaration lines from a file's content.
+ * This gives precise signal about every exported name without including
+ * implementation details, and works regardless of file length.
+ * Falls back to first 3000 chars for CommonJS or files with no explicit exports.
+ */
+function extractExportSignatures(content: string): string {
+  const exportLines = content
+    .split("\n")
+    .filter((line) => line.trimStart().startsWith("export "));
+
+  if (exportLines.length > 0) {
+    return exportLines.join("\n");
+  }
+
+  // Fallback for CommonJS or files without top-level export keywords
+  return content.slice(0, 3000) + (content.length > 3000 ? "\n... (truncated)" : "");
+}
+
 function buildGeneratedFilesSection(cache: Map<string, string>): string {
   if (cache.size === 0) return "";
   const lines = [
@@ -45,9 +64,7 @@ function buildGeneratedFilesSection(cache: Map<string, string>): string {
   ];
   for (const [filePath, content] of cache) {
     lines.push(`\n--- ${filePath} ---`);
-    // Include enough to see all export names (first 800 chars covers most API files)
-    lines.push(content.slice(0, 800));
-    if (content.length > 800) lines.push("... (truncated)");
+    lines.push(extractExportSignatures(content));
   }
   return lines.join("\n") + "\n";
 }
@@ -308,7 +325,7 @@ export class CodeGenerator {
 
     const spec = await fs.readFile(specFilePath, "utf-8");
     const constitutionSection = context?.constitution
-      ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution.slice(0, 2000)}\n`
+      ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution}\n`
       : "";
     const contextSummary = context
       ? `Tech Stack: ${context.techStack.join(", ")}\nExisting files: ${context.fileStructure.slice(0, 20).join(", ")}`

package/core/context-loader.ts

@@ -244,7 +244,7 @@ export class ContextLoader {
       for (const f of propFiles.slice(0, 2)) {
         try {
           const content = await fs.readFile(path.join(this.projectRoot, f), "utf-8");
-          parts.push(`// ${f}\n${content.slice(0, 800)}`);
+          parts.push(`// ${f}\n${content.slice(0, 2000)}`);
         } catch { /* skip */ }
       }
       if (parts.length > 0) context.routeSummary = parts.join("\n\n");

package/core/spec-assessor.ts

@@ -54,7 +54,7 @@ export async function assessSpec(
   constitution?: string
 ): Promise<SpecAssessment | null> {
   const prompt = `Assess the following feature specification.
-${constitution ? `\n=== Project Constitution (check consistency against this) ===\n${constitution.slice(0, 1500)}\n` : ""}
+${constitution ? `\n=== Project Constitution (check consistency against this) ===\n${constitution}\n` : ""}
 === Feature Spec ===
 ${spec}`;
 

package/core/task-generator.ts

@@ -53,7 +53,7 @@ export function buildTaskPrompt(spec: string, context?: ProjectContext): string
   const parts: string[] = [spec];
 
   if (context.constitution) {
-    parts.push(`\n=== Project Constitution (rules to follow) ===\n${context.constitution.slice(0, 1500)}`);
+    parts.push(`\n=== Project Constitution (rules to follow) ===\n${context.constitution}`);
   }
 
   if (context.techStack.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.14.1",
+  "version": "0.17.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/prompts/update.prompt.ts

@@ -41,7 +41,7 @@ export function buildSpecUpdatePrompt(
   context?: ProjectContext
 ): string {
   const constitutionSection = context?.constitution
-    ? `\n=== Project Constitution (all changes must comply) ===\n${context.constitution.slice(0, 1500)}\n`
+    ? `\n=== Project Constitution (all changes must comply) ===\n${context.constitution}\n`
     : "";
 
   const dslSummary = existingDsl