@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/docx/tests/test_docx_skill.py

@@ -0,0 +1,525 @@
+# MIT License. End-to-end tests for the docx skill.
+"""Pytest suite proving create / read / edit / template round-trips.
+
+Runs the scripts as subprocesses (argparse CLIs) and also verifies the
+outputs with python-docx directly. Stdlib + python-docx only; all
+fixtures are generated on the fly; no network.
+"""
+from __future__ import annotations
+
+import json
+import os
+import struct
+import subprocess
+import sys
+import zlib
+from pathlib import Path
+
+import pytest
+from docx import Document
+
+SKILL = Path(__file__).resolve().parent.parent
+SCRIPTS = SKILL / "scripts"
+
+NON_ASCII = "Фамилия — ‘test’"
+
+
+def make_png(path: Path) -> None:
+    """Write a tiny valid 2x2 red PNG using only stdlib."""
+    def chunk(tag: bytes, data: bytes) -> bytes:
+        return (struct.pack(">I", len(data)) + tag + data
+                + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
+
+    ihdr = struct.pack(">IIBBBBB", 2, 2, 8, 2, 0, 0, 0)
+    raw = b"".join(b"\x00" + b"\xff\x00\x00" * 2 for _ in range(2))
+    png = (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr)
+           + chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b""))
+    path.write_bytes(png)
+
+
+def run(script: str, *args: str) -> dict:
+    env = dict(os.environ)
+    env["LC_ALL"] = "C"  # prove no locale-default text reads
+    env["PYTHONIOENCODING"] = "utf-8"
+    proc = subprocess.run(
+        [sys.executable, str(SCRIPTS / script), *map(str, args)],
+        capture_output=True, env=env, check=False)
+    assert proc.returncode == 0, proc.stderr.decode("utf-8", "replace")
+    return json.loads(proc.stdout.decode("utf-8"))
+
+
+@pytest.fixture(scope="module")
+def workdir(tmp_path_factory) -> Path:
+    return tmp_path_factory.mktemp("docxskill")
+
+
+@pytest.fixture(scope="module")
+def created(workdir: Path) -> Path:
+    """Create a document exercising every create feature."""
+    png = workdir / "pic.png"
+    make_png(png)
+    spec = {
+        "page": {"width_mm": 210, "height_mm": 297,
+                 "margins_mm": {"top": 25, "bottom": 25,
+                                "left": 20, "right": 20}},
+        "header": "Report header",
+        "footer": "Page footer",
+        "styles": [{"name": "FancyNote", "base": "Normal", "font": "Arial",
+                    "size_pt": 11, "italic": True, "color": "1F4E79"}],
+        "blocks": [
+            {"type": "heading", "text": "Main Title", "level": 1},
+            {"type": "heading", "text": "Section One", "level": 2},
+            {"type": "paragraph", "runs": [
+                {"text": "plain "},
+                {"text": "boldbit", "bold": True},
+                {"text": " italicbit", "italic": True},
+                {"text": " underbit", "underline": True}]},
+            {"type": "paragraph", "text": "Styled note.",
+             "style": "FancyNote"},
+            {"type": "bullet_list", "items": ["alpha", "beta"]},
+            {"type": "numbered_list", "items": ["first", "second"]},
+            {"type": "table", "header": ["Name", "Qty"],
+             "rows": [["Widget", "3"], ["Gadget", "5"]],
+             "style": "Table Grid", "header_bold": True},
+            {"type": "image", "path": str(png), "width_mm": 30},
+            {"type": "page_break"},
+            {"type": "paragraph", "text": "After the break."},
+        ],
+    }
+    spec_path = workdir / "spec.json"
+    spec_path.write_text(json.dumps(spec), encoding="utf-8")
+    out = workdir / "created.docx"
+    res = run("docx_create.py", spec_path, out)
+    assert res["ok"] and out.exists()
+    return out
+
+
+class TestCreateAndRead:
+    def test_text_roundtrip(self, created: Path):
+        text = run("docx_read.py", created, "--text")
+        body = "\n".join(text["body"])
+        for expected in ("Main Title", "plain boldbit italicbit underbit",
+                         "Styled note.", "alpha", "second",
+                         "After the break."):
+            assert expected in body
+        assert text["tables"] == [[["Name", "Qty"], ["Widget", "3"],
+                                   ["Gadget", "5"]]]
+        assert "Report header" in text["headers"]
+        assert "Page footer" in text["footers"]
+
+    def test_structure(self, created: Path):
+        st = run("docx_read.py", created, "--structure")
+        outline = [(h["level"], h["text"]) for h in st["outline"]]
+        assert (1, "Main Title") in outline
+        assert (2, "Section One") in outline
+        assert st["table_count"] == 1
+        assert st["tables"][0] == {"rows": 3, "cols": 2}
+
+    def test_styles_used(self, created: Path):
+        styles = run("docx_read.py", created, "--styles")["styles"]
+        for s in ("Heading 1", "FancyNote", "List Bullet", "List Number",
+                  "Table Grid"):
+            assert s in styles
+
+    def test_images_extracted(self, created: Path, workdir: Path):
+        outdir = workdir / "media"
+        res = run("docx_read.py", created, "--images", outdir)
+        assert len(res["images"]) == 1
+        img = Path(res["images"][0])
+        assert img.read_bytes().startswith(b"\x89PNG")
+
+    def test_run_formatting_persisted(self, created: Path):
+        doc = Document(str(created))
+        para = next(p for p in doc.paragraphs if "boldbit" in p.text)
+        flags = {r.text.strip(): (r.bold, r.italic, r.underline)
+                 for r in para.runs if r.text.strip()}
+        assert flags["boldbit"][0] is True
+        assert flags["italicbit"][1] is True
+        assert flags["underbit"][2] is True
+
+    def test_page_setup(self, created: Path):
+        sec = Document(str(created)).sections[0]
+        assert round(sec.page_width.mm) == 210
+        assert round(sec.top_margin.mm) == 25
+
+    def test_revisions_detection(self, created: Path):
+        rev = run("docx_read.py", created, "--revisions")
+        assert rev["has_tracked_changes"] is False
+        assert rev["comments"] is False
+
+
+class TestEdit:
+    def test_replace_preserves_formatting(self, created: Path, workdir: Path):
+        out = workdir / "edited.docx"
+        res = run("docx_edit.py", "replace", created, "--find", "boldbit",
+                  "--replace", "REPLACED", "-o", out)
+        assert res["replacements"] == 1
+        doc = Document(str(out))
+        para = next(p for p in doc.paragraphs if "REPLACED" in p.text)
+        run_ = next(r for r in para.runs if "REPLACED" in r.text)
+        assert run_.bold is True  # formatting survived
+
+    def test_set_cell(self, created: Path, workdir: Path):
+        out = workdir / "cell.docx"
+        run("docx_edit.py", "set-cell", created, "--table", "0", "--row",
+            "1", "--col", "1", "--text", "99", "-o", out)
+        assert Document(str(out)).tables[0].cell(1, 1).text == "99"
+
+    def test_insert_and_delete(self, created: Path, workdir: Path):
+        out = workdir / "ins.docx"
+        run("docx_edit.py", "insert", created, "--index", "0", "--text",
+            "Inserted first", "-o", out)
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Inserted first"
+        out2 = workdir / "del.docx"
+        run("docx_edit.py", "delete", out, "--index", "0", "-o", out2)
+        assert Document(str(out2)).paragraphs[0].text != "Inserted first"
+
+    def test_apply_style(self, created: Path, workdir: Path):
+        out = workdir / "styled.docx"
+        doc = Document(str(created))
+        idx = next(i for i, p in enumerate(doc.paragraphs)
+                   if p.text == "After the break.")
+        run("docx_edit.py", "style", created, "--index", str(idx),
+            "--style", "Heading 2", "-o", out)
+        doc2 = Document(str(out))
+        assert doc2.paragraphs[idx].style.name == "Heading 2"
+
+
+class TestTemplate:
+    def test_fill_everywhere_non_ascii(self, workdir: Path):
+        # Build a template: tokens in body, split runs, table, header, footer.
+        tpl = workdir / "tpl.docx"
+        doc = Document()
+        doc.sections[0].header.paragraphs[0].text = "H: {{name}}"
+        doc.sections[0].footer.paragraphs[0].text = "F: {{date}}"
+        p = doc.add_paragraph()
+        p.add_run("Dear {{na")          # token split across runs
+        p.add_run("me}}, hello.")
+        t = doc.add_table(rows=1, cols=2)
+        t.cell(0, 0).text = "{{name}}"
+        t.cell(0, 1).text = "{{ date }}"   # spaced variant
+        doc.add_paragraph("Unfilled: {{missing}}")
+        doc.save(str(tpl))
+
+        values = workdir / "values.json"
+        values.write_text(
+            json.dumps({"name": NON_ASCII, "date": "2026-08-08"},
+                       ensure_ascii=False), encoding="utf-8")
+        out = workdir / "filled.docx"
+        res = run("docx_template.py", tpl, values, out)
+        assert res["ok"] is True
+        assert res["unfilled_tokens"] == ["missing"]
+
+        text = run("docx_read.py", out, "--text")
+        assert f"Dear {NON_ASCII}, hello." in text["body"]
+        assert text["tables"][0][0] == [NON_ASCII, "2026-08-08"]
+        assert f"H: {NON_ASCII}" in text["headers"]
+        assert "F: 2026-08-08" in text["footers"]
+
+    def test_strict_fails_on_unfilled(self, workdir: Path):
+        tpl = workdir / "tpl2.docx"
+        doc = Document()
+        doc.add_paragraph("{{gone}}")
+        doc.save(str(tpl))
+        values = workdir / "empty.json"
+        values.write_text("{}", encoding="utf-8")
+        env = dict(os.environ, LC_ALL="C", PYTHONIOENCODING="utf-8")
+        proc = subprocess.run(
+            [sys.executable, str(SCRIPTS / "docx_template.py"), str(tpl),
+             str(values), str(workdir / "out2.docx"), "--strict"],
+            capture_output=True, env=env, check=False)
+        assert proc.returncode == 1
+        payload = json.loads(proc.stdout.decode("utf-8"))
+        assert payload["unfilled_tokens"] == ["gone"]
+
+
+# --------------------------------------------------------------- new parity
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def q(tag: str) -> str:
+    return f"{{{W}}}{tag}"
+
+
+def run_raw(script: str, *args: str):
+    env = dict(os.environ, LC_ALL="C", PYTHONIOENCODING="utf-8")
+    return subprocess.run(
+        [sys.executable, str(SCRIPTS / script), *map(str, args)],
+        capture_output=True, env=env, check=False)
+
+
+def _add_ins(para, rev_id: int, text: str, author="Editor"):
+    from lxml import etree
+    ins = etree.SubElement(para._p, q("ins"))
+    ins.set(q("id"), str(rev_id))
+    ins.set(q("author"), author)
+    ins.set(q("date"), "2026-01-02T03:04:05Z")
+    r = etree.SubElement(ins, q("r"))
+    t = etree.SubElement(r, q("t"))
+    t.text = text
+    t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+
+
+def _add_del(para, rev_id: int, text: str, author="Editor"):
+    from lxml import etree
+    dele = etree.SubElement(para._p, q("del"))
+    dele.set(q("id"), str(rev_id))
+    dele.set(q("author"), author)
+    dele.set(q("date"), "2026-01-02T03:04:05Z")
+    r = etree.SubElement(dele, q("r"))
+    t = etree.SubElement(r, q("delText"))
+    t.text = text
+    t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+
+
+@pytest.fixture()
+def tracked(tmp_path: Path) -> Path:
+    """Doc with a tracked insertion + deletion in body AND in a table."""
+    doc = Document()
+    p = doc.add_paragraph("Base ")
+    _add_ins(p, 1, "ADDED")
+    _add_del(p, 2, "REMOVED")
+    table = doc.add_table(rows=1, cols=1)
+    cp = table.cell(0, 0).paragraphs[0]
+    cp.add_run("Cell ")
+    _add_ins(cp, 3, "CELLADD")
+    _add_del(cp, 4, "CELLGONE")
+    path = tmp_path / "tracked.docx"
+    doc.save(str(path))
+    return path
+
+
+class TestRevisions:
+    def test_list(self, tracked: Path):
+        res = run("docx_revisions.py", "list", tracked)
+        revs = {r["id"]: r for r in res["revisions"]}
+        assert len(revs) == 4
+        assert revs["1"] == {"id": "1", "author": "Editor",
+                             "date": "2026-01-02T03:04:05Z",
+                             "type": "insertion", "text": "ADDED"}
+        assert revs["2"]["type"] == "deletion"
+        assert revs["2"]["text"] == "REMOVED"
+        assert revs["3"]["text"] == "CELLADD"  # inside table
+        assert revs["4"]["type"] == "deletion"
+
+    def test_accept_all(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "acc.docx"
+        res = run("docx_revisions.py", "accept-all", tracked, "-o", out)
+        assert res["resolved"] == 4
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base ADDED"
+        assert doc.tables[0].cell(0, 0).text == "Cell CELLADD"
+        assert run("docx_revisions.py", "list", out)["revisions"] == []
+
+    def test_reject_all(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "rej.docx"
+        run("docx_revisions.py", "reject-all", tracked, "-o", out)
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base REMOVED"
+        assert doc.tables[0].cell(0, 0).text == "Cell CELLGONE"
+
+    def test_accept_single_by_id(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "one.docx"
+        res = run("docx_revisions.py", "accept", tracked, "--id", "1",
+                  "-o", out)
+        assert res["resolved"] == 1
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base ADDED"  # del 2 unresolved
+        remaining = run("docx_revisions.py", "list", out)["revisions"]
+        assert sorted(r["id"] for r in remaining) == ["2", "3", "4"]
+
+    def test_reject_single_by_id(self, tracked: Path, tmp_path: Path):
+        out = tmp_path / "rone.docx"
+        run("docx_revisions.py", "reject", tracked, "--id", "2", "-o", out)
+        doc = Document(str(out))
+        assert doc.paragraphs[0].text == "Base REMOVED"  # ins 1 unresolved
+
+    def test_unknown_id_fails(self, tracked: Path, tmp_path: Path):
+        proc = run_raw("docx_revisions.py", "accept", tracked, "--id",
+                       "999", "-o", tmp_path / "x.docx")
+        assert proc.returncode == 1
+
+
+class TestComments:
+    @pytest.fixture()
+    def base(self, tmp_path: Path) -> Path:
+        doc = Document()
+        doc.add_paragraph("The quarterly revenue rose sharply.")
+        doc.add_paragraph("Second paragraph.")
+        path = tmp_path / "base.docx"
+        doc.save(str(path))
+        return path
+
+    def test_add_list_delete(self, base: Path, tmp_path: Path):
+        out = tmp_path / "com.docx"
+        res = run("docx_comments.py", "add", base, "--target",
+                  "quarterly revenue", "--text", "Needs a source",
+                  "--author", "Reviewer", "--initials", "R", "-o", out)
+        assert res["ok"] is True
+        cid = res["comment_id"]
+
+        listed = run("docx_comments.py", "list", out)["comments"]
+        assert len(listed) == 1
+        c = listed[0]
+        assert c["id"] == cid
+        assert c["author"] == "Reviewer"
+        assert c["text"] == "Needs a source"
+        assert c["anchored_text"] == "quarterly revenue"
+        assert c["date"]
+
+        # document text unchanged by anchoring
+        text = run("docx_read.py", out, "--text")
+        assert "The quarterly revenue rose sharply." in text["body"]
+
+        out2 = tmp_path / "nocom.docx"
+        run("docx_comments.py", "delete", out, "--id", cid, "-o", out2)
+        assert run("docx_comments.py", "list", out2)["comments"] == []
+        text2 = run("docx_read.py", out2, "--text")
+        assert "The quarterly revenue rose sharply." in text2["body"]
+
+    def test_xml_fallback_path(self, base: Path, tmp_path: Path):
+        out = tmp_path / "xmlcom.docx"
+        res = run("docx_comments.py", "add", base, "--target",
+                  "Second paragraph", "--text", "fallback note",
+                  "--author", "Bot", "--xml", "-o", out)
+        assert res["native_api"] is False
+        listed = run("docx_comments.py", "list", out)["comments"]
+        assert listed[0]["text"] == "fallback note"
+        assert listed[0]["anchored_text"] == "Second paragraph"
+        # file still opens cleanly
+        assert Document(str(out)).paragraphs[1].text == "Second paragraph."
+
+    def test_missing_target_fails(self, base: Path, tmp_path: Path):
+        proc = run_raw("docx_comments.py", "add", base, "--target",
+                       "not present", "--text", "x", "-o",
+                       tmp_path / "y.docx")
+        assert proc.returncode == 1
+
+
+class TestValidate:
+    def test_healthy_file_passes(self, created: Path):
+        res = run("docx_validate.py", created)
+        assert res["ok"] is True
+        assert all(i["severity"] != "error" for i in res["issues"])
+
+    def test_not_a_zip(self, tmp_path: Path):
+        bad = tmp_path / "bad.docx"
+        bad.write_bytes(b"this is not a zip file")
+        proc = run_raw("docx_validate.py", bad)
+        assert proc.returncode == 1
+        rep = json.loads(proc.stdout.decode("utf-8"))
+        assert rep["issues"][0]["code"] == "not-a-zip"
+
+    def test_dangling_rel_and_empty_image(self, created: Path,
+                                          tmp_path: Path):
+        import shutil
+        import zipfile
+        broken = tmp_path / "broken.docx"
+        shutil.copy(created, broken)
+        # rebuild the zip: drop the image part, zero out nothing else
+        src = zipfile.ZipFile(str(created))
+        with zipfile.ZipFile(str(broken), "w") as dst:
+            for item in src.infolist():
+                if item.filename.startswith("word/media/"):
+                    dst.writestr(item.filename, b"")  # empty image
+                else:
+                    dst.writestr(item, src.read(item.filename))
+        proc = run_raw("docx_validate.py", broken)
+        assert proc.returncode == 1
+        rep = json.loads(proc.stdout.decode("utf-8"))
+        codes = {i["code"] for i in rep["issues"]}
+        assert "empty-image" in codes
+
+    def test_missing_style(self, tmp_path: Path):
+        import zipfile
+        doc = Document()
+        doc.add_paragraph("styled", style="Heading 1")
+        path = tmp_path / "styles.docx"
+        doc.save(str(path))
+        # rewrite document.xml to reference a style id that doesn't exist
+        src = zipfile.ZipFile(str(path))
+        broken = tmp_path / "badstyle.docx"
+        with zipfile.ZipFile(str(broken), "w") as dst:
+            for item in src.infolist():
+                data = src.read(item.filename)
+                if item.filename == "word/document.xml":
+                    data = data.replace(b'w:val="Heading1"',
+                                        b'w:val="GhostStyle"')
+                dst.writestr(item, data)
+        proc = run_raw("docx_validate.py", broken)
+        assert proc.returncode == 1
+        rep = json.loads(proc.stdout.decode("utf-8"))
+        assert any(i["code"] == "missing-style" and "GhostStyle"
+                   in i["detail"] for i in rep["issues"])
+
+
+class TestNormalize:
+    def test_merges_split_runs(self, tmp_path: Path):
+        doc = Document()
+        p = doc.add_paragraph()
+        p.add_run("Hel")            # identical (no) formatting, split
+        p.add_run("lo wo")
+        p.add_run("rld")
+        b = p.add_run("BOLD1")
+        b.bold = True
+        b2 = p.add_run("BOLD2")
+        b2.bold = True
+        i = p.add_run("ital")
+        i.italic = True
+        path = tmp_path / "split.docx"
+        doc.save(str(path))
+
+        out = tmp_path / "norm.docx"
+        res = run("docx_edit.py", "normalize", path, "-o", out)
+        assert res["runs_merged"] == 3  # 2 plain merges + 1 bold merge
+
+        doc2 = Document(str(out))
+        para = doc2.paragraphs[0]
+        assert para.text == "Hello worldBOLD1BOLD2ital"
+        assert [r.text for r in para.runs] == \
+            ["Hello world", "BOLD1BOLD2", "ital"]
+        assert para.runs[1].bold is True
+        assert para.runs[2].italic is True
+
+
+class TestFields:
+    def test_toc_and_page_numbers_via_edit(self, created: Path,
+                                           tmp_path: Path):
+        out = tmp_path / "fields.docx"
+        run("docx_edit.py", "toc", created, "--index", "0", "-o", out)
+        run("docx_edit.py", "page-numbers", out)
+
+        import zipfile
+        doc_xml = zipfile.ZipFile(str(out)).read(
+            "word/document.xml").decode("utf-8")
+        assert "TOC \\o" in doc_xml
+        assert "fldChar" in doc_xml
+        footer_names = [n for n in zipfile.ZipFile(str(out)).namelist()
+                        if n.startswith("word/footer")]
+        footers = "".join(zipfile.ZipFile(str(out)).read(n).decode("utf-8")
+                          for n in footer_names)
+        assert "PAGE" in footers and "NUMPAGES" in footers
+        # still a valid document
+        assert run("docx_validate.py", out)["ok"] is True
+
+    def test_toc_and_footer_in_create_spec(self, tmp_path: Path):
+        spec = {
+            "footer_page_numbers": True,
+            "blocks": [
+                {"type": "toc"},
+                {"type": "heading", "text": "Chapter", "level": 1},
+            ],
+        }
+        spec_path = tmp_path / "fspec.json"
+        spec_path.write_text(json.dumps(spec), encoding="utf-8")
+        out = tmp_path / "fcreate.docx"
+        run("docx_create.py", spec_path, out)
+
+        import zipfile
+        z = zipfile.ZipFile(str(out))
+        assert "TOC \\o" in z.read("word/document.xml").decode("utf-8")
+        footers = "".join(z.read(n).decode("utf-8") for n in z.namelist()
+                          if n.startswith("word/footer"))
+        assert "NUMPAGES" in footers

package/skills/home-devices/SKILL.md

@@ -0,0 +1,121 @@
+---
+id: home-devices
+name: home-devices
+description: "扫描局域网里的设备（mDNS/SSDP），按设备类型用通用协议或现成开源库接入：Home Assistant、米家、NAS、打印机、电视/音箱"
+when_to_use: "用户要扫描/发现家里或局域网里的设备，或要接入/控制 Home Assistant、米家、NAS、打印机、电视、音箱、门锁、摄像头等设备时使用"
+version: "1.0.0"
+tags:
+  - home
+  - devices
+  - lan
+  - integration
+user_invocable: true
+disable_model_invocation: false
+argument_hint: "[设备或平台名，如 米家 / Home Assistant / NAS]"
+suggested_prompts:
+  - id: scan
+    title: "扫一下家里有哪些设备"
+  - id: mijia
+    title: "帮我连上米家"
+  - id: home-assistant
+    title: "帮我连上 Home Assistant"
+metadata:
+  display-name: "家庭设备发现与接入"
+---
+
+# 家庭设备发现与接入
+
+目标：在用户同意的前提下，把局域网里的设备接到这只 Jelly 上，之后用人话就能查询和控制。
+**以通用能力为主**：先扫到设备，再用通用协议或成熟的开源库去连；不为单个设备写插件。
+只有协议私有且没有现成库，或者必须常驻监听（例如持续接收门铃事件）时，才建议用户装插件。
+
+## 铁律（每条都必须遵守）
+
+1. **只扫本地网络。** 只发现本机所在的局域网（组播/本网段）。绝不扫描公网地址，不做大范围端口扫描，不对别人的网络做探测。
+2. **凭据只进保险箱。** 令牌、密码、设备 token 一律用 `request_secret`（`persist: true`，`name` 形如 `home/<平台>/<用途>`）获取，
+   之后只以 `secret://vault/<name>` 引用写进命令。先用 `request_secret` 的 `op: "list"` 查是否已存过，存过就直接用。
+   明文绝不出现在对话、memory、文件里；用户如果把密码直接贴在对话里，提醒他去改密码。
+3. **接入前先确认，而且是第一步。** 每接入一台设备或一个账号，在查保险箱、要令牌、试令牌、发任何带凭据的请求**之前**，先调用 `decision`（`mode: "approval"`）：
+   `category: "device"`，`target` 用人话写清是哪台设备（名字 + 局域网地址，如「客厅 NAS（192.168.1.20）」），
+   `summary` 一句话写清要做什么（如「接入客厅 NAS，只读查看剩余空间」）。不要写内部 id、MAC、token。
+   结果 `proceed: false` 就停下，告诉用户没有接入。即使保险箱里已经有令牌、或者上次接过，这台设备在本次对话里也要先确认。
+   用户最新一条消息若明确要求了这一步（如「把路由器管理员密码改一下」），仍调用一次 `confirm_action`，并把那句话**原文**填进 `user_request`；
+   主机核对通过就直接 `proceed: true`，不再弹卡。它只覆盖用户说的那一步（改 2.4GHz 不含 5GHz，「查一下密码」不等于授权修改），
+   只用一次；被拒/过期后不得重试或绕路，等用户新消息再说。铁律 4 的高风险，以及恢复出厂、刷固件、会断网的重启，永远照常弹卡。
+4. **高风险操作每次都确认。** 门锁、燃气（阀门/灶具）、摄像头（查看/录像/关闭）、报警（布防/撤防）、门禁 ——
+   对这几类的**每一次**操作，都必须先调用 `confirm_action`，并且带上 `risk: "high"`（`category: "device"`）。
+   漏带 `risk: "high"` 是严重错误：带上它之后用户的自动放行规则也不会跳过这张卡。不能批量确认，不能沿用上一次的确认。
+5. **接入成功必须记下来（不能省），只记地址和类型。** 只读验证一通过，**在回复用户之前**就调用
+   `memory({ action: "save", file_path: "knowledge/home-devices.md", type: "reference", content: ... })`：
+   名称、类型、局域网地址/端口、接入方式、凭据的 vault 名字（只写名字，不写值）。没写 memory 就不算接入完成。
+   绝不写令牌、密码、token。
+   这一步**没有例外**：地址是 127.0.0.1、看起来像测试环境、用户没提、之前已经记过（重新 save 会合并去重）——都照样调用。
+   调用 `memory` 并拿到返回之前，不要写给用户的接入结论。
+
+## 1. 发现
+
+按顺序做，扫到足够信息就停：
+
+- **mDNS / Bonjour**
+  - macOS：`dns-sd -B <服务类型> local.` 浏览；`dns-sd -L <实例名> <服务类型> local.` 解析主机和端口；`dns-sd -G v4 <主机名>` 取 IP。
+    `dns-sd` 不会自己退出，用 `timeout 5 dns-sd ...` 或 shell 超时收尾。
+  - Linux：`avahi-browse -rtp <服务类型>`（`-t` 扫完即退出）。
+  - 常用服务类型：`_home-assistant._tcp`、`_hap._tcp`（HomeKit）、`_miio._udp`（米家局域网）、`_smb._tcp`、`_afpovertcp._tcp`、
+    `_webdav._tcp`、`_ipp._tcp` / `_ipps._tcp`（打印机）、`_airplay._tcp`、`_raop._tcp`、`_googlecast._tcp`、`_http._tcp`。
+- **SSDP / UPnP**：向 `239.255.255.250:1900` 发 `M-SEARCH`（`ST: ssdp:all`，`MX: 2`），读回应里的 `LOCATION` 描述文档，识别 DLNA 渲染器、NAS、路由器。
+  可用 `python3` 标准库几行实现，等待不超过 3 秒。
+- **ARP / 端口探测（克制）**：只在上面两步没发现、且用户明确要找某台设备时才做。只看 `arp -a` 已知邻居；
+  端口只探测本网段、少量已知端口（如 8123、445、631、5000/5001），不做全端口扫描。
+
+把结果整理成一张简短清单给用户：名称、类型、地址、建议接法。然后问用户要接哪一台（或按用户原话直接进入对应接法）。
+
+## 2. 按设备类型接入
+
+### Home Assistant
+- **Cteno Station 自带 HA**：若 `/var/lib/cteno/home-assistant/agent-token` 存在，说明在 Station 上，HA 在 `http://127.0.0.1:8123`，
+  令牌已由首次开机脚本生成，不用找用户要。请求头写 `Authorization: Bearer $(cat /var/lib/cteno/home-assistant/agent-token)`，不要打印令牌。
+  已预装小米官方 `xiaomi_home`（账号登录后网关子设备也会列出）、涂鸦 `tuya`、`homekit_controller`、`matter`。
+  HA 自动发现的设备用 WebSocket `config_entries/flow/progress` 查看，再用 `/api/config/config_entries/flow` 走配对流程；接入前照铁律 3 确认。
+- 发现：`_home-assistant._tcp`（TXT 里有 `base_url` / `internal_url`、`version`），默认端口 8123。
+- 凭据：长期访问令牌（HA 个人资料页 →「长期访问令牌」创建）。`request_secret` 取，name 如 `home/home-assistant/token`。
+- 顺序：① `confirm_action`（device）→ ② `request_secret` 取令牌 → ③ `GET /api/` 验证 → ④ 写 memory → ⑤ 回复。不能跳过或调换 ①。
+- 接口：REST `GET <base>/api/`（验证令牌，返回 `{"message": "API running."}`）、`GET <base>/api/states`、
+  `POST <base>/api/services/<domain>/<service>`；实时事件用 WebSocket `<base>/api/websocket`。
+  请求头 `Authorization: Bearer secret://vault/<name>`（runtime 会替换成真实值并从输出中擦除）。
+- 门锁（`lock.*`）、报警（`alarm_control_panel.*`）、摄像头（`camera.*`）、燃气阀（`valve.*` 中的燃气）服务调用前，按铁律 4 每次确认。
+
+### 米家（小米）
+- 首选：小米官方开源的 **ha_xiaomi_home** 路线：用户在小米账号 OAuth 页登录授权，拿到的令牌存 vault；
+  之后经 MIoT 云 HTTP 接口查询和控制设备（人不在家也能用）。如果用户已有 Home Assistant，建议直接在 HA 里装这个集成，再按 HA 接法控制。
+- 备选：**python-miio** 局域网直连（`_miio._udp` 发现，端口 54321）。需要先拿到每台设备的 token（从米家账号导出），
+  token 用 `request_secret` 存 vault，每台设备一个 name。
+- OAuth 登录页由用户本人完成；不要索要小米账号密码。
+
+### NAS
+- SMB：`_smb._tcp`（445）。macOS 可 `smbutil view //<user>@<host>` 列共享；挂载用 `mount_smbfs`，查空间用 `df -h <挂载点>`。
+- WebDAV：`_webdav._tcp`，用 `PROPFIND`（`quota-available-bytes` / `quota-used-bytes`）查空间。
+- 密码用 `request_secret`；只读操作优先，删除/覆盖文件另按 `confirm_action`（irreversible）确认。
+
+### 打印机
+- IPP：`_ipp._tcp` / `_ipps._tcp`（631）。`ipptool -tv ipp://<host>/ipp/print get-printer-attributes.test` 查状态与耗材；
+  macOS 也可 `lpstat -p`。
+
+### 电视和音箱
+- AirPlay（`_airplay._tcp` / `_raop._tcp`）、Google Cast（`_googlecast._tcp`）、DLNA（SSDP `urn:schemas-upnp-org:device:MediaRenderer:1`）。
+  可用 `pyatv`、`pychromecast`、UPnP AVTransport SOAP 控制播放/音量。
+
+## 3. 接入完成后
+
+固定三步，按顺序，一步都不能少：
+
+1. 做一次只读验证（例如 HA `GET /api/` 返回 `API running.`，NAS 能列出共享）。
+2. **必须调用** `memory`（`action: "save"`，`file_path: "knowledge/home-devices.md"`，`type: "reference"`）——在第 3 步之前。示例条目：
+   `- 客厅 Home Assistant — 类型 home-assistant — http://192.168.1.10:8123 — REST+长期令牌（vault: home/home-assistant/token）`
+3. memory 返回后，才用一句人话告诉用户接入结果。
+
+以后用户说「把客厅灯关了」「NAS 还剩多少」，先 `memory(recall)` 查已接入设备，再按上面的接法执行。
+
+## 验证状态
+
+- Home Assistant REST、SMB 发现：有本地假服务 E2E（`scripts/e2e/home-devices/e2e.mjs`）。
+- 米家 OAuth / MIoT 云、python-miio 直连：**未用真实账号验证**，仅流程说明。