Metadata-Version: 2.4
Name: windcode
Version: 0.1.0
Summary: A safe, extensible terminal coding agent
Project-URL: Homepage, https://github.com/tingfeng347/windcode
Project-URL: Repository, https://github.com/tingfeng347/windcode
Project-URL: Issues, https://github.com/tingfeng347/windcode/issues
Author: Tingfeng347
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,cli,coding-assistant,mcp,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.12.0
Requires-Dist: anthropic[aiohttp]>=0.98.0
Requires-Dist: httpx<1,>=0.28.0
Requires-Dist: jsonschema<5,>=4.25.0
Requires-Dist: mcp<2,>=1.10.0
Requires-Dist: openai[aiohttp]>=2.34.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pyyaml<7,>=6.0.2
Requires-Dist: textual>=6.0.0
Requires-Dist: tomli-w>=1.2.0
Description-Content-Type: text/markdown

# Windcode

Windcode 是一个Coding Agent。它可以在本地
工作区中读取和修改代码、执行命令、运行测试、恢复会话，并通过权限策略与 Linux 沙箱控制
高风险操作。

![alt text](assets/image.png)
![alt text](assets/image1.png)
![alt text](assets/image2.png)
![alt text](assets/image3.png)
![alt text](assets/image4.png)

## 功能

- Textual 终端工作台与 Python SDK
- Anthropic Messages、OpenAI Responses 和 OpenAI-compatible 模型协议
- 流式输出、工具调用、审批、取消、重试与显式模型回退
- 会话恢复、历史回退、上下文压缩和本地 trace
- 多子智能体并行执行与独立 Worktree
- 项目级长期记忆：用户画像、项目事实、经验、SOP 与主动查询
- MCP Server、Skills、Hooks 和本地插件扩展
- 四种权限模式与可选 bubblewrap 沙箱


## 快速开始

环境要求：Linux、Python 3.12+、[uv](https://docs.astral.sh/uv/)。bubblewrap 可选。

从 PyPI 安装命令行工具：

```bash
uv tool install windcode
windcode /path/to/project
```

也可以安装到当前 Python 环境：

```bash
uv pip install windcode
```

从源码运行：

```bash
uv sync --frozen --all-groups
cp .windcode/config.toml.example .windcode/config.toml
uv run windcode /path/to/project
```

最小模型配置：

```toml
primary_provider = "primary"

[providers.primary]
protocol = "openai_compatible"
model = "your-model"
base_url = "https://example.com/v1"
api_key_env = "MODEL_API_KEY"
```

密钥应通过环境变量或 Windcode 凭据存储提供，不要写入项目配置。

```bash
export MODEL_API_KEY="..."
uv run windcode .
```

常用启动参数：

```text
--config FILE
--model PROVIDER_OR_MODEL
--resume SESSION_ID
--permission-mode plan|default|accept_edits|full_access
--sandbox / --no-sandbox
```

## 常用命令

```text
/new                         新建会话
/resume [SESSION_ID]         恢复会话
/history                     查看历史节点
/rewind RECORD_ID            回退到历史记录
/model                       管理模型与 Provider
/mode MODE                   切换权限模式
/memory                      管理长期记忆
/extensions                  管理扩展
/compact                     压缩当前上下文
/agents                      查看子智能体
/status                      查看运行状态
```

## MCP Server

```toml
[extensions]
enabled = true

[extensions.mcp_servers.example]
transport = "streamable_http"
url = "https://example.com/mcp"
enable = true
required = false
```

`enable = false` 的服务器不会连接、不会参与工具搜索，也不会注入模型上下文。`required` 只在
服务器启用时表示启动阶段必须连接成功。

## 本地状态

Windcode 将记忆、会话、trace、扩展状态和 Worktree 统一存放在选定的状态根下：

```toml
[storage]
project_state_root = ".windcode/state"
user_storage_root = "~/.local/state/windcode/state"
```

配置项目状态根时优先使用项目目录；未配置时使用用户状态目录。`.windcode/config.toml` 和
`.windcode/state/` 都不应提交到 Git。

## 开发

```bash
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -q
uv build
```

## 构建与发布

发布前更新 `pyproject.toml` 和 `src/windcode/__init__.py` 中的版本号，并完成完整检查：

```bash
uv sync --frozen --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -q
uv build --no-sources
```

可以先发布到 TestPyPI 验证：

```bash
uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --token "$TEST_PYPI_TOKEN"
```

正式版本通过 GitHub Release 自动发布：创建与项目版本一致的标签，例如 `v0.1.0`，然后发布
GitHub Release。`.github/workflows/publish.yml` 会验证标签、运行测试、构建发行包，并使用
PyPI Trusted Publishing 发布。首次发布前需要在 PyPI 配置以下 Trusted Publisher：

```text
Owner: tingfeng347
Repository: windcode
Workflow: publish.yml
Environment: pypi
```

PyPI 不允许覆盖已经发布的同名版本；重新发布前必须增加版本号。

生产代码位于 `src/windcode/`。本地 `tests/` 与 `spec/` 目录由 Git 忽略，仅用于开发和规格管理。

## License

[Apache-2.0](LICENSE)
