🚀 feat(dsh): 补齐 Harness 技能与规则初始化

.Knowledge/manifest-routing.json

@@ -1,7 +1,5 @@
 {
   "version": "3.2.12",
-  "projectRev": 2,
-  "pkgRev": 2,
   "knowledgeRoot": ".Knowledge",
   "matcherKey": "matcherId",
   "sourceOfTruth": ".Knowledge/manifest-routing.json",
@@ -24,6 +22,7 @@
     "config-precheck": ".Knowledge/topics/f2s-config-precheck.md",
     "f2s-task": ".Knowledge/topics/f2s-task.md",
     "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md",
+    "flow2spec-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.md",
     "f2s-git-commit": ".Knowledge/topics/f2s-git-commit.md",
     "flow2spec-presentations": ".Knowledge/topics/f2s-flow2spec-presentations.md",
     "flow2spec-milestones": ".Knowledge/topics/f2s-flow2spec-milestones.md",
@@ -33,8 +32,7 @@
     "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-dsh-adapter": ".Knowledge/topics/flow2spec-dsh-adapter.md"
+    "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md"
   },
   "taskToTopicRules": [
     {
@@ -78,6 +76,14 @@
         "f2s-req-plan"
       ]
     },
+    {
+      "task": "flow2spec-dsh-adapter",
+      "matcherId": "m-flow2spec-dsh-adapter",
+      "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json",
+      "topics": [
+        "flow2spec-dsh-adapter"
+      ]
+    },
     {
       "task": "git-commit",
       "matcherId": "m-f2s-git-commit",
@@ -157,16 +163,10 @@
       "topics": [
         "flow2spec-doctor"
       ]
-    },
-    {
-      "task": "flow2spec-dsh-adapter",
-      "matcherId": "m-flow2spec-dsh-adapter",
-      "matcherPath": ".Knowledge/matchers/m-flow2spec-dsh-adapter.json",
-      "topics": [
-        "flow2spec-dsh-adapter"
-      ]
     }
   ],
+  "projectRev": 2,
+  "pkgRev": 2,
   "topicMetadata": {
     "implement-tech-design": {
       "primary": "policy",

.Knowledge/template/index.template.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`。

.dsh/AGENTS.md

@@ -0,0 +1,6 @@
+# Flow2Spec（`.dsh/` 目录说明）
+
+DeepSeek Harness 从仓库根 [`AGENTS.md`](../AGENTS.md) 加载完整项目说明。
+
+- `skills/`：DeepSeek Harness 可发现的 Flow2Spec `f2s-*` 技能
+- `topics/`：按需读取的规则长文镜像

.dsh/skills/f2s-doc-arch/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: f2s-doc-arch
+description: 根据用户说明或文档（或扫描代码）生成项目架构说明初稿，无固定格式，描述清楚即可；触发：项目架构说明、f2s-doc-arch、架构初稿
+---
+> 执行口径：本技能产物默认写入 `.Knowledge/stock-docs/`，后续由知识库技能链（如 `f2s-doc-final`、`f2s-kb-build`）同步到 `.Knowledge/topics/index/manifest`。
+
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
+- 当 `subAgent=true` 时，从以下两种子策略择一：
+  - **B 模式（默认，单轮并行）**：主先产出「inventory（入口 + 核心模块名，主手写）」+「扫描契约（可读路径 / 禁扫目录 / 统一产出字段）」→ 子 agent 并行只读扫表 → 主一轮合并去重 → 写 `stock-docs` 初稿 → 用户确认与验收在主 agent 内完成。
+  - **C 模式（多轮纠偏）**：切换判据为以下任一 —— 多 workspace / monorepo、目录极深或源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合 / 矛盾严重。
+- **子交付硬约束**：子 agent 不得自行裁剪目录范围，必须按主手写 inventory 执行；子交付按「子交付 YAML schema」（字段：`source` / `scope` / `cross_refs` / `pending`），禁止散文式回传。
+- **写权硬约束**：`.Knowledge/index.md` / `manifest-routing.json` 恒由主 agent 落盘，子 agent 不得触碰。
+- 落盘侧自验；本 SKILL 不绑定交叉校验。
+
+# 生成项目架构说明（初稿）
+
+本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。
+
+**与 f2s-kb-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-kb-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-kb-add`**，**勿用本技能冒充该流程**。
+
+---
+
+## 入参（均可选）
+
+| 参数           | 说明                                                                                                                                                              |
+| -------------- | -------------------------- |
+| **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 |
+| **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 |
+
+**注意**：不传任何说明或文档时，将使用 **AI 扫描项目代码与目录** 生成架构说明初稿，**不保证质量**。执行时**必须先提示用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才继续。
+
+---
+
+## 执行流程
+
+### 1. 若用户提供了说明或文档
+
+1. **读取与理解**
+   - 若第一参数是**文档路径**：在配置根的父目录下按路径读取该文件内容（支持 .md、.txt 等文本格式）。
+   - 若第一参数是**纯文字说明**：直接以用户输入为「用户说明」。
+2. **结合项目补充**
+   - 根据用户说明中的**代码路径、模块名、入口**等线索，结合配置根的父目录下的实际目录结构、关键文件（如 package.json、入口文件、配置文件）进行**归纳与补全**。
+   - 若用户说明较宽泛（如只说了「一个后台系统」），**主动引导**用户补充：主要代码路径、模块/包划分、入口与启动方式、与外部系统的边界等，便于生成更贴合的架构说明。
+3. **生成初稿**
+   - 若启用拆子（B 模式），子 agent 必须按主手写 inventory 执行扫描，交付遵循子交付 YAML schema。
+   - 产出一份**项目架构说明**：可包含但不限于：项目定位、技术栈、目录/模块划分、关键路径与入口、配置与部署要点、与文档产物阶段的对应说明（若适用）。
+   - **无固定格式**：采用清晰的标题与段落即可，不强制套用《终稿模版》。
+4. **输出**
+   - 默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`；若用户传入第二参数则写入该路径。
+   - 若目录不存在则先创建。
+
+### 2. 若用户未提供任何说明或文档
+
+1. **提醒并确认**
+   - 明确说明：「**未收到任何参数。** 不传递说明或文档时，将使用 AI 扫描项目代码与目录生成架构说明初稿，**不保证质量**，且易遗漏重点、难以区分主次。建议先提供一段简要说明或已有文档（如 README、设计 doc）再执行本技能。」
+   - **必须询问用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」
+   - 仅当用户**明确确认**（如回复「确认」「是」「直接扫描」等）后，才继续步骤 2；若用户未确认或表示取消，则不再执行扫描与生成。
+2. **扫描与生成**
+   - 基于配置根的父目录：列出主要目录与代表性文件（可结合 package.json、常见入口与配置文件名），归纳出「目录结构、疑似模块、入口与配置」等。
+   - 生成一份**架构说明初稿**，并在文中注明「本初稿由扫描项目结构生成，建议结合业务说明与代码细节进一步补充」。
+3. **输出**
+   - 同上，默认 `.Knowledge/stock-docs/架构说明_初稿.md`，或用户指定的第二参数。
+
+---
+
+## 引导与迭代
+
+- 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
+
+## 大功能拆分建议
+
+扫描或理解完源码/说明后，若识别出以下任一信号，须在初稿**末尾**输出「拆分建议」段落，供用户参考（不阻断生成）：
+
+- 源码总量超过 **~5000 行**，或涉及文件超过 **20 个**；
+- 能明显识别出 **3 个以上不相干职责域**（如接口层 / 核心规则 / 数据模型 / 外部依赖各自独立）；
+- 用户说明本身已提到「多个子模块」或「多个功能」。
+
+**拆分建议格式**（写在初稿末尾，独立节）：
+
+```
+## 拆分建议
+
+当前功能体量较大，建议拆成多份 focused stock-doc，各自对应一个独立 topic：
+
+| 建议文档 | 主要内容 | 建议 topic primary |
+|---|---|---|
+| <功能名>-概述_初稿.md | 入口边界、子模块关系、快速索引 | feature |
+| <功能名>-业务规则_初稿.md | 核心流程、门禁、状态机 | policy |
+| <功能名>-数据模型_初稿.md | 表结构、枚举、模型约定 | module |
+| <功能名>-外部依赖_初稿.md | SOA/QMQ/Redis/风控封装 | config |
+
+拆分后各子 topic 通过各自 matcher 独立命中，主 topic 正文写导航链接；
+不通过 topicDependencies 串联"概述 → 详情"（见 f2s-topic-authoring 第 5 节）。
+```
+
+用户可选择：**A) 按拆分建议分别执行 `f2s-doc-arch`**（推荐），或 **B) 继续用当前单份初稿**进入后续流程。
+
+## 完成后的下一步（硬约束）
+
+本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-kb-build`：
+
+1. 告知初稿路径，建议用户先审阅、补充内容。
+2. **下一步必须为 `f2s-doc-final`**：以初稿路径为入参，产出 `.Knowledge/stock-docs/<方案名>_终稿.md`（《终稿模版》规范格式）。
+3. **仅在终稿落盘后**再引导 **`f2s-kb-build`**，且入参须为终稿路径（含 `_终稿` 或由 `f2s-doc-final` 刚生成）。
+4. **禁止**在完成回复中单独写「请执行 `f2s-kb-build`」且入参指向 `*_初稿.md`；**禁止**将 `f2s-kb-build` 与 `f2s-doc-final` 并列成「二选一」。
+5. **唯一例外**：用户**明确要求**跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 `f2s-kb-build`。
+
+**完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-kb-build`，且 ctx-build 在终稿之后）：
+
+> 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-kb-build <终稿路径>`** 同步知识路由主题与索引。
+
+---
+
+## 路径与输出约定
+
+- 所有路径均相对于**配置根的父目录**。
+- **默认输出**：`.Knowledge/stock-docs/架构说明_初稿.md`；项目名取自 `package.json` 的 `name`（去掉 scope 与非法字符）或当前目录名。
+- 若用户传入第二参数为输出路径，则优先使用该路径；若目录不存在则先创建。
+
+---
+
+## 约束与注意
+
+- **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
+- **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
+- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-kb-build`**；不得仅推荐 build。