From 01a572d7cf60d6e36b4c46d788a9aa18e233b31c Mon Sep 17 00:00:00 2001 From: liguochuan <292761894@qq.com> Date: Fri, 14 Aug 2026 12:25:36 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=80=20feat(dsh):=20=E6=94=AF=E6=8C=81?= =?UTF-8?q?=20DeepSeek=20Harness=20=E9=A1=B9=E7=9B=AE=E7=BA=A7=E9=80=82?= =?UTF-8?q?=E9=85=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 flow2spec init dsh、技能分发、规则镜像与 Doctor 检查 - 补齐中英文文档、知识路由和初始化回归测试 - 泛化客户端相关文案，避免固定客户端数量和名称 --- .Knowledge/index.md | 1 + .Knowledge/manifest-routing.json | 18 ++++- .../matchers/m-flow2spec-dsh-adapter.json | 16 ++++ .Knowledge/topics/flow2spec-dsh-adapter.md | 27 +++++++ README.en.md | 9 ++- README.md | 9 ++- README.zh-CN.md | 9 ++- cli.js | 19 ++--- ...72\347\241\200\344\273\213\347\273\215.md" | 4 +- docs/en/Flow2Spec-Introduction.md | 4 +- docs/en/architecture.md | 4 +- docs/en/design-principles.md | 6 +- docs/en/directory-conventions.md | 4 +- docs/en/milestones.md | 3 +- docs/en/usage-guide.md | 7 +- ...73\344\270\216\345\216\237\347\220\206.md" | 6 +- ...77\347\224\250\350\257\264\346\230\216.md" | 9 ++- ...57\345\276\204\347\272\246\345\256\232.md" | 4 +- ...56\351\207\214\347\250\213\347\242\221.md" | 9 ++- lib/agents.js | 2 + lib/doctor.js | 5 +- lib/dshAgentsAdapter.js | 81 +++++++++++++++++++ lib/init.js | 32 +++++++- package.json | 2 +- .../flow2spec-intro-public-en/index.html | 4 +- .../flow2spec-intro-public/index.html | 6 +- .../flow2spec-intro-public/market-compare.md | 4 +- .../\346\274\224\350\256\262\347\250\277.md" | 2 +- scripts/test-dsh-init.js | 44 ++++++++++ templates/en-US/knowledge/index.md | 1 + .../en-US/knowledge/manifest-routing.json | 16 +++- .../matchers/m-flow2spec-dsh-adapter.json | 6 ++ .../knowledge/topics/flow2spec-dsh-adapter.md | 16 ++++ .../rules/f2s-flow2spec-unified-entry.md | 2 +- .../en-US/skills/f2s-kb-upgrade/SKILL.md | 6 +- templates/en-US/skills/f2s-req-plan/SKILL.md | 10 +-- templates/zh-CN/knowledge/index.md | 1 + .../zh-CN/knowledge/manifest-routing.json | 16 +++- .../matchers/m-flow2spec-dsh-adapter.json | 6 ++ .../knowledge/topics/flow2spec-dsh-adapter.md | 16 ++++ .../rules/f2s-flow2spec-unified-entry.md | 2 +- .../zh-CN/skills/f2s-kb-upgrade/SKILL.md | 6 +- templates/zh-CN/skills/f2s-req-plan/SKILL.md | 12 +-- website/src/pages/en/index.astro | 2 +- website/src/pages/index.astro | 4 +- 45 files changed, 382 insertions(+), 90 deletions(-) create mode 100644 .Knowledge/matchers/m-flow2spec-dsh-adapter.json create mode 100644 .Knowledge/topics/flow2spec-dsh-adapter.md create mode 100644 lib/dshAgentsAdapter.js create mode 100644 scripts/test-dsh-init.js create mode 100644 templates/en-US/knowledge/matchers/m-flow2spec-dsh-adapter.json create mode 100644 templates/en-US/knowledge/topics/flow2spec-dsh-adapter.md create mode 100644 templates/zh-CN/knowledge/matchers/m-flow2spec-dsh-adapter.json create mode 100644 templates/zh-CN/knowledge/topics/flow2spec-dsh-adapter.md diff --git a/.Knowledge/index.md b/.Knowledge/index.md index 79b71e1..a4a9f01 100644 --- a/.Knowledge/index.md +++ b/.Knowledge/index.md @@ -38,6 +38,7 @@ | f2s-kb-distill | `.Knowledge/topics/f2s-kb-distill.md` | Q&A 驱动知识提取；自动判断创建新 topic 或追加现有 topic | 技能：skills/f2s-kb-distill/SKILL.mdc | | flow2spec-init-defaults | `.Knowledge/topics/f2s-init-defaults.md` | `flow2spec init` 字段默认值、四处落点一致性、老项目缺字段补写、`init` 不动 stock/req/topics/matchers、manifest 两个版本字段（`projectRev` / `pkgRev`）对照 | 包源码：`lib/flow2specConfig.js` `DEFAULTS` / `CONFIG_FIELDS`；模板：`templates/{locale}/flow2spec.config.json` | | flow2spec-doctor | `.Knowledge/topics/flow2spec-doctor.md` | `flow2spec doctor` 只读检查环境、项目初始化、协作上下文与知识库健康 | stock：[Doctor 诊断命令](stock-docs/Flow2Spec-doctor诊断命令.md)；中英文命令文档：`docs/命令说明.md` / `docs/en/commands-reference.md` | +| flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh`、DeepSeek Harness 项目技能发现与 `.dsh/` 目录适配 | 用户文档：`docs/使用说明.md` / `docs/en/usage-guide.md`；实现：`lib/dshAgentsAdapter.js` | 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`；**`f2s-kb-feedback-closing`** 在 cases 1–3 建议执行 **`f2s-kb-distill`**。 diff --git a/.Knowledge/manifest-routing.json b/.Knowledge/manifest-routing.json index 3d32380..a8f5118 100644 --- a/.Knowledge/manifest-routing.json +++ b/.Knowledge/manifest-routing.json @@ -33,7 +33,8 @@ "f2s-kb-distill": ".Knowledge/topics/f2s-kb-distill.md", "flow2spec-init-defaults": ".Knowledge/topics/f2s-init-defaults.md", "flow2spec-collaboration": ".Knowledge/topics/flow2spec-collaboration.md", - "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md" + "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md", + "flow2spec-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.md" }, "taskToTopicRules": [ { @@ -156,6 +157,14 @@ "topics": [ "flow2spec-doctor" ] + }, + { + "task": "flow2spec-dsh-adapter", + "matcherId": "m-flow2spec-dsh-adapter", + "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", + "topics": [ + "flow2spec-dsh-adapter" + ] } ], "topicMetadata": { @@ -234,6 +243,13 @@ "tags": [ "module" ] + }, + "flow2spec-dsh-adapter": { + "primary": "feature", + "confidence": "inferred", + "tags": [ + "module" + ] } } } diff --git a/.Knowledge/matchers/m-flow2spec-dsh-adapter.json b/.Knowledge/matchers/m-flow2spec-dsh-adapter.json new file mode 100644 index 0000000..8df1194 --- /dev/null +++ b/.Knowledge/matchers/m-flow2spec-dsh-adapter.json @@ -0,0 +1,16 @@ +{ + "includeAny": [ + "DeepSeek Harness", + "deepseek-harness", + "dsh", + "flow2spec init dsh", + ".dsh/skills", + ".dsh/topics", + "Cordis 插件", + "Harness 技能", + "Harness 适配" + ], + "id": "m-flow2spec-dsh-adapter", + "version": "1.0.0", + "schema": "flow2spec.matcher.v1" +} diff --git a/.Knowledge/topics/flow2spec-dsh-adapter.md b/.Knowledge/topics/flow2spec-dsh-adapter.md new file mode 100644 index 0000000..d1599f5 --- /dev/null +++ b/.Knowledge/topics/flow2spec-dsh-adapter.md @@ -0,0 +1,27 @@ +--- +id: flow2spec-dsh-adapter +revision: 0 +summary: "DeepSeek Harness 项目级技能初始化与目录适配" +primary: feature +confidence: inferred +tags: [module] +--- +# DeepSeek Harness 适配 + +## 适用场景 + +用于 `flow2spec init dsh`、DeepSeek Harness 技能发现、`.dsh/skills`、`.dsh/topics` 和根 `AGENTS.md` 入口问题。 + +## 已落地能力 + +- `flow2spec init dsh` 将 Flow2Spec 技能复制到 `.dsh/skills//SKILL.md`。 +- 将模板规则长文镜像到 `.dsh/topics/*.md`，并写入 `.dsh/AGENTS.md` 目录指针。 +- 根目录没有 `AGENTS.md` 时生成 Harness 兼容的完整入口；已有入口不会被覆盖。 +- 原生 Cordis 插件不在本适配范围内，属于后续路线图事项。 + +## 维护边界 + +- Agent 注册：`lib/agents.js` +- 初始化适配：`lib/init.js`、`lib/dshAgentsAdapter.js` +- 诊断与回归：`lib/doctor.js`、`scripts/test-dsh-init.js` +- 用户文档：`docs/使用说明.md`、`docs/en/usage-guide.md`、`docs/目录与路径约定.md` diff --git a/README.en.md b/README.en.md index 2c9076f..d45ac25 100644 --- a/README.en.md +++ b/README.en.md @@ -5,7 +5,7 @@

- Give Cursor, Claude Code, and Codex the project facts they need before editing. + Give each initialized AI coding client the project facts it needs before editing.

@@ -13,7 +13,8 @@ Live demo · Introduction · Usage guide · - Commands + Commands · + Roadmap

@@ -26,6 +27,8 @@ Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a sm ```bash npx @double-coding/flow2spec@latest init +# DeepSeek Harness projects: +flow2spec init dsh ``` ## Why it exists @@ -47,7 +50,7 @@ Flow2Spec does not add documentation for its own sake. It keeps a small, machine | --- | --- | --- | | 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 Cursor, Claude Code, and Codex. | `.cursor/`, `.claude/`, `.codex/`, `AGENTS.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 | | Local task state | Keeps AI steps and user-side todos separate from product knowledge. | `.task/` | diff --git a/README.md b/README.md index ec22d15..f1baa4b 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

- Give Cursor, Claude Code, and Codex the project facts they need before editing. + Give each initialized AI coding client the project facts it needs before editing.

@@ -13,7 +13,8 @@ Live demo · Introduction · Usage guide · - Commands + Commands · + Roadmap

@@ -26,6 +27,8 @@ Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a sm ```bash npx @double-coding/flow2spec@latest init +# DeepSeek Harness projects: +flow2spec init dsh ``` ## Why it exists @@ -47,7 +50,7 @@ Flow2Spec does not add documentation for its own sake. It keeps a small, machine | --- | --- | --- | | 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 Cursor, Claude Code, and Codex. | `.cursor/`, `.claude/`, `.codex/`, `AGENTS.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/` | diff --git a/README.zh-CN.md b/README.zh-CN.md index 2243121..bcf1854 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -5,7 +5,7 @@

- 让 Cursor、Claude Code、Codex 在动手改代码前，先读到正确的项目事实。 + 让每个已初始化的 AI 编程客户端在动手改代码前，先读到正确的项目事实。

@@ -13,7 +13,8 @@ 在线演示 · 基础介绍 · 使用说明 · - 命令说明 + 命令说明 · + 路线图

@@ -26,6 +27,8 @@ Flow2Spec 是给 AI 编码工具使用的 Spec-driven 工作流层。它会在 ```bash npx @double-coding/flow2spec@latest init +# DeepSeek Harness 项目： +flow2spec init dsh ``` ## 为什么需要它 @@ -47,7 +50,7 @@ Flow2Spec 不是为了增加文档数量。它把项目事实保存在一层小 | --- | --- | --- | | 知识路由 | 把一次需求映射到 agent 需要读取的少量 topics。 | `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` | | 主题分片 | 保存 API、上限、锁、数据规则、业务流程等项目事实。 | `.Knowledge/topics/*.md` | -| Agent 入口 | 为 Cursor、Claude Code、Codex 安装规则和技能。 | `.cursor/`, `.claude/`, `.codex/`, `AGENTS.md` | +| Agent 入口 | 为选中的 AI 编程客户端安装规则和技能。 | 客户端配置根、`.dsh/`、`AGENTS.md` | | 技能工作流 | 澄清需求、编写方案、实现、修复、同步知识、提交。 | `f2s-*` skills | | 团队协作 | 每个人的任务现场留在本地，确认后的知识通过结构化 delta 与 topic revision 合入共享仓库。 | `.task//`, `.Knowledge/` | diff --git a/cli.js b/cli.js index c8a9905..8ae7bc9 100644 --- a/cli.js +++ b/cli.js @@ -246,26 +246,21 @@ agent（可多个，空格分隔；省略时交互选择）： 示例: flow2spec init # 交互选择工具和配置 - flow2spec init claude # 直接写入 .claude/，跳过工具选择 - flow2spec init cursor claude # 同时写入 .cursor/ 与 .claude/ - flow2spec init codex --locale en-US # 使用英文模板初始化 Codex + flow2spec init # 直接写入指定客户端配置根，跳过工具选择 + flow2spec init # 同时初始化多个客户端 + flow2spec init --locale en-US # 使用英文模板初始化指定客户端 + flow2spec init dsh # 初始化 DeepSeek Harness 项目技能 flow2spec init --yes # 跳过所有问答，使用默认值（适合 CI） flow2spec init --reset-knowledge # 强制用模板覆盖 .Knowledge（谨慎） init 会: - 1. 交互询问要初始化的 AI 工具（cursor / claude / codex，可多选）；已通过参数指定则跳过。 + 1. 交互询问要初始化的 AI 工具（见上方 agent 列表，可多选）；已通过参数指定则跳过。 传 --yes 或非 TTY 环境时跳过问答，使用默认值。 2. 对 ${CONFIG_FILENAME} 中缺失的配置字段逐项提问（已有字段不覆盖）。模板语言由 --locale、已有 locale 或默认 zh-CN 决定。 传 --yes 时所有缺失字段使用各自默认值。 3. 默认仅补齐 .Knowledge 缺失模板，并对路由清单做包级/结构增量对齐（manifest-routing + matcherPath 分片；关键词仅写在 matchers/*.json）；不替代 f2s-* 对业务文档与路由内容的写入。 传 --reset-knowledge 时才会强制用模板覆盖 .Knowledge 中模板承载部分。 - 4. 在各 agent 配置根写入 rules、skills（Claude 规则自动转 .md；Codex 在仓库根写入完整 AGENTS.md，.codex/ 写入指针）。 - Claude 额外写入 .claude/hooks/f2s-config-session.js、f2s-config-inject.js 与 .claude/settings.json： - SessionStart 注入一次配置摘要；PreToolUse 仅在调用 f2s-* Skill 时提示首步必须 Read 配置。 - Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件； - 并写入 .cursor/hooks.json，在 sessionStart 自动检测知识库版本。 - Codex：仓库根 AGENTS.md（完整条令）；.codex/AGENTS.md 为指针； - 并写入 .codex/hooks.json，在 SessionStart 注入配置摘要并检测知识库版本。 + 4. 在各 agent 配置根写入对应的 rules、skills、入口和 hooks（若该客户端支持）；具体落盘方式以客户端适配器为准。 5. 每次 init 将当前 locale 包模板 knowledge/index.md 复制到 .Knowledge/template/index.template.md，供 f2s-kb-upgrade 技能与 .Knowledge/index.md 对照；不自动改写 index.md。（「知识库升级」指 f2s-kb-upgrade 技能，init 本身不是升级命令。） 6. 非破坏式补充 .gitignore：忽略 .task/ 与 .Knowledge/update-check.json 这类本地运行态。 7. 规则与技能在各 agent 配置根加载；其他模版类文件在 .Knowledge/template/ 等目录。 @@ -795,6 +790,8 @@ if (sub === "init") { const { root, label } = AGENTS[id]; if (id === "codex") return ` - ${root}/：（${label}）skills/、topics/、hooks/、hooks.json、AGENTS.md（指针）；仓库根 AGENTS.md（完整）`; + if (id === "dsh") + return ` - ${root}/：（${label}）skills/、topics/、AGENTS.md（指针）；根 AGENTS.md（缺少时生成）`; if (id === "claude") { const hookLine = claudeHooksResult?.settingsChanged ? "rules/、skills/、hooks/f2s-config-session.js、hooks/f2s-config-inject.js、settings.json（已写入 f2s SessionStart/PreToolUse hooks）" 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 f6aa482..29b2982 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" @@ -415,7 +415,7 @@ Flow2Spec 提供三个互补命令，按触发方式与粒度区分：

适合什么项目与快速体验

-**最适合**：中大型业务项目、长期维护的代码仓库、多人协作规则很多的项目、经常使用 Cursor / Claude Code / Codex 的团队、希望 AI 不只是"看文档"而是参与维护项目知识的场景。 +**最适合**：中大型业务项目、长期维护的代码仓库、多人协作规则很多的项目、经常使用多个 AI 编程客户端的团队、希望 AI 不只是"看文档"而是参与维护项目知识的场景。 **可能不适合**：一次性脚本或非常小的个人项目（\< 5000 行，一份 README 够用）。 @@ -442,7 +442,7 @@ npx @double-coding/flow2spec@latest init ``` -目前已支持 Cursor、Claude Code、Codex 三端初始化，也支持中文 / 英文模板。 +目前支持按客户端初始化，也支持中文 / 英文模板；新增客户端可以沿用同一套知识库与技能分发模型。 --- diff --git a/docs/en/Flow2Spec-Introduction.md b/docs/en/Flow2Spec-Introduction.md index 9e13105..a493558 100644 --- a/docs/en/Flow2Spec-Introduction.md +++ b/docs/en/Flow2Spec-Introduction.md @@ -431,7 +431,7 @@ In short: **single Q&A → distill (auto), new module bulk import → add, perio

What projects and quick start

-**Best for**: medium to large business projects, long-lived codebases, multi-person teams with many rules, teams using Cursor / Claude Code / Codex regularly, and projects where you want AI to participate in maintaining project knowledge — not just read docs. +**Best for**: medium to large business projects, long-lived codebases, multi-person teams with many rules, teams using multiple AI coding clients, and projects where you want AI to participate in maintaining project knowledge — not just read docs. **May not fit**: one-off scripts or very small personal projects (\< 5000 lines, a README is enough). @@ -458,7 +458,7 @@ Common workflows: ``` -Currently supports initialization for Cursor, Claude Code, and Codex, with both Chinese and English templates. +Initialization is client-selectable and supports both Chinese and English templates; new clients can reuse the same knowledge-base and skill-distribution model. --- diff --git a/docs/en/architecture.md b/docs/en/architecture.md index ac05dab..77996ae 100644 --- a/docs/en/architecture.md +++ b/docs/en/architecture.md @@ -23,7 +23,7 @@ Four rings in the repo (do not collapse rules + skills into a single "third ring | --- | --- | --- | | **Knowledge** | `.Knowledge/` | Routing, topics, stock/req docs (§2 layers) | | **Task** | `.task/` | `todo.json`, checklists, user todos | -| **Rules** | `.cursor/.claude/.codex` rules, `AGENTS.md` | Read order, gap gates, execution constraints | +| **Rules** | `.cursor/.claude/.codex/.dsh` rules/topics, `AGENTS.md` | Read order, gap gates, execution constraints | | **Skills** | config root `skills/*/SKILL.md` | `f2s-kb-feat/fix/sync`, etc. | --- @@ -51,7 +51,7 @@ The pipeline `match → expand → verify → act` operates on L0–L2 (and L3 w | Layer | Location | Role | | --- | --- | --- | | Knowledge layer (knowledge ring) | `.Knowledge/` | Business docs, index, routing (§2 layers) | -| Execution layer (rules + skills rings) | `.cursor/.claude/.codex` | Rules and skill entry points | +| Execution layer (rules + skills rings) | `.cursor/.claude/.codex/.dsh` | Rules and skill entry points | --- diff --git a/docs/en/design-principles.md b/docs/en/design-principles.md index 6bccc74..71c025b 100644 --- a/docs/en/design-principles.md +++ b/docs/en/design-principles.md @@ -556,9 +556,9 @@ Each SKILL.md's orchestration section reads: #### 1. Tools are pluggable: one knowledge base, any tool combination ``` -flow2spec init cursor claude codex ← all three tools installed -flow2spec init claude ← only Claude -flow2spec init cursor codex ← skip Claude +flow2spec init ← initialize the requested tools +flow2spec init ← initialize one tool +flow2spec init ← add or skip tools as needed .Knowledge/ stays the same, tools can be added or removed at any time ``` diff --git a/docs/en/directory-conventions.md b/docs/en/directory-conventions.md index f929671..9899a14 100644 --- a/docs/en/directory-conventions.md +++ b/docs/en/directory-conventions.md @@ -6,7 +6,7 @@ - `.Knowledge/`: **Knowledge ring** — business docs and machine-readable routing ([architecture.md §2](./architecture.md)) - `.task/`: **Task ring** — change tracking (not inside `.Knowledge/`) -- `Config Root` (`.cursor/.claude/.codex`): **Rules ring + skills ring** +- `Config Root` (`.cursor/.claude/.codex/.dsh`): **Rules ring + skills ring** See [architecture.md §1](./architecture.md) for Memory Coding four rings. @@ -29,6 +29,8 @@ See [architecture.md §1](./architecture.md) for Memory Coding four rings. | `Config Root/skills/` | Skill definitions (`SKILL.md`) | | `Config Root/template/` | (Deprecated) No longer written to; historical directories may be cleaned up | | `.codex/AGENTS.md` | Codex unified entry point and loading instructions | +| `.dsh/AGENTS.md` | DeepSeek Harness directory pointer; the complete project entry remains root `AGENTS.md` | +| `.dsh/topics/` | Long-form rule mirrors loaded on demand by DeepSeek Harness | | `flow2spec.config.json` | Project root configuration, controls `subAgent`, `switchAgentVerification`, `changeTracking` (nested object with `feat` / `fix` / `implement` sub-items) | > See [Usage Guide Section 1](./usage-guide.md) for multi-platform references and path tables (detail maintained in a single table); **the authoritative source remains `Read(flow2spec.config.json)`**. diff --git a/docs/en/milestones.md b/docs/en/milestones.md index 5b49d8f..788c5c6 100644 --- a/docs/en/milestones.md +++ b/docs/en/milestones.md @@ -9,6 +9,7 @@ | Stage | Time | Summary | | --- | --- | --- | +| M28 · DeepSeek Harness project skill adapter | 2026-08-14 | Added `flow2spec init dsh`, distributing Flow2Spec skills to `.dsh/skills/`, mirroring rules to `.dsh/topics/`, and adapting the repository-root `AGENTS.md` entry; native Cordis plugin work remains on the roadmap | | M27 · npm org rename typo fix & migration | 2026-08-04 | Fixed npm org name typo codeing → coding; new package published as @double-coding/flow2spec 3.2.11; legacy @double-codeing/flow2spec 3.2.10 farewell release + npm deprecate all versions; README/CLI added bilingual migration notice; f2s-kb-upgrade Step -1 added D branch for automatic org rename migration (legacy pkg only) | | M26 · Automated knowledge merge engine and collaboration hardening | 2026-08 | Added five `flow2spec kb` commands, structured deltas, topic-revision optimistic locking, and an automatic skill merge path; tightened developerId fallbacks and blank-content validation; version reached 3.2.8 | | M25 · Per-developer task isolation | 2026-07 | Added collaboration settings and developerId resolution, isolating personal progress under separate task roots while retaining one shared knowledge base | @@ -75,7 +76,7 @@ - B: installed but behind → dispatch an independent sub-agent to run `npm i -g ...@latest` in the background (fire-and-forget); Step 2 uses `npx @latest init` - C: missing / latest unknown → same as B; if all probes fail, Step -1 can be skipped entirely - Step 2 command list default form is now driven by the Step -1 branch; added "manual override" clause and a "helper commands" note (`flow2spec --version` / `flow2spec update`) -- Added **`f2s-dev-workflow-constraints`** rule long text (Cursor / Claude / Codex, three ends): writes only to `templates/`, never to the config root; user drives distribution; dual repos stay in sync — **this rule lives only inside this repo, not in `templates/`**, so downstream projects never receive it +- Added **`f2s-dev-workflow-constraints`** rule long text: writes only to `templates/`, never to the config root; user drives distribution; dual repos stay in sync — **this rule lives only inside this repo, not in `templates/`**, so downstream projects never receive it - Added **`repo-dev-check`** self-check skill: on this repo, before committing, walks every pending change through the "templates vs config-root" decision table + dual-repo diff + distribution guidance; trigger words include "dual-repo drift", "write boundary", "templates vs config root" - `.Knowledge/topics/f2s-dev-workflow-constraints.md` thinned to a routing summary pointing to the config-root long text; matcher added new trigger words (`sync:agents`, `写盘边界`, `双仓漂移`); index.md topic table updated with related-doc column - Dual-repo sync for repo-local rule / skill: content contains the dual-repo package-name cross-reference table (`@double-coding` / `@ctrip`), so we sync byte-for-byte across repos without rewriting package names diff --git a/docs/en/usage-guide.md b/docs/en/usage-guide.md index e4c64bc..65ec39f 100644 --- a/docs/en/usage-guide.md +++ b/docs/en/usage-guide.md @@ -7,9 +7,9 @@ Execute in the project root: ```bash -flow2spec init [cursor|claude|codex ...] +flow2spec init [cursor|claude|codex|dsh ...] # To force reset .Knowledge from template: -flow2spec init [cursor|claude|codex ...] --reset-knowledge +flow2spec init [cursor|claude|codex|dsh ...] --reset-knowledge ``` | What `init` does | What `init` does NOT do | @@ -30,6 +30,7 @@ Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual val | **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Config reading remains rule-based: **Read(`flow2spec.config.json`)** before entering skill body. Cursor hooks are used for update checks only, not automatic config reads. | | **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` injects one config summary; `PreToolUse` only guards **`f2s-*` Skill** calls by reminding the agent that the first skill-body action must be **Read**. Neither replaces the disk read. | | **Codex** | root `AGENTS.md` mandatory step + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` field-semantics table + `.codex/hooks/f2s-config-session.js` | `SessionStart` injects one configuration summary; config reading still relies on text rules and **Read** as a hard requirement; the table explains field semantics only, does not write current values, and disk Read is authoritative. Codex has no Claude-style `PreToolUse` guard, so when `subAgent=true` the skill body must explicitly decide whether to split; even when it does not split, it must output the no-split reason. | +| **DeepSeek Harness** | root `AGENTS.md` (generated only when absent) + `.dsh/skills/` + `.dsh/topics/` | Harness loads project instructions from repository-root `AGENTS.md` and discovers project skills from `.dsh/skills//SKILL.md`; Flow2Spec mirrors long-form rules to `.dsh/topics/`. Native Cordis plugin integration is outside this adapter. | | **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. | For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.md). @@ -137,6 +138,8 @@ In interactive terminals, the Flow2Spec CLI checks the latest npm version with a After `flow2spec init codex`, Codex projects include `.codex/hooks.json`, `.codex/hooks/f2s-config-session.js`, and `.codex/hooks/f2s-update-check.js`. On Codex `SessionStart` for `startup|resume`, the first script injects one configuration summary and the second checks the knowledge-base version automatically. When the hook is first generated or changed, trust it through `/hooks` in Codex. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip only the version check. +After `flow2spec init dsh`, Flow2Spec writes project skills to `.dsh/skills/`, mirrors long-form rules to `.dsh/topics/`, and writes `.dsh/AGENTS.md` as a directory pointer. If the repository has no root `AGENTS.md`, init generates a Harness-compatible full entry; an existing root file is preserved. + After `flow2spec init cursor`, Cursor projects include `.cursor/hooks.json` and `.cursor/hooks/f2s-update-check.js`. The hook runs on Cursor `sessionStart` and injects upgrade reminders through `additional_context`. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip the check. After `flow2spec init claude`, Claude projects include `.claude/settings.json`, `.claude/hooks/f2s-config-session.js`, `.claude/hooks/f2s-config-inject.js`, and `.claude/hooks/f2s-update-check.js`: `SessionStart` injects the configuration summary and checks the knowledge-base version, while `PreToolUse Skill` only guards `f2s-*` Skill calls. The version-check script injects an agent-instruction notice through `additional_context`, requiring the agent to relay the message verbatim to the user. The notice format is: "Current project `` knowledge-base version v, lower than latest package version v. Run the f2s-kb-upgrade skill to align templates and routing." If today's cache still flags a needed upgrade, every new session re-injects the reminder; after a successful upgrade, `f2s-kb-upgrade` clears `.Knowledge/update-check.json` so stale reminders disappear. diff --git "a/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" "b/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" index 5108c48..927a398 100644 --- "a/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" +++ "b/docs/\344\275\223\347\263\273\344\270\216\345\216\237\347\220\206.md" @@ -23,7 +23,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并 | --- | --- | --- | | **知识环** | `.Knowledge/` | 路由、主题、存量/需求文档（见 §2 多层） | | **任务环** | `.task/` | `todo.json`、checklist、用户代办 | -| **规则环** | `.cursor/.claude/.codex` 下 rules、`AGENTS.md` | 读取顺序、缺口闸门、实现约束 | +| **规则环** | `.cursor/.claude/.codex/.dsh` 下 rules/topics、`AGENTS.md` | 读取顺序、缺口闸门、实现约束 | | **技能环** | 配置根 `skills/*/SKILL.md` | `f2s-kb-feat/fix/sync` 等维护与触发 | 与「两层结构」的关系：**知识环**对应「随项目走」的知识层；**规则环 + 技能环**落在各工具配置根，随工具升级迭代；**任务环**与 `.Knowledge/` 并列于仓内，不属于 `.Knowledge/` 目录。 @@ -53,7 +53,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并 | 层 | 位置 | 作用 | | --- | --- | --- | | 知识层（知识环） | `.Knowledge/` | 保存业务文档、索引、路由（§2 多层） | -| 执行层（规则环 + 技能环） | `.cursor/.claude/.codex` | 保存规则与技能入口 | +| 执行层（规则环 + 技能环） | `.cursor/.claude/.codex/.dsh` | 保存规则与技能入口 | --- @@ -199,7 +199,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV ## 8. 设计收益 1. 跨工具共享同一业务知识源 -2. 不破坏 Claude/Cursor/Codex 的规则加载习惯 +2. 不破坏各客户端原有的规则加载习惯 3. 通过 `manifest-routing` + `matcherPath` 分片（`matchers/*.json`）控制任务路由与依赖，减少误读与全量扫描 4. 主/子 agent 职责边界清晰，主 agent 始终持有全局视图，子 agent 专注单元处理，汇总一致性由主 agent 保证 5. 验证归属可配置：默认落盘侧自验保持低开销，交叉验证按需启用提升关键场景置信度 diff --git "a/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" "b/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" index 7f7f815..df6a496 100644 --- "a/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" +++ "b/docs/\344\275\277\347\224\250\350\257\264\346\230\216.md" @@ -7,11 +7,11 @@ 在业务仓库根执行： ```bash -flow2spec init [cursor|claude|codex ...] +flow2spec init [cursor|claude|codex|dsh ...] # 使用英文模板： -flow2spec init [cursor|claude|codex ...] --locale en-US +flow2spec init [cursor|claude|codex|dsh ...] --locale en-US # 需要强制重置 .Knowledge 到模板时： -flow2spec init [cursor|claude|codex ...] --reset-knowledge +flow2spec init [cursor|claude|codex|dsh ...] --reset-knowledge ``` @@ -39,6 +39,7 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge | **Cursor** | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`） | 配置读取走文本约束：技能正文前先 **Read(`flow2spec.config.json`)**；Cursor hook 仅用于版本更新检测，不自动读取配置。 | | **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` 仅注入一次配置摘要；`PreToolUse` 仅在调用 **`f2s-*` Skill** 时做守门提示，提醒首步必须 **Read**。两者都不替代磁盘 Read。 | | **Codex** | 根 `AGENTS.md` 顶部强制步骤 + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` 字段语义表 + `.codex/hooks/f2s-config-session.js` | `SessionStart` 注入一次配置摘要；配置读取仍以文本约束 + **Read** 为硬要求；表格只说明字段语义，不写当前值，配置真值以磁盘 **Read** 为准。Codex 无 Claude 的 `PreToolUse` 守门，`subAgent=true` 时需在技能正文前段显式判断是否拆子；即使不拆，也必须输出不拆原因。 | +| **DeepSeek Harness** | 根 `AGENTS.md`（缺少时由 init 生成） + `.dsh/skills/` + `.dsh/topics/` | Harness 从仓库根 `AGENTS.md` 加载项目说明，并从 `.dsh/skills//SKILL.md` 发现项目技能；Flow2Spec 将规则长文镜像到 `.dsh/topics/`。本轮适配不包含原生 Cordis 插件。 | | **知识库（可选）** | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时 | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。 | @@ -124,6 +125,8 @@ Flow2Spec CLI 在交互式执行 `flow2spec version` / `flow2spec init` 时会 Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json`、`.codex/hooks/f2s-config-session.js` 与 `.codex/hooks/f2s-update-check.js`：前者在 Codex `SessionStart` 的 `startup|resume` 事件注入一次配置摘要，后者自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 `/hooks` 信任该项目 hook。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时仅跳过版本检查，不影响配置摘要注入。 +DeepSeek Harness 项目执行 `flow2spec init dsh` 后，Flow2Spec 会把项目级技能写入 `.dsh/skills/`，把规则长文镜像到 `.dsh/topics/`，并生成 `.dsh/AGENTS.md` 目录指针。若仓库根没有 `AGENTS.md`，init 会生成一份适配 Harness 的完整入口；若已有该文件则保留用户内容，不覆盖。 + Cursor 项目执行 `flow2spec init cursor` 后会写入 `.cursor/hooks.json` 与 `.cursor/hooks/f2s-update-check.js`，在 Cursor `sessionStart` 自动检查知识库版本；脚本通过 `additional_context` 把升级提示注入会话。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时跳过检查。 Claude 项目执行 `flow2spec init claude` 后会写入 `.claude/settings.json`、`.claude/hooks/f2s-config-session.js`、`.claude/hooks/f2s-config-inject.js` 与 `.claude/hooks/f2s-update-check.js`：`SessionStart` 注入配置摘要并检查知识库版本，`PreToolUse Skill` 仅在调用 `f2s-*` Skill 前做守门提示。版本检查脚本通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户），格式为："当前项目「<项目名>」知识库版本 v<当前版本>，低于最新包版本 v<最新版本>。可执行 f2s-kb-upgrade skill 对齐模板与路由。"若当天缓存仍标记需升级，新会话每次都会重新注入提示；升级成功后 `f2s-kb-upgrade` 会清理 `.Knowledge/update-check.json`，避免旧提示残留。 diff --git "a/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" "b/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" index 6a73f00..8553a8e 100644 --- "a/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" +++ "b/docs/\347\233\256\345\275\225\344\270\216\350\267\257\345\276\204\347\272\246\345\256\232.md" @@ -6,7 +6,7 @@ - `.Knowledge/`：**知识环**——业务知识文档与机读路由（见 [体系与原理 §2 多层记忆](./体系与原理.md)） - `.task/`：**任务环**——变更追踪与跨会话续作（不在 `.Knowledge/` 内） -- `配置根`（`.cursor/.claude/.codex`）：**规则环 + 技能环**入口 +- `配置根`（`.cursor/.claude/.codex/.dsh`）：**规则环 + 技能环**入口 Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。 @@ -29,6 +29,8 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。 | `配置根/skills/` | 技能定义（`SKILL.md`） | | `配置根/template/` | （废弃）不再写入；历史目录可清理 | | `.codex/AGENTS.md` | Codex 统一入口与加载说明 | +| `.dsh/AGENTS.md` | DeepSeek Harness 目录指针；完整项目入口仍是根 `AGENTS.md` | +| `.dsh/topics/` | DeepSeek Harness 按需读取的规则长文镜像 | | `flow2spec.config.json` | 项目根配置，控制 `subAgent`、`switchAgentVerification`、`changeTracking`（嵌套对象，含 `feat` / `fix` / `implement` 三个子项） | > 多端提示与路径表见 [使用说明 § 一](./使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。 diff --git "a/docs/\351\241\271\347\233\256\351\207\214\347\250\213\347\242\221.md" "b/docs/\351\241\271\347\233\256\351\207\214\347\250\213\347\242\221.md" index 7026746..c152fa9 100644 --- "a/docs/\351\241\271\347\233\256\351\207\214\347\250\213\347\242\221.md" +++ "b/docs/\351\241\271\347\233\256\351\207\214\347\250\213\347\242\221.md" @@ -9,6 +9,7 @@ | 阶段 | 时间 | 摘要 | | --- | --- | --- | +| M28 · DeepSeek Harness 项目级技能适配 | 2026-08-14 | 新增 `flow2spec init dsh`，将 Flow2Spec 技能分发到 `.dsh/skills/`，规则镜像到 `.dsh/topics/`，并适配根 `AGENTS.md` 入口；原生 Cordis 插件列入后续路线图 | | M27 · npm 组织名拼写修正与迁移 | 2026-08-04 | 修正 npm 组织名 codeing → coding，新包发布在 @double-coding/flow2spec 3.2.11；旧包 @double-codeing/flow2spec 3.2.10 收官 + npm deprecate 全版本告知；README/CLI 增加双语迁移公告，f2s-kb-upgrade 步骤 -1 增加 D 分支自动完成组织名迁移（仅存在于旧包收官版） | | M26 · 知识库自动合并引擎与协作边界加固 | 2026-08 | 新增 `flow2spec kb` 五命令、结构化 delta、topic revision 乐观锁与技能自动合并链路；强化 developerId 降级与空 content 校验边界，版本进入 3.2.8 | | M25 · 多人任务按 developerId 隔离 | 2026-07 | 新增协作开关与 developerId 解析链路，将个人任务进度隔离到独立任务根，同时保持共享知识库统一协作 | @@ -23,7 +24,7 @@ | M16 · 意图识别开关与路由规则 | 2026-06-08 | 新增 intentRecognition 配置开关与 f2s-intent-routing 规则；高置信操作意图可受控自动分流到 f2s 技能 | | M15 · 全端技术方案与普通问答收口 | 2026-06-05 | f2s-req-backend 升级为 f2s-req-tech，技术方案模板扩展为前后端/全栈通用；普通问答源码补答后增加知识库补充建议收口 | | M14 · f2s-git-commit 快捷提交 | 2026-06-04 | f2s-git-commit 新增快捷提交模式，跳过知识库覆盖检查但保留 diff、精确 add、hooks 与提交信息展示 | -| M13 · 更新检测与三端启动提醒 | 2026-06-04 | 新增 updateCheck.enabled 配置、版本检查 hook、自然日缓存；Claude/Cursor/Codex 三端 SessionStart 注入升级提示 | +| M13 · 更新检测与客户端启动提醒 | 2026-06-04 | 新增 updateCheck.enabled 配置、版本检查 hook、自然日缓存；为当时已支持的客户端注入升级提示 | | M12 · 主题分类与 init 合并校验 | 2026-06-03 | topicMetadata 支持 primary/tags/confidence；init 支持合并校验与模板优先覆盖；多个 skill 统一重命名到 kb-/doc- 前缀 | | M11 · 知识工程规范与 skill 骨架 | 2026-06-03 | 新增 skill-authoring 规范、f2s-kb-addRules 口述规则沉淀能力、f2s-topic-authoring 创作侧准则和大功能拆分策略 | | M10 · 文档沉淀规则补强 | 2026-05-27 | f2s-doc-add 增加多模块检测；双仓包名规则落地；全局规则补充否定式表达禁止约束 | @@ -75,7 +76,7 @@ - B 已装但落后 → 派独立子 agent 后台跑 `npm i -g ...@latest`（fire-and-forget）；步骤 2 用 `npx @latest init` - C 未装 / latest 未知 → 按 B 处理；探测全失败可整体跳过步骤 -1 - 步骤 2 命令清单默认形态随步骤 -1 分支选定；补「手动 override」条款与「辅助命令」小节（`flow2spec --version` / `flow2spec update`） -- 新增 **`f2s-dev-workflow-constraints`** 规则长文（Cursor / Claude / Codex 三端）：Flow2Spec 双仓自身开发的写盘边界与分发口径——只改 templates、不改配置根、用户驱动分发、双仓一致；**本规则只存本仓、不进 templates**，下游拿不到 +- 新增 **`f2s-dev-workflow-constraints`** 规则长文：Flow2Spec 双仓自身开发的写盘边界与分发口径——只改 templates、不改配置根、用户驱动分发、双仓一致；**本规则只存本仓、不进 templates**，下游拿不到 - 新增 **`repo-dev-check`** 自查 skill：本仓提交前逐份改动套「templates vs 配置根」判定表 + 双仓 diff + 分发建议；触发词包括「双仓漂移」「写盘边界」「templates vs 配置根」 - `.Knowledge/topics/f2s-dev-workflow-constraints.md` 打薄成路由摘要，指向配置根 rules 长文；matcher 补新触发词（`sync:agents` / `写盘边界` / `双仓漂移`）；index.md 主题一览同步更新关联文档列 - 本仓专属规则 / skill 的双仓同步义务：内容含双仓包名对照表（`@double-coding` / `@ctrip`），双仓采用**逐字节一致**同步策略，不做包名替换 @@ -158,7 +159,7 @@ - 保留 diff 读取、冲突检查、精确 add、git hooks 与提交信息首行展示 - 禁止自动 push / pull，保留用户确认环节 -## M13 · 更新检测与三端启动提醒 +## M13 · 更新检测与客户端启动提醒 - flow2spec.config.json 新增 updateCheck.enabled 配置 - 版本检查 hook 落地:manifest version 与 npm latest 比对;自然日缓存到 .Knowledge/update-check.json @@ -212,7 +213,7 @@ - flow2spec init codex 将完整规则写入仓库根 AGENTS.md - .codex/AGENTS.md 退化为指针，降低 Codex 自动发现规则缺失风险 -- 确立 Codex 三端（Claude/Cursor/Codex）规则注入各自配置根的统一模式 +- 确立各客户端将规则注入自身配置根的统一模式 ## M5 · CLI 运维命令与任务路由 diff --git a/lib/agents.js b/lib/agents.js index 0540dd6..d6937e7 100644 --- a/lib/agents.js +++ b/lib/agents.js @@ -6,6 +6,7 @@ const AGENTS = { cursor: { root: ".cursor", label: "Cursor" }, claude: { root: ".claude", label: "Claude" }, codex: { root: ".codex", label: "Codex" }, + dsh: { root: ".dsh", label: "DeepSeek Harness" }, }; const KNOWLEDGE_ROOT = ".Knowledge"; @@ -14,6 +15,7 @@ const AGENT_SUBDIRS = { cursor: ["rules", "skills"], claude: ["rules", "skills"], codex: ["skills"], + dsh: ["skills", "topics"], }; /** diff --git a/lib/doctor.js b/lib/doctor.js index 9433f07..b833ecd 100644 --- a/lib/doctor.js +++ b/lib/doctor.js @@ -183,7 +183,7 @@ function runDoctor(cwd = process.cwd(), options = {}) { "项目入口", STATUS.error, "缺少根 AGENTS.md。", - "运行 flow2spec init codex，或重新初始化所需 Agent。", + "运行 flow2spec init codex 或 flow2spec init dsh，或重新初始化所需 Agent。", ), ); @@ -207,6 +207,7 @@ function runDoctor(cwd = process.cwd(), options = {}) { const requiredAgentFiles = { codex: ["AGENTS.md", "hooks.json"], + dsh: ["AGENTS.md", "skills", "topics"], claude: ["settings.json"], cursor: ["hooks.json"], }; @@ -219,7 +220,7 @@ function runDoctor(cwd = process.cwd(), options = {}) { "agent-roots", "Agent 配置", STATUS.warning, - "未检测到 .codex、.claude 或 .cursor 配置根。", + "未检测到 .codex、.claude、.cursor 或 .dsh 配置根。", "运行 flow2spec init 初始化实际使用的 Agent。", ), ); diff --git a/lib/dshAgentsAdapter.js b/lib/dshAgentsAdapter.js new file mode 100644 index 0000000..09388fd --- /dev/null +++ b/lib/dshAgentsAdapter.js @@ -0,0 +1,81 @@ +const fs = require("fs"); +const path = require("path"); +const { buildCodexAgentsMd } = require("./codexAgentsAdapter"); + +function replaceSection(body, startHeading, endHeading, replacement) { + const start = body.indexOf(startHeading); + const end = body.indexOf(endHeading, start + startHeading.length); + if (start < 0 || end < 0) return body; + return `${body.slice(0, start)}${replacement.trim()}\n\n${body.slice(end)}`; +} + +function buildDshAgentsMd(templatesDir, projectConfig) { + let body = buildCodexAgentsMd(templatesDir, projectConfig) + .replace(/Codex/g, "DeepSeek Harness") + .replace(/codex/g, "dsh"); + + const isEnglish = path.basename(path.dirname(templatesDir)) === "templates" && + path.basename(templatesDir) === "en-US"; + if (isEnglish) { + body = body + .replace(" **`./.dsh/AGENTS.md`** is only a pointer.", "") + .replace("\n**`.dsh/AGENTS.md`** is only a pointer and cannot replace root `AGENTS.md`.\n", "\n"); + body = replaceSection( + body, + "## DeepSeek Harness Hooks", + "## Flow2Spec Skills", + `## DeepSeek Harness Integration + +DeepSeek Harness loads the repository-root \`AGENTS.md\` and discovers project skills from \`./.dsh/skills/\`. Flow2Spec mirrors its long-form rules to \`./.dsh/topics/\` for on-demand reading. Native Cordis plugin integration is outside this initialization adapter.`, + ); + return body; + } + + body = body + .replace("**`./.dsh/AGENTS.md`** 仅为指针。", "") + .replace("- **`.dsh/AGENTS.md`** 仅为目录指针，不能替代根 `AGENTS.md`。\n", ""); + return replaceSection( + body, + "## DeepSeek Harness Hooks", + "## Flow2Spec 技能", + `## DeepSeek Harness 适配 + +DeepSeek Harness 会加载仓库根 \`AGENTS.md\`，并从 \`./.dsh/skills/\` 发现项目技能。Flow2Spec 将规则长文镜像到 \`./.dsh/topics/\` 供按需读取。原生 Cordis 插件集成不属于本初始化适配范围。`, + ); +} + +function buildDshAgentsStubMd(templatesDir) { + const isEnglish = path.basename(templatesDir) === "en-US"; + if (isEnglish) { + return `# Flow2Spec (\`.dsh/\` Directory Notes) + +DeepSeek Harness loads the complete project instructions from repository-root [\`AGENTS.md\`](../AGENTS.md). + +- \`skills/\`: Flow2Spec \`f2s-*\` skills discovered by DeepSeek Harness +- \`topics/\`: long-form rule mirrors loaded on demand +`; + } + return `# Flow2Spec（\`.dsh/\` 目录说明） + +DeepSeek Harness 从仓库根 [\`AGENTS.md\`](../AGENTS.md) 加载完整项目说明。 + +- \`skills/\`：DeepSeek Harness 可发现的 Flow2Spec \`f2s-*\` 技能 +- \`topics/\`：按需读取的规则长文镜像 +`; +} + +function writeDshAgentsStub(cwd, templatesDir) { + const dshRoot = path.join(cwd, ".dsh"); + fs.mkdirSync(dshRoot, { recursive: true }); + fs.writeFileSync( + path.join(dshRoot, "AGENTS.md"), + buildDshAgentsStubMd(templatesDir), + "utf8", + ); +} + +module.exports = { + buildDshAgentsMd, + buildDshAgentsStubMd, + writeDshAgentsStub, +}; diff --git a/lib/init.js b/lib/init.js index b8c12cd..eda0a7a 100644 --- a/lib/init.js +++ b/lib/init.js @@ -15,6 +15,10 @@ const { buildCodexAgentsMd, buildCodexAgentsStubMd, } = require("./codexAgentsAdapter"); +const { + buildDshAgentsMd, + writeDshAgentsStub, +} = require("./dshAgentsAdapter"); const { loadFlow2specConfig, ensureFlow2specProjectConfig, @@ -1157,12 +1161,12 @@ function stripMdcFrontmatter(src) { return src.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, ""); } -function writeCodexTopicMirrors(cwd, templatesDir) { +function writeTopicMirrors(cwd, templatesDir, agentRoot) { const rulesDir = path.join(templatesDir, "rules"); - const outDir = path.join(cwd, ".codex", "topics"); + const outDir = path.join(cwd, agentRoot, "topics"); ensureDir(outDir); if (!fs.existsSync(rulesDir)) return; - // 与 `.cursor/rules/*.mdc` 同源：Codex 不读 rules/，故镜像全部包模板规则到 `.codex/topics/*.md` + // Mirror rule templates for clients that load long-form guidance on demand. const names = fs .readdirSync(rulesDir) .filter((n) => { @@ -1180,6 +1184,10 @@ function writeCodexTopicMirrors(cwd, templatesDir) { } } +function writeCodexTopicMirrors(cwd, templatesDir) { + writeTopicMirrors(cwd, templatesDir, ".codex"); +} + /** * 完整条令写仓库根；.codex/AGENTS.md 仅为指针，避免双份全文重复与 cwd 在 .codex 时双倍拼接。 */ @@ -1191,11 +1199,27 @@ function writeCodexEntry(cwd, templatesDir, projectConfig) { writeCodexTopicMirrors(cwd, templatesDir); } +/** Write the root instructions needed by DeepSeek Harness without overwriting an existing entry. */ +function writeDshEntry(cwd, templatesDir, projectConfig) { + const agentsPath = path.join(cwd, "AGENTS.md"); + if (!fs.existsSync(agentsPath)) { + fs.writeFileSync( + agentsPath, + buildDshAgentsMd(templatesDir, projectConfig), + "utf8", + ); + } + writeDshAgentsStub(cwd, templatesDir); + writeTopicMirrors(cwd, templatesDir, ".dsh"); +} + function writeAgentArtifacts(cwd, agentId, templatesDir, projectConfig) { const root = AGENTS[agentId].root; copySkills(cwd, root, templatesDir); removeLegacyAgentTemplateDir(cwd, root); - if (agentId !== "codex") { + if (agentId === "dsh") { + writeDshEntry(cwd, templatesDir, projectConfig); + } else if (agentId !== "codex") { copyRulesTemplates(cwd, root, templatesDir); } else { writeCodexEntry(cwd, templatesDir, projectConfig); diff --git a/package.json b/package.json index a905b32..2d2bb9e 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,7 @@ "registry": "https://registry.npmjs.org/" }, "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-doctor.js", + "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", "sync:agents": "node cli.js init cursor claude codex", "prepublishOnly": "node cli.js --help", "pack:check": "npm pack --dry-run", diff --git a/presentations/flow2spec-intro-public-en/index.html b/presentations/flow2spec-intro-public-en/index.html index 10d9332..f54c1f6 100644 --- a/presentations/flow2spec-intro-public-en/index.html +++ b/presentations/flow2spec-intro-public-en/index.html @@ -309,8 +309,8 @@

①
Multi-Platform
- One .Knowledge/ · Cursor / Claude / Codex - natively coexist + One .Knowledge/ · any configured client + natively coexists
diff --git a/presentations/flow2spec-intro-public/index.html b/presentations/flow2spec-intro-public/index.html index 953a74a..60b887a 100644 --- a/presentations/flow2spec-intro-public/index.html +++ b/presentations/flow2spec-intro-public/index.html @@ -319,7 +319,7 @@

①
多端复用
- .Knowledge/ 一份 · Cursor / Claude / Codex + .Knowledge/ 一份 · 任意已配置客户端 原生加载并存

@@ -935,7 +935,7 @@

会话断了 · AI 自己接上

- 一个横跨三端、9 步、分多次会话完成的真实任务 —— + 一个横跨多个客户端、9 步、分多次会话完成的真实任务 —— 中途任何一次下班关机，下次只说一句「继续」。

@@ -1016,7 +1016,7 @@

// 续作体验

    -
  • 真实任务：三端 · 9 步 · 多次会话
    • +
  • 真实任务：多客户端 · 9 步 · 多次会话
  • 只说「继续」→ todo.json 命中 → task.md 断点续作 diff --git a/presentations/flow2spec-intro-public/market-compare.md b/presentations/flow2spec-intro-public/market-compare.md index 5ff8bab..b4f21a5 100644 --- a/presentations/flow2spec-intro-public/market-compare.md +++ b/presentations/flow2spec-intro-public/market-compare.md @@ -16,7 +16,7 @@ | 维度 | 说的是什么 | 不满足会怎样 | |---|---|---| -| ① **多端复用** | 一份知识，Cursor / Claude / Codex / 未来新 IDE 都能用 | 换工具重写一份，团队分裂 | +| ① **多端复用** | 一份知识，当前客户端与未来新 IDE 都能用 | 换工具重写一份，团队分裂 | | ② **路由收窄** | 一句话命中一个 topic，只读相关那 300 行 | 系统提示词扁平，token 爆、拿错段 | | ③ **双向同步** | 改代码顺手改知识（`f2s-kb-feat/fix`），不是一次性生成 | 第二次迭代 spec 和 code 分家 | | ④ **原生 agent** | 规则 + 知识喂给现有 agent，不劫持、不做 wrapper | 跟 IDE 抢主导权，新模型来了跟不上 | @@ -76,7 +76,7 @@ | ① 多端复用 | `.Knowledge/` 是事实源，`.cursor/.claude/.codex/` 各自按原生方式挂载规则 | | ② 路由收窄 | `manifest-routing.json` + `matchers/*.json` 机读命中 → 依赖链展开 → **缺口闸门**强制澄清 | | ③ 双向同步 | `f2s-kb-feat` / `f2s-kb-fix` 强制「改代码带着改知识」 | -| ④ 原生 agent | 只提供 rules + skills + knowledge，执行仍走 Cursor / Claude / Codex 原生 | +| ④ 原生 agent | 只提供 rules + skills + knowledge，执行仍走各客户端原生能力 | | ⑤ 变更留痕 + 收尾闸门 | `.task/todo.json` + `task.md` + `user-todos.md`，跨会话可续作；`f2s-git-commit` 提交前强制「冲突扫 / KB 覆盖查 / emoji+Conventional 首行」三查 | --- diff --git "a/presentations/flow2spec-intro-public/\346\274\224\350\256\262\347\250\277.md" "b/presentations/flow2spec-intro-public/\346\274\224\350\256\262\347\250\277.md" index 469e1a9..48e86f0 100644 --- "a/presentations/flow2spec-intro-public/\346\274\224\350\256\262\347\250\277.md" +++ "b/presentations/flow2spec-intro-public/\346\274\224\350\256\262\347\250\277.md" @@ -119,7 +119,7 @@ Flow2Spec 五条：**多端复用** · **路由收窄**（缺口闸门）· ** ## 第 9 页 · 任务续作 -**会话断了 · AI 自己接上**。真实任务：三端、**9 步**、多次会话；下次只说「**继续**」。 +**会话断了 · AI 自己接上**。真实任务：多个客户端、**9 步**、多次会话；下次只说「**继续**」。 左：`.task/completed/.../task.md` 九步清单（屏上步骤 1～9）。 右：关键词命中 `todo.json` → 读剩余步骤、加载规则技能、断点续作。 diff --git a/scripts/test-dsh-init.js b/scripts/test-dsh-init.js new file mode 100644 index 0000000..6b7095f --- /dev/null +++ b/scripts/test-dsh-init.js @@ -0,0 +1,44 @@ +const assert = require("assert"); +const fs = require("fs"); +const os = require("os"); +const path = require("path"); + +const runInit = require("../lib/init"); + +(async () => { + for (const locale of ["zh-CN", "en-US"]) { + const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), `flow2spec-dsh-${locale}-`)); + try { + const result = await runInit(tmpRoot, ["dsh"], { + configValues: { locale }, + }); + + assert.deepStrictEqual(result.ids, ["dsh"]); + assert(fs.existsSync(path.join(tmpRoot, ".dsh", "skills", "f2s-kb-feat", "SKILL.md"))); + assert(fs.existsSync(path.join(tmpRoot, ".dsh", "topics", "f2s-task.md"))); + assert(fs.existsSync(path.join(tmpRoot, ".dsh", "AGENTS.md"))); + assert(fs.existsSync(path.join(tmpRoot, "AGENTS.md"))); + assert(fs.existsSync(path.join(tmpRoot, ".Knowledge", "topics", "flow2spec-dsh-adapter.md"))); + assert(fs.existsSync(path.join(tmpRoot, ".Knowledge", "matchers", "m-flow2spec-dsh-adapter.json"))); + + const entry = fs.readFileSync(path.join(tmpRoot, "AGENTS.md"), "utf8"); + assert(entry.includes(locale === "zh-CN" ? "DeepSeek Harness" : "DeepSeek Harness")); + assert(entry.includes(locale === "zh-CN" ? ".dsh/skills" : ".dsh/skills")); + + await runInit(tmpRoot, ["dsh"], { configValues: { locale } }); + assert(fs.existsSync(path.join(tmpRoot, ".dsh", "skills", "f2s-kb-feat", "SKILL.md"))); + + const preservedRoot = path.join(tmpRoot, "AGENTS.md"); + fs.writeFileSync(preservedRoot, "# user-owned entry\n", "utf8"); + await runInit(tmpRoot, ["dsh"], { configValues: { locale } }); + assert.strictEqual(fs.readFileSync(preservedRoot, "utf8"), "# user-owned entry\n"); + } finally { + fs.rmSync(tmpRoot, { recursive: true, force: true }); + } + } + + console.log("dsh init tests passed"); +})().catch((error) => { + console.error(error); + process.exit(1); +}); diff --git a/templates/en-US/knowledge/index.md b/templates/en-US/knowledge/index.md index f9cb66e..f31add5 100644 --- a/templates/en-US/knowledge/index.md +++ b/templates/en-US/knowledge/index.md @@ -28,6 +28,7 @@ The **machine-readable source of truth** is `.Knowledge/manifest-routing.json` p | config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | Read `flow2spec.config.json` / orchestration switches before executing `f2s-*` | Codex long-form: repository-root `.codex/topics/f2s-config-check.md`; [routing summary](topics/f2s-config-precheck.md) | | f2s-task | `.Knowledge/topics/f2s-task.md` | Change tracking, `.task/` task lists, and cross-session resume | Long-form: configuration-root `rules/f2s-task.*`; Codex: `.codex/topics/f2s-task.md` | | f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | Requirement/spec planning and implementation; always maintain `.task/` | Skill: `skills/f2s-req-plan/SKILL.md`; depends on `f2s-task` | +| flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh` and DeepSeek Harness project skill discovery | User guide: `docs/en/usage-guide.md`; implementation: `lib/dshAgentsAdapter.js` | Keep **1-3** clickable summary links per topic. Full path mappings are written to `.Knowledge/migration-report.md` in migration scenarios. Among these, **`implement-tech-design`**, **`f2s-doc-routing`**, **`config-precheck`**, and **`f2s-task`** are **routing summaries** under `topics/`; long-form execution instructions live in configuration-root **`rules/f2s-*.md(c)`**. When using Codex, see **`.codex/AGENTS.md`** and **`.codex/topics/f2s-*.md`** (`f2s-config-check` shares the same pre-step source as `AGENTS`; open on demand). **`f2s-knowledge-preflight`** and **`f2s-kb-feedback-closing`** are gates for initial reads in ordinary Q&A and closure after source-code supplementation. They are effective as configuration-root rules / Codex long-form topics and are not written into `topicPaths` or `taskToTopicRules`. diff --git a/templates/en-US/knowledge/manifest-routing.json b/templates/en-US/knowledge/manifest-routing.json index 7924ddb..41feb7f 100644 --- a/templates/en-US/knowledge/manifest-routing.json +++ b/templates/en-US/knowledge/manifest-routing.json @@ -40,6 +40,11 @@ "f2s-req-plan": { "primary": "policy", "confidence": "manual" + }, + "flow2spec-dsh-adapter": { + "primary": "feature", + "confidence": "inferred", + "tags": ["module"] } }, "topicPaths": { @@ -48,7 +53,8 @@ "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md", "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", "f2s-task": ".Knowledge/topics/f2s-task.md", - "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md" + "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", + "flow2spec-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.md" }, "taskToTopicRules": [ { @@ -91,6 +97,14 @@ "topics": [ "f2s-req-plan" ] + }, + { + "task": "flow2spec-dsh-adapter", + "matcherId": "m-flow2spec-dsh-adapter", + "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", + "topics": [ + "flow2spec-dsh-adapter" + ] } ] } diff --git a/templates/en-US/knowledge/matchers/m-flow2spec-dsh-adapter.json b/templates/en-US/knowledge/matchers/m-flow2spec-dsh-adapter.json new file mode 100644 index 0000000..e7a277e --- /dev/null +++ b/templates/en-US/knowledge/matchers/m-flow2spec-dsh-adapter.json @@ -0,0 +1,6 @@ +{ + "includeAny": ["DeepSeek Harness", "deepseek-harness", "dsh", "flow2spec init dsh", ".dsh/skills", ".dsh/topics", "Cordis plugin", "Harness adapter"], + "id": "m-flow2spec-dsh-adapter", + "version": "1.0.0", + "schema": "flow2spec.matcher.v1" +} diff --git a/templates/en-US/knowledge/topics/flow2spec-dsh-adapter.md b/templates/en-US/knowledge/topics/flow2spec-dsh-adapter.md new file mode 100644 index 0000000..7223d7e --- /dev/null +++ b/templates/en-US/knowledge/topics/flow2spec-dsh-adapter.md @@ -0,0 +1,16 @@ +--- +id: flow2spec-dsh-adapter +revision: 0 +summary: "DeepSeek Harness project skill initialization and directory adapter" +primary: feature +confidence: inferred +tags: [module] +--- +# DeepSeek Harness Adapter + +Use this topic for `flow2spec init dsh`, DeepSeek Harness skill discovery, `.dsh/skills`, `.dsh/topics`, and the repository-root `AGENTS.md` entry. + +- Skills are written to `.dsh/skills//SKILL.md`. +- Long-form rules are mirrored to `.dsh/topics/*.md`, with `.dsh/AGENTS.md` as a directory pointer. +- A missing root `AGENTS.md` receives a full entry; an existing entry is preserved. +- Native Cordis plugin work remains a later roadmap item. diff --git a/templates/en-US/rules/f2s-flow2spec-unified-entry.md b/templates/en-US/rules/f2s-flow2spec-unified-entry.md index 8c4a55c..0d01fa3 100644 --- a/templates/en-US/rules/f2s-flow2spec-unified-entry.md +++ b/templates/en-US/rules/f2s-flow2spec-unified-entry.md @@ -92,7 +92,7 @@ Some environments create an **independent `git worktree`** or equivalent isolate ## Knowledge-Base Version Self-Check (Hook Auto-Triggered; First Time Each Day Only When updateCheck.enabled=true) -All three clients register a SessionStart version-check script: Cursor writes **`.cursor/hooks.json`** through `flow2spec init cursor` and runs `node .cursor/hooks/f2s-update-check.js` at `sessionStart`; Codex writes **`.codex/hooks.json`** through `flow2spec init codex` and registers both the configuration-summary script `node .codex/hooks/f2s-config-session.js` and the version-check script `node .codex/hooks/f2s-update-check.js` on `SessionStart` `startup|resume`; Claude writes **`.claude/settings.json`** through `flow2spec init claude` and registers the configuration summary, version check, and `PreToolUse Skill` guard. After the version-check script compares versions and writes cache, when an upgrade is needed it injects an imperative upgrade notice through `additional_context` (agent-instruction text requires the agent to relay it to the user verbatim). +Each initialized client uses its own startup/update mechanism when supported; the generated client entrypoint is authoritative. Clients without hooks continue to use the generated rules, skills, `AGENTS.md`, or topic mirrors. Version-check scripts compare versions and, when an upgrade is needed, inject an imperative upgrade notice through `additional_context` where the client supports it. Project-level skill discovery clients use `.dsh/skills/` and `.dsh/topics/` through `flow2spec init dsh`. **Rule-layer fallback check** (backup for script cache): diff --git a/templates/en-US/skills/f2s-kb-upgrade/SKILL.md b/templates/en-US/skills/f2s-kb-upgrade/SKILL.md index a070d1a..9133c8d 100644 --- a/templates/en-US/skills/f2s-kb-upgrade/SKILL.md +++ b/templates/en-US/skills/f2s-kb-upgrade/SKILL.md @@ -62,8 +62,8 @@ description: Knowledge-base template upgrade skill (this SKILL only): **V1 flow - **One-click closure for old projects**: **first `f2s-kb-migrate`** -> **then this skill** (`init`). Do not use only `init` as a substitute for full migration. - **Projects already using new `.Knowledge`**: **run only this skill**; do not repeat migrate. -**Why does each Cursor / Claude / Codex directory have a same-named `SKILL.md`?** -Each tool only loads `skills/` under **its own configuration root** (for example, Codex only loads `.codex/skills/`). `flow2spec init` writes the current-language skill content into the selected agent directories. +**Why does each configured client directory have a same-named `SKILL.md`?** +Each client only loads `skills/` under **its own configuration root**. `flow2spec init` writes the current-language skill content into the selected agent directories. ## Goal @@ -73,7 +73,7 @@ When the user says "help me upgrade the knowledge-base template / run f2s-kb-upg 1. When this skill's step 2 runs **`flow2spec init`**, it defaults to **incremental write** (without `--reset-knowledge`). 2. Append `--reset-knowledge` only when the user explicitly requests "overwrite reset". -3. Prefer agents specified by the user; if unspecified, default to `cursor claude codex`. +3. Prefer agents specified by the user; if unspecified, use the package's default client selection. ## init and Skill Self-Update (Required) diff --git a/templates/en-US/skills/f2s-req-plan/SKILL.md b/templates/en-US/skills/f2s-req-plan/SKILL.md index 9ab4049..f9eb769 100644 --- a/templates/en-US/skills/f2s-req-plan/SKILL.md +++ b/templates/en-US/skills/f2s-req-plan/SKILL.md @@ -18,13 +18,7 @@ Start from a requirement or technical design and cover the full "plan -> impleme | **This skill's responsibility** | Planning draft, code implementation, and sub-agent orchestration; **must not** define a custom `.task/` structure or weaken checkbox/archive requirements | | **Relationship with changeTracking** | `f2s-req-plan` is **not constrained by** `changeTracking.feat/fix/implement`; it **always** uses task lists. See `f2s-task` "Activation Conditions" | -**All three clients must read the full `f2s-task` text (Step 0 is mandatory, before any step below):** - -| Client | Path | -| --- | --- | -| **Cursor** | Config-root `rules/f2s-task.mdc`; or initialized `.cursor/rules/f2s-task.mdc` | -| **Claude Code** | `.claude/rules/f2s-task.md` | -| **Codex** | `.codex/topics/f2s-task.md` | +**Every client initialized for the project must read the full `f2s-task` text (Step 0 is mandatory, before any step below).** Use the active client's generated rules, `AGENTS.md`, or topic entrypoint; do not substitute this skill's summary for the full text. ## Orchestration (main / sub agent) @@ -46,7 +40,7 @@ Start from a requirement or technical design and cover the full "plan -> impleme ### Step 0: Preflight (Mandatory, Before Any Step) 1. **`Read("flow2spec.config.json")`** (project root; missing fields are treated as `false`). -2. **`Read` the full `f2s-task` text for one of the three clients above** (do not skip; do not use only this SKILL summary as a substitute). +2. **`Read` the full `f2s-task` text from the active client's generated entrypoint** (do not skip; do not use only this SKILL summary as a substitute). 3. Decide whether to split to sub agents and whether to cross-verify based on the read `subAgent` / `switchAgentVerification` values. ### Step 1: Continuation Triage + Parse Input diff --git a/templates/zh-CN/knowledge/index.md b/templates/zh-CN/knowledge/index.md index 8f6f507..bce6b9d 100644 --- a/templates/zh-CN/knowledge/index.md +++ b/templates/zh-CN/knowledge/index.md @@ -28,6 +28,7 @@ | config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | 执行 `f2s-*` 前读 `flow2spec.config.json` / 编排开关 | Codex 长文：仓库根 `.codex/topics/f2s-config-check.md`；[路由摘要](topics/f2s-config-precheck.md) | | f2s-task | `.Knowledge/topics/f2s-task.md` | 变更追踪、`.task/` 任务清单与跨会话续作 | 长文：配置根 `rules/f2s-task.*`；Codex：`.codex/topics/f2s-task.md` | | f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | 需求/方案规划与实现；始终维护 `.task/` | 技能：`skills/f2s-req-plan/SKILL.md`；依赖 `f2s-task` | +| flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh` 与 DeepSeek Harness 项目技能发现 | 用户文档：`docs/使用说明.md`；实现：`lib/dshAgentsAdapter.js` | 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。 其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。**`f2s-knowledge-preflight`** 与 **`f2s-kb-feedback-closing`** 是普通问答首读 / 源码补答收口门禁，作为配置根规则 / Codex 专题长文生效，不写入 `topicPaths` 或 `taskToTopicRules`。 diff --git a/templates/zh-CN/knowledge/manifest-routing.json b/templates/zh-CN/knowledge/manifest-routing.json index 7924ddb..41feb7f 100644 --- a/templates/zh-CN/knowledge/manifest-routing.json +++ b/templates/zh-CN/knowledge/manifest-routing.json @@ -40,6 +40,11 @@ "f2s-req-plan": { "primary": "policy", "confidence": "manual" + }, + "flow2spec-dsh-adapter": { + "primary": "feature", + "confidence": "inferred", + "tags": ["module"] } }, "topicPaths": { @@ -48,7 +53,8 @@ "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md", "config-precheck": ".Knowledge/topics/f2s-config-precheck.md", "f2s-task": ".Knowledge/topics/f2s-task.md", - "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md" + "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md", + "flow2spec-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.md" }, "taskToTopicRules": [ { @@ -91,6 +97,14 @@ "topics": [ "f2s-req-plan" ] + }, + { + "task": "flow2spec-dsh-adapter", + "matcherId": "m-flow2spec-dsh-adapter", + "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json", + "topics": [ + "flow2spec-dsh-adapter" + ] } ] } diff --git a/templates/zh-CN/knowledge/matchers/m-flow2spec-dsh-adapter.json b/templates/zh-CN/knowledge/matchers/m-flow2spec-dsh-adapter.json new file mode 100644 index 0000000..0ff8c89 --- /dev/null +++ b/templates/zh-CN/knowledge/matchers/m-flow2spec-dsh-adapter.json @@ -0,0 +1,6 @@ +{ + "includeAny": ["DeepSeek Harness", "deepseek-harness", "dsh", "flow2spec init dsh", ".dsh/skills", ".dsh/topics", "Cordis 插件", "Harness 适配"], + "id": "m-flow2spec-dsh-adapter", + "version": "1.0.0", + "schema": "flow2spec.matcher.v1" +} diff --git a/templates/zh-CN/knowledge/topics/flow2spec-dsh-adapter.md b/templates/zh-CN/knowledge/topics/flow2spec-dsh-adapter.md new file mode 100644 index 0000000..b1c0d94 --- /dev/null +++ b/templates/zh-CN/knowledge/topics/flow2spec-dsh-adapter.md @@ -0,0 +1,16 @@ +--- +id: flow2spec-dsh-adapter +revision: 0 +summary: "DeepSeek Harness 项目级技能初始化与目录适配" +primary: feature +confidence: inferred +tags: [module] +--- +# DeepSeek Harness 适配 + +用于 `flow2spec init dsh`、DeepSeek Harness 技能发现、`.dsh/skills`、`.dsh/topics` 和根 `AGENTS.md` 入口问题。 + +- 技能写入 `.dsh/skills//SKILL.md`。 +- 规则长文镜像到 `.dsh/topics/*.md`，并写入 `.dsh/AGENTS.md` 目录指针。 +- 缺少根 `AGENTS.md` 时生成完整入口，已有入口不覆盖。 +- 原生 Cordis 插件属于后续路线图事项。 diff --git a/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md b/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md index 799483f..1d0e9b5 100644 --- a/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md +++ b/templates/zh-CN/rules/f2s-flow2spec-unified-entry.md @@ -92,7 +92,7 @@ alwaysApply: true ## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时） -三端均在 SessionStart 注册版本检查脚本：Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`** 在 `sessionStart` 执行 `node .cursor/hooks/f2s-update-check.js`；Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionStart` 的 `startup|resume` 事件同时注册配置摘要脚本 `node .codex/hooks/f2s-config-session.js` 与版本检查脚本 `node .codex/hooks/f2s-update-check.js`；Claude 由 `flow2spec init claude` 写入 **`.claude/settings.json`**，注册配置摘要、版本检查与 `PreToolUse Skill` 守门。版本检查脚本完成版本比对与缓存写入后，需升级时通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户）。 +各已初始化客户端在支持时使用自身的启动 / 更新机制，具体以生成的客户端入口为准。不提供 hooks 的客户端继续通过生成的 rules、skills、`AGENTS.md` 或 topics 镜像工作。版本检查脚本在客户端支持时完成版本比对并注入升级提示；项目级技能发现客户端通过 `flow2spec init dsh` 使用 `.dsh/skills/` 与 `.dsh/topics/`。 **规则层双保险**（与脚本缓存互为备份）： diff --git a/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md b/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md index 9b74ffc..3cc064d 100644 --- a/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md +++ b/templates/zh-CN/skills/f2s-kb-upgrade/SKILL.md @@ -62,8 +62,8 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V - **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。 - **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。 -**为何 Cursor / Claude / Codex 下各有一份同名 `SKILL.md`？** -各工具只加载**本配置根**下的 `skills/`（例如 Codex 仅 `.codex/skills/`）。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 +**为何每个已配置客户端目录下都有一份同名 `SKILL.md`？** +各客户端只加载**自身配置根**下的 `skills/`。`flow2spec init` 会向所选 agent 目录**同步落盘**当前语言对应的技能内容。 ## 目标 @@ -73,7 +73,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V 1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。 2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。 -3. 优先写入用户指定的 agent；未指定时默认 `cursor claude codex`。 +3. 优先写入用户指定的 agent；未指定时使用包的默认客户端选择。 ## init 与技能自更新（必须） diff --git a/templates/zh-CN/skills/f2s-req-plan/SKILL.md b/templates/zh-CN/skills/f2s-req-plan/SKILL.md index 1bc3577..0232fd5 100644 --- a/templates/zh-CN/skills/f2s-req-plan/SKILL.md +++ b/templates/zh-CN/skills/f2s-req-plan/SKILL.md @@ -18,13 +18,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 | **本技能职责** | 规划草稿、实现代码、子 agent 编排；**不得**自定 `.task/` 结构或弱化打钩/归档 | | **与 changeTracking** | `f2s-req-plan` **不受** `changeTracking.feat/fix/implement` 约束，**始终**走任务清单；见 `f2s-task`「生效条件」 | -**三端读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**： - -| 端 | 路径 | -| --- | --- | -| **Cursor** | 配置根 `rules/f2s-task.mdc`；或已 init 的 `.cursor/rules/f2s-task.mdc` | -| **Claude Code** | `.claude/rules/f2s-task.md` | -| **Codex** | `.codex/topics/f2s-task.md` | +**所有已为项目初始化的客户端都必须读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**。请从当前客户端生成的 rules、`AGENTS.md` 或 topics 入口读取，不得用本技能摘要代替全文。 ## 编排（主 / 子 agent） @@ -46,7 +40,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ### 步骤 0：前置（强制，任何步骤之前） 1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。 -2. **`Read` 上表三端之一的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 +2. **`Read` 当前客户端生成入口中的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。 3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。 ### 步骤 1：续作分诊 + 解析输入 @@ -140,7 +134,7 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务 ## 约束 -- **步骤 0**：必须先 `Read` `flow2spec.config.json` + **`f2s-task` 全文**（三端路径见上表） +- **步骤 0**：必须先 `Read` `flow2spec.config.json` + 当前客户端入口中的 **`f2s-task` 全文** - **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突 - 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务） - 步骤 2 必须主 agent；未确认禁止落盘 diff --git a/website/src/pages/en/index.astro b/website/src/pages/en/index.astro index 18a9f23..a7278a2 100644 --- a/website/src/pages/en/index.astro +++ b/website/src/pages/en/index.astro @@ -21,7 +21,7 @@ const sections = [
    -
    3AI clients
    Cursor · Claude Code · Codex
    1 baseShared knowledge layer
    .Knowledge/
    Route firstFind the relevant facts
    before changing code
    +
    MultiAI clients
    Connect the clients you use
    1 baseShared knowledge layer
    .Knowledge/
    Route firstFind the relevant facts
    before changing code

    The context problem

    AI can write.
    It just keeps guessing first.

    Project constraints live in code, docs, chat and someone's memory. A new session starts from zero, and more searching means more opportunities to misread the system.

    Without Flow2Spec

    “Which module owns this table?”

    The agent searches 416 APIs and 796 files, then guesses from a similar old implementation.

    search
    search
    search
    With Flow2Spec

    “Matcher hit: m-product-review-template-library.”

    Read verified facts first, then open only the files that need to change.

    ✓ matcher hit

    One small layer, four jobs

    Four layers that
    turn context into infrastructure.

    Each layer does one job. Together, they give AI collaboration continuity across a team.

    01

    Knowledge

    A shared base of APIs, boundaries, data rules and workflows.

    .Knowledge/topics/*.md
    02

    Task

    Each developer's local progress, context and user todos.

    .task/<developerId>/
    03

    Rules

    One entrypoint, one set of gates, across every agent.

    AGENTS.md · .codex/
    04

    Skills

    Reusable workflows for clarifying, building, fixing, syncing and committing.

    f2s-*

    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.

    diff --git a/website/src/pages/index.astro b/website/src/pages/index.astro index 5dd9fe8..a90295e 100644 --- a/website/src/pages/index.astro +++ b/website/src/pages/index.astro @@ -46,7 +46,7 @@ const sections = [
    -
    3AI 客户端
    Cursor · Claude Code · Codex
    1 库共享知识层
    .Knowledge/
    先读每次变更先定位事实
    再开始写代码
    +
    多端AI 客户端
    按需接入 Flow2Spec
    1 库共享知识层
    .Knowledge/
    先读每次变更先定位事实
    再开始写代码

    The context problem

    AI 很会写。
    但它总要重新猜一遍。

    项目里的约束散落在代码、文档、聊天记录和某个人的记忆里。新会话从零开始，搜索越多，误读和漂移越容易发生。

    @@ -64,7 +64,7 @@ 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

    为项目写入知识库、规则和 Cursor、Claude Code、Codex 的入口。

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

    描述第一个需求

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

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

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

    验证并持续交付

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

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

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

    A calmer first run

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

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

    01写入协作骨架

    初始化

    npx @double-coding/flow2spec@latest init

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

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

    描述第一个需求

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

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

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

    验证并持续交付

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

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

    会得到可复用的项目记忆

    Keep exploring

    从这里，继续阅读。

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

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