Skip to content

install.zh-CN.md

Latest commit

 

History

History
243 lines (182 loc) · 9.68 KB

install.zh-CN.md

File metadata and controls

243 lines (182 loc) · 9.68 KB
Raw

安装 codoop-flow skills 到各 coding agent

English · 简体中文

codoop-flow 包含 12 个独立 Skill，分别应对 AI 驱动开发的不同阶段：

Skill 用途 阶段
codoop-init 分析已有项目的自定义目录，或创建新项目的标准空目录 初始化
grilling 每次只问一个大白话问题，确认产品决策 探索 / 工单需求确认
codoop-discover 产品设计与架构规划（0→1 阶段） 开码前
codoop-ticket 工单编排（PRD → Spec → Plan） 工单设计
spec-driven-development 设计技术规格 工单设计 / 独立使用
planning-and-task-breakdown 分解规格为有序任务 工单设计 / 独立使用
definition-of-done 项目级完成标准检查清单 质量守门
codoop-execute 代码实现与交付（隔离 worktree） 编码 & 发布
codoop-ux-walkthrough 用指定 persona 体验流程并产出非阻塞体验报告 独立使用 / 第三环批准后
incremental-implementation 把大改动拆成可逐步验证的小改动 第三环写码 / 独立使用
debugging-and-error-recovery 定位根因并指导失败恢复 第三环排错 / 独立使用
test-driven-development 按先写测试、再实现的方式开发 第三环验证 / 独立使用

每个 skill 都可以在完整的 codoop-flow 插件中独立触发。确定性 CLI、共享 Python 模块和评审 persona 只保留一份，统一放在 runtime/codoop-flow/；skill 不再各自携带脚本。

前提：目标机器有 python3(标准库即可,无第三方依赖);目标工程是一个 git 仓库, 且有 docs/tickets/{pending,in_progress,done,failed}/。准备一份 codoop_flow.toml 指向目标工程(见 codoop_flow.toml.example)。

初始化时，codoop-init 会询问输出语言并写入 codoop_flow.toml 的 output_language。它接受任意 BCP 47 语言标签，例如 zh-CN、en、ko、 es、pt-BR 或 ar；auto 跟随用户当前使用的语言。手动初始化可传入 --output-language <language>。

初始化还会询问 user_role：developer、product_manager、designer、 operations、founder 或 general（普通用户 / 其他行业）；手动初始化可传入 --user-role <role>。它只影响实时对话，工单文档、报告和代码仍保持专业、精确。

项目配置与页面快照

项目配置默认位于 .codoop-flow/codoop_flow.toml，仍作为个人设置由 Git 忽略；同目录下的 ui-snapshots/index.json 和 ui-snapshots/pages/*.html 是随实现版本管理的页面基线，不能忽略整个 .codoop-flow/。 显式 --config 优先，否则从 Git 根目录先查新位置、再查旧根目录配置； 在项目子目录运行同样有效。再次 init 会迁移唯一的旧配置并保留设置， 自定义显式路径不迁移；两份并存时使用新位置并报告，不合并。

init 首次盘点现有页面并建立代表性离线 HTML，后续只刷新变化页面。 ticket 在已有页面上下文中生成工单预览；execute 验证交付后在工单分支 更新基线，随代码合并。没有界面时跳过建档，无法查看时记录未核实状态。 CLI setup 只初始化配置，视觉扫描由 init skill 执行。 详见 快照规则。

一键安装（全部 12 个 Skill）

克隆一次，然后运行：

git clone https://github.com/Codoop/codoop-flow.git
bash codoop-flow/scripts/install-skills.sh

这会把全部 12 个 Skill 和一份共享 Runtime 安装到各 agent。Codex 使用 ~/.codex/runtime/codoop-flow/，Claude 使用 ~/.claude/runtime/codoop-flow/，Cursor 使用 ~/.cursor/runtime/codoop-flow/。再跑一次就是原地更新。用 --agent codex、--agent claude 或 --agent cursor 只装到某一个 agent。 用 --dry-run 预览但不实际复制。

Cursor 推荐直接装插件（见下方 Cursor 章节），脚本的 --agent cursor 只是插件系统不可用时的兜底。

Codex

从 GitHub marketplace 仓库安装 codoop-flow Codex 插件：

codex plugin marketplace add Codoop/codoop-flow
codex plugin add codoop-flow@codoop-flow

然后重启/打开 Codex。日常流程只需要两句话：

使用 $codoop-init，分析这个仓库并初始化 codoop-flow。
使用 codoop-execute skill，针对 /path/to/repo/.codoop-flow/codoop_flow.toml 跑下一张工单。

本地开发时也可以不走插件安装，改为克隆并用安装脚本：

git clone https://github.com/Codoop/codoop-flow.git
bash codoop-flow/scripts/install-skills.sh --agent codex

Claude Code

/plugin marketplace add Codoop/codoop-flow
/plugin install codoop-flow@codoop-flow

请安装完整的 codoop-flow 插件项。各 Skill 共用插件 Runtime，不再作为 独立 Claude 插件发布。

SSH 报错?市场默认用 SSH 克隆。没配 SSH key 就用完整 HTTPS:

/plugin marketplace add https://github.com/Codoop/codoop-flow.git
/plugin install codoop-flow@codoop-flow

本地 / 开发:

git clone https://github.com/Codoop/codoop-flow.git
claude --plugin-dir /path/to/codoop-flow

装好后，可以在会话内直接调用核心 skill：

1. codoop-discover（第一环：产品设计）— 在会话内调用：

/skill codoop-discover 我想做一个 SaaS 项目管理工具，面向远程团队

2. codoop-ticket（第二环：工单编排）— 在会话内调用：

/skill codoop-ticket 帮我设计电商平台的用户搜索功能工单

3. spec-driven-development（第二环：规格设计）— 独立使用或由 codoop-ticket 调用：

/skill spec-driven-development 基于工单 PRD，设计技术规格

4. planning-and-task-breakdown（第二环：任务分解）— 独立使用或由 codoop-ticket 调用：

/skill planning-and-task-breakdown 基于规格，分解成实现任务

5. definition-of-done（质量守门：完成标准）— 开发中参考：

/skill definition-of-done 检查我完成的任务是否符合完成标准

6. codoop-execute（第三环：代码实现）— 在会话内调用：

使用 codoop-execute skill，针对 /path/to/repo/.codoop-flow/codoop_flow.toml 跑下一张工单

或用循环定时跑：

/loop 5m 使用 codoop-execute skill，针对 /path/to/repo/.codoop-flow/codoop_flow.toml 跑下一张工单

7. codoop-ux-walkthrough（独立使用 / 技术批准后的洞察）— 让指定 persona 体验任务，写一份非阻塞报告：

/skill codoop-ux-walkthrough 请以首次使用的运营人员身份体验这个功能，并写入 experience_report.md。

Cursor

Cursor 读取的 SKILL.md 格式与 Claude、Codex 完全一致，并且自带插件 系统。因此 codoop-flow 以「一个插件」的方式安装——skill 和它们共享的 Runtime 保持同层，与其他 agent 完全一样。插件清单位于 .cursor-plugin/plugin.json。

本地 / 开发——把仓库软链到 Cursor 的本地插件目录，然后重载：

git clone https://github.com/Codoop/codoop-flow.git
ln -s "$(pwd)/codoop-flow" ~/.cursor/plugins/local/codoop-flow
# 在 Cursor 里执行 "Developer: Reload Window"（或重启）

重载后，打开 Customize 面板确认插件已加载，然后输入 / 按名字搜索来 触发 skill（如 /codoop-init、/codoop-execute），或者直接描述任务—— Cursor 会像其他 agent 一样按 description 自动发现 skill：

/codoop-init 分析这个仓库并初始化 codoop-flow
使用 codoop-execute，针对 /path/to/repo/.codoop-flow/codoop_flow.toml 跑下一张工单

Cursor 支持并行 subagent，所以 codoop-execute 能像 Codex/Claude 一样并行运行评审 persona。

兜底（无插件系统时）： 把 skill 和 Runtime 拷进 Cursor 根目录，保持同层：

bash codoop-flow/scripts/install-skills.sh --agent cursor

这会写入 ~/.cursor/skills/ 和 ~/.cursor/runtime/codoop-flow/。

通用拷贝(Gemini / 其他 agent)

请保持插件结构完整。把公开 skill 和 Runtime 分别复制到同一个 agent 根目录下的 skills/ 与 runtime/：

git clone https://github.com/Codoop/codoop-flow.git
# 拷全部 12 个 Skill — 每个都自带 SKILL.md
for skill in codoop-init grilling codoop-discover codoop-ticket spec-driven-development \
             planning-and-task-breakdown definition-of-done codoop-execute \
             codoop-ux-walkthrough incremental-implementation \
             debugging-and-error-recovery test-driven-development; do
  cp -R "codoop-flow/skills/$skill"  <目标 agent 的技能目录>/
done
mkdir -p <agent根目录>/runtime
cp -R codoop-flow/runtime/codoop-flow <agent根目录>/runtime/

各 agent 的落脚点(参考各自文档,可能随版本变化):

Agent 放哪 怎么触发
Gemini CLI 放进其 skills 目录 自动发现
其他 agent skill 是纯 Markdown，把每个 SKILL.md 内容作为 system prompt / instructions 喂进去 直接对话

关键：保持 <agent根目录>/skills/ 和 <agent根目录>/runtime/codoop-flow/ 同级。每个 Skill 都从自己的 SKILL.md 相对定位 Runtime；只搬 Skill 文件夹会找不到 CLI 和评审 persona。

验证装好了

codex plugin list
python3 <agent根目录>/runtime/codoop-flow/codoop_tools.py --config <toml> status

能打印出各阶段工单计数(JSON)就说明护栏 CLI 就位、config 正确。

注意:如果宿主 agent 没有 subagent 工具,就在同一个会话里串行运行评审 persona。