# xcode

**Repository Path**: xywhsoft/xcode

## Basic Information

- **Project Name**: xcode
- **Description**: 一个基于浏览器的 AI 代码编写 Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xcode 用户使用文档

`xcode` 是一个面向代码仓库的本地 AI 编码代理。它可以：

- 读取当前工作区文件、目录、Git 状态和差异
- 在你的批准下编辑文件、执行命令、访问网络资源
- 以 CLI 或 TUI 方式和 LLM 协作完成分析、修改、回滚、导出会话等任务
- 管理会话、审批、后台任务、MCP、skills、commands、LSP 等能力

本文档面向首次使用者，重点说明：

- 怎么开始使用
- `xcode` 能做什么
- 有哪些高价值的使用技巧
- 常见使用例子
- 怎么让 `xcode` 调用 LLM 生成一个简单页面

## 1. 开始使用

### 1.1 前提

在仓库根目录准备：

- `build\xcode.exe`
- `.xcode\config.json`
- `.xcode\secrets.local.json` 或对应环境变量中的 API Key

当前常见配置形态是：

```json
{
  "provider": {
    "kind": "openai_compat",
    "model": "GLM-5.1",
    "api_key_env": "GLM_API_KEY",
    "api_key_secret_file": ".xcode/secrets.local.json",
    "base_url": "https://open.bigmodel.cn/api/coding/paas/v4"
  }
}
```

密钥建议放到：

- 环境变量：`GLM_API_KEY`
- 或工作区文件：`.xcode\secrets.local.json`

示例：

```json
{
  "GLM_API_KEY": "your-api-key"
}
```

不要把真实密钥提交进 Git。

### 1.2 查看命令帮助

```powershell
xcode --help
```

### 1.3 推荐的两种启动方式

#### 方式 A：进入交互式 TUI

这是最适合日常编码协作的入口。

```powershell
xcode tui --interactive
```

如果你当前不在目标仓库目录：

```powershell
xcode tui --interactive --workspace D:\path\to\repo
```

#### 方式 B：直接执行单次任务

适合“做完就退出”的场景。

```powershell
xcode run "分析当前项目并告诉我入口文件和主要模块。"
```

### 1.4 `xcode` 默认行为

直接运行：

```powershell
xcode
```

会进入 TUI 命令路径，但当前更适合把它理解成“当前状态快照入口”。  
如果你要持续输入和协作，建议显式使用：

```powershell
xcode tui --interactive
```

## 2. xcode 能做什么

### 2.1 代码和仓库分析

它可以读取：

- 顶层目录结构
- 具体文件内容
- Git 分支、状态、差异
- README、配置文件、入口文件

适合这类任务：

- “分析当前项目结构”
- “这个仓库是做什么的”
- “找出前端入口和路由层”
- “告诉我哪些文件和登录流程有关”

### 2.2 代码修改

它可以：

- 修改一个文件
- 多点编辑一个文件
- 生成新文件
- 基于现有代码风格补组件、页面、接口、样式

默认重要写操作会进入审批。

### 2.3 命令执行

它可以在权限允许时执行：

- Shell / PowerShell 命令
- 构建
- 测试
- Lint
- Git 辅助命令

### 2.4 会话与回滚

它支持：

- session 持久化
- `/checkpoint`
- `/undo`
- `/redo`
- `/rewind`
- `xcode export`
- `xcode import`

这意味着你可以先让它改，再撤回，再重做。

### 2.5 审批和权限

它内置权限模式，常见包括：

- `Read(...)`
- `Edit(...)`
- `Bash(...)`
- `PowerShell(...)`
- `WebFetch(...)`
- `Mcp(...)`

你可以查看当前规则：

```powershell
xcode permissions list
```

添加规则：

```powershell
xcode permissions add allow Read(*)
xcode permissions add allow Edit(src/*)
xcode permissions add deny WebFetch(*)
```

### 2.6 TUI 里的上下文注入

在 TUI 里，你可以直接把上下文附给模型：

- `@path [prompt]`：附文件或目录
- `pasted_path [prompt]`：直接粘一个路径
- `@terminal:<id> [prompt]`：附后台任务日志
- `@server:resource [prompt]`：附 MCP resource
- `!command [ -- prompt]`：执行命令并附输出

## 3. 常用工作流

### 3.1 先分析，再改

```powershell
xcode run "先分析当前仓库的前端结构，再说明应该改哪些文件来做首页。"
```

或者进入 TUI：

```powershell
xcode tui --interactive
```

然后输入：

```text
分析当前项目，告诉我前端入口、样式入口和适合放首页的位置。
```

### 3.2 附文件让模型更准

```text
@README.md 根据这个项目说明，告诉我首页应该展示什么内容
```

### 3.3 附整个目录

```text
@src 分析这个目录的模块结构
```

### 3.4 先跑命令，再让模型解释

```text
!powershell -NoProfile -Command Get-ChildItem -Force -- 分析当前项目目录结构
```

### 3.5 分多轮完成一个任务

```text
先分析当前项目
```

```text
给我一个首页实现方案
```

```text
开始修改文件
```

```text
把配色改成更简洁的深浅对比风格
```

## 4. TUI 常用命令

进入交互后：

```text
/help
```

当前常用命令包括：

- `/status`
- `/model`
- `/permissions`
- `/context`
- `/checkpoint`
- `/undo`
- `/rewind`
- `/redo`
- `/sessions`
- `/resume`
- `/new`
- `/details`
- `/tasks`
- `/attach`
- `/agents`
- `/mcp`
- `/skills`
- `/commands`
- `/history`
- `/prev`
- `/next`
- `/multiline`
- `/editor`
- `/approve`
- `/deny`
- `/cancel`
- `/themes`
- `/diff-style`
- `/keybindings`
- `/scroll-speed`
- `/mouse`
- `/vim`
- `/voice`

退出：

- `/exit`
- `q`

## 5. 使用技巧

### 5.1 想持续协作，就用 `tui --interactive`

`xcode run` 适合单次任务。  
需要多轮讨论、审批、回滚、看任务面板时，用：

```powershell
xcode tui --interactive
```

### 5.2 分析项目时，明确要求“先检查工作区”

虽然 `xcode` 已经会对“分析当前项目”这类请求做一版宿主侧 inspection，但更稳的写法仍然是：

```text
请先检查当前工作区的目录结构、README、配置文件和入口文件，再分析当前项目。
```

### 5.3 用 `@file`、`@dir`、`!command` 提高命中率

如果模型回答过于保守，不要反复解释，直接补上下文：

```text
@package.json @src 根据这些内容分析当前前端结构
```

或：

```text
!git status -- 解释当前仓库改动
```

### 5.4 大段输入用 `/multiline` 或 `/editor`

如果你的提示词很长：

- `/multiline` 进入多行输入
- `/editor` 用外部编辑器写提示词

### 5.5 先让它提出方案，再批准修改

这是比较稳的做法：

1. 先让它分析
2. 再让它说明要改哪些文件
3. 最后批准修改

### 5.6 用 `--file` / `--dir` 做一次性任务

```powershell
xcode run --file .\README.md "根据这个说明写一个首页实现方案"
```

```powershell
xcode run --dir .\src "分析这个目录，并找出首页入口"
```

## 6. 常见使用例子

### 6.1 分析当前项目

```powershell
xcode run "分析当前项目，告诉我技术栈、入口文件、构建方式和主要模块。"
```

### 6.2 解释一个文件

```powershell
xcode run --file .\src\main.js "解释这个文件的职责和执行流程。"
```

### 6.3 根据目录生成重构建议

```powershell
xcode run --dir .\src "分析这个目录结构，并给出一个低风险重构方案。"
```

### 6.4 在 TUI 里改一个组件

```text
@src\components\Header.jsx 把这个头部组件改得更适合营销首页
```

### 6.5 生成提交说明

```powershell
xcode commit-message
```

### 6.6 生成 PR 描述

```powershell
xcode pr-description
```

## 7. 用 xcode 调用 LLM 生成一个简单页面

这里给一个最小、稳定的工作流。

### 7.1 目标

在当前项目里生成一个简单的主页，至少包含：

- 标题
- 副标题
- 一个主按钮
- 一个功能区
- 基本响应式样式

### 7.2 推荐方式：交互式 TUI

先启动：

```powershell
xcode tui --interactive
```

如果仓库里已经有前端代码，先让它分析：

```text
请先检查当前工作区的目录结构、README、前端入口文件和样式入口，再告诉我应该在哪些文件里实现首页。
```

然后再给出明确任务：

```text
请为当前项目实现一个简单的网站主页：
- 保持现有技术栈和代码风格
- 优先复用现有页面入口、布局和样式体系
- 页面包含 Hero 区、功能区、页脚
- 支持移动端
- 修改完成后告诉我改了哪些文件
```

如果它需要更多上下文，可以主动附加：

```text
@README.md 根据产品说明生成首页
```

```text
@src 分析前端结构并实现首页
```

### 7.3 一次性命令方式

```powershell
xcode run "请为当前项目实现一个简单的网站主页。先分析当前仓库的技术栈、前端入口和样式结构，再在正确的页面文件中实现 Hero、功能区和页脚，保持现有代码风格并支持移动端。"
```

如果你已经知道产品定位，建议加上业务描述：

```powershell
xcode run "请为当前项目实现一个面向开发者工具产品的简单主页。先分析现有前端结构，再生成一个包含标题、副标题、CTA 按钮、功能介绍和页脚的响应式首页。"
```

### 7.4 如果你想让结果更稳

把需求写得更具体：

```text
请实现首页，并满足这些要求：
- 主题：开发者工具官网
- 风格：简洁、现代、专业
- 首屏包含主标题、说明文字、两个按钮
- 第二屏展示 3 个功能卡片
- 第三屏展示一个使用流程
- 页脚包含品牌和导航
- 优先改现有入口文件，不要新建无关页面
```

### 7.5 审批和回滚

当 `xcode` 请求修改文件时，你可以在 TUI 中：

- `/approve`：批准
- `/deny`：拒绝
- `/cancel`：取消

如果改完后你不满意：

- `/undo`：撤回上一轮修改
- `/redo`：重新应用

### 7.6 一个完整的最小示例

```powershell
xcode tui --interactive
```

然后输入：

```text
请先检查当前项目的前端目录结构和入口文件，再为这个项目实现一个简单的网站主页。主页需要包含标题、副标题、主按钮、3 个功能卡片和页脚，保持现有技术栈和样式风格，并做好移动端适配。
```

如果项目说明在 README：

```text
@README.md 结合这个说明，实现一个简单的网站主页
```

## 8. 故障排查

### 8.1 只打印快照然后退出

如果你运行：

```powershell
xcode
```

看到的是状态快照并自动退出，改用：

```powershell
xcode tui --interactive
```

### 8.2 模型说“无法访问项目文件”

优先这样做：

- 明确要求它先检查工作区
- 主动附文件或目录
- 用 `!command` 提供目录结构

例如：

```text
@src 分析当前项目
```

或：

```text
!git status -- 结合仓库状态分析当前项目
```

### 8.3 修改被拦住

查看权限：

```powershell
xcode permissions list
```

必要时增加规则：

```powershell
xcode permissions add allow Edit(src/*)
```

### 8.4 想确认当前模型和 provider

在 TUI 里用：

```text
/model
```

或命令行看配置：

```powershell
xcode config show
```

## 9. 相关命令速查

```powershell
xcode tui --interactive
xcode run "<instruction>"
xcode run --file .\README.md "<instruction>"
xcode run --dir .\src "<instruction>"
xcode permissions list
xcode sessions list
xcode session-info latest
xcode export latest
xcode import .\bundle.jsonl
xcode commit-message
xcode pr-description
xcode code-review
```

## 10. 建议的上手顺序

如果你第一次使用，按这个顺序：

1. `xcode --help`
2. `xcode tui --interactive`
3. 输入：`请先检查当前项目，再告诉我它的结构`
4. 用 `@README.md` 或 `@src` 给更多上下文
5. 再让它做一个小改动
6. 用 `/approve` 批准
7. 用 `/undo` / `/redo` 体验回滚

如果你的目标是“用 LLM 帮我做页面”，直接从这句开始就够了：

```text
请先检查当前项目的前端结构，再为当前项目实现一个简单的网站主页，包含标题、副标题、主按钮、功能区和页脚，并保持现有技术栈与代码风格。
```