@zq-silk/yui 0.0.0

package/i18n/README.zh-CN.md

@@ -0,0 +1,205 @@
+<p align="right"><a href="../README.md">English</a> | <strong>简体中文</strong></p>
+
+# Yui
+
+Yui 是一个用于长期 Codex/Claude 工作的本地编排器。控制状态保存在可检查的 JSON 文件中，所有 Agent 终端完全由 tmux 主导，带 Repository 的 Task 使用确定性的 Git worktree。
+
+当前实现恢复了实用的 Role/Agent/session 模型和 CLI 框架，但没有恢复后期膨胀的数据维护、租约、定时调度和恢复账本体系。
+
+## 环境要求
+
+- Node.js 20.17+、22.9+ 或 24.x
+- Git
+- tmux
+- Codex CLI 或 Claude Code CLI
+
+## 初始化
+
+```sh
+npm install -g @zq-silk/yui
+yui setup
+yui doctor
+```
+
+`setup` 是交互式的：检测已安装的 Agent CLI、选择要配置的 Agent、默认 Agent 和 Operator Agent、确认 Operator workspace，并询问 shell completion。再次运行不会删除已有 Task/Role，可用于调整配置。
+
+`completion` 无论是否指定 shell，都会进入确认流程：
+
+```sh
+yui completion
+yui completion zsh
+```
+
+流程会确认生成脚本、安装路径和 shell 启动文件修改。补全脚本直接由命令目录生成，支持二级及更深层子命令。
+
+默认 home 是 `~/.yui`。隔离环境可设置：
+
+```sh
+export YUI_HOME=/absolute/path/to/yui-home
+yui setup
+```
+
+home 中包含 `schema.json`、权威 `state.json`、Controller 发现文件和受管理 worktree。当前存储版本严格匹配且 fresh-only；代码保留了未来版本的迁移注册表，但本版不迁移旧格式。
+
+## 快速开始
+
+```sh
+yui repository add app /absolute/path/to/app --base main
+yui repository list
+
+yui task create "交付 CSV 导出" --repository <repository-id> --base main
+yui task update <task-id> --priority high --tags release,csv --due-at 2026-08-01T00:00:00Z
+yui task update <task-id> --clear-priority --clear-tags --clear-due-at
+yui task show <task-id>
+yui task context <task-id>
+yui task activate <task-id>
+```
+
+查看已有 Task 的详细状态时，优先使用 `task context`。它一次聚合 Task、Brief、Active Decision、最近的 Milestone、Role、当前及最近的 WorkItem 与关联 Run、最近的 Message、Open/Resolved InputRequest 和 Event。终端输出会精简历史和长文本；`yui --json task context <task-id>` 会在顶层 `data` 中返回完整记录。
+
+新 Task 是 Draft，并已创建 Leader。激活时会排入第一次持久 Leader wake。带 Repository 的 Task 会先为每个 Role 创建 `<YUI_HOME>/worktrees/<task-id>/<role-name>`，对应分支为 `yui/<task-id>/<role-name>`，然后才启动 Leader；后续新增 Role 也会在执行前获得独立 worktree。
+
+通过 Operator 提交消息：
+
+```sh
+yui operator submit "比较 CSV 与 JSON 的兼容性" --task <task-id>
+yui operator submit "研究更小的缓存设计"
+yui operator enter
+```
+
+不带 `--task` 时会创建新 Draft。Draft 可以继续规划，但激活前不会执行 Agent 工作。
+
+添加 Worker 并派发 WorkItem：
+
+```sh
+yui task role add <task-id> implementer --agent codex
+yui task role list <task-id>
+
+yui task work create <task-id> "实现导出器" --role implementer
+yui task work dispatch <work-item-id> --input "完成实现并运行聚焦测试"
+```
+
+Worker 显式结束当前 Run：
+
+```sh
+yui task run yield <run-id> --summary "导出器已完成，聚焦测试通过"
+```
+
+yield 会原子完成 Run 和 WorkItem、追加结果消息并唤醒 Leader。Leader 不会自唤醒；Leader 忙碌时，Operator/Worker 的 pending wake 会一直保留到 Leader 空闲。
+
+当活动 Leader Run 必须获得用户决定才能继续时，可以创建持久 InputRequest，并 yield 当前 Run：
+
+```sh
+yui task input request <task-id> --question "默认使用哪种格式？" \
+  --choice csv="CSV" --choice json="JSON" --blocks work-item:<work-item-id>
+yui task input list
+yui task input show <input-id>
+yui task input answer <input-id> --choice csv
+```
+
+请求默认必须由用户回答，并保持开放直到回答或取消。当 Agent 存在安全的推荐方案时，可以为选项设置明确的超时回退：
+
+```sh
+yui task input request <task-id> --question "默认使用哪种格式？" \
+  --choice csv="CSV" --choice json="JSON" \
+  --recommend csv --timeout-seconds 300
+```
+
+推荐项会明确展示给用户；如果截止时间前没有回答，第一轮到期后的 Controller 扫描会原子采用这个确定选项，并排队恢复固定的 Leader session。自由文本和必须由用户回答的请求永远不会自动解决。
+
+`task input list` 是权威的全局开放输入 Inbox；可附加 Task ID 限定范围，或使用 `--all` 查看已回答和已取消的请求。Controller 还会尝试向已经运行且处于输入状态的 Operator composer 投递一次带回执的提示；它不会为了通知而启动或打断 Operator。Operator 不在线或正忙时，请求仍保留在 Inbox，并在后续 Controller 扫描时重新尝试。用户和 Operator 都可回答。存在开放请求时，无关的 pending wake 不会绕过等待，Task 也不能 complete 或 archive。原 Leader 也可执行 `yui task input cancel <task-id> <input-id> --reason "..."`，取消不会使 Leader 自唤醒。
+
+```sh
+yui task context <task-id>
+```
+
+需要查看单个集合或记录时，再使用 `task work`、`task message`、`task run` 和 Task Knowledge 下的细分命令。
+
+完成目标后，可将 Task 标记为 completed，从而停止自动唤醒，同时保留 session 和各 Role worktree：
+
+```sh
+yui task complete <task-id> --summary "CSV 导出已交付并验证"
+yui task reopen <task-id>
+```
+
+completed Task 在显式 reopen 前会拒绝消息、派发、进入 session、重试和迟到的 yield。archive 仍是终态，并负责 tmux/worktree 清理。
+Task 生命周期的交互选择只展示有效来源状态：activate 只展示 Draft，complete 只展示 active，reopen 只展示 completed。
+
+## Session 与 tmux
+
+Yui 不代理交互式 Agent 终端。执行 `operator enter`、`role enter` 或 `task enter` 前，Yui 会关闭 readline、退出 raw mode、暂停自身 stdin，再同步把终端交给 tmux。因此 Codex 原生的 `/model`、斜杠命令提示、全屏渲染和按键处理都可正常工作。
+
+```sh
+yui role enter <global-role>
+yui task enter <task-id> [role]
+yui task role enter <task-id> <role>
+```
+
+每个 Role 可绑定多个 Agent，有一个 active Agent，并为每个 Agent binding 独立保存 native session。切换 Agent 会保留休眠 session；Role 有活动 Run 或 native process 时禁止切换。
+
+Claude 的 session ID 在启动前分配。受管理的 Codex 启动使用 Codex 结构化 `notify` 回调，在 turn 完成后记录 thread ID，不再向模型对话注入 session-bind prompt。
+
+## Controller 与失败处理
+
+每个 `YUI_HOME` 有一个后台 Controller：
+
+```sh
+yui controller status
+yui controller stop
+yui controller restart
+```
+
+`controller restart` 会用当前安装的 Yui 版本替换 Controller 进程及其调度循环、socket 服务，不会停止或重启已受管的 tmux/Agent 会话。
+
+完整 reconciliation 默认每 30 秒执行一次；持久状态变化仍会立即请求一次扫描。保留的闭环为：
+
+1. 准备 active Task 的 repository workspace；
+2. 停止 archived Task 的 tmux，并只清理干净 worktree；
+3. 投递排队的 Worker Run；
+4. 检测活动 Role 进程退出；
+5. Leader 空闲时投递 pending wake。
+
+自动输入只通过 tmux 投递，并先进行 Agent 专属 readiness 检查。pane 内 receipt 可避免 Controller 重试时重复输入同一 Run。
+
+Role 在 yield 前退出时，Controller 会失败对应 Run 和 running WorkItem，并唤醒 Leader。恢复状态通过精简的 Jobs 兼容视图呈现：
+
+```sh
+yui jobs list
+yui jobs retry leader-recovery:<task-id>
+yui task reconcile <task-id>
+yui task run retry <failed-run-id>
+```
+
+`jobs` 不是旧版通用队列，只展示持久 Leader wake 和 Leader recovery failure。
+
+completion 是可逆的执行屏障。归档是终态：失败活动 Run、停止 Task 的 tmux session，并逐个移除干净的 Role worktree；脏 Role worktree 会保留，供人工确认处理。
+
+## 管理命令
+
+```sh
+yui update
+yui agent add|list|show|update|remove
+yui role add|list|show|update|remove|bind|enter
+yui role session record|replace
+yui repository add|list
+```
+
+Agent 环境变量绑定只保存进程环境变量名，不保存 secret 值；raw args 不能覆盖 adapter 管理的生命周期参数。
+
+## 范围
+
+Yui 面向一台机器上的一个受信任本地用户。它不包含 Web/API、多用户协调、backup/import/export、trash/restore、derived index、recovery journal、runtime lease、inactivity TTL、cooldown 或 recurring schedule。
+
+持久化和调度细节见 [ARCHITECTURE.md](../ARCHITECTURE.md)。
+
+## 本地开发
+
+```sh
+npm run build
+npm test
+npm run lint
+```
+
+## 许可证
+
+[MIT](../LICENSE)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zq-silk/yui",
+  "version": "0.0.0",
+  "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "yui": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "ARCHITECTURE.md",
+    "i18n/README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^20.17.0 || ^22.9.0 || ^24.0.0"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "libc": [
+    "glibc"
+  ],
+  "keywords": [
+    "yui",
+    "tmux",
+    "cli",
+    "agents",
+    "codex",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhangqian-silk/Yui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zhangqian-silk/Yui/issues"
+  },
+  "homepage": "https://github.com/zhangqian-silk/Yui#readme"
+}

package/skills/yui-leader/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: yui-leader
+description: Lead one lean Yui Task by reading messages, creating Worker roles and WorkItems, dispatching Runs, and collecting yielded summaries.
+---
+
+# Yui Leader
+
+Own the direction of the Task identified in the launch context. Decompose the mission into finite WorkItems, dispatch the right Worker, and synthesize the yielded summaries for the user.
+
+## Recover current state
+
+Use only the public current commands:
+
+```sh
+yui task show <task-id>
+yui task message list <task-id>
+yui task input list <task-id> --all
+yui task role list <task-id>
+yui task work list <task-id>
+yui task run list <work-item-id>
+```
+
+Use the Task, WorkItem, Role, and Run IDs supplied by Yui output or the launch prompt. Do not infer IDs from tmux names or edit Yui storage directly.
+
+## Decompose and dispatch
+
+1. Add a Worker only when the Task needs a separate execution role:
+
+   ```sh
+   yui task role add <task-id> <role-name> --agent <codex-or-claude>
+   ```
+
+2. Create a finite WorkItem and assign it by Role name:
+
+   ```sh
+   yui task work create <task-id> "<clear outcome>" --role <role-name>
+   ```
+
+3. Read the WorkItem ID from the response, then dispatch one bounded round:
+
+   ```sh
+   yui task work dispatch <work-item-id> --input "<scope, constraints, and expected evidence>"
+   ```
+
+Do not dispatch a terminal WorkItem or create a second active Run for the same WorkItem.
+
+## Request a decision
+
+If the active Leader control Run cannot make progress without user input, create one durable request:
+
+```sh
+yui task input request <task-id> --question "<specific question>" \
+  --choice <key>=<label> --blocks work-item:<work-item-id>
+```
+
+Omit `--choice` for free text. Without a recommendation, the request requires an explicit user answer and never expires. When the choices include a safe fallback that you genuinely recommend, add both `--recommend <key>` and `--timeout-seconds <seconds>`. After that deadline, Yui may apply only that exact choice; never configure this fallback for a decision that inherently requires user authorization. Use repeated `--choice` or `--blocks` options only when needed. A successful request yields the current Leader Run and releases its active fence, so stop that turn and wait for Yui to resume the same session after an answer. If the question is no longer needed, only its originating Leader may cancel it with `yui task input cancel <task-id> <input-id> --reason "<reason>"`; cancellation does not self-wake the Leader.
+
+## Collect and continue
+
+- Incoming TaskMessages contain Operator input or Worker yield summaries. Do not author a TaskMessage to direct or wake yourself.
+- A Worker finishes with `yui task run yield`; that yield completes its Run and WorkItem, appends the summary as a TaskMessage, and wakes the Leader.
+- Collect results with `yui task work list <task-id>` and `yui task message list <task-id>`.
+- If a running Session disappears, use `yui task reconcile <task-id>` to request an immediate Controller scan, inspect `yui task run list <work-item-id>`, then retry only the confirmed failed Run with `yui task run retry <run-id>`. `yui jobs list` only shows pending Leader wakes and Leader recovery failures. Inspect partial work first because retry may repeat it.
+- Manual bookkeeping is only for a WorkItem with no queued or running Run:
+
+  ```sh
+  yui task work update <work-item-id> <todo|running|done|failed> --summary "<text>"
+  ```
+
+Never use a manual WorkItem update to replace or override an active Run.
+
+Summarize the outcome, tests or evidence, remaining risks, and next action. Ask the user or Operator to archive the Task when continued Leader work is no longer useful.

package/skills/yui-operator/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: yui-operator
+description: Use the lean Yui Operator to create or route tasks, register repositories, inspect work, enter sessions, and archive finished tasks.
+---
+
+# Yui Operator
+
+Act as the task-neutral entry point for the user's work. Keep the flow simple: inspect current Tasks, submit the request to the right Task, and leave implementation decisions to that Task's Leader.
+
+## Handle a request
+
+1. Inspect existing work with `yui task list` and inspect the global open-input Inbox with `yui task input list`. When a likely match exists, use `yui task context <task-id>` first; it includes the Task's open and recently resolved inputs. Use the narrower show/list commands only when one collection or record needs closer inspection.
+2. Route a request to an existing Task with:
+
+   ```sh
+   yui operator submit "<request>" --task <task-id>
+   ```
+
+3. If the request is a distinct mission, create it directly through the Operator:
+
+   ```sh
+   yui operator submit "<request>"
+   ```
+
+4. Keep the new Task as a Draft while the mission is still being clarified. When it is ready to execute, run `yui task activate <task-id>`.
+5. Report the resulting Task ID and lifecycle state to the user and keep follow-up work inside that Task.
+
+Use `yui --json ...` for non-`enter` commands when stable machine-readable output helps you retain exact IDs.
+Structured reads such as `task list`, `task show`, and `task context` return their payload in the top-level `data` field; consume that field directly instead of parsing terminal text from `output`. The `task context` data contains complete records even though its terminal output summarizes long histories.
+
+## Repositories and direct Task creation
+
+For repository-backed work, register the repository first:
+
+```sh
+yui repository add <name> <absolute-path> --base <ref>
+yui repository list
+yui task create "<title>" --repository <repository-id> --base <ref>
+yui task activate <task-id>
+```
+
+For work that does not need Git, use `yui task create "<title>"`. Every created Draft already has one Leader record; activate it before entering the Leader or dispatching work.
+
+## Enter and administer
+
+- The user enters the global session with `yui operator enter`. Do not recursively run that command from inside the Operator session.
+- Activate a ready Draft with `yui task activate <task-id>`.
+- Enter an active Task's Leader with `yui task enter <task-id>`, or a named Worker with `yui task enter <task-id> <role-name>`.
+- Relay explicit Task-scoped information with `yui task message send <task-id> "<body>"`.
+- Inspect a Leader's durable question with `yui task input show <input-id>`, then answer it with exactly one of `yui task input answer <input-id> --choice <key>` or `yui task input answer <input-id> --text "<answer>"`. An answer queues the Task's fixed Leader session to continue.
+- When Yui delivers an input-required notice, present its question, choices, recommendation, and deadline to the user. Do not choose or invent an answer. Submit only the user's response; if a recommended request reaches its deadline first, Yui applies the recorded fallback and resumes the Leader automatically.
+- Inspect Workers with `yui task role list <task-id>` and queued failures with `yui jobs list`.
+- Detect a disappeared running Session with `yui task reconcile <task-id>`, which requests an immediate Controller scan. Then inspect Run history before using `yui task run retry <failed-run-id>`; `yui jobs list` only shows pending Leader wakes and Leader recovery failures.
+- Retry only an explicitly failed Job with `yui jobs retry <job-id>`.
+- Archive finished work with `yui task archive <task-id>` after confirming that no more Task work is required. Archival stops Task Sessions and removes only a clean managed worktree; a dirty worktree is preserved for deliberate cleanup and Job retry.
+
+Never edit Yui's authoritative files directly or manually manage Yui tmux sessions and worktree directories.

package/skills/yui-worker/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: yui-worker
+description: Execute one lean Yui WorkItem in the assigned Agent session and finish the Run with a concise yielded summary.
+---
+
+# Yui Worker
+
+Execute the bounded WorkItem from the launch prompt. Do not take over Task direction, create other Roles, or dispatch more work.
+
+## Work the assigned round
+
+1. Keep the supplied Task, WorkItem, and Run IDs exact. When context is needed, inspect the current records:
+
+   ```sh
+   yui task show <task-id>
+   yui task message list <task-id>
+   yui task work list <task-id>
+   ```
+
+2. Work only in the cwd/worktree provided for this Role. Do not manually create, move, or remove a Yui worktree or tmux session.
+3. Stay within the dispatched scope. If blocked, stop at a safe boundary and put the blocker, needed decision, and completed evidence in the yield summary.
+
+4. At the end of the round, yield exactly once:
+
+   ```sh
+   yui task run yield <run-id> --summary "<result, evidence, risks, and follow-up>"
+   ```
+
+The yield marks the current Run and WorkItem completed, records the summary as a TaskMessage, and wakes the Leader. If the round ends partial or blocked, state that plainly in the summary and leave the Leader to create follow-up work; do not claim tests, files, or results that you did not verify.
+
+Use only the current commands above. Never edit Yui's authoritative files directly.