为 Agent 设计的项目结构
One wok, any stack.

npm、Cargo、Go 都把某一种语言的工程放在仓库顶层。Agent 会同时在多种技术栈之间工作，没有明确规则时会到处建文件，仓库很快就乱了。Wokspace 让顶层变成工作区，给每个文件一个确定的位置。

curl -fsSL https://raw.githubusercontent.com/XiaoXianThis/wokspace/main/apps/site/public/install.sh | sh

irm https://raw.githubusercontent.com/XiaoXianThis/wokspace/main/apps/site/public/install.ps1 | iex

安装脚本会校验 SHA-256。也可以从 Releases 页面直接下载各平台的二进制文件。

顶层是工作区，不是工程

AGENTS.md        所有 Agent 首先读取的规则
apps/            独立的子项目，各自使用自己语言的原生结构
build/           最终构建产物（不提交）
docs/            长期有效的事实：架构、决策、指南、接口契约
work/            其余一切：spec、脚本、测试、素材、基础设施、临时区

根目录冻结

只提交 3 个文件和 4 个目录。白名单式的 .gitignore 把其他东西挡在 git 之外，包括 .cursor/、.kiro/、.claude/。

骨架冻结

所有目录从第一天起就存在，每个目录都有写明规则的 README。Agent 写文件之前就知道该放哪里。

多技术栈并存

apps/ 里每个 app 都是普通的 Go、Rust、Node、Python、.NET 或 Java 工程，互不引用源码。

不依赖工具也能运转

规则是纯 Markdown。wok 只是加速器：创建项目、在根目录运行任务、检查规则。

约定优于配置

没有配置文件。任务命令写在每个 app 的 AGENTS.md 里，留空就自动识别。

三个平台都能用

命名规则、换行符和命令都按 Windows、macOS、Linux 通用的标准来定。

快速开始

wok init my-project          # 生成完整骨架，并执行 git init
cd my-project
wok new web                  # 生成 apps/web/AGENTS.md，并登记到 apps/README.md
cd apps/web
npm create vite@latest .
cd ../..
wok dev web                  # 在 apps/web/ 中执行 npm run dev

也可以直接告诉 Agent："用 Vite 建一个 web 应用。" AGENTS.md 的规则会让它执行 wok new web，在 apps/web/ 里初始化工程，填写任务表，并在结束前执行 wok check。

命令

wok init [dir]                 # 创建 wokspace；--existing 向非空目录补充缺失的文件
wok new <app>                  # 创建 apps/<app>/ 及其 AGENTS.md
wok dev [app...]               # 启动 app；多个 app 并行运行，输出带标签
wok build [app...] [--all]     # 构建 app，产物输出到 build/<app>/
wok test [app...] [--all]      # 测试 app
wok install [app...] [--all]   # 安装 app 的依赖
wok run <app> <task> [-- args] # 运行任意任务
wok ls [app]                   # 列出 app 以及每个任务背后的命令
wok check                      # 按 AGENTS.md 检查目录结构

在 wokspace 内的任何目录都能使用 wok。在 apps/<app>/ 里时，可以省略 app 名。

任务：约定优先，必要时再配置

每个 app 的 AGENTS.md 里有一张任务表，人、Agent 和 wok 都读这张表。命令留空表示使用 wok 自动识别的命令，wok ls 会显示最终结果和每条命令的来源。

| task    | command                                              | windows |
|---------|------------------------------------------------------|---------|
| install |                                                      |         |
| dev     |                                                      |         |
| test    | cargo test --all-features                            |         |
| build   | cargo build --release && cp target/release/api "$WOK_OUT" | cargo build --release && copy target\release\api.exe "$WOK_OUT" |

自动识别

工程文件	install	dev	test	build
`package.json` 按 lock 文件选择 npm、pnpm、yarn 或 bun	`<pm> install`	`<pm> run dev`	`<pm> run test`	`<pm> run build`
`deno.json`	`deno install`	`deno task dev`	`deno task test`	`deno task build`
`Cargo.toml`	`cargo fetch`	`cargo run`	`cargo test`	`cargo build --release`
`go.mod`	`go mod download`	`go run .`	`go test ./...`	`go build -o "$WOK_OUT" .`
`.sln` `.csproj` `*.fsproj`	`dotnet restore`	`dotnet run`	`dotnet test`	`dotnet publish -c Release -o "$WOK_OUT"`
`gradlew` `build.gradle(.kts)`			`gradlew test`	`gradlew build`
`pom.xml`	`mvn dependency:resolve`		`mvn test`	`mvn package`
`pyproject.toml` + `uv.lock`	`uv sync`		`uv run pytest`	`uv build --out-dir "$WOK_OUT"`
`pyproject.toml` + `poetry.lock`	`poetry install`		`poetry run pytest`	`poetry build`

package.json 的每个 script 和 deno.json 的每个 task 也会自动成为任务，所以不写表也能直接 wok run web lint。

命令在 app 目录中执行：macOS 和 Linux 通过 sh，Windows 通过 cmd。执行前，wok 会在所有平台上替换 $WOK_ROOT、$WOK_APP 和 $WOK_OUT（该 app 的 build/<app>/ 目录），同时把它们设为环境变量。

和各家 Agent 共处

AGENTS.md 是唯一提交到仓库的规则入口。Kiro、Codex、Cursor、GitHub Copilot 等工具会直接读取它。Claude Code 需要在本地建一个 CLAUDE.md，内容只有一行 @AGENTS.md。

各家 Agent 的专属目录都不进 git。团队需要共享的配置（MCP、hooks 等）以标准版本放在 work/agent/configs/，每个人复制到本地。Kiro 的 spec 可以把 .kiro/specs 链接到 work/specs/，Windows 上用目录联接，不需要管理员权限。

完整规则见 AGENTS.md，设计取舍见决策记录。

为 Agent 设计的项目结构One wok, any stack.