windcode 0.1.0

A safe, extensible terminal coding agent

Windcode

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

功能

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

快速开始

环境要求：Linux、Python 3.12+、uv。bubblewrap 可选。

从 PyPI 安装命令行工具：

uv tool install windcode
windcode /path/to/project

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

uv pip install windcode

从源码运行：

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

最小模型配置：

primary_provider = "primary"

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

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

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

常用启动参数：

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

常用命令

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

MCP Server

[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 统一存放在选定的状态根下：

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

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

开发

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

构建与发布

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

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 验证：

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：

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

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

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

License

Apache-2.0