docs: clarify Chinese README purpose compatibility and setup

Author: OracleNep

README.zh-CN.md

@@ -2,54 +2,105 @@
 
 [English](README.md) | 简体中文
 
-AgentFlowDesk 是一个 **local-first 的 AI Coding Agent 任务工作台与上下文管理器**。
+AgentFlowDesk 是一个 **local-first 的 AI Coding Agent 工作流管理器**。
 
-它不是新的聊天机器人，也不是新的大模型封装层，而是给 Claude Code、Codex CLI、Cursor、Gemini CLI、OpenCode 等 AI Coding Agent 提供一层更工程化的工作流管理能力。
+它 **不是** Claude Skill、不是 MCP Server、不是 IDE 扩展、不是浏览器插件，也不是新的聊天机器人。它是一个运行在本地的 Python CLI，位于你的 AI Coding Agent 外层，用来管理 Agent 工作前后的工程流程：
 
-它帮助开发者把一次性的 AI 对话，变成可拆分、可追踪、可复盘、可复用的工程流程：
+```text
+任务 → Context Pack → Agent 指令文件 → Agent 命令 → 日志 + Diff + 检查结果 → Review Report
+```
 
-- 在把需求交给 Agent 前，先拆成结构化任务
-- 为每个任务生成紧凑的 **Context Pack**
-- 导出到 `AGENTS.md`、`CLAUDE.md`、Cursor Rules、Codex instructions、`GEMINI.md`
-- 调用本地 Agent 命令，并记录 prompt、日志、diff、检查结果和 review report
-- 避免 AI Agent 工作过程散落在多个聊天窗口里，难以追踪和复盘
+简单说：AgentFlowDesk 会为 Claude Code、Codex CLI、Cursor、Gemini CLI、OpenCode 等工具准备干净的任务上下文，然后记录这次给了 Agent 什么、执行了什么、改了什么、测试结果如何，以及最后是否需要人工 review。
 
-> 当前状态：v0.1.0 MVP，CLI 优先。Web 任务板会在核心流程稳定后再做。
+> 当前状态：v0.1.0 MVP，CLI 优先。MVP 不需要启动服务器。Web 任务板会在核心流程稳定后再做。
 >
 > CI 说明：测试 workflow 会在 Python 3.10、3.11、3.12 上验证安装流程，以及 Context Pack / export / run 的核心路径。
 
-## 为什么做这个项目
+## 它到底是什么？
 
-AI Coding Agent 已经很强，但实际使用时仍然有很多操作层痛点：
+AgentFlowDesk 是一个给已经在使用 AI Coding Agent 的开发者准备的 **本地 Python 命令行工具**。
 
-1. **上下文需要反复复制和重写**：每次都要重新解释项目结构、文件作用、编码风格、验收标准。
-2. **结果难以复盘**：Agent 改完代码后，prompt、日志、diff、测试命令、人工验收状态往往分散在不同地方。
-3. **并行任务很麻烦**：想让多个 Agent 或多个分支同时跑任务，需要手动准备目录、分支、上下文和检查命令。
-4. **成功经验难以沉淀**：一次效果很好的 prompt 或任务拆解，很难变成下次可复用的 workflow。
-5. **不同 Agent 工具割裂**：Claude Code、Codex、Cursor、Gemini 等工具的指令文件和上下文组织方式不同，用户缺少统一管理层。
+它给这些 Agent 加了一层工程化工作流：
 
-AgentFlowDesk 的目标是把：
+- **任务管理器**：把需求拆成带目标、相关文件、备注和验收标准的小任务。
+- **Context Pack 生成器**：为每个任务生成可复现的 prompt 上下文包。
+- **指令文件导出器**：从同一份任务上下文导出 `AGENTS.md`、`CLAUDE.md`、Cursor Rules、Codex instructions、`GEMINI.md`。
+- **命令包装器**：可选地调用你本机已经安装好的 Agent CLI。
+- **运行记录器**：把 prompt、stdout、stderr、git diff、检查结果和 review report 保存到 `.agentflow/`。
 
-```text
-一次性聊天窗口
+它本身 **不提供模型能力**。除非你明确配置 `--command`，否则它不会主动调用 Claude、Codex、OpenCode、Gemini 或其他远程服务。
+
+## 兼容哪些工具？
+
+AgentFlowDesk 的兼容方式有两种：
+
+1. **文件型上下文**：把任务上下文导出为常见 Agent 指令文件，给对应工具读取，或者人工复制粘贴。
+2. **命令包装器模式**：运行任意本地 CLI 命令，并把 `{prompt}` 替换为当前任务生成的 Context Pack 路径。
+
+| 工具 | 当前支持情况 | 用法 |
+|---|---|---|
+| Claude Code | 支持 | 导出 `CLAUDE.md`，或者在你的 Claude Code CLI 支持 stdin 时使用 `claude < {prompt}`。 |
+| Codex CLI | 支持 | 导出 `AGENTS.md` 和 `.codex/instructions.md`，或者用 `{prompt}` 包装你本地安装的 Codex 命令。 |
+| OpenCode | 支持，通用 CLI 模式 | 导出 `AGENTS.md` / 使用生成的 `context-pack.md`，或者在你的 `opencode` 命令支持 prompt 文件或 stdin 时用命令包装器调用。专用 preset 后续补。 |
+| Cursor | 支持，文件导出模式 | 导出 `.cursor/rules/agentflow.mdc`，然后在项目里正常使用 Cursor。 |
+| Gemini CLI | 支持 | 导出 `GEMINI.md`，或者用命令包装器调用本地 Gemini CLI。 |
+| 其他 Coding Agent CLI | 通常支持 | 只要这个工具能读 prompt 文件、读 stdin，或者支持项目级指令文件，就可以接入。 |
+
+这里的“兼容”指的是 **工作流层兼容**，不是官方插件协议。不同 Agent CLI 的命令参数可能会变化，所以 AgentFlowDesk 的核心设计保持通用：你决定具体命令，AgentFlowDesk 负责提供 `{prompt}` 并记录运行过程。
+
+## 安装
+
+### 环境要求
+
+- Python 3.10+
+- 推荐安装 Git，用于捕获 diff
+- 可选：Claude Code、Codex CLI、OpenCode、Gemini CLI 或其他本地 Agent CLI
+
+### 从源码安装
+
+```bash
+git clone https://github.com/OracleNep/AgentFlowDesk.git
+cd AgentFlowDesk
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+python -m pip install -U pip
+python -m pip install -e .[dev]
 ```
 
-变成：
+验证安装：
 
-```text
-任务 → Context Pack → Agent Run → Diff + Checks → 人工 Review → 可复用 Workflow
+```bash
+agentflow --help
+pytest -q
 ```
 
-## 快速开始
+## 怎么部署 / 怎么启动？
+
+MVP 版本没有后台服务，也没有 Web Server，所以不需要 `docker compose up` 或 `npm run dev`。
 
-在项目根目录安装并初始化：
+所谓“部署”，就是把 CLI 安装好，然后在你要使用 AI Agent 的代码仓库里初始化：
 
 ```bash
-python -m pip install -e .
-agentflow init --name MyProject --description "Demo project using AI coding agents"
+cd /path/to/your/project
+agentflow init --name MyProject --description "Project managed with AI coding agents"
+```
+
+初始化后会在当前项目下生成：
+
+```text
+.agentflow/
+  config.json
+  tasks.json
+  runs.json
+  context/
+  runs/
 ```
 
-创建一个任务：
+AgentFlowDesk 默认只写本地 `.agentflow/` 目录，不会主动上传你的代码或 prompt。
+
+## 基础工作流
+
+### 1. 创建任务
 
 ```bash
 agentflow task create \
@@ -68,13 +119,25 @@ agentflow task list
 agentflow task show AF-20260613-001
 ```
 
-生成 Context Pack：
+### 2. 生成 Context Pack
 
 ```bash
 agentflow context build AF-20260613-001
 ```
 
-导出给不同 Agent 使用：
+生成目录：
+
+```text
+.agentflow/context/<task-id>/
+  task-brief.md
+  agent-instructions.md
+  commands.md
+  environment.md
+  relevant-files.md
+  context-pack.md
+```
+
+### 3. 导出给不同 Agent 使用
 
 ```bash
 agentflow export AF-20260613-001 \
@@ -86,7 +149,19 @@ agentflow export AF-20260613-001 \
   --force
 ```
 
-运行一个 Agent 命令或普通本地命令：
+导出目标：
+
+| Target | 输出文件 |
+|---|---|
+| `agents` | `AGENTS.md` |
+| `claude` | `CLAUDE.md` |
+| `cursor` | `.cursor/rules/agentflow.mdc` |
+| `codex` | `.codex/instructions.md` |
+| `gemini` | `GEMINI.md` |
+
+### 4. 执行命令并记录结果
+
+先用安全的本地命令试跑：
 
 ```bash
 agentflow run AF-20260613-001 \
@@ -95,7 +170,25 @@ agentflow run AF-20260613-001 \
   --check "pytest -q"
 ```
 
-`{prompt}` 会被替换为当前任务生成的 Context Pack 路径。
+如果你的 Claude Code CLI 支持 stdin，可以这样接：
+
+```bash
+agentflow run AF-20260613-001 \
+  --agent claude-code \
+  --command "claude < {prompt}" \
+  --check "pytest -q"
+```
+
+如果要接 OpenCode，可以先用通用命令包装器：
+
+```bash
+agentflow run AF-20260613-001 \
+  --agent opencode \
+  --command "opencode < {prompt}" \
+  --check "pytest -q"
+```
+
+如果你的 Agent CLI 使用的是 `--prompt-file`、`--file`、`run`、`exec` 等其他参数，直接替换 `--command` 即可。`{prompt}` 永远会被 AgentFlowDesk 替换为生成的 `context-pack.md` 路径。
 
 运行后会生成：
 
@@ -108,87 +201,19 @@ agentflow run AF-20260613-001 \
   review-report.md
 ```
 
-## 核心概念
-
-### Task
-
-Task 是最小的 Agent 工作单元。它描述“这次要让 Agent 做什么”。
-
-示例：
-
-```yaml
-title: Add SARIF ruleId support
-goal: Modify the SARIF reporter so each finding has a stable ruleId.
-files:
-  - src/reporters/sarif.py
-acceptance:
-  - Unit tests pass
-  - No unrelated files changed
-agent:
-  preferred: claude-code
-```
-
-一个好的 Task 应该尽量包含：
-
-- 明确目标
-- 相关文件或目录
-- 验收标准
-- 额外注意事项
-- 推荐使用的 Agent
-
-### Context Pack
-
-Context Pack 是按任务生成的上下文包，核心目标是减少重复复制粘贴，并让每次 Agent Run 都可复现。
-
-它包含：
-
-- 任务说明
-- Agent 操作规则
-- 项目命令
-- 文件树
-- Git 状态
-- 相关文件摘录
-- 合并后的 `context-pack.md`
-
-生成目录：
-
-```text
-.agentflow/context/<task-id>/
-  task-brief.md
-  agent-instructions.md
-  commands.md
-  environment.md
-  relevant-files.md
-  context-pack.md
-```
-
-### Export Target
-
-AgentFlowDesk 可以把同一个任务上下文导出为多个工具常用的指令文件：
-
-| Target | 输出文件 |
-|---|---|
-| `agents` | `AGENTS.md` |
-| `claude` | `CLAUDE.md` |
-| `cursor` | `.cursor/rules/agentflow.mdc` |
-| `codex` | `.codex/instructions.md` |
-| `gemini` | `GEMINI.md` |
-
-这样你可以用同一份任务上下文，在不同 AI Coding Agent 之间切换。
-
-### Run
+## 为什么做这个项目
 
-Run 表示某个任务的一次执行尝试。它会记录：
+AI Coding Agent 已经很强，但实际使用时仍然有很多操作层痛点：
 
-- 本次传给 Agent 的 prompt
-- stdout / stderr
-- Git diff
-- 检查命令结果
-- Review Report
+1. **上下文需要反复复制和重写**：每次都要重新解释项目结构、文件作用、编码风格、验收标准。
+2. **结果难以复盘**：Agent 改完代码后，prompt、日志、diff、测试命令、人工验收状态往往分散在不同地方。
+3. **并行任务很麻烦**：想让多个 Agent 或多个分支同时跑任务，需要手动准备目录、分支、上下文和检查命令。
+4. **成功经验难以沉淀**：一次效果很好的 prompt 或任务拆解，很难变成下次可复用的 workflow。
+5. **不同 Agent 工具割裂**：Claude Code、Codex、Cursor、Gemini 等工具的指令文件和上下文组织方式不同，用户缺少统一管理层。
 
-这让每次 Agent 修改都可以被复盘，而不是只留下一段聊天记录。
+AgentFlowDesk 的目标是把一次性 Agent 会话变成可 review 的工程产物。
 
-## 示例工作流
+## 示例 Review 流程
 
 ```bash
 agentflow init
@@ -201,11 +226,7 @@ agentflow task create \
   --acceptance "public CLI behavior remains unchanged"
 
 agentflow export AF-20260613-001 --target claude --force
-
-# 使用你偏好的 Agent，或者用命令包装器调用：
 agentflow run AF-20260613-001 --command "claude < {prompt}" --check "pytest -q"
-
-# 查看本次运行报告：
 cat .agentflow/runs/*/review-report.md
 ```
 
@@ -240,7 +261,7 @@ AgentFlowDesk 默认只在项目本地 `.agentflow/` 目录下保存数据，不
 
 ### 2. 不替代 Agent，只管理 Agent 工作流
 
-AgentFlowDesk 不试图替代 Claude Code、Codex、Cursor、Gemini 等工具。
+AgentFlowDesk 不试图替代 Claude Code、Codex、Cursor、Gemini、OpenCode 等工具。
 
 它做的是这些工具之上的工程化管理层：