用 CleanCode 把每个需求变成一张可运行的开发画布：分支工作区、依赖连线与 Agent 协作实操

从 GitHub Releases 取对应平台的安装包：macOS 是同时支持 Apple Silicon 与 Intel 的 Universal 包，Windows 是 x64 的 NSIS 安装程序，Linux 提供 x64 的 AppImage 与 DEB。macOS 因为还没有完成开发者签名与公证，初次打开会被系统拦下。

# 从 GitHub Releases 取对应平台安装包，并用同一次发布里的 SHA256SUMS.txt 核对

# macOS：未过 Developer ID 签名与公证，初次打开会被拦
xattr -dr com.apple.quarantine /Applications/CleanCode.app
open /Applications/CleanCode.app

这一步里最不该跳的是校验。移除隔离属性的命令必须精确指向那个 app 包本身，不要换成 /Applications、下载目录或家目录这种宽路径——那样等于把整层的门禁一起拆了。更稳的替代做法是按苹果官方说明，在「系统设置 → 隐私与安全性」里选择「仍然打开」。想跑源码则需要 Node.js 24 及以上与 pnpm 10，检查命令也一并准备好。

# 从源码运行（仅开发与贡献时需要）
git clone https://github.com/chen-985211/cleancode.git
cd cleancode
pnpm install
pnpm dev

pnpm typecheck     # 类型检查
pnpm test          # 测试
pnpm dist:mac      # 也可 dist:win / dist:linux，产物写入 release/

给某个特性分支建一个工作区，它做的不是切一次分支，而是开一套独立上下文：自己的 Git worktree、自己的画布、终端、执行范围与 Agent 会话。于是几个需求可以同时推进，不必挤在同一份终端历史与服务状态里；切回任何一个工作区，终端输出还在，Agent 上下文还在，工作目录也没挪过位置。

feature/auth（独立 worktree）
├── Coding Agent
└── 可执行工作流
    └── 安装依赖 ──> API 服务 ──> Web 应用 └─> 测试

每个物理工作区分别保存：画布、终端会话、Agent 会话

两件事要记牢。其一，归档一个干净的工作区会移除 worktree 但保留 Git 分支，所以归档前先把未提交的改动处理掉。其二，它明确不负责 Git 合并、变基、冲突解决、分支删除与远程仓库托管——这些继续用你原来的 Git 工具，别指望画布替你解决冲突。另外它还支持浏览、搜索与筛选 GitHub Issues 并为某个 Issue 开一个关联工作区，但这条路需要本机已经安装并登录 GitHub CLI，且当前只支持 github.com。

开发环境的崩溃点通常不在命令本身，而在顺序与条件没被环境记住：先装依赖，等服务真的就绪，再起前端，最后跑测试。这些细节散落在 README、脚本注释、终端历史与人的记忆里，切一次分支就得重新核一遍。在画布上它们变成可执行的工作流：终端块跑真实的构建、测试与开发服务器，有向连线声明真实依赖。

执行语义（记住这五条就够用了）

1) 没有上游依赖的任务可以并行启动
2) 下游任务等到它每一个直接依赖都完成或就绪才启动
3) 有限任务按退出码判定成功或失败
4) 长跑服务在匹配到指定输出文本或打开 TCP 监听后转为就绪
5) 上游失败会显式阻塞它的所有下游

就绪判定这一条最实用：长跑服务不是靠等一段固定时间来判断的，而是靠「输出里出现某段文字」或者「端口真的开始监听」，所以依赖它的下游不会抢跑。反过来，某个构建失败会沿着连线把下游全部挡住，而不是让它们带着半成品继续跑。画布上还能把终端堆叠、折叠成组合或排成网格，组合只做视觉组织，不是工作流节点。

两个分支都要起同一个开发服务时，端口冲突是最烦人的那类问题。它的处理办法是让运行时分配并把最终端点注入回去，注入通道只走项目现有启动路径已经读取的环境变量，或者现有 CLI 已经接受的安全占位后缀——不允许为了支持动态端口去改你的源码或项目配置。画布上会显示实际地址，不用自己去翻日志。

端口策略怎么选

fixed      端口不可变；只有项目契约明确要求时才用
preferred  惯用端口优先，被占用时另分配
auto       由运行时分配并注入最终端点

注入方式：启动环境变量，或命令参数里的安全端口占位
选择约束：只能挑项目现有启动路径已经在读的环境变量
约束补充：动态策略不能搭配不注入的做法

默认的经验法则很朴素：存在惯用端口时用优先策略并保证注入，没有惯用端口时用自动加注入，只有在用户或项目契约明确要求端口不可变化时才用固定。另外一条容易被忽略——环境变量注入只能选项目现有启动路径已经在读的那些，参数注入只能选现有 CLI 或任务包装器已经接受的后缀。

支持这一能力的 Agent 会被注入一个本机 HTTP JSON-RPC 服务，不需要你手写任何配置：应用按 Provider 生成启动级的配置或临时文件，令牌一律通过环境变量引用，临时文件里不得出现明文。默认开启，开关在应用设置里独立的 CleanCode MCP 页面，按「终端画布」与「Agent 协作」两类整体启用，没有单工具开关。

CleanCode MCP 的端点形态（由应用注入，不需要你手写）

http://127.0.0.1:随机端口/mcp/会话ID

只监听回环地址；每次注册生成一个 24 字节随机的 base64url Bearer Token
只接受 POST，Authorization 必须精确等于 Bearer 令牌
非 POST -> 405   未知会话 -> 404   鉴权失败 -> 401   请求体超过 1 MiB -> 413

工具总数 21：终端画布 16 个 + Agent 协作 5 个

于是你可以直接说「读一下当前项目，帮我把安装依赖、起服务、跑检查连成一条流程」：Agent 先用 inspect_graph 看现状，再用 create_terminal_workflow 一次把终端与连线建好，还能用 inspect_terminal_workflow_plan 在不启动任何进程的前提下校验拓扑。协作那五个工具则让 Agent 之间能列出彼此、发消息与等待回复，消息种类分为任务、提问、进展与结果。

三处边界值得先告诉团队。其一，删除积木、解散组合与断开依赖这三个破坏性工具需要画布上的独立审批，Provider 的预批准只避免了命令行自己重复询问，绕不过应用层的审批。其二，启动、查询与停止工作流的工具还没有实现，所以 Agent 只能说「已经搭好」，不能声称工作流已经跑起来了。其三，端口与执行配置只是持久化的意图，工具并不能分配端口、启动终端或返回真实端点。

复用这一层是这个工具真正的复利所在：一套验证过的画布流程，下次建工作区时自动出现，不用再靠记忆重建。可以存成项目模板或全局收藏，可以加进快捷执行栏用快捷键启动，也可以给项目设默认 Agent 与终端模板，让新建工作区时自动带上，需要的话再打开模板自动运行。

把跑通的东西变成资产

1) 收藏为项目模板或全局收藏
2) 加进快捷执行栏，用快捷键启动常用任务
3) 给项目设默认 Agent 与终端模板，新建工作区时自动带上
4) 需要时打开「模板自动运行」
5) 从 GitHub Issue 直接开一个关联工作区（需本机装好并登录 gh CLI）

边界同样要说清。它是 Preview，构建没有签名与公证；它不做 Git 合并、变基与冲突解决；Issue 那条路依赖 gh CLI 且目前只支持 github.com。协作消息只保证至少一次投递，不保证任务只执行一次，所以 Agent 侧要按消息 ID 去重，避免重复副作用；消息正文上限是 32768 字符，每个工作区每个应用进程最多保留 4096 条消息，这些容量限制在编排复杂协作时会真的撞到。