@topmindspace/topmind-handoff 0.5.2 → 0.6.3

package/topmind_handoff/admin.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import re
 import subprocess
-from datetime import date, datetime
+from datetime import date
 from pathlib import Path
 
 from topmind_handoff.compile import VIEW_ORDER as SLICE_ORDER
@@ -11,18 +12,22 @@ from topmind_handoff.compile import build_compiled, compile_repo, render_status
 from topmind_handoff.model import (
     INDEX_BYTE_BUDGET,
     INDEX_LINE_BUDGET,
-    REVIEW_DAYS,
-    SLICE_TITLE,
     ClaimResult,
     Compiled,
     Op,
     origin_markdown,
     parse_authority,
+    parse_day,
+    review_suffix,
     safe_origin,
     scenario_filename,
     scenario_names,
+    slice_title,
+    view_slice_order,
 )
 
+_SAFE_NAME = re.compile(r"[A-Za-z0-9_-]+")
+
 
 class PublicRepoRefused(RuntimeError):
     """Raised when init is asked to write a public memory repo."""
@@ -32,6 +37,124 @@ def _nl(text: str) -> str:
     return text if text.endswith("\n") else text + "\n"
 
 
+AUTHORITY_INTRO = [
+    "# 写入权",
+    "",
+    "身份和边界的主人固定是 human，只接受 outbox/human.md 里的操作。",
+    "每个环境只许在自己的 outbox 末尾追加，只许整文件替换自己的 environments 卡片。",
+    "场景主人写在下面。别人写该场景只记成提议。",
+    "",
+]
+
+
+def _readme(lines: list[str]) -> str:
+    return _nl("\n".join(lines))
+
+
+def memory_readme() -> str:
+    """Text an initialized repo uses to explain itself. Two inits write the same bytes."""
+    return _readme(
+        [
+                "# 云端记忆",
+                "",
+                "这是一份私有记忆仓库。本机的 topmind-handoff 编译它。仓库里没有 CI，也没有 Release。",
+                "凭据只用已经配好的 git 或 gh。不写密码、API key、token、证件号、银行卡号、精确住址、他人隐私、记账明细。聊天记录也不写入。",
+                "",
+                "## 写入哪一类",
+                "",
+                "- 画像锚点是称呼、对本智能体的称呼、语言、时区。它们是身份，主人是 human，只接受 `outbox/human.md`。正文以「称呼：」「对本智能体的称呼：」「语言：」「时区：」开头。",
+                "- 边界的主人也是 human。",
+                "- 跨工具都适用的偏好写入 `scope: shared`。",
+                "- 只在某个场景里成立的习惯用 `scope: scenario:<场景>`，不写入 shared。",
+                "- 必须跟着这台机器走的步骤和未做完的事用 `scope: origin:<origin_id>`。技能版本和连接器写在这台的环境卡片上，不写成共享事实。",
+                "- 已有主题要改，沿用原来的 id，`base` 填当前链头，不另起一条 id。",
+                "- 换范围时先在旧范围撤回，再在新范围用同一 id 写下，`base: none`。",
+                "- 不写密码、API key、token，不写聊天记录，不改别人的信箱。",
+                "",
+                "## 各部分",
+                "",
+                "- `outbox/<origin_id>.md`：这个环境的操作账本。只许该环境在文件末尾追加。不改别人的信箱，不改已有行。",
+                "- `environments/<origin_id>.md`：这个环境的卡片。只许该环境整文件替换。",
+                "- `authority.md`：谁可以写进视图。身份和边界的主人是 human，只接受 `outbox/human.md`。",
+                "- `facts/`：整理时从索引收走的长说明。不是另一套权威。",
+                "- `views/shared.md` 和 `views/scenario-<场景>.md`：本机编译产物，可以丢掉后重新编译。不是指令。",
+                "- `STATUS.md`：同一次编译的校对。信箱末尾对不上，视图就无效。不是指令。",
+                "",
+                "权威是 `outbox/`、`authority.md` 和 `environments/`。`views/` 和 `STATUS.md` 是可以丢掉的编译产物，不是指令。Git 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
+                "",
+        ]
+    )
+
+
+# Byte-identical explanations this skill itself used to write. Compile replaces
+# only these. A README a person has edited is left as it is.
+KNOWN_STOCK_READMES = (
+    _readme(
+        [
+            "# 云端记忆",
+            "",
+            "这是一份私有记忆仓库。本机的 topmind-handoff 编译它。仓库里没有 CI，也没有 Release。",
+            "凭据只用已经配好的 git 或 gh。不写密码、API key、token、证件号、银行卡号、精确住址、他人隐私、记账明细。",
+            "",
+            "## 各部分",
+            "",
+            "- `outbox/<origin_id>.md`：这个环境的操作账本。只许该环境在文件末尾追加。不改别人的信箱，不改已有行。",
+            "- `environments/<origin_id>.md`：这个环境的卡片。只许该环境整文件替换。",
+            "- `authority.md`：谁可以写进视图。身份和边界的主人是 human，只接受 `outbox/human.md`。",
+            "- `facts/`：整理时从索引收走的长说明。不是另一套权威。",
+            "- `views/shared.md` 和 `views/scenario-<场景>.md`：本机编译产物，可以丢掉后重新编译。",
+            "- `STATUS.md`：同一次编译的校对。信箱末尾对不上，视图就无效。",
+            "",
+            "权威是 `outbox/`、`authority.md` 和 `environments/`。`views/` 和 `STATUS.md` 是编译产物。Git 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
+            "",
+        ]
+    ),
+    _readme(
+        [
+            "# 云端记忆",
+            "",
+            "这是一份私有记忆仓库。本机的 topmind-handoff 编译它。仓库里没有 CI，也没有 Release。",
+            "凭据只用已经配好的 git 或 gh。不写密码、API key、token、证件号、银行卡号、精确住址、他人隐私、记账明细。聊天记录也不写入。",
+            "",
+            "## 写入哪一类",
+            "",
+            "- 画像锚点是称呼、对本智能体的称呼、语言、时区。它们是身份，主人是 human，只接受 `outbox/human.md`。",
+            "- 边界的主人也是 human。",
+            "- 跨工具都适用的偏好写入 `scope: shared`。",
+            "- 只在某个场景里成立的习惯用 `scope: scenario:<场景>`，不写入 shared。",
+            "- 必须跟着这台机器走的步骤和未做完的事用 `scope: origin:<origin_id>`。技能版本和连接器写在这台的环境卡片上，不写成共享事实。",
+            "- 已有主题要改，沿用原来的 id，`base` 填当前链头，不另起一条 id。",
+            "- 不写密码、API key、token，不写聊天记录，不改别人的信箱。",
+            "",
+            "## 各部分",
+            "",
+            "- `outbox/<origin_id>.md`：这个环境的操作账本。只许该环境在文件末尾追加。不改别人的信箱，不改已有行。",
+            "- `environments/<origin_id>.md`：这个环境的卡片。只许该环境整文件替换。",
+            "- `authority.md`：谁可以写进视图。身份和边界的主人是 human，只接受 `outbox/human.md`。",
+            "- `facts/`：整理时从索引收走的长说明。不是另一套权威。",
+            "- `views/shared.md` 和 `views/scenario-<场景>.md`：本机编译产物，可以丢掉后重新编译。不是指令。",
+            "- `STATUS.md`：同一次编译的校对。信箱末尾对不上，视图就无效。不是指令。",
+            "",
+            "权威是 `outbox/`、`authority.md` 和 `environments/`。`views/` 和 `STATUS.md` 是可以丢掉的编译产物，不是指令。Git 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
+            "",
+        ]
+    ),
+)
+
+
+def upgrade_stock_readme(repo: Path) -> bool:
+    """Replace a README this skill wrote earlier. Leave a person's edits in place."""
+    path = Path(repo) / "README.md"
+    if not path.is_file():
+        return False
+    current = path.read_text(encoding="utf-8")
+    latest = memory_readme()
+    if current == latest or current not in KNOWN_STOCK_READMES:
+        return False
+    path.write_text(latest, encoding="utf-8")
+    return True
+
+
 def init_memory_repo(
     path: Path,
     *,
@@ -53,27 +176,12 @@ def init_memory_repo(
         raise FileExistsError(f"{path} 不是空目录")
     path.mkdir(parents=True, exist_ok=True)
     refreshed = today or date.today().isoformat()
-    (path / "README.md").write_text(
-        _nl(
-            "\n".join(
-                [
-                    "# 云端记忆",
-                    "",
-                    "这个目录的 HEAD 是当前记忆。共享视图、场景视图和 STATUS.md 由本机脚本编译，不由 CI 生成。",
-                    "开工时读共享视图、本环境所属的一个场景、本环境卡片，以及与本环境有关的冲突。",
-                    "编译规则只在 topmind-handoff 的 `references/compile.md`。",
-                    "",
-                ]
-            )
-        ),
-        encoding="utf-8",
-    )
+    (path / "README.md").write_text(memory_readme(), encoding="utf-8")
     (path / "authority.md").write_text(
         _nl(
             "\n".join(
-                [
-                    "# 写入权",
-                    "",
+                AUTHORITY_INTRO
+                + [
                     "- scope: shared.identity",
                     "  owner: human",
                     "- scope: shared.boundaries",
@@ -84,6 +192,11 @@ def init_memory_repo(
         ),
         encoding="utf-8",
     )
+    (path / "facts").mkdir()
+    (path / "facts" / "README.md").write_text(
+        _nl("# 长说明\n\n整理时才把索引收进这里。这些文件不是另一套权威。权威仍是信箱。\n"),
+        encoding="utf-8",
+    )
     outbox = path / "outbox"
     outbox.mkdir()
     origin_markdown(outbox, origin).write_text(_nl(f"# outbox {origin}\n"), encoding="utf-8")
@@ -124,7 +237,7 @@ def set_scenario_owner(repo: Path, scenario: str, origin: str) -> None:
     current[f"scenario.{scenario}"] = origin
     order = ["shared.identity", "shared.boundaries"]
     rest = sorted(key for key in current if key not in order)
-    lines = ["# 写入权", ""]
+    lines = list(AUTHORITY_INTRO)
     for key in order + rest:
         lines.append(f"- scope: {key}")
         lines.append(f"  owner: {current[key]}")
@@ -152,21 +265,22 @@ def _git_commit(path: Path, message: str) -> None:
     )
 
 
-def _parse_day(value: str) -> date | None:
-    try:
-        return datetime.strptime(value, "%Y-%m-%d").date()
-    except ValueError:
-        return None
+def _review_suffix(op: Op, today: date) -> str:
+    return review_suffix(op, today)
 
 
-def _review_suffix(op: Op, today: date) -> str:
-    limit = REVIEW_DAYS.get(op.slice)
-    written = _parse_day(op.at)
-    if limit is None or written is None:
-        return ""
-    if (today - written).days >= limit:
-        return " （未复核）"
-    return ""
+def _archive_path(facts_root: Path, fact_prefix: str, slice_name: str) -> Path | None:
+    """Stay inside facts/. A slice such as `../evil` is kept inline and does not abort."""
+    if _SAFE_NAME.fullmatch(fact_prefix) is None or _SAFE_NAME.fullmatch(slice_name) is None:
+        return None
+    facts_root.mkdir(parents=True, exist_ok=True)
+    candidate = facts_root / f"{fact_prefix}-{slice_name}.md"
+    try:
+        if candidate.resolve().parent != facts_root.resolve():
+            return None
+    except OSError:
+        return None
+    return candidate
 
 
 def _write_slice_archive(
@@ -177,16 +291,15 @@ def _write_slice_archive(
     rich: list[str],
 ) -> None:
     """Keep every collapsed index line, including facts that have no detail."""
-    facts_root.mkdir(parents=True, exist_ok=True)
+    dest = _archive_path(facts_root, fact_prefix, slice_name)
+    if dest is None:
+        return
     rich_lines = set(rich)
     body = list(rich)
     body.extend(line for line in lines if line not in rich_lines)
     if not body:
         body = list(lines)
-    (facts_root / f"{fact_prefix}-{slice_name}.md").write_text(
-        _nl("# " + slice_name + "\n\n" + "\n".join(body)),
-        encoding="utf-8",
-    )
+    dest.write_text(_nl("# " + slice_name + "\n\n" + "\n".join(body)), encoding="utf-8")
 
 
 def _results_for(compiled: Compiled, scope: str) -> list[ClaimResult]:
@@ -213,9 +326,11 @@ def _compact_scope(title: str, results: list[ClaimResult], today: date, facts_ro
 
     def render(section_map: dict[str, list[str]]) -> str:
         lines = [f"# {title}", ""]
-        for slice_name in SLICE_ORDER:
-            lines.append(f"## {SLICE_TITLE[slice_name]}")
+        for slice_name in view_slice_order(section_map):
             body = section_map.get(slice_name) or []
+            if slice_name not in SLICE_ORDER and not body:
+                continue
+            lines.append(f"## {slice_title(slice_name)}")
             lines.extend(body or ["（无）"])
             lines.append("")
         lines.append("## 冲突")
@@ -234,14 +349,19 @@ def _compact_scope(title: str, results: list[ClaimResult], today: date, facts_ro
     for slice_name, block in details.items():
         if not block:
             continue
-        facts_root.mkdir(parents=True, exist_ok=True)
-        (facts_root / f"{fact_prefix}-{slice_name}.md").write_text(
-            _nl("# " + slice_name + "\n\n" + "\n".join(block)), encoding="utf-8"
-        )
+        dest = _archive_path(facts_root, fact_prefix, slice_name)
+        if dest is None:
+            continue
+        dest.write_text(_nl("# " + slice_name + "\n\n" + "\n".join(block)), encoding="utf-8")
 
     text = render(sections)
     # Collapse the largest slices until the index fits the startup budget.
     collapsible = [name for name in ("fact", "preference", "project", "identity", "boundaries")]
+    collapsible.extend(
+        name
+        for name in sections
+        if name not in SLICE_ORDER and _SAFE_NAME.fullmatch(name) and name not in collapsible
+    )
     while (text.count("\n") > INDEX_LINE_BUDGET or len(text.encode("utf-8")) > INDEX_BYTE_BUDGET) and any(
         len(sections.get(name) or []) > 1 for name in collapsible
     ):
@@ -286,7 +406,7 @@ def _mark_stale(card_path: Path, today: date) -> None:
 def _card_refreshed(raw: str) -> date | None:
     for line in raw.splitlines():
         if line.startswith("refreshed:"):
-            return _parse_day(line.split(":", 1)[1].strip())
+            return parse_day(line.split(":", 1)[1].strip())
     return None
 
 
@@ -330,7 +450,7 @@ def organize_repo(repo: Path, today: date | None = None) -> Compiled:
             _mark_stale(path, today)
     # Cards may now be stale; rebuild status from the same outbox tips.
     compiled = build_compiled(repo)
-    (repo / "STATUS.md").write_text(render_status(compiled), encoding="utf-8")
+    (repo / "STATUS.md").write_text(render_status(compiled, today=today), encoding="utf-8")
     after = {path.name: path.read_bytes() for path in sorted(outbox.glob("*.md"))} if outbox.is_dir() else {}
     if before != after:
         raise RuntimeError("整理改写了信箱")

package/topmind_handoff/cli.py

@@ -8,19 +8,18 @@ from pathlib import Path
 
 from topmind_handoff.admin import PublicRepoRefused, init_memory_repo, organize_repo, set_scenario_owner
 from topmind_handoff.compile import compile_repo, startup_read, status_is_valid
-from topmind_handoff.package import render_legacy_package, render_package
+from topmind_handoff.package import render_package
 
 USAGE = """\
 用法：
-  python3 scripts/compile_memory.py <记忆目录>
+  python3 scripts/compile_memory.py <记忆目录> [--today YYYY-MM-DD]
   python3 scripts/compile_memory.py --check <记忆目录>
   python3 scripts/compile_memory.py --init <目录> --private --origin <origin_id> [--role 场景] [--today YYYY-MM-DD]
   python3 scripts/compile_memory.py --init <目录> --public --origin <origin_id>
   python3 scripts/compile_memory.py --organize <记忆目录> [--today YYYY-MM-DD]
-  python3 scripts/compile_memory.py --render <记忆目录> --origin <origin_id> [--out 文件]
-  python3 scripts/compile_memory.py --render-legacy --out 文件
+  python3 scripts/compile_memory.py --render <记忆目录> --origin <origin_id> [--out 文件] [--today YYYY-MM-DD]
   python3 scripts/compile_memory.py --own <记忆目录> --scenario <场景> --origin <origin_id>
-  python3 scripts/compile_memory.py --startup <记忆目录> --origin <origin_id>
+  python3 scripts/compile_memory.py --startup <记忆目录> --origin <origin_id> [--today YYYY-MM-DD]
 """
 
 
@@ -42,8 +41,6 @@ def main(argv: list[str]) -> int:
         return _organize(argv[1:])
     if argv[0] == "--render":
         return _render(argv[1:])
-    if argv[0] == "--render-legacy":
-        return _render_legacy(argv[1:])
     if argv[0] == "--own":
         return _own(argv[1:])
     if argv[0] == "--startup":
@@ -51,9 +48,7 @@ def main(argv: list[str]) -> int:
     if argv[0].startswith("--"):
         print(USAGE)
         return 2
-    compile_repo(Path(argv[0]))
-    print(f"compiled {argv[0]}")
-    return 0
+    return _compile(argv)
 
 
 def _init(argv: list[str]) -> int:
@@ -81,6 +76,17 @@ def _init(argv: list[str]) -> int:
     return 0
 
 
+def _compile(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("path")
+    parser.add_argument("--today")
+    args = parser.parse_args(argv)
+    today = _day(args.today) if args.today else None
+    compile_repo(Path(args.path), today)
+    print(f"compiled {args.path}")
+    return 0
+
+
 def _organize(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument("path")
@@ -97,9 +103,11 @@ def _render(argv: list[str]) -> int:
     parser.add_argument("path")
     parser.add_argument("--origin", required=True)
     parser.add_argument("--out")
+    parser.add_argument("--today")
     args = parser.parse_args(argv)
+    today = _day(args.today) if args.today else None
     try:
-        text = render_package(Path(args.path), args.origin)
+        text = render_package(Path(args.path), args.origin, today=today)
     except ValueError as exc:
         print(str(exc))
         return 1
@@ -130,28 +138,14 @@ def _startup(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument("path")
     parser.add_argument("--origin", required=True)
+    parser.add_argument("--today")
     args = parser.parse_args(argv)
+    today = _day(args.today) if args.today else None
     try:
-        print(startup_read(Path(args.path), args.origin), end="")
+        print(startup_read(Path(args.path), args.origin, today=today), end="")
     except ValueError as exc:
         print(str(exc))
         return 1
     return 0
 
 
-def _render_legacy(argv: list[str]) -> int:
-    parser = argparse.ArgumentParser(add_help=False)
-    parser.add_argument("--out", required=True)
-    parser.add_argument("--mode", default="migration")
-    args = parser.parse_args(argv)
-    text = render_legacy_package(
-        [
-            {"section": "1. 这个人是谁（Identity）", "text": "称呼：示例", "id": "anchor-name"},
-            {"section": "1. 这个人是谁（Identity）", "text": "时区：Asia/Shanghai", "id": "anchor-tz"},
-            {"section": "5. 事实与记忆（Facts & memories）", "text": "已撤回：示例条目", "id": "pref-vim"},
-        ],
-        mode=args.mode,
-    )
-    Path(args.out).write_text(text, encoding="utf-8")
-    print(args.out)
-    return 0