# Xigua Agent

`Xigua Agent` 是一个受 `claude-code` 启发、可在本机运行、以 CLI 为优先入口的知识工作台智能体。当前实现采用可复用的 runtime core 与全屏终端 shell 分层设计。

## 当前状态

V1 当前聚焦于：

- 全屏 TUI 交互
- OpenAI / OpenAI-compatible 后端
- 本地文件、搜索、shell、网页工具
- 正式的多智能体任务运行时
- 会话持久化与恢复
- 权限控制
- 权限模式与行为模式
- 本地 skills、agents 与 MCP 集成

`ps`、`logs`、`attach`、`kill`、`daemon`、`remote-control`、`desktop`、`mobile` 等非核心公开入口在当前版本中以兼容占位形式存在。

## 快速开始

从 npm 安装：

```bash
npm install -g @ciqtek/xigua
xigua doctor
```

### 首次配置（30 秒完成）

```bash
xigua onboard
```

只需粘贴 DeepSeek API Key 即可开始使用！

**默认配置**：
- Provider: DeepSeek V4 Flash
- 上下文: 1M tokens（超长对话、大型文档）
- 图片: 原生支持（无需额外配置）
- 成本: 极低（输入 ￥0.08/M tokens）

获取 API Key：https://platform.deepseek.com/api_keys

### 开始使用

```bash
xigua
```

### 高级配置（可选）

需要自定义 Provider、多模型配置？

```bash
xigua onboard --custom
```

支持：
- 多个 Provider（OpenAI、Anthropic、自定义端点）
- 自定义模型列表
- 降级策略配置

## 配置

首次运行时，Xigua Agent 会创建：

- 配置文件：`~/.xigua-agent/config.json`
- 会话目录：`~/.xigua-agent/sessions`

默认 provider 配置使用 `OPENAI_API_KEY`，默认模型为 `gpt-4.1-mini`。

你可以在 TUI 内查看和更新配置：

- `/config show`
- `/config path`
- `/config set model gpt-4.1`
- `/config set baseURL http://localhost:8000/v1`
- `/config set apiKeyEnv MY_OPENAI_KEY`
- `/config set permissionMode bypass`
- `/config set behaviorMode chat`

当前模式模型分为两条轴：

- 权限模式：`ask | auto | bypass`
- 行为模式：`chat | plan`

其中：

- `bypass` 适合受控远程运行环境
- `plan` 会切换为规划工作流，默认只暴露只读/分析类工具，并通过 `Plan` 工具把计划沉淀到 `workspace/.xigua/plans/`

## Slash Commands

- `/help`
- `/clear`
- `/model`
- `/config`
- `/tools`
- `/permissions`
- `/mode`
- `/status`
- `/resume`
- `/doctor`
- `/mcp`
- `/agents`
- `/skills`
- `/plan`
- `/tasks`

其中与模式和规划直接相关的命令包括：

- `/permissions mode <ask|auto|bypass>`
- `/mode <chat|plan>`
- `/plan`
- `/plan show`
- `/plan approve`
- `/plan revise`
- `/plan cancel`

## 文档

完整文档索引见 `docs/README.md`。

关键入口：

- `docs/requirements/agent/agent-001-cli-office-agent-v1-requirement.md`
- `docs/plans/agent/agent-001-cli-office-agent-v1-design-v1.md`
- `docs/plans/agent/agent-001-cli-office-agent-v1-plan-v1.md`
- `docs/tests/agent/agent-001-cli-office-agent-v1-test-report-20260401.md`
- `docs/summary/agent-001-cli-office-agent-v1-summary-20260401.md`
- `docs/requirements/agent/agent-002-multi-provider-model-requirement.md`
- `docs/plans/agent/agent-002-multi-provider-model-plan-v1.md`
- `docs/requirements/agent/agent-004-phase-0-task-runtime-requirement.md`
- `docs/plans/agent/agent-004-phase-0-task-runtime-design-v1.md`
- `docs/plans/agent/agent-004-phase-0-task-runtime-plan-v1.md`
- `docs/tests/agent/agent-004-phase-0-task-runtime-test-report-20260402.md`
- `docs/summary/agent-004-phase-0-task-runtime-summary-20260402.md`
- `docs/requirements/agent/agent-006-permission-and-behavior-modes-requirement.md`
- `docs/plans/agent/agent-006-permission-and-behavior-modes-design-v1.md`
- `docs/plans/agent/agent-006-permission-and-behavior-modes-plan-v1.md`
- `docs/tests/agent/agent-006-permission-and-behavior-modes-test-report-20260402.md`
- `docs/summary/agent-006-permission-and-behavior-modes-summary-20260402.md`
- `docs/pmm/pmm-002-xigua-agent-vs-claude-code-gap-and-readiness-20260404.md`
- `docs/pmm/pmm-004-xigua-agent-claude-openclaw-comprehensive-comparison-20260405.md`

## 任务运行时

`Agent` 工具现在会创建正式 task，而不是只返回一段字符串摘要。

当前支持：

- 父 session 记录 task 元数据
- 子任务使用独立 child session 保存 transcript
- `/status` 显示任务统计
- `/tasks list`
- `/tasks show <task-id>`
- `/tasks open <task-id>`

这意味着主 agent、subagent 和更深一层的 child agent 都可以通过同一套 session/task 模型管理，而不是把多智能体行为隐藏在一次普通工具调用后面。

## 权限与规划模式

当前 `xigua-agent` 已支持：

- 正式 `bypass` 权限模式
- `chat / plan` 行为模式
- `plan` 文档存储与审批流
- `Plan / SubmitPlan` 双阶段规划工具流

关键行为：

- `plan` 模式下默认只暴露 `Read / Glob / Grep / WebFetch / WebSearch / Skill / Agent / Plan`
- 规划完成后，模型应通过 `SubmitPlan` 把状态推进到审批阶段
- `Plan` 工具会把计划落盘到 `workspace/.xigua/plans/<session-id>.md`
- 计划进入 `ready_for_approval` 后，TUI 会显示审批面板
- 批准后会自动退出 `plan` 并回到 `chat`