sdd-flow-kit 0.1.0 → 1.0.1

package/README.md

@@ -13,22 +13,21 @@
 
 #### 安装教程
 
-1.  进入你要开发的项目目录（例如 `adInsight-web` 或任意工程根目录）
-2.  安装（本地/私有 npm 方式均可）：`npm i -D /Users/lixinxin/Desktop/Huanwang/sdd-flow-kit` 或发布后 `npm i -D sdd-flow-kit`
-3.  先初始化环境（默认 `claude-code`）：`npx sdd-flow-kit setup`
-4.  启动：`npx sdd-flow-kit run --product ADI --version 2.3.2`
-5.  预演：`npx sdd-flow-kit run --product ADI --version 2.3.2 --dry-run`
-6.  一句话触发：`npx sdd-flow-kit invoke "开发 ADI 2.3.2 需求"`
-7.  环境健检：`npx sdd-flow-kit doctor --agent claude-code`
+1.  进入你要开发的项目目录
+2.  安装：`npm i -D sdd-flow-kit`
+3.  安装流程（安装即用，默认 `claude-code`）：`npx sdd-flow-kit install`
+    - 会自动安装对应 AI 环境并写入项目级触发 Skill（仅在“开发 <产品> <版本> 需求/版本/PRD”场景触发）
+    - 会在项目根目录生成 `docs/<项目>-doc-skill/`（用于 PRD 下载脚本与说明），可通过 `--project` 选择：`OMS` / `ADI` / `欢盟` / `AD Tools`（默认 `OMS`）
+4.  （可选）预演安装：`npx sdd-flow-kit install --dry-run --plan-json`
+5.  （可选）环境健检：`npx sdd-flow-kit doctor --agent claude-code`
+6.  完成后，直接在 Cursor / Claude Code / Codex / OpenClaw 中用自然语言发起需求，例如：`开发 ADI 2.3.2 需求`
 
 #### 使用说明
 
-1.  `setup`：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境
-2.  `start`：创建 `openspec/PRD/<YYYYMMDD>-<product>-<version>/` 并生成 1~5 步所需模板
-3.  `run`：先执行 `setup` 逻辑，再生成流程骨架与 `AUTO-RUN-CHECKLIST.md`
-4.  第 2 步 SDD 循环提示词与第 4/5 步入口文件可直接在 Cursor/Claude/Codex/OpenClaw 使用
-5.  `invoke`：从自然语言解析 product/version，并自动触发 `run`
-6.  `doctor`：检查 git/npx/agent CLI/openspec/tool 目录，输出可机读诊断结果
+1.  `install`（等价 `setup`）：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境，同时写入项目级 Skill
+2.  安装完成后，本工具主要负责“流程环境与模板”落地；业务需求由你在目标 AI 工具中自然语言驱动
+3.  `start`/`run`/`invoke` 属于进阶能力（脚本化或一键编排时使用）
+4.  `doctor`：检查 git/npx/agent CLI/openspec/tool 目录，输出可机读诊断结果
 
 #### 当前自动化边界
 
@@ -36,6 +35,23 @@
 - 已支持：环境检测与按工具自动执行 `npx @lixin5257xxx/opsx-workflow setup ...`
 - 自动化增强：`claude-code` adapter 支持 `claude -p` 自动执行并记录 `AUTO-RUN-LOG.md`（失败自动降级人工）
 
+#### npm 发包流程
+
+1.  发布前检查：`npm whoami`（确认已登录正确 npm 账号）
+2.  构建产物：`npm run build`
+3.  本地打包检查：`npm pack`（确认 tar 包内容包含 `dist/`、`src/templates/`、`README.md`）
+4.  （可选）在目标项目验证安装：`npm i -D ./sdd-flow-kit-<version>.tgz`，并执行 `npx sdd-flow-kit install --dry-run --plan-json`
+5.  正式发布：
+    - 首次发布 scoped 包：`npm publish --access public`
+    - 非 scoped 或后续版本：`npm publish`
+6.  发布后验证：在任意项目执行 `npm i -D sdd-flow-kit`，再执行 `npx sdd-flow-kit install`
+
+版本升级建议：
+
+1.  修改版本号：`npm version patch`（或 `minor` / `major`）
+2.  重新执行构建与发布步骤
+3.  在 `README.md` 或变更记录中补充本次升级说明
+
 #### 参与贡献
 
 1.  Fork 本仓库

package/dist/cli.js

@@ -30,14 +30,15 @@ function printHelp() {
         "1) 生成流程产物骨架：",
         "   npx sdd-flow-kit start --product ADI --version 2.3.2",
         "",
-        "2) 初始化环境（环境选择 + 分支处理 + opsx 检测安装）：",
-        "   npx sdd-flow-kit setup --agent claude-code",
+        "2) 安装流程到当前项目（推荐，安装即用）：",
+        "   npx sdd-flow-kit install",
+        "   (等价于: npx sdd-flow-kit setup)",
         "",
         "3) 生成骨架并进入可执行模式（推荐）：",
         "   npx sdd-flow-kit run --product ADI --version 2.3.2 --agent claude-code",
         "",
-        "4) 一句话触发：",
-        "   npx sdd-flow-kit invoke \"开发 ADI 2.3.2 需求\"",
+        "4) 一句话触发（可选能力）：",
+        "   npx sdd-flow-kit invoke \"开发 XXX 1.2.3 需求\"",
         "",
         "5) 环境健检：",
         "   npx sdd-flow-kit doctor --agent claude-code",
@@ -46,6 +47,7 @@ function printHelp() {
         "   --projectRoot <path>   目标项目根目录（默认当前目录）",
         "   --agent <name>         cursor | claude-code | codex | openclaw | custom（默认 claude-code）",
         "   --branch <name>        开发分支；不存在会自动创建",
+        "   --project <name>       OMS | ADI | 欢盟 | AD Tools（默认 OMS，用于生成 docs/*-doc-skill）",
         "   -y                     非交互模式（使用默认值）",
         "   --dry-run              预演模式：仅检测并输出计划，不执行写入/安装/切分支",
         "   --plan-json            输出机器可读 JSON 计划结果",
@@ -60,7 +62,12 @@ async function main() {
         printHelp();
         return;
     }
-    if (cmd !== "start" && cmd !== "run" && cmd !== "setup" && cmd !== "doctor" && cmd !== "invoke") {
+    if (cmd !== "start" &&
+        cmd !== "run" &&
+        cmd !== "setup" &&
+        cmd !== "install" &&
+        cmd !== "doctor" &&
+        cmd !== "invoke") {
         printHelp();
         node_process_1.default.exitCode = 1;
         return;
@@ -73,6 +80,7 @@ async function main() {
     const dryRun = node_process_1.default.argv.includes("--dry-run");
     const planJson = node_process_1.default.argv.includes("--plan-json");
     const agentValue = getArgValue("--agent") ?? "claude-code";
+    const projectKind = (getArgValue("--project") ?? "OMS");
     if (!ALLOWED_AGENTS.includes(agentValue)) {
         // eslint-disable-next-line no-console
         console.error(`不支持的 --agent: ${agentValue}`);
@@ -81,6 +89,13 @@ async function main() {
         return;
     }
     const agent = agentValue;
+    const allowedProjects = ["OMS", "ADI", "欢盟", "AD Tools"];
+    if (!allowedProjects.includes(projectKind)) {
+        // eslint-disable-next-line no-console
+        console.error(`不支持的 --project: ${projectKind}（可选：${allowedProjects.join(" / ")}）`);
+        node_process_1.default.exitCode = 1;
+        return;
+    }
     if (cmd === "doctor") {
         const doctor = await (0, doctor_1.runDoctor)({ projectRoot: node_path_1.default.resolve(projectRoot), agent });
         // eslint-disable-next-line no-console
@@ -97,16 +112,17 @@ async function main() {
             node_process_1.default.exitCode = 1;
         return;
     }
-    if (cmd === "setup") {
+    if (cmd === "setup" || cmd === "install") {
         const result = await (0, setupProject_1.setupProject)({
             projectRoot: node_path_1.default.resolve(projectRoot),
             agent,
             branch,
             yes,
             dryRun,
+            projectKind: projectKind,
         });
         // eslint-disable-next-line no-console
-        console.log(`setup 完成：agent=${result.agent}, branch=${result.branch}, setupExecuted=${result.setupExecuted}, dryRun=${dryRun}`);
+        console.log(`setup 完成：agent=${result.agent}, project=${result.projectKind}, branch=${result.branch}, setupExecuted=${result.setupExecuted}, skillInstalled=${result.skillInstalled}, docsSkillInstalled=${result.docsSkillInstalled}, dryRun=${dryRun}`);
         if (result.plannedActions.length > 0) {
             // eslint-disable-next-line no-console
             console.log(`planned: ${result.plannedActions.join(" | ")}`);
@@ -114,7 +130,7 @@ async function main() {
         if (planJson) {
             // eslint-disable-next-line no-console
             console.log(JSON.stringify({
-                command: "setup",
+                command: cmd,
                 projectRoot: node_path_1.default.resolve(projectRoot),
                 dryRun,
                 result,

package/dist/steps/setupProject.js

@@ -10,7 +10,9 @@ const node_path_1 = __importDefault(require("node:path"));
 const promises_2 = require("node:readline/promises");
 const node_process_1 = __importDefault(require("node:process"));
 const fs_1 = require("../core/fs");
+const templates_1 = require("../core/templates");
 const EDITOR_CHOICES = ["claude-code", "cursor", "codex", "openclaw"];
+const PROJECT_CHOICES = ["OMS", "ADI", "欢盟", "AD Tools"];
 function runGit(args, cwd) {
     const out = (0, node_child_process_1.spawnSync)("git", args, { cwd, encoding: "utf8" });
     if (out.status !== 0) {
@@ -71,6 +73,27 @@ async function askBranch(defaultBranch) {
     rl.close();
     return answer || defaultBranch;
 }
+async function askProjectKind(defaultKind) {
+    if (!node_process_1.default.stdin.isTTY)
+        return defaultKind;
+    const rl = (0, promises_2.createInterface)({ input: node_process_1.default.stdin, output: node_process_1.default.stdout });
+    const prompt = [
+        "请选择当前项目类型（用于生成 PRD 下载 skill）：",
+        "1) OMS (default)",
+        "2) ADI",
+        "3) 欢盟",
+        "4) AD Tools",
+        "输入编号（回车默认 1）：",
+    ].join("\n");
+    const answer = (await rl.question(`${prompt}\n`)).trim();
+    rl.close();
+    if (!answer)
+        return defaultKind;
+    const idx = Number(answer);
+    if (Number.isNaN(idx) || idx < 1 || idx > PROJECT_CHOICES.length)
+        return defaultKind;
+    return PROJECT_CHOICES[idx - 1];
+}
 function isEditorEnvironmentReady(projectRoot, agent) {
     const checks = {
         cursor: ["openspec", ".cursor"],
@@ -124,9 +147,69 @@ function ensureBranch(projectRoot, branch) {
     runGit(["checkout", "-b", branch], projectRoot);
     return { branch, created: true };
 }
+function skillInstallPath(projectRoot, agent) {
+    const relMap = {
+        cursor: ".cursor/skills/sdd-flow-kit/SKILL.md",
+        "claude-code": ".claude/skills/sdd-flow-kit/SKILL.md",
+        codex: ".codex/skills/sdd-flow-kit/SKILL.md",
+        openclaw: ".openclaw/skills/sdd-flow-kit/SKILL.md",
+        custom: ".sdd-flow-kit/SKILL.md",
+    };
+    const rel = relMap[agent];
+    if (!rel)
+        return null;
+    return node_path_1.default.join(projectRoot, rel);
+}
+async function installAgentSkill(projectRoot, agent) {
+    const target = skillInstallPath(projectRoot, agent);
+    if (!target)
+        return;
+    const template = await (0, templates_1.loadTemplateText)("artifacts/06-agent-skill.template.md");
+    const content = template.replaceAll("{{AGENT_NAME}}", agent);
+    await (0, fs_1.writeTextFileEnsuredDir)(target, content);
+}
+function renderVars(template, vars) {
+    let out = template;
+    for (const [k, v] of Object.entries(vars)) {
+        out = out.replaceAll(`{{${k}}}`, v);
+    }
+    return out;
+}
+function docSkillDirName(kind) {
+    switch (kind) {
+        case "ADI":
+            return { dir: "adi-doc-skill", prefix: "ADI" };
+        case "欢盟":
+            return { dir: "huan-doc-skill", prefix: "HUAN" };
+        case "AD Tools":
+            return { dir: "ad-tools-doc-skill", prefix: "ADTOOLS" };
+        case "OMS":
+        default:
+            return { dir: "oms-doc-skill", prefix: "OMS" };
+    }
+}
+async function installDocsSkill(projectRoot, kind) {
+    const { dir, prefix } = docSkillDirName(kind);
+    const docsDir = node_path_1.default.join(projectRoot, "docs", dir);
+    const pyTemplate = await (0, templates_1.loadTemplateText)("skills/confluence-doc.py.template");
+    const mdTemplate = await (0, templates_1.loadTemplateText)("skills/doc-skill.SKILL.md.template");
+    const md = renderVars(mdTemplate, {
+        SKILL_NAME: `${prefix.toLowerCase()}-doc`,
+        PRODUCT: kind,
+        PRODUCT_PREFIX: prefix,
+        PRODUCT_PREFIX_LOWER: prefix.toLowerCase(),
+        SKILL_DIR: dir,
+    });
+    const py = pyTemplate.replaceAll("{{DOC_PRODUCT_PREFIX}}", prefix);
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(docsDir, "SKILL.md"), md);
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(docsDir, "confluence-doc.py"), py);
+    return { dirPath: docsDir };
+}
 async function setupProject(options) {
     const defaultAgent = options.agent ?? "claude-code";
     const selectedAgent = options.yes ? defaultAgent : await askAgent(defaultAgent);
+    const defaultKind = options.projectKind ?? "OMS";
+    const selectedKind = options.yes ? defaultKind : await askProjectKind(defaultKind);
     const defaultBranch = options.branch ?? pickDefaultBranch(options.projectRoot);
     const selectedBranch = options.yes ? defaultBranch : await askBranch(defaultBranch);
     const plannedActions = [];
@@ -142,6 +225,8 @@ async function setupProject(options) {
     }
     let environmentReady = await isEditorEnvironmentReady(options.projectRoot, selectedAgent);
     let setupExecuted = false;
+    let skillInstalled = false;
+    let docsSkillInstalled = false;
     if (!environmentReady) {
         const { cmd, args } = buildSetupCommand(options.projectRoot, selectedAgent);
         if (options.dryRun) {
@@ -163,14 +248,31 @@ async function setupProject(options) {
     else if (options.dryRun) {
         plannedActions.push("environment already ready, no setup needed");
     }
+    if (options.dryRun) {
+        const skillPath = skillInstallPath(options.projectRoot, selectedAgent);
+        if (skillPath) {
+            plannedActions.push(`would install skill: ${skillPath}`);
+        }
+        const { dir } = docSkillDirName(selectedKind);
+        plannedActions.push(`would install docs skill: ${node_path_1.default.join(options.projectRoot, "docs", dir)}`);
+    }
+    else {
+        await installAgentSkill(options.projectRoot, selectedAgent);
+        skillInstalled = true;
+        await installDocsSkill(options.projectRoot, selectedKind);
+        docsSkillInstalled = true;
+    }
     const summary = [
         "# SETUP-SUMMARY",
         "",
         `agent: ${selectedAgent}`,
+        `projectKind: ${selectedKind}`,
         `branch: ${branchResult.branch}`,
         `branchCreated: ${branchResult.created}`,
         `environmentReady: ${environmentReady}`,
         `setupExecuted: ${setupExecuted}`,
+        `skillInstalled: ${skillInstalled}`,
+        `docsSkillInstalled: ${docsSkillInstalled}`,
         `dryRun: ${Boolean(options.dryRun)}`,
         "",
         "plannedActions:",
@@ -180,10 +282,13 @@ async function setupProject(options) {
     await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(options.projectRoot, ".sdd-flow-kit", "setup-summary.md"), summary);
     return {
         agent: selectedAgent,
+        projectKind: selectedKind,
         branch: branchResult.branch,
         branchCreated: branchResult.created,
         environmentReady,
         setupExecuted,
         plannedActions,
+        skillInstalled,
+        docsSkillInstalled,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",

package/src/templates/artifacts/06-agent-skill.template.md

@@ -0,0 +1,30 @@
+---
+name: sdd-flow-kit-trigger
+description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类似表达时，必须启动 sdd-flow-kit 流程；其它对话保持原本 AI 行为。
+---
+
+# SDD Flow Trigger Skill
+
+## 触发条件（仅这些场景触发）
+- 用户说法包含类似：`开发 XXX 1.2 需求`、`开发 XXX 1.2.3 版本`、`开发 XXX PRD`
+- 或明确要求“按 SDD 流程”推进某版本需求
+
+## 触发后必须执行
+1. 从用户输入中提取 `product` 与 `version`
+2. 在项目根目录执行：
+   - `npx sdd-flow-kit run --product <product> --version <version> -y`
+3. 按 `openspec/PRD/<runId>/RUNME.md` 严格推进第 1~5 步
+4. 交付物至少包含：
+   - `01-需求分析报告.md`
+   - `02-改动点清单.md`
+   - `03-待确认问题清单.md`
+   - `04-技术文档草稿.md`
+   - `05-openspec-提案草稿.md`
+
+## 非触发场景
+- 如果用户没有表达“开发某产品某版本需求”，则不要强制进入该流程
+- 继续按常规 AI 对话处理用户问题
+
+## 当前环境
+- agent: {{AGENT_NAME}}
+- 安装命令: `npx sdd-flow-kit install`

package/src/templates/skills/confluence-doc.py.template

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""
+Confluence 需求文档获取脚本（Playwright）
+
+用法:
+  python3 confluence-doc.py <版本号>
+
+环境变量:
+  CONFLUENCE_BASE_URL      例如 https://confluence.huan.tv
+  CONFLUENCE_SEARCH_URL    例如 https://confluence.huan.tv/dosearchsite.action?includeArchivedSpaces=false
+  CONFLUENCE_USERNAME
+  CONFLUENCE_PASSWORD
+  DOC_PRODUCT_PREFIX       例如 ADI / OMS / HUAN / ADTOOLS
+  DOC_DOWNLOAD_DIR         输出目录（默认当前脚本所在目录的上级 docs/）
+
+注意:
+  - 为安全起见，本模板不包含任何默认账号密码
+  - 你需要先安装 playwright:
+      pip install playwright && playwright install chromium
+"""
+
+import sys
+import os
+import re
+from pathlib import Path
+from urllib.parse import urljoin, urlparse, unquote
+
+try:
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    print("❌ 请先安装 playwright: pip install playwright && playwright install chromium")
+    sys.exit(1)
+
+
+def env(name: str, default: str | None = None) -> str:
+    v = os.environ.get(name, default)
+    if v is None or str(v).strip() == "":
+        raise RuntimeError(f"缺少环境变量: {name}")
+    return str(v)
+
+
+def normalize_version(raw: str) -> str:
+    """将 1.2.3 / V1.2.3 / XXX-V1.2.3 / XXX_V1.2.3 统一为 1.2.3"""
+    v = raw.strip()
+    v = re.sub(r"^[A-Z]+[-_]?V?", "", v, flags=re.IGNORECASE)
+    v = re.sub(r"^V", "", v, flags=re.IGNORECASE)
+    return v
+
+
+def version_slug(prefix: str, version: str) -> str:
+    """1.2.3 -> <prefix>-v123"""
+    return prefix.lower() + "-v" + version.replace(".", "")
+
+
+def search_keywords(prefix: str, version: str) -> list[str]:
+    return [f"{prefix}-V{version}", f"{prefix}_V{version}"]
+
+
+def sanitize_filename(name: str) -> str:
+    name = re.sub(r'[\\/:*?"<>|]', "-", name)
+    return name.strip() or "需求文档"
+
+
+def parse_html_to_markdown(html_content: str) -> str:
+    md = html_content
+    md = re.sub(r"<h1[^>]*>(.*?)</h1>", r"# \1\n\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<h2[^>]*>(.*?)</h2>", r"## \1\n\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<h3[^>]*>(.*?)</h3>", r"### \1\n\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<h4[^>]*>(.*?)</h4>", r"#### \1\n\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<li[^>]*>(.*?)</li>", r"- \1\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r'<a[^>]*href="([^"]+)"[^>]*>(.*?)</a>', r"[\2](\1)", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r'<img[^>]*src="([^"]+)"[^>]*>', r"![](\1)", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<p[^>]*>(.*?)</p>", r"\1\n\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<br[^>]*>", r"\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<strong[^>]*>(.*?)</strong>", r"**\1**", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<b[^>]*>(.*?)</b>", r"**\1**", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<em[^>]*>(.*?)</em>", r"*\1*", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<code[^>]*>(.*?)</code>", r"`\1`", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<pre[^>]*>(.*?)</pre>", r"```\n\1\n```", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<[^>]+>", "", md)
+    md = re.sub(r"\n{3,}", "\n\n", md)
+    return md.strip()
+
+
+def is_wiki_page_href(href: str) -> bool:
+    if not href:
+        return False
+    href_lower = href.lower()
+    if any(x in href_lower for x in ("dosearchsite", "login.action", "dashboard")):
+        return False
+    return any(x in href_lower for x in ("/pages/", "/display/", "/spaces/"))
+
+
+def absolutize_href(base_url: str, href: str) -> str:
+    return base_url + href if href.startswith("/") else href
+
+
+def href_path_matches_keyword(href: str, keyword: str) -> bool:
+    path = unquote(urlparse(href).path).lower()
+    kw = keyword.lower()
+    compact = kw.replace(".", "")
+    path_compact = path.replace(".", "")
+    return kw in path or compact in path_compact
+
+
+def find_search_result(page, base_url: str, keyword: str):
+    keyword_lower = keyword.lower()
+    seen: set[str] = set()
+    selectors = [
+        ".search-result .title a",
+        ".search-result-title a",
+        "#search-results .gs-title a",
+        f"a[href*='{keyword}']",
+        f"a:has-text('{keyword}')",
+        ".search-result a",
+        "#search-results a",
+    ]
+    scored: list[tuple[int, str]] = []
+
+    for selector in selectors:
+        links = page.locator(selector)
+        for i in range(links.count()):
+            href = links.nth(i).get_attribute("href") or ""
+            raw_text = (links.nth(i).inner_text() or "").strip()
+            title_text = raw_text.split("\n")[0].strip()
+            link_title_attr = (links.nth(i).get_attribute("title") or "").strip()
+            text = link_title_attr or title_text
+            if not is_wiki_page_href(href):
+                continue
+            full_url = absolutize_href(base_url, href)
+            if full_url in seen:
+                continue
+            seen.add(full_url)
+
+            text_hit = keyword_lower in text.lower()
+            path_hit = href_path_matches_keyword(href, keyword)
+            if not text_hit:
+                continue
+
+            score = 2 + (1 if path_hit else 0)
+            scored.append((score, full_url))
+
+    if not scored:
+        return None
+    scored.sort(key=lambda x: x[0], reverse=True)
+    best = scored[0][1]
+    print(f"   找到文档链接: {best[:100]}...")
+    return best
+
+
+def run_search(page, base_url: str, keyword: str, search_url: str) -> str | None:
+    page.goto(search_url, wait_until="networkidle", timeout=60000)
+    page.wait_for_timeout(800)
+    search_selector = None
+    for selector in ["#search-query-input", "input[name='search-query']", "input.search-query", "input[id*='search']"]:
+        if page.locator(selector).count() > 0:
+            search_selector = selector
+            break
+    if not search_selector:
+        search_selector = "input[type='text']"
+    page.fill(search_selector, keyword)
+    page.keyboard.press("Enter")
+    page.wait_for_load_state("networkidle", timeout=30000)
+    page.wait_for_timeout(1500)
+    return find_search_result(page, base_url, keyword)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("❌ 请提供版本号")
+        print("   用法: python3 confluence-doc.py <版本号>")
+        sys.exit(1)
+
+    base_url = env("CONFLUENCE_BASE_URL")
+    search_url = env("CONFLUENCE_SEARCH_URL", base_url.rstrip("/") + "/dosearchsite.action?includeArchivedSpaces=false")
+    username = env("CONFLUENCE_USERNAME")
+    password = env("CONFLUENCE_PASSWORD")
+    prefix = os.environ.get("DOC_PRODUCT_PREFIX", "{{DOC_PRODUCT_PREFIX}}").strip() or "{{DOC_PRODUCT_PREFIX}}"
+    version = normalize_version(sys.argv[1])
+    keywords = search_keywords(prefix, version)
+
+    # 输出目录默认为仓库 docs/ 下
+    default_download = os.environ.get("DOC_DOWNLOAD_DIR")
+    if default_download:
+        docs_root = Path(default_download)
+    else:
+        docs_root = Path(__file__).resolve().parents[1]
+
+    slug = version_slug(prefix, version)
+    version_dir = docs_root / slug
+    version_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"\n📥 开始获取 {prefix} {keywords[0]} 需求文档")
+    print(f"🔍 将依次尝试: {', '.join(keywords)}")
+    print(f"📁 输出目录: {docs_root}")
+    print(f"🖼️ 图片目录: {version_dir}")
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        context = browser.new_context()
+        page = context.new_page()
+        try:
+            # 登录（如需要）
+            page.goto(search_url, wait_until="networkidle", timeout=60000)
+            if "login" in page.url.lower():
+                page.wait_for_selector("#username-field", timeout=10000)
+                page.fill("#username-field", username)
+                page.fill("#password-field", password)
+                page.click("#login-button")
+                page.wait_for_load_state("networkidle", timeout=30000)
+
+            target_url = None
+            matched_keyword = None
+            for kw in keywords:
+                print(f"\n🔍 搜索关键词: {kw}")
+                found = run_search(page, base_url, kw, search_url)
+                if found:
+                    target_url = found
+                    matched_keyword = kw
+                    break
+                print(f"   未找到 {kw}，尝试下一个关键词...")
+
+            if not target_url or not matched_keyword:
+                print(f"❌ 未找到 {prefix} {version} 的需求文档，请检查 Confluence 页面命名。")
+                sys.exit(1)
+
+            print(f"✅ 命中: {matched_keyword}")
+            print(f"   进入页面: {target_url[:120]}...")
+            page.goto(target_url, wait_until="networkidle", timeout=60000)
+
+            try:
+                title = page.locator("#title-text").text_content().strip()
+            except Exception:
+                title = f"{matched_keyword} 需求文档"
+
+            content_elem = page.locator("#main-content")
+            if not content_elem.count():
+                content_elem = page.locator(".wiki-content")
+            content_html = content_elem.inner_html() if content_elem.count() else ""
+
+            img_urls = re.findall(r'<img[^>]*src="([^"]+)"', content_html)
+            for i, img_url in enumerate(img_urls):
+                original_url = img_url
+                if img_url.startswith("//"):
+                    img_url = "https:" + img_url
+                elif img_url.startswith("/"):
+                    img_url = base_url.rstrip("/") + img_url
+                elif not img_url.startswith("http"):
+                    img_url = urljoin(base_url, img_url)
+
+                if img_url.startswith("http") and not img_url.startswith("data:"):
+                    parsed = urlparse(img_url)
+                    ext = os.path.splitext(parsed.path)[1] or ".png"
+                    filename = f"image_{i + 1}{ext}"
+                    filepath = version_dir / filename
+                    try:
+                        resp = page.request.get(img_url)
+                        if resp.ok:
+                            filepath.write_bytes(resp.body())
+                            content_html = content_html.replace(f'src="{original_url}"', f'src="{slug}/{filename}"')
+                    except Exception:
+                        pass
+
+            content_md = parse_html_to_markdown(content_html)
+            md_content = f"""# {title}
+
+> 版本: {matched_keyword}
+> 来源: {target_url}
+
+---
+
+{content_md}
+"""
+            md_filename = sanitize_filename(title) + ".md"
+            if not re.search(rf"{prefix}[-_]?V", md_filename, flags=re.IGNORECASE):
+                md_filename = f"{matched_keyword}-{md_filename}"
+            md_path = docs_root / md_filename
+            md_path.write_text(md_content, encoding="utf-8")
+
+            print("\n✅ 获取完成！")
+            print(f"📄 主文档: {md_path}")
+            print(f"🖼️ 图片目录: {version_dir}")
+        finally:
+            browser.close()
+
+
+if __name__ == "__main__":
+    main()
+

package/src/templates/skills/doc-skill.SKILL.md.template

@@ -0,0 +1,55 @@
+---
+name: {{SKILL_NAME}}
+description: |
+  当用户说「获取 {{PRODUCT}} Vx.y.z 需求文档」「下载 {{PRODUCT}}-Vx.y.z PRD」「查询 {{PRODUCT}} x.y.z 版本需求」时触发。
+  自动从 Confluence 搜索对应版本 PRD 页面，下载图片并生成 Markdown 到本仓库 `docs/`。
+---
+
+# {{PRODUCT}} 需求文档获取（docs/{{SKILL_DIR}}）
+
+## 触发条件
+
+用户说：
+
+- 「获取 {{PRODUCT}} V1.2.3 需求文档」
+- 「下载 {{PRODUCT}}-V1.2.3 PRD」
+- 「查询 {{PRODUCT}} 1.2.3 版本需求」
+
+## 执行方式
+
+在当前项目根目录执行：
+
+```bash
+cd docs/{{SKILL_DIR}}
+export CONFLUENCE_BASE_URL="https://confluence.huan.tv"
+export CONFLUENCE_USERNAME="<你的账号>"
+export CONFLUENCE_PASSWORD="<你的密码>"
+export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
+python3 confluence-doc.py <版本号>
+```
+
+版本号支持多种写法：
+
+```bash
+python3 confluence-doc.py 1.2.3
+python3 confluence-doc.py V1.2.3
+python3 confluence-doc.py {{PRODUCT_PREFIX}}-V1.2.3
+python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
+```
+
+## 输出结构
+
+```
+<repo>/docs/
+├── {{PRODUCT_PREFIX}}-V1.2.3-xxx.md
+└── {{PRODUCT_PREFIX_LOWER}}-v123/
+    ├── image_1.png
+    └── image_2.png
+```
+
+## 注意事项
+
+- 依赖 Playwright：`pip install playwright && playwright install chromium`
+- 脚本：`docs/{{SKILL_DIR}}/confluence-doc.py`
+- 为安全起见，脚本不包含默认账号密码，请用环境变量注入
+