luminae-helper 1.2.2 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +48 -43
  3. package/codex-plugins/.agents/plugins/marketplace.json +20 -0
  4. package/codex-plugins/.claude-plugin/marketplace.json +13 -0
  5. package/codex-plugins/plugins/ai-development-workflow/.claude-plugin/plugin.json +8 -0
  6. package/codex-plugins/plugins/ai-development-workflow/.codex-plugin/plugin.json +15 -0
  7. package/codex-plugins/plugins/ai-development-workflow/LICENSE +21 -0
  8. package/codex-plugins/plugins/ai-development-workflow/hooks/codex.json +30 -0
  9. package/codex-plugins/plugins/ai-development-workflow/hooks/hooks.json +22 -0
  10. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/SKILL.md +38 -0
  11. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/agents/openai.yaml +3 -0
  12. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/references/codex-coordinator.md +55 -0
  13. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/references/coordination.md +292 -0
  14. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/references/direct-handoff.md +17 -0
  15. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/references/handoff.md +59 -0
  16. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/references/verification.md +58 -0
  17. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/scripts/codex_compact.py +112 -0
  18. package/codex-plugins/plugins/ai-development-workflow/skills/ai-development-workflow/scripts/codex_dispatch.py +102 -0
  19. package/package.json +2 -1
  20. package/src/index.js +13 -0
  21. package/src/lib/codex-plugin.js +276 -0
  22. package/src/lib/constants.js +14 -68
  23. package/src/lib/installer.js +25 -34
  24. package/src/lib/skill-command.js +40 -0
  25. package/src/lib/ui.js +78 -124
package/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.3.2
4
+
5
+ - 随包分发 ai-development-workflow 0.9.1。Codex 审查弹窗显示「校验派单回传安排」和「压缩后恢复统筹上下文」。
6
+
7
+ ## 1.3.1
8
+
9
+ - 随包分发 ai-development-workflow 0.9.0。明确启用的 Codex 统筹可使用业务工作区只读权限,并在派单前校验任务、回传安排和独立检查点。普通开发会话沿用宿主默认设置。
10
+ - 补齐会话身份、回传责任、独立监督及临时 Bug 排查规则。Codex 和 Claude Code 继续支持各自的压缩续接 Hook。
11
+
12
+ ## 1.3.0
13
+
14
+ - 公共技能统一安装为 Skill 目录。更新选中的受管旧命令时,先安装 Skill 再移除旧文件,仍支持离线卸载旧命令。
15
+ - 增加 `skill install <技能ID> --tool <宿主ID>`,按当前正式目录安装指定技能。
16
+ - 在交互安装流程中支持 Codex 和 Claude Code 插件,同时支持 `plugin install` 命令。默认按技能名安装 Helper 随包提供的受管插件,也可显式指定外部本地包。ai-development-workflow 插件 0.8.1 在两端均包含压缩续接 Hook,按各自宿主规则加载。
17
+
18
+ ## 1.2.3
19
+
20
+ - 验证运行时安装 / 更新可获取 ai-skills 0.5.0 正式 Tag,完整复制文档执行者、工作区绑定和接替所需引用及配置。
21
+ - 公共技能继续按最新正式 Tag 获取,不内嵌快照;保留旧管理标识迁移、非受管同名内容和外来软链保护,以及离线卸载。
22
+
3
23
  ## 1.2.2
4
24
 
5
25
  - 公共技能的技能选择、目标工具、确认预览、兼容转换确认面板都固定提供「✕ 退出」;嵌入包装器时额外保留「↩ 返回主菜单」。
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # luminae-helper
2
2
 
3
- AI 编程工具的 skills/commands 管理 CLI。一键将公共 AI agent 技能安装到 Claude Code、Cursor、Codex、Hermes Agent、OpenCode、Trae 等工具中。
3
+ AI 编程工具的 Skill 和插件安装 CLI。一键将公共 AI agent 技能安装到 Claude Code、Cursor、Codex、Hermes Agent 和 OpenCode。
4
4
 
5
- 公共内容不内置在 npm 包中。选择「安装 / 更新」时从 `ai-skills` 拉取最新正式 Git Tag,再复制到目标工具。首次需要网络与 Git;卸载和 `--version` 不需要拉取技能。
5
+ 公共 Skill 源码从正式 Tag 获取。选择「安装 / 更新 → Skill」时从 `ai-skills` 拉取最新正式 Git Tag,再复制到目标工具。首次需要网络与 Git;卸载和 `--version` 不需要拉取技能。
6
6
 
7
7
  ## 前置条件
8
8
 
@@ -26,20 +26,44 @@ npm install -g luminae-helper
26
26
  luminae-helper
27
27
  ```
28
28
 
29
- 进入交互式菜单,分四步:
29
+ 选择「安装 / 更新 → Skill」,分四步:
30
30
 
31
- 1. **选择内容** — 勾选要安装的 commands / skills
31
+ 1. **选择内容** — 勾选要安装的 Skill
32
32
  2. **选择工具** — 勾选要安装到哪些 AI 工具(自动检测本机已安装的)
33
33
  3. **预览确认** — 确认后执行
34
34
  4. **执行安装** — 复制文件到各工具目录,汇总结果
35
35
 
36
+ 也可以直接安装指定技能:
37
+
38
+ ```bash
39
+ luminae-helper skill install ai-development-workflow --tool codex
40
+ luminae-helper skill install git-push --tool claude-code
41
+ luminae-helper skill --help
42
+ ```
43
+
44
+ `skill install` 根据最新正式 Tag 校验技能 ID,只安装到 `--tool` 指定的已安装宿主。技能 ID 不存在时会列出当前可安装的条目。无法更新来源时命令会报错,可进入交互流程选择已验证的旧缓存。
45
+
46
+ ### 安装插件
47
+
48
+ 运行 `luminae-helper`,选择「安装 / 更新 → 插件」,再选 Codex 或 Claude Code。留空使用 Helper 的受管清单,目前两端都提供 `ai-development-workflow`。输入本地插件目录可安装该宿主兼容的外部包。
49
+
50
+ ```bash
51
+ luminae-helper plugin install ai-development-workflow --tool codex
52
+ luminae-helper plugin install ai-development-workflow --tool claude-code
53
+ luminae-helper plugin install my-plugin --tool claude-code --source "/path/to/local-plugin"
54
+ ```
55
+
56
+ 省略 `--tool` 时使用 Codex。`--source` 接受独立插件目录和本地来源目录。Codex 识别 `.codex-plugin/plugin.json` 或 `plugin.json`,优先读取 `.agents/plugins/marketplace.json`。Claude Code 使用 `.claude-plugin/plugin.json` 和 `.claude-plugin/marketplace.json`。本地来源只提供目录内的本地插件。
57
+
58
+ Helper 调用相应宿主的 CLI 安装。Codex 用户在 Settings → Hooks 或 `/hooks` 审阅并信任 Hook。Claude Code 在新会话或 `/reload-plugins` 后加载插件,可通过 `/hooks` 查看。压缩续接依赖 Python 3.9+,两端分别登记各自的统筹会话。插件卸载由宿主管理。
59
+
36
60
  ### 卸载技能
37
61
 
38
62
  再次运行 `luminae-helper`,在第一步主菜单中选择「卸载」。
39
63
 
40
64
  卸载时只会删除带有 `managed-by: luminae-helper` 标识的文件,不会误删用户手动创建或 AI 工具自带的同名文件。
41
65
 
42
- 安装同理:目标位置已有同名的非本工具内容时直接跳过(结果表标「已跳过」),不会覆盖。识别兼容顶层旧字段和 metadata 新字段,仅接受有效 frontmatter 中的 `luminae-helper` 管理者;正文示例、其他管理者、重复键、冲突或损坏内容不认领。公共安装不接管软链或链接形式的 SKILL.md;发现与卸载不会顺带迁移文件。
66
+ 安装时,目标宿主已有非本工具管理的同名 Skill 或旧命令文件会跳过并说明冲突。更新受管旧命令时,成功安装 Skill 后才移除旧文件。识别兼容顶层旧字段和 metadata 新字段,仅接受有效 frontmatter 中的 `luminae-helper` 管理者;正文示例、其他管理者、重复键、冲突或损坏内容不认领。公共安装不接管软链或链接形式的 SKILL.md;发现与卸载不会顺带迁移文件。
43
67
 
44
68
  ### 其他命令
45
69
 
@@ -52,46 +76,27 @@ luminae-helper outdated # 检查 npm registry 是否有新版本
52
76
 
53
77
  任何步骤按 `Ctrl+C` 或在导航行选择「退出」即可安全退出,不会产生残留文件。
54
78
 
55
- ## 包含内容
56
-
57
- ### Commands(命令)
79
+ ## 公共技能
58
80
 
59
- | 命令 | 用途 |
60
- |------|------|
61
- | `git-push` | 代码审查 → 提交信息 → commit → push 完整工作流 |
81
+ | 技能 ID | 用途 |
82
+ |---------|------|
83
+ | `ai-development-workflow` | 协调跨阶段、多工作区和多会话开发任务 |
84
+ | `generate-refactor-docs` | 生成页面、接口和后端链路的重构文档 |
85
+ | `git-flow` | 管理 Git Flow feature、release 和 hotfix 分支 |
86
+ | `git-push` | 按用户授权执行提交前检查、提交和推送 |
87
+ | `identity` | 检测项目类型并设定 Agent 身份 |
62
88
 
63
- ### Skills(技能)
64
-
65
- | 技能 | 用途 |
66
- |------|------|
67
- | `ai-development-workflow` | AI 协作开发流程:协调跨阶段、多工作区和多会话任务,覆盖专业分工、回传监控、验证及交接 |
68
- | `git-flow` | Git Flow feature / release / hotfix 分支的创建、检出与 finish,版本号自动计算 |
69
- | `identity` | 检测项目类型,自动设定 agent 身份(前端/后端/全栈等) |
89
+ 实际可安装列表由正式 Tag 决定。公共来源的 `skills/` 优先,旧版本的 `commands/<id>/SKILL.md` 仍可读取和安装为 Skill。旧受管命令在卸载菜单中标为「旧命令」。
70
90
 
71
91
  ## 支持的工具
72
92
 
73
- | 工具 | command 模式 | skill 模式 | 安装方式 |
74
- |------|:-----------:|:---------:|------|
75
- | Claude Code | ✓ | ✓ | `~/.claude/commands/*.md` / `~/.claude/skills/*/` |
76
- | Codex | ✗ | ✓ | `~/.codex/skills/*/` |
77
- | Cursor | ✗ | ✓ | `~/.cursor/skills/*/` |
78
- | Hermes Agent | ✗ | ✓ | `~/.hermes/skills/*/` |
79
- | OpenCode | ✗ | ✓ | `~/.opencode/skills/*/` |
80
- | Trae | ✓ | ✗ | `~/.trae/commands/*.md` |
81
-
82
- ### Command vs Skill
83
-
84
- - **Command** — 以 `/command-name` 方式触发,安装为单个 `.md` 文件(Claude Code、Trae)
85
- - **Skill** — 作为上下文注入到 agent,安装为完整目录(Codex、Cursor、Hermes、OpenCode)
86
-
87
- 当技能类型与工具能力不匹配时,CLI 会自动做 fallback 转换(如 command 源安装到只支持 skill 的工具),并在结果中标注。
88
-
89
- ### 兼容转换
90
-
91
- | 场景 | 转换方式 |
92
- |------|---------|
93
- | Command → 仅支持 skill 的工具 | 将 `.md` 文件包装为 skill 目录安装 |
94
- | Skill → 仅支持 command 的工具 | 将目录下的 `SKILL.md` 安装为 `.md` 文件 |
93
+ | 宿主 | `--tool` | Skill 安装目录 |
94
+ |------|----------|----------------|
95
+ | Claude Code | `claude-code` | `~/.claude/skills/*/` |
96
+ | Codex | `codex` | `~/.codex/skills/*/` |
97
+ | Cursor | `cursor` | `~/.cursor/skills/*/` |
98
+ | Hermes Agent | `hermes-agent` | `~/.hermes/skills/*/` |
99
+ | OpenCode | `opencode` | `~/.opencode/skills/*/` |
95
100
 
96
101
  ## 工作原理
97
102
 
@@ -128,13 +133,13 @@ npm uninstall -g luminae-helper
128
133
 
129
134
  ### 公共技能来源与缓存
130
135
 
131
- 源仓库为 `https://github.com/evenweiss/ai-skills.git`。每次选择「安装 / 更新」都会检查最大正式版本 Tag(`X.Y.Z` 或 `vX.Y.Z`,不含预发布版本),不跟随未发布的 main。界面显示实际 Tag 和提交。
136
+ 源仓库为 `https://github.com/evenweiss/ai-skills.git`。交互安装 Skill 和 `skill install` 都会检查最大正式版本 Tag(`X.Y.Z` 或 `vX.Y.Z`,不含预发布版本),不跟随未发布的 main。界面显示实际 Tag 和提交。
132
137
 
133
138
  缓存位于 `~/.cache/luminae-helper/public-skills/`:首次 clone,后续 fetch。只长期保留最近一次成功获取的正式版本;临时目录和无人使用的历史快照会自动清理。并发安装登记独立占用,旧快照在最后一个使用者退出后才回收,下载与清理不会中断其他安装。正常完成、返回、取消或失败都会释放占用;异常退出的遗留占用与临时数据在下次缓存操作时回收。
134
139
 
135
140
  不要编辑缓存;工作树或 HEAD 被修改的快照会被保留并提示,不会自动覆盖或删除,因此这类快照需要自行保留改动后处理。
136
141
 
137
- 更新失败时,CLI 显示有效旧缓存的 Tag/提交,默认返回;只有明确选择才使用旧缓存安装,且提示未确认是最新版本。没有有效缓存时停止本次安装。删除缓存后,下次安装会重新下载;已安装的受管内容仍可离线卸载,包括新版本中已移除的条目。
142
+ 交互安装遇到更新失败时,会显示有效旧缓存的 Tag/提交,默认返回;只有明确选择才使用旧缓存安装,且提示未确认是最新版本。没有有效缓存时停止本次安装。删除缓存后,下次安装会重新下载;已安装的受管内容仍可离线卸载,包括新版本中已移除的条目。
138
143
 
139
144
  安装继续采用复制方式;更新缓存不会自动修改已安装技能,需要再次选择安装 / 更新。公共技能保留覆盖保护,公司内部技能不属于本工具。
140
145
 
@@ -145,7 +150,7 @@ npm test
145
150
  npm pack
146
151
  ```
147
152
 
148
- 测试使用临时源码、Git 仓库和目标目录,不依赖本地公共技能副本。打包和 npm 安装不再触发技能下载。`commands/`、`skills/` 的旧生成目录仍被忽略,但不会进入 npm 包;旧 `sync-skills` 脚本已移除。
153
+ 测试使用临时源码、Git 仓库和目标目录,不依赖本地公共技能副本。打包和 npm 安装不再触发技能下载。`commands/`、`skills/` 的旧生成目录仍被忽略,但不会进入 npm 包;旧 `sync-skills` 脚本已移除。受管插件的包和两端清单存放于 `codex-plugins/`,随 npm 包分发。更新受管插件时同步包内容和插件清单版本。
149
154
 
150
155
  需要正式发布 CLI 时再执行 `npm publish`,公共技能的新 Tag 不要求 CLI 同步发版。
151
156
 
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "luminae-helper",
3
+ "interface": {
4
+ "displayName": "Luminae Helper"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "ai-development-workflow",
9
+ "source": {
10
+ "source": "local",
11
+ "path": "./plugins/ai-development-workflow"
12
+ },
13
+ "policy": {
14
+ "installation": "AVAILABLE",
15
+ "authentication": "ON_INSTALL"
16
+ },
17
+ "category": "Productivity"
18
+ }
19
+ ]
20
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "luminae-helper",
3
+ "owner": {
4
+ "name": "Luminae Helper"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "ai-development-workflow",
9
+ "source": "./plugins/ai-development-workflow"
10
+ }
11
+ ],
12
+ "description": "Luminae Helper 随包分发的插件"
13
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "name": "ai-development-workflow",
3
+ "version": "0.9.1",
4
+ "description": "AI 协作开发流程与上下文压缩后的统筹续接提醒。",
5
+ "author": {
6
+ "name": "evenweiss"
7
+ }
8
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "name": "ai-development-workflow",
3
+ "version": "0.9.1",
4
+ "description": "AI 协作开发流程,支持统筹压缩续接和按任务启用的只读与派单校验。",
5
+ "skills": "./skills/",
6
+ "hooks": "./hooks/codex.json",
7
+ "interface": {
8
+ "displayName": "AI 协作开发流程",
9
+ "shortDescription": "跨会话协作、任务交接与独立验收",
10
+ "capabilities": [
11
+ "Instructions",
12
+ "Lifecycle hooks"
13
+ ]
14
+ }
15
+ }
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 evenweiss
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,30 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "matcher": "^compact$",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "python3 -B \"${PLUGIN_ROOT}/skills/ai-development-workflow/scripts/codex_compact.py\"",
10
+ "statusMessage": "压缩后恢复统筹上下文",
11
+ "timeout": 5
12
+ }
13
+ ]
14
+ }
15
+ ],
16
+ "PreToolUse": [
17
+ {
18
+ "matcher": "^mcp__codex_app__(send_message_to_thread|create_thread|fork_thread|handoff_thread)$",
19
+ "hooks": [
20
+ {
21
+ "type": "command",
22
+ "command": "python3 -B \"${PLUGIN_ROOT}/skills/ai-development-workflow/scripts/codex_dispatch.py\"",
23
+ "statusMessage": "校验派单回传安排",
24
+ "timeout": 5
25
+ }
26
+ ]
27
+ }
28
+ ]
29
+ }
30
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "matcher": "^compact$",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "python3",
10
+ "timeout": 5,
11
+ "args": [
12
+ "-B",
13
+ "${CLAUDE_PLUGIN_ROOT}/skills/ai-development-workflow/scripts/codex_compact.py",
14
+ "--host",
15
+ "claude-code"
16
+ ]
17
+ }
18
+ ]
19
+ }
20
+ ]
21
+ }
22
+ }
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: ai-development-workflow
3
+ description: 用于跨会话、跨工作区或有阶段依赖的 AI 协作开发,安排任务分工、交接回传、监控和独立验收。日常单次编码或无需协调的小改通常无需调用。
4
+ ---
5
+
6
+ # AI Development Workflow
7
+
8
+ 先核对项目工作流、最新用户决定、依赖、风险和独立验证需要,沿用项目已采用的分类、需求及契约机制,按风险取用流程。未设统筹时,短周期、低依赖的单仓小改可由单执行会话直接完成。需要协调时,沿用用户亲自衔接或唯一统筹的既有选择。有统筹时通常逐段协调。项目或任务明确采用负责人串联,且同任务交接路线、接收方、权限和所需资源可核实时,由统筹首派给任务负责人,再按[同任务直接交接](references/direct-handoff.md)执行。已有安排继续有效。
9
+
10
+ ## 组织、派发与收取
11
+
12
+ - 开工时按[会话身份与职责](references/coordination.md#执行者类别与任务匹配)选择本次所需身份;采用统筹时,再按风险判断是否启用[独立只读监督](references/coordination.md#已授权监控的核查与收口),沿用适用的已有安排。
13
+ - 统筹负责只读查询、协调、派单、任务包、证据核对和验收管理。实质交付由执行者承担。每轮首次修改源码、测试或其他交付物,或运行用于交付或验收的实质测试前,先核对当前会话在该任务中的角色。涉及仓库操作时,同步按[工作区定位](references/coordination.md#执行会话的工作区定位与操作范围)核对已确认的实施分支及归并安排。收到简短确认或实施范围批准后,沿用已确认的分工。轻量修复和同时使用专项实施技能的任务同样适用。当前会话承担统筹时,转入实施、合流、正式文档修订或实质验证前,按[任务包](references/coordination.md#任务包)核对实际执行者、授权及唯一写入负责人,复用覆盖本次的有效派单或按授权下发。采用统筹时,独立文档修订在制作清单、逐项核验或拟稿前完成派发安排,具体见[文档分工](references/coordination.md#文档任务的制作与确认)。
14
+ - 已采用统筹的任务,在现有协调记录保留当前会话角色、执行者、唯一写入负责人及本技能和适用引用的入口。续接摘要保留该记录的入口。上下文压缩后,或续接摘要缺少分工依据时,在首次安排实施或实质验证前,重新读取任务适用的技能及引用,从最新协调记录、原派单或可定位的用户决定核实角色、执行者和授权。核实仍为统筹时,按既有分工复用派单或按授权下发。角色或写入归属暂无法核实时,先做只读核查,仅暂缓受影响的写入或实质验证。 已启用插件 Hook 时,按[压缩续接](references/coordination.md#插件的压缩续接)登记或撤销当前统筹任务。Claude Code 当前会话 ID 由宿主替换 `${CLAUDE_SESSION_ID}`,未替换时不得作为 ID 使用。
15
+ - 子 Agent 和独立主会话均按实际能力和专业职责匹配。用户已指定时沿用。未指定时,统筹在已有授权内按[执行者选择](references/coordination.md#组织方式与执行者选择)优先复用合适会话;预计需要多轮与用户直接交互的任务,安排用户可直接进入和回复的独立主会话。仅澄清会实质影响执行的缺项。按[工作区定位](references/coordination.md#执行会话的工作区定位与操作范围)核实实际工作区和适用规则,支持经核实的绑定或显式目录,按用户选择安排主工作区或 worktree。
16
+ - 派发前核实依赖、执行者占用、实际执行存续和收取安排,按[任务包](references/coordination.md#任务包)核对实际发送正文里的本任务身份、回传指令、授权和不依赖自报的检查点。启动或接替时从现有协调记录核对轮次出口和收取安排,后续沿用有效约定,有变化才更新。默认下发后交还用户。约定检查点时明确后续触发方式,统筹在被唤起后核查。交还前确需查状态时,只做即时查询。仅当用户明确要求本轮持续跟进,或满足技术保全条件时,才阻塞等待。单说“先完成某项”只指定顺序;用户明确要求持续跟进时,跟进到约定结果并结束。交还时简报已派事项和负责人、待派或暂缓事项,以及谁在何时触发收取。没有自动唤醒能力时说明手动续接。按[轮次出口与续接](references/coordination.md#统筹的轮次出口与续接)处理必要的技术保全等待。缺少执行者、工具或权限时,报告缺口或交用户人工转交任务包。统筹继续履行协调职责,实质交付仍由执行者负责。
17
+ - 执行者首次接单前读取本技能、任务适用引用、项目规则及相关技能,按任务包核对并履行本任务的身份和回传职责。复用时核对已加载内容和变化,任务包提供可访问入口。技能或关键引用不可读取时,说明缺项及受影响动作,仅暂缓依赖该资料的操作,其他独立且已授权的工作继续。执行者可直接处理职责内的局部沟通。共性问题、跨任务协调和授权缺口默认由当前唯一顶层统筹收口。执行者再委派须核对授权,原执行者继续负责整体交付。
18
+ - 统筹核收阶段交付、确认接替完成或发现退出依赖解除时,主动按[接管与退出](references/handoff.md)核查所辖会话。已达到退出条件、保全和依赖核验通过,且已有覆盖该会话或批次的归档授权时,直接归档并回读实际状态。缺少授权时,在本轮汇总已具备条件的会话、可能影响及缺失授权,可按明确范围一次确认。仍有职责或依赖的会话保留,记录下次核查条件,在后续已约定的核收中重查。
19
+
20
+ ## 基线、授权与验收
21
+
22
+ - 复用现有记录,保留可定位的任务目标、非目标、版本、实际工作区、负责人、决定来源及覆盖关系、依赖与交付条件、证据和停止点。先定位证据缺口,只补影响判断的最小信息。局部疑问仅暂缓受影响项,统筹按既有分工派发已就绪且获授权的独立事项。推荐或派发方案前核对已确认目标、已核事实及关键反例,排除违反约束的路径。专业方案由对应执行者产出。
23
+ - 创建、复用、派单、再委派、消息、分支和 worktree 操作,以及本地开发、提交、推送、合并、部署、配置发布、远程主机变更、直接 DB 写和真实 API 写,分别核对用户授权及工具许可,遵守系统、用户、项目和工具边界。方案批准只覆盖已确认范围。直接复用仍有效且覆盖本次动作的授权。常规实现选择在已确认范围内由执行者处理,无需重复询问。缺少写授权时先说明目标环境、动作和影响,再取得所需授权。
24
+ - 收到暂停或撤权即停止受影响的操作安排及下游放行,沿获准链路通知,涉及写入时核查实际停写。发现统筹代做时,停止相关实质操作、保全产物及证据,确认停写后移交唯一写入权。按[状态和回报](references/coordination.md#状态和回报)核查在途操作。复工须符合最新有效决定、操作授权和适用条件。
25
+ - 单个开发任务默认由开发者自验,满足任务通过条件后交付。满足项目提测条件并进入需求级测试后,由未参与相关实现的验证者在独立上下文中验收。按[验收与证据](references/verification.md#验收与证据)判断是否提前做专项独立验证。单任务交付、专项验证、需求级独立验收和用户业务接受分别记录,用户完成约定的业务接受。按验收报告返修时,派单及交付复用原问题编号或可定位条目,逐项说明处理范围及待确认或延期事项。普通小改按影响范围验证并检查最终差异。阶段报告写明已证明范围、版本与证据、未闭合项及负责人、下一动作和准入条件。会话状态和交付回报须与实际验收状态分开,阻断项闭合后才能放行。
26
+
27
+ ## 按场景读引用
28
+
29
+ | 场景 | 对应章节 |
30
+ |---|---|
31
+ | 派单、类别选择、再委派、工作区或状态协调 | [协作与交接](references/coordination.md)的目录按需定位,短任务按[任务包](references/coordination.md#任务包)准备,局部沟通按[沟通分流](references/coordination.md#局部沟通与统一收口)处理 |
32
+ | 评估方案可行性(含是否需新增接口、字段或同步链路)、设计与实现同步、接口迁移、兼容或契约就绪,单会话同样适用 | [基线与契约](references/coordination.md#基线与契约) |
33
+ | 独立文档制作、正式修订或同步外部文档,单会话同样适用 | [文档分工与写前核对](references/coordination.md#文档任务的制作与确认) |
34
+ | 临时 Bug 排查、诊断后有据修复或独立复现 | [临时 Bug 排查](references/coordination.md#临时-bug-排查),明确身份、证据、修复条件、停止点和回传方式 |
35
+ | Codex 统筹任务明确启用只读和派单校验 | [Codex 统筹保护](references/codex-coordinator.md) |
36
+ | 负责人串联、同任务交接及发送不明 | [同任务直接交接](references/direct-handoff.md),核对路线、当前版本、发送与接手证据 |
37
+ | 接替、故障接管或归档 | [接管与退出](references/handoff.md),按实际退化迹象评估,保留授权、停写、保全和收取依赖核验 |
38
+ | 专项取证、Mock、环境受限、提前独立验证、需求级测试、多方验收或切换发布 | [验证与阶段出口](references/verification.md),按相关章节核对证据和准入 |
@@ -0,0 +1,3 @@
1
+ interface:
2
+ display_name: "AI 协作开发流程"
3
+ short_description: "协调跨阶段与多工作区开发,覆盖专业分工、结果回传、监控核查、验证及交接"
@@ -0,0 +1,55 @@
1
+ # Codex 统筹保护
2
+
3
+ 仅用于用户明确启用的 Codex 统筹任务。使用专用统筹会话,同一会话只登记一个受保护任务。这套配置须由用户或获准配置者建立。角色约定、技能加载、压缩续接登记和安装插件本身不会启用保护。
4
+
5
+ ## 启用
6
+
7
+ 1. **限制业务写入**:在宿主给专用统筹会话选用命名权限配置,仅允许写独立的协调目录。协调目录应位于所有业务工作区之外,且不能覆盖 Codex 配置、插件或派单登记。下例路径须替换为真实绝对路径,保留其他会话原有的默认权限设置。宿主若只能启用整会话只读,就把协调记录写入交给已授权的负责人。宿主不能选择或核实实际权限时,把保护记为未启用。
8
+
9
+ ```toml
10
+ [permissions.workflow-coordinator.filesystem]
11
+ ":root" = "read"
12
+ "/absolute/path/to/separate-coordination-dir" = "write"
13
+ ```
14
+
15
+ 主机已采用命名权限时沿用现有 `default_permissions`。首次配置时需要明确原默认权限;不要把 `workflow-coordinator` 设为全局默认。命名权限与旧 `sandbox_mode` 配置不叠加。支持的 app-server 客户端可用 `thread/start` 的 `permissions: "workflow-coordinator"` 选择权限,并核对实际生效值。没有选择入口时可从宿主界面使用经核实的只读权限。启用期间保持原权限。专用 app-server 会话可以使用 `approvalPolicy: "never"`,防止本地命令请求脱离沙箱;其他入口也不要批准命令绕过只读限制。此配置约束本地文件操作,远程写入工具按宿主及服务授权单独控制。开发会话继续使用各自获准的工作区权限。
16
+
17
+ 2. **信任并核对 Hook**:在 Codex 的 Settings → Hooks 或 `/hooks` 审阅并信任本插件的 `SessionStart` 和 `PreToolUse`。确认当前宿主会运行插件 Hook。原有的压缩续接登记仍按[压缩续接](coordination.md#插件的压缩续接)处理。
18
+ 3. **登记已确认的派单路线**:由用户或获准配置者在 Codex 配置目录下创建 `ai-development-workflow/dispatch/<统筹会话ID>.json`,以宿主确认的会话 ID 命名。目录和文件须在统筹不可写范围内。填入已经核对的目标、身份、回传权限和不依赖统筹或执行者自报的查收触发方式。更换责任方、任务版本或路线时,先更新或撤销登记;编辑登记应一次替换完整文件,避免并发读取半份记录。下面是发给已有会话、只读查收的例子。
19
+
20
+ ```json
21
+ {
22
+ "coordinator": "<统筹会话ID>",
23
+ "task": "WF-42",
24
+ "version": "v2",
25
+ "routes": [
26
+ {
27
+ "threadId": "<执行者会话ID>",
28
+ "role": "开发执行者",
29
+ "reporting": {
30
+ "events": ["completed", "stopped", "blocked"],
31
+ "recipient": "<负责收取的统筹会话ID>",
32
+ "entry": "执行者当前任务终稿,经 read_thread 查收",
33
+ "deliverable": "任务版本、结果、制品、自验证据和未做项",
34
+ "mode": "read-only",
35
+ "authorization": "pending"
36
+ },
37
+ "checkpoint": {
38
+ "owner": "<已约定的触发人>",
39
+ "trigger": "<具体时间或独立事件>",
40
+ "entry": "<已获准且可用的查收入口>"
41
+ }
42
+ }
43
+ ]
44
+ }
45
+ ```
46
+
47
+ 新会话路线用工具调用中的完整 `target` 对象替代 `threadId`。向已有会话派单时,若工具调用传入 `hostId`,路线须登记相同的 `hostId`。不同目标或身份分别登记。确认允许主动回传时,`mode` 写 `active`,`authorization` 写 `approved`,`source` 填可定位的直接用户授权出处;只读查收使用 `pending` 或 `not-enabled`,省略 `source`。路线登记不产生创建、派发、消息或写入授权。
48
+
49
+ ## 派单与检查
50
+
51
+ 在真实任务包正文保留具体职责和回传指令,再增加一段标记为 `workflow-dispatch` 的 JSON 代码块。把登记里的 `task`、`version` 和本路线的 `role`、`reporting`、`checkpoint` 合成一个 JSON 对象。目标仍填写在工具参数里。Hook 检查实际调用的目标和正文。失败按提示补齐,不改走 fork 或 handoff;这些入口在登记期间拒绝。此检查覆盖桌面 MCP 的新建会话和发送消息。因同一入口也能发普通消息,已登记的专用统筹会话通过该入口发出的消息都须匹配一条登记路线。未登记会话直接通过。
52
+
53
+ 双方漏报时,按[独立监督和收取规则](coordination.md#已授权监控的核查与收口)由约定触发人唤起监督者,核对会话与产物。漏报提醒和宿主审批分别按授权执行。
54
+
55
+ 保护应有实际通过和拒绝证据。不要依据「已安装」推定 Hook 运行。Hook 不覆盖其他通道,也不替代沙箱或真实授权。确认结束后由获准配置者移除本会话的派单登记;若已采用压缩续接登记,按原规则撤销。需要后续开发时另用拥有对应权限的执行会话。