makecindy / makecindy/cindy

feat(desktop): 新增项目级环境配置(Worktree 脚本、变量与快捷操作)

Open
#1,319 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.