Human-AI Workspace

简体中文 | English

一个面向非技术用户（小白）的 AI 与人类项目协作方案。

很多人知道自己想让 AI 做什么，却看不懂项目里的代码、配置、测试和日志。这不应该妨碍人使用 AI 创建和维护真正的项目。

Human-AI Workspace 把项目分成两个清晰的协作空间：

• for_human：只放需要人与 AI 共同理解、确认和决策的内容，全部用大白话表达。
• for_ai：放项目本体、源代码、测试、配置、技术文档和验证证据，由 AI 负责理解和维护。

它的目标不是把技术做成无人能审计的黑箱，而是让 AI 主动把重要的进度、风险、选择和验证结果翻译成人能够理解的信息。

它解决什么问题

使用 AI 做项目时，非技术用户经常遇到这些困难：

• 不知道项目现在究竟完成到哪一步；
• AI 说“完成了”，但不知道有没有真正测试；
• 技术选项太多，不知道应该选 API、SDK、MCP 还是 CLI；
• AI 问了很多专业问题，却不知道哪些必须由自己决定；
• 重要决定散落在聊天记录中，换一次会话或模型就容易丢失；
• 项目代码越来越多，但人类能够理解和掌控的信息越来越少。

这个模板为项目建立一个稳定的“人类协作界面”，让人不必读懂全部代码，也能知道：

• 这个项目要解决什么问题；
• 目前能做什么、不能做什么；
• 已经完成和验证了什么；
• 还有哪些事情没有完成；
• 哪些问题需要自己决定；
• AI 为什么认为项目已经达到可用状态。

目录结构

项目目录/
├── .gitignore
├── AGENTS.md
├── for_human/
│   ├── PROJECT.md
│   ├── STATUS.md
│   └── DECISIONS.md
└── for_ai/
    ├── AGENTS.md
    ├── src/
    ├── tests/
    └── ...

for_human 按人类查看信息的目的拆成三个文件：

• PROJECT.md：项目是什么、使用场景是什么、最终希望得到什么；
• STATUS.md：现在能做什么、完成到哪里、验证到什么程度；
• DECISIONS.md：哪些事项需要人决定，以及以前已经决定了什么。

初始模板只保留五个必要的协作入口文件，并尽量使用短句，以减少模型上下文占用；验收标准放在 PROJECT.md，当前验收结果放在 STATUS.md，详细技术证据留在 for_ai。

人和 AI 如何分工

人类负责

• 说明最终想实现的目标和真实使用场景；
• 决定自己的偏好、成本、风险容忍和权限边界；
• 授权本地写入、外部发布、生产修改等重要操作；
• 根据实际使用体验做最终验收。

AI 负责

• 阅读代码、资料和实际环境；
• 比较技术方案并选择综合最优实现；
• 自行补全必要的安全边界、测试和专业验收标准；
• 对纯技术问题作出专业判断，不把裸技术名词推给用户选择；
• 把影响用户的风险和取舍翻译成大白话；
• 用测试和可复核证据证明结果，而不是只宣称“已完成”。

核心协作原则

1. 目标由人提出，技术实现由 AI 负责。
2. 纯技术问题由 AI 调查和选择；会影响体验、成本、风险或权限的事情，由 AI 解释并给出建议后让人决定。
3. AI 应主动发现人没有想到的重要需求，但只询问可能实质改变项目的高信息增益问题。
4. for_human 必须保持大白话，不能变成日志、代码和术语的堆放处。
5. AI 不能没有证据就宣布完成；专业验收由 AI 负责证明，最终用户验收由人负责。
6. 创建本地工作区必须由用户明确授权，不能因为一次普通聊天而自动生成文件。

立即试用模板

需要 Node.js 20 或更高版本，以及已经配置 user.name 和 user.email 的 Git。先安装 CLI：

npm install --global human-ai-workspace-cli

设置工作总目录环境变量。CLI 不会猜测或自动创建总目录；未设置、目录不存在或不是绝对路径时会拒绝下载：

[Environment]::SetEnvironmentVariable(
    "HUMAN_AI_WORKSPACE_ROOT",
    "D:\ZM\qwenpaw_job",
    "User"
)

重新打开终端或 AI Agent 后，只需运行：

haiw "项目名称"

CLI 会按本机日期创建：

D:\ZM\qwenpaw_job\YYYY-MM-DD_项目名称

它使用固定模板版本 template-v0.2.0，校验文件清单和 SHA-256，不覆盖已有目录。创建时会在工作区根目录初始化 main 分支，暂存模板文件并生成初始提交：

chore: initialize Human-AI Workspace

根目录 .gitignore 只预置一条 Human-AI Workspace 通用规则：for_human 任意层级只有 Markdown 文件会被 Git 跟踪；其他位置默认可被跟踪，具体项目可以继续补充自己的忽略规则。CLI 不会修改 Git 的全局或仓库配置；下载、校验、Git 初始化或初始提交失败时，不会留下正式工作区。

创建完成后，让 AI 打开新目录并先读取根目录 AGENTS.md。

当前阶段

这是项目的第一个中文模板版本，当前重点是验证：

• for_human 与 for_ai 的双层结构是否真正降低理解门槛；
• 不同 AI Agent 能否遵循同一套协作方式；
• 人类可读状态是否能长期与真实实现保持一致；
• 哪些内容应该成为稳定模板，哪些应该由具体项目自行生成。

后续计划

• 根据真实使用反馈继续改进 CLI；
• 增加适合不同项目规模的模板变体；
• 根据需要提供 Cloudflare Streamable HTTP MCP 入口；
• 增加跨 Agent 的使用示例和协作评测。

反馈与参与

这个项目面向不想先成为程序员、也希望真正掌控 AI 项目的普通用户。欢迎通过 Issue 分享：

• 哪些内容依然看不懂；
• 哪些问题 AI 应该主动询问；
• 哪些状态最值得放进 for_human；
• 你使用不同 AI Agent 时遇到的兼容问题。

开源许可

本项目采用 MIT License 开源许可。