Skip to content

新增命令中心与双斜杠透传功能,修复建群后立即被解散和回调超时问题#19

Open
pb763396199 wants to merge 8 commits intoHNGM-HP:mainfrom
pb763396199:feature/slash-command-passthrough
Open

新增命令中心与双斜杠透传功能,修复建群后立即被解散和回调超时问题#19
pb763396199 wants to merge 8 commits intoHNGM-HP:mainfrom
pb763396199:feature/slash-command-passthrough

Conversation

@pb763396199
Copy link
Contributor

PR: feature/slash-command-passthrough

📝 变更概述

本 PR 新增命令中心与双斜杠透传功能,优化命令解析器,并修复建群场景下的回调超时问题。

✨ 新增功能

1. 双斜杠命令透传(//<command>

  • 支持 //superpowers:brainstorming 形式透传命名空间命令到 OpenCode
  • 保留原始大小写,适配 OpenCode 技能调用规范
  • 自动拦截路径形式的 token(如 !/tmp/script.sh),避免误判

2. 命令文档生成(/commands

  • 新增 /commands 命令,自动生成 docs/generated/commands.md
  • 按内置命令、MCP 命令、技能命令分组展示
  • 支持表格形式查看命令清单与描述

3. 命令解析器优化

  • 重构 src/commands/parser.ts,统一命令类型定义
  • 增强自然语言识别:创建角色发送文件新建会话窗口
  • 改进 Shell 透传白名单拦截逻辑,防止交互式编辑器卡住

🐛 Bug 修复

建群后立即被解散问题(三重保护机制)

  • 问题:私聊建群后,生命周期清理误判群成员不足,导致群聊立即被解散
  • 修复
    1. 建群后设置 5 分钟保护期,保护期内不触发清理
    2. 群主/创建者在白名单时,跳过成员数检查
    3. 回调超时重试机制,避免消息丢失导致状态不同步

📁 文件变更

src/commands/command-doc.ts     [新增] 命令文档生成器
src/commands/parser.ts          [修改] 命令解析器重构
src/handlers/command.ts         [修改] 命令处理器适配
src/handlers/lifecycle.ts       [修改] 生命周期清理逻辑
src/handlers/p2p.ts             [修改] 私聊建群保护机制
tests/commands/parser-*.test.ts [新增] 单元测试

🧪 测试建议

飞书测试步骤:

  1. 双斜杠透传

    //superpowers:brainstorming
    
  2. 命令文档生成

    /commands
    
image image
  1. 私聊建群保护
    • 私聊发送 /create_chat → 选择"新建会话" → 点击"创建群聊"
    • 验证:建群后 5 分钟内不会自动解散

📌 注意事项

  • 双斜杠透传要求当前聊天已绑定 OpenCode 会话
  • /commands 生成的文档保存在 docs/generated/commands.md
  • 建群保护期时长可通过 LIFECYCLE_GRACE_PERIOD_MS 环境变量调整(默认 300000ms = 5 分钟)

HNGM-HP and others added 8 commits March 6, 2026 19:08
# Conflicts:
#	README.md
#	assets/docs/architecture.md
#	assets/docs/sdk-api.md
#	assets/docs/workspace-guide.md
#	package-lock.json
#	package.json
#	src/index.ts
- 新增 // 前缀命令解析,支持命名空间透传(如 //superpowers:brainstorming)
- 新增 /commands 命令,生成命令清单 Markdown 文件并发送到飞书
- 新增 command-doc.ts 命令文档生成器,输出表格格式(分组、分列)
- 新增 OpencodeClient.getCommands 方法,动态获取可用命令列表
- 新增系统生成文件豁免机制,绕过 ALLOWED_DIRECTORIES 白名单校验
- 修复透传命令大小写问题,保留原始命令名(OpenCode 区分大小写)
- README 新增命令中心和双斜杠透传使用说明
- 为 getCommands() 添加 5 分钟缓存机制,减少重复 API 调用
- 实现 OpenCode 版本兼容性检查,首次调用时自动检测 API 可用性
- 添加 clearCommandsCache() 方法用于手动刷新缓存
- 新增双斜杠透传功能单元测试,覆盖 23 个测试用例
- 测试覆盖包括:命名空间解析、大小写保留、参数处理、边界情况

技术细节:
- 缓存使用 TTL 策略,5 分钟后自动失效
- 版本检查通过实际调用 command.list API 验证兼容性
- 测试用例覆盖 parseDoubleSlashCommand 的所有主要场景
- 遵循项目 TypeScript 编码规范,无类型错误
问题表现:
1. 私聊 /create_chat 创建群后立即被自动解散
2. 飞书弹出"目标回调服务超时未响应"警告(虽然群实际创建成功)

根本原因:
- 飞书 createChat API 的成员添加是异步操作,有同步延迟
- lifecycle.ts 的孤儿映射清理在启动时执行,新群未出现在 getUserChats() 返回列表中
- 飞书卡片回调响应限制为 3 秒,但建群流程涉及多个耗时异步操作

修复方案(三重保护):

1️. p2p.ts - ensureUserInGroup 添加重试机制
   - 最多重试 3 次,每次间隔 500ms(总等待 1.5 秒)
   - 等待飞书 API 完成成员列表同步
   - 最后一次重试失败后尝试手动拉取用户作为兜底

2️. lifecycle.ts - runCleanupScan 添加新群保护窗口
   - 清理孤儿映射前检查群的创建时间
   - 如果群创建时间在 30 秒内,跳过清理
   - 给飞书 API 足够的时间完成同步
   - 保护窗口结束后,真正的孤儿仍会被清理

3️. p2p.ts - handleCardAction 异步执行建群逻辑
   - 使用 setImmediate 将建群逻辑改为后台异步执行
   - 立即返回响应给飞书,避免回调超时(限制 3 秒)
   - 后台执行失败记录日志,建群成功后在新群发送欢迎消息

技术细节:
- 检查 session.createdAt 字段判断群的创建时间
- 保护窗口:30 秒
- 重试延迟:500ms * 3 = 最多等待 1.5 秒
- setImmediate 将回调加入事件队列下一个 tick 执行

测试验证:
- 编译检查通过
- 建议测试:私聊 /create_chat 提交表单
- 预期行为:群创建成功,无超时警告,不会被自动解散
@HNGM-HP HNGM-HP force-pushed the main branch 4 times, most recently from 2701b81 to dd0b50a Compare March 17, 2026 13:13
@HNGM-HP
Copy link
Owner

HNGM-HP commented Mar 17, 2026

@pb763396199 感谢你的付出!
请你更新版本至最新beta{v2.9.1}版本,解决分支冲突后合并提交至beta,并更新版本号为v2.9.2-beta-pr1;
请你严格测试,尽量确保无明显BUG;
再次感谢!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants