Okki VS Code Plugin

cursor插件市场搜索okki-vscode-plugin.okki-tapd-plugin安装使用

vscode插件市场搜索okki-tapd-plugin安装使用

功能简介-快速生成关联tapd需求/bug的git提交

https://xmkm.yuque.com/armee3/iu926w/ge6p415lcrwqm9ns

使用

不再依赖小满账号登录。 配置好下方 Access Token 后，直接刷新待办即可使用。面板上的「登录/退出」按钮已隐藏。

1. 配置 Token（见 第二节）后，点击刷新拉取待办

2. 自动生成关联tapd的commit信息并提交，commit信息如下：

feat(talk): 【fe】【WABA】新消息发送失败原因支持

--story=1121404721001043807 --user=vickwang; https://www.tapd.cn/21404721/s/2429758

仅执行git commit 命令，需要手动add文件到暂存区

3. 不关联tapd待办的紧急/特殊提交，包含关键字--story=0或--bug=0，例：

feat: 这是紧急|特殊提交说明 xxxx --story=0

fix: 这是紧急|特殊提交说明 xxxx --bug=0

4. 切换项目

提交规范

具体提交规范见Git 提交规范

功能简介—工作区使用文档

https://xmkm.yuque.com/armee3/iu926w/svtixd65cf22bv2o

一.安装okki-tapd-plugin插件

在vscode插件市场搜索okki-tapd-plugin安装使用，cursor须搜索okki-vscode-plugin.okki-tapd-plugin

不再建议从从vsix安装，会很难更新最新版本

二.配置 Access Token

插件通过 TAPD OpenAPI 拉待办/详情，通过 GitLab API 建分支/查项目，请配置以下 Token（均支持环境变量，推荐写入 ~/.zshrc）。

配置后请 Reload Window，再点待办面板刷新。

1. TAPD Access Token（待办列表 / 一键修复）

1. 打开 TAPD 个人访问令牌 创建个人 Access Token（用户态）
2. 任选一种方式配置（优先级从高到低）：
   • VS Code / Cursor 设置：搜索 Okki Tapd Plugin: Tapd Access Token，粘贴 token（推荐，改完即生效）
   • 环境变量：

     export TAPD_ACCESS_TOKEN="你的token"
     # 或短名
     export TAPD_TOKEN="你的token"
     

     写入 ~/.zshrc 后需完全重启编辑器（Reload Window 不够，进程环境有缓存）
   • 扩展弹窗输入：未配置时会引导粘贴，并自动写入设置 OkkiTapdPlugin.tapdAccessToken

用于：

• 刷新待办（需求/缺陷 todo）
• 一键修复拉取详情、评论、图片

未配置时，刷新待办 / 一键修复会弹窗引导打开上述配置页。

2. GitLab Access Token（建分支 / 查项目等）

1. 打开 https://gitlab.xiaoman.cc/-/profile/personal_access_tokens ，生成 access_token
2. 
3. 生成完后点击复制 token
4. 任选一种方式配置（优先级从高到低）：
   • 环境变量（推荐）：

     export GITLAB_ACCESS_TOKEN="你的token"
     # 或短名
     export GITLAB_TOKEN="你的token"
     

   • VS Code / Cursor 设置：搜索 Okki Tapd Plugin: Git Access Token，粘贴 token
     

创建工作区 / 一键修复时若远程还没有对应分支，会用该 Token 直连 GitLab API 创建分支（不再依赖小满登录）。

3. PHP CRM 相关设置

在设置页搜索 OkkiTapdPlugin，可配置：

设置项	说明
php-crm-debugg-port	PHP Xdebug 监听端口，默认 ``。新建 PHP 工作区时写入 .vscode/launch.json 的 Listen for Xdebug。需与后端开发机 10.64.32.1 的 /data/github/php-xdebug-proxy/config/config.php 一致
php-crm-debugg-url	PHP 接口环境基础地址。示例：https://cookie.wzw.php.dev.xiaoman.cn

4. 说明：账号配置兜底

无需再登录小满拿项目列表。插件内置常用项目映射，commit 页脚里的用户名兜底取 git config user.name：

项目名	workspace_id
深圳市小满科技有限公司	20036231
OKKI CRM	21404721
大数据组需求	49376479
事故管理	53717204

三.相关功能一览

四.具体功能使用

1.新待办面板

配置 TAPD Token 后点击刷新即可拉取「我的待办」。面板在原有功能上增加了✨来区分合法的tapd，只有命名规范且已经拖进具体迭代的tapd右边悬浮图标才会出现git相关功能（创建工作区，打开测试环境，打开php接口环境，复制分支名，一键修复），因为这些功能的一键操作均依赖该tapd对应的分支名。

在待办标题旁边，我们也新增了一些功能，这些功能都是针对当前工作区的操作（根据任意分支创建工作区，拉取合并当前分支的远程分支代码，推送当前分支代码，创建当前分支合并请求，打开当前分支对应的测试环境，打开 php 接口环境）

2.worktree列表面板

在待办面板下面，新增了git worktree列表来方便我们查看管理我们新增的工作区

• 点击列表项可直接打开对应工作区
• 右侧悬浮图标支持打开工作区对应测试环境、打开 php 接口环境，复制分支名，删除工作区
• 当某个工作区有未推送或者修改的代码时，对应的工作区列表项会通过颜色变化提示，并在末尾显示未推送记录数

3.输出面板

方便查找问题和打印git日志，方便大家知道该插件进行了哪些操作

4.新建工作区功能

5.创建合并请求功能

6.打开测试环境

7.打开 php 接口环境

顶部工具栏、待办项、worktree 列表均可点击「打开php接口环境」（地球图标，紧挨「打开测试环境」）。

地址规则

• 当前是 worktree：https://{转换后的分支名}_{主仓库上一级目录名}.php.dev.xiaoman.cn/api/pageRead/user
  分支名里的 / 会转成 -。例如分支 story/crm/iteration-8-6/1141445，主仓库上一级目录为 www：
  https://story-crm-iteration-8-6-1141445_www.php.dev.xiaoman.cn/api/pageRead/user
• 当前不是 worktree：https://{主仓库上一级目录名}.php.dev.xiaoman.cn/api/pageRead/user
• 若设置了 php-crm-debugg-url（如 https://cookie.wzw.php.dev.xiaoman.cn），则用该地址替换上面的基础域名；worktree 仍会在域名前面加上转换后的分支名。默认打开路径均为 /api/pageRead/user

8.启动script脚本服务（command+shift+j）

根据当前git记录的修改文件和vscode当前显示文件所属的子项目自动勾选所需启动服务。

例如修改crm目录下的一个文件，vscode窗口显示的文件是shell目录下的一个文件，当我执行 cmd + shift + j 时，就会同时显示crm和shell相关服务命令

命令可重复执行，正在运行的服务不会重复执行

9.一键修复（Cursor Agent）

面向 Cursor 的能力：在待办项上点击「一键修复」，自动准备分支工作区、拉取 TAPD 上下文，并预填 Agent Prompt，确认后即可让 Agent 开始修复。

前置条件

1. 在 Cursor 中使用（非 VS Code 纯净环境）
2. 待办需符合命名规范且已拖入迭代（标题带 ✨，与其它 git 一键能力相同）
3. 已配置 TAPD Access Token
4. 已配置 GitLab Access Token（远程尚无对应分支时会自动创建）

使用步骤

1. 在待办列表找到目标需求/缺陷，点击右侧「一键修复」图标
2. 进度提示会依次展示：创建工作区 → 拉取 TAPD 信息 → 组装 Prompt → 启动 Agent
3. 成功后 Agent 面板会预填修复上下文，确认后按 Enter 发送即可

一键修复会做什么

步骤	说明
确保工作区	若该 TAPD 对应分支的 worktree 不存在则创建；已存在则复用，不会强制打开新窗口
拉取 TAPD	通过 OpenAPI 获取标题、描述、状态、评论；描述/评论中的图片会下载到工作区 .cursor/assets/
写上下文文件	生成 .cursor/tapd-bug-*.md 或 .cursor/tapd-story-*.md，供 Agent 阅读
组装 Prompt	按「Prompt 模板」渲染最终提示词，并预填到 Cursor Agent

Prompt 模板

顶部工具栏点击「Prompt 模板」可分别编辑 Bug / Story 模板，并管理历史版本（恢复 / 删除）。

模板可用变量：

变量	含义
{{worktreePath}}	工作区绝对路径
{{contextFile}}	TAPD 上下文 markdown 文件路径

保存后新的一键修复会使用最新模板；也可从历史表切回旧版本。

失败时

• Agent 预填失败：可选择「复制 Prompt」，或使用命令「重试 Agent 预填」
• 详细日志：Output 面板选择 OKKI Git Worktree Manager

10. PHP 项目工作区

识别为 PHP 项目时（根目录有 composer.json、根目录 *.php，或存在 protected/），新建工作区会额外做两件事：

1. 写入 .vscode/launch.json
   • Listen for Xdebug：端口读设置 php-crm-debugg-port（默认 9059）
   • Debug current PHP file：调试当前 PHP 文件
2. 创建 {工作区}/protected/runtime，并赋予可写权限（777），供 Yii 运行时写日志/缓存

非 PHP 项目不受影响。

11.其它功能就不演示了...

五.复杂功能对应的业务流程

1.新建工作区

六.其它

q1: upstream是什么，origin是什么？

a1: upstream代表上游仓库，origin代码fock的仓库。

q2: upstream和 origin有什么用？

a2: 在我们推送代码功能，创建工作区功能，以及创建合并请求公共都需要用到这两个仓库。

q3:upstream和origin是如何获取的，
a3:git remote -v, 前面的是origin，后面的是upstream。如果说你发现插件分支相关功能奇怪时，或许是顺序对不上🤔 git remote -v 一下

q4: 还需要小满账号登录吗？
a4: 不需要。配置 TAPD_ACCESS_TOKEN + GITLAB_ACCESS_TOKEN（或设置项）即可拉待办、建分支、一键修复。面板登录按钮已隐藏。

如何发布插件

更改版本号，即package.json里的version字段，并合并到master就会自动构建发布应用市场。不过市场有延迟，预估要一个小时左右才会更新成功。