feat(desktop): 新增项目级环境配置(Worktree 脚本、变量与快捷操作)
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
## 使用场景 / Use case
Cindy 已支持为任务创建独立 Git Worktree,但新 Worktree 通常还需要手动安装依赖、准备配置、启动开发服务或运行项目检查。
对于需要频繁并行开发、切换项目或从移动端创建任务的用户,希望 Cindy 能记住每个项目的环境准备方式,并在正确的生命周期自动执行;同时把常用命令做成一键操作,减少每次重复告诉 Agent “先安装依赖、再启动项目”。
## 当前问题 / Current limitation
目前 Cindy 已具备 Worktree 的创建、恢复和安全回收能力,但缺少项目级环境配置:
- 新 Worktree 不共享 `node_modules`,仍需手动执行 `pnpm install` 等初始化命令;
- 无法在 Worktree 创建和清理时运行项目自定义脚本;
- 无法针对 macOS、Windows、Linux 提供不同命令;
- 没有项目级环境变量管理;
- 启动开发服务、运行测试、仓库体检等高频命令不能配置为任务顶部的一键 Action。
相关现状:
- Worktree 生命周期:[`WorktreeManager.ts`](https://github.com/makecindy/cindy/blob/main/apps/desktop/src/main/worktree/WorktreeManager.ts)
- 当前 Worktree 说明:[`worktrees.md`](https://github.com/makecindy/cindy/blob/main/apps/desktop/help-knowledge/worktrees.md)
- 当前环境准备仍要求在新 Worktree 手动安装依赖:[`environment-setup.md`](https://github.com/makecindy/cindy/blob/main/docs/dev-rules/environment-setup.md)
## 期望方案 / Proposed solution
在 Desktop 设置中增加项目级「环境」页面,按仓库保存以下配置。
### 1. 设置脚本 / Setup script
- 创建新 Worktree 后、Agent 第一次开始工作前自动运行;
- 默认脚本之外,支持 macOS / Windows / Linux 平台覆盖;
- 在新 Worktree 根目录执行;
- 显示执行状态和完整日志;
- 执行失败时阻止任务静默继续,提供重试和查看日志入口。
示例:
```bash
pnpm install
pnpm run build
```
### 2. 清理脚本 / Cleanup script
- 在 Worktree 被回收前运行;
- 在待清理的 Worktree 根目录执行;
- 可用于停止服务、释放端口、清理临时资源;
- 默认采用安全策略:脚本失败时保留 Worktree,并提示用户处理,避免直接删除现场;
- 同样支持按平台覆盖。
### 3. 项目 Actions
允许为项目配置常用操作:
- 名称、图标、命令;
- 默认命令及按平台覆盖;
- 显示在任务顶部或项目快捷入口;
- 点击后在 Cindy 内置终端中执行;
- Worktree 任务以当前 Worktree 为 cwd,普通任务以当前项目目录为 cwd。
示例:
- Run Dev Client
- Run Unit Tests
- Verify Merge Candidate
- Repository Doctor
### 4. 环境变量
- 支持项目级环境变量,供设置脚本、清理脚本、Actions 和项目启动的子进程使用;
- 普通变量可以进入可共享配置;
- Secret 必须存入系统凭证存储或 Cindy 的安全存储,禁止明文写入仓库;
- UI 明确区分共享配置与本机私有配置。
### 5. 配置持久化与共享
建议采用“仓库共享配置 + 本机覆盖”的结构,例如:
- 仓库内配置:可提交 Git,与团队共享;
- 本机覆盖:不进入 Git,用于路径、端口和 Secret;
- 没有环境配置的现有项目保持原行为,不改变现有 Worktree 流程。
具体文件名和 schema 可在实现阶段确定,不强制与其他产品保持一致。
## 安全边界
这些脚本本质上允许仓库执行任意本地命令,因此需要:
- 首次运行来自仓库的环境脚本前要求用户确认信任;
- 配置内容发生变化后重新确认;
- 确认界面展示将执行的完整命令、cwd 和变量来源;
- Secret 不进入日志,不通过 Agent 上下文回显;
- 不允许清理脚本绕过 Cindy 现有的 dirty check、live session、keep sentinel 等 Worktree 安全守卫。
## 验收标准 / Acceptance criteria
- [ ] 可为单个项目配置默认及 macOS / Windows / Linux 设置脚本;
- [ ] 新 Worktree 首次使用前自动执行设置脚本,并可查看日志、失败后重试;
- [ ] Worktree 回收前执行清理脚本,失败时默认保留 Worktree;
- [ ] 可配置项目 Actions,并在当前任务对应的 cwd 中通过内置终端执行;
- [ ] 环境变量作用域明确,Secret 不写入 Git、不出现在日志;
- [ ] 仓库配置可共享,本机配置可覆盖;
- [ ] 配置新增或变化后有明确的信任确认;
- [ ] 未配置该能力的项目和既有任务行为完全不变;
- [ ] Settings 和任务入口同时适配 Light / Dark 与现有 i18n 体系;
- [ ] 增加设置脚本、清理脚本、平台覆盖、Action cwd、失败保护和配置变更确认的测试。
## 参考
Codex Local environments 提供了相近的 Setup scripts 与 Actions 设计,可作为交互和生命周期参考:
https://learn.chatgpt.com/docs/environments/local-environment
Contributor guide
Research direction
Start with apps/desktop/src/main/worktree/WorktreeManager.ts to map Worktree creation, recovery, cleanup, dirty checks, live sessions, and keep sentinels. Read apps/desktop/help-knowledge/worktrees.md and docs/dev-rules/environment-setup.md, then trace the Desktop Settings and task entry points. Done means the listed lifecycle, platform, Action, variable, trust, failure-protection, compatibility, theme, i18n, and test requirements are covered without changing unconfigured projects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, typescript
- Domain
- desktop, security, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100