@elvis1513/auto-coding-skill 2.0.1 → 2.0.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.
package/README.md CHANGED
@@ -23,9 +23,18 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
23
23
 
24
24
  ## Release Notes
25
25
 
26
+ ### v2.0.2
27
+
28
+ - Added default Codex subagent templates under `.agents/agents`.
29
+ - `autocoding init --ai codex` and `autocoding init --ai all` now install the Codex agent templates automatically.
30
+ - Updated Codex agent defaults to current model names: `gpt-5.5`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`; highest reasoning uses `xhigh`.
31
+ - Added concrete capability routing for MCP servers, installed skills, plugins/apps/connectors, browser tools, GitHub, Figma, security review, and artifact workflows.
32
+ - Changed multi-agent guidance from unconditional delegation to a role model that works either as real subagents or as sequential main-agent phases.
33
+ - Hardened CLI help/argument validation, asset sync checks, and stricter autopipeline config diagnostics.
34
+
26
35
  ### v2.0.1
27
36
 
28
- - Updated the Codex installer target from `.codex/skills` to `.agents/skills`, matching current Codex global and project skill discovery.
37
+ - Updated the Codex installer target to `.agents/skills`, matching current Codex global and project skill discovery.
29
38
 
30
39
  ### v0.3.1
31
40
 
@@ -113,6 +122,8 @@ autocoding init --ai all
113
122
  # or: --ai codex / --ai claude
114
123
  ```
115
124
 
125
+ For Codex installs, the command also creates `.agents/agents/` with the default `explorer`, `fixer`, `reviewer`, `docs_researcher`, and `browser_debugger` subagents.
126
+
116
127
  2. Initialize docs and local scripts:
117
128
 
118
129
  ```bash
@@ -172,14 +183,19 @@ It must be committed to Git. Do not add it to `.gitignore`.
172
183
 
173
184
  5. Tool selection rule during execution:
174
185
 
175
- - Prefer current MCP / skills / plugins / apps first.
176
- - Fall back to shell / manual work only when those capabilities are unavailable or insufficient.
186
+ - Local code, tests, git, and project gates: use shell, repo scripts, and `docs/tools/autopipeline/ap.py`.
187
+ - Current library/framework/API/CLI/cloud docs: use Context7 or the matching installed skill before coding against uncertain behavior.
188
+ - UI verification: use Browser/in-app browser for local pages, Chrome for the user's logged-in Chrome state, Playwright for deterministic automation, and Computer Use only for native or unsupported UI surfaces.
189
+ - GitHub/PR/CI: use GitHub connectors for remote PR, issue, review, and CI state; use local git for local diff, commit, and push.
190
+ - Figma/frontend/design, security review, data/reporting, and document artifacts: use the matching installed plugin or skill before manual recreation.
191
+ - Fall back to shell/manual work only when those capabilities are unavailable, insufficient, unreliable, or slower than direct execution.
177
192
 
178
193
  6. Collaboration rule during execution:
179
194
 
180
- - Prefer multi-agent mode.
181
- - Split research, design, implementation, verification, and documentation into parallel subtasks whenever the boundaries are clear.
182
- - Keep one main agent responsible for integration and final gates.
195
+ - Use `.agents/agents` as the default role model: `explorer`, `docs_researcher`, `browser_debugger`, `fixer`, `reviewer`.
196
+ - If the client permits subagents, split independent work across those roles.
197
+ - If the client cannot run subagents, execute the same role sequence in the main agent.
198
+ - Keep one main agent responsible for scope, integration, quality gates, docs closure, git state, and final delivery.
183
199
 
184
200
  ## AGENTS.md Constraint Example
185
201
 
@@ -193,17 +209,23 @@ It must be committed to Git. Do not add it to `.gitignore`.
193
209
  - If required docs are missing, create/update docs first, then code.
194
210
 
195
211
  ## Tooling Policy
196
- - Prefer currently available MCP servers, installed skills, plugins, and app connectors before shell/manual work.
212
+ - Route by source of truth:
213
+ 1) local code/tests/git -> shell + repo scripts
214
+ 2) current docs/API behavior -> Context7 or matching docs skill
215
+ 3) UI/browser proof -> Browser, Chrome, Playwright, or Computer Use by scenario
216
+ 4) PR/Issue/CI -> GitHub connector
217
+ 5) design/frontend/security/artifacts -> matching installed skill/plugin
197
218
  - When a connector or MCP can read or write the authoritative source directly, use it instead of retyping or duplicating state.
198
219
 
199
220
  ## Multi-Agent Policy
200
- - Default to multi-agent execution.
201
- - Before substantial work, split into parallel subtasks whenever boundaries are clear:
202
- 1) design / research
203
- 2) backend implementation
204
- 3) frontend implementation
205
- 4) validation / documentation / review
206
- - Keep one main agent responsible for task framing, integration, quality gates, and final delivery.
221
+ - Use `.agents/agents` roles:
222
+ 1) explorer
223
+ 2) docs_researcher
224
+ 3) browser_debugger
225
+ 4) fixer
226
+ 5) reviewer
227
+ - Spawn subagents only when the client supports and allows it; otherwise run the same role phases in the main agent.
228
+ - Keep one main agent responsible for task framing, integration, quality gates, docs closure, git state, and final delivery.
207
229
 
208
230
  ## Default Gate Policy
209
231
  - Default local gate is lightweight only.
@@ -0,0 +1,30 @@
1
+ name = "browser_debugger"
2
+ description = "浏览器调试代理,用于复现 UI 问题、收集控制台和网络证据。"
3
+ model = "gpt-5.5"
4
+ model_reasoning_effort = "xhigh"
5
+ sandbox_mode = "workspace-write"
6
+
7
+ developer_instructions = """
8
+ 你负责复现问题和采集证据,不优先修改业务代码。
9
+
10
+ 工作要求:
11
+ 1. 先复现,再下结论;无法复现时明确说明阻塞点。
12
+ 2. 按场景选择工具:
13
+ - localhost、file、应用内页面:优先 Browser / in-app browser;需要脚本控制时配合 node_repl。
14
+ - 需要复用用户 Chrome 登录态、扩展或已有标签页:使用 Chrome 控制能力;需要脚本控制时配合 node_repl。
15
+ - 需要稳定自动化复现、截图或 smoke test:使用 Playwright。
16
+ - 原生桌面 App 或没有专用连接器的 UI:才使用 Computer Use。
17
+ 3. 重点关注:
18
+ - 操作路径
19
+ - 实际表现
20
+ - 控制台报错
21
+ - 网络请求
22
+ - 状态变化
23
+ 4. 输出必须包含:
24
+ - 复现步骤
25
+ - 实际结果
26
+ - 预期结果
27
+ - 证据
28
+ - 根因候选
29
+ 5. 如果需要代码修复,只给出修复建议,交给 fixer 或主代理实施。
30
+ """
@@ -0,0 +1,21 @@
1
+ name = "docs_researcher"
2
+ description = "文档/API核对代理,负责确认框架、库、参数和版本行为。"
3
+ model = "gpt-5.4-mini"
4
+ model_reasoning_effort = "medium"
5
+ sandbox_mode = "read-only"
6
+
7
+ developer_instructions = """
8
+ 你只负责核对文档和接口行为,不修改代码。
9
+
10
+ 工作要求:
11
+ 1. 涉及当前库、框架、SDK、CLI、云服务或 API 行为时,优先使用 Context7 等文档 MCP 或对应已安装 skill。
12
+ 2. 优先使用官方文档、项目仓库、发行说明或连接器返回的权威信息;不要用博客或二手资料替代官方来源。
13
+ 3. 重点核对:API签名、参数含义、版本兼容性、废弃项、默认行为、迁移要求。
14
+ 4. 输出要简洁、可引用、可落地。
15
+ 5. 优先返回:
16
+ - 结论
17
+ - 证据点
18
+ - 对当前项目的影响
19
+ - 建议给 explorer / fixer / reviewer 的下一步
20
+ 6. 如果文档不足以确认,明确标注“不确定”,不要猜。
21
+ """
@@ -0,0 +1,27 @@
1
+ name = "explorer"
2
+ description = "只读代码探索代理,用于定位调用链、关键文件和根因候选。"
3
+ model = "gpt-5.4-mini"
4
+ model_reasoning_effort = "medium"
5
+ sandbox_mode = "read-only"
6
+
7
+ developer_instructions = """
8
+ 你只负责探索,不负责修改。
9
+
10
+ 工作要求:
11
+ 1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
12
+ 2. 先读项目已有文档、配置、路由、任务记录,再做结论。
13
+ 3. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
14
+ 4. 输出内容必须尽量具体到:
15
+ - 文件路径
16
+ - 函数名 / 方法名
17
+ - 关键结构体 / 类 / 接口
18
+ - 关键配置项
19
+ 5. 不要泛泛而谈,不要直接给大段修复方案。
20
+ 6. 输出格式:
21
+ - 问题入口
22
+ - 调用链
23
+ - 关键文件
24
+ - 根因候选
25
+ - 建议交给哪个代理继续处理
26
+ 7. 优先快速精准搜索,避免全仓库无差别扫描。
27
+ """
@@ -0,0 +1,25 @@
1
+ name = "fixer"
2
+ description = "实现型修复代理,适合小范围、快速、定点修改。"
3
+ model = "gpt-5.3-codex-spark"
4
+ model_reasoning_effort = "medium"
5
+ sandbox_mode = "workspace-write"
6
+
7
+ developer_instructions = """
8
+ 你负责小而准的实现修改。
9
+
10
+ 工作要求:
11
+ 1. 只在问题已经相对明确后再动手。
12
+ 2. 坚持“最小可辩护修改”原则。
13
+ 3. 除非明确要求,否则不要重构、不做大面积改名、不改无关文件。
14
+ 4. 先跟随项目现有模式、helper、组件、脚本和文档约束,不新造不必要抽象。
15
+ 5. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
16
+ 6. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
17
+ 7. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
18
+ 8. 修改后运行聚焦门禁:优先项目 light gate,其次相关测试、typecheck、lint、git diff --check。
19
+ 9. 修改后输出:
20
+ - 修改文件
21
+ - 修改点
22
+ - 修改原因
23
+ - 验证方法
24
+ 10. 如发现问题超出小修范围,要立即停止并上报,不要自行扩大战场。
25
+ """
@@ -0,0 +1,22 @@
1
+ name = "reviewer"
2
+ description = "代码审查代理,聚焦正确性、安全性、回归风险和测试缺失。"
3
+ model = "gpt-5.5"
4
+ model_reasoning_effort = "xhigh"
5
+ sandbox_mode = "read-only"
6
+
7
+ developer_instructions = """
8
+ 你是资深 reviewer,不负责写新功能,主要负责发现问题。
9
+
10
+ 工作要求:
11
+ 1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
12
+ 2. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
13
+ 3. 以 git diff、相关测试、接口契约、真实运行证据为基础,不凭风格偏好输出问题。
14
+ 4. 优先输出真实问题,不要输出样式洁癖式意见。
15
+ 5. 每条问题尽量包含:
16
+ - 问题点
17
+ - 影响范围
18
+ - 复现条件
19
+ - 建议修法
20
+ 6. 发现测试不足时,指出应补哪些测试或验证路径。
21
+ 7. 结论要按严重程度排序:高 / 中 / 低。
22
+ """
@@ -9,9 +9,9 @@ This skill is for Go backend + frontend monorepo projects that rely on Jenkins t
9
9
 
10
10
  `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Unused environment keys should be removed from the template instead of being left as placeholders.
11
11
 
12
- Prefer already available MCP servers, installed skills, plugins, and app connectors over ad-hoc manual work whenever they can complete the task reliably.
12
+ At task start, inventory the current client capabilities before choosing a route: installed MCP servers, local skills, plugins/apps/connectors, browser/control tools, and repo scripts. Prefer those capabilities when they provide current, authoritative, or directly inspectable state.
13
13
 
14
- Default to multi-agent execution when the client supports it. Break work into independent design, research, implementation, validation, and documentation subtasks so Claude/Codex can run them in parallel whenever that reduces cycle time without weakening control of the main task.
14
+ Use multi-agent roles deliberately. When the client exposes subagent tools and the active runtime policy permits delegation, split independent research, exploration, implementation, browser verification, and review work. When delegation is unavailable or restricted, execute the same role sequence in the main agent instead of pretending parallelism is possible.
15
15
 
16
16
  ## Supported clients
17
17
 
@@ -20,22 +20,30 @@ Default to multi-agent execution when the client supports it. Break work into in
20
20
 
21
21
  ## Tooling policy
22
22
 
23
- Use available platform capabilities first:
23
+ Use the most direct authoritative capability for each task:
24
24
 
25
- 1) Prefer installed MCP servers for design context, documentation lookup, browser automation, issue/docs systems, and deployment/runtime inspection.
26
- 2) Prefer already installed local skills when the task matches them.
27
- 3) Prefer supported plugins/apps/connectors when they provide authoritative project context or can write back records.
28
- 4) Fall back to manual shell/code workflows only when the above are unavailable, insufficient, or slower than direct execution.
25
+ 1) Local repo work: use shell, repo scripts, and `docs/tools/autopipeline/ap.py` for edits, tests, gates, git, and project-local verification.
26
+ 2) Current library/framework/API/CLI/cloud behavior: use a documentation MCP such as Context7 or the matching installed skill before coding migrations, config changes, or API integrations.
27
+ 3) Browser and UI verification: use Browser/in-app browser for localhost and app-owned sessions; use Chrome when the user's existing logged-in Chrome state is required; use Playwright for deterministic browser automation or terminal-first smoke tests; use Computer Use only for native apps or UI surfaces without a purpose-built connector.
28
+ 4) Product/design sources: use Figma, Build Web Apps, Product Design, or frontend skills when the task depends on design context, visual implementation, screenshots, or generated UI.
29
+ 5) GitHub/PR/CI state: use GitHub connectors for PRs, issues, review comments, and Actions/CI metadata; use local git for local diff, staging, commits, and pushes.
30
+ 6) Security-sensitive changes: use reviewer/security skills or security scan capabilities for auth, permission, payment, file transfer, deployment, dependency, and data-boundary changes.
31
+ 7) Analytical or document artifacts: use Data Analytics, documents, PDFs, spreadsheets, presentations, or LaTeX skills/plugins for those artifact types, including render/validation steps.
32
+ 8) OpenAI/API keys and other secrets: use secure platform/key setup capabilities when available; do not paste, invent, or persist secrets outside the configured secure flow.
33
+ 9) Screen/recent-work context: use Chronicle or screenshot skills when the user references visible UI state or recent manual actions.
34
+ 10) Fall back to manual shell/code workflows only when the above are unavailable, insufficient, or slower than direct execution.
29
35
 
30
36
  ## Collaboration policy
31
37
 
32
- Prefer multi-agent mode across the workflow:
38
+ Use `.agents/agents` role templates as the default collaboration model for Codex installs:
33
39
 
34
- 1) Split independent subtasks early when they can run in parallel.
35
- 2) Keep the main agent on the critical path: task framing, design decisions, integration, Jenkins / target-env verification, and final closure.
36
- 3) Use side agents for bounded work such as research, code slices, documentation updates, targeted regression checks, or review passes.
37
- 4) Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
38
- 5) A practical default split for Go fullstack work is: design/research, backend implementation, frontend implementation, validation/documentation.
40
+ 1) `explorer`: read-only repo discovery, call-chain tracing, config mapping, and root-cause candidates.
41
+ 2) `docs_researcher`: current external documentation, API signatures, version behavior, and compatibility checks.
42
+ 3) `browser_debugger`: browser reproduction, console/network evidence, screenshots, and UI behavior verification.
43
+ 4) `fixer`: bounded implementation after the cause and acceptance path are clear.
44
+ 5) `reviewer`: read-only correctness, security, regression-risk, and missing-test review.
45
+
46
+ The main agent always owns task framing, design decisions, integration, Jenkins / target-env verification, closure records, git state, and final delivery. Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
39
47
 
40
48
  ## Entry
41
49
 
@@ -46,6 +54,8 @@ autocoding init --ai codex
46
54
  # or claude / all
47
55
  ```
48
56
 
57
+ For Codex targets, this also installs the default subagent templates into `.agents/agents/`.
58
+
49
59
  2) Initialize docs/tooling:
50
60
 
51
61
  ```bash
@@ -122,6 +122,7 @@ docs:
122
122
  - `target_env.backend_root_password`
123
123
  - `target_env.health_base_url`
124
124
  - `target_env.health_path`
125
+ - `jenkins.base_url`
125
126
  - `jenkins.ui_username`
126
127
  - `jenkins.ui_password`
127
128
  - `jenkins.api_user`
@@ -161,28 +162,75 @@ docs:
161
162
 
162
163
  ## 1.5 工具使用策略(Claude / Codex 专属)
163
164
 
164
- 优先使用当前环境已安装、已授权、已可访问的工具能力:
165
+ 任务开始时先做能力盘点:当前可用的 MCP servers、已安装 skills、plugins / apps / connectors、浏览器控制能力、repo 脚本。能直接读取权威状态、当前文档或真实 UI 的能力,优先于手写推测。
165
166
 
166
- 1) MCP servers
167
- 2) 已安装 skills
168
- 3) plugins / apps / connectors
169
- 4) shell / 手工实现
167
+ 默认路由:
170
168
 
171
- 规则:
172
- - 做设计、查资料、查文档、查 Jenkins、查页面、写回外部系统时,优先调用现成能力。
173
- - 工具不可用、权限不足、结果不可靠时,才回退到 shell 或手工流程。
169
+ 1) 本地代码 / 测试 / Git / 门禁
170
+ 优先使用 shell、项目脚本、`docs/tools/autopipeline/ap.py`。本地 diff、提交、推送以 Git 实际状态为准。
171
+
172
+ 2) 当前库 / 框架 / SDK / API / CLI / 云服务文档
173
+ 优先使用 Context7 等文档 MCP 或对应已安装 skill,先确认版本、参数、默认行为、废弃项,再改代码。
174
+
175
+ 3) 浏览器与 UI 验证
176
+ - localhost、file、应用内页面:优先 Browser / in-app browser;需要脚本控制时配合 node_repl。
177
+ - 必须复用用户 Chrome 登录态、扩展或已有标签页:使用 Chrome 控制能力;需要脚本控制时配合 node_repl。
178
+ - 需要稳定自动化复现、截图或 smoke test:使用 Playwright。
179
+ - 原生桌面 App 或没有专用连接器的 UI:才使用 Computer Use。
180
+
181
+ 4) GitHub / PR / Issue / CI
182
+ 远端 PR、Issue、review comments、Actions/CI 状态优先用 GitHub connector;本地 diff、commit、push 仍用本地 Git。
183
+
184
+ 5) Figma / 视觉设计 / 前端体验
185
+ 设计上下文先用 Figma;视觉强相关页面优先使用 frontend / build-web / product-design 类 skill,并用浏览器截图或真实页面验证收口。
186
+
187
+ 6) 安全敏感变更
188
+ 鉴权、权限、支付、文件上传下载、部署、依赖、数据边界变更,默认安排 reviewer 或安全扫描能力做只读复核。
189
+
190
+ 7) 报告与文件类产物
191
+ Dashboard / 数据报告使用 Data Analytics;Word/PDF/表格/PPT/LaTeX 使用对应文档类 skill 或插件,并做渲染/校验。
192
+
193
+ 8) OpenAI/API key/密钥类操作
194
+ 使用平台提供的安全 key 创建或写入流程;不要在普通文档、日志或提交中手写、复制、持久化密钥。
195
+
196
+ 9) 屏幕与近期操作上下文
197
+ 当任务依赖用户当前屏幕、浏览器登录状态或最近手工操作时,优先使用 Chronicle / screenshot 类能力获取真实上下文。
198
+
199
+ 回退规则:
200
+ - 工具不可用、权限不足、结果不可靠或比直接执行更慢时,才回退到 shell 或手工流程。
174
201
  - 不重复手写工具已经能直接读取或写回的权威数据。
202
+ - 外部信息必须优先来自官方文档、项目连接器或真实运行状态。
175
203
 
176
204
  ---
177
205
 
178
206
  ## 1.6 多 Agent 协作策略(Claude / Codex 专属)
179
207
 
180
- 整个流程尽可能使用多 agent 并行推进。
208
+ 默认使用 `.agents/agents` 中的角色模型来拆解任务;只有在当前客户端明确提供并允许子代理/多代理工具时,才实际并行派发。若运行时策略不允许子代理,则由主 agent 按同一角色顺序串行完成,不假装并行。
181
209
 
182
- 规则:
183
- - 主 agent 负责任务定义、方案裁决、代码集成、轻量门禁、Jenkins/目标环境闭环、最终交付。
184
- - 子 agent 优先拆为:设计/调研、后端实现、前端实现、验证/文档。
185
- - 任务边界不清或需要强一致裁决时,由主 agent 保持控制,不机械拆分。
210
+ 默认角色:
211
+
212
+ 1) `explorer`
213
+ 只读探索:定位入口、调用链、关键文件、配置项、根因候选。
214
+
215
+ 2) `docs_researcher`
216
+ 文档/API 核对:确认当前版本行为、参数、兼容性、废弃项和官方建议。
217
+
218
+ 3) `browser_debugger`
219
+ 浏览器验证:复现路径、控制台、网络请求、截图、实际/预期行为。
220
+
221
+ 4) `fixer`
222
+ 定点实现:在问题和验收路径清晰后做最小可辩护修改,并运行聚焦校验。
223
+
224
+ 5) `reviewer`
225
+ 只读复核:正确性、安全性、回归风险、边界条件和测试缺口。
226
+
227
+ 主 agent 始终负责:
228
+ - 任务定义、范围裁决、方案取舍
229
+ - 代码集成和冲突处理
230
+ - 轻量门禁、Jenkins/目标环境闭环
231
+ - 文档闭环、Git 状态、最终交付
232
+
233
+ 任务边界不清、需要强一致裁决或涉及架构取舍时,由主 agent 保持控制,不机械拆分。
186
234
 
187
235
  ---
188
236
 
@@ -217,16 +265,16 @@ docs:
217
265
 
218
266
  ### 2.3 任务步骤
219
267
 
220
- 1. 需求确认
268
+ 1. 需求确认
221
269
  明确任务范围、影响服务、是否涉及 API/数据库/部署/Jenkins/前端页面。
222
270
 
223
- 2. 最小设计记录
271
+ 2. 最小设计记录
224
272
  普通小改动只更新 `taskbook` 或设计文档中的最小必要段落;跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
225
273
 
226
- 3. 开发实现
274
+ 3. 开发实现
227
275
  只修改本次任务必要文件,不做无关重构。
228
276
 
229
- 4. 本地轻量校验
277
+ 4. 本地轻量校验
230
278
  默认只跑最少必要检查:
231
279
  - 优先执行 `commands.light_gate`
232
280
  - 若未配置,则执行 `quick_test` / `test` / `build` 中最先配置的一项
@@ -234,22 +282,22 @@ docs:
234
282
  - API 文档检查
235
283
  - Jenkins 配置检查
236
284
 
237
- 5. 提交推送
285
+ 5. 提交推送
238
286
  `dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push 后继续验证 Jenkins 和目标环境。
239
287
 
240
- 6. Jenkins 验证
288
+ 6. Jenkins 验证
241
289
  仅 `verify` 模式默认执行。查看 Jenkins 构建、镜像、部署结果;失败则根据 Jenkins 日志修复,再次提交推送。
242
290
 
243
- 7. 目标环境验证
291
+ 7. 目标环境验证
244
292
  仅 `verify` 模式默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
245
293
 
246
- 8. 回归与证据记录
294
+ 8. 回归与证据记录
247
295
  只有真实执行过 Jenkins / 目标环境验证,或显式要求本地运行验证时,才允许把 `regression-matrix.md` 标为 `PASS`。
248
296
 
249
- 9. 闭环记录
297
+ 9. 闭环记录
250
298
  每个任务必须留下轻量闭环记录。`dev` 模式用 `DEV-CLOSED`,`verify` 模式用 `PASS` / `FAIL` / `PARTIAL`。
251
299
 
252
- 10. 配置入库
300
+ 10. 配置入库
253
301
  `docs/ENGINEERING.md` 中保留下来的环境信息、前端/后端账号、Jenkins 账号与密码必须 100% 填写、正确填写,并提交 Git 作为项目权威配置持续维护。
254
302
 
255
303
  ---
@@ -1,5 +1,5 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
- Prefer already available MCP servers, installed skills, plugins, and app connectors during design, research, verification, and documentation workflows.
3
- Prefer multi-agent mode whenever the task can be split into independent parallel subtasks without weakening integration control.
2
+ Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
3
+ Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
4
4
  Default to the lightweight local gate first, then use Jenkins build verification and real target-environment verification as the primary completion gate.
5
5
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
@@ -1,5 +1,5 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
- Prefer already available MCP servers, installed skills, plugins, and app connectors during design, research, verification, and documentation workflows.
3
- Prefer multi-agent mode whenever the task can be split into independent parallel subtasks without weakening integration control.
2
+ Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
3
+ Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
4
4
  Default to the lightweight local gate first, then use Jenkins build verification and real target-environment verification as the primary completion gate.
5
5
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
@@ -193,12 +193,12 @@ def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: b
193
193
  except Exception as retry_exc:
194
194
  raise APError(f"Jenkins API request failed after crumb retry: {url}\n{retry_exc}") from retry_exc
195
195
  else:
196
- raise APError(
197
- f"Jenkins API request failed: {url}\n"
198
- f"HTTP 403\n{body or '(empty response body)'}\n"
199
- "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
196
+ raise APError(
197
+ f"Jenkins API request failed: {url}\n"
198
+ f"HTTP 403\n{body or '(empty response body)'}\n"
199
+ "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
200
200
  "Fill jenkins.base_url in docs/ENGINEERING.md if needed."
201
- ) from exc
201
+ ) from exc
202
202
  else:
203
203
  raise APError(
204
204
  f"Jenkins API request failed: {url}\n"
@@ -556,7 +556,14 @@ def _text(value: object) -> str:
556
556
 
557
557
 
558
558
  def _is_placeholder(value: object) -> bool:
559
- return _text(value).upper() in _INVALID_PLACEHOLDERS
559
+ raw = _text(value)
560
+ upper = raw.upper()
561
+ return (
562
+ upper in _INVALID_PLACEHOLDERS
563
+ or (raw.startswith("<") and raw.endswith(">"))
564
+ or upper.startswith("REPLACE_")
565
+ or upper.startswith("YOUR_")
566
+ )
560
567
 
561
568
 
562
569
  def _is_explicit_fill(value: object) -> bool:
@@ -564,6 +571,8 @@ def _is_explicit_fill(value: object) -> bool:
564
571
 
565
572
 
566
573
  def _validate_url_field(errors: List[str], field: str, value: object) -> None:
574
+ if not _is_explicit_fill(value):
575
+ return
567
576
  raw = _text(value)
568
577
  parsed = urllib.parse.urlparse(raw)
569
578
  if parsed.scheme not in {"http", "https"} or not parsed.netloc:
@@ -571,6 +580,8 @@ def _validate_url_field(errors: List[str], field: str, value: object) -> None:
571
580
 
572
581
 
573
582
  def _validate_path_field(errors: List[str], field: str, value: object) -> None:
583
+ if not _is_explicit_fill(value):
584
+ return
574
585
  raw = _text(value)
575
586
  if not raw.startswith("/"):
576
587
  errors.append(f"{field} must start with '/'")
@@ -603,7 +614,9 @@ def cmd_run(args: argparse.Namespace) -> None:
603
614
  "Edit docs/ENGINEERING.md frontmatter. "
604
615
  f"Available: {', '.join(commands.keys()) or '(none)'}"
605
616
  )
606
- cmd = str(commands[name])
617
+ cmd = str(commands.get(name) or "").strip()
618
+ if not cmd:
619
+ raise APError(f"Command is blank: commands.{name}. Edit docs/ENGINEERING.md frontmatter.")
607
620
  print(f"[run] {name}: {cmd}")
608
621
  run_shell(cmd, cwd=repo)
609
622
  print(f"[run] OK: {name}")
@@ -792,7 +805,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
792
805
  runtime_cfg = (cfg.get("runtime") or {})
793
806
 
794
807
  missing: List[str] = []
795
- warnings: List[str] = []
808
+ validation_errors: List[str] = []
796
809
 
797
810
  mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
798
811
  if mode not in {"dev", "verify"}:
@@ -837,28 +850,27 @@ def cmd_doctor(args: argparse.Namespace) -> None:
837
850
  }
838
851
  for key, path in repo_docs.items():
839
852
  if not path.exists():
840
- warnings.append(f"{key} missing on disk: {path}")
853
+ validation_errors.append(f"{key} missing on disk: {path}")
841
854
 
842
- _validate_url_field(warnings, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
843
- _validate_url_field(warnings, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
844
- _validate_url_field(warnings, "target_env.health_base_url", target_cfg.get("health_base_url"))
845
- _validate_path_field(warnings, "target_env.health_path", target_cfg.get("health_path"))
846
- _validate_url_field(warnings, "jenkins.base_url", jenkins_cfg.get("base_url"))
847
- _validate_url_field(warnings, "jenkins.job_url", jenkins_cfg.get("job_url"))
855
+ _validate_url_field(validation_errors, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
856
+ _validate_url_field(validation_errors, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
857
+ _validate_url_field(validation_errors, "target_env.health_base_url", target_cfg.get("health_base_url"))
858
+ _validate_path_field(validation_errors, "target_env.health_path", target_cfg.get("health_path"))
859
+ _validate_url_field(validation_errors, "jenkins.base_url", jenkins_cfg.get("base_url"))
860
+ _validate_url_field(validation_errors, "jenkins.job_url", jenkins_cfg.get("job_url"))
848
861
 
849
862
  runtime_enabled = any(str(runtime_cfg.get(key) or "").strip() for key in ["docker_compose_file", "docker_service", "health_base_url", "health_path"])
850
863
  if runtime_enabled and not str(runtime_cfg.get("docker_compose_file") or "").strip():
851
- warnings.append("runtime config is partially enabled but runtime.docker_compose_file is missing")
864
+ validation_errors.append("runtime config is partially enabled but runtime.docker_compose_file is missing")
852
865
 
853
866
  try:
854
867
  timeout_s = int(jenkins_cfg.get("deploy_timeout_sec") or 0)
855
868
  if timeout_s <= 0:
856
- warnings.append("jenkins.deploy_timeout_sec must be a positive integer")
869
+ validation_errors.append("jenkins.deploy_timeout_sec must be a positive integer")
857
870
  except Exception:
858
- warnings.append("jenkins.deploy_timeout_sec must be a positive integer")
871
+ validation_errors.append("jenkins.deploy_timeout_sec must be a positive integer")
859
872
 
860
- if warnings:
861
- missing.extend([f"invalid {item}" for item in warnings])
873
+ missing.extend(validation_errors)
862
874
 
863
875
  if missing:
864
876
  raise APError("Doctor found blocking config issues:\n- " + "\n- ".join(missing))
package/cli/src/index.js CHANGED
@@ -9,17 +9,33 @@ function die(msg){
9
9
  process.exit(1);
10
10
  }
11
11
 
12
+ function takeValue(rest, index, flag){
13
+ const value = rest[index + 1];
14
+ if (!value || value.startsWith("--")) die(`${flag} requires a value`);
15
+ return value;
16
+ }
17
+
12
18
  function parseArgs(argv){
13
19
  const args = { cmd: null, ai: null, mode: "project", dest: null, force: false };
14
20
  const [,, cmd, ...rest] = argv;
15
- args.cmd = cmd ?? "help";
21
+ args.cmd = (!cmd || cmd === "-h" || cmd === "--help") ? "help" : cmd;
16
22
  for (let i = 0; i < rest.length; i++) {
17
23
  const a = rest[i];
18
- if (a === "--ai") args.ai = rest[++i];
19
- else if (a === "--mode") args.mode = rest[++i];
20
- else if (a === "--dest") args.dest = rest[++i];
24
+ if (a === "--ai") {
25
+ args.ai = takeValue(rest, i, a);
26
+ i += 1;
27
+ }
28
+ else if (a === "--mode") {
29
+ args.mode = takeValue(rest, i, a);
30
+ i += 1;
31
+ }
32
+ else if (a === "--dest") {
33
+ args.dest = takeValue(rest, i, a);
34
+ i += 1;
35
+ }
21
36
  else if (a === "--force") args.force = true;
22
37
  else if (a === "-h" || a === "--help") args.cmd = "help";
38
+ else die(`unknown argument: ${a}`);
23
39
  }
24
40
  return args;
25
41
  }
@@ -62,6 +78,18 @@ function resolveTargetDir(ai, mode, destOverride){
62
78
  die(`unknown ai: ${ai}`);
63
79
  }
64
80
 
81
+ function resolveAgentsDir(mode, destOverride, multiTarget){
82
+ if (destOverride) {
83
+ return multiTarget
84
+ ? path.join(destOverride, "agents")
85
+ : path.join(destOverride, ".agents", "agents");
86
+ }
87
+ if (mode !== "project" && mode !== "global") die(`--mode must be 'project' or 'global'`);
88
+ return mode === "project"
89
+ ? path.join(projectRoot(), ".agents", "agents")
90
+ : path.join(os.homedir(), ".agents", "agents");
91
+ }
92
+
65
93
  function main(){
66
94
  const args = parseArgs(process.argv);
67
95
 
@@ -89,7 +117,9 @@ Examples:
89
117
 
90
118
  const here = path.dirname(fileURLToPath(import.meta.url));
91
119
  const assetSkill = path.resolve(here, "..", "assets", "skill");
120
+ const assetAgents = path.resolve(here, "..", "assets", "agents");
92
121
  if (!exists(assetSkill)) die(`missing assets at ${assetSkill}`);
122
+ if (!exists(assetAgents)) die(`missing assets at ${assetAgents}`);
93
123
 
94
124
  for (const t of targets) {
95
125
  const dstOverride = args.dest
@@ -102,6 +132,16 @@ Examples:
102
132
  }
103
133
  copyDir(assetSkill, dst);
104
134
  console.log(`[autocoding] installed skill to: ${dst}`);
135
+
136
+ if (t === "codex") {
137
+ const agentsDst = resolveAgentsDir(args.mode, args.dest, targets.length > 1);
138
+ if (exists(agentsDst)) {
139
+ if (!args.force) die(`target exists: ${agentsDst}\nRe-run with --force to overwrite.`);
140
+ rmrf(agentsDst);
141
+ }
142
+ copyDir(assetAgents, agentsDst);
143
+ console.log(`[autocoding] installed Codex agents to: ${agentsDst}`);
144
+ }
105
145
  }
106
146
 
107
147
  console.log("[autocoding] done.");
@@ -5,7 +5,11 @@ import { fileURLToPath } from "node:url";
5
5
  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
6
6
  const srcSkill = path.join(repoRoot, "src", "auto-coding-skill");
7
7
  const dstSkill = path.join(repoRoot, "cli", "assets", "skill");
8
+ const srcAgents = path.join(repoRoot, "src", "agents");
9
+ const dstAgents = path.join(repoRoot, "cli", "assets", "agents");
10
+ const checkOnly = process.argv.includes("--check");
8
11
 
12
+ function exists(p){ try { fs.accessSync(p); return true; } catch { return false; } }
9
13
  function rmrf(p){ fs.rmSync(p, { recursive:true, force:true }); }
10
14
  function shouldSkip(name){
11
15
  return name === "__pycache__" || name === ".DS_Store" || name.endsWith(".pyc");
@@ -21,6 +25,58 @@ function copyDir(src, dst){
21
25
  }
22
26
  }
23
27
 
28
+ function listFiles(root, base = root){
29
+ if (!exists(root)) return [];
30
+ const out = [];
31
+ for (const ent of fs.readdirSync(root, { withFileTypes:true })) {
32
+ if (shouldSkip(ent.name)) continue;
33
+ const p = path.join(root, ent.name);
34
+ if (ent.isDirectory()) out.push(...listFiles(p, base));
35
+ else out.push(path.relative(base, p));
36
+ }
37
+ return out.sort();
38
+ }
39
+
40
+ function compareDirs(src, dst, label){
41
+ const diffs = [];
42
+ const srcFiles = listFiles(src);
43
+ const dstFiles = listFiles(dst);
44
+ const srcSet = new Set(srcFiles);
45
+ const dstSet = new Set(dstFiles);
46
+
47
+ for (const rel of srcFiles) {
48
+ if (!dstSet.has(rel)) {
49
+ diffs.push(`${label}: missing asset ${rel}`);
50
+ continue;
51
+ }
52
+ const srcBuf = fs.readFileSync(path.join(src, rel));
53
+ const dstBuf = fs.readFileSync(path.join(dst, rel));
54
+ if (!srcBuf.equals(dstBuf)) diffs.push(`${label}: stale asset ${rel}`);
55
+ }
56
+ for (const rel of dstFiles) {
57
+ if (!srcSet.has(rel)) diffs.push(`${label}: extra asset ${rel}`);
58
+ }
59
+ return diffs;
60
+ }
61
+
62
+ if (checkOnly) {
63
+ const diffs = [
64
+ ...compareDirs(srcSkill, dstSkill, "skill"),
65
+ ...compareDirs(srcAgents, dstAgents, "agents"),
66
+ ];
67
+ if (diffs.length > 0) {
68
+ console.error("[sync-assets] assets are out of sync:");
69
+ for (const diff of diffs) console.error(`- ${diff}`);
70
+ console.error("[sync-assets] run: npm run sync-assets");
71
+ process.exit(1);
72
+ }
73
+ console.log("[sync-assets] OK: cli assets match src");
74
+ process.exit(0);
75
+ }
76
+
24
77
  rmrf(dstSkill);
25
78
  copyDir(srcSkill, dstSkill);
79
+ rmrf(dstAgents);
80
+ copyDir(srcAgents, dstAgents);
26
81
  console.log("[sync-assets] updated cli/assets/skill from src/auto-coding-skill");
82
+ console.log("[sync-assets] updated cli/assets/agents from src/agents");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvis1513/auto-coding-skill",
3
- "version": "2.0.1",
3
+ "version": "2.0.2",
4
4
  "description": "CLI installer for auto-coding-skill (Claude Code + Codex CLI) with Go fullstack + Jenkins workflow support.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -9,11 +9,13 @@
9
9
  "files": [
10
10
  "cli/src",
11
11
  "cli/assets/skill",
12
+ "cli/assets/agents",
12
13
  "README.md",
13
14
  "LICENSE"
14
15
  ],
15
16
  "scripts": {
16
- "test": "node -c cli/src/index.js && python3 -c \"import ast, pathlib; files = ['src/auto-coding-skill/scripts/ap.py', 'src/auto-coding-skill/scripts/core.py', 'src/auto-coding-skill/scripts/http_checks.py', 'cli/assets/skill/scripts/ap.py', 'cli/assets/skill/scripts/core.py', 'cli/assets/skill/scripts/http_checks.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-grammar-ok')\" && python3 -m py_compile src/auto-coding-skill/scripts/ap.py src/auto-coding-skill/scripts/core.py src/auto-coding-skill/scripts/http_checks.py cli/assets/skill/scripts/ap.py cli/assets/skill/scripts/core.py cli/assets/skill/scripts/http_checks.py && find src cli -type d -name '__pycache__' -prune -exec rm -rf {} +",
17
+ "test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && python3 -c \"import ast, pathlib; files = ['src/auto-coding-skill/scripts/ap.py', 'src/auto-coding-skill/scripts/core.py', 'src/auto-coding-skill/scripts/http_checks.py', 'cli/assets/skill/scripts/ap.py', 'cli/assets/skill/scripts/core.py', 'cli/assets/skill/scripts/http_checks.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-grammar-ok')\" && python3 -m py_compile src/auto-coding-skill/scripts/ap.py src/auto-coding-skill/scripts/core.py src/auto-coding-skill/scripts/http_checks.py cli/assets/skill/scripts/ap.py cli/assets/skill/scripts/core.py cli/assets/skill/scripts/http_checks.py && python3 -c \"import pathlib, tomllib; files = sorted(pathlib.Path('src/agents').glob('*.toml')) + sorted(pathlib.Path('cli/assets/agents').glob('*.toml')); [tomllib.loads(path.read_text(encoding='utf-8')) for path in files]; print('agent-toml-ok')\" && npm run check:assets && find src cli -type d -name '__pycache__' -prune -exec rm -rf {} +",
18
+ "check:assets": "node cli/src/sync-assets.js --check",
17
19
  "sync-assets": "node cli/src/sync-assets.js",
18
20
  "release:check": "npm run sync-assets && npm run test && npm pack --dry-run"
19
21
  },