From 0fd4c10b1470be0546740d2b5b30f01c7ff55864 Mon Sep 17 00:00:00 2001 From: liguochuan <292761894@qq.com> Date: Mon, 17 Aug 2026 11:51:21 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20fix(release):=20=E6=81=A2?= =?UTF-8?q?=E5=A4=8D=20npm=20=E5=AE=8C=E6=95=B4=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../topics/f2s-dev-workflow-constraints.md | 7 +- .../rules/repo-dev-workflow-constraints.md | 7 + .../topics/repo-dev-workflow-constraints.md | 7 + .../rules/repo-dev-workflow-constraints.mdc | 7 + package-lock.json | 10 +- package.json | 7 +- packages/cli/README.md | 157 +++++++++++++++++- packages/cli/package.json | 30 +++- packages/core/package.json | 2 +- scripts/sync-package-readme.js | 25 +++ scripts/test-package-install.js | 12 ++ 11 files changed, 255 insertions(+), 16 deletions(-) create mode 100644 scripts/sync-package-readme.js diff --git a/.Knowledge/topics/f2s-dev-workflow-constraints.md b/.Knowledge/topics/f2s-dev-workflow-constraints.md index a789772..19386a5 100644 --- a/.Knowledge/topics/f2s-dev-workflow-constraints.md +++ b/.Knowledge/topics/f2s-dev-workflow-constraints.md @@ -1,6 +1,6 @@ --- id: f2s-dev-workflow-constraints -revision: 0 +revision: 1 summary: "f2s-dev-workflow-constraints（路由摘要）" primary: policy confidence: inferred @@ -55,3 +55,8 @@ flow2spec init codex claude cursor - **不写下游可见位置**：本 topic 与关联 rules/skill 一律不落 `templates/`；`f2s-kb-upgrade` 步骤 -1 / 步骤 2 的 init 分发**不带**这些文件到下游。 - `LOCAL_CONTEXT.md`、`.claude/memory/` 为本地不入库文件，不视为配置根。 +## npm workspace 发布门禁 + +- 主 CLI 包 `@double-coding/flow2spec` 的 `packages/cli/README.md` 与根 `README.md` 保持完全一致；Core 包维护面向程序化调用的独立 README。 +- Core、CLI 与 workspace 根版本保持一致，CLI 固定依赖同版本 Core。 +- 发布前运行 `npm run pack:check` 与 `node scripts/test-package-install.js`，并从 CLI tarball 校验 README，确保 npm 页面保留完整产品文档。 diff --git a/.claude/rules/repo-dev-workflow-constraints.md b/.claude/rules/repo-dev-workflow-constraints.md index 1478bc2..8849d04 100644 --- a/.claude/rules/repo-dev-workflow-constraints.md +++ b/.claude/rules/repo-dev-workflow-constraints.md @@ -111,6 +111,13 @@ flow2spec init codex claude cursor **注意**：`init` **不会**动本仓专属手写文件（本规则、`repo-dev-check` skill）——这些文件在 `templates/` 里没有对应源，`init` 找不到就不写，用户手写的原始版本得以保留。 +## npm workspace 发布门禁 + +- `@double-coding/flow2spec` 是面向普通用户的主包，`packages/cli/README.md` 必须与根 `README.md` 完全一致；根 README 变更后执行 `npm run sync:package-readme`。 +- `@double-coding/flow2spec-core` 面向 CLI 与原生插件开发者，维护独立的 `packages/core/README.md`，不复制主包的用户文档。 +- Core、CLI 与 workspace 根版本保持一致，CLI 对 Core 的依赖固定为同一版本。 +- 发布前执行 `npm run pack:check` 与 `node scripts/test-package-install.js`；安装测试必须从 CLI tarball 解出 `package/README.md` 并与根 README 比较，防止 npm 页面退化为占位说明。 + ## 与其他规则的关系 - **`f2s-flow2spec-unified-entry`**：讲「消费侧读取顺序」；本文件讲「本仓开发时的生产侧写盘边界」。两者并存不冲突。 diff --git a/.codex/topics/repo-dev-workflow-constraints.md b/.codex/topics/repo-dev-workflow-constraints.md index 1478bc2..8849d04 100644 --- a/.codex/topics/repo-dev-workflow-constraints.md +++ b/.codex/topics/repo-dev-workflow-constraints.md @@ -111,6 +111,13 @@ flow2spec init codex claude cursor **注意**：`init` **不会**动本仓专属手写文件（本规则、`repo-dev-check` skill）——这些文件在 `templates/` 里没有对应源，`init` 找不到就不写，用户手写的原始版本得以保留。 +## npm workspace 发布门禁 + +- `@double-coding/flow2spec` 是面向普通用户的主包，`packages/cli/README.md` 必须与根 `README.md` 完全一致；根 README 变更后执行 `npm run sync:package-readme`。 +- `@double-coding/flow2spec-core` 面向 CLI 与原生插件开发者，维护独立的 `packages/core/README.md`，不复制主包的用户文档。 +- Core、CLI 与 workspace 根版本保持一致，CLI 对 Core 的依赖固定为同一版本。 +- 发布前执行 `npm run pack:check` 与 `node scripts/test-package-install.js`；安装测试必须从 CLI tarball 解出 `package/README.md` 并与根 README 比较，防止 npm 页面退化为占位说明。 + ## 与其他规则的关系 - **`f2s-flow2spec-unified-entry`**：讲「消费侧读取顺序」；本文件讲「本仓开发时的生产侧写盘边界」。两者并存不冲突。 diff --git a/.cursor/rules/repo-dev-workflow-constraints.mdc b/.cursor/rules/repo-dev-workflow-constraints.mdc index 1478bc2..8849d04 100644 --- a/.cursor/rules/repo-dev-workflow-constraints.mdc +++ b/.cursor/rules/repo-dev-workflow-constraints.mdc @@ -111,6 +111,13 @@ flow2spec init codex claude cursor **注意**：`init` **不会**动本仓专属手写文件（本规则、`repo-dev-check` skill）——这些文件在 `templates/` 里没有对应源，`init` 找不到就不写，用户手写的原始版本得以保留。 +## npm workspace 发布门禁 + +- `@double-coding/flow2spec` 是面向普通用户的主包，`packages/cli/README.md` 必须与根 `README.md` 完全一致；根 README 变更后执行 `npm run sync:package-readme`。 +- `@double-coding/flow2spec-core` 面向 CLI 与原生插件开发者，维护独立的 `packages/core/README.md`，不复制主包的用户文档。 +- Core、CLI 与 workspace 根版本保持一致，CLI 对 Core 的依赖固定为同一版本。 +- 发布前执行 `npm run pack:check` 与 `node scripts/test-package-install.js`；安装测试必须从 CLI tarball 解出 `package/README.md` 并与根 README 比较，防止 npm 页面退化为占位说明。 + ## 与其他规则的关系 - **`f2s-flow2spec-unified-entry`**：讲「消费侧读取顺序」；本文件讲「本仓开发时的生产侧写盘边界」。两者并存不冲突。 diff --git a/package-lock.json b/package-lock.json index be3c7dc..dcf4b2a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "flow2spec-workspace", - "version": "3.3.0", + "version": "3.3.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "flow2spec-workspace", - "version": "3.3.0", + "version": "3.3.1", "workspaces": [ "packages/core", "packages/cli" @@ -25,10 +25,10 @@ }, "packages/cli": { "name": "@double-coding/flow2spec", - "version": "3.3.0", + "version": "3.3.1", "license": "ISC", "dependencies": { - "@double-coding/flow2spec-core": "3.3.0" + "@double-coding/flow2spec-core": "3.3.1" }, "bin": { "flow2spec": "cli.js" @@ -39,7 +39,7 @@ }, "packages/core": { "name": "@double-coding/flow2spec-core", - "version": "3.3.0", + "version": "3.3.1", "license": "ISC", "engines": { "node": ">=16" diff --git a/package.json b/package.json index 459aada..4436f05 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "flow2spec-workspace", "private": true, - "version": "3.3.0", + "version": "3.3.1", "description": "Flow2Spec workspace for the Core library and CLI packages", "workspaces": [ "packages/core", @@ -11,11 +11,12 @@ "node": ">=16" }, "scripts": { - "test": "node cli.js --help && node cli.js kb check && node scripts/test-knowledge-engine.js && node scripts/test-developer-id.js && node scripts/test-template-knowledge.js && node scripts/test-init-gitignore.js && node scripts/test-dsh-init.js && node scripts/test-doctor.js && node scripts/test-core-api.js && node scripts/test-package-install.js", + "test": "node cli.js --help && node cli.js kb check && node scripts/sync-package-readme.js --check && node scripts/test-knowledge-engine.js && node scripts/test-developer-id.js && node scripts/test-template-knowledge.js && node scripts/test-init-gitignore.js && node scripts/test-dsh-init.js && node scripts/test-doctor.js && node scripts/test-core-api.js && node scripts/test-package-install.js", "test:core": "node scripts/test-core-api.js", "test:cli": "node cli.js --help && node cli.js doctor --json", "sync:agents": "node cli.js init cursor claude codex", - "pack:check": "npm pack --workspace @double-coding/flow2spec-core --dry-run && npm pack --workspace @double-coding/flow2spec --dry-run", + "sync:package-readme": "node scripts/sync-package-readme.js", + "pack:check": "node scripts/sync-package-readme.js --check && npm pack --workspace @double-coding/flow2spec-core --dry-run && npm pack --workspace @double-coding/flow2spec --dry-run", "tag:version": "node scripts/git-tag-version.js" } } diff --git a/packages/cli/README.md b/packages/cli/README.md index 312111c..f1baa4b 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,3 +1,156 @@ -# @double-coding/flow2spec +# Flow2Spec -Flow2Spec CLI。业务项目继续使用 `npx @double-coding/flow2spec@latest init`，CLI 内部调用 `@double-coding/flow2spec-core`。 +

+ Flow2Spec routes a natural language coding request into compact project facts before code edits +

+ +

+ Give each initialized AI coding client the project facts it needs before editing. +

+ +

+ 中文 · + Live demo · + Introduction · + Usage guide · + Commands · + Roadmap +

+ +

+ npm latest + node version + license +

+ +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 +# DeepSeek Harness projects: +flow2spec init dsh +``` + +## Why it exists + +Without a maintained, routable project memory, an agent has to rediscover the same constraints on every request. Flow2Spec keeps those facts in compact topic shards and routes each request to the topics it needs. + +| Without Flow2Spec | With Flow2Spec | +| --- | --- | +| “Which module owns this table?” | `[matcher hit] m-product-review-template-library` | +| “Is batchReScore sync or async?” | `[loading deps] 4 topics · ~300 lines` | +| “Is there a lock? What is the idempotency key?” | `Redis lock ... TTL 10 min` | +| Agent searches 416 APIs, 796 files, and 4.7 MB of source before editing. | Agent reads the verified constraints first and opens the relevant files. | + +Flow2Spec does not add documentation for its own sake. It keeps a small, machine-readable knowledge layer alongside the code, and lets the same skills update it when verified facts change. + +## What you get + +| Layer | What it does | Files | +| --- | --- | --- | +| Knowledge routing | Maps a request to the few topics the agent needs to read. | `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` | +| Topic shards | Stores project facts such as APIs, limits, locks, data rules, and workflows. | `.Knowledge/topics/*.md` | +| Agent entrypoints | Installs rules and skills for the selected AI coding clients. | client configuration roots, `.dsh/`, `AGENTS.md` | +| Skill workflows | Clarifies requirements, writes specs, implements, fixes, syncs knowledge, and commits. | `f2s-*` skills | +| Team collaboration | Keeps each developer's task state local while merging reviewed knowledge through structured deltas and topic revisions. | `.task//`, `.Knowledge/` | + +## Built for shared repositories + +Flow2Spec separates collaboration state by ownership. Checklists, session context, and user todos stay under each developer's local `TASK_ROOT` and do not enter Git. Confirmed project knowledge remains shared in `.Knowledge/`. + +Knowledge-producing skills write a structured `kb-delta.json` instead of editing topic files directly. Before apply, the CLI compares the delta's `baseRevisions` with the topic revisions on disk. Different topics can merge independently; concurrent changes to the same topic stop for a semantic review after the latest branch state is pulled. + +Read the full model in [Team Collaboration](./docs/en/team-collaboration.md). + +## First use + +After initialization, you do not need to document the whole project upfront. Start with the change you actually need. The agent reads the relevant code and existing docs while it works, then saves confirmed project facts back into the knowledge base. + +For an existing project, you can ask the agent to draft the project structure first: + +```text +/f2s-doc-arch +``` + +This helps the agent understand the main directories, module boundaries, and existing conventions. It is optional. For a small change, you can start directly from the request. + +## Daily development + +Most of the time, describe the task in natural language: + +```text +Add batch recalculation. It should retry failed items and avoid running the same batch twice. +``` + +The agent should look for relevant project knowledge first. If something is missing, it should explain the gap, then read the necessary code or ask you a follow-up question. Confirmed facts such as APIs, limits, locks, data rules, and workflows can be synced back into `.Knowledge`. + +A larger change usually follows this path: + +```text +describe the requirement + → agent fills in missing details + → generate or review the technical spec + → implement / fix + → sync verified project facts + → check knowledge coverage before commit +``` + +If you already know which workflow you want, use one of the explicit entrypoints below. + +## How the knowledge base grows + +Flow2Spec's knowledge base is not meant to be finished in one pass. It grows with development: + +1. `init` creates the base skeleton. +2. The first time a module matters, the agent reads the relevant code and docs. +3. Confirmed facts from the development process become routable topics. +4. Later similar requests can hit those topics directly instead of searching the whole repository again. + +The directories can be read this way: + +- `req-docs/`: technical specs and implementation plans for concrete changes. +- `stock-docs/`: stable project background, architecture notes, and imported source material. +- `topics/`: compact facts the agent should actually load. +- `matchers/`: rules that route a user request to the right topics. + +## Explicit skill entrypoints + +Natural-language requests can select these workflows automatically when intent recognition is enabled. Use the entrypoints below when you want to choose one directly. + +| Command | Purpose | +| --- | --- | +| `/f2s-req-clarify` | Clarify missing requirements until the change is unambiguous. | +| `/f2s-req-tech` | Turn confirmed requirements into an implementation-ready technical proposal. | +| `/f2s-kb-feat` | Add a capability and update project knowledge. | +| `/f2s-kb-fix` | Fix behavior and correct the matching knowledge. | +| `/f2s-kb-sync` | Sync already implemented facts into `.Knowledge/`. | +| `/f2s-kb-add ` | Import an existing module or document set. | +| `/f2s-git-commit` | Check changed files and knowledge coverage before committing. | + +Full references: + +- [Usage guide](./docs/en/usage-guide.md) +- [Commands reference](./docs/en/commands-reference.md) +- [Directory conventions](./docs/en/directory-conventions.md) +- [Architecture and principles](./docs/en/architecture.md) +- [Team collaboration](./docs/en/team-collaboration.md) +- [Design principles](./docs/en/design-principles.md) +- [Project milestones](./docs/en/milestones.md) + +## When not to use it + +Flow2Spec is useful when context drift is expensive. It may be unnecessary for: + +- throwaway one-off scripts; +- tiny solo projects where one `CLAUDE.md` is enough; +- teams that will not keep `.Knowledge/` aligned with the code. + +## Learn more + +- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md) — product narrative, diagrams, and comparison with ordinary project memory. +- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md) — Chinese long-form introduction. +- [Product website](https://double-coding-lab.github.io/Flow2Spec/en/) — a website-style guide to Flow2Spec's core capabilities and workflow. + +## License + +[MIT](./LICENSE) diff --git a/packages/cli/package.json b/packages/cli/package.json index e6a5af6..4aa7373 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,12 +1,11 @@ { "name": "@double-coding/flow2spec", - "version": "3.3.0", + "version": "3.3.1", "description": "在业务仓库初始化文档驱动、可写回知识库的 AI 协作骨架", "homepage": "https://github.com/double-coding-lab/Flow2Spec#readme", "repository": { "type": "git", - "url": "git+https://github.com/double-coding-lab/Flow2Spec.git", - "directory": "packages/cli" + "url": "git+https://github.com/double-coding-lab/Flow2Spec.git" }, "bugs": { "url": "https://github.com/double-coding-lab/Flow2Spec/issues" @@ -21,7 +20,7 @@ "README.md" ], "dependencies": { - "@double-coding/flow2spec-core": "3.3.0" + "@double-coding/flow2spec-core": "3.3.1" }, "publishConfig": { "access": "public", @@ -30,5 +29,28 @@ "engines": { "node": ">=16" }, + "keywords": [ + "flow2spec", + "cursor", + "cursor-rules", + "agent-skills", + "claude", + "codex", + "deepseek-harness", + "ai-workflow", + "project-context", + "knowledge-base", + "documentation", + "rules", + "skills", + "stock-docs", + "req-docs", + "context-engineering", + "f2s" + ], + "author": "兰大神 <550947002@qq.com>", + "contributors": [ + "七七是只猫 <292761894@qq.com>" + ], "license": "ISC" } diff --git a/packages/core/package.json b/packages/core/package.json index 92280d2..0c4a3f3 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@double-coding/flow2spec-core", - "version": "3.3.0", + "version": "3.3.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/scripts/sync-package-readme.js b/scripts/sync-package-readme.js new file mode 100644 index 0000000..c37b7e7 --- /dev/null +++ b/scripts/sync-package-readme.js @@ -0,0 +1,25 @@ +#!/usr/bin/env node +"use strict"; + +const fs = require("fs"); +const path = require("path"); + +const rootDir = path.resolve(__dirname, ".."); +const sourcePath = path.join(rootDir, "README.md"); +const targetPath = path.join(rootDir, "packages", "cli", "README.md"); +const source = fs.readFileSync(sourcePath, "utf8"); +const checkOnly = process.argv.includes("--check"); + +if (checkOnly) { + const target = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : ""; + if (target !== source) { + console.error("packages/cli/README.md is not synchronized with the root README.md"); + console.error("Run: npm run sync:package-readme"); + process.exit(1); + } + console.log("check-package-readme: ok"); + process.exit(0); +} + +fs.writeFileSync(targetPath, source, "utf8"); +console.log("synced README.md to packages/cli/README.md"); diff --git a/scripts/test-package-install.js b/scripts/test-package-install.js index 48928b5..16e9775 100644 --- a/scripts/test-package-install.js +++ b/scripts/test-package-install.js @@ -23,6 +23,18 @@ run("npm", ["pack", "--workspace", "@double-coding/flow2spec", "--pack-destinati const tarballs = fs.readdirSync(tempDir).filter((file) => file.endsWith(".tgz")); assert.strictEqual(tarballs.length, 2, "expected Core and CLI tarballs"); +const cliTarball = tarballs.find((file) => /^double-coding-flow2spec-\d/.test(file)); +assert.ok(cliTarball, "expected CLI tarball"); +const packedReadme = run("tar", [ + "-xOf", + path.join(tempDir, cliTarball), + "package/README.md", +]); +assert.strictEqual( + packedReadme, + fs.readFileSync(path.resolve(__dirname, "..", "README.md"), "utf8"), + "CLI package must publish the complete root README", +); run("npm", [ "install", "--ignore-scripts",