wsctl

一个用于 AI 开发工作区的通用管理原型：

• 用 .wsctl/ 保存 Git 友好的 Markdown/YAML 管理数据；

• 用 Python 包和 CLI 提供统一服务；

• 用 MCP 让支持 MCP 的 AI 开发工具发现和调用；

• 用 SQLite/FTS5 做本地检索索引，索引可随时重建；

• 不内置构建、测试、部署或烧写逻辑。

当前版本是外部实验原型，用来验证通用管理面能否适配现有工作流。

快速开始

python3 -m pip install -e '.[mcp]'

wsctl init /tmp/my-project
wsctl --root /tmp/my-project workspace add /tmp/my-project --allow-write
wsctl --root /tmp/my-project projects create demo --name "Demo Project"
wsctl --root /tmp/my-project create task \
  --title "写下第一条通用任务" \
  --project demo \
  --tag preview
wsctl --root /tmp/my-project list task --json
wsctl --root /tmp/my-project context --project demo --query 任务 --json

Related MCP server: sourcebook

适配现有工作区

原型提供了一个只读预览命令，把旧工作区映射到新的 .wsctl/：

wsctl legacy preview \
  --source /path/to/old-workspace \
  --out /path/to/preview-workspace \
  --project my-project

它不会修改旧工作区。项目、知识、决策和证据会写入预览目录的 .wsctl/，并抽取一个演示任务用于验证任务上下文。

MCP

wsctl-mcp --list-tools
wsctl-mcp --workspace /path/to/preview-workspace

默认所有工作区只读；写入需要在注册时显式开启：

wsctl workspace add /path/to/project --allow-write

接入当前 Buildroot 工作区

外部原型可以给现有 Buildroot 工作区增加一组只读/计划型 MCP 工具：

wsctl-mcp \
  --legacy-workspace /path/to/buildroot-workspace-framework \
  --list-tools

这些工具通过当前仓库已有的 wsctl 源码读取真实事实，不修改当前仓库：

• legacy_doctor

• legacy_project_list

• legacy_project_context

• legacy_source_status

• legacy_branch_status

• legacy_worktree_status

• legacy_history

• legacy_knowledge_list

• legacy_knowledge_verify

• legacy_agent_status

• legacy_build_plan

• legacy_test_plan

• legacy_deploy_plan

• legacy_release_show

构建、测试、部署只生成计划，不执行。legacy_deploy_plan 会只读探测板卡运行槽。

Codex/Claude 等 MCP 客户端的配置值示例：

{
  "command": "/home/cj/Tech/wsctl/.venv/bin/wsctl-mcp",
  "args": [
    "--legacy-workspace",
    "/home/cj/buildroot-workspace-framework"
  ]
}

也可以直接生成宿主配置片段：

wsctl setup mcp --host codex \
  --legacy-workspace /path/to/buildroot-workspace-framework

该命令只输出配置，不修改用户配置。Codex 片段包含：

default_tools_approval_mode = "approve"

这只适用于当前只暴露只读/计划工具的 legacy-only MCP server。以后如果同时暴露写入或执行工具，应按工具单独设置审批模式。

当前边界

包含：

• workspace 注册表；

• project/task/knowledge/decision/evidence；

• context 与全文检索；

• CLI 和 MCP；

• wsctl init 与 legacy preview。

不包含：

• 构建、测试、部署、烧写；

• 外部 SaaS 同步；

• 远程 HTTP 服务；

• 多用户权限系统；

• 自动 Git commit。