@zq-silk/yui 0.15.8 → 0.15.11

package/i18n/README.zh-CN.md

@@ -2,18 +2,38 @@
 
 # Yui
 
+[![Core CI](https://github.com/zhangqian-silk/yui/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/zhangqian-silk/yui/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+![Node](https://img.shields.io/badge/node-20%20%7C%2022%20%7C%2024-brightgreen.svg)
+![Platform](https://img.shields.io/badge/platform-Linux%20x64%20%28glibc%29-blue.svg)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#参与开发)
+
 让 Agent 持续推进你的任务，而不只是回答一轮对话。
 
-Yui 帮你把日常请求组织成任务，再协调 Agent 解决它们。你只需在对话中描述
-目标：Agent 识别相关 Project，区分新任务与已有任务的补充，把相关需求放在
-一起。每个 Task 由一个 Leader 负责规划，按需调用其他已配置的 Agent，
-并把结果和需要你决定的事项带回来。
+Yui 是面向编程 Agent 的本地控制面。你只需用自然语言把目标告诉 Operator：它
+识别相关 Project，区分新任务与已有任务的补充，并把每个请求整理成一个 Task，
+由一个 Leader 负责规划、委派，并把结果与决策带回来。意图、进展和结果都保存
+在单次对话之外，因此继续工作从 Task 开始——而不是靠你在多个终端之间搬运
+上下文或凭记忆。
+
+**亮点**
+
+- **天生持久** —— Task、决策与结果都保存在本地的单一 SQLite 存储里，进程
+  崩溃或重启都不丢，继续工作从 Task 开始，而不是从聊天记录开始。
+- **一处对话，多个 Task** —— Operator 把自然语言请求变成新 Task 或已有
+  Task 的补充，无需记 Task ID，也不用在多个终端之间搬运上下文。
+- **每个结果都有 Leader 负责** —— 规划、拆成 WorkItem、委派给 Worker 与
+  Reviewer 并闭环；你也可以随时直接和它沟通。
+- **自带 Agent** —— Codex CLI、Claude Code CLI 和 ACP 通过统一边界接入，
+  可替换而不丢失 Task。
+- **本地优先、私有** —— 一切运行在你自己的机器上，面向单个受信任用户；
+  Web 视图仅本地回环、只读。
+- **默认隔离** —— 仓库改动发生在受管 Git worktree 中，稳定 checkout 保持只读。
 
-你不必为每个步骤手动建单，在多个终端之间搬运上下文，或记住哪个 Agent
-正在处理哪条需求。Yui 把意图、进展和结果保存在单次对话之外，让继续工作
-从任务本身开始，而不是依赖你的记忆。
+> **状态：** 尚未发布 1.0（0.15.x）。CLI 与配置在版本之间仍可能变化；每次升级
+> 都会迁移有效的既有 Home。
 
-[快速开始](#快速开始) · [通过对话管理工作](#通过对话管理工作) · [核心设计](#核心设计)
+[快速开始](#快速开始) · [通过对话管理工作](#通过对话管理工作) · [架构](#架构) · [设计原则](#设计原则)
 
 ## 快速开始
 
@@ -104,7 +124,156 @@ Agent 可以重新读取任务上下文，继续兼容的 Session，或在必要
 想直观看进展，可以在另一个终端运行 `yui web`。本地 Web 展示同一份任务与
 待回答问题，不是另一套需要同步的任务系统。
 
-## 核心设计
+## 架构
+
+在底层，Yui 把每一条持久事实都保存在同一个本地 SQLite 存储里，并让 Agent
+通过小而明确的操作来读写它。下面从几个不同角度看同一套系统：
+
+- [产品结构](#产品结构) —— 你面对的持久对象
+- [工作如何流转](#工作如何流转) —— 围绕 Task 的闭环
+- [用户消息流转](#用户消息流转) —— 你发一条消息时发生了什么
+- [核心模块](#核心模块) —— 长期运行的运行时组件
+- [分层设计](#分层设计) —— 自上而下的职责划分
+- [生命周期](#生命周期) —— Task 与 WorkItem 经历的状态
+
+### 产品结构
+
+Yui 为你组织的东西 —— 是持久对象，而不是进程：
+
+```text
+  全局
+   ├─ Operator ── 与你对话的 Agent；横跨所有 Project 与 Task
+   └─ Projects
+       └─ Project ── 受管的代码库 + 它的 Project Knowledge
+           └─ Task ── 你要的一个明确结果
+               ├─ Brief ......... 目标 · 边界 · 方法
+               ├─ Roles ......... Leader（负责）· Workers · Reviewers
+               ├─ WorkItem ...... 可独立验收的需求
+               │     └─ AgentRun .. 一次明确请求的执行 ─▶ Result
+               ├─ 消息 .......... 持久对话 + Decision
+               └─ 审查 / 集成 ─▶ 验收交付
+```
+
+### 工作如何流转
+
+```text
+  你
+   │  用自然语言描述工作 · 回答问题 · 细化范围
+   ▼
+  Operator ── 读取你的意图，然后：
+   │            • 新建一个 Task，或
+   │            • 把补充追加到已有 Task（follow-up）
+   ▼
+  Task ── 由一个 Leader 负责，闭环推进：
+   │
+   │   规划 ─▶ 拆解为多个 WorkItem ─▶ 交付 ─▶ 审查 ─▶ 关闭
+   │
+   │   每个 WorkItem 由 Leader 自己推进，或委派出去：
+   │     ├──▶ Worker     另一个 Agent 来实现
+   │     └──▶ Reviewer   在验收前检查结果
+   │
+   ▼
+  结果与决策回到你这里 —— 你也可以随时直接和 Leader 沟通某个任务的细节。
+```
+
+### 用户消息流转
+
+你发一条消息时会发生什么 —— Controller 只负责唤醒 Agent，持久记录始终在存储里：
+
+```text
+  ── 入站 ────────────────────────────────────────────────────────────────────
+  你 ─▶ Operator ─▶ 记录一个 Task（新建或 follow-up）+ 一条 Message ─▶ yui.db
+                                                                        │
+                                                        Controller 唤醒 Leader
+                                                                        ▼
+  ── 处理 ────────────────────────────────────────────────────────────────────
+  Leader 读取 Context ─▶ 自己动手，或委派给 Worker / Reviewer
+                      ─▶ 把结果 · 决策 · 消息写回 ─▶ yui.db
+                                                                        │
+                                                       Controller 唤醒 Operator
+                                                                        ▼
+  ── 出站 ────────────────────────────────────────────────────────────────────
+  yui.db ─▶ Operator 读取更新 ─▶ 回复你
+```
+
+### 核心模块
+
+长期运行的运行时组件。你始终只和 Operator 对话，真正读写存储的是 Agent
+与 Controller：
+
+```text
+  你
+   │  你用自然语言和 Operator 对话
+   │  （你不直接驱动 Controller 或存储）
+   ▼
+  Agent 会话 · 在 tmux 中
+   │  Operator ── 与你对话的 Agent；把请求归入 Task
+   │  Leader · Workers · Reviewers ── 规划、交付、审查
+   │  每个角色通过 AgentHost / AgentEndpoint / Driver 驱动一个原生 Agent：
+   │    Codex CLI（App Server）· Claude Code CLI（stream-json）· ACP
+   │
+   │  Agent 读取 Context 并做原子修改（yui 操作）
+   ▼
+  ┌─ yui.db — SQLite (WAL) · 唯一事实来源 · 每次修改一个事务
+  │  Task · WorkItem · AgentRun · 消息 · 决策 · 结果
+  └─ Project Knowledge · 配置
+   ▲
+   │  读取并记录运行事实；唤醒会话并投递工作
+   │
+  Controller · 每个 Home 一个
+     投递 · Scheduler · Job · 能力宿主 · Web 监听
+     它负责搬运工作、记录事实——但从不判断回答好坏
+
+  Agent 在 Project 中工作：只读 checkout + 隔离 worktree。
+  Web 视图（yui web）：对存储的本地回环、只读投影。
+```
+
+### 分层设计
+
+每一层只负责一件事，并暴露小而明确的能力，而不是固定流程：
+
+```text
+  体验层 Experience   —  你如何交互
+    CLI（Operator）· Web（本地回环、只读）· 原生 Agent 会话
+    采集输入 · 展示事实 · 确认操作 · 调用能力
+        ▼
+  决策层 Intelligence —  谁来决定
+    Operator：识别请求、划分 Task
+    Leader：  规划 · 委派 · 判断 · 完成一个 Task
+    Workers · Reviewers（行为来自 Role 与 Skill）
+        ▼
+  能力层 Capability   —  Yui 暴露的原子操作
+    交付：  Task · WorkItem · Decision · Candidate · Review
+    上下文：Context · Message · InputRequest · Project Knowledge
+    配置：  Role · Agent 配置 · Project · Plugin
+    执行：  dispatch · inspect · stop · 资源操作 · Artifact
+        ▼
+  执行层 Execution    —  工作实际如何运行
+    AgentHost / AgentEndpoint / Driver，各自运行在 tmux 会话中
+    Codex CLI（App Server）· Claude Code CLI（stream-json）· ACP
+    受管 Git worktree · 采用的环境
+        ▼
+  内核 Kernel         —  持久权威：yui.db（SQLite，WAL）
+    存储 · 身份 · 权限 · 操作事实 · 实例宿主
+
+  ▲ 插件通过 Capability Registry 扩展能力层
+```
+
+### 生命周期
+
+每个对象的状态只有一个权威；执行与等待是运行事实，不是额外状态：
+
+```text
+  Task      draft ─▶ active ─▶ completed ─▶ archived
+                        └────▶ cancelled ─▶ archived
+
+  WorkItem  open ─▶ accepted ─▶ retired
+
+  Draft 只保存规划；激活后才采用交付工作区。
+  归档需要工作已了结、worktree 干净，且不可重新打开。
+```
+
+## 设计原则
 
 ### Agent 做判断，Yui 保存工作事实
 
@@ -139,6 +308,17 @@ Task-local 插件。可执行插件仍需要具体执行授权；业务结果可
 Yui 面向一个受信任本地用户，不是 OS 沙箱，也不是远程多用户服务。发布、
 授予新权限等外部效果仍需相应授权。
 
+## 对比
+
+|  | 只聊天的 Agent | 手动 Agent CLI + tmux | Yui |
+| --- | --- | --- | --- |
+| 工作能否跨会话留存 | 否 | 靠你自己记 | 持久 Task，集中存储 |
+| 新请求还是补充 | 你判断 | 你判断 | Operator 自动分流 |
+| 多步委派 | 手动 | 手动 | Leader → WorkItem → Worker/Reviewer |
+| 中途换模型/Agent | 上下文丢失 | 手动重配 | 统一边界下可替换 |
+| 并行工作隔离 | —— | 自己管分支 | 受管 Git worktree |
+| 事实存放在哪 | 聊天记录 | 分散各处 | 单一 SQLite 事实来源 |
+
 ## 深入了解
 
 [总体架构](../ARCHITECTURE.md)介绍端到端设计，
@@ -150,7 +330,9 @@ Yui 默认将控制面数据保存在 `~/.yui`，通过 `YUI_HOME` 选择另一
 
 ## 参与开发
 
-源码 checkout 中从 `npm ci` 和 `npm test` 开始，阅读
+完整流程见 [CONTRIBUTING.md](../CONTRIBUTING.md)，并请遵守
+[行为准则](../CODE_OF_CONDUCT.md)。简而言之：源码 checkout 中从
+`npm ci` 和 `npm test` 开始，阅读
 `.agents/skills/develop-yui/SKILL.md` 与[验证策略](../docs/testing/verification-levels.md)。
 源码构建还需要 Linux C 编译器和静态 libc 开发库，用于构建 Claude 子进程
 监督器；发布的 npm 包已包含该可执行文件，安装使用时无需编译。
@@ -160,6 +342,13 @@ Yui 默认将控制面数据保存在 `~/.yui`，通过 `YUI_HOME` 选择另一
 状态命令前执行该 launcher 的 `setup`。不要用全局 `yui` 或 `make link`
 验证本地修改。真实模型、付费或共享资源测试需要用户明确请求这些资源。
 
+## 社区与支持
+
+- 问题、缺陷与功能建议：提交
+  [GitHub issue](https://github.com/zhangqian-silk/yui/issues)。
+- 安全：见[安全策略](../SECURITY.md)。Yui 面向单个受信任的本地用户，不是
+  OS 沙箱，也不是远程服务；涉及安全的问题请私下报告，不要公开提交 issue。
+
 ## 许可证
 
 [MIT](../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.15.8",
+  "version": "0.15.11",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,
@@ -14,6 +14,7 @@
     "docs",
     "README.md",
     "ARCHITECTURE.md",
+    "ARCHITECTURE.zh-CN.md",
     "i18n/README.zh-CN.md",
     "LICENSE"
   ],