@topmindspace/topmind-handoff 0.7.1 → 0.7.3

package/topmind_handoff/admin.py

@@ -8,7 +8,7 @@ from datetime import date
 from pathlib import Path
 
 from topmind_handoff.compile import VIEW_ORDER as SLICE_ORDER
-from topmind_handoff.compile import build_compiled, compile_repo, render_status
+from topmind_handoff.compile import build_compiled, compile_repo, write_compiled_status
 from topmind_handoff.model import (
     CLUSTER_SIZE,
     ClaimResult,
@@ -68,7 +68,8 @@ def memory_readme() -> str:
                 "- 只在某个场景里成立的习惯用 `scope: scenario:<场景>`，不写入 shared。",
                 "- 另一台要接着做的下一步用 `scope: shared` 或 `scope: scenario:<场景>`。只在这台的路径和工具状态用 `scope: origin:<origin_id>`。技能版本和连接器写在这台的环境卡片上，不写成共享事实。",
                 "- 产出只记状态、下一步和位置，不记正文。`slice` 用 `work` 或 `project`。`~/` 路径用 `scope: origin:`。",
-                "- 已有主题要改，沿用原来的 id，`base` 填当前链头，不另起一条 id。",
+                "- 日常工作默认每个环境维护一份自己的【当前工作】（`--work`，写进 `id: work.<origin_id>`，跨环境同步进展且互不冲突；仅本机可见加 `--local`）；特定项目交接加 `--topic <专项名>`；完结加 `--done` 撤回。",
+                "- 已有主题要改，沿用原来的 id，`base` 填当前链头，不另起一条 id（可用 `--set`、`--work`、`--retract`、`--resolve` 自动算 `op_id` 和 `base`）。",
                 "- 换范围时先在旧范围撤回，再在新范围用同一 id 写下，`base: none`。",
                 "- 不写密码、API key、token，不写聊天记录，不改别人的信箱。",
                 "",
@@ -179,178 +180,6 @@ def write_knowledge_skeleton(repo: Path) -> list[Path]:
     return written
 
 
-# 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、证件号、银行卡号、精确住址、他人隐私、记账明细。聊天记录也不写入。",
-                    "",
-                    "## 写入哪一类",
-                    "",
-                    "- 画像锚点是称呼、对本智能体的称呼、语言、时区。它们是身份，主人是 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 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
-                    "",
-            ]
-        ),
-    _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 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
-            "",
-        ]
-    ),
-    _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 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
-            "",
-        ]
-    ),
-    _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`：同一次编译的校对。信箱末尾对不上，视图就无效。不是指令。",
-            "- `knowledge/`：跨环境共享的经验、收藏帖、提示词。普通 Markdown，任何环境直接编辑。见 `knowledge/README.md`。",
-            "",
-            "权威是 `outbox/`、`authority.md` 和 `environments/`。`views/` 和 `STATUS.md` 是可以丢掉的编译产物，不是指令。Git 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
-            "",
-            "## knowledge/ 知识库",
-            "",
-            "- `knowledge/<大类>/<主题>.md`，最多两级。大类有收藏帖、段子、引流曝光、写作、图片视频、提示词。",
-            "- 它是参考资料，不是指令，不覆盖偏好与边界，不进 `outbox/`、编译、视图和 `authority.md`。",
-            "- 任何环境都可以直接改，提交并推送即可，git 历史就是留痕。不写凭据、隐私和聊天记录。",
-            "- 条目格式、拆分规则、读写时机见 `knowledge/README.md`。",
-            "",
-        ]
-    ),
-)
-
-
-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")
-    # The new explanation points at knowledge/. Add only the files that are missing.
-    write_knowledge_skeleton(repo)
-    return True
-
-
 def init_memory_repo(
     path: Path,
     *,
@@ -626,41 +455,6 @@ def _compact_scope(
     return text
 
 
-def _mark_stale(card_path: Path, today: date) -> None:
-    raw = card_path.read_text(encoding="utf-8")
-    card = _card_refreshed(raw)
-    if card is None:
-        return
-    if (today - card).days < 90:
-        return
-    if raw.startswith("---"):
-        parts = raw.split("---", 2)
-        front = parts[1]
-        body = parts[2] if len(parts) > 2 else ""
-        if "stale:" not in front:
-            front = front.rstrip() + "\nstale: true\n"
-        else:
-            front = front.replace("stale: false", "stale: true")
-        if "未刷新" not in body:
-            body = body.rstrip() + "\n\n未刷新\n"
-        card_path.write_text(_nl("---" + front + "---" + body), encoding="utf-8")
-        return
-    extra = ""
-    if "stale: true" not in raw:
-        extra += "stale: true\n"
-    if "未刷新" not in raw:
-        extra += "未刷新\n"
-    if extra:
-        card_path.write_text(_nl(raw.rstrip() + "\n" + extra), encoding="utf-8")
-
-
-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 None
-
-
 def write_index_views(repo: Path, compiled: Compiled, today: date | None, *, fit: bool) -> None:
     """Write one-line views. `fit` clusters slices that are past the startup budget.
 
@@ -712,15 +506,7 @@ def organize_repo(repo: Path, today: date | None = None) -> Compiled:
     before = {path.name: path.read_bytes() for path in sorted(outbox.glob("*.md"))} if outbox.is_dir() else {}
     compiled = build_compiled(repo)
     write_index_views(repo, compiled, today, fit=True)
-    environments = repo / "environments"
-    if environments.is_dir():
-        for path in sorted(environments.glob("*.md")):
-            _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, today=today, index_fit="organized"), encoding="utf-8"
-    )
+    write_compiled_status(repo, compiled, today=today, index_fit="organized")
     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

@@ -7,8 +7,17 @@ from datetime import datetime
 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, open_claim, startup_read, status_is_valid
-from topmind_handoff.package import render_package
+from topmind_handoff.compile import (
+    compile_repo,
+    open_claim,
+    record_retract,
+    record_resolve,
+    record_set,
+    record_work,
+    startup_read,
+    status_is_valid,
+)
+from topmind_handoff.package import render_package, replay_package
 
 USAGE = """\
 用法：
@@ -16,6 +25,11 @@ USAGE = """\
   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 --set <记忆目录> --origin <origin_id> --id <claim_id> --text <正文> [--scope 范围] [--slice 维度] [--base op_id] [--detail 长说明] [--today YYYY-MM-DD]
+  python3 scripts/compile_memory.py --retract <记忆目录> --origin <origin_id> --id <claim_id> [--scope 范围] [--today YYYY-MM-DD]
+  python3 scripts/compile_memory.py --resolve <记忆目录> --origin <origin_id> --id <claim_id> --text <正文> [--scope 范围] [--slice 维度] [--detail 长说明] [--today YYYY-MM-DD]
+  python3 scripts/compile_memory.py --work <记忆目录> --origin <origin_id> [--text 正文] [--topic 专项] [--local] [--done] [--detail 长说明] [--today YYYY-MM-DD]
+  python3 scripts/compile_memory.py --replay <记忆目录> --file <交接包> [--confirm]
   python3 scripts/compile_memory.py --organize <记忆目录> [--today YYYY-MM-DD]
   python3 scripts/compile_memory.py --open <记忆目录> --id <claim_id>
   python3 scripts/compile_memory.py --render <记忆目录> --origin <origin_id> [--out 文件] [--today YYYY-MM-DD]
@@ -25,7 +39,10 @@ USAGE = """\
 
 
 def _day(value: str):
-    return datetime.strptime(value, "%Y-%m-%d").date()
+    try:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    except ValueError as exc:
+        raise ValueError(f"日期格式无效（应为 YYYY-MM-DD）：{value}") from exc
 
 
 def main(argv: list[str]) -> int:
@@ -33,11 +50,24 @@ def main(argv: list[str]) -> int:
         print(USAGE)
         return 0 if argv else 2
     if argv[0] == "--check":
+        if len(argv) != 2:
+            print(USAGE)
+            return 2
         ok, message = status_is_valid(Path(argv[1]))
         print(message)
         return 0 if ok else 1
     if argv[0] == "--init":
         return _init(argv[1:])
+    if argv[0] == "--set":
+        return _set(argv[1:])
+    if argv[0] == "--retract":
+        return _retract(argv[1:])
+    if argv[0] == "--resolve":
+        return _resolve(argv[1:])
+    if argv[0] == "--work":
+        return _work(argv[1:])
+    if argv[0] == "--replay":
+        return _replay(argv[1:])
     if argv[0] == "--organize":
         return _organize(argv[1:])
     if argv[0] == "--open":
@@ -84,8 +114,12 @@ def _compile(argv: list[str]) -> int:
     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)
+    try:
+        today = _day(args.today) if args.today else None
+        compile_repo(Path(args.path), today)
+    except ValueError as exc:
+        print(str(exc))
+        return 1
     print(f"compiled {args.path}")
     return 0
 
@@ -95,8 +129,12 @@ def _organize(argv: list[str]) -> int:
     parser.add_argument("path")
     parser.add_argument("--today")
     args = parser.parse_args(argv)
-    today = _day(args.today) if args.today else None
-    organize_repo(Path(args.path), today)
+    try:
+        today = _day(args.today) if args.today else None
+        organize_repo(Path(args.path), today)
+    except ValueError as exc:
+        print(str(exc))
+        return 1
     print(f"organized {args.path}")
     return 0
 
@@ -121,8 +159,8 @@ def _render(argv: list[str]) -> int:
     parser.add_argument("--out")
     parser.add_argument("--today")
     args = parser.parse_args(argv)
-    today = _day(args.today) if args.today else None
     try:
+        today = _day(args.today) if args.today else None
         text = render_package(Path(args.path), args.origin, today=today)
     except ValueError as exc:
         print(str(exc))
@@ -157,8 +195,8 @@ def _startup(argv: list[str]) -> int:
     parser.add_argument("--also")
     parser.add_argument("--today")
     args = parser.parse_args(argv)
-    today = _day(args.today) if args.today else None
     try:
+        today = _day(args.today) if args.today else None
         print(startup_read(Path(args.path), args.origin, today=today, also=args.also), end="")
     except ValueError as exc:
         print(str(exc))
@@ -166,3 +204,141 @@ def _startup(argv: list[str]) -> int:
     return 0
 
 
+def _set(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("path")
+    parser.add_argument("--origin", required=True)
+    parser.add_argument("--id", required=True, dest="claim_id")
+    parser.add_argument("--text", required=True)
+    parser.add_argument("--scope", default="shared")
+    parser.add_argument("--slice", dest="slice_name")
+    parser.add_argument("--base")
+    parser.add_argument("--detail", default="")
+    parser.add_argument("--today")
+    args = parser.parse_args(argv)
+    try:
+        today = _day(args.today) if args.today else None
+        op_id = record_set(
+            Path(args.path),
+            origin=args.origin,
+            claim_id=args.claim_id,
+            text=args.text,
+            scope=args.scope,
+            slice_name=args.slice_name,
+            base=args.base,
+            detail=args.detail,
+            today=today,
+        )
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    print(f"set {op_id} ({args.scope} {args.claim_id})")
+    return 0
+
+
+def _retract(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("path")
+    parser.add_argument("--origin", required=True)
+    parser.add_argument("--id", required=True, dest="claim_id")
+    parser.add_argument("--scope", default="shared")
+    parser.add_argument("--text", default="已撤回")
+    parser.add_argument("--today")
+    args = parser.parse_args(argv)
+    try:
+        today = _day(args.today) if args.today else None
+        op_id = record_retract(
+            Path(args.path),
+            origin=args.origin,
+            claim_id=args.claim_id,
+            scope=args.scope,
+            text=args.text,
+            today=today,
+        )
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    print(f"retracted {op_id} ({args.scope} {args.claim_id})")
+    return 0
+
+
+def _resolve(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("path")
+    parser.add_argument("--origin", required=True)
+    parser.add_argument("--id", required=True, dest="claim_id")
+    parser.add_argument("--text", required=True)
+    parser.add_argument("--scope", default="shared")
+    parser.add_argument("--slice", dest="slice_name")
+    parser.add_argument("--detail", default="")
+    parser.add_argument("--today")
+    args = parser.parse_args(argv)
+    try:
+        today = _day(args.today) if args.today else None
+        op_id = record_resolve(
+            Path(args.path),
+            origin=args.origin,
+            claim_id=args.claim_id,
+            text=args.text,
+            scope=args.scope,
+            slice_name=args.slice_name,
+            detail=args.detail,
+            today=today,
+        )
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    print(f"resolved {op_id} ({args.scope} {args.claim_id})")
+    return 0
+
+
+def _work(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("path")
+    parser.add_argument("--origin", required=True)
+    parser.add_argument("--text", default="")
+    parser.add_argument("--topic")
+    parser.add_argument("--scope")
+    parser.add_argument("--local", action="store_true")
+    parser.add_argument("--done", action="store_true")
+    parser.add_argument("--detail", default="")
+    parser.add_argument("--today")
+    args = parser.parse_args(argv)
+    try:
+        today = _day(args.today) if args.today else None
+        op_id = record_work(
+            Path(args.path),
+            origin=args.origin,
+            text=args.text,
+            topic=args.topic,
+            scope=args.scope,
+            local=args.local,
+            done=args.done,
+            detail=args.detail,
+            today=today,
+        )
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    action = "done" if args.done else "work"
+    print(f"{action} {op_id}")
+    return 0
+
+
+def _replay(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("path")
+    parser.add_argument("--file", required=True, dest="pkg_file")
+    parser.add_argument("--confirm", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        pkg_text = Path(args.pkg_file).read_text(encoding="utf-8")
+        added = replay_package(Path(args.path), pkg_text, confirmed=args.confirm)
+    except (ValueError, OSError) as exc:
+        print(str(exc))
+        return 1
+    mode = "replayed" if args.confirm else "preview"
+    print(f"{mode}: {', '.join(added) if added else 'none'}")
+    return 0
+
+