mogician-delegate

结构化委托技能包：「先拆分，再委托，再汇总」的体系化协作方案。

包含三部分：

• SKILL.md + references/：面向 opencode 智能体的结构化委托技能文档（Build / Plan / Worker 三种职责模式）
• Session 会话管理器 CLI：基于 .tmp/session/ 目录的文件化任务委托工具
• 原子写入机制：所有写入先写临时文件再 rename，避免半写文件导致数据损坏

定位为「禁止自动加载」技能：仅在需要任务拆分、子任务委托、结果汇总时按需加载，不替代具体领域技能。

核心概念

文件化委托是本体系唯一支持的委托模式，所有任务卡（plan）与执行结果（report）通过 .tmp/session/ 目录传递，实现跨阶段可追溯、上下文持续积累。

.tmp/session/<session-id>/
├── session.json              # session 元数据
├── context/                  # 跨阶段上下文（task-card.md / architecture.md / ...）
├── <stage-1>/                # 阶段 1（一次委托-执行-验收周期）
│   ├── plan.md               # 任务卡（Primary Agent 写入）
│   └── report.md             # 执行结果（Sub Agent 写入）
└── <stage-2>/

Session ID 命名规则：YYYY-MM-DD-任务简述（如 2026-08-12-add-session-mechanism）。

安装

| 方式 | 命令 | |------|------| | 全局安装 | npm install -g @bigmogician/mogician-delegate | | 免安装（推荐） | npx --yes @bigmogician/mogician-delegate <command> | | 项目内依赖（pnpm） | pnpm add -D @bigmogician/mogician-delegate |

环境要求：Node.js >= 18。

安装后可将技能文档部署到项目目录：

mogician-delegate install-skill              # 默认安装到 .agents/skills/mogician-delegate/
mogician-delegate install-skill --output custom-dir   # 指定安装位置

快速开始

# 1. 创建 session（幂等，不存在则自动创建）
mogician-delegate ensure --session-id 2026-08-12-demo

# 2. 创建 stage 并写入任务卡
mogician-delegate ensure-stage --session-id 2026-08-12-demo --stage analysis
cat <<'EOF' | mogician-delegate write-plan --session-id 2026-08-12-demo --stage analysis
# 任务卡：分析 xxx 模块的影响面
- 边界：只读分析，不改代码
- 交付：report.md 中给出影响面清单
EOF

# 3. Sub Agent 执行后读取结果
mogician-delegate read-report --session-id 2026-08-12-demo --stage analysis

# 4. 标记完成
mogician-delegate complete --session-id 2026-08-12-demo

命令总览

| 命令 | 说明 | |------|------| | check-ignore | 检查 .tmp/ 是否被 git ignore | | ensure | 确保 session 存在，不存在则幂等创建 | | ensure-stage | 确保 stage 存在，不存在则幂等创建 | | list | 列出所有 session，或指定 session 的 stage 信息 | | status | 显示 session 状态 | | read-plan / write-plan | 读取 / 写入阶段 plan.md | | read-report / write-report | 读取 / 写入阶段 report.md | | list-context | 列出 session context 目录下的文件（含概要） | | read-context / write-context | 读取 / 写入 session 级 context 文件 | | complete | 将 currentStage 置为 null，标记完成 | | read / write | 通用文件读写（非首选，优先使用专用命令） | | install-skill | 安装 / 覆盖更新技能到项目 | | --help / -h | 显示帮助 | | --version / -v | 显示版本号 |

各命令详细参数可通过 mogician-delegate <command> --help 查看。

默认输出为阅读友好的纯文本；全局参数 --json 可输出 JSON 格式（不推荐常规使用）。

写入内容三选一（推荐顺序）：--stdin（推荐，配合 heredoc 原样保留）> --from-file > --content。

技能文档结构

| 文档 | 适用对象 | 内容 | |------|----------|------| | references/common.md | Primary Agent（Build / Plan 共用） | 通用规则框架 | | references/build.md | Primary Agent | 开发实现、修复、测试、验收 | | references/plan.md | Primary Agent | 分析调研、定位、影响评估 | | references/worker.md | Sub Agent | 执行明确任务卡的子任务 | | references/session.md | 全部 | Session 文件化委托规范（唯一委托模式） |

完整委托流程与规范见 references/session.md。

开发者指南

pnpm install        # 安装依赖
pnpm dev            # tsx 直跑 src/session.ts（无需编译）
pnpm build          # TypeScript 编译到 dist/（tsc + chmod）
pnpm test           # vitest 黑盒测试套件（136 用例）
pnpm pack           # 打包 npm 包

技术栈：TypeScript 7 / Node.js >= 18（CommonJS）/ vitest / pnpm。

License

MIT