@harmonyos-arkts/d2h 0.1.22 → 0.1.27

package/skills/d2h-architecture-plan/scripts/test_architecture_plan.py

@@ -0,0 +1,378 @@
+"""Behavior checks for the dashboard selection boundary; no real project is touched."""
+
+import copy
+import contextlib
+import io
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+import architecture_plan as helper
+from architecture_plan import ContractError, apply_selection, read_selection, validate_plan
+
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+HELPER = SKILL_ROOT / "scripts" / "architecture_plan.py"
+
+
+class ArchitecturePlanTests(unittest.TestCase):
+    def setUp(self):
+        self.plan = json.loads((SKILL_ROOT / "references" / "architecture-plan.example.json").read_text(encoding="utf-8"))
+        self.decision = {
+            "requestId": "request-1", "planId": self.plan["planId"],
+            "selectedProposalId": "android-mirror",
+            "action": "select-and-create", "source": "dashboard", "notes": "",
+        }
+
+    def test_example_has_three_independently_valid_trees_and_no_user_selection(self):
+        validate_plan(self.plan)
+        self.assertEqual({p["id"] for p in self.plan["proposals"]}, {"android-mirror", "harmony-practice", "hybrid"})
+        self.assertIsNone(self.plan["selectedProposalId"])
+
+    def test_minimal_content_needs_no_execution_paths_or_architecture_relationship_models(self):
+        self.plan["androidAnalysis"]["risks"] = []
+        validate_plan(self.plan)
+        self.assertEqual(set(self.plan["androidAnalysis"]), {"summary", "techStack", "risks"})
+        self.assertEqual(set(self.plan["project"]), {"name", "summary"})
+        for proposal in self.plan["proposals"]:
+            self.assertEqual(set(proposal), {"id", "name", "summary", "directoryTree"})
+        updated, result = apply_selection(self.plan, self.decision)
+        self.assertEqual(result["nextAction"], "create-directory-shell")
+        self.assertEqual(updated["androidAnalysis"], self.plan["androidAnalysis"])
+
+    def test_selecting_nonrecommended_scheme_does_not_change_recommendation_or_trees(self):
+        original = copy.deepcopy(self.plan)
+        updated, result = apply_selection(self.plan, self.decision)
+        self.assertEqual(self.plan, original)
+        self.assertEqual(updated["recommendedProposalId"], "hybrid")
+        self.assertEqual(updated["selectedProposalId"], "android-mirror")
+        self.assertEqual(updated["proposals"], original["proposals"])
+        self.assertNotIn("selection", updated)
+        proposal, confirmation = read_selection(updated, self.decision)
+        self.assertEqual(proposal, updated["proposals"][0])
+        self.assertEqual(confirmation["requestId"], self.decision["requestId"])
+        self.assertEqual(result["nextAction"], "create-directory-shell")
+        validate_plan(updated)
+
+    def test_select_only_does_not_instruct_creation(self):
+        self.decision["action"] = "select"
+        updated, result = apply_selection(self.plan, self.decision)
+        self.assertEqual(result["nextAction"], "selection-recorded")
+        self.assertEqual(updated["selectedProposalId"], "android-mirror")
+
+    def test_exact_retry_does_not_change_plan(self):
+        updated, _ = apply_selection(self.plan, self.decision)
+        retry, result = apply_selection(updated, self.decision, self.decision)
+        self.assertEqual(retry, updated)
+        self.assertEqual(result["status"], "already-applied")
+
+    def test_request_id_cannot_be_reused_with_changed_content(self):
+        updated, _ = apply_selection(self.plan, self.decision)
+        for key, value in (("selectedProposalId", "hybrid"), ("action", "select"), ("notes", "changed")):
+            changed = {**self.decision, key: value}
+            with self.subTest(key=key), self.assertRaisesRegex(ContractError, "requestId"):
+                apply_selection(updated, changed, self.decision)
+
+    def test_new_request_can_change_the_selected_scheme(self):
+        updated, _ = apply_selection(self.plan, self.decision)
+        changed = {**self.decision, "requestId": "request-2", "selectedProposalId": "harmony-practice"}
+        final, result = apply_selection(updated, changed, self.decision)
+        self.assertEqual(result["status"], "applied")
+        self.assertEqual(final["selectedProposalId"], "harmony-practice")
+        _, confirmation = read_selection(final, changed)
+        self.assertEqual(confirmation["selectedProposalId"], "harmony-practice")
+
+    def test_wrong_plan_scheme_action_and_extra_paths_are_rejected(self):
+        for key, value in (
+            ("planId", "another-project"), ("planId", True),
+            ("selectedProposalId", "unknown"), ("action", "run-command"),
+            ("targetRoot", "E:/other"), ("directoryTree", {}),
+        ):
+            with self.subTest(key=key), self.assertRaises(ContractError):
+                apply_selection(self.plan, {**self.decision, key: value})
+        self.assertIsNone(self.plan["selectedProposalId"])
+
+    def test_plan_and_callback_only_need_content_and_selection_metadata(self):
+        self.assertEqual(set(self.plan), {
+            "planId", "project", "androidAnalysis", "proposals", "recommendedProposalId",
+            "recommendationReason", "selectedProposalId",
+        })
+        self.assertEqual(set(self.decision), {
+            "requestId", "planId", "selectedProposalId", "action", "source", "notes",
+        })
+        validate_plan(self.plan)
+        updated, _ = apply_selection(self.plan, self.decision)
+        self.assertEqual(set(updated), set(self.plan))
+
+    def test_fixed_analysis_fields_and_concise_risk_cards_are_validated(self):
+        stack = self.plan["androidAnalysis"]["techStack"]
+        invalid = (
+            {"techStack": "Kotlin"}, {"techStack": [""]},
+            {"techStack": {key: value for key, value in stack.items() if key != "storage"}},
+            {"techStack": {**stack, "ui": ""}},
+            {"techStack": {**stack, "language": ["Kotlin", "Java"]}},
+            {"techStack": {**stack, "frameworks": "extra category"}},
+            {"risks": ["long unstructured risk"]},
+            {"risks": [{"title": "存储适配", "impact": ""}]},
+            {"risks": [{"title": "存储适配"}]},
+            {"risks": [{"title": "存储适配", "impact": "需核验", "answerRequired": True}]},
+            {"risks": [{"title": str(index), "impact": "影响"} for index in range(6)]},
+        )
+        for fields in invalid:
+            with self.subTest(fields=fields), self.assertRaises(ContractError):
+                validate_plan({**self.plan, "androidAnalysis": {**self.plan["androidAnalysis"], **fields}})
+
+    def test_removed_fields_are_not_reintroduced_into_compact_contract(self):
+        cases = (("project", "targetRoot"), ("project", "scope"), ("androidAnalysis", "regions"),
+                 ("androidAnalysis", "structure"), ("androidAnalysis", "openQuestions"),
+                 ("androidAnalysis", "dependencies"), ("proposal", "mappings"),
+                 ("proposal", "dependencies"), ("proposal", "sharedOwners"),
+                 ("proposal", "benefits"), ("proposal", "costs"), ("proposal", "risks"))
+        for section, field in cases:
+            broken = copy.deepcopy(self.plan)
+            value = broken["proposals"][0] if section == "proposal" else broken[section]
+            value[field] = []
+            with self.subTest(section=section, field=field), self.assertRaisesRegex(ContractError, "unknown fields"):
+                validate_plan(broken)
+
+    def test_invalid_paths_case_collisions_and_skipped_levels_are_rejected(self):
+        for path in ("../escape", "/absolute", "E:/absolute", "a\\b", "a//b", "a/./b", "a/../b", "NUL", "x.", "{pages,state}", "a/b"):
+            broken = copy.deepcopy(self.plan)
+            leaf = broken["proposals"][0]["directoryTree"]["children"][0]
+            leaf["path"] = path
+            leaf["name"] = path.split("/")[-1]
+            with self.subTest(path=path), self.assertRaises(ContractError):
+                validate_plan(broken)
+        root = self.plan["proposals"][0]["directoryTree"]
+        root["children"].append({"name": "ENTRY", "path": "ENTRY", "description": "collision", "kind": "directory", "children": []})
+        with self.assertRaisesRegex(ContractError, "case-conflicting"):
+            validate_plan(self.plan)
+
+    def test_nested_module_and_missing_child_array_are_rejected(self):
+        entry = self.plan["proposals"][0]["directoryTree"]["children"][1]
+        entry["children"][0]["kind"] = "HAR"
+        with self.assertRaisesRegex(ContractError, "nested module"):
+            validate_plan(self.plan)
+        entry["children"][0]["kind"] = "directory"
+        del entry["children"][0]["children"]
+        with self.assertRaises(ContractError):
+            validate_plan(self.plan)
+
+    def test_empty_tree_or_tree_without_application_module_is_rejected(self):
+        for mode in ("empty", "no-hap", "hap-without-source"):
+            broken = copy.deepcopy(self.plan)
+            tree = broken["proposals"][0]["directoryTree"]
+            if mode == "empty":
+                tree["children"] = []
+            elif mode == "no-hap":
+                tree["children"][1].pop("kind")
+            else:
+                tree["children"][1]["children"] = []
+            with self.subTest(mode=mode), self.assertRaises(ContractError):
+                validate_plan(broken)
+
+    def test_read_preserves_user_notes_for_implementation_review(self):
+        answer = {**self.decision, "notes": "保留现有目录，只补充风险说明。"}
+        selected, _ = apply_selection(self.plan, answer)
+        _, result = read_selection(selected, answer)
+        self.assertEqual(result["notes"], answer["notes"])
+
+    def test_new_submission_cannot_overwrite_the_confirmation_input_in_place(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, saved_file = root / "architecture-plan.json", root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            saved_file.write_text(json.dumps(self.decision), encoding="utf-8")
+            original = plan_file.read_bytes()
+            result = self.run_cli("apply-selection", plan_file, saved_file)
+            self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+            self.assertEqual(plan_file.read_bytes(), original)
+
+    def test_required_content_scheme_identity_and_selection_consistency_are_checked(self):
+        mutations = (
+            lambda p: p["project"].pop("summary"),
+            lambda p: p["androidAnalysis"].pop("risks"),
+            lambda p: p["androidAnalysis"].pop("techStack"),
+            lambda p: p["androidAnalysis"].update(risks="unknown"),
+            lambda p: p["proposals"][1].pop("directoryTree"),
+            lambda p: p["proposals"].pop(),
+            lambda p: p["proposals"][0].update(id="hybrid"),
+            lambda p: p.update(selectedProposalId="unknown"),
+            lambda p: p.update(selection=None),
+        )
+        for index, mutate in enumerate(mutations):
+            broken = copy.deepcopy(self.plan)
+            mutate(broken)
+            with self.subTest(index=index), self.assertRaises(ContractError):
+                validate_plan(broken)
+
+    def run_cli(self, *args):
+        return subprocess.run([sys.executable, str(HELPER), *map(str, args)],
+                              capture_output=True, text=True, encoding="utf-8", timeout=10)
+
+    def test_dashboard_and_question_use_the_same_durable_confirmation_and_read_step(self):
+        for source in ("dashboard", "question"):
+            with self.subTest(source=source), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                plan_file, answer_file = root / "architecture-plan.json", root / "tool-answer.json"
+                saved_file = root / "architecture-selection.json"
+                plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+                answer = {**self.decision, "source": source}
+                answer_file.write_text(json.dumps(answer), encoding="utf-8")
+                applied = self.run_cli("apply-selection", plan_file, answer_file)
+                self.assertEqual(applied.returncode, 0, applied.stdout + applied.stderr)
+                self.assertEqual(json.loads(saved_file.read_text(encoding="utf-8")), answer)
+                saved_plan = json.loads(plan_file.read_text(encoding="utf-8"))
+                self.assertEqual(saved_plan["selectedProposalId"], answer["selectedProposalId"])
+                self.assertNotIn("selection", saved_plan)
+                resumed = self.run_cli("read-selection", plan_file)
+                self.assertEqual(resumed.returncode, 0, resumed.stdout + resumed.stderr)
+                output = json.loads(resumed.stdout)
+                self.assertEqual(output["source"], source)
+                self.assertEqual(output["nextAction"], "create-directory-shell")
+                self.assertEqual(output["selectedProposalId"], "android-mirror")
+                self.assertEqual({p.name for p in root.iterdir()}, {plan_file.name, answer_file.name, saved_file.name})
+
+    def test_read_rejects_unconfirmed_or_mismatched_selection(self):
+        with self.assertRaisesRegex(ContractError, "no confirmed"):
+            read_selection(self.plan, self.decision)
+        updated, _ = apply_selection(self.plan, self.decision)
+        for key, value in (("planId", "other-plan"), ("selectedProposalId", "hybrid")):
+            with self.subTest(key=key), self.assertRaisesRegex(ContractError, "does not match"):
+                read_selection(updated, {**self.decision, key: value})
+
+    def test_read_select_only_never_requests_creation(self):
+        answer = {**self.decision, "action": "select", "source": "question"}
+        updated, _ = apply_selection(self.plan, answer)
+        _, result = read_selection(updated, answer)
+        self.assertEqual(result["nextAction"], "selection-recorded")
+
+    def test_missing_confirmation_file_prevents_directory_implementation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            plan_file = Path(directory) / "architecture-plan.json"
+            selected, _ = apply_selection(self.plan, self.decision)
+            plan_file.write_text(json.dumps(selected), encoding="utf-8")
+            result = self.run_cli("read-selection", plan_file)
+            self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout)["status"], "error")
+
+    def test_recovery_applies_saved_question_answer_before_reading_implementation_input(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, saved_file = root / "architecture-plan.json", root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            answer = {**self.decision, "source": "question"}
+            saved_file.write_text(json.dumps(answer), encoding="utf-8")
+            pending = self.run_cli("read-selection", plan_file)
+            self.assertEqual(pending.returncode, 1)
+            recovered = self.run_cli("apply-selection", plan_file, saved_file, "--recover")
+            self.assertEqual(recovered.returncode, 0, recovered.stdout + recovered.stderr)
+            ready = self.run_cli("read-selection", plan_file)
+            self.assertEqual(ready.returncode, 0, ready.stdout + ready.stderr)
+            self.assertEqual(json.loads(ready.stdout)["source"], "question")
+
+    def test_cli_retries_without_writing_and_never_creates_target(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            target = root / "not-created"
+            plan_file, decision_file = root / "architecture-plan.json", root / "incoming-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            decision_file.write_text(json.dumps(self.decision), encoding="utf-8-sig")
+            result = self.run_cli("apply-selection", plan_file, decision_file)
+            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout)["nextAction"], "create-directory-shell")
+            first_write = plan_file.stat().st_mtime_ns
+            retry = self.run_cli("apply-selection", plan_file, decision_file)
+            self.assertEqual(retry.returncode, 0, retry.stdout + retry.stderr)
+            self.assertEqual(json.loads(retry.stdout)["status"], "already-applied")
+            self.assertEqual(plan_file.stat().st_mtime_ns, first_write)
+            self.assertFalse(target.exists())
+            self.assertEqual({p.name for p in root.iterdir()}, {plan_file.name, decision_file.name, "architecture-selection.json"})
+
+    def test_changed_retry_is_rejected_without_replacing_confirmation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            saved = root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            incoming.write_text(json.dumps(self.decision), encoding="utf-8")
+            self.assertEqual(self.run_cli("apply-selection", plan_file, incoming).returncode, 0)
+            plan_bytes, confirmed_bytes = plan_file.read_bytes(), saved.read_bytes()
+            incoming.write_text(json.dumps({**self.decision, "action": "select"}), encoding="utf-8")
+            rejected = self.run_cli("apply-selection", plan_file, incoming)
+            self.assertEqual(rejected.returncode, 1, rejected.stdout)
+            self.assertIn("requestId", json.loads(rejected.stdout)["error"])
+            self.assertEqual(plan_file.read_bytes(), plan_bytes)
+            self.assertEqual(saved.read_bytes(), confirmed_bytes)
+
+    def test_recovery_flag_requires_the_script_owned_confirmation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            incoming.write_text(json.dumps(self.decision), encoding="utf-8")
+            rejected = self.run_cli("apply-selection", plan_file, incoming, "--recover")
+            self.assertEqual(rejected.returncode, 1)
+            self.assertFalse((root / "architecture-selection.json").exists())
+
+    def test_failed_plan_write_cannot_enter_implementation_and_can_recover(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            saved = root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            incoming.write_text(json.dumps(self.decision), encoding="utf-8")
+            original = plan_file.read_bytes()
+            save_json = helper.save_json
+
+            def fail_plan_write(path, value):
+                if path == plan_file:
+                    raise OSError("simulated plan write failure")
+                save_json(path, value)
+
+            arguments = [str(HELPER), "apply-selection", str(plan_file), str(incoming)]
+            with patch.object(sys, "argv", arguments), patch.object(helper, "save_json", side_effect=fail_plan_write):
+                with contextlib.redirect_stdout(io.StringIO()):
+                    self.assertEqual(helper.main(), 1)
+            self.assertEqual(plan_file.read_bytes(), original)
+            self.assertEqual(json.loads(saved.read_text(encoding="utf-8")), self.decision)
+            self.assertEqual(self.run_cli("read-selection", plan_file).returncode, 1)
+            recovered = self.run_cli("apply-selection", plan_file, saved, "--recover")
+            self.assertEqual(recovered.returncode, 0, recovered.stdout + recovered.stderr)
+            self.assertEqual(self.run_cli("read-selection", plan_file).returncode, 0)
+
+    def test_reloaded_notes_are_utf8_even_with_an_ascii_console(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            answer = {**self.decision, "notes": "保留目录，补充说明 📝"}
+            incoming.write_text(json.dumps(answer, ensure_ascii=False), encoding="utf-8")
+            self.assertEqual(self.run_cli("apply-selection", plan_file, incoming).returncode, 0)
+            result = subprocess.run([sys.executable, str(HELPER), "read-selection", str(plan_file)],
+                                    capture_output=True, timeout=10,
+                                    env={**os.environ, "PYTHONIOENCODING": "ascii"})
+            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout.decode("utf-8"))["notes"], answer["notes"])
+
+    def test_cli_error_leaves_plan_bytes_unchanged_and_returns_structured_error(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, decision_file = root / "plan.json", root / "decision.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            original = plan_file.read_bytes()
+            for content in (json.dumps({**self.decision, "planId": "other-plan"}), '{"action":"select","action":"select-and-create"}', '[]', '{invalid'):
+                decision_file.write_text(content, encoding="utf-8")
+                result = self.run_cli("apply-selection", plan_file, decision_file)
+                self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+                self.assertEqual(json.loads(result.stdout)["status"], "error")
+                self.assertEqual(plan_file.read_bytes(), original)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/d2h-cloud-knowledge/SKILL.md

@@ -27,7 +27,7 @@ version: 1.3.0
 
 | 环节 | 触发条件 | 查什么 |
 |------|----------|--------|
-| 页面 spec 生成（`d2h-spec-plan`） | spec 标记了平台能力项（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等） | 该能力对应 Kit/API 是否可用、是否受系统能力限制，写入 spec 依据 |
+| Spec 行为或平台能力核验 | spec 标记了平台能力项（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等） | 该能力对应 Kit/API 是否可用、是否受系统能力限制，写入 spec 依据 |
 | 页面实现前（`d2h-spec-develop` 步骤 1-2） | 功能清单（F-xxx）中存在平台能力或不确定的 @kit.* Kit / @ohos.* 模块 API | API 签名、参数/返回值、所需权限、错误码、推荐用法与指南 |
 | 页面实现中 | 不确定 ArkUI 组件/属性行为（如 Tabs、Swiper、手势、懒加载） | 开发指南与 FAQ 中的权威行为描述 |
 | 构建失败分诊 | 编译错误指向 @kit.* / @ohos.* API 签名、类型、import 模块名 | 核对该 API 的真实签名与起始版本，避免臆造签名反复试错 |

package/skills/d2h-dashboard/SKILL.md

@@ -14,43 +14,57 @@ npx --yes d2h-dashboard@latest --dataDir <项目>/.migration [--port 8080] [--ho
 - `--dataDir` 必填，指向迁移工作区 `.migration`；`--port` 默认 8080，占用自动 +1 重试至 8090；`--host` 默认 `127.0.0.1`。
 - 启动链：npx 拉包并执行 bin → `node …/server/serve.mjs` 常驻，同时托管前端与 `/api/data/*`。
 - 成功后 stdout 固定两行，实际 URL 以第二行为准：`[dashboard] dataDir=<绝对路径>`、`[dashboard] http://<host>:<实际端口>`。
-- 健康检查：`GET /api/data/manifest` 返回 200 且 `root` 等于传入 dataDir（绝对路径规范化比较）。
 
 ## 自动启动（迁移会话内）
 
 - `.migration/progress.json` 出现（`progress init` 后）或恢复会话已存在 → 自动启动看板并用默认浏览器打开 URL，不等用户请求；每轮会话执行一次，复用实例不重复启动、不重复打开。
 - 启动或打开失败只记录不阻塞迁移，下次阶段更新重试一次。
+- 确认 `$url` 后按「TUI 常驻横幅」一节更新横幅；端口漂移（重启落到新端口）同样触发更新。
 
-## 后台启动与打开浏览器
+## 后台启动与验证（必做）
 
-常驻进程必须后台启动（非交互、明确超时）：
+用 `--detach` 自守护启动，一条命令完成（服务器常驻、日志按项目隔离、父进程就绪后自行退出），无需任何 cmd 包装或 shell 重定向：
 
-```bash
-# bash
-nohup npx --yes d2h-dashboard@latest --dataDir "$DATA_DIR" > /tmp/d2h-dashboard.log 2>&1 &
+```powershell
+# Windows：npx 必须用 npx.cmd（npx.ps1 被执行策略拦截）
+npx.cmd --yes d2h-dashboard@latest --dataDir "$dataDir" --detach
 ```
 
-```powershell
-# Windows PowerShell 5.1：npx 必须用 npx.cmd（npx.ps1 被执行策略拦截）；
-# 重定向交给脱离的 cmd，禁止 Start-Process -RedirectStandardOutput——会卡死会话（已实测）
-$log = "$env:TEMP\d2h-dashboard.log"
-$arg = "/c npx.cmd --yes d2h-dashboard@latest --dataDir `"$dataDir`" > `"$log`" 2> `"$log.err`""
-Start-Process -FilePath cmd.exe -ArgumentList $arg -WindowStyle Hidden | Out-Null
-Start-Sleep -Seconds 2; Get-Content $log -ErrorAction SilentlyContinue
+```bash
+# bash（macOS/Linux）
+npx --yes d2h-dashboard@latest --dataDir "$DATA_DIR" --detach
 ```
 
-打开浏览器（Windows 必须 `cmd /c start`，`Start-Process "http://…"` 静默不弹窗，已实测）：
+事实源铁律：**实例唯一事实源 = 端口探测的 manifest root；日志只是辅助排查，禁止用日志内容判定实例归属或端口。** 启动后必须轮询验证成功，禁止只看输出就宣布就绪：
 
 ```powershell
-cmd /c start "" "http://127.0.0.1:<port>"     # Windows
+$deadline = (Get-Date).AddSeconds(20); $url = $null
+do {
+  Start-Sleep -Milliseconds 500
+  foreach ($p in 8080..8090) {
+    try { $j = (Invoke-WebRequest "http://127.0.0.1:$p/api/data/manifest" -TimeoutSec 1 -UseBasicParsing).Content | ConvertFrom-Json
+          if ($j.root -eq $dataDir) { $url = "http://127.0.0.1:$p"; break } } catch {}
+  }
+} while (-not $url -and (Get-Date) -lt $deadline)
 ```
 
-```bash
-open "http://…"        # macOS
-xdg-open "http://…"    # Linux
-```
+未命中 → 读 stdout 里的 `log=…` 路径尾部定位原因，重试一次；仍失败只记录不阻塞。
+
+确认 `$url` 后打开浏览器（Windows 必须 `cmd /c start "" "<url>"`，`Start-Process "<url>"` 静默不弹窗；macOS `open`、Linux `xdg-open`）。
+
+**URL 告知规范**：URL 单独成行或用反引号包裹，其后不得紧跟任何文字（含中文括号说明）——否则 markdown 会把 URL+后缀渲染成单个失效链接，说明放下一行。
+
+## TUI 常驻横幅
+
+- 确认 `$url` 后（启动/复用/端口漂移）执行，10s 超时防卡死：
+  ```powershell
+  Start-Process cmd.exe -ArgumentList '/c opencode-tui-extension.cmd set "<url>"' -NoNewWindow -PassThru | Wait-Process -Timeout 10 -ErrorAction SilentlyContinue
+  ```
+  bash：`timeout 10 opencode-tui-extension set "<url>"`
+- 停止看板后同法执行 `clear`
+- 失败/超时/命令不存在：只记录不阻塞，降级为 URL 单独成行输出；安装注册由 `d2h install` 负责，本 skill 不做初始化
 
 ## 复用与停止
 
-- **复用**：启动前探测 8080–8090 `GET /api/data/manifest`（1s 超时），`root` == 目标 dataDir 且 `GET /` 返回 200 才复用该 URL；仅 root 匹配但 `GET /` 非 200 属损坏实例（如资产被删/版本切换残留），按停止规则杀掉后重新启动。root 不匹配跳过（其他流程的服务器）。服务器常驻，会话结束不回收，残留进程属预期。
-- **停止**：仅用户显式要求（「关闭看板」「关闭 XX 项目看板」）才执行，且必须 root 归属校验通过：Windows `Get-NetTCPConnection -LocalPort <port> -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess }`（杀 node 真实 PID，cmd 包装 PID 无效）；bash `kill <pid>`。未找到 → 报告未在运行；root 不匹配 → 跳过并说明属于其他流程。
+- **复用**：启动前探测 8080–8090 `GET /api/data/manifest`（1s 超时），`root` == 目标 dataDir 且 `GET /` 返回 200 才复用该 URL；仅 root 匹配但 `GET /` 非 200 属损坏实例（资产被删/版本切换残留），按停止规则杀掉后重新启动。root 不匹配跳过（其他流程的服务器）。服务器常驻，会话结束不回收，残留进程属预期。
+- **停止**：仅用户显式要求（「关闭看板」「关闭 XX 项目看板」）才执行，且必须 root 归属校验通过：Windows `Get-NetTCPConnection -LocalPort <port> -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess }`（杀 node 真实 PID，cmd 包装 PID 无效）；bash `kill <pid>`。未找到 → 报告未在运行；root 不匹配 → 跳过并说明属于其他流程。停止成功后按「TUI 常驻横幅」执行 `clear`。