diff --git a/.Knowledge/topics/kb-routing-summary.md b/.Knowledge/topics/kb-routing-summary.md index f577ce7..93e24d1 100644 --- a/.Knowledge/topics/kb-routing-summary.md +++ b/.Knowledge/topics/kb-routing-summary.md @@ -27,6 +27,7 @@ confidence: manual - 写法规范（软 30 字 / 硬 40 字、职责 + 用户会问的核心名词、`includeAny` 单概念词优先、落盘前模拟问句自测）以 `f2s-topic-authoring`「初筛召回规范」为准，本 topic 不复述。 - 存量修复走 `f2s-kb-upgrade` 完整流程步骤 3a.7 / 3a.8：`kb build --fix-topics` 补占位头部 → `kb check --strict` 报 summary warning → agent 逐个 Read 正文补写语义摘要 → `kb build` 同步进 `rule.summary`。 +- `f2s-kb-upgrade` 步骤 -1 的 A 分支（包侧均为最新）**不得直接停止**：须先做项目侧对齐检查（manifest `version`/`pkgRev` 对比包 Template Version + `kb check --strict`），未对齐视同 Template 更新转完整流程；否则刚升完包的老项目会被误判「无事可做」跳过 summary 补写。 ## 边界 diff --git a/README.en.md b/README.en.md index 20e0352..8246f44 100644 --- a/README.en.md +++ b/README.en.md @@ -26,7 +26,14 @@ Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository. ```bash -npx @double-coding/flow2spec@latest init +# Recommended: install globally, then initialize +# (keeps the `flow2spec` command available for kb maintenance and upgrades) +npm install -g @double-coding/flow2spec +flow2spec init + +# One-off trial without installing (always resolves the latest version): +# npx @double-coding/flow2spec@latest init + # Native DeepSeek Harness plugin: # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness # Project-level adapter without the plugin: diff --git a/README.md b/README.md index 69bea71..de3ccbf 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,14 @@ Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository. ```bash -npx @double-coding/flow2spec@latest init +# Recommended: install globally, then initialize +# (keeps the `flow2spec` command available for kb maintenance and upgrades) +npm install -g @double-coding/flow2spec +flow2spec init + +# One-off trial without installing (always resolves the latest version): +# npx @double-coding/flow2spec@latest init + # Native DeepSeek Harness plugin: # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness # Project-level adapter without the plugin: diff --git a/README.zh-CN.md b/README.zh-CN.md index 99a2e66..7b6deff 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -26,7 +26,13 @@ Flow2Spec 是给 AI 编码工具使用的 Spec-driven 工作流层。它会在项目里建立小而可路由的 `.Knowledge/` 知识库，安装面向 agent 的 `f2s-*` 技能，并把可选的本地任务状态和产品知识分开保存。新的会话可以按需求加载相关事实，而不是重新翻完整个仓库。 ```bash -npx @double-coding/flow2spec@latest init +# 推荐：全局安装后初始化（保留 flow2spec 命令，便于后续知识库维护与升级） +npm install -g @double-coding/flow2spec +flow2spec init + +# 免安装一次性体验（始终解析最新版）： +# npx @double-coding/flow2spec@latest init + # DeepSeek Harness 原生插件： # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness # 未装插件时的项目级适配： diff --git "a/docs/Flow2Spec\345\237\272\347\241\200\344\273\213\347\273\215.md" "b/docs/Flow2Spec\345\237\272\347\241\200\344\273\213\347\273\215.md" index d9ba445..0959d2b 100644 --- "a/docs/Flow2Spec\345\237\272\347\241\200\344\273\213\347\273\215.md" +++ "b/docs/Flow2Spec\345\237\272\347\241\200\344\273\213\347\273\215.md" @@ -422,7 +422,8 @@ Flow2Spec 提供三个互补命令，按触发方式与粒度区分： **5 分钟快速体验**： ```Plain Text -npx @double-coding/flow2spec@latest init +npm install -g @double-coding/flow2spec +flow2spec init ``` @@ -459,7 +460,8 @@ Flow2Spec 做的事，是把项目知识整理成可路由、可依赖、可验 - 文档和代码开始不同步。 ```Plain Text -npx @double-coding/flow2spec@latest init +npm install -g @double-coding/flow2spec +flow2spec init ``` 开源地址：`https://github.com/double-coding-lab/Flow2Spec` diff --git a/docs/en/Flow2Spec-Introduction.md b/docs/en/Flow2Spec-Introduction.md index 0476e14..c057fd8 100644 --- a/docs/en/Flow2Spec-Introduction.md +++ b/docs/en/Flow2Spec-Introduction.md @@ -438,7 +438,8 @@ In short: **single Q&A → distill (auto), new module bulk import → add, perio **5-minute quick start**: ```Plain Text -npx @double-coding/flow2spec@latest init +npm install -g @double-coding/flow2spec +flow2spec init ``` @@ -475,7 +476,8 @@ If your project already has these problems, try it in one repository first: - documentation and code have started to drift apart. ```Plain Text -npx @double-coding/flow2spec@latest init +npm install -g @double-coding/flow2spec +flow2spec init ``` Repository: `https://github.com/double-coding-lab/Flow2Spec` diff --git a/docs/en/upgrade-guide.md b/docs/en/upgrade-guide.md new file mode 100644 index 0000000..b0c440b --- /dev/null +++ b/docs/en/upgrade-guide.md @@ -0,0 +1,120 @@ +# Flow2Spec Upgrade Guide (CLI 3.6.1 / Core 3.7.1 / Template 3.6.1) + +> Highlight of this release: **routing-summary recall anchors**. Every routing rule in `manifest-routing.json` now carries a `summary` semantic digest (synced automatically from topic frontmatter), which greatly improves knowledge-base hit rates for natural phrasings such as "where are the prototypes" or "which folder holds the flowcharts". `kb check` gains summary quality validation accordingly. + +## Version matrix + +| Dimension | Latest | Notes | +| --- | --- | --- | +| CLI (`@double-coding/flow2spec`) | 3.6.1 | `kb check` prints warning details | +| Core (`@double-coding/flow2spec-core`) | 3.7.1 | summary sync engine + quality validation; upgrade-skill project-side alignment check | +| Template Version | 3.6.1 | templates carry topic-layer changes (projectRev 3) | +| Qoder plugin | 3.7.1 | self-built (`npm run build:qoder-plugin`), named after the Core version | + +--- + +## New users (first-time setup) + +### Option 1: CLI (Codex / Cursor / Claude / DSH) + +```bash +npm install -g @double-coding/flow2spec +flow2spec init # multi-select, follow the prompts +``` + +Installing the CLI automatically brings the latest compatible Core (`^3.6.0` → 3.7.1); no separate install is needed. After init you are on the latest knowledge-base templates with summary-based first-pass recall built in — nothing extra to do. + +### Option 2: Qoder plugin (self-built install) + +The Qoder plugin marketplace hosts official plugins only; build the Flow2Spec plugin yourself and install it locally: + +1. Clone the repository and build the plugin package: + + ```bash + git clone https://github.com/double-coding-lab/Flow2Spec.git + cd Flow2Spec && npm install && npm run build:qoder-plugin + # produces output/flow2spec-3.7.1.zip + ``` + +2. In Qoder's plugin management, choose local install and import the zip; +3. On first use in a project, run `flow2spec init plugin` as prompted (plugin mode: initializes only the knowledge base and config, writes no client directories). + +Then tell the agent things like "f2s-kb-build / f2s-kb-add" to start building the knowledge base. + +--- + +## Existing users (projects with `.Knowledge`) + +Template 3.5.0 → 3.6.x **includes topic-layer changes** (projectRev 2 → 3), so updating the packages alone is not enough — run one knowledge-base upgrade. Three steps: + +### Step 1: Update the packages + +Check current versions and available updates: + +```bash +flow2spec version +flow2spec update --check +``` + +Two cases depending on your current CLI: + +- **CLI is already 3.6.x**: run `flow2spec update --core` to get Core 3.7.1 (inside the `^3.6.0` range); if your CLI is below 3.6.1, also run `flow2spec update --cli` (its `kb check` prints warning details, handy for watching step 2 progress). +- **CLI below 3.6.0**: reinstall the latest: + + ```bash + npm install -g @double-coding/flow2spec@latest + ``` + +**Qoder plugin users**: pull the latest code and rebuild the plugin package (`npm run build:qoder-plugin`, producing `output/flow2spec-3.7.1.zip`), then re-import it in Qoder's plugin management; no global npm package needed. + +### Step 2: Knowledge-base upgrade (the key step — let the agent do it) + +In your project session, tell the agent: + +```text +f2s-kb-upgrade +``` + +The agent runs the full flow. The parts relevant to this release: + +1. Runs `flow2spec init` to align the routing manifest and templates (**incremental — it never overwrites your accumulated business knowledge**); +2. `kb build --fix-topics` fills in frontmatter skeletons for existing topics; +3. **Summary rewrite (new in this release)**: `kb check --strict` lists every missing/placeholder topic summary; the agent reads each topic body, writes a one-line semantic summary per the authoring rules, then `kb build` syncs it into the routing manifest — only after this step does your existing knowledge base gain the first-pass recall boost; +4. Writes back `projectRev` and prints an upgrade summary. + +No manual edits to any `.Knowledge` file are needed. + +### Step 3: Verify + +```bash +flow2spec version # CLI 3.6.1 / Core 3.7.1 / Template 3.6.1 +flow2spec kb check --strict # expect: knowledge check: ok, no summary warnings +``` + +Then try one natural question (e.g. "where do the prototypes / requirement docs of this project live") and confirm the agent hits the right topic. + +--- + +## FAQ + +**Q: Will the upgrade overwrite the knowledge base I already wrote?** +No. The init run by `f2s-kb-upgrade` is incremental and only updates template-owned routing structure and rules; your business content in `stock-docs` / `req-docs` / topic bodies is untouched. `--reset-knowledge` is used only when you explicitly ask for an overwrite reset. + +**Q: Can I just update the packages and skip `f2s-kb-upgrade`?** +The engine capabilities (summary sync, validation) take effect, but your existing topics have no summaries, so first-pass recall does not improve — and `kb check` will keep reporting placeholder/missing warnings. Run the upgrade soon after updating the packages. + +**Q: My project is still on the very old V1 layout (no `.Knowledge/manifest-routing.json` shards)?** +V1 auto-migration has been removed from the package. First do a one-time migration with the historical `@double-coding/flow2spec@3.4.x` (or move things into the `.Knowledge` shape manually), then run `f2s-kb-upgrade` on the latest version. + +**Q: I told the agent `f2s-kb-upgrade` and it just replied "everything is up to date" and did nothing?** +A known misjudgment in older skills (Template ≤ 3.6.0): they only compared "installed packages vs npm" and never checked "project knowledge base vs package templates" — an old project right after a package upgrade hits exactly this. Fixed since Template 3.6.1 (a project-side alignment check is now mandatory before stopping). If you hit it during the first upgrade of an old project, just be more explicit: + +```text +f2s-kb-upgrade, force the full flow: run flow2spec init first, then kb build --fix-topics and kb check --strict, and rewrite summaries per 3a.8 +``` + +**Q: After upgrading, git shows lots of changes under `.cursor/` and `.codex/` — is that normal?** +Yes. Those are real updates to rule and skill bodies in the new templates (including the wholesale removal of `f2s-kb-migrate`), not empty diffs; use `git diff -w` to verify. The upgrade only touches `.Knowledge/`, the agent config roots (`.cursor/` `.codex/` etc.), `AGENTS.md`, and `flow2spec.config.json` — **never your business source code**; commit the upgrade changes separately from business changes. Also, the manifest `version` is the Template Version (3.6.1 after upgrading) and will not equal the Core version — that is expected. + +**Q: After upgrading, my commit is blocked by `kb check` reporting routing drift?** +The manifest and topics are out of sync (usually after hand-editing the manifest). Ask the agent to run `flow2spec kb build` once (idempotent) and it self-heals. diff --git "a/docs/\345\215\207\347\272\247\346\214\207\345\215\227.md" "b/docs/\345\215\207\347\272\247\346\214\207\345\215\227.md" new file mode 100644 index 0000000..e70f549 --- /dev/null +++ "b/docs/\345\215\207\347\272\247\346\214\207\345\215\227.md" @@ -0,0 +1,120 @@ +# Flow2Spec 升级指南（CLI 3.6.1 / Core 3.7.1 / Template 3.6.1） + +> 本次版本核心能力：**路由初筛 summary 召回锚**。`manifest-routing.json` 的每条路由规则新增 `summary` 语义摘要（由 topic frontmatter 自动同步），大幅提升自然问法（如「原型放在哪」「流程图在哪个目录」）的知识库命中率；`kb check` 同步新增 summary 质量校验。 + +## 版本对照 + +| 维度 | 最新版本 | 说明 | +| --- | --- | --- | +| CLI（`@double-coding/flow2spec`） | 3.6.1 | `kb check` 输出 warning 明细 | +| Core（`@double-coding/flow2spec-core`） | 3.7.1 | summary 同步引擎 + 质量校验；升级技能项目侧对齐检查 | +| Template Version | 3.6.1 | 模板含主题层变更（projectRev 3） | +| Qoder 插件 | 3.7.1 | 自行构建（`npm run build:qoder-plugin`），随 Core 版本号命名 | + +--- + +## 新用户（首次接入） + +### 方式一：CLI（Codex / Cursor / Claude / DSH） + +```bash +npm install -g @double-coding/flow2spec +flow2spec init # 可多选，按提示回答 +``` + +安装 CLI 会自动带上兼容的最新 Core（`^3.6.0` → 3.7.1），无需单独安装。init 完成后即为最新知识库模板，天然具备 summary 初筛能力，无需额外操作。 + +### 方式二：Qoder 插件（自行构建安装） + +Qoder 插件市场为官方插件，Flow2Spec 插件需自行构建后本地安装： + +1. 克隆仓库并构建插件包： + + ```bash + git clone https://github.com/double-coding-lab/Flow2Spec.git + cd Flow2Spec && npm install && npm run build:qoder-plugin + # 产出 output/flow2spec-3.7.1.zip + ``` + +2. 在 Qoder 插件管理中选择本地安装，导入该 zip； +3. 首次在项目中使用时按提示执行 `flow2spec init plugin`（插件模式：仅初始化知识库与配置，不写任何客户端目录）。 + +初始化后按需对 agent 说「f2s-kb-build / f2s-kb-add」等开始沉淀知识库。 + +--- + +## 老用户（已有 `.Knowledge` 项目） + +本次 Template 3.5.0 → 3.6.0 **包含主题层变更**（projectRev 2 → 3），因此不能只更新包，需要走一次知识库升级。分三步： + +### 第 1 步：更新包 + +先看当前版本与可用更新： + +```bash +flow2spec version +flow2spec update --check +``` + +按当前 CLI 版本分两种情况： + +- **CLI 已是 3.6.x**：执行 `flow2spec update --core` 更新 Core 到 3.7.1（在 `^3.6.0` 兼容范围内）；若 CLI 低于 3.6.1，建议再 `flow2spec update --cli` 升到 3.6.1（`kb check` 可打印 warning 明细，便于第 2 步观察补写进度）。 +- **CLI 低于 3.6.0**：直接重装最新： + + ```bash + npm install -g @double-coding/flow2spec@latest + ``` + +**Qoder 插件用户**：拉取最新代码重新构建插件包（`npm run build:qoder-plugin`，产出 `output/flow2spec-3.7.1.zip`），在 Qoder 插件管理中重新导入即可，无需操作 npm 全局包。 + +### 第 2 步：知识库升级（关键，交给 agent 做） + +在项目会话中对 agent 说： + +```text +f2s-kb-upgrade +``` + +agent 会代跑完整流程，其中与本次版本直接相关的是： + +1. 代跑 `flow2spec init` 对齐路由清单与模板（**增量落盘，不覆盖你已沉淀的业务知识**）； +2. `kb build --fix-topics` 为存量 topic 补齐 frontmatter 骨架； +3. **summary 补写（本版新增）**：`kb check --strict` 会列出所有缺失 / 占位的 topic 摘要，agent 逐个阅读 topic 正文、按创作规范补写一句话语义摘要，再 `kb build` 同步进路由清单——这一步完成后，你的存量知识库才真正获得初筛召回增强； +4. 回写 `projectRev`，输出升级摘要。 + +全程无需手动改任何 `.Knowledge` 文件。 + +### 第 3 步：验证 + +```bash +flow2spec version # CLI 3.6.1 / Core 3.7.1 / Template 3.6.1 +flow2spec kb check --strict # 期望：knowledge check: ok，无 summary warning +``` + +再用一句自然问法试试路由（例如问「这个项目的原型 / 需求文档放在哪」），确认 agent 能命中对应 topic。 + +--- + +## 常见问题 + +**Q：升级会覆盖我已经写好的知识库吗？** +不会。`f2s-kb-upgrade` 代跑的 init 是增量对齐，只更新模板承载的路由结构与规则；`stock-docs` / `req-docs` / topic 正文的业务内容不受影响。只有明确要求「覆盖重置」时才会带 `--reset-knowledge`。 + +**Q：不跑 `f2s-kb-upgrade`，只更新包行不行？** +引擎能力（summary 同步、校验）会生效，但你的存量 topic 没有摘要，初筛命中率不会提升；且首次 `kb check` 会持续报占位 / 缺失 warning。建议升级包后尽快跑一次。 + +**Q：我的项目还是很老的 V1 布局（无 `.Knowledge/manifest-routing.json` 分片结构）怎么办？** +V1 自动迁移已随包移除。先用历史版本 `@double-coding/flow2spec@3.4.x` 完成一次性迁移（或手动迁入 `.Knowledge` 形态），再回到最新版本跑 `f2s-kb-upgrade`。 + +**Q：对 agent 说 `f2s-kb-upgrade`，它回复「版本均为最新」就停了，什么都没做？** +这是旧版技能（Template ≤ 3.6.0）的已知误判：它只比对了「本机包 vs npm」，没检查「项目知识库 vs 包模板」——刚升完包的老项目恰好命中。Template 3.6.1 起已修复（停止前强制项目侧对齐检查）。老项目首次升级时若遇到，说得更明确即可绕过： + +```text +f2s-kb-upgrade，强制走完整流程：先代跑 flow2spec init，再 kb build --fix-topics 和 kb check --strict，按 3a.8 补写 summary +``` + +**Q：升级后 git 里 `.cursor/`、`.codex/` 出现大量文件变化，正常吗？** +正常。这些是新模板的规则与技能正文真实更新（含已移除的 `f2s-kb-migrate` 整文件删除），不是空改动；可用 `git diff -w` 验证实质变更占比。升级只会动 `.Knowledge/`、各 agent 配置根（`.cursor/` `.codex/` 等）、`AGENTS.md`、`flow2spec.config.json`，**不碰业务源码**；建议把升级改动与业务改动分开提交。另外 manifest 的 `version` 是 Template Version（升级后为 3.6.1），不会等于 Core 版本号，属正常现象。 + +**Q：升级后提交代码被 `kb check` 拦住报 routing drift？** +说明 manifest 与 topic 不同步（常见于手改过 manifest）。让 agent 跑一次 `flow2spec kb build`（幂等）即可自愈。 diff --git a/package-lock.json b/package-lock.json index 18b71de..673d467 100644 --- a/package-lock.json +++ b/package-lock.json @@ -39,7 +39,7 @@ }, "packages/core": { "name": "@double-coding/flow2spec-core", - "version": "3.7.0", + "version": "3.7.1", "license": "ISC", "engines": { "node": ">=16" diff --git a/packages/cli/README.md b/packages/cli/README.md index 69bea71..de3ccbf 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -26,7 +26,14 @@ Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository. ```bash -npx @double-coding/flow2spec@latest init +# Recommended: install globally, then initialize +# (keeps the `flow2spec` command available for kb maintenance and upgrades) +npm install -g @double-coding/flow2spec +flow2spec init + +# One-off trial without installing (always resolves the latest version): +# npx @double-coding/flow2spec@latest init + # Native DeepSeek Harness plugin: # https://github.com/double-coding-lab/Flow2Spec-DeepSeek-Harness # Project-level adapter without the plugin: diff --git a/packages/core/README.md b/packages/core/README.md index e8c1ce4..ace4fc2 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -27,4 +27,4 @@ const versions = getVersions(); - `update.check()` 复用 `.Knowledge/update-check.json` 的每日缓存，分别返回 Core 与 Template 更新状态；网络不可用时返回 `unavailable`，不会阻断宿主。 - `capabilities.json` 的 `protocolVersion` 用于插件启动时执行能力兼容校验。 -包通过 `index.d.ts` 导出完整公共契约类型。普通 CLI 用户继续使用 `npx @double-coding/flow2spec init`，无需直接调用这些 API。 +包通过 `index.d.ts` 导出完整公共契约类型。普通 CLI 用户继续使用 `flow2spec init`（全局安装 `@double-coding/flow2spec` 后），无需直接调用这些 API。 diff --git a/packages/core/package.json b/packages/core/package.json index 15cc401..9828f6b 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,7 +1,7 @@ { "name": "@double-coding/flow2spec-core", - "version": "3.7.0", - "templateVersion": "3.6.0", + "version": "3.7.1", + "templateVersion": "3.6.1", "description": "Flow2Spec Core APIs, knowledge engine, project initialization and shared resources", "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme", "repository": { diff --git a/packages/core/templates/en-US/knowledge/manifest-routing.json b/packages/core/templates/en-US/knowledge/manifest-routing.json index 764adc0..a7c0076 100644 --- a/packages/core/templates/en-US/knowledge/manifest-routing.json +++ b/packages/core/templates/en-US/knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.6.0", + "version": "3.6.1", "projectRev": 3, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", diff --git a/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md b/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md index 9209b74..814a775 100644 --- a/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md +++ b/packages/core/templates/en-US/skills/f2s-kb-upgrade/SKILL.md @@ -111,12 +111,18 @@ Record CLI Version, Core Version, Core Range, Template Version, Protocol Version | Case | Action | Default step 2 command | | --- | --- | --- | -| **A. Template is current** | If only Core changed, run `flow2spec update --core`, then one idempotent init to refresh the Hook, clear the cache, and **stop this skill**. If Core is also current, stop immediately. | `flow2spec init ` | +| **A. Template is current** | If only Core changed, run `flow2spec update --core`, then one idempotent init to refresh the Hook. Afterwards **do not stop immediately**: first run the "**project-side alignment check**" below, and only stop this skill (clearing the cache) after it passes. | `flow2spec init ` | | **B. Template changed and latest Core is inside Core Range** | Run `flow2spec update --core`, then continue to step 0. A compatible Core update does not require a CLI release or upgrade. | `flow2spec init ` | | **C. Not installed, unknown, or latest Core is outside the range** | Use an explicit latest CLI/Core combination so npx cannot reuse an old Core. If latest Core still is not compatible, upgrade to a CLI that supports it first. | `npx --yes --package @latest --package @latest flow2spec init ` | If the preflight fails, case C is allowed as fallback, but never treat Core Version as Template Version. This step does not mandate a sub-agent or a background global install. +**Project-side alignment check (required before stopping on branch A)**: `flow2spec version` / `update --check` compare the **installed packages vs npm latest**; they do not reflect **whether this project's `.Knowledge` is aligned with the current package templates** (typical misjudgment: running this skill in an old project right after upgrading the CLI/Core — the packages are "all current" but the project-side templates are still old, and stopping here would skip the entire upgrade). Confirm item by item before stopping: + +1. Read the project-side `.Knowledge/manifest-routing.json`: if `version` (project-side Template Version) is **lower than** the installed package Template Version, or the `pkgRev` / `projectRev` fields are missing → the project side is not aligned; **treat it as a Template update**: continue with step 0 → 2 (init) → 2c judgment, do not stop; +2. If the fields match, run `flow2spec kb check --strict`: on summary quality warnings or structural problems → handle them via steps 3a.7 / 3a.8 before wrapping up; +3. Only when all of the above pass may branch A stop, and the summary must state "project side aligned (version=X, strict passed)". + ### Step 0: Version Judgment and Branching (Required, Before init) > **Naming note**: **"V1"** and **"current repository (V2+)"** below are **flow-branch labels inside this skill**. If the **npm package is v3.x, v4.x, ...** and the repository is already in `.Knowledge` + `manifest-routing` shape, still use the **"current repository (V2+)"** branch (only `init` alignment). **Do not** interpret the npm major version number as the literal "V2" here. @@ -287,7 +293,8 @@ Verify at least: Output: -- **Step -1 global version preflight**: branch (`A Installed & on latest (upgrade skipped) / B Installed but behind (sub-agent dispatched to upgrade) / C Missing or latest unknown (dispatched / advised)`) + current global version + npm latest (if obtained) +- **Step -1 global version preflight**: branch (`A Installed & on latest (must include project-side alignment conclusion) / B Installed but behind (sub-agent dispatched to upgrade) / C Missing or latest unknown (dispatched / advised)`) + current global version + npm latest (if obtained) +- **Project-side alignment check** (required on branch A): `aligned (version=X, strict passed, stopped)` / `not aligned (version X < package Y, switched to full flow)` / `strict warnings (handled via 3a.7/3a.8)` - Executed command (including agents and whether reset was used) - Whether it succeeded - **`projectRev` judgment**: project `X` vs package `Y` -> fast path / full flow / field-missing fallback (step 2c) @@ -306,7 +313,7 @@ Output: ```markdown ## f2s-kb-upgrade Execution Result -- **Step -1 global version preflight**: `A Installed & on latest (upgrade skipped) / B Installed but behind (sub-agent dispatched to run npm i -g in background) / C Missing or latest unknown (dispatched / conservative npx)`; current version=``, latest=`` +- **Step -1 global version preflight**: `A Installed & on latest (project-side alignment: ) / B Installed but behind (sub-agent dispatched to run npm i -g in background) / C Missing or latest unknown (dispatched / conservative npx)`; current version=``, latest=`` - Command run inside this skill: `` - init mode: `incremental` / `overwrite reset (--reset-knowledge)` - Result: `success` / `failure` @@ -339,7 +346,7 @@ Output: ## Completion Self-Check -1. **Step -1** was performed: `flow2spec version` and `flow2spec update --check` recorded CLI/Core/Core Range/Template/Protocol; Core-only updates refreshed Core/Hook and stopped, while Template updates selected the current CLI or an explicit latest CLI/Core combination through A/B/C. +1. **Step -1** was performed: `flow2spec version` and `flow2spec update --check` recorded CLI/Core/Core Range/Template/Protocol; Core-only updates refreshed Core/Hook, while Template updates selected the current CLI or an explicit latest CLI/Core combination through A/B/C; **before stopping on branch A, the "project-side alignment check" was completed** (manifest `version`/`pkgRev` comparison + `kb check --strict`), and when not aligned the skill switched to the full flow instead of stopping. 2. **Step 0** was performed: on V1 the skill stopped and told the user how to proceed, and **current repositories (V2+)** entered the `init` flow normally. 3. **Before step 2** recorded the project-side `projectRev` (`projectRev`), and **after step 2 `init`** re-read `pkgRev` and executed **step 2c** judgment. 4. After **step 2 `init`**, **`f2s-kb-upgrade/SKILL.md`** was re-read: on full flow, a change must trigger **a rerun from step 2c per the new literal text** (**no second `init`**); on fast path, the loop can be skipped (see "init and skill self-update" / "fast-path exception"). diff --git a/packages/core/templates/zh-CN/knowledge/manifest-routing.json b/packages/core/templates/zh-CN/knowledge/manifest-routing.json index cd90bff..f694bd3 100644 --- a/packages/core/templates/zh-CN/knowledge/manifest-routing.json +++ b/packages/core/templates/zh-CN/knowledge/manifest-routing.json @@ -1,5 +1,5 @@ { - "version": "3.6.0", + "version": "3.6.1", "projectRev": 3, "knowledgeRoot": ".Knowledge", "matcherKey": "matcherId", diff --git a/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md b/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md index b5d31a7..2f30e79 100644 --- a/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md +++ b/packages/core/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md @@ -111,12 +111,18 @@ flow2spec update --check | 情况 | 行动 | 步骤 2 默认命令 | | --- | --- | --- | -| **A. Template 已是最新** | 若只有 Core 更新，执行 `flow2spec update --core` 后幂等 init 刷新 Hook，删除缓存并**停止本技能**；Core 也最新则直接停止 | `flow2spec init ` | +| **A. Template 已是最新** | 若只有 Core 更新，执行 `flow2spec update --core` 后幂等 init 刷新 Hook；随后**不得直接停止**，必须先做下方「**项目侧对齐检查**」，通过后才删除缓存并停止本技能 | `flow2spec init ` | | **B. Template 有更新且最新 Core 落在当前 Core Range** | 执行 `flow2spec update --core`，继续步骤 0；CLI 无需因 Core 兼容更新而发版或升级 | `flow2spec init ` | | **C. 未安装、版本未知或最新 Core 超出范围** | 使用显式 latest CLI/Core 组合，避免 npx 复用旧 Core；若最新 Core 仍不兼容，先升级支持它的 CLI | `npx --yes --package @latest --package @latest flow2spec init ` | 预检失败时允许回退 C，但不得把 Core Version 当作 Template Version。此步骤不强制创建子 agent，也不后台安装全局包。 +**项目侧对齐检查（A 分支停止前必须）**：`flow2spec version` / `update --check` 对比的是**本机包 vs npm 最新**，不反映**本项目 `.Knowledge` 是否已对齐当前包模板**（典型误判：刚升级完 CLI/Core 后首次在老项目跑本技能，包侧「均为最新」但项目侧模板仍是旧版，直接停止会跳过全部升级动作）。停止前逐项确认： + +1. Read 项目侧 `.Knowledge/manifest-routing.json`：若 `version`（项目侧 Template Version）**低于**本机包 Template Version，或 `pkgRev` / `projectRev` 字段缺失 → 项目侧未对齐，**视同 Template 更新**：继续步骤 0 → 2（init）→ 2c 判定，不得停止； +2. 字段一致时再执行 `flow2spec kb check --strict`：若报 summary 质量 warning 或结构问题 → 转步骤 3a.7 / 3a.8 处理完再收尾； +3. 以上均通过才允许按 A 分支停止，并在摘要中写明「项目侧已对齐（version=X，strict 通过）」。 + ### 步骤 0：版本判定与分流（必须，先于 init） > **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。 @@ -287,7 +293,8 @@ flow2spec update --check 输出以下信息： -- **步骤 -1 全局版本预检**：分支结论（`A 已装且是 latest（跳过升级） / B 已装但落后（已派子 agent 后台升级） / C 未装或 latest 未知（已派或提示）`）+ 当前全局版本 + npm latest 版本（若拿到） +- **步骤 -1 全局版本预检**：分支结论（`A 已装且是 latest（需附项目侧对齐结论） / B 已装但落后（已派子 agent 后台升级） / C 未装或 latest 未知（已派或提示）`）+ 当前全局版本 + npm latest 版本（若拿到） +- **项目侧对齐检查**（A 分支时必填）：`已对齐（version=X，strict 通过，已停止）` / `未对齐（version X < 包 Y，已转完整流程）` / `strict 报 warning（已转 3a.7/3a.8）` - 执行命令（含 agent 与是否 reset） - 是否成功 - **`projectRev` 判定**：`projectRev` X vs `pkgRev` Y → 快速路径 / 完整流程 / 字段缺失走兜底（步骤 2c） @@ -306,7 +313,7 @@ flow2spec update --check ```markdown ## f2s-kb-upgrade 执行结果 -- **步骤 -1 全局版本预检**：`A 已装且是 latest（跳过升级） / B 已装但落后（已派子 agent 后台升级 npm i -g） / C 未装或 latest 未知（已派 / 保守用 npx）`；当前版本=``，latest=`` +- **步骤 -1 全局版本预检**：`A 已装且是 latest（项目侧对齐：<结论>） / B 已装但落后（已派子 agent 后台升级 npm i -g） / C 未装或 latest 未知（已派 / 保守用 npx）`；当前版本=``，latest=`` - 本技能内代跑命令：`<实际执行的 flow2spec init ... 或显式 latest CLI/Core 组合 init ...>` - init 模式：`增量` / `覆盖重置（--reset-knowledge）` - 执行结果：`成功` / `失败` @@ -339,7 +346,7 @@ flow2spec update --check ## 完成后自检 -1. 是否已做 **步骤 -1**：执行 `flow2spec version` 与 `flow2spec update --check`，记录 CLI/Core/Core Range/Template/Protocol；Core-only 更新是否直接刷新 Core/Hook 并停止，Template 更新是否按 A/B/C 选择当前 CLI 或显式 latest CLI/Core 组合。 +1. 是否已做 **步骤 -1**：执行 `flow2spec version` 与 `flow2spec update --check`，记录 CLI/Core/Core Range/Template/Protocol；Core-only 更新是否直接刷新 Core/Hook，Template 更新是否按 A/B/C 选择当前 CLI 或显式 latest CLI/Core 组合；**A 分支停止前是否完成「项目侧对齐检查」**（manifest `version`/`pkgRev` 对比 + `kb check --strict`），未对齐时是否已转完整流程而非直接停止。 2. 是否已做 **步骤 0**：V1 已停止执行并告知用户处理方式、**现行库（V2+）** 正常进入 `init` 流程。 3. 是否在 **步骤 2 开始前** 记录了项目侧 `projectRev`（`projectRev`），并在 **步骤 2 的 `init` 之后** 重读 `pkgRev`、执行 **步骤 2c** 判定。 4. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**：完整流程下有变化必须**按新版字面从步骤 2c 起重跑**（**不再次 init**）；快速路径下可跳过该闭环（见「init 与技能自更新」「快速路径例外」）。 diff --git a/website/src/data/docs.mjs b/website/src/data/docs.mjs index 7433523..02c8adb 100644 --- a/website/src/data/docs.mjs +++ b/website/src/data/docs.mjs @@ -6,6 +6,7 @@ export const docs = [ { id: 'design', header: true, zh: { title: '设计说明', source: '设计说明' }, en: { title: 'Design', source: 'en/design-principles' } }, { id: 'collaboration', header: true, zh: { title: '团队协作', source: '团队协作' }, en: { title: 'Collaboration', source: 'en/team-collaboration' } }, { id: 'milestones', header: true, zh: { title: '项目里程碑', source: '项目里程碑' }, en: { title: 'Milestones', source: 'en/milestones' } }, + { id: 'upgrade', header: false, zh: { title: '升级指南', source: '升级指南' }, en: { title: 'Upgrade guide', source: 'en/upgrade-guide' } }, { id: 'directories', header: false, zh: { title: '目录与路径约定', source: '目录与路径约定' }, en: { title: 'Directory conventions', source: 'en/directory-conventions' } }, { id: 'scenarios', header: false, zh: { title: '使用案例', source: '使用案例-模拟对话' }, en: { title: 'Usage scenarios', source: 'en/usage-scenarios' } } ]; diff --git a/website/src/pages/en/index.astro b/website/src/pages/en/index.astro index d65bb60..eaf620d 100644 --- a/website/src/pages/en/index.astro +++ b/website/src/pages/en/index.astro @@ -27,8 +27,8 @@ const sections = [

Progressive routing

From one sentence to
the context you can verify.

Don't pour the repository into the model. Match, expand dependencies, and read only the facts relevant to this request.

✦

More context isn't always better.
It should be just enough, and useful again tomorrow.

A living development loop

Every delivery makes
the next one faster.

The knowledge base grows through real development: verified, revised, and accurately routed into the next request.

  1. 01
    Describe the requestSay what needs to change in natural language.
  2. 02
    Read relevant factsRoute topics, expand dependencies, fill gaps.
  3. 03
    Build and write backCode and knowledge close in the same workflow.
Flow2Spec development knowledge loop
LC
Q7
shared knowledgetopic revision +1reviewed and merged

Built for shared repositories

Two people.
One knowledge base.

Progress stays local to each developer. Confirmed project facts live in shared `.Knowledge/`, so personal todos never become product knowledge.

Explore team collaboration
-

A calmer first run

Three minutes to
give your project a clear path.

You do not need a complete knowledge base first. Initialize, route one real request, and leave behind the first verified fact.

01Write the collaboration skeleton

Initialize

npx @double-coding/flow2spec@latest init

Write the knowledge base, rules and supported tool entrypoints into the project.

You get.Knowledge/ · AGENTS.md
02Put a request on the route

Describe your first request

“Add pagination to order search; route me to the relevant facts first.”

Start with a real module or change. Build topic facts as they become relevant instead of writing everything up front.

You getMatched topics · filled context
03Leave the result behind

Verify and keep delivering

Facts verifiedReady for the next request

Confirm the routes, topics and revisions are healthy, then turn this verified fact into a shortcut for the next request.

You getReusable project memory
-

Keep exploring

Start here, then
go at your own pace.

From installation to collaboration, choose what to explore next.

Usage guideFrom install to daily development→CommandsCLI and skill entrypoints→ArchitectureRouting and knowledge model→npm packageInstall the latest version↗
+

A calmer first run

Three minutes to
give your project a clear path.

You do not need a complete knowledge base first. Initialize, route one real request, and leave behind the first verified fact.

01Write the collaboration skeleton

Initialize

npm i -g @double-coding/flow2spec && flow2spec init

Write the knowledge base, rules and supported tool entrypoints into the project.

You get.Knowledge/ · AGENTS.md
02Put a request on the route

Describe your first request

“Add pagination to order search; route me to the relevant facts first.”

Start with a real module or change. Build topic facts as they become relevant instead of writing everything up front.

You getMatched topics · filled context
03Leave the result behind

Verify and keep delivering

Facts verifiedReady for the next request

Confirm the routes, topics and revisions are healthy, then turn this verified fact into a shortcut for the next request.

You getReusable project memory
+

Keep exploring

Start here, then
go at your own pace.

From installation to collaboration, choose what to explore next.

Usage guideFrom install to daily development→CommandsCLI and skill entrypoints→ArchitectureRouting and knowledge model→Upgrade guideThree steps to the latest version→
Flow2Spec

Project facts, routed before code.

GitHub ↗npm ↗
© 2026 Double Coding Lab
diff --git a/website/src/pages/index.astro b/website/src/pages/index.astro index c62782a..433a652 100644 --- a/website/src/pages/index.astro +++ b/website/src/pages/index.astro @@ -64,9 +64,9 @@ const sections = [
LC
Q7
shared knowledgetopic revision +1reviewed and merged

Built for shared repositories

两个人，
一份知识库。

任务进度按开发者隔离，确认后的项目事实留在共享的 `.Knowledge/`。并行开发不会把个人待办混进产品知识。

了解团队协作
-

A calmer first run

三分钟，
让项目有章可循。

不用先整理完整知识库。先初始化，再用一次真实需求让它长出第一条可验证事实。

01写入协作骨架

初始化

npx @double-coding/flow2spec@latest init

为项目写入知识库、规则和已选择客户端的入口。

会得到.Knowledge/ · AGENTS.md
02让需求进入路由

描述第一个需求

“给订单查询增加分页，先找相关事实。”

从真实模块或变更开始，按需建立主题事实，不必一次写完所有文档。

会得到命中主题 · 补齐上下文
03把结果留下来

验证并持续交付

事实已验证下一次请求可以直接复用

确认路由、主题和 revision 都健康，让这次验证过的事实成为下一次工作的捷径。

会得到可复用的项目记忆
+

A calmer first run

三分钟，
让项目有章可循。

不用先整理完整知识库。先初始化，再用一次真实需求让它长出第一条可验证事实。

01写入协作骨架

初始化

npm i -g @double-coding/flow2spec && flow2spec init

为项目写入知识库、规则和已选择客户端的入口。

会得到.Knowledge/ · AGENTS.md
02让需求进入路由

描述第一个需求

“给订单查询增加分页，先找相关事实。”

从真实模块或变更开始，按需建立主题事实，不必一次写完所有文档。

会得到命中主题 · 补齐上下文
03把结果留下来

验证并持续交付

事实已验证下一次请求可以直接复用

确认路由、主题和 revision 都健康，让这次验证过的事实成为下一次工作的捷径。

会得到可复用的项目记忆
-

Keep exploring

从这里，继续阅读。

从安装到协作，选择下一步要了解的内容。

使用说明从安装到日常开发→命令说明完整 CLI 与 Skill 入口→体系与原理了解路由和知识模型→npm package安装最新版本↗
+

Keep exploring

从这里，继续阅读。

从安装到协作，选择下一步要了解的内容。

使用说明从安装到日常开发→命令说明完整 CLI 与 Skill 入口→体系与原理了解路由和知识模型→升级指南老项目三步升到最新版→