@sakanano-moe/agenthelm 6.5.2 → 6.6.0

package/runtime/plugins/project-orchestrator/runtime/wf.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+"""wf：人用的文件查找入口，基于交付物台账（runtime/assets.py），无需 Agent。
+
+    wf                       交互模式
+    wf 笔记 9月1号             直接查（日期、同义词自动识别）
+    wf -o 笔记 9月1号          查到后直接打开最新一个
+    wf recent                最近改动的交付物
+    wf cases [词]            Case 列表（进行中在前）
+    wf refs <路径|序号> [层数]  谁引用它 / 它引用谁
+    wf o|f|c|p|v <序号>       打开 / 在文件管理器中显示 / 复制路径 / 打印路径 / 列出版本（序号指上一次结果）
+    wf check                 台账巡检摘要
+    wf rebuild               强制重建台账
+
+--project <目录> 与 --output json 可写在任意位置；缺省从当前目录向上查找 Project Profile。
+打开、显示与复制只在 macOS 上调用系统命令，其他平台打印绝对路径。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import unicodedata
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import assets  # noqa: E402
+from assets import AssetError, Project  # noqa: E402
+
+ACTIONS = {"o": "open", "f": "reveal", "c": "copy", "v": "versions", "r": "refs", "p": "path"}
+STATUS_LABEL = {"active": "进行中", "waiting": "等待", "done": "已完成", "captured": "待澄清",
+                "suspended": "挂起", "abandoned": "放弃"}
+
+
+# ---------------------------------------------------------------- display
+
+class Style:
+    def __init__(self) -> None:
+        self.on = sys.stdout.isatty() and "NO_COLOR" not in os.environ
+
+    def _wrap(self, code: str, text: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if self.on else text
+
+    def bold(self, text: str) -> str:
+        return self._wrap("1", text)
+
+    def dim(self, text: str) -> str:
+        return self._wrap("2", text)
+
+    def cyan(self, text: str) -> str:
+        return self._wrap("36", text)
+
+    def green(self, text: str) -> str:
+        return self._wrap("32", text)
+
+    def yellow(self, text: str) -> str:
+        return self._wrap("33", text)
+
+    def red(self, text: str) -> str:
+        return self._wrap("31", text)
+
+
+S = Style()
+
+
+def display_width(text: str) -> int:
+    return sum(2 if unicodedata.east_asian_width(character) in "WF" else 1 for character in text)
+
+
+def clip(text: str, width: int) -> str:
+    if display_width(text) <= width:
+        return text
+    out, used = "", 0
+    for character in text:
+        size = 2 if unicodedata.east_asian_width(character) in "WF" else 1
+        if used + size > width - 1:
+            break
+        out += character
+        used += size
+    return out + "…"
+
+
+def term_width() -> int:
+    return max(60, min(shutil.get_terminal_size((100, 24)).columns, 120))
+
+
+def status_text(item: dict) -> str:
+    status = item.get("status", "")
+    if not status:
+        return "project" if item.get("container_kind") == "project" else "-"
+    label = STATUS_LABEL.get(status, status)
+    return S.green(label) if status == "active" else S.yellow(label) if status == "waiting" else S.dim(label)
+
+
+def render_groups(groups: list[dict]) -> None:
+    width = term_width()
+    for index, item in enumerate(groups, 1):
+        label = item["title"] or item["name"]
+        date = (item["modified"] or "")[:10]
+        left = f" {S.bold(S.cyan(f'{index:>2}'))}  {S.bold(clip(label, width - 22))}"
+        visible = display_width(re.sub(r"\033\[[0-9;]*m", "", left))
+        print(left + " " * max(1, width - visible - len(date)) + S.dim(date))
+        owner = item["case_title"] or item["container"]
+        git = item["git"]
+        git_text = S.dim(git) if git.startswith(("tracked", "none")) else S.yellow(git)
+        print(f"     {item['name']} · {clip(owner, width - 50)} ({status_text(item)}) · {git_text}")
+        print(S.dim(f"     {clip(item['path'], width - 6)}"))
+        if item.get("versions"):
+            names = " · ".join(version["name"] for version in item["versions"][:4])
+            more = f" 等 {len(item['versions'])} 个" if len(item["versions"]) > 4 else ""
+            print(S.dim(f"     └ 同系列另有 {len(item['versions'])} 个：{clip(names, width - 30)}{more}"))
+
+
+# ---------------------------------------------------------------- last results
+
+def save_last(project: Project, groups: list[dict]) -> None:
+    """Remember the last result list (paths and versions) in the cache, never in the project."""
+    try:
+        path = project.state_dir(create=True) / assets.LAST_NAME
+        payload = [{"path": group["path"], "name": group["name"], "title": group["title"],
+                    "modified": group["modified"], "versions": group.get("versions", [])} for group in groups]
+        path.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+        os.chmod(path, 0o600)
+    except (OSError, AssetError):
+        pass
+
+
+def load_last(project: Project) -> list[dict]:
+    try:
+        data = json.loads((project.state_dir() / assets.LAST_NAME).read_text(encoding="utf-8"))
+    except (OSError, ValueError, AssetError):
+        return []
+    return [item for item in data if isinstance(item, dict) and isinstance(item.get("path"), str)] \
+        if isinstance(data, list) else []
+
+
+def resolve_target(token: str, last: list[dict]) -> dict | None:
+    if token.isdigit():
+        index = int(token) - 1
+        if 0 <= index < len(last):
+            return last[index]
+        print(S.red(f"没有第 {token} 项（上一次结果共 {len(last)} 项）"))
+        return None
+    return {"path": token, "name": Path(token).name, "title": "", "modified": "", "versions": []}
+
+
+# ---------------------------------------------------------------- actions
+
+def do_action(action: str, relative: str, project: Project, platform: str | None = None) -> str:
+    """Open / reveal / copy on macOS; elsewhere (or without the commands) print the absolute path."""
+    target = str(project.root / relative)
+    mac = (platform or sys.platform) == "darwin"
+    if action == "open" and mac and shutil.which("open"):
+        subprocess.run(["open", target], check=False)
+        print(S.green("已打开 ") + relative)
+    elif action == "reveal" and mac and shutil.which("open"):
+        subprocess.run(["open", "-R", target], check=False)
+        print(S.green("已在 Finder 中显示 ") + relative)
+    elif action == "copy" and mac and shutil.which("pbcopy"):
+        subprocess.run(["pbcopy"], input=target.encode("utf-8"), check=False)
+        print(S.green("已复制绝对路径 ") + target)
+    else:
+        print(target)
+        return "printed"
+    return action
+
+
+def show_versions(group: dict) -> None:
+    print(S.bold(group.get("title") or group.get("name", "")))
+    print(f"  {(group.get('modified') or '')[:16].replace('T', ' ')}  {group['path']}  {S.green('最新')}")
+    for version in group.get("versions", []):
+        print(f"  {(version.get('modified') or '')[:16].replace('T', ' ')}  {version['path']}  "
+              f"{S.dim(version.get('git', ''))}")
+
+
+def show_refs(project: Project, path: str, depth: int = 1) -> dict:
+    result = assets.refs(project, path, depth=depth)
+    print(S.bold(result["path"]))
+    if result["inbound"]:
+        print(S.cyan("  被引用："))
+        for item in result["inbound"][:25]:
+            via = "" if item["via"] == "file" else S.dim("（目录级）")
+            print(f"    ← {item['src']}{via}")
+    else:
+        print(S.dim("  没有被任何 Case 或扫描根里的文件引用"))
+    if result["outbound"]:
+        print(S.cyan("  引用了："))
+        for item in result["outbound"][:25]:
+            print(f"    → {item['dst']}")
+    if result["affected_containers"]:
+        print(S.yellow("  改动会波及：") + "、".join(result["affected_containers"][:8]))
+    return result
+
+
+def do_search(project: Project, terms: list[str], *, limit: int = 10, **filters: str) -> list[dict]:
+    if assets.status(project)["status"] != "fresh":
+        print(S.dim("（索引更新中…）"))
+    result = assets.find(project, terms, limit=limit, **filters)
+    query = result["query"]
+    description = " ".join(query["terms"]) or "全部"
+    if query["dates"]:
+        description += " · 日期 " + ",".join(date.replace("*-", "") for date in query["dates"])
+    print(S.dim(f"查找：{description}"))
+    if not result["results"]:
+        print(S.yellow("没有找到。") + S.dim("试试更短的词、去掉日期，或 `wf cases` 先看 Case 列表。"))
+        return []
+    render_groups(result["results"])
+    tail = f"共 {result['total']} 组"
+    if result["total"] > result["returned"]:
+        tail += f"，只显示前 {result['returned']} 组（加关键词收窄）"
+    print(S.dim(tail + "。序号可接 o 打开 / f 显示 / c 复制 / v 版本 / r 引用，例：o1"))
+    save_last(project, result["results"])
+    return result["results"]
+
+
+def do_cases(project: Project, term: str | None, limit: int = 30) -> dict:
+    result = assets.cases(project, term, limit=limit)
+    width = term_width()
+    for item in result["results"]:
+        status = STATUS_LABEL.get(item["status"], item["status"] or "-")
+        mark = S.green(f"{status:<4}") if item["status"] == "active" else S.dim(f"{status:<4}")
+        print(f" {mark} {S.bold(clip(item['title'] or item['id'], width - 52))}  {S.dim(clip(item['id'], 44))}  "
+              f"{S.dim(str(item['files']) + ' 个文件')}")
+    print(S.dim(f"共 {result['total']} 个 Case" + ("；用 `wf <Case 关键词>` 查其文件" if result["total"] else "")))
+    return result
+
+
+def do_recent(project: Project, limit: int) -> dict:
+    result = assets.recent(project, limit=limit)
+    render_groups(result["results"])
+    save_last(project, result["results"])
+    return result
+
+
+def do_check(project: Project) -> dict:
+    report = assets.check(project)
+    totals, tiers, counts = report["totals"], report["claim_tiers"], report["broken_counts"]
+    git = totals["git"]
+    print(S.bold("台账巡检"))
+    print(f"  文件 {totals['files']} · 引用 {totals['edges']} · Git 已入库 {git.get('tracked', 0)} / "
+          f"不入库 {git.get('ignored', 0)} / 新建未提交 {git.get('untracked', 0)} / 非 Git {git.get('none', 0)}")
+    print(f"  交付物：文件级被引用 {tiers.get('file', 0)} · 仅目录覆盖 {tiers.get('directory', 0)} · "
+          f"无人认领 {S.yellow(str(tiers.get('none', 0)))}")
+    print(f"  断链：真断链 {S.yellow(str(counts.get('real-broken', 0)))} · "
+          f"说明文字 {counts.get('prose-not-path', 0)} · 主题链接 {counts.get('wikilink-topic', 0)}")
+    for container, paths in list(report["unclaimed"].items())[:5]:
+        print(S.dim(f"  无人认领 · {container}: {paths[0]}"))
+    return report
+
+
+# ---------------------------------------------------------------- entry
+
+HELP = f"""{S.bold('用法')}
+  直接输入关键词查找；可带日期（9月1号 / 0901 / 2026-09-01），同义词按项目的 asset-synonyms.json 展开。
+  {S.cyan('o1')} 打开第 1 项   {S.cyan('f1')} 在文件管理器中显示   {S.cyan('c1')} 复制绝对路径   {S.cyan('p1')} 打印路径
+  {S.cyan('v1')} 查看全部版本   {S.cyan('r1')} 谁引用它（r1 2 为两层）   {S.cyan('1')} 直接打开
+  {S.cyan('recent')} 最近改动   {S.cyan('cases [词]')} Case 列表   {S.cyan('check')} 巡检   {S.cyan('q')} 退出
+  过滤：{S.cyan('ext:xlsx')}  {S.cyan('kind:deliverable')}（也可 draft/source/data）  {S.cyan('in:片段')}（限定 Case/目录）"""
+
+
+def parse_filters(tokens: list[str]) -> tuple[list[str], dict]:
+    terms, filters = [], {}
+    for token in tokens:
+        match = re.match(r"^(ext|kind|in):(.+)$", token)
+        if match:
+            filters[{"ext": "ext", "kind": "kind", "in": "container"}[match.group(1)]] = match.group(2)
+        else:
+            terms.append(token)
+    return terms, filters
+
+
+def split_globals(argv: list[str]) -> tuple[list[str], Path | None, str]:
+    """Pull ``--project`` and ``--output`` out of any position."""
+    rest, project, output = [], None, "text"
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        name, _, inline = token.partition("=")
+        if name in ("--project", "--output"):
+            if inline:
+                value = inline
+            elif index + 1 < len(argv):
+                index += 1
+                value = argv[index]
+            else:
+                raise AssetError(f"{name} 需要一个值")
+            if name == "--project":
+                project = Path(value)
+            elif value in ("text", "json"):
+                output = value
+            else:
+                raise AssetError("--output 只能是 text 或 json")
+        else:
+            rest.append(token)
+        index += 1
+    return rest, project, output
+
+
+def interactive(project: Project) -> int:
+    try:
+        import readline  # noqa: F401  line editing and history
+    except ImportError:
+        pass
+    current = assets.status(project)
+    if current["status"] != "fresh":
+        print(S.dim("（索引更新中…）"))
+        assets.rebuild(project)
+        current = assets.status(project)
+    print(S.bold(S.cyan("交付物台账")) + S.dim(f"  ·  {current.get('file_count', '?')} 个文件  ·  索引 "
+                                             f"{current.get('built_at', '')[11:16]}"))
+    print(S.dim("输入关键词查找；? 帮助；q 退出"))
+    groups: list[dict] = []
+    while True:
+        try:
+            line = input(S.bold(S.cyan("\n查找 › "))).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if not line:
+            continue
+        if line in ("q", "quit", "exit", "退出"):
+            return 0
+        if line in ("?", "help", "帮助"):
+            print(HELP)
+            continue
+        try:
+            match = re.match(r"^([ofcvrp])\s*(\d+)(?:\s+(\d+))?$", line) or re.match(r"^()(\d+)()$", line)
+            if match:
+                key, number, extra = match.group(1) or "o", match.group(2), match.group(3)
+                target = resolve_target(number, groups or load_last(project))
+                if target is None:
+                    continue
+                if key == "v":
+                    show_versions(target)
+                elif key == "r":
+                    show_refs(project, target["path"], depth=int(extra or 1))
+                else:
+                    do_action(ACTIONS[key], target["path"], project)
+                continue
+            if line in ("recent", "最近"):
+                groups = do_recent(project, 15)["results"]
+                continue
+            if line == "cases" or line.startswith("cases "):
+                do_cases(project, line.split(None, 1)[1] if " " in line else None)
+                continue
+            if line == "check":
+                do_check(project)
+                continue
+            terms, filters = parse_filters(line.split())
+            groups = do_search(project, terms, **filters)
+        except AssetError as exc:
+            print(S.red(f"出错：{exc}"))
+
+
+def command(project: Project, argv: list[str], output: str) -> tuple[int, dict | None]:
+    head = argv[0]
+
+    def number(position: int, default: int) -> int:
+        return int(argv[position]) if len(argv) > position and argv[position].isdigit() else default
+
+    if output == "json":
+        if head in ("recent", "最近"):
+            return 0, assets.recent(project, limit=number(1, 15))
+        if head in ("cases", "case"):
+            return 0, assets.cases(project, " ".join(argv[1:]) or None)
+        if head == "check":
+            return 0, assets.check(project)
+        if head == "rebuild":
+            return 0, assets.rebuild(project, force=True)
+        if head in ("refs", "r") and len(argv) > 1:
+            target = resolve_target(argv[1], load_last(project))
+            return (1, None) if target is None else (0, assets.refs(project, target["path"], depth=number(2, 1)))
+        terms, filters = parse_filters(argv[1:] if head in ("-o", "-f", "-c") else argv)
+        result = assets.find(project, terms, **filters)
+        save_last(project, result["results"])
+        return (0 if result["results"] else 1), result
+    if head in ("recent", "最近"):
+        do_recent(project, number(1, 15))
+        return 0, None
+    if head in ("cases", "case"):
+        do_cases(project, " ".join(argv[1:]) or None)
+        return 0, None
+    if head == "check":
+        do_check(project)
+        return 0, None
+    if head == "rebuild":
+        result = assets.rebuild(project, force=True)
+        print(f"{result['action']}：{result['file_count']} 个文件")
+        return 0, None
+    if (head in ACTIONS and len(argv) > 1 and (argv[1].isdigit() or head == "r")) or (head == "refs" and len(argv) > 1):
+        target = resolve_target(argv[1], load_last(project))
+        if target is None:
+            return 1, None
+        if head in ("r", "refs"):
+            show_refs(project, target["path"], depth=number(2, 1))
+        elif head == "v":
+            show_versions(target)
+        else:
+            do_action(ACTIONS[head], target["path"], project)
+        return 0, None
+    flags = {"-o": "open", "-f": "reveal", "-c": "copy"}
+    action = flags.get(head)
+    terms, filters = parse_filters(argv[1:] if action else argv)
+    groups = do_search(project, terms, **filters)
+    if action and groups:
+        do_action(action, groups[0]["path"], project)
+    return (0 if groups else 1), None
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    output = "text"
+    try:
+        argv, start, output = split_globals(argv)
+        if argv and argv[0] in ("-h", "--help", "help"):
+            print(__doc__)
+            return 0
+        project = Project.discover(start, explicit=start is not None)
+        if not argv:
+            if output == "json":
+                raise AssetError("交互模式不支持 --output json")
+            return interactive(project)
+        code, result = command(project, argv, output)
+        if output == "json":
+            print(json.dumps(result if result is not None else {"ok": False, "code": "not-found",
+                                                                  "error": "没有这一项"}, ensure_ascii=False, indent=2))
+        return code
+    except AssetError as exc:
+        if output == "json":
+            print(json.dumps({"ok": False, "code": exc.code, "error": str(exc)}, ensure_ascii=False))
+        else:
+            print(S.red(f"出错：{exc}"), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/plugins/project-orchestrator/skills/project-orchestrator/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: project-orchestrator
+description: 按项目契约统一执行会话发现、Task/Case 选择、能力路由、文件落位、验证、进度更新和限定范围的 Git 交付。当项目在 AGENTS.md 中声明 project-orchestrator，且当前工作可能创建或修改项目文件时使用。Agent 扩展（Plugin/Skill/MCP）的盘点、迁移与同步不在本 Skill 内——那是 agent-pack。
+---
+
+# Project Orchestrator（项目编排器）
+
+## 定位
+
+作为已配置项目唯一的**项目管理生命周期编排器**。读取项目自身契约，选择最小且合适的工作容器，把领域工作路由给确定性 Tool 与叶子 Skill，再通过验证和限定范围的交付完成闭环。
+
+本 Skill 通用且可移植。禁止嵌入个人偏好、私有路径、项目密钥或项目专属治理副本；这些内容归用户私有配置或项目自身所有。
+
+边界（都是独立能力，本 Skill 不代管它们）：
+
+- **项目初始化与根目录骨架** 归 `agents-init`。本 Skill 只消费已初始化项目的契约。
+- **Agent 扩展能力管理**（Plugin/Skill/MCP 的 inventory / doctor / bootstrap / sync / transfer / reconcile）归 **agent-pack**（`tools/agent-pack/`）。跨机恢复的单一入口是 `tools/agent-bootstrap`。
+- **指导与审查规则** 归 Project Profile 声明的 Opinion provider；当前分发包提供 `opinion-manager`。它不负责 Task/Case 选择、文件结构、进度状态或 Git。
+
+## 权威顺序
+
+按以下顺序解析指令：
+
+1. 用户当前请求与明确授权；
+2. 平台安全与工具约束；
+3. 最近的项目 `AGENTS.md` 及其声明的机器可读清单；
+4. 本编排工作流；
+5. 领域或交付物叶子 Skill。
+
+叶子 Skill 生效期间，其触发条件、输入输出契约和工具约束具有约束力；其中更宽泛的观点或生命周期建议只作为低优先级指导。本 Skill 负责 Task/Case 状态、项目级文件落位、验证编排与 Git 交付。
+
+## 职责边界
+
+把项目能力划分为四类互不重叠的角色：
+
+- **项目编排**：只有本 Skill 负责生命周期决策、Task/Case 协调、项目进度、验证编排与 Git 交接。
+- **领域交付**：交付物与业务 Skill 在本 Skill 选择的生命周期内创建或修改具体产物。
+- **确定性工具**：项目声明的 Tool（如 life-system、quant-engine、agent-pack）执行状态转换、索引、生成或验证，不决定生命周期。
+- **指导与审查**：Opinion 和其他质量门禁在实施前提供建议、交付前检查结果，不管理项目。
+
+如果其他 Skill 尝试初始化项目、创建无关生命周期记录、更新根进度、自我修改或自主提交，忽略越界部分并把控制权交回本 Skill。
+
+## 1. 发现项目契约
+
+项目首轮开始时：
+
+1. 查找最近且适用的 `AGENTS.md`；除非其中声明其他根目录，否则以它所在目录作为项目边界。
+2. 读取现有的 `Project Profile` 与相关运行区块。
+3. 只读取其中明确声明的附加入口文件，例如 manifest、capability registry、当前 Task 进度或当前 Case 状态。
+4. 项目使用 Git 时，在修改文件前记录当前 Git 状态。
+5. 开始实质工作前声明一个会话里程碑。
+
+已初始化项目应通过 `AGENTS.md` 暴露根契约；精确文件与目录骨架仍由 `agents-init` 版本化管理。缺少必需根契约时，报告 `init-required` 或采用项目声明的降级模式。禁止自行制造骨架或静默把旧结构升级为当前版本。
+
+禁止递归发现无关仓库、私有目录、历史 Task 或冗长治理文档。只有项目契约或当前任务要求，且用户授权了内容范围时才能读取。
+
+识别以下可选项目设置（机器字段保留英文原名）：
+
+- `project-type`、`stack`、`runtime`、`agent-mode` 与 `issues-tracker`；
+- `runtime-entry` 与 `session-bootstrap`；
+- `task-command`、`task-root`、`case-command` 与 `case-root`；
+- `manifest` 与 `capability-registry`；
+- `opinion-command`、`opinion-strict-mode` 与项目 Opinion 入口；
+- `commit-policy`、`branch-policy` 与 `push-policy`；
+- `memory` 声明的记忆提供方、目录、命令与参数文件；
+- 隐私目录、生成输出与禁止路径。
+
+`agent-pack` 读取的机器契约位于 `.agents/moe.sakanano.agent-pack/project.json`：其 `capabilities` 区块声明可移植 Plugin 根目录、外部 Plugin 目录、独立 Skill 根目录、可移植/原生 MCP 来源、客户端策略、本地凭据环境文件与导入目标。所有相对路径都必须限制在项目根目录内。本 Skill 不写该文件。
+
+缺少可选设置时关闭对应集成。禁止杜撰命令或路径。
+
+## 2. 分类当前请求
+
+先读取 Project Profile 的 `work.mode`。新项目默认 `case-workspace`；字段缺失或为 `legacy` 时保持项目现有 Task/Case 模式，禁止因升级 Skill 自动迁移其他项目。
+
+### Case 工作目录模式
+
+`work.mode=case-workspace` 时，Case 是唯一持久工作容器。需要保存交付物、证据或跨会话状态的工作使用 Case；无持久资产的单轮回答直接完成。子任务留在同一 Case 的工作项清单，确需独立过程记录时放入 `work-items/`，不得建立平行的顶层 Task 生命周期。
+
+Case 自有输入放 `refs/`，交付物放 `docs/`（草稿 `docs/drafts/`），数据放 `data/`，图片放 `images/`，专属脚本放 `scripts/`，过程记录放 `.agent-doc/`。只创建实际需要的子目录。`CASE.md` 保存目标、状态、下一动作、决策与完成证据，过程文件不得成为第二套状态权威。
+
+专属于 Case 的来源包、会议纪要、核验结果和报告保存在 Case 内。跨 Case 的版本化公共模板、项目运行时代码和长期项目主文档保留原权威位置，Case 记录来源、版本和本地证据；公共参考需有明确复用范围，禁止将单个 Case 的资料扔入共享目录。自有文件使用 Case 相对引用，外部权威引用注明项目根目录或外部来源。隐私区不因自包含要求而越界复制。
+
+项目没有声明自己的 Case 工具（Profile 无 `work.case.command`）时，用随包的 `runtime/case.py` 新建、更新与校验 Case，不手写 Frontmatter；用法见 [Case 工作目录工具](../../references/case-workspaces.md#默认-case-工具官方样例)。
+
+人不经过 Agent 时用项目入口 `runtime/project_cli.py`（项目根目录的启动器或 `agenthelm project`）找资料、看进展、检查与记录；Agent 需要同样的信息时调用它的子命令并加 `--output json`，例如 `project_cli.py --project <项目> progress --output json`，不另写一套查找逻辑。写入类子命令（`fix`、`record`、`tools --run`）默认只预览，执行前按本 Skill 的授权规则取得用户同意。项目在 Profile 的 `entry` 段声明自有事项工具与项目工具，约定见 [项目入口](../../references/case-workspaces.md#项目入口不需要-ai-agent)。
+
+检索和统计以所有 Case 为入口，通过标题、别名、旧 Task ID、标签、目标和文件名查找；正文只在候选确定后按需读取。查找具体文件、版本或引用影响面时先用随包的 `runtime/assets.py find` / `refs` / `check`（人用入口 `runtime/wf.py`），不靠记忆翻目录；见 [交付物台账](../../references/case-workspaces.md#交付物台账与-wf-查找官方样例)。恢复视图只展示未关闭状态，全量统计包括历史完成与放弃记录，禁止把迁移时间当作业务完成时间。
+
+已授权迁移历史 Task 时，先列出全部源目录与目标映射，再做代表性 Demo、哈希验证和批量迁移。独立 Task 转独立 Case，确有同一目标和证据链的 Task 才合入既有 Case；标题相似不能作为合并证据。保留原 TASK.md、progress、原文件和旧 ID；关闭原因包含放弃时保留真实历史状态。工具入口和限制见 [Case 工作目录工具](../../references/case-workspaces.md)。
+
+### 既有 Task/Case 模式
+
+写入前分类当前请求：
+
+- **回答或诊断**：检查并报告；除非用户要求，否则不创建生命周期记录或修改文件。
+- **小型项目改动**：可在单个会话完成且项目未强制要求 Task 时直接编辑。
+- **Task**：适用于边界明确，并需要工作目录、产物、决策或独立进度记录的交付。
+- **Case**：适用于跨会话服务线索、不确定性调研、外部等待、回访或结果跟踪。
+- **Task + Case**：只在长期 Case 协调具体 Task 工作区时使用。
+
+仅在既有模式下使用以上 Task/Case 分类。Case 工作目录模式统一续接 Case。依据目标、证据链和交付物判断，不能只看标题相似度。
+
+除非项目明确要求，否则寒暄、确认、简单问题、命令修正或一次性单文件编辑不创建 Task。禁止只为满足指标或流程而创建 Case。
+
+## 3. 初始化或恢复状态
+
+项目声明 bootstrap 命令时：
+
+1. 首次收到服务输入时运行一次只读状态命令。
+2. 只有状态明确报告 bootstrap 必需或已过期时才执行 bootstrap。
+3. 创建新工作前，用配置命令发现未完成工作。
+4. 只有当前任务授权覆盖私有 Case 或 Task 上下文时才能展开读取。
+
+已经位于 Task 目录时，先读取任务简报和本地进度，再读项目 backlog。已经位于 Case 上下文时，使用配置的下一步命令，禁止依靠记忆重建状态。
+
+Project Profile 声明了 `memory` 时，恢复状态后读取记忆索引：`provider` 为 `project-orchestrator` 时运行随包的 `runtime/memory.py index --project <项目>`，为 `project` 时运行其 `index_command`。索引每条一行，说明何时应当想起该条记忆；只在当前任务命中时读取条目正文。依据某条记忆行动前，核对其中提到的文件、命令与外部对象仍然存在；标注为可能过期的条目先核实再使用。
+
+## 4. 路由能力
+
+根据三项输入构建执行路由：
+
+1. 用户要求的结果；
+2. Project Profile 与当前 Task/Case 约束；
+3. 项目已声明的 capability registry。
+
+采用以下优先级：
+
+1. 用确定性项目 Tool 执行状态转换、索引、生成或验证；
+2. 用精确匹配的领域或交付物叶子 Skill 处理判断密集型工作；
+3. 只有没有已注册能力适用时才采用通用实现。
+
+一个交付物可以同时启用多个叶子 Skill。先应用最具体的交付物/领域 Skill，再执行无障碍、安全或 Opinion 等横切检查。两个 Skill 指令冲突时，在会改变交付物的最小决策点暂停并呈现冲突。
+
+禁止宣称缺失能力已经存在。使用项目定义的机制记录能力缺口，或直接报告。
+
+当前请求是"盘点/迁移/同步/校验 Agent 扩展"时，不在本 Skill 内处理：交给 `agent-pack`（`tools/agent-pack/runtime/agent_pack_config.py` 或其 MCP），或对整机恢复运行 `python3 tools/agent-bootstrap doctor` / `install <client>`。本 Skill 只负责把这类请求识别并路由过去。
+
+## 5. 计划与执行
+
+计划复杂度与工作量保持匹配：
+
+- 小型可逆改动使用简短内部计划；
+- Case 工作目录模式统一更新 CASE.md，子工作项仅保存过程；
+- 既有模式中的多步骤交付物工作更新 Task 进度，跨会话连续工作或回访更新 Case 状态。
+
+编辑前：
+
+1. 检查相关现有文件和邻近测试；
+2. 在 dirty worktree 中保留用户的无关改动；
+3. 识别权威源与生成派生物；
+4. 只确认会实质改变范围、权限、外部状态或不可逆影响的决策。
+
+执行期间：
+
+- 修改权威源后，通过已声明 Tool 重新生成派生物；
+- 文件只能放在项目声明的位置；
+- 保留可复用事实、决策与验证证据，避免提交缓存、临时日志或可重建中间产物；
+- 由叶子 Skill 创建或审查交付物，本 Skill 继续拥有生命周期与 Git 职责；
+- 证据改变执行路线时更新计划。
+
+## 6. 调用独立指导与审查
+
+Opinion 是独立的指导/审查能力。项目声明 Opinion provider，且 `OPINION.md` 含用户确认的规则时，在两个明确边界调用它：
+
+1. **实施前**：使用明确的交付物信号请求适用指导。
+2. **交付前**：请求独立检查，并通过 provider 自身的演化流程记录未解决冲突或可复用反馈。
+
+provider 支持分层加载且规则已声明时，实施前读取核心规则与规则束索引，任务命中触发条件或判断不清时读取对应规则束，交付前用 provider 的核对命令比对本次交付的信号与已读取的规则束。provider 返回 `fallback` 或不可用时完整读取 `OPINION.md`。
+
+禁止在本 Skill 内解释、存储或演化 Opinion 规则；禁止让 Opinion provider 选择 Task/Case 状态、路径、进度或 Git 操作。`OPINION.md` 仍为空白时跳过规则检查并记录未配置状态。provider 不可用时，明确报告指导/检查降级；只有项目策略允许时才能继续。
+
+## 7. 验证与记录
+
+按风险比例验证：
+
+- 对改动范围运行聚焦测试或 validator；
+- 验证机器可读 manifest 与生成索引；
+- 布局重要时目视检查渲染产物；
+- 运行项目声明的 Opinion 或其他横切质量门禁；
+- 检查最终 diff 的范围、密钥、生成噪声与意外删除。
+
+记录当前工作容器要求的最小持久证据：
+
+- Task：状态、决策、验证证据、阻塞和下一步；
+- Case：候选、决策、已观察结果；结果尚未发生时记录 follow-up；
+- 直接改动：简洁交接与验证结果。
+
+禁止把推断结果记录为已确认 outcome。
+
+记录可复用的项目事实时遵守项目的记忆约定：
+
+- 每类信息只有一个权威位置，其他位置只留指针；进行中的工作状态属于 Task 或 Case，行为与表达偏好属于 Opinion provider 的候选流程。
+- 能从文件或版本历史直接得到的内容、已完成工作的流水、只对当前对话有用的内容不写入记忆。
+- 客户端自带的记忆功能只保存该客户端自身的运行事实；项目事实写入仓库。
+- 使用随包工具时，先用 `memory.py create` 预览再写入，`description` 写明何时应当想起这条记忆；内容已晋升为规则或已经失效时用 `retire` 退役。
+
+结束一个里程碑前运行记忆检查：随包工具为 `memory.py check`，自有实现为 Profile 的 `check_command`。先处理结构问题与失效的来源路径；到期条目核实后用 `verify` 更新。体积预算、保留窗口与复核间隔由项目自己的参数文件规定。
+
+## 8. 限定范围的 Git 交付
+
+对 Git 项目：
+
+1. 把最终状态与基线比较；
+2. 只暂存属于当前请求的文件；
+3. 检查 staged diff；
+4. 只有用户明确要求/授权，或项目策略允许自动提交时才 commit；
+5. push、发布、merge、tag 或创建 PR 必须有单独明确授权，或项目策略明确许可。
+
+dirty worktree 中禁止宽泛暂存。禁止重写、丢弃或吸收无关改动。创建 commit 后报告 hash。
+
+## 9. 保持边界清晰
+
+- 项目初始化与骨架迁移归版本化的 `agents-init` 管理，不属于本 Skill。
+- Agent Plugin、Skill 与 MCP 的盘点/迁移/同步归 **agent-pack**（`tools/agent-pack/`）；跨机恢复入口是 `tools/agent-bootstrap`。禁止在本 Skill 内重建第二套配置管理逻辑。
+- 除非本 Skill 明确委派，领域 Skill 禁止自我修改、创建无关 Task/Case、编辑全局进度或提交改动。
+- 生成索引属于投影，源记录保持权威地位。
+- 项目本地规则可以特化本工作流，应引用本 Skill，避免复制完整生命周期。
+
+## 完成检查
+
+结束前确认：
+
+- 已交付用户要求的结果，或已识别具体阻塞；
+- Task/Case 选择有依据且状态为最新；
+- 已按声明能力路由项目 Tool 与叶子 Skill；
+- 已运行相关测试、渲染和 Opinion 检查，或明确说明省略项；
+- 项目声明了记忆提供方时，已运行记忆检查，新写入的条目符合项目的记忆约定；
+- 无关 worktree 改动保持原样；
+- commit 与 push 操作符合用户授权。