ai-dev-workspace

AI 开发工作区

你的助手会在由你掌控的 Markdown 文件中记住不同会话之间的工作内容。为开发者提供共享、持久的任务记忆，方便你在 Claude Code、Codex 和其他助手之间切换。

快速开始

连接仓库前先离线试用：ws demo · 5 分钟教程 · Claude Code + Codex 指南 · 移除它

pipx install ai-dev-workspace --pip-args='--pre'  # beta; omit --pip-args after a stable release
cd ~/code/myapp && ws start

没有 pipx？运行 brew install pipx，或运行 python3 -m venv ~/.ws && ~/.ws/bin/pip install --pre ai-dev-workspace；在运行 ws start 前，将其 bin 目录加入 PATH。

更喜欢 Claude Code 插件？可预览。目前尚未列入 Anthropic 官方插件目录；请从我们的 GitHub 市场安装：

/plugin marketplace add Alenroyfeild/ai-dev-workspace
/plugin install ai-dev-workspace@ai-dev-workspace

已在 beta.5（2026-10-22）上实时检查。参见插件预览。

ws start 会预览每个文件，并且只有在你确认后才会写入。生成的助手钩子和配置保留在本地（.git/info/exclude），任务记忆存放在仓库之外的 ~/.ai-dev-workspace/<repo-name> 中，ws start --undo 则可彻底移除仓库配置。

观看视频（0.1.0b6 版）

• 观看 2 分钟讲解视频
• 深入了解：真实命令，真实输出
• 功能短片：切换助手 · 继续下一步 · 失败路径 · 技能 · 团队工作区（预览） · 防护机制 · 助手 · 作为插件安装（预览）
• 早期版本：0.1.0b5

使用场景

• 在任务中途切换 Claude Code ↔ Codex： 在 Claude Code 中开始任务并保存检查点，然后在 Codex 中使用完全相同的任务说明和任务记忆继续工作（指南）。
• 第二天继续工作，无需重新解释： 在会话开始时，将进行中的任务、近期决策和阻碍因素直接注入上下文（教程）。
• 停止重复尝试失败方案： 每个新会话的任务说明中都会在 Do not redo: 下列出失败路径（指南）。
• 保留已确认的修正： 使用 ws remember 记录决策或约束，让新会话遵循先前的裁定（命令）。
• 阻止危险命令和信息泄露： 可选启用的 guards 套件会拒绝危险的 shell 操作，以及命令或写入文件中的机密信息（套件）。
• 与团队共享领域笔记（预览）： 通过私有 git 仓库共享已批准的知识，并提供基于同意的预览（团队）。

示例

Session 1 — You: “Empty email returns missing_email; leave signup unchanged.”
Assistant: “I’ll trace login and keep the decision with this task.”
You: “Save a checkpoint and stop here.”

Session 2 — You: “Continue the login fix.”
Assistant: “The saved note says return missing_email and leave signup unchanged.”
You: “Yes, continue.”

功能

功能	状态	功能说明	文档链接
会话摘要	稳定	在会话开始时注入范围受限的任务记忆、决策和阻碍事项	概览
决策与交接	稳定	保存状态、下一步操作和明确裁定（ws checkpoint、ws remember）	命令
失败尝试	稳定	记录失败的方法，并以 Do not redo: 显示	概念
经验	稳定	记录可跨任务复用的心得和指导（ws lesson）	命令
ws lesson review	稳定	只读列出日期较早的经验（--days N）；不会更改或删除任何内容	命令
MCP 服务	稳定	默认通过 stdio 提供 7 个核心工具；其他工具可按名称请求	MCP
防护包	稳定	PreToolUse 钩子会在执行前拒绝有风险的命令和机密；beta.7 可解析 git push 选项语法（缩写、--prune、--mirror）；这是安全网，而非安全边界	软件包
规范包	稳定	同一会话中相同命令反复失败时提供提醒	软件包
ws digest	稳定	将冗长的终端输出压缩为重点明确的 Markdown 笔记	命令
原生导入	稳定	读取现有的 Claude 和 Codex 记忆文件（ws import native）	命令
ws import claude-mem	预览	已通过测试夹具验证的 SQLite 副本导入；较新的上游架构可能无法导入	高级用法
ws audit	稳定	根据范围受限的本地清单提供只读的技术栈／接线建议；无需登录，也不证明客户端正在运行	命令
ws demo	稳定	创建隔离的沙盒仓库，以安全地测试命令	教程
Claude Code 插件	预览	钩子 + MCP；需要 CLI + ws start；未收录在 Anthropic 目录中；未经 Windows 测试	高级用法
Codex 插件	预览	钩子需要通过可信的手动方式安装到桌面；不支持 MCP；钩子未经实际运行测试	高级用法
Cursor 插件	预览	仅通过测试夹具验证；尚未提交；没有经过验证的安装命令	高级用法
Codex SessionStart 补全	预览	为已认领的任务恢复已更改的转录内容；已通过测试夹具验证，但未经 Codex 恢复会话的实际测试	高级用法
MCP 插件根目录发现	预览	插件服务可根据客户端根目录查找 ws start 仓库；Codex 不提供根目录	高级用法
Worker 回退链	预览	仅运行已声明的提供方和只读角色；超时视为尝试失败	高级用法
网关提供方	预览	仅通过本地假服务进行测试；向配置的 base_url 发送经过脱敏的摘要，不包含工具	高级用法
精简 MCP 回忆	稳定	提供范围受限的笔记卡片和明确标记为不可信的详细内容；CLI 代码片段保持不变	高级用法
经验晋升	稳定	根据重复笔记的相似度提出草稿；不会自动安装规则	高级用法
digest_file MCP 工具	预览	可选的纯大小建议；提供范围限定的文件摘要，不会自动压缩	软件包
行为包	稳定	可选的工程指南；仅提供建议，不执行强制约束，也不会学习会话模式	软件包
Skills 打包	稳定	已检查格式；未经验证的第三方安装程序；仍需要 CLI 和设置步骤	Skills
团队共享	预览	基于私有 git 的知识库，支持基于同意的拉取和预览	团队
MCP Registry	预览	预配置的 server.json 目录条目，用于 MCP 客户端发现	MCP

工作原理

Claude Code / Codex / Cursor / Copilot / Gemini / Antigravity
        │ (session startup & capture hooks)
        ▼
~/.ai-dev-workspace/<repo-name>/           (private, outside repo)
  ├── workspace.json                       (settings, active task, packs)
  └── vault/
      ├── Tasks/<id>.md                    (status, next action, decisions, blockers)
      └── Learnings.md                     (reusable cross-task lessons & dead ends)
        ▲
        │ (MCP stdio connection: 7 core tools by default; others by name)
  Local Assistant (MCP client)

记忆存储不会在后台调用模型。ws delegate --run 只会启动已声明的助手 CLI，或将经过脱敏的简报发送到明确配置的网关；输出未经验证。任务记忆是由你掌控的纯 Markdown。

结果

在独立的配对调查中测得，详见 bench/README.md（Codex gpt-6-luna，每个组 n=5）：

组别	通过（October 11）	通过（October 10）
全新基线（无记忆）	0/5	0/5
工作区（自动简报）	2/5	1/5
纯 Markdown 交接	5/5	4/5

最新的受控测试显示，纯 Markdown 交接优于工作区（分别为 5/5 和 4/5，对比 2/5 和 1/5），而自动捕获的发布门槛仍未达到。工作区的优势在于结构化、支持跨助手交接，以及避免手动管理文件。详情和早期测试结果请参阅：bench/README.md 和 docs/MEASUREMENTS.md。

对比

• 内置记忆文件（CLAUDE.md、AGENTS.md）： 为每个助手提供纯指令；ai-dev-workspace 增加了跨助手交接、活动任务状态，以及 Do not redo: 约束。
• 纯 HANDOFF.md： 适用于手动记录（并且在最新基准测试组中优于工作区自动捕获：5/5 对比 2/5）；ai-dev-workspace 增加了跨助手自动化、结构化简报注入和过时警告。
• claude-mem： 通过钩子捕获工具使用情况，并借助 AI 将其压缩到 SQLite + 向量搜索中（上游文档），无需显式命令即可自动捕获记忆；ai-dev-workspace 保留由你掌控的显式 Markdown，不会在后台调用模型来处理记忆（显式委派可调用已声明的 CLI 或已配置的网关），并专注于提供包含后续步骤和死路的持久交接（指南）。

兼容性

助手	状态	测试证明
Claude Code	支持，已在 macOS 上进行实时测试	通过 CI 测试
Codex	支持，已在 macOS 上进行实时测试	通过 CI 测试
Cursor	支持，已通过 fixture 测试；欢迎提供实时测试报告	通过 CI 测试
Copilot（VS Code）	支持，已通过 fixture 测试；欢迎提供实时测试报告	通过 CI 测试
Gemini CLI	支持，已通过 fixture 测试；欢迎提供实时测试报告	通过 CI 测试
Antigravity	预览版，已通过 fixture 测试；支持 rules、MCP、SessionStart/PreToolUse 钩子；无自动捕获	通过 CI 测试

使用 Cursor、Copilot（VS Code）、Gemini CLI 或 Antigravity 的测试人员，请通过 反馈故障 分享遇到的问题。

已知限制

• 客户端覆盖范围： Claude Code 和 Codex 已在 macOS 上进行实时测试；Linux 和 Windows 仅通过 CI 测试。Cursor、Copilot（VS Code）、Gemini CLI 和 Antigravity 已通过 fixture 测试。
• 捕获尽力而为： 显式 CLI 命令（ws remember、ws checkpoint）具有确定性；自动捕获转录内容中的提示词则尽力而为。
• 防护措施只是安全网： 模式匹配会阻止命令或写入文件中的常见风险命令和机密信息，但并非无法绕过的安全边界。
• 团队共享： 已在一台 Mac 上通过本地 HTTPS Git 服务测试多用户工作流：三个独立配置文件、双向共享，以及生成的 Claude Code 和 Codex 钩子输出。托管式 GitHub 检查和实时助手会话仍待完成。（路线图）

隐私与安全

• **默认私密：**记忆存储在代码检出路径之外的 ~/.ai-dev-workspace/<repo-name> 中。团队共享需要显式创建私有仓库（ws team init），并手动确认。
• 尽力进行脱敏：ws 会屏蔽已知的 API 密钥、令牌和私密片段（<private>...</private>），但基于正则表达式的脱敏仅能尽力而为，不能取代良好的操作性密钥管理习惯。
• 防护措施是安全网：guards PreToolUse 钩子会拦截命令或写入文件中的已知高风险 shell 模式和密钥，但它只是安全网，并非无法绕过的安全边界。

后续计划

• **通用 Agent 插件清单（PLG3）：**已搁置，在 Codex 能够加载根清单且不丢失插件钩子之前不可用。
• **通过 roots 使用 Codex 插件 MCP（PLG5）：**已搁置，Codex 暂不可用；codex-cli 0.155.1 不提供 roots，也无法展开插件 MCP 路径，因此请使用 ws start 来运行 MCP。支持 roots 的客户端可使用 beta.7 预览版。

文档

• 入门：5 分钟教程 · 设置指南 · 演示教程 · 跨客户端指南
• 使用：CLI 命令 · 套件目录 · 技能分发 · MCP 服务 · 高级用法
• 指南：无需后台 AI 保留决策 · 停止重试无效方案
• 团队：团队使用 · 团队工作区设置
• 参考：概览 · 架构 · 基准测量 · 客户端验证 · Windows 支持 · 路线图

状态与贡献

ai-dev-workspace 处于公开测试阶段（PyPI 上的 v0.1.0-beta.7）。计划中的改进记录在路线图中。欢迎通过问题反馈提交错误报告和反馈。

基于 MIT License 发布。