@gordon.gan/specflow 1.8.0-beta → 1.8.1-beta

package/README.md

@@ -72,7 +72,7 @@ explore（可选）→ propose → refine → apply → review → test → veri
 │       ↓                                                                 │
 │  refine           ≥2 轮精化：挑战假设 / 新方案 / 探边界 / 质疑 scope     │
 │       ↓                                                                 │
-│  approval [可选]  AI 7 维闭环检查 + 设计质量 + 可实施性 → approval.md 供审批 │
+│  document [可选] 通用长文档引擎 → 方案文档（0→1 / bugfix / feature）      │
 │       ↓                                                                 │
 │  apply            Phase A 重写 tasks.md → Phase B 逐任务 TDD 执行         │
 │                   （可选 /specflow:apply --yes：少打断，成功后串行验收）   │
@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.7.0-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.8.0-alpha）
 specflow --help
 ```
 
@@ -259,14 +259,15 @@ specflow init
 
 ## IDE 工作流命令
 
-共 **11 个**技能，命名因 IDE 而异：
+共 **12 个**技能，命名因 IDE 而异：
 
 | 阶段 | Claude Code | Cursor | Codex |
 |------|-------------|--------|-------|
 | 探索（可选） | `/specflow:explore` | `specflow:explore` | `$specflow-explore` |
 | 规划 | `/specflow:propose` | `specflow:propose` | `$specflow-propose` |
 | 精化 | `/specflow:refine` | `specflow:refine` | `$specflow-refine` |
-| 审批（可选） | `/specflow:approval` | `specflow:approval` | `$specflow-approval` |
+| 方案文档（可选） | `/specflow:techdoc` | `specflow:techdoc` | `$specflow-techdoc` |
+| 跨仓方案（可选） | `/specflow:techdoc-synth` | `specflow:techdoc-synth` | `$specflow-techdoc-synth` |
 | 构建 | `/specflow:apply` | `specflow:apply` | `$specflow-apply` |
 | 审查 | `/specflow:review` | `specflow:review` | `$specflow-review` |
 | 测试 | `/specflow:test` | `specflow:test` | `$specflow-test` |
@@ -282,7 +283,8 @@ specflow init
 | **explore** | 读代码、比方案、定边界；产出 `explore.md`，confirmed 后 handoff 到 propose |
 | **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架）；叙述语言跟 `artifacts.language` |
 | **refine** | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact |
-| **approval** | refine 后可选：AI 7 维闭环 + 设计质量 + 可实施性 → `approval.md`；非轻量变更走 **ACP**：分片 `approval/parts/` → Stage 12e AI Review → **`specflow approval finalize`**。**多仓 mode A**：主仓 `/specflow:approval` 一次发起，Subagent 并行跑子仓 approval，主仓等待后 **`finalize --bundle`** 产出 `approval-unified.md`（各仓 `approval.md` 为 apply 真源） |
+| **techdoc** | 可选：`specflow techdoc run <0to1|frontend-0to1|bugfix|feature|poc|migration>` 用**通用长文档引擎**生成方案文档——**场景轴 × 技术栈轴正交**：场景管「做什么」（0→1 / 加功能 / 修 bug / 预研选型 / 技术升级），输入特征（hasBackend / uiInScope / containsApiChange / hasPersistence）自动决定章节伸缩（纯逻辑功能 ~3 章，全栈功能 ~10 章）。两遍扫描（Pass 1 大纲冻结 → Pass 2 逐章按要点填空）+ 分层真源（契约实体 zod + 受控叙述）+ 四层上下文注入（大纲要点 + 依赖摘要 + 契约注入 + 本片片段，保证注意力不稀释 / token 不易打满）+ 覆盖双通道校验 + AI Review。审批文档走独立入口 `techdoc approve`（四件套 → 审批模式，非业务场景）。详见 `docs/GENERIC_LONGDOC_ENGINE_DESIGN.md` |
+| **techdoc-synth** | 可选：`specflow techdoc synthesize --workspace-root <root>` 把多仓四件套合成**一份跨仓文档**（统一大纲 + 契约实体命名空间 `<repo>_<id>` + 每章按仓分节 + 全局结论）；省略 `--profile` 时自动识别场景（`--text` 优先，其次四件套内容；不确定且有 `--text` 时确认，无 `--text` 时回退 approve）。带确定性质量门禁（validate 强制每必选章含所有仓 `### <repo>` 小节）。区别于 `techdoc approve --bundle` 的物理拼接；原有多仓多产物不受影响 |
 | **apply** | Phase A 重写 tasks.md；Phase B 按语言路由 ECC 审查 + TDD 逐任务执行；可选 `--yes` |
 | **review** | 代码审查，对照 specs 检查回归 |
 | **test** | 单元 + 集成 + E2E + 回归测试 |

package/dist/cli/commands/document-run.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CLI: specflow techdoc {plan|validate|run} — Generic LongDoc Engine, IDE-model driven.
+ *
+ * The engine does NOT call a third-party LLM API. In Cursor/Codex the Agent runs on the IDE's
+ * model, so:
+ *   - `document plan <profile>` emits a step list the Agent executes with the IDE model.
+ *   - `document validate --work-root <path>` deterministically validates + renders Agent-written
+ *     artifacts (outline.yaml / chapters/*.md / entities.json) — no LLM call.
+ *   - `document run <profile>` guides: plan → Agent executes → validate (requires injected LLM only
+ *     for library/tests; CLI itself never fetches an API).
+ */
+import type { Command } from 'commander';
+import type { DocumentLLM } from '../../core/document/llm.js';
+export interface DocumentPlanOptions {
+    text?: string;
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    tasks?: string;
+    code?: string;
+    workRoot?: string;
+    json?: boolean;
+    markdown?: boolean;
+    signoff?: boolean;
+}
+export interface DocumentValidateOptions {
+    workRoot?: string;
+    json?: boolean;
+    noRender?: boolean;
+}
+export declare function planDocumentCommand(profileId: string, options: DocumentPlanOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function validateDocumentCommand(options: DocumentValidateOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function injectLLM(llm: DocumentLLM): void;
+export declare function runDocumentCommand(profileId: string | undefined, options: {
+    text?: string;
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    code?: string;
+    workRoot?: string;
+    json?: boolean;
+    signoff?: boolean;
+} & {
+    skipReview?: boolean;
+    maxRounds?: number;
+}): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function detectDocumentCommand(options: {
+    text?: string;
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    code?: string;
+    json?: boolean;
+}): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export interface ApproveOptions {
+    proposal?: string;
+    specs?: string;
+    design?: string;
+    tasks?: string;
+    change?: string;
+    workspaceRoot?: string;
+    changes?: string;
+    workRoot?: string;
+    signoff?: boolean;
+    bundle?: boolean;
+    json?: boolean;
+}
+export declare function approveDocumentCommand(options: ApproveOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export interface SynthesizeOptions {
+    workspaceRoot: string;
+    changes?: string;
+    profile?: string;
+    text?: string;
+    workRoot?: string;
+    signoff?: boolean;
+    json?: boolean;
+}
+export declare function synthesizeDocumentCommand(options: SynthesizeOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function registerDocumentRunCommand(program: Command): void;